@maxiaochao/pi-toolkit 0.9.4 → 0.10.0

package/packages/codex-edit/tests/legacy-parser-v0.1.7.mjs

@@ -0,0 +1,128 @@
+// Frozen semantic baseline from @maxiaochao/pi-codex-edit v0.1.7.
+// Source blob: codex-edit-v0.1.7:packages/codex-edit/src/parser.ts
+// Git blob ID: e2896b59d40b5f6f01b3a4a7918476f4acc28cd8
+// Keep this file unchanged; add cases to comparison-cases.mjs instead.
+
+export function parseLegacyPatch(patch) {
+  const lines = patch.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim().split("\n");
+  if (lines[0]?.trim() !== "*** Begin Patch") throw new Error("The first line of the patch must be '*** Begin Patch'");
+  if (lines.at(-1)?.trim() !== "*** End Patch") throw new Error("The last line of the patch must be '*** End Patch'");
+  const operations = [];
+  let index = 1;
+  while (index < lines.length - 1) {
+    const line = lines[index];
+    if (line.startsWith("*** Add File: ")) {
+      const path = line.slice("*** Add File: ".length);
+      index += 1;
+      const content = [];
+      while (index < lines.length - 1 && !lines[index].startsWith("*** ")) {
+        if (!lines[index].startsWith("+")) throw new Error(`Invalid add line ${index + 1}`);
+        content.push(lines[index].slice(1));
+        index += 1;
+      }
+      if (content.length === 0) throw new Error(`Add file hunk for path '${path}' is empty`);
+      operations.push({ action: "add", path, content: `${content.join("\n")}\n` });
+      continue;
+    }
+    if (line.startsWith("*** Delete File: ")) {
+      const path = line.slice("*** Delete File: ".length);
+      if (!path) throw new Error(`Delete file hunk on line ${index + 1} has an empty path`);
+      operations.push({ action: "delete", path });
+      index += 1;
+      continue;
+    }
+    if (line.startsWith("*** Update File: ")) {
+      const path = line.slice("*** Update File: ".length);
+      index += 1;
+      let moveTo;
+      if (lines[index]?.startsWith("*** Move to: ")) {
+        moveTo = lines[index].slice("*** Move to: ".length);
+        index += 1;
+      }
+      const chunks = [];
+      while (index < lines.length - 1 && !lines[index].startsWith("*** ")) {
+        let context;
+        if (lines[index] === "@@" || lines[index].startsWith("@@ ")) {
+          context = lines[index].slice(2).trim() || undefined;
+          index += 1;
+        }
+        const oldLines = [];
+        const newLines = [];
+        const contextLineIndices = [];
+        while (index < lines.length - 1 && !lines[index].startsWith("*** ") && !lines[index].startsWith("@@")) {
+          const change = lines[index];
+          const marker = change[0];
+          if (!["+", "-", " "].includes(marker)) throw new Error(`Invalid update line ${index + 1}`);
+          const text = change.slice(1);
+          if (marker === "+") newLines.push(text);
+          else if (marker === "-") oldLines.push(text);
+          else {
+            contextLineIndices.push([oldLines.length, newLines.length]);
+            oldLines.push(text);
+            newLines.push(text);
+          }
+          index += 1;
+        }
+        const endOfFile = lines[index] === "*** End of File";
+        if (endOfFile) index += 1;
+        if (oldLines.length === 0 && newLines.length === 0) throw new Error(`Empty update chunk on line ${index + 1}`);
+        chunks.push({ context, oldLines, newLines, contextLineIndices, endOfFile });
+      }
+      if (chunks.length === 0) throw new Error(`Update file hunk for path '${path}' is empty`);
+      operations.push({ action: "update", path, moveTo, chunks });
+      continue;
+    }
+    throw new Error(`Invalid hunk header on line ${index + 1}: ${line}`);
+  }
+  if (operations.length === 0) throw new Error("Patch contains no file operations");
+  const targets = operations.flatMap((operation) => [operation.path, operation.moveTo].filter(Boolean));
+  if (new Set(targets).size !== targets.length) throw new Error("Multiple operations target the same path");
+  return operations;
+}
+
+function findCandidates(lines, pattern, start, eof, compare) {
+  const candidates = [];
+  for (let index = start; index + pattern.length <= lines.length; index += 1) {
+    if (pattern.every((line, offset) => compare(lines[index + offset], line))) candidates.push(index);
+  }
+  candidates.sort((left, right) => eof ? right - left : left - right);
+  return candidates;
+}
+
+function locate(lines, pattern, start, eof, label) {
+  if (pattern.length === 0) return Math.min(start, lines.length);
+  const comparisons = [
+    (left, right) => left === right,
+    (left, right) => left.trimEnd() === right.trimEnd(),
+    (left, right) => left.trim() === right.trim(),
+  ];
+  for (const compare of comparisons) {
+    const candidates = findCandidates(lines, pattern, start, eof, compare);
+    if (candidates.length > 0) return candidates[0];
+  }
+  throw new Error(`Failed to find expected lines${label ? ` in ${label}` : ""}: ${pattern.join("\\n")}`);
+}
+
+export function applyLegacyUpdate(content, chunks, path) {
+  const bom = content.startsWith("\ufeff") ? "\ufeff" : "";
+  const withoutBom = bom ? content.slice(1) : content;
+  const ending = withoutBom.includes("\r\n") ? "\r\n" : "\n";
+  const normalized = withoutBom.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const hadFinalNewline = normalized.endsWith("\n");
+  const lines = normalized === "" ? [] : normalized.split("\n");
+  if (hadFinalNewline) lines.pop();
+  const replacements = [];
+  let cursor = 0;
+  for (const chunk of chunks) {
+    if (chunk.context !== undefined) cursor = locate(lines, [chunk.context], cursor, false, path) + 1;
+    const start = locate(lines, chunk.oldLines, cursor, chunk.endOfFile, path);
+    replacements.push({ start, length: chunk.oldLines.length, next: chunk.newLines });
+    cursor = start + chunk.oldLines.length;
+  }
+  const output = [...lines];
+  for (const replacement of [...replacements].reverse()) output.splice(replacement.start, replacement.length, ...replacement.next);
+  let next = output.join("\n");
+  if (hadFinalNewline || next.length > 0) next += "\n";
+  if (ending === "\r\n") next = next.replace(/\n/g, "\r\n");
+  return bom + next;
+}

package/packages/codex-edit/tests/native-vs-codex.ts

@@ -0,0 +1,109 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { createEditToolDefinition } from "@earendil-works/pi-coding-agent";
+import registerCodexEdit from "../extensions/codex-edit.ts";
+import { comparisonCases } from "./comparison-cases.mjs";
+
+async function writeSnapshot(root, snapshot) {
+  for (const [path, content] of Object.entries(snapshot)) {
+    const absolute = join(root, path);
+    await mkdir(dirname(absolute), { recursive: true });
+    await writeFile(absolute, content, "utf8");
+  }
+}
+
+async function readSnapshot(root, relative = "") {
+  const snapshot = {};
+  for (const entry of await readdir(join(root, relative), { withFileTypes: true })) {
+    const path = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) Object.assign(snapshot, await readSnapshot(root, path));
+    else snapshot[path] = await readFile(join(root, path), "utf8");
+  }
+  return snapshot;
+}
+
+async function runNativeCase(testCase) {
+  if (testCase.outcomes.native === "unsupported") {
+    assert.equal(testCase.nativeCalls, null, `${testCase.id}: unsupported native case must not invent edit calls`);
+    return "unsupported";
+  }
+  const workspace = await mkdtemp(join(tmpdir(), "codex-edit-native-"));
+  try {
+    await writeSnapshot(workspace, testCase.input);
+    const edit = createEditToolDefinition(workspace);
+    try {
+      for (const [index, call] of testCase.nativeCalls.entries()) {
+        await edit.execute(`native-${index}`, call, undefined, undefined, { cwd: workspace });
+      }
+      if (testCase.outcomes.native !== "pass") {
+        assert.fail(`${testCase.id}: native edit unexpectedly succeeded`);
+      }
+      assert.deepEqual(await readSnapshot(workspace), testCase.expected);
+      return "pass";
+    } catch (error) {
+      if (testCase.outcomes.native === "pass") throw error;
+      return "fail";
+    }
+  } finally {
+    await rm(workspace, { recursive: true, force: true });
+  }
+}
+
+async function getCodexTool() {
+  let tool;
+  await registerCodexEdit({
+    registerTool(definition) { tool = definition; },
+    on() {},
+    getActiveTools() { return []; },
+  });
+  assert.ok(tool, "Codex Edit extension did not register apply_patch");
+  return tool;
+}
+
+async function runCodexCase(tool, testCase) {
+  const workspace = await mkdtemp(join(tmpdir(), "codex-edit-local-"));
+  try {
+    await writeSnapshot(workspace, testCase.input);
+    try {
+      await tool.execute("codex-local", { patch: testCase.patch }, undefined, undefined, {
+        cwd: workspace,
+        hasUI: false,
+      });
+      if (testCase.outcomes.local !== "pass") {
+        assert.fail(`${testCase.id}: local Codex Edit unexpectedly succeeded`);
+      }
+      assert.deepEqual(await readSnapshot(workspace), testCase.expected);
+      return "pass";
+    } catch (error) {
+      if (testCase.outcomes.local === "pass") throw error;
+      assert.deepEqual(
+        await readSnapshot(workspace),
+        testCase.input,
+        `${testCase.id}: failed Codex patch must not partially mutate the workspace`,
+      );
+      return "fail";
+    }
+  } finally {
+    await rm(workspace, { recursive: true, force: true });
+  }
+}
+
+export default async function () {
+  const codexTool = await getCodexTool();
+  const results = [];
+  for (const testCase of comparisonCases) {
+    const native = await runNativeCase(testCase);
+    const codex = await runCodexCase(codexTool, testCase);
+    results.push({ id: testCase.id, native, codex });
+  }
+  assert.equal(results.length, comparisonCases.length);
+  assert.equal(results.filter(({ native }) => native === "pass").length, 5);
+  assert.equal(results.filter(({ native }) => native === "fail").length, 2);
+  assert.equal(results.filter(({ native }) => native === "unsupported").length, 5);
+  assert.equal(results.filter(({ codex }) => codex === "pass").length, 7);
+  assert.equal(results.filter(({ codex }) => codex === "fail").length, 5);
+  for (const result of results) console.log(`${result.id}: native=${result.native}, codex=${result.codex}`);
+  console.log(`Native edit vs local Codex Edit: ${results.length} comparison cases passed`);
+}

package/packages/codex-edit/tests/package.test.mjs

@@ -12,6 +12,8 @@ test("package points Pi at the extension and config is reachable from it", async
   const source = await readFile(join(packageDir, "extensions/codex-edit.ts"), "utf8");
   assert.match(source, /new URL\("\.\.\/config\.json", import\.meta\.url\)/);
   assert.match(source, /model-routing\.ts/);
+  assert.match(source, /parameters: Type\.Object\(\{\s*patch: Type\.String/);
+  assert.match(source, /applyUpdateGroups\(before, operation\.chunkGroups, operation\.path\)/);
   const config = JSON.parse(await readFile(join(packageDir, "config.json"), "utf8"));
   assert.equal(config.enabled, true);
   assert.deepEqual(config.models, ["gpt-5.6-*"]);
@@ -41,3 +43,9 @@ test("matches allowed model IDs with globs independently of provider and grammar
   assert.equal(modelIsAllowed({ ...baseModel, id: "GPT-5.6-terra" }, settings), false);
   assert.equal(modelIsAllowed(baseModel, { enabled: false, models: ["gpt-5.6-*"] }), false);
 });
+
+test("execution keeps a resolved-path conflict guard after parser coalescing", async () => {
+  const source = await readFile(join(packageDir, "extensions/codex-edit.ts"), "utf8");
+  assert.match(source, /new Set\(targets\)\.size !== targets\.length/);
+  assert.match(source, /Multiple patch operations target the same resolved path/);
+});

package/packages/codex-edit/tests/parser.test.mjs

@@ -3,7 +3,7 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
-import { applyUpdate, parsePatch, resolveWorkspacePath } from "../src/parser.ts";
+import { applyUpdate, applyUpdateGroups, parsePatch, resolveWorkspacePath } from "../src/parser.ts";
 
 test("parses add, delete, update, and move operations", () => {
   const operations = parsePatch(`*** Begin Patch
@@ -162,6 +162,128 @@ test("parses multiple file operations used by structural refactors", () => {
   );
 });
 
+test("coalesces repeated updates to one path and preserves operation order", () => {
+  const operations = parsePatch(`*** Begin Patch
+*** Update File: src/tool.ts
+@@
+-const value = 1;
++const value = 2;
+*** Update File: src/tool.ts
+@@
+-const value = 2;
++const value = 3;
+*** End Patch`);
+  assert.equal(operations.length, 1);
+  assert.equal(operations[0].path, "src/tool.ts");
+  assert.equal(operations[0].chunkGroups.length, 2);
+  const after = applyUpdateGroups("const value = 1;\n", operations[0].chunkGroups, "src/tool.ts");
+  assert.equal(after, "const value = 3;\n");
+});
+
+test("still rejects conflicting repeated targets", () => {
+  assert.throws(() => parsePatch(`*** Begin Patch
+*** Update File: src/tool.ts
+@@
+-old
++new
+*** Delete File: src/tool.ts
+*** End Patch`), /same path/);
+  assert.throws(() => parsePatch(`*** Begin Patch
+*** Update File: src/old.ts
+*** Move to: src/new.ts
+@@
+-old
++new
+*** Add File: src/new.ts
++replacement
+*** End Patch`), /same path/);
+});
+
+test("rejects empty chunks and stale expected lines instead of guessing", () => {
+  assert.throws(() => parsePatch(`*** Begin Patch
+*** Update File: src/tool.ts
+@@
+*** End Patch`), /Empty update chunk/);
+  const [operation] = parsePatch(`*** Begin Patch
+*** Update File: src/tool.ts
+@@
+-missing line
++replacement
+*** End Patch`);
+  assert.throws(
+    () => applyUpdate("actual line\n", operation.chunks, operation.path),
+    /Failed to find expected lines in src\/tool\.ts/,
+  );
+});
+
+test("handles the reported project-scale repeated-file and Markdown shapes", () => {
+  const operations = parsePatch(`*** Begin Patch
+*** Update File: skills/pi-worktree/SKILL.md
+@@
+-description: old
++description: updated
+@@
+ ---
++Release notes follow.
+*** Update File: packages/tiny-subagent/src/tool.ts
+@@
+-const state = "old";
++const state = "middle";
+*** Update File: packages/tiny-subagent/src/tool.ts
+@@
+-const state = "middle";
++const state = "new";
+*** Update File: scripts/release-package.sh
+@@
+-ROOT_LEVEL=patch
++ROOT_LEVEL=minor
+*** Update File: scripts/release-package.sh
+@@
+-ROOT_LEVEL=minor
++ROOT_LEVEL=patch
+*** End Patch`);
+  assert.deepEqual(operations.map((operation) => operation.path), [
+    "skills/pi-worktree/SKILL.md",
+    "packages/tiny-subagent/src/tool.ts",
+    "scripts/release-package.sh",
+  ]);
+  assert.equal(operations[1].chunkGroups.length, 2);
+  assert.equal(operations[2].chunkGroups.length, 2);
+
+  const skill = `---
+name: pi-worktree
+description: old
+---
+
+# pi-worktree
+
+---
+Footer
+`;
+  assert.equal(
+    applyUpdateGroups(skill, operations[0].chunkGroups, operations[0].path),
+    `---
+name: pi-worktree
+description: updated
+---
+Release notes follow.
+
+# pi-worktree
+
+---
+Footer
+`,
+  );
+  assert.equal(
+    applyUpdateGroups('const state = "old";\n', operations[1].chunkGroups, operations[1].path),
+    'const state = "new";\n',
+  );
+  assert.equal(
+    applyUpdateGroups("ROOT_LEVEL=patch\n", operations[2].chunkGroups, operations[2].path),
+    "ROOT_LEVEL=patch\n",
+  );
+});
+
 test("rejects workspace escapes", () => {
   assert.equal(resolveWorkspacePath("/tmp/project", "/tmp/project/src/a.js"), "/tmp/project/src/a.js");
   assert.throws(() => resolveWorkspacePath("/tmp/project", "/tmp/other/a.js"), /escapes/);

package/packages/codex-edit/tests/released-vs-local.test.mjs

@@ -0,0 +1,31 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { applyUpdate, parsePatch } from "../src/parser.ts";
+import { comparisonCases } from "./comparison-cases.mjs";
+import { runPatchCase } from "./comparison-harness.mjs";
+import { applyLegacyUpdate, parseLegacyPatch } from "./legacy-parser-v0.1.7.mjs";
+
+test("released v0.1.7 versus local parser over the growing comparison corpus", () => {
+  const results = [];
+  for (const testCase of comparisonCases) {
+    const released = runPatchCase(
+      testCase,
+      parseLegacyPatch,
+      applyLegacyUpdate,
+      testCase.outcomes.released,
+    );
+    const local = runPatchCase(testCase, parsePatch, applyUpdate, testCase.outcomes.local);
+    results.push({ id: testCase.id, released, local });
+  }
+
+  assert.equal(results.length, comparisonCases.length);
+  assert.deepEqual(
+    results.find(({ id }) => id === "repeated-update-same-path"),
+    { id: "repeated-update-same-path", released: "fail", local: "pass" },
+  );
+  assert.equal(results.filter(({ released }) => released === "pass").length, 6);
+  assert.equal(results.filter(({ released }) => released === "fail").length, 6);
+  assert.equal(results.filter(({ local }) => local === "pass").length, 7);
+  assert.equal(results.filter(({ local }) => local === "fail").length, 5);
+  for (const result of results) console.log(`${result.id}: released=${result.released}, local=${result.local}`);
+});

package/packages/herdr-subagents/CHANGELOG.md

@@ -0,0 +1,41 @@
+## 2026-10-08 - v0.2.0
+
+- replace Tiny Subagent with visible interactive Herdr agents and durable batch workflows
+- Skip tool and command registration outside a Herdr workspace so unavailable Subagent capabilities do not enter the model context.
+- Preserve newly allocated panes when blocked runs resume, stop blindly retrying Herdr resource-creating commands after uncertain failures, and prevent concurrent historical resumes from writing the same Pi session.
+- Isolate malformed queue/history entries so healthy active runs and durable history remain recoverable, and share durable attempt settlement plus task projection contracts across execution modes.
+- Retain blocked Fleet and dispatcher ownership after stateless response errors, and include public test entrypoints in the published package.
+- Preserve every pending stale-tab cleanup across repeated pane migrations, retry all of them during startup reconciliation, and surface allocator cleanup failures through batch updates.
+- Keep persisted reports authoritative even when Herdr transport fails after submission, persist failure reports for historical follow-ups, reject resume attempts against active or cleanup-pending runs, recover terminal deferred cleanup on startup, preserve cancelled ownership on shutdown, keep recovered Agent attempts aligned with durable turns, archive malformed turns, remove rejected background queue entries, support Pi enhanced keyboard sequences and authoritative status rendering, centralize lifecycle metadata, surface control-plane and cleanup failures, merge deferred cleanup against current durable state, and force-close focused tabs when parent shutdown is already active.
+- Share strict report parsing across live and recovered paths, validate durable task ordering, surface unreadable queue/history records, reconcile prior sessions even within one Pi process, keep settled Fleet rows navigable, preserve surviving sibling panes during dead-pane recovery, and retain cleanup diagnostics.
+- Keep queued and blocked siblings alive when one blocked response fails, centralize authoritative run-status transitions, and bind focus-deferred tab cleanup to parent-session shutdown.
+- Retain dispatcher and Fleet ownership while a batch is blocked, centralize task/turn transitions, surface transient pane lookup failures, and notify deferred single-task cleanup failures.
+- Fail reconciliation when task records are unreadable, archive malformed child reports before replacing them with valid failure records, and keep durable history and saved-session follow-up usable.
+- Keep startup reconciliation moving past truncated child reports, resume dispatch after recovery errors, clear stale blocked fields after authoritative follow-ups, and surface deferred cleanup failures.
+- Stream Fleet row and pane updates while a blocked answer resumes work and releases queued siblings.
+- Keep the active Fleet widget stable when another background run is queued, refresh rows and pane navigation after blocked responses, and cover the public extension UI/input wiring with injectable dependencies.
+- Centralize parent ownership, run-status aggregation, and serialized pane allocation across initial, continued, recovered, and historical runs.
+- Run every initial task, blocked response, recovered task, and historical follow-up as a visible interactive Pi Agent through Herdr Agent start/prompt; remove print mode, pane shell injection, completion markers, and marker polling.
+- Give every started task a new on-demand pane, retain completed panes until the batch settles, and then close the whole tab with focus-safe cleanup.
+- Add a flat fully described tool schema with runtime mode validation and a Fleet-style task list with direct keyboard pane navigation.
+- Continue historical sessions as durable turns of the same logical task, and cancel/archive unfinished work when the parent Pi session closes.
+- Persist and reconcile queued/running work across parent shutdown, avoid retrying uncertain startup operations, preserve post-submit failures, warn without timing out stalled children, and atomically replace state snapshots.
+- Add compact project-local history, saved-session follow-ups in new Herdr tabs, explicit per-run cleanup, unlimited retention, and generated-state Git exclusion.
+- Support structured `needs-input` reports, preserve blocked panes and sessions, and resume the original child with `action: respond`.
+- Queue background batches behind one active run, return stable IDs immediately, keep progress visible, and send one compact run-level parent notification.
+- Show active run counts in a persistent widget, expose compact `/herdr-subagents active` and pane focus navigation, update progress labels, and defer cleanup while a completed tab is focused.
+- Execute ordered read-only batches with FIFO bounded concurrency, stable result order, and sibling failure isolation; force write-capable runs to serial execution.
+- Add built-in worker, explorer, and reviewer personas with project/global/package discovery precedence.
+- Add merged global and project model, thinking, skill, and concurrency settings plus `/herdr-subagents` discovery commands.
+- Run one synchronous subagent in a dedicated, unfocused Herdr tab and close it after completion.
+- Require a structured child report and return only its summary and document paths to the parent.
+- Persist run/task metadata, the full result, and the child Pi session under `.pi/herdr-subagents/runs`.
+
+## 2026-09-30 - v0.1.1
+
+- Add standalone testing documentation and production-runner screenshot/demo media.
+- Align the package manifest and root bundle with the shared workspace source.
+
+## 2026-09-01 - v0.1.0
+
+- initial release

package/packages/herdr-subagents/README.md

@@ -0,0 +1,155 @@
+# @maxiaochao/pi-herdr-subagents
+
+A Pi extension that runs focused foreground or background work as normal interactive Pi Agents in visible Herdr panes. Full answers and sessions stay in project-local records while the parent receives only concise summaries and document paths.
+
+![Herdr Subagents production runner screenshot](docs/screenshot.png)
+
+## Demo
+
+![Herdr Subagents demo](docs/demo.gif)
+
+## Requirements and install
+
+Run Pi inside Herdr, then install the package:
+
+```bash
+pi install npm:@maxiaochao/pi-herdr-subagents
+```
+
+Update an existing standalone installation with:
+
+```bash
+pi update npm:@maxiaochao/pi-herdr-subagents
+```
+
+The full `@maxiaochao/pi-toolkit` package also bundles this extension. Install the full toolkit or this standalone child package, not both.
+
+Inside a Herdr workspace, the package registers `herdr_subagents` and `/herdr-subagents`. Outside Herdr (or without a workspace ID), the extension registers neither, so the tool is absent from the model context. Start Pi inside Herdr or reload the extension there to enable them.
+
+The design replaces hidden print-mode subprocesses with ordinary interactive Pi Agents managed through Herdr, so delegated work stays visible, inspectable, resumable, and durably recorded.
+
+## Usage
+
+Discover the effective personas first:
+
+```text
+herdr_subagents({ action: "list" })
+```
+
+Then run one self-contained task:
+
+```text
+herdr_subagents({
+  agent: "worker",
+  label: "auth-review",
+  prompt: "Inspect the authentication flow and summarize the risks"
+})
+```
+
+Or submit an ordered foreground batch:
+
+```text
+herdr_subagents({
+  label: "security-review",
+  concurrency: 3,
+  tasks: [
+    { name: "auth", agent: "reviewer", prompt: "Review authentication" },
+    { name: "sessions", agent: "explorer", prompt: "Trace session storage" }
+  ]
+})
+```
+
+Set `background: true` to return a stable run ID immediately while the queue continues. One run is dispatched at a time by an extension instance; later runs remain queued and start FIFO. Each background run sends one compact parent notification only when the whole run completes, partially fails, fails, or blocks. Individual successful tasks do not wake the parent model.
+
+A child missing required information reports `needs-input` with an exact question. The run becomes blocked, keeps its Herdr tab, pane, partial report, and Pi session, and returns control to the parent. Answer through the same tool to continue the original session:
+
+```text
+herdr_subagents({ action: "respond", runId: "<run-id>", answer: "Use the main branch." })
+```
+
+While a batch is active, its task rows stay below the editor. With an empty editor, press `↓` to enter the list, `↑`/`↓` to choose a task, `Enter` to focus its exact pane, and `Esc` to return. `/herdr-subagents focus <task-number>` remains available as a fallback.
+
+## History
+
+Run `/herdr-subagents history` or `herdr_subagents({ action: "history" })` to list compact project-local run and task reports after Herdr tabs close. Full results, described documents, artifacts, and persistent Pi sessions remain separate on disk and are not loaded into parent context.
+
+Continue a saved conversation in a new Herdr tab with `herdr_subagents({ action: "resume", runId: "<run-id>", task: 1, prompt: "Follow up..." })`. Remove only a selected archive with `herdr_subagents({ action: "cleanup", runId: "<run-id>" })`. History has no automatic count-based eviction. The extension adds the runtime path to local Git excludes when available (and otherwise uses `.pi/.gitignore`) without overwriting unrelated rules.
+
+Read-only tasks start FIFO up to the configured concurrency limit. A pane is created only when its task starts, belongs exclusively to that task, and is never reused. Completed panes remain inspectable while another task in the batch is unsettled. Results remain in input order, and one failed task does not cancel its siblings. Any batch containing a write-capable persona is forced to concurrency one.
+
+The widget shows one row per queued, running, blocked, failed, or completed task. Answering a blocked task refreshes rows and pane IDs as that task resumes and queued siblings start. Completed rows remain selectable until the whole batch settles. `/herdr-subagents active` shows the same compact state. Native labels stay short: `SA · <batch>` for the tab and `<order> · <task>` for each pane. When all tasks settle, the tab closes immediately if unfocused or after the user leaves it; a deferred close failure is persisted and shown as a warning.
+
+Foreground calls block until all children report completion, failure, or a request for input. Every child is started with Herdr's Agent lifecycle as a normal Pi TUI and prompted with wait semantics; no print-mode command or completion marker is injected into the pane.
+
+## Reports and records
+
+The child must finish through the package's structured `subagent_report` tool. The parent receives only:
+
+- completion or failure status
+- a concise summary
+- paths to useful documents
+- the task-record location
+
+The complete result is not copied into the parent model context. Each run is retained under:
+
+```text
+.pi/herdr-subagents/runs/<run>/tasks/<task>/
+```
+
+The task directory contains the full result, structured report, task metadata, system prompt, and persistent Pi session. Run-level metadata is stored in the parent run directory.
+
+## Personas
+
+The package includes `worker` (write access), `explorer` (read access), and `reviewer` (read access). Persona definitions are discovered in this order, with the first available higher-precedence definition replacing the lower one:
+
+1. `.pi/herdr-subagents/agents/*.md` in the project
+2. `~/.pi/agent/herdr-subagents/agents/*.md` globally
+3. this package's `agents/*.md`
+
+A custom persona without `access` is treated as write-capable. Definitions may set `access`, `model`, `thinking`, `tools`, and `skills` in frontmatter.
+
+The default `agents/worker.md` uses this format:
+
+```md
+---
+name: worker
+description: General-purpose worker for one focused task
+tools: read, bash, edit, write, grep, find, ls
+---
+
+You are a focused worker subagent.
+```
+
+Supported frontmatter:
+
+- `name` and `description` are required.
+- `model` optionally selects a child model. A call-level `model` overrides it; otherwise the current session model is inherited.
+- `tools` optionally restricts built-in tools. `subagent_report` is always added so the child can settle the task.
+- `access` is `read` or `write`; omitted custom values default to `write`.
+- `thinking` and `skills` provide persona defaults.
+
+Global settings live at `~/.pi/agent/herdr-subagents.json`; project overrides live at `.pi/herdr-subagents.json`. Both support `defaultConcurrency`, `maxConcurrency`, `stalledWarningSeconds`, `defaultModel`, and a `personas` object whose entries can override `model`, `thinking`, and `skills`.
+
+```json
+{
+  "defaultModel": "provider/model",
+  "maxConcurrency": 3,
+  "personas": {
+    "reviewer": { "thinking": "high", "skills": ["code-review"] }
+  }
+}
+```
+
+Project values override global values recursively. Model resolution is: task override, project persona setting, global persona setting, persona frontmatter, global/project default model, then parent model. Run `/herdr-subagents agents`, `/herdr-subagents models`, or `/herdr-subagents settings` to inspect effective values and their sources.
+
+## Recovery and failures
+
+Queued background submissions are persisted before dispatch. Closing the parent Pi session cancels queued, running, and blocked work, records `cancelled`, and closes the owned run tab. On the next Pi start, stale active records and queued submissions from a prior parent session are reconciled to a terminal state, including when Pi reused the same process, and leaked tabs are cleaned up when possible. Missing, truncated, or structurally invalid child reports become explicit failures or cancellation diagnostics; recovery errors are reported without leaving new submissions paused.
+
+Tab, pane, and child startup commands are not automatically retried: an error may arrive after Herdr already created the resource. A failure after prompt submission is preserved and never automatically rerun. Historical follow-ups exclude concurrent resumes of the same run with an atomic `.resume.lock` directory; if Pi crashes without releasing it, confirm no Agent is still using that run before removing the lock manually. `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.
+
+## Development and tests
+
+See [TESTING.md](TESTING.md) for deterministic tests, extension loading, packaging, and real Herdr smoke requirements.

package/packages/herdr-subagents/TESTING.md

@@ -0,0 +1,24 @@
+# Herdr Subagents test strategy
+
+## 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. `npm pack ./packages/herdr-subagents --dry-run` verifies package contents.
+4. Verify the README example and the production-runner media `docs/screenshot.png` and `docs/demo.gif` are present in the tarball.
+
+## Cases
+
+- Resolve package, global, and project personas and validate frontmatter/configuration.
+- Run foreground tasks and FIFO bounded-concurrency batches through an injectable Herdr boundary.
+- Verify all paths use interactive Agent start/prompt without print mode, shell injection, markers, or pane reuse.
+- Force write-capable batches to serial execution while allowing bounded read-only parallelism.
+- Preserve compact reports, full results, Pi sessions, blocked questions, and historical follow-ups.
+- Recover queued/running work after interruption without retrying post-prompt side effects, including truncated reports and recovery errors.
+- Verify the flat public contract and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, and stable display while another background run queues.
+- Verify blocked-response live Fleet updates, authoritative stale-field replacement, parent-shutdown cancellation, cleanup notifications, atomic state replacement, non-retried uncertain startup operations, and stalled warnings.
+- Verify resumed batches retain newly allocated pane IDs and historical follow-ups exclude simultaneous session writers.
+
+## Latest baseline
+
+All 133 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, and persona cases 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 two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.

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

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