opencode-swarm 7.86.0 → 7.87.1

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

@@ -0,0 +1,86 @@
+/**
+ * Worktree merge-back status registry (leaf module — no app imports).
+ *
+ * Bridges two subsystems that otherwise cannot see each other:
+ *
+ *   - WORKTREE ISOLATION (`worktree-isolation.ts`) knows, at merge-back
+ *     time, whether a Task-dispatched coder's isolated worktree merged
+ *     cleanly back into the main tree.
+ *   - EPIC MODE Rule 2 (`plan/manager.updateTaskStatus`) auto-commits a
+ *     `swarm(task <id>):` marker on completion. That marker is the
+ *     evidence Rule 3 scans to decide a downstream task's upstream is
+ *     satisfied.
+ *
+ * Without this bridge, a coder whose worktree merge-back FAILED (conflict)
+ * leaves its changes stranded in the preserved worktree, yet Rule 2 would
+ * still fire an `--allow-empty` marker and Rule 3 would treat the task as
+ * done — silently advancing the plan past work that never landed.
+ *
+ * This module is deliberately a LEAF: it imports nothing from the app so
+ * that both `worktree-isolation.ts` (writer) and `plan/manager.ts` (reader)
+ * can depend on it without creating an import cycle.
+ *
+ * STATE DURABILITY: Status is stored in an in-memory Map (fast, per-process)
+ * AND persisted to `.swarm/worktree-merge-status.json` (survives plugin restart).
+ * On each write, the JSON file is atomically updated. On read, the in-memory
+ * map is checked first (fast path); on plugin restart, the map is empty but
+ * the durable file is restored on first read or Rule 2 lookup.
+ */
+/** Why a task's worktree work did not fully reach the main tree. */
+export type WorktreeMergeOutcome = 'partial' | 'failed';
+export interface WorktreeMergeFailure {
+    outcome: WorktreeMergeOutcome;
+    /** Pipeline stage that failed (e.g. 'merge', 'auto-commit'). */
+    stage: string;
+    /** Human-readable detail surfaced in the Rule 2 skip warning. */
+    message: string;
+}
+declare function getDurableStatusPath(projectDir?: string): string;
+/**
+ * Load the durable file into the in-memory map. The clear+repopulate is
+ * synchronous (no `await`), so no read can observe a transiently-empty map
+ * in Node's single-threaded model. Called only from init and the one-shot
+ * lazy load — never on a steady-state lookup.
+ */
+declare function loadDurableStatus(statusPath: string): void;
+declare function saveDurableStatus(statusPath: string): void;
+/**
+ * Initialize the durable status path for this project and load existing
+ * status from disk. Called from `createDelegationGateHook` before any coder
+ * dispatches. Re-initializing the SAME path is a no-op (the in-memory map is
+ * already the live authority); switching to a DIFFERENT path reloads.
+ */
+export declare function initDurableStatusPath(projectDir: string): void;
+/**
+ * Record that task `taskId`'s worktree merge-back did not fully land.
+ * No-op when `taskId` is undefined (non-plan dispatches carry no plan id
+ * and are never subject to Epic Rule 2).
+ */
+export declare function recordWorktreeMergeFailure(taskId: string | undefined, failure: WorktreeMergeFailure): void;
+/**
+ * Clear any recorded failure for `taskId`. Called when a (re-)dispatch of
+ * the same task merges cleanly, so a later success supersedes an earlier
+ * failure and Rule 2 is allowed to commit the marker again.
+ */
+export declare function clearWorktreeMergeStatus(taskId: string | undefined): void;
+/**
+ * Query whether task `taskId`'s most recent worktree merge-back failed.
+ * Returns the failure detail, or undefined when the task merged cleanly,
+ * was never worktree-isolated, or has no recorded status.
+ * On first read after plugin restart, loads from durable storage.
+ */
+export declare function getWorktreeMergeFailure(taskId: string): WorktreeMergeFailure | undefined;
+/**
+ * @internal test seam. Use `resetForTest()` in afterEach to isolate tests
+ * that set durableStatusPath via `initDurableStatusPath`.
+ */
+export declare const _internals: {
+    failuresByTask: Map<string, WorktreeMergeFailure>;
+    getDurableStatusPath: typeof getDurableStatusPath;
+    loadDurableStatus: typeof loadDurableStatus;
+    saveDurableStatus: typeof saveDurableStatus;
+    initDurableStatusPath: typeof initDurableStatusPath;
+    /** Reset both in-memory and durable state for test isolation. */
+    resetForTest(): void;
+};
+export {};