@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
@@ -7,6 +7,7 @@
7
7
  * - `classifyTaskMutationIntent` / `expectsImplementationMutation`: does the
8
8
  * task REQUIRE file changes? Consumed by the completion mutation guard,
9
9
  * which blocks completion, so its vocabulary is deliberately narrow.
10
+ * Verbs inside filenames and path-like tokens do not count.
10
11
  * - `taskMayMutate`: COULD the task plausibly change files? Consumed by
11
12
  * acceptance level inference, which only raises evidence gates, so its
12
13
  * vocabulary is deliberately broad (any bare write verb).
@@ -18,16 +19,20 @@
18
19
  */
19
20
 
20
21
  const REVIEW_ONLY_PATTERNS = [
21
- /\breview only\b/i,
22
+ /\b(?:review|read)[- ]only\b/i,
23
+ /\bno\s+(?:source\s+)?edits?\b/i,
24
+ /\bwithout\s+edits?\b/i,
22
25
  /\bsuggest fixes only\b/i,
23
26
  /\bonly return findings\b/i,
24
27
  /\breturn findings only\b/i,
25
28
  ];
26
29
 
30
+ const NO_EDIT_BOUNDARY_ASSERTION_PATTERN = /\bno\s+(?:source\s+)?edits?\s*,\s*(?:commits?|pushes?|merges?|installs?|changes?|writes?)\b/i;
31
+
27
32
  const REVIEWER_REQUIRED_EDIT_PATTERNS = [
28
33
  /\bmust\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
29
34
  /\brequired\s+to\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
30
- /(?:^|[.!?\n]\s*)implement\s+(?:the\s+)?(?:approved|requested|specified|file|code|source|fix(?:es)?|changes?)\b/i,
35
+ /(?:^|[.!?:;,\n]\s*)implement\s+(?:the\s+)?(?:approved|requested|specified|file|code|source|fix(?:es)?|changes?)\b/i,
31
36
  /\bregardless\s+of\s+findings\b/i,
32
37
  /\balways\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
33
38
  /\bapply\s+(?:the\s+)?fix(?:es)?\s+directly\b/i,
@@ -40,7 +45,7 @@ const REVIEWER_REQUIRED_EDIT_PATTERNS = [
40
45
  // being swallowed as the object.
41
46
  // Accept serialized line separators too: workflow prompts can carry literal
42
47
  // `\\n`/`\\r\\n` between clauses instead of decoded newlines.
43
- const NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b((?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
48
+ const NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change|implement)\b((?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
44
49
  const COORDINATED_NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+((?=(?:(?!\\(?:r\\n|n))[^.;:!?\n–—-])*\b(?:and|or)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b)(?:(?!\\(?:r\\n|n))[^.;:!?\n–—-])*?\b(?:and|or)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b(?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
45
50
 
46
51
  /** Objects of a no-edit prohibition that mean "the codebase in general" rather than a named scope. */
@@ -85,13 +90,25 @@ const RESEARCH_AGENT_PATTERNS = [
85
90
  // CLI flags like "--fix" and genuine clause-level dashes like "branch—fix it"),
86
91
  // strip the known severity compounds (must|should|needs + dash + verb) from the
87
92
  // task text before matching. Dash coverage: ASCII hyphen + U+2010..U+2015.
88
- const SEVERITY_COMPOUND_PATTERN = /\b(?:must|should|needs)[\-\u2010-\u2015](?:fix|edit|update|add|remove|replace|create|apply|make|do|implement|modify|delete|patch)\b/gi;
93
+ const SEVERITY_COMPOUND_PATTERN = /\b(?:must|should|needs)[-\u2010-\u2015](?:fix|edit|update|add|remove|replace|create|apply|make|do|implement|modify|delete|patch)\b/gi;
89
94
 
90
95
  function stripSeverityCompounds(task: string): string {
91
96
  return task.replace(SEVERITY_COMPOUND_PATTERN, " ");
92
97
  }
93
98
  export { stripSeverityCompounds };
94
99
 
100
+ // Quoted categories in a finding-classification request describe fixes, not
101
+ // instructions to perform them. Strip only that request, leaving sibling
102
+ // imperatives (including another "must fix") subject to the normal guards.
103
+ const FINDING_CLASSIFICATION_PATTERN = /\b(?:classify|categorize|weigh)\s+(?:(?:the|remaining)\s+)*(?:findings?|items?|issues?)\s+as\s+["“]must\s+fix\s+before\s+[^"”\n]+["”]\s+(?:vs\.?|versus)\s+["“]must\s+fix\s+before\s+[^"”\n]+["”]/gi;
104
+
105
+ const PATH_LIKE_TOKEN_PATTERN = /[^\s]+[/\\][^\s]+|[^\s/\\]+\.[A-Za-z][A-Za-z0-9]{0,9}\b/g;
106
+ const PATH_INTERNAL_IMPLEMENTATION_VERB = /\b(?:implement|edit|modify|refactor|delete|update|add|remove|replace|create)\b/i;
107
+
108
+ function stripPathLikeTokens(task: string): string {
109
+ return task.replace(PATH_LIKE_TOKEN_PATTERN, (token) => (PATH_INTERNAL_IMPLEMENTATION_VERB.test(token) ? " " : token));
110
+ }
111
+
95
112
  const FIX_OR_PATCH_IMPLEMENTATION_PATTERN = /\b(?:fix|patch)\s+(?:(?:it|this|that|them|each|any|all|these|those)\b|(?:(?:a|an|the|any|all)\s+)?(?:(?:failing|failed|broken|flaky|red|cold|start|current|existing|reported|approved|known|regression|unit|integration|e2e|source|typescript|type-?script|ts|type-?check|compiler)\s+)*(?:bug|defect|issues?|problems?|failures?|regressions?|tests?|errors?|items?|typos?|code|source|implementation|component|function|module|class|method|logic|file|files|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command|lint(?:ing)?|build|ci|type-?check|type\s+checking)\b)/i;
96
113
 
97
114
  const WORKER_IMPLEMENTATION_PATTERNS = [
@@ -103,12 +120,18 @@ const WORKER_IMPLEMENTATION_PATTERNS = [
103
120
  /\bdo those fixes\b/i,
104
121
  ];
105
122
 
106
- const GENERAL_IMPLEMENTATION_PATTERNS = [
123
+ const FOLLOW_ON_IMPLEMENTATION_PATTERN = /(?:^|[.!?:;,\n])\s*(?:fix|patch|update|add|remove|replace|create|delete)\s+(?:(?:the|a|an|this|that|these|those|requested|specified|current|existing|approved|your|our)\s+)(?!(?:report|summary|findings?|analysis|recommendations?|answer|response|proposal|plan|issue|bug report)\b)[a-z][\w./-]*/i;
124
+ const ADVISORY_INFINITIVE_PATTERN = /\b(?:explain|recommend|describe)\s+how\s+to\s+(?:fix|patch|update|add|remove|replace|create|delete|implement|edit|modify|refactor)\b/i;
125
+ const EXPLICIT_IMPLEMENTATION_PATTERNS = [
107
126
  /\b(?:implement|edit|modify|refactor)\b/i,
108
- FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
109
127
  /\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
110
128
  /\bmake\s+(?:the\s+)?changes\b/i,
111
129
  /\bdo those fixes\b/i,
130
+ ];
131
+
132
+ const GENERAL_IMPLEMENTATION_PATTERNS = [
133
+ ...EXPLICIT_IMPLEMENTATION_PATTERNS,
134
+ FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
112
135
  /\b(?:update|add|remove|replace|delete|create)\s+(?:the\s+)?(?:file|files|code|source|implementation|test|tests|component|function|module|class|method|logic|import|imports|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command)\b/i,
113
136
  ];
114
137
 
@@ -141,10 +164,13 @@ interface NoEditProhibitionAnalysis {
141
164
  }
142
165
 
143
166
  function analyzeNoEditProhibitions(taskText: string): NoEditProhibitionAnalysis {
167
+ const readOnlyBoundary = NO_EDIT_BOUNDARY_ASSERTION_PATTERN.test(taskText);
144
168
  let present = REVIEW_ONLY_PATTERNS.some((pattern) => pattern.test(taskText))
145
- || NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText));
146
- let blanket = present;
147
- let strippedText = stripPatterns(taskText, [...REVIEW_ONLY_PATTERNS, ...NO_TOOL_INTENT_PATTERNS]);
169
+ || NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText))
170
+ || readOnlyBoundary;
171
+ let blanket = false;
172
+ let strippedText = stripPatterns(taskText, [...REVIEW_ONLY_PATTERNS, ...NO_TOOL_INTENT_PATTERNS, ADVISORY_INFINITIVE_PATTERN]);
173
+ if (readOnlyBoundary) strippedText = stripPatterns(strippedText, [NO_EDIT_BOUNDARY_ASSERTION_PATTERN]);
148
174
  const stripNoEditProhibition = (match: string, object: string, offset: number, source: string): string => {
149
175
  present = true;
150
176
  if (GENERIC_PROHIBITION_OBJECT.test(object) && !hasScopedProhibitionContinuation(source.slice(offset + match.length))) blanket = true;
@@ -172,16 +198,23 @@ function hasImplementationIntent(agent: string, taskText: string): boolean {
172
198
  }
173
199
 
174
200
  export function classifyTaskMutationIntent(agent: string, task: string): TaskMutationIntent {
175
- const taskText = stripSeverityCompounds(stripFrameworkInstructions(task));
201
+ const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), [FINDING_CLASSIFICATION_PATTERN]);
176
202
  const taskTextWithoutScopedConstraints = stripPatterns(taskText, SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
177
203
  const prohibitions = analyzeNoEditProhibitions(taskTextWithoutScopedConstraints);
178
204
  if (prohibitions.present) {
179
205
  if (prohibitions.blanket) return { kind: "read-only" };
180
- return hasImplementationIntent(agent, prohibitions.strippedText) ? { kind: "implementation" } : { kind: "read-only" };
206
+ const remaining = stripPathLikeTokens(prohibitions.strippedText);
207
+ if (isReviewerStyleAgent(agent)) {
208
+ return hasImplementationIntent(agent, remaining) ? { kind: "implementation" } : { kind: "read-only" };
209
+ }
210
+ return EXPLICIT_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(remaining))
211
+ || FOLLOW_ON_IMPLEMENTATION_PATTERN.test(remaining)
212
+ ? { kind: "implementation" }
213
+ : { kind: "read-only" };
181
214
  }
182
215
 
183
216
  if (RESEARCH_AGENT_PATTERNS.some((pattern) => pattern.test(agent))) return { kind: "read-only" };
184
- if (hasImplementationIntent(agent, taskText)) return { kind: "implementation" };
217
+ if (hasImplementationIntent(agent, stripPathLikeTokens(taskText))) return { kind: "implementation" };
185
218
  if (isReviewerStyleAgent(agent)) return { kind: "read-only" };
186
219
  return taskHasReadOnlyDeliverable(taskTextWithoutScopedConstraints) ? { kind: "read-only" } : { kind: "unknown" };
187
220
  }
@@ -204,7 +237,7 @@ const MAY_MUTATE_VERB_PATTERN = /\b(?:fix|implement|update|write|edit|modify|mig
204
237
  * does.
205
238
  */
206
239
  export function taskMayMutate(task: string): boolean {
207
- const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
240
+ const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), [FINDING_CLASSIFICATION_PATTERN, ...SCOPED_NO_EDIT_CONSTRAINT_PATTERNS]);
208
241
  const prohibitions = analyzeNoEditProhibitions(taskText);
209
242
  if (prohibitions.blanket) return false;
210
243
  return MAY_MUTATE_VERB_PATTERN.test(stripPatterns(prohibitions.strippedText, READ_ONLY_DELIVERABLE_PATTERNS));
@@ -0,0 +1,18 @@
1
+ import type { AsyncStatus, SubagentState } from "../../shared/types.ts";
2
+
3
+ /** Projection-only guidance, not a control route or proof of current child liveness. */
4
+ export function workflowAsyncChildSteeringGuidance(status: AsyncStatus, state?: SubagentState): string[] {
5
+ if (status.mode !== "workflow" || (status.state !== "running" && status.state !== "queued")
6
+ || !state?.currentSessionId || status.sessionId !== state.currentSessionId
7
+ || !state.workflowControllers?.has(status.runId)) return [];
8
+ const ids = new Set((status.steps ?? []).flatMap((step) =>
9
+ step.async === true && step.status === "running"
10
+ && step.runner?.type !== "external-cli" && step.runner?.type !== "external-job"
11
+ && typeof step.runId === "string" && /^[A-Za-z0-9_-]+$/.test(step.runId) && step.runId !== status.runId
12
+ ? [step.runId] : []));
13
+ if (ids.size === 0) return [];
14
+ return [
15
+ "Async children recorded as running; direct steering rechecks controls. Choose an exact child ID (queued does not mean consumed):",
16
+ ...[...ids].map((id) => ` subagent({ action: "steer", id: "${id}", mode: "follow_up", message: "..." })`),
17
+ ];
18
+ }
@@ -15,6 +15,7 @@ import type {
15
15
  } from "../../shared/types.ts";
16
16
  import { getAgentDir } from "../../shared/utils.ts";
17
17
  import { isTerminalParallelHandoffChildStatus } from "./parallel-handoff.ts";
18
+ import { MACHINE_DIFF_OPTIONS, validateWorktreePatchRepresentsCurrentWorktree } from "./worktree.ts";
18
19
 
19
20
  export const WORKTREE_CLEANUP_PLAN_VERSION = 1 as const;
20
21
  export const WORKTREE_CLEANUP_PLAN_TTL_MS = 30 * 60 * 1000;
@@ -572,7 +573,7 @@ function resolveBranchTip(repoRoot: string, branch: string): { value?: string; e
572
573
  return { value: result.stdout.trim() };
573
574
  }
574
575
 
575
- function isPatchCaptured(record: ManifestMetadataRecord, worktreePath: string): { path?: string; error?: string } {
576
+ function isPatchCaptured(record: ManifestMetadataRecord, worktreePath: string, baseCommit: string): { path?: string; error?: string } {
576
577
  const patchPath = metadataPatchPath(record);
577
578
  if (!patchPath || record.child.patch?.error !== undefined || record.child.patch?.changed !== true) return {};
578
579
  const inspection = inspectPath(patchPath);
@@ -587,6 +588,8 @@ function isPatchCaptured(record: ManifestMetadataRecord, worktreePath: string):
587
588
  if (!patchStat.isFile()) return { error: "captured handoff patch is not a file" };
588
589
  if (pathInside(worktreePath, inspection.realpath)) return { error: "durable handoff patch lives inside the worktree" };
589
590
  if (patchStat.size <= 0) return { error: "captured handoff patch is empty" };
591
+ const validationError = validateWorktreePatchRepresentsCurrentWorktree(worktreePath, baseCommit, patchPath);
592
+ if (validationError) return { error: `captured handoff patch failed validation: ${validationError}` };
590
593
  return { path: patchPath };
591
594
  }
592
595
 
@@ -665,14 +668,14 @@ function buildManagedEntry(input: {
665
668
  entry.preconditions.statusDigest = status.digest;
666
669
  if (status.output && status.output.trim()) return blockedEntry(entry, "dirty", "keep", "worktree has uncommitted or untracked changes");
667
670
 
668
- const diff = runGit(worktreePath, ["diff", "--quiet", resolvedBase.value, "--"]);
671
+ const diff = runGit(worktreePath, ["diff", "--quiet", ...MACHINE_DIFF_OPTIONS, resolvedBase.value, "--"]);
669
672
  if (diff.status !== 0 && diff.status !== 1) return blockedEntry(entry, "unknown", "unknown", `git diff safety check failed: ${gitFailure(diff, "git diff")}`);
670
673
  const ancestor = runGit(repoRoot, ["merge-base", "--is-ancestor", git.head, targetHead]);
671
674
  if (ancestor.status !== 0 && ancestor.status !== 1) return blockedEntry(entry, "unknown", "unknown", `local merge safety check failed: ${gitFailure(ancestor, "git merge-base --is-ancestor")}`);
672
675
  const branchTipIsAncestor = ancestor.status === 0;
673
676
  let divergenceSafe = diff.status === 0;
674
677
  if (!divergenceSafe) {
675
- const captured = isPatchCaptured(record, worktreePath);
678
+ const captured = isPatchCaptured(record, worktreePath, resolvedBase.value);
676
679
  if (captured.error) return blockedEntry(entry, "ineligible", "keep", captured.error);
677
680
  if (captured.path) {
678
681
  entry.patchPath = captured.path;
@@ -0,0 +1,213 @@
1
+ import { spawn } from "node:child_process";
2
+ import { createOwnedProcessTreeController } from "../background/owned-process-tree.ts";
3
+ import type { ProcessTreeTerminal } from "../../shared/types.ts";
4
+
5
+ function terminateCommandTree(pid: number, controller: ReturnType<typeof createOwnedProcessTreeController>): Promise<ProcessTreeTerminal> {
6
+ if (process.platform !== "win32") return controller.terminate();
7
+ return new Promise((resolve) => {
8
+ let settled = false;
9
+ const fallback = () => {
10
+ if (settled) return;
11
+ settled = true;
12
+ void controller.terminate().then(resolve);
13
+ };
14
+ const cleanup = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
15
+ cleanup.once("error", fallback);
16
+ cleanup.once("close", (status) => {
17
+ if (settled) return;
18
+ if (status !== 0) return fallback();
19
+ settled = true;
20
+ resolve({ state: "observed", mechanism: "windows-taskkill", pid, verifiedAt: Date.now() });
21
+ });
22
+ });
23
+ }
24
+
25
+ export interface SetupCommandOptions {
26
+ cwd?: string;
27
+ env?: NodeJS.ProcessEnv;
28
+ input?: string;
29
+ /** Worktrunk uses 128 KiB; Git and hooks use spawnSync's 1 MiB default. */
30
+ maxBuffer?: number;
31
+ signal?: AbortSignal;
32
+ deadlineAt?: number;
33
+ /** Only the existing configured setup-hook timeout, not a new Git budget. */
34
+ hookTimeoutMs?: number;
35
+ /** Read-only probes may define negative answers as completed commands. */
36
+ acceptedExitCodes?: readonly number[];
37
+ onSpawn?: (process: { pid: number; processGroupId?: number }) => void;
38
+ }
39
+
40
+ export interface SetupCommandResult {
41
+ stdout: string;
42
+ stdoutBuffer: Buffer;
43
+ stderr: string;
44
+ status: number | null;
45
+ signal: NodeJS.Signals | null;
46
+ error?: Error;
47
+ pid?: number;
48
+ processGroupId?: number;
49
+ /** Absent on normal completion: trusted command completion is NOT tree proof. */
50
+ processTree?: ProcessTreeTerminal;
51
+ outputIncomplete: boolean;
52
+ }
53
+
54
+ function commandError(message: string, code: string): NodeJS.ErrnoException {
55
+ return Object.assign(new Error(message), { code });
56
+ }
57
+
58
+ /**
59
+ * Setup I/O only. Commands must await their descendants before reporting success.
60
+ * Exit 0 + natural close + complete output still requires caller JSON/path validation.
61
+ * Invalid output is NOT accepted completion: retain unknown ownership, never signal
62
+ * this completed command's PID later. Callers own compensation and admission.
63
+ */
64
+ export async function runSetupCommand(
65
+ command: string,
66
+ args: string[],
67
+ options: SetupCommandOptions,
68
+ ): Promise<SetupCommandResult> {
69
+ const result: SetupCommandResult = {
70
+ stdout: "", stdoutBuffer: Buffer.alloc(0), stderr: "", status: null, signal: null, outputIncomplete: false,
71
+ };
72
+ const maxBuffer = options.maxBuffer ?? 1024 * 1024;
73
+ if (!Number.isSafeInteger(maxBuffer) || maxBuffer <= 0) throw new Error("Invalid setup command maxBuffer");
74
+ if (options.deadlineAt !== undefined && !Number.isFinite(options.deadlineAt)) throw new Error("Invalid setup deadline");
75
+ if (options.hookTimeoutMs !== undefined && (!Number.isSafeInteger(options.hookTimeoutMs) || options.hookTimeoutMs <= 0)) {
76
+ throw new Error("Invalid setup hook timeout");
77
+ }
78
+ const cancellation = (): Error | undefined => {
79
+ if (options.signal?.aborted) return commandError("Worktree setup aborted", "ABORT_ERR");
80
+ if (options.deadlineAt !== undefined && Date.now() >= options.deadlineAt) {
81
+ return commandError("Worktree setup deadline exceeded", "ETIMEDOUT");
82
+ }
83
+ return undefined;
84
+ };
85
+ result.error = cancellation();
86
+ if (result.error) return result;
87
+
88
+ let child;
89
+ try {
90
+ child = spawn(command, args, {
91
+ cwd: options.cwd,
92
+ env: options.env ? { ...process.env, ...options.env } : process.env,
93
+ stdio: "pipe", shell: false, windowsHide: true,
94
+ // Isolated owned POSIX group, never unref'd or fire-and-forget.
95
+ detached: process.platform !== "win32",
96
+ });
97
+ } catch (error) {
98
+ result.error = error instanceof Error ? error : new Error(String(error));
99
+ return result;
100
+ }
101
+ result.pid = child.pid;
102
+ if (child.pid !== undefined && process.platform !== "win32") result.processGroupId = child.pid;
103
+ const tree = child.pid === undefined ? undefined : createOwnedProcessTreeController(child.pid);
104
+ let termination: Promise<ProcessTreeTerminal> | undefined;
105
+ let directSettled = false;
106
+ const releaseUnknownIO = () => {
107
+ if (!directSettled || result.processTree?.state !== "unknown") return;
108
+ const detail = result.processTree.diagnostic ? `: ${result.processTree.diagnostic}` : "";
109
+ result.error = commandError(`Worktree setup process tree settlement is unverified${detail}`, "PROCESS_TREE_UNVERIFIED");
110
+ result.outputIncomplete = true;
111
+ // Only local I/O is released; unknown descendant ownership remains retained.
112
+ child.stdin.destroy();
113
+ child.stdout.destroy();
114
+ child.stderr.destroy();
115
+ };
116
+ const terminate = () => {
117
+ if (termination || !tree) return;
118
+ if (directSettled) {
119
+ result.processTree = {
120
+ state: "unknown", reason: "verification-failed",
121
+ diagnostic: "Command exited before termination began; no longer safe to signal its recorded PID.",
122
+ };
123
+ releaseUnknownIO();
124
+ return;
125
+ }
126
+ termination = terminateCommandTree(result.pid!, tree).then((proof) => {
127
+ result.processTree = proof;
128
+ releaseUnknownIO();
129
+ return proof;
130
+ });
131
+ };
132
+ const fail = (error: Error) => {
133
+ result.error ??= error;
134
+ terminate();
135
+ };
136
+ const onAbort = () => fail(commandError("Worktree setup aborted", "ABORT_ERR"));
137
+ const stdout: Buffer[] = [];
138
+ const stderr: Buffer[] = [];
139
+ let capturedBytes = 0;
140
+ const capture = (chunks: Buffer[], chunk: Buffer) => {
141
+ const remaining = maxBuffer - capturedBytes;
142
+ if (remaining > 0) {
143
+ const saved = Buffer.from(chunk.subarray(0, remaining));
144
+ chunks.push(saved);
145
+ capturedBytes += saved.length;
146
+ }
147
+ if (chunk.length > remaining) {
148
+ result.outputIncomplete = true;
149
+ fail(commandError("Worktree setup command output exceeds maxBuffer", "ENOBUFS"));
150
+ }
151
+ };
152
+ const onStdout = (chunk: Buffer) => capture(stdout, chunk);
153
+ const onStderr = (chunk: Buffer) => capture(stderr, chunk);
154
+ child.stdout.on("data", onStdout);
155
+ child.stderr.on("data", onStderr);
156
+ child.stdin.on("error", fail);
157
+ const close = new Promise<void>((resolve) => child.once("close", () => resolve()));
158
+ const directExit = new Promise<void>((resolve) => {
159
+ child.once("exit", (status, signal) => {
160
+ directSettled = true;
161
+ result.status = status;
162
+ result.signal = signal;
163
+ if (status === null || !(options.acceptedExitCodes ?? [0]).includes(status)) terminate();
164
+ releaseUnknownIO();
165
+ resolve();
166
+ });
167
+ child.once("error", (error) => {
168
+ fail(error);
169
+ // A failed spawn has no direct process to await. Other errors do not prove exit.
170
+ if (child.pid === undefined) {
171
+ directSettled = true;
172
+ resolve();
173
+ }
174
+ });
175
+ });
176
+ let timer: ReturnType<typeof setTimeout> | undefined;
177
+ const deadlineAt = Math.min(options.deadlineAt ?? Infinity,
178
+ options.hookTimeoutMs === undefined ? Infinity : Date.now() + options.hookTimeoutMs);
179
+ const armDeadline = () => {
180
+ if (deadlineAt === Infinity) return;
181
+ const remaining = deadlineAt - Date.now();
182
+ if (remaining <= 0) fail(commandError("Worktree setup command timed out", "ETIMEDOUT"));
183
+ else timer = setTimeout(armDeadline, Math.min(remaining, 2 ** 31 - 1));
184
+ };
185
+ options.signal?.addEventListener("abort", onAbort, { once: true });
186
+ try {
187
+ armDeadline();
188
+ if (options.signal?.aborted) onAbort();
189
+ if (child.pid !== undefined) {
190
+ try { options.onSpawn?.({ pid: child.pid, processGroupId: result.processGroupId }); }
191
+ catch (error) { fail(error instanceof Error ? error : new Error(String(error))); }
192
+ }
193
+ child.stdin.end(options.input);
194
+ await directExit;
195
+ if (termination) result.processTree = await termination;
196
+ releaseUnknownIO();
197
+ await close;
198
+ // Abort/overflow may arrive while draining stdio after direct exit.
199
+ if (termination) result.processTree = await termination;
200
+ const cancelled = cancellation();
201
+ if (cancelled) fail(cancelled);
202
+ result.stdoutBuffer = Buffer.concat(stdout);
203
+ result.stdout = result.stdoutBuffer.toString("utf8");
204
+ result.stderr = Buffer.concat(stderr).toString("utf8");
205
+ return result;
206
+ } finally {
207
+ if (timer) clearTimeout(timer);
208
+ options.signal?.removeEventListener("abort", onAbort);
209
+ child.stdout.removeListener("data", onStdout);
210
+ child.stderr.removeListener("data", onStderr);
211
+ child.stdin.removeListener("error", fail);
212
+ }
213
+ }