@xzzpig/pi-subagents 0.7.0 → 0.9.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 (234) hide show
  1. package/CHANGELOG.md +456 -4
  2. package/README.md +3 -3
  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 +13 -3
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +154 -42
  12. package/docs/configuration.md +85 -26
  13. package/docs/extension-api.md +81 -16
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +75 -11
  16. package/docs/observability.md +34 -21
  17. package/docs/tool-reference.md +142 -18
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +148 -4
  20. package/index.ts +10 -1
  21. package/install.mjs +1 -1
  22. package/package.json +7 -6
  23. package/prompts/council.md +19 -7
  24. package/prompts/parallel-review.md +5 -1
  25. package/prompts/review-loop.md +11 -7
  26. package/skills/council-mode/SKILL.md +44 -215
  27. package/skills/council-mode/references/pass-contracts.md +150 -0
  28. package/skills/pi-subagents/SKILL.md +90 -32
  29. package/skills/pi-subagents/references/constraints-and-recipes.md +34 -223
  30. package/skills/pi-subagents/references/execution-controls.md +104 -19
  31. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  32. package/skills/pi-subagents/references/multi-lane-orchestration.md +16 -4
  33. package/skills/pi-subagents/references/prompting-and-roles.md +71 -36
  34. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  35. package/src/agents/agent-management.ts +471 -114
  36. package/src/agents/agent-refinements.ts +4 -4
  37. package/src/agents/agent-serializer.ts +16 -4
  38. package/src/agents/agents.ts +1076 -351
  39. package/src/agents/builtin-names.ts +6 -0
  40. package/src/agents/runtime-agent-events.ts +70 -0
  41. package/src/agents/runtime-agent-registry.ts +31 -20
  42. package/src/api/agents.ts +10 -5
  43. package/src/api/background-work.ts +12 -3
  44. package/src/api/capability-ceiling.ts +0 -1
  45. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  46. package/src/api/delegation.ts +0 -7
  47. package/src/api/external-job-provider.ts +10 -1
  48. package/src/api/external-runs.ts +67 -4
  49. package/src/api/preflight.ts +97 -34
  50. package/src/api/project-panes.ts +2 -0
  51. package/src/api/shared-types.ts +6 -0
  52. package/src/extension/config.ts +90 -0
  53. package/src/extension/doctor.ts +15 -13
  54. package/src/extension/fanout-child.ts +17 -16
  55. package/src/extension/index.ts +139 -41
  56. package/src/extension/public-execution.ts +113 -22
  57. package/src/extension/rpc.ts +182 -13
  58. package/src/extension/schemas.ts +63 -21
  59. package/src/extension/tool-description.ts +48 -23
  60. package/src/extension/tool-result.ts +19 -0
  61. package/src/inspectors/herdr/actions.ts +2 -1
  62. package/src/inspectors/herdr/client.ts +3 -3
  63. package/src/inspectors/herdr/focus.ts +55 -0
  64. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  65. package/src/inspectors/herdr/project-panes.ts +228 -44
  66. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  67. package/src/integrations/herdr-status.ts +75 -5
  68. package/src/intercom/native-supervisor-channel.ts +138 -60
  69. package/src/intercom/result-intercom.ts +2 -0
  70. package/src/intercom/supervisor-ui.ts +243 -0
  71. package/src/profiles/profiles.ts +5 -6
  72. package/src/runs/background/active-async-capacity.ts +103 -18
  73. package/src/runs/background/async-execution.ts +492 -125
  74. package/src/runs/background/async-job-tracker.ts +127 -28
  75. package/src/runs/background/async-resume.ts +67 -29
  76. package/src/runs/background/async-retention.ts +21 -4
  77. package/src/runs/background/async-status-snapshot.ts +23 -261
  78. package/src/runs/background/async-status.ts +199 -14
  79. package/src/runs/background/auto-drain.ts +1 -1
  80. package/src/runs/background/chain-append.ts +8 -3
  81. package/src/runs/background/chain-root-attachment.ts +79 -8
  82. package/src/runs/background/control-channel.ts +101 -214
  83. package/src/runs/background/fleet-view.ts +38 -22
  84. package/src/runs/background/inspect-rpc.ts +8 -8
  85. package/src/runs/background/notify.ts +295 -8
  86. package/src/runs/background/process-terminal.ts +16 -0
  87. package/src/runs/background/result-delivery-ownership.ts +45 -0
  88. package/src/runs/background/result-files.ts +28 -14
  89. package/src/runs/background/result-watcher.ts +43 -19
  90. package/src/runs/background/resume-guidance.ts +2 -2
  91. package/src/runs/background/retained-children.ts +1 -1
  92. package/src/runs/background/run-child-session.ts +613 -0
  93. package/src/runs/background/run-status.ts +99 -18
  94. package/src/runs/background/runner-aliases.ts +125 -0
  95. package/src/runs/background/runner-child-sessions.ts +31 -0
  96. package/src/runs/background/scheduled-runs.ts +174 -18
  97. package/src/runs/background/stale-run-reconciler.ts +13 -4
  98. package/src/runs/background/steering.ts +8 -15
  99. package/src/runs/background/subagent-runner.ts +959 -1159
  100. package/src/runs/background/subagent-wait.ts +86 -31
  101. package/src/runs/background/terminal-run-index.ts +1 -1
  102. package/src/runs/background/wait-completions.ts +45 -2
  103. package/src/runs/background/wait-config.ts +23 -9
  104. package/src/runs/background/wait-tool.ts +27 -19
  105. package/src/runs/foreground/async-steering-action.ts +3 -19
  106. package/src/runs/foreground/async-stop-action.ts +23 -2
  107. package/src/runs/foreground/execution.ts +585 -481
  108. package/src/runs/foreground/foreground-control.ts +13 -0
  109. package/src/runs/foreground/foreground-history.ts +26 -3
  110. package/src/runs/foreground/subagent-executor.ts +1549 -410
  111. package/src/runs/foreground/workflow-detach-reconcile.ts +141 -104
  112. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  113. package/src/runs/shared/abort-recovery.ts +119 -0
  114. package/src/runs/shared/acceptance.ts +147 -39
  115. package/src/runs/shared/agent-contract.ts +1 -1
  116. package/src/runs/shared/async-status-projection.ts +565 -0
  117. package/src/runs/shared/background-process-options.ts +9 -0
  118. package/src/runs/shared/capability-ceiling.ts +2 -2
  119. package/src/runs/shared/child-hooks.ts +25 -0
  120. package/src/runs/shared/child-identity.ts +62 -0
  121. package/src/runs/shared/child-launch-plan.ts +151 -0
  122. package/src/runs/shared/child-launch.ts +314 -0
  123. package/src/runs/shared/child-lifecycle.ts +25 -0
  124. package/src/runs/shared/child-runtime-config.ts +126 -0
  125. package/src/runs/shared/child-session.ts +342 -0
  126. package/src/runs/shared/child-tool-plan.ts +540 -0
  127. package/src/runs/shared/claude-code-adapter.ts +133 -0
  128. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  129. package/src/runs/shared/completion-evidence.ts +89 -0
  130. package/src/runs/shared/completion-guard.ts +57 -6
  131. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  132. package/src/runs/shared/dynamic-fanout.ts +4 -4
  133. package/src/runs/shared/extension-bindings.ts +78 -0
  134. package/src/runs/shared/external-cli-contract.ts +167 -0
  135. package/src/runs/shared/external-cli-preflight.ts +138 -0
  136. package/src/runs/shared/external-cli-runner.ts +349 -54
  137. package/src/runs/shared/external-job-bridge.ts +53 -37
  138. package/src/runs/shared/external-job-runner.ts +126 -23
  139. package/src/runs/shared/fast-mode-extension.ts +10 -0
  140. package/src/runs/shared/host-step-status.ts +231 -0
  141. package/src/runs/shared/lane-metadata.ts +126 -0
  142. package/src/runs/shared/launch-cwd.ts +16 -0
  143. package/src/runs/shared/long-running-guard.ts +2 -1
  144. package/src/runs/shared/mcp-config-sources.ts +422 -0
  145. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  146. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  147. package/src/runs/shared/model-exclusions.ts +141 -10
  148. package/src/runs/shared/model-fallback.ts +187 -33
  149. package/src/runs/shared/model-scope.ts +106 -39
  150. package/src/runs/shared/mutation-evidence.ts +199 -0
  151. package/src/runs/shared/nested-events.ts +38 -48
  152. package/src/runs/shared/nested-path.ts +0 -14
  153. package/src/runs/shared/nested-render.ts +9 -5
  154. package/src/runs/shared/orca-progress-tabs.ts +83 -16
  155. package/src/runs/shared/parallel-handoff.ts +423 -7
  156. package/src/runs/shared/parallel-utils.ts +28 -5
  157. package/src/runs/shared/permissions.ts +1 -14
  158. package/src/runs/shared/pi-spawn.ts +69 -35
  159. package/src/runs/shared/process-signal.ts +16 -0
  160. package/src/runs/shared/run-fanout-budget.ts +0 -13
  161. package/src/runs/shared/run-history.ts +21 -1
  162. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  163. package/src/runs/shared/single-output.ts +89 -22
  164. package/src/runs/shared/structured-output.ts +61 -7
  165. package/src/runs/shared/subagent-control.ts +6 -2
  166. package/src/runs/shared/subagent-prompt-runtime.ts +216 -360
  167. package/src/runs/shared/task-intent.ts +21 -7
  168. package/src/runs/shared/tool-availability.ts +18 -64
  169. package/src/runs/shared/tool-budget.ts +0 -14
  170. package/src/runs/shared/tool-timeout.ts +1 -1
  171. package/src/runs/shared/workflow-graph.ts +16 -0
  172. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  173. package/src/runs/shared/worktree.ts +571 -62
  174. package/src/shared/atomic-json.ts +3 -1
  175. package/src/shared/child-session-name.ts +46 -0
  176. package/src/shared/extension-context.ts +24 -0
  177. package/src/shared/fork-context.ts +21 -12
  178. package/src/shared/fork-session-cwd.ts +27 -0
  179. package/src/shared/formatters.ts +18 -3
  180. package/src/shared/jsonl-writer.ts +11 -0
  181. package/src/shared/launch-contract.ts +20 -6
  182. package/src/shared/pruned-fork.ts +450 -0
  183. package/src/shared/session-file-trust.ts +19 -0
  184. package/src/shared/session-tokens.ts +14 -3
  185. package/src/shared/settings.ts +21 -102
  186. package/src/shared/shortcuts.ts +17 -0
  187. package/src/shared/thinking-ceiling.ts +46 -0
  188. package/src/shared/types.ts +644 -75
  189. package/src/shared/utils.ts +60 -93
  190. package/src/shared/workflow-child-permit.ts +207 -0
  191. package/src/slash/delegation-adapters.ts +1 -9
  192. package/src/slash/delegation-request.ts +0 -4
  193. package/src/slash/prompt-template-bridge.ts +37 -1
  194. package/src/slash/slash-bridge.ts +1 -2
  195. package/src/slash/slash-commands.ts +383 -116
  196. package/src/slash/slash-live-state.ts +22 -11
  197. package/src/slash/subagents-admin.ts +29 -12
  198. package/src/tui/fleet-native-transcript.ts +4 -0
  199. package/src/tui/fleet-status.ts +278 -90
  200. package/src/tui/fleet-transcript.ts +11 -5
  201. package/src/tui/fleet.ts +54 -28
  202. package/src/tui/render-helpers.ts +31 -0
  203. package/src/tui/render.ts +1433 -166
  204. package/src/watchdog/change-signature.ts +40 -1
  205. package/src/watchdog/child-status.ts +54 -34
  206. package/src/watchdog/diff-tool.ts +77 -0
  207. package/src/watchdog/emission-guard.ts +5 -3
  208. package/src/watchdog/guidance.ts +20 -0
  209. package/src/watchdog/permission-arbiter.ts +59 -52
  210. package/src/watchdog/register-child.ts +28 -25
  211. package/src/watchdog/register-main.ts +10 -9
  212. package/src/watchdog/render.ts +4 -5
  213. package/src/watchdog/review.ts +15 -4
  214. package/src/watchdog/rules.ts +70 -0
  215. package/src/watchdog/runtime.ts +75 -92
  216. package/src/watchdog/scope.ts +0 -11
  217. package/src/watchdog/settings.ts +48 -104
  218. package/src/watchdog/turn-delta.ts +1 -1
  219. package/src/watchdog/types.ts +18 -32
  220. package/src/watchdog/warning-format.ts +0 -1
  221. package/src/workflows/chat-progress.ts +7 -3
  222. package/src/workflows/host-command.ts +235 -0
  223. package/src/workflows/scripted-workflow.ts +1142 -69
  224. package/src/workflows/workflow-checklist.ts +439 -0
  225. package/src/workflows/workflow-child-summary.ts +121 -0
  226. package/src/workflows/workflow-preflight.ts +297 -0
  227. package/src/workflows/workflow-receipt.ts +232 -6
  228. package/src/workflows/workflow-resources.ts +150 -0
  229. package/src/workflows/workflow-settlement.ts +246 -0
  230. package/src/runs/shared/child-protocol.ts +0 -401
  231. package/src/runs/shared/pi-args.ts +0 -858
  232. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  233. package/src/runs/shared/turn-budget.ts +0 -98
  234. package/src/shared/post-exit-stdio-guard.ts +0 -85
@@ -8,12 +8,14 @@ import {
8
8
  type AsyncStartedEvent,
9
9
  type ControlEvent,
10
10
  type SteeringNotice,
11
+ type SubagentChildStatusEvent,
11
12
  type SubagentState,
12
- POLL_INTERVAL_MS,
13
13
  DIRS,
14
+ SUBAGENT_CHILD_STATUS_EVENT,
14
15
  SUBAGENT_CONTROL_EVENT,
15
16
  SUBAGENT_CONTROL_INTERCOM_EVENT,
16
17
  SUBAGENT_STEERING_NOTICE_EVENT,
18
+ WIDGET_ANIMATION_INTERVAL_MS,
17
19
  } from "../../shared/types.ts";
18
20
  import { readStatus, resolveWatchPath } from "../../shared/utils.ts";
19
21
  import { normalizeParallelGroups } from "./parallel-groups.ts";
@@ -22,6 +24,9 @@ import { findNestedRouteForRootId, hasLiveNestedDescendants, updateAsyncJobNeste
22
24
  import { listAsyncRuns, type AsyncRunSummary } from "./async-status.ts";
23
25
  import { EXTERNAL_JOB_BRIDGE_REQUEST_DIR, serviceExternalJobBridgeRequests } from "../shared/external-job-bridge.ts";
24
26
  import { shouldUseNativeFsWatch } from "../../shared/watch-strategy.ts";
27
+ import { parseWorkflowChildSummary } from "../../workflows/workflow-child-summary.ts";
28
+ import { validHostStepNodes } from "../shared/host-step-status.ts";
29
+ import { withCachedUiContext } from "../../shared/extension-context.ts";
25
30
 
26
31
  interface AsyncJobTrackerOptions {
27
32
  completionRetentionMs?: number;
@@ -34,6 +39,8 @@ interface AsyncJobTrackerOptions {
34
39
  watch?: typeof fs.watch;
35
40
  kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
36
41
  now?: () => number;
42
+ /** Resolve native supervisor requests without scanning supervisor mailboxes. */
43
+ supervisorRequestState?: (event: ControlEvent) => "pending" | "resolved" | "unknown";
37
44
  }
38
45
 
39
46
  const CONTROL_EVENT_READ_CHUNK_BYTES = 64 * 1024;
@@ -68,42 +75,58 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
68
75
  const steeringNoticeSeen = new Map<string, number>();
69
76
  const jobWatchers = new Map<string, { watchers: Map<string, fs.FSWatcher>; retryTimer?: ReturnType<typeof setTimeout> }>();
70
77
  const refreshTimers = new Map<string, ReturnType<typeof setTimeout>>();
78
+ let widgetRerenderTimer: ReturnType<typeof setTimeout> | undefined;
71
79
  const runningJobIds = new Set<string>();
80
+ const externalJobBridgeRuns = new Set<string>();
81
+ const externalJobBridgeEligibility = (steps: AsyncJobState["steps"]): "required" | "not-required" | "unknown" => {
82
+ if (!Array.isArray(steps)) return "unknown";
83
+ for (const step of steps) {
84
+ const runner = (step as { runner?: unknown } | null)?.runner;
85
+ if (runner === undefined) continue;
86
+ if (!runner || typeof runner !== "object" || Array.isArray(runner)) return "unknown";
87
+ const runnerType = (runner as { type?: unknown }).type;
88
+ if (typeof runnerType !== "string") return "unknown";
89
+ if (runnerType === "external-job") return "required";
90
+ if (runnerType !== "pi" && runnerType !== "external-cli") return "unknown";
91
+ }
92
+ return "not-required";
93
+ };
72
94
  let rootWatcher: fs.FSWatcher | undefined;
73
95
  let nextLivenessAt = Date.now() + livenessIntervalMs;
96
+ let nextWidgetAnimationAt = Date.now() + WIDGET_ANIMATION_INTERVAL_MS;
74
97
  const watch = options.watch ?? fs.watch;
75
98
  const useNativeWatcher = () => shouldUseNativeFsWatch("async-job-tracker", options.platform);
76
99
  const terminalStatus = (status: string) => status === "complete" || status === "failed" || status === "paused" || status === "stopped";
100
+ const withLastUiContext = <T>(run: (ctx: ExtensionContext) => T): T | undefined => {
101
+ const cached = state.lastUiContext;
102
+ return withCachedUiContext(cached, () => {
103
+ if (state.lastUiContext === cached) state.lastUiContext = null;
104
+ }, run);
105
+ };
77
106
  const rerenderWidget = (ctx: ExtensionContext, jobs = Array.from(state.asyncJobs.values())) => {
78
107
  if (state.widgetsSuspended) return;
79
108
  renderWidget(ctx, options.widgetEnabled === false ? [] : jobs);
80
109
  (ctx.ui as { requestRender?: () => void }).requestRender?.();
81
110
  };
82
111
  const rerenderLastWidget = (jobs = Array.from(state.asyncJobs.values())) => {
83
- const ctx = state.lastUiContext;
84
- if (!ctx) return;
85
- try {
86
- if (ctx.hasUI) rerenderWidget(ctx, jobs);
87
- } catch (error) {
88
- if (error instanceof Error && error.message.includes("extension ctx is stale")) {
89
- state.lastUiContext = null;
90
- return;
91
- }
92
- throw error;
93
- }
112
+ withLastUiContext((ctx) => rerenderWidget(ctx, jobs));
113
+ };
114
+ const scheduleLastWidgetRerender = () => {
115
+ if (widgetRerenderTimer) return;
116
+ widgetRerenderTimer = setTimeout(() => {
117
+ widgetRerenderTimer = undefined;
118
+ rerenderLastWidget();
119
+ }, EVENT_REFRESH_DEBOUNCE_MS);
120
+ widgetRerenderTimer.unref?.();
94
121
  };
95
122
  const requestLastWidgetRender = () => {
96
- const ctx = state.lastUiContext;
97
- if (!ctx || state.widgetsSuspended || options.widgetEnabled === false) return;
98
- try {
99
- if (ctx.hasUI) (ctx.ui as { requestRender?: () => void }).requestRender?.();
100
- } catch (error) {
101
- if (error instanceof Error && error.message.includes("extension ctx is stale")) {
102
- state.lastUiContext = null;
103
- return;
104
- }
105
- throw error;
106
- }
123
+ if (options.widgetEnabled === false) return;
124
+ withLastUiContext((ctx) => {
125
+ if (state.widgetsSuspended) return;
126
+ const requestRender = (ctx.ui as { requestRender?: () => void }).requestRender;
127
+ if (requestRender) requestRender.call(ctx.ui);
128
+ else renderWidget(ctx, Array.from(state.asyncJobs.values()));
129
+ });
107
130
  };
108
131
  const refreshWidget = (ctx: ExtensionContext) => rerenderWidget(ctx);
109
132
  const restoredControlEventCursor = (asyncDir: string) => {
@@ -152,6 +175,9 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
152
175
  currentStep: run.currentStep,
153
176
  chainStepCount: run.chainStepCount,
154
177
  parallelGroups: groups,
178
+ hostSteps: run.hostSteps,
179
+ ...(run.mode === "workflow" && run.workflowGraph ? { workflowGraph: run.workflowGraph } : {}),
180
+ preflight: run.preflight,
155
181
  steps: visibleSteps,
156
182
  stepsTotal: visibleSteps.length,
157
183
  runningSteps: visibleSteps.filter((step) => step.status === "running").length,
@@ -177,6 +203,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
177
203
  parentWorkflowRunId: run.parentWorkflowRunId,
178
204
  workflowKey: run.workflowKey,
179
205
  workflow: run.workflow,
206
+ workflowChildren: parseWorkflowChildSummary(run.workflowChildren),
180
207
  };
181
208
  };
182
209
  const cancelCleanup = (asyncId: string) => {
@@ -227,6 +254,28 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
227
254
  return;
228
255
  }
229
256
  if (!parsed || typeof parsed !== "object") return;
257
+ if ((parsed as { type?: unknown }).type === "subagent.child-status") {
258
+ const event = parsed as Partial<SubagentChildStatusEvent>;
259
+ if (event.version !== 1 || typeof event.runId !== "string" || typeof event.childId !== "string" || (event.status !== "stopping" && event.status !== "stopped") || typeof event.ts !== "number") return;
260
+ pi.events.emit(SUBAGENT_CHILD_STATUS_EVENT, {
261
+ type: "subagent.child-status",
262
+ version: 1,
263
+ runId: event.runId,
264
+ childId: event.childId,
265
+ status: event.status,
266
+ ts: event.ts,
267
+ ...(typeof event.reason === "string" ? { reason: event.reason } : {}),
268
+ source: event.source === "rpc" ? "rpc" : "async",
269
+ asyncDir: job.asyncDir,
270
+ ...(typeof event.stepIndex === "number" ? { stepIndex: event.stepIndex } : {}),
271
+ ...(typeof event.agent === "string" ? { agent: event.agent } : {}),
272
+ ...(typeof event.childRunId === "string" ? { childRunId: event.childRunId } : {}),
273
+ ...(typeof event.workflowKey === "string" ? { workflowKey: event.workflowKey } : {}),
274
+ ...(typeof event.phase === "string" ? { phase: event.phase } : {}),
275
+ ...(typeof event.label === "string" ? { label: event.label } : {}),
276
+ } satisfies SubagentChildStatusEvent);
277
+ return;
278
+ }
230
279
  if ((parsed as { type?: unknown }).type === "subagent.steering.notice") {
231
280
  const notice = parsed as Partial<SteeringNotice>;
232
281
  if (typeof notice.requestId !== "string" || typeof notice.runId !== "string" || (notice.state !== "failed" && notice.state !== "partial" && notice.state !== "recovered") || typeof notice.message !== "string") return;
@@ -246,6 +295,15 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
246
295
  if ((parsed as { type?: unknown }).type !== "subagent.control") return;
247
296
  const record = parsed as { event?: ControlEvent; channels?: string[]; childIntercomTarget?: string; noticeText?: string; intercom?: { to?: string; message?: string } };
248
297
  if (!record.event || !Array.isArray(record.channels)) return;
298
+ if (record.event.type === "needs_attention" && record.event.reason === "supervisor_request" && options.supervisorRequestState) {
299
+ let requestState: "pending" | "resolved" | "unknown" = "unknown";
300
+ try {
301
+ requestState = options.supervisorRequestState(record.event);
302
+ } catch (error) {
303
+ console.error(`Failed to resolve supervisor request state for async control event in '${job.asyncDir}':`, error);
304
+ }
305
+ if (requestState === "resolved") return;
306
+ }
249
307
  const payload = {
250
308
  event: record.event,
251
309
  source: "async" as const,
@@ -321,10 +379,11 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
321
379
  if (timer) clearTimeout(timer);
322
380
  refreshTimers.delete(asyncId);
323
381
  runningJobIds.delete(asyncId);
382
+ externalJobBridgeRuns.delete(asyncId);
324
383
  };
325
384
 
326
385
  const refreshJob = (job: AsyncJobState): boolean => {
327
- const widgetExpanded = state.lastUiContext?.hasUI ? state.lastUiContext.ui.getToolsExpanded?.() ?? false : false;
386
+ const widgetExpanded = withLastUiContext((ctx) => ctx.ui.getToolsExpanded?.() ?? false) ?? false;
328
387
  const widgetStateBefore = widgetRenderKey(job, widgetExpanded);
329
388
  let nestedRefreshFailed = false;
330
389
  const refreshNestedProjection = () => {
@@ -335,9 +394,15 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
335
394
  console.error(`Failed to refresh nested async descendants for '${job.asyncDir}':`, error);
336
395
  }
337
396
  };
397
+ let bridgeSweepAttempted = false;
338
398
  try {
339
399
  emitNewControlEvents(job);
340
- serviceExternalJobBridgeRequests(job.asyncDir);
400
+ const bridgeAlreadyRequired = externalJobBridgeRuns.has(job.asyncId) || externalJobBridgeEligibility(job.steps) === "required";
401
+ if (bridgeAlreadyRequired) {
402
+ externalJobBridgeRuns.add(job.asyncId);
403
+ bridgeSweepAttempted = true;
404
+ serviceExternalJobBridgeRequests(job.asyncDir);
405
+ }
341
406
  try {
342
407
  if (job.nestedRoute) reconcileNestedAsyncDescendants(job.nestedRoute, { resultsDir, kill: options.kill, now: options.now });
343
408
  } catch (error) {
@@ -363,6 +428,15 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
363
428
  },
364
429
  });
365
430
  const status = reconciliation.status ?? readStatus(job.asyncDir);
431
+ if (!bridgeAlreadyRequired) {
432
+ const bridgeEligibility = externalJobBridgeEligibility(status?.steps);
433
+ if (bridgeEligibility === "required") externalJobBridgeRuns.add(job.asyncId);
434
+ // Missing or ambiguous status retains the legacy sweep for recovery races.
435
+ if (bridgeEligibility !== "not-required") {
436
+ bridgeSweepAttempted = true;
437
+ serviceExternalJobBridgeRequests(job.asyncDir);
438
+ }
439
+ }
366
440
  if (status) {
367
441
  const previousStatus = job.status;
368
442
  job.status = status.state;
@@ -381,7 +455,13 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
381
455
  job.mode = status.mode;
382
456
  job.parentWorkflowRunId = status.parentWorkflowRunId ?? job.parentWorkflowRunId;
383
457
  job.workflowKey = status.workflowKey ?? job.workflowKey;
458
+ job.lane = status.lane ?? job.lane;
384
459
  job.workflow = status.workflow ?? job.workflow;
460
+ if (status.mode === "workflow") job.workflowGraph = status.workflowGraph ?? job.workflowGraph;
461
+ job.hostSteps = validHostStepNodes(status.workflowGraph);
462
+ const workflowChildren = parseWorkflowChildSummary(status.workflowChildren);
463
+ if (workflowChildren && workflowChildren.workflowRunId !== status.runId) throw new Error("workflowChildren.workflowRunId does not match async status runId.");
464
+ job.workflowChildren = workflowChildren ?? job.workflowChildren;
385
465
  job.currentStep = status.currentStep ?? job.currentStep;
386
466
  job.chainStepCount = status.chainStepCount ?? job.chainStepCount;
387
467
  job.startedAt = status.startedAt ?? job.startedAt;
@@ -431,6 +511,14 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
431
511
  runningJobIds.add(job.asyncId);
432
512
  }
433
513
  } catch (error) {
514
+ if (!bridgeSweepAttempted) {
515
+ try {
516
+ bridgeSweepAttempted = true;
517
+ serviceExternalJobBridgeRequests(job.asyncDir);
518
+ } catch (bridgeError) {
519
+ console.error(`Failed to service external job bridge for '${job.asyncDir}':`, bridgeError);
520
+ }
521
+ }
434
522
  if (job.status !== "failed") {
435
523
  console.error(`Failed to read async status for '${job.asyncDir}':`, error);
436
524
  job.status = "failed";
@@ -448,7 +536,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
448
536
  const timer = setTimeout(() => {
449
537
  refreshTimers.delete(asyncId);
450
538
  const job = state.asyncJobs.get(asyncId);
451
- if (job && refreshJob(job)) rerenderLastWidget();
539
+ if (job && refreshJob(job)) scheduleLastWidgetRerender();
452
540
  }, delayMs);
453
541
  timer.unref?.();
454
542
  refreshTimers.set(asyncId, timer);
@@ -556,8 +644,11 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
556
644
  }
557
645
  if (widgetChanged) rerenderLastWidget();
558
646
  }
559
- if (runningJobIds.size > 0) requestLastWidgetRender();
560
- }, Math.min(POLL_INTERVAL_MS, livenessIntervalMs));
647
+ if (runningJobIds.size > 0 && now >= nextWidgetAnimationAt) {
648
+ nextWidgetAnimationAt = now + WIDGET_ANIMATION_INTERVAL_MS;
649
+ requestLastWidgetRender();
650
+ }
651
+ }, Math.min(WIDGET_ANIMATION_INTERVAL_MS, livenessIntervalMs));
561
652
  state.poller.unref?.();
562
653
  };
563
654
 
@@ -576,6 +667,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
576
667
  : rawAgents;
577
668
  const sessionRoot = state.liveAsyncSessionRoots?.get(info.id);
578
669
  state.liveAsyncSessionRoots?.delete(info.id);
670
+ externalJobBridgeRuns.delete(info.id);
579
671
  state.asyncJobs.set(info.id, {
580
672
  asyncId: info.id,
581
673
  asyncDir,
@@ -601,6 +693,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
601
693
  turnBudget: info.turnBudget,
602
694
  parentWorkflowRunId: info.parentWorkflowRunId,
603
695
  workflowKey: info.workflowKey,
696
+ ...(info.mode === "workflow" && info.workflowGraph ? { workflowGraph: info.workflowGraph } : {}),
604
697
  controlEventCursor: 0,
605
698
  });
606
699
  const job = state.asyncJobs.get(info.id)!;
@@ -648,11 +741,15 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
648
741
  for (const asyncId of jobWatchers.keys()) closeJobWatcher(asyncId);
649
742
  for (const timer of refreshTimers.values()) clearTimeout(timer);
650
743
  refreshTimers.clear();
744
+ if (widgetRerenderTimer) clearTimeout(widgetRerenderTimer);
745
+ widgetRerenderTimer = undefined;
651
746
  runningJobIds.clear();
747
+ externalJobBridgeRuns.clear();
652
748
  };
653
749
 
654
750
  const resetJobs = (ctx?: ExtensionContext) => {
655
751
  dispose();
752
+ state.statusProjectionSessionId = null;
656
753
  for (const timer of state.cleanupTimers.values()) clearTimeout(timer);
657
754
  state.cleanupTimers.clear();
658
755
  state.asyncJobs.clear();
@@ -669,6 +766,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
669
766
 
670
767
  const restoreActiveJobs = (ctx?: ExtensionContext) => {
671
768
  if (ctx?.hasUI) state.lastUiContext = ctx;
769
+ state.statusProjectionSessionId = null;
672
770
  if (!state.currentSessionId) return;
673
771
  let runs: AsyncRunSummary[];
674
772
  try {
@@ -684,6 +782,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
684
782
  rememberFleetJob(state, job);
685
783
  watchJob(job);
686
784
  }
785
+ state.statusProjectionSessionId = state.currentSessionId;
687
786
  if (runs.length === 0) return;
688
787
  ensurePoller();
689
788
  rerenderLastWidget();
@@ -1,16 +1,20 @@
1
1
  import * as fs from "node:fs";
2
2
  import * as path from "node:path";
3
- import { DIRS, type AcceptanceInput, type AsyncStatus, type ResolvedTurnBudget, type SteeringRecoveryDescriptor, type SubagentRunMode } from "../../shared/types.ts";
3
+ import { DIRS, type AcceptanceInput, type AsyncStatus, type SteeringRecoveryDescriptor, type SubagentRunMode } from "../../shared/types.ts";
4
4
  import type { AgentConfig } from "../../agents/agents.ts";
5
+ import { normalizeExtensionBindings } from "../shared/extension-bindings.ts";
6
+ import { normalizeWorkflowLaneMetadata } from "../shared/lane-metadata.ts";
5
7
  import { validateAcceptanceInput } from "../shared/acceptance.ts";
6
8
  import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
7
9
  import { intersectSubagentCapabilityCeilings, parseSubagentCapabilityCeiling, type ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
8
10
  import { validateRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.ts";
9
- import { resolveTurnBudgetConfig } from "../shared/turn-budget.ts";
10
11
  import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
11
12
  import { resultFilePath, resultPayloadPathForIndexedRun } from "./result-files.ts";
12
13
  import { canScanAsyncRunPrefix, MIN_SAFE_ASYNC_RUN_PREFIX_LENGTH } from "./run-id-query.ts";
13
14
  import { parallelHandoffPath, resolveRetainedWorktreeCwd } from "../shared/parallel-handoff.ts";
15
+ import { normalizeWorktreeBaseRef } from "../shared/worktree.ts";
16
+ import { intersectThinkingCeilings, parseThinkingLevel, type ThinkingLevel } from "../../shared/thinking-ceiling.ts";
17
+ import { assertWorkflowGraphHostSteps } from "../shared/host-step-status.ts";
14
18
 
15
19
  export interface AsyncResumeParams {
16
20
  id?: string;
@@ -38,14 +42,21 @@ export type AsyncResumeTarget = {
38
42
  state: AsyncStatus["state"];
39
43
  mode?: SubagentRunMode;
40
44
  agent: string;
45
+ /** Human-readable display name for the child session, when derived at launch. */
46
+ sessionName?: string;
41
47
  index: number;
42
48
  cwd?: string;
49
+ /** True when cwd is the retained managed worktree recorded by the handoff. */
50
+ managedWorktree?: boolean;
43
51
  sessionFile?: string;
44
52
  model?: string;
45
53
  thinking?: string;
54
+ thinkingCeiling?: ThinkingLevel;
46
55
  recoveryDescriptor?: SteeringRecoveryDescriptor;
47
56
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
48
57
  launchContractDigest?: string;
58
+ runner?: NonNullable<AsyncStatus["steps"]>[number]["runner"];
59
+ externalJob?: NonNullable<AsyncStatus["steps"]>[number]["externalJob"];
49
60
  };
50
61
 
51
62
  interface AsyncResultFile {
@@ -58,11 +69,12 @@ interface AsyncResultFile {
58
69
  cwd?: string;
59
70
  sessionId?: string;
60
71
  sessionFile?: string;
72
+ sessionName?: string;
61
73
  model?: string;
62
74
  thinking?: string;
63
75
  launchContractDigest?: string;
64
76
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
65
- results?: Array<{ agent?: string; success?: boolean; sessionFile?: string; intercomTarget?: string; model?: string; thinking?: string; launchContractDigest?: string; capabilityCeiling?: ResolvedSubagentCapabilityCeiling }>;
77
+ results?: Array<{ agent?: string; sessionName?: string; success?: boolean; sessionFile?: string; intercomTarget?: string; model?: string; thinking?: string; launchContractDigest?: string; capabilityCeiling?: ResolvedSubagentCapabilityCeiling }>;
66
78
  }
67
79
 
68
80
  export interface AsyncRunLocation {
@@ -99,6 +111,7 @@ function validateResultFile(value: unknown, resultPath: string): AsyncResultFile
99
111
  const child = ensureObject(entry, `${resultPath} results[${index}]`);
100
112
  const agent = validateOptionalString(child, "agent", resultPath, `results[${index}].agent`);
101
113
  const sessionFile = validateOptionalString(child, "sessionFile", resultPath, `results[${index}].sessionFile`);
114
+ const sessionName = validateOptionalString(child, "sessionName", resultPath, `results[${index}].sessionName`);
102
115
  const intercomTarget = validateOptionalString(child, "intercomTarget", resultPath, `results[${index}].intercomTarget`);
103
116
  const model = validateOptionalString(child, "model", resultPath, `results[${index}].model`);
104
117
  const thinking = validateOptionalString(child, "thinking", resultPath, `results[${index}].thinking`);
@@ -106,7 +119,7 @@ function validateResultFile(value: unknown, resultPath: string): AsyncResultFile
106
119
  const capabilityCeiling = child.capabilityCeiling === undefined ? undefined : parseSubagentCapabilityCeiling(child.capabilityCeiling, `async result file '${resultPath}' results[${index}].capabilityCeiling`);
107
120
  const success = child.success;
108
121
  if (success !== undefined && typeof success !== "boolean") throw new Error(`Invalid async result file '${resultPath}': results[${index}].success must be a boolean.`);
109
- return { agent, sessionFile, intercomTarget, model, thinking, launchContractDigest, ...(capabilityCeiling ? { capabilityCeiling } : {}), ...(typeof success === "boolean" ? { success } : {}) };
122
+ return { agent, sessionName, sessionFile, intercomTarget, model, thinking, launchContractDigest, ...(capabilityCeiling ? { capabilityCeiling } : {}), ...(typeof success === "boolean" ? { success } : {}) };
110
123
  });
111
124
  }
112
125
  const success = data.success;
@@ -243,7 +256,7 @@ export function resolveAsyncRunLocation(params: AsyncResumeParams, asyncDirRoot:
243
256
  }
244
257
 
245
258
  function resultState(result: AsyncResultFile): AsyncStatus["state"] {
246
- if (result.state === "complete" || result.state === "failed" || result.state === "paused" || result.state === "stopped" || result.state === "running" || result.state === "queued") {
259
+ if (result.state === "complete" || result.state === "failed" || result.state === "partial" || result.state === "paused" || result.state === "stopped" || result.state === "running" || result.state === "queued") {
247
260
  return result.state;
248
261
  }
249
262
  return result.success ? "complete" : "failed";
@@ -252,6 +265,7 @@ function resultState(result: AsyncResultFile): AsyncStatus["state"] {
252
265
  function validateStatusForResume(status: AsyncStatus | null, source: string): void {
253
266
  if (!status) return;
254
267
  if (typeof status.runId !== "string") throw new Error(`Invalid async status '${source}': runId must be a string.`);
268
+ assertWorkflowGraphHostSteps(status.workflowGraph, source, status.runId);
255
269
  if (status.sessionId !== undefined && typeof status.sessionId !== "string") throw new Error(`Invalid async status '${source}': sessionId must be a string.`);
256
270
  if (status.cwd !== undefined && typeof status.cwd !== "string") throw new Error(`Invalid async status '${source}': cwd must be a string.`);
257
271
  if (status.sessionFile !== undefined && typeof status.sessionFile !== "string") throw new Error(`Invalid async status '${source}': sessionFile must be a string.`);
@@ -263,8 +277,10 @@ function validateStatusForResume(status: AsyncStatus | null, source: string): vo
263
277
  const stepRecord = step as Record<string, unknown>;
264
278
  if (typeof stepRecord.agent !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].agent must be a string.`);
265
279
  if (stepRecord.sessionFile !== undefined && typeof stepRecord.sessionFile !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].sessionFile must be a string.`);
280
+ if (stepRecord.sessionName !== undefined && typeof stepRecord.sessionName !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].sessionName must be a string.`);
266
281
  if (stepRecord.model !== undefined && typeof stepRecord.model !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].model must be a string.`);
267
282
  if (stepRecord.thinking !== undefined && typeof stepRecord.thinking !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].thinking must be a string.`);
283
+ if (stepRecord.thinkingCeiling !== undefined) stepRecord.thinkingCeiling = parseThinkingLevel(stepRecord.thinkingCeiling, `async status '${source}' steps[${index}].thinkingCeiling`);
268
284
  if (stepRecord.launchContractDigest !== undefined && typeof stepRecord.launchContractDigest !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].launchContractDigest must be a string.`);
269
285
  if (stepRecord.capabilityCeiling !== undefined) stepRecord.capabilityCeiling = parseSubagentCapabilityCeiling(stepRecord.capabilityCeiling, `async status '${source}' steps[${index}].capabilityCeiling`);
270
286
  });
@@ -277,23 +293,6 @@ function normalizeRecoveryAcceptance(value: unknown, descriptorPath: string): Ac
277
293
  return value as AcceptanceInput;
278
294
  }
279
295
 
280
- function normalizeRecoveryTurnBudget(value: unknown, descriptorPath: string): ResolvedTurnBudget {
281
- if (value && typeof value === "object" && !Array.isArray(value)) {
282
- const {
283
- outcome: _outcome,
284
- turnCount: _turnCount,
285
- wrapUpRequestedAtTurn: _wrapUpRequestedAtTurn,
286
- terminationDeferredAtTurn: _terminationDeferredAtTurn,
287
- exceededAtTurn: _exceededAtTurn,
288
- ...publicTurnBudget
289
- } = value as Record<string, unknown>;
290
- value = publicTurnBudget;
291
- }
292
- const result = resolveTurnBudgetConfig(value, "recoveryDescriptor.initialTurnBudget");
293
- if (result.error || !result.turnBudget) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${result.error ?? "recoveryDescriptor.initialTurnBudget is invalid."}`);
294
- return result.turnBudget;
295
- }
296
-
297
296
  export function asyncReviveRequiresRecoveryDescriptor(target: Pick<AsyncResumeTarget, "recoveryDescriptor" | "mode" | "sessionFile">): boolean {
298
297
  if (target.recoveryDescriptor) return false;
299
298
  return !(target.mode === "workflow" && Boolean(target.sessionFile));
@@ -318,11 +317,12 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
318
317
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': expected an object.`);
319
318
  const parsed = value as Record<string, unknown>;
320
319
  const allowedFields = new Set([
321
- "version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sessionFile", "cwd", "model", "modelOverrideFromParent", "fallbackModels", "thinking", "tools", "extensions",
322
- "subagentOnlyExtensions", "mcpDirectTools", "systemPrompt", "systemPromptMode", "inheritProjectContext", "inheritSkills", "skills",
320
+ "version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sessionFile", "cwd", "model", "modelProvider", "modelOverrideFromParent", "modelOrigin", "fallbackModels", "thinking", "thinkingCeiling", "tools", "allowNestedSubagents", "extensions",
321
+ "subagentOnlyExtensions", "mcpDirectTools", "excludeTools", "mutationTools", "systemPrompt", "systemPromptMode", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills",
323
322
  "skillPath", "agentFilePath", "completionGuard", "memory", "outputPath", "outputMode", "structuredOutputSchema", "acceptance", "sessionDir", "artifactConfig",
324
323
  "artifactsDir", "maxOutput", "controlConfig", "context", "intercomBridge", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
325
- "launchResolvedExtensions", "runFanoutBudget",
324
+ "launchResolvedExtensions", "runFanoutBudget", "lane", "baseRef",
325
+ "extensionBindings",
326
326
  ]);
327
327
  for (const field of Object.keys(parsed)) {
328
328
  if (!allowedFields.has(field)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': unknown field '${field}'.`);
@@ -338,6 +338,9 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
338
338
  throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${error instanceof Error ? error.message : String(error)}`);
339
339
  }
340
340
  if (parsed.capabilityCeiling !== undefined) parsed.capabilityCeiling = parseSubagentCapabilityCeiling(parsed.capabilityCeiling, `async recovery descriptor '${descriptorPath}' capabilityCeiling`);
341
+ if (parsed.thinkingCeiling !== undefined) parsed.thinkingCeiling = parseThinkingLevel(parsed.thinkingCeiling, `async recovery descriptor '${descriptorPath}' thinkingCeiling`);
342
+ if (parsed.extensionBindings !== undefined) parsed.extensionBindings = normalizeExtensionBindings(parsed.extensionBindings)!.value;
343
+ if (parsed.lane !== undefined) parsed.lane = normalizeWorkflowLaneMetadata(parsed.lane, `Invalid async recovery descriptor '${descriptorPath}': lane`);
341
344
  if (parsed.agentContract !== undefined) {
342
345
  if (!parsed.agentContract || typeof parsed.agentContract !== "object" || Array.isArray(parsed.agentContract)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': agentContract must be an object.`);
343
346
  const contract = parsed.agentContract as Record<string, unknown>;
@@ -347,18 +350,31 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
347
350
  if (parsed.outputMode !== "inline" && parsed.outputMode !== "file-only") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': outputMode is invalid.`);
348
351
  if (parsed.context !== undefined && parsed.context !== "fresh" && parsed.context !== "fork") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': context is invalid.`);
349
352
  if (parsed.modelOverrideFromParent !== undefined && typeof parsed.modelOverrideFromParent !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': modelOverrideFromParent must be a boolean.`);
353
+ if (parsed.modelOrigin !== undefined && parsed.modelOrigin !== "explicit" && parsed.modelOrigin !== "inherited" && parsed.modelOrigin !== "configured") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': modelOrigin must be 'explicit', 'inherited', or 'configured'.`);
354
+ if (parsed.modelOrigin === undefined && parsed.model !== undefined) parsed.modelOrigin = parsed.modelOverrideFromParent ? "inherited" : "configured";
350
355
  for (const field of ["inheritProjectContext", "inheritSkills", "share"] as const) {
351
356
  if (typeof parsed[field] !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a boolean.`);
352
357
  }
358
+ if (parsed.inheritGlobalContext === undefined) parsed.inheritGlobalContext = parsed.inheritProjectContext;
359
+ else if (typeof parsed.inheritGlobalContext !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': inheritGlobalContext must be a boolean.`);
360
+ if (parsed.allowNestedSubagents !== undefined && typeof parsed.allowNestedSubagents !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': allowNestedSubagents must be a boolean.`);
353
361
  if (!Number.isInteger(parsed.maxSubagentDepth) || (parsed.maxSubagentDepth as number) < 0) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': maxSubagentDepth must be a non-negative integer.`);
354
- for (const field of ["fallbackModels", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "skills", "skillPath"] as const) {
362
+ for (const field of ["fallbackModels", "tools", "excludeTools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "skills", "skillPath"] as const) {
355
363
  const item = parsed[field];
356
364
  if (item !== undefined && (!Array.isArray(item) || item.some((entry) => typeof entry !== "string" || !entry.trim()))) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must contain non-empty strings.`);
357
365
  }
358
366
  if (parsed.systemPrompt !== undefined && typeof parsed.systemPrompt !== "string") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': systemPrompt must be a string.`);
359
- for (const field of ["launchContractDigest", "sessionFile", "model", "thinking", "agentFilePath", "outputPath", "sessionDir", "artifactsDir"] as const) {
367
+ for (const field of ["launchContractDigest", "sessionFile", "model", "modelProvider", "thinking", "agentFilePath", "outputPath", "sessionDir", "artifactsDir"] as const) {
360
368
  if (parsed[field] !== undefined && (typeof parsed[field] !== "string" || !(parsed[field] as string).trim())) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a non-empty string.`);
361
369
  }
370
+ if (parsed.baseRef !== undefined) {
371
+ if (typeof parsed.baseRef !== "string") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': baseRef must be a string.`);
372
+ try {
373
+ parsed.baseRef = normalizeWorktreeBaseRef(parsed.baseRef);
374
+ } catch (error) {
375
+ throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${error instanceof Error ? error.message : String(error)}`);
376
+ }
377
+ }
362
378
  if (parsed.completionGuard !== undefined && typeof parsed.completionGuard !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': completionGuard must be a boolean.`);
363
379
  if (parsed.structuredOutputSchema !== undefined && (!parsed.structuredOutputSchema || typeof parsed.structuredOutputSchema !== "object" || Array.isArray(parsed.structuredOutputSchema))) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': structuredOutputSchema must be an object.`);
364
380
  if (parsed.memory !== undefined) {
@@ -368,7 +384,9 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
368
384
  }
369
385
  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.`);
370
386
  if (parsed.initialTurnBudget !== undefined) {
371
- parsed.initialTurnBudget = normalizeRecoveryTurnBudget(parsed.initialTurnBudget, descriptorPath);
387
+ // Older descriptors may contain the removed turn-budget setting. Accept it
388
+ // for recovery compatibility, but do not restore or enforce it.
389
+ delete parsed.initialTurnBudget;
372
390
  }
373
391
  if (parsed.initialToolBudget !== undefined) {
374
392
  const result = validateToolBudgetConfig(parsed.initialToolBudget, "recoveryDescriptor.initialToolBudget");
@@ -481,13 +499,17 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
481
499
  state,
482
500
  ...(mode ? { mode } : {}),
483
501
  agent: selectedStep.agent,
502
+ ...(selectedStep.sessionName ?? result?.results?.[requestedIndex]?.sessionName ? { sessionName: selectedStep.sessionName ?? result?.results?.[requestedIndex]?.sessionName } : {}),
484
503
  index: requestedIndex,
485
504
  cwd: status?.cwd ?? result?.cwd,
486
505
  sessionFile: selectedStep.sessionFile ?? status?.sessionFile ?? result?.sessionFile,
487
506
  model: selectedStep.model,
488
507
  thinking: selectedStep.thinking,
489
508
  launchContractDigest: selectedStep.launchContractDigest ?? result?.results?.[requestedIndex]?.launchContractDigest ?? result?.launchContractDigest ?? recoveryDescriptor?.launchContractDigest,
509
+ ...(selectedStep.runner ? { runner: selectedStep.runner } : {}),
510
+ ...(selectedStep.externalJob ? { externalJob: selectedStep.externalJob } : {}),
490
511
  ...(capabilityCeiling ? { capabilityCeiling } : {}),
512
+ ...(selectedStep.thinkingCeiling ? { thinkingCeiling: selectedStep.thinkingCeiling } : {}),
491
513
  ...(recoveryDescriptor ? { recoveryDescriptor } : {}),
492
514
  };
493
515
  }
@@ -509,13 +531,17 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
509
531
  state,
510
532
  ...(mode ? { mode } : {}),
511
533
  agent: selected.step.agent,
534
+ ...(selected.step.sessionName ?? result?.results?.[selected.index]?.sessionName ? { sessionName: selected.step.sessionName ?? result?.results?.[selected.index]?.sessionName } : {}),
512
535
  index: selected.index,
513
536
  cwd: status?.cwd ?? result?.cwd,
514
537
  sessionFile: selected.step.sessionFile ?? status?.sessionFile ?? result?.sessionFile,
515
538
  model: selected.step.model,
516
539
  thinking: selected.step.thinking,
517
540
  launchContractDigest: selected.step.launchContractDigest ?? result?.results?.[selected.index]?.launchContractDigest ?? result?.launchContractDigest ?? recoveryDescriptor?.launchContractDigest,
541
+ ...(selected.step.runner ? { runner: selected.step.runner } : {}),
542
+ ...(selected.step.externalJob ? { externalJob: selected.step.externalJob } : {}),
518
543
  ...(capabilityCeiling ? { capabilityCeiling } : {}),
544
+ ...(selected.step.thinkingCeiling ? { thinkingCeiling: selected.step.thinkingCeiling } : {}),
519
545
  ...(recoveryDescriptor ? { recoveryDescriptor } : {}),
520
546
  };
521
547
  }
@@ -537,6 +563,7 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
537
563
  const resolvedSessionFile = sessionFile ? validateResumeSessionFile(runId, sessionFile) : undefined;
538
564
  const stepModel = statusSteps[index]?.model ?? resultSteps[index]?.model ?? (stepCount === 1 ? result?.model : undefined);
539
565
  const stepThinking = statusSteps[index]?.thinking ?? resultSteps[index]?.thinking ?? (stepCount === 1 ? result?.thinking : undefined);
566
+ const thinkingCeiling = statusSteps[index]?.thinkingCeiling ?? (stepCount === 1 ? recoveryDescriptor?.thinkingCeiling : undefined);
540
567
  const capabilityCeiling = intersectSubagentCapabilityCeilings(status?.capabilityCeiling, statusSteps[index]?.capabilityCeiling, result?.capabilityCeiling, resultSteps[index]?.capabilityCeiling);
541
568
  const managedWorktreeCwd = location.asyncDir
542
569
  ? resolveRetainedWorktreeCwd(parallelHandoffPath(location.asyncDir), runId, index)
@@ -550,13 +577,18 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
550
577
  state,
551
578
  ...(mode ? { mode } : {}),
552
579
  agent,
580
+ ...(statusSteps[index]?.sessionName ?? resultSteps[index]?.sessionName ? { sessionName: statusSteps[index]?.sessionName ?? resultSteps[index]?.sessionName } : {}),
553
581
  index,
554
582
  ...(resumeCwd ? { cwd: resumeCwd } : {}),
583
+ ...(managedWorktreeCwd ? { managedWorktree: true } : {}),
555
584
  ...(resolvedSessionFile ? { sessionFile: resolvedSessionFile } : {}),
556
585
  ...(stepModel ? { model: stepModel } : {}),
557
586
  ...(stepThinking ? { thinking: stepThinking } : {}),
558
587
  launchContractDigest: statusSteps[index]?.launchContractDigest ?? resultSteps[index]?.launchContractDigest ?? result?.launchContractDigest ?? recoveryDescriptor?.launchContractDigest,
588
+ ...(statusSteps[index]?.runner ? { runner: statusSteps[index]!.runner } : {}),
589
+ ...(statusSteps[index]?.externalJob ? { externalJob: statusSteps[index]!.externalJob } : {}),
559
590
  ...(capabilityCeiling ? { capabilityCeiling } : {}),
591
+ ...(thinkingCeiling ? { thinkingCeiling } : {}),
560
592
  ...(recoveryDescriptor ? { recoveryDescriptor } : {}),
561
593
  };
562
594
  }
@@ -565,15 +597,21 @@ export function applySteeringRecoveryAgentConfig(agentConfig: AgentConfig, descr
565
597
  return {
566
598
  ...agentConfig,
567
599
  model: descriptor.model,
600
+ modelProvider: descriptor.modelProvider,
568
601
  fallbackModels: descriptor.fallbackModels ? [...descriptor.fallbackModels] : undefined,
569
602
  thinking: descriptor.thinking,
603
+ maxThinking: intersectThinkingCeilings(descriptor.thinkingCeiling, agentConfig.maxThinking),
570
604
  tools: descriptor.tools ? [...descriptor.tools] : undefined,
605
+ excludeTools: descriptor.excludeTools ? [...descriptor.excludeTools] : undefined,
606
+ allowNestedSubagents: descriptor.allowNestedSubagents,
571
607
  extensions: descriptor.extensions ? [...descriptor.extensions] : undefined,
572
608
  subagentOnlyExtensions: descriptor.subagentOnlyExtensions ? [...descriptor.subagentOnlyExtensions] : undefined,
573
609
  mcpDirectTools: descriptor.mcpDirectTools ? [...descriptor.mcpDirectTools] : undefined,
610
+ mutationTools: descriptor.mutationTools ? [...descriptor.mutationTools] : undefined,
574
611
  systemPrompt: descriptor.systemPrompt ?? agentConfig.systemPrompt,
575
612
  systemPromptMode: descriptor.systemPromptMode,
576
613
  inheritProjectContext: descriptor.inheritProjectContext,
614
+ inheritGlobalContext: descriptor.inheritGlobalContext,
577
615
  inheritSkills: descriptor.inheritSkills,
578
616
  skills: descriptor.skills ? [...descriptor.skills] : undefined,
579
617
  skillPath: descriptor.skillPath ? [...descriptor.skillPath] : undefined,
@@ -594,7 +632,7 @@ export function buildRevivedAsyncTask(target: AsyncResumeTarget, message: string
594
632
  `Original agent: ${target.agent}`,
595
633
  target.sessionFile ? `Original session file: ${target.sessionFile}` : undefined,
596
634
  "",
597
- "Use the stored session context as background. Answer the orchestrator's follow-up below. Do not assume the original child process is still alive.",
635
+ "Use the stored session context as background. Answer the orchestrator's follow-up below. Do not assume the original child session is still running.",
598
636
  "",
599
637
  "Follow-up:",
600
638
  message,