fix(gateway): expose restart drain controls

src/cli/daemon-cli/lifecycle-core.test.ts

@@ -326,6 +326,27 @@ describe("runServiceRestart token drift", () => {
     expect(service.restart).toHaveBeenCalledTimes(1);
   });
 
+  it("writes restart force and wait options into the service-manager intent", async () => {
+    service.readRuntime.mockResolvedValue({ status: "running", pid: 1234 });
+
+    await runServiceRestart({
+      ...createServiceRunArgs(),
+      opts: {
+        json: true,
+        restartIntent: {
+          waitMs: 2_500,
+        },
+      },
+    });
+
+    expect(writeGatewayRestartIntentSync).toHaveBeenCalledWith({
+      targetPid: 1234,
+      intent: {
+        waitMs: 2_500,
+      },
+    });
+  });
+
   it("clears restart intent when service-manager restart fails before signaling", async () => {
     service.readRuntime.mockResolvedValue({ status: "running", pid: 1234 });
     writeGatewayRestartIntentSync.mockReturnValueOnce(true);

src/cli/daemon-cli/lifecycle-core.ts

@@ -13,6 +13,7 @@ import { isSystemdUserServiceAvailable } from "../../daemon/systemd.js";
 import { isGatewaySecretRefUnavailableError } from "../../gateway/credentials.js";
 import {
   clearGatewayRestartIntentSync,
+  type GatewayRestartIntent,
   writeGatewayRestartIntentSync,
 } from "../../infra/restart.js";
 import { isWSL } from "../../infra/wsl.js";
@@ -28,6 +29,9 @@ import { filterContainerGenericHints } from "./shared.js";
 
 type DaemonLifecycleOptions = {
   json?: boolean;
+  force?: boolean;
+  wait?: string;
+  restartIntent?: GatewayRestartIntent;
 };
 
 type RestartPostCheckContext = {
@@ -440,6 +444,7 @@ export async function runServiceRestart(params: {
   const json = Boolean(params.opts?.json);
   const { stdout, emit, fail } = createDaemonActionContext({ action: "restart", json });
   const warnings: string[] = [];
+  const restartIntent = params.opts?.restartIntent;
   let handledRecovery: ServiceRecoveryResult | null = null;
   let recoveredLoadedState: boolean | null = null;
   const emitScheduledRestart = (
@@ -552,6 +557,7 @@ export async function runServiceRestart(params: {
         const runtime = await params.service.readRuntime(process.env).catch(() => null);
         wroteRestartIntent = writeGatewayRestartIntentSync({
           targetPid: runtime?.pid,
+          ...(restartIntent ? { intent: restartIntent } : {}),
         });
       }
       try {

src/cli/daemon-cli/lifecycle.ts

@@ -7,10 +7,12 @@ import {
   formatGatewayPidList,
   signalVerifiedGatewayPidSync,
 } from "../../infra/gateway-processes.js";
+import { type GatewayRestartIntent, writeGatewayRestartIntentSync } from "../../infra/restart.js";
 import { defaultRuntime } from "../../runtime.js";
 import { normalizeOptionalString } from "../../shared/string-coerce.js";
 import { theme } from "../../terminal/theme.js";
 import { formatCliCommand } from "../command-format.js";
+import { parseDurationMs } from "../parse-duration.js";
 import { recoverInstalledLaunchAgent } from "./launchd-recovery.js";
 import {
   runServiceRestart,
@@ -122,7 +124,25 @@ async function stopGatewayWithoutServiceManager(port: number) {
   };
 }
 
-async function restartGatewayWithoutServiceManager(port: number) {
+function resolveGatewayRestartIntentOptions(
+  opts: DaemonLifecycleOptions,
+): GatewayRestartIntent | undefined {
+  if (opts.force && opts.wait !== undefined) {
+    throw new Error("--force cannot be combined with --wait");
+  }
+  if (opts.force) {
+    return { force: true };
+  }
+  if (opts.wait !== undefined) {
+    return { waitMs: parseDurationMs(String(opts.wait)) };
+  }
+  return undefined;
+}
+
+async function restartGatewayWithoutServiceManager(
+  port: number,
+  restartIntent?: GatewayRestartIntent,
+) {
   await assertUnmanagedGatewayRestartEnabled(port);
   const pids = resolveVerifiedGatewayListenerPids(port);
   if (pids.length === 0) {
@@ -133,6 +153,10 @@ async function restartGatewayWithoutServiceManager(port: number) {
       `multiple gateway processes are listening on port ${port}: ${formatGatewayPidList(pids)}; use "openclaw gateway status --deep" before retrying restart`,
     );
   }
+  writeGatewayRestartIntentSync({
+    targetPid: pids[0],
+    ...(restartIntent ? { intent: restartIntent } : {}),
+  });
   signalVerifiedGatewayPidSync(pids[0], "SIGUSR1");
   return {
     result: "restarted" as const,
@@ -197,6 +221,7 @@ export async function runDaemonRestart(opts: DaemonLifecycleOptions = {}): Promi
   const json = Boolean(opts.json);
   const service = resolveGatewayService();
   let restartedWithoutServiceManager = false;
+  const restartIntent = resolveGatewayRestartIntentOptions(opts);
   const restartPort = await resolveGatewayLifecyclePort(service).catch(() =>
     resolveGatewayPortFallback(),
   );
@@ -208,7 +233,10 @@ export async function runDaemonRestart(opts: DaemonLifecycleOptions = {}): Promi
     serviceNoun: "Gateway",
     service,
     renderStartHints: renderGatewayServiceStartHints,
-    opts,
+    opts: {
+      ...opts,
+      ...(restartIntent ? { restartIntent } : {}),
+    },
     checkTokenDrift: true,
     onNotLoaded: async () => {
       if (process.platform === "darwin") {
@@ -217,7 +245,7 @@ export async function runDaemonRestart(opts: DaemonLifecycleOptions = {}): Promi
           return recovered;
         }
       }
-      const handled = await restartGatewayWithoutServiceManager(restartPort);
+      const handled = await restartGatewayWithoutServiceManager(restartPort, restartIntent);
       if (handled) {
         restartedWithoutServiceManager = true;
         return handled;

src/cli/daemon-cli/register-service-commands.test.ts

@@ -59,6 +59,28 @@ describe("addGatewayServiceCommands", () => {
         );
       },
     },
+    {
+      name: "forwards restart force and wait controls",
+      argv: ["restart", "--wait", "30s"],
+      assert: () => {
+        expect(runDaemonRestart).toHaveBeenCalledWith(
+          expect.objectContaining({
+            wait: "30s",
+          }),
+        );
+      },
+    },
+    {
+      name: "forwards restart force control",
+      argv: ["restart", "--force"],
+      assert: () => {
+        expect(runDaemonRestart).toHaveBeenCalledWith(
+          expect.objectContaining({
+            force: true,
+          }),
+        );
+      },
+    },
     {
       name: "forwards status auth collisions from parent gateway command",
       argv: ["status", "--token", "tok_status", "--password", "pw_status"],

src/cli/daemon-cli/register-service-commands.ts

@@ -1,7 +1,7 @@
 import type { Command } from "commander";
 import { createLazyImportLoader } from "../../shared/lazy-promise.js";
 import { inheritOptionFromParent } from "../command-options.js";
-import type { DaemonInstallOptions, GatewayRpcOpts } from "./types.js";
+import type { DaemonInstallOptions, DaemonLifecycleOptions, GatewayRpcOpts } from "./types.js";
 
 const daemonInstallModuleLoader = createLazyImportLoader(() => import("./install.runtime.js"));
 const daemonLifecycleModuleLoader = createLazyImportLoader(() => import("./lifecycle.runtime.js"));
@@ -44,6 +44,14 @@ function resolveRpcOptions(cmdOpts: GatewayRpcOpts, command?: Command): GatewayR
   };
 }
 
+function resolveRestartOptions(cmdOpts: DaemonLifecycleOptions, command?: Command) {
+  const parentForce = inheritOptionFromParent<boolean>(command, "force");
+  return {
+    ...cmdOpts,
+    force: Boolean(cmdOpts.force || parentForce),
+  };
+}
+
 export function addGatewayServiceCommands(parent: Command, opts?: { statusDescription?: string }) {
   parent
     .command("status")
@@ -113,9 +121,14 @@ export function addGatewayServiceCommands(parent: Command, opts?: { statusDescri
   parent
     .command("restart")
     .description("Restart the Gateway service (launchd/systemd/schtasks)")
+    .option("--force", "Restart immediately without waiting for active gateway work", false)
+    .option(
+      "--wait <duration>",
+      "Wait duration before forcing restart (ms, 10s, 5m; 0 waits indefinitely)",
+    )
     .option("--json", "Output JSON", false)
-    .action(async (cmdOpts) => {
+    .action(async (cmdOpts, command) => {
       const { runDaemonRestart } = await loadDaemonLifecycleModule();
-      await runDaemonRestart(cmdOpts);
+      await runDaemonRestart(resolveRestartOptions(cmdOpts, command));
     });
 }

src/cli/daemon-cli/types.ts

@@ -26,4 +26,6 @@ export type DaemonInstallOptions = {
 
 export type DaemonLifecycleOptions = {
   json?: boolean;
+  force?: boolean;
+  wait?: string;
 };