@xzzpig/pi-subagents 0.14.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (198) hide show
  1. package/CHANGELOG.md +233 -0
  2. package/README.md +6 -5
  3. package/agents/evidence-auditor.md +34 -0
  4. package/agents/researcher.md +23 -13
  5. package/agents/reviewer.md +3 -2
  6. package/docs/agents.md +56 -15
  7. package/docs/configuration.md +92 -14
  8. package/docs/extension-api.md +132 -19
  9. package/docs/missions.md +10 -2
  10. package/docs/models.md +11 -22
  11. package/docs/observability.md +63 -11
  12. package/docs/standalone-background.md +59 -0
  13. package/docs/tool-reference.md +42 -23
  14. package/docs/watchdog.md +39 -10
  15. package/docs/workflows.md +58 -19
  16. package/index.ts +5 -2
  17. package/inspector-runner.mjs +2 -2
  18. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +13 -3
  19. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +18 -6
  20. package/node_modules/@xzzpig/pi-components/src/transcript.ts +26 -6
  21. package/package.json +9 -4
  22. package/prompts/parallel-review.md +1 -1
  23. package/runner-peer-loader.mjs +24 -0
  24. package/runner-peer-preload.mjs +36 -0
  25. package/skills/pi-subagents/SKILL.md +34 -22
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  27. package/skills/pi-subagents/references/execution-controls.md +27 -8
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
  31. package/skills/pi-subagents/references/review-and-validation.md +3 -3
  32. package/src/agents/advertised-agent-prompt.ts +94 -0
  33. package/src/agents/agent-management.ts +71 -59
  34. package/src/agents/agent-serializer.ts +6 -3
  35. package/src/agents/agents.ts +198 -72
  36. package/src/agents/builtin-names.ts +1 -0
  37. package/src/agents/chain-serializer.ts +5 -0
  38. package/src/agents/runtime-agent-registry.ts +7 -6
  39. package/src/api/delegation.ts +4 -0
  40. package/src/api/preflight.ts +110 -71
  41. package/src/api/required-child-extensions.ts +6 -0
  42. package/src/api/shared-types.ts +3 -1
  43. package/src/api/workflow-resources.ts +6 -0
  44. package/src/extension/config.ts +14 -37
  45. package/src/extension/fanout-child.ts +68 -5
  46. package/src/extension/herdr-pi-bridge.ts +164 -0
  47. package/src/extension/index.ts +141 -51
  48. package/src/extension/public-execution.ts +7 -6
  49. package/src/extension/rpc.ts +8 -21
  50. package/src/extension/schemas.ts +86 -84
  51. package/src/extension/tool-description.ts +32 -79
  52. package/src/inspectors/actions.ts +148 -0
  53. package/src/inspectors/ghostty/actions.ts +74 -0
  54. package/src/inspectors/ghostty/plugin.ts +17 -0
  55. package/src/inspectors/herdr/actions.ts +99 -179
  56. package/src/inspectors/herdr/plugin.ts +20 -0
  57. package/src/inspectors/herdr/project-panes.ts +4 -1
  58. package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
  59. package/src/inspectors/plugins.ts +8 -0
  60. package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
  61. package/src/inspectors/types.ts +51 -0
  62. package/src/integrations/pi-web-session-liveness.ts +73 -0
  63. package/src/intercom/intercom-bridge.ts +50 -8
  64. package/src/intercom/native-supervisor-channel.ts +142 -115
  65. package/src/intercom/supervisor-ui.ts +3 -2
  66. package/src/missions/workflow-state.ts +37 -16
  67. package/src/policy/authority.ts +4 -0
  68. package/src/profiles/profiles.ts +12 -6
  69. package/src/runs/background/active-async-capacity.ts +22 -18
  70. package/src/runs/background/active-run-index.ts +17 -1
  71. package/src/runs/background/async-execution.ts +359 -176
  72. package/src/runs/background/async-job-tracker.ts +41 -7
  73. package/src/runs/background/async-resume.ts +19 -12
  74. package/src/runs/background/async-retention.ts +20 -0
  75. package/src/runs/background/async-status-snapshot.ts +10 -12
  76. package/src/runs/background/async-status.ts +32 -13
  77. package/src/runs/background/auto-drain.ts +59 -35
  78. package/src/runs/background/binary-bootstrap.ts +38 -0
  79. package/src/runs/background/chain-append.ts +1 -1
  80. package/src/runs/background/chain-root-attachment.ts +22 -33
  81. package/src/runs/background/control-channel.ts +78 -44
  82. package/src/runs/background/fleet-view.ts +30 -2
  83. package/src/runs/background/notify.ts +193 -19
  84. package/src/runs/background/owned-process-tree.ts +35 -8
  85. package/src/runs/background/process-terminal.ts +23 -23
  86. package/src/runs/background/result-files.ts +8 -4
  87. package/src/runs/background/result-watcher.ts +19 -2
  88. package/src/runs/background/retained-nested-route-tracker.ts +96 -0
  89. package/src/runs/background/run-child-session.ts +118 -41
  90. package/src/runs/background/run-status.ts +78 -5
  91. package/src/runs/background/runner-aliases.ts +22 -5
  92. package/src/runs/background/runner-child-launch.ts +93 -0
  93. package/src/runs/background/runner-child-sessions.ts +5 -4
  94. package/src/runs/background/runner-http-dispatcher.ts +119 -0
  95. package/src/runs/background/scheduled-runs.ts +51 -18
  96. package/src/runs/background/stale-run-reconciler.ts +38 -12
  97. package/src/runs/background/steering.ts +20 -2
  98. package/src/runs/background/subagent-runner.ts +766 -432
  99. package/src/runs/background/subagent-wait.ts +179 -28
  100. package/src/runs/background/wait-completions.ts +79 -27
  101. package/src/runs/background/wait-subscriptions.ts +9 -3
  102. package/src/runs/background/wait-tool.ts +5 -3
  103. package/src/runs/foreground/async-steering-action.ts +37 -7
  104. package/src/runs/foreground/async-stop-action.ts +93 -3
  105. package/src/runs/foreground/execution.ts +174 -194
  106. package/src/runs/foreground/foreground-history.ts +5 -2
  107. package/src/runs/foreground/prompt-audit.ts +12 -6
  108. package/src/runs/foreground/subagent-executor.ts +896 -397
  109. package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
  110. package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
  111. package/src/runs/shared/acceptance.ts +54 -14
  112. package/src/runs/shared/agent-contract.ts +1 -1
  113. package/src/runs/shared/async-status-projection.ts +172 -78
  114. package/src/runs/shared/capability-ceiling.ts +2 -0
  115. package/src/runs/shared/child-hooks.ts +167 -3
  116. package/src/runs/shared/child-launch-plan.ts +15 -3
  117. package/src/runs/shared/child-launch.ts +44 -16
  118. package/src/runs/shared/child-lifecycle.ts +6 -3
  119. package/src/runs/shared/child-runtime-config.ts +8 -1
  120. package/src/runs/shared/child-session.ts +130 -24
  121. package/src/runs/shared/child-tool-plan.ts +145 -14
  122. package/src/runs/shared/completion-evidence.ts +2 -2
  123. package/src/runs/shared/completion-guard.ts +6 -3
  124. package/src/runs/shared/dynamic-fanout.ts +2 -2
  125. package/src/runs/shared/effective-system-prompt.ts +33 -0
  126. package/src/runs/shared/external-cli-contract.ts +11 -1
  127. package/src/runs/shared/external-cli-preflight.ts +6 -2
  128. package/src/runs/shared/external-cli-runner.ts +9 -7
  129. package/src/runs/shared/herdr-connection.ts +134 -0
  130. package/src/runs/shared/herdr-external-adapters.ts +169 -0
  131. package/src/runs/shared/herdr-machine.ts +279 -0
  132. package/src/runs/shared/herdr-pi-protocol.ts +59 -0
  133. package/src/runs/shared/herdr-placed-run.ts +263 -0
  134. package/src/runs/shared/host-step-status.ts +11 -11
  135. package/src/runs/shared/llm-intent-arbiter.ts +40 -21
  136. package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
  137. package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
  138. package/src/runs/shared/model-scope.ts +1 -1
  139. package/src/runs/shared/nested-events.ts +19 -10
  140. package/src/runs/shared/orca-progress-tabs.ts +7 -1
  141. package/src/runs/shared/parallel-handoff.ts +57 -12
  142. package/src/runs/shared/parallel-utils.ts +10 -4
  143. package/src/runs/shared/pi-spawn.ts +10 -0
  144. package/src/runs/shared/readonly-drain-observation.ts +42 -0
  145. package/src/runs/shared/run-fanout-budget.ts +8 -8
  146. package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
  147. package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
  148. package/src/runs/shared/task-intent.ts +46 -13
  149. package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
  150. package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
  151. package/src/runs/shared/worktree-setup-command.ts +213 -0
  152. package/src/runs/shared/worktree.ts +437 -214
  153. package/src/shared/child-cache-retention.ts +43 -0
  154. package/src/shared/fork-context.ts +15 -72
  155. package/src/shared/launch-contract.ts +70 -8
  156. package/src/shared/model-response-aliases.ts +13 -0
  157. package/src/shared/opencode-session-headers.ts +30 -0
  158. package/src/shared/pruned-fork.ts +1 -1
  159. package/src/shared/required-child-extensions.ts +81 -0
  160. package/src/shared/settings.ts +5 -2
  161. package/src/shared/shortcuts.ts +0 -4
  162. package/src/shared/types.ts +163 -90
  163. package/src/shared/utils.ts +10 -2
  164. package/src/shared/watch-strategy.ts +2 -0
  165. package/src/shared/workflow-child-permit.ts +18 -13
  166. package/src/slash/delegation-adapters.ts +3 -1
  167. package/src/slash/delegation-request.ts +14 -0
  168. package/src/slash/slash-commands.ts +2 -7
  169. package/src/slash/subagents-admin.ts +31 -14
  170. package/src/tui/fleet-status.ts +165 -20
  171. package/src/tui/fleet.ts +30 -19
  172. package/src/tui/render.ts +210 -50
  173. package/src/watchdog/child-status.ts +28 -28
  174. package/src/watchdog/lsp-diagnostics.ts +1 -1
  175. package/src/watchdog/model-selection.ts +21 -1
  176. package/src/watchdog/permission-arbiter.ts +5 -2
  177. package/src/watchdog/register-child.ts +10 -2
  178. package/src/watchdog/register-main.ts +39 -35
  179. package/src/watchdog/render.ts +1 -1
  180. package/src/watchdog/review.ts +122 -74
  181. package/src/watchdog/rules.ts +1 -1
  182. package/src/watchdog/runtime.ts +100 -27
  183. package/src/watchdog/scope.ts +1 -1
  184. package/src/watchdog/settings.ts +3 -0
  185. package/src/watchdog/tool-actions.ts +13 -12
  186. package/src/watchdog/turn-delta.ts +23 -0
  187. package/src/watchdog/types.ts +5 -3
  188. package/src/watchdog/warning-format.ts +1 -1
  189. package/src/workflows/chat-progress.ts +3 -3
  190. package/src/workflows/scripted-workflow.ts +349 -26
  191. package/src/workflows/workflow-checklist.ts +17 -20
  192. package/src/workflows/workflow-child-summary.ts +57 -8
  193. package/src/workflows/workflow-preflight.ts +19 -19
  194. package/src/workflows/workflow-receipt.ts +24 -6
  195. package/src/workflows/workflow-resources.ts +108 -22
  196. package/src/workflows/workflow-settlement.ts +3 -0
  197. package/src/runs/shared/model-exclusions.ts +0 -373
  198. /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
@@ -94,7 +94,7 @@ function workflowResultChildren(status: AsyncStatus, childRunId: string, result:
94
94
  }));
95
95
  }
96
96
 
97
- function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, result: SingleResult, asyncDir: string, resolution: WorkflowTerminalResolution | undefined): WorkflowReceipt | undefined {
97
+ function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, result: SingleResult, asyncDir: string, resolution: WorkflowTerminalResolution | undefined): { receipt: WorkflowReceipt; path: string } | undefined {
98
98
  const receiptRoot = path.dirname(asyncDir);
99
99
  const receiptPath = workflowReceiptPath(receiptRoot, status.runId);
100
100
  if (!fs.existsSync(receiptPath)) return undefined;
@@ -155,8 +155,7 @@ function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, resul
155
155
  delete next.workflowResolution;
156
156
  delete next.recovery;
157
157
  }
158
- writeWorkflowReceipt(asyncDir, next);
159
- return next;
158
+ return { receipt: next, path: writeWorkflowReceipt(asyncDir, next) };
160
159
  }
161
160
 
162
161
  function appendDetachedWorkflowEvent(asyncDir: string, event: Record<string, unknown>): void {
@@ -209,10 +208,13 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
209
208
  if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
210
209
  }
211
210
  let receipt: WorkflowReceipt | undefined;
211
+ let receiptPath: string | undefined;
212
212
  let receiptError: string | undefined;
213
213
  const resolution = classifyWorkflowSettlement(next, input.result.interrupted);
214
214
  try {
215
- receipt = reconcileWorkflowReceipt(next, input.childRunId, input.result, asyncDir, resolution);
215
+ const publication = reconcileWorkflowReceipt(next, input.childRunId, input.result, asyncDir, resolution);
216
+ receipt = publication?.receipt;
217
+ receiptPath = publication?.path;
216
218
  } catch (error) {
217
219
  receiptError = `Failed to reconcile async workflow receipt: ${error instanceof Error ? error.message : String(error)}`;
218
220
  }
@@ -241,9 +243,10 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
241
243
  cwd: next.cwd,
242
244
  sessionId: next.sessionId ?? (typeof existing?.sessionId === "string" ? existing.sessionId : undefined),
243
245
  completionOwnerId: next.completionOwnerId,
246
+ ...(next.scheduleOrigin ? { scheduleOrigin: next.scheduleOrigin } : {}),
244
247
  },
245
248
  receipt,
246
- receiptPath: path.join(asyncDir, "workflow-receipt.json"),
249
+ receiptPath,
247
250
  receiptPersistenceError: receiptError,
248
251
  resolution,
249
252
  terminalOutcome: receipt?.terminalOutcome,
@@ -283,6 +286,7 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
283
286
  agent: "workflow",
284
287
  success: plan.status.state === "complete",
285
288
  state: plan.status.state,
289
+ ...(plan.publicResult.workflowReceipt ? { workflowReceipt: plan.publicResult.workflowReceipt } : {}),
286
290
  ...(resolution ? { workflowResolution: resolution } : {}),
287
291
  ...(plan.receipt?.terminalOutcome ? { terminalOutcome: plan.receipt.terminalOutcome } : {}),
288
292
  recovery: plan.recovery,
@@ -291,6 +295,7 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
291
295
  results,
292
296
  sessionId: plan.status.sessionId,
293
297
  completionOwnerId: plan.status.completionOwnerId,
298
+ ...(plan.status.scheduleOrigin ? { scheduleOrigin: plan.status.scheduleOrigin } : {}),
294
299
  timestamp: Date.now(),
295
300
  triggerTurn: true,
296
301
  });
@@ -3,8 +3,10 @@ import * as path from "node:path";
3
3
  import type { AgentToolResult } from "@earendil-works/pi-agent-core";
4
4
  import type { Details, ForegroundRunControl, SubagentState } from "../../shared/types.ts";
5
5
  import { readStatus } from "../../shared/utils.ts";
6
- import { steeringReceipt } from "../background/steering.ts";
7
- import type { SteerDeliveryMode } from "../background/control-channel.ts";
6
+ import { steeringReceipt, waitForSteeringAction } from "../background/steering.ts";
7
+ import { requestAsyncSteer, type SteerDeliveryMode } from "../background/control-channel.ts";
8
+ import { currentCompletionOwnerId } from "../../shared/completion-owner.ts";
9
+ import { workflowAsyncChildSteeringGuidance } from "../shared/workflow-async-child-guidance.ts";
8
10
 
9
11
  export interface WorkflowForegroundSteeringTarget {
10
12
  control: ForegroundRunControl;
@@ -66,6 +68,58 @@ function managementError(message: string): AgentToolResult<Details> {
66
68
  return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
67
69
  }
68
70
 
71
+ /** Local controllers remain authoritative; recorded foreign ownership permits enqueue, not takeover or proof of liveness. */
72
+ export async function steerWorkflowRun(input: {
73
+ state: SubagentState;
74
+ runId: string;
75
+ asyncDir: string;
76
+ message: string;
77
+ mode?: SteerDeliveryMode;
78
+ index?: number;
79
+ signal?: AbortSignal;
80
+ ackTimeoutMs?: number;
81
+ }): Promise<AgentToolResult<Details>> {
82
+ const { state, runId, asyncDir } = input;
83
+ const status = readStatus(asyncDir);
84
+ if (!status || status.mode !== "workflow" || status.runId !== runId || path.basename(asyncDir) !== runId) {
85
+ return managementError(`Workflow '${runId}' does not match its resolved run directory.`);
86
+ }
87
+ if (state.workflowControllers?.has(runId)) {
88
+ const route = resolveWorkflowForegroundSteeringTarget({ state, workflowRunId: runId, asyncDirRoot: path.dirname(asyncDir) });
89
+ if (!route.ok) return managementError([route.message, ...workflowAsyncChildSteeringGuidance(status, state)].join("\n"));
90
+ return steerWorkflowForegroundTarget({ target: route.target, message: input.message, mode: input.mode, index: input.index });
91
+ }
92
+ if (!state.currentSessionId) return managementError("Workflow steering requires an active parent session.");
93
+ if (status.sessionId !== state.currentSessionId) return managementError(`Workflow '${runId}' was not found in the active session.`);
94
+ if (status.state !== "running" && status.state !== "queued") return managementError(`Workflow '${runId}' is not running or queued and cannot be steered.`);
95
+ if (typeof status.completionOwnerId !== "string" || !status.completionOwnerId.trim()
96
+ || status.completionOwnerId === (state.completionOwnerId ?? currentCompletionOwnerId())
97
+ || [...state.foregroundControls.values()].some((control) => control.parentWorkflowRunId === runId)) {
98
+ return managementError(`Workflow '${runId}' has no live foreground child and is not a recorded foreign workflow.`);
99
+ }
100
+ if (input.index !== undefined) {
101
+ const step = status.steps?.[input.index];
102
+ if (!Number.isInteger(input.index) || input.index < 0 || !step) return managementError(`Workflow '${runId}' index ${input.index} is out of range or invalid.`);
103
+ if (step.status !== "running" && step.status !== "pending") return managementError(`Workflow '${runId}' child ${input.index} is ${step.status} and cannot be steered.`);
104
+ if (typeof step.workflowKey !== "string" || !step.workflowKey.trim()) return managementError(`Workflow '${runId}' child ${input.index} has no projected workflow key.`);
105
+ }
106
+ const requestId = randomUUID();
107
+ try {
108
+ requestAsyncSteer(asyncDir, { id: requestId, message: input.message, mode: input.mode, ...(input.index !== undefined ? { targetIndex: input.index } : {}), source: "steer-action" });
109
+ } catch (error) {
110
+ return managementError(`Failed to queue steering for workflow ${runId}: ${error instanceof Error ? error.message : String(error)}`);
111
+ }
112
+ // Only the owner writes the ledger. No acknowledgment leaves an honest, unaddressed queued receipt.
113
+ const steering = await waitForSteeringAction({ asyncDir, sourceRunId: runId, requestId, timeoutMs: input.ackTimeoutMs ?? 3_000, signal: input.signal })
114
+ ?? { requestId, state: "pending" as const, deliveryStatus: "queued" as const, sourceRunId: runId, targets: input.index === undefined ? [] : [{ index: input.index, state: "pending" as const }] };
115
+ const failed = steering.state === "failed" || steering.state === "partial";
116
+ return {
117
+ content: [{ type: "text", text: steeringReceipt(input.message, `Steering ${failed ? steering.state : steering.deliveryStatus === "delivered" ? "delivered" : "queued"} for workflow ${runId} (request ${requestId}).`) }],
118
+ ...(failed ? { isError: true } : {}),
119
+ details: { mode: "management", results: [], steering },
120
+ };
121
+ }
122
+
69
123
  /**
70
124
  * Steer a live workflow-owned foreground child through its in-process session.
71
125
  * `steer` (and `auto`) interrupt the child at its next safe point; `follow_up`
@@ -91,6 +145,7 @@ export async function steerWorkflowForegroundTarget(input: {
91
145
 
92
146
  const message = input.message.trim();
93
147
  const requestId = randomUUID();
148
+
94
149
  const outcome = await child.steer({ message, ...(input.mode && input.mode !== "steer" ? { mode: input.mode } : {}) });
95
150
  const target = outcome.state === "delivered"
96
151
  ? { index, state: "delivered" as const, deliveredAt: Date.now() }
@@ -11,6 +11,7 @@ import type {
11
11
  AcceptanceLedger,
12
12
  AcceptanceLevel,
13
13
  AcceptanceReport,
14
+ AcceptanceReviewGate,
14
15
  AcceptanceRole,
15
16
  AcceptanceRuntimeCheck,
16
17
  AcceptanceRuntimeCheckStatus,
@@ -24,7 +25,7 @@ import type {
24
25
  ChildWatchdogProgress,
25
26
  } from "../../shared/types.ts";
26
27
  import { unresolvedChildWatchdogBlockers } from "../../watchdog/child-status.ts";
27
- import { isAgentContractV1 } from "./agent-contract.ts";
28
+ import { isAgentContract } from "./agent-contract.ts";
28
29
  import { classifyTaskMutationIntent, stripSeverityCompounds, taskMayMutate } from "./task-intent.ts";
29
30
 
30
31
  const LEVEL_RANK: Record<Exclude<AcceptanceLevel, "auto">, number> = {
@@ -105,11 +106,15 @@ function inferLevel(input: {
105
106
  const inferredReadOnly = readOnlyTask || ((readOnlyAgent || input.acceptanceRole === "read-only") && !taskMayWrite);
106
107
  const roleResolvesReadOnly = input.acceptanceRole !== undefined && inferredReadOnly;
107
108
  const dynamicResolvesReadOnly = inferredReadOnly && !writeTask;
108
- const keywordRiskReadOnly = input.acceptanceRole === undefined ? intent.kind === "read-only" : inferredReadOnly;
109
+ const riskyKeywordPattern = /\b(?:release|migration|migrate|security|data[- ]loss|destructive|post-review|fix pass)\b/;
110
+ // Topic keywords cannot override classified read-only intent; unknown tasks keep their risk gate.
111
+ const keywordRiskReadOnly = input.acceptanceRole === undefined
112
+ ? intent.kind === "read-only"
113
+ : inferredReadOnly;
109
114
  const risky = Boolean(input.async && writeTask)
110
115
  || (Boolean(input.dynamic) && !roleResolvesReadOnly && !dynamicResolvesReadOnly)
111
116
  || (Boolean(input.dynamicGroup) && !roleResolvesReadOnly && !dynamicResolvesReadOnly)
112
- || (!keywordRiskReadOnly && /\b(?:release|migration|migrate|security|data[- ]loss|destructive|post-review|fix pass)\b/.test(task));
117
+ || (!keywordRiskReadOnly && riskyKeywordPattern.test(task));
113
118
 
114
119
  if (risky) {
115
120
  reasons.push(input.async ? "async write-capable or risky run" : "risky write-capable run");
@@ -202,10 +207,23 @@ export function normalizeGateAcceptance(gate: unknown, acceptance: AcceptanceInp
202
207
  return normalized.error ? { ok: false, error: normalized.error } : { ok: true, acceptance: normalized.value as AcceptanceInput };
203
208
  }
204
209
  if (typeof gate !== "string" || !gate.trim()) return { ok: false, error: "gate must be a non-empty command string." };
205
- if (acceptance !== undefined) return { ok: false, error: "gate cannot be combined with acceptance; use one gate command or acceptance.verify." };
210
+ if (acceptance !== undefined && acceptance !== false) return { ok: false, error: "gate cannot be combined with acceptance; use one gate command or acceptance.verify." + describeGateAcceptanceConflict(gate, acceptance) };
206
211
  return { ok: true, acceptance: { level: "verified", verify: [{ id: "gate", command: gate.trim() }] } };
207
212
  }
208
213
 
214
+ export function describeGateAcceptanceConflict(gate: unknown, acceptance: unknown): string {
215
+ const render = (value: unknown): string => {
216
+ let encoded: string;
217
+ try {
218
+ encoded = JSON.stringify(value) ?? String(value);
219
+ } catch {
220
+ encoded = String(value);
221
+ }
222
+ return encoded.length > 120 ? `${encoded.slice(0, 120)}...` : encoded;
223
+ };
224
+ return ` Both fields were present: gate=${render(gate)} acceptance=${render(acceptance)}.`;
225
+ }
226
+
209
227
  function explicitAcceptanceCanDisable(explicit: AcceptanceConfig): boolean {
210
228
  return explicit.level === "none" && typeof explicit.reason === "string" && explicit.reason.trim().length > 0;
211
229
  }
@@ -354,7 +372,7 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
354
372
  return errors;
355
373
  }
356
374
 
357
- export function validateExecutionAcceptance(input: {
375
+ type ExecutionAcceptanceInput = {
358
376
  acceptance?: unknown;
359
377
  outputSchema?: unknown;
360
378
  tasks?: Array<{ acceptance?: unknown; outputSchema?: unknown }>;
@@ -363,23 +381,39 @@ export function validateExecutionAcceptance(input: {
363
381
  outputSchema?: unknown;
364
382
  parallel?: Array<{ acceptance?: unknown; outputSchema?: unknown }> | { acceptance?: unknown; outputSchema?: unknown };
365
383
  }>;
366
- }): string[] {
384
+ };
385
+
386
+ export function validateExecutionAcceptancePolicy(input: ExecutionAcceptanceInput): string[] {
367
387
  const errors = validateAcceptanceInput(input.acceptance, "acceptance");
368
- errors.push(...validateAcceptanceReportMode(input.acceptance, input.outputSchema, "acceptance"));
369
388
  for (const [index, task] of (input.tasks ?? []).entries()) {
370
389
  errors.push(...validateAcceptanceInput(task.acceptance, `tasks[${index}].acceptance`));
371
- errors.push(...validateAcceptanceReportMode(task.acceptance, task.outputSchema, `tasks[${index}].acceptance`));
372
390
  }
373
391
  for (const [stepIndex, step] of (input.chain ?? []).entries()) {
374
392
  errors.push(...validateAcceptanceInput(step.acceptance, `chain[${stepIndex}].acceptance`));
375
- errors.push(...validateAcceptanceReportMode(step.acceptance, step.outputSchema, `chain[${stepIndex}].acceptance`));
376
393
  if (Array.isArray(step.parallel)) {
377
394
  for (const [taskIndex, task] of step.parallel.entries()) {
378
395
  errors.push(...validateAcceptanceInput(task.acceptance, `chain[${stepIndex}].parallel[${taskIndex}].acceptance`));
379
- errors.push(...validateAcceptanceReportMode(task.acceptance, task.outputSchema, `chain[${stepIndex}].parallel[${taskIndex}].acceptance`));
380
396
  }
381
397
  } else if (step.parallel) {
382
398
  errors.push(...validateAcceptanceInput(step.parallel.acceptance, `chain[${stepIndex}].parallel.acceptance`));
399
+ }
400
+ }
401
+ return errors;
402
+ }
403
+
404
+ export function validateExecutionAcceptance(input: ExecutionAcceptanceInput): string[] {
405
+ const errors = validateExecutionAcceptancePolicy(input);
406
+ errors.push(...validateAcceptanceReportMode(input.acceptance, input.outputSchema, "acceptance"));
407
+ for (const [index, task] of (input.tasks ?? []).entries()) {
408
+ errors.push(...validateAcceptanceReportMode(task.acceptance, task.outputSchema, `tasks[${index}].acceptance`));
409
+ }
410
+ for (const [stepIndex, step] of (input.chain ?? []).entries()) {
411
+ errors.push(...validateAcceptanceReportMode(step.acceptance, step.outputSchema, `chain[${stepIndex}].acceptance`));
412
+ if (Array.isArray(step.parallel)) {
413
+ for (const [taskIndex, task] of step.parallel.entries()) {
414
+ errors.push(...validateAcceptanceReportMode(task.acceptance, task.outputSchema, `chain[${stepIndex}].parallel[${taskIndex}].acceptance`));
415
+ }
416
+ } else if (step.parallel) {
383
417
  errors.push(...validateAcceptanceReportMode(step.parallel.acceptance, step.parallel.outputSchema, `chain[${stepIndex}].parallel.acceptance`));
384
418
  }
385
419
  }
@@ -392,7 +426,7 @@ function validateAcceptanceReportMode(acceptance: unknown, outputSchema: unknown
392
426
  acceptance = normalized.value;
393
427
  if (!acceptance || typeof acceptance !== "object" || Array.isArray(acceptance)) return [];
394
428
  if (!("report" in acceptance)) return [];
395
- return outputSchema === undefined ? [`${pathLabel}.report requires outputSchema.`] : [];
429
+ return outputSchema === undefined || outputSchema === false ? [`${pathLabel}.report requires outputSchema.`] : [];
396
430
  }
397
431
 
398
432
  function normalizeCriteria(criteria: Array<string | { id?: string; must?: string; evidence?: AcceptanceEvidenceKind[]; severity?: "required" | "recommended" }> | undefined, evidence: AcceptanceEvidenceKind[]): ResolvedAcceptanceGate[] {
@@ -422,7 +456,7 @@ export function resolveEffectiveAcceptance(input: {
422
456
  }): ResolvedAcceptanceConfig {
423
457
  const explicit = normalizeAcceptanceInput(input.explicit);
424
458
  const explicitLevel = normalizeLevel(explicit.level);
425
- if (isAgentContractV1(input.agentContract)) {
459
+ if (isAgentContract(input.agentContract)) {
426
460
  const level = explicitAcceptanceCanDisable(explicit) || explicitLevel === "auto"
427
461
  ? "none"
428
462
  : explicitLevel;
@@ -473,6 +507,12 @@ function acceptanceRequiresChildReport(acceptance: ResolvedAcceptanceConfig): bo
473
507
  return acceptance.criteria.length > 0 || acceptance.evidence.length > 0;
474
508
  }
475
509
 
510
+ /** Label a declared review gate the same way in prompts and capability summaries. */
511
+ export function formatReviewGateLabel(review: AcceptanceReviewGate): string {
512
+ const status = review.required === false ? "optional" : "required";
513
+ return review.agent ? `${status} by ${review.agent}` : status;
514
+ }
515
+
476
516
  export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, options: { reportOptional?: boolean; structuredOutput?: boolean } = {}): string {
477
517
  if (acceptance.level === "none") return "";
478
518
  if (options.reportOptional && !acceptanceRequiresChildReport(acceptance)) return "";
@@ -492,7 +532,7 @@ export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, opt
492
532
  for (const command of acceptance.verify) lines.push(`- ${command.id}: ${command.command}`);
493
533
  }
494
534
  if (acceptance.review) {
495
- lines.push("", `Review gate: ${acceptance.review.required === false ? "optional" : "required"}${acceptance.review.agent ? ` by ${acceptance.review.agent}` : ""}.`);
535
+ lines.push("", `Review gate: ${formatReviewGateLabel(acceptance.review)}.`);
496
536
  if (acceptance.review.focus) lines.push(`Review focus: ${acceptance.review.focus}`);
497
537
  }
498
538
  if (acceptance.stopRules.length > 0) {
@@ -1381,7 +1421,7 @@ export async function evaluateAcceptance(input: {
1381
1421
  if (input.watchdog) {
1382
1422
  const unresolved = unresolvedChildWatchdogBlockers(input.watchdog);
1383
1423
  ledger.runtimeChecks.push(unresolved.length
1384
- ? { id: "watchdog-blocker", status: "failed", message: `Unresolved watchdog blocker: ${unresolved[0]!.summary}` }
1424
+ ? { id: "watchdog-blocker", status: "failed", message: "Unresolved watchdog blocker (details are available in child watchdog status)." }
1385
1425
  : { id: "watchdog-blocker", status: "passed", message: "No unresolved watchdog blockers." });
1386
1426
  }
1387
1427
 
@@ -1,6 +1,6 @@
1
1
  import type { AgentContract, EffectsProjection, ExecutionProjection, ReviewProjection, SingleResult } from "../../shared/types.ts";
2
2
 
3
- export function isAgentContractV1(contract: AgentContract | undefined): boolean {
3
+ export function isAgentContract(contract: AgentContract | undefined): boolean {
4
4
  return contract?.version === 1;
5
5
  }
6
6