claude-code-swarm 0.3.25 → 0.4.0

package/scripts/map-sidecar.mjs

@@ -20,13 +20,17 @@
 
 import fs from "fs";
 import path from "path";
-import { SOCKET_PATH, PID_PATH, INBOX_SOCKET_PATH, sessionPaths, pluginDir } from "../src/paths.mjs";
+import { SOCKET_PATH, PID_PATH, INBOX_SOCKET_PATH, CASCADE_DB_PATH, sessionPaths, pluginDir, ensureCascadeDir } from "../src/paths.mjs";
 import { connectToMAP } from "../src/map-connection.mjs";
 import { createMeshPeer, createMeshInbox } from "../src/mesh-connection.mjs";
 import { createSocketServer, createCommandHandler } from "../src/sidecar-server.mjs";
 import { startOpenTasksEventBridge } from "../src/opentasks-bridge.mjs";
 import { createContentProvider } from "../src/content-provider.mjs";
 import { startMemoryWatcher } from "../src/memory-watcher.mjs";
+import { openCascadeTracker, ensureStream, closeCascadeTracker } from "../src/cascade-client.mjs";
+import { buildStreamOpenedParams, emitStreamOpened } from "../src/cascade-events.mjs";
+import { startCascadeWatcher } from "../src/cascade-watcher.mjs";
+import { setupCascadeDiffServer } from "../src/cascade-diff-server.mjs";
 import { readConfig } from "../src/config.mjs";
 import { createLogger, init as initLog } from "../src/log.mjs";
 import { configureNodePath, resolvePackage } from "../src/swarmkit-resolver.mjs";
@@ -98,6 +102,16 @@ initLog({ ..._logConfig, sessionId: SESSION_ID || undefined });
 const MESH_ENABLED = hasFlag("mesh-enabled");
 const MESH_PEER_ID = getArg("mesh-peer-id", "");
 
+// Cascade gate — whether git-cascade integration is enabled. Used to declare
+// the `cascade.canServeDiff` MAP capability conditionally: the diff server
+// (src/cascade-diff-server.mjs) is wired in setupCascade() only when this is
+// true, so declaring the capability without it would invite timed-out
+// cascade/diff.request notifications from the hub.
+let CASCADE_ENABLED = false;
+try {
+  CASCADE_ENABLED = Boolean(readConfig().cascade?.enabled);
+} catch { /* config unreadable — leave cascade off */ }
+
 // Parse inbox config (passed as JSON blob from sidecar-client)
 let INBOX_CONFIG = null;
 const inboxConfigJson = getArg("inbox-config", "");
@@ -125,6 +139,9 @@ let inactivityTimer = null;
 let reconnectInterval = null;
 let transportMode = "websocket"; // "mesh" or "websocket"
 let opentasksBridge = null; // Daemon watch → MAP event bridge (Option A)
+let cascadeTracker = null; // git-cascade local-mode tracker (Phase 1+)
+let cascadeWatcher = null; // observed-git ref watcher (Phase 2)
+let cascadeDiffServerDispose = null; // cascade/diff.request handler cleanup (Phase 3)
 const registeredAgents = new Map();
 
 // ── Inactivity Timer ────────────────────────────────────────────────────────
@@ -152,6 +169,27 @@ async function shutdown() {
     opentasksBridge = null;
   }
 
+  // Stop the cascade ref watcher before the tracker DB closes — the watcher
+  // calls into the tracker. Safe no-op when cascade was never enabled.
+  if (cascadeWatcher) {
+    try { cascadeWatcher.stop(); } catch { /* ignore */ }
+    cascadeWatcher = null;
+  }
+
+  // Dispose the cascade diff server (unregisters the cascade/diff.request
+  // handler). Safe no-op when cascade was never enabled.
+  if (cascadeDiffServerDispose) {
+    try { cascadeDiffServerDispose(); } catch { /* ignore */ }
+    cascadeDiffServerDispose = null;
+  }
+
+  // Close the git-cascade tracker (local state store) before the socket
+  // and connection drop. Safe no-op when cascade was never enabled.
+  if (cascadeTracker) {
+    closeCascadeTracker(cascadeTracker);
+    cascadeTracker = null;
+  }
+
   // Stop agent-inbox first (it borrows the connection/peer, doesn't own it)
   if (inboxInstance) {
     try { await inboxInstance.stop(); } catch { /* ignore */ }
@@ -234,6 +272,7 @@ function startSlowReconnectLoop() {
         credential: AUTH_CREDENTIAL || undefined,
         projectContext: PROJECT_CONTEXT,
         inboxEnabled: !!INBOX_CONFIG || MESH_ENABLED,
+        cascadeEnabled: CASCADE_ENABLED,
         onMessage: () => resetInactivityTimer(),
       });
 
@@ -245,6 +284,28 @@ function startSlowReconnectLoop() {
         if (commandHandler) commandHandler.setConnection(newConn);
         attachReconnectionListener(newConn);
 
+        // Point the cascade watcher at the fresh connection and re-assert
+        // open streams — idempotent on the hub, covers the reconnect gap.
+        if (cascadeWatcher) {
+          try {
+            cascadeWatcher.setConnection(newConn);
+            cascadeWatcher.reassertStreams();
+          } catch { /* ignore — cascade must never crash the sidecar */ }
+        }
+
+        // Re-register the cascade diff server on the fresh connection — the
+        // previous handler was bound to the dead one. No-op when cascade is
+        // disabled (dispose handle is null).
+        if (cascadeDiffServerDispose) {
+          try {
+            cascadeDiffServerDispose();
+            cascadeDiffServerDispose = setupCascadeDiffServer(newConn, {
+              repoPath: process.cwd(),
+              tracker: cascadeTracker,
+            });
+          } catch { /* ignore — cascade must never crash the sidecar */ }
+        }
+
         // Re-register active agents so the MAP server knows about them
         await reRegisterAgents(newConn);
 
@@ -425,6 +486,34 @@ function registerContentHandler(conn) {
   });
 }
 
+/**
+ * Register the x-dispatch/nudge notification handler on a connection.
+ * When the hub sends a nudge (a dispatch thread received a new turn),
+ * the sidecar stores the nudge so the UserPromptSubmit hook can inject
+ * a hint about pending messages.
+ */
+function registerNudgeHandler(conn) {
+  if (!conn || typeof conn.onNotification !== "function") return;
+
+  conn.onNotification("x-dispatch/nudge", (params) => {
+    const dispatchId = params?.dispatch_id;
+    const conversationId = params?.conversation_id;
+    if (!dispatchId) return;
+
+    log.info("dispatch nudge received", { dispatchId, conversationId });
+    resetInactivityTimer();
+
+    // Store the nudge via the command handler's nudge command.
+    // Use a fake client since we don't need the response.
+    if (commandHandler) {
+      commandHandler(
+        { action: "nudge", dispatch_id: dispatchId, conversation_id: conversationId },
+        { write: () => {}, writable: true },
+      );
+    }
+  });
+}
+
 async function startWebSocketTransport() {
   connection = await connectToMAP({
     server: MAP_SERVER,
@@ -433,6 +522,7 @@ async function startWebSocketTransport() {
     credential: AUTH_CREDENTIAL || undefined,
     projectContext: PROJECT_CONTEXT,
     inboxEnabled: !!INBOX_CONFIG || MESH_ENABLED,
+    cascadeEnabled: CASCADE_ENABLED,
     onMessage: () => {
       resetInactivityTimer();
     },
@@ -511,6 +601,116 @@ async function startLegacyAgentInbox(mapConnection) {
   }
 }
 
+// ── Cascade (git-cascade local-mode tracking) ───────────────────────────────
+
+/**
+ * Determine the current branch and its HEAD commit for `repoPath`.
+ * Returns null for either field on any git error.
+ */
+function getRepoHead(repoPath) {
+  let branch = null;
+  let commit = null;
+  try {
+    branch = execSync("git rev-parse --abbrev-ref HEAD", {
+      cwd: repoPath, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch { /* not a git repo / detached */ }
+  try {
+    commit = execSync("git rev-parse HEAD", {
+      cwd: repoPath, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch { /* no commits yet */ }
+  return { branch, commit };
+}
+
+/**
+ * Cascade setup: open a git-cascade tracker in local mode, register the
+ * working branch as a local-mode stream, emit one `x-cascade/stream.opened`
+ * event, and start the Phase 2 observed-git ref watcher.
+ *
+ * Stores the tracker on `cascadeTracker` and the watcher on `cascadeWatcher`.
+ * Fully resilient — any failure is logged and swallowed so cascade can never
+ * crash the sidecar.
+ */
+async function setupCascade() {
+  try {
+    const cfg = readConfig();
+    if (!cfg.cascade?.enabled) return;
+
+    const repoPath = process.cwd();
+    const { branch, commit } = getRepoHead(repoPath);
+    if (!branch || branch === "HEAD") {
+      log.warn("cascade: no current branch, skipping stream registration");
+      return;
+    }
+
+    ensureCascadeDir();
+    cascadeTracker = await openCascadeTracker({ repoPath, dbPath: CASCADE_DB_PATH });
+    if (!cascadeTracker) return; // openCascadeTracker already logged the reason
+
+    // First-emit settle window. AgentConnection.connect() resolves once the
+    // SDK handshake completes, but the hub-side session-context attach (which
+    // stamps the swarmId on inbound messages) can land a beat later. The live
+    // e2e (src/__tests__/cascade/live-cc-swarm-cascade-e2e.test.ts) surfaced
+    // that a callExtension fired immediately after connect can race the
+    // inbound register and be silently dropped. Give the hub a small window
+    // to settle before the first cascade emit. The watcher's
+    // reassertStreams() (run on watcher start and on every reconnect) is the
+    // belt-and-suspenders recovery; this settle is the cheaper first line of
+    // defense. Replace with a proper readiness signal if the MAP SDK ever
+    // exposes one.
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const teamName = MAP_SCOPE.replace("swarm:", "");
+    const agentId = `${teamName}-sidecar`;
+
+    const result = ensureStream(cascadeTracker, { branch, agentId });
+    if (!result) return;
+
+    if (result.created) {
+      log.info("cascade: registered working branch as stream", { branch, streamId: result.streamId });
+      const params = buildStreamOpenedParams({
+        streamId: result.streamId,
+        name: branch,
+        agentId,
+        baseCommit: commit || "",
+        branchName: branch,
+        metadata: { trigger: "sidecar-boot" },
+      });
+      emitStreamOpened(connection, params);
+    } else {
+      log.debug("cascade: working branch already tracked", { branch, streamId: result.streamId });
+    }
+
+    // Phase 2: start the observed-git ref watcher. It detects commits/merges/
+    // pushes from git ref state and emits x-cascade/* events with real git
+    // data. Attribution (agent_id, task_ref) comes from the PostToolUse(Bash)
+    // hook via the command handler's cascade-attribution side-channel.
+    cascadeWatcher = startCascadeWatcher({
+      tracker: cascadeTracker,
+      connection,
+      repoPath,
+      getAttribution: commandHandler?.getCascadeAttribution,
+      agentId,
+    });
+
+    // Phase 3: wire the cascade diff server. It registers a
+    // cascade/diff.request handler so the hub can fetch unified diffs for
+    // cc-swarm-tracked streams on demand. Resilient — try/catch keeps a
+    // cascade failure from ever crashing the sidecar.
+    try {
+      cascadeDiffServerDispose = setupCascadeDiffServer(connection, {
+        repoPath,
+        tracker: cascadeTracker,
+      });
+    } catch (err) {
+      log.warn("cascade diff server setup failed", { error: err.message });
+    }
+  } catch (err) {
+    log.warn("cascade setup failed", { error: err.message });
+  }
+}
+
 // ── Main ────────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -557,6 +757,10 @@ async function main() {
     return commandHandler(command, client);
   });
 
+  // Register dispatch nudge handler — must come after commandHandler is created
+  // so the notification can store nudge state via the command handler.
+  registerNudgeHandler(connection);
+
   // Start memory file watcher if minimem is enabled
   const sidecarConfig = readConfig();
   if (sidecarConfig.minimem?.enabled) {
@@ -581,6 +785,11 @@ async function main() {
     }
   }
 
+  // Cascade Phase 1: register the working branch as a local-mode
+  // git-cascade stream and emit x-cascade/stream.opened. No-op unless
+  // cascade.enabled. Resilient — never crashes the sidecar.
+  await setupCascade();
+
   // Start inactivity timer
   resetInactivityTimer();
 

package/src/__tests__/cascade-client.test.mjs

@@ -0,0 +1,217 @@
+/**
+ * cascade-client.test.mjs — git-cascade tracker ownership (Phase 1)
+ *
+ * Exercises openCascadeTracker / ensureStream / closeCascadeTracker against a
+ * real temp git repo with a couple of branches. git-cascade is resolved at
+ * runtime via swarmkit-resolver, so these tests require git-cascade to be
+ * importable from the workspace.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import {
+  openCascadeTracker,
+  ensureStream,
+  closeCascadeTracker,
+  findStreamByBranch,
+  recordObservedCommit,
+  recordObservedMerge,
+} from "../cascade-client.mjs";
+import { makeTmpDir, cleanupTmpDir } from "./helpers.mjs";
+
+/**
+ * Create a real git repo with an initial commit and a couple of branches.
+ * Leaves `main` (or the default branch) checked out.
+ */
+function makeGitRepo(dir) {
+  execSync("git init", { cwd: dir, stdio: "pipe" });
+  execSync('git config user.email "test@test.com"', { cwd: dir, stdio: "pipe" });
+  execSync('git config user.name "Test"', { cwd: dir, stdio: "pipe" });
+  execSync("git config commit.gpgsign false", { cwd: dir, stdio: "pipe" });
+  fs.writeFileSync(path.join(dir, "README.md"), "# test\n");
+  execSync("git add .", { cwd: dir, stdio: "pipe" });
+  execSync('git commit -m "initial"', { cwd: dir, stdio: "pipe" });
+  // Create a couple of extra branches.
+  execSync("git branch feature-a", { cwd: dir, stdio: "pipe" });
+  execSync("git branch feature-b", { cwd: dir, stdio: "pipe" });
+}
+
+/** Current branch name of a repo. */
+function currentBranch(dir) {
+  return execSync("git rev-parse --abbrev-ref HEAD", {
+    cwd: dir, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"],
+  }).trim();
+}
+
+/** HEAD commit SHA of a repo (optionally a specific rev). */
+function headSha(dir, rev = "HEAD") {
+  return execSync(`git rev-parse ${rev}`, {
+    cwd: dir, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"],
+  }).trim();
+}
+
+describe("cascade-client", () => {
+  let repoDir;
+  let dbPath;
+  let tracker;
+
+  beforeEach(() => {
+    repoDir = makeTmpDir("cascade-test-");
+    dbPath = path.join(repoDir, "tracker.db");
+    makeGitRepo(repoDir);
+    tracker = null;
+  });
+
+  afterEach(() => {
+    if (tracker) {
+      closeCascadeTracker(tracker);
+      tracker = null;
+    }
+    cleanupTmpDir(repoDir);
+  });
+
+  it("openCascadeTracker returns a tracker for a git repo", async () => {
+    tracker = await openCascadeTracker({ repoPath: repoDir, dbPath });
+    expect(tracker).not.toBeNull();
+    expect(typeof tracker.trackExistingBranch).toBe("function");
+  });
+
+  it("openCascadeTracker returns null for a non-git directory", async () => {
+    const nonGit = makeTmpDir("cascade-nongit-");
+    try {
+      const t = await openCascadeTracker({
+        repoPath: nonGit,
+        dbPath: path.join(nonGit, "tracker.db"),
+      });
+      expect(t).toBeNull();
+    } finally {
+      cleanupTmpDir(nonGit);
+    }
+  });
+
+  it("ensureStream creates a stream for the working branch", async () => {
+    tracker = await openCascadeTracker({ repoPath: repoDir, dbPath });
+    expect(tracker).not.toBeNull();
+
+    const branch = currentBranch(repoDir);
+    const result = ensureStream(tracker, { branch, agentId: "team-sidecar" });
+
+    expect(result).not.toBeNull();
+    expect(result.created).toBe(true);
+    expect(typeof result.streamId).toBe("string");
+    expect(result.streamId.length).toBeGreaterThan(0);
+  });
+
+  it("ensureStream is idempotent on a second call for the same branch", async () => {
+    tracker = await openCascadeTracker({ repoPath: repoDir, dbPath });
+    expect(tracker).not.toBeNull();
+
+    const branch = currentBranch(repoDir);
+    const first = ensureStream(tracker, { branch, agentId: "team-sidecar" });
+    const second = ensureStream(tracker, { branch, agentId: "team-sidecar" });
+
+    expect(first).not.toBeNull();
+    expect(second).not.toBeNull();
+    expect(first.created).toBe(true);
+    expect(second.created).toBe(false);
+    expect(second.streamId).toBe(first.streamId);
+  });
+
+  it("ensureStream tracks distinct branches as separate streams", async () => {
+    tracker = await openCascadeTracker({ repoPath: repoDir, dbPath });
+    expect(tracker).not.toBeNull();
+
+    const a = ensureStream(tracker, { branch: "feature-a", agentId: "team-sidecar" });
+    const b = ensureStream(tracker, { branch: "feature-b", agentId: "team-sidecar" });
+
+    expect(a).not.toBeNull();
+    expect(b).not.toBeNull();
+    expect(a.created).toBe(true);
+    expect(b.created).toBe(true);
+    expect(a.streamId).not.toBe(b.streamId);
+  });
+
+  it("ensureStream returns null when tracker is missing", () => {
+    expect(ensureStream(null, { branch: "main", agentId: "x" })).toBeNull();
+  });
+
+  it("closeCascadeTracker is a safe no-op on null", () => {
+    expect(() => closeCascadeTracker(null)).not.toThrow();
+  });
+
+  it("closeCascadeTracker closes an open tracker", async () => {
+    const t = await openCascadeTracker({ repoPath: repoDir, dbPath });
+    expect(t).not.toBeNull();
+    expect(() => closeCascadeTracker(t)).not.toThrow();
+  });
+
+  it("findStreamByBranch resolves a tracked branch and returns null otherwise", async () => {
+    tracker = await openCascadeTracker({ repoPath: repoDir, dbPath });
+    expect(tracker).not.toBeNull();
+
+    const branch = currentBranch(repoDir);
+    const created = ensureStream(tracker, { branch, agentId: "team-sidecar" });
+    expect(created).not.toBeNull();
+
+    expect(findStreamByBranch(tracker, branch)).toBe(created.streamId);
+    expect(findStreamByBranch(tracker, "no-such-branch")).toBeNull();
+    expect(findStreamByBranch(null, branch)).toBeNull();
+  });
+
+  it("recordObservedCommit persists a change and returns its id", async () => {
+    tracker = await openCascadeTracker({ repoPath: repoDir, dbPath });
+    expect(tracker).not.toBeNull();
+
+    const branch = currentBranch(repoDir);
+    const stream = ensureStream(tracker, { branch, agentId: "team-sidecar" });
+    expect(stream).not.toBeNull();
+
+    const commit = headSha(repoDir);
+    const changeId = await recordObservedCommit(tracker, {
+      streamId: stream.streamId,
+      commit,
+      description: "initial",
+    });
+
+    expect(typeof changeId).toBe("string");
+    expect(changeId.length).toBeGreaterThan(0);
+  });
+
+  it("recordObservedCommit returns null when tracker is missing", async () => {
+    const result = await recordObservedCommit(null, {
+      streamId: "s1", commit: "abc", description: "x",
+    });
+    expect(result).toBeNull();
+  });
+
+  it("recordObservedMerge persists a merge edge and returns its id", async () => {
+    tracker = await openCascadeTracker({ repoPath: repoDir, dbPath });
+    expect(tracker).not.toBeNull();
+
+    const target = ensureStream(tracker, { branch: currentBranch(repoDir), agentId: "team-sidecar" });
+    const source = ensureStream(tracker, { branch: "feature-a", agentId: "team-sidecar" });
+    expect(target).not.toBeNull();
+    expect(source).not.toBeNull();
+
+    const mergeCommit = headSha(repoDir);
+    const mergeId = await recordObservedMerge(tracker, {
+      sourceStreamId: source.streamId,
+      sourceCommit: headSha(repoDir, "feature-a"),
+      targetStreamId: target.streamId,
+      mergeCommit,
+      metadata: { trigger: "test" },
+    });
+
+    expect(typeof mergeId).toBe("string");
+    expect(mergeId.length).toBeGreaterThan(0);
+  });
+
+  it("recordObservedMerge returns null when required fields are missing", async () => {
+    tracker = await openCascadeTracker({ repoPath: repoDir, dbPath });
+    expect(tracker).not.toBeNull();
+    const result = await recordObservedMerge(tracker, { sourceStreamId: "s1" });
+    expect(result).toBeNull();
+  });
+});