@xzzpig/pi-subagents 0.13.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (202) hide show
  1. package/CHANGELOG.md +243 -0
  2. package/README.md +6 -5
  3. package/agents/evidence-auditor.md +34 -0
  4. package/agents/researcher.md +23 -13
  5. package/agents/reviewer.md +3 -2
  6. package/docs/agents.md +56 -15
  7. package/docs/configuration.md +93 -15
  8. package/docs/extension-api.md +132 -19
  9. package/docs/missions.md +10 -2
  10. package/docs/models.md +11 -22
  11. package/docs/observability.md +67 -11
  12. package/docs/standalone-background.md +59 -0
  13. package/docs/tool-reference.md +42 -23
  14. package/docs/watchdog.md +39 -10
  15. package/docs/workflows.md +58 -19
  16. package/index.ts +5 -2
  17. package/inspector-runner.mjs +2 -2
  18. package/node_modules/@xzzpig/pi-components/CHANGELOG.md +19 -0
  19. package/node_modules/@xzzpig/pi-components/README.md +28 -0
  20. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +46 -4
  21. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +65 -17
  22. package/node_modules/@xzzpig/pi-components/package.json +1 -1
  23. package/node_modules/@xzzpig/pi-components/src/transcript.ts +107 -14
  24. package/package.json +10 -5
  25. package/prompts/parallel-review.md +1 -1
  26. package/runner-peer-loader.mjs +24 -0
  27. package/runner-peer-preload.mjs +36 -0
  28. package/skills/pi-subagents/SKILL.md +34 -22
  29. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  30. package/skills/pi-subagents/references/execution-controls.md +27 -8
  31. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  32. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
  33. package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
  34. package/skills/pi-subagents/references/review-and-validation.md +3 -3
  35. package/src/agents/advertised-agent-prompt.ts +94 -0
  36. package/src/agents/agent-management.ts +71 -59
  37. package/src/agents/agent-serializer.ts +6 -3
  38. package/src/agents/agents.ts +198 -72
  39. package/src/agents/builtin-names.ts +1 -0
  40. package/src/agents/chain-serializer.ts +5 -0
  41. package/src/agents/runtime-agent-registry.ts +7 -6
  42. package/src/api/delegation.ts +4 -0
  43. package/src/api/preflight.ts +110 -71
  44. package/src/api/required-child-extensions.ts +6 -0
  45. package/src/api/shared-types.ts +3 -1
  46. package/src/api/workflow-resources.ts +6 -0
  47. package/src/extension/config.ts +14 -37
  48. package/src/extension/fanout-child.ts +68 -5
  49. package/src/extension/herdr-pi-bridge.ts +164 -0
  50. package/src/extension/index.ts +141 -51
  51. package/src/extension/public-execution.ts +7 -6
  52. package/src/extension/rpc.ts +8 -21
  53. package/src/extension/schemas.ts +86 -84
  54. package/src/extension/tool-description.ts +32 -79
  55. package/src/inspectors/actions.ts +148 -0
  56. package/src/inspectors/ghostty/actions.ts +74 -0
  57. package/src/inspectors/ghostty/plugin.ts +17 -0
  58. package/src/inspectors/herdr/actions.ts +99 -179
  59. package/src/inspectors/herdr/plugin.ts +20 -0
  60. package/src/inspectors/herdr/project-panes.ts +4 -1
  61. package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
  62. package/src/inspectors/plugins.ts +8 -0
  63. package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
  64. package/src/inspectors/types.ts +51 -0
  65. package/src/integrations/pi-web-session-liveness.ts +73 -0
  66. package/src/intercom/intercom-bridge.ts +50 -8
  67. package/src/intercom/native-supervisor-channel.ts +142 -115
  68. package/src/intercom/supervisor-ui.ts +3 -2
  69. package/src/missions/workflow-state.ts +37 -16
  70. package/src/policy/authority.ts +4 -0
  71. package/src/profiles/profiles.ts +12 -6
  72. package/src/runs/background/active-async-capacity.ts +22 -18
  73. package/src/runs/background/active-run-index.ts +17 -1
  74. package/src/runs/background/async-execution.ts +359 -176
  75. package/src/runs/background/async-job-tracker.ts +41 -7
  76. package/src/runs/background/async-resume.ts +19 -12
  77. package/src/runs/background/async-retention.ts +20 -0
  78. package/src/runs/background/async-status-snapshot.ts +10 -12
  79. package/src/runs/background/async-status.ts +32 -13
  80. package/src/runs/background/auto-drain.ts +59 -35
  81. package/src/runs/background/binary-bootstrap.ts +38 -0
  82. package/src/runs/background/chain-append.ts +1 -1
  83. package/src/runs/background/chain-root-attachment.ts +22 -33
  84. package/src/runs/background/control-channel.ts +78 -44
  85. package/src/runs/background/fleet-view.ts +30 -2
  86. package/src/runs/background/notify.ts +193 -19
  87. package/src/runs/background/owned-process-tree.ts +35 -8
  88. package/src/runs/background/process-terminal.ts +23 -23
  89. package/src/runs/background/result-files.ts +8 -4
  90. package/src/runs/background/result-watcher.ts +19 -2
  91. package/src/runs/background/retained-nested-route-tracker.ts +96 -0
  92. package/src/runs/background/run-child-session.ts +118 -41
  93. package/src/runs/background/run-status.ts +78 -5
  94. package/src/runs/background/runner-aliases.ts +22 -5
  95. package/src/runs/background/runner-child-launch.ts +93 -0
  96. package/src/runs/background/runner-child-sessions.ts +5 -4
  97. package/src/runs/background/runner-http-dispatcher.ts +119 -0
  98. package/src/runs/background/scheduled-runs.ts +51 -18
  99. package/src/runs/background/stale-run-reconciler.ts +38 -12
  100. package/src/runs/background/steering.ts +20 -2
  101. package/src/runs/background/subagent-runner.ts +766 -432
  102. package/src/runs/background/subagent-wait.ts +179 -28
  103. package/src/runs/background/wait-completions.ts +79 -27
  104. package/src/runs/background/wait-subscriptions.ts +9 -3
  105. package/src/runs/background/wait-tool.ts +5 -3
  106. package/src/runs/foreground/async-steering-action.ts +37 -7
  107. package/src/runs/foreground/async-stop-action.ts +93 -3
  108. package/src/runs/foreground/execution.ts +174 -194
  109. package/src/runs/foreground/foreground-history.ts +5 -2
  110. package/src/runs/foreground/prompt-audit.ts +12 -6
  111. package/src/runs/foreground/subagent-executor.ts +896 -397
  112. package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
  113. package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
  114. package/src/runs/shared/acceptance.ts +54 -14
  115. package/src/runs/shared/agent-contract.ts +1 -1
  116. package/src/runs/shared/async-status-projection.ts +172 -78
  117. package/src/runs/shared/capability-ceiling.ts +2 -0
  118. package/src/runs/shared/child-hooks.ts +167 -3
  119. package/src/runs/shared/child-launch-plan.ts +15 -3
  120. package/src/runs/shared/child-launch.ts +44 -16
  121. package/src/runs/shared/child-lifecycle.ts +6 -3
  122. package/src/runs/shared/child-runtime-config.ts +8 -1
  123. package/src/runs/shared/child-session.ts +130 -24
  124. package/src/runs/shared/child-tool-plan.ts +145 -14
  125. package/src/runs/shared/completion-evidence.ts +2 -2
  126. package/src/runs/shared/completion-guard.ts +6 -3
  127. package/src/runs/shared/dynamic-fanout.ts +2 -2
  128. package/src/runs/shared/effective-system-prompt.ts +33 -0
  129. package/src/runs/shared/external-cli-contract.ts +11 -1
  130. package/src/runs/shared/external-cli-preflight.ts +6 -2
  131. package/src/runs/shared/external-cli-runner.ts +9 -7
  132. package/src/runs/shared/herdr-connection.ts +134 -0
  133. package/src/runs/shared/herdr-external-adapters.ts +169 -0
  134. package/src/runs/shared/herdr-machine.ts +279 -0
  135. package/src/runs/shared/herdr-pi-protocol.ts +59 -0
  136. package/src/runs/shared/herdr-placed-run.ts +263 -0
  137. package/src/runs/shared/host-step-status.ts +11 -11
  138. package/src/runs/shared/llm-intent-arbiter.ts +40 -21
  139. package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
  140. package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
  141. package/src/runs/shared/model-scope.ts +1 -1
  142. package/src/runs/shared/nested-events.ts +19 -10
  143. package/src/runs/shared/orca-progress-tabs.ts +7 -1
  144. package/src/runs/shared/parallel-handoff.ts +57 -12
  145. package/src/runs/shared/parallel-utils.ts +10 -4
  146. package/src/runs/shared/pi-spawn.ts +10 -0
  147. package/src/runs/shared/readonly-drain-observation.ts +42 -0
  148. package/src/runs/shared/run-fanout-budget.ts +8 -8
  149. package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
  150. package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
  151. package/src/runs/shared/task-intent.ts +46 -13
  152. package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
  153. package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
  154. package/src/runs/shared/worktree-setup-command.ts +213 -0
  155. package/src/runs/shared/worktree.ts +437 -214
  156. package/src/shared/child-cache-retention.ts +43 -0
  157. package/src/shared/fork-context.ts +15 -72
  158. package/src/shared/launch-contract.ts +70 -8
  159. package/src/shared/model-response-aliases.ts +13 -0
  160. package/src/shared/opencode-session-headers.ts +30 -0
  161. package/src/shared/pruned-fork.ts +1 -1
  162. package/src/shared/required-child-extensions.ts +81 -0
  163. package/src/shared/settings.ts +5 -2
  164. package/src/shared/shortcuts.ts +0 -4
  165. package/src/shared/types.ts +164 -90
  166. package/src/shared/utils.ts +10 -2
  167. package/src/shared/watch-strategy.ts +2 -0
  168. package/src/shared/workflow-child-permit.ts +18 -13
  169. package/src/slash/delegation-adapters.ts +3 -1
  170. package/src/slash/delegation-request.ts +14 -0
  171. package/src/slash/slash-commands.ts +2 -7
  172. package/src/slash/subagents-admin.ts +31 -14
  173. package/src/tui/fleet-native-transcript.ts +50 -6
  174. package/src/tui/fleet-status.ts +165 -20
  175. package/src/tui/fleet.ts +52 -21
  176. package/src/tui/render.ts +210 -50
  177. package/src/watchdog/child-status.ts +28 -28
  178. package/src/watchdog/lsp-diagnostics.ts +1 -1
  179. package/src/watchdog/model-selection.ts +21 -1
  180. package/src/watchdog/permission-arbiter.ts +5 -2
  181. package/src/watchdog/register-child.ts +10 -2
  182. package/src/watchdog/register-main.ts +39 -35
  183. package/src/watchdog/render.ts +1 -1
  184. package/src/watchdog/review.ts +122 -74
  185. package/src/watchdog/rules.ts +1 -1
  186. package/src/watchdog/runtime.ts +100 -27
  187. package/src/watchdog/scope.ts +1 -1
  188. package/src/watchdog/settings.ts +3 -0
  189. package/src/watchdog/tool-actions.ts +13 -12
  190. package/src/watchdog/turn-delta.ts +23 -0
  191. package/src/watchdog/types.ts +5 -3
  192. package/src/watchdog/warning-format.ts +1 -1
  193. package/src/workflows/chat-progress.ts +3 -3
  194. package/src/workflows/scripted-workflow.ts +349 -26
  195. package/src/workflows/workflow-checklist.ts +17 -20
  196. package/src/workflows/workflow-child-summary.ts +57 -8
  197. package/src/workflows/workflow-preflight.ts +19 -19
  198. package/src/workflows/workflow-receipt.ts +24 -6
  199. package/src/workflows/workflow-resources.ts +108 -22
  200. package/src/workflows/workflow-settlement.ts +3 -0
  201. package/src/runs/shared/model-exclusions.ts +0 -373
  202. /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
@@ -19,7 +19,8 @@ import * as path from "node:path";
19
19
  import type { AgentToolResult } from "@earendil-works/pi-agent-core";
20
20
  import { keyText, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
21
21
  import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
22
- import { discoverAgentsAll, type AgentScope } from "../agents/agents.ts";
22
+ import { clearAgentDiscoveryCache, discoverAgents, discoverAgentsAll, type AgentConfig, type AgentScope } from "../agents/agents.ts";
23
+ import { appendAdvertisedAgentPrompt, buildAdvertisedAgentPrompt } from "../agents/advertised-agent-prompt.ts";
23
24
  import { mergeAgentsForScope } from "../agents/agent-selection.ts";
24
25
  import { clearRuntimeAgentsForPi } from "../agents/runtime-agent-registry.ts";
25
26
  import { discoverAgentsWithRuntime } from "../agents/runtime-discovery.ts";
@@ -31,8 +32,9 @@ import { getAgentDir } from "../shared/utils.ts";
31
32
  import { isStaleExtensionContextError, withCachedUiContext } from "../shared/extension-context.ts";
32
33
  import { currentCompletionOwnerId } from "../shared/completion-owner.ts";
33
34
  import { cleanupOldChainDirs } from "../shared/settings.ts";
34
- import { clearLegacyResultAnimationTimer, renderSubagentResult, renderSubagentSummary } from "../tui/render.ts";
35
- import { openSubagentFleetFromStatus } from "../tui/fleet.ts";
35
+ import { clearLegacyResultAnimationTimer, renderSubagentResult, renderSubagentSummary, setInlineWorkflowCoverage } from "../tui/render.ts";
36
+ import { openSubagentFleet } from "../tui/fleet.ts";
37
+ import { createBuiltinInspectorPlugins } from "../inspectors/plugins.ts";
36
38
  import { SubagentFleetStatus, resolveFleetViewPlacement } from "../tui/fleet-status.ts";
37
39
  import { createSubagentParamsSchema } from "./schemas.ts";
38
40
  import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
@@ -56,6 +58,8 @@ import {
56
58
  type SupervisorRequestMessageDetails,
57
59
  } from "../intercom/supervisor-ui.ts";
58
60
  import { registerHerdrStatusBridge, type HerdrStatusRun } from "../integrations/herdr-status.ts";
61
+ import { hasLiveSubagentWork, registerPiWebSessionLiveness } from "../integrations/pi-web-session-liveness.ts";
62
+ import { createRetainedNestedRouteTracker } from "../runs/background/retained-nested-route-tracker.ts";
59
63
  import { listHerdrProjectPaneRoots, restoreHerdrProjectPaneSnapshots } from "../inspectors/herdr/project-panes.ts";
60
64
  import { registerSubagentRpcBridge } from "./rpc.ts";
61
65
  import { clearSlashSnapshots, getSlashRenderableSnapshot, resolveSlashMessageDetails, restoreSlashFinalSnapshots, type SlashMessageDetails } from "../slash/slash-live-state.ts";
@@ -69,7 +73,7 @@ import { SUBAGENT_CHILD_ENV, SUBAGENT_PARENT_SESSION_ENV } from "../runs/shared/
69
73
  import { disposeChildSessions } from "../runs/shared/child-session.ts";
70
74
  import { resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
71
75
  import { formatDuration, shortenPath } from "../shared/formatters.ts";
72
- import { applyModelExclusionsConfig, loadConfig, resolveAsyncByDefault, resolveScheduledStoreRoot } from "./config.ts";
76
+ import { loadConfig, resolveAsyncByDefault, resolveScheduledStoreRoot } from "./config.ts";
73
77
  import { applyInjectionBlock, renderInjectionBlock, resolveInjectableAgents } from "./context-injection.ts";
74
78
  import { buildSubagentToolDescription, buildSubagentToolPromptMetadata } from "./tool-description.ts";
75
79
  import { formatWorkflowPreflightSummary, normalizeWorkflowPreflight } from "../workflows/workflow-preflight.ts";
@@ -336,14 +340,18 @@ function createSlashResultComponent(
336
340
  theme: ExtensionContext["ui"]["theme"],
337
341
  rendererConfig?: MainWindowRendererConfig,
338
342
  foregroundDetachShortcut?: string,
343
+ getCurrentTheme: () => ExtensionContext["ui"]["theme"] = () => theme,
339
344
  ): Container {
340
345
  const container = new Container();
341
346
  let lastVersion = -1;
347
+ let lastTheme: ExtensionContext["ui"]["theme"] | undefined;
342
348
  container.render = (width: number): string[] => {
343
349
  const snapshot = getSlashRenderableSnapshot(details);
344
- if (snapshot.version !== lastVersion || isSlashResultRunning(snapshot.result)) {
350
+ const currentTheme = getCurrentTheme();
351
+ if (snapshot.version !== lastVersion || currentTheme !== lastTheme || isSlashResultRunning(snapshot.result)) {
345
352
  lastVersion = snapshot.version;
346
- rebuildSlashResultContainer(container, snapshot.result, options, theme, rendererConfig, foregroundDetachShortcut);
353
+ lastTheme = currentTheme;
354
+ rebuildSlashResultContainer(container, snapshot.result, options, currentTheme, rendererConfig, foregroundDetachShortcut);
347
355
  }
348
356
  return Container.prototype.render.call(container, width);
349
357
  };
@@ -426,8 +434,6 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
426
434
  cleanupOldChainDirs();
427
435
 
428
436
  const config = loadConfig();
429
- // Apply the process-wide exclusion TTL before any child launch can record a model failure.
430
- applyModelExclusionsConfig(config);
431
437
  const waitToolConfig = resolveWaitToolConfig(config.waitTool);
432
438
  const asyncByDefault = resolveAsyncByDefault(config);
433
439
  const fleetViewEnabled = config.fleetView !== false;
@@ -437,14 +443,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
437
443
  const tempArtifactsDir = getArtifactsDir(null);
438
444
  const artifactCleanupDays = config.artifactConfig?.cleanupDays ?? DEFAULT_ARTIFACT_CONFIG.cleanupDays;
439
445
  cleanupAllArtifactDirs(artifactCleanupDays);
440
- const resultIndexCleanupTimer = setTimeout(() => {
441
- try {
442
- cleanupResultIndexes(DIRS.results);
443
- } catch (error) {
444
- console.error("Failed to clean stale subagent result indexes:", error);
445
- }
446
- }, 30_000);
447
- resultIndexCleanupTimer.unref?.();
446
+ let resultIndexCleanupTimer: ReturnType<typeof setTimeout> | undefined;
448
447
 
449
448
  const state: SubagentState = {
450
449
  baseCwd: "",
@@ -490,17 +489,20 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
490
489
  }, run);
491
490
  };
492
491
 
493
- const supervisorChannel = createNativeSupervisorChannel(pi, state);
492
+ const supervisorChannel = createNativeSupervisorChannel(pi, state, {
493
+ getCurrentOwnerStates: () => executor.getCurrentSupervisorOwnerStates(),
494
+ });
494
495
  const waitSubscriptionManager = createWaitSubscriptionManager(pi, state);
495
496
  const mainWatchdog = registerMainWatchdog(pi);
496
497
  const resultDeliveryOwnership = createResultDeliveryOwnership(state);
497
498
  const completionNotifier = registerSubagentNotify(pi, state, { batchConfig: config.completionBatch, ownership: resultDeliveryOwnership });
499
+ let retainedNestedRouteTracker: ReturnType<typeof createRetainedNestedRouteTracker> | undefined;
498
500
  const fleetStatus = fleetViewEnabled
499
501
  ? new SubagentFleetStatus(state, async (itemKey) => {
500
502
  const ctx = withLastUiContext((current) => current);
501
503
  if (!ctx) return;
502
504
  try {
503
- await openSubagentFleetFromStatus(ctx, state, pi, { itemKey, asyncDirRoot: DIRS.async, resultsDir: DIRS.results, fleetKeybindings: config.fleetKeybindings });
505
+ await openSubagentFleet(ctx, state, { initialKey: itemKey, asyncDirRoot: DIRS.async, resultsDir: DIRS.results, fleetKeybindings: config.fleetKeybindings, inspectorPlugins: createBuiltinInspectorPlugins(), events: pi.events });
504
506
  } catch (error) {
505
507
  if (isStaleExtensionContextError(error)) {
506
508
  if (state.lastUiContext === ctx) state.lastUiContext = null;
@@ -508,11 +510,12 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
508
510
  }
509
511
  throw error;
510
512
  }
511
- }, { placement: fleetViewPlacement })
513
+ }, { placement: fleetViewPlacement, onWorkflowCoverageChange: setInlineWorkflowCoverage })
512
514
  : undefined;
513
515
  let executorScheduled: ((id: string, params: SubagentParamsLike, signal: AbortSignal, ctx: ExtensionContext) => Promise<AgentToolResult<Details>>) | undefined;
514
516
  let goalTurnId = 0;
515
517
  let parentSessionEnvValue: string | null = null;
518
+ let releaseHostSessionLiveness = () => {};
516
519
  const scheduledStoreRoot = config.scheduledRuns?.storeRoot === undefined ? undefined : resolveScheduledStoreRoot(config.scheduledRuns.storeRoot);
517
520
  const scheduledRunManager = createScheduledRunManager({
518
521
  config,
@@ -530,6 +533,15 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
530
533
  resolveCapabilityCeiling: (sessionId) => resolveCurrentSubagentCapabilityCeiling(sessionId),
531
534
  });
532
535
  let refreshResultDelivery = () => {};
536
+ let advertisedAgents: AgentConfig[] = [];
537
+ let advertisedContext: Pick<ExtensionContext, "cwd" | "model"> | undefined;
538
+ const refreshAdvertisedAgents = () => {
539
+ advertisedAgents = [];
540
+ if (!advertisedContext) return;
541
+ clearAgentDiscoveryCache();
542
+ advertisedAgents = discoverAgents(advertisedContext.cwd, "both", advertisedContext.model?.provider).agents
543
+ .filter((agent) => agent.advertise === true);
544
+ };
533
545
  const hasResultDeliveryDemand = () => {
534
546
  if ([...state.asyncJobs.values()].some((job) => job.status === "queued" || job.status === "running")) return true;
535
547
  if (state.foregroundControls.size > 0) return true;
@@ -561,25 +573,41 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
561
573
  const { startResultWatcher, transitionResultDelivery, primeExistingResults, stopResultWatcher } = resultWatcher;
562
574
  refreshResultDelivery = resultWatcher.refreshResultDelivery;
563
575
  const asyncRetentionAbort = new AbortController();
564
- const asyncRetentionTimer = setTimeout(async () => {
565
- try {
566
- await cleanupAsyncRetention({
567
- asyncDirRoot: DIRS.async,
568
- resultsDir: DIRS.results,
569
- signal: asyncRetentionAbort.signal,
570
- protectedRunIds: new Set([
571
- ...state.asyncJobs.keys(),
572
- ...(state.workflowControllers?.keys() ?? []),
573
- ...scheduledRunManager.referencedAsyncRunIds(),
574
- ]),
575
- });
576
- } catch (error) {
577
- console.error("Failed to clean retained async subagent state:", error);
576
+ let asyncRetentionTimer: ReturnType<typeof setTimeout> | undefined;
577
+ const startSessionMaintenance = () => {
578
+ if (!resultIndexCleanupTimer) {
579
+ resultIndexCleanupTimer = setTimeout(() => {
580
+ try {
581
+ cleanupResultIndexes(DIRS.results);
582
+ } catch (error) {
583
+ console.error("Failed to clean stale subagent result indexes:", error);
584
+ }
585
+ }, 30_000);
586
+ resultIndexCleanupTimer.unref?.();
587
+ }
588
+ waitSubscriptionManager.start();
589
+ if (!asyncRetentionTimer) {
590
+ asyncRetentionTimer = setTimeout(async () => {
591
+ try {
592
+ await cleanupAsyncRetention({
593
+ asyncDirRoot: DIRS.async,
594
+ resultsDir: DIRS.results,
595
+ signal: asyncRetentionAbort.signal,
596
+ protectedRunIds: new Set([
597
+ ...state.asyncJobs.keys(),
598
+ ...(state.workflowControllers?.keys() ?? []),
599
+ ...scheduledRunManager.referencedAsyncRunIds(),
600
+ ]),
601
+ });
602
+ } catch (error) {
603
+ console.error("Failed to clean retained async subagent state:", error);
604
+ }
605
+ }, ASYNC_RETENTION_DELAY_MS);
606
+ asyncRetentionTimer.unref?.();
578
607
  }
579
- }, ASYNC_RETENTION_DELAY_MS);
580
- asyncRetentionTimer.unref?.();
608
+ };
581
609
 
582
- const executor = createSubagentExecutor({
610
+ const executorDeps: Parameters<typeof createSubagentExecutor>[0] = {
583
611
  pi,
584
612
  state,
585
613
  config,
@@ -592,9 +620,20 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
592
620
  getSubagentSessionRoot,
593
621
  expandTilde,
594
622
  discoverAgents: discoverAgentsForRuntime,
623
+ onAgentsChanged: () => {
624
+ try {
625
+ refreshAdvertisedAgents();
626
+ } catch (error) {
627
+ // The mutation already persisted. Withdraw stale guidance, not its result.
628
+ console.error("Failed to refresh advertised agents; catalog withdrawn until refresh:", error);
629
+ }
630
+ },
595
631
  activateSupervisorTransport: () => supervisorChannel.activateTransport(),
632
+ findPendingAsks: (target) => supervisorChannel.findPendingAsks(target),
596
633
  refreshResultDelivery: () => refreshResultDelivery(),
597
- });
634
+ trackRetainedNestedRoute: undefined,
635
+ };
636
+ const executor = createSubagentExecutor(executorDeps);
598
637
  executorScheduled = executor.executeScheduled;
599
638
 
600
639
  pi.registerMessageRenderer<SupervisorRequestMessageDetails>(SUPERVISOR_REQUEST_MESSAGE_TYPE, renderSupervisorRequest);
@@ -611,7 +650,14 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
611
650
  pi.registerMessageRenderer<SlashMessageDetails>(SLASH_RESULT_TYPE, (message, options, theme) => {
612
651
  const details = resolveSlashMessageDetails(message.details);
613
652
  if (!details) return undefined;
614
- return createSlashResultComponent(details, options, theme, config.mainWindowRenderer, config.foregroundDetachShortcut);
653
+ return createSlashResultComponent(
654
+ details,
655
+ options,
656
+ theme,
657
+ config.mainWindowRenderer,
658
+ config.foregroundDetachShortcut,
659
+ () => state.lastUiContext?.ui.theme ?? theme,
660
+ );
615
661
  });
616
662
 
617
663
  pi.registerMessageRenderer<undefined>(SLASH_TEXT_RESULT_TYPE, (message, _options, _theme) => {
@@ -762,10 +808,29 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
762
808
 
763
809
  pi.registerTool(tool);
764
810
 
811
+ pi.on("before_agent_start", (event) => {
812
+ if (process.env[SUBAGENT_CHILD_ENV] === "1") return undefined;
813
+ const next = applyInjectionBlock({
814
+ systemPrompt: event.systemPrompt,
815
+ block: state.contextInjectionBlock ?? "",
816
+ });
817
+ return next ? { systemPrompt: next } : undefined;
818
+ });
819
+
820
+ pi.on("before_agent_start", (event, ctx) => {
821
+ const selectedTools = event.systemPromptOptions?.selectedTools ?? (typeof pi.getActiveTools === "function" ? pi.getActiveTools() : []);
822
+ const sessionId = state.currentSessionId ?? resolveCurrentSessionId(ctx.sessionManager);
823
+ const advertisedPrompt = Array.isArray(selectedTools) && selectedTools.includes("subagent")
824
+ ? buildAdvertisedAgentPrompt(advertisedAgents, resolveCurrentSubagentCapabilityCeiling(sessionId))
825
+ : undefined;
826
+ const systemPrompt = appendAdvertisedAgentPrompt(event.systemPrompt, advertisedPrompt);
827
+ if (systemPrompt !== event.systemPrompt) return { systemPrompt };
828
+ });
829
+
765
830
  registerWaitTool(pi, state, waitToolConfig.enabled, waitSubscriptionManager, waitToolConfig.defaultTimeoutMs);
766
831
 
767
832
  pi.on("agent_end", async (_event, ctx) => {
768
- if (!ctx.hasUI) await drainOutstandingWork({ state, events: pi.events });
833
+ if (!ctx.hasUI) await drainOutstandingWork({ state, events: pi.events, hasPendingSupervisorRequest: supervisorChannel.hasPendingRequests });
769
834
  const ownerSessionId = state.currentSessionId;
770
835
  if (!ownerSessionId) return;
771
836
  goalTurnId += 1;
@@ -896,6 +961,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
896
961
  const previousRuntimeSessionId = state.currentSessionId;
897
962
  resultDeliveryOwnership.claimPredecessor(previousSessionFile, previousRuntimeSessionId);
898
963
  state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
964
+ state.supervisorOwnerSessionId = ctx.sessionManager.getSessionId() || null;
899
965
  transitionResultDelivery();
900
966
  state.parentSessionFile = ctx.sessionManager.getSessionFile();
901
967
  state.trustedSessionFileRoot = state.parentSessionFile ? path.join(getAgentDir(), "sessions") : undefined;
@@ -932,6 +998,9 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
932
998
  cleanupSessionArtifacts(ctx);
933
999
  logSlowPhase("session-artifact-cleanup", phaseStartedAt);
934
1000
  state.foregroundControls.clear();
1001
+ retainedNestedRouteTracker?.clear();
1002
+ retainedNestedRouteTracker = undefined;
1003
+ executorDeps.trackRetainedNestedRoute = undefined;
935
1004
  state.lastForegroundControlId = null;
936
1005
  phaseStartedAt = Date.now();
937
1006
  resetJobs(ctx);
@@ -997,6 +1066,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
997
1066
  if (runtimeCleaned) return;
998
1067
  runtimeCleaned = true;
999
1068
  const shuttingDownParentSession = parentSessionEnvValue;
1069
+ releaseHostSessionLiveness();
1070
+ releaseHostSessionLiveness = () => {};
1000
1071
  // Workflow continuations retain their launch context; abort them before
1001
1072
  // teardown so a reload cannot launch through a stale context.
1002
1073
  for (const controller of state.workflowControllers?.values() ?? []) {
@@ -1005,8 +1076,10 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1005
1076
  state.workflowControllers?.clear();
1006
1077
  state.workflowChildStops?.clear();
1007
1078
  clearRuntimeAgentsForPi(pi);
1008
- clearTimeout(resultIndexCleanupTimer);
1009
- clearTimeout(asyncRetentionTimer);
1079
+ if (resultIndexCleanupTimer) clearTimeout(resultIndexCleanupTimer);
1080
+ resultIndexCleanupTimer = undefined;
1081
+ if (asyncRetentionTimer) clearTimeout(asyncRetentionTimer);
1082
+ asyncRetentionTimer = undefined;
1010
1083
  asyncRetentionAbort.abort();
1011
1084
  stopResultWatcher();
1012
1085
  resultDeliveryOwnership.clear();
@@ -1020,6 +1093,9 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1020
1093
  for (const timer of state.cleanupTimers.values()) clearTimeout(timer);
1021
1094
  state.cleanupTimers.clear();
1022
1095
  state.asyncJobs.clear();
1096
+ retainedNestedRouteTracker?.clear();
1097
+ retainedNestedRouteTracker = undefined;
1098
+ executorDeps.trackRetainedNestedRoute = undefined;
1023
1099
  for (const unsubscribe of eventUnsubscribes) {
1024
1100
  try {
1025
1101
  unsubscribe();
@@ -1034,6 +1110,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1034
1110
  promptTemplateBridge.dispose();
1035
1111
  state.widgetsSuspended = false;
1036
1112
  state.currentSessionId = null;
1113
+ state.supervisorOwnerSessionId = null;
1037
1114
  state.statusProjectionSessionId = null;
1038
1115
  state.parentSessionFile = null;
1039
1116
  parentSessionEnvValue = null;
@@ -1096,7 +1173,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1096
1173
  if (event.reason !== "manual") suspendWidgetsForCompaction();
1097
1174
  });
1098
1175
 
1099
- pi.on("session_compact", () => {
1176
+ pi.on("session_compact", (event) => {
1177
+ if (event.reason !== "manual") return;
1100
1178
  const hasActiveAsyncWork = [...state.asyncJobs.values()].some((job) => job.status === "queued" || job.status === "running");
1101
1179
  if (!hasActiveAsyncWork || !withLastUiContext(() => true)) return;
1102
1180
  pi.sendMessage(
@@ -1111,9 +1189,25 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1111
1189
 
1112
1190
  pi.on("session_start", (event, ctx) => {
1113
1191
  installRuntime(ctx);
1192
+ startSessionMaintenance();
1114
1193
  const recovering = event.reason === "startup" || event.reason === "reload" || event.reason === "resume";
1115
1194
  resetSessionState(ctx, recovering, event.previousSessionFile);
1116
1195
  refreshContextInjectionSnapshot(ctx);
1196
+ releaseHostSessionLiveness();
1197
+ const sessionId = ctx.sessionManager.getSessionId();
1198
+ const sessionFile = ctx.sessionManager.getSessionFile();
1199
+ const liveness = sessionId
1200
+ ? registerPiWebSessionLiveness({
1201
+ sessionId,
1202
+ ...(sessionFile ? { sessionFile } : {}),
1203
+ isActive: () => hasLiveSubagentWork(state) || completionNotifier.hasPendingDelivery(),
1204
+ })
1205
+ : { registered: false, release: () => {} };
1206
+ releaseHostSessionLiveness = liveness.release;
1207
+ if (liveness.registered) {
1208
+ retainedNestedRouteTracker = createRetainedNestedRouteTracker(state);
1209
+ executorDeps.trackRetainedNestedRoute = retainedNestedRouteTracker.track;
1210
+ }
1117
1211
  herdrStatusBridge.sessionStarted({
1118
1212
  hasUI: ctx.hasUI === true,
1119
1213
  runs: activeHerdrRuns(),
@@ -1123,15 +1217,6 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1123
1217
  supervisorChannel.activateTransport();
1124
1218
  });
1125
1219
 
1126
- pi.on("before_agent_start", (event) => {
1127
- if (process.env[SUBAGENT_CHILD_ENV] === "1") return undefined;
1128
- const next = applyInjectionBlock({
1129
- systemPrompt: event.systemPrompt,
1130
- block: state.contextInjectionBlock ?? "",
1131
- });
1132
- return next ? { systemPrompt: next } : undefined;
1133
- });
1134
-
1135
1220
  pi.on("session_shutdown", async () => {
1136
1221
  runtimeEntry.cleanup();
1137
1222
  try {
@@ -1141,4 +1226,9 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1141
1226
  }
1142
1227
  await herdrStatusBridge.flush();
1143
1228
  });
1229
+
1230
+ pi.on("session_start", (_event, ctx) => {
1231
+ advertisedContext = { cwd: ctx.cwd, model: ctx.model };
1232
+ refreshAdvertisedAgents();
1233
+ });
1144
1234
  }
@@ -73,7 +73,6 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
73
73
  }
74
74
  }
75
75
  if (params.baseRef !== undefined) {
76
- if (typeof params.baseRef !== "string") return { ok: false, error: "baseRef must be a valid Git ref.", mode: params.action === undefined ? "workflow" : "management" };
77
76
  try {
78
77
  normalizeWorktreeBaseRef(params.baseRef);
79
78
  } catch (error) {
@@ -90,16 +89,18 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
90
89
  if (hasNamedWorkflow && (params.workflowScript !== undefined || params.workflowScriptPath !== undefined)) {
91
90
  return { ok: false, error: "workflow is mutually exclusive with workflowScript and workflowScriptPath.", mode: "workflow" };
92
91
  }
93
- if (!hasNamedWorkflow && params.args !== undefined) {
94
- return { ok: false, error: "args requires a named workflow resource.", mode: "workflow" };
95
- }
96
92
  const hasWorkflowInput = params.workflowScript !== undefined || params.workflowScriptPath !== undefined || hasNamedWorkflow;
93
+ if (!hasWorkflowInput && params.args !== undefined) {
94
+ return { ok: false, error: "args requires workflow, workflowScript, or workflowScriptPath.", mode: "workflow" };
95
+ }
97
96
  const hasCapacityOverride = params.globalConcurrencyLimit !== undefined || params.maxSubagentSpawnsPerRun !== undefined;
98
97
  if (hasCapacityOverride) {
99
98
  const capacityOverrideError = validateWorkflowCapacityOverrides(params);
100
99
  if (capacityOverrideError) return { ok: false, error: capacityOverrideError, mode: params.action === undefined ? "workflow" : "management" };
101
- if (params.action !== undefined || hasNamedWorkflow || (params.workflowScript === undefined && params.workflowScriptPath === undefined)) {
102
- return { ok: false, error: "Workflow capacity overrides are only supported on top-level workflowScript or workflowScriptPath calls.", mode: params.action === undefined ? "workflow" : "management" };
100
+ const validatesSpawnBudget = typeof params.action === "string" && params.action.trim() === "validate"
101
+ && params.globalConcurrencyLimit === undefined && params.maxSubagentSpawnsPerRun !== undefined;
102
+ if ((params.action !== undefined && !validatesSpawnBudget) || hasNamedWorkflow || (params.workflowScript === undefined && params.workflowScriptPath === undefined)) {
103
+ return { ok: false, error: "Workflow capacity overrides are only supported on top-level workflowScript or workflowScriptPath calls; validate accepts maxSubagentSpawnsPerRun for static budget checks.", mode: params.action === undefined ? "workflow" : "management" };
103
104
  }
104
105
  }
105
106
  if (params.preflight !== undefined && !hasWorkflowInput) {
@@ -499,9 +499,13 @@ function manageParams(params: unknown): SubagentParamsLike {
499
499
  if (requiresId && typeof input.id !== "string") {
500
500
  throw new SubagentRpcError("invalid_params", `RPC manage ${action} requires id.`);
501
501
  }
502
+ if (action === "schedule.run" && input.quiet !== undefined && typeof input.quiet !== "boolean") {
503
+ throw new SubagentRpcError("invalid_params", "RPC manage quiet must be a boolean.");
504
+ }
502
505
  const output: SubagentParamsLike = {
503
506
  action,
504
507
  ...(typeof input.id === "string" ? { id: input.id.trim() } : {}),
508
+ ...(action === "schedule.run" && input.quiet === true ? { quiet: true } : {}),
505
509
  };
506
510
  assertSubagentParams(output, "RPC manage params");
507
511
  return output;
@@ -643,27 +647,10 @@ function stopAsyncRun(
643
647
  message: `Stop requested for async run ${initialRunId}.`,
644
648
  };
645
649
  }
646
- try {
647
- deliverStopRequest({
648
- asyncDir: location.asyncDir,
649
- pid: initialStatus.pid,
650
- kill: options.kill,
651
- now: options.now,
652
- source: "rpc-stop",
653
- ...(child ? { targetIndex: child.index, childId: child.id } : {}),
654
- });
655
- } catch (error) {
656
- throw new SubagentRpcError("execution_failed", error instanceof Error ? error.message : String(error));
657
- }
658
- if (child) emitChildStopping(initialRunId, location.asyncDir, child);
659
- return {
660
- runId: initialRunId,
661
- asyncDir: location.asyncDir,
662
- previousState: initialStatus.state,
663
- state: "stopping",
664
- ...(child ? { childId: child.id } : {}),
665
- message: child ? `Stop requested for child ${child.id} in async run ${initialRunId}.` : `Stop requested for async run ${initialRunId}.`,
666
- };
650
+ // Workflow controls live in-process; a persisted run directory cannot restore them.
651
+ throw new SubagentRpcError("invalid_state", child
652
+ ? `Child '${child.id}' in workflow ${initialRunId} has no live stop callback available.`
653
+ : `Workflow ${initialRunId} has no live run controller available to stop.`);
667
654
  }
668
655
 
669
656
  let status;