@erichll/pi-sandbox 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.7.0 - 2026-08-17
+
+- **Builtin `subagent` model fail-fast.** An explicit `model` on `start`/
+  `handoff` is now validated against the host model registry before a child Pi
+  spawns. Unknown models fail before any session/broker/process is created;
+  ambiguous bare ids are rejected with a `provider/model` hint; a trailing
+  `:thinking` suffix is preserved; `status`/`wait`/`stop`/`follow_up` are never
+  intercepted.
+
+- **FleetView external-worker display.** Declare `pi-subagents >=0.50.0` as an
+  **optional** peer dependency (no forced install for builtin/off users) and
+  mirror pi-sandbox's isolated external workers into pi-subagents' FleetView
+  (caller-owned `external-runs`) whenever `subagents.provider ===
+  "pi-subagents"` AND `externalWorkerIsolation === "enforce"`. Loading uses a
+  dynamic import only; import/registry failures disable the display path
+  without weakening fail-closed isolation or network approval. v1 records are
+  `running`-only and cleaned up on worker unregister, session shutdown, and
+  supervisor replacement.
+
+- **`pi-subagents` capability baseline raised to `0.50.0`** (test/CI only;
+  does not affect the published runtime). The dev dependency is pinned exactly
+  to `0.50.0`, the capability boundary is redocumented, the compatibility-gate
+  entry resolves through the package `exports["."]` via `import.meta.resolve`,
+  and the external-isolation probe is generalized. Verified by
+  `gate:external-isolation` and the model-backed `gate:pi-subagents`
+  (`PASS`, `piSubagents: 0.50.0`).
+
 ## 0.6.2 - 2026-08-13
 
 - Bump `@erichll/pi-auto-review` to `0.3.5` so consumers inherit the raised

package/README.md

@@ -82,12 +82,16 @@ Supported modes:
   itself is not wrapped while `externalWorkerIsolation` is `off`.
 - `off`: protect Bash only.
 
-### `pi-subagents` 0.45.2 capability boundary
+### `pi-subagents` 0.50.0 capability boundary
 
 `pi-sandbox` verifies the following combination in its test suite and release
-gate:
+gate. This version boundary is pinned exactly (see the package
+`devDependencies`) and additionally exercised against the latest published
+`pi-subagents` on a nightly CI schedule. The `PI_SUBAGENT_PI_BINARY` seam
+(`externalWorkerIsolation: "enforce"`) is re-checked deterministically by the
+`gate:external-isolation` probe on the pinned and latest dependency.
 
-| Capability | `builtin` | `pi-subagents` 0.45.2 |
+| Capability | `builtin` | `pi-subagents` 0.50.0 |
 | --- | --- | --- |
 | Outer worker sandbox | Yes | Opt-in (`externalWorkerIsolation: "enforce"`) |
 | Bash sandbox | Yes | Yes |
@@ -95,6 +99,11 @@ gate:
 | `workflowScript`, missions, schedules | No | Yes |
 | permission-system parent forwarding | Not required | Verified by compatibility gate |
 
+Upgrading across a capability boundary (for example `0.49.0` → `0.50.0`)
+requires re-running `npm run gate:external-isolation` and, before a release,
+the model-backed `npm run gate:pi-subagents`. See `docs/compat-notes.md` for
+the recorded compatibility seams and how each is verified on upgrade.
+
 For the external provider, `off` leaves the worker process outside the outer
 Sandbox Runtime boundary. Do not treat inherited Bash sandboxing as complete
 worker isolation unless the trusted global configuration explicitly enables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-sandbox",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Sandbox Runtime-backed Linux and macOS sandbox with pi-auto-review approval",
   "type": "module",
   "license": "Apache-2.0",
@@ -54,13 +54,19 @@
     "@erichll/pi-auto-review": "0.3.5"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.82.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "pi-subagents": ">=0.50.0",
     "typebox": ">=1.0.0"
   },
+  "peerDependenciesMeta": {
+    "pi-subagents": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.83.0",
-    "@types/node": "^22.15.3",
-    "pi-subagents": "^0.47.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@types/node": "^26.2.0",
+    "pi-subagents": "0.50.0",
     "typescript": "^6.0.3"
   }
 }

package/src/external-runs-view.ts

@@ -0,0 +1,173 @@
+// Optional FleetView integration for pi-sandbox's isolated external workers.
+//
+// When the host is running the external `pi-subagents` provider with
+// `externalWorkerIsolation: "enforce"`, pi-sandbox supervises the external
+// worker process trees itself. This module mirrors those supervised workers
+// into pi-subagents' caller-owned external-run registry so they show up in the
+// FleetView (pi-subagents >= 0.50.0).
+//
+// This is a pure observability enhancement: it participates in NO sandbox
+// allow/deny decision, and nothing here can downgrade an isolated worker into
+// host execution. `pi-subagents/external-runs` is loaded via a DYNAMIC import
+// only (never a top-level static import), because pi-subagents is an OPTIONAL
+// peer dependency: builtin/off deployments may not have it installed.
+//
+// Deliberate scope of v1: records are "running" only. No completed/failed/
+// endedAt are fabricated because neither the launcher nor the supervisor
+// protocol currently reports process exit evidence to this extension (the
+// record would therefore be a lie). See docs/compat-notes.md seam 5.
+
+type ExternalRunState = "running";
+
+/** Structural view of the specific pi-subagents API we consume. */
+type ExternalRunsApi = {
+  registerExternalRun(input: {
+    id: string;
+    sessionId: string;
+    source: string;
+    label: string;
+    state: ExternalRunState;
+    startedAt: number;
+    preview?: string;
+  }): unknown;
+  unregisterExternalRun(sessionId: string, id: string): boolean;
+};
+
+export type ExternalRunsView = {
+  /** Whether the pi-subagents runtime is reachable (dynamic import succeeded). */
+  readonly enabled: boolean;
+  /** Diagnostic string when the runtime is disabled. */
+  readonly error?: string;
+  /** Mirror a supervisor lifecycle.registered event into the registry. */
+  registered(worker: { id: string; cwd: string; startedAt: number }): void;
+  /** Mirror a supervisor lifecycle.unregistered event out of the registry. */
+  unregistered(workerId: string): void;
+  /** Unregister every run this view registered (session shutdown / replace). */
+  close(): void;
+};
+
+const VIEW_LABEL = "isolated pi-subagents worker";
+const VIEW_SOURCE = "pi-sandbox";
+
+/**
+ * Whether the FleetView integration should be enabled for a given provider /
+ * isolation combination. It is enabled ONLY when the external pi-subagents
+ * provider owns orchestration AND outer worker isolation is enforced -- the
+ * sole case where pi-sandbox actually supervises external workers and can
+ * truthfully vouch for a "running" record it owns.
+ */
+export function externalRunsViewEnabledWhen(
+  provider: string,
+  externalWorkerIsolation: string,
+): boolean {
+  return provider === "pi-subagents" && externalWorkerIsolation === "enforce";
+}
+
+function ident(value: string): { ok: true; value: string } | { ok: false; error: string } {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed !== value) {
+    return { ok: false, error: "must be a non-empty trimmed string" };
+  }
+  return { ok: true, value: trimmed };
+}
+
+export function createExternalRunsView(
+  sessionIdInput: string,
+  load: () => Promise<unknown> = () => import("pi-subagents/external-runs"),
+): Promise<ExternalRunsView> {
+  return (async () => {
+    const sessionId = ident(sessionIdInput);
+    if (!sessionId.ok) {
+      return disabledView(`invalid session id: ${sessionId.error}`);
+    }
+    let api: ExternalRunsApi | undefined;
+    let loadError: string | undefined;
+    try {
+      const mod = (await load()) as Record<string, unknown>;
+      const registerExternalRun = mod.registerExternalRun;
+      const unregisterExternalRun = mod.unregisterExternalRun;
+      if (typeof registerExternalRun !== "function" || typeof unregisterExternalRun !== "function") {
+        throw new Error("pi-subagents/external-runs does not expose registerExternalRun/unregisterExternalRun");
+      }
+      api = { registerExternalRun, unregisterExternalRun } as unknown as ExternalRunsApi;
+    } catch (error) {
+      loadError = `FleetView external-run registration unavailable: ${error instanceof Error ? error.message : String(error)}`;
+      // Never thrown: disable only the display path. Sandbox fail-closed and
+      // network approval for the supervisor are untouched.
+      return disabledView(loadError);
+    }
+
+    // (sessionId, workerId) pairs this extension registered, so we never
+    // duplicate-register and never unregister records owned by other sources.
+    const registered = new Map<string, number>();
+
+    return {
+      get enabled() {
+        return Boolean(api);
+      },
+      error: loadError,
+      registered(worker) {
+        const fullId = ident(worker.id);
+        const cwd = ident(worker.cwd);
+        if (!api || !fullId.ok || !cwd.ok) return;
+        if (registered.has(fullId.value)) return; // avoid duplicate registration
+        try {
+          api!.registerExternalRun({
+            id: fullId.value,
+            sessionId: sessionId.value,
+            source: VIEW_SOURCE,
+            label: VIEW_LABEL,
+            state: "running",
+            startedAt:
+              Number.isSafeInteger(worker.startedAt) && worker.startedAt > 0
+                ? worker.startedAt
+                : Date.now(),
+            preview: cwd.value,
+          });
+          registered.set(fullId.value, Date.now());
+        } catch (error) {
+          // Registry full / malformed record / unknown fields: log, do not emit.
+          console.error(
+            `pi-sandbox: could not register external run for worker '${fullId.value}': ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+      },
+      unregistered(workerId) {
+        const fullId = ident(workerId);
+        if (!fullId.ok) return;
+        if (!registered.has(fullId.value)) return; // we did not register it
+        registered.delete(fullId.value);
+        if (api) {
+          try {
+            api.unregisterExternalRun(sessionId.value, fullId.value);
+          } catch {
+            // Best-effort; nothing else to fall back to.
+          }
+        }
+      },
+      close() {
+        for (const workerId of registered.keys()) {
+          if (api) {
+            try {
+              api.unregisterExternalRun(sessionId.value, workerId);
+            } catch {
+              // best-effort
+            }
+          }
+        }
+        registered.clear();
+      },
+    };
+  })();
+}
+
+function disabledView(error: string): ExternalRunsView {
+  console.error(`pi-sandbox: ${error}`);
+  return {
+    enabled: false,
+    error,
+    registered() {},
+    unregistered() {},
+    close() {},
+  };
+}

package/src/external-supervisor.ts

@@ -20,6 +20,13 @@ type Request = {
   port?: unknown;
 };
 
+export type ExternalWorkerSupervisorLifecycle = {
+  /** Called immediately after a worker finishes the register protocol. */
+  registered?(worker: { id: string; cwd: string; startedAt: number }): void;
+  /** Called immediately after a worker completes the unregister protocol. */
+  unregistered?(worker: { id: string; cwd: string }): void;
+};
+
 export type ExternalWorkerSupervisor = {
   socketPath: string;
   capability: string;
@@ -35,6 +42,7 @@ export type ExternalWorkerSupervisor = {
 
 export async function createExternalWorkerSupervisor(
   approvalContext: (worker: { id: string; cwd: string }) => TrapApprovalContext,
+  lifecycle: ExternalWorkerSupervisorLifecycle = {},
 ): Promise<ExternalWorkerSupervisor> {
   const directory = await mkdtemp(join(tmpdir(), "pi-sandbox-external-"));
   await chmod(directory, 0o700);
@@ -94,6 +102,11 @@ export async function createExternalWorkerSupervisor(
           requests: 0,
         });
         socket.write(`${JSON.stringify({ id: request.id, action: "allow" })}\n`);
+        lifecycle.registered?.({
+          id: request.workerId as string,
+          cwd: request.cwd as string,
+          startedAt: workers.get(request.workerId as string)!.startedAt,
+        });
         return;
       }
       const knownWorker =
@@ -106,6 +119,10 @@ export async function createExternalWorkerSupervisor(
         seen.add(request.id as string);
         knownWorker.state = "exited";
         socket.write(`${JSON.stringify({ id: request.id, action: "allow" })}\n`);
+        lifecycle.unregistered?.({
+          id: request.workerId as string,
+          cwd: request.cwd as string,
+        });
         return;
       }
       const workerCwd =

package/src/index.ts

@@ -31,11 +31,17 @@ import type {
   ProcessBackedSubagentManager,
   ProcessBackedSubagentSession,
 } from "./subagent.ts";
+import { validateSubagentModel } from "./subagent.ts";
 import { Type } from "typebox";
 import {
   createExternalWorkerSupervisor,
   type ExternalWorkerSupervisor,
 } from "./external-supervisor.ts";
+import {
+  createExternalRunsView,
+  externalRunsViewEnabledWhen,
+  type ExternalRunsView,
+} from "./external-runs-view.ts";
 
 const EXTENSION_NAME = "pi-sandbox";
 const registrations = new WeakMap<ExtensionAPI, Promise<void>>();
@@ -254,6 +260,10 @@ async function performRegistration(
   const subagentProvider =
     options.subagentProvider ?? config.subagents.provider;
   const externalWorkerIsolation = config.subagents.externalWorkerIsolation;
+  const externalRunsViewEnabled = externalRunsViewEnabledWhen(
+    subagentProvider,
+    externalWorkerIsolation,
+  );
   const additionalAllowRead = config.filesystem.additionalAllowRead;
   const hostIPC = options.hostIPC ?? config.hostIPC;
   const subagents =
@@ -268,6 +278,7 @@ async function performRegistration(
   const cwd = process.cwd();
   let isolation: ExternalWorkerIsolation | undefined;
   let supervisor: ExternalWorkerSupervisor | undefined;
+  let fleetView: ExternalRunsView | undefined;
   let externalIsolationFailure: string | undefined;
   const localBash = createBashToolDefinition(cwd);
 
@@ -474,6 +485,21 @@ async function performRegistration(
           : requireTask();
       const parentId =
         action === "handoff" ? requireSession().id : undefined;
+      // Fail fast on an invalid explicit model before spawning a child Pi.
+      // Only process-spawning actions (start/handoff) reach this block, so
+      // status/wait/stop/follow_up are never intercepted by model validation.
+      // When no model is specified the child inherits host behavior (no check).
+      const modelSpec = params.model?.trim();
+      if (modelSpec) {
+        const modelCheck = validateSubagentModel(
+          modelSpec,
+          ctx.modelRegistry?.getAvailable() ?? [],
+          ctx.model?.provider,
+        );
+        if (!modelCheck.ok) {
+          throw new Error(modelCheck.error);
+        }
+      }
       const session = await subagents.start(sessionOptions(task, parentId));
       const unsubscribe = update(session);
       try {
@@ -548,6 +574,10 @@ async function performRegistration(
   });
 
   pi.on("session_start", async (_event, ctx) => {
+    // A new session may replace a prior supervisor ownership; drop the old
+    // session's FleetView registrations before reconstructing.
+    fleetView?.close();
+    fleetView = undefined;
     if (
       subagentProvider === "pi-subagents" &&
       externalWorkerIsolation === "enforce"
@@ -555,15 +585,28 @@ async function performRegistration(
       try {
         isolation?.restore();
         await supervisor?.close();
-        supervisor = await createExternalWorkerSupervisor((worker) => ({
-          broker: getBoundaryBroker(),
-          command: "external pi-subagents worker network request",
-          cwd: worker.cwd,
-          sessionId: sessionId(ctx),
-          scopeKey: `${sessionId(ctx)}:turn:${currentTurn}`,
-          agentName: `pi-subagents-worker:${worker.id}`,
-          humanApproval: humanApproval(ctx),
-        }));
+        supervisor = undefined;
+        if (externalRunsViewEnabled) {
+          fleetView = await createExternalRunsView(sessionId(ctx));
+        }
+        supervisor = await createExternalWorkerSupervisor(
+          (worker) => ({
+            broker: getBoundaryBroker(),
+            command: "external pi-subagents worker network request",
+            cwd: worker.cwd,
+            sessionId: sessionId(ctx),
+            scopeKey: `${sessionId(ctx)}:turn:${currentTurn}`,
+            agentName: `pi-subagents-worker:${worker.id}`,
+            humanApproval: humanApproval(ctx),
+          }),
+          {
+            // Observability-only: never influences allow/deny, and a failure
+            // here must not stop the supervisor from answering approval RPCs
+            // or make the worker launch on the host.
+            registered: (worker) => fleetView?.registered(worker),
+            unregistered: (worker) => fleetView?.unregistered(worker.id),
+          },
+        );
         isolation = enableExternalWorkerIsolation(supervisor);
         externalIsolationFailure = undefined;
       } catch (error) {
@@ -573,6 +616,8 @@ async function performRegistration(
         isolation = undefined;
         await supervisor?.close();
         supervisor = undefined;
+        fleetView?.close();
+        fleetView = undefined;
         console.error(message);
         if (ctx.hasUI) ctx.ui.notify(message, "warning");
       }
@@ -622,6 +667,8 @@ async function performRegistration(
   pi.on("session_shutdown", async () => {
     isolation?.restore();
     isolation = undefined;
+    fleetView?.close();
+    fleetView = undefined;
     await supervisor?.close();
     supervisor = undefined;
     await subagents?.shutdown();

package/src/subagent.ts

@@ -104,6 +104,103 @@ function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+/**
+ * Minimal structural shape of a registry model used for validation. Kept as
+ * a structural type so this pure helper does not depend on the host coding
+ * agent's `Model` type.
+ */
+export interface SubagentModelLike {
+  /** Bare model id, e.g. `claude-3-5-sonnet` (not provider-prefixed). */
+  id: string;
+  /** Provider id, e.g. `anthropic`. */
+  provider: string;
+}
+
+export type SubagentModelValidation =
+  | { ok: true; mode: "inherit" }
+  | { ok: true; mode: "explicit" }
+  | { ok: false; error: string };
+
+// Mirrors pi's valid thinking levels (cli/args.ts VALID_THINKING_LEVELS).
+const VALID_THINKING_LEVELS = new Set([
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+]);
+
+/**
+ * Split an optional trailing `:thinking` suffix off a model pattern. A suffix
+ * that is not a valid thinking level is treated as part of the model id (pi
+ * supports model ids containing colons, e.g. OpenRouter's `:exacto`).
+ */
+export function splitModelThinking(
+  modelSpec: string,
+): { base: string; thinking?: string } {
+  const colon = modelSpec.lastIndexOf(":");
+  if (colon === -1) return { base: modelSpec };
+  const suffix = modelSpec.slice(colon + 1);
+  if (VALID_THINKING_LEVELS.has(suffix)) {
+    return { base: modelSpec.slice(0, colon), thinking: suffix };
+  }
+  return { base: modelSpec };
+}
+
+/**
+ * Fail-fast validation of an explicit subagent model before a child Pi spawns.
+ *
+ * Rules (see docs/compat-notes.md / Plan.md phase C2):
+ *  - `undefined`/empty -> inherit host behavior, never validated.
+ *  - `provider/model` -> requires an exact match on `${provider}/${modelId}`.
+ *  - bare model id -> preferred provider first; otherwise accept only when
+ *    globally unique; otherwise reject as ambiguous and ask for the full id.
+ *  - a valid trailing `:thinking` suffix is stripped for base validation and
+ *    preserved in the original pattern passed to the child.
+ *
+ * Only `start`/`handoff` (process-spawning actions) should call this.
+ */
+export function validateSubagentModel(
+  modelSpec: string | undefined,
+  available: readonly SubagentModelLike[],
+  preferredProvider: string | undefined,
+): SubagentModelValidation {
+  const spec = (modelSpec ?? "").trim();
+  if (!spec) return { ok: true, mode: "inherit" };
+  const { base } = splitModelThinking(spec);
+
+  // Full `provider/model` reference: require an exact registry match.
+  const fullMatch = available.find((m) => `${m.provider}/${m.id}` === base);
+  if (fullMatch) return { ok: true, mode: "explicit" };
+
+  // Contains a `/`, so it was intended as a full provider/model reference that
+  // did not match any registered model. Do not fall back to bare matching.
+  if (base.includes("/")) {
+    return {
+      ok: false,
+      error: `subagent start requires an available model; unknown model '${base}'`, // eslint-disable-line
+    };
+  }
+
+  // Bare model id.
+  const matches = available.filter((m) => m.id === base);
+  if (matches.length === 0) {
+    return {
+      ok: false,
+      error: `subagent start requires an available model; unknown model '${base}'`, // eslint-disable-line
+    };
+  }
+  const preferred = matches.find((m) => m.provider === preferredProvider);
+  if (preferred) return { ok: true, mode: "explicit" };
+  if (matches.length === 1) return { ok: true, mode: "explicit" };
+  return {
+    ok: false,
+    error: `subagent start requires an unambiguous model; '${base}' is available under multiple providers (${matches.map((m) => m.provider).join(", ")}). Use provider/model or set PI_MODEL to disambiguate.`,
+  };
+}
+
 export function resolvePiInvocation(): ProcessInvocation {
   const currentEntry = process.argv[1];
   if (