@xzzpig/pi-subagents 0.1.0 → 0.3.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 (108) hide show
  1. package/CHANGELOG.md +135 -0
  2. package/README.md +4 -0
  3. package/agents/reviewer.md +3 -4
  4. package/docs/agents.md +343 -0
  5. package/docs/configuration.md +395 -0
  6. package/docs/extension-api.md +308 -0
  7. package/docs/missions.md +121 -0
  8. package/docs/models.md +192 -0
  9. package/docs/observability.md +198 -0
  10. package/docs/tool-reference.md +343 -0
  11. package/docs/watchdog.md +176 -0
  12. package/docs/workflows.md +163 -0
  13. package/package.json +13 -11
  14. package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
  15. package/skills/pi-subagents/references/execution-controls.md +7 -7
  16. package/skills/pi-subagents/references/management-authoring-rpc.md +1 -1
  17. package/skills/pi-subagents/references/prompting-and-roles.md +1 -1
  18. package/src/agents/agents.ts +53 -23
  19. package/src/agents/frontmatter.ts +7 -3
  20. package/src/agents/skills.ts +2 -9
  21. package/src/api/preflight.ts +1 -1
  22. package/src/api/project-panes.ts +30 -0
  23. package/src/extension/config.ts +54 -1
  24. package/src/extension/doctor.ts +40 -0
  25. package/src/extension/fanout-child.ts +5 -4
  26. package/src/extension/index.ts +114 -38
  27. package/src/extension/public-execution.ts +35 -4
  28. package/src/extension/rpc.ts +10 -15
  29. package/src/extension/schemas.ts +33 -11
  30. package/src/extension/subagent-guide.ts +39 -0
  31. package/src/extension/tool-description.ts +38 -18
  32. package/src/inspectors/herdr/actions.ts +11 -2
  33. package/src/inspectors/herdr/inspector-runner.ts +16 -3
  34. package/src/inspectors/herdr/project-panes.ts +459 -63
  35. package/src/intercom/intercom-bridge.ts +7 -2
  36. package/src/intercom/native-supervisor-channel.ts +102 -4
  37. package/src/missions/actions.ts +25 -2
  38. package/src/missions/lifecycle.ts +25 -9
  39. package/src/missions/store.ts +89 -7
  40. package/src/missions/types.ts +33 -0
  41. package/src/missions/workflow-state.ts +25 -15
  42. package/src/runs/background/active-async-capacity.ts +431 -0
  43. package/src/runs/background/active-run-index.ts +46 -0
  44. package/src/runs/background/async-execution.ts +158 -71
  45. package/src/runs/background/async-job-tracker.ts +297 -133
  46. package/src/runs/background/async-resume.ts +37 -5
  47. package/src/runs/background/async-status.ts +39 -5
  48. package/src/runs/background/chain-append.ts +33 -15
  49. package/src/runs/background/completion-replay.ts +267 -0
  50. package/src/runs/background/control-channel.ts +95 -54
  51. package/src/runs/background/fleet-view.ts +18 -5
  52. package/src/runs/background/owned-process-tree.ts +104 -0
  53. package/src/runs/background/process-terminal.ts +17 -3
  54. package/src/runs/background/result-watcher.ts +113 -10
  55. package/src/runs/background/resume-guidance.ts +53 -0
  56. package/src/runs/background/retained-children.ts +14 -6
  57. package/src/runs/background/run-status.ts +119 -5
  58. package/src/runs/background/scheduled-runs.ts +25 -1
  59. package/src/runs/background/stale-run-reconciler.ts +12 -24
  60. package/src/runs/background/subagent-runner.ts +127 -41
  61. package/src/runs/background/subagent-wait.ts +5 -2
  62. package/src/runs/background/wait-completions.ts +39 -5
  63. package/src/runs/background/wait-subscriptions.ts +21 -5
  64. package/src/runs/foreground/async-dismiss-action.ts +85 -0
  65. package/src/runs/foreground/async-steering-action.ts +7 -8
  66. package/src/runs/foreground/chain-execution.ts +40 -2
  67. package/src/runs/foreground/execution.ts +97 -19
  68. package/src/runs/foreground/foreground-control.ts +12 -0
  69. package/src/runs/foreground/foreground-history.ts +137 -0
  70. package/src/runs/foreground/prompt-audit.ts +172 -0
  71. package/src/runs/foreground/subagent-executor.ts +1274 -243
  72. package/src/runs/foreground/workflow-foreground-steering.ts +187 -0
  73. package/src/runs/shared/acceptance.ts +13 -4
  74. package/src/runs/shared/completion-guard.ts +17 -1
  75. package/src/runs/shared/dynamic-fanout.ts +1 -1
  76. package/src/runs/shared/llm-intent-arbiter.ts +302 -0
  77. package/src/runs/shared/model-fallback.ts +8 -4
  78. package/src/runs/shared/model-scope.ts +12 -2
  79. package/src/runs/shared/parallel-utils.ts +3 -0
  80. package/src/runs/shared/pi-args.ts +44 -1
  81. package/src/runs/shared/run-fanout-budget.ts +280 -0
  82. package/src/runs/shared/single-output.ts +4 -2
  83. package/src/runs/shared/subagent-prompt-runtime.ts +94 -9
  84. package/src/runs/shared/task-intent.ts +19 -3
  85. package/src/runs/shared/worktree.ts +20 -7
  86. package/src/shared/agent-stream-options.ts +5 -0
  87. package/src/shared/artifacts.ts +17 -21
  88. package/src/shared/display-text.ts +150 -0
  89. package/src/shared/file-coalescer.ts +9 -0
  90. package/src/shared/fork-context.ts +13 -0
  91. package/src/shared/formatters.ts +4 -6
  92. package/src/shared/node-executable.ts +21 -0
  93. package/src/shared/prompt-resources.ts +51 -0
  94. package/src/shared/settings.ts +15 -2
  95. package/src/shared/types.ts +158 -4
  96. package/src/shared/utf8.ts +11 -0
  97. package/src/shared/utils.ts +46 -34
  98. package/src/slash/prompt-workflows.ts +2 -15
  99. package/src/slash/slash-commands.ts +22 -2
  100. package/src/tui/fleet-status.ts +29 -17
  101. package/src/tui/fleet-transcript.ts +1 -48
  102. package/src/tui/fleet.ts +362 -37
  103. package/src/tui/render.ts +235 -71
  104. package/src/watchdog/change-signature.ts +4 -3
  105. package/src/watchdog/permission-arbiter.ts +2 -1
  106. package/src/watchdog/review.ts +4 -3
  107. package/src/workflows/chat-progress.ts +8 -2
  108. package/src/workflows/scripted-workflow.ts +273 -20
@@ -5,6 +5,8 @@ import * as path from "node:path";
5
5
  import { pathToFileURL } from "node:url";
6
6
  import type { Message } from "@earendil-works/pi-ai";
7
7
  import { writeAtomicJson } from "../../shared/atomic-json.ts";
8
+ import { createFileCoalescer } from "../../shared/file-coalescer.ts";
9
+ import { isActiveAsyncState, updateActiveRunIndex } from "./active-run-index.ts";
8
10
  import { createChildTranscriptWriter, type ChildTranscriptWriter } from "../../shared/child-transcript.ts";
9
11
  import { closeSteerInbox, consumeInterruptRequest, consumeSteerRequests, deliverInterruptRequest, deliverStopRequest, deliverTimeoutRequest, enqueueStepSteer, steerAcksDir, steerCapabilityPath, stepSteerInboxDir, watchAsyncControlInbox, type SteerAck, type SteerCapability, type SteerRequest } from "./control-channel.ts";
10
12
  import { appendJsonl as appendRawJsonl, formatOutputArtifactContent, getArtifactPaths, writeArtifact, writeMetadata } from "../../shared/artifacts.ts";
@@ -23,11 +25,14 @@ import {
23
25
  type LaunchResolvedChildExtensionsV1,
24
26
  type RuntimeAcknowledgedChildExtensionsV1,
25
27
  type ModelAttempt,
28
+ type PiWriterProcessInstanceExitV1,
29
+ type ProcessTreeTerminalV1,
26
30
  type NestedRouteInfo,
27
31
  type NestedRunSummary,
28
32
  type ResolvedControlConfig,
29
33
  type ResolvedTurnBudget,
30
34
  type ResolvedToolBudget,
35
+ type RunFanoutBudgetDescriptor,
31
36
  type SubagentRunMode,
32
37
  type SubagentOutputState,
33
38
  type UsageBudgetConfig,
@@ -66,13 +71,14 @@ import {
66
71
  DEFAULT_GLOBAL_CONCURRENCY_LIMIT,
67
72
  Semaphore,
68
73
  } from "../shared/parallel-utils.ts";
69
- import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/pi-args.ts";
74
+ import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan, type SubagentTaskDelivery } from "../shared/pi-args.ts";
70
75
  import { readRuntimeAcknowledgedExtensions } from "../shared/runtime-acknowledged-extensions.ts";
71
76
  import { outputEntryFromAsyncResult, resolveOutputReferences } from "../shared/chain-outputs.ts";
72
77
  import { createStructuredOutputRuntime, MISSING_STRUCTURED_OUTPUT_CALL_ERROR, readStructuredOutput } from "../shared/structured-output.ts";
73
78
  import { formatProcessSignalError, isUnexplainedProcessSignal } from "../shared/process-signal.ts";
74
79
  import { readChildToolDiagnosticError } from "../shared/tool-availability.ts";
75
80
  import { collectDynamicResults, DynamicFanoutError, materializeDynamicParallelStep, validateDynamicCollection } from "../shared/dynamic-fanout.ts";
81
+ import { claimRunFanoutBatch, getRunFanoutBudgetSnapshot } from "../shared/run-fanout-budget.ts";
76
82
  import { nestedSummaryFromAsyncStatus, projectNestedEvents, resolveNestedAsyncDir, writeNestedEvent } from "../shared/nested-events.ts";
77
83
  import { formatModelAttemptNote, isRetryableModelFailure } from "../shared/model-fallback.ts";
78
84
  import {
@@ -83,9 +89,10 @@ import {
83
89
  waitForSubagentStartupRetry,
84
90
  } from "../shared/subagent-startup-retry.ts";
85
91
  import { markProcessTerminalCandidateLeaseRelease, writeProcessTerminalCandidate, type ProcessTerminalCandidate } from "./process-terminal.ts";
92
+ import { createOwnedProcessTreeController, type OwnedProcessTreeController } from "./owned-process-tree.ts";
86
93
  import { createSteeringStatus, recordSteeringRequest, steeringStatus, terminalSteeringNoticeState, updateSteeringTarget } from "./steering.ts";
87
94
  import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
88
- import { detectSubagentError, extractTextFromContent, extractToolArgsPreview, getFinalOutput, hasEmptyTerminalAssistantResponse, readStatus } from "../../shared/utils.ts";
95
+ import { PROMPT_REDACTED, detectSubagentError, extractTextFromContent, extractToolArgsPreview, getFinalOutput, hasEmptyTerminalAssistantResponse, readStatus } from "../../shared/utils.ts";
89
96
  import { evaluateCompletionMutationGuard } from "../shared/completion-guard.ts";
90
97
  import {
91
98
  createMutatingFailureState,
@@ -136,6 +143,8 @@ import {
136
143
  type ChildWatchdogStateSnapshot,
137
144
  } from "../../watchdog/child-status.ts";
138
145
 
146
+ const INTERCOM_DETACH_RECEIPT = "Detached for intercom coordination before task completion.";
147
+
139
148
  interface SubagentRunConfig {
140
149
  id: string;
141
150
  steps: RunnerStep[];
@@ -175,6 +184,7 @@ interface SubagentRunConfig {
175
184
  /** Global cap on simultaneously-running subagent tasks within this run. */
176
185
  globalConcurrencyLimit?: number;
177
186
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
187
+ runFanoutBudget?: RunFanoutBudgetDescriptor;
178
188
  launchContractDigest?: string;
179
189
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
180
190
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
@@ -230,7 +240,7 @@ interface StepResult {
230
240
  structuredOutputSchemaPath?: string;
231
241
  acceptance?: import("../../shared/types.ts").AcceptanceLedger;
232
242
  watchdog?: import("../../shared/types.ts").ChildWatchdogProgress;
233
- writerProcesses?: Array<{ processInstanceId: string; kind: "pi-writer"; attempt: number; closeObservedAt: number; exitCode: number | null; signal: string | null }>;
243
+ writerProcesses?: PiWriterProcessInstanceExitV1[];
234
244
  writerAttemptCount?: number;
235
245
  runner?: ExternalCliRunnerStatus;
236
246
  externalProcess?: ExternalProcessStatus;
@@ -510,6 +520,7 @@ interface RunPiStreamingResult {
510
520
  processInstanceId: string;
511
521
  processCloseObservedAt?: number;
512
522
  processSignal?: string | null;
523
+ processTree: ProcessTreeTerminalV1;
513
524
  }
514
525
 
515
526
  function runPiStreaming(
@@ -546,7 +557,9 @@ function runPiStreaming(
546
557
  stdio: ["ignore", "pipe", "pipe"],
547
558
  env: spawnEnv,
548
559
  windowsHide: true,
560
+ detached: process.platform !== "win32",
549
561
  });
562
+ let processTreeController: OwnedProcessTreeController | undefined;
550
563
  const stderrTail = createBoundedByteTail();
551
564
  const rawStdoutTail = createBoundedByteTail();
552
565
  const messages: Message[] = [];
@@ -554,6 +567,7 @@ function runPiStreaming(
554
567
  let model: string | undefined;
555
568
  let writerRegistrationError: string | undefined;
556
569
  if (typeof child.pid === "number") {
570
+ processTreeController = createOwnedProcessTreeController(child.pid);
557
571
  try {
558
572
  onWriterProcess?.({ state: "running", pid: child.pid });
559
573
  } catch (writerError) {
@@ -701,7 +715,6 @@ function runPiStreaming(
701
715
  // a lingering stdio holder after `exit`, or a child that never exits.
702
716
  const FINAL_STOP_GRACE_MS = 1000;
703
717
  const HARD_KILL_MS = 3000;
704
- const TIMEOUT_HARD_KILL_MS = 3000;
705
718
  let childExited = false;
706
719
  let forcedTerminationSignal = false;
707
720
  let cleanTerminalAssistantStopReceived = false;
@@ -709,7 +722,6 @@ function runPiStreaming(
709
722
  let finalDrainTimer: NodeJS.Timeout | undefined;
710
723
  let finalHardKillTimer: NodeJS.Timeout | undefined;
711
724
  let watchdogTailTimer: NodeJS.Timeout | undefined;
712
- let timeoutHardKillTimer: NodeJS.Timeout | undefined;
713
725
  let turnBudgetTerminationTimer: NodeJS.Timeout | undefined;
714
726
  let turnBudgetHardKillTimer: NodeJS.Timeout | undefined;
715
727
  let protocolHardKillTimer: NodeJS.Timeout | undefined;
@@ -774,22 +786,16 @@ function runPiStreaming(
774
786
  timedOut = true;
775
787
  interrupted = false;
776
788
  error = timeoutMessage ?? "Subagent timed out.";
777
- trySignalChild(child, "SIGTERM");
778
- timeoutHardKillTimer = setTimeout(() => {
779
- if (!settled) trySignalChild(child, "SIGKILL");
780
- }, TIMEOUT_HARD_KILL_MS);
781
- timeoutHardKillTimer.unref?.();
789
+ if (processTreeController) void processTreeController.terminate();
790
+ else trySignalChild(child, "SIGTERM");
782
791
  });
783
792
  registerStop?.(() => {
784
793
  if (settled || timedOut || stopped) return;
785
794
  stopped = true;
786
795
  interrupted = false;
787
796
  error = stopMessage ?? "Subagent stopped by user.";
788
- trySignalChild(child, "SIGTERM");
789
- timeoutHardKillTimer = setTimeout(() => {
790
- if (!settled) trySignalChild(child, "SIGKILL");
791
- }, TIMEOUT_HARD_KILL_MS);
792
- timeoutHardKillTimer.unref?.();
797
+ if (processTreeController) void processTreeController.terminate();
798
+ else trySignalChild(child, "SIGTERM");
793
799
  });
794
800
  registerTurnBudgetAbort?.((message, state) => {
795
801
  if (settled || timedOut || stopped || turnBudgetExceeded) return;
@@ -818,10 +824,6 @@ function runPiStreaming(
818
824
  finalHardKillTimer = undefined;
819
825
  }
820
826
  clearWatchdogTailTimer();
821
- if (timeoutHardKillTimer) {
822
- clearTimeout(timeoutHardKillTimer);
823
- timeoutHardKillTimer = undefined;
824
- }
825
827
  if (turnBudgetTerminationTimer) {
826
828
  clearTimeout(turnBudgetTerminationTimer);
827
829
  turnBudgetTerminationTimer = undefined;
@@ -883,9 +885,12 @@ function runPiStreaming(
883
885
  childExited = true;
884
886
  clearDrainTimers();
885
887
  });
886
- child.on("close", (exitCode, signal) => {
888
+ child.on("close", async (exitCode, signal) => {
887
889
  settled = true;
888
890
  const processCloseObservedAt = Date.now();
891
+ const processTree = processTreeController
892
+ ? await processTreeController.finishAfterWriterClose()
893
+ : { state: "unknown" as const, reason: "verification-failed" as const, diagnostic: "Writer PID was unavailable." };
889
894
  try {
890
895
  onWriterProcess?.({ state: "none" });
891
896
  } catch {
@@ -937,6 +942,7 @@ function runPiStreaming(
937
942
  processInstanceId,
938
943
  processCloseObservedAt,
939
944
  processSignal: signal,
945
+ processTree,
940
946
  }));
941
947
  });
942
948
 
@@ -959,7 +965,7 @@ function runPiStreaming(
959
965
  const stderr = stderrTail.text();
960
966
  const finalOutput = getFinalOutput(messages) || rawStdoutTail.text().trim();
961
967
  const spawnErrorMessage = spawnError instanceof Error ? spawnError.message : String(spawnError);
962
- resolve(omitUndefinedProperties({ stderr, exitCode: 1, messages, usage, toolCount, durationMs: Date.now() - startedAt, model, error: stopped ? (stopMessage ?? "Subagent stopped by user.") : timedOut ? (timeoutMessage ?? "Subagent timed out.") : turnBudgetExceeded ? turnBudgetMessage : error ?? assistantError ?? spawnErrorMessage, protocolError, finalOutput: (timedOut || stopped) && !finalOutput.trim() ? (stopped ? stopMessage ?? "Subagent stopped by user." : timeoutMessage ?? "Subagent timed out.") : finalOutput, outputState: finalOutput.trim() ? "present" : "absent", timedOut, stopped, turnBudget, turnBudgetExceeded, wrapUpRequested: turnBudget?.outcome === "wrap-up-requested" || turnBudget?.outcome === "termination-deferred" || turnBudgetExceeded || undefined, observedMutationAttempt, structuredOutputToolInvoked, structuredOutputMessageStartIndex, watchdog: childWatchdogState, processInstanceId }));
968
+ resolve(omitUndefinedProperties({ stderr, exitCode: 1, messages, usage, toolCount, durationMs: Date.now() - startedAt, model, error: stopped ? (stopMessage ?? "Subagent stopped by user.") : timedOut ? (timeoutMessage ?? "Subagent timed out.") : turnBudgetExceeded ? turnBudgetMessage : error ?? assistantError ?? spawnErrorMessage, protocolError, finalOutput: (timedOut || stopped) && !finalOutput.trim() ? (stopped ? stopMessage ?? "Subagent stopped by user." : timeoutMessage ?? "Subagent timed out.") : finalOutput, outputState: finalOutput.trim() ? "present" : "absent", timedOut, stopped, turnBudget, turnBudgetExceeded, wrapUpRequested: turnBudget?.outcome === "wrap-up-requested" || turnBudget?.outcome === "termination-deferred" || turnBudgetExceeded || undefined, observedMutationAttempt, structuredOutputToolInvoked, structuredOutputMessageStartIndex, watchdog: childWatchdogState, processInstanceId, processTree: { state: "unknown", reason: "verification-failed", diagnostic: spawnErrorMessage } }));
963
969
  });
964
970
  });
965
971
  }
@@ -1103,6 +1109,7 @@ interface SingleStepContext {
1103
1109
  orchestratorIntercomTarget?: string;
1104
1110
  nestedRoute?: NestedRouteInfo;
1105
1111
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1112
+ runFanoutBudget?: RunFanoutBudgetDescriptor;
1106
1113
  onAttemptStart?: (attempt: { model?: string; thinking?: string }) => void;
1107
1114
  onChildEvent?: (event: ChildEvent) => void;
1108
1115
  onWriterProcess?: (writer: { state: "none" | "spawning" } | { state: "running"; pid: number }) => void;
@@ -1204,7 +1211,7 @@ async function runSingleStep(
1204
1211
  artifactPaths = getArtifactPaths(ctx.artifactsDir, ctx.id, step.agent, index);
1205
1212
  fs.mkdirSync(ctx.artifactsDir, { recursive: true });
1206
1213
  if (ctx.artifactConfig?.includeInput !== false) {
1207
- fs.writeFileSync(artifactPaths.inputPath, `# Task for ${step.agent}\n\n${task}`, "utf-8");
1214
+ fs.writeFileSync(artifactPaths.inputPath, `# Task for ${step.agent}\n\n${PROMPT_REDACTED}; live Prompt Audit only.\n`, "utf-8");
1208
1215
  }
1209
1216
  if (ctx.artifactConfig?.includeTranscript !== false) {
1210
1217
  transcriptWriter = createChildTranscriptWriter({
@@ -1217,7 +1224,7 @@ async function runSingleStep(
1217
1224
  });
1218
1225
  }
1219
1226
  }
1220
- transcriptWriter?.writeInitialUserMessage(task);
1227
+ transcriptWriter?.writeInitialUserMessage(`${PROMPT_REDACTED}; live Prompt Audit only.`);
1221
1228
 
1222
1229
  if (step.runner?.type === "external-cli") {
1223
1230
  const runner: ExternalCliRunnerStatus = {
@@ -1260,7 +1267,7 @@ async function runSingleStep(
1260
1267
  artifactPaths,
1261
1268
  artifactConfig: ctx.artifactConfig,
1262
1269
  output: formatOutputArtifactContent(omitUndefinedProperties({ output: resolvedOutput.fullOutput, error: external.error, metadataPath: ctx.artifactConfig?.includeMetadata === false ? undefined : artifactPaths.metadataPath })),
1263
- metadata: { runId: ctx.id, agent: step.agent, task, runner, externalProcess: external.externalProcess, exitCode: external.exitCode, error: external.error, timestamp: Date.now() },
1270
+ metadata: { runId: ctx.id, agent: step.agent, task: PROMPT_REDACTED, runner, externalProcess: external.externalProcess, exitCode: external.exitCode, error: external.error, timestamp: Date.now() },
1264
1271
  })
1265
1272
  : {};
1266
1273
  return omitUndefinedProperties({
@@ -1290,7 +1297,7 @@ async function runSingleStep(
1290
1297
  let capabilityAudit: import("../shared/capability-ceiling.ts").SubagentCapabilityAudit | undefined;
1291
1298
  let launchResolvedExtensions = step.launchResolvedExtensions;
1292
1299
  const modelAttempts: ModelAttempt[] = [];
1293
- const writerProcesses: Array<{ processInstanceId: string; kind: "pi-writer"; attempt: number; closeObservedAt: number; exitCode: number | null; signal: string | null }> = [];
1300
+ const writerProcesses: PiWriterProcessInstanceExitV1[] = [];
1294
1301
  let writerAttemptCount = 0;
1295
1302
  const attemptNotes: string[] = [];
1296
1303
  const eventsPath = path.join(path.dirname(ctx.outputFile), "events.jsonl");
@@ -1304,6 +1311,9 @@ async function runSingleStep(
1304
1311
 
1305
1312
  let modelIndex = 0;
1306
1313
  let startupAttemptIndex = 0;
1314
+ // Escalated to "file" after an unexplained zero-activity startup failure so
1315
+ // retries keep the task text out of argv (endpoint pre-exec scans may deny it).
1316
+ let taskDeliveryOverride: SubagentTaskDelivery | undefined;
1307
1317
  modelAttemptsLoop: while (modelIndex < candidates.length) {
1308
1318
  if (ctx.timeoutSignal?.aborted || ctx.stopSignal?.aborted || ctx.skipAcceptance?.()) break;
1309
1319
  const candidate = candidates[modelIndex];
@@ -1329,6 +1339,7 @@ async function runSingleStep(
1329
1339
  parentSessionId: step.parentSessionId,
1330
1340
  baseArgs: ["--mode", "json", "-p"],
1331
1341
  task,
1342
+ taskDelivery: taskDeliveryOverride,
1332
1343
  sessionEnabled,
1333
1344
  sessionDir,
1334
1345
  sessionFile: step.sessionFile,
@@ -1354,6 +1365,10 @@ async function runSingleStep(
1354
1365
  parentControlInbox: ctx.nestedRoute?.controlInbox,
1355
1366
  parentRootRunId: ctx.nestedRoute?.rootRunId,
1356
1367
  parentCapabilityToken: ctx.nestedRoute?.capabilityToken,
1368
+ runFanoutBudget: ctx.runFanoutBudget ? {
1369
+ ...ctx.runFanoutBudget,
1370
+ ...(step.runFanoutPath ? { parentPath: `${ctx.runFanoutBudget.parentPath ? `${ctx.runFanoutBudget.parentPath}/` : ""}${step.runFanoutPath}` } : {}),
1371
+ } : undefined,
1357
1372
  steerInboxDir: ctx.steerInboxDir,
1358
1373
  steerCapabilityPath: ctx.steerCapabilityPath,
1359
1374
  steerAckDir: ctx.steerAckDir,
@@ -1427,6 +1442,7 @@ async function runSingleStep(
1427
1442
  closeObservedAt: run.processCloseObservedAt,
1428
1443
  exitCode: run.exitCode,
1429
1444
  signal: run.processSignal ?? null,
1445
+ processTree: run.processTree,
1430
1446
  });
1431
1447
  }
1432
1448
  if (run.turnBudget) turnBudget = run.turnBudget;
@@ -1581,6 +1597,10 @@ async function runSingleStep(
1581
1597
  });
1582
1598
  const shouldRetry = await waitForSubagentStartupRetry(retryDelayMs, [ctx.timeoutSignal, ctx.stopSignal]);
1583
1599
  if (!shouldRetry || ctx.skipAcceptance?.()) break modelAttemptsLoop;
1600
+ if (!taskDeliveryOverride && run.processSignal === "SIGKILL") {
1601
+ taskDeliveryOverride = "file";
1602
+ attemptNotes.push("[startup-retry] retrying with file task delivery to keep the task text out of the child process argv.");
1603
+ }
1584
1604
  attempt.error = retryNote;
1585
1605
  attemptNotes.push(retryNote);
1586
1606
  startupAttemptIndex += 1;
@@ -1675,6 +1695,7 @@ async function runSingleStep(
1675
1695
  const acceptanceFailure = effectiveAcceptance ? acceptanceFailureMessage(effectiveAcceptance) : undefined;
1676
1696
  const acceptanceCanFailRun = acceptanceFailure && effectiveAcceptance?.explicit && (finalResult?.exitCode ?? 1) === 0 && !finalResult?.interrupted && !timedOutAfterAcceptance && !stoppedAfterAcceptance && !turnBudgetExceeded && !isAgentContractV1(step.agentContract);
1677
1697
  const effectiveFinalExitCode = timedOutAfterAcceptance || stoppedAfterAcceptance || turnBudgetExceeded ? 1 : acceptanceCanFailRun ? 1 : finalResult?.exitCode ?? 1;
1698
+ const intercomDetachReceipt = finalResult?.finalOutput === INTERCOM_DETACH_RECEIPT;
1678
1699
  const effectiveFinalError = stoppedAfterAcceptance
1679
1700
  ? ctx.stopMessage ?? "Subagent stopped by user."
1680
1701
  : timedOutAfterAcceptance
@@ -1683,7 +1704,7 @@ async function runSingleStep(
1683
1704
  ? finalResult?.error ?? (turnBudget ? turnBudgetExceededMessage(turnBudget, turnBudget.turnCount) : "Subagent exceeded turn budget.")
1684
1705
  : acceptanceCanFailRun
1685
1706
  ? (finalResult?.error ? `${finalResult.error}\n${acceptanceFailure}` : acceptanceFailure)
1686
- : finalResult?.error;
1707
+ : finalResult?.error ?? (intercomDetachReceipt ? INTERCOM_DETACH_RECEIPT : undefined);
1687
1708
 
1688
1709
  const artifactErrors = artifactPaths && ctx.artifactConfig?.enabled !== false
1689
1710
  ? persistStepArtifacts({
@@ -1698,7 +1719,7 @@ async function runSingleStep(
1698
1719
  metadata: {
1699
1720
  runId: ctx.id,
1700
1721
  agent: step.agent,
1701
- task,
1722
+ task: PROMPT_REDACTED,
1702
1723
  exitCode: effectiveFinalExitCode,
1703
1724
  model: finalResult?.model,
1704
1725
  attemptedModels: attemptedModels.length > 0 ? attemptedModels : undefined,
@@ -1955,6 +1976,47 @@ function combinedAbortSignal(signals: Array<AbortSignal | undefined>): AbortSign
1955
1976
  return controller.signal;
1956
1977
  }
1957
1978
 
1979
+ async function runSingleStepWithTimeout(
1980
+ step: SubagentStep,
1981
+ ctx: SingleStepContext,
1982
+ parentDeadlineAt?: number,
1983
+ ): Promise<SingleStepResult> {
1984
+ if (step.timeoutMs === undefined) return runSingleStep(step, ctx);
1985
+
1986
+ const parentRemainingMs = parentDeadlineAt === undefined ? undefined : Math.max(0, parentDeadlineAt - Date.now());
1987
+ const timeoutMs = parentRemainingMs === undefined ? step.timeoutMs : Math.min(step.timeoutMs, parentRemainingMs);
1988
+ const timeoutMessage = parentRemainingMs !== undefined && parentRemainingMs <= step.timeoutMs
1989
+ ? ctx.timeoutMessage
1990
+ : `Subagent timed out after ${step.timeoutMs}ms.`;
1991
+ const timeoutController = new AbortController();
1992
+ let timeoutAction: (() => void) | undefined;
1993
+ let timeoutTriggered = false;
1994
+ const triggerTimeout = (): void => {
1995
+ if (timeoutTriggered) return;
1996
+ timeoutTriggered = true;
1997
+ timeoutController.abort();
1998
+ timeoutAction?.();
1999
+ };
2000
+ const registerTimeout = (action: (() => void) | undefined): void => {
2001
+ timeoutAction = action;
2002
+ ctx.registerTimeout?.(action ? triggerTimeout : undefined);
2003
+ if (action && timeoutTriggered) action();
2004
+ };
2005
+ const timer = setTimeout(triggerTimeout, timeoutMs);
2006
+ timer.unref?.();
2007
+ try {
2008
+ return await runSingleStep(step, {
2009
+ ...ctx,
2010
+ registerTimeout,
2011
+ timeoutSignal: combinedAbortSignal([ctx.timeoutSignal, timeoutController.signal]),
2012
+ timeoutMessage,
2013
+ });
2014
+ } finally {
2015
+ clearTimeout(timer);
2016
+ ctx.registerTimeout?.(undefined);
2017
+ }
2018
+ }
2019
+
1958
2020
  async function runSubagent(
1959
2021
  config: SubagentRunConfig,
1960
2022
  onWriterProcess?: (writer: { state: "none" | "spawning" } | { state: "running"; pid: number }) => void,
@@ -2128,6 +2190,7 @@ async function runSubagent(
2128
2190
  ...(config.launchContractDigest ? { launchContractDigest: config.launchContractDigest } : {}),
2129
2191
  ...(config.launchResolvedExtensions ? { launchResolvedExtensions: config.launchResolvedExtensions } : {}),
2130
2192
  ...(config.capabilityCeiling ? { capabilityCeiling: config.capabilityCeiling } : {}),
2193
+ ...(config.runFanoutBudget ? { runFanoutBudget: getRunFanoutBudgetSnapshot(config.runFanoutBudget) } : {}),
2131
2194
  ...(config.parentWorkflowRunId ? { parentWorkflowRunId: config.parentWorkflowRunId } : {}),
2132
2195
  ...(config.workflowKey ? { workflowKey: config.workflowKey } : {}),
2133
2196
  ...(config.runnerProcessInstanceId ? { processTerminal: { version: 1 as const, state: "pending" as const, runId: id, runnerProcessInstanceId: config.runnerProcessInstanceId } } : {}),
@@ -2139,6 +2202,7 @@ async function runSubagent(
2139
2202
 
2140
2203
  fs.mkdirSync(asyncDir, { recursive: true });
2141
2204
  writeAtomicJson(statusPath, statusPayload);
2205
+ updateActiveRunIndex(asyncDir, statusPayload.state);
2142
2206
  let pendingParallelUsageCost: CostSummary = { inputTokens: 0, outputTokens: 0, costUsd: 0 };
2143
2207
  const currentUsageTotals = (): CostSummary => {
2144
2208
  const cost = results.reduce<CostSummary>((sum, result) => ({
@@ -2211,11 +2275,25 @@ async function runSubagent(
2211
2275
  for (const node of graph.nodes) updateNode(node);
2212
2276
  statusPayload.workflowGraph = graph;
2213
2277
  };
2214
- const writeStatusPayload = (): void => {
2278
+ let lastIndexedActiveState = isActiveAsyncState(statusPayload.state);
2279
+ const writeStatusPayloadNow = (): void => {
2215
2280
  refreshWorkflowGraph();
2216
2281
  writeAtomicJson(statusPath, statusPayload);
2282
+ const activeState = isActiveAsyncState(statusPayload.state);
2283
+ if (activeState && activeState !== lastIndexedActiveState) {
2284
+ updateActiveRunIndex(asyncDir, statusPayload.state);
2285
+ }
2286
+ lastIndexedActiveState = activeState;
2217
2287
  emitNestedSelfEvent(statusPayload.state === "running" || statusPayload.state === "queued" ? "subagent.nested.updated" : "subagent.nested.completed");
2218
2288
  };
2289
+ const statusWriteCoalescer = createFileCoalescer(writeStatusPayloadNow, 100);
2290
+ const writeStatusPayload = (immediate = true): void => {
2291
+ if (immediate || statusPayload.state !== "running" || statusPayload.activityState !== undefined) {
2292
+ if (!statusWriteCoalescer.flush(statusPath)) writeStatusPayloadNow();
2293
+ return;
2294
+ }
2295
+ statusWriteCoalescer.schedule(statusPath);
2296
+ };
2219
2297
  const updateExternalProcess = (index: number, process: ExternalProcessStatus): void => {
2220
2298
  requiredStatusStep(statusPayload, index).externalProcess = process;
2221
2299
  statusPayload.lastUpdate = Date.now();
@@ -2287,7 +2365,7 @@ async function runSubagent(
2287
2365
  const nestedAsyncDir = run.asyncDir ?? resolveNestedAsyncDir(config.nestedRoute.rootRunId, run);
2288
2366
  if (!nestedAsyncDir) continue;
2289
2367
  try {
2290
- deliverInterruptRequest(omitUndefinedProperties({ asyncDir: nestedAsyncDir, pid: run.pid, source: "ancestor-interrupt" }));
2368
+ deliverInterruptRequest({ asyncDir: nestedAsyncDir, source: "ancestor-interrupt" });
2291
2369
  } catch (error) {
2292
2370
  appendJsonl(eventsPath, JSON.stringify({
2293
2371
  type: "subagent.nested.interrupt_failed",
@@ -2742,7 +2820,7 @@ async function runSubagent(
2742
2820
  step.lastActivityAt = now;
2743
2821
  statusPayload.lastActivityAt = now;
2744
2822
  statusPayload.lastUpdate = now;
2745
- writeStatusPayload();
2823
+ writeStatusPayload(false);
2746
2824
  return;
2747
2825
  }
2748
2826
  if (event.type === "tool_execution_start" && event.toolName) {
@@ -2878,7 +2956,7 @@ async function runSubagent(
2878
2956
  statusPayload.lastActivityAt = now;
2879
2957
  statusPayload.lastUpdate = now;
2880
2958
  maybeEmitActiveLongRunning(flatIndex, now);
2881
- writeStatusPayload();
2959
+ writeStatusPayload(false);
2882
2960
  };
2883
2961
  const updateRunnerActivityState = (now: number): boolean => {
2884
2962
  if (!controlConfig.enabled) return false;
@@ -2977,7 +3055,6 @@ async function runSubagent(
2977
3055
  if (stopped || timedOut || interrupted || statusPayload.state !== "running") return;
2978
3056
  stopped = true;
2979
3057
  const now = Date.now();
2980
- statusPayload.state = "stopped";
2981
3058
  statusPayload.stopped = true;
2982
3059
  statusPayload.error = stopMessage;
2983
3060
  currentActivityState = undefined;
@@ -3010,7 +3087,6 @@ async function runSubagent(
3010
3087
  timedOut = true;
3011
3088
  const now = Date.now();
3012
3089
  const message = timeoutMessage ?? "Subagent timed out.";
3013
- statusPayload.state = "failed";
3014
3090
  statusPayload.timedOut = true;
3015
3091
  statusPayload.error = message;
3016
3092
  currentActivityState = undefined;
@@ -3200,6 +3276,9 @@ async function runSubagent(
3200
3276
  throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} materialized ${materialized.parallel.length} items that resolve output to the same path: ${step.parallel.outputPath}. Remove the explicit output path or use an inherited relative agent output so each item can be isolated.`);
3201
3277
  }
3202
3278
  if (materialized.collectedOnEmpty) await validateDynamicCollection(step.collect.outputSchema, materialized.collectedOnEmpty);
3279
+ if (!config.runFanoutBudget) throw new Error("Async runner is missing its run fan-out budget identity.");
3280
+ const runFanoutBudget = claimRunFanoutBatch(config.runFanoutBudget, materialized.parallel.map((_, itemIndex) => `chain[${stepIndex}].expand[${itemIndex}]`));
3281
+ statusPayload.runFanoutBudget = runFanoutBudget;
3203
3282
  } catch (error) {
3204
3283
  const now = Date.now();
3205
3284
  const message = error instanceof DynamicFanoutError ? error.message : error instanceof Error ? error.message : String(error);
@@ -3306,6 +3385,7 @@ async function runSubagent(
3306
3385
  const materializedTask = step.parallel.namespaceOutputPath ? injectSingleOutputInstruction(taskText, outputPath, step.parallel) : taskText;
3307
3386
  return omitUndefinedProperties({
3308
3387
  ...step.parallel,
3388
+ runFanoutPath: `chain[${stepIndex}].expand[${itemIndex}]`,
3309
3389
  task: materializedTask,
3310
3390
  effectiveAcceptance: resolveEffectiveAcceptance(omitUndefinedProperties({
3311
3391
  explicit: step.parallel.acceptanceInput,
@@ -3449,7 +3529,7 @@ async function runSubagent(
3449
3529
  writeStatusPayload();
3450
3530
  appendJsonl(eventsPath, JSON.stringify({ type: "subagent.step.started", ts: taskStartTime, runId: id, stepIndex: fi, agent: task.agent }));
3451
3531
  flushPendingStepSteers(fi);
3452
- const singleResult = await runSingleStep(task, compactOptional<SingleStepContext>({
3532
+ const singleResult = await runSingleStepWithTimeout(task, compactOptional<SingleStepContext>({
3453
3533
  previousOutput, placeholder, cwd, sessionEnabled,
3454
3534
  outputs,
3455
3535
  sessionDir: config.sessionDir ? path.join(config.sessionDir, `dynamic-${stepIndex}-${taskIdx}`) : undefined,
@@ -3465,6 +3545,7 @@ async function runSubagent(
3465
3545
  orchestratorIntercomTarget: config.controlIntercomTarget,
3466
3546
  nestedRoute: config.nestedRoute,
3467
3547
  capabilityCeiling: config.capabilityCeiling,
3548
+ runFanoutBudget: config.runFanoutBudget,
3468
3549
  registerInterrupt: (interrupt) => registerStepInterrupt(fi, interrupt),
3469
3550
  registerTimeout: (interrupt) => registerStepTimeout(fi, interrupt),
3470
3551
  registerStop: (stop) => registerStepStop(fi, stop),
@@ -3479,7 +3560,7 @@ async function runSubagent(
3479
3560
  onWriterProcess,
3480
3561
  onExternalProcess: (process) => updateExternalProcess(fi, process),
3481
3562
  skipAcceptance: () => timedOut || stopped,
3482
- }));
3563
+ }), config.deadlineAt);
3483
3564
  const taskEndTime = Date.now();
3484
3565
  const childInterrupted = singleResult.interrupted === true;
3485
3566
  const childStopped = singleResult.stopped === true;
@@ -3831,7 +3912,7 @@ async function runSubagent(
3831
3912
  const { taskForRun, taskCwd } = prepareParallelTaskRun(task, cwd, worktreeSetup, taskIdx);
3832
3913
  flushPendingStepSteers(fi);
3833
3914
 
3834
- const singleResult = await runSingleStep(taskForRun, compactOptional<SingleStepContext>({
3915
+ const singleResult = await runSingleStepWithTimeout(taskForRun, compactOptional<SingleStepContext>({
3835
3916
  previousOutput, placeholder, cwd: taskCwd, sessionEnabled,
3836
3917
  outputs,
3837
3918
  sessionDir: taskSessionDir,
@@ -3847,6 +3928,7 @@ async function runSubagent(
3847
3928
  orchestratorIntercomTarget: config.controlIntercomTarget,
3848
3929
  nestedRoute: config.nestedRoute,
3849
3930
  capabilityCeiling: config.capabilityCeiling,
3931
+ runFanoutBudget: config.runFanoutBudget,
3850
3932
  registerInterrupt: (interrupt) => registerStepInterrupt(fi, interrupt),
3851
3933
  registerTimeout: (interrupt) => registerStepTimeout(fi, interrupt),
3852
3934
  registerStop: (stop) => registerStepStop(fi, stop),
@@ -3861,7 +3943,7 @@ async function runSubagent(
3861
3943
  onWriterProcess,
3862
3944
  onExternalProcess: (process) => updateExternalProcess(fi, process),
3863
3945
  skipAcceptance: () => timedOut || stopped,
3864
- }));
3946
+ }), config.deadlineAt);
3865
3947
  if (task.sessionFile) {
3866
3948
  latestSessionFile = task.sessionFile;
3867
3949
  }
@@ -4120,7 +4202,7 @@ async function runSubagent(
4120
4202
  }));
4121
4203
 
4122
4204
  flushPendingStepSteers(flatIndex);
4123
- const singleResult = await runSingleStep(seqStep, compactOptional<SingleStepContext>({
4205
+ const singleResult = await runSingleStepWithTimeout(seqStep, compactOptional<SingleStepContext>({
4124
4206
  previousOutput, placeholder, cwd, sessionEnabled,
4125
4207
  outputs: statusPayload.mode === "single" ? undefined : outputs,
4126
4208
  sessionDir: config.sessionDir,
@@ -4136,6 +4218,7 @@ async function runSubagent(
4136
4218
  orchestratorIntercomTarget: config.controlIntercomTarget,
4137
4219
  nestedRoute: config.nestedRoute,
4138
4220
  capabilityCeiling: config.capabilityCeiling,
4221
+ runFanoutBudget: config.runFanoutBudget,
4139
4222
  registerInterrupt: (interrupt) => registerStepInterrupt(flatIndex, interrupt),
4140
4223
  registerTimeout: (interrupt) => registerStepTimeout(flatIndex, interrupt),
4141
4224
  registerStop: (stop) => registerStepStop(flatIndex, stop),
@@ -4150,7 +4233,7 @@ async function runSubagent(
4150
4233
  onWriterProcess,
4151
4234
  onExternalProcess: (process) => updateExternalProcess(flatIndex, process),
4152
4235
  skipAcceptance: () => timedOut || stopped,
4153
- }));
4236
+ }), config.deadlineAt);
4154
4237
  if (seqStep.sessionFile) {
4155
4238
  latestSessionFile = seqStep.sessionFile;
4156
4239
  }
@@ -4380,6 +4463,9 @@ async function runSubagent(
4380
4463
  clearTimeout(timeoutTimer);
4381
4464
  timeoutTimer = undefined;
4382
4465
  }
4466
+ if (!timedOut && !stopped && !interrupted && config.timeoutMs !== undefined && results.some((result) => result.timedOut === true && result.error === timeoutMessage)) {
4467
+ timedOut = true;
4468
+ }
4383
4469
  const signalTerminated = !stopped && !timedOut && !turnBudgetExceeded && !interrupted && results.some((result) => result.exitCode !== 0 && isUnexplainedProcessSignal(omitUndefinedProperties({
4384
4470
  processSignal: result.processSignal,
4385
4471
  interrupted: result.interrupted,
@@ -4439,6 +4525,7 @@ async function runSubagent(
4439
4525
  statusPayload.error = `Step failed: ${failedStep.agent}`;
4440
4526
  }
4441
4527
  }
4528
+ writeStatusPayload();
4442
4529
  try {
4443
4530
  writeAtomicJson(resultPath, {
4444
4531
  lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
@@ -4571,7 +4658,7 @@ async function runSubagent(
4571
4658
  shareError,
4572
4659
  }));
4573
4660
  if (config.runnerProcessInstanceId) {
4574
- const writers: Record<string, Array<{ processInstanceId: string; kind: "pi-writer"; attempt: number; closeObservedAt: number; exitCode: number | null; signal: string | null }>> = {};
4661
+ const writers: Record<string, PiWriterProcessInstanceExitV1[]> = {};
4575
4662
  const expectedWriters: Record<string, number> = {};
4576
4663
  for (const [index, result] of results.entries()) {
4577
4664
  writers[String(index)] = result.writerProcesses ?? [];
@@ -4592,7 +4679,6 @@ async function runSubagent(
4592
4679
  console.error(`Failed to write process-terminal candidate for '${id}':`, error);
4593
4680
  }
4594
4681
  }
4595
- writeStatusPayload();
4596
4682
  }
4597
4683
 
4598
4684
  async function waitForStartupControl(
@@ -62,6 +62,7 @@ import {
62
62
  } from "../../shared/types.ts";
63
63
  import { formatDuration, shortenPath } from "../../shared/formatters.ts";
64
64
  import { collectWaitCompletions } from "./wait-completions.ts";
65
+ import { formatResumeFirstFailedRunsNote } from "./resume-guidance.ts";
65
66
  export { WAIT_TOOL_ENABLED_ENV, resolveWaitToolConfig, type ResolvedWaitToolConfig } from "./wait-config.ts";
66
67
 
67
68
  /** States that mean a run is still in flight (not yet resolved). */
@@ -604,6 +605,7 @@ export async function waitForSubagents(
604
605
  let finishedAsyncCount: number;
605
606
  let failedAsyncCount: number;
606
607
  let completions: WaitCompletion[] | undefined;
608
+ let resumeGuidance = "";
607
609
  const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
608
610
  const providerFinishedCount = [...initialProviderIds].filter((id) => !activeProviderIds.has(id)).length;
609
611
  try {
@@ -612,6 +614,7 @@ export async function waitForSubagents(
612
614
  finishedAsyncCount = terminal.length;
613
615
  failedAsyncCount = terminal.filter((run) => run.state === "failed").length;
614
616
  terminalSummary = summarizeTerminalRuns(terminal, providerFinishedCount);
617
+ resumeGuidance = formatResumeFirstFailedRunsNote(terminal);
615
618
  completions = collectWaitCompletions(terminal, deps.state, deps.resultsDir ?? DIRS.results);
616
619
  } catch (error) {
617
620
  return result(error instanceof Error ? error.message : String(error), true);
@@ -637,7 +640,7 @@ export async function waitForSubagents(
637
640
  : `${initialAsyncIds.size} async run(s) and ${initialProviderIds.size} provider item(s)`;
638
641
  const status = relevantAttention.length > 0 ? "attention required" : "done";
639
642
  return result(
640
- `Waited ${elapsed} for ${scope}; ${status}.${outcome}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
643
+ `Waited ${elapsed} for ${scope}; ${status}.${outcome}${resumeGuidance}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
641
644
  deps.failOnFailedRuns === true && failedAsyncCount > 0,
642
645
  completions,
643
646
  );
@@ -654,7 +657,7 @@ export async function waitForSubagents(
654
657
  ? `${relevantAttention.length} of ${initialCount} ${subject} need attention`
655
658
  : `${finishedCount} of ${initialCount} ${subject} finished`;
656
659
  return result(
657
- `Waited ${elapsed}; ${progress}.${outcome}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`,
660
+ `Waited ${elapsed}; ${progress}.${outcome}${resumeGuidance}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`,
658
661
  deps.failOnFailedRuns === true && failedAsyncCount > 0,
659
662
  completions,
660
663
  );
@@ -2,6 +2,7 @@ import * as fs from "node:fs";
2
2
  import * as path from "node:path";
3
3
  import type { ArtifactPaths, SubagentState, WaitCompletion, WaitCompletionChild } from "../../shared/types.ts";
4
4
  import type { AsyncRunSummary } from "./async-status.ts";
5
+ import { readCompletionReplay, writeCompletionReplay } from "./completion-replay.ts";
5
6
 
6
7
  function asNonEmptyString(value: unknown): string | undefined {
7
8
  return typeof value === "string" && value ? value : undefined;
@@ -68,12 +69,34 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
68
69
  * file is deleted after delivery, so this record is the only in-process source once
69
70
  * the watcher has consumed it.
70
71
  */
71
- export function recordWaitCompletion(state: SubagentState, runId: string, data: Record<string, unknown>, now: number, ttlMs: number): void {
72
+ export function recordWaitCompletion(
73
+ state: SubagentState,
74
+ runId: string,
75
+ data: Record<string, unknown>,
76
+ now: number,
77
+ ttlMs: number,
78
+ persistence?: { resultsDir: string; sessionId: string },
79
+ ): void {
72
80
  const store = state.completedResults ??= new Map();
73
81
  for (const [key, entry] of store) {
74
82
  if (now - entry.seenAt > ttlMs) store.delete(key);
75
83
  }
76
- store.set(runId, { seenAt: now, completion: toWaitCompletion(data, runId) });
84
+ let completion = toWaitCompletion(data, runId);
85
+ if (persistence) {
86
+ try {
87
+ completion = writeCompletionReplay({
88
+ ...persistence,
89
+ runId,
90
+ completion,
91
+ data,
92
+ now,
93
+ ttlMs,
94
+ }).completion;
95
+ } catch (error) {
96
+ console.error(`Failed to persist completion replay for '${runId}':`, error);
97
+ }
98
+ }
99
+ store.set(runId, { seenAt: now, completion });
77
100
  }
78
101
 
79
102
  /**
@@ -102,10 +125,21 @@ export function collectWaitCompletions(terminal: AsyncRunSummary[], state: Subag
102
125
  });
103
126
  }
104
127
  // The watcher may have consumed the file between the store check and the
105
- // read; its record is authoritative when present, otherwise the payload
106
- // is gone and the text summary remains the only surface for this run.
128
+ // read. Prefer its in-memory record, then the durable replay written before
129
+ // result cleanup so watcher reloads do not lose completion details.
107
130
  const late = state.completedResults?.get(run.id);
108
- if (late) completions.push(late.completion);
131
+ if (late) {
132
+ completions.push(late.completion);
133
+ continue;
134
+ }
135
+ try {
136
+ const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
137
+ if (replay) completions.push(replay.completion);
138
+ } catch (replayError) {
139
+ throw new Error(`Failed to read completion replay for '${run.id}': ${errorMessage(replayError)}`, {
140
+ cause: replayError instanceof Error ? replayError : undefined,
141
+ });
142
+ }
109
143
  }
110
144
  }
111
145
  return completions.length > 0 ? completions : undefined;