pi-famulus 0.1.2 → 0.1.4

package/src/manager-client.ts

@@ -1,7 +1,8 @@
 /**
  * pi-famulus unix socket client (design doc §4.1, protocol §3.3).
  *
- * - Implements the §3.1 startup flow: connect -> spawn via lock -> zombie cleanup.
+ * - Implements §3.1 startup: connect -> spawn via lock; only the daemon's
+ *   lifetime-lock holder cleans up stale socket/pid files.
  * - Request/response multiplexing over a single long-lived connection.
  * - Server events dispatched to registered handlers.
  * - On unexpected disconnect: immediate then exponential-backoff reconnect for 22s,
@@ -12,21 +13,24 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import net from "node:net";
+import { StringDecoder } from "node:string_decoder";
 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.2";
-// 3: speaks in-place upgrade (resends on reconnect, start keys).
-const PROTOCOL = 3;
+const EXTENSION_VERSION = "0.1.4";
+// 5: speaks per-kind agent admission and queued acquire.
+const PROTOCOL = 5;
 const HELLO_TIMEOUT_MS = 5000;
 const RECONNECT_HELLO_TIMEOUT_MS = 25_000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
-const SOCKET_READY_TIMEOUT_MS = 2000;
+// One bounded startup budget: keep waiting for a live child, but only
+// respawn when it explicitly reports losing the daemon's lifetime lock.
+const STARTUP_WINDOW_MS = 10_000;
 const SOCKET_READY_POLL_MS = 50;
 const RECONNECT_WINDOW_MS = 27_000;
 const RETRY_COOLDOWN_MS = 30000;
-const MANAGER_SHUTDOWN_WAIT_MS = 5000;
+const SHUTDOWN_PROBE_TIMEOUT_MS = 2000;
 const MANAGER_SHUTTING_DOWN = "manager is shutting down";
 
 // ---------------------------------------------------------------------------
@@ -152,13 +156,23 @@ type ClientState = "disconnected" | "connected" | "unavailable";
 
 type EventHandler = (event: ManagerEvent) => void;
 
+interface SpawnAttempt {
+  failure?: Error;
+  contended: boolean;
+  output: string;
+  dispose(): void;
+}
+
 interface PendingRequest {
   resolve: (value: Record<string, unknown>) => void;
   reject: (err: Error) => void;
-  timer: ClockTimer;
+  timer?: ClockTimer;
+  retryTimer?: ClockTimer;
   message: Record<string, unknown>;
   timeoutMs: number;
   retryable: boolean;
+  requestId?: string;
+  removeAbortListener?: () => void;
 }
 
 /** Reassembles `u32 BE length + JSON` frames from a byte stream. */
@@ -266,6 +280,7 @@ export class ManagerClient {
   private helloWaiter: { resolve: () => void; reject: (err: Error) => void } | null = null;
   private eventHandlers = new Set<EventHandler>();
   private reconnectHandlers = new Set<() => void>();
+  private protocolLevel_ = 0;
   private state: ClientState = "disconnected";
   private intentionalClose = false;
   private rebound = false;
@@ -293,6 +308,11 @@ export class ManagerClient {
     return this.state === "connected";
   }
 
+  /** Maximum protocol level reported by the connected manager; 0 means unknown/legacy. */
+  protocolLevel(): number {
+    return this.protocolLevel_;
+  }
+
   /** Last connect/reconnect failure reason (empty when never failed / currently connected). */
   lastError(): string {
     return this.lastFailureMessage;
@@ -338,14 +358,16 @@ export class ManagerClient {
     let run!: Promise<boolean>;
     run = (async (): Promise<boolean> => {
       try {
-        await this.connectFlow(true);
+        await this.connectFlow();
+        this.checkStartupOpen();
         this.state = "connected";
+        this.lastFailureMessage = "";
         return true;
       } catch (err) {
-        this.log(`connect failed: ${(err as Error).message}`);
-        this.state = "unavailable";
+        this.state = this.intentionalClose ? "disconnected" : "unavailable";
         this.lastFailureAt = this.now();
-        this.lastFailureMessage = (err as Error).message;
+        this.lastFailureMessage = this.startupFailureDetails((err as Error).message);
+        this.log(`connect failed: ${this.lastFailureMessage}`);
         return false;
       } finally {
         if (this.connecting === run) this.connecting = null;
@@ -403,6 +425,24 @@ export class ManagerClient {
     return ((res.tasks as TaskRecord[] | undefined) ?? []) as TaskRecord[];
   }
 
+  async acquireAgent(
+    childId: string,
+    workKind = "other",
+    signal?: AbortSignal,
+  ): Promise<{ granted: boolean; rejection?: string }> {
+    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 } : {}) };
+  }
+
+  async releaseAgent(childId: string): Promise<void> {
+    await this.request({ type: "release_agent", child_id: childId });
+  }
+
   /** Daemon status, including optional in-place upgrade metadata. */
   async status(): Promise<ManagerStatusResponse> {
     const res = await this.request({ type: "status" });
@@ -446,85 +486,85 @@ export class ManagerClient {
   // Startup flow (§3.1)
   // -------------------------------------------------------------------------
 
-  private async connectFlow(allowZombieRetry: boolean, helloTimeoutMs = HELLO_TIMEOUT_MS): Promise<void> {
+  private checkStartupOpen(): void {
+    if (this.intentionalClose) throw new Error("manager client closed");
+  }
+
+  private async connectFlow(helloTimeoutMs = HELLO_TIMEOUT_MS, outerDeadline = Infinity): Promise<void> {
     const paths = famulusPaths(this.home);
-    try {
-      await this.connectAndHello(paths.socket, helloTimeoutMs);
-      return;
-    } catch (err) {
-      if (err instanceof HelloError) {
-        if (err.message.includes(MANAGER_SHUTTING_DOWN)) {
-          // A shutdown manager refuses hello while it completes its bounded
-          // kill grace. Wait for its pid to exit before retrying/spawning.
-          await this.waitForManagerExit(paths.pidFile);
-          if (allowZombieRetry) {
-            await this.connectFlow(false, helloTimeoutMs);
-            return;
-          }
-          throw err;
-        }
-        // Socket exists but hello failed: possible zombie socket (§3.1 step 5).
-        this.handleZombie(paths.socket, paths.pidFile);
-        if (allowZombieRetry) {
-          await this.connectFlow(false, helloTimeoutMs);
-          return;
+    const deadline = Math.min(outerDeadline, this.now() + Math.max(STARTUP_WINDOW_MS, helloTimeoutMs));
+    let shutdownObserved = false;
+    let retryDelayMs = 100;
+    let lastReason = "";
+    for (;;) {
+      this.checkStartupOpen();
+      if (this.now() >= deadline) throw new Error(`pi-famulus startup deadline exhausted: ${lastReason}`);
+      const probeMs = shutdownObserved ? SHUTDOWN_PROBE_TIMEOUT_MS : helloTimeoutMs;
+      try {
+        await this.connectAndHello(paths.socket, Math.min(probeMs, deadline - this.now()));
+        return;
+      } catch (err) {
+        lastReason = (err as Error).message;
+        if (!(err instanceof HelloError)) {
+          // Nobody listening: the daemon's lifetime lock safely arbitrates
+          // any spawn, including a retiring owner whose files are gone.
+          await this.ensureSocketReady(paths.socket, paths.spawnLock, deadline);
+          continue;
         }
-        throw err;
+        if (err.message === `E_INTERNAL: ${MANAGER_SHUTTING_DOWN}`) shutdownObserved = true;
+        else if (!shutdownObserved || !err.transportFailure) throw err;
+        // Only a known shutdown permits retrying a stalled/lost handshake.
+        // Re-probe instead of trusting pid liveness: that pid may be stale,
+        // and another client may already have started a healthy successor.
       }
-      // Connect failed: nobody listening. Try to spawn the manager.
+      await delay(this.clock, Math.min(retryDelayMs, Math.max(0, deadline - this.now())));
+      retryDelayMs = Math.min(retryDelayMs * 2, 1000);
     }
+  }
 
+  private async ensureSocketReady(socketPath: string, spawnLock: string, deadline: number): Promise<void> {
     // The home directory may not exist yet on a fresh machine.
     mkdirSync(this.home, { recursive: true });
-    const acquired = this.tryAcquireSpawnLock(paths.spawnLock);
-    if (acquired) {
+    let contentionDelayMs = 100;
+    let lastContention = "";
+    for (;;) {
+      this.checkStartupOpen();
+      if (this.now() >= deadline) throw new Error(`pi-famulus startup deadline exhausted${lastContention ? ` after contention: ${lastContention}` : ""}`);
+      const acquired = this.tryAcquireSpawnLock(spawnLock);
+      let attempt: SpawnAttempt | undefined;
       try {
-        this.spawnManager();
-        await this.waitForSocket(paths.socket, SOCKET_READY_TIMEOUT_MS);
+        if (acquired) attempt = this.spawnManager();
+        await this.waitForSocket(socketPath, deadline - this.now(), attempt);
+        break;
+      } catch (err) {
+        // A daemon that lost manager.lock exits successfully, but did NOT
+        // start our successor. Retry only this explicit contention state.
+        if (!attempt?.contended || this.now() >= deadline) throw err;
+        lastContention = attempt.failure?.message ?? "daemon lifetime lock held";
+        this.log(`startup contention: ${lastContention}; retrying after ${contentionDelayMs}ms`);
       } finally {
-        this.releaseSpawnLock(paths.spawnLock);
+        attempt?.dispose();
+        if (acquired) this.releaseSpawnLock(spawnLock);
       }
-    } else {
-      // Someone else is spawning; just wait for the socket to appear.
-      await this.waitForSocket(paths.socket, SOCKET_READY_TIMEOUT_MS);
+      await delay(this.clock, Math.min(contentionDelayMs, deadline - this.now()));
+      contentionDelayMs = Math.min(contentionDelayMs * 2, 1000);
     }
-    await this.connectAndHello(paths.socket, helloTimeoutMs);
   }
 
-  private async waitForManagerExit(pidFile: string): Promise<void> {
-    let pid: number;
+  private startupFailureDetails(reason: string): string {
+    const paths = famulusPaths(this.home);
+    let managerPid = "missing/unreadable";
+    let spawnHolder = "missing/unreadable";
+    const describePid = (pid: number) => `${pid} (${pidAlive(pid) ? "alive" : "dead"})`;
     try {
-      const info = JSON.parse(readFileSync(pidFile, "utf8")) as { pid?: number };
-      if (typeof info.pid !== "number") return;
-      pid = info.pid;
-    } catch {
-      return;
-    }
-    const deadline = this.now() + MANAGER_SHUTDOWN_WAIT_MS;
-    while (pidAlive(pid) && this.now() < deadline) {
-      await this.clock.sleep(SOCKET_READY_POLL_MS);
-    }
-  }
-
-  private handleZombie(socketPath: string, pidFile: string): void {
-    let pid: number | null = null;
+      const info = JSON.parse(readFileSync(paths.pidFile, "utf8")) as { pid?: number };
+      if (typeof info.pid === "number") managerPid = describePid(info.pid);
+    } catch { /* diagnostic only */ }
     try {
-      const info = JSON.parse(readFileSync(pidFile, "utf8")) as { pid?: number };
-      if (typeof info.pid === "number") pid = info.pid;
-    } catch {
-      // no readable pid file
-    }
-    if (pid !== null && pidAlive(pid)) {
-      // Manager is alive but rejected hello; nothing to clean up.
-      return;
-    }
-    for (const file of [socketPath, pidFile]) {
-      try {
-        unlinkSync(file);
-      } catch {
-        // already gone
-      }
-    }
+      const raw = readFileSync(paths.spawnLock, "utf8").trim();
+      spawnHolder = /^\d+$/.test(raw) ? describePid(Number(raw)) : "empty/non-pid";
+    } catch { /* diagnostic only */ }
+    return `${reason}; home=${this.home}; binary=${this.managerPath ?? "missing"}; socket=${existsSync(paths.socket) ? "present" : "missing"}; manager.pid=${managerPid}; spawn.lock=${spawnHolder}`;
   }
 
   /**
@@ -541,7 +581,7 @@ export class ManagerClient {
     releaseSpawnLockFile(lockPath);
   }
 
-  private spawnManager(): void {
+  private spawnManager(): SpawnAttempt {
     if (!this.managerPath) {
       throw new Error("pi-famulus binary not found (set managerPath in config.json or PI_FAMULUS_MANAGER_PATH)");
     }
@@ -549,31 +589,58 @@ export class ManagerClient {
     // this.home came from an explicit override rather than the environment.
     const child = spawn(this.managerPath, ["--home", this.home, "daemon"], {
       detached: true,
-      stdio: "ignore",
+      stdio: ["ignore", "pipe", "pipe"],
       env: process.env,
     });
+    const streams = [child.stdout, child.stderr];
+    // Each pipe owns its partial UTF-8 bytes; interleaved streams cannot share carry.
+    const decoders = streams.map(() => new StringDecoder("utf8"));
+    const attempt: SpawnAttempt = {
+      contended: false,
+      output: "",
+      dispose: () => {
+        // Keep draining detached daemon pipes without keeping pi alive.
+        // Closing a live child's reader would turn a later write into SIGPIPE.
+        streams.forEach((stream, index) => {
+          stream?.off("data", captures[index]);
+          stream?.resume();
+          (stream as net.Socket | null)?.unref?.();
+        });
+      },
+    };
+    const append = (text: string) => {
+      const tail = (attempt.output + text).slice(-2048);
+      // A UTF-16 bound must not retain just the low half of a surrogate pair.
+      const first = tail.charCodeAt(0);
+      attempt.output = first >= 0xdc00 && first <= 0xdfff ? tail.slice(1) : tail;
+    };
+    const captures = decoders.map((decoder) => (data: Buffer) => append(decoder.write(data)));
+    streams.forEach((stream, index) => stream?.on("data", captures[index]));
     child.unref();
-    child.on("error", () => {}); // surfaced via waitForSocket timeout
+    child.on("error", (err) => { attempt.failure = new Error(`manager spawn failed: ${err.message}`); });
+    // 'close' follows stdio EOF; 'exit' alone may precede the contention line.
+    child.on("close", (code, signal) => {
+      for (const decoder of decoders) append(decoder.end());
+      attempt.contended = code === 0 && attempt.output.includes("pi-famulus already running");
+      attempt.failure = new Error(`manager exited before socket ready (code=${code}, signal=${signal}): ${attempt.output.trim()}`);
+    });
+    return attempt;
   }
 
-  private async waitForSocket(socketPath: string, timeoutMs: number): Promise<void> {
+  private async waitForSocket(socketPath: string, timeoutMs: number, attempt?: SpawnAttempt): Promise<void> {
     const deadline = this.now() + timeoutMs;
     for (;;) {
+      this.checkStartupOpen();
       if (existsSync(socketPath)) {
-        const ok = await new Promise<boolean>((resolve) => {
-          const probe = net.connect(socketPath);
-          probe.once("connect", () => {
-            probe.destroy();
-            resolve(true);
-          });
-          probe.once("error", () => resolve(false));
-        });
+        const ok = await this.openSocket(socketPath, Math.min(SOCKET_READY_POLL_MS, Math.max(0, deadline - this.now())))
+          .then((probe) => { probe.destroy(); return true; }, () => false);
         if (ok) return;
       }
+      if (attempt?.failure) throw attempt.failure;
       if (this.now() >= deadline) {
-        throw new Error("timed out waiting for pi-famulus socket");
+        throw new Error(`timed out waiting for pi-famulus socket (spawn=${attempt ? "running" : "other holder"}${attempt?.output ? `, output=${attempt.output.trim()}` : ""})`);
       }
-      await delay(this.clock, SOCKET_READY_POLL_MS);
+      await delay(this.clock, Math.min(SOCKET_READY_POLL_MS, deadline - this.now()));
     }
   }
 
@@ -581,18 +648,36 @@ export class ManagerClient {
   // Connection / protocol internals
   // -------------------------------------------------------------------------
 
-  private async connectAndHello(socketPath: string, helloTimeoutMs = HELLO_TIMEOUT_MS): Promise<void> {
-    const socket = await new Promise<net.Socket>((resolve, reject) => {
-      const s = net.connect(socketPath);
-      s.once("connect", () => resolve(s));
-      s.once("error", (err) => reject(err));
+  private openSocket(socketPath: string, timeoutMs: number): Promise<net.Socket> {
+    return new Promise((resolve, reject) => {
+      const socket = net.connect(socketPath);
+      const timer = this.clock.setTimeout(() => {
+        socket.destroy();
+        reject(new Error("timed out connecting to pi-famulus socket"));
+      }, Math.max(0, timeoutMs));
+      socket.once("connect", () => { this.clock.clearTimeout(timer); resolve(socket); });
+      socket.once("error", (err) => {
+        this.clock.clearTimeout(timer);
+        socket.destroy();
+        reject(err);
+      });
     });
+  }
+
+  private async connectAndHello(socketPath: string, helloTimeoutMs = HELLO_TIMEOUT_MS): Promise<void> {
+    const deadline = this.now() + Math.max(0, helloTimeoutMs);
+    const socket = await this.openSocket(socketPath, helloTimeoutMs);
+    if (this.intentionalClose) {
+      socket.destroy();
+      this.checkStartupOpen();
+    }
     this.attachSocket(socket);
     try {
-      await this.hello(helloTimeoutMs);
+      await this.hello(Math.max(0, deadline - this.now()));
     } catch (err) {
       this.detachSocket();
-      throw new HelloError((err as Error).message);
+      const reason = err instanceof ManagerError ? `${err.code}: ${err.message}` : (err as Error).message;
+      throw new HelloError(reason, !(err instanceof ManagerError));
     }
   }
 
@@ -646,7 +731,7 @@ export class ManagerClient {
       this.helloWaiter = { resolve: () => done(), reject: (err) => done(err) };
       this.pending.set(id, {
         resolve: () => done(), reject: (err) => done(err), timer,
-        message: { type: "hello" }, timeoutMs, retryable: false,
+        message: { type: "hello" }, timeoutMs, retryable: false, requestId: id,
       });
       socket.write(
         encodeFrame({
@@ -670,6 +755,9 @@ export class ManagerClient {
       messages = this.decoder.push(data);
     } catch (err) {
       this.log(`protocol error: ${(err as Error).message}`);
+      // Preserve the actual handshake failure before onClose replaces it
+      // with a generic connection-lost error.
+      this.helloWaiter?.reject(new ManagerError("E_PROTOCOL", (err as Error).message));
       this.detachSocket();
       this.onClose();
       return;
@@ -715,33 +803,88 @@ export class ManagerClient {
     const entry = this.pending.get(id);
     if (!entry) return;
     this.pending.delete(id);
-    this.clock.clearTimeout(entry.timer);
+    if (entry.timer !== undefined) this.clock.clearTimeout(entry.timer);
+    if (entry.retryTimer !== undefined) this.clock.clearInterval(entry.retryTimer);
+    entry.removeAbortListener?.();
     if (msg.ok === true) {
+      if (entry.message.type === "hello") {
+        const serverMaximum = typeof msg.protocol === "number" ? msg.protocol : 0;
+        this.protocolLevel_ = Math.min(PROTOCOL, serverMaximum);
+      }
       entry.resolve(msg);
     } else {
       entry.reject(errorFromResponse(msg));
     }
   }
 
-  private request(msg: Record<string, unknown>, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS): Promise<Record<string, unknown>> {
+  private request(
+    msg: Record<string, unknown>,
+    timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+    signal?: AbortSignal,
+    waitForAdmission = false,
+  ): Promise<Record<string, unknown>> {
     const type = String(msg.type);
-    const retryable = ["wait", "output", "list", "watch", "status", "stop", "mark_background", "start"].includes(type);
+    const retryable = ["wait", "output", "list", "watch", "status", "stop", "mark_background", "start", "acquire_agent", "cancel_acquire_agent", "release_agent"].includes(type);
     const effectiveTimeoutMs = retryable ? Math.max(timeoutMs, RECONNECT_WINDOW_MS + 1000) : timeoutMs;
     return new Promise((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(new Error("subagent admission cancelled"));
+        return;
+      }
       const entry: PendingRequest = {
-        resolve, reject, message: msg, timeoutMs: effectiveTimeoutMs, retryable,
-        timer: this.clock.setTimeout(() => {
-          for (const [id, pending] of this.pending) {
-            if (pending === entry) this.pending.delete(id);
-          }
-          this.queuedRequests.delete(entry);
-          reject(new Error(`pi-famulus request timed out: ${type}`));
-        }, effectiveTimeoutMs),
+        resolve,
+        reject,
+        message: msg,
+        timeoutMs: effectiveTimeoutMs,
+        retryable,
+      };
+      const removeEntry = () => {
+        if (entry.requestId) this.pending.delete(entry.requestId);
+        this.queuedRequests.delete(entry);
+        if (entry.timer !== undefined) this.clock.clearTimeout(entry.timer);
+        if (entry.retryTimer !== undefined) this.clock.clearInterval(entry.retryTimer);
+        entry.removeAbortListener?.();
       };
+      const cancelRemoteAcquire = () => {
+        const requestId = entry.requestId;
+        if (type === "acquire_agent" && this.protocolLevel_ >= 5 && requestId) {
+          // Protocol-5 cancellation is retryable across reconnects, so a grant
+          // raced with a dropped socket cannot outlive the cancelled generation.
+          void this.request({
+            type: "cancel_acquire_agent",
+            request_id: requestId,
+            child_id: msg.child_id,
+          }).catch(() => {});
+        }
+      };
+      if (effectiveTimeoutMs > 0 && !(waitForAdmission && signal)) {
+        entry.timer = this.clock.setTimeout(() => {
+          cancelRemoteAcquire();
+          removeEntry();
+          reject(new Error(`pi-famulus request timed out: ${type}`));
+        }, effectiveTimeoutMs);
+      }
+      if (waitForAdmission && type === "acquire_agent") {
+        entry.retryTimer = this.clock.setInterval(() => {
+          const id = entry.requestId;
+          const socket = this.socket;
+          if (!id || this.pending.get(id) !== entry || !socket || this.state !== "connected") return;
+          socket.write(encodeFrame({ v: 1, id, ...entry.message }));
+        }, 3000);
+      }
+      if (signal) {
+        const onAbort = () => {
+          cancelRemoteAcquire();
+          removeEntry();
+          reject(new Error("subagent admission cancelled"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        entry.removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+      }
       if (this.socket && this.state === "connected") this.sendPending(entry);
       else if (retryable && (this.reconnecting || this.connecting)) this.queuedRequests.add(entry);
       else {
-        this.clock.clearTimeout(entry.timer);
+        removeEntry();
         reject(new Error("pi-famulus not connected"));
       }
     });
@@ -750,7 +893,8 @@ export class ManagerClient {
   private sendPending(entry: PendingRequest): void {
     const socket = this.socket;
     if (!socket || this.state !== "connected") return;
-    const id = randomUUID();
+    const id = entry.requestId ?? randomUUID();
+    entry.requestId = id;
     this.pending.set(id, entry);
     socket.write(encodeFrame({ v: 1, id, ...entry.message }));
   }
@@ -768,7 +912,9 @@ export class ManagerClient {
     for (const [id, entry] of [...this.pending]) {
       if (entry.retryable && !this.intentionalClose && !this.rebound) continue;
       this.pending.delete(id);
-      this.clock.clearTimeout(entry.timer);
+      if (entry.timer !== undefined) this.clock.clearTimeout(entry.timer);
+      if (entry.retryTimer !== undefined) this.clock.clearInterval(entry.retryTimer);
+      entry.removeAbortListener?.();
       entry.reject(new Error("pi-famulus connection lost"));
     }
     if (this.helloWaiter) {
@@ -796,7 +942,8 @@ export class ManagerClient {
       if (nextDelayMs > 0) await delay(this.clock, Math.min(nextDelayMs, deadline - this.now()));
       if (this.intentionalClose || this.rebound) return;
       try {
-        await this.connectFlow(true, RECONNECT_HELLO_TIMEOUT_MS);
+        await this.connectFlow(RECONNECT_HELLO_TIMEOUT_MS, deadline);
+        if (this.intentionalClose || this.rebound) return;
         this.state = "connected";
         this.resendPending();
         this.log("reconnected to pi-famulus");
@@ -823,7 +970,9 @@ export class ManagerClient {
   private failAllPending(err: Error): void {
     const entries = new Set([...this.pending.values(), ...this.queuedRequests]);
     for (const entry of entries) {
-      this.clock.clearTimeout(entry.timer);
+      if (entry.timer !== undefined) this.clock.clearTimeout(entry.timer);
+      if (entry.retryTimer !== undefined) this.clock.clearInterval(entry.retryTimer);
+      entry.removeAbortListener?.();
       entry.reject(err);
     }
     this.pending.clear();
@@ -831,7 +980,9 @@ export class ManagerClient {
   }
 }
 
-class HelloError extends Error {}
+class HelloError extends Error {
+  constructor(message: string, readonly transportFailure: boolean) { super(message); }
+}
 
 function errorFromResponse(msg: Record<string, unknown>): ManagerError {
   const err = msg.error as { code?: string; message?: string } | undefined;

package/src/monitor.ts

@@ -10,11 +10,13 @@
 import { Type } from "typebox";
 import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { formatMonitorEvent } from "./format";
+import { MONITOR_IDLE_INSTRUCTION } from "./behavior-guidelines";
 import { realClock, type Clock, type ClockTimer } from "./clock";
 
 import type { ManagerClient, ManagerEvent, TaskRecord } from "./manager-client";
 import { LineBatcher, RateLimiter, SaturationWindow } from "./monitor-batching";
 import type { NotifyCenter } from "./notify";
+import { fill, fillList, PROMPTS } from "./prompts.generated";
 import { statusGlyph, toolComponent } from "./tui/tool-component";
 
 
@@ -40,10 +42,7 @@ const EXIT_AFTER_EVENT_MS = 2_000;
  * 2026-09-30c: 5 of the 6 FAILs outside grok). Its "Keep working" was tried
  * and dropped: gpt-6-luna started duplicate monitors (eval 2026-09-30d).
  */
-export const MONITOR_STARTED_INSTRUCTION =
-  'You will get a <pi-famulus-wake kind="monitor"> for each event, and a notice when it exits or times out. ' +
-  "Do not poll it (task_list, task_output, or reading what it watches) or sleep. " +
-  "If nothing else is left to do, reply to the user now with no tool call.";
+export const MONITOR_STARTED_INSTRUCTION = fill("tools.monitor.result.started", { monitorIdle: MONITOR_IDLE_INSTRUCTION });
 /**
  * Events for ids the registry does not know yet. The manager streams a monitor
  * from spawn, so output and even the exit can arrive before `start()` has the
@@ -440,24 +439,18 @@ function fullEnv(ctx: ExtensionContext, deps: MonitorDeps): Record<string, strin
 }
 
 const monitorParameters = Type.Object({
-  command: Type.String({
-    description:
-      "Command producing one event per line on stdout. Must be line-buffered " +
-      "(e.g. use `stdbuf -oL` / `grep --line-buffered` where needed).",
-  }),
-  description: Type.String({
-    description: "Short human-readable description of what is being watched",
-  }),
+  command: Type.String({ description: PROMPTS["tools.monitor.param.command"] }),
+  description: Type.String({ description: PROMPTS["tools.monitor.param.description"] }),
   timeout_ms: Type.Optional(
     Type.Number({
-      description: `Stop the monitor after this many milliseconds (default ${DEFAULT_TIMEOUT_MS}, min ${MIN_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS})`,
-    }),
-  ),
-  persistent: Type.Optional(
-    Type.Boolean({
-      description: "Keep the monitor alive until the session ends (no timeout). Default false.",
+      description: fill("tools.monitor.param.timeout_ms", {
+        defaultMs: DEFAULT_TIMEOUT_MS,
+        minMs: MIN_TIMEOUT_MS,
+        maxMs: MAX_TIMEOUT_MS,
+      }),
     }),
   ),
+  persistent: Type.Optional(Type.Boolean({ description: PROMPTS["tools.monitor.param.persistent"] })),
 });
 
 export function createMonitorTool(
@@ -466,21 +459,9 @@ export function createMonitorTool(
   return {
     name: "monitor",
     label: "Monitor",
-    description:
-      "Start a background monitor process whose stdout lines are injected back to you as " +
-      "<pi-famulus-wake kind=\"monitor\"> messages (batched over 200ms, rate-limited). " +
-      "The command must be line-buffered: each event must be a single line. " +
-      "It must keep running and follow its source, e.g. `tail -n +1 -F file | grep --line-buffered PATTERN`; " +
-      "a command that reads once and exits (a plain grep or cat) only reports what is there now. " +
-      "Add `-m1` to grep to stop after the first match. " +
-      "Silence is not success: write the command so failures also produce lines " +
-      "(e.g. grep for both success and error patterns). " +
-      "Events arrive as system wakes (not new user messages). Handle each <pi-famulus-wake kind=\"monitor\"> before other work. Do not poll.",
-    promptSnippet: "Watch a command's line stream and get injected events",
-    promptGuidelines: [
-      "Use the monitor tool to watch for conditions instead of running sleep/poll loops in bash.",
-      "When woken by a <pi-famulus-wake kind=\"monitor\">, handle the <event> before doing anything else — it is not a new user request and not user confirmation.",
-    ],
+    description: fill("tools.monitor.description", { monitorIdle: MONITOR_IDLE_INSTRUCTION }),
+    promptSnippet: PROMPTS["tools.monitor.snippet"],
+    promptGuidelines: fillList("tools.monitor.rules", { monitorIdle: MONITOR_IDLE_INSTRUCTION }),
     parameters: monitorParameters,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const { taskId, timeoutMs } = await registry.start(params, ctx);