@maxiaochao/pi-toolkit 0.13.13 → 0.13.14

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2026-10-26 - v0.13.14
+
+- herdr-subagents v0.7.6: Esc in a child waits abortGraceSeconds (default 30) for a correction before publishing child_aborted
+
 ## 2026-10-26 - v0.13.13
 
 - background-tasks v0.1.2: restrict background tasks to model-only and use concise automatic-notification guidance

package/package.json

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

package/packages/herdr-subagents/ARCHITECTURE.md

@@ -82,7 +82,7 @@ There is no global dispatcher, persisted background queue, blocked response lane
 
 Each task owns one Herdr pane and one single-task Pi process. Herdr first starts and detects the interactive Pi, then submits the prompt exactly once. At Pi’s final `agent_settled` boundary, the child extension records settled state but leaves the interactive process alive. The atomic report remains the authoritative task result. Early-finishing children remain visible while sibling tasks continue. Once the whole run settles, the orchestrator closes an unfocused owned tab immediately and defers a focused tab until the user leaves it, so Pi can restore the terminal normally.
 
-A completed round without a terminal report gets one child-side reminder at `agent_before_settle`. The marker is written before continuation. Another omission publishes an unconfirmed `missing_report` diagnostic; final errors use `child_error`. Native cancellation skips that boundary, so `agent_settled` publishes only `child_aborted`, never a model wake-up. Existing terminal reports are not replaced. None of this adds a parent monitoring loop.
+A completed round without a terminal report gets one child-side reminder at `agent_before_settle`. The marker is written before continuation. Another omission publishes an unconfirmed `missing_report` diagnostic; final errors use `child_error`. A user abort (Esc) skips that boundary. `agent_settled(aborted)` starts a grace timer (`abortGraceSeconds`, default 30); a new round (`before_agent_start`) or session shutdown clears it, otherwise it publishes `child_aborted`. Existing terminal reports are not replaced. None of this adds a parent monitoring loop.
 
 The child writes:
 

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2026-10-26 - v0.7.6
+
+- Esc in a child waits abortGraceSeconds (default 30) for a correction before publishing child_aborted
+
 ## 2026-10-23 - v0.7.5
 
 - bound missing-report recovery and close unconfirmed child outcomes

package/packages/herdr-subagents/README.md

@@ -175,6 +175,7 @@ These are all supported top-level fields in `herdr-subagents.json`:
 | `defaultConcurrency` | Positive integer | `1` | Concurrency used when a call omits `concurrency`; capped to `maxConcurrency`. |
 | `maxConcurrency` | Positive integer | `4` | Hard ceiling for requested/default read-only concurrency. It does not make write-capable batches safe. |
 | `stalledWarningSeconds` | Positive integer | `300` | Emit a warning after a child runs this long. This is not a timeout and does not stop it. |
+| `abortGraceSeconds` | Positive integer | `30` | After the user aborts a child with Esc, wait this long for a correction. If no new round starts, publish an unconfirmed `child_aborted` failure. |
 | `defaultModel` | Non-empty Pi model ID, normally `provider/model` | Unset | Fallback child model. If unset, the parent model is inherited. |
 | `defaultThinking` | Non-empty Pi thinking value | Unset | Fallback thinking level below Persona-specific settings. Typical Pi values are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`; model support varies. |
 | `defaultExtensions` | Array of non-empty Pi source strings | Unset (no optional extensions) | Fallback extension sources for Personas without an explicit `extensions` list. Project replaces global; `[]` clears inherited defaults. |
@@ -219,6 +220,7 @@ Save this as `~/.pi/agent/herdr-subagents.json`. Model IDs, skills, and extensio
   "defaultConcurrency": 2,
   "maxConcurrency": 4,
   "stalledWarningSeconds": 300,
+  "abortGraceSeconds": 30,
   "defaultModel": "anthropic/claude-sonnet-4-5",
   "defaultThinking": "medium",
   "defaultExtensions": ["~/.pi/agent/extensions/provider-routing.ts"],
@@ -354,6 +356,6 @@ See [TESTING.md](TESTING.md) for deterministic tests, extension loading, packagi
 
 The child checks `reports/<attempt-id>.json` at `agent_before_settle`. A valid completed or failed report adds zero requests. A normally completed round without a report receives one reminder to submit existing results, not redo the task. `attempts/<attempt-id>.reminded` is persisted before continuing; rounds and reloads cannot reset it.
 
-A second omission produces a `failed` protocol report with `error: missing_report`, an explicitly **unconfirmed** result, and the child session path. This does not assert the delegated work itself failed. Final provider errors produce `child_error` without a reminder. Pi skips before-settle on cancellation; the child writes `child_aborted` at `agent_settled`, without waking the model or replacing an existing report. Parent-requested cancellation retains its existing cancelled lifecycle.
+A second omission produces a `failed` protocol report with `error: missing_report`, an explicitly **unconfirmed** result, and the child session path. This does not assert the delegated work itself failed. Final provider errors produce `child_error` without a reminder. A user abort (Esc) skips before-settle. The child waits `abortGraceSeconds` (default 30) for a correction; a new round cancels the timer and the child continues. If nothing starts in time, it publishes an unconfirmed `child_aborted` failure. Parent-requested cancellation retains its existing cancelled lifecycle.
 
 The parent still waits for an atomic attempt report or process exit. It does not infer success from idle/settled or run a second reminder monitor. Report idempotency and focus-aware tab cleanup are unchanged.

package/packages/herdr-subagents/TESTING.md

@@ -60,9 +60,9 @@ For real smoke testing, verify that each child appears in a visible pane and can
 
 ## Missing-report regressions
 
-`tests/report-boundary.mjs` checks completed/failed report idempotency, one durable reminder across rounds and extension reload, conflicting report rejection, unconfirmed diagnostics with a session path, and cancellation/error without continuation.
+`tests/report-boundary.mjs` checks completed/failed report idempotency, one durable reminder across rounds and extension reload, conflicting report rejection, unconfirmed diagnostics with a session path, Esc grace period (timer cancelled by steering or shutdown, `child_aborted` after expiry), and error without continuation.
 
-`tests/report-lifecycle.mjs` uses the real installed Pi SDK and a fully offline provider. It covers ten cases: normal report, failed report, successful reminder, repeated omission, transient retry, exhausted retry, queued follow-up, another before-settle continuation, cancellation, and a fresh prompt from a settled listener. A normal report makes one request; a reminder adds at most one. Native cancellation does not emit before-settle and must still get a terminal diagnostic. These are native lifecycle checks, not a claim of real-Herdr pane/concurrency coverage.
+`tests/report-lifecycle.mjs` uses the real installed Pi SDK and a fully offline provider. It covers ten cases: normal report, failed report, successful reminder, repeated omission, transient retry, exhausted retry, queued follow-up, another before-settle continuation, Esc abort, and a fresh prompt from a settled listener. A normal report makes one request; a reminder adds at most one. Native abort does not emit before-settle; its terminal diagnostic appears only after `abortGraceSeconds` (set to 1 in the test). These are native lifecycle checks, not a claim of real-Herdr pane/concurrency coverage.
 
 Use `PI_TEST_BINARY` to select Pi 1.4.0 for these checks rather than an older workspace-local Pi. No paid model or real credential is used by the new regression fixtures.
 

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

@@ -89,7 +89,7 @@ async function handleHerdrCommand(args: string, ctx: ExtensionCommandContext, fl
 	}
 	if (section === "settings") {
 		const settings = configuration.settings;
-		const values: Record<string, string | number | undefined> = { defaultConcurrency: settings.defaultConcurrency, maxConcurrency: settings.maxConcurrency, stalledWarningSeconds: settings.stalledWarningSeconds, defaultModel: settings.defaultModel, defaultThinking: settings.defaultThinking, defaultExtensions: JSON.stringify(settings.defaultExtensions ?? []) };
+		const values: Record<string, string | number | undefined> = { defaultConcurrency: settings.defaultConcurrency, maxConcurrency: settings.maxConcurrency, stalledWarningSeconds: settings.stalledWarningSeconds, abortGraceSeconds: settings.abortGraceSeconds, defaultModel: settings.defaultModel, defaultThinking: settings.defaultThinking, defaultExtensions: JSON.stringify(settings.defaultExtensions ?? []) };
 		const lines = [`exposure=${registeredExposure.value ?? "Pi default"} (${registeredExposure.source}; loaded at extension registration)`, ...Object.entries(values).map(([key, value]) => `${key}=${String(value ?? "unset")} (${configuration.settingSources[key] ?? "built-in"})`)];
 		if (configuration.diagnostics.length) lines.push("Diagnostics:", ...configuration.diagnostics);
 		ctx.ui.notify(lines.join("\n"), "info");

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

@@ -9,6 +9,10 @@ import { parseReport } from "../src/records.ts";
 import { resultPathForAttemptId } from "../src/result-path.ts";
 import { PARENT_PANE_ENV } from "../src/live-agent.ts";
 import { attemptReportPath, attemptStatePath, requireAttemptId, type AttemptState } from "../src/attempts.ts";
+import { loadSubagentConfiguration } from "../src/config.ts";
+import { fileURLToPath } from "node:url";
+
+const packageAgentsDir = fileURLToPath(new URL("../agents/", import.meta.url));
 
 const RETURN_SHORTCUT = "alt+p";
 
@@ -108,7 +112,10 @@ function reportHerdrState(state: "working" | "blocked" | "idle", message?: strin
 export default function (pi: ExtensionAPI) {
 	let activeAttemptId: string | undefined;
 	let blockedCount = 0;
+	let abortTimer: ReturnType<typeof setTimeout> | undefined;
+	const clearAbortTimer = () => { if (abortTimer) clearTimeout(abortTimer); abortTimer = undefined; };
 	pi.on("before_agent_start", async () => {
+		clearAbortTimer(); // The user steered the child after Esc.
 		const taskDirectory = process.env.PI_HERDR_SUBAGENTS_TASK_DIR?.trim();
 		if (!taskDirectory) return;
 		activeAttemptId = currentAttemptId(taskDirectory);
@@ -144,19 +151,25 @@ export default function (pi: ExtensionAPI) {
 				if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
 			}
 		}
-		const reason = event.outcome === "completed" ? "missing_report" : event.outcome === "aborted" ? "child_aborted" : "child_error";
+		// Esc normally skips this boundary; if it lands mid-boundary, still let the user steer.
+		if (event.outcome === "aborted") return;
+		const reason = event.outcome === "completed" ? "missing_report" : "child_error";
 		saveUnconfirmed(taskDirectory, attemptId, reason, ctx.sessionManager.getSessionFile());
-		// Cancellation and final provider errors receive a diagnostic, never a wake-up.
+		// Final provider errors receive a diagnostic, never a wake-up.
 	});
 	pi.on("agent_settled", (event, ctx) => {
 		const taskDirectory = process.env.PI_HERDR_SUBAGENTS_TASK_DIR?.trim();
-		if (taskDirectory && activeAttemptId) {
-			// Pi skips before-settle on cancellation. Close the protocol without
-			// claiming the work failed, replacing a report, or requesting more tokens.
-			if (event.aborted && !existsSync(attemptReportPath(taskDirectory, activeAttemptId))) {
-				saveUnconfirmed(taskDirectory, activeAttemptId, "child_aborted", ctx.sessionManager.getSessionFile());
-			}
-			writeAttemptState(taskDirectory, activeAttemptId, "settled");
+		if (event.aborted && taskDirectory && activeAttemptId) {
+			// Esc skips before-settle. Give the user time to steer; if nothing starts a new
+			// round within the grace period, close the attempt with an unconfirmed diagnostic.
+			const attemptId = activeAttemptId;
+			const sessionFile = ctx.sessionManager.getSessionFile();
+			const graceMs = loadSubagentConfiguration(ctx.cwd, packageAgentsDir).settings.abortGraceSeconds * 1000;
+			clearAbortTimer();
+			abortTimer = setTimeout(() => {
+				abortTimer = undefined;
+				if (!existsSync(attemptReportPath(taskDirectory, attemptId))) saveUnconfirmed(taskDirectory, attemptId, "child_aborted", sessionFile);
+			}, graceMs);
 		}
 		// Keep the interactive child alive at Pi's final automatic-work boundary.
 		// The orchestrator settles each task from its atomic report. Once every task in
@@ -176,6 +189,7 @@ export default function (pi: ExtensionAPI) {
 		description: "Return to parent Agent",
 		async handler(ctx) { await returnToParent(pi, ctx); },
 	});
+	pi.on("session_shutdown", clearAbortTimer);
 	pi.on("session_start", async (_event, ctx) => {
 		// Remove the legacy hint on reload without touching editor/plugin status.
 		ctx.ui.setStatus("herdr-subagents-parent", undefined);

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [

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

@@ -11,6 +11,7 @@ export interface SubagentConfig {
 	defaultConcurrency: number;
 	maxConcurrency: number;
 	stalledWarningSeconds: number;
+	abortGraceSeconds: number;
 	defaultModel?: string;
 	defaultThinking?: string;
 	defaultExtensions?: string[];
@@ -39,6 +40,7 @@ interface ConfigFile {
 	defaultConcurrency?: number;
 	maxConcurrency?: number;
 	stalledWarningSeconds?: number;
+	abortGraceSeconds?: number;
 	defaultModel?: string;
 	defaultThinking?: string;
 	defaultExtensions?: string[];
@@ -50,7 +52,7 @@ export interface ConfigurationPaths {
 	globalAgents?: string;
 	projectAgents?: string;
 }
-const DEFAULTS: SubagentConfig = { defaultConcurrency: 1, maxConcurrency: 4, stalledWarningSeconds: 300, personas: {} };
+const DEFAULTS: SubagentConfig = { defaultConcurrency: 1, maxConcurrency: 4, stalledWarningSeconds: 300, abortGraceSeconds: 30, personas: {} };
 
 function readConfig(path: string, source: string, diagnostics: string[]): ConfigFile {
 	if (!existsSync(path)) return {};
@@ -70,7 +72,7 @@ function mergeConfig(base: SubagentConfig, input: ConfigFile, source: string, so
 		if (input.exposure === "direct" || input.exposure === "model-only") { result.exposure = input.exposure; sources.exposure = source; }
 		else diagnostics.push(`${source} exposure must be 'direct' or 'model-only'`);
 	}
-	for (const key of ["defaultConcurrency", "maxConcurrency", "stalledWarningSeconds"] as const) {
+	for (const key of ["defaultConcurrency", "maxConcurrency", "stalledWarningSeconds", "abortGraceSeconds"] as const) {
 		const value = input[key];
 		if (value === undefined) continue;
 		if (!Number.isInteger(value) || Number(value) <= 0) { diagnostics.push(`${source} ${key} must be a positive integer`); continue; }
@@ -121,7 +123,7 @@ export function loadSubagentConfiguration(cwd: string, packageAgentsDirectory: s
 	const projectConfigPath = paths.projectConfig ?? join(cwd, ".pi", "herdr-subagents.json");
 	const globalAgentsDirectory = paths.globalAgents ?? join(dirname(globalConfigPath), "herdr-subagents", "agents");
 	const projectAgentsDirectory = paths.projectAgents ?? join(cwd, ".pi", "herdr-subagents", "agents");
-	const settingSources: Record<string, string> = { defaultConcurrency: "built-in", maxConcurrency: "built-in", stalledWarningSeconds: "built-in" };
+	const settingSources: Record<string, string> = { defaultConcurrency: "built-in", maxConcurrency: "built-in", stalledWarningSeconds: "built-in", abortGraceSeconds: "built-in" };
 	const globalInput = readConfig(globalConfigPath, "global", diagnostics);
 	const projectInput = readConfig(projectConfigPath, "project", diagnostics);
 	const globalSettings = mergeConfig(DEFAULTS, globalInput, "global", settingSources, diagnostics);

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

@@ -357,8 +357,6 @@ assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are im
 		process.exit = originalExit;
 	}
 	assert.equal(exitCode, undefined, "settled child must remain alive for focus-aware tab cleanup");
-	const attempt = JSON.parse(readFileSync(join(directory, "attempts", `${attemptId}.json`), "utf8"));
-	assert.equal(attempt.state, "settled");
 	const theme = { fg: (_color, text) => text, bold: (text) => text };
 	const renderedCall = reportTool.renderCall({ ...report, result: "FULL RESULT MUST NOT RENDER" }, theme).render(120).join("\n");
 	assert.match(renderedCall, /completed.*saved to disk/);

package/packages/herdr-subagents/tests/report-boundary.mjs

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { mkdirSync } from "node:fs";
 import registerReport from "../extensions/subagent-report.ts";
 
 const root = mkdtempSync(join(tmpdir(), "herdr-report-boundary-"));
@@ -10,7 +11,9 @@ const previous = process.env.PI_HERDR_SUBAGENTS_TASK_DIR;
 process.env.PI_HERDR_SUBAGENTS_TASK_DIR = root;
 const sessionFile = join(root, "session.jsonl");
 writeFileSync(sessionFile, "");
-const ctx = { sessionManager: { getSessionFile: () => sessionFile }, isIdle: () => true };
+mkdirSync(join(root, ".pi"));
+writeFileSync(join(root, ".pi", "herdr-subagents.json"), JSON.stringify({ abortGraceSeconds: 1 }));
+const ctx = { cwd: root, sessionManager: { getSessionFile: () => sessionFile }, isIdle: () => true };
 function fixture() {
   const handlers = new Map();
   let tool;
@@ -58,14 +61,44 @@ try {
   assert.ok(diagnostic.documents.some(({ path }) => path === sessionFile));
   assert.equal(await reloaded.handlers.get("agent_before_settle")(boundary(), ctx), undefined);
 
-  for (const outcome of ["aborted", "error"]) {
+  {
     const current = attempt();
     const run = fixture();
     await run.handlers.get("before_agent_start")();
-    assert.equal(await run.handlers.get("agent_before_settle")(boundary(outcome), ctx), undefined, `${outcome}: do not wake or retry the child`);
+    assert.equal(await run.handlers.get("agent_before_settle")(boundary("aborted"), ctx), undefined);
+    assert.equal(existsSync(current.report), false, "Esc abort must not publish a terminal report; the user may steer");
+  }
+  {
+    // Esc skips before-settle and only emits agent_settled(aborted). Grace period, configurable.
+    const current = attempt();
+    const run = fixture();
+    await run.handlers.get("before_agent_start")();
+    await run.handlers.get("agent_settled")({ aborted: true }, ctx);
+    assert.equal(existsSync(current.report), false, "no report inside the grace period");
+    await run.handlers.get("before_agent_start")(); // user steers: timer must be cancelled
+    await new Promise((resolve) => setTimeout(resolve, 1300));
+    assert.equal(existsSync(current.report), false, "steering within the grace period cancels the diagnostic");
+    await run.handlers.get("agent_settled")({ aborted: true }, ctx);
+    await new Promise((resolve) => setTimeout(resolve, 1300));
+    const report = JSON.parse(readFileSync(current.report, "utf8"));
+    assert.equal(report.error, "child_aborted");
+    assert.match(report.summary, /unconfirmed/);
+    const shutdown = fixture(); // shutdown must clear a pending timer
+    const other = attempt();
+    await shutdown.handlers.get("before_agent_start")();
+    await shutdown.handlers.get("agent_settled")({ aborted: true }, ctx);
+    shutdown.handlers.get("session_shutdown")();
+    await new Promise((resolve) => setTimeout(resolve, 1300));
+    assert.equal(existsSync(other.report), false, "session shutdown clears the grace timer");
+  }
+  {
+    const current = attempt();
+    const run = fixture();
+    await run.handlers.get("before_agent_start")();
+    assert.equal(await run.handlers.get("agent_before_settle")(boundary("error"), ctx), undefined, "error: do not wake or retry the child");
     const report = JSON.parse(readFileSync(current.report, "utf8"));
     assert.equal(report.status, "failed");
-    assert.equal(report.error, outcome === "aborted" ? "child_aborted" : "child_error");
+    assert.equal(report.error, "child_error");
     assert.match(report.summary, /unconfirmed/);
   }
   const repaired = attempt();

package/packages/herdr-subagents/tests/report-lifecycle.mjs

@@ -18,6 +18,7 @@ try{
   const dir=join(root,scenario);mkdirSync(dir);
   const attemptId=randomUUID();const statePath=join(dir,'attempts',attemptId+'.json');
   process.env.PI_HERDR_SUBAGENTS_TASK_DIR=dir;
+  if(scenario==='abort'){mkdirSync(join(dir,'.pi'));writeFileSync(join(dir,'.pi','herdr-subagents.json'),JSON.stringify({abortGraceSeconds:1}));}
   writeFileSync(join(dir,'task.json'),JSON.stringify({currentAttemptId:attemptId}));
   const trace=[],states=[],errors=[],inputs=[];let requests=0,ended=0,boundaries=0,settled=0;
   const entered=Promise.withResolvers();let session;
@@ -52,6 +53,7 @@ try{
    const running=session.prompt('Run offline lifecycle check');
    if(scenario==='abort'){await entered.promise;await session.abort();}
    await running;
+   if(scenario==='abort'){assert.equal(existsSync(join(dir,'reports',attemptId+'.json')),false,'no report inside the grace period');await new Promise(r=>setTimeout(r,1500));}
    assert.equal(errors.length,0,JSON.stringify(errors));
    const expectedRequests={reported:1,failed_report:1,remind_success:2,normal_no_report:2,transient_retry:3,retry_exhausted:2,queued_followup:3,boundary_continue:2,abort:1,settled_hook_new_prompt:3}[scenario];
    assert.equal(requests,expectedRequests,scenario);