@xzzpig/pi-subagents 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/CHANGELOG.md +135 -0
  2. package/README.md +4 -0
  3. package/agents/reviewer.md +3 -4
  4. package/docs/agents.md +343 -0
  5. package/docs/configuration.md +395 -0
  6. package/docs/extension-api.md +308 -0
  7. package/docs/missions.md +121 -0
  8. package/docs/models.md +192 -0
  9. package/docs/observability.md +198 -0
  10. package/docs/tool-reference.md +343 -0
  11. package/docs/watchdog.md +176 -0
  12. package/docs/workflows.md +163 -0
  13. package/package.json +13 -11
  14. package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
  15. package/skills/pi-subagents/references/execution-controls.md +7 -7
  16. package/skills/pi-subagents/references/management-authoring-rpc.md +1 -1
  17. package/skills/pi-subagents/references/prompting-and-roles.md +1 -1
  18. package/src/agents/agents.ts +53 -23
  19. package/src/agents/frontmatter.ts +7 -3
  20. package/src/agents/skills.ts +2 -9
  21. package/src/api/preflight.ts +1 -1
  22. package/src/api/project-panes.ts +30 -0
  23. package/src/extension/config.ts +54 -1
  24. package/src/extension/doctor.ts +40 -0
  25. package/src/extension/fanout-child.ts +5 -4
  26. package/src/extension/index.ts +114 -38
  27. package/src/extension/public-execution.ts +35 -4
  28. package/src/extension/rpc.ts +10 -15
  29. package/src/extension/schemas.ts +33 -11
  30. package/src/extension/subagent-guide.ts +39 -0
  31. package/src/extension/tool-description.ts +38 -18
  32. package/src/inspectors/herdr/actions.ts +11 -2
  33. package/src/inspectors/herdr/inspector-runner.ts +16 -3
  34. package/src/inspectors/herdr/project-panes.ts +459 -63
  35. package/src/intercom/intercom-bridge.ts +7 -2
  36. package/src/intercom/native-supervisor-channel.ts +102 -4
  37. package/src/missions/actions.ts +25 -2
  38. package/src/missions/lifecycle.ts +25 -9
  39. package/src/missions/store.ts +89 -7
  40. package/src/missions/types.ts +33 -0
  41. package/src/missions/workflow-state.ts +25 -15
  42. package/src/runs/background/active-async-capacity.ts +431 -0
  43. package/src/runs/background/active-run-index.ts +46 -0
  44. package/src/runs/background/async-execution.ts +158 -71
  45. package/src/runs/background/async-job-tracker.ts +297 -133
  46. package/src/runs/background/async-resume.ts +37 -5
  47. package/src/runs/background/async-status.ts +39 -5
  48. package/src/runs/background/chain-append.ts +33 -15
  49. package/src/runs/background/completion-replay.ts +267 -0
  50. package/src/runs/background/control-channel.ts +95 -54
  51. package/src/runs/background/fleet-view.ts +18 -5
  52. package/src/runs/background/owned-process-tree.ts +104 -0
  53. package/src/runs/background/process-terminal.ts +17 -3
  54. package/src/runs/background/result-watcher.ts +113 -10
  55. package/src/runs/background/resume-guidance.ts +53 -0
  56. package/src/runs/background/retained-children.ts +14 -6
  57. package/src/runs/background/run-status.ts +119 -5
  58. package/src/runs/background/scheduled-runs.ts +25 -1
  59. package/src/runs/background/stale-run-reconciler.ts +12 -24
  60. package/src/runs/background/subagent-runner.ts +127 -41
  61. package/src/runs/background/subagent-wait.ts +5 -2
  62. package/src/runs/background/wait-completions.ts +39 -5
  63. package/src/runs/background/wait-subscriptions.ts +21 -5
  64. package/src/runs/foreground/async-dismiss-action.ts +85 -0
  65. package/src/runs/foreground/async-steering-action.ts +7 -8
  66. package/src/runs/foreground/chain-execution.ts +40 -2
  67. package/src/runs/foreground/execution.ts +97 -19
  68. package/src/runs/foreground/foreground-control.ts +12 -0
  69. package/src/runs/foreground/foreground-history.ts +137 -0
  70. package/src/runs/foreground/prompt-audit.ts +172 -0
  71. package/src/runs/foreground/subagent-executor.ts +1274 -243
  72. package/src/runs/foreground/workflow-foreground-steering.ts +187 -0
  73. package/src/runs/shared/acceptance.ts +13 -4
  74. package/src/runs/shared/completion-guard.ts +17 -1
  75. package/src/runs/shared/dynamic-fanout.ts +1 -1
  76. package/src/runs/shared/llm-intent-arbiter.ts +302 -0
  77. package/src/runs/shared/model-fallback.ts +8 -4
  78. package/src/runs/shared/model-scope.ts +12 -2
  79. package/src/runs/shared/parallel-utils.ts +3 -0
  80. package/src/runs/shared/pi-args.ts +44 -1
  81. package/src/runs/shared/run-fanout-budget.ts +280 -0
  82. package/src/runs/shared/single-output.ts +4 -2
  83. package/src/runs/shared/subagent-prompt-runtime.ts +94 -9
  84. package/src/runs/shared/task-intent.ts +19 -3
  85. package/src/runs/shared/worktree.ts +20 -7
  86. package/src/shared/agent-stream-options.ts +5 -0
  87. package/src/shared/artifacts.ts +17 -21
  88. package/src/shared/display-text.ts +150 -0
  89. package/src/shared/file-coalescer.ts +9 -0
  90. package/src/shared/fork-context.ts +13 -0
  91. package/src/shared/formatters.ts +4 -6
  92. package/src/shared/node-executable.ts +21 -0
  93. package/src/shared/prompt-resources.ts +51 -0
  94. package/src/shared/settings.ts +15 -2
  95. package/src/shared/types.ts +158 -4
  96. package/src/shared/utf8.ts +11 -0
  97. package/src/shared/utils.ts +46 -34
  98. package/src/slash/prompt-workflows.ts +2 -15
  99. package/src/slash/slash-commands.ts +22 -2
  100. package/src/tui/fleet-status.ts +29 -17
  101. package/src/tui/fleet-transcript.ts +1 -48
  102. package/src/tui/fleet.ts +362 -37
  103. package/src/tui/render.ts +235 -71
  104. package/src/watchdog/change-signature.ts +4 -3
  105. package/src/watchdog/permission-arbiter.ts +2 -1
  106. package/src/watchdog/review.ts +4 -3
  107. package/src/workflows/chat-progress.ts +8 -2
  108. package/src/workflows/scripted-workflow.ts +273 -20
@@ -15,14 +15,15 @@ import {
15
15
  SUBAGENT_CONTROL_INTERCOM_EVENT,
16
16
  SUBAGENT_STEERING_NOTICE_EVENT,
17
17
  } from "../../shared/types.ts";
18
- import { readStatus } from "../../shared/utils.ts";
18
+ import { readStatus, resolveWatchPath } from "../../shared/utils.ts";
19
19
  import { normalizeParallelGroups } from "./parallel-groups.ts";
20
20
  import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
21
- import { hasLiveNestedDescendants, updateAsyncJobNestedProjection } from "../shared/nested-events.ts";
21
+ import { findNestedRouteForRootId, hasLiveNestedDescendants, updateAsyncJobNestedProjection } from "../shared/nested-events.ts";
22
22
  import { listAsyncRuns, type AsyncRunSummary } from "./async-status.ts";
23
23
 
24
24
  interface AsyncJobTrackerOptions {
25
25
  completionRetentionMs?: number;
26
+ /** Slow safety sweep for liveness repair when filesystem events are missed. */
26
27
  pollIntervalMs?: number;
27
28
  resultsDir?: string;
28
29
  widgetEnabled?: boolean;
@@ -34,6 +35,9 @@ const CONTROL_EVENT_READ_CHUNK_BYTES = 64 * 1024;
34
35
  const MAX_CONTROL_EVENT_LINE_BYTES = 1024 * 1024;
35
36
  const CONTROL_EVENT_SCAN_WINDOW_BYTES = 2 * 1024 * 1024;
36
37
  const MAX_RECENT_FLEET_JOBS = 20;
38
+ const DEFAULT_LIVENESS_INTERVAL_MS = 5000;
39
+ const EVENT_REFRESH_DEBOUNCE_MS = 25;
40
+ const WATCH_ATTACHMENT_RETRY_MS = 100;
37
41
 
38
42
  function rememberFleetJob(state: SubagentState, job: AsyncJobState): void {
39
43
  state.fleetJobs ??= new Map();
@@ -51,12 +55,19 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
51
55
  handleComplete: (data: unknown) => void;
52
56
  resetJobs: (ctx?: ExtensionContext) => void;
53
57
  restoreActiveJobs: (ctx?: ExtensionContext) => void;
58
+ dispose: () => void;
54
59
  } {
55
60
  const completionRetentionMs = options.completionRetentionMs ?? 10000;
56
- const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
61
+ const livenessIntervalMs = options.pollIntervalMs ?? DEFAULT_LIVENESS_INTERVAL_MS;
57
62
  const resultsDir = options.resultsDir ?? DIRS.results;
58
63
  const steeringNoticeSeen = new Map<string, number>();
64
+ const jobWatchers = new Map<string, { watchers: Map<string, fs.FSWatcher>; retryTimer?: ReturnType<typeof setTimeout> }>();
65
+ const refreshTimers = new Map<string, ReturnType<typeof setTimeout>>();
66
+ const runningJobIds = new Set<string>();
67
+ let rootWatcher: fs.FSWatcher | undefined;
68
+ let nextLivenessAt = Date.now() + livenessIntervalMs;
59
69
  const rerenderWidget = (ctx: ExtensionContext, jobs = Array.from(state.asyncJobs.values())) => {
70
+ if (state.widgetsSuspended) return;
60
71
  renderWidget(ctx, options.widgetEnabled === false ? [] : jobs);
61
72
  (ctx.ui as { requestRender?: () => void }).requestRender?.();
62
73
  };
@@ -73,6 +84,19 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
73
84
  throw error;
74
85
  }
75
86
  };
87
+ const requestLastWidgetRender = () => {
88
+ const ctx = state.lastUiContext;
89
+ if (!ctx || state.widgetsSuspended || options.widgetEnabled === false) return;
90
+ try {
91
+ if (ctx.hasUI) (ctx.ui as { requestRender?: () => void }).requestRender?.();
92
+ } catch (error) {
93
+ if (error instanceof Error && error.message.includes("extension ctx is stale")) {
94
+ state.lastUiContext = null;
95
+ return;
96
+ }
97
+ throw error;
98
+ }
99
+ };
76
100
  const refreshWidget = (ctx: ExtensionContext) => rerenderWidget(ctx);
77
101
  const restoredControlEventCursor = (asyncDir: string) => {
78
102
  try {
@@ -82,6 +106,14 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
82
106
  throw error;
83
107
  }
84
108
  };
109
+ const findNestedRouteForJob = (runId: string) => {
110
+ try {
111
+ return findNestedRouteForRootId(runId);
112
+ } catch (error) {
113
+ console.error(`Failed to resolve nested event route for '${runId}':`, error);
114
+ return undefined;
115
+ }
116
+ };
85
117
  const summaryToJob = (run: AsyncRunSummary): AsyncJobState => {
86
118
  const groups = normalizeParallelGroups(run.parallelGroups, run.steps.length, run.chainStepCount ?? run.steps.length);
87
119
  const activeGroup = run.currentStep !== undefined
@@ -130,6 +162,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
130
162
  totalTokens: run.totalTokens,
131
163
  sessionFile: run.sessionFile,
132
164
  controlEventCursor: restoredControlEventCursor(run.asyncDir),
165
+ nestedRoute: findNestedRouteForJob(run.id),
133
166
  nestedChildren: run.nestedChildren,
134
167
  parentWorkflowRunId: run.parentWorkflowRunId,
135
168
  workflowKey: run.workflowKey,
@@ -146,6 +179,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
146
179
  cancelCleanup(asyncId);
147
180
  const timer = setTimeout(() => {
148
181
  state.cleanupTimers.delete(asyncId);
182
+ closeJobWatcher(asyncId);
149
183
  state.asyncJobs.delete(asyncId);
150
184
  rerenderLastWidget();
151
185
  }, completionRetentionMs);
@@ -268,139 +302,245 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
268
302
  }
269
303
  };
270
304
 
305
+ const closeJobWatcher = (asyncId: string) => {
306
+ const watched = jobWatchers.get(asyncId);
307
+ if (watched?.retryTimer) clearTimeout(watched.retryTimer);
308
+ for (const watcher of watched?.watchers.values() ?? []) watcher.close();
309
+ jobWatchers.delete(asyncId);
310
+ const timer = refreshTimers.get(asyncId);
311
+ if (timer) clearTimeout(timer);
312
+ refreshTimers.delete(asyncId);
313
+ runningJobIds.delete(asyncId);
314
+ };
315
+
316
+ const refreshJob = (job: AsyncJobState): boolean => {
317
+ const widgetStateBefore = widgetRenderKey(job);
318
+ let nestedRefreshFailed = false;
319
+ const refreshNestedProjection = () => {
320
+ try {
321
+ updateAsyncJobNestedProjection(job);
322
+ } catch (error) {
323
+ nestedRefreshFailed = true;
324
+ console.error(`Failed to refresh nested async descendants for '${job.asyncDir}':`, error);
325
+ }
326
+ };
327
+ try {
328
+ emitNewControlEvents(job);
329
+ try {
330
+ if (job.nestedRoute) reconcileNestedAsyncDescendants(job.nestedRoute, { resultsDir, kill: options.kill, now: options.now });
331
+ } catch (error) {
332
+ nestedRefreshFailed = true;
333
+ console.error(`Failed to refresh nested async descendants for '${job.asyncDir}':`, error);
334
+ }
335
+ refreshNestedProjection();
336
+ const reconciliation = reconcileAsyncRun(job.asyncDir, {
337
+ resultsDir,
338
+ kill: options.kill,
339
+ now: options.now,
340
+ startedRun: {
341
+ runId: job.asyncId,
342
+ pid: job.pid,
343
+ sessionId: job.sessionId,
344
+ mode: job.mode,
345
+ agents: job.agents,
346
+ chainStepCount: job.chainStepCount,
347
+ parallelGroups: job.parallelGroups,
348
+ startedAt: job.startedAt,
349
+ sessionFile: job.sessionFile,
350
+ },
351
+ });
352
+ const status = reconciliation.status ?? readStatus(job.asyncDir);
353
+ if (status) {
354
+ const previousStatus = job.status;
355
+ job.status = status.state;
356
+ if (job.status === "running") runningJobIds.add(job.asyncId);
357
+ else runningJobIds.delete(job.asyncId);
358
+ if (job.status !== "complete" && job.status !== "failed" && job.status !== "paused" && job.status !== "stopped") cancelCleanup(job.asyncId);
359
+ job.sessionId = status.sessionId ?? job.sessionId;
360
+ job.activityState = status.activityState;
361
+ job.lastActivityAt = status.lastActivityAt ?? job.lastActivityAt;
362
+ job.currentTool = status.currentTool;
363
+ job.currentToolStartedAt = status.currentToolStartedAt;
364
+ job.currentPath = status.currentPath;
365
+ job.turnCount = status.turnCount ?? job.turnCount;
366
+ job.toolCount = status.toolCount ?? job.toolCount;
367
+ job.steering = status.steering ?? job.steering;
368
+ job.mode = status.mode;
369
+ job.parentWorkflowRunId = status.parentWorkflowRunId ?? job.parentWorkflowRunId;
370
+ job.workflowKey = status.workflowKey ?? job.workflowKey;
371
+ job.workflow = status.workflow ?? job.workflow;
372
+ job.currentStep = status.currentStep ?? job.currentStep;
373
+ job.chainStepCount = status.chainStepCount ?? job.chainStepCount;
374
+ job.startedAt = status.startedAt ?? job.startedAt;
375
+ if (status.lastUpdate !== undefined) job.updatedAt = status.lastUpdate;
376
+ if (status.steps?.length) {
377
+ const groups = normalizeParallelGroups(status.parallelGroups, status.steps.length, status.chainStepCount ?? status.steps.length);
378
+ job.parallelGroups = groups.length ? groups : job.parallelGroups;
379
+ job.hasParallelGroups = groups.length > 0 || job.hasParallelGroups;
380
+ const activeGroup = status.currentStep !== undefined
381
+ ? groups.find((group) => status.currentStep! >= group.start && status.currentStep! < group.start + group.count)
382
+ : undefined;
383
+ const visibleSteps = activeGroup
384
+ ? status.steps.slice(activeGroup.start, activeGroup.start + activeGroup.count).map((step, index) => ({ ...step, index: activeGroup.start + index }))
385
+ : status.steps.map((step, index) => ({ ...step, index }));
386
+ job.activeParallelGroup = Boolean(activeGroup);
387
+ job.agents = visibleSteps.map((step) => step.agent);
388
+ job.steps = visibleSteps;
389
+ refreshNestedProjection();
390
+ job.stepsTotal = visibleSteps.length;
391
+ job.runningSteps = visibleSteps.filter((step) => step.status === "running").length;
392
+ job.completedSteps = visibleSteps.filter((step) => step.status === "complete" || step.status === "completed").length;
393
+ if (status.state === "complete") job.completedSteps = visibleSteps.length;
394
+ }
395
+ job.sessionDir = status.sessionDir ?? job.sessionDir;
396
+ job.outputFile = status.outputFile ?? job.outputFile;
397
+ job.totalTokens = status.totalTokens ?? job.totalTokens;
398
+ job.timeoutMs = status.timeoutMs ?? job.timeoutMs;
399
+ job.deadlineAt = status.deadlineAt ?? job.deadlineAt;
400
+ job.timedOut = status.timedOut ?? job.timedOut;
401
+ job.stopped = status.stopped ?? job.stopped;
402
+ job.turnBudget = status.turnBudget ?? job.turnBudget;
403
+ job.turnBudgetExceeded = status.turnBudgetExceeded ?? job.turnBudgetExceeded;
404
+ job.wrapUpRequested = status.wrapUpRequested ?? job.wrapUpRequested;
405
+ job.sessionFile = status.sessionFile ?? job.sessionFile;
406
+ if (job.status === "complete" || job.status === "failed" || job.status === "paused" || job.status === "stopped") {
407
+ rememberFleetJob(state, job);
408
+ if (!nestedRefreshFailed && !hasLiveNestedDescendants(job.nestedChildren) && (previousStatus !== job.status || !state.cleanupTimers.has(job.asyncId))) {
409
+ scheduleCleanup(job.asyncId);
410
+ }
411
+ }
412
+ return widgetRenderKey(job) !== widgetStateBefore;
413
+ }
414
+ if (job.status === "queued") {
415
+ job.status = "running";
416
+ job.updatedAt = Date.now();
417
+ runningJobIds.add(job.asyncId);
418
+ }
419
+ } catch (error) {
420
+ if (job.status !== "failed") {
421
+ console.error(`Failed to read async status for '${job.asyncDir}':`, error);
422
+ job.status = "failed";
423
+ job.updatedAt = Date.now();
424
+ }
425
+ runningJobIds.delete(job.asyncId);
426
+ rememberFleetJob(state, job);
427
+ if (!hasLiveNestedDescendants(job.nestedChildren) && !state.cleanupTimers.has(job.asyncId)) scheduleCleanup(job.asyncId);
428
+ }
429
+ return widgetRenderKey(job) !== widgetStateBefore;
430
+ };
431
+
432
+ const scheduleJobRefresh = (asyncId: string, delayMs = EVENT_REFRESH_DEBOUNCE_MS) => {
433
+ if (refreshTimers.has(asyncId)) return;
434
+ const timer = setTimeout(() => {
435
+ refreshTimers.delete(asyncId);
436
+ const job = state.asyncJobs.get(asyncId);
437
+ if (job && refreshJob(job)) rerenderLastWidget();
438
+ }, delayMs);
439
+ timer.unref?.();
440
+ refreshTimers.set(asyncId, timer);
441
+ };
442
+
443
+ const watchJob = (job: AsyncJobState) => {
444
+ const watched = jobWatchers.get(job.asyncId) ?? { watchers: new Map<string, fs.FSWatcher>() };
445
+ const active = job.status === "queued" || job.status === "running";
446
+ const watchPath = (watchPath: string): boolean => {
447
+ if (watched.watchers.has(watchPath)) return true;
448
+ const nestedEventSink = job.nestedRoute?.eventSink === watchPath;
449
+ let watcher: fs.FSWatcher;
450
+ try {
451
+ watcher = fs.watch(resolveWatchPath(watchPath), (_event, file) => {
452
+ const rawFileName = file?.toString();
453
+ const fileName = rawFileName ?? path.basename(watchPath);
454
+ const nestedEventFile = nestedEventSink && (!rawFileName || rawFileName.endsWith(".json") || rawFileName.endsWith(".jsonl"));
455
+ if (fileName === "status.json" || fileName === "events.jsonl" || nestedEventFile) {
456
+ scheduleJobRefresh(job.asyncId);
457
+ }
458
+ if (watchPath !== job.asyncDir && !nestedEventSink) {
459
+ watcher.close();
460
+ watched.watchers.delete(watchPath);
461
+ watchJob(job);
462
+ }
463
+ });
464
+ } catch {
465
+ return false;
466
+ }
467
+ watcher.on("error", () => {
468
+ watcher.close();
469
+ watched.watchers.delete(watchPath);
470
+ if (watchPath.endsWith("status.json") || nestedEventSink) watchJob(job);
471
+ });
472
+ watcher.unref?.();
473
+ watched.watchers.set(watchPath, watcher);
474
+ return true;
475
+ };
476
+ watchPath(job.asyncDir);
477
+ const statusPath = path.join(job.asyncDir, "status.json");
478
+ const hadStatusWatcher = watched.watchers.has(statusPath);
479
+ const statusWatched = watchPath(statusPath);
480
+ if (statusWatched && !hadStatusWatcher) scheduleJobRefresh(job.asyncId);
481
+ watchPath(path.join(job.asyncDir, "events.jsonl"));
482
+ if (job.nestedRoute) watchPath(job.nestedRoute.eventSink);
483
+ if (!statusWatched && active && !watched.retryTimer) {
484
+ watched.retryTimer = setTimeout(() => {
485
+ watched.retryTimer = undefined;
486
+ const current = state.asyncJobs.get(job.asyncId);
487
+ if (current) watchJob(current);
488
+ }, WATCH_ATTACHMENT_RETRY_MS);
489
+ watched.retryTimer.unref?.();
490
+ } else if (statusWatched && watched.retryTimer) {
491
+ clearTimeout(watched.retryTimer);
492
+ watched.retryTimer = undefined;
493
+ }
494
+ if (watched.watchers.size > 0 || watched.retryTimer) jobWatchers.set(job.asyncId, watched);
495
+ else jobWatchers.delete(job.asyncId);
496
+ };
497
+
498
+ const watchAsyncRoot = () => {
499
+ if (rootWatcher) return;
500
+ try {
501
+ rootWatcher = fs.watch(resolveWatchPath(asyncDirRoot), (_event, file) => {
502
+ const runDirName = file?.toString();
503
+ for (const job of state.asyncJobs.values()) {
504
+ if (jobWatchers.has(job.asyncId) || (runDirName && path.basename(job.asyncDir) !== runDirName)) continue;
505
+ watchJob(job);
506
+ if (jobWatchers.has(job.asyncId)) scheduleJobRefresh(job.asyncId);
507
+ }
508
+ });
509
+ rootWatcher.on("error", () => {
510
+ rootWatcher?.close();
511
+ rootWatcher = undefined;
512
+ });
513
+ rootWatcher.unref?.();
514
+ } catch {
515
+ // The liveness sweep retries if the async root is not available yet.
516
+ }
517
+ };
518
+
271
519
  const ensurePoller = () => {
520
+ watchAsyncRoot();
272
521
  if (state.poller) return;
522
+ nextLivenessAt = Date.now() + livenessIntervalMs;
273
523
  state.poller = setInterval(() => {
274
524
  if (state.asyncJobs.size === 0) {
275
525
  rerenderLastWidget([]);
276
- if (state.poller) {
277
- clearInterval(state.poller);
278
- state.poller = null;
279
- }
526
+ if (state.poller) clearInterval(state.poller);
527
+ state.poller = null;
528
+ rootWatcher?.close();
529
+ rootWatcher = undefined;
280
530
  return;
281
531
  }
282
-
283
- let widgetChanged = false;
284
- for (const job of state.asyncJobs.values()) {
285
- const widgetStateBefore = widgetRenderKey(job);
286
- let nestedRefreshFailed = false;
287
- const refreshNestedProjection = () => {
288
- try {
289
- updateAsyncJobNestedProjection(job);
290
- } catch (error) {
291
- nestedRefreshFailed = true;
292
- console.error(`Failed to refresh nested async descendants for '${job.asyncDir}':`, error);
293
- }
294
- };
295
- const reconcileNestedDescendants = () => {
296
- try {
297
- if (job.nestedRoute) reconcileNestedAsyncDescendants(job.nestedRoute, { resultsDir, kill: options.kill, now: options.now });
298
- } catch (error) {
299
- nestedRefreshFailed = true;
300
- console.error(`Failed to refresh nested async descendants for '${job.asyncDir}':`, error);
301
- }
302
- refreshNestedProjection();
303
- };
304
- try {
305
- emitNewControlEvents(job);
306
- reconcileNestedDescendants();
307
- const reconciliation = reconcileAsyncRun(job.asyncDir, {
308
- resultsDir,
309
- kill: options.kill,
310
- now: options.now,
311
- startedRun: {
312
- runId: job.asyncId,
313
- pid: job.pid,
314
- sessionId: job.sessionId,
315
- mode: job.mode,
316
- agents: job.agents,
317
- chainStepCount: job.chainStepCount,
318
- parallelGroups: job.parallelGroups,
319
- startedAt: job.startedAt,
320
- sessionFile: job.sessionFile,
321
- },
322
- });
323
- const status = reconciliation.status ?? readStatus(job.asyncDir);
324
- if (status) {
325
- const previousStatus = job.status;
326
- job.status = status.state;
327
- if (job.status !== "complete" && job.status !== "failed" && job.status !== "paused" && job.status !== "stopped") cancelCleanup(job.asyncId);
328
- job.sessionId = status.sessionId ?? job.sessionId;
329
- job.activityState = status.activityState;
330
- job.lastActivityAt = status.lastActivityAt ?? job.lastActivityAt;
331
- job.currentTool = status.currentTool;
332
- job.currentToolStartedAt = status.currentToolStartedAt;
333
- job.currentPath = status.currentPath;
334
- job.turnCount = status.turnCount ?? job.turnCount;
335
- job.toolCount = status.toolCount ?? job.toolCount;
336
- job.steering = status.steering ?? job.steering;
337
- job.mode = status.mode;
338
- job.parentWorkflowRunId = status.parentWorkflowRunId ?? job.parentWorkflowRunId;
339
- job.workflowKey = status.workflowKey ?? job.workflowKey;
340
- job.workflow = status.workflow ?? job.workflow;
341
- job.currentStep = status.currentStep ?? job.currentStep;
342
- job.chainStepCount = status.chainStepCount ?? job.chainStepCount;
343
- job.startedAt = status.startedAt ?? job.startedAt;
344
- if (status.lastUpdate !== undefined) job.updatedAt = status.lastUpdate;
345
- if (status.steps?.length) {
346
- const groups = normalizeParallelGroups(status.parallelGroups, status.steps.length, status.chainStepCount ?? status.steps.length);
347
- job.parallelGroups = groups.length ? groups : job.parallelGroups;
348
- job.hasParallelGroups = groups.length > 0 || job.hasParallelGroups;
349
- const activeGroup = status.currentStep !== undefined
350
- ? groups.find((group) => status.currentStep! >= group.start && status.currentStep! < group.start + group.count)
351
- : undefined;
352
- const visibleSteps = activeGroup
353
- ? status.steps.slice(activeGroup.start, activeGroup.start + activeGroup.count).map((step, index) => ({ ...step, index: activeGroup.start + index }))
354
- : status.steps.map((step, index) => ({ ...step, index }));
355
- job.activeParallelGroup = Boolean(activeGroup);
356
- job.agents = visibleSteps.map((step) => step.agent);
357
- job.steps = visibleSteps;
358
- refreshNestedProjection();
359
- job.stepsTotal = visibleSteps.length;
360
- job.runningSteps = visibleSteps.filter((step) => step.status === "running").length;
361
- job.completedSteps = visibleSteps.filter((step) => step.status === "complete" || step.status === "completed").length;
362
- if (status.state === "complete") job.completedSteps = visibleSteps.length;
363
- }
364
- job.sessionDir = status.sessionDir ?? job.sessionDir;
365
- job.outputFile = status.outputFile ?? job.outputFile;
366
- job.totalTokens = status.totalTokens ?? job.totalTokens;
367
- job.timeoutMs = status.timeoutMs ?? job.timeoutMs;
368
- job.deadlineAt = status.deadlineAt ?? job.deadlineAt;
369
- job.timedOut = status.timedOut ?? job.timedOut;
370
- job.stopped = status.stopped ?? job.stopped;
371
- job.turnBudget = status.turnBudget ?? job.turnBudget;
372
- job.turnBudgetExceeded = status.turnBudgetExceeded ?? job.turnBudgetExceeded;
373
- job.wrapUpRequested = status.wrapUpRequested ?? job.wrapUpRequested;
374
- job.sessionFile = status.sessionFile ?? job.sessionFile;
375
- if (job.status === "complete" || job.status === "failed" || job.status === "paused" || job.status === "stopped") {
376
- rememberFleetJob(state, job);
377
- if (!nestedRefreshFailed && !hasLiveNestedDescendants(job.nestedChildren) && (previousStatus !== job.status || !state.cleanupTimers.has(job.asyncId))) {
378
- scheduleCleanup(job.asyncId);
379
- }
380
- }
381
- if (widgetRenderKey(job) !== widgetStateBefore) widgetChanged = true;
382
- continue;
383
- }
384
- if (job.status === "queued") {
385
- job.status = "running";
386
- job.updatedAt = Date.now();
387
- }
388
- } catch (error) {
389
- if (job.status !== "failed") {
390
- console.error(`Failed to read async status for '${job.asyncDir}':`, error);
391
- job.status = "failed";
392
- job.updatedAt = Date.now();
393
- }
394
- rememberFleetJob(state, job);
395
- if (!hasLiveNestedDescendants(job.nestedChildren) && !state.cleanupTimers.has(job.asyncId)) {
396
- scheduleCleanup(job.asyncId);
397
- }
532
+ const now = Date.now();
533
+ if (now >= nextLivenessAt) {
534
+ nextLivenessAt = now + livenessIntervalMs;
535
+ let widgetChanged = false;
536
+ for (const job of state.asyncJobs.values()) {
537
+ watchJob(job);
538
+ if (refreshJob(job)) widgetChanged = true;
398
539
  }
399
- if (widgetRenderKey(job) !== widgetStateBefore) widgetChanged = true;
540
+ if (widgetChanged) rerenderLastWidget();
400
541
  }
401
-
402
- if (widgetChanged) rerenderLastWidget();
403
- }, pollIntervalMs);
542
+ if (runningJobIds.size > 0) requestLastWidgetRender();
543
+ }, Math.min(POLL_INTERVAL_MS, livenessIntervalMs));
404
544
  state.poller.unref?.();
405
545
  };
406
546
 
@@ -417,10 +557,13 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
417
557
  const agents = firstGroupCount && firstGroupCount > 0
418
558
  ? rawAgents?.slice(0, firstGroupCount)
419
559
  : rawAgents;
560
+ const sessionRoot = state.liveAsyncSessionRoots?.get(info.id);
561
+ state.liveAsyncSessionRoots?.delete(info.id);
420
562
  state.asyncJobs.set(info.id, {
421
563
  asyncId: info.id,
422
564
  asyncDir,
423
565
  ...(typeof info.cwd === "string" ? { cwd: path.resolve(info.cwd) } : {}),
566
+ ...(sessionRoot ? { sessionRoot } : {}),
424
567
  status: "queued",
425
568
  pid: typeof info.pid === "number" ? info.pid : undefined,
426
569
  ...(typeof info.sessionId === "string" ? { sessionId: info.sessionId } : {}),
@@ -442,7 +585,10 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
442
585
  workflowKey: info.workflowKey,
443
586
  controlEventCursor: 0,
444
587
  });
445
- rememberFleetJob(state, state.asyncJobs.get(info.id)!);
588
+ const job = state.asyncJobs.get(info.id)!;
589
+ rememberFleetJob(state, job);
590
+ watchJob(job);
591
+ scheduleJobRefresh(info.id, 0);
446
592
  ensurePoller();
447
593
  rerenderLastWidget();
448
594
  };
@@ -456,9 +602,14 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
456
602
  let nestedRefreshFailed = false;
457
603
  if (job) {
458
604
  job.status = result.state ?? (result.success ? "complete" : "failed");
605
+ runningJobIds.delete(asyncId);
459
606
  job.stopped = result.stopped ?? job.stopped;
460
607
  job.updatedAt = Date.now();
461
- if (result.asyncDir) job.asyncDir = result.asyncDir;
608
+ if (result.asyncDir && result.asyncDir !== job.asyncDir) {
609
+ closeJobWatcher(asyncId);
610
+ job.asyncDir = result.asyncDir;
611
+ watchJob(job);
612
+ }
462
613
  try {
463
614
  updateAsyncJobNestedProjection(job);
464
615
  } catch (error) {
@@ -471,14 +622,25 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
471
622
  if (!nestedRefreshFailed && !hasLiveNestedDescendants(job?.nestedChildren)) scheduleCleanup(asyncId);
472
623
  };
473
624
 
625
+ const dispose = () => {
626
+ if (state.poller) clearInterval(state.poller);
627
+ state.poller = null;
628
+ rootWatcher?.close();
629
+ rootWatcher = undefined;
630
+ for (const asyncId of jobWatchers.keys()) closeJobWatcher(asyncId);
631
+ for (const timer of refreshTimers.values()) clearTimeout(timer);
632
+ refreshTimers.clear();
633
+ runningJobIds.clear();
634
+ };
635
+
474
636
  const resetJobs = (ctx?: ExtensionContext) => {
475
- for (const timer of state.cleanupTimers.values()) {
476
- clearTimeout(timer);
477
- }
637
+ dispose();
638
+ for (const timer of state.cleanupTimers.values()) clearTimeout(timer);
478
639
  state.cleanupTimers.clear();
479
640
  state.asyncJobs.clear();
480
641
  state.fleetJobs?.clear();
481
642
  state.foregroundControls?.clear();
643
+ state.liveAsyncSessionRoots?.clear();
482
644
  state.lastForegroundControlId = null;
483
645
  state.resultFileCoalescer.clear();
484
646
  if (ctx?.hasUI) {
@@ -500,12 +662,14 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
500
662
  for (const run of runs) {
501
663
  const job = summaryToJob(run);
502
664
  state.asyncJobs.set(run.id, job);
665
+ if (job.status === "running") runningJobIds.add(job.asyncId);
503
666
  rememberFleetJob(state, job);
667
+ watchJob(job);
504
668
  }
505
669
  if (runs.length === 0) return;
506
670
  ensurePoller();
507
671
  rerenderLastWidget();
508
672
  };
509
673
 
510
- return { ensurePoller, refreshWidget, handleStarted, handleComplete, resetJobs, restoreActiveJobs };
674
+ return { ensurePoller, refreshWidget, handleStarted, handleComplete, resetJobs, restoreActiveJobs, dispose };
511
675
  }
@@ -1,10 +1,11 @@
1
1
  import * as fs from "node:fs";
2
2
  import * as path from "node:path";
3
- import { DIRS, type AcceptanceInput, type AsyncStatus, type SteeringRecoveryDescriptor } from "../../shared/types.ts";
3
+ import { DIRS, type AcceptanceInput, type AsyncStatus, type ResolvedTurnBudget, type SteeringRecoveryDescriptor } from "../../shared/types.ts";
4
4
  import type { AgentConfig } from "../../agents/agents.ts";
5
5
  import { validateAcceptanceInput } from "../shared/acceptance.ts";
6
6
  import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
7
7
  import { intersectSubagentCapabilityCeilings, parseSubagentCapabilityCeiling, type ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
8
+ import { validateRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.ts";
8
9
  import { resolveTurnBudgetConfig } from "../shared/turn-budget.ts";
9
10
  import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
10
11
 
@@ -273,6 +274,23 @@ function normalizeRecoveryAcceptance(value: unknown, descriptorPath: string): Ac
273
274
  return value as AcceptanceInput;
274
275
  }
275
276
 
277
+ function normalizeRecoveryTurnBudget(value: unknown, descriptorPath: string): ResolvedTurnBudget {
278
+ if (value && typeof value === "object" && !Array.isArray(value)) {
279
+ const {
280
+ outcome: _outcome,
281
+ turnCount: _turnCount,
282
+ wrapUpRequestedAtTurn: _wrapUpRequestedAtTurn,
283
+ terminationDeferredAtTurn: _terminationDeferredAtTurn,
284
+ exceededAtTurn: _exceededAtTurn,
285
+ ...publicTurnBudget
286
+ } = value as Record<string, unknown>;
287
+ value = publicTurnBudget;
288
+ }
289
+ const result = resolveTurnBudgetConfig(value, "recoveryDescriptor.initialTurnBudget");
290
+ if (result.error || !result.turnBudget) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${result.error ?? "recoveryDescriptor.initialTurnBudget is invalid."}`);
291
+ return result.turnBudget;
292
+ }
293
+
276
294
  export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): SteeringRecoveryDescriptor | undefined {
277
295
  if (!asyncDir) return undefined;
278
296
  const descriptorPath = path.join(asyncDir, "recovery-descriptor.json");
@@ -289,8 +307,8 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
289
307
  "version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sessionFile", "cwd", "model", "fallbackModels", "thinking", "tools", "extensions",
290
308
  "subagentOnlyExtensions", "mcpDirectTools", "systemPrompt", "systemPromptMode", "inheritProjectContext", "inheritSkills", "skills",
291
309
  "skillPath", "agentFilePath", "completionGuard", "memory", "outputPath", "outputMode", "structuredOutputSchema", "acceptance", "sessionDir", "artifactConfig",
292
- "artifactsDir", "maxOutput", "controlConfig", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
293
- "launchResolvedExtensions",
310
+ "artifactsDir", "maxOutput", "controlConfig", "intercomBridge", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
311
+ "launchResolvedExtensions", "runFanoutBudget",
294
312
  ]);
295
313
  for (const field of Object.keys(parsed)) {
296
314
  if (!allowedFields.has(field)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': unknown field '${field}'.`);
@@ -300,6 +318,11 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
300
318
  if (typeof parsed[field] !== "string" || !(parsed[field] as string).trim()) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a non-empty string.`);
301
319
  }
302
320
  if (parsed.version !== 1) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': version must be 1.`);
321
+ try {
322
+ parsed.runFanoutBudget = validateRunFanoutBudgetDescriptor(parsed.runFanoutBudget);
323
+ } catch (error) {
324
+ throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${error instanceof Error ? error.message : String(error)}`);
325
+ }
303
326
  if (parsed.capabilityCeiling !== undefined) parsed.capabilityCeiling = parseSubagentCapabilityCeiling(parsed.capabilityCeiling, `async recovery descriptor '${descriptorPath}' capabilityCeiling`);
304
327
  if (parsed.agentContract !== undefined) {
305
328
  if (!parsed.agentContract || typeof parsed.agentContract !== "object" || Array.isArray(parsed.agentContract)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': agentContract must be an object.`);
@@ -329,8 +352,7 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
329
352
  }
330
353
  if (parsed.absoluteDeadlineAt !== undefined && (!Number.isFinite(parsed.absoluteDeadlineAt) || (parsed.absoluteDeadlineAt as number) <= 0)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': absoluteDeadlineAt must be a positive timestamp.`);
331
354
  if (parsed.initialTurnBudget !== undefined) {
332
- const result = resolveTurnBudgetConfig(parsed.initialTurnBudget, "recoveryDescriptor.initialTurnBudget");
333
- if (result.error) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${result.error}`);
355
+ parsed.initialTurnBudget = normalizeRecoveryTurnBudget(parsed.initialTurnBudget, descriptorPath);
334
356
  }
335
357
  if (parsed.initialToolBudget !== undefined) {
336
358
  const result = validateToolBudgetConfig(parsed.initialToolBudget, "recoveryDescriptor.initialToolBudget");
@@ -352,6 +374,16 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
352
374
  if (artifact.includeTranscript !== undefined && typeof artifact.includeTranscript !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.includeTranscript must be a boolean.`);
353
375
  if (!Number.isInteger(artifact.cleanupDays) || (artifact.cleanupDays as number) < 0) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.cleanupDays must be a non-negative integer.`);
354
376
  }
377
+ if (parsed.intercomBridge !== undefined) {
378
+ if (!parsed.intercomBridge || typeof parsed.intercomBridge !== "object" || Array.isArray(parsed.intercomBridge)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge must be an object.`);
379
+ const bridge = parsed.intercomBridge as Record<string, unknown>;
380
+ for (const field of Object.keys(bridge)) {
381
+ if (field !== "mode" && field !== "instructionFile" && field !== "resultDelivery") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.${field} is not supported.`);
382
+ }
383
+ if (bridge.mode !== undefined && bridge.mode !== "off" && bridge.mode !== "fork-only" && bridge.mode !== "always") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.mode is invalid.`);
384
+ if (bridge.instructionFile !== undefined && typeof bridge.instructionFile !== "string") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.instructionFile must be a string.`);
385
+ if (bridge.resultDelivery !== undefined && typeof bridge.resultDelivery !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.resultDelivery must be a boolean.`);
386
+ }
355
387
  if (parsed.controlConfig !== undefined) {
356
388
  if (!parsed.controlConfig || typeof parsed.controlConfig !== "object" || Array.isArray(parsed.controlConfig)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig must be an object.`);
357
389
  const control = parsed.controlConfig as Record<string, unknown>;