claude-code-swarm 0.3.26 → 0.4.0

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.26",
+  "version": "0.4.0",
   "description": "Launch Claude Code with swarmkit capabilities, including team orchestration, MAP observability, and session tracking.",
   "owner": {
     "name": "alexngai"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-code-swarm",
   "description": "Spin up Claude Code agent teams from openteams YAML topologies with optional MAP (Multi-Agent Protocol) observability and coordination. Provides hooks for session lifecycle, agent spawn/complete tracking, and a /swarm skill to launch team configurations.",
-  "version": "0.3.26",
+  "version": "0.4.0",
   "author": {
     "name": "alexngai"
   },

package/CLAUDE.md

@@ -226,6 +226,98 @@ Skill-tree options:
 - `basePath` — Path to skill-tree storage directory (default: `.swarm/skill-tree/`)
 - `defaultProfile` — Default profile when no role-specific criteria exist (default: `""`)
 
+### Cascade integration (Phases 1–2)
+```json
+{
+  "template": "gsd",
+  "map": { "server": "ws://localhost:8080" },
+  "cascade": {
+    "enabled": true
+  }
+}
+```
+
+When enabled, the MAP sidecar opens a persistent `git-cascade` tracker
+(`MultiAgentRepoTracker`) in **local mode** as a local state store under
+`.swarm/claude-swarm/tmp/cascade/tracker.db`. On boot it registers the
+repository's current working branch as a local-mode git-cascade stream and
+emits a single `x-cascade/stream.opened` notification over the MAP connection
+so an OpenHive hub's cascade subsystem can observe the swarm.
+
+**Phase 2 — observed git.** The sidecar also runs a poll-based ref watcher
+(`src/cascade-watcher.mjs`). Every ~3s it diffs `git for-each-ref` snapshots
+and, when it detects git activity, emits `x-cascade/*` events with real git
+data: `stream.committed` (per new commit, with message summary / files touched
+/ parent / git-cascade change id), `stream.merged` (for merge commits, with
+best-effort source-stream resolution via the 2nd parent), `stream.pushed`
+(when a remote-tracking ref catches up to a local branch), and `stream.opened`
+(for newly-appeared branches + a connection re-assert on MAP reconnect). The
+watcher is the **detector**; it works fully standalone, emitting unattributed
+events when no attribution is present.
+
+After the ref-diff pass each tick the watcher also probes in-progress
+**merge-conflict** state: a cheap `existsSync` on the worktree-local
+`.git/MERGE_HEAD`. On the off→on transition it records a conflict row
+(`recordObservedConflict` → git-cascade `conflicts.createConflict`) and emits
+`x-cascade/stream.conflicted` with the conflicted files (`git diff
+--name-only --diff-filter=U`), the conflicting commit (`MERGE_HEAD`), the
+target commit (`HEAD`), and `source: "merge"`. On the on→off transition it
+discriminates by HEAD: if HEAD advanced to a commit with ≥2 parents the merge
+was resolved + committed (`resolution_method: "manual"`, or `"agent"` when a
+fresh attribution hint is present) — otherwise the merge was aborted (HEAD
+unchanged → `"abandoned"`, via `conflicts.abandonConflict`). Conflict events
+fire only on transitions, never on every tick while a conflict is open. The
+sidecar advertises `cascade.emitsConflicts: true` honestly off the back of
+this. Rebase-conflict observation (`.git/rebase-merge/`,
+`.git/rebase-apply/`) is a known future expansion — v1 covers `git merge`
+conflicts only.
+
+A `PostToolUse(Bash)` hook supplies **attribution only** — it does not detect
+git. It builds an `{ agentId, taskRef, ts }` hint and pushes it to the sidecar
+via the `cascade-attribution` socket command. The watcher stamps `agent_id` /
+`metadata.task_ref` on emitted events when a fresh hint (within ~30s) exists.
+`taskRef` is correlated against the in-progress opentasks task only when
+`opentasks.enabled`; without opentasks, attribution carries `agent_id` only.
+
+When the watcher detects a branch forked from a tracked branch it links the
+fork: the `x-cascade/stream.opened` event carries `parent_stream` (the parent
+branch's stream id) and the git-cascade tracker DB records the parent edge, so
+an OpenHive hub's PR-stack walker can traverse parent → child.
+
+**Phase 3 — diff serving.** The sidecar wires a diff server
+(`src/cascade-diff-server.mjs`) that registers an inbound `cascade/diff.request`
+handler on the MAP connection, so an OpenHive hub's cascade changelog/diff
+endpoints work for cc-swarm-tracked streams. On a request the server resolves
+the diff with plain git in the repo cwd — cc-swarm runs git-cascade in local
+mode with no worktrees, so the request's `head` / `base` (commit hashes,
+self-identifying) drive `git show <head>` (single commit) or
+`git diff <base>..<head>` (range), with `--name-only` when `files_only` is set
+and a `file_paths` path restriction when present. `files_touched` is always
+computed via `--name-only`. A 50 MB stdout cap and 30 s timeout bound the git
+spawn. The server replies inline (`cascade/diff.response`, `streaming: false`)
+when the raw diff is ≤ 512 KB; larger diffs send a streaming announcement
+(`streaming: true`) followed by 1 MB base64 `cascade/diff.chunk` notifications,
+seq-ordered, with `final: true` + a sha256 over the full payload on the last
+chunk. Any error (bad request, git failure) folds into the typed
+`cascade/diff.response` error variant — the server never throws.
+
+The sidecar declares the `cascade: { canServeDiff: true }` MAP capability at
+registration, **conditional on `cascade.enabled`** — the same gate the diff
+server is wired on. Declaring `canServeDiff` without the server would invite
+`cascade/diff.request` notifications from the hub that time out.
+
+cc-swarm emits `x-cascade/*` events itself over MAP — the tracker is not given
+git-cascade's `emit` callback. Cascade is only meaningful when `map` is enabled
+(there is otherwise no connection to emit on); when `map` is disabled it is an
+inert no-op rather than a hard failure. All cascade work is fully gated on
+`cascade.enabled` and wrapped so a cascade failure can never crash the sidecar.
+
+Cascade options:
+- `enabled` — Enable git-cascade integration (default: `false`)
+
+Requires `git-cascade` (`>= ^0.0.7`), installed on demand via swarmkit during
+bootstrap when `cascade.enabled`.
+
 ### Logging
 ```json
 {
@@ -303,6 +395,7 @@ All config values can be overridden via `SWARM_*` environment variables. Priorit
 | `skilltree.enabled` | `SWARM_SKILLTREE_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
 | `skilltree.basePath` | `SWARM_SKILLTREE_BASE_PATH` | string | `""` |
 | `skilltree.defaultProfile` | `SWARM_SKILLTREE_DEFAULT_PROFILE` | string | `""` |
+| `cascade.enabled` | `SWARM_CASCADE_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
 | `mesh.enabled` | `SWARM_MESH_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
 | `mesh.peerId` | `SWARM_MESH_PEER_ID` | string | `""` |
 | `mesh.mapServer` | `SWARM_MESH_MAP_SERVER` | string | `""` |
@@ -404,6 +497,7 @@ Both modes:
 - `trajectory: { canReport: true, canServeContent: true }` — reports checkpoints, serves transcript content on demand
 - `tasks: { canCreate, canAssign, canUpdate, canList }` — task management
 - `opentasks: { canQuery, canLink, canAnnotate, canTask }` — conditional, when task_graph configured
+- `cascade: { canServeDiff: true }` — conditional, when `cascade.enabled` — sidecar serves unified diffs on demand via `cascade/diff.request` (see Cascade integration above)
 
 Message delivery is **pull-based**: the `UserPromptSubmit` hook reads the inbox on each turn and injects messages into Claude Code's prompt context. No real-time push delivery.
 
@@ -465,6 +559,7 @@ Global (managed by swarmkit, installed on demand during bootstrap):
 - **sessionlog** — git-integrated session capture (installed when `sessionlog.enabled: true`)
 - **minimem** — file-based memory with vector search (installed when `minimem.enabled: true`)
 - **skill-tree** — versioned skill library with serving layer (installed when `skilltree.enabled: true`)
+- **git-cascade** — multi-agent git tracking; local-mode tracker for cascade observability (installed when `cascade.enabled: true`)
 
 Runtime:
 - **Claude Code agent teams** — enabled via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.json

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Ngai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/hooks/hooks.json

@@ -80,6 +80,15 @@
           }
         ]
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('fs'),p=require('path'),h=require('os').homedir();let c={};try{c=JSON.parse(f.readFileSync('.swarm/claude-swarm/config.json','utf-8'))}catch{try{c=JSON.parse(f.readFileSync(p.join(h,'.claude-swarm','config.json'),'utf-8'))}catch{}};process.exit((c.cascade?.enabled||process.env.SWARM_CASCADE_ENABLED)&&(c.map?.enabled||c.map?.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED)?0:1)\" 2>/dev/null && node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" cascade-bash-attribution"
+          }
+        ]
+      },
       {
         "matcher": "TaskCreate",
         "hooks": [

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.26",
+  "version": "0.4.0",
   "description": "Claude Code plugin for launching agent teams from openteams topologies with MAP observability",
+  "author": "Alex Ngai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexngai/claude-code-swarm.git"
+  },
   "type": "module",
   "exports": {
     ".": "./src/index.mjs",
@@ -24,6 +30,7 @@
   },
   "peerDependencies": {
     "agent-inbox": "*",
+    "git-cascade": ">=0.0.9",
     "opentasks": ">=0.1.1",
     "swarmkit": "*"
   },
@@ -31,6 +38,9 @@
     "agent-inbox": {
       "optional": true
     },
+    "git-cascade": {
+      "optional": true
+    },
     "opentasks": {
       "optional": true
     }
@@ -45,6 +55,7 @@
     "test:e2e:tier4": "vitest run --config e2e/vitest.config.e2e.mjs -t tier4",
     "test:e2e:tier5": "vitest run --config e2e/vitest.config.e2e.mjs -t tier5",
     "test:e2e:tier7": "vitest run --config e2e/vitest.config.e2e.mjs -t tier7",
+    "prepublishOnly": "publint",
     "version:patch": "npm version patch --no-git-tag-version && node scripts/sync-version.mjs",
     "version:minor": "npm version minor --no-git-tag-version && node scripts/sync-version.mjs",
     "version:major": "npm version major --no-git-tag-version && node scripts/sync-version.mjs"
@@ -54,8 +65,10 @@
   },
   "devDependencies": {
     "agent-inbox": "^0.2.3",
+    "git-cascade": "^0.0.9",
     "minimem": "^0.1.1",
     "opentasks": "^0.1.2",
+    "publint": "^0.3.21",
     "skill-tree": "^0.2.0",
     "vitest": "^4.0.18",
     "ws": "^8.0.0"

package/renovate.json5

@@ -0,0 +1,6 @@
+{
+  // Dependency-update policy is shared across the swarm/openhive ecosystem.
+  // See github.com/alexngai/swarm-renovate-config.
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["github>alexngai/swarm-renovate-config"]
+}

package/scripts/map-hook.mjs

@@ -20,6 +20,7 @@
  *   task-completed      — Complete task in opentasks + emit bridge event
  *   opentasks-mcp-used  — Bridge opentasks MCP tool use → MAP task sync payload
  *   sessionlog-dispatch — Dispatch a sessionlog lifecycle hook via programmatic API
+ *   cascade-bash-attribution — Push a cascade attribution hint to the sidecar
  *
  * Usage: node map-hook.mjs <action>
  *        Hook event data is read from stdin (JSON).
@@ -36,7 +37,7 @@ configureNodePath();
 const log = createLogger("map-hook");
 import { readRoles, matchRole } from "../src/roles.mjs";
 import { formatInboxAsMarkdown } from "../src/inbox.mjs";
-import { sendToInbox } from "../src/sidecar-client.mjs";
+import { sendToInbox, sendToSidecar } from "../src/sidecar-client.mjs";
 import { sessionPaths } from "../src/paths.mjs";
 import {
   sendCommand,
@@ -51,7 +52,7 @@ import {
   buildMinimemBridgeCommand,
 } from "../src/map-events.mjs";
 import { syncSessionlog, dispatchSessionlogHook } from "../src/sessionlog.mjs";
-import { findSocketPath, pushSyncEvent } from "../src/opentasks-client.mjs";
+import { findSocketPath, pushSyncEvent, rpcRequest } from "../src/opentasks-client.mjs";
 
 const action = process.argv[2];
 
@@ -232,6 +233,60 @@ async function handleMinimemMcpUsed(hookData, sessionId) {
   }
 }
 
+// ── cascade attribution (PostToolUse Bash) ──────────────────────────────────
+//
+// Attribution-only: this does NOT parse the git command or detect git. The
+// cascade-watcher in the sidecar is the detector. This hook just builds an
+// attribution hint { agentId, taskRef, ts } and pushes it to the sidecar as a
+// `cascade-attribution` command — the watcher reads the freshest hint to
+// stamp agent_id / task_ref on observed-git events.
+
+async function handleCascadeBashAttribution(hookData, sessionId) {
+  const config = readConfig();
+  if (!config.cascade?.enabled || !config.map?.enabled) return;
+
+  // Acting agent id — same resolution other hooks use: hook data first,
+  // then env. Falls back to the session id when nothing else identifies it.
+  const agentId =
+    hookData.agent_id ||
+    process.env.CLAUDE_AGENT_ID ||
+    process.env.MACRO_AGENT_ID ||
+    sessionId ||
+    "";
+
+  // taskRef — only correlated when opentasks is enabled. When opentasks is
+  // disabled we skip the query entirely and leave taskRef null; no task
+  // correlation is expected without opentasks (intended).
+  let taskRef = null;
+  if (config.opentasks?.enabled && agentId) {
+    try {
+      const otSocketPath = findSocketPath();
+      const nodes = await rpcRequest(
+        "graph.query",
+        { type: "task", filter: { status: "in_progress", assignee: agentId } },
+        otSocketPath,
+      );
+      const task = Array.isArray(nodes) ? nodes[0] : null;
+      if (task) {
+        // resource_id intentionally omitted — the hub resolves it from the
+        // swarm's registered task graph. Emitting a guessed value causes false
+        // bindings.
+        taskRef = {
+          node_id: task.node_id || task.id || "",
+        };
+      }
+    } catch {
+      // Best-effort — leave taskRef null on any failure.
+    }
+  }
+
+  const sPaths = sessionPaths(sessionId);
+  await sendToSidecar(
+    { action: "cascade-attribution", agentId, taskRef, ts: Date.now() },
+    sPaths.socketPath,
+  );
+}
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -253,6 +308,7 @@ async function main() {
       case "native-task-created": await handleNativeTaskCreated(hookData, sessionId); break;
       case "native-task-updated": await handleNativeTaskUpdated(hookData, sessionId); break;
       case "minimem-mcp-used": await handleMinimemMcpUsed(hookData, sessionId); break;
+      case "cascade-bash-attribution": await handleCascadeBashAttribution(hookData, sessionId); break;
       case "sessionlog-dispatch": await handleSessionlogDispatch(hookData); break;
       default:
         log.warn("unknown action", { action });

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);
 
@@ -461,6 +522,7 @@ async function startWebSocketTransport() {
     credential: AUTH_CREDENTIAL || undefined,
     projectContext: PROJECT_CONTEXT,
     inboxEnabled: !!INBOX_CONFIG || MESH_ENABLED,
+    cascadeEnabled: CASCADE_ENABLED,
     onMessage: () => {
       resetInactivityTimer();
     },
@@ -539,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() {
@@ -613,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();