fix: pre-push review findings on the exec_command buffer-cap fix

Ran an adversarial review before opening the PR. It found the truncation
notice added alongside the buffer cap didn't actually work: prefixing
execOutputTruncatedMessage into drainString()'s text meant the notice
always sat ~2MiB before the end of the combined output, but the tool's
own downstream truncateExecOutput() keeps at most a 400KB tail (even at
the maximum allowed max_output_tokens) — so the notice was reliably
swallowed, or chopped into an unreadable fragment at smaller budgets.
Verified with direct reproductions against the real functions.

Fixed by moving the signal out of the text stream entirely:
- execOutputBuffer gains consumeTruncated() (read+reset, called once per
  collect()) and peekTruncated() (read-only, for status views) instead of
  injecting a marker into the drained bytes.
- collect() now returns (string, bool); both call sites thread the bool
  through to execToolResult, which sets meta["output_buffer_truncated"]
  and appends the notice to the response body *after* truncateExecOutput
  runs, so it can never be re-truncated or land in a discarded region.
- Also flagged: a session torn down without ever being polled again after
  truncation loses the signal entirely, since nothing drains/logs it on
  teardown. Full audit-trail logging felt like overkill for a soft
  transparency signal on top of a hard memory-safety fix, but exposed
  peekTruncated() on ExecSessionSnapshot and surfaced it in the /ps row
  (background_terminals.go) so it's visible any time a still-running
  session is checked — covers the common case (the review's own scenario:
  a long-lived dev server nobody's polling but that's still alive) even
  though a session reaped before ever being looked at is still a gap.

New tests: reworked TestExecOutputBufferCapsUndrainedData for the
consume/peek API, and TestExecToolResultSurfacesBufferTruncationOutsideByteBudget
reproducing the review's exact failure case (max_output_tokens=1) and
proving the notice now survives it.

internal/agent/compaction.go

@@ -280,6 +280,25 @@ func isContextLimitError(message string) bool {
 	return false
 }
 
+// isStreamTimeoutError reports whether a streamed error is a provider stream
+// idle/stall timeout (providerio surfaces these as "idle timeout after …" /
+// "no output for …" / "stream stalled"). Such a turn produced nothing, so when
+// no content was forwarded yet it can be safely re-issued on a fresh connection
+// (see the stall-retry in the agent loop). Substring + case-insensitive to
+// tolerate the prefixed "provider stream error: …" wrapping.
+func isStreamTimeoutError(message string) bool {
+	lowered := strings.ToLower(strings.TrimSpace(message))
+	if lowered == "" {
+		return false
+	}
+	for _, needle := range []string{"idle timeout after", "no output for", "stream stalled"} {
+		if strings.Contains(lowered, needle) {
+			return true
+		}
+	}
+	return false
+}
+
 // compactionState carries the per-run state the agent loop needs to compact a
 // conversation safely. It is created once per Run and is a no-op whenever
 // options.ContextWindow <= 0.

internal/agent/decode_args_test.go

@@ -0,0 +1,99 @@
+package agent
+
+import "testing"
+
+// decodeToolArguments must (a) decode a normal single-object payload unchanged,
+// (b) tolerate a weak model packing multiple concatenated top-level JSON objects
+// into one arguments string by decoding the FIRST object and ignoring the rest
+// (the minimax-m3 "invalid character '{' after top-level value" failure), and
+// (c) still reject a genuinely malformed/truncated first object.
+func TestDecodeToolArguments(t *testing.T) {
+	t.Run("single object decodes normally", func(t *testing.T) {
+		var a map[string]any
+		if err := decodeToolArguments(`{"path":"x"}`, &a); err != nil {
+			t.Fatalf("err = %v, want nil", err)
+		}
+		if a["path"] != "x" {
+			t.Fatalf("decoded %v, want path=x", a)
+		}
+	})
+
+	t.Run("concatenated objects decode the first, ignore trailing", func(t *testing.T) {
+		var b map[string]any
+		if err := decodeToolArguments(`{"path":"first"}{"path":"second"}`, &b); err != nil {
+			t.Fatalf("multi-object should decode the first, got err = %v", err)
+		}
+		if b["path"] != "first" {
+			t.Fatalf("decoded %v, want the first object (path=first)", b)
+		}
+	})
+
+	t.Run("distinct tools' args concatenated (real minimax case): first object used", func(t *testing.T) {
+		var c map[string]any
+		if err := decodeToolArguments(`{"plan":[1,2]}{"cmd":"go version"}`, &c); err != nil {
+			t.Fatalf("err = %v, want nil", err)
+		}
+		if _, ok := c["plan"]; !ok || c["cmd"] != nil {
+			t.Fatalf("decoded %v, want only the first object's keys", c)
+		}
+	})
+
+	t.Run("truncated first object still errors", func(t *testing.T) {
+		var d map[string]any
+		if err := decodeToolArguments(`{"path":`, &d); err == nil {
+			t.Fatal("truncated JSON must still error")
+		}
+	})
+
+	t.Run("non-JSON trailing garbage still errors (not masked)", func(t *testing.T) {
+		var g map[string]any
+		if err := decodeToolArguments(`{"x":1}xyz`, &g); err == nil {
+			t.Fatal("a valid first object followed by non-JSON garbage must still error")
+		}
+	})
+
+	t.Run("recoverableToolArguments: only whole-JSON trailing is tolerated", func(t *testing.T) {
+		cases := []struct {
+			in    string
+			ok    bool
+			first string
+		}{
+			{`{"a":1}`, true, `{"a":1}`},
+			{`{"a":1}{"b":2}`, true, `{"a":1}`},
+			{`{"a":1}  {"b":2}  `, true, `{"a":1}`},
+			{`{"a":1}xyz`, false, ""},
+			{`{"a":`, false, ""},
+			{`   `, false, ""},
+		}
+		for _, c := range cases {
+			first, ok := recoverableToolArguments(c.in)
+			if ok != c.ok || (ok && first != c.first) {
+				t.Fatalf("recoverableToolArguments(%q) = (%q,%v), want (%q,%v)", c.in, first, ok, c.first, c.ok)
+			}
+		}
+	})
+
+	t.Run("historySafeToolCalls recovers the first object, not {}", func(t *testing.T) {
+		out := historySafeToolCalls([]ToolCall{
+			{ID: "c1", Name: "read_file", Arguments: `{"path":"README.md"}{"path":"AGENTS.md"}`}, // concatenated -> first
+			{ID: "c2", Name: "read_file", Arguments: `{"path":"x"}xyz`},                          // garbage -> {}
+			{ID: "c3", Name: "read_file", Arguments: `{"path":"ok"}`},                            // valid -> unchanged
+		})
+		if out[0].Arguments != `{"path":"README.md"}` {
+			t.Fatalf("concatenated args should record the first object, got %q", out[0].Arguments)
+		}
+		if out[1].Arguments != "{}" {
+			t.Fatalf("garbage-trailing args should record {}, got %q", out[1].Arguments)
+		}
+		if out[2].Arguments != `{"path":"ok"}` {
+			t.Fatalf("valid args should be unchanged, got %q", out[2].Arguments)
+		}
+	})
+
+	t.Run("whitespace-only errors (caller guards empty)", func(t *testing.T) {
+		var e map[string]any
+		if err := decodeToolArguments("   ", &e); err == nil {
+			t.Fatal("whitespace-only must error")
+		}
+	})
+}

internal/agent/loop.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"sort"
 	"strings"
 	"sync"
@@ -20,6 +21,12 @@ import (
 const maxTurnsAnswer = "Agent reached maximum number of turns without a final answer."
 const maxTurnsFinalAnswerPrompt = "You have reached the tool-turn limit. Do not call tools. Give a concise final answer now: summarize what you completed, what you found, and any remaining blockers."
 
+// maxStreamStallRetries bounds how many times a turn that timed out (idle/stall)
+// WITH NO OUTPUT yet is re-issued on a fresh connection before giving up. Only
+// the no-output case is retried (a partial turn would duplicate), so this is a
+// safe recovery for a stalled/dead pooled connection.
+const maxStreamStallRetries = 2
+
 const (
 	toolResultMetaControl       = "control"
 	toolResultControlSpecReview = "spec_review_required"
@@ -203,55 +210,72 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 			}
 		}
 
-		collected := zeroruntime.CollectStreamWithOptions(ctx, stream, zeroruntime.CollectOptions{
-			OnText:          options.OnText,
-			OnReasoning:     options.OnReasoning,
-			OnUsage:         options.OnUsage,
-			OnToolCallStart: options.OnToolCallStart,
-			OnToolCallDelta: options.OnToolCallDelta,
-		})
-		if collected.Error != "" {
-			collectedErr := errors.New(collected.Error)
-			if isImageRejectionError(collectedErr) {
-				result.Messages = copyMessages(messages)
-				return result, fmt.Errorf("model %s rejected the image: %s. The model may not support image input — try switching to a vision-capable model (claude, gpt-4o, gemini)", options.Model, collected.Error)
+		// Wrapped callbacks flag ANY output forwarded this turn, so a stall retry
+		// never re-streams on top of output the user already saw — even across the
+		// reactive-compaction retry below, which overwrites `collected`.
+		forwardedAnything := false
+		mark := func() { forwardedAnything = true }
+		// OnUsage is telemetry, not visible output, so it does NOT mark
+		// forwardedAnything: a provider that emits an early usage event (e.g. prompt
+		// tokens) then stalls with no content must still be safely retried. The gate
+		// only guards against re-streaming output the user actually SAW.
+		forwardingOpts := zeroruntime.CollectOptions{OnUsage: options.OnUsage}
+		if options.OnText != nil {
+			forwardingOpts.OnText = func(s string) { mark(); options.OnText(s) }
+		}
+		if options.OnReasoning != nil {
+			forwardingOpts.OnReasoning = func(s string) { mark(); options.OnReasoning(s) }
+		}
+		if options.OnToolCallStart != nil {
+			forwardingOpts.OnToolCallStart = func(id, name string) { mark(); options.OnToolCallStart(id, name) }
+		}
+		if options.OnToolCallDelta != nil {
+			forwardingOpts.OnToolCallDelta = func(id, fragment string) { mark(); options.OnToolCallDelta(id, fragment) }
+		}
+		// recoverStreamError applies the same non-stall recovery the initial stream
+		// gets to ANY collected error — including one from a reissued (stall-retry)
+		// stream: an image rejection gets the friendly wrapping, and a context limit
+		// gets one compaction + reactive reissue (omitting visible callbacks, since
+		// any pre-error output was already forwarded). It returns the possibly-updated
+		// collected and a non-nil stop error when the run must end now.
+		recoverStreamError := func(collected zeroruntime.CollectedStream) (zeroruntime.CollectedStream, error) {
+			if isImageRejectionError(errors.New(collected.Error)) {
+				return collected, fmt.Errorf("model %s rejected the image: %s. The model may not support image input — try switching to a vision-capable model (claude, gpt-4o, gemini)", options.Model, collected.Error)
 			}
-			// REACTIVE compaction: the streamed error may also be a context
-			// limit (some providers surface it mid-stream). Compact and retry
-			// the same turn once before giving up.
+			// REACTIVE compaction: the streamed error may also be a context limit
+			// (some providers surface it mid-stream). Compact and retry once.
 			if compacted, retried, retryErr := compactor.recover(ctx, provider, messages, request.Tools, collected.Error); retried {
 				messages = compacted
 				if retryErr != nil {
-					result.Messages = copyMessages(messages)
-					return result, retryErr
+					return collected, retryErr
 				}
-				// Reuse the SAME active-mode partition (exposed) from this
-				// turn rather than the bare toolDefinitions: exposed depends on
-				// registry+loaded (not the messages), so they stay valid after compaction.
-				// Routing through an empty-loaded partition here would re-hide every
-				// already-loaded deferred tool.
+				// Reuse the SAME active-mode partition (exposed) from this turn rather
+				// than the bare toolDefinitions: exposed depends on registry+loaded (not
+				// the messages), so it stays valid after compaction.
 				retryRequest := zeroruntime.CompletionRequest{
 					Messages:        copyMessages(messages),
 					Tools:           exposed,
 					ReasoningEffort: options.ReasoningEffort,
 				}
-				// Pre-content reconnect of a mid-stream disconnect: route the connect
-				// through the reconnect helper too (AUDIT-L1).
 				retryStream, retryStreamErr := streamWithReconnect(ctx, provider, retryRequest, reconnectNoticeFor(options))
 				if retryStreamErr != nil {
-					result.Messages = copyMessages(messages)
-					return result, retryStreamErr
+					return collected, retryStreamErr
 				}
-				// Omit OnText on the reactive retry: when the original error
-				// surfaced MID-stream, partial text was already forwarded to the
-				// user. Re-streaming the retried response on top of it would
-				// duplicate output. OnUsage IS kept so token telemetry/budgeting
-				// still counts the successful retry. The retried text is captured
-				// in collected.Text and becomes the turn's assistant message.
 				collected = zeroruntime.CollectStreamWithOptions(ctx, retryStream, zeroruntime.CollectOptions{
 					OnUsage: options.OnUsage,
 				})
 			}
+			return collected, nil
+		}
+
+		collected := zeroruntime.CollectStreamWithOptions(ctx, stream, forwardingOpts)
+		if collected.Error != "" {
+			updated, stop := recoverStreamError(collected)
+			collected = updated
+			if stop != nil {
+				result.Messages = copyMessages(messages)
+				return result, stop
+			}
 		}
 		// Check ctx first: on cancellation helpers.go sets collected.Error to
 		// ctx.Err().Error(), so returning errors.New(collected.Error) would lose
@@ -260,9 +284,45 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 			result.Messages = copyMessages(messages)
 			return result, ctx.Err()
 		}
+		// A stream idle/stall timeout with NO output forwarded yet this turn can be
+		// safely re-issued on a fresh connection — nothing was shown, so there's no
+		// duplication (this recovers the macOS stale-pooled-connection hang when it
+		// slips past the transport's response-header timeout). A turn that already
+		// streamed partial text/tool-calls is NOT retried (it would duplicate) and
+		// falls through to the error return below. Capped + exponential backoff.
+		for attempt := 1; attempt <= maxStreamStallRetries &&
+			isStreamTimeoutError(collected.Error) && !forwardedAnything &&
+			collected.Text == "" && len(collected.ToolCalls) == 0; attempt++ {
+			if err := sleepWithContext(ctx, backoffFor(attempt)); err != nil {
+				result.Messages = copyMessages(messages)
+				return result, err
+			}
+			retryRequest := zeroruntime.CompletionRequest{
+				Messages:        copyMessages(messages),
+				Tools:           exposed,
+				ReasoningEffort: options.ReasoningEffort,
+			}
+			retryStream, retryErr := streamWithReconnect(ctx, provider, retryRequest, reconnectNoticeFor(options))
+			if retryErr != nil {
+				result.Messages = copyMessages(messages)
+				return result, retryErr
+			}
+			collected = zeroruntime.CollectStreamWithOptions(ctx, retryStream, forwardingOpts)
+		}
 		if collected.Error != "" {
-			result.Messages = copyMessages(messages)
-			return result, errors.New(collected.Error)
+			// Route a reissued stream's non-stall error through the SAME recovery as
+			// the initial stream (image-rejection wrapping / context-limit compaction)
+			// rather than returning it raw.
+			updated, stop := recoverStreamError(collected)
+			collected = updated
+			if stop != nil {
+				result.Messages = copyMessages(messages)
+				return result, stop
+			}
+			if collected.Error != "" {
+				result.Messages = copyMessages(messages)
+				return result, errors.New(collected.Error)
+			}
 		}
 
 		// Carry the turn's terminal stop reason so a final answer cut off at the
@@ -615,8 +675,20 @@ func historySafeToolCalls(calls []ToolCall) []ToolCall {
 	for i, call := range calls {
 		safe[i] = call
 		args := strings.TrimSpace(call.Arguments)
-		if args == "" || !json.Valid([]byte(args)) {
+		switch {
+		case args == "":
 			safe[i].Arguments = "{}"
+		case json.Valid([]byte(args)):
+			// already a single valid JSON value — keep as-is
+		default:
+			// Recover the first object for the concatenated case so the replayed
+			// transcript matches what executeToolCall actually ran; otherwise (real
+			// corruption) fall back to an empty object.
+			if first, ok := recoverableToolArguments(args); ok {
+				safe[i].Arguments = first
+			} else {
+				safe[i].Arguments = "{}"
+			}
 		}
 	}
 	return safe
@@ -641,10 +713,53 @@ func toolSchemaJSON(registry *tools.Registry, name string) string {
 // is a non-nil ABORT error only when the call demands the whole run stop (a
 // canceled/timed-out ask_user prompt) rather than continuing — every ordinary
 // success or tool error returns a nil abort error.
+// recoverableToolArguments inspects a tool call's raw JSON arguments. It returns
+// the raw text of the FIRST JSON value when the payload is one value optionally
+// followed by additional WHOLE JSON values (the weak-model concatenated case, e.g.
+// `{A}{B}`). ok is false when the payload is genuinely malformed: a bad/truncated
+// first value, OR trailing NON-JSON garbage after a valid first value (e.g.
+// `{"x":1}xyz`) — that case must still error, not be silently accepted. Sharing
+// this between dispatch and replay-history keeps them consistent: only a cleanly
+// recoverable first object is ever used.
+func recoverableToolArguments(arguments string) (first string, ok bool) {
+	dec := json.NewDecoder(strings.NewReader(arguments))
+	var head json.RawMessage
+	if err := dec.Decode(&head); err != nil {
+		return "", false
+	}
+	// The remainder must be only whole JSON values (or nothing); any decode error
+	// other than EOF means trailing garbage — reject so corruption still surfaces.
+	for {
+		var rest json.RawMessage
+		if err := dec.Decode(&rest); err != nil {
+			if errors.Is(err, io.EOF) {
+				return strings.TrimSpace(string(head)), true
+			}
+			return "", false
+		}
+	}
+}
+
+// decodeToolArguments decodes a tool call's JSON arguments into v. It tolerates a
+// weaker model that packs MULTIPLE concatenated top-level JSON objects into one
+// arguments string (`{A}{B}`) — the cause of "invalid character '{' after top-level
+// value" failures with small models like minimax-m3 — by decoding the FIRST object
+// and ignoring the trailing WHOLE JSON values, so the primary intended call runs.
+// A genuinely malformed payload (bad/truncated first object, or non-JSON trailing
+// garbage) still returns the real parse error; a standard single-object payload
+// decodes exactly as before.
+func decodeToolArguments(arguments string, v any) error {
+	if first, ok := recoverableToolArguments(arguments); ok {
+		return json.Unmarshal([]byte(first), v)
+	}
+	// Not cleanly recoverable — surface the genuine parse error.
+	return json.Unmarshal([]byte(arguments), v)
+}
+
 func executeToolCall(ctx context.Context, registry *tools.Registry, call ToolCall, permissionMode PermissionMode, options Options) (ToolResult, error) {
 	args := map[string]any{}
 	if call.Arguments != "" {
-		if err := json.Unmarshal([]byte(call.Arguments), &args); err != nil {
+		if err := decodeToolArguments(call.Arguments, &args); err != nil {
 			return ToolResult{
 				ToolCallID: call.ID,
 				Name:       call.Name,

internal/agent/loop_test.go

@@ -1053,7 +1053,10 @@ func TestRunSanitizesMalformedToolCallArgumentsBeforeRetry(t *testing.T) {
 		turns: [][]zeroruntime.StreamEvent{
 			{
 				{Type: zeroruntime.StreamEventToolCallStart, ToolCallID: "call-1", ToolName: "read_file"},
-				{Type: zeroruntime.StreamEventToolCallDelta, ToolCallID: "call-1", ArgumentsFragment: `{"path":"README.md"}{"path":"AGENTS.md"}`},
+				// Genuinely malformed (truncated) args: still error -> sanitize -> retry.
+				// (Concatenated multi-object args are now tolerated; see
+				// TestRunRecoversFirstObjectFromConcatenatedToolArgs.)
+				{Type: zeroruntime.StreamEventToolCallDelta, ToolCallID: "call-1", ArgumentsFragment: `{"path":"README.md"`},
 				{Type: zeroruntime.StreamEventToolCallEnd, ToolCallID: "call-1"},
 				{Type: zeroruntime.StreamEventDone},
 			},
@@ -1103,6 +1106,53 @@ func TestRunSanitizesMalformedToolCallArgumentsBeforeRetry(t *testing.T) {
 	}
 }
 
+// A weak model (e.g. minimax-m3) that packs MULTIPLE concatenated JSON objects into
+// one tool-call slot must RECOVER the first object and run the call, not fail with
+// "invalid character '{' after top-level value". The trailing object(s) are dropped
+// (the model re-issues them on a later turn if still needed).
+func TestRunRecoversFirstObjectFromConcatenatedToolArgs(t *testing.T) {
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "README.md"), []byte("hello readme"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	registry := tools.NewRegistry()
+	registry.Register(tools.NewReadFileTool(root))
+	provider := &mockProvider{
+		turns: [][]zeroruntime.StreamEvent{
+			{
+				{Type: zeroruntime.StreamEventToolCallStart, ToolCallID: "call-1", ToolName: "read_file"},
+				{Type: zeroruntime.StreamEventToolCallDelta, ToolCallID: "call-1", ArgumentsFragment: `{"path":"README.md"}{"path":"AGENTS.md"}`},
+				{Type: zeroruntime.StreamEventToolCallEnd, ToolCallID: "call-1"},
+				{Type: zeroruntime.StreamEventDone},
+			},
+			{
+				{Type: zeroruntime.StreamEventText, Content: "done"},
+				{Type: zeroruntime.StreamEventDone},
+			},
+		},
+	}
+
+	result, err := Run(context.Background(), "read", provider, Options{Registry: registry, MaxTurns: 2})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.FinalAnswer != "done" {
+		t.Fatalf("final answer = %q, want done", result.FinalAnswer)
+	}
+	var toolResult string
+	for _, message := range provider.requests[1].Messages {
+		if message.Role == zeroruntime.MessageRoleTool {
+			toolResult = message.Content
+		}
+	}
+	if strings.Contains(toolResult, "Failed to parse arguments") {
+		t.Fatalf("concatenated args should recover the first object, not fail to parse: %q", toolResult)
+	}
+	if !strings.Contains(toolResult, "hello readme") {
+		t.Fatalf("expected README.md contents (the first object's path), got %q", toolResult)
+	}
+}
+
 func TestRunDefersSelfCorrectFeedbackUntilAfterToolBatch(t *testing.T) {
 	// A single assistant turn with two tool calls where the first mutates and
 	// self-correct fails must keep both tool_results contiguous, with the feedback

internal/agent/stall_retry_test.go

@@ -0,0 +1,122 @@
+package agent
+
+import (
+	"context"
+	"sync/atomic"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/tools"
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+// stallProvider connects successfully (HTTP 200) but the stream emits a stall/idle
+// timeout error for the first stallBefore calls, then succeeds with "done". When
+// partialText is set it emits that text BEFORE the stall, simulating a stall after
+// partial output (which must NOT be retried — re-issuing would duplicate it).
+type stallProvider struct {
+	calls         int32
+	stallBefore   int32
+	partialText   string
+	reasoningText string
+}
+
+func (p *stallProvider) StreamCompletion(_ context.Context, _ zeroruntime.CompletionRequest) (<-chan zeroruntime.StreamEvent, error) {
+	n := atomic.AddInt32(&p.calls, 1)
+	ch := make(chan zeroruntime.StreamEvent, 3)
+	if n <= p.stallBefore {
+		if p.partialText != "" {
+			ch <- zeroruntime.StreamEvent{Type: zeroruntime.StreamEventText, Content: p.partialText}
+		}
+		if p.reasoningText != "" {
+			ch <- zeroruntime.StreamEvent{Type: zeroruntime.StreamEventReasoning, Content: p.reasoningText}
+		}
+		ch <- zeroruntime.StreamEvent{
+			Type:  zeroruntime.StreamEventError,
+			Error: "provider stream error: no output for 10m (the model produced nothing)",
+		}
+		close(ch)
+		return ch, nil
+	}
+	ch <- zeroruntime.StreamEvent{Type: zeroruntime.StreamEventText, Content: "done"}
+	ch <- zeroruntime.StreamEvent{Type: zeroruntime.StreamEventDone}
+	close(ch)
+	return ch, nil
+}
+
+// A no-output stall is re-issued on a fresh connection and recovers — this is the
+// macOS stale-pooled-connection hang turned into an automatic recovery.
+func TestRunRetriesStreamStallWithNoOutput(t *testing.T) {
+	p := &stallProvider{stallBefore: 1}
+	result, err := Run(context.Background(), "go", p, Options{Registry: tools.NewRegistry()})
+	if err != nil {
+		t.Fatalf("a no-output stall should retry to success, got %v", err)
+	}
+	if result.FinalAnswer != "done" {
+		t.Fatalf("final answer = %q, want %q", result.FinalAnswer, "done")
+	}
+	if got := atomic.LoadInt32(&p.calls); got != 2 {
+		t.Fatalf("want 2 calls (1 stall + 1 retry), got %d", got)
+	}
+}
+
+// A stall AFTER partial output must NOT be retried — re-issuing would duplicate
+// the already-streamed text. It surfaces the error instead.
+func TestRunDoesNotRetryStallAfterPartialOutput(t *testing.T) {
+	p := &stallProvider{stallBefore: 1, partialText: "partial"}
+	_, err := Run(context.Background(), "go", p, Options{Registry: tools.NewRegistry()})
+	if err == nil {
+		t.Fatal("a stall after partial output must NOT be retried; want an error")
+	}
+	if got := atomic.LoadInt32(&p.calls); got != 1 {
+		t.Fatalf("partial-then-stall must not retry, got %d calls", got)
+	}
+}
+
+// A stall after only REASONING was forwarded (no text/tool-calls) must NOT be
+// retried: the user already saw the reasoning, so re-issuing with callbacks
+// re-enabled would duplicate it. collected.Text is empty here, so this exercises
+// the turn-level forwarded-output gate specifically, not the text check.
+func TestRunDoesNotRetryStallAfterForwardedReasoning(t *testing.T) {
+	p := &stallProvider{stallBefore: 1, reasoningText: "thinking hard"}
+	_, err := Run(context.Background(), "go", p, Options{
+		Registry:    tools.NewRegistry(),
+		OnReasoning: func(string) {},
+	})
+	if err == nil {
+		t.Fatal("a stall after forwarded reasoning must NOT be retried; want an error")
+	}
+	if got := atomic.LoadInt32(&p.calls); got != 1 {
+		t.Fatalf("reasoning-then-stall must not retry, got %d calls", got)
+	}
+}
+
+// A persistent stall surfaces an error after exhausting the capped retries.
+func TestRunGivesUpAfterMaxStallRetries(t *testing.T) {
+	p := &stallProvider{stallBefore: 99}
+	_, err := Run(context.Background(), "go", p, Options{Registry: tools.NewRegistry()})
+	if err == nil {
+		t.Fatal("a persistent stall must surface an error after exhausting retries")
+	}
+	if got := atomic.LoadInt32(&p.calls); got != int32(1+maxStreamStallRetries) {
+		t.Fatalf("want %d calls (1 + %d retries), got %d", 1+maxStreamStallRetries, maxStreamStallRetries, got)
+	}
+}
+
+func TestIsStreamTimeoutError(t *testing.T) {
+	timeouts := []string{
+		"provider stream error: no output for 10m (the model produced nothing)",
+		"provider stream error: idle timeout after 5m0s (upstream stopped sending data)",
+		"stream stalled (upstream kept the connection alive but produced no output)",
+	}
+	for _, m := range timeouts {
+		if !isStreamTimeoutError(m) {
+			t.Fatalf("want timeout-classified: %q", m)
+		}
+	}
+	notTimeouts := []string{"", "context length exceeded", "rate limit error: slow down", "model not found"}
+	for _, m := range notTimeouts {
+		if isStreamTimeoutError(m) {
+			t.Fatalf("must NOT classify as timeout: %q", m)
+		}
+	}
+}

internal/config/active_provider_env_test.go

@@ -0,0 +1,49 @@
+package config
+
+import (
+	"os"
+	"testing"
+)
+
+// SetActiveProviderEnv must export the provider name so a child process (whose
+// resolution reads the inherited environment via the nil-map -> os.Getenv path in
+// applyEnv) resolves the SAME active provider. A blank name CLEARS it.
+func TestSetActiveProviderEnvRoundTrips(t *testing.T) {
+	t.Setenv(ActiveProviderEnv, "") // register cleanup; restores the original after
+
+	if err := os.Unsetenv(ActiveProviderEnv); err != nil {
+		t.Fatalf("unset: %v", err)
+	}
+	SetActiveProviderEnv("") // blank with nothing set stays unset
+	if got := os.Getenv(ActiveProviderEnv); got != "" {
+		t.Fatalf("empty name set the env to %q, want unset", got)
+	}
+
+	// Regression: switching from a named provider back to an unnamed/default profile
+	// must CLEAR a previously exported value, not leave it stale for children.
+	if err := os.Setenv(ActiveProviderEnv, "stale-provider"); err != nil {
+		t.Fatalf("seed stale: %v", err)
+	}
+	SetActiveProviderEnv("") // blank must unset the stale value
+	if got := os.Getenv(ActiveProviderEnv); got != "" {
+		t.Fatalf("blank name left stale env %q, want cleared", got)
+	}
+	cfgStale := &FileConfig{}
+	applyEnv(cfgStale, nil)
+	if cfgStale.ActiveProvider != "" {
+		t.Fatalf("applyEnv still resolved stale provider %q after clear", cfgStale.ActiveProvider)
+	}
+
+	SetActiveProviderEnv("ollama-cloud")
+	if got := os.Getenv(ActiveProviderEnv); got != "ollama-cloud" {
+		t.Fatalf("env = %q, want ollama-cloud", got)
+	}
+
+	// applyEnv with a nil map is the exact path a child uses: it falls back to
+	// os.Getenv, so the inherited value selects the active provider.
+	cfg := &FileConfig{}
+	applyEnv(cfg, nil)
+	if cfg.ActiveProvider != "ollama-cloud" {
+		t.Fatalf("applyEnv ActiveProvider = %q, want ollama-cloud (inherited env not read)", cfg.ActiveProvider)
+	}
+}

internal/config/max_turns_env_test.go

@@ -0,0 +1,56 @@
+package config
+
+import (
+	"os"
+	"testing"
+)
+
+// SetMaxTurnsEnv must export the per-run turn budget so a child process (whose
+// resolution reads the inherited environment via the nil-map -> os.Getenv path in
+// applyEnv) runs with the SAME budget the user set via /turns. n <= 0 is a no-op,
+// and a non-numeric/zero env value must not clobber the configured budget.
+func TestSetMaxTurnsEnvRoundTrips(t *testing.T) {
+	t.Setenv(MaxTurnsEnv, "") // register cleanup; restores the original after
+
+	if err := os.Unsetenv(MaxTurnsEnv); err != nil {
+		t.Fatalf("unset: %v", err)
+	}
+	SetMaxTurnsEnv(0) // non-positive must not set anything
+	if got := os.Getenv(MaxTurnsEnv); got != "" {
+		t.Fatalf("n<=0 set the env to %q, want unset", got)
+	}
+
+	SetMaxTurnsEnv(150)
+	if got := os.Getenv(MaxTurnsEnv); got != "150" {
+		t.Fatalf("env = %q, want 150", got)
+	}
+
+	// applyEnv with a nil map is the exact path a child uses: it falls back to
+	// os.Getenv, so the inherited value sets the budget.
+	cfg := &FileConfig{MaxTurns: defaultMaxTurns}
+	applyEnv(cfg, nil)
+	if cfg.MaxTurns != 150 {
+		t.Fatalf("applyEnv MaxTurns = %d, want 150 (inherited env not read)", cfg.MaxTurns)
+	}
+
+	// A garbage env value must leave the configured budget untouched.
+	if err := os.Setenv(MaxTurnsEnv, "not-a-number"); err != nil {
+		t.Fatalf("set: %v", err)
+	}
+	cfg2 := &FileConfig{MaxTurns: defaultMaxTurns}
+	applyEnv(cfg2, nil)
+	if cfg2.MaxTurns != defaultMaxTurns {
+		t.Fatalf("garbage env clobbered MaxTurns to %d, want default %d", cfg2.MaxTurns, defaultMaxTurns)
+	}
+
+	// An over-ceiling env value (e.g. a raw shell export that bypasses the /turns
+	// clamp) must be clamped to MaxTurnsCeiling at the read site.
+	if err := os.Setenv(MaxTurnsEnv, "999999"); err != nil {
+		t.Fatalf("set: %v", err)
+	}
+	cfg3 := &FileConfig{MaxTurns: defaultMaxTurns}
+	applyEnv(cfg3, nil)
+	if cfg3.MaxTurns != MaxTurnsCeiling {
+		t.Fatalf("applyEnv MaxTurns = %d, want clamped to ceiling %d", cfg3.MaxTurns, MaxTurnsCeiling)
+	}
+}

internal/config/resolver.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"net/url"
 	"os"
+	"strconv"
 	"strings"
 
 	"github.com/Gitlawb/zero/internal/modelregistry"
@@ -13,7 +14,15 @@ import (
 	"github.com/Gitlawb/zero/internal/sandbox"
 )
 
-const defaultMaxTurns = 30
+// defaultMaxTurns is the per-run tool-turn budget when none is configured. 30 was
+// too low for real multi-step agentic work (agents ran out mid-task before reaching
+// later steps); 50 matches the old "deep" preset. Raise per-session with /turns.
+const defaultMaxTurns = 50
+
+// MaxTurnsCeiling caps the per-run tool-turn budget so a stray env value or typo
+// can't set an absurd ceiling. Shared between applyEnv (read site) and the /turns
+// command (write site) so the bound holds even if the env is set by a raw shell.
+const MaxTurnsCeiling = 500
 
 // defaultDeferThreshold is the number of deferred-eligible (MCP) tools at which
 // Zero collapses their full JSON schemas into compact `tool_search` reminder
@@ -431,11 +440,53 @@ func mergeProfile(base ProviderProfile, next ProviderProfile) ProviderProfile {
 	return base
 }
 
+// ActiveProviderEnv selects the active provider profile by name (read in applyEnv).
+const ActiveProviderEnv = "ZERO_PROVIDER"
+
+// SetActiveProviderEnv exports the active provider name to the process environment
+// so a spawned child process (which inherits the environment) resolves the SAME
+// provider profile — and therefore the same credentials (env key / stored key /
+// OAuth) — as its parent. Without this a sub-agent re-resolves config.json's
+// default provider and can land on one whose credentials don't match the parent's
+// live selection, failing auth the instant it spawns. A blank name CLEARS the
+// variable: switching back to an unnamed/default profile must not keep exporting a
+// stale provider to children.
+func SetActiveProviderEnv(name string) {
+	name = strings.TrimSpace(name)
+	if name == "" {
+		_ = os.Unsetenv(ActiveProviderEnv)
+		return
+	}
+	_ = os.Setenv(ActiveProviderEnv, name)
+}
+
+// MaxTurnsEnv overrides the per-run tool-turn budget by name (read in applyEnv).
+const MaxTurnsEnv = "ZERO_MAX_TURNS"
+
+// SetMaxTurnsEnv exports the per-run tool-turn budget to the process environment so
+// a spawned child (sub-agent / swarm member, which inherits the environment) runs
+// with the SAME budget the user set via /turns. Without it a child re-resolves
+// config.json's default and a large delegated task can exhaust its turns mid-run
+// (exit 4 / max-turns). No-op for n <= 0.
+func SetMaxTurnsEnv(n int) {
+	if n > 0 {
+		_ = os.Setenv(MaxTurnsEnv, strconv.Itoa(n))
+	}
+}
+
 func applyEnv(cfg *FileConfig, env map[string]string) {
-	activeProvider := strings.TrimSpace(envValue(env, "ZERO_PROVIDER"))
+	activeProvider := strings.TrimSpace(envValue(env, ActiveProviderEnv))
 	if activeProvider != "" {
 		cfg.ActiveProvider = activeProvider
 	}
+	if maxTurns := strings.TrimSpace(envValue(env, MaxTurnsEnv)); maxTurns != "" {
+		if n, err := strconv.Atoi(maxTurns); err == nil && n > 0 {
+			if n > MaxTurnsCeiling {
+				n = MaxTurnsCeiling
+			}
+			cfg.MaxTurns = n
+		}
+	}
 
 	applyProviderEnv(cfg, ProviderKindOpenAI, envProfile{
 		Name:    string(ProviderKindOpenAI),

internal/config/resolver_test.go

@@ -883,8 +883,8 @@ func TestResolveAllowsNoConfiguredProviders(t *testing.T) {
 	if HasProviderProfile(resolved.Provider) {
 		t.Fatalf("Provider = %#v, want zero value", resolved.Provider)
 	}
-	if resolved.MaxTurns != 30 {
-		t.Fatalf("MaxTurns = %d, want 30", resolved.MaxTurns)
+	if resolved.MaxTurns != defaultMaxTurns {
+		t.Fatalf("MaxTurns = %d, want default %d", resolved.MaxTurns, defaultMaxTurns)
 	}
 }
 

internal/providers/anthropic/provider.go

@@ -211,11 +211,11 @@ func (provider *Provider) stream(ctx context.Context, body []byte, events chan<-
 	err = providerio.ScanSSEDataWithContext(streamCtx, cancelStream, response.Body, provider.streamIdleTimeout, func(data string) bool {
 		return provider.emitPayload(ctx, data, state, events)
 	})
-	if errors.Is(err, providerio.ErrStreamIdle) {
+	if errors.Is(err, providerio.ErrStreamIdle) || errors.Is(err, providerio.ErrStreamStalled) {
 		state.closeOpen(ctx, events)
 		providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{
 			Type:  zeroruntime.StreamEventError,
-			Error: provider.redact(fmt.Sprintf("provider stream error: idle timeout after %s (upstream stopped sending data)", provider.streamIdleTimeout)),
+			Error: provider.redact("provider stream error: " + providerio.StreamTimeoutMessage(err, provider.streamIdleTimeout)),
 		})
 		return
 	}

internal/providers/factory_test.go

@@ -264,6 +264,13 @@ func TestNewRejectsUnsupportedProviderKind(t *testing.T) {
 }
 
 func TestNewRoutesChatGPTCatalogToCodexProvider(t *testing.T) {
+	// Isolate the OAuth token store to an empty temp path so the factory reads no
+	// stored login — otherwise this test picks up the developer's real chatgpt
+	// OAuth token and the "want empty chatgpt-account-id" assertion fails locally
+	// (it still passes in CI, where no login is stored). Mirrors the isolation in
+	// TestNewRoutesChatGPTCatalogWithStoredAccountID.
+	t.Setenv("ZERO_OAUTH_TOKENS_PATH", t.TempDir()+"/tokens.json")
+
 	transport := &captureTransport{
 		responseBody: "data: [DONE]\n\n",
 	}

internal/providers/gemini/provider.go

@@ -158,10 +158,10 @@ func (provider *Provider) stream(ctx context.Context, body []byte, events chan<-
 	err = providerio.ScanSSEDataWithContext(streamCtx, cancelStream, response.Body, provider.streamIdleTimeout, func(data string) bool {
 		return provider.emitPayload(ctx, data, &state, events)
 	})
-	if errors.Is(err, providerio.ErrStreamIdle) {
+	if errors.Is(err, providerio.ErrStreamIdle) || errors.Is(err, providerio.ErrStreamStalled) {
 		providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{
 			Type:  zeroruntime.StreamEventError,
-			Error: provider.redact(fmt.Sprintf("provider stream error: idle timeout after %s (upstream stopped sending data)", provider.streamIdleTimeout)),
+			Error: provider.redact("provider stream error: " + providerio.StreamTimeoutMessage(err, provider.streamIdleTimeout)),
 		})
 		return
 	}

internal/providers/openai/codex_responses.go

@@ -389,10 +389,10 @@ func (p *CodexProvider) streamResponses(
 	err = providerio.ScanSSEDataWithContext(streamCtx, cancelStream, response.Body, inner.streamIdleTimeout, func(data string) bool {
 		return p.emitResponsesEvent(ctx, data, state, events)
 	})
-	if errors.Is(err, providerio.ErrStreamIdle) {
+	if errors.Is(err, providerio.ErrStreamIdle) || errors.Is(err, providerio.ErrStreamStalled) {
 		providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{
 			Type:  zeroruntime.StreamEventError,
-			Error: p.redact(fmt.Sprintf("provider stream error: idle timeout after %s (upstream stopped sending data)", inner.streamIdleTimeout)),
+			Error: p.redact("provider stream error: " + providerio.StreamTimeoutMessage(err, inner.streamIdleTimeout)),
 		})
 		return
 	}

internal/providers/openai/provider.go

@@ -102,10 +102,11 @@ func New(options Options) (*Provider, error) {
 		endpoint = baseURL + "/chat/completions"
 	}
 
-	httpClient := options.HTTPClient
-	if httpClient == nil {
-		httpClient = http.DefaultClient
-	}
+	// Route through providerio.HTTPClient so a missing client gets the shared,
+	// stall-hardened transport (bounded response-header wait + shorter idle-conn
+	// reuse) rather than the raw http.DefaultClient, which hangs on a reused-dead
+	// pooled connection (the macOS-only "both providers stall" bug).
+	httpClient := providerio.HTTPClient(options.HTTPClient)
 
 	maxTokens := options.MaxTokens
 	if maxTokens < 0 {
@@ -218,12 +219,12 @@ func (provider *Provider) stream(ctx context.Context, body []byte, events chan<-
 	err = providerio.ScanSSEDataWithContext(streamCtx, cancelStream, response.Body, provider.streamIdleTimeout, func(data string) bool {
 		return provider.emitPayload(ctx, data, state, events)
 	})
-	if errors.Is(err, providerio.ErrStreamIdle) {
+	if errors.Is(err, providerio.ErrStreamIdle) || errors.Is(err, providerio.ErrStreamStalled) {
 		state.flushBufferedContent(events)
 		state.closeBufferedOpen(events)
 		sendEvent(ctx, events, zeroruntime.StreamEvent{
 			Type:  zeroruntime.StreamEventError,
-			Error: provider.redact(fmt.Sprintf("provider stream error: idle timeout after %s (upstream stopped sending data)", provider.streamIdleTimeout)),
+			Error: provider.redact("provider stream error: " + providerio.StreamTimeoutMessage(err, provider.streamIdleTimeout)),
 		})
 		return
 	}

internal/providers/providerio/providerio.go

@@ -23,6 +23,26 @@ const maxSSELineBytes = 16 * 1024 * 1024
 // closing the connection. Callers surface it as an idle-timeout error.
 var ErrStreamIdle = errors.New("idle timeout (upstream stopped sending data)")
 
+// ErrStreamStalled reports that a streaming upstream kept the connection alive
+// (SSE keep-alives reset the idle watchdog, so it never fired) but produced no
+// actual output for streamContentStallFactor × the idle timeout. Without this an
+// upstream that heartbeats-but-stalls — observed on chatgpt/gpt-5.x and ollama
+// reasoning models — would hang the agent indefinitely.
+var ErrStreamStalled = errors.New("stream stalled (upstream kept the connection alive but produced no output)")
+
+// StreamTimeoutMessage returns the human-readable detail for a stream-timeout
+// error (ErrStreamIdle or ErrStreamStalled), given the configured idle timeout.
+// Callers prepend their own "provider stream error: " prefix. A stalled stream
+// gets a distinct, actionable message — it did NOT stop sending data (keep-alives
+// kept arriving); it just produced no output, which usually means the model is
+// stuck or very slow.
+func StreamTimeoutMessage(err error, idleTimeout time.Duration) string {
+	if errors.Is(err, ErrStreamStalled) {
+		return fmt.Sprintf("no output for %s (the model kept the connection alive but produced nothing — it may be stuck; try a faster model or lower reasoning effort)", idleTimeout*streamContentStallFactor)
+	}
+	return fmt.Sprintf("idle timeout after %s (upstream stopped sending data)", idleTimeout)
+}
+
 // DefaultStreamIdleTimeout is the single source of truth for how long every
 // provider waits on a silent stream before aborting it. The watchdog only fires
 // on genuine silence — SSE keep-alive comments reset it (see
@@ -33,6 +53,14 @@ var ErrStreamIdle = errors.New("idle timeout (upstream stopped sending data)")
 // Override globally with ZERO_STREAM_IDLE_TIMEOUT.
 const DefaultStreamIdleTimeout = 5 * time.Minute
 
+// streamContentStallFactor bounds a heartbeat-but-no-output stream. Keep-alives
+// reset the idle watchdog (a heartbeating upstream is not "dead"), but if NO real
+// data line arrives for streamContentStallFactor × the idle timeout, the stream is
+// treated as stalled and aborted (ErrStreamStalled). It is > 1 so a slow-but-
+// producing request — one that emits data between heartbeats — is never killed; the
+// content watchdog only catches a stream that heartbeats while producing nothing.
+const streamContentStallFactor = 2
+
 // streamIdleTimeoutEnv is the global override for the stream idle timeout. It
 // accepts a Go duration ("5m", "300s", "90s") or a bare number of seconds
 // ("300"). A value of "0", "off", "none", or "disabled" turns the watchdog off
@@ -77,12 +105,42 @@ func NormalizeBaseURL(baseURL string, defaultBaseURL string, label string) (stri
 	return baseURL, nil
 }
 
-// HTTPClient returns the configured client or the process default.
+// sharedHTTPClient is the process-wide client used when a provider supplies none.
+// It tunes the default transport to defeat the stale-pooled-connection hang: Go
+// keeps idle keep-alive connections in a pool, and a later request can reuse one
+// the server/NAT has silently dropped. Because the model call is a POST (non-
+// idempotent), Go will NOT auto-retry it on a fresh connection — so it blocks
+// forever waiting for a response that never arrives. This is provider-agnostic
+// (every provider shares the default transport), which is why it reproduced on
+// BOTH chatgpt and ollama, and it surfaces on macOS far more than Linux because
+// macOS keeps dead pooled connections around longer.
+//
+//   - ResponseHeaderTimeout bounds the gap between finishing the request and the
+//     first response header, so a reused-dead connection fails fast (then the
+//     reconnect path re-dials) instead of hanging. It does NOT bound streaming
+//     after the 200 header arrives, so slow first tokens / long reasoning are
+//     unaffected (the stream-idle + content watchdogs cover that).
+//   - IdleConnTimeout is shortened so a connection that went idle across a pause
+//     is closed (and re-dialed fresh) rather than reused after it has gone stale.
+var sharedHTTPClient = func() *http.Client {
+	transport := http.DefaultTransport.(*http.Transport).Clone()
+	// 120s, not 60s: a slow cloud proxy (e.g. ollama `*:cloud`) can withhold its
+	// 200 response header until the upstream model emits a first token, so a 60s cap
+	// risked aborting a legitimately-slow-but-alive request. 120s still bounds a
+	// truly dead reused connection (which never responds) while tolerating slow
+	// header delivery; slow first tokens after the header are covered by the idle +
+	// content-stall watchdogs.
+	transport.ResponseHeaderTimeout = 120 * time.Second
+	transport.IdleConnTimeout = 30 * time.Second
+	return &http.Client{Transport: transport}
+}()
+
+// HTTPClient returns the configured client or the shared, stall-hardened default.
 func HTTPClient(client *http.Client) *http.Client {
 	if client != nil {
 		return client
 	}
-	return http.DefaultClient
+	return sharedHTTPClient
 }
 
 // SendEvent writes a provider event without blocking cancellation cleanup.
@@ -202,21 +260,36 @@ func ScanSSEDataWithContext(
 	// The idle watchdog is optional. When idleTimeout <= 0 it is disabled, but we
 	// STILL run the goroutine + select loop so ctx cancellation is always honored
 	// (a nil idleC channel simply never fires in the select).
-	var idleC <-chan time.Time
+	var idleC, contentC <-chan time.Time
 	resetIdle := func() {}
+	resetContent := func() {}
 	if idleTimeout > 0 {
+		// reset drains the timer's channel if it already fired before re-arming, so
+		// a stale tick can't trip the watchdog after activity resumed.
+		reset := func(t *time.Timer, d time.Duration) func() {
+			return func() {
+				if !t.Stop() {
+					select {
+					case <-t.C:
+					default:
+					}
+				}
+				t.Reset(d)
+			}
+		}
 		idle := time.NewTimer(idleTimeout)
 		defer idle.Stop()
 		idleC = idle.C
-		resetIdle = func() {
-			if !idle.Stop() {
-				select {
-				case <-idle.C:
-				default:
-				}
-			}
-			idle.Reset(idleTimeout)
-		}
+		resetIdle = reset(idle, idleTimeout)
+
+		// Content watchdog: only real data lines reset it (keep-alives do not), so a
+		// stream that heartbeats without producing output is bounded instead of
+		// hanging forever.
+		contentTimeout := idleTimeout * streamContentStallFactor
+		content := time.NewTimer(contentTimeout)
+		defer content.Stop()
+		contentC = content.C
+		resetContent = reset(content, contentTimeout)
 	}
 
 	for {
@@ -232,6 +305,12 @@ func ScanSSEDataWithContext(
 			// a timeout instead of blocking the agent forever.
 			cancel()
 			return ErrStreamIdle
+		case <-contentC:
+			// Upstream kept heartbeating (idle watchdog never fired) but produced
+			// no output for the content window. Treat as stalled and abort rather
+			// than hanging forever.
+			cancel()
+			return ErrStreamStalled
 		case item, ok := <-payloads:
 			if !ok {
 				// Reader finished: deliver its terminal status (EOF -> nil,
@@ -246,8 +325,11 @@ func ScanSSEDataWithContext(
 			}
 			resetIdle()
 			if item.keepAlive {
+				// A heartbeat keeps the connection "alive" (idle watchdog) but is
+				// NOT output, so it must not reset the content watchdog.
 				continue
 			}
+			resetContent()
 			if !handle(item.data) {
 				// The provider asked to stop (e.g. it already emitted an error
 				// for this payload). Abort the read and end like ScanSSEData:

internal/providers/providerio/providerio_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"io"
+	"net/http"
 	"strings"
 	"testing"
 	"time"
@@ -201,3 +202,133 @@ func TestUpstreamUnreachable(t *testing.T) {
 		})
 	}
 }
+
+// A heartbeating-but-output-less upstream must not hang forever: SSE keep-alives
+// feed the idle watchdog (so it never fires), but the content watchdog
+// (idleTimeout × streamContentStallFactor) aborts with ErrStreamStalled when no
+// real data line arrives. This is the gpt-5.x / ollama "still generating forever"
+// hang.
+func TestScanSSEDataWithContextAbortsOnContentStall(t *testing.T) {
+	pr, pw := io.Pipe()
+	defer func() { _ = pw.Close() }()
+
+	stop := make(chan struct{})
+	defer close(stop)
+	go func() {
+		// Heartbeat every 30ms — comfortably under the 100ms idle timeout, so idle
+		// never fires under CI/GC jitter — but never send a data line.
+		for {
+			select {
+			case <-stop:
+				return
+			default:
+			}
+			if _, err := io.WriteString(pw, ": keep-alive\n\n"); err != nil {
+				return
+			}
+			time.Sleep(30 * time.Millisecond)
+		}
+	}()
+
+	cancelled := false
+	cancel := func() { cancelled = true }
+
+	done := make(chan error, 1)
+	go func() {
+		// idle 100ms → content stall at 200ms. Keep-alives reset idle but not content.
+		done <- ScanSSEDataWithContext(context.Background(), cancel, pr, 100*time.Millisecond, func(string) bool { return true })
+	}()
+
+	select {
+	case err := <-done:
+		if !errors.Is(err, ErrStreamStalled) {
+			t.Fatalf("err = %v, want ErrStreamStalled", err)
+		}
+	case <-time.After(3 * time.Second):
+		t.Fatal("ScanSSEDataWithContext hung on a heartbeat-but-no-output stream")
+	}
+	if !cancelled {
+		t.Fatal("content stall did not cancel the request context")
+	}
+}
+
+// Real data lines reset the content watchdog, so a slow-but-producing stream that
+// runs longer than the content window is never aborted.
+func TestScanSSEDataWithContextContentResetsOnData(t *testing.T) {
+	pr, pw := io.Pipe()
+
+	go func() {
+		// One data line every 30ms for ~300ms (well past the 200ms content window,
+		// with comfortable slack under the 100ms idle timeout), so the content
+		// watchdog keeps resetting, then close cleanly.
+		for i := 0; i < 10; i++ {
+			if _, err := io.WriteString(pw, "data: chunk\n\n"); err != nil {
+				return
+			}
+			time.Sleep(30 * time.Millisecond)
+		}
+		_ = pw.Close()
+	}()
+
+	n := 0
+	done := make(chan error, 1)
+	go func() {
+		done <- ScanSSEDataWithContext(context.Background(), func() {}, pr, 100*time.Millisecond, func(string) bool { n++; return true })
+	}()
+
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("err = %v, want nil (data kept the stream alive)", err)
+		}
+	case <-time.After(3 * time.Second):
+		t.Fatal("ScanSSEDataWithContext hung on a producing stream")
+	}
+	if n != 10 {
+		t.Fatalf("handled %d data lines, want 10", n)
+	}
+}
+
+// StreamTimeoutMessage must give a stalled stream a distinct, accurate detail —
+// it reports the content window (idle × factor) and must NOT claim the upstream
+// "stopped sending data" (keep-alives were still arriving).
+func TestStreamTimeoutMessage(t *testing.T) {
+	idle := 5 * time.Minute
+	if msg := StreamTimeoutMessage(ErrStreamIdle, idle); !strings.Contains(msg, "idle timeout after 5m") {
+		t.Fatalf("idle message = %q, want it to mention the 5m idle timeout", msg)
+	}
+	stalled := StreamTimeoutMessage(ErrStreamStalled, idle)
+	if !strings.Contains(stalled, "no output for 10m") {
+		t.Fatalf("stalled message = %q, want it to report the 10m content window", stalled)
+	}
+	if strings.Contains(stalled, "stopped sending data") {
+		t.Fatalf("stalled message must not claim the upstream stopped sending data: %q", stalled)
+	}
+}
+
+// HTTPClient(nil) must return the shared, stall-hardened transport (bounded
+// response-header wait + shorter idle-conn reuse) that defeats the macOS stale-
+// pooled-connection hang; an explicit client is returned untouched.
+func TestHTTPClientReturnsStallHardenedSharedClient(t *testing.T) {
+	got := HTTPClient(nil)
+	if got == nil {
+		t.Fatal("HTTPClient(nil) returned nil")
+	}
+	tr, ok := got.Transport.(*http.Transport)
+	if !ok {
+		t.Fatalf("transport type = %T, want *http.Transport", got.Transport)
+	}
+	if tr.ResponseHeaderTimeout != 120*time.Second {
+		t.Fatalf("ResponseHeaderTimeout = %v, want 120s", tr.ResponseHeaderTimeout)
+	}
+	if tr.IdleConnTimeout != 30*time.Second {
+		t.Fatalf("IdleConnTimeout = %v, want 30s", tr.IdleConnTimeout)
+	}
+	if HTTPClient(nil) != got {
+		t.Fatal("HTTPClient(nil) must return a shared instance so the conn pool is reused")
+	}
+	custom := &http.Client{}
+	if HTTPClient(custom) != custom {
+		t.Fatal("an explicit client must be returned unchanged")
+	}
+}

internal/specialist/exec.go

@@ -204,7 +204,11 @@ type ChildRunResult struct {
 	Events   []streamjson.Event
 	Stderr   string
 	ExitCode int
-	Started  bool
+	// Signal is a human-readable description (e.g. "signal: killed") when the child
+	// was terminated by a signal rather than exiting normally; empty otherwise. It
+	// turns an opaque exit -1 into an actionable reason (SIGKILL ~ out of memory).
+	Signal  string
+	Started bool
 }
 
 func (executor Executor) Run(ctx context.Context, params TaskParameters, options TaskRunOptions) (ExecResult, error) {
@@ -566,17 +570,35 @@ func (executor Executor) runBuiltArgs(ctx context.Context, built BuildArgsResult
 		exitCode := run.exitCodeOr(-1)
 		summary := SummarizeStream(run.Events, exitCode)
 		executor.recordSpecialistStop(accounting, summary, "error", summary.ExitCode, err, false)
-		return ExecResult{}, err
+		// Carry the child session id even on a post-start failure so a caller (the
+		// swarm launcher -> FailWithSession) can still make the failed member
+		// drillable; the session exists once the child has started.
+		return ExecResult{SessionID: built.SessionID}, err
 	}
 	summary := SummarizeStream(run.Events, run.ExitCode)
 	rolledUp := executor.rollUpSpecialistUsage(accounting, summary)
 	executor.recordSpecialistStop(accounting, summary, summary.Status, summary.ExitCode, nil, rolledUp)
 	return ExecResult{
-		Result:    BuildFinalResult(run.Events, run.Stderr, run.ExitCode),
+		Result:    BuildFinalResult(run.Events, run.Stderr, run.ExitCode, run.Signal),
 		SessionID: built.SessionID,
 	}, nil
 }
 
+// availableSpecialistList renders the registered specialist names for a corrective
+// "not found" error, so a model that guessed a wrong name learns the real options.
+func availableSpecialistList(result LoadResult) string {
+	names := make([]string, 0, len(result.Specialists))
+	for _, manifest := range result.Specialists {
+		if n := strings.TrimSpace(manifest.Metadata.Name); n != "" {
+			names = append(names, n)
+		}
+	}
+	if len(names) == 0 {
+		return "(none registered)"
+	}
+	return strings.Join(names, ", ")
+}
+
 func (executor Executor) loadManifest(name string) (Manifest, error) {
 	name = strings.TrimSpace(name)
 	if name == "" {
@@ -592,7 +614,12 @@ func (executor Executor) loadManifest(name string) (Manifest, error) {
 	}
 	manifest, ok := Find(result, name)
 	if !ok {
-		return Manifest{}, fmt.Errorf("specialist %q not found", name)
+		// Corrective error: a model that invents a specialist name (e.g.
+		// "validator-runner", "file-writer") otherwise gets an opaque "not found"
+		// and keeps retrying made-up names. List the ACTUALLY-registered ones so it
+		// self-corrects — no hardcoded names, since a custom registry may not have
+		// worker/explorer/code-review.
+		return Manifest{}, fmt.Errorf("specialist %q not found. Available: %s. Pick one of these whose tools fit the task, or omit the name to use the default", name, availableSpecialistList(result))
 	}
 	return manifest, nil
 }
@@ -783,15 +810,22 @@ func runChildProcess(ctx context.Context, binaryPath string, args []string, prog
 	}
 	exitCode := 0
 	started := true
+	signalDesc := ""
 	if err := command.Wait(); err != nil {
 		var exitErr *osexec.ExitError
 		if errors.As(err, &exitErr) {
 			exitCode = exitErr.ExitCode()
+			if exitCode < 0 && exitErr.ProcessState != nil {
+				// ExitCode() is -1 when the child was terminated by a signal rather
+				// than exiting. ProcessState.String() is the portable description
+				// (e.g. "signal: killed") — capture it so the failure isn't opaque.
+				signalDesc = exitErr.ProcessState.String()
+			}
 		} else {
 			return ChildRunResult{Events: events, Stderr: stderr.String(), ExitCode: -1, Started: started}, fmt.Errorf("run specialist child: %w", err)
 		}
 	}
-	return ChildRunResult{Events: events, Stderr: stderr.String(), ExitCode: exitCode, Started: started}, nil
+	return ChildRunResult{Events: events, Stderr: stderr.String(), ExitCode: exitCode, Signal: signalDesc, Started: started}, nil
 }
 
 func (run ChildRunResult) exitCodeOr(defaultExitCode int) int {

internal/specialist/load_manifest_error_test.go

@@ -0,0 +1,32 @@
+package specialist
+
+import (
+	"strings"
+	"testing"
+)
+
+// A model that invents a specialist name (e.g. "validator-runner", "file-writer")
+// must get a corrective error listing the real specialists, so it self-corrects to a
+// capable one instead of looping on made-up names that spawn doomed sub-agents.
+func TestLoadManifestUnknownNameListsAvailable(t *testing.T) {
+	executor := Executor{
+		Load: func(LoadOptions) (LoadResult, error) {
+			return LoadResult{Specialists: []Manifest{
+				{Metadata: Metadata{Name: "worker"}},
+				{Metadata: Metadata{Name: "explorer"}},
+				{Metadata: Metadata{Name: "code-review"}},
+			}}, nil
+		},
+	}
+
+	_, err := executor.loadManifest("validator-runner")
+	if err == nil {
+		t.Fatal("an unknown specialist name must error")
+	}
+	msg := err.Error()
+	for _, want := range []string{"validator-runner", "not found", "worker", "explorer", "code-review"} {
+		if !strings.Contains(msg, want) {
+			t.Fatalf("error %q missing %q (must steer the model to a real specialist)", msg, want)
+		}
+	}
+}

internal/specialist/output_tool.go

@@ -260,6 +260,12 @@ func formatTaskOutputSummary(task background.Task, summary StreamResult, rawLine
 	if !task.CompletedAt.IsZero() {
 		fmt.Fprintf(&builder, "completed_at: %s\n", task.CompletedAt.Format(time.RFC3339))
 		fmt.Fprintf(&builder, "exit_code: %d\n", task.ExitCode)
+		if task.ExitCode < 0 {
+			// A negative exit code means the background child was terminated by a
+			// signal rather than exiting (the int-only launcher can't carry the
+			// signal name). Give the same actionable hint the foreground path does.
+			builder.WriteString("note: terminated by a signal — killed before it finished. Likely causes: the OS out-of-memory killer (common when many sub-agents run in parallel — try fewer), a timeout, or cancellation.\n")
+		}
 	}
 
 	if summary.Text != "" {

internal/specialist/streamer.go

@@ -134,12 +134,17 @@ func SummarizeStream(events []streamjson.Event, processExitCode int) StreamResul
 	return result
 }
 
-func BuildFinalResult(events []streamjson.Event, stderrOutput string, processExitCode int) tools.Result {
+func BuildFinalResult(events []streamjson.Event, stderrOutput string, processExitCode int, signalDesc string) tools.Result {
 	summary := SummarizeStream(events, processExitCode)
 	hasErrors := len(summary.Errors) > 0 || summary.ExitCode != 0
 	if summary.Status != "" && summary.Status != "success" && summary.Status != "ok" {
 		hasErrors = true
 	}
+	// A captured kill signal must always surface, even if a late run_end reported a
+	// clean exit just before the child was killed during teardown.
+	if strings.TrimSpace(signalDesc) != "" {
+		hasErrors = true
+	}
 	if !hasErrors {
 		output := summary.Text
 		if summary.SessionID != "" {
@@ -149,7 +154,15 @@ func BuildFinalResult(events []streamjson.Event, stderrOutput string, processExi
 	}
 
 	var builder strings.Builder
-	fmt.Fprintf(&builder, "Subagent failed (exit %d)\n", summary.ExitCode)
+	if signal := strings.TrimSpace(signalDesc); signal != "" {
+		// The child was terminated by a signal (exit code -1) rather than exiting.
+		// Surface the signal instead of an opaque "exit -1", and list the common
+		// causes evenhandedly — this branch also covers timeouts and cancellations,
+		// so don't assert OOM.
+		fmt.Fprintf(&builder, "Subagent terminated by a signal (%s) — it was killed before it finished. Common causes: an out-of-memory kill, a timeout, or cancellation; check the signal to tell which. If you were running many sub-agents in parallel, reduce the concurrency.\n", signal)
+	} else {
+		fmt.Fprintf(&builder, "Subagent failed (exit %d)\n", summary.ExitCode)
+	}
 	if len(summary.Errors) > 0 {
 		fmt.Fprintf(&builder, "errors: %s\n", strings.Join(summary.Errors, "; "))
 	}

internal/specialist/streamer_test.go

@@ -25,7 +25,7 @@ func TestParseStreamAndBuildFinalResultSuccess(t *testing.T) {
 	if summary.SessionID != "child" || summary.Text != "done" || summary.ExitCode != 0 || len(summary.Tools) != 1 || summary.Tools[0] != "grep" {
 		t.Fatalf("unexpected summary: %#v", summary)
 	}
-	result := BuildFinalResult(events, "", 0)
+	result := BuildFinalResult(events, "", 0, "")
 	if result.Status != tools.StatusOK || result.Output != "session_id: child\ndone" {
 		t.Fatalf("unexpected final result: %#v", result)
 	}
@@ -41,7 +41,7 @@ func TestBuildFinalResultUsesTextDeltasWhenFinalMissing(t *testing.T) {
 	if err != nil {
 		t.Fatalf("ParseStream returned error: %v", err)
 	}
-	result := BuildFinalResult(events, "", 0)
+	result := BuildFinalResult(events, "", 0, "")
 	if result.Status != tools.StatusOK || result.Output != "session_id: child\nhello world" {
 		t.Fatalf("unexpected final result: %#v", result)
 	}
@@ -82,7 +82,7 @@ func TestBuildFinalResultErrorIncludesDiagnostics(t *testing.T) {
 	if err != nil {
 		t.Fatalf("ParseStream returned error: %v", err)
 	}
-	result := BuildFinalResult(events, "stderr text", 0)
+	result := BuildFinalResult(events, "stderr text", 0, "")
 	if result.Status != tools.StatusError {
 		t.Fatalf("Status = %s, want error", result.Status)
 	}
@@ -93,6 +93,33 @@ func TestBuildFinalResultErrorIncludesDiagnostics(t *testing.T) {
 	}
 }
 
+// A child terminated by a signal (exit code -1) must surface the signal + an
+// actionable hint, not an opaque "Subagent failed (exit -1)".
+func TestBuildFinalResultSurfacesKillSignal(t *testing.T) {
+	events, err := ParseStream(strings.NewReader(strings.Join([]string{
+		`{"schemaVersion":2,"type":"run_start","runId":"run_1","sessionId":"child"}`,
+		`{"schemaVersion":2,"type":"tool_call","runId":"run_1","id":"call_1","name":"read_file"}`,
+		"",
+	}, "\n")))
+	if err != nil {
+		t.Fatalf("ParseStream returned error: %v", err)
+	}
+	result := BuildFinalResult(events, "", -1, "signal: killed")
+	if result.Status != tools.StatusError {
+		t.Fatalf("Status = %s, want error", result.Status)
+	}
+	// Surfaces the signal + lists causes (OOM/timeout/cancellation) without asserting
+	// OOM as the sole cause.
+	for _, want := range []string{"terminated by a signal", "signal: killed", "out-of-memory", "timeout", "cancellation"} {
+		if !strings.Contains(result.Output, want) {
+			t.Fatalf("kill output missing %q:\n%s", want, result.Output)
+		}
+	}
+	if strings.Contains(result.Output, "Subagent failed (exit") {
+		t.Fatalf("signaled child should not show the opaque exit line:\n%s", result.Output)
+	}
+}
+
 func TestParseStreamRejectsInvalidLines(t *testing.T) {
 	_, err := ParseStream(strings.NewReader(`{"schemaVersion":2,"runId":"run_1"}` + "\n"))
 	if err == nil || !strings.Contains(err.Error(), "type is required") {

internal/swarm/coordinator.go

@@ -166,6 +166,12 @@ func (c *Coordinator) Fail(id, errMsg string) error {
 	return c.finish(id, StatusFailed, "", errMsg, "")
 }
 
+// FailWithSession marks a task failed but keeps its child session id, so a member
+// that ran and failed (e.g. exited non-zero / hit max-turns) is still drillable.
+func (c *Coordinator) FailWithSession(id, errMsg, sessionID string) error {
+	return c.finish(id, StatusFailed, "", errMsg, sessionID)
+}
+
 func (c *Coordinator) finish(id string, status TaskStatus, result, errMsg, sessionID string) error {
 	c.mu.Lock()
 	defer c.mu.Unlock()

internal/swarm/launcher_specialist.go

@@ -2,8 +2,10 @@ package swarm
 
 import (
 	"context"
+	"errors"
 
 	"github.com/Gitlawb/zero/internal/specialist"
+	"github.com/Gitlawb/zero/internal/tools"
 )
 
 // NewSpecialistLauncher adapts internal/specialist.Executor into a
@@ -54,7 +56,18 @@ func NewSpecialistLauncher(executor specialist.Executor) MemberLauncher {
 			MemberAutonomy: true,
 		})
 		if err != nil {
-			return MemberResult{}, err
+			// Preserve the child session id on a post-start failure too (exec.go
+			// returns it on the error path) so lifecycle's FailWithSession can keep
+			// the failed member drillable, not just the StatusError case below.
+			return MemberResult{SessionID: res.SessionID}, err
+		}
+		if res.Result.Status == tools.StatusError {
+			// The child ran but its task FAILED (e.g. non-zero exit / max-turns).
+			// Surface it as a member failure so the swarm marks it [failed], not
+			// [done] — otherwise the orchestrator (which can't see the AGENTS panel)
+			// trusts incomplete work. Keep the session id so the failed member is
+			// still drillable, and carry its report as the failure message.
+			return MemberResult{SessionID: res.SessionID}, errors.New(res.Result.Output)
 		}
 		return MemberResult{Result: res.Result.Output, SessionID: res.SessionID}, nil
 	}}

internal/swarm/launcher_specialist_test.go

@@ -67,3 +67,50 @@ func TestSpecialistLauncherRunsUnregisteredSwarmAgent(t *testing.T) {
 		t.Fatalf("member args missing agent type: %#v", gotArgs)
 	}
 }
+
+// A member whose child exits non-zero (e.g. exit 4 / max-turns) must be reported as
+// a FAILURE — otherwise the swarm marks it [done] and the orchestrator trusts
+// incomplete work. The failed member keeps its session id (drill-in) and the child
+// report rides along as the failure message.
+func TestSpecialistLauncherMarksNonZeroExitAsFailed(t *testing.T) {
+	four := 4
+	executor := specialist.Executor{
+		BinaryPath:   "/usr/local/bin/zero",
+		NewSessionID: func() (string, error) { return "member_task", nil },
+		Load: func(specialist.LoadOptions) (specialist.LoadResult, error) {
+			return specialist.LoadResult{}, nil
+		},
+		RunChild: func(ctx context.Context, binaryPath string, args []string, progress func(streamjson.Event)) (specialist.ChildRunResult, error) {
+			return specialist.ChildRunResult{
+				Events: []streamjson.Event{
+					{Type: streamjson.EventRunStart, SessionID: "member_task"},
+					{Type: streamjson.EventFinal, Text: "i could not finish the objective"},
+					{Type: streamjson.EventRunEnd, Status: "error", ExitCode: &four},
+				},
+				ExitCode: 4,
+			}, nil
+		},
+	}
+
+	handle, err := NewSpecialistLauncher(executor).Launch(context.Background(), MemberSpec{
+		ID:           "m1",
+		TaskID:       "m1",
+		AgentType:    "subagent",
+		Team:         "probe",
+		Task:         "a task too big for the budget",
+		SystemPrompt: "You are a subagent spawned to complete a specific task.",
+	})
+	if err != nil {
+		t.Fatalf("launch: %v", err)
+	}
+	res, err := handle.Wait()
+	if err == nil {
+		t.Fatal("a member that exited non-zero must be reported as FAILED, got nil error")
+	}
+	if !strings.Contains(err.Error(), "exit 4") {
+		t.Fatalf("failure should carry the child report (exit 4), got %q", err.Error())
+	}
+	if res.SessionID != "member_task" {
+		t.Fatalf("a failed member must keep its session id for drill-in, got %q", res.SessionID)
+	}
+}

internal/swarm/lifecycle.go

@@ -71,7 +71,9 @@ func (s *Swarm) watch(t *Team, m *Member, spec MemberSpec) {
 			}
 			// fall through to record the original error if relaunch fails
 		}
-		_ = s.coord.Fail(m.TaskID, memberError(err))
+		// res.SessionID is preserved by the handle even on error, so a member that
+		// ran then failed stays drillable; a pure launch error carries an empty id.
+		_ = s.coord.FailWithSession(m.TaskID, memberError(err), res.SessionID)
 	} else {
 		_ = s.coord.CompleteWithSession(m.TaskID, res.Result, res.SessionID)
 	}

internal/swarm/tools.go

@@ -103,6 +103,25 @@ func errResult(format string, a ...any) tools.Result {
 	return tools.Result{Status: tools.StatusError, Output: "Error: " + fmt.Sprintf(format, a...)}
 }
 
+// agentTypeProperty builds the schema for an agent-type parameter, constraining it
+// to the roster's currently registered types (the built-ins plus any user-registered
+// agents) via an enum so a model can't spawn or hand off to an unknown type — the
+// schema teaches the valid set up front instead of the model learning it from a
+// failed call. Falls back to a free-form string if the roster is unavailable or
+// empty (so the tool never advertises an empty, un-satisfiable enum).
+func agentTypeProperty(sw *Swarm, description string) tools.PropertySchema {
+	prop := tools.PropertySchema{Type: "string", Description: description}
+	if sw == nil {
+		return prop
+	}
+	if registry := sw.Registry(); registry != nil {
+		if types := registry.AgentTypes(); len(types) > 0 {
+			prop.Enum = types
+		}
+	}
+	return prop
+}
+
 // ---- swarm_spawn -----------------------------------------------------------
 
 type spawnTool struct {
@@ -118,7 +137,7 @@ func (t *spawnTool) Parameters() tools.Schema {
 	return tools.Schema{
 		Type: "object",
 		Properties: map[string]tools.PropertySchema{
-			"agent_type": {Type: "string", Description: "Roster agent type to spawn (e.g. teammate, subagent)."},
+			"agent_type": agentTypeProperty(t.sw, "Roster agent type to spawn."),
 			"task":       {Type: "string", Description: "The focused task/briefing for the member."},
 			"team":       {Type: "string", Description: "Team to spawn into. Defaults to \"default\"."},
 		},
@@ -353,7 +372,7 @@ func (t *handoffTool) Parameters() tools.Schema {
 		Type: "object",
 		Properties: map[string]tools.PropertySchema{
 			"task_id":       {Type: "string", Description: "Task id to hand off."},
-			"to_agent_type": {Type: "string", Description: "Roster agent type to take over."},
+			"to_agent_type": agentTypeProperty(t.sw, "Roster agent type to take over."),
 			"note":          {Type: "string", Description: "Optional handoff note delivered to the new member's inbox."},
 			"team":          {Type: "string", Description: "Team the task belongs to. Defaults to \"default\"."},
 		},

internal/swarm/tools_test.go

@@ -2,6 +2,7 @@ package swarm
 
 import (
 	"context"
+	"slices"
 	"strings"
 	"testing"
 	"time"
@@ -10,6 +11,46 @@ import (
 	"github.com/Gitlawb/zero/internal/tools"
 )
 
+func TestSpawnAndHandoffAgentTypeEnumReflectsRoster(t *testing.T) {
+	sw := newSwarmFor(t, newLauncher(okFor))
+	want := sw.Registry().AgentTypes() // sorted built-ins: subagent, teammate
+
+	spawnEnum := (&spawnTool{sw: sw}).Parameters().Properties["agent_type"].Enum
+	if !slices.Equal(spawnEnum, want) {
+		t.Fatalf("spawn agent_type enum = %v, want roster %v", spawnEnum, want)
+	}
+	if !slices.Contains(spawnEnum, "subagent") || !slices.Contains(spawnEnum, "teammate") {
+		t.Fatalf("enum missing built-in roster types: %v", spawnEnum)
+	}
+	handoffEnum := (&handoffTool{sw: sw}).Parameters().Properties["to_agent_type"].Enum
+	if !slices.Equal(handoffEnum, want) {
+		t.Fatalf("handoff to_agent_type enum = %v, want roster %v", handoffEnum, want)
+	}
+
+	// A user-registered custom type must extend the enum (not a hardcoded list).
+	if err := sw.Registry().Register(Definition{AgentType: "researcher"}); err != nil {
+		t.Fatalf("register custom agent: %v", err)
+	}
+	spawnEnum = (&spawnTool{sw: sw}).Parameters().Properties["agent_type"].Enum
+	if !slices.Contains(spawnEnum, "researcher") {
+		t.Fatalf("custom agent type not reflected in spawn enum: %v", spawnEnum)
+	}
+	handoffEnum = (&handoffTool{sw: sw}).Parameters().Properties["to_agent_type"].Enum
+	if !slices.Contains(handoffEnum, "researcher") {
+		t.Fatalf("custom agent type not reflected in handoff enum: %v", handoffEnum)
+	}
+}
+
+func TestAgentTypePropertyFallsBackWithoutRoster(t *testing.T) {
+	prop := agentTypeProperty(nil, "desc")
+	if prop.Type != "string" || prop.Description != "desc" {
+		t.Fatalf("unexpected property: %+v", prop)
+	}
+	if prop.Enum != nil {
+		t.Fatalf("nil swarm must not advertise an (empty) enum, got %v", prop.Enum)
+	}
+}
+
 func TestCollapseRuneSafeTruncation(t *testing.T) {
 	// 300 multi-byte runes: truncation must not split a rune (no invalid UTF-8).
 	got := collapse(strings.Repeat("🚀", 300))

internal/tools/exec_command.go

@@ -28,8 +28,17 @@ const (
 	completedSessionRetention = 30 * time.Second
 	maxExecSessions           = 64
 	recentExecOutputBytes     = 4096
-	execSessionStopTimeout    = 3 * time.Second
-	execSessionEvictedMessage = "[zero] session evicted: too many background terminals\n"
+	// maxExecOutputBufferBytes caps the undrained output an unpolled session can
+	// accumulate. Without a cap, a long-lived background session nobody polls
+	// again (e.g. a dev server left running after its initiating run was
+	// cancelled) grows this buffer forever as long as the process keeps writing
+	// output, with no ceiling — this previously ran a session's memory into the
+	// tens of gigabytes over several hours and got the whole zero process
+	// OOM-killed by the OS.
+	maxExecOutputBufferBytes         = 2 * 1024 * 1024
+	execSessionStopTimeout           = 3 * time.Second
+	execSessionEvictedMessage        = "[zero] session evicted: too many background terminals\n"
+	execOutputBufferTruncatedMessage = "[zero] output buffer truncated: undrained output exceeded 2MiB, oldest output dropped"
 )
 
 type execSessionManager struct {
@@ -233,6 +242,10 @@ type ExecSessionSnapshot struct {
 	Status       string
 	ExitCode     *int
 	RecentOutput string
+	// OutputTruncated reflects the buffer's last-known truncation state (see
+	// execOutputBuffer.peekTruncated), so a session listing (/ps) still shows
+	// this even if the session is reaped before ever being polled again.
+	OutputTruncated bool
 }
 
 type ExecSessionController interface {
@@ -317,24 +330,26 @@ func (session *execSession) snapshot() ExecSessionSnapshot {
 		status = "exited"
 	}
 	return ExecSessionSnapshot{
-		ID:           session.id,
-		Command:      session.commandText,
-		Cwd:          session.cwd,
-		RelativeCwd:  session.relativeCwd,
-		StartedAt:    startedAt,
-		LastUsedAt:   lastUsedAt,
-		TTY:          session.tty,
-		Status:       status,
-		ExitCode:     copiedExit,
-		RecentOutput: session.output.recentString(),
+		ID:              session.id,
+		Command:         session.commandText,
+		Cwd:             session.cwd,
+		RelativeCwd:     session.relativeCwd,
+		StartedAt:       startedAt,
+		LastUsedAt:      lastUsedAt,
+		TTY:             session.tty,
+		Status:          status,
+		ExitCode:        copiedExit,
+		RecentOutput:    session.output.recentString(),
+		OutputTruncated: session.output.peekTruncated(),
 	}
 }
 
 type execOutputBuffer struct {
-	mu     sync.Mutex
-	data   []byte
-	recent []byte
-	notify chan struct{}
+	mu        sync.Mutex
+	data      []byte
+	recent    []byte
+	truncated bool
+	notify    chan struct{}
 }
 
 func newExecOutputBuffer() *execOutputBuffer {
@@ -344,6 +359,10 @@ func newExecOutputBuffer() *execOutputBuffer {
 func (buffer *execOutputBuffer) Write(p []byte) (int, error) {
 	buffer.mu.Lock()
 	buffer.data = append(buffer.data, p...)
+	if len(buffer.data) > maxExecOutputBufferBytes {
+		buffer.data = buffer.data[len(buffer.data)-maxExecOutputBufferBytes:]
+		buffer.truncated = true
+	}
 	buffer.recent = append(buffer.recent, p...)
 	if len(buffer.recent) > recentExecOutputBytes {
 		buffer.recent = buffer.recent[len(buffer.recent)-recentExecOutputBytes:]
@@ -373,6 +392,34 @@ func (buffer *execOutputBuffer) drainString() string {
 	return out
 }
 
+// consumeTruncated reports whether the buffer has dropped output to stay
+// within maxExecOutputBufferBytes since the last call, resetting the flag.
+// Kept as an out-of-band signal rather than text embedded in drainString's
+// result: an earlier version prefixed a notice directly into the drained
+// string, but that notice always sat ~maxExecOutputBufferBytes (2MiB) before
+// the end of the combined output, far outside the byte-budget head/tail
+// window truncateExecOutput keeps afterward (at most 400KB even at the
+// tool's maximum max_output_tokens) — so the notice was reliably swallowed
+// or chopped by that second, unrelated truncation pass. Surfacing it as a
+// separate bool lets the caller report it regardless of where in the byte
+// stream the overflow happened.
+func (buffer *execOutputBuffer) consumeTruncated() bool {
+	buffer.mu.Lock()
+	defer buffer.mu.Unlock()
+	truncated := buffer.truncated
+	buffer.truncated = false
+	return truncated
+}
+
+// peekTruncated reports the buffer's last-known truncation state without
+// clearing it, for status views (e.g. /ps) that shouldn't consume the signal
+// a subsequent poll is still meant to report via consumeTruncated.
+func (buffer *execOutputBuffer) peekTruncated() bool {
+	buffer.mu.Lock()
+	defer buffer.mu.Unlock()
+	return buffer.truncated
+}
+
 type execCommandTool struct {
 	baseTool
 	workspaceRoot string
@@ -485,25 +532,28 @@ func (tool execCommandTool) run(ctx context.Context, args map[string]any, engine
 	if err != nil {
 		return errorResult("Error starting exec_command: " + err.Error())
 	}
-	output := session.collect(ctx, time.Duration(yieldTimeMS)*time.Millisecond)
+	output, outputTruncated := session.collect(ctx, time.Duration(yieldTimeMS)*time.Millisecond)
 	if ctx != nil && ctx.Err() != nil && !session.doneClosed() {
 		session.terminate()
-		output += session.collect(context.Background(), time.Second)
+		more, moreTruncated := session.collect(context.Background(), time.Second)
+		output += more
+		outputTruncated = outputTruncated || moreTruncated
 	}
 	exitCode, exited := session.exitStatus()
 	if exited {
 		tool.manager.remove(session.id)
 	}
 	return execToolResult(execToolResultInput{
-		commandText:     commandText,
-		output:          output,
-		sessionID:       session.id,
-		exitCode:        exitCode,
-		exited:          exited,
-		relativeCwd:     relativeCwd,
-		tty:             session.tty,
-		plan:            session.plan,
-		maxOutputTokens: maxOutputTokens,
+		commandText:           commandText,
+		output:                output,
+		outputBufferTruncated: outputTruncated,
+		sessionID:             session.id,
+		exitCode:              exitCode,
+		exited:                exited,
+		relativeCwd:           relativeCwd,
+		tty:                   session.tty,
+		plan:                  session.plan,
+		maxOutputTokens:       maxOutputTokens,
 	})
 }
 
@@ -558,26 +608,39 @@ func (tool execCommandTool) startSession(commandText string, absoluteCwd string,
 	return session, nil
 }
 
-func (session *execSession) collect(ctx context.Context, wait time.Duration) string {
+// collect drains the session's output buffer, returning the accumulated text
+// and whether the buffer ever had to drop output to stay within
+// maxExecOutputBufferBytes since the last collect call.
+func (session *execSession) collect(ctx context.Context, wait time.Duration) (string, bool) {
 	if ctx == nil {
 		ctx = context.Background()
 	}
 	deadline := time.Now().Add(wait)
 	var builder strings.Builder
+	truncated := false
+	finish := func() (string, bool) {
+		if session.output.consumeTruncated() {
+			truncated = true
+		}
+		return builder.String(), truncated
+	}
 	for {
 		if chunk := session.output.drainString(); chunk != "" {
 			builder.WriteString(chunk)
+			if session.output.consumeTruncated() {
+				truncated = true
+			}
 			continue
 		}
 		if session.doneClosed() {
 			if chunk := session.output.drainString(); chunk != "" {
 				builder.WriteString(chunk)
 			}
-			return builder.String()
+			return finish()
 		}
 		remaining := time.Until(deadline)
 		if remaining <= 0 {
-			return builder.String()
+			return finish()
 		}
 		timer := time.NewTimer(remaining)
 		select {
@@ -602,9 +665,9 @@ func (session *execSession) collect(ctx context.Context, wait time.Duration) str
 				default:
 				}
 			}
-			return builder.String()
+			return finish()
 		case <-timer.C:
-			return builder.String()
+			return finish()
 		}
 	}
 }
@@ -701,22 +764,23 @@ func (tool writeStdinTool) RunWithOptions(ctx context.Context, args map[string]a
 			}
 		}
 	}
-	output := session.collect(ctx, time.Duration(yieldTimeMS)*time.Millisecond)
+	output, outputTruncated := session.collect(ctx, time.Duration(yieldTimeMS)*time.Millisecond)
 	exitCode, exited := session.exitStatus()
 	if exited {
 		tool.manager.remove(session.id)
 	}
 	return execToolResult(execToolResultInput{
-		commandText:     session.commandText,
-		output:          output,
-		sessionID:       session.id,
-		exitCode:        exitCode,
-		exited:          exited,
-		relativeCwd:     session.relativeCwd,
-		tty:             session.tty,
-		interrupted:     interrupted,
-		plan:            session.plan,
-		maxOutputTokens: maxOutputTokens,
+		commandText:           session.commandText,
+		output:                output,
+		outputBufferTruncated: outputTruncated,
+		sessionID:             session.id,
+		exitCode:              exitCode,
+		exited:                exited,
+		relativeCwd:           session.relativeCwd,
+		tty:                   session.tty,
+		interrupted:           interrupted,
+		plan:                  session.plan,
+		maxOutputTokens:       maxOutputTokens,
 	})
 }
 
@@ -741,16 +805,22 @@ func shouldInterruptExecSession(chars string, tty bool) bool {
 }
 
 type execToolResultInput struct {
-	commandText     string
-	output          string
-	sessionID       int
-	exitCode        int
-	exited          bool
-	relativeCwd     string
-	tty             bool
-	interrupted     bool
-	plan            zeroSandbox.CommandPlan
-	maxOutputTokens int
+	commandText string
+	output      string
+	// outputBufferTruncated is true when the session's undrained output buffer
+	// had to drop bytes to stay within maxExecOutputBufferBytes since it was
+	// last collected — data that is gone for good, unlike the head/tail
+	// truncation below (which the caller can recover by polling again or
+	// raising max_output_tokens).
+	outputBufferTruncated bool
+	sessionID             int
+	exitCode              int
+	exited                bool
+	relativeCwd           string
+	tty                   bool
+	interrupted           bool
+	plan                  zeroSandbox.CommandPlan
+	maxOutputTokens       int
 }
 
 func execToolResult(input execToolResultInput) Result {
@@ -771,16 +841,26 @@ func execToolResult(input execToolResultInput) Result {
 	} else {
 		meta["session_id"] = strconv.Itoa(input.sessionID)
 	}
+	if input.outputBufferTruncated {
+		meta["output_buffer_truncated"] = "true"
+	}
 
 	status := StatusOK
 	if input.exited && ((input.exitCode != 0 && !input.interrupted) || meta[SandboxLikelyDeniedMeta] == "true") {
 		status = StatusError
 	}
 	body := formatExecCommandOutput(output, input.sessionID, input.exited, input.exitCode, input.interrupted)
+	if input.outputBufferTruncated {
+		// Appended after truncateExecOutput's own head/tail slicing, not
+		// embedded in the text that goes through it — a marker inside that
+		// text can land in the discarded middle or get chopped at a small
+		// max_output_tokens budget. Appending here guarantees it survives.
+		body += "\n" + execOutputBufferTruncatedMessage
+	}
 	return Result{
 		Status:    status,
 		Output:    body,
-		Truncated: truncated,
+		Truncated: truncated || input.outputBufferTruncated,
 		Meta:      meta,
 		Display: Display{
 			Summary: execDisplaySummary(input.commandText, input.sessionID, input.exited, input.exitCode),

internal/tools/exec_command_test.go

@@ -363,6 +363,93 @@ func TestStartExecProcessFallsBackAfterPTYStartMutation(t *testing.T) {
 	}
 }
 
+// TestExecOutputBufferCapsUndrainedData: a session nobody polls must not grow
+// its undrained buffer without bound — a long-lived background process that
+// keeps writing while unpolled previously ran a session's memory into the
+// tens of gigabytes and got the whole zero process OOM-killed by the OS.
+func TestExecOutputBufferCapsUndrainedData(t *testing.T) {
+	buffer := newExecOutputBuffer()
+
+	chunk := strings.Repeat("x", 1024)
+	writes := (maxExecOutputBufferBytes / len(chunk)) + 10 // comfortably over the cap
+	for i := 0; i < writes; i++ {
+		if _, err := buffer.Write([]byte(chunk)); err != nil {
+			t.Fatalf("Write: %v", err)
+		}
+	}
+
+	buffer.mu.Lock()
+	dataLen := len(buffer.data)
+	buffer.mu.Unlock()
+	if dataLen > maxExecOutputBufferBytes {
+		t.Fatalf("undrained buffer grew to %d bytes, want <= %d", dataLen, maxExecOutputBufferBytes)
+	}
+
+	out := buffer.drainString()
+	// drainString itself carries no truncation marker: a marker embedded in
+	// the drained text would always sit ~maxExecOutputBufferBytes before the
+	// end of the string, past any realistic head/tail truncation window a
+	// caller applies afterward (see execToolResult), so it's reliably lost.
+	// The signal lives out of band on consumeTruncated/peekTruncated instead.
+	if !strings.HasSuffix(out, chunk) {
+		t.Fatal("drained output should keep the most recent bytes, not the oldest")
+	}
+	if len(out) > maxExecOutputBufferBytes {
+		t.Fatalf("drained output = %d bytes, want <= %d (no marker text mixed in)", len(out), maxExecOutputBufferBytes)
+	}
+
+	if !buffer.peekTruncated() {
+		t.Fatal("peekTruncated should report the overflow without clearing it")
+	}
+	if !buffer.peekTruncated() {
+		t.Fatal("a second peekTruncated call should still report it — peek must not consume")
+	}
+	if !buffer.consumeTruncated() {
+		t.Fatal("consumeTruncated should report the overflow")
+	}
+	if buffer.consumeTruncated() {
+		t.Fatal("consumeTruncated should reset after being read once")
+	}
+	if buffer.peekTruncated() {
+		t.Fatal("peekTruncated should reflect the reset state after consumeTruncated")
+	}
+
+	// A second drain with no intervening writes must be empty.
+	if got := buffer.drainString(); got != "" {
+		t.Fatalf("drainString after a full drain = %q, want empty", got)
+	}
+}
+
+// TestExecToolResultSurfacesBufferTruncationOutsideByteBudget: an earlier
+// version embedded the truncation notice directly in the drained text, which
+// a review found sits ~maxExecOutputBufferBytes before the end of the
+// string — far past the head/tail window truncateExecOutput keeps even at
+// the tool's smallest allowed max_output_tokens, so the notice was reliably
+// swallowed or chopped. The notice must survive regardless of how small the
+// byte budget is, and it must not count against that budget.
+func TestExecToolResultSurfacesBufferTruncationOutsideByteBudget(t *testing.T) {
+	hugeOutput := strings.Repeat("y", maxExecOutputBufferBytes+1024)
+
+	result := execToolResult(execToolResultInput{
+		commandText:           "cmd",
+		output:                hugeOutput,
+		outputBufferTruncated: true,
+		sessionID:             1,
+		exited:                false,
+		maxOutputTokens:       1, // the schema's own declared minimum
+	})
+
+	if !strings.Contains(result.Output, execOutputBufferTruncatedMessage) {
+		t.Fatalf("result output should contain the buffer-truncation notice even at the smallest max_output_tokens, got %q", result.Output[:min(len(result.Output), 200)])
+	}
+	if result.Meta["output_buffer_truncated"] != "true" {
+		t.Fatalf("result meta should flag output_buffer_truncated, got %#v", result.Meta)
+	}
+	if !result.Truncated {
+		t.Fatal("result should report Truncated when the buffer dropped output")
+	}
+}
+
 // resilientTempDir is like t.TempDir() but tolerates the Windows handle-release
 // lag: a SIGKILL'd child process that had the dir as its cwd may not have
 // released it the instant it is reaped, so the immediate RemoveAll t.TempDir()

internal/tui/background_terminals.go

@@ -146,6 +146,9 @@ func formatBackgroundTerminalRow(session tools.ExecSessionSnapshot, now time.Tim
 	}
 	preview := compactCommandOutputText(session.RecentOutput)
 	prefix := fmt.Sprintf("%d · %s · %s · %s", session.ID, session.Status, age, cwd)
+	if session.OutputTruncated {
+		prefix += " · output truncated"
+	}
 	if preview != "" {
 		return prefix + " · " + command + " · " + preview
 	}

internal/tui/command_center.go

@@ -441,6 +441,8 @@ func (m model) handleModelCommand(args string) (model, string) {
 	m.providerProfile = nextProfile
 	m.provider = nextProvider
 	m.providerName = displayValue(nextProfile.Name, string(metadata.ProviderKind))
+	// Keep sub-agent child processes on the same provider we just switched to.
+	config.SetActiveProviderEnv(nextProfile.Name)
 	m.modelName = target.modelID
 	resetEffort := false
 	if m.reasoningEffort != "" && !reasoningEffortAllowed(target.reasoningEfforts, m.reasoningEffort) {
@@ -516,6 +518,8 @@ func (m model) switchProviderModel(providerName, modelID string) (model, string)
 	m.providerProfile = target
 	m.providerName = target.Name
 	m.modelName = target.Model
+	// Keep sub-agent child processes on the same provider we just switched to.
+	config.SetActiveProviderEnv(target.Name)
 	if strings.TrimSpace(m.userConfigPath) != "" {
 		_, _ = config.SetActiveProvider(m.userConfigPath, target.Name)
 		_, _ = config.SetProviderModel(m.userConfigPath, target.Name, target.Model)

internal/tui/commands.go

@@ -40,6 +40,7 @@ const (
 	commandImage
 	commandAddDir
 	commandSelfCorrect
+	commandTurns
 	commandUnknown
 )
 
@@ -241,6 +242,13 @@ var commandDefinitions = []commandDefinition{
 		description: "Show or set post-edit self-correction depth (LSP-only default; on/tests/full add the project test plan; off/lsp disable tests, LSP-only).",
 		kind:        commandSelfCorrect,
 	},
+	{
+		name:        "/turns",
+		usage:       "/turns [n]",
+		group:       commandGroupSession,
+		description: "Show or set the per-run tool-turn budget for this session (raise it for long multi-step tasks).",
+		kind:        commandTurns,
+	},
 	{
 		name:        "/help",
 		usage:       "/help",

internal/tui/flush.go

@@ -139,6 +139,10 @@ func (m model) drainFlushQueue() (model, tea.Cmd) {
 // surface ended.
 func (m *model) resetFlushFrontier(divider string) {
 	m.flushed = 0
+	// Renumbers every row's bodyY from the top (used by /clear, /resume, /rewind,
+	// /compact); a transcript-hover target's bodyY would otherwise risk
+	// coincidentally matching an unrelated row in the rebuilt transcript.
+	m.hover = hoverTarget{}
 	if divider != "" && m.flushedAny {
 		m.flushQueue = append(m.flushQueue, zeroTheme.faint.Render(divider))
 	}

internal/tui/hover.go

@@ -0,0 +1,117 @@
+package tui
+
+import tea "charm.land/bubbletea/v2"
+
+// hoverKind discriminates which clickable surface a hoverTarget refers to.
+type hoverKind int
+
+const (
+	hoverNone hoverKind = iota
+	// hoverTranscript: a specialist card or collapse/expand toggle header in the
+	// main transcript body (or the subchat child view), identified by bodyY.
+	hoverTranscript
+	// hoverSidebarAgent: a clickable AGENTS sidebar row, identified by sessionID.
+	hoverSidebarAgent
+	// hoverPlanStep: a plan step row in the sidebar's PLAN section, identified by
+	// step index.
+	hoverPlanStep
+)
+
+// hoverTarget identifies the single clickable row (if any) currently under the
+// mouse cursor with no button pressed. Exactly one of bodyY/sessionID/stepIndex is
+// meaningful, discriminated by kind.
+//
+// The sidebar fields deliberately store a STABLE IDENTITY (sessionID, stepIndex),
+// not a raw line offset: the AGENTS/PLAN section sizes can change between when a
+// hover is detected and when the sidebar next renders (a swarm member's linger
+// window elapsing, a plan step completing) with no mouse motion in between to
+// re-resolve it. A cached raw offset would then silently point at whatever
+// unrelated row now occupies that slot. hoveredSidebarLineOffset (sidebar.go)
+// re-resolves the CURRENT line offset for this identity fresh on every render, so
+// a row that's gone simply doesn't highlight rather than a wrong one lighting up.
+type hoverTarget struct {
+	kind      hoverKind
+	bodyY     int    // hoverTranscript
+	sessionID string // hoverSidebarAgent
+	stepIndex int    // hoverPlanStep
+}
+
+// mouseHover reports whether msg is a plain cursor-movement event with NO button
+// pressed — a hover, not a drag. Requires AllMotion mouse reporting (see View's
+// wantsMouseCapture branch); CellMotion only reports motion while a button is held,
+// so this predicate would never match under the old mouse mode.
+func mouseHover(msg tea.MouseMsg) bool {
+	if _, ok := msg.(tea.MouseMotionMsg); !ok {
+		return false
+	}
+	return mouseEvent(msg).Button == tea.MouseNone
+}
+
+// updateHoverTarget resolves what's under the cursor for a hover motion, using
+// the SAME hit-testers and priority order as the click handlers in
+// handleTranscriptSelectionMouse's press case: a sidebar row (agent, then plan
+// step) takes priority since it's outside the chat column, then a clickable
+// transcript line. Clears the hover when nothing clickable is under the cursor.
+func (m model) updateHoverTarget(msg tea.MouseMsg) model {
+	if hit, ok := m.sidebarLineAtMouse(msg); ok {
+		return m.withHover(hoverTarget{kind: hoverSidebarAgent, sessionID: hit.sessionID})
+	}
+	if stepIndex, ok := m.planStepAtMouse(msg); ok {
+		return m.withHover(hoverTarget{kind: hoverPlanStep, stepIndex: stepIndex})
+	}
+	if line, ok := m.transcriptLineAtMouse(msg); ok {
+		// A permission option reuses its OWN existing keyboard-cursor highlight
+		// (see hoverPermissionOption) rather than the m.hover mechanism, so there's
+		// nothing further to set here.
+		if line.permOption {
+			return m.hoverPermissionOption(line.permChoice).withHover(hoverTarget{})
+		}
+		// Only a card or a collapse/expand toggle header is "clickable" here; plain
+		// selectable text (e.g. a user/assistant message) isn't, so hovering over
+		// it must not light up as if it were.
+		if line.specialistCard || line.toggle {
+			return m.withHover(hoverTarget{kind: hoverTranscript, bodyY: line.bodyY})
+		}
+	}
+	return m.withHover(hoverTarget{})
+}
+
+// hoverPermissionOption moves the pending permission prompt's cursor to the
+// hovered option, reusing its EXISTING keyboard-navigation highlight (the same
+// one Tab/Shift+Tab/arrow keys move) instead of new styling — the popup already
+// renders whichever option .cursor points at differently. A no-op when no
+// permission prompt is pending or the choice isn't found (defensive; every
+// permOption line's choice always comes from permissionOptions(request) in the
+// first place).
+func (m model) hoverPermissionOption(choice permissionDecision) model {
+	if m.pendingPermission == nil {
+		return m
+	}
+	for index, option := range permissionOptions(m.pendingPermission.request) {
+		if option.choice == choice {
+			m.pendingPermission.cursor = index
+			return m
+		}
+	}
+	return m
+}
+
+func (m model) withHover(t hoverTarget) model {
+	m.hover = t
+	return m
+}
+
+// clearHover drops any hover highlight. Called wherever the underlying content a
+// hover target refers to may no longer mean the same thing on the next render — a
+// wheel-scroll (the cursor's mapping to a bodyY is only recomputed on the NEXT
+// motion event; without clearing, a stale bodyY could coincidentally match a
+// DIFFERENT row after the viewport shifts, highlighting the wrong thing) or a
+// subchat toggle (bodyY numbering is entirely different between the parent
+// transcript and a child session).
+func (m model) clearHover() model {
+	if m.hover.kind == hoverNone {
+		return m
+	}
+	m.hover = hoverTarget{}
+	return m
+}

internal/tui/hover_test.go

@@ -0,0 +1,284 @@
+package tui
+
+import (
+	"strings"
+	"testing"
+
+	tea "charm.land/bubbletea/v2"
+
+	"github.com/Gitlawb/zero/internal/agent"
+)
+
+func TestMouseHoverPredicate(t *testing.T) {
+	if !mouseHover(testMouseMotion(tea.MouseNone, 5, 5)) {
+		t.Error("a motion event with no button pressed must be a hover")
+	}
+	if mouseHover(testMouseMotion(tea.MouseLeft, 5, 5)) {
+		t.Error("a motion event WITH a button pressed is a drag, not a hover")
+	}
+	if mouseHover(testMouseClick(tea.MouseLeft, 5, 5)) {
+		t.Error("a click is not a hover")
+	}
+	if mouseHover(testMouseWheel(tea.MouseWheelDown, 5, 5)) {
+		t.Error("a wheel event is not a hover")
+	}
+}
+
+func TestUpdateHoverTargetOnSpecialistCard(t *testing.T) {
+	m := specialistClickTestModel(t, "child-sess-1")
+	x, y, ok := specialistCardClickPoint(m, 2)
+	if !ok {
+		t.Fatal("expected a specialist card selectable line in the layout")
+	}
+
+	updated, _ := m.Update(testMouseMotion(tea.MouseNone, x, y))
+	m = updated.(model)
+	if m.hover.kind != hoverTranscript {
+		t.Fatalf("hover.kind = %v, want hoverTranscript over a specialist card", m.hover.kind)
+	}
+}
+
+func TestUpdateHoverTargetOnToggleRow(t *testing.T) {
+	m := mouseTestModel()
+	m.transcript = appendTranscriptRow(m.transcript, transcriptRow{kind: rowReasoning, text: "private thought"})
+
+	width := m.chatColumnWidth()
+	body, selectable := m.transcriptBody(width, "")
+	start, _, top := m.transcriptViewportStart(body, width)
+	var target transcriptSelectableLine
+	for _, line := range selectable {
+		if line.toggle {
+			target = line
+			break
+		}
+	}
+	if !target.toggle {
+		t.Fatalf("expected reasoning header to be clickable, selectable=%#v", selectable)
+	}
+
+	updated, _ := m.Update(testMouseMotion(tea.MouseNone, target.textStart, top+target.bodyY-start))
+	m = updated.(model)
+	if m.hover.kind != hoverTranscript {
+		t.Fatalf("hover.kind = %v, want hoverTranscript over a toggle header", m.hover.kind)
+	}
+	if m.hover.bodyY != target.bodyY {
+		t.Fatalf("hover.bodyY = %d, want %d", m.hover.bodyY, target.bodyY)
+	}
+}
+
+func TestUpdateHoverTargetOnPlainTextIsNone(t *testing.T) {
+	m := mouseTestModel()
+	m.transcript = appendRow(m.transcript, rowUser, "hello world")
+	textY := firstTranscriptTextMouseY(t, m)
+
+	updated, _ := m.Update(testMouseMotion(tea.MouseNone, 3, textY))
+	m = updated.(model)
+	if m.hover.kind != hoverNone {
+		t.Fatalf("hover.kind = %v, want hoverNone over plain (non-clickable) text", m.hover.kind)
+	}
+}
+
+func TestUpdateHoverTargetOnSidebarAgentRow(t *testing.T) {
+	// Only a SWARM member row (a session mapped via swarmSessionMap) is clickable
+	// in the sidebar — a Task-delegation specialist row is not (sidebarAgentRows
+	// only records hits from the swarm loop). swarmSidebarTestModel builds exactly
+	// that: real conversation + a mapped swarm member session.
+	m := swarmSidebarTestModel(t, map[string]string{"subagent-1": "sess-1"})
+	if !m.sidebarActive() {
+		t.Fatal("sanity check failed: sidebar should be active with a swarm member present on a 100-col terminal")
+	}
+	hits := m.sidebarAgentSelectables(sidebarWidth(m.width))
+	if len(hits) == 0 {
+		t.Fatal("expected at least one clickable sidebar agent row")
+	}
+	x0 := m.chatColumnWidth() + 3
+
+	updated, _ := m.Update(testMouseMotion(tea.MouseNone, x0+1, hits[0].lineOffset))
+	m = updated.(model)
+	if m.hover.kind != hoverSidebarAgent {
+		t.Fatalf("hover.kind = %v, want hoverSidebarAgent", m.hover.kind)
+	}
+	if m.hover.sessionID != hits[0].sessionID {
+		t.Fatalf("hover.sessionID = %q, want %q", m.hover.sessionID, hits[0].sessionID)
+	}
+	// The bug this guards: hoverTarget must store the STABLE identity (sessionID),
+	// not a raw line offset — resolve it back to a line offset the same way the
+	// render path does (hoveredSidebarLineOffset) and confirm it lands on the
+	// SAME row that was actually hovered, not some other row at that raw index.
+	resolved, ok := m.hoveredSidebarLineOffset(sidebarWidth(m.width))
+	if !ok || resolved != hits[0].lineOffset {
+		t.Fatalf("hoveredSidebarLineOffset() = (%d, %v), want (%d, true)", resolved, ok, hits[0].lineOffset)
+	}
+}
+
+func TestUpdateHoverTargetOnPlanStep(t *testing.T) {
+	m := runningPlanModel(t, 3)
+	m.altScreen = true
+	m.height = 40
+	// sidebarActive requires real conversation; runningPlanModel only sets m.plan,
+	// leaving the transcript at its default (welcome-only, i.e. "empty").
+	m.transcript = appendRow(m.transcript, rowUser, "do something")
+	if !m.sidebarActive() {
+		t.Fatal("sanity check failed: sidebar should be active with a plan present on a 100-col terminal")
+	}
+	hits := m.sidebarPlanSelectables(sidebarWidth(m.width))
+	if len(hits) == 0 {
+		t.Fatal("expected at least one clickable plan step row")
+	}
+	x0 := m.chatColumnWidth() + 3
+
+	updated, _ := m.Update(testMouseMotion(tea.MouseNone, x0+1, hits[0].lineOffset))
+	m = updated.(model)
+	if m.hover.kind != hoverPlanStep {
+		t.Fatalf("hover.kind = %v, want hoverPlanStep", m.hover.kind)
+	}
+	if m.hover.stepIndex != hits[0].stepIndex {
+		t.Fatalf("hover.stepIndex = %d, want %d", m.hover.stepIndex, hits[0].stepIndex)
+	}
+	// The bug this guards: the render path must resolve stepIndex back to the
+	// CORRECT current lineOffset (hits[0].lineOffset, which is >= base=4, never a
+	// raw small index like 0/1/2) — not treat stepIndex itself as a line offset
+	// into the rendered sidebar (which would land on the AGENTS header/body).
+	resolved, ok := m.hoveredSidebarLineOffset(sidebarWidth(m.width))
+	if !ok || resolved != hits[0].lineOffset {
+		t.Fatalf("hoveredSidebarLineOffset() = (%d, %v), want (%d, true)", resolved, ok, hits[0].lineOffset)
+	}
+}
+
+func TestUpdateHoverTargetOnPermissionOptionMovesCursor(t *testing.T) {
+	m := mouseTestModel()
+	m.pending = true // the permission prompt only renders into the transcript body while m.pending
+	m.pendingPermission = &pendingPermissionPrompt{
+		request: agent.PermissionRequest{ToolName: "write_file"},
+		cursor:  0,
+	}
+	width := m.chatColumnWidth()
+	body, selectable := m.transcriptBody(width, "")
+	start, _, top := m.transcriptViewportStart(body, width)
+	var target transcriptSelectableLine
+	found := false
+	for _, line := range selectable {
+		if line.permOption && line.permChoice != permissionOptions(m.pendingPermission.request)[0].choice {
+			target = line
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatal("expected at least 2 permission options to test a non-default hover target")
+	}
+
+	updated, _ := m.Update(testMouseMotion(tea.MouseNone, target.textStart, top+target.bodyY-start))
+	m = updated.(model)
+	// Permission-option hover reuses the existing cursor highlight, not m.hover.
+	if m.hover.kind != hoverNone {
+		t.Fatalf("hover.kind = %v, want hoverNone (permission options use pendingPermission.cursor)", m.hover.kind)
+	}
+	wantIndex := -1
+	for index, option := range permissionOptions(m.pendingPermission.request) {
+		if option.choice == target.permChoice {
+			wantIndex = index
+			break
+		}
+	}
+	if m.pendingPermission.cursor != wantIndex {
+		t.Fatalf("pendingPermission.cursor = %d, want %d (the hovered option)", m.pendingPermission.cursor, wantIndex)
+	}
+}
+
+func TestHoverChangesTranscriptRenderOutput(t *testing.T) {
+	m := specialistClickTestModel(t, "child-sess-1")
+	width := m.chatColumnWidth()
+	without := m.transcriptBodyLayout(width, "").String()
+
+	x, y, ok := specialistCardClickPoint(m, 2)
+	if !ok {
+		t.Fatal("expected a specialist card selectable line in the layout")
+	}
+	updated, _ := m.Update(testMouseMotion(tea.MouseNone, x, y))
+	m = updated.(model)
+	if m.hover.kind != hoverTranscript {
+		t.Fatal("sanity check failed: hover should be set over the specialist card")
+	}
+	with := m.transcriptBodyLayout(width, "").String()
+
+	if without == with {
+		t.Fatal("rendering with a hover target set should differ from without (the highlight should show)")
+	}
+}
+
+func TestHoverChangesSidebarRenderOutput(t *testing.T) {
+	m := swarmSidebarTestModel(t, map[string]string{"subagent-1": "sess-1"})
+	width := m.chatColumnWidth()
+	height := m.height
+	without := strings.Join(m.renderContextSidebar(sidebarWidth(m.width), height), "\n")
+
+	hits := m.sidebarAgentSelectables(sidebarWidth(m.width))
+	if len(hits) == 0 {
+		t.Fatal("expected at least one clickable sidebar agent row")
+	}
+	updated, _ := m.Update(testMouseMotion(tea.MouseNone, width+3+1, hits[0].lineOffset))
+	m = updated.(model)
+	if m.hover.kind != hoverSidebarAgent {
+		t.Fatal("sanity check failed: hover should be set over the sidebar agent row")
+	}
+	with := strings.Join(m.renderContextSidebar(sidebarWidth(m.width), height), "\n")
+
+	if without == with {
+		t.Fatal("sidebar rendering with a hover target set should differ from without (the highlight should show)")
+	}
+}
+
+func TestHoverClearsOnWheelScroll(t *testing.T) {
+	m := mouseTestModel()
+	for i := 0; i < 80; i++ {
+		m.transcript = appendRow(m.transcript, rowUser, "line content")
+	}
+	m.hover = hoverTarget{kind: hoverTranscript, bodyY: 5}
+
+	updated, _ := m.Update(testMouseWheel(tea.MouseWheelUp, 0, 3))
+	m = updated.(model)
+	if m.hover.kind != hoverNone {
+		t.Fatalf("hover should clear on a wheel scroll, got %#v", m.hover)
+	}
+}
+
+func TestHoverClearsOnSubchatExit(t *testing.T) {
+	m := mouseTestModel()
+	m.subchat.active = true
+	m.subchat.childSessionID = "child-1"
+	m.subchat.childRows = appendRow(nil, rowUser, "child text")
+	m.hover = hoverTarget{kind: hoverTranscript, bodyY: 5}
+
+	updated, _ := m.Update(tea.KeyPressMsg(tea.Key{Code: tea.KeyEsc}))
+	m = updated.(model)
+	if m.subchat.active {
+		t.Fatal("Esc should exit the subchat view")
+	}
+	if m.hover.kind != hoverNone {
+		t.Fatalf("hover should clear on subchat exit (bodyY numbering differs), got %#v", m.hover)
+	}
+}
+
+// A sidebar row can disappear between when it was hovered and the next render
+// (a swarm member's linger window elapsing) with no mouse motion in between to
+// re-target the hover. hoveredSidebarLineOffset must not paint a highlight on
+// whatever unrelated row now occupies that identity's old slot — it must find
+// nothing and skip painting entirely.
+func TestHoveredSidebarLineOffsetSelfHealsWhenRowDisappears(t *testing.T) {
+	m := swarmSidebarTestModel(t, map[string]string{"subagent-1": "sess-1"})
+	hits := m.sidebarAgentSelectables(sidebarWidth(m.width))
+	if len(hits) == 0 {
+		t.Fatal("expected at least one clickable sidebar agent row")
+	}
+	m.hover = hoverTarget{kind: hoverSidebarAgent, sessionID: hits[0].sessionID}
+
+	// Simulate the member disappearing (a fresh model with no swarm member at all,
+	// same identity no longer present) without any mouse motion clearing m.hover.
+	m2 := swarmSidebarTestModel(t, nil)
+	m2.hover = m.hover
+
+	if _, ok := m2.hoveredSidebarLineOffset(sidebarWidth(m2.width)); ok {
+		t.Fatal("hoveredSidebarLineOffset should find nothing once the identity no longer resolves, not fall back to a stale/coincidental row")
+	}
+}

internal/tui/model.go

@@ -40,6 +40,13 @@ const chatWheelScrollLines = 5
 const ctrlCExitConfirmDuration = 3 * time.Second
 const ctrlCExitConfirmText = "Press Ctrl+C again to exit"
 
+// dragEdgeScrollInterval/dragEdgeScrollStep drive the smooth-glide auto-scroll
+// while a drag holds past the transcript edge (see edgeScrollDelta). A small step
+// on a short, steady cadence reads as a smooth continuous scroll; the wheel-scroll
+// tick size (chatWheelScrollLines) would jump too far per step for that.
+const dragEdgeScrollInterval = 70 * time.Millisecond
+const dragEdgeScrollStep = 1
+
 type model struct {
 	ctx                    context.Context
 	cwd                    string
@@ -280,10 +287,31 @@ type model struct {
 	// (clickable suggestions, right-click paste, transcript select) pause while on.
 	mouseReleased       bool
 	transcriptSelection transcriptSelectionState
-	copyStatus          string
-	copyStatusSeq       int
-	exitConfirmActive   bool
-	exitConfirmSeq      int
+	// hover identifies the single clickable row (if any) currently under the
+	// mouse cursor with no button pressed, so it renders in a distinct style —
+	// the visual cue that it's clickable. Requires AllMotion mouse reporting
+	// (see wantsMouseCapture) since idle cursor movement carries no button.
+	hover             hoverTarget
+	copyStatus        string
+	copyStatusSeq     int
+	exitConfirmActive bool
+	exitConfirmSeq    int
+	// edgeScrollDelta drives the smooth-glide auto-scroll while a drag holds past
+	// the transcript's top/bottom edge: 0 when idle, else the signed per-tick step
+	// (matches transcriptEdgeScrollDelta's sign convention). A self-scheduling
+	// tea.Tick chain (see dragEdgeScrollTickCmd) keeps stepping it at a fixed small
+	// increment regardless of whether new raw mouse-motion events arrive — a
+	// terminal only reports motion on actual cursor movement, so without a timer
+	// the scroll would stop dead the instant the physical mouse holds still, even
+	// while parked past the edge. edgeScrollSeq invalidates a stale in-flight tick
+	// (mirroring exitConfirmSeq/copyStatusSeq) whenever the drag moves back into
+	// the body, releases, or the chain is otherwise stopped.
+	edgeScrollDelta int
+	edgeScrollSeq   int
+	// edgeScrollMouseX is the column the tick chain keeps extending the selection
+	// at — captured from the triggering drag since a timer tick carries no mouse
+	// position of its own.
+	edgeScrollMouseX int
 
 	// picker, when non-nil, is an open interactive selector overlay (/model,
 	// /effort with no argument). It captures ↑/↓/Enter/Esc and applies
@@ -330,6 +358,15 @@ type exitConfirmExpiredMsg struct {
 	seq int
 }
 
+// dragEdgeScrollTickMsg advances the smooth-glide auto-scroll one step (see
+// edgeScrollDelta). seq must match m.edgeScrollSeq or the tick is stale (the
+// drag moved back into the body, released, or was otherwise stopped since this
+// tick was scheduled) and is silently dropped — the self-scheduling chain simply
+// doesn't reschedule itself, so it terminates rather than ticking forever.
+type dragEdgeScrollTickMsg struct {
+	seq int
+}
+
 // toolCallStreamStartMsg / toolCallStreamDeltaMsg carry a tool call's live
 // argument stream from the agent goroutine to the update loop, so a file being
 // written renders as it streams (see streamingToolCallView).
@@ -890,6 +927,12 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 			m.exitConfirmActive = false
 		}
 		return m, nil
+	case dragEdgeScrollTickMsg:
+		if msg.seq != m.edgeScrollSeq || m.edgeScrollDelta == 0 || !m.transcriptSelection.active {
+			return m, nil // stale, or the chain was stopped since this tick was scheduled
+		}
+		m = m.dragToEdgeScroll(m.edgeScrollDelta, m.edgeScrollMouseX)
+		return m, dragEdgeScrollTickCmd(m.edgeScrollSeq)
 	case providerWizardOAuthMsg:
 		return m.applyProviderWizardOAuth(msg)
 	case providerWizardDeviceCodeMsg:
@@ -956,6 +999,7 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 			// Subchat view exits on Esc (returns to main chat).
 			if m.subchat.active {
 				m.chatScrollOffset = m.subchat.exit()
+				m = m.clearHover() // bodyY numbering differs between subchat and the parent transcript
 				return m, nil
 			}
 			if m.mcpCommandCancel != nil {
@@ -1174,11 +1218,17 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 			if m.transcriptDetailed {
 				return m, nil
 			}
+			// A stationary mouse over a bodyY-keyed transcript hover target would
+			// otherwise stay lit at the scrolled-away bodyY until the next real
+			// motion event (see clearHover) — same reasoning as the wheel-scroll
+			// cases in mouse.go.
+			m = m.clearHover()
 			return m.scrollChat(m.chatPageScrollLines()), nil
 		case keyIs(msg, tea.KeyPgDown):
 			if m.transcriptDetailed {
 				return m, nil
 			}
+			m = m.clearHover()
 			return m.scrollChat(-m.chatPageScrollLines()), nil
 		case keyIs(msg, tea.KeyDown):
 			if m.transcriptDetailed {
@@ -1220,6 +1270,7 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 			// ArrowUp exits subchat view (returns to main chat).
 			if m.subchat.active {
 				m.chatScrollOffset = m.subchat.exit()
+				m = m.clearHover() // bodyY numbering differs between subchat and the parent transcript
 				return m, nil
 			}
 			if m.transcriptDetailed {
@@ -1445,6 +1496,10 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 	case tea.WindowSizeMsg:
 		m.width = msg.Width
 		m.height = msg.Height
+		// A resize re-wraps content at a new width, shifting every row's bodyY;
+		// a stale transcript-hover target could coincidentally land on an
+		// unrelated clickable row (same reasoning as clearHover's other callers).
+		m = m.clearHover()
 		// Reset the streaming-text fade state. A width change can re-wrap
 		// the in-progress text into a different number of visual lines,
 		// which invalidates the per-line age mapping. The next delta
@@ -1881,7 +1936,14 @@ func (m model) View() tea.View {
 	view.AltScreen = m.altScreen
 	view.ReportFocus = m.notifier != nil
 	if m.wantsMouseCapture() {
-		view.MouseMode = tea.MouseModeCellMotion
+		// AllMotion (not CellMotion) is required for hover highlighting: it
+		// reports cursor movement even with no button pressed. CellMotion only
+		// reports motion while a button is held (drag) — see bubbletea's
+		// MouseMode docs. AllMotion has marginally worse terminal compatibility
+		// but is well supported by the terminals this app targets; the existing
+		// 15ms mouse-event throttle (mouseEventThrottleInterval) already bounds
+		// the redraw rate from the extra motion events.
+		view.MouseMode = tea.MouseModeAllMotion
 	}
 	return view
 }
@@ -2030,10 +2092,14 @@ func (m model) footerView(width int) string {
 	// while the transcript scrolls underneath (a streaming turn no longer pushes
 	// the plan off-screen). Budgeted to at most a third of the screen height; a
 	// taller plan collapses to a one-line summary so the composer always stays
-	// on screen.
-	if plan := m.renderPinnedPlanPanel(width, m.pinnedPlanMaxHeight()); plan != "" {
-		footer.WriteString(plan)
-		footer.WriteString("\n")
+	// on screen. Skipped in the subchat drill-in: m.plan belongs to the PARENT
+	// run, not the subagent/swarm child session being viewed there, so pinning it
+	// above that composer would show unrelated state.
+	if !m.subchat.active {
+		if plan := m.renderPinnedPlanPanel(width, m.pinnedPlanMaxHeight()); plan != "" {
+			footer.WriteString(plan)
+			footer.WriteString("\n")
+		}
 	}
 	// The row above the composer: transient copy feedback takes priority; otherwise
 	// a faint idle affordance — discoverable key hints on the left, a jump-to-bottom
@@ -3465,6 +3531,18 @@ func (m model) handleSubmit() (tea.Model, tea.Cmd) {
 		m, text = m.handleSelfCorrectCommand(command.text)
 		m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: text})
 		return m, nil
+	case commandTurns:
+		// Changing the budget mid-run would mutate the inherited ZERO_MAX_TURNS env
+		// that sub-agents spawned later in THIS run read, making the run's budget
+		// inconsistent. Require an idle session (the new budget applies next run).
+		if m.pending && strings.TrimSpace(command.text) != "" {
+			m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: "Turns\nFinish or stop the current run before changing the tool-turn budget."})
+			return m, nil
+		}
+		text := ""
+		m, text = m.handleTurnsCommand(command.text)
+		m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: text})
+		return m, nil
 	case commandTheme:
 		text := ""
 		m, text = m.handleThemeCommand(command.text)

internal/tui/mouse.go

@@ -14,6 +14,25 @@ type mouseSelectionTarget struct {
 	Index int
 }
 
+// scrollChatExtendingSelection scrolls the chat and, if a drag-selection is in
+// progress, extends its cursor to the mouse's current position against the
+// POST-scroll viewport — mirroring what a mouseMotion event does. Without this, a
+// selection's cursor is only ever updated by actual mouse movement (see
+// handleTranscriptSelectionMouse's mouseMotion case): a wheel-scroll event is a
+// distinct message type that never reaches that code, so scrolling while
+// selecting left the selection frozen at whatever line the mouse last physically
+// moved over — capped at the viewport that was visible before the scroll.
+func (m model) scrollChatExtendingSelection(delta int, msg tea.MouseMsg) model {
+	m = m.scrollChat(delta)
+	if !m.transcriptSelection.active {
+		return m
+	}
+	if line, ok := m.nearestTranscriptLineAtMouse(msg); ok {
+		m.transcriptSelection.cursor = transcriptSelectionPointForMouse(line, mouseX(msg))
+	}
+	return m
+}
+
 func (m model) handleMouse(msg tea.MouseMsg) (tea.Model, tea.Cmd) {
 	// While a provider-wizard OAuth login is in flight, ignore all mouse input
 	// (clicks and wheel) so a stray scroll can't change the selected provider
@@ -84,10 +103,17 @@ func (m model) handleMouse(msg tea.MouseMsg) (tea.Model, tea.Cmd) {
 	if next, cmd, ok := m.handleTranscriptSelectionMouse(msg); ok {
 		return next, cmd
 	}
+	// A plain hover (cursor moved, no button pressed) never matches the
+	// press/drag/release cases above, so it falls through here — resolve what's
+	// under the cursor so it can render with the hover highlight.
+	if mouseHover(msg) {
+		return m.updateHoverTarget(msg), nil
+	}
 
 	switch {
 	case mouseWheelUp(msg):
 		m.clearMouseSelection()
+		m = m.clearHover()
 		if m.providerWizard != nil {
 			m.providerWizard.move(-1)
 			return m, nil
@@ -116,9 +142,10 @@ func (m model) handleMouse(msg tea.MouseMsg) (tea.Model, tea.Cmd) {
 				return next, nil
 			}
 		}
-		return m.scrollChat(chatWheelScrollLines), nil
+		return m.scrollChatExtendingSelection(chatWheelScrollLines, msg), nil
 	case mouseWheelDown(msg):
 		m.clearMouseSelection()
+		m = m.clearHover()
 		if m.providerWizard != nil {
 			m.providerWizard.move(1)
 			return m, nil
@@ -147,7 +174,7 @@ func (m model) handleMouse(msg tea.MouseMsg) (tea.Model, tea.Cmd) {
 				return next, nil
 			}
 		}
-		return m.scrollChat(-chatWheelScrollLines), nil
+		return m.scrollChatExtendingSelection(-chatWheelScrollLines, msg), nil
 	default:
 		return m, nil
 	}

internal/tui/mouse_test.go

@@ -407,6 +407,245 @@ func TestTranscriptSelectionReleaseExtendsRangeWithoutMotion(t *testing.T) {
 	}
 }
 
+// A completed selection stays "active" through the async copy-command grace
+// window (transcriptCopiedMsg hasn't landed yet), but the drag itself is over.
+// A genuine hover motion (no button held) arriving in that window must NOT be
+// treated as a drag continuation — it must fall through to hover handling
+// instead of silently moving the selection the user just released.
+func TestTranscriptHoverAfterReleaseDoesNotMoveSelection(t *testing.T) {
+	m := withSidebarContent(mouseTestModel())
+	m.mouseCapture = true
+	m.transcript = appendRow(m.transcript, rowUser, "hello world")
+	textY := firstTranscriptTextMouseY(t, m)
+
+	updated, _ := m.Update(testMouseClick(tea.MouseLeft, 3, textY))
+	m = updated.(model)
+	updated, cmd := m.Update(testMouseRelease(tea.MouseNone, 8, textY))
+	m = updated.(model)
+	if cmd == nil {
+		t.Fatal("sanity check failed: release should return the copy command")
+	}
+	if m.transcriptSelection.dragging {
+		t.Fatal("dragging must be false immediately after release")
+	}
+	before := m.selectedTranscriptText()
+
+	// A hover (no button) moves further along the same line, in the window
+	// before transcriptCopiedMsg has landed (m.transcriptSelection.active is
+	// still true here).
+	updated, _ = m.Update(testMouseMotion(tea.MouseNone, 10, textY))
+	m = updated.(model)
+
+	if got := m.selectedTranscriptText(); got != before {
+		t.Fatalf("a post-release hover changed the selection: got %q, want unchanged %q", got, before)
+	}
+}
+
+// Dragging a selection past the top edge of the visible transcript must
+// auto-scroll toward older content and extend the selection to follow — the
+// classic "drag past the viewport edge keeps scrolling" affordance.
+func TestTranscriptSelectionDragPastTopEdgeAutoScrolls(t *testing.T) {
+	m := mouseTestModel()
+	m.mouseCapture = true
+	// This test exercises the animated glide specifically; reducedMotion
+	// defaults from TTY detection (see defaultReducedMotion), which differs
+	// between a local dev shell and CI's non-TTY runners — set it explicitly
+	// so the test is deterministic regardless of environment.
+	m.reducedMotion = false
+	for i := 0; i < 80; i++ {
+		m.transcript = appendRow(m.transcript, rowUser, "line content")
+	}
+	textY := topmostVisibleTranscriptMouseY(t, m)
+
+	updated, _ := m.Update(testMouseClick(tea.MouseLeft, 0, textY))
+	m = updated.(model)
+	if !m.transcriptSelection.active {
+		t.Fatal("selection should be active after a left click on transcript text")
+	}
+	cursorBefore := m.transcriptSelection.cursor.bodyY
+	scrollBefore := m.chatScrollOffset
+
+	frame, _, _ := m.transcriptHitTestLayout()
+	aboveBody := frame.bodyRect.y - 1 // one row above the visible transcript body
+
+	// A left-button drag (not a hover) moved past the top edge: the smooth-glide
+	// chain must start immediately (first step + a scheduled tick).
+	updated, cmd := m.Update(testMouseMotion(tea.MouseLeft, 0, aboveBody))
+	m = updated.(model)
+	if cmd == nil {
+		t.Fatal("crossing the top edge should schedule the glide tick chain")
+	}
+	if m.edgeScrollDelta <= 0 {
+		t.Fatalf("edgeScrollDelta = %d, want > 0 (scrolling toward older content)", m.edgeScrollDelta)
+	}
+	if m.chatScrollOffset == scrollBefore {
+		t.Fatal("dragging past the top edge should auto-scroll toward older content")
+	}
+
+	// A single small step may land on a blank spacer row between messages (no
+	// text there yet) — drive the tick chain forward like a sustained real hold
+	// would, and the cursor must eventually reach a genuinely earlier line.
+	for i := 0; i < 10 && m.transcriptSelection.cursor.bodyY >= cursorBefore; i++ {
+		updated, _ = m.Update(dragEdgeScrollTickMsg{seq: m.edgeScrollSeq})
+		m = updated.(model)
+	}
+
+	if !m.transcriptSelection.active {
+		t.Fatal("selection must survive an edge auto-scroll, not be cleared")
+	}
+	if m.transcriptSelection.cursor.bodyY >= cursorBefore {
+		t.Fatalf("selection cursor bodyY = %d, want < %d (it must extend upward to follow the drag)", m.transcriptSelection.cursor.bodyY, cursorBefore)
+	}
+}
+
+// Symmetric to the top-edge case: dragging past the BOTTOM edge scrolls toward
+// newer content. Requires scrolling up first so there's somewhere to scroll back
+// down to (chatScrollOffset=0 already sits at the bottom).
+func TestTranscriptSelectionDragPastBottomEdgeAutoScrolls(t *testing.T) {
+	m := mouseTestModel()
+	m.mouseCapture = true
+	m.reducedMotion = false // deterministic across local/CI TTY-detection differences
+	for i := 0; i < 80; i++ {
+		m.transcript = appendRow(m.transcript, rowUser, "line content")
+	}
+	m.chatScrollOffset = chatWheelScrollLines * 3 // scrolled up, away from the bottom
+
+	textY := topmostVisibleTranscriptMouseY(t, m)
+	updated, _ := m.Update(testMouseClick(tea.MouseLeft, 0, textY))
+	m = updated.(model)
+	if !m.transcriptSelection.active {
+		t.Fatal("selection should be active after a left click on transcript text")
+	}
+	cursorBefore := m.transcriptSelection.cursor.bodyY
+	scrollBefore := m.chatScrollOffset
+
+	frame, _, _ := m.transcriptHitTestLayout()
+	belowBody := frame.bodyRect.y + frame.bodyRect.height // one row below the visible transcript body
+
+	updated, cmd := m.Update(testMouseMotion(tea.MouseLeft, 0, belowBody))
+	m = updated.(model)
+	if cmd == nil {
+		t.Fatal("crossing the bottom edge should schedule the glide tick chain")
+	}
+	if m.edgeScrollDelta >= 0 {
+		t.Fatalf("edgeScrollDelta = %d, want < 0 (scrolling toward newer content)", m.edgeScrollDelta)
+	}
+	if m.chatScrollOffset >= scrollBefore {
+		t.Fatal("dragging past the bottom edge should auto-scroll toward newer content (offset decreases)")
+	}
+
+	for i := 0; i < 10 && m.transcriptSelection.cursor.bodyY <= cursorBefore; i++ {
+		updated, _ = m.Update(dragEdgeScrollTickMsg{seq: m.edgeScrollSeq})
+		m = updated.(model)
+	}
+
+	if !m.transcriptSelection.active {
+		t.Fatal("selection must survive an edge auto-scroll, not be cleared")
+	}
+	if m.transcriptSelection.cursor.bodyY <= cursorBefore {
+		t.Fatalf("selection cursor bodyY = %d, want > %d (it must extend downward to follow the drag)", m.transcriptSelection.cursor.bodyY, cursorBefore)
+	}
+}
+
+// The glide tick chain must self-terminate the instant the drag moves back into
+// the visible body — otherwise a stray scheduled tick could keep scrolling after
+// the user has already dragged back to the content they wanted selected.
+func TestTranscriptSelectionEdgeGlideStopsWhenDragReturnsToBody(t *testing.T) {
+	m := mouseTestModel()
+	m.mouseCapture = true
+	m.reducedMotion = false // deterministic across local/CI TTY-detection differences
+	for i := 0; i < 80; i++ {
+		m.transcript = appendRow(m.transcript, rowUser, "line content")
+	}
+	textY := topmostVisibleTranscriptMouseY(t, m)
+
+	updated, _ := m.Update(testMouseClick(tea.MouseLeft, 0, textY))
+	m = updated.(model)
+	frame, _, _ := m.transcriptHitTestLayout()
+	updated, _ = m.Update(testMouseMotion(tea.MouseLeft, 0, frame.bodyRect.y-1))
+	m = updated.(model)
+	if m.edgeScrollDelta == 0 {
+		t.Fatal("sanity check failed: the glide chain should be running")
+	}
+	seqWhileGliding := m.edgeScrollSeq
+
+	updated, _ = m.Update(testMouseMotion(tea.MouseLeft, 0, textY))
+	m = updated.(model)
+	if m.edgeScrollDelta != 0 {
+		t.Fatalf("edgeScrollDelta = %d, want 0 (dragging back into the body must stop the glide)", m.edgeScrollDelta)
+	}
+
+	// A tick already in flight from before the drag returned must be a no-op —
+	// it carries the OLD seq, which no longer matches.
+	scrollBefore := m.chatScrollOffset
+	updated, _ = m.Update(dragEdgeScrollTickMsg{seq: seqWhileGliding})
+	m = updated.(model)
+	if m.chatScrollOffset != scrollBefore {
+		t.Fatal("a stale in-flight tick must not scroll after the glide was stopped")
+	}
+}
+
+// A keypress mid-glide clears m.transcriptSelection.active directly (the
+// KeyPressMsg handler in model.go), NOT through stopEdgeScroll — so
+// edgeScrollDelta is left stale. If a fresh drag past the SAME edge afterward
+// doesn't reset it, startEdgeScroll's "already running" fast path is fooled into
+// thinking a chain is already active and silently does nothing: no immediate
+// step, no scheduled tick. The press handler must reset glide state so every new
+// drag starts clean regardless of how the previous one ended.
+func TestTranscriptSelectionEdgeGlideRecoversAfterKeypressInterrupt(t *testing.T) {
+	m := mouseTestModel()
+	m.mouseCapture = true
+	m.reducedMotion = false // deterministic across local/CI TTY-detection differences
+	for i := 0; i < 80; i++ {
+		m.transcript = appendRow(m.transcript, rowUser, "line content")
+	}
+	textY := topmostVisibleTranscriptMouseY(t, m)
+
+	updated, _ := m.Update(testMouseClick(tea.MouseLeft, 0, textY))
+	m = updated.(model)
+	frame, _, _ := m.transcriptHitTestLayout()
+	aboveBody := frame.bodyRect.y - 1
+
+	updated, _ = m.Update(testMouseMotion(tea.MouseLeft, 0, aboveBody))
+	m = updated.(model)
+	if m.edgeScrollDelta == 0 {
+		t.Fatal("sanity check failed: the glide chain should be running")
+	}
+
+	// A keypress interrupts the drag WITHOUT releasing the mouse — clears
+	// transcriptSelection.active directly, bypassing stopEdgeScroll.
+	updated, _ = m.Update(testKey('a'))
+	m = updated.(model)
+	if m.transcriptSelection.active {
+		t.Fatal("sanity check failed: the keypress should have cleared the selection")
+	}
+	if m.edgeScrollDelta == 0 {
+		t.Fatal("sanity check failed: edgeScrollDelta should still be stale here (that's the bug this test guards)")
+	}
+
+	// A brand-new press+drag past the SAME edge must glide normally, not be
+	// silently swallowed by the stale state from the interrupted drag. The
+	// viewport shifted from the first glide's step, so the topmost visible text
+	// line's on-screen Y must be recomputed — reusing the ORIGINAL textY would
+	// fail for an unrelated reason (it may now land on a blank spacer row).
+	textY = topmostVisibleTranscriptMouseY(t, m)
+	updated, _ = m.Update(testMouseClick(tea.MouseLeft, 0, textY))
+	m = updated.(model)
+	if !m.transcriptSelection.active {
+		t.Fatal("sanity check failed: the new press should start a fresh selection")
+	}
+	scrollBefore := m.chatScrollOffset
+
+	updated, cmd := m.Update(testMouseMotion(tea.MouseLeft, 0, aboveBody))
+	m = updated.(model)
+	if cmd == nil {
+		t.Fatal("the new drag should schedule a fresh glide tick chain, not be fooled by stale state")
+	}
+	if m.chatScrollOffset == scrollBefore {
+		t.Fatal("the new drag should have applied its immediate first scroll step")
+	}
+}
+
 func TestTranscriptSelectionClearsAfterCopy(t *testing.T) {
 	m := mouseTestModel()
 	m.transcriptSelection = transcriptSelectionState{active: true}

internal/tui/session_controls.go

@@ -9,6 +9,7 @@ import (
 	tea "charm.land/bubbletea/v2"
 
 	"github.com/Gitlawb/zero/internal/agent"
+	"github.com/Gitlawb/zero/internal/config"
 	"github.com/Gitlawb/zero/internal/modelregistry"
 	"github.com/Gitlawb/zero/internal/sessions"
 	"github.com/Gitlawb/zero/internal/usage"
@@ -256,6 +257,42 @@ func (m model) handleSelfCorrectCommand(args string) (model, string) {
 	return m, m.selfCorrectText()
 }
 
+// maxTurnsCeiling caps the per-session /turns budget so a typo (e.g. /turns 99999)
+// can't set an absurd ceiling; real multi-step tasks fit comfortably under it. Shared
+// with config so applyEnv enforces the same bound on an inherited ZERO_MAX_TURNS.
+const maxTurnsCeiling = config.MaxTurnsCeiling
+
+func (m model) handleTurnsCommand(args string) (model, string) {
+	args = strings.TrimSpace(args)
+	if args == "" || strings.EqualFold(args, "status") {
+		return m, m.turnsText()
+	}
+	n, err := strconv.Atoi(args)
+	if err != nil || n < 1 {
+		return m, "Turns\nUsage: /turns <n> — set the per-run tool-turn budget for this session (a positive number, e.g. /turns 150)."
+	}
+	if n > maxTurnsCeiling {
+		n = maxTurnsCeiling
+	}
+	m.agentOptions.MaxTurns = n
+	// Propagate the budget to spawned sub-agents / swarm members (which inherit the
+	// environment) so a delegated task gets the same budget, not config.json's default.
+	config.SetMaxTurnsEnv(n)
+	return m, m.turnsText()
+}
+
+func (m model) turnsText() string {
+	return renderCommandOutput(commandOutput{
+		Title:  "Turns",
+		Status: commandStatusOK,
+		Sections: []commandSection{{
+			Title: "State",
+			Lines: []string{fmt.Sprintf("max tool-turns per run: %d", m.agentOptions.MaxTurns)},
+		}},
+		Hints: []string{fmt.Sprintf("/turns <n> sets this session's tool-turn budget (max %d); raise it for long multi-step tasks like delegation/swarm runs", maxTurnsCeiling)},
+	})
+}
+
 func (m model) selfCorrectText() string {
 	depth := "LSP diagnostics only — fast, scoped to changed files"
 	if m.selfCorrectTests {

internal/tui/sidebar.go

@@ -17,6 +17,7 @@ import (
 	"time"
 
 	"charm.land/lipgloss/v2"
+	"github.com/charmbracelet/x/ansi"
 
 	"github.com/Gitlawb/zero/internal/tools"
 )
@@ -607,6 +608,15 @@ func (m model) renderContextSidebar(width, height int) []string {
 	}
 	add(tokenLine)
 
+	// Hover highlight: resolved by STABLE IDENTITY (sessionID / stepIndex), not a
+	// cached line offset — see hoveredSidebarLineOffset. A row whose identity no
+	// longer resolves (it disappeared since the hover was last set from a real
+	// mouse motion) simply doesn't highlight, rather than a coincidentally-matching
+	// unrelated row lighting up.
+	if lineOffset, ok := m.hoveredSidebarLineOffset(width); ok && lineOffset >= 0 && lineOffset < len(lines) {
+		lines[lineOffset] = zeroTheme.hover.Render(ansi.Strip(lines[lineOffset]))
+	}
+
 	// Normalize every row to exactly width cells.
 	for i := range lines {
 		lines[i] = padStyledLine(lines[i], width)
@@ -620,6 +630,31 @@ func (m model) renderContextSidebar(width, height int) []string {
 	return lines
 }
 
+// hoveredSidebarLineOffset resolves the hovered sidebar row's CURRENT line offset
+// fresh on every call, by re-matching m.hover's stable identity (sessionID for an
+// agent, stepIndex for a plan step) against a freshly computed hit list — never a
+// cached index. Returns false when the hover isn't sidebar-scoped, or when the
+// identity no longer resolves (that row disappeared since the hover was last set
+// by a real mouse motion — a linger window elapsing, a plan step completing —
+// with no intervening motion to re-target it).
+func (m model) hoveredSidebarLineOffset(width int) (int, bool) {
+	switch m.hover.kind {
+	case hoverSidebarAgent:
+		for _, hit := range m.sidebarAgentSelectables(width) {
+			if hit.sessionID == m.hover.sessionID {
+				return hit.lineOffset, true
+			}
+		}
+	case hoverPlanStep:
+		for _, hit := range m.sidebarPlanSelectables(width) {
+			if hit.stepIndex == m.hover.stepIndex {
+				return hit.lineOffset, true
+			}
+		}
+	}
+	return 0, false
+}
+
 // sidebarHeader renders a bold-muted uppercase section label. Bold muted (vs the
 // faint body items and placeholders) gives the header enough weight to read as a
 // section heading rather than more filler. The width arg is unused — kept so it

internal/tui/subchat_regression_test.go

@@ -0,0 +1,118 @@
+package tui
+
+import (
+	"strings"
+	"testing"
+
+	tea "charm.land/bubbletea/v2"
+)
+
+// The subchat drill-in (viewing a subagent/swarm child session) swaps the on-screen
+// transcript to m.subchat.childRows, but mouse hit-testing and the footer's pinned
+// plan panel were never made subchat-aware — they kept operating on/showing the
+// PARENT run's state while the child session was on screen. These tests guard the
+// fix: mouse selection must resolve against the child rows, the plan panel must not
+// show in that view, and a selection in progress must extend across a wheel-scroll
+// instead of freezing at whatever was visible when the drag started.
+
+func TestFooterHidesPlanPanelDuringSubchat(t *testing.T) {
+	m := runningPlanModel(t, 3)
+	m.altScreen = true
+	m.height = 30
+	width := m.chatColumnWidth()
+
+	withoutSubchat := m.footerView(width)
+	if !strings.Contains(withoutSubchat, "Step number 1 here") {
+		t.Fatalf("sanity check failed: pinned plan panel should render outside subchat, got:\n%s", withoutSubchat)
+	}
+
+	m.subchat.active = true
+	m.subchat.childSessionID = "child-1"
+	withSubchat := m.footerView(width)
+	if strings.Contains(withSubchat, "Step number 1 here") {
+		t.Fatalf("plan panel must NOT show while viewing a subchat child session, got:\n%s", withSubchat)
+	}
+}
+
+func TestTranscriptSelectionInSubchatUsesChildSessionRows(t *testing.T) {
+	m := mouseTestModel()
+	m.mouseCapture = true
+	// Parent transcript has DIFFERENT text than the child session: if selection
+	// hit-tests against the wrong (parent) rows, this proves it by either matching
+	// nothing or matching the wrong text.
+	m.transcript = appendRow(m.transcript, rowUser, "parent transcript text")
+	m.subchat.active = true
+	m.subchat.childSessionID = "child-1"
+	m.subchat.childRows = appendRow(nil, rowUser, "hello world")
+
+	textY := topmostVisibleTranscriptMouseY(t, m)
+	updated, _ := m.Update(testMouseClick(tea.MouseLeft, 3, textY))
+	m = updated.(model)
+	updated, _ = m.Update(testMouseMotion(tea.MouseLeft, 8, textY))
+	m = updated.(model)
+
+	if got := m.selectedTranscriptText(); got != "hello" {
+		t.Fatalf("selectedTranscriptText() in subchat = %q, want hello (from the CHILD session's rows)", got)
+	}
+}
+
+func TestTranscriptSelectionExtendsAcrossWheelScroll(t *testing.T) {
+	m := mouseTestModel()
+	m.mouseCapture = true
+	// Enough rows that the transcript overflows the viewport, so a wheel-scroll is
+	// a real (non-clamped) scroll. chatScrollOffset=0 anchors to the BOTTOM (newest
+	// content, see transcriptViewport.window: start = totalLines-height-offset), so
+	// with overflow content the topmost VISIBLE line is not the transcript's first
+	// line — topmostVisibleTranscriptMouseY (window-aware) finds it correctly.
+	for i := 0; i < 80; i++ {
+		m.transcript = appendRow(m.transcript, rowUser, "line content")
+	}
+	textY := topmostVisibleTranscriptMouseY(t, m)
+
+	updated, _ := m.Update(testMouseClick(tea.MouseLeft, 0, textY))
+	m = updated.(model)
+	if !m.transcriptSelection.active {
+		t.Fatal("selection should be active after a left click on transcript text")
+	}
+	cursorBefore := m.transcriptSelection.cursor.bodyY
+	scrollBefore := m.chatScrollOffset
+
+	// Wheel UP reveals OLDER content above (offset increases -> window.start
+	// decreases): re-evaluating the SAME on-screen Y afterward must land on an
+	// EARLIER (smaller bodyY) line now that the viewport has shifted, extending the
+	// selection upward instead of leaving the cursor pinned to the pre-scroll line.
+	updated, _ = m.Update(testMouseWheel(tea.MouseWheelUp, 0, textY))
+	m = updated.(model)
+
+	if m.chatScrollOffset == scrollBefore {
+		t.Fatal("sanity check failed: wheel-up should have scrolled (80 rows overflow a 30-row terminal)")
+	}
+	if !m.transcriptSelection.active {
+		t.Fatal("selection must survive a wheel-scroll, not be cleared")
+	}
+	if m.transcriptSelection.cursor.bodyY >= cursorBefore {
+		t.Fatalf("selection cursor bodyY = %d, want < %d (it must extend to follow the scroll, not freeze)", m.transcriptSelection.cursor.bodyY, cursorBefore)
+	}
+}
+
+// topmostVisibleTranscriptMouseY returns the on-screen Y of the topmost currently
+// VISIBLE selectable text line — window-aware (unlike firstTranscriptTextMouseY,
+// which walks the full unwindowed layout and only lands on-screen when everything
+// fits in one viewport). It resolves against transcriptHitTestSource, the same
+// subchat-aware source transcriptLineAtMouse uses, so it works for both the parent
+// transcript and a subchat child session.
+func topmostVisibleTranscriptMouseY(t *testing.T, m model) int {
+	t.Helper()
+	header, items, width := m.transcriptHitTestSource()
+	frame := m.scrollableTranscriptFrame(header, m.footerView(width))
+	metrics := measureTranscriptBodyItems(items, m.transcriptBodyHeights)
+	window := transcriptViewportForLayout(metrics, frame, m.chatScrollOffset).window()
+	layout := layoutVisibleTranscriptBodyItems(items, metrics, window)
+	for _, line := range layout.selectable {
+		if line.text != "" && !line.toggle {
+			return frame.bodyRect.y + (line.bodyY - window.start)
+		}
+	}
+	t.Fatalf("no selectable visible transcript text line found: %#v", layout.selectable)
+	return 0
+}

internal/tui/theme.go

@@ -29,6 +29,7 @@ type tuiTheme struct {
 	line       lipgloss.Style // default borders, rules, status separators
 	lineStrong lipgloss.Style // emphasized borders
 	selection  lipgloss.Style // transcript selection highlight
+	hover      lipgloss.Style // hovered clickable row (specialist card, toggle, sidebar/plan row)
 
 	// Title bar.
 	badge lipgloss.Style // ` 0 ` brand chip: onAccent on accent, bold
@@ -210,6 +211,13 @@ func buildTheme(p palette) tuiTheme {
 		line:       fg(p.line),
 		lineStrong: fg(p.line2),
 		selection:  lipgloss.NewStyle().Background(col(p.accent)).Foreground(col(p.onAccent)),
+		// A full block (like selection) would be too heavy for something that
+		// repaints on every mouse movement; a soft foreground reads as
+		// "interactive" at a glance without competing with real content colors
+		// (e.g. a specialist card's red/green status glyph). Amber (not the brand
+		// lime accent) — lime read as too glaring for something that repaints
+		// continuously as the cursor moves.
+		hover: fg(p.amber),
 
 		badge: lipgloss.NewStyle().Background(col(p.accent)).Foreground(col(p.onAccent)).Bold(true),
 

internal/tui/transcript_selection.go

@@ -22,8 +22,20 @@ type transcriptSelectionPoint struct {
 
 type transcriptSelectionState struct {
 	active bool
-	anchor transcriptSelectionPoint
-	cursor transcriptSelectionPoint
+	// dragging is true from press until release — narrower than active, which
+	// stays true through the async copy-command grace window after release (a
+	// non-empty selection isn't reset to {} until transcriptCopiedMsg lands).
+	// mouseMotion gates on THIS, not active, so a genuine hover motion arriving
+	// in that post-release window doesn't get misrouted as a drag continuation.
+	// It also deliberately does NOT require msg's own Button field to be
+	// non-None on each motion event: some terminals don't restate the button on
+	// every motion report during a real drag (see
+	// TestTranscriptSelectionUpdatesOnGenericMotion), so trusting the
+	// per-event button field would break those terminals — dragging tracks the
+	// app's own press/release bracket instead.
+	dragging bool
+	anchor   transcriptSelectionPoint
+	cursor   transcriptSelectionPoint
 }
 
 type transcriptSelectableLine struct {
@@ -159,10 +171,45 @@ func (m model) finalizeTranscriptBodyRow(rendered string, selectable []transcrip
 	shifted := shiftSelectableX(selectable, gutter)
 	if m.transcriptSelection.active {
 		lines = viewLines(m.renderRenderedSelection(strings.Join(lines, "\n"), shifted, startBodyY))
+	} else if m.hover.kind == hoverTranscript {
+		// Mutually exclusive with the selection highlight above: transcriptSelection
+		// stays active for the lifetime of a persisted (copied) selection, not just
+		// during the drag — so hover correctly stays suppressed over old selected
+		// text too, not only mid-drag.
+		lines = viewLines(m.renderHoverHighlight(strings.Join(lines, "\n"), shifted, startBodyY))
 	}
 	return transcriptBodyRenderedItem{lines: lines, selectable: shifted}
 }
 
+// renderHoverHighlight re-styles the WHOLE line at m.hover.bodyY in the hover
+// accent (see renderRenderedSelection for the sibling selection-highlight logic,
+// which this mirrors). Only a clickable line (a specialist card or a
+// collapse/expand toggle header) is eligible — if the hovered bodyY no longer
+// matches one (content shifted beneath a stale hover target), this is a no-op,
+// which self-heals a hover left over from before a transcript update.
+func (m model) renderHoverHighlight(rendered string, selectable []transcriptSelectableLine, startBodyY int) string {
+	index := m.hover.bodyY - startBodyY
+	if index < 0 {
+		return rendered
+	}
+	lines := viewLines(rendered)
+	if index >= len(lines) {
+		return rendered
+	}
+	matched := false
+	for _, line := range selectable {
+		if line.bodyY == m.hover.bodyY && (line.specialistCard || line.toggle) {
+			matched = true
+			break
+		}
+	}
+	if !matched {
+		return rendered
+	}
+	lines[index] = zeroTheme.hover.Render(ansi.Strip(lines[index]))
+	return strings.Join(lines, "\n")
+}
+
 func (m model) transcriptBodyItems(width int, emptyOverlay string) []transcriptBodyItem {
 	items := []transcriptBodyItem{}
 	// Transcript ROWS render at the full chat width; row/status glyphs provide
@@ -968,16 +1015,46 @@ func splitPlainAtDisplayWidth(text string, width int) (string, string) {
 	return text, ""
 }
 
+// transcriptHitTestSource returns the header/body-items/width mouse hit-testing
+// must use to match what's actually on screen. It mirrors transcriptView's own
+// branching exactly: the subchat drill-in swaps BOTH the header (nav bar instead
+// of the pinned title bar) and the row source (the child session's rows instead
+// of the parent transcript) — and drops the sidebar-reserved width, since subchat
+// is always single-column. Hit-testing against the wrong source is why mouse
+// selection previously resolved against transcript rows that weren't even
+// visible while viewing a subagent/swarm child session.
+func (m model) transcriptHitTestSource() (header string, items []transcriptBodyItem, width int) {
+	if m.subchat.active {
+		width = chatWidth(m.width)
+		return renderSubchatNavBar(m.subchat.childSessionTitle, width), m.transcriptBodyItemsFromRows(m.subchat.childRows, width), width
+	}
+	width = m.chatColumnWidth()
+	return m.pinnedTitleBar(width), m.transcriptBodyItems(width, ""), width
+}
+
+// transcriptHitTestBlocked reports whether mouse hit-testing must be skipped
+// outright — a modal/overlay is up, or there's no alt-screen viewport at all.
+func (m model) transcriptHitTestBlocked() bool {
+	return !m.altScreen || m.height <= 0 || m.setup.visible || m.providerWizard != nil || m.mcpAddWizard != nil || m.mcpManager != nil || m.picker != nil || m.suggestionsActive()
+}
+
+// transcriptHitTestLayout computes the frame/window/layout mouse hit-testing needs,
+// shared by transcriptLineAtMouse (exact match) and nearestTranscriptLineAtMouse
+// (nearest-line fallback for scroll-driven selection extension).
+func (m model) transcriptHitTestLayout() (frame transcriptFrameLayout, window transcriptViewportWindow, layout transcriptBodyLayout) {
+	header, items, width := m.transcriptHitTestSource()
+	frame = m.scrollableTranscriptFrame(header, m.footerView(width))
+	metrics := measureTranscriptBodyItems(items, m.transcriptBodyHeights)
+	window = transcriptViewportForLayout(metrics, frame, m.chatScrollOffset).window()
+	layout = layoutVisibleTranscriptBodyItems(items, metrics, window)
+	return frame, window, layout
+}
+
 func (m model) transcriptLineAtMouse(msg tea.MouseMsg) (transcriptSelectableLine, bool) {
-	if !m.altScreen || m.height <= 0 || m.setup.visible || m.providerWizard != nil || m.mcpAddWizard != nil || m.mcpManager != nil || m.picker != nil || m.suggestionsActive() {
+	if m.transcriptHitTestBlocked() {
 		return transcriptSelectableLine{}, false
 	}
-	width := m.chatColumnWidth()
-	frame := m.scrollableTranscriptFrame(m.pinnedTitleBar(width), m.footerView(width))
-	items := m.transcriptBodyItems(width, "")
-	metrics := measureTranscriptBodyItems(items, m.transcriptBodyHeights)
-	window := transcriptViewportForLayout(metrics, frame, m.chatScrollOffset).window()
-	layout := layoutVisibleTranscriptBodyItems(items, metrics, window)
+	frame, window, layout := m.transcriptHitTestLayout()
 	_, localY, ok := frame.bodyRect.local(mouseX(msg), mouseY(msg))
 	if !ok {
 		return transcriptSelectableLine{}, false
@@ -995,6 +1072,146 @@ func (m model) transcriptLineAtMouse(msg tea.MouseMsg) (transcriptSelectableLine
 	return transcriptSelectableLine{}, false
 }
 
+// nearestTranscriptLineAtMouse is transcriptLineAtMouse with a fallback for
+// scroll-driven selection extension: the recomputed on-screen position can land
+// exactly on a non-selectable spacer row between messages (blank lines aren't in
+// layout.selectable; a scroll can shift which physical row is text vs spacer), where
+// an EXACT match finds nothing even though real text sits one row away. Falls back
+// to the closest visible selectable line by bodyY, so the selection still extends
+// instead of silently freezing for that scroll tick. Only used for scroll
+// extension — a plain click keeps using transcriptLineAtMouse's exact match, since
+// "nothing there" is a meaningful, correct result for an intentional click below
+// the last line or in dead space.
+func (m model) nearestTranscriptLineAtMouse(msg tea.MouseMsg) (transcriptSelectableLine, bool) {
+	if line, ok := m.transcriptLineAtMouse(msg); ok {
+		return line, true
+	}
+	if m.transcriptHitTestBlocked() {
+		return transcriptSelectableLine{}, false
+	}
+	frame, window, layout := m.transcriptHitTestLayout()
+	_, localY, ok := frame.bodyRect.local(mouseX(msg), mouseY(msg))
+	if !ok || mouseX(msg) < 0 {
+		return transcriptSelectableLine{}, false
+	}
+	return nearestTranscriptSelectableAt(layout, window.start+localY)
+}
+
+// nearestTranscriptSelectableAt returns the selectable line in layout closest to
+// targetBodyY (ties go to whichever is found first) — the fallback core shared by
+// nearestTranscriptLineAtMouse (target derived from a mouse position that may
+// have shifted onto a non-selectable spacer row) and the edge-auto-scroll drag
+// case (target derived directly from the new viewport's top/bottom bound, which
+// has no "mouse position" to speak of at all).
+func nearestTranscriptSelectableAt(layout transcriptBodyLayout, targetBodyY int) (transcriptSelectableLine, bool) {
+	best := transcriptSelectableLine{}
+	bestDist := -1
+	found := false
+	for _, line := range layout.selectable {
+		dist := line.bodyY - targetBodyY
+		if dist < 0 {
+			dist = -dist
+		}
+		if !found || dist < bestDist {
+			best, bestDist, found = line, dist, true
+		}
+	}
+	return best, found
+}
+
+// transcriptEdgeScrollDelta reports the scroll delta to apply when a drag has
+// moved past the top or bottom edge of the visible transcript body while
+// staying within its horizontal span — the classic "drag past the viewport
+// edge auto-scrolls" affordance from browsers/editors. Positive reveals OLDER
+// content (dragged above the top edge, same sign convention as wheel-up);
+// negative reveals NEWER content (dragged below the bottom edge). ok is false
+// when the point isn't a vertical-edge case at all (e.g. off to the side, over
+// the sidebar) — that's not an edge-scroll, just outside the column.
+func (m model) transcriptEdgeScrollDelta(msg tea.MouseMsg) (int, bool) {
+	if m.transcriptHitTestBlocked() {
+		return 0, false
+	}
+	frame, _, _ := m.transcriptHitTestLayout()
+	x, y := mouseX(msg), mouseY(msg)
+	if x < frame.bodyRect.x || x >= frame.bodyRect.x+frame.bodyRect.width {
+		return 0, false
+	}
+	if y < frame.bodyRect.y {
+		return chatWheelScrollLines, true
+	}
+	if y >= frame.bodyRect.y+frame.bodyRect.height {
+		return -chatWheelScrollLines, true
+	}
+	return 0, false
+}
+
+// dragToEdgeScroll scrolls one step toward the edge the drag moved past, then
+// extends the selection cursor to whichever line now sits at THAT edge of the
+// new viewport, at column x. It deliberately does NOT try to re-resolve the
+// drag's (still off-screen) physical mouse position — after scrolling, that
+// position is still outside frame.bodyRect (scrolling changes what content
+// occupies a screen row, not the mouse's screen position), so
+// nearestTranscriptLineAtMouse would keep finding nothing. Anchoring to the
+// viewport edge instead is what makes the selection visibly keep pace with the
+// drag while the mouse holds past the edge. Takes a plain column rather than a
+// tea.MouseMsg because the smooth-glide tick chain (dragEdgeScrollTickMsg) calls
+// this repeatedly with no real mouse event of its own — see edgeScrollMouseX.
+func (m model) dragToEdgeScroll(delta int, x int) model {
+	m = m.scrollChat(delta)
+	_, window, layout := m.transcriptHitTestLayout()
+	target := window.start
+	if delta < 0 {
+		target = window.start + window.height - 1
+	}
+	if line, ok := nearestTranscriptSelectableAt(layout, target); ok {
+		m.transcriptSelection.cursor = transcriptSelectionPointForMouse(line, x)
+	}
+	return m
+}
+
+// dragEdgeScrollTickCmd schedules the next step of the smooth-glide edge-scroll,
+// gated by seq (see dragEdgeScrollTickMsg / edgeScrollSeq).
+func dragEdgeScrollTickCmd(seq int) tea.Cmd {
+	return tea.Tick(dragEdgeScrollInterval, func(time.Time) tea.Msg {
+		return dragEdgeScrollTickMsg{seq: seq}
+	})
+}
+
+// startEdgeScroll (re)starts the smooth-glide tick chain in the given direction —
+// a no-op if it's already running the SAME direction (a fresh raw motion event
+// arriving mid-glide must not reset the cadence, or repeated events faster than
+// dragEdgeScrollInterval would make it jerky again, defeating the point). x is
+// remembered for the ticks, which carry no mouse position of their own. Applies
+// one immediate step so there's no perceptible delay between crossing the edge
+// and the first visible movement.
+func (m model) startEdgeScroll(direction int, x int) (model, tea.Cmd) {
+	step := dragEdgeScrollStep
+	if direction < 0 {
+		step = -step
+	}
+	if m.edgeScrollDelta == step {
+		m.edgeScrollMouseX = x
+		return m, nil
+	}
+	m = m.dragToEdgeScroll(step, x)
+	m.edgeScrollDelta = step
+	m.edgeScrollMouseX = x
+	m.edgeScrollSeq++
+	return m, dragEdgeScrollTickCmd(m.edgeScrollSeq)
+}
+
+// stopEdgeScroll ends the smooth-glide tick chain (the drag moved back into the
+// body, off to the side, or released). Bumping edgeScrollSeq invalidates any
+// tick already in flight, so it lands as a no-op and doesn't reschedule itself.
+func (m model) stopEdgeScroll() model {
+	if m.edgeScrollDelta == 0 {
+		return m
+	}
+	m.edgeScrollDelta = 0
+	m.edgeScrollSeq++
+	return m
+}
+
 func (m model) transcriptViewportStart(body string, width int) (int, int, int) {
 	frame := m.scrollableTranscriptFrame(m.pinnedTitleBar(width), m.footerView(width))
 	return transcriptViewportStartForFrame(body, frame, m.chatScrollOffset)
@@ -1029,6 +1246,7 @@ func (m model) handleTranscriptSelectionMouse(msg tea.MouseMsg) (model, tea.Cmd,
 				m = m.appendSystemNotice(errMsg)
 			}
 			m.chatScrollOffset = 0
+			m = m.clearHover() // bodyY numbering differs between subchat and the parent transcript
 			return m, nil, true
 		}
 		// A click on a PLAN step row drops a transcript card listing the file
@@ -1058,6 +1276,7 @@ func (m model) handleTranscriptSelectionMouse(msg tea.MouseMsg) (model, tea.Cmd,
 				m = m.appendSystemNotice(errMsg)
 			}
 			m.chatScrollOffset = 0
+			m = m.clearHover() // bodyY numbering differs between subchat and the parent transcript
 			return m, nil, true
 		}
 		if line.toggle {
@@ -1070,21 +1289,57 @@ func (m model) handleTranscriptSelectionMouse(msg tea.MouseMsg) (model, tea.Cmd,
 		}
 		point := transcriptSelectionPointForMouse(line, mouseX(msg))
 		m.copyStatus = ""
-		m.transcriptSelection = transcriptSelectionState{active: true, anchor: point, cursor: point}
+		m.transcriptSelection = transcriptSelectionState{active: true, dragging: true, anchor: point, cursor: point}
+		// A fresh press always starts a brand-new drag: reset any glide state left
+		// over from a PREVIOUS selection that ended without going through
+		// stopEdgeScroll (e.g. a keypress mid-drag clears transcriptSelection.active
+		// directly, model.go's KeyPressMsg handler). Without this, a stale
+		// edgeScrollDelta can coincidentally match this new drag's direction and
+		// fool startEdgeScroll's "already running" fast path into silently doing
+		// nothing for the whole hold.
+		m = m.stopEdgeScroll()
 		return m, nil, true
 	case mouseMotion(msg):
-		if !m.transcriptSelection.active {
+		// Gate on dragging (the app's own press/release bracket), not active
+		// alone: active stays true through the async copy-command grace window
+		// after release, so without this a genuine hover motion arriving in
+		// that window would be misrouted here and silently move the
+		// just-released selection instead of falling through to hover
+		// handling. Deliberately NOT gated on msg's own Button field — see
+		// transcriptSelectionState.dragging's doc comment.
+		if !m.transcriptSelection.dragging {
 			return m, nil, false
 		}
-		line, ok := m.transcriptLineAtMouse(msg)
-		if ok {
+		if line, ok := m.transcriptLineAtMouse(msg); ok {
 			m.transcriptSelection.cursor = transcriptSelectionPointForMouse(line, mouseX(msg))
+			m = m.stopEdgeScroll() // back inside the body: any running glide ends
+			return m, nil, true
 		}
-		return m, nil, true
+		// The drag moved past the top/bottom edge of the visible transcript:
+		// auto-scroll toward that side and extend the selection to follow.
+		delta, ok := m.transcriptEdgeScrollDelta(msg)
+		if !ok {
+			m = m.stopEdgeScroll() // off to the side (e.g. over the sidebar), not an edge case
+			return m, nil, true
+		}
+		if m.reducedMotion {
+			// No animated glide: a single, larger step per raw motion event,
+			// matching the app's reduced-motion convention elsewhere.
+			m = m.dragToEdgeScroll(delta, mouseX(msg))
+			return m, nil, true
+		}
+		direction := 1
+		if delta < 0 {
+			direction = -1
+		}
+		var cmd tea.Cmd
+		m, cmd = m.startEdgeScroll(direction, mouseX(msg))
+		return m, cmd, true
 	case mouseRelease(msg):
 		if !m.transcriptSelection.active {
 			return m, nil, false
 		}
+		m = m.stopEdgeScroll()
 		if line, ok := m.transcriptLineAtMouse(msg); ok {
 			m.transcriptSelection.cursor = transcriptSelectionPointForMouse(line, mouseX(msg))
 		}
@@ -1093,6 +1348,10 @@ func (m model) handleTranscriptSelectionMouse(msg tea.MouseMsg) (model, tea.Cmd,
 			m.transcriptSelection = transcriptSelectionState{}
 			return m, nil, true
 		}
+		// The drag itself is over even though the selection stays active for
+		// the async copy-command grace window below — see dragging's doc
+		// comment on why mouseMotion must stop treating events as a drag now.
+		m.transcriptSelection.dragging = false
 		return m, copyTranscriptSelectionCmd(text), true
 	default:
 		return m, nil, false
@@ -1113,8 +1372,11 @@ func (m model) toggleTranscriptRow(rowIndex int) model {
 }
 
 func (m model) selectedTranscriptText() string {
-	width := m.chatColumnWidth()
-	layout := m.transcriptBodyLayout(width, "")
+	// Must read from the SAME row source transcriptLineAtMouse hit-tested against
+	// (subchat vs parent transcript) — otherwise the selection's bodyY range is
+	// matched against the wrong layout here and copy silently returns nothing.
+	_, items, _ := m.transcriptHitTestSource()
+	layout := layoutTranscriptBodyItems(items)
 	parts := []string{}
 	for _, line := range layout.selectable {
 		start, end, ok := m.selectedColumnsForTranscriptLine(line)

internal/tui/turns_command_test.go

@@ -0,0 +1,62 @@
+package tui
+
+import (
+	"os"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+func TestHandleTurnsCommand(t *testing.T) {
+	// Isolate the inherited-by-children budget env this command exports.
+	t.Setenv("ZERO_MAX_TURNS", "")
+
+	t.Run("sets a valid budget and exports it for children", func(t *testing.T) {
+		got, out := model{}.handleTurnsCommand("150")
+		if got.agentOptions.MaxTurns != 150 {
+			t.Fatalf("MaxTurns = %d, want 150", got.agentOptions.MaxTurns)
+		}
+		if !strings.Contains(out, "150") {
+			t.Fatalf("output should report 150, got %q", out)
+		}
+		if env := os.Getenv("ZERO_MAX_TURNS"); env != "150" {
+			t.Fatalf("ZERO_MAX_TURNS = %q, want 150 (so sub-agents inherit it)", env)
+		}
+	})
+
+	t.Run("clamps above the ceiling (env too)", func(t *testing.T) {
+		got, _ := model{}.handleTurnsCommand("99999")
+		if got.agentOptions.MaxTurns != maxTurnsCeiling {
+			t.Fatalf("MaxTurns = %d, want clamp to %d", got.agentOptions.MaxTurns, maxTurnsCeiling)
+		}
+		if env := os.Getenv("ZERO_MAX_TURNS"); env != strconv.Itoa(maxTurnsCeiling) {
+			t.Fatalf("ZERO_MAX_TURNS = %q, want clamped %d", env, maxTurnsCeiling)
+		}
+	})
+
+	t.Run("invalid / non-positive input is rejected without changing the budget", func(t *testing.T) {
+		for _, in := range []string{"abc", "0", "-5", "3.5"} {
+			m := model{}
+			m.agentOptions.MaxTurns = 42
+			got, out := m.handleTurnsCommand(in)
+			if got.agentOptions.MaxTurns != 42 {
+				t.Fatalf("input %q changed MaxTurns to %d, want unchanged (42)", in, got.agentOptions.MaxTurns)
+			}
+			if !strings.Contains(out, "Usage") {
+				t.Fatalf("input %q should show usage, got %q", in, out)
+			}
+		}
+	})
+
+	t.Run("empty / status shows the current budget without changing it", func(t *testing.T) {
+		m := model{}
+		m.agentOptions.MaxTurns = 42
+		got, out := m.handleTurnsCommand("")
+		if got.agentOptions.MaxTurns != 42 {
+			t.Fatalf("status changed MaxTurns to %d, want 42", got.agentOptions.MaxTurns)
+		}
+		if !strings.Contains(out, "42") {
+			t.Fatalf("status should report current 42, got %q", out)
+		}
+	})
+}