feat(service): join whole-service stop to a child drain over launcher IPC

A Windows SCM stop cannot deliver a graceful signal, so the launcher now asks its managed child to drain over the existing IPC channel and waits, bounded, for a stopped acknowledgement before its forced fallback. The child drives the same Effect-runtime interruption path as SIGTERM via process.emit, and acknowledges from a scope finalizer. POSIX keeps its signal-driven finalizer path. Author scope: ENV-1:R10-T3-LIFECYCLE Stage B.

Author: env1-agent

apps/server/src/cloud/serviceLauncherClient.ts

@@ -251,3 +251,37 @@ export const make = Effect.fn("cloud.service_launcher_client.make")(function* (o
 });
 
 export const layer = Layer.effect(ServiceLauncherClient, make());
+
+/**
+ * Installs the managed graceful-stop handler. When the launcher owns this
+ * process it asks for a stop over the existing child IPC channel; this drives
+ * the same Effect-runtime interruption path the runtime already installs for
+ * `SIGTERM`, then acknowledges the drain from a scope finalizer so the launcher
+ * can distinguish a completed shutdown from a forced one. A server that is not
+ * launcher-managed (or that receives no stop request) is unaffected.
+ *
+ * `process.emit("SIGTERM")` is used rather than `process.kill` so the same
+ * finalizer path runs on Windows, where a process signal is a hard kill.
+ */
+export const managedShutdownLayer = Layer.effectDiscard(
+  Effect.gen(function* () {
+    const { host, managed } = yield* resolveStartup();
+    if (!managed) return;
+    const onMessage = (...args: ReadonlyArray<unknown>) => {
+      const message = decodeServiceLauncherParentMessage(args[0]);
+      if (message?.type === "stop") process.emit("SIGTERM");
+    };
+    host.on("message", onMessage);
+    yield* Effect.addFinalizer(() =>
+      Effect.sync(() => {
+        host.off("message", onMessage);
+        try {
+          host.send({ type: "stopped" });
+        } catch {
+          // The channel may already be closed; the launcher then falls back to
+          // its bounded force-termination instead of trusting this ack.
+        }
+      }),
+    );
+  }),
+);

apps/server/src/cloud/serviceProtocol.ts

@@ -47,6 +47,12 @@ export type ServiceLauncherChildMessage =
   | {
       readonly type: "prepared";
       readonly updateId: string;
+    }
+  /** Sent once the managed child has drained its lifetime and is about to exit
+      in response to {@link ServiceLauncherParentMessage} `stop`. It is the
+      acknowledgement that a graceful stop completed, not a request to stop. */
+  | {
+      readonly type: "stopped";
     };
 
 export type ServiceLauncherParentMessage =
@@ -61,6 +67,12 @@ export type ServiceLauncherParentMessage =
   | {
       readonly type: "committed";
       readonly updateId: string;
+    }
+  /** Asks the managed child to run its own graceful shutdown and finalizers.
+      Used on platforms where a process signal is a hard kill (Windows), so the
+      launcher can join a real drain instead of terminating the child. */
+  | {
+      readonly type: "stop";
     };
 
 const SEMVER_NUMBER = "(?:0|[1-9]\\d*)";
@@ -249,7 +261,9 @@ export function decodeServiceLauncherChildMessage(
   }
   return value.type === "prepared" && typeof value.updateId === "string"
     ? { type: value.type, updateId: value.updateId }
-    : undefined;
+    : value.type === "stopped"
+      ? { type: value.type }
+      : undefined;
 }
 
 export function decodeServiceLauncherParentMessage(
@@ -264,5 +278,7 @@ export function decodeServiceLauncherParentMessage(
   }
   return value.type === "committed" && typeof value.updateId === "string"
     ? { type: value.type, updateId: value.updateId }
-    : undefined;
+    : value.type === "stop"
+      ? { type: value.type }
+      : undefined;
 }

apps/server/src/server.ts

@@ -797,6 +797,8 @@ const makeServerLayer = Layer.unwrap(
       runtimeStateLayer.pipe(Layer.provide(launcherLayer)),
       tailscaleServeLayer,
       cloudDesiredLinkReconcileLayer,
+      // Additive: lets a launcher-owned process drain on an IPC stop request.
+      ServiceLauncherClient.managedShutdownLayer,
     );
 
     return serverApplicationLayer.pipe(

apps/server/src/serviceLauncher.test.ts

@@ -1,10 +1,17 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
+import * as NodeChildProcess from "node:child_process";
 
-import { Launcher, readServiceState, writeServiceState } from "./serviceLauncher.ts";
+import {
+  Launcher,
+  readServiceState,
+  requestGracefulChildStop,
+  writeServiceState,
+} from "./serviceLauncher.ts";
 import {
   compareExactServiceVersions,
   decodeServiceState,
@@ -360,3 +367,57 @@ if (context.update?.status === "pending") {
     }),
   );
 });
+
+it.layer(NodeServices.layer)("whole-service graceful stop over IPC", (it) => {
+  it.effect("drains the managed child over IPC before force-termination", () =>
+    Effect.gen(function* () {
+      // POSIX keeps its signal-driven finalizer path; the IPC drain is the
+      // Windows path where a signal would be a hard kill. The production helper
+      // is exercised against a real Node child at the real IPC boundary.
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-service-launcher-graceful-" });
+      const drainMarker = path.join(root, "drained.txt");
+      // @effect-diagnostics-next-line preferSchemaOverJson:off - embeds a path in the child source.
+      const encodedDrainMarker = JSON.stringify(drainMarker);
+      const childSource =
+        `const { writeFileSync } = require("node:fs");\n` +
+        `process.on("message", (message) => {\n` +
+        `  if (message && message.type === "stop") {\n` +
+        `    setTimeout(() => {\n` +
+        `      writeFileSync(${encodedDrainMarker}, "drained");\n` +
+        `      process.send({ type: "stopped" });\n` +
+        `      process.exit(0);\n` +
+        `    }, 25);\n` +
+        `  }\n` +
+        `});\n` +
+        `setInterval(() => {}, 1_000);\n`;
+      const child = NodeChildProcess.spawn(process.execPath, ["-e", childSource], {
+        stdio: ["ignore", "ignore", "inherit", "ipc"],
+      });
+      yield* Effect.promise(() => new Promise<void>((r) => child.once("spawn", () => r())));
+      yield* Effect.promise(() => requestGracefulChildStop(child));
+      yield* Effect.promise(() => new Promise<void>((r) => child.once("exit", () => r())));
+
+      // The child ran its own drain before the helper resolved.
+      assert.isTrue(yield* fs.exists(drainMarker));
+    }),
+  );
+
+  it.effect("does not wait for a child without a live IPC channel", () =>
+    Effect.gen(function* () {
+      const child = NodeChildProcess.spawn(
+        process.execPath,
+        ["-e", "setInterval(() => {}, 1_000);"],
+        {
+          stdio: ["ignore", "ignore", "inherit"],
+        },
+      );
+      yield* Effect.promise(() => new Promise<void>((r) => child.once("spawn", () => r())));
+      // No `ipc` stdio: the helper must return without driving a drain and the
+      // caller falls back to its bounded force-termination.
+      yield* Effect.promise(() => requestGracefulChildStop(child));
+      child.kill();
+    }),
+  );
+});

apps/server/src/serviceLauncher.ts

@@ -33,6 +33,9 @@ import {
 const HANDOFF_DELAY_MS = 2_000;
 const PREPARED_TIMEOUT_MS = 120_000;
 const TERMINATE_GRACE_MS = 5_000;
+/** Bound on how long a Windows whole-service stop waits for the managed child
+    to drain and acknowledge before it force-terminates the process. */
+const STOP_ACK_TIMEOUT_MS = 10_000;
 
 type TerminalStatus = "committed" | "rolled-back" | "failed";
 type ChildRole = "active" | "trial";
@@ -258,6 +261,40 @@ function waitForExit(child: NodeChildProcess.ChildProcess): Promise<void> {
   return new Promise((resolve) => child.once("exit", () => resolve()));
 }
 
+/**
+ * Asks the managed child to run its own graceful shutdown over the existing
+ * IPC channel and waits, bounded, for the `stopped` acknowledgement or the
+ * child's own exit. Returns without forcing; the caller still terminates to
+ * guarantee the process is gone. Only meaningful where a signal is a hard kill
+ * (Windows), so POSIX keeps its existing signal-driven drain.
+ */
+export function requestGracefulChildStop(child: NodeChildProcess.ChildProcess): Promise<void> {
+  if (!child.connected || child.send === undefined) return Promise.resolve();
+  return new Promise<void>((resolve) => {
+    let settled = false;
+    let timer: NodeJS.Timeout;
+    function finish() {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.off("message", onMessage);
+      child.off("exit", onExit);
+      resolve();
+    }
+    function onMessage(value: unknown) {
+      const reply = decodeServiceLauncherChildMessage(value);
+      if (reply?.type === "stopped") finish();
+    }
+    function onExit() {
+      finish();
+    }
+    timer = setTimeout(finish, STOP_ACK_TIMEOUT_MS);
+    child.on("message", onMessage);
+    child.on("exit", onExit);
+    sendMessage(child, { type: "stop" }).catch(() => finish());
+  });
+}
+
 async function terminateChild(
   child: NodeChildProcess.ChildProcess,
   signal: NodeJS.Signals = "SIGTERM",
@@ -353,7 +390,14 @@ export class Launcher {
       this.#stopping = true;
       const child = this.#child?.process;
       this.#child = null;
-      if (child !== undefined) await terminateChild(child, signal);
+      if (child !== undefined) {
+        // Windows cannot deliver a graceful signal: request the child's own
+        // lifetime drain over IPC first, then guarantee the process is gone.
+        // POSIX keeps its existing signal-driven finalizer path.
+        // oxlint-disable-next-line t3code/no-global-process-runtime -- Standalone launcher has no Effect runtime.
+        if (process.platform === "win32") await requestGracefulChildStop(child);
+        await terminateChild(child, signal);
+      }
       this.#done = true;
       this.#completion.resolve();
     });
@@ -472,6 +516,11 @@ export class Launcher {
       await this.#handleUpdateRequest(child, message);
       return;
     }
+    if (message.type === "stopped") {
+      // Owned by the dedicated whole-service stop listener in
+      // requestGracefulChildStop; a replacement handoff ignores it.
+      return;
+    }
     await this.#handlePrepared(child, message.updateId);
   }