pi-herdr-managed-agents 0.1.0-beta.1

package/AUDIT.md

@@ -0,0 +1,81 @@
+# Native harness reliability audit
+
+Compared our standalone extraction against `giuseppecrj/pi-herdr-agents` at [`8a181890479f46d5955d4f1bac3be759a2d39010`](https://github.com/giuseppecrj/pi-herdr-agents/tree/8a181890479f46d5955d4f1bac3be759a2d39010) (npm v1.6.0).
+
+Scope: launch/readiness, process versus turn lifecycle, result delivery, supervision, and recovery. This is a targeted reliability audit, not a comprehensive security certification of either package. The comparison checkout was inspected read-only; its scripts and dependencies were not executed. Fixes below are independent implementations, not copied source.
+
+## Findings fixed in this extraction
+
+### P1 — Early waits could recommend closing a child that was still working
+
+`subagent_wait` returns early if any requested child needs input. Its formatter nevertheless classified other `running` children as `finished`, printed their old final text, and added a terminal-cleanup instruction. Following that instruction could destroy ongoing work.
+
+**Fix:** running, blocked, failed, and completed wait sections are distinct. A running child gets no final output or cleanup instruction. Regression coverage waits on a blocked child plus a working sibling.
+
+Files: `extensions/subagents/index.ts`, `extensions/subagents/manager.test.ts`.
+
+### P1 — Missing prompt evidence caused ambiguous tasks to be replayed
+
+The native backend resent a task when it could not correlate the submitted prompt with its transcript. Missing session hooks or delayed metadata do not prove the first submission did not execute. Side-effecting work could run twice. The same error path assumed an unseen prompt meant a stopped agent and closed its tab.
+
+**Fix:** submit the prompt once. Claude receives a generated native `--session-id`, and the manager knows its expected transcript path before submission; integration metadata is no longer the sole source of that identity. A positively identified pending Claude paste may receive Enter, but the prompt is never pasted again automatically. On missing correlation, report the uncertainty, confirm interruption, and retain the stopped tab for diagnosis; force-close only when interruption cannot be confirmed.
+
+Regression tests run the real native backend and manager through a fake Herdr CLI: missing session hooks can still yield a correlated final answer; absent transcripts cause one submission, an interruption, and no premature tab closure. These are offline simulations, not a claim that the user's historical live failure was reproduced and eliminated.
+
+Files: `extensions/subagents/src/backends/herdr.ts`, `test/native-startup.test.ts`.
+
+### P1 — Pending follow-ups still looked completed
+
+The manager reserved a concurrency slot through a private `restarting` flag, but left its public snapshot completed until the asynchronous `RunStarted` event arrived. A wait/check could return the old result, and pruning could treat the session as disposable. A new run also retained the previous final text.
+
+**Fix:** reserve the new turn's visible `running` state synchronously, clear stale terminal fields, reject overlapping startup sends, and restore the old snapshot if submission fails before `RunStarted`. Regression coverage holds a follow-up at the backend boundary and checks status, waiting, duplicate rejection, failed-send rollback, and cancellation before startup acknowledgement. Cancelling a still-starting follow-up disposes its session so a delayed submission cannot start afterward.
+
+Files: `extensions/subagents/src/manager.ts`, `extensions/subagents/manager.test.ts`.
+
+### P1 — Failed notification sends could lose queued results
+
+The result queue cleared every entry before trying to deliver the batch. If one host `sendMessage` threw, that result and the rest of the batch were lost. A follow-up handler also deleted its deferred result by ID after awaiting submission, which could delete an already-completed new turn instead of the old result.
+
+**Fix:** acknowledge each result only after the host accepts it. Preserve failed and unattempted entries for a later flush. Retract the specific previous result rather than whichever result now occupies that ID. Tests cover ordered delivery, failed sends, reentrant completion, and fast follow-up races. This does not provide transactional exactly-once delivery across process crashes or hosts that accept a message and then throw.
+
+Files: `extensions/subagents/src/result-delivery.ts`, `extensions/subagents/index.ts`, `extensions/subagents/result-delivery.test.ts`.
+
+### P2 — Input-required notification was deferred and acknowledged too early
+
+A blocked child notification used `followUp`, which waits for the parent's entire run to end, despite needing prompt attention. Its version was marked notified before the host send succeeded.
+
+**Fix:** send input-required messages as steering messages (available after the current tool batch), and mark the version only after successful submission. Normal completion still uses deferred follow-ups so explicit waits can consume pending results without duplicate automatic delivery.
+
+File: `extensions/subagents/index.ts`.
+
+### Packaging check — A supposedly clean profile still loaded personal skills
+
+Pi discovers `~/.agents/skills` in addition to its configured agent directory. Isolating only `agentDir` allowed the maintainer's personal skills into the smoke test.
+
+**Fix:** isolate the home environment as well and restore it afterward. The test verifies exactly the published extension and portable skill.
+
+File: `test/package.test.ts`.
+
+## Ideas worth borrowing next
+
+| Idea from the comparison package                                        | Recommendation for our native multi-harness design                                                                                                                                                                               |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Distinct process, turn, and delivery state (`lifecycle.ts`)             | Adopt the invariants, not its entire state machine. The fixes above address concrete conflations. Explicit open/closed session metadata would further improve recovery and cleanup messages.                                     |
+| Explicit session identity before launch (`launch.ts`)                   | Applied to native Claude with its own `--session-id` option; retain each harness's actual CLI and transcript format.                                                                                                             |
+| File wake-ups with bounded reconciliation (`wake.ts`, `supervision.ts`) | Good performance follow-up. Our viewport timer alone launches two `herdr pane read` commands per second per active child. First consider on-demand viewport reads, then shared event-driven supervision with a polling fallback. |
+| Retained managed worktrees (`launch.ts`)                                | Useful for parallel writers, but an explicit new feature: ownership, dirty-state recovery, and cleanup require their own design and tests. Do not silently create worktrees for readers.                                         |
+| Watchers survive reload/session changes (`index.ts`)                    | Potentially useful, but do not copy automatic delivery into a different parent conversation. Define ownership and opt-in handoff first; current teardown behavior is documented.                                                 |
+| Help-request and completion sidecars (`completion.ts`)                  | Useful for Pi-owned children; not directly portable to native Claude/Codex. Keep native transcript correlation unless each harness exposes a supported event channel.                                                            |
+| Built-in roles/model fallback                                           | Not required to fix these bugs. Keep model-neutral self-contained tasks; never automatically replay uncertain side-effecting work on another model.                                                                              |
+
+## Validation and remaining limits
+
+- `npm run check`: passes against Pi 0.85.1.
+- `npm test`: 48 offline tests pass, including native-backend simulations and package allowlist/clean-profile loading.
+- `npm run format:check`: passes.
+- Formatting and Git whitespace checks are release gates.
+- No new runtime dependencies were added by these audit fixes.
+- Real native smoke testing remains pending: the installed Herdr client is 0.8.2/protocol 20 while the user's running server is 0.8.0/protocol 19. The user's server was not stopped or upgraded.
+- Native readiness still contains fixed grace periods. Startup-time permission dialogs, transcript-path changes, and the original screenshot-review failure need live verification before a stable release.
+- These fixes are in the standalone package only; they have not been installed into the maintainer's live Pi setup.
+- The packed archive also loads successfully with production-only dependencies in a fresh home/profile.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Davis
+
+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,130 @@
+# Pi Herdr Managed Agents
+
+Run **Pi, Claude Code, and Codex subagents in separate, auditable Herdr tabs** while Pi keeps ownership of their tasks, follow-up messages, results, and cancellation.
+
+This is an independent community extension, not an official Herdr or Pi product. It is distinct from the separately maintained `pi-herdr-agents` npm package.
+
+**Beta:** native CLI interfaces and transcript formats change. See [limitations](#limitations-and-troubleshooting) before relying on unattended runs.
+
+## Install
+
+From GitHub:
+
+```sh
+pi install git:github.com/Crush53/pi-herdr-managed-agents@v0.1.0-beta.1
+```
+
+From npm (beta):
+
+```sh
+pi install npm:pi-herdr-managed-agents@0.1.0-beta.1
+```
+
+Restart Pi or run `/reload` after installation. Disable any existing extension that registers `subagent_spawn`, the other `subagent_*` tools, `/subagents`, or `/btw` before enabling this one. In particular, don't load this alongside the original `my-pi-setup` subagents extension.
+
+The package does **not** change your model, theme, credentials, or global instructions. Its portable orchestration skill is included; harness-specific review skills are not.
+
+## Requirements and Herdr setup
+
+- Node.js 22.18+ and Pi. Development checks target Pi **0.85.1**; other releases are not yet verified.
+- [Herdr](https://herdr.dev/) for visible native tabs, with a matching client/server version. Outside Herdr, headless backends are used instead.
+- Install and authenticate only the harnesses you want to use: `pi`, `claude`, and/or `codex` on `PATH`.
+
+Install Herdr using its official instructions, then install the native integrations you need:
+
+```sh
+herdr integration install pi
+herdr integration install claude
+herdr integration install codex
+```
+
+These commands update the relevant harness configuration; the package never runs them automatically. Herdr's generated integration files are not bundled, so they can match your installed Herdr version.
+
+Launch Herdr from a trusted project, then launch Pi inside a Herdr pane:
+
+```sh
+herdr
+# In a Herdr terminal:
+pi
+```
+
+## Use
+
+Ask Pi naturally:
+
+> Use a Claude subagent in plan mode to inspect this project and propose a migration plan. Don't implement it. Iterate on the plan with the same agent.
+
+> Ask a Codex subagent to review the changed files while you run the tests. Report its findings when it finishes.
+
+Model hints are interpreted by each harness. Pi inherits the parent model and thinking level by default; Claude and Codex use their own defaults. This package does not require any particular provider or model.
+
+### Tools and commands
+
+| Tool / command    | Purpose                                                                                                                                           |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subagent_spawn`  | Start a self-contained task with `prompt`, `name`, `harness`, optional `working_dir`, `model`, `reasoning_effort`, and Claude-only `mode: "plan"` |
+| `subagent_send`   | Steer a running child or continue a settled session on the same ID                                                                                |
+| `subagent_check`  | Nonblocking snapshot without consuming the result                                                                                                 |
+| `subagent_list`   | List model-visible managed sessions                                                                                                               |
+| `subagent_wait`   | Wait for requested results; return early when a child needs input                                                                                 |
+| `subagent_cancel` | Interrupt work and retain partial transcripts                                                                                                     |
+| `/subagents`      | Dashboard and managed interaction                                                                                                                 |
+| `/btw <question>` | User-invoked background Pi side question                                                                                                          |
+
+Up to **four children** run concurrently, shared across all harnesses and `/btw`. Completion and input-required notifications return to the parent automatically. No polling loop is needed.
+
+Native tabs retain each harness's own UI, skills, and configuration. The parent receives correlated final text, not an arbitrary terminal snapshot. Native session files stay with the harness. Outside Herdr, Pi uses an in-process SDK session, Claude uses the Agent SDK, and Codex uses its app-server protocol.
+
+### Planning and cleanup
+
+Use `mode: "plan"` for planning-only Claude tasks. Iterate through `subagent_send`. At Claude's **Ready to code?** dialog, choosing Yes starts implementation: for planning-only work, choose the revision/feedback option and request the final plan without implementation.
+
+Keep a blocked or follow-up-needed tab open. After collecting the result and finishing immediate follow-up, close only the reported child tab. The package prompts the parent to do this; it does not remove arbitrary user tabs. Shutdown, reload, and session replacement dispose managed sessions and may close their tabs.
+
+## Security and permissions
+
+**These are autonomous processes with access to your machine, not sandboxes.**
+
+- Native Claude execution uses `--dangerously-skip-permissions`; native Codex uses `--dangerously-bypass-approvals-and-sandbox`. The headless Claude and Codex execution backends also bypass native approvals.
+- Claude plan mode uses the harness's native planning permissions instead of its execution bypass flag.
+- Claude/Codex delegation requires a trusted working directory; an untrusted parent cannot obtain bypass access by choosing another directory. Pi child project resources remain trust-gated.
+- Child tool exclusions prevent ordinary nested orchestration through this package. They are **not** a security boundary against an agent executing arbitrary shell commands.
+- Children use your installed agents' authentication and incur their normal provider usage. There is no package telemetry or credential upload.
+- Concurrent children share the working directory unless you explicitly supply separate, trusted directories. There is no automatic Git worktree isolation.
+
+Review tasks and trust settings before delegating destructive or sensitive work.
+
+## Limitations and troubleshooting
+
+- A **Herdr client/server protocol mismatch** prevents agent startup. Save your work and restart Herdr yourself when safe. Stopping its server terminates pane processes; this extension never does that automatically.
+- **Claude prompt not recorded** has been reported on some native startups. This beta assigns Claude a native session UUID before launch and never automatically resends an uncorrelated prompt. Check integrations, the child's terminal, and session metadata before retrying: missing evidence does not prove no work happened. The historical live failure still needs verification with a matching Herdr client/server.
+- A closed native session cannot be reopened with `subagent_send`. A failed run whose session is still open can be continued on the same ID after inspecting state.
+- Input typed directly into an already-settled native terminal is outside Pi's manager. Use `subagent_send` for managed follow-up.
+- Native approval and planning UI changes can affect readiness detection. Only harness-specific correlated final markers count as completion.
+- macOS is the initial native test platform. Other platforms need validation against their Herdr and agent CLI versions.
+
+## Development
+
+```sh
+npm ci
+npm run check
+npm run format:check
+npm test
+npm pack --dry-run
+```
+
+`npm test` is offline: it tests manager concurrency, cancellation, blocked-input wakeups, transcript correlation, trust boundaries, clean-profile loading, and the publish allowlist. `npm run check` supplies TypeScript static checking; formatting is handled by Prettier rather than a separate linter.
+
+Optional headless integration tests use real providers and may incur charges:
+
+```sh
+npm run test:live
+```
+
+No compilation step or install/prepare script is required. Pi loads the TypeScript extension directly. Runtime dependency versions are pinned because Effect is currently a prerelease.
+
+See [RELEASING.md](RELEASING.md) for publishing and the native smoke-test checklist, and [AUDIT.md](AUDIT.md) for the comparative reliability audit and regression fixes.
+
+## Attribution
+
+Extracted from [Crush53/my-pi-setup](https://github.com/Crush53/my-pi-setup), based on Benjamin Davis's [my-pi-setup](https://github.com/davis7dotsh/my-pi-setup). The original MIT copyright and license are preserved in [LICENSE](LICENSE). Herdr integration and standalone packaging by Crush53.

package/RELEASING.md

@@ -0,0 +1,57 @@
+# Releasing
+
+## Validate
+
+```sh
+npm ci
+npm run check
+npm run format:check
+npm test
+npm pack --dry-run
+```
+
+Inspect the tarball file list for credentials, transcripts, personal settings, and missing runtime helpers. Test the packed archive with a fresh Pi profile and production dependencies; loading successfully from a developer checkout alone is not sufficient.
+
+## Native smoke tests
+
+Use a disposable Herdr test session, never stop a user's active server. Ensure the client/server protocols match and integrations are current. Record exact Pi, Herdr, Claude, and Codex versions.
+
+- Start Pi, Claude, and Codex children with a short harmless prompt; require a correlated final response.
+- Send a second prompt to the same ID and verify the new result rather than stale output.
+- Test a long multiline Claude prompt, plus a screenshot path.
+- Start a Claude planner; confirm blocked-input notification and early wait return. Answer a routine question, request a revision, and finish without allowing implementation.
+- Cancel a running child and verify the native process stops.
+- Exercise untrusted-directory rejection without approving any trust prompt.
+- Run outside Herdr and verify headless backends.
+- Close only test-owned tabs and stop only the disposable server.
+
+Do not call a release stable while native startup failures remain unverified or reproducible. Keep prereleases on npm's `beta` tag and mark GitHub releases as prereleases.
+
+## Publish
+
+Authenticate in your own terminal; never put tokens into repository files or prompts:
+
+```sh
+npm login
+npm whoami
+```
+
+Set the next version in `package.json` and update the lockfile and README install examples. Commit reviewed changes, then:
+
+```sh
+npm publish --access public --tag beta
+# Only after publication succeeds:
+git tag v0.1.0-beta.1
+git push origin main --tags
+gh release create v0.1.0-beta.1 --prerelease --generate-notes
+```
+
+`prepublishOnly` reruns static checks, formatting, and offline tests. Publication may require npm's browser-based 2FA approval. Check `npm view pi-herdr-managed-agents@0.1.0-beta.1` before retrying an ambiguous publish failure: published versions cannot be overwritten.
+
+For a GitHub-only beta, create the tag and prerelease without npm publishing and clearly label the npm release as pending.
+
+## Pi gallery
+
+The manifest includes the `pi-package` keyword and an explicit `pi` resource manifest. The [Pi package gallery](https://pi.dev/packages) discovers tagged npm packages; indexing is not necessarily immediate. Do not claim a gallery listing until it is visible.
+
+An optional public MP4 URL in `pi.video` or image URL in `pi.image` can add a gallery preview. Use a demo captured in a clean test workspace, not personal session screenshots.

package/extensions/shared/tool-call-timeout.ts

@@ -0,0 +1,104 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+export const CHILD_TOOL_CALL_TIMEOUT_MS = 3 * 60 * 1_000;
+
+interface ToolRegistry {
+  getAllTools(): Array<{ name: string }>;
+  getToolDefinition(name: string): ToolDefinition | undefined;
+}
+
+function formatTimeout(timeoutMs: number) {
+  if (timeoutMs % 60_000 === 0) {
+    const minutes = timeoutMs / 60_000;
+    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  }
+  if (timeoutMs % 1_000 === 0) {
+    const seconds = timeoutMs / 1_000;
+    return `${seconds} second${seconds === 1 ? "" : "s"}`;
+  }
+  return `${timeoutMs} ms`;
+}
+
+export class ToolCallTimeoutError extends Error {
+  constructor(toolName: string, timeoutMs: number) {
+    super(
+      `Tool call "${toolName}" timed out after ${formatTimeout(timeoutMs)}.`,
+    );
+    this.name = "ToolCallTimeoutError";
+  }
+}
+
+export async function runWithToolCallTimeout<T>(
+  toolName: string,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+  execute: (signal: AbortSignal) => Promise<T>,
+) {
+  const timeoutController = new AbortController();
+  const executionSignal = signal
+    ? AbortSignal.any([signal, timeoutController.signal])
+    : timeoutController.signal;
+  const timeoutError = new ToolCallTimeoutError(toolName, timeoutMs);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(timeoutError);
+      timeoutController.abort(timeoutError);
+    }, timeoutMs);
+  });
+
+  let removeAbortListener: (() => void) | undefined;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    if (!signal) return;
+    const onAbort = () => {
+      reject(
+        signal.reason instanceof Error
+          ? signal.reason
+          : new Error(`Tool call "${toolName}" was aborted.`),
+      );
+    };
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+    removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+  });
+
+  try {
+    return await Promise.race([execute(executionSignal), timeout, aborted]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    removeAbortListener?.();
+  }
+}
+
+/**
+ * Wrap every currently registered child tool with an independent execution
+ * timeout. Calling apply() again is safe and picks up tools registered later.
+ */
+export function createToolCallTimeoutGuard(
+  timeoutMs = CHILD_TOOL_CALL_TIMEOUT_MS,
+) {
+  const wrapped = new WeakSet<ToolDefinition>();
+
+  const wrap = (definition: ToolDefinition) => {
+    if (wrapped.has(definition)) return;
+    wrapped.add(definition);
+
+    const execute = definition.execute;
+    definition.execute = async (toolCallId, params, signal, onUpdate, ctx) =>
+      runWithToolCallTimeout(definition.name, timeoutMs, signal, (signal) =>
+        execute.call(definition, toolCallId, params, signal, onUpdate, ctx),
+      );
+  };
+
+  return {
+    apply(session: ToolRegistry) {
+      for (const { name } of session.getAllTools()) {
+        const definition = session.getToolDefinition(name);
+        if (definition) wrap(definition);
+      }
+    },
+  };
+}