Summary

openclaw cron add --session-key <key> (and cron edit --session-key) is accepted by the CLI and reflected back in cron list, but the gateway ignores it when the job runs. Every cron run is keyed under agent:<agentId>:cron:<jobId> regardless, and each run also creates a persistent :run:<sessionId> receipt entry that the in-process cron.sessionRetention reaper does not clean up.

Net effect: there is no way to make multiple cron runs share a session via CLI flags, and the session store grows unbounded without an externally configured session.maintenance policy.

Version

OpenClaw 2026.4.5 (commit 3e72c03), Linuxbrew install on Linux 6.8.0, bundled Node runtime.

Reproduction

# 1. Create a cron with an explicit --session-key
openclaw cron add \
  --agent main \
  --name "session-key test" \
  --cron "0 0 1 1 *" --tz "America/Denver" \
  --session-key "agent:main:my-shared-key" \
  --message "Reply OK only." \
  --no-deliver --json
# → returns: { "id": "<JOB_ID>", "sessionKey": "agent:main:my-shared-key", "sessionTarget": "isolated", ... }

# 2. Trigger it twice
openclaw cron run <JOB_ID> --expect-final --timeout 60000
openclaw cron run <JOB_ID> --expect-final --timeout 60000

# 3. Inspect the session store
openclaw sessions --json

Expected

Both runs append to a single persistent session keyed agent:main:my-shared-key. Session count grows by 1 (the shared session) regardless of how many times the cron fires.

Actual

Three new entries in the session store after two runs:

agent:main:cron:<JOB_ID>                              ← mutable pointer, rebound to latest sessionId on each run
agent:main:cron:<JOB_ID>:run:<sessionId-of-run-1>     ← persistent receipt
agent:main:cron:<JOB_ID>:run:<sessionId-of-run-2>     ← persistent receipt

• agent:main:my-shared-key is never created.
• Each run gets a brand-new sessionId UUID — runs do not share context.
• The :run: entries persist indefinitely. The in-process cron.sessionRetention reaper (default 24h) does not sweep them — verified by finding 21–28 day old :run: entries on a production deployment with no external maintenance configured. Tested with sessionTarget: isolated. sessionTarget: main is a different code path (requires --system-event instead of --message) and was not exercised in this reproduction.

Impact

On a deployment running two heartbeat-style crons at 15,45 7-20 * * 1-5 and 0,30 8-18 * * 1-5, the session store accumulated 179 entries across 3 agents with cron :run: receipts going back 28 days. Operators have no way to:

1. Make heartbeat checks share context across runs (would meaningfully reduce token cost on long-running deployments).
2. Rely on cron.sessionRetention to bound store growth — must configure top-level session.maintenance.pruneAfter as a workaround.

Adding session.maintenance cleared 53 stale entries on the first enforce pass, confirming the in-process reaper had been silently failing.

Suggested fixes (any one would resolve)

1. Honor --session-key for sessionTarget: isolated agentTurn jobs — route runs to the user-provided key, append turns to that session.
2. Reject --session-key at the CLI layer for incompatible sessionTarget values, with a clear error, so users aren't misled by the silent acceptance.
3. Fix cron.sessionRetention to actually sweep :run: receipts (it appears to only handle cleanly-completed sessions, not aborted/timed-out ones).
4. Add a documented sessionMode: shared option that explicitly opts into cross-run session reuse.

Fix #2 is the minimum viable correction — current behavior is the worst case (silently misleading). Fix #1 or #4 would unlock real architectural improvements for high-frequency cron deployments.

Related

Workaround for affected deployments: set top-level session.maintenance (session singular, NOT tools.sessions):

{
  "session": {
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "14d",
      "maxEntries": 400,
      "maxDiskBytes": "500mb"
    }
  }
}

The schema docs at runtime-schema-CZl4UsDY.js:17650+ describe this block but it is not present in default configs and openclaw doctor --fix does not add it.