@maxiaochao/pi-toolkit 0.11.3 → 0.11.4

package/CHANGELOG.md

@@ -1,9 +1,15 @@
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.11.3",
+  "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,6 +1,9 @@
-## Unreleased
+## 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
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.4.12",
+  "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

@@ -134,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)) {
@@ -144,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.");
@@ -160,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/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

@@ -495,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);