@smartergpt/lexrunner 1.0.0

package/dist/cli.d.cts

@@ -0,0 +1,2709 @@
+#!/usr/bin/env node
+import { z } from 'zod';
+import { Octokit } from '@octokit/rest';
+
+/**
+ * Gate execution result
+ */
+declare const GateResult: z.ZodObject<{
+    gate: z.ZodString;
+    status: z.ZodEnum<{
+        pass: "pass";
+        fail: "fail";
+        blocked: "blocked";
+        skipped: "skipped";
+        retrying: "retrying";
+    }>;
+    exitCode: z.ZodOptional<z.ZodNumber>;
+    duration: z.ZodOptional<z.ZodNumber>;
+    stdout: z.ZodOptional<z.ZodString>;
+    stderr: z.ZodOptional<z.ZodString>;
+    artifacts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    attempts: z.ZodDefault<z.ZodNumber>;
+    lastAttempt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type GateResult = z.infer<typeof GateResult>;
+/**
+ * Node execution state
+ */
+declare const NodeResult: z.ZodObject<{
+    name: z.ZodString;
+    status: z.ZodEnum<{
+        pass: "pass";
+        fail: "fail";
+        blocked: "blocked";
+        skipped: "skipped";
+        retrying: "retrying";
+    }>;
+    gates: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        gate: z.ZodString;
+        status: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+            blocked: "blocked";
+            skipped: "skipped";
+            retrying: "retrying";
+        }>;
+        exitCode: z.ZodOptional<z.ZodNumber>;
+        duration: z.ZodOptional<z.ZodNumber>;
+        stdout: z.ZodOptional<z.ZodString>;
+        stderr: z.ZodOptional<z.ZodString>;
+        artifacts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        attempts: z.ZodDefault<z.ZodNumber>;
+        lastAttempt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    blockedBy: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    eligibleForMerge: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+type NodeResult = z.infer<typeof NodeResult>;
+/**
+ * Plan item with dependencies resolved by name.
+ * Note: Input generator defaults name := id when name is unset.
+ * All deps references must match item names in the final plan.
+ */
+declare const PlanItem: z.ZodObject<{
+    name: z.ZodString;
+    deps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    gates: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        run: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        runtime: z.ZodDefault<z.ZodEnum<{
+            local: "local";
+            container: "container";
+            "ci-service": "ci-service";
+        }>>;
+        container: z.ZodOptional<z.ZodObject<{
+            image: z.ZodString;
+            entrypoint: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            mounts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                source: z.ZodString;
+                target: z.ZodString;
+                type: z.ZodDefault<z.ZodEnum<{
+                    bind: "bind";
+                    volume: "volume";
+                }>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        artifacts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>>;
+    tier: z.ZodOptional<z.ZodObject<{
+        suggested: z.ZodEnum<{
+            senior: "senior";
+            mid: "mid";
+            junior: "junior";
+        }>;
+        actual: z.ZodOptional<z.ZodEnum<{
+            senior: "senior";
+            mid: "mid";
+            junior: "junior";
+        }>>;
+        escalated: z.ZodDefault<z.ZodBoolean>;
+        escalationReason: z.ZodOptional<z.ZodString>;
+        mismatch: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+type PlanItem = z.infer<typeof PlanItem>;
+declare const Plan: z.ZodObject<{
+    schemaVersion: z.ZodString;
+    target: z.ZodDefault<z.ZodString>;
+    policy: z.ZodOptional<z.ZodObject<{
+        requiredGates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        optionalGates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        maxWorkers: z.ZodDefault<z.ZodNumber>;
+        retries: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            maxAttempts: z.ZodDefault<z.ZodNumber>;
+            backoffSeconds: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        overrides: z.ZodDefault<z.ZodObject<{
+            adminGreen: z.ZodOptional<z.ZodObject<{
+                allowedUsers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                requireReason: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        blockOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        mergeRule: z.ZodDefault<z.ZodObject<{
+            type: z.ZodDefault<z.ZodEnum<{
+                "strict-required": "strict-required";
+            }>>;
+        }, z.core.$strip>>;
+        performance: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+            maxMemoryMB: z.ZodOptional<z.ZodNumber>;
+            batchSize: z.ZodDefault<z.ZodNumber>;
+            cacheTTLSeconds: z.ZodDefault<z.ZodNumber>;
+            enableCaching: z.ZodDefault<z.ZodBoolean>;
+            throttleOnMemory: z.ZodDefault<z.ZodBoolean>;
+            memoryThresholdPercent: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        security: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+            blockCritical: z.ZodDefault<z.ZodBoolean>;
+            blockHigh: z.ZodDefault<z.ZodBoolean>;
+            maxMedium: z.ZodDefault<z.ZodNumber>;
+            maxLow: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        deps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        gates: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            run: z.ZodString;
+            cwd: z.ZodOptional<z.ZodString>;
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            runtime: z.ZodDefault<z.ZodEnum<{
+                local: "local";
+                container: "container";
+                "ci-service": "ci-service";
+            }>>;
+            container: z.ZodOptional<z.ZodObject<{
+                image: z.ZodString;
+                entrypoint: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                mounts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    source: z.ZodString;
+                    target: z.ZodString;
+                    type: z.ZodDefault<z.ZodEnum<{
+                        bind: "bind";
+                        volume: "volume";
+                    }>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
+            artifacts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strict>>>;
+        tier: z.ZodOptional<z.ZodObject<{
+            suggested: z.ZodEnum<{
+                senior: "senior";
+                mid: "mid";
+                junior: "junior";
+            }>;
+            actual: z.ZodOptional<z.ZodEnum<{
+                senior: "senior";
+                mid: "mid";
+                junior: "junior";
+            }>>;
+            escalated: z.ZodDefault<z.ZodBoolean>;
+            escalationReason: z.ZodOptional<z.ZodString>;
+            mismatch: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+type Plan = z.infer<typeof Plan>;
+/**
+ * Load and validate a plan.json file
+ */
+declare function loadPlan(planContent: string): Plan;
+
+/**
+ * Error Recovery and Resilience Framework
+ *
+ * Implements:
+ * - Error classification (transient vs permanent)
+ * - Exponential backoff retry mechanism
+ * - Circuit breaker pattern for external services
+ * - Graceful degradation strategies
+ * - Detailed error diagnostics and recovery guidance
+ */
+/**
+ * Error classification types
+ */
+declare enum ErrorType {
+    /** Transient errors that may succeed on retry (network, rate limits, temporary service outages) */
+    Transient = "transient",
+    /** Permanent errors that won't succeed on retry (validation, auth, not found) */
+    Permanent = "permanent",
+    /** Unknown error classification */
+    Unknown = "unknown"
+}
+/**
+ * Error severity levels for prioritization and alerting
+ */
+declare enum ErrorSeverity {
+    /** Critical errors that prevent operation continuation */
+    Critical = "critical",
+    /** High severity errors that impact functionality */
+    High = "high",
+    /** Medium severity errors with workarounds available */
+    Medium = "medium",
+    /** Low severity errors or warnings */
+    Low = "low"
+}
+/**
+ * Classified error with context and recovery information
+ */
+interface ClassifiedError {
+    /** Original error */
+    error: Error;
+    /** Error classification type */
+    type: ErrorType;
+    /** Severity level */
+    severity: ErrorSeverity;
+    /** Human-readable context */
+    context: string;
+    /** Suggested recovery actions */
+    recoveryActions: string[];
+    /** Whether this error is retryable */
+    retryable: boolean;
+    /** Error code for automation */
+    code: string;
+    /** Metadata for diagnostics */
+    metadata?: Record<string, any>;
+}
+
+/**
+ * Execution state management for the lexrunner
+ * Handles status tracking, propagation, and merge eligibility
+ * Includes error diagnostics and recovery tracking
+ */
+
+/**
+ * Error diagnostic information
+ */
+interface ErrorDiagnostic {
+    nodeName: string;
+    gateName: string;
+    classified: ClassifiedError;
+    timestamp: string;
+    attemptNumber: number;
+}
+/**
+ * Execution state manager with error tracking
+ */
+declare class ExecutionState {
+    private results;
+    private plan;
+    private policy;
+    private errorDiagnostics;
+    constructor(plan: Plan);
+    /**
+     * Record error diagnostic for troubleshooting
+     */
+    recordErrorDiagnostic(nodeName: string, gateName: string, error: Error, attemptNumber: number): void;
+    /**
+     * Get error diagnostics
+     */
+    getErrorDiagnostics(): ErrorDiagnostic[];
+    /**
+     * Get summary of errors by type
+     */
+    getErrorSummary(): {
+        transient: number;
+        permanent: number;
+        unknown: number;
+    };
+    /**
+     * Update gate result for a node
+     */
+    updateGateResult(nodeName: string, gateResult: GateResult): void;
+    /**
+     * Update node status based on its gate results and policy
+     */
+    private updateNodeStatus;
+    /**
+     * Propagate blocked status to dependent nodes
+     */
+    propagateBlockedStatus(): void;
+    /**
+     * Get required gates for a node based on policy and node configuration
+     */
+    private getRequiredGatesForNode;
+    /**
+     * Build dependency map for the plan
+     */
+    private buildDependencyMap;
+    /**
+     * Get current results
+     */
+    getResults(): Map<string, NodeResult>;
+    /**
+     * Get result for specific node
+     */
+    getNodeResult(nodeName: string): NodeResult | undefined;
+    /**
+     * Get nodes eligible for merge
+     */
+    getEligibleNodes(): string[];
+    /**
+     * Check if all nodes are complete (passed, failed, or blocked)
+     */
+    isExecutionComplete(): boolean;
+    /**
+     * Load gate results from a directory and populate execution state
+     * This allows importing results from external runs (manual gates, CI, etc.)
+     *
+     * @param gateResultsDir Directory containing gate result JSON files
+     * @returns Number of gate results loaded
+     */
+    loadGateResultsFromDirectory(gateResultsDir: string): number;
+}
+
+/**
+ * Progress indicators for human mode CLI output
+ * Provides timing and progress ticks for long operations
+ */
+interface ProgressOptions {
+    /** Whether to show progress indicators (disabled in JSON mode) */
+    enabled: boolean;
+}
+/**
+ * Progress reporter for long-running operations
+ */
+declare class ProgressReporter {
+    private enabled;
+    private startTimes;
+    constructor(options?: ProgressOptions);
+    /**
+     * Mark the start of a level
+     */
+    levelStart(level: number, items: string[]): void;
+    /**
+     * Mark the completion of a level
+     */
+    levelComplete(level: number): void;
+    /**
+     * Mark the start of a node/item
+     */
+    nodeStart(name: string): void;
+    /**
+     * Mark the completion of a node/item (only if >2s threshold)
+     */
+    nodeComplete(name: string, success?: boolean): void;
+    /**
+     * Format duration in human-readable format
+     */
+    private formatDuration;
+}
+
+/**
+ * Turn Cost Tracking for Merge-Weave Operations
+ *
+ * Implements Turn Cost tracking per the coordination cost compression thesis:
+ * Turn Cost = λL + γC + ρR + τT + αA
+ *
+ * Where:
+ * - L: Latency (API response time, gate execution, merge time)
+ * - C: Context Reset tokens (N/A for deterministic runner)
+ * - R: Renegotiation (conflict resolution retries, clarification turns)
+ * - T: Token Bloat (excess tokens beyond expected)
+ * - A: Attention Switch (human interventions, manual conflict resolutions)
+ */
+/**
+ * Default weights for Turn Cost calculation
+ */
+declare const DEFAULT_TURN_COST_WEIGHTS: {
+    /** Weight for latency (λ) - normalized to seconds */
+    readonly lambda: 0.1;
+    /** Weight for context reset tokens (γ) */
+    readonly gamma: 0.1;
+    /** Weight for renegotiation count (ρ) */
+    readonly rho: 0.3;
+    /** Weight for token bloat (τ) */
+    readonly tau: 0.2;
+    /** Weight for attention switch count (α) */
+    readonly alpha: 0.3;
+};
+type TurnCostWeights = typeof DEFAULT_TURN_COST_WEIGHTS;
+/**
+ * Turn Cost components tracked during merge-weave operations
+ */
+interface TurnCostComponents {
+    /** Total latency in milliseconds */
+    latencyMs: number;
+    /** Context reset tokens (N/A for deterministic runner, always 0) */
+    contextResetTokens: number;
+    /** Number of renegotiation events (conflict retries, clarifications) */
+    renegotiationCount: number;
+    /** Token bloat (actual - expected tokens used) */
+    tokenBloat: number;
+    /** Number of attention switches (human interventions) */
+    attentionSwitchCount: number;
+}
+/**
+ * Event recorded during Turn Cost tracking
+ */
+interface TurnCostEvent {
+    /** Type of event */
+    type: "latency" | "renegotiation" | "token_bloat" | "attention_switch";
+    /** Timestamp of the event */
+    timestamp: string;
+    /** Event-specific details */
+    details: {
+        /** Reason for the event */
+        reason?: string;
+        /** Duration in milliseconds (for latency events) */
+        durationMs?: number;
+        /** Expected token count (for token bloat events) */
+        expectedTokens?: number;
+        /** Actual token count (for token bloat events) */
+        actualTokens?: number;
+        /** Item name associated with the event */
+        itemName?: string;
+    };
+}
+/**
+ * Turn Cost summary for output
+ */
+interface TurnCostSummary {
+    /** Component values */
+    components: TurnCostComponents;
+    /** Weighted score using default weights */
+    weightedScore: number;
+    /** Number of events recorded */
+    eventCount: number;
+    /** Optional prior run score for comparison */
+    priorRunScore?: number;
+    /** Optional improvement percentage (negative = improvement) */
+    improvement?: string;
+}
+/**
+ * MergeWeaveTurnCost tracks coordination costs during merge-weave operations.
+ *
+ * Usage:
+ * ```typescript
+ * const turnCost = new MergeWeaveTurnCost();
+ *
+ * // Track latency for operations
+ * const start = performance.now();
+ * await someOperation();
+ * turnCost.recordLatency(performance.now() - start);
+ *
+ * // Track renegotiation events
+ * turnCost.recordRenegotiation('conflict in feature-branch');
+ *
+ * // Track token bloat
+ * turnCost.recordTokenBloat(1000, 1500); // expected, actual
+ *
+ * // Track attention switches
+ * turnCost.recordAttentionSwitch('manual conflict resolution required');
+ *
+ * // Get summary
+ * const summary = turnCost.toJSON();
+ * ```
+ */
+declare class MergeWeaveTurnCost {
+    private components;
+    private events;
+    private weights;
+    constructor(weights?: TurnCostWeights);
+    /**
+     * Record latency from an operation.
+     * @param durationMs Duration in milliseconds
+     * @param itemName Optional item name for context
+     */
+    recordLatency(durationMs: number, itemName?: string): void;
+    /**
+     * Record a renegotiation event (conflict resolution retry, clarification).
+     * @param reason Reason for the renegotiation
+     * @param itemName Optional item name for context
+     */
+    recordRenegotiation(reason: string, itemName?: string): void;
+    /**
+     * Record token bloat (excess tokens used beyond expected).
+     * @param expected Expected token count
+     * @param actual Actual token count
+     * @param itemName Optional item name for context
+     */
+    recordTokenBloat(expected: number, actual: number, itemName?: string): void;
+    /**
+     * Record an attention switch (human intervention required).
+     * @param reason Reason for the attention switch
+     * @param itemName Optional item name for context
+     */
+    recordAttentionSwitch(reason: string, itemName?: string): void;
+    /**
+     * Get the current Turn Cost components.
+     */
+    getComponents(): TurnCostComponents;
+    /**
+     * Get all recorded events.
+     */
+    getEvents(): TurnCostEvent[];
+    /**
+     * Calculate the weighted Turn Cost score.
+     * @param weights Optional custom weights (uses default if not provided)
+     */
+    getWeightedScore(weights?: TurnCostWeights): number;
+    /**
+     * Get Turn Cost summary for output.
+     * @param priorRunScore Optional prior run score for comparison
+     */
+    toJSON(priorRunScore?: number): TurnCostSummary;
+    /**
+     * Reset all tracked values.
+     */
+    reset(): void;
+    /**
+     * Merge another TurnCost tracker into this one.
+     * Useful for aggregating per-item costs into a total.
+     */
+    merge(other: MergeWeaveTurnCost): void;
+}
+
+/**
+ * Execute gates for multiple items with concurrency control and dependency ordering
+ */
+declare function executeGatesWithPolicy(plan: Plan, executionState: ExecutionState, artifactDir: string, timeoutMs?: number, progressReporter?: ProgressReporter, skipValidation?: boolean, repoRoot?: string, options?: {
+    runId?: string;
+    baseDir?: string;
+    turnCostTracker?: MergeWeaveTurnCost;
+}): Promise<void>;
+
+/**
+ * Merge eligibility and decision logic for lexrunner
+ * Implements policy-based merge decisions, short-circuiting, and manual overrides
+ */
+
+/**
+ * Merge decision result
+ */
+interface MergeDecision {
+    nodeName: string;
+    eligible: boolean;
+    reason: string;
+    requiresOverride: boolean;
+    blockedBy?: string[];
+}
+/**
+ * Override request for manual merge approval
+ */
+interface OverrideRequest {
+    nodeName: string;
+    requestedBy: string;
+    reason: string;
+    timestamp: string;
+}
+/**
+ * Merge eligibility evaluator
+ */
+declare class MergeEligibilityEvaluator {
+    private plan;
+    private policy;
+    private executionState;
+    private overrides;
+    constructor(plan: Plan, executionState: ExecutionState);
+    /**
+     * Get default policy if none specified
+     */
+    private getDefaultPolicy;
+    /**
+     * Evaluate merge eligibility for all nodes
+     */
+    evaluateAllNodes(): Map<string, MergeDecision>;
+    /**
+     * Evaluate merge eligibility for a specific node
+     */
+    evaluateNode(nodeName: string): MergeDecision;
+    /**
+     * Evaluate strict-required merge rule
+     */
+    private evaluateStrictRequired;
+    /**
+     * Check status of all dependencies
+     */
+    private checkDependencyStatus;
+    /**
+     * Request manual override for a node
+     */
+    requestOverride(nodeName: string, requestedBy: string, reason: string): boolean;
+    /**
+     * Check if an override is valid
+     */
+    private isValidOverride;
+    /**
+     * Get nodes ready for merge (eligible and all dependencies merged)
+     */
+    getNodesReadyForMerge(): string[];
+    /**
+     * Get merge summary for reporting
+     */
+    getMergeSummary(): {
+        eligible: string[];
+        blocked: string[];
+        pending: string[];
+        failed: string[];
+        overrides: OverrideRequest[];
+    };
+    /**
+     * Clear all overrides (for testing or reset)
+     */
+    clearOverrides(): void;
+}
+
+/**
+ * Core inputs processing - reads and normalizes configuration sources
+ * Maintains deterministic ordering and stable output
+ */
+/**
+ * Configuration source types
+ */
+interface ConfigSource {
+    file: string;
+    content: unknown;
+    exists: boolean;
+}
+/**
+ * Provenance map tracking source file for each configuration key
+ */
+interface ProvenanceMap {
+    [key: string]: string;
+}
+/**
+ * Normalized input configuration
+ */
+interface InputConfig {
+    version: number;
+    target: string;
+    items: InputItem[];
+    sources: ConfigSource[];
+    provenance?: ProvenanceMap;
+}
+interface InputItem {
+    id?: string;
+    name: string;
+    branch?: string;
+    sha?: string;
+    deps: string[];
+    strategy: "rebase-weave" | "merge-weave" | "squash-weave";
+    gates?: InputGate[];
+}
+interface InputGate {
+    name: string;
+    run: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    runtime?: "local" | "container" | "ci-service";
+    artifacts?: string[];
+}
+/**
+ * Load configuration from file system with deterministic precedence
+ * Returns normalized configuration with stable ordering
+ */
+declare function loadInputs(baseDir?: string): InputConfig;
+
+/**
+ * Capability Tier Schema
+ *
+ * Defines tier types for task assignment governance.
+ * Implements Claim 3.4: Matching task tier to model capability
+ * reduces overall Turn Cost by avoiding over/under-allocation.
+ */
+
+/**
+ * Tier override specification from CLI
+ * Format: "item-name=tier" (e.g., "PR-123=senior")
+ */
+declare const TierOverride: z.ZodObject<{
+    itemName: z.ZodString;
+    tier: z.ZodEnum<{
+        senior: "senior";
+        mid: "mid";
+        junior: "junior";
+    }>;
+}, z.core.$strip>;
+type TierOverride = z.infer<typeof TierOverride>;
+
+/**
+ * Core plan generation - transforms inputs to normalized plan
+ * Maintains deterministic ordering and canonical structure
+ */
+
+/**
+ * Generate normalized plan from input configuration
+ * Ensures deterministic output with stable ordering
+ */
+declare function generatePlan(inputs: InputConfig, options?: {
+    tierOverrides?: TierOverride[];
+}): Plan;
+
+/**
+ * Core snapshot generation - creates deterministic snapshot.md with metadata
+ * Includes plan hash, environment fingerprint, and stable metadata
+ */
+
+/**
+ * Generate deterministic snapshot.md with plan metadata
+ */
+declare function generateSnapshot(plan: Plan, inputs: InputConfig): string;
+/**
+ * Generate snapshot.md for GitHub-generated plans
+ */
+declare function generateGitHubSnapshot(plan: Plan): string;
+
+/**
+ * Serialize any value to canonical JSON with deterministic key ordering
+ * Arrays keep authored order, objects get keys sorted recursively
+ * Always ends with newline for consistent file artifacts
+ */
+declare function canonicalJSONStringify(input: unknown): string;
+
+/**
+ * Local overlay setup and initialization
+ * Auto-detects project type and creates .smartergpt.local/ directory
+ */
+interface LocalOverlayConfig {
+    role: string;
+    projectType: string;
+    name?: string;
+    version?: string;
+}
+interface LocalOverlayResult {
+    created: boolean;
+    path: string;
+    config: LocalOverlayConfig;
+    copiedFiles: string[];
+}
+/**
+ * Initialize local overlay directory with auto-detected project configuration
+ *
+ * @param baseDir - Base directory for workspace (default: current working directory)
+ * @param force - Force recreation even if local overlay exists
+ * @returns Result of initialization
+ */
+declare function initLocalOverlay(baseDir?: string, force?: boolean): LocalOverlayResult;
+
+/**
+ * Profile resolver with manifest support
+ * Implements precedence chain: --profile-dir → LEX_PR_PROFILE_DIR → .smartergpt.local/ → .smartergpt/
+ */
+/**
+ * Profile manifest schema
+ */
+interface ProfileManifest {
+    role: string;
+    name?: string;
+    version?: string;
+}
+/**
+ * Resolved profile information
+ */
+interface ResolvedProfile {
+    path: string;
+    source: string;
+    manifest: ProfileManifest;
+}
+/**
+ * Resolve profile directory with precedence chain
+ *
+ * Precedence order:
+ * 1. --profile-dir flag (passed as parameter)
+ * 2. LEX_PR_PROFILE_DIR environment variable
+ * 3. .smartergpt.local/ (local override, not tracked)
+ * 4. .smartergpt/ (tracked example profile)
+ *
+ * @param profileDirFlag - Profile directory from CLI flag (optional)
+ * @param baseDir - Base directory to resolve relative paths (default: current working directory)
+ * @returns Resolved profile with absolute path and manifest
+ */
+declare function resolveProfile(profileDirFlag?: string, baseDir?: string): ResolvedProfile;
+
+/**
+ * Health check endpoint for MCP server and general system health
+ */
+interface HealthStatus {
+    status: "healthy" | "degraded" | "unhealthy";
+    timestamp: string;
+    uptime: number;
+    version: string;
+    checks: {
+        memory: HealthCheck;
+        activeOperations: HealthCheck;
+        errorRate: HealthCheck;
+    };
+    metrics?: {
+        memory: NodeJS.MemoryUsage;
+        activeProfiles: number;
+        errorSummary: {
+            totalErrors: number;
+            uniqueErrors: number;
+        };
+    };
+}
+interface HealthCheck {
+    status: "pass" | "warn" | "fail";
+    message?: string;
+    value?: any;
+}
+/**
+ * Health checker for system monitoring
+ */
+declare class HealthChecker {
+    private startTime;
+    constructor();
+    /**
+     * Get current health status
+     */
+    getHealth(includeMetrics?: boolean): HealthStatus;
+    /**
+     * Check memory usage
+     */
+    private checkMemory;
+    /**
+     * Check active operations
+     */
+    private checkActiveOperations;
+    /**
+     * Check error rate
+     */
+    private checkErrorRate;
+}
+/**
+ * Global health checker instance
+ */
+declare const healthChecker: HealthChecker;
+
+/**
+ * Run-Centric Schemas for Tool-Grounded Interactions
+ *
+ * This module defines the canonical Zod schemas for StatusResponse and NextOption,
+ * which structure all tool-grounded interactions in the lexrunner system.
+ *
+ * Key invariants:
+ * - `nextOptions` is the ONLY canonical source of allowed next actions
+ * - Models should never invent actions outside of `nextOptions`
+ * - `summary` must be a single sentence that orients quickly
+ */
+
+/**
+ * PersonaSnapshot Schema
+ *
+ * Captures the current persona mode and its constraints at a point in time.
+ *
+ * @example
+ * ```typescript
+ * const snapshot: PersonaSnapshot = {
+ *   mode: "senior-dev",
+ *   forbidden: ["force-push", "delete-branch"],
+ *   completionGates: ["lint", "test", "build"],
+ *   decisionStyle: {
+ *     preferSmallDiffs: true,
+ *     requireRationaleForSkips: true,
+ *     escalateSecurityFindings: true
+ *   }
+ * };
+ * ```
+ */
+declare const PersonaSnapshotSchema: z.ZodObject<{
+    mode: z.ZodString;
+    forbidden: z.ZodArray<z.ZodString>;
+    completionGates: z.ZodArray<z.ZodString>;
+    decisionStyle: z.ZodOptional<z.ZodObject<{
+        preferSmallDiffs: z.ZodOptional<z.ZodBoolean>;
+        requireRationaleForSkips: z.ZodOptional<z.ZodBoolean>;
+        escalateSecurityFindings: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    outputFormat: z.ZodOptional<z.ZodObject<{
+        severityLevels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        requireSeverityOnFindings: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * StatusResponse Schema
+ *
+ * The canonical response format for run status queries.
+ * Contains full context for orientation and available actions.
+ *
+ * @example
+ * ```typescript
+ * const status: StatusResponse = {
+ *   runId: "01HXYZ123ABC",
+ *   state: "gated",
+ *   mode: "senior-dev",
+ *   procedure: "merge-weave-main",
+ *   summary: "Waiting for lint gate to pass on PR #42.",
+ *   progress: {
+ *     completed: ["fetch-prs", "analyze-deps"],
+ *     current: "run-gates",
+ *     remaining: ["merge-prs", "cleanup"]
+ *   },
+ *   nextOptions: [
+ *     {
+ *       action: "retry_gate",
+ *       description: "Retry the failing lint gate.",
+ *       riskLevel: "low"
+ *     },
+ *     {
+ *       action: "skip_gate",
+ *       description: "Skip the lint gate and continue.",
+ *       requiresLLMDecision: true,
+ *       prompt: "Provide rationale for skipping the lint gate.",
+ *       riskLevel: "medium"
+ *     }
+ *   ],
+ *   blockers: ["lint gate failing"],
+ *   riskFlags: ["unstable-ci"]
+ * };
+ * ```
+ */
+declare const StatusResponseSchema: z.ZodObject<{
+    runId: z.ZodString;
+    state: z.ZodString;
+    mode: z.ZodString;
+    procedure: z.ZodString;
+    summary: z.ZodString;
+    progress: z.ZodOptional<z.ZodObject<{
+        completed: z.ZodArray<z.ZodString>;
+        current: z.ZodNullable<z.ZodString>;
+        remaining: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    nextOptions: z.ZodArray<z.ZodObject<{
+        action: z.ZodString;
+        description: z.ZodString;
+        requiresLLMDecision: z.ZodOptional<z.ZodBoolean>;
+        prompt: z.ZodOptional<z.ZodString>;
+        responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        objective: z.ZodOptional<z.ZodString>;
+        constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        style: z.ZodOptional<z.ZodEnum<{
+            brief: "brief";
+            detailed: "detailed";
+        }>>;
+        riskLevel: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>>;
+    }, z.core.$strip>>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    riskFlags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    blockers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    persona: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodString;
+        forbidden: z.ZodArray<z.ZodString>;
+        completionGates: z.ZodArray<z.ZodString>;
+        decisionStyle: z.ZodOptional<z.ZodObject<{
+            preferSmallDiffs: z.ZodOptional<z.ZodBoolean>;
+            requireRationaleForSkips: z.ZodOptional<z.ZodBoolean>;
+            escalateSecurityFindings: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        outputFormat: z.ZodOptional<z.ZodObject<{
+            severityLevels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            requireSeverityOnFindings: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type StatusResponse = z.infer<typeof StatusResponseSchema>;
+
+/**
+ * Run Lifecycle Types
+ *
+ * Core types for the run lifecycle manager, including RunState, RunFilter,
+ * and related interfaces for tracking tool-grounded execution runs.
+ */
+
+/**
+ * Run State Schema
+ *
+ * Represents the complete state of a run at any point in time.
+ * Persisted to .lexrunner/runs/{runId}.json
+ */
+declare const RunStateSchema$1: z.ZodObject<{
+    runId: z.ZodString;
+    mode: z.ZodString;
+    procedure: z.ZodString;
+    repo: z.ZodString;
+    task: z.ZodOptional<z.ZodString>;
+    state: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    completedAt: z.ZodOptional<z.ZodString>;
+    completedSteps: z.ZodArray<z.ZodString>;
+    currentStep: z.ZodNullable<z.ZodString>;
+    params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    persona: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodString;
+        forbidden: z.ZodArray<z.ZodString>;
+        completionGates: z.ZodArray<z.ZodString>;
+        decisionStyle: z.ZodOptional<z.ZodObject<{
+            preferSmallDiffs: z.ZodOptional<z.ZodBoolean>;
+            requireRationaleForSkips: z.ZodOptional<z.ZodBoolean>;
+            escalateSecurityFindings: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        outputFormat: z.ZodOptional<z.ZodObject<{
+            severityLevels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            requireSeverityOnFindings: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type RunState$1 = z.infer<typeof RunStateSchema$1>;
+/**
+ * Parameters for creating a new run
+ */
+interface CreateRunParams {
+    /** Persona mode, e.g. "senior-dev", "eager-pm" */
+    mode: string;
+    /** Procedure being executed, e.g. "merge-weave-main", "pr-review" */
+    procedure: string;
+    /** Repository identifier (owner/repo or path) */
+    repo: string;
+    /** Optional task description */
+    task?: string;
+    /** Initial state in procedure state machine */
+    initialState?: string;
+    /** Runtime parameters for the run */
+    params?: Record<string, unknown>;
+    /** Additional metadata for the run */
+    metadata?: Record<string, unknown>;
+    /** Persona snapshot to freeze for the run */
+    persona?: z.infer<typeof PersonaSnapshotSchema>;
+}
+/**
+ * Filter options for listing runs
+ */
+interface RunFilter {
+    /** Filter by state */
+    state?: string;
+    /** Filter by procedure */
+    procedure?: string;
+    /** Filter by mode */
+    mode?: string;
+    /** Filter by creation date (ISO 8601 timestamp) - runs created after this date */
+    since?: string;
+    /** Filter by creation date (ISO 8601 timestamp) - runs created before this date */
+    until?: string;
+    /** Maximum number of runs to return */
+    limit?: number;
+}
+/**
+ * Input parameters for starting a run (MCP tool)
+ */
+declare const StartRunInputSchema: z.ZodObject<{
+    mode: z.ZodString;
+    procedure: z.ZodString;
+    repo: z.ZodString;
+    task: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type StartRunInput = z.infer<typeof StartRunInputSchema>;
+/**
+ * Input for getStatus (MCP tool)
+ */
+declare const GetStatusInputSchema: z.ZodObject<{
+    runId: z.ZodString;
+}, z.core.$strip>;
+type GetStatusInput = z.infer<typeof GetStatusInputSchema>;
+/**
+ * RunStateFile - Lenient type for testing and backwards compatibility
+ *
+ * This is a partial RunState that allows optional fields like completedSteps.
+ * Used primarily for test fixtures and backwards compatibility with LR-060 tests.
+ */
+interface RunStateFile {
+    runId: string;
+    mode: string;
+    procedure: string;
+    repo: string;
+    state: string;
+    createdAt: string;
+    updatedAt: string;
+    task?: string;
+    completedAt?: string;
+    completedSteps?: string[];
+    currentStep?: string | null;
+    params?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    /** Optional blockers for status display */
+    blockers?: string[];
+    /** Optional progress info for status display */
+    progress?: {
+        current: number;
+        total: number;
+        phase?: string;
+    };
+    /** Optional context for status display */
+    context?: Record<string, unknown>;
+}
+
+/**
+ * Status builder for constructing StatusResponse from run state
+ *
+ * Derives nextOptions from current state and builds rich context for model orientation.
+ */
+
+/**
+ * Input type for statusBuilder - accepts both RunState and lenient RunStateFile
+ */
+type StatusBuilderInput = RunState$1 | RunStateFile;
+/**
+ * Build a StatusResponse from run state
+ */
+declare function buildStatusResponse(runState: StatusBuilderInput, options?: {
+    baseDir?: string;
+}): StatusResponse;
+
+/**
+ * Artifact Discovery and Metadata
+ *
+ * Provides functionality to list and inspect artifacts and receipts for a run.
+ * Artifacts include plan files, decision logs, failure logs, gate reports, and reports.
+ */
+
+/**
+ * Input schema for listArtifacts
+ */
+declare const ListArtifactsInputSchema: z.ZodObject<{
+    runId: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+        gate: "gate";
+        failure: "failure";
+        log: "log";
+        decision: "decision";
+        report: "report";
+        plan: "plan";
+    }>>;
+    path: z.ZodOptional<z.ZodString>;
+    latestOnly: z.ZodOptional<z.ZodBoolean>;
+    inline: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type ListArtifactsInput = z.infer<typeof ListArtifactsInputSchema>;
+/**
+ * Output schema for listArtifacts
+ */
+declare const ListArtifactsOutputSchema: z.ZodObject<{
+    artifacts: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        type: z.ZodEnum<{
+            gate: "gate";
+            failure: "failure";
+            log: "log";
+            decision: "decision";
+            report: "report";
+            plan: "plan";
+        }>;
+        size: z.ZodNumber;
+        createdAt: z.ZodString;
+        modifiedAt: z.ZodString;
+        content: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    totalCount: z.ZodNumber;
+}, z.core.$strip>;
+type ListArtifactsOutput = z.infer<typeof ListArtifactsOutputSchema>;
+
+/**
+ * RunStore — Persistence Contract for Run Lifecycle
+ *
+ * This module defines the canonical interfaces and Zod schemas for run lifecycle persistence.
+ * It is the interface layer for the Store Layer 1.0.0 persistence abstraction.
+ *
+ * Key Design Decisions:
+ * - ID Naming: `runId`, `stepId`, `receiptId` (not generic `id`)
+ * - ID Ownership: Caller (orchestration) generates IDs, store is dumb persistence
+ * - Timestamps: UTC ISO 8601 strings (YYYY-MM-DDTHH:mm:ss.sssZ) for serialization
+ * - NDJSON Coexistence: RunStore does NOT replace audit logs; they remain human-friendly traces
+ *
+ * @module store/run-store
+ */
+
+/**
+ * Run state machine states.
+ *
+ * @example
+ * ```typescript
+ * const state: RunState = "running";
+ * ```
+ */
+declare const RunStateSchema: z.ZodEnum<{
+    completed: "completed";
+    failed: "failed";
+    pending: "pending";
+    aborted: "aborted";
+    running: "running";
+}>;
+type RunState = z.infer<typeof RunStateSchema>;
+/**
+ * A single run record.
+ *
+ * ID Ownership: `runId` MUST be pre-generated by the caller (orchestration layer).
+ * The same runId appears in artifacts, NDJSON logs, and MCP status responses.
+ * The store is responsible for persistence, not identity generation.
+ *
+ * Timestamps: All timestamps MUST be UTC ISO 8601 strings (YYYY-MM-DDTHH:mm:ss.sssZ).
+ *
+ * @example
+ * ```typescript
+ * const run: RunRecord = {
+ *   runId: "01HXYZ123ABC",
+ *   planHash: "sha256:abc123...",
+ *   state: "running",
+ *   startedAt: "2024-01-15T10:30:00.000Z",
+ *   metadata: { prNumber: 42 }
+ * };
+ * ```
+ */
+declare const RunRecordSchema: z.ZodObject<{
+    runId: z.ZodString;
+    planHash: z.ZodString;
+    state: z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        pending: "pending";
+        aborted: "aborted";
+        running: "running";
+    }>;
+    startedAt: z.ZodString;
+    completedAt: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type RunRecord = z.infer<typeof RunRecordSchema>;
+/**
+ * A single step within a run.
+ *
+ * Timestamps: MUST be UTC ISO 8601 strings.
+ *
+ * @example
+ * ```typescript
+ * const step: StepOutcome = {
+ *   stepId: "step-001",
+ *   runId: "01HXYZ123ABC",
+ *   nodeId: "pr-42",
+ *   gateName: "lint",
+ *   status: "pass",
+ *   durationMs: 1234,
+ *   timestamp: "2024-01-15T10:30:05.000Z"
+ * };
+ * ```
+ */
+declare const StepOutcomeSchema: z.ZodObject<{
+    stepId: z.ZodString;
+    runId: z.ZodString;
+    nodeId: z.ZodString;
+    gateName: z.ZodString;
+    status: z.ZodEnum<{
+        pass: "pass";
+        fail: "fail";
+        blocked: "blocked";
+        skipped: "skipped";
+    }>;
+    durationMs: z.ZodNumber;
+    logs: z.ZodOptional<z.ZodString>;
+    artifacts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+type StepOutcome = z.infer<typeof StepOutcomeSchema>;
+/**
+ * A receipt recording scope/risk changes requiring human approval.
+ *
+ * Timestamps: MUST be UTC ISO 8601 strings.
+ *
+ * @example
+ * ```typescript
+ * const receipt: Receipt = {
+ *   receiptId: "receipt-001",
+ *   runId: "01HXYZ123ABC",
+ *   reason: "Scope expanded beyond initial plan",
+ *   approver: "alice@example.com",
+ *   timestamp: "2024-01-15T10:31:00.000Z"
+ * };
+ * ```
+ */
+declare const ReceiptSchema: z.ZodObject<{
+    receiptId: z.ZodString;
+    runId: z.ZodString;
+    reason: z.ZodString;
+    approver: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+type Receipt = z.infer<typeof ReceiptSchema>;
+/**
+ * Options for listing runs.
+ */
+interface ListRunsOptions {
+    /** Maximum number of runs to return. */
+    limit?: number;
+    /** Number of runs to skip (for pagination). */
+    offset?: number;
+    /** Filter by run state. */
+    state?: RunState;
+}
+/**
+ * RunStore — persistence contract for run lifecycle.
+ *
+ * Default: InMemoryRunStore (CLI).
+ * Future: SqliteRunStore, PostgresRunStore.
+ *
+ * Note: RunStore provides structured access to runs/steps/receipts.
+ * It does NOT replace NDJSON audit logs — those remain the human-friendly trace.
+ *
+ * @example
+ * ```typescript
+ * // Create a run
+ * await store.createRun({
+ *   runId: "run-001",
+ *   planHash: "sha256:abc123",
+ *   state: "pending",
+ *   startedAt: new Date().toISOString()
+ * });
+ *
+ * // Update run state
+ * await store.updateRun("run-001", { state: "running" });
+ *
+ * // Append step outcomes
+ * await store.appendStep({
+ *   stepId: "step-001",
+ *   runId: "run-001",
+ *   nodeId: "pr-42",
+ *   gateName: "lint",
+ *   status: "pass",
+ *   durationMs: 1234,
+ *   timestamp: new Date().toISOString()
+ * });
+ *
+ * // Get run details
+ * const run = await store.getRun("run-001");
+ *
+ * // Clean up
+ * await store.close();
+ * ```
+ */
+interface RunStore {
+    /**
+     * Create a new run record.
+     *
+     * @param run - The run record to create (runId must be pre-generated by caller)
+     * @throws If run with same runId already exists
+     */
+    createRun(run: RunRecord): Promise<void>;
+    /**
+     * Update an existing run record.
+     *
+     * @param runId - The run identifier to update
+     * @param updates - Partial updates to apply (runId cannot be changed)
+     * @throws If run with given runId does not exist
+     */
+    updateRun(runId: string, updates: Partial<Omit<RunRecord, "runId">>): Promise<void>;
+    /**
+     * Get a run record by ID.
+     *
+     * @param runId - The run identifier
+     * @returns The run record, or null if not found
+     */
+    getRun(runId: string): Promise<RunRecord | null>;
+    /**
+     * List run records with optional filtering and pagination.
+     *
+     * @param options - Optional filtering and pagination options
+     * @returns Array of run records matching the criteria
+     */
+    listRuns(options?: ListRunsOptions): Promise<RunRecord[]>;
+    /**
+     * Append a step outcome to a run.
+     *
+     * @param step - The step outcome to append
+     */
+    appendStep(step: StepOutcome): Promise<void>;
+    /**
+     * Get all step outcomes for a run.
+     *
+     * @param runId - The run identifier
+     * @returns Array of step outcomes for the run
+     */
+    getStepsForRun(runId: string): Promise<StepOutcome[]>;
+    /**
+     * Save a receipt for scope/risk escalation.
+     *
+     * @param receipt - The receipt to save
+     */
+    saveReceipt(receipt: Receipt): Promise<void>;
+    /**
+     * Get all receipts for a run.
+     *
+     * @param runId - The run identifier
+     * @returns Array of receipts for the run
+     */
+    getReceiptsForRun(runId: string): Promise<Receipt[]>;
+    /**
+     * Get the count of runs, optionally filtered by state.
+     *
+     * @param state - Optional state filter
+     * @returns Number of runs matching the criteria
+     */
+    getRunCount(state?: RunState): Promise<number>;
+    /**
+     * Close the store and release any resources.
+     * Should be called when the store is no longer needed.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Execution Frame Types
+ *
+ * Types for capturing workflow execution as Frames for memory integration.
+ * Implements AX-005: Frame emission for core workflows.
+ *
+ * AX Principle: Memory Is a Feature
+ */
+
+/**
+ * Frame outcome status
+ */
+type FrameOutcome = "success" | "failure" | "partial";
+/**
+ * Execution Frame schema
+ *
+ * Represents what was attempted, scope touched, outcome, and recommended next steps.
+ */
+declare const ExecutionFrameSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        gate: "gate";
+        procedure: "procedure";
+        execution: "execution";
+        "merge-weave": "merge-weave";
+    }>;
+    reference_point: z.ZodString;
+    summary_caption: z.ZodString;
+    module_scope: z.ZodArray<z.ZodString>;
+    keywords: z.ZodArray<z.ZodString>;
+    outcome: z.ZodEnum<{
+        success: "success";
+        failure: "failure";
+        partial: "partial";
+    }>;
+    next_actions: z.ZodArray<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        duration_ms: z.ZodOptional<z.ZodNumber>;
+        conflicts_resolved: z.ZodOptional<z.ZodNumber>;
+        gates_passed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        gates_failed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        artifacts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        error: z.ZodOptional<z.ZodString>;
+        exit_code: z.ZodOptional<z.ZodNumber>;
+        run_id: z.ZodOptional<z.ZodString>;
+        plan_hash: z.ZodOptional<z.ZodString>;
+        turn_cost: z.ZodOptional<z.ZodObject<{
+            components: z.ZodObject<{
+                latencyMs: z.ZodNumber;
+                contextResetTokens: z.ZodNumber;
+                renegotiationCount: z.ZodNumber;
+                tokenBloat: z.ZodNumber;
+                attentionSwitchCount: z.ZodNumber;
+            }, z.core.$strip>;
+            weightedScore: z.ZodNumber;
+            eventCount: z.ZodNumber;
+            priorRunScore: z.ZodOptional<z.ZodNumber>;
+            improvement: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        tier_metrics: z.ZodOptional<z.ZodObject<{
+            totalTasks: z.ZodNumber;
+            byTier: z.ZodObject<{
+                senior: z.ZodNumber;
+                mid: z.ZodNumber;
+                junior: z.ZodNumber;
+            }, z.core.$strip>;
+            escalations: z.ZodNumber;
+            mismatches: z.ZodNumber;
+            tierMatchRate: z.ZodNumber;
+            escalationRate: z.ZodNumber;
+        }, z.core.$strip>>;
+        governed_by: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            constraintId: z.ZodString;
+            source: z.ZodEnum<{
+                persona: "persona";
+                baseline: "baseline";
+                learned: "learned";
+            }>;
+            action: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ExecutionFrame = z.infer<typeof ExecutionFrameSchema>;
+/**
+ * Result of Frame emission
+ */
+interface FrameEmitResult {
+    /** Whether the Frame was emitted successfully */
+    success: boolean;
+    /** The emitted Frame (if successful) */
+    frame?: ExecutionFrame;
+    /** Frame ID (if stored via Lex) */
+    frameId?: string;
+    /** Error message (if failed) */
+    error?: string;
+}
+
+/**
+ * Run Lifecycle Manager
+ *
+ * Core infrastructure for creating, tracking, and persisting run state
+ * across the tool-grounded lifecycle.
+ *
+ * Supports dual-write mode: persists to both NDJSON files (backward compatible)
+ * and optional RunStore for structured queries.
+ */
+
+/**
+ * Options for creating a RunManager
+ */
+interface RunManagerOptions {
+    /**
+     * Base directory for run storage (defaults to cwd)
+     */
+    baseDir?: string;
+    /**
+     * Optional RunStore for structured persistence.
+     * If provided, step outcomes and receipts will be persisted to this store.
+     * NDJSON coexistence is maintained regardless.
+     */
+    runStore?: RunStore;
+}
+/**
+ * RunManager - Core run lifecycle management
+ *
+ * Handles creation, retrieval, updates, and cleanup of run state.
+ * Supports dual-write mode: NDJSON files for backward compatibility,
+ * plus optional RunStore for structured queries.
+ */
+declare class RunManager {
+    private baseDir;
+    private runStore;
+    /**
+     * Create a new RunManager
+     *
+     * @param baseDirOrOptions - Base directory string (deprecated) or options object
+     */
+    constructor(baseDirOrOptions?: string | RunManagerOptions);
+    /**
+     * Get the runs directory path
+     *
+     * @returns Path to the runs directory
+     */
+    getRunsDir(): string;
+    /**
+     * Create a new run
+     *
+     * Generates a unique runId (ULID), initializes state, and persists to disk.
+     *
+     * @param params - Run creation parameters
+     * @returns The created RunState
+     */
+    createRun(params: CreateRunParams): Promise<RunState$1>;
+    /**
+     * Get a run by ID
+     *
+     * @param runId - The run identifier
+     * @returns RunState if found, null if not found
+     */
+    getRun(runId: string): Promise<RunState$1 | null>;
+    /**
+     * List runs with optional filtering
+     *
+     * Note: Filters are applied to the index first, so only matching entries
+     * are loaded. Use the `limit` filter to control the number of runs loaded.
+     *
+     * @param filter - Optional filter criteria
+     * @returns Array of RunState objects matching the filter
+     */
+    listRunStates(filter?: RunFilter): Promise<RunState$1[]>;
+    /**
+     * List run IDs (synchronous)
+     *
+     * Returns sorted list of run IDs from the index.
+     *
+     * @returns Sorted array of run IDs
+     */
+    listRuns(): string[];
+    /**
+     * Update a run
+     *
+     * Applies updates atomically and persists changes.
+     *
+     * @param runId - The run identifier
+     * @param updates - Partial updates to apply
+     * @returns Updated RunState
+     * @throws Error if run not found
+     */
+    updateRun(runId: string, updates: Partial<RunState$1>): Promise<RunState$1>;
+    /**
+     * Transition run state
+     *
+     * Applies a state transition event and persists the change.
+     * Currently does not validate against a state machine - this is
+     * intentionally flexible for different procedures.
+     *
+     * @param runId - The run identifier
+     * @param newState - The new state to transition to
+     * @returns Updated RunState
+     * @throws AXErrorException if run not found
+     */
+    transitionState(runId: string, newState: string): Promise<RunState$1>;
+    /**
+     * Mark a step as complete
+     *
+     * @param runId - The run identifier
+     * @param stepId - The step to mark as complete
+     * @param nextStep - The next step to set as current (optional)
+     * @returns Updated RunState
+     */
+    completeStep(runId: string, stepId: string, nextStep?: string | null): Promise<RunState$1>;
+    /**
+     * Log a decision to the run's decision log
+     *
+     * @param runId - The run identifier
+     * @param decision - The decision to log
+     */
+    logDecision(runId: string, decision: Record<string, unknown>): Promise<void>;
+    /**
+     * Log a failure to the run's failure log
+     *
+     * @param runId - The run identifier
+     * @param failure - The failure to log
+     */
+    logFailure(runId: string, failure: Record<string, unknown>): Promise<void>;
+    /**
+     * Get the RunStore instance (if configured)
+     *
+     * @returns The RunStore instance, or undefined if not configured
+     */
+    getRunStore(): RunStore | undefined;
+    /**
+     * Record a step outcome to the RunStore.
+     *
+     * Step outcomes are persisted to both:
+     * 1. NDJSON log (backward compatible)
+     * 2. RunStore (if configured)
+     *
+     * @param outcome - The step outcome to record
+     *
+     * @example
+     * ```typescript
+     * await manager.recordStepOutcome({
+     *   stepId: "step-001",
+     *   runId: "run-001",
+     *   nodeId: "pr-42",
+     *   gateName: "lint",
+     *   status: "pass",
+     *   durationMs: 1234,
+     *   timestamp: new Date().toISOString()
+     * });
+     * ```
+     */
+    recordStepOutcome(outcome: StepOutcome): Promise<void>;
+    /**
+     * Record a receipt (scope/risk escalation) to the RunStore.
+     *
+     * Receipts are persisted to both:
+     * 1. NDJSON log (backward compatible)
+     * 2. RunStore (if configured)
+     *
+     * @param receipt - The receipt to record
+     *
+     * @example
+     * ```typescript
+     * await manager.recordReceipt({
+     *   receiptId: "receipt-001",
+     *   runId: "run-001",
+     *   reason: "Scope expanded beyond initial plan",
+     *   approver: "alice@example.com",
+     *   timestamp: new Date().toISOString()
+     * });
+     * ```
+     */
+    recordReceipt(receipt: Receipt): Promise<void>;
+    /**
+     * Get step outcomes for a run.
+     *
+     * Queries the RunStore if configured, otherwise returns from NDJSON logs.
+     *
+     * @param runId - The run identifier
+     * @returns Array of step outcomes for the run
+     */
+    getStepOutcomes(runId: string): Promise<StepOutcome[]>;
+    /**
+     * Get receipts for a run.
+     *
+     * Queries the RunStore if configured, otherwise returns from NDJSON logs.
+     *
+     * @param runId - The run identifier
+     * @returns Array of receipts for the run
+     */
+    getReceipts(runId: string): Promise<Receipt[]>;
+    /**
+     * Get decisions for a run
+     *
+     * @param runId - The run identifier
+     * @returns Array of decision log entries
+     */
+    getDecisions(runId: string): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Get failures for a run
+     *
+     * @param runId - The run identifier
+     * @returns Array of failure log entries
+     */
+    getFailures(runId: string): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Archive a run (mark as archived in metadata)
+     *
+     * @param runId - The run identifier
+     */
+    archiveRun(runId: string): Promise<void>;
+    /**
+     * Delete a run and all associated data (sync version)
+     *
+     * @param runId - The run identifier
+     * @returns true if run was deleted, false if not found
+     */
+    deleteRun(runId: string): boolean;
+    /**
+     * Delete a run and all associated data (async version)
+     *
+     * @param runId - The run identifier
+     */
+    deleteRunAsync(runId: string): Promise<void>;
+    /**
+     * Start a new run (MCP tool interface)
+     *
+     * Convenience wrapper around createRun for MCP tool usage.
+     * Maps StartRunInput to CreateRunParams and returns a structured result.
+     *
+     * @param input - MCP tool input for starting a run
+     * @returns Result object with runId, status, message, and initialStatus
+     */
+    startRun(input: StartRunInput): {
+        runId: string;
+        status: string;
+        message: string;
+        initialStatus: ReturnType<typeof buildStatusResponse>;
+    };
+    /**
+     * Check if a run exists
+     *
+     * @param runId - The run identifier
+     * @returns true if run exists, false otherwise
+     */
+    runExists(runId: string): boolean;
+    /**
+     * Load run state (synchronous)
+     *
+     * @param runId - The run identifier
+     * @returns RunState
+     * @throws Error if run not found
+     */
+    loadRunState(runId: string): RunState$1;
+    /**
+     * Update run state (synchronous)
+     *
+     * @param runId - The run identifier
+     * @param updates - Partial updates to apply
+     * @returns Updated RunState
+     * @throws Error if run not found
+     */
+    updateRunState(runId: string, updates: Partial<RunState$1>): RunState$1;
+    /**
+     * Get status of a run (MCP tool interface)
+     *
+     * Convenience wrapper around getRun for MCP tool usage.
+     * Returns a structured status response.
+     *
+     * @param input - MCP tool input for getting status
+     * @returns Status response object
+     * @throws RunNotFoundError if run not found
+     */
+    getStatus(input: GetStatusInput): ReturnType<typeof buildStatusResponse>;
+    /**
+     * List artifacts for a run (MCP tool interface)
+     *
+     * Returns metadata for all artifacts in a run directory,
+     * with optional filtering by type, path pattern, and recency.
+     *
+     * @param input - MCP tool input for listing artifacts
+     * @returns ListArtifactsOutput with artifacts array and total count
+     * @throws RunNotFoundError if run not found
+     */
+    listArtifacts(input: ListArtifactsInput): ListArtifactsOutput;
+    /**
+     * Complete a run and emit a Frame (AX-005)
+     *
+     * Transitions the run to a terminal state and emits an execution Frame
+     * capturing what was attempted, scope touched, outcome, and next steps.
+     * The Frame is persisted to .lexrunner/frames/ for audit trail.
+     *
+     * @param runId - The run identifier
+     * @param outcome - The outcome of the run (success/failure/partial)
+     * @param nextActions - Recommended next actions
+     * @param options - Additional options
+     * @returns Updated RunState and FrameEmitResult
+     */
+    completeRunWithFrame(runId: string, outcome: FrameOutcome, nextActions: string[], options?: {
+        artifacts?: string[];
+        error?: string;
+        planHash?: string;
+    }): Promise<{
+        runState: RunState$1;
+        frameResult: FrameEmitResult;
+    }>;
+    /**
+     * Synchronous version of createRun for MCP compatibility
+     *
+     * @param params - Run creation parameters
+     * @returns The created RunState
+     */
+    private createRunSync;
+    /**
+     * Create an index entry from a run state
+     */
+    private createIndexEntry;
+    /**
+     * Check if a state is terminal
+     */
+    private isTerminalState;
+}
+/**
+ * Create a new RunManager instance
+ *
+ * @param baseDirOrOptions - Base directory string or options object
+ * @returns A new RunManager instance
+ *
+ * @example
+ * ```typescript
+ * // Legacy: string baseDir
+ * const manager = createRunManager("/path/to/project");
+ *
+ * // New: options object with RunStore
+ * const store = new InMemoryRunStore();
+ * const manager = createRunManager({ baseDir: "/path/to/project", runStore: store });
+ * ```
+ */
+declare function createRunManager(baseDirOrOptions?: string | RunManagerOptions): RunManager;
+
+/**
+ * Compute merge order levels using Kahn's algorithm with deterministic ordering
+ * Returns array of levels, where each level contains item names that can be processed in parallel
+ */
+declare function computeMergeOrder(plan: Plan): string[][];
+
+/**
+ * GitHub API integration for PR discovery and metadata extraction
+ * Maintains deterministic ordering and stable output
+ * Includes error recovery with retry and circuit breaker patterns
+ */
+
+interface GitHubPullRequest {
+    number: number;
+    title: string;
+    branch: string;
+    sha: string;
+    state: "open" | "closed" | "merged";
+    labels: string[];
+    author: string;
+    baseBranch: string;
+    createdAt: string;
+    updatedAt: string;
+    mergeable?: boolean;
+    body?: string | null;
+    draft?: boolean;
+    reviewRequested?: boolean;
+}
+interface GitHubConfig {
+    token?: string;
+    owner: string;
+    repo: string;
+}
+/**
+ * GitHub API client for PR operations with error recovery
+ */
+declare class GitHubAPI {
+    private octokit;
+    config: GitHubConfig;
+    private circuitBreaker;
+    private normalized;
+    constructor(config: GitHubConfig);
+    /**
+     * Get the underlying Octokit instance for advanced operations
+     * Use with caution - prefer using typed methods when available
+     */
+    getOctokit(): Octokit;
+    /**
+     * Normalize repository owner and name to match GitHub's canonical casing.
+     * This handles case-insensitive lookups where git remote URLs may have
+     * different casing than the actual GitHub repository.
+     */
+    private normalizeRepositoryName;
+    /**
+     * Extract HTTP status code from error object
+     */
+    private extractErrorStatus;
+    /**
+     * Discover open pull requests with stable ordering and error recovery
+     */
+    discoverPullRequests(state?: "open" | "closed" | "all"): Promise<GitHubPullRequest[]>;
+    /**
+     * Get repository information
+     */
+    getRepositoryInfo(): Promise<{
+        name: string;
+        fullName: string;
+        defaultBranch: string;
+        private: boolean;
+    }>;
+    /**
+     * Check if authentication is working
+     */
+    checkAuth(): Promise<{
+        authenticated: boolean;
+        user?: string;
+    }>;
+    /**
+     * Get a specific pull request by number
+     */
+    getPullRequest(prNumber: number): Promise<GitHubPullRequest | null>;
+    /**
+     * Update a pull request (e.g., to undraft it)
+     */
+    updatePullRequest(owner: string, repo: string, prNumber: number, updates: {
+        draft?: boolean;
+        title?: string;
+        body?: string;
+    }): Promise<void>;
+    /**
+     * Add a label to a pull request
+     */
+    addLabel(prNumber: number, label: string): Promise<void>;
+    /**
+     * Remove a label from a pull request
+     */
+    removeLabel(prNumber: number, label: string): Promise<void>;
+    /**
+     * Get labels for a pull request
+     */
+    getLabels(prNumber: number): Promise<string[]>;
+    /**
+     * Get repository info (for harvest)
+     */
+    getRepository(): Promise<{
+        default_branch: string;
+        [key: string]: any;
+    }>;
+    /**
+     * Get a git reference (branch/tag SHA)
+     */
+    getRef(ref: string): Promise<{
+        object: {
+            sha: string;
+        };
+    }>;
+    /**
+     * Get check runs for a commit SHA
+     */
+    getCheckRuns(sha: string): Promise<{
+        total_count: number;
+        check_runs: Array<{
+            status: string;
+            conclusion: string | null;
+        }>;
+    }>;
+    /**
+     * Get reviews for a pull request
+     */
+    getReviews(prNumber: number): Promise<Array<{
+        user: {
+            login: string;
+        } | null;
+        state: string;
+    }>>;
+    /**
+     * Compare two commits
+     */
+    compare(base: string, head: string): Promise<{
+        merge_base_commit?: {
+            sha: string;
+        };
+    }>;
+    /**
+     * List issues (excluding PRs if filtered by caller)
+     */
+    listIssues(options: {
+        state: "open" | "closed" | "all";
+    }): Promise<any[]>;
+    /**
+     * Update a pull request's branch with the latest changes from the base branch
+     * This is typically used after merging another PR to keep branches up to date
+     */
+    updatePullRequestBranch(owner: string, repo: string, prNumber: number): Promise<void>;
+    /**
+     * Merge a pull request
+     */
+    mergePullRequest(owner: string, repo: string, prNumber: number, options: {
+        method: "squash" | "merge" | "rebase";
+        commitTitle?: string;
+    }): Promise<boolean>;
+    /**
+     * Get commit status for a SHA
+     */
+    getCommitStatus(owner: string, repo: string, ref: string): Promise<{
+        state: string;
+        statuses: any[];
+    }>;
+}
+/**
+ * Create GitHub API client from environment and config
+ */
+declare function createGitHubAPI(): Promise<GitHubAPI | null>;
+
+/**
+ * GitHub API integration types
+ * Defines data structures for PR metadata and repository information
+ */
+interface RepositoryInfo {
+    owner: string;
+    repo: string;
+    defaultBranch: string;
+    url: string;
+}
+interface PullRequest {
+    number: number;
+    title: string;
+    body: string | null;
+    head: {
+        ref: string;
+        sha: string;
+    };
+    base: {
+        ref: string;
+        sha: string;
+    };
+    state: "open" | "closed" | "merged";
+    labels: Array<{
+        name: string;
+        color: string;
+    }>;
+    draft: boolean;
+    mergeable?: boolean | null;
+    user: {
+        login: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+interface PullRequestDetails extends PullRequest {
+    dependencies: string[];
+    tags: string[];
+    requiredGates: string[];
+    metadata?: {
+        priority?: string;
+        labels?: string[];
+        [key: string]: any;
+    };
+    gateOverrides?: {
+        skip?: string[];
+        required?: string[];
+    };
+}
+interface PRQueryOptions {
+    state?: "open" | "closed" | "all";
+    labels?: string[];
+    query?: string;
+    base?: string;
+    head?: string;
+    sort?: "created" | "updated" | "popularity" | "long-running";
+    direction?: "asc" | "desc";
+    per_page?: number;
+    page?: number;
+}
+/**
+ * GitHub Issue representation
+ */
+interface GitHubIssue {
+    number: number;
+    title: string;
+    body: string | null;
+    state: "open" | "closed";
+    labels: Array<{
+        name: string;
+        color: string;
+    }>;
+    user: {
+        login: string;
+    };
+    assignees: Array<{
+        login: string;
+    }>;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Query options for listing issues
+ */
+interface IssueQueryOptions {
+    state?: "open" | "closed" | "all";
+    labels?: string[];
+    assignee?: string;
+    creator?: string;
+    mentioned?: string;
+    sort?: "created" | "updated" | "comments";
+    direction?: "asc" | "desc";
+    per_page?: number;
+    page?: number;
+}
+/**
+ * GitHub Check Run representation
+ */
+interface GitHubCheckRun {
+    id: number;
+    name: string;
+    status: "queued" | "in_progress" | "completed";
+    conclusion: "success" | "failure" | "neutral" | "cancelled" | "skipped" | "timed_out" | "action_required" | null;
+    started_at: string | null;
+    completed_at: string | null;
+    html_url: string;
+    app: {
+        name: string;
+    };
+}
+/**
+ * Options for querying check runs
+ */
+interface CheckRunsOptions {
+    ref?: string;
+    check_name?: string;
+    status?: "queued" | "in_progress" | "completed";
+    filter?: "latest" | "all";
+}
+
+/**
+ * GitHub API client for PR discovery and metadata extraction
+ * Implements the GitHubClient interface with authentication and rate limiting
+ */
+
+interface GitHubClient {
+    listOpenPRs(options?: PRQueryOptions): Promise<PullRequest[]>;
+    getPRDetails(number: number): Promise<PullRequestDetails>;
+    getPRDependencies(pr: PullRequest): Promise<string[]>;
+    validateRepository(): Promise<RepositoryInfo>;
+    listIssues(options?: IssueQueryOptions): Promise<GitHubIssue[]>;
+    getOctokit(): any;
+    getOwner(): string;
+    getRepo(): string;
+    getPRDiff(prNumber: number): Promise<string>;
+    getPRFiles(prNumber: number): Promise<Array<{
+        path: string;
+        content: string;
+    }>>;
+    getCheckRuns(ref: string, options?: CheckRunsOptions): Promise<GitHubCheckRun[]>;
+    updatePullRequestBranch(prNumber: number): Promise<void>;
+}
+/**
+ * Factory function to create GitHub client with auto-detection of repository info
+ */
+declare function createGitHubClient(options?: {
+    token?: string;
+    owner?: string;
+    repo?: string;
+    octokit?: Octokit;
+}): Promise<GitHubClient>;
+
+/**
+ * Types for file-change analysis and intersection detection
+ */
+/**
+ * Represents a file change in a PR
+ */
+interface FileChange {
+    filename: string;
+    status: "added" | "modified" | "removed" | "renamed";
+    additions: number;
+    deletions: number;
+    changes: number;
+    patch?: string;
+    previousFilename?: string;
+}
+/**
+ * Represents an intersection between PRs on specific files
+ */
+interface FileIntersection {
+    prs: string[];
+    files: string[];
+    confidence: number;
+}
+/**
+ * Heuristic types for dependency detection
+ */
+type HeuristicType = "shared-files" | "directory-proximity" | "test-overlap";
+/**
+ * Dependency suggestion based on file analysis
+ */
+interface DependencySuggestion {
+    from: string;
+    to: string;
+    reason: string;
+    confidence: number;
+    sharedFiles: string[];
+    heuristic?: HeuristicType;
+}
+/**
+ * Conflict prediction based on file overlap
+ */
+interface ConflictPrediction {
+    prs: string[];
+    files: string[];
+    severity: "low" | "medium" | "high";
+    reason: string;
+}
+/**
+ * Complete file analysis result
+ */
+interface FileAnalysisResult {
+    fileIntersections: FileIntersection[];
+    suggestions: DependencySuggestion[];
+    conflicts: ConflictPrediction[];
+}
+
+/**
+ * File-Change Analysis Engine & Intersection Detection
+ * Analyzes file changes across PRs to detect implicit dependencies and suggest merge order
+ */
+
+/**
+ * File analyzer for detecting PR dependencies based on file changes
+ */
+declare class FileAnalyzer {
+    private cache;
+    private octokit;
+    private owner;
+    private repo;
+    constructor(octokit: Octokit, owner: string, repo: string);
+    /**
+     * Fetch file changes for a specific PR
+     */
+    getPRFileChanges(prNumber: number, sha?: string): Promise<FileChange[]>;
+    /**
+     * Build file intersection matrix for multiple PRs
+     */
+    buildIntersectionMatrix(prs: Array<{
+        number: number;
+        name: string;
+        sha?: string;
+    }>): Promise<FileIntersection[]>;
+    /**
+     * Find files that are modified in both PRs
+     */
+    private findSharedFiles;
+    /**
+     * Calculate confidence level for intersection based on change types
+     */
+    private calculateIntersectionConfidence;
+    /**
+     * Predict potential conflicts based on file overlaps
+     */
+    predictConflicts(prs: Array<{
+        number: number;
+        name: string;
+        sha?: string;
+    }>): Promise<ConflictPrediction[]>;
+    /**
+     * Assess severity of potential conflict
+     */
+    private assessConflictSeverity;
+    /**
+     * Generate human-readable conflict reason
+     */
+    private generateConflictReason;
+    /**
+     * Generate dependency suggestions based on file analysis
+     */
+    suggestDependencies(prs: Array<{
+        number: number;
+        name: string;
+        sha?: string;
+    }>): Promise<DependencySuggestion[]>;
+    /**
+     * Generate dependency suggestions using multiple heuristics
+     */
+    suggestDependenciesWithHeuristics(prs: Array<{
+        number: number;
+        name: string;
+        sha?: string;
+    }>): Promise<DependencySuggestion[]>;
+    /**
+     * Heuristic 1: Shared file modifications
+     */
+    private heuristicSharedFiles;
+    /**
+     * Heuristic 2: Directory proximity
+     * PRs modifying files in the same directory structure likely related
+     */
+    private heuristicDirectoryProximity;
+    /**
+     * Heuristic 3: Test overlap
+     * PRs that modify the same test files or test the same modules
+     */
+    private heuristicTestOverlap;
+    /**
+     * Extract directory path from filename
+     */
+    private getDirectoryPath;
+    /**
+     * Check if file is a test file
+     */
+    private isTestFile;
+    /**
+     * Extract module name from test file
+     */
+    private getTestedModule;
+    /**
+     * Perform complete file analysis on a set of PRs
+     */
+    analyzeFiles(prs: Array<{
+        number: number;
+        name: string;
+        sha?: string;
+    }>): Promise<FileAnalysisResult>;
+    /**
+     * Clear the cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        entries: string[];
+    };
+}
+/**
+ * Create a file analyzer for detecting implicit dependencies between PRs
+ *
+ * Factory function that creates a FileAnalyzer instance with caching,
+ * heuristic analysis, and conflict prediction capabilities. The analyzer
+ * uses multiple heuristics to suggest dependencies based on file changes.
+ *
+ * @param octokit - Authenticated Octokit instance for GitHub API access
+ * @param owner - Repository owner (username or organization)
+ * @param repo - Repository name
+ * @returns FileAnalyzer instance with methods for analyzing file changes
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createFileAnalyzer } from "./planner/fileAnalysis.js";
+ * import { Octokit } from "@octokit/rest";
+ *
+ * const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
+ * const analyzer = createFileAnalyzer(octokit, "owner", "repo");
+ *
+ * const analysis = await analyzer.analyzeFiles([
+ *   { number: 101, name: "PR-101", sha: "abc123" },
+ *   { number: 102, name: "PR-102", sha: "def456" }
+ * ]);
+ *
+ * console.log("File intersections:", analysis.fileIntersections);
+ * console.log("Suggestions:", analysis.suggestions);
+ * console.log("Conflicts:", analysis.conflicts);
+ * ```
+ *
+ * @example With caching
+ * ```typescript
+ * const analyzer = createFileAnalyzer(octokit, "owner", "repo");
+ *
+ * // First call fetches from GitHub API
+ * const analysis1 = await analyzer.analyzeFiles(prs);
+ *
+ * // Second call uses cache
+ * const analysis2 = await analyzer.analyzeFiles(prs);
+ *
+ * // Check cache statistics
+ * const stats = analyzer.getCacheStats();
+ * console.log(`Cache size: ${stats.size} entries`);
+ *
+ * // Clear cache if needed
+ * analyzer.clearCache();
+ * ```
+ *
+ * @example Dependency suggestions with heuristics
+ * ```typescript
+ * const analyzer = createFileAnalyzer(octokit, "owner", "repo");
+ *
+ * const prs = [
+ *   { number: 100, name: "PR-100", body: "", sha: "abc" },
+ *   { number: 101, name: "PR-101", body: "", sha: "def" },
+ *   { number: 102, name: "PR-102", body: "", sha: "ghi" }
+ * ];
+ *
+ * const suggestions = await analyzer.suggestDependenciesWithHeuristics(prs);
+ *
+ * // Suggestions are sorted by confidence (high to low)
+ * suggestions.forEach(s => {
+ *   console.log(`${s.from} → ${s.to}`);
+ *   console.log(`  Confidence: ${(s.confidence * 100).toFixed(0)}%`);
+ *   console.log(`  Heuristic: ${s.heuristic}`);
+ *   console.log(`  Reason: ${s.reason}`);
+ *   console.log(`  Shared files: ${s.sharedFiles.join(", ")}`);
+ * });
+ * ```
+ *
+ * @example Conflict prediction
+ * ```typescript
+ * const analyzer = createFileAnalyzer(octokit, "owner", "repo");
+ * const analysis = await analyzer.analyzeFiles(prs);
+ *
+ * const highSeverityConflicts = analysis.conflicts.filter(c => c.severity === "high");
+ *
+ * highSeverityConflicts.forEach(conflict => {
+ *   console.error(`Conflict: ${conflict.prs.join(" vs ")}`);
+ *   console.error(`  Files: ${conflict.files.join(", ")}`);
+ *   console.error(`  Severity: ${conflict.severity}`);
+ *   console.error(`  Reason: ${conflict.reason}`);
+ * });
+ * ```
+ *
+ * @see {@link ../../../docs/diffgraph-planner.md#file-change-heuristics} for heuristic details
+ */
+declare function createFileAnalyzer(octokit: Octokit, owner: string, repo: string): FileAnalyzer;
+
+/**
+ * GitHub-powered plan generation
+ * Auto-discovers PRs and generates plan.json from GitHub metadata
+ */
+
+interface GitHubPlanOptions {
+    query?: string;
+    labels?: string[];
+    excludePRs?: number[];
+    includeDrafts?: boolean;
+    target?: string;
+    policy?: {
+        requiredGates?: string[];
+        maxWorkers?: number;
+    };
+    tierOverrides?: TierOverride[];
+}
+/**
+ * Generate plan from GitHub PRs with automatic dependency resolution
+ */
+declare function generatePlanFromGitHub(client: GitHubClient, options?: GitHubPlanOptions): Promise<Plan>;
+
+/**
+ * Multi-Repo Plan Generation
+ *
+ * Extends GitHub plan generation to support multiple repositories.
+ * This enables merge-weave operations across repos like lex, lexsona, and lexrunner.
+ *
+ * @module
+ */
+
+/**
+ * Repository target for multi-repo discovery
+ */
+interface RepoTarget {
+    owner: string;
+    repo: string;
+    /** Priority for merge ordering (lower = earlier). Default: 1 */
+    priority?: number;
+}
+/**
+ * Options for multi-repo plan generation
+ */
+interface MultiRepoPlanOptions {
+    query?: string;
+    labels?: string[];
+    excludePRs?: number[];
+    includeDrafts?: boolean;
+    target?: string;
+    policy?: {
+        requiredGates?: string[];
+        maxWorkers?: number;
+    };
+    tierOverrides?: TierOverride[];
+    /** GitHub token for authentication */
+    githubToken?: string;
+}
+/**
+ * Generate plan from multiple GitHub repositories
+ *
+ * This function:
+ * 1. Discovers PRs from each repository
+ * 2. Resolves cross-repo dependencies (owner/repo#123 format)
+ * 3. Combines into a single plan with proper ordering
+ *
+ * @example
+ * ```typescript
+ * const plan = await generateMultiRepoPlan([
+ *   { owner: "Guffawaffle", repo: "lex", priority: 1 },
+ *   { owner: "Guffawaffle", repo: "lexsona", priority: 2 },
+ *   { owner: "Guffawaffle", repo: "lexrunner", priority: 3 },
+ * ], {
+ *   labels: ["ready-to-merge"],
+ *   policy: { requiredGates: ["lint", "test"] }
+ * });
+ * ```
+ */
+declare function generateMultiRepoPlan(repos: RepoTarget[], options?: MultiRepoPlanOptions): Promise<Plan>;
+
+/**
+ * Git operations for merge pyramid execution
+ * Implements weave strategy and conflict detection
+ */
+
+interface MergeOperation {
+    item: PlanItem;
+    targetBranch: string;
+    strategy: "rebase-weave" | "merge-weave" | "squash-weave";
+}
+interface WeaveResult {
+    success: boolean;
+    item: PlanItem;
+    conflicts?: string[];
+    sha?: string;
+    message?: string;
+}
+interface WeaveExecutionResult {
+    operations: WeaveResult[];
+    successful: number;
+    failed: number;
+    conflicts: number;
+    totalOperations: number;
+}
+/**
+ * Git operations manager for merge pyramid execution
+ */
+declare class GitOperations {
+    private git;
+    private workingDir;
+    constructor(workingDir?: string);
+    /**
+     * Check if git repository is in a clean state
+     */
+    isClean(): Promise<boolean>;
+    /**
+     * Get current branch name
+     */
+    getCurrentBranch(): Promise<string>;
+    /**
+     * Get commit SHA for a branch
+     */
+    getBranchHead(branchName: string): Promise<string | null>;
+    /**
+     * Get list of conflicted files using git diff
+     * This captures files with unmerged status (UU, AA, DU, UD, etc.)
+     */
+    getConflictedFiles(): Promise<string[]>;
+    /**
+     * Create and checkout a new branch for weave operations
+     */
+    createWeaveBranch(baseBranch?: string): Promise<string>;
+    /**
+     * Execute a single merge operation with conflict detection
+     */
+    executeMergeOperation(operation: MergeOperation): Promise<WeaveResult>;
+    /**
+     * Execute merge pyramid with dependency ordering
+     */
+    executeWeave(plan: Plan, levels: string[][], progressReporter?: ProgressReporter): Promise<WeaveExecutionResult>;
+    /**
+     * Rollback to previous state
+     */
+    rollback(targetBranch: string): Promise<void>;
+    /**
+     * Clean up integration branches
+     */
+    cleanup(branchPattern?: string): Promise<void>;
+    /**
+     * Get current HEAD commit SHA
+     */
+    getCurrentHead(): Promise<string>;
+    /**
+     * Get diff between two commits
+     */
+    getDiff(baseSha: string, headSha: string): Promise<string>;
+    /**
+     * Reset repository to a specific commit (hard reset)
+     */
+    resetHard(targetSha: string): Promise<void>;
+}
+/**
+ * Create git operations manager
+ */
+declare function createGitOperations(workingDir?: string): GitOperations;
+
+/**
+ * Configuration bootstrapping and workspace setup
+ * Provides automatic configuration discovery and fallback mechanisms
+ */
+interface BootstrapConfig {
+    profileDir: string;
+    hasConfiguration: boolean;
+    missingFiles: string[];
+    suggestions: string[];
+}
+/**
+ * Bootstrap workspace configuration with intelligent defaults
+ *
+ * @param baseDir - Base directory for profile resolution
+ * @param profileDirFlag - Optional profile directory override (from CLI --profile-dir)
+ */
+declare function bootstrapWorkspace(baseDir?: string, profileDirFlag?: string): BootstrapConfig;
+/**
+ * Detect project type and suggest appropriate templates
+ */
+declare function detectProjectType(baseDir?: string): string;
+/**
+ * Get environment-specific configuration suggestions
+ */
+declare function getEnvironmentSuggestions(): string[];
+
+/**
+ * Guided workflow response types for MCP server
+ *
+ * These types enable context-aware workflow guidance without modifying
+ * existing tool response structures. Per LPR-037 and Guff's Option 1 approach.
+ */
+/**
+ * Workflow action that can be taken in the current phase
+ */
+interface WorkflowAction {
+    /** MCP tool command name (e.g., 'gates_run', 'plan_validate') */
+    command: string;
+    /** Human-readable description of what this action does */
+    description: string;
+    /** Whether this action must be performed before proceeding */
+    required: boolean;
+}
+/**
+ * Common issue and its resolution in a workflow phase
+ */
+interface CommonIssue {
+    /** Symptom or error message pattern */
+    symptom: string;
+    /** Recommended solution or next step */
+    solution: string;
+}
+/**
+ * Guided workflow response from the workflow_guide tool
+ */
+interface WorkflowGuide {
+    /** Current workflow phase identifier */
+    phase: string;
+    /** Available next steps in this phase */
+    nextSteps: WorkflowAction[];
+    /** Common issues that occur in this phase */
+    commonIssues: CommonIssue[];
+    /** Link to relevant documentation */
+    documentation?: string;
+    /** Whether agent can proceed to next phase */
+    canProceed: boolean;
+    /** Optional recommendation for the most common next action */
+    recommendedAction?: string;
+}
+
+/**
+ * Workflow state machine for guided MCP workflows
+ *
+ * Tracks workflow phases and valid transitions for deterministic guidance.
+ * Per LPR-037 implementation.
+ */
+
+/**
+ * Valid workflow phases
+ */
+type WorkflowPhase = "initial" | "post-plan-creation" | "post-gates-run" | "pre-merge" | "post-merge" | "error-recovery";
+/**
+ * Create a workflow guide for a given phase without managing state
+ *
+ * This is a stateless helper for the MCP server that doesn't require
+ * maintaining a state machine instance.
+ */
+declare function createWorkflowGuide(phase: WorkflowPhase): WorkflowGuide;
+
+declare function main(argv?: string[]): Promise<void>;
+
+export { ExecutionState, GitHubAPI, MergeEligibilityEvaluator, type MultiRepoPlanOptions, type RepoTarget, bootstrapWorkspace, canonicalJSONStringify, computeMergeOrder, createFileAnalyzer, createGitHubAPI, createGitHubClient, createGitOperations, createRunManager, createWorkflowGuide, detectProjectType, executeGatesWithPolicy, generateGitHubSnapshot, generateMultiRepoPlan, generatePlan, generatePlanFromGitHub, generateSnapshot, getEnvironmentSuggestions, healthChecker, initLocalOverlay, loadInputs, loadPlan, main, resolveProfile };