@xzzpig/pi-subagents 0.16.0 → 0.19.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 (166) hide show
  1. package/CHANGELOG.md +233 -1
  2. package/README.md +5 -3
  3. package/agents/claude-code-writer.md +1 -0
  4. package/agents/codex-exec-writer.md +1 -0
  5. package/agents/cursor-agent-writer.md +1 -0
  6. package/agents/reviewer.md +3 -2
  7. package/agents/worker.md +3 -2
  8. package/docs/agents.md +34 -21
  9. package/docs/configuration.md +82 -7
  10. package/docs/extension-api.md +75 -8
  11. package/docs/missions.md +13 -13
  12. package/docs/models.md +7 -5
  13. package/docs/observability.md +23 -13
  14. package/docs/standalone-background.md +5 -5
  15. package/docs/tool-reference.md +98 -100
  16. package/docs/watchdog.md +2 -0
  17. package/docs/workflows.md +214 -162
  18. package/inspector-runner.mjs +1 -1
  19. package/node_modules/@xzzpig/pi-components/package.json +4 -4
  20. package/package.json +15 -9
  21. package/prompts/council.md +6 -3
  22. package/prompts/review-loop.md +1 -1
  23. package/runner-peer-loader.mjs +4 -7
  24. package/runner-peer-preload.mjs +5 -7
  25. package/skills/council-mode/SKILL.md +1 -1
  26. package/skills/pi-subagents/SKILL.md +13 -5
  27. package/skills/pi-subagents/references/constraints-and-recipes.md +8 -5
  28. package/skills/pi-subagents/references/execution-controls.md +72 -69
  29. package/skills/pi-subagents/references/management-authoring-rpc.md +4 -4
  30. package/skills/pi-subagents/references/multi-lane-orchestration.md +9 -1
  31. package/skills/pi-subagents/references/prompting-and-roles.md +52 -54
  32. package/src/agents/advertised-agent-prompt.ts +21 -41
  33. package/src/agents/agent-eject.ts +3 -3
  34. package/src/agents/agent-management.ts +63 -54
  35. package/src/agents/agent-memory.ts +90 -3
  36. package/src/agents/agent-serializer.ts +4 -4
  37. package/src/agents/agents.ts +132 -51
  38. package/src/agents/global-npm-root.ts +58 -0
  39. package/src/agents/proactive-skills.ts +4 -1
  40. package/src/agents/runtime-agent-registry.ts +14 -11
  41. package/src/agents/skills.ts +42 -9
  42. package/src/api/delegation.ts +15 -0
  43. package/src/api/inspectors.ts +27 -0
  44. package/src/api/preflight.ts +7 -2
  45. package/src/extension/config.ts +12 -4
  46. package/src/extension/control-notices.ts +3 -0
  47. package/src/extension/doctor.ts +10 -4
  48. package/src/extension/fanout-child.ts +20 -3
  49. package/src/extension/herdr-pi-bridge.ts +2 -0
  50. package/src/extension/index.ts +168 -206
  51. package/src/extension/public-execution.ts +69 -35
  52. package/src/extension/reply-workflow-script.ts +58 -0
  53. package/src/extension/rpc.ts +39 -11
  54. package/src/extension/schemas.ts +47 -138
  55. package/src/extension/subagent-guide.ts +12 -4
  56. package/src/extension/tool-activation.ts +146 -0
  57. package/src/extension/tool-description.ts +62 -27
  58. package/src/extension/upgrade-notice.ts +40 -0
  59. package/src/inspectors/ghostty/plugin.ts +13 -1
  60. package/src/inspectors/plugins.ts +70 -3
  61. package/src/integrations/herdr-status.ts +19 -3
  62. package/src/intercom/intercom-bridge.ts +2 -0
  63. package/src/intercom/native-supervisor-channel.ts +26 -16
  64. package/src/intercom/result-intercom.ts +4 -0
  65. package/src/runs/background/active-async-capacity.ts +3 -25
  66. package/src/runs/background/async-execution.ts +60 -95
  67. package/src/runs/background/async-job-tracker.ts +91 -56
  68. package/src/runs/background/async-resume.ts +16 -8
  69. package/src/runs/background/async-retention.ts +46 -16
  70. package/src/runs/background/async-status.ts +2 -0
  71. package/src/runs/background/await-async-run.ts +76 -0
  72. package/src/runs/background/binary-bootstrap.ts +34 -6
  73. package/src/runs/background/chain-root-attachment.ts +4 -4
  74. package/src/runs/background/control-channel.ts +18 -2
  75. package/src/runs/background/fleet-view.ts +51 -7
  76. package/src/runs/background/notify.ts +98 -7
  77. package/src/runs/background/pid-namespace.ts +18 -0
  78. package/src/runs/background/process-terminal-candidate.ts +98 -0
  79. package/src/runs/background/process-terminal.ts +17 -96
  80. package/src/runs/background/result-watcher.ts +1 -1
  81. package/src/runs/background/retained-children.ts +3 -2
  82. package/src/runs/background/run-child-session.ts +20 -6
  83. package/src/runs/background/run-id-resolver.ts +10 -5
  84. package/src/runs/background/run-status.ts +16 -4
  85. package/src/runs/background/runner-aliases.ts +54 -16
  86. package/src/runs/background/runner-child-launch.ts +4 -2
  87. package/src/runs/background/runner-startup-failure.ts +56 -0
  88. package/src/runs/background/scheduled-runs.ts +5 -5
  89. package/src/runs/background/stale-run-reconciler.ts +19 -3
  90. package/src/runs/background/subagent-runner-bootstrap.ts +276 -0
  91. package/src/runs/background/subagent-runner.ts +111 -288
  92. package/src/runs/background/wait-tool.ts +2 -0
  93. package/src/runs/background/workflow-terminal-proof.ts +68 -0
  94. package/src/runs/foreground/async-stop-action.ts +17 -3
  95. package/src/runs/foreground/execution.ts +111 -139
  96. package/src/runs/foreground/prompt-audit.ts +3 -9
  97. package/src/runs/foreground/subagent-executor.ts +715 -258
  98. package/src/runs/shared/acceptance.ts +167 -68
  99. package/src/runs/shared/async-status-projection.ts +5 -0
  100. package/src/runs/shared/capability-ceiling.ts +4 -1
  101. package/src/runs/shared/child-hooks.ts +1 -16
  102. package/src/runs/shared/child-launch.ts +37 -16
  103. package/src/runs/shared/child-runtime-config.ts +3 -0
  104. package/src/runs/shared/child-session.ts +144 -8
  105. package/src/runs/shared/child-tool-plan.ts +38 -116
  106. package/src/runs/shared/dynamic-fanout.ts +1 -1
  107. package/src/runs/shared/external-cli-runner.ts +3 -1
  108. package/src/runs/shared/external-job-bridge.ts +54 -0
  109. package/src/runs/shared/git-environment.ts +29 -0
  110. package/src/runs/shared/mcp-config-sources.ts +5 -1
  111. package/src/runs/shared/mcp-direct-tool-allowlist.ts +104 -12
  112. package/src/runs/shared/mcp-direct-tool-grant.ts +22 -6
  113. package/src/runs/shared/model-resolution.ts +35 -10
  114. package/src/runs/shared/model-scope.ts +28 -9
  115. package/src/runs/shared/nested-events.ts +12 -0
  116. package/src/runs/shared/orca-progress-tabs.ts +3 -2
  117. package/src/runs/shared/parallel-utils.ts +4 -1
  118. package/src/runs/shared/pi-spawn.ts +1 -3
  119. package/src/runs/shared/single-output.ts +11 -2
  120. package/src/runs/shared/structured-output.ts +227 -7
  121. package/src/runs/shared/subagent-control.ts +2 -16
  122. package/src/runs/shared/subagent-prompt-runtime.ts +29 -5
  123. package/src/runs/shared/tool-availability.ts +2 -2
  124. package/src/runs/shared/tool-budget.ts +21 -0
  125. package/src/runs/shared/usage-reconciliation.ts +73 -0
  126. package/src/runs/shared/worktree.ts +36 -9
  127. package/src/shared/child-session-name.ts +4 -2
  128. package/src/shared/disabled-features.ts +123 -0
  129. package/src/shared/extension-context.ts +13 -0
  130. package/src/shared/fork-context.ts +11 -4
  131. package/src/shared/launch-contract.ts +1 -1
  132. package/src/shared/model-info.ts +9 -0
  133. package/src/shared/pruned-fork.ts +69 -56
  134. package/src/shared/settings.ts +1 -1
  135. package/src/shared/types.ts +73 -16
  136. package/src/slash/delegation-adapters.ts +25 -1
  137. package/src/slash/prompt-template-bridge.ts +18 -3
  138. package/src/slash/prompt-workflows.ts +12 -1
  139. package/src/slash/slash-commands.ts +17 -246
  140. package/src/slash/subagent-cost.ts +313 -0
  141. package/src/slash/subagents-admin.ts +4 -5
  142. package/src/tui/fleet-status.ts +38 -8
  143. package/src/tui/fleet.ts +21 -6
  144. package/src/tui/render.ts +166 -71
  145. package/src/tui/running-tone.ts +28 -0
  146. package/src/watchdog/diff-tool.ts +47 -12
  147. package/src/watchdog/permission-arbiter.ts +13 -15
  148. package/src/watchdog/register-child.ts +13 -5
  149. package/src/watchdog/register-main.ts +3 -3
  150. package/src/watchdog/review.ts +16 -16
  151. package/src/watchdog/runtime.ts +2 -1
  152. package/src/watchdog/turn-delta.ts +12 -6
  153. package/src/workflows/chat-progress.ts +2 -2
  154. package/src/workflows/scripted-workflow.ts +225 -59
  155. package/src/workflows/structured-workflow-scripts.ts +177 -0
  156. package/src/workflows/workflow-checklist.ts +6 -0
  157. package/src/workflows/workflow-child-summary.ts +4 -2
  158. package/src/workflows/workflow-receipt.ts +8 -2
  159. package/src/workflows/workflow-resources.ts +37 -12
  160. package/src/workflows/workflow-reuse.ts +120 -0
  161. package/src/workflows/workflow-revival.ts +123 -0
  162. package/src/workflows/workflow-settlement.ts +4 -1
  163. package/src/runs/shared/completion-evidence.ts +0 -89
  164. package/src/runs/shared/completion-guard.ts +0 -255
  165. package/src/runs/shared/llm-intent-arbiter.ts +0 -321
  166. package/src/runs/shared/task-intent.ts +0 -244
@@ -20,9 +20,9 @@ import {
20
20
  import { readStatus, resolveWatchPath } from "../../shared/utils.ts";
21
21
  import { normalizeParallelGroups } from "./parallel-groups.ts";
22
22
  import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
23
- import { findNestedRouteForRootId, hasLiveNestedDescendants, updateAsyncJobNestedProjection } from "../shared/nested-events.ts";
23
+ import { findNestedRouteForRootId, hasLiveNestedDescendants, retainNestedLookupRoute, updateAsyncJobNestedProjection } from "../shared/nested-events.ts";
24
24
  import { listAsyncRuns, type AsyncRunSummary } from "./async-status.ts";
25
- import { EXTERNAL_JOB_BRIDGE_REQUEST_DIR, serviceExternalJobBridgeRequests } from "../shared/external-job-bridge.ts";
25
+ import { EXTERNAL_JOB_BRIDGE_REQUEST_DIR, externalJobBridgeEligibility, serviceExternalJobBridgeRequests } from "../shared/external-job-bridge.ts";
26
26
  import { shouldUseNativeFsWatch } from "../../shared/watch-strategy.ts";
27
27
  import { parseWorkflowChildSummary } from "../../workflows/workflow-child-summary.ts";
28
28
  import { validHostStepNodes } from "../shared/host-step-status.ts";
@@ -51,6 +51,11 @@ const MAX_RECENT_FLEET_JOBS = 20;
51
51
  const DEFAULT_LIVENESS_INTERVAL_MS = 5000;
52
52
  const EVENT_REFRESH_DEBOUNCE_MS = 25;
53
53
  const WATCH_ATTACHMENT_RETRY_MS = 100;
54
+ /** A native supervisor request is already its own parent turn; its attention notice only escalates an unanswered one. */
55
+ const SUPERVISOR_NOTICE_GRACE_MS = 60_000;
56
+
57
+ type ControlRecord = { event: ControlEvent; channels: string[]; childIntercomTarget?: string; noticeText?: string; intercom?: { to?: string; message?: string } };
58
+ type ControlPayload = { event: ControlEvent; source: "async"; asyncDir: string; childIntercomTarget?: string; noticeText: string };
54
59
 
55
60
  const isTerminalJobStatus = (status: AsyncJobState["status"]): boolean =>
56
61
  status === "complete" || status === "failed" || status === "partial" || status === "paused" || status === "rejected" || status === "stopped";
@@ -85,19 +90,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
85
90
  // Early native failure is visible before its publisher finishes. Retain only
86
91
  // that scoped observation, using the existing liveness sweep to renew delivery.
87
92
  const terminalPublications = new Map<string, { instanceId: string; pending: true } | { pending: false }>();
88
- const externalJobBridgeEligibility = (steps: AsyncJobState["steps"]): "required" | "not-required" | "unknown" => {
89
- if (!Array.isArray(steps)) return "unknown";
90
- for (const step of steps) {
91
- const runner = (step as { runner?: unknown } | null)?.runner;
92
- if (runner === undefined) continue;
93
- if (!runner || typeof runner !== "object" || Array.isArray(runner)) return "unknown";
94
- const runnerType = (runner as { type?: unknown }).type;
95
- if (typeof runnerType !== "string") return "unknown";
96
- if (runnerType === "external-job") return "required";
97
- if (runnerType !== "pi" && runnerType !== "external-cli") return "unknown";
98
- }
99
- return "not-required";
100
- };
93
+ const supervisorNoticeTimers = new Map<string, { asyncId: string; timer: ReturnType<typeof setTimeout> }>();
101
94
  let rootWatcher: fs.FSWatcher | undefined;
102
95
  let nextLivenessAt = Date.now() + livenessIntervalMs;
103
96
  let nextWidgetAnimationAt = Date.now() + WIDGET_ANIMATION_INTERVAL_MS;
@@ -223,11 +216,53 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
223
216
  const timer = setTimeout(() => {
224
217
  state.cleanupTimers.delete(asyncId);
225
218
  closeJobWatcher(asyncId);
219
+ const job = state.asyncJobs.get(asyncId);
220
+ retainNestedLookupRoute(state, job?.nestedRoute, job?.sessionId);
226
221
  state.asyncJobs.delete(asyncId);
227
222
  rerenderLastWidget();
228
223
  }, completionRetentionMs);
229
224
  state.cleanupTimers.set(asyncId, timer);
230
225
  };
226
+ const deliverControlRecord = (record: ControlRecord, payload: ControlPayload) => {
227
+ if (record.channels.includes("event")) {
228
+ pi.events.emit(SUBAGENT_CONTROL_EVENT, payload);
229
+ }
230
+ if (record.event.type !== "active_long_running" && record.channels.includes("intercom") && record.intercom?.to && record.intercom.message) {
231
+ pi.events.emit(SUBAGENT_CONTROL_INTERCOM_EVENT, {
232
+ ...payload,
233
+ to: record.intercom.to,
234
+ message: record.intercom.message,
235
+ });
236
+ }
237
+ };
238
+ const readSupervisorRequestState = (event: ControlEvent, asyncDir: string): "pending" | "resolved" | "unknown" => {
239
+ try {
240
+ return options.supervisorRequestState?.(event) ?? "unknown";
241
+ } catch (error) {
242
+ console.error(`Failed to resolve supervisor request state for async control event in '${asyncDir}':`, error);
243
+ return "unknown";
244
+ }
245
+ };
246
+ const scheduleSupervisorNotice = (asyncId: string, record: ControlRecord, payload: ControlPayload) => {
247
+ const key = `${asyncId}:${record.event.index}:${record.event.toolCallId}`;
248
+ if (supervisorNoticeTimers.has(key)) return;
249
+ const timer = setTimeout(() => {
250
+ supervisorNoticeTimers.delete(key);
251
+ const job = state.asyncJobs.get(asyncId);
252
+ if (job?.status !== "running" && job?.status !== "queued") return;
253
+ if (readSupervisorRequestState(record.event, payload.asyncDir) === "resolved") return;
254
+ deliverControlRecord(record, payload);
255
+ }, SUPERVISOR_NOTICE_GRACE_MS);
256
+ timer.unref?.();
257
+ supervisorNoticeTimers.set(key, { asyncId, timer });
258
+ };
259
+ const clearSupervisorNotices = (asyncId?: string) => {
260
+ for (const [key, entry] of supervisorNoticeTimers) {
261
+ if (asyncId !== undefined && entry.asyncId !== asyncId) continue;
262
+ clearTimeout(entry.timer);
263
+ supervisorNoticeTimers.delete(key);
264
+ }
265
+ };
231
266
  const emitNewControlEvents = (job: AsyncJobState) => {
232
267
  const eventsPath = path.join(job.asyncDir, "events.jsonl");
233
268
  let fd: number;
@@ -262,24 +297,28 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
262
297
  if (!parsed || typeof parsed !== "object") return;
263
298
  if ((parsed as { type?: unknown }).type === "subagent.child-status") {
264
299
  const event = parsed as Partial<SubagentChildStatusEvent>;
265
- if (event.version !== 1 || typeof event.runId !== "string" || typeof event.childId !== "string" || (event.status !== "stopping" && event.status !== "stopped") || typeof event.ts !== "number") return;
266
- pi.events.emit(SUBAGENT_CHILD_STATUS_EVENT, {
267
- type: "subagent.child-status",
268
- version: 1,
269
- runId: event.runId,
270
- childId: event.childId,
271
- status: event.status,
272
- ts: event.ts,
273
- ...(typeof event.reason === "string" ? { reason: event.reason } : {}),
274
- source: event.source === "rpc" ? "rpc" : "async",
275
- asyncDir: job.asyncDir,
276
- ...(typeof event.stepIndex === "number" ? { stepIndex: event.stepIndex } : {}),
277
- ...(typeof event.agent === "string" ? { agent: event.agent } : {}),
278
- ...(typeof event.childRunId === "string" ? { childRunId: event.childRunId } : {}),
279
- ...(typeof event.workflowKey === "string" ? { workflowKey: event.workflowKey } : {}),
280
- ...(typeof event.phase === "string" ? { phase: event.phase } : {}),
281
- ...(typeof event.label === "string" ? { label: event.label } : {}),
282
- } satisfies SubagentChildStatusEvent);
300
+ if (event.version !== 1 || typeof event.runId !== "string" || typeof event.childId !== "string" || (event.status !== "started" && event.status !== "stopping" && event.status !== "stopped") || typeof event.ts !== "number") return;
301
+ try {
302
+ pi.events.emit(SUBAGENT_CHILD_STATUS_EVENT, {
303
+ type: "subagent.child-status",
304
+ version: 1,
305
+ runId: event.runId,
306
+ childId: event.childId,
307
+ status: event.status,
308
+ ts: event.ts,
309
+ ...(typeof event.reason === "string" ? { reason: event.reason } : {}),
310
+ source: event.source === "rpc" ? "rpc" : "async",
311
+ asyncDir: job.asyncDir,
312
+ ...(typeof event.stepIndex === "number" ? { stepIndex: event.stepIndex } : {}),
313
+ ...(typeof event.agent === "string" ? { agent: event.agent } : {}),
314
+ ...(typeof event.childRunId === "string" ? { childRunId: event.childRunId } : {}),
315
+ ...(typeof event.workflowKey === "string" ? { workflowKey: event.workflowKey } : {}),
316
+ ...(typeof event.phase === "string" ? { phase: event.phase } : {}),
317
+ ...(typeof event.label === "string" ? { label: event.label } : {}),
318
+ } satisfies SubagentChildStatusEvent);
319
+ } catch (error) {
320
+ console.error("Failed to emit async child status event:", error);
321
+ }
283
322
  return;
284
323
  }
285
324
  if ((parsed as { type?: unknown }).type === "subagent.steering.notice") {
@@ -299,34 +338,27 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
299
338
  return;
300
339
  }
301
340
  if ((parsed as { type?: unknown }).type !== "subagent.control") return;
302
- const record = parsed as { event?: ControlEvent; channels?: string[]; childIntercomTarget?: string; noticeText?: string; intercom?: { to?: string; message?: string } };
303
- if (!record.event || !Array.isArray(record.channels)) return;
304
- if (record.event.type === "needs_attention" && record.event.reason === "supervisor_request" && options.supervisorRequestState) {
305
- let requestState: "pending" | "resolved" | "unknown" = "unknown";
306
- try {
307
- requestState = options.supervisorRequestState(record.event);
308
- } catch (error) {
309
- console.error(`Failed to resolve supervisor request state for async control event in '${job.asyncDir}':`, error);
310
- }
311
- if (requestState === "resolved") return;
312
- }
313
- const payload = {
341
+ const candidate = parsed as Partial<ControlRecord>;
342
+ if (!candidate.event || !Array.isArray(candidate.channels)) return;
343
+ // SAFETY: event is present and channels is an array; every other ControlRecord field is optional.
344
+ const record = candidate as ControlRecord;
345
+ const supervisorRequest = record.event.type === "needs_attention" && record.event.reason === "supervisor_request" && options.supervisorRequestState !== undefined;
346
+ if (supervisorRequest && readSupervisorRequestState(record.event, job.asyncDir) === "resolved") return;
347
+ const payload: ControlPayload = {
314
348
  event: record.event,
315
- source: "async" as const,
349
+ source: "async",
316
350
  asyncDir: job.asyncDir,
317
351
  childIntercomTarget: record.childIntercomTarget,
318
352
  noticeText: record.noticeText ?? formatControlNoticeMessage(record.event, record.childIntercomTarget),
319
353
  };
320
- if (record.channels.includes("event")) {
321
- pi.events.emit(SUBAGENT_CONTROL_EVENT, payload);
322
- }
323
- if (record.event.type !== "active_long_running" && record.channels.includes("intercom") && record.intercom?.to && record.intercom.message) {
324
- pi.events.emit(SUBAGENT_CONTROL_INTERCOM_EVENT, {
325
- ...payload,
326
- to: record.intercom.to,
327
- message: record.intercom.message,
328
- });
354
+ // External intercom asks have no native lifecycle to re-check, so they keep the immediate notice.
355
+ if (supervisorRequest && record.event.currentTool !== "intercom") {
356
+ // Status and waits still react now; the parent notice and intercom copy wait for the grace period.
357
+ if (record.channels.includes("event")) pi.events.emit(SUBAGENT_CONTROL_EVENT, { ...payload, noticeDeferred: true });
358
+ scheduleSupervisorNotice(job.asyncId, record, payload);
359
+ return;
329
360
  }
361
+ deliverControlRecord(record, payload);
330
362
  };
331
363
  let readCursor = cursor;
332
364
  let lastCompleteCursor = cursor;
@@ -387,6 +419,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
387
419
  runningJobIds.delete(asyncId);
388
420
  externalJobBridgeRuns.delete(asyncId);
389
421
  terminalPublications.delete(asyncId);
422
+ clearSupervisorNotices(asyncId);
390
423
  };
391
424
 
392
425
  const refreshJob = (job: AsyncJobState): boolean => {
@@ -694,7 +727,8 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
694
727
  const agents = firstGroupCount && firstGroupCount > 0
695
728
  ? rawAgents?.slice(0, firstGroupCount)
696
729
  : rawAgents;
697
- const sessionRoot = state.liveAsyncSessionRoots?.get(info.id);
730
+ const existingJob = state.asyncJobs.get(info.id);
731
+ const sessionRoot = state.liveAsyncSessionRoots?.get(info.id) ?? existingJob?.sessionRoot;
698
732
  state.liveAsyncSessionRoots?.delete(info.id);
699
733
  externalJobBridgeRuns.delete(info.id);
700
734
  terminalPublications.delete(info.id);
@@ -779,6 +813,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
779
813
  runningJobIds.clear();
780
814
  externalJobBridgeRuns.clear();
781
815
  terminalPublications.clear();
816
+ clearSupervisorNotices();
782
817
  };
783
818
 
784
819
  const resetJobs = (ctx?: ExtensionContext) => {
@@ -7,7 +7,7 @@ import { snapshotRequiredChildExtensions } from "../../shared/required-child-ext
7
7
  import { normalizeWorkflowLaneMetadata } from "../shared/lane-metadata.ts";
8
8
  import { validateAcceptanceInput } from "../shared/acceptance.ts";
9
9
  import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
10
- import { intersectSubagentCapabilityCeilings, parseSubagentCapabilityCeiling, type ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
10
+ import { intersectSubagentCapabilityCeilings, normalizeCapabilityCeilingAllowedAgents, parseSubagentCapabilityCeiling, type ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
11
11
  import { validateRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.ts";
12
12
  import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
13
13
  import { resultFilePath, resultPayloadPathForIndexedRun } from "./result-files.ts";
@@ -83,6 +83,7 @@ interface AsyncResultFile {
83
83
  sandbox?: string;
84
84
  permissionProfile?: string;
85
85
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
86
+ admissionCapabilityCeiling?: ResolvedSubagentCapabilityCeiling;
86
87
  results?: Array<{ agent?: string; sessionName?: string; success?: boolean; sessionFile?: string; intercomTarget?: string; model?: string; thinking?: string; launchContractDigest?: string; sandbox?: string; permissionProfile?: string; capabilityCeiling?: ResolvedSubagentCapabilityCeiling }>;
87
88
  }
88
89
 
@@ -154,6 +155,7 @@ function validateResultFile(value: unknown, resultPath: string): AsyncResultFile
154
155
  ...(data.sandbox === undefined ? {} : { sandbox: validateSandboxProfileName(data.sandbox, `async result file '${resultPath}' sandbox`) }),
155
156
  ...(data.permissionProfile === undefined ? {} : { permissionProfile: validatePermissionProfileName(data.permissionProfile, `async result file '${resultPath}' permissionProfile`) }),
156
157
  ...(data.capabilityCeiling === undefined ? {} : { capabilityCeiling: parseSubagentCapabilityCeiling(data.capabilityCeiling, `async result file '${resultPath}' capabilityCeiling`) }),
158
+ ...(data.admissionCapabilityCeiling === undefined ? {} : { admissionCapabilityCeiling: parseSubagentCapabilityCeiling(data.admissionCapabilityCeiling, `async result file '${resultPath}' admissionCapabilityCeiling`) }),
157
159
  ...(typeof success === "boolean" ? { success } : {}),
158
160
  ...(results ? { results } : {}),
159
161
  };
@@ -287,6 +289,7 @@ function validateStatusForResume(status: AsyncStatus | null, source: string): vo
287
289
  if (status.cwd !== undefined && typeof status.cwd !== "string") throw new Error(`Invalid async status '${source}': cwd must be a string.`);
288
290
  if (status.sessionFile !== undefined && typeof status.sessionFile !== "string") throw new Error(`Invalid async status '${source}': sessionFile must be a string.`);
289
291
  if (status.capabilityCeiling !== undefined) status.capabilityCeiling = parseSubagentCapabilityCeiling(status.capabilityCeiling, `async status '${source}' capabilityCeiling`);
292
+ if (status.admissionCapabilityCeiling !== undefined) status.admissionCapabilityCeiling = parseSubagentCapabilityCeiling(status.admissionCapabilityCeiling, `async status '${source}' admissionCapabilityCeiling`);
290
293
  if (status.steps !== undefined) {
291
294
  if (!Array.isArray(status.steps)) throw new Error(`Invalid async status '${source}': steps must be an array.`);
292
295
  status.steps.forEach((step, index) => {
@@ -312,9 +315,9 @@ function normalizeRecoveryAcceptance(value: unknown, descriptorPath: string): Ac
312
315
  return value as AcceptanceInput;
313
316
  }
314
317
 
315
- export function asyncReviveRequiresRecoveryDescriptor(target: Pick<AsyncResumeTarget, "recoveryDescriptor" | "mode" | "sessionFile">): boolean {
318
+ export function asyncReviveRequiresRecoveryDescriptor(target: Pick<AsyncResumeTarget, "recoveryDescriptor" | "mode" | "sessionFile" | "capabilityCeiling">): boolean {
316
319
  if (target.recoveryDescriptor) return false;
317
- return !(target.mode === "workflow" && Boolean(target.sessionFile));
320
+ return !(target.mode === "workflow" && target.sessionFile && target.capabilityCeiling);
318
321
  }
319
322
 
320
323
  function resumeTargetMode(status: AsyncStatus | null, result: AsyncResultFile | undefined): SubagentRunMode | undefined {
@@ -336,9 +339,9 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
336
339
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': expected an object.`);
337
340
  const parsed = value as Record<string, unknown>;
338
341
  const allowedFields = new Set([
339
- "modelResponseAliases", "version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sandbox", "permissionProfile", "sessionFile", "cwd", "model", "modelProvider", "modelOverrideFromParent", "modelOrigin", "fast", "thinking", "thinkingCeiling", "tools", "allowNestedSubagents", "extensions",
342
+ "modelResponseAliases", "version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sandbox", "permissionProfile", "sessionFile", "cwd", "model", "modelProvider", "modelOverrideFromParent", "modelOrigin", "fast", "thinking", "thinkingCeiling", "tools", "allowNestedSubagents", "allowedAgents", "extensions",
340
343
  "subagentOnlyExtensions", "mcpDirectTools", "excludeTools", "mutationTools", "systemPrompt", "systemPromptMode", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills",
341
- "skillPath", "agentFilePath", "completionGuard", "memory", "outputPath", "outputMode", "structuredOutputSchema", "acceptance", "sessionDir", "artifactConfig",
344
+ "skillPath", "agentFilePath", "memory", "outputPath", "outputMode", "structuredOutputSchema", "acceptance", "sessionDir", "artifactConfig",
342
345
  "artifactsDir", "maxOutput", "controlConfig", "context", "intercomBridge", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
343
346
  "launchResolvedExtensions", "runFanoutBudget", "lane", "baseRef",
344
347
  "extensionBindings",
@@ -384,6 +387,10 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
384
387
  if (parsed.inheritGlobalContext === undefined) parsed.inheritGlobalContext = parsed.inheritProjectContext;
385
388
  else if (typeof parsed.inheritGlobalContext !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': inheritGlobalContext must be a boolean.`);
386
389
  if (parsed.allowNestedSubagents !== undefined && typeof parsed.allowNestedSubagents !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': allowNestedSubagents must be a boolean.`);
390
+ if (parsed.allowedAgents !== undefined) {
391
+ try { parsed.allowedAgents = normalizeCapabilityCeilingAllowedAgents(parsed.allowedAgents); }
392
+ catch (error) { throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${error instanceof Error ? error.message : String(error)}`); }
393
+ }
387
394
  if (!Number.isInteger(parsed.maxSubagentDepth) || (parsed.maxSubagentDepth as number) < 0) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': maxSubagentDepth must be a non-negative integer.`);
388
395
  for (const field of ["tools", "excludeTools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "skills", "skillPath"] as const) {
389
396
  const item = parsed[field];
@@ -403,7 +410,6 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
403
410
  }
404
411
  if (parsed.sandbox !== undefined) parsed.sandbox = validateSandboxProfileName(parsed.sandbox, `async recovery descriptor '${descriptorPath}' sandbox`);
405
412
  if (parsed.permissionProfile !== undefined) parsed.permissionProfile = validatePermissionProfileName(parsed.permissionProfile, `async recovery descriptor '${descriptorPath}' permissionProfile`);
406
- if (parsed.completionGuard !== undefined && typeof parsed.completionGuard !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': completionGuard must be a boolean.`);
407
413
  if (parsed.structuredOutputSchema !== undefined && (!parsed.structuredOutputSchema || typeof parsed.structuredOutputSchema !== "object" || Array.isArray(parsed.structuredOutputSchema))) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': structuredOutputSchema must be an object.`);
408
414
  if (parsed.memory !== undefined) {
409
415
  if (!parsed.memory || typeof parsed.memory !== "object" || Array.isArray(parsed.memory)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': memory must be an object.`);
@@ -596,7 +602,9 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
596
602
  const stepModel = statusSteps[index]?.model ?? resultSteps[index]?.model ?? (stepCount === 1 ? result?.model : undefined);
597
603
  const stepThinking = statusSteps[index]?.thinking ?? resultSteps[index]?.thinking ?? (stepCount === 1 ? result?.thinking : undefined);
598
604
  const thinkingCeiling = statusSteps[index]?.thinkingCeiling ?? (stepCount === 1 ? recoveryDescriptor?.thinkingCeiling : undefined);
599
- const capabilityCeiling = intersectSubagentCapabilityCeilings(status?.capabilityCeiling, statusSteps[index]?.capabilityCeiling, result?.capabilityCeiling, resultSteps[index]?.capabilityCeiling);
605
+ const capabilityCeiling = mode === "workflow"
606
+ ? intersectSubagentCapabilityCeilings(status?.admissionCapabilityCeiling, result?.admissionCapabilityCeiling)
607
+ : intersectSubagentCapabilityCeilings(status?.capabilityCeiling, statusSteps[index]?.capabilityCeiling, result?.capabilityCeiling, resultSteps[index]?.capabilityCeiling);
600
608
  const managedWorktreeCwd = location.asyncDir
601
609
  ? resolveRetainedWorktreeCwd(parallelHandoffPath(location.asyncDir), runId, index)
602
610
  : undefined;
@@ -637,6 +645,7 @@ export function applySteeringRecoveryAgentConfig(agentConfig: AgentConfig, descr
637
645
  tools: descriptor.tools ? [...descriptor.tools] : undefined,
638
646
  excludeTools: descriptor.excludeTools ? [...descriptor.excludeTools] : undefined,
639
647
  allowNestedSubagents: descriptor.allowNestedSubagents,
648
+ allowedAgents: descriptor.allowedAgents === undefined ? undefined : [...descriptor.allowedAgents],
640
649
  extensions: descriptor.extensions ? [...descriptor.extensions] : undefined,
641
650
  subagentOnlyExtensions: descriptor.subagentOnlyExtensions ? [...descriptor.subagentOnlyExtensions] : undefined,
642
651
  mcpDirectTools: descriptor.mcpDirectTools ? [...descriptor.mcpDirectTools] : undefined,
@@ -651,7 +660,6 @@ export function applySteeringRecoveryAgentConfig(agentConfig: AgentConfig, descr
651
660
  skills: descriptor.skills ? [...descriptor.skills] : undefined,
652
661
  skillPath: descriptor.skillPath ? [...descriptor.skillPath] : undefined,
653
662
  filePath: descriptor.agentFilePath as string,
654
- completionGuard: descriptor.completionGuard,
655
663
  memory: descriptor.memory ? { ...descriptor.memory } : undefined,
656
664
  output: descriptor.outputPath,
657
665
  toolBudget: descriptor.initialToolBudget,
@@ -1,4 +1,4 @@
1
- import { spawnSync } from "node:child_process";
1
+ import { execFile } from "node:child_process";
2
2
  import * as fs from "node:fs";
3
3
  import * as os from "node:os";
4
4
  import * as path from "node:path";
@@ -6,7 +6,10 @@ import { randomUUID } from "node:crypto";
6
6
  import { Worker } from "node:worker_threads";
7
7
  import { writeAtomicJson } from "../../shared/atomic-json.ts";
8
8
  import type { AsyncStatus } from "../../shared/types.ts";
9
- import { MISSION_BINDING_FILE } from "../../missions/lifecycle.ts";
9
+ import { readMissionBinding, type MissionLaunchBinding } from "../../missions/lifecycle.ts";
10
+ import { MissionNotFoundError, readMission } from "../../missions/store.ts";
11
+ import type { MissionStatus } from "../../missions/types.ts";
12
+ import { REVIVAL_ORIGIN_FILE } from "../../workflows/workflow-revival.ts";
10
13
  import { ACTIVE_RUN_INDEX_DIR } from "./active-run-index.ts";
11
14
  import { encodeIndexSegment } from "./index-segment.ts";
12
15
  import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
@@ -26,6 +29,8 @@ const RUN_TOMBSTONE_MARKERS_DIR = "async-retention-run-tombstones";
26
29
  const LOCK_STALE_MS = 24 * 60 * 60 * 1000;
27
30
  const RUN_MODES = new Set<AsyncStatus["mode"]>(["single", "parallel", "chain", "workflow"]);
28
31
  const TERMINAL_STATES = new Set<AsyncStatus["state"]>(["complete", "failed", "stopped", "rejected"]);
32
+ // Mirrors TERMINAL_MISSION_STATUSES in src/missions/store.ts, which keeps it private.
33
+ const TERMINAL_MISSION_STATUSES = new Set<MissionStatus>(["completed", "failed", "cancelled"]);
29
34
  const RESULT_TIMESTAMP_FIELDS = ["endedAt", "completedAt", "createdAt", "writtenAt", "expiresAt", "timestamp"] as const;
30
35
 
31
36
  interface RetentionCursor {
@@ -93,7 +98,7 @@ export interface AsyncRetentionOptions {
93
98
  hostname?: string;
94
99
  processStartIdentity?: string;
95
100
  isProcessAlive?: (pid: number) => boolean | undefined;
96
- getProcessStartIdentity?: (pid: number) => string | undefined;
101
+ getProcessStartIdentity?: (pid: number) => Promise<string | undefined>;
97
102
  lstatSync?: typeof fs.lstatSync;
98
103
  signal?: AbortSignal;
99
104
  discoveryWorkerUrl?: URL;
@@ -212,6 +217,25 @@ function missionObserverIndexExists(resultsDir: string, runId: string): boolean
212
217
  return fs.existsSync(path.join(resultsDir, "result-index", "observers", "mission", `${encodeIndexSegment(runId)}.json`));
213
218
  }
214
219
 
220
+ // The retention window doubles as a terminal mission's grace period. Unreadable references and
221
+ // pending syncs are kept because the watcher needs the run's binding to retry.
222
+ function missionReferenceBlocksReclaim(runDir: string, resultsDir: string, runId: string): boolean {
223
+ if (missionObserverIndexExists(resultsDir, runId)) return true;
224
+ let binding: MissionLaunchBinding | undefined;
225
+ try {
226
+ binding = readMissionBinding(runDir);
227
+ } catch {
228
+ return true;
229
+ }
230
+ if (!binding) return false;
231
+ try {
232
+ const mission = readMission(binding.location, binding.missionId);
233
+ return !TERMINAL_MISSION_STATUSES.has(mission.status);
234
+ } catch (error) {
235
+ return !(error instanceof MissionNotFoundError);
236
+ }
237
+ }
238
+
215
239
  function runTombstoneMarkerPath(maintenanceRoot: string, runId: string): string {
216
240
  return path.join(maintenanceRoot, RUN_TOMBSTONE_MARKERS_DIR, `${encodeIndexSegment(runId)}.json`);
217
241
  }
@@ -296,8 +320,10 @@ function runSkipReason(input: {
296
320
  if (activeMarkerExists(input.asyncDirRoot, status.runId)) return "active-index";
297
321
  if (!TERMINAL_STATES.has(status.state)) return "non-terminal";
298
322
  if (status.mode === "workflow" || status.parentWorkflowRunId || status.workflowKey) return "workflow-reference";
323
+ // A revived workflow child is a link in its key's revival chain; deleting it would cut off later revivals.
324
+ if (fs.existsSync(path.join(runDir, REVIVAL_ORIGIN_FILE))) return "workflow-reference";
299
325
  if (hasNestedReferences(status)) return "nested-reference";
300
- if (fs.existsSync(path.join(runDir, MISSION_BINDING_FILE)) || missionObserverIndexExists(input.resultsDir, status.runId)) return "mission-reference";
326
+ if (missionReferenceBlocksReclaim(runDir, input.resultsDir, status.runId)) return "mission-reference";
301
327
  if (hasUnresolvedRunHandoff(runDir, status)) return "handoff-reference";
302
328
  if (hasResumableContract(runDir, status)) return "resumable";
303
329
  const timestamp = statusTimestamp(status, runDir);
@@ -324,16 +350,16 @@ function readCursor(root: string): RetentionCursor {
324
350
  return value?.version === 1 ? value as unknown as RetentionCursor : { version: 1 };
325
351
  }
326
352
 
327
- let currentProcessStartIdentity: string | undefined | null = null;
353
+ let currentProcessStartIdentity: Promise<string | undefined> | undefined;
328
354
 
329
- function processStartIdentity(pid: number): string | undefined {
355
+ function processStartIdentity(pid: number): Promise<string | undefined> {
330
356
  // Foreign PIDs can be reused while this process lives, so resolve them afresh.
331
357
  if (pid !== process.pid) return computeProcessStartIdentity(pid);
332
- if (currentProcessStartIdentity === null) currentProcessStartIdentity = computeProcessStartIdentity(pid);
358
+ currentProcessStartIdentity ??= computeProcessStartIdentity(pid);
333
359
  return currentProcessStartIdentity;
334
360
  }
335
361
 
336
- function computeProcessStartIdentity(pid: number): string | undefined {
362
+ async function computeProcessStartIdentity(pid: number): Promise<string | undefined> {
337
363
  if (process.platform === "linux") {
338
364
  try {
339
365
  const stat = fs.readFileSync(`/proc/${pid}/stat`).toString("utf8");
@@ -346,8 +372,12 @@ function computeProcessStartIdentity(pid: number): string | undefined {
346
372
  }
347
373
  }
348
374
  if (process.platform === "win32") {
349
- const result = spawnSync("powershell.exe", ["-NoProfile", "-Command", `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CreationDate`], { encoding: "utf-8", windowsHide: true });
350
- const started = result.status === 0 ? result.stdout.trim() : "";
375
+ // PowerShell takes ~0.5 s to start; a synchronous spawn would freeze the TUI.
376
+ const started = await new Promise<string>((resolve) => {
377
+ execFile("powershell.exe", ["-NoProfile", "-Command", `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CreationDate`], { encoding: "utf-8", windowsHide: true, timeout: 5_000 }, (error, stdout) => {
378
+ resolve(error ? "" : stdout.trim());
379
+ });
380
+ });
351
381
  return started ? `win:${started}` : undefined;
352
382
  }
353
383
  return undefined;
@@ -381,7 +411,7 @@ function parseLockOwner(lockDir: string): RetentionLockOwner | undefined {
381
411
  return owner as unknown as RetentionLockOwner;
382
412
  }
383
413
 
384
- function staleLock(lockDir: string, now: number, options: Required<Pick<AsyncRetentionOptions, "hostname" | "isProcessAlive" | "getProcessStartIdentity">>): { stale: boolean; token?: string } {
414
+ async function staleLock(lockDir: string, now: number, options: Required<Pick<AsyncRetentionOptions, "hostname" | "isProcessAlive" | "getProcessStartIdentity">>): Promise<{ stale: boolean; token?: string }> {
385
415
  const owner = parseLockOwner(lockDir);
386
416
  if (!owner) {
387
417
  try {
@@ -394,7 +424,7 @@ function staleLock(lockDir: string, now: number, options: Required<Pick<AsyncRet
394
424
  const alive = options.isProcessAlive(owner.pid);
395
425
  if (alive === false) return { stale: true, token: owner.token };
396
426
  if (alive === true && owner.processStartIdentity) {
397
- const currentIdentity = options.getProcessStartIdentity(owner.pid);
427
+ const currentIdentity = await options.getProcessStartIdentity(owner.pid);
398
428
  if (currentIdentity !== undefined && currentIdentity !== owner.processStartIdentity) return { stale: true, token: owner.token };
399
429
  }
400
430
  return { stale: now - owner.startedAt >= LOCK_STALE_MS, token: owner.token };
@@ -416,10 +446,10 @@ function createLockDirectory(lockDir: string, owner: RetentionLockOwner): boolea
416
446
  }
417
447
  }
418
448
 
419
- function acquireRetentionLock(lockDir: string, owner: RetentionLockOwner, options: Required<Pick<AsyncRetentionOptions, "hostname" | "isProcessAlive" | "getProcessStartIdentity">>): boolean {
449
+ async function acquireRetentionLock(lockDir: string, owner: RetentionLockOwner, options: Required<Pick<AsyncRetentionOptions, "hostname" | "isProcessAlive" | "getProcessStartIdentity">>): Promise<boolean> {
420
450
  for (let attempt = 0; attempt < 4; attempt += 1) {
421
451
  if (createLockDirectory(lockDir, owner)) return true;
422
- const stale = staleLock(lockDir, owner.startedAt, options);
452
+ const stale = await staleLock(lockDir, owner.startedAt, options);
423
453
  if (!stale.stale) return false;
424
454
  const staleKey = (stale.token ?? owner.token).replace(/[^A-Za-z0-9._-]/g, "-");
425
455
  const tombstone = `${lockDir}.stale-${staleKey}`;
@@ -672,7 +702,7 @@ export async function cleanupAsyncRetention(options: AsyncRetentionOptions): Pro
672
702
  const pid = options.pid ?? process.pid;
673
703
  const hostname = options.hostname ?? os.hostname();
674
704
  const getProcessStartIdentity = options.getProcessStartIdentity ?? processStartIdentity;
675
- const currentProcessStartIdentity = options.processStartIdentity ?? getProcessStartIdentity(pid) ?? (pid === process.pid ? `runtime:${Math.round(Date.now() - process.uptime() * 1000)}` : undefined);
705
+ const currentProcessStartIdentity = options.processStartIdentity ?? await getProcessStartIdentity(pid) ?? (pid === process.pid ? `runtime:${Math.round(Date.now() - process.uptime() * 1000)}` : undefined);
676
706
  const lockOwner: RetentionLockOwner = { version: 1, token: lockToken, pid, hostname, startedAt: currentTime, ...(currentProcessStartIdentity ? { processStartIdentity: currentProcessStartIdentity } : {}) };
677
707
  const lockOptions = { hostname, isProcessAlive: options.isProcessAlive ?? processIsAlive, getProcessStartIdentity };
678
708
  const result: AsyncRetentionResult = {
@@ -709,7 +739,7 @@ export async function cleanupAsyncRetention(options: AsyncRetentionOptions): Pro
709
739
  return true;
710
740
  };
711
741
  fs.mkdirSync(maintenanceRoot, { recursive: true });
712
- if (!acquireRetentionLock(lockDir, lockOwner, lockOptions)) {
742
+ if (!await acquireRetentionLock(lockDir, lockOwner, lockOptions)) {
713
743
  increment(result.skipped, "lock-busy");
714
744
  return finish();
715
745
  }
@@ -51,6 +51,7 @@ interface AsyncRunStepSummary {
51
51
  structured?: boolean;
52
52
  status: AsyncJobStep["status"];
53
53
  runner?: AsyncJobStep["runner"];
54
+ externalProcess?: AsyncJobStep["externalProcess"];
54
55
  activityState?: ActivityState;
55
56
  lastActivityAt?: number;
56
57
  currentTool?: string;
@@ -357,6 +358,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
357
358
  ...(step.structured ? { structured: step.structured } : {}),
358
359
  status: step.status,
359
360
  ...(step.runner ? { runner: step.runner } : {}),
361
+ ...(step.externalProcess ? { externalProcess: step.externalProcess } : {}),
360
362
  ...(stepActivityState ? { activityState: stepActivityState } : {}),
361
363
  ...(stepLastActivityAt ? { lastActivityAt: stepLastActivityAt } : {}),
362
364
  ...(step.currentTool ? { currentTool: step.currentTool } : {}),
@@ -0,0 +1,76 @@
1
+ import * as fs from "node:fs";
2
+ import { readStatus } from "../../shared/utils.ts";
3
+ import { workflowAwaitedAsyncResultPath } from "./async-execution.ts";
4
+ import { waitForImportedAsyncRoot, type ImportedAsyncRootResult } from "./chain-root-attachment.ts";
5
+ import { currentPidNamespaceScope } from "./pid-namespace.ts";
6
+ import { resultPayloadPathForSessionRun } from "./result-files.ts";
7
+ import { checkPidLiveness } from "./stale-run-reconciler.ts";
8
+
9
+ type ExistingAsyncRunOutcome =
10
+ | { status: "settled"; result: ImportedAsyncRootResult }
11
+ | { status: "unavailable"; reason: string };
12
+
13
+ function errorMessage(error: unknown): string {
14
+ return error instanceof Error ? error.message : String(error);
15
+ }
16
+
17
+ /** Read-only probe: the runner is gone while status still says it is active and no result was published. */
18
+ function runnerExitedWithoutResult(asyncDir: string, runId: string, resultPath: string): boolean {
19
+ const status = readStatus(asyncDir);
20
+ if (!status || (status.state !== "running" && status.state !== "queued") || typeof status.pid !== "number") return false;
21
+ if (status.pidNamespaceScope !== undefined && status.pidNamespaceScope !== currentPidNamespaceScope()) return false;
22
+ if (checkPidLiveness(status.pid) !== "dead") return false;
23
+ return !fs.existsSync(resultPath) && !(status.sessionId && resultPayloadPathForSessionRun(asyncDir, status.sessionId, runId));
24
+ }
25
+
26
+ /**
27
+ * Waits for an existing workflow-awaited async child, identified by its async
28
+ * directory and exact run id, and returns its published result without
29
+ * launching, consuming, or rewriting anything. Anything short of a published
30
+ * result file for that exact run is `unavailable`. Rejects with the signal's
31
+ * reason when aborted.
32
+ */
33
+ export async function awaitExistingAsyncRun(asyncDir: string, runId: string, signal: AbortSignal): Promise<ExistingAsyncRunOutcome> {
34
+ signal.throwIfAborted();
35
+ let status: ReturnType<typeof readStatus>;
36
+ try {
37
+ status = readStatus(asyncDir);
38
+ } catch (error) {
39
+ return { status: "unavailable", reason: `Async status for run '${runId}' is unreadable: ${errorMessage(error)}` };
40
+ }
41
+ if (!status) return { status: "unavailable", reason: `No async status exists for run '${runId}' at ${asyncDir}.` };
42
+ if (status.runId !== runId) return { status: "unavailable", reason: `Async status at ${asyncDir} belongs to run '${status.runId}', not '${runId}'.` };
43
+ // The launcher's initial status has no workflow identity until the runner starts, so only the
44
+ // mode is checked here; a run that does not publish to the workflow result path stays unavailable.
45
+ if (status.mode !== "single") return { status: "unavailable", reason: `Async run '${runId}' is not a single-agent run.` };
46
+ const resultPath = workflowAwaitedAsyncResultPath(asyncDir);
47
+ let runnerExited = false;
48
+ let completed: ImportedAsyncRootResult;
49
+ try {
50
+ completed = await waitForImportedAsyncRoot({ runId, asyncDir, resultPath, index: 0 }, {
51
+ shouldAbort: () => signal.aborted || (runnerExited = runnerExitedWithoutResult(asyncDir, runId, resultPath)),
52
+ });
53
+ } catch (error) {
54
+ signal.throwIfAborted();
55
+ return { status: "unavailable", reason: `Could not await async run '${runId}': ${errorMessage(error)}` };
56
+ }
57
+ signal.throwIfAborted();
58
+ if (runnerExited) return { status: "unavailable", reason: `Async runner for run '${runId}' exited without publishing a result.` };
59
+ // Only a parsed result file carries importedPublication; status-derived fallbacks do not.
60
+ if (!completed.importedPublication) return { status: "unavailable", reason: `Async run '${runId}' ended without a result file at ${resultPath}.` };
61
+ return { status: "settled", result: completed };
62
+ }
63
+
64
+ /**
65
+ * Renames the published result to a file owned by `claimant`. Only one of several
66
+ * concurrent importers can win the rename; the others get undefined and launch fresh.
67
+ */
68
+ export function claimWorkflowAwaitedResult(asyncDir: string, claimant: string): string | undefined {
69
+ const claimedPath = `${workflowAwaitedAsyncResultPath(asyncDir)}.${claimant}.claimed`;
70
+ try {
71
+ fs.renameSync(workflowAwaitedAsyncResultPath(asyncDir), claimedPath);
72
+ return claimedPath;
73
+ } catch {
74
+ return undefined;
75
+ }
76
+ }