opencode-orchestrator 1.2.62 → 1.2.67

package/README.md

@@ -8,8 +8,12 @@
 
   [![MIT License](https://img.shields.io/badge/license-MIT-red.svg)](LICENSE)
   [![npm](https://img.shields.io/npm/v/opencode-orchestrator.svg)](https://www.npmjs.com/package/opencode-orchestrator)
+  <!-- VERSION:START -->
+  **Version:** `1.2.67`
+  <!-- VERSION:END -->
 </div>
 
+
 ---
 
 ## ⚡ Quick Start
@@ -18,61 +22,184 @@
 npm install -g opencode-orchestrator
 ```
 
+Install hooks are source-checkout safe, prefer `opencode.jsonc` when present, preserve sibling plugin entries, and skip automatic config mutation in CI environments.
+
 Inside an OpenCode environment:
 ```bash
 /task "Implement a new authentication module with JWT and audit logs"
 ```
 
+
 ---
 
 ## 🚀 Engine Workflow
 
-OpenCode Orchestrator utilizes a **Hub-and-Spoke Topology** with **Work-Stealing Queues** to execute complex engineering tasks through parallel, context-isolated sessions.
-
-```text
-            [ User Task ]
-                    │
-         ┌──────────▼──────────┐
-         │     COMMANDER       │◄───────────┐ (Loop Phase)
-         │  [Work-Stealing]    │            │
-         └────────┬────────────┘            │
-                  │                         │
-         ┌────────▼──────────┐              │
-         │      PLANNER      │ (Todo.md)    │
-         │  [Session Pool]   │              │
-         └────────┬──────────┘              │
-                  │                         │ (MVCC Atomic Sync)
-     ┌─────────────┼──────────────┐          │
-     ▼     (Isolated Session Pool)▼          │
-[ Session A ] [ Session B ] [ Session C ]   │
-[  Worker   ] [  Worker   ] [  Reviewer ]   │
-│ [Memory   ] │ [Memory   ] │ [Memory    │  │
-│  Pooling] │ │  Pooling] │ │  Pooling]  │  │
-     └─────────────┬──────────────┘          │
-                  │                         │
-         ┌────────▼──────────┐              │
-         │   MSVP MONITOR    │──────────────┘
-         │ [Adaptive Poll]   │
-         └────────┬──────────┘
-                  │
-         ┌────────▼──────────┐
-         │ QUALITY ASSURANCE │
-         └────────┬──────────┘
-                  │
-            [ ✨COMPLETED ]
+**Hub-and-Spoke Architecture** with Work-Stealing Queues for parallel, context-isolated task execution.
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                           USER INPUT /task "..."                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+                                         │
+                                         ▼
+╔══════════════════════════════════════════════════════════════════════════════╗
+║  ┌─────────────────────────────────────────────────────────────────────────┐ ║
+║  │                            C O M M A N D E R                           │ ║
+║  │                    [ Mission Analysis & Delegation ]                    │ ║
+║  │                                                                          │ ║
+║  │    • Interprets user intent    • Coordinates multi-agent workflow      │ ║
+║  │    • Monitors progress          • Manages work-stealing queues         │ ║
+║  └─────────────────────────────────────────────────────────────────────────┘ ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+                                         │
+                         ┌───────────────┼───────────────┐
+                         ▼               ▼               ▼
+╔═════════════════╗  ╔═════════════════╗  ╔═════════════════╗
+║   P L A N N E R ║  ║     W O R K E R ║  ║    W O R K E R   ║
+║  [Architect]    ║  ║  [Implementer]  ║  ║  [Implementer]   ║
+║                 ║  ║                 ║  ║                 ║
+║  • Dependency   ║  ║  • File coding ║  ║  • File coding  ║
+║    analysis     ║  ║  • TDD workflow ║  ║  • TDD workflow ║
+║  • Roadmap gen ║  ║  • Documentation║  ║  • Documentation║
+║  • TODO.md      ║  ║                 ║  ║                 ║
+╚═════════════════╝  ╚═════════════════╝  ╚═════════════════╝
+         │                   │                     │
+         │    ┌──────────────┼─────────────────────┘
+         │    │              │
+         ▼    ▼              ▼
+╔══════════════════════════════════════╗
+║         SESSION POOL (MVCC Sync)   ║
+║   ┌─────────────────────────────────┐ ║
+║   │  Object Pool │ Buffer Pool      │ ║
+║   │  String Pool │ Connection Pool  │ ║
+║   └─────────────────────────────────┘ ║
+╚══════════════════════════════════════╝
+         │
+         ▼
+╔══════════════════════════════════════╗
+║       MSVP MONITOR / REVIEWER       ║
+║  ┌─────────────────────────────────┐ ║
+║  │  • Adaptive polling (500ms-5s) │ ║
+║  │  • Stability detection         │ ║
+║  │  • Unit test verification      │ ║
+║  └─────────────────────────────────┘ ║
+╚══════════════════════════════════════╝
+                 │
+                 ▼
+        ┌────────────────┐
+        │  ✨ COMPLETED  │
+        └────────────────┘
+```
+
+---
+
+## 🏗️ Architecture Layers
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           PRESENTATION LAYER                                │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
+│  │ Task Toast  │  │ Progress    │  │ Notification│  │ Mission Summary │  │
+│  │ Manager     │  │ Notifier    │  │ Manager     │  │ Display         │  │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────────┘  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                           BUSINESS LOGIC LAYER                              │
+│  ┌───────────────────────────────────────────────────────────────────────┐  │
+│  │                    Parallel Agent Orchestration                        │  │
+│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────────┐  │  │
+│  │  │ Commander  │  │  Planner   │  │  Worker    │  │   Reviewer     │  │  │
+│  │  │   Agent    │  │   Agent    │  │   Agent    │  │     Agent      │  │  │
+│  │  └────────────┘  └────────────┘  └────────────┘  └────────────────┘  │  │
+│  └───────────────────────────────────────────────────────────────────────┘  │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐│
+│  │ Concurrency     │  │   Task Store   │  │    Hook System              ││
+│  │ Controller      │  │   (In-Memory)  │  │  [Early/Normal/Late Phases] ││
+│  └─────────────────┘  └─────────────────┘  └─────────────────────────────┘│
+├─────────────────────────────────────────────────────────────────────────────┤
+│                           INFRASTRUCTURE LAYER                              │
+│  ┌────────────────┐  ┌────────────────┐  ┌────────────────────────────┐  │
+│  │ Session Pool   │  │ Work-Stealing  │  │    Memory Pools           │  │
+│  │ [5 per agent]  │  │ [Chase-Lev]    │  │  ┌──────┐ ┌──────┐ ┌─────┐│  │
+│  │ [10 reuse max] │  │ [LIFO/FIFO]    │  │  │Object│ │String│ │Buffer││  │
+│  └────────────────┘  └────────────────┘  │  │ 200  │ │ intern│ │ 4KB ││  │
+│                                          │  └──────┘ └──────┘ └─────┘│  │
+│  ┌────────────────┐  ┌────────────────┐  └────────────────────────────┘  │
+│  │ MVCC State     │  │ Circuit Breaker │  ┌────────────────────────────┐  │
+│  │ [Atomic Sync]  │  │ [5 failures→open│  │ Rust Connection Pool     │  │
+│  │                │  │  [2 success→close│ │ [4 processes, 30s idle]   │  │
+│  └────────────────┘  └────────────────┘  └────────────────────────────┘  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                           SAFETY LAYER                                      │
+│  ┌────────────────┐  ┌────────────────┐  ┌─────────────────────────────┐ │
+│  │ RAII Pattern   │  │ Shutdown       │  │ Auto-Recovery               │ │
+│  │ [Zero Leaks]   │  │ Manager        │  │ [Exponential Backoff]       │ │
+│  │                │  │ [5s timeout]   │  │ [Rate limit handling]       │ │
+│  └────────────────┘  └────────────────┘  └─────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🧪 Test Utilities
+
+Reusable test helpers keep filesystem, task, and process-heavy flows deterministic:
+
+```
+tests/harness/
+├── fixture.ts          Disposable tmpdir utilities
+│   ├── tmpdir()        async disposable with cleanup
+│   ├── tmpdirSync()    sync disposable with cleanup  
+│   ├── createMockFs()  In-memory fs mock
+│   └── waitFor()       Async condition waiter
+│
+├── builders.ts         Factory functions for test objects
+│   ├── createParallelTask()    Build ParallelTask instances
+│   ├── createBackgroundTask()  Build BackgroundTask instances
+│   └── createTodo()            Build Todo instances
+│
+├── mocks.ts           Mock utilities
+│   ├── mockConsole()         Spy on console.log/error
+│   ├── mockProcessExit()     Mock process.exit
+│   ├── useFakeTimers()       Time manipulation
+│   └── createMockEmitter()   EventEmitter spy
+│
+└── index.ts           Unified exports
+```
+
+### Usage Example
+
+```typescript
+import { tmpdir, createParallelTask, mockConsole } from "@/tests/harness";
+
+describe("My test", () => {
+  let consoleMock;
+
+  beforeEach(() => {
+    consoleMock = mockConsole();
+    consoleMock.setup();
+  });
+
+  afterEach(() => {
+    consoleMock.restore();
+  });
+
+  it("should work", async () => {
+    await using tmp = await tmpdir({ git: true });
+    const task = createParallelTask({ description: "Test" });
+    expect(task.status).toBe("pending");
+  });
+});
 ```
 
 ---
 
 ## ⚡ Elite Multi-Agent Swarm
 
-| Agent | Expertise | Capability |
-|:------|:----------|:-----------|
-| **Commander** | Mission Hub | Session pooling, parallel thread control, state rehydration, work-stealing coordination |
-| **Planner** | Architect | Symbolic mapping, dependency research, roadmap generation, file-level planning |
+| Agent | Role | Core Responsibilities |
+|:------|:-----|:------------------------|
+| **Commander** | Mission Hub | Task decomposition, agent coordination, work-stealing orchestration, final mission seal |
+| **Planner** | Architect | Dependency analysis, roadmap generation, TODO.md creation via MVCC, file-level planning |
 | **Worker** | Implementer | High-throughput coding, TDD workflow, documentation, isolated file execution |
-| **Reviewer** | Auditor | Rigid verification, LSP/Lint authority, integration testing, final mission seal |
-
+| **Reviewer** | Auditor | Unit test verification, LSP/Lint validation, integration testing, quality gate |
 ---
 
 ## 🛠️ Core Capabilities
@@ -104,7 +231,7 @@ Maintains focus across thousands of conversation turns using a 4-tier memory str
 
 ---
 
-## � Performance Benchmarks
+## ⚙️ Performance Benchmarks
 
 | Metric | Improvement |
 |:-------|:------------|
@@ -153,6 +280,9 @@ The installation process is **production-safe** with multiple protection layers:
 3. ✅ **Atomic writes** — temp file + rename (OS-level atomic)
 4. ✅ **Automatic rollback** — restores from backup on any failure
 5. ✅ **Cross-platform** — Windows (native, Git Bash, WSL2), macOS, Linux
+6. ✅ **CI-aware** — skips non-essential operations in CI environments
+7. ✅ **Timeout protection** — 30s timeout prevents hanging
+8. ✅ **Graceful degradation** — exits 0 on non-critical failures
 
 ### Configuration Logs
 - Unix: `/tmp/opencode-orchestrator.log`
@@ -160,11 +290,36 @@ The installation process is **production-safe** with multiple protection layers:
 
 ---
 
+## 🧪 Testing & Stability
+
+### Test Utilities
+Reusable helpers under `tests/harness/` provide:
+- **Disposable tmpdir**: Automatic cleanup with `Symbol.asyncDispose` / `Symbol.dispose`
+- **Test builders**: Factory functions for `ParallelTask`, `BackgroundTask`, `Todo`
+- **Mock utilities**: Console, process, timers, file system, event emitter mocks
+
+```typescript
+import { tmpdir, createParallelTask, mockConsole } from "@/tests/harness";
+
+await using tmp = await tmpdir({ git: true });
+const task = createParallelTask({ description: "Test" });
+```
+
+### TUI Stability
+- **Cleanup guarantees**: `initToastClient()` returns a cleanup function
+- **Timeout protection**: AbortController-based 2-10s timeout for async toast operations
+- **Error isolation**: Try/catch around all toast operations prevents cascade failures
+
+### Cross-Platform Reliability
+- **Windows guard**: Proper handling of WSL2, Git Bash, native Windows paths
+- **Signal handling**: Graceful shutdown on SIGINT/SIGTERM
+- **Process isolation**: Child process cleanup with timeout
+
+---
+
 ## 📚 Documentation
 
-- [Why We Built a Custom Orchestrator →](docs/WHY_CUSTOM_ORCHESTRATOR.md)
 - [System Architecture Deep-Dive →](docs/SYSTEM_ARCHITECTURE.md)
-- [Windows Configuration Guide →](docs/WINDOWS_CONFIGURATION.md)
 - [Developer Notes →](docs/DEVELOPERS_NOTE.md)
 
 ---

package/dist/core/agents/consts/task-status.const.d.ts

@@ -1,21 +1,2 @@
-/**
- * TASK_STATUS - Task status constants (for parallel tasks)
- */
-export declare const TASK_STATUS: {
-    readonly PENDING: "pending";
-    readonly RUNNING: "running";
-    readonly COMPLETED: "completed";
-    readonly FAILED: "failed";
-    readonly ERROR: "error";
-    readonly TIMEOUT: "timeout";
-    readonly CANCELLED: "cancelled";
-};
-/**
- * TODO_STATUS - Todo item status constants
- */
-export declare const TODO_STATUS: {
-    readonly PENDING: "pending";
-    readonly IN_PROGRESS: "in_progress";
-    readonly COMPLETED: "completed";
-    readonly CANCELLED: "cancelled";
-};
+export { TASK_STATUS } from "../../../shared/loop/constants/task-status.js";
+export { TODO_STATUS } from "../../../shared/loop/constants/todo-status.js";

package/dist/core/loop/circuit-breaker.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Circuit Breaker - Loop Detection and Prevention
+ *
+ * Detects repetitive patterns and trips the circuit to prevent
+ * infinite loops. Uses tool call history for pattern detection.
+ */
+export interface CircuitBreakerState {
+    lastAccessedAt: number;
+    lastTrippedAt: number;
+    isOpen: boolean;
+    toolCallHistory: string[];
+}
+export declare function isCircuitOpen(sessionID: string): boolean;
+export declare function detectRepetitiveToolUse(sessionID: string): string | null;
+export declare function shouldTripCircuit(sessionID: string): boolean;
+export declare function recordToolCall(sessionID: string, toolName: string): void;
+export declare function clearCircuitState(sessionID: string): void;
+export declare function getCircuitState(sessionID: string): CircuitBreakerState | undefined;
+export declare function shutdownCircuitBreaker(): void;

package/dist/core/loop/compaction-guard.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Compaction Guard - Prevents post-compaction Resume Errors
+ *
+ * After session compaction, continuation prompts may reference deleted context.
+ * This guard ensures continuation only happens after a newer compaction epoch.
+ */
+export interface CompactionGuardState {
+    compactionEpoch: number;
+    lastAccessedAt: number;
+}
+export declare function armCompactionGuard(sessionID: string, timestamp: number): number;
+export declare function isCompactionSafe(sessionID: string, currentEpoch: number): boolean;
+export declare function clearCompactionState(sessionID: string): void;
+export declare function getCompactionState(sessionID: string): CompactionGuardState | undefined;
+export declare function shutdownCompactionGuard(): void;

package/dist/core/loop/mission-loop-handler.d.ts

@@ -3,23 +3,14 @@
  *
  * Monitors session events and ensures the mission loop continues
  * until all verification requirements are met.
+ *
+ * Integrates: ProgressTracker, SessionStateStore, CompactionGuard, CircuitBreaker
  */
 import type { PluginInput } from "@opencode-ai/plugin";
 type OpencodeClient = PluginInput["client"];
-/**
- * Handle session.idle event for mission loop
- */
 export declare function handleMissionIdle(client: OpencodeClient, directory: string, sessionID: string, mainSessionID?: string): Promise<void>;
-/**
- * Handle user message - cancel countdown
- */
 export declare function handleUserMessage(sessionID: string): void;
-/**
- * Handle abort
- */
 export declare function handleAbort(sessionID: string): void;
-/**
- * Clean up session state
- */
 export declare function cleanupSession(sessionID: string): void;
+export declare function handleSessionCompacted(sessionID: string): void;
 export {};

package/dist/core/loop/mission-loop.d.ts

@@ -42,7 +42,3 @@ export declare function generateMissionContinuationPrompt(state: MissionLoopStat
  * Generate completion notification
  */
 export declare function generateCompletionNotification(state: MissionLoopState): string;
-/**
- * Generate max iterations reached notification
- */
-export declare function generateMaxIterationsNotification(state: MissionLoopState): string;

package/dist/core/loop/progress-tracker.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Progress Tracker - Snapshot-based Progress Tracking
+ *
+ * Implements content-hash-based progress detection to identify when
+ * agents are truly making progress vs just cycling without completion.
+ */
+export interface NormalizedTodo {
+    id: string | null;
+    content: string;
+    priority: string;
+    status: string;
+}
+export interface ProgressUpdateResult {
+    hasProgressed: boolean;
+    stagnationCount: number;
+    previousIncompleteCount?: number;
+    progressSource: "none" | "count" | "snapshot";
+    recoveredFromStagnation?: boolean;
+}
+export declare const DEFAULT_STAGNATION_THRESHOLD = 3;
+export declare const PROGRESS_GRACE_PERIOD_MS = 5000;
+export declare function hashTodos(todos: NormalizedTodo[]): string;
+export declare function countCompleted(todos: NormalizedTodo[]): number;
+export declare function resetProgress(sessionID: string): void;
+export declare function clearSession(sessionID: string): void;
+export declare function trackProgress(sessionID: string, incompleteCount: number, todos?: NormalizedTodo[]): ProgressUpdateResult;
+export declare function markInjectionPerformed(sessionID: string): void;
+export declare function isStagnant(sessionID: string, threshold?: number): boolean;
+export declare function getStagnationCount(sessionID: string): number;
+export interface ProgressTracker {
+    trackProgress: typeof trackProgress;
+    resetProgress: typeof resetProgress;
+    clearSession: typeof clearSession;
+    hashTodos: typeof hashTodos;
+    isStagnant: typeof isStagnant;
+    getStagnationCount: typeof getStagnationCount;
+    markInjectionPerformed: typeof markInjectionPerformed;
+}
+export declare function createProgressTracker(): ProgressTracker;

package/dist/core/loop/session-state-store.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Session State Store - TTL-based Session State Management
+ *
+ * Provides automatic cleanup of stale session states to prevent memory leaks.
+ */
+export interface SessionState {
+    stagnationCount: number;
+    countdownTimer?: ReturnType<typeof setTimeout>;
+    countdownStartedAt?: number;
+    lastCheckTime?: number;
+    isRecovering: boolean;
+    isAborting: boolean;
+    inFlight: boolean;
+}
+export declare const SESSION_STATE_TTL_MS: number;
+export declare const PRUNE_INTERVAL_MS: number;
+export interface SessionStateStore {
+    getState: (sessionID: string) => SessionState;
+    getExistingState: (sessionID: string) => SessionState | undefined;
+    cancelCountdown: (sessionID: string) => void;
+    cleanup: (sessionID: string) => void;
+    cancelAllCountdowns: () => void;
+    shutdown: () => void;
+}
+declare function createSessionStateStore(): SessionStateStore;
+export { createSessionStateStore };

package/dist/core/notification/toast-core.d.ts

@@ -8,7 +8,7 @@ type OpencodeClient = PluginInput["client"];
 /**
  * Initialize the toast system with the OpenCode client
  */
-export declare function initToastClient(client: OpencodeClient): void;
+export declare function initToastClient(client: OpencodeClient): () => void;
 /**
  * Register a notification handler
  */

package/dist/core/plugins/plugin-manager.d.ts

@@ -1,6 +1,7 @@
 /**
  * PluginManager - Manages dynamic loading of orchestrator plugins
  */
+import type { ToolDefinition } from "@opencode-ai/plugin";
 export declare class PluginManager {
     private static instance;
     private plugins;
@@ -17,7 +18,7 @@ export declare class PluginManager {
     /**
      * Get all dynamically registered tools
      */
-    getDynamicTools(): Record<string, any>;
+    getDynamicTools(): Record<string, ToolDefinition>;
     /**
      * Shutdown - cleanup all plugins
      */