@xzzpig/pi-subagents 0.8.0 → 0.10.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 (221) hide show
  1. package/CHANGELOG.md +477 -0
  2. package/README.md +2 -2
  3. package/agents/claude-code-writer.md +15 -0
  4. package/agents/claude-code.md +15 -0
  5. package/agents/codex-exec-writer.md +15 -0
  6. package/agents/codex-exec.md +15 -0
  7. package/agents/cursor-agent-writer.md +14 -0
  8. package/agents/cursor-agent.md +14 -0
  9. package/agents/reviewer.md +1 -1
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +195 -39
  12. package/docs/configuration.md +81 -22
  13. package/docs/extension-api.md +69 -14
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +32 -9
  16. package/docs/observability.md +22 -20
  17. package/docs/tool-reference.md +123 -14
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +142 -4
  20. package/install.mjs +1 -1
  21. package/package.json +7 -6
  22. package/prompts/review-loop.md +2 -2
  23. package/skills/council-mode/SKILL.md +48 -243
  24. package/skills/council-mode/references/pass-contracts.md +150 -0
  25. package/skills/pi-subagents/SKILL.md +89 -35
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +30 -234
  27. package/skills/pi-subagents/references/execution-controls.md +91 -15
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +13 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +59 -31
  31. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  32. package/src/agents/agent-management.ts +384 -115
  33. package/src/agents/agent-refinements.ts +4 -4
  34. package/src/agents/agent-serializer.ts +14 -2
  35. package/src/agents/agents.ts +935 -372
  36. package/src/agents/builtin-names.ts +6 -0
  37. package/src/agents/runtime-agent-events.ts +70 -0
  38. package/src/agents/runtime-agent-registry.ts +42 -21
  39. package/src/api/agents.ts +10 -5
  40. package/src/api/background-work.ts +12 -3
  41. package/src/api/capability-ceiling.ts +0 -1
  42. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  43. package/src/api/delegation.ts +0 -7
  44. package/src/api/external-runs.ts +67 -4
  45. package/src/api/preflight.ts +77 -21
  46. package/src/api/shared-types.ts +6 -0
  47. package/src/extension/config.ts +90 -0
  48. package/src/extension/doctor.ts +5 -13
  49. package/src/extension/fanout-child.ts +14 -14
  50. package/src/extension/index.ts +115 -37
  51. package/src/extension/public-execution.ts +103 -15
  52. package/src/extension/rpc.ts +120 -25
  53. package/src/extension/schemas.ts +65 -29
  54. package/src/extension/tool-description.ts +48 -26
  55. package/src/inspectors/herdr/actions.ts +2 -1
  56. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  57. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  58. package/src/integrations/herdr-status.ts +51 -3
  59. package/src/intercom/native-supervisor-channel.ts +138 -60
  60. package/src/intercom/result-intercom.ts +7 -0
  61. package/src/intercom/supervisor-ui.ts +243 -0
  62. package/src/profiles/profiles.ts +5 -6
  63. package/src/runs/background/active-async-capacity.ts +103 -18
  64. package/src/runs/background/async-execution.ts +417 -133
  65. package/src/runs/background/async-job-tracker.ts +95 -15
  66. package/src/runs/background/async-resume.ts +60 -28
  67. package/src/runs/background/async-retention.ts +20 -3
  68. package/src/runs/background/async-status-snapshot.ts +23 -261
  69. package/src/runs/background/async-status.ts +204 -14
  70. package/src/runs/background/auto-drain.ts +1 -1
  71. package/src/runs/background/chain-append.ts +8 -3
  72. package/src/runs/background/chain-root-attachment.ts +74 -8
  73. package/src/runs/background/control-channel.ts +4 -205
  74. package/src/runs/background/fleet-view.ts +38 -22
  75. package/src/runs/background/inspect-rpc.ts +8 -8
  76. package/src/runs/background/notify.ts +238 -12
  77. package/src/runs/background/process-terminal.ts +16 -0
  78. package/src/runs/background/result-delivery-ownership.ts +45 -0
  79. package/src/runs/background/result-files.ts +28 -14
  80. package/src/runs/background/result-watcher.ts +39 -16
  81. package/src/runs/background/resume-guidance.ts +2 -2
  82. package/src/runs/background/retained-children.ts +1 -1
  83. package/src/runs/background/run-child-session.ts +613 -0
  84. package/src/runs/background/run-status.ts +84 -17
  85. package/src/runs/background/runner-aliases.ts +125 -0
  86. package/src/runs/background/runner-child-sessions.ts +31 -0
  87. package/src/runs/background/scheduled-runs.ts +174 -18
  88. package/src/runs/background/stale-run-reconciler.ts +10 -4
  89. package/src/runs/background/steering.ts +8 -15
  90. package/src/runs/background/subagent-runner.ts +718 -1161
  91. package/src/runs/background/subagent-wait.ts +86 -31
  92. package/src/runs/background/terminal-run-index.ts +1 -1
  93. package/src/runs/background/wait-completions.ts +43 -2
  94. package/src/runs/background/wait-config.ts +23 -9
  95. package/src/runs/background/wait-tool.ts +26 -19
  96. package/src/runs/foreground/async-steering-action.ts +3 -19
  97. package/src/runs/foreground/execution.ts +489 -499
  98. package/src/runs/foreground/foreground-control.ts +13 -0
  99. package/src/runs/foreground/foreground-history.ts +23 -1
  100. package/src/runs/foreground/subagent-executor.ts +1223 -402
  101. package/src/runs/foreground/workflow-detach-reconcile.ts +140 -115
  102. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  103. package/src/runs/shared/abort-recovery.ts +119 -0
  104. package/src/runs/shared/acceptance.ts +138 -36
  105. package/src/runs/shared/async-status-projection.ts +565 -0
  106. package/src/runs/shared/background-process-options.ts +9 -0
  107. package/src/runs/shared/capability-ceiling.ts +2 -2
  108. package/src/runs/shared/child-hooks.ts +25 -0
  109. package/src/runs/shared/child-identity.ts +32 -6
  110. package/src/runs/shared/child-launch-plan.ts +151 -0
  111. package/src/runs/shared/child-launch.ts +364 -0
  112. package/src/runs/shared/child-lifecycle.ts +25 -0
  113. package/src/runs/shared/child-runtime-config.ts +126 -0
  114. package/src/runs/shared/child-session.ts +366 -0
  115. package/src/runs/shared/child-tool-plan.ts +632 -0
  116. package/src/runs/shared/claude-code-adapter.ts +133 -0
  117. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  118. package/src/runs/shared/completion-evidence.ts +89 -0
  119. package/src/runs/shared/completion-guard.ts +6 -5
  120. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  121. package/src/runs/shared/dynamic-fanout.ts +3 -3
  122. package/src/runs/shared/external-cli-contract.ts +167 -0
  123. package/src/runs/shared/external-cli-preflight.ts +138 -0
  124. package/src/runs/shared/external-cli-runner.ts +348 -55
  125. package/src/runs/shared/fast-mode-extension.ts +5 -5
  126. package/src/runs/shared/host-step-status.ts +231 -0
  127. package/src/runs/shared/lane-metadata.ts +126 -0
  128. package/src/runs/shared/launch-cwd.ts +16 -0
  129. package/src/runs/shared/long-running-guard.ts +2 -1
  130. package/src/runs/shared/mcp-config-sources.ts +422 -0
  131. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  132. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  133. package/src/runs/shared/model-exclusions.ts +139 -9
  134. package/src/runs/shared/model-fallback.ts +146 -14
  135. package/src/runs/shared/mutation-evidence.ts +57 -3
  136. package/src/runs/shared/nested-events.ts +99 -77
  137. package/src/runs/shared/nested-path.ts +0 -14
  138. package/src/runs/shared/nested-render.ts +9 -5
  139. package/src/runs/shared/orca-progress-tabs.ts +12 -7
  140. package/src/runs/shared/parallel-handoff.ts +423 -7
  141. package/src/runs/shared/parallel-utils.ts +20 -7
  142. package/src/runs/shared/permissions.ts +1 -14
  143. package/src/runs/shared/pi-spawn.ts +69 -35
  144. package/src/runs/shared/process-signal.ts +16 -0
  145. package/src/runs/shared/run-fanout-budget.ts +0 -13
  146. package/src/runs/shared/run-history.ts +21 -1
  147. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  148. package/src/runs/shared/sandbox-profile-guard.ts +85 -0
  149. package/src/runs/shared/sandbox-startup-diagnostics.ts +54 -0
  150. package/src/runs/shared/single-output.ts +89 -22
  151. package/src/runs/shared/structured-output.ts +49 -9
  152. package/src/runs/shared/subagent-control.ts +6 -2
  153. package/src/runs/shared/subagent-prompt-runtime.ts +188 -365
  154. package/src/runs/shared/task-intent.ts +21 -7
  155. package/src/runs/shared/tool-availability.ts +18 -62
  156. package/src/runs/shared/tool-budget.ts +0 -14
  157. package/src/runs/shared/tool-timeout.ts +1 -1
  158. package/src/runs/shared/workflow-graph.ts +16 -0
  159. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  160. package/src/runs/shared/worktree.ts +571 -62
  161. package/src/shared/atomic-json.ts +3 -1
  162. package/src/shared/child-session-name.ts +46 -0
  163. package/src/shared/extension-context.ts +24 -0
  164. package/src/shared/fork-context.ts +21 -12
  165. package/src/shared/fork-session-cwd.ts +27 -0
  166. package/src/shared/formatters.ts +18 -3
  167. package/src/shared/jsonl-writer.ts +11 -0
  168. package/src/shared/launch-contract.ts +11 -1
  169. package/src/shared/pruned-fork.ts +450 -0
  170. package/src/shared/sandbox-profile.ts +23 -0
  171. package/src/shared/session-file-trust.ts +19 -0
  172. package/src/shared/session-tokens.ts +14 -3
  173. package/src/shared/settings.ts +19 -105
  174. package/src/shared/shortcuts.ts +17 -0
  175. package/src/shared/thinking-ceiling.ts +0 -6
  176. package/src/shared/types.ts +545 -70
  177. package/src/shared/utils.ts +60 -93
  178. package/src/shared/workflow-child-permit.ts +207 -0
  179. package/src/slash/delegation-adapters.ts +1 -9
  180. package/src/slash/delegation-request.ts +0 -4
  181. package/src/slash/prompt-template-bridge.ts +37 -1
  182. package/src/slash/slash-bridge.ts +1 -2
  183. package/src/slash/slash-commands.ts +383 -116
  184. package/src/slash/slash-live-state.ts +22 -11
  185. package/src/slash/subagents-admin.ts +29 -12
  186. package/src/tui/fleet-native-transcript.ts +4 -0
  187. package/src/tui/fleet-status.ts +217 -82
  188. package/src/tui/fleet-transcript.ts +11 -5
  189. package/src/tui/fleet.ts +54 -28
  190. package/src/tui/render-helpers.ts +31 -0
  191. package/src/tui/render.ts +1429 -163
  192. package/src/watchdog/change-signature.ts +40 -1
  193. package/src/watchdog/child-status.ts +54 -34
  194. package/src/watchdog/diff-tool.ts +77 -0
  195. package/src/watchdog/emission-guard.ts +5 -3
  196. package/src/watchdog/guidance.ts +20 -0
  197. package/src/watchdog/register-child.ts +28 -25
  198. package/src/watchdog/register-main.ts +10 -9
  199. package/src/watchdog/render.ts +4 -5
  200. package/src/watchdog/review.ts +15 -4
  201. package/src/watchdog/rules.ts +70 -0
  202. package/src/watchdog/runtime.ts +75 -92
  203. package/src/watchdog/scope.ts +0 -11
  204. package/src/watchdog/settings.ts +48 -104
  205. package/src/watchdog/turn-delta.ts +1 -1
  206. package/src/watchdog/types.ts +18 -32
  207. package/src/watchdog/warning-format.ts +0 -1
  208. package/src/workflows/chat-progress.ts +7 -3
  209. package/src/workflows/host-command.ts +235 -0
  210. package/src/workflows/scripted-workflow.ts +988 -59
  211. package/src/workflows/workflow-checklist.ts +439 -0
  212. package/src/workflows/workflow-child-summary.ts +121 -0
  213. package/src/workflows/workflow-preflight.ts +297 -0
  214. package/src/workflows/workflow-receipt.ts +232 -6
  215. package/src/workflows/workflow-resources.ts +150 -0
  216. package/src/workflows/workflow-settlement.ts +246 -0
  217. package/src/runs/shared/child-protocol.ts +0 -401
  218. package/src/runs/shared/pi-args.ts +0 -935
  219. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  220. package/src/runs/shared/turn-budget.ts +0 -98
  221. package/src/shared/post-exit-stdio-guard.ts +0 -85
@@ -9,7 +9,7 @@
9
9
  * Toggle: async parameter (default: true; set asyncByDefault:false in config.json to opt out)
10
10
  *
11
11
  * Config file: ~/.pi/agent/extensions/subagent/config.json
12
- * { "asyncByDefault": true, "defaultSubagentContext": "fork", "forceTopLevelAsync": true, "maxSubagentDepth": 1, "intercomBridge": { "mode": "always", "instructionFile": "./intercom-bridge.md" }, "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
12
+ * { "asyncByDefault": true, "defaultSubagentContext": "fork", "forkContext": { "mode": "pruned", "model": "provider/model" }, "forceTopLevelAsync": true, "maxSubagentDepth": 1, "intercomBridge": { "mode": "always", "instructionFile": "./intercom-bridge.md" }, "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
13
13
  */
14
14
 
15
15
  import { randomUUID } from "node:crypto";
@@ -19,12 +19,15 @@ 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 { discoverAgents, discoverAgentsAll, type AgentConfig, type AgentScope } from "../agents/agents.ts";
22
+ import { discoverAgentSnapshot, discoverAgents, discoverAgentsAll, type AgentConfig, type AgentScope } from "../agents/agents.ts";
23
23
  import { mergeAgentsForScope } from "../agents/agent-selection.ts";
24
24
  import { clearRuntimeAgentsForPi, listRuntimeAgentConfigs, mergeRuntimeAgents } from "../agents/runtime-agent-registry.ts";
25
+ import { registerRuntimeAgentEventListener } from "../agents/runtime-agent-events.ts";
25
26
  import { ensureAccessibleDir } from "../shared/accessible-dir.ts";
26
27
  import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
27
28
  import { resolveCurrentSessionId } from "../shared/session-identity.ts";
29
+ import { getAgentDir } from "../shared/utils.ts";
30
+ import { isStaleExtensionContextError, withCachedUiContext } from "../shared/extension-context.ts";
28
31
  import { currentCompletionOwnerId } from "../shared/completion-owner.ts";
29
32
  import { cleanupOldChainDirs } from "../shared/settings.ts";
30
33
  import { clearLegacyResultAnimationTimer, renderSubagentResult, renderSubagentSummary } from "../tui/render.ts";
@@ -33,33 +36,42 @@ import { SubagentFleetStatus, resolveFleetViewPlacement } from "../tui/fleet-sta
33
36
  import { createSubagentParamsSchema } from "./schemas.ts";
34
37
  import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
35
38
  import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
36
- import { getActiveAsyncCapacitySnapshot, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
39
+ import { getActiveAsyncCapacitySnapshot, resolveAbandonedSlotReleaseAfterMs, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
37
40
  import { cleanupResultIndexes, missionObserverResultCandidateFiles } from "../runs/background/result-files.ts";
38
41
  import { ASYNC_RETENTION_DELAY_MS, cleanupAsyncRetention } from "../runs/background/async-retention.ts";
39
42
  import { createResultWatcher } from "../runs/background/result-watcher.ts";
43
+ import { createResultDeliveryOwnership } from "../runs/background/result-delivery-ownership.ts";
40
44
  import { createScheduledRunManager } from "../runs/background/scheduled-runs.ts";
41
45
  import { registerSlashCommands } from "../slash/slash-commands.ts";
42
46
  import { registerPromptTemplateDelegationBridge } from "../slash/prompt-template-bridge.ts";
43
47
  import { registerMainWatchdog } from "../watchdog/register-main.ts";
44
48
  import { registerSlashSubagentBridge } from "../slash/slash-bridge.ts";
45
49
  import { createNativeSupervisorChannel } from "../intercom/native-supervisor-channel.ts";
50
+ import {
51
+ renderSupervisorReply,
52
+ renderSupervisorRequest,
53
+ SUPERVISOR_REPLY_ENTRY_TYPE,
54
+ SUPERVISOR_REQUEST_MESSAGE_TYPE,
55
+ type SupervisorRequestMessageDetails,
56
+ } from "../intercom/supervisor-ui.ts";
46
57
  import { registerHerdrStatusBridge, type HerdrStatusRun } from "../integrations/herdr-status.ts";
47
58
  import { listHerdrProjectPaneRoots, restoreHerdrProjectPaneSnapshots } from "../inspectors/herdr/project-panes.ts";
48
59
  import { registerSubagentRpcBridge } from "./rpc.ts";
49
60
  import { clearSlashSnapshots, getSlashRenderableSnapshot, resolveSlashMessageDetails, restoreSlashFinalSnapshots, type SlashMessageDetails } from "../slash/slash-live-state.ts";
50
- import { inspectSubagentStatus } from "../runs/background/run-status.ts";
51
61
  import { resolveWaitToolConfig } from "../runs/background/subagent-wait.ts";
52
62
  import { registerWaitTool } from "../runs/background/wait-tool.ts";
53
63
  import { createWaitSubscriptionManager } from "../runs/background/wait-subscriptions.ts";
54
64
  import { drainOutstandingWork } from "../runs/background/auto-drain.ts";
55
65
  import registerSubagentNotify, { parseSubagentNotifyContent, type SubagentNotifyDetails } from "../runs/background/notify.ts";
56
66
  import { formatSteeringNotice, handleSubagentSteeringNotice, SUBAGENT_STEERING_MESSAGE_TYPE, type SubagentSteeringMessageDetails } from "./steering-notices.ts";
57
- import { SUBAGENT_CHILD_ENV, SUBAGENT_PARENT_SESSION_ENV } from "../runs/shared/pi-args.ts";
67
+ import { SUBAGENT_CHILD_ENV, SUBAGENT_PARENT_SESSION_ENV } from "../runs/shared/child-runtime-config.ts";
68
+ import { disposeChildSessions } from "../runs/shared/child-session.ts";
58
69
  import { resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
59
70
  import { formatDuration, shortenPath } from "../shared/formatters.ts";
60
- import { loadConfig, resolveAsyncByDefault, resolveScheduledStoreRoot } from "./config.ts";
71
+ import { applyModelExclusionsConfig, loadConfig, resolveAsyncByDefault, resolveScheduledStoreRoot } from "./config.ts";
61
72
  import { applyInjectionBlock, renderInjectionBlock, resolveInjectableAgents, SUBAGENT_INJECTION_MARKER } from "./context-injection.ts";
62
73
  import { buildSubagentToolDescription, buildSubagentToolPromptMetadata } from "./tool-description.ts";
74
+ import { formatWorkflowPreflightSummary, normalizeWorkflowPreflight } from "../workflows/workflow-preflight.ts";
63
75
  import { finalizeToolResult } from "./tool-result.ts";
64
76
  import { collectGoalContinuationNotices } from "../missions/goal-driver.ts";
65
77
  import { restoreForegroundRunHistory } from "../runs/foreground/foreground-history.ts";
@@ -250,15 +262,25 @@ function workflowLaneKeys(script: string): string[] {
250
262
  return keys;
251
263
  }
252
264
 
253
- function formatWorkflowManifest(script: string, async: unknown, clarify: unknown): string {
265
+ function formatWorkflowPreflightCall(input: unknown): string {
266
+ if (input === undefined) return "";
267
+ try {
268
+ return formatWorkflowPreflightSummary(normalizeWorkflowPreflight(input));
269
+ } catch (error) {
270
+ return `preflight · rejected: ${error instanceof Error ? error.message : String(error)}`;
271
+ }
272
+ }
273
+
274
+ function formatWorkflowManifest(script: string, async: unknown, clarify: unknown, preflightInput?: unknown): string {
254
275
  if (clarify === true) return "workflow script · rejected: clarify UI unsupported";
255
276
  const keys = workflowLaneKeys(script);
256
277
  // The workflow executor starts background work unless callers pass async:false.
257
278
  const mode = async === false ? "foreground" : "background";
258
- if (keys.length === 0) return `workflow script · ${mode}`;
279
+ const preflight = formatWorkflowPreflightCall(preflightInput);
280
+ if (keys.length === 0) return `workflow script · ${mode}${preflight ? ` · ${preflight}` : ""}`;
259
281
  const visibleKeys = keys.slice(0, 4).join(", ");
260
282
  const remainder = keys.length > 4 ? `, +${keys.length - 4}` : "";
261
- return `workflow · ${mode} · ${keys.length} lane${keys.length === 1 ? "" : "s"}: ${visibleKeys}${remainder}`;
283
+ return `workflow · ${mode} · ${keys.length} lane${keys.length === 1 ? "" : "s"}: ${visibleKeys}${remainder}${preflight ? ` · ${preflight}` : ""}`;
262
284
  }
263
285
 
264
286
  /**
@@ -291,10 +313,6 @@ function isSlashResultError(result: { details?: Details }): boolean {
291
313
  return result.details?.results.some((entry) => entry.exitCode !== 0 && entry.progress?.status !== "running") || false;
292
314
  }
293
315
 
294
- function isStaleExtensionContextError(error: unknown): boolean {
295
- return error instanceof Error && error.message.includes("Extension context no longer active");
296
- }
297
-
298
316
  function rebuildSlashResultContainer(
299
317
  container: Container,
300
318
  result: AgentToolResult<Details>,
@@ -384,9 +402,13 @@ export function projectActiveHerdrRuns(state: SubagentState): HerdrStatusRun[] {
384
402
  .filter((job) => active(job.status))
385
403
  .map((job) => {
386
404
  const children = job.mode === "workflow" ? foregroundChildrenByWorkflow.get(job.asyncId) : undefined;
405
+ const currentStep = job.steps?.find((step) => step.status === "running")
406
+ ?? (job.currentStep !== undefined ? job.steps?.[job.currentStep] : undefined)
407
+ ?? job.steps?.find((step) => step.status === "pending");
387
408
  return {
388
409
  id: job.asyncId,
389
410
  agents: children?.length ? children.map((child) => child.agent) : job.agents,
411
+ ...(currentStep?.label ? { taskLabel: currentStep.label } : {}),
390
412
  needsAttention: job.activityState === "needs_attention" || children?.some((child) => child.needsAttention),
391
413
  };
392
414
  });
@@ -403,6 +425,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
403
425
  cleanupOldChainDirs();
404
426
 
405
427
  const config = loadConfig();
428
+ // Apply the process-wide exclusion TTL before any child launch can record a model failure.
429
+ applyModelExclusionsConfig(config);
406
430
  const waitToolConfig = resolveWaitToolConfig(config.waitTool);
407
431
  const asyncByDefault = resolveAsyncByDefault(config);
408
432
  const fleetViewEnabled = config.fleetView !== false;
@@ -424,6 +448,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
424
448
  const state: SubagentState = {
425
449
  baseCwd: "",
426
450
  currentSessionId: null,
451
+ statusProjectionSessionId: null,
427
452
  completionOwnerId: currentCompletionOwnerId(),
428
453
  artifactDirPreference: config.artifactDir ?? DEFAULT_ARTIFACT_CONFIG.dir,
429
454
  ...(config.authorityPolicy ? { authorityPolicy: config.authorityPolicy } : {}),
@@ -457,16 +482,31 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
457
482
  clear: () => {},
458
483
  },
459
484
  };
485
+ const withLastUiContext = <T>(run: (ctx: ExtensionContext) => T): T | undefined => {
486
+ const cached = state.lastUiContext;
487
+ return withCachedUiContext(cached, () => {
488
+ if (state.lastUiContext === cached) state.lastUiContext = null;
489
+ }, run);
490
+ };
460
491
 
461
492
  const supervisorChannel = createNativeSupervisorChannel(pi, state);
462
493
  const waitSubscriptionManager = createWaitSubscriptionManager(pi, state);
463
494
  const mainWatchdog = registerMainWatchdog(pi);
464
- const completionNotifier = registerSubagentNotify(pi, state, { batchConfig: config.completionBatch });
495
+ const resultDeliveryOwnership = createResultDeliveryOwnership(state);
496
+ const completionNotifier = registerSubagentNotify(pi, state, { batchConfig: config.completionBatch, ownership: resultDeliveryOwnership });
465
497
  const fleetStatus = fleetViewEnabled
466
498
  ? new SubagentFleetStatus(state, async (itemKey) => {
467
- const ctx = state.lastUiContext;
468
- if (!ctx?.hasUI) return;
469
- await openSubagentFleet(ctx, state, { initialKey: itemKey, asyncDirRoot: DIRS.async, resultsDir: DIRS.results, fleetKeybindings: config.fleetKeybindings });
499
+ const ctx = withLastUiContext((current) => current);
500
+ if (!ctx) return;
501
+ try {
502
+ await openSubagentFleet(ctx, state, { initialKey: itemKey, asyncDirRoot: DIRS.async, resultsDir: DIRS.results, fleetKeybindings: config.fleetKeybindings });
503
+ } catch (error) {
504
+ if (isStaleExtensionContextError(error)) {
505
+ if (state.lastUiContext === ctx) state.lastUiContext = null;
506
+ return;
507
+ }
508
+ throw error;
509
+ }
470
510
  }, { placement: fleetViewPlacement })
471
511
  : undefined;
472
512
  let executorScheduled: ((id: string, params: SubagentParamsLike, signal: AbortSignal, ctx: ExtensionContext) => Promise<AgentToolResult<Details>>) | undefined;
@@ -495,10 +535,11 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
495
535
  if (scheduledRunManager.observedCompletionRunIds().size > 0) return true;
496
536
  return missionObserverResultCandidateFiles(DIRS.results).length > 0;
497
537
  };
498
- const discoverAgentsForRuntime = (cwd: string, scope: AgentScope) => {
499
- const discovered = discoverAgents(cwd, scope);
500
- if (listRuntimeAgentConfigs(pi).length === 0) return discovered;
501
- const all = discoverAgentsAll(cwd);
538
+ const discoverAgentsForRuntime = (cwd: string, scope: AgentScope, preferredModelProvider?: string) => {
539
+ if (listRuntimeAgentConfigs(pi).length === 0) return discoverAgents(cwd, scope, preferredModelProvider);
540
+ const snapshot = discoverAgentSnapshot(cwd, scope, preferredModelProvider, { includeChains: false });
541
+ const discovered = snapshot.effective;
542
+ const all = snapshot.all;
502
543
  const configuredAgents: AgentConfig[] = [
503
544
  ...all.builtin,
504
545
  ...all.package,
@@ -515,6 +556,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
515
556
  const { ensurePoller, refreshWidget, handleStarted, handleComplete, resetJobs, restoreActiveJobs, dispose: disposeAsyncJobTracker } = createAsyncJobTracker(pi, state, DIRS.async, {
516
557
  widgetEnabled: asyncWidgetEnabled,
517
558
  onJobTerminal: () => refreshResultDelivery(),
559
+ supervisorRequestState: supervisorChannel.getSupervisorRequestState,
518
560
  });
519
561
  const resultWatcher = createResultWatcher(
520
562
  pi,
@@ -523,6 +565,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
523
565
  10 * 60 * 1000,
524
566
  {
525
567
  notifier: completionNotifier,
568
+ ownership: resultDeliveryOwnership,
526
569
  observeCompletion: (result) => scheduledRunManager.handleAsyncCompletion(result),
527
570
  observedCompletionRunIds: () => scheduledRunManager.observedCompletionRunIds(),
528
571
  hasDeliveryDemand: hasResultDeliveryDemand,
@@ -530,7 +573,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
530
573
  resultScanLogging: config.resultScanLogging,
531
574
  },
532
575
  );
533
- const { startResultWatcher, primeExistingResults, stopResultWatcher } = resultWatcher;
576
+ const { startResultWatcher, transitionResultDelivery, primeExistingResults, stopResultWatcher } = resultWatcher;
534
577
  refreshResultDelivery = resultWatcher.refreshResultDelivery;
535
578
  const asyncRetentionAbort = new AbortController();
536
579
  const asyncRetentionTimer = setTimeout(async () => {
@@ -557,6 +600,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
557
600
  config,
558
601
  asyncByDefault,
559
602
  waitToolEnabled: waitToolConfig.enabled,
603
+ waitToolDefaultTimeoutMs: waitToolConfig.defaultTimeoutMs,
560
604
  handleScheduledRunAction: (params, ctx) => scheduledRunManager.handleToolCall(params, ctx),
561
605
  watchdog: mainWatchdog,
562
606
  tempArtifactsDir,
@@ -568,6 +612,14 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
568
612
  });
569
613
  executorScheduled = executor.executeScheduled;
570
614
 
615
+ pi.registerMessageRenderer<SupervisorRequestMessageDetails>(SUPERVISOR_REQUEST_MESSAGE_TYPE, renderSupervisorRequest);
616
+ const registerEntryRenderer = (pi as unknown as {
617
+ registerEntryRenderer?: (customType: string, renderer: (entry: { data?: unknown }, options: { expanded: boolean }, theme: ExtensionContext["ui"]["theme"]) => Component | undefined) => void;
618
+ }).registerEntryRenderer;
619
+ if (typeof registerEntryRenderer === "function") {
620
+ registerEntryRenderer.call(pi, SUPERVISOR_REPLY_ENTRY_TYPE, renderSupervisorReply);
621
+ }
622
+
571
623
  pi.registerMessageRenderer<SlashMessageDetails>(SLASH_RESULT_TYPE, (message, options, theme) => {
572
624
  const details = resolveSlashMessageDetails(message.details);
573
625
  if (!details) return undefined;
@@ -644,7 +696,6 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
644
696
 
645
697
  const slashBridge = registerSlashSubagentBridge({
646
698
  events: pi.events,
647
- asyncByDefault,
648
699
  getContext: () => state.lastUiContext,
649
700
  execute: (id, params, signal, onUpdate, ctx) =>
650
701
  executeSubagentCollapsed(id, params, signal, onUpdate, ctx),
@@ -693,7 +744,13 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
693
744
  }
694
745
  if (args.workflowScript)
695
746
  return new Text(
696
- `${title}${gap}${formatWorkflowManifest(args.workflowScript, args.async, false)}`,
747
+ `${title}${gap}${formatWorkflowManifest(args.workflowScript, args.async, false, args.preflight)}`,
748
+ 0,
749
+ 0,
750
+ );
751
+ if (args.workflowScriptPath)
752
+ return new Text(
753
+ `${title}${gap}${theme.fg("accent", args.workflowScriptPath)}${args.async === true ? `${gap}${theme.fg("warning", "[async]")}` : ""}${args.preflight !== undefined ? `${gap}${theme.fg("dim", formatWorkflowPreflightCall(args.preflight))}` : ""}`,
697
754
  0,
698
755
  0,
699
756
  );
@@ -717,7 +774,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
717
774
 
718
775
  pi.registerTool(tool);
719
776
 
720
- registerWaitTool(pi, state, waitToolConfig.enabled, waitSubscriptionManager);
777
+ registerWaitTool(pi, state, waitToolConfig.enabled, waitSubscriptionManager, waitToolConfig.defaultTimeoutMs);
721
778
 
722
779
  pi.on("agent_end", async (_event, ctx) => {
723
780
  if (!ctx.hasUI) await drainOutstandingWork({ state, events: pi.events });
@@ -740,7 +797,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
740
797
  }
741
798
  });
742
799
 
743
- registerSlashCommands(pi, state, {
800
+ const disposeSlashCommands = registerSlashCommands(pi, state, {
744
801
  fleetKeybindings: config.fleetKeybindings,
745
802
  foregroundDetachShortcut: config.foregroundDetachShortcut,
746
803
  });
@@ -780,6 +837,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
780
837
  fleetStatus?.refresh();
781
838
  };
782
839
  const eventUnsubscribes = [
840
+ registerRuntimeAgentEventListener(pi),
783
841
  pi.events.on(SUBAGENT_ASYNC_STARTED_EVENT, asyncStartedHandler),
784
842
  pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, asyncCompleteHandler),
785
843
  pi.events.on(SUBAGENT_PROCESS_TERMINAL_EVENT, () => {
@@ -796,7 +854,9 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
796
854
  if (event.toolName !== "subagent") return;
797
855
  if (!ctx.hasUI) return;
798
856
  state.lastUiContext = ctx;
857
+ const activeJobCount = state.asyncJobs.size;
799
858
  restoreActiveJobs(ctx);
859
+ if (state.asyncJobs.size > activeJobCount) herdrStatusBridge.syncRuns();
800
860
  fleetStatus?.setContext(ctx);
801
861
  fleetStatus?.refresh();
802
862
  if (state.asyncJobs.size > 0) {
@@ -819,14 +879,13 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
819
879
  const suspendWidgetsForCompaction = () => {
820
880
  if (state.widgetsSuspended) return;
821
881
  state.widgetsSuspended = true;
822
- if (state.lastUiContext?.hasUI) state.lastUiContext.ui.setWidget(WIDGET_KEY, undefined);
882
+ withLastUiContext((ctx) => ctx.ui.setWidget(WIDGET_KEY, undefined));
823
883
  fleetStatus?.refresh();
824
884
  };
825
885
  const resumeWidgetsAfterCompaction = () => {
826
886
  if (!state.widgetsSuspended) return;
827
887
  state.widgetsSuspended = false;
828
- const ctx = state.lastUiContext;
829
- if (ctx?.hasUI) refreshWidget(ctx);
888
+ withLastUiContext((ctx) => refreshWidget(ctx));
830
889
  fleetStatus?.refresh();
831
890
  };
832
891
 
@@ -838,16 +897,20 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
838
897
  state.activeAsyncCapacity = getActiveAsyncCapacitySnapshot(
839
898
  state.currentSessionId,
840
899
  resolveMaxActiveAsyncRunsPerSession(config.maxActiveAsyncRunsPerSession),
841
- { liveWorkflowRunIds: new Set(state.workflowControllers?.keys() ?? []) },
900
+ { liveWorkflowRunIds: new Set(state.workflowControllers?.keys() ?? []), abandonedSlotReleaseAfterMs: resolveAbandonedSlotReleaseAfterMs(config.capacity?.abandonedSlotReleaseAfterMs) },
842
901
  );
843
902
  };
844
903
 
845
- const resetSessionState = (ctx: ExtensionContext, recovering: boolean) => {
904
+ const resetSessionState = (ctx: ExtensionContext, recovering: boolean, previousSessionFile?: string) => {
846
905
  state.widgetsSuspended = false;
847
906
  state.baseCwd = ctx.cwd;
848
907
  goalTurnId = 0;
908
+ const previousRuntimeSessionId = state.currentSessionId;
909
+ resultDeliveryOwnership.claimPredecessor(previousSessionFile, previousRuntimeSessionId);
849
910
  state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
911
+ transitionResultDelivery();
850
912
  state.parentSessionFile = ctx.sessionManager.getSessionFile();
913
+ state.trustedSessionFileRoot = state.parentSessionFile ? path.join(getAgentDir(), "sessions") : undefined;
851
914
  state.trustedSessionRoots = [...new Set([
852
915
  ...(config.defaultSessionDir ? [path.resolve(expandTilde(config.defaultSessionDir))] : []),
853
916
  ...(state.parentSessionFile ? [getSubagentSessionRoot(state.parentSessionFile)] : []),
@@ -862,10 +925,10 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
862
925
  const projectPaneOwnerRoot = path.resolve(ctx.cwd);
863
926
  restoreHerdrProjectPaneSnapshots(state, [...new Set([...(state.herdrProjectPanes?.keys() ?? []), ...listHerdrProjectPaneRoots(projectPaneOwnerRoot), projectPaneOwnerRoot])]);
864
927
  // Set PI_SUBAGENT_PARENT_SESSION for permission-system forwarding.
865
- // Only set in the root session (the interactive UI session), not in
866
- // child subagent processes — children inherit the parent's value
867
- // through the process environment at spawn time and must not overwrite
868
- // it with their own session identity.
928
+ // Only set in the root session (the interactive UI session), not in a
929
+ // child host: the runner process inherits the parent's value through
930
+ // its environment at spawn time and must not overwrite it with a child
931
+ // session's identity.
869
932
  if (!process.env[SUBAGENT_CHILD_ENV]) {
870
933
  const sessionId = ctx.sessionManager.getSessionId();
871
934
  if (sessionId) {
@@ -946,11 +1009,19 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
946
1009
  if (runtimeCleaned) return;
947
1010
  runtimeCleaned = true;
948
1011
  const shuttingDownParentSession = parentSessionEnvValue;
1012
+ // Workflow continuations retain their launch context; abort them before
1013
+ // teardown so a reload cannot launch through a stale context.
1014
+ for (const controller of state.workflowControllers?.values() ?? []) {
1015
+ if (!controller.signal.aborted) controller.abort(new Error("Workflow stopped because the extension session was replaced or reloaded."));
1016
+ }
1017
+ state.workflowControllers?.clear();
1018
+ state.workflowChildStops?.clear();
949
1019
  clearRuntimeAgentsForPi(pi);
950
1020
  clearTimeout(resultIndexCleanupTimer);
951
1021
  clearTimeout(asyncRetentionTimer);
952
1022
  asyncRetentionAbort.abort();
953
1023
  stopResultWatcher();
1024
+ resultDeliveryOwnership.clear();
954
1025
  completionNotifier.dispose();
955
1026
  mainWatchdog.dispose();
956
1027
  scheduledRunManager.stop();
@@ -968,12 +1039,14 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
968
1039
  // Best effort cleanup during shutdown or reload.
969
1040
  }
970
1041
  }
1042
+ disposeSlashCommands.dispose();
971
1043
  slashBridge.cancelAll();
972
1044
  slashBridge.dispose();
973
1045
  promptTemplateBridge.cancelAll();
974
1046
  promptTemplateBridge.dispose();
975
1047
  state.widgetsSuspended = false;
976
1048
  state.currentSessionId = null;
1049
+ state.statusProjectionSessionId = null;
977
1050
  state.parentSessionFile = null;
978
1051
  parentSessionEnvValue = null;
979
1052
  if (shuttingDownParentSession && process.env[SUBAGENT_PARENT_SESSION_ENV] === shuttingDownParentSession) {
@@ -1037,7 +1110,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1037
1110
 
1038
1111
  pi.on("session_compact", () => {
1039
1112
  const hasActiveAsyncWork = [...state.asyncJobs.values()].some((job) => job.status === "queued" || job.status === "running");
1040
- if (!hasActiveAsyncWork || state.lastUiContext?.hasUI !== true) return;
1113
+ if (!hasActiveAsyncWork || !withLastUiContext(() => true)) return;
1041
1114
  pi.sendMessage(
1042
1115
  {
1043
1116
  customType: "subagent-compaction-resume",
@@ -1051,7 +1124,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1051
1124
  pi.on("session_start", (event, ctx) => {
1052
1125
  installRuntime(ctx);
1053
1126
  const recovering = event.reason === "startup" || event.reason === "reload" || event.reason === "resume";
1054
- resetSessionState(ctx, recovering);
1127
+ resetSessionState(ctx, recovering, event.previousSessionFile);
1055
1128
  refreshContextInjectionSnapshot(ctx);
1056
1129
  herdrStatusBridge.sessionStarted({
1057
1130
  hasUI: ctx.hasUI === true,
@@ -1073,6 +1146,11 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1073
1146
 
1074
1147
  pi.on("session_shutdown", async () => {
1075
1148
  runtimeEntry.cleanup();
1149
+ try {
1150
+ await disposeChildSessions();
1151
+ } catch (error) {
1152
+ console.error("Failed to dispose in-process child sessions:", error);
1153
+ }
1076
1154
  await herdrStatusBridge.flush();
1077
1155
  });
1078
1156
  }
@@ -1,7 +1,17 @@
1
+ import { normalizeWorktreeBaseRef } from "../runs/shared/worktree.ts";
2
+
1
3
  export interface PublicSubagentExecutionParams {
2
4
  action?: unknown;
5
+ capabilities?: unknown;
6
+ mode?: unknown;
7
+ repo?: unknown;
8
+ planId?: unknown;
3
9
  agent?: unknown;
4
10
  task?: unknown;
11
+ handoffPath?: unknown;
12
+ laneId?: unknown;
13
+ merge?: unknown;
14
+ supersession?: unknown;
5
15
  step?: unknown;
6
16
  tasks?: unknown;
7
17
  chain?: unknown;
@@ -10,9 +20,18 @@ export interface PublicSubagentExecutionParams {
10
20
  chainDir?: unknown;
11
21
  chainName?: unknown;
12
22
  config?: unknown;
23
+ workflow?: unknown;
24
+ args?: unknown;
13
25
  workflowScript?: unknown;
26
+ workflowScriptPath?: unknown;
27
+ sessionOnly?: unknown;
28
+ globalConcurrencyLimit?: unknown;
29
+ maxSubagentSpawnsPerRun?: unknown;
30
+ preflight?: unknown;
14
31
  isolation?: unknown;
15
32
  worktree?: unknown;
33
+ baseRef?: unknown;
34
+ lane?: unknown;
16
35
  async?: unknown;
17
36
  output?: unknown;
18
37
  resume?: unknown;
@@ -21,6 +40,7 @@ export interface PublicSubagentExecutionParams {
21
40
  workflowKey?: unknown;
22
41
  workflowChildAsyncId?: unknown;
23
42
  workflowAwaitAsync?: unknown;
43
+ workflowAwaitDetached?: unknown;
24
44
  workflowParentDeadlineAt?: unknown;
25
45
  suppressRoutineResultIntercom?: unknown;
26
46
  runFanoutBudget?: unknown;
@@ -33,33 +53,92 @@ export type PublicSubagentExecutionNormalization<T> =
33
53
  | { ok: true; params: T }
34
54
  | { ok: false; error: string; mode: PublicSubagentExecutionMode };
35
55
 
56
+ export function validateWorkflowCapacityOverrides(params: PublicSubagentExecutionParams): string | undefined {
57
+ for (const [name, value] of [
58
+ ["globalConcurrencyLimit", params.globalConcurrencyLimit],
59
+ ["maxSubagentSpawnsPerRun", params.maxSubagentSpawnsPerRun],
60
+ ] as const) {
61
+ if (value !== undefined && (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)) return `${name} must be a positive safe integer.`;
62
+ }
63
+ }
64
+
36
65
  /**
37
66
  * Enforce the public execution cutover before requests reach the executor.
38
67
  * Internal runs.run children and structured owned delegation bypass this boundary.
39
68
  */
40
- export function normalizePublicSubagentExecution<T extends PublicSubagentExecutionParams>(params: T, options: { asyncByDefault?: boolean } = {}): PublicSubagentExecutionNormalization<T> {
69
+ export function normalizePublicSubagentExecution<T extends PublicSubagentExecutionParams>(params: T): PublicSubagentExecutionNormalization<T> {
70
+ for (const field of ["resource", "resourceProvenance", "workflowResource", "workflowResourceProvenance", "workflowResourcePermit", "resourcePermit", "permit"] as const) {
71
+ if (Object.hasOwn(params, field) && (params as Record<string, unknown>)[field] !== undefined) {
72
+ return { ok: false, error: "Public execution does not accept workflow resource provenance or permit fields.", mode: params.action === undefined ? "workflow" : "management" };
73
+ }
74
+ }
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
+ try {
78
+ normalizeWorktreeBaseRef(params.baseRef);
79
+ } catch (error) {
80
+ return { ok: false, error: error instanceof Error ? error.message : String(error), mode: params.action === undefined ? "workflow" : "management" };
81
+ }
82
+ }
83
+ if (params.workflowScript !== undefined && params.workflowScriptPath !== undefined) {
84
+ return { ok: false, error: "workflowScript and workflowScriptPath are mutually exclusive.", mode: "workflow" };
85
+ }
86
+ const hasNamedWorkflow = params.workflow !== undefined;
87
+ if (hasNamedWorkflow && (typeof params.workflow !== "string" || !params.workflow.trim())) {
88
+ return { ok: false, error: "workflow must be a non-empty named workflow resource.", mode: "workflow" };
89
+ }
90
+ if (hasNamedWorkflow && (params.workflowScript !== undefined || params.workflowScriptPath !== undefined)) {
91
+ return { ok: false, error: "workflow is mutually exclusive with workflowScript and workflowScriptPath.", mode: "workflow" };
92
+ }
93
+ if (!hasNamedWorkflow && params.args !== undefined) {
94
+ return { ok: false, error: "args requires a named workflow resource.", mode: "workflow" };
95
+ }
96
+ const hasWorkflowInput = params.workflowScript !== undefined || params.workflowScriptPath !== undefined || hasNamedWorkflow;
97
+ const hasCapacityOverride = params.globalConcurrencyLimit !== undefined || params.maxSubagentSpawnsPerRun !== undefined;
98
+ if (hasCapacityOverride) {
99
+ const capacityOverrideError = validateWorkflowCapacityOverrides(params);
100
+ 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" };
103
+ }
104
+ }
105
+ if (params.preflight !== undefined && !hasWorkflowInput) {
106
+ return { ok: false, error: "preflight requires workflowScript or workflowScriptPath.", mode: params.action === undefined ? "workflow" : "management" };
107
+ }
108
+ if (params.preflight !== undefined && hasNamedWorkflow && params.workflowScript === undefined && params.workflowScriptPath === undefined) {
109
+ return { ok: false, error: "preflight is not supported with named workflow resources.", mode: "workflow" };
110
+ }
111
+ const hasValidWorkflowInput = (typeof params.workflowScript === "string" && Boolean(params.workflowScript.trim()))
112
+ || (typeof params.workflowScriptPath === "string" && Boolean(params.workflowScriptPath.trim()))
113
+ || (typeof params.workflow === "string" && Boolean(params.workflow.trim()));
41
114
  if (params.isolation !== undefined) {
42
115
  if (params.isolation !== "none" && params.isolation !== "worktree") {
43
- return { ok: false, error: "isolation must be 'none' or 'worktree'.", mode: params.workflowScript !== undefined ? "workflow" : "management" };
116
+ return { ok: false, error: "isolation must be 'none' or 'worktree'.", mode: hasWorkflowInput ? "workflow" : "management" };
44
117
  }
45
118
  const isolationWorktree = params.isolation === "worktree";
46
119
  if (params.worktree !== undefined && params.worktree !== isolationWorktree) {
47
- return { ok: false, error: `isolation '${params.isolation}' conflicts with worktree: ${String(params.worktree)}.`, mode: params.workflowScript !== undefined ? "workflow" : "management" };
120
+ return { ok: false, error: `isolation '${params.isolation}' conflicts with worktree: ${String(params.worktree)}.`, mode: hasWorkflowInput ? "workflow" : "management" };
48
121
  }
49
122
  const { isolation: _isolation, ...normalizedParams } = params;
50
123
  params = { ...normalizedParams, worktree: isolationWorktree } as T;
51
124
  }
52
125
  if (params.runFanoutBudget !== undefined || params.runFanoutAdmitted !== undefined) {
53
- return { ok: false, error: "Public execution does not accept internal run fan-out fields.", mode: params.workflowScript !== undefined ? "workflow" : "management" };
126
+ return { ok: false, error: "Public execution does not accept internal run fan-out fields.", mode: hasWorkflowInput ? "workflow" : "management" };
54
127
  }
55
- if (params.workflowParentRunId !== undefined || params.workflowKey !== undefined || params.workflowChildAsyncId !== undefined || params.workflowAwaitAsync !== undefined || params.workflowParentDeadlineAt !== undefined || params.suppressRoutineResultIntercom !== undefined) {
56
- return { ok: false, error: "Public execution does not accept internal workflow child fields.", mode: params.workflowScript !== undefined ? "workflow" : "management" };
128
+ if (params.workflowParentRunId !== undefined || params.workflowKey !== undefined || params.workflowChildAsyncId !== undefined || params.workflowAwaitAsync !== undefined || params.workflowAwaitDetached !== undefined || params.workflowParentDeadlineAt !== undefined || params.suppressRoutineResultIntercom !== undefined) {
129
+ return { ok: false, error: "Public execution does not accept internal workflow child fields.", mode: hasWorkflowInput ? "workflow" : "management" };
57
130
  }
58
131
  const action = params.action;
59
132
  if (action !== undefined && (typeof action !== "string" || !action.trim())) {
60
133
  return { ok: false, error: "action must be a non-empty management/control action, or omit action and use workflowScript.", mode: "management" };
61
134
  }
62
135
  const normalizedAction = typeof action === "string" ? action.trim() : undefined;
136
+ if (params.baseRef !== undefined && normalizedAction !== undefined && normalizedAction !== "resume" && normalizedAction !== "schedule.create") {
137
+ return { ok: false, error: "baseRef is only supported for child execution, resume, and schedule.create.", mode: "management" };
138
+ }
139
+ if (normalizedAction !== undefined && hasNamedWorkflow) {
140
+ return { ok: false, error: "Named workflow resource execution must omit action.", mode: "management" };
141
+ }
63
142
  if (params.clarify !== undefined) {
64
143
  return { ok: false, error: "Public workflowScript execution does not support clarify UI.", mode: "workflow" };
65
144
  }
@@ -90,17 +169,26 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
90
169
  if (legacyAction === "parallel" || legacyAction === "tasks" || legacyAction === "chain") {
91
170
  return { ok: false, error: "Legacy top-level chain and parallel inputs were removed; use workflowScript.", mode: "workflow" };
92
171
  }
172
+ if (normalizedAction === "validate") {
173
+ if (params.agent !== undefined || params.task !== undefined || params.step !== undefined) {
174
+ return { ok: false, error: "validate requires workflowScript or workflowScriptPath and does not accept direct agent, task, or step execution fields.", mode: "management" };
175
+ }
176
+ if (!hasValidWorkflowInput) {
177
+ return { ok: false, error: "validate requires a non-empty workflowScript or workflowScriptPath.", mode: "management" };
178
+ }
179
+ return { ok: true, params: { ...params, action: normalizedAction } };
180
+ }
93
181
  if (normalizedAction === "schedule.create") {
94
182
  if (params.agent !== undefined || params.task !== undefined || params.step !== undefined) {
95
- return { ok: false, error: "schedule.create requires workflowScript and does not accept direct agent, task, or step execution fields.", mode: "management" };
183
+ return { ok: false, error: "schedule.create requires workflowScript or workflowScriptPath and does not accept direct agent, task, or step execution fields.", mode: "management" };
96
184
  }
97
- if (typeof params.workflowScript !== "string" || !params.workflowScript.trim()) {
98
- return { ok: false, error: "schedule.create requires a non-empty workflowScript.", mode: "management" };
185
+ if (!hasValidWorkflowInput) {
186
+ return { ok: false, error: "schedule.create requires a non-empty workflowScript or workflowScriptPath.", mode: "management" };
99
187
  }
100
188
  return { ok: true, params: { ...params, action: normalizedAction } };
101
189
  }
102
- if (params.workflowScript !== undefined) {
103
- return { ok: false, error: "workflowScript execution must omit action; only schedule.create accepts action with workflowScript.", mode: "management" };
190
+ if (hasWorkflowInput) {
191
+ return { ok: false, error: "Workflow execution must omit action; only validate and schedule.create accept action with workflowScript or workflowScriptPath.", mode: "management" };
104
192
  }
105
193
  if (params.task !== undefined) {
106
194
  return { ok: false, error: "Structured single-child task cannot be combined with a management/control action.", mode: "management" };
@@ -110,8 +198,8 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
110
198
  if (params.step !== undefined) {
111
199
  return { ok: false, error: "step is not a public execution field; use workflowScript for orchestration.", mode: "workflow" };
112
200
  }
113
- if (params.workflowScript !== undefined && (params.agent !== undefined || params.task !== undefined)) {
114
- return { ok: false, error: "Structured single-child execution cannot be combined with workflowScript.", mode: "workflow" };
201
+ if (hasWorkflowInput && (params.agent !== undefined || params.task !== undefined)) {
202
+ return { ok: false, error: "Structured single-child execution cannot be combined with workflow, workflowScript, or workflowScriptPath.", mode: "workflow" };
115
203
  }
116
204
  if (params.agent !== undefined || params.task !== undefined) {
117
205
  if (typeof params.agent !== "string" || !params.agent.trim()) {
@@ -129,8 +217,8 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
129
217
  } as T,
130
218
  };
131
219
  }
132
- if (typeof params.workflowScript !== "string" || !params.workflowScript.trim()) {
133
- return { ok: false, error: "Execution requires either { agent, task? } for one child or a non-empty workflowScript for orchestration.", mode: "workflow" };
220
+ if (!hasValidWorkflowInput) {
221
+ return { ok: false, error: "Execution requires either { agent, task? } for one child, a named workflow resource, or a non-empty workflowScript or workflowScriptPath for orchestration.", mode: "workflow" };
134
222
  }
135
223
  return { ok: true, params };
136
224
  }