opencode-swarm-plugin 0.27.0 → 0.27.3

package/.turbo/turbo-build.log

@@ -1,9 +1,9 @@
 $ bun build ./src/index.ts --outdir ./dist --target node --external @electric-sql/pglite --external swarm-mail && bun build ./src/plugin.ts --outfile ./dist/plugin.js --target node --external @electric-sql/pglite --external swarm-mail && tsc
-Bundled 200 modules in 42ms
+Bundled 200 modules in 41ms
 
   index.js  1.19 MB  (entry point)
 
-Bundled 201 modules in 42ms
+Bundled 201 modules in 39ms
 
   plugin.js  1.16 MB  (entry point)
 

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # opencode-swarm-plugin
 
+## 0.27.3
+
+### Patch Changes
+
+- [`ec23d25`](https://github.com/joelhooks/swarm-tools/commit/ec23d25aeca667c0294a6255fecf11dd7d7fd6b3) Thanks [@joelhooks](https://github.com/joelhooks)! - Add .beads → .hive directory migration support
+
+  - Fix migration version collision: beadsMigration now v7, cellsViewMigration now v8 (was conflicting with streams v6)
+  - Add `checkBeadsMigrationNeeded()` to detect legacy .beads directories
+  - Add `migrateBeadsToHive()` to rename .beads to .hive
+  - Add `ensureHiveDirectory()` to create .hive if missing (called by hive_sync)
+  - Update hive_sync to ensure .hive directory exists before writing
+  - Add migration prompt to `swarm setup` CLI flow
+
+- Updated dependencies [[`ec23d25`](https://github.com/joelhooks/swarm-tools/commit/ec23d25aeca667c0294a6255fecf11dd7d7fd6b3)]:
+  - swarm-mail@0.3.3
+
+## 0.27.2
+
+### Patch Changes
+
+- [`50a2bf5`](https://github.com/joelhooks/swarm-tools/commit/50a2bf51c5320c038f202191d7acbfd2179f2cb3) Thanks [@joelhooks](https://github.com/joelhooks)! - Fix cells view migration not being applied
+
+  The v7 migration (cellsViewMigration) that creates the `cells` view was added after
+  swarm-mail@0.3.0 was published. This caused `hive_sync` to fail with
+  "relation cells does not exist" because the JSONL export queries the `cells` view.
+
+  This patch ensures the v7 migration is included in the published package.
+
+- Updated dependencies [[`50a2bf5`](https://github.com/joelhooks/swarm-tools/commit/50a2bf51c5320c038f202191d7acbfd2179f2cb3)]:
+  - swarm-mail@0.3.2
+
 ## 0.27.0
 
 ### Minor Changes

package/bin/swarm.ts

@@ -27,6 +27,10 @@ import {
 import { homedir } from "os";
 import { basename, dirname, join } from "path";
 import { fileURLToPath } from "url";
+import {
+  checkBeadsMigrationNeeded,
+  migrateBeadsToHive,
+} from "../src/hive";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(
@@ -336,46 +340,8 @@ const DEPENDENCIES: Dependency[] = [
     installType: "brew",
     description: "AI coding assistant (plugin host)",
   },
-  {
-    name: "Beads",
-    command: "bd",
-    checkArgs: ["--version"],
-    required: true,
-    install:
-      "curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash",
-    installType: "curl",
-    description: "Git-backed issue tracking",
-  },
-  {
-    name: "Go",
-    command: "go",
-    checkArgs: ["version"],
-    required: false,
-    install: "brew install go",
-    installType: "brew",
-    description: "Required for Agent Mail",
-  },
-  {
-    name: "MCP Agent Mail",
-    command: "curl",
-    checkArgs: [
-      "-s",
-      "-X",
-      "POST",
-      "http://localhost:8765/mcp",
-      "-H",
-      "Content-Type: application/json",
-      "-d",
-      "{}",
-      "-o",
-      "/dev/null",
-    ],
-    required: false,
-    install: "https://github.com/Dicklesworthstone/mcp_agent_mail",
-    installType: "manual",
-    description:
-      "Multi-agent coordination & file reservations (like Gmail for coding agents)",
-  },
+  // Note: Beads CLI (bd) is NO LONGER required - we use HiveAdapter from swarm-mail
+  // which provides the same functionality programmatically without external dependencies
   {
     name: "CASS (Coding Agent Session Search)",
     command: "cass",
@@ -1136,16 +1102,10 @@ function getFixCommand(dep: Dependency): string | null {
   switch (dep.name) {
     case "OpenCode":
       return "brew install sst/tap/opencode";
-    case "Beads":
-      return "curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash";
-    case "Go":
-      return "brew install go (or visit https://go.dev/dl/)";
     case "semantic-memory":
       return "npm install -g semantic-memory";
     case "Redis":
       return "brew install redis && brew services start redis";
-    case "MCP Agent Mail":
-      return "See: https://github.com/Dicklesworthstone/mcp_agent_mail";
     case "CASS (Coding Agent Session Search)":
       return "See: https://github.com/Dicklesworthstone/coding_agent_session_search";
     case "UBS (Ultimate Bug Scanner)":
@@ -1534,6 +1494,45 @@ async function setup() {
     }
   }
 
+  // Check for .beads → .hive migration
+  const cwd = process.cwd();
+  const migrationCheck = checkBeadsMigrationNeeded(cwd);
+  if (migrationCheck.needed) {
+    p.log.step("Legacy .beads directory detected");
+    p.log.message(dim("  Found: " + migrationCheck.beadsPath));
+    
+    const shouldMigrate = await p.confirm({
+      message: "Migrate .beads to .hive? (recommended)",
+      initialValue: true,
+    });
+
+    if (p.isCancel(shouldMigrate)) {
+      p.cancel("Setup cancelled");
+      process.exit(0);
+    }
+
+    if (shouldMigrate) {
+      const migrateSpinner = p.spinner();
+      migrateSpinner.start("Migrating .beads to .hive...");
+      
+      try {
+        const result = await migrateBeadsToHive(cwd);
+        if (result.migrated) {
+          migrateSpinner.stop("Migration complete");
+          p.log.success("Renamed .beads/ → .hive/");
+        } else {
+          migrateSpinner.stop("Migration skipped");
+          p.log.warn(result.reason || "Unknown reason");
+        }
+      } catch (error) {
+        migrateSpinner.stop("Migration failed");
+        p.log.error(error instanceof Error ? error.message : String(error));
+      }
+    } else {
+      p.log.warn("Skipping migration - .beads will continue to work but is deprecated");
+    }
+  }
+
   // Model selection
   p.log.step("Configure swarm agents...");
 

package/dist/hive.d.ts

@@ -32,6 +32,54 @@ export declare class HiveValidationError extends Error {
     constructor(message: string, zodError: z.ZodError);
 }
 export declare const BeadValidationError: typeof HiveValidationError;
+/**
+ * Result of checking if .beads → .hive migration is needed
+ */
+export interface MigrationCheckResult {
+    /** Whether migration is needed */
+    needed: boolean;
+    /** Path to .beads directory if it exists */
+    beadsPath?: string;
+}
+/**
+ * Result of migrating .beads → .hive
+ */
+export interface MigrationResult {
+    /** Whether migration was performed */
+    migrated: boolean;
+    /** Reason if migration was skipped */
+    reason?: string;
+}
+/**
+ * Check if .beads → .hive migration is needed
+ *
+ * Migration is needed when:
+ * - .beads directory exists
+ * - .hive directory does NOT exist
+ *
+ * @param projectPath - Absolute path to the project root
+ * @returns MigrationCheckResult indicating if migration is needed
+ */
+export declare function checkBeadsMigrationNeeded(projectPath: string): MigrationCheckResult;
+/**
+ * Migrate .beads directory to .hive
+ *
+ * This function renames .beads to .hive. It should only be called
+ * after user confirmation via CLI prompt.
+ *
+ * @param projectPath - Absolute path to the project root
+ * @returns MigrationResult indicating success or skip reason
+ */
+export declare function migrateBeadsToHive(projectPath: string): Promise<MigrationResult>;
+/**
+ * Ensure .hive directory exists
+ *
+ * Creates .hive directory if it doesn't exist. This is idempotent
+ * and safe to call multiple times.
+ *
+ * @param projectPath - Absolute path to the project root
+ */
+export declare function ensureHiveDirectory(projectPath: string): void;
 /**
  * Get or create a HiveAdapter instance for a project
  * Exported for testing - allows tests to verify state directly

package/dist/hive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hive.d.ts","sourceRoot":"","sources":["../src/hive.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hive.d.ts","sourceRoot":"","sources":["../src/hive.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -27741,6 +27741,43 @@ class HiveValidationError extends Error {
   }
 }
 var BeadValidationError = HiveValidationError;
+function checkBeadsMigrationNeeded(projectPath) {
+  const beadsDir = join(projectPath, ".beads");
+  const hiveDir = join(projectPath, ".hive");
+  if (existsSync(hiveDir)) {
+    return { needed: false };
+  }
+  if (existsSync(beadsDir)) {
+    return { needed: true, beadsPath: beadsDir };
+  }
+  return { needed: false };
+}
+async function migrateBeadsToHive(projectPath) {
+  const beadsDir = join(projectPath, ".beads");
+  const hiveDir = join(projectPath, ".hive");
+  if (existsSync(hiveDir)) {
+    return {
+      migrated: false,
+      reason: ".hive directory already exists - skipping migration to avoid data loss"
+    };
+  }
+  if (!existsSync(beadsDir)) {
+    return {
+      migrated: false,
+      reason: ".beads directory not found - nothing to migrate"
+    };
+  }
+  const { renameSync } = await import("node:fs");
+  renameSync(beadsDir, hiveDir);
+  return { migrated: true };
+}
+function ensureHiveDirectory(projectPath) {
+  const hiveDir = join(projectPath, ".hive");
+  if (!existsSync(hiveDir)) {
+    const { mkdirSync } = __require("node:fs");
+    mkdirSync(hiveDir, { recursive: true });
+  }
+}
 var adapterCache = new Map;
 async function getHiveAdapter(projectKey) {
   if (adapterCache.has(projectKey)) {
@@ -28075,6 +28112,7 @@ var hive_sync = tool({
         }
       }
     };
+    ensureHiveDirectory(projectKey);
     const flushManager = new FlushManager({
       adapter,
       projectKey,
@@ -35959,6 +35997,7 @@ export {
   requireTool,
   repoCrawlTools,
   parseFrontmatter,
+  migrateBeadsToHive,
   mcpCallWithAutoInit,
   mandateTools,
   mandateSchemas,
@@ -36012,6 +36051,7 @@ export {
   extractJsonFromText,
   evaluatePromotion,
   evaluateBatchPromotions,
+  ensureHiveDirectory,
   discoverSkills,
   src_default as default,
   createStorageWithFallback,
@@ -36024,6 +36064,7 @@ export {
   createAgentMailError,
   clearSessionState,
   checkTool,
+  checkBeadsMigrationNeeded,
   checkAllTools,
   beads_update,
   beads_sync,

package/dist/plugin.js

@@ -27633,6 +27633,13 @@ class HiveError extends Error {
     this.name = "HiveError";
   }
 }
+function ensureHiveDirectory(projectPath) {
+  const hiveDir = join(projectPath, ".hive");
+  if (!existsSync(hiveDir)) {
+    const { mkdirSync } = __require("node:fs");
+    mkdirSync(hiveDir, { recursive: true });
+  }
+}
 var adapterCache = new Map;
 async function getHiveAdapter(projectKey) {
   if (adapterCache.has(projectKey)) {
@@ -27966,6 +27973,7 @@ var hive_sync = tool({
         }
       }
     };
+    ensureHiveDirectory(projectKey);
     const flushManager = new FlushManager({
       adapter,
       projectKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.27.0",
+  "version": "0.27.3",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,7 +33,7 @@
     "@opencode-ai/plugin": "^1.0.134",
     "gray-matter": "^4.0.3",
     "ioredis": "^5.4.1",
-    "swarm-mail": "0.3.0",
+    "swarm-mail": "0.3.3",
     "zod": "4.1.8"
   },
   "devDependencies": {

package/src/hive.integration.test.ts

@@ -20,13 +20,6 @@ import {
   getHiveAdapter,
   setHiveWorkingDirectory,
   // Legacy aliases for backward compatibility tests
-  hive_create,
-  hive_create_epic,
-  hive_query,
-  hive_update,
-  hive_close,
-  hive_start,
-  hive_ready,
   beads_link_thread,
   BeadError,
   getBeadsAdapter,
@@ -691,4 +684,150 @@ describe("beads integration", () => {
       }
     });
   });
+
+  describe("Directory Migration (.beads → .hive)", () => {
+    it("checkBeadsMigrationNeeded detects .beads without .hive", async () => {
+      const { checkBeadsMigrationNeeded } = await import("./hive");
+      const { mkdirSync, rmSync, writeFileSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { tmpdir } = await import("node:os");
+      
+      // Create temp project with .beads directory only
+      const tempProject = join(tmpdir(), `hive-migration-test-${Date.now()}`);
+      const beadsDir = join(tempProject, ".beads");
+      
+      mkdirSync(beadsDir, { recursive: true });
+      writeFileSync(join(beadsDir, "issues.jsonl"), '{"id":"bd-test","title":"Test"}');
+      
+      const result = checkBeadsMigrationNeeded(tempProject);
+      
+      expect(result.needed).toBe(true);
+      expect(result.beadsPath).toBe(beadsDir);
+      
+      // Cleanup
+      rmSync(tempProject, { recursive: true, force: true });
+    });
+
+    it("checkBeadsMigrationNeeded returns false if .hive exists", async () => {
+      const { checkBeadsMigrationNeeded } = await import("./hive");
+      const { mkdirSync, rmSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { tmpdir } = await import("node:os");
+      
+      // Create temp project with .hive directory
+      const tempProject = join(tmpdir(), `hive-migration-test-${Date.now()}`);
+      const hiveDir = join(tempProject, ".hive");
+      
+      mkdirSync(hiveDir, { recursive: true });
+      
+      const result = checkBeadsMigrationNeeded(tempProject);
+      
+      expect(result.needed).toBe(false);
+      
+      // Cleanup
+      rmSync(tempProject, { recursive: true, force: true });
+    });
+
+    it("migrateBeadsToHive renames .beads to .hive", async () => {
+      const { migrateBeadsToHive } = await import("./hive");
+      const { mkdirSync, existsSync, rmSync, writeFileSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { tmpdir } = await import("node:os");
+      
+      // Create temp project with .beads directory
+      const tempProject = join(tmpdir(), `hive-migration-test-${Date.now()}`);
+      const beadsDir = join(tempProject, ".beads");
+      const hiveDir = join(tempProject, ".hive");
+      
+      mkdirSync(beadsDir, { recursive: true });
+      writeFileSync(join(beadsDir, "issues.jsonl"), '{"id":"bd-test","title":"Test"}');
+      writeFileSync(join(beadsDir, "config.yaml"), "version: 1");
+      
+      // Run migration (called after user confirms in CLI)
+      const result = await migrateBeadsToHive(tempProject);
+      
+      // Verify .beads renamed to .hive
+      expect(result.migrated).toBe(true);
+      expect(existsSync(hiveDir)).toBe(true);
+      expect(existsSync(beadsDir)).toBe(false);
+      expect(existsSync(join(hiveDir, "issues.jsonl"))).toBe(true);
+      expect(existsSync(join(hiveDir, "config.yaml"))).toBe(true);
+      
+      // Cleanup
+      rmSync(tempProject, { recursive: true, force: true });
+    });
+
+    it("migrateBeadsToHive skips if .hive already exists", async () => {
+      const { migrateBeadsToHive } = await import("./hive");
+      const { mkdirSync, existsSync, rmSync, writeFileSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { tmpdir } = await import("node:os");
+      
+      // Create temp project with BOTH .beads and .hive
+      const tempProject = join(tmpdir(), `hive-migration-test-${Date.now()}`);
+      const beadsDir = join(tempProject, ".beads");
+      const hiveDir = join(tempProject, ".hive");
+      
+      mkdirSync(beadsDir, { recursive: true });
+      mkdirSync(hiveDir, { recursive: true });
+      writeFileSync(join(beadsDir, "issues.jsonl"), '{"id":"bd-old"}');
+      writeFileSync(join(hiveDir, "issues.jsonl"), '{"id":"bd-new"}');
+      
+      // Run migration - should skip
+      const result = await migrateBeadsToHive(tempProject);
+      
+      // Verify both still exist (no migration)
+      expect(result.migrated).toBe(false);
+      expect(result.reason).toContain("already exists");
+      expect(existsSync(beadsDir)).toBe(true);
+      expect(existsSync(hiveDir)).toBe(true);
+      
+      // Cleanup
+      rmSync(tempProject, { recursive: true, force: true });
+    });
+
+    it("ensureHiveDirectory creates .hive if missing", async () => {
+      const { ensureHiveDirectory } = await import("./hive");
+      const { mkdirSync, existsSync, rmSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { tmpdir } = await import("node:os");
+      
+      // Create empty temp project
+      const tempProject = join(tmpdir(), `hive-ensure-test-${Date.now()}`);
+      mkdirSync(tempProject, { recursive: true });
+      
+      const hiveDir = join(tempProject, ".hive");
+      expect(existsSync(hiveDir)).toBe(false);
+      
+      // Ensure creates it
+      ensureHiveDirectory(tempProject);
+      
+      expect(existsSync(hiveDir)).toBe(true);
+      
+      // Cleanup
+      rmSync(tempProject, { recursive: true, force: true });
+    });
+
+    it("ensureHiveDirectory is idempotent", async () => {
+      const { ensureHiveDirectory } = await import("./hive");
+      const { mkdirSync, existsSync, rmSync, writeFileSync, readFileSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { tmpdir } = await import("node:os");
+      
+      // Create temp project with existing .hive
+      const tempProject = join(tmpdir(), `hive-ensure-test-${Date.now()}`);
+      const hiveDir = join(tempProject, ".hive");
+      mkdirSync(hiveDir, { recursive: true });
+      writeFileSync(join(hiveDir, "issues.jsonl"), '{"id":"existing"}');
+      
+      // Ensure doesn't overwrite
+      ensureHiveDirectory(tempProject);
+      
+      expect(existsSync(hiveDir)).toBe(true);
+      expect(readFileSync(join(hiveDir, "issues.jsonl"), "utf-8")).toBe('{"id":"existing"}');
+      
+      // Cleanup
+      rmSync(tempProject, { recursive: true, force: true });
+    });
+  });
 });

package/src/hive.ts

@@ -130,6 +130,111 @@ export class HiveValidationError extends Error {
 // Legacy alias for backward compatibility
 export const BeadValidationError = HiveValidationError;
 
+// ============================================================================
+// Directory Migration (.beads → .hive)
+// ============================================================================
+
+/**
+ * Result of checking if .beads → .hive migration is needed
+ */
+export interface MigrationCheckResult {
+  /** Whether migration is needed */
+  needed: boolean;
+  /** Path to .beads directory if it exists */
+  beadsPath?: string;
+}
+
+/**
+ * Result of migrating .beads → .hive
+ */
+export interface MigrationResult {
+  /** Whether migration was performed */
+  migrated: boolean;
+  /** Reason if migration was skipped */
+  reason?: string;
+}
+
+/**
+ * Check if .beads → .hive migration is needed
+ * 
+ * Migration is needed when:
+ * - .beads directory exists
+ * - .hive directory does NOT exist
+ * 
+ * @param projectPath - Absolute path to the project root
+ * @returns MigrationCheckResult indicating if migration is needed
+ */
+export function checkBeadsMigrationNeeded(projectPath: string): MigrationCheckResult {
+  const beadsDir = join(projectPath, ".beads");
+  const hiveDir = join(projectPath, ".hive");
+  
+  // If .hive already exists, no migration needed
+  if (existsSync(hiveDir)) {
+    return { needed: false };
+  }
+  
+  // If .beads exists but .hive doesn't, migration is needed
+  if (existsSync(beadsDir)) {
+    return { needed: true, beadsPath: beadsDir };
+  }
+  
+  // Neither exists - no migration needed
+  return { needed: false };
+}
+
+/**
+ * Migrate .beads directory to .hive
+ * 
+ * This function renames .beads to .hive. It should only be called
+ * after user confirmation via CLI prompt.
+ * 
+ * @param projectPath - Absolute path to the project root
+ * @returns MigrationResult indicating success or skip reason
+ */
+export async function migrateBeadsToHive(projectPath: string): Promise<MigrationResult> {
+  const beadsDir = join(projectPath, ".beads");
+  const hiveDir = join(projectPath, ".hive");
+  
+  // Check if .hive already exists - skip migration
+  if (existsSync(hiveDir)) {
+    return { 
+      migrated: false, 
+      reason: ".hive directory already exists - skipping migration to avoid data loss" 
+    };
+  }
+  
+  // Check if .beads exists
+  if (!existsSync(beadsDir)) {
+    return { 
+      migrated: false, 
+      reason: ".beads directory not found - nothing to migrate" 
+    };
+  }
+  
+  // Perform the rename
+  const { renameSync } = await import("node:fs");
+  renameSync(beadsDir, hiveDir);
+  
+  return { migrated: true };
+}
+
+/**
+ * Ensure .hive directory exists
+ * 
+ * Creates .hive directory if it doesn't exist. This is idempotent
+ * and safe to call multiple times.
+ * 
+ * @param projectPath - Absolute path to the project root
+ */
+export function ensureHiveDirectory(projectPath: string): void {
+  const hiveDir = join(projectPath, ".hive");
+  
+  if (!existsSync(hiveDir)) {
+    const { mkdirSync } = require("node:fs");
+    mkdirSync(hiveDir, { recursive: true });
+  }
+}
+
 // ============================================================================
 // Adapter Singleton
 // ============================================================================
@@ -714,7 +819,10 @@ export const hive_sync = tool({
       }
     };
 
-    // 1. Flush cells to JSONL using FlushManager
+    // 1. Ensure .hive directory exists before writing
+    ensureHiveDirectory(projectKey);
+
+    // 2. Flush cells to JSONL using FlushManager
     const flushManager = new FlushManager({
       adapter,
       projectKey,
@@ -731,7 +839,7 @@ export const hive_sync = tool({
       return "No cells to sync";
     }
 
-    // 2. Check if there are changes to commit
+    // 3. Check if there are changes to commit
     const hiveStatusResult = await runGitCommand([
       "status",
       "--porcelain",
@@ -740,7 +848,7 @@ export const hive_sync = tool({
     const hasChanges = hiveStatusResult.stdout.trim() !== "";
 
     if (hasChanges) {
-      // 3. Stage .hive changes
+      // 4. Stage .hive changes
       const addResult = await runGitCommand(["add", ".hive/"]);
       if (addResult.exitCode !== 0) {
         throw new HiveError(
@@ -750,7 +858,7 @@ export const hive_sync = tool({
         );
       }
 
-      // 4. Commit
+      // 5. Commit
       const commitResult = await withTimeout(
         runGitCommand(["commit", "-m", "chore: sync hive"]),
         TIMEOUT_MS,
@@ -768,7 +876,7 @@ export const hive_sync = tool({
       }
     }
 
-    // 5. Pull if requested
+    // 6. Pull if requested
     if (autoPull) {
       const pullResult = await withTimeout(
         runGitCommand(["pull", "--rebase"]),
@@ -785,7 +893,7 @@ export const hive_sync = tool({
       }
     }
 
-    // 6. Push
+    // 7. Push
     const pushResult = await withTimeout(
       runGitCommand(["push"]),
       TIMEOUT_MS,