opencode-swarm 7.3.2 → 7.3.4

package/dist/cli/index.js

@@ -34,7 +34,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.3.2",
+    version: "7.3.4",
     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",

package/dist/hooks/diff-scope.d.ts

@@ -4,6 +4,16 @@
  * were modified, or null if in-scope, no scope declared, or git unavailable.
  * Never throws.
  */
+import { bunSpawn } from '../utils/bun-compat';
+/**
+ * Test-only dependency-injection seam — see `gitignore-warning.ts:_internals`
+ * for the rationale (`mock.module` from `bun:test` leaks across files in
+ * Bun's shared test-runner process). Mutating this local object is
+ * file-scoped and trivially restorable via `afterEach`.
+ */
+export declare const _internals: {
+    bunSpawn: typeof bunSpawn;
+};
 /**
  * Validate that git-changed files match the declared scope for a task.
  * Returns a warning string if undeclared files were modified, null otherwise.

package/dist/index.js

@@ -33,7 +33,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.3.2",
+    version: "7.3.4",
     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",
@@ -65374,7 +65374,7 @@ function createAgentActivityHooks(config3, directory) {
       const duration5 = Date.now() - entry.startTime;
       const explicitSuccess = typeof output.success === "boolean" ? output.success : undefined;
       const explicitFailure = explicitSuccess === false || !!output.error;
-      const success3 = explicitFailure ? false : true;
+      const success3 = !explicitFailure;
       const key = entry.tool;
       const existing = swarmState.toolAggregates.get(key) ?? {
         tool: key,
@@ -89610,19 +89610,141 @@ init_loader();
 init_schema();
 init_qa_gate_profile();
 init_gate_evidence();
+import * as fs86 from "node:fs";
+import * as path106 from "node:path";
+
+// src/hooks/diff-scope.ts
+init_bun_compat();
 import * as fs85 from "node:fs";
 import * as path105 from "node:path";
 
-// src/hooks/diff-scope.ts
+// src/utils/gitignore-warning.ts
 init_bun_compat();
 import * as fs84 from "node:fs";
 import * as path104 from "node:path";
+var _internals = { bunSpawn };
+var _swarmGitExcludedChecked = false;
+function fileCoversSwarm(content) {
+  for (const rawLine of content.split(`
+`)) {
+    const line = rawLine.trim();
+    if (line.startsWith("#") || line.length === 0)
+      continue;
+    if (line === ".swarm" || line === ".swarm/")
+      return true;
+  }
+  return false;
+}
+var ENSURE_SWARM_GIT_EXCLUDED_OUTER_TIMEOUT_MS = 3000;
+var ENSURE_SWARM_GIT_EXCLUDED_PER_CALL_TIMEOUT_MS = 1500;
+var GIT_SPAWN_OPTIONS = {
+  timeout: ENSURE_SWARM_GIT_EXCLUDED_PER_CALL_TIMEOUT_MS,
+  stdin: "ignore",
+  stdout: "pipe",
+  stderr: "pipe"
+};
+async function ensureSwarmGitExcluded(directory, options = {}) {
+  if (_swarmGitExcludedChecked)
+    return;
+  _swarmGitExcludedChecked = true;
+  const { quiet = false } = options;
+  try {
+    const gitRootProc = _internals.bunSpawn(["git", "-C", directory, "rev-parse", "--show-toplevel"], GIT_SPAWN_OPTIONS);
+    let gitRootExitCode;
+    let gitRootOutput;
+    try {
+      [gitRootExitCode, gitRootOutput] = await Promise.all([
+        gitRootProc.exited,
+        gitRootProc.stdout.text()
+      ]);
+    } finally {
+      try {
+        gitRootProc.kill();
+      } catch {}
+    }
+    if (gitRootExitCode !== 0)
+      return;
+    const gitRoot = gitRootOutput.trim();
+    if (!gitRoot)
+      return;
+    const excludePathProc = _internals.bunSpawn(["git", "-C", directory, "rev-parse", "--git-path", "info/exclude"], GIT_SPAWN_OPTIONS);
+    let excludePathExitCode;
+    let excludePathRaw;
+    try {
+      [excludePathExitCode, excludePathRaw] = await Promise.all([
+        excludePathProc.exited,
+        excludePathProc.stdout.text()
+      ]);
+    } finally {
+      try {
+        excludePathProc.kill();
+      } catch {}
+    }
+    if (excludePathExitCode !== 0)
+      return;
+    const excludeRelPath = excludePathRaw.trim();
+    if (!excludeRelPath)
+      return;
+    const excludePath = path104.isAbsolute(excludeRelPath) ? excludeRelPath : path104.join(directory, excludeRelPath);
+    const checkIgnoreProc = _internals.bunSpawn(["git", "-C", directory, "check-ignore", "-q", ".swarm/.gitkeep"], GIT_SPAWN_OPTIONS);
+    let checkIgnoreExitCode;
+    try {
+      checkIgnoreExitCode = await checkIgnoreProc.exited;
+    } finally {
+      try {
+        checkIgnoreProc.kill();
+      } catch {}
+    }
+    if (checkIgnoreExitCode !== 0) {
+      try {
+        fs84.mkdirSync(path104.dirname(excludePath), { recursive: true });
+        let existing = "";
+        try {
+          existing = fs84.readFileSync(excludePath, "utf8");
+        } catch {}
+        if (!fileCoversSwarm(existing)) {
+          fs84.appendFileSync(excludePath, `
+# opencode-swarm local runtime state
+.swarm/
+`, "utf8");
+          if (!quiet) {
+            console.warn("[opencode-swarm] Added .swarm/ to .git/info/exclude to prevent runtime state from appearing in git status.");
+          }
+        }
+      } catch {}
+    }
+    const trackedProc = _internals.bunSpawn(["git", "-C", directory, "ls-files", "--", ".swarm"], GIT_SPAWN_OPTIONS);
+    let trackedExitCode;
+    let trackedOutput;
+    try {
+      [trackedExitCode, trackedOutput] = await Promise.all([
+        trackedProc.exited,
+        trackedProc.stdout.text()
+      ]);
+    } finally {
+      try {
+        trackedProc.kill();
+      } catch {}
+    }
+    if (trackedExitCode === 0 && trackedOutput.trim().length > 0) {
+      console.warn(`[opencode-swarm] WARNING: .swarm/ files are tracked by Git.
+` + `.swarm/ contains local runtime state and may contain sensitive session data.
+` + `Ignoring will not affect already-tracked files. To stop tracking them, run:
+` + `  git rm -r --cached .swarm
+` + `  echo ".swarm/" >> .gitignore
+` + '  git commit -m "Stop tracking opencode-swarm runtime state"');
+    }
+  } catch {}
+}
+
+// src/hooks/diff-scope.ts
+var _internals2 = { bunSpawn };
 function getDeclaredScope(taskId, directory) {
   try {
-    const planPath = path104.join(directory, ".swarm", "plan.json");
-    if (!fs84.existsSync(planPath))
+    const planPath = path105.join(directory, ".swarm", "plan.json");
+    if (!fs85.existsSync(planPath))
       return null;
-    const raw = fs84.readFileSync(planPath, "utf-8");
+    const raw = fs85.readFileSync(planPath, "utf-8");
     const plan = JSON.parse(raw);
     for (const phase of plan.phases ?? []) {
       for (const task of phase.tasks ?? []) {
@@ -89643,30 +89765,47 @@ function getDeclaredScope(taskId, directory) {
     return null;
   }
 }
+var GIT_DIFF_SPAWN_OPTIONS = {
+  timeout: ENSURE_SWARM_GIT_EXCLUDED_PER_CALL_TIMEOUT_MS,
+  stdin: "ignore",
+  stdout: "pipe",
+  stderr: "pipe"
+};
 async function getChangedFiles(directory) {
   try {
-    const proc = bunSpawn(["git", "diff", "--name-only", "HEAD~1"], {
+    const proc = _internals2.bunSpawn(["git", "diff", "--name-only", "HEAD~1"], {
       cwd: directory,
-      stdout: "pipe",
-      stderr: "pipe"
+      ...GIT_DIFF_SPAWN_OPTIONS
     });
-    const [exitCode, stdout] = await Promise.all([
-      proc.exited,
-      proc.stdout.text()
-    ]);
+    let exitCode;
+    let stdout;
+    try {
+      [exitCode, stdout] = await Promise.all([proc.exited, proc.stdout.text()]);
+    } finally {
+      try {
+        proc.kill();
+      } catch {}
+    }
     if (exitCode === 0) {
       return stdout.trim().split(`
 `).map((f) => f.trim()).filter((f) => f.length > 0);
     }
-    const proc2 = bunSpawn(["git", "diff", "--name-only", "HEAD"], {
+    const proc2 = _internals2.bunSpawn(["git", "diff", "--name-only", "HEAD"], {
       cwd: directory,
-      stdout: "pipe",
-      stderr: "pipe"
+      ...GIT_DIFF_SPAWN_OPTIONS
     });
-    const [exitCode2, stdout2] = await Promise.all([
-      proc2.exited,
-      proc2.stdout.text()
-    ]);
+    let exitCode2;
+    let stdout2;
+    try {
+      [exitCode2, stdout2] = await Promise.all([
+        proc2.exited,
+        proc2.stdout.text()
+      ]);
+    } finally {
+      try {
+        proc2.kill();
+      } catch {}
+    }
     if (exitCode2 === 0) {
       return stdout2.trim().split(`
 `).map((f) => f.trim()).filter((f) => f.length > 0);
@@ -89684,9 +89823,10 @@ async function validateDiffScope(taskId, directory) {
     const changedFiles = await getChangedFiles(directory);
     if (!changedFiles)
       return null;
+    const nonSwarmFiles = changedFiles.filter((f) => !f.replace(/\\/g, "/").startsWith(".swarm/"));
     const normalise = (p) => p.replace(/\\/g, "/").replace(/^\.\//, "");
     const normScope = new Set(declaredScope.map(normalise));
-    const undeclared = changedFiles.map(normalise).filter((f) => !normScope.has(f));
+    const undeclared = nonSwarmFiles.map(normalise).filter((f) => !normScope.has(f));
     if (undeclared.length === 0)
       return null;
     const scopeStr = declaredScope.join(", ");
@@ -89738,7 +89878,7 @@ var TIER_3_PATTERNS = [
 ];
 function matchesTier3Pattern(files) {
   for (const file3 of files) {
-    const fileName = path105.basename(file3);
+    const fileName = path106.basename(file3);
     for (const pattern of TIER_3_PATTERNS) {
       if (pattern.test(fileName)) {
         return true;
@@ -89752,8 +89892,8 @@ function checkReviewerGate(taskId, workingDirectory, stageBParallelEnabled = fal
     if (hasActiveTurboMode()) {
       const resolvedDir2 = workingDirectory;
       try {
-        const planPath = path105.join(resolvedDir2, ".swarm", "plan.json");
-        const planRaw = fs85.readFileSync(planPath, "utf-8");
+        const planPath = path106.join(resolvedDir2, ".swarm", "plan.json");
+        const planRaw = fs86.readFileSync(planPath, "utf-8");
         const plan = JSON.parse(planRaw);
         for (const planPhase of plan.phases ?? []) {
           for (const task of planPhase.tasks ?? []) {
@@ -89822,8 +89962,8 @@ function checkReviewerGate(taskId, workingDirectory, stageBParallelEnabled = fal
     }
     try {
       const resolvedDir2 = workingDirectory;
-      const planPath = path105.join(resolvedDir2, ".swarm", "plan.json");
-      const planRaw = fs85.readFileSync(planPath, "utf-8");
+      const planPath = path106.join(resolvedDir2, ".swarm", "plan.json");
+      const planRaw = fs86.readFileSync(planPath, "utf-8");
       const plan = JSON.parse(planRaw);
       for (const planPhase of plan.phases ?? []) {
         for (const task of planPhase.tasks ?? []) {
@@ -90012,8 +90152,8 @@ async function executeUpdateTaskStatus(args2, fallbackDir) {
         };
       }
     }
-    normalizedDir = path105.normalize(args2.working_directory);
-    const pathParts = normalizedDir.split(path105.sep);
+    normalizedDir = path106.normalize(args2.working_directory);
+    const pathParts = normalizedDir.split(path106.sep);
     if (pathParts.includes("..")) {
       return {
         success: false,
@@ -90023,11 +90163,11 @@ async function executeUpdateTaskStatus(args2, fallbackDir) {
         ]
       };
     }
-    const resolvedDir = path105.resolve(normalizedDir);
+    const resolvedDir = path106.resolve(normalizedDir);
     try {
-      const realPath = fs85.realpathSync(resolvedDir);
-      const planPath = path105.join(realPath, ".swarm", "plan.json");
-      if (!fs85.existsSync(planPath)) {
+      const realPath = fs86.realpathSync(resolvedDir);
+      const planPath = path106.join(realPath, ".swarm", "plan.json");
+      if (!fs86.existsSync(planPath)) {
         return {
           success: false,
           message: `Invalid working_directory: plan not found in "${realPath}"`,
@@ -90058,22 +90198,22 @@ async function executeUpdateTaskStatus(args2, fallbackDir) {
   }
   if (args2.status === "in_progress") {
     try {
-      const evidencePath = path105.join(directory, ".swarm", "evidence", `${args2.task_id}.json`);
-      fs85.mkdirSync(path105.dirname(evidencePath), { recursive: true });
-      const fd = fs85.openSync(evidencePath, "wx");
+      const evidencePath = path106.join(directory, ".swarm", "evidence", `${args2.task_id}.json`);
+      fs86.mkdirSync(path106.dirname(evidencePath), { recursive: true });
+      const fd = fs86.openSync(evidencePath, "wx");
       let writeOk = false;
       try {
-        fs85.writeSync(fd, JSON.stringify({
+        fs86.writeSync(fd, JSON.stringify({
           taskId: args2.task_id,
           required_gates: ["reviewer", "test_engineer"],
           gates: {}
         }, null, 2));
         writeOk = true;
       } finally {
-        fs85.closeSync(fd);
+        fs86.closeSync(fd);
         if (!writeOk) {
           try {
-            fs85.unlinkSync(evidencePath);
+            fs86.unlinkSync(evidencePath);
           } catch {}
         }
       }
@@ -90083,8 +90223,8 @@ async function executeUpdateTaskStatus(args2, fallbackDir) {
     recoverTaskStateFromDelegations(args2.task_id);
     let phaseRequiresReviewer = true;
     try {
-      const planPath = path105.join(directory, ".swarm", "plan.json");
-      const planRaw = fs85.readFileSync(planPath, "utf-8");
+      const planPath = path106.join(directory, ".swarm", "plan.json");
+      const planRaw = fs86.readFileSync(planPath, "utf-8");
       const plan = JSON.parse(planRaw);
       const taskPhase = plan.phases.find((p) => p.tasks.some((t) => t.id === args2.task_id));
       if (taskPhase?.required_agents && !taskPhase.required_agents.includes("reviewer")) {
@@ -90394,8 +90534,8 @@ init_utils2();
 init_ledger();
 init_manager();
 init_create_tool();
-import fs86 from "node:fs";
-import path106 from "node:path";
+import fs87 from "node:fs";
+import path107 from "node:path";
 function derivePlanId5(plan) {
   return `${plan.swarm}-${plan.title}`.replace(/[^a-zA-Z0-9-_]/g, "_");
 }
@@ -90446,7 +90586,7 @@ async function executeWriteDriftEvidence(args2, directory) {
     entries: [evidenceEntry]
   };
   const filename = "drift-verifier.json";
-  const relativePath = path106.join("evidence", String(phase), filename);
+  const relativePath = path107.join("evidence", String(phase), filename);
   let validatedPath;
   try {
     validatedPath = validateSwarmPath(directory, relativePath);
@@ -90457,12 +90597,12 @@ async function executeWriteDriftEvidence(args2, directory) {
       message: error93 instanceof Error ? error93.message : "Failed to validate path"
     }, null, 2);
   }
-  const evidenceDir = path106.dirname(validatedPath);
+  const evidenceDir = path107.dirname(validatedPath);
   try {
-    await fs86.promises.mkdir(evidenceDir, { recursive: true });
-    const tempPath = path106.join(evidenceDir, `.${filename}.tmp`);
-    await fs86.promises.writeFile(tempPath, JSON.stringify(evidenceContent, null, 2), "utf-8");
-    await fs86.promises.rename(tempPath, validatedPath);
+    await fs87.promises.mkdir(evidenceDir, { recursive: true });
+    const tempPath = path107.join(evidenceDir, `.${filename}.tmp`);
+    await fs87.promises.writeFile(tempPath, JSON.stringify(evidenceContent, null, 2), "utf-8");
+    await fs87.promises.rename(tempPath, validatedPath);
     let snapshotInfo;
     let snapshotError;
     let qaProfileLocked;
@@ -90556,8 +90696,8 @@ var write_drift_evidence = createSwarmTool({
 init_zod();
 init_utils2();
 init_create_tool();
-import fs87 from "node:fs";
-import path107 from "node:path";
+import fs88 from "node:fs";
+import path108 from "node:path";
 function normalizeVerdict2(verdict) {
   switch (verdict) {
     case "APPROVED":
@@ -90605,7 +90745,7 @@ async function executeWriteHallucinationEvidence(args2, directory) {
     entries: [evidenceEntry]
   };
   const filename = "hallucination-guard.json";
-  const relativePath = path107.join("evidence", String(phase), filename);
+  const relativePath = path108.join("evidence", String(phase), filename);
   let validatedPath;
   try {
     validatedPath = validateSwarmPath(directory, relativePath);
@@ -90616,12 +90756,12 @@ async function executeWriteHallucinationEvidence(args2, directory) {
       message: error93 instanceof Error ? error93.message : "Failed to validate path"
     }, null, 2);
   }
-  const evidenceDir = path107.dirname(validatedPath);
+  const evidenceDir = path108.dirname(validatedPath);
   try {
-    await fs87.promises.mkdir(evidenceDir, { recursive: true });
-    const tempPath = path107.join(evidenceDir, `.${filename}.tmp`);
-    await fs87.promises.writeFile(tempPath, JSON.stringify(evidenceContent, null, 2), "utf-8");
-    await fs87.promises.rename(tempPath, validatedPath);
+    await fs88.promises.mkdir(evidenceDir, { recursive: true });
+    const tempPath = path108.join(evidenceDir, `.${filename}.tmp`);
+    await fs88.promises.writeFile(tempPath, JSON.stringify(evidenceContent, null, 2), "utf-8");
+    await fs88.promises.rename(tempPath, validatedPath);
     return JSON.stringify({
       success: true,
       phase,
@@ -90667,8 +90807,8 @@ var write_hallucination_evidence = createSwarmTool({
 init_zod();
 init_utils2();
 init_create_tool();
-import fs88 from "node:fs";
-import path108 from "node:path";
+import fs89 from "node:fs";
+import path109 from "node:path";
 function normalizeVerdict3(verdict) {
   switch (verdict) {
     case "PASS":
@@ -90742,7 +90882,7 @@ async function executeWriteMutationEvidence(args2, directory) {
     entries: [evidenceEntry]
   };
   const filename = "mutation-gate.json";
-  const relativePath = path108.join("evidence", String(phase), filename);
+  const relativePath = path109.join("evidence", String(phase), filename);
   let validatedPath;
   try {
     validatedPath = validateSwarmPath(directory, relativePath);
@@ -90753,12 +90893,12 @@ async function executeWriteMutationEvidence(args2, directory) {
       message: error93 instanceof Error ? error93.message : "Failed to validate path"
     }, null, 2);
   }
-  const evidenceDir = path108.dirname(validatedPath);
+  const evidenceDir = path109.dirname(validatedPath);
   try {
-    await fs88.promises.mkdir(evidenceDir, { recursive: true });
-    const tempPath = path108.join(evidenceDir, `.${filename}.tmp`);
-    await fs88.promises.writeFile(tempPath, JSON.stringify(evidenceContent, null, 2), "utf-8");
-    await fs88.promises.rename(tempPath, validatedPath);
+    await fs89.promises.mkdir(evidenceDir, { recursive: true });
+    const tempPath = path109.join(evidenceDir, `.${filename}.tmp`);
+    await fs89.promises.writeFile(tempPath, JSON.stringify(evidenceContent, null, 2), "utf-8");
+    await fs89.promises.rename(tempPath, validatedPath);
     return JSON.stringify({
       success: true,
       phase,
@@ -90811,69 +90951,6 @@ init_write_retro();
 // src/index.ts
 init_utils();
 
-// src/utils/gitignore-warning.ts
-import * as fs89 from "node:fs";
-import * as path109 from "node:path";
-var _gitignoreWarningEmitted = false;
-function findGitRoot(startDir) {
-  let current = startDir;
-  while (true) {
-    try {
-      const gitPath = path109.join(current, ".git");
-      const stat6 = fs89.statSync(gitPath);
-      if (stat6.isDirectory()) {
-        return current;
-      }
-    } catch {}
-    const parent = path109.dirname(current);
-    if (parent === current) {
-      return null;
-    }
-    current = parent;
-  }
-}
-function fileCoversSwarm(content) {
-  for (const rawLine of content.split(`
-`)) {
-    const line = rawLine.trim();
-    if (line.startsWith("#") || line.length === 0)
-      continue;
-    if (line === ".swarm" || line === ".swarm/")
-      return true;
-  }
-  return false;
-}
-function readFileSafe(filePath) {
-  try {
-    return fs89.readFileSync(filePath, "utf8");
-  } catch {
-    return null;
-  }
-}
-function warnIfSwarmNotGitignored(directory, quiet = false) {
-  if (_gitignoreWarningEmitted)
-    return;
-  try {
-    const gitRoot = findGitRoot(directory);
-    if (!gitRoot)
-      return;
-    const gitignoreContent = readFileSafe(path109.join(gitRoot, ".gitignore"));
-    if (gitignoreContent !== null && fileCoversSwarm(gitignoreContent)) {
-      _gitignoreWarningEmitted = true;
-      return;
-    }
-    const excludeContent = readFileSafe(path109.join(gitRoot, ".git", "info", "exclude"));
-    if (excludeContent !== null && fileCoversSwarm(excludeContent)) {
-      _gitignoreWarningEmitted = true;
-      return;
-    }
-    _gitignoreWarningEmitted = true;
-    if (!quiet) {
-      console.warn('[opencode-swarm] WARNING: .swarm/ is not in your .gitignore. Shell audit logs may contain API keys. Add ".swarm/" to your .gitignore to prevent accidental commits.');
-    }
-  } catch {}
-}
-
 // src/utils/tool-output.ts
 function truncateToolOutput(output, maxLines, toolName, tailLines = 10) {
   if (!output) {
@@ -90977,10 +91054,15 @@ async function initializeOpenCodeSwarm(ctx) {
     }
     repoGraphHook.init().catch(() => {}).finally(() => clearTimeout(watchdog));
   });
+  await withTimeout(ensureSwarmGitExcluded(ctx.directory, { quiet: config3.quiet }), ENSURE_SWARM_GIT_EXCLUDED_OUTER_TIMEOUT_MS, new Error(`ensureSwarmGitExcluded exceeded ${ENSURE_SWARM_GIT_EXCLUDED_OUTER_TIMEOUT_MS}ms budget; continuing without git-hygiene check`)).catch((err3) => {
+    const msg = err3 instanceof Error ? err3.message : String(err3);
+    log("ensureSwarmGitExcluded timed out or failed (non-fatal)", {
+      error: msg
+    });
+  });
   initTelemetry(ctx.directory);
   writeSwarmConfigExampleIfNew(ctx.directory);
   writeProjectConfigIfNew(ctx.directory, config3.quiet);
-  warnIfSwarmNotGitignored(ctx.directory, config3.quiet);
   if (config3.version_check !== false) {
     scheduleVersionCheck(package_default.version, (msg) => {
       if (config3.quiet) {

package/dist/utils/gitignore-warning.d.ts

@@ -1,3 +1,15 @@
+import { bunSpawn } from './bun-compat';
+/**
+ * Test-only dependency-injection seam. Production code calls
+ * `_internals.bunSpawn(...)` so tests can replace the function on this object
+ * without touching the real `./bun-compat` module — `mock.module` from
+ * `bun:test` leaks across files in Bun's shared test-runner process, which
+ * would corrupt unrelated suites that import `bun-compat`. Mutating this
+ * local object is file-scoped and trivially restorable via `afterEach`.
+ */
+export declare const _internals: {
+    bunSpawn: typeof bunSpawn;
+};
 /**
  * Module-level flag so the warning fires at most once per process.
  * Exported for test reset purposes only — do not use in production code.
@@ -7,11 +19,71 @@ export declare let _gitignoreWarningEmitted: boolean;
  * Reset the deduplication flag. Exposed for test isolation only.
  */
 export declare function resetGitignoreWarningState(): void;
+/**
+ * Module-level flag for ensureSwarmGitExcluded deduplication.
+ * Exported for test reset purposes only.
+ */
+export declare let _swarmGitExcludedChecked: boolean;
+/**
+ * Reset the ensureSwarmGitExcluded deduplication flag. Exposed for test isolation only.
+ */
+export declare function resetSwarmGitExcludedState(): void;
 /**
  * Checks whether `.swarm/` is covered by `.gitignore` or `.git/info/exclude`
  * in the git repo rooted at or above `directory`. If not covered, emits a
  * single `console.warn` (unless `quiet` is true). Fires at most once per process.
  *
  * Never throws — any file-system error silently skips the check.
+ *
+ * @deprecated Use `ensureSwarmGitExcluded` instead. This function only recognises
+ * `.git` as a directory and does NOT handle Git worktrees or submodules.
  */
 export declare function warnIfSwarmNotGitignored(directory: string, quiet?: boolean): void;
+export interface EnsureSwarmGitExcludedOptions {
+    quiet?: boolean;
+}
+/**
+ * Hard upper bound on the entire `ensureSwarmGitExcluded` operation when
+ * called from plugin init. The plugin host (OpenCode TUI / Desktop) will
+ * silently drop a plugin whose entry never resolves (issue #704); every
+ * awaited call on the init path therefore has an obligation to be bounded.
+ *
+ * 3_000 ms is ~30× the realistic worst-case duration on a healthy host (all
+ * four `git` calls land in well under 200 ms in aggregate) and ~6× the
+ * per-call budget below. Slower-than-3 s hosts are pathological (NFS-stalled
+ * `.git`, antivirus quarantine) and we deliberately fail-open: a debug log
+ * is emitted and the plugin continues to load without the hygiene exclude.
+ */
+export declare const ENSURE_SWARM_GIT_EXCLUDED_OUTER_TIMEOUT_MS = 3000;
+/**
+ * Hard upper bound on each individual `git` subprocess invoked by
+ * `ensureSwarmGitExcluded` (and reused by `validateDiffScope`). Both Bun's
+ * `Bun.spawn` and the Node fallback in `bunSpawn` honor this `timeout`
+ * option and kill the child on expiry (`bun-compat.ts` Node fallback calls
+ * `proc.kill('SIGKILL')`; Bun kills via `killSignal`).
+ *
+ * 1_500 ms gives a ~30× margin over the realistic worst case and is well
+ * below the outer wrapper budget so the inner kills fire first on a
+ * pathological host.
+ */
+export declare const ENSURE_SWARM_GIT_EXCLUDED_PER_CALL_TIMEOUT_MS = 1500;
+/**
+ * Automatically protect `.swarm/` from Git pollution before any `.swarm/` write.
+ *
+ * Uses git CLI (not filesystem walks) so it correctly handles Git worktrees
+ * and submodules where `.git` is a file rather than a directory.
+ *
+ * Steps:
+ * 1. Resolve git root via `git rev-parse --show-toplevel`
+ * 2. Resolve local exclude path via `git rev-parse --git-path info/exclude`
+ * 3. Check if `.swarm/` is already ignored via `git check-ignore -q`
+ * 4. If not ignored: append `.swarm/` to the local exclude file (idempotent)
+ * 5. Detect tracked `.swarm/` files via `git ls-files -- .swarm`
+ * 6. If tracked: emit an unsuppressed remediation warning
+ *
+ * Never throws. Fires at most once per process.
+ *
+ * quiet option: only suppresses cosmetic logs. The exclude write and tracked-file
+ * warning are never suppressed regardless of quiet mode.
+ */
+export declare function ensureSwarmGitExcluded(directory: string, options?: EnsureSwarmGitExcludedOptions): Promise<void>;

package/package.json

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