docs: refresh push-based orchestration refs

docs/automation/tasks.md

@@ -26,6 +26,9 @@ Not every agent run creates a task. Heartbeat turns and normal interactive chat
 - ACP, subagents, all cron jobs, and CLI operations create tasks. Heartbeat turns do not.
 - Each task moves through `queued → running → terminal` (succeeded, failed, timed_out, cancelled, or lost).
 - Cron tasks stay live while the cron runtime still owns the job; chat-backed CLI tasks stay live only while their owning run context is still active.
+- Completion is push-driven: detached work can notify directly or wake the
+  requester session/heartbeat when it finishes, so status polling loops are
+  usually unnecessary.
 - Isolated cron runs and subagent completions best-effort clean up tracked browser tabs/processes for their child session before final cleanup bookkeeping.
 - Isolated cron delivery suppresses stale interim parent replies while
   descendant subagent work is still draining, and it prefers final descendant
@@ -128,6 +131,10 @@ When a task reaches a terminal state, OpenClaw notifies you. There are two deliv
 Task completion triggers an immediate heartbeat wake so you see the result quickly — you do not have to wait for the next scheduled heartbeat tick.
 </Tip>
 
+That means the usual workflow is push-based: start detached work once, then let
+the runtime wake or notify you on completion. Poll task state only when you
+need debugging, intervention, or an explicit audit.
+
 ### Notification policies
 
 Control how much you hear about each task:

docs/concepts/system-prompt.md

@@ -30,6 +30,22 @@ The prompt is intentionally compact and uses fixed sections:
 - **Runtime**: host, OS, node, model, repo root (when detected), thinking level (one line).
 - **Reasoning**: current visibility level + /reasoning toggle hint.
 
+The Tooling section also includes runtime guidance for long-running work:
+
+- use cron for future follow-up (`check back later`, reminders, recurring work)
+  instead of `exec` sleep loops, `yieldMs` delay tricks, or repeated `process`
+  polling
+- use `exec` / `process` only for commands that start now and continue running
+  in the background
+- when automatic completion wake is enabled, start the command once and rely on
+  the push-based wake path when it emits output or fails
+- use `process` for logs, status, input, or intervention when you need to
+  inspect a running command
+- if the task is larger, prefer `sessions_spawn`; sub-agent completion is
+  push-based and auto-announces back to the requester
+- do not poll `subagents list` / `sessions_list` in a loop just to wait for
+  completion
+
 Safety guardrails in the system prompt are advisory. They guide model behavior but do not enforce policy. Use tool policy, exec approvals, sandboxing, and channel allowlists for hard enforcement; operators can disable these by design.
 
 ## Prompt modes

docs/tools/exec.md

@@ -50,6 +50,12 @@ Notes:
 - Script preflight checks (for common Python/Node shell-syntax mistakes) only inspect files inside the
   effective `workdir` boundary. If a script path resolves outside `workdir`, preflight is skipped for
   that file.
+- For long-running work that starts now, start it once and rely on automatic
+  completion wake when it is enabled and the command emits output or fails.
+  Use `process` for logs, status, input, or intervention; do not emulate
+  scheduling with sleep loops, timeout loops, or repeated polling.
+- For work that should happen later or on a schedule, use cron instead of
+  `exec` sleep/delay patterns.
 
 ## Config
 
@@ -171,6 +177,9 @@ Background + poll:
 {"tool":"process","action":"poll","sessionId":"<id>"}
 ```
 
+Polling is for on-demand status, not waiting loops. If automatic completion wake
+is enabled, the command can wake the session when it emits output or fails.
+
 Send keys (tmux-style):
 
 ```json

docs/tools/subagents.md

@@ -43,6 +43,9 @@ transcript path on disk when you need the raw full transcript.
 
 - The spawn command is non-blocking; it returns a run id immediately.
 - On completion, the sub-agent announces a summary/result message back to the requester chat channel.
+- Completion is push-based. Once spawned, do not poll `/subagents list`,
+  `sessions_list`, or `sessions_history` in a loop just to wait for it to
+  finish; inspect status only on-demand for debugging or intervention.
 - On completion, OpenClaw best-effort closes tracked browser tabs/processes opened by that sub-agent session before the announce cleanup flow continues.
 - For manual spawns, delivery is resilient:
   - OpenClaw tries direct `agent` delivery first with a stable idempotency key.
@@ -189,6 +192,14 @@ Results flow back up the chain:
 
 Each level only sees announces from its direct children.
 
+Operational guidance:
+
+- Start child work once and wait for completion events instead of building poll
+  loops around `sessions_list`, `sessions_history`, `/subagents list`, or
+  `exec` sleep commands.
+- If a child completion event arrives after you already sent the final answer,
+  the correct follow-up is `NO_REPLY`.
+
 ### Tool policy by depth
 
 - Role and control scope are written into session metadata at spawn time. That keeps flat or restored session keys from accidentally regaining orchestrator privileges.