@g3un/pi-orchestra 0.1.0 → 0.2.0

package/src/tools/workflow.ts

@@ -1,7 +1,7 @@
 import { defineTool, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import type { AgentResultStatus, AgentRun } from "../core/subagent.ts";
-import type { OrchestraApi, WaitRunResult } from "../core/orchestra.ts";
+import type { AgentResultStatus, AgentRun, AgentRunResult } from "../core/subagent.ts";
+import type { OrchestraApi } from "../core/orchestra.ts";
 import type { AgentStore } from "../core/store.ts";
 import type { WorkflowRun, WorkflowStageOutput, WorkflowStageRun, WorkflowStageSpec } from "../core/workflow.ts";
 import { WORKGROUP_STRATEGY_VALUES, type WorkgroupMember, type WorkgroupStrategy } from "../core/workgroup.ts";
@@ -15,7 +15,6 @@ import {
   isTerminalAgentState,
   normalizeEntityName,
   requireWorkflow,
-  resolveWaitTimeoutMs,
 } from "../utils.ts";
 import {
   createWorkgroupTool,
@@ -41,17 +40,10 @@ export type WorkflowInput =
   | {
       action: "cancel";
       id: string;
-    }
-  | {
-      action: "wait";
-      id: string;
-      /** Defaults to 10 minutes. Use null to wait indefinitely. */
-      timeoutMs?: number | null;
     };
 
 export interface WorkflowOutput {
   workflow?: WorkflowRun;
-  timedOut?: boolean;
   message: string;
 }
 
@@ -65,6 +57,11 @@ export interface WorkflowToolDeps {
   store: AgentStore;
 }
 
+export interface WorkflowPiToolOptions {
+  onWorkflowInput?: (ctx: ExtensionContext, input: WorkflowInput) => void;
+  onWorkflowOutput?: (ctx: ExtensionContext, output: WorkflowOutput) => void;
+}
+
 const WorkflowStageParams = Type.Object(
   {
     name: Type.String({
@@ -87,8 +84,8 @@ const WorkflowStageParams = Type.Object(
 );
 
 const WorkflowActionParams = Type.String({
-  enum: ["start", "status", "cancel", "wait"],
-  description: "start launches; status inspects; cancel closes active runs; wait awaits terminal workflow state.",
+  enum: ["start", "status", "cancel"],
+  description: "start launches; status inspects progress or results; cancel closes active runs.",
 });
 
 const WorkflowToolParams = Type.Object(
@@ -101,7 +98,7 @@ const WorkflowToolParams = Type.Object(
     ),
     id: Type.Optional(
       Type.String({
-        description: "Required for status/cancel/wait. Workflow id/name.",
+        description: "Required for status/cancel. Workflow id/name.",
       }),
     ),
     goal: Type.Optional(
@@ -115,19 +112,6 @@ const WorkflowToolParams = Type.Object(
         minItems: 1,
       }),
     ),
-    timeoutMs: Type.Optional(
-      Type.Union(
-        [
-          Type.Number({
-            exclusiveMinimum: 0,
-          }),
-          Type.Null(),
-        ],
-        {
-          description: "Optional for action=wait. Positive ms; default 10 min; null waits indefinitely.",
-        },
-      ),
-    ),
   },
   { additionalProperties: false },
 );
@@ -156,24 +140,9 @@ export function createWorkflowTool({ orchestra, store }: WorkflowToolDeps): Work
       }
 
       const workflow = findWorkflow(store, input.id);
-      if (!workflow) {
-        return input.action === "wait"
-          ? { timedOut: false, message: formatWorkflowNotFound(input.id) }
-          : { message: formatWorkflowNotFound(input.id) };
-      }
+      if (!workflow) return { message: formatWorkflowNotFound(input.id) };
 
-      if (input.action === "status") {
-        return { workflow, message: formatWorkflowMessage(workflow) };
-      }
-
-      if (input.action === "wait") {
-        const result = await waitWorkflow(store, workflow.id, input.timeoutMs);
-        return {
-          workflow: result.workflow,
-          timedOut: result.timedOut,
-          message: formatWaitWorkflowMessage(result.workflow, result.timedOut, input.id),
-        };
-      }
+      if (input.action === "status") return { workflow, message: formatWorkflowMessage(workflow) };
 
       const closedWorkflow = await closeWorkflow(orchestra, store, workflow);
       return { workflow: closedWorkflow, message: formatWorkflowMessage(closedWorkflow, "Workflow cancelled.") };
@@ -181,24 +150,29 @@ export function createWorkflowTool({ orchestra, store }: WorkflowToolDeps): Work
   };
 }
 
-export function defineWorkflowPiTool(resolveTool: (ctx: ExtensionContext) => WorkflowTool) {
+export function defineWorkflowPiTool(
+  resolveTool: (ctx: ExtensionContext) => WorkflowTool,
+  options: WorkflowPiToolOptions = {},
+) {
   return defineTool({
     name: "workflow",
     label: "Workflow",
     description: "Run linear workgroup stages with automatic restricted stage leaders.",
-    promptSnippet: "Launch a multi-stage workflow, then use workflow wait/status for progress and final output.",
+    promptSnippet: "Launch a multi-stage workflow; completion is delivered automatically as a pi-orchestra event.",
     promptGuidelines: [
       "Use workflow for ordered multi-stage work; not branching/DAG plans.",
       "Each stage gets its own bus and automatic leader; previous outputs feed the next stage.",
       "Use compete when one worker success is enough; use synthesize when findings must be combined.",
-      "Use status for progress, wait for terminal success/blocked/failed/closed.",
+      "Use workflow status for progress; workflow.finished events deliver terminal success/blocked/failed/closed results.",
     ],
     parameters: WorkflowToolParams,
     executionMode: "sequential",
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const output = await resolveTool(ctx).execute(
-        withDefaultModels(toWorkflowInput(params as RawWorkflowParams), ctx),
-      );
+      const input = withDefaultModels(toWorkflowInput(params as RawWorkflowParams), ctx);
+      options.onWorkflowInput?.(ctx, input);
+
+      const output = await resolveTool(ctx).execute(input);
+      if (output.workflow) options.onWorkflowOutput?.(ctx, output);
 
       return {
         content: [{ type: "text", text: output.message }],
@@ -262,7 +236,13 @@ async function runStage(workflowId: string, stageIndex: number, deps: WorkflowRu
     workerRunIds: workgroupOutput.runs.map((run) => run.id),
   });
 
-  const settledWorkgroup = await settleWorkgroupRuns(deps.orchestra, bus.id, stage.strategy);
+  const settledWorkgroup = await settleWorkgroupRuns(
+    deps.orchestra,
+    deps.store,
+    bus.id,
+    workgroupOutput.runs.map((run) => run.id),
+    stage.strategy,
+  );
   if (isWorkflowClosed(deps.store, workflowId)) return;
 
   if (stage.strategy === "compete" && !settledWorkgroup.winner) {
@@ -278,7 +258,7 @@ async function runStageLeader(
   workflowId: string,
   stageIndex: number,
   busId: string,
-  workerResults: WaitRunResult[],
+  workerResults: AgentRunResult[],
   deps: WorkflowRunnerDeps,
 ): Promise<void> {
   const workflow = requireWorkflow(deps.store, workflowId);
@@ -300,10 +280,9 @@ async function runStageLeader(
     leaderRunId: leaderRun.id,
   });
 
-  const leaderSettled = await deps.orchestra.waitBusSettled(busId, { timeoutMs: null });
+  const latestLeaderRun = await terminalRunEvent(deps.store, leaderRun.id);
   if (isWorkflowClosed(deps.store, workflowId)) return;
 
-  const latestLeaderRun = leaderSettled.runs.find((run) => run.id === leaderRun.id) ?? leaderRun;
   const output = buildStageOutput(latestLeaderRun, leaderRun.id, workerResults);
   finishStage(deps.store, requireWorkflow(deps.store, workflowId), stageIndex, output);
 }
@@ -381,7 +360,6 @@ function toWorkflowInput(params: RawWorkflowParams): WorkflowInput {
   }
 
   if (!params.id) throw new Error(`workflow action=${params.action} requires id.`);
-  if (params.action === "wait") return { action: "wait", id: params.id, timeoutMs: params.timeoutMs };
   return { action: params.action, id: params.id };
 }
 
@@ -489,7 +467,7 @@ function buildStageWorkerGoal(workflow: WorkflowRun, stageIndex: number): string
   return parts.join("\n");
 }
 
-function buildLeaderTask(workflow: WorkflowRun, stageIndex: number, workerResults: WaitRunResult[]): string {
+function buildLeaderTask(workflow: WorkflowRun, stageIndex: number, workerResults: AgentRunResult[]): string {
   const stage = workflow.stages[stageIndex];
   const strategyInstructions =
     stage.strategy === "compete"
@@ -536,12 +514,12 @@ function formatPreviousStageOutput(stageName: string, output: WorkflowStageOutpu
   return [`<stage_output name="${stageName}">`, formatStageOutputForPrompt(output), "</stage_output>"].join("\n");
 }
 
-function formatWorkerResults(workerResults: WaitRunResult[]): string {
+function formatWorkerResults(workerResults: AgentRunResult[]): string {
   if (workerResults.length === 0) return "None.";
   return workerResults.map(formatWorkerResult).join("\n\n");
 }
 
-function formatWorkerResult(result: WaitRunResult): string {
+function formatWorkerResult(result: AgentRunResult): string {
   const lines = [
     `<worker_result run_id="${result.runId}" name="${result.name}" profile="${result.profile}" state="${result.state}">`,
   ];
@@ -565,7 +543,7 @@ function formatJsonData(data: unknown): string {
   return JSON.stringify(data, null, 2) ?? String(data);
 }
 
-function buildCompeteNoWinnerOutput(workerResults: WaitRunResult[]): WorkflowStageOutput {
+function buildCompeteNoWinnerOutput(workerResults: AgentRunResult[]): WorkflowStageOutput {
   const status = workerResults.some((worker) => worker.result?.status === "blocked") ? "blocked" : "failed";
   const counts = countWorkerResultStatuses(workerResults);
   const workflowRunResults = workerResults.map(toWorkflowRunResult);
@@ -577,7 +555,7 @@ function buildCompeteNoWinnerOutput(workerResults: WaitRunResult[]): WorkflowSta
   };
 }
 
-function countWorkerResultStatuses(workerResults: WaitRunResult[]): Record<AgentResultStatus, number> {
+function countWorkerResultStatuses(workerResults: AgentRunResult[]): Record<AgentResultStatus, number> {
   const counts: Record<AgentResultStatus, number> = { success: 0, blocked: 0, failed: 0 };
   for (const worker of workerResults) {
     if (worker.result) counts[worker.result.status]++;
@@ -588,7 +566,7 @@ function countWorkerResultStatuses(workerResults: WaitRunResult[]): Record<Agent
 function buildStageOutput(
   leaderRun: AgentRun,
   leaderRunId: string,
-  workerResults: WaitRunResult[],
+  workerResults: AgentRunResult[],
 ): WorkflowStageOutput {
   if (!leaderRun.result) {
     return {
@@ -609,7 +587,7 @@ function buildStageOutput(
   return output;
 }
 
-function toWorkflowRunResult(result: WaitRunResult) {
+function toWorkflowRunResult(result: AgentRunResult) {
   const output = {
     runId: result.runId,
     name: result.name,
@@ -625,46 +603,21 @@ function formatStageOutput(output: WorkflowStageOutput): string {
   return parts.join("\n");
 }
 
-function waitWorkflow(
-  store: AgentStore,
-  workflowId: string,
-  timeoutMs: number | null | undefined,
-): Promise<{ workflow: WorkflowRun; timedOut: boolean }> {
-  const resolvedTimeoutMs = resolveWaitTimeoutMs("workflow wait", timeoutMs);
-  const initialWorkflow = requireWorkflow(store, workflowId);
-  if (isTerminalAgentState(initialWorkflow.state)) {
-    return Promise.resolve({ workflow: initialWorkflow, timedOut: false });
-  }
+function terminalRunEvent(store: AgentStore, runId: string): Promise<AgentRun> {
+  const initialRun = store.getRun(runId);
+  if (initialRun && isTerminalAgentState(initialRun.state)) return Promise.resolve(initialRun);
 
   return new Promise((resolve) => {
-    let settled = false;
-    let latestWorkflow = initialWorkflow;
-    let timeout: ReturnType<typeof setTimeout> | undefined;
-
-    const cleanup = () => {
-      if (timeout) clearTimeout(timeout);
-      unsubscribe();
-    };
-
-    const unsubscribe = store.subscribeWorkflow(workflowId, (workflow) => {
-      if (settled) return;
-      latestWorkflow = workflow;
-      if (!isTerminalAgentState(workflow.state)) return;
-
-      settled = true;
-      cleanup();
-      resolve({ workflow, timedOut: false });
-    });
-
-    if (resolvedTimeoutMs !== null) {
-      timeout = setTimeout(() => {
-        if (settled) return;
-
-        settled = true;
-        cleanup();
-        resolve({ workflow: latestWorkflow, timedOut: true });
-      }, resolvedTimeoutMs);
-    }
+    let unsubscribe: () => void = () => undefined;
+    unsubscribe = store.subscribeRuns(
+      (run) => {
+        if (!isTerminalAgentState(run.state)) return;
+
+        unsubscribe();
+        resolve(run);
+      },
+      (run) => run.id === runId,
+    );
   });
 }
 
@@ -672,14 +625,6 @@ function formatWorkflowNotFound(id: string): string {
   return `Workflow ${id} not found.`;
 }
 
-function formatWaitWorkflowMessage(workflow: WorkflowRun | undefined, timedOut: boolean, requestedId?: string): string {
-  if (!workflow) return formatWorkflowNotFound(requestedId ?? "");
-  const label = requestedId === workflow.id ? workflow.id : formatNamedEntityLabel(workflow);
-  const prefix = timedOut ? "Timed out waiting for" : "Workflow reached terminal state:";
-  const result = workflow.result ? ` result=${workflow.result.status}` : "";
-  return `${prefix} ${label}; state=${workflow.state}${result}.`;
-}
-
 function formatWorkflowMessage(
   workflow: WorkflowRun,
   headline = `Workflow ${formatNamedEntityLabel(workflow)} is ${workflow.state}.`,
@@ -695,12 +640,11 @@ function formatWorkflowMessage(
 }
 
 type RawWorkflowParams = {
-  action: "start" | "status" | "cancel" | "wait";
+  action: "start" | "status" | "cancel";
   name?: string;
   id?: string;
   goal?: string;
   stages?: RawWorkflowStageParams[];
-  timeoutMs?: number | null;
 };
 
 type RawWorkflowStageParams = {

package/src/tools/workgroup.ts

@@ -1,11 +1,19 @@
 import { defineTool, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import type { AgentProfile, AgentRun } from "../core/subagent.ts";
+import type { AgentProfile, AgentResultStatus, AgentRun, AgentRunResult } from "../core/subagent.ts";
 import type { Bus } from "../core/bus.ts";
-import type { AgentResultStatus } from "../core/subagent.ts";
-import type { OrchestraApi, WaitRunResult } from "../core/orchestra.ts";
+import type { OrchestraApi } from "../core/orchestra.ts";
+import type { AgentStore } from "../core/store.ts";
 import { WORKGROUP_STRATEGY_VALUES, type WorkgroupMember, type WorkgroupStrategy } from "../core/workgroup.ts";
-import { closeAgentRuns, formatError, formatNamedEntityLabel, normalizeEntityName, slugify } from "../utils.ts";
+import {
+  closeAgentRuns,
+  formatError,
+  formatNamedEntityLabel,
+  isTerminalAgentState,
+  normalizeEntityName,
+  slugify,
+  toAgentRunResult,
+} from "../utils.ts";
 import {
   AgentProfileParams,
   spawnSubagent,
@@ -33,10 +41,10 @@ export interface WorkgroupSettlement {
   strategy: WorkgroupStrategy;
   status: AgentResultStatus;
   /** Results that should be consumed by downstream orchestration. For compete, this is the winning result when present. */
-  workerResults: WaitRunResult[];
+  workerResults: AgentRunResult[];
   /** Every terminal result observed while settling this workgroup. */
-  completedResults: WaitRunResult[];
-  winner?: WaitRunResult;
+  completedResults: AgentRunResult[];
+  winner?: AgentRunResult;
   pendingRunIds: string[];
 }
 
@@ -45,8 +53,25 @@ export interface WorkgroupTool {
   execute(input: WorkgroupInput): Promise<WorkgroupOutput>;
 }
 
+export interface WorkgroupLaunchEvent {
+  input: WorkgroupInput;
+  bus: Bus;
+}
+
+export interface WorkgroupLaunchedEvent {
+  input: WorkgroupInput;
+  output: WorkgroupOutput;
+}
+
+export interface WorkgroupLaunchFailedEvent extends WorkgroupLaunchEvent {
+  error: unknown;
+}
+
 export interface WorkgroupToolDeps {
   orchestra: OrchestraApi;
+  onWorkgroupLaunching?: (event: WorkgroupLaunchEvent) => void;
+  onWorkgroupLaunched?: (event: WorkgroupLaunchedEvent) => void;
+  onWorkgroupLaunchFailed?: (event: WorkgroupLaunchFailedEvent) => void;
 }
 
 export const WorkgroupMemberParams = Type.Object(
@@ -100,7 +125,12 @@ interface SpawnFailure {
   error: unknown;
 }
 
-export function createWorkgroupTool({ orchestra }: WorkgroupToolDeps): WorkgroupTool {
+export function createWorkgroupTool({
+  orchestra,
+  onWorkgroupLaunching,
+  onWorkgroupLaunched,
+  onWorkgroupLaunchFailed,
+}: WorkgroupToolDeps): WorkgroupTool {
   return {
     name: "workgroup",
 
@@ -110,51 +140,52 @@ export function createWorkgroupTool({ orchestra }: WorkgroupToolDeps): Workgroup
       const bus = orchestra.getBus(input.busId);
       if (!bus) throw new Error(`Bus ${input.busId} not found.`);
 
-      const preparedInput: PreparedWorkgroupInput = {
-        ...input,
-        members: prepareMembers(input.members, orchestra.listRuns()),
-      };
-      const spawnResults = await Promise.allSettled(
-        preparedInput.members.map(async (member): Promise<SpawnSuccess> => {
-          const run = await spawnSubagent(orchestra, toSubagentSpawnInput(preparedInput, member, bus.id));
-          return { member, run };
-        }),
-      );
-
-      const successes = collectSpawnSuccesses(spawnResults);
-      const failures = collectSpawnFailures(preparedInput.members, spawnResults);
-      if (failures.length > 0) {
-        const cleanupResults = await Promise.allSettled(
-          successes.map((success) => orchestra.closeAgent(success.run.id)),
+      onWorkgroupLaunching?.({ input, bus });
+      try {
+        const preparedInput: PreparedWorkgroupInput = {
+          ...input,
+          members: prepareMembers(input.members, orchestra.listRuns()),
+        };
+        const spawnResults = await Promise.allSettled(
+          preparedInput.members.map(async (member): Promise<SpawnSuccess> => {
+            const run = await spawnSubagent(orchestra, toSubagentSpawnInput(preparedInput, member, bus.id));
+            return { member, run };
+          }),
         );
-        throw new Error(formatLaunchFailure(failures, successes, cleanupResults));
-      }
 
-      const runs = successes.map((success) => success.run);
-      return {
-        bus,
-        runs,
-        message: formatWorkgroupMessage(bus, preparedInput, runs),
-      };
+        const successes = collectSpawnSuccesses(spawnResults);
+        const failures = collectSpawnFailures(preparedInput.members, spawnResults);
+        if (failures.length > 0) {
+          const cleanupResults = await Promise.allSettled(
+            successes.map((success) => orchestra.closeAgent(success.run.id)),
+          );
+          throw new Error(formatLaunchFailure(failures, successes, cleanupResults));
+        }
+
+        const runs = successes.map((success) => success.run);
+        const output = {
+          bus,
+          runs,
+          message: formatWorkgroupMessage(bus, preparedInput, runs),
+        };
+        onWorkgroupLaunched?.({ input, output });
+        return output;
+      } catch (error) {
+        onWorkgroupLaunchFailed?.({ input, bus, error });
+        throw error;
+      }
     },
   };
 }
 
 export async function settleWorkgroupRuns(
   orchestra: OrchestraApi,
+  store: AgentStore,
   busId: string,
+  runIds: string[],
   strategy: WorkgroupStrategy,
 ): Promise<WorkgroupSettlement> {
-  if (strategy === "compete") return await settleCompeteWorkgroupRuns(orchestra, busId);
-
-  const settled = await orchestra.waitBusSettled(busId, { timeoutMs: null });
-  return {
-    strategy,
-    status: resolveWorkgroupStatus(settled.runResults),
-    workerResults: settled.runResults,
-    completedResults: settled.runResults,
-    pendingRunIds: settled.pendingRunIds,
-  };
+  return await new WorkgroupSettlementCollector(orchestra, store, busId, runIds, strategy).settle();
 }
 
 export function defineWorkgroupPiTool(resolveTool: (ctx: ExtensionContext) => WorkgroupTool) {
@@ -162,11 +193,11 @@ export function defineWorkgroupPiTool(resolveTool: (ctx: ExtensionContext) => Wo
     name: "workgroup",
     label: "Workgroup",
     description: "Spawn multiple subagents onto an existing bus; you lead and collect results.",
-    promptSnippet: "Spawn a main-led workgroup on an existing bus, then collect results with bus wait actions.",
+    promptSnippet: "Spawn a main-led workgroup on an existing bus; member finish events are delivered automatically.",
     promptGuidelines: [
       "Create a bus first; workgroup only spawns members.",
-      "Use compete when one successful member is enough; use wait_next, then close losers and summarize.",
-      "Use synthesize when members provide complementary findings to combine; wait_settled usually fits.",
+      "Use workgroup compete when one successful member is enough; close losers after a success event if appropriate.",
+      "Use workgroup synthesize when members provide complementary findings; react to member finish events as they arrive.",
       "publish_bus is peer-reference context, not a leader-request channel.",
     ],
     parameters: WorkgroupToolParams,
@@ -183,39 +214,123 @@ export function defineWorkgroupPiTool(resolveTool: (ctx: ExtensionContext) => Wo
   });
 }
 
-async function settleCompeteWorkgroupRuns(orchestra: OrchestraApi, busId: string): Promise<WorkgroupSettlement> {
-  const completedResults: WaitRunResult[] = [];
-  const excludeRunIds: string[] = [];
+class WorkgroupSettlementCollector {
+  private readonly runIds: Set<string>;
+  private readonly completedRunIds = new Set<string>();
+  private readonly completedResults: AgentRunResult[] = [];
+
+  constructor(
+    private readonly orchestra: OrchestraApi,
+    private readonly store: AgentStore,
+    private readonly busId: string,
+    runIds: string[],
+    private readonly strategy: WorkgroupStrategy,
+  ) {
+    this.runIds = new Set(runIds);
+  }
 
-  for (;;) {
-    const nextRun = await orchestra.waitNextRun(busId, { excludeRunIds, timeoutMs: null });
-    if (!nextRun.runResult) {
-      return {
-        strategy: "compete",
-        status: resolveWorkgroupStatus(completedResults),
-        workerResults: completedResults,
-        completedResults,
-        pendingRunIds: nextRun.pendingRunIds,
+  settle(): Promise<WorkgroupSettlement> {
+    return new Promise((resolve) => {
+      let settled = false;
+      let unsubscribe: () => void = () => undefined;
+
+      const finish = (settlement: WorkgroupSettlement) => {
+        if (settled) return;
+
+        settled = true;
+        unsubscribe();
+        resolve(settlement);
       };
-    }
 
-    completedResults.push(nextRun.runResult);
-    excludeRunIds.push(nextRun.runResult.runId);
-    if (nextRun.runResult.result?.status === "success") {
-      await closeAgentRuns(orchestra, nextRun.pendingRunIds);
-      return {
-        strategy: "compete",
-        status: "success",
-        workerResults: [nextRun.runResult],
-        completedResults,
-        winner: nextRun.runResult,
-        pendingRunIds: [],
+      const finishWithWinner = (winner: AgentRunResult) => {
+        if (settled) return;
+
+        settled = true;
+        unsubscribe();
+        void closeAgentRuns(this.orchestra, this.getPendingRunIds()).finally(() => {
+          resolve({
+            strategy: this.strategy,
+            status: "success",
+            workerResults: [winner],
+            completedResults: this.completedResults,
+            winner,
+            pendingRunIds: [],
+          });
+        });
+      };
+
+      const finishFromCurrentState = () => {
+        this.captureTerminalRuns();
+
+        const winner = this.strategy === "compete" ? this.completedResults.find(isSuccessfulRunResult) : undefined;
+        if (winner) {
+          finishWithWinner(winner);
+          return;
+        }
+
+        if (!this.isSettled()) return;
+
+        finish({
+          strategy: this.strategy,
+          status: resolveWorkgroupStatus(this.completedResults),
+          workerResults: this.completedResults,
+          completedResults: this.completedResults,
+          pendingRunIds: this.getPendingRunIds(),
+        });
       };
+
+      const observeRun = (run: AgentRun) => {
+        if (settled || !this.runIds.has(run.id) || !isTerminalAgentState(run.state)) return;
+        this.recordTerminalRun(run);
+        finishFromCurrentState();
+      };
+
+      unsubscribe = this.store.subscribeRuns(observeRun, (run) => run.busId === this.busId && this.runIds.has(run.id));
+      finishFromCurrentState();
+
+      if (!settled && this.runIds.size === 0) {
+        finish({
+          strategy: this.strategy,
+          status: "failed",
+          workerResults: [],
+          completedResults: [],
+          pendingRunIds: [],
+        });
+      }
+    });
+  }
+
+  private captureTerminalRuns(): void {
+    for (const runId of this.runIds) {
+      const run = this.store.getRun(runId);
+      if (run) this.recordTerminalRun(run);
     }
   }
+
+  private recordTerminalRun(run: AgentRun): void {
+    if (!isTerminalAgentState(run.state) || this.completedRunIds.has(run.id)) return;
+
+    this.completedRunIds.add(run.id);
+    this.completedResults.push(toAgentRunResult(run));
+  }
+
+  private isSettled(): boolean {
+    return [...this.runIds].every((runId) => {
+      const run = this.store.getRun(runId);
+      return run !== undefined && isTerminalAgentState(run.state);
+    });
+  }
+
+  private getPendingRunIds(): string[] {
+    return [...this.runIds].filter((runId) => this.store.getRun(runId)?.state === "idle");
+  }
+}
+
+function isSuccessfulRunResult(result: AgentRunResult): boolean {
+  return result.result?.status === "success";
 }
 
-function resolveWorkgroupStatus(results: WaitRunResult[]): AgentResultStatus {
+function resolveWorkgroupStatus(results: AgentRunResult[]): AgentResultStatus {
   const statuses = results.map((result) => result.result?.status);
   if (statuses.includes("success")) return "success";
   if (statuses.includes("blocked")) return "blocked";
@@ -404,7 +519,7 @@ function formatWorkgroupMessage(bus: Bus, input: PreparedWorkgroupInput, runs: A
     "Runs:",
     ...runs.map((run) => `- ${formatNamedEntityLabel(run)}: ${run.state}`),
     "",
-    "Use bus action=wait_next to handle member results as they finish, or bus action=wait_settled for full fan-in.",
+    "Pi-orchestra will deliver workgroup.member_finished events as members finish.",
   ].join("\n");
 }