fix(nudge): deliver queued nudges via hook trigger, not raw tmux send-keys

Format nudge messages as <system-reminder> blocks so agents process them
as background notifications rather than user interruptions. Add
watchAndDeliver idle poller to drain queued nudges when agent becomes
idle (UserPromptSubmit hook does not fire for idle agents).

Closes #2497

Co-Authored-By: Sean Bearden <72461227+seanbearden@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

internal/cmd/nudge.go

@@ -124,6 +124,18 @@ const ifFreshMaxAge = 60 * time.Second
 // This is a var (not const) so tests can override it to avoid 15s waits.
 var waitIdleTimeout = 15 * time.Second
 
+// idleWatcherTimeout is how long the background idle watcher polls after
+// queuing a nudge. If the agent becomes idle within this window, the watcher
+// drains the queue and delivers directly. This covers the gap where an agent
+// finishes work after WaitForIdle's timeout but before anyone sends new input
+// (so UserPromptSubmit never fires and the queue never drains).
+// Var so tests can override.
+var idleWatcherTimeout = 60 * time.Second
+
+// idleWatcherPollInterval is how often the background watcher checks for idle.
+// Var so tests can override.
+var idleWatcherPollInterval = 1 * time.Second
+
 // deliverNudge routes a nudge based on the --mode flag.
 // For "immediate" mode: sends directly via tmux (current behavior).
 // For "queue" mode: writes to the nudge queue for cooperative delivery.
@@ -156,8 +168,15 @@ func deliverNudge(t *tmux.Tmux, sessionName, message, sender string) error {
 		// Try to wait for idle
 		err := t.WaitForIdle(sessionName, waitIdleTimeout)
 		if err == nil {
-			// Agent is idle — safe to deliver directly
-			return t.NudgeSession(sessionName, prefixedMessage)
+			// Agent is idle — deliver directly. Format as system-reminder
+			// so the agent processes it as a background notification rather
+			// than a user interruption/correction.
+			formatted := nudge.FormatForInjection([]nudge.QueuedNudge{{
+				Sender:   sender,
+				Message:  message,
+				Priority: nudgePriorityFlag,
+			}})
+			return t.NudgeSession(sessionName, formatted)
 		}
 		// Terminal errors (session gone, no server) — propagate, don't queue.
 		// Queueing a nudge for a dead session means it will never be delivered.
@@ -173,15 +192,82 @@ func deliverNudge(t *tmux.Tmux, sessionName, message, sender string) error {
 			// Queue failed — fall back to immediate as last resort.
 			// Better to interrupt than lose the message entirely.
 			fmt.Fprintf(os.Stderr, "Warning: queue fallback failed (%v), delivering immediately\n", qErr)
-			return t.NudgeSession(sessionName, prefixedMessage)
-		}
+			// Still use FormatForInjection so the agent sees a consistent
+			// <system-reminder> format regardless of delivery path.
+			formatted := nudge.FormatForInjection([]nudge.QueuedNudge{{
+				Sender:   sender,
+				Message:  message,
+				Priority: nudgePriorityFlag,
+			}})
+			return t.NudgeSession(sessionName, formatted)
+		}
+		// Run watcher synchronously: polls for idle over a longer window.
+		// The UserPromptSubmit hook drains the queue on agent input, but an
+		// idle agent receives no input — so queued nudges are lost without
+		// this watcher. It exits on: delivery, session death, or timeout.
+		// Must be synchronous (not a goroutine) because gt nudge is a CLI
+		// command — the process exits after return, killing any goroutines.
+		watchAndDeliver(t, townRoot, sessionName)
 		return nil
 
 	default: // NudgeModeImmediate
 		return t.NudgeSession(sessionName, prefixedMessage)
 	}
 }
 
+// watchAndDeliver polls a session for idle state over idleWatcherTimeout.
+// When the agent becomes idle, it drains the nudge queue and sends the
+// formatted content directly via NudgeSession. This bypasses the
+// UserPromptSubmit hook entirely — that hook does not fire for tmux
+// send-keys input, so we cannot rely on it.
+//
+// This runs synchronously — gt nudge blocks until the watcher exits.
+// Errors are logged to stderr rather than returned since delivery failure
+// after successful queue write is non-fatal (queue persists for next drain).
+//
+// Exit conditions:
+//   - Agent becomes idle: drain queue and deliver formatted content, exit.
+//   - Queue is empty (someone else drained it): exit.
+//   - Session disappears: exit (nothing to deliver to).
+//   - Timeout: exit (queue stays for next input or watcher cycle).
+func watchAndDeliver(t *tmux.Tmux, townRoot, sessionName string) {
+	fmt.Fprintf(os.Stderr, "Watching %s for idle (up to %s)...\n", sessionName, idleWatcherTimeout)
+	deadline := time.Now().Add(idleWatcherTimeout)
+	for time.Now().Before(deadline) {
+		time.Sleep(idleWatcherPollInterval)
+
+		// If queue is already empty, someone else drained it.
+		if nudge.QueueLen(townRoot, sessionName) == 0 {
+			return
+		}
+
+		// Check if session still exists — no point watching a dead session.
+		if exists, _ := t.HasSession(sessionName); !exists {
+			return
+		}
+
+		// Use WaitForIdle with a short timeout instead of single-snapshot
+		// IsIdle to get the consecutive-poll guard (2 polls 200ms apart).
+		// This avoids false positives during inter-tool-call gaps where
+		// the prompt briefly appears while Claude Code is still working.
+		if err := t.WaitForIdle(sessionName, idleWatcherPollInterval); err == nil {
+			// Drain atomically claims queued entries (rename-based).
+			// If another process raced and drained first, we get an
+			// empty slice and skip delivery to avoid duplicates.
+			drained, _ := nudge.Drain(townRoot, sessionName)
+			if len(drained) == 0 {
+				return
+			}
+			formatted := nudge.FormatForInjection(drained)
+			if err := t.NudgeSession(sessionName, formatted); err != nil {
+				fmt.Fprintf(os.Stderr, "idle-watcher: delivery for %s failed: %v\n", sessionName, err)
+			}
+			return
+		}
+	}
+	// Timeout — nudge stays in queue for next watcher or manual drain.
+}
+
 // validNudgeModes is the set of allowed --mode values.
 var validNudgeModes = map[string]bool{
 	NudgeModeImmediate: true,

internal/cmd/nudge_test.go

@@ -375,6 +375,38 @@ func TestIfFreshSessionAgeCheck(t *testing.T) {
 	}
 }
 
+func TestPostQueueIdleRecovery_SkipsDeliveryWhenDrainEmpty(t *testing.T) {
+	// Behavioral test (gt-y2zk): when the idle recovery path fires but
+	// another process already drained the queue, we must NOT deliver to
+	// avoid duplicates. This exercises the len(drained) > 0 guard.
+	townRoot := t.TempDir()
+	session := "gt-crew-test"
+
+	// Enqueue a nudge, then drain it (simulating a racing hook).
+	if err := nudge.Enqueue(townRoot, session, nudge.QueuedNudge{
+		Sender:  "test",
+		Message: "hello",
+	}); err != nil {
+		t.Fatalf("Enqueue: %v", err)
+	}
+	drained, err := nudge.Drain(townRoot, session)
+	if err != nil {
+		t.Fatalf("first Drain: %v", err)
+	}
+	if len(drained) != 1 {
+		t.Fatalf("first Drain got %d entries, want 1", len(drained))
+	}
+
+	// Second drain should return empty — the racing hook already claimed it.
+	drained2, err := nudge.Drain(townRoot, session)
+	if err != nil {
+		t.Fatalf("second Drain: %v", err)
+	}
+	if len(drained2) != 0 {
+		t.Errorf("second Drain got %d entries, want 0 (already claimed)", len(drained2))
+	}
+}
+
 func TestValidModeMapsMatchConstants(t *testing.T) {
 	// Ensure the validation maps cover all defined mode constants.
 	modes := []string{NudgeModeImmediate, NudgeModeQueue, NudgeModeWaitIdle}
@@ -390,3 +422,86 @@ func TestValidModeMapsMatchConstants(t *testing.T) {
 		}
 	}
 }
+
+func TestIdleWatcherTimeout(t *testing.T) {
+	// Verify the watcher timeout is in a reasonable range.
+	if idleWatcherTimeout < 10*time.Second {
+		t.Errorf("idleWatcherTimeout = %v, too short (min 10s)", idleWatcherTimeout)
+	}
+	if idleWatcherTimeout > 5*time.Minute {
+		t.Errorf("idleWatcherTimeout = %v, too long (max 5m)", idleWatcherTimeout)
+	}
+}
+
+func TestIdleWatcherPollInterval(t *testing.T) {
+	// Verify the poll interval is reasonable — fast enough to be responsive,
+	// slow enough to not burn CPU.
+	if idleWatcherPollInterval < 200*time.Millisecond {
+		t.Errorf("idleWatcherPollInterval = %v, too fast (min 200ms)", idleWatcherPollInterval)
+	}
+	if idleWatcherPollInterval > 5*time.Second {
+		t.Errorf("idleWatcherPollInterval = %v, too slow (max 5s)", idleWatcherPollInterval)
+	}
+}
+
+func TestIdleWatcherExitsOnEmptyQueue(t *testing.T) {
+	// watchAndDeliver should exit immediately when queue is empty
+	// (someone else drained it). We test this by calling with a
+	// temp dir that has no queue files.
+	origTimeout := idleWatcherTimeout
+	origInterval := idleWatcherPollInterval
+	defer func() {
+		idleWatcherTimeout = origTimeout
+		idleWatcherPollInterval = origInterval
+	}()
+
+	// Very short timeout so test doesn't hang
+	idleWatcherTimeout = 500 * time.Millisecond
+	idleWatcherPollInterval = 50 * time.Millisecond
+
+	tmpDir := t.TempDir()
+
+	// watchAndDeliver checks QueueLen first — with no queue files,
+	// it should exit immediately. We verify it doesn't block.
+	done := make(chan struct{})
+	go func() {
+		// Use a nil-safe Tmux — QueueLen returns 0 before IsIdle is called.
+		watchAndDeliver(nil, tmpDir, "test-session")
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// Good — exited because queue was empty
+	case <-time.After(2 * time.Second):
+		t.Fatal("watchAndDeliver did not exit within 2s for empty queue")
+	}
+}
+
+func TestQueueLen(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	// Empty queue
+	if got := nudge.QueueLen(tmpDir, "test-session"); got != 0 {
+		t.Errorf("QueueLen on empty dir = %d, want 0", got)
+	}
+
+	// Enqueue one
+	err := nudge.Enqueue(tmpDir, "test-session", nudge.QueuedNudge{
+		Sender:  "test",
+		Message: "hello",
+	})
+	if err != nil {
+		t.Fatalf("Enqueue failed: %v", err)
+	}
+
+	if got := nudge.QueueLen(tmpDir, "test-session"); got != 1 {
+		t.Errorf("QueueLen after enqueue = %d, want 1", got)
+	}
+
+	// Drain and verify empty
+	_, _ = nudge.Drain(tmpDir, "test-session")
+	if got := nudge.QueueLen(tmpDir, "test-session"); got != 0 {
+		t.Errorf("QueueLen after drain = %d, want 0", got)
+	}
+}

internal/nudge/queue.go

@@ -272,6 +272,18 @@ func Pending(townRoot, session string) (int, error) {
 	return count, nil
 }
 
+// QueueLen returns the number of pending nudges for a session without draining.
+// Returns 0 on error — callers use this for quick checks. Missing queue
+// directories are expected (no nudges yet) and silenced; other filesystem
+// errors are logged to stderr so they don't go unnoticed.
+func QueueLen(townRoot, session string) int {
+	n, err := Pending(townRoot, session)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Warning: nudge queue check failed for %s: %v\n", session, err)
+	}
+	return n
+}
+
 // FormatForInjection formats queued nudges as a system-reminder block
 // suitable for Claude Code hook output.
 func FormatForInjection(nudges []QueuedNudge) string {