@xzzpig/pi-subagents 0.14.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (198) hide show
  1. package/CHANGELOG.md +233 -0
  2. package/README.md +6 -5
  3. package/agents/evidence-auditor.md +34 -0
  4. package/agents/researcher.md +23 -13
  5. package/agents/reviewer.md +3 -2
  6. package/docs/agents.md +56 -15
  7. package/docs/configuration.md +92 -14
  8. package/docs/extension-api.md +132 -19
  9. package/docs/missions.md +10 -2
  10. package/docs/models.md +11 -22
  11. package/docs/observability.md +63 -11
  12. package/docs/standalone-background.md +59 -0
  13. package/docs/tool-reference.md +42 -23
  14. package/docs/watchdog.md +39 -10
  15. package/docs/workflows.md +58 -19
  16. package/index.ts +5 -2
  17. package/inspector-runner.mjs +2 -2
  18. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +13 -3
  19. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +18 -6
  20. package/node_modules/@xzzpig/pi-components/src/transcript.ts +26 -6
  21. package/package.json +9 -4
  22. package/prompts/parallel-review.md +1 -1
  23. package/runner-peer-loader.mjs +24 -0
  24. package/runner-peer-preload.mjs +36 -0
  25. package/skills/pi-subagents/SKILL.md +34 -22
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  27. package/skills/pi-subagents/references/execution-controls.md +27 -8
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
  31. package/skills/pi-subagents/references/review-and-validation.md +3 -3
  32. package/src/agents/advertised-agent-prompt.ts +94 -0
  33. package/src/agents/agent-management.ts +71 -59
  34. package/src/agents/agent-serializer.ts +6 -3
  35. package/src/agents/agents.ts +198 -72
  36. package/src/agents/builtin-names.ts +1 -0
  37. package/src/agents/chain-serializer.ts +5 -0
  38. package/src/agents/runtime-agent-registry.ts +7 -6
  39. package/src/api/delegation.ts +4 -0
  40. package/src/api/preflight.ts +110 -71
  41. package/src/api/required-child-extensions.ts +6 -0
  42. package/src/api/shared-types.ts +3 -1
  43. package/src/api/workflow-resources.ts +6 -0
  44. package/src/extension/config.ts +14 -37
  45. package/src/extension/fanout-child.ts +68 -5
  46. package/src/extension/herdr-pi-bridge.ts +164 -0
  47. package/src/extension/index.ts +141 -51
  48. package/src/extension/public-execution.ts +7 -6
  49. package/src/extension/rpc.ts +8 -21
  50. package/src/extension/schemas.ts +86 -84
  51. package/src/extension/tool-description.ts +32 -79
  52. package/src/inspectors/actions.ts +148 -0
  53. package/src/inspectors/ghostty/actions.ts +74 -0
  54. package/src/inspectors/ghostty/plugin.ts +17 -0
  55. package/src/inspectors/herdr/actions.ts +99 -179
  56. package/src/inspectors/herdr/plugin.ts +20 -0
  57. package/src/inspectors/herdr/project-panes.ts +4 -1
  58. package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
  59. package/src/inspectors/plugins.ts +8 -0
  60. package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
  61. package/src/inspectors/types.ts +51 -0
  62. package/src/integrations/pi-web-session-liveness.ts +73 -0
  63. package/src/intercom/intercom-bridge.ts +50 -8
  64. package/src/intercom/native-supervisor-channel.ts +142 -115
  65. package/src/intercom/supervisor-ui.ts +3 -2
  66. package/src/missions/workflow-state.ts +37 -16
  67. package/src/policy/authority.ts +4 -0
  68. package/src/profiles/profiles.ts +12 -6
  69. package/src/runs/background/active-async-capacity.ts +22 -18
  70. package/src/runs/background/active-run-index.ts +17 -1
  71. package/src/runs/background/async-execution.ts +359 -176
  72. package/src/runs/background/async-job-tracker.ts +41 -7
  73. package/src/runs/background/async-resume.ts +19 -12
  74. package/src/runs/background/async-retention.ts +20 -0
  75. package/src/runs/background/async-status-snapshot.ts +10 -12
  76. package/src/runs/background/async-status.ts +32 -13
  77. package/src/runs/background/auto-drain.ts +59 -35
  78. package/src/runs/background/binary-bootstrap.ts +38 -0
  79. package/src/runs/background/chain-append.ts +1 -1
  80. package/src/runs/background/chain-root-attachment.ts +22 -33
  81. package/src/runs/background/control-channel.ts +78 -44
  82. package/src/runs/background/fleet-view.ts +30 -2
  83. package/src/runs/background/notify.ts +193 -19
  84. package/src/runs/background/owned-process-tree.ts +35 -8
  85. package/src/runs/background/process-terminal.ts +23 -23
  86. package/src/runs/background/result-files.ts +8 -4
  87. package/src/runs/background/result-watcher.ts +19 -2
  88. package/src/runs/background/retained-nested-route-tracker.ts +96 -0
  89. package/src/runs/background/run-child-session.ts +118 -41
  90. package/src/runs/background/run-status.ts +78 -5
  91. package/src/runs/background/runner-aliases.ts +22 -5
  92. package/src/runs/background/runner-child-launch.ts +93 -0
  93. package/src/runs/background/runner-child-sessions.ts +5 -4
  94. package/src/runs/background/runner-http-dispatcher.ts +119 -0
  95. package/src/runs/background/scheduled-runs.ts +51 -18
  96. package/src/runs/background/stale-run-reconciler.ts +38 -12
  97. package/src/runs/background/steering.ts +20 -2
  98. package/src/runs/background/subagent-runner.ts +766 -432
  99. package/src/runs/background/subagent-wait.ts +179 -28
  100. package/src/runs/background/wait-completions.ts +79 -27
  101. package/src/runs/background/wait-subscriptions.ts +9 -3
  102. package/src/runs/background/wait-tool.ts +5 -3
  103. package/src/runs/foreground/async-steering-action.ts +37 -7
  104. package/src/runs/foreground/async-stop-action.ts +93 -3
  105. package/src/runs/foreground/execution.ts +174 -194
  106. package/src/runs/foreground/foreground-history.ts +5 -2
  107. package/src/runs/foreground/prompt-audit.ts +12 -6
  108. package/src/runs/foreground/subagent-executor.ts +896 -397
  109. package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
  110. package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
  111. package/src/runs/shared/acceptance.ts +54 -14
  112. package/src/runs/shared/agent-contract.ts +1 -1
  113. package/src/runs/shared/async-status-projection.ts +172 -78
  114. package/src/runs/shared/capability-ceiling.ts +2 -0
  115. package/src/runs/shared/child-hooks.ts +167 -3
  116. package/src/runs/shared/child-launch-plan.ts +15 -3
  117. package/src/runs/shared/child-launch.ts +44 -16
  118. package/src/runs/shared/child-lifecycle.ts +6 -3
  119. package/src/runs/shared/child-runtime-config.ts +8 -1
  120. package/src/runs/shared/child-session.ts +130 -24
  121. package/src/runs/shared/child-tool-plan.ts +145 -14
  122. package/src/runs/shared/completion-evidence.ts +2 -2
  123. package/src/runs/shared/completion-guard.ts +6 -3
  124. package/src/runs/shared/dynamic-fanout.ts +2 -2
  125. package/src/runs/shared/effective-system-prompt.ts +33 -0
  126. package/src/runs/shared/external-cli-contract.ts +11 -1
  127. package/src/runs/shared/external-cli-preflight.ts +6 -2
  128. package/src/runs/shared/external-cli-runner.ts +9 -7
  129. package/src/runs/shared/herdr-connection.ts +134 -0
  130. package/src/runs/shared/herdr-external-adapters.ts +169 -0
  131. package/src/runs/shared/herdr-machine.ts +279 -0
  132. package/src/runs/shared/herdr-pi-protocol.ts +59 -0
  133. package/src/runs/shared/herdr-placed-run.ts +263 -0
  134. package/src/runs/shared/host-step-status.ts +11 -11
  135. package/src/runs/shared/llm-intent-arbiter.ts +40 -21
  136. package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
  137. package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
  138. package/src/runs/shared/model-scope.ts +1 -1
  139. package/src/runs/shared/nested-events.ts +19 -10
  140. package/src/runs/shared/orca-progress-tabs.ts +7 -1
  141. package/src/runs/shared/parallel-handoff.ts +57 -12
  142. package/src/runs/shared/parallel-utils.ts +10 -4
  143. package/src/runs/shared/pi-spawn.ts +10 -0
  144. package/src/runs/shared/readonly-drain-observation.ts +42 -0
  145. package/src/runs/shared/run-fanout-budget.ts +8 -8
  146. package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
  147. package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
  148. package/src/runs/shared/task-intent.ts +46 -13
  149. package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
  150. package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
  151. package/src/runs/shared/worktree-setup-command.ts +213 -0
  152. package/src/runs/shared/worktree.ts +437 -214
  153. package/src/shared/child-cache-retention.ts +43 -0
  154. package/src/shared/fork-context.ts +15 -72
  155. package/src/shared/launch-contract.ts +70 -8
  156. package/src/shared/model-response-aliases.ts +13 -0
  157. package/src/shared/opencode-session-headers.ts +30 -0
  158. package/src/shared/pruned-fork.ts +1 -1
  159. package/src/shared/required-child-extensions.ts +81 -0
  160. package/src/shared/settings.ts +5 -2
  161. package/src/shared/shortcuts.ts +0 -4
  162. package/src/shared/types.ts +163 -90
  163. package/src/shared/utils.ts +10 -2
  164. package/src/shared/watch-strategy.ts +2 -0
  165. package/src/shared/workflow-child-permit.ts +18 -13
  166. package/src/slash/delegation-adapters.ts +3 -1
  167. package/src/slash/delegation-request.ts +14 -0
  168. package/src/slash/slash-commands.ts +2 -7
  169. package/src/slash/subagents-admin.ts +31 -14
  170. package/src/tui/fleet-status.ts +165 -20
  171. package/src/tui/fleet.ts +30 -19
  172. package/src/tui/render.ts +210 -50
  173. package/src/watchdog/child-status.ts +28 -28
  174. package/src/watchdog/lsp-diagnostics.ts +1 -1
  175. package/src/watchdog/model-selection.ts +21 -1
  176. package/src/watchdog/permission-arbiter.ts +5 -2
  177. package/src/watchdog/register-child.ts +10 -2
  178. package/src/watchdog/register-main.ts +39 -35
  179. package/src/watchdog/render.ts +1 -1
  180. package/src/watchdog/review.ts +122 -74
  181. package/src/watchdog/rules.ts +1 -1
  182. package/src/watchdog/runtime.ts +100 -27
  183. package/src/watchdog/scope.ts +1 -1
  184. package/src/watchdog/settings.ts +3 -0
  185. package/src/watchdog/tool-actions.ts +13 -12
  186. package/src/watchdog/turn-delta.ts +23 -0
  187. package/src/watchdog/types.ts +5 -3
  188. package/src/watchdog/warning-format.ts +1 -1
  189. package/src/workflows/chat-progress.ts +3 -3
  190. package/src/workflows/scripted-workflow.ts +349 -26
  191. package/src/workflows/workflow-checklist.ts +17 -20
  192. package/src/workflows/workflow-child-summary.ts +57 -8
  193. package/src/workflows/workflow-preflight.ts +19 -19
  194. package/src/workflows/workflow-receipt.ts +24 -6
  195. package/src/workflows/workflow-resources.ts +108 -22
  196. package/src/workflows/workflow-settlement.ts +3 -0
  197. package/src/runs/shared/model-exclusions.ts +0 -373
  198. /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
@@ -39,6 +39,7 @@
39
39
  */
40
40
 
41
41
  import * as fs from "node:fs";
42
+ import * as path from "node:path";
42
43
  import type { AgentToolResult } from "@earendil-works/pi-agent-core";
43
44
  import {
44
45
  listBackgroundWorkWakeChannels,
@@ -61,6 +62,7 @@ import {
61
62
  type Usage,
62
63
  type WaitCompletion,
63
64
  } from "../../shared/types.ts";
65
+ import { nestedRunScope } from "../shared/nested-events.ts";
64
66
  import { formatDuration, shortenPath } from "../../shared/formatters.ts";
65
67
  import { toAgentToolUsage } from "../../shared/utils.ts";
66
68
  import { collectWaitCompletions } from "./wait-completions.ts";
@@ -103,6 +105,8 @@ export interface SubagentWaitDeps {
103
105
  onUpdate?: (result: AgentToolResult<Details>) => void;
104
106
  asyncDirRoot?: string;
105
107
  resultsDir?: string;
108
+ /** Root from the child's validated inherited route, not a tool argument. */
109
+ nestedRootRunId?: string;
106
110
  kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
107
111
  now?: () => number;
108
112
  pollIntervalMs?: number;
@@ -118,6 +122,8 @@ export interface SubagentWaitDeps {
118
122
  failOnFailedRuns?: boolean;
119
123
  /** Internal auto-drain mode surfaces actionable attention as an error. */
120
124
  failOnAttention?: boolean;
125
+ /** Durable owned supervisor-request barrier used by headless auto-drain. */
126
+ hasPendingSupervisorRequest?: () => boolean;
121
127
  /** Arm a durable exact-target wait subscription in a long-lived interactive runtime. */
122
128
  subscribe?: (input: { targetKind: "async" | "foreground"; runId: string; requestedId: string; timeoutMs: number }) => { token: string; expiresAt: number };
123
129
  /** Injectable provider protocol surfaces for deterministic tests. */
@@ -214,14 +220,13 @@ function matchesId(run: AsyncRunSummary, id: string): boolean {
214
220
  }
215
221
 
216
222
  function activeDetachedForegroundRuns(params: SubagentWaitParams, deps: SubagentWaitDeps): ForegroundResumeRun[] {
217
- if (!params.id || !deps.state.foregroundRuns) return [];
218
223
  const sessionId = deps.state.currentSessionId;
219
- if (!sessionId) return [];
220
- return [...deps.state.foregroundRuns.values()].filter((run) =>
221
- (run.runId === params.id || run.runId.startsWith(params.id!))
222
- && run.sessionId === sessionId
223
- && run.children.some((child) => child.status === "detached")
224
+ if (!sessionId || !deps.state.foregroundRuns) return [];
225
+ const runs = [...deps.state.foregroundRuns.values()].filter((run) =>
226
+ run.sessionId === sessionId && run.children.some((child) => child.status === "detached")
224
227
  );
228
+ if (params.id) return runs.filter((run) => run.runId === params.id || run.runId.startsWith(params.id!));
229
+ return params.all === true ? runs : [];
225
230
  }
226
231
 
227
232
  function summarizeForegroundChildren(run: ForegroundResumeRun, indices: Set<number>): string {
@@ -265,22 +270,39 @@ function backgroundWorkForSession(deps: SubagentWaitDeps, nowMs: number): Backgr
265
270
  return deps.backgroundWork?.snapshot(sessionId, nowMs) ?? snapshotBackgroundWork(sessionId, nowMs);
266
271
  }
267
272
 
268
- /** Queued/running runs from this session, including runs that need attention. */
269
- function activeRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps): AsyncRunSummary[] {
270
- const asyncDirRoot = deps.asyncDirRoot ?? DIRS.async;
271
- const resultsDir = deps.resultsDir ?? DIRS.results;
272
- const runs = listAsyncRuns(asyncDirRoot, {
273
- states: [...ACTIVE_STATES],
273
+ export function waitRunScopes(deps: Pick<SubagentWaitDeps, "asyncDirRoot" | "resultsDir" | "nestedRootRunId">): Array<{ asyncDirRoot: string; resultsDir: string }> {
274
+ return [
275
+ { asyncDirRoot: deps.asyncDirRoot ?? DIRS.async, resultsDir: deps.resultsDir ?? DIRS.results },
276
+ ...(deps.nestedRootRunId ? [nestedRunScope(deps.nestedRootRunId)] : []),
277
+ ];
278
+ }
279
+
280
+ function collectScopedCompletions(terminal: AsyncRunSummary[], deps: SubagentWaitDeps, references: string[]): WaitCompletion[] | undefined {
281
+ const completions = waitRunScopes(deps).flatMap((scope) => collectWaitCompletions(
282
+ terminal.filter((run) => path.resolve(path.dirname(run.asyncDir)) === path.resolve(scope.asyncDirRoot)),
283
+ deps.state, scope.resultsDir, (reference) => references.push(reference),
284
+ ) ?? []);
285
+ return completions.length ? completions : undefined;
286
+ }
287
+
288
+ /** Immediate-session runs only; named lookups can also recover already-terminal results. */
289
+ function runsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps, activeOnly = true): AsyncRunSummary[] {
290
+ const runs = waitRunScopes(deps).flatMap(({ asyncDirRoot, resultsDir }) => listAsyncRuns(asyncDirRoot, {
291
+ states: activeOnly ? [...ACTIVE_STATES] : undefined,
274
292
  sessionId: deps.state.currentSessionId ?? undefined,
275
293
  resultsDir,
276
294
  kill: deps.kill,
277
295
  now: deps.now,
278
296
  includeNested: false,
279
297
  ...(params.id ? { runId: params.id } : {}),
280
- });
298
+ }));
281
299
  return params.id ? runs.filter((run) => matchesId(run, params.id!)) : runs;
282
300
  }
283
301
 
302
+ function activeRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps): AsyncRunSummary[] {
303
+ return runsForSession(params, deps);
304
+ }
305
+
284
306
  /** Runs (from the initial set) currently flagged needs_attention, for reporting. */
285
307
  function attentionRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps, initialIds: Set<string>): AsyncRunSummary[] {
286
308
  return activeRunsForSession(params, deps).filter((run) => needsAttention(run) && initialIds.has(run.id));
@@ -288,9 +310,7 @@ function attentionRunsForSession(params: SubagentWaitParams, deps: SubagentWaitD
288
310
 
289
311
  /** Exact initial runs in any state, for the final summary. */
290
312
  function runsForIds(runIds: Iterable<string>, deps: SubagentWaitDeps): AsyncRunSummary[] {
291
- const asyncDirRoot = deps.asyncDirRoot ?? DIRS.async;
292
- const resultsDir = deps.resultsDir ?? DIRS.results;
293
- return [...runIds].flatMap((runId) => listAsyncRuns(asyncDirRoot, {
313
+ return waitRunScopes(deps).flatMap(({ asyncDirRoot, resultsDir }) => [...runIds].flatMap((runId) => listAsyncRuns(asyncDirRoot, {
294
314
  sessionId: deps.state.currentSessionId ?? undefined,
295
315
  resultsDir,
296
316
  kill: deps.kill,
@@ -298,7 +318,7 @@ function runsForIds(runIds: Iterable<string>, deps: SubagentWaitDeps): AsyncRunS
298
318
  includeNested: false,
299
319
  runId,
300
320
  exactRunId: true,
301
- }));
321
+ })));
302
322
  }
303
323
 
304
324
  function summarizeTerminalRuns(runs: AsyncRunSummary[], providerFinishedCount = 0): string {
@@ -337,6 +357,9 @@ function completionUsage(completions: WaitCompletion[] | undefined): Usage | und
337
357
 
338
358
  function result(text: string, isError = false, completions?: WaitCompletion[]): AgentToolResult<Details> {
339
359
  const usage = completionUsage(completions);
360
+ for (const completion of completions ?? []) {
361
+ if (completion.workflowReceiptPath) text += `\nWorkflow receipt [${completion.runId}]: ${completion.workflowReceiptPath}`;
362
+ }
340
363
  return {
341
364
  content: [{ type: "text", text }],
342
365
  ...(isError ? { isError: true } : {}),
@@ -375,6 +398,49 @@ function windowElapsedResult(
375
398
  };
376
399
  }
377
400
 
401
+ function supervisorYieldResult(
402
+ activeRunIds: string[],
403
+ activeProviderItems: readonly RegisteredBackgroundWorkItem[] = [],
404
+ ): AgentToolResult<Details> {
405
+ return {
406
+ content: [{ type: "text", text: "Wait yielded for a pending supervisor request. Background work remains active and will continue after the supervisor reply." }],
407
+ details: {
408
+ mode: "management",
409
+ results: [],
410
+ wait: {
411
+ reason: "supervisor_request",
412
+ timedOut: false,
413
+ activeRunIds,
414
+ activeProviderItems: activeProviderItems.map(({ provider, id }) => ({ provider, id })),
415
+ },
416
+ },
417
+ };
418
+ }
419
+
420
+ interface InitialWaitScope {
421
+ asyncRunIds: Set<string>;
422
+ foregroundRuns: Array<{ runId: string; sessionId?: string; detachedIndices: Set<number> }>;
423
+ providerIds: Set<string>;
424
+ }
425
+
426
+ function supervisorYieldForScope(scope: InitialWaitScope, params: SubagentWaitParams, deps: SubagentWaitDeps, nowMs: number): AgentToolResult<Details> {
427
+ try {
428
+ const activeAsyncIds = new Set(activeRunsForSession(params.id ? { id: params.id } : {}, deps).map((run) => run.id));
429
+ const activeRunIds = new Set([...scope.asyncRunIds].filter((id) => activeAsyncIds.has(id)));
430
+ for (const initial of scope.foregroundRuns) {
431
+ const current = deps.state.foregroundRuns?.get(initial.runId);
432
+ if (!current || current.sessionId !== initial.sessionId) continue;
433
+ if (current.children.some((child) => initial.detachedIndices.has(child.index) && child.status === "detached")) activeRunIds.add(initial.runId);
434
+ }
435
+ const activeProviderItems = scope.providerIds.size > 0
436
+ ? backgroundWorkForSession(deps, nowMs).items.filter((item) => scope.providerIds.has(backgroundWorkIdentity(item)))
437
+ : [];
438
+ return supervisorYieldResult([...activeRunIds], activeProviderItems);
439
+ } catch (error) {
440
+ return result(error instanceof Error ? error.message : String(error), true);
441
+ }
442
+ }
443
+
378
444
  /** Build the live status shown while async work keeps bg_wait blocked. */
379
445
  function asyncWaitUpdate(runs: AsyncRunSummary[], providerCount: number, elapsedMs: number): AgentToolResult<Details> {
380
446
  const activity = runs.flatMap((run) => {
@@ -497,6 +563,7 @@ async function waitForDetachedForegroundRun(
497
563
  now: () => number,
498
564
  pollIntervalMs: number,
499
565
  timeoutMs: number,
566
+ supervisorYield: () => AgentToolResult<Details>,
500
567
  ): Promise<AgentToolResult<Details>> {
501
568
  const initialDetachedIndices = new Set(run.children.filter((child) => child.status === "detached").map((child) => child.index));
502
569
  while (true) {
@@ -507,6 +574,7 @@ async function waitForDetachedForegroundRun(
507
574
  if (!current || current.sessionId !== run.sessionId) {
508
575
  return result(`Remembered foreground run "${run.runId}" disappeared before a terminal child result was recorded. Completion cannot be confirmed; do not launch a replacement without checking the originating child session.`, true);
509
576
  }
577
+ if (deps.hasPendingSupervisorRequest?.()) return supervisorYield();
510
578
  const pending = current.children.filter((child) => initialDetachedIndices.has(child.index) && child.status === "detached");
511
579
  const attention = foregroundChildrenNeedingAttention(current, initialDetachedIndices);
512
580
  if (attention.length > 0) return formatForegroundAttention(current, attention, now() - startedAt);
@@ -531,6 +599,38 @@ async function waitForDetachedForegroundRun(
531
599
  }
532
600
  }
533
601
 
602
+ async function waitForSessionDetachedForegroundRuns(
603
+ runs: ForegroundResumeRun[],
604
+ signal: AbortSignal | undefined,
605
+ deps: SubagentWaitDeps,
606
+ startedAt: number,
607
+ now: () => number,
608
+ pollIntervalMs: number,
609
+ timeoutMs: number,
610
+ supervisorYield: () => AgentToolResult<Details>,
611
+ ): Promise<AgentToolResult<Details>> {
612
+ const texts: string[] = [];
613
+ for (const run of runs) {
614
+ const one = await waitForDetachedForegroundRun(run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield);
615
+ if (one.isError) return one;
616
+ if (one.details.wait?.reason === "supervisor_request") return one;
617
+ if (one.details.wait?.reason === "window_elapsed") {
618
+ const activeRunIds = runs.filter((initial) => {
619
+ const current = deps.state.foregroundRuns?.get(initial.runId);
620
+ if (!current || current.sessionId !== initial.sessionId) return false;
621
+ return initial.children.some((child) => child.status === "detached"
622
+ && current.children.some((candidate) => candidate.index === child.index && candidate.status === "detached"));
623
+ }).map((activeRun) => activeRun.runId);
624
+ return windowElapsedResult(
625
+ one.content.map((part) => part.type === "text" ? part.text : "").join("\n"),
626
+ activeRunIds,
627
+ );
628
+ }
629
+ texts.push(one.content.map((part) => part.type === "text" ? part.text : "").join("\n").trim());
630
+ }
631
+ return result(texts.filter(Boolean).join("\n") || `Waited ${formatDuration(now() - startedAt)} for remembered detached foreground run(s); done.`);
632
+ }
633
+
534
634
  /**
535
635
  * Block until the targeted async or remembered detached foreground run finishes,
536
636
  * the timeout elapses, or the turn is aborted. Resolves with a short
@@ -554,6 +654,7 @@ export async function waitForSubagents(
554
654
  ? params.timeoutMs
555
655
  : deps.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
556
656
  const startedAt = now();
657
+ const sessionId = deps.state.currentSessionId;
557
658
  const waitForAll = params.id ? true : params.all === true;
558
659
  if (params.nonBlocking && !params.id) {
559
660
  return result("Non-blocking wait subscriptions require id so the registration can bind one exact run identity.", true);
@@ -566,13 +667,17 @@ export async function waitForSubagents(
566
667
  let foreground: ForegroundResumeRun[];
567
668
  let providerSnapshot: BackgroundWorkSnapshot;
568
669
  try {
569
- active = activeRunsForSession(params, deps);
570
- foreground = activeDetachedForegroundRuns(params, deps);
670
+ active = runsForSession(params, deps, !params.id);
671
+ foreground = activeDetachedForegroundRuns(params, deps).map((run) => ({
672
+ ...run,
673
+ children: run.children.map((child) => ({ ...child })),
674
+ }));
571
675
  providerSnapshot = params.id ? { providers: [], items: [] } : backgroundWorkForSession(deps, startedAt);
572
676
  } catch (error) {
573
677
  return result(error instanceof Error ? error.message : String(error), true);
574
678
  }
575
679
 
680
+ let selectedForeground: ForegroundResumeRun | undefined;
576
681
  if (params.id) {
577
682
  const candidates = [
578
683
  ...active.map((run) => ({ kind: "async" as const, id: run.id, run })),
@@ -581,9 +686,21 @@ export async function waitForSubagents(
581
686
  const exact = candidates.filter((candidate) => candidate.id === params.id);
582
687
  const matches = exact.length > 0 ? exact : candidates;
583
688
  if (matches.length > 1) {
584
- return result(`Ambiguous subagent run id prefix "${params.id}" matched ${matches.length} active runs: ${matches.map((candidate) => candidate.id).join(", ")}. Pass a longer id.`, true);
689
+ return result(`Ambiguous subagent run id prefix "${params.id}" matched ${matches.length} runs: ${matches.map((candidate) => candidate.id).join(", ")}. Pass a longer id.`, true);
585
690
  }
586
691
  const selected = matches[0];
692
+ if (selected?.kind === "async" && !ACTIVE_STATES.includes(selected.run.state)) {
693
+ try {
694
+ const references: string[] = [];
695
+ const completions = collectScopedCompletions([selected.run], deps, references);
696
+ return result(
697
+ `Run "${selected.id}" is terminal. Outcome: ${summarizeTerminalRuns([selected.run])}.${formatCompletionRecovery(completions)}${references.length ? `\n${references.join("\n")}` : ""}`,
698
+ deps.failOnFailedRuns === true && (selected.run.state === "failed" || selected.run.state === "partial"), completions,
699
+ );
700
+ } catch (error) {
701
+ return result(error instanceof Error ? error.message : String(error), true);
702
+ }
703
+ }
587
704
  if (selected && params.nonBlocking) {
588
705
  if (!deps.subscribe) {
589
706
  return result("Non-blocking wait subscriptions require a long-lived interactive subagent runtime; this runtime can only use blocking bg_wait calls.", true);
@@ -595,27 +712,47 @@ export async function waitForSubagents(
595
712
  return result(error instanceof Error ? error.message : String(error), true);
596
713
  }
597
714
  }
598
- if (selected?.kind === "foreground") {
599
- return waitForDetachedForegroundRun(selected.run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs);
600
- }
715
+ selectedForeground = selected?.kind === "foreground" ? selected.run : undefined;
601
716
  active = selected?.kind === "async" ? [selected.run] : [];
602
717
  }
603
718
 
604
719
  let providerActive = providerSnapshot.items;
720
+ const scopedForeground = selectedForeground ? [selectedForeground] : params.id ? [] : foreground;
721
+ const initialAsyncIds = new Set(active.map((run) => run.id));
722
+ const initialProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
723
+ const initialScope: InitialWaitScope = {
724
+ asyncRunIds: initialAsyncIds,
725
+ foregroundRuns: scopedForeground.map((run) => ({
726
+ runId: run.runId,
727
+ sessionId: run.sessionId,
728
+ detachedIndices: new Set(run.children.filter((child) => child.status === "detached").map((child) => child.index)),
729
+ })),
730
+ providerIds: initialProviderIds,
731
+ };
732
+ const supervisorYield = () => supervisorYieldForScope(initialScope, params, deps, now());
733
+ if (selectedForeground) {
734
+ return waitForDetachedForegroundRun(selectedForeground, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield);
735
+ }
605
736
  if (active.length === 0 && providerActive.length === 0) {
737
+ if (waitForAll && !params.id && foreground.length > 0) {
738
+ return waitForSessionDetachedForegroundRuns(foreground, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield);
739
+ }
606
740
  return result(params.id
607
741
  ? `No active run matched "${params.id}". Nothing to wait for.`
608
742
  : "No active async runs or registered provider work in this session. Nothing to wait for.");
609
743
  }
610
744
  const waitParams = params.id ? { ...params, id: active[0]!.id } : params;
611
- const initialAsyncIds = new Set(active.map((run) => run.id));
612
- const initialProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
613
745
  const initialProviderNames = new Set(providerActive.map((item) => item.provider));
614
746
  const initialCount = initialAsyncIds.size + initialProviderIds.size;
615
747
  const stopOnAttention = params.stopOnAttention ?? deps.stopOnAttention !== false;
616
748
  let attention = active.filter((run) => needsAttention(run));
749
+ let supervisorBarrier = false;
617
750
 
618
751
  const isDone = (): boolean => {
752
+ if (deps.hasPendingSupervisorRequest?.()) {
753
+ supervisorBarrier = true;
754
+ return true;
755
+ }
619
756
  if (attention.some((run) => initialAsyncIds.has(run.id) && (stopOnAttention || hasSupervisorTool(run)))) return true;
620
757
  const activeAsyncIds = new Set(active.map((run) => run.id));
621
758
  const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
@@ -647,6 +784,7 @@ export async function waitForSubagents(
647
784
  }
648
785
  try {
649
786
  await waitForWake(pollIntervalMs, signal, deps);
787
+ if (deps.state.currentSessionId !== sessionId) return result("Wait stopped because the active session changed.", true);
650
788
  active = activeRunsForSession(waitParams, deps);
651
789
  attention = attentionRunsForSession(waitParams, deps, initialAsyncIds);
652
790
  providerSnapshot = params.id ? providerSnapshot : backgroundWorkForSession(deps, now());
@@ -660,12 +798,16 @@ export async function waitForSubagents(
660
798
  return result(error instanceof Error ? error.message : String(error), true);
661
799
  }
662
800
  }
801
+ if (supervisorBarrier) {
802
+ return supervisorYield();
803
+ }
663
804
 
664
805
  let terminalSummary: string;
665
806
  let finishedAsyncCount: number;
666
807
  let failedAsyncCount: number;
667
808
  let completions: WaitCompletion[] | undefined;
668
809
  let resumeGuidance = "";
810
+ const references: string[] = [];
669
811
  const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
670
812
  const providerFinishedCount = [...initialProviderIds].filter((id) => !activeProviderIds.has(id)).length;
671
813
  try {
@@ -675,7 +817,7 @@ export async function waitForSubagents(
675
817
  failedAsyncCount = terminal.filter((run) => run.state === "failed" || run.state === "partial").length;
676
818
  terminalSummary = summarizeTerminalRuns(terminal, providerFinishedCount);
677
819
  resumeGuidance = formatResumeFirstFailedRunsNote(terminal);
678
- completions = collectWaitCompletions(terminal, deps.state, deps.resultsDir ?? DIRS.results);
820
+ completions = collectScopedCompletions(terminal, deps, references);
679
821
  } catch (error) {
680
822
  return result(error instanceof Error ? error.message : String(error), true);
681
823
  }
@@ -691,9 +833,18 @@ export async function waitForSubagents(
691
833
  + providerActive.filter((item) => initialProviderIds.has(backgroundWorkIdentity(item))).length;
692
834
  const elapsed = formatDuration(now() - startedAt);
693
835
  const outcome = terminalSummary ? ` Outcome: ${terminalSummary}.` : "";
694
- const recoveryNote = formatCompletionRecovery(completions);
836
+ const recoveryNote = formatCompletionRecovery(completions) + (references.length ? `\n${references.join("\n")}\n` : "");
695
837
 
696
838
  if (waitForAll) {
839
+ const foregroundResult = !params.id && foreground.length > 0 && relevantAttention.length === 0
840
+ ? await waitForSessionDetachedForegroundRuns(foreground, signal, deps, startedAt, now, pollIntervalMs, timeoutMs, supervisorYield)
841
+ : undefined;
842
+ if (foregroundResult?.isError) return foregroundResult;
843
+ if (foregroundResult?.details.wait?.reason === "supervisor_request") return foregroundResult;
844
+ if (foregroundResult?.details.wait?.reason === "window_elapsed") return foregroundResult;
845
+ const foregroundNote = foregroundResult
846
+ ? `\n${foregroundResult.content.map((part) => part.type === "text" ? part.text : "").join("\n")}`
847
+ : "";
697
848
  const scope = params.id
698
849
  ? `run "${params.id}"`
699
850
  : initialProviderIds.size === 0
@@ -701,7 +852,7 @@ export async function waitForSubagents(
701
852
  : `${initialAsyncIds.size} async run(s) and ${initialProviderIds.size} provider item(s)`;
702
853
  const status = relevantAttention.length > 0 ? "attention required" : "done";
703
854
  return result(
704
- `Waited ${elapsed} for ${scope}; ${status}.${outcome}${recoveryNote}${resumeGuidance}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
855
+ `Waited ${elapsed} for ${scope}; ${status}.${outcome}${recoveryNote}${resumeGuidance}${attentionNote}${foregroundNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
705
856
  (deps.failOnFailedRuns === true && failedAsyncCount > 0) || (deps.failOnAttention === true && relevantAttention.length > 0),
706
857
  completions,
707
858
  );
@@ -2,7 +2,7 @@ import * as fs from "node:fs";
2
2
  import type { ArtifactPaths, SubagentState, Usage, WaitCompletion, WaitCompletionChild } from "../../shared/types.ts";
3
3
  import type { AsyncRunSummary } from "./async-status.ts";
4
4
  import { readCompletionReplay, writeCompletionReplay } from "./completion-replay.ts";
5
- import { fallbackResultPayloadPathForSessionRun, resultFilePath, resultPayloadPathForSessionRun } from "./result-files.ts";
5
+ import { fallbackResultPayloadPathForSessionRun, resultFilePath, resultPayloadMatchesSessionRun, resultPayloadPathForSessionRun } from "./result-files.ts";
6
6
  import { parseWorkflowChildSummary } from "../../workflows/workflow-child-summary.ts";
7
7
  import { projectTimeoutRecovery } from "../shared/mutation-evidence.ts";
8
8
 
@@ -44,6 +44,27 @@ function errorMessage(error: unknown): string {
44
44
 
45
45
  const STRUCTURED_OUTPUT_INLINE_LIMIT_BYTES = 4 * 1024;
46
46
 
47
+ function waitResultPayloadCandidate(resultsDir: string, run: AsyncRunSummary): string {
48
+ const publicPath = resultFilePath(resultsDir, run.id);
49
+ if (!run.sessionId) return publicPath;
50
+ try {
51
+ const indexedPath = resultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id);
52
+ return indexedPath ?? publicPath;
53
+ } catch (error) {
54
+ if (!isAccessDenied(error)) throw error;
55
+ const pendingPath = fallbackResultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id);
56
+ return pendingPath ?? publicPath;
57
+ }
58
+ }
59
+
60
+ function readWaitResultPayload(candidatePath: string, run: AsyncRunSummary): Record<string, unknown> | undefined {
61
+ // A terminal run without session ownership cannot safely claim a payload.
62
+ if (!run.sessionId) return undefined;
63
+ const payload: unknown = JSON.parse(fs.readFileSync(candidatePath, "utf-8"));
64
+ if (!resultPayloadMatchesSessionRun(payload, run.sessionId, run.id)) return undefined;
65
+ return payload as Record<string, unknown>;
66
+ }
67
+
47
68
  export function projectStructuredOutput(value: unknown): unknown {
48
69
  if (value === undefined) return undefined;
49
70
  const serialized = JSON.stringify(value);
@@ -96,6 +117,9 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
96
117
  })
97
118
  : undefined;
98
119
  const agent = asNonEmptyString(data.agent);
120
+ const receipt = data.workflowReceipt;
121
+ const workflowReceiptPath = receipt && typeof receipt === "object" && !Array.isArray(receipt)
122
+ ? asNonEmptyString((receipt as Record<string, unknown>).path) : undefined;
99
123
  const mode = asNonEmptyString(data.mode);
100
124
  const state = asNonEmptyString(data.state);
101
125
  const workflowChildren = parseWorkflowChildSummary(data.workflowChildren);
@@ -104,6 +128,7 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
104
128
  runId,
105
129
  ...(agent ? { agent } : {}),
106
130
  ...(mode ? { mode } : {}),
131
+ ...(workflowReceiptPath ? { workflowReceiptPath } : {}),
107
132
  ...(state ? { state } : {}),
108
133
  ...(typeof data.success === "boolean" ? { success: data.success } : {}),
109
134
  ...(results && results.length > 0 ? { results } : {}),
@@ -114,8 +139,9 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
114
139
  /**
115
140
  * Record a consumed terminal payload for later surfacing by bg_wait, pruning
116
141
  * stale entries with the same TTL that dedupes completion notifications. The result
117
- * file is deleted after delivery, so this record is the only in-process source once
118
- * the watcher has consumed it.
142
+ * file is deleted after durable replay succeeds, so this record is the in-process
143
+ * source once the watcher has consumed it. Payload ownership must be explicit and
144
+ * agree with persistence ownership. Returns whether that replay is durable.
119
145
  */
120
146
  export function recordWaitCompletion(
121
147
  state: SubagentState,
@@ -124,7 +150,10 @@ export function recordWaitCompletion(
124
150
  now: number,
125
151
  ttlMs: number,
126
152
  persistence?: { resultsDir: string; sessionId: string },
127
- ): void {
153
+ ): boolean {
154
+ const sessionId = asNonEmptyString(data.sessionId);
155
+ if (!sessionId || !resultPayloadMatchesSessionRun(data, sessionId, runId)) return false;
156
+ if (persistence && persistence.sessionId !== sessionId) return false;
128
157
  const store = state.completedResults ??= new Map();
129
158
  for (const [key, entry] of store) {
130
159
  if (now - entry.seenAt > ttlMs) store.delete(key);
@@ -144,7 +173,8 @@ export function recordWaitCompletion(
144
173
  console.error(`Failed to persist completion replay for '${runId}':`, error);
145
174
  }
146
175
  }
147
- store.set(runId, { seenAt: now, completion });
176
+ store.set(runId, { sessionId, seenAt: now, completion });
177
+ return completion.archivePath !== undefined;
148
178
  }
149
179
 
150
180
  /**
@@ -153,37 +183,59 @@ export function recordWaitCompletion(
153
183
  * so a direct read never observes a torn write; the read is deliberately read-only —
154
184
  * the watcher owns notification and cleanup.
155
185
  */
156
- export function collectWaitCompletions(terminal: AsyncRunSummary[], state: SubagentState, resultsDir: string): WaitCompletion[] | undefined {
186
+ export function collectWaitCompletions(terminal: AsyncRunSummary[], state: SubagentState, resultsDir: string, onReference?: (text: string) => void): WaitCompletion[] | undefined {
157
187
  if (terminal.length === 0) return undefined;
158
188
  const completions: WaitCompletion[] = [];
189
+ const add = (completion: WaitCompletion, resultPath?: string): void => {
190
+ completions.push(completion);
191
+ // Tool details are not model context. Publish the evidence address in content
192
+ // without copying potentially unbounded reviewer output into every wait.
193
+ const reference = completion.archivePath ?? resultPath;
194
+ if (reference) onReference?.(`Result [${completion.runId}]: ${reference}`);
195
+ };
159
196
  for (const run of terminal) {
160
197
  const recorded = state.completedResults?.get(run.id);
161
- if (recorded) {
162
- completions.push(recorded.completion);
198
+ if (recorded && recorded.sessionId === run.sessionId) {
199
+ if (recorded.completion.archivePath) {
200
+ add(recorded.completion);
201
+ continue;
202
+ }
203
+ try {
204
+ const candidatePath = waitResultPayloadCandidate(resultsDir, run);
205
+ if (!readWaitResultPayload(candidatePath, run)) {
206
+ const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
207
+ add(replay?.completion ?? recorded.completion);
208
+ continue;
209
+ }
210
+ add(recorded.completion, candidatePath);
211
+ continue;
212
+ } catch (error) {
213
+ if (errorCode(error) !== "ENOENT") throw error;
214
+ }
215
+ const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
216
+ add(replay?.completion ?? recorded.completion);
163
217
  continue;
164
218
  }
165
- const publicResultPath = resultFilePath(resultsDir, run.id);
166
- let resultPath = publicResultPath;
219
+ let candidatePath: string;
167
220
  try {
168
- resultPath = run.sessionId
169
- ? resultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id) ?? publicResultPath
170
- : publicResultPath;
221
+ candidatePath = waitResultPayloadCandidate(resultsDir, run);
171
222
  } catch (error) {
172
- if (!isAccessDenied(error) || !run.sessionId) throw error;
173
- try {
174
- resultPath = fallbackResultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id) ?? publicResultPath;
175
- } catch (fallbackError) {
176
- throw new Error(`Failed to read subagent result '${publicResultPath}': ${errorMessage(fallbackError)}`, {
177
- cause: fallbackError instanceof Error ? fallbackError : undefined,
178
- });
179
- }
223
+ const publicResultPath = resultFilePath(resultsDir, run.id);
224
+ throw new Error(`Failed to read subagent result '${publicResultPath}': ${errorMessage(error)}`, {
225
+ cause: error instanceof Error ? error : undefined,
226
+ });
180
227
  }
181
228
  try {
182
- const raw = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as Record<string, unknown>;
183
- completions.push(toWaitCompletion(raw, run.id));
229
+ const payload = readWaitResultPayload(candidatePath, run);
230
+ if (!payload) {
231
+ const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
232
+ if (replay) add(replay.completion);
233
+ continue;
234
+ }
235
+ add(toWaitCompletion(payload, run.id), candidatePath);
184
236
  } catch (error) {
185
237
  if (errorCode(error) !== "ENOENT") {
186
- throw new Error(`Failed to read subagent result '${resultPath}': ${errorMessage(error)}`, {
238
+ throw new Error(`Failed to read subagent result '${candidatePath}': ${errorMessage(error)}`, {
187
239
  cause: error instanceof Error ? error : undefined,
188
240
  });
189
241
  }
@@ -191,13 +243,13 @@ export function collectWaitCompletions(terminal: AsyncRunSummary[], state: Subag
191
243
  // read. Prefer its in-memory record, then the durable replay written before
192
244
  // result cleanup so watcher reloads do not lose completion details.
193
245
  const late = state.completedResults?.get(run.id);
194
- if (late) {
195
- completions.push(late.completion);
246
+ if (late && late.sessionId === run.sessionId) {
247
+ add(late.completion);
196
248
  continue;
197
249
  }
198
250
  try {
199
251
  const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
200
- if (replay) completions.push(replay.completion);
252
+ if (replay) add(replay.completion);
201
253
  } catch (replayError) {
202
254
  throw new Error(`Failed to read completion replay for '${run.id}': ${errorMessage(replayError)}`, {
203
255
  cause: replayError instanceof Error ? replayError : undefined,
@@ -44,6 +44,7 @@ export interface ArmWaitSubscriptionInput {
44
44
  }
45
45
 
46
46
  export interface WaitSubscriptionManager {
47
+ start(): void;
47
48
  arm(input: ArmWaitSubscriptionInput): WaitSubscriptionRecord;
48
49
  restore(): void;
49
50
  reconcile(): void;
@@ -109,6 +110,7 @@ export function createWaitSubscriptionManager(
109
110
  state.waitSubscriptions = subscriptions;
110
111
  const unresolvedRestoredForegroundTokens = new Set<string>();
111
112
  let disposed = false;
113
+ let interval: ReturnType<typeof setInterval> | undefined;
112
114
  let lastForeignSweepAt = 0;
113
115
 
114
116
  /**
@@ -283,10 +285,13 @@ export function createWaitSubscriptionManager(
283
285
  SUBAGENT_RESULT_INTERCOM_EVENT,
284
286
  ];
285
287
  const unsubscribes = wakeChannels.map((channel) => pi.events.on(channel, reconcile));
286
- const interval = setInterval(reconcile, options.pollIntervalMs ?? RECONCILE_INTERVAL_MS);
287
- interval.unref?.();
288
288
 
289
289
  return {
290
+ start() {
291
+ if (disposed || interval) return;
292
+ interval = setInterval(reconcile, options.pollIntervalMs ?? RECONCILE_INTERVAL_MS);
293
+ interval.unref?.();
294
+ },
290
295
  arm(input) {
291
296
  const sessionId = state.currentSessionId;
292
297
  if (!sessionId) throw new Error("A wait subscription requires an active session identity.");
@@ -338,7 +343,8 @@ export function createWaitSubscriptionManager(
338
343
  dispose() {
339
344
  if (disposed) return;
340
345
  disposed = true;
341
- clearInterval(interval);
346
+ if (interval) clearInterval(interval);
347
+ interval = undefined;
342
348
  for (const unsubscribe of unsubscribes) {
343
349
  try { unsubscribe(); } catch { /* best effort */ }
344
350
  }
@@ -11,14 +11,15 @@ export function registerWaitTool(
11
11
  enabled = resolveWaitToolConfig().enabled,
12
12
  subscriptions?: Pick<WaitSubscriptionManager, "arm">,
13
13
  defaultTimeoutMs?: number,
14
+ child?: { nestedRootRunId?: string },
14
15
  ): void {
15
16
  const description = `Wait for background, provider, or detached work that has no native completion notification, then return.
16
17
 
17
- Ordinary async subagent runs already notify this session natively when they complete or need attention. In an interactive chat, return control instead of calling this merely to wait. Use this tool for provider jobs, remembered detached foreground runs, or other background work without a native notification path. Headless runs auto-drain current-session subagent work at agent_end; use this tool only when the current turn must receive non-notifying background work results.
18
+ ${child ? "This child runtime does not install the root session's native completion notifier. Use blocking bg_wait to collect your owned descendants during this turn, then read the returned result references before synthesizing findings. Automatic draining at agent_end keeps owned work alive but does not synthesize its results." : "Ordinary async subagent runs already notify this session natively when they complete or need attention. In an interactive chat, return control instead of calling this merely to wait. Use this tool for provider jobs, remembered detached foreground runs, or other background work without a native notification path. Headless runs auto-drain current-session subagent work at agent_end; use this tool only when the current turn must receive non-notifying background work results."}
18
19
 
19
20
  • { } — return when the first initially active async run or registered provider item finishes, or when a subagent needs attention.
20
- • { all: true } — wait for every async run and provider item that was active when the call began.
21
- • { id: "..." } — wait for one async or remembered detached foreground subagent run (id or prefix).
21
+ • { all: true } — wait for every async run, provider item, and remembered detached foreground descendant that was active when the call began.
22
+ • { id: "..." } — wait for one async or remembered detached foreground subagent run (id or prefix). Named async runs that already finished return their terminal result references.
22
23
  • { id: "...", nonBlocking: true } — resolve the prefix once, persist an exact-run wake subscription, and return immediately. Use this for detached work without native completion delivery; the originating interactive session wakes on completion, failure, attention, reconciliation failure, or timeout.
23
24
  • { stopOnAttention: false } — for blocking waits only, keep waiting through idle or long-thinking attention; supervisor/contact requests still stop the wait.
24
25
  • { timeoutMs: 600000 } — stop waiting after N ms; active work keeps running. Omitted values use waitTool.defaultTimeoutMs, then 30 minutes. Window expiry returns a non-error window_elapsed result with active work identities.
@@ -26,6 +27,7 @@ Ordinary async subagent runs already notify this session natively when they comp
26
27
  Non-blocking subscriptions are visible in subagent status and differ from disabling waitTool: waitTool.enabled=false returns immediately without registering any future wake. Provider jobs are session-scoped and identified exactly, so replacing one job with another cannot hide a completion. Provider extensions must be explicitly loaded in this process. In a child agent, keep \`bg_wait\` in the child tool allowlist and load each provider through the agent's extensions or subagentOnlyExtensions; this tool never loads providers or grants tools itself.${enabled ? "" : "\n\nConfigured behavior: bg_wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED and returns immediately without blocking."}`;
27
28
  const execute: ToolDefinition<typeof SubagentWaitParams, Details>["execute"] = async (_id, params, signal, onUpdate, ctx) => finalizeToolResult(await waitForSubagents(params, signal, {
28
29
  state,
30
+ nestedRootRunId: child?.nestedRootRunId,
29
31
  events: pi.events,
30
32
  enabled,
31
33
  ...(defaultTimeoutMs !== undefined ? { defaultTimeoutMs } : {}),