feat(wake): expose typed sessionKey on wake protocol + system event CLI

Adds an optional sessionKey to the WakeParamsSchema and threads it through
the gateway wake handler, CronService.wake(), and the underlying timer.wake()
ops so callers can target a specific session for async-task completion
relays instead of always hitting the agent's main session.

Also adds --session-key to `openclaw system event`.

The schema rejects empty/non-string sessionKey at the gateway boundary;
mismatched session keys (a key that does not belong to the resolving agent)
fall back to the agent's main session inside resolveCronSessionKey, which
is the existing safety path.

Refs #52305 (companion to PR #50818, which closes the related cron-run
remap slice at internal enqueue sites). Doesn't depend on #50818.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/cli/system-cli.test.ts

@@ -67,6 +67,38 @@ describe("system-cli", () => {
     expect(runtimeErrors[0]).toContain("--mode must be now or next-heartbeat");
   });
 
+  it("forwards --session-key on system event", async () => {
+    await runCli([
+      "system",
+      "event",
+      "--text",
+      "ping",
+      "--session-key",
+      "agent:main:telegram:dm:42",
+    ]);
+
+    expect(callGatewayFromCli).toHaveBeenCalledWith(
+      "wake",
+      expect.any(Object),
+      { mode: "next-heartbeat", text: "ping", sessionKey: "agent:main:telegram:dm:42" },
+      { expectFinal: false },
+    );
+  });
+
+  it("omits sessionKey from payload when --session-key not provided", async () => {
+    await runCli(["system", "event", "--text", "ping"]);
+
+    const [, , params] = callGatewayFromCli.mock.calls[0]!;
+    expect(params).not.toHaveProperty("sessionKey");
+  });
+
+  it("treats empty --session-key as omitted", async () => {
+    await runCli(["system", "event", "--text", "ping", "--session-key", "  "]);
+
+    const [, , params] = callGatewayFromCli.mock.calls[0]!;
+    expect(params).not.toHaveProperty("sessionKey");
+  });
+
   it.each([
     { args: ["system", "heartbeat", "last"], method: "last-heartbeat", params: undefined },
     {

src/cli/system-cli.ts

@@ -8,7 +8,12 @@ import { formatCliCommand } from "./command-format.js";
 import type { GatewayRpcOpts } from "./gateway-rpc.js";
 import { addGatewayClientOptions, callGatewayFromCli } from "./gateway-rpc.js";
 
-type SystemEventOpts = GatewayRpcOpts & { text?: string; mode?: string; json?: boolean };
+type SystemEventOpts = GatewayRpcOpts & {
+  text?: string;
+  mode?: string;
+  sessionKey?: string;
+  json?: boolean;
+};
 type SystemGatewayOpts = GatewayRpcOpts & { json?: boolean };
 
 const normalizeWakeMode = (raw: unknown) => {
@@ -56,6 +61,10 @@ export function registerSystemCli(program: Command) {
       .description("Enqueue a system event and optionally trigger a heartbeat")
       .requiredOption("--text <text>", "System event text")
       .option("--mode <mode>", "Wake mode (now|next-heartbeat)", "next-heartbeat")
+      .option(
+        "--session-key <sessionKey>",
+        "Target a specific session for the event (defaults to the agent's main session)",
+      )
       .option("--json", "Output JSON", false),
   ).action(async (opts: SystemEventOpts) => {
     await runSystemGatewayCommand(
@@ -68,7 +77,13 @@ export function registerSystemCli(program: Command) {
           );
         }
         const mode = normalizeWakeMode(opts.mode);
-        return await callGatewayFromCli("wake", opts, { mode, text }, { expectFinal: false });
+        const sessionKey = normalizeOptionalString(opts.sessionKey);
+        return await callGatewayFromCli(
+          "wake",
+          opts,
+          sessionKey ? { mode, text, sessionKey } : { mode, text },
+          { expectFinal: false },
+        );
       },
       "ok",
     );