feat: default queueing to steer

docs/concepts/queue.md

@@ -1,7 +1,8 @@
 ---
-summary: "Command queue design that serializes inbound auto-reply runs"
+summary: "Auto-reply queue modes, defaults, and per-session overrides"
 read_when:
   - Changing auto-reply execution or concurrency
+  - Explaining /queue modes or message steering behavior
 title: "Command queue"
 ---
 
@@ -20,25 +21,33 @@ We serialize inbound auto-reply runs (all channels) through a tiny in-process qu
 - When verbose logging is enabled, queued runs emit a short notice if they waited more than ~2s before starting.
 - Typing indicators still fire immediately on enqueue (when supported by the channel) so user experience is unchanged while we wait our turn.
 
-## Queue modes (per channel)
+## Defaults
+
+When unset, all inbound channel surfaces use:
+
+- `mode: "steer"`
+- `debounceMs: 500`
+- `cap: 20`
+- `drop: "summarize"`
+
+`steer` is the default because it keeps the active model turn responsive without
+starting a second session run. If the current run cannot accept steering,
+OpenClaw falls back to a followup queue entry.
+
+## Queue modes
 
 Inbound messages can steer the current run, wait for a followup turn, or do both:
 
-- `steer`: inject immediately into the current run (cancels pending tool calls after the next tool boundary). If not streaming, falls back to followup.
-- `followup`: enqueue for the next agent turn after the current run ends.
-- `collect`: coalesce all queued messages into a **single** followup turn (default). If messages target different channels/threads, they drain individually to preserve routing.
-- `steer-backlog` (aka `steer+backlog`): steer now **and** preserve the message for a followup turn.
+- `steer`: queue a steering message into the active Pi run. Pi delivers it **after the current assistant turn finishes executing its tool calls**, before the next LLM call. If the run is not actively streaming or steering is unavailable, OpenClaw falls back to a followup queue entry.
+- `followup`: enqueue each message for a later agent turn after the current run ends.
+- `collect`: coalesce queued messages into a **single** followup turn after the quiet window. If messages target different channels/threads, they drain individually to preserve routing.
+- `steer-backlog` (aka `steer+backlog`): steer now **and** preserve the same message for a followup turn.
 - `interrupt` (legacy): abort the active run for that session, then run the newest message.
 - `queue` (legacy alias): same as `steer`.
 
 Steer-backlog means you can get a followup response after the steered run, so
 streaming surfaces can look like duplicates. Prefer `collect`/`steer` if you want
 one response per inbound message.
-Send `/queue collect` as a standalone command (per-session) or set `messages.queue.byChannel.discord: "collect"`.
-
-Defaults (when unset in config):
-
-- All surfaces → `collect`
 
 Configure globally or per channel via `messages.queue`:
 
@@ -46,8 +55,8 @@ Configure globally or per channel via `messages.queue`:
 {
   messages: {
     queue: {
-      mode: "collect",
-      debounceMs: 1000,
+      mode: "steer",
+      debounceMs: 500,
       cap: 20,
       drop: "summarize",
       byChannel: { discord: "collect" },
@@ -60,17 +69,33 @@ Configure globally or per channel via `messages.queue`:
 
 Options apply to `followup`, `collect`, and `steer-backlog` (and to `steer` when it falls back to followup):
 
-- `debounceMs`: wait for quiet before starting a followup turn (prevents “continue, continue”).
-- `cap`: max queued messages per session.
-- `drop`: overflow policy (`old`, `new`, `summarize`).
+- `debounceMs`: quiet window before draining queued followups. Bare numbers are milliseconds; units `ms`, `s`, `m`, `h`, and `d` are accepted by `/queue` options.
+- `cap`: max queued messages per session. Values below `1` are ignored.
+- `drop: "summarize"`: default. Drop the oldest queued entries as needed, keep compact summaries, and inject them as a synthetic followup prompt.
+- `drop: "old"`: drop the oldest queued entries as needed, without preserving summaries.
+- `drop: "new"`: reject the newest message when the queue is already full.
 
-Summarize keeps a short bullet list of dropped messages and injects it as a synthetic followup prompt.
-Defaults: `debounceMs: 1000`, `cap: 20`, `drop: summarize`.
+Defaults: `debounceMs: 500`, `cap: 20`, `drop: summarize`.
+
+## Precedence
+
+For mode selection, OpenClaw resolves:
+
+1. Inline or stored per-session `/queue` override.
+2. `messages.queue.byChannel.<channel>`.
+3. `messages.queue.mode`.
+4. Default `steer`.
+
+For options, inline or stored `/queue` options win over config. Then
+channel-specific debounce (`messages.queue.debounceMsByChannel`), plugin
+debounce defaults, global `messages.queue` options, and built-in defaults are
+applied. `cap` and `drop` are global/session options, not per-channel config
+keys.
 
 ## Per-session overrides
 
 - Send `/queue <mode>` as a standalone command to store the mode for the current session.
-- Options can be combined: `/queue collect debounce:2s cap:25 drop:summarize`
+- Options can be combined: `/queue collect debounce:0.5s cap:25 drop:summarize`
 - `/queue default` or `/queue reset` clears the session override.
 
 ## Scope and guarantees