pi-famulus 0.1.8 → 0.2.0

package/src/index.ts

@@ -21,16 +21,16 @@ import { createAgentLoader, type AgentLoader } from "./agents/loader";
 import { createBashOverride } from "./bash-override";
 import { createComms, type CommsWithOrigin } from "./comms/comms";
 import { createRegistryCommsHost } from "./comms/registry-host";
-import { createAgentMessageTool, createContactSupervisorTool } from "./comms/tools";
+import { createAgentMessageTool } from "./comms/tools";
 import { registerReplyCommand } from "./comms/reply-command";
-import { describeManagerSearch, getFamulusHome, loadConfig, resolveManagerPath, resolveSubagentConfig } from "./config";
+import { describeManagerSearch, getFamulusHome, loadConfig, resolveManagerPath, resolveSubagentConfig, taskOutputPath } from "./config";
+import { ensureNativeManagerInstalled } from "./native-manager.js";
 import type { TaskExitInfo } from "./format";
 import { EXTENSION_VERSION, ManagerClient, type ManagerEvent, type TaskRecord } from "./manager-client";
 import { createMonitorTool, exitEventFromRecord, MonitorRegistry } from "./monitor";
 import { admitAgentChild, reregisterAgentLeases } from "./subagent/admission";
 import { NotifyCenter } from "./notify";
 import { onWakeMessageEnd, registryStatusLookup } from "./wake-delivery";
-import { createChildBashTool } from "./subagent/child-bash";
 import { ChildShellTracker, createOverrunNotifier } from "./subagent/overrun";
 import {
   agentEndReason,
@@ -43,7 +43,11 @@ import {
 import { TranscriptWriter } from "./subagent/transcript";
 import { FleetWidget } from "./subagent/fleet-widget";
 import { WorkIndex, type WorkItem } from "./work-index";
-import { createPiSessionFn, isFamulusChildSession, modelCandidates } from "./subagent/pi-runtime";
+import { fileURLToPath } from "node:url";
+import { isFamulusChildSession, modelCandidates } from "./subagent/pi-runtime";
+import { createHostedSessionFn } from "./subagent/hosted-session";
+import { isHostedChildProcess, registerChildMode } from "./child-mode";
+import { openAttachView, registerAttachCommand } from "./tui/attach-command";
 import { SubagentRegistry } from "./subagent/registry";
 import { InProcessRunner } from "./subagent/runner";
 import { createSubagentTool } from "./subagent/tool";
@@ -55,6 +59,52 @@ import { registerTasksCommand } from "./tui/tasks-command";
 import { stderrPathFor } from "./tui/task-output-paths";
 import { shellWakeTitle } from "./wake";
 
+async function promptIfHostedSession(
+  c: ManagerClient,
+  live: () => ExtensionContext | null,
+  query: { sessionFile?: string | null; sessionId?: string },
+  where: "start" | "switch",
+): Promise<"takeover" | "stay" | "none"> {
+  if (!c.isAvailable() || c.protocolLevel() < 6) return "none";
+  const found = await c.hostedLookup({
+    ...(query.sessionId ? { sessionId: query.sessionId } : {}),
+    ...(query.sessionFile ? { sessionFile: query.sessionFile } : {}),
+  }).catch(() => null);
+  if (!found || found.residency !== "warm" || typeof found.child_id !== "string") return "none";
+  const uiCtx = live();
+  if (!uiCtx) return "none";
+  if (where === "start" && query.sessionId && uiCtx.sessionManager.getSessionId() !== query.sessionId) return "none";
+  if (!uiCtx.hasUI) {
+    uiCtx.ui.notify(
+      "This session file belongs to a warm hosted subagent. Use /attach from the parent, or open it in the TUI to take over.",
+      "warning",
+    );
+    return "stay";
+  }
+  const choice = await uiCtx.ui.select("This session is hosted by pi-famulus", [
+    "Attach to the hosted process",
+    "Take over",
+    "Cancel",
+  ]);
+  if (choice === "Take over") {
+    try {
+      await c.agentTakeover(found.child_id);
+      return "takeover";
+    } catch (err) {
+      uiCtx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+      return "stay";
+    }
+  }
+  if (choice === "Attach to the hosted process") {
+    try {
+      await openAttachView(uiCtx, c, found.child_id);
+    } catch (err) {
+      uiCtx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+    }
+  }
+  return "stay";
+}
+
 /** Read only the tail of a task output file for the notification preview (≤ maxChars). */
 export function readPreview(outputPath: string | undefined, maxChars: number): string {
   if (!outputPath) return "";
@@ -76,6 +126,10 @@ interface FamulusRuntime {
 }
 
 export default function (pi: ExtensionAPI): void {
+  if (isHostedChildProcess()) {
+    registerChildMode(pi);
+    return;
+  }
   if (isFamulusChildSession(pi)) return;
   // A /reload parked the previous instance's runtime: adopt it so its shells,
   // monitors and subagents keep running (see reload-handoff.ts). Another
@@ -99,7 +153,28 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
   registerBehaviorGuidelines(pi);
   const home = getFamulusHome();
   const config = loadConfig(home);
-  const managerPath = resolveManagerPath(config, home);
+  // pi update reinstalls extensions with npm. omit=optional drops the platform
+  // package during that install. Fetch it in the background so a slow or
+  // unreachable registry cannot stall extension startup.
+  let managerPath = resolveManagerPath(config, home);
+  let famulusInfo: {
+    extensionVersion: string;
+    managerPath: string | null;
+    describeSearch: () => string;
+    getClient: () => ManagerClient | null;
+  } | null = null;
+  const nativeRestore: Promise<string | null> = managerPath
+    ? Promise.resolve(managerPath)
+    : Promise.resolve()
+        .then(() => ensureNativeManagerInstalled())
+        .then((path) => {
+          if (path) {
+            managerPath = path;
+            if (famulusInfo) famulusInfo.managerPath = path;
+          }
+          return path;
+        })
+        .catch(() => null);
   const clock = realClock;
 
   // Claude-style transcript pills for notifications (TUI only; no-ops elsewhere).
@@ -392,12 +467,17 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
     clock,
     syncWithManager: deps.syncWithManager,
   });
-  registerFamulusCommand(pi, {
+  registerAttachCommand(pi, {
+    getClient: () => client,
+    getRegistry: () => subagentRegistry,
+  });
+  famulusInfo = {
     extensionVersion: EXTENSION_VERSION,
     managerPath,
     describeSearch: () => describeManagerSearch(config, home),
     getClient: () => client,
-  });
+  };
+  registerFamulusCommand(pi, famulusInfo);
   monitorRegistry.onChange(() => {
     for (const mon of monitorRegistry.listActive()) {
       const existing = workIndex.get(mon.taskId);
@@ -424,9 +504,11 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
   // M4: comms host bridges the registry and the NotifyCenter. A single Comms
   // instance lives at extension scope (mailbox is per-run namespaced; pending
   // waiters are resolved via dispose() on session_shutdown).
+  let watchResume: (childId: string) => void = () => {};
   const commsHost = createRegistryCommsHost({
     getRegistry: () => subagentRegistry,
     getNotifyCenter: () => notifyCenter,
+    onResumeAccepted: (childId) => watchResume(childId),
   });
   const comms: CommsWithOrigin = createComms(commsHost, {
     decisionTimeoutMs: subagentConfig.decisionTimeoutMs,
@@ -443,6 +525,9 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       defaultTimeoutMs: subagentConfig.timeoutMs,
       defaultConcurrency: subagentConfig.concurrency,
       clock,
+      registerResumeWatch: (watch) => {
+        watchResume = watch;
+      },
       resolveAgent: (name) => {
         const loader = agentLoader;
         if (!loader) return resolveAgentDef([], name); // builtins-only fallback
@@ -523,11 +608,48 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       sessionId: startCtx.sessionManager.getSessionId(),
       managerPath,
       cwd: startCtx.cwd,
+      sessionFile: startCtx.sessionManager.getSessionFile?.(),
       clock,
       log: () => {}, // keep quiet; degradation is surfaced via tools
     });
 
+    // Hosted children run bash in their own process. The parent learns the
+    // foreground shell from task_started (origin child-bash) so overrun wakes
+    // still carry <shell>.
+    const childShells = new ChildShellTracker();
+    const parentSessionId = startCtx.sessionManager.getSessionId();
     client.onEvent((event) => {
+      const hosted = event as ManagerEvent & {
+        child_id?: string;
+        reason?: string;
+        request_id?: string;
+        message?: string;
+        name?: string;
+        residency?: string;
+        driver?: string;
+        last_text?: string;
+      };
+      if (hosted.event === "agent_comms" && hosted.child_id && hosted.request_id) {
+        const reason = hosted.reason === "need_decision" ? "need_decision" : "progress_update";
+        void comms.contactSupervisor(hosted.child_id, reason, hosted.message ?? "").then((reply) => {
+          if (reason === "need_decision") void client?.agentCommsReply(hosted.request_id!, hosted.child_id!, reply).catch(() => {});
+        }).catch(() => {});
+        return;
+      }
+      if (hosted.event === "agent_detach" && hosted.child_id) {
+        notifyCenter?.notify({
+          customType: "pi-famulus-wake",
+          content: `System wake — not a new user message.\n\nThe user talked to ${hosted.name ?? hosted.child_id} directly.\n${hosted.last_text ?? ""}`,
+          details: { kind: "supervisor-update", from: hosted.child_id, name: hosted.name ?? hosted.child_id, message: hosted.last_text ?? "" },
+        });
+        return;
+      }
+      if (hosted.event === "agent_state" && hosted.child_id) {
+        const handle = subagentRegistry?.handle(hosted.child_id) as { pauseStall?: () => void; resumeStall?: () => void } | undefined;
+        if (hosted.driver === "user") handle?.pauseStall?.();
+        else handle?.resumeStall?.();
+        return;
+      }
       if (event.event === "task_started" && event.task_id) {
         const prior = taskMeta.get(event.task_id);
         taskMeta.set(event.task_id, {
@@ -539,6 +661,14 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
               ? { startedAt: prior.startedAt }
               : {}),
         });
+        if (event.origin?.via === "child-bash" && event.origin.child_id) {
+          childShells.start(event.origin.child_id, {
+            taskId: event.task_id,
+            command: event.command ?? "",
+            startedAt: typeof event.ts === "number" ? event.ts : clock.now(),
+            outputPath: taskOutputPath(home, parentSessionId, event.task_id),
+          });
+        }
         if (notifyOnExit.has(event.task_id) && typeof event.ts === "number") {
           upsertBackgroundTask(event.task_id, event.ts);
         }
@@ -561,6 +691,7 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         return;
       }
       if (event.event === "task_exited" && event.task_id) {
+        childShells.endByTask(event.task_id);
         // A known monitor closes (and patches the index via onExited); an
         // unknown id is buffered in case a monitor start is about to claim it.
         if (monitorRegistry?.handleExit(event.task_id, event)) return;
@@ -610,9 +741,7 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         "warning",
       );
     }
-    // The foreground shell each child is blocked on, for its overrun wake.
-    const childShells = new ChildShellTracker();
-    const createSession = createPiSessionFn({
+    const createSession = createHostedSessionFn({
       getModelRegistry: () => ctx?.modelRegistry ?? null,
       getModelRuntime: () => {
         const registry = ctx?.modelRegistry as { runtime?: unknown } | null | undefined;
@@ -623,29 +752,10 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       getScopedModels: () => ctx?.scopedModels ?? [],
       getCwd: () => ctx?.cwd ?? process.cwd(),
       getProjectTrusted: () => ctx?.isProjectTrusted() ?? false,
-      customTools: (req) => {
-        const tools: Array<ToolDefinition<any, any, any>> = [
-          // M4: every child can reach the supervisor and its siblings.
-          createContactSupervisorTool(comms, req.childId),
-          createAgentMessageTool(comms, { kind: "child", childId: req.childId, runId: req.runId }, commsHost, clock),
-        ];
-        // The no-background bash variant replaces the built-in bash inside
-        // child sessions (custom tools override builtins by name).
-        tools.push(
-          createChildBashTool({
-            getClient: () => client,
-            home,
-            sessionId: () => ctx?.sessionManager.getSessionId() ?? "",
-            sessionEnv: () => (ctx ? sessionEnv(ctx) : {}),
-            trackTask,
-            childId: req.childId,
-            runId: req.runId,
-            clock,
-            shells: childShells,
-          }),
-        );
-        return tools;
-      },
+      getClient: () => client,
+      getHome: () => home,
+      extensionEntry: fileURLToPath(import.meta.url),
+      piCommand: subagentConfig.piCommand,
     });
     // The registry outlives startCtx across a /reload, which leaves startCtx
     // stale; its closures keep plain values instead.
@@ -819,13 +929,23 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
     startFleetWidget(startCtx);
 
     // Connect in the background: a cold manager spawn must not stall the
-    // first prompt. Tools call ensureAvailable() lazily before use.
+    // first prompt. The cache install, if one is running, finishes first so a
+    // missing optional package is not reported before it can be restored.
+    // Tools call ensureAvailable() lazily before use.
     const c = client;
-    void c
-      .connect()
+    void nativeRestore
+      .then((path) => {
+        if (client !== c || !c) return null;
+        if (path) c.useManagerPath(path);
+        return c.connect();
+      })
       .then((ok) => {
+        if (ok === null || client !== c || !c) return;
         if (ok) {
           if (c.protocolLevel() >= 4) void reconcileAgentLeases(c).catch(() => {});
+          const file = startCtx.sessionManager.getSessionFile?.();
+          const sid = startCtx.sessionManager.getSessionId();
+          void promptIfHostedSession(c, () => ctx, { sessionFile: file, sessionId: sid }, "start").catch(() => {});
           return;
         }
         // A /reload may have replaced startCtx by now; report to the live one.
@@ -870,6 +990,14 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
   };
   const runtime: FamulusRuntime = { attach: (host) => binding.attach(host) };
 
+  pi.on("session_before_switch", async (event, switchCtx) => {
+    const file = event.targetSessionFile;
+    if (!file || !client?.isAvailable()) return;
+    const outcome = await promptIfHostedSession(client, () => switchCtx, { sessionFile: file }, "switch");
+    if (outcome === "none" || outcome === "takeover") return;
+    return { cancel: true };
+  });
+
   pi.on("session_shutdown", async (event) => {
     if (event.reason === "reload" && ctx) {
       // Keep the session's shells, monitors and subagents running; the

package/src/manager-client.ts

@@ -18,10 +18,10 @@ import { famulusPaths } from "./config";
 import { realClock, type Clock, type ClockTimer } from "./clock";
 
 const MAX_FRAME_BYTES = 4 * 1024 * 1024; // 4 MiB (§3.3)
-const EXTENSION_VERSION = "0.1.8";
+const EXTENSION_VERSION = "0.2.0";
 export { EXTENSION_VERSION };
 // 5: speaks per-kind agent admission and queued acquire.
-const PROTOCOL = 5;
+const PROTOCOL = 6;
 const HELLO_TIMEOUT_MS = 5000;
 const RECONNECT_HELLO_TIMEOUT_MS = 25_000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
@@ -124,6 +124,8 @@ export interface ManagerEvent {
   output_size?: number;
   end_reason?: string;
   ts?: number;
+  /** Set on task_started when the daemon recorded who asked for the task. */
+  origin?: { via: string; child_id?: string; run_id?: string };
 }
 
 export class ManagerError extends Error {
@@ -142,6 +144,12 @@ export interface ManagerClientOptions {
   piPid?: number;
   /** Session working directory, sent on hello (optional; older managers ignore it). */
   cwd?: string;
+  /** `parent` for a pi session, `child` for pi-famulus inside a hosted subagent. */
+  role?: "parent" | "child";
+  childId?: string;
+  token?: string;
+  /** Pi session file this process has open. */
+  sessionFile?: string;
   log?: (message: string) => void;
   clock?: Clock;
 }
@@ -285,9 +293,13 @@ function delay(clock: Clock, ms: number): Promise<void> {
 export class ManagerClient {
   private readonly home: string;
   private readonly sessionId: string;
-  private readonly managerPath: string | null;
+  private managerPath: string | null;
   private readonly piPid: number;
   private readonly cwd: string | undefined;
+  private readonly role: "parent" | "child";
+  private readonly childId: string | undefined;
+  private readonly token: string | undefined;
+  private readonly sessionFile: string | undefined;
   private readonly log: (message: string) => void;
   private readonly clock: Clock;
 
@@ -315,6 +327,10 @@ export class ManagerClient {
     this.managerPath = options.managerPath;
     this.piPid = options.piPid ?? process.pid;
     this.cwd = options.cwd;
+    this.role = options.role ?? "parent";
+    this.childId = options.childId;
+    this.token = options.token;
+    this.sessionFile = options.sessionFile;
     this.log = options.log ?? (() => {});
     this.clock = options.clock ?? realClock;
   }
@@ -327,6 +343,11 @@ export class ManagerClient {
     return this.state === "connected";
   }
 
+  /** A binary found after construction. The first path wins. */
+  useManagerPath(path: string): void {
+    if (!this.managerPath) this.managerPath = path;
+  }
+
   /** Maximum protocol level reported by the connected manager; 0 means unknown/legacy. */
   protocolLevel(): number {
     return this.protocolLevel_;
@@ -453,20 +474,140 @@ export class ManagerClient {
     childId: string,
     workKind = "other",
     signal?: AbortSignal,
-  ): Promise<{ granted: boolean; rejection?: string }> {
+  ): Promise<{ granted: boolean; rejection?: string; queuedBehind?: number }> {
     if (signal?.aborted) throw new Error("subagent admission cancelled");
     const message: Record<string, unknown> = { type: "acquire_agent", child_id: childId };
     if (this.protocolLevel_ >= 5) message.work_kind = workKind;
     // Protocol 4 has no cancel frame. Keep its immediate acquire correlated so
     // admission can release a grant that arrives after the generation aborts.
     const res = await this.request(message, DEFAULT_REQUEST_TIMEOUT_MS, this.protocolLevel_ >= 5 ? signal : undefined, true);
-    return { granted: res.granted === true, ...(typeof res.rejection === "string" ? { rejection: res.rejection } : {}) };
+    return {
+      granted: res.granted === true,
+      ...(typeof res.rejection === "string" ? { rejection: res.rejection } : {}),
+      ...(typeof res.queued_behind === "number" ? { queuedBehind: res.queued_behind } : {}),
+    };
   }
 
   async releaseAgent(childId: string): Promise<void> {
     await this.request({ type: "release_agent", child_id: childId });
   }
 
+  requireHostedProtocol(): void {
+    if (this.protocolLevel_ < 6) {
+      throw new Error(
+        "this pi-famulus daemon does not host subagents (protocol " +
+          `${this.protocolLevel_}; need 6). Restart pi so it starts the current daemon.`,
+      );
+    }
+  }
+
+  async agentSpawn(input: {
+    childId: string;
+    runId: string;
+    name: string;
+    argv: string[];
+    cwd: string;
+    env: Record<string, string>;
+  }): Promise<Record<string, unknown>> {
+    this.requireHostedProtocol();
+    return this.request({
+      type: "agent_spawn",
+      child_id: input.childId,
+      run_id: input.runId,
+      name: input.name,
+      argv: input.argv,
+      cwd: input.cwd,
+      env: input.env,
+    }, 20_000);
+  }
+
+  async agentInput(childId: string, op: string, text: string, source = "parent", since?: string): Promise<Record<string, unknown>> {
+    this.requireHostedProtocol();
+    return this.request({
+      type: "agent_input",
+      child_id: childId,
+      op,
+      text,
+      source,
+      ...(since ? { since } : {}),
+    }, 20_000);
+  }
+
+  async agentWatch(childId: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_watch", child_id: childId });
+  }
+
+  async agentUnwatch(childId: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_unwatch", child_id: childId });
+  }
+
+  async agentPeers(): Promise<Array<{ childId: string; name: string; runId: string; activity: string; residency: string }>> {
+    this.requireHostedProtocol();
+    const res = await this.request({ type: "agent_peers" });
+    const peers = Array.isArray(res.peers) ? res.peers : [];
+    return peers.flatMap((peer) => {
+      if (!peer || typeof peer !== "object") return [];
+      const row = peer as Record<string, unknown>;
+      if (typeof row.child_id !== "string") return [];
+      return [{
+        childId: row.child_id,
+        name: typeof row.name === "string" ? row.name : row.child_id,
+        runId: typeof row.run_id === "string" ? row.run_id : "",
+        activity: typeof row.activity === "string" ? row.activity : "idle",
+        residency: typeof row.residency === "string" ? row.residency : "",
+      }];
+    });
+  }
+
+  async agentPark(childId: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_park", child_id: childId });
+  }
+
+  async agentTakeover(childId: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_takeover", child_id: childId });
+  }
+
+  async hostedLookup(query: { sessionId?: string; sessionFile?: string }): Promise<Record<string, unknown> | null> {
+    if (this.protocolLevel_ < 6) return null;
+    const res = await this.request({
+      type: "hosted_lookup",
+      ...(query.sessionId ? { session_id: query.sessionId } : {}),
+      ...(query.sessionFile ? { session_file: query.sessionFile } : {}),
+    });
+    const hosted = res.hosted;
+    return hosted && typeof hosted === "object" ? hosted as Record<string, unknown> : null;
+  }
+
+  async agentComms(requestId: string, reason: string, message: string): Promise<string> {
+    this.requireHostedProtocol();
+    const res = await this.request({ type: "agent_comms", request_id: requestId, reason, message }, 11 * 60 * 1000);
+    return typeof res.reply === "string" ? res.reply : "";
+  }
+
+  async agentCommsReply(requestId: string, childId: string, message: string): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_comms_reply", request_id: requestId, child_id: childId, message });
+  }
+
+  async agentUiResponse(childId: string, rpcId: string, value: Record<string, unknown>, cancelled: boolean): Promise<void> {
+    this.requireHostedProtocol();
+    await this.request({ type: "agent_ui_response", child_id: childId, rpc_id: rpcId, value, cancelled });
+  }
+
+  async agentCache(expiresAt: number | null, tier: string | null, lifetimeMs: number | null): Promise<void> {
+    if (this.protocolLevel_ < 6) return;
+    await this.request({
+      type: "agent_cache",
+      ...(expiresAt !== null ? { expires_at: expiresAt } : {}),
+      ...(tier ? { tier } : {}),
+      ...(lifetimeMs !== null ? { lifetime_ms: lifetimeMs } : {}),
+    });
+  }
+
   /** Daemon status, including optional in-place upgrade metadata. */
   async status(): Promise<ManagerStatusResponse> {
     const res = await this.request({ type: "status" });
@@ -769,6 +910,10 @@ export class ManagerClient {
           ...(this.cwd ? { cwd: this.cwd } : {}),
           extension_version: EXTENSION_VERSION,
           protocol: PROTOCOL,
+          role: this.role,
+          ...(this.sessionFile ? { session_file: this.sessionFile } : {}),
+          ...(this.childId ? { child_id: this.childId } : {}),
+          ...(this.token ? { token: this.token } : {}),
         }),
       );
     });
@@ -860,7 +1005,7 @@ export class ManagerClient {
     waitForAdmission = false,
   ): Promise<Record<string, unknown>> {
     const type = String(msg.type);
-    const retryable = ["wait", "output", "list", "watch", "status", "stop", "mark_background", "start", "acquire_agent", "cancel_acquire_agent", "release_agent"].includes(type);
+    const retryable = ["wait", "output", "list", "watch", "status", "stop", "mark_background", "start", "acquire_agent", "cancel_acquire_agent", "release_agent", "agent_spawn", "agent_watch", "agent_park", "agent_peers", "hosted_lookup"].includes(type);
     const effectiveTimeoutMs = retryable ? Math.max(timeoutMs, RECONNECT_WINDOW_MS + 1000) : timeoutMs;
     return new Promise((resolve, reject) => {
       if (signal?.aborted) {

package/src/native-manager.d.ts

@@ -3,7 +3,37 @@ export interface NativeManagerOptions {
   arch?: string;
   /** Node package resolver; tests can use createRequire from an isolated consumer. */
   resolve?: (specifier: string) => string;
+  /** Walk node_modules from this file instead of this module. */
+  from?: string;
+  /** Do not walk above this directory. */
+  stopAt?: string;
+  /** Versioned platform cache. `false` disables the cache lookup. */
+  cacheDir?: string | false;
+}
+export interface NativeCacheOptions {
+  version?: string;
+  platform?: string;
+  arch?: string;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+}
+export interface EnsureNativeOptions extends NativeManagerOptions {
+  env?: NodeJS.ProcessEnv;
+  npmCommand?: string;
+  spawn?: (
+    command: string,
+    args: string[],
+    options?: { timeout?: number; windowsHide?: boolean; encoding?: "utf8" },
+  ) => { status: number | null; error?: Error };
 }
 export function nativePackageName(platform: string, arch: string): string | null;
+export function nativeCacheDir(options?: NativeCacheOptions): string;
 /** Null when unsupported, missing, corrupt, non-executable, or a different version. */
 export function resolveNativeManagerPath(options?: NativeManagerOptions): string | null;
+/** `npm <package> <path>` or why the exact platform package was not usable. */
+export function describeNativeLookup(options?: NativeManagerOptions): string;
+/**
+ * Install the exact platform package into the versioned cache when it is missing.
+ * Returns the binary path, or null when it is still unusable.
+ */
+export function ensureNativeManagerInstalled(options?: EnsureNativeOptions): string | null;