@maxiaochao/pi-toolkit 0.11.21 → 0.12.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2026-10-15 - v0.12.0
+
+- herdr-subagents v0.6.0: require explicit task Personas and clarify concise tool descriptions
+- Require an explicit Herdr Subagents Persona for every new task, clarify concise tool descriptions, and identify tasks with conflicting write access in parallel requests.
+
+## 2026-10-15 - v0.11.22
+
+- herdr-subagents v0.5.4: preserve configured model and authentication extensions in isolated real-Herdr smoke tests
+- Herdr Subagents: preserve configured models and explicit authentication extensions in isolated real-Herdr E2E tests instead of losing account-pool setup.
+
 ## 2026-10-15 - v0.11.21
 
 - simplify Agent Team to config-driven orchestration with persistent investigation records and optional extra review

package/README.md

@@ -39,7 +39,7 @@ Restart Pi after updating. `pi update --extensions` has the same effect when upd
 
 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.
+Herdr Subagents tasks require an explicit `agent` Persona; no default `worker` is selected. 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. The [real Herdr smoke test](packages/herdr-subagents/TESTING.md) preserves the configured analyst model and explicit authentication extensions while isolating unrelated settings.
 
 Multiple standalone children may be installed together. `pi-openai-account-pool` may also be installed alongside the complete toolkit because the toolkit does not embed it. Every other child in the table above is embedded, so a second install exposes the same resource twice.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.11.21",
+  "version": "0.12.0",
   "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/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 2026-10-15 - v0.6.0
+
+- require explicit task Personas and clarify concise tool descriptions
+- Require an explicit Herdr Subagents Persona for every new task, clarify concise tool descriptions, and identify tasks with conflicting write access in parallel requests.
+
+## 2026-10-15 - v0.5.4
+
+- preserve configured model and authentication extensions in isolated real-Herdr smoke tests
+- Preserve the configured analyst model, thinking level, and explicit authentication extensions in isolated real-Herdr smoke tests; append the concurrent package probe without replacing those extensions.
+- Add deterministic smoke-configuration coverage and isolate exposure test fixtures from personal settings.
+
 ## 2026-10-14 - v0.5.3
 
 - allow optional Pi-native tool exposure while inheriting Pi defaults when unset

package/packages/herdr-subagents/README.md

@@ -26,7 +26,7 @@ The tools and command are registered only when Pi is running inside Herdr with a
 
 ## Execution contract
 
-`herdr_subagents` accepts an ordered, non-empty `tasks` array.
+`herdr_subagents` accepts an ordered, non-empty `tasks` array. Every task must explicitly set `agent`; there is no default Persona.
 
 - `concurrency: 1` runs tasks strictly in input order.
 - `concurrency: N` runs at most N read-only tasks at once.
@@ -110,7 +110,7 @@ Starts one ordered batch and waits until every task reaches a terminal state. It
 | `concurrency` | No | `defaultConcurrency` | Maximum number of simultaneously active read-only tasks. It is capped by `maxConcurrency`. |
 | `tasks[].name` | Yes | — | Short pane/task name, at most 48 characters. |
 | `tasks[].prompt` | Yes | — | Self-contained task instructions. |
-| `tasks[].agent` | No | `"worker"` | Effective Persona name. |
+| `tasks[].agent` | Yes | — | Effective Persona name; use control `list` to inspect available Personas. |
 | `tasks[].model` | No | Persona/default model | Model override for this task. |
 
 A batch containing a write-capable Persona must explicitly or effectively use `concurrency: 1`; an unsafe parallel request is rejected.
@@ -321,4 +321,4 @@ Use `/herdr-subagents agents`, `/herdr-subagents models`, and `/herdr-subagents
 
 ## Development and tests
 
-See [TESTING.md](TESTING.md) for deterministic tests, extension loading, packaging, and real Herdr smoke requirements.
+See [TESTING.md](TESTING.md) for deterministic tests, extension loading, packaging, and real Herdr smoke requirements. The real smoke preserves your configured `analyst` model, thinking level, and explicit extensions (including authentication providers) inside its isolated fixture; unrelated Persona settings remain isolated.

package/packages/herdr-subagents/TESTING.md

@@ -12,7 +12,9 @@ It verifies:
 - bounded read-only parallelism;
 - ordered results despite concurrent completion;
 - sibling continuation after failure and all-failed aggregation;
-- explicit rejection of parallel write-capable tasks;
+- required explicit Personas in the tool schema and execution, including legacy single-task argument normalization;
+- rejection of missing, blank, invalid, and unknown Personas before creating runs, while custom Personas remain supported;
+- explicit rejection of parallel write-capable tasks with the conflicting task, Persona, and corrective action;
 - waiting through a delayed authoritative report after a prompt transport error while the Pi process is alive;
 - explicit failure when the process exits without a report;
 - parent cancellation of running and queued tasks;
@@ -20,7 +22,9 @@ It verifies:
 - omitted exposure delegates both tools to Pi's default, while project configuration can consistently select model-only exposure;
 - immutable terminal task records;
 - idempotent duplicate reports and rejection of conflicting replacements;
-- keeping a settled child alive for focus-aware cleanup instead of force-exiting its TUI.
+- keeping a settled child alive for focus-aware cleanup instead of force-exiting its TUI;
+- preserving the configured smoke model, thinking level, and authentication extensions while isolating unrelated settings;
+- project-over-global smoke configuration, explicit extension clearing, model overrides, and local-source paths after moving to a temporary directory.
 
 The previous broad lifecycle suite remains available temporarily as `npm run test:legacy --workspace @maxiaochao/pi-herdr-subagents` for migration auditing. Scenarios for background queues, blocked/respond, and historical resume intentionally no longer describe the public contract.
 
@@ -36,4 +40,10 @@ Run the real Herdr smoke test from a Herdr session:
 npm run test:real-herdr --workspace @maxiaochao/pi-herdr-subagents
 ```
 
+The smoke reads the effective `analyst` model, thinking level, and explicit `extensions` from the invoking project's normal Herdr configuration (npm's `INIT_CWD`, or the current directory when run directly). It copies only those fields into its temporary configuration. It keeps the bundled read-only Persona, tool allowlist, and test concurrency; user skills, prompts, and unrelated settings are not copied. Local extension paths remain relative to the invoking project. The concurrent package-loading probe appends its test package rather than replacing the configured extensions.
+
+This preserves authentication extensions such as `npm:@maxiaochao/pi-openai-account-pool` in both the single and concurrent cases. Children still use `--no-extensions`: only the mandatory child extensions, configured explicit sources, and test probe load. The smoke does not copy or edit credentials. If no Herdr model is configured, Pi's normal startup model selection still applies.
+
+`HERDR_SUBAGENTS_E2E_MODEL=provider/model` overrides only the smoke model; configured extensions remain loaded. Set `HERDR_SUBAGENTS_E2E_FOCUS_CLEANUP=1` to also verify deferred cleanup while focused and restoration of the original workspace/tab focus.
+
 For real smoke testing, verify that each child appears in a visible pane and can be focused and inspected. An early-finishing child must remain visible while sibling tasks continue. After the whole run settles, a focused child must remain at its restored Pi UI until focus leaves the run tab; the tab must then close automatically. Verify that the parent returns only after all requested tasks settle. Also verify cancellation closes the run tab and does not overwrite a report already atomically published.

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

@@ -42,7 +42,7 @@ export function normalizeHerdrSubagentsArguments(args: unknown): HerdrSubagentsR
 		tasks: [{
 			name: label || "task",
 			prompt: legacy.prompt,
-			...(typeof legacy.agent === "string" ? { agent: legacy.agent } : {}),
+			agent: legacy.agent as string,
 			...(typeof legacy.model === "string" ? { model: legacy.model } : {}),
 		}],
 		...(label ? { label } : {}),
@@ -148,7 +148,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 		name: "herdr_subagents",
 		...(exposure ? { exposure } : {}),
 		label: "Herdr Subagents",
-		description: "Run one or more ordered tasks in visible, focusable Herdr Pi panes. concurrency 1 is strict serial execution; higher values form a bounded pool for read-only tasks. Write-capable tasks require concurrency 1. The call returns only after every task has one terminal completed, failed, or cancelled result. Complete results and Pi sessions stay in project-local records.",
+		description: "Run ordered tasks in visible Herdr Pi panes, with an explicit agent for each task. concurrency 1 is serial; higher values require read-only Personas. Returns after all tasks complete, fail, or cancel; full results and sessions remain in project-local records.",
 		promptSnippet: "Run focused work in visible Herdr subagents",
 		parameters: HerdrSubagentsParams,
 		prepareArguments: normalizeHerdrSubagentsArguments,

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [
@@ -37,7 +37,7 @@
     "typebox": "*"
   },
   "scripts": {
-    "test": "node --experimental-strip-types tests/core-state-machine.mjs",
+    "test": "node --experimental-strip-types tests/core-state-machine.mjs && node --experimental-strip-types tests/real-herdr-config.test.mjs",
     "test:real-herdr": "node --experimental-strip-types tests/real-herdr-smoke.mjs",
     "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",
     "test:legacy": "node --experimental-strip-types tests/run-tests.mjs && node --experimental-strip-types tests/cleanup-timing.mjs"

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

@@ -92,7 +92,8 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 	const runId = options.runId ?? randomUUID();
 	const requestedConcurrency = Math.max(1, Math.floor(options.concurrency));
 	if (requestedConcurrency > 1 && tasks.some((task) => task.access === "write")) {
-		throw new Error("Write-capable tasks require concurrency 1; parallel writes are not safe.");
+		const writers = tasks.filter((task) => task.access === "write").map((task) => `${JSON.stringify(task.name)} (agent=${task.agent})`).join(", ");
+		throw new Error(`Write-capable tasks require concurrency 1: ${writers}. Use concurrency: 1, or select a read-only Persona for read-only work.`);
 	}
 	const effectiveConcurrency = Math.min(requestedConcurrency, options.maxConcurrency, tasks.length);
 	const runDirectory = join(options.cwd, ".pi", "herdr-subagents", "runs", `${timestamp().replace(/[-:.]/g, "").replace("Z", "Z-")}${runId.slice(0, 8)}`);

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

@@ -4,14 +4,14 @@ import { Type } from "typebox";
 const HerdrSubagentsTaskParams = Type.Object({
 	name: Type.String({ minLength: 1, maxLength: 48, description: "Short task name shown in the pane and task list." }),
 	prompt: Type.String({ minLength: 1, description: "Self-contained prompt for this task." }),
-	agent: Type.Optional(Type.String({ minLength: 1, description: "Persona for this task. Defaults to worker." })),
+	agent: Type.String({ minLength: 1, description: "Persona name, use control list for available Personas." }),
 	model: Type.Optional(Type.String({ minLength: 1, description: "Optional model override for this task." })),
 }, { additionalProperties: false });
 
 export const HerdrSubagentsParams = Type.Object({
 	tasks: Type.Array(HerdrSubagentsTaskParams, { minItems: 1, description: "Ordered tasks to execute. Use one item for a single task; independent read-only tasks may run concurrently." }),
 	label: Type.Optional(Type.String({ minLength: 1, maxLength: 48, description: "Short Herdr run-tab label." })),
-	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum simultaneously active Agents. Write-capable tasks force concurrency one." })),
+	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum active Agents. Values above 1 require read-only Personas; write-capable Personas require 1 or the batch is rejected." })),
 }, { additionalProperties: false });
 
 export const HerdrSubagentsControlParams = Type.Object({

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

@@ -7,7 +7,7 @@ import type { OwnerIdentity } from "./ownership.ts";
 import { cancelActiveSubagentRuns } from "./reconcile.ts";
 import { getSubagentRunStatus, runStatusText } from "./status.ts";
 
-export interface HerdrSubagentsTaskParams { name: string; prompt: string; agent?: string; model?: string; }
+export interface HerdrSubagentsTaskParams { name: string; prompt: string; agent: string; model?: string; }
 
 export interface HerdrSubagentsRunParams {
 	tasks: HerdrSubagentsTaskParams[];
@@ -140,7 +140,7 @@ async function executeBatch({ params, signal, onUpdate, ctx, dependencies, disco
 	const tasks = params.tasks as HerdrSubagentsTaskParams[];
 	const resolved: BatchTask[] = [];
 	for (const task of tasks) {
-		const personaName = task.agent?.trim() || "worker";
+		const personaName = task.agent.trim();
 		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, extensions: persona.extensions, systemPrompt: persona.systemPrompt });

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

@@ -10,6 +10,9 @@ export const HERDR_ACTIONS = {
 
 export function validateRunParams(params: HerdrSubagentsRunParams): string | undefined {
 	if (!params.tasks?.length) return "Provide a non-empty tasks list.";
+	for (const [index, task] of params.tasks.entries()) {
+		if (typeof task.agent !== "string" || !task.agent.trim()) return `tasks[${index}].agent is required; select a Persona explicitly (use herdr_subagents_control action=list).`;
+	}
 	return undefined;
 }
 

package/packages/herdr-subagents/tests/core-state-machine.mjs

@@ -1,11 +1,13 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { runHerdrSubagentsBatch } from "../src/batch-runner.ts";
 import registerSubagentReport from "../extensions/subagent-report.ts";
-import { registerHerdrSubagents } from "../extensions/herdr-subagents.ts";
+import { normalizeHerdrSubagentsArguments, registerHerdrSubagents } from "../extensions/herdr-subagents.ts";
 import { applyTaskStatus } from "../src/records.ts";
+import { executeHerdrSubagents } from "../src/tool.ts";
 
 process.env.HERDR_ENV = "1";
 process.env.HERDR_WORKSPACE_ID = "test-workspace";
@@ -92,6 +94,45 @@ async function run(tasks, concurrency, herdr = fakeHerdr(), signal) {
 	return { result, herdr };
 }
 
+{
+	const herdr = fakeHerdr();
+	const execute = (params) => executeHerdrSubagents(params, undefined, undefined, { cwd: root }, {
+		agentsDirectory: fileURLToPath(new URL("../agents/", import.meta.url)),
+		configurationPaths: { globalConfig: join(root, "global-config.json") },
+		herdr,
+	});
+	const missing = { name: "review", prompt: "Read-only review" };
+	for (const params of [
+		{ tasks: [missing] },
+		...["", " \t", null, 42].map((agent) => ({ tasks: [{ ...missing, agent }] })),
+		normalizeHerdrSubagentsArguments({ prompt: "Read-only review" }),
+		normalizeHerdrSubagentsArguments({ prompt: "Read-only review", agent: 42 }),
+	]) {
+		const response = await execute(params);
+		assert.equal(response.isError, true, "Missing or invalid agent must not silently select worker");
+		assert.match(response.content[0].text, /tasks\[0\]\.agent.*required/);
+	}
+	const laterMissing = await execute({ tasks: [{ ...missing, agent: "analyst" }, missing], concurrency: 2 });
+	assert.match(laterMissing.content[0].text, /tasks\[1\]\.agent.*required/);
+	const unknown = await execute({ tasks: [{ ...missing, agent: "unknown-persona" }] });
+	assert.equal(unknown.isError, true);
+	assert.match(unknown.content[0].text, /Unknown persona 'unknown-persona'/);
+	assert.deepEqual(herdr.starts, [], "Invalid requests must not start an Agent");
+	assert.equal(existsSync(join(root, ".pi", "herdr-subagents", "runs")), false, "Invalid requests must not create run records");
+
+	const serial = await execute(normalizeHerdrSubagentsArguments({ prompt: "make change", agent: "worker" }));
+	assert.equal(serial.details.status, "completed", "Explicit worker must still run serially through legacy argument normalization");
+	const parallel = await execute({ tasks: ["analyst", "reviewer", "explorer"].map((agent) => ({ ...missing, agent })), concurrency: 2 });
+	assert.equal(parallel.details.status, "completed");
+	assert.equal(parallel.details.effectiveConcurrency, 2);
+
+	const projectAgents = join(root, ".pi", "herdr-subagents", "agents");
+	mkdirSync(projectAgents, { recursive: true });
+	writeFileSync(join(projectAgents, "auditor.md"), "---\nname: auditor\ndescription: Custom read-only reviewer\naccess: read\n---\nReview the task.\n");
+	const custom = await execute({ tasks: [{ ...missing, agent: " auditor " }], concurrency: 2 });
+	assert.equal(custom.details.status, "completed", "Custom Persona names must remain valid and trim whitespace");
+}
+
 {
 	const { result, herdr } = await run([task("one", "first slow"), task("two", "second")], 1);
 	assert.equal(result.status, "completed");
@@ -146,7 +187,12 @@ async function run(tasks, concurrency, herdr = fakeHerdr(), signal) {
 	assert.deepEqual(result.activity.map((entry) => entry.status), ["cancelled", "cancelled"]);
 }
 
-await assert.rejects(() => run([task("writer", "edit", "write"), task("reader", "read")], 2), /require concurrency 1/);
+await assert.rejects(() => run([task("writer", "edit", "write"), task("reader", "read")], 2), (error) => {
+	assert.match(error.message, /writer.*worker/);
+	assert.match(error.message, /concurrency: 1/);
+	assert.match(error.message, /read-only Persona/);
+	return true;
+});
 
 const terminal = { id: "task", runId: "run", order: 1, status: "completed" };
 assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are immutable/);
@@ -159,6 +205,7 @@ assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are im
 	const historicalRun = { id: "historical-run", label: "historical", status: "completed", ownerSessionId: "old-session", ownerProcessId: 99999999, tabId: "w1:t-reused", taskIds: ["historical-task"], completedAt: "2026-10-01T00:00:00.000Z" };
 	writeFileSync(join(runDirectory, "run.json"), JSON.stringify(historicalRun));
 	writeFileSync(join(taskDirectory, "task.json"), JSON.stringify({ id: "historical-task", runId: "historical-run", order: 1, status: "completed", completedAt: historicalRun.completedAt }));
+	const configurationPaths = { globalConfig: join(lifecycleRoot, "global-config.json") };
 	const events = new Map();
 	const registeredTools = new Map();
 	const herdrCalls = [];
@@ -172,6 +219,8 @@ assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are im
 			async closeTab(tabId) { herdrCalls.push(["closeTab", tabId]); },
 		},
 		isEditor: () => false,
+		configurationCwd: lifecycleRoot,
+		configurationPaths,
 	});
 	await events.get("session_start")?.({}, {
 		cwd: lifecycleRoot,
@@ -181,6 +230,9 @@ assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are im
 	});
 	assert.deepEqual(herdrCalls, [], "Pi startup must not inspect or close historical Subagent tabs");
 	assert.deepEqual(JSON.parse(readFileSync(join(runDirectory, "run.json"), "utf8")), historicalRun, "Pi startup must not mutate historical Subagent records");
+	const taskSchema = registeredTools.get("herdr_subagents").parameters.properties.tasks.items;
+	assert.ok(taskSchema.required.includes("agent"), "The model-facing schema must require agent");
+	assert.equal(taskSchema.properties.agent.enum, undefined, "Custom Persona names must remain valid");
 	assert.equal(registeredTools.get("herdr_subagents")?.exposure, undefined, "Unconfigured Subagent execution must inherit Pi's exposure default");
 	assert.equal(registeredTools.get("herdr_subagents_control")?.exposure, undefined, "Unconfigured Subagent control must inherit Pi's exposure default");
 	mkdirSync(join(lifecycleRoot, ".pi"), { recursive: true });
@@ -190,7 +242,7 @@ assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are im
 		on() {},
 		registerTool(tool) { configuredTools.set(tool.name, tool); },
 		registerCommand() {},
-	}, { herdr: {}, isEditor: () => false, configurationCwd: lifecycleRoot });
+	}, { herdr: {}, isEditor: () => false, configurationCwd: lifecycleRoot, configurationPaths });
 	assert.equal(configuredTools.get("herdr_subagents")?.exposure, "model-only", "Project configuration can exclude Subagent execution from Codemode");
 	assert.equal(configuredTools.get("herdr_subagents_control")?.exposure, "model-only", "Project configuration applies consistently to both Subagent tools");
 }

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

@@ -0,0 +1,14 @@
+import { resolve } from "node:path";
+import { loadSubagentConfiguration } from "../src/config.ts";
+
+export function smokePersona(cwd, agentsDirectory, model, paths) {
+	const discovery = loadSubagentConfiguration(cwd, agentsDirectory, undefined, paths);
+	const analyst = discovery.personas.find(({ name }) => name === "analyst");
+	if (!analyst) throw new Error("Real Herdr smoke requires an analyst Persona.");
+	return {
+		model: model?.trim() || analyst.model,
+		thinking: analyst.thinking,
+		// Local sources must still resolve from the caller's project after moving to the fixture cwd.
+		extensions: analyst.extensions.map((source) => /^(?:[a-z][a-z\d+.-]*:|~(?:\/|$)|git@)/i.test(source) ? source : resolve(cwd, source)),
+	};
+}

package/packages/herdr-subagents/tests/real-herdr-config.test.mjs

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadSubagentConfiguration } from "../src/config.ts";
+import { childPiArgs } from "../src/live-agent.ts";
+import { smokePersona } from "./real-herdr-config.mjs";
+
+const root = mkdtempSync(join(tmpdir(), "herdr-smoke-config-"));
+const agents = fileURLToPath(new URL("../agents", import.meta.url));
+const paths = {
+	globalConfig: join(root, "global.json"),
+	projectConfig: join(root, "project.json"),
+	globalAgents: join(root, "global-agents"),
+	projectAgents: join(root, "project-agents"),
+};
+const write = (path, value) => writeFileSync(path, JSON.stringify(value));
+try {
+	write(paths.globalConfig, {
+		maxConcurrency: 1,
+		defaultModel: "openai-codex/test-model",
+		defaultThinking: "high",
+		personas: { analyst: {
+			extensions: ["npm:@maxiaochao/pi-openai-account-pool"],
+			skills: ["unrelated-skill"],
+		} },
+	});
+	const before = readFileSync(paths.globalConfig, "utf8");
+	const persona = smokePersona(root, agents, undefined, paths);
+	assert.deepEqual(persona, {
+		model: "openai-codex/test-model",
+		thinking: "high",
+		extensions: ["npm:@maxiaochao/pi-openai-account-pool"],
+	});
+
+	const fixture = join(root, "fixture.json");
+	const probe = join(root, "local-package");
+	write(fixture, { personas: { analyst: { ...persona, extensions: [...persona.extensions, probe] } } });
+	const isolated = loadSubagentConfiguration(root, agents, undefined, { ...paths, globalConfig: fixture });
+	const analyst = isolated.personas.find(({ name }) => name === "analyst");
+	assert.equal(isolated.settings.maxConcurrency, 4);
+	assert.equal(analyst.access, "read");
+	assert.deepEqual(analyst.skills, []);
+	assert.deepEqual(analyst.extensions, ["npm:@maxiaochao/pi-openai-account-pool", probe]);
+	const args = childPiArgs({ ...analyst, sessionFile: join(root, "session.jsonl") }, join(root, "system.md"));
+	assert.equal(args[args.indexOf("--model") + 1], "openai-codex/test-model");
+	assert.ok(args.includes("--no-extensions"));
+	assert.ok(args.includes("npm:@maxiaochao/pi-openai-account-pool"));
+	assert.ok(args.includes(probe));
+	assert.equal(readFileSync(paths.globalConfig, "utf8"), before);
+	console.log("PASS smoke preserves configured model and authentication extensions without copying unrelated settings");
+
+	write(paths.projectConfig, { personas: { analyst: {
+		model: "custom/project-model",
+		thinking: "low",
+		extensions: ["./provider with spaces.ts", "../provider-package", "~/provider.ts", "npm:provider@1.0.0", "git:github.com/example/provider@v1", "builtin:codemode", "https://example.test/provider.git"],
+	} } });
+	assert.deepEqual(smokePersona(root, agents, undefined, paths), {
+		model: "custom/project-model",
+		thinking: "low",
+		extensions: [join(root, "provider with spaces.ts"), join(root, "..", "provider-package"), "~/provider.ts", "npm:provider@1.0.0", "git:github.com/example/provider@v1", "builtin:codemode", "https://example.test/provider.git"],
+	});
+	console.log("PASS smoke honors project precedence and keeps local and native package sources valid in a temporary cwd");
+
+	write(paths.projectConfig, { personas: { analyst: { extensions: [] } } });
+	assert.deepEqual(smokePersona(root, agents, " custom/override-model ", paths), {
+		model: "custom/override-model",
+		thinking: "high",
+		extensions: [],
+	});
+	mkdirSync(paths.globalAgents, { recursive: true });
+	writeFileSync(join(paths.globalAgents, "analyst.md"), "---\nname: analyst\ndescription: Custom user analyst\naccess: write\ntools: write\n---\nUnrelated user prompt.\n");
+	const selected = smokePersona(root, agents, undefined, paths);
+	assert.deepEqual(Object.keys(selected).sort(), ["extensions", "model", "thinking"]);
+	assert.equal(selected.model, "openai-codex/test-model");
+	console.log("PASS smoke supports model overrides and explicit extension clearing without copying Persona tools or prompts");
+} finally {
+	rmSync(root, { recursive: true, force: true });
+}

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

@@ -7,12 +7,14 @@ import { fileURLToPath } from "node:url";
 import { executeHerdrSubagents } from "../src/tool.ts";
 import { CliHerdrAutomation } from "../src/herdr.ts";
 import { waitFor } from "./wait-for.mjs";
+import { smokePersona } from "./real-herdr-config.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.");
 }
 
 const packageDirectory = dirname(dirname(fileURLToPath(import.meta.url)));
+const runtimePersona = smokePersona(process.env.INIT_CWD || process.cwd(), join(packageDirectory, "agents"), process.env.HERDR_SUBAGENTS_E2E_MODEL);
 const root = mkdtempSync(join(tmpdir(), "pi-herdr-subagents-real-"));
 const herdr = new CliHerdrAutomation();
 const tabIds = new Set();
@@ -47,7 +49,6 @@ for (const method of ["createTab", "splitPane", "startAgent", "isTabFocused", "w
 		}
 	};
 }
-const model = process.env.HERDR_SUBAGENTS_E2E_MODEL?.trim();
 const configurationPaths = {
 	globalConfig: join(root, "global-config.json"),
 	projectConfig: join(root, "project-config.json"),
@@ -94,7 +95,9 @@ async function waitForCleanup(result) {
 	}, `cleanup of ${result.tabId}`, 5_000);
 }
 
-async function runCase(label, names, concurrency, extensions = []) {
+async function runCase(label, names, concurrency, extraExtensions = []) {
+	const extensions = [...runtimePersona.extensions, ...extraExtensions];
+	writeFileSync(configurationPaths.globalConfig, JSON.stringify({ personas: { analyst: { ...runtimePersona, 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);
@@ -108,7 +111,6 @@ async function runCase(label, names, concurrency, extensions = []) {
 		tasks: names.map((name) => ({
 			name,
 			agent: "analyst",
-			...(model ? { model } : {}),
 			prompt: `Do not inspect files. Call subagent_report with status completed, summary '${name} completed', and result 'hello'.`,
 		})),
 	}, timeout, (update) => {
@@ -145,7 +147,8 @@ async function runCase(label, names, concurrency, extensions = []) {
 		const report = JSON.parse(readFileSync(join(taskResult.recordDirectory, "report.json"), "utf8"));
 		assert.equal(task.status, "completed");
 		assert.deepEqual(task.extensions, extensions);
-		if (extensions.length) {
+		if (runtimePersona.model) assert.equal(task.model, runtimePersona.model);
+		if (extraExtensions.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");
 		}
@@ -168,7 +171,6 @@ try {
 		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;