macro-agent 0.2.4 → 0.2.5

package/src/agent/__tests__/agent-manager-v2.completion-signal.test.ts

@@ -0,0 +1,284 @@
+/**
+ * S1 (completion-detection) unit tests for promptUntilDone's optional
+ * `isComplete` predicate.
+ *
+ * The macro `promptUntilDone` normally completes ONLY when the agent calls the
+ * macro done() tool; otherwise it re-prompts "call done()" up to maxFollowUps
+ * times (each a slow full turn). The τ agent calls τ's `finish`, not macro
+ * done(), so without an external completion predicate the loop exhausts
+ * maxFollowUps and Atlas.solve() hangs until the rollout backstop.
+ *
+ * These tests drive promptUntilDone with a MOCKED acp session `prompt` stream
+ * (no live agent) and assert:
+ *   - an `isComplete` that flips true after the first streamed update breaks the
+ *     loop on attempt 0, calls terminate(agentId, "completed"), returns
+ *     completedExternally:true, and does NOT exhaust maxFollowUps;
+ *   - back-compat: with NO predicate the existing done()-detection is unchanged.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createAgentManagerV2 } from "../agent-manager-v2.js";
+import { AgentStore } from "../agent-store.js";
+import type { AgentManager } from "../agent-manager.js";
+import type { InboxAdapter, TasksAdapter } from "../../adapters/types.js";
+
+// ── Mock acp-factory: a controllable per-spawn session.prompt stream ───────
+// `promptStreamFactory` is reassigned per test to control what each prompt
+// attempt yields. `promptCallCount` lets us assert how many attempts ran.
+let promptStreamFactory: () => AsyncIterable<unknown>;
+let promptCallCount = 0;
+// Invoked when the agent handle is closed (i.e. terminate() tears down the
+// session). The silent-stream repro registers a hook here so that ONLY a real
+// terminate() can end its otherwise-forever-blocked stream — faithfully
+// modelling the live "stream ends/throws on teardown" behavior. On the old
+// reactive-only code terminate() is never called mid-stream, so the stream
+// never ends → the for-await hangs (red).
+let onHandleClose: (() => void) | null = null;
+
+vi.mock("acp-factory", () => ({
+  AgentFactory: {
+    spawn: vi.fn().mockResolvedValue({
+      createSession: vi.fn().mockResolvedValue({
+        id: "provider-session-1",
+        prompt: vi.fn().mockImplementation(() => {
+          promptCallCount++;
+          return promptStreamFactory();
+        }),
+        forkWithFlush: vi.fn().mockResolvedValue({ id: "forked-session-1" }),
+      }),
+      loadSession: vi.fn().mockResolvedValue({ id: "loaded-session-1" }),
+      close: vi.fn().mockImplementation(async () => {
+        onHandleClose?.();
+      }),
+      isRunning: vi.fn().mockReturnValue(true),
+    }),
+  },
+}));
+
+function createMockInboxAdapter(): InboxAdapter {
+  return {
+    registerAgent: vi.fn().mockResolvedValue(undefined),
+    deregisterAgent: vi.fn().mockResolvedValue(undefined),
+    send: vi.fn().mockResolvedValue("msg-1"),
+    onDelivery: vi.fn(),
+    offDelivery: vi.fn(),
+    checkInbox: vi.fn().mockResolvedValue([]),
+    readThread: vi.fn().mockResolvedValue([]),
+    setSignalFilter: vi.fn(),
+    setEmissionValidator: vi.fn(),
+    socketPath: "/tmp/test-inbox.sock",
+    stop: vi.fn().mockResolvedValue(undefined),
+  } as unknown as InboxAdapter;
+}
+
+// A single benign streamed update (an agent message chunk — NOT a done() tool
+// call), used to trigger the isComplete check mid-stream.
+function* oneMessageUpdate(): Generator<unknown> {
+  yield {
+    sessionUpdate: "agent_message_chunk",
+    content: { type: "text", text: "working" },
+  };
+}
+
+// A stream that emits a macro done() tool-call update (title ends with __done),
+// for the back-compat path.
+function* doneToolUpdate(): Generator<unknown> {
+  yield {
+    sessionUpdate: "tool_call",
+    title: "mcp__macro-agent__done",
+    rawInput: { status: "completed" },
+  };
+}
+
+async function* asAsync(gen: Iterable<unknown>): AsyncIterable<unknown> {
+  for (const u of gen) yield u;
+}
+
+// Reproduces the live τ hang: the agent runs the whole episode in ONE prompt()
+// call, yields a couple of updates, then the stream goes SILENT but does NOT
+// close — the async iterator just blocks forever. With only the reactive
+// per-update / per-attempt checks, isComplete is never re-evaluated and the
+// for-await never unblocks.
+//
+// The ONLY way out is terminate(): it tears down the session (calls
+// handle.close()), which we wire to release the dangling await — faithfully
+// modelling the live "stream ends on teardown" behavior. So on the old
+// reactive-only code (terminate never called mid-stream) the stream NEVER ends
+// → hang (red); the concurrent poller calls terminate → close → release →
+// stream ends → completion (green).
+function silentThenHangStream(): () => AsyncIterable<unknown> {
+  let release: () => void = () => {};
+  const hang = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  // terminate() → handle.close() → release the blocked stream.
+  onHandleClose = () => release();
+  async function* gen(): AsyncIterable<unknown> {
+    yield {
+      sessionUpdate: "agent_message_chunk",
+      content: { type: "text", text: "working 1" },
+    };
+    yield {
+      sessionUpdate: "agent_message_chunk",
+      content: { type: "text", text: "working 2" },
+    };
+    // Silent-but-open: block forever until terminate() releases it — exactly
+    // the live failure mode (silent, non-closing iterator).
+    await hang;
+  }
+  return gen;
+}
+
+function createMockTasksAdapter(): TasksAdapter {
+  return {
+    createTask: vi.fn().mockResolvedValue("ot-task-1"),
+    assignTask: vi.fn().mockResolvedValue(undefined),
+    transitionTask: vi.fn().mockResolvedValue(undefined),
+    getTask: vi.fn().mockResolvedValue(null),
+    queryReady: vi.fn().mockResolvedValue([]),
+    listTasks: vi.fn().mockResolvedValue([]),
+    addBlocker: vi.fn().mockResolvedValue(undefined),
+    removeBlocker: vi.fn().mockResolvedValue(undefined),
+    claimTask: vi.fn().mockResolvedValue(null),
+    unclaimTask: vi.fn().mockResolvedValue(undefined),
+    listClaimable: vi.fn().mockResolvedValue([]),
+    connect: vi.fn().mockResolvedValue(undefined),
+    disconnect: vi.fn(),
+    connected: true,
+  } as unknown as TasksAdapter;
+}
+
+describe("promptUntilDone — S1 external completion predicate", () => {
+  let agentStore: AgentStore;
+  let inboxAdapter: InboxAdapter;
+  let manager: AgentManager;
+
+  beforeEach(() => {
+    promptCallCount = 0;
+    onHandleClose = null;
+    agentStore = new AgentStore(":memory:");
+    inboxAdapter = createMockInboxAdapter();
+    manager = createAgentManagerV2(agentStore, inboxAdapter, createMockTasksAdapter(), {
+      defaultCwd: "/tmp/test",
+    });
+  });
+
+  afterEach(async () => {
+    await manager.close();
+    agentStore.close();
+  });
+
+  it("breaks on attempt 0 when isComplete flips true after the first update; terminates 'completed'; completedExternally:true; does NOT exhaust maxFollowUps", async () => {
+    promptStreamFactory = () => asAsync(oneMessageUpdate());
+
+    const spawned = await manager.spawn({ task: "tau episode", role: "worker" });
+    expect(manager.hasActiveSession(spawned.id)).toBe(true);
+
+    // Flip true after the first update is observed.
+    let updates = 0;
+    const isComplete = vi.fn(() => {
+      updates++;
+      return updates >= 1; // true from the first check on
+    });
+
+    const maxFollowUps = 16;
+    const result = await manager.promptUntilDone(spawned.id, "go", {
+      maxFollowUps,
+      isComplete,
+    });
+
+    expect(result.completedExternally).toBe(true);
+    expect(result.doneCalled).toBe(false);
+    // Only the initial attempt ran — no "please call done()" re-prompts.
+    expect(promptCallCount).toBe(1);
+    expect(isComplete).toHaveBeenCalled();
+    // Mirrors the done() path: the agent is terminated (its active session is
+    // torn down + the store record transitions to "stopped"). terminate() is an
+    // internal closure call, so we observe its EFFECT rather than spy on it.
+    expect(manager.hasActiveSession(spawned.id)).toBe(false);
+    expect(agentStore.getAgent(spawned.id)!.state).toBe("stopped");
+  });
+
+  it("REPRO (live hang): silent-but-open stream + poll-only isComplete → concurrent poller terminates and returns bounded (completedExternally:true, promptCallCount===1)", async () => {
+    // The stream yields 2 updates then blocks forever without closing. The
+    // predicate is true from the start but can ONLY be observed via the
+    // concurrent poller, because no further updates arrive to drive the
+    // reactive per-update check, and the per-attempt check never runs (the
+    // for-await never ends on its own). On the OLD reactive-only code this
+    // test HANGS until the vitest timeout (red). With the concurrent poller it
+    // returns within a few poll intervals (green).
+    promptStreamFactory = silentThenHangStream();
+
+    const spawned = await manager.spawn({ task: "tau episode (silent)", role: "worker" });
+    expect(manager.hasActiveSession(spawned.id)).toBe(true);
+
+    // FALSE during the streamed updates (so the reactive per-update check
+    // (a) does NOT catch it), then TRUE once the episode has externally
+    // completed. After the 2 updates the stream goes silent forever, so the
+    // reactive checks never run again — ONLY the concurrent poller can observe
+    // the flip. (The 2 per-update reactive checks consume the first 2 false
+    // returns; everything after — i.e. the poller — sees true.)
+    let checks = 0;
+    const isComplete = vi.fn(() => {
+      checks++;
+      return checks > 2;
+    });
+
+    const pollIntervalMs = 20;
+    const maxFollowUps = 16;
+
+    const start = Date.now();
+    const result = await manager.promptUntilDone(spawned.id, "go", {
+      maxFollowUps,
+      isComplete,
+      pollIntervalMs,
+    });
+    const elapsed = Date.now() - start;
+
+    // Bounded return — NOT a hang, NOT maxFollowUps exhaustion.
+    expect(elapsed).toBeLessThan(2000);
+    expect(result.completedExternally).toBe(true);
+    expect(result.doneCalled).toBe(false);
+    // The whole episode is one prompt() call; no re-prompts.
+    expect(promptCallCount).toBe(1);
+    expect(isComplete).toHaveBeenCalled();
+    // terminate('completed') was effected: session torn down + store stopped.
+    expect(manager.hasActiveSession(spawned.id)).toBe(false);
+    expect(agentStore.getAgent(spawned.id)!.state).toBe("stopped");
+  });
+
+  it("back-compat: with NO predicate, done()-detection is unchanged (doneCalled true, completedExternally false, terminate 'completed')", async () => {
+    promptStreamFactory = () => asAsync(doneToolUpdate());
+
+    const spawned = await manager.spawn({ task: "normal agent", role: "worker" });
+
+    const result = await manager.promptUntilDone(spawned.id, "go", {
+      maxFollowUps: 2,
+    });
+
+    expect(result.doneCalled).toBe(true);
+    expect(result.doneStatus).toBe("completed");
+    expect(result.completedExternally).toBe(false);
+    expect(promptCallCount).toBe(1);
+    // done()-detection still terminates the agent (unchanged behavior).
+    expect(manager.hasActiveSession(spawned.id)).toBe(false);
+    expect(agentStore.getAgent(spawned.id)!.state).toBe("stopped");
+  });
+
+  it("no predicate + no done(): exhausts maxFollowUps (unchanged re-prompt behavior)", async () => {
+    // Empty stream each attempt — agent never calls done(), no predicate.
+    promptStreamFactory = () => asAsync([]);
+
+    const spawned = await manager.spawn({ task: "silent agent", role: "worker" });
+
+    const maxFollowUps = 3;
+    const result = await manager.promptUntilDone(spawned.id, "go", {
+      maxFollowUps,
+    });
+
+    expect(result.doneCalled).toBe(false);
+    expect(result.completedExternally).toBe(false);
+    // Initial attempt + maxFollowUps re-prompts = maxFollowUps + 1 prompt calls.
+    expect(promptCallCount).toBe(maxFollowUps + 1);
+  });
+});

package/src/agent/agent-manager-v2.ts

@@ -48,7 +48,7 @@ import type {
   AgentLifecycleEvent,
   AgentConfig,
   ContinueAgentOptions,
-  MCPServerConfig,
+  MCPServerStdioConfig,
 } from "./types.js";
 import { AgentManagerError } from "./types.js";
 import type { RoleRegistry, Capability } from "../roles/types.js";
@@ -220,6 +220,12 @@ export function createAgentManagerV2(
   const activeSessions = new Map<AgentId, ActiveSession>();
   const agentWorkspaces = new Map<AgentId, Workspace>();
   const lifecycleListeners = new Set<AgentLifecycleCallback>();
+  // In-flight fire-and-forget terminate() promises (e.g. the promptUntilDone
+  // completion poller tears the agent down without awaiting it, to keep
+  // completion latency low). close() awaits these so shutdown cannot return
+  // while a group-kill is still racing — which would let process.exit orphan
+  // the subtree.
+  const pendingTerminations = new Set<Promise<unknown>>();
   let spawnInterceptor: SpawnInterceptor | null = null;
   let isShuttingDown = false;
   let mapServerUrl: string | undefined;
@@ -285,7 +291,7 @@ export function createAgentManagerV2(
     lineage?: string[];
     sessionId?: string;
     streamId?: string;
-  }): MCPServerConfig {
+  }): MCPServerStdioConfig {
     const env: Record<string, string> = {
       MACRO_AGENT_ID: opts.agentId,
       MACRO_PARENT_ID: opts.parentId,
@@ -759,15 +765,28 @@ export function createAgentManagerV2(
             value: v,
           })),
         },
-        ...(agentConfig?.mcpServers?.map((s) => ({
-          name: s.name,
-          command: s.command,
-          args: s.args ?? [],
-          env: Object.entries(s.env ?? {}).map(([k, v]) => ({
-            name: k,
-            value: v,
-          })),
-        })) ?? []),
+        ...(agentConfig?.mcpServers?.map((s) => {
+          if ("command" in s) {
+            return {
+              name: s.name,
+              command: s.command,
+              args: s.args ?? [],
+              env: Object.entries(s.env ?? {}).map(([k, v]) => ({
+                name: k,
+                value: v,
+              })),
+            };
+          }
+          return {
+            name: s.name,
+            type: s.type,
+            url: s.url,
+            headers: Object.entries(s.headers ?? {}).map(([k, v]) => ({
+              name: k,
+              value: v,
+            })),
+          };
+        }) ?? []),
       ];
 
       // Always-on subsystem MCP servers (the "trinity"). The macro-agent
@@ -1753,63 +1772,189 @@ export function createAgentManagerV2(
     options?: {
       maxFollowUps?: number;
       onUpdate?: (update: ExtendedSessionUpdate) => void;
+      /**
+       * Optional caller-supplied completion predicate. When it returns true the
+       * loop stops consuming, terminates the agent as "completed", and returns
+       * `completedExternally: true` — WITHOUT requiring the macro `done()` tool.
+       *
+       * Checked three ways (all fire terminate + return completedExternally):
+       *   (a) reactively after each streamed update (fast path),
+       *   (b) reactively after each attempt's stream ends (fast path),
+       *   (c) on a CONCURRENT ~2s timer while consuming the stream. (c) is the
+       *       critical path for the live τ rollout: the agent runs the whole
+       *       episode in ONE prompt() call, calls τ's finish, the env writes its
+       *       reward sink (done:true), and then the prompt() stream goes SILENT
+       *       and does NOT close — the async iterator just blocks. With only the
+       *       reactive checks (a)/(b) the predicate is never re-evaluated and
+       *       solve() hangs until the rollout backstop. The concurrent poller
+       *       observes done:true independent of update arrival, flips
+       *       completedExternally, and terminate()s the agent — which ends the
+       *       in-flight prompt() generator (via return or throw, both handled).
+       *
+       * Generic by design: this module has NO knowledge of what the predicate
+       * reads (e.g. an external reward sink). Back-compat: when absent, NO poller
+       * is started and behavior is unchanged — only `done()` detection drives
+       * completion.
+       *
+       * @param pollIntervalMs Override the concurrent poll cadence (default
+       *   2000ms). Primarily a test seam.
+       */
+      isComplete?: () => boolean | Promise<boolean>;
+      pollIntervalMs?: number;
     }
   ): Promise<{
     doneCalled: boolean;
     doneStatus?: string;
+    completedExternally: boolean;
     updates: ExtendedSessionUpdate[];
   }> {
     const maxFollowUps = options?.maxFollowUps ?? 2;
+    const pollIntervalMs = options?.pollIntervalMs ?? 2000;
     const allUpdates: ExtendedSessionUpdate[] = [];
     let doneCalled = false;
     let doneStatus: string | undefined;
+    let completedExternally = false;
 
     let currentMessage = message;
 
     for (let attempt = 0; attempt <= maxFollowUps; attempt++) {
-      for await (const update of prompt(agentId, currentMessage)) {
-        allUpdates.push(update);
-        options?.onUpdate?.(update);
+      // ── Concurrent completion poller ─────────────────────────────────────
+      // Only armed when the caller supplies a predicate (back-compat: no
+      // predicate → no poller, identical behavior). The live failure mode is a
+      // prompt() stream that has gone SILENT but not CLOSED after the episode
+      // externally completed; the reactive per-update check never fires again
+      // because no updates arrive. This timer re-evaluates isComplete()
+      // independent of update arrival. On true it flips completedExternally and
+      // terminate()s the agent, which ends the in-flight prompt() generator
+      // (return or throw) so the for-await below unblocks. The interval is
+      // always cleared in `finally` so no timer leaks across attempts.
+      let pollTimer: ReturnType<typeof setInterval> | undefined;
+      let polling = false;
+
+      // Resolves the instant completion is detected (external predicate OR the
+      // macro done() tool). The attempt is RACED against this signal so it
+      // returns WITHOUT waiting for the prompt() generator to drain or for
+      // terminate() to finish. The prior design relied on terminate() ending
+      // the silent in-flight stream to unblock the for-await; when that teardown
+      // stalled (e.g. a long, busy real episode whose subprocess is slow to die),
+      // promptUntilDone never returned and the macro session stayed "running"
+      // until the multi-hour hard-timer — the refinement "finalization hang".
+      let signalDone: () => void = () => {};
+      const doneSignal = new Promise<void>((resolve) => {
+        signalDone = resolve;
+      });
 
-        // Detect done() tool call from session updates.
-        // acp-factory uses { sessionUpdate: "tool_call", title: "mcp__macro-agent__done" }
-        const uAny = update as any;
+      const startPoller = () => {
+        if (!options?.isComplete) return;
+        pollTimer = setInterval(() => {
+          if (polling || completedExternally) return;
+          polling = true;
+          void (async () => {
+            try {
+              if (!completedExternally && options.isComplete && (await options.isComplete())) {
+                completedExternally = true;
+                signalDone();
+                // Tear down the agent/session in the BACKGROUND — never await it
+                // here, so a slow teardown cannot gate the return. Tracked in
+                // pendingTerminations so close() awaits it before shutdown
+                // returns (else a still-racing group-kill is abandoned by a
+                // subsequent process.exit, orphaning the subtree). Best effort.
+                {
+                  const t = terminate(agentId, "completed" as any).catch(() => {});
+                  pendingTerminations.add(t);
+                  void t.finally(() => pendingTerminations.delete(t));
+                }
+              }
+            } catch {
+              // Predicate errored — leave completion to the reactive checks.
+            } finally {
+              polling = false;
+            }
+          })();
+        }, pollIntervalMs);
+      };
 
-        // Check title field (primary detection)
-        if (
-          (uAny.sessionUpdate === "tool_call" || uAny.sessionUpdate === "tool_call_update") &&
-          typeof uAny.title === "string" &&
-          uAny.title.endsWith("__done")
-        ) {
-          doneCalled = true;
-          // Extract status from rawInput (may arrive across multiple updates —
-          // first update has rawInput={}, subsequent has full input)
-          try {
-            const raw = uAny.rawInput;
-            const input =
-              typeof raw === "string" ? JSON.parse(raw) :
-              typeof raw === "object" ? raw :
-              uAny.input;
-            if (input?.status) {
-              doneStatus = input.status;
+      // Consume the stream as a background task so a silent-but-open generator
+      // can be raced against the completion signal below.
+      const consume = (async () => {
+        for await (const update of prompt(agentId, currentMessage)) {
+          allUpdates.push(update);
+          options?.onUpdate?.(update);
+
+          // External completion predicate (reactive fast path).
+          if (options?.isComplete && (await options.isComplete())) {
+            completedExternally = true;
+            signalDone();
+            break;
+          }
+          if (completedExternally) break;
+
+          // Detect done() tool call from session updates.
+          // acp-factory uses { sessionUpdate: "tool_call", title: "mcp__macro-agent__done" }
+          const uAny = update as any;
+
+          // Check title field (primary detection)
+          if (
+            (uAny.sessionUpdate === "tool_call" || uAny.sessionUpdate === "tool_call_update") &&
+            typeof uAny.title === "string" &&
+            uAny.title.endsWith("__done")
+          ) {
+            doneCalled = true;
+            // Extract status from rawInput (may arrive across multiple updates —
+            // first update has rawInput={}, subsequent has full input)
+            try {
+              const raw = uAny.rawInput;
+              const input =
+                typeof raw === "string" ? JSON.parse(raw) :
+                typeof raw === "object" ? raw :
+                uAny.input;
+              if (input?.status) {
+                doneStatus = input.status;
+              }
+            } catch {
+              // Best effort — rawInput may not be parseable yet
             }
-          } catch {
-            // Best effort — rawInput may not be parseable yet
+            signalDone();
           }
-        }
 
-        // Fallback: check older format
-        if (
-          uAny.type === "result" &&
-          uAny.subtype === "tool_result" &&
-          uAny.toolName === "done"
-        ) {
-          doneCalled = true;
-          doneStatus = uAny.result?.status;
+          // Fallback: check older format
+          if (
+            uAny.type === "result" &&
+            uAny.subtype === "tool_result" &&
+            uAny.toolName === "done"
+          ) {
+            doneCalled = true;
+            doneStatus = uAny.result?.status;
+            signalDone();
+          }
         }
+      })();
+      // Prevent an unhandled rejection if we return via doneSignal before the
+      // now-orphaned stream throws from a background teardown.
+      consume.catch(() => {});
+
+      try {
+        startPoller();
+        // Return as soon as EITHER the stream drains naturally OR completion is
+        // signalled — whichever comes first. This is the key change: completion
+        // no longer depends on the generator unblocking.
+        await Promise.race([consume, doneSignal]);
+      } catch (err) {
+        // A genuine stream error (not a post-completion teardown) re-throws.
+        if (!completedExternally && !doneCalled) throw err;
+      } finally {
+        // Always clear the concurrent poller so no timer leaks across attempts.
+        if (pollTimer) clearInterval(pollTimer);
+      }
+
+      // Re-check after the stream ends in case completion landed exactly as the
+      // attempt's stream drained (the inner break / poller already set the flag
+      // when it fired mid-stream).
+      if (!completedExternally && options?.isComplete && (await options.isComplete())) {
+        completedExternally = true;
       }
 
-      if (doneCalled) break;
+      if (doneCalled || completedExternally) break;
 
       if (attempt < maxFollowUps) {
         currentMessage =
@@ -1817,9 +1962,11 @@ export function createAgentManagerV2(
       }
     }
 
-    // Auto-terminate when done() was called and the handler signaled shouldTerminate.
-    // This closes the lifecycle gap: without this, agents stay in "running" state
-    // after calling done() because nothing triggers terminate().
+    // Auto-terminate when the agent completed — either via the macro done() tool
+    // or via the caller's external completion predicate. This closes the
+    // lifecycle gap: without this, agents stay in "running" state because
+    // nothing triggers terminate(). The external path mirrors the done() path
+    // (terminate as "completed").
     if (doneCalled) {
       const reason = doneStatus === "completed" ? "completed" : (doneStatus ?? "failed");
       try {
@@ -1827,9 +1974,15 @@ export function createAgentManagerV2(
       } catch {
         // Best effort — agent may already be stopping
       }
+    } else if (completedExternally) {
+      try {
+        await terminate(agentId, "completed" as any);
+      } catch {
+        // Best effort — agent may already be stopping
+      }
     }
 
-    return { doneCalled, doneStatus, updates: allUpdates };
+    return { doneCalled, doneStatus, completedExternally, updates: allUpdates };
   }
 
   function getSession(agentId: AgentId): Session | null {
@@ -1974,6 +2127,19 @@ export function createAgentManagerV2(
       });
     }
     activeSessions.clear();
+
+    // Await any in-flight fire-and-forget terminations (e.g. the completion
+    // poller's background teardown) so shutdown does not return while a
+    // group-kill is still racing — otherwise a follow-on process.exit abandons
+    // it and orphans the acp/claude/mcp_env subtree. Bounded by a backstop so a
+    // genuinely stuck close() cannot wedge shutdown.
+    if (pendingTerminations.size > 0) {
+      await Promise.race([
+        Promise.allSettled([...pendingTerminations]),
+        new Promise((resolve) => setTimeout(resolve, 6000)),
+      ]);
+    }
+
     agentWorkspaces.clear();
     lifecycleListeners.clear();
 

package/src/agent/agent-manager.ts

@@ -164,10 +164,27 @@ export interface AgentManager {
       maxFollowUps?: number;
       /** Callback for each update during prompting */
       onUpdate?: (update: ExtendedSessionUpdate) => void;
+      /**
+       * Optional caller-supplied completion predicate. When it returns true the
+       * loop stops early and terminates the agent as "completed" WITHOUT
+       * requiring the macro done() tool. Back-compat: absent → unchanged.
+       *
+       * Evaluated reactively per-update/per-attempt AND on a concurrent timer
+       * (see implementation) so a silent-but-open prompt() stream still
+       * completes. No predicate → no poller, unchanged behavior.
+       */
+      isComplete?: () => boolean | Promise<boolean>;
+      /**
+       * Override the concurrent isComplete() poll cadence in ms (default 2000).
+       * Only meaningful alongside `isComplete`; primarily a test seam.
+       */
+      pollIntervalMs?: number;
     },
   ): Promise<{
     doneCalled: boolean;
     doneStatus?: string;
+    /** True when the caller's isComplete() predicate ended the loop. */
+    completedExternally: boolean;
     updates: ExtendedSessionUpdate[];
   }>;