opencode-swarm 7.107.6 → 7.109.0

package/dist/hooks/delegation-gate/worktree-isolation.d.ts

@@ -8,9 +8,46 @@
  * Extracted from delegation-gate.ts (FR-003) for modularity.
  * The _internals seam allows test injection of worktree operations.
  */
-import type { PluginConfig } from '../../config';
+import type { PluginConfig, WorktreeIsolationConfig } from '../../config';
 import type { WorktreeHandle } from '../../worktree';
 import { attemptMergeBackFromDirty, cleanupOrphanedBranches, postMergeCleanup, provisionWorktree, removeWorktree, startupOrphanRecovery } from '../../worktree';
+/**
+ * FR-201: Per-lane runtime profile injected into spawned child processes.
+ *
+ * Produced at lane provisioning time and written as `.swarm/lanes/{laneIndex}.env`
+ * (KEY=VAL format, one per line) so any child process spawned inside the lane
+ * can source it to get lane-specific PORT, TMPDIR, cache redirects, etc.
+ *
+ * The profile is computed from the resolved WorktreeIsolationConfig.runtime_isolation:
+ * - PORT = (port_base ?? 0) + laneIndex * port_stride
+ * - env_overrides merged verbatim
+ * - cache_redirects mapped to env vars
+ */
+export interface LaneRuntimeProfile {
+    /** 0-based lane index used for port and env derivation. */
+    laneIndex: number;
+    /** Absolute path to the provisioned worktree. */
+    worktreePath: string;
+    /** Env var overrides for this lane (includes PORT after derivation). */
+    envOverrides: Record<string, string>;
+}
+/**
+ * Parses a Lean Turbo laneId (e.g. "lane-3") and returns its 0-based index.
+ * Returns 0 for unparseable ids.
+ */
+export declare function parseLeanLaneIndex(laneId: string): number;
+/**
+ * FR-201 SC-122: Computes the per-lane runtime profile from the resolved runtime_isolation config.
+ *
+ * Derives:
+ * - PORT = (port_base ?? 0) + laneIndex * port_stride
+ * - Derives PORT from port_base + lane_index * port_stride (when port_base is set)
+ * - Merges env_overrides — explicit caller values win over derived PORT
+ * - Merges cache_redirects (base → lane-suffixed-path mapped to env vars; wins over env_overrides)
+ *
+ * Returns undefined when runtime_isolation is disabled (zero behavior change).
+ */
+export declare function computeLaneRuntimeProfile(runtime: WorktreeIsolationConfig['runtime_isolation'], laneIndex: number, worktreePath: string): LaneRuntimeProfile | undefined;
 export declare const MAX_TRACKED_STANDARD_WORKTREE_CALLS = 256;
 export interface StandardWorktreeDispatch {
     callID: string;
@@ -19,11 +56,54 @@ export interface StandardWorktreeDispatch {
     planTaskId?: string;
     handle: WorktreeHandle;
     mergeStrategy: 'merge' | 'rebase' | 'cherry-pick';
+    /** FR-201: 0-based lane index for runtime profile derivation. */
+    laneIndex: number;
+}
+export interface AwaitingMergeRecord {
+    callID: string;
+    parentSessionID: string;
+    taskId: string;
+    planTaskId?: string;
+    branch: string;
+    worktreePath: string;
+    mergeStrategy: 'merge' | 'rebase' | 'cherry-pick';
+    queuedAt: number;
 }
+/** Map keyed by callID. Lanes waiting for or in the middle of merge-back. */
+export declare const awaitingMergeByCallID: Map<string, AwaitingMergeRecord>;
 export declare const standardWorktreeByCallID: Map<string, StandardWorktreeDispatch>;
 export declare const standardWorktreeSerializationSessions: Set<string>;
+/**
+ * FR-104 SC-111/SC-112: Per-session state tracking for serialization release.
+ * Maps sessionID → serialization state for that session.
+ */
+interface SessionSerializationState {
+    sessionID: string;
+    /** Date.now() when the session was first added to standardWorktreeSerializationSessions */
+    serializedAt: number;
+    /**
+     * Count of successful dispatches (merge-back completed with 'merged') from this
+     * session since it entered serialized mode.
+     */
+    successfulDispatchesSince: number;
+}
 export declare function resetStandardWorktreeIsolationState(): void;
+/**
+ * FR-104 SC-111/SC-112: Check whether a serialized session has met its release conditions
+ * (either enough successful dispatches have completed, or the TTL has expired).
+ * If so, release it from serialized mode.
+ */
+export declare function checkStandardWorktreeSerializationRelease(sessionID: string, config: WorktreeIsolationConfig): void;
+/**
+ * FR-104 SC-113: Add a session to the serialization set.
+ * When the set is at capacity, evicts the oldest entry whose session has NO
+ * in-flight dispatch — never evict an actively-dispatching session.
+ * If ALL 256 entries are in-flight, refuses the new entry and logs a warning
+ * rather than silently breaking isolation.
+ */
+declare function rememberStandardWorktreeSerializationSession(sessionID: string): boolean;
 export declare function sanitizeWorktreeTaskId(raw: string): string;
+export declare function resolveWorktreeIsolationConfig(config: PluginConfig): WorktreeIsolationConfig;
 export declare function precreateStandardWorktreeSession(args: {
     config: PluginConfig;
     directory: string;
@@ -33,8 +113,31 @@ export declare function precreateStandardWorktreeSession(args: {
     planTaskId?: string;
     description?: string;
     outputArgs: Record<string, unknown>;
+    /** Scope to materialize into the lane for durability across restart (FR-102). */
+    scope?: {
+        taskId: string;
+        files: string[];
+    };
 }): Promise<void>;
-export declare function finishStandardWorktreeDispatch(directory: string, dispatch: StandardWorktreeDispatch): Promise<void>;
+export declare function finishStandardWorktreeDispatch(directory: string, dispatch: StandardWorktreeDispatch, config?: PluginConfig, 
+/**
+ * Optional callID for cleanup of awaitingMergeByCallID. When omitted,
+ * derived from dispatch.callID (for backward compatibility with test callers
+ * that pass StandardWorktreeDispatch objects directly).
+ */
+callID?: string): Promise<void>;
+/**
+ * FR-201: Read and parse a lane runtime profile from disk.
+ *
+ * Reads `<worktree>/.swarm/lanes/{laneIndex}.env` (KEY=VALUE format, one per line).
+ * - Skips blank lines and lines starting with `#` (comments).
+ * - Skips malformed lines (no `=` separator).
+ * - Validates each key with `isValidEnvKey`; rejects and skips invalid keys.
+ * - Returns an empty record when the file does not exist.
+ *
+ * Exposed via _internals for testability (no mock.module leakage).
+ */
+export declare function readLaneEnvFileFromDisk(worktreePath: string, laneIndex: number): Promise<Record<string, string>>;
 /**
  * _internals seam for test injection of worktree operations.
  * Tests set these entries on delegation-gate's _internals (which proxies
@@ -45,6 +148,19 @@ export declare const _internals: {
     removeWorktree: typeof removeWorktree;
     attemptMergeBackFromDirty: typeof attemptMergeBackFromDirty;
     postMergeCleanup: typeof postMergeCleanup;
+    /** FR-201: read lane runtime profile from disk for spawn injection. */
+    readLaneEnvFileFromDisk: typeof readLaneEnvFileFromDisk;
+    /** FR-104: exposes serializationStateBySessionID for test setup (SC-111/SC-112/SC-113). */
+    serializationStateBySessionID: Map<string, SessionSerializationState>;
+    /**
+     * FR-104 SC-113: exposes the FIFO eviction function for direct test invocation.
+     * Tests use this to exercise the cap-check logic without going through the
+     * full precreateStandardWorktreeSession path.
+     */
+    rememberStandardWorktreeSerializationSession: typeof rememberStandardWorktreeSerializationSession;
+    /** FR-105 SC-115: exposes awaitingMergeByCallID for test setup. */
+    awaitingMergeByCallID: Map<string, AwaitingMergeRecord>;
     startupOrphanRecovery: typeof startupOrphanRecovery;
     cleanupOrphanedBranches: typeof cleanupOrphanedBranches;
 };
+export {};

package/dist/hooks/delegation-gate/worktree-merge-status.d.ts

@@ -34,6 +34,14 @@ export interface WorktreeMergeFailure {
     stage: string;
     /** Human-readable detail surfaced in the Rule 2 skip warning. */
     message: string;
+    /** Worktree path where the lane is preserved after a failed/partial merge. */
+    worktreePath?: string;
+    /** Branch name of the lane. */
+    branch?: string;
+    /** Timestamp (Date.now()) when the lane entered merge-back. */
+    queuedAt?: number;
+    /** Timestamp (Date.now()) when merge-back completed (success or failure). */
+    completedAt?: number;
 }
 declare function getDurableStatusPath(projectDir?: string): string;
 /**
@@ -70,6 +78,15 @@ export declare function clearWorktreeMergeStatus(taskId: string | undefined): vo
  * On first read after plugin restart, loads from durable storage.
  */
 export declare function getWorktreeMergeFailure(taskId: string): WorktreeMergeFailure | undefined;
+/**
+ * Iterate all worktree merge failures. Used by /swarm lanes to surface
+ * conflicted lanes that are NOT in awaitingMergeByCallID (i.e., merge
+ * has completed with partial/failed outcome).
+ */
+export declare function getAllWorktreeMergeFailures(): IterableIterator<[
+    string,
+    WorktreeMergeFailure
+]>;
 /**
  * @internal test seam. Use `resetForTest()` in afterEach to isolate tests
  * that set durableStatusPath via `initDurableStatusPath`.

package/dist/hooks/init-orphan-recovery-advisory.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Init Orphan Recovery Advisory Hook (FR-103 SC-108)
+ *
+ * At plugin init, `cleanupOrphanedBranches` is called to reclaim orphaned worktrees
+ * and branches. Any warnings or errors (state-unreadable conditions) are written
+ * to `<directory>/.swarm/advisories/init-orphan-recovery.json`.
+ *
+ * This hook runs in the `messagesTransform` chain (before `guardrailsHooks.messagesTransform`)
+ * and surfaces those advisories to the architect on their NEXT TURN.
+ *
+ * Advisory file format:
+ * ```json
+ * {
+ *   "initTimestamp": "<ISO timestamp>",
+ *   "warnings": ["warning message 1", "warning message 2"],
+ *   "errors": [{ "branch": "swarm-lane/sess/lane", "error": "detail" }],
+ *   "reclaimed": { "removedBranches": [], "prunedWorktrees": true }
+ * }
+ * ```
+ *
+ * The file is deleted after consumption (best-effort) so repeated turns don't re-surface.
+ */
+export interface InitOrphanAdvisory {
+    initTimestamp: string;
+    warnings: string[];
+    errors: Array<{
+        branch: string;
+        error: string;
+    }>;
+    reclaimed: {
+        removedBranches: string[];
+        removedWorktrees: string[];
+        prunedWorktrees: boolean;
+    };
+}
+/**
+ * Creates a messagesTransform hook that surfaces init orphan recovery advisories
+ * on the architect's first turn after plugin init.
+ *
+ * @param directory - Project root directory (for .swarm/advisories path)
+ * @returns A hook object with a messagesTransform handler
+ */
+export declare function createInitOrphanRecoveryAdvisoryHook(directory: string): {
+    messagesTransform: (input: Record<string, never>, output: {
+        messages?: Array<{
+            info: {
+                role: string;
+                agent?: string;
+                sessionID?: string;
+            };
+            parts: Array<{
+                type?: string;
+                text?: string;
+                [key: string]: unknown;
+            }>;
+        }>;
+    }) => Promise<void>;
+};

package/dist/hooks/init-orphan-recovery.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Init Orphan Recovery Helper (FR-103 / SC-107..SC-110)
+ *
+ * Bounded plugin-init wrapper around `cleanupOrphanedBranches` that:
+ *   - Enumerates orphaned worktree directories under `.swarm-worktrees/<sessionId>/` and removes them
+ *   - Calls cleanupOrphanedBranches(ctx.directory, []) at plugin init (no sessions active → all swarm-lane branches are orphans)
+ *   - Writes results to `<directory>/.swarm/advisories/init-orphan-recovery.json`
+ *   - Is wrapped in `withTimeout` so it never blocks plugin init
+ *   - Runs via `queueMicrotask` off the `server()` resolution path (precedent: repoGraphHook.init)
+ *
+ * This module intentionally lives in `src/hooks/` so that `src/index.ts` can import
+ * it without matching the forbidden `worktree/` or `merge-back/` patterns.
+ *
+ * The companion hook `createInitOrphanRecoveryAdvisoryHook` (src/hooks/init-orphan-recovery-advisory.ts)
+ * reads the advisory file at session-start and pushes messages to pendingAdvisoryMessages.
+ */
+import * as fs from 'node:fs';
+import { isLocked, listActiveLocks, tryAcquireLock } from '../parallel/file-locks';
+import { removeWorktree } from '../worktree/core';
+/**
+ * Lock file path for the init orphan recovery advisory lock.
+ * advisory-only — signals that another process may be actively using the repo.
+ */
+export declare const ORPHAN_RECOVERY_LOCK_FILE = ".swarm/locks/init-orphan-recovery.lock";
+/**
+ * DI seam for orphaned worktree removal operations and cross-process lock checking.
+ * Exposed so tests can intercept removeWorktree, rmSync, and lock operations
+ * without mock.module leakage.
+ */
+export declare const _internals: {
+    rmSync: typeof fs.rmSync;
+    removeWorktree: typeof removeWorktree;
+    isLocked: typeof isLocked;
+    listActiveLocks: typeof listActiveLocks;
+    tryAcquireLock: typeof tryAcquireLock;
+};
+export interface InitOrphanRecoveryResult {
+    attempted: boolean;
+    /** Set to true when cross-process lock is held by another process — advisory-only cleanup */
+    crossProcessLockHeld: boolean;
+    warnings: string[];
+    orphanedBranches: string[];
+    removedWorktrees: string[];
+    prunedWorktrees: boolean;
+    diagnostic?: {
+        file: string;
+        reason: string;
+    };
+}
+/**
+ * Runs bounded orphan cleanup at plugin init time.
+ *
+ * Active sessions from swarmState are passed to cleanupOrphanedBranches so their
+ * branches are skipped and not reclaimed during init recovery.
+ *
+ * Cross-process safety: before doing any destructive cleanup, checks whether any
+ * other opencode process holds the advisory lock at `.swarm/locks/init-orphan-recovery.lock`.
+ * If a lock is held (another process is active), skips destructive cleanup entirely
+ * and reports detected orphans in result.warnings instead — preventing a second
+ * process from deleting the first process's active worktrees/branches.
+ *
+ * @param directory - Project root directory
+ * @returns Result object describing what was attempted and any warnings/diagnostics
+ */
+export declare function runInitOrphanRecovery(directory: string): Promise<InitOrphanRecoveryResult>;