pi-herdsman 0.17.0 → 0.18.0

package/README.md

@@ -46,6 +46,19 @@ to you.
 
 ## Install
 
+### Linux / macOS bootstrap
+
+Install the released, tested Pi / Herdr / Pi Herdsman stack:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.sh | sh
+```
+
+The bootstrapper requires Node `>=22.19.0` and npm. It reconciles the exact Pi
+and Herdr versions declared by the current Pi Herdsman release, pins that Pi
+Herdsman release, verifies the Herdr download, and refreshes the Herdr Pi
+integration. Re-run it to update or repair the stack.
+
 ### Existing Pi / herdr
 
 ```sh

package/dist/index.js

@@ -31,7 +31,7 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 // package.json
 var package_default = {
   name: "pi-herdsman",
-  version: "0.17.0",
+  version: "0.18.0",
   type: "module",
   description: "Asynchronous Pi subagents and agent fleet orchestration for parallel coding agents with nested delegation, background work, and supervision in herdr.",
   license: "Apache-2.0",
@@ -77,6 +77,20 @@ var package_default = {
     ],
     image: "https://raw.githubusercontent.com/boadij/pi-herdsman/main/docs/assets/thumbnail.webp"
   },
+  piHerdsman: {
+    runtime: {
+      pi: "0.87.1",
+      herdr: {
+        version: "0.9.1",
+        sha256: {
+          "linux-x86_64": "2a02fed16beb651ef006e1d43f048f652ca4dc58ad053cd2d44450563d5c54b7",
+          "linux-aarch64": "f4ccf4de745f2cb9a39a983e9ba3703dad50ec2a58dea83026ceab721bbd8d9e",
+          "macos-x86_64": "053be0639935fe54ab5efbdb46651054e4f6a753a5b43153c88bd6912bce1e94",
+          "macos-aarch64": "5fc7a7e7adfaca56fa80aa89dcb025693357268dab8285b9ce2d08a2313c89de"
+        }
+      }
+    }
+  },
   scripts: {
     test: "node --experimental-test-module-mocks --import=./scripts/test-env.mjs --test --test-timeout=10000",
     smoke: "node scripts/smoke.mjs",
@@ -1805,6 +1819,7 @@ var HerdrStartFailure = class extends Error {
 };
 var SETTLE_TIMEOUT = 2e3;
 var START_DIAGNOSTIC_TIMEOUT = 2e3;
+var FRESH_PANE_BUSY_RETRY_TIMEOUT = 2e3;
 var HERDR_START_TIMEOUT_MIN = 3001;
 var HERDR_START_TIMEOUT_MAX = 3e5;
 var STARTUP_TIMEOUT_MIN = HERDR_START_TIMEOUT_MIN + START_DIAGNOSTIC_TIMEOUT;
@@ -2044,6 +2059,12 @@ function sameCwd(observed, expected) {
   if (typeof observed !== "string") return false;
   return canonicalCwd(observed) === canonicalCwd(expected);
 }
+function matchesAttemptTerminal(pane, attempt) {
+  return pane?.pane_id === attempt.paneId && pane.workspace_id === attempt.workspaceId && pane.tab_id === attempt.tabId && pane.terminal_id === attempt.terminalId;
+}
+function matchesAttemptPane(pane, attempt) {
+  return matchesAttemptTerminal(pane, attempt) && sameCwd(pane.cwd, attempt.cwd);
+}
 function capturedShellProcess(process2) {
   return process2.foreground_processes?.find(
     (candidate) => candidate.pid === process2.shell_pid
@@ -2383,6 +2404,7 @@ async function startHerdrAgent(pi, ctx, options) {
   const env = validateEnvironment(options.env ?? []);
   const release = await lockLifecycle(ctx, options.signal);
   let attempt;
+  let retryAttempted = false;
   let stage = "topology";
   try {
     const cwd = canonicalCwd(options.cwd);
@@ -2397,7 +2419,7 @@ async function startHerdrAgent(pi, ctx, options) {
       error("start", "caller pane is required for split placement");
     let tab;
     let panes;
-    let paneId;
+    let createdPane;
     let createdTab = false;
     const tabs = placement.kind === "tab" && !placement.tabId ? void 0 : (await runHerdr(
       pi,
@@ -2461,7 +2483,7 @@ async function startHerdrAgent(pi, ctx, options) {
         }
       );
       tab = made.tab;
-      paneId = made.root_pane.pane_id;
+      createdPane = made.root_pane;
       createdTab = true;
     } else {
       const existingPanes = panes ?? (await runHerdr(
@@ -2511,31 +2533,44 @@ async function startHerdrAgent(pi, ctx, options) {
             timeout: startupCallTimeout(startupDeadline)
           }
         );
-        paneId = split.pane.pane_id;
+        createdPane = split.pane;
       }
     }
-    if (!paneId) error("start", "Herdr did not return a pane");
+    const paneId = createdPane?.pane_id;
+    const terminalId = createdPane?.terminal_id;
+    if (typeof paneId !== "string" || !paneId)
+      error("start", "Herdr did not return a pane");
+    if (typeof terminalId !== "string" || !terminalId)
+      error("start", `pane ${paneId} did not include terminal identity`);
     attempt = {
       herdrAgent: alias(workspaceId, options.label, options.runId),
       workspaceId,
       tabId: tab.tab_id,
       paneId,
+      terminalId,
       cwd,
-      createdTab
+      createdTab,
+      launchMayHaveStarted: false
     };
     let started;
     stage = "pane_readiness";
-    let shell;
     try {
-      shell = await proveShellReady(
+      await waitForShellMarker(
         pi,
         ctx,
         paneId,
-        void 0,
         startupDeadline,
         "start",
         options.signal
       );
+      attempt.shellProcess = await paneProcess(
+        pi,
+        ctx,
+        paneId,
+        options.signal,
+        startupDeadline,
+        true
+      );
     } catch (failure) {
       if (failure instanceof OperationError)
         throw withStartupDiagnostic(
@@ -2551,7 +2586,6 @@ async function startHerdrAgent(pi, ctx, options) {
       throw failure;
     }
     stage = "ownership_capture";
-    attempt.shellProcess = shell;
     const currentPanes = (await runHerdr(pi, ctx, ["pane", "list", "--workspace", workspaceId], {
       signal: options.signal,
       timeout: startupCallTimeout(startupDeadline)
@@ -2559,8 +2593,8 @@ async function startHerdrAgent(pi, ctx, options) {
     const currentPane = currentPanes.find(
       (item) => item.pane_id === paneId
     );
-    if (!currentPane || currentPane.workspace_id !== workspaceId || currentPane.tab_id !== tab.tab_id)
-      error("start", `pane ${paneId} topology changed before launch`);
+    if (!matchesAttemptPane(currentPane, attempt))
+      error("start", `pane ${paneId} identity changed before launch`);
     if (createdTab) {
       const tabPanes = currentPanes.filter(
         (item) => item.tab_id === tab.tab_id
@@ -2568,67 +2602,81 @@ async function startHerdrAgent(pi, ctx, options) {
       if (tabPanes.length !== 1 || tabPanes[0]?.pane_id !== paneId)
         error("start", `tab ${tab.tab_id} topology changed before launch`);
     }
-    if (!sameCwd(currentPane.cwd, cwd))
-      error("start", `pane ${paneId} cwd does not match requested cwd`, {
-        expected_cwd: cwd,
-        observed_cwd: typeof currentPane.cwd === "string" ? currentPane.cwd : null
-      });
     stage = "agent_start";
-    const latest = await paneProcess(
-      pi,
-      ctx,
-      paneId,
-      options.signal,
-      startupDeadline,
-      true
+    const retryDeadline = Math.min(
+      Date.now() + FRESH_PANE_BUSY_RETRY_TIMEOUT,
+      startupDeadline - START_DIAGNOSTIC_TIMEOUT
     );
-    if (!latest || latest.pane_id !== paneId || !sameShellProcessOwner(shell, latest))
-      error("start", `pane ${paneId} shell identity changed before launch`);
-    const remaining = startupCallTimeout(startupDeadline, childTimeout);
-    if (remaining < HERDR_START_TIMEOUT_MIN)
-      error("start", "startup deadline exhausted before agent start");
-    try {
-      started = await runHerdr(
-        pi,
-        ctx,
-        [
-          "agent",
-          "start",
-          attempt.herdrAgent,
-          "--kind",
-          "pi",
-          "--pane",
-          paneId,
-          "--timeout",
-          String(Math.min(remaining, childTimeout)),
-          "--",
-          ...options.extensionPath ? ["--extension", options.extensionPath] : [],
-          "--extension",
-          HERDR_AGENT_STATE_EXTENSION,
-          ...options.agentArgs ?? []
-        ],
-        {
-          signal: options.signal,
-          // Outlive Herdr's own readiness deadline by the diagnostic window so
-          // its structured failure is the one reported. With the identical
-          // value this command's kill always won the race, and "Herdr command
-          // was killed" replaced Herdr's reason.
-          timeout: Math.min(remaining, childTimeout) + START_DIAGNOSTIC_TIMEOUT
-        }
-      );
-    } catch (failure) {
-      if (isUnstructuredResultFailure(failure))
-        throw withStartupDiagnostic(
-          failure,
-          await captureStartupDiagnostic(
-            pi,
-            ctx,
+    for (; ; ) {
+      const remaining = startupCallTimeout(startupDeadline, childTimeout);
+      if (remaining < HERDR_START_TIMEOUT_MIN)
+        error("start", "startup deadline exhausted before agent start");
+      try {
+        started = await runHerdr(
+          pi,
+          ctx,
+          [
+            "agent",
+            "start",
+            attempt.herdrAgent,
+            "--kind",
+            "pi",
+            "--pane",
             paneId,
-            startupDeadline,
-            options.signal
-          )
+            "--timeout",
+            String(Math.min(remaining, childTimeout)),
+            "--",
+            ...options.extensionPath ? ["--extension", options.extensionPath] : [],
+            "--extension",
+            HERDR_AGENT_STATE_EXTENSION,
+            ...options.agentArgs ?? []
+          ],
+          {
+            signal: options.signal,
+            // Outlive Herdr's own readiness deadline by the diagnostic window so
+            // its structured failure is the one reported. With the identical
+            // value this command's kill always won the race, and "Herdr command
+            // was killed" replaced Herdr's reason.
+            timeout: Math.min(remaining, childTimeout) + START_DIAGNOSTIC_TIMEOUT
+          }
         );
-      throw failure;
+        attempt.launchMayHaveStarted = true;
+        break;
+      } catch (failure) {
+        const busy = failure instanceof OperationError && failure.detail.details?.herdrCode === "agent_pane_busy";
+        if (busy && Date.now() < retryDeadline) {
+          retryAttempted = true;
+          const pane = (await runHerdr(pi, ctx, ["pane", "get", paneId], {
+            signal: options.signal,
+            timeout: startupCallTimeout(startupDeadline)
+          })).pane;
+          if (!matchesAttemptPane(pane, attempt))
+            error(
+              "start",
+              `pane ${paneId} identity changed during startup retry`
+            );
+          const remainingRetry = retryDeadline - Date.now();
+          if (remainingRetry > 0)
+            await sleep(Math.min(POLL_INTERVAL, remainingRetry), void 0, {
+              signal: options.signal
+            });
+          if (Date.now() >= retryDeadline) throw failure;
+          continue;
+        }
+        if (!busy) attempt.launchMayHaveStarted = true;
+        if (isUnstructuredResultFailure(failure))
+          throw withStartupDiagnostic(
+            failure,
+            await captureStartupDiagnostic(
+              pi,
+              ctx,
+              paneId,
+              startupDeadline,
+              options.signal
+            )
+          );
+        throw failure;
+      }
     }
     stage = "agent_result";
     const agent = started.agent;
@@ -2640,7 +2688,8 @@ async function startHerdrAgent(pi, ctx, options) {
     attempt.agent = agent;
     return attempt;
   } catch (cause) {
-    if (attempt) throw new HerdrStartFailure(cause, stage, attempt, false);
+    if (attempt)
+      throw new HerdrStartFailure(cause, stage, attempt, retryAttempted);
     throw cause;
   } finally {
     release();
@@ -2718,7 +2767,7 @@ function normalizePaneProcess(value2, paneId, required) {
     ...foreground !== void 0 ? { foreground_processes: Object.freeze(foreground) } : {}
   });
 }
-async function proveShellReady(pi, ctx, paneId, expected, deadline, operation, signal) {
+async function waitForShellMarker(pi, ctx, paneId, deadline, operation, signal) {
   const timeout = () => {
     if (operation === "start") return startupCallTimeout(deadline);
     const remaining = deadline - Date.now();
@@ -2751,11 +2800,17 @@ async function proveShellReady(pi, ctx, paneId, expected, deadline, operation, s
       noResult: true
     }
   );
+}
+async function proveShellReady(pi, ctx, paneId, expected, deadline, operation, signal) {
+  await waitForShellMarker(pi, ctx, paneId, deadline, operation, signal);
+  const timeout = operation === "start" ? startupCallTimeout(deadline) : deadline - Date.now();
+  if (timeout <= 0)
+    error(operation, `pane ${paneId} shell readiness deadline exhausted`);
   const result = await runHerdr(
     pi,
     ctx,
     ["pane", "process-info", "--pane", paneId],
-    { signal, timeout: timeout() }
+    { signal, timeout }
   );
   const value2 = result?.process_info;
   const shell = normalizePaneProcess(value2, paneId, true);
@@ -3026,7 +3081,7 @@ async function rollbackHerdrStart(pi, ctx, started, signal) {
   const release = await lockLifecycle(ctx, signal);
   try {
     const expectedShell = started.shellProcess;
-    if (!expectedShell)
+    if (started.launchMayHaveStarted && !expectedShell)
       error("rollback", `pane ${started.paneId} process ownership is unproven`);
     const listedAgents2 = await runHerdr(pi, ctx, ["agent", "list"], {
       signal
@@ -3042,7 +3097,9 @@ async function rollbackHerdrStart(pi, ctx, started, signal) {
     );
     if (replacement)
       error("rollback", `pane ${started.paneId} has a replacement agent`);
-    if (managed) {
+    if (!started.launchMayHaveStarted && managed)
+      error("rollback", `pane ${started.paneId} agent ownership changed`);
+    if (started.launchMayHaveStarted && managed) {
       const observedSession = sessionIdentity(managed.agent_session);
       const sessionReference = started.sessionReference ?? (observedSession?.kind === "id" ? { id: observedSession.value } : observedSession?.kind === "path" ? { path: observedSession.value } : void 0);
       const initial = await proveExactRunningAgent(
@@ -3128,11 +3185,16 @@ async function rollbackHerdrStart(pi, ctx, started, signal) {
         error("rollback", `tab ${started.tabId} pane ownership is unproven`);
     }
     const pane = (await runHerdr(pi, ctx, ["pane", "get", started.paneId], { signal })).pane;
-    if (!pane || pane.pane_id !== started.paneId || pane.workspace_id !== started.workspaceId || pane.tab_id !== started.tabId)
+    if (!matchesAttemptTerminal(pane, started))
       error("rollback", `pane ${started.paneId} ownership is unproven`);
-    const observed = await paneProcess(pi, ctx, started.paneId, signal);
-    if (!observed || !sameShellProcessOwner(expectedShell, observed))
-      error("rollback", `pane ${started.paneId} process ownership is unproven`);
+    if (started.launchMayHaveStarted || !sameCwd(pane.cwd, started.cwd)) {
+      const observed = await paneProcess(pi, ctx, started.paneId, signal);
+      if (!expectedShell || !observed || !sameShellProcessOwner(expectedShell, observed))
+        error(
+          "rollback",
+          `pane ${started.paneId} process ownership is unproven`
+        );
+    }
     if (!managed) {
       const listedAgents3 = await runHerdr(pi, ctx, ["agent", "list"], {
         signal