pi-maestro-teammate 2.6.0 → 2.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-maestro-teammate",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "description": "Pi extension — teammate agent dispatch with DAG task graphs, RPC messaging, and compact TUI",
   "type": "module",
   "engines": {
@@ -69,6 +69,10 @@
       "types": "./types/public/v1/extension.d.ts",
       "default": "./src/public/v1/extension.ts"
     },
+    "./v1/foreground-detach": {
+      "types": "./types/public/v1/foreground-detach.d.ts",
+      "default": "./src/public/v1/foreground-detach.ts"
+    },
     "./v1/model-routing": {
       "types": "./types/public/v1/model-routing.d.ts",
       "default": "./src/public/v1/model-routing.ts"

package/src/agents/agents.ts

@@ -197,6 +197,23 @@ function isReservedAgentName(name: string): boolean {
   return isBuiltinAgentName(name);
 }
 
+function agentDefinitionFingerprint(agent: AgentConfig): string {
+  return JSON.stringify([
+    agent.name,
+    agent.description,
+    agent.tools ?? null,
+    agent.model ?? null,
+    agent.fallbackModels ?? null,
+    agent.taskType ?? null,
+    agent.thinking ?? null,
+    agent.systemPromptMode,
+    agent.inheritProjectContext,
+    agent.inheritSkills,
+    agent.defaultContext ?? null,
+    agent.systemPrompt,
+  ]);
+}
+
 interface DiscoveryDirs {
   legacyUserAgentsDir: string;
   userPiAgentsDir: string;
@@ -394,8 +411,17 @@ export function discoverAgents(
   }> = [];
   const mergeAgent = (agent: AgentConfig): void => {
     // Builtin names are reserved so custom definitions cannot silently replace
-    // the stable general, exploration, and DAG orchestration roles.
+    // the stable general, exploration, and DAG orchestration roles. Package
+    // catalogs may carry byte-equivalent builtin mirrors for other consumers;
+    // those are duplicates, not attempted overrides.
     if (agent.source !== "builtin" && isReservedAgentName(agent.name)) {
+      const builtin = agentMap.get(agent.name);
+      if (
+        builtin?.source === "builtin"
+        && agentDefinitionFingerprint(builtin) === agentDefinitionFingerprint(agent)
+      ) {
+        return;
+      }
       rejectedCandidates.push({ name: agent.name, reason: "reserved-builtin", candidate: agent });
       return;
     }

package/src/extension/index.ts

@@ -487,7 +487,7 @@ import {
   type RuntimeReadModelSnapshotV2,
 } from "../runtime-v2/read-model.ts";
 import { RuntimeReadModelBrokerBridge } from "../runtime-v2/broker-read-model.ts";
-import { formatLocalAgentMessage } from "../shared/routing.ts";
+import { formatLocalAgentMessage, formatNoRestorableRuntimeError } from "../shared/routing.ts";
 export * from "./teammate-core.ts";
 import {
   appendTeammateDepthContext,
@@ -2704,7 +2704,7 @@ export default function registerTeammateExtension(
       const restarted = agent.status === "sleeping" && agent.restart?.(message, provenance) === true;
       if (!restarted) {
         restoreDeferredAgentContext(agent, deferredContext);
-        return { delivered: false, error: `Agent "${targetLabel}" has no restorable runtime.` };
+        return { delivered: false, error: formatNoRestorableRuntimeError(targetLabel, agent.status) };
       }
       const restartDelivery = agent.restartDelivery;
       if (restartDelivery) {
@@ -6201,7 +6201,7 @@ export default function registerTeammateExtension(
       const agent = cid ? state.activeRuns.get(cid) : undefined;
       if (agent && !LIVE_AGENT_STATUSES.has(agent.status)) {
         return {
-          content: [{ type: "text", text: `Agent "${params.to}" is already ${agent.status} and cannot receive commands.` }],
+          content: [{ type: "text", text: formatNoRestorableRuntimeError(params.to, agent.status) }],
           isError: true,
           details: { delivered: false },
         };

package/src/extension/teammate-core.ts

@@ -10,11 +10,11 @@ import { randomUUID } from "node:crypto";
 import { logDiagnosticError, logDiagnosticWarn } from "../shared/diagnostic-log.ts";
 
 import { altKey } from "pi-maestro-settings-core/v1";
+import { registerForegroundDetach, setPersistentUi } from "../public/v1/foreground-detach.ts";
 import type {
   ExtensionAPI,
   ExtensionCommandContext,
   ExtensionContext,
-  ExtensionUIContext,
   ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { createHash } from "node:crypto";
@@ -896,81 +896,7 @@ export function backgroundWaitGuidance(correlationId: string): string {
  */
 export const FOREGROUND_DETACH_HINT = `${altKey("B")} detaches a foreground call to background.`;
 
-/**
- * One session-scoped Alt+B listener dispatches to the oldest active foreground
- * owner. This makes nested calls detach layer by layer from the outermost call
- * instead of relying on TUI listener registration order.
- */
-type ForegroundDetachOwner = {
-  active: boolean;
-  detach(): void;
-};
-
-let persistentUi: ExtensionUIContext | undefined;
-let persistentUiUnsubscribe: (() => void) | undefined;
-const foregroundDetachOwners: ForegroundDetachOwner[] = [];
-
-function uninstallForegroundDetachListener(): void {
-  const unsubscribe = persistentUiUnsubscribe;
-  persistentUiUnsubscribe = undefined;
-  unsubscribe?.();
-}
-
-function installForegroundDetachListener(): void {
-  if (!persistentUi || persistentUiUnsubscribe || foregroundDetachOwners.length === 0) return;
-  persistentUiUnsubscribe = persistentUi.onTerminalInput((data: string) => {
-    if (data !== "\x1bb") return undefined;
-    const owner = foregroundDetachOwners.shift();
-    if (!owner) return undefined;
-    owner.active = false;
-    if (foregroundDetachOwners.length === 0) uninstallForegroundDetachListener();
-    owner.detach();
-    return { consume: true };
-  });
-}
-
-export function setPersistentUi(
-  ui: ExtensionUIContext | undefined,
-  resetOwners = false,
-): void {
-  if (persistentUi !== ui || resetOwners) {
-    uninstallForegroundDetachListener();
-    persistentUi = ui;
-  }
-  if (!ui || resetOwners) {
-    for (const owner of foregroundDetachOwners) owner.active = false;
-    foregroundDetachOwners.length = 0;
-    if (!ui) return;
-  }
-  installForegroundDetachListener();
-}
-
-/** Registers one foreground owner; unregister is idempotent on every race path. */
-export function registerForegroundDetach(
-  detach: () => void,
-  ui?: ExtensionUIContext,
-): () => void {
-  if (ui) setPersistentUi(ui);
-  const owner: ForegroundDetachOwner = { active: true, detach };
-  foregroundDetachOwners.push(owner);
-  try {
-    installForegroundDetachListener();
-  } catch (error) {
-    owner.active = false;
-    const index = foregroundDetachOwners.indexOf(owner);
-    if (index >= 0) foregroundDetachOwners.splice(index, 1);
-    if (foregroundDetachOwners.length === 0) uninstallForegroundDetachListener();
-    throw error;
-  }
-
-  return () => {
-    if (!owner.active) return;
-    owner.active = false;
-    const index = foregroundDetachOwners.indexOf(owner);
-    if (index >= 0) foregroundDetachOwners.splice(index, 1);
-    if (foregroundDetachOwners.length === 0) uninstallForegroundDetachListener();
-  };
-}
+export { registerForegroundDetach, setPersistentUi };
 
 export function foregroundWaitWindowMs(
   tasks: ReadonlyArray<{ timeoutMs?: number }>,

package/src/extension/teammate-proxy.ts

@@ -20,7 +20,11 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { Check } from "typebox/value";
 import { isGuiTeammateToolAllowed, registerGuiTool, unregisterGuiTool } from "../shared/gui-registry.ts";
 import { aggregateAgentRunPhase, projectAgentRuntime } from "../shared/agent-status.ts";
-import { formatLocalAgentMessage, resolveAgentCompletionTarget } from "../shared/routing.ts";
+import {
+  formatLocalAgentMessage,
+  formatNoRestorableRuntimeError,
+  resolveAgentCompletionTarget,
+} from "../shared/routing.ts";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { TeammateParams, TeammateSendParams, TeammateListParams, TeammateWatchParams, TeammateWaitParams, TeammateMonitorParams, ObserveParams, LocalObserveParams } from "./schemas.ts";
 import {
@@ -3113,7 +3117,7 @@ export async function handleProxyRequest(
       const agent = state.activeRuns.get(cid);
       if (agent && !LIVE_AGENT_STATUSES.has(agent.status)) {
         reply({ type: "teammate_proxy_result", requestId, result: {
-          content: [{ type: "text", text: `Agent "${to}" is already ${agent.status} and cannot receive commands.` }],
+          content: [{ type: "text", text: formatNoRestorableRuntimeError(to, agent.status) }],
           isError: true, details: { delivered: false },
         }});
         return;
@@ -3298,7 +3302,7 @@ export async function handleProxyRequest(
         if (!restarted || !agent) {
           if (agent) restoreDeferredAgentContext(agent, deferredContext);
           reply({ type: "teammate_proxy_result", requestId, result: {
-            content: [{ type: "text", text: `Agent "${to}" has no restorable runtime.` }],
+            content: [{ type: "text", text: formatNoRestorableRuntimeError(to, agent?.status) }],
             isError: true, details: { delivered: false },
           }});
           return;

package/src/public/v1/foreground-detach.ts

@@ -0,0 +1,90 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+
+/** One session-scoped Alt+B listener shared by every foreground tool owner. */
+type ForegroundDetachOwner = {
+  active: boolean;
+  detach(): void;
+};
+
+type ForegroundDetachRegistry = {
+  ui?: ExtensionUIContext;
+  unsubscribe?: () => void;
+  owners: ForegroundDetachOwner[];
+};
+
+const REGISTRY_KEY = Symbol.for("pi-maestro.foreground-detach.v1");
+const globals = globalThis as typeof globalThis & Record<symbol, unknown>;
+
+function registry(): ForegroundDetachRegistry {
+  const existing = globals[REGISTRY_KEY];
+  if (existing && typeof existing === "object" && Array.isArray((existing as ForegroundDetachRegistry).owners)) {
+    return existing as ForegroundDetachRegistry;
+  }
+  const created: ForegroundDetachRegistry = { owners: [] };
+  globals[REGISTRY_KEY] = created;
+  return created;
+}
+
+function uninstallForegroundDetachListener(state: ForegroundDetachRegistry): void {
+  const unsubscribe = state.unsubscribe;
+  state.unsubscribe = undefined;
+  unsubscribe?.();
+}
+
+function installForegroundDetachListener(state: ForegroundDetachRegistry): void {
+  if (!state.ui || state.unsubscribe || state.owners.length === 0) return;
+  state.unsubscribe = state.ui.onTerminalInput((data: string) => {
+    if (data !== "\x1bb") return undefined;
+    const owner = state.owners.shift();
+    if (!owner) return undefined;
+    owner.active = false;
+    if (state.owners.length === 0) uninstallForegroundDetachListener(state);
+    owner.detach();
+    return { consume: true };
+  });
+}
+
+export function setPersistentUi(
+  ui: ExtensionUIContext | undefined,
+  resetOwners = false,
+): void {
+  const state = registry();
+  if (state.ui !== ui || resetOwners) {
+    uninstallForegroundDetachListener(state);
+    state.ui = ui;
+  }
+  if (!ui || resetOwners) {
+    for (const owner of state.owners) owner.active = false;
+    state.owners.length = 0;
+    if (!ui) return;
+  }
+  installForegroundDetachListener(state);
+}
+
+/** Registers one foreground owner; unregister is idempotent on every race path. */
+export function registerForegroundDetach(
+  detach: () => void,
+  ui?: ExtensionUIContext,
+): () => void {
+  if (ui) setPersistentUi(ui);
+  const state = registry();
+  const owner: ForegroundDetachOwner = { active: true, detach };
+  state.owners.push(owner);
+  try {
+    installForegroundDetachListener(state);
+  } catch (error) {
+    owner.active = false;
+    const index = state.owners.indexOf(owner);
+    if (index >= 0) state.owners.splice(index, 1);
+    if (state.owners.length === 0) uninstallForegroundDetachListener(state);
+    throw error;
+  }
+
+  return () => {
+    if (!owner.active) return;
+    owner.active = false;
+    const index = state.owners.indexOf(owner);
+    if (index >= 0) state.owners.splice(index, 1);
+    if (state.owners.length === 0) uninstallForegroundDetachListener(state);
+  };
+}

package/src/public/v1/index.ts

@@ -16,6 +16,7 @@ export * from "./completion-durability.ts";
 export * from "./events.ts";
 export * from "./execution.ts";
 export * from "./extension.ts";
+export * from "./foreground-detach.ts";
 export * from "./mailbox.ts";
 export * from "./model-routing.ts";
 export * from "./monitor-window-state.ts";

package/src/runs/execution-infra.ts

@@ -1502,75 +1502,247 @@ export function normalizeTeammateParams(
 }
 
 // ---------------------------------------------------------------------------
-// AC3: Windows-safe pi binary resolution
+// AC3: shell-free, provenance-bearing Pi launcher resolution
 // ---------------------------------------------------------------------------
 
-export let resolvedPiEntryPoint: string | null | undefined;
+export type PiLaunchSource =
+  | "override"
+  | "path-native"
+  | "windows-shim"
+  | "host-entry"
+  | "path-fallback";
 
-export function resolvePiEntryPoint(): string | null {
-  if (resolvedPiEntryPoint !== undefined) return resolvedPiEntryPoint;
+export interface PiLaunchSpec {
+  command: string;
+  argsPrefix: string[];
+  source: PiLaunchSource;
+}
+
+export interface PiSpawnCommandOptions {
+  envBinary?: string | null;
+  entryPoint?: string | null;
+  platform?: NodeJS.Platform;
+  pathValue?: string | null;
+  argv?: readonly string[];
+  execPath?: string;
+  appData?: string | null;
+  /** @internal deterministic filesystem seam for focused launcher tests. */
+  isFile?: (candidate: string) => boolean;
+  /** @internal deterministic package-manifest seam for focused launcher tests. */
+  readTextFile?: (candidate: string) => string;
+}
 
-  // Try current process argv (if pi is the host)
-  const argv1 = process.argv[1];
-  if (argv1 && (argv1.endsWith(".mjs") || argv1.endsWith(".js"))) {
-    resolvedPiEntryPoint = argv1;
-    return resolvedPiEntryPoint;
+function regularFileExists(candidate: string): boolean {
+  try {
+    return fs.statSync(candidate).isFile();
+  } catch {
+    return false;
   }
+}
 
-  if (process.platform === "win32") {
-    // Parse pi.cmd to find the real .js entry point
-    const npmDir = process.env.APPDATA
-      ? path.join(process.env.APPDATA, "npm")
-      : null;
-    if (npmDir) {
-      const cmdFile = path.join(npmDir, "pi.cmd");
-      try {
-        const content = fs.readFileSync(cmdFile, "utf-8");
-        // pi.cmd contains: "%_prog%" "%dp0%\node_modules\...\cli.js" %*
-        const match = content.match(/"?%dp0%\\([^"*%\r\n]+\.(?:js|mjs))"?/);
-        if (match) {
-          const entryPoint = path.join(npmDir, match[1]);
-          if (fs.existsSync(entryPoint)) {
-            resolvedPiEntryPoint = entryPoint;
-            return resolvedPiEntryPoint;
-          }
-        }
-      } catch { /* fallback */ }
+function pathPiCandidate(
+  platform: NodeJS.Platform,
+  pathValue: string | null | undefined,
+  isFile: (candidate: string) => boolean,
+): Pick<PiLaunchSpec, "command" | "source"> | undefined {
+  if (!pathValue) return undefined;
+  const directories = pathValue.split(platform === "win32" ? ";" : ":").filter(Boolean);
+  if (platform !== "win32") {
+    for (const directory of directories) {
+      const candidate = path.join(directory, "pi");
+      if (isFile(candidate)) return { command: candidate, source: "path-native" };
     }
+    return undefined;
   }
 
-  resolvedPiEntryPoint = null;
-  return null;
+  // Prefer a native executable anywhere on PATH before considering cmd/bat
+  // wrappers. Ignore npm's extensionless POSIX shim: cross-spawn follows its
+  // shebang through sh.exe, so the Pi Node process does not own the IPC channel.
+  for (const extension of [".exe", ".com"] as const) {
+    for (const directory of directories) {
+      const candidate = path.join(directory, `pi${extension}`);
+      if (isFile(candidate)) return { command: candidate, source: "path-native" };
+    }
+  }
+  for (const extension of [".cmd", ".bat"] as const) {
+    for (const directory of directories) {
+      const candidate = path.join(directory, `pi${extension}`);
+      if (isFile(candidate)) return { command: candidate, source: "windows-shim" };
+    }
+  }
+  return undefined;
 }
 
-export interface PiSpawnCommandOptions {
-  envBinary?: string | null;
-  entryPoint?: string | null;
-  platform?: NodeJS.Platform;
+const WINDOWS_PI_SHIM_ENTRY_PATTERN = /"?%dp0%[\\/]([^"*%\r\n]+?\.(?:js|mjs|cjs))"?/i;
+
+function resolvedWindowsPiShim(
+  shim: string,
+  isFile: (candidate: string) => boolean,
+  readTextFile: (candidate: string) => string,
+  execPath: string,
+): PiLaunchSpec | undefined {
+  try {
+    const match = WINDOWS_PI_SHIM_ENTRY_PATTERN.exec(readTextFile(shim));
+    if (!match) return undefined;
+    const entry = path.resolve(path.dirname(shim), match[1]!.replace(/[\\/]/g, path.sep));
+    const verified = verifiedHostPiEntry(entry, isFile, readTextFile);
+    return verified
+      ? { command: execPath, argsPrefix: [verified], source: "windows-shim" }
+      : undefined;
+  } catch {
+    return undefined;
+  }
 }
 
-export function getPiSpawnCommand(
-  args: string[],
-  options: PiSpawnCommandOptions = {},
-): { command: string; args: string[]; shell: false } {
+function verifiedHostPiEntry(
+  entryPoint: string | null | undefined,
+  isFile: (candidate: string) => boolean,
+  readTextFile: (candidate: string) => string,
+): string | undefined {
+  if (!entryPoint || !/\.(?:js|mjs|cjs)$/i.test(entryPoint) || !isFile(entryPoint)) return undefined;
+  const absoluteEntry = path.resolve(entryPoint);
+  let directory = path.dirname(absoluteEntry);
+  for (let depth = 0; depth < 10; depth += 1) {
+    const manifestPath = path.join(directory, "package.json");
+    if (isFile(manifestPath)) {
+      try {
+        const manifest = JSON.parse(readTextFile(manifestPath)) as {
+          name?: unknown;
+          bin?: unknown;
+        };
+        const acceptedPackage = manifest.name === "@earendil-works/pi-coding-agent"
+          || manifest.name === "@mariozechner/pi-coding-agent";
+        const piBin = typeof manifest.bin === "object" && manifest.bin !== null
+          ? (manifest.bin as Record<string, unknown>).pi
+          : undefined;
+        if (acceptedPackage && typeof piBin === "string"
+          && path.resolve(directory, piBin) === absoluteEntry) return absoluteEntry;
+      } catch {
+        return undefined;
+      }
+      return undefined;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return undefined;
+}
+
+export let resolvedPiEntryPoint: string | null | undefined;
+
+/**
+ * Resolve process.argv[1] only when its owning package manifest proves it is
+ * Pi's declared CLI. A generic .js/.mjs suffix is never evidence of identity.
+ */
+export function resolvePiEntryPoint(): string | null {
+  if (resolvedPiEntryPoint !== undefined) return resolvedPiEntryPoint;
+  resolvedPiEntryPoint = verifiedHostPiEntry(
+    process.argv[1],
+    regularFileExists,
+    (candidate) => fs.readFileSync(candidate, "utf-8"),
+  ) ?? null;
+  return resolvedPiEntryPoint;
+}
+
+export function resolvePiLaunchSpec(options: PiSpawnCommandOptions = {}): PiLaunchSpec {
   const envBinary = options.envBinary === undefined
     ? process.env.PI_TEAMMATE_PI_BINARY
     : options.envBinary;
-  if (envBinary) {
-    return { command: envBinary, args, shell: false };
+  if (envBinary?.trim()) {
+    return { command: envBinary, argsPrefix: [], source: "override" };
   }
 
-  const entryPoint = options.entryPoint === undefined
+  const platform = options.platform ?? process.platform;
+  const isFile = options.isFile ?? regularFileExists;
+  const readTextFile = options.readTextFile ?? ((candidate: string) => fs.readFileSync(candidate, "utf-8"));
+  const execPath = options.execPath ?? process.execPath;
+  const pathCandidate = pathPiCandidate(
+    platform,
+    options.pathValue === undefined ? process.env.PATH : options.pathValue,
+    isFile,
+  );
+  if (pathCandidate?.source === "path-native") return { ...pathCandidate, argsPrefix: [] };
+  if (pathCandidate?.source === "windows-shim") {
+    const resolved = resolvedWindowsPiShim(pathCandidate.command, isFile, readTextFile, execPath);
+    if (resolved) return resolved;
+  }
+
+  // APPDATA/npm is not guaranteed to be present in PATH for service/gateway
+  // processes, so retain an explicit, verified Windows shim fallback.
+  if (platform === "win32") {
+    const appData = options.appData === undefined ? process.env.APPDATA : options.appData;
+    if (appData) {
+      const shim = path.join(appData, "npm", "pi.cmd");
+      if (isFile(shim)) {
+        const resolved = resolvedWindowsPiShim(shim, isFile, readTextFile, execPath);
+        if (resolved) return resolved;
+      }
+    }
+  }
+  const injectedEntry = options.entryPoint !== undefined
+    ? verifiedHostPiEntry(options.entryPoint, isFile, readTextFile)
+    : options.argv !== undefined
+      ? verifiedHostPiEntry(options.argv[1], isFile, readTextFile)
+      : undefined;
+  const hostEntry = options.entryPoint === undefined && options.argv === undefined
     ? resolvePiEntryPoint()
-    : options.entryPoint;
-  if (entryPoint) {
-    return { command: process.execPath, args: [entryPoint, ...args], shell: false };
+    : injectedEntry;
+  if (hostEntry) {
+    return {
+      command: options.execPath ?? process.execPath,
+      argsPrefix: [hostEntry],
+      source: "host-entry",
+    };
   }
 
-  // cross-spawn resolves Windows .cmd shims without opting into shell mode
-  // and escapes each argv item before invoking cmd.exe internally.
-  void options.platform;
-  return { command: "pi", args, shell: false };
+  // Preserve the historical ENOENT failure mode when no resolver candidate is
+  // installed, but make that unverified fallback explicit in diagnostics.
+  return { command: "pi", argsPrefix: [], source: "path-fallback" };
+}
+
+export function getPiSpawnCommand(
+  args: string[],
+  options: PiSpawnCommandOptions = {},
+): PiLaunchSpec & { args: string[]; shell: false } {
+  const launch = resolvePiLaunchSpec(options);
+  return {
+    ...launch,
+    args: [...launch.argsPrefix, ...args],
+    shell: false,
+  };
+}
+
+export interface PiLaunchDiagnostic {
+  type: "teammate_pi_launch_diagnostic";
+  source: PiLaunchSource;
+  phase: "spawn" | "child-error" | "close";
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  stderrTail: string;
+}
+
+export function piLaunchDiagnostic(
+  launch: Pick<PiLaunchSpec, "source">,
+  phase: PiLaunchDiagnostic["phase"],
+  exitCode: number | null,
+  signal: NodeJS.Signals | null,
+  stderr: string,
+): PiLaunchDiagnostic {
+  return {
+    type: "teammate_pi_launch_diagnostic",
+    source: launch.source,
+    phase,
+    exitCode,
+    signal,
+    stderrTail: truncateUtf8Tail(stderr.trim(), EXECUTION_BUFFER_LIMITS.stderrBytes),
+  };
+}
+
+export function formatPiLaunchDiagnostic(diagnostic: PiLaunchDiagnostic): string {
+  return `source=${diagnostic.source}, phase=${diagnostic.phase}, exit=${diagnostic.exitCode ?? "null"}, `
+    + `signal=${diagnostic.signal ?? "none"}`
+    + (diagnostic.stderrTail ? `\nstderr tail:\n${diagnostic.stderrTail}` : "");
 }
 
 export interface InteractiveTerminalLaunchOptions {

package/src/runs/pi-subprocess-attempt.ts

@@ -94,10 +94,12 @@ import {
   extractPiEventError,
   extractStructuredOutputCandidate,
   extractTextContent,
+  formatPiLaunchDiagnostic,
   getPiSpawnCommand,
   getTeammateDepth,
   getTeammateSessionRoot,
   isPiResultReadyTurn,
+  piLaunchDiagnostic,
   readRegularTextFile,
   releasePublishedTurnHistory,
   resetUsage,
@@ -876,8 +878,8 @@ export async function runSingleAttempt(
     );
 
     let useIpc = false;
+    const spawnSpec = getPiSpawnCommand(piArgs);
     try {
-      const spawnSpec = getPiSpawnCommand(piArgs);
       useIpc = !spawnSpec.shell;
       const spawnOpts: Parameters<typeof crossSpawn>[2] = {
         cwd,
@@ -892,6 +894,8 @@ export async function runSingleAttempt(
       if (schemaFile) cleanupFile(schemaFile);
       if (outputFile) cleanupFile(outputFile);
 
+      const spawnDiagnostic = piLaunchDiagnostic(spawnSpec, "spawn", null, null, "");
+      options.onChildEvent?.({ ...spawnDiagnostic, correlationId });
       const result: SingleResult = {
         agent: params.agent,
         name: params.name,
@@ -901,7 +905,8 @@ export async function runSingleAttempt(
           role: "system",
           content:
             `Failed to spawn pi subprocess (agent=${params.agent}, model=${state.resolvedModel || "unknown"}, `
-            + `correlationId=${correlationId}, phase=spawn): ${error instanceof Error ? error.message : String(error)}`,
+            + `correlationId=${correlationId}, ${formatPiLaunchDiagnostic(spawnDiagnostic)}): `
+            + `${error instanceof Error ? error.message : String(error)}`,
         }],
         usage: emptyUsage(),
         model: state.resolvedModel,
@@ -2869,24 +2874,31 @@ export async function runSingleAttempt(
       if (finalContent && !messages.some((message) => message.content === finalContent)) {
         appendDistinctAssistantMessage(messages, finalContent);
       }
-      let stderrAlreadyReported = false;
       if (messages.length === 0) {
         const content = state.lastContent.trim() || stderrTail || "(no output)";
-        stderrAlreadyReported = stderrTail.length > 0 && content === stderrTail;
         appendBoundedTranscriptMessage(messages, { role: "assistant", content });
       }
 
-      // An abnormal exit used to be a bare number: stderr was dropped whenever
-      // the child had produced any assistant text, and the signal was ignored.
+      // Gateway results and Monitor observers consume the same bounded,
+      // provenance-bearing diagnostic projection.
       if ((code ?? 1) !== 0) {
-        const detail = stderrAlreadyReported ? "" : stderrTail;
+        const closeDiagnostic = piLaunchDiagnostic(
+          spawnSpec,
+          "close",
+          code,
+          signal,
+          stderrTail,
+        );
+        options.onChildEvent?.({ ...closeDiagnostic, correlationId });
+        const transcriptDiagnostic = stderrTail && messages.some((message) => message.content === stderrTail)
+          ? { ...closeDiagnostic, stderrTail: "" }
+          : closeDiagnostic;
         appendBoundedTranscriptMessage(messages, {
           role: "system",
           content:
             `Teammate child process exited abnormally (agent=${params.agent}, `
-            + `correlationId=${correlationId}, exit=${code ?? "null"}, signal=${signal ?? "none"}, `
-            + `elapsed=${Date.now() - startTime}ms, tools=${progress.toolCount}).`
-            + (detail ? `\nstderr tail:\n${truncateUtf8Tail(detail, EXECUTION_BUFFER_LIMITS.stderrBytes)}` : ""),
+            + `correlationId=${correlationId}, ${formatPiLaunchDiagnostic(transcriptDiagnostic)}, `
+            + `elapsed=${Date.now() - startTime}ms, tools=${progress.toolCount}).`,
         });
       }
 
@@ -2989,9 +3001,17 @@ export async function runSingleAttempt(
       progress.durationMs = Date.now() - startTime;
       options.onProgress?.(progress);
 
+      const childErrorDiagnostic = piLaunchDiagnostic(
+        spawnSpec,
+        "child-error",
+        null,
+        child.signalCode,
+        state.stderrBuffer,
+      );
+      options.onChildEvent?.({ ...childErrorDiagnostic, correlationId });
       const processError =
         `Teammate child process error (agent=${params.agent}, model=${state.resolvedModel || "unknown"}, `
-        + `correlationId=${correlationId}, phase=child-error): ${error.message}`;
+        + `correlationId=${correlationId}, ${formatPiLaunchDiagnostic(childErrorDiagnostic)}): ${error.message}`;
       if (state.initialResultPublished) {
         appendBoundedTranscriptMessage(messages, {
           role: "system",

package/src/shared/routing.ts

@@ -96,3 +96,13 @@ export function formatLocalAgentMessage(input: LocalAgentMessageInput): string {
     input.message,
   ].join("\n");
 }
+
+/** Explain why a settled local agent cannot accept another message and how to continue. */
+export function formatNoRestorableRuntimeError(label: string, status?: string): string {
+  const state = status === "completed"
+    ? "has completed"
+    : status
+      ? `is ${status}`
+      : "is unavailable";
+  return `Agent "${label}" ${state} and has no restorable runtime. Dispatch a new teammate and pass the previous agent:// publication via tasks[].briefing.`;
+}

package/types/extension/teammate-core.d.ts

@@ -5,7 +5,8 @@
  * TUI: Alt+R mode-aware session list, widget above editor, Alt+B foreground→background detach
  * Mode: RPC subprocess — stdin open for steer/follow_up/abort
  */
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { registerForegroundDetach, setPersistentUi } from "../public/v1/foreground-detach.ts";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import type { WorkspaceSessionScan } from "../transcript/session-transcript.ts";
 import type { RecentToolInfo } from "../shared/types.ts";
 import { type WorkspaceBackgroundJobSnapshot, type WorkspaceOwnerState } from "./workspace-peers.ts";
@@ -122,9 +123,7 @@ export declare function backgroundWaitGuidance(correlationId: string): string;
  * discoverable across the root single, root graph, and nested foreground paths.
  */
 export declare const FOREGROUND_DETACH_HINT: string;
-export declare function setPersistentUi(ui: ExtensionUIContext | undefined, resetOwners?: boolean): void;
-/** Registers one foreground owner; unregister is idempotent on every race path. */
-export declare function registerForegroundDetach(detach: () => void, ui?: ExtensionUIContext): () => void;
+export { registerForegroundDetach, setPersistentUi };
 export declare function foregroundWaitWindowMs(tasks: ReadonlyArray<{
     timeoutMs?: number;
 }>, fallbackMs?: number): number;

package/types/public/v1/foreground-detach.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+export declare function setPersistentUi(ui: ExtensionUIContext | undefined, resetOwners?: boolean): void;
+/** Registers one foreground owner; unregister is idempotent on every race path. */
+export declare function registerForegroundDetach(detach: () => void, ui?: ExtensionUIContext): () => void;

package/types/public/v1/index.d.ts

@@ -16,6 +16,7 @@ export * from "./completion-durability.ts";
 export * from "./events.ts";
 export * from "./execution.ts";
 export * from "./extension.ts";
+export * from "./foreground-detach.ts";
 export * from "./mailbox.ts";
 export * from "./model-routing.ts";
 export * from "./monitor-window-state.ts";

package/types/runs/execution-infra.d.ts

@@ -571,18 +571,46 @@ export declare function buildExpertLeaderPrompt(objective: string): string;
 export declare function prepareTeammateMode(params: RunTeammateParams): RunTeammateParams;
 /** Normalize the tasks-only public contract into executable graph tasks. */
 export declare function normalizeTeammateParams(params: RunTeammateParams): NormalizeTeammateResult;
-export declare let resolvedPiEntryPoint: string | null | undefined;
-export declare function resolvePiEntryPoint(): string | null;
+export type PiLaunchSource = "override" | "path-native" | "windows-shim" | "host-entry" | "path-fallback";
+export interface PiLaunchSpec {
+    command: string;
+    argsPrefix: string[];
+    source: PiLaunchSource;
+}
 export interface PiSpawnCommandOptions {
     envBinary?: string | null;
     entryPoint?: string | null;
     platform?: NodeJS.Platform;
+    pathValue?: string | null;
+    argv?: readonly string[];
+    execPath?: string;
+    appData?: string | null;
+    /** @internal deterministic filesystem seam for focused launcher tests. */
+    isFile?: (candidate: string) => boolean;
+    /** @internal deterministic package-manifest seam for focused launcher tests. */
+    readTextFile?: (candidate: string) => string;
 }
-export declare function getPiSpawnCommand(args: string[], options?: PiSpawnCommandOptions): {
-    command: string;
+export declare let resolvedPiEntryPoint: string | null | undefined;
+/**
+ * Resolve process.argv[1] only when its owning package manifest proves it is
+ * Pi's declared CLI. A generic .js/.mjs suffix is never evidence of identity.
+ */
+export declare function resolvePiEntryPoint(): string | null;
+export declare function resolvePiLaunchSpec(options?: PiSpawnCommandOptions): PiLaunchSpec;
+export declare function getPiSpawnCommand(args: string[], options?: PiSpawnCommandOptions): PiLaunchSpec & {
     args: string[];
     shell: false;
 };
+export interface PiLaunchDiagnostic {
+    type: "teammate_pi_launch_diagnostic";
+    source: PiLaunchSource;
+    phase: "spawn" | "child-error" | "close";
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stderrTail: string;
+}
+export declare function piLaunchDiagnostic(launch: Pick<PiLaunchSpec, "source">, phase: PiLaunchDiagnostic["phase"], exitCode: number | null, signal: NodeJS.Signals | null, stderr: string): PiLaunchDiagnostic;
+export declare function formatPiLaunchDiagnostic(diagnostic: PiLaunchDiagnostic): string;
 export interface InteractiveTerminalLaunchOptions {
     platform?: NodeJS.Platform;
     terminalCommand?: string;

package/types/shared/routing.d.ts

@@ -37,3 +37,5 @@ export interface LocalAgentMessageInput {
 }
 /** Canonical model-visible envelope for local agent-to-agent messages. */
 export declare function formatLocalAgentMessage(input: LocalAgentMessageInput): string;
+/** Explain why a settled local agent cannot accept another message and how to continue. */
+export declare function formatNoRestorableRuntimeError(label: string, status?: string): string;