@maxiaochao/pi-toolkit 0.11.4 → 0.11.5

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2026-10-13 - v0.11.5
+
+- bundle herdr-subagents v0.4.14: allow explicit extension sources with native Pi package semantics and reliable cleanup checks
+
 ## 2026-10-12 - v0.11.4
 
 - bundle herdr-subagents v0.4.13: fix stale-idle child startup race and require real Herdr E2E release smoke
@@ -8,6 +12,8 @@
 
 ## Unreleased
 
+- Add opt-in Herdr Subagents persona extension sources, including npm/git Pi packages, with saved restart configuration and documented native package-resource semantics.
+- Harden Herdr Subagents cleanup checks with condition-based waits, lock/focus regressions, and retained failure diagnostics; keep production cleanup behavior unchanged.
 - Fix Herdr Subagents startup failures caused by stale idle observations and require real child-Agent smoke tests before releasing that package.
 
 - Replace split child/root publishing with one idempotent root-tag workflow, make final-version local checks authoritative, keep CI publication-only, and remove timing-sensitive Herdr lifecycle assertions.

package/README.md

@@ -39,6 +39,8 @@ Restart Pi after updating. The `todo` tool and widget will no longer load. `pi u
 
 Each child README owns its feature description, motivation or upstream alignment, examples, screenshots/demos, configuration, and test documentation.
 
+Herdr Subagents personas can opt into local extension files or npm/git Pi packages through `extensions`. This uses native Pi package semantics: package-provided skills, prompt templates, and themes may also load, and `--no-skills` does not exclude explicitly selected package skills. See the [extension-source contract](packages/herdr-subagents/README.md#explicit-extension-sources-and-pi-packages) for precedence, isolation, and examples.
+
 Multiple standalone children may be installed together. `pi-todo` may also be installed alongside the complete toolkit because Todo is no longer bundled. Do not install another bundled child alongside the complete toolkit because that exposes the same resource twice.
 
 To keep Todo after updating the toolkit:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.11.4",
+  "version": "0.11.5",
   "description": "Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [

package/packages/herdr-subagents/ARCHITECTURE.md

@@ -275,7 +275,7 @@ Merging them into one physical file would either put long prompts into JSON or r
 
 ### Sources of confusion to remove
 
-1. Persona Markdown and JSON both expose `model`, `thinking`, and `skills`; this is intentional override layering but must be described as one resolution pipeline.
+1. Persona Markdown and JSON both expose `model`, `thinking`, `skills`, and `extensions`; this is intentional override layering but must be described as one resolution pipeline.
 2. Call-level task model overrides are resolved later in `tool.ts`, after configuration loading.
 3. TypeBox validates shape while `validation.ts` validates action-dependent requirements; these are complementary but currently look like duplicated validation.
 4. Downstream modules receive partially resolved values instead of one canonical run plan.
@@ -313,6 +313,7 @@ interface ResolvedRunPlan {
     thinking?: string;
     tools?: string[];
     skills: string[];
+    extensions: string[];
     systemPrompt: string;
   }>;
   provenance: Record<string, string>;

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2026-10-13 - v0.4.14
+
+- allow explicit extension sources with native Pi package semantics and reliable cleanup checks
+- Add persona `extensions` in Markdown and JSON with project → global → effective Markdown precedence, replacement arrays, and explicit clearing.
+- Pass local files/directories and native npm/git/built-in sources to child Pi while retaining `--no-extensions` and mandatory child extensions.
+- Persist sources for historical, failed/blocked, and queued-task restarts; expose effective sources in persona listing.
+- Document that explicit Pi packages can load skills, prompts, and themes, including package skills despite `--no-skills`, without automatically broadening explicit tool allowlists.
+- Add deterministic source/precedence/restart tests, a real Pi file/package loading check, and package-source coverage in the real concurrent Herdr smoke.
+- Replace deferred-cleanup test sleeps with bounded condition waits; add a controlled lock-contention regression. Make real Herdr smoke respect deferred cleanup, optionally test focus/restore, and preserve failure traces and live tab/pane snapshots instead of deleting the evidence.
+
 ## 2026-10-12 - v0.4.13
 
 - fix stale-idle child startup race and require real Herdr E2E release smoke

package/packages/herdr-subagents/README.md

@@ -160,7 +160,7 @@ These are all supported top-level fields in `herdr-subagents.json`:
 | `defaultThinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` | Unset | Thinking level below persona-specific settings. Provider/model support can vary. If unset, parent thinking is inherited only when the parent model is also inherited. |
 | `personas` | Object keyed by an existing persona name | `{}` | Per-persona JSON overrides described below. This does not create a persona; a matching Markdown definition must exist. |
 
-Known fields with an invalid JSON type, an empty required string, or a non-positive integer are ignored with a diagnostic shown by `/herdr-subagents settings`. Model IDs, thinking-level compatibility, and skill availability are ultimately validated by Pi when the child starts. When `defaultConcurrency` exceeds `maxConcurrency`, the effective default is reduced to the maximum.
+Known fields with an invalid JSON type, an empty required string, or a non-positive integer are ignored with a diagnostic shown by `/herdr-subagents settings`. Model IDs, thinking-level compatibility, and skill/extension source availability are ultimately handled by Pi when the child starts. When `defaultConcurrency` exceeds `maxConcurrency`, the effective default is reduced to the maximum.
 
 Each `personas.<name>` object supports exactly these overrides:
 
@@ -168,7 +168,8 @@ Each `personas.<name>` object supports exactly these overrides:
 | --- | --- | --- |
 | `model` | Non-empty Pi model string | Overrides the model from the effective persona Markdown and `defaultModel`. |
 | `thinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` | Overrides persona Markdown and `defaultThinking`. The value is passed to Pi's `--thinking` option. |
-| `skills` | Array of non-empty strings | Replaces the entire lower-precedence skill list. Use `[]` to clear inherited skills. Each item is passed to child Pi as `--skill`. |
+| `skills` | Array of non-empty strings | Replaces the entire lower-precedence explicit skill list. Use `[]` to clear that list. Each item is passed to child Pi as `--skill`. Package-provided skills are separate; see below. |
+| `extensions` | Array of non-empty Pi source strings | Replaces the entire lower-precedence extension-source list. Use `[]` to clear it. Each item is passed as `--extension` after the mandatory child extensions. Accepts local files/directories, `npm:` and `git:` Pi packages, and `builtin:` sources. |
 
 JSON persona overrides cannot change `name`, `description`, `access`, `tools`, or the system prompt; define those in persona Markdown.
 
@@ -281,7 +282,49 @@ The child thinking level is selected in this order:
 4. effective `defaultThinking` JSON setting (project overrides global)
 5. parent Pi thinking level when the child also inherits the parent model
 
-Thinking has no call-level override. `skills` uses the first three persona-level steps and has no global default; a project `skills` array replaces, rather than appends to, the global or Markdown list.
+Thinking has no call-level override. `skills` and `extensions` use the first three persona-level steps and have no global default. A project array replaces, rather than appends to, the global or effective Markdown list; `[]` explicitly clears it. There is no task-level extension override.
+
+### Explicit extension sources and Pi packages
+
+For a local routing hook, add this frontmatter to a persona Markdown file (the hook must already exist):
+
+```md
+---
+name: routed-explorer
+description: Explorer with a provider routing hook
+access: read
+tools: read, bash, grep, find, ls, codemode
+extensions: ~/.pi/agent/extensions/gateway-routing.ts
+---
+Inspect the requested code and report your findings.
+```
+
+Frontmatter accepts a single source or a comma-separated inline list, optionally enclosed in brackets. Use `extensions: []` to clear the list. Like the existing persona format, it does not support multiline YAML lists.
+
+JSON accepts an array only. For example, override the built-in explorer with a local hook and an npm Pi package:
+
+```json
+{
+  "personas": {
+    "explorer": {
+      "extensions": [
+        "~/.pi/agent/extensions/gateway-routing.ts",
+        "npm:@example/pi-tools@1.0.0"
+      ]
+    }
+  }
+}
+```
+
+`@example/pi-tools` is illustrative; replace it with a trusted Pi package. An ordinary npm library is not automatically a Pi extension package. Pin npm versions or git refs when reproducible restarts matter. Relative local paths resolve from the child working directory (the project root), **not** from the JSON or Markdown file. `~` resolves to the user's home directory. Source strings are passed to Pi without rewriting `npm:`, `git:`, or `builtin:` identifiers.
+
+**This field uses Pi's native package-loading semantics. It is not an extensions-only resource filter.** A file loads that extension. A Pi package can also load its declared **skills, prompt templates, and themes**. In particular, explicitly selected package skills still load despite the child's `--no-skills`; persona `skills: []` clears only the explicit skill list, not skills carried by an extension package. To select one extension without the package's other resources, use its local extension-file path or a dedicated package that exposes only the intended resources. The string list does not support Pi's settings object-form resource filters.
+
+Children still start with `--no-extensions`, then explicitly load `builtin:codemode`, the bundled `subagent-report`, and the configured sources in order. Unconfigured personas retain their existing behavior. The list does not inherit the parent's extensions, installed-package settings, or package resource filters. Pi manages source resolution, caching, dependency installation, and startup diagnostics; an npm/git source may require network access. Herdr Subagents does not implement a separate installer or guarantee that Pi's extension warnings terminate a task. Inspect the child's startup diagnostics when a required routing hook does not run.
+
+Effective sources are saved in each task record and shown by persona listing. Historical resume, failed/blocked-task restarts, and queued-task recovery reuse the saved list instead of re-reading current persona overrides. A live child is not reloaded when configuration changes. Saving a source does not freeze its code: local files and unpinned package versions can change.
+
+Load only trusted extension code. `access: read` controls scheduling; it is not a sandbox for extension hooks, which can perform side effects outside model tools. `PI_HERDR_SUBAGENTS_CHILD` prevents **this package** from registering recursively, not arbitrary third-party extensions. Loading a package does not broaden an explicit `tools` allowlist. Persona `tools` still accepts only the existing built-in names; adding extension-defined tools to that schema is a separate feature.
 
 Override the model for one task:
 
@@ -313,7 +356,7 @@ Queued background submissions are persisted before dispatch. Closing the parent
 
 Tab, pane, and child startup commands are not automatically retried: an error may arrive after Herdr already created the resource. Recovery is best effort, not complete: Herdr 0.9.2 has no idempotency key for tab creation or pane splitting, so a `SIGKILL` after the external resource is created but before its ID is durably persisted can leave an orphan that cannot be identified for cleanup. A failure after prompt submission is preserved and never automatically rerun. Historical follow-ups use a recoverable task-scoped `.resume.lock`, so different tasks can continue concurrently without allowing two writers for one saved session. Herdr exposes no retrying state, and Pi exposes no reliable public auto-retry hook, so `retrying` is supported by the runtime schema and Fleet but is not fabricated from ambiguous lifecycle events. `stalledWarningSeconds` emits a warning without killing long-running work. Run/task/report snapshots use atomic replacement so interruption cannot expose half-written JSON.
 
-The child does not inherit parent extensions, parent conversation, or unconfigured skills, but normal project context files still apply. It uses the same Pi installation, provider configuration, model catalog, and credentials as the parent.
+The child does not inherit parent extensions or parent conversation. Skills load from explicit persona paths and from explicitly selected Pi packages; normal project context files still apply. It uses the same Pi installation, provider configuration, model catalog, and credentials as the parent.
 
 ## Development and tests
 

package/packages/herdr-subagents/TESTING.md

@@ -2,9 +2,11 @@
 
 ## Flow
 
-1. `npm --prefix packages/herdr-subagents test` runs deterministic scheduler, recovery, and persona tests.
-2. `pi -ne -ns --no-session -e ./packages/herdr-subagents/extensions/herdr-subagents.ts` verifies extension loading.
-3. From a Pi session inside Herdr, run `npm --prefix packages/herdr-subagents run test:real-herdr`. This is a mandatory child-package and root-bundle release gate. It starts one real child Pi and then two concurrent read-only child Pi Agents, requires assistant events and matching attempt-scoped reports, and verifies final tab cleanup. `HERDR_SUBAGENTS_E2E_MODEL=provider/model` optionally pins the smoke model. Failed cleanup preserves the temporary durable records and fails the gate.
+1. `npm --prefix packages/herdr-subagents test` runs deterministic scheduler, recovery, and persona tests, then a controlled run-state-lock regression for deferred cleanup. The regression proves that the old 10 ms assertion can observe unfinished cleanup while both successful cleanup and error persistence eventually settle after lock release; it also checks that the condition waiter fails on timeout.
+2. `PI_TEST_BINARY="$(command -v pi)" npm --prefix packages/herdr-subagents run load-test` verifies extension contracts and loading, then starts real Pi with generated child arguments against temporary file/package fixtures. The package fixture must expose its skill and prompt despite discovery flags, while the explicit tool allowlist remains unchanged. This check makes no provider calls or network installs. `PI_TEST_BINARY` pins the tested CLI so npm cannot substitute an older workspace-local Pi binary; use a Pi version supporting native `builtin:codemode` and package sources.
+3. From a Pi session inside Herdr, run `npm --prefix packages/herdr-subagents run test:real-herdr`. This is a mandatory child-package and root-bundle release gate. It starts one unconfigured real child Pi and then two concurrent read-only child Pi Agents with an explicit local Pi package. It requires assistant events, matching attempt-scoped reports, saved extension sources, a package-extension startup marker, package skill availability despite `--no-skills`, and final tab cleanup. `HERDR_SUBAGENTS_E2E_MODEL=provider/model` optionally pins the smoke model. The check waits up to five seconds for pane removal and the durable cleanup commit; a recorded `cleanupError` fails immediately instead of being retried away. A failed assertion or runtime check preserves the temporary durable records, `trace.json`, and `failure.json` with tab/pane snapshots. Teardown errors are retained separately and fail the gate; already-missing tabs are successful cleanup.
+
+   For an intentional focus regression, run `HERDR_SUBAGENTS_E2E_FOCUS_CLEANUP=1 HERDR_SUBAGENTS_E2E_MODEL=provider/model npm --prefix packages/herdr-subagents run test:real-herdr`. It briefly focuses only the concurrent test's tab at cleanup, requires `cleanupPendingTabIds`, restores the globally focused workspace and its active tab, asserts that focus is still restored after cleanup, then verifies automatic cleanup without manually closing the test tab. Run this only when brief visible focus changes are acceptable; it requires an existing focused tab to restore.
 4. From a dedicated visible X11 Herdr client/window with the GStreamer X11 and VP8 plugins installed, run `HERDR_MEDIA_WINDOW_ID=<window-id> node scripts/capture-package-media.mjs`. Capture intentionally cycles through the live child panes, so avoid using that client/window for other work while recording; the script restores the previously focused pane afterward when it still exists. The Herdr capture must show a parent Pi conversation, a three-task run tab, each of the three real interactive Agent panes receiving focus in turn, the active parent Fleet footer with yellow running indicators and real metrics, and the final compact parent response. The published screenshot must be the parent Fleet view, while the full WebM preserves the parent → three focused children → Fleet → parent sequence.
 5. `npm pack ./packages/herdr-subagents --dry-run` verifies package contents.
 6. Verify the README renders the GitHub attachment video directly and live Herdr UI media `docs/screenshot.png` and `docs/demo.webm` are present in the tarball; `docs/demo.gif` must be absent. Inspect the WebM metadata and play it through once to confirm the parent → three focused children → Fleet → parent sequence.
@@ -12,6 +14,7 @@
 ## Cases
 
 - Resolve package, global, and project personas and validate frontmatter/configuration, including the neutral read-only `analyst` persona.
+- Verify extension-source Markdown parsing, JSON type diagnostics, precedence, trimming, replacement/empty lists, unchanged unconfigured startup, local/npm source argument preservation, persona listing, durable history, historical resume, blocked-task restart, and queued-task recovery.
 - Run foreground tasks and FIFO bounded-concurrency batches through an injectable Herdr boundary.
 - Simulate one fast failure beside a controlled slow success and verify the foreground call returns the stable run ID and failure before releasing the slow task, detaches caller cancellation without aborting that task, releases the dispatcher so the next batch starts before the slow task settles, removes durable queue state, and emits exactly one final follow-up.
 - Verify a detached dispatcher promise can settle normally after its successor starts without clearing or otherwise disturbing the successor's active slot, while blocked foreground runs retain their existing dispatcher ownership.
@@ -37,6 +40,7 @@
 - Simulate a false screen-settled return while the authoritative Pi lifecycle remains working, then write the report later and verify the task completes without a transient failed state.
 - Verify reports are bound to unique attempt IDs, blocked results are not tool errors, duplicate blocked responses are serialized, mixed failed/cancelled aggregates remain partial, and cleanup failures never overwrite business outcomes.
 - Verify settling a batch merges run state written concurrently under the run lock instead of overwriting `run.json` from a stale in-memory copy.
+- Wait for deferred cleanup commits/notifications rather than fixed sleeps. Hold the real run-state lock across the old assertion point to reproduce both successful-cleanup and error-persistence races, then require the expected durable state after release. Real smoke failures retain evidence before teardown.
 - Verify an explicitly named failed task continues from its saved Pi session: it reuses its own live pane while its batch still runs, restarts in a new pane when that pane is gone, refuses to continue without a saved session, is never selected by an unqualified response, and does not start queued siblings that the running batch still owns.
 - Verify a settling batch adopts the task records on disk, so a continued task keeps its run `running` and its Herdr tab open instead of being overwritten by the batch's own stale view.
 - Verify a continuation claims its task before touching any pane, so a sibling continuation that finishes first leaves the shared tab open, and only the last one to settle closes it.
@@ -46,4 +50,4 @@
 
 ## Latest baseline
 
-All 246 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, lifecycle, attempt-isolation, and persona cases plus the extension-contract lifecycle simulations must pass. The startup regression test reproduces the real ordering where `before_agent_start` records the attempt as working while Herdr can still report stale idle. Every release also runs the real single-Agent and concurrent read-only Herdr smoke; a skipped smoke is not a passing release check.
+All 266 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, lifecycle, attempt-isolation, and persona cases, the controlled cleanup-timing regression, and the extension-contract lifecycle simulations must pass. The startup regression test reproduces the real ordering where `before_agent_start` records the attempt as working while Herdr can still report stale idle. Every release also runs the real single-Agent and concurrent read-only Herdr smoke; a skipped smoke is not a passing release check.

package/packages/herdr-subagents/extensions/herdr-subagents.ts

@@ -88,7 +88,7 @@ async function handleHerdrCommand(args: string, ctx: ExtensionCommandContext, fl
 	}
 	const configuration = loadSubagentConfiguration(ctx.cwd, packageAgentsDir, ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined);
 	if (section === "agents") {
-		ctx.ui.notify(configuration.personas.map((persona) => `${persona.name}: ${persona.source}, ${persona.access}, model=${persona.model ?? "unresolved"} (${persona.modelSource}), thinking=${persona.thinking ?? "default"}, tools=${persona.tools?.join(",") ?? "default"}, skills=${persona.skills.join(",") || "none"}`).join("\n"), "info");
+		ctx.ui.notify(configuration.personas.map((persona) => `${persona.name}: ${persona.source}, ${persona.access}, model=${persona.model ?? "unresolved"} (${persona.modelSource}), thinking=${persona.thinking ?? "default"}, tools=${persona.tools?.join(",") ?? "default"}, skills=${persona.skills.join(",") || "none"}, extensions=${persona.extensions.join(",") || "none"} (${persona.extensionsSource})`).join("\n"), "info");
 		return;
 	}
 	if (section === "settings") {

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.4.13",
+  "version": "0.4.14",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [
@@ -37,9 +37,9 @@
     "typebox": "*"
   },
   "scripts": {
-    "test": "node --experimental-strip-types tests/run-tests.mjs",
+    "test": "node --experimental-strip-types tests/run-tests.mjs && node --experimental-strip-types tests/cleanup-timing.mjs",
     "test:real-herdr": "node --experimental-strip-types tests/real-herdr-smoke.mjs",
-    "load-test": "env -u PI_HERDR_SUBAGENTS_CHILD pi -ne -ns --no-session -e ./tests/extension-contract.ts && env -u PI_HERDR_SUBAGENTS_CHILD pi -ne -ns --no-session -e ./extensions/herdr-subagents.ts"
+    "load-test": "env -u PI_HERDR_SUBAGENTS_CHILD \"${PI_TEST_BINARY:-pi}\" -ne -ns --no-session -e ./tests/extension-contract.ts && env -u PI_HERDR_SUBAGENTS_CHILD \"${PI_TEST_BINARY:-pi}\" -ne -ns --no-session -e ./extensions/herdr-subagents.ts && node --experimental-strip-types tests/extension-sources-load.mjs"
   },
   "publishConfig": {
     "access": "public"

package/packages/herdr-subagents/src/batch-runner.ts

@@ -27,6 +27,7 @@ export interface BatchTask {
 	thinking?: string;
 	tools?: string[];
 	skills: string[];
+	extensions?: string[];
 	systemPrompt: string;
 }
 
@@ -103,7 +104,7 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 		const taskRecord: TaskRecord = {
 			id: taskId, runId, order: index + 1, name: task.name, status: "queued", prompt: task.prompt,
 			agent: task.agent, access: task.access, model: task.model, thinking: task.thinking,
-			tools: task.tools, skills: task.skills, systemPrompt: reportProtocolPrompt(task.systemPrompt), sessionFile,
+			tools: task.tools, skills: task.skills, extensions: task.extensions, systemPrompt: reportProtocolPrompt(task.systemPrompt), sessionFile,
 		};
 		await mkdir(taskDirectory, { recursive: true, mode: 0o700 });
 		await writeFile(systemPromptFile, String(taskRecord.systemPrompt), { encoding: "utf8", mode: 0o600 });

package/packages/herdr-subagents/src/config.ts

@@ -4,7 +4,7 @@ import { dirname, join } from "node:path";
 import { discoverPackageAgents, type AgentDefinition } from "./personas.ts";
 
 export type PersonaAccess = "read" | "write";
-export interface PersonaConfig { model?: string; thinking?: string; skills?: string[]; }
+export interface PersonaConfig { model?: string; thinking?: string; skills?: string[]; extensions?: string[]; }
 export interface SubagentConfig {
 	defaultConcurrency: number;
 	maxConcurrency: number;
@@ -22,6 +22,8 @@ export interface EffectivePersona extends AgentDefinition {
 	thinkingSource: string;
 	skills: string[];
 	skillsSource: string;
+	extensions: string[];
+	extensionsSource: string;
 }
 export interface SubagentConfiguration {
 	settings: SubagentConfig;
@@ -83,9 +85,11 @@ function mergeConfig(base: SubagentConfig, input: ConfigFile, source: string, so
 				if (typeof value === "string" && value.trim()) valid[field] = value.trim();
 				else diagnostics.push(`${source} persona '${name}' ${field} must be a non-empty string`);
 			}
-			if (raw.skills !== undefined) {
-				if (Array.isArray(raw.skills) && raw.skills.every((value) => typeof value === "string" && value.trim())) valid.skills = raw.skills.map((value) => value.trim());
-				else diagnostics.push(`${source} persona '${name}' skills must be an array of non-empty strings`);
+			for (const field of ["skills", "extensions"] as const) {
+				const value = raw[field];
+				if (value === undefined) continue;
+				if (Array.isArray(value) && value.every((item) => typeof item === "string" && item.trim())) valid[field] = value.map((item) => item.trim());
+				else diagnostics.push(`${source} persona '${name}' ${field} must be an array of non-empty strings`);
 			}
 			input.personas[name] = valid;
 			result.personas[name] = { ...(result.personas[name] ?? {}), ...valid };
@@ -123,7 +127,9 @@ export function loadSubagentConfiguration(cwd: string, packageAgentsDirectory: s
 		const thinkingSource = projectPersona.thinking ? "project persona" : globalPersona.thinking ? "global persona" : definition.thinking ? `${source} persona` : settings.defaultThinking ? settingSources.defaultThinking : "default";
 		const skills = projectPersona.skills ?? globalPersona.skills ?? definition.skills ?? [];
 		const skillsSource = projectPersona.skills ? "project persona" : globalPersona.skills ? "global persona" : definition.skills ? `${source} persona` : "none";
-		return { ...definition, source, access: definition.access ?? "write", model, modelSource, thinking, thinkingSource, skills, skillsSource };
+		const extensions = projectPersona.extensions ?? globalPersona.extensions ?? definition.extensions ?? [];
+		const extensionsSource = projectPersona.extensions ? "project persona" : globalPersona.extensions ? "global persona" : definition.extensions ? `${source} persona` : "none";
+		return { ...definition, source, access: definition.access ?? "write", model, modelSource, thinking, thinkingSource, skills, skillsSource, extensions, extensionsSource };
 	}).sort((left, right) => left.name.localeCompare(right.name));
 	return { settings, settingSources, personas, diagnostics };
 }

package/packages/herdr-subagents/src/history.ts

@@ -7,7 +7,7 @@ import { isActiveStatus, readReport, readRunRecord, readTaskRecord, type Persist
 import { findRunDirectory } from "./run-locator.ts";
 import { resumeHistoricalTaskConcurrent } from "./historical-resume.ts";
 
-export interface HistoricalTask { order: number; id: string; name: string; agent: string; status: TaskStatus; summary?: string; question?: string; documents: PersistedDocument[]; recordDirectory: string; sessionFile: string; model?: string; thinking?: string; tools?: string[]; skills: string[]; access?: string; }
+export interface HistoricalTask { order: number; id: string; name: string; agent: string; status: TaskStatus; summary?: string; question?: string; documents: PersistedDocument[]; recordDirectory: string; sessionFile: string; model?: string; thinking?: string; tools?: string[]; skills: string[]; extensions?: string[]; access?: string; }
 export interface HistoricalRun { id: string; label: string; status: RunStatus; startedAt: string; completedAt?: string; effectiveConcurrency?: number; cleanupPendingTabIds?: string[]; tasks: HistoricalTask[]; recordDirectory: string; }
 
 export async function ensureRuntimeIgnored(cwd: string): Promise<void> {
@@ -66,7 +66,7 @@ export async function listSubagentHistory(cwd: string): Promise<HistoricalRun[]>
 					historyStatus = "failed";
 					report = { summary: `Missing structured report: ${reportFile}`, documents: [] };
 				}
-				tasks.push({ order: task.order ?? tasks.length + 1, id: task.id, name: task.name ?? task.agent ?? "worker", agent: task.agent ?? "worker", status: historyStatus, summary: report.summary, question: report.question, documents: report.documents ?? [], recordDirectory: taskDirectory, sessionFile: task.sessionFile, model: task.model, thinking: task.thinking, tools: task.tools, skills: task.skills ?? [], access: task.access });
+				tasks.push({ order: task.order ?? tasks.length + 1, id: task.id, name: task.name ?? task.agent ?? "worker", agent: task.agent ?? "worker", status: historyStatus, summary: report.summary, question: report.question, documents: report.documents ?? [], recordDirectory: taskDirectory, sessionFile: task.sessionFile, model: task.model, thinking: task.thinking, tools: task.tools, skills: task.skills ?? [], extensions: task.extensions ?? [], access: task.access });
 			}
 			history.push({ id: run.id, label: run.label, status: projectedStatus, startedAt: run.startedAt, completedAt: run.completedAt, effectiveConcurrency: run.effectiveConcurrency, cleanupPendingTabIds: run.cleanupPendingTabIds, tasks, recordDirectory: directory });
 		} catch (error) {

package/packages/herdr-subagents/src/live-agent.ts

@@ -16,6 +16,7 @@ export interface LiveTaskRecord {
 	thinking?: string;
 	tools?: string[];
 	skills?: string[];
+	extensions?: string[];
 	currentAttemptId?: string;
 }
 
@@ -41,6 +42,7 @@ export function childPiArgs(task: LiveTaskRecord, systemPromptFile: string): str
 		"--no-skills",
 		"--append-system-prompt", systemPromptFile,
 	];
+	for (const extension of task.extensions ?? []) args.push("--extension", extension);
 	if (task.model) args.push("--model", task.model);
 	if (task.thinking) args.push("--thinking", task.thinking);
 	if (task.tools?.length) args.push("--tools", [...new Set([...task.tools, "codemode", "subagent_report"])].join(","));

package/packages/herdr-subagents/src/personas.ts

@@ -21,6 +21,7 @@ export interface AgentDefinition {
 	access?: "read" | "write";
 	thinking?: string;
 	skills?: string[];
+	extensions?: string[];
 	systemPrompt: string;
 	filePath: string;
 }
@@ -79,6 +80,9 @@ export function parseAgentMarkdown(content: string, filePath = "<memory>"): Agen
 	const access = rawAccess as "read" | "write" | undefined;
 	const thinking = fields.get("thinking")?.trim() || undefined;
 	const skills = fields.has("skills") ? parseList(fields.get("skills") ?? "") : undefined;
+	const rawExtensions = fields.get("extensions");
+	const extensions = rawExtensions?.trim() === "[]" ? [] : rawExtensions === undefined ? undefined : parseList(rawExtensions);
+	if (rawExtensions !== undefined && !extensions) throw new Error("frontmatter extensions must contain non-empty sources or []");
 	return {
 		name,
 		description,
@@ -87,6 +91,7 @@ export function parseAgentMarkdown(content: string, filePath = "<memory>"): Agen
 		...(access ? { access } : {}),
 		...(thinking ? { thinking } : {}),
 		...(skills ? { skills } : {}),
+		...(extensions ? { extensions } : {}),
 		systemPrompt: lines.slice(end + 1).join("\n").trim(),
 		filePath,
 	};

package/packages/herdr-subagents/src/records.ts

@@ -83,6 +83,7 @@ export interface TaskRecord {
 	thinking?: string;
 	tools?: string[];
 	skills?: string[];
+	extensions?: string[];
 	systemPrompt?: string;
 	sessionFile?: string;
 	startedAt?: string;

package/packages/herdr-subagents/src/tool.ts

@@ -73,7 +73,7 @@ export function listText(discovery: SubagentConfiguration): string {
 		const model = agent.model ?? "unresolved";
 		const tools = agent.tools?.join(", ") ?? "Pi default built-in tools";
 		const skills = agent.skills.join(", ") || "none";
-		lines.push(`- ${agent.name}: ${agent.description} (source: ${agent.source}; access: ${agent.access}; model: ${model} [${agent.modelSource}]; thinking: ${agent.thinking ?? "default"}; tools: ${tools}; skills: ${skills})`);
+		lines.push(`- ${agent.name}: ${agent.description} (source: ${agent.source}; access: ${agent.access}; model: ${model} [${agent.modelSource}]; thinking: ${agent.thinking ?? "default"}; tools: ${tools}; skills: ${skills}; extensions: ${agent.extensions.join(", ") || "none"} [${agent.extensionsSource}])`);
 	}
 	if (discovery.diagnostics.length > 0) {
 		lines.push("", "Persona diagnostics:", ...discovery.diagnostics.map((diagnostic) => `- ${diagnostic}`));
@@ -184,7 +184,7 @@ async function executeBatch({ params, signal, onUpdate, ctx, dependencies, disco
 		const personaName = task.agent?.trim() || "worker";
 		const persona = discovery.personas.find((candidate) => candidate.name === personaName);
 		if (!persona) return errorResponse(`Unknown persona '${personaName}'.\n\n${listText(discovery)}`);
-		resolved.push({ name: task.name, prompt: task.prompt, agent: persona.name, access: persona.access, model: task.model?.trim() || persona.model, thinking: persona.thinking ?? (persona.modelSource === "parent session" && !task.model ? ctx.thinkingLevel : undefined), tools: persona.tools, skills: persona.skills, systemPrompt: persona.systemPrompt });
+		resolved.push({ name: task.name, prompt: task.prompt, agent: persona.name, access: persona.access, model: task.model?.trim() || persona.model, thinking: persona.thinking ?? (persona.modelSource === "parent session" && !task.model ? ctx.thinkingLevel : undefined), tools: persona.tools, skills: persona.skills, extensions: persona.extensions, systemPrompt: persona.systemPrompt });
 	}
 	try {
 		const result = await runHerdrSubagentsBatch(resolved, {

package/packages/herdr-subagents/tests/cleanup-timing.mjs

@@ -0,0 +1,61 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupRunTab } from "../src/tab-cleanup.ts";
+import { acquireDirectoryLock } from "../src/run-state.ts";
+import { writeJsonAtomic } from "../src/state.ts";
+import { waitFor } from "./wait-for.mjs";
+
+const root = mkdtempSync(join(tmpdir(), "pi-herdr-cleanup-timing-"));
+try {
+	await assert.rejects(waitFor(() => false, "controlled missing completion", 20), /Timed out.*controlled missing completion/);
+	for (const failClose of [false, true]) {
+		const runFile = join(root, "run.json");
+		const run = { id: "cleanup-timing", label: "cleanup-timing", status: "completed" };
+		await writeJsonAtomic(runFile, run);
+		let leaveFocus;
+		const focus = new Promise((resolve) => { leaveFocus = resolve; });
+		let closeAttempted = false;
+		const herdr = {
+			async isTabFocused() { return true; },
+			async waitForTabUnfocused() { await focus; },
+			async closeTab() {
+				closeAttempted = true;
+				if (failClose) throw new Error("controlled close failure");
+			},
+		};
+		const cleanup = await cleanupRunTab({ herdr, tabId: "test-tab", runFile, runRecord: run });
+		assert.equal(cleanup.deferred, true);
+		const lock = await acquireDirectoryLock(join(root, ".state.lock"), { wait: true });
+		try {
+			leaveFocus();
+			await waitFor(() => closeAttempted, "controlled close attempt");
+			await new Promise((resolve) => setTimeout(resolve, 10));
+			const premature = JSON.parse(readFileSync(runFile, "utf8"));
+			assert.deepEqual(premature.cleanupPendingTabIds, ["test-tab"]);
+			assert.equal(premature.cleanupError, undefined);
+			console.log(`REPRO ${failClose ? "error persistence" : "successful cleanup"}: at the old 10 ms assertion point, the legitimate run-state lock keeps cleanup pending`);
+		} finally {
+			await lock.release();
+		}
+		const settled = await waitFor(() => {
+			const record = JSON.parse(readFileSync(runFile, "utf8"));
+			return (failClose ? record.cleanupError : !record.cleanupPendingTabIds) ? record : false;
+		}, "cleanup state commit");
+		assert.equal(settled.status, "completed");
+		if (failClose) {
+			assert.equal(settled.cleanupError, "controlled close failure");
+			assert.deepEqual(settled.cleanupPendingTabIds, ["test-tab"]);
+		} else {
+			assert.equal(settled.cleanupPendingTabIds, undefined);
+			assert.equal(settled.cleanupError, undefined);
+		}
+		// Wait for the detached chain's lock release before reusing or deleting its record.
+		const joined = await acquireDirectoryLock(join(root, ".state.lock"), { wait: true });
+		await joined.release();
+		console.log(`PASS ${failClose ? "error persistence" : "successful cleanup"} settles after the lock releases`);
+	}
+} finally {
+	rmSync(root, { recursive: true, force: true });
+}

package/packages/herdr-subagents/tests/extension-sources-load.mjs

@@ -0,0 +1,52 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { childPiArgs } from "../src/live-agent.ts";
+
+// Exercise native Pi package semantics without provider calls or network installs.
+const root = mkdtempSync(join(tmpdir(), "pi-herdr-extension-sources-"));
+try {
+	const packageDirectory = join(root, "local package");
+	mkdirSync(join(packageDirectory, "skills", "package-skill"), { recursive: true });
+	mkdirSync(join(packageDirectory, "prompts"), { recursive: true });
+	writeFileSync(join(packageDirectory, "package.json"), JSON.stringify({
+		name: "extension-source-fixture",
+		pi: { extensions: ["extension.ts"], skills: ["skills"], prompts: ["prompts"] },
+	}));
+	writeFileSync(join(packageDirectory, "extension.ts"), `export default function (pi) {
+		pi.registerCommand("package-extension", { description: "Package extension loaded", handler() {} });
+	}`);
+	writeFileSync(join(packageDirectory, "skills", "package-skill", "SKILL.md"), "---\nname: package-skill\ndescription: Package skill loading probe\n---\n# Probe\n");
+	writeFileSync(join(packageDirectory, "prompts", "package-prompt.md"), "Package prompt loading probe.");
+	const fileExtension = join(root, "file extension.ts");
+	writeFileSync(fileExtension, `export default function (pi) {
+		pi.registerCommand("file-extension", { description: "File extension loaded", handler() {} });
+	}`);
+	const probe = join(root, "probe.ts");
+	const resultPath = join(root, "result.json");
+	writeFileSync(probe, `import { writeFileSync } from "node:fs";
+		export default function (pi) {
+			pi.on("session_start", (_event, ctx) => {
+				writeFileSync(${JSON.stringify(resultPath)}, JSON.stringify({
+					commands: pi.getCommands().map((command) => command.name),
+					tools: pi.getActiveTools(),
+				}));
+				ctx.shutdown();
+			});
+		}`);
+	const args = childPiArgs({ id: "probe", sessionFile: join(root, "session.jsonl"), tools: ["read"], extensions: [fileExtension, "./local package", probe] }, join(root, "system.md"));
+	writeFileSync(join(root, "system.md"), "Extension source loading probe.");
+	const env = { ...process.env, PI_CODING_AGENT_DIR: join(root, "agent"), PI_HERDR_SUBAGENTS_CHILD: "1" };
+	for (const key of Object.keys(env)) if (key.startsWith("HERDR_") || key === "PI_HERDR_SUBAGENTS_TASK_DIR" || key === "PI_HERDR_SUBAGENTS_PARENT_PANE_ID") delete env[key];
+	const result = spawnSync(process.env.PI_TEST_BINARY?.trim() || "pi", [...args, "--offline", "--no-mcp"], { cwd: root, env, encoding: "utf8", timeout: 30_000 });
+	assert.equal(result.error, undefined, String(result.error));
+	assert.equal(result.status, 0, result.stderr || result.stdout);
+	const loaded = JSON.parse(readFileSync(resultPath, "utf8"));
+	for (const command of ["file-extension", "package-extension", "skill:package-skill", "package-prompt", "parent"]) assert.ok(loaded.commands.includes(command), `Missing ${command}: ${JSON.stringify(loaded)}`);
+	assert.deepEqual([...loaded.tools].sort(), ["codemode", "read", "subagent_report"]);
+	console.log("PASS real Pi loads explicit file and package sources, including package skills/prompts despite discovery flags, without broadening the tool allowlist");
+} finally {
+	rmSync(root, { recursive: true, force: true });
+}

package/packages/herdr-subagents/tests/real-herdr-smoke.mjs

@@ -1,10 +1,12 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { executeHerdrSubagents } from "../src/tool.ts";
 import { CliHerdrAutomation } from "../src/herdr.ts";
+import { waitFor } from "./wait-for.mjs";
 
 if (process.env.HERDR_ENV !== "1" || !process.env.HERDR_WORKSPACE_ID) {
 	throw new Error("The real Herdr smoke test must run from a Pi session inside Herdr.");
@@ -14,6 +16,37 @@ const packageDirectory = dirname(dirname(fileURLToPath(import.meta.url)));
 const root = mkdtempSync(join(tmpdir(), "pi-herdr-subagents-real-"));
 const herdr = new CliHerdrAutomation();
 const tabIds = new Set();
+const paneIds = new Set();
+const trace = [];
+const startedAt = performance.now();
+let failed = false;
+let controlledFocus;
+function record(event) {
+	trace.push({ elapsedMs: Math.round(performance.now() - startedAt), ...event });
+	writeFileSync(join(root, "trace.json"), JSON.stringify(trace, null, 2));
+}
+for (const method of ["createTab", "splitPane", "startAgent", "isTabFocused", "waitForTabUnfocused", "closeTab", "paneExists"]) {
+	const original = herdr[method].bind(herdr);
+	herdr[method] = async (...args) => {
+		if (method === "isTabFocused" && controlledFocus && !controlledFocus.triggered && tabIds.has(args[0])) {
+			const focused = spawnSync(process.env.PI_HERDR_SUBAGENTS_HERDR_BINARY?.trim() || "herdr", ["tab", "focus", args[0]], { encoding: "utf8", timeout: 10_000 });
+			assert.equal(focused.status, 0, focused.stderr);
+			controlledFocus.triggered = true;
+			record({ event: "controlled-focus", tabId: args[0], previousWorkspaceId: controlledFocus.previousWorkspaceId, previousTabId: controlledFocus.previousTabId });
+		}
+		record({ method, phase: "start", args: args.map((arg) => typeof arg === "object" ? { ...arg, signal: undefined } : arg) });
+		try {
+			const result = await original(...args);
+			if (result?.tabId) tabIds.add(result.tabId);
+			if (result?.paneId) paneIds.add(result.paneId);
+			record({ method, phase: "end", result });
+			return result;
+		} catch (error) {
+			record({ method, phase: "error", error: String(error), stderr: error.stderr });
+			throw error;
+		}
+	};
+}
 const model = process.env.HERDR_SUBAGENTS_E2E_MODEL?.trim();
 const configurationPaths = {
 	globalConfig: join(root, "global-config.json"),
@@ -30,7 +63,45 @@ function hasAssistantMessage(path) {
 	});
 }
 
-async function runCase(label, names, concurrency) {
+function restoreTestFocus() {
+	if (!controlledFocus?.triggered || controlledFocus.restored) return;
+	const restored = spawnSync(process.env.PI_HERDR_SUBAGENTS_HERDR_BINARY?.trim() || "herdr", ["tab", "focus", controlledFocus.previousTabId], { encoding: "utf8", timeout: 10_000 });
+	assert.equal(restored.status, 0, restored.stderr);
+	const workspace = spawnSync(process.env.PI_HERDR_SUBAGENTS_HERDR_BINARY?.trim() || "herdr", ["workspace", "focus", controlledFocus.previousWorkspaceId], { encoding: "utf8", timeout: 10_000 });
+	assert.equal(workspace.status, 0, workspace.stderr);
+	controlledFocus.restored = true;
+	assertRestoredFocus();
+	record({ event: "restored-focus", workspaceId: controlledFocus.previousWorkspaceId, tabId: controlledFocus.previousTabId });
+}
+
+function assertRestoredFocus() {
+	const result = spawnSync(process.env.PI_HERDR_SUBAGENTS_HERDR_BINARY?.trim() || "herdr", ["workspace", "list"], { encoding: "utf8", timeout: 10_000 });
+	assert.equal(result.status, 0, result.stderr);
+	const focused = JSON.parse(result.stdout).result.workspaces.find((workspace) => workspace.focused);
+	assert.equal(focused?.workspace_id, controlledFocus.previousWorkspaceId, "The original workspace focus was not restored");
+	assert.equal(focused?.active_tab_id, controlledFocus.previousTabId, "The original tab focus was not restored");
+}
+
+async function waitForCleanup(result) {
+	const signal = AbortSignal.timeout(5_000);
+	await waitFor(async () => {
+		const run = JSON.parse(readFileSync(join(result.recordDirectory, "run.json"), "utf8"));
+		if (run.cleanupError) throw new Error(`Cleanup failed: ${run.cleanupError}`);
+		const survivingPaneIds = [];
+		for (const task of result.tasks) if (await herdr.paneExists(task.paneId, signal)) survivingPaneIds.push(task.paneId);
+		record({ event: "cleanup-observation", run, survivingPaneIds });
+		return !run.cleanupPendingTabIds?.length && survivingPaneIds.length === 0 && !existsSync(join(result.recordDirectory, ".state.lock"));
+	}, `cleanup of ${result.tabId}`, 5_000);
+}
+
+async function runCase(label, names, concurrency, extensions = []) {
+	if (concurrency > 1 && process.env.HERDR_SUBAGENTS_E2E_FOCUS_CLEANUP === "1") {
+		const workspaces = spawnSync(process.env.PI_HERDR_SUBAGENTS_HERDR_BINARY?.trim() || "herdr", ["workspace", "list"], { encoding: "utf8", timeout: 10_000 });
+		assert.equal(workspaces.status, 0, workspaces.stderr);
+		const previous = JSON.parse(workspaces.stdout).result.workspaces.find((workspace) => workspace.focused);
+		assert.ok(previous?.active_tab_id, "The focused cleanup probe needs an existing focused tab to restore");
+		controlledFocus = { previousWorkspaceId: previous.workspace_id, previousTabId: previous.active_tab_id, triggered: false, restored: false };
+	}
 	const response = await executeHerdrSubagents({
 		label,
 		concurrency,
@@ -42,6 +113,7 @@ async function runCase(label, names, concurrency) {
 		})),
 	}, timeout, (update) => {
 		if (update.details?.tabId) tabIds.add(update.details.tabId);
+		if (update.details?.cleanupError) record({ event: "cleanup-warning", details: update.details, content: update.content });
 	}, { cwd: root }, {
 		agentsDirectory: join(packageDirectory, "agents"),
 		configurationPaths,
@@ -50,16 +122,33 @@ async function runCase(label, names, concurrency) {
 
 	const result = response.details;
 	if (result?.tabId) tabIds.add(result.tabId);
+	record({ event: "case-result", label, result, run: result?.recordDirectory ? JSON.parse(readFileSync(join(result.recordDirectory, "run.json"), "utf8")) : undefined });
 	assert.equal(response.isError, undefined, response.content?.[0]?.text);
 	assert.equal(result.status, "completed");
 	assert.equal(result.effectiveConcurrency, concurrency);
 	assert.equal(result.tasks.length, names.length);
 	assert.equal(new Set(result.tasks.map((task) => task.paneId)).size, names.length);
 
+	if (controlledFocus) {
+		assert.equal(controlledFocus.triggered, true, "The focus probe did not reach cleanup");
+		const run = JSON.parse(readFileSync(join(result.recordDirectory, "run.json"), "utf8"));
+		assert.ok(run.cleanupPendingTabIds?.includes(result.tabId), "Focused cleanup was not deferred");
+		restoreTestFocus();
+	}
+	await waitForCleanup(result);
+	if (controlledFocus) {
+		assertRestoredFocus();
+		console.log("PASS focused cleanup: deferred while focused, original workspace/tab focus restored, automatic cleanup observed");
+	}
 	for (const taskResult of result.tasks) {
 		const task = JSON.parse(readFileSync(join(taskResult.recordDirectory, "task.json"), "utf8"));
 		const report = JSON.parse(readFileSync(join(taskResult.recordDirectory, "report.json"), "utf8"));
 		assert.equal(task.status, "completed");
+		assert.deepEqual(task.extensions, extensions);
+		if (extensions.length) {
+			const commands = JSON.parse(readFileSync(join(taskResult.recordDirectory, "extension-loaded.json"), "utf8"));
+			assert.ok(commands.includes("skill:smoke-package-skill"), "Explicit package skill did not load in the real child");
+		}
 		assert.equal(report.status, "completed");
 		assert.equal(report.attemptId, task.currentAttemptId);
 		assert.equal(hasAssistantMessage(task.sessionFile), true, `${taskResult.name} produced no assistant event`);
@@ -70,8 +159,38 @@ async function runCase(label, names, concurrency) {
 
 try {
 	await runCase("real-single", ["hello-single"], 1);
-	await runCase("real-concurrent", ["hello-one", "hello-two"], 2);
+	const packageSource = join(root, "local-package");
+	mkdirSync(join(packageSource, "skills", "smoke-package-skill"), { recursive: true });
+	writeFileSync(join(packageSource, "package.json"), JSON.stringify({ name: "herdr-smoke-package", pi: { extensions: ["extension.ts"], skills: ["skills"] } }));
+	writeFileSync(join(packageSource, "skills", "smoke-package-skill", "SKILL.md"), "---\nname: smoke-package-skill\ndescription: A real Herdr package-loading probe\n---\n# Probe\n");
+	writeFileSync(join(packageSource, "extension.ts"), `import { writeFileSync } from "node:fs";
+		import { join } from "node:path";
+		export default function (pi) {
+			pi.on("session_start", () => writeFileSync(join(process.env.PI_HERDR_SUBAGENTS_TASK_DIR, "extension-loaded.json"), JSON.stringify(pi.getCommands().map((command) => command.name))));
+		}`);
+	writeFileSync(configurationPaths.globalConfig, JSON.stringify({ personas: { analyst: { extensions: [packageSource] } } }));
+	await runCase("real-concurrent", ["hello-one", "hello-two"], 2, [packageSource]);
+} catch (error) {
+	failed = true;
+	const snapshots = [];
+	for (const [kind, ids] of [["tab", tabIds], ["pane", paneIds]]) for (const id of ids) {
+		const result = spawnSync(process.env.PI_HERDR_SUBAGENTS_HERDR_BINARY?.trim() || "herdr", [kind, "get", id], { encoding: "utf8", timeout: 10_000 });
+		snapshots.push({ kind, id, status: result.status, stdout: result.stdout, stderr: result.stderr, error: result.error ? String(result.error) : undefined });
+	}
+	writeFileSync(join(root, "failure.json"), JSON.stringify({ error: String(error), snapshots }, null, 2));
+	console.error(`FAIL real Herdr smoke; preserved diagnostics: ${root}`);
+	throw error;
 } finally {
-	for (const tabId of tabIds) await herdr.closeTab(tabId).catch(() => undefined);
-	rmSync(root, { recursive: true, force: true });
+	const cleanupErrors = [];
+	try { restoreTestFocus(); } catch (error) { cleanupErrors.push(String(error)); }
+	for (const tabId of tabIds) await herdr.closeTab(tabId, AbortSignal.timeout(10_000)).catch((error) => {
+		if (!/tab[_ -]?not[_ -]?found|unknown tab/i.test(`${error}\n${error.stderr ?? ""}`)) cleanupErrors.push(String(error));
+	});
+	if (cleanupErrors.length) {
+		failed = true;
+		writeFileSync(join(root, "teardown-errors.json"), JSON.stringify(cleanupErrors, null, 2));
+		console.error(`FAIL smoke teardown; preserved diagnostics: ${root}`);
+		process.exitCode = 1;
+	}
+	if (!failed) rmSync(root, { recursive: true, force: true });
 }

package/packages/herdr-subagents/tests/run-tests.mjs

@@ -26,6 +26,7 @@ import { isAbortError } from "../src/errors.ts";
 import { acquireDirectoryLock, withRunStateLock } from "../src/run-state.ts";
 import { childPiArgs } from "../src/live-agent.ts";
 import registerSubagentReport from "../extensions/subagent-report.ts";
+import { waitFor } from "./wait-for.mjs";
 
 /** Drives one task through the batch runner and projects its single result like a task-scoped run. */
 async function runSingleTask(prompt, { label, agent, model, tools, systemPrompt, onStalled, ...options } = {}) {
@@ -581,6 +582,10 @@ try {
 
 	const definition = parseAgentMarkdown(`---\nname: reviewer\ndescription: Review code\nmodel: fake/model\ntools: read, grep\n---\nReview carefully.`, "reviewer.md");
 	check("persona frontmatter parsing", definition.name === "reviewer" && definition.model === "fake/model" && definition.tools?.join(",") === "read,grep" && definition.systemPrompt === "Review carefully.");
+	const extensionDefinition = parseAgentMarkdown(`---\nname: routed\ndescription: Routed explorer\nextensions: "~/.pi/agent/extensions/gateway-routing.ts", npm:@example/pi-tools@1.0.0\n---\nExplore.`, "routed.md");
+	check("persona frontmatter accepts local and npm extension sources", extensionDefinition.extensions?.join(",") === "~/.pi/agent/extensions/gateway-routing.ts,npm:@example/pi-tools@1.0.0");
+	const clearedExtensions = parseAgentMarkdown(`---\nname: routed\ndescription: Routed explorer\nextensions: []\n---\nExplore.`);
+	check("persona frontmatter can explicitly clear extension sources", Array.isArray(clearedExtensions.extensions) && clearedExtensions.extensions.length === 0);
 	const inheritedToolArgs = childPiArgs({ id: "inherited", sessionFile: "/tmp/inherited.jsonl" }, "/tmp/system.md");
 	check("child Pi enables codemode when a persona inherits default tools", inheritedToolArgs.includes("builtin:codemode") && inheritedToolArgs[inheritedToolArgs.indexOf("--tools") + 1] === "+codemode");
 	const explicitToolArgs = childPiArgs({ id: "explicit", sessionFile: "/tmp/explicit.jsonl", tools: ["read"] }, "/tmp/system.md");
@@ -633,6 +638,51 @@ try {
 	const configuredStart = configuredHerdr.calls.find(([name]) => name === "startAgent")[1];
 	check("configured persona uses displayed effective values", !configuredRun.isError && configuredStart.args.includes("task/model") && configuredStart.args.includes("high") && configuredStart.args.includes("--skill") && configuredStart.args.includes("project-skill"));
 
+	const extensionRoot = join(root, "extension-sources");
+	const extensionAgents = join(extensionRoot, "agents");
+	mkdirSync(extensionAgents, { recursive: true });
+	writeFileSync(join(extensionAgents, "routed.md"), `---\nname: routed\ndescription: Routed explorer\naccess: read\ntools: read\nextensions: ./markdown.ts\n---\nExplore.`);
+	const extensionPaths = { globalConfig: join(extensionRoot, "global.json"), projectConfig: join(extensionRoot, "project.json"), globalAgents: join(extensionRoot, "missing-global"), projectAgents: join(extensionRoot, "missing-project") };
+	const extensionPersona = () => loadSubagentConfiguration(extensionRoot, extensionAgents, undefined, extensionPaths).personas[0];
+	check("Markdown extension sources are effective without JSON overrides", extensionPersona()?.extensions?.join(",") === "./markdown.ts" && extensionPersona()?.extensionsSource === "package persona");
+	writeFileSync(extensionPaths.globalConfig, JSON.stringify({ personas: { routed: { extensions: ["./global.ts"] } } }));
+	check("global JSON replaces Markdown extension sources", extensionPersona()?.extensions?.join(",") === "./global.ts" && extensionPersona()?.extensionsSource === "global persona");
+	const extensionSources = ["~/.pi/agent/extensions/gateway-routing.ts", "npm:@example/pi-tools@1.0.0", "./local package"];
+	writeFileSync(extensionPaths.projectConfig, JSON.stringify({ personas: { routed: { extensions: extensionSources.map((source) => ` ${source} `) } } }));
+	check("project JSON trims and replaces global extension sources", JSON.stringify(extensionPersona()?.extensions) === JSON.stringify(extensionSources) && extensionPersona()?.extensionsSource === "project persona");
+	const extensionDependencies = { agentsDirectory: extensionAgents, configurationPaths: extensionPaths };
+	const sourceValues = (args) => args.flatMap((value, index) => value === "--extension" ? [args[index + 1]] : []);
+	const extensionRunHerdr = fakeHerdr();
+	const extensionRun = await executeHerdrSubagents({ tasks: [{ name: "routed", agent: "routed", prompt: "Review" }] }, undefined, undefined, { cwd: extensionRoot }, { ...extensionDependencies, herdr: extensionRunHerdr });
+	const extensionStart = extensionRunHerdr.calls.find(([name]) => name === "startAgent")[1];
+	check("explicit extension sources follow mandatory child extensions without shell splitting", !extensionRun.isError && extensionStart.args.includes("--no-extensions") && extensionStart.args.includes("--no-skills") && sourceValues(extensionStart.args)[0] === "builtin:codemode" && sourceValues(extensionStart.args)[1].endsWith("/extensions/subagent-report.ts") && JSON.stringify(sourceValues(extensionStart.args).slice(2)) === JSON.stringify(extensionSources) && extensionStart.args.includes("read,codemode,subagent_report"));
+	const extensionRecord = JSON.parse(readFileSync(join(extensionRun.details.tasks[0].recordDirectory, "task.json"), "utf8"));
+	check("effective extension sources are persisted in durable tasks", JSON.stringify(extensionRecord.extensions) === JSON.stringify(extensionSources));
+	const extensionHistory = await listSubagentHistory(extensionRoot);
+	check("history exposes saved extension sources", JSON.stringify(extensionHistory[0]?.tasks[0]?.extensions) === JSON.stringify(extensionSources));
+	const extensionList = await executeHerdrSubagents({ action: "list" }, undefined, undefined, { cwd: extensionRoot }, extensionDependencies);
+	check("persona listing shows extension sources and their precedence", extensionList.content[0].text.includes("npm:@example/pi-tools@1.0.0") && extensionList.content[0].text.includes("project persona"));
+	writeFileSync(extensionPaths.projectConfig, JSON.stringify({ personas: { routed: { extensions: [] } } }));
+	check("empty project extension list clears lower-precedence sources", extensionPersona()?.extensions?.length === 0 && extensionPersona()?.extensionsSource === "project persona");
+	const extensionResumeHerdr = fakeHerdr();
+	const extensionResume = await executeHerdrSubagents({ action: "resume", runId: extensionRun.details.runId, task: 1, prompt: "Follow up" }, undefined, undefined, { cwd: extensionRoot }, { ...extensionDependencies, herdr: extensionResumeHerdr });
+	const extensionResumeStart = extensionResumeHerdr.calls.find(([name]) => name === "startAgent")[1];
+	check("historical restart retains saved sources after configuration changes", !extensionResume.isError && JSON.stringify(sourceValues(extensionResumeStart.args).slice(2)) === JSON.stringify(extensionSources));
+	for (const invalidSources of ["npm:example", [""], ["valid", 42], null]) {
+		writeFileSync(extensionPaths.projectConfig, JSON.stringify({ personas: { routed: { extensions: invalidSources } } }));
+		const invalidSourcesConfig = loadSubagentConfiguration(extensionRoot, extensionAgents, undefined, extensionPaths);
+		check(`invalid extension sources are diagnosed: ${JSON.stringify(invalidSources)}`, invalidSourcesConfig.diagnostics.some((message) => message.includes("extensions must be an array of non-empty strings")) && invalidSourcesConfig.personas[0]?.extensions?.join(",") === "./global.ts");
+	}
+	writeFileSync(extensionPaths.projectConfig, JSON.stringify({ personas: { routed: { extensions: extensionSources } } }));
+	const extensionBlockedHerdr = fakeHerdr("blocked");
+	const extensionBlocked = await executeHerdrSubagents({ tasks: [{ name: "routed-blocked", agent: "routed", prompt: "Ask a question" }] }, undefined, undefined, { cwd: extensionRoot }, { ...extensionDependencies, herdr: extensionBlockedHerdr });
+	const extensionResponseHerdr = fakeHerdr();
+	extensionResponseHerdr.isTaskRunning = async () => false;
+	const extensionAnswered = await executeHerdrSubagents({ action: "respond", runId: extensionBlocked.details.runId, task: 1, answer: "Use main" }, undefined, undefined, { cwd: extensionRoot }, { ...extensionDependencies, herdr: extensionResponseHerdr });
+	const extensionResponseStart = extensionResponseHerdr.calls.find(([name]) => name === "startAgent")?.[1];
+	check("blocked response restart retains saved extension sources", !extensionAnswered.isError && extensionResponseStart && JSON.stringify(sourceValues(extensionResponseStart.args).slice(2)) === JSON.stringify(extensionSources));
+	check("unconfigured children keep only mandatory extensions", sourceValues(inheritedToolArgs).length === 2 && JSON.stringify(childPiArgs({ id: "inherited", sessionFile: "/tmp/inherited.jsonl", extensions: [] }, "/tmp/system.md")) === JSON.stringify(inheritedToolArgs));
+
 	const analystHerdr = fakeHerdr();
 	analystHerdr.expectConcurrentPrompts(3);
 	const analystBatch = await executeHerdrSubagents({ label: "independent-analysis", concurrency: 3, tasks: [
@@ -761,7 +811,7 @@ try {
 	check("write-capable batch is forced serial", writerBatch.details.effectiveConcurrency === 1 && writerHerdr.maxActive === 1 && writerHerdr.calls.filter(([name]) => name === "splitPane").length === 1);
 	const focusedHerdr = fakeHerdr("focused");
 	await executeHerdrSubagents({ tasks: [{ name: "inspect", prompt: "inspect", agent: "explorer" }] }, undefined, undefined, { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: focusedHerdr });
-	await new Promise((resolve) => setTimeout(resolve, 0));
+	await waitFor(() => focusedHerdr.calls.some(([name]) => name === "closeTab"), "focused tab close");
 	const focusedCalls = focusedHerdr.calls.map(([name]) => name);
 	check("focused completed tab defers cleanup until focus leaves", focusedCalls.indexOf("waitForTabUnfocused") >= 0 && focusedCalls.indexOf("closeTab") > focusedCalls.indexOf("waitForTabUnfocused"));
 	const pendingCleanupHerdr = fakeHerdr();
@@ -774,7 +824,7 @@ try {
 	const resumeWhilePending = await executeHerdrSubagents({ action: "resume", runId: pendingCleanupRun.details.runId, task: 1, prompt: "too soon" }, undefined, undefined, { cwd: root }, { agentsDirectory: join(process.cwd(), "agents"), herdr: pendingCleanupHerdr });
 	check("pending tab cleanup blocks deletion but permits an isolated resume generation", pendingCleanupRecord.cleanupPendingTabIds?.includes(pendingCleanupRun.details.tabId) && cleanupWhilePending.isError && !resumeWhilePending.isError);
 	releasePendingCleanup();
-	await new Promise((resolve) => setTimeout(resolve, 10));
+	await waitFor(() => !JSON.parse(readFileSync(join(pendingCleanupRun.details.recordDirectory, "run.json"), "utf8")).cleanupPendingTabIds && !existsSync(join(pendingCleanupRun.details.recordDirectory, ".state.lock")), "deferred cleanup state commit");
 	const releasedCleanupRecord = JSON.parse(readFileSync(join(pendingCleanupRun.details.recordDirectory, "run.json"), "utf8"));
 	check("deferred cleanup merges into the latest run record", releasedCleanupRecord.status === "completed" && !("cleanupPendingTabIds" in releasedCleanupRecord));
 	const shutdownDeferredHerdr = fakeHerdr();
@@ -789,13 +839,13 @@ try {
 	const shutdownDeferredController = new AbortController();
 	await executeHerdrSubagents({ tasks: [{ name: "shutdown-deferred", prompt: "inspect", agent: "explorer" }] }, shutdownDeferredController.signal, undefined, { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: shutdownDeferredHerdr });
 	shutdownDeferredController.abort(new Error("Parent Pi session closed."));
-	await new Promise((resolve) => setTimeout(resolve, 10));
+	await waitFor(() => shutdownDeferredHerdr.calls.some(([name]) => name === "closeTab"), "shutdown close of a focused tab");
 	check("parent shutdown force-closes a settled focused tab", shutdownDeferredHerdr.calls.some(([name]) => name === "closeTab"));
 	const deferredFailureHerdr = fakeHerdr();
 	deferredFailureHerdr.isTabFocused = async () => true;
 	deferredFailureHerdr.closeTab = async () => { throw new Error("deferred close failed"); };
 	const deferredFailure = await executeHerdrSubagents({ tasks: [{ name: "deferred-cleanup", prompt: "inspect", agent: "explorer" }] }, undefined, undefined, { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: deferredFailureHerdr });
-	await new Promise((resolve) => setTimeout(resolve, 10));
+	await waitFor(() => JSON.parse(readFileSync(join(deferredFailure.details.recordDirectory, "run.json"), "utf8")).cleanupError === "deferred close failed" && !existsSync(join(deferredFailure.details.recordDirectory, ".state.lock")), "deferred cleanup error commit");
 	const deferredFailureRecord = JSON.parse(readFileSync(join(deferredFailure.details.recordDirectory, "run.json"), "utf8"));
 	check("deferred focus cleanup failure remains durably retryable", deferredFailureRecord.cleanupError === "deferred close failed" && deferredFailureRecord.cleanupPendingTabIds?.includes(deferredFailure.details.tabId));
 	const deferredSingleHerdr = fakeHerdr();
@@ -803,7 +853,7 @@ try {
 	deferredSingleHerdr.closeTab = async () => { throw new Error("single deferred close failed"); };
 	const deferredSingleUpdates = [];
 	const deferredSingle = await executeHerdrSubagents({ tasks: [{ name: "deferred-single", prompt: "single deferred cleanup", agent: "explorer" }] }, undefined, (update) => deferredSingleUpdates.push(update), { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: deferredSingleHerdr });
-	await new Promise((resolve) => setTimeout(resolve, 10));
+	await waitFor(() => deferredSingleUpdates.some((update) => update.details.cleanupError) && !existsSync(join(deferredSingle.details.recordDirectory, ".state.lock")), "deferred cleanup error notification");
 	const deferredSingleRun = JSON.parse(readFileSync(join(deferredSingle.details.recordDirectory, "run.json"), "utf8"));
 	check("deferred cleanup failure is persisted and surfaced without changing completion", deferredSingleRun.status === "completed" && deferredSingleRun.cleanupError === "single deferred close failed" && deferredSingleUpdates.some((update) => update.content[0].text.includes("cleanup failed") && update.details.cleanupError));
 	const cancelledHerdr = fakeHerdr();
@@ -1791,13 +1841,14 @@ try {
 	const staleContinuationTask = join(staleContinuationRun, "tasks", "01-task");
 	mkdirSync(staleContinuationTask, { recursive: true });
 	writeFileSync(join(staleContinuationRun, "run.json"), JSON.stringify({ id: "stale-continuation", label: "stale-continuation", status: "running", cwd: staleContinuationRoot, effectiveConcurrency: 1, tabId: "w1:t-old", paneIds: ["w1:p-old"], startedAt: new Date().toISOString() }));
-	writeFileSync(join(staleContinuationTask, "task.json"), JSON.stringify({ id: "stale-task", runId: "stale-continuation", order: 1, name: "stale-task", status: "queued", prompt: "continue", agent: "explorer", skills: [], sessionFile: join(staleContinuationTask, "session.jsonl") }));
+	writeFileSync(join(staleContinuationTask, "task.json"), JSON.stringify({ id: "stale-task", runId: "stale-continuation", order: 1, name: "stale-task", status: "queued", prompt: "continue", agent: "explorer", skills: [], extensions: extensionSources, sessionFile: join(staleContinuationTask, "session.jsonl") }));
 	writeFileSync(join(staleContinuationTask, "system-prompt.md"), "Report the result.");
 	const staleContinuationHerdr = fakeHerdr();
 	staleContinuationHerdr.paneExists = async () => false;
 	staleContinuationHerdr.createTab = async (request) => { staleContinuationHerdr.calls.push(["createTab", request]); return { tabId: "w1:t-new", paneId: "w1:p-new" }; };
 	await continueQueuedRun(staleContinuationRun, staleContinuationHerdr);
 	const staleContinuationRecord = JSON.parse(readFileSync(join(staleContinuationRun, "run.json"), "utf8"));
+	check("queued recovery retains saved extension sources", JSON.stringify(sourceValues(staleContinuationHerdr.calls.find(([name]) => name === "startAgent")[1].args).slice(2)) === JSON.stringify(extensionSources));
 	check("queued recovery closes a replaced stale tab", staleContinuationRecord.status === "completed" && staleContinuationRecord.tabId === "w1:t-new" && !staleContinuationRecord.staleTabIds && staleContinuationHerdr.calls.some(([name, request]) => name === "closeTab" && request.tabId === "w1:t-old"));
 	const failedCleanupRoot = join(root, "stale-continuation-cleanup-failure");
 	const failedCleanupRun = join(failedCleanupRoot, ".pi", "herdr-subagents", "runs", "run");

package/packages/herdr-subagents/tests/wait-for.mjs

@@ -0,0 +1,12 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+/** Wait for an observable condition, not an assumed completion time. */
+export async function waitFor(check, description, timeoutMs = 5_000) {
+	const deadline = performance.now() + timeoutMs;
+	for (;;) {
+		const result = await check();
+		if (result) return result;
+		if (performance.now() >= deadline) throw new Error(`Timed out after ${timeoutMs} ms waiting for ${description}`);
+		await delay(10);
+	}
+}