@xzzpig/pi-subagents 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (218) hide show
  1. package/CHANGELOG.md +443 -0
  2. package/README.md +2 -2
  3. package/agents/claude-code-writer.md +15 -0
  4. package/agents/claude-code.md +15 -0
  5. package/agents/codex-exec-writer.md +15 -0
  6. package/agents/codex-exec.md +15 -0
  7. package/agents/cursor-agent-writer.md +14 -0
  8. package/agents/cursor-agent.md +14 -0
  9. package/agents/reviewer.md +1 -1
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +151 -39
  12. package/docs/configuration.md +81 -22
  13. package/docs/extension-api.md +69 -14
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +32 -9
  16. package/docs/observability.md +22 -20
  17. package/docs/tool-reference.md +123 -14
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +142 -4
  20. package/install.mjs +1 -1
  21. package/package.json +5 -4
  22. package/prompts/review-loop.md +2 -2
  23. package/skills/council-mode/SKILL.md +48 -243
  24. package/skills/council-mode/references/pass-contracts.md +150 -0
  25. package/skills/pi-subagents/SKILL.md +89 -35
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +30 -234
  27. package/skills/pi-subagents/references/execution-controls.md +91 -15
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +13 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +59 -31
  31. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  32. package/src/agents/agent-management.ts +370 -114
  33. package/src/agents/agent-refinements.ts +4 -4
  34. package/src/agents/agent-serializer.ts +12 -2
  35. package/src/agents/agents.ts +919 -372
  36. package/src/agents/builtin-names.ts +6 -0
  37. package/src/agents/runtime-agent-events.ts +70 -0
  38. package/src/agents/runtime-agent-registry.ts +31 -20
  39. package/src/api/agents.ts +10 -5
  40. package/src/api/background-work.ts +12 -3
  41. package/src/api/capability-ceiling.ts +0 -1
  42. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  43. package/src/api/delegation.ts +0 -7
  44. package/src/api/external-runs.ts +67 -4
  45. package/src/api/preflight.ts +48 -18
  46. package/src/api/shared-types.ts +6 -0
  47. package/src/extension/config.ts +90 -0
  48. package/src/extension/doctor.ts +5 -13
  49. package/src/extension/fanout-child.ts +14 -14
  50. package/src/extension/index.ts +115 -37
  51. package/src/extension/public-execution.ts +103 -15
  52. package/src/extension/rpc.ts +120 -25
  53. package/src/extension/schemas.ts +57 -21
  54. package/src/extension/tool-description.ts +48 -26
  55. package/src/inspectors/herdr/actions.ts +2 -1
  56. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  57. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  58. package/src/integrations/herdr-status.ts +51 -3
  59. package/src/intercom/native-supervisor-channel.ts +138 -60
  60. package/src/intercom/result-intercom.ts +2 -0
  61. package/src/intercom/supervisor-ui.ts +243 -0
  62. package/src/profiles/profiles.ts +5 -6
  63. package/src/runs/background/active-async-capacity.ts +103 -18
  64. package/src/runs/background/async-execution.ts +366 -128
  65. package/src/runs/background/async-job-tracker.ts +95 -15
  66. package/src/runs/background/async-resume.ts +45 -28
  67. package/src/runs/background/async-retention.ts +20 -3
  68. package/src/runs/background/async-status-snapshot.ts +23 -261
  69. package/src/runs/background/async-status.ts +189 -14
  70. package/src/runs/background/auto-drain.ts +1 -1
  71. package/src/runs/background/chain-append.ts +8 -3
  72. package/src/runs/background/chain-root-attachment.ts +74 -8
  73. package/src/runs/background/control-channel.ts +4 -205
  74. package/src/runs/background/fleet-view.ts +38 -22
  75. package/src/runs/background/inspect-rpc.ts +8 -8
  76. package/src/runs/background/notify.ts +238 -12
  77. package/src/runs/background/process-terminal.ts +16 -0
  78. package/src/runs/background/result-delivery-ownership.ts +45 -0
  79. package/src/runs/background/result-files.ts +28 -14
  80. package/src/runs/background/result-watcher.ts +39 -16
  81. package/src/runs/background/resume-guidance.ts +2 -2
  82. package/src/runs/background/retained-children.ts +1 -1
  83. package/src/runs/background/run-child-session.ts +613 -0
  84. package/src/runs/background/run-status.ts +84 -17
  85. package/src/runs/background/runner-aliases.ts +125 -0
  86. package/src/runs/background/runner-child-sessions.ts +31 -0
  87. package/src/runs/background/scheduled-runs.ts +174 -18
  88. package/src/runs/background/stale-run-reconciler.ts +10 -4
  89. package/src/runs/background/steering.ts +8 -15
  90. package/src/runs/background/subagent-runner.ts +676 -1161
  91. package/src/runs/background/subagent-wait.ts +86 -31
  92. package/src/runs/background/terminal-run-index.ts +1 -1
  93. package/src/runs/background/wait-completions.ts +43 -2
  94. package/src/runs/background/wait-config.ts +23 -9
  95. package/src/runs/background/wait-tool.ts +26 -19
  96. package/src/runs/foreground/async-steering-action.ts +3 -19
  97. package/src/runs/foreground/execution.ts +468 -499
  98. package/src/runs/foreground/foreground-control.ts +13 -0
  99. package/src/runs/foreground/foreground-history.ts +23 -1
  100. package/src/runs/foreground/subagent-executor.ts +1172 -400
  101. package/src/runs/foreground/workflow-detach-reconcile.ts +140 -115
  102. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  103. package/src/runs/shared/abort-recovery.ts +119 -0
  104. package/src/runs/shared/acceptance.ts +138 -36
  105. package/src/runs/shared/async-status-projection.ts +565 -0
  106. package/src/runs/shared/background-process-options.ts +9 -0
  107. package/src/runs/shared/capability-ceiling.ts +2 -2
  108. package/src/runs/shared/child-hooks.ts +25 -0
  109. package/src/runs/shared/child-identity.ts +32 -6
  110. package/src/runs/shared/child-launch-plan.ts +151 -0
  111. package/src/runs/shared/child-launch.ts +314 -0
  112. package/src/runs/shared/child-lifecycle.ts +25 -0
  113. package/src/runs/shared/child-runtime-config.ts +126 -0
  114. package/src/runs/shared/child-session.ts +342 -0
  115. package/src/runs/shared/child-tool-plan.ts +540 -0
  116. package/src/runs/shared/claude-code-adapter.ts +133 -0
  117. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  118. package/src/runs/shared/completion-evidence.ts +89 -0
  119. package/src/runs/shared/completion-guard.ts +6 -5
  120. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  121. package/src/runs/shared/dynamic-fanout.ts +3 -3
  122. package/src/runs/shared/external-cli-contract.ts +167 -0
  123. package/src/runs/shared/external-cli-preflight.ts +138 -0
  124. package/src/runs/shared/external-cli-runner.ts +348 -55
  125. package/src/runs/shared/fast-mode-extension.ts +5 -5
  126. package/src/runs/shared/host-step-status.ts +231 -0
  127. package/src/runs/shared/lane-metadata.ts +126 -0
  128. package/src/runs/shared/launch-cwd.ts +16 -0
  129. package/src/runs/shared/long-running-guard.ts +2 -1
  130. package/src/runs/shared/mcp-config-sources.ts +422 -0
  131. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  132. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  133. package/src/runs/shared/model-exclusions.ts +139 -9
  134. package/src/runs/shared/model-fallback.ts +142 -14
  135. package/src/runs/shared/mutation-evidence.ts +57 -3
  136. package/src/runs/shared/nested-events.ts +38 -48
  137. package/src/runs/shared/nested-path.ts +0 -14
  138. package/src/runs/shared/nested-render.ts +9 -5
  139. package/src/runs/shared/orca-progress-tabs.ts +12 -7
  140. package/src/runs/shared/parallel-handoff.ts +423 -7
  141. package/src/runs/shared/parallel-utils.ts +15 -7
  142. package/src/runs/shared/permissions.ts +1 -14
  143. package/src/runs/shared/pi-spawn.ts +69 -35
  144. package/src/runs/shared/process-signal.ts +16 -0
  145. package/src/runs/shared/run-fanout-budget.ts +0 -13
  146. package/src/runs/shared/run-history.ts +21 -1
  147. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  148. package/src/runs/shared/single-output.ts +89 -22
  149. package/src/runs/shared/structured-output.ts +49 -9
  150. package/src/runs/shared/subagent-control.ts +6 -2
  151. package/src/runs/shared/subagent-prompt-runtime.ts +188 -365
  152. package/src/runs/shared/task-intent.ts +21 -7
  153. package/src/runs/shared/tool-availability.ts +18 -62
  154. package/src/runs/shared/tool-budget.ts +0 -14
  155. package/src/runs/shared/tool-timeout.ts +1 -1
  156. package/src/runs/shared/workflow-graph.ts +16 -0
  157. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  158. package/src/runs/shared/worktree.ts +571 -62
  159. package/src/shared/atomic-json.ts +3 -1
  160. package/src/shared/child-session-name.ts +46 -0
  161. package/src/shared/extension-context.ts +24 -0
  162. package/src/shared/fork-context.ts +21 -12
  163. package/src/shared/fork-session-cwd.ts +27 -0
  164. package/src/shared/formatters.ts +18 -3
  165. package/src/shared/jsonl-writer.ts +11 -0
  166. package/src/shared/launch-contract.ts +8 -1
  167. package/src/shared/pruned-fork.ts +450 -0
  168. package/src/shared/session-file-trust.ts +19 -0
  169. package/src/shared/session-tokens.ts +14 -3
  170. package/src/shared/settings.ts +19 -105
  171. package/src/shared/shortcuts.ts +17 -0
  172. package/src/shared/thinking-ceiling.ts +0 -6
  173. package/src/shared/types.ts +524 -70
  174. package/src/shared/utils.ts +60 -93
  175. package/src/shared/workflow-child-permit.ts +207 -0
  176. package/src/slash/delegation-adapters.ts +1 -9
  177. package/src/slash/delegation-request.ts +0 -4
  178. package/src/slash/prompt-template-bridge.ts +37 -1
  179. package/src/slash/slash-bridge.ts +1 -2
  180. package/src/slash/slash-commands.ts +383 -116
  181. package/src/slash/slash-live-state.ts +22 -11
  182. package/src/slash/subagents-admin.ts +29 -12
  183. package/src/tui/fleet-native-transcript.ts +4 -0
  184. package/src/tui/fleet-status.ts +217 -82
  185. package/src/tui/fleet-transcript.ts +11 -5
  186. package/src/tui/fleet.ts +54 -28
  187. package/src/tui/render-helpers.ts +31 -0
  188. package/src/tui/render.ts +1429 -163
  189. package/src/watchdog/change-signature.ts +40 -1
  190. package/src/watchdog/child-status.ts +54 -34
  191. package/src/watchdog/diff-tool.ts +77 -0
  192. package/src/watchdog/emission-guard.ts +5 -3
  193. package/src/watchdog/guidance.ts +20 -0
  194. package/src/watchdog/register-child.ts +28 -25
  195. package/src/watchdog/register-main.ts +10 -9
  196. package/src/watchdog/render.ts +4 -5
  197. package/src/watchdog/review.ts +15 -4
  198. package/src/watchdog/rules.ts +70 -0
  199. package/src/watchdog/runtime.ts +75 -92
  200. package/src/watchdog/scope.ts +0 -11
  201. package/src/watchdog/settings.ts +48 -104
  202. package/src/watchdog/turn-delta.ts +1 -1
  203. package/src/watchdog/types.ts +18 -32
  204. package/src/watchdog/warning-format.ts +0 -1
  205. package/src/workflows/chat-progress.ts +7 -3
  206. package/src/workflows/host-command.ts +235 -0
  207. package/src/workflows/scripted-workflow.ts +988 -59
  208. package/src/workflows/workflow-checklist.ts +439 -0
  209. package/src/workflows/workflow-child-summary.ts +121 -0
  210. package/src/workflows/workflow-preflight.ts +297 -0
  211. package/src/workflows/workflow-receipt.ts +232 -6
  212. package/src/workflows/workflow-resources.ts +150 -0
  213. package/src/workflows/workflow-settlement.ts +246 -0
  214. package/src/runs/shared/child-protocol.ts +0 -401
  215. package/src/runs/shared/pi-args.ts +0 -935
  216. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  217. package/src/runs/shared/turn-budget.ts +0 -98
  218. package/src/shared/post-exit-stdio-guard.ts +0 -85
package/docs/workflows.md CHANGED
@@ -14,7 +14,7 @@ Packaged `worker`, `oracle`, and `advisor` default to forked context when a laun
14
14
 
15
15
  Child-safety boundaries are enforced at runtime:
16
16
 
17
- - Spawned child sessions do not receive the bundled `pi-subagents` skill.
17
+ - Child sessions do not receive the bundled `pi-subagents` skill.
18
18
  - Forked child context filtering removes parent-only subagent artifacts (including old hidden orchestration-instruction messages, slash/status/control messages, and prior parent `subagent` tool-call/tool-result history) while preserving ordinary prose and unrelated tool calls/results.
19
19
  - By default, children do not register the `subagent` tool and receive boundary instructions that they are not the parent orchestrator and must not propose or run subagents.
20
20
  - The explicit exception is an agent whose resolved builtin `tools` includes `subagent`; that child gets a child-safe `subagent` tool for the fanout work the parent assigned, still bounded by `maxSubagentDepth`.
@@ -35,10 +35,64 @@ Add `autofix` to `/parallel-review` or `/parallel-cleanup` to apply only the syn
35
35
 
36
36
  ## Scripted workflows (workflowScript)
37
37
 
38
- All model-facing subagent execution is expressed through `workflowScript` in the `subagent` tool. Use stable keys and ordinary JavaScript for one child, sequence, and parallelism. For ordinary parallel fanout, use `await runs.all([{ key, agent, task }, ...])`. It resolves to an ordered array, not a key map, so use indexes, destructuring, or `.map(...)`, not `results.<key>`. Do not read `.output` from unawaited `runs.run` launches. Store a `runs.run` promise only when the script later observes it with `await`, `Promise.race`, or `Promise.all`, such as steering a live child before awaiting its result. Scripts are ordinary JavaScript statement bodies. Use an explicit `return` for a useful result:
38
+ Use direct `{ agent, task }` for one bounded child. Use `workflowScript` when the parent needs a stable keyed child, sequence, fanout, steering, retry, or aggregation. For ordinary parallel fanout, use `await runs.all([{ key, agent, task }, ...])`. It resolves to an ordered array, not a key map, so use indexes, destructuring, or `.map(...)`, not `results.<key>`. Do not read `.output` from unawaited `runs.run` launches. Store a `runs.run` promise only when the script later observes it with `await`, `Promise.race`, or `Promise.all`, such as steering a live child before awaiting its result. Scripts are ordinary JavaScript statement bodies. Use an explicit `return` for a useful result:
39
39
 
40
40
  Child results cross into the script as plain JSON data. Non-JSON host metadata is omitted, so use returned fields such as `runId`, `ok`, `output`, and `structuredOutput` for workflow control.
41
41
 
42
+ Validate a script without launching children:
43
+
44
+ ```js
45
+ subagent({ action: "validate", workflowScript: `
46
+ const results = await runs.all([{ key: "scan", agent: "scout", task: "Scan" }]);
47
+ return results[0].output;
48
+ ` });
49
+ ```
50
+
51
+ For a script stored in a file, use `workflowScriptPath` instead of `workflowScript`:
52
+
53
+ ```js
54
+ subagent({ workflowScriptPath: "workflows/review.js", cwd: "/path/to/project" });
55
+ subagent({ action: "validate", workflowScriptPath: "workflows/review.js" });
56
+ ```
57
+
58
+ The fields are mutually exclusive. Relative paths resolve against the request `cwd`; absolute paths pass through. The host reads the file before validation, schedule creation, or workflow sandbox execution. The sandbox still has no filesystem access. Missing, unreadable, and empty files return file input errors instead of script syntax errors.
59
+
60
+ ### Named workflow resources for permission extensions
61
+
62
+ Use a named workflow resource when a permission or policy extension needs to distinguish extension-resolved workflow content from raw model-authored scripts:
63
+
64
+ ```js
65
+ subagent({ workflow: "review", args: { task: "Review the change" } });
66
+ subagent({ workflow: "run-ci", args: { command: "npm test" } });
67
+ ```
68
+
69
+ The host resolves the name and validates bounded plain-JSON `args` before starting the workflow. Resource provenance is recorded in workflow details and receipts for downstream permission/policy checks. Resource authority is not caller-supplied: `runs.host` is available only when the resolved resource explicitly grants the requested host key and command. Inline `workflowScript` and `workflowScriptPath` remain raw, unknown-provenance inputs, so their `runs.host` calls are unavailable through the public execution boundary. Named resources cannot be combined with `agent`, `task`, `workflowScript`, or `workflowScriptPath`; this first slice ships only the package-owned `review` and `run-ci` resources, not a user/project resource registry.
70
+
71
+ ### Opt-in bounded workflows
72
+
73
+ Composite workflows have no default parent deadline. Add bounds only when the workflow contract calls for them:
74
+
75
+ ```js
76
+ subagent({
77
+ workflowScript: `
78
+ const scan = await runs.run("scan", { agent: "scout", task: "Inspect the named files." });
79
+ return runs.run("review", { agent: "reviewer", task: "Review:\n" + scan.output });
80
+ `,
81
+ timeoutMs: 900000,
82
+ toolBudget: { soft: 40, hard: 60 },
83
+ usageBudget: { tokens: { soft: 100000, hard: 150000 } }
84
+ });
85
+ ```
86
+
87
+ - `timeoutMs` sets the workflow deadline and bounds child deadlines to the remaining time.
88
+ - `toolBudget` becomes the default for each child unless that child supplies a narrower value.
89
+ - `usageBudget` accounts for reported usage across completed workflow children. Once exhausted, it rejects later child launches but does not stop children that are already running.
90
+ - Budget and timeout stops return a structured `terminalOutcome` with `state: "partial"` and reason `budget_exhausted` or `timeout`. Workflow receipts keep settled child evidence for recovery.
91
+
92
+ These controls are opt-in. Avoid tight hard budgets for mutation-capable workers unless the workflow has an explicit checkpoint and handoff path.
93
+
94
+ The result is `{ ok, errors }`. Invalid scripts return a tool error and include line and column data when available. Validation checks syntax, portable nested-async rules, literal `runs.run` and `runs.all` keys, duplicate literal keys in one `runs.all` group, direct keyed access to a known `runs.all` result, and statically clear non-JSON boundary values. Dynamic keys and other runtime-only values are accepted without a warning. Validation does not discover agents, launch children, or create run artifacts.
95
+
42
96
  ```js
43
97
  subagent({ workflowScript: `
44
98
  const scan = await runs.run("scan", { agent: "scout", task: "Scan the codebase" });
@@ -72,6 +126,61 @@ subagent({ workflowScript: `
72
126
  ` });
73
127
  ```
74
128
 
129
+ ### Parallel sequential lanes
130
+
131
+ For a bounded set of independent chains, `runs.lanes(...)` removes the mechanical loop that would otherwise connect each lane's stages. It is a helper inside `workflowScript`, not a new top-level `subagent` execution mode:
132
+
133
+ ```js
134
+ subagent({ workflowScript: `
135
+ const board = await runs.lanes([
136
+ {
137
+ key: "api",
138
+ stages: [
139
+ { key: "writer", agent: "worker", task: "Implement the API change" },
140
+ { key: "challenge", resume: "previous", task: "Challenge the API implementation" },
141
+ { key: "review", agent: "reviewer", task: "Review the API lane" }
142
+ ]
143
+ },
144
+ {
145
+ key: "ui",
146
+ stages: [
147
+ { key: "writer", agent: "worker", task: "Implement the UI change" },
148
+ { key: "review", agent: "reviewer", task: "Review the UI lane" }
149
+ ]
150
+ }
151
+ ]);
152
+ return board.map((lane) => ({
153
+ key: lane.key,
154
+ state: lane.state,
155
+ failedStage: lane.failedStage,
156
+ stages: lane.stages.map((stage) => ({
157
+ key: stage.key,
158
+ state: stage.state,
159
+ ok: stage.ok,
160
+ runId: stage.runId,
161
+ outputReference: stage.outputReference,
162
+ verdict: stage.verdict
163
+ }))
164
+ }));
165
+ ` });
166
+ ```
167
+
168
+ The first stage from every lane is launched in one existing `runs.all(...)` batch. Later stages in each lane start only after the preceding stage settles. A later stage with `resume: "previous"` requires the preceding child to return a retained `runId`; the helper then uses the existing retained-resume launch checks and does not accept an arbitrary run id. Generated child keys use `<lane>.<stage>`, while the returned board uses the local lane and stage keys.
169
+
170
+ The helper validates the complete plain-JSON lane inventory before launching anything. It bounds the inventory to 32 lanes, 16 stages per lane, 64 total stages, and 64 KiB of canonical JSON; task and path fields retain the existing 1 MiB and 32 KiB limits. Stage keys must be unique within a lane and generated keys must be unique and valid workflow keys. A child failure, stopped/detached result, or explicit `structuredOutput.verdict === "blocked"` blocks only that lane; later stages are marked `skipped` and sibling lanes continue. Reviewer prose is never parsed.
171
+
172
+ The board is bounded and contains only lane/stage keys, state, success, retained run ids, explicit output references, bounded errors, and an optional structured verdict. It does not return child transcripts or create a lane registry or cleanup authority. Use raw `runs.run(...)`/`runs.all(...)` when a workflow needs conditional or rolling orchestration beyond this helper.
173
+
174
+ ### Host command steps
175
+
176
+ Use the named `run-ci` resource when a permission/policy extension needs to admit one supported non-interactive command as workflow evidence instead of a child-agent run:
177
+
178
+ ```js
179
+ subagent({ workflow: "run-ci", args: { command: "npm test", timeoutMs: 120000 } });
180
+ ```
181
+
182
+ The first named resource version supports only `npm test` and `npm run typecheck`, with bounded timeout values. Its resolved script uses `runs.host("ci", ...)` and the resource authority admits only the selected command. **There is no per-step `cwd` field:** the command and relative output path use the workflow cwd. Set `cwd` on the outer `subagent({...})` request when the workflow should run in another directory. The command has no stdin, receives the workflow cwd, and must be awaited or returned. Stdout, stderr, and the saved log are bounded. A nonzero exit, timeout, abort, or output-write failure fails the workflow. Async status and terminal receipts store the bounded host-step state; renderers do not run commands or read command output.
183
+
75
184
  ### Steering a workflow child
76
185
 
77
186
  Use `await runs.steer(key, message, options?)` after `runs.run` or `runs.all` has launched that stable key. Scripts do not target raw run ids. The optional fields are `mode: "steer" | "follow_up" | "auto"`, a non-negative child `index`, and a positive `ackTimeoutMs`.
@@ -260,7 +369,36 @@ Each child uses the existing worktree lifecycle: it branches from clean HEAD, jo
260
369
 
261
370
  A top-level `{ workflowScript, worktree: true }` makes isolation the default for every workflow child. An individual child can override that default with `worktree: false`. Keep one writer when parallel writes are not intentionally isolated.
262
371
 
263
- Configure the worktree base directory and setup hook in [configuration.md](configuration.md).
372
+ Use `baseRef` to branch managed worktrees from a named commit or branch instead of the default `HEAD`. For example, `{ workflowScript, worktree: true, baseRef: "refs/heads/release" }` applies the release ref to children unless a child supplies its own `baseRef`. The source checkout must still be clean, and the ref must resolve to a commit before any worktree is allocated.
373
+
374
+ Configure the worktree provider, native path layout, base directory, and setup hook in [configuration.md](configuration.md).
375
+
376
+ ### Lane metadata lifecycle
377
+
378
+ Workflow children may declare a bounded `lane` object (`version`, `key`, optional
379
+ `mode`, opaque `sourceRef`, advisory `claims`, and advisory `outputPaths`). The
380
+ lane key must match the `runs.run`/`runs.all` workflow key. These fields are
381
+ display and triage hints only: they do not grant tools, authorization, or
382
+ cleanup permission, and `sourceRef` is never resolved over the network while
383
+ rendering status. Worktree paths and branches copied into status are also
384
+ display-only; the handoff manifest remains the deletion authority.
385
+
386
+ | Durable file | Owner | Pending / running / finalized / cleanup states | Release predicate | Rollback predicate | Stale-head behavior | Fail-closed cases |
387
+ | --- | --- | --- | --- | --- | --- | --- |
388
+ | `status.json` | Async runner and workflow status projector | Child step starts `pending`, becomes `running`, then terminal `complete`/`failed`/`paused`/`stopped`; worktree path and branch are copied at launch | Status is terminal and the existing active-run/process proof can release the run marker; lane metadata alone never releases a worktree | Setup or persistence failure keeps the lane unknown; only the existing verified setup rollback may remove a newly created worktree | Recorded status is retained; a base/head mismatch is not repaired or inferred from render-time Git calls | Missing, malformed, or key-mismatched lane data; only one of `worktreePath`/`branch`; unverified process state |
389
+ | `handoffs/<run-id>.json` | Existing parallel handoff writer and cleanup engine | Group is `partial` with preserved cleanup tasks while pending/running; finalized groups contain child identity, patch, and cleanup evidence; cleanup is `partial` or `complete` | Only the existing cleanup engine's fresh Git checks and recorded task evidence can release a worktree/branch; #1621 adds no deletion path | Missing diff, failed capture, or cleanup error preserves the task and records the reason | `baseCommit` is retained as evidence; stale or changed heads remain unknown/preserved until an explicit later reconciliation | Missing/invalid manifest, mismatched run/key/task identity, duplicate identity, dirty or uncaptured work |
390
+ | `workflow-receipt.json` | Workflow terminal settlement | No receipt while `pending`/`running`; terminal receipt is finalized with one optional lane block per keyed child | Receipt publication is complete only after every included child entry is serialized; it does not authorize cleanup | Receipt write failure leaves status/handoff evidence authoritative and the workflow reports the missing receipt | Existing receipt is not backfilled or rewritten from a newer head | Invalid version/state, mismatched entry key or lane key, stale continuation lineage |
391
+ | `.active-runs` marker | Existing active-run index | `pending`/`running` while the runner is live; terminal marker remains until observed process proof | Marker removal requires the existing exact-run process-terminal proof | Unknown proof keeps the marker and lane retained for inspection | Marker state is not inferred from Git head or timestamps alone | Missing/unknown process proof, active marker, or foreign run identity |
392
+
393
+ Older runs without lane metadata remain readable and retain their existing
394
+ handoff/cleanup behavior. Missing lane, receipt, or handoff metadata is
395
+ unknown—not eligible for destructive cleanup.
396
+
397
+ For managed worktree launches, the runner writes the pending handoff and the
398
+ display-only status path/branch from the deterministic setup plan before the
399
+ first `git worktree add`. If setup then fails or is interrupted, that pending
400
+ ownership record remains preserved evidence; cleanup still rechecks the actual
401
+ worktree state before any removal.
264
402
 
265
403
  ## Supervisor coordination (child asks parent)
266
404
 
@@ -310,7 +448,7 @@ export PI_SUBAGENT_MAX_DEPTH=1
310
448
  export PI_SUBAGENT_MAX_DEPTH=0
311
449
  ```
312
450
 
313
- `PI_SUBAGENT_DEPTH` is internal and propagated automatically. Do not set it manually.
451
+ `PI_SUBAGENT_MAX_DEPTH` applies to the top-level parent; children inherit their limit through their runtime config, and their own depth is tracked there too.
314
452
 
315
453
  ## Prompt-template integration
316
454
 
package/install.mjs CHANGED
@@ -87,7 +87,7 @@ if (fs.existsSync(EXTENSION_DIR)) {
87
87
  console.log(`
88
88
  The extension is now available in pi. Tools added:
89
89
  • subagent - Delegate tasks to agents and inspect run status
90
- • subagent_wait - Block until background subagent runs finish (delivers their results)
90
+ • bg_wait - Wait for background/provider/detached work without native completion notifications
91
91
 
92
92
  Documentation: ${EXTENSION_DIR}/README.md
93
93
  `);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xzzpig/pi-subagents",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
5
5
  "author": "Nico Bailon",
6
6
  "license": "MIT",
@@ -17,7 +17,7 @@
17
17
  "./agent-management": "./src/api/agent-management.ts",
18
18
  "./control-channel": "./src/api/control-channel.ts",
19
19
  "./intercom-bridge": "./src/api/intercom-bridge.ts",
20
- "./pi-args": "./src/api/pi-args.ts",
20
+ "./child-tool-plan": "./src/api/child-tool-plan.ts",
21
21
  "./shared-types": "./src/api/shared-types.ts",
22
22
  "./project-panes": "./src/api/project-panes.ts"
23
23
  },
@@ -94,7 +94,9 @@
94
94
  "@earendil-works/pi-agent-core": "0.84.2",
95
95
  "@earendil-works/pi-ai": "0.84.2",
96
96
  "@earendil-works/pi-tui": "0.84.2",
97
+ "@oxlint/plugins": "1.80.0",
97
98
  "@types/node": "24.13.3",
99
+ "oxlint": "1.80.0",
98
100
  "typescript": "5.9.3",
99
101
  "@earendil-works/pi-coding-agent": "file:./test/fixtures/pi-coding-agent-shim"
100
102
  },
@@ -109,7 +111,6 @@
109
111
  "test": "npm run test:unit",
110
112
  "test:unit": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --test test/unit/*.test.ts",
111
113
  "test:integration": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
112
- "test:e2e": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/e2e/*.test.ts",
113
- "test:all": "npm run test:unit && npm run test:integration && npm run test:e2e"
114
+ "test:all": "npm run test:unit && npm run test:integration"
114
115
  }
115
116
  }
@@ -10,7 +10,7 @@ Default to a maximum of 3 review rounds unless I specify a different cap. Count
10
10
 
11
11
  If the invocation includes an implementation request, first launch one async `worker` to implement the approved scope. If the current diff is already the target, start with review. The sequence can be launched up front with `workflowScript` when it is already clear, or continued as follow-up single-agent runs after each async completion. For an initial workflowScript, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless I explicitly want the foreground clarify UI. Use only one writer against the active worktree at a time unless I explicitly ask for isolated worktrees.
12
12
 
13
- As a conservative orchestration policy, do not set `turnBudget`, a hard `toolBudget`, or a tight `usageBudget` on implementation or fix workers. A default tool budget blocks read/search tools rather than mutation tools, and reported usage has no reservation model, so count or usage limits still do not measure delivery safety. Give each writer a narrow delivery slice and an outer elapsed deadline with enough margin. Before that deadline, request a checkpoint after the current tool returns with changed files, build/test state, remaining work, and commit or PR state. An elapsed timeout is not a mutation-safe boundary and must not be the checkpoint trigger.
13
+ As a conservative orchestration policy, do not set a hard `toolBudget` or tight `usageBudget` on implementation or fix workers. A default tool budget blocks read/search tools rather than mutation tools, and reported usage has no reservation model, so count or usage limits still do not measure delivery safety. Give each writer a narrow delivery slice and an outer elapsed deadline with enough margin. Before that deadline, request a checkpoint after the current tool returns with changed files, build/test state, remaining work, and commit or PR state. An elapsed timeout is not a mutation-safe boundary and must not be the checkpoint trigger.
14
14
 
15
15
  For each review round, launch fresh-context `reviewer` agents in parallel. Reviewers must inspect the repository, relevant instructions, and current diff directly from files and commands. They must not rely on the main conversation history and must not edit files.
16
16
 
@@ -28,7 +28,7 @@ Do not blindly apply every reviewer suggestion. If reviewers surface an unapprov
28
28
 
29
29
  When an async implementation worker completes, treat its handoff as the transition into review, not as final completion, unless I explicitly asked for worker-only work, review-only output, or to stop after implementation.
30
30
 
31
- When there are fixes worth doing now and the workflow is implementation-authorized, launch one async forked `worker` without hard turn or tool-call caps to apply only those synthesized fixes. Ask it to preserve the approved scope, run focused validation, and report changed files, commands run with exit codes, validation evidence, surprises, and anything left undone.
31
+ When there are fixes worth doing now and the workflow is implementation-authorized, launch one async forked `worker` without hard tool-call caps to apply only those synthesized fixes. Ask it to preserve the approved scope, run focused validation, and report changed files, commands run with exit codes, validation evidence, surprises, and anything left undone.
32
32
 
33
33
  After a fix worker returns, run another review round only when it made material changes or addressed non-trivial findings. Do not keep looping for optional polish, speculative improvements, or findings already deferred by the parent.
34
34
 
@@ -5,250 +5,55 @@ description: Run a bounded supervisor-mediated advisor council. Use when the use
5
5
 
6
6
  # Council Mode
7
7
 
8
- This skill is for the parent supervisor only. Do not inject it into advisors. The
9
- parent selects the roster, curates all cross-advisor communication, decides which
10
- feedback is valid, and writes the decision memo. Advisors do not talk directly or
11
- see peer transcripts by default. This is not free-form agent chat.
12
-
13
- Use council mode for a material decision with real tradeoffs. Do not use it for a
14
- trivial or settled question, or for implementation work. Read
15
- `skills/pi-subagents/references/execution-controls.md` before you launch advisors.
16
-
17
- ## Roster and limits
18
-
19
- Use advisor profile names directly. A `council-*` profile defines model, tools,
20
- context, output defaults, and any persistent stance in the profile body. Its
21
- profile configuration or explicit invocation owns its context choice.
22
-
23
- Package advisors can also join the roster only when their package Pi extension is
24
- installed and their external-job provider is registered. For Surf, `gpt-pro` is
25
- available only after the `surf-cli` Pi extension loads Surf's `surf-oracle`
26
- provider. Treat it as a normal advisor name in `runs.all` after that provider is
27
- visible. It is background-only, so omit `async` unless you explicitly want
28
- detached receipt semantics; workflow execution will await the terminal provider
29
- result. External runners can lack repo tools, structured-output support, or
30
- resumability. For them, include the needed evidence or file excerpts in the task,
31
- use the text JSON contract below instead of `outputSchema`, and use the
32
- fresh-context fallback path for cross-exam when the run is not resumable.
33
-
34
- Create model-based profiles in your user or project agent directory. Do not add
35
- them to this package. This is a valid example:
36
-
37
- ```markdown
38
- ---
39
- name: council-sol
40
- description: Read-only fresh-context advisor for bounded council decisions
41
- tools: read, grep, find, ls
42
- model: openai-codex/gpt-5.6-sol
43
- thinking: high
44
- systemPromptMode: replace
45
- inheritProjectContext: true
46
- inheritSkills: false
47
- defaultContext: fresh
48
- acceptanceRole: read-only
49
- ---
8
+ Council mode is parent-supervised advice for a material decision with real tradeoffs. It is not free-form agent chat, implementation work, a transcript dump, mutation authority, or a council UI.
9
+
10
+ The parent selects the roster, relays only curated claims, decides validity, and writes the memo. Advisors stay read-only and do not see peer transcripts by default.
11
+
12
+ Before launch, read:
13
+
14
+ - `skills/pi-subagents/references/execution-controls.md`
15
+ - `skills/council-mode/references/pass-contracts.md`
16
+
17
+ ## Roster
18
+
19
+ Run `subagent({ action: "list" })`, then choose 2-3 executable advisor names that start with `council-`. The prefix is convention only. Never use more than four advisors.
20
+
21
+ If fewer than two council profiles are available, fill with `oracle`, then `reviewer`. Launch fallback `oracle` with `context: "fork"`; let fallback `reviewer` use its normal profile context. Note fallbacks and known context modes in the memo. If fewer than two advisors remain, use the normal one-oracle consultation loop and label it degraded mode.
22
+
23
+ `council-*` profiles live in user or project agent directories, not this package. A profile defines model, tools, context, output defaults, and persistent stance. Keep advisors read-only, disable inherited skills unless needed, and put stance in the profile body instead of inventing per-run role labels.
50
24
 
51
- Analyze the council question independently. Inspect evidence directly. Do not
52
- edit, run mutating commands, commit, push, contact peers, or spawn subagents.
53
- Return concise, cited advice using the report contract in the council task.
54
- ```
55
-
56
- After `subagent({ action: "list" })`, prefer 2–3 executable names that start with
57
- `council-`. The prefix is a naming convention, not runtime selection. If fewer
58
- than two profiles are available, fill the roster with `oracle`, then `reviewer`,
59
- until it has two advisors. Launch fallback `oracle` with `context: "fork"` so
60
- global defaults cannot remove its parent-chat context. Let fallback `reviewer`
61
- use its normal profile context. Note the fallback and known context modes in the
62
- memo. Use the normal single-oracle consultation loop only when a requested roster
63
- or unavailable builtins leaves fewer than two advisors.
64
- Label that result as degraded mode. Never use more than four advisors.
65
-
66
- Pass 1 is independent reports. Pass 2 is one cross-exam. The default pass cap is
67
- 2. Run pass 3 only when `--max-passes 3` was requested and a material dispute can
68
- be settled by evidence an advisor can produce. Never run an unbounded loop.
25
+ External-job/package advisors may join only when their provider is registered. Treat them as ordinary advisor names in `runs.all`, but honor their runner limits: they may lack repo tools, structured output, or resumability. Include evidence they cannot read, request JSON text instead of `outputSchema`, and use a fresh-context fallback when they cannot resume for cross-exam.
26
+
27
+ ## Passes
28
+
29
+ Pass 1 is independent reports. Pass 2 is one cross-exam. Run Pass 3 only when `--max-passes 3` was requested and a material dispute can still be settled by evidence. Never run an unbounded loop.
69
30
 
70
31
  ## Protocol
71
32
 
72
- 1. The parent writes a brief with the question, scope, non-goals, evidence targets,
73
- roster, known advisor context modes, and pass cap. If the user wants a specific
74
- lens, keep it in the question, scope, or profile body instead of inventing a
75
- per-advisor label.
76
- 2. Before Pass 1, tell the user the roster, requested or known context modes, and
77
- pass cap. Use a stable key, `phase`, and concise `label` for every
78
- workflow child. For example, use `advisor-oracle`, `phase: "Council pass 1"`,
79
- and `label: "Oracle — intent and consistency"`.
80
- 3. Launch one async `workflowScript` with `runs.all` for independent advisor
81
- reports. Set `context` when the selected advisor has a known profile context or
82
- a fallback rule requests one, because a global default can otherwise override
83
- that profile. Set `context: "fork"` for fallback `oracle`. If no advisor context
84
- is known, omit `context` and disclose the unknown runtime default in the memo.
85
- Each advisor is read-only and must not spawn children, edit files, run mutating
86
- commands, commit, or push. Set `output: false` unless separate advisor artifacts
87
- are explicitly requested or useful for the decision. When separate artifacts are
88
- useful, give advisors relative output paths so the runtime stores them under its
89
- managed artifact directory; do not ask them to write root-level council report
90
- files. For installed
91
- external-runner advisors such as Surf `gpt-pro` after `surf-oracle` is
92
- registered, do not pass `outputSchema`; put the schema request in the task text
93
- and accept `result.output` as the report.
94
- 4. Return one aggregate Pass 1 receipt. After it completes, tell the user the
95
- completion count, agreement count, dispute count, and whether Pass 2 is needed.
96
- 5. The parent synthesizes a claim matrix in session. It contains agreements,
97
- disputed claims, missing proof, owner decisions, and a relay set of at most five
98
- high-impact claims per advisor. Do not delegate this synthesis.
99
- 6. Before Pass 2, tell the user how many claims are relayed and why each is
100
- material. Launch a second async `workflowScript` with `runs.all` resume calls.
101
- Each task is a curated challenge packet, not a peer transcript. A resume requires
102
- a retained run id and a non-empty task. It excludes `agent` and rejects `gate`.
103
- Record the new run id from every resume. Pass 3 resumes those latest ids. Return
104
- one aggregate Pass 2 receipt.
105
- 7. After Pass 2, tell the user whether the council converged or which owner
106
- decisions remain. The parent writes the final memo. Do not delegate it.
107
-
108
- If an advisor is not resumable, run the same profile in fresh context with its own
109
- pass-1 report and the challenge packet. Label that response as a fresh-context
110
- fallback, not a true cross-exam.
111
-
112
- Do not set `clarify`, `worktree`, `gate`, turn budgets, tool budgets, or tight usage
113
- budgets on advisors. Bound work through the roster, pass cap, and report length.
114
-
115
- ## Advisor contracts and pass receipts
116
-
117
- Pass-1 reports are at most about 600 words. Give native Pi advisors the same
118
- `outputSchema`, so reports are comparable without heading cleanup. For
119
- external-runner advisors, do not pass `outputSchema`; ask them to return compact
120
- JSON text with the same fields. The following shape is a contract template. Use
121
- the runtime schema syntax supported by the workflow for native advisors and keep
122
- narrative fields as strings:
123
-
124
- ```js
125
- const pass1OutputSchema = {
126
- type: "object",
127
- required: [
128
- "recommendation", "evidence", "assumptions", "risks", "confidence",
129
- "challengeClaims", "ownerDecisions", "changeMyMind"
130
- ],
131
- properties: {
132
- recommendation: { type: "string" },
133
- evidence: {
134
- type: "array",
135
- items: {
136
- type: "object",
137
- required: ["claim", "sources"],
138
- properties: {
139
- claim: { type: "string" },
140
- sources: { type: "array", items: { type: "string" } }
141
- }
142
- }
143
- },
144
- assumptions: {
145
- type: "array",
146
- items: {
147
- type: "object",
148
- required: ["assumption", "status"],
149
- properties: {
150
- assumption: { type: "string" },
151
- status: { enum: ["verified", "unverified"] }
152
- }
153
- }
154
- },
155
- risks: { type: "array", items: { type: "string" } },
156
- confidence: {
157
- type: "object",
158
- required: ["level", "reason"],
159
- properties: {
160
- level: { enum: ["high", "medium", "low"] },
161
- reason: { type: "string" }
162
- }
163
- },
164
- challengeClaims: { type: "array", items: { type: "string" }, maxItems: 3 },
165
- ownerDecisions: { type: "array", items: { type: "string" } },
166
- changeMyMind: { type: "array", items: { type: "string" } }
167
- }
168
- };
169
- ```
170
-
171
- Include this contract in each Pass 1 task: inspect supplied evidence directly; do
172
- not see or ask about other advisors; stay read-only; do not spawn children; return
173
- only the structured report. For external-runner advisors, say `Return only JSON
174
- matching this shape. Do not wrap it in Markdown.` and include any evidence they
175
- cannot read through tools.
176
-
177
- After `runs.all`, return one aggregate receipt rather than making the parent find
178
- separate artifacts. Preserve the result order or map it by stable key so each row
179
- contains the advisor identity and report:
180
-
181
- ```js
182
- return {
183
- pass: 1,
184
- advisors: results.map((result, index) => ({
185
- key: result.key,
186
- agent: result.agent,
187
- requestedContext: roster[index].context ?? "runtime-default-unknown",
188
- runId: result.runId,
189
- report: result.structuredOutput ?? result.output
190
- }))
191
- };
192
- ```
193
-
194
- Do not replace `runtime-default-unknown` with a guessed context. It records that
195
- the launch intentionally omitted context.
196
-
197
- A challenge packet contains only disputed claims, strong conflicting evidence,
198
- missing proof, owner decisions, and high-impact risks. Attribute peer content as
199
- "another advisor". Do not include full peer reports. Use a common Pass 2 contract:
200
-
201
- ```js
202
- const pass2OutputSchema = {
203
- type: "object",
204
- required: ["responses", "recommendationChanged", "outOfScopeFindings"],
205
- properties: {
206
- responses: {
207
- type: "array",
208
- items: {
209
- type: "object",
210
- required: ["claimId", "disposition", "reason", "sources"],
211
- properties: {
212
- claimId: { type: "string" },
213
- disposition: {
214
- enum: ["accept", "reject", "refine", "owner-decision"]
215
- },
216
- reason: { type: "string" },
217
- sources: { type: "array", items: { type: "string" } }
218
- }
219
- }
220
- },
221
- recommendationChanged: {
222
- type: "object",
223
- required: ["changed", "reason"],
224
- properties: { changed: { type: "boolean" }, reason: { type: "string" } }
225
- },
226
- outOfScopeFindings: { type: "array", items: { type: "string" } }
227
- }
228
- };
229
- ```
230
-
231
- Use stable resume keys such as `cross-oracle`, `phase: "Council pass 2"`, concise
232
- labels, and `output: false` unless separate artifacts are requested or useful. Keep
233
- any artifact outputs under the managed run artifact directory. Do not pass
234
- `outputSchema` to external-runner fallback launches; ask for compact JSON text
235
- instead. The aggregate Pass 2 receipt uses the same row shape as Pass 1, with the
236
- new `runId` and `structuredOutput ?? output`.
237
-
238
- ## Stop and memo
239
-
240
- Converged means no disputed claim remains that both materially affects the
241
- recommendation and can plausibly be settled by evidence. Stop at convergence, the
242
- pass cap, failed fallback, or user interruption. Put unresolved disputes in owner
243
- decisions. Never add a round for polish or symmetry.
244
-
245
- The parent memo states the question and scope, recommendation, rationale, accepted
246
- and rejected feedback with reasons, owner decisions, evidence and run ids,
247
- confidence, what would change the decision, and the roster, passes, fallbacks, and
248
- known advisor context modes. Identify advisors by profile name or model-based
249
- profile, not by invented role labels. State that fallback `oracle` is context-aware
250
- and forked.
251
-
252
- Council mode is not agent-to-agent chat, a transcript dump, mutation authority,
253
- auto-escalation to writer lanes, or a council UI. Escalate to a writer only after
254
- the parent memo and only when the user explicitly requests it.
33
+ 1. Write the council brief: question, scope, non-goals, evidence targets, roster, known advisor context modes, and pass cap.
34
+ 2. Tell the user the roster, context modes, and pass cap.
35
+ 3. Launch one async `workflowScript` with `runs.all` for Pass 1. Use stable keys, `phase: "Council pass 1"`, concise labels, and `output: false` unless separate artifacts are useful. Set `context` only when the profile context is known or a fallback rule requires it.
36
+ 4. Return one aggregate Pass 1 receipt. On completion, tell the user completion count, agreement count, dispute count, and whether Pass 2 is needed.
37
+ 5. Synthesize the claim matrix in the parent: agreements, disputed claims, missing proof, owner decisions, and at most five material relay claims per advisor.
38
+ 6. For Pass 2, tell the user which claims are relayed and why they matter. Resume each advisor with a curated challenge packet. A resume needs a retained run id and task; it excludes `agent` and rejects `gate`. Record each new run id; Pass 3 resumes those latest ids with new stable keys.
39
+ 7. Stop at convergence, pass cap, failed fallback, or user interruption. The parent writes the final memo.
40
+
41
+ If an advisor is not resumable, run the same profile fresh with its Pass 1 report and challenge packet. Label it a fresh-context fallback, not true cross-exam.
42
+
43
+ Do not set `clarify`, `worktree`, `gate`, tool budgets, or tight usage budgets on advisors. Bound work through the roster, pass cap, and report length.
44
+
45
+ ## Memo
46
+
47
+ Converged means no disputed claim remains that both affects the recommendation and can plausibly be settled by advisor evidence. Put unresolved disputes in owner decisions. Do not add a round for polish or symmetry.
48
+
49
+ The memo states:
50
+
51
+ - question and scope
52
+ - recommendation and rationale
53
+ - accepted and rejected feedback with reasons
54
+ - owner decisions
55
+ - evidence and run ids
56
+ - confidence and what would change the decision
57
+ - roster, passes, fallbacks, and known advisor context modes
58
+
59
+ Identify advisors by profile name. State when fallback `oracle` was forked and context-aware. Escalate to a writer only after the memo and only when the user requests it.