opencode-swarm 7.78.3 → 7.78.5

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

@@ -122,6 +122,19 @@ export interface LaneResult {
 }
 /**
  * Result of a full phase run.
+ *
+ * ## Serial Tasks Contract
+ *
+ * `serializedTasks` contains task IDs excluded from parallel lanes due to lock conflicts
+ * (Issue #1 - Serial Task Orphan Risk).
+ *
+ * **Caller Responsibility**: The orchestrator MUST complete these tasks via standard
+ * serial flow (normal task dispatch). The runner does NOT dispatch serializedTasks.
+ *
+ * **Verification**: phase-ready (step 6b) verifies serializedTasks by checking that
+ * each task ID has status: completed in plan.json. If serializedTasks contain task IDs
+ * but those tasks are not marked completed in plan.json, phase-ready returns ok: false,
+ * blocking phase advancement.
  */
 export interface LeanTurboPhaseResult {
     /** Whether the phase ran (at least one lane attempted) */
@@ -132,7 +145,11 @@ export interface LeanTurboPhaseResult {
     lanes: LaneResult[];
     /** Task IDs that were degraded (risk conditions) */
     degradedTasks: string[];
-    /** Task IDs excluded from parallel lanes, must complete via standard serial flow */
+    /**
+     * Task IDs excluded from parallel lanes due to lock conflicts.
+     * Caller must complete these via standard serial flow before phase can advance.
+     * (Issue #1: Serial Task Orphan Risk - Fixed with integration test)
+     */
     serializedTasks: string[];
     /** Lanes whose coder completed but merge-back to primary branch failed */
     mergeBackFailures?: MergeBackFailureInfo[];
@@ -326,8 +343,11 @@ export declare class LeanTurboRunner {
      */
     private _selectNextAgent;
     /**
-     * Safely write lane evidence, catching errors to prevent evidence write
-     * failure from blocking lane processing.
+     * Write lane evidence with retry logic for transient disk errors.
+     *
+     * Evidence is required by phase-ready (step 4b) to verify lane completion.
+     * Transient I/O errors are retried with exponential backoff; permanent errors
+     * are logged and dropped (evidence failure is non-fatal for runner operation).
      */
     private _writeLaneEvidenceSafely;
     /**
@@ -335,11 +355,20 @@ export declare class LeanTurboRunner {
      */
     private _buildLanePrompt;
     /**
-     * Serializes access to durable state via a promise chain.
-     * Prevents concurrent lane updates from racing on turbo-state.json writes.
+     * Serializes access to durable state via a promise chain AND file-based lock.
+     *
+     * - Promise chain: serializes writes within a single runner instance
+     * - File-based lock: coordinates between multiple runners with the same sessionID
+     *
+     * Timeout budget starts when this call reaches the front of the queue (execution
+     * time), not when it is enqueued. withTurboStateLock computes its deadline
+     * internally on entry, so each caller gets a full 10-second window regardless
+     * of how long it waited behind prior entries.
      *
-     * Includes a 10-second timeout: if state persistence hangs, the lock is
-     * released so subsequent updates are not blocked indefinitely.
+     * Timeout coverage: withTurboStateLock is tested directly in state-lock.test.ts
+     * (test: "throws TurboStateLockTimeoutError when lock is held by another caller").
+     * This wrapper delegates to it in a single line with no additional timeout logic,
+     * so a separate wrapper-level timeout test would duplicate that coverage.
      */
     private _withStateLock;
     /**

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

@@ -0,0 +1,59 @@
+/**
+ * Durable Lean Turbo state write-lock helper.
+ *
+ * ## Issue #2: Cross-Runner Durable State Race
+ *
+ * Multiple LeanTurboRunner instances with the same sessionID share turbo-state.json.
+ * Each runner has its own in-process _stateLock promise chain, but without file-level
+ * coordination, concurrent runners can race:
+ *
+ * - Runner A: load state → modify → write
+ * - Runner B: load state (gets A's version) → modify → write (overwrites A's changes)
+ *
+ * This module adds file-based locking using proper-lockfile to coordinate read-modify-write
+ * cycles across processes, preventing inter-runner write races.
+ *
+ * ## Pattern
+ *
+ * Mirrors the evidence-lock pattern (src/evidence/lock.ts) with:
+ * - Exponential backoff (50ms start, 2000ms max) with jitter
+ * - Timeout protection (default 30 seconds for state, 60 seconds for evidence)
+ * - Best-effort lock release in finally block
+ * - Non-fatal lock release failures (proper-lockfile TTL cleanup)
+ *
+ * ## Telemetry
+ *
+ * Events emitted (when integrated into runners):
+ * - turbo_state_lock_acquired
+ * - turbo_state_lock_contended
+ * - turbo_state_lock_timeout (thrown as error)
+ */
+import { tryAcquireLock } from '../../parallel/file-locks';
+/** Test-only seam — allows injecting a mock tryAcquireLock without mock.module. */
+export declare const _internals: {
+    tryAcquireLock: typeof tryAcquireLock;
+};
+export declare class TurboStateLockTimeoutError extends Error {
+    readonly directory: string;
+    readonly sessionID: string;
+    constructor(directory: string, sessionID: string, timeoutMs: number);
+}
+/**
+ * Acquire an exclusive turbo-state lock, execute `fn`, then release the lock.
+ *
+ * Retries with exponential backoff until `timeoutMs` elapses,
+ * then throws `TurboStateLockTimeoutError`. Always releases the lock in a
+ * `finally` block even if `fn` throws.
+ *
+ * **Timeout scope**: `timeoutMs` governs lock _acquisition_ only. Once the lock
+ * is held, `fn()` runs to completion with no separate execution deadline.
+ * Callers must ensure `fn` is bounded (e.g., synchronous disk writes). This
+ * matches the behaviour of the previous `Promise.race` implementation, which
+ * also could not cancel an in-flight `fn()`.
+ *
+ * @param directory    Project root directory
+ * @param sessionID    Session identifier (for lock metadata and diagnostics)
+ * @param fn           Callback that performs the read-modify-write on turbo state
+ * @param timeoutMs    Maximum wait time for lock acquisition (default 30 000ms)
+ */
+export declare function withTurboStateLock<T>(directory: string, sessionID: string, fn: () => Promise<T>, timeoutMs?: number): Promise<T>;

package/dist/utils/swarm-artifact-cache.d.ts

@@ -0,0 +1,23 @@
+export interface SwarmArtifactCacheStats {
+    textReadCount: number;
+    textCacheHitCount: number;
+    textCacheMissCount: number;
+    parsedReadCount: number;
+    parseCount: number;
+    parsedCacheHitCount: number;
+    parsedCacheMissCount: number;
+    statFailureCount: number;
+    evictionCount: number;
+    textEvictionCount: number;
+    parsedEvictionCount: number;
+    cloneFallbackCount: number;
+    textEntryCount: number;
+    parsedEntryCount: number;
+}
+export declare function cloneCachedValue<T>(value: T): T;
+export declare function readCachedTextFileSync(filePath: string, directRead: () => string | null): string | null;
+export declare function readCachedTextFile(filePath: string, directRead: () => Promise<string | null>): Promise<string | null>;
+export declare function readCachedParsedFileSync<T>(filePath: string, namespace: string, readText: () => string | null, parse: (content: string) => T): T | null;
+export declare function readCachedParsedFile<T>(filePath: string, namespace: string, readText: () => Promise<string | null>, parse: (content: string) => T): Promise<T | null>;
+export declare function resetSwarmArtifactCache(): void;
+export declare function getSwarmArtifactCacheStats(): SwarmArtifactCacheStats;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.78.3",
+	"version": "7.78.5",
 	"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",