pi-herdr-agents 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -7,7 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-## [v1.5.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.4.2...v1.5.0)
+## [v1.5.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.5.0...v1.5.1)
+
+### Merged
+
+- Fix subagent lifecycle, resume permissions, and failure reporting [`#30`](https://github.com/giuseppecrj/pi-herdr-agents/pull/30)
+
+### Commits
+
+- fix(subagents): preserve capabilities across resume (#26) [`9b46c5c`](https://github.com/giuseppecrj/pi-herdr-agents/commit/9b46c5c612c299ca9bb2ad3b6511b0af53438814)
+- fix(subagents): preserve model failure evidence and fallback delivery (#24) [`a6366ee`](https://github.com/giuseppecrj/pi-herdr-agents/commit/a6366eea08ec6679535f3f4fa9dbd6c9201254e9)
+- fix(roles): reject malformed capability declarations (#27) [`0d263b8`](https://github.com/giuseppecrj/pi-herdr-agents/commit/0d263b8867e1708288302e0f9a5c9b806c810345)
+- fix(workflows): join child cleanup before terminal delivery (#25) [`e928817`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e9288172b8037b39ed04107ad0729292ea596a8f)
+- test(integration): assert cwd and session delivery structurally (#28) [`ec277ff`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ec277ff9ddf4b309edb1f12942acac68ee295eb2)
+
+## [v1.5.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.4.2...v1.5.0) - 2026-09-05
 
 ### Merged
 
@@ -28,6 +42,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - feat: allow disabling bundled agent roles [`e866ade`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e866ade49f35c7bd51931c1e216fd9749abca2e8)
 - fix: distinguish role-pack replacements from bundled warnings [`d4452c8`](https://github.com/giuseppecrj/pi-herdr-agents/commit/d4452c8994c61607d2c1d1259679c1b7f7be8780)
 - fix: address evaluation validator review findings [`406d1ab`](https://github.com/giuseppecrj/pi-herdr-agents/commit/406d1ab9e1a129d336ed0b850508d335b130e156)
+- chore: release v1.5.0 [`d77714c`](https://github.com/giuseppecrj/pi-herdr-agents/commit/d77714c79123db91d4741838587b4851527c4615)
 
 ## [v1.4.2](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.4.1...v1.4.2) - 2026-08-31
 

package/CONTEXT.md

@@ -33,7 +33,7 @@ The runner-owned append-only `run.jsonl` that starts with approval binding the w
 _Avoid_: User-authored plan, mutable audit log, duplicated result
 
 **Terminal lifecycle**:
-Completed read and review panes close after result capture while child session files and run evidence remain. Writer-worktree retention belongs to a deferred writer workflow.
+Every workflow terminal path stops queued work and accounts for active read and review panes before checkout disposal and final delivery. Completed panes close after result capture while child session files and run evidence remain. Unconfirmed child exit retains the checkout and ends failed with `cancel_termination_failed`. Writer-worktree retention belongs to a deferred writer workflow.
 _Avoid_: Retaining every clean pane, deleting review evidence
 
 **Restart boundary**:

package/README.md

@@ -342,12 +342,25 @@ followed by agent frontmatter, per-agent config, the global default, and finally
 the parent model. Model values must be exact authenticated `provider/model-id`
 references. A value can contain an ordered comma-separated fallback list, for
 example `provider/preferred, provider/fallback`. The extension validates every
-candidate before launch, retries the preferred model normally, then launches
-later candidates only after a provider/agent request failure. A completed child
-result, including a negative task result, never switches models. Completion
-metadata and the status widget report the model actually used; an exhausted
-list reports every attempted model. Workflow metadata accepts one exact model
-only, to keep approved workflow runtimes deterministic.
+candidate before launch, then launches later candidates only after the selected
+child settles with a provider/agent error. Pi owns any automatic transient
+retrying inside that child; the extension does not infer retry counts or
+permanence from the error text. A completed child result, including a negative
+task result, never switches models. Completion metadata reports the requested
+candidate, every attempted candidate, the model actually used, and each raw
+model failure in attempt order when fallbacks are tried. Workflow metadata accepts one exact
+model only, to keep approved workflow runtimes deterministic.
+
+A catalog-listed model and configured authentication do not prove that the
+active provider account can use that model. Providers may reject an account /
+model combination only when the request is made. The completion preserves each
+raw provider reason with its model and suggests checking account access,
+spawning a new subagent with a supported model, or choosing an appropriate
+configured fallback. `subagent_resume` does not select a model and should be
+used only after the session's stored model is usable. The completion does not
+claim a permanent failure or a retry count that Pi has not exposed. Reliable
+structured permanence and retry counts require an upstream Pi/ExtensionAPI
+diagnostics seam for final provider errors and retry outcomes.
 
 `config.json` is gitignored in the source tree so local overrides are not
 committed from a checkout. On an installed package root, treat it as disposable
@@ -478,6 +491,8 @@ Parameters:
 - If process identity cannot be captured for an active pane, the pane remains present after close, or any captured process still lives after the bounded wait, the checkout is retained and the run ends `failed` with `cancel_termination_failed`. Successful cancellation is not reported in that case.
 - A successful cancel writes one `cancelled` terminal journal event and one result-free delivery. Repeated cancel is idempotent and returns the authoritative terminal outcome (including a prior fail-closed result).
 
+Every terminal path—normal completion, early script return, script or Worker failure, deadline, interruption, and explicit cancellation—stops queued work and accounts for active workflow children before checkout disposal or final delivery. If active-child exit cannot be confirmed, the checkout is retained and the authoritative outcome is `failed` with `cancel_termination_failed`.
+
 There is no list, status, resume, or history action in v1. Workflow ownership and the Worker survive `/reload` in the same Pi process, and the latest parent API receives one final delivery. A full process restart reconciles interruption without replay: startup marks only the last known running journal event as `interrupted`, leaves sessions, journals, and reader checkouts in place, and requires a new approved run.
 
 ### Bundled `orchestrate` skill
@@ -490,7 +505,7 @@ The script and journal retain every original child envelope. Synthesis receives
 
 The runner-owned checkout contains only the pinned commit. Parent staged, unstaged, and untracked state is not review evidence. Effective child tools are the resolved role allowlist intersected with the runner maximum (`read`, `grep`, `find`, and `ls`) and deny rules. Public `subagent` results can be abbreviated above 16,000 characters, but workflow scripts receive complete child reports within their explicit bounds. Operational failures are preserved without silent fallback; recovery is a new exact approved run.
 
-The parent calls `herdr_workflow prepare`, presents its packet unchanged, and waits for the exact `APPROVE <8-character lowercase hash prefix>` reply before calling `start`. After start, one final delivery is sent without polling. Cancellation is fail-closed and retains evidence when process exit cannot be confirmed. Same-process `/reload` preserves ownership; full restart records interruption without replay, restart, cleanup, or history. Workflow JavaScript runs in a Worker-hosted `vm` for event-loop availability only; neither the Worker nor `vm` is a security boundary, and worktrees do not provide process or security isolation.
+The parent calls `herdr_workflow prepare`, presents its packet unchanged, and waits for the exact `APPROVE <8-character lowercase hash prefix>` reply before calling `start`. After start, one final delivery is sent without polling. Every terminal path is fail-closed: it accounts for queued and active children before checkout disposal and delivery, retaining evidence when process exit cannot be confirmed. Same-process `/reload` preserves ownership; full restart records interruption without replay, restart, cleanup, or history. Workflow JavaScript runs in a Worker-hosted `vm` for event-loop availability only; neither the Worker nor `vm` is a security boundary, and worktrees do not provide process or security isolation.
 
 ---
 
@@ -509,6 +524,8 @@ The `caller_ping` tool lets a Pi-backed subagent request help from its parent ag
 - `message` (optional): Follow-up prompt to send after resuming
 - `autoExit` (optional): Whether the resumed session should auto-exit after its next response fully settles. Defaults to `true` for autonomous follow-up work; set `false` when resuming for an interactive handoff.
 
+Each public child stores a session-adjacent versioned launch-policy sidecar. Public resume restores its resolved tool allowlist and denied subagent tools rather than looking up the current role, so later role changes cannot widen a child. An intentionally unrestricted launch remains unrestricted (no `--tools` argument); a restricted launch restores its exact allowlist. The `autoExit` override still controls whether `subagent_done` is available, while `caller_ping` remains available. Missing, malformed, or unsupported policy fails closed before a pane is created with recovery guidance. Public resume also rejects workflow-owned and managed-worktree child sessions; use their retained workflow evidence or workspace instead.
+
 **Interaction flow:**
 
 1. Child calls `caller_ping({ message: "Not sure which schema to use" })`
@@ -632,8 +649,11 @@ specific exact authenticated `provider/model-id`.
 
 `tools` is passed to Pi's `--tools` allowlist and may name any registered
 built-in, extension, or custom tool. Listing a tool does not install its
-extension. Likewise, `skills` names must already be discoverable by Pi; this
-package does not install role prerequisites.
+extension. Use one non-empty inline comma-separated scalar, such as
+`tools: read, grep`; do not use YAML lists, containers, quotes, or comments.
+Omitting `tools` intentionally leaves the role unrestricted. Likewise, `skills`
+names must already be discoverable by Pi; this package does not install role
+prerequisites.
 
 ### 3. Verify and launch
 
@@ -736,9 +756,17 @@ collision rules, and rejected alternatives.
 - Generic roles omit `model` unless a particular runtime is functionally required.
 - `/subagent list` shows the expected source and a smoke launch succeeds.
 
-The current parser is permissive: unsupported or unknown frontmatter may be
-ignored rather than rejected. Compare definitions against the reference below
-and verify them with `/subagent list` plus a smoke launch.
+Capability declarations are strict: use the unquoted, unindented keys
+`tools:`, `deny-tools:`, and `spawning:` exactly once when present. Declare
+`tools` and `deny-tools` as non-empty inline comma-separated scalars, and
+`spawning` as exactly `true` or `false`. YAML lists, containers, multiline
+values, quotes, comments, empty values, duplicates, noncanonical key spelling,
+and invalid booleans are rejected. A role with an invalid capability declaration
+is excluded from discovery, and an exact-name launch reports the diagnostic
+before creating a Herdr pane or worktree. Other unsupported or unknown
+frontmatter may still be ignored.
+Compare definitions against the reference below and verify them with
+`/subagent list` plus a smoke launch.
 
 ### Frontmatter Reference
 
@@ -749,11 +777,11 @@ and verify them with `/subagent list` plus a smoke launch.
 | `model`       | string  | Optional exact authenticated Pi model default or ordered comma-separated fallback list; omit to use per-agent config, global config, then the parent                                                                                                                       |
 | `thinking`    | string  | Optional Pi thinking default (`off` through `max`); omit to inherit the parent                                                                                                                                   |
 | `system-prompt` | string | `append` passes the agent body through Pi's appended system prompt; `replace` replaces Pi's default system prompt. Without this field, the body is included in the task wrapper                                                                                                                                                                                                                                 |
-| `tools`       | string  | Comma-separated Pi `--tools` allowlist; may contain any registered built-in, extension, or custom tool name                                                                                                                                                                 |
+| `tools`       | string  | One non-empty inline comma-separated Pi `--tools` allowlist under the exact unquoted key `tools:`; may contain any registered built-in, extension, or custom tool name. Omit to leave unrestricted. YAML lists, containers, multiline values, quotes, comments, noncanonical keys, and duplicates are rejected. |
 | `skills`      | string  | Comma-separated installed skill names to auto-load. Use this plural form for new definitions; legacy project/global definitions using singular `skill` remain compatible. |
 | `session-mode` | string | Default child-session mode: `standalone`, `lineage-only`, or `fork` |
-| `spawning`    | boolean | Set `false` to deny all subagent-spawning tools                                                                                                                                                                                                                             |
-| `deny-tools`  | string  | Comma-separated `pi-herdr-agents` tool names to suppress; this is not a universal cross-extension deny list                                                                                                                                                                  |
+| `spawning`    | boolean | Set exactly `false` to deny all subagent-spawning tools under the exact unquoted key `spawning:`. Only one `true` or `false` declaration is accepted. |
+| `deny-tools`  | string  | One non-empty inline comma-separated `pi-herdr-agents` tool list to suppress under the exact unquoted key `deny-tools:`; this is not a universal cross-extension deny list. YAML lists, containers, multiline values, quotes, comments, noncanonical keys, and duplicates are rejected. |
 | `auto-exit`   | boolean | Auto-shutdown after Pi fully settles when the latest assistant turn does not end with `stopReason: "aborted"` — no `subagent_done` call needed. User input does not permanently disable auto-exit. Recommended for autonomous agents (scout, worker); not for interactive ones (planner). Also determines the default value of `interactive` (see below). |
 | `interactive` | boolean | Override whether stall/recovery transitions wake the parent session. Defaults to the inverse of `auto-exit`: autonomous agents (`auto-exit: true`) are non-interactive and get stall pings; agents without `auto-exit` are interactive and stay quiet. Explicit values take precedence. |
 | `cwd`         | string  | Default working directory. Absolute paths are unambiguous; relative agent-frontmatter paths resolve from Pi's agent config directory (`PI_CODING_AGENT_DIR` or `~/.pi/agent`), not the project root                                                                                                                                                                                                            |

package/docs/adr/0003-installable-role-packs.md

@@ -29,7 +29,14 @@ roles are listed or launched.
 
 Role packs use the existing agent-definition format. The filename stem is the
 canonical role name; `name` frontmatter is optional and, when present, must
-match the stem. `description` is required for contributed roles.
+match the stem. `description` is required for contributed roles. Capability
+declarations are strict: use the unquoted, unindented keys `tools:`,
+`deny-tools:`, and `spawning:` exactly once when present. `tools` and
+`deny-tools` must each be one non-empty inline comma-separated scalar, and
+`spawning` must be exactly `true` or `false`. YAML lists, containers,
+multiline or empty values, quotes, comments, noncanonical key spelling, and
+duplicate declarations are invalid; omit `tools` to intentionally leave a role
+unrestricted.
 
 ## Why
 
@@ -80,7 +87,10 @@ Within the package layer:
 
 Invalid registrations do not suppress unrelated roles. Listing surfaces report
 concise diagnostics, and an exact-name launch reports the matching diagnostic
-instead of treating an invalid contribution as a bare agent.
+instead of treating an invalid contribution as a bare agent. An invalid
+capability declaration makes that role name unavailable at its precedence layer
+rather than falling through to a lower-priority role, and launch rejects it
+before Herdr creates a pane or worktree.
 
 ## Reload and security
 

package/docs/orchestrated-review-workflow-plan.md

@@ -19,7 +19,7 @@ Shipped:
 - bounded parallel review, fresh synthesis, and explicit non-retryable failure evidence for parent-guided recovery;
 - a preferred adversarial procedure in the existing authoring skill, with risk-based discovery and candidate-dependent verification;
 - one final parent delivery; and
-- fail-closed cancellation with process-exit confirmation before checkout cleanup.
+- fail-closed terminal cleanup with process-exit confirmation for every outcome before checkout disposal.
 
 Package and runtime slices are shipped. Remaining work is limited to deferred writer behavior and any future workflow extensions.
 
@@ -146,7 +146,7 @@ The LLM cannot authorize execution by passing approval text in tool arguments. `
 7. dispose the reader checkout only after termination is confirmed;
 8. append one `cancelled` terminal event and deliver one bounded cancellation receipt.
 
-If a captured process remains after the bounded wait, retain the checkout and append `failed` with `cancel_termination_failed`; never report successful cancellation or clean up underneath a live child. All completion, failure, interruption, and cancellation paths use the same compare-and-set terminal gate. Repeated cancellation is idempotent.
+If a captured process remains after the bounded wait, retain the checkout and append `failed` with `cancel_termination_failed`; never report successful cancellation or clean up underneath a live child. All completion, early return, failure, interruption, deadline, and cancellation paths use the same compare-and-set terminal gate and terminate queued or active children before checkout disposal and delivery. Repeated cancellation is idempotent.
 
 ## Workflow metadata
 

package/docs/worktree-subagents.md

@@ -190,11 +190,11 @@ The extension never pushes, creates a PR, merges, cherry-picks, or changes the p
 - **Creation failure:** the manifest is marked failed. If Herdr created the branch but returned an incomplete response, the extension reconciles a unique branch match through `/worktree list` and records any recovered workspace/path.
 - **Launch failure after creation:** the manifest is marked failed and the workspace, forked session, and path are retained. The destination is not focused unless Pi startup is confirmed.
 - **Worker failure:** summary and available Git state are returned; the workspace remains open. Auto-exit waits until Pi is fully settled, so a transient provider error followed by automatic compaction or retry does not end the worker early.
-- **`caller_ping`:** the child exits with `needs_help`; continue worktree-bound follow-up in the retained workspace rather than through `subagent_resume`.
+- **`caller_ping`:** the child exits with `needs_help`; continue worktree-bound follow-up in the retained workspace rather than through `subagent_resume`. Public `subagent_resume` rejects managed-worktree child sessions before creating a pane so it cannot silently lose worktree ownership or policy.
 - **Parent `/reload`, `/new`, `/resume`, or `/fork`:** active in-memory watchers transfer to the replacement parent session.
 - **Full process restart or crash:** the worktree remains, but v1 does not automatically rediscover and resume its watcher.
 
-`subagent_resume` resumes a session in a new ordinary Herdr pane. It does not reattach the managed worktree lifecycle or produce a new worktree handoff. For worktree follow-up, focus the retained workspace and resume manually from its shell:
+`subagent_resume` rejects managed-worktree sessions. It does not reattach the managed worktree lifecycle or produce a new worktree handoff. For worktree follow-up, focus the retained workspace and resume manually from its shell:
 
 ```bash
 herdr workspace focus <workspace-id>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Asynchronous Pi subagents and approved review workflows in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",

package/pi-extension/subagents/completion.ts

@@ -86,7 +86,7 @@ function completionArtifact(
 	return consumeExitSidecar(options.sessionFile);
 }
 
-async function waitForDisappearanceArtifacts(
+async function waitForDelayedSidecar(
 	signal: AbortSignal,
 	options: CompletionOptions,
 ): Promise<CompletionResult | null> {
@@ -137,7 +137,15 @@ export async function waitForCompletion(
 
 		try {
 			const exitCode = terminalExitCode(await options.readTerminalTail());
-			if (exitCode !== null) return { reason: "sentinel", exitCode };
+			if (exitCode !== null) {
+				// The shell sentinel can become readable just before the child writes
+				// its authoritative error sidecar. Preserve that error metadata.
+				if (exitCode !== 0) {
+					const racedCompletion = await waitForDelayedSidecar(signal, options);
+					if (racedCompletion) return racedCompletion;
+				}
+				return { reason: "sentinel", exitCode };
+			}
 		} catch {
 			// Terminal reads are only sentinel/output probes; Herdr status is polled
 			// independently below, even when terminal reads succeed.
@@ -155,10 +163,7 @@ export async function waitForCompletion(
 			if (inspection.kind === "missing") {
 				// Pane closure and atomic artifact publication are separate operations.
 				// Allow a short bounded grace window before declaring evidence lost.
-				const racedCompletion = await waitForDisappearanceArtifacts(
-					signal,
-					options,
-				);
+				const racedCompletion = await waitForDelayedSidecar(signal, options);
 				if (racedCompletion) return racedCompletion;
 				return {
 					reason: "error",