macro-agent 0.1.7 → 0.1.10

package/src/map/cascade-bridge.ts

@@ -0,0 +1,301 @@
+/**
+ * Cascade Bridge — forwards GitCascadeAdapter events to the MAP hub as
+ * `x-cascade/*` notifications.
+ *
+ * macro-agent's GitCascadeAdapter maintains a structured `GitCascadeEvent`
+ * stream (translated from git-cascade's native `x-cascade/*` emissions + local
+ * adapter events). This bridge subscribes to that stream and translates
+ * **back** to `x-cascade/*` MAP method calls so the OpenHive hub receives the
+ * canonical event schema.
+ *
+ * The round-trip (git-cascade → adapter translation → bridge re-translation)
+ * is deliberate: it preserves the adapter's internal abstraction (other
+ * macro-agent code consumes `GitCascadeEvent`, not raw MAP params) while
+ * guaranteeing the hub sees the same schema git-cascade defines. The bridge
+ * is the only place that knows about both shapes.
+ *
+ * Standalone-safe: when `connection.isConnected` is false, events are
+ * dropped. macro-agent continues to work without an OpenHive hub.
+ *
+ * @module map/cascade-bridge
+ */
+
+import { CASCADE_METHODS } from 'git-cascade/events';
+import type { LifecycleBridgeConnection } from './lifecycle-bridge.js';
+import type {
+  GitCascadeAdapter,
+  GitCascadeEvent,
+} from '../workspace/git-cascade-adapter.js';
+
+export interface CascadeBridgeDisposable {
+  /** Unsubscribe from the adapter event stream. Safe to call multiple times. */
+  dispose: () => void;
+}
+
+export interface CascadeBridgeOptions {
+  /** Enable debug logging when events fail to forward. Defaults to false. */
+  verbose?: boolean;
+}
+
+/**
+ * Create a cascade bridge.
+ *
+ * Subscribes to `adapter.onEvent()` and forwards a fixed subset of events
+ * (the ones that have a canonical `x-cascade/*` method name) as MAP
+ * notifications via `connection.callExtension()`. Events with no MAP
+ * counterpart (`stream:forked`, `worktree:*`, `task:*`, `mergeQueue:*`, etc.)
+ * are silently ignored.
+ *
+ * @returns A disposable that unsubscribes from the adapter stream.
+ */
+export function createCascadeBridge(
+  connection: LifecycleBridgeConnection,
+  adapter: GitCascadeAdapter,
+  options: CascadeBridgeOptions = {}
+): CascadeBridgeDisposable {
+  const verbose = options.verbose ?? false;
+
+  const unsubscribe = adapter.onEvent((event: GitCascadeEvent) => {
+    if (!connection.isConnected) return;
+
+    const mapped = translate(event);
+    if (!mapped) return;
+
+    // Fire-and-forget: never block the adapter's event loop on a MAP RPC.
+    // Errors are swallowed to preserve standalone-safety; they indicate the
+    // hub is unreachable or the method isn't registered, neither of which
+    // should break local cascade operations.
+    void connection
+      .callExtension(mapped.method, mapped.params)
+      .catch((err) => {
+        if (verbose) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[cascade-bridge] failed to forward ${event.type} as ${mapped.method}:`,
+            err instanceof Error ? err.message : err
+          );
+        }
+      });
+  });
+
+  return { dispose: unsubscribe };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// GitCascadeEvent → x-cascade/* translation
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface TranslatedCall {
+  method: string;
+  params: Record<string, unknown>;
+}
+
+/**
+ * Translate a `GitCascadeEvent` into a MAP method call.
+ *
+ * Covers the 7 event types that have canonical MAP method names. Returns
+ * `null` for events that are macro-agent-internal (worktree/task/mergeQueue
+ * lifecycle, local-only forks, etc.).
+ *
+ * Field names flip from camelCase (macro-agent internal) back to snake_case
+ * (MAP wire format). The bridge is intentionally conservative — it only
+ * emits fields present on the event, letting the hub back-fill/ignore as
+ * needed.
+ */
+function translate(event: GitCascadeEvent): TranslatedCall | null {
+  const d = event.data;
+
+  switch (event.type) {
+    case 'stream:created':
+      return {
+        method: CASCADE_METHODS.STREAM_OPENED,
+        params: {
+          stream_id: d.streamId,
+          name: d.name,
+          agent_id: d.agentId,
+          base_commit: d.baseCommit,
+          parent_stream: d.parentStream,
+          branch_name: d.branchName,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'stream:committed':
+      return {
+        method: CASCADE_METHODS.STREAM_COMMITTED,
+        params: {
+          stream_id: d.streamId,
+          commit_hash: d.commit,
+          change_id: d.changeId,
+          agent_id: d.agentId,
+          message_summary: d.messageSummary,
+          files_touched: d.filesTouched,
+          parent_commit: d.parentCommit,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'stream:merged':
+      return {
+        method: CASCADE_METHODS.STREAM_MERGED,
+        params: {
+          source_stream_id: d.sourceStreamId,
+          target_stream_id: d.targetStreamId,
+          merge_commit: d.mergeCommit,
+          agent_id: d.agentId,
+          strategy: d.strategy,
+          source_commit: d.sourceCommit,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'stream:conflicted':
+      return {
+        method: CASCADE_METHODS.STREAM_CONFLICTED,
+        params: {
+          stream_id: d.streamId,
+          conflict_id: d.conflictId,
+          conflicted_files: d.conflictedFiles,
+          agent_id: d.agentId,
+          conflicting_commit: d.conflictingCommit,
+          target_commit: d.targetCommit,
+          source: d.source,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'conflict:resolved':
+      // The adapter emits this from two sources: workspace-manager's local
+      // resolveConflict path (carries resolvedBy + resolutionCommit) AND the
+      // forwarded git-cascade stream.conflict_resolved (carries the explicit
+      // resolution_method). Bridge only forwards events with conflict_id +
+      // stream_id present (the cascade-driven shape).
+      if (!d.streamId || !d.conflictId) return null;
+      return {
+        method: CASCADE_METHODS.STREAM_CONFLICT_RESOLVED,
+        params: {
+          stream_id: d.streamId,
+          conflict_id: d.conflictId,
+          resolution_method:
+            (d.resolutionMethod as string | undefined) ??
+            (d.resolvedBy ? 'agent' : 'manual'),
+          resolved_by: d.resolvedBy,
+          resolution_summary: d.resolutionSummary,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'stream:abandoned':
+      return {
+        method: CASCADE_METHODS.STREAM_ABANDONED,
+        params: {
+          stream_id: d.streamId,
+          reason: d.reason,
+          cascade: d.cascade,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'stream:pushed':
+      // Trunk-style push to a remote (direct-push / optimistic-push). Hub
+      // sees this as the "merged" equivalent for non-stream targets.
+      if (!d.streamId || !d.pushedCommit || !d.remoteRef) return null;
+      return {
+        method: CASCADE_METHODS.STREAM_PUSHED,
+        params: {
+          stream_id: d.streamId,
+          agent_id: d.agentId,
+          pushed_commit: d.pushedCommit,
+          remote: d.remote ?? 'origin',
+          remote_ref: d.remoteRef,
+          strategy: d.strategy,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'cascade:rebased':
+      return {
+        method: CASCADE_METHODS.CASCADE_REBASED,
+        params: {
+          stream_id: d.streamId,
+          agent_id: d.agentId,
+          triggered_by_stream_id: d.triggeredByStreamId,
+          triggered_by_agent_id: d.triggeredByAgentId,
+          new_base_commit: d.newBaseCommit,
+          new_head: d.newHead,
+          new_commits: d.newCommits,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'cascade:completed':
+      return {
+        method: CASCADE_METHODS.CASCADE_COMPLETED,
+        params: {
+          root_stream_id: d.rootStreamId,
+          agent_id: d.agentId,
+          strategy: d.strategy,
+          updated_streams: d.updatedStreams,
+          failed_streams: d.failedStreams,
+          skipped_streams: d.skippedStreams,
+          deferred_streams: d.deferredStreams,
+          metadata: d.metadata,
+        },
+      };
+
+    case 'mergeQueue:added':
+      if (!d.entryId || !d.streamId) return null;
+      return {
+        method: CASCADE_METHODS.QUEUE_ADDED,
+        params: {
+          entry_id: d.entryId,
+          stream_id: d.streamId,
+          target_branch: (d.targetBranch as string | undefined) ?? 'main',
+          metadata: d.metadata,
+        },
+      };
+
+    case 'mergeQueue:ready':
+      if (!d.entryId || !d.streamId) return null;
+      return {
+        method: CASCADE_METHODS.QUEUE_READY,
+        params: {
+          entry_id: d.entryId,
+          stream_id: d.streamId,
+          target_branch: (d.targetBranch as string | undefined) ?? 'main',
+        },
+      };
+
+    case 'mergeQueue:cancelled':
+      if (!d.entryId || !d.streamId) return null;
+      return {
+        method: CASCADE_METHODS.QUEUE_CANCELLED,
+        params: {
+          entry_id: d.entryId,
+          stream_id: d.streamId,
+          target_branch: (d.targetBranch as string | undefined) ?? 'main',
+          reason: d.reason,
+        },
+      };
+
+    case 'mergeQueue:removed':
+      if (!d.entryId || !d.streamId) return null;
+      return {
+        method: CASCADE_METHODS.QUEUE_REMOVED,
+        params: {
+          entry_id: d.entryId,
+          stream_id: d.streamId,
+          target_branch: (d.targetBranch as string | undefined) ?? 'main',
+          outcome: d.outcome,
+        },
+      };
+
+    // 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)
+    default:
+      return null;
+  }
+}

package/src/map/lifecycle-bridge.ts

@@ -13,13 +13,6 @@ import type { TaskBridge } from "./types.js";
 
 /** Minimal interface for the MAP connection methods we need */
 export interface LifecycleBridgeConnection {
-  spawn(options: {
-    agentId?: string | undefined;
-    name?: string | undefined;
-    role?: string | undefined;
-    scopes?: string[];
-    metadata?: Record<string, unknown>;
-  }): Promise<unknown>;
   callExtension(method: string, params?: unknown): Promise<unknown>;
   get isConnected(): boolean;
 }
@@ -28,6 +21,8 @@ interface RegisteredAgent {
   id: string;
   name: string;
   role: string;
+  /** MAP-assigned agent ID (ULID) from the hub, used for unregistration */
+  mapId?: string;
 }
 
 /**
@@ -41,9 +36,27 @@ export function createLifecycleBridge(
   agentStore: AgentStore,
   scope: string,
   taskBridge?: TaskBridge,
+  getLocalMapId?: (localAgentId: string) => string | undefined,
 ): { callback: AgentLifecycleCallback; cleanup: () => Promise<void> } {
   const registered = new Map<string, RegisteredAgent>();
 
+  /**
+   * Poll for the local MAP server's assigned ID for an agent.
+   * The local MAP server and the lifecycle bridge both listen to the same
+   * lifecycle callback, so they may fire in any order. Poll briefly to handle
+   * the race.
+   */
+  async function waitForLocalMapId(localAgentId: string, timeoutMs = 500): Promise<string | undefined> {
+    if (!getLocalMapId) return undefined;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const id = getLocalMapId(localAgentId);
+      if (id) return id;
+      await new Promise((r) => setTimeout(r, 20));
+    }
+    return getLocalMapId(localAgentId);
+  }
+
   const callback: AgentLifecycleCallback = (event) => {
     if (!connection.isConnected) return;
 
@@ -55,22 +68,57 @@ export function createLifecycleBridge(
         const entry: RegisteredAgent = { id: agent.id, name, role };
         registered.set(agent.id, entry);
 
-        // Register agent with MAP hub
-        connection
-          .spawn({
-            agentId: agent.id,
-            name,
-            role,
-            scopes: [scope],
-            metadata: {
-              parent: (agent as any).parent_id ?? undefined,
-              team: (agent as any).team ?? undefined,
-              cwd: (agent as any).cwd ?? undefined,
-            },
-          })
-          .catch(() => {
+        // Build per-agent capabilities.
+        // Coordinators (head managers) support ACP for interactive chat.
+        const capabilities: Record<string, unknown> = {
+          messaging: { canReceive: true },
+        };
+        if (role === "coordinator") {
+          capabilities.protocols = ["acp"];
+          capabilities.acp = { version: "2024-10-07" };
+        }
+
+        // Register agent with MAP hub (use map/agents/register to preserve
+        // per-agent capabilities; map/agents/spawn drops them).
+        // Include the local MAP server's ID in metadata so clients can route
+        // ACP messages to the correct agent on the macro-agent's own MAP server.
+        // Also include provider_session_id so OpenHive can find the underlying
+        // Claude Code JSONL transcript on disk for history recovery.
+        const agentMetadata = (agent as any).metadata as Record<string, unknown> | undefined;
+        const providerSessionId =
+          typeof agentMetadata?.provider_session_id === "string"
+            ? agentMetadata.provider_session_id
+            : undefined;
+        (async () => {
+          const peerMapId = await waitForLocalMapId(agent.id);
+          try {
+            const result: any = await connection.callExtension("map/agents/register", {
+              name,
+              role,
+              capabilities,
+              metadata: {
+                // From the hub's perspective these IDs identify this agent on
+                // the macro-agent (peer) side. `peerAgentId` is macro-agent's
+                // internal store id; `peerMapId` is its local MAP server ULID.
+                // Hub callers use these to address the agent in routing
+                // (ACP streams target peerMapId, lifecycle ops use peerAgentId).
+                peerAgentId: agent.id,
+                peerMapId,
+                provider_session_id: providerSessionId,
+                parent: (agent as any).parent_id ?? undefined,
+                team: (agent as any).team ?? undefined,
+                cwd: (agent as any).cwd ?? undefined,
+              },
+            });
+            // Track the MAP-assigned agent ID for unregistration
+            const mapId = result?.agent?.id ?? result?.id;
+            if (mapId) {
+              entry.mapId = mapId;
+            }
+          } catch {
             // Silent — MAP hub may be temporarily unavailable
-          });
+          }
+        })();
 
         // Bridge task creation if agent has a task
         if (taskBridge && (agent as any).task_id) {
@@ -88,12 +136,14 @@ export function createLifecycleBridge(
 
       case "stopped": {
         const agent = event.agent;
+        const entry = registered.get(agent.id);
         registered.delete(agent.id);
 
-        // Unregister agent from MAP hub
+        // Unregister agent from MAP hub (use MAP-assigned ID if available)
+        const unregId = entry?.mapId ?? agent.id;
         connection
           .callExtension("map/agents/unregister", {
-            agentId: agent.id,
+            agentId: unregId,
             reason: event.reason ?? "stopped",
           })
           .catch(() => {
@@ -123,11 +173,11 @@ export function createLifecycleBridge(
       registered.clear();
       return;
     }
-    // Unregister all tracked agents
-    const promises = Array.from(registered.keys()).map((agentId) =>
+    // Unregister all tracked agents (use MAP-assigned IDs)
+    const promises = Array.from(registered.values()).map((entry) =>
       connection
         .callExtension("map/agents/unregister", {
-          agentId,
+          agentId: entry.mapId ?? entry.id,
           reason: "sidecar_shutdown",
         })
         .catch(() => {}),

package/src/map/server.ts

@@ -107,7 +107,7 @@ export function createMAPServerInstance(
             role: params.role ?? "worker",
             state: "idle",
             sessionId: ctx?.session?.id,
-            metadata: { localAgentId: spawned.id, task: params.task },
+            metadata: { peerAgentId: spawned.id, task: params.task },
           });
           if (registered?.id) {
             mapIdToLocalId.set(registered.id, spawned.id);
@@ -145,6 +145,38 @@ export function createMAPServerInstance(
       return { agent: { id: spawned.id } };
     };
 
+    /**
+     * Terminate a running agent. Accepts either the agent's local ID or the
+     * MAP-assigned ULID (we resolve back to local via mapIdToLocalId).
+     * Reason defaults to "stopped"; use "cancelled" for user-initiated stops.
+     */
+    handlers["_macro/terminateAgent"] = async (params) => {
+      const agentIdParam = params.agentId as string | undefined;
+      const reason = (params.reason as string) ?? "cancelled";
+      if (!agentIdParam) {
+        return { success: false, error: "agentId is required" };
+      }
+      // Resolve either a MAP ULID or a local agent ID to our internal ID.
+      const localId = mapIdToLocalId.get(agentIdParam) ?? agentIdParam;
+      try {
+        await agentManager.terminate(localId as any, reason as any);
+        return { success: true };
+      } catch (err) {
+        return { success: false, error: (err as Error).message };
+      }
+    };
+
+    /**
+     * Inspect ACP stream → peer agent bindings on this MAP server.
+     * Each stream carries the peer agent id (macro-agent's internal store id)
+     * it was opened against, set by the bridge from MAP routing. Useful for
+     * routing tests and debugging multi-coordinator scenarios.
+     */
+    handlers["_macro/getAcpStreamBindings"] = async () => {
+      if (!acpBridge) return { bindings: [] };
+      return { bindings: acpBridge.getStreamBindings() };
+    };
+
     // ── Task extensions ───────────────────────────────────────────
     handlers["_macro/task/list"] = async () => {
       if (!tasksAdapter.connected) return { tasks: [] };
@@ -404,16 +436,21 @@ export function createMAPServerInstance(
         try {
           if (event.type === "spawned" || event.type === "started") {
             const agent = event.agent;
-            // Register agent in MAPServer's registry so it's visible to clients.
-            // We wrap in try/catch because the registry's event bus may throw
-            // if subscription filters encounter unexpected state.
+            // Register agent ONCE. spawn() fires "spawned" immediately followed
+            // by "started", so without this guard the listener re-registers
+            // on the second event — generating a fresh MAP ULID and overwriting
+            // localIdToMapId. Consumers racing against that overwrite (like the
+            // sidecar's lifecycle bridge, which snapshots peerMapId into hub
+            // metadata) end up disagreeing with _macro/spawnAgent's return
+            // value on which ULID refers to this agent.
+            if (localIdToMapId.has(agent.id)) return;
             try {
               const registered = mapServer.agents.register({
                 name: agent.name ?? agent.id,
                 role: agent.role ?? "worker",
                 state: "idle",
                 metadata: {
-                  localAgentId: agent.id, // Store local ID in metadata
+                  peerAgentId: agent.id, // macro-agent's internal store id
                   parent: (agent as any).parent ?? null,
                   task: (agent as any).task ?? null,
                   cwd: (agent as any).cwd ?? null,
@@ -454,7 +491,7 @@ export function createMAPServerInstance(
             role: agent.role ?? "worker",
             state: agent.state === "running" ? "busy" : "idle",
             metadata: {
-              localAgentId: agent.id,
+              peerAgentId: agent.id,
               parent: agent.parent ?? null,
               task: agent.task ?? null,
             },
@@ -535,5 +572,9 @@ export function createMAPServerInstance(
     getConnectionCount(): number {
       return connectionCount;
     },
+
+    getLocalMapId(localAgentId: string): string | undefined {
+      return localIdToMapId.get(localAgentId);
+    },
   };
 }

package/src/map/sidecar.ts

@@ -35,7 +35,7 @@ export function createMAPSidecar(
   deps: MAPSidecarDeps,
   config: MAPSidecarConfig,
 ): MAPSidecar {
-  const { agentManager, agentStore, inboxAdapter, tasksAdapter } = deps;
+  const { agentManager, agentStore, inboxAdapter, tasksAdapter, getLocalMapId, gitCascadeAdapter } = deps;
   const scope = config.scope ?? "swarm:macro-agent";
   const agentName = config.agentName ?? "macro-agent-sidecar";
 
@@ -50,6 +50,7 @@ export function createMAPSidecar(
   let trajectoryReporter: TrajectoryReporter | null = null;
   let taskBridge: TaskBridge | null = null;
   let coordinationCleanup: (() => void) | null = null;
+  let cascadeBridgeCleanup: (() => void) | null = null;
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
 
   /**
@@ -82,6 +83,10 @@ export function createMAPSidecar(
       coordinationCleanup();
       coordinationCleanup = null;
     }
+    if (cascadeBridgeCleanup) {
+      try { cascadeBridgeCleanup(); } catch { /* non-critical */ }
+      cascadeBridgeCleanup = null;
+    }
     if (trajectoryReporter) {
       trajectoryReporter.stop();
       trajectoryReporter = null;
@@ -115,8 +120,6 @@ export function createMAPSidecar(
         capabilities: {
           messaging: { canSend: true, canReceive: true },
           mail: { canCreate: true, canJoin: true, canViewHistory: true },
-          protocols: ['acp'],
-          acp: { version: '2024-10-07' },
           trajectory: { canReport: true, canServeContent: false },
           tasks: {
             canCreate: true,
@@ -128,6 +131,10 @@ export function createMAPSidecar(
         metadata: {
           systemId: config.systemId ?? "macro-agent",
           type: "macro-agent-sidecar",
+          // Signals that this swarm can spawn ACP-capable coordinators on demand,
+          // even before any coordinator has registered. The hub's /sessions/create-acp
+          // endpoint handles the spawn via _macro/spawnAgent when no ACP agent exists.
+          canHostAcp: true,
         },
         reconnection: {
           enabled: config.reconnection?.enabled ?? true,
@@ -177,6 +184,19 @@ export function createMAPSidecar(
       isConnected = true;
       } // end if (!isConnected)
 
+      // Publish sidecar metadata to the hub. The MAP SDK's connect()/register()
+      // does not propagate the `metadata` field from connect options — it only
+      // forwards name/role/capabilities/scopes. Call updateMetadata explicitly
+      // so the hub sees canHostAcp (and any other metadata the UI relies on).
+      try {
+        const metadata = (connectOpts.metadata as Record<string, unknown>) ?? {};
+        if (typeof connection.updateMetadata === "function") {
+          await connection.updateMetadata(metadata);
+        }
+      } catch {
+        // Non-fatal — metadata is advisory
+      }
+
       // Monitor connection state
       connection.onStateChange(
         (newState: string, _oldState: string) => {
@@ -254,6 +274,7 @@ export function createMAPSidecar(
       agentStore,
       scope,
       taskBridge,
+      getLocalMapId,
     );
     lifecycleCallback = bridge.callback;
     lifecycleCleanup = bridge.cleanup;
@@ -272,6 +293,13 @@ export function createMAPSidecar(
       tasksAdapter,
       trajectoryReporter,
     });
+
+    // 5. Cascade Bridge (optional — only when a GitCascadeAdapter is available)
+    if (gitCascadeAdapter) {
+      const { createCascadeBridge } = await import("./cascade-bridge.js");
+      const cascadeBridge = createCascadeBridge(connection, gitCascadeAdapter);
+      cascadeBridgeCleanup = cascadeBridge.dispose;
+    }
   }
 
   return {

package/src/map/types.ts

@@ -68,6 +68,21 @@ export interface MAPSidecarDeps {
   agentStore: AgentStore;
   inboxAdapter: InboxAdapter;
   tasksAdapter: TasksAdapter;
+  /**
+   * Optional lookup for the local MAP server's ULID for a given local agent ID.
+   * When provided, the lifecycle bridge includes this ID in hub registration
+   * metadata so clients (e.g., SwarmCraft) can target the agent correctly on
+   * the macro-agent's own MAP server.
+   */
+  getLocalMapId?: (localAgentId: string) => string | undefined;
+  /**
+   * Optional GitCascadeAdapter. When provided, the sidecar wires a cascade
+   * bridge that forwards the adapter's event stream to the hub as
+   * `x-cascade/*` MAP notifications. Leave undefined to disable cascade
+   * event forwarding (macro-agent will still use cascade internally, just
+   * without hub observability).
+   */
+  gitCascadeAdapter?: import("../workspace/git-cascade-adapter.js").GitCascadeAdapter;
 }
 
 // =============================================================================
@@ -244,4 +259,9 @@ export interface MAPServerInstance {
   getUrl(): string;
   /** Get number of active connections */
   getConnectionCount(): number;
+  /**
+   * Resolve a local agent ID (macro-agent internal) to its MAP server-assigned ULID.
+   * Returns undefined if the agent is not registered on the MAP server yet.
+   */
+  getLocalMapId(localAgentId: string): string | undefined;
 }

package/src/mcp/tools/done-v2.ts

@@ -106,6 +106,15 @@ function buildLifecycleContext(
     streamId: record?.workspace_stream_id ?? process.env.MACRO_STREAM_ID,
   };
 
+  // Pull task_ref out of agent metadata if it was stashed there at spawn
+  // time. Validates the shape — bad data is silently dropped rather than
+  // pushed downstream into cascade payloads.
+  const meta = record?.metadata as Record<string, unknown> | undefined;
+  const tr = meta?.task_ref as { resource_id?: unknown; node_id?: unknown } | undefined;
+  if (tr && typeof tr.resource_id === "string" && typeof tr.node_id === "string") {
+    ctx.taskRef = { resource_id: tr.resource_id, node_id: tr.node_id };
+  }
+
   // Resolve capabilities for dispatch
   if (roleRegistry) {
     try {