opencode-swarm 7.107.5 → 7.108.0

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>;