chore: ignore zero-skills local build artifact

A locally built test binary under this name was accidentally committed
(and has been scrubbed from the branch history); ignore the name so it
cannot recur.

.gitignore

@@ -37,8 +37,13 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 /zero
 /zero.exe
+/zero-skills
 /snake-game.html
 
 # Superpowers skill artifacts (brainstorm mockups, specs, plans) — local only
 .superpowers/
 docs/superpowers/
+
+# Termux/Android build artifacts
+zero-termux-arm64
+zero-linux-sandbox

AGENTS.md

@@ -47,6 +47,12 @@ Tips:
 - In a monorepo, drop a narrower `AGENTS.md` in each sub-tree (e.g. `services/api/AGENTS.md`). Zero picks those up automatically when you launch from inside the sub-tree.
 - A YAML frontmatter block (`---\n...\n---`) at the top is preserved verbatim in the injected prompt but is not parsed for `globs:` or `alwaysApply:` scoping today — keep the body self-contained.
 
+### Personal guidelines, across every project
+
+For preferences that follow *you*, not a specific repo (tone, tooling habits, workflow), drop a `ZERO.md` in your user config directory: `~/.config/zero/ZERO.md` on Linux/macOS, `%AppData%\Roaming\zero\ZERO.md` on Windows — the same directory as `config.json` and your personal specialists. Same format and 8 KiB cap as the project files above, and the same case-insensitive basename match.
+
+This file is injected as its own `## User guidelines` section, before the project's `AGENTS.md`/`ZERO.md`, and is labeled as personal preference in the prompt: project guidelines are the later, more specific instruction and take precedence over it when the two conflict.
+
 ## 2. Custom specialists
 
 Specialists are Zero's sub-agents. Three scopes, in priority order:
@@ -307,6 +313,7 @@ A team that wants every contributor's Zero to behave the same way commits:
 Each contributor adds only:
 
 - `~/.config/zero/config.json` — their personal API keys, theme, default mode.
+- `~/.config/zero/ZERO.md` — personal preferences that follow them across every project (see section 1).
 - `~/.local/share/zero/skills/` — personal skills they keep across projects.
 
 That's it. Run `zero` from the repo root and the agent has the team's full instruction set, every contributor's personal setup, and nothing else.

docs/INSTALL.md

@@ -173,6 +173,61 @@ Linux native sandboxing also requires Bubblewrap to be installed.
 
 macOS uses the system sandbox and does not need an extra helper binary.
 
+### Termux (Android)
+
+Zero can run natively on Android via [Termux](https://termux.dev/). Build with
+`GOOS=android` to avoid the `faccessat2` syscall that is blocked by Samsung's
+seccomp filter on Android:
+
+```bash
+# Install Go in Termux
+pkg install golang
+
+# Build Zero for Android
+git clone https://github.com/Gitlawb/zero.git
+cd zero
+CGO_ENABLED=0 GOOS=android GOARCH=arm64 go build -ldflags="-s -w" -o zero ./cmd/zero
+
+# Move into PATH
+mv zero ~/.local/bin/
+```
+
+> **Why `GOOS=android`?** Go 1.26+ detects `runtime.GOOS == "android"` and skips
+> the `faccessat2` syscall inside `os/exec.findExecutable`, falling back to
+> permission-bit checks. Without this flag, Android's seccomp sends SIGSYS and
+> kills the process whenever Zero looks up a binary on `PATH` (git, sh, etc.).
+
+**DNS.** Android does not expose `/etc/resolv.conf`. Go's pure-Go DNS resolver
+needs one. Use `proot` to bind-mount Termux's resolver config:
+
+```bash
+pkg install proot
+proot -b "$PREFIX/etc/resolv.conf:/etc/resolv.conf" zero
+```
+
+Create a wrapper at `~/.local/bin/zero` to avoid typing proot every time:
+
+```bash
+#!/data/data/com.termux/files/usr/bin/bash
+exec proot -b "$PREFIX/etc/resolv.conf:/etc/resolv.conf" ~/.local/bin/zero.bin "$@"
+```
+
+**Scroll.** On native Termux (not under PRoot), mouse scrolling works out of the
+box. The TUI uses Bubble Tea's `AllMotion` mouse mode by default. If you run Zero
+inside PRoot (e.g. through proot-distro), the scroll fix activates `CellMotion`
+to avoid PRoot's ptrace interference with the 1003 escape sequence.
+
+**Providers.** Zero works with any OpenAI-compatible provider on Termux. For
+example, to use OpenCode Zen's free tier:
+
+```bash
+zero providers add opencode \
+  --name opencode \
+  --model deepseek-v4-flash-free \
+  --base-url https://opencode.ai/zen/v1 \
+  --set-active
+```
+
 Windows source builds can use the main `zero.exe` as the command runner and setup
 helper through Zero's built-in self-dispatch path. If you want a release-style
 layout anyway, build the standalone helper executables next to `zero.exe`:

docs/STREAM_JSON_PROTOCOL.md

@@ -41,6 +41,7 @@ events when present.
 
 ```json
 { "schemaVersion": 2, "type": "run_start", "runId": "run_20260603_abc123", "sessionId": "zero_20260603100000_abc123", "cwd": "/repo", "provider": "openai", "model": "gpt-4.1", "apiModel": "gpt-4.1" }
+{ "schemaVersion": 2, "type": "reasoning", "runId": "run_20260603_abc123", "delta": "Thinking..." }
 { "schemaVersion": 2, "type": "text", "runId": "run_20260603_abc123", "delta": "..." }
 { "schemaVersion": 2, "type": "tool_call", "runId": "run_20260603_abc123", "id": "call_1", "name": "read_file", "args": { "path": "README.md" }, "sideEffect": "read" }
 { "schemaVersion": 2, "type": "permission_request", "runId": "run_20260603_abc123", "id": "call_2", "name": "write_file", "action": "prompt", "permission": "prompt", "permissionMode": "ask", "sideEffect": "write", "reason": "Creates or overwrites files." }
@@ -51,6 +52,10 @@ events when present.
 { "schemaVersion": 2, "type": "run_end", "runId": "run_20260603_abc123", "status": "success", "exitCode": 0 }
 ```
 
+`reasoning` events carry live model reasoning/status deltas for providers that
+stream them separately from answer text. They are liveness/progress events only:
+they are not folded into `text` or the final answer.
+
 Permission events may include structured sandbox metadata:
 
 ```json

internal/agent/compaction.go

@@ -325,6 +325,43 @@ type compactionState struct {
 	// OnText is deliberately NOT forwarded (compaction stays invisible to the user),
 	// but its token COST must still be counted so usage reports and budgets include it.
 	onUsage func(Usage)
+
+	// calibrationRatio scales the raw byte/4 token estimate toward the provider's
+	// real prompt-token count. ApproxTextTokens over-counts code-heavy content by
+	// ~15-20%, which would trip compaction early (at ~60% of true capacity). It
+	// starts at 1.0 and converges via an EMA as each turn reports actual usage, so
+	// later turns compact nearer to real capacity. Zero is treated as 1.0.
+	calibrationRatio float64
+}
+
+// calibrate folds one turn's (rawEstimate, actualPromptTokens) sample into the
+// running calibration ratio. A single sample is clamped to a sane band so an
+// outlier (a huge cache-read turn, a provider-overhead spike) can't skew the
+// estimate enough to disable or thrash compaction.
+func (state *compactionState) calibrate(rawEstimate int, actualPromptTokens int) {
+	if !state.enabled || rawEstimate <= 0 || actualPromptTokens <= 0 {
+		return
+	}
+	sample := float64(actualPromptTokens) / float64(rawEstimate)
+	if sample < 0.5 {
+		sample = 0.5
+	} else if sample > 2.0 {
+		sample = 2.0
+	}
+	if state.calibrationRatio <= 0 {
+		state.calibrationRatio = 1.0
+	}
+	const alpha = 0.3 // weight on the newest sample; smooths jitter across turns
+	state.calibrationRatio = state.calibrationRatio*(1-alpha) + sample*alpha
+}
+
+// calibratedTokens applies the learned ratio to a raw estimate. Before any sample
+// arrives (ratio unset) it returns the raw estimate unchanged.
+func (state *compactionState) calibratedTokens(raw int) int {
+	if state.calibrationRatio <= 0 {
+		return raw
+	}
+	return int(float64(raw) * state.calibrationRatio)
 }
 
 func newCompactionState(options Options) *compactionState {
@@ -353,7 +390,7 @@ func (state *compactionState) maybeCompact(
 	// the messages; both the threshold check and the shrink check below use the
 	// same term so they stay consistent.
 	toolTokens := estimateToolDefTokens(tools)
-	size := estimateTokens(messages) + toolTokens
+	size := state.calibratedTokens(estimateTokens(messages) + toolTokens)
 	if size <= state.threshold {
 		return messages
 	}
@@ -370,7 +407,7 @@ func (state *compactionState) maybeCompact(
 	// entirely and preserve recent turns verbatim.
 	if pruned, reclaimed := pruneStaleToolOutput(messages, state.preserveLast); reclaimed > 0 {
 		messages = pruned
-		size = estimateTokens(messages) + toolTokens
+		size = state.calibratedTokens(estimateTokens(messages) + toolTokens)
 		if size <= state.threshold {
 			state.lowWaterMark = size
 			return messages
@@ -386,7 +423,7 @@ func (state *compactionState) maybeCompact(
 		// later turn) can try again; we never drop messages on failure here.
 		return messages
 	}
-	newSize := estimateTokens(compacted) + toolTokens
+	newSize := state.calibratedTokens(estimateTokens(compacted) + toolTokens)
 	if newSize >= size {
 		// Compaction did not actually shrink anything (e.g. nothing to
 		// summarize). Leave the history untouched and don't churn next turn.
@@ -444,7 +481,7 @@ func (state *compactionState) recover(
 	// the SAME combined (messages + tool-defs) domain maybeCompact uses, so the
 	// proactive shrink-guard compares like with like.
 	state.reactiveAttempted = true
-	state.lowWaterMark = estimateTokens(result) + estimateToolDefTokens(tools)
+	state.lowWaterMark = state.calibratedTokens(estimateTokens(result) + estimateToolDefTokens(tools))
 	return result, true, nil
 }
 

internal/agent/compaction_calibrate_test.go

@@ -0,0 +1,50 @@
+package agent
+
+import "testing"
+
+func TestCalibrationConvergesTowardActual(t *testing.T) {
+	state := &compactionState{enabled: true}
+
+	// Before any sample, the estimate is unchanged.
+	if got := state.calibratedTokens(1000); got != 1000 {
+		t.Fatalf("uncalibrated tokens = %d, want 1000", got)
+	}
+
+	// The estimator over-counts: our raw estimate is 1000 but the provider reports
+	// 850 (a 0.85 ratio). Feeding that sample repeatedly should pull the ratio
+	// toward 0.85, so a 1000-token raw estimate calibrates downward.
+	for range 20 {
+		state.calibrate(1000, 850)
+	}
+	got := state.calibratedTokens(1000)
+	if got >= 1000 || got < 820 || got > 880 {
+		t.Fatalf("calibrated tokens = %d, want ~850 after convergence", got)
+	}
+}
+
+func TestCalibrateIgnoresDegenerateSamples(t *testing.T) {
+	state := &compactionState{enabled: true}
+	state.calibrate(0, 500) // zero estimate
+	state.calibrate(500, 0) // zero actual
+	if state.calibrationRatio != 0 {
+		t.Fatalf("degenerate samples must not move the ratio, got %v", state.calibrationRatio)
+	}
+	// Disabled state never calibrates.
+	disabled := &compactionState{enabled: false}
+	disabled.calibrate(1000, 850)
+	if disabled.calibrationRatio != 0 {
+		t.Fatalf("disabled compaction must not calibrate, got %v", disabled.calibrationRatio)
+	}
+}
+
+func TestCalibrateClampsOutliers(t *testing.T) {
+	state := &compactionState{enabled: true}
+	// A wild outlier (10x) is clamped to 2.0, so one bad sample can't blow up the
+	// ratio and disable compaction.
+	for range 50 {
+		state.calibrate(1000, 10000)
+	}
+	if state.calibrationRatio > 2.0 {
+		t.Fatalf("ratio should be clamped at 2.0, got %v", state.calibrationRatio)
+	}
+}

internal/agent/compaction_preserve.go

@@ -20,6 +20,16 @@ const (
 	toolNameUpdatePlan = "update_plan"
 	toolNameToolSearch = "tool_search"
 	toolNameSkill      = "skill"
+	toolNameWriteFile  = "write_file"
+	toolNameEditFile   = "edit_file"
+)
+
+// maxRecentEdits caps how many edited files are carried across a compaction, and
+// maxEditNoteBytes caps each edit's one-line note, so a long editing run can't
+// bloat the preserved-state block.
+const (
+	maxRecentEdits   = 20
+	maxEditNoteBytes = 160
 )
 
 const (
@@ -100,12 +110,123 @@ func formatPlanArguments(arguments string) string {
 }
 
 // skillEntry is a named preserved body. It began as loaded-skill state and is
-// reused for loaded tools and project instruction blocks.
+// reused for loaded tools, project instruction blocks, and recent file edits.
 type skillEntry struct {
 	name string
 	body string
 }
 
+// recentEdits returns the files mutated by write_file/edit_file calls in messages
+// — latest note per path, in last-seen order — as skillEntry{name: path, body:
+// note}. After compaction elides the editing turns, this tells the model WHAT it
+// changed in each file (from the tool's result) so it need not re-read to
+// rediscover its own footprint. Capped at maxRecentEdits paths.
+//
+// Ordering is by LAST edit, not first: re-editing a file moves it to the newest
+// position so the tail cap below keeps the file the model most recently touched
+// rather than an earlier, now-stale entry.
+func recentEdits(messages []zeroruntime.Message) []skillEntry {
+	pathByID := map[string]string{}
+	sequence := make([]string, 0)
+	for _, message := range messages {
+		for _, call := range message.ToolCalls {
+			if call.Name != toolNameWriteFile && call.Name != toolNameEditFile {
+				continue
+			}
+			path := editPathFromArguments(call.Arguments)
+			if path == "" {
+				continue
+			}
+			if call.ID != "" {
+				pathByID[call.ID] = path
+			}
+			sequence = append(sequence, path)
+		}
+	}
+	order := lastSeenOrder(sequence)
+	if len(order) == 0 {
+		return nil
+	}
+
+	noteByPath := map[string]string{}
+	for _, message := range messages {
+		if message.Role != zeroruntime.MessageRoleTool || message.ToolCallID == "" {
+			continue
+		}
+		if path, ok := pathByID[message.ToolCallID]; ok {
+			noteByPath[path] = editNote(message.Content)
+		}
+	}
+
+	// Keep the most recent maxRecentEdits paths (the tail of last-seen order).
+	if len(order) > maxRecentEdits {
+		order = order[len(order)-maxRecentEdits:]
+	}
+	entries := make([]skillEntry, 0, len(order))
+	for _, path := range order {
+		entries = append(entries, skillEntry{name: path, body: noteByPath[path]})
+	}
+	return entries
+}
+
+// lastSeenOrder dedupes paths keeping each at its LAST occurrence, preserving
+// chronological order otherwise. A re-edited path therefore lands at the newest
+// position rather than staying pinned to where it first appeared.
+func lastSeenOrder(paths []string) []string {
+	lastIdx := make(map[string]int, len(paths))
+	for i, p := range paths {
+		lastIdx[p] = i
+	}
+	order := make([]string, 0, len(lastIdx))
+	for i, p := range paths {
+		if lastIdx[p] == i {
+			order = append(order, p)
+		}
+	}
+	return order
+}
+
+// editPathFromArguments pulls the target file path from a write_file/edit_file
+// call's JSON arguments (path/file/file_path/filename aliases). Returns "" on
+// malformed arguments or no path.
+func editPathFromArguments(arguments string) string {
+	var parsed struct {
+		Path     string `json:"path"`
+		File     string `json:"file"`
+		FilePath string `json:"file_path"`
+		Filename string `json:"filename"`
+	}
+	if err := json.Unmarshal([]byte(strings.TrimSpace(arguments)), &parsed); err != nil {
+		return ""
+	}
+	for _, candidate := range []string{parsed.Path, parsed.File, parsed.FilePath, parsed.Filename} {
+		if s := strings.TrimSpace(candidate); s != "" {
+			return s
+		}
+	}
+	return ""
+}
+
+// editNote reduces an edit tool's result to a single short line (its first
+// non-empty line, byte-capped on a rune boundary) for the preserved summary.
+func editNote(content string) string {
+	for _, line := range strings.Split(content, "\n") {
+		s := strings.TrimSpace(line)
+		if s == "" {
+			continue
+		}
+		if len(s) > maxEditNoteBytes {
+			limit := maxEditNoteBytes
+			for limit > 0 && !utf8.RuneStart(s[limit]) {
+				limit--
+			}
+			s = s[:limit] + "…"
+		}
+		return s
+	}
+	return ""
+}
+
 // loadedSkills returns the skills loaded via the skill tool in messages — the
 // latest body per name, in first-seen order — matching each skill tool call to
 // its tool result by id.
@@ -310,11 +431,17 @@ func capBody(body string) string {
 // preservedState is the JSON shape of the carried-across-compaction block.
 type preservedState struct {
 	Plan                string                 `json:"plan,omitempty"`
+	RecentEdits         []preservedEdit        `json:"recent_edits,omitempty"`
 	Tools               []preservedTool        `json:"tools,omitempty"`
 	Skills              []preservedSkill       `json:"skills,omitempty"`
 	ProjectInstructions []preservedInstruction `json:"project_instructions,omitempty"`
 }
 
+type preservedEdit struct {
+	Path string `json:"path"`
+	Note string `json:"note,omitempty"`
+}
+
 type preservedTool struct {
 	Name string `json:"name"`
 	Body string `json:"body"`
@@ -347,6 +474,12 @@ func appendPreservedState(summary string, middle []zeroruntime.Message) string {
 		plan = priorState.Plan
 	}
 
+	// Recent edits: merge edits preserved earlier with fresh write_file/edit_file
+	// results in middle (newer note per path wins AND moves to the newest
+	// position), so the tail cap keeps the files the model most recently touched
+	// across repeated compactions rather than dropping a just-re-edited file.
+	edits := capRecentEdits(mergeRecentEdits(preservedEditsToEntries(priorState.RecentEdits), recentEdits(middle)))
+
 	// Tools: preserve deferred tool_search schemas from the transcript. Fresh
 	// loads override older carried copies by name.
 	tools := mergeSkillEntries(preservedToolsToEntries(priorState.Tools), loadedToolSchemas(middle))
@@ -360,19 +493,76 @@ func appendPreservedState(summary string, middle []zeroruntime.Message) string {
 		projectInstructionEntries(middle),
 	)
 
-	if block := formatPreservedState(plan, tools, skills, instructions); block != "" {
+	if block := formatPreservedState(plan, edits, tools, skills, instructions); block != "" {
 		summary += "\n\n" + block
 	}
 	return summary
 }
 
+// mergeRecentEdits overlays fresh edits onto edits preserved by an earlier
+// compaction. Unlike mergeSkillEntries (which keeps refreshed entries in their
+// original slot), a path touched again by a fresh edit MOVES to the newest
+// position and takes the fresh note, so capRecentEdits — which keeps only the
+// most-recent tail — never drops a file the model just re-edited. Paths present
+// only in the older set keep their relative order, ahead of the fresh ones.
+func mergeRecentEdits(older, newer []skillEntry) []skillEntry {
+	if len(newer) == 0 {
+		return older
+	}
+	freshBody := make(map[string]string, len(newer))
+	freshOrder := make([]string, 0, len(newer))
+	for _, e := range newer {
+		if _, ok := freshBody[e.name]; !ok {
+			freshOrder = append(freshOrder, e.name)
+		}
+		freshBody[e.name] = e.body
+	}
+	merged := make([]skillEntry, 0, len(older)+len(freshOrder))
+	// Older entries that were NOT re-edited keep their position, oldest first.
+	for _, e := range older {
+		if _, refreshed := freshBody[e.name]; refreshed {
+			continue // re-appended at its newest position below
+		}
+		merged = append(merged, e)
+	}
+	// Fresh edits follow, in last-seen order, each carrying the fresh note — so
+	// the most recently touched files sit at the tail the cap preserves.
+	for _, name := range freshOrder {
+		merged = append(merged, skillEntry{name: name, body: freshBody[name]})
+	}
+	return merged
+}
+
+// capRecentEdits bounds the preserved edit list to the most recent maxRecentEdits
+// entries after a merge, so repeated compactions can't grow it without limit.
+func capRecentEdits(entries []skillEntry) []skillEntry {
+	if len(entries) > maxRecentEdits {
+		return entries[len(entries)-maxRecentEdits:]
+	}
+	return entries
+}
+
+func preservedEditsToEntries(edits []preservedEdit) []skillEntry {
+	entries := make([]skillEntry, 0, len(edits))
+	for _, e := range edits {
+		if e.Path == "" {
+			continue
+		}
+		entries = append(entries, skillEntry{name: e.Path, body: e.Note})
+	}
+	return entries
+}
+
 // formatPreservedState renders state as the labelled, single-line
 // JSON block. Returns "" when there is nothing to preserve.
-func formatPreservedState(plan string, tools, skills, instructions []skillEntry) string {
-	if plan == "" && len(tools) == 0 && len(skills) == 0 && len(instructions) == 0 {
+func formatPreservedState(plan string, edits, tools, skills, instructions []skillEntry) string {
+	if plan == "" && len(edits) == 0 && len(tools) == 0 && len(skills) == 0 && len(instructions) == 0 {
 		return ""
 	}
 	state := preservedState{Plan: plan}
+	for _, e := range edits {
+		state.RecentEdits = append(state.RecentEdits, preservedEdit{Path: e.name, Note: e.body})
+	}
 	for _, t := range tools {
 		state.Tools = append(state.Tools, preservedTool{Name: t.name, Body: t.body})
 	}

internal/agent/compaction_recent_edits_test.go

@@ -0,0 +1,121 @@
+package agent
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+// recentEdits extracts each mutated file's path and a one-line note from the
+// matching tool result, latest note per path in last-seen order.
+func TestRecentEditsExtractsPathsAndNotes(t *testing.T) {
+	messages := []zeroruntime.Message{
+		{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{
+			{ID: "e1", Name: "write_file", Arguments: `{"path":"internal/foo.go","content":"package foo"}`},
+		}},
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "e1", Content: "Wrote internal/foo.go (12 lines)"},
+		{Role: zeroruntime.MessageRoleAssistant, ToolCalls: []zeroruntime.ToolCall{
+			{ID: "e2", Name: "edit_file", Arguments: `{"path":"internal/bar.go","old_string":"a","new_string":"b"}`},
+		}},
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "e2", Content: "Applied edit to internal/bar.go"},
+	}
+
+	edits := recentEdits(messages)
+	if len(edits) != 2 {
+		t.Fatalf("expected 2 edited files, got %d: %#v", len(edits), edits)
+	}
+	if edits[0].name != "internal/foo.go" || !strings.Contains(edits[0].body, "12 lines") {
+		t.Fatalf("first edit = %#v, want foo.go with its note", edits[0])
+	}
+	if edits[1].name != "internal/bar.go" || !strings.Contains(edits[1].body, "Applied edit") {
+		t.Fatalf("second edit = %#v, want bar.go with its note", edits[1])
+	}
+}
+
+// After compaction elides the editing turns, the preserved-state block still
+// names the edited files and what changed, so the model needn't re-read them.
+func TestCompactionPreservesRecentEdits(t *testing.T) {
+	messages := []zeroruntime.Message{
+		{Role: zeroruntime.MessageRoleSystem, Content: "system"},
+		{Role: zeroruntime.MessageRoleUser, Content: "add a flag"},
+		{Role: zeroruntime.MessageRoleAssistant, Content: "editing", ToolCalls: []zeroruntime.ToolCall{
+			{ID: "e1", Name: "write_file", Arguments: `{"path":"cmd/main.go","content":"..."}`},
+		}},
+		{Role: zeroruntime.MessageRoleTool, ToolCallID: "e1", Content: "Wrote cmd/main.go (adds --version flag)"},
+		{Role: zeroruntime.MessageRoleAssistant, Content: "done"},
+		{Role: zeroruntime.MessageRoleUser, Content: "continue"},
+		{Role: zeroruntime.MessageRoleAssistant, Content: "continuing"},
+	}
+	summary := compactStateConversation(t, messages)
+
+	state := parsePreservedStateBlock(summary)
+	if len(state.RecentEdits) != 1 {
+		t.Fatalf("expected 1 preserved edit, got %#v", state.RecentEdits)
+	}
+	if state.RecentEdits[0].Path != "cmd/main.go" || !strings.Contains(state.RecentEdits[0].Note, "--version") {
+		t.Fatalf("preserved edit = %#v, want cmd/main.go + its note", state.RecentEdits[0])
+	}
+}
+
+// A fresh edit note for a path overrides the one carried from an earlier
+// compaction (newer wins) and moves the path to the newest position rather than
+// duplicating it or leaving it pinned to its old slot.
+func TestRecentEditsMergeNewerWins(t *testing.T) {
+	prior := preservedState{RecentEdits: []preservedEdit{{Path: "a.go", Note: "old note"}, {Path: "z.go", Note: "z"}}}
+	older := preservedEditsToEntries(prior.RecentEdits)
+	newer := []skillEntry{{name: "a.go", body: "new note"}, {name: "b.go", body: "added"}}
+
+	merged := mergeRecentEdits(older, newer)
+	// z.go (untouched) keeps its lead; a.go is re-edited so it takes the new note
+	// and moves behind z.go, ahead of the brand-new b.go: [z.go, a.go, b.go].
+	if len(merged) != 3 {
+		t.Fatalf("expected z.go + refreshed a.go + b.go, got %#v", merged)
+	}
+	if merged[0].name != "z.go" {
+		t.Fatalf("untouched z.go should stay first, got %#v", merged)
+	}
+	if merged[1].name != "a.go" || merged[1].body != "new note" {
+		t.Fatalf("re-edited a.go should move to the newest edits with the new note, got %#v", merged[1])
+	}
+	if merged[2].name != "b.go" {
+		t.Fatalf("brand-new b.go should be last, got %#v", merged[2])
+	}
+}
+
+// Regression: once more than maxRecentEdits distinct files are tracked, re-editing
+// an early file must move it into the capped tail rather than leaving it to be
+// dropped — otherwise the next compaction omits exactly the file the model most
+// recently touched.
+func TestRecentEditsCapKeepsReeditedFile(t *testing.T) {
+	// Earlier compaction preserved exactly maxRecentEdits files, f0 the oldest.
+	older := make([]skillEntry, 0, maxRecentEdits)
+	for i := 0; i < maxRecentEdits; i++ {
+		older = append(older, skillEntry{name: fmt.Sprintf("f%d.go", i), body: "old"})
+	}
+	// Fresh window re-edits the OLDEST file (f0) and adds a brand-new file, so the
+	// merged list exceeds the cap and something must be dropped.
+	newer := []skillEntry{{name: "f0.go", body: "re-edited"}, {name: "fresh.go", body: "new"}}
+
+	merged := capRecentEdits(mergeRecentEdits(older, newer))
+	if len(merged) != maxRecentEdits {
+		t.Fatalf("cap should keep %d entries, got %d", maxRecentEdits, len(merged))
+	}
+
+	var f0 *skillEntry
+	for i := range merged {
+		if merged[i].name == "f0.go" {
+			f0 = &merged[i]
+		}
+		if merged[i].name == "f1.go" {
+			t.Fatalf("f1.go (now the least-recently touched) should have been dropped, got %#v", merged)
+		}
+	}
+	if f0 == nil {
+		t.Fatalf("re-edited f0.go must survive the cap, got %#v", merged)
+	}
+	if f0.body != "re-edited" {
+		t.Fatalf("surviving f0.go should carry the fresh note, got %q", f0.body)
+	}
+}

internal/agent/file_diagnostics.go

@@ -3,6 +3,8 @@ package agent
 import (
 	"context"
 	"os"
+	"path/filepath"
+	"strings"
 	"time"
 
 	"github.com/Gitlawb/zero/internal/lsp"
@@ -18,9 +20,12 @@ const fileDiagnosticsTimeout = 10 * time.Second
 // checks it against the file's language server, and formats error-severity
 // diagnostics for the model. Warnings and hints are excluded — nagging about
 // style on every edit is noise, while a type error the edit just introduced is
-// exactly what the model should see before its next step. Returns nil when
-// manager is nil, disabling inline diagnostics entirely.
-func NewFileDiagnostics(manager *lsp.Manager) func(context.Context, string) string {
+// exactly what the model should see before its next step. Diagnostics are
+// rendered with workspace-relative paths: the absolute path would put the
+// local username/home directory into the model prompt and session transcript
+// on every edit. Returns nil when manager is nil, disabling inline diagnostics
+// entirely.
+func NewFileDiagnostics(manager *lsp.Manager, workspaceRoot string) func(context.Context, string) string {
 	if manager == nil {
 		return nil
 	}
@@ -39,6 +44,19 @@ func NewFileDiagnostics(manager *lsp.Manager) func(context.Context, string) stri
 		if len(errors) == 0 {
 			return ""
 		}
-		return lsp.FormatDiagnostics(absPath, errors)
+		return lsp.FormatDiagnostics(diagnosticsDisplayPath(workspaceRoot, absPath), errors)
 	}
 }
+
+// diagnosticsDisplayPath renders absPath relative to the workspace root for
+// model-facing output, falling back to the file's base name when the path is
+// outside the workspace (a bare name still identifies the file without
+// exposing the directory layout).
+func diagnosticsDisplayPath(workspaceRoot, absPath string) string {
+	if workspaceRoot != "" {
+		if rel, err := filepath.Rel(workspaceRoot, absPath); err == nil && !strings.HasPrefix(rel, "..") {
+			return rel
+		}
+	}
+	return filepath.Base(absPath)
+}

internal/agent/file_diagnostics_test.go

@@ -0,0 +1,24 @@
+package agent
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+// Diagnostics are model-facing: absolute paths would leak the local username
+// and directory layout into the prompt and session transcript on every edit.
+func TestDiagnosticsDisplayPath(t *testing.T) {
+	root := filepath.Join("/Users", "someone", "project")
+	cases := []struct {
+		root, abs, want string
+	}{
+		{root, filepath.Join(root, "internal", "a.go"), filepath.Join("internal", "a.go")},
+		{root, filepath.Join("/etc", "other.go"), "other.go"}, // outside root -> base name only
+		{"", filepath.Join("/home", "user", "x.go"), "x.go"},  // no root -> base name only
+	}
+	for _, c := range cases {
+		if got := diagnosticsDisplayPath(c.root, c.abs); got != c.want {
+			t.Errorf("diagnosticsDisplayPath(%q, %q) = %q, want %q", c.root, c.abs, got, c.want)
+		}
+	}
+}

internal/agent/guardrails.go

@@ -22,6 +22,12 @@ const (
 	// calls have executed since the last update_plan call.
 	staleToolCallThreshold = 10
 
+	// stalePlanTurnThreshold injects the same one-shot reminder once this many
+	// turns have passed since the last update_plan while plan items are still
+	// pending — the turn-based complement to staleToolCallThreshold, catching a
+	// plan that drifts stale across many turns that each make few tool calls.
+	stalePlanTurnThreshold = 8
+
 	// toolOnlyProgressReminderAt injects a one-shot progress nudge after this
 	// many consecutive turns contain tool calls but no visible assistant text.
 	// It does not stop the run; it tells the model to synthesize what it already
@@ -43,8 +49,12 @@ const (
 	toolFailureHintAt = 2
 	// toolFailureStopAt halts the run after a tool fails this many times in a row
 	// with the same error, so NO model (weak or strong) burns turns looping on a
-	// bad call.
-	toolFailureStopAt = 4
+	// bad call. Set to 6 (not 4): a corrective hint fires at toolFailureHintAt (2),
+	// and a model iterating on a genuinely tricky edit can legitimately fail a few
+	// times after the hint while converging — stopping at 4 cut those runs short.
+	// The streak still resets the moment the tool succeeds or hits a different
+	// error, so this only affects true same-error loops.
+	toolFailureStopAt = 6
 
 	// maxContinueNudges bounds how many times the headless completion gate
 	// (Options.RequireCompletionSignal) re-prompts a model that stopped without a
@@ -354,8 +364,13 @@ type guardState struct {
 	emptyTurns               int
 	totalToolCalls           int
 	toolCallsSincePlanUpdate int
-	planEverCalled           bool
-	notCalledReminderSent    bool
+	// turnsSincePlanUpdate counts turns (not individual tool calls) since the last
+	// update_plan, so a plan that goes stale across many low-tool-call turns is
+	// still caught — the tool-call counter alone can take many turns to trip when
+	// the model makes only one call per turn.
+	turnsSincePlanUpdate  int
+	planEverCalled        bool
+	notCalledReminderSent bool
 	// staleReminderSent records whether the stale reminder has already fired for
 	// the current stale interval. It is cleared when a plan update opens a new
 	// interval, making the reminder one-shot per interval rather than per turn.
@@ -414,8 +429,9 @@ func (state *guardState) observeToolResult(name string, failed bool, output stri
 func (state *guardState) observeTurn(collected zeroruntime.CollectedStream) (stop bool) {
 	hasToolCalls := len(collected.ToolCalls) > 0
 	hasVisibleText := strings.TrimSpace(collected.Text) != ""
+	hasReasoning := collected.HasReasoning || len(collected.ReasoningBlocks) > 0
 
-	if hasToolCalls || hasVisibleText {
+	if hasToolCalls || hasVisibleText || hasReasoning {
 		state.emptyTurns = 0
 	} else {
 		state.emptyTurns++
@@ -427,11 +443,16 @@ func (state *guardState) observeTurn(collected zeroruntime.CollectedStream) (sto
 		state.toolOnlyReminderSent = false
 	}
 
+	// One turn has passed; the plan-update below resets this to 0 when the model
+	// refreshes the plan this turn.
+	state.turnsSincePlanUpdate++
+
 	for _, call := range collected.ToolCalls {
 		state.totalToolCalls++
 		if call.Name == planToolName {
 			state.planEverCalled = true
 			state.toolCallsSincePlanUpdate = 0
+			state.turnsSincePlanUpdate = 0
 			// A fresh plan update opens a new stale interval.
 			state.staleReminderSent = false
 			// Record how many items remain so the completion gate knows whether
@@ -485,10 +506,12 @@ func (state *guardState) progressReminder() string {
 // number of turns completed so far).
 func (state *guardState) planReminder(turn int) string {
 	// STALE reminder takes priority: a long run without a plan update is the
-	// stronger signal. One-shot per stale interval.
-	if state.planEverCalled &&
-		!state.staleReminderSent &&
-		state.toolCallsSincePlanUpdate >= staleToolCallThreshold {
+	// stronger signal. Fires on either the tool-call streak OR a turn streak with
+	// pending items (so a plan drifting stale across many low-call turns is caught,
+	// while a fully-completed plan is left alone). One-shot per stale interval.
+	if state.planEverCalled && !state.staleReminderSent &&
+		(state.toolCallsSincePlanUpdate >= staleToolCallThreshold ||
+			(state.turnsSincePlanUpdate >= stalePlanTurnThreshold && state.planItemsPending > 0)) {
 		state.staleReminderSent = true
 		return planStaleReminder(state.toolCallsSincePlanUpdate)
 	}

internal/agent/guardrails_test.go

@@ -22,6 +22,14 @@ func textTurn(content string) []zeroruntime.StreamEvent {
 	}
 }
 
+// reasoningTurn produces live reasoning without visible assistant text.
+func reasoningTurn(content string) []zeroruntime.StreamEvent {
+	return []zeroruntime.StreamEvent{
+		{Type: zeroruntime.StreamEventReasoning, Content: content},
+		{Type: zeroruntime.StreamEventDone},
+	}
+}
+
 // toolTurn produces a turn that calls a named tool with the given args JSON.
 func toolTurn(callID string, toolName string, args string) []zeroruntime.StreamEvent {
 	return []zeroruntime.StreamEvent{
@@ -101,6 +109,31 @@ func TestRunResetsEmptyTurnCounterOnVisibleOutput(t *testing.T) {
 	}
 }
 
+func TestRunResetsEmptyTurnCounterOnReasoning(t *testing.T) {
+	provider := &mockProvider{
+		turns: [][]zeroruntime.StreamEvent{
+			reasoningTurn("thinking 1"),
+			reasoningTurn("thinking 2"),
+			reasoningTurn("thinking 3"),
+			textTurn("done"),
+		},
+	}
+
+	result, err := Run(context.Background(), "go", provider, Options{
+		Registry: tools.NewRegistry(),
+		MaxTurns: 12,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.FinalAnswer != "done" {
+		t.Fatalf("expected reasoning-only turns to keep the run live until final answer, got %q", result.FinalAnswer)
+	}
+	if len(provider.requests) != 4 {
+		t.Fatalf("expected 4 turns, got %d", len(provider.requests))
+	}
+}
+
 func TestRunResetsEmptyTurnCounterOnToolCall(t *testing.T) {
 	root := t.TempDir()
 	writeAgentTestFile(t, root+"/notes.txt", "alpha")

internal/agent/loop.go

@@ -25,7 +25,12 @@ const maxTurnsFinalAnswerPrompt = "You have reached the tool-turn limit. Do not
 // 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
+//
+// Set to 1 (not 2): each attempt can itself idle for the full stream timeout
+// (~5min) before the stall is even detected, so 2 retries left an interactive
+// session frozen for ~15min. One retry keeps the common single-hiccup recovery
+// while bounding the worst case to ~2× the idle timeout.
+const maxStreamStallRetries = 1
 
 const (
 	toolResultMetaControl       = "control"
@@ -145,6 +150,11 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 	// has already been demanded this run, so it fires at most once.
 	acceptanceRequested := false
 
+	// toolDefCache memoizes each tool's rendered JSON-schema definition across
+	// turns (a tool's advertised schema is stable for the run), so partitionTools
+	// doesn't re-run the recursive schema→map conversion for every tool every turn.
+	toolDefCache := map[string]zeroruntime.ToolDefinition{}
+
 	result := Result{Messages: copyMessages(messages)}
 	for turn := 0; turn < maxTurns; turn++ {
 		result.Turns = turn + 1
@@ -153,7 +163,7 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 		// the tool-definition tokens (they ride on every request) in its estimate.
 		// partitionTools depends only on registry/permissions/options/loaded, not on
 		// the messages, so computing it before compaction is safe.
-		exposed, _ := partitionTools(registry, permissionMode, options, loaded)
+		exposed, _ := partitionToolsCached(registry, permissionMode, options, loaded, toolDefCache)
 
 		// PROACTIVE compaction: if the history is approaching the model's
 		// context window, summarize the oldest middle before building the
@@ -163,6 +173,7 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 			Messages:        copyMessages(messages),
 			Tools:           exposed,
 			ReasoningEffort: options.ReasoningEffort,
+			PromptCacheKey:  options.SessionID,
 		}
 
 		// Report the per-category context budget for this turn so a surface can
@@ -198,6 +209,7 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 					Messages:        copyMessages(messages),
 					Tools:           exposed,
 					ReasoningEffort: options.ReasoningEffort,
+					PromptCacheKey:  options.SessionID,
 				}
 				// Pre-content connect after a context-limit compaction: route through the
 				// reconnect helper so a transient upstream hiccup here doesn't fail the
@@ -258,6 +270,7 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 					Messages:        copyMessages(messages),
 					Tools:           exposed,
 					ReasoningEffort: options.ReasoningEffort,
+					PromptCacheKey:  options.SessionID,
 				}
 				retryStream, retryStreamErr := streamWithReconnect(ctx, provider, retryRequest, reconnectNoticeFor(options))
 				if retryStreamErr != nil {
@@ -316,6 +329,7 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 				Messages:        copyMessages(messages),
 				Tools:           exposed,
 				ReasoningEffort: options.ReasoningEffort,
+				PromptCacheKey:  options.SessionID,
 			}
 			retryStream, retryErr := streamWithReconnect(ctx, provider, retryRequest, reconnectNoticeFor(options))
 			if retryErr != nil {
@@ -340,6 +354,16 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 			}
 		}
 
+		// Calibrate the compaction token estimator against the provider's real
+		// prompt-token count for the request we just sent, so later turns trigger
+		// compaction near true capacity instead of ~15% early on code-heavy history.
+		// Recompute the estimate HERE (not at request-build time): a reactive
+		// compaction may have replaced `messages` with a smaller set and re-sent, so
+		// this reflects the request that actually produced collected.Usage. The
+		// assistant reply is appended below, after this, so `messages` is still the
+		// sent request.
+		compactor.calibrate(estimateTokens(messages)+estimateToolDefTokens(exposed), collected.Usage.InputTokens)
+
 		// Carry the turn's terminal stop reason so a final answer cut off at the
 		// output token cap (or by a content filter) is reported as truncated. A
 		// tool-call turn normalizes to "" and clears any prior reason.
@@ -685,6 +709,7 @@ func finalAnswerAfterMaxTurns(ctx context.Context, provider Provider, messages [
 	stream, err := streamWithReconnect(ctx, provider, zeroruntime.CompletionRequest{
 		Messages:        copyMessages(finalMessages),
 		ReasoningEffort: options.ReasoningEffort,
+		PromptCacheKey:  options.SessionID,
 	}, reconnectNoticeFor(options))
 	if err != nil {
 		return "", messages, ""
@@ -2488,6 +2513,17 @@ func permissionActionFromSandbox(action sandbox.Action) PermissionAction {
 // exposed. The exposed slice is alpha-sorted by name, matching the legacy order
 // so the inactive path is stable.
 func partitionTools(registry *tools.Registry, permissionMode PermissionMode, options Options, loaded map[string]bool) ([]zeroruntime.ToolDefinition, string) {
+	return partitionToolsCached(registry, permissionMode, options, loaded, nil)
+}
+
+// partitionToolsCached is partitionTools with an optional per-tool definition
+// cache. The partitioning itself (visibility, deferral, ordering) is recomputed
+// every call — it must be, because a tool's deferred state can flip mid-run (e.g.
+// swarm tools un-defer once a swarm is active). Only the expensive part —
+// rendering each tool's JSON-schema parameters — is memoized by tool name, since a
+// tool's advertised name/description/schema is stable for the run. defCache nil
+// disables caching (used by tests and the plain partitionTools entrypoint).
+func partitionToolsCached(registry *tools.Registry, permissionMode PermissionMode, options Options, loaded map[string]bool, defCache map[string]zeroruntime.ToolDefinition) ([]zeroruntime.ToolDefinition, string) {
 	registeredTools := registry.All()
 
 	visible := make([]tools.Tool, 0, len(registeredTools))
@@ -2531,7 +2567,7 @@ func partitionTools(registry *tools.Registry, permissionMode PermissionMode, opt
 			if tool.Name() == tools.ToolSearchToolName {
 				continue
 			}
-			definitions = append(definitions, runtimeToolDefinition(tool))
+			definitions = append(definitions, cachedRuntimeToolDefinition(defCache, tool))
 		}
 		sort.Slice(definitions, func(left int, right int) bool {
 			return definitions[left].Name < definitions[right].Name
@@ -2563,13 +2599,13 @@ func partitionTools(registry *tools.Registry, permissionMode PermissionMode, opt
 		}
 		if tools.IsDeferred(tool) {
 			if loaded[name] {
-				loadedTail = append(loadedTail, runtimeToolDefinition(tool))
+				loadedTail = append(loadedTail, cachedRuntimeToolDefinition(defCache, tool))
 			} else {
 				hiddenTools = append(hiddenTools, tool)
 			}
 			continue
 		}
-		eager = append(eager, runtimeToolDefinition(tool))
+		eager = append(eager, cachedRuntimeToolDefinition(defCache, tool))
 	}
 	sort.Slice(eager, func(left int, right int) bool {
 		return eager[left].Name < eager[right].Name
@@ -2603,6 +2639,24 @@ func partitionTools(registry *tools.Registry, permissionMode PermissionMode, opt
 	return definitions, discovery
 }
 
+// cachedRuntimeToolDefinition returns the tool's rendered definition, reusing a
+// cached render when defCache holds one for this tool name. A tool's advertised
+// definition is stable across a run, so caching skips the recursive schema→map
+// conversion (schemaToRuntimeMap) that would otherwise run for every tool on every
+// turn. tool_search is excluded by its callers (its description is dynamic), so it
+// never poisons the cache. A nil cache computes fresh.
+func cachedRuntimeToolDefinition(defCache map[string]zeroruntime.ToolDefinition, tool tools.Tool) zeroruntime.ToolDefinition {
+	if defCache == nil {
+		return runtimeToolDefinition(tool)
+	}
+	if def, ok := defCache[tool.Name()]; ok {
+		return def
+	}
+	def := runtimeToolDefinition(tool)
+	defCache[tool.Name()] = def
+	return def
+}
+
 // runtimeToolDefinition renders a tool's advertised definition (name, description,
 // JSON-schema parameters) as sent to the provider.
 func runtimeToolDefinition(tool tools.Tool) zeroruntime.ToolDefinition {

internal/agent/parallel_tools.go

@@ -51,21 +51,33 @@ func parallelSafeToolCall(registry *tools.Registry, call ToolCall, options Optio
 }
 
 // executeParallelReadBatch runs calls[start:end] concurrently (bounded by
-// maxParallelReadTools) and returns results indexed relative to start. Any
-// permission prompt that still occurs (a sandbox preflight can demand one even
-// for an auto-allowed read) is serialized so an interactive front-end never
-// sees two prompts at once.
+// maxParallelReadTools) and returns results indexed relative to start. All
+// execution-side callbacks that can fire inside executeToolCall are serialized
+// behind one mutex: a permission prompt (a sandbox preflight can demand one
+// even for an auto-allowed read) must never appear twice at once on an
+// interactive front-end, and OnPermission event handlers append to shared
+// session-recording state without their own locking — two batched reads under
+// a granted extra root would otherwise race (the pre-batch serial loop never
+// had two callbacks in flight at once).
 func executeParallelReadBatch(ctx context.Context, registry *tools.Registry, calls []ToolCall, start, end int, permissionMode PermissionMode, options Options) []precomputedToolResult {
 	batchOptions := options
+	var callbackMutex sync.Mutex
 	if options.OnPermissionRequest != nil {
-		var promptMutex sync.Mutex
 		inner := options.OnPermissionRequest
 		batchOptions.OnPermissionRequest = func(ctx context.Context, request PermissionRequest) (PermissionDecision, error) {
-			promptMutex.Lock()
-			defer promptMutex.Unlock()
+			callbackMutex.Lock()
+			defer callbackMutex.Unlock()
 			return inner(ctx, request)
 		}
 	}
+	if options.OnPermission != nil {
+		inner := options.OnPermission
+		batchOptions.OnPermission = func(event PermissionEvent) {
+			callbackMutex.Lock()
+			defer callbackMutex.Unlock()
+			inner(event)
+		}
+	}
 
 	results := make([]precomputedToolResult, end-start)
 	semaphore := make(chan struct{}, maxParallelReadTools)

internal/agent/parallel_tools_test.go

@@ -17,6 +17,9 @@ type probeTool struct {
 	name       string
 	sideEffect tools.SideEffect
 	delay      time.Duration
+	// shared, when set, receives this probe's start/end entries too, so a test
+	// can observe ordering ACROSS probes (e.g. reads vs a write barrier).
+	shared *probeLog
 
 	mu        sync.Mutex
 	active    int
@@ -24,6 +27,24 @@ type probeTool struct {
 	log       []string
 }
 
+// probeLog is a mutex-guarded event log shared between probes.
+type probeLog struct {
+	mu      sync.Mutex
+	entries []string
+}
+
+func (log *probeLog) append(entry string) {
+	log.mu.Lock()
+	defer log.mu.Unlock()
+	log.entries = append(log.entries, entry)
+}
+
+func (log *probeLog) snapshot() []string {
+	log.mu.Lock()
+	defer log.mu.Unlock()
+	return append([]string(nil), log.entries...)
+}
+
 func (tool *probeTool) Name() string        { return tool.name }
 func (tool *probeTool) Description() string { return "test probe tool" }
 func (tool *probeTool) Parameters() tools.Schema {
@@ -45,7 +66,13 @@ func (tool *probeTool) Run(_ context.Context, args map[string]any) tools.Result
 	}
 	tool.log = append(tool.log, "start:"+id)
 	tool.mu.Unlock()
+	if tool.shared != nil {
+		tool.shared.append("start:" + id)
+	}
 	time.Sleep(tool.delay)
+	if tool.shared != nil {
+		tool.shared.append("end:" + id)
+	}
 	tool.mu.Lock()
 	tool.active--
 	tool.log = append(tool.log, "end:"+id)
@@ -127,10 +154,9 @@ func TestRunExecutesConsecutiveReadsConcurrently(t *testing.T) {
 }
 
 func TestRunParallelReadsNeverSpanMutatingCall(t *testing.T) {
-	read := &probeTool{name: "probe_read", sideEffect: tools.SideEffectRead, delay: 30 * time.Millisecond}
-	write := &probeTool{name: "probe_write", sideEffect: tools.SideEffectWrite}
-	// Shared log across both probes so relative ordering is observable.
-	write.mu = sync.Mutex{}
+	shared := &probeLog{}
+	read := &probeTool{name: "probe_read", sideEffect: tools.SideEffectRead, delay: 30 * time.Millisecond, shared: shared}
+	write := &probeTool{name: "probe_write", sideEffect: tools.SideEffectWrite, shared: shared}
 	registry := tools.NewRegistry()
 	registry.Register(read)
 	registry.Register(write)
@@ -151,32 +177,26 @@ func TestRunParallelReadsNeverSpanMutatingCall(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	// The write must start only after r1+r2 finished, and r3/r4 must start only
-	// after the write finished: batches never cross a mutating call.
-	index := func(log []string, entry string) int {
+
+	// Cross-probe ordering on the SHARED log: the write must start only after
+	// both first-batch reads finished, and both second-batch reads must start
+	// only after the write finished — batches never cross a mutating call.
+	log := shared.snapshot()
+	index := func(entry string) int {
 		for i, e := range log {
 			if e == entry {
 				return i
 			}
 		}
+		t.Fatalf("entry %q missing from shared log: %v", entry, log)
 		return -1
 	}
-	readLog := func() []string { read.mu.Lock(); defer read.mu.Unlock(); return append([]string(nil), read.log...) }()
-	writeLog := func() []string { write.mu.Lock(); defer write.mu.Unlock(); return append([]string(nil), write.log...) }()
-	if index(writeLog, "start:w") == -1 {
-		t.Fatalf("write probe never ran: %v", writeLog)
+	writeStart, writeEnd := index("start:w"), index("end:w")
+	if firstBatchMaxEnd := max(index("end:r1"), index("end:r2")); writeStart < firstBatchMaxEnd {
+		t.Fatalf("write started before the first read batch finished: %v", log)
 	}
-	for _, entry := range []string{"end:r1", "end:r2"} {
-		if index(readLog, entry) == -1 {
-			t.Fatalf("first read batch incomplete: %v", readLog)
-		}
-	}
-	// r3/r4 must appear strictly after r1/r2 in the read log (the write barrier
-	// between the two batches forces full separation).
-	firstBatchMaxEnd := max(index(readLog, "end:r1"), index(readLog, "end:r2"))
-	secondBatchMinStart := min(index(readLog, "start:r3"), index(readLog, "start:r4"))
-	if secondBatchMinStart < firstBatchMaxEnd {
-		t.Fatalf("second read batch started before first batch ended: %v", readLog)
+	if secondBatchMinStart := min(index("start:r3"), index("start:r4")); secondBatchMinStart < writeEnd {
+		t.Fatalf("second read batch started before the write finished: %v", log)
 	}
 	if read.maxActive < 2 {
 		t.Fatalf("reads within a batch must overlap, max concurrency was %d", read.maxActive)

internal/agent/partition_cache_test.go

@@ -0,0 +1,63 @@
+package agent
+
+import (
+	"context"
+	"reflect"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/tools"
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+// countingSchemaTool records how many times its Parameters() schema is read, so a
+// test can prove the definition cache avoids re-rendering across turns.
+type countingSchemaTool struct {
+	name  string
+	calls *int
+}
+
+func (t countingSchemaTool) Name() string        { return t.name }
+func (t countingSchemaTool) Description() string { return "counts schema reads" }
+func (t countingSchemaTool) Parameters() tools.Schema {
+	*t.calls++
+	return tools.Schema{Type: "object", AdditionalProperties: false, Properties: map[string]tools.PropertySchema{
+		"x": {Type: "string"},
+	}}
+}
+func (t countingSchemaTool) Safety() tools.Safety {
+	return tools.Safety{SideEffect: tools.SideEffectRead, Permission: tools.PermissionAllow}
+}
+func (t countingSchemaTool) Run(_ context.Context, _ map[string]any) tools.Result {
+	return tools.Result{Status: tools.StatusOK}
+}
+
+// The cache renders a tool's schema once and reuses it across calls, and its
+// output is identical to the uncached path.
+func TestPartitionToolsCacheRendersOnceAndMatchesUncached(t *testing.T) {
+	calls := 0
+	registry := tools.NewRegistry()
+	registry.Register(countingSchemaTool{name: "alpha", calls: &calls})
+	registry.Register(countingSchemaTool{name: "beta", calls: &calls})
+
+	uncached, _ := partitionTools(registry, PermissionModeAuto, Options{}, map[string]bool{})
+
+	base := calls
+	cache := map[string]zeroruntime.ToolDefinition{}
+	first, _ := partitionToolsCached(registry, PermissionModeAuto, Options{}, map[string]bool{}, cache)
+	rendersAfterFirst := calls - base
+	second, _ := partitionToolsCached(registry, PermissionModeAuto, Options{}, map[string]bool{}, cache)
+	rendersAfterSecond := calls - base
+
+	if rendersAfterFirst != 2 {
+		t.Fatalf("first cached call should render 2 tools once each, rendered %d times", rendersAfterFirst)
+	}
+	if rendersAfterSecond != 2 {
+		t.Fatalf("second cached call must reuse the cache (no new schema reads), total renders = %d", rendersAfterSecond)
+	}
+	if !reflect.DeepEqual(first, second) {
+		t.Fatal("cached calls must return identical definitions")
+	}
+	if !reflect.DeepEqual(first, uncached) {
+		t.Fatal("cached output must match the uncached partitionTools output")
+	}
+}

internal/agent/plan_staleness_test.go

@@ -0,0 +1,64 @@
+package agent
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+func planUpdateTurn(status string) zeroruntime.CollectedStream {
+	return zeroruntime.CollectedStream{ToolCalls: []zeroruntime.ToolCall{
+		{Name: "update_plan", Arguments: `{"plan":[{"content":"step one","status":"` + status + `"}]}`},
+	}}
+}
+
+// Turn-based staleness: a plan that goes many turns without an update — while
+// items are still pending — draws the stale reminder even though few tool calls
+// have run (the tool-call streak alone would not have tripped).
+func TestPlanReminderFiresOnTurnStaleness(t *testing.T) {
+	state := newGuardState()
+	state.observeTurn(planUpdateTurn("in_progress"))
+
+	// Text-only turns advance the turn counter without adding tool calls.
+	for range stalePlanTurnThreshold {
+		state.observeTurn(zeroruntime.CollectedStream{Text: "still working…"})
+	}
+
+	if state.toolCallsSincePlanUpdate >= staleToolCallThreshold {
+		t.Fatalf("precondition: the tool-call trigger must not fire (%d calls)", state.toolCallsSincePlanUpdate)
+	}
+	if got := state.planReminder(stalePlanTurnThreshold + 2); !strings.Contains(got, planStaleReminderMarker) {
+		t.Fatalf("expected a turn-based stale reminder, got %q", got)
+	}
+}
+
+// A fully-completed plan is NOT stale: no pending items means the turn-based
+// trigger stays quiet even after many turns, so a finished plan isn't nagged.
+func TestPlanReminderSkipsTurnStalenessWhenComplete(t *testing.T) {
+	state := newGuardState()
+	state.observeTurn(planUpdateTurn("completed"))
+
+	for range stalePlanTurnThreshold + 3 {
+		state.observeTurn(zeroruntime.CollectedStream{Text: "wrapping up…"})
+	}
+
+	if got := state.planReminder(stalePlanTurnThreshold + 5); got != "" {
+		t.Fatalf("a completed plan must not draw a stale reminder, got %q", got)
+	}
+}
+
+// A plan update resets the turn counter, so the stale reminder does not fire
+// right after a fresh update.
+func TestPlanUpdateResetsTurnStaleness(t *testing.T) {
+	state := newGuardState()
+	state.observeTurn(planUpdateTurn("in_progress"))
+	for range stalePlanTurnThreshold - 1 {
+		state.observeTurn(zeroruntime.CollectedStream{Text: "working…"})
+	}
+	// Refresh the plan — resets the turn streak.
+	state.observeTurn(planUpdateTurn("in_progress"))
+	if got := state.planReminder(stalePlanTurnThreshold + 1); got != "" {
+		t.Fatalf("a just-refreshed plan must not be stale, got %q", got)
+	}
+}

internal/agent/reconnect.go

@@ -3,9 +3,11 @@ package agent
 import (
 	"context"
 	"fmt"
+	"math/rand"
 	"strings"
 	"time"
 
+	"github.com/Gitlawb/zero/internal/errhint"
 	"github.com/Gitlawb/zero/internal/zeroruntime"
 )
 
@@ -17,10 +19,20 @@ import (
 // times. We retry ONLY the connect (not a partially-consumed stream), so no
 // already-forwarded OnText is ever duplicated.
 const (
-	maxStreamReconnects = 2
-	streamReconnectBase = 500 * time.Millisecond
+	// maxStreamReconnects is how many times the connect is re-issued after a
+	// transient disconnect. 4 (not 2): with jittered exponential backoff this rides
+	// out a multi-second network blip (~0.5s + 1s + 2s + 4s worst case) instead of
+	// dying on a 2s hiccup and re-burning every token on a restart.
+	maxStreamReconnects = 4
+	// streamReconnectMax caps a single backoff so the tail attempts don't wait
+	// minutes on a long outage.
+	streamReconnectMax = 8 * time.Second
 )
 
+// streamReconnectBase is the first-retry delay (doubled each subsequent attempt).
+// A var, not a const, so tests can shrink it to keep the exhaustion path fast.
+var streamReconnectBase = 500 * time.Millisecond
+
 // reconnectNotifier is called before each retry with the 1-based attempt number
 // and the max, so the caller can surface a "Reconnecting N/max" notice. Nil is
 // fine.
@@ -73,7 +85,7 @@ func streamWithReconnect(ctx context.Context, provider Provider, request zerorun
 		if notify != nil {
 			notify(attempt, maxStreamReconnects)
 		}
-		if waitErr := sleepWithContext(ctx, backoffFor(attempt)); waitErr != nil {
+		if waitErr := sleepWithContext(ctx, jitteredBackoff(attempt)); waitErr != nil {
 			return nil, err // ctx cancelled while waiting; surface the original error
 		}
 		stream, err = provider.StreamCompletion(ctx, request)
@@ -96,6 +108,19 @@ func shouldReconnect(ctx context.Context, err error) bool {
 	if isContextLimitError(msg) || isImageRejectionError(err) {
 		return false
 	}
+	// HTTP 5xx statuses are non-reconnectable and must be excluded BEFORE the
+	// transport substring match below — otherwise "504 Gateway Timeout" would slip
+	// through on the generic "timeout" needle. 503 already exhausted
+	// providerio.SendWithRetry (retrying is a redundant double-retry); 500/502/504
+	// are non-idempotent by providerio's rule — the completion POST may already
+	// have reached the model before the upstream/gateway gave up, so replaying the
+	// connect risks duplicate billable work. Digit-boundary matched so an
+	// incidental "504" inside a latency/id number is not mistaken for a status.
+	if errhint.HasStatusCode(msg, "500", "502", "503", "504") {
+		return false
+	}
+	// Transport-level disconnects only. A genuine transport failure (EOF, reset,
+	// refused, timeout) means no response was received, which is safe to reconnect.
 	for _, needle := range []string{
 		"eof",
 		"connection reset",
@@ -106,8 +131,6 @@ func shouldReconnect(ctx context.Context, err error) bool {
 		"timed out",
 		"temporarily unavailable",
 		"i/o timeout",
-		"503",
-		"502",
 		"server closed",
 		"unexpected end",
 	} {
@@ -118,14 +141,31 @@ func shouldReconnect(ctx context.Context, err error) bool {
 	return false
 }
 
+// backoffFor is the deterministic exponential base delay for a 1-based attempt,
+// capped at streamReconnectMax. Jitter is layered on separately (jitteredBackoff).
 func backoffFor(attempt int) time.Duration {
 	d := streamReconnectBase
 	for i := 1; i < attempt; i++ {
+		if d >= streamReconnectMax {
+			return streamReconnectMax
+		}
 		d *= 2
 	}
+	if d > streamReconnectMax {
+		d = streamReconnectMax
+	}
 	return d
 }
 
+// jitteredBackoff adds up to 50% random jitter on top of backoffFor so concurrent
+// runs (swarm members, a cron fleet) that all trip on the same outage don't
+// reconnect in lockstep and hammer a recovering endpoint. Never shorter than the
+// deterministic base, so backoff still grows attempt over attempt.
+func jitteredBackoff(attempt int) time.Duration {
+	base := backoffFor(attempt)
+	return base + time.Duration(rand.Int63n(int64(base/2)+1))
+}
+
 func sleepWithContext(ctx context.Context, d time.Duration) error {
 	timer := time.NewTimer(d)
 	defer timer.Stop()

internal/agent/reconnect_test.go

@@ -44,6 +44,10 @@ func TestStreamWithReconnectRecoversFromTransientDisconnect(t *testing.T) {
 }
 
 func TestStreamWithReconnectGivesUpAfterMax(t *testing.T) {
+	// Shrink the backoff so exhausting all retries stays fast (real base would
+	// sleep ~7.5s across 4 attempts).
+	defer func(orig time.Duration) { streamReconnectBase = orig }(streamReconnectBase)
+	streamReconnectBase = time.Millisecond
 	// Always fails with a disconnect error → exhausts retries and returns it.
 	p := &flakyProvider{failBefore: 99, failErr: errors.New("connection reset by peer")}
 	_, err := streamWithReconnect(context.Background(), p, zeroruntime.CompletionRequest{}, nil)
@@ -87,7 +91,7 @@ func TestShouldReconnectClassification(t *testing.T) {
 	ctx := context.Background()
 	disconnects := []string{
 		"unexpected EOF", "connection reset by peer", "broken pipe",
-		"i/o timeout", "503 Service Unavailable", "server closed the connection",
+		"i/o timeout", "server closed the connection", "connection refused",
 	}
 	for _, m := range disconnects {
 		if !shouldReconnect(ctx, errors.New(m)) {
@@ -97,6 +101,13 @@ func TestShouldReconnectClassification(t *testing.T) {
 	notDisconnects := []string{
 		"context length exceeded", "invalid api key", "model not found",
 		"400 bad request: unsupported parameter",
+		// HTTP 5xx statuses are handled by providerio.SendWithRetry (503) or are
+		// non-idempotent (500/502/504); the reconnect path must not double-retry
+		// them. "504 Gateway Timeout" must NOT slip through on the generic "timeout"
+		// transport signal — a gateway timeout is non-idempotent, since the upstream
+		// may have already processed the completion POST before giving up.
+		"503 Service Unavailable", "502 Bad Gateway",
+		"504 Gateway Timeout", "500 Internal Server Error",
 	}
 	for _, m := range notDisconnects {
 		if shouldReconnect(ctx, errors.New(m)) {
@@ -112,6 +123,24 @@ func TestBackoffGrows(t *testing.T) {
 	if backoffFor(2) != 2*streamReconnectBase {
 		t.Fatalf("attempt 2 backoff = %v, want %v", backoffFor(2), 2*streamReconnectBase)
 	}
+	// The exponential base is capped so late attempts don't wait minutes.
+	if got := backoffFor(20); got != streamReconnectMax {
+		t.Fatalf("attempt 20 backoff = %v, want cap %v", got, streamReconnectMax)
+	}
+}
+
+func TestJitteredBackoffStaysInBounds(t *testing.T) {
+	// Jitter never drops below the deterministic base and never exceeds base*1.5,
+	// so backoff still grows attempt over attempt while decorrelating retries.
+	for attempt := 1; attempt <= 5; attempt++ {
+		base := backoffFor(attempt)
+		for i := 0; i < 200; i++ {
+			got := jitteredBackoff(attempt)
+			if got < base || got > base+base/2 {
+				t.Fatalf("attempt %d jittered backoff %v out of [%v, %v]", attempt, got, base, base+base/2)
+			}
+		}
+	}
 }
 
 func TestReconnectNoticeRoutesThroughReasoning(t *testing.T) {

internal/agent/skills_context_test.go

@@ -7,14 +7,18 @@ import (
 )
 
 func TestSkillsContextCapsLongList(t *testing.T) {
-	skills := make([]SkillInfo, 0, 40)
-	for i := 0; i < 40; i++ {
+	// 60 skills with realistic trigger-rich descriptions (~180 chars each, under
+	// the 200-rune truncation) total well past the 4096-byte list budget, so the
+	// overflow summary must kick in while the block stays bounded.
+	longDesc := strings.Repeat("use when the request touches deployments, release notes, or verification; ", 2) + "number "
+	skills := make([]SkillInfo, 0, 60)
+	for i := 0; i < 60; i++ {
 		n := strconv.Itoa(i)
-		skills = append(skills, SkillInfo{Name: "skill-" + n, Description: "does something useful, number " + n})
+		skills = append(skills, SkillInfo{Name: "skill-" + n, Description: longDesc + n})
 	}
 	got := skillsContext(Options{Skills: skills})
-	if len(got) > 1200 {
-		t.Fatalf("skills block should stay bounded, got %d bytes:\n%s", len(got), got)
+	if len(got) > skillsContextListBudget+1000 {
+		t.Fatalf("skills block should stay bounded near the %d-byte budget, got %d bytes:\n%s", skillsContextListBudget, len(got), got)
 	}
 	if !strings.Contains(got, "more (call skill") {
 		t.Fatalf("expected an overflow summary line, got:\n%s", got)
@@ -25,6 +29,27 @@ func TestSkillsContextCapsLongList(t *testing.T) {
 	}
 }
 
+// A realistic mid-size skill set (20 skills, trigger-rich descriptions) must be
+// listed in FULL — no overflow summary. This pins the fix for the old 640-byte
+// budget, under which skills past ~#6 were invisible to the model and therefore
+// never triggered.
+func TestSkillsContextListsRealisticSetInFull(t *testing.T) {
+	desc := "Use when the user asks about deployments, release notes, or pre-merge verification runs."
+	skills := make([]SkillInfo, 0, 20)
+	for i := 0; i < 20; i++ {
+		skills = append(skills, SkillInfo{Name: "skill-" + strconv.Itoa(i), Description: desc})
+	}
+	got := skillsContext(Options{Skills: skills})
+	if strings.Contains(got, "more (call skill") {
+		t.Fatalf("20 described skills must all be listed without overflow, got:\n%s", got)
+	}
+	for i := 0; i < 20; i++ {
+		if !strings.Contains(got, "- skill-"+strconv.Itoa(i)+":") {
+			t.Fatalf("skill-%d missing from the list:\n%s", i, got)
+		}
+	}
+}
+
 func TestSkillsContext(t *testing.T) {
 	if got := skillsContext(Options{}); got != "" {
 		t.Fatalf("no skills should yield an empty section, got %q", got)

internal/agent/system_prompt.go

@@ -9,6 +9,7 @@ import (
 	"strings"
 	"unicode/utf8"
 
+	"github.com/Gitlawb/zero/internal/config"
 	"github.com/Gitlawb/zero/internal/repomap"
 	"github.com/Gitlawb/zero/internal/workspaceseed"
 )
@@ -38,6 +39,14 @@ const fallbackSystemPrompt = "You are Zero, a terminal coding agent. Help with t
 // general-to-specific order.
 var projectContextFiles = []string{"AGENTS.md", "ZERO.md", ".zero/AGENTS.md"}
 
+// userContextFile is the per-user instruction file, resolved under
+// config.UserConfigDir()/zero/ alongside the rest of Zero's per-user config
+// (config.json, commands, specialists) so users can keep personal guidance out
+// of individual repositories.
+const userContextFile = "ZERO.md"
+
+var userConfigDirForPrompt = config.UserConfigDir
+
 // maxProjectContextBytes caps how much of a single project doc is injected so
 // a large guidelines file can't blow the context budget.
 const maxProjectContextBytes = 8 << 10 // 8 KiB per file
@@ -81,6 +90,13 @@ func buildSystemPrompt(options Options) string {
 	if seed := workspaceSeedContext(options.Cwd); seed != "" {
 		sections = append(sections, seed)
 	}
+	// User guidelines are injected before workspace/project guidelines so the
+	// project's AGENTS.md/ZERO.md is the later, more specific instruction
+	// block. See userGuidelines for the explicit precedence note carried in
+	// the section text itself.
+	if user := userGuidelines(); user != "" {
+		sections = append(sections, user)
+	}
 	if ws := workspaceContext(options.Cwd); ws != "" {
 		sections = append(sections, ws)
 	}
@@ -175,10 +191,19 @@ func specialistDelegationContext(options Options) string {
 // when no skills are installed, so a skill-less run reproduces the previous prompt
 // byte-for-byte.
 // skillsContextListBudget bounds the bytes spent listing individual skills so a
-// workspace with dozens of them can't bloat every turn's prompt. Skills past the
-// budget are summarized as a count rather than dropped — the model can still load
-// any of them by name (an unknown name returns the full list from the skill tool).
-const skillsContextListBudget = 640
+// workspace with an extreme number of them can't bloat every turn's prompt.
+// Skills past the budget are summarized as a count rather than dropped — the
+// model can still load any of them by name (an unknown name returns the full
+// list from the skill tool).
+//
+// The budget is deliberately generous — roughly 18 skills with maximally long
+// (200-rune, ASCII) descriptions, or 40+ with typical terser ones; non-ASCII
+// descriptions consume it faster since the budget counts bytes. This list is
+// the model's ONLY discovery surface, so a skill squeezed out of it effectively
+// never triggers. The previous 640-byte cap silently broke invocation for
+// anyone with more than ~6 skills — the model cannot match a request against a
+// skill it cannot see.
+const skillsContextListBudget = 4096
 
 func skillsContext(options Options) string {
 	if len(options.Skills) == 0 {
@@ -186,7 +211,7 @@ func skillsContext(options Options) string {
 	}
 	var b strings.Builder
 	b.WriteString("<available_skills>\n")
-	b.WriteString("Reusable, on-demand instruction sets you can load with the skill tool. When a request matches one, call skill with its exact name to pull in its guidance before acting — do not guess names or skip a relevant skill.\n")
+	b.WriteString("Reusable, on-demand instruction sets you can load with the skill tool. Before acting on a request, scan this list; when the request matches a skill's name or description, call skill with its exact name FIRST and follow the loaded guidance — do not guess names, do not skip a matching skill, and do not substitute your own approach for its instructions.\n")
 	listed, spent, omitted := 0, 0, 0
 	for _, info := range options.Skills {
 		name := strings.TrimSpace(info.Name)
@@ -216,9 +241,11 @@ func skillsContext(options Options) string {
 }
 
 // truncateForSkillLine keeps a skill's one-line description short so a single
-// verbose description can't dominate the skills-list budget.
+// verbose description can't dominate the skills-list budget. The cap is roomy on
+// purpose: the description carries the skill's trigger conditions ("use when…"),
+// and truncating those is what stops the model from ever invoking the skill.
 func truncateForSkillLine(desc string) string {
-	const maxDescRunes = 100
+	const maxDescRunes = 200
 	runes := []rune(desc)
 	if len(runes) <= maxDescRunes {
 		return desc
@@ -312,13 +339,7 @@ func projectGuidelines(cwd, gitRoot string) string {
 		if remaining := maxProjectContextTotalBytes - totalUsed; remaining < limit {
 			limit = remaining
 		}
-		if len(content) > limit {
-			cut := limit
-			for cut > 0 && !utf8.RuneStart(content[cut]) {
-				cut--
-			}
-			content = content[:cut] + "\n… (truncated)"
-		}
+		content = truncateGuidelineContent(content, limit)
 		label := projectGuidelineLabel(match, gitRoot)
 		b.WriteString("\n\n## Project guidelines (" + label + ")\n\n" + content)
 		totalUsed += len(content)
@@ -326,6 +347,92 @@ func projectGuidelines(cwd, gitRoot string) string {
 	return b.String()
 }
 
+// userGuidelines returns the per-user ZERO.md instructions block, if present.
+// The file lives in config.UserConfigDir()/zero/ next to Zero's other
+// per-user config; the basename match is case-insensitive so a file saved as
+// zero.md still resolves on case-sensitive filesystems, mirroring the project
+// guideline loader. The section carries an explicit precedence note because
+// this is a global, personal preferences file: it is injected earlier in the
+// prompt than the project's AGENTS.md/ZERO.md (see buildSystemPrompt), and
+// the note keeps that precedence unambiguous even if a model weighs later
+// context more heavily than section order alone implies.
+func userGuidelines() string {
+	configDir, err := userConfigDirForPrompt()
+	if err != nil {
+		return ""
+	}
+	configDir = strings.TrimSpace(configDir)
+	if configDir == "" {
+		return ""
+	}
+	match := findCaseInsensitiveFile(filepath.Join(configDir, "zero"), userContextFile)
+	if match == "" {
+		return ""
+	}
+	data, err := os.ReadFile(match)
+	if err != nil {
+		return ""
+	}
+	content := strings.TrimSpace(string(data))
+	if content == "" {
+		return ""
+	}
+	content = truncateGuidelineContent(content, maxProjectContextBytes)
+	return "## User guidelines (" + filepath.Base(match) + ")\n\n" +
+		"These are the operator's personal preferences, not project policy. " +
+		"Where they conflict with a repository's project guidelines below (AGENTS.md/ZERO.md), the project guidelines take precedence.\n\n" +
+		content
+}
+
+// truncationMarker is appended to guideline content that was cut short.
+const truncationMarker = "\n… (truncated)"
+
+// truncateGuidelineContent caps content at limit bytes without splitting a
+// UTF-8 rune, appending a truncation marker when anything was cut. Space for
+// the marker is reserved before choosing the cut point. When limit is too
+// small to fit the marker itself, the marker is dropped instead, so the
+// returned string never exceeds limit for any non-negative limit.
+func truncateGuidelineContent(content string, limit int) string {
+	if len(content) <= limit {
+		return content
+	}
+	if limit <= 0 {
+		return ""
+	}
+	cut := limit - len(truncationMarker)
+	if cut < 0 {
+		cut = 0
+	}
+	for cut > 0 && !utf8.RuneStart(content[cut]) {
+		cut--
+	}
+	if truncated := content[:cut] + truncationMarker; len(truncated) <= limit {
+		return truncated
+	}
+	// limit is smaller than the marker itself: fall back to a hard,
+	// rune-safe cut at limit bytes with no marker rather than exceeding it.
+	end := limit
+	for end > 0 && !utf8.RuneStart(content[end]) {
+		end--
+	}
+	return content[:end]
+}
+
+// findCaseInsensitiveFile returns the on-disk path of the regular file in dir
+// whose name matches basename case-insensitively, or "" when absent.
+func findCaseInsensitiveFile(dir, basename string) string {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return ""
+	}
+	for _, e := range entries {
+		if !e.IsDir() && strings.EqualFold(e.Name(), basename) {
+			return filepath.Join(dir, e.Name())
+		}
+	}
+	return ""
+}
+
 // projectGuidelineDirs returns the directory chain from gitRoot to cwd
 // (inclusive), in root-to-leaf order. If gitRoot is empty or unreachable
 // from cwd, the chain collapses to [cwd].
@@ -378,23 +485,16 @@ func projectGuidelineLabel(match, gitRoot string) string {
 // Returns "" when nothing matches.
 func findProjectContextFile(dir string) string {
 	for _, name := range projectContextFiles {
-		baseLower := strings.ToLower(filepath.Base(name))
 		// Walk to the file's parent through dir with case-insensitive segment
-		// matching, then find a regular file with the same lowercased
-		// basename. This works on both case-sensitive and case-insensitive
-		// filesystems and always returns the on-disk filename.
+		// matching, then find a regular file with the same basename. This works
+		// on both case-sensitive and case-insensitive filesystems and always
+		// returns the on-disk filename.
 		parent, ok := resolveDirCaseInsensitive(filepath.Dir(filepath.Join(dir, name)), dir)
 		if !ok {
 			continue
 		}
-		entries, err := os.ReadDir(parent)
-		if err != nil {
-			continue
-		}
-		for _, e := range entries {
-			if !e.IsDir() && strings.ToLower(e.Name()) == baseLower {
-				return filepath.Join(parent, e.Name())
-			}
+		if match := findCaseInsensitiveFile(parent, filepath.Base(name)); match != "" {
+			return match
 		}
 	}
 	return ""

internal/agent/system_prompt.md

@@ -63,6 +63,10 @@ work.
   targeted diffs. Match the existing indentation, imports, and idioms. Match the
   file's comment density: do not add explanatory comments unless the user asks or
   the code is already comment-dense.
+- Solve the problem as posed, not a more general version of it. Add no
+  speculative abstraction, configurability, or handling for cases that cannot
+  occur, and nothing the user did not ask for. A small diff can still be
+  over-built; if a 200-line solution could be 50, rewrite it.
 - Preserve behavior you were not asked to change. Do not delete or rewrite code
   you did not author unless the task requires it; if you must, say so.
 

internal/agent/system_prompt_test.go

@@ -9,6 +9,25 @@ import (
 	"github.com/Gitlawb/zero/internal/sandbox"
 )
 
+// TestMain points userConfigDirForPrompt at an empty, package-wide temp
+// directory for every test in this package. Without this, buildSystemPrompt
+// falls back to the real config.UserConfigDir, so any developer with a
+// personal ~/.config/zero/ZERO.md would get its content folded into
+// otherwise-unrelated prompt assertions, making test runs non-deterministic
+// across contributor machines. Tests that specifically exercise user
+// guidelines stub userConfigDirForPrompt themselves via
+// withSystemPromptTestUserConfigDir(Func) and restore this default on cleanup.
+func TestMain(m *testing.M) {
+	dir, err := os.MkdirTemp("", "zero-agent-tests-*")
+	if err != nil {
+		panic(err)
+	}
+	userConfigDirForPrompt = func() (string, error) { return dir, nil }
+	code := m.Run()
+	os.RemoveAll(dir)
+	os.Exit(code)
+}
+
 func TestCoreSystemPromptIncludesCodingQualityRules(t *testing.T) {
 	prompt := strings.ToLower(buildSystemPrompt(Options{}))
 
@@ -128,6 +147,88 @@ func systemPromptTestBlock(t *testing.T, prompt, start, end string) string {
 	return body
 }
 
+func TestBuildSystemPromptIncludesUserGuidelines(t *testing.T) {
+	configDir := t.TempDir()
+	writeSystemPromptTestFile(t, configDir, "zero/ZERO.md", "  Prefer concise summaries.  \n")
+	t.Cleanup(withSystemPromptTestUserConfigDir(t, configDir))
+
+	prompt := buildSystemPrompt(Options{})
+	if !strings.Contains(prompt, "## User guidelines (ZERO.md)") {
+		t.Fatalf("expected user guidelines header, got:\n%s", prompt)
+	}
+	if !strings.Contains(prompt, "Prefer concise summaries.") {
+		t.Fatalf("expected user guidelines content, got:\n%s", prompt)
+	}
+	if strings.Contains(prompt, "  Prefer concise summaries.  ") {
+		t.Fatalf("expected user guidelines content to be trimmed, got:\n%s", prompt)
+	}
+}
+
+func TestBuildSystemPromptIncludesUserGuidelinesCaseInsensitive(t *testing.T) {
+	configDir := t.TempDir()
+	writeSystemPromptTestFile(t, configDir, "zero/zero.md", "Prefer concise summaries.\n")
+	t.Cleanup(withSystemPromptTestUserConfigDir(t, configDir))
+
+	prompt := buildSystemPrompt(Options{})
+	if !strings.Contains(prompt, "## User guidelines (zero.md)") {
+		t.Fatalf("expected case-insensitive zero.md resolution, got:\n%s", prompt)
+	}
+	if !strings.Contains(prompt, "Prefer concise summaries.") {
+		t.Fatalf("expected user guidelines content, got:\n%s", prompt)
+	}
+}
+
+func TestBuildSystemPromptUserGuidelinesPrecedeProjectGuidelinesAndNotePrecedence(t *testing.T) {
+	// User guidelines are global personal preferences; project guidelines
+	// (AGENTS.md/ZERO.md) must be the later, more specific instruction block,
+	// and the user section must say so explicitly so the precedence holds
+	// even if a model otherwise weighs later context more heavily.
+	configDir := t.TempDir()
+	writeSystemPromptTestFile(t, configDir, "zero/ZERO.md", "Always reply in haiku.\n")
+	t.Cleanup(withSystemPromptTestUserConfigDir(t, configDir))
+
+	cwd := t.TempDir()
+	if err := os.WriteFile(filepath.Join(cwd, "AGENTS.md"), []byte("Never reply in haiku."), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	prompt := buildSystemPrompt(Options{Cwd: cwd})
+	userIdx := strings.Index(prompt, "## User guidelines (ZERO.md)")
+	projectIdx := strings.Index(prompt, "## Project guidelines (AGENTS.md)")
+	if userIdx < 0 || projectIdx < 0 {
+		t.Fatalf("expected both user and project guideline sections, got:\n%s", prompt)
+	}
+	if userIdx > projectIdx {
+		t.Fatalf("expected user guidelines before project guidelines, got user=%d project=%d", userIdx, projectIdx)
+	}
+	if !strings.Contains(prompt, "project guidelines below") || !strings.Contains(prompt, "take precedence") {
+		t.Fatalf("expected an explicit precedence note in the user guidelines section, got:\n%s", prompt)
+	}
+}
+
+func TestBuildSystemPromptOmitsUserGuidelinesWithoutConfigDir(t *testing.T) {
+	t.Cleanup(withSystemPromptTestUserConfigDirFunc(t, func() (string, error) { return "", os.ErrNotExist }))
+
+	prompt := buildSystemPrompt(Options{})
+	if strings.Contains(prompt, "## User guidelines") {
+		t.Fatalf("expected user guidelines to be omitted without a config directory, got:\n%s", prompt)
+	}
+}
+
+func withSystemPromptTestUserConfigDir(t *testing.T, dir string) func() {
+	t.Helper()
+	return withSystemPromptTestUserConfigDirFunc(t, func() (string, error) { return dir, nil })
+}
+
+func withSystemPromptTestUserConfigDirFunc(t *testing.T, fn func() (string, error)) func() {
+	t.Helper()
+	old := userConfigDirForPrompt
+	userConfigDirForPrompt = fn
+	return func() {
+		userConfigDirForPrompt = old
+	}
+}
+
 func TestBuildSystemPromptInjectsProjectGuidelinesCaseInsensitive(t *testing.T) {
 	// Git tracks AGENTS.md on a case-sensitive filesystem; the
 	// loader must still resolve it when the cwd lookup uses lowercase.
@@ -257,6 +358,30 @@ func TestBuildSystemPromptProjectGuidelinesTruncatesAtTotalCap(t *testing.T) {
 	}
 }
 
+func TestTruncateGuidelineContentStaysWithinLimit(t *testing.T) {
+	limit := 64
+	content := strings.Repeat("x", limit+1)
+	got := truncateGuidelineContent(content, limit)
+	if len(got) > limit {
+		t.Fatalf("truncated result is %d bytes, want at most %d", len(got), limit)
+	}
+	if !strings.Contains(got, "truncated") {
+		t.Fatalf("expected truncation marker, got %q", got)
+	}
+}
+
+func TestTruncateGuidelineContentStaysWithinLimitForSmallBudgets(t *testing.T) {
+	// Limits at or below the truncation marker's own length can't fit the
+	// marker at all; the helper must still never exceed the requested limit.
+	content := strings.Repeat("x", 100)
+	for _, limit := range []int{0, 1, len(truncationMarker) - 1, len(truncationMarker), len(truncationMarker) + 1} {
+		got := truncateGuidelineContent(content, limit)
+		if len(got) > limit {
+			t.Fatalf("truncateGuidelineContent(_, %d) = %q (%d bytes), want at most %d bytes", limit, got, len(got), limit)
+		}
+	}
+}
+
 func TestProjectGuidelineDirsOrdersRootToLeaf(t *testing.T) {
 	root := filepath.Join("r")
 	leaf := filepath.Join(root, "a", "b")

internal/cli/app.go

@@ -12,6 +12,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/Gitlawb/zero/internal/agent"
@@ -78,6 +79,8 @@ type appDeps struct {
 	runAgentEval           func(context.Context, agentEvalOptions) (agentEvalReport, error)
 	inspectChanges         func(context.Context, zerogit.InspectOptions) (zerogit.ChangeSummary, error)
 	commitChanges          func(context.Context, zerogit.CommitOptions) (zerogit.CommitResult, error)
+	pushChanges            func(context.Context, zerogit.PushOptions) (zerogit.PushResult, error)
+	createPR               func(context.Context, zerogit.PROptions) (zerogit.PRResult, error)
 	runTUI                 func(context.Context, tui.Options) int
 	runEditor              func(string) error
 	checkUpdate            func(context.Context, update.Options) (update.Result, error)
@@ -179,6 +182,8 @@ func defaultAppDeps() appDeps {
 		runAgentEval:     defaultRunAgentEval,
 		inspectChanges:   zerogit.Inspect,
 		commitChanges:    zerogit.Commit,
+		pushChanges:      zerogit.Push,
+		createPR:         zerogit.CreatePR,
 		runTUI:           tui.Run,
 		runEditor:        openEditor,
 		checkUpdate:      update.Check,
@@ -517,6 +522,12 @@ func fillAppDeps(deps appDeps) appDeps {
 	if deps.commitChanges == nil {
 		deps.commitChanges = defaults.commitChanges
 	}
+	if deps.pushChanges == nil {
+		deps.pushChanges = defaults.pushChanges
+	}
+	if deps.createPR == nil {
+		deps.createPR = defaults.createPR
+	}
 	if deps.runTUI == nil {
 		deps.runTUI = defaults.runTUI
 	}
@@ -772,6 +783,14 @@ func runInteractiveTUIWithSetup(stderr io.Writer, deps appDeps, permissionMode a
 			Specialists:    specialistRuntime.specialists,
 			Skills:         pluginActivation.skillInfos(deps.skillsDir()),
 		},
+		// LoadSkills backs /skills and direct /<skill-name> invocation in the TUI.
+		// It resolves against the same merged set (default dir + plugin skill
+		// roots) as the skill tool and the system-prompt list, re-read per use so
+		// newly installed skills work without a restart.
+		LoadSkills: cachedSkillsLoader(func() []skills.Skill {
+			merged, _ := plugins.MergedSkillsLoaded(deps.skillsDir(), pluginActivation.skillRoots)
+			return merged
+		}),
 		PermissionMode: permissionMode,
 		Notify:         resolved.Notify,
 		KeyBindings:    resolved.KeyBindings,
@@ -1267,3 +1286,26 @@ Flags:
 `)
 	return err
 }
+
+// cachedSkillsLoader memoizes a skills loader for a short interval. The TUI
+// calls the loader from autocomplete on every "/x" keystroke; without a cache
+// each keystroke would re-read every SKILL.md body. Two seconds is fresh enough
+// that a newly installed skill still shows up "immediately" while typing.
+func cachedSkillsLoader(load func() []skills.Skill) func() []skills.Skill {
+	var (
+		mu     sync.Mutex
+		at     time.Time
+		cached []skills.Skill
+	)
+	const ttl = 2 * time.Second
+	return func() []skills.Skill {
+		mu.Lock()
+		defer mu.Unlock()
+		if cached != nil && time.Since(at) < ttl {
+			return cached
+		}
+		cached = load()
+		at = time.Now()
+		return cached
+	}
+}

internal/cli/exec.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/Gitlawb/zero/internal/agent"
 	"github.com/Gitlawb/zero/internal/config"
+	"github.com/Gitlawb/zero/internal/errhint"
 	"github.com/Gitlawb/zero/internal/imageinput"
 	"github.com/Gitlawb/zero/internal/lsp"
 	"github.com/Gitlawb/zero/internal/modelregistry"
@@ -543,6 +544,7 @@ func runExec(args []string, stdout io.Writer, stderr io.Writer, deps appDeps) in
 		EnabledTools:            options.enabledTools,
 		DisabledTools:           options.disabledTools,
 		OnText:                  writer.text,
+		OnReasoning:             writer.reasoning,
 		OnToolCall: func(call agent.ToolCall) {
 			writer.toolCall(call, registry)
 			sessionRecorder.append(sessions.EventToolCall, map[string]any{
@@ -718,7 +720,7 @@ func newExecSelfCorrector(enabled bool, workspaceRoot string, autonomy string) (
 		defer cancel()
 		_ = manager.Shutdown(ctx)
 	}
-	fileDiagnostics := agent.NewFileDiagnostics(manager)
+	fileDiagnostics := agent.NewFileDiagnostics(manager, workspaceRoot)
 	if !enabled {
 		return nil, fileDiagnostics, cleanup
 	}
@@ -961,6 +963,14 @@ func writeExecProviderError(stdout io.Writer, stderr io.Writer, format execOutpu
 	if _, err := fmt.Fprintf(stderr, "[zero] %s\n", message); err != nil {
 		return exitCrash
 	}
+	// Append a one-line next step for recognized provider failures (auth /
+	// rate-limit / connectivity / …). The classifier gates on a provider-origin
+	// marker, so non-provider codes (sandbox_error, mcp_error) never draw a hint.
+	if hint := errhint.CLIHint(errors.New(message)); hint != "" {
+		if _, err := fmt.Fprintf(stderr, "[zero] %s\n", hint); err != nil {
+			return exitCrash
+		}
+	}
 	return exitProvider
 }
 

internal/cli/exec_protocol_test.go

@@ -529,6 +529,45 @@ func TestRunExecStreamJSONRunStartUsesResolvedAPIModel(t *testing.T) {
 	}
 }
 
+func TestRunExecStreamJSONEmitsReasoningEvents(t *testing.T) {
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+	cwd := t.TempDir()
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+
+	exitCode := runWithDeps([]string{"exec", "--output-format", "stream-json", "think then answer"}, &stdout, &stderr, appDeps{
+		getwd: func() (string, error) {
+			return cwd, nil
+		},
+		resolveConfig: func(_ string, _ config.Overrides) (config.ResolvedConfig, error) {
+			return execResolvedConfig(), nil
+		},
+		newProvider: func(config.ProviderProfile) (zeroruntime.Provider, error) {
+			return reasoningExecProvider{}, nil
+		},
+	})
+
+	if exitCode != exitSuccess {
+		t.Fatalf("expected exit code %d, got %d: %s", exitSuccess, exitCode, stderr.String())
+	}
+	events := decodeJSONLines(t, stdout.String())
+	reasoningIdx, reasoning := findJSONEventIndex(t, events, "reasoning")
+	if reasoning["delta"] != "Thinking. " {
+		t.Fatalf("unexpected reasoning event: %#v", reasoning)
+	}
+	textIdx, text := findJSONEventIndex(t, events, "text")
+	if text["delta"] != "done" {
+		t.Fatalf("unexpected text event: %#v", text)
+	}
+	if reasoningIdx >= textIdx {
+		t.Fatalf("expected reasoning event before text event, got indices %d and %d", reasoningIdx, textIdx)
+	}
+	final := findJSONEvent(t, events, "final")
+	if final["text"] != "done" {
+		t.Fatalf("reasoning must not be folded into final answer: %#v", final)
+	}
+}
+
 func TestExecEventWriterTruncatesStreamJSONToolResults(t *testing.T) {
 	var stdout bytes.Buffer
 	writer := execEventWriter{
@@ -751,6 +790,17 @@ type toolCallingExecProvider struct {
 	answer     string
 }
 
+type reasoningExecProvider struct{}
+
+func (reasoningExecProvider) StreamCompletion(context.Context, zeroruntime.CompletionRequest) (<-chan zeroruntime.StreamEvent, error) {
+	ch := make(chan zeroruntime.StreamEvent, 3)
+	ch <- zeroruntime.StreamEvent{Type: zeroruntime.StreamEventReasoning, Content: "Thinking. "}
+	ch <- zeroruntime.StreamEvent{Type: zeroruntime.StreamEventText, Content: "done"}
+	ch <- zeroruntime.StreamEvent{Type: zeroruntime.StreamEventDone}
+	close(ch)
+	return ch, nil
+}
+
 func (provider toolCallingExecProvider) StreamCompletion(ctx context.Context, request zeroruntime.CompletionRequest) (<-chan zeroruntime.StreamEvent, error) {
 	for _, message := range request.Messages {
 		if message.Role == zeroruntime.MessageRoleTool {
@@ -777,13 +827,19 @@ func (provider toolCallingExecProvider) StreamCompletion(ctx context.Context, re
 
 func findJSONEvent(t *testing.T, events []map[string]any, eventType string) map[string]any {
 	t.Helper()
-	for _, event := range events {
+	_, event := findJSONEventIndex(t, events, eventType)
+	return event
+}
+
+func findJSONEventIndex(t *testing.T, events []map[string]any, eventType string) (int, map[string]any) {
+	t.Helper()
+	for idx, event := range events {
 		if event["type"] == eventType {
-			return event
+			return idx, event
 		}
 	}
 	t.Fatalf("event %q not found in %#v", eventType, events)
-	return nil
+	return -1, nil
 }
 
 func findSessionEvent(t *testing.T, events []sessions.Event, eventType sessions.EventType) sessions.Event {

internal/cli/exec_provider_hint_test.go

@@ -0,0 +1,50 @@
+package cli
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+// A recognized provider error in text mode prints the raw message plus a one-line
+// actionable hint; a non-provider error (or JSON mode) prints no hint.
+func TestWriteExecProviderErrorAppendsHint(t *testing.T) {
+	t.Run("provider auth error gets a hint", func(t *testing.T) {
+		var stdout, stderr bytes.Buffer
+		code := writeExecProviderError(&stdout, &stderr, execOutputText, "provider_error",
+			"auth error: your API key is missing or invalid")
+		if code != exitProvider {
+			t.Fatalf("exit code = %d, want exitProvider", code)
+		}
+		out := stderr.String()
+		if !strings.Contains(out, "auth error:") {
+			t.Fatalf("expected raw message, got %q", out)
+		}
+		if !strings.Contains(out, "zero auth") {
+			t.Fatalf("expected an actionable hint referencing `zero auth`, got %q", out)
+		}
+	})
+
+	t.Run("non-provider error gets no hint", func(t *testing.T) {
+		var stdout, stderr bytes.Buffer
+		writeExecProviderError(&stdout, &stderr, execOutputText, "sandbox_error",
+			"sandbox setup failed: permission denied")
+		out := stderr.String()
+		// Exactly one "[zero]" line — no spurious hint attached to a local error.
+		if n := strings.Count(out, "[zero]"); n != 1 {
+			t.Fatalf("expected exactly one [zero] line for a non-provider error, got %d:\n%s", n, out)
+		}
+	})
+
+	t.Run("json mode never appends a hint line", func(t *testing.T) {
+		var stdout, stderr bytes.Buffer
+		writeExecProviderError(&stdout, &stderr, execOutputJSON, "provider_error",
+			"auth error: bad key")
+		if stderr.Len() != 0 {
+			t.Fatalf("json mode must not write to stderr, got %q", stderr.String())
+		}
+		if strings.Contains(stdout.String(), "zero auth") {
+			t.Fatalf("json mode must not inject a hint into the structured payload, got %q", stdout.String())
+		}
+	})
+}

internal/cli/exec_writer.go

@@ -80,6 +80,16 @@ func (writer *execEventWriter) text(delta string) {
 	writer.writeStdout(delta)
 }
 
+func (writer *execEventWriter) reasoning(delta string) {
+	if writer.format == execOutputJSON {
+		writer.writeJSON(map[string]any{"type": "reasoning", "delta": delta})
+		return
+	}
+	if writer.format == execOutputStreamJSON {
+		writer.writeStreamJSON(streamjson.Event{Type: streamjson.EventReasoning, RunID: writer.runID, Delta: delta})
+	}
+}
+
 func (writer *execEventWriter) toolCall(call agent.ToolCall, registry *tools.Registry) {
 	if writer.format == execOutputJSON {
 		writer.writeJSON(map[string]any{

internal/cli/repoinfo.go

@@ -88,6 +88,15 @@ func formatRepoInfo(info repoinfo.Info) string {
 	fmt.Fprintf(&b, "Files:        %d\n", info.FileCount)
 	fmt.Fprintf(&b, "Directories:  %d (max depth %d)\n", info.DirectoryCount, info.MaxDepth)
 	fmt.Fprintf(&b, "Est. LOC:     %d\n", info.LOCEstimate)
+	if info.CommitCount != nil {
+		fmt.Fprintf(&b, "Commits:      %d\n", *info.CommitCount)
+	}
+	if info.BranchCount != nil {
+		fmt.Fprintf(&b, "Branches:     %d\n", *info.BranchCount)
+	}
+	if info.TagCount != nil {
+		fmt.Fprintf(&b, "Tags:         %d\n", *info.TagCount)
+	}
 	if info.PrimaryLanguage != "" {
 		fmt.Fprintf(&b, "Primary lang: %s\n", info.PrimaryLanguage)
 	}

internal/cli/repoinfo_test.go

@@ -33,7 +33,7 @@ func TestFormatRepoInfoText(t *testing.T) {
 	contrib := 3
 	info := repoInfoTestData(age, contrib)
 	out := formatRepoInfo(info)
-	for _, want := range []string{"Files", "TypeScript", "main", "GitHub Actions", "42", "3"} {
+	for _, want := range []string{"Files", "TypeScript", "main", "GitHub Actions", "42", "3", "Commits:      100", "Branches:     5", "Tags:         10"} {
 		if !strings.Contains(out, want) {
 			t.Fatalf("text output missing %q:\n%s", want, out)
 		}
@@ -113,12 +113,16 @@ func initTempGitRepo(t *testing.T) string {
 }
 
 func repoInfoTestData(age, contrib int) repoinfo.Info {
+	commits := 100
+	branches := 5
+	tags := 10
 	return repoinfo.Info{
 		FileCount: 10, DirectoryCount: 3, MaxDepth: 2, LOCEstimate: 500,
 		Languages:       []repoinfo.LangStat{{Name: "TypeScript", LOCEstimate: 400, FileCount: 4}},
 		PrimaryLanguage: "TypeScript", LanguageCount: 1,
 		WorkspaceType: "none", CICD: []string{"GitHub Actions"},
 		HasGit: true, Branch: "main", AgeDays: &age, Contributors90d: &contrib,
+		CommitCount: &commits, BranchCount: &branches, TagCount: &tags,
 	}
 }
 

internal/cli/workflows.go

@@ -41,6 +41,13 @@ type changesCommandOptions struct {
 	hasMessage   bool
 	dryRun       bool
 	maxDiffBytes int
+	remote       string
+	force        bool
+	title        string
+	body         string
+	fill         bool
+	draft        bool
+	yes          bool
 	auto         bool
 }
 
@@ -266,6 +273,10 @@ func runChanges(args []string, stdout io.Writer, stderr io.Writer, deps appDeps)
 			return exitCrash
 		}
 		return exitSuccess
+	case "push":
+		return runChangesPush(args, stdout, stderr, deps)
+	case "pr", "pull-request":
+		return runChangesPR(args, stdout, stderr, deps)
 	default:
 		return writeExecUsageError(stderr, fmt.Sprintf("unknown changes command %q", command))
 	}
@@ -465,6 +476,41 @@ func parseChangesArgs(args []string, command string) (changesCommandOptions, boo
 				return options, false, err
 			}
 			options.maxDiffBytes = maxDiffBytes
+		case arg == "--remote":
+			value, next, err := nextFlagValue(args, index, arg)
+			if err != nil {
+				return options, false, err
+			}
+			options.remote = strings.TrimSpace(value)
+			index = next
+		case strings.HasPrefix(arg, "--remote="):
+			options.remote = strings.TrimSpace(strings.TrimPrefix(arg, "--remote="))
+		case arg == "--force":
+			options.force = true
+		case arg == "--title":
+			value, next, err := nextFlagValue(args, index, arg)
+			if err != nil {
+				return options, false, err
+			}
+			options.title = value
+			index = next
+		case strings.HasPrefix(arg, "--title="):
+			options.title = strings.TrimPrefix(arg, "--title=")
+		case arg == "--body":
+			value, next, err := nextFlagValue(args, index, arg)
+			if err != nil {
+				return options, false, err
+			}
+			options.body = value
+			index = next
+		case strings.HasPrefix(arg, "--body="):
+			options.body = strings.TrimPrefix(arg, "--body=")
+		case arg == "--fill":
+			options.fill = true
+		case arg == "--draft":
+			options.draft = true
+		case arg == "--yes":
+			options.yes = true
 		case arg == "-a" || arg == "--auto":
 			options.auto = true
 		case strings.HasPrefix(arg, "-"):
@@ -473,15 +519,30 @@ func parseChangesArgs(args []string, command string) (changesCommandOptions, boo
 			return options, false, execUsageError{fmt.Sprintf("unexpected changes argument %q", arg)}
 		}
 	}
+	if command != "commit" && options.message != "" {
+		return options, false, execUsageError{"--message is only valid with `zero changes commit`"}
+	}
 	if command != "commit" && (options.hasMessage || options.dryRun || options.auto) {
 		return options, false, execUsageError{"--message, --dry-run, and --auto are only valid with `zero changes commit`"}
 	}
 	if command == "commit" && options.hasMessage && options.auto {
 		return options, false, execUsageError{"cannot specify both --message and --auto"}
 	}
-	if command == "commit" && options.baseRef != "" {
+	if command != "commit" && command != "push" && options.dryRun {
+		return options, false, execUsageError{"--dry-run is only valid with commit or push"}
+	}
+	if command != "inspect" && options.baseRef != "" {
 		return options, false, execUsageError{"--base is only valid with `zero changes inspect`"}
 	}
+	if command != "push" && command != "pr" && (options.remote != "" || options.force) {
+		return options, false, execUsageError{"--remote and --force are only valid with push or pr"}
+	}
+	if command != "pr" && (options.title != "" || options.body != "" || options.fill || options.draft) {
+		return options, false, execUsageError{"--title, --body, --fill, and --draft are only valid with `zero changes pr`"}
+	}
+	if command != "push" && command != "pr" && options.yes {
+		return options, false, execUsageError{"--yes is only valid with push or pr"}
+	}
 	return options, false, nil
 }
 
@@ -759,14 +820,24 @@ func writeChangesHelp(w io.Writer) error {
 	_, err := fmt.Fprint(w, `Usage:
   zero changes inspect [flags]
   zero changes commit [flags]
+  zero changes push [flags]
+  zero changes pr [flags]
 
-Inspects local git changes and optionally creates a commit.
+Inspects, commits, pushes, and creates pull requests for local git changes.
 
 Flags:
   -C, --cwd <path>        Workspace directory
       --base <ref>        Diff against <ref>...HEAD instead of the working tree
       --diff-bytes <n>    Maximum diff bytes to include
   -m, --message <text>    Commit message for `+"`zero changes commit`"+`
+      --dry-run           Preview commit metadata / push without mutating git state
+      --remote <name>     Remote to push to (defaults to upstream tracked branch or origin)
+      --force             Use force-with-lease when pushing
+      --title <text>      PR title
+      --body <text>       PR body
+      --fill              Automatically populate PR title and body from commits
+      --draft             Create PR as a draft
+      --yes               Confirm pushing to a default/protected branch
   -a, --auto              Auto-generate commit message using LLM (use --dry-run to preview)
       --dry-run           Preview commit metadata without mutating git state
       --json              Print JSON output
@@ -775,6 +846,128 @@ Flags:
 	return err
 }
 
+func runChangesPush(args []string, stdout io.Writer, stderr io.Writer, deps appDeps) int {
+	options, help, err := parseChangesArgs(args, "push")
+	if err != nil {
+		return writeExecUsageError(stderr, err.Error())
+	}
+	if help {
+		if err := writeChangesHelp(stdout); err != nil {
+			return exitCrash
+		}
+		return exitSuccess
+	}
+	workspaceRoot, err := resolveWorkspaceRoot(options.cwd, deps)
+	if err != nil {
+		return writeExecUsageError(stderr, err.Error())
+	}
+
+	result, err := deps.pushChanges(context.Background(), zerogit.PushOptions{
+		Cwd:                    workspaceRoot,
+		Remote:                 options.remote,
+		Force:                  options.force,
+		DryRun:                 options.dryRun,
+		AllowPushDefaultBranch: options.yes,
+	})
+	if err != nil {
+		return writeExecUsageError(stderr, err.Error())
+	}
+
+	if options.json {
+		if err := writePrettyJSON(stdout, result); err != nil {
+			return exitCrash
+		}
+		return exitSuccess
+	}
+
+	dryRunStr := ""
+	if options.dryRun {
+		dryRunStr = " (dry run)"
+	}
+	if _, err := fmt.Fprintf(stdout, "Pushed branch %s to remote %s%s\n", result.Branch, result.Remote, dryRunStr); err != nil {
+		return exitCrash
+	}
+	if result.Output != "" {
+		if _, err := fmt.Fprintln(stdout, result.Output); err != nil {
+			return exitCrash
+		}
+	}
+	return exitSuccess
+}
+
+func runChangesPR(args []string, stdout io.Writer, stderr io.Writer, deps appDeps) int {
+	options, help, err := parseChangesArgs(args, "pr")
+	if err != nil {
+		return writeExecUsageError(stderr, err.Error())
+	}
+	if help {
+		if err := writeChangesHelp(stdout); err != nil {
+			return exitCrash
+		}
+		return exitSuccess
+	}
+	if !options.fill && options.title == "" {
+		return writeExecUsageError(stderr, "must provide either --fill or --title to run non-interactively")
+	}
+	workspaceRoot, err := resolveWorkspaceRoot(options.cwd, deps)
+	if err != nil {
+		return writeExecUsageError(stderr, err.Error())
+	}
+
+	if !options.json {
+		if _, err := fmt.Fprintln(stdout, "Pushing current branch to set upstream..."); err != nil {
+			return exitCrash
+		}
+	}
+	pushResult, err := deps.pushChanges(context.Background(), zerogit.PushOptions{
+		Cwd:                    workspaceRoot,
+		Remote:                 options.remote,
+		Force:                  options.force,
+		AllowPushDefaultBranch: options.yes,
+	})
+	if err != nil {
+		return writeExecUsageError(stderr, fmt.Sprintf("auto-push failed: %v", err))
+	}
+	if !options.json {
+		if _, err := fmt.Fprintf(stdout, "Pushed branch %s to remote %s\n", pushResult.Branch, pushResult.Remote); err != nil {
+			return exitCrash
+		}
+	}
+
+	prResult, err := deps.createPR(context.Background(), zerogit.PROptions{
+		Cwd:   workspaceRoot,
+		Fill:  options.fill,
+		Draft: options.draft,
+		Title: options.title,
+		Body:  options.body,
+	})
+	if err != nil {
+		return writeExecUsageError(stderr, err.Error())
+	}
+
+	if options.json {
+		type prJSONResult struct {
+			Branch string `json:"branch"`
+			Remote string `json:"remote"`
+			Output string `json:"output"`
+		}
+		res := prJSONResult{
+			Branch: pushResult.Branch,
+			Remote: pushResult.Remote,
+			Output: strings.TrimSpace(prResult.Output),
+		}
+		if err := writePrettyJSON(stdout, res); err != nil {
+			return exitCrash
+		}
+		return exitSuccess
+	}
+
+	if _, err := fmt.Fprintln(stdout, strings.TrimSpace(prResult.Output)); err != nil {
+		return exitCrash
+	}
+	return exitSuccess
+}
+
 func generateAutoCommitMessage(ctx context.Context, provider zeroruntime.Provider, model string, summary zerogit.ChangeSummary) (string, error) {
 	var promptBuilder strings.Builder
 	promptBuilder.WriteString("Analyze the following git diff and generate a concise, conventional commit message.\n")

internal/errhint/errhint.go

@@ -0,0 +1,167 @@
+// Package errhint classifies provider/model failures into a few user-actionable
+// categories and turns them into a one-line "next step" hint.
+//
+// Provider errors already arrive with a classified string prefix from
+// providerio.ClassifiedError ("auth error:", "rate limit error:", …); lower-level
+// failures (DNS, TLS, timeouts, context-length) arrive as raw driver or library
+// messages. Classify matches both so the interactive error row (TUI) and the
+// `zero exec` provider-error path (CLI) can append one concrete next step instead
+// of dumping an identical red blob for every failure mode.
+package errhint
+
+import "strings"
+
+// Category buckets a provider/model failure into a small set of classes that each
+// map to a distinct recovery action.
+type Category int
+
+const (
+	// Unknown means the error didn't match any known signature; callers should
+	// emit no hint rather than guess.
+	Unknown Category = iota
+	Auth
+	RateLimit
+	Connectivity
+	ModelNotFound
+	ContextOverflow
+)
+
+// providerMarkers are the prefixes the provider layer attaches to every
+// provider-originated failure: providerio.ClassifiedError emits "auth error:",
+// "rate limit error:", "provider error:", and "provider request error:", and the
+// streaming paths wrap transport/decoding failures as "provider stream error:".
+// A UI surface's error can also be a *local* failure (a tool's "permission
+// denied", a "file does not exist", a config error), so Classify only proceeds
+// past this gate for messages that are recognizably from the provider — otherwise
+// a broad substring like "does not exist" would attach a bogus /model hint to an
+// unrelated local error.
+var providerMarkers = []string{
+	"auth error:",
+	"rate limit error:",
+	"provider error:",
+	"provider request error:",
+	"provider stream error:",
+}
+
+// Classify buckets err by scanning its message for known signatures. It is a
+// deliberately conservative string heuristic — the provider layer has already
+// discarded the numeric HTTP status by the time the error reaches a UI surface,
+// so the message is all we have. It first gates on a provider-origin marker (see
+// providerMarkers) so local failures never draw a provider hint, then sub-classifies.
+// Order matters: more specific signatures are tested before broader ones (e.g.
+// "context length" as overflow before the generic "timeout" as connectivity).
+func Classify(err error) Category {
+	if err == nil {
+		return Unknown
+	}
+	m := strings.ToLower(err.Error())
+	if !containsAny(m, providerMarkers...) {
+		return Unknown
+	}
+	switch {
+	case containsAny(m, "auth error:", "unauthorized", "api key", "api_key", "invalid_api_key",
+		"authentication", "permission denied", "forbidden") || containsStatusCode(m, "401", "403"):
+		return Auth
+	case containsAny(m, "rate limit", "rate_limit", "too many requests", "quota",
+		"resource_exhausted", "overloaded") || containsStatusCode(m, "429", "529"):
+		return RateLimit
+	case containsAny(m, "context length", "context window", "maximum context", "context_length_exceeded",
+		"too many tokens", "prompt is too long", "reduce the length", "maximum context length"):
+		return ContextOverflow
+	case containsAny(m, "model not found", "model_not_found", "does not exist", "unknown model",
+		"no such model", "unsupported model", "invalid model", "model is not"):
+		return ModelNotFound
+	case containsAny(m, "dial tcp", "no such host", "connection refused", "network is unreachable",
+		"i/o timeout", "context deadline exceeded", "tls handshake", "connection reset",
+		"unexpected eof", "lookup ", "timeout"):
+		return Connectivity
+	default:
+		return Unknown
+	}
+}
+
+// TUIHint returns a one-line hint referencing interactive slash commands, or ""
+// when the category is Unknown. Meant to sit under the raw error in the live
+// error row.
+func TUIHint(err error) string {
+	switch Classify(err) {
+	case Auth:
+		return "API key rejected — run /provider to re-check your credentials"
+	case RateLimit:
+		return "Rate limited — wait a moment, or switch model with /model"
+	case Connectivity:
+		return "Can't reach the provider — run /doctor --connectivity"
+	case ModelNotFound:
+		return "Model unavailable — pick another with /model"
+	case ContextOverflow:
+		return "Context window full — run /compact to free space"
+	default:
+		return ""
+	}
+}
+
+// CLIHint returns a one-line hint referencing `zero …` subcommands, or "" when the
+// category is Unknown. Meant for the non-interactive `zero exec` error path, where
+// slash commands don't apply.
+func CLIHint(err error) string {
+	switch Classify(err) {
+	case Auth:
+		return "API key rejected — run `zero auth` or set the provider's API key, then retry"
+	case RateLimit:
+		return "Rate limited — wait a moment, or switch model with --model"
+	case Connectivity:
+		return "Can't reach the provider — run `zero doctor`"
+	case ModelNotFound:
+		return "Model unavailable — run `zero doctor` or pick another with --model"
+	case ContextOverflow:
+		return "Context window full — shorten the prompt or start a fresh session"
+	default:
+		return ""
+	}
+}
+
+func containsAny(haystack string, needles ...string) bool {
+	for _, n := range needles {
+		if strings.Contains(haystack, n) {
+			return true
+		}
+	}
+	return false
+}
+
+// containsStatusCode reports whether haystack contains any of the given HTTP
+// status codes as a standalone number — not embedded in a longer digit run like
+// "completed in 4290ms" or "request id 14015" — so an incidental number can't be
+// mis-bucketed as an auth/rate-limit failure.
+func containsStatusCode(haystack string, codes ...string) bool {
+	return HasStatusCode(haystack, codes...)
+}
+
+// HasStatusCode reports whether haystack contains any of the given HTTP status
+// codes as a standalone number — not embedded in a longer digit run like
+// "completed in 4290ms" or "request id 14015". Exported so other packages (e.g.
+// the reconnect classifier) can gate on a status code without re-implementing
+// the digit-boundary check.
+func HasStatusCode(haystack string, codes ...string) bool {
+	for _, code := range codes {
+		for from := 0; ; {
+			rel := strings.Index(haystack[from:], code)
+			if rel < 0 {
+				break
+			}
+			pos := from + rel
+			beforeOK := pos == 0 || !isASCIIDigit(haystack[pos-1])
+			end := pos + len(code)
+			afterOK := end >= len(haystack) || !isASCIIDigit(haystack[end])
+			if beforeOK && afterOK {
+				return true
+			}
+			from = pos + 1
+		}
+	}
+	return false
+}
+
+func isASCIIDigit(b byte) bool {
+	return b >= '0' && b <= '9'
+}

internal/errhint/errhint_test.go

@@ -0,0 +1,94 @@
+package errhint
+
+import (
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestClassify(t *testing.T) {
+	cases := []struct {
+		name string
+		msg  string
+		want Category
+	}{
+		{"nil-ish empty", "", Unknown},
+		{"providerio auth prefix", "auth error: your API key is missing or invalid — run `zero auth`", Auth},
+		{"raw 401", "provider request error: 401 Unauthorized", Auth},
+		{"invalid api key", "provider request error: invalid_api_key: incorrect key provided", Auth},
+		{"rate limit prefix", "rate limit error: 429 too many requests", RateLimit},
+		{"overloaded", "provider error: model is overloaded, please retry", RateLimit},
+		{"resource exhausted gemini", "provider stream error: rpc error: code = ResourceExhausted desc = quota exceeded", RateLimit},
+		{"context length openai", "provider request error: this model's maximum context length is 128000 tokens", ContextOverflow},
+		{"context_length_exceeded", "provider request error: context_length_exceeded", ContextOverflow},
+		{"model not found", "provider request error: 404 the model `gpt-9` does not exist", ModelNotFound},
+		{"unknown model", "provider request error: unknown model: sonnet-99", ModelNotFound},
+		{"dns failure", "provider stream error: Post \"https://api...\": dial tcp: lookup api.foo.com: no such host", Connectivity},
+		{"connection refused", "provider stream error: dial tcp 127.0.0.1:443: connection refused", Connectivity},
+		{"deadline", "provider stream error: context deadline exceeded (Client.Timeout exceeded)", Connectivity},
+		{"provider-marked but no sub-signature", "provider error: something totally unexpected happened", Unknown},
+
+		// An incidental number that merely contains a status-code digit run must NOT
+		// be mis-bucketed (digit-boundary check), even behind a provider marker.
+		{"incidental latency number", "provider error: request completed in 4290ms then failed", Unknown},
+		{"incidental request id", "provider error: request id 14015 failed unexpectedly", Unknown},
+		{"standalone 401 still auth", "provider request error: got 401 from upstream", Auth},
+		{"standalone 429 still rate limit", "provider error: 429 returned", RateLimit},
+
+		// Local (non-provider) failures must NOT be classified — no provider marker,
+		// so no bogus recovery hint attaches to them.
+		{"local fs permission denied", "open /etc/shadow: permission denied", Unknown},
+		{"local file missing", "stat foo.go: no such file or directory", Unknown},
+		{"local model config typo", "unknown model: sonnet-99", Unknown},
+		{"tool timeout local", "tool bash timed out after 600s", Unknown},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := Classify(errors.New(tc.msg)); got != tc.want {
+				t.Fatalf("Classify(%q) = %v, want %v", tc.msg, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestClassifyNil(t *testing.T) {
+	if got := Classify(nil); got != Unknown {
+		t.Fatalf("Classify(nil) = %v, want Unknown", got)
+	}
+}
+
+// Context-overflow must win over the connectivity "timeout" catch-all: a message
+// mentioning both "context length" and a timeout is an overflow, not a network
+// problem.
+func TestContextOverflowBeatsConnectivity(t *testing.T) {
+	err := errors.New("provider request error: maximum context length exceeded; request timeout")
+	if got := Classify(err); got != ContextOverflow {
+		t.Fatalf("Classify = %v, want ContextOverflow", got)
+	}
+}
+
+func TestHintsPresentForKnownCategories(t *testing.T) {
+	known := []error{
+		errors.New("auth error: bad key"),
+		errors.New("rate limit error: 429"),
+		errors.New("provider stream error: dial tcp: no such host"),
+		errors.New("provider request error: model does not exist"),
+		errors.New("provider request error: maximum context length is 128000 tokens"),
+	}
+	for _, err := range known {
+		if h := TUIHint(err); strings.TrimSpace(h) == "" {
+			t.Fatalf("TUIHint(%q) empty, want a hint", err)
+		}
+		if h := CLIHint(err); strings.TrimSpace(h) == "" {
+			t.Fatalf("CLIHint(%q) empty, want a hint", err)
+		}
+	}
+	// Unknown yields no hint on either surface.
+	unknown := errors.New("provider error: mystery")
+	if h := TUIHint(unknown); h != "" {
+		t.Fatalf("TUIHint(unknown) = %q, want empty", h)
+	}
+	if h := CLIHint(unknown); h != "" {
+		t.Fatalf("CLIHint(unknown) = %q, want empty", h)
+	}
+}

internal/providers/factory.go

@@ -24,7 +24,7 @@ type Options struct {
 	ModelRegistry *modelregistry.Registry
 	// OAuthResolver, when set, lets the provider authenticate model calls with an
 	// OAuth bearer token (preferred over the API key). nil => API-key auth only.
-	// Applied to the OpenAI and Anthropic providers.
+	// Applied to the OpenAI, Anthropic, and Google (Gemini) providers.
 	OAuthResolver providerio.TokenResolver
 	// OAuthLoginKey is the credential-store key OAuthResolver bound to (empty when
 	// there is no OAuth login). It is the SAME selection the bearer resolver made,
@@ -91,6 +91,7 @@ func New(profile config.ProviderProfile, options Options) (zeroruntime.Provider,
 			AuthScheme:      profile.AuthScheme,
 			AuthHeaderValue: profile.AuthHeaderValue,
 			CustomHeaders:   profile.CustomHeaders,
+			OAuthResolver:   options.OAuthResolver,
 			MaxTokens:       resolved.maxOutputTokens,
 			HTTPClient:      options.HTTPClient,
 			UserAgent:       options.UserAgent,

internal/providers/gemini/provider.go

@@ -49,6 +49,10 @@ type Options struct {
 	CustomHeaders   map[string]string
 	HTTPClient      *http.Client
 	UserAgent       string
+	// OAuthResolver, when set, supplies an OAuth bearer credential per request and
+	// is retried once with a forced token refresh after an upstream 401 (matching
+	// the OpenAI and Anthropic providers). Nil falls back to plain API-key auth.
+	OAuthResolver providerio.TokenResolver
 	// StreamIdleTimeout aborts the stream if no data arrives for this long.
 	// When unset, Zero uses providerio.ResolveStreamIdleTimeout — the
 	// ZERO_STREAM_IDLE_TIMEOUT override or providerio.DefaultStreamIdleTimeout.
@@ -67,6 +71,7 @@ type Provider struct {
 	customHeaders     map[string]string
 	httpClient        *http.Client
 	userAgent         string
+	oauthResolver     providerio.TokenResolver
 	streamIdleTimeout time.Duration
 }
 
@@ -95,6 +100,7 @@ func New(options Options) (*Provider, error) {
 		customHeaders:     providerio.CopyHeaders(options.CustomHeaders),
 		httpClient:        providerio.HTTPClient(options.HTTPClient),
 		userAgent:         options.UserAgent,
+		oauthResolver:     options.OAuthResolver,
 		streamIdleTimeout: providerio.ResolveStreamIdleTimeout(options.StreamIdleTimeout),
 	}, nil
 }
@@ -127,20 +133,22 @@ func (provider *Provider) stream(ctx context.Context, body []byte, events chan<-
 	streamCtx, cancelStream := context.WithCancel(ctx)
 	defer cancelStream()
 
-	response, err := providerio.SendWithRetry(streamCtx, provider.httpClient, http.MethodPost, provider.streamURL(), body, func(request *http.Request) {
-		request.Header.Set("Content-Type", "application/json")
-		if provider.userAgent != "" {
-			request.Header.Set("User-Agent", provider.userAgent)
-		}
-		providerio.ApplyAuthHeaders(request, providerio.AuthHeaders{
+	response, err := providerio.SendWithAuthRetry(streamCtx, provider.httpClient, http.MethodPost, provider.streamURL(), body,
+		providerio.AuthHeaders{
 			APIKey:            provider.apiKey,
 			DefaultAuthHeader: "x-goog-api-key",
 			AuthHeader:        provider.authHeader,
 			AuthScheme:        provider.authScheme,
 			AuthHeaderValue:   provider.authHeaderValue,
 			CustomHeaders:     provider.customHeaders,
-		})
-	}, 0)
+		},
+		provider.oauthResolver,
+		func(request *http.Request) {
+			request.Header.Set("Content-Type", "application/json")
+			if provider.userAgent != "" {
+				request.Header.Set("User-Agent", provider.userAgent)
+			}
+		}, 0)
 	if err != nil {
 		providerio.SendEvent(ctx, events, zeroruntime.StreamEvent{Type: zeroruntime.StreamEventError, Error: provider.redact("provider stream error: " + err.Error())})
 		return

internal/providers/gemini/provider_test.go

@@ -370,6 +370,57 @@ func TestStreamCompletionClassifiesHTTPAndPromptBlockErrors(t *testing.T) {
 	}
 }
 
+// A 401 with an OAuth resolver is retried once with a force-refreshed token; the
+// replayed request carries the refreshed bearer and succeeds.
+func TestStreamCompletionRetries401WithRefreshedToken(t *testing.T) {
+	var attempts int
+	var secondAuth string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		if attempts == 1 {
+			http.Error(w, `{"error":{"message":"token expired"}}`, http.StatusUnauthorized)
+			return
+		}
+		secondAuth = r.Header.Get("Authorization")
+		writeSSE(w, `{}`)
+	}))
+	defer server.Close()
+
+	var forceRefreshOnRetry bool
+	resolver := func(ctx context.Context, forceRefresh bool) (string, string, bool, error) {
+		if forceRefresh {
+			forceRefreshOnRetry = true
+			return "Authorization", "Bearer refreshed", true, nil
+		}
+		return "Authorization", "Bearer stale", true, nil
+	}
+
+	provider, err := New(Options{
+		APIKey:        "sk-google",
+		BaseURL:       server.URL,
+		Model:         "gemini-test",
+		OAuthResolver: resolver,
+	})
+	if err != nil {
+		t.Fatalf("New returned error: %v", err)
+	}
+	stream, err := provider.StreamCompletion(context.Background(), validRequest())
+	if err != nil {
+		t.Fatalf("StreamCompletion returned error: %v", err)
+	}
+	drain(stream)
+
+	if attempts != 2 {
+		t.Fatalf("attempts = %d, want 2 (initial 401 + one refreshed retry)", attempts)
+	}
+	if !forceRefreshOnRetry {
+		t.Fatalf("resolver was not called with forceRefresh on the retry")
+	}
+	if secondAuth != "Bearer refreshed" {
+		t.Fatalf("retry Authorization = %q, want refreshed bearer", secondAuth)
+	}
+}
+
 func TestStreamCompletionEmitsStreamErrorObject(t *testing.T) {
 	provider := newTestProviderWithKey(t, "sk-google", func(w http.ResponseWriter, r *http.Request) {
 		writeSSE(w, `{"error":{"code":429,"message":"stream failed sk-google","status":"RESOURCE_EXHAUSTED"}}`)

internal/providers/openai/provider.go

@@ -9,6 +9,7 @@ import (
 	"io"
 	"net/http"
 	"net/url"
+	"os"
 	"strings"
 	"time"
 
@@ -283,10 +284,10 @@ func (provider *Provider) emitChunk(
 	events chan<- zeroruntime.StreamEvent,
 ) {
 	for _, choice := range chunk.Choices {
-		if choice.Delta.ReasoningContent != "" {
+		if reasoning := choice.Delta.reasoningText(); reasoning != "" {
 			sendEvent(ctx, events, zeroruntime.StreamEvent{
 				Type:    zeroruntime.StreamEventReasoning,
-				Content: choice.Delta.ReasoningContent,
+				Content: reasoning,
 			})
 		}
 		if choice.Delta.Content != "" {
@@ -317,6 +318,13 @@ func (provider *Provider) emitChunk(
 	}
 }
 
+func (delta streamDelta) reasoningText() string {
+	if delta.ReasoningContent != "" {
+		return delta.ReasoningContent
+	}
+	return delta.Reasoning
+}
+
 // mapFinishReason maps OpenAI's finish_reason onto the runtime's normalized
 // terminal reasons. A normal finish ("stop"/"tool_calls"/"") returns "".
 func mapFinishReason(reason string) string {
@@ -414,6 +422,12 @@ func (provider *Provider) openAIRequest(request zeroruntime.CompletionRequest) c
 	if effort := openAIReasoningEffort(request.ReasoningEffort); effort != "" {
 		mapped.ReasoningEffort = effort
 	}
+	// prompt_cache_key is a documented OpenAI parameter; compatible servers
+	// ignore unknown fields, but a strict endpoint that rejects it can be
+	// accommodated with ZERO_DISABLE_PROMPT_CACHE_KEY=1.
+	if key := strings.TrimSpace(request.PromptCacheKey); key != "" && !promptCacheKeyDisabled() {
+		mapped.PromptCacheKey = key
+	}
 	if len(request.Tools) > 0 {
 		mapped.Tools = make([]toolDefinition, 0, len(request.Tools))
 		for _, tool := range request.Tools {
@@ -430,6 +444,15 @@ func (provider *Provider) openAIRequest(request zeroruntime.CompletionRequest) c
 	return mapped
 }
 
+// promptCacheKeyDisabled reports whether the ZERO_DISABLE_PROMPT_CACHE_KEY
+// kill switch is set to a truthy value. "0" and "false" (any case) are
+// no-ops, matching how ZERO_FORMAT_ON_WRITE parses boolean flags, so an
+// explicitly-disabled toggle never flips the behavior it names.
+func promptCacheKeyDisabled() bool {
+	value := strings.TrimSpace(os.Getenv("ZERO_DISABLE_PROMPT_CACHE_KEY"))
+	return value != "" && value != "0" && !strings.EqualFold(value, "false")
+}
+
 // openAIReasoningEffort normalizes a requested effort to a value the OpenAI chat
 // completions API accepts, or "" to omit the field. "none" (and anything else)
 // is dropped rather than risking a 400 on an unrecognized enum.

internal/providers/openai/provider_test.go

@@ -227,6 +227,39 @@ func TestStreamCompletionEmitsReasoningContentDeltas(t *testing.T) {
 	}
 }
 
+func TestStreamCompletionEmitsReasoningAliasDeltas(t *testing.T) {
+	provider := newTestProvider(t, func(w http.ResponseWriter, r *http.Request) {
+		writeSSE(w, `{"choices":[{"delta":{"reasoning":"Thinking. "}}]}`)
+		writeSSE(w, `{"choices":[{"delta":{"reasoning":"Answering now."}}]}`)
+		writeSSE(w, `[DONE]`)
+	})
+
+	events := collectProviderEvents(t, provider)
+	reasoning := eventsOfType(events, zeroruntime.StreamEventReasoning)
+	if len(reasoning) != 2 {
+		t.Fatalf("reasoning events = %#v, want two reasoning deltas", reasoning)
+	}
+	if reasoning[0].Content != "Thinking. " || reasoning[1].Content != "Answering now." {
+		t.Fatalf("unexpected reasoning events: %#v", reasoning)
+	}
+	if text := eventsOfType(events, zeroruntime.StreamEventText); len(text) != 0 {
+		t.Fatalf("reasoning must not emit text events, got %#v", text)
+	}
+}
+
+func TestStreamCompletionPrefersReasoningContentOverAlias(t *testing.T) {
+	provider := newTestProvider(t, func(w http.ResponseWriter, r *http.Request) {
+		writeSSE(w, `{"choices":[{"delta":{"reasoning_content":"standard","reasoning":"alias"}}]}`)
+		writeSSE(w, `[DONE]`)
+	})
+
+	events := collectProviderEvents(t, provider)
+	reasoning := eventsOfType(events, zeroruntime.StreamEventReasoning)
+	if len(reasoning) != 1 || reasoning[0].Content != "standard" {
+		t.Fatalf("reasoning events = %#v, want standard reasoning_content", reasoning)
+	}
+}
+
 func TestStreamCompletionEmitsReasoningBeforeRegularContent(t *testing.T) {
 	provider := newTestProvider(t, func(w http.ResponseWriter, r *http.Request) {
 		writeSSE(w, `{"choices":[{"delta":{"reasoning_content":"Thinking. ","content":"Answer."}}]}`)
@@ -1226,3 +1259,61 @@ func TestOpenAIRequestEmptyContentHandling(t *testing.T) {
 		t.Fatalf("assistant tool calls dropped: %#v", req.Messages[1])
 	}
 }
+
+// TestOpenAIRequestPromptCacheKey locks in prompt_cache_key forwarding: a
+// session-carrying request serializes the key so the backend can route to a
+// replica holding the cached prefix, a keyless request omits the field
+// entirely (strict servers see byte-identical requests to before), and
+// ZERO_DISABLE_PROMPT_CACHE_KEY suppresses it for endpoints that reject it.
+func TestOpenAIRequestPromptCacheKey(t *testing.T) {
+	provider, err := New(Options{Model: "gpt-test"})
+	if err != nil {
+		t.Fatalf("New returned error: %v", err)
+	}
+	messages := []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "hi"}}
+
+	req := provider.openAIRequest(zeroruntime.CompletionRequest{
+		Messages:       messages,
+		PromptCacheKey: "sess_123",
+	})
+	if req.PromptCacheKey != "sess_123" {
+		t.Fatalf("PromptCacheKey = %q, want sess_123", req.PromptCacheKey)
+	}
+	data, err := json.Marshal(req)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if !strings.Contains(string(data), `"prompt_cache_key":"sess_123"`) {
+		t.Fatalf("prompt_cache_key not serialized: %s", data)
+	}
+
+	req = provider.openAIRequest(zeroruntime.CompletionRequest{Messages: messages})
+	if data, err = json.Marshal(req); err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if strings.Contains(string(data), "prompt_cache_key") {
+		t.Fatalf("keyless request must omit prompt_cache_key: %s", data)
+	}
+
+	t.Setenv("ZERO_DISABLE_PROMPT_CACHE_KEY", "1")
+	req = provider.openAIRequest(zeroruntime.CompletionRequest{
+		Messages:       messages,
+		PromptCacheKey: "sess_123",
+	})
+	if req.PromptCacheKey != "" {
+		t.Fatalf("kill switch ignored; PromptCacheKey = %q", req.PromptCacheKey)
+	}
+
+	// Explicitly-falsy kill switch values must NOT disable forwarding — only
+	// truthy values flip the toggle (same parsing as ZERO_FORMAT_ON_WRITE).
+	for _, value := range []string{"0", "false", "FALSE"} {
+		t.Setenv("ZERO_DISABLE_PROMPT_CACHE_KEY", value)
+		req = provider.openAIRequest(zeroruntime.CompletionRequest{
+			Messages:       messages,
+			PromptCacheKey: "sess_123",
+		})
+		if req.PromptCacheKey != "sess_123" {
+			t.Fatalf("ZERO_DISABLE_PROMPT_CACHE_KEY=%q must be a no-op; PromptCacheKey = %q", value, req.PromptCacheKey)
+		}
+	}
+}

internal/providers/openai/types.go

@@ -8,6 +8,11 @@ type chatCompletionRequest struct {
 	ReasoningEffort     string           `json:"reasoning_effort,omitempty"`
 	Stream              bool             `json:"stream"`
 	StreamOptions       *streamOptions   `json:"stream_options,omitempty"`
+	// PromptCacheKey asks the backend to route the request to a replica that
+	// already holds this conversation's prefix in its prompt cache (the OpenAI
+	// `prompt_cache_key` parameter). Omitted when the caller carries no session
+	// identity or when ZERO_DISABLE_PROMPT_CACHE_KEY is set.
+	PromptCacheKey string `json:"prompt_cache_key,omitempty"`
 }
 
 // streamOptions requests the final usage chunk on a streaming response. Without
@@ -78,6 +83,7 @@ type streamChoice struct {
 type streamDelta struct {
 	Content          string                `json:"content"`
 	ReasoningContent string                `json:"reasoning_content"`
+	Reasoning        string                `json:"reasoning"`
 	ToolCalls        []streamToolCallDelta `json:"tool_calls"`
 }
 

internal/repoinfo/repoinfo.go

@@ -54,6 +54,9 @@ type Info struct {
 	AgeDays               *int       `json:"ageDays,omitempty"`
 	Contributors90d       *int       `json:"contributors90d,omitempty"`
 	CommitVelocity30d     *int       `json:"commitVelocity30d,omitempty"`
+	BranchCount           *int       `json:"branchCount,omitempty"`
+	CommitCount           *int       `json:"commitCount,omitempty"`
+	TagCount              *int       `json:"tagCount,omitempty"`
 }
 
 // RunGit runs a git subcommand in dir and returns raw stdout. A non-zero exit
@@ -229,6 +232,43 @@ func Collect(ctx context.Context, opts Options) (Info, error) {
 			info.CommitVelocity30d = &n
 		}
 	}
+	if count, err := run(ctx, dir, "rev-list", "--count", "HEAD"); err == nil {
+		if n, perr := strconv.Atoi(strings.TrimSpace(count)); perr == nil {
+			info.CommitCount = &n
+		}
+	}
+	if branches, err := run(ctx, dir, "branch", "-a"); err == nil {
+		set := map[string]bool{}
+		for _, line := range strings.Split(branches, "\n") {
+			line = strings.TrimSpace(line)
+			if line == "" || strings.Contains(line, "->") {
+				continue
+			}
+			// Strip leading '* ' (current branch) or '+ ' (checked out in another worktree).
+			line = strings.TrimPrefix(line, "* ")
+			line = strings.TrimPrefix(line, "+ ")
+			line = strings.TrimSpace(line)
+			if line == "" || strings.HasPrefix(line, "(") {
+				continue
+			}
+			// If it's a remote branch, extract the branch name.
+			// E.g., remotes/origin/main -> main
+			// E.g., remotes/origin/feature/xyz -> feature/xyz
+			if strings.HasPrefix(line, "remotes/") {
+				line = strings.TrimPrefix(line, "remotes/")
+				if slashIdx := strings.Index(line, "/"); slashIdx != -1 {
+					line = line[slashIdx+1:]
+				}
+			}
+			set[line] = true
+		}
+		n := len(set)
+		info.BranchCount = &n
+	}
+	if tags, err := run(ctx, dir, "tag"); err == nil {
+		n := countNonEmptyLines(tags)
+		info.TagCount = &n
+	}
 
 	return info, nil
 }
@@ -328,3 +368,13 @@ func defaultRunGit(ctx context.Context, dir string, args ...string) (string, err
 	}
 	return stdout.String(), nil
 }
+
+func countNonEmptyLines(s string) int {
+	count := 0
+	for _, line := range strings.Split(s, "\n") {
+		if strings.TrimSpace(line) != "" {
+			count++
+		}
+	}
+	return count
+}

internal/repoinfo/repoinfo_test.go

@@ -43,6 +43,8 @@ func TestCollectCoreMetrics(t *testing.T) {
 			"remote":    "https://github.com/x/y.git\n",
 			"log":       "0\n",
 			"rev-list":  "12\n",
+			"branch":    "  main\n  remotes/origin/HEAD -> origin/main\n  remotes/origin/main\n  remotes/origin/feature\n",
+			"tag":       "v0.1.0\nv0.2.0\n",
 		}, nil),
 	})
 	if err != nil {
@@ -85,6 +87,15 @@ func TestCollectCoreMetrics(t *testing.T) {
 	if info.CommitVelocity30d == nil || *info.CommitVelocity30d != 12 {
 		t.Fatalf("CommitVelocity30d=%v want 12", info.CommitVelocity30d)
 	}
+	if info.CommitCount == nil || *info.CommitCount != 12 {
+		t.Fatalf("CommitCount=%v want 12", info.CommitCount)
+	}
+	if info.BranchCount == nil || *info.BranchCount != 2 {
+		t.Fatalf("BranchCount=%v want 2", info.BranchCount)
+	}
+	if info.TagCount == nil || *info.TagCount != 2 {
+		t.Fatalf("TagCount=%v want 2", info.TagCount)
+	}
 }
 
 func TestCollectContributorsUnique(t *testing.T) {
@@ -252,12 +263,13 @@ func TestCollectNotGitRepo(t *testing.T) {
 }
 
 func TestCollectOnlyReadOnlyLocalSubcommands(t *testing.T) {
-	allowed := map[string]bool{"ls-tree": true, "rev-parse": true, "remote": true, "log": true, "rev-list": true}
+	allowed := map[string]bool{"ls-tree": true, "rev-parse": true, "remote": true, "log": true, "rev-list": true, "branch": true, "tag": true}
 	var used []string
 	_, err := Collect(context.Background(), Options{
 		Now: time.Unix(0, 0),
 		RunGit: fakeGit(t, map[string]string{
 			"ls-tree": lsTree, "rev-parse": "main\n", "remote": "u\n", "log": "0\n", "rev-list": "1\n",
+			"branch": "main\n", "tag": "v0.1.0\n",
 		}, &used),
 	})
 	if err != nil {

internal/sandbox/manager.go

@@ -3,8 +3,9 @@ package sandbox
 import (
 	"errors"
 	"os"
-	"os/exec"
+	"path/filepath"
 	"runtime"
+	"strings"
 )
 
 // errWindowsSandboxNotInitialized is returned only to a caller that explicitly
@@ -121,9 +122,55 @@ func (manager SandboxManager) Backend() Backend {
 	return manager.backend
 }
 
+// isExecutable checks whether a file is executable. On Unix, this checks the
+// execute permission bits. On Windows, Go's os.FileMode does not set execute
+// bits, so we check for common executable extensions instead.
+func isExecutable(fi os.FileInfo) bool {
+	if !fi.Mode().IsRegular() {
+		return false
+	}
+	if runtime.GOOS == "windows" {
+		name := strings.ToLower(fi.Name())
+		return strings.HasSuffix(name, ".exe") ||
+			strings.HasSuffix(name, ".com") ||
+			strings.HasSuffix(name, ".bat") ||
+			strings.HasSuffix(name, ".cmd")
+	}
+	return fi.Mode()&0o111 != 0
+}
+
+// lookupExecutable checks whether a named binary exists and is executable,
+// using os.Stat instead of exec.LookPath. exec.LookPath internally uses the
+// faccessat2 syscall, which is blocked by Android's seccomp filter (SIGSYS).
+func lookupExecutable(name string) (string, error) {
+	if !strings.Contains(name, string(os.PathSeparator)) {
+		path := os.Getenv("PATH")
+		for _, dir := range strings.Split(path, string(os.PathListSeparator)) {
+			if dir == "" {
+				continue // skip empty entries (e.g. trailing colon)
+			}
+			candidate := filepath.Join(dir, name)
+			if fi, err := os.Stat(candidate); err == nil {
+				if isExecutable(fi) {
+					return candidate, nil
+				}
+			}
+		}
+		return "", errors.New("executable file not found in $PATH")
+	}
+	fi, err := os.Stat(name)
+	if err != nil {
+		return "", err
+	}
+	if isExecutable(fi) {
+		return name, nil
+	}
+	return "", errors.New("executable file not found")
+}
+
 func selectPlatformBackend(goos string, lookup func(string) (string, error)) Backend {
 	if lookup == nil {
-		lookup = exec.LookPath
+		lookup = lookupExecutable
 	}
 	switch goos {
 	case "linux":

internal/sandbox/runner_windows_integration_test.go

@@ -190,6 +190,67 @@ func TestWindowsUnelevatedRealSandboxSmoke(t *testing.T) {
 	}
 }
 
+// TestWindowsRestrictedTokenNestedPipeCapture pins the fix in
+// broadenWindowsRestrictedTokenDefaultDacl (windows_token_windows.go): a
+// nested subprocess spawned FROM WITHIN the sandboxed process, with its
+// output captured via a pipe, must succeed. Before the fix, the sandboxed
+// process's own attempt to create a pipe for such a subprocess failed with
+// ERROR_ACCESS_DENIED (Win32 error 5) — the WRITE_RESTRICTED token's extra
+// access check has no restricted-SID match against a freshly created pipe's
+// default security descriptor. This is exactly the pattern any tool that
+// shells out internally and captures output hits (`gh` invoking `git`, for
+// one; cmd.exe's own FOR /F does the identical CreatePipe+CreateProcess
+// dance internally, so it reproduces the bug with no external dependency
+// beyond cmd.exe itself).
+func TestWindowsRestrictedTokenNestedPipeCapture(t *testing.T) {
+	if os.Getenv("ZERO_SANDBOX_REAL_SMOKE") != "1" {
+		t.Skip("set ZERO_SANDBOX_REAL_SMOKE=1 to run real Windows sandbox smoke tests")
+	}
+	runnerExe := realSmokeExecutable(t, "ZERO_WINDOWS_COMMAND_RUNNER_EXE", WindowsSandboxCommandRunnerName)
+
+	root := t.TempDir()
+	sandboxHome := filepath.Join(root, ".zero-sandbox")
+	profile := PermissionProfile{
+		FileSystem: FileSystemPolicy{
+			Kind:                 FileSystemRestricted,
+			ReadRoots:            []string{root},
+			WriteRoots:           []WritableRoot{{Root: root, ProtectedMetadataNames: []string{".git", ".zero", ".agents"}}},
+			IncludePlatformRoots: true,
+			AllowTemp:            true,
+		},
+		Network: NetworkPolicy{Mode: NetworkDeny},
+	}
+	config := WindowsSandboxCommandArgsOptions{
+		SandboxHome:       sandboxHome,
+		CommandCWD:        root,
+		WorkspaceRoots:    []string{root},
+		PermissionProfile: profile,
+		SandboxLevel:      WindowsSandboxLevelUnelevated,
+	}
+
+	marker := filepath.Join(root, "nested-pipe-marker.txt")
+	script := filepath.Join(root, "nested-pipe.cmd")
+	// FOR /F drives cmd.exe's own internal CreatePipe+CreateProcess capture
+	// of the quoted command's output — the exact mechanism this fix targets.
+	// The full path to whoami.exe sidesteps PATH resolution inside the
+	// sandboxed process's minimal environment.
+	scriptBody := "for /F %%i in ('C:\\Windows\\System32\\whoami.exe') do echo %%i> " + marker + "\r\n"
+	if err := os.WriteFile(script, []byte(scriptBody), 0o644); err != nil {
+		t.Fatalf("write nested-pipe script: %v", err)
+	}
+
+	runWindowsRealSmokeCommand(t, runnerExe, config, []string{
+		"cmd.exe", "/d", "/s", "/c", script,
+	}, 0)
+	captured, err := os.ReadFile(marker)
+	if err != nil {
+		t.Fatalf("read nested-pipe marker: %v", err)
+	}
+	if strings.TrimSpace(string(captured)) == "" {
+		t.Fatalf("nested-pipe marker is empty; FOR /F failed to capture the subprocess's output")
+	}
+}
+
 func realSmokeExecutable(t *testing.T, envKey string, fallbackName string) string {
 	t.Helper()
 	if path := os.Getenv(envKey); path != "" {

internal/sandbox/windows_token_windows.go

@@ -21,6 +21,11 @@ const (
 
 var procCreateRestrictedToken = windows.NewLazySystemDLL("advapi32.dll").NewProc("CreateRestrictedToken")
 
+// procSetEntriesInAclW merges new ACEs into an existing ACL. Not wrapped by
+// x/sys/windows (its internal setEntriesInAcl is unexported), so it is
+// declared directly the same way procCreateRestrictedToken is.
+var procSetEntriesInAclW = windows.NewLazySystemDLL("advapi32.dll").NewProc("SetEntriesInAclW")
+
 type windowsLocalSID struct {
 	sid *windows.SID
 }
@@ -122,9 +127,139 @@ func createWindowsRestrictedTokenFromBase(base windows.Token, capabilitySIDs []w
 		_ = restricted.Close()
 		return 0, err
 	}
+	if err := broadenWindowsRestrictedTokenDefaultDacl(restricted, sidFromBytes(logonSID)); err != nil {
+		_ = restricted.Close()
+		return 0, err
+	}
+	runtime.KeepAlive(logonSID)
 	return restricted, nil
 }
 
+// broadenWindowsRestrictedTokenDefaultDacl adds the token's own logon SID to
+// its default DACL (the DACL applied to any kernel object the token's process
+// creates WITHOUT an explicit security descriptor, e.g. anonymous pipes,
+// events, mutexes).
+//
+// A WRITE_RESTRICTED token requires a WRITE-type access check to match BOTH
+// the normal enabled-SID grant AND a SEPARATE grant to one of the token's
+// restricted SIDs. CreateRestrictedToken does not touch the default DACL it
+// inherits from the base token, so newly created objects only carry ACEs for
+// the base token's normal identity (owner, SYSTEM, Administrators) — none of
+// which are in the restricted-SID list — so the second check fails. This
+// breaks anything that creates a pipe/handle for itself with default
+// security, which is exactly what any tool using a language runtime's
+// "spawn a subprocess and capture its output" primitive does (Go's os/exec,
+// and by extension `gh`, and many other CLI tools that shell out
+// internally): CreatePipe() succeeds, but the creating process's own token
+// then fails to actually read/write the handle it just made.
+//
+// The logon SID is already unconditionally present in this token's
+// restricted-SID list (see createWindowsRestrictedTokenFromBase), so adding
+// it here — and ONLY it — to the default DACL is the minimal change that
+// satisfies the WRITE_RESTRICTED extra check for self-created objects. It
+// does not touch file-system access: NTFS write-jailing is enforced by the
+// explicit ACL grants applied to workspace paths (windows_acl.go), which are
+// created WITH an explicit security descriptor and never consult the token's
+// default DACL. The exposure is bounded to the same logon session (other
+// processes running as the same signed-in user could, in principle, open a
+// NAMED kernel object the sandboxed process creates with default security;
+// anonymous pipes — the actual object type this fixes — have no name and are
+// only reachable via an inherited handle, so this is a no-op for them).
+func broadenWindowsRestrictedTokenDefaultDacl(token windows.Token, logonSID *windows.SID) error {
+	oldDacl, oldDaclBuf, err := windowsTokenDefaultDacl(token)
+	if err != nil {
+		return fmt.Errorf("read token default DACL: %w", err)
+	}
+	// The second (WRITE-type) access check only needs a read/write match; a
+	// full GENERIC_ALL grant (which also implies DELETE, WRITE_DAC, and
+	// WRITE_OWNER) is broader than the pipe/event/mutex use case this exists
+	// for actually requires.
+	access := []windows.EXPLICIT_ACCESS{{
+		AccessPermissions: windows.GENERIC_READ | windows.GENERIC_WRITE,
+		AccessMode:        windows.GRANT_ACCESS,
+		Inheritance:       windows.NO_INHERITANCE,
+		Trustee: windows.TRUSTEE{
+			MultipleTrusteeOperation: windows.NO_MULTIPLE_TRUSTEE,
+			TrusteeForm:              windows.TRUSTEE_IS_SID,
+			TrusteeType:              windows.TRUSTEE_IS_USER,
+			TrusteeValue:             windows.TrusteeValueFromSID(logonSID),
+		},
+	}}
+	newDacl, err := setEntriesInACL(access, oldDacl)
+	// oldDacl points INTO oldDaclBuf (see windowsTokenDefaultDacl) and is
+	// dereferenced by native code inside setEntriesInACL, above. Nothing in Go
+	// references oldDaclBuf once windowsTokenDefaultDacl returned, so without
+	// this KeepAlive it is eligible for GC the moment an allocation in this
+	// function (the EXPLICIT_ACCESS literal, TrusteeValueFromSID) hits a
+	// safepoint, before the native call ever reads it - a real, if narrow,
+	// use-after-free window in security-boundary code.
+	runtime.KeepAlive(oldDaclBuf)
+	if err != nil {
+		return fmt.Errorf("merge token default DACL: %w", err)
+	}
+	defer func() { _, _ = windows.LocalFree(windows.Handle(unsafe.Pointer(newDacl))) }()
+	if err := windowsSetTokenDefaultDacl(token, newDacl); err != nil {
+		return fmt.Errorf("set token default DACL: %w", err)
+	}
+	return nil
+}
+
+type windowsTokenDefaultDaclInfo struct {
+	DefaultDacl *windows.ACL
+}
+
+// windowsTokenDefaultDacl returns the token's current default DACL along with
+// the buffer backing it. TOKEN_DEFAULT_DACL embeds the ACL data inside the
+// same allocation GetTokenInformation fills, so the returned *windows.ACL is
+// only valid for as long as the returned buffer stays reachable: the caller
+// must runtime.KeepAlive(buf) until every native call that dereferences the
+// ACL has completed. A KeepAlive inside this function, ending at its own
+// return, would not protect any use by the caller after that.
+func windowsTokenDefaultDacl(token windows.Token) (*windows.ACL, []byte, error) {
+	var size uint32
+	err := windows.GetTokenInformation(token, windows.TokenDefaultDacl, nil, 0, &size)
+	if err == nil || err != windows.ERROR_INSUFFICIENT_BUFFER {
+		return nil, nil, fmt.Errorf("size TokenDefaultDacl: %w", err)
+	}
+	buf := make([]byte, size)
+	if err := windows.GetTokenInformation(token, windows.TokenDefaultDacl, &buf[0], size, &size); err != nil {
+		return nil, nil, fmt.Errorf("get TokenDefaultDacl: %w", err)
+	}
+	info := (*windowsTokenDefaultDaclInfo)(unsafe.Pointer(&buf[0]))
+	return info.DefaultDacl, buf, nil
+}
+
+func windowsSetTokenDefaultDacl(token windows.Token, dacl *windows.ACL) error {
+	info := windowsTokenDefaultDaclInfo{DefaultDacl: dacl}
+	err := windows.SetTokenInformation(token, windows.TokenDefaultDacl, (*byte)(unsafe.Pointer(&info)), uint32(unsafe.Sizeof(info)))
+	runtime.KeepAlive(info)
+	return err
+}
+
+// setEntriesInACL merges entries into oldACL via Win32 SetEntriesInAclW,
+// returning a newly allocated ACL the caller must free with windows.LocalFree.
+func setEntriesInACL(entries []windows.EXPLICIT_ACCESS, oldACL *windows.ACL) (*windows.ACL, error) {
+	if len(entries) == 0 {
+		return nil, errors.New("setEntriesInACL requires at least one entry")
+	}
+	var newACL *windows.ACL
+	// SetEntriesInAclW reports failure directly in its return value (ERROR_SUCCESS
+	// on success, a Win32 error code otherwise); unlike many Win32 APIs it does not
+	// set the thread's last-error, so the syscall trio's second/third return
+	// values (which surface GetLastError) are not meaningful here.
+	ret, _, _ := procSetEntriesInAclW.Call(
+		uintptr(len(entries)),
+		uintptr(unsafe.Pointer(&entries[0])),
+		uintptr(unsafe.Pointer(oldACL)),
+		uintptr(unsafe.Pointer(&newACL)),
+	)
+	runtime.KeepAlive(entries)
+	if ret != 0 {
+		return nil, fmt.Errorf("SetEntriesInAclW: %w", syscall.Errno(ret))
+	}
+	return newACL, nil
+}
+
 func copyWindowsLogonSID(token windows.Token) ([]byte, error) {
 	groups, err := token.GetTokenGroups()
 	if err == nil {

internal/streamjson/streamjson.go

@@ -21,6 +21,7 @@ type EventType string
 const (
 	EventRunStart           EventType = "run_start"
 	EventText               EventType = "text"
+	EventReasoning          EventType = "reasoning"
 	EventToolCall           EventType = "tool_call"
 	EventPermission         EventType = "permission"
 	EventPermissionRequest  EventType = "permission_request"

internal/tools/ask_user.go

@@ -272,15 +272,36 @@ func coerceAskUserOptions(optionsValue, descsValue any) (labels []string, descri
 // FormatAskUserAnswers renders question/answer pairs into a clear, model-readable
 // block. Missing answers are surfaced explicitly so the model never silently
 // treats an unanswered question as answered.
+//
+// It distinguishes two shapes of "empty" the model would otherwise conflate: a
+// wholesale dismissal (the user closed the prompt without answering ANYTHING) is
+// flagged up front as a skip, so the model doesn't invent a default; a single
+// blank field amid other answers is marked "(left blank)".
 func FormatAskUserAnswers(questions []AskUserQuestion, answers []string) string {
-	lines := make([]string, 0, len(questions)*3)
+	anyAnswered := false
+	for index := range questions {
+		if index < len(answers) && strings.TrimSpace(answers[index]) != "" {
+			anyAnswered = true
+			break
+		}
+	}
+
+	lines := make([]string, 0, len(questions)*3+2)
+	if len(questions) > 0 && !anyAnswered {
+		lines = append(lines, "[note] The user dismissed this prompt without answering. Treat this as a skip: do not assume a default — ask again more specifically, or proceed only if the intent is already unambiguous.")
+		lines = append(lines, "")
+	}
 	for index, question := range questions {
 		answer := ""
 		if index < len(answers) {
 			answer = strings.TrimSpace(answers[index])
 		}
 		if answer == "" {
-			answer = "(no answer provided)"
+			if anyAnswered {
+				answer = "(left blank)"
+			} else {
+				answer = "(skipped)"
+			}
 		}
 		lines = append(lines, fmt.Sprintf("%d. [question] %s", index+1, question.Question))
 		lines = append(lines, "[answer] "+answer)

internal/tools/ask_user_format_test.go

@@ -0,0 +1,34 @@
+package tools
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestFormatAskUserAnswersDistinguishesSkipFromBlank(t *testing.T) {
+	questions := []AskUserQuestion{
+		{Question: "Which database?"},
+		{Question: "Migrate existing data?"},
+	}
+
+	// Wholesale dismissal (nothing answered): flagged as a skip up front.
+	dismissed := FormatAskUserAnswers(questions, []string{"", ""})
+	if !strings.Contains(dismissed, "dismissed this prompt") || !strings.Contains(dismissed, "Treat this as a skip") {
+		t.Fatalf("all-empty answers must be flagged as a skip, got:\n%s", dismissed)
+	}
+	if strings.Contains(dismissed, "left blank") {
+		t.Fatalf("a full dismissal should read as skipped, not left-blank:\n%s", dismissed)
+	}
+	if !strings.Contains(dismissed, "(skipped)") {
+		t.Fatalf("dismissed questions should render (skipped):\n%s", dismissed)
+	}
+
+	// Partial answer: the blank one is "left blank", no wholesale-skip note.
+	partial := FormatAskUserAnswers(questions, []string{"postgres", ""})
+	if strings.Contains(partial, "dismissed this prompt") {
+		t.Fatalf("a partial answer is not a dismissal:\n%s", partial)
+	}
+	if !strings.Contains(partial, "postgres") || !strings.Contains(partial, "(left blank)") {
+		t.Fatalf("partial answers should show the answer and mark the blank one left-blank:\n%s", partial)
+	}
+}

internal/tools/bash.go

@@ -1,7 +1,6 @@
 package tools
 
 import (
-	"bytes"
 	"context"
 	"errors"
 	"fmt"
@@ -123,10 +122,14 @@ func (tool bashTool) run(ctx context.Context, args map[string]any, engine *zeroS
 	defer plan.Cleanup()
 	addSandboxMeta(meta, plan)
 
-	var stdout bytes.Buffer
-	var stderr bytes.Buffer
-	command.Stdout = &stdout
-	command.Stderr = &stderr
+	// Bound the capture so a command with runaway output (`cat huge.log`, `yes`)
+	// can't grow Zero's memory before truncation: only the head+tail each stream
+	// will ever surface to the model are retained, the middle is discarded as it
+	// streams, and the true size is counted for the truncation marker.
+	stdout := newBoundedBuffer(bashOutputBudgetBytes, bashOutputBudgetBytes)
+	stderr := newBoundedBuffer(bashOutputBudgetBytes, bashOutputBudgetBytes)
+	command.Stdout = stdout
+	command.Stderr = stderr
 
 	// Kill the shell as a process group on timeout and bound the post-kill I/O
 	// wait, so a backgrounded child cannot outlive the command or hang Run().
@@ -138,7 +141,12 @@ func (tool bashTool) run(ctx context.Context, args map[string]any, engine *zeroS
 	err = command.Run()
 	exitCode := commandExitCode(err)
 	meta["exit_code"] = strconv.Itoa(exitCode)
-	stderrText := appendSandboxBlocks(stderr.String(), monitor.Stop())
+	stdoutText := stdout.retained()
+	stderrRetained := stderr.retained()
+	stderrText := appendSandboxBlocks(stderrRetained, monitor.Stop())
+	// Sandbox blocks are extra model-visible stderr bytes appended after capture;
+	// count them toward the true total so the budget/marker stay accurate.
+	stderrTotal := stderr.total + (len(stderrText) - len(stderrRetained))
 
 	if errors.Is(commandCtx.Err(), context.DeadlineExceeded) {
 		return Result{
@@ -155,26 +163,31 @@ func (tool bashTool) run(ctx context.Context, args map[string]any, engine *zeroS
 				Meta:   meta,
 			}
 		}
-		markLikelySandboxDenial(meta, plan, exitCode, stdout.String(), stderrText)
+		markLikelySandboxDenial(meta, plan, exitCode, stdoutText, stderrText)
+		outText, errText, truncated := budgetBashCapture(stdoutText, stdout.total, stderrText, stderrTotal, meta)
 		return Result{
-			Status: StatusError,
-			Output: formatBashOutputWithShellHint(commandText, stdout.String(), stderrText, exitCode, meta),
-			Meta:   meta,
+			Status:    StatusError,
+			Output:    formatBashOutputWithShellHint(commandText, outText, errText, exitCode, meta),
+			Truncated: truncated,
+			Meta:      meta,
 		}
 	}
 
-	markLikelySandboxDenial(meta, plan, exitCode, stdout.String(), stderrText)
+	markLikelySandboxDenial(meta, plan, exitCode, stdoutText, stderrText)
+	outText, errText, truncated := budgetBashCapture(stdoutText, stdout.total, stderrText, stderrTotal, meta)
 	if meta[SandboxLikelyDeniedMeta] == "true" {
 		return Result{
-			Status: StatusError,
-			Output: formatBashOutputWithShellHint(commandText, stdout.String(), stderrText, exitCode, meta),
-			Meta:   meta,
+			Status:    StatusError,
+			Output:    formatBashOutputWithShellHint(commandText, outText, errText, exitCode, meta),
+			Truncated: truncated,
+			Meta:      meta,
 		}
 	}
 	return Result{
-		Status: StatusOK,
-		Output: formatBashOutput(stdout.String(), stderrText, exitCode),
-		Meta:   meta,
+		Status:    StatusOK,
+		Output:    formatBashOutput(outText, errText, exitCode),
+		Truncated: truncated,
+		Meta:      meta,
 	}
 }
 
@@ -354,12 +367,125 @@ func formatBashOutput(stdout string, stderr string, exitCode int) string {
 	if len(parts) == 0 {
 		return "Command completed with no output."
 	}
-	// Cap the context cost of a verbose command at the same default budget as
-	// exec_command (head/tail window); the full output is spilled to disk and
-	// referenced in the truncation notice, so nothing is lost. Previously bash
-	// output was unbounded — one chatty build log could flood the context.
-	output, _ := truncateExecOutputSpill(strings.Join(parts, "\n"), defaultMaxOutputTokens, "bash")
-	return output
+	return strings.Join(parts, "\n")
+}
+
+// bashOutputBudgetBytes caps each of stdout/stderr shown to the model. bash is the
+// one tool that can emit unbounded output (`cat large.log`, `find /`, verbose test
+// runs); every other read/search tool already budgets its output. Head+tail
+// truncation keeps both the start and the end of an oversized stream, since
+// build/test failures usually surface at the tail.
+const bashOutputBudgetBytes = 96 * 1024
+
+// budgetBashOutput truncates stdout and stderr to bashOutputBudgetBytes each,
+// keeping the head and tail of anything larger, and records raw/emitted byte
+// counts plus a truncated flag in meta (mirroring outputBudgetMeta's shape for
+// the read/search tools). Detection that needs the full output (sandbox-denial
+// scanning) must run on the raw strings before this is applied.
+func budgetBashOutput(stdout string, stderr string, meta map[string]string) (string, string, bool) {
+	return budgetBashCapture(stdout, len(stdout), stderr, len(stderr), meta)
+}
+
+// budgetBashCapture is budgetBashOutput for the streaming-capture path: outTotal
+// and errTotal are the true byte counts (from boundedBuffer.total), which may
+// exceed the retained strings when the middle was dropped during capture. Meta's
+// raw_bytes therefore reflects everything the command produced, not just what was
+// kept in memory.
+func budgetBashCapture(out string, outTotal int, errStr string, errTotal int, meta map[string]string) (string, string, bool) {
+	outText, outRaw, outTrunc := truncateHeadTailWithTotal(out, outTotal, bashOutputBudgetBytes)
+	errText, errRaw, errTrunc := truncateHeadTailWithTotal(errStr, errTotal, bashOutputBudgetBytes)
+	truncated := outTrunc || errTrunc
+	if meta != nil {
+		emitted := len(outText) + len(errText)
+		meta["raw_bytes"] = strconv.Itoa(outRaw + errRaw)
+		meta["emitted_bytes"] = strconv.Itoa(emitted)
+		meta["estimated_tokens"] = strconv.Itoa(estimatedTokensFromBytes(emitted))
+		if truncated {
+			meta["truncated"] = "true"
+		}
+	}
+	return outText, errText, truncated
+}
+
+// boundedBuffer is an io.Writer that retains at most headCap bytes from the start
+// and tailCap bytes from the end of a stream while counting the total written, so
+// a command emitting unbounded output (`cat huge.log`, `yes`) cannot grow Zero's
+// memory: the middle is discarded as it arrives instead of buffered whole and then
+// truncated. total records the full size for the truncation marker even though the
+// middle is never held. Not safe for concurrent writes; exec drives Stdout and
+// Stderr from separate goroutines, so each stream gets its own buffer.
+type boundedBuffer struct {
+	head    []byte
+	headCap int
+	tail    []byte
+	tailCap int
+	total   int
+}
+
+func newBoundedBuffer(headCap, tailCap int) *boundedBuffer {
+	return &boundedBuffer{headCap: headCap, tailCap: tailCap}
+}
+
+func (b *boundedBuffer) Write(p []byte) (int, error) {
+	n := len(p)
+	b.total += n
+	// Fill the head until it reaches headCap; the head is written once and frozen.
+	if len(b.head) < b.headCap {
+		take := b.headCap - len(b.head)
+		if take > len(p) {
+			take = len(p)
+		}
+		b.head = append(b.head, p[:take]...)
+		p = p[take:]
+	}
+	// Anything past the head feeds a rolling tail that keeps only the last tailCap
+	// bytes. Compact once it grows past 2×tailCap so the append stays amortized O(1)
+	// while memory never exceeds ~2×tailCap.
+	if len(p) > 0 && b.tailCap > 0 {
+		b.tail = append(b.tail, p...)
+		if len(b.tail) > 2*b.tailCap {
+			b.tail = append(b.tail[:0], b.tail[len(b.tail)-b.tailCap:]...)
+		}
+	}
+	return n, nil
+}
+
+// retained returns the kept head+tail bytes (marker-less) as a string. The junction
+// between head and tail lands in the middle, which the display budget trims away;
+// callers that need the true size read total separately.
+func (b *boundedBuffer) retained() string {
+	if len(b.tail) > b.tailCap {
+		// Not yet compacted since the last overflow; expose only the last tailCap.
+		return string(b.head) + string(b.tail[len(b.tail)-b.tailCap:])
+	}
+	return string(b.head) + string(b.tail)
+}
+
+// truncateHeadTail keeps the first and last halves of value when it exceeds
+// maxBytes, dropping the middle behind a marker. Returns the possibly-truncated
+// text, the raw byte length, and whether truncation happened.
+func truncateHeadTail(value string, maxBytes int) (string, int, bool) {
+	// value holds the whole stream, so its length is the true raw size.
+	return truncateHeadTailWithTotal(value, len(value), maxBytes)
+}
+
+// truncateHeadTailWithTotal head+tail-truncates value to maxBytes, using total —
+// the full original byte count — for the "N bytes omitted" marker and the raw
+// count. total may exceed len(value) when the middle was already discarded during
+// bounded capture (boundedBuffer): value then holds only the retained head+tail,
+// and this trims it to the display budget while still reporting the true total.
+func truncateHeadTailWithTotal(value string, total, maxBytes int) (string, int, bool) {
+	if maxBytes <= 0 || total <= maxBytes {
+		return value, total, false
+	}
+	marker := fmt.Sprintf("\n[zero] output truncated: %d bytes omitted from the middle — redirect to a file and read_file a range for the full text\n", total-maxBytes)
+	budget := maxBytes - len(marker)
+	if budget < 0 {
+		budget = 0
+	}
+	head := budget / 2
+	tail := budget - head
+	return utf8Prefix(value, head) + marker + utf8Suffix(value, tail), total, true
 }
 
 func formatBashOutputWithShellHint(command string, stdout string, stderr string, exitCode int, meta map[string]string) string {

internal/tools/bash_budget_test.go

@@ -0,0 +1,127 @@
+package tools
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// Small output passes through untouched and records raw==emitted, no truncated flag.
+func TestBudgetBashOutputSmallPassesThrough(t *testing.T) {
+	meta := map[string]string{}
+	out, errStr, truncated := budgetBashOutput("hello\n", "warn\n", meta)
+	if out != "hello\n" || errStr != "warn\n" {
+		t.Fatalf("small output altered: out=%q err=%q", out, errStr)
+	}
+	if truncated {
+		t.Fatalf("small output must report truncated=false")
+	}
+	if meta["truncated"] == "true" {
+		t.Fatalf("small output must not be flagged truncated: %v", meta)
+	}
+	if meta["raw_bytes"] != strconv.Itoa(len("hello\n")+len("warn\n")) {
+		t.Fatalf("raw_bytes wrong: %v", meta)
+	}
+}
+
+// Oversized stdout is truncated head+tail: both the first and last lines survive,
+// the middle is dropped behind a marker, and meta is flagged.
+func TestBudgetBashOutputTruncatesHeadAndTail(t *testing.T) {
+	head := "FIRST_LINE_MARKER\n"
+	tail := "\nLAST_LINE_MARKER"
+	big := head + strings.Repeat("x", bashOutputBudgetBytes) + tail
+
+	meta := map[string]string{}
+	out, _, truncated := budgetBashOutput(big, "", meta)
+
+	if !truncated {
+		t.Fatalf("oversized output must report truncated=true")
+	}
+	if !strings.Contains(out, "FIRST_LINE_MARKER") {
+		t.Fatalf("head lost after truncation")
+	}
+	if !strings.Contains(out, "LAST_LINE_MARKER") {
+		t.Fatalf("tail lost after truncation (failures live at the tail)")
+	}
+	if !strings.Contains(out, "output truncated") {
+		t.Fatalf("expected a truncation marker, got:\n%s", out[:200])
+	}
+	if len(out) > bashOutputBudgetBytes {
+		t.Fatalf("emitted %d bytes exceeds budget %d", len(out), bashOutputBudgetBytes)
+	}
+	if meta["truncated"] != "true" {
+		t.Fatalf("expected truncated=true, got %v", meta)
+	}
+	if meta["raw_bytes"] != strconv.Itoa(len(big)) {
+		t.Fatalf("raw_bytes = %s, want %d", meta["raw_bytes"], len(big))
+	}
+	if got, _ := strconv.Atoi(meta["emitted_bytes"]); got != len(out) {
+		t.Fatalf("emitted_bytes = %s, want %d", meta["emitted_bytes"], len(out))
+	}
+}
+
+// boundedBuffer must keep memory bounded to head+tail while counting every byte,
+// so a runaway command can't OOM Zero before truncation runs. It keeps the very
+// first bytes (head) and the very last bytes (tail), discarding the middle.
+func TestBoundedBufferKeepsHeadAndTailBounded(t *testing.T) {
+	b := newBoundedBuffer(8, 8)
+	total := 0
+	for i := 0; i < 1000; i++ {
+		chunk := []byte(fmt.Sprintf("%05d.", i)) // 6 bytes each
+		n, err := b.Write(chunk)
+		if err != nil || n != len(chunk) {
+			t.Fatalf("Write = (%d, %v), want (%d, nil)", n, err, len(chunk))
+		}
+		total += len(chunk)
+	}
+	if b.total != total {
+		t.Fatalf("total = %d, want %d (every byte must be counted)", b.total, total)
+	}
+	// Retained memory is bounded regardless of how much streamed through.
+	if len(b.head) > 8 {
+		t.Fatalf("head grew past its cap: %d", len(b.head))
+	}
+	if len(b.tail) > 2*8 {
+		t.Fatalf("tail grew past 2×cap (compaction failed): %d", len(b.tail))
+	}
+	r := b.retained()
+	if len(r) > 8+8 {
+		t.Fatalf("retained %d bytes, want <= headCap+tailCap", len(r))
+	}
+	if !strings.HasPrefix(r, "00000.") {
+		t.Fatalf("retained head lost, got prefix %q", r[:min(6, len(r))])
+	}
+	if !strings.HasSuffix(r, "00999.") {
+		t.Fatalf("retained tail lost, got %q", r)
+	}
+}
+
+// budgetBashCapture reports the TRUE total (not the retained size) in the marker
+// and raw_bytes, even though only a bounded head+tail was ever held in memory.
+func TestBudgetBashCaptureReportsTrueTotal(t *testing.T) {
+	// Retained head+tail as boundedBuffer would hand over; the real command produced
+	// far more than was kept.
+	retained := "HEAD_START" + strings.Repeat("y", bashOutputBudgetBytes) + "TAIL_END"
+	total := 10 * bashOutputBudgetBytes
+
+	meta := map[string]string{}
+	out, _, truncated := budgetBashCapture(retained, total, "", 0, meta)
+
+	if !truncated {
+		t.Fatal("oversized capture must report truncated=true")
+	}
+	if !strings.Contains(out, "HEAD_START") || !strings.Contains(out, "TAIL_END") {
+		t.Fatalf("head/tail lost after budgeting:\n%s", out[:min(120, len(out))])
+	}
+	if len(out) > bashOutputBudgetBytes {
+		t.Fatalf("emitted %d bytes exceeds budget %d", len(out), bashOutputBudgetBytes)
+	}
+	if meta["raw_bytes"] != strconv.Itoa(total) {
+		t.Fatalf("raw_bytes = %s, want the true total %d", meta["raw_bytes"], total)
+	}
+	// The marker must cite the true omitted count (total-budget), not retained-budget.
+	if !strings.Contains(out, strconv.Itoa(total-bashOutputBudgetBytes)) {
+		t.Fatalf("marker should cite the true omitted byte count:\n%s", out[:min(200, len(out))])
+	}
+}

internal/tools/bash_tool_test.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"path/filepath"
 	"runtime"
+	"strconv"
 	"strings"
 	"testing"
 	"time"
@@ -252,6 +253,43 @@ func TestBashToolRunsCommandInWorkspace(t *testing.T) {
 	}
 }
 
+// A command with runaway output must not be buffered whole in memory: the capture
+// is bounded to head+tail, yet raw_bytes still reports the true (much larger) size.
+// If capture were unbounded this would balloon Zero's memory before truncation.
+func TestBashToolBoundsRunawayOutputCapture(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("uses a POSIX shell pipeline (yes | head)")
+	}
+	const produced = 500000 // ~5× the 96 KiB budget
+
+	result := NewBashTool(t.TempDir()).Run(context.Background(), map[string]any{
+		"command": fmt.Sprintf("yes ABCDEFGH | head -c %d", produced),
+	})
+
+	if result.Status != StatusOK {
+		t.Fatalf("expected ok status, got %s: %s", result.Status, result.Output)
+	}
+	if !result.Truncated || result.Meta["truncated"] != "true" {
+		t.Fatalf("runaway output should be flagged truncated, meta=%v", result.Meta)
+	}
+	if !strings.Contains(result.Output, "output truncated") {
+		t.Fatalf("expected a truncation marker in output")
+	}
+	// The emitted (model-visible) text is capped near the budget...
+	if len(result.Output) > bashOutputBudgetBytes+1024 {
+		t.Fatalf("emitted %d bytes far exceeds budget %d", len(result.Output), bashOutputBudgetBytes)
+	}
+	// ...but raw_bytes reflects the full stream, proving the total was counted while
+	// only a bounded slice was ever held (raw >> the ~2×budget retention cap).
+	raw, err := strconv.Atoi(result.Meta["raw_bytes"])
+	if err != nil {
+		t.Fatalf("raw_bytes not an int: %q", result.Meta["raw_bytes"])
+	}
+	if raw < produced {
+		t.Fatalf("raw_bytes = %d, want >= %d (full stream counted)", raw, produced)
+	}
+}
+
 func TestBashToolUsesRequestedCwd(t *testing.T) {
 	root := t.TempDir()
 	nested := filepath.Join(root, "nested")

internal/tools/edit_file.go

@@ -114,7 +114,10 @@ func (tool editFileTool) RunWithOptions(ctx context.Context, args map[string]any
 		switch {
 		case ferr == nil:
 			oldString = search
-			newString = findNew
+			// The model's new_string was written at old_string's (mismatched)
+			// indentation; re-shape it to the span actually being replaced so a
+			// tolerant match never strips indentation or a trailing CR.
+			newString = adaptReplacementToSpan(search, findOld, findNew)
 			occurrences = strings.Count(content, search)
 		case errors.Is(ferr, errEditFuzzyAmbiguous):
 			return errorResult("Error: old_string matches multiple locations in " + relativePath + " even after fuzzy matching. Provide more surrounding context to make the match unique, or pass replace_all: true.")

internal/tools/edit_replacers.go

@@ -13,6 +13,7 @@ package tools
 import (
 	"errors"
 	"regexp"
+	"sort"
 	"strings"
 )
 
@@ -45,26 +46,42 @@ func fuzzyEditMatch(content, find string, replaceAll bool) (string, error) {
 	}
 	found := false
 	for _, replacer := range replacers {
+		// Collect the replacer's DISTINCT candidate spans that literally occur in
+		// content. Two or more distinct spans from one strategy (e.g. duplicate
+		// blocks at different indentation, each occurring once) mean the model's
+		// intent is genuinely ambiguous — silently editing the first would be a
+		// wrong-span write, so it is rejected instead.
+		var candidates []string
+		seen := map[string]bool{}
 		for _, search := range replacer(content, find) {
-			if search == "" {
+			if search == "" || seen[search] {
 				continue
 			}
-			index := strings.Index(content, search)
-			if index < 0 {
-				continue
-			}
-			found = true
-			if isDisproportionateEditMatch(search, find) {
-				return "", errors.New("refusing replacement because the matched span is much larger than old_string; re-read the file and provide the full exact old_string for the intended replacement")
-			}
-			if replaceAll {
-				return search, nil
-			}
-			if strings.LastIndex(content, search) != index {
+			seen[search] = true
+			if strings.Index(content, search) < 0 {
 				continue
 			}
+			candidates = append(candidates, search)
+		}
+		if len(candidates) == 0 {
+			continue
+		}
+		found = true
+		if !replaceAll && len(candidates) > 1 {
+			return "", errEditFuzzyAmbiguous
+		}
+		search := candidates[0]
+		if isDisproportionateEditMatch(search, find) {
+			return "", errors.New("refusing replacement because the matched span is much larger than old_string; re-read the file and provide the full exact old_string for the intended replacement")
+		}
+		if replaceAll {
 			return search, nil
 		}
+		if strings.Index(content, search) == strings.LastIndex(content, search) {
+			return search, nil
+		}
+		// The single candidate occurs at multiple positions; a later, stricter
+		// strategy may still resolve a unique span, so keep cascading.
 	}
 	if !found {
 		return "", errEditFuzzyNotFound
@@ -202,22 +219,33 @@ func blockAnchorReplacer(content, find string) []string {
 		return similarity / float64(linesToCheck)
 	}
 
-	best := candidates[0]
-	if len(candidates) > 1 {
-		bestSimilarity := -1.0
-		for _, candidate := range candidates {
-			if s := middleSimilarity(candidate); s > bestSimilarity {
-				bestSimilarity = s
-				best = candidate
-			}
+	// Return EVERY candidate that clears the similarity threshold, best first.
+	// Picking only the best would hide competing blocks from fuzzyEditMatch's
+	// distinct-candidate ambiguity check and could silently edit the wrong
+	// block; with all qualifying spans surfaced, one clear winner still
+	// resolves (single candidate) while two plausible blocks are rejected as
+	// ambiguous. replaceAll consumers take the first (most similar) span.
+	type scoredSpan struct {
+		span       span
+		similarity float64
+	}
+	var qualifying []scoredSpan
+	for _, candidate := range candidates {
+		if s := middleSimilarity(candidate); s >= editAnchorSimilarityThreshold {
+			qualifying = append(qualifying, scoredSpan{span: candidate, similarity: s})
 		}
-		if bestSimilarity < editAnchorSimilarityThreshold {
-			return nil
-		}
-	} else if middleSimilarity(best) < editAnchorSimilarityThreshold {
+	}
+	if len(qualifying) == 0 {
 		return nil
 	}
-	return []string{strings.Join(contentLines[best.start:best.end+1], "\n")}
+	sort.SliceStable(qualifying, func(i, j int) bool {
+		return qualifying[i].similarity > qualifying[j].similarity
+	})
+	spans := make([]string, 0, len(qualifying))
+	for _, scored := range qualifying {
+		spans = append(spans, strings.Join(contentLines[scored.span.start:scored.span.end+1], "\n"))
+	}
+	return spans
 }
 
 var editWhitespaceRun = regexp.MustCompile(`\s+`)
@@ -422,6 +450,75 @@ func contextAwareReplacer(content, find string) []string {
 	return candidates
 }
 
+// adaptReplacementToSpan re-shapes the model's replacement to the span a
+// tolerant matcher resolved. When old_string only matched after normalization,
+// new_string was written at old_string's (wrong) shape, so applying it raw
+// would strip the file's indentation or drop a trailing CR:
+//
+//  1. Uniform re-indent: when every span line equals delta + the corresponding
+//     find line's indentation (the line-trimmed / indentation-flexible shapes),
+//     the same delta is prepended to every non-blank replacement line. Any
+//     line that breaks the uniform-delta relationship disables the shift —
+//     block-anchor matches with a drifted interior are left untouched.
+//  2. Trailing CR: a span from a CRLF file ends mid-line at "\r" (candidates
+//     are built by joining lines split on "\n"); the replacement gets the same
+//     trailing "\r" so the file's CRLF pairs stay intact.
+func adaptReplacementToSpan(span, find, replacement string) string {
+	if delta, ok := uniformIndentDelta(span, find); ok && delta != "" {
+		lines := strings.Split(replacement, "\n")
+		for i, line := range lines {
+			if strings.TrimSpace(line) == "" {
+				continue
+			}
+			lines[i] = delta + line
+		}
+		replacement = strings.Join(lines, "\n")
+	}
+	if strings.HasSuffix(span, "\r") && !strings.HasSuffix(replacement, "\r") {
+		replacement += "\r"
+	}
+	return replacement
+}
+
+// uniformIndentDelta returns the indentation prefix that, prepended to every
+// non-blank find line, yields the corresponding span line's indentation. ok is
+// false when line counts differ, any line pair disagrees on the delta, or the
+// span is not simply a uniformly deeper-indented copy of find.
+func uniformIndentDelta(span, find string) (string, bool) {
+	spanLines := strings.Split(span, "\n")
+	findLines := splitFindLines(find)
+	if len(spanLines) != len(findLines) {
+		return "", false
+	}
+	leadingWhitespace := func(line string) string {
+		return line[:len(line)-len(strings.TrimLeft(line, " \t"))]
+	}
+	delta := ""
+	haveDelta := false
+	for i := range findLines {
+		spanLine := strings.TrimSuffix(spanLines[i], "\r")
+		findLine := strings.TrimSuffix(findLines[i], "\r")
+		if strings.TrimSpace(spanLine) == "" && strings.TrimSpace(findLine) == "" {
+			continue
+		}
+		spanIndent := leadingWhitespace(spanLine)
+		findIndent := leadingWhitespace(findLine)
+		if !strings.HasSuffix(spanIndent, findIndent) {
+			return "", false
+		}
+		lineDelta := spanIndent[:len(spanIndent)-len(findIndent)]
+		if !haveDelta {
+			delta = lineDelta
+			haveDelta = true
+			continue
+		}
+		if lineDelta != delta {
+			return "", false
+		}
+	}
+	return delta, haveDelta
+}
+
 // levenshtein computes edit distance with a two-row rolling matrix.
 func levenshtein(a, b string) int {
 	if a == "" {

internal/tools/edit_replacers_test.go

@@ -47,11 +47,13 @@ func TestEditFuzzyLineTrimmed(t *testing.T) {
 	initial := "func a() {\n\tx := 1\n\treturn x\n}\n"
 	result, after := runEdit(t, t.TempDir(), initial, map[string]any{
 		"old_string": "x := 1\nreturn x",
-		"new_string": "\ty := 2\n\treturn y",
+		"new_string": "y := 2\nreturn y",
 	})
 	if result.Status != StatusOK {
 		t.Fatalf("expected ok, got %q", result.Output)
 	}
+	// new_string was written at old_string's outdented shape; the span's
+	// indentation must be re-applied so the file keeps its tabs.
 	if !strings.Contains(after, "\ty := 2\n\treturn y\n}") {
 		t.Fatalf("unexpected content: %q", after)
 	}
@@ -112,16 +114,69 @@ func TestEditFuzzyIndentationFlexible(t *testing.T) {
 	initial := "if ok {\n\t\tfor i := range xs {\n\t\t\tsum += xs[i]\n\t\t}\n}\n"
 	result, after := runEdit(t, t.TempDir(), initial, map[string]any{
 		"old_string": "for i := range xs {\n\tsum += xs[i]\n}",
-		"new_string": "\t\tsum += total(xs)",
+		"new_string": "sum += total(xs)",
 	})
 	if result.Status != StatusOK {
 		t.Fatalf("expected ok, got %q", result.Output)
 	}
-	if !strings.Contains(after, "total(xs)") || strings.Contains(after, "range xs") {
+	// The replacement lands at the span's real depth (two tabs), not at
+	// old_string's outdented depth.
+	if !strings.Contains(after, "\t\tsum += total(xs)") || strings.Contains(after, "range xs") {
 		t.Fatalf("unexpected content: %q", after)
 	}
 }
 
+func TestEditFuzzyCRLFLineTrimmedPreservesCarriageReturns(t *testing.T) {
+	// CRLF file + a multi-line outdented old_string: the resolved span carries
+	// tabs and trailing CRs; the replacement must inherit both so the file's
+	// CRLF pairs and indentation survive the edit.
+	initial := "func a() {\r\n\tx := 1\r\n\treturn x\r\n}\r\n"
+	result, after := runEdit(t, t.TempDir(), initial, map[string]any{
+		"old_string": "x := 1\nreturn x",
+		"new_string": "y := 2\nreturn y",
+	})
+	if result.Status != StatusOK {
+		t.Fatalf("expected ok, got %q", result.Output)
+	}
+	if !strings.Contains(after, "\ty := 2\r\n\treturn y\r\n}") {
+		t.Fatalf("unexpected content: %q", after)
+	}
+	if strings.Contains(after, "\n\treturn y\n") {
+		t.Fatalf("bare LF introduced into CRLF file: %q", after)
+	}
+}
+
+func TestUniformIndentDelta(t *testing.T) {
+	cases := []struct {
+		span, find string
+		want       string
+		ok         bool
+	}{
+		{"\tx := 1\n\treturn x", "x := 1\nreturn x", "\t", true},
+		{"\t\tfor {\n\t\t\tgo()\n\t\t}", "for {\n\tgo()\n}", "\t\t", true},
+		{"x := 1", "x := 1", "", true},                          // no shift needed
+		{"\tx := 1\n  return x", "x := 1\nreturn x", "", false}, // mixed delta
+		{"\ta\n\tb\n\tc", "a\nb", "", false},                    // line-count mismatch
+		{"  a", "\ta", "", false},                               // find indent not a suffix
+	}
+	for _, c := range cases {
+		got, ok := uniformIndentDelta(c.span, c.find)
+		if ok != c.ok || (ok && got != c.want) {
+			t.Errorf("uniformIndentDelta(%q, %q) = %q,%v want %q,%v", c.span, c.find, got, ok, c.want, c.ok)
+		}
+	}
+}
+
+func TestAdaptReplacementLeavesNonUniformSpansAlone(t *testing.T) {
+	// Block-anchor style match with a drifted interior: no uniform delta, so
+	// the replacement must pass through untouched.
+	span := "\tfunc h() {\n\t\t// drifted comment\n\t}"
+	find := "func h() {\n// different comment\n}"
+	if got := adaptReplacementToSpan(span, find, "replacement()"); got != "replacement()" {
+		t.Fatalf("non-uniform span must not re-indent: %q", got)
+	}
+}
+
 func TestEditFuzzyEscapeNormalized(t *testing.T) {
 	// Model reproduced the line as it would appear inside a quoted string
 	// literal, with escaped quotes.
@@ -262,3 +317,53 @@ func TestLevenshtein(t *testing.T) {
 		}
 	}
 }
+
+func TestEditFuzzyDistinctCandidatesAreAmbiguous(t *testing.T) {
+	// Two same-content blocks at DIFFERENT indentation: each resolved span is
+	// distinct and occurs exactly once, so the old literal-uniqueness check
+	// passed and silently edited the first block. Distinct-shaped candidates
+	// from one strategy must instead report ambiguity and leave the file alone.
+	initial := "\tif x {\n\t\tgo()\n\t}\nmid\n\t\tif x {\n\t\t\tgo()\n\t\t}\n"
+	result, after := runEdit(t, t.TempDir(), initial, map[string]any{
+		"old_string": "if x {\n\tgo()\n}",
+		"new_string": "stop()",
+	})
+	if result.Status != StatusError || !strings.Contains(result.Output, "multiple locations") {
+		t.Fatalf("distinct fuzzy candidates must be ambiguous, got %q", result.Output)
+	}
+	if after != initial {
+		t.Fatalf("file must be unchanged, got %q", after)
+	}
+}
+
+func TestEditFuzzyBlockAnchorTwoPlausibleBlocksAmbiguous(t *testing.T) {
+	// Two blocks share the same first/last anchor lines and BOTH interiors sit
+	// above the similarity threshold. Picking the "best" one would silently
+	// edit a block the model may not have meant; both must surface so the
+	// cascade reports ambiguity and the file stays untouched.
+	initial := strings.Join([]string{
+		"func setup(cfg Config) {",
+		"\tvalue := compute(alpha, beta, gamma)",
+		"}",
+		"",
+		"func setup(cfg Config) {",
+		"\tvalue := compute(alpha, delta, gamma)",
+		"}",
+		"",
+	}, "\n")
+	find := strings.Join([]string{
+		"func setup(cfg Config) {",
+		"\tvalue := compute(alpha, omega, gamma)",
+		"}",
+	}, "\n")
+	result, after := runEdit(t, t.TempDir(), initial, map[string]any{
+		"old_string": find,
+		"new_string": "func setup(cfg Config) {}",
+	})
+	if result.Status != StatusError || !strings.Contains(result.Output, "multiple locations") {
+		t.Fatalf("two plausible anchor blocks must be ambiguous, got %q", result.Output)
+	}
+	if after != initial {
+		t.Fatalf("file must be unchanged, got %q", after)
+	}
+}

internal/tools/spill.go

@@ -1,6 +1,7 @@
 package tools
 
 import (
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
@@ -21,12 +22,68 @@ import (
 // are opportunistically removed whenever a new spill happens.
 const spillRetention = 7 * 24 * time.Hour
 
-// spillDir returns the shared spill directory, creating it on first use.
+// spillRootPath returns the spill directory path without creating or checking
+// it. Used by the read-path resolver to recognize spill files as readable.
+func spillRootPath() string {
+	name := "zero-tool-output"
+	if uid := os.Getuid(); uid >= 0 {
+		name = fmt.Sprintf("zero-tool-output-%d", uid)
+	}
+	return filepath.Join(os.TempDir(), name)
+}
+
+// resolveSpillReadPath reports whether requestedPath is a file inside the
+// spill directory and, if so, returns its verified absolute path. Spill files
+// are zero-created, per-uid owned, and already secret-redacted, so letting the
+// scoped read tools open them is what makes the truncation notice's
+// "read_file it" recovery actually work. Symlinks are resolved and the result
+// must still be inside the spill dir, so a planted link cannot smuggle an
+// out-of-scope file through this gate.
+func resolveSpillReadPath(requestedPath string) (string, bool) {
+	if requestedPath == "" || !filepath.IsAbs(requestedPath) {
+		return "", false
+	}
+	root := spillRootPath()
+	cleaned := filepath.Clean(requestedPath)
+	if cleaned == root || !strings.HasPrefix(cleaned, root+string(filepath.Separator)) {
+		return "", false
+	}
+	resolved, err := filepath.EvalSymlinks(cleaned)
+	if err != nil {
+		return "", false
+	}
+	resolvedRoot, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		return "", false
+	}
+	if !strings.HasPrefix(resolved, resolvedRoot+string(filepath.Separator)) {
+		return "", false
+	}
+	return resolved, true
+}
+
+// spillDir returns the per-user spill directory, creating it on first use.
+// Hardened for shared temp dirs (Linux /tmp): the name carries the uid so
+// users cannot collide, and a pre-existing path is only accepted when it is a
+// real directory (not a symlink that would redirect spills) owned by the
+// current user. Any doubt fails the spill — it is best-effort anyway.
 func spillDir() (string, error) {
-	dir := filepath.Join(os.TempDir(), "zero-tool-output")
+	dir := spillRootPath()
 	if err := os.MkdirAll(dir, 0o700); err != nil {
 		return "", err
 	}
+	// MkdirAll follows symlinks and leaves an existing directory untouched, so
+	// verify what is actually at the path.
+	info, err := os.Lstat(dir)
+	if err != nil {
+		return "", err
+	}
+	if !info.IsDir() {
+		return "", fmt.Errorf("spill path %s is not a directory", dir)
+	}
+	if err := checkSpillDirOwner(info); err != nil {
+		return "", err
+	}
 	return dir, nil
 }
 

internal/tools/spill_hardening_test.go

@@ -0,0 +1,91 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+func spillDirName() string {
+	if uid := os.Getuid(); uid >= 0 {
+		return fmt.Sprintf("zero-tool-output-%d", uid)
+	}
+	return "zero-tool-output"
+}
+
+func TestSpillDirRejectsSymlink(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("symlink creation needs privileges on Windows")
+	}
+	tmp := t.TempDir()
+	t.Setenv("TMPDIR", tmp)
+	elsewhere := filepath.Join(tmp, "elsewhere")
+	if err := os.Mkdir(elsewhere, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	// An attacker pre-creates the spill path as a symlink to redirect spills.
+	if err := os.Symlink(elsewhere, filepath.Join(tmp, spillDirName())); err != nil {
+		t.Fatal(err)
+	}
+	if path := spillTruncatedOutput("bash", "sensitive output"); path != "" {
+		t.Fatalf("spill must refuse a symlinked directory, wrote %s", path)
+	}
+	entries, _ := os.ReadDir(elsewhere)
+	if len(entries) != 0 {
+		t.Fatalf("nothing may land behind the symlink: %v", entries)
+	}
+}
+
+func TestSpillDirAcceptsOwnedDirectory(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	if path := spillTruncatedOutput("bash", "ok"); path == "" {
+		t.Fatal("spill must work in a clean per-user temp dir")
+	}
+}
+
+func TestResolveSpillReadPathContainment(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	spillPath := spillTruncatedOutput("exec_command", "spilled body")
+	if spillPath == "" {
+		t.Fatal("spill must succeed in a clean temp dir")
+	}
+	resolved, ok := resolveSpillReadPath(spillPath)
+	if !ok || resolved == "" {
+		t.Fatalf("a real spill file must resolve, got ok=%v", ok)
+	}
+	if _, ok := resolveSpillReadPath(filepath.Join(spillRootPath(), "..", "escape.txt")); ok {
+		t.Fatal("path traversal out of the spill dir must be rejected")
+	}
+	if _, ok := resolveSpillReadPath("/etc/hosts"); ok {
+		t.Fatal("paths outside the spill dir must be rejected")
+	}
+	if _, ok := resolveSpillReadPath(spillRootPath()); ok {
+		t.Fatal("the spill dir itself is not a readable file target")
+	}
+	if runtime.GOOS != "windows" {
+		// A symlink planted inside the spill dir pointing outside must not leak.
+		link := filepath.Join(spillRootPath(), "sneaky-link")
+		if err := os.Symlink("/etc/hosts", link); err == nil {
+			if _, ok := resolveSpillReadPath(link); ok {
+				t.Fatal("symlink escaping the spill dir must be rejected")
+			}
+		}
+	}
+}
+
+func TestReadFileCanReadSpillFile(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	spillPath := spillTruncatedOutput("exec_command", "line one\nline two\n")
+	if spillPath == "" {
+		t.Fatal("spill must succeed")
+	}
+	workspace := t.TempDir()
+	result := NewReadFileTool(workspace).Run(context.Background(), map[string]any{"path": spillPath})
+	if result.Status != StatusOK || !strings.Contains(result.Output, "line two") {
+		t.Fatalf("read_file must be able to follow the truncation notice: %s %q", result.Status, result.Output)
+	}
+}

internal/tools/spill_owner_unix.go

@@ -0,0 +1,24 @@
+//go:build !windows
+
+package tools
+
+import (
+	"fmt"
+	"os"
+	"syscall"
+)
+
+// checkSpillDirOwner rejects a spill directory not owned by the current user:
+// on a shared /tmp another user could have pre-created the path and would then
+// control its lifetime (deletion/renaming) even though the 0600 spill files
+// keep their contents private.
+func checkSpillDirOwner(info os.FileInfo) error {
+	stat, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return nil
+	}
+	if int(stat.Uid) != os.Geteuid() {
+		return fmt.Errorf("spill directory is owned by uid %d, not the current user", stat.Uid)
+	}
+	return nil
+}

internal/tools/spill_owner_windows.go

@@ -0,0 +1,12 @@
+//go:build windows
+
+package tools
+
+import "os"
+
+// checkSpillDirOwner is a no-op on Windows: %TEMP% is per-user by default and
+// there is no portable uid to compare. The Lstat symlink/dir check in spillDir
+// still applies.
+func checkSpillDirOwner(os.FileInfo) error {
+	return nil
+}

internal/tools/spill_test.go

@@ -39,18 +39,6 @@ func TestTruncateExecOutputUnderBudgetUnchanged(t *testing.T) {
 	}
 }
 
-func TestFormatBashOutputCapsVerboseOutput(t *testing.T) {
-	t.Setenv("TMPDIR", t.TempDir())
-	long := strings.Repeat("x", 200*1024)
-	formatted := formatBashOutput(long, "", 0)
-	if len(formatted) > defaultMaxOutputTokens*4+1024 {
-		t.Fatalf("bash output must be capped near the token budget, got %d bytes", len(formatted))
-	}
-	if !strings.Contains(formatted, "output truncated") {
-		t.Fatal("capped bash output must carry the truncation notice")
-	}
-}
-
 func TestSweepSpillDirRemovesOnlyOldFiles(t *testing.T) {
 	dir := t.TempDir()
 	oldFile := filepath.Join(dir, "bash-old.txt")

internal/tools/tool_search.go

@@ -261,10 +261,16 @@ func (tool toolSearchTool) rankByKeyword(query string, deferred []Tool) []Tool {
 	for index, candidate := range deferred {
 		name := strings.ToLower(candidate.Name())
 		desc := strings.ToLower(candidate.Description())
+		nameSquashed := squashSeparators(name)
 		score := 0
 		for _, keyword := range keywords {
-			if strings.Contains(name, keyword) {
+			switch {
+			case strings.Contains(name, keyword):
 				score += 2
+			case strings.Contains(nameSquashed, squashSeparators(keyword)):
+				// Separator-insensitive fallback: "webfetch" matches "web_fetch".
+				// Ranked below an exact substring so precise queries still win.
+				score++
 			}
 			if strings.Contains(desc, keyword) {
 				score++
@@ -290,6 +296,19 @@ func (tool toolSearchTool) rankByKeyword(query string, deferred []Tool) []Tool {
 	return matches
 }
 
+// squashSeparators drops separators so "web_fetch", "web-fetch", and "web fetch"
+// all normalize to "webfetch". It lets a query missing the separators still match
+// a tool name, the common way a model mistypes a tool ("webfetch").
+func squashSeparators(s string) string {
+	return strings.Map(func(r rune) rune {
+		switch r {
+		case '_', '-', ' ', '.':
+			return -1
+		}
+		return r
+	}, s)
+}
+
 // noMatchMessage reports that nothing loaded and names the available deferred
 // tools so the model can retry with a valid select: query.
 func (tool toolSearchTool) noMatchMessage(query string, deferred []Tool) string {

internal/tools/tool_search_test.go

@@ -184,6 +184,29 @@ func TestToolSearchKeywordRanksByNameThenDescription(t *testing.T) {
 	}
 }
 
+// A query missing the name's separators still matches: "webfetch" -> web_fetch.
+func TestToolSearchKeywordMatchesSeparatorInsensitive(t *testing.T) {
+	reg := NewRegistry()
+	reg.Register(searchFakeTool{
+		name:        "web_fetch",
+		description: "Fetch a URL.",
+		parameters:  Schema{Type: "object", AdditionalProperties: false},
+	})
+	reg.Register(searchFakeTool{
+		name:        "stock_quote",
+		description: "Get a stock price.",
+		parameters:  Schema{Type: "object", AdditionalProperties: false},
+	})
+	tool := NewToolSearchTool(reg).(optionsAwareTool)
+
+	result := tool.RunWithOptions(context.Background(),
+		map[string]any{"query": "webfetch"}, RunOptions{})
+
+	if got := result.Meta["load_tools"]; got != "web_fetch" {
+		t.Fatalf("load_tools = %q, want web_fetch (separator-insensitive match)", got)
+	}
+}
+
 func TestToolSearchKeywordExcludesNonMatches(t *testing.T) {
 	reg := newDeferredFixtureRegistry()
 	tool := NewToolSearchTool(reg).(optionsAwareTool)

internal/tools/workspace.go

@@ -254,6 +254,14 @@ func scopedReadRoots(workspaceRoot string, scope PathScope) ([]string, error) {
 }
 
 func resolveScopedReadPath(workspaceRoot string, scope PathScope, requestedPath string) (string, string, error) {
+	// Spill files (truncated tool output saved under the per-uid temp dir) are
+	// readable regardless of scope: the truncation notice tells the model to
+	// read_file/grep them, which must actually work. resolveSpillReadPath
+	// verifies containment after symlink resolution, so this cannot be used to
+	// reach anything outside the spill dir.
+	if spillPath, ok := resolveSpillReadPath(requestedPath); ok {
+		return spillPath, spillPath, nil
+	}
 	if requestedPath == "" || !filepath.IsAbs(requestedPath) || scope == nil {
 		return resolveWorkspacePath(workspaceRoot, requestedPath)
 	}

internal/tui/assistant_markdown.go

@@ -8,6 +8,7 @@ import (
 	"unicode/utf8"
 
 	"charm.land/lipgloss/v2"
+	"github.com/charmbracelet/x/ansi"
 )
 
 const (
@@ -237,8 +238,10 @@ func renderAssistantMarkdownPlainText(text string, proseMeasure int, tableMeasur
 }
 
 func stripMarkdownRenderControls(text string) string {
-	text = strings.ReplaceAll(text, markdownBoldStart, "")
-	return strings.ReplaceAll(text, markdownBoldEnd, "")
+	// renderAssistantMarkdownText embeds markdownBoldStart/markdownBoldEnd
+	// markers for prose text, and highlightCodeAuto embeds ANSI color sequences
+	// for fenced code blocks. Strip everything so clipboard text is pure plain text.
+	return ansi.Strip(text)
 }
 
 func styleAssistantMarkdownLine(line string, base lipgloss.Style) string {

internal/tui/autocomplete.go

@@ -188,7 +188,54 @@ func (m model) matchCommandSuggestions(token string) []commandSuggestion {
 	out := matchCommandSuggestionsWithFilter(token, func(command commandDefinition) bool {
 		return command.kind != commandSandboxSetup || m.sandboxSetupCommand != nil
 	})
-	return append(out, m.matchUserCommandSuggestions(token)...)
+	out = append(out, m.matchUserCommandSuggestions(token)...)
+	out = append(out, m.matchSkillSuggestions(token)...)
+	// Each source caps itself, but the merged list must honor the shared cap too
+	// (three sources could otherwise stack up to ~3x the palette bound).
+	if len(out) > maxCommandSuggestions {
+		out = out[:maxCommandSuggestions]
+	}
+	return out
+}
+
+// matchSkillSuggestions returns installed skills whose slash name has the typed
+// prefix, so skills are discoverable and invocable from the palette like user
+// commands. Precedence (builtin > user command > skill) is enforced here by
+// skipping any skill whose name is claimed by a builtin (or alias) or a user
+// command — unlike the builtin/user pair, a shadowed skill row would be dead at
+// dispatch time, so it must not be advertised at all.
+func (m model) matchSkillSuggestions(token string) []commandSuggestion {
+	prefix := strings.ToLower(strings.TrimSpace(strings.TrimPrefix(token, "/")))
+	if prefix == "" || m.loadSkills == nil {
+		return nil
+	}
+	taken := m.takenSlashNames()
+	var out []commandSuggestion
+	// Read through the loader (not the startup snapshot in agentOptions) so the
+	// palette matches what dispatch will actually resolve — a skill installed or
+	// removed mid-session appears/disappears without a restart.
+	for _, skill := range m.installedSkills() {
+		name := skillSlashName(skill.Name)
+		if name == "" || taken[name] || !strings.HasPrefix(name, prefix) {
+			continue
+		}
+		// Two skills whose names collide after lowercasing (e.g. "Deploy" and
+		// "deploy") map to one slash name; only the first — the one dispatch will
+		// run — may be advertised, or the row's description and the executed
+		// instructions silently diverge.
+		taken[name] = true
+		desc := strings.TrimSpace(skill.Description)
+		if desc == "" {
+			desc = "Skill: /" + name
+		} else {
+			desc += " (skill)"
+		}
+		out = append(out, commandSuggestion{Name: "/" + name, Desc: desc})
+		if len(out) >= maxCommandSuggestions {
+			break
+		}
+	}
+	return out
 }
 
 // matchUserCommandSuggestions returns file-sourced /commands whose name has the

internal/tui/coalesce.go

@@ -0,0 +1,109 @@
+package tui
+
+import (
+	"sync"
+	"time"
+
+	tea "charm.land/bubbletea/v2"
+)
+
+// streamCoalesceInterval is roughly one 60fps frame. Assistant-text deltas that
+// arrive within this window are merged into a single agentTextMsg, so the render
+// rate decouples from the token rate: a fast local model (100+ tok/s) no longer
+// forces 100+ full Update→View cycles (each re-parsing the growing markdown) per
+// second. Rendering stays smooth regardless of provider speed.
+const streamCoalesceInterval = 16 * time.Millisecond
+
+// textCoalescer batches agentTextMsg deltas before forwarding them to the Bubble
+// Tea program. Any OTHER message flushes the pending text first, so ordering
+// between streamed prose and tool-call / reasoning / row / usage messages is
+// preserved. The turn's final agentResponseMsg does not pass through here (it is
+// a tea.Cmd return, not a sink message), but the model drops deltas whose runID
+// is no longer active, so a flush that races just past end-of-turn is harmless.
+//
+// Sink messages originate from the single agent goroutine and so arrive
+// serially; the only concurrent caller is the flush timer. The mutex guards the
+// buffer/timer AND is held across the downstream forward, so a timer-fired text
+// flush can never overtake a concurrent non-text message: whoever holds the lock
+// drains and forwards atomically, and the other caller blocks until it is done.
+type textCoalescer struct {
+	forward func(tea.Msg) // downstream sink (external sink + program.Send)
+	// afterFunc schedules fn to run after one frame interval and returns a
+	// stoppable timer. Defaults to a real time.AfterFunc(streamCoalesceInterval, …);
+	// tests swap in a controllable timer so flush timing is deterministic instead of
+	// racing the 16ms wall clock.
+	afterFunc func(fn func()) coalesceTimer
+
+	mu    sync.Mutex
+	buf   []byte
+	runID int
+	timer coalesceTimer
+}
+
+// coalesceTimer is the subset of *time.Timer the coalescer needs. Abstracted
+// behind afterFunc so a test can substitute a timer it controls.
+type coalesceTimer interface {
+	Stop() bool
+}
+
+func newTextCoalescer(forward func(tea.Msg)) *textCoalescer {
+	return &textCoalescer{
+		forward: forward,
+		afterFunc: func(fn func()) coalesceTimer {
+			return time.AfterFunc(streamCoalesceInterval, fn)
+		},
+	}
+}
+
+// send is the coalescing entry point installed as the RuntimeMessageSink.
+func (c *textCoalescer) send(msg tea.Msg) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	text, ok := msg.(agentTextMsg)
+	if !ok {
+		// Non-text message: flush buffered text first (preserving order), then
+		// forward it — both under the lock so nothing can interleave between them.
+		c.drainAndForwardLocked()
+		c.forward(msg)
+		return
+	}
+
+	// A delta for a different run than the one buffered: flush the old run's text
+	// before buffering the new run's. In practice runs are sequential (the prior
+	// run's end already flushed via a non-text message), so this is belt-and-braces.
+	if len(c.buf) > 0 && text.runID != c.runID {
+		c.drainAndForwardLocked()
+	}
+	c.runID = text.runID
+	c.buf = append(c.buf, text.delta...)
+	if c.timer == nil {
+		c.timer = c.afterFunc(c.flush)
+	}
+}
+
+// flush forwards any buffered text as one agentTextMsg. Runs on the timer
+// goroutine; the lock it takes serializes it against send so its output can't be
+// reordered around a concurrent non-text message.
+func (c *textCoalescer) flush() {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.drainAndForwardLocked()
+}
+
+// drainAndForwardLocked forwards any buffered text as one agentTextMsg and stops
+// the timer, all while the caller holds c.mu — so a text flush and any non-text
+// forward are strictly ordered and never interleave. A no-op when nothing is
+// buffered. string(c.buf) copies, so reusing the backing array via [:0] is safe.
+func (c *textCoalescer) drainAndForwardLocked() {
+	if len(c.buf) == 0 {
+		return
+	}
+	if c.timer != nil {
+		c.timer.Stop()
+		c.timer = nil
+	}
+	msg := agentTextMsg{runID: c.runID, delta: string(c.buf)}
+	c.buf = c.buf[:0]
+	c.forward(msg)
+}

internal/tui/coalesce_test.go

@@ -0,0 +1,182 @@
+package tui
+
+import (
+	"sync"
+	"testing"
+	"time"
+
+	tea "charm.land/bubbletea/v2"
+)
+
+// recorder is a thread-safe sink that captures forwarded messages in order.
+type recorder struct {
+	mu   sync.Mutex
+	msgs []tea.Msg
+}
+
+func (r *recorder) forward(msg tea.Msg) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.msgs = append(r.msgs, msg)
+}
+
+func (r *recorder) snapshot() []tea.Msg {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	out := make([]tea.Msg, len(r.msgs))
+	copy(out, r.msgs)
+	return out
+}
+
+// manualTimer is a coalesceTimer that never fires on its own, so a test can prove
+// buffering deterministically without racing the real 16ms frame timer: the flush
+// happens only when the test calls c.flush() explicitly.
+type manualTimer struct{ stopped bool }
+
+func (m *manualTimer) Stop() bool {
+	prev := m.stopped
+	m.stopped = true
+	return !prev
+}
+
+// Rapid deltas within one frame collapse into a single agentTextMsg carrying the
+// concatenated text.
+func TestCoalescerBatchesDeltas(t *testing.T) {
+	rec := &recorder{}
+	c := newTextCoalescer(rec.forward)
+	// Swap in a timer that never auto-fires so the "still buffered" assertion below
+	// cannot flake if the scheduler pauses this goroutine past the frame interval.
+	c.afterFunc = func(func()) coalesceTimer { return &manualTimer{} }
+
+	c.send(agentTextMsg{runID: 1, delta: "Hel"})
+	c.send(agentTextMsg{runID: 1, delta: "lo, "})
+	c.send(agentTextMsg{runID: 1, delta: "world"})
+
+	// Nothing forwarded yet — still buffered within the frame (the timer we injected
+	// never fires; only the explicit flush below delivers the text).
+	if got := rec.snapshot(); len(got) != 0 {
+		t.Fatalf("deltas should buffer, forwarded %d early: %#v", len(got), got)
+	}
+
+	c.flush()
+
+	got := rec.snapshot()
+	if len(got) != 1 {
+		t.Fatalf("expected 1 coalesced message, got %d: %#v", len(got), got)
+	}
+	text, ok := got[0].(agentTextMsg)
+	if !ok || text.delta != "Hello, world" || text.runID != 1 {
+		t.Fatalf("coalesced message = %#v, want agentTextMsg{1, \"Hello, world\"}", got[0])
+	}
+}
+
+// A non-text message flushes buffered text first, so ordering (text before the
+// tool call it precedes) is preserved.
+func TestCoalescerFlushesTextBeforeOtherMessages(t *testing.T) {
+	rec := &recorder{}
+	c := newTextCoalescer(rec.forward)
+
+	c.send(agentTextMsg{runID: 1, delta: "about to run"})
+	c.send(toolCallStreamStartMsg{runID: 1, id: "t1", name: "bash"})
+
+	got := rec.snapshot()
+	if len(got) != 2 {
+		t.Fatalf("expected text then tool-call, got %d: %#v", len(got), got)
+	}
+	if text, ok := got[0].(agentTextMsg); !ok || text.delta != "about to run" {
+		t.Fatalf("first forwarded message must be the flushed text, got %#v", got[0])
+	}
+	if _, ok := got[1].(toolCallStreamStartMsg); !ok {
+		t.Fatalf("second forwarded message must be the tool-call start, got %#v", got[1])
+	}
+}
+
+// A delta for a new run flushes the previous run's buffered text before buffering
+// the new run's, so text is never mis-attributed across runs.
+func TestCoalescerFlushesOnRunSwitch(t *testing.T) {
+	rec := &recorder{}
+	c := newTextCoalescer(rec.forward)
+
+	c.send(agentTextMsg{runID: 1, delta: "run one text"})
+	c.send(agentTextMsg{runID: 2, delta: "run two text"})
+	c.flush()
+
+	got := rec.snapshot()
+	if len(got) != 2 {
+		t.Fatalf("expected one message per run, got %d: %#v", len(got), got)
+	}
+	if first := got[0].(agentTextMsg); first.runID != 1 || first.delta != "run one text" {
+		t.Fatalf("first message = %#v, want run 1 text flushed on switch", got[0])
+	}
+	if second := got[1].(agentTextMsg); second.runID != 2 || second.delta != "run two text" {
+		t.Fatalf("second message = %#v, want run 2 text", got[1])
+	}
+}
+
+// Under concurrency (the frame timer firing while a non-text message is sent),
+// forwarding must stay serialized and ordered: buffered text is always delivered
+// before a following non-text message, never after it. Run with -race to catch
+// the interleaving CodeRabbit flagged.
+func TestCoalescerOrdersTextBeforeNonTextUnderConcurrency(t *testing.T) {
+	for iter := 0; iter < 200; iter++ {
+		rec := &recorder{}
+		c := newTextCoalescer(rec.forward)
+
+		// Buffer text, then let the timer race against an inline non-text send.
+		c.send(agentTextMsg{runID: 1, delta: "before-tool"})
+		done := make(chan struct{})
+		go func() {
+			c.send(toolCallStreamStartMsg{runID: 1, id: "t1", name: "bash"})
+			close(done)
+		}()
+		<-done
+
+		// Give the timer a chance to also fire, then settle.
+		time.Sleep(2 * streamCoalesceInterval)
+		c.flush()
+
+		got := rec.snapshot()
+		textIdx, toolIdx := -1, -1
+		for i, m := range got {
+			switch m.(type) {
+			case agentTextMsg:
+				if textIdx == -1 {
+					textIdx = i
+				}
+			case toolCallStreamStartMsg:
+				toolIdx = i
+			}
+		}
+		if textIdx == -1 || toolIdx == -1 {
+			t.Fatalf("iter %d: missing messages: %#v", iter, got)
+		}
+		if textIdx > toolIdx {
+			t.Fatalf("iter %d: text (%d) forwarded after tool-call (%d): %#v", iter, textIdx, toolIdx, got)
+		}
+	}
+}
+
+// The frame timer flushes buffered text on its own without an explicit flush or a
+// following message.
+func TestCoalescerTimerFlushes(t *testing.T) {
+	rec := &recorder{}
+	c := newTextCoalescer(rec.forward)
+
+	c.send(agentTextMsg{runID: 1, delta: "timer-driven"})
+
+	deadline := time.Now().Add(time.Second)
+	for time.Now().Before(deadline) {
+		if len(rec.snapshot()) > 0 {
+			break
+		}
+		time.Sleep(streamCoalesceInterval)
+	}
+
+	got := rec.snapshot()
+	if len(got) != 1 {
+		t.Fatalf("timer should have flushed exactly one message, got %d: %#v", len(got), got)
+	}
+	if text := got[0].(agentTextMsg); text.delta != "timer-driven" {
+		t.Fatalf("timer-flushed message = %#v", got[0])
+	}
+}

internal/tui/command_center.go

@@ -482,6 +482,9 @@ func (m model) handleModelCommand(args string) (model, string) {
 		lines = append(lines, target.notice)
 	}
 	lines = append(lines, summary)
+	if warn := m.visionDropWarning(); warn != "" {
+		lines = append(lines, warn)
+	}
 	return m, strings.Join(lines, "\n")
 }
 
@@ -536,7 +539,11 @@ func (m model) switchProviderModel(providerName, modelID string) (model, string,
 			cmds = append(cmds, cmd)
 		}
 	}
-	return m, fmt.Sprintf("Model\nSwitched to %s · %s", target.Name, target.Model), tea.Batch(cmds...)
+	status := fmt.Sprintf("Model\nSwitched to %s · %s", target.Name, target.Model)
+	if warn := m.visionDropWarning(); warn != "" {
+		status += "\n" + warn
+	}
+	return m, status, tea.Batch(cmds...)
 }
 
 // profileWithCredential fills a profile's APIKey for provider construction the same

internal/tui/command_views.go

@@ -698,3 +698,19 @@ func (m model) debugText() string {
 		}},
 	})
 }
+
+// skillsText is the /skills fallback when NO skills are installed — an install
+// hint. With skills present /skills opens the searchable skill picker instead
+// (see newSkillPicker), matching how /model works.
+func (m model) skillsText() string {
+	return renderCommandOutput(commandOutput{
+		Title:  "Skills",
+		Status: commandStatusInfo,
+		Sections: []commandSection{{
+			Lines: []string{"No skills installed."},
+		}},
+		Hints: []string{
+			"install one: create <skills-dir>/<name>/SKILL.md (see `zero skills`)",
+		},
+	})
+}

internal/tui/commands.go

@@ -41,7 +41,12 @@ const (
 	commandAddDir
 	commandSelfCorrect
 	commandTurns
+	commandRetry
+	commandEdit
+	commandCopy
+	commandExport
 	commandNew
+	commandSkills
 	commandUnknown
 )
 
@@ -127,6 +132,13 @@ var commandDefinitions = []commandDefinition{
 		description: "List registered tools.",
 		kind:        commandTools,
 	},
+	{
+		name:        "/skills",
+		usage:       "/skills",
+		group:       commandGroupTools,
+		description: "List installed skills; run one directly with /<skill-name> [args].",
+		kind:        commandSkills,
+	},
 	{
 		name:        "/context",
 		usage:       "/context",
@@ -209,9 +221,9 @@ var commandDefinitions = []commandDefinition{
 	},
 	{
 		name:        "/compact",
-		usage:       "/compact [status]",
+		usage:       "/compact [status|now]",
 		group:       commandGroupSession,
-		description: "Show or request transcript compaction state.",
+		description: "Compact the transcript now, or show compaction state (/compact status).",
 		kind:        commandCompact,
 	},
 	{
@@ -257,6 +269,34 @@ var commandDefinitions = []commandDefinition{
 		description: "Show or set the per-run tool-turn budget for this session (raise it for long multi-step tasks).",
 		kind:        commandTurns,
 	},
+	{
+		name:        "/retry",
+		usage:       "/retry",
+		group:       commandGroupSession,
+		description: "Resend your last prompt.",
+		kind:        commandRetry,
+	},
+	{
+		name:        "/edit",
+		usage:       "/edit",
+		group:       commandGroupSession,
+		description: "Recall your last prompt into the composer to edit and resend.",
+		kind:        commandEdit,
+	},
+	{
+		name:        "/copy",
+		usage:       "/copy",
+		group:       commandGroupSession,
+		description: "Copy the last answer to the clipboard.",
+		kind:        commandCopy,
+	},
+	{
+		name:        "/export",
+		usage:       "/export [path]",
+		group:       commandGroupSession,
+		description: "Write the conversation transcript to a file.",
+		kind:        commandExport,
+	},
 	{
 		name:        "/help",
 		usage:       "/help",

internal/tui/compact_now_test.go

@@ -0,0 +1,27 @@
+package tui
+
+import (
+	"strings"
+	"testing"
+)
+
+// "/compact now" is accepted as a manual trigger (not a usage error), while a
+// bogus argument still reports usage.
+func TestCompactNowAccepted(t *testing.T) {
+	m := model{}
+
+	_, nowText, _ := m.handleCompactCommand("now")
+	if strings.Contains(nowText, "usage:") {
+		t.Fatalf("/compact now must be accepted as a trigger, got usage error: %q", nowText)
+	}
+
+	_, statusText, _ := m.handleCompactCommand("status")
+	if strings.Contains(statusText, "usage:") {
+		t.Fatalf("/compact status must not error, got: %q", statusText)
+	}
+
+	_, bogusText, _ := m.handleCompactCommand("frobnicate")
+	if !strings.Contains(bogusText, "usage:") {
+		t.Fatalf("/compact frobnicate must report usage, got: %q", bogusText)
+	}
+}

internal/tui/composer.go

@@ -280,7 +280,7 @@ func (m model) composerPositionAtMouse(msg tea.MouseMsg) (int, bool) {
 }
 
 func (m model) composerMouseSelectionBlocked() bool {
-	return m.setup.visible || m.providerWizard != nil || m.mcpAddWizard != nil ||
+	return m.transcriptDetailed || m.setup.visible || m.providerWizard != nil || m.mcpAddWizard != nil ||
 		m.mcpManager != nil || m.picker != nil || m.suggestionsActive()
 }
 

internal/tui/error_hint_test.go

@@ -0,0 +1,27 @@
+package tui
+
+import (
+	"strings"
+	"testing"
+)
+
+// A hinted error row renders the raw error and the faint one-line next step
+// below it; an unhinted row renders just the error.
+func TestRenderErrorRowShowsHint(t *testing.T) {
+	withHint := renderErrorRow(transcriptRow{
+		kind: rowError,
+		text: "auth error: your API key is missing or invalid",
+		hint: "API key rejected — run /provider to re-check your credentials",
+	}, 80)
+	if !strings.Contains(withHint, "auth error:") {
+		t.Fatalf("expected raw error text in output, got:\n%s", withHint)
+	}
+	if !strings.Contains(withHint, "/provider") {
+		t.Fatalf("expected hint referencing /provider, got:\n%s", withHint)
+	}
+
+	noHint := renderErrorRow(transcriptRow{kind: rowError, text: "provider error: mystery"}, 80)
+	if strings.Contains(noHint, "→") {
+		t.Fatalf("unhinted error must not render a hint arrow, got:\n%s", noHint)
+	}
+}

internal/tui/file_view_test.go

@@ -143,7 +143,7 @@ func TestFileViewSwapsTranscriptBody(t *testing.T) {
 	m := filesPanelTestModel()
 	m = m.openFileView("internal/tui/sidebar.go")
 
-	items := m.transcriptBodyItems(m.chatColumnWidth(), "")
+	items := m.transcriptBodyItems(m.chatColumnWidth(), "", false)
 	if len(items) != 1 {
 		t.Fatalf("file view should swap the body to a single block item, got %d items", len(items))
 	}
@@ -264,6 +264,55 @@ func TestFileViewFullBodyTruncatesLongFile(t *testing.T) {
 	}
 }
 
+// TestDetailedTranscriptClosesFileView: entering detailed transcript mode
+// closes an active file drill-in so the full transcript body replaces the file
+// content.
+func TestDetailedTranscriptClosesFileView(t *testing.T) {
+	m := filesPanelTestModel()
+	m.altScreen = true
+	m = m.openFileView("web/app.js")
+
+	if !m.fileView.active {
+		t.Fatal("sanity check: openFileView should activate the file view")
+	}
+
+	updated, _ := m.Update(testKeyCtrl('o'))
+	m = updated.(model)
+
+	if m.fileView.active {
+		t.Fatal("detailed transcript should close the file drill-in")
+	}
+	if !m.transcriptDetailed {
+		t.Fatal("Ctrl+O should enter detailed mode")
+	}
+
+	items := m.transcriptBodyItems(m.chatColumnWidth(), "", true)
+	if len(items) <= 1 {
+		t.Fatalf("detailed transcript should show multiple body items, got %d", len(items))
+	}
+}
+
+// TestDetailedTranscriptStaysClosedOnSecondToggle: toggling out and back into
+// detailed mode does not re-open the closed file view.
+func TestDetailedTranscriptStaysClosedOnSecondToggle(t *testing.T) {
+	m := filesPanelTestModel()
+	m.altScreen = true
+	m = m.openFileView("web/app.js")
+
+	updated, _ := m.Update(testKeyCtrl('o'))
+	m = updated.(model)
+
+	updated, _ = m.Update(testKeyCtrl('o'))
+	m = updated.(model)
+
+	if m.fileView.active {
+		t.Fatal("exiting detailed mode must not re-open the file drill-in")
+	}
+	if m.transcriptDetailed {
+		t.Fatal("second Ctrl+O should exit detailed mode")
+	}
+}
+
 // TestFileViewKeysDeferToBlockingModal: with a permission prompt up, Esc and
 // the d/f shortcuts belong to the prompt — the drill-in must not swallow them
 // (Esc exiting the view instead of reaching the prompt's deny handling).

internal/tui/files_panel.go

@@ -372,7 +372,7 @@ func (m model) scrollOffsetForTranscriptRow(rowIndex int) (int, bool) {
 		return 0, false
 	}
 	width := m.chatColumnWidth()
-	items := m.transcriptBodyItems(width, "")
+	items := m.transcriptBodyItems(width, "", false)
 	metrics := measureTranscriptBodyItems(items, m.transcriptBodyHeights)
 	startY := -1
 	for _, span := range metrics.spans {

internal/tui/flush_test.go

@@ -121,7 +121,7 @@ func TestEscCancellationLeavesVisibleMarker(t *testing.T) {
 	m.pending = true
 	m.activeRunID = 5
 	m.runCancel = func() {}
-	m.streamingText = "half an answer"
+	m.streamingText = []byte("half an answer")
 
 	updated, _ := m.Update(testKey(tea.KeyEsc))
 	next := updated.(model)
@@ -133,7 +133,7 @@ func TestEscCancellationLeavesVisibleMarker(t *testing.T) {
 	if !transcriptContains(next.transcript, "half an answer") {
 		t.Fatalf("expected the partial streamed answer to be preserved, got %#v", next.transcript)
 	}
-	if next.streamingText != "" {
+	if len(next.streamingText) != 0 {
 		t.Fatal("streaming text should be cleared after cancel")
 	}
 }

internal/tui/image_attach.go

@@ -292,6 +292,18 @@ func renderImageChips(labels []string) string {
 // and staged documents, e.g. "[Image #1] [Image #2] [Doc #1]". Returns "" when
 // nothing is staged. Numbered (not named) so a long screenshot path never shows
 // in the composer.
+// visionDropWarning returns a one-line notice when images are staged but the
+// (now active) model can't accept them, so switching to a non-vision model warns
+// the user immediately at switch time instead of silently dropping the images at
+// submit. Empty when there is nothing staged or the model supports vision.
+func (m model) visionDropWarning() string {
+	if len(m.pendingImages) == 0 || m.modelSupportsVisionTUI() {
+		return ""
+	}
+	return fmt.Sprintf("⚠ %d staged image(s) will be dropped — %s has no vision support.",
+		len(m.pendingImages), displayValue(m.modelName, "the active model"))
+}
+
 func renderAttachmentChips(imageLabels []string, docs []pendingDocument) string {
 	chips := make([]string, 0, len(imageLabels)+len(docs))
 	for i := range imageLabels {

internal/tui/image_attach_test.go

@@ -483,3 +483,76 @@ func TestRenderAttachmentChips(t *testing.T) {
 		t.Fatalf("chip row %q should not show file names", got)
 	}
 }
+
+// TestRetryResendsAttachments guards the /retry contract: it must resend the exact
+// request the last prompt carried — including its staged image and PDF document —
+// not a degraded text-only prompt. launchPrompt clears the pending queues once a
+// turn is sent, so without re-staging the remembered snapshot a vision/document-
+// backed turn that failed would silently retry as a different task.
+func TestRetryResendsAttachments(t *testing.T) {
+	root := t.TempDir()
+
+	captured := make(chan []zeroruntime.ImageBlock, 1)
+	provider := &fakeProvider{events: []zeroruntime.StreamEvent{
+		{Type: zeroruntime.StreamEventText, Content: "ok"},
+		{Type: zeroruntime.StreamEventDone},
+	}}
+	m := newModel(context.Background(), Options{
+		Cwd:          root,
+		ProviderName: "openai",
+		ModelName:    "gpt-4.1",
+		Provider:     provider,
+		Registry:     tools.NewRegistry(),
+		SessionStore: testSessionStore(t),
+	})
+	m.agentOptions.OnText = func(string) {}
+	m.captureRunImages = func(imgs []zeroruntime.ImageBlock) { captured <- imgs }
+
+	// State left after a prior vision+PDF prompt was submitted: the pending queues
+	// are cleared, but the remembered snapshot survives so /retry can reproduce it.
+	m.lastPrompt = "describe both"
+	m.lastImages = []zeroruntime.ImageBlock{{MediaType: "image/png", Data: []byte{0x89, 'P', 'N', 'G'}}}
+	m.lastImageLabels = []string{"photo.png"}
+	m.lastDocuments = []pendingDocument{{label: "spec.pdf", text: "Top secret design notes"}}
+
+	m.input.SetValue("/retry")
+	updated, cmd := m.handleSubmit()
+	next := updated.(model)
+	if cmd == nil {
+		t.Fatal("/retry with a remembered prompt should launch a run")
+	}
+	// The retried turn re-consumes and then clears the queues, exactly like a fresh
+	// submit; the snapshot must survive so a second /retry stays reproducible.
+	if len(next.pendingImages) != 0 || len(next.pendingImageLabels) != 0 || len(next.pendingDocuments) != 0 {
+		t.Fatalf("retry must clear pending queues after resend, got imgs=%d labels=%d docs=%d",
+			len(next.pendingImages), len(next.pendingImageLabels), len(next.pendingDocuments))
+	}
+	if len(next.lastImages) != 1 || len(next.lastDocuments) != 1 {
+		t.Fatalf("retry must keep the snapshot for a subsequent retry, got imgs=%d docs=%d",
+			len(next.lastImages), len(next.lastDocuments))
+	}
+
+	updated, _ = next.Update(execCmd(cmd))
+	_ = updated.(model)
+
+	select {
+	case imgs := <-captured:
+		if len(imgs) != 1 || imgs[0].MediaType != "image/png" {
+			t.Fatalf("retried run must resend the remembered image, got %#v", imgs)
+		}
+	default:
+		t.Fatal("expected the retried run to receive the remembered image")
+	}
+
+	if len(provider.requests) != 1 {
+		t.Fatalf("expected one provider request, got %d", len(provider.requests))
+	}
+	msgs := provider.requests[0].Messages
+	last := msgs[len(msgs)-1]
+	if !strings.Contains(last.Content, "Top secret design notes") {
+		t.Fatalf("retried prompt should re-prepend the document text, got:\n%s", last.Content)
+	}
+	if !strings.Contains(last.Content, "describe both") {
+		t.Fatalf("retried prompt should include the remembered user text, got:\n%s", last.Content)
+	}
+}

internal/tui/lsp_manager_test.go

@@ -0,0 +1,31 @@
+package tui
+
+import (
+	"context"
+	"testing"
+)
+
+// The LSP manager is built once at construction (when cwd is known) and reused —
+// a fresh manager per run would cold-start gopls on the first edit of every turn.
+func TestNewModelBuildsSharedLSPManager(t *testing.T) {
+	m := newModel(context.Background(), Options{Cwd: t.TempDir()})
+	if m.lspManager == nil {
+		t.Fatal("expected a session-long lspManager when cwd is set")
+	}
+	// The pointer is stable across model copies (Bubble Tea passes the model by
+	// value every Update), so every run shares the same warm servers.
+	copied := m
+	if copied.lspManager != m.lspManager {
+		t.Fatal("lspManager pointer must survive a model copy")
+	}
+}
+
+// shutdownLSPManager must be nil-safe: a model built without a cwd has no manager,
+// and quitting it must not panic.
+func TestShutdownLSPManagerNilSafe(t *testing.T) {
+	m := model{}
+	if m.lspManager != nil {
+		t.Fatal("expected no manager on a zero-value model")
+	}
+	m.shutdownLSPManager() // must not panic
+}

internal/tui/model.go

@@ -19,6 +19,7 @@ import (
 	"github.com/Gitlawb/zero/internal/agent"
 	"github.com/Gitlawb/zero/internal/config"
 	"github.com/Gitlawb/zero/internal/doctor"
+	"github.com/Gitlawb/zero/internal/errhint"
 	"github.com/Gitlawb/zero/internal/lsp"
 	internalmcp "github.com/Gitlawb/zero/internal/mcp"
 	"github.com/Gitlawb/zero/internal/modelregistry"
@@ -28,6 +29,7 @@ import (
 	"github.com/Gitlawb/zero/internal/providers/providerio"
 	"github.com/Gitlawb/zero/internal/sandbox"
 	"github.com/Gitlawb/zero/internal/sessions"
+	"github.com/Gitlawb/zero/internal/skills"
 	"github.com/Gitlawb/zero/internal/streamjson"
 	"github.com/Gitlawb/zero/internal/tools"
 	"github.com/Gitlawb/zero/internal/usage"
@@ -61,6 +63,7 @@ type model struct {
 	ctx                         context.Context
 	cwd                         string
 	userCommands                []usercommands.Command // file-sourced /commands (.zero/commands)
+	loadSkills                  func() []skills.Skill  // lazy installed-skills loader for /skills + /<skill-name>
 	userConfigPath              string
 	doctorUserConfigPath        string
 	projectConfigPath           string
@@ -76,24 +79,29 @@ type model struct {
 	discoverProviderModels      func(context.Context, config.ProviderProfile) ([]providermodeldiscovery.Model, error)
 	discoverOllamaContextWindow func(ctx context.Context, baseURL string, model string) (int, error)
 	registry                    *tools.Registry
-	sessionStore                *sessions.Store
-	sandboxStore                *sandbox.GrantStore
-	mcpConfig                   config.MCPConfig
-	mcpPermissionStore          *internalmcp.PermissionStore
-	mcpTokenStore               *internalmcp.TokenStore
-	mcpCommand                  func(context.Context, []string) MCPCommandResult
-	sandboxSetupCommand         func(context.Context) SandboxSetupCommandResult
-	mcpViewStateCache           MCPViewState
-	mcpViewStateReady           bool
-	mcpCommandSeq               int
-	mcpCommandCancel            context.CancelFunc
-	sandboxSetupSeq             int
-	sandboxSetupInFlight        bool
-	doctorCommandSeq            int
-	doctorInFlight              bool
-	doctorFrame                 int
-	activeSession               sessions.Metadata
-	sessionEvents               []sessions.Event
+	// lspManager is created once per session and reused across prompts so gopls (and
+	// other language servers) stay warm — a fresh manager per run would cold-start
+	// the server on the first edit of every turn. Nil when cwd is unknown; runs then
+	// fall back to a per-run manager. Torn down in quit().
+	lspManager           *lsp.Manager
+	sessionStore         *sessions.Store
+	sandboxStore         *sandbox.GrantStore
+	mcpConfig            config.MCPConfig
+	mcpPermissionStore   *internalmcp.PermissionStore
+	mcpTokenStore        *internalmcp.TokenStore
+	mcpCommand           func(context.Context, []string) MCPCommandResult
+	sandboxSetupCommand  func(context.Context) SandboxSetupCommandResult
+	mcpViewStateCache    MCPViewState
+	mcpViewStateReady    bool
+	mcpCommandSeq        int
+	mcpCommandCancel     context.CancelFunc
+	sandboxSetupSeq      int
+	sandboxSetupInFlight bool
+	doctorCommandSeq     int
+	doctorInFlight       bool
+	doctorFrame          int
+	activeSession        sessions.Metadata
+	sessionEvents        []sessions.Event
 	// titledSessions records session ids for which a model-generated title has
 	// already been attempted this process, so a finished turn re-fires the title
 	// generator at most once per session (even before its async result lands).
@@ -261,13 +269,30 @@ type model struct {
 	headerPrinted bool
 
 	// Composer input history (shell-style ↑/↓ recall of submitted inputs).
+	// lastPrompt is the verbatim text of the most recent submitted prompt, so
+	// /retry can resend it and /edit can recall it into the composer.
+	lastPrompt string
+	// lastImages/lastImageLabels/lastDocuments remember the attachments consumed
+	// by the most recent submitted prompt. launchPrompt clears the pending queues
+	// once a turn is sent, so /retry re-stages these to reproduce the exact same
+	// request — otherwise a vision/PDF-backed prompt would silently retry as
+	// text-only and answer a different task. They share the underlying image bytes
+	// with the sent turn (never mutated in place), so no deep copy is needed.
+	lastImages      []zeroruntime.ImageBlock
+	lastImageLabels []string
+	lastDocuments   []pendingDocument
 	// historyIdx == len(inputHistory) means "not navigating"; historyDraft
 	// preserves whatever was typed before recall started.
 	inputHistory []string
 	historyIdx   int
 	historyDraft string
 
-	streamingText              string // live assistant text for the current segment
+	// streamingText is the live assistant text for the current segment, accumulated
+	// as []byte so each delta is an O(1) amortized append instead of the O(n²) that
+	// string += delta incurs across a long generation. Read via streamingTextString().
+	// A []byte (not strings.Builder) because the model is copied by value on every
+	// Update, which would trip strings.Builder's copy check.
+	streamingText              []byte
 	streamingReasoning         string // live provider reasoning for the current segment
 	streamingReasoningExpanded bool
 	// turnStreamedRunes accumulates every reasoning+answer rune streamed in the
@@ -712,6 +737,7 @@ func newModel(ctx context.Context, options Options) model {
 		cwd:                         cwd,
 		swarmDoneAt:                 map[string]time.Time{},
 		userCommands:                loadedUserCommands,
+		loadSkills:                  options.LoadSkills,
 		composerCursorVisible:       true,
 		userConfigPath:              options.UserConfigPath,
 		doctorUserConfigPath:        doctorUserConfigPath,
@@ -773,6 +799,11 @@ func newModel(ctx context.Context, options Options) model {
 	// Streaming text always renders statically at base ink (the disabled path in
 	// styleStreamingLine), so no accent glow and no per-line fade ticks.
 	m.fadeDisabled = true
+	// One session-long LSP manager (cheap to build — servers start lazily on the
+	// first Check), reused across prompts so gopls stays warm between turns.
+	if cwd != "" {
+		m.lspManager = lsp.NewManager(cwd)
+	}
 	m.refreshMCPViewState()
 	return m
 }
@@ -902,9 +933,22 @@ func (m model) noBlockingModal() bool {
 func (m model) quit() (tea.Model, tea.Cmd) {
 	m.stopPRWatcher()
 	m.stopAllBackgroundTerminalSessions()
+	m.shutdownLSPManager()
 	return m, tea.Quit
 }
 
+// shutdownLSPManager gracefully stops the session-long language servers on exit.
+// Best-effort with a short deadline so a slow server can't hang the quit; the
+// servers are our child processes and would be reaped on exit regardless.
+func (m model) shutdownLSPManager() {
+	if m.lspManager == nil {
+		return
+	}
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+	_ = m.lspManager.Shutdown(shutdownCtx)
+}
+
 func (m model) handleCtrlC() (tea.Model, tea.Cmd) {
 	if !m.pending && m.composerValue() != "" && m.noBlockingModal() && !m.transcriptDetailed && !m.subchat.active {
 		m.clearComposer()
@@ -1313,7 +1357,7 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 			// home screen or a narrow terminal. Hiding reflows the chat to full
 			// width, so mirror the width-change bookkeeping (re-wrap the streaming
 			// fade, resize the composer) the WindowSizeMsg path does.
-			if m.noBlockingModal() && m.sidebarToggleAllowed() {
+			if !m.transcriptDetailed && m.noBlockingModal() && m.sidebarToggleAllowed() {
 				// Just show/hide — no transcript notice. The reflow IS the feedback,
 				// and emitting a line every toggle piled up noise in the chat.
 				m.sidebarHidden = !m.sidebarHidden
@@ -1380,22 +1424,50 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 				return m, nil
 			}
 		case keyIs(msg, tea.KeyPgUp):
-			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):
+			m = m.clearHover()
+			return m.scrollChat(-m.chatPageScrollLines()), nil
+		case keyShift(msg) && keyIs(msg, tea.KeyUp):
+			// Shift+Up scrolls the transcript up one line. Must be checked before
+			// plain KeyUp so shifted arrows aren't consumed by the composer-path.
 			if m.transcriptDetailed {
 				return m, nil
 			}
+			if m.pendingPermission != nil {
+				return m.movePermissionCursor(-1), nil
+			}
+			if m.pendingAskUser != nil {
+				return m.moveAskUserCursor(-1), nil
+			}
+			if m.providerWizard != nil {
+				return m.handleProviderWizardKey(msg)
+			}
+			if m.mcpAddWizard != nil {
+				return m.handleMCPAddWizardKey(msg)
+			}
+			if m.mcpManager != nil {
+				return m.handleMCPManagerKey(msg)
+			}
+			if m.picker != nil {
+				if m.modelPickerIsLoading() {
+					return m, nil
+				}
+				m.pickerMoved(-1)
+				return m, nil
+			}
+			if m.suggestionsActive() {
+				break
+			}
+			if m.composerValue() != "" {
+				break // let the input handle multiline navigation
+			}
 			m = m.clearHover()
-			return m.scrollChat(-m.chatPageScrollLines()), nil
-		case keyIs(msg, tea.KeyDown):
+			return m.scrollChat(1), nil
+		case keyShift(msg) && keyIs(msg, tea.KeyDown):
+			// Shift+Down scrolls the transcript down one line. Must be checked
+			// before plain KeyDown so shifted arrows aren't consumed.
 			if m.transcriptDetailed {
 				return m, nil
 			}
@@ -1421,6 +1493,41 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 				m.pickerMoved(1)
 				return m, nil
 			}
+			if m.suggestionsActive() {
+				break
+			}
+			if m.composerValue() != "" {
+				break // let the input handle multiline navigation
+			}
+			m = m.clearHover()
+			return m.scrollChat(-1), nil
+		case keyIs(msg, tea.KeyDown):
+			if m.transcriptDetailed {
+				m = m.clearHover()
+				return m.scrollChat(-1), nil
+			}
+			if m.pendingPermission != nil {
+				return m.movePermissionCursor(1), nil
+			}
+			if m.pendingAskUser != nil {
+				return m.moveAskUserCursor(1), nil
+			}
+			if m.providerWizard != nil {
+				return m.handleProviderWizardKey(msg)
+			}
+			if m.mcpAddWizard != nil {
+				return m.handleMCPAddWizardKey(msg)
+			}
+			if m.mcpManager != nil {
+				return m.handleMCPManagerKey(msg)
+			}
+			if m.picker != nil {
+				if m.modelPickerIsLoading() {
+					return m, nil
+				}
+				m.pickerMoved(1)
+				return m, nil
+			}
 			if m.suggestionsActive() {
 				m.moveSuggestion(1)
 				return m, nil
@@ -1439,7 +1546,8 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 				return m, nil
 			}
 			if m.transcriptDetailed {
-				return m, nil
+				m = m.clearHover()
+				return m.scrollChat(1), nil
 			}
 			if m.pendingPermission != nil {
 				return m.movePermissionCursor(-1), nil
@@ -1473,6 +1581,48 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 			if m.historyRecallActive() {
 				return m.recallHistory(-1), nil
 			}
+		case keyCtrl(msg, 'u'):
+			// Ctrl+U scrolls up half a page, or moves the cursor up in
+			// permission/ask-user prompts. Falls through to the active modal
+			// (wizard, etc.) when none of the above are in focus.
+			if m.transcriptDetailed {
+				return m, nil
+			}
+			if m.pendingPermission != nil {
+				return m.movePermissionCursor(-1), nil
+			}
+			if m.pendingAskUser != nil {
+				return m.moveAskUserCursor(-1), nil
+			}
+			if m.providerWizard != nil || m.mcpAddWizard != nil || m.mcpManager != nil || m.picker != nil || m.pendingSpecReview != nil {
+				break
+			}
+			if m.composerValue() != "" {
+				break // let the input handle its own Ctrl+U (delete-to-bol)
+			}
+			m = m.clearHover()
+			return m.scrollChat(m.chatPageScrollLines()), nil
+		case keyCtrl(msg, 'd'):
+			// Ctrl+D scrolls down half a page, or moves the cursor down in
+			// permission/ask-user prompts. Falls through to the active modal
+			// when none of the above are in focus.
+			if m.transcriptDetailed {
+				return m, nil
+			}
+			if m.pendingPermission != nil {
+				return m.movePermissionCursor(1), nil
+			}
+			if m.pendingAskUser != nil {
+				return m.moveAskUserCursor(1), nil
+			}
+			if m.providerWizard != nil || m.mcpAddWizard != nil || m.mcpManager != nil || m.picker != nil || m.pendingSpecReview != nil {
+				break
+			}
+			if m.composerValue() != "" {
+				break // let the input handle its own Ctrl+D (delete-next-char)
+			}
+			m = m.clearHover()
+			return m.scrollChat(-m.chatPageScrollLines()), nil
 		}
 		if m.transcriptDetailed {
 			return m, nil
@@ -1576,7 +1726,7 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 		// Streaming text means any in-progress tool call has finished — clear the
 		// live "writing" block so it doesn't linger over new prose.
 		m.clearStreamingToolCall()
-		m.streamingText += msg.delta
+		m.streamingText = append(m.streamingText, msg.delta...)
 		m.turnStreamedRunes += utf8.RuneCountInString(msg.delta)
 		// recordStreamingDelta appends a time.Time to lineAges for every
 		// newline in the delta and bumps lastStreamActivity. It also
@@ -1859,20 +2009,23 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 			if row, ok := reasoningTranscriptRow("", msg.runID, m.streamingReasoning); ok {
 				m.transcript = appendTranscriptRow(m.transcript, row)
 			}
-			if text := strings.TrimRight(m.streamingText, "\n"); strings.TrimSpace(text) != "" {
+			if text := strings.TrimRight(m.streamingTextString(), "\n"); strings.TrimSpace(text) != "" {
 				m.transcript = appendTranscriptRow(m.transcript, transcriptRow{kind: rowAssistant, text: text})
 			}
 			// The error row terminates the turn, so it carries the done-line
-			// metadata a final assistant row would have carried.
+			// metadata a final assistant row would have carried. A recognized
+			// provider failure (auth/rate-limit/connectivity/…) also carries a
+			// one-line next step so the user isn't left staring at a raw blob.
 			m.transcript = appendTranscriptRow(m.transcript, transcriptRow{
 				kind:        rowError,
 				text:        msg.err.Error(),
+				hint:        errhint.TUIHint(msg.err),
 				final:       true,
 				turnTools:   msg.turnTools,
 				turnElapsed: msg.turnElapsed,
 			})
 		}
-		m.streamingText = ""
+		m.streamingText = nil
 		m.streamingReasoning = ""
 		m.streamingReasoningExpanded = false
 		// Roll the completed run's wall-time into the session's rolling average so
@@ -2047,14 +2200,14 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 				m.streamingReasoning = ""
 				m.streamingReasoningExpanded = false
 			}
-			if text := strings.TrimRight(m.streamingText, "\n"); strings.TrimSpace(text) != "" {
+			if text := strings.TrimRight(m.streamingTextString(), "\n"); strings.TrimSpace(text) != "" {
 				m.transcript = appendTranscriptRow(m.transcript, transcriptRow{kind: rowAssistant, text: text})
 				// This interim narration is the agent explaining what it's about to
 				// do — attribute it to the active plan step so the step-detail card
 				// can replay the agent's own account of the work.
 				m = m.captureStepNarration(text)
 			}
-			m.streamingText = ""
+			m.streamingText = nil
 			// The tool call has finalized into its card — drop the live "writing"
 			// preview so it doesn't linger or duplicate beneath the card.
 			m.clearStreamingToolCall()
@@ -2171,14 +2324,23 @@ func (m model) View() tea.View {
 	}
 	view.ReportFocus = m.notifier != nil
 	if m.wantsMouseCapture() {
-		// 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
+		if isRunningUnderPRoot() {
+			// Under PRoot the AllMotion (1003) sequence doesn't work
+			// reliably, breaking touch-gesture scrolling. Fall back to
+			// CellMotion which still delivers wheel events, clicks, and
+			// drag — the only thing lost is hover-highlighting.
+			view.MouseMode = tea.MouseModeCellMotion
+		} else {
+			// 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
 }
@@ -2253,7 +2415,7 @@ func (m model) transcriptView() string {
 	if m.transcriptEmpty() && !m.pending && viewportOverlay != "" {
 		emptyOverlay = viewportOverlay
 	}
-	bodyItems := m.transcriptBodyItems(width, emptyOverlay)
+	bodyItems := m.transcriptBodyItems(width, emptyOverlay, false)
 
 	footer := m.footerView(width)
 
@@ -2293,7 +2455,7 @@ func (m model) twoColumnTranscriptView() string {
 	width := chatW
 
 	suggestionOverlay := m.suggestionOverlay(width)
-	bodyItems := m.transcriptBodyItems(width, "")
+	bodyItems := m.transcriptBodyItems(width, "", false)
 	footer := m.footerView(width)
 	overlayForViewport := suggestionOverlay
 	if m.transcriptEmpty() && !m.pending {
@@ -2723,7 +2885,15 @@ func (m model) chatTranscriptViewport() (transcriptViewport, bool) {
 		return transcriptViewport{}, false
 	}
 	width := m.chatColumnWidth()
-	items := m.transcriptBodyItems(width, "")
+	if m.transcriptDetailed {
+		items := m.transcriptBodyItems(width, "", true)
+		body := measureTranscriptBodyItems(items, m.transcriptBodyHeights)
+		header := detailedTranscriptHeader(width) + "\n" + zeroTheme.line.Render(strings.Repeat("-", width))
+		footer := m.detailedTranscriptFooter(width)
+		frame := m.scrollableTranscriptFrame(header, footer)
+		return transcriptViewportForLayout(body, frame, m.chatScrollOffset), true
+	}
+	items := m.transcriptBodyItems(width, "", false)
 	body := measureTranscriptBodyItems(items, m.transcriptBodyHeights)
 	frame := m.scrollableTranscriptFrame(m.pinnedTitleBar(width), m.footerView(width))
 	return transcriptViewportForLayout(body, frame, m.chatScrollOffset), true
@@ -2785,7 +2955,7 @@ func (m model) liveReasoningBodyCap() int {
 }
 
 func (m model) interimBlock(width int) string {
-	text := strings.TrimRight(m.streamingText, "\n")
+	text := strings.TrimRight(m.streamingTextString(), "\n")
 	reasoning := strings.TrimRight(m.streamingReasoning, "\n")
 	blocks := []string{}
 	if strings.TrimSpace(reasoning) != "" {
@@ -2849,7 +3019,7 @@ func (m model) spinnerGlyph() string {
 // (reasoning, waiting on the model, or a tool in flight). Cheap and robust — no
 // transcript scan — so it can't misreport on a long, output-less step.
 func (m model) workingActivity() string {
-	if strings.TrimSpace(m.streamingText) != "" {
+	if strings.TrimSpace(m.streamingTextString()) != "" {
 		return "writing"
 	}
 	return "thinking"
@@ -3563,6 +3733,11 @@ func (m model) choosePicker() (tea.Model, tea.Cmd) {
 		if text != "" {
 			m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: text})
 		}
+	case pickerSkill:
+		// Fill the composer with "/name " so the user adds their request before
+		// submitting (a bare second Enter runs it without one); names the slash
+		// path cannot reach run immediately instead.
+		m, cmd = m.chooseSkillFromPicker(item)
 	case pickerTheme:
 		// The hovered palette is already live from the preview; handleThemeCommand
 		// records the choice (m.themeMode) and re-applies it, and reports the switch.
@@ -3678,6 +3853,15 @@ func (m model) handleSubmit() (tea.Model, tea.Cmd) {
 	case commandTools:
 		m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: m.toolsText()})
 		return m, nil
+	case commandSkills:
+		// With skills installed, /skills opens a searchable picker (like /model);
+		// the text card remains only as the no-skills install hint.
+		if picker := m.newSkillPicker(); picker != nil {
+			m.picker = picker
+			return m, nil
+		}
+		m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: m.skillsText()})
+		return m, nil
 	case commandMCP:
 		if strings.TrimSpace(command.text) == "" {
 			return m.openMCPManager(), nil
@@ -3873,6 +4057,11 @@ func (m model) handleSubmit() (tea.Model, tea.Cmd) {
 		if next, cmd, handled := m.handleUserCommand(command.text); handled {
 			return next, cmd
 		}
+		// Then an installed skill: "/<skill-name> [args]" runs the skill directly
+		// (deterministic invocation, vs waiting for the model to pull it in).
+		if next, cmd, handled := m.handleSkillCommand(command.text); handled {
+			return next, cmd
+		}
 		m.transcript = reduceTranscript(m.transcript, transcriptAction{
 			kind: actionAppendError,
 			text: "unknown command: " + command.text,
@@ -3897,6 +4086,62 @@ func (m model) handleSubmit() (tea.Model, tea.Cmd) {
 		}
 		m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: "$ " + cmdText})
 		return m, runBashEscape(m.cwd, cmdText)
+	case commandRetry:
+		// /retry launches a run, so it needs the same guards a normal prompt gets:
+		// never start one while exiting (would strand the shutdown flush) or during
+		// compaction (would race compactResultMsg's wholesale rewrite of
+		// transcript/sessionEvents and silently drop events).
+		if m.exiting {
+			return m, nil
+		}
+		if m.pending {
+			m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: "Retry\ncannot retry while a run is in progress."})
+			return m, nil
+		}
+		if m.compactInFlight {
+			m.transcript = reduceTranscript(m.transcript, transcriptAction{
+				kind: actionAppendSystem,
+				text: "Retry\nstatus: warning\nCompaction is running. Retry once it finishes.",
+			})
+			return m, nil
+		}
+		if strings.TrimSpace(m.lastPrompt) == "" {
+			m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: "Retry\nno previous prompt to resend."})
+			return m, nil
+		}
+		// Re-stage the attachments the last prompt carried so launchPrompt rebuilds
+		// an identical request (document preamble + images + vision re-check). Without
+		// this the queues are empty and /retry would resend a text-only prompt,
+		// silently dropping the image/PDF context and answering a different task.
+		m.pendingImages = m.lastImages
+		m.pendingImageLabels = m.lastImageLabels
+		m.pendingDocuments = m.lastDocuments
+		return m.launchPrompt(m.lastPrompt)
+	case commandEdit:
+		if strings.TrimSpace(m.lastPrompt) == "" {
+			m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: "Edit\nno previous prompt to recall."})
+			return m, nil
+		}
+		// Re-stage the remembered attachments alongside the recalled text so an
+		// edited resend carries the same image/PDF context — the reappearing chip
+		// row is the visible confirmation. Without this, editing a vision- or
+		// document-backed prompt would silently submit a text-only version and
+		// answer a different task (the same gap /retry guards against).
+		m.pendingImages = m.lastImages
+		m.pendingImageLabels = m.lastImageLabels
+		m.pendingDocuments = m.lastDocuments
+		m.input.SetValue(m.lastPrompt)
+		return m, nil
+	case commandCopy:
+		text := m.lastAssistantAnswer()
+		if strings.TrimSpace(text) == "" {
+			m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: "Copy\nno answer to copy yet."})
+			return m, nil
+		}
+		return m, copyTranscriptSelectionCmd(text)
+	case commandExport:
+		m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: m.handleExportCommand(command.text)})
+		return m, nil
 	case commandPrompt:
 		if intent, ok := detectMCPSetupIntent(command.text); ok {
 			return m.openMCPAddWizardFromIntent(intent), nil
@@ -3911,6 +4156,15 @@ func (m model) handleSubmit() (tea.Model, tea.Cmd) {
 // composer. Queued prompts use this path too, so session and image behavior
 // stays identical to immediate submissions.
 func (m model) launchPrompt(prompt string) (model, tea.Cmd) {
+	// Remember the verbatim prompt (before specialist/document expansion) so /retry
+	// and /edit can act on exactly what the user submitted. Snapshot the staged
+	// attachments too: launchPrompt clears the pending queues below, so /retry
+	// re-stages these to resend an identical vision/PDF-backed request rather than
+	// a degraded text-only one.
+	m.lastPrompt = prompt
+	m.lastImages = m.pendingImages
+	m.lastImageLabels = m.pendingImageLabels
+	m.lastDocuments = m.pendingDocuments
 	m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendUser, text: prompt})
 	if m.provider == nil {
 		m.transcript = reduceTranscript(m.transcript, transcriptAction{
@@ -4098,7 +4352,7 @@ func (m *model) cancelRun() {
 		if row, ok := reasoningTranscriptRow("", m.activeRunID, m.streamingReasoning); ok {
 			m.transcript = appendTranscriptRow(m.transcript, row)
 		}
-		if text := strings.TrimRight(m.streamingText, "\n"); strings.TrimSpace(text) != "" {
+		if text := strings.TrimRight(m.streamingTextString(), "\n"); strings.TrimSpace(text) != "" {
 			m.transcript = appendTranscriptRow(m.transcript, transcriptRow{kind: rowAssistant, text: text})
 		}
 		m.transcript = appendTranscriptRow(m.transcript, transcriptRow{kind: rowSystem, text: "Run cancelled."})
@@ -4119,7 +4373,7 @@ func (m *model) cancelRun() {
 	m.pendingAskUser = nil
 	// The interim block renders streamingText live; a cancelled run's partial
 	// answer must not leak into (and concatenate with) the next turn's stream.
-	m.streamingText = ""
+	m.streamingText = nil
 	m.streamingReasoning = ""
 	m.streamingReasoningExpanded = false
 	// Hard-stop the fade and drop the per-line age map. The next turn's
@@ -4196,12 +4450,18 @@ func (m model) runAgentWithOptions(runID int, runCtx context.Context, prompt str
 		// matching exec; the per-turn lsp.Manager is torn down when this run
 		// returns; auto-fix vs report-only follows the active permission mode.
 		if !runOptions.specDraft && options.Cwd != "" {
-			lspManager := lsp.NewManager(options.Cwd)
-			defer func() {
-				shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-				defer cancel()
-				_ = lspManager.Shutdown(shutdownCtx)
-			}()
+			// Prefer the session-long manager (kept warm across prompts). Only when it
+			// is absent — e.g. cwd was unknown at construction, or a test built the
+			// model directly — fall back to a per-run manager that is shut down here.
+			lspManager := m.lspManager
+			if lspManager == nil {
+				lspManager = lsp.NewManager(options.Cwd)
+				defer func() {
+					shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+					defer cancel()
+					_ = lspManager.Shutdown(shutdownCtx)
+				}()
+			}
 			options.SelfCorrect = agent.NewSelfCorrector(options.Cwd, agent.NewLSPDiagnosticsChecker(lspManager), agent.NewProjectVerifier(options.Cwd), agent.SelfCorrectConfig{
 				Enabled:      true,
 				IncludeTests: m.selfCorrectTests,
@@ -4211,7 +4471,7 @@ func (m model) runAgentWithOptions(runID int, runCtx context.Context, prompt str
 			// Inline post-edit diagnostics: edit_file/write_file append error
 			// diagnostics for the file they just wrote to their own output, so the
 			// model sees a break in the same turn. Shares the run's lazy manager.
-			options.FileDiagnostics = agent.NewFileDiagnostics(lspManager)
+			options.FileDiagnostics = agent.NewFileDiagnostics(lspManager, options.Cwd)
 		}
 
 		// Some providers synthesize tool-call ids that repeat within a run (e.g.
@@ -4663,6 +4923,13 @@ func (m model) sendAgentText(runID int, delta string) {
 	m.runtimeMessageSink(agentTextMsg{runID: runID, delta: delta})
 }
 
+// streamingTextString returns the accumulated live assistant text. streamingText
+// is stored as []byte for O(1) amortized appends; the conversion here is bounded
+// by the segment length, the same cost the renderer already pays.
+func (m model) streamingTextString() string {
+	return string(m.streamingText)
+}
+
 func (m model) sendToolCallStreamStart(runID int, id, name string) {
 	if m.runtimeMessageSink == nil {
 		return

internal/tui/model_test.go

@@ -2142,7 +2142,7 @@ func TestTranscriptSelectionPaintsHighlightOnceNotTwice(t *testing.T) {
 	width := m.chatColumnWidth()
 
 	findRow := func(mm model) (transcriptBodyItem, bool) {
-		for _, it := range mm.transcriptBodyItems(width, "") {
+		for _, it := range mm.transcriptBodyItems(width, "", false) {
 			if it.kind == transcriptBodyItemRow && it.rowIndex >= 0 {
 				return it, true
 			}
@@ -2198,7 +2198,7 @@ func TestReasoningAfterToolCardGetsBlankSeparator(t *testing.T) {
 		transcriptRow{kind: rowReasoning, text: "Considering the next step in detail before acting"},
 		transcriptRow{kind: rowToolResult, id: "t2", tool: "read_file", status: tools.StatusOK, detail: "x\ny"},
 	)
-	items := m.transcriptBodyItems(m.chatColumnWidth(), "")
+	items := m.transcriptBodyItems(m.chatColumnWidth(), "", false)
 	reasoningIdx := -1
 	for i := range items {
 		if items[i].rowIndex >= 0 && items[i].rowIndex < len(m.transcript) &&
@@ -2223,7 +2223,7 @@ func TestAssistantNarrationBeforeToolCardGetsBlankSeparator(t *testing.T) {
 		transcriptRow{kind: rowAssistant, text: "I'll inspect the existing file, then run it."},
 		transcriptRow{kind: rowToolResult, id: "t1", tool: "read_file", status: tools.StatusOK, detail: "File: time_test.py\n\n  1 | print('x')"},
 	)
-	items := m.transcriptBodyItems(m.chatColumnWidth(), "")
+	items := m.transcriptBodyItems(m.chatColumnWidth(), "", false)
 	toolIdx := -1
 	for i := range items {
 		if items[i].rowIndex >= 0 && items[i].rowIndex < len(m.transcript) &&
@@ -2247,7 +2247,7 @@ func TestUserPromptBeforeToolCardGetsBlankSeparator(t *testing.T) {
 		transcriptRow{kind: rowUser, text: "create the landing page"},
 		transcriptRow{kind: rowToolResult, id: "t1", tool: "write_file", status: tools.StatusOK, detail: "--- /dev/null\n+++ b/index.html\n@@ -0,0 +1,1 @@\n+<!DOCTYPE html>"},
 	)
-	items := m.transcriptBodyItems(m.chatColumnWidth(), "")
+	items := m.transcriptBodyItems(m.chatColumnWidth(), "", false)
 	toolIdx := -1
 	for i := range items {
 		if items[i].rowIndex >= 0 && items[i].rowIndex < len(m.transcript) &&
@@ -2273,7 +2273,7 @@ func TestAssistantAfterToolCardGetsRuleSeparator(t *testing.T) {
 		transcriptRow{kind: rowToolResult, id: "t1", tool: "bash", status: tools.StatusOK, detail: "stdout:\nok\nexit_code: 0"},
 		transcriptRow{kind: rowAssistant, text: "Done.", final: true},
 	)
-	items := m.transcriptBodyItems(m.chatColumnWidth(), "")
+	items := m.transcriptBodyItems(m.chatColumnWidth(), "", false)
 	finalIdx := -1
 	for i := range items {
 		if items[i].rowIndex >= 0 && items[i].rowIndex < len(m.transcript) &&
@@ -2301,13 +2301,13 @@ func TestStreamingAssistantAfterToolCardGetsRuleSeparator(t *testing.T) {
 	m.width, m.height = 120, 40
 	m.altScreen = true
 	m.pending = true
-	m.streamingText = "Done."
+	m.streamingText = []byte("Done.")
 	m.transcript = append(m.transcript,
 		transcriptRow{kind: rowUser, text: "run it"},
 		transcriptRow{kind: rowAssistant, text: "I'll run it first."},
 		transcriptRow{kind: rowToolResult, id: "t1", tool: "bash", status: tools.StatusOK, detail: "stdout:\nok\nexit_code: 0"},
 	)
-	items := m.transcriptBodyItems(m.chatColumnWidth(), "")
+	items := m.transcriptBodyItems(m.chatColumnWidth(), "", false)
 	pendingIdx := -1
 	for i := range items {
 		if items[i].kind == transcriptBodyItemPendingInterim {
@@ -2357,7 +2357,7 @@ func TestTranscriptBodyRowsUseFullWidthAndAlignSelection(t *testing.T) {
 		t.Fatalf("expected no body gutter at width %d, got %d", width, gutter)
 	}
 
-	items := m.transcriptBodyItems(width, "")
+	items := m.transcriptBodyItems(width, "", false)
 	var row *transcriptBodyItem
 	for i := range items {
 		if items[i].kind == transcriptBodyItemRow && items[i].rowIndex >= 0 {

internal/tui/mouse.go

@@ -1,6 +1,36 @@
 package tui
 
-import tea "charm.land/bubbletea/v2"
+import (
+	"os"
+	"strings"
+	"sync"
+
+	tea "charm.land/bubbletea/v2"
+)
+
+// parseTracerPid returns true when /proc/self/status contains a non-zero
+// TracerPid. This detects any ptrace tracer (PRoot, gdb, strace, dlv, etc.),
+// not PRoot specifically. That's intentional: under any ptrace tracer the
+// AllMotion (1003) sequence is unreliable, so CellMotion is the safer
+// fallback. The only loss is hover-highlighting, which has no functional
+// impact.
+func parseTracerPid(data []byte) bool {
+	for _, line := range strings.Split(string(data), "\n") {
+		if strings.HasPrefix(line, "TracerPid:") {
+			pid := strings.TrimSpace(line[10:])
+			return pid != "0"
+		}
+	}
+	return false
+}
+
+var isRunningUnderPRoot = sync.OnceValue(func() bool {
+	data, err := os.ReadFile("/proc/self/status")
+	if err != nil {
+		return false
+	}
+	return parseTracerPid(data)
+})
 
 type mouseOverlayHit struct {
 	x int
@@ -257,7 +287,7 @@ func (m model) syncMouseCapture() (model, tea.Cmd) {
 }
 
 func (m model) mouseOverComposer(msg tea.MouseMsg) bool {
-	if !m.altScreen || m.height <= 0 {
+	if !m.altScreen || m.height <= 0 || m.transcriptDetailed {
 		return false
 	}
 	width := m.chatColumnWidth()

internal/tui/mouse_test.go

@@ -920,6 +920,30 @@ func TestMouseCaptureOnlyDuringInteractiveSetupStages(t *testing.T) {
 	}
 }
 
+// TestComposerMouseSelectionBlockedInDetailedMode: composer mouse hit-testing
+// is disabled while the detailed transcript view is active, so wheel and click
+// events in the composer area reach the transcript body instead.
+func TestComposerMouseSelectionBlockedInDetailedMode(t *testing.T) {
+	m := mouseTestModel()
+	m.input.SetValue("some text")
+
+	updated, _ := m.Update(testKeyCtrl('o'))
+	m = updated.(model)
+
+	if !m.transcriptDetailed {
+		t.Fatal("sanity check: Ctrl+O should enter detailed mode")
+	}
+	if !m.composerMouseSelectionBlocked() {
+		t.Fatal("composerMouseSelectionBlocked should be true in detailed mode")
+	}
+
+	width := m.chatColumnWidth()
+	frame := m.scrollableTranscriptFrame(m.pinnedTitleBar(width), m.footerView(width))
+	if m.mouseOverComposer(testMouseWheel(tea.MouseWheelUp, 0, frame.composerRect.y)) {
+		t.Fatal("mouseOverComposer should return false in detailed mode")
+	}
+}
+
 func firstTranscriptTextMouseY(t *testing.T, m model) int {
 	t.Helper()
 	_, y := firstTranscriptTextMousePoint(t, m)
@@ -986,6 +1010,38 @@ func withSidebarContent(m model) model {
 	return m
 }
 
+func TestParseTracerPidMissing(t *testing.T) {
+	if got := parseTracerPid([]byte("Pid: 123\nName: foo\n")); got {
+		t.Fatal("missing TracerPid should return false")
+	}
+}
+
+func TestParseTracerPidZero(t *testing.T) {
+	if got := parseTracerPid([]byte("TracerPid: 0\nName: foo\n")); got {
+		t.Fatal("TracerPid: 0 should return false")
+	}
+}
+
+func TestParseTracerPidNonZero(t *testing.T) {
+	if got := parseTracerPid([]byte("Name: foo\nTracerPid: 42\n")); !got {
+		t.Fatal("TracerPid: 42 should return true")
+	}
+}
+
+func TestParseTracerPidMalformed(t *testing.T) {
+	// Non-numeric values are treated as non-zero since any non-"0" string
+	// indicates a tracer is attached, matching the function's semantics.
+	if got := parseTracerPid([]byte("TracerPid: abc\n")); !got {
+		t.Fatal("malformed TracerPid should return true (non-zero string)")
+	}
+}
+
+func TestParseTracerPidEmpty(t *testing.T) {
+	if got := parseTracerPid([]byte{}); got {
+		t.Fatal("empty input should return false")
+	}
+}
+
 func setupMouseTestModel() model {
 	m := newModel(context.Background(), Options{
 		Setup: SetupOptions{

internal/tui/new_session_test.go

@@ -20,6 +20,10 @@ func TestStartNewSessionResetsState(t *testing.T) {
 	m.pendingImageLabels = []string{"pic.png"}
 	m.pendingDocuments = []pendingDocument{{label: "doc.pdf"}}
 	m.queuedMessage = "queued"
+	// The /retry attachment snapshot is prior-session state too and must not survive.
+	m.lastImages = make([]zeroruntime.ImageBlock, 1)
+	m.lastImageLabels = []string{"pic.png"}
+	m.lastDocuments = []pendingDocument{{label: "doc.pdf"}}
 
 	next := m.startNewSession()
 
@@ -41,6 +45,11 @@ func TestStartNewSessionResetsState(t *testing.T) {
 		t.Fatalf("startNewSession must clear staged input, got images=%d labels=%d docs=%d queued=%q",
 			len(next.pendingImages), len(next.pendingImageLabels), len(next.pendingDocuments), next.queuedMessage)
 	}
+	// The /retry snapshot must not leak the previous session's attachments.
+	if len(next.lastImages) != 0 || len(next.lastImageLabels) != 0 || len(next.lastDocuments) != 0 {
+		t.Fatalf("startNewSession must clear the retry snapshot, got images=%d labels=%d docs=%d",
+			len(next.lastImages), len(next.lastImageLabels), len(next.lastDocuments))
+	}
 }
 
 func TestNewCommandStartsFreshSession(t *testing.T) {

internal/tui/onboarding.go

@@ -1151,6 +1151,29 @@ func (m model) setupProvider() SetupProviderOption {
 	return m.setup.providers[index]
 }
 
+// setupErrorAffordance returns a faint one-line recovery hint tailored to the
+// current setup stage, so a first-run error points the user at the inline fix
+// instead of leaving them staring at a red line. Empty for stages whose footer
+// already makes recovery obvious. Each hint names only keys the stage's footer
+// confirms, so the guidance is always accurate.
+func (m model) setupErrorAffordance() string {
+	switch m.setup.stage {
+	case setupStageEndpoint:
+		return "→ edit the endpoint above, then Enter to retry (← to go back)"
+	case setupStageCredentials:
+		if m.setupCredentialInputActive() {
+			return "→ re-enter the key above, then Enter to retry (← to go back)"
+		}
+	case setupStageName:
+		return "→ edit the name above, then Enter to continue (← to go back)"
+	case setupStageModel:
+		if !m.setup.modelLoad {
+			return "→ pick another model with ↑/↓, or type to search"
+		}
+	}
+	return ""
+}
+
 func (m model) setupView(width int) string {
 	if width <= 0 {
 		width = defaultStartupWidth
@@ -1159,6 +1182,9 @@ func (m model) setupView(width int) string {
 	content := m.setupStageLines(width, height)
 	if m.setup.err != "" {
 		content = append(content, "", zeroTheme.red.Render("error: "+m.setup.err))
+		if hint := m.setupErrorAffordance(); hint != "" {
+			content = append(content, zeroTheme.faint.Render(hint))
+		}
 	}
 	progress := m.setupProgressText()
 	footer := m.setupFooter()

internal/tui/onboarding_affordance_test.go

@@ -0,0 +1,29 @@
+package tui
+
+import (
+	"strings"
+	"testing"
+)
+
+// Each input/choice stage's error affordance names an accurate recovery step;
+// stages without a tailored hint return empty.
+func TestSetupErrorAffordance(t *testing.T) {
+	endpoint := model{}
+	endpoint.setup.stage = setupStageEndpoint
+	if got := endpoint.setupErrorAffordance(); !strings.Contains(got, "endpoint") || !strings.Contains(got, "Enter") {
+		t.Fatalf("endpoint affordance = %q", got)
+	}
+
+	name := model{}
+	name.setup.stage = setupStageName
+	if got := name.setupErrorAffordance(); !strings.Contains(got, "name") {
+		t.Fatalf("name affordance = %q", got)
+	}
+
+	// A stage with no tailored hint (method chooser) returns empty.
+	method := model{}
+	method.setup.stage = setupStageMethod
+	if got := method.setupErrorAffordance(); got != "" {
+		t.Fatalf("method stage should have no affordance, got %q", got)
+	}
+}

internal/tui/options.go

@@ -13,6 +13,7 @@ import (
 	"github.com/Gitlawb/zero/internal/providermodeldiscovery"
 	"github.com/Gitlawb/zero/internal/sandbox"
 	"github.com/Gitlawb/zero/internal/sessions"
+	"github.com/Gitlawb/zero/internal/skills"
 	"github.com/Gitlawb/zero/internal/tools"
 	"github.com/Gitlawb/zero/internal/usage"
 	"github.com/Gitlawb/zero/internal/zeroruntime"
@@ -48,7 +49,13 @@ type Options struct {
 	SessionCompactor            SessionCompactor
 	PrService                   *PrService
 
-	AgentOptions    agent.Options
+	AgentOptions agent.Options
+	// LoadSkills returns the installed skills (default skills dir merged with any
+	// plugin skill roots), bodies included, for /skills and direct /<skill-name>
+	// invocation. Called lazily per use so newly installed skills are picked up
+	// without a restart. Nil means the session has no skills wiring (skills stay
+	// model-pulled via the skill tool only).
+	LoadSkills      func() []skills.Skill
 	PermissionMode  agent.PermissionMode
 	ReasoningEffort modelregistry.ReasoningEffort
 	ResponseStyle   string

internal/tui/permission_prompt_test.go

@@ -309,3 +309,70 @@ func TestPermissionRenderShowsNetworkTargetAndHostScopedAlways(t *testing.T) {
 		t.Fatalf("network prompt should render target label, got %q", got)
 	}
 }
+
+// TestPermissionCursorCtrlU ensures Ctrl+U moves the permission cursor UP
+// (toward the first option). Regression: the original implementation moved
+// the cursor DOWN on Ctrl+U and UP on Ctrl+D.
+func TestPermissionCursorCtrlU(t *testing.T) {
+	m := pendingPermissionModel(t, func(agent.PermissionDecision) {})
+	m.pendingPermission.cursor = 2 // middle option
+
+	updated, _ := m.Update(testKeyCtrl('u'))
+	next := updated.(model)
+	if next.pendingPermission.cursor != 1 {
+		t.Fatalf("Ctrl+U moved cursor to %d, want 1 (one step up)", next.pendingPermission.cursor)
+	}
+}
+
+// TestPermissionCursorCtrlD ensures Ctrl+D moves the permission cursor DOWN
+// (toward the last option). Regression: the original implementation moved
+// the cursor UP on Ctrl+D and DOWN on Ctrl+U.
+func TestPermissionCursorCtrlD(t *testing.T) {
+	m := pendingPermissionModel(t, func(agent.PermissionDecision) {})
+	m.pendingPermission.cursor = 0 // first option
+
+	updated, _ := m.Update(testKeyCtrl('d'))
+	next := updated.(model)
+	if next.pendingPermission.cursor != 1 {
+		t.Fatalf("Ctrl+D moved cursor to %d, want 1 (one step down)", next.pendingPermission.cursor)
+	}
+}
+
+// TestShiftUpComposerGuard ensures Shift+Up does NOT scroll the transcript
+// when the composer has text, so it falls through to the input's own line
+// navigation.
+func TestShiftUpComposerGuard(t *testing.T) {
+	m := mouseTestModel()
+	// Add enough transcript rows so scrolling is valid.
+	for i := 0; i < 20; i++ {
+		m.transcript = appendRow(m.transcript, rowAssistant, "line")
+	}
+	m.input.SetValue("some text")
+	m.chatScrollOffset = 5
+
+	updated, cmd := m.Update(testKeyShift(tea.KeyUp))
+	next := updated.(model)
+	_ = cmd
+	if got := next.chatScrollOffset; got != 5 {
+		t.Fatalf("Shift+Up with non-empty composer scrolled offset to %d, want 5 (unchanged)", got)
+	}
+}
+
+// TestShiftDownComposerGuard ensures Shift+Down does NOT scroll the transcript
+// when the composer has text, falling through to the input's navigation.
+func TestShiftDownComposerGuard(t *testing.T) {
+	m := mouseTestModel()
+	// Add enough transcript rows so scrolling is valid.
+	for i := 0; i < 20; i++ {
+		m.transcript = appendRow(m.transcript, rowAssistant, "line")
+	}
+	m.input.SetValue("some text")
+	m.chatScrollOffset = 3
+
+	updated, cmd := m.Update(testKeyShift(tea.KeyDown))
+	next := updated.(model)
+	_ = cmd
+	if got := next.chatScrollOffset; got != 3 {
+		t.Fatalf("Shift+Down with non-empty composer scrolled offset to %d, want 3 (unchanged)", got)
+	}
+}

internal/tui/picker.go

@@ -24,6 +24,7 @@ const (
 	pickerEffort
 	pickerSession
 	pickerTheme
+	pickerSkill
 )
 
 // pickerItem is one selectable row: Label is shown, Value is passed to the
@@ -102,16 +103,83 @@ func (p *commandPicker) applyQuery() {
 		p.selected = clampInt(p.selected, 0, maxInt(0, len(p.items)-1))
 		return
 	}
-	filtered := make([]pickerItem, 0, len(source))
-	for _, item := range source {
-		if strings.Contains(strings.ToLower(strings.Join([]string{item.Group, item.Label, item.Value, item.Meta}, " ")), query) {
-			filtered = append(filtered, item)
+
+	// Rank matches (exact < prefix < contains < subsequence) instead of a flat
+	// substring filter, so the closest match to "sonnet 4.5" lands at the top
+	// rather than buried behind scrolling. Groups stay contiguous — a group is
+	// ordered by its best-matching item and never split into two header blocks —
+	// so the grouped model picker still renders one header per provider.
+	type entry struct {
+		item  pickerItem
+		score int
+		order int
+	}
+	groupFirst := map[string]int{}
+	groupBest := map[string]int{}
+	entries := make([]entry, 0, len(source))
+	for index, item := range source {
+		score, ok := scorePickerItem(item, query)
+		if !ok {
+			continue
 		}
+		if _, seen := groupFirst[item.Group]; !seen {
+			groupFirst[item.Group] = index
+		}
+		if best, seen := groupBest[item.Group]; !seen || score < best {
+			groupBest[item.Group] = score
+		}
+		entries = append(entries, entry{item: item, score: score, order: index})
+	}
+	sort.SliceStable(entries, func(a, b int) bool {
+		ga, gb := entries[a].item.Group, entries[b].item.Group
+		if ga != gb {
+			// Most-relevant group first; ties keep original group appearance order so
+			// a group is never scattered across the list.
+			if groupBest[ga] != groupBest[gb] {
+				return groupBest[ga] < groupBest[gb]
+			}
+			return groupFirst[ga] < groupFirst[gb]
+		}
+		// Within a group: best match first, then original order.
+		if entries[a].score != entries[b].score {
+			return entries[a].score < entries[b].score
+		}
+		return entries[a].order < entries[b].order
+	})
+	filtered := make([]pickerItem, 0, len(entries))
+	for _, e := range entries {
+		filtered = append(filtered, e.item)
 	}
 	p.items = filtered
 	p.selected = 0
 }
 
+// scorePickerItem ranks an item against a lowercased query; lower is better, and
+// ok is false when it doesn't match at all. Tiers mirror scoreFileSuggestion:
+// exact/prefix/contains on the label (what the user reads) beat matches deeper in
+// the joined haystack, and a fuzzy subsequence is the last-resort match.
+func scorePickerItem(item pickerItem, query string) (int, bool) {
+	label := strings.ToLower(item.Label)
+	hay := strings.ToLower(strings.Join([]string{item.Group, item.Label, item.Value, item.Meta}, " "))
+	switch {
+	case label == query:
+		return 0, true
+	case strings.HasPrefix(label, query):
+		return 20, true
+	case strings.Contains(label, query):
+		return 40, true
+	case strings.HasPrefix(hay, query):
+		return 60, true
+	case strings.Contains(hay, query):
+		return 80, true
+	default:
+		if gap, ok := fuzzySubsequenceGap(hay, query); ok {
+			return 120 + gap, true
+		}
+		return 0, false
+	}
+}
+
 // newModelPicker lists active (non-deprecated) models, preselecting the active
 // one. Returns nil when the catalog is unavailable so the caller falls back to
 // the plain status text.
@@ -158,6 +226,35 @@ func (m model) newModelPicker() *commandPicker {
 	return &commandPicker{kind: pickerModel, title: "Choose a model", items: items, allItems: append([]pickerItem{}, items...), selected: 0}
 }
 
+// newSkillPicker lists the installed skills for browse-and-run: type to filter,
+// arrow keys to select, Enter runs the chosen skill immediately. Selection is by
+// the skill's EXACT name (item.Value), so even skills the slash path cannot
+// reach — names shadowed by a builtin or user command, or names that don't fit
+// a slash token — are runnable here: picking from the Skills picker is
+// unambiguous. Returns nil when no skills are installed (the caller falls back
+// to the install-hint card).
+func (m model) newSkillPicker() *commandPicker {
+	installed := m.installedSkills()
+	items := make([]pickerItem, 0, len(installed))
+	for _, skill := range installed {
+		name := strings.TrimSpace(skill.Name)
+		if name == "" {
+			continue
+		}
+		label := name
+		if slash := skillSlashName(name); slash != "" {
+			// Show the slash form where one exists — it doubles as documentation
+			// of the direct "/name [args]" invocation.
+			label = "/" + slash
+		}
+		items = append(items, pickerItem{Label: label, Value: name, Meta: strings.TrimSpace(skill.Description)})
+	}
+	if len(items) == 0 {
+		return nil
+	}
+	return &commandPicker{kind: pickerSkill, title: "pick a skill · ⏎ fills /name — add your request", items: items, allItems: append([]pickerItem{}, items...), selected: 0}
+}
+
 // modelPickerProviders returns the providers to list in /model: all saved
 // providers, falling back to the active profile when none were threaded in.
 func (m model) modelPickerProviders() []config.ProviderProfile {

internal/tui/picker_fuzzy_test.go

@@ -0,0 +1,72 @@
+package tui
+
+import (
+	"testing"
+)
+
+func newFuzzyTestPicker(items []pickerItem) *commandPicker {
+	return &commandPicker{
+		kind:     pickerModel,
+		items:    append([]pickerItem{}, items...),
+		allItems: append([]pickerItem{}, items...),
+	}
+}
+
+// A closer match ranks above a merely-containing one, so the best result lands at
+// the top instead of in original order.
+func TestPickerRanksBestMatchFirst(t *testing.T) {
+	p := newFuzzyTestPicker([]pickerItem{
+		{Label: "Claude Opus 4.5", Value: "opus-4.5"},
+		{Label: "Claude Sonnet 4.5", Value: "sonnet-4.5"},
+		{Label: "Sonnet", Value: "sonnet"}, // exact-ish prefix match should win
+	})
+	p.query = "sonnet"
+	p.applyQuery()
+
+	if len(p.items) != 2 {
+		t.Fatalf("expected 2 matches for 'sonnet', got %d: %#v", len(p.items), p.items)
+	}
+	if p.items[0].Value != "sonnet" {
+		t.Fatalf("exact/prefix match should rank first, got %q", p.items[0].Value)
+	}
+}
+
+// A subsequence query (non-contiguous characters) still matches when no substring does.
+func TestPickerFuzzySubsequenceMatches(t *testing.T) {
+	p := newFuzzyTestPicker([]pickerItem{
+		{Label: "Claude Sonnet 4.5", Value: "sonnet-4.5"},
+		{Label: "GPT-5", Value: "gpt-5"},
+	})
+	p.query = "snt45" // subsequence of "sonnet 4.5", not a substring
+	p.applyQuery()
+
+	if len(p.items) != 1 || p.items[0].Value != "sonnet-4.5" {
+		t.Fatalf("subsequence query should match sonnet-4.5, got %#v", p.items)
+	}
+}
+
+// Ranking keeps each group contiguous: a filtered result never splits one group
+// into two separate blocks, so group headers still render once per group.
+func TestPickerRankingKeepsGroupsContiguous(t *testing.T) {
+	p := newFuzzyTestPicker([]pickerItem{
+		{Group: "openai", Label: "gpt-5 mini", Value: "a"},
+		{Group: "anthropic", Label: "sonnet 4.5", Value: "b"},
+		{Group: "openai", Label: "gpt-5 codex", Value: "c"},
+		{Group: "anthropic", Label: "opus 4.5", Value: "d"},
+	})
+	p.query = "5" // matches both openai models and the "4.5" anthropic ones
+	p.applyQuery()
+
+	// Every item's group must appear as one contiguous run.
+	seen := map[string]bool{}
+	last := ""
+	for _, item := range p.items {
+		if item.Group != last {
+			if seen[item.Group] {
+				t.Fatalf("group %q split into non-contiguous blocks: %#v", item.Group, p.items)
+			}
+			seen[item.Group] = true
+			last = item.Group
+		}
+	}
+}

internal/tui/rendering.go

@@ -987,6 +987,12 @@ func isDoctorResultHeading(value string) bool {
 
 func renderErrorRow(row transcriptRow, width int) string {
 	note := noteBox(row.text, width, zeroTheme.cardErr, zeroTheme.red)
+	// A recognized failure carries a one-line next step. Render it just below the
+	// red box in the faint metadata style so it reads as guidance, not more error
+	// text (and to avoid nesting ANSI styles inside noteBox's per-line red wrap).
+	if hint := strings.TrimSpace(row.hint); hint != "" {
+		note += "\n" + fitStyledLine(zeroTheme.faint.Render("→ "+hint), width)
+	}
 	return note
 }
 

internal/tui/rendering_lime_test.go

@@ -224,14 +224,14 @@ func TestCommandCardRowTrimsIndentedActionsLabel(t *testing.T) {
 func TestInterimBlockShowsStreamingTextWithCursor(t *testing.T) {
 	m := limeTestModel()
 	m.pending = true
-	m.streamingText = "I'll add a --version flag"
+	m.streamingText = []byte("I'll add a --version flag")
 	got := plainRender(t, m.interimBlock(96))
 	if !strings.Contains(got, "I'll add a --version flag") || !strings.Contains(got, "▌") {
 		t.Fatalf("interim block = %q, want streamed text with trailing cursor", got)
 	}
 
 	// Before the first delta the block falls back to the liveness spinner.
-	m.streamingText = ""
+	m.streamingText = nil
 	if got := plainRender(t, m.interimBlock(96)); !strings.Contains(got, "Working") {
 		t.Fatalf("empty interim block = %q, want the liveness label", got)
 	}
@@ -240,13 +240,13 @@ func TestInterimBlockShowsStreamingTextWithCursor(t *testing.T) {
 func TestInterimBlockRendersStreamingMarkdownTable(t *testing.T) {
 	m := limeTestModel()
 	m.pending = true
-	m.streamingText = strings.Join([]string{
+	m.streamingText = []byte(strings.Join([]string{
 		"Here's the comparison:",
 		"",
 		"| Category | System A | System B |",
 		"|---|---|---|",
 		"| **Label** | Alpha | Beta |",
-	}, "\n")
+	}, "\n"))
 
 	rendered := m.interimBlock(72)
 	got := plainRender(t, rendered)
@@ -511,6 +511,50 @@ func TestSelectableAssistantRowKeepsMarkdownSemanticsPlain(t *testing.T) {
 	}
 }
 
+func TestStripMarkdownRenderControlsStripsAllANSI(t *testing.T) {
+	// Bold markers that renderAssistantMarkdownText embeds for prose formatting.
+	withBold := "\x1b[1mhello\x1b[22m world"
+	if got := stripMarkdownRenderControls(withBold); got != "hello world" {
+		t.Fatalf("stripMarkdownRenderControls(%q) = %q, want %q", withBold, got, "hello world")
+	}
+	// Color sequences from highlightCodeAuto for fenced code blocks.
+	withColor := "\x1b[38;2;236;236;238mdef\x1b[0m hello():"
+	if got := stripMarkdownRenderControls(withColor); got != "def hello():" {
+		t.Fatalf("stripMarkdownRenderControls(%q) = %q, want %q", withColor, got, "def hello():")
+	}
+	// Sequences that combine both (bold + underline + color).
+	withBoldColor := "\x1b[1;4;38;2;236;236;238mW\x1b[m"
+	if got := stripMarkdownRenderControls(withBoldColor); got != "W" {
+		t.Fatalf("stripMarkdownRenderControls(%q) = %q, want %q", withBoldColor, got, "W")
+	}
+}
+
+func TestSelectedTranscriptTextStripsANSIFromHighlightedCode(t *testing.T) {
+	m := limeTestModel()
+	m.width, m.height = 120, 40
+	m.altScreen = true
+	m.headerPrinted = true
+	code := `package main
+
+import "fmt"
+
+func main() {
+	fmt.Println("hello")
+}`
+	row := transcriptRow{kind: rowAssistant, text: "First, here's the code:\n\n```go\n" + code + "\n```\n\nThat's it.", final: true}
+	m.transcript = append(m.transcript, row)
+	m.flushed = len(m.transcript)
+
+	// The highlighted code block contains ANSI color sequences from chroma;
+	// verify none survive in the selectable text used for clipboard copy.
+	_, selectable := m.renderSelectableAssistantRow(0, row, 72, 0)
+	for _, line := range selectable {
+		if ansiPattern.MatchString(line.text) {
+			t.Fatalf("selectable text leaked ANSI escapes: %q", line.text)
+		}
+	}
+}
+
 func TestFinalAnswerRendersPlainTextAndCompletionLine(t *testing.T) {
 	m := limeTestModel()
 	row := transcriptRow{
@@ -1528,10 +1572,10 @@ func TestCancelRunClearsStreamingText(t *testing.T) {
 	m := limeTestModel()
 	m.pending = true
 	m.activeRunID = 3
-	m.streamingText = "partial answer from a doomed run"
+	m.streamingText = []byte("partial answer from a doomed run")
 	m.cancelRun()
-	if m.streamingText != "" {
-		t.Fatalf("cancelRun must clear streamingText, got %q", m.streamingText)
+	if len(m.streamingText) != 0 {
+		t.Fatalf("cancelRun must clear streamingText, got %q", string(m.streamingText))
 	}
 }
 

internal/tui/resume_scope_test.go

@@ -0,0 +1,31 @@
+package tui
+
+import (
+	"runtime"
+	"testing"
+)
+
+func TestSessionMatchesWorkspace(t *testing.T) {
+	cases := []struct {
+		name        string
+		sessionCwd  string
+		workspace   string
+		wantVisible bool
+	}{
+		{"same workspace", "/home/u/proj", "/home/u/proj", true},
+		{"trailing slash normalizes", "/home/u/proj/", "/home/u/proj", true},
+		{"different workspace hidden", "/home/u/other", "/home/u/proj", false},
+		{"session with no cwd stays visible", "", "/home/u/proj", true},
+		{"unknown current workspace keeps all", "/home/u/other", "", true},
+		// Casing: matched case-insensitively on Windows (its FS is), case-sensitively
+		// elsewhere. This exercises the platform-specific branch on each OS's CI.
+		{"case differs only", "/home/U/Proj", "/home/u/proj", runtime.GOOS == "windows"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := sessionMatchesWorkspace(tc.sessionCwd, tc.workspace); got != tc.wantVisible {
+				t.Fatalf("sessionMatchesWorkspace(%q, %q) = %v, want %v", tc.sessionCwd, tc.workspace, got, tc.wantVisible)
+			}
+		})
+	}
+}

internal/tui/retry_edit_test.go

@@ -0,0 +1,96 @@
+package tui
+
+import (
+	"context"
+	"testing"
+
+	tea "charm.land/bubbletea/v2"
+
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+func TestCommandsRegistered(t *testing.T) {
+	for _, name := range []string{"/retry", "/edit", "/copy", "/export"} {
+		if cmd, ok := resolveCommand(name); !ok {
+			t.Fatalf("%s should be a registered command", name)
+		} else if cmd.name != name {
+			t.Fatalf("resolveCommand(%q) = %q", name, cmd.name)
+		}
+	}
+}
+
+// /edit recalls the last prompt into the composer for editing.
+func TestEditRecallsLastPrompt(t *testing.T) {
+	m := newModel(context.Background(), Options{})
+	m.lastPrompt = "refactor the parser"
+	m.input.SetValue("/edit")
+
+	updated, _ := m.Update(testKey(tea.KeyEnter))
+	next := updated.(model)
+
+	if got := next.composerValue(); got != "refactor the parser" {
+		t.Fatalf("/edit should recall last prompt into composer, got %q", got)
+	}
+}
+
+// /edit must re-stage the remembered attachments alongside the recalled text, so an
+// edited resend of a vision/PDF-backed prompt carries the same image/document
+// context instead of silently sending a text-only version.
+func TestEditRestagesAttachments(t *testing.T) {
+	m := newModel(context.Background(), Options{ModelName: "gpt-4.1"})
+	m.lastPrompt = "describe the diagram"
+	m.lastImages = []zeroruntime.ImageBlock{{MediaType: "image/png"}}
+	m.lastImageLabels = []string{"diagram.png"}
+	m.lastDocuments = []pendingDocument{{label: "spec.pdf", text: "notes"}}
+	m.input.SetValue("/edit")
+
+	updated, _ := m.Update(testKey(tea.KeyEnter))
+	next := updated.(model)
+
+	if got := next.composerValue(); got != "describe the diagram" {
+		t.Fatalf("/edit should recall the prompt text, got %q", got)
+	}
+	if len(next.pendingImages) != 1 || len(next.pendingImageLabels) != 1 || next.pendingImageLabels[0] != "diagram.png" {
+		t.Fatalf("/edit should re-stage the remembered image, got imgs=%d labels=%v",
+			len(next.pendingImages), next.pendingImageLabels)
+	}
+	if len(next.pendingDocuments) != 1 || next.pendingDocuments[0].label != "spec.pdf" {
+		t.Fatalf("/edit should re-stage the remembered document, got %#v", next.pendingDocuments)
+	}
+}
+
+// /retry with no prior prompt reports that there's nothing to resend rather than
+// launching an empty run.
+func TestRetryWithoutPriorPromptIsNoOp(t *testing.T) {
+	m := newModel(context.Background(), Options{})
+	m.input.SetValue("/retry")
+
+	updated, _ := m.Update(testKey(tea.KeyEnter))
+	next := updated.(model)
+
+	if !transcriptContains(next.transcript, "no previous prompt") {
+		t.Fatalf("/retry with no history should note there's nothing to resend, got %#v", next.transcript)
+	}
+}
+
+// /retry must not launch a run while compaction is rewriting session state — the
+// same guard a normal prompt has.
+func TestRetryBlockedDuringCompaction(t *testing.T) {
+	m := newModel(context.Background(), Options{})
+	m.lastPrompt = "do the thing"
+	m.compactInFlight = true
+	m.input.SetValue("/retry")
+
+	updated, cmd := m.Update(testKey(tea.KeyEnter))
+	next := updated.(model)
+
+	if next.pending {
+		t.Fatal("/retry must not start a run during compaction")
+	}
+	if cmd != nil {
+		t.Fatal("/retry during compaction must not return a run command")
+	}
+	if !transcriptContains(next.transcript, "Compaction is running") {
+		t.Fatalf("/retry during compaction should warn, got %#v", next.transcript)
+	}
+}

internal/tui/run.go

@@ -25,7 +25,7 @@ func Run(ctx context.Context, options Options) int {
 
 	externalSink := options.RuntimeMessageSink
 	var program *tea.Program
-	options.RuntimeMessageSink = func(msg tea.Msg) {
+	forward := func(msg tea.Msg) {
 		if externalSink != nil {
 			externalSink(msg)
 		}
@@ -33,6 +33,10 @@ func Run(ctx context.Context, options Options) int {
 			program.Send(msg)
 		}
 	}
+	// Coalesce streamed assistant-text deltas to ~one frame each so a fast provider
+	// can't drive a full Update→View per token; every other message flushes pending
+	// text first, keeping order intact.
+	options.RuntimeMessageSink = newTextCoalescer(forward).send
 	options.AltScreen = useAltScreen(options)
 
 	programOpts := []tea.ProgramOption{

internal/tui/session.go

@@ -4,6 +4,8 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"path/filepath"
+	"runtime"
 	"strings"
 	"time"
 
@@ -80,6 +82,12 @@ func (m model) startNewSession() model {
 	m.pendingImageLabels = nil
 	m.pendingDocuments = nil
 	m.queuedMessage = ""
+	// The remembered /retry attachment snapshot belongs to the previous session
+	// too — dropping it keeps a post-/new /retry from re-staging old images or
+	// documents. lastPrompt is composer history (like inputHistory) and stays.
+	m.lastImages = nil
+	m.lastImageLabels = nil
+	m.lastDocuments = nil
 
 	note := "Started a new session."
 	if previousID != "" {
@@ -220,9 +228,11 @@ func (m model) sessionPrompt(prompt string) string {
 
 func (m model) resolveResumeSession(args string) (*sessions.Metadata, error) {
 	if strings.EqualFold(args, "latest") {
-		// Latest *resumable* conversation, so "latest" never lands on a child or
-		// spec sub-run. An explicit `/resume <id>` below still resolves any session.
-		latest, err := m.sessionStore.LatestResumable()
+		// Latest *resumable* conversation IN THIS WORKSPACE, so "latest" never lands
+		// on a child, a spec sub-run, or a session from another project (matching the
+		// workspace-scoped picker). An explicit `/resume <id>` below still resolves
+		// any session regardless of workspace.
+		latest, err := m.latestResumableInWorkspace()
 		if err != nil {
 			return nil, err
 		}
@@ -321,6 +331,18 @@ func (m model) newSessionPicker() *commandPicker {
 	now := m.now()
 	items := make([]pickerItem, 0, len(metas))
 	for _, meta := range metas {
+		// Workspace-scoped: hide sessions from other project directories so /resume
+		// lists this workspace's history, not every project's. Checked BEFORE the
+		// per-session event read below, so a large global history doesn't pay 50
+		// full file reads to build one workspace's list. Sessions with no recorded
+		// Cwd (older runs) stay visible rather than vanishing.
+		if !sessionMatchesWorkspace(meta.Cwd, m.cwd) {
+			continue
+		}
+		// A zero-event session has nothing to resume — skip it without a file read.
+		if meta.EventCount == 0 {
+			continue
+		}
 		// Skip empty/failed runs (no assistant output, no tool calls) — e.g. the
 		// same prompt retried while the model wasn't responding. They have nothing
 		// to resume and otherwise flood the list with identical rows. Still on disk.
@@ -356,6 +378,52 @@ func (m model) newSessionPicker() *commandPicker {
 // resuming: a tool call/result, or a non-user message with real content (not the
 // no-output guardrail stop). Empty/failed runs return false and are hidden from
 // the picker (they stay on disk). Errors fail open (the session is kept).
+// latestResumableInWorkspace returns the most-recently-updated resumable session
+// belonging to the current workspace, or nil when none exist. ListResumable is
+// ordered latest-first, so the first qualifying match is the latest. It applies
+// the SAME filters as newSessionPicker — workspace membership, non-empty
+// metadata, and real resumable content — so `/resume latest` never lands on a
+// zero-event or empty/failed run the picker would have hidden.
+func (m model) latestResumableInWorkspace() (*sessions.Metadata, error) {
+	metas, err := m.sessionStore.ListResumable()
+	if err != nil {
+		return nil, err
+	}
+	for i := range metas {
+		if !sessionMatchesWorkspace(metas[i].Cwd, m.cwd) {
+			continue
+		}
+		if metas[i].EventCount == 0 {
+			continue
+		}
+		if !m.sessionHasResumableContent(metas[i].SessionID) {
+			continue
+		}
+		return &metas[i], nil
+	}
+	return nil, nil
+}
+
+// sessionMatchesWorkspace reports whether a session recorded in sessionCwd
+// belongs to the current workspaceCwd. A session with no recorded Cwd (older
+// runs) or an unknown current workspace is kept visible rather than filtered out,
+// so the scoping never hides history it can't confidently place elsewhere. On
+// Windows the comparison is case-insensitive, since the filesystem is and the
+// same workspace can be spelled with different casing (C:\Proj vs c:\proj).
+func sessionMatchesWorkspace(sessionCwd, workspaceCwd string) bool {
+	sessionCwd = strings.TrimSpace(sessionCwd)
+	workspaceCwd = strings.TrimSpace(workspaceCwd)
+	if sessionCwd == "" || workspaceCwd == "" {
+		return true
+	}
+	a := filepath.Clean(sessionCwd)
+	b := filepath.Clean(workspaceCwd)
+	if runtime.GOOS == "windows" {
+		return strings.EqualFold(a, b)
+	}
+	return a == b
+}
+
 func (m model) sessionHasResumableContent(sessionID string) bool {
 	events, err := m.sessionStore.ReadEvents(sessionID)
 	if err != nil {

internal/tui/session_controls.go

@@ -326,8 +326,10 @@ func (m model) handleCompactCommand(args string) (model, string, tea.Cmd) {
 	if args == "status" {
 		return m, m.compactText(false), nil
 	}
-	if args != "" {
-		return m, "Compact\nusage: /compact [status]", nil
+	// Bare "/compact" already triggers compaction; accept "now" too since that is
+	// what users reach for when they see the context gauge climbing.
+	if args != "" && args != "now" {
+		return m, "Compact\nusage: /compact [status|now]", nil
 	}
 	if m.compactInFlight {
 		return m, m.compactText(true), nil

internal/tui/sidebar.go

@@ -82,7 +82,7 @@ func (m model) sidebarToggleAllowed() bool {
 // would have any visible effect. The subchat drill-in keeps its own single-column
 // view, so the sidebar is suppressed there.
 func (m model) sidebarAvailable() bool {
-	if !m.altScreen || m.height <= 0 || m.subchat.active {
+	if !m.altScreen || m.height <= 0 || m.subchat.active || m.transcriptDetailed {
 		return false
 	}
 	if sidebarWidth(m.width) <= 0 {

internal/tui/skill_commands.go

@@ -0,0 +1,205 @@
+package tui
+
+import (
+	"strings"
+
+	tea "charm.land/bubbletea/v2"
+
+	"github.com/Gitlawb/zero/internal/skills"
+)
+
+// Skill slash invocation: "/<skill-name> [args]" runs an installed skill
+// directly, mirroring user commands (.zero/commands). Skills were previously
+// model-pulled only (the skill tool), which made invocation a matter of model
+// discretion; typing the skill's name makes it deterministic. Precedence is
+// builtin > user command > skill: parseCommand resolves builtins first, and the
+// commandUnknown fallback tries user commands before skills.
+
+// handleSkillCommand resolves a "/name args" that wasn't a builtin or a user
+// command against the installed skills. On a match it launches a normal agent
+// turn whose prompt inlines the skill body (its instructions) followed by the
+// typed args, returning handled=true. handled=false means no skill matched, so
+// the caller falls through to "unknown command".
+func (m model) handleSkillCommand(raw string) (model, tea.Cmd, bool) {
+	name, args := splitUserCommand(raw)
+	if name == "" {
+		return m, nil, false
+	}
+	skill, ok := m.lookupSkillCommand(name)
+	if !ok {
+		return m, nil, false
+	}
+	body := strings.TrimSpace(skill.Content)
+	if body == "" {
+		// The name matched a real skill, so falling through to "unknown command"
+		// would mislead; surface the actual problem instead.
+		m.transcript = reduceTranscript(m.transcript, transcriptAction{
+			kind: actionAppendError,
+			text: "skill /" + name + " has an empty SKILL.md body (" + skill.Path + ")",
+		})
+		return m, nil, true
+	}
+	return m.launchOrDeferExpandedPrompt(raw, skillInvocationPrompt(body, args))
+}
+
+// bareSkillInvocationNote is appended when a skill is invoked with no request.
+// The body alone is instructions with no target ("review the PR" — which PR?),
+// and without this note the model improvises one instead of asking. The wording
+// is conditional so self-contained skills (no target needed) still just run.
+const bareSkillInvocationNote = "The user invoked this skill directly without providing a request. " +
+	"If these instructions need a target or details that are not already clear from the conversation " +
+	"(which pull request, file, branch, topic, …), ask for them first — do not guess or pick one yourself. " +
+	"If the instructions are self-contained, proceed."
+
+// skillInvocationPrompt builds the agent prompt for a skill invocation: the
+// skill body (its instructions), then either the user's request or — for a bare
+// invocation — the ask-first note above. Mirrors usercommands.Expand's
+// no-placeholder behavior for the args case.
+func skillInvocationPrompt(body, args string) string {
+	if args != "" {
+		return body + "\n\n" + args
+	}
+	return body + "\n\n" + bareSkillInvocationNote
+}
+
+// launchOrDeferExpandedPrompt applies the same run-state guards the plain
+// commandPrompt path has to an expanded (user command / skill) prompt: while
+// exiting nothing may start, a prompt submitted mid-run is queued for the next
+// turn, and compaction-in-flight warns instead of racing the compactor. The
+// EXPANDED prompt is what gets queued — the queue flush path resubmits text as
+// a literal prompt, so queuing the raw "/name args" would send it to the model
+// as prose instead of re-dispatching it. raw is the typed invocation; on the
+// compaction warning it is restored into the composer for an easy re-submit
+// (the commandUnknown dispatch cleared the composer before we got here, unlike
+// the plain-prompt path whose guard fires before the clear). Empty raw (the
+// picker path has no typed form) restores nothing.
+func (m model) launchOrDeferExpandedPrompt(raw, prompt string) (model, tea.Cmd, bool) {
+	if m.exiting {
+		return m, nil, true
+	}
+	if m.pending {
+		return m.queueMessage(prompt), nil, true
+	}
+	if m.compactInFlight {
+		if strings.TrimSpace(raw) != "" {
+			m.input.SetValue(raw)
+			m.input.CursorEnd()
+		}
+		m.transcript = reduceTranscript(m.transcript, transcriptAction{
+			kind: actionAppendSystem,
+			text: "Compact\nstatus: warning\nCompaction is running. Re-run the command when it finishes.",
+		})
+		return m, nil, true
+	}
+	next, teaCmd := m.launchPrompt(prompt)
+	return next, teaCmd, true
+}
+
+// takenSlashNames returns every slash token already claimed by a builtin
+// command (or alias) or a user command — the names a typed "/x" would dispatch
+// to before ever reaching a skill.
+func (m model) takenSlashNames() map[string]bool {
+	taken := map[string]bool{}
+	for _, command := range commandDefinitions {
+		taken[strings.TrimPrefix(command.name, "/")] = true
+		for _, alias := range command.aliases {
+			taken[strings.TrimPrefix(alias, "/")] = true
+		}
+	}
+	for _, cmd := range m.userCommands {
+		taken[cmd.Name] = true
+	}
+	return taken
+}
+
+// chooseSkillFromPicker handles Enter on a skill-picker row. Most skills want a
+// request ("review WHICH pr?"), so selection fills the composer with
+// "/name " — cursor at the end — for the user to complete and submit (Enter
+// again runs it bare). Skills whose names cannot be typed as a slash command
+// (non-slash shapes, or names shadowed by a builtin or user command) fall back
+// to running immediately: the picker is the only path that reaches them, and an
+// unfillable composer would be a dead end.
+func (m model) chooseSkillFromPicker(item pickerItem) (model, tea.Cmd) {
+	slash := skillSlashName(item.Value)
+	if slash == "" || m.takenSlashNames()[slash] {
+		return m.invokeSkillByName(item.Value)
+	}
+	m.input.SetValue("/" + slash + " ")
+	m.input.CursorEnd()
+	return m, nil
+}
+
+// invokeSkillByName runs the installed skill with the given EXACT raw name (the
+// skill-picker path). The same run-state guards as slash invocation apply; the
+// picker offers no args affordance, so the prompt is the skill body alone.
+func (m model) invokeSkillByName(name string) (model, tea.Cmd) {
+	for _, skill := range m.installedSkills() {
+		if strings.TrimSpace(skill.Name) != name {
+			continue
+		}
+		body := strings.TrimSpace(skill.Content)
+		if body == "" {
+			m.transcript = reduceTranscript(m.transcript, transcriptAction{
+				kind: actionAppendError,
+				text: "skill " + name + " has an empty SKILL.md body (" + skill.Path + ")",
+			})
+			return m, nil
+		}
+		next, teaCmd, _ := m.launchOrDeferExpandedPrompt("", skillInvocationPrompt(body, ""))
+		return next, teaCmd
+	}
+	// The picker row came from a slightly older load (TTL cache) and the skill
+	// has since been removed.
+	m.transcript = reduceTranscript(m.transcript, transcriptAction{
+		kind: actionAppendError,
+		text: "skill " + name + " is no longer installed",
+	})
+	return m, nil
+}
+
+// lookupSkillCommand returns the installed skill whose slash name matches the
+// given (lowercased) name. Linear scan over a fresh load — skills are re-read
+// per invocation so a skill installed mid-session is invocable without a
+// restart, and the body is never held on the model.
+func (m model) lookupSkillCommand(name string) (skills.Skill, bool) {
+	name = strings.ToLower(strings.TrimSpace(name))
+	if name == "" {
+		return skills.Skill{}, false
+	}
+	for _, skill := range m.installedSkills() {
+		if skillSlashName(skill.Name) == name {
+			return skill, true
+		}
+	}
+	return skills.Skill{}, false
+}
+
+// installedSkills returns the session's installed skills (default dir merged
+// with plugin skill roots) via the injected loader, or nil when the session has
+// no skills wiring (e.g. bare test models).
+func (m model) installedSkills() []skills.Skill {
+	if m.loadSkills == nil {
+		return nil
+	}
+	return m.loadSkills()
+}
+
+// skillSlashName maps a skill's frontmatter name to its slash-command form:
+// lowercased, and only if it fits the slash-token shape (letters, digits,
+// dot/underscore/hyphen — a superset of user-command names, since skill names
+// are free-form frontmatter). Returns "" for names that cannot be typed as a
+// /command (e.g. containing spaces); those skills remain loadable by the model
+// via the skill tool and are still listed by /skills.
+func skillSlashName(name string) string {
+	name = strings.ToLower(strings.TrimSpace(name))
+	if name == "" {
+		return ""
+	}
+	for _, r := range name {
+		valid := (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '-' || r == '_' || r == '.'
+		if !valid {
+			return ""
+		}
+	}
+	return name
+}

internal/tui/skill_commands_test.go

@@ -0,0 +1,412 @@
+package tui
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	tea "charm.land/bubbletea/v2"
+
+	"github.com/Gitlawb/zero/internal/agent"
+	"github.com/Gitlawb/zero/internal/skills"
+)
+
+// newSkillTestModel builds a model with an injected skills loader (and the
+// matching palette metadata), no filesystem involved.
+func newSkillTestModel(t *testing.T, installed ...skills.Skill) model {
+	t.Helper()
+	infos := make([]agent.SkillInfo, 0, len(installed))
+	for _, s := range installed {
+		infos = append(infos, agent.SkillInfo{Name: s.Name, Description: s.Description})
+	}
+	return newModel(context.Background(), Options{
+		Cwd:          t.TempDir(),
+		LoadSkills:   func() []skills.Skill { return installed },
+		AgentOptions: agent.Options{Skills: infos},
+	})
+}
+
+func submitInput(t *testing.T, m model, input string) model {
+	t.Helper()
+	m.input.SetValue(input)
+	updated, _ := m.Update(testKey(tea.KeyEnter))
+	return updated.(model)
+}
+
+func TestSkillCommandInvokesAndSubmits(t *testing.T) {
+	m := newSkillTestModel(t, skills.Skill{
+		Name:        "deploy-checks",
+		Description: "Run the pre-deploy verification suite.",
+		Content:     "Run every verification step and summarize failures.",
+		Path:        "/skills/deploy-checks/SKILL.md",
+	})
+
+	next := submitInput(t, m, "/deploy-checks ship v2 to production")
+
+	if transcriptContains(next.transcript, "unknown command") {
+		t.Fatalf("an installed skill must not be 'unknown', got %#v", next.transcript)
+	}
+	if !transcriptContains(next.transcript, "Run every verification step and summarize failures.") {
+		t.Fatalf("skill body should be inlined into the prompt, got %#v", next.transcript)
+	}
+	if !transcriptContains(next.transcript, "ship v2 to production") {
+		t.Fatalf("typed args should follow the skill body, got %#v", next.transcript)
+	}
+}
+
+func TestSkillCommandWithoutArgs(t *testing.T) {
+	m := newSkillTestModel(t, skills.Skill{Name: "reviewer", Content: "Review the diff for correctness."})
+
+	next := submitInput(t, m, "/reviewer")
+
+	if !transcriptContains(next.transcript, "Review the diff for correctness.") {
+		t.Fatalf("bare skill invocation should submit the body, got %#v", next.transcript)
+	}
+	// A bare invocation carries the ask-first note: instructions with no target
+	// must make the model ask ("which PR?") instead of improvising one.
+	if !transcriptContains(next.transcript, "ask for them first") {
+		t.Fatalf("bare invocation should carry the clarify-first note, got %#v", next.transcript)
+	}
+}
+
+// An invocation WITH a request must not carry the ask-first note — the user
+// already said what to apply the skill to.
+func TestSkillCommandWithArgsHasNoClarifyNote(t *testing.T) {
+	m := newSkillTestModel(t, skills.Skill{Name: "reviewer", Content: "Review the diff."})
+
+	next := submitInput(t, m, "/reviewer PR 484 reconnect changes")
+
+	if transcriptContains(next.transcript, "ask for them first") {
+		t.Fatalf("args invocation must not carry the clarify note, got %#v", next.transcript)
+	}
+}
+
+// A skill's frontmatter name is free-form; invocation matches its lowercased
+// slash form.
+func TestSkillCommandNameIsCaseInsensitive(t *testing.T) {
+	m := newSkillTestModel(t, skills.Skill{Name: "Deploy-Checks", Content: "Check things."})
+
+	next := submitInput(t, m, "/deploy-checks")
+
+	if !transcriptContains(next.transcript, "Check things.") {
+		t.Fatalf("uppercase frontmatter name should be invocable lowercased, got %#v", next.transcript)
+	}
+}
+
+// Precedence: a user command (.zero/commands) shadows a same-named skill.
+func TestUserCommandShadowsSkill(t *testing.T) {
+	root := t.TempDir()
+	writeUserCommand(t, root, "greet.md", "Say hello from the user command.")
+	m := newModel(context.Background(), Options{
+		Cwd:        root,
+		LoadSkills: func() []skills.Skill { return []skills.Skill{{Name: "greet", Content: "Skill body must not run."}} },
+	})
+
+	next := submitInput(t, m, "/greet")
+
+	if !transcriptContains(next.transcript, "Say hello from the user command.") {
+		t.Fatalf("user command should win the name collision, got %#v", next.transcript)
+	}
+	if transcriptContains(next.transcript, "Skill body must not run.") {
+		t.Fatalf("shadowed skill must not run, got %#v", next.transcript)
+	}
+}
+
+// An empty skill body is a real, named match — surface the problem instead of
+// falling through to a misleading "unknown command".
+func TestSkillCommandEmptyBody(t *testing.T) {
+	m := newSkillTestModel(t, skills.Skill{Name: "hollow", Path: "/skills/hollow/SKILL.md"})
+
+	next := submitInput(t, m, "/hollow")
+
+	if transcriptContains(next.transcript, "unknown command") {
+		t.Fatalf("an empty skill must not be 'unknown', got %#v", next.transcript)
+	}
+	if !transcriptContains(next.transcript, "empty SKILL.md body") {
+		t.Fatalf("empty-body error should be surfaced, got %#v", next.transcript)
+	}
+}
+
+func TestUnknownSlashStillUnknownWithSkillsInstalled(t *testing.T) {
+	m := newSkillTestModel(t, skills.Skill{Name: "reviewer", Content: "Review."})
+
+	next := submitInput(t, m, "/definitelynotaskill")
+
+	if !transcriptContains(next.transcript, "unknown command") {
+		t.Fatalf("non-matching name should still be unknown, got %#v", next.transcript)
+	}
+}
+
+func TestSkillSlashName(t *testing.T) {
+	cases := map[string]string{
+		"deploy-checks":  "deploy-checks",
+		"Deploy-Checks":  "deploy-checks",
+		"  pdf_tools  ":  "pdf_tools",
+		"v2.migrate":     "v2.migrate",
+		"has space":      "",
+		"emoji✨":         "",
+		"":               "",
+		"slash/inside":   "",
+		"tab\tseparated": "",
+	}
+	for in, want := range cases {
+		if got := skillSlashName(in); got != want {
+			t.Errorf("skillSlashName(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestSkillAppearsInAutocomplete(t *testing.T) {
+	m := newSkillTestModel(t, skills.Skill{Name: "deploy-checks", Description: "Run the pre-deploy suite.", Content: "x"})
+
+	got := m.matchCommandSuggestions("/dep")
+	found := false
+	for _, s := range got {
+		if s.Name == "/deploy-checks" {
+			found = true
+			if s.Desc != "Run the pre-deploy suite. (skill)" {
+				t.Fatalf("skill suggestion should be labeled, got %q", s.Desc)
+			}
+		}
+	}
+	if !found {
+		t.Fatalf("skill /deploy-checks should appear for '/dep', got %#v", got)
+	}
+}
+
+// A skill shadowed by a builtin (or its alias) or a user command would be dead
+// at dispatch time, so the palette must not advertise it.
+func TestShadowedSkillNotSuggested(t *testing.T) {
+	root := t.TempDir()
+	writeUserCommand(t, root, "deploy.md", "User deploy.")
+	installed := []skills.Skill{
+		{Name: "help", Content: "x"},     // builtin collision
+		{Name: "sessions", Content: "x"}, // builtin ALIAS collision (/resume alias)
+		{Name: "deploy", Content: "x"},   // user-command collision
+	}
+	infos := make([]agent.SkillInfo, 0, len(installed))
+	for _, s := range installed {
+		infos = append(infos, agent.SkillInfo{Name: s.Name})
+	}
+	m := newModel(context.Background(), Options{
+		Cwd:          root,
+		LoadSkills:   func() []skills.Skill { return installed },
+		AgentOptions: agent.Options{Skills: infos},
+	})
+
+	// Assert on the advertised NAME with a skill-marked Desc, not on the exact
+	// fallback Desc format — the invariant is that no skill row carries a
+	// builtin/user-command name, regardless of description wording.
+	for _, token := range []string{"/hel", "/ses", "/dep"} {
+		for _, s := range m.matchSkillSuggestions(token) {
+			if s.Name == "/help" || s.Name == "/sessions" || s.Name == "/deploy" {
+				t.Fatalf("shadowed skill advertised for %q: %#v", token, s)
+			}
+		}
+	}
+}
+
+// Invalid slash shapes (spaces etc.) and a bare "/" must not surface skills.
+func TestSkillSuggestionEdgeCases(t *testing.T) {
+	m := newSkillTestModel(t, skills.Skill{Name: "has space", Description: "not invocable", Content: "x"})
+
+	if got := m.matchSkillSuggestions("/has"); len(got) != 0 {
+		t.Fatalf("invalid slash-shape skill must not be suggested, got %#v", got)
+	}
+	if got := m.matchSkillSuggestions("/"); got != nil {
+		t.Fatalf("bare '/' should not list skills, got %#v", got)
+	}
+}
+
+func TestSkillsCommandResolves(t *testing.T) {
+	command, ok := resolveCommand("/skills")
+	if !ok || command.kind != commandSkills {
+		t.Fatalf("resolveCommand(/skills) = %#v, %v", command, ok)
+	}
+}
+
+// With skills installed, /skills opens a searchable picker (like /model).
+func TestSkillsCommandOpensPicker(t *testing.T) {
+	m := newSkillTestModel(t,
+		skills.Skill{Name: "deploy-checks", Description: "Run the pre-deploy suite.", Content: "x"},
+		skills.Skill{Name: "has space", Description: "tool-only skill", Content: "x"},
+	)
+
+	next := submitInput(t, m, "/skills")
+
+	if next.picker == nil || next.picker.kind != pickerSkill {
+		t.Fatalf("/skills should open the skill picker, got %#v", next.picker)
+	}
+	labels := map[string]string{}
+	for _, item := range next.picker.items {
+		labels[item.Label] = item.Value
+	}
+	if labels["/deploy-checks"] != "deploy-checks" {
+		t.Fatalf("slash-invocable skill should show its slash form, got %#v", labels)
+	}
+	// A non-slash-shaped name is still selectable (bare label, exact-name value).
+	if labels["has space"] != "has space" {
+		t.Fatalf("non-slash skill should be listed bare but selectable, got %#v", labels)
+	}
+}
+
+// Enter on a picker row fills the composer with "/name " so the user can add
+// their request (which PR? which file?) before submitting — it must NOT fire
+// the skill with no request attached.
+func TestSkillPickerEnterFillsComposer(t *testing.T) {
+	m := newSkillTestModel(t, skills.Skill{Name: "reviewer", Content: "Review the diff for correctness."})
+
+	next := submitInput(t, m, "/skills")
+	if next.picker == nil {
+		t.Fatal("picker should be open")
+	}
+	updated, _ := next.Update(testKey(tea.KeyEnter))
+	after := updated.(model)
+
+	if after.picker != nil {
+		t.Fatal("picker should close on Enter")
+	}
+	if got := after.input.Value(); got != "/reviewer " {
+		t.Fatalf("composer should be filled with the invocation, got %q", got)
+	}
+	if transcriptContains(after.transcript, "Review the diff for correctness.") {
+		t.Fatalf("skill must not run before the user submits, got %#v", after.transcript)
+	}
+
+	// A second Enter submits the (bare) invocation and runs the skill.
+	final, _ := after.Update(testKey(tea.KeyEnter))
+	done := final.(model)
+	if !transcriptContains(done.transcript, "Review the diff for correctness.") {
+		t.Fatalf("submitting the filled composer should run the skill, got %#v", done.transcript)
+	}
+}
+
+// Picker selection is by exact name, so a skill shadowed by a builtin (dead on
+// the slash path) is still runnable from the picker.
+func TestSkillPickerRunsBuiltinShadowedSkill(t *testing.T) {
+	m := newSkillTestModel(t, skills.Skill{Name: "help", Description: "shadowed", Content: "Shadowed skill body."})
+
+	next := submitInput(t, m, "/skills")
+	if next.picker == nil {
+		t.Fatal("picker should be open")
+	}
+	updated, _ := next.Update(testKey(tea.KeyEnter))
+	after := updated.(model)
+
+	if !transcriptContains(after.transcript, "Shadowed skill body.") {
+		t.Fatalf("picker must run the shadowed skill directly, got %#v", after.transcript)
+	}
+}
+
+func TestSkillsCommandEmptyState(t *testing.T) {
+	m := newModel(context.Background(), Options{Cwd: t.TempDir()})
+
+	next := submitInput(t, m, "/skills")
+
+	if !transcriptContains(next.transcript, "No skills installed.") {
+		t.Fatalf("empty state should say no skills, got %#v", next.transcript)
+	}
+}
+
+// Run-state guards: an expanded skill prompt must not race an active run — it
+// queues (as the EXPANDED prompt, since the queue flush submits literal text).
+func TestSkillInvocationQueuedWhileRunPending(t *testing.T) {
+	m := newSkillTestModel(t, skills.Skill{Name: "reviewer", Content: "Review the diff."})
+	m.pending = true
+
+	next, _, handled := m.handleSkillCommand("/reviewer focus on tests")
+	if !handled {
+		t.Fatal("skill must be handled even while a run is pending")
+	}
+	if next.queuedMessage == "" || !strings.Contains(next.queuedMessage, "Review the diff.") {
+		t.Fatalf("expanded prompt should be queued, got %q", next.queuedMessage)
+	}
+	if !strings.Contains(next.queuedMessage, "focus on tests") {
+		t.Fatalf("queued prompt should carry the args, got %q", next.queuedMessage)
+	}
+}
+
+func TestSkillInvocationDroppedWhileExiting(t *testing.T) {
+	m := newSkillTestModel(t, skills.Skill{Name: "reviewer", Content: "Review."})
+	m.exiting = true
+
+	next, cmd, handled := m.handleSkillCommand("/reviewer")
+	if !handled || cmd != nil || next.queuedMessage != "" {
+		t.Fatalf("exiting must swallow the invocation: handled=%v cmd=%v queued=%q", handled, cmd, next.queuedMessage)
+	}
+}
+
+func TestSkillInvocationWarnsDuringCompaction(t *testing.T) {
+	m := newSkillTestModel(t, skills.Skill{Name: "reviewer", Content: "Review."})
+	m.compactInFlight = true
+
+	next, _, handled := m.handleSkillCommand("/reviewer")
+	if !handled {
+		t.Fatal("skill must be handled during compaction")
+	}
+	if !transcriptContains(next.transcript, "Compaction is running") {
+		t.Fatalf("compaction warning expected, got %#v", next.transcript)
+	}
+	// The typed invocation is restored for an easy re-submit (the dispatch path
+	// cleared the composer before the guard could fire).
+	if got := next.input.Value(); got != "/reviewer" {
+		t.Fatalf("typed invocation should be restored into the composer, got %q", got)
+	}
+}
+
+// The same guard now protects user commands (previously they could start a
+// second concurrent run).
+func TestUserCommandQueuedWhileRunPending(t *testing.T) {
+	root := t.TempDir()
+	writeUserCommand(t, root, "greet.md", "Say hello to $1.")
+	m := newModel(context.Background(), Options{Cwd: root})
+	m.pending = true
+
+	next, _, handled := m.handleUserCommand("/greet world")
+	if !handled {
+		t.Fatal("user command must be handled while pending")
+	}
+	if !strings.Contains(next.queuedMessage, "Say hello to world.") {
+		t.Fatalf("expanded user-command prompt should be queued, got %q", next.queuedMessage)
+	}
+}
+
+// Two skills whose names collide after lowercasing map to one slash name; only
+// the one dispatch will run may be advertised.
+func TestCaseCollidingSkillsAdvertisedOnce(t *testing.T) {
+	m := newSkillTestModel(t,
+		skills.Skill{Name: "Deploy", Description: "wins", Content: "a"},
+		skills.Skill{Name: "deploy", Description: "loses", Content: "b"},
+	)
+
+	rows := 0
+	for _, s := range m.matchSkillSuggestions("/dep") {
+		if s.Name == "/deploy" {
+			rows++
+			if !strings.Contains(s.Desc, "wins") {
+				t.Fatalf("advertised row must describe the skill dispatch runs, got %q", s.Desc)
+			}
+		}
+	}
+	if rows != 1 {
+		t.Fatalf("case-colliding skills must yield exactly one /deploy row, got %d", rows)
+	}
+}
+
+// The palette reads through the loader, so a skill installed mid-session (the
+// loader's next result) appears without a restart.
+func TestSkillPaletteReadsThroughLoader(t *testing.T) {
+	installed := []skills.Skill{}
+	m := newModel(context.Background(), Options{
+		Cwd:        t.TempDir(),
+		LoadSkills: func() []skills.Skill { return installed },
+	})
+	if got := m.matchSkillSuggestions("/lat"); len(got) != 0 {
+		t.Fatalf("no skills installed yet, got %#v", got)
+	}
+	installed = append(installed, skills.Skill{Name: "late-arrival", Description: "installed mid-session", Content: "x"})
+	got := m.matchSkillSuggestions("/lat")
+	if len(got) != 1 || got[0].Name != "/late-arrival" {
+		t.Fatalf("mid-session skill should appear via the loader, got %#v", got)
+	}
+}

internal/tui/specialist_summary_render_test.go

@@ -22,7 +22,7 @@ func TestTranscriptBodyItemsIncludesSummaryBeforeCards(t *testing.T) {
 		specialistInfo: &specialistInfo{name: "explorer", description: "map code", childSessionID: "s2", status: specialistCompleted, startedAt: now, completedAt: now, tokenCount: 2000},
 	})
 
-	items := m.transcriptBodyItems(80, "")
+	items := m.transcriptBodyItems(80, "", false)
 	body := bodyItemsString(m, items, 80)
 	if !strings.Contains(body, "specialists") {
 		t.Errorf("transcript body should contain summary line with 'specialists', got:\n%s", body)

internal/tui/syntax_highlight_test.go

@@ -7,7 +7,7 @@ import (
 
 func TestStreamingCodeRendersHighlighted(t *testing.T) {
 	m := model{
-		streamingText: "```go\nfunc main() {}\n```",
+		streamingText: []byte("```go\nfunc main() {}\n```"),
 		pending:       true,
 	}
 	out := m.interimBlock(80)
@@ -86,7 +86,7 @@ func TestStreamingMarkdownStablePrefixUsesRenderCache(t *testing.T) {
 
 func TestStreamingBuffersOpenFencedCodeBlock(t *testing.T) {
 	open := model{
-		streamingText: "Here is the script:\n```python\nfrom datetime import datetime\nprint(datetime.now())",
+		streamingText: []byte("Here is the script:\n```python\nfrom datetime import datetime\nprint(datetime.now())"),
 		pending:       true,
 	}
 	openOut := plainRender(t, open.interimBlock(90))
@@ -98,7 +98,7 @@ func TestStreamingBuffersOpenFencedCodeBlock(t *testing.T) {
 	}
 
 	closed := model{
-		streamingText: open.streamingText + "\n```",
+		streamingText: []byte(string(open.streamingText) + "\n```"),
 		pending:       true,
 	}
 	closedOut := closed.interimBlock(90)