@xzzpig/pi-subagents 0.13.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 (202) hide show
  1. package/CHANGELOG.md +243 -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 +93 -15
  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 +67 -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/CHANGELOG.md +19 -0
  19. package/node_modules/@xzzpig/pi-components/README.md +28 -0
  20. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +46 -4
  21. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +65 -17
  22. package/node_modules/@xzzpig/pi-components/package.json +1 -1
  23. package/node_modules/@xzzpig/pi-components/src/transcript.ts +107 -14
  24. package/package.json +10 -5
  25. package/prompts/parallel-review.md +1 -1
  26. package/runner-peer-loader.mjs +24 -0
  27. package/runner-peer-preload.mjs +36 -0
  28. package/skills/pi-subagents/SKILL.md +34 -22
  29. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  30. package/skills/pi-subagents/references/execution-controls.md +27 -8
  31. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  32. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
  33. package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
  34. package/skills/pi-subagents/references/review-and-validation.md +3 -3
  35. package/src/agents/advertised-agent-prompt.ts +94 -0
  36. package/src/agents/agent-management.ts +71 -59
  37. package/src/agents/agent-serializer.ts +6 -3
  38. package/src/agents/agents.ts +198 -72
  39. package/src/agents/builtin-names.ts +1 -0
  40. package/src/agents/chain-serializer.ts +5 -0
  41. package/src/agents/runtime-agent-registry.ts +7 -6
  42. package/src/api/delegation.ts +4 -0
  43. package/src/api/preflight.ts +110 -71
  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 +32 -13
  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 +766 -432
  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 +896 -397
  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 +44 -16
  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 +145 -14
  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 +19 -10
  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/readonly-drain-observation.ts +42 -0
  148. package/src/runs/shared/run-fanout-budget.ts +8 -8
  149. package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
  150. package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
  151. package/src/runs/shared/task-intent.ts +46 -13
  152. package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
  153. package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
  154. package/src/runs/shared/worktree-setup-command.ts +213 -0
  155. package/src/runs/shared/worktree.ts +437 -214
  156. package/src/shared/child-cache-retention.ts +43 -0
  157. package/src/shared/fork-context.ts +15 -72
  158. package/src/shared/launch-contract.ts +70 -8
  159. package/src/shared/model-response-aliases.ts +13 -0
  160. package/src/shared/opencode-session-headers.ts +30 -0
  161. package/src/shared/pruned-fork.ts +1 -1
  162. package/src/shared/required-child-extensions.ts +81 -0
  163. package/src/shared/settings.ts +5 -2
  164. package/src/shared/shortcuts.ts +0 -4
  165. package/src/shared/types.ts +164 -90
  166. package/src/shared/utils.ts +10 -2
  167. package/src/shared/watch-strategy.ts +2 -0
  168. package/src/shared/workflow-child-permit.ts +18 -13
  169. package/src/slash/delegation-adapters.ts +3 -1
  170. package/src/slash/delegation-request.ts +14 -0
  171. package/src/slash/slash-commands.ts +2 -7
  172. package/src/slash/subagents-admin.ts +31 -14
  173. package/src/tui/fleet-native-transcript.ts +50 -6
  174. package/src/tui/fleet-status.ts +165 -20
  175. package/src/tui/fleet.ts +52 -21
  176. package/src/tui/render.ts +210 -50
  177. package/src/watchdog/child-status.ts +28 -28
  178. package/src/watchdog/lsp-diagnostics.ts +1 -1
  179. package/src/watchdog/model-selection.ts +21 -1
  180. package/src/watchdog/permission-arbiter.ts +5 -2
  181. package/src/watchdog/register-child.ts +10 -2
  182. package/src/watchdog/register-main.ts +39 -35
  183. package/src/watchdog/render.ts +1 -1
  184. package/src/watchdog/review.ts +122 -74
  185. package/src/watchdog/rules.ts +1 -1
  186. package/src/watchdog/runtime.ts +100 -27
  187. package/src/watchdog/scope.ts +1 -1
  188. package/src/watchdog/settings.ts +3 -0
  189. package/src/watchdog/tool-actions.ts +13 -12
  190. package/src/watchdog/turn-delta.ts +23 -0
  191. package/src/watchdog/types.ts +5 -3
  192. package/src/watchdog/warning-format.ts +1 -1
  193. package/src/workflows/chat-progress.ts +3 -3
  194. package/src/workflows/scripted-workflow.ts +349 -26
  195. package/src/workflows/workflow-checklist.ts +17 -20
  196. package/src/workflows/workflow-child-summary.ts +57 -8
  197. package/src/workflows/workflow-preflight.ts +19 -19
  198. package/src/workflows/workflow-receipt.ts +24 -6
  199. package/src/workflows/workflow-resources.ts +108 -22
  200. package/src/workflows/workflow-settlement.ts +3 -0
  201. package/src/runs/shared/model-exclusions.ts +0 -373
  202. /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
@@ -2,6 +2,97 @@
2
2
 
3
3
  Public seams for other Pi extensions and host integrations: the in-process RPC, the structured delegation API, launch preflight, capability ceilings, the background-work provider contract, and the Herdr integration.
4
4
 
5
+ ## Trusted workflow resources
6
+
7
+ Loaded trusted TypeScript extensions can import `registerWorkflowResource` from `pi-subagents/workflow-resources`. This subpath does not load the main extension and exposes no resolver or permit constructor. Its exported types are `RegisterWorkflowResourceInput`, `WorkflowResourceDefinition`, and `WorkflowResourceRegistration`:
8
+
9
+ ```typescript
10
+ registerWorkflowResource({
11
+ sessionId: string,
12
+ definition: {
13
+ name: string,
14
+ version: number,
15
+ resolve(args: Readonly<Record<string, unknown>>):
16
+ | { script: string; hostCommands?: readonly { key: string; command: string }[] }
17
+ | { error: string },
18
+ },
19
+ }): { dispose(): void }
20
+ ```
21
+
22
+ Names are case-sensitive, at most 128 characters, and match `[A-Za-z0-9][A-Za-z0-9._-]*`; use an extension prefix. Versions are positive safe integers. Registration throws for invalid input, protected builtins (`review`, `run-ci`), or duplicate names within the same session. Different sessions may register the same name. Dispose before replacement; there is no silent overwrite.
23
+
24
+ Register in `session_start` using **`ctx.sessionManager.getSessionId()`**, not the session file path or a tool argument. Dispose in `session_shutdown`. New/resumed/forked sessions and reloads need registration from the replacement runtime's `session_start`; do not retain old `pi`/`ctx` references. The extension owns cleanup, not an automatic registration lifecycle manager. Disposal is idempotent and cannot remove a newer replacement. Missing cleanup can cause a duplicate-registration failure on reload.
25
+
26
+ `resolve` must do synchronous, bounded validation and string construction, without I/O, SDK calls, timers or process work. Core deep-copies plain JSON args: at most 16 KiB encoded, nesting depth 8, 16 fields per object, 64 items per array, finite numbers, and nonempty strings of at most 16 KiB. The extension must additionally reject unsupported fields and validate resource-specific semantics. Throws, promises/thenables and malformed expansions fail before authority is issued; errors are bounded to 4096 characters.
27
+
28
+ Host grants bind **exact key/trimmed-command pairs**, not independent sets of keys and commands. At most 32 grants are accepted, with unique safe workflow keys and nonempty commands bounded to 16 KiB without NUL. Omitted grants give no host authority. Core snapshots the expansion and grants at resolution. Disposing stops future lookup, but already-admitted workflows retain captured grants, even after replacement. Use existing stop/deadline controls for cancellation; this does not promise survival of host shutdown or durable named scheduling. Existing child admission and capability ceilings still apply.
29
+
30
+ ### Mixed child and finite host example
31
+
32
+ This extension owns two fixed commands; `scripts/finite-check.mjs` must be an existing trusted finite helper in the workflow cwd. It runs a reviewer first, then a check. No command or flags come from free-form public args.
33
+
34
+ ```typescript
35
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
36
+ import { registerWorkflowResource } from "pi-subagents/workflow-resources";
37
+
38
+ export default function (pi: ExtensionAPI) {
39
+ let registration: { dispose(): void } | undefined;
40
+ pi.on("session_start", (_event, ctx) => {
41
+ registration?.dispose();
42
+ registration = registerWorkflowResource({
43
+ sessionId: ctx.sessionManager.getSessionId(),
44
+ definition: {
45
+ name: "acme.review-check",
46
+ version: 1,
47
+ resolve(args) {
48
+ if (Object.keys(args).some(k => k !== "task" && k !== "check"))
49
+ return { error: "Only task and check are supported." };
50
+ if (typeof args.task !== "string" || !args.task.trim() || args.task.length > 4000)
51
+ return { error: "task must contain 1–4000 characters." };
52
+ if (args.check !== "quick" && args.check !== "full")
53
+ return { error: "check must be quick or full." };
54
+ const command = args.check === "quick"
55
+ ? "node ./scripts/finite-check.mjs --mode quick"
56
+ : "node ./scripts/finite-check.mjs --mode full";
57
+ const host = { kind: "command", command, timeoutMs: 120000 };
58
+ return {
59
+ hostCommands: [{ key: "check", command }],
60
+ script: `
61
+ const review = await runs.run("review", {
62
+ agent: "reviewer", task: ${JSON.stringify(args.task)}
63
+ });
64
+ if (!review.ok) throw new Error("Review child failed");
65
+ const check = await runs.host("check", ${JSON.stringify(host)});
66
+ return { review: review.output, check };
67
+ `,
68
+ };
69
+ },
70
+ },
71
+ });
72
+ });
73
+ pi.on("session_shutdown", () => {
74
+ registration?.dispose();
75
+ registration = undefined;
76
+ });
77
+ }
78
+ ```
79
+
80
+ Invoke through the public `subagent` tool (use `async: false` for foreground):
81
+
82
+ ```json
83
+ {
84
+ "workflow": "acme.review-check",
85
+ "args": { "task": "Review the current change; return findings only.", "check": "quick" },
86
+ "async": true
87
+ }
88
+ ```
89
+
90
+ The parent evaluates child findings and ordinary command logs/status/terminal receipts; child success is not approval or proof of a clean review. The timeout above bounds the host command, not the whole workflow.
91
+
92
+ **Trust boundary:** this API composes already-loaded trusted code; it is neither authentication nor a sandbox. Session IDs scope lookup, not authorization between malicious extensions. Core owns opaque permits and provenance; caller-supplied issuer/trust/permit metadata cannot grant authority. Raw public scripts and script paths do not gain host authority, and registration is not an arbitrary-command entry point for public args.
93
+
94
+ The existing shell runner uses workflow cwd and inherited environment. Exact matching does not pin PATH resolution, executable bytes, repository helpers, or credentials. Those remain operator/extension trust responsibilities. `JSON.stringify` embeds data in JavaScript source; **it is not shell escaping**. Keep commands fixed as above, or validate strictly bounded numeric/hex tokens before binding known positions; never concatenate arbitrary task text or flags into shell commands. No new runner, cwd confinement, CI/merge policy, or SDK lifecycle framework is provided.
95
+
5
96
  ## In-process event-bus RPC
6
97
 
7
98
  Other Pi extensions can use the in-process event-bus RPC instead of scraping slash output or calling internal modules. Listen for `subagents:rpc:v1:ready`, send requests on `subagents:rpc:v1:request`, and read replies from `subagents:rpc:v1:reply:<requestId>`.
@@ -170,7 +261,7 @@ unregisterExternalRun(ctx.sessionManager.getSessionId(), "dependency-review");
170
261
 
171
262
  The API validates and caches bounded display fields when the caller registers or updates a job. FleetView reads that cache only. It does not poll caller code. `snapshotExternalRuns(sessionId)` and `listExternalRuns(sessionId)` return bounded current-session snapshots. Snapshots filter the session-qualified cache key before inspecting record fields; API-written records avoid repeated normalization through module-private provenance, while records replaced or mutated through the process-local registry are validated on demand. By default, malformed records for the requested session throw with the validation error. Display-only Fleet callers can pass `{ ignoreMalformed: true, onMalformedRecord }` to remove bad records and keep rendering with a programmatic diagnostic.
172
263
 
173
- External jobs are observational. The caller owns execution, persistence, cancellation, and result delivery. FleetView does not expose stop, steer, resume, cancel, or Herdr controls for them. Supplied report and transcript paths are shown as bounded text only; FleetView does not read arbitrary external paths.
264
+ External jobs are observational. The caller owns execution, persistence, cancellation, and result delivery. FleetView does not expose stop, steer, resume, cancel, or inspector controls for them. Supplied report and transcript paths are shown as bounded text only; FleetView does not read arbitrary external paths.
174
265
 
175
266
  ## Launch contract preflight
176
267
 
@@ -190,7 +281,8 @@ const result = await resolveSubagentLaunchContract({
190
281
 
191
282
  if (!result.ok) {
192
283
  // missing_agent, ambiguous_agent, missing_skill, denied_required_tool,
193
- // invalid_artifact_dir, invalid_cwd, or unsupported_mode
284
+ // invalid_artifact_dir, invalid_cwd, unsupported_mode, restricted_agent,
285
+ // thinking_ceiling, invalid_extension_bindings, or invalid_intercom_bridge
194
286
  throw new Error(result.message);
195
287
  }
196
288
 
@@ -200,11 +292,17 @@ console.log(result.contract.digest, result.contract.tools.effectiveAllowlist);
200
292
  Preflight covers ordinary single-agent launch resolution:
201
293
 
202
294
  - Selected agent identity and shadowed candidates.
203
- - A parsed-definition digest, including system prompt and launch-affecting model, tool, skill, extension, output, and memory fields.
295
+ - A parsed-definition digest, including system prompt and launch-affecting model, tool, skill, extension, output, and memory fields. Runtime overlays such as the Intercom bridge never change it.
204
296
  - Fresh/fork context, effective model and thinking, skill and tool resolution, direct MCP selections, runtime/configured extensions.
297
+ - The resolved Intercom bridge state (`intercomBridge.mode` and `intercomBridge.active`). An active bridge appends the bridge instruction to the child prompt and adds `contact_supervisor` to a declared tool list, exactly as execution does.
205
298
  - Artifact/session paths, async lifecycle/status/result/event/process-terminal paths, package/lifecycle versions, capability-ceiling audit data, and stable digests.
206
299
 
207
- `launchContractDigest` is the canonical digest of the caller task, effective system prompt, model candidates, effective tools/extensions/MCP (including inherited capability ceilings), output binding, and structured-output schema that ordinary foreground and async execution report in results/status/events and metadata.
300
+ `launchContractDigest` is the canonical digest of the caller task, effective system prompt (including an active bridge instruction), model candidates, effective tools/extensions/MCP (including inherited capability ceilings and the bridge tool), output binding, and structured-output schema that ordinary foreground and async execution report in results/status/events and metadata. Preflight and each execution path that reports the digest assemble it through one shared binding, so equal inputs produce equal digests.
301
+
302
+ Bridge inputs:
303
+
304
+ - `intercomBridge` replaces the global `intercomBridge` config for this launch, with the same semantics as the `subagent` tool and delegation overrides. Pass the same value to the launch you compare against. Preflight reads the global config from disk on each call while the running extension keeps the config it loaded at startup, so pass the override when the digest must not depend on that file.
305
+ - The default bridge instruction never names the parent session, so most hosts need no further input. When the configured `instructionFile` interpolates `{orchestratorTarget}`, preflight reports a `host_required` diagnostic unless the host supplies a non-empty `orchestratorTarget`; the executor derives that target with `resolveIntercomSessionTarget` from `pi-subagents/intercom-bridge`, given the parent session name and id.
208
306
 
209
307
  Boundaries:
210
308
 
@@ -294,6 +392,7 @@ Bounds:
294
392
 
295
393
  - Schemas are capped at 64 KiB; tasks and returned text/structured values are capped at 1 MiB, with smaller bounds on identity/configuration strings and a maximum `timeoutMs` of 2,147,483,647.
296
394
  - Structured delegation accepts `toolBudget: { hard: 0, block: "*" }` to block the first tool call and run a zero-tool leaf; ordinary model-facing/configured budgets keep their existing minimum of one.
395
+ - `intercomBridge` optionally replaces the global bridge config for one delegation, for example `{ mode: "off" }` when no supervisor session will answer the child. Pass the same value to `resolveSubagentLaunchContract` to compare `launchContractDigest` against the terminal response.
297
396
  - The foreground bridge retains up to 8,192 exact pending-cancellation and settled-attempt identities per extension context. If either history fills, it fails closed with `unavailable_context` for later starts rather than evicting identity facts; lifecycle reset clears the bounded history.
298
397
 
299
398
  Constraints:
@@ -366,7 +465,7 @@ Semantics:
366
465
 
367
466
  Children do not gain provider tools or extensions automatically. Add `bg_wait` to the child agent's `tools` allowlist and load each provider through `extensions` or `subagentOnlyExtensions`. The parent's effective `waitTool` setting reaches every child through its typed runtime config; `PI_SUBAGENT_WAIT_TOOL_ENABLED` keeps precedence in the parent.
368
467
 
369
- Foreground children never load the parent's ambient extensions: they share the parent's process, and loading them would start a second copy of every ambient extension, including this one, inside it. Agents that need MCP tools (`mcpDirectTools`, or MCP tools from an ambient adapter such as pi-mcp-adapter) or models from a provider extension must run as background children (`async: true`), which load the ambient extensions inside the detached runner process unless the agent sets `extensions` or the capability ceiling denies extensions.
468
+ Local foreground children never load the parent's ambient extensions: they share the parent's process, and loading them would start a second copy of every ambient extension, including this one, inside it. They do inherit the providers the parent's extensions registered, so a provider extension's models resolve in a local foreground child. Pane-native remote foreground children instead use the remote machine's provider discovery and configuration. Agents that need MCP tools (`mcpDirectTools`, or MCP tools from an ambient adapter such as pi-mcp-adapter) must run as background children (`async: true`), which load the ambient extensions inside the detached runner process unless the agent sets `extensions` or the capability ceiling denies extensions.
370
469
 
371
470
  ## External job provider bridge
372
471
 
@@ -391,6 +490,27 @@ The provider returns handles with `providerJobId`, `state`, optional `handleUrl`
391
490
 
392
491
  The async runner process does not import provider internals. It writes operation requests into its async run directory. The parent Pi process services those requests against the registered provider and writes operation responses. If the provider is not registered, the bridge fails closed with an actionable error. If a run is recovered after provider job metadata exists, the runner calls `reattach` and `result`; it does not call `start` or `follow-up` again.
393
492
 
493
+ ## Inspect integration
494
+
495
+ Inspect is the portable command and action surface for an existing async run. The public actions are:
496
+
497
+ ```ts
498
+ subagent({ action: "inspector.command", id: "<run-id>", index: 0 })
499
+ subagent({ action: "inspector.open", id: "<run-id>", index: 0, focus: true })
500
+ subagent({ action: "inspector.status", id: "<run-id>", index: 0 })
501
+ subagent({ action: "inspector.close", id: "<run-id>", index: 0 })
502
+ ```
503
+
504
+ `inspector.command` returns a standalone runner command without contacting a host or writing a binding. `inspector.open` selects an available bundled inspector plugin. `status` and `close` select the plugin that owns the run binding and report clearly when that plugin does not support the requested lifecycle action. Without an available plugin, `open` fails closed with an actionable message; ordinary launches remain headless. Closing an inspector never stops the run.
505
+
506
+ ### Herdr inspector plugin
507
+
508
+ The bundled Herdr inspector plugin supports Herdr 0.7.5+. It opens a raw dashboard pane, not the child session and not a literal attach. It reads lifecycle, status, output, and mission artifacts; steer and stop continue through pi-subagents' existing control inbox. Use `focus` only with `inspector.open`; Herdr 0.7.5 cannot focus an arbitrary existing raw pane id.
509
+
510
+ ### Ghostty inspector plugin
511
+
512
+ Ghostty 1.3+ on macOS is the second bundled open-only plugin, using Ghostty's preview AppleScript API. It splits the focused terminal and launches the read-only inspector command; status and close are unavailable because it writes no binding. Ghostty Automation permission is required.
513
+
394
514
  ## Herdr integration
395
515
 
396
516
  When Pi runs inside [Herdr](https://herdr.dev), pi-subagents automatically reports active async-run counts through Herdr pane metadata.
@@ -410,20 +530,6 @@ rows = [
410
530
  ]
411
531
  ```
412
532
 
413
- ### Inspector panes
414
-
415
- Herdr 0.7.5+ can open an on-demand inspector for an existing async run:
416
-
417
- ```ts
418
- subagent({ action: "inspector.open", id: "<run-id>", index: 0, focus: true })
419
- subagent({ action: "inspector.status", id: "<run-id>", index: 0 })
420
- subagent({ action: "inspector.close", id: "<run-id>", index: 0 })
421
- ```
422
-
423
- The inspector is a raw dashboard pane, not the child session and not a literal attach. It reads lifecycle/status/output/mission artifacts and sends `steer` or `stop` through pi-subagents' existing control inbox. Closing it never stops the run.
424
-
425
- Herdr remains optional. Ordinary launches stay headless, and missing/older Herdr versions affect only Herdr-specific inspector and project-pane actions. FleetView opens the selected active async child with `H`. Use `focus` only with `inspector.open`; Herdr 0.7.5 cannot focus an arbitrary existing raw pane id.
426
-
427
533
  ### Project panes
428
534
 
429
535
  For substantial work in another codebase, Herdr 0.7.5+ can open a project-owned Pi pane rooted in that repository:
@@ -469,6 +575,8 @@ Detached children do not stop when the session does. They are the host process's
469
575
 
470
576
  This matters because "is the parent busy?" is the wrong idle signal. A parent that launches a detached run and hands control back — which is what the async launch output tells it to do — is not prompting, streaming, compacting, or running a shell command. A host that reaps sessions on those signals alone will dispose exactly the session that was waiting to be woken.
471
577
 
578
+ When pi-subagents runs inside a compatible pi-web host, it discovers the versioned `Symbol.for("@agegr/pi-web/session-liveness/v1")` registry and registers one provider for the current session. The provider reports live `queued`/`running` async jobs, active nested descendants (including foreground routes retained after their direct parent settles), foreground controls that still have a scheduling owner or active child, and completion notifications waiting for their batch-delivery timer. Retained terminal history, future schedules, and wait subscriptions do not make a session live by themselves. The registration is replaced on session changes and released during runtime shutdown or reload; other hosts remain unaffected.
579
+
472
580
  If your host reclaims idle sessions, keep a session alive while it still has live detached work:
473
581
 
474
582
  - Read run state from the status files under the async run directory rather than from event traffic. A long, quiet workflow sends almost nothing to the parent, so recent-activity heuristics conclude the wrong thing.
@@ -486,6 +594,7 @@ The main runtime files in this repository:
486
594
  | File | Purpose |
487
595
  |------|---------|
488
596
  | `src/extension/index.ts` | Extension registration, tool registration, message/render wiring. |
597
+ | `src/integrations/pi-web-session-liveness.ts` | Optional pi-web idle-eviction liveness bridge. |
489
598
  | `src/agents/agents.ts` | Agent and chain discovery, frontmatter parsing. |
490
599
  | `src/runs/foreground/subagent-executor.ts` | Main execution routing for single, parallel, chain, management, status, interrupt, and doctor actions. |
491
600
  | `src/runs/foreground/execution.ts` | Core foreground `runSync` handling: drives one in-process child session per attempt. |
@@ -505,3 +614,7 @@ The main runtime files in this repository:
505
614
  | `src/intercom/intercom-bridge.ts` | Runtime intercom bridge instructions and diagnostics. |
506
615
  | `src/extension/schemas.ts` / `src/shared/types.ts` | Tool schemas, shared types, and event constants. |
507
616
  | `test/unit/` / `test/integration/` | Unit and loader-based integration tests. |
617
+
618
+ ### Published package vs source checkout
619
+
620
+ The npm tarball ships TypeScript compiler output with the same file layout and a compiled `index.js` entry. A Git checkout continues to run `index.ts` directly, so local extension development does not require a build step. Run `npm run pack:pkg` to build and pack the same artifact published to npm.
package/docs/missions.md CHANGED
@@ -103,10 +103,16 @@ subagent({
103
103
  Create a fixed recurring workflow:
104
104
 
105
105
  ```ts
106
- subagent({ action: "schedule.create", id: "backlog", every: "6h", catchUp: "latest", workflowScript: "..." })
106
+ subagent({ action: "schedule.create", id: "backlog", every: "6h", catchUp: "latest", workflowScript: "return runs.run('main', { agent: 'worker', task: args.task })", args: { task: "Maintain core" } })
107
107
  ```
108
108
 
109
- Fixed intervals support `m`, `h`, `d`, and `w` units and advance from the planned time without completion drift.
109
+ Fixed intervals support `m`, `h`, `d`, and `w` units and advance from the planned time without completion drift. Schedule arguments are normalized and persisted for exact replay after reload; do not put secrets in them.
110
+
111
+ Create a quiet recurring workflow whose successful completions stay visible but do not wake the parent session:
112
+
113
+ ```ts
114
+ subagent({ action: "schedule.create", id: "nightly-sweep", every: "24h", quiet: true, workflowScript: "..." })
115
+ ```
110
116
 
111
117
  Manage schedules with `schedule.list`, `schedule.show`, `schedule.history`, `schedule.pause`, `schedule.resume`, `schedule.run`, `schedule.run-due`, and `schedule.delete`.
112
118
 
@@ -116,6 +122,8 @@ Behavior:
116
122
  - An optional top-level `baseRef` selects the safe Git ref used by managed worktrees (default `HEAD`); it is persisted with the schedule and forwarded on every fire. The source checkout must still be clean.
117
123
  - Definitions, bounded history, append-only events, and per-run receipts are stored with mode `0600`.
118
124
  - `overlap` is currently fixed to `skip`; `catchUp` supports `latest` (default) and `none`.
125
+ - A successful `schedule.run` satisfies the next natural fire; a failed manual launch does not skip it.
126
+ - `quiet` persists only on recurring (`every`) schedules. Successful automatic fires stay visible without a parent turn; failed, stopped, or paused outcomes still wake the session. One-shot `at` schedules and `schedule.run` stay noisy unless that launch passes `quiet: true`.
119
127
  - `schedule.run-due` lets an external launcher start due project work without making `pi-subagents` a daemon.
120
128
  - Calendar recurrence, cron, queue/replace overlap, and the schedule TUI inspector are intentionally deferred to the next slice.
121
129
  - The old `schedule`, `schedule-list`, `schedule-status`, and `schedule-cancel` actions were removed in a hard cutover.
package/docs/models.md CHANGED
@@ -13,6 +13,8 @@ Builtin agents inherit your current Pi default model. This keeps new installs fr
13
13
 
14
14
  Precedence, strongest first: per-run override → provider-scoped role override → `agentOverrides.<name>.model` → agent frontmatter `model` → `subagents.defaultModel` → the parent session model. A provider preference does not replace this order; it only resolves bare model ids when the active registry has more than one match. Fully qualified `provider/model` strings still win exactly.
15
15
 
16
+ Each launch resolves one model. Provider errors, including HTTP 429 responses, are returned from that model rather than selecting another one. Separately, a verified compaction abort after useful progress may continue the retained child session once on the same resolved model; this lifecycle recovery preserves work and is not model fallback.
17
+
16
18
  Use `model: "inherit"` in agent frontmatter or `agentOverrides.<name>.model` to select the current parent session model explicitly.
17
19
 
18
20
  ## Setting defaults and overrides
@@ -57,7 +59,7 @@ To keep one role definition but configure it differently for work and personal p
57
59
  }
58
60
  ```
59
61
 
60
- The provider key comes from the active parent session model (or an explicit host `preferredProvider`) before fallback selection. Provider-scoped fields layer over the ordinary override in the same settings file; project settings still win over user settings. A fallback attempt does not switch the selected provider configuration.
62
+ The provider key comes from the active parent session model (or an explicit host `preferredProvider`). Provider-scoped fields layer over the ordinary override in the same settings file; project settings still win over user settings.
61
63
 
62
64
  For one run, put the override in the command:
63
65
 
@@ -65,7 +67,7 @@ For one run, put the override in the command:
65
67
  /run reviewer[model=anthropic/claude-sonnet-4:high] "Review this diff"
66
68
  ```
67
69
 
68
- For a persistent role override with a backup model for provider failures:
70
+ For a persistent role override:
69
71
 
70
72
  ```json
71
73
  {
@@ -73,8 +75,7 @@ For a persistent role override with a backup model for provider failures:
73
75
  "agentOverrides": {
74
76
  "reviewer": {
75
77
  "model": "anthropic/claude-sonnet-4",
76
- "thinking": "high",
77
- "fallbackModels": ["openai-codex/gpt-5.6-luna:low"]
78
+ "thinking": "high"
78
79
  }
79
80
  }
80
81
  }
@@ -87,7 +88,7 @@ For a persistent role override with a backup model for provider failures:
87
88
 
88
89
  Set `fast: true` on a run, in agent frontmatter, or in `subagents.agentOverrides.<name>.fast` to request the OpenAI priority service tier for supported native OpenAI-Codex children. This can use a higher quota tier or cost more. It is off by default.
89
90
 
90
- Fast mode fails before launch unless every resolved model candidate is on the allowlist. The current allowlist is `openai-codex/gpt-5.6-luna` and `openai-codex/gpt-5.6-sol`. External runners, Anthropic models, and other providers do not use fast mode.
91
+ Fast mode fails before launch unless the resolved model is on the allowlist. The current allowlist is `openai-codex/gpt-5.6-luna` and `openai-codex/gpt-5.6-sol`. External runners, Anthropic models, and other providers do not use fast mode.
91
92
 
92
93
  ## Recommended model tiering (optional)
93
94
 
@@ -100,19 +101,7 @@ A setup that works well in practice: route agents by task shape instead of runni
100
101
 
101
102
  The routing rule: use the capability tiers (1–3) when the task is well-scoped, and the intent tier (4) when scoping or judging is the task itself.
102
103
 
103
- Give tier-4 agents cross-provider `fallbackModels` so subscription usage limits degrade gracefully instead of failing the run. Fallback triggers on retryable provider/model failures such as rate-limit, overload, unavailable-model, and provider-reported timeout errors. The outer run-level `timeoutMs` / `maxRuntimeMs` deadline is terminal and does not start another fallback attempt:
104
-
105
- ```yaml
106
- ---
107
- name: shaper
108
- description: Open-ended design/UX/product/planning agent for ambiguous tasks
109
- model: anthropic/claude-fable-5
110
- thinking: medium
111
- fallbackModels: openai-codex/gpt-5.5:high
112
- ---
113
- ```
114
-
115
- One interaction worth knowing for tier 4: forked context over an Anthropic parent transcript with signed thinking blocks forces the child's thinking off, so intent-tier agents work best with fresh context.
104
+ Each launch resolves one model and starts the child once. Provider, authentication, quota, rate-limit, stream, empty-response, context-overflow, and provisioning failures are returned from that attempt. To try another model, the parent or operator must issue a later explicit launch.
116
105
 
117
106
  ## Thinking level defaults
118
107
 
@@ -144,7 +133,7 @@ Set `subagents.maxThinking` to enforce a hard maximum for every native Pi child.
144
133
  }
145
134
  ```
146
135
 
147
- Requests above the ceiling fail before child startup; the setting covers frontmatter, `agentOverrides`, per-run overrides, fallback models, parallel/chain children, nested launches, and resumed children. Project settings take precedence over user settings. External runners retain their existing behavior.
136
+ Requests above the ceiling fail before child startup; the setting covers frontmatter, `agentOverrides`, per-run overrides, parallel/chain children, nested launches, and resumed children. Project settings take precedence over user settings. External runners retain their existing behavior.
148
137
 
149
138
  ## Extension defaults
150
139
 
@@ -219,11 +208,11 @@ To keep subagents inside a budget or compliance profile, enforce a model scope.
219
208
  - `agents.<name>` adds a second allow-list for that agent. The model must pass both the global list and the matching agent list, so an agent rule cannot weaken the global rule. Agent rules inherit `enforce` and `strict` when those fields are absent.
220
209
  - A top-level `enforce: true` with only agent allow-lists restricts only those named agents. Unknown names are allowed so settings can be shared across projects and machines.
221
210
  - Models you pass explicitly — the tool-call `model`, `--model`, or a clarify pick — error and abort the run.
222
- - By default, models from agent frontmatter, `subagents.defaultModel`, the inherited parent session model, or fallback chains only warn and remain available, so existing configurations keep working while you tighten the scope.
223
- - Set `strict: true` with `enforce: true` to reject every resolved out-of-scope model. This includes inherited models and fallback candidates. An invalid fallback fails the run instead of being removed from the candidate chain.
211
+ - By default, models from agent frontmatter, `subagents.defaultModel`, or the inherited parent session model only warn and remain available, so existing configurations keep working while you tighten the scope.
212
+ - Set `strict: true` with `enforce: true` to reject every resolved out-of-scope model, including inherited models.
224
213
  - `enforce: true` requires at least one non-empty global or agent `allow` list; otherwise the config is rejected at load time.
225
214
 
226
- Model scope is policy only. It rejects or warns; it does not select a cheaper model. Set `agentOverrides.worker.model` to choose a worker model and use `modelScope.agents.worker` to prevent a per-run override or fallback from escaping that restriction.
215
+ Model scope is policy only. It rejects or warns; it does not select a cheaper model. Set `agentOverrides.worker.model` to choose a worker model and use `modelScope.agents.worker` to prevent a per-run override from escaping that restriction.
227
216
 
228
217
  `inherit` expands in the parent process at each launch. It is never sent to the child as a model id. A nested child therefore inherits its immediate parent's current model, not the original top-level model. If no parent model is available, an enforced `inherit` entry does not match and fails closed.
229
218
 
@@ -12,7 +12,7 @@ A background child is a pi session created inside the detached runner process. T
12
12
 
13
13
  Live progress shows compact detail for single, chain, and parallel modes: a bounded one-line task, current tool, recent output, token counts, aggregate cost, duration, activity freshness, current-tool duration, and chain graph metadata when available. Workflow `label` metadata wins over raw task text in compact multi-child cards.
14
14
 
15
- Press Pi's configured expand key (`Ctrl+O` by default) to expand the full streaming view with complete output per step. Running-card hints also advertise `Ctrl+Alt+F` for the Fleet inspector.
15
+ Press Pi's configured expand key (`Ctrl+O` by default) to expand the full streaming view with complete output per step.
16
16
 
17
17
  Sequential chains show a flow line like `done scout → running worker`. Chains with parallel steps show per-step cards instead. Chain status uses `label` and `phase` metadata when present, while falling back to agent names for older chains.
18
18
 
@@ -35,11 +35,42 @@ async subagent worker · background
35
35
  ● Step 1/1: worker · running
36
36
  task: Review authentication boundaries
37
37
  ⎿ read: src/auth.ts | 2.0s
38
- Press configured-expand-key for live detail · Ctrl+Alt+F Fleet
38
+ Press configured-expand-key for live detail
39
39
  ```
40
40
 
41
41
  To inspect one background child in text, use `subagent({ action: "status", id: "...", view: "transcript" })`; add `index` for a specific child in a parallel or chain run.
42
42
 
43
+ In Pi fullscreen mode with mouse dispatch (verified with Pi TUI 0.85.1), left-click
44
+ anywhere on the async widget's header row to fold it into a live one-line status
45
+ summary. Click again to restore the usual layout. No knowledge of extension commands
46
+ or keyboard shortcuts is needed. The summary counts the widget's tracked runs,
47
+ including workflow parents and children, rather than unique agents.
48
+
49
+ Folding stays in effect across progress updates and does not change Pi's global
50
+ expand setting, run execution, or completion notifications. Task rows, drag and
51
+ wheel events, and modifier clicks are left unhandled. The state resets when the
52
+ widget is removed or Pi reloads. Regular mode keeps the existing keyboard controls.
53
+
54
+ ### Reducing status display noise
55
+
56
+ Chat records tool-call history; FleetView and the async widget show live run/child updates. Separate `subagent({ action: "status", id: "..." })` calls leave separate historical entries even when their `Status target: run …` labels match. A matching run ID identifies the queried run, not the tool call, and is not evidence of duplicate execution. Live Fleet/widget refreshes do not merge those entries.
57
+
58
+ For compact chat results with FleetView as the only live editor surface, merge these top-level keys into `~/.pi/agent/extensions/subagent/config.json` (not Pi's `settings.json` or a `subagents` object), then restart Pi:
59
+
60
+ ```json
61
+ {
62
+ "inlineToolDisplay": "summary",
63
+ "fleetView": true,
64
+ "asyncWidget": false
65
+ }
66
+ ```
67
+
68
+ - `inlineToolDisplay: "summary"` keeps one static result row per call, alongside its call heading. A completed status query is not proof that the queried child has finished.
69
+ - `fleetView: true` retains live progress. Open `/subagents-fleet` for details instead of repeatedly requesting status just to watch progress. Pi's expand key does not expand summary results; keep `"rich"` if you want expandable inline output.
70
+ - `asyncWidget: false` hides only the additional under-editor async widget, leaving FleetView available. This configuration reduces visible surfaces; it does not guarantee ordering relative to other extensions.
71
+
72
+ Thanks to [DraconDev](https://github.com/DraconDev) for reporting the display noise and suggesting summary mode in [#1931](https://github.com/nicobailon/pi-subagents/issues/1931).
73
+
43
74
  ## FleetView
44
75
 
45
76
  In the TUI, a persistent FleetView below the editor keeps active work visible as a compact summary. Set `fleetViewPlacement` to `"aboveEditor"` to move it above the editor.
@@ -58,9 +89,9 @@ After you expand it:
58
89
  reviewer · running 38s · ↓ 1.1k window · 1.4k spent
59
90
  ```
60
91
 
61
- When the focused editor is empty, press `↓` or `←` to expand the summary into `main` plus active children with agent name, state, elapsed time, and token usage. When providers report usage, `window` is the latest assistant turn's input plus cache-read tokens, while `spent` keeps the cumulative input-plus-output total. Old run artifacts without window data keep the existing token-total label. The compact line counts active current-session work and Herdr project panes. Then use `↑`/`↓` or `j`/`k` to select a child and `Enter` to open the Fleet lobby; press `Enter` or `H` there to open its child-specific Herdr inspector. Printable navigation keys are never intercepted before activation.
92
+ When the focused editor is empty, press `↓` or `←` to expand the summary into `main` plus active children with agent name, state, elapsed time, and token usage. When providers report usage, `window` is the latest assistant turn's input plus cache-read tokens, while `spent` keeps the cumulative input-plus-output total. Old run artifacts without window data keep the existing token-total label. The compact line counts active current-session work and Herdr project panes. Then use `↑`/`↓` or `j`/`k` to select a child and `Enter` to open the Fleet lobby; press `Enter` or `H` there to open its child-specific inspector through an available Inspect plugin. Printable navigation keys are never intercepted before activation.
62
93
 
63
- FleetView replaces the legacy above-editor async widget by default. Successful background completions stay quiet so inactive Pi tabs are not marked unread, while failed or paused completions still notify the originating session. Parallel runs show every active child independently. Chains with parallel groups keep their grouped shape in progress and results, so failed or paused agents stay visible next to completed ones. When a child is explicitly allowed to fan out with `tools: subagent` or `allowNestedSubagents: true`, its nested runs appear under that parent child in the main status tree instead of being hidden inside the child session.
94
+ FleetView and the under-editor async widget are both enabled by default; set `asyncWidget: false` to keep only FleetView. Successful background completions stay quiet so inactive Pi tabs are not marked unread, while failed or paused completions still notify the originating session. Parallel runs show every active child independently. Chains with parallel groups keep their grouped shape in progress and results, so failed or paused agents stay visible next to completed ones. When a child is explicitly allowed to fan out with `tools: subagent` or `allowNestedSubagents: true`, its nested runs appear under that parent child in the main status tree instead of being hidden inside the child session.
64
95
 
65
96
  ## The fleet inspector
66
97
 
@@ -72,18 +103,22 @@ Default keys:
72
103
  - `Shift+K`/`Shift+J` — scroll one line
73
104
  - `PgUp`/`PgDn` — scroll one page
74
105
  - `x`/`Ctrl+O` — toggle tool details
106
+ - `t`/`T` — expand or collapse the replayed assistant thinking blocks
107
+ - `v` — switch between the structured transcript and the plain-text view
75
108
  - `r` — refresh
76
109
  - `Esc` — close
77
- - `Enter` — open the selected inspectable async child in its child-specific Herdr inspector
110
+ - `Enter` — open the selected inspectable async child through the available Inspect plugin
78
111
  - `s` — compose an acknowledged message to a selected live async child; Tab cycles `steer`, `follow_up`, and `auto`
79
112
  - `D` — stop a selected child's top-level async run after confirmation
80
- - `H` — open the selected active async child in a Herdr inspector pane (Herdr 0.7.5+)
113
+ - `H` — open the selected active async child through the available Inspect plugin
81
114
 
82
115
  Set `fleetKeybindings` in the extension config to replace inspector-level keys when a terminal intercepts keys such as `PgUp`, `PgDn`, `Home`, or `End`. Prompt modes keep fixed keys such as `Esc`, `Enter`, `Tab`, and stop-confirmation `Y`/`N`.
83
116
 
117
+ In the structured view every replayed assistant message keeps its own thinking block, collapsed by default to a `Thinking` label that names the expand key. The plain-text view (`v`) carries no thinking entries.
118
+
84
119
  `Ctrl+Alt+F` opens the same inspector even while a foreground turn is active and slash input is queued.
85
120
 
86
- Enter and `H` use the existing Herdr pane path. In a child-specific Herdr inspector, type ordinary guidance and press Enter to send it through the acknowledged steer channel; `steer <message>`, `status`, and `stop` remain available as explicit controls.
121
+ Enter and `H` use the available Inspect plugin. On macOS with Ghostty 1.3+ (TERM_PROGRAM=ghostty), this includes the other bundled open-only plugin using Ghostty's preview AppleScript API; status and close are unavailable because no binding is written. In a child-specific inspector, type ordinary guidance and press Enter to send it through the acknowledged steer channel; `steer <message>`, `status`, and `stop` remain available as explicit controls. The bundled Herdr plugin uses Herdr 0.7.5+.
87
122
 
88
123
  Without a TUI, `/subagents-fleet` retains the textual `subagent({ action: "status", view: "fleet" })` fallback, and mutations use explicit commands: run `/subagents-stop` and pick from the selector, or use `/subagents-stop <run-id>` / `subagent({ action: "stop", id: "..." })` when you already know the id.
89
124
 
@@ -158,7 +193,6 @@ Async runs write machine-readable lifecycle artifacts for observability and work
158
193
  - `status.json` powers the widget and `subagent({ action: "status" })` output.
159
194
  - `events.jsonl` contains wrapper events plus child Pi JSON events annotated with run and step metadata, including correlated `subagent.steer.requested`, `scheduled`, `routed`, `queued`, `delivered`, `failed`, and `recovered` events plus failure/partial/recovery notices.
160
195
  - `output-<n>.log` is a live human-readable tail.
161
- - Fallback information is persisted so background runs are debuggable after completion.
162
196
 
163
197
  For a top-level async run, `details.asyncDir` points at that directory; the final summary is written to Pi's subagent results directory as `<runId>.json`. Nested async runs use the same shape under the nested async root and are discoverable through status projections that read the nested-run registry. These files are append/update artifacts only; interactive foreground behavior is unchanged.
164
198
 
@@ -185,7 +219,9 @@ stop API.
185
219
 
186
220
  ### Status and result fields
187
221
 
188
- The status/result fields are: `lifecycleArtifactVersion`, `runId`/`id`, `sessionId`, `mode`, `state`, `startedAt`, `lastUpdate`, `endedAt`, `durationMs`, `cwd`, `asyncDir`, `sessionFile`, `outputFile`, `workflowGraph`, `steps`, `results`, `totalTokens`, `totalCost`, `model`/`attemptedModels`/`modelAttempts`, `toolCount`, `turnCount`, optional `launchResolvedExtensions`, optional `runtimeAcknowledgedExtensions`, and nested `children` when a child is allowed to launch subagents.
222
+ The status/result fields are: `lifecycleArtifactVersion`, `runId`/`id`, `sessionId`, `mode`, `state`, `startedAt`, `lastUpdate`, `endedAt`, `durationMs`, `cwd`, `asyncDir`, `sessionFile`, `outputFile`, `workflowGraph`, `steps`, `results`, `totalTokens`, `totalCost`, `model`/`requestedModel`, `toolCount`, `turnCount`, optional `launchResolvedExtensions`, optional `runtimeAcknowledgedExtensions`, and nested `children` when a child is allowed to launch subagents.
223
+
224
+ `requestedModel` records the launch's requested model (the explicit `--model` override, else the agent's configured model) before registry normalization.
189
225
 
190
226
  `launchResolvedExtensions` is parent-resolved launch intent only: it reports opaque extension identifiers and whether ambient extensions were disabled, without exposing raw extension paths or claiming the child runtime acknowledged that those extensions loaded.
191
227
 
@@ -203,7 +239,7 @@ The reported `runtimeAcknowledgedExtensions` projection is `{ version: 1, source
203
239
 
204
240
  ### Process-terminal proof
205
241
 
206
- Lifecycle artifact v3 adds `process-terminal-candidate.json` (private runner evidence) and `process-terminal.json` (the public proof projection).
242
+ Lifecycle artifacts include `process-terminal-candidate.json` (private runner evidence) and `process-terminal.json` (the public proof projection).
207
243
 
208
244
  A proof is `observed` only after the live parent observes the exact detached runner's `close` event and any tracked canonical-session lease is free. Children run inside the runner process, so the candidate records no separate writer processes. If the observer is unavailable, the proof is `unknown`; do not infer process exit from `endedAt`, result-file existence, PID disappearance, or lease-directory absence.
209
245
 
@@ -213,6 +249,26 @@ The `subagent:process-terminal` event and RPC `ping.capabilities.processTerminal
213
249
 
214
250
  Both launch paths subscribe to the child session's event stream directly; there is no stdout protocol. The `events.jsonl` artifact mirrors those events with `message_update` dropped, and the transcript records them with `message_update` projected the same way pi's JSON mode prints it. `agent_end.willRetry` defers completion until the child settles, and `agent_settled` is the terminal watermark; a child whose run does not settle shortly after its terminal event is aborted and finished without it.
215
251
 
252
+ ### Completion notification diagnostics
253
+
254
+ For an instrumented parent session, enable Node's opt-in debug sink **before starting Pi**:
255
+
256
+ ```sh
257
+ NODE_DEBUG=pi-subagents-notify pi 2>notification-debug.log
258
+ ```
259
+
260
+ This writes bounded JSON records prefixed `PI-SUBAGENTS-NOTIFY <pid>:` to stderr, not run artifacts or chat. The capture also contains other stderr output; review it before sharing. Records contain only `reason`, sanitized `id`/`runId` (up to 128 characters each), and `source`; task/output text, paths, credentials, and exception bodies are not included.
261
+
262
+ - `disposed`, `missing_session`, `foreground_session_mismatch`, `not_owned`: delivery rejected by an existing guard.
263
+ - `emit_foreground_session_mismatch`, `emit_not_owned`: ownership/session recheck rejected emission.
264
+ - `intercom_delivered`, `deduped_ttl`: already acknowledged; no new message needed.
265
+ - `deduped_pending`: shares an in-flight delivery promise.
266
+ - `batch_deferred`: held for batching, **not lost**; look for a later emission or disposal record for the same run.
267
+ - `send_accepted`, `send_failed`: `sendMessage` returned or threw, respectively. Acceptance is not proof the model read the message; failures remain retryable.
268
+ - `dispose_pending`: notifier shutdown left held results unacknowledged for later delivery.
269
+
270
+ Without `NODE_DEBUG`, tracing only checks the debug-enabled flag: no identity sanitization/serialization, diagnostic buffering, or log I/O. Existing delivery guards, TTL, timers and batching are unchanged. Traces cover notifier decisions only, not discovery gaps; absence of a trace does not diagnose the original missing-notification symptom.
271
+
216
272
  ## Workflow and debug artifacts
217
273
 
218
274
  Each scripted workflow stores runtime artifacts under a workflow artifact directory. The on-disk directory is still named `chain-runs` for compatibility. With the default `artifactDir: "session"` or with `"temp"`, it is user-scoped temp storage. With `artifactDir: "project"`, the root is `<cwd>/.pi/subagents/chain-runs/`:
@@ -230,7 +286,7 @@ Debug artifacts live under `{sessionDir}/subagent-artifacts/`, `.pi/subagents/ar
230
286
  - `{runId}_{agent}.jsonl`
231
287
  - `{runId}_{agent}_meta.json`
232
288
 
233
- Metadata records timing, usage, exit code, final model, attempted models, fallback attempt outcomes, and the resolved acceptance ledger with its parsed child report.
289
+ Metadata records timing, usage, exit code, the resolved model, and the resolved acceptance ledger with its parsed child report. A strictly guarded retained-session recovery after a verified compaction abort may continue once on that same model; it never selects another model.
234
290
 
235
291
  For npm package projects, project-scoped artifacts need a `.npmignore` rule (or `.gitignore` when no `.npmignore` exists) or a `files` allowlist that does not include `.pi/subagents/`. pi-subagents warns at launch when these package settings can include the artifacts. Use `artifactDir: "session"` or `"temp"` to keep them outside the package worktree.
236
292
 
@@ -0,0 +1,59 @@
1
+ # Standalone background execution
2
+
3
+ Supported standalone target: **official Pi 0.85.1, Linux x64**. Keep its adjacent release assets with the executable. Other versions, operating systems, architectures and packagers are outside the fully validated support target; limited experimental Windows coverage is described below.
4
+
5
+ Pi's extension loader supplies its embedded SDK to `binary-bootstrap.ts`, which awaits the existing configured runner before exiting. Startup authorization, revival leases, controls, disposal and process-close observation remain shared with npm. Each independent run has its own host; native sessions inside that run share it. No per-session CLI protocol, runtime download/install, alternate SDK or foreground fallback is introduced. Npm Pi keeps its Node runner, peer aliases and detected npm `PI_PACKAGE_DIR` override (including refusal when no npm root exists).
6
+
7
+ Implementation and lifecycle fixtures derive from [@xz-dev](https://github.com/xz-dev)'s [PR #2049](https://github.com/nicobailon/pi-subagents/pull/2049), source commit `910807bfefcf9ee41d73fa25ec86dcd75ab8f4b2` (Xiangzhe, `xiangzhedev@gmail.com`). Integration retains the lifecycle contract and reduces commentary rather than removing its evidence gates.
8
+
9
+ ## Experimental Windows host recognition
10
+
11
+ The resolver recognizes Bun's Windows virtual entrypoint prefixes, `B:/~BUN/` and `B:\~BUN\`, alongside `/$bunfs/`. It launches the real `process.execPath` (or the existing executable override). The `B:` prefix is virtual, not the installation drive; `pi-native.exe` is not a required executable name.
12
+
13
+ A local Windows x64 smoke passed with **xz-dev/pi `0.85.1-xz.169.1.gb5f4d0ff`, Bun 1.4.2**: a fresh async worker executed a read-only Git command, returned its result, delivered the native completion notification, and exited with code 0 and no remaining runner process. This is not validation of the official Windows distribution or every Bun-compiled Pi host. Windows remains **experimental**: the full standalone lifecycle matrix has not been validated there.
14
+
15
+ Node-hosted npm Pi keeps its existing runner path and is not affected by this virtual-entrypoint detection defect. Installing only the pi-subagents extension through npm does not change a Bun-compiled Pi host into an npm Pi host.
16
+
17
+ ## Official binary gate
18
+
19
+ On Linux x64 with Node, npm, tar and bubblewrap installed, provision dependencies and the checksum-pinned release separately from execution:
20
+
21
+ ```bash
22
+ npm ci --ignore-scripts
23
+ release_dir="$(mktemp -d)"
24
+ url="$(node -p 'require("./test/smoke/standalone-release.json").url')"
25
+ sha="$(node -p 'require("./test/smoke/standalone-release.json").archiveSha256')"
26
+ curl --fail --location --retry 3 "$url" --output "$release_dir/release.tar.gz"
27
+ printf '%s %s\n' "$sha" "$release_dir/release.tar.gz" | sha256sum --check -
28
+ tar -xzf "$release_dir/release.tar.gz" -C "$release_dir"
29
+ node test/smoke/standalone-matrix.mjs "$release_dir/pi/pi" "$(mktemp -d)/matrix"
30
+ ```
31
+
32
+ The `official-standalone` CI job runs this gate. Both archive and executable hashes are pinned. Each of 18 modes gets a fresh stage with no filesystem core SDK/shim, empty installation caches and isolated network/PID namespaces. Bare-Bun SDK import must fail; accepted execution uses Pi's actual loader. Missing sandbox support fails rather than skips. Use disk-backed storage: retained stages can occupy several GiB.
33
+
34
+ The matrix covers public launch/notification, workflows, same-run concurrent sessions, parallel stop, targeted steer/interrupt, child/tool/run deadlines, missing bootstrap, post-spawn persistence/authorization failures, SDK initialization failure, malformed bootstrap input/EOF with an authorized positive control, and competing revival. The provider is deterministic, but SDK sessions, runner and public extension are real. Only startup-failure writes are faulted.
35
+
36
+ `matrix.json` records complete/partial results; `inputs.json` freezes source identities and every mode must use the same package hash. Inspect per-mode logs, `identity.json`, lifecycle/notification evidence, `status.json` and `process-terminal.json`. A persisted result is not exit proof: the gate separately awaits observed close, verifies dead PIDs before sandbox teardown and checks session shutdown/lease release. CI retains receipts and at most 32 MiB compressed lifecycle evidence. Contributor-head passes do not establish acceptance for a different integration snapshot.
37
+
38
+ For a focused diagnostic, use `node test/smoke/standalone-background.mjs "$release_dir/pi/pi" "$(mktemp -d)/check" bootstrap-errors` (or another matrix mode). A focused pass is not the complete gate.
39
+
40
+ ## Npm regressions and local trial
41
+
42
+ Existing npm clean-install CI covers real SDK 0.85.1. The standalone CI job also checks the public npm launch path without execution-time network:
43
+
44
+ ```bash
45
+ npm_checks="$(mktemp -d)"
46
+ node test/smoke/clean-install.mjs "$npm_checks/sdk" 0.85.1
47
+ node test/smoke/npm-background.mjs "$npm_checks/sdk" "$npm_checks/launch"
48
+ ```
49
+
50
+ To try a checkout without replacing your installation, start a separate supported Pi process with an isolated agent directory:
51
+
52
+ ```bash
53
+ PI_CODING_AGENT_DIR="$(mktemp -d)" "$release_dir/pi/pi" \
54
+ --no-extensions --no-skills --no-prompt-templates --extension "$PWD/index.ts"
55
+ ```
56
+
57
+ This command targets a source checkout. The published npm package uses the compiled `index.js` entry instead.
58
+
59
+ Configure a provider in that isolated session, ask for a read-only background child and inspect its notification/run artifacts. This loads only the checkout for that process; it does not install the candidate or reuse normal credentials. Keep the parent alive for notifications.