@xzzpig/pi-subagents 0.14.0 → 0.15.1

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 (206) hide show
  1. package/CHANGELOG.md +239 -0
  2. package/README.md +7 -6
  3. package/agents/evidence-auditor.md +34 -0
  4. package/agents/researcher.md +23 -13
  5. package/agents/reviewer.md +3 -2
  6. package/docs/agents.md +55 -136
  7. package/docs/configuration.md +92 -14
  8. package/docs/extension-api.md +132 -74
  9. package/docs/fork-extensions.md +184 -0
  10. package/docs/missions.md +10 -2
  11. package/docs/models.md +11 -22
  12. package/docs/observability.md +63 -11
  13. package/docs/standalone-background.md +59 -0
  14. package/docs/tool-reference.md +42 -23
  15. package/docs/watchdog.md +39 -10
  16. package/docs/workflows.md +58 -19
  17. package/index.ts +5 -2
  18. package/inspector-runner.mjs +2 -2
  19. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +13 -3
  20. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +18 -6
  21. package/node_modules/@xzzpig/pi-components/src/transcript.ts +26 -6
  22. package/package.json +9 -4
  23. package/prompts/parallel-review.md +1 -1
  24. package/runner-peer-loader.mjs +24 -0
  25. package/runner-peer-preload.mjs +36 -0
  26. package/skills/pi-subagents/SKILL.md +34 -22
  27. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  28. package/skills/pi-subagents/references/execution-controls.md +27 -8
  29. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  30. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
  31. package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
  32. package/skills/pi-subagents/references/review-and-validation.md +3 -3
  33. package/src/agents/advertised-agent-prompt.ts +94 -0
  34. package/src/agents/agent-eject.ts +339 -0
  35. package/src/agents/agent-management.ts +79 -387
  36. package/src/agents/agent-serializer.ts +6 -3
  37. package/src/agents/agents.ts +198 -72
  38. package/src/agents/builtin-names.ts +1 -0
  39. package/src/agents/chain-serializer.ts +5 -0
  40. package/src/agents/runtime-agent-registry.ts +7 -6
  41. package/src/api/agent-management.ts +2 -2
  42. package/src/api/delegation.ts +4 -0
  43. package/src/api/preflight.ts +131 -86
  44. package/src/api/required-child-extensions.ts +6 -0
  45. package/src/api/shared-types.ts +3 -1
  46. package/src/api/workflow-resources.ts +6 -0
  47. package/src/extension/config.ts +14 -37
  48. package/src/extension/fanout-child.ts +68 -5
  49. package/src/extension/herdr-pi-bridge.ts +164 -0
  50. package/src/extension/index.ts +141 -51
  51. package/src/extension/public-execution.ts +7 -6
  52. package/src/extension/rpc.ts +8 -21
  53. package/src/extension/schemas.ts +86 -84
  54. package/src/extension/tool-description.ts +32 -79
  55. package/src/inspectors/actions.ts +148 -0
  56. package/src/inspectors/ghostty/actions.ts +74 -0
  57. package/src/inspectors/ghostty/plugin.ts +17 -0
  58. package/src/inspectors/herdr/actions.ts +99 -179
  59. package/src/inspectors/herdr/plugin.ts +20 -0
  60. package/src/inspectors/herdr/project-panes.ts +4 -1
  61. package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
  62. package/src/inspectors/plugins.ts +8 -0
  63. package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
  64. package/src/inspectors/types.ts +51 -0
  65. package/src/integrations/pi-web-session-liveness.ts +73 -0
  66. package/src/intercom/intercom-bridge.ts +50 -8
  67. package/src/intercom/native-supervisor-channel.ts +142 -115
  68. package/src/intercom/supervisor-ui.ts +3 -2
  69. package/src/missions/workflow-state.ts +37 -16
  70. package/src/policy/authority.ts +4 -0
  71. package/src/profiles/profiles.ts +12 -6
  72. package/src/runs/background/active-async-capacity.ts +22 -18
  73. package/src/runs/background/active-run-index.ts +17 -1
  74. package/src/runs/background/async-execution.ts +359 -176
  75. package/src/runs/background/async-job-tracker.ts +41 -7
  76. package/src/runs/background/async-resume.ts +19 -12
  77. package/src/runs/background/async-retention.ts +20 -0
  78. package/src/runs/background/async-status-snapshot.ts +10 -12
  79. package/src/runs/background/async-status.ts +38 -35
  80. package/src/runs/background/auto-drain.ts +59 -35
  81. package/src/runs/background/binary-bootstrap.ts +38 -0
  82. package/src/runs/background/chain-append.ts +1 -1
  83. package/src/runs/background/chain-root-attachment.ts +22 -33
  84. package/src/runs/background/control-channel.ts +78 -44
  85. package/src/runs/background/fleet-view.ts +30 -2
  86. package/src/runs/background/notify.ts +193 -19
  87. package/src/runs/background/owned-process-tree.ts +35 -8
  88. package/src/runs/background/process-terminal.ts +23 -23
  89. package/src/runs/background/result-files.ts +8 -4
  90. package/src/runs/background/result-watcher.ts +19 -2
  91. package/src/runs/background/retained-nested-route-tracker.ts +96 -0
  92. package/src/runs/background/run-child-session.ts +118 -41
  93. package/src/runs/background/run-status.ts +78 -5
  94. package/src/runs/background/runner-aliases.ts +22 -5
  95. package/src/runs/background/runner-child-launch.ts +93 -0
  96. package/src/runs/background/runner-child-sessions.ts +5 -4
  97. package/src/runs/background/runner-http-dispatcher.ts +119 -0
  98. package/src/runs/background/scheduled-runs.ts +51 -18
  99. package/src/runs/background/stale-run-reconciler.ts +38 -12
  100. package/src/runs/background/steering.ts +20 -2
  101. package/src/runs/background/subagent-runner.ts +770 -444
  102. package/src/runs/background/subagent-wait.ts +179 -28
  103. package/src/runs/background/wait-completions.ts +79 -27
  104. package/src/runs/background/wait-subscriptions.ts +9 -3
  105. package/src/runs/background/wait-tool.ts +5 -3
  106. package/src/runs/foreground/async-steering-action.ts +37 -7
  107. package/src/runs/foreground/async-stop-action.ts +93 -3
  108. package/src/runs/foreground/execution.ts +174 -194
  109. package/src/runs/foreground/foreground-history.ts +5 -2
  110. package/src/runs/foreground/prompt-audit.ts +12 -6
  111. package/src/runs/foreground/subagent-executor.ts +915 -411
  112. package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
  113. package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
  114. package/src/runs/shared/acceptance.ts +54 -14
  115. package/src/runs/shared/agent-contract.ts +1 -1
  116. package/src/runs/shared/async-status-projection.ts +172 -78
  117. package/src/runs/shared/capability-ceiling.ts +2 -0
  118. package/src/runs/shared/child-hooks.ts +167 -3
  119. package/src/runs/shared/child-launch-plan.ts +15 -3
  120. package/src/runs/shared/child-launch.ts +49 -85
  121. package/src/runs/shared/child-lifecycle.ts +6 -3
  122. package/src/runs/shared/child-runtime-config.ts +8 -1
  123. package/src/runs/shared/child-session.ts +130 -24
  124. package/src/runs/shared/child-tool-plan.ts +149 -112
  125. package/src/runs/shared/completion-evidence.ts +2 -2
  126. package/src/runs/shared/completion-guard.ts +6 -3
  127. package/src/runs/shared/dynamic-fanout.ts +2 -2
  128. package/src/runs/shared/effective-system-prompt.ts +33 -0
  129. package/src/runs/shared/external-cli-contract.ts +11 -1
  130. package/src/runs/shared/external-cli-preflight.ts +6 -2
  131. package/src/runs/shared/external-cli-runner.ts +9 -7
  132. package/src/runs/shared/herdr-connection.ts +134 -0
  133. package/src/runs/shared/herdr-external-adapters.ts +169 -0
  134. package/src/runs/shared/herdr-machine.ts +279 -0
  135. package/src/runs/shared/herdr-pi-protocol.ts +59 -0
  136. package/src/runs/shared/herdr-placed-run.ts +263 -0
  137. package/src/runs/shared/host-step-status.ts +11 -11
  138. package/src/runs/shared/llm-intent-arbiter.ts +40 -21
  139. package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
  140. package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
  141. package/src/runs/shared/model-scope.ts +1 -1
  142. package/src/runs/shared/nested-events.ts +27 -34
  143. package/src/runs/shared/orca-progress-tabs.ts +7 -1
  144. package/src/runs/shared/parallel-handoff.ts +57 -12
  145. package/src/runs/shared/parallel-utils.ts +10 -4
  146. package/src/runs/shared/pi-spawn.ts +10 -0
  147. package/src/runs/shared/profile-extensions.ts +134 -0
  148. package/src/runs/shared/profile-launch-env.ts +113 -0
  149. package/src/runs/shared/readonly-drain-observation.ts +42 -0
  150. package/src/runs/shared/run-fanout-budget.ts +8 -8
  151. package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
  152. package/src/runs/shared/sandbox-profile-guard.ts +34 -0
  153. package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
  154. package/src/runs/shared/task-intent.ts +46 -13
  155. package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
  156. package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
  157. package/src/runs/shared/worktree-setup-command.ts +213 -0
  158. package/src/runs/shared/worktree.ts +437 -214
  159. package/src/shared/child-cache-retention.ts +43 -0
  160. package/src/shared/fork-context.ts +15 -72
  161. package/src/shared/launch-contract.ts +70 -8
  162. package/src/shared/model-response-aliases.ts +13 -0
  163. package/src/shared/opencode-session-headers.ts +30 -0
  164. package/src/shared/permission-profile.ts +14 -0
  165. package/src/shared/pruned-fork.ts +1 -1
  166. package/src/shared/required-child-extensions.ts +81 -0
  167. package/src/shared/sandbox-profile.ts +14 -0
  168. package/src/shared/settings.ts +5 -2
  169. package/src/shared/shortcuts.ts +0 -4
  170. package/src/shared/types.ts +163 -90
  171. package/src/shared/utils.ts +10 -2
  172. package/src/shared/watch-strategy.ts +2 -0
  173. package/src/shared/workflow-child-permit.ts +18 -13
  174. package/src/slash/delegation-adapters.ts +3 -1
  175. package/src/slash/delegation-request.ts +14 -0
  176. package/src/slash/slash-commands.ts +2 -7
  177. package/src/slash/subagents-admin.ts +31 -14
  178. package/src/tui/fleet-status.ts +165 -20
  179. package/src/tui/fleet.ts +30 -19
  180. package/src/tui/render.ts +210 -50
  181. package/src/watchdog/child-status.ts +28 -28
  182. package/src/watchdog/lsp-diagnostics.ts +1 -1
  183. package/src/watchdog/model-selection.ts +21 -1
  184. package/src/watchdog/permission-arbiter.ts +5 -2
  185. package/src/watchdog/register-child.ts +10 -2
  186. package/src/watchdog/register-main.ts +39 -35
  187. package/src/watchdog/render.ts +1 -1
  188. package/src/watchdog/review.ts +122 -74
  189. package/src/watchdog/rules.ts +1 -1
  190. package/src/watchdog/runtime.ts +100 -27
  191. package/src/watchdog/scope.ts +1 -1
  192. package/src/watchdog/settings.ts +3 -0
  193. package/src/watchdog/tool-actions.ts +13 -12
  194. package/src/watchdog/turn-delta.ts +23 -0
  195. package/src/watchdog/types.ts +5 -3
  196. package/src/watchdog/warning-format.ts +1 -1
  197. package/src/workflows/chat-progress.ts +3 -3
  198. package/src/workflows/scripted-workflow.ts +349 -26
  199. package/src/workflows/workflow-checklist.ts +17 -20
  200. package/src/workflows/workflow-child-summary.ts +57 -8
  201. package/src/workflows/workflow-preflight.ts +19 -19
  202. package/src/workflows/workflow-receipt.ts +24 -6
  203. package/src/workflows/workflow-resources.ts +108 -22
  204. package/src/workflows/workflow-settlement.ts +3 -0
  205. package/src/runs/shared/model-exclusions.ts +0 -373
  206. /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
@@ -1,8 +1,15 @@
1
1
  import { spawnSync } from "node:child_process";
2
2
  import * as fs from "node:fs";
3
3
  import * as path from "node:path";
4
+ import { performance } from "node:perf_hooks";
4
5
  import { pathToFileURL } from "node:url";
5
6
  import type { Message } from "@earendil-works/pi-ai";
7
+ import { arbitrateCompletionGuardRescue, createTaskMutationArbiter } from "../shared/llm-intent-arbiter.ts";
8
+ import { installRunnerHttpDispatcher } from "./runner-http-dispatcher.ts";
9
+
10
+ const isRunnerEntrypoint = Boolean(process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href);
11
+ // Detached Node runners skip Pi's CLI dispatcher setup; install the runner's own.
12
+ if (isRunnerEntrypoint) installRunnerHttpDispatcher({ agentDir: getAgentDir(), cwd: process.cwd() });
6
13
  import { writeAtomicJson } from "../../shared/atomic-json.ts";
7
14
  import { writeAsyncResultFile, writePendingAsyncResultFile } from "./result-files.ts";
8
15
  import { createFileCoalescer } from "../../shared/file-coalescer.ts";
@@ -10,11 +17,12 @@ import { createCapacityResilientJsonWriter } from "../../shared/capacity-resilie
10
17
  import { isStorageCapacityError } from "../../shared/file-system-retry.ts";
11
18
  import { updateActiveRunIndex } from "./active-run-index.ts";
12
19
  import { createChildTranscriptWriter, type ChildTranscriptWriter } from "../../shared/child-transcript.ts";
13
- import { closeSteerInbox, consumeInterruptRequest, consumeSteerRequests, deliverInterruptRequest, deliverStopRequest, deliverTimeoutRequest, watchAsyncControlInbox, type SteerRequest, type StopRequest } from "./control-channel.ts";
20
+ import { closeSteerInbox, consumeInterruptRequest, consumeSteerRequests, consumeStopRequestPayloads, deliverInterruptRequest, deliverStopRequest, deliverTimeoutRequest, watchAsyncControlInbox, type SteerRequest, type StopRequest } from "./control-channel.ts";
14
21
  import { appendJsonl as appendRawJsonl, formatOutputArtifactContent, getArtifactPaths, writeArtifact, writeMetadata } from "../../shared/artifacts.ts";
15
22
  import { PI_CODING_AGENT_PACKAGE, resolveInstalledPiPackageRoot } from "../shared/pi-spawn.ts";
16
23
  import { preflightLaunchCwd } from "../shared/launch-cwd.ts";
17
24
  import { captureSingleOutputSnapshot, extractChildWrittenOutput, finalizeSingleOutput, formatSavedOutputReference, injectOutputPathSystemPrompt, injectSingleOutputInstruction, resolveSingleOutput, type SingleOutputSnapshot } from "../shared/single-output.ts";
25
+ import { runSetupCommand } from "../shared/worktree-setup-command.ts";
18
26
  import {
19
27
  type ActivityState,
20
28
  type ArtifactConfig,
@@ -27,10 +35,9 @@ import {
27
35
  type AsyncStatus,
28
36
  type ChainOutputMap,
29
37
  type CostSummary,
30
- type LaunchResolvedChildExtensionsV1,
31
- type RuntimeAcknowledgedChildExtensionsV1,
32
- type ModelAttempt,
33
- type PiWriterProcessInstanceExitV1,
38
+ type LaunchResolvedChildExtensions,
39
+ type RuntimeAcknowledgedChildExtensions,
40
+ type PiWriterProcessInstanceExit,
34
41
  type NestedRouteInfo,
35
42
  type NestedRunSummary,
36
43
  type ResolvedControlConfig,
@@ -46,6 +53,7 @@ import {
46
53
  type SteeringTargetStatus,
47
54
  type SubagentChildStatusEvent,
48
55
  type WorkflowLaneMetadata,
56
+ type HerdrMachineReference,
49
57
  DEFAULT_MAX_OUTPUT,
50
58
  type MaxOutputConfig,
51
59
  SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
@@ -72,10 +80,12 @@ import {
72
80
  DEFAULT_GLOBAL_CONCURRENCY_LIMIT,
73
81
  Semaphore,
74
82
  } from "../shared/parallel-utils.ts";
75
- import { applyThinkingSuffix, deriveForkPromptCacheKey, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/child-tool-plan.ts";
76
- import { buildInProcessChildLaunch, type InheritedChildRuntime } from "../shared/child-launch.ts";
77
- import type { ChildSessionFactory } from "../shared/child-session.ts";
78
- import { runChildSession, type ChildEvent, type RunChildSessionResult, type StepSteerHandler } from "./run-child-session.ts";
83
+ import { applyThinkingSuffix, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/child-tool-plan.ts";
84
+ import type { InheritedChildRuntime } from "../shared/child-launch.ts";
85
+ import { buildRunnerChildLaunch } from "./runner-child-launch.ts";
86
+ import { normalizeExtensionBindings } from "../shared/extension-bindings.ts";
87
+ import type { ChildSessionFactory, DefaultChildSessionFactoryOptions } from "../shared/child-session.ts";
88
+ import { runChildSession, type ChildEvent, type RunChildSessionInput, type RunChildSessionResult, type SteerDelivery, type StepSteerHandler } from "./run-child-session.ts";
79
89
  import { loadRunnerChildSessionFactory } from "./runner-child-sessions.ts";
80
90
  import { SUBAGENT_CHILD_ENV } from "../shared/child-runtime-config.ts";
81
91
  import { deriveChildSessionName } from "../../shared/child-session-name.ts";
@@ -88,10 +98,10 @@ import { buildTimeoutRecoverySummary, collectTrackedMutationEvidence, snapshotTr
88
98
  import { collectDynamicResults, DynamicFanoutError, materializeDynamicParallelStep, validateDynamicCollection } from "../shared/dynamic-fanout.ts";
89
99
  import { claimRunFanoutBatch, getRunFanoutBudgetSnapshot } from "../shared/run-fanout-budget.ts";
90
100
  import { nestedSummaryFromAsyncStatus, projectNestedEvents, resolveNestedAsyncDir, writeNestedEvent } from "../shared/nested-events.ts";
91
- import { formatModelAttemptNote, formatSubagentModelVerificationError, isContextOverflow, isRetryableModelFailureAttempt, recordRetryableModelFailure } from "../shared/model-fallback.ts";
92
- import { markProcessTerminalCandidateLeaseRelease, writeProcessTerminalCandidate, type ProcessTerminalCandidate } from "./process-terminal.ts";
93
- import { createSteeringStatus, recordSteeringRequest, steeringStatus, terminalSteeringNoticeState, updateSteeringTarget } from "./steering.ts";
94
- import { PROMPT_REDACTED, detectSubagentError, extractTextFromContent, extractToolArgsPreview, formatEmptyTerminalAssistantResponseError, getFinalOutput, hasEmptyTerminalAssistantResponse, readStatus } from "../../shared/utils.ts";
101
+ import { formatSubagentModelVerificationError, isContextOverflow } from "../shared/model-resolution.ts";
102
+ import { markProcessTerminalCandidateLeaseRelease, processTerminalPath, writeProcessTerminalCandidate, type ProcessTerminalCandidate } from "./process-terminal.ts";
103
+ import { createSteeringStatus, recordSteeringRequest, steeringStatus, terminalSteeringNoticeState, unconsumedSteerReason, updateSteeringTarget } from "./steering.ts";
104
+ import { PROMPT_REDACTED, detectSubagentError, extractTextFromContent, extractToolArgsPreview, formatEmptyTerminalAssistantResponseError, getAgentDir, getFinalOutput, hasEmptyTerminalAssistantResponse, readStatus } from "../../shared/utils.ts";
95
105
  import { evaluateCompletionMutationGuard, expectsImplementationMutation, hasMutationToolCapability, validateImplementationToolContract } from "../shared/completion-guard.ts";
96
106
  import { planCompletionEvidence, projectSettlementDiagnostic } from "../shared/completion-evidence.ts";
97
107
  import { planAbortRecovery } from "../shared/abort-recovery.ts";
@@ -111,6 +121,9 @@ import type { TokenUsage } from "../../shared/types.ts";
111
121
  import {
112
122
  cleanupWorktrees,
113
123
  createWorktrees,
124
+ withWorktreeTransaction,
125
+ WorktreeSetupError,
126
+ type WorktreeSetupProgress,
114
127
  diffWorktrees,
115
128
  findWorktreeTaskCwdConflict,
116
129
  formatWorktreeDiffSummary,
@@ -118,23 +131,22 @@ import {
118
131
  WORKTREE_AGENT_CWD_PLACEHOLDER,
119
132
  type WorktreeSetup,
120
133
  } from "../shared/worktree.ts";
121
- import { findModelInfo, resolveEffectiveThinking } from "../../shared/model-info.ts";
134
+ import { findModelInfo, resolveEffectiveThinking, splitKnownThinkingSuffix } from "../../shared/model-info.ts";
122
135
  import { assertThinkingWithinCeiling } from "../../shared/thinking-ceiling.ts";
123
- import { launchBindingDigest } from "../../shared/launch-contract.ts";
136
+ import { resolveLaunchBinding } from "../../shared/launch-contract.ts";
124
137
  import { writeInitialProgressFile } from "../../shared/settings.ts";
125
138
  import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.ts";
126
139
  import { acceptanceFailureMessage, aggregateAcceptanceReport, buildSkippedAcceptanceLedger, evaluateAcceptance, formatAcceptancePrompt, resolveAcceptanceReportMode, resolveEffectiveAcceptance, stripAcceptanceReport } from "../shared/acceptance.ts";
127
- import { attachContractProjections, isAgentContractV1 } from "../shared/agent-contract.ts";
140
+ import { attachContractProjections, isAgentContract } from "../shared/agent-contract.ts";
128
141
  import { waitForImportedAsyncRoot } from "./chain-root-attachment.ts";
129
- import { normalizeExtensionBindings } from "../shared/extension-bindings.ts";
130
142
  import { appendRunnerStepsToStatus, consumeChainAppendRequests, countPendingChainAppendRequests, statusStepDescription } from "./chain-append.ts";
131
143
  import { asyncStatusChildIdentity } from "../shared/child-identity.ts";
132
- import { validateSandboxProfileName } from "../../shared/sandbox-profile.ts";
133
- import { validatePermissionProfileName } from "../../shared/permission-profile.ts";
144
+ import { validateSandboxProfileNameOptional } from "../../shared/sandbox-profile.ts";
145
+ import { validatePermissionProfileNameOptional } from "../../shared/permission-profile.ts";
134
146
  import { initialToolBudgetState, toolBudgetState } from "../shared/tool-budget.ts";
135
147
  import { toolTimeoutCallKey } from "../shared/tool-timeout.ts";
136
148
  import { usageBudgetExceededMessage, usageBudgetState } from "../shared/usage-budget.ts";
137
- import { formatParallelHandoffError, formatParallelHandoffReference, parallelHandoffPath, writeParallelHandoffGroup, writePendingParallelHandoff } from "../shared/parallel-handoff.ts";
149
+ import { formatParallelHandoffError, formatParallelHandoffReference, parallelHandoffPath, writeParallelHandoffGroup, writeWorktreeSetupHandoff } from "../shared/parallel-handoff.ts";
138
150
  import { resolveWatchdogConfig } from "../../watchdog/settings.ts";
139
151
  import { acquireSessionLease, type SessionLeaseRequest } from "../shared/session-lease.ts";
140
152
  import { buildExternalCliPrompt, runExternalCli } from "../shared/external-cli-runner.ts";
@@ -142,9 +154,10 @@ import { resolveClaudeCodeLaunch } from "../shared/claude-code-adapter.ts";
142
154
  import { resolveCodexExecLaunch } from "../shared/codex-exec-adapter.ts";
143
155
  import { resolveCursorAgentLaunch } from "../shared/cursor-agent-adapter.ts";
144
156
  import { resolveExternalCliRunnerStatus } from "../shared/external-cli-contract.ts";
157
+ import { formatHerdrMachineHint, prepareHerdrMachineExternalCliRun } from "../shared/herdr-machine.ts";
158
+ import { HerdrExternalNeedsAttentionError, createHerdrExternalAdapter, prepareInternalHerdrExternalAdapter, type HerdrExternalAdapterId, type HerdrExternalResult } from "../shared/herdr-external-adapters.ts";
145
159
  import { runExternalJob } from "../shared/external-job-runner.ts";
146
160
  import { createOrcaProgressTab, type OrcaProgressTab } from "../shared/orca-progress-tabs.ts";
147
- import { clearSandboxStartupDiagnostic, readSandboxStartupDiagnostic } from "../shared/sandbox-startup-diagnostics.ts";
148
161
  import type { ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
149
162
  import {
150
163
  acceptChildWatchdogEvent,
@@ -161,7 +174,7 @@ const INTERCOM_DETACH_RECEIPT = "Detached for intercom coordination before task
161
174
  // child host.
162
175
  process.env[SUBAGENT_CHILD_ENV] = "1";
163
176
 
164
- interface SubagentRunConfig {
177
+ export interface SubagentRunConfig {
165
178
  id: string;
166
179
  steps: RunnerStep[];
167
180
  resultPath: string;
@@ -201,6 +214,8 @@ interface SubagentRunConfig {
201
214
  deadlineAt?: number;
202
215
  /** Resolved configured hard per-tool-call timeout (ms); fast tools still have a default when undefined. */
203
216
  toolTimeoutMs?: number;
217
+ /** Steer the running steps to checkpoint and stop this many ms before `deadlineAt`; absent = no checkpoint steer. */
218
+ checkpointBeforeDeadlineMs?: number;
204
219
  toolBudget?: ResolvedToolBudget;
205
220
  usageBudget?: UsageBudgetConfig;
206
221
  revivalLease?: SessionLeaseRequest;
@@ -209,9 +224,11 @@ interface SubagentRunConfig {
209
224
  globalConcurrencyLimit?: number;
210
225
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
211
226
  runFanoutBudget?: RunFanoutBudgetDescriptor;
227
+ /** Builtin tool names the host runtime provides; used to intersect agent-declared tools. */
228
+ hostAvailableBuiltins?: readonly string[];
212
229
  launchContractDigest?: string;
213
- launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
214
- runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
230
+ launchResolvedExtensions?: LaunchResolvedChildExtensions;
231
+ runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensions;
215
232
  runnerProcessInstanceId?: string;
216
233
  launchBarrierToken?: string;
217
234
  parentWorkflowRunId?: string;
@@ -228,8 +245,8 @@ interface StepResult {
228
245
  permissionProfile?: string;
229
246
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
230
247
  capabilityAudit?: import("../shared/capability-ceiling.ts").SubagentCapabilityAudit;
231
- launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
232
- runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
248
+ launchResolvedExtensions?: LaunchResolvedChildExtensions;
249
+ runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensions;
233
250
  output: string;
234
251
  outputState?: SubagentOutputState;
235
252
  error?: string;
@@ -249,14 +266,15 @@ interface StepResult {
249
266
  sessionFile?: string;
250
267
  intercomTarget?: string;
251
268
  model?: string;
269
+ nativeMachine?: import("../../shared/types.ts").SingleResult["nativeMachine"];
252
270
  thinking?: string;
253
- attemptedModels?: string[];
254
- modelAttempts?: ModelAttempt[];
271
+ requestedModel?: string;
255
272
  /** True when the dispatch failed because the input exceeded the model's context window. */
256
273
  contextOverflow?: boolean;
257
274
  totalCost?: CostSummary;
258
275
  artifactPaths?: ArtifactPaths;
259
276
  outputSaveError?: string;
277
+ artifactOutputSaveFailed?: true;
260
278
  metadataSaveError?: string;
261
279
  truncated?: boolean;
262
280
  transcriptPath?: string;
@@ -279,21 +297,13 @@ interface StepResult {
279
297
  function commonSandboxProfile(steps: readonly RunnerStatusStep[]): string | undefined {
280
298
  const profile = steps[0]?.sandbox;
281
299
  if (!profile || !steps.every((step) => step.sandbox === profile)) return undefined;
282
- try {
283
- return validateSandboxProfileName(profile);
284
- } catch {
285
- return undefined;
286
- }
300
+ return validateSandboxProfileNameOptional(profile);
287
301
  }
288
302
 
289
303
  function commonPermissionProfile(steps: readonly RunnerStatusStep[]): string | undefined {
290
304
  const profile = steps[0]?.permissionProfile;
291
305
  if (!profile || !steps.every((step) => step.permissionProfile === profile)) return undefined;
292
- try {
293
- return validatePermissionProfileName(profile);
294
- } catch {
295
- return undefined;
296
- }
306
+ return validatePermissionProfileNameOptional(profile);
297
307
  }
298
308
 
299
309
  function persistStepArtifacts(input: {
@@ -419,50 +429,22 @@ function emptyUsage(): Usage {
419
429
  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
420
430
  }
421
431
 
422
- function tokenUsageFromAttempts(attempts: ModelAttempt[] | undefined): TokenUsage | null {
423
- if (!attempts || attempts.length === 0) return null;
424
- let input = 0;
425
- let output = 0;
426
- for (const attempt of attempts) {
427
- input += attempt.usage?.input ?? 0;
428
- output += attempt.usage?.output ?? 0;
429
- }
432
+ function tokenUsageFromUsage(usage: Usage | undefined): TokenUsage | null {
433
+ const input = usage?.input ?? 0;
434
+ const output = usage?.output ?? 0;
430
435
  const total = input + output;
431
436
  return total > 0 ? { input, output, total } : null;
432
437
  }
433
438
 
434
- function costSummaryFromAttempts(attempts: ModelAttempt[] | undefined): CostSummary | undefined {
435
- if (!attempts || attempts.length === 0) return undefined;
436
- let inputTokens = 0;
437
- let outputTokens = 0;
438
- let costUsd = 0;
439
- for (const attempt of attempts) {
440
- inputTokens += attempt.usage?.input ?? 0;
441
- outputTokens += attempt.usage?.output ?? 0;
442
- costUsd += attempt.usage?.cost ?? 0;
443
- }
439
+ function costSummaryFromUsage(usage: Usage | undefined): CostSummary | undefined {
440
+ const inputTokens = usage?.input ?? 0;
441
+ const outputTokens = usage?.output ?? 0;
442
+ const costUsd = usage?.cost ?? 0;
444
443
  return inputTokens > 0 || outputTokens > 0 || costUsd > 0
445
444
  ? { inputTokens, outputTokens, costUsd }
446
445
  : undefined;
447
446
  }
448
447
 
449
- function usageFromAttempts(attempts: ModelAttempt[] | undefined): Usage | undefined {
450
- if (!attempts || attempts.length === 0) return undefined;
451
- const usage = emptyUsage();
452
- for (const attempt of attempts) {
453
- if (!attempt.usage) continue;
454
- usage.input += attempt.usage.input;
455
- usage.output += attempt.usage.output;
456
- usage.cacheRead += attempt.usage.cacheRead;
457
- usage.cacheWrite += attempt.usage.cacheWrite;
458
- usage.cost += attempt.usage.cost;
459
- usage.turns += attempt.usage.turns;
460
- }
461
- return usage.input !== 0 || usage.output !== 0 || usage.cacheRead !== 0 || usage.cacheWrite !== 0 || usage.cost !== 0 || usage.turns !== 0
462
- ? usage
463
- : undefined;
464
- }
465
-
466
448
  function appendRecentStepOutput(step: RunnerStatusStep, lines: string[]): void {
467
449
  const nonEmpty = lines.filter((line) => line.trim());
468
450
  if (nonEmpty.length === 0) return;
@@ -656,6 +638,38 @@ function writeRunLog(
656
638
  write(logPath, lines.join("\n"));
657
639
  }
658
640
 
641
+ function expectedMissingGitEvidence(error: unknown): boolean {
642
+ if (typeof (error as { code?: unknown })?.code !== "number") return false;
643
+ const stderr = (error as { stderr?: unknown }).stderr;
644
+ const detail = Buffer.isBuffer(stderr) ? stderr.toString("utf-8") : String(stderr ?? "");
645
+ return /not a git repository|Needed a single revision/i.test(detail);
646
+ }
647
+
648
+ async function readGitFingerprint(cwd: string, signal: AbortSignal, onError: (error: unknown) => void): Promise<string | undefined> {
649
+ try {
650
+ const runGit = async (args: string[]) => {
651
+ const result = await runSetupCommand("git", args, {
652
+ cwd, signal, maxBuffer: 16 * 1024 * 1024, deadlineAt: Date.now() + 30_000,
653
+ acceptedExitCodes: Array.from({ length: 256 }, (_, code) => code),
654
+ });
655
+ if (result.error) throw result.error;
656
+ if (result.status !== 0) {
657
+ throw Object.assign(new Error(result.stderr || `git exited with ${result.status}`), { code: result.status, stderr: result.stderr });
658
+ }
659
+ return result.stdoutBuffer;
660
+ };
661
+ const headOutput = await runGit(["rev-parse", "--verify", "HEAD"]);
662
+ const head = headOutput.toString("utf-8").trim();
663
+ if (!head) return undefined;
664
+ const status = await runGit(["status", "--porcelain=v1", "-z", "--untracked-files=normal"]);
665
+ return `${head}\0${status.toString("base64")}`;
666
+ } catch (error) {
667
+ if ((error as NodeJS.ErrnoException)?.code === "PROCESS_TREE_UNVERIFIED") throw error;
668
+ if (!signal.aborted && !expectedMissingGitEvidence(error)) onError(error);
669
+ return undefined;
670
+ }
671
+ }
672
+
659
673
  /** Context for running a single step */
660
674
  interface SingleStepContext {
661
675
  previousOutput: string;
@@ -681,6 +695,8 @@ interface SingleStepContext {
681
695
  registerStop?: (stop: (() => void) | undefined) => void;
682
696
  /** Receives the live child's steer handler while its session runs. */
683
697
  registerSteer?: (steer: StepSteerHandler | undefined) => void;
698
+ /** Reports a live child's later steer consumption or unconsumed settlement. */
699
+ onSteerOutcome?: (request: SteerRequest, delivery: SteerDelivery) => void;
684
700
  timeoutSignal?: AbortSignal;
685
701
  stopSignal?: AbortSignal;
686
702
  timeoutMessage?: string;
@@ -694,19 +710,43 @@ interface SingleStepContext {
694
710
  nestedRoute?: NestedRouteInfo;
695
711
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
696
712
  runFanoutBudget?: RunFanoutBudgetDescriptor;
713
+ hostAvailableBuiltins?: readonly string[];
697
714
  onAttemptStart?: (attempt: { model?: string; thinking?: string; contextLimit?: number }) => void;
698
715
  onChildEvent?: (event: ChildEvent) => void;
699
716
  onExternalProcess?: (process: ExternalProcessStatus) => void;
717
+ prepareExternalActivity?: (cwd: string, signal: AbortSignal) => Promise<void>;
718
+ onExternalStreamActivity?: () => void;
700
719
  onExternalJob?: (status: ExternalJobStatus) => void;
701
720
  skipAcceptance?: () => boolean;
702
- usageBudgetExhausted?: () => boolean;
721
+ /** Authoritative owner decision after event delivery; undefined includes incomplete run-wide usage. */
722
+ usageBudgetExhausted?: () => boolean | undefined;
723
+ /** Existing run-owned budget configuration; cost allowance is not settled by the live token ledger. */
724
+ usageBudget?: UsageBudgetConfig;
703
725
  /** False when sibling work in the same Git worktree could have caused the tracked diff. */
704
726
  trackedMutationEvidenceForCompletionGuard?: boolean;
705
727
  orcaProgressTab?: OrcaProgressTab;
706
728
  }
707
729
 
708
- /** Run a single pi agent step, returning output and metadata */
709
- async function runSingleStepInner(
730
+ /** Machine runs: a one-line hint for predictable remote failures, and a note that writer changes live on the machine. */
731
+ function decorateHerdrMachineResult<T extends { output: string; exitCode: number | null; error?: string; externalProcess: { stderrPath: string } }>(result: T, machine: HerdrMachineReference, adapter: string | undefined): T {
732
+ let stderrTail = "";
733
+ try {
734
+ const stderr = fs.readFileSync(result.externalProcess.stderrPath, "utf-8");
735
+ stderrTail = stderr.slice(-4096);
736
+ } catch { /* stderr log is best-effort evidence. */ }
737
+ const hint = result.exitCode === 0 ? undefined : formatHerdrMachineHint(machine, `${result.error ?? ""}\n${stderrTail}\nexit code ${result.exitCode}`);
738
+ const error = hint ? `${result.error ?? `Remote command exited with code ${result.exitCode}.`}\n${hint}` : result.error;
739
+ const note = result.exitCode === 0 && adapter?.endsWith("-writer") ? `Changes made by this run live on ${machine.label ?? machine.id} at ${machine.cwd}; the local checkout is unchanged.` : undefined;
740
+ const output = note ? (result.output.trim() ? `${result.output.trimEnd()}\n\n${note}` : note) : result.output;
741
+ return { ...result, output, ...(error !== undefined ? { error } : {}) };
742
+ }
743
+
744
+ export async function settleHerdrExternalRunnerError(error: unknown, adapter: HerdrExternalAdapterId, evidence: Parameters<ReturnType<typeof createHerdrExternalAdapter>["normalize"]>[0], retain: () => Promise<void>): Promise<HerdrExternalResult> {
745
+ await retain();
746
+ if (!(error instanceof HerdrExternalNeedsAttentionError)) throw error;
747
+ return createHerdrExternalAdapter(adapter).normalize(evidence, error.message);
748
+ }
749
+ export async function runSingleStepInner(
710
750
  step: SubagentStep,
711
751
  ctx: SingleStepContext,
712
752
  ): Promise<StepResult & { completionGuardTriggered?: boolean }> {
@@ -764,8 +804,7 @@ async function runSingleStepInner(
764
804
  sessionFile: imported.sessionFile,
765
805
  intercomTarget: imported.intercomTarget,
766
806
  model: imported.model,
767
- attemptedModels: imported.attemptedModels,
768
- modelAttempts: imported.modelAttempts,
807
+ requestedModel: imported.requestedModel,
769
808
  contextOverflow: imported.contextOverflow,
770
809
  totalCost: imported.totalCost,
771
810
  usage: imported.usage,
@@ -799,16 +838,15 @@ async function runSingleStepInner(
799
838
  subagentOnlyExtensions: step.subagentOnlyExtensions,
800
839
  fast: step.fast,
801
840
  model: step.model,
802
- modelCandidates: step.modelCandidates,
803
841
  mcpDirectTools: step.mcpDirectTools,
804
842
  cwd: step.cwd ?? ctx.cwd,
805
843
  requireReadTool: Boolean(step.skills?.length),
806
844
  structuredOutput: Boolean(effectiveStructuredOutput),
807
845
  capabilityCeiling: step.capabilityCeiling ?? ctx.capabilityCeiling,
808
846
  inheritedCapabilityCeiling: ctx.inheritedChildRuntime?.capabilityCeiling,
847
+ requiredExtensions: step.requiredExtensions ?? ctx.inheritedChildRuntime?.requiredExtensions,
809
848
  permissionRules: step.permissionRules,
810
- sandbox: step.sandbox,
811
- permissionProfile: step.permissionProfile,
849
+ hostAvailableBuiltins: ctx.hostAvailableBuiltins,
812
850
  }));
813
851
  const contractTools = resolvedTaskToolPlan.explicitToolAllowlist ? resolvedTaskToolPlan.effectiveToolAllowlist : undefined;
814
852
  const contractError = validateImplementationToolContract({
@@ -836,8 +874,8 @@ async function runSingleStepInner(
836
874
  // Derive from the pre-acceptance task so internal acceptance/recovery
837
875
  // instructions never leak into the display name.
838
876
  const childSessionName = step.sessionName ?? deriveChildSessionName({ agent: step.agent, task, label: step.label });
839
- if (step.effectiveAcceptance) {
840
- const acceptancePrompt = formatAcceptancePrompt(step.effectiveAcceptance, { reportOptional: isAgentContractV1(step.agentContract), structuredOutput: Boolean(step.structuredOutput?.acceptanceReportPath) });
877
+ if (step.effectiveAcceptance && (step.runner?.type === "external-cli" || step.runner?.type === "external-job")) {
878
+ const acceptancePrompt = formatAcceptancePrompt(step.effectiveAcceptance, { reportOptional: isAgentContract(step.agentContract), structuredOutput: Boolean(step.structuredOutput?.acceptanceReportPath) });
841
879
  if (acceptancePrompt) task = `${task}\n${acceptancePrompt}`;
842
880
  }
843
881
  const sessionEnabled = Boolean(step.sessionFile) || ctx.sessionEnabled;
@@ -866,7 +904,53 @@ async function runSingleStepInner(
866
904
  transcriptWriter?.writeInitialUserMessage(`${PROMPT_REDACTED}; live Prompt Audit only.`);
867
905
 
868
906
  if (step.runner?.type === "external-cli") {
869
- const externalCwd = step.cwd ?? ctx.cwd;
907
+ const externalCwd = step.machine?.cwd ?? step.cwd ?? ctx.cwd;
908
+ const externalAbortSignal = combinedAbortSignal([ctx.timeoutSignal, ctx.stopSignal]);
909
+ if (!step.machine && externalAbortSignal) await ctx.prepareExternalActivity?.(externalCwd, externalAbortSignal);
910
+ if (externalAbortSignal?.aborted) {
911
+ const stopped = ctx.stopSignal?.aborted === true;
912
+ const message = stopped ? ctx.stopMessage ?? "Subagent stopped by user." : ctx.timeoutMessage ?? "Subagent timed out.";
913
+ return omitUndefinedProperties({ agent: step.agent, context: step.context, output: message, error: message, exitCode: 1, stopped: stopped || undefined, timedOut: stopped ? undefined : true });
914
+ }
915
+ if (step.machine) {
916
+ const runner = resolveExternalCliRunnerStatus({ ...step.runner, machine: step.machine });
917
+ const outputSnapshot = captureSingleOutputSnapshot(step.outputPath);
918
+ const placedRunId = `${ctx.id}-${ctx.flatIndex}`;
919
+ const session = await prepareInternalHerdrExternalAdapter({ adapter: step.runner.adapter as HerdrExternalAdapterId, machine: step.machine, runId: placedRunId }, {});
920
+ let timedOut = false, stopped = false, retain = false;
921
+ const evidenceInput = { runId: placedRunId, requestId: `prompt-${ctx.flatIndex}`, task: buildExternalCliPrompt(step.systemPrompt ?? "", task), cwd: externalCwd, nativeSessionId: session.launch.nativeSessionId };
922
+ let resolveInterruption!: (value: "timeout" | "stop") => void, rejectInterruption!: (error: unknown) => void;
923
+ const interruption = new Promise<"timeout" | "stop">((resolve, reject) => { resolveInterruption = resolve; rejectInterruption = reject; });
924
+ ctx.registerTimeout?.(() => { timedOut = true; retain = true; resolveInterruption("timeout"); });
925
+ ctx.registerStop?.(() => { stopped = true; void session.abort().then(() => resolveInterruption("stop"), rejectInterruption); });
926
+ try {
927
+ let settled: HerdrExternalResult;
928
+ try {
929
+ const raced = await Promise.race([session.promptAndSettle(evidenceInput).then((value) => ({ kind: "settled" as const, value })), interruption.then((kind) => ({ kind }))]);
930
+ if (raced.kind === "settled") settled = raced.value;
931
+ else if (raced.kind === "timeout") settled = createHerdrExternalAdapter(step.runner.adapter as HerdrExternalAdapterId).normalize(evidenceInput, "Placed external run timed out; truthful pane retained for inspection.");
932
+ else return { agent: step.agent, context: step.context, output: "Placed external run stopped by user.", outputState: "present", exitCode: 1, stopped: true, runner, execution: { status: "stopped", success: false, exitCode: 1, stopped: true } };
933
+ } catch (error) {
934
+ retain = true;
935
+ settled = await settleHerdrExternalRunnerError(error, step.runner.adapter as HerdrExternalAdapterId, evidenceInput, () => session.retain());
936
+ }
937
+ const output = settled.output;
938
+ try { fs.writeFileSync(ctx.outputFile, output, "utf-8"); } catch { /* Observability output is best-effort. */ }
939
+ const resolvedOutput = step.outputPath ? resolveSingleOutput(step.outputPath, output, outputSnapshot, step.outputClaimPath) : { fullOutput: output };
940
+ const outputReference = resolvedOutput.savedPath ? formatSavedOutputReference(resolvedOutput.savedPath, resolvedOutput.fullOutput) : undefined;
941
+ const finalizedOutput = finalizeSingleOutput(omitUndefinedProperties({ fullOutput: resolvedOutput.fullOutput, outputPath: step.outputPath, outputMode: step.outputMode, exitCode: 1, preserveSavedOutput: true, savedPath: resolvedOutput.savedPath, outputReference, saveError: resolvedOutput.saveError }));
942
+ const artifactErrors = artifactPaths && ctx.artifactConfig?.enabled !== false ? persistStepArtifacts({ artifactPaths, artifactConfig: ctx.artifactConfig, output: formatOutputArtifactContent(omitUndefinedProperties({ output: resolvedOutput.fullOutput, metadataPath: ctx.artifactConfig?.includeMetadata === false ? undefined : artifactPaths.metadataPath })), metadata: { runId: ctx.id, agent: step.agent, task: PROMPT_REDACTED, runner, placement: session.owner.identity, settlement: settled.settlement, outcome: settled.outcome, timestamp: Date.now() } }) : {};
943
+ return omitUndefinedProperties({ agent: step.agent, ...(childSessionName ? { sessionName: childSessionName } : {}), context: step.context, output: finalizedOutput.displayOutput, outputState: output.trim() ? "present" : "absent", exitCode: 1, error: resolvedOutput.fatalError ? resolvedOutput.saveError : undefined, timedOut, stopped, artifactPaths, outputSaveError: [resolvedOutput.saveError, artifactErrors.outputSaveError].filter(Boolean).join("\n") || undefined, metadataSaveError: artifactErrors.metadataSaveError, runner, execution: { status: "partial", success: false, exitCode: 1 } });
944
+ } catch (error) {
945
+ // Any post-allocation uncertainty retains the pane; only explicit stop
946
+ // and successful exact settlement are destructive.
947
+ retain = true;
948
+ throw error;
949
+ } finally {
950
+ ctx.registerTimeout?.(undefined); ctx.registerStop?.(undefined);
951
+ if (retain) await session.retain(); else await session.dispose();
952
+ }
953
+ }
870
954
  const adapterLaunch = step.runner.adapter === "codex-exec" || step.runner.adapter === "codex-exec-writer"
871
955
  ? resolveCodexExecLaunch({ adapter: step.runner.adapter, command: step.runner.command, asyncDir: path.dirname(ctx.outputFile), stepIndex: ctx.flatIndex })
872
956
  : step.runner.adapter === "claude-code" || step.runner.adapter === "claude-code-writer"
@@ -874,9 +958,13 @@ async function runSingleStepInner(
874
958
  : step.runner.adapter === "cursor-agent" || step.runner.adapter === "cursor-agent-writer"
875
959
  ? resolveCursorAgentLaunch({ adapter: step.runner.adapter, command: step.runner.command, cwd: externalCwd, asyncDir: path.dirname(ctx.outputFile), stepIndex: ctx.flatIndex })
876
960
  : undefined;
877
- const runner = resolveExternalCliRunnerStatus({ ...step.runner, ...(adapterLaunch ? { args: adapterLaunch.args } : {}) });
961
+ const runner = resolveExternalCliRunnerStatus({ ...step.runner, ...(adapterLaunch ? { args: adapterLaunch.args } : {}), ...(step.machine ? { machine: step.machine } : {}) });
878
962
  const outputSnapshot = captureSingleOutputSnapshot(step.outputPath);
879
- const external = await runExternalCli(omitUndefinedProperties({
963
+ const onExternalOutput = (chunk: Buffer): void => {
964
+ if (chunk.length > 0) ctx.onExternalStreamActivity?.();
965
+ ctx.orcaProgressTab?.append(chunk.toString("utf-8"));
966
+ };
967
+ const externalInput = omitUndefinedProperties({
880
968
  command: adapterLaunch?.command ?? runner.command,
881
969
  args: adapterLaunch?.args ?? runner.args,
882
970
  cwd: externalCwd,
@@ -894,9 +982,13 @@ async function runSingleStepInner(
894
982
  timeoutMessage: ctx.timeoutMessage,
895
983
  stopMessage: ctx.stopMessage,
896
984
  onProcess: ctx.onExternalProcess,
897
- onStdout: (chunk) => ctx.orcaProgressTab?.append(chunk.toString("utf-8")),
898
- onStderr: (chunk) => ctx.orcaProgressTab?.append(chunk.toString("utf-8")),
899
- }));
985
+ onStdout: onExternalOutput,
986
+ onStderr: onExternalOutput,
987
+ });
988
+ const preparedExternal = prepareHerdrMachineExternalCliRun(externalInput, step.machine ? { machine: step.machine, ...(step.machineEnv ? { env: step.machineEnv } : {}) } : undefined, { localCwd: ctx.cwd });
989
+ const ran = await runExternalCli(preparedExternal.input);
990
+ const externalProcess = preparedExternal.decorateProcess(ran.externalProcess);
991
+ const external = step.machine ? decorateHerdrMachineResult(ran, step.machine, step.runner.adapter) : ran;
900
992
  try { fs.writeFileSync(ctx.outputFile, external.output, "utf-8"); } catch { /* Observability output is best-effort. */ }
901
993
  const resolvedOutput = step.outputPath && external.exitCode === 0
902
994
  ? resolveSingleOutput(step.outputPath, external.output, outputSnapshot, step.outputClaimPath)
@@ -920,7 +1012,7 @@ async function runSingleStepInner(
920
1012
  artifactPaths,
921
1013
  artifactConfig: ctx.artifactConfig,
922
1014
  output: formatOutputArtifactContent(omitUndefinedProperties({ output: resolvedOutput.fullOutput, error: external.error, metadataPath: ctx.artifactConfig?.includeMetadata === false ? undefined : artifactPaths.metadataPath })),
923
- metadata: { runId: ctx.id, agent: step.agent, task: PROMPT_REDACTED, runner, externalProcess: external.externalProcess, exitCode: external.exitCode, error: external.error, timestamp: Date.now() },
1015
+ metadata: { runId: ctx.id, agent: step.agent, task: PROMPT_REDACTED, runner, externalProcess: externalProcess, exitCode: external.exitCode, error: external.error, timestamp: Date.now() },
924
1016
  })
925
1017
  : {};
926
1018
  return omitUndefinedProperties({
@@ -936,9 +1028,10 @@ async function runSingleStepInner(
936
1028
  processSignal: external.processSignal,
937
1029
  artifactPaths,
938
1030
  outputSaveError: [resolvedOutput.saveError, artifactErrors.outputSaveError].filter(Boolean).join("\n") || undefined,
1031
+ artifactOutputSaveFailed: artifactErrors.outputSaveError ? true : undefined,
939
1032
  metadataSaveError: artifactErrors.metadataSaveError,
940
1033
  runner,
941
- externalProcess: external.externalProcess,
1034
+ externalProcess: externalProcess,
942
1035
  });
943
1036
  }
944
1037
 
@@ -1005,6 +1098,7 @@ async function runSingleStepInner(
1005
1098
  stopped: external.stopped,
1006
1099
  artifactPaths,
1007
1100
  outputSaveError: [resolvedOutput.saveError, artifactErrors.outputSaveError].filter(Boolean).join("\n") || undefined,
1101
+ artifactOutputSaveFailed: artifactErrors.outputSaveError ? true : undefined,
1008
1102
  metadataSaveError: artifactErrors.metadataSaveError,
1009
1103
  runner,
1010
1104
  externalJob: external.externalJob,
@@ -1018,16 +1112,9 @@ async function runSingleStepInner(
1018
1112
  alignForkedSessionCwd(step.sessionFile, effectiveCwd);
1019
1113
  }
1020
1114
 
1021
- const candidates = step.modelCandidates !== undefined
1022
- ? step.modelCandidates.length > 0 ? step.modelCandidates : [undefined]
1023
- : step.model
1024
- ? [step.model]
1025
- : [undefined];
1026
- const attemptedModels: string[] = [];
1115
+ const candidate = step.model;
1027
1116
  let capabilityAudit: import("../shared/capability-ceiling.ts").SubagentCapabilityAudit | undefined;
1028
1117
  let launchResolvedExtensions = step.launchResolvedExtensions;
1029
- const modelAttempts: ModelAttempt[] = [];
1030
- const attemptNotes: string[] = [];
1031
1118
  let finalRequiredOutputMissing: boolean | undefined;
1032
1119
  const eventsPath = path.join(path.dirname(ctx.outputFile), "events.jsonl");
1033
1120
  let finalResult: RunChildSessionResult | undefined;
@@ -1038,20 +1125,17 @@ async function runSingleStepInner(
1038
1125
  let toolBudget = step.toolBudget ? initialToolBudgetState(step.toolBudget) : undefined;
1039
1126
  let toolBudgetBlocked = false;
1040
1127
  let actualLaunchContractDigest = step.launchContractDigest;
1041
- const mutationSnapshot = snapshotTrackedMutations(step.cwd ?? ctx.cwd);
1128
+ const mutationSnapshot = step.machine ? { source: "tracked-files" as const, trackedOnly: true as const, cwd: step.cwd ?? ctx.cwd, dirtyFiles: [], fingerprints: {}, unavailable: "Local Git evidence is not authoritative for a pane-native remote run." } : snapshotTrackedMutations(step.cwd ?? ctx.cwd);
1042
1129
  let finalMutationEvidence = collectTrackedMutationEvidence(mutationSnapshot, step.cwd ?? ctx.cwd);
1043
1130
 
1044
- let modelIndex = 0;
1045
1131
  let contextOverflow = false;
1046
1132
  let launchWarningsEmitted = false;
1047
- let abortRecoveryAttempted = false;
1048
- let nextAttemptTask = task;
1049
- modelAttemptsLoop: while (modelIndex < candidates.length) {
1050
- if (ctx.timeoutSignal?.aborted || ctx.stopSignal?.aborted || ctx.skipAcceptance?.()) break;
1051
- const recoveringAbort = abortRecoveryAttempted;
1052
- const attemptTask = nextAttemptTask;
1053
- const candidate = candidates[modelIndex];
1054
- const expectedModelForVerification = candidate && !(step.skipPrimaryModelVerification && modelIndex === 0) ? candidate : undefined;
1133
+ const aggregateUsage = emptyUsage();
1134
+ let launched = false;
1135
+ let recoveryTask = task;
1136
+ singleLaunch: for (let attemptIndex = 0; attemptIndex < 2; attemptIndex++) {
1137
+ if (ctx.timeoutSignal?.aborted || ctx.stopSignal?.aborted || ctx.skipAcceptance?.()) break singleLaunch;
1138
+ const expectedModelForVerification = candidate && !step.skipPrimaryModelVerification ? candidate : undefined;
1055
1139
  try {
1056
1140
  assertThinkingWithinCeiling({ model: candidate, configThinking: step.thinking, ceiling: step.thinkingCeiling, agent: step.agent, runId: ctx.id });
1057
1141
  } catch (error) {
@@ -1081,60 +1165,18 @@ async function runSingleStepInner(
1081
1165
  })
1082
1166
  : undefined;
1083
1167
  let watchdogSink: ((event: ChildWatchdogStatusEvent) => void) | undefined;
1084
- const launch = buildInProcessChildLaunch(omitUndefinedProperties({
1085
- parentSessionId: step.parentSessionId,
1086
- forkCacheKey: step.context === "fork" ? deriveForkPromptCacheKey(step.parentSessionId) : undefined,
1087
- sessionEnabled,
1088
- sessionDir,
1089
- sessionFile: step.sessionFile,
1090
- model: candidate,
1091
- inheritProjectContext: step.inheritProjectContext,
1092
- inheritGlobalContext: step.inheritGlobalContext,
1093
- inheritSkills: step.inheritSkills,
1094
- requireReadTool: Boolean(step.skills?.length),
1095
- tools: step.tools,
1096
- excludeTools: step.excludeTools,
1097
- allowNestedSubagents: step.allowNestedSubagents,
1098
- extensions: step.extensions,
1099
- subagentOnlyExtensions: step.subagentOnlyExtensions,
1100
- fast: step.fast,
1101
- modelCandidates: step.modelCandidates,
1102
- systemPrompt: step.systemPrompt ?? "",
1103
- systemPromptMode: step.systemPromptMode,
1104
- mcpDirectTools: step.mcpDirectTools,
1105
- extensionBindings,
1106
- capabilityCeiling: step.capabilityCeiling ?? ctx.capabilityCeiling,
1107
- cwd: step.cwd ?? ctx.cwd,
1108
- intercomSessionName: ctx.childIntercomTarget,
1109
- sessionName: childSessionName,
1110
- orchestratorIntercomTarget: ctx.orchestratorIntercomTarget,
1111
- runId: ctx.id,
1112
- childAgentName: step.agent,
1113
- childIndex: ctx.flatIndex,
1114
- nestedRoute: ctx.nestedRoute,
1115
- runFanoutBudget: ctx.runFanoutBudget ? {
1116
- ...ctx.runFanoutBudget,
1117
- ...(step.runFanoutPath ? { parentPath: `${ctx.runFanoutBudget.parentPath ? `${ctx.runFanoutBudget.parentPath}/` : ""}${step.runFanoutPath}` } : {}),
1118
- } : undefined,
1119
- structuredOutput: effectiveStructuredOutput,
1120
- toolBudget: step.toolBudget,
1121
- permissionRules: step.permissionRules,
1122
- projectTrusted: step.projectTrusted,
1123
- trustedProjectCwd: step.trustedProjectCwd,
1124
- sandbox: step.sandbox,
1125
- permissionProfile: step.permissionProfile,
1126
- permissionAuditPath: step.permissionRules && ctx.artifactsDir
1127
- ? path.join(ctx.artifactsDir, "permission-audit", `${ctx.id}-${ctx.flatIndex}.jsonl`)
1128
- : undefined,
1129
- childWatchdog,
1130
- watchdogStatus: (event) => watchdogSink?.(event),
1131
- waitToolEnabled: step.waitToolEnabled,
1132
- waitToolDefaultTimeoutMs: step.waitToolDefaultTimeoutMs,
1133
- thinkingCeiling: step.thinkingCeiling,
1134
- maxSubagentDepth: step.maxSubagentDepth,
1135
- inherited: ctx.inheritedChildRuntime,
1136
- host: "runner",
1137
- }));
1168
+ let launch: ReturnType<typeof buildRunnerChildLaunch>;
1169
+ try {
1170
+ launch = buildRunnerChildLaunch(step, ctx, {
1171
+ sessionEnabled,
1172
+ sessionDir,
1173
+ model: candidate,
1174
+ sessionName: childSessionName,
1175
+ structuredOutput: effectiveStructuredOutput,
1176
+ childWatchdog,
1177
+ watchdogStatus: (event) => watchdogSink?.(event),
1178
+ });
1179
+ } catch (error) { throw error; }
1138
1180
  if (effectiveStructuredOutput && launch.config.structuredOutput) {
1139
1181
  // The runner reads the value back from the runtime's files after the run.
1140
1182
  launch.config.structuredOutput.capture = createStructuredOutputFileCapture(effectiveStructuredOutput);
@@ -1153,43 +1195,35 @@ async function runSingleStepInner(
1153
1195
  subagentOnlyExtensions: step.subagentOnlyExtensions,
1154
1196
  fast: step.fast,
1155
1197
  model: step.model,
1156
- modelCandidates: step.modelCandidates,
1157
1198
  mcpDirectTools: step.mcpDirectTools,
1158
1199
  cwd: step.cwd ?? ctx.cwd,
1159
1200
  requireReadTool: Boolean(step.skills?.length),
1160
1201
  structuredOutput: Boolean(effectiveStructuredOutput),
1161
1202
  capabilityCeiling: step.capabilityCeiling ?? ctx.capabilityCeiling,
1162
1203
  inheritedCapabilityCeiling: ctx.inheritedChildRuntime?.capabilityCeiling,
1204
+ requiredExtensions: step.requiredExtensions ?? ctx.inheritedChildRuntime?.requiredExtensions,
1163
1205
  permissionRules: step.permissionRules,
1164
- sandbox: step.sandbox,
1165
- permissionProfile: step.permissionProfile,
1206
+ hostAvailableBuiltins: ctx.hostAvailableBuiltins,
1166
1207
  }));
1167
1208
  launchResolvedExtensions = projectLaunchResolvedChildExtensions(toolPlan);
1168
- actualLaunchContractDigest = launchBindingDigest(omitUndefinedProperties({
1209
+ actualLaunchContractDigest = resolveLaunchBinding({
1169
1210
  definitionDigest: step.definitionDigest,
1170
- task: step.launchBindingTask ?? task,
1171
- ...(candidate ? { model: candidate } : {}),
1172
- modelCandidates: candidates as string[],
1173
- ...(step.fast !== undefined ? { fast: step.fast } : {}),
1174
- ...(resolveEffectiveThinking(candidate, step.thinking) ? { thinking: resolveEffectiveThinking(candidate, step.thinking) } : {}),
1175
- ...(step.thinkingCeiling ? { thinkingCeiling: step.thinkingCeiling } : {}),
1176
- systemPrompt: step.systemPrompt ?? "",
1177
1211
  systemPromptMode: step.systemPromptMode,
1178
1212
  inheritProjectContext: step.inheritProjectContext,
1179
1213
  inheritGlobalContext: step.inheritGlobalContext,
1180
1214
  inheritSkills: step.inheritSkills,
1181
- sandbox: step.sandbox,
1182
- permissionProfile: step.permissionProfile,
1215
+ task: step.launchBindingTask ?? task,
1216
+ model: candidate,
1217
+ fast: step.fast,
1218
+ thinking: resolveEffectiveThinking(candidate, step.thinking),
1219
+ systemPrompt: step.systemPrompt ?? "",
1183
1220
  skills: step.skills,
1184
- tools: toolPlan.effectiveToolAllowlist,
1185
- ...(toolPlan.excludeTools.length > 0 ? { excludeTools: toolPlan.excludeTools } : {}),
1186
- extensions: toolPlan.extensionArgs,
1187
- mcpDirectTools: toolPlan.effectiveMcpTools,
1188
- ...(step.outputPath ? { outputPath: step.outputPath } : {}),
1189
- ...(step.outputMode ? { outputMode: step.outputMode } : {}),
1190
- ...(step.structuredOutputSchema ? { structuredOutputSchema: step.structuredOutputSchema } : {}),
1191
- ...(extensionBindings ? { extensionBindings } : {}),
1192
- }));
1221
+ toolPlan,
1222
+ outputPath: step.outputPath,
1223
+ outputMode: step.outputMode,
1224
+ structuredOutputSchema: step.structuredOutputSchema,
1225
+ extensionBindings,
1226
+ }).launchContractDigest;
1193
1227
  }
1194
1228
  capabilityAudit = attemptCapabilityAudit;
1195
1229
  // Each attempt rewrites the step output log; synchronous appends keep a
@@ -1198,7 +1232,7 @@ async function runSingleStepInner(
1198
1232
  const run = await runChildSession(omitUndefinedProperties({
1199
1233
  factory: ctx.childSessions,
1200
1234
  launch,
1201
- prompt: `Task: ${attemptTask}`,
1235
+ prompt: `Task: ${recoveryTask}`,
1202
1236
  childWatchdog,
1203
1237
  childEventContext: { runId: ctx.id, stepIndex: ctx.flatIndex, agent: step.agent },
1204
1238
  appendChildEvent: (event) => appendDiagnosticJsonl(eventsPath, JSON.stringify(event), typeof event.type === "string" ? event.type : undefined),
@@ -1214,6 +1248,7 @@ async function runSingleStepInner(
1214
1248
  registerTimeout: ctx.registerTimeout,
1215
1249
  registerStop: ctx.registerStop,
1216
1250
  registerSteer: ctx.registerSteer,
1251
+ onSteerOutcome: ctx.onSteerOutcome,
1217
1252
  registerWatchdogStatus: (sink) => { watchdogSink = sink; },
1218
1253
  timeoutMessage: ctx.timeoutMessage,
1219
1254
  stopMessage: ctx.stopMessage,
@@ -1223,8 +1258,19 @@ async function runSingleStepInner(
1223
1258
  runDeadlineAt: ctx.deadlineAt,
1224
1259
  expectedModelForVerification,
1225
1260
  modelVerificationRegistry: step.modelVerificationRegistry,
1261
+ modelResponseAliases: step.modelResponseAliases,
1226
1262
  mutationTools: step.mutationTools,
1227
1263
  }));
1264
+ launched = true;
1265
+ aggregateUsage.input += run.usage.input;
1266
+ aggregateUsage.output += run.usage.output;
1267
+ aggregateUsage.cacheRead += run.usage.cacheRead;
1268
+ aggregateUsage.cacheWrite += run.usage.cacheWrite;
1269
+ aggregateUsage.cost += run.usage.cost;
1270
+ aggregateUsage.turns += run.usage.turns;
1271
+ // A parked run still owes completion evidence when it actually finishes.
1272
+ // Stopped/timedOut runs already have terminal failures; checking completion evidence there is meaningless.
1273
+ const completionDiagnosticsEligible = !run.interrupted && !run.stopped && !run.timedOut;
1228
1274
  const toolDiagnostic = run.exitCode === 0 && !run.error ? launch.capture.toolDiagnostic() : undefined;
1229
1275
  const toolAvailabilityError = toolDiagnostic ? formatChildToolDiagnostic(toolDiagnostic) : undefined;
1230
1276
  const runtimeAcknowledgedExtensions = launch.capture.runtimeAcknowledgedExtensions();
@@ -1240,7 +1286,7 @@ async function runSingleStepInner(
1240
1286
  let structuredOutput: unknown;
1241
1287
  let structuredError: string | undefined;
1242
1288
  let validatedStructuredOutput = false;
1243
- if (effectiveStructuredOutput && run.exitCode === 0 && !run.error && !toolAvailabilityError && !midToolExitError) {
1289
+ if (completionDiagnosticsEligible && effectiveStructuredOutput && run.exitCode === 0 && !run.error && !toolAvailabilityError && !midToolExitError) {
1244
1290
  if (!run.structuredOutputToolInvoked) {
1245
1291
  structuredError = MISSING_STRUCTURED_OUTPUT_CALL_ERROR;
1246
1292
  } else {
@@ -1262,33 +1308,29 @@ async function runSingleStepInner(
1262
1308
  const errorMessages = validatedStructuredOutput
1263
1309
  ? run.messages.slice(run.structuredOutputMessageStartIndex ?? run.messages.length)
1264
1310
  : run.messages;
1265
- const hiddenError = run.exitCode === 0 && !run.error && !toolAvailabilityError && !structuredError && !midToolExitError
1311
+ const hiddenError = completionDiagnosticsEligible && run.exitCode === 0 && !run.error && !toolAvailabilityError && !structuredError && !midToolExitError
1266
1312
  ? detectSubagentError(errorMessages)
1267
1313
  : null;
1268
1314
  const terminalEmptyAfterUsefulWork = !validatedStructuredOutput
1269
1315
  && hasEmptyTerminalAssistantResponse(run.messages)
1270
1316
  && (run.toolCount > 0 || Boolean(run.finalOutput.trim()));
1271
- // A startup guard can block the child's first turn, which leaves no message to
1272
- // inspect; prefer the reason the blocked child published for the launcher.
1273
- const sandboxStartupDiagnostic = readSandboxStartupDiagnostic(launch.sandboxDiagnosticsPath);
1274
- const emptyOutputError = run.exitCode === 0
1317
+ const emptyOutputError = completionDiagnosticsEligible && run.exitCode === 0
1275
1318
  && !run.error
1276
1319
  && !toolAvailabilityError
1277
1320
  && !structuredError
1278
1321
  && !validatedStructuredOutput
1279
1322
  && (!run.finalOutput.trim() || terminalEmptyAfterUsefulWork)
1280
1323
  && (!hiddenError?.hasError || hasEmptyTerminalAssistantResponse(run.messages))
1281
- ? sandboxStartupDiagnostic?.reason ?? formatEmptyTerminalAssistantResponseError(run.messages)
1324
+ ? formatEmptyTerminalAssistantResponseError(run.messages)
1282
1325
  : undefined;
1283
- const startupBlocked = sandboxStartupDiagnostic !== undefined && emptyOutputError === sandboxStartupDiagnostic.reason;
1284
- if (startupBlocked) clearSandboxStartupDiagnostic(launch.sandboxDiagnosticsPath);
1285
- const completionGuardEnabled = isAgentContractV1(step.agentContract) ? step.completionGuard === true : step.completionGuard !== false;
1326
+ const completionGuardEnabled = isAgentContract(step.agentContract) ? step.completionGuard === true : step.completionGuard !== false;
1286
1327
  const completionToolPlan = resolvedTaskToolPlan;
1287
1328
  const completionTools = completionToolPlan ? (completionToolPlan.explicitToolAllowlist ? completionToolPlan.effectiveToolAllowlist : undefined) : step.tools;
1288
- const mutationEvidence = collectTrackedMutationEvidence(mutationSnapshot, step.cwd ?? ctx.cwd);
1329
+ const remoteGitChanged = run.nativeMachine?.initialGit && run.nativeMachine.finalGit ? run.nativeMachine.initialGit.head !== run.nativeMachine.finalGit.head || run.nativeMachine.initialGit.dirty !== run.nativeMachine.finalGit.dirty : undefined;
1330
+ const mutationEvidence = run.nativeMachine ? { source: "tracked-files" as const, trackedOnly: true as const, changedFiles: [], attemptedMutation: remoteGitChanged === true, ...(remoteGitChanged === undefined ? { unavailable: "Remote Git before/after evidence was incomplete." } : {}) } : collectTrackedMutationEvidence(mutationSnapshot, step.cwd ?? ctx.cwd);
1289
1331
  finalMutationEvidence = mutationEvidence;
1290
1332
  const completionMutationEvidence = ctx.trackedMutationEvidenceForCompletionGuard === false ? undefined : mutationEvidence;
1291
- const completionGuard = run.exitCode === 0 && !run.error && !structuredError && !hiddenError?.hasError && !midToolExitError && !emptyOutputError && completionGuardEnabled
1333
+ const completionGuard = completionDiagnosticsEligible && run.exitCode === 0 && !run.error && !structuredError && !hiddenError?.hasError && !midToolExitError && !emptyOutputError && completionGuardEnabled
1292
1334
  ? evaluateCompletionMutationGuard(omitUndefinedProperties({
1293
1335
  agent: step.agent,
1294
1336
  task: taskForCompletionGuard,
@@ -1301,14 +1343,27 @@ async function runSingleStepInner(
1301
1343
  }))
1302
1344
  : undefined;
1303
1345
  const mutationAttemptObserved = run.observedMutationAttempt === true || completionMutationEvidence?.attemptedMutation === true;
1346
+ let arbitration = { triggered: completionGuard?.triggered === true && !mutationAttemptObserved, rescued: false };
1347
+ if (arbitration.triggered) {
1348
+ const modelContext = launch.capture.completionIntentContext?.();
1349
+ arbitration = await arbitrateCompletionGuardRescue({
1350
+ guardTriggered: true,
1351
+ task: taskForCompletionGuard,
1352
+ // Construct lazily too: the shared gate refuses overlength tasks before
1353
+ // registry/auth/model work. The child has already shut down normally.
1354
+ arbiter: modelContext ? async (task) => createTaskMutationArbiter(modelContext)?.(task) ?? "unavailable" : undefined,
1355
+ });
1356
+ }
1304
1357
  const completionEvidence = planCompletionEvidence({
1305
1358
  guard: completionGuard,
1359
+ guardTriggered: arbitration.triggered,
1360
+ arbiterRescued: arbitration.rescued,
1306
1361
  completionGuardEnabled,
1307
1362
  mutationCapable: hasMutationToolCapability(completionTools, completionToolPlan?.effectiveMcpTools ?? step.mcpDirectTools),
1308
1363
  implementationMutationExpected: expectsImplementationMutation(step.agent, taskForCompletionGuard),
1309
1364
  mutationAttemptObserved,
1310
1365
  mutationEvidence: completionMutationEvidence,
1311
- agentContractV1: isAgentContractV1(step.agentContract),
1366
+ agentContractEnabled: isAgentContract(step.agentContract),
1312
1367
  });
1313
1368
  const finalOutputHasPersistableFileContent = run.exitCode === 0 && !run.error && !emptyOutputError && Boolean(stripAcceptanceReport(run.finalOutput).trim());
1314
1369
  const requiredOutput = step.outputMode === "file-only" && step.outputPath
@@ -1317,7 +1372,7 @@ async function runSingleStepInner(
1317
1372
  ? { kind: "structured" as const, path: effectiveStructuredOutput.outputPath, missing: !fs.existsSync(effectiveStructuredOutput.outputPath) }
1318
1373
  : undefined;
1319
1374
  finalRequiredOutputMissing = requiredOutput?.missing;
1320
- const missingRequiredOutputError = formatRequiredOutputError(requiredOutput);
1375
+ const missingRequiredOutputError = completionDiagnosticsEligible ? formatRequiredOutputError(requiredOutput) : undefined;
1321
1376
  const missingRequiredOutputAfterMutation = Boolean(missingRequiredOutputError) && (mutationAttemptObserved || Boolean(mutationEvidence.changedFiles.length));
1322
1377
  const effectiveExitCode = toolAvailabilityError || completionEvidence.legacyFailureError || midToolExitError || structuredError || emptyOutputError || missingRequiredOutputError
1323
1378
  ? 1
@@ -1338,15 +1393,6 @@ async function runSingleStepInner(
1338
1393
  : `${hiddenError.errorType} failed with exit code ${effectiveExitCode}`
1339
1394
  : undefined);
1340
1395
  const error = underlyingError ?? missingRequiredOutputError ?? completionEvidence.legacyFailureError;
1341
- const attempt: ModelAttempt = omitUndefinedProperties({
1342
- model: candidate ?? run.model ?? step.model ?? "default",
1343
- success: effectiveExitCode === 0 && !error,
1344
- exitCode: effectiveExitCode,
1345
- error,
1346
- usage: run.usage,
1347
- });
1348
- modelAttempts.push(attempt);
1349
- if (!recoveringAbort && candidate) attemptedModels.push(candidate);
1350
1396
  completionGuardTriggeredFinal = completionEvidence.guardTriggered && !underlyingError && !missingRequiredOutputError;
1351
1397
  finalOutputSnapshot = outputSnapshot;
1352
1398
  if (step.toolBudget) {
@@ -1364,11 +1410,14 @@ async function runSingleStepInner(
1364
1410
  });
1365
1411
  const fileMutationEffect = completionEvidence.fileMutation ?? (missingRequiredOutputAfterMutation ? { status: "observed" as const, expected: completionEvidence.mutationExpected, attempted: true, evidence: mutationEvidence } : undefined);
1366
1412
  finalResult = { ...run, exitCode: effectiveExitCode, model: candidate ?? run.model, error, structuredOutput, runtimeAcknowledgedExtensions, ...(step.agentContract ? { agentContract: step.agentContract } : {}), ...(fileMutationEffect || settlementDiagnostic ? { effects: { ...(fileMutationEffect ? { fileMutation: fileMutationEffect } : {}), ...(settlementDiagnostic ? { settlementDiagnostic } : {}) } } : {}) } as RunChildSessionResult;
1367
- const abortRecovery = !attempt.success ? planAbortRecovery({
1413
+ if (run.stopped || run.timedOut || ctx.timeoutSignal?.aborted || ctx.stopSignal?.aborted || ctx.skipAcceptance?.()) break singleLaunch;
1414
+ if (effectiveExitCode === 0 && !error) break singleLaunch;
1415
+ if (completionEvidence.guardTriggered) break singleLaunch;
1416
+ const recovery = planAbortRecovery({
1368
1417
  messages: run.messages,
1369
1418
  error,
1370
1419
  sessionAvailable: Boolean(step.sessionFile && fs.existsSync(step.sessionFile)),
1371
- alreadyResumed: abortRecoveryAttempted,
1420
+ alreadyResumed: attemptIndex > 0,
1372
1421
  stopped: run.stopped || ctx.stopSignal?.aborted || ctx.skipAcceptance?.(),
1373
1422
  interrupted: run.interrupted,
1374
1423
  timedOut: run.timedOut || ctx.timeoutSignal?.aborted,
@@ -1378,39 +1427,26 @@ async function runSingleStepInner(
1378
1427
  acceptanceFailed: false,
1379
1428
  currentTool: run.currentTool,
1380
1429
  afterCompactionSettlement: run.afterCompactionSettlement,
1381
- }) : undefined;
1382
- if (abortRecovery?.action === "settle" && abortRecovery.diagnostic) {
1383
- attempt.error = attempt.error
1384
- ? `${abortRecovery.diagnostic}\n${attempt.error.slice(0, 8_000)}`
1385
- : abortRecovery.diagnostic;
1386
- if (finalResult) finalResult.abortRecoveryDiagnostic = abortRecovery.diagnostic;
1430
+ });
1431
+ if (recovery.action === "resume") {
1432
+ recoveryTask = recovery.prompt;
1433
+ continue singleLaunch;
1387
1434
  }
1388
- if (run.stopped || run.timedOut || ctx.timeoutSignal?.aborted || ctx.stopSignal?.aborted || ctx.skipAcceptance?.()) break modelAttemptsLoop;
1389
- if (abortRecovery?.action === "settle" && abortRecovery.diagnostic) break modelAttemptsLoop;
1390
- if (attempt.success) break modelAttemptsLoop;
1391
- if (recoveringAbort) break modelAttemptsLoop;
1392
- if (abortRecovery?.action === "resume") {
1393
- abortRecoveryAttempted = true;
1394
- nextAttemptTask = abortRecovery.prompt;
1395
- attemptNotes.push("[abort-recovery] provider/transport abort after useful progress; resuming the retained child session once.");
1396
- continue;
1435
+ if (recovery.diagnostic) {
1436
+ finalResult.abortRecoveryDiagnostic = recovery.diagnostic;
1397
1437
  }
1398
- if (completionEvidence.guardTriggered) break modelAttemptsLoop;
1399
1438
 
1400
- const retryableModelFailure = isRetryableModelFailureAttempt({ error, messages: run.messages, toolCount: run.toolCount, ...(startupBlocked ? { startupBlocked: true } : {}) });
1401
- if (retryableModelFailure) recordRetryableModelFailure(candidate ?? run.model ?? step.model, error);
1402
1439
  if (isContextOverflow(error)) {
1403
1440
  contextOverflow = true;
1404
- attemptNotes.push(`[fallback] ${attempt.model} failed: context overflow — the input exceeds this model's context window. Reduce the task input or use a model with a larger context window.`);
1405
- break modelAttemptsLoop;
1441
+ break singleLaunch;
1406
1442
  }
1407
- if (!retryableModelFailure || modelIndex === candidates.length - 1) break modelAttemptsLoop;
1408
- attemptNotes.push(formatModelAttemptNote(attempt, candidates[modelIndex + 1]));
1409
- modelIndex += 1;
1443
+ break singleLaunch;
1410
1444
  }
1411
1445
 
1412
1446
  const rawOutput = finalResult?.finalOutput ?? "";
1413
- const outputForPersistence = stripAcceptanceReport(rawOutput);
1447
+ let outputForPersistence = stripAcceptanceReport(rawOutput);
1448
+ if (!outputForPersistence.trim() && finalResult?.structuredOutput !== undefined)
1449
+ outputForPersistence = JSON.stringify(finalResult.structuredOutput, null, 2);
1414
1450
  const resolvedOutput = step.outputPath && finalResult?.exitCode === 0
1415
1451
  ? resolveSingleOutput(step.outputPath, outputForPersistence, finalOutputSnapshot, step.outputClaimPath)
1416
1452
  : { fullOutput: outputForPersistence };
@@ -1423,9 +1459,6 @@ async function runSingleStepInner(
1423
1459
  const output = stripAcceptanceReport(resolvedOutput.fullOutput);
1424
1460
  const outputReference = resolvedOutput.savedPath ? formatSavedOutputReference(resolvedOutput.savedPath, output) : undefined;
1425
1461
  let outputForSummary = output;
1426
- if (attemptNotes.length > 0) {
1427
- outputForSummary = `${attemptNotes.join("\n")}\n\n${outputForSummary}`.trim();
1428
- }
1429
1462
  if (finalResult?.stopped && !outputForSummary.trim()) {
1430
1463
  outputForSummary = ctx.stopMessage ?? "Subagent stopped by user.";
1431
1464
  }
@@ -1478,7 +1511,7 @@ async function runSingleStepInner(
1478
1511
  cwd: step.cwd ?? ctx.cwd,
1479
1512
  signal: combinedAbortSignal([ctx.timeoutSignal, ctx.stopSignal]),
1480
1513
  abortMessage: ctx.stopSignal?.aborted ? ctx.stopMessage ?? "Subagent stopped by user." : ctx.timeoutMessage ?? "Subagent timed out.",
1481
- reportOptional: isAgentContractV1(step.agentContract),
1514
+ reportOptional: isAgentContract(step.agentContract),
1482
1515
  artifactsDir: ctx.artifactsDir,
1483
1516
  runId: ctx.id,
1484
1517
  watchdog: finalResult?.watchdog,
@@ -1494,7 +1527,7 @@ async function runSingleStepInner(
1494
1527
  : acceptance
1495
1528
  : undefined;
1496
1529
  const acceptanceFailure = effectiveAcceptance ? acceptanceFailureMessage(effectiveAcceptance) : undefined;
1497
- const acceptanceCanFailRun = acceptanceFailure && effectiveAcceptance?.explicit && (finalResult?.exitCode ?? 1) === 0 && !finalResult?.interrupted && !timedOutAfterAcceptance && !stoppedAfterAcceptance && !isAgentContractV1(step.agentContract);
1530
+ const acceptanceCanFailRun = acceptanceFailure && effectiveAcceptance?.explicit && (finalResult?.exitCode ?? 1) === 0 && !finalResult?.interrupted && !timedOutAfterAcceptance && !stoppedAfterAcceptance && !isAgentContract(step.agentContract);
1498
1531
  const effectiveFinalExitCode = timedOutAfterAcceptance || stoppedAfterAcceptance ? 1 : acceptanceCanFailRun ? 1 : finalResult?.exitCode ?? 1;
1499
1532
  const intercomDetachReceipt = finalResult?.finalOutput === INTERCOM_DETACH_RECEIPT;
1500
1533
  const baseFinalError = stoppedAfterAcceptance
@@ -1510,7 +1543,7 @@ async function runSingleStepInner(
1510
1543
  abortRecoveryDiagnostic: effectiveFinalExitCode !== 0 ? finalResult?.abortRecoveryDiagnostic : undefined,
1511
1544
  requiredOutput: effectiveFinalExitCode !== 0 ? finalResult?.effects?.settlementDiagnostic?.requiredOutput : undefined,
1512
1545
  });
1513
- const usage = usageFromAttempts(modelAttempts);
1546
+ const usage = launched ? aggregateUsage : undefined;
1514
1547
 
1515
1548
  const artifactErrors = artifactPaths && ctx.artifactConfig?.enabled !== false
1516
1549
  ? persistStepArtifacts({
@@ -1528,16 +1561,15 @@ async function runSingleStepInner(
1528
1561
  task: PROMPT_REDACTED,
1529
1562
  exitCode: effectiveFinalExitCode,
1530
1563
  model: finalResult?.model,
1531
- attemptedModels: attemptedModels.length > 0 ? attemptedModels : undefined,
1532
- modelAttempts,
1564
+ nativeMachine: finalResult?.nativeMachine,
1565
+ requestedModel: step.requestedModel,
1533
1566
  usage,
1534
1567
  error: effectiveFinalError,
1535
1568
  acceptance: effectiveAcceptance,
1536
1569
  ...(capabilityAudit ? { capabilityCeiling: capabilityAudit.ceiling, capabilityAudit } : {}),
1537
- sandbox: step.sandbox,
1538
1570
  launchContractDigest: actualLaunchContractDigest,
1539
1571
  launchResolvedExtensions,
1540
- ...((finalResult as (RunChildSessionResult & { runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1 }) | undefined)?.runtimeAcknowledgedExtensions ? { runtimeAcknowledgedExtensions: (finalResult as RunChildSessionResult & { runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1 }).runtimeAcknowledgedExtensions } : {}),
1572
+ ...((finalResult as (RunChildSessionResult & { runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensions }) | undefined)?.runtimeAcknowledgedExtensions ? { runtimeAcknowledgedExtensions: (finalResult as RunChildSessionResult & { runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensions }).runtimeAcknowledgedExtensions } : {}),
1541
1573
  ...(transcriptWriter ? { transcriptPath: artifactPaths.transcriptPath } : {}),
1542
1574
  transcriptError: transcriptWriter?.getError(),
1543
1575
  skills: step.skills,
@@ -1550,8 +1582,6 @@ async function runSingleStepInner(
1550
1582
  agent: step.agent,
1551
1583
  ...(childSessionName ? { sessionName: childSessionName } : {}),
1552
1584
  context: step.context,
1553
- ...(step.sandbox ? { sandbox: step.sandbox } : {}),
1554
- ...(step.permissionProfile ? { permissionProfile: step.permissionProfile } : {}),
1555
1585
  ...(step.agentContract ? { agentContract: step.agentContract } : {}),
1556
1586
  launchContractDigest: actualLaunchContractDigest,
1557
1587
  output: outputForSummary,
@@ -1561,14 +1591,16 @@ async function runSingleStepInner(
1561
1591
  sessionFile: step.sessionFile,
1562
1592
  intercomTarget: ctx.childIntercomTarget,
1563
1593
  model: finalResult?.model,
1594
+ nativeMachine: finalResult?.nativeMachine,
1564
1595
  thinking: resolveEffectiveThinking(finalResult?.model, step.thinking),
1565
- attemptedModels: attemptedModels.length > 0 ? attemptedModels : undefined,
1566
- modelAttempts,
1596
+ requestedModel: step.requestedModel,
1567
1597
  contextOverflow: contextOverflow || undefined,
1568
- totalCost: costSummaryFromAttempts(modelAttempts),
1598
+ totalCost: costSummaryFromUsage(usage),
1569
1599
  usage,
1570
1600
  artifactPaths,
1601
+ savedOutputPath: finalizedOutput.savedPath,
1571
1602
  outputSaveError: [resolvedOutput.saveError, artifactErrors.outputSaveError].filter(Boolean).join("\n") || undefined,
1603
+ artifactOutputSaveFailed: artifactErrors.outputSaveError ? true : undefined,
1572
1604
  metadataSaveError: artifactErrors.metadataSaveError,
1573
1605
  transcriptPath: transcriptWriter ? artifactPaths?.transcriptPath : undefined,
1574
1606
  transcriptError: transcriptWriter?.getError(),
@@ -1587,12 +1619,9 @@ async function runSingleStepInner(
1587
1619
  watchdog: finalResult?.watchdog,
1588
1620
  ...(capabilityAudit ? { capabilityCeiling: capabilityAudit.ceiling, capabilityAudit } : {}),
1589
1621
  launchResolvedExtensions,
1590
- ...((finalResult as (RunChildSessionResult & { runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1 }) | undefined)?.runtimeAcknowledgedExtensions ? { runtimeAcknowledgedExtensions: (finalResult as RunChildSessionResult & { runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1 }).runtimeAcknowledgedExtensions } : {}),
1622
+ ...((finalResult as (RunChildSessionResult & { runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensions }) | undefined)?.runtimeAcknowledgedExtensions ? { runtimeAcknowledgedExtensions: (finalResult as RunChildSessionResult & { runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensions }).runtimeAcknowledgedExtensions } : {}),
1591
1623
  });
1592
- // SAFETY: `result` is the step result assembled above for this same run; agent-contract
1593
- // projections are attached to that object and re-narrowed to its own type, so the
1594
- // assertion only re-states the shape the builders already produced here.
1595
- return isAgentContractV1(step.agentContract) ? attachContractProjections(result as unknown as import("../../shared/types.ts").SingleResult) as unknown as typeof result : result;
1624
+ return isAgentContract(step.agentContract) ? attachContractProjections(result as unknown as import("../../shared/types.ts").SingleResult) as unknown as typeof result : result;
1596
1625
  }
1597
1626
 
1598
1627
  async function runSingleStep(
@@ -1683,12 +1712,15 @@ function markParallelGroupSetupFailure(input: {
1683
1712
  const statusStep = requiredStatusStep(input.statusPayload, flatTaskIndex);
1684
1713
  const task = input.group.parallel[taskIndex];
1685
1714
  if (!task) throw new Error(`Missing parallel task at index ${taskIndex}`);
1686
- statusStep.status = "failed";
1715
+ const stopped = statusStep.stopped || statusStep.stopRequested || input.statusPayload.stopped;
1716
+ const paused = !stopped && input.statusPayload.state === "paused";
1717
+ statusStep.status = stopped ? "stopped" : paused ? "paused" : "failed";
1687
1718
  statusStep.startedAt = input.failedAt;
1688
1719
  statusStep.endedAt = input.failedAt;
1689
1720
  statusStep.durationMs = 0;
1690
- statusStep.exitCode = 1;
1691
- input.results.push(omitUndefinedProperties({ agent: task.agent, context: task.context, output: input.setupError, success: false, exitCode: 1, sessionFile: task.sessionFile }));
1721
+ statusStep.exitCode = paused ? 0 : 1;
1722
+ statusStep.error ??= input.setupError;
1723
+ input.results.push(omitUndefinedProperties({ agent: task.agent, context: task.context, output: input.setupError, error: input.setupError, success: false, exitCode: paused ? 0 : 1, sessionFile: task.sessionFile, stopped: stopped || undefined, interrupted: paused || undefined, timedOut: input.statusPayload.timedOut || undefined }));
1692
1724
  }
1693
1725
  input.statusPayload.currentStep = input.groupStartFlatIndex;
1694
1726
  input.statusPayload.lastUpdate = input.failedAt;
@@ -1812,8 +1844,12 @@ function missingRequiredOutputAfterUsefulMutation(result: SingleStepResult): boo
1812
1844
  }
1813
1845
 
1814
1846
  function partialExecutionWithUsefulMutation(result: SingleStepResult): boolean {
1847
+ if (result.execution?.status !== "partial") return false;
1848
+ // Pane-native external results are deliberately partial from bounded terminal
1849
+ // evidence alone; Pi mutation-based partials retain their existing behavior.
1850
+ if (result.runner?.type === "external-cli" && result.runner.machine) return true;
1815
1851
  const fileMutation = result.effects?.fileMutation;
1816
- return result.execution?.status === "partial" && (fileMutation?.attempted === true || Boolean(fileMutation?.evidence?.changedFiles.length));
1852
+ return fileMutation?.attempted === true || Boolean(fileMutation?.evidence?.changedFiles.length);
1817
1853
  }
1818
1854
 
1819
1855
  function partialEvidenceResult(result: SingleStepResult): boolean {
@@ -1845,7 +1881,10 @@ async function runSingleStepWithTimeout(
1845
1881
  ctx: SingleStepContext,
1846
1882
  parentDeadlineAt?: number,
1847
1883
  ): Promise<SingleStepResult> {
1848
- if (step.timeoutMs === undefined) return runSingleStep(step, ctx);
1884
+ if (step.timeoutMs === undefined) return runSingleStep(step, parentDeadlineAt === undefined ? ctx : {
1885
+ ...ctx,
1886
+ deadlineAt: ctx.deadlineAt === undefined ? parentDeadlineAt : Math.min(ctx.deadlineAt, parentDeadlineAt),
1887
+ });
1849
1888
 
1850
1889
  const parentRemainingMs = parentDeadlineAt === undefined ? undefined : Math.max(0, parentDeadlineAt - Date.now());
1851
1890
  const timeoutMs = parentRemainingMs === undefined ? step.timeoutMs : Math.min(step.timeoutMs, parentRemainingMs);
@@ -1882,7 +1921,7 @@ async function runSingleStepWithTimeout(
1882
1921
  }
1883
1922
  }
1884
1923
 
1885
- async function runSubagent(
1924
+ export async function runSubagent(
1886
1925
  config: SubagentRunConfig,
1887
1926
  childSessions: ChildSessionFactory,
1888
1927
  ): Promise<void> {
@@ -1913,6 +1952,7 @@ async function runSubagent(
1913
1952
  let currentActivityState: ActivityState | undefined;
1914
1953
  let activityTimer: NodeJS.Timeout | undefined;
1915
1954
  let timeoutTimer: NodeJS.Timeout | undefined;
1955
+ let checkpointTimer: NodeJS.Timeout | undefined;
1916
1956
  let timedOut = false;
1917
1957
  let stopped = false;
1918
1958
  let usageBudgetExceeded = false;
@@ -1920,6 +1960,9 @@ async function runSubagent(
1920
1960
  const stopMessage = "Subagent stopped by user.";
1921
1961
  const timeoutAbortController = new AbortController();
1922
1962
  const stopAbortController = new AbortController();
1963
+ const setupInterruptController = new AbortController();
1964
+ const runStopSignal = AbortSignal.any([timeoutAbortController.signal, stopAbortController.signal]);
1965
+ const setupSignal = AbortSignal.any([timeoutAbortController.signal, stopAbortController.signal, setupInterruptController.signal]);
1923
1966
  let previousCumulativeTokens: TokenUsage = { input: 0, output: 0, total: 0 };
1924
1967
  let latestSessionFile: string | undefined;
1925
1968
 
@@ -1961,7 +2004,7 @@ async function runSubagent(
1961
2004
  model: task.model,
1962
2005
  ...(task.contextLimit !== undefined ? { contextLimit: task.contextLimit } : {}),
1963
2006
  thinking: task.thinking,
1964
- attemptedModels: task.modelCandidates && task.modelCandidates.length > 0 ? task.modelCandidates : task.model ? [task.model] : undefined,
2007
+ requestedModel: task.requestedModel,
1965
2008
  recentTools: [],
1966
2009
  recentOutput: [],
1967
2010
  }));
@@ -2017,7 +2060,7 @@ async function runSubagent(
2017
2060
  model: step.model,
2018
2061
  ...(step.contextLimit !== undefined ? { contextLimit: step.contextLimit } : {}),
2019
2062
  thinking: step.thinking,
2020
- attemptedModels: step.modelCandidates && step.modelCandidates.length > 0 ? step.modelCandidates : step.model ? [step.model] : undefined,
2063
+ requestedModel: step.requestedModel,
2021
2064
  recentTools: [],
2022
2065
  recentOutput: [],
2023
2066
  }));
@@ -2093,20 +2136,29 @@ async function runSubagent(
2093
2136
  },
2094
2137
  onError: (error, filePath) => console.error(`Failed to update async run index '${filePath}':`, error),
2095
2138
  });
2096
- const queueActiveRunIndex = (): void => {
2097
- const state = statusPayload.state;
2139
+ const queueActiveRunIndex = (status: AsyncStatus): void => {
2140
+ const state = status.state;
2098
2141
  if (state === lastIndexedStatusState && indexPersistence.pendingCount() === 0) return;
2099
- indexPersistence.write(asyncDir, { state, toolCallId: statusPayload.toolCallId }, (_filePath, payload) => {
2142
+ indexPersistence.write(asyncDir, { state, toolCallId: status.toolCallId }, (_filePath, payload) => {
2100
2143
  const indexPayload = payload as { state: AsyncStatus["state"]; toolCallId?: string };
2101
2144
  updateActiveRunIndex(asyncDir, indexPayload.state, indexPayload.toolCallId, { retryCapacityErrors: true });
2102
2145
  });
2103
2146
  };
2147
+ let finalResultCommitted = false;
2148
+ let finalResultPublication: { resolve(): void; reject(error: unknown): void } | undefined;
2104
2149
  const runPersistence = createCapacityResilientJsonWriter({
2105
2150
  keepAlive: true,
2106
- onSuccess: (filePath) => {
2107
- if (filePath === statusPath) queueActiveRunIndex();
2151
+ onSuccess: (filePath, payload) => {
2152
+ if (filePath === statusPath) queueActiveRunIndex(payload as AsyncStatus);
2153
+ if (filePath === resultPath && finalResultPublication) {
2154
+ finalResultCommitted = true;
2155
+ finalResultPublication.resolve();
2156
+ }
2157
+ },
2158
+ onError: (error, filePath) => {
2159
+ console.error(`Failed to persist async run state '${filePath}':`, error);
2160
+ if (filePath === resultPath) finalResultPublication?.reject(error);
2108
2161
  },
2109
- onError: (error, filePath) => console.error(`Failed to persist async run state '${filePath}':`, error),
2110
2162
  });
2111
2163
  try {
2112
2164
  fs.mkdirSync(asyncDir, { recursive: true });
@@ -2114,7 +2166,7 @@ async function runSubagent(
2114
2166
  if (!isStorageCapacityError(error)) throw error;
2115
2167
  console.error(`Failed to prepare async run storage '${asyncDir}' while storage is full:`, error);
2116
2168
  }
2117
- runPersistence.write(statusPath, statusPayload);
2169
+ runPersistence.write(statusPath, { ...statusPayload });
2118
2170
 
2119
2171
  let pendingParallelUsageCost: CostSummary = { inputTokens: 0, outputTokens: 0, costUsd: 0 };
2120
2172
  const currentUsageTotals = (): CostSummary => {
@@ -2133,6 +2185,13 @@ async function runSubagent(
2133
2185
  setOptionalProperty(statusPayload, "usageBudget", usageBudgetState(config.usageBudget, currentUsageTotals()));
2134
2186
  return statusPayload.usageBudget;
2135
2187
  };
2188
+ // Continuation admission only: the existing ledger has no in-flight cost or
2189
+ // external/import usage coverage. Never change ordinary budget enforcement.
2190
+ let continuationUsageUncertain = config.steps.some(isDynamicRunnerGroup) || flatSteps.some((step) => Boolean(step.runner || step.importAsyncRoot));
2191
+ const continuationUsageBudgetExhausted = (): boolean | undefined => {
2192
+ const exhausted = refreshUsageBudget()?.exhausted === true;
2193
+ return exhausted ? true : config.usageBudget && continuationUsageUncertain ? undefined : false;
2194
+ };
2136
2195
  const emitNestedSelfEvent = (type: "subagent.nested.updated" | "subagent.nested.completed"): void => {
2137
2196
  if (!config.nestedRoute || !config.nestedSelf) return;
2138
2197
  try {
@@ -2187,7 +2246,6 @@ async function runSubagent(
2187
2246
  for (const node of graph.nodes) updateNode(node);
2188
2247
  statusPayload.workflowGraph = graph;
2189
2248
  };
2190
- let finalResultCommitted = false;
2191
2249
  const statusResultState = (): AsyncStatus["state"] | undefined => {
2192
2250
  if (statusPayload.state === "running" || statusPayload.state === "queued") return undefined;
2193
2251
  return statusPayload.state;
@@ -2234,11 +2292,7 @@ async function runSubagent(
2234
2292
  sessionFile: step.sessionFile,
2235
2293
  model: step.model,
2236
2294
  thinking: step.thinking,
2237
- sandbox: step.sandbox,
2238
- attemptedModels: step.attemptedModels,
2239
- modelAttempts: step.modelAttempts,
2240
- usage: usageFromAttempts(step.modelAttempts),
2241
- contextOverflow: step.contextOverflow,
2295
+ requestedModel: step.requestedModel, contextOverflow: step.contextOverflow,
2242
2296
  })),
2243
2297
  exitCode: state === "complete" || state === "paused" ? 0 : 1,
2244
2298
  timestamp: now,
@@ -2251,14 +2305,15 @@ async function runSubagent(
2251
2305
  }), (filePath, payload) => writePendingAsyncResultFile(filePath, payload as Record<string, unknown>));
2252
2306
  };
2253
2307
  const writeStatusPayloadNow = (): void => {
2308
+ if (finalResultPublication) return;
2254
2309
  refreshWorkflowGraph();
2255
2310
  writeRecoverableStatusResult();
2256
- runPersistence.write(statusPath, statusPayload);
2311
+ runPersistence.write(statusPath, { ...statusPayload });
2257
2312
  emitNestedSelfEvent(statusPayload.state === "running" || statusPayload.state === "queued" ? "subagent.nested.updated" : "subagent.nested.completed");
2258
2313
  };
2259
2314
  const statusWriteCoalescer = createFileCoalescer(writeStatusPayloadNow, 100);
2260
2315
  const writeStatusPayload = (immediate = true): void => {
2261
- if (immediate || statusPayload.state !== "running" || statusPayload.activityState !== undefined) {
2316
+ if (immediate || statusPayload.state !== "running") {
2262
2317
  if (!statusWriteCoalescer.flush(statusPath)) writeStatusPayloadNow();
2263
2318
  return;
2264
2319
  }
@@ -2401,6 +2456,8 @@ async function runSubagent(
2401
2456
  yield* nestedRuns(child.steps?.flatMap((step) => step.children ?? []));
2402
2457
  }
2403
2458
  };
2459
+ const isNestedControlDescendant = (run: NestedRunSummary): boolean =>
2460
+ !config.nestedSelf || run.path.some((entry) => entry.runId === id);
2404
2461
  const interruptNestedAsyncDescendants = (): void => {
2405
2462
  if (!config.nestedRoute) return;
2406
2463
  let registry: ReturnType<typeof projectNestedEvents>;
@@ -2416,7 +2473,7 @@ async function runSubagent(
2416
2473
  return;
2417
2474
  }
2418
2475
  for (const run of nestedRuns(registry.children)) {
2419
- if (run.state !== "running" && run.state !== "queued") continue;
2476
+ if (!isNestedControlDescendant(run) || (run.state !== "running" && run.state !== "queued")) continue;
2420
2477
  const nestedAsyncDir = run.asyncDir ?? resolveNestedAsyncDir(config.nestedRoute.rootRunId, run);
2421
2478
  if (!nestedAsyncDir) continue;
2422
2479
  try {
@@ -2447,7 +2504,7 @@ async function runSubagent(
2447
2504
  return;
2448
2505
  }
2449
2506
  for (const run of nestedRuns(registry.children)) {
2450
- if (run.state !== "running" && run.state !== "queued") continue;
2507
+ if (!isNestedControlDescendant(run) || (run.state !== "running" && run.state !== "queued")) continue;
2451
2508
  const nestedAsyncDir = run.asyncDir ?? resolveNestedAsyncDir(config.nestedRoute.rootRunId, run);
2452
2509
  if (!nestedAsyncDir) continue;
2453
2510
  try {
@@ -2478,7 +2535,7 @@ async function runSubagent(
2478
2535
  return;
2479
2536
  }
2480
2537
  for (const run of nestedRuns(registry.children)) {
2481
- if (run.state !== "running" && run.state !== "queued") continue;
2538
+ if (!isNestedControlDescendant(run) || (run.state !== "running" && run.state !== "queued")) continue;
2482
2539
  const nestedAsyncDir = run.asyncDir ?? resolveNestedAsyncDir(config.nestedRoute.rootRunId, run);
2483
2540
  if (!nestedAsyncDir) continue;
2484
2541
  try {
@@ -2534,6 +2591,7 @@ async function runSubagent(
2534
2591
  }
2535
2592
  const appendedSteps = requests.flatMap((request) => request.steps);
2536
2593
  steps.push(...appendedSteps);
2594
+ flatSteps.push(...flattenSteps(appendedSteps));
2537
2595
  const now = Date.now();
2538
2596
  const pendingAppends = countPendingChainAppendRequests(asyncDir);
2539
2597
  const added = appendRunnerStepsToStatus({
@@ -2567,9 +2625,66 @@ async function runSubagent(
2567
2625
  setOptionalProperty(groupNode, "acceptanceStatus", acceptance?.status ?? groupNode.acceptanceStatus);
2568
2626
  };
2569
2627
 
2628
+ const EXTERNAL_GIT_PROBE_MIN_INTERVAL_MS = 2_000;
2629
+ type ExternalActivityEvidence = {
2630
+ cwd?: string;
2631
+ lastStreamActivityAt?: number;
2632
+ fingerprint?: string;
2633
+ probeInFlight?: Promise<void>;
2634
+ lastProbeStartedAt?: number;
2635
+ };
2636
+ const externalActivityEvidence = new Map<number, ExternalActivityEvidence>();
2637
+ const gitProbesByCwd = new Map<string, Promise<string | undefined>>();
2638
+ let periodicGitProbeFailure: { index: number; error: Error; message: string } | undefined;
2639
+ const reportedGitProbeErrors = new Set<string>();
2640
+ const reportGitProbeError = (externalCwd: string, error: unknown): void => {
2641
+ if (reportedGitProbeErrors.has(externalCwd)) return;
2642
+ reportedGitProbeErrors.add(externalCwd);
2643
+ const detail = error instanceof Error ? error.message : String(error);
2644
+ console.error(`[pi-subagents] Git activity evidence unavailable for '${externalCwd.slice(-300)}'; check the cwd and Git installation: ${detail.slice(0, 500)}`);
2645
+ };
2646
+ const readSharedGitFingerprint = (externalCwd: string): Promise<string | undefined> => {
2647
+ const inFlight = gitProbesByCwd.get(externalCwd);
2648
+ if (inFlight) return inFlight;
2649
+ const probe = readGitFingerprint(externalCwd, runStopSignal, (error) => reportGitProbeError(externalCwd, error)).finally(() => gitProbesByCwd.delete(externalCwd));
2650
+ gitProbesByCwd.set(externalCwd, probe);
2651
+ return probe;
2652
+ };
2653
+ const recordPeriodicGitProbeFailure = (index: number, error: unknown): void => {
2654
+ if (periodicGitProbeFailure) return;
2655
+ const cause = error instanceof Error ? error : new Error(String(error));
2656
+ const message = `PROCESS_TREE_UNVERIFIED: ${cause.message}`;
2657
+ periodicGitProbeFailure = { index, error: cause, message };
2658
+ statusPayload.error = message;
2659
+ const step = statusPayload.steps[index];
2660
+ if (step) step.error = message;
2661
+ statusPayload.lastUpdate = Date.now();
2662
+ writeStatusPayload();
2663
+ appendJsonl(eventsPath, JSON.stringify({
2664
+ type: "subagent.run.process_tree_unverified",
2665
+ ts: statusPayload.lastUpdate,
2666
+ runId: id,
2667
+ index,
2668
+ code: "PROCESS_TREE_UNVERIFIED",
2669
+ message,
2670
+ }));
2671
+ };
2672
+ const prepareExternalActivity = async (index: number, externalCwd: string, signal: AbortSignal): Promise<void> => {
2673
+ if (!controlConfig.enabled) return;
2674
+ const resolvedCwd = path.resolve(externalCwd);
2675
+ const evidence: ExternalActivityEvidence = { cwd: resolvedCwd, lastProbeStartedAt: performance.now() };
2676
+ externalActivityEvidence.set(index, evidence);
2677
+ evidence.fingerprint = await readGitFingerprint(resolvedCwd, signal, (error) => reportGitProbeError(resolvedCwd, error));
2678
+ };
2679
+ const recordExternalStreamActivity = (index: number): void => {
2680
+ const evidence = externalActivityEvidence.get(index) ?? {};
2681
+ externalActivityEvidence.set(index, evidence);
2682
+ evidence.lastStreamActivityAt = Date.now();
2683
+ };
2570
2684
  const stepOutputActivityAt = (index: number): number => {
2571
2685
  const step = statusPayload.steps[index];
2572
2686
  let lastActivityAt = step?.lastActivityAt ?? step?.startedAt ?? overallStartTime;
2687
+ lastActivityAt = Math.max(lastActivityAt, externalActivityEvidence.get(index)?.lastStreamActivityAt ?? 0);
2573
2688
  const outputPath = path.join(asyncDir, `output-${index}.log`);
2574
2689
  try {
2575
2690
  lastActivityAt = Math.max(lastActivityAt, fs.statSync(outputPath).mtimeMs);
@@ -2861,7 +2976,10 @@ async function runSubagent(
2861
2976
  const applySteerDelivery = (requestId: string, index: number, delivery: { state: "delivered" | "queued" | "failed"; message: string }): void => {
2862
2977
  const lifecycle = steeringStatus(statusPayload);
2863
2978
  const request = lifecycle.recent.find((candidate) => candidate.id === requestId);
2864
- if (!request || !request.targets.some((target) => target.index === index)) return;
2979
+ const target = request?.targets.find((candidate) => candidate.index === index);
2980
+ if (!request || !target) return;
2981
+ if (target.state === "delivered" || target.state === "late" || target.state === "failed") return;
2982
+ if (target.state === delivery.state) return;
2865
2983
  const late = fs.existsSync(steeringMarkerPath(requestId));
2866
2984
  const now = Date.now();
2867
2985
  if (delivery.state === "delivered") {
@@ -2914,6 +3032,7 @@ async function runSubagent(
2914
3032
  const updateStepFromChildEvent = (flatIndex: number, event: ChildEvent): void => {
2915
3033
  const step = statusPayload.steps[flatIndex];
2916
3034
  if (!step) return;
3035
+ const previousActivityState = step.activityState;
2917
3036
  const now = Date.now();
2918
3037
  statusPayload.currentStep = flatIndex;
2919
3038
  if (isChildWatchdogStatusEvent(event)) {
@@ -2933,7 +3052,7 @@ async function runSubagent(
2933
3052
  return;
2934
3053
  }
2935
3054
  if (event.type === "message_end") {
2936
- const next = applyChildWatchdogMessage(step.watchdog, event.message, now);
3055
+ const next = applyChildWatchdogMessage(step.watchdog, event.message);
2937
3056
  if (next) step.watchdog = next;
2938
3057
  if (next && (event.message as { role?: unknown } | undefined)?.role === "custom") {
2939
3058
  statusPayload.lastUpdate = now;
@@ -3048,6 +3167,10 @@ async function runSubagent(
3048
3167
  appendRecentStepOutput(step, stripAcceptanceReport(extractTextFromContent(event.message.content)).split("\n").slice(-10));
3049
3168
  step.turnCount = (step.turnCount ?? 0) + 1;
3050
3169
  const usage = event.message.usage;
3170
+ if (config.usageBudget) {
3171
+ const known = (value: unknown) => typeof value === "number" && Number.isFinite(value) && value >= 0;
3172
+ if (!known(usage?.input ?? usage?.inputTokens) || !known(usage?.output ?? usage?.outputTokens)) continuationUsageUncertain = true;
3173
+ }
3051
3174
  if (usage) {
3052
3175
  const input = usage.input ?? usage.inputTokens ?? 0;
3053
3176
  const output = usage.output ?? usage.outputTokens ?? 0;
@@ -3067,9 +3190,10 @@ async function runSubagent(
3067
3190
  statusPayload.lastActivityAt = now;
3068
3191
  statusPayload.lastUpdate = now;
3069
3192
  maybeEmitActiveLongRunning(flatIndex, now);
3070
- writeStatusPayload(false);
3193
+ // A sibling may keep aggregate attention unchanged; publish this step's transition.
3194
+ writeStatusPayload(step.activityState !== previousActivityState);
3071
3195
  };
3072
- const updateRunnerActivityState = (now: number): boolean => {
3196
+ const updateRunnerActivityState = (now: number, skipExternalProbeIndex?: number): boolean => {
3073
3197
  if (!controlConfig.enabled) return false;
3074
3198
  let changed = false;
3075
3199
  let runLastActivityAt = statusPayload.lastActivityAt ?? overallStartTime;
@@ -3086,12 +3210,35 @@ async function runSubagent(
3086
3210
  config: controlConfig,
3087
3211
  startedAt: step.startedAt ?? overallStartTime,
3088
3212
  lastActivityAt,
3089
- turnCount: step.turnCount,
3213
+ turnCount: flatSteps[index]?.runner?.type === "external-cli" ? 1 : step.turnCount,
3090
3214
  currentTool: step.currentTool,
3091
3215
  thinking: step.thinking,
3092
3216
  now,
3093
3217
  }));
3094
3218
  if (idleState === "needs_attention") {
3219
+ const evidence = externalActivityEvidence.get(index);
3220
+ if (index !== skipExternalProbeIndex && evidence?.cwd && evidence.fingerprint) {
3221
+ if (evidence.probeInFlight) continue;
3222
+ if (performance.now() - (evidence.lastProbeStartedAt ?? 0) >= EXTERNAL_GIT_PROBE_MIN_INTERVAL_MS) {
3223
+ evidence.lastProbeStartedAt = performance.now();
3224
+ const baseline = evidence.fingerprint;
3225
+ evidence.probeInFlight = readSharedGitFingerprint(evidence.cwd).then((fingerprint) => {
3226
+ if (requiredStatusStep(statusPayload, index).status !== "running") return;
3227
+ if (fingerprint && fingerprint !== baseline) {
3228
+ evidence.fingerprint = fingerprint;
3229
+ evidence.lastStreamActivityAt = Date.now();
3230
+ updateRunnerActivityState(Date.now());
3231
+ } else {
3232
+ updateRunnerActivityState(Date.now(), index);
3233
+ }
3234
+ }).catch((error: unknown) => {
3235
+ recordPeriodicGitProbeFailure(index, error);
3236
+ }).finally(() => {
3237
+ delete evidence.probeInFlight;
3238
+ });
3239
+ continue;
3240
+ }
3241
+ }
3095
3242
  const previous = step.activityState;
3096
3243
  step.activityState = "needs_attention";
3097
3244
  if (previous !== "needs_attention") {
@@ -3139,10 +3286,59 @@ async function runSubagent(
3139
3286
  activityTimer.unref?.();
3140
3287
  }
3141
3288
 
3289
+ const publishSetupUnknown = (progress: WorktreeSetupProgress): void => {
3290
+ if (!progress.unknown) return;
3291
+ const proof = {
3292
+ version: 1 as const, state: "unknown" as const, runId: id,
3293
+ runnerProcessInstanceId: config.runnerProcessInstanceId ?? "unknown",
3294
+ reason: "process-tree-unverified" as const,
3295
+ diagnostic: `Worktree setup settlement unknown: ${progress.unknown}; manual reconciliation required; ${parallelHandoffPath(asyncDir)}`,
3296
+ };
3297
+ statusPayload.processTerminal = proof;
3298
+ // Publish the sticky proof independently of in-process child writer counts.
3299
+ writeAtomicJson(processTerminalPath(asyncDir), proof);
3300
+ };
3301
+ const finalizeWorktree = async (setup: WorktreeSetup, stepIndex: number, flatStartIndex: number, action: () => void, deadlineAt?: number): Promise<void> => {
3302
+ let admitted = false;
3303
+ try {
3304
+ await Promise.all([...externalActivityEvidence.values()].map((evidence) => evidence.probeInFlight).filter((probe): probe is Promise<void> => probe !== undefined));
3305
+ if (periodicGitProbeFailure) throw periodicGitProbeFailure.error;
3306
+ await withWorktreeTransaction(() => {
3307
+ if (deadlineAt !== undefined && Date.now() >= deadlineAt) throw new Error("Run deadline expired before worktree cleanup");
3308
+ admitted = true;
3309
+ action();
3310
+ });
3311
+ }
3312
+ catch (error) {
3313
+ if (admitted) throw error;
3314
+ const reason = `Worktree finalization retained; manual reconciliation required: ${error instanceof Error ? error.message : String(error)}`;
3315
+ statusPayload.parallelHandoff = writeParallelHandoffGroup({
3316
+ manifestPath: parallelHandoffPath(asyncDir), runId: id,
3317
+ mode: (config.resultMode ?? statusPayload.mode) === "parallel" ? "parallel" : (config.resultMode ?? statusPayload.mode) === "single" ? "single" : "chain",
3318
+ source: "async", cwd, stepIndex, flatStartIndex, setup, diffs: [], results: [],
3319
+ cleanup: { state: "partial", pruned: false, errors: [reason], tasks: setup.worktrees.map((worktree) => ({
3320
+ index: worktree.index, path: worktree.path, branch: worktree.branch, provider: worktree.provider, naming: worktree.naming,
3321
+ worktreeRemoved: false, branchRemoved: false, preserved: true, reason,
3322
+ })) },
3323
+ });
3324
+ previousOutput = [previousOutput, reason, formatParallelHandoffReference(statusPayload.parallelHandoff)].filter(Boolean).join("\n\n");
3325
+ writeStatusPayload();
3326
+ }
3327
+ };
3328
+ const cleanupRemainingWorktree = (setup: WorktreeSetup, stepIndex: number, flatStartIndex: number) => finalizeWorktree(setup, stepIndex, flatStartIndex, () => {
3329
+ const cleanup = cleanupWorktrees(setup);
3330
+ statusPayload.parallelHandoff = writeParallelHandoffGroup({
3331
+ manifestPath: parallelHandoffPath(asyncDir), runId: id,
3332
+ mode: (config.resultMode ?? statusPayload.mode) === "parallel" ? "parallel" : (config.resultMode ?? statusPayload.mode) === "single" ? "single" : "chain",
3333
+ source: "async", cwd, stepIndex, flatStartIndex, setup, diffs: [], results: [], cleanup,
3334
+ });
3335
+ writeStatusPayload();
3336
+ }, config.deadlineAt);
3142
3337
  const interruptRunner = () => {
3143
3338
  consumeInterruptRequest(asyncDir);
3144
3339
  if (interrupted || statusPayload.state !== "running") return;
3145
3340
  interrupted = true;
3341
+ setupInterruptController.abort();
3146
3342
  const now = Date.now();
3147
3343
  statusPayload.state = "paused";
3148
3344
  currentActivityState = undefined;
@@ -3167,16 +3363,17 @@ async function runSubagent(
3167
3363
  interruptActiveChildren();
3168
3364
  };
3169
3365
  const stopRunner = () => {
3170
- if (stopped || timedOut || interrupted || statusPayload.state !== "running") return;
3366
+ if (stopped || timedOut || (statusPayload.state !== "running" && statusPayload.state !== "paused")) return;
3171
3367
  stopped = true;
3368
+ interrupted = false;
3172
3369
  const now = Date.now();
3173
3370
  statusPayload.stopped = true;
3174
3371
  statusPayload.error = stopMessage;
3175
3372
  currentActivityState = undefined;
3176
3373
  delete statusPayload.activityState;
3177
3374
  statusPayload.lastUpdate = now;
3178
- for (const step of statusPayload.steps) {
3179
- if (step.status !== "running" && step.status !== "pending") continue;
3375
+ for (const [index, step] of statusPayload.steps.entries()) {
3376
+ if (step.status !== "running" && step.status !== "pending" && step.status !== "paused") continue;
3180
3377
  step.status = "stopped";
3181
3378
  step.error = stopMessage;
3182
3379
  step.exitCode = 1;
@@ -3185,6 +3382,8 @@ async function runSubagent(
3185
3382
  step.endedAt = now;
3186
3383
  step.durationMs = step.startedAt ? now - step.startedAt : 0;
3187
3384
  step.lastActivityAt = now;
3385
+ const result = results[index];
3386
+ if (result?.interrupted) results[index] = { ...result, output: stopMessage, error: stopMessage, exitCode: 1, success: false, interrupted: false, stopped: true };
3188
3387
  }
3189
3388
  writeStatusPayload();
3190
3389
  appendJsonl(eventsPath, JSON.stringify({
@@ -3256,6 +3455,30 @@ async function runSubagent(
3256
3455
  const remainingMs = Math.max(0, config.deadlineAt - Date.now());
3257
3456
  timeoutTimer = setTimeout(timeoutRunner, remainingMs);
3258
3457
  timeoutTimer.unref?.();
3458
+ // Route the pre-deadline checkpoint like any external steer so its lifecycle records the receipt.
3459
+ const checkpointBeforeDeadlineMs = config.checkpointBeforeDeadlineMs;
3460
+ const checkpointDelayMs = checkpointBeforeDeadlineMs === undefined || !Number.isInteger(checkpointBeforeDeadlineMs) || checkpointBeforeDeadlineMs <= 0
3461
+ ? undefined
3462
+ : remainingMs - checkpointBeforeDeadlineMs;
3463
+ if (checkpointDelayMs !== undefined && checkpointDelayMs >= 1_000) {
3464
+ const deadlineAt = config.deadlineAt;
3465
+ checkpointTimer = setTimeout(() => {
3466
+ checkpointTimer = undefined;
3467
+ if (timedOut || stopped || interrupted) return;
3468
+ if (!statusPayload.steps.some((step) => step.status === "running")) return;
3469
+ const now = Date.now();
3470
+ const seconds = Math.round(Math.max(0, deadlineAt - now) / 1000);
3471
+ deliverSteerRequest({
3472
+ type: "steer",
3473
+ id: `deadline-checkpoint-${now}`,
3474
+ ts: now,
3475
+ mode: "steer",
3476
+ source: "deadline-checkpoint",
3477
+ message: `Deadline checkpoint from the runner: this run is killed in about ${seconds} seconds. Finish the current tool call only, then stop and reply with a handoff: changed files, build/test state, remaining work, and commit/PR state. Do not start new work.`,
3478
+ });
3479
+ }, checkpointDelayMs);
3480
+ checkpointTimer.unref?.();
3481
+ }
3259
3482
  }
3260
3483
  appendJsonl(
3261
3484
  eventsPath,
@@ -3301,14 +3524,7 @@ async function runSubagent(
3301
3524
  const thinkingOverride = step.thinkingOverrides?.[itemIndex];
3302
3525
  const model = thinkingOverride ? applyThinkingSuffix(step.parallel.model, thinkingOverride, true) : step.parallel.model;
3303
3526
  const configThinking = thinkingOverride ? thinkingOverride : step.parallel.thinking;
3304
- const candidates = step.parallel.modelCandidates !== undefined
3305
- ? step.parallel.modelCandidates.length > 0
3306
- ? step.parallel.modelCandidates.map((candidate) => thinkingOverride ? applyThinkingSuffix(candidate, thinkingOverride, true) ?? candidate : candidate)
3307
- : [undefined]
3308
- : model ? [model] : [undefined];
3309
- for (const candidate of candidates) {
3310
- assertThinkingWithinCeiling({ model: candidate, configThinking, ceiling: step.parallel.thinkingCeiling, agent: step.parallel.agent, runId: id });
3311
- }
3527
+ assertThinkingWithinCeiling({ model, configThinking, ceiling: step.parallel.thinkingCeiling, agent: step.parallel.agent, runId: id });
3312
3528
  }
3313
3529
  if (materialized.collectedOnEmpty) await validateDynamicCollection(step.collect.outputSchema, materialized.collectedOnEmpty);
3314
3530
  if (!config.runFanoutBudget) throw new Error("Async runner is missing its run fan-out budget identity.");
@@ -3376,14 +3592,14 @@ async function runSubagent(
3376
3592
  cwd,
3377
3593
  signal: combinedAbortSignal([timeoutAbortController.signal, stopAbortController.signal]),
3378
3594
  abortMessage: stopAbortController.signal.aborted ? stopMessage : timeoutMessage ?? "Subagent timed out.",
3379
- reportOptional: isAgentContractV1(step.agentContract),
3595
+ reportOptional: isAgentContract(step.agentContract),
3380
3596
  }))
3381
3597
  : undefined;
3382
3598
  const groupStopped = stopped || stopAbortController.signal.aborted;
3383
3599
  const groupTimedOut = !groupStopped && (timedOut || timeoutAbortController.signal.aborted);
3384
3600
  const effectiveGroupAcceptance = groupTimedOut || groupStopped ? undefined : groupAcceptance;
3385
3601
  if (placeholder && effectiveGroupAcceptance) placeholder.acceptance = effectiveGroupAcceptance;
3386
- const groupAcceptanceFailure = effectiveGroupAcceptance && (!isAgentContractV1(step.agentContract) || step.gateOn === "acceptance") ? acceptanceFailureMessage(effectiveGroupAcceptance) : undefined;
3602
+ const groupAcceptanceFailure = effectiveGroupAcceptance && (!isAgentContract(step.agentContract) || step.gateOn === "acceptance") ? acceptanceFailureMessage(effectiveGroupAcceptance) : undefined;
3387
3603
  if (groupTimedOut || groupStopped || groupAcceptanceFailure) {
3388
3604
  const errorMessage = groupStopped ? stopMessage : groupTimedOut ? timeoutMessage ?? "Subagent timed out." : groupAcceptanceFailure!;
3389
3605
  statusPayload.state = groupStopped ? "stopped" : "failed";
@@ -3441,10 +3657,6 @@ async function runSubagent(
3441
3657
  ...(thinkingOverride ? {
3442
3658
  ...(model ? { model } : {}),
3443
3659
  ...(thinking ? { thinking } : {}),
3444
- ...(step.parallel.modelCandidates ? { modelCandidates: step.parallel.modelCandidates.flatMap((candidate) => {
3445
- const resolved = applyThinkingSuffix(candidate, thinkingOverride, true);
3446
- return resolved ? [resolved] : [];
3447
- }) } : {}),
3448
3660
  } : {}),
3449
3661
  structuredOutputSchema: step.parallel.structuredOutputSchema ?? step.parallel.structuredOutput?.schema,
3450
3662
  });
@@ -3471,7 +3683,7 @@ async function runSubagent(
3471
3683
  ...(task.contextLimit !== undefined ? { contextLimit: task.contextLimit } : {}),
3472
3684
  ...(task.thinking ? { thinking: task.thinking } : {}),
3473
3685
  ...(task.thinkingCeiling ? { thinkingCeiling: task.thinkingCeiling } : {}),
3474
- ...(task.modelCandidates && task.modelCandidates.length > 0 ? { attemptedModels: task.modelCandidates } : task.model ? { attemptedModels: [task.model] } : {}),
3686
+ ...(task.requestedModel ? { requestedModel: task.requestedModel } : {}),
3475
3687
  recentTools: [],
3476
3688
  recentOutput: [],
3477
3689
  });
@@ -3585,10 +3797,12 @@ async function runSubagent(
3585
3797
  nestedRoute: config.nestedRoute,
3586
3798
  capabilityCeiling: config.capabilityCeiling,
3587
3799
  runFanoutBudget: config.runFanoutBudget,
3800
+ hostAvailableBuiltins: config.hostAvailableBuiltins,
3588
3801
  registerInterrupt: (interrupt) => registerStepInterrupt(fi, interrupt),
3589
3802
  registerTimeout: (interrupt) => registerStepTimeout(fi, interrupt),
3590
3803
  registerStop: (stop) => registerStepStop(fi, stop),
3591
3804
  registerSteer: (steer) => registerStepSteer(fi, steer),
3805
+ onSteerOutcome: (request, delivery) => applySteerDelivery(request.id, fi, delivery),
3592
3806
  timeoutSignal: timeoutAbortController.signal,
3593
3807
  stopSignal: stopAbortController.signal,
3594
3808
  trackedMutationEvidenceForCompletionGuard: false,
@@ -3598,15 +3812,18 @@ async function runSubagent(
3598
3812
  onAttemptStart: (attempt) => updateStepModel(fi, attempt.model, attempt.thinking, attempt.contextLimit),
3599
3813
  onChildEvent: (event) => updateStepFromChildEvent(fi, event),
3600
3814
  onExternalProcess: (process) => updateExternalProcess(fi, process),
3815
+ prepareExternalActivity: (externalCwd, signal) => prepareExternalActivity(fi, externalCwd, signal),
3816
+ onExternalStreamActivity: () => recordExternalStreamActivity(fi),
3601
3817
  onExternalJob: (externalJob) => updateExternalJob(fi, externalJob),
3602
3818
  skipAcceptance: () => timedOut || stopped || childStopRequests.has(fi),
3603
- usageBudgetExhausted: () => refreshUsageBudget()?.exhausted === true,
3819
+ usageBudgetExhausted: continuationUsageBudgetExhausted,
3820
+ usageBudget: config.usageBudget,
3604
3821
  orcaProgressTab,
3605
3822
  }), config.deadlineAt);
3606
3823
  const taskEndTime = Date.now();
3607
3824
  const childInterrupted = singleResult.interrupted === true;
3608
3825
  const childStopped = singleResult.stopped === true;
3609
- requiredStatusStep(statusPayload, fi).status = stopped || childStopped ? "stopped" : timedOut ? "failed" : childInterrupted ? "paused" : singleResult.exitCode === 0 ? "complete" : "failed";
3826
+ requiredStatusStep(statusPayload, fi).status = stopped || childStopped ? "stopped" : timedOut ? "failed" : childInterrupted ? "paused" : singleResult.execution?.status === "partial" ? "partial" : singleResult.exitCode === 0 ? "complete" : "failed";
3610
3827
  requiredStatusStep(statusPayload, fi).endedAt = taskEndTime;
3611
3828
  requiredStatusStep(statusPayload, fi).durationMs = taskEndTime - taskStartTime;
3612
3829
  requiredStatusStep(statusPayload, fi).exitCode = stopped || childStopped ? 1 : timedOut ? 1 : childInterrupted ? 0 : singleResult.exitCode;
@@ -3619,8 +3836,7 @@ async function runSubagent(
3619
3836
  setOptionalProperty(requiredStatusStep(statusPayload, fi), "sessionName", singleResult.sessionName);
3620
3837
  setOptionalProperty(requiredStatusStep(statusPayload, fi), "model", singleResult.model);
3621
3838
  setOptionalProperty(requiredStatusStep(statusPayload, fi), "thinking", resolveEffectiveThinking(singleResult.model, requiredStatusStep(statusPayload, fi).thinking));
3622
- setOptionalProperty(requiredStatusStep(statusPayload, fi), "attemptedModels", singleResult.attemptedModels);
3623
- setOptionalProperty(requiredStatusStep(statusPayload, fi), "modelAttempts", singleResult.modelAttempts);
3839
+ setOptionalProperty(requiredStatusStep(statusPayload, fi), "requestedModel", singleResult.requestedModel);
3624
3840
  setOptionalProperty(requiredStatusStep(statusPayload, fi), "contextOverflow", singleResult.contextOverflow);
3625
3841
  setOptionalProperty(requiredStatusStep(statusPayload, fi), "totalCost", singleResult.totalCost);
3626
3842
  if (singleResult.totalCost) {
@@ -3679,7 +3895,7 @@ async function runSubagent(
3679
3895
  output: pr.output,
3680
3896
  outputState: pr.outputState,
3681
3897
  error: pr.error,
3682
- success: pr.stopped !== true && pr.interrupted !== true && pr.exitCode === 0,
3898
+ success: pr.stopped !== true && pr.interrupted !== true && pr.exitCode === 0 && pr.execution?.status !== "partial",
3683
3899
  exitCode: pr.interrupted === true ? 0 : pr.exitCode,
3684
3900
  skipped: pr.skipped,
3685
3901
  interrupted: pr.interrupted,
@@ -3691,12 +3907,13 @@ async function runSubagent(
3691
3907
  intercomTarget: pr.intercomTarget,
3692
3908
  model: pr.model,
3693
3909
  thinking: pr.thinking,
3694
- attemptedModels: pr.attemptedModels,
3695
- modelAttempts: pr.modelAttempts,
3910
+ requestedModel: pr.requestedModel,
3696
3911
  contextOverflow: pr.contextOverflow,
3697
3912
  totalCost: pr.totalCost,
3698
3913
  usage: pr.usage,
3699
3914
  artifactPaths: pr.artifactPaths,
3915
+ outputSaveError: pr.outputSaveError,
3916
+ artifactOutputSaveFailed: pr.artifactOutputSaveFailed,
3700
3917
  transcriptPath: pr.transcriptPath,
3701
3918
  transcriptError: pr.transcriptError,
3702
3919
  effects: pr.effects,
@@ -3718,7 +3935,7 @@ async function runSubagent(
3718
3935
  const failures = parallelResults.filter((result) => result.exitCode !== 0 && result.exitCode !== -1);
3719
3936
  const acceptanceFailures = parallelResults
3720
3937
  .map((result, originalIndex) => ({ result, originalIndex, task: dynamicSteps[originalIndex] }))
3721
- .filter(({ result, task }) => isAgentContractV1(task?.agentContract ?? step.agentContract) && task?.gateOn === "acceptance" && result.acceptance?.status === "rejected");
3938
+ .filter(({ result, task }) => isAgentContract(task?.agentContract ?? step.agentContract) && task?.gateOn === "acceptance" && result.acceptance?.status === "rejected");
3722
3939
  if (acceptanceFailures.length > 0) {
3723
3940
  const message = acceptanceFailures
3724
3941
  .map(({ result, originalIndex }) => `Dynamic item ${originalIndex + 1} (${result.agent}, key ${materialized.items[originalIndex]?.key ?? originalIndex}) acceptance rejected: ${(result.acceptance ? acceptanceFailureMessage(result.acceptance) : undefined) ?? "acceptance rejected"}`)
@@ -3748,13 +3965,13 @@ async function runSubagent(
3748
3965
  cwd,
3749
3966
  signal: combinedAbortSignal([timeoutAbortController.signal, stopAbortController.signal]),
3750
3967
  abortMessage: stopAbortController.signal.aborted ? stopMessage : timeoutMessage ?? "Subagent timed out.",
3751
- reportOptional: isAgentContractV1(step.agentContract),
3968
+ reportOptional: isAgentContract(step.agentContract),
3752
3969
  }))
3753
3970
  : undefined;
3754
3971
  const groupStopped = stopped || stopAbortController.signal.aborted;
3755
3972
  const groupTimedOut = !groupStopped && (timedOut || timeoutAbortController.signal.aborted);
3756
3973
  const effectiveGroupAcceptance = groupTimedOut || groupStopped ? undefined : groupAcceptance;
3757
- const groupAcceptanceFailure = effectiveDynamicGroupAcceptance.explicit && effectiveGroupAcceptance && (!isAgentContractV1(step.agentContract) || step.gateOn === "acceptance") ? acceptanceFailureMessage(effectiveGroupAcceptance) : undefined;
3974
+ const groupAcceptanceFailure = effectiveDynamicGroupAcceptance.explicit && effectiveGroupAcceptance && (!isAgentContract(step.agentContract) || step.gateOn === "acceptance") ? acceptanceFailureMessage(effectiveGroupAcceptance) : undefined;
3758
3975
  const groupError = groupStopped ? stopMessage : groupTimedOut ? timeoutMessage ?? "Subagent timed out." : groupAcceptanceFailure;
3759
3976
  markDynamicGraphGroup(stepIndex, groupError ? groupStopped ? "stopped" : "failed" : "completed", groupError, effectiveGroupAcceptance);
3760
3977
  if (groupError) {
@@ -3833,7 +4050,9 @@ async function runSubagent(
3833
4050
  break;
3834
4051
  }
3835
4052
  try {
3836
- worktreeSetup = createWorktrees(cwd, `${id}-s${stepIndex}`, group.parallel.length, omitUndefinedProperties({
4053
+ worktreeSetup = await createWorktrees(cwd, `${id}-s${stepIndex}`, group.parallel.length, omitUndefinedProperties({
4054
+ signal: setupSignal,
4055
+ deadlineAt: config.deadlineAt,
3837
4056
  agents: group.parallel.map((task) => task.agent),
3838
4057
  labels: group.parallel.map((task) => task.lane?.key ?? config.workflowKey ?? task.outputName ?? task.label),
3839
4058
  tasks: group.parallel.map((task) => task.task),
@@ -3844,9 +4063,10 @@ async function runSubagent(
3844
4063
  ? omitUndefinedProperties({ hookPath: config.worktreeSetupHook, timeoutMs: config.worktreeSetupHookTimeoutMs })
3845
4064
  : undefined,
3846
4065
  baseDir: config.worktreeBaseDir,
3847
- beforeCreate: (plannedSetup) => {
3848
- for (const worktree of plannedSetup.worktrees) setStatusWorktreeReference(requiredStatusStep(statusPayload, groupStartFlatIndex + worktree.index), worktree);
3849
- const pendingHandoff = writePendingParallelHandoff({
4066
+ onProgress: (progress) => {
4067
+ publishSetupUnknown(progress);
4068
+ for (const worktree of progress.setup.worktrees) setStatusWorktreeReference(requiredStatusStep(statusPayload, groupStartFlatIndex + worktree.index), worktree);
4069
+ const pendingHandoff = writeWorktreeSetupHandoff({
3850
4070
  manifestPath: parallelHandoffPath(asyncDir),
3851
4071
  runId: id,
3852
4072
  mode: (config.resultMode ?? statusPayload.mode) === "parallel" ? "parallel" : "chain",
@@ -3854,16 +4074,25 @@ async function runSubagent(
3854
4074
  cwd,
3855
4075
  stepIndex,
3856
4076
  flatStartIndex: groupStartFlatIndex,
3857
- setup: plannedSetup,
4077
+ progress,
3858
4078
  laneBindings: handoffWorkflowKey || config.lane ? [{ index: groupStartFlatIndex, taskIndex: 0, ...(handoffWorkflowKey ? { workflowKey: handoffWorkflowKey } : {}), ...(handoffChildRunId ? { runId: handoffChildRunId } : {}), ...(config.lane ? { lane: config.lane } : {}) }] : undefined,
3859
4079
  });
4080
+ if (!pendingHandoff) return;
3860
4081
  statusPayload.parallelHandoff = pendingHandoff;
3861
4082
  statusPayload.lastUpdate = Date.now();
3862
4083
  writeStatusPayload();
3863
4084
  },
3864
4085
  }));
4086
+ if (config.deadlineAt !== undefined && Date.now() >= config.deadlineAt) timeoutRunner();
4087
+ if (setupSignal.aborted) throw new Error(stopped ? stopMessage : timedOut ? timeoutMessage ?? "Subagent timed out." : "Subagent paused during worktree setup.");
3865
4088
  } catch (error) {
4089
+ if (worktreeSetup) await cleanupRemainingWorktree(worktreeSetup, stepIndex, groupStartFlatIndex);
4090
+ if (config.deadlineAt !== undefined && Date.now() >= config.deadlineAt) timeoutRunner();
3866
4091
  const setupError = error instanceof Error ? error.message : String(error);
4092
+ if (error instanceof WorktreeSetupError) publishSetupUnknown(error.snapshot);
4093
+ for (let index = groupStartFlatIndex; index < groupStartFlatIndex + group.parallel.length; index++) {
4094
+ if (childStopRequests.has(index)) markChildStopped(index);
4095
+ }
3867
4096
  const failedAt = Date.now();
3868
4097
  markParallelGroupSetupFailure({
3869
4098
  statusPayload,
@@ -3984,10 +4213,12 @@ async function runSubagent(
3984
4213
  nestedRoute: config.nestedRoute,
3985
4214
  capabilityCeiling: config.capabilityCeiling,
3986
4215
  runFanoutBudget: config.runFanoutBudget,
4216
+ hostAvailableBuiltins: config.hostAvailableBuiltins,
3987
4217
  registerInterrupt: (interrupt) => registerStepInterrupt(fi, interrupt),
3988
4218
  registerTimeout: (interrupt) => registerStepTimeout(fi, interrupt),
3989
4219
  registerStop: (stop) => registerStepStop(fi, stop),
3990
4220
  registerSteer: (steer) => registerStepSteer(fi, steer),
4221
+ onSteerOutcome: (request, delivery) => applySteerDelivery(request.id, fi, delivery),
3991
4222
  timeoutSignal: timeoutAbortController.signal,
3992
4223
  stopSignal: stopAbortController.signal,
3993
4224
  trackedMutationEvidenceForCompletionGuard: Boolean(worktreeSetup),
@@ -3997,9 +4228,12 @@ async function runSubagent(
3997
4228
  onAttemptStart: (attempt) => updateStepModel(fi, attempt.model, attempt.thinking, attempt.contextLimit),
3998
4229
  onChildEvent: (event) => updateStepFromChildEvent(fi, event),
3999
4230
  onExternalProcess: (process) => updateExternalProcess(fi, process),
4231
+ prepareExternalActivity: (externalCwd, signal) => prepareExternalActivity(fi, externalCwd, signal),
4232
+ onExternalStreamActivity: () => recordExternalStreamActivity(fi),
4000
4233
  onExternalJob: (externalJob) => updateExternalJob(fi, externalJob),
4001
4234
  skipAcceptance: () => timedOut || stopped || childStopRequests.has(fi),
4002
- usageBudgetExhausted: () => refreshUsageBudget()?.exhausted === true,
4235
+ usageBudgetExhausted: continuationUsageBudgetExhausted,
4236
+ usageBudget: config.usageBudget,
4003
4237
  orcaProgressTab,
4004
4238
  }), config.deadlineAt);
4005
4239
  if (task.sessionFile) {
@@ -4011,7 +4245,7 @@ async function runSubagent(
4011
4245
  const childInterrupted = singleResult.interrupted === true;
4012
4246
  const childStopped = singleResult.stopped === true;
4013
4247
 
4014
- requiredStatusStep(statusPayload, fi).status = stopped || childStopped ? "stopped" : timedOut ? "failed" : childInterrupted ? "paused" : singleResult.exitCode === 0 ? "complete" : "failed";
4248
+ requiredStatusStep(statusPayload, fi).status = stopped || childStopped ? "stopped" : timedOut ? "failed" : childInterrupted ? "paused" : singleResult.execution?.status === "partial" ? "partial" : singleResult.exitCode === 0 ? "complete" : "failed";
4015
4249
  requiredStatusStep(statusPayload, fi).endedAt = taskEndTime;
4016
4250
  requiredStatusStep(statusPayload, fi).durationMs = taskDuration;
4017
4251
  requiredStatusStep(statusPayload, fi).exitCode = stopped || childStopped ? 1 : timedOut ? 1 : childInterrupted ? 0 : singleResult.exitCode;
@@ -4024,8 +4258,7 @@ async function runSubagent(
4024
4258
  setOptionalProperty(requiredStatusStep(statusPayload, fi), "sessionName", singleResult.sessionName);
4025
4259
  setOptionalProperty(requiredStatusStep(statusPayload, fi), "model", singleResult.model);
4026
4260
  setOptionalProperty(requiredStatusStep(statusPayload, fi), "thinking", resolveEffectiveThinking(singleResult.model, requiredStatusStep(statusPayload, fi).thinking));
4027
- setOptionalProperty(requiredStatusStep(statusPayload, fi), "attemptedModels", singleResult.attemptedModels);
4028
- setOptionalProperty(requiredStatusStep(statusPayload, fi), "modelAttempts", singleResult.modelAttempts);
4261
+ setOptionalProperty(requiredStatusStep(statusPayload, fi), "requestedModel", singleResult.requestedModel);
4029
4262
  setOptionalProperty(requiredStatusStep(statusPayload, fi), "contextOverflow", singleResult.contextOverflow);
4030
4263
  setOptionalProperty(requiredStatusStep(statusPayload, fi), "totalCost", singleResult.totalCost);
4031
4264
  if (singleResult.totalCost) {
@@ -4093,7 +4326,7 @@ async function runSubagent(
4093
4326
  const sessionTokens = config.sessionDir
4094
4327
  ? parseSessionTokens(path.join(config.sessionDir, `parallel-${t}`))
4095
4328
  : null;
4096
- const fallbackTokens = tokenUsageFromAttempts(parallelResults[t]?.modelAttempts);
4329
+ const fallbackTokens = tokenUsageFromUsage(parallelResults[t]?.usage);
4097
4330
  const observedTokens = requiredStatusStep(statusPayload, fi).tokens;
4098
4331
  const taskTokens = sessionTokens ?? (fallbackTokens
4099
4332
  ? { ...fallbackTokens, ...(observedTokens?.window !== undefined ? { window: observedTokens.window } : {}), ...(observedTokens?.windowPeak !== undefined ? { windowPeak: observedTokens.windowPeak } : {}) }
@@ -4125,7 +4358,7 @@ async function runSubagent(
4125
4358
  output: pr.output,
4126
4359
  outputState: pr.outputState,
4127
4360
  error: pr.error,
4128
- success: pr.stopped !== true && pr.interrupted !== true && pr.exitCode === 0,
4361
+ success: pr.stopped !== true && pr.interrupted !== true && pr.exitCode === 0 && pr.execution?.status !== "partial",
4129
4362
  exitCode: pr.interrupted === true ? 0 : pr.exitCode,
4130
4363
  skipped: pr.skipped,
4131
4364
  interrupted: pr.interrupted,
@@ -4137,12 +4370,13 @@ async function runSubagent(
4137
4370
  intercomTarget: pr.intercomTarget,
4138
4371
  model: pr.model,
4139
4372
  thinking: pr.thinking,
4140
- attemptedModels: pr.attemptedModels,
4141
- modelAttempts: pr.modelAttempts,
4373
+ requestedModel: pr.requestedModel,
4142
4374
  contextOverflow: pr.contextOverflow,
4143
4375
  totalCost: pr.totalCost,
4144
4376
  usage: pr.usage,
4145
4377
  artifactPaths: pr.artifactPaths,
4378
+ outputSaveError: pr.outputSaveError,
4379
+ artifactOutputSaveFailed: pr.artifactOutputSaveFailed,
4146
4380
  transcriptPath: pr.transcriptPath,
4147
4381
  transcriptError: pr.transcriptError,
4148
4382
  effects: pr.effects,
@@ -4175,51 +4409,54 @@ async function runSubagent(
4175
4409
  exitCode: r.exitCode,
4176
4410
  error: r.error,
4177
4411
  model: r.model,
4178
- attemptedModels: r.attemptedModels,
4412
+ requestedModel: r.requestedModel,
4179
4413
  })),
4180
4414
  );
4181
4415
  if (worktreeSetup) {
4182
- const captured = captureParallelWorktreeDiffs(worktreeSetup, asyncDir, stepIndex, group);
4183
- if (captured.summary) previousOutput = `${previousOutput}\n\n${captured.summary}`;
4416
+ const setup = worktreeSetup;
4184
4417
  worktreeFinalized = true;
4185
- const manifestPath = parallelHandoffPath(asyncDir);
4186
- const handoff = {
4187
- manifestPath,
4188
- runId: id,
4189
- mode: (config.resultMode ?? statusPayload.mode) === "parallel" ? "parallel" as const : "chain" as const,
4190
- source: "async" as const,
4191
- cwd,
4192
- stepIndex,
4193
- flatStartIndex: groupStartFlatIndex,
4194
- setup: worktreeSetup,
4195
- diffs: captured.diffs,
4196
- results: parallelResults.map((result) => ({
4197
- agent: result.agent,
4198
- ...(handoffWorkflowKey ? { workflowKey: handoffWorkflowKey } : {}),
4199
- ...(handoffChildRunId ? { runId: handoffChildRunId } : {}),
4200
- ...(config.lane ? { lane: config.lane } : {}),
4201
- status: result.stopped || (result.exitCode !== 0 && isUnexplainedProcessSignal(omitUndefinedProperties({
4202
- processSignal: result.processSignal,
4203
- interrupted: result.interrupted,
4204
- timedOut: result.timedOut,
4205
- stopped: result.stopped,
4206
- }))) ? "stopped" as const : result.interrupted ? "paused" as const : result.exitCode === 0 ? "completed" as const : "failed" as const,
4207
- summary: result.output || result.error || "(no output)",
4208
- ...(result.artifactPaths?.outputPath ? { outputPath: result.artifactPaths.outputPath } : {}),
4209
- ...(result.structuredOutput !== undefined ? { structuredOutput: result.structuredOutput } : {}),
4210
- ...(result.structuredOutputPath ? { structuredOutputPath: result.structuredOutputPath } : {}),
4211
- ...(result.sessionFile ? { sessionPath: result.sessionFile } : {}),
4212
- })),
4213
- };
4214
- try {
4215
- writeParallelHandoffGroup(handoff);
4216
- const cleanup = cleanupWorktrees(worktreeSetup, { kind: "preserve", capturedDiffs: captured.diffs, handoffManifestPath: manifestPath });
4217
- statusPayload.parallelHandoff = writeParallelHandoffGroup({ ...handoff, cleanup });
4218
- previousOutput = `${previousOutput}\n\n${formatParallelHandoffReference(statusPayload.parallelHandoff)}`;
4219
- } catch (error) {
4220
- previousOutput = `${previousOutput}\n\n${formatParallelHandoffError(error)}`;
4221
- }
4222
- writeStatusPayload();
4418
+ await finalizeWorktree(setup, stepIndex, groupStartFlatIndex, () => {
4419
+ const captured = captureParallelWorktreeDiffs(setup, asyncDir, stepIndex, group);
4420
+ if (captured.summary) previousOutput = `${previousOutput}\n\n${captured.summary}`;
4421
+ const manifestPath = parallelHandoffPath(asyncDir);
4422
+ const handoff = {
4423
+ manifestPath,
4424
+ runId: id,
4425
+ mode: (config.resultMode ?? statusPayload.mode) === "parallel" ? "parallel" as const : "chain" as const,
4426
+ source: "async" as const,
4427
+ cwd,
4428
+ stepIndex,
4429
+ flatStartIndex: groupStartFlatIndex,
4430
+ setup,
4431
+ diffs: captured.diffs,
4432
+ results: parallelResults.map((result) => ({
4433
+ agent: result.agent,
4434
+ ...(handoffWorkflowKey ? { workflowKey: handoffWorkflowKey } : {}),
4435
+ ...(handoffChildRunId ? { runId: handoffChildRunId } : {}),
4436
+ ...(config.lane ? { lane: config.lane } : {}),
4437
+ status: result.stopped || (result.exitCode !== 0 && isUnexplainedProcessSignal(omitUndefinedProperties({
4438
+ processSignal: result.processSignal,
4439
+ interrupted: result.interrupted,
4440
+ timedOut: result.timedOut,
4441
+ stopped: result.stopped,
4442
+ }))) ? "stopped" as const : result.interrupted ? "paused" as const : result.exitCode === 0 ? "completed" as const : "failed" as const,
4443
+ summary: result.output || result.error || "(no output)",
4444
+ ...(result.artifactPaths?.outputPath ? { outputPath: result.artifactPaths.outputPath } : {}),
4445
+ ...(result.structuredOutput !== undefined ? { structuredOutput: result.structuredOutput } : {}),
4446
+ ...(result.structuredOutputPath ? { structuredOutputPath: result.structuredOutputPath } : {}),
4447
+ ...(result.sessionFile ? { sessionPath: result.sessionFile } : {}),
4448
+ })),
4449
+ };
4450
+ try {
4451
+ writeParallelHandoffGroup(handoff);
4452
+ const cleanup = cleanupWorktrees(setup, { kind: "preserve", capturedDiffs: captured.diffs, handoffManifestPath: manifestPath });
4453
+ statusPayload.parallelHandoff = writeParallelHandoffGroup({ ...handoff, cleanup });
4454
+ previousOutput = `${previousOutput}\n\n${formatParallelHandoffReference(statusPayload.parallelHandoff)}`;
4455
+ } catch (error) {
4456
+ previousOutput = `${previousOutput}\n\n${formatParallelHandoffError(error)}`;
4457
+ }
4458
+ writeStatusPayload();
4459
+ });
4223
4460
  }
4224
4461
 
4225
4462
  appendJsonl(eventsPath, JSON.stringify({
@@ -4228,12 +4465,12 @@ async function runSubagent(
4228
4465
  runId: id,
4229
4466
  stepIndex,
4230
4467
  success: parallelResults.every((r) => r.exitCode === 0 || r.exitCode === -1)
4231
- && parallelResults.every((result, index) => !(isAgentContractV1(group.parallel[index]?.agentContract) && group.parallel[index]?.gateOn === "acceptance" && result.acceptance?.status === "rejected")),
4468
+ && parallelResults.every((result, index) => !(isAgentContract(group.parallel[index]?.agentContract) && group.parallel[index]?.gateOn === "acceptance" && result.acceptance?.status === "rejected")),
4232
4469
  }));
4233
4470
 
4234
4471
  const acceptanceGateFailure = parallelResults
4235
4472
  .map((result, index) => ({ result, index, task: group.parallel[index] }))
4236
- .find(({ result, task }) => isAgentContractV1(task?.agentContract) && task?.gateOn === "acceptance" && result.acceptance?.status === "rejected");
4473
+ .find(({ result, task }) => isAgentContract(task?.agentContract) && task?.gateOn === "acceptance" && result.acceptance?.status === "rejected");
4237
4474
  if (acceptanceGateFailure) {
4238
4475
  statusPayload.error = (acceptanceGateFailure.result.acceptance ? acceptanceFailureMessage(acceptanceGateFailure.result.acceptance) : undefined) ?? "Parallel acceptance gate rejected the step.";
4239
4476
  writeStatusPayload();
@@ -4243,7 +4480,7 @@ async function runSubagent(
4243
4480
  break;
4244
4481
  }
4245
4482
  } finally {
4246
- if (worktreeSetup && !worktreeFinalized) cleanupWorktrees(worktreeSetup);
4483
+ if (worktreeSetup && !worktreeFinalized) await cleanupRemainingWorktree(worktreeSetup, stepIndex, groupStartFlatIndex);
4247
4484
  }
4248
4485
  } else {
4249
4486
  const seqStep = step as SubagentStep;
@@ -4270,7 +4507,9 @@ async function runSubagent(
4270
4507
  let singleWorktreeSetup: WorktreeSetup | undefined;
4271
4508
  if (seqStep.worktree) {
4272
4509
  try {
4273
- singleWorktreeSetup = createWorktrees(cwd, `${id}-s${stepIndex}`, 1, omitUndefinedProperties({
4510
+ singleWorktreeSetup = await createWorktrees(cwd, `${id}-s${stepIndex}`, 1, omitUndefinedProperties({
4511
+ signal: setupSignal,
4512
+ deadlineAt: config.deadlineAt,
4274
4513
  agents: [seqStep.agent],
4275
4514
  labels: [seqStep.lane?.key ?? config.workflowKey ?? seqStep.outputName ?? seqStep.label],
4276
4515
  tasks: [seqStep.task],
@@ -4281,12 +4520,13 @@ async function runSubagent(
4281
4520
  ? omitUndefinedProperties({ hookPath: config.worktreeSetupHook, timeoutMs: config.worktreeSetupHookTimeoutMs })
4282
4521
  : undefined,
4283
4522
  baseDir: config.worktreeBaseDir,
4284
- beforeCreate: (plannedSetup) => {
4285
- const worktree = plannedSetup.worktrees[0];
4523
+ onProgress: (progress) => {
4524
+ publishSetupUnknown(progress);
4525
+ const worktree = progress.setup.worktrees[0];
4286
4526
  if (worktree) {
4287
4527
  setStatusWorktreeReference(requiredStatusStep(statusPayload, flatIndex), worktree);
4288
4528
  }
4289
- const pendingHandoff = writePendingParallelHandoff({
4529
+ const pendingHandoff = writeWorktreeSetupHandoff({
4290
4530
  manifestPath: parallelHandoffPath(asyncDir),
4291
4531
  runId: id,
4292
4532
  mode: "single",
@@ -4294,19 +4534,47 @@ async function runSubagent(
4294
4534
  cwd,
4295
4535
  stepIndex,
4296
4536
  flatStartIndex: flatIndex,
4297
- setup: plannedSetup,
4537
+ progress,
4298
4538
  laneBindings: handoffWorkflowKey || config.lane ? [{ index: flatIndex, taskIndex: 0, ...(handoffWorkflowKey ? { workflowKey: handoffWorkflowKey } : {}), ...(handoffChildRunId ? { runId: handoffChildRunId } : {}), ...(config.lane ? { lane: config.lane } : {}) }] : undefined,
4299
4539
  });
4540
+ if (!pendingHandoff) return;
4300
4541
  statusPayload.parallelHandoff = pendingHandoff;
4301
4542
  statusPayload.lastUpdate = Date.now();
4302
4543
  writeStatusPayload();
4303
4544
  },
4304
4545
  }));
4305
4546
  } catch (error) {
4306
- if (singleWorktreeSetup) cleanupWorktrees(singleWorktreeSetup);
4307
- throw error;
4547
+ if (error instanceof WorktreeSetupError) publishSetupUnknown(error.snapshot);
4548
+ if (config.deadlineAt !== undefined && Date.now() >= config.deadlineAt) timeoutRunner();
4549
+ const message = error instanceof Error ? error.message : String(error);
4550
+ if (childStopRequests.has(flatIndex)) markChildStopped(flatIndex);
4551
+ const statusStep = requiredStatusStep(statusPayload, flatIndex);
4552
+ statusStep.status = stopped || childStopRequests.has(flatIndex) ? "stopped" : interrupted ? "paused" : "failed";
4553
+ statusStep.error ??= message;
4554
+ statusStep.exitCode = interrupted ? 0 : 1;
4555
+ statusStep.endedAt = Date.now();
4556
+ results.push(stopped ? stoppedStepResult(seqStep.agent, seqStep.context, seqStep.sessionName)
4557
+ : childStopRequests.has(flatIndex) ? childStopResult(flatIndex, seqStep.agent, seqStep.context)
4558
+ : timedOut ? timedOutStepResult(seqStep.agent, seqStep.context, seqStep.sessionName)
4559
+ : interrupted ? pausedStepResult(seqStep.agent, seqStep.context, seqStep.sessionName)
4560
+ : { agent: seqStep.agent, output: message, error: message, exitCode: 1, success: false });
4561
+ statusPayload.error ??= message;
4562
+ writeStatusPayload();
4563
+ flatIndex++;
4564
+ break;
4308
4565
  }
4309
4566
  }
4567
+ if (singleWorktreeSetup && config.deadlineAt !== undefined && Date.now() >= config.deadlineAt) timeoutRunner();
4568
+ if (singleWorktreeSetup && (timedOut || stopped || interrupted || childStopRequests.has(flatIndex))) {
4569
+ await cleanupRemainingWorktree(singleWorktreeSetup, stepIndex, flatIndex);
4570
+ results.push(stopped ? stoppedStepResult(seqStep.agent, seqStep.context, seqStep.sessionName)
4571
+ : childStopRequests.has(flatIndex) ? childStopResult(flatIndex, seqStep.agent, seqStep.context)
4572
+ : timedOut ? timedOutStepResult(seqStep.agent, seqStep.context, seqStep.sessionName)
4573
+ : pausedStepResult(seqStep.agent, seqStep.context, seqStep.sessionName));
4574
+ if (interrupted) requiredStatusStep(statusPayload, flatIndex).status = "paused";
4575
+ flatIndex++;
4576
+ continue;
4577
+ }
4310
4578
  const singleCwd = singleWorktreeSetup?.worktrees[0]?.agentCwd ?? cwd;
4311
4579
  const stepStartTime = Date.now();
4312
4580
  statusPayload.currentStep = flatIndex;
@@ -4351,10 +4619,12 @@ async function runSubagent(
4351
4619
  nestedRoute: config.nestedRoute,
4352
4620
  capabilityCeiling: config.capabilityCeiling,
4353
4621
  runFanoutBudget: config.runFanoutBudget,
4622
+ hostAvailableBuiltins: config.hostAvailableBuiltins,
4354
4623
  registerInterrupt: (interrupt) => registerStepInterrupt(flatIndex, interrupt),
4355
4624
  registerTimeout: (interrupt) => registerStepTimeout(flatIndex, interrupt),
4356
4625
  registerStop: (stop) => registerStepStop(flatIndex, stop),
4357
4626
  registerSteer: (steer) => registerStepSteer(flatIndex, steer),
4627
+ onSteerOutcome: (request, delivery) => applySteerDelivery(request.id, flatIndex, delivery),
4358
4628
  timeoutSignal: timeoutAbortController.signal,
4359
4629
  stopSignal: stopAbortController.signal,
4360
4630
  timeoutMessage,
@@ -4363,13 +4633,16 @@ async function runSubagent(
4363
4633
  onAttemptStart: (attempt) => updateStepModel(flatIndex, attempt.model, attempt.thinking, attempt.contextLimit),
4364
4634
  onChildEvent: (event) => updateStepFromChildEvent(flatIndex, event),
4365
4635
  onExternalProcess: (process) => updateExternalProcess(flatIndex, process),
4636
+ prepareExternalActivity: (externalCwd, signal) => prepareExternalActivity(flatIndex, externalCwd, signal),
4637
+ onExternalStreamActivity: () => recordExternalStreamActivity(flatIndex),
4366
4638
  onExternalJob: (externalJob) => updateExternalJob(flatIndex, externalJob),
4367
4639
  skipAcceptance: () => timedOut || stopped || childStopRequests.has(flatIndex),
4368
- usageBudgetExhausted: () => refreshUsageBudget()?.exhausted === true,
4640
+ usageBudgetExhausted: continuationUsageBudgetExhausted,
4641
+ usageBudget: config.usageBudget,
4369
4642
  orcaProgressTab,
4370
4643
  }), config.deadlineAt);
4371
4644
  } catch (error) {
4372
- if (singleWorktreeSetup) cleanupWorktrees(singleWorktreeSetup);
4645
+ if (singleWorktreeSetup) await cleanupRemainingWorktree(singleWorktreeSetup, stepIndex, flatIndex);
4373
4646
  throw error;
4374
4647
  }
4375
4648
  if (seqStep.sessionFile) {
@@ -4390,18 +4663,20 @@ async function runSubagent(
4390
4663
  output: stopped || childStopped ? stopMessage : timedOut ? singleResult.output || (timeoutMessage ?? "Subagent timed out.") : singleResult.output,
4391
4664
  outputState: singleResult.outputState,
4392
4665
  error: stopped || childStopped ? stopMessage : timedOut ? (timeoutMessage ?? "Subagent timed out.") : singleResult.error,
4393
- success: !stopped && !childStopped && !timedOut && singleResult.interrupted !== true && singleResult.exitCode === 0,
4666
+ success: !stopped && !childStopped && !timedOut && singleResult.interrupted !== true && singleResult.exitCode === 0 && singleResult.execution?.status !== "partial",
4394
4667
  exitCode: stopped || childStopped ? 1 : timedOut ? 1 : singleResult.interrupted === true ? 0 : singleResult.exitCode,
4395
4668
  sessionFile: singleResult.sessionFile,
4396
4669
  intercomTarget: singleResult.intercomTarget,
4397
4670
  model: singleResult.model,
4398
4671
  thinking: singleResult.thinking,
4399
- attemptedModels: singleResult.attemptedModels,
4400
- modelAttempts: singleResult.modelAttempts,
4672
+ requestedModel: singleResult.requestedModel,
4401
4673
  contextOverflow: singleResult.contextOverflow,
4402
4674
  totalCost: singleResult.totalCost,
4403
4675
  usage: singleResult.usage,
4404
4676
  artifactPaths: singleResult.artifactPaths,
4677
+ savedOutputPath: singleResult.savedOutputPath,
4678
+ outputSaveError: singleResult.outputSaveError,
4679
+ artifactOutputSaveFailed: singleResult.artifactOutputSaveFailed,
4405
4680
  transcriptPath: singleResult.transcriptPath,
4406
4681
  transcriptError: singleResult.transcriptError,
4407
4682
  effects: singleResult.effects,
@@ -4446,7 +4721,7 @@ async function runSubagent(
4446
4721
  if (cumulativeTokens) {
4447
4722
  previousCumulativeTokens = cumulativeTokens;
4448
4723
  } else {
4449
- const fallbackTokens = tokenUsageFromAttempts(singleResult.modelAttempts);
4724
+ const fallbackTokens = tokenUsageFromUsage(singleResult.usage);
4450
4725
  const observedTokens = requiredStatusStep(statusPayload, flatIndex).tokens;
4451
4726
  stepTokens = fallbackTokens
4452
4727
  ? { ...fallbackTokens, ...(observedTokens?.window !== undefined ? { window: observedTokens.window } : {}), ...(observedTokens?.windowPeak !== undefined ? { windowPeak: observedTokens.windowPeak } : {}) }
@@ -4466,7 +4741,7 @@ async function runSubagent(
4466
4741
 
4467
4742
  const stepEndTime = Date.now();
4468
4743
  const childInterrupted = singleResult.interrupted === true;
4469
- requiredStatusStep(statusPayload, flatIndex).status = stopped || childStopped ? "stopped" : timedOut ? "failed" : childInterrupted ? "paused" : singleResult.exitCode === 0 ? "complete" : "failed";
4744
+ requiredStatusStep(statusPayload, flatIndex).status = stopped || childStopped ? "stopped" : timedOut ? "failed" : childInterrupted ? "paused" : singleResult.execution?.status === "partial" ? "partial" : singleResult.exitCode === 0 ? "complete" : "failed";
4470
4745
  requiredStatusStep(statusPayload, flatIndex).endedAt = stepEndTime;
4471
4746
  requiredStatusStep(statusPayload, flatIndex).durationMs = stepEndTime - stepStartTime;
4472
4747
  requiredStatusStep(statusPayload, flatIndex).exitCode = stopped || childStopped ? 1 : timedOut ? 1 : childInterrupted ? 0 : singleResult.exitCode;
@@ -4479,8 +4754,7 @@ async function runSubagent(
4479
4754
  setOptionalProperty(requiredStatusStep(statusPayload, flatIndex), "sessionName", singleResult.sessionName);
4480
4755
  setOptionalProperty(requiredStatusStep(statusPayload, flatIndex), "model", singleResult.model);
4481
4756
  setOptionalProperty(requiredStatusStep(statusPayload, flatIndex), "thinking", resolveEffectiveThinking(singleResult.model, requiredStatusStep(statusPayload, flatIndex).thinking));
4482
- setOptionalProperty(requiredStatusStep(statusPayload, flatIndex), "attemptedModels", singleResult.attemptedModels);
4483
- setOptionalProperty(requiredStatusStep(statusPayload, flatIndex), "modelAttempts", singleResult.modelAttempts);
4757
+ setOptionalProperty(requiredStatusStep(statusPayload, flatIndex), "requestedModel", singleResult.requestedModel);
4484
4758
  setOptionalProperty(requiredStatusStep(statusPayload, flatIndex), "contextOverflow", singleResult.contextOverflow);
4485
4759
  setOptionalProperty(requiredStatusStep(statusPayload, flatIndex), "totalCost", singleResult.totalCost);
4486
4760
  setOptionalProperty(requiredStatusStep(statusPayload, flatIndex), "error", stopped || childStopped ? stopMessage : timedOut ? (timeoutMessage ?? "Subagent timed out.") : singleResult.error);
@@ -4522,48 +4796,51 @@ async function runSubagent(
4522
4796
  }));
4523
4797
  if (stopped || childStopped) appendTerminalChildStatusEvent(flatIndex, stepEndTime);
4524
4798
  if (singleWorktreeSetup && !singleResult.detached) {
4525
- const diffs = diffWorktrees(singleWorktreeSetup, [seqStep.agent], path.join(asyncDir, "worktree-diffs", `step-${stepIndex}`));
4526
- const diffSummary = formatWorktreeDiffSummary(diffs);
4527
- const manifestPath = parallelHandoffPath(asyncDir);
4528
- const handoff = {
4529
- manifestPath,
4530
- runId: id,
4531
- mode: "single" as const,
4532
- source: "async" as const,
4533
- cwd,
4534
- stepIndex,
4535
- flatStartIndex: flatIndex,
4536
- setup: singleWorktreeSetup,
4537
- diffs,
4538
- results: [{
4539
- agent: singleResult.agent,
4540
- ...(handoffWorkflowKey ? { workflowKey: handoffWorkflowKey } : {}),
4541
- ...(handoffChildRunId ? { runId: handoffChildRunId } : {}),
4542
- ...(config.lane ? { lane: config.lane } : {}),
4543
- status: singleResult.stopped ? "stopped" as const : singleResult.interrupted ? "paused" as const : singleResult.exitCode === 0 ? "completed" as const : "failed" as const,
4544
- summary: singleResult.output || singleResult.error || "(no output)",
4545
- ...(singleResult.artifactPaths?.outputPath ? { outputPath: singleResult.artifactPaths.outputPath } : {}),
4546
- ...(singleResult.structuredOutput !== undefined ? { structuredOutput: singleResult.structuredOutput } : {}),
4547
- ...(singleResult.structuredOutputPath ? { structuredOutputPath: singleResult.structuredOutputPath } : {}),
4548
- ...(singleResult.sessionFile ? { sessionPath: singleResult.sessionFile } : {}),
4549
- }],
4550
- };
4551
- try {
4552
- writeParallelHandoffGroup(handoff);
4553
- const cleanup = cleanupWorktrees(singleWorktreeSetup, {
4554
- kind: "preserve",
4555
- capturedDiffs: diffs,
4556
- handoffManifestPath: manifestPath,
4557
- ...(config.parentWorkflowRunId && singleResult.sessionFile && fs.existsSync(singleResult.sessionFile) && !singleResult.stopped
4558
- ? { cleanupBlocker: "retained child resume requires managed worktree cwd" }
4559
- : {}),
4560
- });
4561
- statusPayload.parallelHandoff = writeParallelHandoffGroup({ ...handoff, cleanup });
4562
- previousOutput = [previousOutput, diffSummary, formatParallelHandoffReference(statusPayload.parallelHandoff)].filter(Boolean).join("\n\n");
4563
- } catch (error) {
4564
- previousOutput = [previousOutput, diffSummary, formatParallelHandoffError(error)].filter(Boolean).join("\n\n");
4565
- }
4566
- writeStatusPayload();
4799
+ const setup = singleWorktreeSetup;
4800
+ await finalizeWorktree(setup, stepIndex, flatIndex, () => {
4801
+ const diffs = diffWorktrees(setup, [seqStep.agent], path.join(asyncDir, "worktree-diffs", `step-${stepIndex}`));
4802
+ const diffSummary = formatWorktreeDiffSummary(diffs);
4803
+ const manifestPath = parallelHandoffPath(asyncDir);
4804
+ const handoff = {
4805
+ manifestPath,
4806
+ runId: id,
4807
+ mode: "single" as const,
4808
+ source: "async" as const,
4809
+ cwd,
4810
+ stepIndex,
4811
+ flatStartIndex: flatIndex,
4812
+ setup,
4813
+ diffs,
4814
+ results: [{
4815
+ agent: singleResult.agent,
4816
+ ...(handoffWorkflowKey ? { workflowKey: handoffWorkflowKey } : {}),
4817
+ ...(handoffChildRunId ? { runId: handoffChildRunId } : {}),
4818
+ ...(config.lane ? { lane: config.lane } : {}),
4819
+ status: singleResult.stopped ? "stopped" as const : singleResult.interrupted ? "paused" as const : singleResult.exitCode === 0 ? "completed" as const : "failed" as const,
4820
+ summary: singleResult.output || singleResult.error || "(no output)",
4821
+ ...(singleResult.artifactPaths?.outputPath ? { outputPath: singleResult.artifactPaths.outputPath } : {}),
4822
+ ...(singleResult.structuredOutput !== undefined ? { structuredOutput: singleResult.structuredOutput } : {}),
4823
+ ...(singleResult.structuredOutputPath ? { structuredOutputPath: singleResult.structuredOutputPath } : {}),
4824
+ ...(singleResult.sessionFile ? { sessionPath: singleResult.sessionFile } : {}),
4825
+ }],
4826
+ };
4827
+ try {
4828
+ writeParallelHandoffGroup(handoff);
4829
+ const cleanup = cleanupWorktrees(setup, {
4830
+ kind: "preserve",
4831
+ capturedDiffs: diffs,
4832
+ handoffManifestPath: manifestPath,
4833
+ ...(config.parentWorkflowRunId && singleResult.sessionFile && fs.existsSync(singleResult.sessionFile) && !singleResult.stopped
4834
+ ? { cleanupBlocker: "retained child resume requires managed worktree cwd" }
4835
+ : {}),
4836
+ });
4837
+ statusPayload.parallelHandoff = writeParallelHandoffGroup({ ...handoff, cleanup });
4838
+ previousOutput = [previousOutput, diffSummary, formatParallelHandoffReference(statusPayload.parallelHandoff)].filter(Boolean).join("\n\n");
4839
+ } catch (error) {
4840
+ previousOutput = [previousOutput, diffSummary, formatParallelHandoffError(error)].filter(Boolean).join("\n\n");
4841
+ }
4842
+ writeStatusPayload();
4843
+ });
4567
4844
  }
4568
4845
 
4569
4846
  if (singleResult.completionGuardTriggered) {
@@ -4581,7 +4858,7 @@ async function runSubagent(
4581
4858
  }
4582
4859
 
4583
4860
  flatIndex++;
4584
- if (isAgentContractV1(seqStep.agentContract) && seqStep.gateOn === "acceptance" && singleResult.acceptance?.status === "rejected") {
4861
+ if (isAgentContract(seqStep.agentContract) && seqStep.gateOn === "acceptance" && singleResult.acceptance?.status === "rejected") {
4585
4862
  statusPayload.error = acceptanceFailureMessage(singleResult.acceptance) ?? "Chain acceptance gate rejected the step.";
4586
4863
  writeStatusPayload();
4587
4864
  break;
@@ -4592,6 +4869,34 @@ async function runSubagent(
4592
4869
  }
4593
4870
  }
4594
4871
 
4872
+ await Promise.all([...externalActivityEvidence.values()].map((evidence) => evidence.probeInFlight).filter((probe): probe is Promise<void> => probe !== undefined));
4873
+ if (periodicGitProbeFailure) {
4874
+ stopped = false;
4875
+ timedOut = false;
4876
+ interrupted = false;
4877
+ delete statusPayload.stopped;
4878
+ delete statusPayload.timedOut;
4879
+ statusPayload.error = periodicGitProbeFailure.message;
4880
+ const step = statusPayload.steps[periodicGitProbeFailure.index];
4881
+ if (step) {
4882
+ step.status = "failed";
4883
+ step.error = periodicGitProbeFailure.message;
4884
+ step.exitCode = 1;
4885
+ delete step.stopped;
4886
+ delete step.timedOut;
4887
+ }
4888
+ const result = results[periodicGitProbeFailure.index];
4889
+ if (result) {
4890
+ result.success = false;
4891
+ result.exitCode = 1;
4892
+ result.error = periodicGitProbeFailure.message;
4893
+ result.output = periodicGitProbeFailure.message;
4894
+ result.stopped = false;
4895
+ result.timedOut = false;
4896
+ result.interrupted = false;
4897
+ }
4898
+ }
4899
+
4595
4900
  let summary = results.map((r) => `${r.agent}:\n${r.output || (r.exitCode !== 0 ? r.error : undefined) || "(no output)"}`).join("\n\n");
4596
4901
  let truncated = false;
4597
4902
 
@@ -4657,9 +4962,15 @@ async function runSubagent(
4657
4962
  clearTimeout(timeoutTimer);
4658
4963
  timeoutTimer = undefined;
4659
4964
  }
4965
+ if (checkpointTimer) {
4966
+ clearTimeout(checkpointTimer);
4967
+ checkpointTimer = undefined;
4968
+ }
4660
4969
  if (!timedOut && !stopped && !interrupted && config.timeoutMs !== undefined && timeoutMessage !== undefined && results.some((result) => result.timedOut === true && result.error?.startsWith(timeoutMessage))) {
4661
4970
  timedOut = true;
4662
4971
  }
4972
+ disposeControlInbox();
4973
+ for (const request of consumeStopRequestPayloads(asyncDir)) stopChildStep(request);
4663
4974
  const signalTerminated = !stopped && !timedOut && !interrupted && results.some((result) => result.exitCode !== 0 && isUnexplainedProcessSignal(omitUndefinedProperties({
4664
4975
  processSignal: result.processSignal,
4665
4976
  interrupted: result.interrupted,
@@ -4667,9 +4978,13 @@ async function runSubagent(
4667
4978
  stopped: result.stopped,
4668
4979
  })));
4669
4980
  const partialWithEvidence = !stopped && !signalTerminated && !timedOut && !usageBudgetExceeded && !interrupted && results.some(partialEvidenceResult) && !results.some(concreteFailureResult);
4981
+ // Flush while still nonterminal; deferred status retries retain that state snapshot.
4982
+ statusWriteCoalescer.flush(statusPath);
4983
+ const publication = new Promise<void>((resolve, reject) => {
4984
+ finalResultPublication = { resolve, reject };
4985
+ });
4670
4986
  statusPayload.state = stopped || signalTerminated ? "stopped" : timedOut || usageBudgetExceeded ? "failed" : interrupted ? "paused" : results.every((r) => r.success) ? "complete" : partialWithEvidence ? "partial" : "failed";
4671
4987
  closeSteerInbox(asyncDir, statusPayload.state, (filePath, payload) => runPersistence.write(filePath, payload));
4672
- disposeControlInbox();
4673
4988
  for (const request of consumeSteerRequests(asyncDir)) deliverSteerRequest(request);
4674
4989
  const effectiveSessionFile = sessionFile ?? latestSessionFile;
4675
4990
  const steeringLifecycle = steeringStatus(statusPayload);
@@ -4678,7 +4993,7 @@ async function runSubagent(
4678
4993
  for (const target of request.targets) {
4679
4994
  if (target.state !== "scheduled" && target.state !== "routed" && target.state !== "queued") continue;
4680
4995
  changed = true;
4681
- const reason = target.state === "queued" ? "run ended before queued follow-up delivery" : "child terminated before steering delivery";
4996
+ const reason = target.state === "queued" ? unconsumedSteerReason() : "child terminated before steering delivery";
4682
4997
  updateSteeringLifecycleTarget(request.id, target.index, "failed", Date.now(), { reason });
4683
4998
  markSteeringAttention(target.index);
4684
4999
  emitSteeringEvent("subagent.steer.failed", { type: "steer", id: request.id, ts: request.requestedAt, message: reason }, target.index, { reason });
@@ -4705,7 +5020,7 @@ async function runSubagent(
4705
5020
  statusPayload.activityState = "needs_attention";
4706
5021
  statusPayload.error = partialResult?.error ?? statusPayload.error;
4707
5022
  for (const step of statusPayload.steps) {
4708
- if (step.status === "failed") step.activityState = "needs_attention";
5023
+ if (step.status === "failed" || step.status === "partial") step.activityState = "needs_attention";
4709
5024
  }
4710
5025
  }
4711
5026
  statusPayload.endedAt = runEndedAt;
@@ -4725,6 +5040,9 @@ async function runSubagent(
4725
5040
  statusPayload.error = `Step failed: ${failedStep.agent}`;
4726
5041
  }
4727
5042
  }
5043
+ let childSessionDisposal: Promise<void> | undefined;
5044
+ const disposeChildSessions = (): Promise<void> => childSessionDisposal ??= childSessions.dispose()
5045
+ .catch((error: unknown) => console.error("Failed to dispose runner child sessions:", error));
4728
5046
  try {
4729
5047
  runPersistence.write(resultPath, {
4730
5048
  lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
@@ -4759,13 +5077,14 @@ async function runSubagent(
4759
5077
  intercomTarget: r.intercomTarget,
4760
5078
  model: r.model,
4761
5079
  thinking: r.thinking,
4762
- attemptedModels: r.attemptedModels,
4763
- modelAttempts: r.modelAttempts,
5080
+ requestedModel: r.requestedModel,
4764
5081
  contextOverflow: r.contextOverflow,
4765
5082
  totalCost: r.totalCost,
4766
5083
  usage: r.usage,
4767
5084
  artifactPaths: r.artifactPaths,
5085
+ savedOutputPath: r.savedOutputPath,
4768
5086
  outputSaveError: r.outputSaveError,
5087
+ artifactOutputSaveFailed: r.artifactOutputSaveFailed,
4769
5088
  metadataSaveError: r.metadataSaveError,
4770
5089
  truncated: r.truncated,
4771
5090
  transcriptPath: r.transcriptPath,
@@ -4820,13 +5139,16 @@ async function runSubagent(
4820
5139
  ...(taskIndex !== undefined && { taskIndex }),
4821
5140
  ...(totalTasks !== undefined && { totalTasks }),
4822
5141
  }, (filePath, payload) => { writeAsyncResultFile(filePath, payload as Record<string, unknown>); });
4823
- finalResultCommitted = true;
5142
+ // Only capacity deferral releases settled sessions before terminal publication.
5143
+ if (!finalResultCommitted) await Promise.all([publication, disposeChildSessions()]);
4824
5144
  } catch (err) {
4825
5145
  const message = `Failed to write result file ${resultPath}: ${err instanceof Error ? err.message : String(err)}`;
4826
5146
  console.error(message, err);
4827
5147
  statusPayload.state = "failed";
4828
5148
  statusPayload.error = message;
4829
5149
  statusPayload.lastUpdate = Date.now();
5150
+ } finally {
5151
+ finalResultPublication = undefined;
4830
5152
  }
4831
5153
  writeStatusPayload();
4832
5154
  await orcaProgressTab?.finish(statusPayload.state === "complete" ? "completed" : statusPayload.state === "stopped" ? "stopped" : "failed", effectiveSessionFile);
@@ -4864,9 +5186,8 @@ async function runSubagent(
4864
5186
  }), (filePath, content) => runPersistence.write(filePath, { content }, (_path, payload) => {
4865
5187
  fs.writeFileSync(_path, (payload as { content: string }).content, "utf-8");
4866
5188
  }));
4867
- // The run is committed: release the child sessions first, then wait for the
4868
- // storage-capacity retries that may still hold the final status or result.
4869
- await childSessions.dispose().catch((error: unknown) => console.error("Failed to dispose runner child sessions:", error));
5189
+ // Preserve normal-success disposal ordering, then drain remaining persistence retries.
5190
+ await disposeChildSessions();
4870
5191
  while (runPersistence.pendingCount() + indexPersistence.pendingCount() > 0) {
4871
5192
  await new Promise((resolve) => setTimeout(resolve, 200));
4872
5193
  }
@@ -4874,7 +5195,7 @@ async function runSubagent(
4874
5195
  indexPersistence.dispose();
4875
5196
  if (config.runnerProcessInstanceId) {
4876
5197
  // Children run inside this process, so no step has writer processes to prove terminal.
4877
- const writers: Record<string, PiWriterProcessInstanceExitV1[]> = {};
5198
+ const writers: Record<string, PiWriterProcessInstanceExit[]> = {};
4878
5199
  const expectedWriters: Record<string, number> = {};
4879
5200
  for (const index of results.keys()) {
4880
5201
  writers[String(index)] = [];
@@ -4900,7 +5221,7 @@ async function runSubagent(
4900
5221
  async function waitForStartupControl(
4901
5222
  controlPath: string,
4902
5223
  token: string,
4903
- action: "ack" | "proceed",
5224
+ action: "ack" | "confirm" | "proceed",
4904
5225
  timeoutMs = 30_000,
4905
5226
  ): Promise<void> {
4906
5227
  const deadline = Date.now() + timeoutMs;
@@ -4914,14 +5235,15 @@ async function waitForStartupControl(
4914
5235
  }
4915
5236
  if (payload.token !== token) throw new Error("Runner startup control token does not match.");
4916
5237
  if (payload.action === action) return;
4917
- if (payload.action !== "ack" && payload.action !== "proceed") throw new Error("Runner startup control action is invalid.");
5238
+ if (payload.action !== "ack" && payload.action !== "confirm" && payload.action !== "proceed") throw new Error("Runner startup control action is invalid.");
4918
5239
  }
4919
5240
  await new Promise((resolve) => setTimeout(resolve, 20));
4920
5241
  }
4921
5242
  throw new Error(`Timed out after ${timeoutMs}ms waiting for runner startup control '${action}'.`);
4922
5243
  }
4923
5244
 
4924
- async function runConfiguredSubagent(config: SubagentRunConfig): Promise<void> {
5245
+ // Both hosts enter here: startup authorization, revival leases and disposal stay shared.
5246
+ export async function runConfiguredSubagent(config: SubagentRunConfig, options?: DefaultChildSessionFactoryOptions): Promise<void> {
4925
5247
  let lease: ReturnType<typeof acquireSessionLease> | undefined;
4926
5248
  let startupCommitted = config.revivalLease === undefined && config.launchBarrierToken === undefined;
4927
5249
  const startupPath = path.join(config.asyncDir, "runner-startup.json");
@@ -4950,6 +5272,8 @@ async function runConfiguredSubagent(config: SubagentRunConfig): Promise<void> {
4950
5272
  writeAtomicJson(startupPath, { state: "ready", token: lease.owner.token, pid: process.pid, owner: lease.owner });
4951
5273
  await waitForStartupControl(startupAckPath, lease.owner.token, "ack");
4952
5274
  writeAtomicJson(startupPath, { state: "acknowledged", token: lease.owner.token, pid: process.pid });
5275
+ await waitForStartupControl(startupAckPath, lease.owner.token, "confirm");
5276
+ writeAtomicJson(startupPath, { state: "confirmed", token: lease.owner.token, pid: process.pid });
4953
5277
  await waitForStartupControl(startupProceedPath, lease.owner.token, "proceed");
4954
5278
  startupCommitted = true;
4955
5279
  for (const controlPath of [startupAckPath, startupProceedPath]) {
@@ -4960,7 +5284,7 @@ async function runConfiguredSubagent(config: SubagentRunConfig): Promise<void> {
4960
5284
  }
4961
5285
  }
4962
5286
  }
4963
- const childSessions = await loadRunnerChildSessionFactory(config);
5287
+ const childSessions = await loadRunnerChildSessionFactory(config, options);
4964
5288
  try {
4965
5289
  await runSubagent(config, childSessions);
4966
5290
  } finally {
@@ -5010,6 +5334,7 @@ function startConfiguredSubagent(config: SubagentRunConfig): void {
5010
5334
  );
5011
5335
  }
5012
5336
 
5337
+ if (isRunnerEntrypoint) {
5013
5338
  const configArg = process.argv[2];
5014
5339
  if (configArg) {
5015
5340
  try {
@@ -5041,3 +5366,4 @@ if (configArg) {
5041
5366
  }
5042
5367
  });
5043
5368
  }
5369
+ }