macro-agent 0.1.10 → 0.1.11

package/src/cli/acp.ts

@@ -34,6 +34,10 @@ async function main() {
   try {
     const system = await bootV2({
       cwd: defaultCwd,
+      // `--instance-id` picks the on-disk compartment under ~/.macro-agent/
+      // so multiple runs with the same id share state. Omit to auto-derive
+      // from the cwd hash. See `BootV2Config.instanceId`.
+      ...(options.instanceId ? { instanceId: options.instanceId } : {}),
       // Enable ACP WebSocket server if port is specified (server mode)
       ...(options.port
         ? {

package/src/lifecycle/__tests__/cascade-consolidation.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Consolidation-through-tracker tests (A3 follow-up).
+ *
+ * Verifies `terminateWithChangeConsolidation` prefers
+ * `workspaceManager.mergeStream()` when both workspaces carry stream ids —
+ * so the merge fires `x-cascade/stream.merged` and propagates to the hub —
+ * and cleanly falls back to raw `git merge` when streams aren't available.
+ *
+ * Unit-only: stubs workspaces + agent manager. No git invocations.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { terminateWithChangeConsolidation } from '../cascade.js';
+import type {
+  CascadeAgentManager,
+  WorkspaceProvider,
+} from '../cascade.js';
+import type { Workspace, WorkspaceManager } from '../../workspace/types.js';
+import * as cleanupModule from '../cleanup.js';
+
+function mkWorkspace(overrides: Partial<Workspace> = {}): Workspace {
+  return {
+    agentId: 'agent',
+    path: '/tmp/wt',
+    branch: 'stream/s',
+    streamId: 's',
+    role: 'worker' as any,
+    createdAt: Date.now(),
+    ...overrides,
+  };
+}
+
+function mkAgentManager(): CascadeAgentManager {
+  return {
+    getChildren: vi.fn(() => []),
+    terminate: vi.fn(async () => {}),
+  };
+}
+
+describe('terminateWithChangeConsolidation', () => {
+  let attemptMergeSpy: ReturnType<typeof vi.spyOn>;
+  let getCurrentBranchSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    // Default: branch matches so the "parent on expected branch" warning doesn't fire.
+    getCurrentBranchSpy = vi
+      .spyOn(cleanupModule, 'getCurrentBranch')
+      .mockReturnValue('stream/parent');
+    attemptMergeSpy = vi.spyOn(cleanupModule, 'attemptMerge');
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('routes through workspaceManager.mergeStream when both workspaces have stream ids', async () => {
+    const mergeStream = vi.fn(() => ({ success: true, newHead: 'abc123' }));
+    const ws = { mergeStream } as unknown as WorkspaceManager;
+    const provider: WorkspaceProvider = {
+      getWorkspace: (id) =>
+        id === 'child'
+          ? mkWorkspace({ agentId: 'child', streamId: 'child-s', branch: 'stream/child' })
+          : mkWorkspace({ agentId: 'parent', streamId: 'parent-s', branch: 'stream/parent', path: '/tmp/parent' }),
+    };
+    const am = mkAgentManager();
+
+    const result = await terminateWithChangeConsolidation(
+      'child' as any,
+      'parent' as any,
+      am,
+      provider,
+      undefined,
+      ws,
+    );
+
+    expect(result).toEqual({ success: true, merged: true, mergeCommit: 'abc123' });
+    expect(mergeStream).toHaveBeenCalledWith({
+      sourceStreamId: 'child-s',
+      targetStreamId: 'parent-s',
+      agentId: 'parent',
+      worktree: '/tmp/parent',
+      metadata: undefined,
+    });
+    // Raw-git path must NOT be touched when the tracker handled it.
+    expect(attemptMergeSpy).not.toHaveBeenCalled();
+    expect(am.terminate).toHaveBeenCalledWith('child', 'changes_consolidated');
+  });
+
+  it('threads a provided taskRef into the mergeStream metadata', async () => {
+    const mergeStream = vi.fn(() => ({ success: true, newHead: 'def456' }));
+    const ws = { mergeStream } as unknown as WorkspaceManager;
+    const provider: WorkspaceProvider = {
+      getWorkspace: (id) =>
+        mkWorkspace({
+          agentId: id,
+          streamId: `${id}-s`,
+          branch: `stream/${id}`,
+        }),
+    };
+
+    const taskRef = { resource_id: 'res-a1', node_id: 'task-a1' };
+    await terminateWithChangeConsolidation(
+      'child' as any,
+      'parent' as any,
+      mkAgentManager(),
+      provider,
+      undefined,
+      ws,
+      taskRef,
+    );
+
+    expect(mergeStream).toHaveBeenCalledWith(
+      expect.objectContaining({ metadata: { task_ref: taskRef } }),
+    );
+  });
+
+  it('surfaces tracker conflicts without falling back to raw git', async () => {
+    const mergeStream = vi.fn(() => ({
+      success: false,
+      conflicts: ['shared.ts'],
+    }));
+    const ws = { mergeStream } as unknown as WorkspaceManager;
+    const provider: WorkspaceProvider = {
+      getWorkspace: (id) =>
+        mkWorkspace({
+          agentId: id,
+          streamId: `${id}-s`,
+          branch: `stream/${id}`,
+        }),
+    };
+    const am = mkAgentManager();
+
+    const result = await terminateWithChangeConsolidation(
+      'child' as any,
+      'parent' as any,
+      am,
+      provider,
+      undefined,
+      ws,
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.conflicts).toEqual(['shared.ts']);
+    expect(attemptMergeSpy).not.toHaveBeenCalled();
+    expect(am.terminate).toHaveBeenCalledWith('child', 'merge_conflict');
+  });
+
+  it('falls back to raw git when workspaceManager is not provided', async () => {
+    attemptMergeSpy.mockReturnValue({
+      success: true,
+      mergeCommit: 'rawabc',
+    });
+    const provider: WorkspaceProvider = {
+      getWorkspace: (id) =>
+        mkWorkspace({
+          agentId: id,
+          streamId: `${id}-s`,
+          branch: `stream/${id}`,
+        }),
+    };
+    const am = mkAgentManager();
+
+    const result = await terminateWithChangeConsolidation(
+      'child' as any,
+      'parent' as any,
+      am,
+      provider,
+      undefined,
+      // No workspaceManager argument.
+    );
+
+    expect(result).toEqual({ success: true, merged: true, mergeCommit: 'rawabc' });
+    expect(attemptMergeSpy).toHaveBeenCalledOnce();
+  });
+
+  it('falls back to raw git when the child workspace lacks a stream id', async () => {
+    attemptMergeSpy.mockReturnValue({ success: true, mergeCommit: 'legacyabc' });
+    const mergeStream = vi.fn();
+    const ws = { mergeStream } as unknown as WorkspaceManager;
+    const provider: WorkspaceProvider = {
+      getWorkspace: (id) =>
+        id === 'child'
+          ? mkWorkspace({ agentId: 'child', streamId: '', branch: 'feat/legacy' })
+          : mkWorkspace({ agentId: 'parent', streamId: 'parent-s', branch: 'stream/parent' }),
+    };
+
+    const result = await terminateWithChangeConsolidation(
+      'child' as any,
+      'parent' as any,
+      mkAgentManager(),
+      provider,
+      undefined,
+      ws,
+    );
+
+    expect(result.success).toBe(true);
+    expect(mergeStream).not.toHaveBeenCalled();
+    expect(attemptMergeSpy).toHaveBeenCalledOnce();
+  });
+
+  it('falls back to raw git when tracker.mergeStream throws', async () => {
+    const mergeStream = vi.fn(() => {
+      throw new Error('stream not found');
+    });
+    attemptMergeSpy.mockReturnValue({ success: true, mergeCommit: 'fallbackabc' });
+    const ws = { mergeStream } as unknown as WorkspaceManager;
+    const provider: WorkspaceProvider = {
+      getWorkspace: (id) =>
+        mkWorkspace({
+          agentId: id,
+          streamId: `${id}-s`,
+          branch: `stream/${id}`,
+        }),
+    };
+
+    const result = await terminateWithChangeConsolidation(
+      'child' as any,
+      'parent' as any,
+      mkAgentManager(),
+      provider,
+      undefined,
+      ws,
+    );
+
+    expect(result.success).toBe(true);
+    expect(mergeStream).toHaveBeenCalledOnce();
+    expect(attemptMergeSpy).toHaveBeenCalledOnce();
+  });
+
+  it('preserves legacy "no workspace provider" behavior', async () => {
+    const am = mkAgentManager();
+    const result = await terminateWithChangeConsolidation(
+      'child' as any,
+      'parent' as any,
+      am,
+    );
+    expect(result).toEqual({ success: true, merged: false });
+    expect(am.terminate).toHaveBeenCalledWith('child', 'parent_stopped');
+  });
+});

package/src/lifecycle/cascade.ts

@@ -129,11 +129,24 @@ export interface WorkspaceProvider {
  * If a merge conflict occurs, the merge is aborted and the child is
  * terminated with a "merge_conflict" reason.
  *
+ * When a `workspaceManager` is provided AND both workspaces carry stream
+ * ids, the merge is routed through `workspaceManager.mergeStream()` so
+ * it flows through git-cascade's tracker — gaining a `stream.merged`
+ * cascade event that propagates to the hub via CascadeBridge. This is
+ * the primary observability win of A3 in the integration plan.
+ *
+ * Falls back to raw `attemptMerge` (unchanged behavior) when either
+ * workspace lacks a stream id or no manager is passed — so
+ * programmatic/legacy callers keep working unchanged.
+ *
  * @param childId - Child agent to terminate
  * @param parentId - Parent agent to consolidate changes into
  * @param agentManager - Agent manager for operations
  * @param workspaceProvider - Optional workspace provider for getting agent workspaces
  * @param options - Optional consolidation options
+ * @param workspaceManager - Optional workspace manager; enables cascade-
+ *   event emission on the consolidation merge when both workspaces are
+ *   stream-backed.
  * @returns ConsolidationResult indicating success or failure
  */
 export async function terminateWithChangeConsolidation(
@@ -141,7 +154,15 @@ export async function terminateWithChangeConsolidation(
   parentId: AgentId,
   agentManager: CascadeAgentManager,
   workspaceProvider?: WorkspaceProvider,
-  options?: ConsolidationOptions
+  options?: ConsolidationOptions,
+  workspaceManager?: WorkspaceManager,
+  /**
+   * Optional task reference inherited from the parent agent's metadata.
+   * When provided + routing through the tracker, threaded into the
+   * `x-cascade/stream.merged` emit so the hub's cascade_merges row records
+   * which task drove the consolidation.
+   */
+  taskRef?: { resource_id: string; node_id: string }
 ): Promise<ConsolidationResult> {
   // If no workspace provider, just terminate normally
   if (!workspaceProvider) {
@@ -171,7 +192,61 @@ export async function terminateWithChangeConsolidation(
     // Continue with merge anyway - use the actual current branch
   }
 
-  // Attempt to merge child branch into parent's worktree
+  // Attempt to merge child branch into parent's worktree.
+  //
+  // Preferred path: route through workspaceManager.mergeStream when both
+  // workspaces have stream ids. Goes via git-cascade's tracker.mergeStream,
+  // which fires `x-cascade/stream.merged` with source/target stream ids so
+  // the hub's cascade projection + the source stream's `merged` status
+  // update in lockstep with the actual git operation.
+  if (
+    workspaceManager &&
+    childWorkspace.streamId &&
+    parentWorkspace.streamId
+  ) {
+    try {
+      const result = workspaceManager.mergeStream({
+        sourceStreamId: childWorkspace.streamId,
+        targetStreamId: parentWorkspace.streamId,
+        agentId: parentId,
+        worktree: parentWorkspace.path,
+        metadata: taskRef ? { task_ref: taskRef } : undefined,
+      });
+      if (result.success) {
+        await agentManager.terminate(childId, "changes_consolidated");
+        return {
+          success: true,
+          merged: true,
+          mergeCommit: result.newHead,
+        };
+      }
+      if (result.conflicts && result.conflicts.length > 0) {
+        // Tracker already aborted; emit and terminate with conflict reason.
+        console.warn(
+          `[cascade] Merge conflict consolidating ${childId} -> ${parentId} via tracker: ${result.conflicts.join(", ")}`
+        );
+        await agentManager.terminate(childId, "merge_conflict");
+        return {
+          success: false,
+          merged: false,
+          conflicts: result.conflicts,
+        };
+      }
+      // Tracker returned a non-conflict failure — fall through to raw
+      // git path so we don't regress the consolidation semantics for
+      // cases the tracker can't handle (e.g., stream in unexpected
+      // status, detached HEAD, branch-name mismatches).
+    } catch (err) {
+      console.warn(
+        `[cascade] tracker.mergeStream failed consolidating ${childId} -> ${parentId}; falling back to raw git: ${err instanceof Error ? err.message : String(err)}`
+      );
+      // Fall through to raw-git path below.
+    }
+  }
+
+  // Fallback: raw git merge. Preserves pre-A3 behavior when streams
+  // aren't available (programmatic callers, legacy role-shaped
+  // workspaces) or when the tracker path bailed.
   const mergeMessage =
     options?.mergeMessage ??
     `Merge changes from ${childId} (${childBranch})`;

package/src/map/__tests__/emit-event.test.ts

@@ -0,0 +1,71 @@
+/**
+ * Tests for MAPSidecar.emitEvent() — custom event emission to MAP hub.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { createMAPSidecar } from "../sidecar.js";
+import type { MAPSidecarConfig } from "../types.js";
+import type { AgentManager } from "../../agent/agent-manager.js";
+import type { AgentStore } from "../../agent/agent-store.js";
+import type { InboxAdapter, TasksAdapter } from "../../adapters/types.js";
+
+function mockDeps() {
+  return {
+    agentManager: {
+      onLifecycleEvent: vi.fn(() => () => {}),
+      list: vi.fn(() => []),
+      get: vi.fn(() => null),
+      spawn: vi.fn().mockResolvedValue({ agent: { id: "spawned-1" } }),
+      close: vi.fn().mockResolvedValue(undefined),
+    } as unknown as AgentManager,
+    agentStore: {
+      getAgent: vi.fn(() => null),
+      listAgents: vi.fn(() => []),
+    } as unknown as AgentStore,
+    inboxAdapter: {
+      onDelivery: vi.fn(),
+      offDelivery: vi.fn(),
+      send: vi.fn().mockResolvedValue("msg-1"),
+    } as unknown as InboxAdapter,
+    tasksAdapter: {
+      createTask: vi.fn().mockResolvedValue("task-1"),
+      transitionTask: vi.fn().mockResolvedValue(undefined),
+      listTasks: vi.fn().mockResolvedValue([]),
+      connected: true,
+    } as unknown as TasksAdapter,
+  };
+}
+
+describe("MAPSidecar.emitEvent", () => {
+  it("is a no-op when disconnected", async () => {
+    const deps = mockDeps();
+    const config: MAPSidecarConfig = {
+      server: "ws://127.0.0.1:1",
+      scope: "swarm:test",
+      reconnection: { enabled: false },
+      reconnectIntervalMs: 999999,
+    };
+
+    const sidecar = createMAPSidecar(deps, config);
+    await sidecar.start();
+    expect(sidecar.connected).toBe(false);
+
+    // Should not throw when disconnected
+    await sidecar.emitEvent!({ type: "dispatch.poll", dispatched: 0 });
+
+    await sidecar.stop();
+  }, 10000);
+
+  it("is defined on the sidecar", () => {
+    const deps = mockDeps();
+    const config: MAPSidecarConfig = {
+      server: "ws://127.0.0.1:1",
+      reconnection: { enabled: false },
+      reconnectIntervalMs: 999999,
+    };
+
+    const sidecar = createMAPSidecar(deps, config);
+    expect(sidecar.emitEvent).toBeDefined();
+    expect(typeof sidecar.emitEvent).toBe("function");
+  });
+});

package/src/map/cascade-action-handler.ts

@@ -0,0 +1,205 @@
+/**
+ * Cascade Action Handler — receives hub→runtime commands.
+ *
+ * Listens for `x-cascade/request.*` notifications from the OpenHive hub
+ * and dispatches to the GitCascadeAdapter. This is the inbound counterpart
+ * to the CascadeBridge (which handles outbound events).
+ *
+ * Actions are fire-and-forget from the hub's perspective: the hub sends
+ * the notification and the UI updates reactively when the resulting
+ * `x-cascade/stream.*` event flows back through the bridge.
+ *
+ * @module map/cascade-action-handler
+ */
+
+import type { GitCascadeAdapter } from '../workspace/git-cascade-adapter.js';
+
+export interface CascadeActionConnection {
+  onNotification(
+    method: string,
+    handler: (params: unknown) => void | Promise<void>,
+  ): void;
+  offNotification(
+    method: string,
+    handler: (params: unknown) => void | Promise<void>,
+  ): void;
+}
+
+const REQUEST_METHODS = {
+  MERGE: 'x-cascade/request.merge',
+  ABANDON: 'x-cascade/request.abandon',
+  PAUSE: 'x-cascade/request.pause',
+  RESUME: 'x-cascade/request.resume',
+  RESOLVE: 'x-cascade/request.resolve',
+  PUSH: 'x-cascade/request.push',
+  COMMIT: 'x-cascade/request.commit',
+} as const;
+
+/**
+ * Register cascade action handlers on the MAP connection.
+ * Returns a cleanup function that removes all handlers.
+ */
+export function setupCascadeActionHandlers(
+  connection: CascadeActionConnection,
+  adapter: GitCascadeAdapter,
+): () => void {
+  const handlers: Array<{
+    method: string;
+    handler: (params: unknown) => void | Promise<void>;
+  }> = [];
+
+  const register = (
+    method: string,
+    handler: (params: unknown) => void | Promise<void>,
+  ): void => {
+    connection.onNotification(method, handler);
+    handlers.push({ method, handler });
+  };
+
+  /** Find the first worktree checked out on a given stream. */
+  function findWorktreeForStream(streamId: string): string | null {
+    const wts = adapter.listWorktrees();
+    const match = wts.find((wt) => wt.currentStream === streamId);
+    return match?.path ?? null;
+  }
+
+  // ── Merge ─────────────────────────────────────────────────────────
+  register(REQUEST_METHODS.MERGE, (params: unknown) => {
+    const p = params as { stream_id?: string; target_stream_id?: string };
+    if (!p?.stream_id) return;
+
+    const stream = adapter.getStream(p.stream_id);
+    const targetStreamId = p.target_stream_id ?? stream?.parentStream;
+    if (!targetStreamId) return;
+
+    const worktreePath = findWorktreeForStream(p.stream_id);
+    if (!worktreePath) return;
+
+    try {
+      adapter.mergeStream({
+        sourceStream: p.stream_id,
+        targetStream: targetStreamId,
+        agentId: 'hub-request',
+        worktree: worktreePath,
+      });
+    } catch {
+      // Non-fatal — the resulting event (or conflict) will surface via the bridge
+    }
+  });
+
+  // ── Abandon ───────────────────────────────────────────────────────
+  register(REQUEST_METHODS.ABANDON, (params: unknown) => {
+    const p = params as { stream_id?: string; reason?: string };
+    if (!p?.stream_id) return;
+    try {
+      adapter.abandonStream(p.stream_id, { reason: p.reason ?? 'hub-request' });
+    } catch { /* non-fatal */ }
+  });
+
+  // ── Pause ─────────────────────────────────────────────────────────
+  register(REQUEST_METHODS.PAUSE, (params: unknown) => {
+    const p = params as { stream_id?: string; reason?: string };
+    if (!p?.stream_id) return;
+    try {
+      adapter.pauseStream(p.stream_id, p.reason);
+    } catch { /* non-fatal */ }
+  });
+
+  // ── Resume ────────────────────────────────────────────────────────
+  register(REQUEST_METHODS.RESUME, (params: unknown) => {
+    const p = params as { stream_id?: string };
+    if (!p?.stream_id) return;
+    try {
+      adapter.resumeStream(p.stream_id);
+    } catch { /* non-fatal */ }
+  });
+
+  // ── Resolve conflict ──────────────────────────────────────────────
+  register(REQUEST_METHODS.RESOLVE, (params: unknown) => {
+    const p = params as {
+      stream_id?: string;
+      conflict_id?: string;
+      strategy?: string;
+    };
+    if (!p?.stream_id || !p?.conflict_id) return;
+    try {
+      adapter.resolveConflict({
+        conflictId: p.conflict_id,
+        resolution: {
+          method: (p.strategy as 'ours' | 'theirs') ?? 'ours',
+          resolvedBy: 'hub-request',
+        },
+      });
+    } catch { /* non-fatal */ }
+  });
+
+  // ── Push ───────────────────────────────────────────────────────────
+  register(REQUEST_METHODS.PUSH, (params: unknown) => {
+    const p = params as {
+      stream_id?: string;
+      remote?: string;
+      target_ref?: string;
+    };
+    if (!p?.stream_id) return;
+
+    const worktreePath = findWorktreeForStream(p.stream_id);
+    if (!worktreePath) return;
+
+    const remote = p.remote ?? 'origin';
+    const streamBranch = `stream/${p.stream_id}`;
+    const targetRef = p.target_ref ?? streamBranch;
+
+    try {
+      const { execSync } = require('child_process');
+      execSync(`git push ${remote} ${streamBranch}:refs/heads/${targetRef}`, {
+        cwd: worktreePath,
+        stdio: 'pipe',
+        encoding: 'utf-8',
+      });
+      // Emit pushed event so the hub records it
+      adapter.notifyStreamPushed?.({
+        streamId: p.stream_id,
+        agentId: 'hub-request',
+        pushedCommit: execSync('git rev-parse HEAD', {
+          cwd: worktreePath,
+          encoding: 'utf-8',
+        }).trim(),
+        remote,
+        remoteRef: targetRef,
+        strategy: 'hub-push',
+      });
+    } catch { /* non-fatal — push failure is reported via absence of pushed event */ }
+  });
+
+  // ── Commit ────────────────────────────────────────────────────────
+  register(REQUEST_METHODS.COMMIT, (params: unknown) => {
+    const p = params as {
+      stream_id?: string;
+      message?: string;
+      metadata?: Record<string, unknown>;
+    };
+    if (!p?.stream_id) return;
+
+    const worktreePath = findWorktreeForStream(p.stream_id);
+    if (!worktreePath) return;
+
+    const message = p.message ?? 'checkpoint (hub-requested)';
+    try {
+      adapter.commitChanges({
+        streamId: p.stream_id,
+        agentId: 'hub-request',
+        worktree: worktreePath,
+        message,
+        metadata: p.metadata,
+      });
+    } catch { /* non-fatal — nothing to commit, or stream conflicted */ }
+  });
+
+  // ── Cleanup ───────────────────────────────────────────────────────
+  return () => {
+    for (const { method, handler } of handlers) {
+      connection.offNotification(method, handler);
+    }
+    handlers.length = 0;
+  };
+}

package/src/map/cascade-bridge.ts

@@ -21,6 +21,14 @@
  */
 
 import { CASCADE_METHODS } from 'git-cascade/events';
+
+// Fallback method names for events not yet present in the installed
+// git-cascade version (`STREAM_PAUSED`, `STREAM_RESUMED`,
+// `STREAM_ROLLED_BACK` were added after 0.0.7). When the dep is upgraded,
+// collapse these back into `CASCADE_METHODS.*` for a single source of truth.
+const X_CASCADE_STREAM_PAUSED = 'x-cascade/stream.paused' as const;
+const X_CASCADE_STREAM_RESUMED = 'x-cascade/stream.resumed' as const;
+const X_CASCADE_STREAM_ROLLED_BACK = 'x-cascade/stream.rolled_back' as const;
 import type { LifecycleBridgeConnection } from './lifecycle-bridge.js';
 import type {
   GitCascadeAdapter,
@@ -290,11 +298,41 @@ function translate(event: GitCascadeEvent): TranslatedCall | null {
         },
       };
 
-    // Local-only events with no MAP counterpart (Phase 1 scope).
-    // 'stream:updated', 'stream:forked', 'stream:paused', 'stream:resumed',
-    // 'worktree:*', 'task:*', 'change:*', 'conflict:*' (legacy local-only
-    // variant — cascade-bridge handles the cascade-driven 'conflict:resolved'
-    // separately above)
+    case 'stream:paused':
+      if (!d.streamId) return null;
+      return {
+        method: X_CASCADE_STREAM_PAUSED,
+        params: {
+          stream_id: d.streamId,
+          reason: d.reason,
+        },
+      };
+
+    case 'stream:resumed':
+      if (!d.streamId) return null;
+      return {
+        method: X_CASCADE_STREAM_RESUMED,
+        params: {
+          stream_id: d.streamId,
+        },
+      };
+
+    case 'stream:rolled_back':
+      if (!d.streamId) return null;
+      return {
+        method: X_CASCADE_STREAM_ROLLED_BACK,
+        params: {
+          stream_id: d.streamId,
+          strategy: d.strategy,
+          target: d.target,
+          new_head: d.newHead,
+        },
+      };
+
+    // Local-only events with no MAP counterpart.
+    // 'stream:updated', 'stream:forked', 'worktree:*', 'task:*',
+    // 'change:*', 'conflict:*' (legacy local-only variant — cascade-bridge
+    // handles the cascade-driven 'conflict:resolved' separately above)
     default:
       return null;
   }