fix(cron): isolate main-session cron wake lanes

galiniliev · galiniliev · commit 30deebee5293 · 2026-05-16T15:39:14.000-07:00
diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md
@@ -90,14 +90,14 @@ This fires ~5–6 times per month instead of 0–1 times per month. OpenClaw use
 
 | Style           | `--session` value   | Runs in                  | Best for                        |
 | --------------- | ------------------- | ------------------------ | ------------------------------- |
-| Main session    | `main`              | Next heartbeat turn      | Reminders, system events        |
+| Main session    | `main`              | Dedicated cron wake lane | Reminders, system events        |
 | Isolated        | `isolated`          | Dedicated `cron:<jobId>` | Reports, background chores      |
 | Current session | `current`           | Bound at creation time   | Context-aware recurring work    |
 | Custom session  | `session:custom-id` | Persistent named session | Workflows that build on history |
 
 <AccordionGroup>
   <Accordion title="Main session vs isolated vs custom">
-    **Main session** jobs enqueue a system event and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). Those system events do not extend daily/idle reset freshness for the target session. **Isolated** jobs run a dedicated agent turn with a fresh session. **Custom sessions** (`session:xxx`) persist context across runs, enabling workflows like daily standups that build on previous summaries.
+    **Main session** jobs enqueue a system event into a cron-owned run lane and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). They can use the target main session's last delivery context for replies, but they do not append routine cron turns to the human chat lane and do not extend daily/idle reset freshness for the target session. **Isolated** jobs run a dedicated agent turn with a fresh session. **Custom sessions** (`session:xxx`) persist context across runs, enabling workflows like daily standups that build on previous summaries.
   </Accordion>
   <Accordion title="What 'fresh session' means for isolated jobs">
     For isolated jobs, "fresh session" means a new transcript/session id for each run. OpenClaw may carry safe preferences such as thinking/fast/verbose settings, labels, and explicit user-selected model/auth overrides, but it does not inherit ambient conversation context from an older cron row: channel/group routing, send or queue policy, elevation, origin, or ACP runtime binding. Use `current` or `session:<id>` when a recurring job should deliberately build on the same conversation context.
diff --git a/src/cron/service.main-job-passes-heartbeat-target-last.test.ts b/src/cron/service.main-job-passes-heartbeat-target-last.test.ts
@@ -43,7 +43,7 @@ describe("cron main job passes heartbeat target=last", () => {
       runHeartbeatOnce: params.runHeartbeatOnce,
       runIsolatedAgentJob: vi.fn(async () => ({ status: "ok" as const })),
     });
-    return { cron, requestHeartbeat };
+    return { cron, enqueueSystemEvent, requestHeartbeat };
   }
 
   function requireRunHeartbeatOnceCall(
@@ -66,6 +66,7 @@ describe("cron main job passes heartbeat target=last", () => {
       source?: string;
       intent?: string;
       reason?: string;
+      sessionKey?: string;
       heartbeat?: unknown;
     };
   }
@@ -109,6 +110,8 @@ describe("cron main job passes heartbeat target=last", () => {
     // heartbeat runner delivers the response to the last active channel.
     const callArgs = requireRunHeartbeatOnceCall(runHeartbeatOnce);
     expect(callArgs.heartbeat.target).toBe("last");
+    expect(callArgs.sessionKey).toMatch(/^agent:main:cron:test-main-delivery:run:\d+$/);
+    expect(callArgs.sessionKey).not.toBe("agent:main:main");
   });
 
   it("should preserve heartbeat.target=last when wakeMode=now falls back to requestHeartbeat", async () => {
@@ -140,6 +143,10 @@ describe("cron main job passes heartbeat target=last", () => {
     expect(heartbeatRequest.source).toBe("cron");
     expect(heartbeatRequest.intent).toBe("immediate");
     expect(heartbeatRequest.reason).toBe("cron:test-main-delivery-busy");
+    expect(heartbeatRequest.sessionKey).toMatch(
+      /^agent:main:cron:test-main-delivery-busy:run:\d+$/,
+    );
+    expect(heartbeatRequest.sessionKey).not.toBe("agent:main:main");
     expect(heartbeatRequest.heartbeat).toEqual({ target: "last" });
   });
 
@@ -160,7 +167,7 @@ describe("cron main job passes heartbeat target=last", () => {
       durationMs: 50,
     }));
 
-    const { cron, requestHeartbeat } = createCronWithSpies({
+    const { cron, enqueueSystemEvent, requestHeartbeat } = createCronWithSpies({
       storePath,
       runHeartbeatOnce,
     });
@@ -172,7 +179,11 @@ describe("cron main job passes heartbeat target=last", () => {
     expect(heartbeatRequest.source).toBe("cron");
     expect(heartbeatRequest.intent).toBe("event");
     expect(heartbeatRequest.reason).toBe("cron:test-next-heartbeat");
+    expect(heartbeatRequest.sessionKey).toMatch(/^agent:main:cron:test-next-heartbeat:run:\d+$/);
+    expect(heartbeatRequest.sessionKey).not.toBe("agent:main:main");
     expect(heartbeatRequest.heartbeat).toEqual({ target: "last" });
     expect(runHeartbeatOnce).not.toHaveBeenCalled();
+    const enqueueOptions = enqueueSystemEvent.mock.calls[0]?.[1] as { sessionKey?: string };
+    expect(enqueueOptions.sessionKey).toBe(heartbeatRequest.sessionKey);
   });
 });
diff --git a/src/cron/service/state.ts b/src/cron/service/state.ts
@@ -1,5 +1,6 @@
 import type { CronConfig } from "../../config/types.cron.js";
 import type { HeartbeatRunResult, HeartbeatWakeRequest } from "../../infra/heartbeat-wake.js";
+import type { DeliveryContext } from "../../utils/delivery-context.types.js";
 import type {
   CronAgentExecutionPhaseUpdate,
   CronAgentExecutionStarted,
@@ -82,6 +83,7 @@ export type CronServiceDeps = {
       agentId?: string;
       sessionKey?: string;
       contextKey?: string;
+      deliveryContext?: DeliveryContext;
       forceSenderIsOwnerFalse?: boolean;
     },
   ) => void;
diff --git a/src/cron/service/timer.test.ts b/src/cron/service/timer.test.ts
@@ -1,8 +1,9 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { setupCronServiceSuite, writeCronStoreSnapshot } from "../../cron/service.test-harness.js";
 import { createCronServiceState } from "../../cron/service/state.js";
-import { onTimer } from "../../cron/service/timer.js";
+import { executeJobCore, onTimer } from "../../cron/service/timer.js";
 import { loadCronStore, saveCronStore } from "../../cron/store.js";
 import type { CronJob } from "../../cron/types.js";
 import * as detachedTaskRuntime from "../../tasks/detached-task-runtime.js";
@@ -33,6 +34,62 @@ afterEach(() => {
 });
 
 describe("cron service timer seam coverage", () => {
+  it("routes main cron jobs onto a cron run lane derived from the target agent", async () => {
+    const { storePath } = await makeStorePath();
+    const now = Date.parse("2026-03-23T12:00:00.000Z");
+    const enqueueSystemEvent = vi.fn();
+    const requestHeartbeat = vi.fn();
+    const runHeartbeatOnce = vi.fn(async () => ({ status: "ran" as const, durationMs: 1 }));
+    const job = {
+      ...createDueMainJob({ now, wakeMode: "now" }),
+      sessionKey: "agent:main-pr-router:main",
+      state: { runningAtMs: now },
+    };
+    const cronRunSessionKey = `agent:main-pr-router:cron:main-heartbeat-job:run:${now}`;
+    const sessionStorePath = path.join(path.dirname(path.dirname(storePath)), "sessions.json");
+    await fs.writeFile(
+      sessionStorePath,
+      JSON.stringify({
+        "agent:main-pr-router:main": {
+          lastChannel: "discord",
+          lastTo: "channel-1",
+          lastAccountId: "default",
+        },
+      }),
+      "utf8",
+    );
+
+    const state = createCronServiceState({
+      storePath,
+      cronEnabled: true,
+      log: logger,
+      nowMs: () => now,
+      resolveSessionStorePath: () => sessionStorePath,
+      enqueueSystemEvent,
+      requestHeartbeat,
+      runHeartbeatOnce,
+      runIsolatedAgentJob: vi.fn(async () => ({ status: "ok" as const })),
+    });
+
+    const result = await executeJobCore(state, job);
+
+    expect(result).toMatchObject({ status: "ok", sessionKey: cronRunSessionKey });
+    expect(enqueueSystemEvent).toHaveBeenCalledWith("heartbeat seam tick", {
+      agentId: undefined,
+      sessionKey: cronRunSessionKey,
+      contextKey: "cron:main-heartbeat-job",
+      deliveryContext: { channel: "discord", to: "channel-1", accountId: "default" },
+    });
+    expect(runHeartbeatOnce).toHaveBeenCalledWith({
+      source: "cron",
+      intent: "immediate",
+      reason: "cron:main-heartbeat-job",
+      agentId: undefined,
+      sessionKey: cronRunSessionKey,
+      heartbeat: { target: "last" },
+    });
+  });
+
   it("persists the next schedule and hands off next-heartbeat main jobs", async () => {
     const { storePath } = await makeStorePath();
     const now = Date.parse("2026-03-23T12:00:00.000Z");
@@ -57,17 +114,18 @@ describe("cron service timer seam coverage", () => {
 
     await onTimer(state);
 
+    const cronRunSessionKey = `agent:main:cron:main-heartbeat-job:run:${now}`;
     expect(enqueueSystemEvent).toHaveBeenCalledWith("heartbeat seam tick", {
       agentId: undefined,
-      sessionKey: "agent:main:main",
+      sessionKey: cronRunSessionKey,
       contextKey: "cron:main-heartbeat-job",
     });
     expect(requestHeartbeat).toHaveBeenCalledWith({
       source: "cron",
       intent: "event",
       reason: "cron:main-heartbeat-job",
       agentId: undefined,
-      sessionKey: "agent:main:main",
+      sessionKey: cronRunSessionKey,
       heartbeat: { target: "last" },
     });
 
@@ -87,7 +145,7 @@ describe("cron service timer seam coverage", () => {
     expect(task.sourceId).toBe("main-heartbeat-job");
     expect(task.ownerKey).toBe("");
     expect(task.scopeKind).toBe("system");
-    expect(task.childSessionKey).toBe("agent:main:main");
+    expect(task.childSessionKey).toBe(cronRunSessionKey);
     expect(task.runId).toBe(`cron:main-heartbeat-job:${now}`);
     expect(task.label).toBe("main heartbeat job");
     expect(task.task).toBe("main heartbeat job");
@@ -142,9 +200,10 @@ describe("cron service timer seam coverage", () => {
       { jobId: "main-heartbeat-job", error: ledgerError },
       "cron: failed to create task ledger record",
     );
+    const cronRunSessionKey = `agent:main:cron:main-heartbeat-job:run:${now}`;
     expect(enqueueSystemEvent).toHaveBeenCalledWith("heartbeat seam tick", {
       agentId: undefined,
-      sessionKey: "agent:main:main",
+      sessionKey: cronRunSessionKey,
       contextKey: "cron:main-heartbeat-job",
     });
 
diff --git a/src/cron/service/timer.ts b/src/cron/service/timer.ts
@@ -6,13 +6,21 @@ import {
   HEARTBEAT_SKIP_CRON_IN_PROGRESS,
   isRetryableHeartbeatBusySkipReason,
 } from "../../infra/heartbeat-wake.js";
-import { DEFAULT_AGENT_ID, isSubagentSessionKey } from "../../routing/session-key.js";
+import { loadSessionStore } from "../../config/sessions/store-load.js";
+import {
+  DEFAULT_AGENT_ID,
+  isSubagentSessionKey,
+  normalizeAgentId,
+  resolveAgentIdFromSessionKey,
+} from "../../routing/session-key.js";
 import { normalizeOptionalLowercaseString } from "../../shared/string-coerce.js";
 import {
   completeTaskRunByRunId,
   createRunningTaskRun,
   failTaskRunByRunId,
 } from "../../tasks/detached-task-runtime.js";
+import { deliveryContextFromSession } from "../../utils/delivery-context.shared.js";
+import type { DeliveryContext } from "../../utils/delivery-context.types.js";
 import { clearCronJobActive, markCronJobActive } from "../active-jobs.js";
 import { resolveCronDeliveryPlan, resolveFailureDestination } from "../delivery-plan.js";
 import {
@@ -414,19 +422,64 @@ export function normalizeCronRunErrorText(err: unknown): string {
   return String(err);
 }
 
+function normalizeCronLaneSegment(value: string | undefined, fallback: string): string {
+  const normalized = normalizeOptionalLowercaseString(value)
+    ?.replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+  return normalized || fallback;
+}
+
+function resolveMainSessionCronRunSessionKey(job: CronJob, startedAt: number): string {
+  const explicitAgentId = job.agentId?.trim();
+  const agentId = normalizeAgentId(
+    explicitAgentId || resolveAgentIdFromSessionKey(job.sessionKey),
+  );
+  const jobSegment = normalizeCronLaneSegment(job.id, "job");
+  const runSegment = normalizeCronLaneSegment(String(Math.max(0, Math.floor(startedAt))), "run");
+  return `agent:${agentId}:cron:${jobSegment}:run:${runSegment}`;
+}
+
+function resolveMainSessionCronDeliveryContext(
+  state: CronServiceState,
+  job: CronJob,
+): DeliveryContext | undefined {
+  const targetSessionKey = job.sessionKey?.trim();
+  if (!targetSessionKey) {
+    return undefined;
+  }
+  const explicitAgentId = job.agentId?.trim();
+  const agentId = normalizeAgentId(
+    explicitAgentId || resolveAgentIdFromSessionKey(targetSessionKey),
+  );
+  const storePath = state.deps.resolveSessionStorePath?.(agentId) ?? state.deps.sessionStorePath;
+  if (!storePath) {
+    return undefined;
+  }
+  try {
+    return deliveryContextFromSession(loadSessionStore(storePath)[targetSessionKey]);
+  } catch {
+    return undefined;
+  }
+}
+
 function tryCreateCronTaskRun(params: {
   state: CronServiceState;
   job: CronJob;
   startedAt: number;
 }): string | undefined {
   const runId = createCronExecutionId(params.job.id, params.startedAt);
+  const childSessionKey =
+    params.job.sessionTarget === "main"
+      ? resolveMainSessionCronRunSessionKey(params.job, params.startedAt)
+      : params.job.sessionKey;
   try {
     createRunningTaskRun({
       runtime: "cron",
       sourceId: params.job.id,
       ownerKey: "",
       scopeKind: "system",
-      childSessionKey: params.job.sessionKey,
+      childSessionKey,
       agentId: params.job.agentId,
       runId,
       label: params.job.name,
@@ -1683,11 +1736,15 @@ async function executeMainSessionCronJob(
           : 'main job requires payload.kind="systemEvent"',
     };
   }
-  const targetMainSessionKey = job.sessionKey;
+  const cronStartedAt =
+    typeof job.state.runningAtMs === "number" ? job.state.runningAtMs : state.deps.nowMs();
+  const cronRunSessionKey = resolveMainSessionCronRunSessionKey(job, cronStartedAt);
+  const deliveryContext = resolveMainSessionCronDeliveryContext(state, job);
   state.deps.enqueueSystemEvent(text, {
     agentId: job.agentId,
-    sessionKey: targetMainSessionKey,
+    sessionKey: cronRunSessionKey,
     contextKey: `cron:${job.id}`,
+    ...(deliveryContext ? { deliveryContext } : {}),
   });
   if (job.wakeMode === "now" && state.deps.runHeartbeatOnce) {
     const reason = `cron:${job.id}`;
@@ -1705,7 +1762,7 @@ async function executeMainSessionCronJob(
         intent: "immediate",
         reason,
         agentId: job.agentId,
-        sessionKey: targetMainSessionKey,
+        sessionKey: cronRunSessionKey,
         heartbeat: { target: "last" },
       });
       if (
@@ -1721,10 +1778,10 @@ async function executeMainSessionCronJob(
           intent: "immediate",
           reason,
           agentId: job.agentId,
-          sessionKey: targetMainSessionKey,
+          sessionKey: cronRunSessionKey,
           heartbeat: { target: "last" },
         });
-        return { status: "ok", summary: text };
+        return { status: "ok", summary: text, sessionKey: cronRunSessionKey };
       }
       if (abortSignal?.aborted) {
         return { status: "error", error: timeoutErrorMessage() };
@@ -1738,21 +1795,31 @@ async function executeMainSessionCronJob(
           intent: "immediate",
           reason,
           agentId: job.agentId,
-          sessionKey: targetMainSessionKey,
+          sessionKey: cronRunSessionKey,
           heartbeat: { target: "last" },
         });
-        return { status: "ok", summary: text };
+        return { status: "ok", summary: text, sessionKey: cronRunSessionKey };
       }
       await waitWithAbort(retryDelayMs);
     }
 
     if (heartbeatResult.status === "ran") {
-      return { status: "ok", summary: text };
+      return { status: "ok", summary: text, sessionKey: cronRunSessionKey };
     }
     if (heartbeatResult.status === "skipped") {
-      return { status: "skipped", error: heartbeatResult.reason, summary: text };
+      return {
+        status: "skipped",
+        error: heartbeatResult.reason,
+        summary: text,
+        sessionKey: cronRunSessionKey,
+      };
     }
-    return { status: "error", error: heartbeatResult.reason, summary: text };
+    return {
+      status: "error",
+      error: heartbeatResult.reason,
+      summary: text,
+      sessionKey: cronRunSessionKey,
+    };
   }
 
   if (abortSignal?.aborted) {
@@ -1763,10 +1830,10 @@ async function executeMainSessionCronJob(
     intent: job.wakeMode === "now" ? "immediate" : "event",
     reason: `cron:${job.id}`,
     agentId: job.agentId,
-    sessionKey: targetMainSessionKey,
+    sessionKey: cronRunSessionKey,
     heartbeat: { target: "last" },
   });
-  return { status: "ok", summary: text };
+  return { status: "ok", summary: text, sessionKey: cronRunSessionKey };
 }
 
 async function executeDetachedCronJob(
diff --git a/src/gateway/server-cron.ts b/src/gateway/server-cron.ts
@@ -301,6 +301,7 @@ export function buildGatewayCronService(params: {
       enqueueSystemEvent(text, {
         sessionKey,
         contextKey: opts?.contextKey,
+        deliveryContext: opts?.deliveryContext,
         forceSenderIsOwnerFalse: opts?.forceSenderIsOwnerFalse,
         trusted: opts?.forceSenderIsOwnerFalse !== true,
       });
