xz-pi-side-agents-herdr 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0
+
+### Patch Changes
+
+- 385169d: heder 兼容
+
+## 0.1.0
+
+- Initial Herdr-native side-agent implementation.
+- Added `/agent`, `/agents`, `/agent-resume` and orchestration tools.
+- Added one-worktree-per-pane lifecycle and guarded `/quit` cleanup.
+- Added project initialization skill with configurable integration branch.
+- Fixed bootstrap completion detection racing with echoed shell commands.
+- Explicitly loads the lifecycle extension in locally launched children.
+- Added an arbitrary-key confirmation before deleting a merged worktree and closing its pane.
+- Reconciles stale registry records when their worktree and pane are already gone, while preserving unmerged branches for resume.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xz-pi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# xz-pi-side-agents-herdr
+
+Herdr-native asynchronous side agents for Pi. It keeps the command/tool surface of `pi-side-agents`, but maps each child Git worktree to a visible Herdr pane instead of a tmux window.
+
+## Requirements
+
+- Node.js 22+
+- Pi 0.84.4+
+- Herdr 0.9+
+- A Git repository
+- Pi must run inside Herdr (`HERDR_ENV=1`)
+
+Do not enable this package together with `pi-side-agents`; both register the same commands and tools.
+
+## Install
+
+```bash
+pi install ./xz-pi-side-agents-herdr
+```
+
+Restart Pi, then initialize the current repository:
+
+```text
+/skill:agent-setup
+```
+
+The setup skill defaults `mainBranch` to the branch checked out during initialization. A different local branch can be specified in the setup request.
+
+## Commands
+
+```text
+/agent [-model <provider/id>] [-mode <name>] <task>
+/agents
+/agent-resume
+```
+
+Tools exposed to the parent agent:
+
+```text
+agent-start
+agent-check
+agent-wait-any
+agent-send
+```
+
+## Model
+
+A child is represented by:
+
+```text
+Agent:    fix-auth-0001
+Branch:   side-agent/fix-auth-0001
+Worktree: ../repo-agent-fix-auth-0001
+Pane:     Herdr pane id such as w1:p4
+```
+
+The worktree starts from the configured integration branch. The first child opens in a narrow right column (`mainPaneRatio` defaults to `0.72`, so main stays largest). Additional children split the largest child pane downward, keeping a balanced stack on the right without shrinking main again. The extension preserves focus, runs project bootstrap in the child pane, starts Pi through `herdr agent start`, and submits the task through `herdr agent prompt`.
+
+## `/quit` safety
+
+On child `/quit`, cleanup occurs only when both conditions hold:
+
+1. `git status --porcelain` is empty;
+2. the child branch has no commit missing from the configured integration branch.
+
+When safe, the child exits to its shell and asks for one final arbitrary-key confirmation in the Herdr pane. After a key is pressed, a detached janitor removes the worktree, deletes the already-merged topic branch, closes the pane, and removes the registry entry.
+
+If uncommitted or unmerged work exists, cleanup is skipped. The worktree and pane remain, the registry status becomes `paused`, and `/agent-resume` can reopen the child session.
+
+## Local state
+
+```text
+.pi/side-agents-herdr/config.json
+.pi/side-agents-herdr/registry.json
+.pi/side-agents-herdr/registry.lock
+.pi/side-agent-start.sh
+.pi/side-agent-finish.sh
+.pi/side-agent-skills/
+```
+
+These files are local runtime configuration and should not be committed.

package/index.ts

@@ -0,0 +1,190 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { handleChildQuit, linkChildSession } from "./src/lifecycle.js";
+import { repoRoot, SideAgentService } from "./src/service.js";
+import { ENV, type AgentRecord } from "./src/types.js";
+
+const terminal = new Set(["waiting_user", "blocked", "paused", "failed", "crashed"]);
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+export function parseAgentArgs(raw: string): { task: string; model?: string; mode?: string } {
+  let rest = raw;
+  const modelMatch = rest.match(/(?:^|\s)-model\s+(\S+)/);
+  const modeMatch = rest.match(/(?:^|\s)-mode\s+(\S+)/);
+  if (modelMatch) rest = rest.replace(modelMatch[0], " ");
+  if (modeMatch) rest = rest.replace(modeMatch[0], " ");
+  return { task: rest.trim(), model: modelMatch?.[1], mode: modeMatch?.[1] };
+}
+
+async function modelFor(ctx: ExtensionContext, requested?: string, mode?: string): Promise<string | undefined> {
+  if (requested) return requested.includes("/") ? requested : requested;
+  if (mode) {
+    for (const path of [join(ctx.cwd, ".pi", "modes.json"), join(process.env.PI_CODING_AGENT_DIR ?? join(process.env.HOME ?? "", ".pi", "agent"), "modes.json")]) {
+      try {
+        const value = JSON.parse(await readFile(path, "utf8")) as { modes?: Record<string, { provider?: string; modelId?: string; thinkingLevel?: string }> };
+        const spec = value.modes?.[mode];
+        if (spec?.provider && spec.modelId) return `${spec.provider}/${spec.modelId}${spec.thinkingLevel ? `:${spec.thinkingLevel}` : ""}`;
+      } catch { /* try next */ }
+    }
+    throw new Error(`Mode '${mode}' was not found in .pi/modes.json or the global modes.json`);
+  }
+  return ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+}
+
+async function serviceFor(ctx: ExtensionContext): Promise<SideAgentService> {
+  const root = process.env[ENV.stateRoot] || await repoRoot(ctx.cwd);
+  return new SideAgentService(root);
+}
+
+function summary(record: AgentRecord): string {
+  return `${record.id}  ${record.status}  pane:${record.paneId ?? "-"}  worktree:${record.worktreePath}\n  task: ${record.task.slice(0, 180)}`;
+}
+
+export default function sideAgentsHerdr(pi: ExtensionAPI): void {
+  if (process.env[ENV.agentId]) {
+    pi.on("session_start", async (_event, ctx) => { await linkChildSession(await serviceFor(ctx), ctx).catch(() => undefined); });
+    pi.on("agent_start", async (_event, ctx) => { const service = await serviceFor(ctx); await service.update(process.env[ENV.agentId]!, { status: "running" }).catch(() => undefined); });
+    pi.on("agent_end", async (_event, ctx) => { const service = await serviceFor(ctx); await service.update(process.env[ENV.agentId]!, { status: "waiting_user" }).catch(() => undefined); });
+    pi.on("session_shutdown", async (event, ctx) => {
+      if (event.reason === "quit") await handleChildQuit(await serviceFor(ctx), ctx).catch(error => console.error(`[side-agent] quit cleanup check failed: ${String(error)}`));
+    });
+    return;
+  }
+
+  let statusTimer: NodeJS.Timeout | undefined;
+  const updateStatus = async (ctx: ExtensionContext) => {
+    if (!ctx.hasUI) return;
+    try {
+      const records = await (await serviceFor(ctx)).list();
+      const text = records.map(record => `${record.id}:${record.status}@${record.paneId ?? "-"}`).join(" ");
+      ctx.ui.setStatus("side-agents-herdr", text || undefined);
+    } catch { /* status is best effort */ }
+  };
+  pi.on("session_start", (_event, ctx) => {
+    if (ctx.hasUI && !statusTimer) {
+      statusTimer = setInterval(() => void updateStatus(ctx), 2500);
+      statusTimer.unref();
+    }
+    void updateStatus(ctx);
+  });
+  pi.on("session_shutdown", () => { if (statusTimer) clearInterval(statusTimer); statusTimer = undefined; });
+
+  pi.registerCommand("agent", {
+    description: "Spawn a background child Pi agent in a Herdr pane/worktree: /agent [-model <provider/id>] [-mode <name>] <task>",
+    handler: async (args, ctx) => {
+      const parsed = parseAgentArgs(args);
+      if (!parsed.task) { ctx.ui.notify("Usage: /agent [-model <provider/id>] [-mode <name>] <task>", "error"); return; }
+      if (!ctx.isProjectTrusted()) { ctx.ui.notify("Side-agent creation requires a trusted project", "error"); return; }
+      try {
+        const result = await (await serviceFor(ctx)).start(ctx, { task: parsed.task, model: await modelFor(ctx, parsed.model, parsed.mode) });
+        ctx.ui.notify(`Started ${result.id}\npane: ${result.paneId}\nworktree: ${result.worktreePath}\nbranch: ${result.branch}`, "info");
+        await updateStatus(ctx);
+      } catch (error) { ctx.ui.notify(`Failed to start agent: ${error instanceof Error ? error.message : String(error)}`, "error"); }
+    },
+  });
+
+  pi.registerCommand("agents", {
+    description: "List tracked side agents",
+    handler: async (_args, ctx) => {
+      try {
+        const records = await (await serviceFor(ctx)).list();
+        ctx.ui.notify(records.length ? records.map(summary).join("\n\n") : "No tracked side agents.", "info");
+      } catch (error) { ctx.ui.notify(String(error), "error"); }
+    },
+  });
+
+  pi.registerCommand("agent-resume", {
+    description: "Resume a previously /quit side-agent session in its retained worktree/Herdr pane",
+    handler: async (args, ctx) => {
+      if (args.trim()) { ctx.ui.notify("/agent-resume takes no arguments", "error"); return; }
+      if (!ctx.hasUI) return;
+      const service = await serviceFor(ctx);
+      const candidates = (await service.list()).filter(record => ["paused", "failed", "crashed"].includes(record.status) && record.childSessionId);
+      if (!candidates.length) { ctx.ui.notify("No resumable side-agent sessions.", "info"); return; }
+      const labels = candidates.map(summary);
+      const selected = await ctx.ui.select("Resume side-agent", labels);
+      if (!selected) return;
+      const candidate = candidates[labels.indexOf(selected)];
+      try {
+        const result = await service.start(ctx, { task: candidate.task, resumeId: candidate.id });
+        ctx.ui.notify(`Resumed ${result.id} in pane ${result.paneId}`, "info");
+      } catch (error) { ctx.ui.notify(`Failed to resume: ${String(error)}`, "error"); }
+    },
+  });
+
+  pi.registerTool({
+    name: "agent-start", label: "Agent Start",
+    description: "Start a background side agent in a Herdr pane and isolated Git worktree. Commands match pi-side-agents. Returns { ok, id, task, paneId, tabId, workspaceId, worktreePath, branch, warnings }.",
+    parameters: Type.Object({
+      description: Type.String({ description: "Self-contained task description" }),
+      branchHint: Type.String({ description: "Short kebab-case feature slug, max 3 words" }),
+      model: Type.Optional(Type.String({ description: "Optional provider/modelId" })),
+    }),
+    async execute(_id, params, signal, _update, ctx) {
+      try {
+        signal?.throwIfAborted();
+        if (!ctx.isProjectTrusted()) throw new Error("agent-start requires a trusted project");
+        const result = await (await serviceFor(ctx)).start(ctx, { task: params.description, branchHint: params.branchHint, model: await modelFor(ctx, params.model) });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: result };
+      } catch (error) {
+        const result = { ok: false, error: error instanceof Error ? error.message : String(error) };
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: result };
+      }
+    },
+    renderCall(args, theme) { return new Text(theme.fg("toolTitle", `Agent Start · ${args.branchHint}`), 0, 0); },
+  });
+
+  pi.registerTool({
+    name: "agent-check", label: "Agent Check",
+    description: "Check a side agent and return its Herdr status, pane/worktree metadata, and recent terminal output.",
+    parameters: Type.Object({ id: Type.String({ description: "Agent id" }) }),
+    async execute(_id, params, _signal, _update, ctx) {
+      try { const value = await (await serviceFor(ctx)).check(params.id); return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], details: value }; }
+      catch (error) { const value = { ok: false, error: String(error) }; return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], details: value }; }
+    },
+    renderCall(args, theme) { return new Text(theme.fg("toolTitle", `Agent Check · ${args.id}`), 0, 0); },
+  });
+
+  pi.registerTool({
+    name: "agent-wait-any", label: "Agent Wait Any",
+    description: "Wait until any requested side agent finishes, yields, blocks, pauses, fails, or crashes.",
+    parameters: Type.Object({ ids: Type.Array(Type.String(), { minItems: 1 }) }),
+    async execute(_id, params, signal, _update, ctx) {
+      const service = await serviceFor(ctx);
+      const known = new Set<string>();
+      while (!signal?.aborted) {
+        for (const id of [...new Set(params.ids)]) {
+          const value = await service.check(id);
+          if (value.ok === true) {
+            known.add(id);
+            const status = (value.agent as AgentRecord).status;
+            if (terminal.has(status)) return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], details: value };
+          } else if (known.has(id)) {
+            const done = { ok: true, agent: { id, status: "done" }, backlog: [] };
+            return { content: [{ type: "text", text: JSON.stringify(done, null, 2) }], details: done };
+          } else {
+            return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], details: value };
+          }
+        }
+        await sleep(1000);
+      }
+      const aborted = { ok: false, error: "agent-wait-any aborted" };
+      return { content: [{ type: "text", text: JSON.stringify(aborted, null, 2) }], details: aborted };
+    },
+    renderCall(args, theme) { return new Text(theme.fg("toolTitle", `Agent Wait · ${args.ids?.join(", ") ?? ""}`), 0, 0); },
+  });
+
+  pi.registerTool({
+    name: "agent-send", label: "Agent Send",
+    description: "Send a prompt to a side agent through Herdr. Prefix ! interrupts first; slash commands such as /quit are forwarded unchanged.",
+    parameters: Type.Object({ id: Type.String(), prompt: Type.String() }),
+    async execute(_id, params, _signal, _update, ctx) {
+      try { const value = await (await serviceFor(ctx)).send(params.id, params.prompt); return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], details: value }; }
+      catch (error) { const value = { ok: false, message: String(error) }; return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], details: value }; }
+    },
+    renderCall(args, theme) { return new Text(theme.fg("toolTitle", `Agent Send · ${args.id}`), 0, 0); },
+  });
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "xz-pi-side-agents-herdr",
+  "version": "0.1.0",
+  "description": "Herdr-native side-agent orchestration for Pi with one Git worktree per pane",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "agents",
+    "herdr",
+    "worktree"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xuzan9396/xz-pi.git",
+    "directory": "xz-pi-side-agents-herdr"
+  },
+  "homepage": "https://github.com/Xuzan9396/xz-pi/tree/main/xz-pi-side-agents-herdr",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "scripts",
+    "skills",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx/esm --test 'test/**/*.test.ts'",
+    "check": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.84.4",
+    "@earendil-works/pi-coding-agent": ">=0.84.4",
+    "@earendil-works/pi-tui": ">=0.84.4",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.0",
+    "typebox": "1.3.7",
+    "typescript": "^5.9.0"
+  }
+}

package/scripts/janitor.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+const payload = JSON.parse(Buffer.from(process.argv[2] ?? "", "base64url").toString("utf8"));
+const dir = join(payload.root, ".pi", "side-agents-herdr");
+const registryPath = join(dir, "registry.json");
+const lockPath = join(dir, "registry.lock");
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const shellQuote = value => `'${String(value).replace(/'/g, `'"'"'`)}'`;
+
+async function mutate(fn) {
+  await mkdir(dir, { recursive: true });
+  const started = Date.now();
+  while (true) {
+    try { const handle = await open(lockPath, "wx", 0o600); await handle.close(); break; }
+    catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const age = Date.now() - (await stat(lockPath).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
+      if (age > 30_000) { await rm(lockPath, { force: true }); continue; }
+      if (Date.now() - started > 10_000) throw new Error(`registry lock timeout: ${lockPath}`);
+      await sleep(50);
+    }
+  }
+  try {
+    const registry = JSON.parse(await readFile(registryPath, "utf8"));
+    await fn(registry);
+    const temporary = `${registryPath}.${process.pid}.tmp`;
+    await writeFile(temporary, JSON.stringify(registry, null, 2) + "\n", { mode: 0o600 });
+    await rename(temporary, registryPath);
+  } finally { await rm(lockPath, { force: true }); }
+}
+
+try {
+  // Wait for Pi to finish session persistence and release its Herdr agent name.
+  // A bounded fallback still prevents a stuck detector from leaking cleanup forever.
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    const live = await exec("herdr", ["agent", "get", payload.id]).then(() => true, () => false);
+    if (!live) break;
+    await sleep(100);
+  }
+  if (payload.paneId) {
+    const confirmation = join(dir, `cleanup-confirm-${payload.id}`);
+    await rm(confirmation, { force: true });
+    const prompt = "[side-agent] Work is clean and merged. Press any key to remove the worktree and close this pane...";
+    const inner = `printf '%s' ${shellQuote(prompt)}; IFS= read -r -n 1 _; printf '\\n'; : > ${shellQuote(confirmation)}`;
+    await exec("herdr", ["pane", "run", payload.paneId, `bash -lc ${shellQuote(inner)}`]);
+    while (true) {
+      const confirmed = await stat(confirmation).then(() => true, () => false);
+      if (confirmed) break;
+      const paneExists = await exec("herdr", ["pane", "get", payload.paneId]).then(() => true, () => false);
+      if (!paneExists) {
+        await mutate(registry => {
+          const record = registry.agents[payload.id];
+          if (!record) return;
+          record.status = "paused";
+          record.warnings = [...(record.warnings ?? []), "Cleanup confirmation pane was closed; worktree was preserved."];
+          record.updatedAt = new Date().toISOString();
+        });
+        process.exit(0);
+      }
+      await sleep(200);
+    }
+    await rm(confirmation, { force: true });
+  }
+  await exec("git", ["-C", payload.root, "worktree", "remove", payload.worktreePath], { env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
+  await exec("git", ["-C", payload.root, "worktree", "prune"], { env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
+  // The child already checked this before requesting cleanup; verify again to
+  // avoid deleting a branch if the integration ref changed during shutdown.
+  const ancestry = await exec("git", ["-C", payload.root, "merge-base", "--is-ancestor", payload.branch, payload.mainBranch]).then(() => true, () => false);
+  if (ancestry) await exec("git", ["-C", payload.root, "branch", "-D", payload.branch], { env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
+  if (payload.paneId) await exec("herdr", ["pane", "close", payload.paneId]).catch(() => undefined);
+  await mutate(registry => { delete registry.agents[payload.id]; });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  await mutate(registry => {
+    const record = registry.agents[payload.id];
+    if (!record) return;
+    const paneGone = message.includes("pane_not_found");
+    record.status = paneGone ? "paused" : "failed";
+    if (paneGone) {
+      record.warnings = [...(record.warnings ?? []), "Cleanup confirmation pane disappeared; worktree was preserved."];
+      delete record.error;
+    } else {
+      record.error = `Cleanup failed: ${message}`;
+    }
+    record.updatedAt = new Date().toISOString();
+  }).catch(() => undefined);
+}

package/skills/agent-setup/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: agent-setup
+description: Initialize or update project-local configuration for xz-pi-side-agents-herdr, including the integration branch and lifecycle scripts
+---
+
+# Herdr Side-Agent Setup
+
+Initialize this repository for `xz-pi-side-agents-herdr`. Everything created below is local runtime configuration under `.pi/`; do not commit it.
+
+## 1. Determine configuration
+
+Find the repository root and current branch:
+
+```bash
+GIT_ROOT=$(git rev-parse --show-toplevel)
+CURRENT_BRANCH=$(git -C "$GIT_ROOT" branch --show-current)
+```
+
+Use the current branch as the default integration branch. If the user supplied a branch in the skill arguments, use that instead. Verify the branch exists with:
+
+```bash
+git -C "$GIT_ROOT" show-ref --verify "refs/heads/$MAIN_BRANCH"
+```
+
+Ask before overwriting any existing files. Ask whether the project needs bootstrap commands such as dependency installation or copying local environment files.
+
+Keep runtime files out of Git status without changing the tracked `.gitignore`. Ensure the shared Git exclude file contains these lines exactly once:
+
+```gitignore
+.pi/side-agents-herdr/
+.pi/side-agent-start.sh
+.pi/side-agent-finish.sh
+.pi/side-agent-skills
+```
+
+Resolve the shared exclude path with `git -C "$GIT_ROOT" rev-parse --git-path info/exclude`, create its parent directory if needed, and append only missing lines. This exclude is shared by the main checkout and linked worktrees.
+
+## 2. Create `.pi/side-agents-herdr/config.json`
+
+```json
+{
+  "version": 1,
+  "mainBranch": "MAIN_BRANCH_VALUE",
+  "mainPaneRatio": 0.72,
+  "childSplitRatio": 0.5,
+  "cleanupOnQuit": true
+}
+```
+
+The first child opens on the right. `mainPaneRatio: 0.72` keeps the main pane at roughly 72% width. Additional children split the largest child pane downward at `childSplitRatio`, producing a balanced stack in the right column without shrinking the main pane.
+
+## 3. Create executable `.pi/side-agent-start.sh`
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+PARENT_ROOT="${1:?parent repository is required}"
+WORKTREE="${2:?worktree is required}"
+AGENT_ID="${3:?agent id is required}"
+MAIN_BRANCH="MAIN_BRANCH_VALUE"
+BRANCH="$(git -C "$WORKTREE" branch --show-current)"
+
+if [[ -z "$BRANCH" || "$BRANCH" == "$MAIN_BRANCH" ]]; then
+  echo "[side-agent-start] invalid child branch: $BRANCH"
+  exit 1
+fi
+
+echo "[side-agent-start] agent=$AGENT_ID branch=$BRANCH main=$MAIN_BRANCH"
+echo "[side-agent-start] base=$(git -C "$WORKTREE" rev-parse --short HEAD)"
+
+# Add project-specific bootstrap commands below this line.
+```
+
+Append bootstrap commands agreed with the user, then run `chmod +x`.
+
+## 4. Create executable `.pi/side-agent-finish.sh`
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+PARENT_ROOT="${PI_SIDE_PARENT_REPO:?PI_SIDE_PARENT_REPO is required}"
+MAIN_BRANCH="MAIN_BRANCH_VALUE"
+BRANCH="$(git branch --show-current)"
+
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "[side-agent-finish] commit or discard local changes first"
+  exit 2
+fi
+
+LOCK_DIR="$PARENT_ROOT/.pi/side-agents-herdr/merge.lock"
+ACQUIRED=0
+for _ in $(seq 1 120); do
+  if mkdir "$LOCK_DIR" 2>/dev/null; then ACQUIRED=1; break; fi
+  sleep 1
+done
+if [[ "$ACQUIRED" != 1 ]]; then
+  echo "[side-agent-finish] timed out waiting for merge lock"
+  exit 3
+fi
+trap 'rmdir "$LOCK_DIR" 2>/dev/null || true' EXIT
+
+git rebase "$MAIN_BRANCH"
+git -C "$PARENT_ROOT" checkout "$MAIN_BRANCH"
+git -C "$PARENT_ROOT" merge --ff-only "$BRANCH"
+echo "[side-agent-finish] merged $BRANCH into $MAIN_BRANCH"
+```
+
+Run `chmod +x`.
+
+## 5. Create `.pi/side-agent-skills/finish/SKILL.md`
+
+```markdown
+---
+name: finish
+description: Finish a Herdr side-agent branch after explicit user approval by rebasing and fast-forwarding it into the configured integration branch
+---
+
+# Finish side-agent work
+
+Only after explicit approval such as “LGTM, merge”:
+
+1. Ensure all intended changes are committed.
+2. Run `.pi/side-agent-finish.sh`.
+3. Resolve any rebase conflict and rerun the script.
+4. Report the landed commits.
+5. Run `/quit` when done. After Pi exits, press any key at the pane confirmation prompt; the extension then removes the clean, fully merged worktree and closes its Herdr pane.
+
+If `/quit` detects uncommitted changes or commits not merged into the integration branch, it preserves both the worktree and pane and reports why cleanup was skipped.
+```
+
+
+## 6. Report
+
+List files created, updated, or skipped. Remind the user:
+
+- Start: `/agent <task>`
+- Inspect: `/agents`
+- Resume a preserved unfinished agent: `/agent-resume`
+- Local `.pi/side-agent-*` and `.pi/side-agents-herdr/` files must remain untracked.

package/src/herdr.ts

@@ -0,0 +1,89 @@
+import { exec, parseJsonOutput } from "./process.js";
+
+interface Envelope<T> { result: T }
+interface PaneInfo { pane_id: string; tab_id?: string; workspace_id?: string; agent_status?: string }
+export interface LayoutPane { pane_id: string; rect: { width: number; height: number; x: number; y: number } }
+
+export class Herdr {
+  async ensureReady(): Promise<void> {
+    if (process.env.HERDR_ENV !== "1") throw new Error("/agent must be run inside a Herdr-managed pane (HERDR_ENV=1)");
+    const status = await exec("herdr", ["status"]);
+    if (!status.stdout.includes("endpoint_compatible: yes")) throw new Error("Herdr client/server endpoint is not compatible");
+  }
+
+  async layout(paneId: string): Promise<{ panes: LayoutPane[] }> {
+    const out = await exec("herdr", ["pane", "layout", "--pane", paneId]);
+    const json = parseJsonOutput<Envelope<{ layout: { panes: LayoutPane[] } }>>(out.stdout, "herdr pane layout");
+    return { panes: json.result.layout.panes };
+  }
+
+  async split(params: { targetPaneId: string; direction: "right" | "down"; ratio: number; cwd: string; env: Record<string, string> }): Promise<PaneInfo> {
+    const args = ["pane", "split", "--pane", params.targetPaneId, "--direction", params.direction, "--ratio", String(params.ratio), "--cwd", params.cwd, "--no-focus"];
+    for (const [key, value] of Object.entries(params.env)) args.push("--env", `${key}=${value}`);
+    const out = await exec("herdr", args);
+    const json = parseJsonOutput<Envelope<{ pane: PaneInfo }>>(out.stdout, "herdr pane split");
+    if (!json.result.pane?.pane_id) throw new Error("Herdr did not return a pane id");
+    return json.result.pane;
+  }
+
+  async run(paneId: string, command: string): Promise<void> {
+    await exec("herdr", ["pane", "run", paneId, command]);
+  }
+
+  async waitOutput(paneId: string, text: string, timeoutMs: number): Promise<string> {
+    const out = await exec("herdr", ["pane", "wait-output", paneId, "--match", text, "--source", "recent-unwrapped", "--timeout", String(timeoutMs)]);
+    return out.stdout;
+  }
+
+  async closePane(paneId: string): Promise<void> {
+    await exec("herdr", ["pane", "close", paneId], { allowFailure: true });
+  }
+
+  async startAgent(name: string, paneId: string, args: string[]): Promise<"ready" | "blocked"> {
+    const command = ["agent", "start", name, "--kind", "pi", "--pane", paneId];
+    if (args.length) command.push("--", ...args);
+    try {
+      await exec("herdr", command);
+      return "ready";
+    } catch (error) {
+      // Herdr keeps the assigned agent name when startup reaches an approval or
+      // question UI. Preserve the pane so the user can resolve it directly.
+      if (String(error).includes("agent_not_ready")) return "blocked";
+      throw error;
+    }
+  }
+
+  async getAgent(target: string): Promise<PaneInfo | undefined> {
+    const out = await exec("herdr", ["agent", "get", target], { allowFailure: true });
+    if (!out.stdout.trim()) return undefined;
+    try {
+      const json = parseJsonOutput<Envelope<{ agent: PaneInfo }>>(out.stdout, "herdr agent get");
+      return json.result.agent;
+    } catch { return undefined; }
+  }
+
+  async readAgent(target: string, lines = 20): Promise<string[]> {
+    const out = await exec("herdr", ["agent", "read", target, "--source", "recent-unwrapped", "--lines", String(lines)], { allowFailure: true });
+    if (!out.stdout.trim()) return [];
+    try {
+      const json = parseJsonOutput<Envelope<Record<string, unknown>>>(out.stdout, "herdr agent read");
+      const result = json.result as { text?: string; content?: string; output?: string };
+      return (result.text ?? result.content ?? result.output ?? "").split(/\r?\n/).filter(Boolean).slice(-lines);
+    } catch { return out.stdout.split(/\r?\n/).filter(Boolean).slice(-lines); }
+  }
+
+  async prompt(target: string, text: string): Promise<void> {
+    await exec("herdr", ["agent", "prompt", target, text]);
+  }
+
+  async interrupt(target: string): Promise<void> {
+    await exec("herdr", ["agent", "send-keys", target, "ctrl+c"], { allowFailure: true });
+  }
+}
+
+export function mapHerdrStatus(status?: string): "running" | "waiting_user" | "blocked" | undefined {
+  if (status === "working") return "running";
+  if (status === "blocked") return "blocked";
+  if (status === "idle" || status === "done") return "waiting_user";
+  return undefined;
+}

package/src/layout.ts

@@ -0,0 +1,18 @@
+import type { LayoutPane } from "./herdr.js";
+
+export function choosePlacement(
+  callerPaneId: string,
+  panes: LayoutPane[],
+  childPaneIds: string[],
+  mainRatio = 0.72,
+  childRatio = 0.5,
+): { targetPaneId: string; direction: "right" | "down"; ratio: number } {
+  const childIds = new Set(childPaneIds);
+  const children = panes
+    .filter(pane => childIds.has(pane.pane_id))
+    .sort((a, b) => (b.rect.height * b.rect.width) - (a.rect.height * a.rect.width));
+  if (!children.length) {
+    return { targetPaneId: callerPaneId, direction: "right", ratio: Math.min(0.82, Math.max(0.6, mainRatio)) };
+  }
+  return { targetPaneId: children[0].pane_id, direction: "down", ratio: Math.min(0.7, Math.max(0.3, childRatio)) };
+}

package/src/lifecycle.ts

@@ -0,0 +1,62 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { git } from "./process.js";
+import { SideAgentService } from "./service.js";
+import { ENV } from "./types.js";
+
+export async function linkChildSession(service: SideAgentService, ctx: ExtensionContext): Promise<void> {
+  const id = process.env[ENV.agentId];
+  if (!id) return;
+  await service.update(id, {
+    childSessionId: ctx.sessionManager.getSessionFile(),
+    status: "running",
+  });
+}
+
+export function cleanupBlockers(dirty: string, unmerged: number, mainBranch: string): string[] {
+  return [
+    dirty.trim() ? "存在未提交修改" : "",
+    unmerged > 0 ? `有 ${unmerged} 个提交尚未合并到 ${mainBranch}` : "",
+  ].filter(Boolean);
+}
+
+export async function handleChildQuit(service: SideAgentService, ctx: ExtensionContext): Promise<void> {
+  const id = process.env[ENV.agentId];
+  if (!id) return;
+  const record = await service.requireRecord(id);
+  const config = await service.store.config();
+  if (!config.cleanupOnQuit) {
+    await service.update(id, { status: "paused" });
+    return;
+  }
+  const dirty = (await git(record.worktreePath, ["status", "--porcelain"])).stdout.trim();
+  const unmerged = Number((await git(record.worktreePath, ["rev-list", "--count", `${record.mainBranch}..${record.branch}`])).stdout.trim() || "0");
+
+  const reasons = cleanupBlockers(dirty, unmerged, record.mainBranch);
+  if (reasons.length) {
+    const message = `未清理 ${record.worktreePath}，因为${reasons.join("，")}。Pane 保留，可使用 /agent-resume 恢复。`;
+    await service.update(id, { status: "paused", warnings: [...record.warnings, message] });
+    if (ctx.hasUI) ctx.ui.notify(message, "warning");
+    console.error(`[side-agent] ${message}`);
+    return;
+  }
+
+  await service.update(id, { status: "cleaning" });
+  const script = fileURLToPath(new URL("../scripts/janitor.mjs", import.meta.url));
+  const payload = Buffer.from(JSON.stringify({
+    root: service.root,
+    id,
+    paneId: record.paneId,
+    worktreePath: record.worktreePath,
+    branch: record.branch,
+    mainBranch: record.mainBranch,
+  })).toString("base64url");
+  const child = spawn(process.execPath, [script, payload], {
+    cwd: service.root,
+    detached: true,
+    stdio: "ignore",
+    env: process.env,
+  });
+  child.unref();
+}

package/src/naming.ts

@@ -0,0 +1,37 @@
+import { basename, dirname, join } from "node:path";
+import type { Registry } from "./types.js";
+
+export function featureSlug(raw: string): string {
+  let slug = raw.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!slug) slug = "task";
+  if (!/^[a-z]/.test(slug)) slug = `task-${slug}`;
+  return slug.slice(0, 22).replace(/-+$/g, "") || "task";
+}
+
+export function nextIdentity(repoRoot: string, hint: string, registry: Registry, existingPaths: string[], existingBranches: string[] = []): {
+  id: string;
+  feature: string;
+  number: number;
+  branch: string;
+  worktreePath: string;
+} {
+  const feature = featureSlug(hint);
+  const parent = dirname(repoRoot);
+  const repo = basename(repoRoot);
+  let number = 1;
+  const occupied = new Set(existingPaths);
+  const branches = new Set(existingBranches);
+  while (true) {
+    const suffix = String(number).padStart(4, "0");
+    const id = `${feature}-${suffix}`;
+    const worktreePath = join(parent, `${repo}-agent-${feature}-${suffix}`);
+    if (!registry.agents[id] && !occupied.has(worktreePath) && !branches.has(`side-agent/${id}`)) {
+      return { id, feature, number, branch: `side-agent/${id}`, worktreePath };
+    }
+    number += 1;
+  }
+}
+
+export function taskHint(task: string): string {
+  return featureSlug(task.split(/\s+/).slice(0, 3).join("-"));
+}

package/src/process.ts

@@ -0,0 +1,36 @@
+import { execFile } from "node:child_process";
+
+export interface ProcessResult {
+  stdout: string;
+  stderr: string;
+}
+
+export function exec(command: string, args: string[], options: { cwd?: string; signal?: AbortSignal; allowFailure?: boolean } = {}): Promise<ProcessResult> {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, {
+      cwd: options.cwd,
+      encoding: "utf8",
+      maxBuffer: 16 * 1024 * 1024,
+      windowsHide: true,
+      signal: options.signal,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    }, (error, stdout, stderr) => {
+      const result = { stdout: String(stdout), stderr: String(stderr) };
+      if (error && !options.allowFailure) {
+        reject(new Error(`${command} ${args.join(" ")} failed: ${result.stderr.trim() || error.message}`));
+      } else resolve(result);
+    });
+  });
+}
+
+export async function git(cwd: string, args: string[], signal?: AbortSignal): Promise<ProcessResult> {
+  return exec("git", ["-C", cwd, ...args], { signal });
+}
+
+export function parseJsonOutput<T>(stdout: string, command: string): T {
+  try {
+    return JSON.parse(stdout) as T;
+  } catch {
+    throw new Error(`${command} returned invalid JSON: ${stdout.slice(0, 500)}`);
+  }
+}

package/src/service.ts

@@ -0,0 +1,273 @@
+import { access, mkdir, readdir, readFile, rm, symlink } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { git } from "./process.js";
+import { Herdr, mapHerdrStatus } from "./herdr.js";
+import { choosePlacement } from "./layout.js";
+import { nextIdentity, taskHint } from "./naming.js";
+import { Store } from "./store.js";
+import { ENV, type AgentRecord, type StartResult } from "./types.js";
+
+const quote = (value: string) => `'${value.replace(/'/g, `'"'"'`)}'`;
+const now = () => new Date().toISOString();
+const pathExists = async (path: string) => access(path).then(() => true, () => false);
+
+export function buildBootstrapCommand(startScript: string, root: string, worktree: string, id: string, marker: string): string {
+  // Keep `${marker}:` out of the echoed shell command. wait-output otherwise
+  // matches the command line before the shell has executed the bootstrap.
+  return `marker=${quote(marker)}; if [ -x ${quote(startScript)} ]; then ${quote(startScript)} ${quote(root)} ${quote(worktree)} ${quote(id)}; fi; code=$?; printf '\\n%s:%s\\n' "$marker" "$code"`;
+}
+
+export interface StartOptions { task: string; branchHint?: string; model?: string; resumeId?: string }
+
+export async function repoRoot(cwd: string): Promise<string> {
+  return (await git(cwd, ["rev-parse", "--show-toplevel"])).stdout.trim();
+}
+
+async function worktreePaths(root: string): Promise<string[]> {
+  const output = (await git(root, ["worktree", "list", "--porcelain"])).stdout;
+  return output.split(/\r?\n/).filter(line => line.startsWith("worktree ")).map(line => resolve(line.slice(9).trim()));
+}
+
+async function syncLocalFiles(root: string, worktree: string): Promise<void> {
+  const names = ["side-agent-start.sh", "side-agent-finish.sh", "side-agent-skills"];
+  await mkdir(join(worktree, ".pi"), { recursive: true });
+  for (const name of names) {
+    const source = join(root, ".pi", name);
+    try { await readFile(source); } catch {
+      try { if (!(await readdir(source)).length && name === "side-agent-skills") continue; } catch { continue; }
+    }
+    const target = join(worktree, ".pi", name);
+    await rm(target, { recursive: true, force: true });
+    await symlink(source, target, process.platform === "win32" ? "junction" : undefined);
+  }
+}
+
+export class SideAgentService {
+  constructor(readonly root: string, readonly store = new Store(root), readonly herdr = new Herdr()) {}
+
+  async start(ctx: ExtensionContext, options: StartOptions): Promise<StartResult> {
+    await this.herdr.ensureReady();
+    const config = await this.store.config();
+    if (options.resumeId) return this.resume(ctx, options.resumeId, options.model);
+
+    const branchOutput = (await git(this.root, ["for-each-ref", "--format=%(refname:short)", "refs/heads/side-agent/"])).stdout;
+    const paths = await worktreePaths(this.root);
+    const baseCommit = (await git(this.root, ["rev-parse", `refs/heads/${config.mainBranch}`])).stdout.trim();
+    let record!: AgentRecord;
+    // Allocate and reserve the id under the registry lock. Two parent Pi
+    // sessions may call agent-start concurrently for the same feature.
+    await this.store.mutate(registry => {
+      const identity = nextIdentity(
+        this.root,
+        options.branchHint ?? taskHint(options.task),
+        registry,
+        paths,
+        branchOutput.split(/\r?\n/).filter(Boolean),
+      );
+      record = {
+        ...identity,
+        task: options.task,
+        status: "allocating_worktree",
+        mainBranch: config.mainBranch,
+        baseCommit,
+        warnings: [],
+        parentSessionId: ctx.sessionManager.getSessionFile(),
+        model: options.model,
+        startedAt: now(), updatedAt: now(),
+      };
+      registry.agents[record.id] = record;
+    });
+
+    let paneId: string | undefined;
+    try {
+      await git(this.root, ["worktree", "add", "-b", record.branch, record.worktreePath, baseCommit]);
+      await syncLocalFiles(this.root, record.worktreePath);
+      await this.update(record.id, { status: "spawning_pane" });
+
+      const placement = await this.placement(record.id, config.mainPaneRatio, config.childSplitRatio);
+      const pane = await this.herdr.split({
+        ...placement, cwd: record.worktreePath,
+        env: {
+          [ENV.agentId]: record.id,
+          [ENV.parentSession]: record.parentSessionId ?? "",
+          [ENV.parentRepo]: this.root,
+          [ENV.stateRoot]: this.root,
+        },
+      });
+      paneId = pane.pane_id;
+      // The actual pane id cannot be known until split; the child can also read HERDR_PANE_ID directly.
+      await this.update(record.id, {
+        paneId, tabId: pane.tab_id, workspaceId: pane.workspace_id,
+        herdrAgentName: record.id, status: "starting",
+      });
+
+      const startScript = join(record.worktreePath, ".pi", "side-agent-start.sh");
+      const marker = `__XZ_SIDE_AGENT_BOOTSTRAP_${record.id}__`;
+      const command = buildBootstrapCommand(startScript, this.root, record.worktreePath, record.id, marker);
+      await this.herdr.run(paneId, command);
+      const bootstrap = await this.herdr.waitOutput(paneId, `${marker}:`, 120_000);
+      if (!bootstrap.includes(`${marker}:0`)) throw new Error("side-agent bootstrap failed");
+
+      // Always pass this extension explicitly. This keeps child lifecycle hooks
+      // available when the parent itself was started with `pi -e <local-path>`;
+      // Pi de-duplicates an already installed extension by resolved path.
+      const args: string[] = ["--extension", fileURLToPath(new URL("../index.ts", import.meta.url))];
+      if (options.model) args.push("--model", options.model);
+      const skills = join(record.worktreePath, ".pi", "side-agent-skills");
+      try { await readdir(skills); args.push("--skill", skills); } catch { /* optional */ }
+      const startup = await this.herdr.startAgent(record.id, paneId, args);
+      if (startup === "blocked") {
+        const warning = "Child Pi is blocked during startup; inspect its Herdr pane. The kickoff task will be submitted after it becomes idle.";
+        await this.update(record.id, { status: "blocked", kickoffPending: true, warnings: [...record.warnings, warning] });
+      } else {
+        await this.update(record.id, { status: "running" });
+        await this.herdr.prompt(record.id, `${options.task}\n\nParent Pi session: ${record.parentSessionId ?? "unknown"}`);
+      }
+      return this.result(await this.requireRecord(record.id));
+    } catch (error) {
+      await this.update(record.id, { status: "failed", error: error instanceof Error ? error.message : String(error), finishedAt: now() });
+      if (paneId) await this.herdr.closePane(paneId);
+      const dirty = await git(record.worktreePath, ["status", "--porcelain"]).catch(() => ({ stdout: "dirty", stderr: "" }));
+      const commits = await git(record.worktreePath, ["rev-list", "--count", `${record.baseCommit}..${record.branch}`]).catch(() => ({ stdout: "1", stderr: "" }));
+      if (!dirty.stdout.trim() && Number(commits.stdout.trim()) === 0) {
+        const removed = await git(this.root, ["worktree", "remove", record.worktreePath]).then(() => true, () => false);
+        if (removed) {
+          await git(this.root, ["branch", "-D", record.branch]).catch(() => undefined);
+          await this.store.mutate(registry => { delete registry.agents[record.id]; });
+        }
+      }
+      throw error;
+    }
+  }
+
+  async resume(ctx: ExtensionContext, id: string, model?: string): Promise<StartResult> {
+    const record = await this.requireRecord(id);
+    if (record.status !== "paused" && record.status !== "failed" && record.status !== "crashed") throw new Error(`${id} is not resumable`);
+    if (!record.childSessionId) throw new Error(`${id} has no child session to resume`);
+    if (!(await pathExists(record.worktreePath))) {
+      const branchExists = await git(this.root, ["rev-parse", "--verify", `refs/heads/${record.branch}`]).then(() => true, () => false);
+      if (!branchExists) throw new Error(`${id} cannot resume: branch ${record.branch} no longer exists`);
+      await git(this.root, ["worktree", "add", record.worktreePath, record.branch]);
+      await syncLocalFiles(this.root, record.worktreePath);
+    }
+    let paneId = record.paneId;
+    if (!paneId || !(await this.herdr.getAgent(paneId)) && !(await this.paneExists(paneId))) {
+      const config = await this.store.config();
+      const placement = await this.placement(record.id, config.mainPaneRatio, config.childSplitRatio);
+      const pane = await this.herdr.split({
+        ...placement, cwd: record.worktreePath,
+        env: { [ENV.agentId]: id, [ENV.parentSession]: record.parentSessionId ?? "", [ENV.parentRepo]: this.root, [ENV.stateRoot]: this.root },
+      });
+      paneId = pane.pane_id;
+      await this.update(id, { paneId, tabId: pane.tab_id, workspaceId: pane.workspace_id });
+    }
+    const args = ["--extension", fileURLToPath(new URL("../index.ts", import.meta.url)), "--session", record.childSessionId];
+    if (model) args.unshift("--model", model);
+    const startup = await this.herdr.startAgent(id, paneId, args);
+    await this.update(id, { status: startup === "blocked" ? "blocked" : "waiting_user", finishedAt: undefined, error: undefined });
+    return this.result(await this.requireRecord(id));
+  }
+
+  private async placement(excludeId: string, mainRatio = 0.72, childRatio = 0.5): Promise<{ targetPaneId: string; direction: "right" | "down"; ratio: number }> {
+    const callerPane = process.env.HERDR_PANE_ID;
+    if (!callerPane) throw new Error("HERDR_PANE_ID is missing");
+    const layout = await this.herdr.layout(callerPane);
+    const visible = new Set(layout.panes.map(pane => pane.pane_id));
+    const registry = await this.store.load();
+    const childPaneIds = Object.values(registry.agents)
+      .filter(record => record.id !== excludeId && record.paneId && visible.has(record.paneId) && !["failed", "crashed"].includes(record.status))
+      .map(record => record.paneId!);
+    return choosePlacement(callerPane, layout.panes, childPaneIds, mainRatio, childRatio);
+  }
+
+  private async paneExists(paneId: string): Promise<boolean> {
+    const result = await import("./process.js").then(({ exec }) => exec("herdr", ["pane", "get", paneId], { allowFailure: true }));
+    return Boolean(result.stdout.trim());
+  }
+
+  private async reconcileMissingResources(record: AgentRecord): Promise<AgentRecord | undefined> {
+    if (await pathExists(record.worktreePath)) return record;
+    if (record.paneId && await this.paneExists(record.paneId)) return record;
+
+    const branchExists = await git(this.root, ["rev-parse", "--verify", `refs/heads/${record.branch}`]).then(() => true, () => false);
+    if (branchExists) {
+      const merged = await git(this.root, ["merge-base", "--is-ancestor", record.branch, record.mainBranch]).then(() => true, () => false);
+      if (!merged) {
+        if (record.paneId) return this.update(record.id, { paneId: undefined, tabId: undefined, workspaceId: undefined });
+        return record;
+      }
+      await git(this.root, ["branch", "-D", record.branch]);
+    }
+    await this.store.mutate(registry => { delete registry.agents[record.id]; });
+    return undefined;
+  }
+
+  async refresh(id: string): Promise<AgentRecord | undefined> {
+    const record = (await this.store.load()).agents[id];
+    if (!record) return undefined;
+    if (["paused", "cleaning", "failed", "crashed"].includes(record.status)) return this.reconcileMissingResources(record);
+    if (["allocating_worktree", "spawning_pane", "starting"].includes(record.status) || !record.paneId) return record;
+    const agent = await this.herdr.getAgent(record.herdrAgentName ?? record.paneId);
+    const mapped = mapHerdrStatus(agent?.agent_status);
+    if (mapped === "waiting_user" && record.kickoffPending && record.herdrAgentName) {
+      await this.herdr.prompt(record.herdrAgentName, `${record.task}\n\nParent Pi session: ${record.parentSessionId ?? "unknown"}`);
+      return this.update(id, { status: "running", kickoffPending: false });
+    }
+    if (mapped && mapped !== record.status) return this.update(id, { status: mapped });
+    if (!agent) {
+      const paneExists = await this.paneExists(record.paneId);
+      return this.update(id, { status: "crashed", error: paneExists ? "Child Pi disappeared but its Herdr pane remains" : "Herdr pane disappeared" });
+    }
+    return (await this.store.load()).agents[id];
+  }
+
+  async list(): Promise<AgentRecord[]> {
+    const records = Object.values((await this.store.load()).agents);
+    const refreshed = await Promise.all(records.map(record => this.refresh(record.id)));
+    return refreshed.filter((record): record is AgentRecord => record !== undefined);
+  }
+
+  async send(id: string, prompt: string): Promise<{ ok: boolean; message: string }> {
+    const record = await this.refresh(id);
+    if (!record?.herdrAgentName) return { ok: false, message: `Unknown agent id: ${id}` };
+    let payload = prompt;
+    if (payload.startsWith("!")) {
+      await this.herdr.interrupt(record.herdrAgentName);
+      payload = payload.slice(1).trimStart();
+      if (payload) await new Promise(resolve => setTimeout(resolve, 300));
+    }
+    if (payload) await this.herdr.prompt(record.herdrAgentName, payload);
+    await this.update(id, { status: "running" });
+    return { ok: true, message: `Sent prompt to ${id}` };
+  }
+
+  async check(id: string): Promise<Record<string, unknown>> {
+    const record = await this.refresh(id);
+    if (!record) return { ok: false, error: `Unknown agent id: ${id}` };
+    return { ok: true, agent: record, backlog: record.herdrAgentName ? await this.herdr.readAgent(record.herdrAgentName, 20) : [] };
+  }
+
+  async update(id: string, patch: Partial<AgentRecord>): Promise<AgentRecord> {
+    let result: AgentRecord | undefined;
+    await this.store.mutate(registry => {
+      const record = registry.agents[id];
+      if (!record) throw new Error(`Unknown agent id: ${id}`);
+      Object.assign(record, patch, { updatedAt: now() });
+      result = record;
+    });
+    return result!;
+  }
+
+  async requireRecord(id: string): Promise<AgentRecord> {
+    const record = (await this.store.load()).agents[id];
+    if (!record) throw new Error(`Unknown agent id: ${id}`);
+    return record;
+  }
+
+  private result(record: AgentRecord): StartResult {
+    if (!record.paneId) throw new Error(`Agent ${record.id} has no pane`);
+    return { ok: true, id: record.id, task: record.task, paneId: record.paneId, tabId: record.tabId, workspaceId: record.workspaceId, worktreePath: record.worktreePath, branch: record.branch, warnings: record.warnings };
+  }
+}

package/src/store.ts

@@ -0,0 +1,75 @@
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { Config, Registry } from "./types.js";
+
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+export class Store {
+  readonly dir: string;
+  readonly registryPath: string;
+  readonly lockPath: string;
+  readonly configPath: string;
+
+  constructor(readonly root: string) {
+    this.dir = join(root, ".pi", "side-agents-herdr");
+    this.registryPath = join(this.dir, "registry.json");
+    this.lockPath = join(this.dir, "registry.lock");
+    this.configPath = join(this.dir, "config.json");
+  }
+
+  async config(): Promise<Config> {
+    let value: Config;
+    try { value = JSON.parse(await readFile(this.configPath, "utf8")) as Config; }
+    catch { throw new Error(`Run /skill:agent-setup first; missing ${this.configPath}`); }
+    if (value.version !== 1 || !value.mainBranch) throw new Error(`Invalid config: ${this.configPath}`);
+    value.mainPaneRatio = typeof value.mainPaneRatio === "number" ? value.mainPaneRatio : 0.72;
+    value.childSplitRatio = typeof value.childSplitRatio === "number" ? value.childSplitRatio : 0.5;
+    value.cleanupOnQuit = value.cleanupOnQuit !== false;
+    return value;
+  }
+
+  async load(): Promise<Registry> {
+    try {
+      const value = JSON.parse(await readFile(this.registryPath, "utf8")) as Registry;
+      if (value.version !== 1 || !value.agents) throw new Error("unsupported registry");
+      return value;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 1, agents: {} };
+      throw error;
+    }
+  }
+
+  async save(registry: Registry): Promise<void> {
+    await mkdir(this.dir, { recursive: true });
+    const temporary = `${this.registryPath}.${process.pid}.tmp`;
+    await writeFile(temporary, JSON.stringify(registry, null, 2) + "\n", { mode: 0o600 });
+    await rename(temporary, this.registryPath);
+  }
+
+  async mutate(fn: (registry: Registry) => void | Promise<void>): Promise<Registry> {
+    await mkdir(dirname(this.lockPath), { recursive: true });
+    const started = Date.now();
+    while (true) {
+      try {
+        const handle = await open(this.lockPath, "wx", 0o600);
+        await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+        await handle.close();
+        break;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+        const age = Date.now() - (await stat(this.lockPath).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
+        if (age > 30_000) { await rm(this.lockPath, { force: true }); continue; }
+        if (Date.now() - started > 10_000) throw new Error(`Timed out waiting for ${this.lockPath}`);
+        await sleep(50);
+      }
+    }
+    try {
+      const registry = await this.load();
+      await fn(registry);
+      await this.save(registry);
+      return registry;
+    } finally {
+      await rm(this.lockPath, { force: true });
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,68 @@
+export const ENV = {
+  agentId: "PI_SIDE_AGENT_ID",
+  parentSession: "PI_SIDE_PARENT_SESSION",
+  parentRepo: "PI_SIDE_PARENT_REPO",
+  stateRoot: "PI_SIDE_AGENTS_ROOT",
+} as const;
+
+export type AgentStatus =
+  | "allocating_worktree"
+  | "spawning_pane"
+  | "starting"
+  | "running"
+  | "waiting_user"
+  | "blocked"
+  | "paused"
+  | "cleaning"
+  | "failed"
+  | "crashed";
+
+export interface Config {
+  version: 1;
+  mainBranch: string;
+  mainPaneRatio: number;
+  childSplitRatio: number;
+  cleanupOnQuit: boolean;
+}
+
+export interface AgentRecord {
+  id: string;
+  feature: string;
+  number: number;
+  task: string;
+  status: AgentStatus;
+  mainBranch: string;
+  baseCommit: string;
+  branch: string;
+  worktreePath: string;
+  paneId?: string;
+  tabId?: string;
+  workspaceId?: string;
+  herdrAgentName?: string;
+  parentSessionId?: string;
+  childSessionId?: string;
+  model?: string;
+  kickoffPending?: boolean;
+  startedAt: string;
+  updatedAt: string;
+  finishedAt?: string;
+  error?: string;
+  warnings: string[];
+}
+
+export interface Registry {
+  version: 1;
+  agents: Record<string, AgentRecord>;
+}
+
+export interface StartResult {
+  ok: true;
+  id: string;
+  task: string;
+  paneId: string;
+  tabId?: string;
+  workspaceId?: string;
+  worktreePath: string;
+  branch: string;
+  warnings: string[];
+}