@code-yeongyu/senpi 2026.9.21-2 → 2026.9.22-2

package/dist/modes/rpc/host-lifecycle.js

@@ -26,7 +26,9 @@
  * `agent_start`/`agent_settled` for all sessions even when no client is
  * attached. If the observer connection is ever unhealthy, activity is reported
  * as unknown (non-idle), so a broken observer can only keep the host alive,
- * never kill it mid-turn.
+ * never kill it mid-turn - for one idle window. Past that, unknown has held
+ * the host open for as long as idleness itself would have, and it stops
+ * counting as busy; the link keeps reconnecting the whole time (#1979).
  *
  * Lifetime binding: the host is spawned with an extra inherited pipe on fd 3
  * whose write end this supervisor holds and never writes to. The kernel closes
@@ -47,11 +49,16 @@ import { dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgentDir, isBunBinary, isBundledNode } from "../../config.js";
 import { processIsLive, readProcessStartTime } from "../app-server/daemon/process.js";
+import { classifyChildExit, noteChildExit } from "./host-child-exit.js";
+// The exit verdict moved to ./host-child-exit.ts with the crash recording it now feeds; it stays
+// exported from here so every existing importer keeps resolving it at its original home.
+export { classifyChildExit } from "./host-child-exit.js";
 import { createHostDaemonPaths, generationPaths, HOST_DAEMON_DIR_ENV } from "./host-daemon-paths.js";
 import { releaseGeneration } from "./host-daemon-registration.js";
 import { watchForSupersession } from "./host-supersession.js";
 import { HOST_CLEANUP_PATHS_ENV, HOST_PUBLIC_SOCKET_ENV, HOST_SCRATCH_DIR_ENV, HOST_WATCH_FD_ENV, HOST_WATCH_PPID_ENV, } from "./host-watchdog.js";
 import { attachJsonlLineReader, MAX_RPC_LINE_CHARACTERS } from "./jsonl.js";
+import { activeTurnsForIdleDecision, createObserverLink } from "./observer-link.js";
 import { HOST_INSTANCE_ID_ENV } from "./protocol-identity.js";
 import { MAX_SOCKET_PATH_BYTES, PUBLIC_SOCKET_IDENTITY_FILE, shieldSocketDuringClose, statSocketIdentity, unlinkOwnedSocket, writeSocketIdentityFile, } from "./socket-ownership.js";
 import { authenticateSocket, createSocketSecret, ensureSocketSecret, resolveSocketTransportAddress, SOCKET_SECRET_FILE_ENV, sendSocketHandshake, socketSecretPath, } from "./socket-transport.js";
@@ -61,6 +68,9 @@ export const HOST_COLD_START_ENV = "SENPI_RPC_HOST_COLD_START";
 export const HOST_IDLE_EXIT_MS_ENV = "SENPI_RPC_HOST_IDLE_EXIT_MS";
 /** Default idle-exit window: 15 minutes of continuous no-connection, no-turn idle. */
 export const DEFAULT_HOST_IDLE_EXIT_MS = 15 * 60_000;
+/** Soft handoff deadline: rescan and report, never interrupt turns or in-flight requests. */
+export const HANDOFF_GRACE_MS_ENV = "SENPI_RPC_HANDOFF_GRACE_MS";
+export const DEFAULT_HANDOFF_GRACE_MS = 10 * 60_000;
 const CHILD_STOP_TIMEOUT_MS = 5_000;
 /** Win32 named-pipe shutdown can leave supervisor handles live after close starts. */
 const WINDOWS_SUPERVISOR_SHUTDOWN_HARD_EXIT_MS = 2_000;
@@ -121,17 +131,6 @@ export function resolveHostPolicy(settings, env) {
         DEFAULT_HOST_IDLE_EXIT_MS;
     return { coldStart, idleExitMs };
 }
-/**
- * How the supervisor reads its child's exit. The RPC host exits 0 only through
- * its own clean shutdown path - including its idle/empty-host policy - so that
- * is an intentional stop, not a crash: the supervisor mirrors its own idle exit
- * instead of reporting failure. Any non-zero code or signal stays a crash.
- */
-export function classifyChildExit(code, signal) {
-    if (code === 0 && signal === null)
-        return { reason: "rpc host exited on its own idle policy", exitCode: 0 };
-    return { reason: `rpc host process exited unexpectedly (${code ?? signal})`, exitCode: 1 };
-}
 /**
  * Pure idle-window decision core. `update()` must be called with the CURRENT
  * activity state; the window only counts continuously idle time and any
@@ -365,12 +364,41 @@ export async function runHostSupervisor(launch) {
     const internalSecret = process.platform === "win32" ? await createSocketSecret(internalSecretPath) : undefined;
     const clientSockets = new Set();
     const busySessions = new Map();
-    let observerHealthy = false;
-    let observerReconnectTimer;
+    // Declared before anything that can reach `currentActivity()`. A client accepted during startup
+    // asks for the activity snapshot, and a `const` read before its initializer runs is a
+    // ReferenceError that fails the connection - which is how a successor's first `open_session`
+    // came back `success: false` during a handoff.
+    let observerSocket;
+    const observerLink = createObserverLink({
+        open: async () => {
+            const secret = internalSecret;
+            const next = createConnection(resolveSocketTransportAddress(internalSocket, process.platform, secret));
+            if (secret)
+                sendSocketHandshake(next, secret);
+            await waitForConnect(next, 5_000);
+            observerSocket = next;
+            attachJsonlLineReader(next, observeHostEvent, { maxLineLength: MAX_RPC_LINE_CHARACTERS });
+            return {
+                onLost: (handler) => {
+                    next.once("close", handler);
+                    next.once("error", handler);
+                },
+            };
+        },
+        settled: () => shuttingDown,
+        retryDelayMs: 250,
+        now: Date.now,
+        setTimer: (run, ms) => {
+            const timer = setTimeout(run, ms);
+            timer.unref?.();
+            return { cancel: () => clearTimeout(timer) };
+        },
+    });
     let childExitWatchTimer;
     let stopSupersessionWatch;
     let shuttingDown = false;
     let draining = false;
+    let handoffGraceTimer;
     let shutdownPromise;
     const childLaunch = spawnableChildLaunch(resolveHostChildLaunch(launch, internalSocket));
     const child = spawn(childLaunch.command, childLaunch.args, {
@@ -409,6 +437,7 @@ export async function runHostSupervisor(launch) {
         // CREATE_NO_WINDOW gives the child a console with no window instead.
         windowsHide: true,
     });
+    const childStartedAt = Date.now();
     // Nothing is ever written; the pipe exists purely so its EOF is a reliable
     // death notification. Errors on it must not crash the supervisor.
     child.stdio[CHILD_WATCH_FD]?.on("error", () => { });
@@ -416,6 +445,9 @@ export async function runHostSupervisor(launch) {
         if (shuttingDown)
             return;
         const { reason, exitCode } = classifyChildExit(code, signal);
+        // Record BEFORE shutting down: `shutdown` ends in `process.exit`, so anything queued after
+        // it is never reached. Writing is best-effort and never throws into this path.
+        noteChildExit(paths.dir, code, signal, childStartedAt);
         void shutdown(reason, exitCode);
     });
     const server = createServer((client) => {
@@ -444,7 +476,12 @@ export async function runHostSupervisor(launch) {
             internal.pipe(client);
             client.once("close", detach);
             client.once("error", detach);
-            internal.once("close", detach);
+            // Let the final lifecycle records drain through the public socket before closing it.
+            internal.once("end", () => client.end(() => client.destroy()));
+            internal.once("close", () => {
+                if (!internal.readableEnded)
+                    detach();
+            });
             internal.once("error", detach);
         };
         if (publicSecret)
@@ -459,13 +496,19 @@ export async function runHostSupervisor(launch) {
     const decider = new IdleExitDecider(policy.coldStart === "persistent" ? Number.POSITIVE_INFINITY : policy.idleExitMs);
     const tickIntervalMs = Math.max(20, Math.min(1_000, policy.idleExitMs / 4));
     const ticker = setInterval(() => {
-        if (decider.update(currentActivity()) === "exit")
+        if (!draining && decider.update(currentActivity()) === "exit")
             void shutdown("idle", 0);
     }, tickIntervalMs);
     function currentActivity() {
         return {
             connections: clientSockets.size,
-            activeTurns: observerHealthy ? countBusySessions() : 1,
+            activeTurns: activeTurnsForIdleDecision({
+                healthy: observerLink.healthy(),
+                unhealthySince: observerLink.unhealthySince(),
+                now: Date.now(),
+                unknownGraceMs: decider.idleExitMs,
+                observedBusy: countBusySessions(),
+            }),
         };
     }
     function countBusySessions() {
@@ -508,6 +551,8 @@ export async function runHostSupervisor(launch) {
             process.exit(exitCode);
         shuttingDown = true;
         clearInterval(ticker);
+        if (handoffGraceTimer)
+            clearTimeout(handoffGraceTimer);
         if (childExitWatchTimer)
             clearInterval(childExitWatchTimer);
         stopSupersessionWatch?.();
@@ -532,7 +577,8 @@ export async function runHostSupervisor(launch) {
             if (internal.dir)
                 await rm(internal.dir, { recursive: true, force: true });
             await stopChild(child);
-            observer?.destroy();
+            observerLink.stop();
+            observerSocket?.destroy();
             if (publicSocketOwned && process.platform !== "win32") {
                 // Ownership-checked: after a takeover, a newer host may have published
                 // a fresh entry at this path; only the entry THIS supervisor bound is
@@ -553,7 +599,6 @@ export async function runHostSupervisor(launch) {
             process.exit(exitCode);
         }
     }
-    let observer;
     let publicSocketOwned = false;
     let publicSocketIdentity;
     function supervisorLog(message) {
@@ -564,20 +609,29 @@ export async function runHostSupervisor(launch) {
     // startup must run the same cleanup instead of Node's default kill, which
     // would leave that directory behind.
     /**
-     * Hand this generation's work to the next one: stop accepting, keep every connection already
-     * proxied, and tell the host child to park its retained sessions as their turns settle. The
-     * child's exit is what ends this supervisor, so the drain never cuts a turn short.
+     * Ask the child to announce and park attached sessions as turns/requests settle. The supervisor
+     * owns the soft grace from this instant; expiry rescans but NEVER kills busy sessions. Child
+     * exit ends the supervisor regardless of clients that keep their connections open.
      */
     function drainForHandoff() {
         if (draining || shuttingDown)
             return;
         draining = true;
         supervisorLog("draining into the next generation");
+        const graceMs = parseIdleExitMs(process.env[HANDOFF_GRACE_MS_ENV]) ?? DEFAULT_HANDOFF_GRACE_MS;
+        handoffGraceTimer = setTimeout(() => {
+            supervisorLog(JSON.stringify({ event: "handoff_grace_expired", graceMs }));
+            requestChildDrain();
+        }, graceMs);
+        handoffGraceTimer.unref();
         // The listening handle is deliberately NOT closed: libuv unlinks a pipe's bound NAME when it
         // closes, and after a handoff that name is the successor's entry. Nothing can reach this
         // listener by path any more (the rename moved the name), and the accept guard above turns
         // away whatever raced it, so leaving the handle open until exit costs nothing and keeps the
         // public path continuously answerable - no window where a client finds no socket at all.
+        requestChildDrain();
+    }
+    function requestChildDrain() {
         if (child.pid !== undefined && child.exitCode === null && child.signalCode === null) {
             try {
                 process.kill(child.pid, "SIGUSR1");
@@ -590,7 +644,7 @@ export async function runHostSupervisor(launch) {
     registerSupervisorSignals(shutdown, drainForHandoff);
     try {
         await waitForListener(internalSocket, 30_000, internalSecret);
-        await connectObserver();
+        await observerLink.open();
         await prepareSocketPath(bindSocket);
         await listen(server, bindSocket, publicSecret);
         publicSocketOwned = true;
@@ -604,40 +658,18 @@ export async function runHostSupervisor(launch) {
             await writeSocketIdentityFile(join(internal.dir, PUBLIC_SOCKET_IDENTITY_FILE), publicSocketIdentity);
         }
         // Losing the public entry IS a drain request: nothing can reach this supervisor by path any
-        // more, and the handoff that replaced it may never have signalled (#1893).
-        stopSupersessionWatch = watchForSupersession({ path: publicSocket, identity: publicSocketIdentity, settled: () => shuttingDown || draining }, () => {
-            supervisorLog("another generation owns the public socket; draining this one");
+        // more, and the handoff that replaced it may never have signalled (#1893). A name that was
+        // deleted rather than taken over is the same loss with nobody serving the path (#1961).
+        stopSupersessionWatch = watchForSupersession({ path: publicSocket, identity: publicSocketIdentity, settled: () => shuttingDown || draining }, (loss) => {
+            supervisorLog(loss === "absent"
+                ? "the public socket entry is gone; nothing can reach this generation; draining"
+                : "another generation owns the public socket; draining this one");
             drainForHandoff();
         });
     }
     catch (cause) {
         await shutdown(`startup failed: ${errorMessage(cause)}`, 1);
     }
-    async function connectObserver() {
-        const secret = internalSecret;
-        const next = createConnection(resolveSocketTransportAddress(internalSocket, process.platform, secret));
-        if (secret)
-            sendSocketHandshake(next, secret);
-        await waitForConnect(next, 5_000);
-        observer = next;
-        observerHealthy = true;
-        attachJsonlLineReader(next, observeHostEvent, { maxLineLength: MAX_RPC_LINE_CHARACTERS });
-        const lost = () => {
-            if (observer !== next || shuttingDown)
-                return;
-            observerHealthy = false;
-            observer = undefined;
-            if (observerReconnectTimer === undefined) {
-                observerReconnectTimer = setTimeout(() => {
-                    observerReconnectTimer = undefined;
-                    void connectObserver().catch(() => lost());
-                }, 250);
-                observerReconnectTimer.unref?.();
-            }
-        };
-        next.once("close", lost);
-        next.once("error", lost);
-    }
     if (process.platform === "win32" && child.pid !== undefined) {
         // This baseline read sits outside the startup try/catch, and readProcessStartTime
         // THROWS when the 1s CIM probe fails (execFile's timeout SIGTERMs the PowerShell