@maxiaochao/pi-toolkit 0.11.1 → 0.11.4

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## 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
+
+## 2026-10-12 - v0.11.3
+
+- harden coordinated publishing and make local release checks authoritative
+
+## Unreleased
+
+- 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.
+
+## 2026-10-12 - v0.11.2
+
+- bundle herdr-subagents v0.4.12: enable codemode for child agents while preserving persona tool boundaries
+- Enable `codemode` for bundled Herdr Subagents children while preserving persona tool boundaries.
+
 ## 2026-10-12 - v0.11.1
 
 - bundle herdr-subagents v0.4.11: add architecture documentation and clear-output guidance evaluation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.11.1",
+  "version": "0.11.4",
   "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,15 @@
+## 2026-10-12 - v0.4.13
+
+- fix stale-idle child startup race and require real Herdr E2E release smoke
+- Make lifecycle tests accept both valid report-first and observation-first execution orderings.
+- Fix child startup being mistaken for completion when `before_agent_start` records the attempt as working before Herdr leaves its stale idle state.
+- Add mandatory real-Herdr single-Agent and concurrent batch smoke tests to the Herdr Subagents release gate.
+
+## 2026-10-12 - v0.4.12
+
+- enable codemode for child agents while preserving persona tool boundaries
+- Enable `codemode` for every child Pi while preserving each persona's existing tool allowlist and read/write boundary.
+
 ## 2026-10-12 - v0.4.11
 
 - add architecture documentation and clear-output guidance evaluation

package/packages/herdr-subagents/README.md

@@ -172,6 +172,8 @@ Each `personas.<name>` object supports exactly these overrides:
 
 JSON persona overrides cannot change `name`, `description`, `access`, `tools`, or the system prompt; define those in persona Markdown.
 
+Every child Pi explicitly loads and enables `codemode`. Built-in personas include it in their tool allowlists. Custom personas may omit `tools` and inherit Pi's defaults plus `codemode`, or list `codemode` explicitly alongside their allowed tools. A read-only persona remains read-only because codemode can call only the tools enabled for that child session.
+
 A global configuration can establish shared defaults:
 
 ```json

package/packages/herdr-subagents/TESTING.md

@@ -4,9 +4,10 @@
 
 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 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.
-4. `npm pack ./packages/herdr-subagents --dry-run` verifies package contents.
-5. 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.
+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.
+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.
 
 ## Cases
 
@@ -45,4 +46,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. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed a read-only package inspection with matching durable attempt/report IDs and automatic tab cleanup.
+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.

package/packages/herdr-subagents/agents/analyst.md

@@ -2,7 +2,7 @@
 name: analyst
 description: Neutral read-only analyst for dynamically assigned roles
 access: read
-tools: read, bash, grep, find, ls
+tools: read, bash, grep, find, ls, codemode
 ---
 
 Act as an independent analyst and follow the role and evaluation method in the task prompt. Do not modify project files. Separate direct evidence, inference, and unknowns, and report concrete evidence with useful paths.

package/packages/herdr-subagents/agents/explorer.md

@@ -2,7 +2,7 @@
 name: explorer
 description: Read-only explorer for fast codebase investigation
 access: read
-tools: read, bash, grep, find, ls
+tools: read, bash, grep, find, ls, codemode
 ---
 
 Investigate the assigned question without modifying files. Report concrete evidence and useful paths.

package/packages/herdr-subagents/agents/reviewer.md

@@ -2,7 +2,7 @@
 name: reviewer
 description: Read-only reviewer for correctness and maintainability risks
 access: read
-tools: read, bash, grep, find, ls
+tools: read, bash, grep, find, ls, codemode
 ---
 
 Review the assigned work without modifying files. Report actionable findings with concrete evidence.

package/packages/herdr-subagents/agents/worker.md

@@ -2,7 +2,7 @@
 name: worker
 description: General-purpose worker for one focused task
 access: write
-tools: read, bash, edit, write, grep, find, ls
+tools: read, bash, edit, write, grep, find, ls, codemode
 ---
 
 You are a focused worker subagent.

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [
@@ -38,6 +38,7 @@
   },
   "scripts": {
     "test": "node --experimental-strip-types tests/run-tests.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"
   },
   "publishConfig": {

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

@@ -36,13 +36,15 @@ export function childPiArgs(task: LiveTaskRecord, systemPromptFile: string): str
 		"--session", task.sessionFile,
 		"--name", `Subagent: ${task.name ?? task.agent ?? "worker"}`,
 		"--no-extensions",
+		"--extension", "builtin:codemode",
 		"--extension", fileURLToPath(new URL("../extensions/subagent-report.ts", import.meta.url)),
 		"--no-skills",
 		"--append-system-prompt", systemPromptFile,
 	];
 	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, "subagent_report"])].join(","));
+	if (task.tools?.length) args.push("--tools", [...new Set([...task.tools, "codemode", "subagent_report"])].join(","));
+	else args.push("--tools", "+codemode");
 	for (const skill of task.skills ?? []) args.push("--skill", skill);
 	return args;
 }
@@ -132,7 +134,6 @@ export async function promptLiveAgent(options: {
 	});
 	const stalledTimer = options.stalledWarningMs ? setTimeout(() => options.onStalled?.(), options.stalledWarningMs) : undefined;
 	let terminalObservedAt: number | undefined;
-	let turnObserved = false;
 	try {
 		await persistRuntime("working");
 		while (!existsSync(attemptReportFile)) {
@@ -142,7 +143,6 @@ export async function promptLiveAgent(options: {
 			try { agentState = await options.herdr.getAgentState(agentName, options.signal); }
 			catch (error) { observationDiagnostic = `Could not observe Herdr agent state: ${error instanceof Error ? error.message : String(error)}`; }
 			const attemptState = await readAttemptState();
-			if (agentState === "working" || agentState === "blocked" || attemptState === "working") turnObserved = true;
 			const promptDetail = promptError instanceof Error ? promptError.message : promptError === undefined ? "" : String(promptError);
 			if (agentState === "blocked" || /agent_blocked/i.test(promptDetail)) {
 				await persistRuntime("waiting_interaction", observationDiagnostic ?? "Herdr is waiting for an approval or interaction; no business input request has been reported.");
@@ -158,7 +158,7 @@ export async function promptLiveAgent(options: {
 			} else if (promptError && promptSettled) {
 				terminalObservedAt ??= Date.now();
 				if (Date.now() - terminalObservedAt >= 50) throw promptError;
-			} else if ((promptSettled || turnObserved || attemptState === "settled") && (agentState === "idle" || agentState === "done" || attemptState === "settled")) {
+			} else if ((promptSettled || attemptState === "settled") && (agentState === "idle" || agentState === "done" || attemptState === "settled")) {
 				if (attemptState === "working") {
 					let live = false;
 					try { live = await options.herdr.isTaskRunning(options.paneId, options.signal); } catch { live = true; }

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

@@ -10,6 +10,7 @@ export const BUILTIN_TOOLS = new Set([
 	"find",
 	"ls",
 	"powershell",
+	"codemode",
 ]);
 
 export interface AgentDefinition {

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

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { executeHerdrSubagents } from "../src/tool.ts";
+import { CliHerdrAutomation } from "../src/herdr.ts";
+
+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 root = mkdtempSync(join(tmpdir(), "pi-herdr-subagents-real-"));
+const herdr = new CliHerdrAutomation();
+const tabIds = new Set();
+const model = process.env.HERDR_SUBAGENTS_E2E_MODEL?.trim();
+const configurationPaths = {
+	globalConfig: join(root, "global-config.json"),
+	projectConfig: join(root, "project-config.json"),
+	globalAgents: join(root, "global-agents"),
+	projectAgents: join(root, "project-agents"),
+};
+const timeout = AbortSignal.timeout(120_000);
+
+function hasAssistantMessage(path) {
+	return readFileSync(path, "utf8").split("\n").filter(Boolean).some((line) => {
+		try { return JSON.parse(line)?.message?.role === "assistant"; }
+		catch { return false; }
+	});
+}
+
+async function runCase(label, names, concurrency) {
+	const response = await executeHerdrSubagents({
+		label,
+		concurrency,
+		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) => {
+		if (update.details?.tabId) tabIds.add(update.details.tabId);
+	}, { cwd: root }, {
+		agentsDirectory: join(packageDirectory, "agents"),
+		configurationPaths,
+		herdr,
+	});
+
+	const result = response.details;
+	if (result?.tabId) tabIds.add(result.tabId);
+	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);
+
+	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.equal(report.status, "completed");
+		assert.equal(report.attemptId, task.currentAttemptId);
+		assert.equal(hasAssistantMessage(task.sessionFile), true, `${taskResult.name} produced no assistant event`);
+		assert.equal(await herdr.paneExists(task.paneId), false, `${taskResult.name} pane survived tab cleanup`);
+	}
+	console.log(`PASS ${label}: ${names.length} real child Agent${names.length === 1 ? "" : "s"} completed and cleaned up`);
+}
+
+try {
+	await runCase("real-single", ["hello-single"], 1);
+	await runCase("real-concurrent", ["hello-one", "hello-two"], 2);
+} finally {
+	for (const tabId of tabIds) await herdr.closeTab(tabId).catch(() => undefined);
+	rmSync(root, { recursive: true, force: true });
+}

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

@@ -24,6 +24,7 @@ import { RunPaneAllocator } from "../src/run-pane-allocator.ts";
 import { aggregateTaskStatus } from "../src/run-status.ts";
 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";
 
 /** Drives one task through the batch runner and projects its single result like a task-scoped run. */
@@ -457,13 +458,13 @@ try {
 		herdr,
 	});
 	check("compact successful report", success.ok && success.status === "completed" && success.summary === "Authentication review completed." && success.documents.length === 1 && !success.output.includes("FULL RESULT"));
-	check("Herdr lifecycle", herdr.calls.map(([name]) => name).join(",") === "createTab,renamePane,startAgent,promptAgent,getAgentState,isTabFocused,closeTab");
+	check("Herdr lifecycle", herdr.calls.map(([name]) => name).filter((name) => name !== "getAgentState").join(",") === "createTab,renamePane,startAgent,promptAgent,isTabFocused,closeTab");
 	const createRequest = herdr.calls.find(([name]) => name === "createTab")[1];
 	const startRequest = herdr.calls.find(([name]) => name === "startAgent")[1];
 	check("named unfocused tab in parent workspace", createRequest.workspaceId === "w1" && createRequest.cwd === root && createRequest.label === "SA · auth-review" && createRequest.focus === false);
 	check("ordinary execution never steals pane focus", !herdr.calls.some(([name]) => name === "focusPane"));
 	check("child environment points at durable task and parent pane", createRequest.env.PI_HERDR_SUBAGENTS_CHILD === "1" && createRequest.env.PI_HERDR_SUBAGENTS_TASK_DIR.includes(join(".pi", "herdr-subagents", "runs")) && createRequest.env.PI_HERDR_SUBAGENTS_PARENT_PANE_ID === "w1:p-parent");
-	check("persistent isolated child Pi", startRequest.kind === "pi" && startRequest.paneId === "w1:p2" && startRequest.args.includes("--session") && startRequest.args.includes("--no-extensions") && startRequest.args.includes("--extension") && startRequest.args.includes("--no-skills") && startRequest.args.includes("--model") && startRequest.args.includes("fake/model") && startRequest.args.includes("--tools") && startRequest.args.includes("read,grep,subagent_report"));
+	check("persistent isolated child Pi", startRequest.kind === "pi" && startRequest.paneId === "w1:p2" && startRequest.args.includes("--session") && startRequest.args.includes("--no-extensions") && startRequest.args.includes("builtin:codemode") && startRequest.args.includes("--extension") && startRequest.args.includes("--no-skills") && startRequest.args.includes("--model") && startRequest.args.includes("fake/model") && startRequest.args.includes("--tools") && startRequest.args.includes("read,grep,codemode,subagent_report"));
 	const promptRequest = herdr.calls.find(([name]) => name === "promptAgent")[1];
 	check("prompt submitted through Herdr", promptRequest.prompt === "Review authentication" && promptRequest.target === startRequest.name);
 
@@ -480,7 +481,7 @@ try {
 		model: { provider: "fake", id: "model" },
 		thinkingLevel: "medium",
 	}, { agentsDirectory: join(process.cwd(), "agents"), herdr: extensionHerdr });
-	check("public extension behavior uses injectable Herdr", !publicResult.isError && publicResult.content[0].text.includes("Authentication review completed.") && !publicResult.content[0].text.includes("FULL RESULT") && extensionHerdr.calls.map(([name]) => name).join(",") === "createTab,renamePane,startAgent,promptAgent,getAgentState,isTabFocused,closeTab", JSON.stringify({ publicResult, calls: extensionHerdr.calls.map(([name]) => name) }));
+	check("public extension behavior uses injectable Herdr", !publicResult.isError && publicResult.content[0].text.includes("Authentication review completed.") && !publicResult.content[0].text.includes("FULL RESULT") && extensionHerdr.calls.map(([name]) => name).filter((name) => name !== "getAgentState").join(",") === "createTab,renamePane,startAgent,promptAgent,isTabFocused,closeTab", JSON.stringify({ publicResult, calls: extensionHerdr.calls.map(([name]) => name) }));
 	let singleStalledWarning = "";
 	await runSingleTask("single slow task", { cwd: root, herdr: fakeHerdr(), stalledWarningSeconds: 0.001, onStalled: (message) => { singleStalledWarning = message; } });
 	check("single-task execution emits configured stalled warning", singleStalledWarning.includes("appears stalled"));
@@ -494,8 +495,18 @@ try {
 	check("missing report is visible failure", !silent.ok && silent.errorMessage?.includes("did not submit") && silentHerdr.calls.at(-1)[0] === "closeTab");
 	const initialIdleHerdr = fakeHerdr();
 	const initialIdlePrompt = initialIdleHerdr.promptAgent.bind(initialIdleHerdr);
+	const initialIdleStart = initialIdleHerdr.startAgent.bind(initialIdleHerdr);
+	let initialIdleDirectory;
+	initialIdleHerdr.startAgent = async (request) => {
+		const sessionIndex = request.args.indexOf("--session");
+		initialIdleDirectory = join(request.args[sessionIndex + 1], "..");
+		return initialIdleStart(request);
+	};
 	let initialIdleAccepted = false;
 	initialIdleHerdr.promptAgent = async (request) => {
+		const task = JSON.parse(readFileSync(join(initialIdleDirectory, "task.json"), "utf8"));
+		mkdirSync(join(initialIdleDirectory, "attempts"), { recursive: true });
+		writeFileSync(join(initialIdleDirectory, "attempts", `${task.currentAttemptId}.json`), JSON.stringify({ attemptId: task.currentAttemptId, state: "working" }));
 		await new Promise((resolve) => setTimeout(resolve, 150));
 		initialIdleAccepted = true;
 		return initialIdlePrompt(request);
@@ -570,6 +581,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 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");
+	check("child Pi enables codemode with an explicit tool allowlist", explicitToolArgs.includes("builtin:codemode") && explicitToolArgs.includes("read,codemode,subagent_report"));
 	const agentsDir = join(root, "agents");
 	await import("node:fs/promises").then(({ mkdir }) => mkdir(agentsDir));
 	writeFileSync(join(agentsDir, "worker.md"), `---\nname: worker\ndescription: Worker\n---\nDo work.`);
@@ -578,7 +593,7 @@ try {
 	check("persona discovery and diagnostics", discovery.agents.length === 1 && discovery.agents[0].name === "worker" && discovery.diagnostics.length === 1);
 	const packageDiscovery = discoverPackageAgents(join(process.cwd(), "agents"));
 	const analystPersona = packageDiscovery.agents.find((persona) => persona.name === "analyst");
-	check("built-in analyst is neutral and read-only", packageDiscovery.diagnostics.length === 0 && analystPersona?.access === "read" && analystPersona.model === undefined && analystPersona.tools?.join(",") === "read,bash,grep,find,ls" && /independent analyst/.test(analystPersona.systemPrompt) && /direct evidence, inference, and unknowns/.test(analystPersona.systemPrompt) && !/auditor|replicator|adversary/.test(analystPersona.systemPrompt));
+	check("built-in analyst is neutral and read-only", packageDiscovery.diagnostics.length === 0 && analystPersona?.access === "read" && analystPersona.model === undefined && analystPersona.tools?.join(",") === "read,bash,grep,find,ls,codemode" && /independent analyst/.test(analystPersona.systemPrompt) && /direct evidence, inference, and unknowns/.test(analystPersona.systemPrompt) && !/auditor|replicator|adversary/.test(analystPersona.systemPrompt));
 
 	const configRoot = join(root, "configuration");
 	const packageAgents = join(configRoot, "package-agents");