fix(trigger): defer local triggers until session idle

docs/chat-commands.md

@@ -79,13 +79,16 @@ Replace `"Review PR #4502"` with the message you want nanobot to receive. The
 trigger is bound to the session where it was created, so the message goes back
 to that same chat. Keep `nanobot gateway` running so trigger messages can be
 delivered. The trigger message starts an automation turn; it is not shown in
-the chat as a normal user message.
+the chat as a normal user message. If that session is already running a turn,
+the trigger waits until the session is idle instead of being injected into the
+active turn.
 
-Trigger deliveries are stored in the workspace until the gateway consumes them.
-If the gateway exits after claiming a delivery but before marking it complete,
-the next gateway start requeues that delivery. This is an at-least-once local
-queue: a delivery may run more than once if the process exits at the wrong time,
-so external scripts should make repeated trigger messages safe.
+Trigger deliveries are stored in the workspace until their linked agent turn
+finishes successfully. If the gateway exits after claiming a delivery but before
+the turn completes, the next gateway start requeues that delivery. This is an
+at-least-once local queue: a delivery may run more than once if the process
+exits at the wrong time, so external scripts should make repeated trigger
+messages safe.
 
 For longer or generated content, omit the message argument and pipe stdin:
 

docs/cli-reference.md

@@ -136,11 +136,13 @@ Keep `nanobot gateway` running so the message can be delivered to the linked
 chat/session.
 
 The command writes to a workspace-local durable queue. If `nanobot gateway` is
-not running yet, the message waits in that workspace. If the gateway exits after
-claiming a delivery but before completing it, the next gateway start requeues
-that delivery. The queue is at-least-once, not exactly-once, so the same message
-can be delivered again after an interrupted process. Run one gateway consumer
-per workspace; this local queue is not a distributed multi-consumer queue.
+not running yet, the message waits in that workspace. If the target session is
+already running a turn, the trigger waits for that session to become idle. If the
+gateway exits after claiming a delivery but before the linked turn completes,
+the next gateway start requeues that delivery. The queue is at-least-once, not
+exactly-once, so the same message can be delivered again after an interrupted
+process. Run one gateway consumer per workspace; this local queue is not a
+distributed multi-consumer queue.
 
 Use stdin when another local process generates the message:
 

docs/concepts.md

@@ -148,8 +148,9 @@ schedule. Create one from the target chat with `/trigger <name>`, then call
 `nanobot trigger <id> "<message>"` when a local script or external service wants
 nanobot to respond in that session. Webhook servers, third-party auth, and
 event-to-message formatting stay outside nanobot. Trigger deliveries are stored
-in the workspace until the gateway consumes them and are requeued on gateway
-restart if processing was interrupted. Delivery is at-least-once, so external
+in the workspace until the linked agent turn finishes successfully. If the
+target session is busy, the trigger waits until that session is idle instead of
+being injected into the active turn. Delivery is at-least-once, so external
 systems should tolerate repeated trigger messages.
 
 ## Where to Go Next

docs/webui.md

@@ -133,9 +133,11 @@ that webhook/service outside nanobot and have it call the trigger command with
 the final message.
 
 Trigger deliveries use the same workspace as the gateway. They survive gateway
-restarts and are requeued if the process exits before marking a delivery
-complete. This is an at-least-once local queue, so repeated delivery is possible
-after an interrupted process.
+restarts and are requeued if the process exits before the linked turn completes.
+If the linked session is already running a turn, the local trigger waits until
+that session is idle instead of being injected into the active turn. This is an
+at-least-once local queue, so repeated delivery is possible after an interrupted
+process.
 
 For recurring background checks that should stay quiet unless there is something
 useful to report, use the protected heartbeat job by editing `HEARTBEAT.md`