@xzzpig/pi-subagents 0.20.0 → 0.22.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 (144) hide show
  1. package/CHANGELOG.md +164 -0
  2. package/README.md +1 -1
  3. package/agents/oracle.md +8 -19
  4. package/agents/researcher.md +0 -3
  5. package/agents/reviewer.md +17 -61
  6. package/agents/scout.md +1 -4
  7. package/agents/worker.md +8 -25
  8. package/docs/agents.md +72 -7
  9. package/docs/configuration.md +58 -7
  10. package/docs/extension-api.md +36 -11
  11. package/docs/fork-extensions.md +1 -0
  12. package/docs/fork-supervisor-routing.md +77 -0
  13. package/docs/missions.md +34 -17
  14. package/docs/models.md +1 -1
  15. package/docs/observability.md +10 -5
  16. package/docs/tool-reference.md +117 -84
  17. package/docs/watchdog.md +8 -6
  18. package/docs/workflows.md +16 -7
  19. package/index.ts +5 -0
  20. package/package.json +6 -3
  21. package/prompts/council.md +1 -1
  22. package/skills/pi-subagents/SKILL.md +1 -1
  23. package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
  24. package/skills/pi-subagents/references/execution-controls.md +16 -16
  25. package/skills/pi-subagents/references/management-authoring-rpc.md +16 -12
  26. package/skills/pi-subagents/references/prompting-and-roles.md +3 -3
  27. package/src/agents/advertised-agent-prompt.ts +9 -1
  28. package/src/agents/agent-management.ts +4 -0
  29. package/src/agents/agent-memory.ts +3 -3
  30. package/src/agents/agent-scope.ts +4 -0
  31. package/src/agents/agent-serializer.ts +8 -1
  32. package/src/agents/agents.ts +191 -145
  33. package/src/api/preflight.ts +8 -4
  34. package/src/api/supervisor-routing.ts +196 -0
  35. package/src/extension/config.ts +21 -2
  36. package/src/extension/context-injection.ts +6 -1
  37. package/src/extension/control-notices.ts +1 -9
  38. package/src/extension/declaration-pinning.ts +164 -0
  39. package/src/extension/doctor.ts +7 -10
  40. package/src/extension/fanout-child.ts +7 -8
  41. package/src/extension/index.ts +143 -134
  42. package/src/extension/reply-workflow-script.ts +20 -11
  43. package/src/extension/rpc.ts +11 -6
  44. package/src/extension/schemas.ts +34 -30
  45. package/src/extension/subagent-guide.ts +86 -6
  46. package/src/extension/subagent-options.ts +47 -0
  47. package/src/extension/tool-activation.ts +3 -2
  48. package/src/extension/tool-description.ts +51 -68
  49. package/src/inspectors/actions.ts +37 -11
  50. package/src/inspectors/plugins.ts +3 -2
  51. package/src/inspectors/tmux/actions.ts +204 -0
  52. package/src/inspectors/tmux/client.ts +85 -0
  53. package/src/inspectors/tmux/plugin.ts +21 -0
  54. package/src/integrations/herdr-status.ts +18 -49
  55. package/src/integrations/program-status.ts +215 -0
  56. package/src/intercom/fork-supervisor-routing.ts +533 -0
  57. package/src/intercom/native-supervisor-channel.ts +152 -13
  58. package/src/intercom/result-intercom.ts +3 -2
  59. package/src/intercom/supervisor-ui.ts +2 -174
  60. package/src/missions/store.ts +25 -5
  61. package/src/profiles/profiles.ts +24 -21
  62. package/src/runs/background/active-async-capacity.ts +58 -8
  63. package/src/runs/background/async-execution.ts +143 -38
  64. package/src/runs/background/async-job-tracker.ts +11 -4
  65. package/src/runs/background/async-resume.ts +5 -2
  66. package/src/runs/background/await-async-run.ts +14 -9
  67. package/src/runs/background/binary-bootstrap.ts +2 -1
  68. package/src/runs/background/calendar-schedule.ts +90 -0
  69. package/src/runs/background/chain-root-attachment.ts +9 -5
  70. package/src/runs/background/fleet-view.ts +5 -5
  71. package/src/runs/background/notify.ts +185 -12
  72. package/src/runs/background/result-files.ts +116 -5
  73. package/src/runs/background/result-watcher.ts +99 -66
  74. package/src/runs/background/resume-guidance.ts +2 -2
  75. package/src/runs/background/run-child-session.ts +16 -2
  76. package/src/runs/background/run-id-resolver.ts +8 -5
  77. package/src/runs/background/run-status.ts +21 -16
  78. package/src/runs/background/runner-child-launch.ts +1 -0
  79. package/src/runs/background/runner-http-dispatcher.ts +3 -0
  80. package/src/runs/background/scheduled-runs.ts +256 -61
  81. package/src/runs/background/subagent-runner-bootstrap.ts +4 -1
  82. package/src/runs/background/subagent-runner.ts +32 -12
  83. package/src/runs/background/subagent-wait.ts +38 -19
  84. package/src/runs/background/terminal-run-index.ts +46 -1
  85. package/src/runs/background/wait-completions.ts +1 -0
  86. package/src/runs/background/wait-tool.ts +33 -23
  87. package/src/runs/background/workflow-terminal-proof.ts +39 -22
  88. package/src/runs/foreground/async-stop-action.ts +48 -22
  89. package/src/runs/foreground/execution.ts +94 -52
  90. package/src/runs/foreground/foreground-history.ts +1 -0
  91. package/src/runs/foreground/subagent-executor.ts +232 -77
  92. package/src/runs/shared/child-commands.ts +2 -1
  93. package/src/runs/shared/child-hooks.ts +4 -3
  94. package/src/runs/shared/child-launch.ts +3 -0
  95. package/src/runs/shared/child-session.ts +41 -24
  96. package/src/runs/shared/child-tool-plan.ts +13 -26
  97. package/src/runs/shared/dynamic-fanout.ts +1 -1
  98. package/src/runs/shared/fork-command-result.ts +10 -0
  99. package/src/runs/shared/herdr-placed-run.ts +5 -4
  100. package/src/runs/shared/mcp-direct-tool-allowlist.ts +5 -3
  101. package/src/runs/shared/model-resolution-diagnostic.ts +25 -0
  102. package/src/runs/shared/model-resolution.ts +30 -1
  103. package/src/runs/shared/nested-events.ts +5 -0
  104. package/src/runs/shared/parallel-handoff.ts +56 -8
  105. package/src/runs/shared/parallel-utils.ts +2 -0
  106. package/src/runs/shared/partial-output.ts +48 -0
  107. package/src/runs/shared/runner-launcher.ts +25 -0
  108. package/src/runs/shared/single-output.ts +53 -0
  109. package/src/runs/shared/structured-output.ts +14 -7
  110. package/src/runs/shared/subagent-control.ts +3 -3
  111. package/src/runs/shared/subagent-prompt-runtime.ts +47 -24
  112. package/src/runs/shared/workflow-async-child-guidance.ts +1 -1
  113. package/src/runs/shared/worktree-cleanup-apply.ts +160 -0
  114. package/src/runs/shared/worktree-cleanup-plan.ts +41 -19
  115. package/src/runs/shared/worktree-lock.ts +29 -0
  116. package/src/runs/shared/worktree.ts +12 -1
  117. package/src/shared/atomic-json.ts +4 -2
  118. package/src/shared/edit-distance.ts +33 -0
  119. package/src/shared/file-lease.ts +74 -0
  120. package/src/shared/formatters.ts +1 -5
  121. package/src/shared/model-info.ts +22 -0
  122. package/src/shared/package-version.ts +17 -0
  123. package/src/shared/parent-wake.ts +79 -0
  124. package/src/shared/pruned-fork.ts +7 -1
  125. package/src/shared/runtime-module-path.ts +19 -0
  126. package/src/shared/settings-file-lease.ts +36 -0
  127. package/src/shared/types.ts +36 -2
  128. package/src/shared/utils.ts +8 -6
  129. package/src/slash/prompt-template-bridge.ts +21 -20
  130. package/src/slash/slash-commands.ts +3 -3
  131. package/src/slash/subagents-admin.ts +2 -1
  132. package/src/tui/fleet-native-transcript.ts +2 -0
  133. package/src/tui/fleet-transcript.ts +12 -3
  134. package/src/tui/fleet.ts +11 -8
  135. package/src/tui/render.ts +27 -19
  136. package/src/tui/subagent-messages.ts +305 -0
  137. package/src/watchdog/diff-tool.ts +2 -2
  138. package/src/watchdog/register-main.ts +2 -22
  139. package/src/watchdog/render.ts +2 -24
  140. package/src/watchdog/runtime.ts +6 -4
  141. package/src/watchdog/settings.ts +18 -13
  142. package/src/watchdog/tool-actions.ts +2 -2
  143. package/src/workflows/scripted-workflow.ts +20 -6
  144. package/src/workflows/workflow-resources.ts +11 -0
@@ -1,6 +1,8 @@
1
+ import { createHash } from "node:crypto";
1
2
  import * as fs from "node:fs";
2
3
  import * as path from "node:path";
3
4
  import { writeAtomicJson } from "../../shared/atomic-json.ts";
5
+ import { withFileLease } from "../../shared/file-lease.ts";
4
6
  import { MISSION_BINDING_FILE } from "../../missions/lifecycle.ts";
5
7
  import { encodeIndexSegment, indexSegmentAliases, MAX_INDEX_SEGMENT_BYTES } from "./index-segment.ts";
6
8
 
@@ -11,6 +13,7 @@ const RUN_INDEX_DIR = "runs";
11
13
  const OBSERVER_INDEX_DIR = "observers";
12
14
  const TOOL_CALL_INDEX_DIR = "tool-calls";
13
15
  const RESULT_PENDING_DIR = "result-pending";
16
+ const RESULT_LEASE_DIR = "result-leases";
14
17
  const MISSION_OBSERVER = "mission";
15
18
  const JSON_EXTENSION = ".json";
16
19
  const MAX_JSON_FILE_STEM_BYTES = MAX_INDEX_SEGMENT_BYTES - Buffer.byteLength(JSON_EXTENSION, "utf-8");
@@ -166,8 +169,18 @@ function writeIndexedPendingResultFile(resultPath: string, data: Record<string,
166
169
  const sessionId = nonEmptyString(data.sessionId);
167
170
  if (!sessionId) throw new Error(`Cannot write async result '${resultPath}' without a sessionId.`);
168
171
  const resultsDir = path.dirname(resultPath);
169
- writeAtomicJson(resultPendingPath(resultsDir, sessionId, runId), data);
170
- writeResultIndexForData(resultPath, data);
172
+ // A consumer can take the payload and remove its indexes as soon as the payload appears,
173
+ // so every index must exist before then. A failed index write still publishes the
174
+ // payload, unindexed but recoverable, before the error is rethrown.
175
+ let indexFailure: { error: unknown } | undefined;
176
+ writeAtomicJson(resultPendingPath(resultsDir, sessionId, runId), data, () => {
177
+ try {
178
+ writeResultIndexForData(resultPath, data);
179
+ } catch (error) {
180
+ indexFailure = { error };
181
+ }
182
+ });
183
+ if (indexFailure) throw indexFailure.error;
171
184
  return { runId, sessionId, resultsDir };
172
185
  }
173
186
 
@@ -228,6 +241,99 @@ export function removeMissionObserverIndex(resultsDir: string, runId: string | u
228
241
  }
229
242
  }
230
243
 
244
+ /** Serializes one run's result publication and retirement across processes. Lookups never take it. */
245
+ export function withResultRunLease<T>(resultsDir: string, runId: string, action: () => T): T {
246
+ const leaseDir = path.join(resultsDir, RESULT_LEASE_DIR);
247
+ fs.mkdirSync(leaseDir, { recursive: true });
248
+ return withFileLease(path.join(leaseDir, createHash("sha256").update(runId).digest("hex")), action);
249
+ }
250
+
251
+ /**
252
+ * The exact payload text a consumer read, with the identity its indexes are keyed by.
253
+ * `stalePublic` is what the public path held, read just before `snapshot`, when it differed:
254
+ * every writer goes through the pending path and promotion empties it, so a pending payload is
255
+ * always newer than the public one beside it, and `stalePublic` is older than `snapshot`.
256
+ */
257
+ export interface ResultSnapshot {
258
+ runId: string;
259
+ sessionId?: string;
260
+ toolCallId?: string;
261
+ snapshot: string;
262
+ stalePublic?: string;
263
+ }
264
+
265
+ export function readResultPayload(filePath: string): string | undefined {
266
+ try {
267
+ return fs.readFileSync(filePath, "utf-8");
268
+ } catch (error) {
269
+ const code = (error as NodeJS.ErrnoException).code;
270
+ // A directory at the public path blocks promotion; it holds no payload.
271
+ if (code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR" || isUnaddressableResultCandidate(error)) return undefined;
272
+ throw error;
273
+ }
274
+ }
275
+
276
+ // Pending paths come first so a reader promoting pending to public between two reads is still seen.
277
+ function resultPayloadCandidates(publicPath: string, read: ResultSnapshot): string[] {
278
+ return [...(read.sessionId ? resultPendingPaths(path.dirname(publicPath), read.sessionId, read.runId) : []), publicPath];
279
+ }
280
+
281
+ /** A payload is one the consumer already read (or an older one it saw beside it), so not newer. */
282
+ function readByConsumer(publicPath: string, read: ResultSnapshot, candidate: string, current: string): boolean {
283
+ return current === read.snapshot || (candidate === publicPath && current === read.stalePublic);
284
+ }
285
+
286
+ /** Call under the run's lease: whether a payload written after the consumer read now exists for the run. */
287
+ export function resultSnapshotReplaced(publicPath: string, read: ResultSnapshot): boolean {
288
+ return resultPayloadCandidates(publicPath, read).some((candidate) => {
289
+ const current = readResultPayload(candidate);
290
+ return current !== undefined && !readByConsumer(publicPath, read, candidate, current);
291
+ });
292
+ }
293
+
294
+ /**
295
+ * Removes the payload a consumer read, the older public payload it saw beside it, and the run's
296
+ * indexes. When a newer payload replaced it, the shared payload paths and indexes stay and only
297
+ * the consumer's own claimed copy goes. A payload that cannot be removed is reported after the
298
+ * indexes are gone.
299
+ */
300
+ export function retireResultSnapshot(publicPath: string, read: ResultSnapshot, payloadPath = publicPath): "retired" | "replaced" {
301
+ const resultsDir = path.dirname(publicPath);
302
+ return withResultRunLease(resultsDir, read.runId, () => {
303
+ // Check every shared path before deleting any: unleased reader promotion can move a newer
304
+ // pending payload onto the public path between two deletions.
305
+ if (resultSnapshotReplaced(publicPath, read)) {
306
+ if (payloadPath !== publicPath && readResultPayload(payloadPath) === read.snapshot) fs.rmSync(payloadPath, { force: true });
307
+ return "replaced";
308
+ }
309
+ let removalFailure: { error: unknown } | undefined;
310
+ for (const candidate of new Set([...resultPayloadCandidates(publicPath, read), payloadPath])) {
311
+ const current = readResultPayload(candidate);
312
+ if (current === undefined || !readByConsumer(publicPath, read, candidate, current)) continue;
313
+ try {
314
+ fs.rmSync(candidate, { force: true });
315
+ } catch (error) {
316
+ removalFailure ??= { error };
317
+ }
318
+ }
319
+ removeResultIndex(resultsDir, read.sessionId, read.runId, read.toolCallId);
320
+ if (removalFailure) throw removalFailure.error;
321
+ return "retired";
322
+ });
323
+ }
324
+
325
+ /** Removes the mission observer index for the payload an observer handled, unless a newer payload replaced it. */
326
+ export function acknowledgeMissionObserverSnapshot(publicPath: string, read: ResultSnapshot): "acknowledged" | "replaced" {
327
+ const resultsDir = path.dirname(publicPath);
328
+ // With no index there is nothing to remove; skipping keeps the lease off runs without a mission.
329
+ if (!fs.existsSync(observerIndexPath(resultsDir, MISSION_OBSERVER, read.runId))) return "acknowledged";
330
+ return withResultRunLease(resultsDir, read.runId, () => {
331
+ if (resultSnapshotReplaced(publicPath, read)) return "replaced";
332
+ removeMissionObserverIndex(resultsDir, read.runId);
333
+ return "acknowledged";
334
+ });
335
+ }
336
+
231
337
  function existingResultFile(resultPath: string): boolean {
232
338
  try {
233
339
  return fs.statSync(resultPath).isFile();
@@ -307,6 +413,11 @@ export function fallbackResultPayloadPathForSessionRun(resultsDir: string, sessi
307
413
  return pendingPath;
308
414
  }
309
415
 
416
+ /** Any pending or public result file for the run, without validating its contents. */
417
+ export function resultPayloadFileForSessionRun(resultsDir: string, sessionId: string, runId: string): string | undefined {
418
+ return firstExistingResultFile([...resultPendingPaths(resultsDir, sessionId, runId), resultFilePath(resultsDir, runId)]);
419
+ }
420
+
310
421
  function resultPayloadLocationFromIndex(resultsDir: string, entry: ResultIndexEntry): ResultPayloadLocation | undefined {
311
422
  if (entry.file !== path.basename(entry.file) || !entry.file.endsWith(".json")) return undefined;
312
423
  const pendingState = promotePendingResultFile(resultsDir, entry.sessionId, entry.runId, entry.file);
@@ -361,9 +472,9 @@ export function resultPayloadPathForIndexedRun(resultsDir: string, runId: string
361
472
  fs.rmSync(entryPath, { force: true });
362
473
  return undefined;
363
474
  }
364
- const location = resultPayloadLocationFromIndex(resultsDir, entry);
365
- if (location) return location.path;
366
- fs.rmSync(entryPath, { force: true });
475
+ // A valid index can precede its payload while the writer is publishing it, so a lookup
476
+ // must not delete it. Payload-less indexes are swept by age in cleanupResultIndexes.
477
+ return resultPayloadLocationFromIndex(resultsDir, entry)?.path;
367
478
  } catch (error) {
368
479
  const code = (error as NodeJS.ErrnoException).code;
369
480
  if (isUnaddressableResultCandidate(error)) return undefined;
@@ -23,7 +23,7 @@ import { projectNestedRegistryForRoot, sanitizeSummary } from "../shared/nested-
23
23
  import { resolveWatchPath } from "../../shared/utils.ts";
24
24
  import { recordWaitCompletion } from "./wait-completions.ts";
25
25
  import { MISSION_BINDING_FILE, syncMissionFromAsyncCompletion } from "../../missions/lifecycle.ts";
26
- import { missionObserverResultCandidateFiles, promotePendingResultFile, removeMissionObserverIndex, removeResultIndex, resultCandidateFilesForSession, resultPayloadPathForIndexedRun, resultPayloadPathForMissionObserverRun, resultPayloadPathForSessionRun, writeAsyncResultFile, writeResultIndexForData } from "./result-files.ts";
26
+ import { acknowledgeMissionObserverSnapshot, missionObserverResultCandidateFiles, promotePendingResultFile, readResultPayload, resultCandidateFilesForSession, resultPayloadPathForIndexedRun, resultPayloadPathForMissionObserverRun, resultPayloadPathForSessionRun, resultSnapshotReplaced, retireResultSnapshot, withResultRunLease, writeAsyncResultFile, writeResultIndexForData, type ResultSnapshot } from "./result-files.ts";
27
27
  import type { CompletionNotifier, CompletionNotification } from "./notify.ts";
28
28
  import type { ResultDeliveryOwnership } from "./result-delivery-ownership.ts";
29
29
 
@@ -45,7 +45,7 @@ type ResultWatcherTimers = {
45
45
  type ResultWatcherDeps = {
46
46
  fs?: ResultWatcherFs;
47
47
  timers?: ResultWatcherTimers;
48
- notifier?: Pick<CompletionNotifier, "deliver">;
48
+ notifier?: Pick<CompletionNotifier, "deliver"> & Partial<Pick<CompletionNotifier, "flush">>;
49
49
  /** Receives persisted completions before active-session delivery filtering. */
50
50
  observeCompletion?: (result: CompletionNotification & { runId: string }) => void;
51
51
  /** Returns cross-session run ids that the completion observer currently owns. */
@@ -63,6 +63,8 @@ type ResultWatcherDeps = {
63
63
  platform?: NodeJS.Platform;
64
64
  /** Shared current/predecessor session ownership used by the notifier. */
65
65
  ownership?: Pick<ResultDeliveryOwnership, "owns" | "claimedSessionIds">;
66
+ /** Called once the parent has this run's result: the notifier accepted it, or an earlier delivery already did. */
67
+ onResultDelivered?: (runId: string) => void;
66
68
  };
67
69
 
68
70
  type ResultFileChild = {
@@ -72,6 +74,7 @@ type ResultFileChild = {
72
74
  structuredOutput?: unknown;
73
75
  structuredOutputPath?: string;
74
76
  outputState?: SubagentOutputState;
77
+ outputPartial?: boolean;
75
78
  error?: string;
76
79
  success?: boolean;
77
80
  state?: string;
@@ -173,25 +176,18 @@ function hasDeliveredNotification(data: ResultFileData): boolean {
173
176
  return typeof data.notificationDeliveredAt === "number" && Number.isFinite(data.notificationDeliveredAt);
174
177
  }
175
178
 
176
- type PublicResultIdentity = {
177
- state?: string;
178
- timestamp?: number;
179
- };
180
-
181
- function resultPayloadWasReplaced(delivered: ResultFileData, disk: PublicResultIdentity | undefined): boolean {
182
- if (!disk) return false;
183
- const deliveredState = typeof delivered.state === "string" ? delivered.state : undefined;
184
- if (disk.state && deliveredState && disk.state !== deliveredState) return true;
185
- const deliveredTimestamp = typeof delivered.timestamp === "number" && Number.isFinite(delivered.timestamp)
186
- ? delivered.timestamp
187
- : undefined;
188
- return disk.timestamp !== undefined && deliveredTimestamp !== undefined && disk.timestamp !== deliveredTimestamp;
189
- }
190
-
191
- function markDeliveredNotification(resultPath: string, data: ResultFileData, runId: string, now: number): ResultFileData {
192
- const marked = { ...data, runId, notificationDeliveredAt: now };
193
- writeAsyncResultFile(resultPath, marked);
194
- return marked;
179
+ /** Marks the payload that was delivered, unless a newer payload replaced it (then returns undefined). */
180
+ function markDeliveredNotification(resultPath: string, data: ResultFileData, read: ResultSnapshot, now: number): { data: ResultFileData; read: ResultSnapshot } | undefined {
181
+ const marked = { ...data, runId: read.runId, notificationDeliveredAt: now };
182
+ return withResultRunLease(path.dirname(resultPath), read.runId, () => {
183
+ if (resultSnapshotReplaced(resultPath, read)) return undefined;
184
+ const { state } = writeAsyncResultFile(resultPath, marked);
185
+ // writeAsyncResultFile writes JSON.stringify(payload, null, 2). A denied promotion leaves the
186
+ // older public payload in place.
187
+ const snapshot = JSON.stringify(marked, null, 2);
188
+ const stalePublic = state === "pending" ? readResultPayload(resultPath) : undefined;
189
+ return { data: marked, read: { ...read, snapshot, stalePublic } };
190
+ });
195
191
  }
196
192
 
197
193
  /**
@@ -209,6 +205,7 @@ export function createResultWatcher(
209
205
  startResultWatcher: () => void;
210
206
  transitionResultDelivery: () => void;
211
207
  primeExistingResults: (options?: { triggerTurn?: boolean }) => void;
208
+ deliverPendingResults: () => Promise<void>;
212
209
  refreshResultDelivery: () => void;
213
210
  stopResultWatcher: () => void;
214
211
  } {
@@ -219,6 +216,9 @@ export function createResultWatcher(
219
216
  const deliverIntercomResults = deps.deliverIntercomResults !== false;
220
217
  const pendingTriggerTurn = new Map<string, boolean>();
221
218
  const processing = new Set<string>();
219
+ const handling = new Set<Promise<void>>();
220
+ // While deliverPendingResults runs, completions skip the batch delay.
221
+ let deliveringPending = 0;
222
222
  const identityCache = new Map<string, { signature: string; identity: ResultFileIdentity }>();
223
223
  let deliveryActive = true;
224
224
  let deliveryEpoch = 0;
@@ -327,18 +327,14 @@ export function createResultWatcher(
327
327
  return Boolean(deps.observeCompletion && !deps.observedCompletionRunIds);
328
328
  };
329
329
 
330
- const removeDeliveredResult = (file: string, sessionId: string, runId: string, toolCallId: string | undefined): boolean => {
330
+ const removeDeliveredResult = (file: string, triggerTurn: boolean, read: ResultSnapshot): void => {
331
+ identityCache.delete(file);
331
332
  try {
332
- if (publicResultFileExists(file)) fsApi.unlinkSync(publicResultPath(file));
333
- identityCache.delete(file);
334
- removeResultIndex(resultsDir, sessionId, runId, toolCallId);
335
- return true;
333
+ if (retireResultSnapshot(publicResultPath(file), read) === "replaced") scheduleResult(file, triggerTurn);
336
334
  } catch (error) {
337
- if (!isAbsentResultCandidate(error)) {
338
- console.error(`Failed to remove delivered subagent result '${publicResultPath(file)}'; will retry:`, error);
339
- return false;
340
- }
341
- return true;
335
+ if (isAbsentResultCandidate(error)) return;
336
+ console.error(`Failed to remove delivered subagent result '${publicResultPath(file)}'; will retry:`, error);
337
+ scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
342
338
  }
343
339
  };
344
340
  const handleResult = async (file: string, triggerTurn: boolean) => {
@@ -359,30 +355,25 @@ export function createResultWatcher(
359
355
  processing.add(file);
360
356
  let rereadReplacedPayload = false;
361
357
  let resultPath = publicResultPath(file);
362
- const readPublicResultIdentity = (): PublicResultIdentity | undefined => {
363
- if (!publicResultFileExists(file)) return undefined;
364
- const parsed: unknown = JSON.parse(fsApi.readFileSync(publicResultPath(file), "utf-8"));
365
- if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
366
- const record = parsed as Record<string, unknown>;
367
- const state = typeof record.state === "string" && record.state ? record.state : undefined;
368
- const timestamp = typeof record.timestamp === "number" && Number.isFinite(record.timestamp)
369
- ? record.timestamp
370
- : undefined;
371
- if (!state && timestamp === undefined) return undefined;
372
- return { state, timestamp };
358
+ // The public payload is read just before the payload itself, so anything published after the
359
+ // read differs from both.
360
+ let publicAtRead: string | undefined;
361
+ const readPayload = (payloadPath: string): string => {
362
+ publicAtRead = readResultPayload(publicResultPath(file));
363
+ return fsApi.readFileSync(payloadPath, "utf-8");
373
364
  };
374
365
  try {
375
366
  const payloadPath = resultPayloadPath(file, observed);
376
367
  if (!payloadPath) return;
377
368
  resultPath = payloadPath;
378
- let raw = fsApi.readFileSync(resultPath, "utf-8");
369
+ let raw = readPayload(resultPath);
379
370
  let identity = resultFileIdentity(raw, file);
380
371
  if (identity.sessionId && identity.runId) {
381
372
  const pendingState = promotePendingResultFile(resultsDir, identity.sessionId, identity.runId, file);
382
373
  if (pendingState === "promoted") {
383
374
  identityCache.delete(file);
384
375
  resultPath = publicResultPath(file);
385
- raw = fsApi.readFileSync(resultPath, "utf-8");
376
+ raw = readPayload(resultPath);
386
377
  identity = resultFileIdentity(raw, file);
387
378
  } else if (pendingState === "pending") {
388
379
  const pendingPath = resultPayloadPathForSessionRun(resultsDir, identity.sessionId, identity.runId);
@@ -391,30 +382,30 @@ export function createResultWatcher(
391
382
  return;
392
383
  }
393
384
  resultPath = pendingPath;
394
- raw = fsApi.readFileSync(resultPath, "utf-8");
385
+ raw = readPayload(resultPath);
395
386
  identity = resultFileIdentity(raw, file);
396
387
  }
397
388
  }
398
389
  let data = parseResult(raw);
390
+ if (typeof data.sessionId !== "string" || !data.sessionId) return;
391
+ const sessionId = data.sessionId;
392
+ const completionOwnerId = data.completionOwnerId;
393
+ const runId = typeof data.runId === "string" && data.runId
394
+ ? data.runId
395
+ : typeof data.id === "string" && data.id ? data.id : file.replace(/\.json$/i, "");
396
+ const toolCallId = typeof data.toolCallId === "string" ? data.toolCallId : undefined;
397
+ let read: ResultSnapshot = { runId, sessionId, toolCallId, snapshot: raw, ...(publicAtRead !== undefined && publicAtRead !== raw ? { stalePublic: publicAtRead } : {}) };
399
398
  const markReplacedPayload = (): boolean => {
400
399
  try {
401
- if (!resultPayloadWasReplaced(data, readPublicResultIdentity())) return false;
400
+ if (!resultSnapshotReplaced(publicResultPath(file), read)) return false;
402
401
  } catch (error) {
403
402
  if (isAccessDenied(error)) throw error;
404
- if (isAbsentResultCandidate(error)) return false;
405
403
  console.error(`Failed to re-read subagent result file '${publicResultPath(file)}':`, error);
406
404
  }
407
405
  identityCache.delete(file);
408
406
  rereadReplacedPayload = true;
409
407
  return true;
410
408
  };
411
- if (typeof data.sessionId !== "string" || !data.sessionId) return;
412
- const sessionId = data.sessionId;
413
- const completionOwnerId = data.completionOwnerId;
414
- const runId = typeof data.runId === "string" && data.runId
415
- ? data.runId
416
- : typeof data.id === "string" && data.id ? data.id : file.replace(/\.json$/i, "");
417
- const toolCallId = typeof data.toolCallId === "string" ? data.toolCallId : undefined;
418
409
  let observerSucceeded = true;
419
410
  try {
420
411
  syncMissionFromAsyncCompletion({ ...data, runId });
@@ -428,7 +419,14 @@ export function createResultWatcher(
428
419
  observerSucceeded = false;
429
420
  console.error(`Completion observer failed for '${resultPath}':`, error);
430
421
  }
431
- if (observerSucceeded) removeMissionObserverIndex(resultsDir, runId);
422
+ if (observerSucceeded) {
423
+ try {
424
+ if (acknowledgeMissionObserverSnapshot(publicResultPath(file), read) === "replaced") rereadReplacedPayload = true;
425
+ } catch (error) {
426
+ observerSucceeded = false;
427
+ console.error(`Failed to acknowledge the mission observer for '${resultPath}'; will retry:`, error);
428
+ }
429
+ }
432
430
  const epoch = deliveryEpoch;
433
431
  if (!ownsCompletion(sessionId, completionOwnerId, epoch)) return;
434
432
  // Recorded before dedupe and before the unlink below so bg_wait can
@@ -461,11 +459,12 @@ export function createResultWatcher(
461
459
  }
462
460
  if (!ownsCompletion(sessionId, completionOwnerId, epoch)) return;
463
461
  if (markReplacedPayload()) return;
462
+ deps.onResultDelivered?.(runId);
464
463
  if (!completionPersisted) {
465
464
  scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
466
465
  return;
467
466
  }
468
- if (!removeDeliveredResult(file, sessionId, runId, toolCallId)) scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
467
+ removeDeliveredResult(file, triggerTurn, read);
469
468
  return;
470
469
  }
471
470
 
@@ -505,6 +504,7 @@ export function createResultWatcher(
505
504
  outputState: result.outputState === "present" || result.outputState === "absent" || result.outputState === "unknown"
506
505
  ? result.outputState
507
506
  : "unknown",
507
+ ...(result.outputPartial === true ? { outputPartial: true } : {}),
508
508
  summary,
509
509
  index,
510
510
  artifactPath: result.artifactPaths?.outputPath,
@@ -522,11 +522,12 @@ export function createResultWatcher(
522
522
  }
523
523
  if (!ownsCompletion(sessionId, completionOwnerId, epoch)) return;
524
524
  if (markReplacedPayload()) return;
525
+ deps.onResultDelivered?.(runId);
525
526
  if (!completionPersisted) {
526
527
  scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
527
528
  return;
528
529
  }
529
- if (!removeDeliveredResult(file, sessionId, runId, toolCallId)) scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
530
+ removeDeliveredResult(file, triggerTurn, read);
530
531
  return;
531
532
  }
532
533
 
@@ -550,7 +551,7 @@ export function createResultWatcher(
550
551
  if (!intercomDelivered) console.error(`Subagent async grouped result intercom delivery was not acknowledged for '${resultPath}'.`);
551
552
  }
552
553
 
553
- const accepted = await notifier.deliver({
554
+ const delivery = notifier.deliver({
554
555
  ...data,
555
556
  id: data.id ?? runId,
556
557
  runId,
@@ -570,15 +571,24 @@ export function createResultWatcher(
570
571
  })) : [],
571
572
  } : {}),
572
573
  });
574
+ if (deliveringPending > 0) notifier.flush?.();
575
+ const accepted = await delivery;
573
576
  if (!ownsCompletion(sessionId, completionOwnerId, epoch)) return;
574
577
  if (!accepted) {
575
578
  scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
576
579
  return;
577
580
  }
581
+ // A newer payload replaced this one; keep the hold until that one is delivered.
578
582
  if (markReplacedPayload()) return;
583
+ deps.onResultDelivered?.(runId);
579
584
  try {
580
- data = markDeliveredNotification(publicResultPath(file), data, runId, Date.now());
585
+ const marked = markDeliveredNotification(publicResultPath(file), data, read, Date.now());
581
586
  identityCache.delete(file);
587
+ if (!marked) {
588
+ rereadReplacedPayload = true;
589
+ return;
590
+ }
591
+ ({ data, read } = marked);
582
592
  } catch (error) {
583
593
  console.error(`Failed to mark subagent result notification delivered for '${resultPath}'; will retry:`, error);
584
594
  scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
@@ -617,7 +627,7 @@ export function createResultWatcher(
617
627
  scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
618
628
  return;
619
629
  }
620
- if (!removeDeliveredResult(file, sessionId, runId, toolCallId)) scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
630
+ removeDeliveredResult(file, triggerTurn, read);
621
631
  } catch (error) {
622
632
  if (isAccessDenied(error)) {
623
633
  console.error(`Failed to process subagent result file '${resultPath}'; will retry:`, error);
@@ -629,11 +639,14 @@ export function createResultWatcher(
629
639
  }
630
640
  };
631
641
 
632
- state.resultFileCoalescer = createFileCoalescer((file) => {
642
+ const resultFileCoalescer = createFileCoalescer((file) => {
633
643
  const triggerTurn = pendingTriggerTurn.get(file) !== false;
634
644
  pendingTriggerTurn.delete(file);
635
- void handleResult(file, triggerTurn);
645
+ const run = handleResult(file, triggerTurn);
646
+ handling.add(run);
647
+ void run.finally(() => handling.delete(run));
636
648
  }, deps.coalesceDelayMs ?? 50);
649
+ state.resultFileCoalescer = resultFileCoalescer;
637
650
 
638
651
  const logScanStats = (stats: ResultScanStats) => {
639
652
  const elapsed = Date.now() - stats.startedAt;
@@ -658,9 +671,9 @@ export function createResultWatcher(
658
671
  for (const runId of observed) files.add(`${runId}.json`);
659
672
  return [...files];
660
673
  };
661
- const primeExistingResults = (options: { triggerTurn?: boolean } = {}) => {
674
+ const eligibleResultFiles = (): string[] => {
675
+ const files: string[] = [];
662
676
  try {
663
- const triggerTurn = options.triggerTurn !== false;
664
677
  const stats: ResultScanStats = { files: 0, scheduled: 0, startedAt: Date.now() };
665
678
  const observed = observedRunIds();
666
679
  for (const file of indexedResultCandidates(observed)) {
@@ -669,12 +682,32 @@ export function createResultWatcher(
669
682
  if (!signature) continue;
670
683
  if (!shouldProcessResult(file, observed, signature)) continue;
671
684
  stats.scheduled += 1;
672
- scheduleResult(file, triggerTurn);
685
+ files.push(file);
673
686
  }
674
687
  logScanStats(stats);
675
688
  } catch (error) {
676
689
  if (!isNotFound(error)) console.error(`Failed to scan subagent result index in '${resultsDir}':`, error);
677
690
  }
691
+ return files;
692
+ };
693
+ const primeExistingResults = (options: { triggerTurn?: boolean } = {}) => {
694
+ const triggerTurn = options.triggerTurn !== false;
695
+ for (const file of eligibleResultFiles()) scheduleResult(file, triggerTurn);
696
+ };
697
+ /** Hand every result that is already on disk to the notifier now, without coalescing or batch delays. */
698
+ const deliverPendingResults = async (): Promise<void> => {
699
+ if (!deliveryActive) return;
700
+ deliveringPending += 1;
701
+ try {
702
+ notifier.flush?.();
703
+ for (const file of eligibleResultFiles()) {
704
+ scheduleResult(file, true);
705
+ resultFileCoalescer.flush(file);
706
+ }
707
+ await Promise.allSettled([...handling]);
708
+ } finally {
709
+ deliveringPending -= 1;
710
+ }
678
711
  };
679
712
 
680
713
  const clearResultScan = () => {
@@ -805,5 +838,5 @@ export function createResultWatcher(
805
838
  identityCache.clear();
806
839
  };
807
840
 
808
- return { startResultWatcher, transitionResultDelivery, primeExistingResults, stopResultWatcher, refreshResultDelivery: () => { primeExistingResults(); startDemandPolling(); } };
841
+ return { startResultWatcher, transitionResultDelivery, primeExistingResults, deliverPendingResults, stopResultWatcher, refreshResultDelivery: () => { primeExistingResults(); startDemandPolling(); } };
809
842
  }
@@ -25,8 +25,8 @@ export function formatAsyncReviveCommand(run: AsyncRunSummary): string | undefin
25
25
  } catch {
26
26
  return undefined;
27
27
  }
28
- const index = run.steps.length === 1 ? "" : `, index: ${step.index}`;
29
- return `subagent({ action: "resume", id: "${run.id}"${index}, message: "Continue from the persisted child session and report the result." })`;
28
+ const index = run.steps.length === 1 ? "" : `, options: { index: ${step.index} }`;
29
+ return `subagent({ action: "resume", id: "${run.id}", message: "Continue from the persisted child session and report the result."${index} })`;
30
30
  }
31
31
 
32
32
  export function formatResumeFirstFailedRunDetail(run: AsyncRunSummary): string | undefined {
@@ -8,6 +8,7 @@
8
8
  import type { Message } from "@earendil-works/pi-ai";
9
9
  import type { ChildTranscriptWriter } from "../../shared/child-transcript.ts";
10
10
  import { extractTextFromContent, extractToolArgsPreview, getFinalOutput, hasEmptyTerminalAssistantResponse } from "../../shared/utils.ts";
11
+ import { qualifyModelWithProvider } from "../../shared/model-info.ts";
11
12
  import type { EffectsProjection, RuntimeAcknowledgedChildExtensions, SubagentOutputState, ToolBudgetState, Usage } from "../../shared/types.ts";
12
13
  import {
13
14
  acceptChildWatchdogEvent,
@@ -24,6 +25,7 @@ import { formatChildModelResolutionDiagnostic, isChildModelResolutionFailure } f
24
25
  import { isMutatingTool, resolveCurrentPath } from "../shared/long-running-guard.ts";
25
26
  import { effectiveToolTimeoutMs, formatToolTimeoutMessage, toolTimeoutCallKey } from "../shared/tool-timeout.ts";
26
27
  import { createReportedChildSessionInput, type InProcessChildLaunch } from "../shared/child-launch.ts";
28
+ import { createPartialOutputTracker, formatPartialOutput, type PartialOutputCause } from "../shared/partial-output.ts";
27
29
  import { childSessionHasQueuedMessages, projectChildSessionEventForJson, type ChildSession, type ChildSessionEvent, type ChildSessionFactory } from "../shared/child-session.ts";
28
30
  import { reconcileAttemptUsage } from "../shared/usage-reconciliation.ts";
29
31
  import { formatSteerMessage } from "../shared/subagent-prompt-runtime.ts";
@@ -114,6 +116,8 @@ export interface RunChildSessionResult {
114
116
  error?: string;
115
117
  finalOutput: string;
116
118
  outputState: SubagentOutputState;
119
+ /** Unfinished streamed text recovered after a timeout or child error. */
120
+ outputPartial?: boolean;
117
121
  interrupted?: boolean;
118
122
  timedOut?: boolean;
119
123
  stopped?: boolean;
@@ -175,6 +179,7 @@ export function runChildSession(input: RunChildSessionInput): Promise<RunChildSe
175
179
  let assistantError: string | undefined;
176
180
  let interrupted = false;
177
181
  let timedOut = false;
182
+ const partialOutput = createPartialOutputTracker();
178
183
  let stopped = false;
179
184
  let observedMutationAttempt = false;
180
185
  let structuredOutputToolInvoked = false;
@@ -411,6 +416,7 @@ export function runChildSession(input: RunChildSessionInput): Promise<RunChildSe
411
416
 
412
417
  const processEvent = (raw: ChildSessionEvent): void => {
413
418
  if (settled) return;
419
+ partialOutput.observe(raw);
414
420
  const event = raw as ChildSessionEvent & ChildEvent;
415
421
  appendChildEvent(projectChildSessionEventForJson(raw) as Record<string, unknown>);
416
422
  input.transcriptWriter?.writeChildEvent(projectChildSessionEventForJson(raw) as ChildEvent);
@@ -512,7 +518,7 @@ export function runChildSession(input: RunChildSessionInput): Promise<RunChildSe
512
518
  if (event.type !== "message_end" || event.message.role !== "assistant") return;
513
519
  const hasToolCall = assistantStartsToolCall(event.message);
514
520
  if (event.message.model) {
515
- model = event.message.model;
521
+ model = qualifyModelWithProvider(event.message.model, event.message.provider, input.modelVerificationRegistry) ?? event.message.model;
516
522
  if (input.expectedModelForVerification && !hasToolCall) {
517
523
  const modelVerificationError = formatSubagentModelVerificationError(input.expectedModelForVerification, event.message.model, input.modelVerificationRegistry, input.modelResponseAliases, session?.virtualModelId);
518
524
  if (modelVerificationError && !error) error = modelVerificationError;
@@ -582,7 +588,14 @@ export function runChildSession(input: RunChildSessionInput): Promise<RunChildSe
582
588
  ? reconcileAttemptUsage(usage, session.messages, messageBaseline)
583
589
  : usage;
584
590
  const closed = finish();
585
- const finalOutput = getFinalOutput(messages);
591
+ const completedOutput = getFinalOutput(messages);
592
+ // Text still streaming at a timeout or thrown session error never reached a
593
+ // completed message; keep it, labeled. The run still fails.
594
+ const partialCause: PartialOutputCause | undefined = timedOut
595
+ ? "timeout"
596
+ : promptError !== undefined && !stopped && !interrupted ? "child error" : undefined;
597
+ const streamedPartial = partialCause ? partialOutput.text() : undefined;
598
+ const finalOutput = partialCause && streamedPartial ? formatPartialOutput(streamedPartial, partialCause) : completedOutput;
586
599
  let finalError = error ?? assistantError;
587
600
  const promptErrorMessage = promptError === undefined ? undefined : promptError instanceof Error ? promptError.message : String(promptError);
588
601
  if (!finalError && promptErrorMessage !== undefined) {
@@ -623,6 +636,7 @@ export function runChildSession(input: RunChildSessionInput): Promise<RunChildSe
623
636
  error: stopped ? stopMessage() : timedOut ? (error ?? timeoutMessage()) : interrupted || (forcedDrainAfterFinalSuccess && !forcedDrainAfterEmptyTerminal && !commandError) ? undefined : finalError,
624
637
  finalOutput: (timedOut || stopped) && !finalOutput.trim() ? (stopped ? stopMessage() : error ?? timeoutMessage()) : finalOutput,
625
638
  outputState: finalOutput.trim() ? "present" : "absent",
639
+ outputPartial: partialCause && streamedPartial ? true : undefined,
626
640
  interrupted: interrupted || undefined,
627
641
  timedOut: timedOut || undefined,
628
642
  stopped: stopped || undefined,
@@ -5,6 +5,7 @@ import { readStatus } from "../../shared/utils.ts";
5
5
  import { findAsyncRunPrefixMatches, type AsyncRunLocation } from "./async-resume.ts";
6
6
  import { resultCandidateFilesForToolCall, resultFilePath, resultPayloadPathForIndexedRun } from "./result-files.ts";
7
7
  import { readActiveRunToolCallIndex } from "./active-run-index.ts";
8
+ import { readTerminalRunToolCallIndex } from "./terminal-run-index.ts";
8
9
  import { assertSafeNestedId, findNestedRunMatchesById, type NestedRoute, type NestedRunMatch, type NestedRunResolutionScope } from "../shared/nested-events.ts";
9
10
 
10
11
  export type ResolvedSubagentRunId =
@@ -66,7 +67,7 @@ function toolCallIdMatches(value: string | undefined, query: string): boolean {
66
67
 
67
68
  function indexedToolCallIdAsyncLocations(toolCallId: string, asyncDirRoot: string, resultsDir: string): AsyncRunMatch[] {
68
69
  const byId = new Map<string, AsyncRunLocation>();
69
- for (const entry of readActiveRunToolCallIndex(asyncDirRoot, toolCallId)) {
70
+ for (const entry of [...readActiveRunToolCallIndex(asyncDirRoot, toolCallId), ...readTerminalRunToolCallIndex(asyncDirRoot, toolCallId)]) {
70
71
  const asyncDir = path.join(asyncDirRoot, entry);
71
72
  const status = readStatus(asyncDir);
72
73
  if (!status || !toolCallIdMatches(status.toolCallId, toolCallId)) continue;
@@ -151,11 +152,13 @@ export function resolveSubagentRunId(id: string, deps: ResolveSubagentRunIdDeps
151
152
  if (hasExactForegroundId(deps.state, id)) return { kind: "foreground", id };
152
153
  const exactAsync = exactAsyncLocation(id, asyncDirRoot, resultsDir);
153
154
  if (exactAsync) return { kind: "async", id, location: exactAsync };
155
+ // A live run and a delivered run can share one alias; count both before deciding it is unique.
156
+ const toolCallMatches = new Map(indexedToolCallIdAsyncLocations(id, asyncDirRoot, resultsDir).map((match) => [match.id, match]));
154
157
  const exactLiveToolCallMatch = exactLiveAsyncToolCallMatch(deps.state, id, asyncDirRoot, resultsDir);
155
- if (exactLiveToolCallMatch) return { kind: "async", id: exactLiveToolCallMatch.id, location: exactLiveToolCallMatch.location };
156
- const exactToolCallIdMatches = indexedToolCallIdAsyncLocations(id, asyncDirRoot, resultsDir);
157
- if (exactToolCallIdMatches.length > 1) throw new Error(`Subagent tool-call id '${id}' is ambiguous across async runs. Use the returned asyncId instead.`);
158
- if (exactToolCallIdMatches[0]) return { kind: "async", id: exactToolCallIdMatches[0].id, location: exactToolCallIdMatches[0].location };
158
+ if (exactLiveToolCallMatch) toolCallMatches.set(exactLiveToolCallMatch.id, exactLiveToolCallMatch);
159
+ if (toolCallMatches.size > 1) throw new Error(`Subagent tool-call id '${id}' is ambiguous across async runs. Use the returned asyncId instead.`);
160
+ const [toolCallMatch] = toolCallMatches.values();
161
+ if (toolCallMatch) return { kind: "async", id: toolCallMatch.id, location: toolCallMatch.location };
159
162
  const nestedScope = deps.nested ?? nestedScopeFromState(deps.state);
160
163
  const exactNested = findNestedRunMatchesById(id, nestedScope ? { scope: nestedScope } : {});
161
164
  if (exactNested.length > 1) throw new Error(`Nested run id '${id}' is ambiguous across authorized registries. Provide the full id after stale registries are cleaned up.`);