opencode-swarm 6.5.0 → 6.8.0

package/README.md

@@ -1,9 +1,9 @@
 <p align="center">
-   <img src="https://img.shields.io/badge/version-6.3.0-blue" alt="Version">
-  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
-  <img src="https://img.shields.io/badge/opencode-plugin-purple" alt="OpenCode Plugin">
-  <img src="https://img.shields.io/badge/agents-9-orange" alt="Agents">
-  <img src="https://img.shields.io/badge/tests-1391-brightgreen" alt="Tests">
+   <img src="https://img.shields.io/badge/version-6.8.0-blue" alt="Version">
+   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+   <img src="https://img.shields.io/badge/opencode-plugin-purple" alt="OpenCode Plugin">
+   <img src="https://img.shields.io/badge/agents-9-orange" alt="Agents">
+   <img src="https://img.shields.io/badge/tests-4008-brightgreen" alt="Tests">
 </p>
 
 <h1 align="center">🐝 OpenCode Swarm</h1>
@@ -352,6 +352,9 @@ Per-agent profiles allow fine-grained overrides:
 | `/swarm benchmark` | Performance benchmarks |
 | `/swarm retrieve [id]` | Retrieve auto-summarized tool outputs |
 | `/swarm reset --confirm` | Clear swarm state files |
+| `/swarm preflight` | Run phase preflight checks (v6.7) |
+| `/swarm config doctor [--fix] [--restore <id>]` | Config validation with optional auto-fix (v6.7) |
+| `/swarm sync-plan` | Force plan.md regeneration from plan.json (v6.7) |
 
 ---
 
@@ -380,12 +383,53 @@ Per-agent profiles allow fine-grained overrides:
   "review_passes": {
     "always_security_review": false,
     "security_globs": ["**/*auth*", "**/*crypto*", "**/*session*", "**/*token*"]
+  },
+  "automation": {
+    "mode": "manual",
+    "capabilities": {
+      "plan_sync": false,
+      "phase_preflight": false,
+      "config_doctor_on_startup": false,
+      "config_doctor_autofix": false,
+      "evidence_auto_summaries": false,
+      "decision_drift_detection": false
+    }
   }
 }
 ```
 
 Save to `~/.config/opencode/opencode-swarm.json` or `.opencode/swarm.json` in your project root. Project config merges over global config via deep merge — partial overrides do not clobber unspecified fields.
 
+### Automation (v6.7)
+
+**Default mode: `manual`** (no background automation). Enable automation features via `automation` config:
+
+```json
+{
+  "automation": {
+    "mode": "hybrid",
+    "capabilities": {
+      "plan_sync": true,
+      "config_doctor_on_startup": true,
+      "evidence_auto_summaries": true
+    }
+  }
+}
+```
+
+**Automation modes:**
+- `manual` - No background automation (default)
+- `hybrid` - Background automation for safe ops, manual for sensitive ones
+- `auto` - Full background automation (target state)
+
+**Per-feature flags (all default `false`):**
+- `plan_sync` - Auto-regenerate plan.md from plan.json when out of sync
+- `phase_preflight` - Phase-boundary validation before agent execution
+- `config_doctor_on_startup` - Config validation on plugin initialization
+- `config_doctor_autofix` - Auto-fix mode for Config Doctor (requires explicit opt-in)
+- `evidence_auto_summaries` - Auto-generate evidence summaries
+- `decision_drift_detection` - Detect drift between planned and actual decisions
+
 ### Disabling Agents
 
 ```json
@@ -423,7 +467,7 @@ The installer auto-configures `opencode.json` to include the plugin. Manual conf
 
 ## Testing
 
-2031 tests across 78 files. Unit, integration, adversarial, and smoke. Covers config schemas, all agent prompts, all hooks, all tools, all commands, guardrail circuit breaker, race conditions, invocation window isolation, multi-invocation state, security category classification, and evidence validation.
+4008 tests across 136 files. Unit, integration, adversarial, and smoke. Covers config schemas, all agent prompts, all hooks, all tools, all commands, guardrail circuit breaker, race conditions, invocation window isolation, multi-invocation state, security category classification, evidence validation, background workers, phase-monitor hooks, and evidence-summary automation.
 
 ```bash
 bun test
@@ -483,6 +527,8 @@ Five tools that improve planning quality and post-phase validation:
 - [Architecture Deep Dive](docs/architecture.md)
 - [Design Rationale](docs/design-rationale.md)
 - [Installation Guide](docs/installation.md)
+- [Linux + Native Windows + Docker Desktop Install Guide](docs/installation-linux-docker.md)
+- [LLM Operator Install Guide](docs/installation-llm-operator.md)
 
 ---
 

package/dist/__tests__/security-adversarial.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/background/circuit-breaker.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Circuit Breaker + Loop Protection Primitives
+ *
+ * Provides fault tolerance and infinite loop prevention for background automation.
+ */
+/** Circuit breaker states */
+export type CircuitBreakerState = 'closed' | 'open' | 'half-open';
+/** Circuit breaker configuration */
+export interface CircuitBreakerConfig {
+    /** Number of failures before opening circuit */
+    failureThreshold: number;
+    /** Time in ms to wait before attempting reset */
+    resetTimeoutMs: number;
+    /** Number of success calls needed to close from half-open */
+    successThreshold: number;
+    /** Timeout for individual calls (0 = no timeout) */
+    callTimeoutMs: number;
+}
+/** Circuit breaker events */
+export interface CircuitBreakerEvents {
+    opened: {
+        timestamp: number;
+        failureCount: number;
+    };
+    closed: {
+        timestamp: number;
+        successCount: number;
+    };
+    'half-open': {
+        timestamp: number;
+    };
+    callSuccess: {
+        duration: number;
+    };
+    callFailure: {
+        error: unknown;
+        duration: number;
+    };
+}
+export type CircuitBreakerEventType = keyof CircuitBreakerEvents;
+/**
+ * Circuit Breaker Implementation
+ *
+ * Prevents cascading failures by stopping requests when the circuit is open.
+ * States:
+ * - closed: Normal operation, requests pass through
+ * - open: Circuit is open, requests fail fast
+ * - half-open: Testing if service recovered
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureTime?;
+    private readonly config;
+    private readonly name;
+    private readonly onStateChange?;
+    constructor(name: string, config?: Partial<CircuitBreakerConfig>, onStateChange?: (eventType: string, event: unknown) => void);
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitBreakerState;
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Execute with timeout
+     */
+    private executeWithTimeout;
+    /**
+     * Record a successful call
+     */
+    private recordSuccess;
+    /**
+     * Record a failed call
+     */
+    private recordFailure;
+    /**
+     * Transition to a new state
+     */
+    private transitionTo;
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset(): void;
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats(): {
+        state: CircuitBreakerState;
+        failureCount: number;
+        successCount: number;
+        lastFailureTime?: number;
+    };
+}
+/**
+ * Loop Protection for preventing infinite automation loops
+ *
+ * Tracks operation history and detects potential infinite loops.
+ */
+export interface LoopProtectionConfig {
+    /** Maximum times an operation can be attempted */
+    maxIterations: number;
+    /** Time window in ms to track iterations */
+    timeWindowMs: number;
+    /** Unique key for the operation being protected */
+    operationKey: string;
+}
+/**
+ * Loop Protection Implementation
+ *
+ * Prevents infinite loops by tracking operation frequency.
+ */
+export declare class LoopProtection {
+    private records;
+    private readonly config;
+    private readonly onLoopDetected?;
+    constructor(config: LoopProtectionConfig, onLoopDetected?: (key: string, count: number) => void);
+    /**
+     * Record an iteration attempt
+     * Returns false if max iterations exceeded
+     */
+    recordAttempt(key?: string): boolean;
+    /**
+     * Check if operation is allowed without recording
+     */
+    canProceed(key?: string): boolean;
+    /**
+     * Get remaining iterations allowed
+     */
+    getRemainingIterations(key?: string): number;
+    /**
+     * Reset tracking for an operation
+     */
+    reset(key?: string): void;
+    /**
+     * Reset all tracking
+     */
+    resetAll(): void;
+    /**
+     * Get current iteration count
+     */
+    getIterationCount(key?: string): number;
+    /**
+     * Get all operation keys being tracked
+     */
+    getTrackedOperations(): string[];
+}

package/dist/background/event-bus.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Typed Event Bus for Internal Automation Events
+ *
+ * Provides a type-safe event system for background automation.
+ * Events flow through the system without external dependencies.
+ */
+/** Automation event types */
+export type AutomationEventType = 'queue.item.enqueued' | 'queue.item.dequeued' | 'queue.item.completed' | 'queue.item.failed' | 'queue.item.retry scheduled' | 'worker.started' | 'worker.stopped' | 'worker.error' | 'circuit.breaker.opened' | 'circuit.breaker.half-open' | 'circuit.breaker.closed' | 'loop.protection.triggered' | 'automation.started' | 'automation.stopped' | 'preflight.requested' | 'preflight.triggered' | 'preflight.skipped' | 'preflight.completed' | 'phase.boundary.detected' | 'phase.status.checked' | 'task.completed' | 'evidence.summary.generated' | 'evidence.summary.error';
+/** Base automation event */
+export interface AutomationEvent<T = unknown> {
+    type: AutomationEventType;
+    timestamp: number;
+    payload: T;
+    source?: string;
+}
+/** Event listener type */
+export type EventListener<T = unknown> = (event: AutomationEvent<T>) => void | Promise<void>;
+/**
+ * Type-safe event bus for automation events
+ */
+export declare class AutomationEventBus {
+    private listeners;
+    private eventHistory;
+    private readonly maxHistorySize;
+    constructor(options?: {
+        maxHistorySize?: number;
+    });
+    /**
+     * Subscribe to an event type
+     */
+    subscribe<T>(type: AutomationEventType, listener: EventListener<T>): () => void;
+    /**
+     * Publish an event to all subscribers
+     */
+    publish<T>(type: AutomationEventType, payload: T, source?: string): Promise<void>;
+    /**
+     * Get recent event history
+     */
+    getHistory(types?: AutomationEventType[]): AutomationEvent[];
+    /**
+     * Clear event history
+     */
+    clearHistory(): void;
+    /**
+     * Get listener count for an event type
+     */
+    getListenerCount(type: AutomationEventType): number;
+    /**
+     * Check if any listeners exist for a type
+     */
+    hasListeners(type: AutomationEventType): boolean;
+}
+/**
+ * Get or create the global event bus instance
+ */
+export declare function getGlobalEventBus(): AutomationEventBus;
+/**
+ * Reset the global event bus (for testing)
+ */
+export declare function resetGlobalEventBus(): void;

package/dist/background/evidence-summary-integration.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Evidence Summary Background Integration
+ *
+ * Wires the evidence summary service to background automation:
+ * - Subscribes to preflight and phase boundary events
+ * - Generates evidence summaries automatically
+ * - Persists artifacts under .swarm/ for GUI consumption
+ * - Respects feature flags (evidence_auto_summaries) with default-off safety
+ */
+import type { AutomationConfig } from '../config/schema';
+import { type EvidenceSummaryArtifact } from '../services/evidence-summary-service';
+/** Evidence summary integration configuration */
+export interface EvidenceSummaryIntegrationConfig {
+    /** Automation configuration for feature flag gating */
+    automationConfig: AutomationConfig;
+    /** Directory to run evidence analysis in */
+    directory: string;
+    /** Swarm directory for persisting summary artifacts */
+    swarmDir: string;
+    /** Filename for the summary artifact (default: evidence-summary.json) */
+    summaryFilename?: string;
+}
+/** Event types that can trigger evidence summary generation */
+export type EvidenceSummaryTriggerEvent = 'preflight.completed' | 'phase.boundary.detected' | 'phase.status.checked' | 'task.completed';
+/** Payload for evidence summary trigger events */
+export interface EvidenceSummaryTriggerPayload {
+    trigger: EvidenceSummaryTriggerEvent;
+    phase: number;
+    reason: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Evidence Summary Integration
+ *
+ * Automatically generates and persists evidence summaries on relevant events.
+ */
+export declare class EvidenceSummaryIntegration {
+    private readonly config;
+    private readonly eventBus;
+    private unsubscribes;
+    constructor(config: EvidenceSummaryIntegrationConfig);
+    /**
+     * Check if auto-summaries are enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Initialize the integration by subscribing to trigger events
+     * Only subscribes if enabled via feature flags
+     */
+    initialize(): void;
+    /**
+     * Subscribe to an event type
+     */
+    private subscribeToEvent;
+    /**
+     * Generate and persist evidence summary
+     */
+    generateSummary(phase: number, trigger: EvidenceSummaryTriggerEvent): Promise<EvidenceSummaryArtifact | null>;
+    /**
+     * Manually trigger summary generation (for CLI or testing)
+     */
+    triggerManual(phase?: number): Promise<EvidenceSummaryArtifact | null>;
+    /**
+     * Cleanup subscriptions
+     */
+    cleanup(): void;
+}
+/**
+ * Create evidence summary integration
+ *
+ * Factory function that creates and optionally initializes the integration.
+ */
+export declare function createEvidenceSummaryIntegration(config: EvidenceSummaryIntegrationConfig, autoInitialize?: boolean): EvidenceSummaryIntegration;

package/dist/background/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Background Automation Framework
+ *
+ * Provides infrastructure for v6.7 background-first automation:
+ * - Typed event bus for internal automation events
+ * - Lightweight in-process queue with priorities and retry metadata
+ * - Worker lifecycle manager (start/stop/register handlers)
+ * - Circuit breaker + loop protection primitives
+ * - Phase-boundary trigger detection and preflight request plumbing
+ * - Passive status artifact writer for GUI visibility
+ *
+ * Gated behind Task 5.2 automation feature flags and default-off behavior.
+ */
+export { CircuitBreaker, type CircuitBreakerConfig, type CircuitBreakerState, LoopProtection, } from './circuit-breaker';
+export { type AutomationEvent, AutomationEventBus, type AutomationEventType, } from './event-bus';
+export { createEvidenceSummaryIntegration, type EvidenceSummaryIntegrationConfig, type EvidenceSummaryTriggerEvent, type EvidenceSummaryTriggerPayload, } from './evidence-summary-integration';
+export { type AutomationFrameworkConfig, BackgroundAutomationManager, createAutomationManager, } from './manager';
+export { PlanSyncWorker, type PlanSyncWorkerOptions, type PlanSyncWorkerStatus, } from './plan-sync-worker';
+export { AutomationQueue, type QueueItem, type QueuePriority, type RetryMetadata, } from './queue';
+export { AutomationStatusArtifact, type AutomationStatusSnapshot, } from './status-artifact';
+export { type PhaseBoundaryResult, PhaseBoundaryTrigger, type PreflightHandler, type PreflightRequest, type PreflightRequestPayload, type PreflightTriggerConfig, type PreflightTriggerEventType, PreflightTriggerManager, } from './trigger';
+export { type WorkerHandler, WorkerManager, type WorkerRegistration, } from './worker';

package/dist/background/manager.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Background Automation Manager
+ *
+ * Main entry point for the background automation framework.
+ * Handles feature flag gating and orchestrates all components.
+ */
+import type { AutomationConfig } from '../config/schema';
+import { CircuitBreaker, type CircuitBreakerConfig, LoopProtection, type LoopProtectionConfig } from './circuit-breaker';
+import { type AutomationEvent, type AutomationEventType } from './event-bus';
+import { AutomationQueue } from './queue';
+import { WorkerManager, type WorkerRegistration } from './worker';
+/** Framework configuration */
+export interface AutomationFrameworkConfig {
+    /** Enable/disable the entire framework */
+    enabled: boolean;
+    /** Max queue size */
+    maxQueueSize?: number;
+    /** Max retries for failed items */
+    maxRetries?: number;
+    /** Circuit breaker config */
+    circuitBreaker?: Partial<CircuitBreakerConfig>;
+    /** Loop protection config */
+    loopProtection?: Partial<LoopProtectionConfig>;
+}
+/**
+ * Background Automation Manager
+ *
+ * Provides a unified interface for background automation with feature flag gating.
+ * All components are optional and only activated when enabled.
+ */
+export declare class BackgroundAutomationManager {
+    private readonly config;
+    private readonly eventBus;
+    private readonly workerManager;
+    private readonly queues;
+    private readonly circuitBreakers;
+    private readonly loopProtections;
+    private isInitialized;
+    private isRunning;
+    constructor(config: AutomationFrameworkConfig);
+    /**
+     * Initialize the automation framework
+     * Only performs work if enabled
+     */
+    initialize(): void;
+    /**
+     * Start the automation framework
+     */
+    start(): void;
+    /**
+     * Stop the automation framework
+     */
+    stop(): void;
+    /**
+     * Check if framework is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Check if framework is running
+     */
+    isActive(): boolean;
+    /**
+     * Create or get a named queue
+     */
+    getOrCreateQueue<T>(name: string): AutomationQueue<T>;
+    /**
+     * Register a worker with the framework
+     */
+    registerWorker(registration: WorkerRegistration): void;
+    /**
+     * Start a specific worker
+     */
+    startWorker(name: string): boolean;
+    /**
+     * Stop a specific worker
+     */
+    stopWorker(name: string): boolean;
+    /**
+     * Get or create a circuit breaker
+     */
+    getOrCreateCircuitBreaker(name: string): CircuitBreaker;
+    /**
+     * Get or create loop protection
+     */
+    getOrCreateLoopProtection(operationKey: string): LoopProtection;
+    /**
+     * Subscribe to automation events
+     */
+    subscribe<T>(type: AutomationEventType, listener: (event: AutomationEvent<T>) => void | Promise<void>): () => void;
+    /**
+     * Publish an event to the automation event bus
+     */
+    publish<T>(type: AutomationEventType, payload: T, source?: string): Promise<void>;
+    /**
+     * Get framework statistics
+     */
+    getStats(): {
+        enabled: boolean;
+        initialized: boolean;
+        running: boolean;
+        queues: Record<string, ReturnType<AutomationQueue['getStats']>>;
+        workers: Record<string, ReturnType<WorkerManager['getStats']>>;
+        circuitBreakers: Record<string, ReturnType<CircuitBreaker['getStats']>>;
+        loopProtections: string[];
+    };
+    /**
+     * Reset the framework (for testing)
+     */
+    reset(): void;
+}
+/**
+ * Get or create the global automation manager
+ */
+export declare function getAutomationManager(config?: AutomationFrameworkConfig): BackgroundAutomationManager;
+/**
+ * Initialize automation manager from plugin config
+ */
+export declare function createAutomationManager(automationConfig: AutomationConfig | undefined): BackgroundAutomationManager;
+/**
+ * Reset the global manager (for testing)
+ */
+export declare function resetAutomationManager(): void;

package/dist/background/plan-sync-worker.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Plan Sync Worker
+ *
+ * Watches .swarm/plan.json for changes and syncs plan.md accordingly.
+ * Uses fs.watch with polling fallback for cross-platform reliability.
+ */
+/** Configuration options for PlanSyncWorker */
+export interface PlanSyncWorkerOptions {
+    /** Directory containing .swarm folder (defaults to cwd) */
+    directory?: string;
+    /** Debounce delay in ms (default: 300ms) */
+    debounceMs?: number;
+    /** Polling interval in ms when fs.watch fails (default: 2000ms) */
+    pollIntervalMs?: number;
+    /** Sync operation timeout in ms (default: 30000ms) - prevents runaway hangs */
+    syncTimeoutMs?: number;
+    /** Called on sync completion (success or failure) */
+    onSyncComplete?: (success: boolean, error?: Error) => void;
+}
+/** Worker status */
+export type PlanSyncWorkerStatus = 'stopped' | 'starting' | 'running' | 'stopping';
+/**
+ * Plan Sync Worker
+ *
+ * Standalone class that watches plan.json and triggers plan.md regeneration.
+ * Handles cross-platform fs.watch reliability issues with polling fallback.
+ */
+export declare class PlanSyncWorker {
+    private readonly directory;
+    private readonly debounceMs;
+    private readonly pollIntervalMs;
+    private readonly syncTimeoutMs;
+    private readonly onSyncComplete?;
+    private status;
+    private watcher;
+    private pollTimer;
+    private debounceTimer;
+    /** In-flight sync lock */
+    private syncing;
+    /** Pending sync requested while in-flight */
+    private pendingSync;
+    /** Last known plan.json stat to detect changes */
+    private lastStat;
+    /** Track if we've been disposed */
+    private disposed;
+    constructor(options?: PlanSyncWorkerOptions);
+    /**
+     * Get the swarm directory path
+     */
+    private getSwarmDir;
+    /**
+     * Get the plan.json file path
+     */
+    private getPlanJsonPath;
+    /**
+     * Start watching for plan.json changes
+     */
+    start(): void;
+    /**
+     * Stop watching and clean up resources
+     */
+    stop(): void;
+    /**
+     * Dispose of the worker - stop and prevent further use
+     */
+    dispose(): void;
+    /**
+     * Get current status
+     */
+    getStatus(): PlanSyncWorkerStatus;
+    /**
+     * Check if worker is running
+     */
+    isRunning(): boolean;
+    /**
+     * Initialize the stat tracking for change detection
+     */
+    private initializeStat;
+    /**
+     * Set up native fs.watch on the swarm directory
+     * Returns true if successful, false if unavailable
+     */
+    private setupNativeWatcher;
+    /**
+     * Set up polling fallback
+     */
+    private setupPolling;
+    /**
+     * Check for changes via polling
+     */
+    private pollCheck;
+    /**
+     * Debounced sync - prevents rapid successive syncs
+     */
+    private debouncedSync;
+    /**
+     * Clear debounce timer
+     */
+    private clearDebounce;
+    /**
+     * Trigger a sync operation with overlap protection
+     */
+    private triggerSync;
+    /**
+     * Execute the sync operation with timeout protection
+     */
+    private executeSync;
+    /**
+     * Safely invoke onSyncComplete callback, catching any exceptions
+     * to prevent callback errors from affecting worker stability
+     */
+    private safeCallback;
+    /**
+     * Wrap a promise with a timeout
+     */
+    private withTimeout;
+}