fix(agents): harden subagent orchestration stack

docs/configuration.md

@@ -168,11 +168,15 @@ a wrapper executable when startup needs fixed arguments. `env` maps environment
 variable names to literal string values and preserves empty strings. DevSpace
 does not expand `$NAME` references in these values.
 
-Codex, Claude, Cursor, Copilot, and Grok accept `command` and `env`. OpenCode and
-Pi are embedded, so their provider entries reject both fields. The daemon
-inherits its startup environment, then overlays the provider's `env`. An
-explicit `command` wins over both the inherited command override and a command
-override placed in `env`.
+All subagent providers accept `env`. The daemon inherits its startup
+environment, then overlays the provider's `env` without mutating the daemon's
+process environment. OpenCode receives that environment on its managed server
+process; embedded Pi scopes it to its provider requests and command execution.
+
+Codex, Claude, Cursor, Copilot, and Grok also accept `command`. OpenCode and Pi
+do not expose a command override. For providers that support it, an explicit
+`command` wins over both the inherited command override and a command override
+placed in `env`.
 
 Existing process-level overrides remain supported: `CODEX_COMMAND`,
 `CODEX_HOME`, `CLAUDE_COMMAND`, `CURSOR_COMMAND`, `COPILOT_COMMAND`,

schema/v1/devspace.schema.json

@@ -177,52 +177,92 @@
         "providers": {
           "type": "array",
           "items": {
-            "type": "object",
-            "properties": {
-              "id": {
-                "type": "string",
-                "enum": [
-                  "codex",
-                  "claude",
-                  "opencode",
-                  "pi",
-                  "cursor",
-                  "copilot",
-                  "grok"
-                ]
-              },
-              "enabled": {
-                "type": "boolean"
-              },
-              "model": {
-                "type": "string",
-                "minLength": 1
-              },
-              "effort": {
-                "type": "string",
-                "minLength": 1
-              },
-              "command": {
-                "type": "string",
-                "minLength": 1,
-                "pattern": "\\S"
+            "oneOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "enum": [
+                      "codex",
+                      "claude",
+                      "cursor",
+                      "copilot",
+                      "grok"
+                    ]
+                  },
+                  "enabled": {
+                    "type": "boolean"
+                  },
+                  "model": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "effort": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "env": {
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+                    },
+                    "additionalProperties": {
+                      "type": "string"
+                    }
+                  },
+                  "command": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "\\S"
+                  }
+                },
+                "required": [
+                  "id",
+                  "enabled"
+                ],
+                "additionalProperties": false
               },
-              "env": {
+              {
                 "type": "object",
-                "propertyNames": {
-                  "type": "string",
-                  "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "enum": [
+                      "opencode",
+                      "pi"
+                    ]
+                  },
+                  "enabled": {
+                    "type": "boolean"
+                  },
+                  "model": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "effort": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "env": {
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+                    },
+                    "additionalProperties": {
+                      "type": "string"
+                    }
+                  }
                 },
-                "additionalProperties": {
-                  "type": "string"
-                }
+                "required": [
+                  "id",
+                  "enabled"
+                ],
+                "additionalProperties": false
               }
-            },
-            "required": [
-              "id",
-              "enabled"
-            ],
-            "additionalProperties": false
+            ]
           }
         }
       },

src/local-agent-acp.test.ts

@@ -336,6 +336,7 @@ if (process.platform !== "win32") {
     await writeFile(candidate, `#!/bin/sh\ntouch '${marker}'\nexit 0\n`, { mode: 0o700 });
     await chmod(candidate, 0o700);
     assert.equal(resolveAcpCommand("cursor", { PATH: commandRoot }), candidate);
+    assert.equal(resolveAcpCommand("cursor", { CURSOR_COMMAND: commandRoot }), undefined);
     assert.equal(existsSync(marker), false, "ACP command discovery must not execute PATH candidates");
   } finally {
     await rm(commandRoot, { recursive: true, force: true });

src/local-agent-acp.ts

@@ -1,7 +1,6 @@
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
-import { accessSync, constants } from "node:fs";
 import { createRequire } from "node:module";
-import { delimiter, resolve } from "node:path";
+import { resolve } from "node:path";
 import { Readable, Writable } from "node:stream";
 import {
   AgentProviderProtocolError,
@@ -28,6 +27,7 @@ import type {
   LocalAgentRuntimeContext,
   LocalAgentWriteMode,
 } from "./local-agent-runtime.js";
+import { resolveExecutableCommand } from "./local-agent-command.js";
 
 export type AcpProvider = "cursor" | "copilot" | "grok";
 
@@ -617,20 +617,7 @@ export function resolveAcpCommand(
       ? env.COPILOT_COMMAND
       : env.GROK_COMMAND;
   const command = configured ?? ACP_COMMANDS[provider][0];
-  if (command.includes("/") || command.includes("\\")) return executableExists(command) ? command : undefined;
-  const path = env.PATH;
-  if (!path) return undefined;
-  const extensions = process.platform === "win32"
-    ? ["", ...(env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)]
-    : [""];
-  for (const directory of path.split(delimiter)) {
-    if (!directory) continue;
-    for (const extension of extensions) {
-      const candidate = resolve(directory, `${command}${extension}`);
-      if (executableExists(candidate)) return candidate;
-    }
-  }
-  return undefined;
+  return resolveExecutableCommand(command, env);
 }
 
 export type AcpCommandResolver = (provider: AcpProvider, env: NodeJS.ProcessEnv) => string | undefined;
@@ -829,15 +816,6 @@ function appendTail(current: string, chunk: string, maxBytes: number): string {
   return Buffer.from(next, "utf8").subarray(-maxBytes).toString("utf8");
 }
 
-function executableExists(command: string): boolean {
-  try {
-    accessSync(command, process.platform === "win32" ? constants.F_OK : constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> {
   let timer: NodeJS.Timeout | undefined;
   const timeout = new Promise<never>((_resolve, reject) => {

src/local-agent-adapters.ts

@@ -1,5 +1,6 @@
 import {
   localAgentProviderEnvironment,
+  localAgentProviderEnvironmentOverrides,
   type SubagentsConfig,
 } from "./local-agent-config.js";
 import type { LocalAgentProvider } from "./local-agent-profiles.js";
@@ -45,11 +46,14 @@ export function createLocalAgentDrivers(
   const providerEnv = (provider: LocalAgentProvider) => options.subagents
     ? localAgentProviderEnvironment(options.subagents, provider, env)
     : env;
+  const providerEnvOverrides = (provider: LocalAgentProvider) => options.subagents
+    ? localAgentProviderEnvironmentOverrides(options.subagents, provider)
+    : {};
   return [
     new CodexLocalAgentDriver(providerEnv("codex")),
     new ClaudeLocalAgentDriver(options.claudeQueryFactory, providerEnv("claude")),
-    new OpencodeLocalAgentDriver(options.opencodeFactory),
-    new PiLocalAgentDriver(options.piSessionFactory),
+    new OpencodeLocalAgentDriver(options.opencodeFactory, providerEnv("opencode")),
+    new PiLocalAgentDriver(options.piSessionFactory, providerEnvOverrides("pi")),
     new AcpLocalAgentDriver("cursor", providerEnv("cursor")),
     new AcpLocalAgentDriver("copilot", providerEnv("copilot")),
     new AcpLocalAgentDriver("grok", providerEnv("grok")),

src/local-agent-availability.test.ts

@@ -40,6 +40,7 @@ assert.equal(
       },
       {
         enabled: true,
+        instructions: "on-demand",
         providers: [{
           id: "codex",
           enabled: true,

src/local-agent-availability.ts

@@ -1,9 +1,8 @@
-import { accessSync, constants, statSync } from "node:fs";
-import { delimiter, resolve } from "node:path";
 import {
   LOCAL_AGENT_PROVIDERS,
   type LocalAgentProvider,
 } from "./local-agent-profiles.js";
+import { resolveExecutableCommand } from "./local-agent-command.js";
 import {
   localAgentProviderEnvironment,
   type SubagentsConfig,
@@ -94,40 +93,10 @@ function commandAvailability(
   command: string,
   env: NodeJS.ProcessEnv,
 ): LocalAgentProviderAvailability {
-  if (resolveCommand(command, env)) return { name: provider, available: true };
+  if (resolveExecutableCommand(command, env)) return { name: provider, available: true };
   return {
     name: provider,
     available: false,
     reason: `${command} executable not found`,
   };
 }
-
-function resolveCommand(command: string, env: NodeJS.ProcessEnv): string | undefined {
-  if (!command) return undefined;
-  if (command.includes("/") || command.includes("\\")) {
-    return executableExists(command) ? command : undefined;
-  }
-  const path = env.PATH;
-  if (!path) return undefined;
-  const extensions = process.platform === "win32"
-    ? ["", ...(env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)]
-    : [""];
-  for (const directory of path.split(delimiter)) {
-    if (!directory) continue;
-    for (const extension of extensions) {
-      const candidate = resolve(directory, `${command}${extension}`);
-      if (executableExists(candidate)) return candidate;
-    }
-  }
-  return undefined;
-}
-
-function executableExists(command: string): boolean {
-  const mode = process.platform === "win32" ? constants.F_OK : constants.X_OK;
-  try {
-    accessSync(command, mode);
-    return statSync(command).isFile();
-  } catch {
-    return false;
-  }
-}

src/local-agent-client.ts

@@ -183,6 +183,13 @@ export class LocalAgentClient {
     return this.startupPromise;
   }
 
+  private async ensureReadyForObservation(): Promise<BetterResult<LocalAgentDaemonStatus, AgentDaemonError>> {
+    const existing = await this.tryHello(true);
+    if (existing.isErr()) return existing;
+    if (existing.value) return Result.ok(existing.value);
+    return this.ensureReady();
+  }
+
   private async ensureReadyInternal(): Promise<BetterResult<LocalAgentDaemonStatus, AgentDaemonError>> {
     const existing = await this.tryHello();
     if (existing.isErr()) return existing;
@@ -223,7 +230,9 @@ export class LocalAgentClient {
     }));
   }
 
-  private async tryHello(): Promise<BetterResult<LocalAgentDaemonStatus | undefined, AgentDaemonError>> {
+  private async tryHello(
+    allowStaleBusyConfig = false,
+  ): Promise<BetterResult<LocalAgentDaemonStatus | undefined, AgentDaemonError>> {
     const authToken = this.authTokenResult("hello");
     if (authToken.isErr()) return authToken;
     const response = await sendRequest(this.endpoint, {
@@ -263,6 +272,9 @@ export class LocalAgentClient {
     const decoded = decodeValue(response.value.result, "hello", decodeDaemonHello);
     if (decoded.isErr()) return decoded;
     if (!decoded.value.configMatches) {
+      if (allowStaleBusyConfig && decoded.value.status.activeTurns > 0) {
+        return Result.ok(decoded.value.status);
+      }
       return this.replaceIdleChangedDaemon(authToken.value, decoded.value.status);
     }
     return Result.ok(decoded.value.status.state === "ready" ? decoded.value.status : undefined);
@@ -376,7 +388,9 @@ export class LocalAgentClient {
     params: Extract<LocalAgentDaemonRequest, { method: M }>['params'],
     timeoutMs: number | null = this.requestTimeoutMs,
   ): Promise<BetterResult<unknown, RequestError<M>>> {
-    const ready = await this.ensureReady();
+    const ready = await (isObservationRequest(method)
+      ? this.ensureReadyForObservation()
+      : this.ensureReady());
     if (ready.isErr()) return ready as BetterResult<unknown, RequestError<M>>;
     const authToken = this.authTokenResult(method);
     if (authToken.isErr()) return authToken as BetterResult<unknown, RequestError<M>>;
@@ -475,6 +489,12 @@ export class LocalAgentClient {
   }
 }
 
+function isObservationRequest(
+  method: LocalAgentDaemonRequest["method"],
+): method is "agent.get" | "agent.list" | "agent.wait" {
+  return method === "agent.get" || method === "agent.list" || method === "agent.wait";
+}
+
 export function createLocalAgentClient(
   config: Pick<ServerConfig, "configDir" | "stateDir" | "subagents">,
 ): LocalAgentClient {

src/local-agent-command.ts

@@ -0,0 +1,35 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, resolve } from "node:path";
+
+export function resolveExecutableCommand(
+  command: string,
+  env: NodeJS.ProcessEnv,
+): string | undefined {
+  if (!command) return undefined;
+  if (command.includes("/") || command.includes("\\")) {
+    return isExecutableFile(command) ? command : undefined;
+  }
+  const path = env.PATH;
+  if (!path) return undefined;
+  const extensions = process.platform === "win32"
+    ? ["", ...(env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)]
+    : [""];
+  for (const directory of path.split(delimiter)) {
+    if (!directory) continue;
+    for (const extension of extensions) {
+      const candidate = resolve(directory, `${command}${extension}`);
+      if (isExecutableFile(candidate)) return candidate;
+    }
+  }
+  return undefined;
+}
+
+function isExecutableFile(command: string): boolean {
+  const mode = process.platform === "win32" ? constants.F_OK : constants.X_OK;
+  try {
+    accessSync(command, mode);
+    return statSync(command).isFile();
+  } catch {
+    return false;
+  }
+}