From 8399ff888fe7a7877b1526fdb5de62a39940c865 Mon Sep 17 00:00:00 2001 From: Kaspre Date: Thu, 7 May 2026 13:01:37 -0400 Subject: [PATCH] docs(system event): document --session-key timing exception Codex review on PR #78687 [P3] flagged that the docs say next-heartbeat "waits for the next scheduled tick" while the patched timer collapses next-heartbeat+sessionKey to an immediate targeted wake. Add a callout describing the exception and pointing callers who want delayed delivery back at the no-session-key path. Refs #78687. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/cli/system.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/cli/system.md b/docs/cli/system.md index 50a0bc23f74..23d56c6e954 100644 --- a/docs/cli/system.md +++ b/docs/cli/system.md @@ -38,6 +38,14 @@ the heartbeat immediately; `next-heartbeat` waits for the next scheduled tick. Pass `--session-key` to target a specific session (for example to relay an async-task completion back to the channel that started it). +> **Timing exception with `--session-key`:** when `--session-key` is supplied, +> `--mode next-heartbeat` collapses to an immediate targeted wake instead of +> waiting for the next scheduled tick. Targeted wakes use heartbeat intent +> `immediate` so they bypass the runner's not-due gate that would otherwise +> defer (and effectively drop) an `event`-intent wake. If you want delayed +> delivery, omit `--session-key` so the event lands on the main session and +> rides the next regular heartbeat. + Flags: - `--text `: required system event text.