opencode-swarm 7.13.2 → 7.15.0

package/dist/turbo/lean/runner.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Lean Turbo Lane Runner.
+ *
+ * Orchestrates parallel lane execution for Lean Turbo:
+ * - Reads plan.json for a given phase
+ * - Plans lane distribution via planLeanTurboLanes()
+ * - Acquires file locks for each lane (all-or-nothing per lane)
+ * - Dispatches coder agents via OpencodeClient session API
+ * - Tracks lane status in memory and updates durable state
+ * - Releases locks on cleanup
+ *
+ * ## Fail-Closed Design
+ *
+ * - If opencodeClient is null at construction, runPhase() returns error immediately
+ * - If lock acquisition fails for a lane, the lane is marked 'blocked'
+ * - If dispatch fails, locks for that lane are released and lane is marked 'failed'
+ */
+import type { OpencodeClient } from '@opencode-ai/sdk';
+import type { LeanTurboConfig } from '../../config/schema';
+import { loadFullAutoRunState } from '../../full-auto/state';
+import { acquireLaneLocks, releaseLaneLocks } from '../../parallel/file-locks';
+import { loadPlanJsonOnly } from '../../plan/manager';
+import { hasActiveFullAuto } from '../../state';
+import { writeLaneEvidence } from './evidence';
+import { planLeanTurboLanes } from './planner';
+import type { LeanTurboLane } from './state';
+import { loadLeanTurboRunState, saveLeanTurboRunState } from './state';
+/**
+ * Shape of the OpencodeClient session API used by the runner.
+ * Extracted into an interface so tests can inject a mock without
+ * requiring the full SDK type.
+ */
+interface SessionClient {
+    create(options: {
+        query: {
+            directory: string;
+        };
+    }): Promise<{
+        data: {
+            id: string;
+        } | null;
+        error: unknown;
+    }>;
+    prompt(options: {
+        path: {
+            id: string;
+        };
+        body: {
+            agent: string;
+            tools: {
+                write: boolean;
+                edit: boolean;
+                patch: boolean;
+            };
+            parts: Array<{
+                type: 'text';
+                text: string;
+            }>;
+        };
+    }): Promise<{
+        data: {
+            parts: Array<{
+                type: string;
+                text?: string;
+            }>;
+        } | null;
+        error: unknown;
+    }>;
+    delete(options: {
+        path: {
+            id: string;
+        };
+    }): Promise<void>;
+}
+/**
+ * Result of a single lane dispatch (session creation + prompt).
+ */
+export interface LaneDispatchResult {
+    /** Whether dispatch succeeded */
+    ok: boolean;
+    /** Session ID if ok === true */
+    sessionId?: string;
+    /** Error message if ok === false */
+    error?: string;
+}
+/**
+ * Result of a single lane's processing.
+ */
+export interface LaneResult {
+    /** Lane identifier */
+    laneId: string;
+    /** Current status */
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'blocked';
+    /** Task IDs assigned to this lane */
+    taskIds: string[];
+    /** Agent name that was dispatched */
+    agent?: string;
+    /** Session ID for this lane (set after successful dispatch) */
+    sessionId?: string;
+    /** Error message if status is 'failed' or 'blocked' */
+    error?: string;
+}
+/**
+ * Result of a full phase run.
+ */
+export interface LeanTurboPhaseResult {
+    /** Whether the phase ran (at least one lane attempted) */
+    ok: boolean;
+    /** Human-readable reason when ok === false */
+    reason?: string;
+    /** Per-lane results */
+    lanes: LaneResult[];
+    /** Task IDs that were degraded (risk conditions) */
+    degradedTasks: string[];
+    /** Task IDs excluded from parallel lanes, must complete via standard serial flow */
+    serializedTasks: string[];
+}
+/**
+ * Orchestrates Lean Turbo lane execution.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * const runner = new LeanTurboRunner({
+ *   directory: projectRoot,
+ *   sessionID: 'sess-abc123',
+ *   opencodeClient: swarmState.opencodeClient,
+ *   generatedAgentNames: swarmState.generatedAgentNames,
+ * });
+ *
+ * const result = await runner.runPhase(1);
+ * // ... monitor lanes ...
+ * await runner.cleanup();
+ * ```
+ */
+export declare class LeanTurboRunner {
+    /**
+     * Test-only dependency-injection seam.
+     * Allows tests to intercept plan/lock/state operations without mock.module leakage.
+     * Production code assigns real functions here at module load.
+     */
+    static _internals: {
+        loadPlanJsonOnly: typeof loadPlanJsonOnly;
+        planLeanTurboLanes: typeof planLeanTurboLanes;
+        acquireLaneLocks: typeof acquireLaneLocks;
+        releaseLaneLocks: typeof releaseLaneLocks;
+        loadLeanTurboRunState: typeof loadLeanTurboRunState;
+        saveLeanTurboRunState: typeof saveLeanTurboRunState;
+        hasActiveFullAuto: typeof hasActiveFullAuto;
+        loadFullAutoRunState: typeof loadFullAutoRunState;
+        writeLaneEvidence: typeof writeLaneEvidence;
+        /** Timeout for lane dispatch (session.create + session.prompt) in ms. Undefined = no timeout. */
+        laneDispatchTimeoutMs: number | undefined;
+    };
+    /**
+     * Test-only dependency-injection seam for session operations.
+     * Allows tests to intercept client.session calls without mock.module leakage.
+     *
+     * Default: uses real OpencodeClient session API from the injected client.
+     * Tests: replace by assigning a mock SessionClient directly to this field
+     * on the runner instance.
+     *
+     * Example:
+     * ```ts
+     * const runner = new LeanTurboRunner({ directory, sessionID });
+     * (runner as unknown as { _sessionOps: SessionClient })._sessionOps = mockSessionOps;
+     * ```
+     *
+     * NB: The fail-closed check uses `opencodeClient === null` (strict equality)
+     * so omitting `opencodeClient` (undefined) does NOT trigger fail-closed,
+     * allowing test mock injection to proceed.
+     */
+    _sessionOps: SessionClient | null;
+    private readonly _directory;
+    private readonly _sessionID;
+    private readonly _client;
+    private readonly _availableAgents;
+    /** Tracks which files are locked per lane (for cleanup) */
+    private _laneLockMap;
+    /** Current lane statuses (updated after each dispatch) */
+    private _laneStatuses;
+    /** Round-robin index for agent selection */
+    private _agentIndex;
+    /**
+     * Tracks lanes that timed out so that when their _doDispatch completes,
+     * we can clean up the orphan session.
+     */
+    private _timedOutLanes;
+    /** Chains durable state updates to prevent race conditions on concurrent lanes. */
+    private _stateLock;
+    /** Lean-mode configuration passed at construction. Undefined means use defaults. */
+    private readonly _leanConfig?;
+    constructor(options: {
+        /** Project root directory */
+        directory: string;
+        /** Current session ID */
+        sessionID: string;
+        /** OpenCode SDK client. Pass null to stay fail-closed. Omit to allow test mock injection. */
+        opencodeClient?: OpencodeClient | null;
+        /** Pre-registered generated agent names */
+        generatedAgentNames?: string[];
+        /** Lean-mode configuration. Falls back to hardcoded defaults if omitted. */
+        leanConfig?: LeanTurboConfig;
+    });
+    /**
+     * Run a single phase: plan lanes, acquire locks, dispatch coders.
+     *
+     * @param phaseNumber - Phase number to execute
+     * @returns Result with per-lane statuses and degraded task list
+     */
+    runPhase(phaseNumber: number): Promise<LeanTurboPhaseResult>;
+    /**
+     * Dispatch a single lane to a named agent.
+     *
+     * Creates an ephemeral session, sends a task prompt, and returns
+     * the session ID for later status polling.
+     *
+     * @param lane - Lane to dispatch
+     * @param agentName - Agent name to dispatch to
+     */
+    dispatchLane(lane: LeanTurboLane, agentName: string): Promise<LaneDispatchResult>;
+    /**
+     * Internal dispatch implementation (separated for timeout wrapping).
+     */
+    private _doDispatch;
+    /**
+     * Get current status of all lanes tracked by this runner.
+     *
+     * Note: This returns in-memory status only. Lane sessions are
+     * managed by the OpenCode runtime and cannot be directly polled
+     * through the SDK. External status tracking (e.g., via session
+     * list) should be used for production status polling.
+     */
+    waitForLanes(): Promise<LaneStatus[]>;
+    /**
+     * Release all lane locks and mark unresolved lanes as blocked.
+     *
+     * Call this on error exit or when shutting down a phase early.
+     * Releases ALL locks and transitions ALL running/pending lanes to blocked.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Cleanup after a successful phase run.
+     *
+     * Only releases locks for lanes that reached a terminal state (completed,
+     * failed, blocked). Does NOT change lane statuses — running lanes stay running.
+     */
+    cleanupAfterSuccess(): Promise<void>;
+    /**
+     * Cleanup after a failed phase run.
+     *
+     * Current behavior: releases ALL locks, marks all unresolved lanes blocked.
+     */
+    cleanupAfterFailure(): Promise<void>;
+    /**
+     * Resolve the list of available coder agent names.
+     *
+     * Prefers agents matching swarm prefix patterns (e.g. `mega_coder`)
+     * over bare `coder`. Falls back to `['coder']` if no coder agents found.
+     */
+    private _resolveCoderAgents;
+    /**
+     * Get the Lean Turbo configuration.
+     *
+     * The config is passed to runPhase (from plugin config or caller).
+     * If not provided, sensible defaults are used.
+     */
+    private _getLeanConfig;
+    /**
+     * Process a single lane: acquire locks, dispatch, track status.
+     *
+     * On successful dispatch completion (session.prompt resolves), the lane
+     * is transitioned to 'completed', locks are released, evidence is written,
+     * and the lane counter is incremented.
+     *
+     * On lock acquisition failure (Bug #4), the lane's tasks are routed to
+     * the serialized tasks set for standard serial fallback.
+     */
+    private _processLane;
+    /**
+     * Select the next available agent using round-robin.
+     */
+    private _selectNextAgent;
+    /**
+     * Safely write lane evidence, catching errors to prevent evidence write
+     * failure from blocking lane processing.
+     */
+    private _writeLaneEvidenceSafely;
+    /**
+     * Build a human-readable prompt describing a lane's tasks.
+     */
+    private _buildLanePrompt;
+    /**
+     * Serializes access to durable state via a promise chain.
+     * Prevents concurrent lane updates from racing on turbo-state.json writes.
+     *
+     * Includes a 10-second timeout: if state persistence hangs, the lock is
+     * released so subsequent updates are not blocked indefinitely.
+     */
+    private _withStateLock;
+    /**
+     * Update durable state with the full lane plan (called once per phase).
+     */
+    private _updateDurableState;
+    /**
+     * Update a single lane's status in durable state.
+     * Serialized through _withStateLock to prevent race conditions with concurrent lanes.
+     */
+    private _updateDurableStateLaneStatus;
+}
+/**
+ * Current status of a lane (returned by waitForLanes).
+ */
+export interface LaneStatus {
+    laneId: string;
+    status: LeanTurboLane['status'];
+    taskIds: string[];
+    agent?: string;
+    sessionId?: string;
+    error?: string;
+}
+export {};

package/dist/turbo/lean/state.d.ts

@@ -0,0 +1,61 @@
+export type LeanTurboStatus = 'idle' | 'running' | 'paused' | 'terminated';
+export interface LeanTurboLane {
+    laneId: string;
+    taskIds: string[];
+    files: string[];
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'blocked';
+    startedAt?: string;
+    completedAt?: string;
+    error?: string;
+    agent?: string;
+    sessionId?: string;
+}
+export interface LeanTurboDegradedTask {
+    taskId: string;
+    reason: string;
+    files: string[];
+    requiredMode: 'standard' | 'balanced';
+}
+export interface LeanTurboCounters {
+    lanesPlanned: number;
+    lanesStarted: number;
+    lanesCompleted: number;
+    lanesFailed: number;
+    tasksSerialized: number;
+    tasksDegraded: number;
+}
+export interface LeanTurboRunState {
+    status: LeanTurboStatus;
+    sessionID: string;
+    strategy: 'lean';
+    phase?: number;
+    maxParallelCoders: number;
+    planId?: string;
+    activeLanePlanId?: string;
+    lanes: LeanTurboLane[];
+    degradedTasks: LeanTurboDegradedTask[];
+    /** Task IDs excluded from parallel lanes, must complete via standard serial flow */
+    serializedTasks: string[];
+    lastReviewerVerdict?: 'APPROVED' | 'NEEDS_REVISION' | 'REJECTED';
+    lastCriticVerdict?: string;
+    pauseReason?: string;
+    terminateReason?: string;
+    counters: LeanTurboCounters;
+}
+export interface LeanTurboPersistedState {
+    version: 1;
+    updatedAt: string;
+    sessions: Record<string, LeanTurboRunState>;
+}
+export declare function emptyCounters(): LeanTurboCounters;
+export declare function emptyRunState(sessionID: string, maxParallelCoders: number): LeanTurboRunState;
+export declare function emptyPersisted(): LeanTurboPersistedState;
+export declare function isStateUnreadable(directory: string): boolean;
+export declare function repairStateUnreadable(directory: string): void;
+export declare function readPersisted(directory: string): LeanTurboPersistedState | null;
+export declare function writePersisted(directory: string, persisted: LeanTurboPersistedState): void;
+export declare function loadLeanTurboRunState(directory: string, sessionID: string): LeanTurboRunState | null;
+export declare function saveLeanTurboRunState(directory: string, runState: LeanTurboRunState): void;
+export declare function isLeanTurboRunActive(directory: string, sessionID: string): boolean;
+export declare function pauseLeanTurboRun(directory: string, sessionID: string, reason: string): void;
+export declare function resetLeanTurboRun(directory: string, sessionID: string): void;

package/dist/turbo/lean/task-completion.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Lean Turbo Stage B bypass verification.
+ *
+ * Provides a synchronous helper to check whether a task is eligible for
+ * Lean Turbo Stage B bypass — i.e., whether it can be marked completed
+ * without running the full reviewer + test_engineer gate.
+ */
+import { listActiveLocks } from '../../parallel/file-locks';
+/**
+ * Test-only seam. Replaces the lock-list function so tests can inject
+ * mock results without touching the real `file-locks` module.
+ */
+export declare const _internals: {
+    listActiveLocks: typeof listActiveLocks;
+    verifyLeanTurboTaskCompletion: typeof verifyLeanTurboTaskCompletion;
+};
+/**
+ * Result of the Lean Turbo task completion eligibility check.
+ */
+export interface LeanTurboTaskCompletionResult {
+    ok: boolean;
+    reason: string;
+    laneFound?: boolean;
+    evidence?: {
+        laneId: string;
+        laneStatus: string;
+        taskIds: string[];
+    };
+}
+/**
+ * Synchronously verify whether a task is eligible for Lean Turbo Stage B bypass.
+ *
+ * Checks are performed in fail-fast order:
+ *  1. Read `.swarm/turbo-state.json` — missing/unreadable → ok: false
+ *  2. Find a Lean Turbo run state (strategy === 'lean' AND status === 'running')
+ *     → none found → ok: false
+ *     If sessionID is provided, also require sessionID to match
+ *  3. Find the lane containing taskId in runState.lanes → none → ok: false
+ *  4. Check if task is in runState.degradedTasks → yes → ok: false with degradation reason
+ *  5. Check lane.status === 'completed' → not completed → ok: false
+ *  6. Check lane evidence file exists at `.swarm/evidence/{phase}/lean-turbo/{laneId}.json`
+ *     → missing → ok: false
+ *  7. Check for active file locks on this lane → any active → ok: false
+ *  8. Read plan.json to get task's files_touched and check Tier-3 patterns → matched → ok: false
+ *  9. All checks pass → ok: true
+ *
+ * @param directory - Project root directory
+ * @param taskId    - Task ID to verify
+ * @param sessionID - Optional session ID to scope which Lean Turbo session may grant bypass.
+ *                    When provided, only a running Lean Turbo session with a matching sessionID
+ *                    can grant bypass — preventing cross-session Stage B bypass.
+ */
+export declare function verifyLeanTurboTaskCompletion(directory: string, taskId: string, sessionID?: string): LeanTurboTaskCompletionResult;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.13.2",
+	"version": "7.15.0",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",