pi-subagents 0.82.1 → 0.83.1

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 ## [Unreleased]
 
+## [0.83.1] - 2026-10-27
+
+### Highlights
+
+- Stopping, interrupting, or resuming a subagent can no longer act on the wrong run: an interrupt with no id is refused, and resuming a worktree child while it is still cleaning up no longer runs it in your main checkout.
+- A mission you start on purpose stays open until its result is checked, instead of showing `completed` on the writer's own report.
+- Capability limits registered by session id, as the docs show, now cover background runs and workflow children, not only foreground launches.
+- Agent files with a blank line inside an indented block are read in full, so settings below that line are no longer dropped.
+
+### Fixed
+
+- `subagent({ action: "interrupt" })` without an id is now refused with "action='interrupt' requires id.", the same as `stop`, `steer`, and `resume`. Before, it interrupted the last foreground run or the newest background run, so a call that lost its id could interrupt the wrong child. When an id matches no run, `stop`, `interrupt`, and `resume` now name that id in the error. Thanks to [@mannainsect](https://github.com/mannainsect) for the report. (#3081)
+- Resuming a background child that ran in its own worktree (`worktree: true`) no longer continues it in your main checkout. If you resumed it in the few seconds while it was saving its changes and removing its worktree, the child could start in your main checkout and commit or switch branches there, or start in a deleted worktree. That resume is now refused with a message to retry once the run finishes cleaning up. Thanks to [@peskycipher](https://github.com/peskycipher) for the report and [@isjiajia01](https://github.com/isjiajia01) for narrowing it down. (#3083)
+- A mission you start with `mission` or `missionId` no longer becomes `completed` when nothing confirmed its result. Before, a background writer run with only its own report marked its mission `completed`, so a claimed result looked like a proven one. When the run, or any workflow child in the mission, ends with acceptance `review-required`, `rejected`, `claimed`, or `pending`, the mission now stays `waiting`, and `mission.show` lists each child's acceptance status. Close it with `mission.close` after you check the result. A `gate` or `acceptance.verify` command alone does not complete a writer run's mission, because writer runs also need a review; add `review: { required: false }` to the `acceptance` policy when the command is enough ([missions.md](docs/missions.md)). Missions created automatically for ordinary launches still complete as before. Thanks to [@kiote](https://github.com/kiote). (#3078)
+- A capability ceiling registered the way the docs show, with `ctx.sessionManager.getSessionId()`, now applies in saved sessions. Before, most checks looked it up by session file path, so background launches, workflow children, and `{ action: "list" }` ignored it and only foreground launches were blocked. Every check now uses the session id, so a ceiling registered by session file path no longer applies. Thanks to [@corobis](https://github.com/corobis) for the report. (#3087)
+- A blank line inside an indented block in an agent file's frontmatter, such as an `external-cli` script argument with an empty line, cut the value off there and dropped every setting below it. The whole block is now read. Lists that used to stop at a blank line, such as `tools:`, now include their later entries, so an agent can get tools it did not get before. `|` and `>` blocks are unchanged. Thanks to [@jbachorik](https://github.com/jbachorik). (#3089)
+- A workflow script that called `runs.run({ key, agent, task })` with a single object passed validation and then failed with "runs.run has an invalid key.". Validation now rejects that call, and both the validation error and the running script show the right forms: `runs.run("plan", { agent, task })` or `runs.all([{ key, agent, task }])`. Thanks to [@brunovcosta](https://github.com/brunovcosta) for the report. (#3088)
+- In a project you have not trusted, agent lookup no longer scans the project's `.git`, `.pi`, and `.agents` folders on every call. It already ignored what was in them, but it still listed them to decide when to refresh, so ordinary git activity made it rebuild its agent list. Thanks to [@ArietidsZ](https://github.com/ArietidsZ). (#3080)
+- Long errors and verdicts in the `runs.lanes` result are now cut at a whole character, so they no longer end in a broken character or go over the 256-byte limit. Thanks to [@XLi-hub](https://github.com/XLi-hub). (#3097)
+
+## [0.83.0] - 2026-10-25
+
+### Highlights
+
+- When an extension or tool search changes the system prompt or tools during a session, subagent results no longer make every later turn miss the prompt cache, so those turns are cheaper and faster again. A child that runs its own subagents keeps its cache too.
+- Subagents that finished their work always report it: background runs no longer end as "exited with code 0 before writing a result", and foreground calls no longer hang when the child stops after its final reply.
+- Children placed on another machine (a Rex tab, Rex over SSH, or a Herdr pane) launch instead of being refused, and workflows no longer crash on Windows standalone Pi builds.
+- Extensions and editors that show subagent activity can refresh on a new event instead of polling, and `bg_wait` now waits for background jobs that other extensions report, such as surf-cli's.
+- A typo in an agent override in settings, such as `modle` or a thinking level like `hgih`, now fails with a "Did you mean" hint instead of being ignored.
+
+### Added
+
+- Extensions and editor integrations that show background subagent activity no longer need to poll for changes. A new `subagent:jobs-changed` event tells them to read `status` again whenever a background run starts, moves to its next step, reports progress, or finishes, including chain and parallel step changes that no event reported before. The RPC `ping` reply now lists it, along with the existing `subagent:async-started` event, and [extension-api.md](docs/extension-api.md#refresh-a-host-view-without-polling) shows how to use them. Thanks to [@raviy06](https://github.com/raviy06) for the proposal. (#3068)
+
+### Fixed
+
+- When an extension or tool search changed the system prompt or tools during a session, the first request of every new turn after the first subagent notice missed the prompt cache, so most of the context was sent uncached again each turn. A child that had called `subagent` missed it on every later request. On models where Pi adds those changes further down the conversation instead of rewriting the start of the prompt (Anthropic and OpenAI models, among others), the way pi-subagents marked its notices and removed parent-only subagent history made Pi move them all back into the start of the prompt, which then changed every turn. Both now leave those changes where they are. Thanks to [@adameq](https://github.com/adameq) for the report. (#3058, #3063)
+- Background subagents that finished their work no longer end as "exited with code 0 before writing a result". When a child stopped after its final reply without reporting that it had settled, or when one of its extensions hung on shutdown, the background runner process exited with the result still unwritten. It now ends the child after its final reply, waits for any compaction that runs after that reply, and waits at most 5 seconds for shutdown handlers. A foreground subagent whose child stops the same way now returns its reply too, instead of the call never returning. Thanks to [@perriea](https://github.com/perriea). (#3051)
+- Background jobs that other extensions report to `bg_wait`, such as surf-cli's or pi-agent-wait's, are now waited for in saved sessions. Before, `bg_wait` and the wait at the end of a `pi -p` run matched a job only when the extension named the session by its file path, so a job named by the session id was ignored and they returned while it was still running. Both forms are now accepted. Thanks to [@cad0p](https://github.com/cad0p) for the report. (#3071)
+- With features turned off in `disabledFeatures`, every `guide` topic now starts with a notice listing what is disabled, and every section with a one-line pointer to that list, not only the `tool-reference` topic. Before, an agent reading the workflow guide with `workflow-scripts` disabled was taught `workflow: true` and `args`, and its call was rejected. With workflow scripts disabled, the notice also says to use the top-level `tasks` or `chain` fields instead. Thanks to [@jefftheai](https://github.com/jefftheai) for the report. (#3057)
+- When text written after a tool call reaches Pi only as a summary, as happens through the Claude Agent SDK used by pi-claude-bridge, a lost ```` ```js workflow ```` block no longer means writing the script to a file first. The error now says to resend the source as `options: { script: "..." }`, which runs it directly. (#3056)
+- A fresh child placed on a machine (a Rex tab, a Rex machine over SSH, or a Herdr pane) launches. Every such launch was refused with "does not support fork, resume, or revival" because each child is handed a local session file path, which placement read as a request to restore a transcript. Builtin agents with a tools list, such as `scout`, can be placed too: their required tools are checked against the tools the remote Pi activates. Forked context is still refused on a machine, and so is a resume that would place the child again, since a placed child's transcript stays on that machine. Thanks to [@honbolau](https://github.com/honbolau) for the report and [@isjiajia01](https://github.com/isjiajia01) for tracing it. (#3043)
+- A misspelled field in a `subagents.agentOverrides` or `agentOverridesByProvider` entry, such as `modle`, was ignored; loading now fails with the settings file, the field, and the nearest known name (`Did you mean 'model'?`). An override's `thinking` must now be a known level (`off` through `max`) or `false`; a typo such as `hgih` used to be appended to the child's model id. Creating or updating an agent with the `subagent` tool now rejects such a level too, instead of writing it into the agent file. Thanks to [@isjiajia01](https://github.com/isjiajia01) for the report. (#3050)
+- Creating an agent with `thinking: off`, or updating one to ` off ` with spaces, now saves `thinking: off` in the agent file. Before, the line was left out, so the agent used the default thinking level instead of none.
+- `extensionBindings` now reach foreground children. Before, an extension in a foreground child saw no `PI_SUBAGENT_EXTENSION_BINDINGS`, or the bindings of the background child that launched it. A foreground child now gets its own bindings while its extensions load and run `session_start`, and the parent's environment is restored afterwards. Thanks to [@crisboarna](https://github.com/crisboarna). (#3049)
+- Workflows no longer crash on Windows standalone Pi builds (Bun 1.3.14) once Bun's transpiler cache is warm. The workflow worker now starts from a file in the package. Thanks to [@temoc](https://github.com/temoc). (#3055)
+- `subagent` calls from providers that send nested tool values as strings, such as `options: { capabilities: "true", timeoutMs: "120000" }`, no longer fail with "must be boolean" or "must be integer". Values inside `options` now get the same type conversion Pi already applies to top-level parameters. Thanks to [@5hiri](https://github.com/5hiri) for the report and [@isjiajia01](https://github.com/isjiajia01) for narrowing it down. (#3048)
+- Child transcripts in `/subagents-fleet`, `subagent` status and inspect replies show each tool call's input (`[tool: bash {"command":"ls"}]`) instead of only the tool name. Thanks to [@kunkun9527](https://github.com/kunkun9527) for the report. (#3053)
+
 ## [0.82.1] - 2026-10-24
 
 ### Highlights

package/bundle/agents.js

@@ -2,14 +2,14 @@ import {
   RUNTIME_AGENT_REGISTER_EVENT,
   RUNTIME_AGENT_REGISTER_VERSION,
   registerAgentViaEvents
-} from "./chunk-43SCHIMD.js";
+} from "./chunk-2S4K53MV.js";
 import {
   registerRuntimeAgent
-} from "./chunk-YKEWIB4M.js";
-import "./chunk-CIZQXJ5Q.js";
-import "./chunk-5LFLVSTM.js";
+} from "./chunk-G2Z6ZH26.js";
+import "./chunk-LNRJCP2Y.js";
+import "./chunk-JEZOSEWG.js";
 import "./chunk-YFCK7H2S.js";
-import "./chunk-Z7KVHQHL.js";
+import "./chunk-QXASAHIA.js";
 export {
   RUNTIME_AGENT_REGISTER_EVENT,
   RUNTIME_AGENT_REGISTER_VERSION,

package/bundle/background-work.js

@@ -5,7 +5,7 @@ import {
   listBackgroundWorkWakeChannels,
   registerBackgroundWorkProvider,
   snapshotBackgroundWork
-} from "./chunk-N2BN7BF5.js";
+} from "./chunk-XA3DY6UG.js";
 export {
   BACKGROUND_WORK_PROTOCOL_VERSION,
   BACKGROUND_WORK_REGISTRY_KEY,

package/bundle/capability-ceiling.js

@@ -8,7 +8,7 @@ import {
   registerSubagentCapabilityCeiling,
   resolveCurrentSubagentCapabilityCeiling,
   resolveSubagentCapabilityCeiling
-} from "./chunk-Z7KVHQHL.js";
+} from "./chunk-QXASAHIA.js";
 export {
   SUBAGENT_CAPABILITY_CEILING_REGISTRY_KEY,
   SUBAGENT_CAPABILITY_CEILING_VERSION,

package/bundle/child-tool-plan.js

@@ -1,11 +1,11 @@
 import {
   resolvePiLaunchToolPlan
-} from "./chunk-4SDU2BZX.js";
+} from "./chunk-V2BZYLEP.js";
 import "./chunk-CTPAE36Y.js";
-import "./chunk-CIZQXJ5Q.js";
-import "./chunk-5LFLVSTM.js";
+import "./chunk-LNRJCP2Y.js";
+import "./chunk-JEZOSEWG.js";
 import "./chunk-YFCK7H2S.js";
-import "./chunk-Z7KVHQHL.js";
+import "./chunk-QXASAHIA.js";
 export {
   resolvePiLaunchToolPlan
 };

package/bundle/{chunk-RMQFMMAT.js → chunk-2D52JFLF.js}

@@ -1,3 +1,9 @@
+import {
+  CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS,
+  getAgentDir,
+  getProjectConfigDir
+} from "./chunk-LNRJCP2Y.js";
+
 // src/runs/shared/rex-machine.ts
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
@@ -67,6 +73,11 @@ function resolveRexLocalPlacement(input) {
   return machine;
 }
 
+// src/runs/shared/herdr-machine.ts
+import { spawnSync as spawnSync3 } from "node:child_process";
+import * as fs3 from "node:fs";
+import * as path3 from "node:path";
+
 // src/runs/shared/herdr-connection.ts
 import { spawn, spawnSync as spawnSync2 } from "node:child_process";
 import * as fs2 from "node:fs";
@@ -127,7 +138,7 @@ function runHerdrRemoteCommandAsync(machine, command, options = {}) {
   return runBoundedCommand(options.sshBin ?? "ssh", [...herdrSshArgs(options.env), machine.target, command], { env: hardenedSshEnv(options.env), timeout: options.timeout, maxBuffer: options.maxBuffer });
 }
 function runBoundedCommand(file, args, options) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const child = spawn(file, args, { env: options.env, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
     const stdout = [], stderr = [], maxBuffer = options.maxBuffer ?? MAX_DISCOVERY_BYTES;
     let stdoutBytes = 0, stderrBytes = 0, error, settled = false, escalation;
@@ -136,7 +147,7 @@ function runBoundedCommand(file, args, options) {
       settled = true;
       clearTimeout(timer);
       if (escalation) clearTimeout(escalation);
-      resolve2({ status, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8"), ...spawnError ? { error: spawnError } : {} });
+      resolve3({ status, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8"), ...spawnError ? { error: spawnError } : {} });
     };
     const terminate = () => {
       child.kill("SIGTERM");
@@ -194,7 +205,7 @@ var SocketRpcClient = class {
     this.#subscriptionAckTimeoutMs = subscriptionAckTimeoutMs;
   }
   call(method, params = {}, timeoutMs = 15e3) {
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const socket = net.createConnection(this.#socketPath);
       let bytes = 0;
       let data = Buffer.alloc(0);
@@ -207,7 +218,7 @@ var SocketRpcClient = class {
         finished = true;
         clearTimeout(timer);
         socket.destroy();
-        error ? reject(error) : resolve2(value);
+        error ? reject(error) : resolve3(value);
       };
       socket.on("connect", () => socket.write(`${JSON.stringify({ id, method, params })}
 `));
@@ -244,8 +255,8 @@ var SocketRpcClient = class {
     const id = String(++this.#next);
     let buffer = Buffer.alloc(0), bytes = 0, acknowledged = false, intentional = false, notified = false, settled = false;
     let resolveAck, rejectAck;
-    const acknowledgement = new Promise((resolve2, reject) => {
-      resolveAck = resolve2;
+    const acknowledgement = new Promise((resolve3, reject) => {
+      resolveAck = resolve3;
       rejectAck = reject;
     });
     const failHandshake = (error) => {
@@ -339,12 +350,12 @@ async function waitForSocket(socketPath, child) {
       }
     } catch {
     }
-    await new Promise((resolve2) => setTimeout(resolve2, 25));
+    await new Promise((resolve3) => setTimeout(resolve3, 25));
   }
   throw new Error("SSH StreamLocal forwarding did not create its local socket.");
 }
 async function terminateChild(child) {
-  const wait = (ms) => child.exitCode !== null || child.signalCode !== null ? Promise.resolve() : Promise.race([new Promise((resolve2) => child.once("exit", () => resolve2())), new Promise((resolve2) => setTimeout(resolve2, ms))]);
+  const wait = (ms) => child.exitCode !== null || child.signalCode !== null ? Promise.resolve() : Promise.race([new Promise((resolve3) => child.once("exit", () => resolve3())), new Promise((resolve3) => setTimeout(resolve3, ms))]);
   if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
   await wait(1e3);
   if (child.exitCode === null && child.signalCode === null) {
@@ -397,12 +408,220 @@ async function connectHerdrMachine(machine, options = {}) {
   return { endpoint, socketPath: primary.socketPath, client: new SocketRpcClient(primary.socketPath), forwardRemoteSocket: sockets.forwardRemoteSocket, close: sockets.close };
 }
 
+// src/runs/shared/herdr-machine.ts
+var MAX_MACHINE_NAME_LENGTH = 128;
+var HERDR_MACHINE_LIST_TIMEOUT_MS = 7500;
+var MAX_HERDR_MACHINE_LIST_BYTES = 1024 * 1024;
+var CONTROL_CHARS = /[\u0000-\u001f\u007f]/u;
+var SUPPORTED_MACHINE_ADAPTERS = new Set(CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS);
+function validateMachineName(value) {
+  const trimmed = value.trim();
+  if (!trimmed) throw new Error("Herdr machine id or label is required.");
+  if (trimmed.length > MAX_MACHINE_NAME_LENGTH) throw new Error(`Herdr machine '${trimmed.slice(0, 24)}\u2026' exceeds ${MAX_MACHINE_NAME_LENGTH} characters.`);
+  if (CONTROL_CHARS.test(trimmed)) throw new Error("Herdr machine id or label contains control characters.");
+  return trimmed;
+}
+function validateTarget(value, requested) {
+  const target = value.trim();
+  if (!target || target.startsWith("-") || /[\s\u0000-\u001f\u007f]/u.test(target)) {
+    throw new Error(`Herdr machine '${requested}' has an ssh target that cannot be passed safely: ${JSON.stringify(target)}.`);
+  }
+  return target;
+}
+function isRemoteAbsolute(value) {
+  return value.startsWith("/") || value === "~" || value.startsWith("~/");
+}
+function validateRemoteCwd(value, requested) {
+  const cwd = value.trim();
+  if (!isRemoteAbsolute(cwd)) throw new Error(`Herdr machine '${requested}' cwd must be an absolute POSIX path or start with '~': ${JSON.stringify(cwd)}.`);
+  if (CONTROL_CHARS.test(cwd)) throw new Error(`Herdr machine '${requested}' cwd contains control characters.`);
+  return cwd.length > 1 ? cwd.replace(/\/+$/u, "") : cwd;
+}
+function parseMachineCatalog(json) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch (error) {
+    throw new Error(`Failed to parse herdr machine list --json: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const entries = Array.isArray(parsed) ? parsed : parsed && typeof parsed === "object" && Array.isArray(parsed.machines) ? parsed.machines : void 0;
+  if (!entries) throw new Error("herdr machine list --json returned no machine list.");
+  return entries.flatMap((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
+    const record = entry;
+    if (typeof record.id !== "string" || !record.id.trim() || typeof record.target !== "string") return [];
+    return [{
+      id: record.id.trim(),
+      ...typeof record.label === "string" && record.label.trim() ? { label: record.label.trim() } : {},
+      target: record.target,
+      ...typeof record.session === "string" && record.session.trim() ? { session: record.session.trim() } : {},
+      enabled: record.enabled !== false
+    }];
+  });
+}
+function readHerdrMachineCatalog(env, herdrBin) {
+  const result = spawnSync3(herdrBin, ["machine", "list", "--json"], {
+    env,
+    encoding: "utf-8",
+    maxBuffer: MAX_HERDR_MACHINE_LIST_BYTES,
+    timeout: HERDR_MACHINE_LIST_TIMEOUT_MS,
+    windowsHide: true
+  });
+  if (result.error) {
+    const code = result.error.code;
+    if (code === "ENOENT") throw new Error(`Herdr CLI '${herdrBin}' was not found on PATH. Saved-machine placement needs Herdr installed locally.`);
+    throw new Error(`Failed to run herdr machine list --json: ${result.error.message}`);
+  }
+  if (result.status !== 0) throw new Error(`herdr machine list --json exited with code ${result.status}: ${(result.stderr || result.stdout).trim()}`);
+  return parseMachineCatalog(result.stdout);
+}
+function selectMachine(catalog, requested) {
+  const byId = catalog.find((entry) => entry.id === requested);
+  const matches = byId ? [byId] : catalog.filter((entry) => entry.label === requested);
+  if (matches.length > 1) throw new Error(`Machine label '${requested}' is ambiguous; use its profile ID.`);
+  const machine = matches[0];
+  if (!machine) {
+    const saved = catalog.filter((entry) => entry.enabled).map((entry) => entry.label ?? entry.id);
+    throw new Error(`Herdr machine '${requested}' was not found. Saved machines: ${saved.length ? saved.join(", ") : "none"}. Add one with herdr machine add <target> --label <name>.`);
+  }
+  if (!machine.enabled) throw new Error(`Machine '${requested}' is disabled. Run herdr machine enable ${machine.id}.`);
+  return machine;
+}
+function readJsonObject(filePath) {
+  if (!fs3.existsSync(filePath)) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(fs3.readFileSync(filePath, "utf-8"));
+  } catch (error) {
+    throw new Error(`Failed to read settings file '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+}
+function machineSettingsFrom(settings, keys, filePath) {
+  const subagents = settings.subagents;
+  if (!subagents || typeof subagents !== "object" || Array.isArray(subagents)) return void 0;
+  const machines = subagents.machines;
+  if (machines === void 0) return void 0;
+  if (!machines || typeof machines !== "object" || Array.isArray(machines)) throw new Error(`Subagent settings in '${filePath}' have invalid 'machines'; expected an object keyed by machine label or id.`);
+  const key = keys.find((candidate) => candidate in machines);
+  if (key === void 0) return void 0;
+  const value = machines[key];
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Subagent settings in '${filePath}' have invalid 'machines.${key}'; expected an object with 'cwd' and optional 'env'.`);
+  const record = value;
+  const entry = {};
+  if (record.cwd !== void 0) {
+    if (typeof record.cwd !== "string" || !record.cwd.trim()) throw new Error(`Subagent settings in '${filePath}' have invalid 'machines.${key}.cwd'; expected a non-empty string.`);
+    entry.cwd = validateRemoteCwd(record.cwd, key);
+  }
+  if (record.env !== void 0) {
+    if (!record.env || typeof record.env !== "object" || Array.isArray(record.env) || Object.entries(record.env).some(([name, item]) => !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name) || typeof item !== "string")) {
+      throw new Error(`Subagent settings in '${filePath}' have invalid 'machines.${key}.env'; expected an object of string values keyed by variable name.`);
+    }
+    entry.env = { ...record.env };
+    if (Object.keys(entry.env).length > 0) {
+      throw new Error(`Subagent settings in '${filePath}' set 'machines.${key}.env'. Saved-machine runs use the remote Herdr/Pi environment; configure credentials and environment on '${key}' and remove the local env map.`);
+    }
+  }
+  if (record.rex !== void 0) {
+    const rex = record.rex, ssh = rex && typeof rex === "object" && !Array.isArray(rex) && Object.keys(rex).every((field) => field === "ssh") ? rex.ssh : void 0;
+    if (typeof ssh !== "string") throw new Error(`Subagent settings in '${filePath}' have invalid 'machines.${key}.rex'; expected { "ssh": "<ssh target>" }.`);
+    entry.rex = { ssh: validateTarget(ssh, key) };
+  }
+  return entry;
+}
+function readMachineSettings(cwd, keys) {
+  const userPath = path3.join(getAgentDir(), "settings.json");
+  const projectPath = path3.join(getProjectConfigDir(findProjectRootForSettings(cwd)), "settings.json");
+  const user = machineSettingsFrom(readJsonObject(userPath), keys, userPath);
+  const project = projectPath === userPath ? void 0 : machineSettingsFrom(readJsonObject(projectPath), keys, projectPath);
+  if (project?.rex) throw new Error(`Project settings '${projectPath}' set a Rex SSH host in 'machines'. Move the rex entry to your user settings '${userPath}'; only user settings choose which host a task runs on.`);
+  if (!user && !project) return void 0;
+  return { ...user, ...project };
+}
+function userRexMachine(machine) {
+  const userPath = path3.join(getAgentDir(), "settings.json");
+  return machineSettingsFrom(readJsonObject(userPath), [machine], userPath)?.rex !== void 0;
+}
+function findProjectRootForSettings(cwd) {
+  let current = path3.resolve(cwd);
+  while (true) {
+    if (fs3.existsSync(path3.join(getProjectConfigDir(current), "settings.json"))) return current;
+    const parent = path3.dirname(current);
+    if (parent === current) return path3.resolve(cwd);
+    current = parent;
+  }
+}
+function remoteMachineCwd(stepCwd, root, name) {
+  const step = stepCwd?.trim();
+  if (step && isRemoteAbsolute(step)) return step;
+  if (!root) throw new Error(`No root for ${name} in this repo. Set subagents.machines.${name}.cwd in .pi/settings.json or pass an absolute cwd on that machine.`);
+  return step ? path3.posix.join(root, step) : root;
+}
+function resolveHerdrMachinePlacement(input) {
+  const requested = validateMachineName(input.machine);
+  const catalog = input.catalogJson !== void 0 ? parseMachineCatalog(input.catalogJson) : readHerdrMachineCatalog(input.env ?? process.env, input.herdrBin ?? process.env.HERDR_BIN ?? "herdr");
+  const selected = selectMachine(catalog, requested);
+  const name = selected.label ?? selected.id;
+  const keys = [.../* @__PURE__ */ new Set([requested, ...selected.label ? [selected.label] : [], selected.id])];
+  const settings = input.settings ?? readMachineSettings(input.cwd, keys);
+  if (settings?.env && Object.keys(settings.env).length > 0) {
+    throw new Error(`Saved-machine environment for '${name}' must be configured remotely. Remove machines.${name}.env and configure the remote Herdr/Pi session instead.`);
+  }
+  const cwd = remoteMachineCwd(input.stepCwd, settings?.cwd, name);
+  return {
+    machine: {
+      provider: "herdr",
+      id: selected.id,
+      ...selected.label ? { label: selected.label } : {},
+      target: validateTarget(selected.target, requested),
+      ...selected.session && selected.session !== "default" ? { session: selected.session } : {},
+      cwd: validateRemoteCwd(cwd, requested)
+    },
+    ...settings?.env ? { env: settings.env } : {}
+  };
+}
+function resolveMachinePlacement(input) {
+  const requested = validateMachineName(input.machine);
+  const settings = input.settings ?? readMachineSettings(input.cwd, [requested]);
+  if (requested === REX_LOCAL_MACHINE) {
+    if (settings?.rex) throw new Error("Machine 'local' is reserved for a Rex pane on this machine; give the Rex SSH host in subagents.machines.local.rex another name.");
+    return { machine: resolveRexLocalPlacement({ cwd: input.cwd, stepCwd: input.stepCwd, env: input.env }) };
+  }
+  if (settings?.rex) return { machine: { provider: "rex", id: requested, target: settings.rex.ssh, cwd: validateRemoteCwd(remoteMachineCwd(input.stepCwd, settings.cwd, requested), requested) } };
+  return resolveHerdrMachinePlacement(input);
+}
+var PLACED_RESTORE_UNSUPPORTED = "Pane-native remote Pi does not support fork, resume, or revival; use fresh context.";
+function formatHerdrMachineRunnerUnsupported(input) {
+  if (input.machine === void 0) return void 0;
+  const name = input.machine.trim();
+  let rex;
+  try {
+    rex = name === REX_LOCAL_MACHINE || userRexMachine(name);
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  if (rex) {
+    if (input.runnerType !== void 0 && input.runnerType !== "pi") return `Agent '${input.agentName}' requested machine '${name}', but Rex supports native Pi children only. Remove the machine or use a native Pi agent.`;
+    if (input.worktree === true) return `Agent '${input.agentName}' requested machine '${name}', but managed worktrees cannot be combined with machine placement.`;
+    if (process.platform === "win32") return `Machine '${name}' runs the child in a Rex pane, which is not supported on Windows.`;
+    return void 0;
+  }
+  if (input.runnerType !== void 0 && input.runnerType !== "pi" && input.runnerType !== "external-cli") {
+    return `Agent '${input.agentName}' requested machine '${input.machine}', but this runner cannot use pane-native Herdr placement. Use native Pi or a built-in Claude, Codex, or Cursor profile.`;
+  }
+  if (input.runnerType === "external-cli" && (input.adapter === void 0 || !SUPPORTED_MACHINE_ADAPTERS.has(input.adapter))) {
+    return `Agent '${input.agentName}' requested machine '${input.machine}', but generic external-cli commands cannot be remote-wrapped safely. Use claude-code, claude-code-writer, codex-exec, codex-exec-writer, cursor-agent, or cursor-agent-writer.`;
+  }
+  if (input.worktree === true) return `Agent '${input.agentName}' requested machine '${input.machine}', but managed worktrees are local git operations and cannot be combined with a Herdr saved machine.`;
+  if (process.platform === "win32") return "Herdr saved-machine pane transport requires hardened OpenSSH StreamLocal forwarding, which is not supported from a Windows host yet.";
+  return void 0;
+}
+
 export {
   remoteShellCommand,
   runBoundedCommand,
   sshMachineAccess,
   connectHerdrMachine,
-  REX_LOCAL_MACHINE,
   REX_EXIT_GONE,
   REX_EXIT_UNREACHABLE,
   isRexLocalMachine,
@@ -412,5 +631,7 @@ export {
   rexGlobalArgs,
   resolveRexBinary,
   rexCommandEnv,
-  resolveRexLocalPlacement
+  resolveMachinePlacement,
+  PLACED_RESTORE_UNSUPPORTED,
+  formatHerdrMachineRunnerUnsupported
 };

package/bundle/{chunk-52UBALJL.js → chunk-2DHZTCOL.js}

@@ -3,11 +3,11 @@ import {
 } from "./chunk-7J4ZXMY7.js";
 import {
   getProjectSubagentsDir
-} from "./chunk-5TYMSZX3.js";
+} from "./chunk-D3JAFGMO.js";
 import {
   getPiSpawnCommand,
   writeAtomicJson
-} from "./chunk-CIZQXJ5Q.js";
+} from "./chunk-LNRJCP2Y.js";
 
 // src/inspectors/herdr/project-panes.ts
 import * as fs from "node:fs";

package/bundle/{chunk-43SCHIMD.js → chunk-2S4K53MV.js}

@@ -1,6 +1,6 @@
 import {
   registerRuntimeAgent
-} from "./chunk-YKEWIB4M.js";
+} from "./chunk-G2Z6ZH26.js";
 
 // src/agents/runtime-agent-events.ts
 var RUNTIME_AGENT_REGISTER_EVENT = "pi-subagents:runtime-agent-register:v1";