fix(redaction): take one run-on step per match, not the whole chain

Following a run-on from the second credential into a third, and on to the
end of the chain, did that walk again from every match inside the chain,
which is quadratic: a megabyte of split JWTs back to back allocated about
seventeen gigabytes and ran for ten minutes. Each match now separates only
the credential it ran into. The scan's own next match starts inside that
credential and takes the following step, so a chain is still covered, and
in chains of three or more the markers after the first pair can join.

A test bounds the allocation on a chain of split JWTs; the linear pass uses
about forty times the input and the walk used far more.

.github/workflows/pr-auto-review.yml

@@ -24,6 +24,7 @@ jobs:
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Setup Go
         uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff

.github/workflows/release-artifacts.yml

@@ -34,12 +34,15 @@ jobs:
       - name: Checkout
         if: ${{ github.event_name != 'workflow_dispatch' || inputs.ref == '' }}
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
 
       - name: Checkout requested ref
         if: ${{ github.event_name == 'workflow_dispatch' && inputs.ref != '' }}
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           ref: ${{ inputs.ref }}
+          persist-credentials: false
 
       - name: Setup Go
         uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff
@@ -129,6 +132,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
 
       # No registry-url here on purpose: setup-node's registry-url writes an
       # .npmrc line referencing $NODE_AUTH_TOKEN, and npm hard-fails on the

.github/workflows/zero-action-smoke.yml

@@ -5,6 +5,8 @@ on:
     paths:
       - action.yml
       - docs/GITHUB_ACTION.md
+      - scripts/action-summary.mjs
+      - scripts/action-summary.test.mjs
       - .github/workflows/zero-action-smoke.yml
   push:
     branches:
@@ -12,6 +14,8 @@ on:
     paths:
       - action.yml
       - docs/GITHUB_ACTION.md
+      - scripts/action-summary.mjs
+      - scripts/action-summary.test.mjs
       - .github/workflows/zero-action-smoke.yml
 
 permissions:
@@ -27,6 +31,14 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Setup Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 24
+
+      - name: Run action-summary test suite
+        run: node --test scripts/action-summary.test.mjs
+
       - name: Parse action.yml and assert documented inputs
         shell: bash
         run: |

.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.8.0"}
+{".":"0.9.0"}

CHANGELOG.md

@@ -6,6 +6,61 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once the first release is
 tagged. Until then, source builds report the version `dev`.
 
+## [0.9.0](https://github.com/Gitlawb/zero/compare/v0.8.0...v0.9.0) (2026-09-15)
+
+
+### Features
+
+* **acp:** add standard session list and resume ([#914](https://github.com/Gitlawb/zero/issues/914)) ([c1937df](https://github.com/Gitlawb/zero/commit/c1937dfac72e6ad0e5ade6e48e2d9c17d9c3e5d6))
+* **acp:** emit structured file changes in tool updates ([#999](https://github.com/Gitlawb/zero/issues/999)) ([faec8ee](https://github.com/Gitlawb/zero/commit/faec8ee2017fdd6d0c2c347add892cb73eb413d7))
+* **acp:** surface safe browser tool metadata ([#1000](https://github.com/Gitlawb/zero/issues/1000)) ([a6ec043](https://github.com/Gitlawb/zero/commit/a6ec0435e36b9bea9793b2fd97f2ecd30e3a0f9b))
+* **exec:** default headless runs to the turn-budget ceiling ([#1049](https://github.com/Gitlawb/zero/issues/1049)) ([9e609c5](https://github.com/Gitlawb/zero/commit/9e609c52420fd322f047fc238c04ac81dd623fdd))
+* **tui:** interactive terminal attach for tty exec sessions ([#1055](https://github.com/Gitlawb/zero/issues/1055)) ([d73ec81](https://github.com/Gitlawb/zero/commit/d73ec81e2d3facb5377bc9ad0fe2aa314628a0c0))
+* **tui:** offer mid-run model escalation behind --allow-escalation ([#1019](https://github.com/Gitlawb/zero/issues/1019)) ([91d921f](https://github.com/Gitlawb/zero/commit/91d921f4c5b8289a9e437f786218f1b48f2add5a))
+* **tui:** richer /resume session browser ([#1047](https://github.com/Gitlawb/zero/issues/1047)) ([2f53117](https://github.com/Gitlawb/zero/commit/2f531178f614e587b629e4f81e0470adda647fbd))
+
+
+### Bug Fixes
+
+* **acp:** make configured MCP tools callable ([#1003](https://github.com/Gitlawb/zero/issues/1003)) ([7f5e5af](https://github.com/Gitlawb/zero/commit/7f5e5af7bbdbe5bb4d91706146072d461c0234a4))
+* **agent:** stop the tool-schema ratchet meaning a different thing per host ([#1017](https://github.com/Gitlawb/zero/issues/1017)) ([f909266](https://github.com/Gitlawb/zero/commit/f9092668a832ea73a69551f0ea2df4f6eaf356df))
+* **background:** treat POSIX zombie leader as already-exited ([#981](https://github.com/Gitlawb/zero/issues/981)) ([1aacf38](https://github.com/Gitlawb/zero/commit/1aacf38b727d31b5ca09949316d6afa8292aec46))
+* **config:** lock config read-modify-write across processes ([#960](https://github.com/Gitlawb/zero/issues/960)) ([b04fe96](https://github.com/Gitlawb/zero/commit/b04fe96e9ef3f2deda4fb2a972270300629079d2))
+* **config:** preserve unknown top-level fields ([#984](https://github.com/Gitlawb/zero/issues/984)) ([488def6](https://github.com/Gitlawb/zero/commit/488def68dcc6d36701fdf171e94a74a436b090fc))
+* **daemon:** publish status files atomically ([#949](https://github.com/Gitlawb/zero/issues/949)) ([9001421](https://github.com/Gitlawb/zero/commit/90014210d2ada2e3d61f4eca5087d3f35a3c4b8b))
+* **installtxn:** put back an install a killed commit left behind ([#997](https://github.com/Gitlawb/zero/issues/997)) ([2837f5e](https://github.com/Gitlawb/zero/commit/2837f5efb38dcd3c69771b0ba31565f98a206120))
+* let the configured forward proxy through the loopback guard ([#1025](https://github.com/Gitlawb/zero/issues/1025)) ([1e4db7c](https://github.com/Gitlawb/zero/commit/1e4db7c6643ca7e2c3d8e4b8b30371cfbe43561e))
+* **lockutil:** use kernel-held advisory locks ([#950](https://github.com/Gitlawb/zero/issues/950)) ([6fe0d1e](https://github.com/Gitlawb/zero/commit/6fe0d1edcdbadea6d566800fbcca739c1cd54ea1))
+* **mcp:** discover OAuth through protected resource metadata ([#991](https://github.com/Gitlawb/zero/issues/991)) ([1b5db17](https://github.com/Gitlawb/zero/commit/1b5db1765672820caac1684b168c9898b5ba3593))
+* **mcp:** reject a server-initiated request as a streamable-HTTP response ([#1054](https://github.com/Gitlawb/zero/issues/1054)) ([2479d94](https://github.com/Gitlawb/zero/commit/2479d946c15dbf74ee3c04a637e97181d1786f08))
+* **oauth:** force-close loopback callback connections past the shutdown deadline ([#1051](https://github.com/Gitlawb/zero/issues/1051)) ([176f5a2](https://github.com/Gitlawb/zero/commit/176f5a242b754a86ea4c7121a8dcc1c0d72cf2e4))
+* **oauth:** Split an oversized keyring token blob across entries ([#1007](https://github.com/Gitlawb/zero/issues/1007)) ([275e248](https://github.com/Gitlawb/zero/commit/275e2486695338ce38193a6e3319f8b6a9a5c33c))
+* **providerio:** close idle connections periodically to prevent HTTP/2 PROTOCOL_ERROR ([#1058](https://github.com/Gitlawb/zero/issues/1058)) ([b76c764](https://github.com/Gitlawb/zero/commit/b76c764b77926891aa67163e6605a2d8540aacaa))
+* **providers:** register Atomic Chat as local OpenAI-compatible runtime ([#550](https://github.com/Gitlawb/zero/issues/550)) ([79fa142](https://github.com/Gitlawb/zero/commit/79fa1422ef1a3691b93342788453ebc284d57f9c))
+* **redaction:** split camelCase keys in normalizeKey ([#994](https://github.com/Gitlawb/zero/issues/994)) ([08fbea7](https://github.com/Gitlawb/zero/commit/08fbea7a3221d2061d88038924f90a4cba9af1ac))
+* **sandbox:** keep a derived ACL target inside the write root it came from ([#1040](https://github.com/Gitlawb/zero/issues/1040)) ([3b43c43](https://github.com/Gitlawb/zero/commit/3b43c43eca968c8619adadc81fcc1a17e220216a))
+* **sandbox:** keep Windows restricted-token SIDs narrow and fail closed on DenyRead ([#1006](https://github.com/Gitlawb/zero/issues/1006)) ([0207f2b](https://github.com/Gitlawb/zero/commit/0207f2b2697149a73ecc89a5ab5db0bd665f1911))
+* **sandbox:** Make WSL backend tests deterministic. ([#948](https://github.com/Gitlawb/zero/issues/948)) ([e59bf78](https://github.com/Gitlawb/zero/commit/e59bf78cabc2703678778b904c27c8bc8ef82bc8))
+* **sandbox:** protect worktree git pointers ([#805](https://github.com/Gitlawb/zero/issues/805)) ([f30f550](https://github.com/Gitlawb/zero/commit/f30f550e6037c53f8521ba2d59c984ae6c574917))
+* **sandbox:** refcount temporary roots so one holder's cleanup cannot revoke another's ([#911](https://github.com/Gitlawb/zero/issues/911)) ([7acac7a](https://github.com/Gitlawb/zero/commit/7acac7acee65565e25089f2a7b5813c086ce65eb))
+* **sessions:** carry an interrupted turn's work into the resume prompt ([#1016](https://github.com/Gitlawb/zero/issues/1016)) ([6ae8396](https://github.com/Gitlawb/zero/commit/6ae8396f0282a5f18a431f0c0ef1a272ecc2ca2b))
+* **sessions:** render resume context fields in key order ([#1043](https://github.com/Gitlawb/zero/issues/1043)) ([da244bc](https://github.com/Gitlawb/zero/commit/da244bcbfcfa05e414567ac0acc3cf8ba745ad7d))
+* **specialist:** keep the pinned model when a specialist is resumed ([#1009](https://github.com/Gitlawb/zero/issues/1009)) ([aadb4a2](https://github.com/Gitlawb/zero/commit/aadb4a27e9cdb41e774e8e1a8f23cf9c2fb50db2))
+* **swarm:** stop original member before handoff ([#957](https://github.com/Gitlawb/zero/issues/957)) ([0021475](https://github.com/Gitlawb/zero/commit/0021475d4c58c91911098f414795512cf60a0b56))
+* **tools:** an edit keeps the reads it did not disturb ([#908](https://github.com/Gitlawb/zero/issues/908)) ([1649008](https://github.com/Gitlawb/zero/commit/1649008506da0e675431dc056251a01891b15cc8))
+* **tools:** make apply_patch tolerant and re-expose edit_file ([#956](https://github.com/Gitlawb/zero/issues/956)) ([2749447](https://github.com/Gitlawb/zero/commit/2749447cdce4ae5dd333538b36fa919b80ecc66d))
+* **tools:** reject fuzzy edits with drifted content ([#983](https://github.com/Gitlawb/zero/issues/983)) ([8b3d1b1](https://github.com/Gitlawb/zero/commit/8b3d1b1597b04bfa6d4bc7f912abc13ca80a6298))
+* **tools:** say when format-on-write ran out of time ([#1044](https://github.com/Gitlawb/zero/issues/1044)) ([6937a30](https://github.com/Gitlawb/zero/commit/6937a309cf00825572210a7610a1f3ea8b74c2f9))
+* **tui:** move voice capture to Ctrl+Space ([#968](https://github.com/Gitlawb/zero/issues/968)) ([eeea330](https://github.com/Gitlawb/zero/commit/eeea3308fed38b37b203522624babaf2f30df91f))
+* **update:** keep Windows failed-restore state in trusted recovery records ([#979](https://github.com/Gitlawb/zero/issues/979)) ([a3852ba](https://github.com/Gitlawb/zero/commit/a3852bac595e06c5d3ca9da22212b281b8796802))
+
+
+### Performance Improvements
+
+* **agent:** cheap compaction — dedicated summarizer model, input cap… ([#532](https://github.com/Gitlawb/zero/issues/532)) ([6645f97](https://github.com/Gitlawb/zero/commit/6645f9744b37dda4d52ecc4631578d62cefc89de))
+* **providers:** parallelize isolated provider unit tests and shrink retry backoffs ([#955](https://github.com/Gitlawb/zero/issues/955)) ([d6b25fc](https://github.com/Gitlawb/zero/commit/d6b25fc3039a6b7d72a5703a87a097449792b102))
+* reduce startup and turn overhead ([#932](https://github.com/Gitlawb/zero/issues/932)) ([1fde941](https://github.com/Gitlawb/zero/commit/1fde941803c4295c11a4a14559f3c5217d1a9e69))
+
 ## [0.8.0](https://github.com/Gitlawb/zero/compare/v0.7.0...v0.8.0) (2026-08-21)
 
 

internal/acp/translate.go

@@ -3,6 +3,7 @@ package acp
 import (
 	"encoding/json"
 	"net/url"
+	"path/filepath"
 	"strings"
 	"unicode"
 	"unicode/utf8"
@@ -246,22 +247,59 @@ func toolCallResult(result agent.ToolResult) ToolCallUpdate {
 }
 
 func toolResultContent(result agent.ToolResult) []ToolCallContent {
+	content := make([]ToolCallContent, 0, 1+len(result.FileDiffs))
 	text := strings.TrimRight(result.Output, "\n")
 	if text == "" {
 		text = result.Display.Summary
 	}
 	if text == "" {
-		return nil
+		return appendToolResultDiffs(content, result.FileDiffs)
 	}
-	return []ToolCallContent{ToolContent(TextBlock(text))}
+	content = append(content, ToolContent(TextBlock(text)))
+	return appendToolResultDiffs(content, result.FileDiffs)
+}
+
+func appendToolResultDiffs(content []ToolCallContent, diffs []tools.FileDiff) []ToolCallContent {
+	for _, diff := range diffs {
+		if !filepath.IsAbs(diff.Path) || (!diff.OldExists && !diff.NewExists) {
+			continue
+		}
+		var oldText *string
+		if diff.OldExists {
+			old := diff.OldText
+			oldText = &old
+		}
+		var newText *string
+		if diff.NewExists {
+			updated := diff.NewText
+			newText = &updated
+		}
+		content = append(content, ToolCallContent{Type: "diff", Path: diff.Path, OldText: oldText, NewText: newText})
+	}
+	return content
 }
 
 func toolResultLocations(result agent.ToolResult) []ToolCallLocation {
-	locs := make([]ToolCallLocation, 0, len(result.ChangedFiles))
-	for _, f := range result.ChangedFiles {
-		if strings.TrimSpace(f) == "" {
+	locs := make([]ToolCallLocation, 0, len(result.FileDiffs)+len(result.ChangedFiles))
+	seen := make(map[string]bool, len(result.FileDiffs)+len(result.ChangedFiles))
+	for _, diff := range result.FileDiffs {
+		path := diff.Path
+		if path == "" || seen[path] {
 			continue
 		}
+		seen[path] = true
+		locs = append(locs, ToolCallLocation{Path: path})
+	}
+	// FileDiff.Path is canonical absolute path data while ChangedFiles is
+	// normally workspace-relative. Without the trusted workspace root these
+	// coordinate systems cannot be correlated safely: a suffix match would let
+	// /workspace/sub/a.go consume the fallback for a distinct root a.go. The
+	// shared seen set deduplicates only identities already exactly comparable.
+	for _, f := range result.ChangedFiles {
+		if f == "" || seen[f] {
+			continue
+		}
+		seen[f] = true
 		locs = append(locs, ToolCallLocation{Path: f})
 	}
 	return locs

internal/acp/translate_test.go

@@ -2,6 +2,7 @@ package acp
 
 import (
 	"encoding/json"
+	"path/filepath"
 	"strings"
 	"testing"
 	"unicode"
@@ -300,21 +301,26 @@ func TestToolCallStart(t *testing.T) {
 }
 
 func TestToolCallResult(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "a.go")
 	ok := toolCallResult(agent.ToolResult{
 		ToolCallID:   "tc1",
 		Name:         "edit_file",
 		Status:       tools.StatusOK,
 		Output:       "applied\n",
 		ChangedFiles: []string{"a.go", ""},
+		FileDiffs:    []tools.FileDiff{{Path: path, OldExists: true, NewExists: true, OldText: "before\n", NewText: "after\n"}},
 	})
 	if ok.SessionUpdate != UpdateToolCallUpdate || ok.Status != ToolStatusCompleted {
 		t.Fatalf("unexpected ok result: %+v", ok)
 	}
-	if len(ok.Content) != 1 || ok.Content[0].Type != "content" || ok.Content[0].Content.Text != "applied" {
+	if len(ok.Content) != 2 || ok.Content[0].Type != "content" || ok.Content[0].Content.Text != "applied" {
 		t.Fatalf("unexpected content: %+v", ok.Content)
 	}
-	if len(ok.Locations) != 1 || ok.Locations[0].Path != "a.go" {
-		t.Fatalf("blank changed files should be dropped, got %+v", ok.Locations)
+	if diff := ok.Content[1]; diff.Type != "diff" || diff.Path != path || diff.OldText == nil || *diff.OldText != "before\n" || diff.NewText == nil || *diff.NewText != "after\n" {
+		t.Fatalf("unexpected diff content: %+v", diff)
+	}
+	if len(ok.Locations) != 2 || ok.Locations[0].Path != path || ok.Locations[1].Path != "a.go" {
+		t.Fatalf("unproven absolute/relative aliases must both remain visible, got %+v", ok.Locations)
 	}
 
 	failed := toolCallResult(agent.ToolResult{ToolCallID: "tc2", Status: tools.StatusError, Output: "boom"})
@@ -323,6 +329,190 @@ func TestToolCallResult(t *testing.T) {
 	}
 }
 
+func TestToolCallDiffJSONDistinguishesEmptyFilesAndDeletion(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "empty.txt")
+	content := appendToolResultDiffs(nil, []tools.FileDiff{
+		{Path: path, OldExists: false, NewExists: true, NewText: ""},
+		{Path: path, OldExists: true, NewExists: true, OldText: "before", NewText: ""},
+		{Path: path, OldExists: true, NewExists: false, OldText: "before"},
+	})
+	if len(content) != 3 {
+		t.Fatalf("diff content = %#v", content)
+	}
+	for index, diff := range content {
+		encoded, err := json.Marshal(diff)
+		if err != nil {
+			t.Fatal(err)
+		}
+		var wire map[string]any
+		if err := json.Unmarshal(encoded, &wire); err != nil {
+			t.Fatal(err)
+		}
+		if wire["path"] != path {
+			t.Fatalf("wire diff %d = %s", index, encoded)
+		}
+		switch index {
+		case 0:
+			oldText, present := wire["oldText"]
+			if !present || oldText != nil || wire["newText"] != "" {
+				t.Fatalf("create diff = %s, want null oldText and empty newText", encoded)
+			}
+		case 1:
+			if wire["oldText"] != "before" || wire["newText"] != "" {
+				t.Fatalf("empty replacement diff = %s", encoded)
+			}
+		case 2:
+			newText, present := wire["newText"]
+			if wire["oldText"] != "before" || !present || newText != nil {
+				t.Fatalf("deletion diff = %s, want oldText and null newText", encoded)
+			}
+		}
+	}
+}
+
+func TestToolResultLocationsPreserveDistinctPathIdentities(t *testing.T) {
+	root := t.TempDir()
+	rootPath := filepath.Join(root, "a.go")
+	nestedPath := filepath.Join(root, "sub", "a.go")
+	diff := func(path string) tools.FileDiff {
+		return tools.FileDiff{Path: path, OldExists: true, NewExists: true, OldText: "before", NewText: "after"}
+	}
+	for _, tc := range []struct {
+		name  string
+		diffs []tools.FileDiff
+		want  []string
+	}{
+		{name: "both rich", diffs: []tools.FileDiff{diff(rootPath), diff(nestedPath)}, want: []string{rootPath, nestedPath, "a.go", filepath.Join("sub", "a.go")}},
+		{name: "root rich", diffs: []tools.FileDiff{diff(rootPath)}, want: []string{rootPath, "a.go", filepath.Join("sub", "a.go")}},
+		{name: "nested rich", diffs: []tools.FileDiff{diff(nestedPath)}, want: []string{nestedPath, "a.go", filepath.Join("sub", "a.go")}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			locations := toolResultLocations(agent.ToolResult{
+				ChangedFiles: []string{"a.go", filepath.Join("sub", "a.go")},
+				FileDiffs:    tc.diffs,
+			})
+			if len(locations) != len(tc.want) {
+				t.Fatalf("locations = %#v, want %#v", locations, tc.want)
+			}
+			for index := range tc.want {
+				if locations[index].Path != tc.want[index] {
+					t.Fatalf("locations = %#v, want %#v", locations, tc.want)
+				}
+			}
+		})
+	}
+}
+
+func TestToolCallResultPreservesWhitespaceInFilePaths(t *testing.T) {
+	relativePath := " report.txt "
+	absolutePath := filepath.Join(t.TempDir(), relativePath)
+	update := toolCallResult(agent.ToolResult{
+		ChangedFiles: []string{relativePath},
+		FileDiffs: []tools.FileDiff{{
+			Path: absolutePath, OldExists: true, NewExists: true, OldText: "before", NewText: "after",
+		}},
+	})
+	if len(update.Content) != 1 || update.Content[0].Path != absolutePath {
+		t.Fatalf("diff content path = %#v, want %q", update.Content, absolutePath)
+	}
+	if len(update.Locations) != 2 || update.Locations[0].Path != absolutePath || update.Locations[1].Path != relativePath {
+		t.Fatalf("locations = %#v, want exact paths %q and %q", update.Locations, absolutePath, relativePath)
+	}
+}
+
+func TestToolResultLocationsDeduplicateOnlyExactPaths(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "a.go")
+	locations := toolResultLocations(agent.ToolResult{
+		ChangedFiles: []string{path, path},
+		FileDiffs:    []tools.FileDiff{{Path: path, OldExists: true, NewExists: true, OldText: "before", NewText: "after"}},
+	})
+	if len(locations) != 1 || locations[0].Path != path {
+		t.Fatalf("exact duplicate locations = %#v", locations)
+	}
+}
+
+func TestDeletedFileEmitsDiffAndKeepsLocations(t *testing.T) {
+	relativePath := "deleted.go"
+	absolutePath := filepath.Join(t.TempDir(), relativePath)
+	update := toolCallResult(agent.ToolResult{
+		ChangedFiles: []string{relativePath},
+		FileDiffs: []tools.FileDiff{{
+			Path: absolutePath, OldExists: true, NewExists: false, OldText: "before",
+		}},
+	})
+	if len(update.Content) != 1 || update.Content[0].OldText == nil || *update.Content[0].OldText != "before" || update.Content[0].NewText != nil {
+		t.Fatalf("deleted file diff = %#v, want oldText with null newText", update.Content)
+	}
+	if len(update.Locations) != 2 || update.Locations[0].Path != absolutePath || update.Locations[1].Path != relativePath {
+		t.Fatalf("deleted file locations = %#v", update.Locations)
+	}
+}
+
+func TestToolCallResultEmitsOnlyRedactedFileDiffs(t *testing.T) {
+	secret := "sk-proj-abcdefghijklmnopqrstuvwxyz"
+	path := filepath.Join(t.TempDir(), "secret.txt")
+	scrubbed := tools.ScrubResultSecrets(tools.Result{FileDiffs: []tools.FileDiff{{
+		Path: path, OldExists: true, NewExists: true, OldText: "token=" + secret, NewText: "safe",
+	}}})
+	update := toolCallResult(agent.ToolResult{ToolCallID: "call", Status: tools.StatusError, FileDiffs: scrubbed.FileDiffs})
+	if len(update.Content) != 1 || update.Content[0].OldText == nil || strings.Contains(*update.Content[0].OldText, secret) {
+		t.Fatalf("ACP content leaked unredacted diff: %#v", update.Content)
+	}
+}
+
+func TestToolCallResultOmitsSemanticallyUnchangedRedactedDiff(t *testing.T) {
+	oldSecret := "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	newSecret := "ghp_9876543210ZYXWVUTSRQPONMLKJIHGFEDCBA"
+	scrubbed := tools.ScrubResultSecrets(tools.Result{
+		ChangedFiles: []string{"credentials.txt"},
+		FileDiffs: []tools.FileDiff{{
+			Path: filepath.Join(t.TempDir(), "credentials.txt"), OldExists: true, NewExists: true,
+			OldText: "token=" + oldSecret, NewText: "token=" + newSecret,
+		}},
+	})
+	update := toolCallResult(agent.ToolResult{
+		ToolCallID: "call", Status: tools.StatusOK,
+		ChangedFiles: scrubbed.ChangedFiles, FileDiffs: scrubbed.FileDiffs,
+	})
+	if len(update.Content) != 0 {
+		t.Fatalf("ACP emitted semantically unchanged redacted diff: %#v", update.Content)
+	}
+	if len(update.Locations) != 1 || update.Locations[0].Path != "credentials.txt" {
+		t.Fatalf("ACP path fallback = %#v", update.Locations)
+	}
+}
+
+func TestToolCallResultOmitsDefaultIgnorableSplitSecretsOnEitherSide(t *testing.T) {
+	secret := "sk-ant-api03-AAAABBBBCCCCDDDDEEEEFFFFGGGG"
+	for name, separator := range map[string]string{
+		"combining grapheme joiner": "\u034f",
+		"variation selector":        "\ufe0f",
+	} {
+		for _, side := range []string{"old", "new"} {
+			t.Run(name+" "+side, func(t *testing.T) {
+				obfuscated := secret[:20] + separator + secret[20:]
+				diff := tools.FileDiff{
+					Path: filepath.Join(t.TempDir(), "secret.txt"), OldExists: true, NewExists: true,
+					OldText: "safe old", NewText: "safe new",
+				}
+				if side == "old" {
+					diff.OldText = obfuscated
+				} else {
+					diff.NewText = obfuscated
+				}
+				scrubbed := tools.ScrubResultSecrets(tools.Result{FileDiffs: []tools.FileDiff{diff}})
+				if !scrubbed.Redacted || len(scrubbed.FileDiffs) != 0 {
+					t.Fatalf("registry boundary retained an obfuscated secret: %#v", scrubbed)
+				}
+				update := toolCallResult(agent.ToolResult{ToolCallID: "call", Status: tools.StatusOK, FileDiffs: scrubbed.FileDiffs})
+				if len(update.Content) != 0 {
+					t.Fatalf("ACP content retained an obfuscated secret: %#v", update.Content)
+				}
+			})
+		}
+	}
+}
+
 func TestPlanUpdateAndStatus(t *testing.T) {
 	upd := planUpdate([]tools.PlanItem{
 		{Content: "step a", Status: "completed"},

internal/acp/types.go

@@ -284,9 +284,30 @@ type ToolCallContent struct {
 	// type == "content"
 	Content *ContentBlock `json:"content,omitempty"`
 	// type == "diff"
-	Path    string `json:"path,omitempty"`
-	OldText string `json:"oldText,omitempty"`
-	NewText string `json:"newText,omitempty"`
+	Path    string  `json:"path,omitempty"`
+	OldText *string `json:"oldText,omitempty"`
+	NewText *string `json:"newText,omitempty"`
+}
+
+// MarshalJSON preserves ACP's discriminated content union. A diff always has
+// path, while nullable oldText/newText distinguish creation, deletion, and an
+// existing file replaced with empty content. Other content variants omit all
+// diff fields rather than serializing irrelevant nulls.
+func (content ToolCallContent) MarshalJSON() ([]byte, error) {
+	if content.Type == "diff" {
+		return json.Marshal(struct {
+			Type    string  `json:"type"`
+			Path    string  `json:"path"`
+			OldText *string `json:"oldText"`
+			NewText *string `json:"newText"`
+		}{
+			Type: content.Type, Path: content.Path, OldText: content.OldText, NewText: content.NewText,
+		})
+	}
+	return json.Marshal(struct {
+		Type    string        `json:"type"`
+		Content *ContentBlock `json:"content,omitempty"`
+	}{Type: content.Type, Content: content.Content})
 }
 
 func ToolContent(block ContentBlock) ToolCallContent {

internal/agent/async_diagnostics_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/Gitlawb/zero/internal/testutil"
 	"github.com/Gitlawb/zero/internal/tools"
 	"github.com/Gitlawb/zero/internal/zeroruntime"
 )
@@ -111,7 +112,11 @@ func TestAsyncDiagnosticsReEditReplacesResult(t *testing.T) {
 	diagnostics := newAsyncDiagnostics(check, "/ws")
 
 	diagnostics.enqueue(context.Background(), []string{"a.go"})
-	waitForIdle(t, diagnostics)
+	testutil.WaitFor(t, "worker idle", func() bool {
+		diagnostics.mu.Lock()
+		defer diagnostics.mu.Unlock()
+		return diagnostics.working == nil
+	})
 	mu.Lock()
 	response = "ERR new"
 	mu.Unlock()
@@ -123,23 +128,6 @@ func TestAsyncDiagnosticsReEditReplacesResult(t *testing.T) {
 	}
 }
 
-func waitForIdle(t *testing.T, diagnostics *asyncDiagnostics) {
-	t.Helper()
-	deadline := time.Now().Add(2 * time.Second)
-	for {
-		diagnostics.mu.Lock()
-		busy := diagnostics.working
-		diagnostics.mu.Unlock()
-		if busy == nil {
-			return
-		}
-		if time.Now().After(deadline) {
-			t.Fatal("worker never went idle")
-		}
-		time.Sleep(2 * time.Millisecond)
-	}
-}
-
 // changedFilesTool is a fake mutating tool reporting a changed file without
 // touching the filesystem.
 type changedFilesTool struct{}

internal/agent/loop.go

@@ -1527,6 +1527,7 @@ func executeToolCall(ctx context.Context, registry *tools.Registry, call ToolCal
 		Images:          result.Images,
 		Redacted:        result.Redacted,
 		ChangedFiles:    result.ChangedFiles,
+		FileDiffs:       result.FileDiffs,
 		ChangeSummaries: result.ChangeSummaries,
 		Display:         result.HumanDisplay(),
 		Outcome:         result.Outcome,
@@ -1833,6 +1834,10 @@ func runToolForUnsandboxedRetry(ctx context.Context, registry *tools.Registry, n
 }
 
 func toolResultFromPrePermissionReject(call ToolCall, result tools.Result) ToolResult {
+	// PrePermissionRejecter runs before Registry.RunWithOptions, so it must
+	// explicitly cross the same transcript/redaction boundary before its result
+	// can be forwarded through ACP.
+	result = tools.ScrubResultSecrets(result)
 	output, outputRedacted := scrubInterceptedOutput(result.Output)
 	display := result.Display
 	summary, summaryRedacted := scrubInterceptedOutput(display.Summary)
@@ -1860,6 +1865,7 @@ func toolResultFromPrePermissionReject(call ToolCall, result tools.Result) ToolR
 		Meta:            meta,
 		Redacted:        result.Redacted || outputRedacted || summaryRedacted || metaRedacted,
 		ChangedFiles:    result.ChangedFiles,
+		FileDiffs:       result.FileDiffs,
 		ChangeSummaries: result.ChangeSummaries,
 		Display:         display,
 		LoadedTools:     loadedToolsFromResult(meta),
@@ -2153,6 +2159,7 @@ func askUserFallbackResult(ctx context.Context, registry *tools.Registry, call T
 			Meta:            result.Meta,
 			Redacted:        result.Redacted,
 			ChangedFiles:    result.ChangedFiles,
+			FileDiffs:       result.FileDiffs,
 			ChangeSummaries: result.ChangeSummaries,
 			Display:         result.HumanDisplay(),
 			Outcome:         result.Outcome,

internal/agent/loop_test.go

@@ -27,6 +27,23 @@ type mockProvider struct {
 	requests []zeroruntime.CompletionRequest
 }
 
+func TestPrePermissionRejectScrubsFileDiffs(t *testing.T) {
+	secret := "sk-proj-abcdefghijklmnopqrstuvwxyz"
+	result := toolResultFromPrePermissionReject(ToolCall{ID: "call", Name: "test"}, tools.Result{
+		Status: tools.StatusError,
+		FileDiffs: []tools.FileDiff{{
+			Path:      filepath.Join(t.TempDir(), "secret.txt"),
+			OldExists: true,
+			NewExists: true,
+			OldText:   "token=" + secret,
+			NewText:   "safe",
+		}},
+	})
+	if len(result.FileDiffs) != 1 || strings.Contains(result.FileDiffs[0].OldText, secret) || !result.Redacted {
+		t.Fatalf("pre-permission FileDiff = %#v, redacted = %t", result.FileDiffs, result.Redacted)
+	}
+}
+
 func TestTypedExecutionOutcomeOverridesLegacySandboxHeuristics(t *testing.T) {
 	engine := sandbox.NewEngine(sandbox.EngineOptions{WorkspaceRoot: t.TempDir(), Policy: sandbox.DefaultPolicy()})
 	call := ToolCall{Name: tools.ExecCommandToolName}

internal/agent/types.go

@@ -84,6 +84,7 @@ type ToolResult struct {
 	Images       []zeroruntime.ImageBlock
 	Redacted     bool
 	ChangedFiles []string
+	FileDiffs    []tools.FileDiff
 	// ChangeSummaries are non-selectable generated-tree summaries emitted by
 	// command execution; callers must not schedule per-file work from them.
 	ChangeSummaries []execution.Change

internal/cli/exec.go

@@ -49,6 +49,14 @@ const (
 	exitInterrupted = 130
 )
 
+// defaultExecMaxTurns is the headless tool-turn budget when no source sets one.
+// An interactive run can be continued past the shared interactive default by the
+// user; an exec run has nobody to unstick it, so evals and automation would
+// truncate mid-task at 80 turns. The ceiling is the already-justified bound —
+// still finite against a genuinely runaway loop, which the loop's empty-turn
+// guard also cuts independently of this budget.
+const defaultExecMaxTurns = config.MaxTurnsCeiling
+
 type execOutputFormat string
 type execInputFormat string
 
@@ -320,6 +328,7 @@ func runExec(args []string, stdout io.Writer, stderr io.Writer, deps appDeps) in
 		}
 		return writeExecProviderError(stdout, stderr, options.outputFormat, "provider_error", err.Error())
 	}
+	resolved.MaxTurns = execTurnBudget(resolved)
 	var displacedMaxTurns int
 	resolved.MaxTurns, displacedMaxTurns = applyProfileTurnBudget(execProfile, options.maxTurns, resolved.MaxTurns)
 	execScope, err := sandbox.NewScope(workspaceRoot, append(append([]string{}, resolved.Sandbox.AdditionalWriteRoots...), options.addDirs...))
@@ -1222,6 +1231,20 @@ func specProfileEffortFilled(effortFilled bool, specReasoningEffort string) bool
 	return effortFilled && strings.TrimSpace(specReasoningEffort) == ""
 }
 
+// execTurnBudget applies the headless default to the resolved turn budget: an
+// interactive run can be continued past the shared default by the user, but an
+// exec run has nobody to unstick it, so an unconfigured budget starts at the
+// documented ceiling instead of truncating mid-task. Explicit sources
+// (--max-turns, mode presets, ZERO_MAX_TURNS, config files) resolve as
+// MaxTurnsSet and pass through; an exec-profile budget still wins via
+// applyProfileTurnBudget afterward.
+func execTurnBudget(resolved config.ResolvedConfig) int {
+	if resolved.MaxTurnsSet {
+		return resolved.MaxTurns
+	}
+	return defaultExecMaxTurns
+}
+
 // applyProfileTurnBudget decides the run's turn budget once config is resolved.
 // The profile displaces the RESOLVED value, not the flag: a pinned budget
 // always wins and the profile backs off entirely, while an env/config budget

internal/cli/exec_test.go

@@ -1975,3 +1975,23 @@ func TestRunExecTopTierDeclineNoSwitch(t *testing.T) {
 		t.Fatalf("provider model = %q, want claude-opus-4.1", providerModels[0])
 	}
 }
+
+func TestExecTurnBudgetDefaultsToCeilingUnlessSet(t *testing.T) {
+	cases := []struct {
+		name     string
+		resolved config.ResolvedConfig
+		want     int
+	}{
+		// A headless run has no user to continue past the shared interactive
+		// default, so an unconfigured budget starts at the ceiling.
+		{"unconfigured default", config.ResolvedConfig{MaxTurns: 80, MaxTurnsSet: false}, config.MaxTurnsCeiling},
+		// A user who configured 80 on purpose (e.g. cost control in CI) keeps 80.
+		{"explicit default value", config.ResolvedConfig{MaxTurns: 80, MaxTurnsSet: true}, 80},
+		{"configured value passes through", config.ResolvedConfig{MaxTurns: 42, MaxTurnsSet: true}, 42},
+	}
+	for _, tc := range cases {
+		if got := execTurnBudget(tc.resolved); got != tc.want {
+			t.Fatalf("%s: execTurnBudget = %d, want %d", tc.name, got, tc.want)
+		}
+	}
+}

internal/config/resolver.go

@@ -166,6 +166,7 @@ func Resolve(options ResolveOptions) (ResolvedConfig, error) {
 		Providers:           providers,
 		Provider:            active,
 		MaxTurns:            cfg.MaxTurns,
+		MaxTurnsSet:         cfg.maxTurnsSet,
 		MCP:                 cfg.MCP,
 		Sandbox:             cfg.Sandbox,
 		Notify:              cfg.Notify,
@@ -234,6 +235,7 @@ func mergeConfig(dst *FileConfig, src FileConfig) {
 	}
 	if src.MaxTurns > 0 {
 		dst.MaxTurns = src.MaxTurns
+		dst.maxTurnsSet = true
 	}
 	for _, provider := range src.Providers {
 		mergeProvider(dst, provider)
@@ -294,6 +296,7 @@ func mergeProjectConfig(dst *FileConfig, src FileConfig) error {
 	}
 	if src.MaxTurns > 0 {
 		dst.MaxTurns = src.MaxTurns
+		dst.maxTurnsSet = true
 	}
 	for _, provider := range src.Providers {
 		candidate := providerMergeCandidate(*dst, provider)
@@ -606,6 +609,7 @@ func applyEnv(cfg *FileConfig, env map[string]string) {
 				n = MaxTurnsCeiling
 			}
 			cfg.MaxTurns = n
+			cfg.maxTurnsSet = true
 		}
 	}
 
@@ -726,6 +730,7 @@ func applyOverrides(cfg *FileConfig, overrides Overrides) {
 	}
 	if overrides.MaxTurns > 0 {
 		cfg.MaxTurns = overrides.MaxTurns
+		cfg.maxTurnsSet = true
 	}
 	if overrides.Sandbox.Enabled != nil {
 		cfg.Sandbox.Enabled = overrides.Sandbox.Enabled

internal/config/resolver_test.go

@@ -2252,3 +2252,45 @@ func TestResolveRejectsInvalidCrossSessionInbound(t *testing.T) {
 		t.Fatalf("error = %v", err)
 	}
 }
+
+func TestResolveReportsExplicitMaxTurns(t *testing.T) {
+	const providerJSON = `{
+		"activeProvider": "p",
+		"providers": [{"name": "p", "provider_kind": "openai-compatible", "base_url": "https://x.example/v1", "apiKey": "k", "model": "m"}]
+	}`
+	providerWithTurns := strings.Replace(providerJSON, `"activeProvider": "p"`, `"activeProvider": "p", "maxTurns": 40`, 1)
+
+	cases := []struct {
+		name string
+		opts ResolveOptions
+		set  bool
+	}{
+		{"built-in default only", ResolveOptions{
+			Overrides: Overrides{Provider: ProviderProfile{Name: "p", ProviderKind: "openai-compatible", BaseURL: "https://x.example/v1", APIKey: "k", Model: "m"}},
+		}, false},
+		{"user config", ResolveOptions{UserConfigPath: writeConfig(t, providerWithTurns)}, true},
+		{"project config", ResolveOptions{
+			UserConfigPath:    writeConfig(t, providerJSON),
+			ProjectConfigPath: writeConfig(t, `{"maxTurns": 40}`),
+		}, true},
+		{"env", ResolveOptions{
+			Env:       map[string]string{MaxTurnsEnv: "120"},
+			Overrides: Overrides{Provider: ProviderProfile{Name: "p", ProviderKind: "openai-compatible", BaseURL: "https://x.example/v1", APIKey: "k", Model: "m"}},
+		}, true},
+		{"cli override", ResolveOptions{
+			Overrides: Overrides{
+				MaxTurns: 42,
+				Provider: ProviderProfile{Name: "p", ProviderKind: "openai-compatible", BaseURL: "https://x.example/v1", APIKey: "k", Model: "m"},
+			},
+		}, true},
+	}
+	for _, tc := range cases {
+		resolved, err := Resolve(tc.opts)
+		if err != nil {
+			t.Fatalf("%s: Resolve() error = %v", tc.name, err)
+		}
+		if resolved.MaxTurnsSet != tc.set {
+			t.Fatalf("%s: MaxTurnsSet = %v, want %v (MaxTurns=%d)", tc.name, resolved.MaxTurnsSet, tc.set, resolved.MaxTurns)
+		}
+	}
+}

internal/config/types.go

@@ -364,6 +364,10 @@ type FileConfig struct {
 	LocalControl        LocalControlConfig `json:"localControl,omitempty"`
 	STT                 STTConfig          `json:"stt,omitempty"`
 	CrossSessionInbound string             `json:"crossSessionInbound,omitempty"`
+	// maxTurnsSet records that some merge source supplied a positive maxTurns —
+	// i.e. the value is configured, not the built-in default. Unexported like
+	// Tools.deferThresholdSet: merge bookkeeping, not a config key.
+	maxTurnsSet bool
 	// Extra preserves top-level fields written by newer Zero versions or
 	// extensions so a read-modify-write through this version is non-destructive.
 	Extra map[string]json.RawMessage `json:"-"`
@@ -461,10 +465,15 @@ type Overrides struct {
 }
 
 type ResolvedConfig struct {
-	ActiveProvider      string
-	Providers           []ProviderProfile
-	Provider            ProviderProfile
-	MaxTurns            int
+	ActiveProvider string
+	Providers      []ProviderProfile
+	Provider       ProviderProfile
+	MaxTurns       int
+	// MaxTurnsSet reports whether MaxTurns came from an explicit source (a
+	// config file, a provider command, ZERO_MAX_TURNS, or CLI overrides) rather
+	// than the built-in default — callers that need a different default can
+	// tell the two apart.
+	MaxTurnsSet         bool
 	MCP                 MCPConfig
 	Sandbox             SandboxConfig
 	Notify              NotifyConfig

internal/daemon/pool_test.go

@@ -7,6 +7,8 @@ import (
 	"sync/atomic"
 	"testing"
 	"time"
+
+	"github.com/Gitlawb/zero/internal/testutil"
 )
 
 // --- test doubles ---------------------------------------------------------
@@ -191,7 +193,7 @@ func TestPoolQueuesWhenFull(t *testing.T) {
 	}()
 	<-started
 	// Wait until the first run holds the only slot.
-	waitFor(t, func() bool { return pool.QueueDepth() == 1 })
+	testutil.WaitFor(t, "queue depth 1", func() bool { return pool.QueueDepth() == 1 })
 
 	secondDone := make(chan struct{})
 	go func() {
@@ -224,7 +226,7 @@ func TestPoolDrainKillsStraggler(t *testing.T) {
 		_, _ = pool.Run(context.Background(), WorkerSpec{Session: "a"}, &collectSink{})
 		close(runDone)
 	}()
-	waitFor(t, func() bool { return pool.QueueDepth() == 1 })
+	testutil.WaitFor(t, "queue depth 1", func() bool { return pool.QueueDepth() == 1 })
 
 	pool.Drain() // KillTimeout elapses, straggler is force-killed
 	if atomic.LoadInt32(&straggler.killed) != 1 {
@@ -242,18 +244,6 @@ func TestPoolDrainKillsStraggler(t *testing.T) {
 	}
 }
 
-func waitFor(t *testing.T, cond func() bool) {
-	t.Helper()
-	deadline := time.Now().Add(2 * time.Second)
-	for time.Now().Before(deadline) {
-		if cond() {
-			return
-		}
-		time.Sleep(time.Millisecond)
-	}
-	t.Fatal("condition not met within timeout")
-}
-
 func TestPoolRunSurfacesStdoutReadError(t *testing.T) {
 	// A worker stdout read error must surface as a failure (not be swallowed and
 	// reported as clean success), and the worker is killed so it can't block on an

internal/daemon/server_test.go

@@ -11,6 +11,7 @@ import (
 	"time"
 
 	"github.com/Gitlawb/zero/internal/observability"
+	"github.com/Gitlawb/zero/internal/testutil"
 )
 
 func TestServeSupportsReadOnlyCustomRuntimeDirectory(t *testing.T) {
@@ -34,7 +35,7 @@ func TestServeSupportsReadOnlyCustomRuntimeDirectory(t *testing.T) {
 	srv := newTestServerWithPaths(t, launcher, paths)
 	serveErr := make(chan error, 1)
 	go func() { serveErr <- srv.Serve() }()
-	waitForFile(t, paths.Status)
+	testutil.WaitFor(t, "file "+paths.Status, func() bool { _, err := os.Stat(paths.Status); return err == nil })
 	srv.Shutdown()
 	if err := <-serveErr; err != nil {
 		t.Fatalf("Serve with 0755 custom runtime directory: %v", err)
@@ -212,18 +213,6 @@ func newTestServerWithPaths(t *testing.T, launcher Launcher, paths Paths) *Serve
 	return srv
 }
 
-func waitForFile(t *testing.T, path string) {
-	t.Helper()
-	deadline := time.Now().Add(2 * time.Second)
-	for time.Now().Before(deadline) {
-		if _, err := os.Stat(path); err == nil {
-			return
-		}
-		time.Sleep(2 * time.Millisecond)
-	}
-	t.Fatalf("file %s did not appear within timeout", path)
-}
-
 func TestServerEndToEnd(t *testing.T) {
 	out := []string{`{"type":"event","seq":1}`, `{"type":"event","seq":2}`}
 	launcher, _ := seqLauncher(&fakeWorker{pid: 1, out: out, exitCode: 0})
@@ -231,7 +220,7 @@ func TestServerEndToEnd(t *testing.T) {
 
 	serveErr := make(chan error, 1)
 	go func() { serveErr <- srv.Serve() }()
-	waitForFile(t, paths.Status)
+	testutil.WaitFor(t, "file "+paths.Status, func() bool { _, err := os.Stat(paths.Status); return err == nil })
 
 	// --- run a session and collect its stream-json output ---
 	runClient, err := Dial(paths.Socket)
@@ -384,7 +373,8 @@ func TestServeCleansStatusThroughBoundDirectoryAfterSwap(t *testing.T) {
 
 	serveErr := make(chan error, 1)
 	go func() { serveErr <- srv.Serve() }()
-	waitForFile(t, filepath.Join(movedDir, "d.status"))
+	movedStatus := filepath.Join(movedDir, "d.status")
+	testutil.WaitFor(t, "file "+movedStatus, func() bool { _, err := os.Stat(movedStatus); return err == nil })
 	srv.Shutdown()
 	select {
 	case err := <-serveErr:
@@ -472,7 +462,7 @@ func TestServerSecondInstanceFails(t *testing.T) {
 
 	serveErr := make(chan error, 1)
 	go func() { serveErr <- srv1.Serve() }()
-	waitForFile(t, paths.Status)
+	testutil.WaitFor(t, "file "+paths.Status, func() bool { _, err := os.Stat(paths.Status); return err == nil })
 
 	// A second server on the same paths must refuse to start (single instance).
 	pool2, _ := NewPool(PoolOptions{Size: 1, Launcher: launcher})
@@ -493,7 +483,7 @@ func TestServerRejectsUnknownCommand(t *testing.T) {
 	srv, paths := newTestServer(t, launcher)
 	go func() { _ = srv.Serve() }()
 	defer srv.Shutdown()
-	waitForFile(t, paths.Status)
+	testutil.WaitFor(t, "file "+paths.Status, func() bool { _, err := os.Stat(paths.Status); return err == nil })
 
 	client, err := Dial(paths.Socket)
 	if err != nil {

internal/daemon/session_test.go

@@ -6,6 +6,8 @@ import (
 	"sync/atomic"
 	"testing"
 	"time"
+
+	"github.com/Gitlawb/zero/internal/testutil"
 )
 
 func drain(t *testing.T, buffered []string, live <-chan string) []string {
@@ -111,7 +113,7 @@ func TestSessionLeaseQueuesWhenPoolFull(t *testing.T) {
 	mgr, _ := NewSessionManager(SessionManagerOptions{Pool: pool})
 
 	sa, _ := mgr.Start(context.Background(), WorkerSpec{Session: "a"})
-	waitFor(t, func() bool { return sa.State() == SessionRunning })
+	testutil.WaitFor(t, "session running", func() bool { return sa.State() == SessionRunning })
 
 	sb, _ := mgr.Start(context.Background(), WorkerSpec{Session: "b"})
 	// b must stay queued (its worker not yet launched) while a holds the slot.
@@ -197,7 +199,7 @@ func TestSessionManagerKeepsRunningOverCap(t *testing.T) {
 
 	s1, _ := mgr.Start(context.Background(), WorkerSpec{Session: "r1"})
 	s2, _ := mgr.Start(context.Background(), WorkerSpec{Session: "r2"})
-	waitFor(t, func() bool { return s1.State() == SessionRunning && s2.State() == SessionRunning })
+	testutil.WaitFor(t, "both sessions running", func() bool { return s1.State() == SessionRunning && s2.State() == SessionRunning })
 	if _, ok := mgr.Get("r1"); !ok {
 		t.Fatal("a running session must never be evicted, even past the cap")
 	}

internal/execution/process_manager.go

@@ -224,6 +224,49 @@ func (manager *ProcessManager) Continue(ctx context.Context, input ProcessContin
 	return result, nil
 }
 
+// WriteInput writes bytes to a retained interactive process's stdin without
+// collecting output. Unlike Continue it never drains the pending output
+// buffer, so a concurrent write_stdin poll still sees everything the process
+// emitted; callers that only need the rolling tail use Snapshot instead.
+func (manager *ProcessManager) WriteInput(id int, data []byte) error {
+	process, ok := manager.get(id)
+	if !ok {
+		return ErrProcessNotFound
+	}
+	process.touch()
+	if len(data) == 0 {
+		return nil
+	}
+	if !process.tty || process.stdin == nil {
+		return ErrProcessStdinDisabled
+	}
+	if _, err := process.stdin.Write(data); err != nil && !process.doneClosed() {
+		return err
+	}
+	return nil
+}
+
+// ResizeInput updates the PTY window size of a retained interactive process
+// so an attached terminal can fill its viewport. Non-positive dimensions are
+// a no-op; platforms without PTY support report the transport's error.
+func (manager *ProcessManager) ResizeInput(id int, cols, rows int) error {
+	if cols <= 0 || rows <= 0 {
+		return nil
+	}
+	process, ok := manager.get(id)
+	if !ok {
+		return ErrProcessNotFound
+	}
+	process.touch()
+	if !process.tty || process.stdin == nil {
+		return ErrProcessStdinDisabled
+	}
+	if err := resizePTY(process.stdin, cols, rows); err != nil && !process.doneClosed() {
+		return err
+	}
+	return nil
+}
+
 func clampInitialProcessWait(wait time.Duration) time.Duration {
 	return min(wait, maxInteractiveYield)
 }

internal/execution/process_manager_test.go

@@ -2,6 +2,7 @@ package execution
 
 import (
 	"context"
+	"errors"
 	"io"
 	"os"
 	"os/exec"
@@ -85,6 +86,126 @@ func TestProcessManagerInterruptsRetainedProcess(t *testing.T) {
 	}
 }
 
+func TestProcessManagerWriteInputUnknownProcess(t *testing.T) {
+	manager := NewProcessManager(ProcessManagerOptions{})
+	if err := manager.WriteInput(4242, []byte("x")); !errors.Is(err, ErrProcessNotFound) {
+		t.Fatalf("WriteInput unknown id = %v, want ErrProcessNotFound", err)
+	}
+}
+
+func TestProcessManagerWriteInputRejectsPipeProcess(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("test command uses a POSIX shell")
+	}
+	root := t.TempDir()
+	manager := NewProcessManager(ProcessManagerOptions{})
+	command := exec.Command("/bin/sh", "-c", "sleep 30")
+	started, err := manager.Start(context.Background(), ProcessStart{
+		Prepared: PreparedCommand{Command: command}, Request: processManagerRequest(root, command),
+	}, time.Millisecond)
+	if err != nil {
+		t.Fatalf("Start: %v", err)
+	}
+	defer manager.Stop(started.ProcessID)
+	if started.TTY {
+		t.Fatal("pipe process reported a TTY")
+	}
+	if err := manager.WriteInput(started.ProcessID, []byte("x")); !errors.Is(err, ErrProcessStdinDisabled) {
+		t.Fatalf("WriteInput pipe process = %v, want ErrProcessStdinDisabled", err)
+	}
+	if err := manager.WriteInput(started.ProcessID, nil); err != nil {
+		t.Fatalf("WriteInput empty data = %v, want nil", err)
+	}
+}
+
+func TestProcessManagerWriteInputDoesNotDrainPendingOutput(t *testing.T) {
+	if runtime.GOOS != "linux" {
+		t.Skip("PTY sessions are only available on Linux")
+	}
+	root := t.TempDir()
+	manager := NewProcessManager(ProcessManagerOptions{})
+	command := exec.CommandContext(context.Background(), "cat")
+	started, err := manager.Start(context.Background(), ProcessStart{
+		Prepared: PreparedCommand{Command: command}, Request: processManagerRequest(root, command),
+		CommandText: "cat", TTY: true,
+	}, 50*time.Millisecond)
+	if err != nil {
+		t.Skipf("PTY transport unavailable: %v", err)
+	}
+	if !started.TTY {
+		t.Skip("PTY transport fell back to pipes")
+	}
+	defer manager.Stop(started.ProcessID)
+
+	if err := manager.WriteInput(started.ProcessID, []byte("hello\r")); err != nil {
+		t.Fatalf("WriteInput: %v", err)
+	}
+	// The PTY echoes input back into the output stream, so the rolling recent
+	// tail shows what was typed without anything being drained.
+	deadline := time.Now().Add(5 * time.Second)
+	for {
+		snapshot, ok := manager.Snapshot(started.ProcessID)
+		if ok && strings.Contains(snapshot.RecentOutput, "hello") {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("recent output never echoed the input: %q", snapshot.RecentOutput)
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	// WriteInput must not have consumed the pending buffer: a write_stdin-style
+	// Continue still collects the echoed bytes.
+	continued, err := manager.Continue(context.Background(), ProcessContinue{
+		ProcessID: started.ProcessID, Wait: 200 * time.Millisecond,
+	})
+	if err != nil {
+		t.Fatalf("Continue: %v", err)
+	}
+	if !strings.Contains(continued.Output, "hello") {
+		t.Fatalf("WriteInput drained the pending output: continued output = %q", continued.Output)
+	}
+}
+
+func TestProcessManagerResizeInputUnknownProcess(t *testing.T) {
+	manager := NewProcessManager(ProcessManagerOptions{})
+	if err := manager.ResizeInput(4242, 100, 40); !errors.Is(err, ErrProcessNotFound) {
+		t.Fatalf("ResizeInput unknown id = %v, want ErrProcessNotFound", err)
+	}
+}
+
+func TestProcessManagerResizeInputUpdatesWindowSize(t *testing.T) {
+	if runtime.GOOS != "linux" {
+		t.Skip("PTY sessions are only available on Linux")
+	}
+	root := t.TempDir()
+	manager := NewProcessManager(ProcessManagerOptions{})
+	command := exec.CommandContext(context.Background(), "/bin/sh", "-c", "sleep 0.3; stty size")
+	started, err := manager.Start(context.Background(), ProcessStart{
+		Prepared: PreparedCommand{Command: command}, Request: processManagerRequest(root, command),
+		CommandText: "stty size", TTY: true,
+	}, time.Millisecond)
+	if err != nil {
+		t.Skipf("PTY transport unavailable: %v", err)
+	}
+	if !started.TTY {
+		t.Skip("PTY transport fell back to pipes")
+	}
+	defer manager.Stop(started.ProcessID)
+
+	if err := manager.ResizeInput(started.ProcessID, 100, 40); err != nil {
+		t.Fatalf("ResizeInput: %v", err)
+	}
+	continued, err := manager.Continue(context.Background(), ProcessContinue{
+		ProcessID: started.ProcessID, Wait: 2 * time.Second,
+	})
+	if err != nil {
+		t.Fatalf("Continue: %v", err)
+	}
+	if combined := started.Output + continued.Output; !strings.Contains(combined, "40 100") {
+		t.Fatalf("stty size output = %q, want %q", combined, "40 100")
+	}
+}
+
 func TestManagedProcessTerminateSkipsReapedProcess(t *testing.T) {
 	reaped := make(chan struct{})
 	close(reaped)

internal/execution/pty_fallback.go

@@ -11,3 +11,7 @@ import (
 func startPTYProcess(_ *exec.Cmd, _ io.Writer) (io.WriteCloser, func(), error) {
 	return nil, nil, errors.New("pty transport is unavailable on this platform")
 }
+
+func resizePTY(_ io.Writer, _, _ int) error {
+	return errors.New("pty transport is unavailable on this platform")
+}

internal/execution/pty_linux.go

@@ -48,6 +48,9 @@ func openPTY() (*os.File, *os.File, error) {
 		_ = master.Close()
 		return nil, nil, err
 	}
+	// A fresh PTY defaults to a 0x0 window; seed a sane size so the process
+	// never sees zero dimensions before an attached client reports its own.
+	_ = unix.IoctlSetWinsize(masterFD, unix.TIOCSWINSZ, &unix.Winsize{Row: 24, Col: 80})
 	pts, err := unix.IoctlGetInt(masterFD, unix.TIOCGPTN)
 	if err != nil {
 		_ = master.Close()
@@ -80,3 +83,16 @@ func hardenPTYProcess(command *exec.Cmd) {
 		return nil
 	}
 }
+
+// resizePTY reports a new window size to the PTY behind an interactive
+// process's stdin writer, so full-screen attached terminals drive the
+// session's own line wrapping.
+func resizePTY(w io.Writer, cols, rows int) error {
+	file, ok := w.(interface{ Fd() uintptr })
+	if !ok {
+		return errors.New("pty transport is unavailable on this platform")
+	}
+	return unix.IoctlSetWinsize(int(file.Fd()), unix.TIOCSWINSZ, &unix.Winsize{
+		Row: uint16(rows), Col: uint16(cols),
+	})
+}

internal/mcp/network_client.go

@@ -216,6 +216,9 @@ func (client *networkClient) request(ctx context.Context, method string, params
 	if err != nil {
 		return err
 	}
+	if message.isRequestOrNotification() {
+		return fmt.Errorf("MCP %s expected a response from server %s, got method %q instead", method, client.server.Name, message.Method)
+	}
 	if !rpcIDMatches(message.ID, id) {
 		return fmt.Errorf("MCP %s response id mismatch for server %s", method, client.server.Name)
 	}

internal/mcp/network_client_test.go

@@ -316,6 +316,50 @@ func TestNonOAuthServerIsUnaffected(t *testing.T) {
 	}
 }
 
+func TestNetworkClientRejectsServerInitiatedRequestAsResponse(t *testing.T) {
+	// A streamable-HTTP server that answers a tools/call POST with a
+	// method-bearing frame (a server-initiated request) must surface a protocol
+	// error rather than an empty, error-free result.
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		message := readHTTPRPCMessage(t, r)
+		switch message.Method {
+		case "initialize":
+			writeHTTPRPCResponse(t, w, message.ID, map[string]any{"protocolVersion": "2024-11-05"})
+		case "notifications/initialized":
+			w.WriteHeader(http.StatusAccepted)
+		case "tools/call":
+			w.Header().Set("Content-Type", "application/json")
+			if _, err := w.Write([]byte(`{"jsonrpc":"2.0","id":` + string(mustRaw(message.ID)) + `,"method":"roots/list","params":{}}`)); err != nil {
+				t.Errorf("write server request: %v", err)
+			}
+		default:
+			writeHTTPRPCResponse(t, w, message.ID, map[string]any{})
+		}
+	}))
+	defer upstream.Close()
+
+	client, err := Connect(ctx, Server{Name: "plain", Type: ServerTypeHTTP, URL: upstream.URL})
+	if err != nil {
+		t.Fatalf("Connect() error = %v", err)
+	}
+	defer func() {
+		if err := client.Close(); err != nil {
+			t.Fatalf("Close() error = %v", err)
+		}
+	}()
+
+	result, err := client.CallTool(ctx, "lookup", map[string]any{"query": "zero"})
+	if err == nil {
+		t.Fatalf("CallTool() error = nil, result = %#v, want protocol error", result)
+	}
+	if !strings.Contains(err.Error(), `"roots/list"`) {
+		t.Fatalf("CallTool() error = %q, want it to name the unexpected method", err)
+	}
+}
+
 func TestDecodeSSERPCMessageSkipsNotifications(t *testing.T) {
 	// A leading server notification (has a method) on the POST's event stream must
 	// be skipped so the actual response (no method) is returned, instead of the

internal/oauth/loopback.go

@@ -20,6 +20,7 @@ type LoopbackListener struct {
 	state    string
 	result   chan callbackResult
 	server   *http.Server
+	done     chan struct{}
 }
 
 type callbackResult struct {
@@ -38,6 +39,14 @@ func NewLoopbackListener(state string) (*LoopbackListener, error) {
 // port (0 = OS-assigned). Used by ChatGPT OAuth which requires a fixed
 // redirect_uri of http://localhost:1455/auth/callback.
 func NewLoopbackListenerOnPort(state string, port int) (*LoopbackListener, error) {
+	return newLoopbackListener(state, port, nil)
+}
+
+// newLoopbackListener is NewLoopbackListenerOnPort with an optional ConnState
+// hook, set before the Serve goroutine starts so tests can synchronize on
+// connection lifecycle events (e.g. a stalled request header being accepted)
+// without racing the running server.
+func newLoopbackListener(state string, port int, connState func(net.Conn, http.ConnState)) (*LoopbackListener, error) {
 	if strings.TrimSpace(state) == "" {
 		return nil, errors.New("oauth: loopback listener requires a non-empty CSRF state")
 	}
@@ -49,9 +58,20 @@ func NewLoopbackListenerOnPort(state string, port int) (*LoopbackListener, error
 		listener: ln,
 		state:    state,
 		result:   make(chan callbackResult, 1),
+		done:     make(chan struct{}),
 	}
-	l.server = &http.Server{Handler: http.HandlerFunc(l.handle)}
-	go func() { _ = l.server.Serve(ln) }()
+	l.server = &http.Server{
+		Handler: http.HandlerFunc(l.handle),
+		// This is a single-use, loopback-only callback server: a client that
+		// never finishes sending its request header must not be able to hold
+		// the accepted connection (and Close, below) open indefinitely.
+		ReadHeaderTimeout: 5 * time.Second,
+		ConnState:         connState,
+	}
+	go func() {
+		_ = l.server.Serve(ln)
+		close(l.done)
+	}()
 	return l, nil
 }
 
@@ -99,11 +119,17 @@ func (l *LoopbackListener) Wait(ctx context.Context) (string, error) {
 	}
 }
 
-// Close shuts the listener down (bounded), idempotent.
+// Close shuts the listener down (bounded), idempotent. If a client leaves a
+// connection open past the shutdown deadline (e.g. a stalled request header),
+// Close forcibly closes it rather than leaking it past the end of the flow,
+// and waits for the Serve goroutine to finish before returning.
 func (l *LoopbackListener) Close() {
 	shutdownCtx, cancel := context.WithTimeout(context.Background(), time.Second)
 	defer cancel()
-	_ = l.server.Shutdown(shutdownCtx)
+	if err := l.server.Shutdown(shutdownCtx); err != nil {
+		_ = l.server.Close()
+	}
+	<-l.done
 }
 
 // parseCallback validates the redirect query and returns the authorization code,

internal/oauth/loopback_test.go

@@ -3,6 +3,9 @@ package oauth
 import (
 	"context"
 	"errors"
+	"fmt"
+	"io"
+	"net"
 	"net/http"
 	"strings"
 	"testing"
@@ -122,3 +125,99 @@ func TestLoopbackProviderError(t *testing.T) {
 		t.Fatalf("Wait err = %v, want provider error", err)
 	}
 }
+
+func TestLoopbackCloseForceClosesSlowHeaderConnection(t *testing.T) {
+	accepted := make(chan struct{}, 1)
+	l, err := newLoopbackListener("audit-state", 0, func(_ net.Conn, state http.ConnState) {
+		// StateNew fires as soon as Serve accepts the connection, before it
+		// blocks reading the (never-completed) header. That's the earliest
+		// point at which net/http's Shutdown will treat this connection as
+		// non-idle, which is what this test needs to exercise.
+		if state == http.StateNew {
+			select {
+			case accepted <- struct{}{}:
+			default:
+			}
+		}
+	})
+	if err != nil {
+		t.Fatalf("NewLoopbackListener: %v", err)
+	}
+	t.Cleanup(l.Close)
+	addr := l.listener.Addr().String()
+	conn, err := net.Dial("tcp", addr)
+	if err != nil {
+		t.Fatalf("Dial: %v", err)
+	}
+	defer conn.Close()
+	// Wait for Serve to accept the connection before sending a request line
+	// and a header key with no terminating CRLF, so Serve is guaranteed to
+	// be blocked reading a partial header (rather than a fixed sleep guessing
+	// that Accept has run).
+	select {
+	case <-accepted:
+	case <-time.After(3 * time.Second):
+		t.Fatal("server never accepted the connection")
+	}
+	fmt.Fprintf(conn, "GET /callback?code=audit-code&state=audit-state HTTP/1.1\r\nHost: %s\r\nX-Stall:", addr)
+
+	started := time.Now()
+	l.Close()
+	if elapsed := time.Since(started); elapsed < 900*time.Millisecond {
+		t.Fatalf("Close returned after %s; expected it to wait out its one-second shutdown deadline first", elapsed)
+	}
+
+	conn.SetReadDeadline(time.Now().Add(time.Second))
+	var one [1]byte
+	_, readErr := conn.Read(one[:])
+	if readErr == nil {
+		t.Fatal("read after Close succeeded; wanted the stalled connection to be closed")
+	}
+	if netErr, ok := readErr.(net.Error); ok && netErr.Timeout() {
+		t.Fatalf("read after Close timed out (%v); wanted the stalled connection closed rather than left open", readErr)
+	}
+}
+
+func TestLoopbackCloseIsIdempotent(t *testing.T) {
+	l, err := NewLoopbackListener("s")
+	if err != nil {
+		t.Fatalf("NewLoopbackListener: %v", err)
+	}
+	l.Close()
+	l.Close() // must not panic or hang
+}
+
+func TestLoopbackCloseReturnsPromptlyAfterSuccessfulCallback(t *testing.T) {
+	l, err := NewLoopbackListener("s")
+	if err != nil {
+		t.Fatalf("NewLoopbackListener: %v", err)
+	}
+	t.Cleanup(l.Close)
+	requestDone := make(chan struct{})
+	go func() {
+		defer close(requestDone)
+		resp, err := http.Get(l.RedirectURI() + "?code=x&state=s")
+		if err == nil {
+			_, _ = io.Copy(io.Discard, resp.Body)
+			resp.Body.Close()
+		}
+	}()
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	if _, err := l.Wait(ctx); err != nil {
+		t.Fatalf("Wait: %v", err)
+	}
+	// Join the client goroutine so the response is fully read (and its
+	// connection returned to idle) before timing Close, instead of racing it.
+	select {
+	case <-requestDone:
+	case <-time.After(3 * time.Second):
+		t.Fatal("http.Get goroutine did not complete")
+	}
+
+	started := time.Now()
+	l.Close()
+	if elapsed := time.Since(started); elapsed > 500*time.Millisecond {
+		t.Fatalf("Close took %s after a completed, idle callback; want a prompt return", elapsed)
+	}
+}

internal/providers/anthropic/provider.go

@@ -90,6 +90,7 @@ type Options struct {
 	// When unset, Zero uses providerio.ResolveStreamIdleTimeout — the
 	// ZERO_STREAM_IDLE_TIMEOUT override or providerio.DefaultStreamIdleTimeout.
 	StreamIdleTimeout time.Duration
+	SessionHeader     string
 }
 
 // Provider streams completions from Anthropic's Messages API.
@@ -108,6 +109,7 @@ type Provider struct {
 	httpClient        *http.Client
 	userAgent         string
 	streamIdleTimeout time.Duration
+	sessionHeader     providerio.SessionHeader
 }
 
 // New creates an Anthropic provider.
@@ -143,6 +145,7 @@ func New(options Options) (*Provider, error) {
 		httpClient:        providerio.HTTPClient(options.HTTPClient),
 		userAgent:         options.UserAgent,
 		streamIdleTimeout: providerio.ResolveStreamIdleTimeout(options.StreamIdleTimeout),
+		sessionHeader:     providerio.NewSessionHeader(options.SessionHeader),
 	}, nil
 }
 
@@ -163,12 +166,12 @@ func (provider *Provider) StreamCompletion(
 	events := make(chan zeroruntime.StreamEvent, 16)
 	go func() {
 		defer close(events)
-		provider.stream(ctx, body, events)
+		provider.stream(ctx, body, request.PromptCacheKey, events)
 	}()
 	return events, nil
 }
 
-func (provider *Provider) stream(ctx context.Context, body []byte, events chan<- zeroruntime.StreamEvent) {
+func (provider *Provider) stream(ctx context.Context, body []byte, sessionID string, events chan<- zeroruntime.StreamEvent) {
 	// streamCtx lets the idle watchdog abort an in-flight body read by cancelling
 	// the request, which unblocks the SSE reader goroutine.
 	streamCtx, cancelStream := context.WithCancel(ctx)
@@ -185,6 +188,7 @@ func (provider *Provider) stream(ctx context.Context, body []byte, events chan<-
 		},
 		provider.oauthResolver,
 		func(request *http.Request) {
+			provider.sessionHeader.Apply(request, sessionID)
 			request.Header.Set("Content-Type", "application/json")
 			request.Header.Set("anthropic-version", provider.version)
 			if provider.beta != "" {

internal/providers/factory.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"net/http"
+	"net/url"
 	"strings"
 
 	"github.com/Gitlawb/zero/internal/config"
@@ -53,6 +54,11 @@ func New(profile config.ProviderProfile, options Options) (zeroruntime.Provider,
 		return newCodexProvider(profile, resolved, options)
 	}
 
+	sessionHeader := sessionHeaderForProfile(profile, resolved)
+	if sessionHeader != "" && strings.TrimSpace(options.UserAgent) == "" {
+		options.UserAgent = "zero"
+	}
+
 	switch resolved.providerKind {
 	case config.ProviderKindOpenAI, config.ProviderKindOpenAICompatible:
 		// prompt_cache_key is an OpenAI-only chat-completions field. Strict
@@ -74,6 +80,7 @@ func New(profile config.ProviderProfile, options Options) (zeroruntime.Provider,
 			UserAgent:             options.UserAgent,
 			ParseThinkTags:        parseThinkTagsForProfile(profile, resolved),
 			DisablePromptCacheKey: resolved.providerKind == config.ProviderKindOpenAICompatible,
+			SessionHeader:         sessionHeader,
 		})
 	case config.ProviderKindAnthropic, config.ProviderKindAnthropicCompat:
 		return anthropic.New(anthropic.Options{
@@ -88,6 +95,7 @@ func New(profile config.ProviderProfile, options Options) (zeroruntime.Provider,
 			MaxTokens:       resolved.maxOutputTokens,
 			HTTPClient:      options.HTTPClient,
 			UserAgent:       options.UserAgent,
+			SessionHeader:   sessionHeader,
 		})
 	case config.ProviderKindGoogle:
 		return gemini.New(gemini.Options{
@@ -345,6 +353,18 @@ func isCodexCatalog(profile config.ProviderProfile, _ resolvedProfile) bool {
 	return providercatalog.NormalizeID(profile.CatalogID) == "chatgpt"
 }
 
+func sessionHeaderForProfile(profile config.ProviderProfile, resolved resolvedProfile) string {
+	switch providercatalog.NormalizeID(profile.CatalogID) {
+	case "opencode", "opencode-go", "opencode-go-anthropic-compatible":
+		return "x-opencode-session"
+	}
+	endpoint, err := url.Parse(resolved.baseURL)
+	if err == nil && strings.EqualFold(endpoint.Hostname(), "opencode.ai") && (endpoint.Path == "/zen" || strings.HasPrefix(endpoint.Path, "/zen/")) {
+		return "x-opencode-session"
+	}
+	return ""
+}
+
 // newCodexProvider builds a Codex-flavored openai provider for the chatgpt
 // catalog. The Codex headers (`originator`, `chatgpt-account-id`) are
 // injected by the CodexProvider wrapper. The `chatgpt-account-id` is read from

internal/providers/factory_test.go

@@ -3,13 +3,17 @@ package providers
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 	"io"
 	"net/http"
 	"strings"
+	"sync"
+	"sync/atomic"
 	"testing"
 
 	"github.com/Gitlawb/zero/internal/config"
 	"github.com/Gitlawb/zero/internal/oauth"
+	"github.com/Gitlawb/zero/internal/providers/providerio"
 	"github.com/Gitlawb/zero/internal/zeroruntime"
 )
 
@@ -794,3 +798,566 @@ func TestResolveRuntimeMetadataRejectsModelOutsideProviderAllowlist(t *testing.T
 		t.Fatalf("error = %q, want it to name the rejected model", err.Error())
 	}
 }
+
+func TestOpenCodeSessionHeader(t *testing.T) {
+	const sessionHeader = "x-opencode-session"
+	tests := []struct {
+		name       string
+		profile    config.ProviderProfile
+		response   string
+		wantHeader bool
+		wantAuth   map[string]string
+	}{
+		{
+			name: "catalog opencode-go default URL",
+			profile: config.ProviderProfile{
+				Name:         "opencode-go",
+				CatalogID:    "opencode-go",
+				ProviderKind: config.ProviderKindOpenAICompatible,
+				APIKey:       "sk-oc-go",
+				Model:        "deepseek-v4-pro",
+			},
+			response:   "data: [DONE]\n\n",
+			wantHeader: true,
+			wantAuth:   map[string]string{"Authorization": "Bearer sk-oc-go"},
+		},
+		{
+			name: "catalog opencode-go-anthropic-compatible",
+			profile: config.ProviderProfile{
+				Name:         "opencode-go-anthropic",
+				CatalogID:    "opencode-go-anthropic-compatible",
+				ProviderKind: config.ProviderKindAnthropicCompat,
+				APIKey:       "sk-oc-ant",
+				Model:        "minimax-m3",
+			},
+			response:   "data: {\"type\":\"message_stop\"}\n\n",
+			wantHeader: true,
+			wantAuth:   map[string]string{"x-api-key": "sk-oc-ant"},
+		},
+		{
+			name: "catalog opencode Zen",
+			profile: config.ProviderProfile{
+				Name:         "opencode-zen",
+				CatalogID:    "opencode",
+				ProviderKind: config.ProviderKindOpenAICompatible,
+				APIKey:       "sk-zen",
+				Model:        "test-model",
+			},
+			response:   "data: [DONE]\n\n",
+			wantHeader: true,
+			wantAuth:   map[string]string{"Authorization": "Bearer sk-zen"},
+		},
+		{
+			name: "renamed catalog profile with custom proxy URL",
+			profile: config.ProviderProfile{
+				Name:         "my-opencode",
+				CatalogID:    "opencode-go",
+				ProviderKind: config.ProviderKindOpenAICompatible,
+				BaseURL:      "https://proxy.example/v1",
+				APIKey:       "sk-proxy",
+				Model:        "test-model",
+			},
+			response:   "data: [DONE]\n\n",
+			wantHeader: true,
+			wantAuth:   map[string]string{"Authorization": "Bearer sk-proxy"},
+		},
+		{
+			name: "catalog-less OpenAI-compatible OpenCode Go URL",
+			profile: config.ProviderProfile{
+				Name:         "manual-go",
+				ProviderKind: config.ProviderKindOpenAICompatible,
+				BaseURL:      "https://opencode.ai/zen/go/v1",
+				APIKey:       "sk-manual",
+				Model:        "test-model",
+			},
+			response:   "data: [DONE]\n\n",
+			wantHeader: true,
+			wantAuth:   map[string]string{"Authorization": "Bearer sk-manual"},
+		},
+		{
+			name: "catalog-less Anthropic-compatible OpenCode Go URL",
+			profile: config.ProviderProfile{
+				Name:         "manual-go-anthropic",
+				ProviderKind: config.ProviderKindAnthropicCompat,
+				BaseURL:      "https://opencode.ai/zen/go",
+				APIKey:       "sk-manual-ant",
+				Model:        "test-model",
+			},
+			response:   "data: {\"type\":\"message_stop\"}\n\n",
+			wantHeader: true,
+			wantAuth:   map[string]string{"x-api-key": "sk-manual-ant"},
+		},
+		{
+			name: "official OpenAI",
+			profile: config.ProviderProfile{
+				Name:         "openai",
+				ProviderKind: config.ProviderKindOpenAI,
+				APIKey:       "sk-openai",
+				Model:        "test-model",
+			},
+			response:   "data: [DONE]\n\n",
+			wantHeader: false,
+			wantAuth:   map[string]string{"Authorization": "Bearer sk-openai"},
+		},
+		{
+			name: "generic OpenAI-compatible",
+			profile: config.ProviderProfile{
+				Name:         "generic",
+				ProviderKind: config.ProviderKindOpenAICompatible,
+				BaseURL:      "https://provider.example/v1",
+				APIKey:       "sk-generic",
+				Model:        "test-model",
+			},
+			response:   "data: [DONE]\n\n",
+			wantHeader: false,
+			wantAuth:   map[string]string{"Authorization": "Bearer sk-generic"},
+		},
+		{
+			name: "official Anthropic",
+			profile: config.ProviderProfile{
+				Name:         "anthropic",
+				ProviderKind: config.ProviderKindAnthropic,
+				APIKey:       "sk-ant",
+				Model:        "test-model",
+			},
+			response:   "data: {\"type\":\"message_stop\"}\n\n",
+			wantHeader: false,
+			wantAuth:   map[string]string{"x-api-key": "sk-ant"},
+		},
+		{
+			name: "lookalike subdomain is not OpenCode",
+			profile: config.ProviderProfile{
+				Name:         "deceptive-host",
+				ProviderKind: config.ProviderKindOpenAICompatible,
+				BaseURL:      "https://opencode.ai.example/zen/go/v1",
+				APIKey:       "sk-fake",
+				Model:        "test-model",
+			},
+			response:   "data: [DONE]\n\n",
+			wantHeader: false,
+			wantAuth:   map[string]string{"Authorization": "Bearer sk-fake"},
+		},
+		{
+			name: "lookalike path is not OpenCode",
+			profile: config.ProviderProfile{
+				Name:         "deceptive-path",
+				ProviderKind: config.ProviderKindOpenAICompatible,
+				BaseURL:      "https://example.com/opencode.ai/zen/go",
+				APIKey:       "sk-fake",
+				Model:        "test-model",
+			},
+			response:   "data: [DONE]\n\n",
+			wantHeader: false,
+			wantAuth:   map[string]string{"Authorization": "Bearer sk-fake"},
+		},
+		{
+			name: "zenith path is not Zen",
+			profile: config.ProviderProfile{
+				Name:         "zenith",
+				ProviderKind: config.ProviderKindOpenAICompatible,
+				BaseURL:      "https://opencode.ai/zenith",
+				APIKey:       "sk-zenith",
+				Model:        "test-model",
+			},
+			response:   "data: [DONE]\n\n",
+			wantHeader: false,
+			wantAuth:   map[string]string{"Authorization": "Bearer sk-zenith"},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			transport := &captureTransport{responseBody: test.response}
+			provider, err := New(test.profile, Options{
+				HTTPClient: &http.Client{Transport: transport},
+				UserAgent:  "zero-test",
+			})
+			if err != nil {
+				t.Fatalf("New() error = %v", err)
+			}
+			stream, err := provider.StreamCompletion(context.Background(), zeroruntime.CompletionRequest{
+				Messages:       []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "hello"}},
+				PromptCacheKey: "conversation-a",
+			})
+			if err != nil {
+				t.Fatalf("StreamCompletion() error = %v", err)
+			}
+			drainStream(t, stream)
+			if transport.request == nil {
+				t.Fatal("HTTP client was not used")
+			}
+			got := transport.request.Header.Get(sessionHeader)
+			if test.wantHeader && got != "conversation-a" {
+				t.Fatalf("%s = %q, want %q", sessionHeader, got, "conversation-a")
+			}
+			if !test.wantHeader && got != "" {
+				t.Fatalf("%s = %q, want no session header", sessionHeader, got)
+			}
+			for header, want := range test.wantAuth {
+				if got := transport.request.Header.Get(header); got != want {
+					t.Fatalf("%s = %q, want %q", header, got, want)
+				}
+			}
+			if got := transport.request.Header.Get("User-Agent"); got != "zero-test" {
+				t.Fatalf("User-Agent = %q, want zero-test", got)
+			}
+			if test.profile.ProviderKind == config.ProviderKindOpenAICompatible {
+				var body map[string]any
+				if err := json.NewDecoder(transport.body()).Decode(&body); err != nil {
+					t.Fatalf("decode request body: %v", err)
+				}
+				if _, ok := body["prompt_cache_key"]; ok {
+					t.Fatalf("openai-compatible body carried prompt_cache_key: %#v", body["prompt_cache_key"])
+				}
+			}
+		})
+	}
+}
+
+func TestOpenCodeSessionHeaderFollowsConversationKey(t *testing.T) {
+	transport := &recordingTransport{status: http.StatusOK, body: "data: [DONE]\n\n"}
+	profile := config.ProviderProfile{
+		Name:         "opencode-go",
+		CatalogID:    "opencode-go",
+		ProviderKind: config.ProviderKindOpenAICompatible,
+		APIKey:       "sk-oc",
+		Model:        "test-model",
+	}
+	options := Options{HTTPClient: &http.Client{Transport: transport}, UserAgent: "zero-test"}
+	provider, err := New(profile, options)
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	for _, key := range []string{"conversation-a", "conversation-a", "conversation-b"} {
+		stream, err := provider.StreamCompletion(context.Background(), zeroruntime.CompletionRequest{
+			Messages:       []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "hello"}},
+			PromptCacheKey: key,
+		})
+		if err != nil {
+			t.Fatalf("StreamCompletion() error = %v", err)
+		}
+		drainStream(t, stream)
+	}
+	got := transport.sessionHeaders()
+	want := []string{"conversation-a", "conversation-a", "conversation-b"}
+	if len(got) != len(want) {
+		t.Fatalf("captured %d requests, want %d", len(got), len(want))
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("request %d x-opencode-session = %q, want %q", i, got[i], want[i])
+		}
+	}
+
+	reconstructed, err := New(profile, options)
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	stream, err := reconstructed.StreamCompletion(context.Background(), zeroruntime.CompletionRequest{
+		Messages:       []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "hello"}},
+		PromptCacheKey: "conversation-a",
+	})
+	if err != nil {
+		t.Fatalf("StreamCompletion() error = %v", err)
+	}
+	drainStream(t, stream)
+	got = transport.sessionHeaders()
+	if last := got[len(got)-1]; last != "conversation-a" {
+		t.Fatalf("reconstructed provider sent %s = %q, want conversation-a", "x-opencode-session", last)
+	}
+}
+
+func TestOpenCodeSessionHeaderCustomOverride(t *testing.T) {
+	custom := map[string]string{"X-Opencode-Session": "explicit-session"}
+	profile := config.ProviderProfile{
+		Name:          "opencode-go",
+		CatalogID:     "opencode-go",
+		ProviderKind:  config.ProviderKindOpenAICompatible,
+		APIKey:        "sk-oc",
+		Model:         "test-model",
+		CustomHeaders: custom,
+	}
+	transport := &captureTransport{responseBody: "data: [DONE]\n\n"}
+	provider, err := New(profile, Options{HTTPClient: &http.Client{Transport: transport}, UserAgent: "zero-test"})
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	stream, err := provider.StreamCompletion(context.Background(), zeroruntime.CompletionRequest{
+		Messages:       []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "hello"}},
+		PromptCacheKey: "conversation-a",
+	})
+	if err != nil {
+		t.Fatalf("StreamCompletion() error = %v", err)
+	}
+	drainStream(t, stream)
+	if got := transport.request.Header.Get("x-opencode-session"); got != "explicit-session" {
+		t.Fatalf("x-opencode-session = %q, want explicit custom value", got)
+	}
+	if len(custom) != 1 || custom["X-Opencode-Session"] != "explicit-session" {
+		t.Fatalf("profile CustomHeaders mutated: %#v", custom)
+	}
+}
+
+func TestOpenCodeSessionHeaderFallback(t *testing.T) {
+	transport := &recordingTransport{status: http.StatusOK, body: "data: [DONE]\n\n"}
+	profile := config.ProviderProfile{
+		Name:         "opencode-go",
+		CatalogID:    "opencode-go",
+		ProviderKind: config.ProviderKindOpenAICompatible,
+		APIKey:       "sk-oc",
+		Model:        "test-model",
+	}
+	options := Options{HTTPClient: &http.Client{Transport: transport}}
+	first, err := New(profile, options)
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	second, err := New(profile, options)
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	request := zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "hello"}},
+	}
+	for _, provider := range []zeroruntime.Provider{first, first, second} {
+		stream, err := provider.StreamCompletion(context.Background(), request)
+		if err != nil {
+			t.Fatalf("StreamCompletion() error = %v", err)
+		}
+		drainStream(t, stream)
+	}
+	headers := transport.sessionHeaders()
+	if len(headers) != 3 {
+		t.Fatalf("captured %d requests, want 3", len(headers))
+	}
+	if headers[0] == "" || headers[1] != headers[0] {
+		t.Fatalf("fallback headers = %q, %q — want one stable nonempty value per provider", headers[0], headers[1])
+	}
+	if headers[2] == headers[0] {
+		t.Fatalf("distinct provider instances shared fallback %q", headers[0])
+	}
+}
+
+func TestOpenCodeSessionHeaderDefaultsUserAgent(t *testing.T) {
+	transport := &captureTransport{responseBody: "data: [DONE]\n\n"}
+	provider, err := New(config.ProviderProfile{
+		Name:         "opencode-go",
+		CatalogID:    "opencode-go",
+		ProviderKind: config.ProviderKindOpenAICompatible,
+		APIKey:       "sk-oc",
+		Model:        "test-model",
+	}, Options{HTTPClient: &http.Client{Transport: transport}})
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	stream, err := provider.StreamCompletion(context.Background(), zeroruntime.CompletionRequest{
+		Messages: []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "hello"}},
+	})
+	if err != nil {
+		t.Fatalf("StreamCompletion() error = %v", err)
+	}
+	drainStream(t, stream)
+	if got := transport.request.Header.Get("User-Agent"); got != "zero" {
+		t.Fatalf("User-Agent = %q, want zero", got)
+	}
+}
+
+func TestOpenCodeSessionHeaderConcurrent(t *testing.T) {
+	transport := &recordingTransport{status: http.StatusOK, body: "data: [DONE]\n\n"}
+	provider, err := New(config.ProviderProfile{
+		Name:         "opencode-go",
+		CatalogID:    "opencode-go",
+		ProviderKind: config.ProviderKindOpenAICompatible,
+		APIKey:       "sk-oc",
+		Model:        "test-model",
+	}, Options{HTTPClient: &http.Client{Transport: transport}})
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+
+	var wg sync.WaitGroup
+	var errsMu sync.Mutex
+	var errs []string
+	for _, session := range []string{"session-a", "session-b"} {
+		wg.Add(1)
+		go func(session string) {
+			defer wg.Done()
+			for i := 0; i < 5; i++ {
+				stream, err := provider.StreamCompletion(context.Background(), zeroruntime.CompletionRequest{
+					Messages:       []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: fmt.Sprintf("req-%s-%d", session, i)}},
+					PromptCacheKey: session,
+				})
+				if err != nil {
+					errsMu.Lock()
+					errs = append(errs, err.Error())
+					errsMu.Unlock()
+					return
+				}
+				for event := range stream {
+					if event.Type == zeroruntime.StreamEventError {
+						errsMu.Lock()
+						errs = append(errs, event.Error)
+						errsMu.Unlock()
+					}
+				}
+			}
+		}(session)
+	}
+	wg.Wait()
+	for _, errText := range errs {
+		t.Errorf("concurrent stream error: %s", errText)
+	}
+
+	requests := transport.recorded()
+	if len(requests) != 10 {
+		t.Fatalf("captured %d requests, want 10", len(requests))
+	}
+	for _, request := range requests {
+		var payload struct {
+			Messages []struct {
+				Content string `json:"content"`
+			} `json:"messages"`
+		}
+		if err := json.Unmarshal([]byte(request.body), &payload); err != nil {
+			t.Fatalf("decode request body: %v", err)
+		}
+		if len(payload.Messages) == 0 {
+			t.Fatal("request carried no user message")
+		}
+		content := payload.Messages[0].Content
+		want := "session-a"
+		if strings.Contains(content, "session-b") {
+			want = "session-b"
+		}
+		if got := request.header.Get("x-opencode-session"); got != want {
+			t.Fatalf("request for %q carried x-opencode-session %q, want %q", content, got, want)
+		}
+	}
+}
+
+func TestOpenCodeSessionHeaderAuthRetry(t *testing.T) {
+	for _, test := range []struct {
+		name     string
+		profile  config.ProviderProfile
+		response string
+	}{
+		{
+			name: "openai-compatible",
+			profile: config.ProviderProfile{
+				Name:         "opencode-go",
+				CatalogID:    "opencode-go",
+				ProviderKind: config.ProviderKindOpenAICompatible,
+				APIKey:       "sk-oc",
+				Model:        "test-model",
+			},
+			response: "data: [DONE]\n\n",
+		},
+		{
+			name: "anthropic-compatible",
+			profile: config.ProviderProfile{
+				Name:         "opencode-go-anthropic",
+				CatalogID:    "opencode-go-anthropic-compatible",
+				ProviderKind: config.ProviderKindAnthropicCompat,
+				APIKey:       "sk-oc-ant",
+				Model:        "minimax-m3",
+			},
+			response: "data: {\"type\":\"message_stop\"}\n\n",
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			transport := &recordingTransport{status: http.StatusOK, body: test.response, unauthorized: 1}
+			var calls atomic.Int32
+			resolver := providerio.TokenResolver(func(context.Context, bool) (string, string, bool, error) {
+				n := calls.Add(1)
+				return "Authorization", fmt.Sprintf("Bearer tok-%d", n), true, nil
+			})
+			provider, err := New(test.profile, Options{
+				HTTPClient:    &http.Client{Transport: transport},
+				OAuthResolver: resolver,
+			})
+			if err != nil {
+				t.Fatalf("New() error = %v", err)
+			}
+			stream, err := provider.StreamCompletion(context.Background(), zeroruntime.CompletionRequest{
+				Messages:       []zeroruntime.Message{{Role: zeroruntime.MessageRoleUser, Content: "hello"}},
+				PromptCacheKey: "conversation-a",
+			})
+			if err != nil {
+				t.Fatalf("StreamCompletion() error = %v", err)
+			}
+			drainStream(t, stream)
+			requests := transport.recorded()
+			if len(requests) != 2 {
+				t.Fatalf("captured %d requests, want 2 (401 + retry)", len(requests))
+			}
+			for i, request := range requests {
+				if got := request.header.Get("x-opencode-session"); got != "conversation-a" {
+					t.Fatalf("attempt %d x-opencode-session = %q, want conversation-a", i, got)
+				}
+			}
+			if first, second := requests[0].header.Get("Authorization"), requests[1].header.Get("Authorization"); first == second {
+				t.Fatalf("Authorization not refreshed across retry: %q", first)
+			}
+		})
+	}
+}
+
+func drainStream(t *testing.T, stream <-chan zeroruntime.StreamEvent) {
+	t.Helper()
+	for event := range stream {
+		if event.Type == zeroruntime.StreamEventError {
+			t.Fatalf("stream error: %s", event.Error)
+		}
+	}
+}
+
+type recordedRequest struct {
+	header http.Header
+	body   string
+}
+
+type recordingTransport struct {
+	mu           sync.Mutex
+	requests     []recordedRequest
+	status       int
+	body         string
+	unauthorized int
+}
+
+func (transport *recordingTransport) RoundTrip(request *http.Request) (*http.Response, error) {
+	var body string
+	if request.Body != nil {
+		data, _ := io.ReadAll(request.Body)
+		body = string(data)
+	}
+	transport.mu.Lock()
+	transport.requests = append(transport.requests, recordedRequest{header: request.Header.Clone(), body: body})
+	attempt := len(transport.requests)
+	transport.mu.Unlock()
+
+	status := transport.status
+	if attempt <= transport.unauthorized {
+		status = http.StatusUnauthorized
+	}
+	return &http.Response{
+		StatusCode: status,
+		Status:     fmt.Sprintf("%d", status),
+		Header:     make(http.Header),
+		Body:       io.NopCloser(strings.NewReader(transport.body)),
+		Request:    request,
+	}, nil
+}
+
+func (transport *recordingTransport) recorded() []recordedRequest {
+	transport.mu.Lock()
+	defer transport.mu.Unlock()
+	return append([]recordedRequest(nil), transport.requests...)
+}
+
+func (transport *recordingTransport) sessionHeaders() []string {
+	requests := transport.recorded()
+	headers := make([]string, 0, len(requests))
+	for _, request := range requests {
+		headers = append(headers, request.header.Get("x-opencode-session"))
+	}
+	return headers
+}

internal/providers/openai/provider.go

@@ -65,6 +65,7 @@ type Options struct {
 	// enabled; the ZERO_DISABLE_PROMPT_CACHE_KEY env kill switch still applies
 	// on top for any endpoint.
 	DisablePromptCacheKey bool
+	SessionHeader         string
 }
 
 // Provider streams completions from an OpenAI-compatible chat completions API.
@@ -85,6 +86,7 @@ type Provider struct {
 	parseThinkTags        bool
 	setRequestExtra       func(*http.Request)
 	disablePromptCacheKey bool
+	sessionHeader         providerio.SessionHeader
 }
 
 // New creates an OpenAI-compatible provider.
@@ -140,6 +142,7 @@ func New(options Options) (*Provider, error) {
 		parseThinkTags:        options.ParseThinkTags,
 		setRequestExtra:       options.SetRequestExtra,
 		disablePromptCacheKey: options.DisablePromptCacheKey,
+		sessionHeader:         providerio.NewSessionHeader(options.SessionHeader),
 	}, nil
 }
 
@@ -156,13 +159,13 @@ func (provider *Provider) StreamCompletion(
 	events := make(chan zeroruntime.StreamEvent, 16)
 	go func() {
 		defer close(events)
-		provider.stream(ctx, body, events)
+		provider.stream(ctx, body, request.PromptCacheKey, events)
 	}()
 
 	return events, nil
 }
 
-func (provider *Provider) stream(ctx context.Context, body []byte, events chan<- zeroruntime.StreamEvent) {
+func (provider *Provider) stream(ctx context.Context, body []byte, sessionID string, events chan<- zeroruntime.StreamEvent) {
 	endpoint := provider.endpoint
 
 	// streamCtx lets the idle watchdog abort an in-flight body read by cancelling
@@ -186,6 +189,7 @@ func (provider *Provider) stream(ctx context.Context, body []byte, events chan<-
 		},
 		provider.oauthResolver,
 		func(request *http.Request) {
+			provider.sessionHeader.Apply(request, sessionID)
 			request.Header.Set("Content-Type", "application/json")
 			if provider.userAgent != "" {
 				request.Header.Set("User-Agent", provider.userAgent)

internal/providers/providerio/headers.go

@@ -1,6 +1,7 @@
 package providerio
 
 import (
+	"crypto/rand"
 	"net/http"
 	"strings"
 )
@@ -52,6 +53,28 @@ func ApplyAuthHeaders(request *http.Request, options AuthHeaders) {
 	request.Header.Set(header, value)
 }
 
+type SessionHeader struct {
+	name     string
+	fallback string
+}
+
+func NewSessionHeader(name string) SessionHeader {
+	if name == "" {
+		return SessionHeader{}
+	}
+	return SessionHeader{name: name, fallback: rand.Text()}
+}
+
+func (header SessionHeader) Apply(request *http.Request, sessionID string) {
+	if header.name == "" {
+		return
+	}
+	if sessionID = strings.TrimSpace(sessionID); sessionID == "" {
+		sessionID = header.fallback
+	}
+	request.Header.Set(header.name, sessionID)
+}
+
 func CopyHeaders(headers map[string]string) map[string]string {
 	if headers == nil {
 		return nil

internal/providers/providerio/providerio.go

@@ -169,10 +169,53 @@ var sharedHTTPClient = func() *http.Client {
 	// content-stall watchdogs.
 	transport.ResponseHeaderTimeout = 120 * time.Second
 	transport.IdleConnTimeout = 30 * time.Second
+	// Periodically close idle connections to prevent stale HTTP/2
+	// connections from causing PROTOCOL_ERROR on the next request.
+	// OpenRouter (and other HTTP/2 backends) can silently RST or
+	// GOAWAY a connection that has been idle in the pool; the next
+	// request over that connection gets a PROTOCOL_ERROR. Closing
+	// idle connections every 30s forces a fresh dial so the error
+	// window is bounded to ~30s while reuse still benefits healthy
+	// connections. No-op on darwin where DisableKeepAlives already
+	// prevents pooling.
+	if runtime.GOOS != "darwin" {
+		startIdleConnCloser(transport, defaultIdleConnCloseInterval)
+	}
 	transport.DisableKeepAlives = runtime.GOOS == "darwin"
 	return &http.Client{Transport: transport}
 }()
 
+const defaultIdleConnCloseInterval = 30 * time.Second
+
+// startIdleConnCloser launches a background goroutine that periodically closes
+// idle keep-alive connections on transport until the returned stop function is
+// invoked.
+func startIdleConnCloser(transport *http.Transport, interval time.Duration) func() {
+	if interval <= 0 || transport == nil {
+		return func() {}
+	}
+	ticker := time.NewTicker(interval)
+	done := make(chan struct{})
+	go func() {
+		defer ticker.Stop()
+		for {
+			select {
+			case <-done:
+				return
+			case <-ticker.C:
+				transport.CloseIdleConnections()
+			}
+		}
+	}()
+	return func() {
+		select {
+		case <-done:
+		default:
+			close(done)
+		}
+	}
+}
+
 // HTTPClient returns the configured client or the shared, stall-hardened default.
 func HTTPClient(client *http.Client) *http.Client {
 	if client != nil {

internal/providers/providerio/providerio_test.go

@@ -6,6 +6,8 @@ import (
 	"io"
 	"math"
 	"net/http"
+	"net/http/httptest"
+	"net/http/httptrace"
 	"runtime"
 	"strings"
 	"testing"
@@ -371,3 +373,97 @@ func TestHTTPClientReturnsStallHardenedSharedClient(t *testing.T) {
 		t.Fatal("an explicit client must be returned unchanged")
 	}
 }
+
+// startIdleConnCloser periodically closes idle pooled connections so stale HTTP/2
+// connections are not reused across long idle periods.
+func TestStartIdleConnCloserClosesIdleConnections(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	tr := http.DefaultTransport.(*http.Transport).Clone()
+	tr.DisableKeepAlives = false
+	defer tr.CloseIdleConnections()
+
+	client := &http.Client{Transport: tr}
+
+	// First request creates a connection in the pool.
+	resp1, err := client.Get(server.URL)
+	if err != nil {
+		t.Fatalf("first request failed: %v", err)
+	}
+	_, _ = io.Copy(io.Discard, resp1.Body)
+	_ = resp1.Body.Close()
+
+	// Immediate second request reuses the pooled connection.
+	var reusedFirst bool
+	trace1 := &httptrace.ClientTrace{
+		GotConn: func(info httptrace.GotConnInfo) {
+			reusedFirst = info.Reused
+		},
+	}
+	req2, err := http.NewRequestWithContext(httptrace.WithClientTrace(context.Background(), trace1), http.MethodGet, server.URL, nil)
+	if err != nil {
+		t.Fatalf("new request failed: %v", err)
+	}
+	resp2, err := client.Do(req2)
+	if err != nil {
+		t.Fatalf("second request failed: %v", err)
+	}
+	_, _ = io.Copy(io.Discard, resp2.Body)
+	_ = resp2.Body.Close()
+
+	if !reusedFirst {
+		t.Fatal("expected immediate second request to reuse keep-alive connection")
+	}
+
+	// Start closer with a short interval and wait for it to fire.
+	stop := startIdleConnCloser(tr, 20*time.Millisecond)
+	defer stop()
+
+	// Poll until the idle closer evicts the connection and a fresh dial occurs.
+	deadline := time.Now().Add(2 * time.Second)
+	var closed bool
+	for time.Now().Before(deadline) {
+		time.Sleep(10 * time.Millisecond)
+		var reused bool
+		trace := &httptrace.ClientTrace{
+			GotConn: func(info httptrace.GotConnInfo) {
+				reused = info.Reused
+			},
+		}
+		req, err := http.NewRequestWithContext(httptrace.WithClientTrace(context.Background(), trace), http.MethodGet, server.URL, nil)
+		if err != nil {
+			t.Fatalf("new request failed: %v", err)
+		}
+		resp, err := client.Do(req)
+		if err != nil {
+			t.Fatalf("request failed: %v", err)
+		}
+		_, _ = io.Copy(io.Discard, resp.Body)
+		_ = resp.Body.Close()
+		if !reused {
+			closed = true
+			break
+		}
+	}
+	if !closed {
+		t.Fatal("expected connection to be closed by idle closer and not reused")
+	}
+}
+
+func TestStartIdleConnCloserEdgeCases(t *testing.T) {
+	// Zero or negative interval returns a no-op stop func without starting goroutine.
+	stopZero := startIdleConnCloser(nil, 0)
+	stopZero()
+
+	tr := http.DefaultTransport.(*http.Transport).Clone()
+	stopNil := startIdleConnCloser(tr, -1*time.Second)
+	stopNil()
+
+	// Calling stop multiple times is idempotent.
+	stop := startIdleConnCloser(tr, 100*time.Millisecond)
+	stop()
+	stop()
+}

internal/redaction/control_split.go

@@ -0,0 +1,547 @@
+package redaction
+
+import (
+	"fmt"
+	"regexp"
+	"regexp/syntax"
+	"sort"
+	"strings"
+	"unicode"
+	"unicode/utf8"
+)
+
+// A CREDENTIAL IS STILL A CREDENTIAL WITH AN INVISIBLE BYTE IN THE MIDDLE.
+//
+// The shape matchers (openaiKeyPattern, textSecretPatterns) all describe a
+// CONTIGUOUS run of body characters, and none of their character classes admits
+// a control or format character. So a single NUL, ESC or zero-width space
+// dropped into the body of a key ends the match, and RedactString emits the two
+// fragments untouched. Whoever reads that output next, a terminal that eats the
+// escape, a log viewer, a JSON consumer that strips control bytes, or a person
+// copying the text, sees the original key back, because nothing about those
+// characters was ever displayed. Reported in #969 for NUL and ESC; every other
+// Cc and Cf character behaves the same way, which is why this is written against
+// the classes rather than against the two bytes named there.
+//
+// HOW: each shape is rewritten so that a run of separators may sit between any
+// two characters it consumes, and matched against the ORIGINAL text. Nothing is
+// removed before matching, so there are no offsets to map back, and the leading
+// \b of every shape is judged by the regexp engine against the real neighbour:
+// a key written after a NUL starts at a boundary, exactly as the unsplit key
+// does, and a key glued to the end of a word does not.
+//
+// An earlier version removed the separators first and matched the compacted
+// copy. That lost the difference between a separator inside a credential and one
+// next to it, and the fixes for that (check the boundary against the source
+// afterwards, map offsets back) left a hole: in "xAKIA<NUL>AKIAIOSF<SOH>ODNN7..."
+// the leftmost compacted match began at the decoy AKIA, was then rejected for
+// the "x" in front of it, and had already consumed the start of the real key, so
+// the real key was never considered. Resuming the scan one byte after each
+// rejection would close that, but it is quadratic for the greedy shapes on text
+// like "ask-ask-ask-..." with a single NUL in it. Keeping the boundary inside
+// the pattern lets RE2 do it in one linear pass.
+//
+// This pass runs AFTER the contiguous matchers, over their output, and never
+// across a replacement. A credential that is whole is claimed by its own strict
+// match, so two whole credentials with a separator between them stay two
+// replacements with the separator still between them. Two split credentials do
+// too: see spansFor.
+//
+// A match never starts or ends on a separator, so the separators on either side
+// of a credential stay where they were: "<NUL>AKIA..." becomes
+// "<NUL>[REDACTED]", as it does for the unsplit key.
+//
+// ONE KNOWN LIMIT, from running the contiguous matchers first. When the part of
+// a split key BEFORE its first separator is already a complete credential on
+// its own, the contiguous matcher claims that part and stops at the separator,
+// and what follows is judged by itself. That is the rest of the key, which is no
+// credential alone, so it stays visible: a fragment of the key, never the whole
+// of it, because the part in front is replaced. For the same reason a credential
+// glued straight onto that rest is left, where the unsplit key would have run on
+// and swallowed it. Carrying the contiguous match across the separator instead
+// would bring back what running first exists to prevent, since nothing tells the
+// rest of a key from prose written after a whole one: that prose would be eaten,
+// and a following JWT would lose its header.
+//
+// WHAT THIS DELIBERATELY DOES NOT TREAT AS A SEPARATOR: tab, newline and
+// carriage return. Those three are real text structure rather than invisible
+// filler, so a credential broken across a line boundary is still two visible
+// fragments here and is not covered. Treating them as gaps would also let a
+// match span a line break and collapse unrelated lines into one replacement. A
+// credential split that way is visible to whoever reads it; the ones handled
+// here are not. Invalid UTF-8 is out for the same reason: the engine reads an
+// invalid byte as U+FFFD, which is drawn.
+
+// splitSecretSeparator reports a character that can sit inside a credential
+// without being seen. Cc covers the C0 and C1 controls (NUL, ESC, DEL, NEL, CSI)
+// and Cf the format characters (zero-width space and joiner, word joiner, BOM,
+// soft hyphen). Tab, newline and carriage return are excluded: see above.
+func splitSecretSeparator(r rune) bool {
+	switch r {
+	case '\t', '\n', '\r':
+		return false
+	}
+	return unicode.Is(unicode.Cc, r) || unicode.Is(unicode.Cf, r)
+}
+
+// containsSplitSeparator is the cheap gate in front of the gap-tolerant pass, so
+// text with nothing invisible in it, which is nearly all text, costs one scan and
+// no allocation. ASCII is settled from the byte alone; only a byte that could
+// begin a multi-byte rune needs decoding, and the C1 and Cf blocks all start
+// with a lead byte at or above 0xC2.
+func containsSplitSeparator(value string) bool {
+	for i := 0; i < len(value); i++ {
+		b := value[i]
+		if b < utf8.RuneSelf {
+			if b < 0x20 || b == 0x7f {
+				if b == '\t' || b == '\n' || b == '\r' {
+					continue
+				}
+				return true
+			}
+			continue
+		}
+		r, width := utf8.DecodeRuneInString(value[i:])
+		if splitSecretSeparator(r) {
+			return true
+		}
+		i += width - 1
+	}
+	return false
+}
+
+// stripSplitSeparators returns value with every splitSecretSeparator removed.
+// Used only on a matched credential, to judge it by its visible characters.
+func stripSplitSeparators(value string) string {
+	var builder strings.Builder
+	builder.Grow(len(value))
+	for offset := 0; offset < len(value); {
+		r, width := utf8.DecodeRuneInString(value[offset:])
+		if !splitSecretSeparator(r) {
+			builder.WriteString(value[offset : offset+width])
+		}
+		offset += width
+	}
+	return builder.String()
+}
+
+// splitSeparatorClass is splitSecretSeparator as a regexp character class,
+// generated from the same Unicode tables and the same three exclusions so the
+// class and the predicate cannot disagree.
+var splitSeparatorClass = func() string {
+	var class strings.Builder
+	class.WriteByte('[')
+	emit := func(lo, hi rune) {
+		fmt.Fprintf(&class, `\x{%x}-\x{%x}`, lo, hi)
+	}
+	for _, table := range []*unicode.RangeTable{unicode.Cc, unicode.Cf} {
+		visit := func(lo, hi, stride uint32) {
+			for r := lo; r <= hi; r += stride {
+				start := rune(r)
+				if !splitSecretSeparator(start) {
+					continue
+				}
+				end := start
+				if stride == 1 {
+					for next := rune(r) + 1; uint32(next) <= hi && splitSecretSeparator(next); next++ {
+						end = next
+					}
+					r = uint32(end)
+				}
+				emit(start, end)
+			}
+		}
+		for _, r := range table.R16 {
+			visit(uint32(r.Lo), uint32(r.Hi), uint32(r.Stride))
+		}
+		for _, r := range table.R32 {
+			visit(r.Lo, r.Hi, r.Stride)
+		}
+	}
+	class.WriteByte(']')
+	return class.String()
+}()
+
+// splitOpenAIPattern and splitTextPatterns are the shape matchers with a run of
+// separators allowed between every two characters they consume, derived from
+// the originals rather than written out a second time so the two lists cannot
+// drift apart.
+var (
+	splitOpenAIPattern = gapTolerant(openaiKeyPattern)
+	splitTextPatterns  = gapTolerantAll(textSecretPatterns)
+)
+
+// splitShape is one credential shape as the split pass uses it.
+type splitShape struct {
+	// free finds the shape anywhere, leftmost first. anchored matches it only
+	// where the text begins, and whole only when it spans the entire text.
+	free, anchored, whole *regexp.Regexp
+	// prefix is the literal every match of the shape begins with.
+	prefix string
+	// accept is the test a match has to pass to be a credential, or nil when
+	// every match is one.
+	accept func(match string) bool
+}
+
+var splitShapes = func() []splitShape {
+	shapes := []splitShape{newSplitShape(openaiKeyPattern, splitOpenAIPattern, func(match string) bool {
+		return openAIShapeIsSecret(stripSplitSeparators(match))
+	})}
+	for i, pattern := range textSecretPatterns {
+		shapes = append(shapes, newSplitShape(pattern, splitTextPatterns[i], nil))
+	}
+	return shapes
+}()
+
+func newSplitShape(original, free *regexp.Regexp, accept func(string) bool) splitShape {
+	return splitShape{
+		free:     free,
+		anchored: regexp.MustCompile(`\A(?:` + free.String() + `)`),
+		whole:    regexp.MustCompile(`\A(?:` + free.String() + `)\z`),
+		prefix:   leadingLiteral(original),
+		accept:   accept,
+	}
+}
+
+// leadingLiteral is the literal every match of pattern begins with, read past a
+// leading \b, or "" when the pattern does not open with one.
+func leadingLiteral(pattern *regexp.Regexp) string {
+	tree, err := syntax.Parse(pattern.String(), syntax.Perl)
+	if err != nil {
+		panic(fmt.Sprintf("redaction: parse %q: %v", pattern.String(), err))
+	}
+	nodes := []*syntax.Regexp{tree}
+	if tree.Op == syntax.OpConcat {
+		nodes = tree.Sub
+	}
+	for _, node := range nodes {
+		if node.Op == syntax.OpWordBoundary {
+			continue
+		}
+		if node.Op == syntax.OpLiteral {
+			return string(node.Rune)
+		}
+		return ""
+	}
+	return ""
+}
+
+// maxRunOnCandidates bounds the anchored matches tried inside one match, so a
+// match full of lookalike starts still costs a fixed number of them.
+const maxRunOnCandidates = 8
+
+// spansFor turns one match of the shape into the stretches to replace.
+//
+// A MATCH CAN RUN ON INTO THE NEXT CREDENTIAL OF ITS OWN SHAPE. Gaps are allowed
+// inside a match, and a separator between two credentials looks exactly like one
+// inside a credential, so a greedy body runs through it into whatever follows. A
+// credential of another shape is still found, because every shape is matched on
+// its own and the union is replaced. One of the SAME shape is not: matches of one
+// pattern never overlap, so the second credential cannot start inside the first
+// one's match. Most bodies swallow it whole, so nothing leaks, but a JWT stops at
+// the next token's first dot, and two split JWTs side by side left the second
+// one's payload and signature in the clear. And a match the filter rejects hides
+// whatever it ran into, so kebab-case prose in front of a split key took the key
+// down with it. Reported by @jatmn.
+//
+// So when a match runs through a run of separators into a position where the
+// same shape matches again and reaches at least as far, that credential is taken
+// on its own, and the first is cut at the separators if it is a complete match by
+// itself. The separators between the two then stay outside both replacements, as
+// they do between two whole credentials, and each piece is filtered on its own.
+// When the first is not complete alone, it keeps the whole of its match and the
+// union joins the two into one replacement.
+//
+// ONE STEP PER MATCH, NOT THE WHOLE CHAIN. The second credential's own match can
+// run on into a third, and following that from here would walk the rest of a
+// chain once for every match inside it, which is quadratic: a megabyte of split
+// JWTs ran for minutes. The scan's own next match starts inside the second
+// credential and takes the step after it, so the chain is still covered, and in
+// a chain of three or more the markers after the first pair can join into one.
+func (shape splitShape) spansFor(text string, start, end int) [][]int {
+	next, gap, nextEnd := shape.runOn(text, start, end)
+	if next < 0 {
+		return shape.keep(nil, text, start, end)
+	}
+	var spans [][]int
+	if shape.whole.MatchString(text[start:gap]) {
+		spans = shape.keep(spans, text, start, gap)
+	} else {
+		spans = shape.keep(spans, text, start, end)
+	}
+	return shape.keep(spans, text, next, nextEnd)
+}
+
+func (shape splitShape) keep(spans [][]int, text string, start, end int) [][]int {
+	if shape.accept != nil && !shape.accept(text[start:end]) {
+		return spans
+	}
+	return append(spans, []int{start, end})
+}
+
+// runOn looks inside the match [start, end) for where it ran through a run of
+// separators into another credential of the same shape. It returns where that
+// credential begins, where the separator run in front of it begins, and where the
+// credential's own match ends, or next = -1 when there is none.
+//
+// Latest first, because a match reaches into the next credential only as far as
+// its own pattern allows. Only where the text after the separators opens with the
+// shape's literal prefix, which is where a match of the shape can begin; the
+// separator in front supplies the word boundary, so matching from there judges it
+// the same as the whole text would.
+func (shape splitShape) runOn(text string, start, end int) (next, gap, nextEnd int) {
+	tried := 0
+	for at := end; at > start && tried < maxRunOnCandidates; {
+		r, size := utf8.DecodeLastRuneInString(text[start:at])
+		if !splitSecretSeparator(r) {
+			at -= size
+			continue
+		}
+		candidate := at
+		for at > start {
+			r, size = utf8.DecodeLastRuneInString(text[start:at])
+			if !splitSecretSeparator(r) {
+				break
+			}
+			at -= size
+		}
+		if !hasGappedPrefix(text[candidate:], shape.prefix) {
+			continue
+		}
+		tried++
+		if match := shape.anchored.FindStringIndex(text[candidate:]); match != nil && candidate+match[1] >= end {
+			return candidate, at, candidate + match[1]
+		}
+	}
+	return -1, 0, 0
+}
+
+// hasGappedPrefix reports whether text opens with prefix, allowing a run of
+// separators between its characters the way the shapes themselves do. A plain
+// prefix test missed a token split inside its first few characters, and the run
+// that swallowed it then went unnoticed.
+func hasGappedPrefix(text, prefix string) bool {
+	at := 0
+	for index, want := range prefix {
+		if index > 0 {
+			for at < len(text) {
+				r, size := utf8.DecodeRuneInString(text[at:])
+				if !splitSecretSeparator(r) {
+					break
+				}
+				at += size
+			}
+		}
+		if at >= len(text) {
+			return false
+		}
+		r, size := utf8.DecodeRuneInString(text[at:])
+		if r != want {
+			return false
+		}
+		at += size
+	}
+	return true
+}
+
+func gapTolerantAll(patterns []*regexp.Regexp) []*regexp.Regexp {
+	tolerant := make([]*regexp.Regexp, 0, len(patterns))
+	for _, pattern := range patterns {
+		tolerant = append(tolerant, gapTolerant(pattern))
+	}
+	return tolerant
+}
+
+// gapTolerant rewrites pattern so that a run of separators may appear before
+// every character it consumes except the first. Zero-width assertions, the
+// leading \b in particular, are left exactly where they were.
+func gapTolerant(pattern *regexp.Regexp) *regexp.Regexp {
+	tree, err := syntax.Parse(pattern.String(), syntax.Perl)
+	if err != nil {
+		panic(fmt.Sprintf("redaction: parse %q: %v", pattern.String(), err))
+	}
+	separator, err := syntax.Parse(splitSeparatorClass, syntax.Perl)
+	if err != nil {
+		panic(fmt.Sprintf("redaction: parse separator class: %v", err))
+	}
+	consumed := false
+	return regexp.MustCompile(withGaps(tree, separator, &consumed).String())
+}
+
+// withGaps inserts the separator run before each consuming atom. consumed
+// tracks whether anything has been consumed yet on this path, because the first
+// character of a match must be a real one: a leading gap would let a match start
+// on a separator and swallow it.
+func withGaps(node, separator *syntax.Regexp, consumed *bool) *syntax.Regexp {
+	switch node.Op {
+	case syntax.OpLiteral:
+		parts := make([]*syntax.Regexp, 0, len(node.Rune))
+		for _, r := range node.Rune {
+			atom := &syntax.Regexp{Op: syntax.OpLiteral, Rune: []rune{r}, Flags: node.Flags}
+			parts = append(parts, gapBefore(atom, separator, consumed))
+		}
+		if len(parts) == 1 {
+			return parts[0]
+		}
+		return &syntax.Regexp{Op: syntax.OpConcat, Sub: parts}
+	case syntax.OpCharClass, syntax.OpAnyChar, syntax.OpAnyCharNotNL:
+		return gapBefore(node, separator, consumed)
+	case syntax.OpConcat, syntax.OpCapture:
+		for i := range node.Sub {
+			node.Sub[i] = withGaps(node.Sub[i], separator, consumed)
+		}
+		return node
+	case syntax.OpAlternate:
+		start, after := *consumed, *consumed
+		for i := range node.Sub {
+			branch := start
+			node.Sub[i] = withGaps(node.Sub[i], separator, &branch)
+			after = after || branch
+		}
+		*consumed = after
+		return node
+	case syntax.OpStar, syntax.OpPlus, syntax.OpQuest, syntax.OpRepeat:
+		// Every shape opens with a literal prefix, so a repetition is never the
+		// first thing a match consumes. If one ever is, its first iteration would
+		// need no gap and the rest would; fail loudly rather than guess.
+		if !*consumed {
+			panic("redaction: gap-tolerant rewrite reached a repetition before any literal")
+		}
+		node.Sub[0] = withGaps(node.Sub[0], separator, consumed)
+		return node
+	case syntax.OpWordBoundary, syntax.OpNoWordBoundary, syntax.OpBeginLine, syntax.OpEndLine,
+		syntax.OpBeginText, syntax.OpEndText, syntax.OpEmptyMatch:
+		return node
+	default:
+		panic(fmt.Sprintf("redaction: gap-tolerant rewrite does not handle %v", node.Op))
+	}
+}
+
+func gapBefore(atom, separator *syntax.Regexp, consumed *bool) *syntax.Regexp {
+	if !*consumed {
+		*consumed = true
+		return atom
+	}
+	gap := &syntax.Regexp{Op: syntax.OpStar, Sub: []*syntax.Regexp{separator}}
+	return &syntax.Regexp{Op: syntax.OpConcat, Sub: []*syntax.Regexp{gap, atom}}
+}
+
+// openAIShapeIsSecret is the digit/kebab-case filter RedactString applies to an
+// openaiKeyPattern match, named so both callers state the same rule once.
+func openAIShapeIsSecret(match string) bool {
+	if knownOpenAIKeyPrefix(match) || secretMatchHasDigit(match) {
+		return true
+	}
+	return !strings.Contains(strings.TrimPrefix(match, "sk-"), "-")
+}
+
+// redactControlSplitSecrets replaces credentials whose body is interrupted by
+// invisible characters. It is a no-op for text containing none of them, which is
+// nearly all text, so the contiguous path keeps its behavior exactly.
+//
+// It runs over the contiguous matchers' output and stops at every replacement
+// they left behind: those mark text already accounted for, and a match reaching
+// across one would be reaching out of one credential and into the next.
+//
+// It runs at most twice. The second pass exists for a credential glued straight
+// onto the end of another split one: it has no word boundary of its own until
+// the first is replaced, and the replacement then supplies one, the same way the
+// contiguous shapes cascade into each other. Two passes and no more keeps the
+// cost linear; a longer chain of glued split credentials is left as the
+// contiguous matchers leave a chain of glued whole ones.
+func redactControlSplitSecrets(value, replacement string) string {
+	if !containsSplitSeparator(value) {
+		return value
+	}
+	once := redactSplitRegions(value, replacement, true)
+	if once == value {
+		return value
+	}
+	// Ungated: the credential the second pass exists for is often contiguous
+	// itself (a whole JWT glued onto a split AWS key), so its region can hold no
+	// separator at all once the first pass has cut the text around it.
+	return redactSplitRegions(once, replacement, false)
+}
+
+func redactSplitRegions(value, replacement string, gated bool) string {
+	if replacement == "" {
+		return redactSplitRegion(value, replacement, 0, gated)
+	}
+	regions := strings.Split(value, replacement)
+	if len(regions) == 1 {
+		return redactSplitRegion(value, replacement, 0, gated)
+	}
+	previous := byte(0)
+	for i, region := range regions {
+		regions[i] = redactSplitRegion(region, replacement, previous, gated)
+		previous = replacement[len(replacement)-1]
+	}
+	return strings.Join(regions, replacement)
+}
+
+// redactSplitRegion runs every gap-tolerant shape over one stretch of text with
+// no replacement inside it and replaces the UNION of what they found.
+//
+// Independently, not one after another. An unbounded body with gaps allowed will
+// run on across a separator into whatever follows, and when that is the start of
+// another credential it takes that credential's prefix with it: in
+// "sk-ant-…<ESC>build<ESC>eyJ….eyJ….sig" the Anthropic shape stops only at the
+// JWT's first dot. Applied in sequence, the JWT shape then finds its header gone
+// and the payload and signature are left in the clear. Matched against the same
+// text, the JWT shape still finds the whole token, and the union covers both.
+//
+// previous is the byte immediately before the region in the original, or zero at
+// the start of the string. It is lent to the engine in front of the region so a
+// leading \b is judged against the real neighbour, and a match is never allowed
+// to begin on it.
+func redactSplitRegion(value, replacement string, previous byte, gated bool) string {
+	if gated && !containsSplitSeparator(value) {
+		return value
+	}
+	text, lead := value, 0
+	if previous != 0 {
+		text, lead = string([]byte{previous})+value, 1
+	}
+	var spans [][]int
+	for _, shape := range splitShapes {
+		for _, match := range shape.free.FindAllStringIndex(text, -1) {
+			if match[0] >= lead {
+				spans = append(spans, shape.spansFor(text, match[0], match[1])...)
+			}
+		}
+	}
+	return spliceSpans(text, spans, replacement)[lead:]
+}
+
+// spliceSpans replaces every named range of value with replacement, merging
+// ranges that overlap so one stretch of text is never replaced twice.
+func spliceSpans(value string, spans [][]int, replacement string) string {
+	if len(spans) == 0 {
+		return value
+	}
+	sort.Slice(spans, func(i, j int) bool {
+		if spans[i][0] != spans[j][0] {
+			return spans[i][0] < spans[j][0]
+		}
+		return spans[i][1] > spans[j][1]
+	})
+	var builder strings.Builder
+	builder.Grow(len(value))
+	written := 0
+	for _, span := range spans {
+		if span[0] < written {
+			// Overlaps the stretch just replaced: extend it rather than emit a
+			// second marker, which would claim two credentials where there was one
+			// stretch of text.
+			if span[1] > written {
+				written = span[1]
+			}
+			continue
+		}
+		builder.WriteString(value[written:span[0]])
+		builder.WriteString(replacement)
+		written = span[1]
+	}
+	builder.WriteString(value[written:])
+	return builder.String()
+}

internal/redaction/control_split_test.go

@@ -0,0 +1,622 @@
+package redaction
+
+import (
+	"fmt"
+	"regexp"
+	"runtime"
+	"strings"
+	"testing"
+	"unicode"
+)
+
+const (
+	awsKey       = "AKIAIOSFODNN7EXAMPLE"
+	anthropicKey = "sk-ant-api03-aaaaaaaaaaaaaaaaaaaaaaaa0123456789ABCD"
+	githubKey    = "ghp_cccccccccccccccccccccccccccccccccccc"
+	openaiKey    = "sk-proj-bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+)
+
+// rejoin drops every character a reader would never see, which is what a
+// terminal, a log viewer or a copy-paste does to this output. If the secret is
+// back after that, the redaction did not happen.
+func rejoin(value string) string {
+	return strings.Map(func(r rune) rune {
+		if splitSecretSeparator(r) {
+			return -1
+		}
+		return r
+	}, value)
+}
+
+// AN INVISIBLE BYTE INSIDE A KEY MUST NOT END THE MATCH.
+//
+// Every shape matcher describes a contiguous body, so one NUL or ESC in the
+// middle of a key ended the match and both fragments were emitted. Dropping the
+// byte — which is what the next reader does, because it was never displayed —
+// put the original key back. Reported in #969 for NUL and ESC; this covers the
+// classes those two belong to, because every member behaves the same way.
+func TestRedactStringRedactsSecretsSplitByInvisibleCharacters(t *testing.T) {
+	separators := map[string]string{
+		"NUL":               "\x00",
+		"ESC":               "\x1b",
+		"BEL":               "\x07",
+		"backspace":         "\x08",
+		"vertical tab":      "\x0b",
+		"form feed":         "\x0c",
+		"DEL":               "\x7f",
+		"C1 NEL":            "\u0085",
+		"C1 CSI":            "\u009b",
+		"zero width space":  "\u200b",
+		"zero width joiner": "\u200d",
+		"word joiner":       "\u2060",
+		"byte order mark":   "\ufeff",
+		"soft hyphen":       "\u00ad",
+	}
+	// Every entry has to BE a separator, or its leg passes vacuously: inserting an
+	// ordinary character into a key also stops the secret matching, and the rejoin
+	// below would then find nothing. An escape mangled on the way into this file is
+	// exactly how that happens.
+	for name, separator := range separators {
+		if runes := []rune(separator); len(runes) != 1 || !splitSecretSeparator(runes[0]) {
+			t.Fatalf("SETUP INVALID: %s is %q, which is not a single invisible separator", name, separator)
+		}
+	}
+	secrets := map[string]string{"aws": awsKey, "anthropic": anthropicKey, "github": githubKey, "openai": openaiKey}
+	for secretName, secret := range secrets {
+		// The premise: the unsplit form already redacts, so a failure below is
+		// about the separator and not about the shape being unknown.
+		if out := RedactString(secret, Options{}); strings.Contains(out, secret) {
+			t.Fatalf("SETUP INVALID: the unsplit %s key is not redacted at all: %q", secretName, out)
+		}
+		for sepName, separator := range separators {
+			for _, at := range []int{1, len(secret) / 2, len(secret) - 1} {
+				split := secret[:at] + separator + secret[at:]
+				out := RedactString(split, Options{})
+				if got := rejoin(out); strings.Contains(got, secret) {
+					t.Errorf("%s key split by %s at byte %d survives: %q rejoins to %q", secretName, sepName, at, out, got)
+				}
+			}
+		}
+	}
+}
+
+// The replacement has to cover the ORIGINAL bytes, separators included. Leaving
+// the separator behind would emit `[REDACTED]\x00[REDACTED]` and tell a reader
+// there were two secrets, and leaving either fragment behind is the leak itself.
+func TestRedactStringCoversTheSeparatorsInsideASplitSecret(t *testing.T) {
+	for _, testCase := range []struct {
+		name  string
+		value string
+		want  string
+	}{
+		{"one separator", "key=" + awsKey[:8] + "\x00" + awsKey[8:], "key=[REDACTED]"},
+		{"several separators", "key=" + strings.Join(strings.Split(awsKey, ""), "\x1b"), "key=[REDACTED]"},
+		{"adjacent separators", "key=" + awsKey[:8] + "\x00\x1b\u200b" + awsKey[8:], "key=[REDACTED]"},
+		{"two split secrets", awsKey[:8] + "\x00" + awsKey[8:] + " and " + githubKey[:8] + "\x00" + githubKey[8:], "[REDACTED] and [REDACTED]"},
+		{"separator before the secret", "\x00" + awsKey, "\x00[REDACTED]"},
+		{"separator after the secret", awsKey + "\x00", "[REDACTED]\x00"},
+		{"text around it survives", "before " + awsKey[:4] + "\x00" + awsKey[4:] + " after", "before [REDACTED] after"},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			if got := RedactString(testCase.value, Options{}); got != testCase.want {
+				t.Errorf("RedactString(...) = %q, want %q", got, testCase.want)
+			}
+		})
+	}
+}
+
+// NOTHING ELSE MOVES. The compaction exists to find a match; it must never
+// reach text that has no secret in it, and text with no invisible character at
+// all must take exactly the path it took before.
+func TestRedactStringLeavesOrdinaryTextWithControlCharactersAlone(t *testing.T) {
+	for _, value := range []string{
+		"a plain sentence",
+		"a sentence\x00with a NUL in it",
+		"\x1b[31mcolored output\x1b[0m",
+		"tab\tseparated\tcolumns",
+		"line one\nline two\r\nline three",
+		"zero\u200bwidth\u200bspaces",
+		"", "\x00", "\x00\x00\x00",
+		"not-a-secret-just-a-long-kebab-case-identifier-here",
+		"sk-some-kebab-case-value-without-any-digits-at-all",
+	} {
+		if got := RedactString(value, Options{}); got != value {
+			t.Errorf("RedactString(%q) = %q, want it unchanged", value, got)
+		}
+	}
+}
+
+// The openai filter that keeps kebab-case identifiers out of the redactor has
+// to apply on the split path too, or working around the false positive would
+// become a matter of inserting a control byte.
+func TestSplitPathKeepsTheOpenAIKebabCaseFilter(t *testing.T) {
+	kebab := "sk-some-kebab-case-value-without-digits"
+	split := kebab[:6] + "\x00" + kebab[6:]
+	if got := RedactString(split, Options{}); got != split {
+		t.Errorf("a kebab-case identifier split by a NUL was redacted: %q", got)
+	}
+	// ... while a real key of the same family, split the same way, is not spared.
+	realKey := openaiKey[:6] + "\x00" + openaiKey[6:]
+	if got := RedactString(realKey, Options{}); strings.Contains(rejoin(got), openaiKey) {
+		t.Errorf("a real openai key split by a NUL survived: %q", got)
+	}
+}
+
+// TAB, NEWLINE AND CARRIAGE RETURN ARE OUT OF SCOPE ON PURPOSE, and this says
+// so in a place that fails if someone changes it without meaning to. They are
+// real text structure: stripping them would let one match span a line break and
+// replace unrelated lines, and a credential broken across a line is visible to
+// whoever reads it rather than hidden from them.
+func TestLineStructureIsNotTreatedAsAnInvisibleSeparator(t *testing.T) {
+	for name, separator := range map[string]string{"tab": "\t", "newline": "\n", "carriage return": "\r"} {
+		if splitSecretSeparator([]rune(separator)[0]) {
+			t.Errorf("%s is treated as an invisible separator; if that is now wanted, this test and the note in control_split.go both need to change", name)
+		}
+		split := awsKey[:8] + separator + awsKey[8:]
+		if got := RedactString(split, Options{}); got != split {
+			t.Errorf("%s split was redacted: %q. That may be an improvement, but it is a scope change this test is here to make deliberate", name, got)
+		}
+	}
+}
+
+// Malformed UTF-8 must not move the span mapping, which works in the source's
+// own byte offsets. A decoder that measured an invalid byte as the three bytes
+// of U+FFFD would shift every later span.
+// The exact output is asserted, not just the absence of the key. An invalid
+// byte measured as three would still cover the secret while moving the
+// replacement's edges onto the bytes around it, which reads as a pass if the
+// test only asks whether the secret is gone.
+func TestSplitRedactionHandlesMalformedUTF8(t *testing.T) {
+	for _, testCase := range []struct {
+		name  string
+		value string
+		want  string
+	}{
+		{"invalid byte before the secret", "\xff" + awsKey[:8] + "\x00" + awsKey[8:], "\xff[REDACTED]"},
+		// An invalid byte is NOT one of the separators: it decodes to U+FFFD and
+		// is drawn, so a key broken by one is visible to whoever reads it, the
+		// same argument that keeps tab and newline out. It is kept in the
+		// compacted text and so it still ends the match.
+		{"invalid byte inside the split", awsKey[:8] + "\x00\xff" + awsKey[8:], awsKey[:8] + "\x00\xff" + awsKey[8:]},
+		{"invalid byte after the secret", awsKey[:8] + "\x00" + awsKey[8:] + "\xfe", "[REDACTED]\xfe"},
+		{"invalid bytes on both sides", "\xff\xfe" + awsKey[:8] + "\x00" + awsKey[8:] + "\xfd\xfc", "\xff\xfe[REDACTED]\xfd\xfc"},
+		{"invalid byte then text then the secret", "\xffpre " + awsKey[:8] + "\x00" + awsKey[8:] + " post", "\xffpre [REDACTED] post"},
+		{"only invalid bytes", "\xff\xfe\x00\xff", "\xff\xfe\x00\xff"},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			got := RedactString(testCase.value, Options{})
+			if got != testCase.want {
+				t.Errorf("RedactString(%q) = %q, want %q", testCase.value, got, testCase.want)
+			}
+			if strings.Contains(rejoin(got), awsKey) {
+				t.Errorf("the key survived: %q", got)
+			}
+		})
+	}
+}
+
+// The compaction is only a lens for finding the match. A string with no
+// separator at all must come back byte-identical, including its invalid bytes.
+func TestCompactionDoesNotRewriteTextItDoesNotRedact(t *testing.T) {
+	for _, value := range []string{"plain", "with\xffinvalid", "tab\there", "\xef\xbb\xbfbom at the front"} {
+		if got := redactControlSplitSecrets(value, RedactedSecret); got != value {
+			t.Errorf("redactControlSplitSecrets(%q) = %q, want it unchanged", value, got)
+		}
+	}
+}
+
+// The separators the tests below need by name, built from their code points so
+// no escape in this file can be mangled into the character it stands for.
+var (
+	nulSeparator  = string(rune(0x00))
+	escSeparator  = string(rune(0x1b))
+	zwspSeparator = string(rune(0x200b))
+)
+
+const (
+	slackKey  = "xoxb-EXAMPLE-NOT-A-REAL-TOKEN-AAAAAAAAAA"
+	googleKey = "AIzaSyD-0123456789abcdefghijklmnopqrstuv"
+	jwtToken  = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dBjftJeZ4CVPmB92K27uhbUJU1p1r0W1gFWFOEjXkPY"
+	otherJWT  = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI5ODc2NTQzMjEwIn0.QWxpY2VCb2JDYXJvbERhdmVFdmVGcmFua0dyYWNlSA"
+)
+
+// splitInTheMiddle puts one separator inside the body of a secret.
+func splitInTheMiddle(secret, separator string) string {
+	half := len(secret) / 2
+	return secret[:half] + separator + secret[half:]
+}
+
+// A SEPARATOR IN FRONT OF A KEY IS A DELIMITER, ONE INSIDE IT IS FILLER.
+//
+// #969 asks for one thing: the split form is redacted the same as the unsplit
+// form. That is the whole assertion here, run over every kind of byte a key can
+// follow. It catches the two ways of getting it wrong from opposite sides. Drop
+// the separators and then ask the pattern for a word boundary, and a key written
+// after a NUL stops redacting the moment a second separator lands inside it,
+// even though the unsplit key after that same NUL redacts today. Ignore the
+// boundary instead, and a key glued to the end of a word starts redacting when
+// it is split, although the unsplit form never did.
+func TestSplitRedactionMatchesTheUnsplitVerdictAtEveryLeadingBoundary(t *testing.T) {
+	leaders := map[string]string{
+		"start of string": "",
+		"space":           "before ",
+		"quote":           `{"k":"`,
+		"equals":          "key=",
+		"NUL":             "prefix" + nulSeparator,
+		"ESC":             "prefix" + escSeparator,
+		"zero width":      "prefix" + zwspSeparator,
+		"letter":          "prefix",
+		"digit":           "7",
+		"underscore":      "field_",
+	}
+	secrets := map[string]string{"aws": awsKey, "github": githubKey, "openai": openaiKey, "slack": slackKey, "google": googleKey}
+	for secretName, secret := range secrets {
+		for leaderName, leader := range leaders {
+			unsplit := leader + secret
+			split := leader + splitInTheMiddle(secret, escSeparator)
+			wantRedacted := !strings.Contains(RedactString(unsplit, Options{}), secret)
+			out := RedactString(split, Options{})
+			gotRedacted := !strings.Contains(rejoin(out), secret)
+			if gotRedacted == wantRedacted {
+				continue
+			}
+			if wantRedacted {
+				t.Errorf("%s key after a %s leader: the unsplit form redacts and the split form does not: %q rejoins to %q",
+					secretName, leaderName, out, rejoin(out))
+				continue
+			}
+			t.Errorf("%s key after a %s leader: the unsplit form is left alone and the split form is redacted: %q",
+				secretName, leaderName, out)
+		}
+	}
+}
+
+// A MATCH MUST NOT REACH OUT OF ONE CREDENTIAL AND INTO THE NEXT.
+//
+// The JWT shapes end on a run of body characters with no trailing boundary, so
+// a matcher reading a copy with the separators removed can start in the key in
+// front and run through the header of the JWT behind it, replacing both with one
+// marker and eating the delimiter between them. The contiguous pass claims whole
+// credentials before this one runs, which is what keeps them apart.
+func TestSplitRedactionKeepsNeighbouringCredentialsApart(t *testing.T) {
+	separators := map[string]string{"NUL": nulSeparator, "ESC": escSeparator, "zero width": zwspSeparator}
+	leaders := map[string]string{
+		"jwt":       jwtToken,
+		"github":    githubKey,
+		"anthropic": anthropicKey,
+		"openai":    openaiKey,
+		"slack":     slackKey,
+		"google":    googleKey,
+		"aws":       awsKey,
+	}
+	for leaderName, leader := range leaders {
+		for sepName, separator := range separators {
+			value := leader + separator + otherJWT
+			want := RedactedSecret + separator + RedactedSecret
+			if got := RedactString(value, Options{}); got != want {
+				t.Errorf("a %s key %s a JWT: RedactString(...) = %q, want %q", leaderName, sepName, got, want)
+			}
+		}
+	}
+}
+
+// splitThroughout puts a separator a quarter of the way into every dot-separated
+// segment of a token. Early, so the part in front is too short to be a
+// credential by itself and the strict pass cannot claim it; a split whose front
+// part is complete alone is the documented limit, not what these tests are about.
+func splitThroughout(secret, separator string) string {
+	parts := strings.Split(secret, ".")
+	for i, part := range parts {
+		quarter := len(part) / 4
+		parts[i] = part[:quarter] + separator + part[quarter:]
+	}
+	return strings.Join(parts, ".")
+}
+
+// TWO SPLIT CREDENTIALS OF ONE SHAPE ARE TWO CREDENTIALS.
+//
+// Matches of one pattern never overlap, so when the first one's body runs on
+// through the separator between them, the second cannot start a match of its
+// own. Whole neighbours are safe because the strict pass claims them first;
+// these are both split. A JWT body stops at the next token's first dot and a
+// classic GitHub body at the next token's underscore, which left the rest of the
+// second credential in the clear, and the bodies that swallow the next key whole
+// joined both keys and the separator between them into one replacement.
+func TestSplitRedactionKeepsTwoSplitCredentialsOfOneShapeApart(t *testing.T) {
+	separators := map[string]string{"NUL": nulSeparator, "ESC": escSeparator, "zero width": zwspSeparator}
+	pairs := map[string][2]string{
+		"jwt":       {jwtToken, otherJWT},
+		"github":    {githubKey, "ghp_ffffffffffffffffffffffffffffffffffff"},
+		"openai":    {openaiKey, "sk-proj-dddddddddddddddddddddddddddddddd"},
+		"anthropic": {anthropicKey, "sk-ant-api03-eeeeeeeeeeeeeeeeeeeeeeee9876543210WXYZ"},
+		"slack":     {slackKey, "xoxb-ANOTHER-NOT-REAL-TOKEN-BBBBBBBBBBBB"},
+	}
+	for name, pair := range pairs {
+		for sepName, separator := range separators {
+			value := splitThroughout(pair[0], escSeparator) + separator + splitThroughout(pair[1], escSeparator)
+			want := RedactedSecret + separator + RedactedSecret
+			if got := RedactString(value, Options{}); got != want {
+				t.Errorf("two split %s credentials with %s between them: RedactString(...) = %q, want %q", name, sepName, got, want)
+			}
+		}
+	}
+}
+
+// The search for where the next credential begins is bounded, so it has to be
+// spent on positions where one can begin. Here the second token's header is split
+// at every character inside the part the first match swallowed, which puts dozens
+// of separator runs between the end of that match and the real boundary.
+func TestSplitRedactionFindsTheNextCredentialPastItsOwnSplits(t *testing.T) {
+	parts := strings.Split(otherJWT, ".")
+	header := strings.Join(strings.Split(parts[0], ""), escSeparator)
+	second := header + "." + strings.Join(parts[1:], ".")
+	value := splitThroughout(jwtToken, escSeparator) + nulSeparator + second
+	want := RedactedSecret + nulSeparator + RedactedSecret
+	if got := RedactString(value, Options{}); got != want {
+		t.Errorf("RedactString(...) = %q, want %q", got, want)
+	}
+}
+
+// And a chain of them leaks nothing, however the markers fall.
+func TestSplitRedactionLeavesNothingOfAChainOfSplitJWTs(t *testing.T) {
+	chain := splitThroughout(jwtToken, escSeparator) + nulSeparator +
+		splitThroughout(otherJWT, escSeparator) + nulSeparator +
+		splitThroughout(jwtToken, zwspSeparator)
+	out := rejoin(RedactString(chain, Options{}))
+	for _, segment := range append(strings.Split(jwtToken, "."), strings.Split(otherJWT, ".")...) {
+		if strings.Contains(out, segment) {
+			t.Errorf("a JWT segment survived a chain of three split tokens: %q in %q", segment, out)
+		}
+	}
+}
+
+// A CHAIN OF SPLIT CREDENTIALS COSTS WHAT ITS LENGTH COSTS.
+//
+// The run-on search once followed a chain to its end from every match inside it,
+// which is quadratic in the chain: a megabyte of split JWTs back to back
+// allocated seventeen gigabytes and ran for ten minutes. Measured as allocation,
+// which that walk multiplies with the chain and a linear pass does not.
+func TestSplitRedactionStaysLinearOnAChainOfSplitJWTs(t *testing.T) {
+	unit := splitThroughout(jwtToken, escSeparator) + nulSeparator
+	chain := strings.Repeat(unit, (64<<10)/len(unit))
+	signature := strings.Split(jwtToken, ".")[2]
+	if strings.Contains(rejoin(RedactString(chain, Options{})), signature) {
+		t.Fatal("SETUP INVALID: the chain is not redacted, so the run-on search never ran")
+	}
+	limit := int64(200 * len(chain))
+	if used := redactAllocBytes(chain); used > limit {
+		t.Errorf("redacting a %d byte chain of split JWTs allocated %d bytes, over the %d byte limit", len(chain), used, limit)
+	}
+}
+
+// A MATCH THE FILTER REJECTS MUST NOT HIDE THE KEY IT RAN INTO.
+//
+// The OpenAI shape is filtered, because kebab-case with no digit in it is prose
+// and not a key. A rejected match still spans the text it matched, and its body
+// runs on through a separator into whatever follows, so a split key after a
+// kebab-case name was rejected along with the name and printed in full.
+func TestSplitRedactionDoesNotLetARejectedNeighbourHideASplitKey(t *testing.T) {
+	const prose = "sk-some-kebab-case-name-here-ok"
+	const key = "sk-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefgh"
+	if !strings.Contains(RedactString(prose, Options{}), prose) {
+		t.Fatal("SETUP INVALID: the prose is redacted on its own, so it is not a rejected match")
+	}
+	if strings.Contains(RedactString(key, Options{}), key) {
+		t.Fatal("SETUP INVALID: the key is not redacted even whole, so it is not a credential")
+	}
+	value := prose + nulSeparator + splitInTheMiddle(key, escSeparator)
+	want := prose + nulSeparator + RedactedSecret
+	if got := RedactString(value, Options{}); got != want {
+		t.Errorf("RedactString(...) = %q, want %q", got, want)
+	}
+}
+
+// ORDINARY TEXT AFTER A KEY IS NOT PART OF THE KEY. Removing the separator
+// between them joins the word behind it onto the end of the key, and an
+// unbounded shape then carries the replacement over text that was never secret.
+func TestSplitRedactionLeavesTextBehindAKeyAlone(t *testing.T) {
+	for _, testCase := range []struct {
+		name  string
+		value string
+		want  string
+	}{
+		{"word", openaiKey + nulSeparator + "ordinary prose here", RedactedSecret + nulSeparator + "ordinary prose here"},
+		{"escape then word", openaiKey + escSeparator + "ordinary", RedactedSecret + escSeparator + "ordinary"},
+		{"zero width then word", githubKey + zwspSeparator + "ordinary", RedactedSecret + zwspSeparator + "ordinary"},
+		{"digits", awsKey + nulSeparator + "0123456789", RedactedSecret + nulSeparator + "0123456789"},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			if got := RedactString(testCase.value, Options{}); got != testCase.want {
+				t.Errorf("RedactString(...) = %q, want %q", got, testCase.want)
+			}
+		})
+	}
+}
+
+// THE OFFSET TABLE IS SIZED BY THE MATCHES, NOT BY THE TEXT IT SEARCHED.
+//
+// RedactString is handed whole command output, verification stdout and
+// notification bodies, none of which is bounded before it runs, and an index
+// carrying a start and an end for every source byte costs sixteen bytes per byte
+// of input on a 64-bit build. Measured against the same text with no separator
+// in it, so the regex work and the output copy cancel out and what is left is
+// what the split path added.
+func TestSplitRedactionDoesNotIndexEverySourceByte(t *testing.T) {
+	const line = "plain log output line with no secret in it "
+	filler := strings.Repeat(line, (1<<20)/len(line))
+	split := filler + " " + splitInTheMiddle(awsKey, escSeparator)
+	plain := filler + " " + awsKey
+	if got := RedactString(split, Options{}); !strings.HasSuffix(got, RedactedSecret) {
+		t.Fatalf("SETUP INVALID: the split key in the large input is not redacted, so nothing indexes it: %q", got[len(got)-64:])
+	}
+	// Four times the input still fails an index of two ints per source byte,
+	// which needs sixteen, and clears the copy this path actually makes.
+	limit := int64(4 * len(split))
+	overhead := redactAllocBytes(split) - redactAllocBytes(plain)
+	if overhead > limit {
+		t.Errorf("redacting %d bytes with a split key allocated %d bytes more than the same text without one, over the %d byte limit",
+			len(split), overhead, limit)
+	}
+}
+
+// redactAllocBytes is the smallest number of bytes any of three RedactString
+// calls allocated. Smallest rather than mean because a garbage collection or an
+// unrelated goroutine can only ever add to the figure.
+func redactAllocBytes(value string) int64 {
+	smallest := int64(-1)
+	for i := 0; i < 3; i++ {
+		var before, after runtime.MemStats
+		runtime.GC()
+		runtime.ReadMemStats(&before)
+		out := RedactString(value, Options{})
+		runtime.ReadMemStats(&after)
+		if len(out) == 0 {
+			panic("RedactString returned nothing")
+		}
+		used := int64(after.TotalAlloc - before.TotalAlloc)
+		if smallest < 0 || used < smallest {
+			smallest = used
+		}
+	}
+	return smallest
+}
+
+// A REPLACEMENT ALREADY ON THE PAGE IS A BARRIER. The default marker is spelled
+// with brackets, which no credential body admits, so it stops a match by
+// itself. A caller is free to supply one made of ordinary word characters, and
+// then the text left by the contiguous pass would read as the middle of a key
+// and carry the replacement out over both delimiters and the text behind them.
+func TestSplitRedactionStopsAtACallerSuppliedReplacement(t *testing.T) {
+	options := Options{Replacement: "REDACTED"}
+	value := "sk-aaaaa" + nulSeparator + awsKey + nulSeparator + "bbbbbbbbbbbbbbb"
+	want := "sk-aaaaa" + nulSeparator + "REDACTED" + nulSeparator + "bbbbbbbbbbbbbbb"
+	if got := RedactString(value, options); got != want {
+		t.Errorf("RedactString(...) = %q, want %q", got, want)
+	}
+}
+
+// A REJECTED MATCH MUST NOT SHADOW THE REAL KEY BEHIND IT. Raised by CodeRabbit
+// on #1067. With the separators removed before matching, the leftmost AWS match
+// in "xAKIA<NUL>AKIAIOSF<SOH>ODNN7EXAMPLE" began at the decoy AKIA, was rejected
+// for the "x" in front of it, and had already consumed the start of the real key,
+// so the real key was never tried. "ask-" in front of a split OpenAI key does the
+// same through "sk-", which is the ordinary-prose version of it. Each input is
+// checked against its unsplit counterpart, which main already redacts.
+func TestSplitRedactionDoesNotLetARejectedMatchShadowTheRealKey(t *testing.T) {
+	soh := string(rune(0x01))
+	for _, testCase := range []struct {
+		name    string
+		split   string
+		unsplit string
+	}{
+		{"decoy AKIA before a split key", "xAKIA" + nulSeparator + "AKIAIOSFODNN7E" + soh + "XAMPLE", "xAKIA" + nulSeparator + awsKey},
+		{"ask- before a split OpenAI key", "ask-" + nulSeparator + splitInTheMiddle(openaiKey, soh), "ask-" + nulSeparator + openaiKey},
+		{"task- before a split OpenAI key", "task-" + escSeparator + splitInTheMiddle(openaiKey, zwspSeparator), "task-" + escSeparator + openaiKey},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			want := RedactString(testCase.unsplit, Options{})
+			if strings.Contains(want, awsKey) || strings.Contains(want, openaiKey) {
+				t.Fatalf("SETUP INVALID: main does not redact the unsplit form either: %q", want)
+			}
+			if got := RedactString(testCase.split, Options{}); got != want {
+				t.Errorf("RedactString(split) = %q, want the unsplit form's %q", got, want)
+			}
+		})
+	}
+}
+
+// AN UNBOUNDED BODY MUST NOT TAKE A NEIGHBOUR'S PREFIX WITH IT. With gaps allowed
+// between body characters, a split key's body runs on across a separator into
+// whatever follows. When that is a JWT, it stops only at the JWT's first dot, and
+// if the shapes were applied one after another the JWT shape would then find its
+// header gone and leave the payload and signature in the clear. The shapes are
+// matched against the same text and their union replaced, so it cannot.
+func TestSplitRedactionKeepsANeighbourWhosePrefixASplitBodyWouldSwallow(t *testing.T) {
+	cut := len(jwtToken) / 2
+	splitJWT := jwtToken[:cut] + nulSeparator + jwtToken[cut:]
+	for _, testCase := range []struct {
+		name  string
+		value string
+	}{
+		{"split Anthropic key, a word, then a split JWT", splitInTheMiddle(anthropicKey, zwspSeparator) + escSeparator + "build" + escSeparator + splitJWT},
+		{"split GitHub key, then a split JWT", splitInTheMiddle(githubKey, nulSeparator) + escSeparator + splitJWT},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			got := rejoin(RedactString(testCase.value, Options{}))
+			for _, piece := range strings.Split(jwtToken, ".") {
+				if strings.Contains(got, piece) {
+					t.Errorf("part of the JWT survives: %q in %q", piece, got)
+				}
+			}
+		})
+	}
+}
+
+// A CREDENTIAL GLUED ONTO A SPLIT ONE GETS ITS BOUNDARY FROM THE REPLACEMENT.
+// Contiguous shapes cascade: once an AWS key is replaced, a JWT written straight
+// after it has the "]" in front of it and matches. A split key is replaced by
+// the second pass, so the JWT behind it needs a pass of its own after that one,
+// and the JWT is often whole, which means its region may hold no separator at
+// all by then. The second case adds a whole key elsewhere so that the strict
+// pass has already cut the text into regions.
+func TestSplitRedactionCascadesIntoACredentialGluedOntoASplitOne(t *testing.T) {
+	csi := string(rune(0x9b))
+	for _, testCase := range []struct {
+		name  string
+		value string
+	}{
+		{"whole JWT glued onto a split AWS key", splitInTheMiddle(awsKey, escSeparator) + jwtToken},
+		{"same, with a whole key elsewhere in the text", "user?q=" + "ASIAIOSFODNN7EXA" + csi + "MPLE" + jwtToken + "'" + awsKey + string(rune(0x7f)) + "ok"},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			got := rejoin(RedactString(testCase.value, Options{}))
+			for _, piece := range strings.Split(jwtToken, ".") {
+				if strings.Contains(got, piece) {
+					t.Errorf("part of the JWT survives: %q in %q", piece, got)
+				}
+			}
+		})
+	}
+}
+
+// THE CLASS AND THE PREDICATE ARE ONE FACT. splitSeparatorClass is generated
+// from the same tables as splitSecretSeparator; this walks every code point and
+// fails on the first one they disagree about.
+func TestSplitSeparatorClassAgreesWithThePredicate(t *testing.T) {
+	class := regexp.MustCompile("^" + splitSeparatorClass + "$")
+	for r := rune(0); r <= unicode.MaxRune; r++ {
+		if r >= 0xd800 && r <= 0xdfff {
+			continue // surrogates are not valid in a Go string
+		}
+		if got, want := class.MatchString(string(r)), splitSecretSeparator(r); got != want {
+			t.Fatalf("U+%04X: class matches = %v, predicate says %v", r, got, want)
+		}
+	}
+}
+
+// ON TEXT WITH NO SEPARATOR, EVERY GAP-TOLERANT SHAPE IS ITS ORIGINAL. The
+// rewrite only adds optional gaps, so a contiguous key has to produce exactly the
+// same match; anything else means the rewrite changed what a shape is.
+func TestGapTolerantShapesMatchContiguousKeysLikeTheOriginals(t *testing.T) {
+	inputs := []string{
+		"key=" + awsKey + " and " + githubKey,
+		"x" + awsKey,
+		anthropicKey + "." + openaiKey,
+		jwtToken + " then " + slackKey + ", " + googleKey,
+		"sk-this-is-kebab-case-prose-not-a-key",
+		"github_pat_11ABCDEFG0123456789_abcdefghijklmnopqrstuvwxyzABCDEFGH/glpat-abcdefghij0123456789",
+	}
+	originals := append([]*regexp.Regexp{openaiKeyPattern}, textSecretPatterns...)
+	tolerant := append([]*regexp.Regexp{splitOpenAIPattern}, splitTextPatterns...)
+	if len(originals) != len(tolerant) {
+		t.Fatalf("SETUP INVALID: %d original shapes and %d gap-tolerant ones", len(originals), len(tolerant))
+	}
+	for i := range originals {
+		for _, input := range inputs {
+			want := fmt.Sprint(originals[i].FindAllStringIndex(input, -1))
+			if got := fmt.Sprint(tolerant[i].FindAllStringIndex(input, -1)); got != want {
+				t.Errorf("shape %s on %q: gap-tolerant matched %s, original %s", originals[i], input, got, want)
+			}
+		}
+	}
+}

internal/redaction/redaction.go

@@ -227,8 +227,7 @@ func RedactString(value string, options Options) string {
 	// openai keys first so the filter can drop kebab-case false positives
 	// before any other pattern rewrites nearby text.
 	redacted = openaiKeyPattern.ReplaceAllStringFunc(redacted, func(match string) string {
-		if !knownOpenAIKeyPrefix(match) && !secretMatchHasDigit(match) &&
-			strings.Contains(strings.TrimPrefix(match, "sk-"), "-") {
+		if !openAIShapeIsSecret(match) {
 			return match
 		}
 		return replacement
@@ -236,6 +235,11 @@ func RedactString(value string, options Options) string {
 	for _, pattern := range textSecretPatterns {
 		redacted = pattern.ReplaceAllString(redacted, replacement)
 	}
+	// Credentials broken up by invisible characters last, over what the
+	// contiguous matchers left: a whole credential is already claimed by its own
+	// strict match, so this pass cannot reach out of one and into the next. It is
+	// a no-op for text with no such character, which is nearly all text.
+	redacted = redactControlSplitSecrets(redacted, replacement)
 	return redacted
 }
 

internal/sandbox/windows_acl.go

@@ -33,8 +33,14 @@ type WindowsACLEntry struct {
 	// down onto the target's EXISTING descendants (not just new ones it
 	// creates going forward), which is why direct-only denies must set this
 	// flag rather than rely on inheritance.
-	NoInherit   bool `json:"noInherit,omitempty"`
-	Materialize bool `json:"materialize,omitempty"`
+	NoInherit bool `json:"noInherit,omitempty"`
+	// Anchor is the write root Path was DERIVED from, for the paths this
+	// package constructs rather than the operator naming. The apply requires
+	// the object it finally opens to still live under it, so a reparse point
+	// planted on the derived tail cannot walk an elevated ACL write out of the
+	// sandbox. Empty for an operator-named path, which has no owned tail.
+	Anchor      string `json:"anchor,omitempty"`
+	Materialize bool   `json:"materialize,omitempty"`
 }
 
 type WindowsACLPlan struct {
@@ -57,10 +63,22 @@ func BuildWindowsACLPlan(config WindowsSandboxCommandConfig) (WindowsACLPlan, er
 			Capability: capability.SID,
 		})
 		for _, path := range capability.ProtectedWriteDenyPaths {
+			// ANCHORED ONLY WHERE THE ANCHOR IS TRUE. Most of these are derived
+			// from the root and sit under it, and holding those inside it is the
+			// point. But ReadOnlySubpaths is a profile field an operator can set to
+			// any path, and one deliberately placed outside the root is a
+			// configuration that works today; anchoring it would turn that into a
+			// containment refusal. A path that is not under the root gets no
+			// anchor and keeps the final-component guard it always had.
+			anchor := ""
+			if pathWithinRoot(capability.Root, path) {
+				anchor = capability.Root
+			}
 			entries = append(entries, WindowsACLEntry{
 				Action:     WindowsACLDenyWrite,
 				Path:       path,
 				Capability: capability.SID,
+				Anchor:     anchor,
 			})
 		}
 	}

internal/sandbox/windows_acl_apply_windows.go

@@ -23,7 +23,10 @@ const (
 )
 
 type windowsACLPathGroup struct {
-	Path        string
+	Path string
+	// Anchor is the write root Path was derived from, empty when the operator
+	// named the path. See verifyWindowsACLHandleUnderAnchor.
+	Anchor      string
 	Entries     []WindowsACLEntry
 	Materialize bool
 }
@@ -69,6 +72,12 @@ func groupWindowsACLPlanByPath(plan WindowsACLPlan) []windowsACLPathGroup {
 		}
 		group.Entries = append(group.Entries, entry)
 		group.Materialize = group.Materialize || entry.Materialize
+		// One path is derived from at most one root, so the first anchor seen is
+		// the anchor. Taking it rather than overwriting keeps a later
+		// operator-named duplicate of the same path from clearing it.
+		if group.Anchor == "" {
+			group.Anchor = entry.Anchor
+		}
 	}
 	out := make([]windowsACLPathGroup, 0, len(byPath))
 	for _, group := range byPath {
@@ -104,6 +113,13 @@ func applyWindowsACLPathGroup(group windowsACLPathGroup) (windowsACLSnapshot, bo
 			}
 			return windowsACLSnapshot{}, false, nil
 		}
+		// Before creating anything: os.MkdirAll walks a pathname and follows every
+		// reparse point on it, so a junction on the derived tail would have this
+		// elevated setup create the directory outside the write root and only the
+		// containment check below would notice, after the fact.
+		if err := verifyWindowsACLPathUnderAnchor(group.Anchor, path); err != nil {
+			return windowsACLSnapshot{}, false, err
+		}
 		if err := os.MkdirAll(path, 0o700); err != nil {
 			return windowsACLSnapshot{}, false, fmt.Errorf("materialize windows ACL target %s: %w", path, err)
 		}
@@ -123,6 +139,15 @@ func applyWindowsACLPathGroup(group windowsACLPathGroup) (windowsACLSnapshot, bo
 		}
 		return windowsACLSnapshot{}, false, err
 	}
+	// THE OBJECT HAS TO BE WHERE THE PLAN SAID IT WOULD BE. The open above
+	// refuses a reparse point at the final component and resolves every one
+	// above it, which is right for a path the operator named and not enough for
+	// one this package derived from a write root: a junction on the derived tail
+	// redirects the handle out of the sandbox with nothing about the final
+	// object looking wrong.
+	if err := verifyWindowsACLHandleUnderAnchor(handle, group.Anchor, path); err != nil {
+		return fail(err)
+	}
 	descriptor, err := windows.GetSecurityInfo(handle, windows.SE_FILE_OBJECT, windows.DACL_SECURITY_INFORMATION)
 	if err != nil {
 		return fail(fmt.Errorf("read windows ACL for %s: %w", path, err))

internal/sandbox/windows_acl_containment_windows.go

@@ -0,0 +1,228 @@
+//go:build windows
+
+package sandbox
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"golang.org/x/sys/windows"
+)
+
+// Keeping an elevated ACL write inside the tree it was planned for.
+//
+// FILE_FLAG_OPEN_REPARSE_POINT GUARDS ONE COMPONENT, AND A PATH HAS MANY. The
+// apply opens its target with that flag, which stops the FINAL component from
+// being followed and refuses the handle when it is a reparse point. Every
+// component above it is resolved normally, as it must be for any absolute path
+// to work at all.
+//
+// That is enough for a target the operator named, and not enough for one the
+// sandbox derived. The write-root carveouts are derived: <root>/.git/hooks and
+// <root>/.git/config are constructed from a root, and <root>/.git is a name an
+// unprivileged workspace writer can create. `mklink /J` needs no privilege, so
+// a junction there makes the apply open <junction-target>/hooks instead, and
+// `zero sandbox setup` writes a deny-write ACE, as Administrator, on an object
+// outside the workspace. The final-component flag never fires: the object at
+// the end of the walk is an ordinary directory.
+//
+// So the derived targets carry the root they were derived FROM, and the object
+// finally opened has to still be inside it. The check is on the handle, not on
+// the name: GetFinalPathNameByHandle answers where the object this process is
+// holding actually lives, and both sides of the comparison go through it so the
+// spelling is normalized the same way (\\?\ prefix, long names, drive letter).
+// A junction anywhere along the derived tail moves the answer out of the root
+// and the apply refuses.
+//
+// The rule is deliberately not "no reparse point anywhere in the path". Above
+// the write root the path belongs to the operator, who may legitimately keep a
+// workspace under a junction or a mapped directory, and refusing that would
+// break setups this has nothing to say about. Only the tail the sandbox itself
+// appended is held strict.
+
+// windowsFinalPathByHandle reports where an open handle's object actually lives.
+func windowsFinalPathByHandle(handle windows.Handle) (string, error) {
+	buffer := make([]uint16, windows.MAX_LONG_PATH)
+	n, err := windows.GetFinalPathNameByHandle(handle, &buffer[0], uint32(len(buffer)), 0)
+	if err != nil {
+		return "", err
+	}
+	if int(n) > len(buffer) {
+		buffer = make([]uint16, n)
+		n, err = windows.GetFinalPathNameByHandle(handle, &buffer[0], uint32(len(buffer)), 0)
+		if err != nil {
+			return "", err
+		}
+	}
+	return windows.UTF16ToString(buffer[:n]), nil
+}
+
+// windowsFinalPathOf opens path without following a final-component reparse
+// point and reports where the object lives. A missing path is surfaced as
+// os.ErrNotExist so callers can walk up to a parent that exists.
+func windowsFinalPathOf(path string) (string, error) {
+	utf16Path, err := windows.UTF16PtrFromString(path)
+	if err != nil {
+		return "", fmt.Errorf("encode windows path %s: %w", path, err)
+	}
+	handle, err := windows.CreateFile(
+		utf16Path,
+		windows.READ_CONTROL,
+		windows.FILE_SHARE_READ|windows.FILE_SHARE_WRITE|windows.FILE_SHARE_DELETE,
+		nil,
+		windows.OPEN_EXISTING,
+		windows.FILE_FLAG_BACKUP_SEMANTICS|windows.FILE_FLAG_OPEN_REPARSE_POINT,
+		0,
+	)
+	if err != nil {
+		return "", fmt.Errorf("open windows path %s: %w", path, err)
+	}
+	defer func() { _ = windows.CloseHandle(handle) }()
+	final, err := windowsFinalPathByHandle(handle)
+	if err != nil {
+		return "", fmt.Errorf("resolve windows path %s: %w", path, err)
+	}
+	return final, nil
+}
+
+// windowsACLTailUnderAnchor returns the components target adds to anchor, and
+// whether target is under anchor lexically at all.
+func windowsACLTailUnderAnchor(anchor, target string) (string, bool) {
+	relative, err := filepath.Rel(filepath.Clean(anchor), filepath.Clean(target))
+	if err != nil {
+		return "", false
+	}
+	if relative == "." {
+		return "", true
+	}
+	if relative == ".." || strings.HasPrefix(relative, ".."+string(filepath.Separator)) {
+		return "", false
+	}
+	return relative, true
+}
+
+// windowsACLContainmentError reports a derived target that resolved outside the
+// root it was derived from.
+type windowsACLContainmentError struct {
+	Anchor string
+	Target string
+	Actual string
+}
+
+func (err windowsACLContainmentError) Error() string {
+	return fmt.Sprintf(
+		"refusing to apply ACL to %s: it resolves to %s, outside the write root %s; "+
+			"a reparse point on the way down redirects an elevated ACL write out of the sandbox",
+		err.Target, err.Actual, err.Anchor)
+}
+
+// verifyWindowsACLHandleUnderAnchor refuses a handle whose object does not live
+// where the plan said it would.
+//
+// anchor empty means the target was named rather than derived, and there is no
+// owned tail to hold strict; the final-component check the caller already did is
+// the whole guard for those.
+func verifyWindowsACLHandleUnderAnchor(handle windows.Handle, anchor, target string) error {
+	if strings.TrimSpace(anchor) == "" {
+		return nil
+	}
+	tail, ok := windowsACLTailUnderAnchor(anchor, target)
+	if !ok {
+		return windowsACLContainmentError{Anchor: anchor, Target: target, Actual: target}
+	}
+	anchorFinal, err := windowsFinalPathOf(anchor)
+	if err != nil {
+		return fmt.Errorf("resolve write root %s: %w", anchor, err)
+	}
+	targetFinal, err := windowsFinalPathByHandle(handle)
+	if err != nil {
+		return fmt.Errorf("resolve windows ACL target %s: %w", target, err)
+	}
+	expected := anchorFinal
+	if tail != "" {
+		expected = filepath.Join(anchorFinal, tail)
+	}
+	if !strings.EqualFold(filepath.Clean(targetFinal), filepath.Clean(expected)) {
+		return windowsACLContainmentError{Anchor: anchor, Target: target, Actual: targetFinal}
+	}
+	return nil
+}
+
+// verifyWindowsACLPathUnderAnchor makes the same check against the deepest
+// component of target that exists, before anything is created.
+//
+// Materialization creates a missing target with os.MkdirAll, which walks a
+// pathname and follows every reparse point on it, so without this an elevated
+// setup creates the directory on the far side of a junction and only the
+// containment check afterwards notices. The window between this check and that
+// create is not closed here; closing it needs the components created relative to
+// retained handles, which is the rooted descent tracked in #808.
+func verifyWindowsACLPathUnderAnchor(anchor, target string) error {
+	if strings.TrimSpace(anchor) == "" {
+		return nil
+	}
+	if _, ok := windowsACLTailUnderAnchor(anchor, target); !ok {
+		return windowsACLContainmentError{Anchor: anchor, Target: target, Actual: target}
+	}
+	existing := filepath.Clean(target)
+	for {
+		if _, err := os.Lstat(existing); err == nil {
+			break
+		} else if !errors.Is(err, os.ErrNotExist) {
+			return fmt.Errorf("inspect windows ACL target %s: %w", existing, err)
+		}
+		parent := filepath.Dir(existing)
+		if parent == existing {
+			return nil
+		}
+		existing = parent
+	}
+	tail, ok := windowsACLTailUnderAnchor(anchor, existing)
+	if !ok || tail == "" {
+		// Above or at the write root, which is the operator's to arrange.
+		return nil
+	}
+	handle, err := windowsACLOpenForContainment(existing)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = windows.CloseHandle(handle) }()
+	// THE ANCESTOR ITSELF IS THE REDIRECTION, WHICH IS WHY ITS NAME LOOKS RIGHT.
+	//
+	// Asking only where this object lives answers "exactly where you asked": the
+	// open above does not follow a final-component reparse point, so a junction
+	// at <root>/.git comes back as <root>/.git. os.MkdirAll does follow it, and
+	// creates the missing components on the far side. So what disqualifies this
+	// ancestor is that it IS a reparse point, not where it reports living.
+	var info windows.ByHandleFileInformation
+	if err := windows.GetFileInformationByHandle(handle, &info); err != nil {
+		return fmt.Errorf("inspect windows ACL target %s: %w", existing, err)
+	}
+	if info.FileAttributes&windows.FILE_ATTRIBUTE_REPARSE_POINT != 0 {
+		return windowsACLContainmentError{Anchor: anchor, Target: target, Actual: existing + " (a reparse point)"}
+	}
+	return verifyWindowsACLHandleUnderAnchor(handle, anchor, existing)
+}
+
+func windowsACLOpenForContainment(path string) (windows.Handle, error) {
+	utf16Path, err := windows.UTF16PtrFromString(path)
+	if err != nil {
+		return 0, fmt.Errorf("encode windows ACL target %s: %w", path, err)
+	}
+	handle, err := windows.CreateFile(
+		utf16Path,
+		windows.READ_CONTROL,
+		windows.FILE_SHARE_READ|windows.FILE_SHARE_WRITE|windows.FILE_SHARE_DELETE,
+		nil,
+		windows.OPEN_EXISTING,
+		windows.FILE_FLAG_BACKUP_SEMANTICS|windows.FILE_FLAG_OPEN_REPARSE_POINT,
+		0,
+	)
+	if err != nil {
+		return 0, fmt.Errorf("open windows ACL target %s: %w", path, err)
+	}
+	return handle, nil
+}

internal/sandbox/windows_acl_containment_windows_test.go

@@ -0,0 +1,231 @@
+//go:build windows
+
+package sandbox
+
+import (
+	"errors"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// windowsACLTestDenySID is a well-known group this process is not a member of.
+//
+// A deny ACE is what the carveouts actually are, and denying a group the test
+// runs as revokes its own WRITE_DAC: the apply succeeds and then nothing can
+// put the DACL back, so the temporary tree cannot be removed. Guests keeps the
+// deny semantics without locking the test out of its own fixture.
+const windowsACLTestDenySID = "S-1-5-32-546"
+
+// makeACLJunction plants a directory junction at link pointing at target.
+//
+// A junction rather than a symlink on purpose: mklink /J needs no privilege, so
+// it is reachable by exactly the unprivileged workspace writer this guards
+// against, and the test runs on an ordinary developer or CI account.
+func makeACLJunction(t *testing.T, link, target string) {
+	t.Helper()
+	output, err := exec.Command("cmd.exe", "/c", "mklink", "/J", link, target).CombinedOutput()
+	if err != nil {
+		t.Skipf("mklink /J unavailable here: %v (%s)", err, output)
+	}
+}
+
+// AN ELEVATED ACL WRITE MUST NOT LEAVE THE WRITE ROOT THROUGH A JUNCTION.
+//
+// The apply opens its target with FILE_FLAG_OPEN_REPARSE_POINT, which refuses a
+// reparse point at the FINAL component and resolves every component above it.
+// The write-root carveouts are derived rather than named: <root>/.git/hooks and
+// <root>/.git/config are constructed from the root, and <root>/.git is a name an
+// unprivileged workspace writer can create before setup runs. A junction there
+// makes the apply open <junction-target>/hooks, an ordinary directory with
+// nothing wrong about its final component, and `zero sandbox setup` writes a
+// deny-write ACE on it as Administrator, outside the workspace.
+func TestApplyWindowsACLRefusesACarveoutRedirectedByAJunction(t *testing.T) {
+	root := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "elsewhere")
+	if err := os.MkdirAll(filepath.Join(outside, "hooks"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	makeACLJunction(t, filepath.Join(root, ".git"), outside)
+
+	carveout := filepath.Join(root, ".git", "hooks")
+	group := windowsACLPathGroup{
+		Path:   carveout,
+		Anchor: root,
+		Entries: []WindowsACLEntry{{
+			Action:     WindowsACLDenyWrite,
+			Path:       carveout,
+			Capability: windowsACLTestDenySID,
+			Anchor:     root,
+		}},
+	}
+
+	_, applied, err := applyWindowsACLPathGroup(group)
+	if applied {
+		t.Error("applied a deny-write ACE through a junction, so an elevated setup rewrote the DACL of an object outside the workspace")
+	}
+	var containment windowsACLContainmentError
+	if !errors.As(err, &containment) {
+		t.Fatalf("err = %v, want a containment refusal", err)
+	}
+	if !strings.Contains(containment.Actual, "elsewhere") {
+		t.Errorf("the refusal does not name where the target actually resolved: %v", containment)
+	}
+}
+
+// The same carveout inside an ordinary workspace still gets its ACE, or the
+// refusal above would prove only that the apply fails.
+func TestApplyWindowsACLStillAppliesAnOrdinaryCarveout(t *testing.T) {
+	root := t.TempDir()
+	carveout := filepath.Join(root, ".git", "hooks")
+	if err := os.MkdirAll(carveout, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	group := windowsACLPathGroup{
+		Path:   carveout,
+		Anchor: root,
+		Entries: []WindowsACLEntry{{
+			Action:     WindowsACLDenyWrite,
+			Path:       carveout,
+			Capability: windowsACLTestDenySID,
+			Anchor:     root,
+		}},
+	}
+
+	snapshot, applied, err := applyWindowsACLPathGroup(group)
+	if err != nil {
+		t.Fatalf("apply: %v", err)
+	}
+	// PUT IT BACK, OR THE TEMP TREE CANNOT BE REMOVED. The ACE just written
+	// denies write to the group this test runs as, and t.TempDir removes the
+	// tree when the test ends.
+	if applied {
+		t.Cleanup(func() {
+			if err := rollbackWindowsACLSnapshots([]windowsACLSnapshot{snapshot}); err != nil {
+				t.Errorf("rollback: %v", err)
+			}
+		})
+	}
+	if !applied {
+		t.Fatal("an ordinary carveout inside the write root was not applied")
+	}
+	if snapshot.Path != carveout {
+		t.Fatalf("snapshot path = %q, want %q", snapshot.Path, carveout)
+	}
+}
+
+// MATERIALIZATION MUST NOT CREATE THROUGH THE JUNCTION EITHER. os.MkdirAll
+// walks a pathname and follows every reparse point on it, so without the
+// pre-create check an elevated setup makes the directory on the far side and
+// only notices afterwards.
+func TestApplyWindowsACLRefusesToMaterializeThroughAJunction(t *testing.T) {
+	root := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "elsewhere")
+	if err := os.MkdirAll(outside, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	makeACLJunction(t, filepath.Join(root, ".git"), outside)
+
+	carveout := filepath.Join(root, ".git", "hooks")
+	if _, err := os.Lstat(filepath.Join(outside, "hooks")); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("SETUP INVALID: the target already holds hooks: %v", err)
+	}
+	group := windowsACLPathGroup{
+		Path:        carveout,
+		Anchor:      root,
+		Materialize: true,
+		Entries: []WindowsACLEntry{{
+			Action:      WindowsACLDenyRead,
+			Path:        carveout,
+			Capability:  windowsACLTestDenySID,
+			Anchor:      root,
+			Materialize: true,
+		}},
+	}
+
+	if _, applied, err := applyWindowsACLPathGroup(group); applied || err == nil {
+		t.Errorf("materialized through a junction: applied=%v err=%v", applied, err)
+	}
+	if _, err := os.Lstat(filepath.Join(outside, "hooks")); !errors.Is(err, os.ErrNotExist) {
+		t.Errorf("an elevated create landed outside the write root: %v", err)
+	}
+}
+
+// An operator-named path carries no anchor and keeps the behaviour it had: the
+// final component is still refused when it is a reparse point, and nothing above
+// it is second-guessed, because above the write root the path belongs to the
+// operator, who may keep a workspace under a junction.
+func TestApplyWindowsACLLeavesAnUnanchoredPathAlone(t *testing.T) {
+	base := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "elsewhere")
+	if err := os.MkdirAll(filepath.Join(outside, "leaf"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	makeACLJunction(t, filepath.Join(base, "link"), outside)
+
+	named := filepath.Join(base, "link", "leaf")
+	group := windowsACLPathGroup{
+		Path: named,
+		Entries: []WindowsACLEntry{{
+			Action:     WindowsACLDenyWrite,
+			Path:       named,
+			Capability: windowsACLTestDenySID,
+		}},
+	}
+
+	snapshot, applied, err := applyWindowsACLPathGroup(group)
+	if err != nil {
+		t.Fatalf("an operator-named path below a junction was refused: %v", err)
+	}
+	if applied {
+		t.Cleanup(func() {
+			if err := rollbackWindowsACLSnapshots([]windowsACLSnapshot{snapshot}); err != nil {
+				t.Errorf("rollback: %v", err)
+			}
+		})
+	}
+	if !applied {
+		t.Fatal("an operator-named path below a junction was not applied")
+	}
+}
+
+// AND THE GUARD ON THE CREATE HAS TO BE PINNED WHERE IT CAN BE SEEN.
+//
+// Through the whole apply, dropping the pre-create check is invisible: the
+// directory is made on the far side of the junction, the containment check on
+// the handle then refuses, and the failure path removes what it made, so the
+// filesystem afterwards looks the same either way. The transient elevated create
+// outside the write root is the thing being prevented, so it is checked here,
+// against the function that prevents it.
+func TestVerifyWindowsACLPathUnderAnchorRefusesAMissingTargetBehindAJunction(t *testing.T) {
+	root := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "elsewhere")
+	if err := os.MkdirAll(outside, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	makeACLJunction(t, filepath.Join(root, ".git"), outside)
+
+	carveout := filepath.Join(root, ".git", "hooks")
+	if _, err := os.Lstat(carveout); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("SETUP INVALID: the carveout already exists, so nothing would be created: %v", err)
+	}
+
+	err := verifyWindowsACLPathUnderAnchor(root, carveout)
+	var containment windowsACLContainmentError
+	if !errors.As(err, &containment) {
+		t.Fatalf("err = %v, want a containment refusal before anything is created", err)
+	}
+
+	// The ordinary case still says yes, or the refusal proves only that the
+	// function rejects things.
+	ordinary := t.TempDir()
+	if err := verifyWindowsACLPathUnderAnchor(ordinary, filepath.Join(ordinary, ".git", "hooks")); err != nil {
+		t.Errorf("an ordinary missing carveout was refused: %v", err)
+	}
+	// And an unanchored path is not this function's business.
+	if err := verifyWindowsACLPathUnderAnchor("", carveout); err != nil {
+		t.Errorf("an unanchored path was refused: %v", err)
+	}
+}

internal/sandbox/windows_acl_test.go

@@ -240,3 +240,117 @@ func TestDedupeWindowsACLEntriesKeepsInheritanceVariants(t *testing.T) {
 		t.Fatalf("dedupe order/shape = %#v, want first NoInherit then inheritable", out)
 	}
 }
+
+// THE PLAN HAS TO CARRY THE ANCHOR, OR THE APPLY HAS NOTHING TO ENFORCE.
+//
+// The apply-side tests hand applyWindowsACLPathGroup an anchor directly, so they
+// pass whether or not anything ever sets one. This drives the real builder and
+// checks which entries come out anchored: the carveouts derived from a write
+// root, and not the paths the operator named, which have no owned tail and whose
+// intermediates are the operator's own business.
+//
+// NATIVE PATHS, NOT WINDOWS LITERALS. The builder is cross-platform and so is
+// this test, and the anchoring decision runs through pathWithinRoot, which is
+// filepath.Rel underneath. On Linux a backslash is an ordinary character, so
+// `C:\workspace\.git\hooks` is one component and is not under `C:\workspace`;
+// the neighbouring tests get away with such literals because they only compare
+// strings they built the same way and never ask whether one contains another.
+func TestBuildWindowsACLPlanAnchorsDerivedCarveouts(t *testing.T) {
+	home := t.TempDir()
+	workspace := t.TempDir()
+	carveout := filepath.Join(workspace, ".git", "hooks")
+	metadata := filepath.Join(workspace, ".zero")
+	named := filepath.Join(t.TempDir(), "named-by-the-operator")
+	config := WindowsSandboxCommandConfig{
+		SandboxHome:    home,
+		WorkspaceRoots: []string{workspace},
+		PermissionProfile: PermissionProfile{
+			FileSystem: FileSystemPolicy{
+				Kind: FileSystemRestricted,
+				WriteRoots: []WritableRoot{{
+					Root:                   workspace,
+					ReadOnlySubpaths:       []string{carveout},
+					ProtectedMetadataNames: []string{".zero"},
+				}},
+				DenyWrite: []string{named},
+			},
+			Network: NetworkPolicy{Mode: NetworkDeny},
+		},
+	}
+
+	plan, err := BuildWindowsACLPlan(config)
+	if err != nil {
+		t.Fatalf("BuildWindowsACLPlan: %v", err)
+	}
+
+	anchors := map[string]string{}
+	for _, entry := range plan.Entries {
+		anchors[strings.ToLower(entry.Path)] = entry.Anchor
+	}
+	for _, derived := range []string{carveout, metadata} {
+		anchor, present := anchors[strings.ToLower(derived)]
+		if !present {
+			t.Fatalf("SETUP INVALID: the plan has no entry for the derived carveout %s", derived)
+		}
+		if anchor != workspace {
+			t.Errorf("derived carveout %s carries anchor %q, want the write root it came from", derived, anchor)
+		}
+	}
+	operatorAnchor, present := anchors[strings.ToLower(named)]
+	if !present {
+		t.Fatal("SETUP INVALID: the plan has no entry for the operator-named deny path")
+	}
+	if operatorAnchor != "" {
+		t.Errorf("operator-named path carries anchor %q, want none: its intermediates are not the sandbox's to police", operatorAnchor)
+	}
+}
+
+// AND AN OUT-OF-ROOT READ-ONLY SUBPATH IS NOT ANCHORED AT ALL.
+//
+// ReadOnlySubpaths is a profile field an operator can set to any path. One
+// placed outside the write root is a configuration that works today, and
+// anchoring it to that root would turn it into a containment refusal: the
+// object is not under the root and never was. Only the paths that are actually
+// under it are held to it.
+func TestBuildWindowsACLPlanLeavesAnOutOfRootSubpathUnanchored(t *testing.T) {
+	home := t.TempDir()
+	workspace := t.TempDir()
+	inside := filepath.Join(workspace, "vendor")
+	outside := filepath.Join(t.TempDir(), "shared")
+	plan, err := BuildWindowsACLPlan(WindowsSandboxCommandConfig{
+		SandboxHome:    home,
+		WorkspaceRoots: []string{workspace},
+		PermissionProfile: PermissionProfile{
+			FileSystem: FileSystemPolicy{
+				Kind: FileSystemRestricted,
+				WriteRoots: []WritableRoot{{
+					Root:             workspace,
+					ReadOnlySubpaths: []string{inside, outside},
+				}},
+			},
+			Network: NetworkPolicy{Mode: NetworkDeny},
+		},
+	})
+	if err != nil {
+		t.Fatalf("BuildWindowsACLPlan: %v", err)
+	}
+
+	seen := map[string]string{}
+	for _, entry := range plan.Entries {
+		seen[strings.ToLower(entry.Path)] = entry.Anchor
+	}
+	insideAnchor, present := seen[strings.ToLower(inside)]
+	if !present {
+		t.Fatal("SETUP INVALID: the plan has no entry for the in-root subpath")
+	}
+	if insideAnchor != workspace {
+		t.Errorf("in-root subpath carries anchor %q, want the write root", insideAnchor)
+	}
+	outsideAnchor, present := seen[strings.ToLower(outside)]
+	if !present {
+		t.Fatal("SETUP INVALID: the plan has no entry for the out-of-root subpath")
+	}
+	if outsideAnchor != "" {
+		t.Errorf("out-of-root subpath carries anchor %q, want none: the apply would refuse a config that works today", outsideAnchor)
+	}
+}

internal/swarm/lifecycle_test.go

@@ -8,6 +8,8 @@ import (
 	"sync/atomic"
 	"testing"
 	"time"
+
+	"github.com/Gitlawb/zero/internal/testutil"
 )
 
 // controllableLauncher records every launched spec and lets a test control each
@@ -85,18 +87,6 @@ func newSwarmForWithSize(t *testing.T, l MemberLauncher, maxTeamSize int) *Swarm
 	return sw
 }
 
-func waitFor(t *testing.T, what string, cond func() bool) {
-	t.Helper()
-	deadline := time.Now().Add(3 * time.Second)
-	for time.Now().Before(deadline) {
-		if cond() {
-			return
-		}
-		time.Sleep(5 * time.Millisecond)
-	}
-	t.Fatalf("timed out waiting for %s", what)
-}
-
 func okFor(spec MemberSpec, _ int) (MemberResult, error) {
 	return MemberResult{Result: "ok:" + spec.Task, SessionID: "sess-" + spec.ID}, nil
 }
@@ -108,7 +98,7 @@ func TestSpawnCompletes(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Spawn: %v", err)
 	}
-	waitFor(t, "task done", func() bool {
+	testutil.WaitFor(t, "task done", func() bool {
 		task, ok := sw.Coordinator().Get(id)
 		return ok && task.Status == StatusDone
 	})
@@ -125,7 +115,7 @@ func TestSpawnInheritsPolicy(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Spawn: %v", err)
 	}
-	waitFor(t, "spec recorded", func() bool { return len(l.recorded()) == 1 })
+	testutil.WaitFor(t, "spec recorded", func() bool { return len(l.recorded()) == 1 })
 	spec := l.recorded()[0]
 	if spec.Model != "orch-model" {
 		t.Fatalf("member model = %q, want inherited orch-model", spec.Model)
@@ -158,7 +148,7 @@ func TestConcurrencyCapAndQueueDrains(t *testing.T) {
 	}
 	// Release everyone; the queue should drain one-per-slot until all are done.
 	close(gate)
-	waitFor(t, "all tasks done", func() bool { return sw.Coordinator().Summarize().Done == 5 })
+	testutil.WaitFor(t, "all tasks done", func() bool { return sw.Coordinator().Summarize().Done == 5 })
 	if team.Running() != 0 || team.QueueDepth() != 0 {
 		t.Fatalf("after drain running=%d queue=%d, want 0/0", team.Running(), team.QueueDepth())
 	}
@@ -176,7 +166,7 @@ func TestRetryOnTemporaryError(t *testing.T) {
 	})
 	sw := newSwarmFor(t, l)
 	id, _ := sw.Spawn(Policy{}, "team", "teammate", "task", "")
-	waitFor(t, "task recovered", func() bool {
+	testutil.WaitFor(t, "task recovered", func() bool {
 		task, ok := sw.Coordinator().Get(id)
 		return ok && task.Status == StatusDone
 	})
@@ -195,7 +185,7 @@ func TestRetryExhaustionFails(t *testing.T) {
 	})
 	sw := newSwarmFor(t, l)
 	id, _ := sw.Spawn(Policy{}, "team", "teammate", "task", "")
-	waitFor(t, "task failed", func() bool {
+	testutil.WaitFor(t, "task failed", func() bool {
 		task, ok := sw.Coordinator().Get(id)
 		return ok && task.Status == StatusFailed
 	})
@@ -210,7 +200,7 @@ func TestPermanentErrorNoRetry(t *testing.T) {
 	})
 	sw := newSwarmFor(t, l)
 	id, _ := sw.Spawn(Policy{}, "team", "teammate", "task", "")
-	waitFor(t, "task failed", func() bool {
+	testutil.WaitFor(t, "task failed", func() bool {
 		task, ok := sw.Coordinator().Get(id)
 		return ok && task.Status == StatusFailed
 	})
@@ -296,7 +286,7 @@ func TestClosePreventsMemberRetry(t *testing.T) {
 		sw.Close()
 		close(closed)
 	}()
-	waitFor(t, "swarm closed state", func() bool {
+	testutil.WaitFor(t, "swarm closed state", func() bool {
 		sw.lifecycleMu.RLock()
 		defer sw.lifecycleMu.RUnlock()
 		return sw.closed
@@ -325,7 +315,7 @@ func TestCloseWaitsForMemberWatchers(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Spawn: %v", err)
 	}
-	waitFor(t, "task running", func() bool {
+	testutil.WaitFor(t, "task running", func() bool {
 		task, ok := sw.Coordinator().Get(id)
 		return ok && task.Status == StatusRunning
 	})
@@ -365,7 +355,7 @@ func TestHandoffDeliversNoteAndRetiresOriginal(t *testing.T) {
 	sw := newSwarmFor(t, l)
 	pol := Policy{Model: "m"}
 	origID, _ := sw.Spawn(pol, "team", "teammate", "original task", "/w")
-	waitFor(t, "original running", func() bool {
+	testutil.WaitFor(t, "original running", func() bool {
 		task, ok := sw.Coordinator().Get(origID)
 		return ok && task.Status == StatusRunning
 	})
@@ -389,7 +379,7 @@ func TestHandoffDeliversNoteAndRetiresOriginal(t *testing.T) {
 	}
 	// The new member carries the handoff note in its task and preserves cwd.
 	close(gate)
-	waitFor(t, "spec for new member", func() bool {
+	testutil.WaitFor(t, "spec for new member", func() bool {
 		for _, s := range l.recorded() {
 			if s.ID == newID {
 				return true
@@ -405,7 +395,7 @@ func TestHandoffDeliversNoteAndRetiresOriginal(t *testing.T) {
 		}
 	}
 	// A handoff of an already-terminal task is rejected.
-	waitFor(t, "new task done", func() bool {
+	testutil.WaitFor(t, "new task done", func() bool {
 		task, ok := sw.Coordinator().Get(newID)
 		return ok && task.Status == StatusDone
 	})
@@ -470,7 +460,7 @@ func TestHandoffMailboxFailureRestoresSourceCompletion(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Spawn: %v", err)
 	}
-	waitFor(t, "original running", func() bool {
+	testutil.WaitFor(t, "original running", func() bool {
 		task, ok := sw.Coordinator().Get(origID)
 		return ok && task.Status == StatusRunning
 	})
@@ -485,7 +475,7 @@ func TestHandoffMailboxFailureRestoresSourceCompletion(t *testing.T) {
 	}
 
 	close(gate)
-	waitFor(t, "source completion after aborted handoff", func() bool {
+	testutil.WaitFor(t, "source completion after aborted handoff", func() bool {
 		task, ok := sw.Coordinator().Get(origID)
 		return ok && task.Status == StatusDone
 	})
@@ -532,7 +522,7 @@ func TestHandoffSuccessorCollisionDoesNotStopSource(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Spawn: %v", err)
 	}
-	waitFor(t, "original running", func() bool {
+	testutil.WaitFor(t, "original running", func() bool {
 		task, ok := coord.Get(origID)
 		return ok && task.Status == StatusRunning
 	})
@@ -557,7 +547,7 @@ func TestHandoffSuccessorCollisionDoesNotStopSource(t *testing.T) {
 		t.Fatalf("collision misdelivered %d handoff notes to the existing task", len(msgs))
 	}
 	close(gate)
-	waitFor(t, "source completion after rejected collision", func() bool {
+	testutil.WaitFor(t, "source completion after rejected collision", func() bool {
 		task, ok := coord.Get(origID)
 		return ok && task.Status == StatusDone
 	})
@@ -643,7 +633,7 @@ func TestCloseReleasesBlockedHandoffBeforeMemberExit(t *testing.T) {
 	case <-time.After(3 * time.Second):
 		t.Fatal("Close did not return after the source member exited")
 	}
-	waitFor(t, "source completion after handoff cancellation", func() bool {
+	testutil.WaitFor(t, "source completion after handoff cancellation", func() bool {
 		task, ok := sw.Coordinator().Get(origID)
 		return ok && task.Status == StatusDone
 	})
@@ -704,7 +694,7 @@ func TestHandoffTimesOutWithoutStartingSuccessor(t *testing.T) {
 	}
 
 	close(releaseOriginal)
-	waitFor(t, "source completion after handoff timeout", func() bool {
+	testutil.WaitFor(t, "source completion after handoff timeout", func() bool {
 		task, ok := sw.Coordinator().Get(origID)
 		return ok && task.Status == StatusDone
 	})
@@ -876,7 +866,7 @@ func TestHandoffRemovesQueuedOriginalBeforeDispatchingSuccessor(t *testing.T) {
 	if _, err := sw.Spawn(pol, "team", "teammate", "slot blocker", "/w"); err != nil {
 		t.Fatalf("Spawn blocker: %v", err)
 	}
-	waitFor(t, "blocker running", func() bool { return len(l.recorded()) == 1 })
+	testutil.WaitFor(t, "blocker running", func() bool { return len(l.recorded()) == 1 })
 	origID, err := sw.Spawn(pol, "team", "teammate", "queued original", "/w")
 	if err != nil {
 		t.Fatalf("Spawn queued original: %v", err)
@@ -890,7 +880,7 @@ func TestHandoffRemovesQueuedOriginalBeforeDispatchingSuccessor(t *testing.T) {
 		t.Fatalf("Handoff: %v", err)
 	}
 	close(gate)
-	waitFor(t, "successor launch", func() bool {
+	testutil.WaitFor(t, "successor launch", func() bool {
 		for _, spec := range l.recorded() {
 			if spec.ID == newID {
 				return true
@@ -923,7 +913,7 @@ func TestAdoptOrphans(t *testing.T) {
 		t.Fatalf("adopted = %v, want [orphan-1]", adopted)
 	}
 	// The orphan is relaunched under a fresh agent and completes.
-	waitFor(t, "orphan completed", func() bool {
+	testutil.WaitFor(t, "orphan completed", func() bool {
 		task, ok := sw.Coordinator().Get("orphan-1")
 		return ok && task.Status == StatusDone
 	})
@@ -964,7 +954,7 @@ func TestCollectScopesToTeam(t *testing.T) {
 	sw := newSwarmFor(t, l)
 	a, _ := sw.Spawn(Policy{}, "alpha", "teammate", "ta", "")
 	_, _ = sw.Spawn(Policy{}, "beta", "teammate", "tb", "")
-	waitFor(t, "alpha done", func() bool {
+	testutil.WaitFor(t, "alpha done", func() bool {
 		task, ok := sw.Coordinator().Get(a)
 		return ok && task.Status == StatusDone
 	})
@@ -1110,7 +1100,7 @@ func TestAdmittedDispatchDoesNotLaunchAfterClose(t *testing.T) {
 		sw.Close()
 		close(closed)
 	}()
-	waitFor(t, "swarm closed state", func() bool {
+	testutil.WaitFor(t, "swarm closed state", func() bool {
 		sw.lifecycleMu.RLock()
 		defer sw.lifecycleMu.RUnlock()
 		return sw.closed
@@ -1170,7 +1160,7 @@ func TestCloseBetweenLaunchPrecheckAndReturn(t *testing.T) {
 		sw.Close()
 		close(closed)
 	}()
-	waitFor(t, "swarm closed state", func() bool {
+	testutil.WaitFor(t, "swarm closed state", func() bool {
 		sw.lifecycleMu.RLock()
 		defer sw.lifecycleMu.RUnlock()
 		return sw.closed
@@ -1268,7 +1258,7 @@ func TestCloseBetweenRetryLaunchPrecheckAndReturn(t *testing.T) {
 		sw.Close()
 		close(closed)
 	}()
-	waitFor(t, "swarm closed state", func() bool {
+	testutil.WaitFor(t, "swarm closed state", func() bool {
 		sw.lifecycleMu.RLock()
 		defer sw.lifecycleMu.RUnlock()
 		return sw.closed
@@ -1460,7 +1450,7 @@ func TestCloseFailsQueuedSpecOnLateCreatedTeam(t *testing.T) {
 		sw.Close()
 		close(closed)
 	}()
-	waitFor(t, "swarm closed state", func() bool {
+	testutil.WaitFor(t, "swarm closed state", func() bool {
 		sw.lifecycleMu.RLock()
 		defer sw.lifecycleMu.RUnlock()
 		return sw.closed

internal/swarm/scheduler_test.go

@@ -4,6 +4,8 @@ import (
 	"math"
 	"testing"
 	"time"
+
+	"github.com/Gitlawb/zero/internal/testutil"
 )
 
 // testTicker returns a ticker factory backed by a single unbounded-handshake
@@ -39,11 +41,11 @@ func TestSchedulerFiresAndCountsRuns(t *testing.T) {
 	for i := 0; i < 3; i++ {
 		ticks <- time.Time{}
 		want := i + 1
-		waitFor(t, "task completed", func() bool { return sw.Coordinator().Summarize().Done == want })
+		testutil.WaitFor(t, "task completed", func() bool { return sw.Coordinator().Summarize().Done == want })
 	}
 
 	// After MaxRuns the job retires itself.
-	waitFor(t, "job retired", func() bool { _, ok := findJob(sched.List(), id); return !ok })
+	testutil.WaitFor(t, "job retired", func() bool { _, ok := findJob(sched.List(), id); return !ok })
 	if got := len(l.recorded()); got != 3 {
 		t.Fatalf("spawned %d members, want 3", got)
 	}
@@ -68,11 +70,11 @@ func TestSchedulerSkipsWhilePreviousRuns(t *testing.T) {
 
 	// Fire 1: spawns and the member stays running (gated).
 	ticks <- time.Time{}
-	waitFor(t, "first spawn", func() bool { return len(l.recorded()) == 1 })
+	testutil.WaitFor(t, "first spawn", func() bool { return len(l.recorded()) == 1 })
 
 	// Fire 2: previous still running => skipped, no new spawn.
 	ticks <- time.Time{}
-	waitFor(t, "skip recorded", func() bool {
+	testutil.WaitFor(t, "skip recorded", func() bool {
 		j, ok := findJob(sched.List(), id)
 		return ok && j.Skipped == 1
 	})
@@ -82,14 +84,14 @@ func TestSchedulerSkipsWhilePreviousRuns(t *testing.T) {
 
 	// Release the first member, then fire 3: previous terminal => spawns again.
 	close(gate)
-	waitFor(t, "first done", func() bool { return sw.Coordinator().Summarize().Done == 1 })
+	testutil.WaitFor(t, "first done", func() bool { return sw.Coordinator().Summarize().Done == 1 })
 	ticks <- time.Time{}
-	waitFor(t, "second spawn", func() bool { return len(l.recorded()) == 2 })
+	testutil.WaitFor(t, "second spawn", func() bool { return len(l.recorded()) == 2 })
 	// fireIfIdle's spawn (what "second spawn" observes via the launcher) and
 	// run's subsequent job.incRuns() are sequential but distinct steps in the
 	// scheduler's goroutine; wait for Runs itself rather than assuming the
 	// launcher recording it means the job's counter is updated too.
-	waitFor(t, "second run recorded", func() bool {
+	testutil.WaitFor(t, "second run recorded", func() bool {
 		j, ok := findJob(sched.List(), id)
 		return ok && j.Runs == 2
 	})
@@ -215,7 +217,7 @@ func TestSchedulerDailyRecomputesNextDelay(t *testing.T) {
 	}
 	for i := 0; i < 2; i++ {
 		ticks <- time.Time{}
-		waitFor(t, "task completed", func() bool { return sw.Coordinator().Summarize().Done == i+1 })
+		testutil.WaitFor(t, "task completed", func() bool { return sw.Coordinator().Summarize().Done == i+1 })
 	}
 	if len(delays) < 2 {
 		t.Fatalf("expected at least two requested delays, got %v", delays)

internal/swarm/tools_test.go

@@ -8,6 +8,7 @@ import (
 	"time"
 	"unicode/utf8"
 
+	"github.com/Gitlawb/zero/internal/testutil"
 	"github.com/Gitlawb/zero/internal/tools"
 )
 
@@ -94,7 +95,7 @@ func TestSpawnToolThroughRegistry(t *testing.T) {
 	if id == "" {
 		t.Fatal("spawn must return a task_id in Meta")
 	}
-	waitFor(t, "spec recorded", func() bool { return len(l.recorded()) == 1 })
+	testutil.WaitFor(t, "spec recorded", func() bool { return len(l.recorded()) == 1 })
 	spec := l.recorded()[0]
 	if spec.Model != "m1" || spec.Cwd != "/work" {
 		t.Fatalf("policy/cwd not threaded into member: model=%q cwd=%q", spec.Model, spec.Cwd)
@@ -165,7 +166,7 @@ func TestStatusAndCollectTools(t *testing.T) {
 		"agent_type": "teammate", "task": "compute", "team": "alpha",
 	}, tools.RunOptions{PermissionGranted: true, Model: "m"})
 	id := spawn.Meta["task_id"]
-	waitFor(t, "task done", func() bool {
+	testutil.WaitFor(t, "task done", func() bool {
 		task, ok := sw.Coordinator().Get(id)
 		return ok && task.Status == StatusDone
 	})
@@ -213,7 +214,7 @@ func TestCollectBlocksUntilMembersFinish(t *testing.T) {
 		"agent_type": "teammate", "task": "compute", "team": "alpha",
 	}, tools.RunOptions{PermissionGranted: true, Model: "m"})
 	id := spawn.Meta["task_id"]
-	waitFor(t, "member running", func() bool {
+	testutil.WaitFor(t, "member running", func() bool {
 		task, ok := sw.Coordinator().Get(id)
 		return ok && task.Status == StatusRunning
 	})
@@ -258,7 +259,7 @@ func TestCollectReturnsPartialOnTimeout(t *testing.T) {
 		"agent_type": "teammate", "task": "compute", "team": "alpha",
 	}, tools.RunOptions{PermissionGranted: true, Model: "m"})
 	id := spawn.Meta["task_id"]
-	waitFor(t, "member running", func() bool {
+	testutil.WaitFor(t, "member running", func() bool {
 		task, ok := sw.Coordinator().Get(id)
 		return ok && task.Status == StatusRunning
 	})
@@ -324,7 +325,7 @@ func TestNewWithUserDefinitions(t *testing.T) {
 	if _, err := sw.Spawn(Policy{Model: "m"}, "team", "researcher", "find things", ""); err != nil {
 		t.Fatalf("Spawn user-defined agent: %v", err)
 	}
-	waitFor(t, "researcher used", func() bool { return used })
+	testutil.WaitFor(t, "researcher used", func() bool { return used })
 
 	// A bad definition makes New fail closed.
 	if _, err := New(Options{BaseDir: t.TempDir(), Launcher: newLauncher(okFor), Definitions: []Definition{{AgentType: "  "}}}); err == nil {
@@ -341,7 +342,7 @@ func TestHandoffToolThroughRegistry(t *testing.T) {
 		"agent_type": "teammate", "task": "long", "team": "alpha",
 	}, tools.RunOptions{PermissionGranted: true, Model: "m"})
 	origID := spawn.Meta["task_id"]
-	waitFor(t, "running", func() bool {
+	testutil.WaitFor(t, "running", func() bool {
 		task, ok := sw.Coordinator().Get(origID)
 		return ok && task.Status == StatusRunning
 	})

internal/testutil/waitfor.go

@@ -0,0 +1,23 @@
+// Package testutil provides small, shared helpers for tests across the
+// codebase.
+package testutil
+
+import (
+	"testing"
+	"time"
+)
+
+// WaitFor polls cond until it returns true, or fails the test if it does not
+// become true within a generous deadline. what names the condition being
+// waited for so a timeout failure message is actionable.
+func WaitFor(t *testing.T, what string, cond func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		if cond() {
+			return
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	t.Fatalf("timed out waiting for %s", what)
+}

internal/tools/apply_patch_tolerance_test.go

@@ -2,8 +2,10 @@ package tools
 
 import (
 	"context"
+	"errors"
 	"os"
 	"path/filepath"
+	"slices"
 	"strconv"
 	"strings"
 	"testing"
@@ -363,7 +365,7 @@ func TestUnifiedPatchCopyOperation(t *testing.T) {
 	if content, _ := os.ReadFile(filepath.Join(root, "dst.txt")); string(content) != "hello\nnew\n" {
 		t.Fatalf("copy destination = %q", string(content))
 	}
-	if len(result.ChangedFiles) != 2 || result.ChangedFiles[0] != "src.txt" || result.ChangedFiles[1] != "dst.txt" {
+	if len(result.ChangedFiles) != 1 || result.ChangedFiles[0] != "dst.txt" {
 		t.Fatalf("changed files = %v", result.ChangedFiles)
 	}
 	destination, err := filepath.EvalSymlinks(filepath.Join(root, "dst.txt"))
@@ -571,9 +573,9 @@ func TestApplyStructuredPatchChangeRefusesSourceChangedAfterPlanning(t *testing.
 		"copy":   {kind: structuredPatchCopy, from: target, to: destination, before: "planned\n", after: "planned\n", mode: 0o644},
 	} {
 		writeTestFile(t, path, "changed after planning\n")
-		committed, err := applyStructuredPatchChange(workspace, change)
-		if err == nil || committed || !strings.Contains(err.Error(), "changed on disk between planning and commit") {
-			t.Fatalf("%s: expected a refusal, got committed=%v err=%v", name, committed, err)
+		outcome, err := applyStructuredPatchChange(workspace, change)
+		if err == nil || len(outcome.completed) != 0 || len(outcome.incompletePaths) != 0 || !strings.Contains(err.Error(), "changed on disk between planning and commit") {
+			t.Fatalf("%s: expected a refusal, got outcome=%#v err=%v", name, outcome, err)
 		}
 		if content, _ := os.ReadFile(path); string(content) != "changed after planning\n" {
 			t.Fatalf("%s: file must be untouched, got %q", name, string(content))
@@ -709,4 +711,158 @@ func TestApplyPatchOperationsReportsCommittedPrefixOnFailure(t *testing.T) {
 	if content, _ := os.ReadFile(filepath.Join(root, "third.txt")); string(content) != "three\n" {
 		t.Fatalf("third.txt must be untouched, got %q", string(content))
 	}
+	if got := result.ChangedFiles; len(got) != 1 || got[0] != "first.txt" {
+		t.Fatalf("partial patch ChangedFiles = %#v, want committed prefix only", got)
+	}
+	resolvedFirst, err := filepath.EvalSymlinks(filepath.Join(root, "first.txt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := result.FileDiffs; len(got) != 1 || got[0] != (FileDiff{Path: resolvedFirst, OldExists: true, NewExists: true, OldText: "one\n", NewText: "ONE\n"}) {
+		t.Fatalf("partial patch FileDiffs = %#v", got)
+	}
+}
+
+func TestApplyPatchOperationsReportsWorkspaceRelativeCommittedPrefixUnderCwd(t *testing.T) {
+	root := t.TempDir()
+	applyRoot := filepath.Join(root, "sub", "dir")
+	if err := os.MkdirAll(applyRoot, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	writeTestFile(t, filepath.Join(applyRoot, "first.txt"), "one\n")
+	writeTestFile(t, filepath.Join(applyRoot, "second.txt"), "two\n")
+	structuredPatchBeforeCommit = func(change structuredPatchChange) {
+		if change.to.relative == "second.txt" {
+			writeTestFile(t, filepath.Join(applyRoot, "second.txt"), "changed\n")
+		}
+	}
+	t.Cleanup(func() { structuredPatchBeforeCommit = nil })
+	patch := strings.Join([]string{
+		"*** Begin Patch",
+		"*** Update File: first.txt", "@@", "-one", "+ONE",
+		"*** Update File: second.txt", "@@", "-two", "+TWO",
+		"*** End Patch", "",
+	}, "\n")
+
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{
+		"cwd": "sub/dir", "patch": patch,
+	})
+	if result.Status != StatusError || !strings.Contains(result.Output, "already committed: sub/dir/first.txt") {
+		t.Fatalf("nested partial failure = status=%s output=%q", result.Status, result.Output)
+	}
+	if got := result.ChangedFiles; len(got) != 1 || got[0] != "sub/dir/first.txt" {
+		t.Fatalf("nested partial ChangedFiles = %#v", got)
+	}
+}
+
+func TestApplyPatchSeparatesVerifiedAndUnverifiedPartialPublications(t *testing.T) {
+	root := t.TempDir()
+	priorPublish := structuredPatchPublishNoReplace
+	structuredPatchPublishNoReplace = func(workspace *os.Root, source, target string, mode os.FileMode) (bool, error) {
+		if target != "uncertain.txt" {
+			return priorPublish(workspace, source, target, mode)
+		}
+		file, err := workspace.OpenFile(target, os.O_WRONLY|os.O_CREATE|os.O_EXCL, mode.Perm())
+		if err != nil {
+			return false, err
+		}
+		if _, err := file.WriteString("partial"); err != nil {
+			_ = file.Close()
+			return true, err
+		}
+		if err := file.Close(); err != nil {
+			return true, err
+		}
+		return true, errors.New("injected failure after partial publication")
+	}
+	t.Cleanup(func() { structuredPatchPublishNoReplace = priorPublish })
+
+	patch := strings.Join([]string{
+		"*** Begin Patch",
+		"*** Add File: verified.txt", "+verified",
+		"*** Add File: uncertain.txt", "+intended complete content",
+		"*** Add File: untouched.txt", "+untouched",
+		"*** End Patch", "",
+	}, "\n")
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch})
+
+	if result.Status != StatusError {
+		t.Fatalf("partial publication status = %s, want error", result.Status)
+	}
+	for _, want := range []string{"already committed: verified.txt", "published but unverified: uncertain.txt"} {
+		if !strings.Contains(result.Output, want) {
+			t.Fatalf("partial publication error must contain %q: %s", want, result.Output)
+		}
+	}
+	committedFragment := strings.SplitN(result.Output, "; published but unverified:", 2)[0]
+	if strings.Contains(committedFragment, "uncertain.txt") {
+		t.Fatalf("unverified path appears in committed fragment: %s", result.Output)
+	}
+	if got, want := result.ChangedFiles, []string{"verified.txt"}; !slices.Equal(got, want) {
+		t.Fatalf("ChangedFiles = %#v, want verified publications only %#v", got, want)
+	}
+	resolvedVerified, err := filepath.EvalSymlinks(filepath.Join(root, "verified.txt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := result.FileDiffs; len(got) != 1 || got[0].Path != resolvedVerified {
+		t.Fatalf("FileDiffs = %#v, want verified.txt only", got)
+	}
+	if got := mustReadTestFile(t, filepath.Join(root, "verified.txt")); got != "verified\n" {
+		t.Fatalf("verified publication = %q", got)
+	}
+	if got := mustReadTestFile(t, filepath.Join(root, "uncertain.txt")); got != "partial" {
+		t.Fatalf("unverified publication = %q", got)
+	}
+	if _, err := os.Stat(filepath.Join(root, "untouched.txt")); !os.IsNotExist(err) {
+		t.Fatalf("later publication must remain untouched: %v", err)
+	}
+}
+
+func TestApplyPatchMoveReportsPublishedDestinationWhenSourceRemovalFails(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "source.txt"), "before\n")
+	priorRemove := structuredPatchRemove
+	structuredPatchRemove = func(workspace *os.Root, name string) error {
+		if name == "source.txt" {
+			return os.ErrPermission
+		}
+		return priorRemove(workspace, name)
+	}
+	t.Cleanup(func() { structuredPatchRemove = priorRemove })
+
+	patch := strings.Join([]string{
+		"*** Begin Patch",
+		"*** Update File: source.txt",
+		"*** Move to: destination.txt",
+		"@@",
+		"-before",
+		"+after",
+		"*** End Patch",
+		"",
+	}, "\n")
+	result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch})
+	if result.Status != StatusError {
+		t.Fatalf("move status = %s, want error", result.Status)
+	}
+	if got := mustReadTestFile(t, filepath.Join(root, "source.txt")); got != "before\n" {
+		t.Fatalf("source content = %q", got)
+	}
+	if got := mustReadTestFile(t, filepath.Join(root, "destination.txt")); got != "after\n" {
+		t.Fatalf("destination content = %q", got)
+	}
+	if got, want := result.ChangedFiles, []string{"destination.txt"}; !slices.Equal(got, want) {
+		t.Fatalf("ChangedFiles = %#v, want %#v", got, want)
+	}
+	resolvedDestination, err := filepath.EvalSymlinks(filepath.Join(root, "destination.txt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantDiff := FileDiff{Path: resolvedDestination, OldExists: false, NewExists: true, NewText: "after\n"}
+	if got := result.FileDiffs; len(got) != 1 || got[0] != wantDiff {
+		t.Fatalf("FileDiffs = %#v, want %#v", got, []FileDiff{wantDiff})
+	}
+	if !strings.Contains(result.Display.Preview, "destination.txt") || strings.Contains(result.Display.Preview, "source.txt") {
+		t.Fatalf("preview must show only destination creation: %q", result.Display.Preview)
+	}
 }

internal/tools/diff_preview.go

@@ -1,19 +1,122 @@
 package tools
 
-import udiff "github.com/aymanbagabas/go-udiff"
+import (
+	"path/filepath"
+	"strings"
+	"unicode"
+	"unicode/utf8"
+
+	"github.com/Gitlawb/zero/internal/redaction"
+	udiff "github.com/aymanbagabas/go-udiff"
+)
 
 // maxToolPreviewBytes caps the inline diff a write tool appends to its result, so
 // a large generated file can't flood the transcript or balloon the persisted
 // session events. Past this the tool falls back to its summary line alone.
 const maxToolPreviewBytes = 48 * 1024
 
+// A structured replacement contains two complete file sides, so its transport
+// budget is intentionally separate from the single rendered-preview budget.
+// Each side may be as large as a normal preview; aggregate producers apply the
+// two-sided result cap in file order.
+const maxToolResultFileDiffBytes = 2 * maxToolPreviewBytes
+
+// FileDiff is a human-facing before/after file change. Registry-boundary
+// redaction applies to both sides before any caller receives it.
+type FileDiff struct {
+	// Path is the canonical absolute path required by ACP diff content. The
+	// separate ChangedFiles result remains workspace-relative for local UI use.
+	Path string
+	// OldExists and NewExists distinguish an empty file from a missing side of a
+	// create/delete/move. Empty strings alone cannot encode that difference.
+	OldExists bool
+	NewExists bool
+	OldText   string
+	NewText   string
+}
+
+// boundedFileDiff declines rather than truncating: a truncated side would look
+// like an exact file replacement. Callers keep ChangedFiles as the safe
+// fallback for large, unsafe, or unchanged content. Each complete side gets the
+// same bound as a rendered preview; aggregate result producers apply their own
+// cap. Control bytes are rejected. Ordinary Unicode format/space characters are
+// retained unless removing them reveals a credential shape that the normal
+// redactor could not see in the original text.
+func boundedFileDiff(path, oldText, newText string, oldExists, newExists bool) (FileDiff, bool) {
+	if !filepath.IsAbs(path) || (!oldExists && !newExists) ||
+		(oldExists == newExists && oldText == newText) ||
+		!utf8.ValidString(oldText) || !utf8.ValidString(newText) ||
+		unsafeDiffText(oldText) || unsafeDiffText(newText) ||
+		len(oldText) > maxToolPreviewBytes || len(newText) > maxToolPreviewBytes {
+		return FileDiff{}, false
+	}
+	return FileDiff{Path: path, OldExists: oldExists, NewExists: newExists, OldText: oldText, NewText: newText}, true
+}
+
+func unsafeDiffText(text string) bool {
+	if !utf8.ValidString(text) {
+		return true
+	}
+	hasCanonicalizableSeparator := false
+	for _, r := range text {
+		switch r {
+		case '\n', '\r', '\t', ' ':
+			continue
+		}
+		if unicode.IsControl(r) {
+			return true
+		}
+		if isDiffCredentialIgnorable(r) {
+			hasCanonicalizableSeparator = true
+		}
+	}
+	if !hasCanonicalizableSeparator {
+		return false
+	}
+	return diffTextRevealsObfuscatedSecret(text)
+}
+
+func diffTextRevealsObfuscatedSecret(text string) bool {
+	if !utf8.ValidString(text) {
+		return false
+	}
+	canonical := strings.Map(func(r rune) rune {
+		switch r {
+		case '\n', '\r', '\t', ' ':
+			return r
+		}
+		if isDiffCredentialIgnorable(r) {
+			return -1
+		}
+		return r
+	}, text)
+	return canonical != text && redaction.RedactString(canonical, redaction.Options{}) != canonical
+}
+
+// isDiffCredentialIgnorable mirrors Unicode's Default_Ignorable_Code_Point
+// derived property using the tables exposed by the Go standard library. Cf
+// catches format controls, while the other two tables cover non-Cf default
+// ignorables such as U+034F COMBINING GRAPHEME JOINER and variation selectors.
+// Unicode whitespace is also removable because it can split a credential that
+// the boundary redactor would otherwise recognize. The caller preserves normal
+// ASCII layout whitespace before consulting this helper.
+func isDiffCredentialIgnorable(r rune) bool {
+	return unicode.Is(unicode.Cf, r) ||
+		unicode.Is(unicode.Other_Default_Ignorable_Code_Point, r) ||
+		unicode.Is(unicode.Variation_Selector, r) ||
+		unicode.IsSpace(r)
+}
+
 // boundedUnifiedDiff returns a unified diff of oldContent -> newContent labelled
 // with path, suitable for the TUI's diff card renderer. A create (oldContent "")
 // yields an all-additions (green) preview; an overwrite/edit yields red/green.
-// Returns "" when there is no change or the diff exceeds maxToolPreviewBytes.
+// Returns "" when there is no change, the rendered diff is unsafe text, or the
+// diff exceeds maxToolPreviewBytes. This applies the same unsafe-text gate as
+// FileDiff to what reaches Display.Preview, without discarding a safe hunk only
+// because an unrelated part of the source file contains an unsafe byte.
 func boundedUnifiedDiff(path, oldContent, newContent string) string {
 	diff := udiff.Unified(path, path, oldContent, newContent)
-	if diff == "" || len(diff) > maxToolPreviewBytes {
+	if diff == "" || !utf8.ValidString(diff) || unsafeDiffText(diff) || len(diff) > maxToolPreviewBytes {
 		return ""
 	}
 	return diff

internal/tools/diff_preview_test.go

@@ -0,0 +1,186 @@
+package tools
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestBoundedFileDiffRefusesPartialOrBinaryContent(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "a.txt")
+	if diff, ok := boundedFileDiff(path, "old", "new", true, true); !ok || diff.Path != path || !diff.OldExists || !diff.NewExists || diff.OldText != "old" || diff.NewText != "new" {
+		t.Fatalf("small text diff = %#v, %t", diff, ok)
+	}
+	for _, tc := range []struct {
+		name string
+		old  string
+		new  string
+	}{
+		{"unchanged", "same", "same"},
+		{"binary old", string([]byte{0xff}), "text"},
+		{"binary new", "text", string([]byte{0xff})},
+		{"nul old", "token=sk-proj-abc\x00def", "text"},
+		{"escape new", "text", "token=sk-proj-abc\x1bdef"},
+		{"c1 old", "token=sk-proj-abc\u0085def", "text"},
+		{"zero width space", "token=sk-proj-abc\u200bdef", "text"},
+		{"zero width joiner", "token=sk-proj-abc\u200ddef", "text"},
+		{"byte order mark", "token=sk-proj-abc\ufeffdef", "text"},
+		{"soft hyphen", "token=sk-proj-abc\u00addef", "text"},
+		{"non breaking space", "token=sk-proj-abc\u00a0def", "text"},
+		{"too large", strings.Repeat("a", maxToolPreviewBytes+1), "b"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if diff, ok := boundedFileDiff(path, tc.old, tc.new, true, true); ok || diff != (FileDiff{}) {
+				t.Fatalf("unexpected diff = %#v, %t", diff, ok)
+			}
+		})
+	}
+}
+
+func TestBoundedFileDiffPreservesEmptyFileOperations(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "empty.txt")
+	for _, tc := range []struct {
+		name                 string
+		oldExists, newExists bool
+	}{
+		{name: "create", newExists: true},
+		{name: "delete", oldExists: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			diff, ok := boundedFileDiff(path, "", "", tc.oldExists, tc.newExists)
+			if !ok || diff.OldExists != tc.oldExists || diff.NewExists != tc.newExists {
+				t.Fatalf("empty %s = %#v, %t", tc.name, diff, ok)
+			}
+		})
+	}
+}
+
+func TestBoundedUnifiedDiffRejectsUnsafeRichText(t *testing.T) {
+	if got := boundedUnifiedDiff("safe.txt", "before\n", "after\n"); got == "" {
+		t.Fatal("safe unified diff was unexpectedly omitted")
+	}
+	for _, content := range []string{
+		"token=sk-proj-abc\x00def",
+		"token=sk-proj-abc\x1bdef",
+		"token=sk-proj-abc\u200bdef",
+		string([]byte{0xff}),
+	} {
+		if got := boundedUnifiedDiff("secret.txt", content, "safe\n"); got != "" {
+			t.Fatalf("unsafe rich diff = %q", got)
+		}
+	}
+
+	old := strings.Repeat("unchanged\n", 12) + "form\ffeed\n" + strings.Repeat("unchanged\n", 12)
+	updated := strings.Replace(old, "unchanged\n", "changed\n", 1)
+	if got := boundedUnifiedDiff("safe-hunk.txt", old, updated); got == "" || strings.Contains(got, "\f") {
+		t.Fatalf("safe hunk near unrelated unsafe text = %q", got)
+	}
+}
+
+func TestStructuredPatchFileDiffsPreserveEmptyOperationsAndResultBudget(t *testing.T) {
+	root, err := filepath.EvalSymlinks(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	changes := []structuredPatchChange{
+		{kind: structuredPatchAdd, to: structuredPatchTarget{absolute: filepath.Join(root, "created"), relative: "created"}},
+		{kind: structuredPatchDelete, from: structuredPatchTarget{absolute: filepath.Join(root, "deleted"), relative: "deleted"}},
+		{kind: structuredPatchUpdate, from: structuredPatchTarget{absolute: filepath.Join(root, "from"), relative: "from"}, to: structuredPatchTarget{absolute: filepath.Join(root, "to"), relative: "to"}},
+	}
+	diffs := fileDiffsFromStructuredPatch(".", changes)
+	if len(diffs) != 4 {
+		t.Fatalf("empty create/delete/move diffs = %#v", diffs)
+	}
+	for _, diff := range diffs {
+		if diff.Path == "" || (!diff.OldExists && !diff.NewExists) {
+			t.Fatalf("invalid diff = %#v", diff)
+		}
+	}
+
+	large := strings.Repeat("x", maxToolResultFileDiffBytes/3+1)
+	budgeted := fileDiffsFromStructuredPatch(".", []structuredPatchChange{
+		{kind: structuredPatchAdd, to: structuredPatchTarget{absolute: filepath.Join(root, "one")}, after: large},
+		{kind: structuredPatchAdd, to: structuredPatchTarget{absolute: filepath.Join(root, "two")}, after: "tiny"},
+		{kind: structuredPatchAdd, to: structuredPatchTarget{absolute: filepath.Join(root, "three")}, after: large},
+		{kind: structuredPatchAdd, to: structuredPatchTarget{absolute: filepath.Join(root, "four")}, after: large},
+	})
+	if len(budgeted) != 3 || filepath.Base(budgeted[0].Path) != "one" || filepath.Base(budgeted[1].Path) != "two" || filepath.Base(budgeted[2].Path) != "three" {
+		t.Fatalf("ordered aggregate file-diff budget = %#v", budgeted)
+	}
+}
+
+func TestStructuredPatchFileDiffsKeepEligibleSameBasenameSibling(t *testing.T) {
+	root, err := filepath.EvalSymlinks(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	diffs := fileDiffsFromStructuredPatch(".", []structuredPatchChange{
+		{
+			kind:  structuredPatchAdd,
+			to:    structuredPatchTarget{absolute: filepath.Join(root, "a.go"), relative: "a.go"},
+			after: strings.Repeat("x", maxToolPreviewBytes+1),
+		},
+		{
+			kind:  structuredPatchAdd,
+			to:    structuredPatchTarget{absolute: filepath.Join(root, "sub", "a.go"), relative: filepath.Join("sub", "a.go")},
+			after: "package sub\n",
+		},
+	})
+	if len(diffs) != 1 || diffs[0].Path != filepath.Join(root, "sub", "a.go") {
+		t.Fatalf("same-basename rich diffs = %#v", diffs)
+	}
+}
+
+func TestBoundedDiffPreservesOrdinaryUnicodeButRejectsObfuscatedSecrets(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "unicode.txt")
+	for name, content := range map[string]string{
+		"family emoji":              "family: 👨‍👩‍👧‍👦\n",
+		"emoji variation selector":  "heart: ❤️\n",
+		"combining grapheme joiner": "ordinary\u034fprose\n",
+		"nonbreaking space":         "ordinary\u00a0prose\n",
+		"byte order mark":           "\ufeffdocument\n",
+		"soft hyphen":               "co\u00adoperate\n",
+	} {
+		t.Run(name, func(t *testing.T) {
+			if _, ok := boundedFileDiff(path, "before\n", content, true, true); !ok {
+				t.Fatalf("ordinary Unicode content was rejected: %q", content)
+			}
+			if preview := boundedUnifiedDiff("unicode.txt", "before\n", content); preview == "" {
+				t.Fatal("ordinary Unicode preview was omitted")
+			}
+		})
+	}
+
+	secret := "sk-ant-api03-AAAABBBBCCCCDDDDEEEEFFFFGGGG"
+	for name, separator := range map[string]string{
+		"zero width space":          "\u200b",
+		"zero width joiner":         "\u200d",
+		"byte order mark":           "\ufeff",
+		"soft hyphen":               "\u00ad",
+		"nonbreaking space":         "\u00a0",
+		"combining grapheme joiner": "\u034f",
+		"variation selector":        "\ufe0f",
+	} {
+		t.Run("split "+name, func(t *testing.T) {
+			obfuscated := secret[:20] + separator + secret[20:]
+			if _, ok := boundedFileDiff(path, "before\n", obfuscated, true, true); ok {
+				t.Fatalf("obfuscated credential produced a rich diff: %q", obfuscated)
+			}
+			if preview := boundedUnifiedDiff("secret.txt", "before\n", obfuscated); preview != "" {
+				t.Fatalf("obfuscated credential produced preview: %q", preview)
+			}
+		})
+	}
+}
+
+func TestWriteFileMarksSuppressedObfuscatedSecretAsRedacted(t *testing.T) {
+	root := t.TempDir()
+	secret := "sk-ant-api03-AAAABBBBCCCCDDDDEEEEFFFFGGGG"
+	obfuscated := secret[:20] + "\u200b" + secret[20:]
+	result := NewScopedWriteFileTool(root, nil).Run(t.Context(), map[string]any{
+		"path": "secret.txt", "content": obfuscated,
+	})
+	if result.Status != StatusOK || len(result.ChangedFiles) != 1 || len(result.FileDiffs) != 0 || !result.Redacted {
+		t.Fatalf("obfuscated-secret result = status=%s changed=%#v diffs=%#v redacted=%t", result.Status, result.ChangedFiles, result.FileDiffs, result.Redacted)
+	}
+}

internal/tools/edit_file.go

@@ -80,6 +80,10 @@ func (tool editFileTool) RunWithOptions(ctx context.Context, args map[string]any
 		}
 	}
 	content := string(contentBytes)
+	priorInfo, err := os.Stat(absolutePath)
+	if err != nil {
+		return errorResult("Error reading " + relativePath + ": " + err.Error())
+	}
 	occurrences := strings.Count(content, oldString)
 
 	// CRLF fallback: read_file normalizes \r\n → \n before presenting content to
@@ -153,19 +157,25 @@ func (tool editFileTool) RunWithOptions(ctx context.Context, args map[string]any
 	if err := recheckScopedWriteTarget(tool.workspaceRoot, tool.scope, requestedPath); err != nil {
 		return errorResult("Error writing " + relativePath + ": " + err.Error())
 	}
-	if err := os.WriteFile(absolutePath, []byte(updated), 0o644); err != nil {
+	if err := commitFileContents(absolutePath, priorInfo, &content, updated); err != nil {
 		return errorResult("Error writing " + relativePath + ": " + err.Error())
 	}
 	modelKnownContent := updated
 	// Optional format-on-write (ZERO_FORMAT_ON_WRITE). Must run BEFORE the
 	// FileTracker re-baseline: recording pre-format content would make the very
 	// next edit look like an external modification and trip the conflict guard.
-	formatting := maybeFormatWrittenFile(ctx, absolutePath, updated)
+	formatting := maybeFormatWrittenFileScoped(ctx, tool.workspaceRoot, tool.scope, absolutePath, updated, priorInfo.Mode().Perm())
 	updated = formatting.Content
+	finalContentKnown := formatting.ContentKnown
 	// Re-baseline to the content we just wrote so subsequent edits in this session
 	// compare against the current on-disk state, not the pre-edit version.
-	newInfo, _ := os.Stat(absolutePath)
-	if updated == modelKnownContent {
+	newInfo := formatting.Info
+	if newInfo == nil {
+		newInfo, _ = os.Stat(absolutePath)
+	}
+	if !finalContentKnown {
+		options.FileTracker.Forget(absolutePath)
+	} else if updated == modelKnownContent {
 		// OUR edit, so we know precisely which lines moved: RecordEdit carries
 		// across the reads this edit did not disturb instead of dropping them.
 		//
@@ -195,12 +205,25 @@ func (tool editFileTool) RunWithOptions(ctx context.Context, args map[string]any
 	}
 	summary := fmt.Sprintf("Successfully edited %s (replaced %d occurrence%s).", relativePath, replacedCount, suffix)
 	summary += formatting.notice(relativePath)
-	summary += inlineDiagnostics(ctx, options, absolutePath, relativePath)
+	if finalContentKnown {
+		summary += inlineDiagnostics(ctx, options, absolutePath, relativePath)
+	}
 	result := okResult(summary)
 	result.ChangedFiles = []string{relativePath}
+	if finalContentKnown {
+		if diff, ok := boundedFileDiff(absolutePath, content, updated, true, true); ok {
+			result.FileDiffs = []FileDiff{diff}
+		} else if diffTextRevealsObfuscatedSecret(content) || diffTextRevealsObfuscatedSecret(updated) {
+			result.Redacted = true
+		}
+	}
 	// Card-only preview (Display.Preview): the model's Output stays the one-line
 	// summary, so the red/green diff costs zero model tokens.
-	result.Display = Display{Summary: fmt.Sprintf("Edited %s", relativePath), Kind: "diff", Preview: boundedUnifiedDiff(relativePath, content, updated)}
+	preview := ""
+	if finalContentKnown {
+		preview = boundedUnifiedDiff(relativePath, content, updated)
+	}
+	result.Display = Display{Summary: fmt.Sprintf("Edited %s", relativePath), Kind: "diff", Preview: preview}
 	return result
 }
 

internal/tools/exec_command.go

@@ -47,8 +47,11 @@ type ExecSessionSnapshot = execution.ProcessSnapshot
 
 type ExecSessionController interface {
 	ExecSessions() []ExecSessionSnapshot
+	ExecSession(id int) (ExecSessionSnapshot, bool)
 	StopExecSession(id int) bool
 	StopAllExecSessions() []int
+	WriteExecSessionInput(id int, data []byte) error
+	ResizeExecSession(id int, cols, rows int) error
 }
 
 type execCommandTool struct {
@@ -95,7 +98,7 @@ func NewScopedExecCommandTool(workspaceRoot string, scope PathScope, manager *ex
 					},
 					"justification": {Type: "string", Description: "User-facing approval question for `require_escalated`; omit otherwise."},
 					"prefix_rule":   {Type: "array", Items: &PropertySchema{Type: "string"}, Description: "Reusable approval prefix for this command, only with `sandbox_permissions: \"require_escalated\"`; keep it narrow, for example [\"git\", \"pull\"]."},
-					"tty":           {Type: "boolean", Description: "True allocates a PTY for the command; false or omitted uses plain pipes.", Default: false},
+					"tty":           {Type: "boolean", Description: "True allocates a PTY for the command; false or omitted uses plain pipes. Use true for commands that may prompt for input (sudo, ssh, interactive installers): the user can then type into the session directly. Setuid tools such as sudo also need sandbox_permissions \"require_escalated\", since the sandbox blocks privilege escalation.", Default: false},
 				},
 				Required:             []string{"cmd"},
 				AdditionalProperties: false,
@@ -131,6 +134,10 @@ func (tool execCommandTool) ExecSessions() []ExecSessionSnapshot {
 	return tool.manager.List()
 }
 
+func (tool execCommandTool) ExecSession(id int) (ExecSessionSnapshot, bool) {
+	return tool.manager.Snapshot(id)
+}
+
 func (tool execCommandTool) StopExecSession(id int) bool {
 	return tool.manager.Stop(id)
 }
@@ -139,6 +146,14 @@ func (tool execCommandTool) StopAllExecSessions() []int {
 	return tool.manager.StopAll()
 }
 
+func (tool execCommandTool) WriteExecSessionInput(id int, data []byte) error {
+	return tool.manager.WriteInput(id, data)
+}
+
+func (tool execCommandTool) ResizeExecSession(id int, cols, rows int) error {
+	return tool.manager.ResizeInput(id, cols, rows)
+}
+
 func (tool execCommandTool) run(ctx context.Context, args map[string]any, engine *zeroSandbox.Engine, directBudget bool) Result {
 	commandText, err := execCommandArg(args)
 	if err != nil {
@@ -172,8 +187,14 @@ func (tool execCommandTool) run(ctx context.Context, args map[string]any, engine
 	if issue := detectShellCommandIssueForRuntime(commandText, detectShellRuntime(runtimeGOOS())); issue != nil && !msysGuardBypassed(issue, commandEngine) {
 		return shellIssueBlockResult(*issue)
 	}
-	if interactive := zeroSandbox.DetectInteractiveCommand(commandText, runtimeGOOS()); interactive.Interactive {
-		return interactiveBlockResult(interactive)
+	// tty:true exists exactly to run prompting commands, so the
+	// non-interactive guard steps aside and the PTY path gets the session.
+	if !ttyRequested {
+		if interactive := zeroSandbox.DetectInteractiveCommand(commandText, runtimeGOOS()); interactive.Interactive {
+			result := interactiveBlockResult(interactive)
+			result.Output += "\nRerun with tty:true if the user should interact with it."
+			return result
+		}
 	}
 	absoluteCwd, relativeCwd, err := resolveScopedPath(tool.workspaceRoot, tool.scope, workdir)
 	if err != nil {
@@ -453,7 +474,7 @@ func execToolResultWithBudget(input execToolResultInput, directBudget bool) Resu
 	if input.exited && input.exitCode != 0 && !input.interrupted {
 		status = StatusError
 	}
-	body := formatExecCommandOutput(output, input.sessionID, input.exited, input.exitCode, input.interrupted)
+	body := formatExecCommandOutput(output, input.sessionID, input.exited, input.exitCode, input.interrupted, input.tty)
 	if status == StatusError && input.exited && !input.interrupted {
 		if issue := detectShellOutputIssueForRuntime(output, detectShellRuntime(runtimeGOOS())); issue != nil {
 			meta["shell_issue"] = issue.Kind
@@ -575,7 +596,7 @@ func executionChangeSummaries(changes []execution.Change) []execution.Change {
 	return summaries
 }
 
-func formatExecCommandOutput(output string, sessionID int, exited bool, exitCode int, interrupted bool) string {
+func formatExecCommandOutput(output string, sessionID int, exited bool, exitCode int, interrupted bool, tty bool) string {
 	output = strings.TrimRight(output, "\r\n")
 	parts := []string{}
 	if output != "" {
@@ -593,12 +614,18 @@ func formatExecCommandOutput(output string, sessionID int, exited bool, exitCode
 			parts = append(parts, "interrupted: true")
 		}
 		parts = append(parts, fmt.Sprintf("exit_code: %d", exitCode))
+		if exitCode != 0 && strings.Contains(output, "no new privileges") {
+			parts = append(parts, `Hint: this command needs sandbox_permissions "require_escalated" (the sandbox blocks setuid); retry with it and tty:true if it prompts.`)
+		}
 	} else {
 		if output == "" {
 			parts = append(parts, "Command is still running.")
 		}
 		parts = append(parts, fmt.Sprintf("session_id: %d", sessionID))
 		parts = append(parts, fmt.Sprintf("Use write_stdin with session_id %d and empty chars to poll; send chars \"\\u0003\" to interrupt/stop it.", sessionID))
+		if tty {
+			parts = append(parts, fmt.Sprintf("This session has a terminal and the user can already type into it (it opened in their TUI; /attach %d reopens it). If it is waiting on a password or confirmation, say so in one line, then keep polling with write_stdin (empty chars, yield_time_ms 60000) until it exits. Do not end your turn while it is running, and never ask for the password in chat.", sessionID))
+		}
 	}
 	return strings.Join(parts, "\n")
 }

internal/tools/exec_command_test.go

@@ -894,3 +894,56 @@ func TestTruncateExecOutputPreservesUTF8(t *testing.T) {
 		t.Fatalf("truncated output is not valid UTF-8: %q", truncated)
 	}
 }
+
+func TestFormatExecCommandOutputTTYAttachHint(t *testing.T) {
+	running := formatExecCommandOutput("", 1007, false, 0, false, true)
+	if !strings.Contains(running, "/attach 1007 reopens it") || !strings.Contains(running, "Do not end your turn while it is running") {
+		t.Fatalf("tty running session should point at /attach and keep-poll guidance: %q", running)
+	}
+	exited := formatExecCommandOutput("", 1007, true, 0, false, true)
+	if strings.Contains(exited, "/attach") {
+		t.Fatalf("exited session should not mention /attach: %q", exited)
+	}
+	pipes := formatExecCommandOutput("", 1007, false, 0, false, false)
+	if strings.Contains(pipes, "/attach") {
+		t.Fatalf("non-tty session should not mention /attach: %q", pipes)
+	}
+}
+
+func TestExecCommandInteractiveBlockSuggestsTTY(t *testing.T) {
+	tool := NewScopedExecCommandTool(t.TempDir(), nil, newExecSessionManager())
+	result := tool.Run(context.Background(), map[string]any{"cmd": "ssh host.example.com"})
+	if result.Status != StatusError || result.Meta["safety_block"] != "interactive_command" {
+		t.Fatalf("expected interactive safety block, got meta=%#v output=%q", result.Meta, result.Output)
+	}
+	if !strings.Contains(result.Output, "tty:true") {
+		t.Fatalf("block output should suggest tty:true: %q", result.Output)
+	}
+}
+
+func TestExecCommandTTYSkipsInteractiveBlock(t *testing.T) {
+	tool := NewScopedExecCommandTool(t.TempDir(), nil, newExecSessionManager())
+	// ssh to a bogus host fails fast on its own; the point is that the
+	// interactive guard must not fire ahead of the tty path.
+	result := tool.Run(context.Background(), map[string]any{
+		"cmd": "ssh host.example.com", "tty": true, "yield_time_ms": 250,
+	})
+	if result.Meta["safety_block"] == "interactive_command" {
+		t.Fatalf("tty:true should not hit the interactive block: %#v", result.Meta)
+	}
+}
+
+func TestFormatExecCommandOutputNoNewPrivilegesHint(t *testing.T) {
+	blocked := formatExecCommandOutput(`sudo: The "no new privileges" flag is set`, 1007, true, 1, false, true)
+	if !strings.Contains(blocked, `sandbox_permissions "require_escalated"`) {
+		t.Fatalf("no_new_privs failure should hint at require_escalated: %q", blocked)
+	}
+	normal := formatExecCommandOutput("some other error", 1007, true, 1, false, true)
+	if strings.Contains(normal, "require_escalated") {
+		t.Fatalf("unrelated failure should not hint at require_escalated: %q", normal)
+	}
+	blockedOK := formatExecCommandOutput(`sudo: The "no new privileges" flag is set`, 1007, true, 0, false, true)
+	if strings.Contains(blockedOK, "require_escalated") {
+		t.Fatalf("zero-exit output should not hint at require_escalated: %q", blockedOK)
+	}
+}

internal/tools/file_commit.go

@@ -0,0 +1,108 @@
+package tools
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"os"
+)
+
+var errFileChangedDuringWrite = errors.New("file changed on disk before the write committed")
+
+// fileWriteBeforeCommit is a deterministic test hook. Production leaves it
+// nil; tests use it to replace a path after observation but before opening the
+// object that will actually be mutated.
+var fileWriteBeforeCommit func(path string)
+
+// fileWriteStat is a deterministic test seam for proving that the opened-file
+// identity is captured before the final preimage comparison. Production uses
+// the file descriptor directly.
+var fileWriteStat = func(file *os.File) (os.FileInfo, error) { return file.Stat() }
+
+// commitFileContents binds an overwrite to the file identity and bytes that
+// the caller observed. A create uses exclusive creation. An overwrite opens the
+// observed object without truncation, verifies identity/content through that
+// handle, then truncates and writes the same handle. A path replacement before
+// or during commit therefore fails instead of publishing stale rich evidence.
+//
+// expectedInfo nil means the caller observed a missing path. expectedContent
+// may be nil for an existing but unreadable file; that path may still be
+// overwritten, but callers must omit rich before/after evidence.
+func commitFileContents(path string, expectedInfo os.FileInfo, expectedContent *string, content string) error {
+	if fileWriteBeforeCommit != nil {
+		fileWriteBeforeCommit(path)
+	}
+
+	if expectedInfo == nil {
+		file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
+		if err != nil {
+			return err
+		}
+		openedInfo, err := fileWriteStat(file)
+		if err != nil {
+			_ = file.Close()
+			return err
+		}
+		return writeAndVerifyFileIdentity(path, file, openedInfo, content, false)
+	}
+
+	flags := os.O_WRONLY
+	if expectedContent != nil {
+		flags = os.O_RDWR
+	}
+	file, err := os.OpenFile(path, flags, 0)
+	if err != nil {
+		return err
+	}
+	openedInfo, err := fileWriteStat(file)
+	if err != nil {
+		_ = file.Close()
+		return err
+	}
+	if !os.SameFile(expectedInfo, openedInfo) {
+		_ = file.Close()
+		return errFileChangedDuringWrite
+	}
+	pathInfo, err := os.Stat(path)
+	if err != nil || !os.SameFile(openedInfo, pathInfo) {
+		_ = file.Close()
+		return errFileChangedDuringWrite
+	}
+	if expectedContent != nil {
+		current, readErr := io.ReadAll(file)
+		if readErr != nil {
+			_ = file.Close()
+			return readErr
+		}
+		if string(current) != *expectedContent {
+			_ = file.Close()
+			return errFileChangedDuringWrite
+		}
+	}
+	return writeAndVerifyFileIdentity(path, file, openedInfo, content, true)
+}
+
+func writeAndVerifyFileIdentity(path string, file *os.File, openedInfo os.FileInfo, content string, truncate bool) error {
+	if truncate {
+		if err := file.Truncate(0); err != nil {
+			_ = file.Close()
+			return err
+		}
+		if _, err := file.Seek(0, io.SeekStart); err != nil {
+			_ = file.Close()
+			return err
+		}
+	}
+	if _, err := io.WriteString(file, content); err != nil {
+		_ = file.Close()
+		return err
+	}
+	if err := file.Close(); err != nil {
+		return err
+	}
+	pathInfo, err := os.Stat(path)
+	if err != nil || !os.SameFile(openedInfo, pathInfo) {
+		return fmt.Errorf("%w: path identity changed", errFileChangedDuringWrite)
+	}
+	return nil
+}

internal/tools/file_commit_test.go

@@ -0,0 +1,131 @@
+package tools
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func installFileWriteRace(t *testing.T, mutate func(string)) {
+	t.Helper()
+	prior := fileWriteBeforeCommit
+	fileWriteBeforeCommit = mutate
+	t.Cleanup(func() { fileWriteBeforeCommit = prior })
+}
+
+func installFileWriteStat(t *testing.T, stat func(*os.File) (os.FileInfo, error)) {
+	t.Helper()
+	prior := fileWriteStat
+	fileWriteStat = stat
+	t.Cleanup(func() { fileWriteStat = prior })
+}
+
+func TestWriteFileRefusesCreateAndOverwriteRaces(t *testing.T) {
+	t.Run("create", func(t *testing.T) {
+		root := t.TempDir()
+		target := filepath.Join(root, "created.txt")
+		installFileWriteRace(t, func(path string) {
+			if err := os.WriteFile(path, []byte("other writer\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+		})
+		result := NewScopedWriteFileTool(root, nil).Run(context.Background(), map[string]any{
+			"path": "created.txt", "content": "zero\n",
+		})
+		if result.Status != StatusError {
+			t.Fatalf("raced create status = %s, want error", result.Status)
+		}
+		if got, err := os.ReadFile(target); err != nil || string(got) != "other writer\n" {
+			t.Fatalf("raced create content = %q, err=%v", got, err)
+		}
+	})
+
+	t.Run("overwrite", func(t *testing.T) {
+		root := t.TempDir()
+		target := filepath.Join(root, "existing.txt")
+		if err := os.WriteFile(target, []byte("observed\n"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		installFileWriteRace(t, func(path string) {
+			if err := os.WriteFile(path, []byte("other writer\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+		})
+		result := NewScopedWriteFileTool(root, nil).Run(context.Background(), map[string]any{
+			"path": "existing.txt", "content": "zero\n", "overwrite": true,
+		})
+		if result.Status != StatusError || !strings.Contains(result.Output, errFileChangedDuringWrite.Error()) {
+			t.Fatalf("raced overwrite = %s: %s", result.Status, result.Output)
+		}
+		if got, err := os.ReadFile(target); err != nil || string(got) != "other writer\n" {
+			t.Fatalf("raced overwrite content = %q, err=%v", got, err)
+		}
+	})
+}
+
+func TestEditFileRefusesPreimageRace(t *testing.T) {
+	root := t.TempDir()
+	target := filepath.Join(root, "existing.txt")
+	if err := os.WriteFile(target, []byte("observed\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	installFileWriteRace(t, func(path string) {
+		if err := os.WriteFile(path, []byte("other writer\n"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	})
+	result := NewScopedEditFileTool(root, nil).Run(context.Background(), map[string]any{
+		"path": "existing.txt", "old_string": "observed", "new_string": "zero",
+	})
+	if result.Status != StatusError || !strings.Contains(result.Output, errFileChangedDuringWrite.Error()) {
+		t.Fatalf("raced edit = %s: %s", result.Status, result.Output)
+	}
+	if got, err := os.ReadFile(target); err != nil || string(got) != "other writer\n" {
+		t.Fatalf("raced edit content = %q, err=%v", got, err)
+	}
+}
+
+func TestOverwriteDoesNotStatOpenedFileAfterFinalPreimageComparison(t *testing.T) {
+	for name, run := range map[string]func(string) Result{
+		"write overwrite": func(root string) Result {
+			return NewScopedWriteFileTool(root, nil).Run(context.Background(), map[string]any{
+				"path": "existing.txt", "content": "zero\n", "overwrite": true,
+			})
+		},
+		"edit": func(root string) Result {
+			return NewScopedEditFileTool(root, nil).Run(context.Background(), map[string]any{
+				"path": "existing.txt", "old_string": "observed", "new_string": "zero",
+			})
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			root := t.TempDir()
+			target := filepath.Join(root, "existing.txt")
+			if err := os.WriteFile(target, []byte("observed\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+
+			statCalls := 0
+			installFileWriteStat(t, func(file *os.File) (os.FileInfo, error) {
+				statCalls++
+				if statCalls == 2 {
+					// This preserves the inode, so identity-only checks cannot detect it.
+					if err := os.WriteFile(target, []byte("other writer\n"), 0o644); err != nil {
+						t.Fatal(err)
+					}
+				}
+				return file.Stat()
+			})
+
+			result := run(root)
+			if result.Status != StatusOK {
+				t.Fatalf("overwrite status = %s: %s", result.Status, result.Output)
+			}
+			if statCalls != 1 {
+				t.Fatalf("opened file was statted %d times; the final byte comparison must be followed directly by mutation", statCalls)
+			}
+		})
+	}
+}

internal/tools/format_on_write.go

@@ -3,11 +3,15 @@ package tools
 import (
 	"context"
 	"errors"
+	"fmt"
+	"io"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"strings"
 	"time"
+
+	"github.com/Gitlawb/zero/internal/sandbox"
 )
 
 // Format-on-write for the mutating file tools. When enabled, a successful
@@ -44,7 +48,9 @@ var formatOnWriteTimeout = 10 * time.Second
 // and finds out from a CI format check it cannot see, which is the thing this
 // feature exists to prevent.
 type formatOnWriteResult struct {
-	Content string
+	Content      string
+	ContentKnown bool
+	Info         os.FileInfo
 	// Formatter is the binary that was run, named in the notice so the user can
 	// tell a slow gofmt from a slow prettier.
 	Formatter string
@@ -117,14 +123,32 @@ func formatOnWriteEnabled() bool {
 	return value != "" && value != "0" && !strings.EqualFold(value, "false")
 }
 
-// maybeFormatWrittenFile runs the configured formatter for absolutePath (when
-// enabled and on PATH) and returns the file's content afterwards. Best-effort
-// throughout: any failure — no formatter, formatter error, timeout, unreadable
-// result — returns writtenContent so the caller's state matches the last write
-// it performed itself. Only the timeout is reported back, for the reason on
-// formatOnWriteResult.
+var runFormatOnWriteCommand = func(ctx context.Context, binaryPath string, arguments []string, directory string) error {
+	formatter := exec.CommandContext(ctx, binaryPath, arguments...)
+	formatter.Dir = directory
+	formatter.Stdin = strings.NewReader("")
+	return formatter.Run()
+}
+
+var readFormattedFile = readRootedFile
+
+// maybeFormatWrittenFile is the unscoped test-facing wrapper. Production
+// callers use maybeFormatWrittenFileScoped so a formatter cannot redirect the
+// final read or recovery write outside the configured write roots.
 func maybeFormatWrittenFile(ctx context.Context, absolutePath string, writtenContent string) formatOnWriteResult {
-	unformatted := formatOnWriteResult{Content: writtenContent}
+	restoreMode := os.FileMode(0o644)
+	if info, err := os.Stat(absolutePath); err == nil {
+		restoreMode = info.Mode().Perm()
+	}
+	return maybeFormatWrittenFileScoped(ctx, filepath.Dir(absolutePath), nil, absolutePath, writtenContent, restoreMode)
+}
+
+// maybeFormatWrittenFileScoped runs the configured formatter and returns only
+// content verified through a descriptor-bound root. Formatter failures restore
+// writtenContent through that same root; if restoration or the final read
+// fails, ContentKnown is false and callers omit exact diff evidence.
+func maybeFormatWrittenFileScoped(ctx context.Context, workspaceRoot string, scope PathScope, absolutePath string, writtenContent string, restoreMode os.FileMode) formatOnWriteResult {
+	unformatted := formatOnWriteResult{Content: writtenContent, ContentKnown: true}
 	if !formatOnWriteEnabled() {
 		return unformatted
 	}
@@ -136,42 +160,90 @@ func maybeFormatWrittenFile(ctx context.Context, absolutePath string, writtenCon
 	if err != nil {
 		return unformatted
 	}
+	root, relativePath, err := openFormattedFileRoot(workspaceRoot, scope, absolutePath)
+	if err != nil {
+		unformatted.ContentKnown = false
+		return unformatted
+	}
+	defer root.Close()
+
 	formatCtx, cancel := context.WithTimeout(ctx, formatOnWriteTimeout)
 	defer cancel()
 	arguments := append(append([]string(nil), command[1:]...), absolutePath)
-	formatter := exec.CommandContext(formatCtx, binaryPath, arguments...)
-	formatter.Dir = filepath.Dir(absolutePath)
-	formatter.Stdin = strings.NewReader("")
-	if err := formatter.Run(); err != nil {
+	if err := runFormatOnWriteCommand(formatCtx, binaryPath, arguments, filepath.Dir(absolutePath)); err != nil {
 		unformatted.Formatter = command[0]
-		// THE FORMATTER EDITS IN PLACE, SO A FAILED RUN CAN LEAVE THE FILE
-		// NEITHER FORMATTED NOR AS WRITTEN. Killed by the deadline or by the
-		// caller, or exiting partway through its own rewrite, the target can hold
-		// a truncation. Returning the written bytes on top of that would leave the
-		// tracker baseline and the diff preview describing a file that is not on
-		// disk, which is a worse failure than the missing formatting: the next
-		// edit compares against content the file does not have.
-		//
-		// Written back unconditionally on this path rather than only when the
-		// bytes differ. Comparing first means reading the file to find out, and a
-		// read that fails leaves the same ambiguity this exists to remove.
-		if restoreErr := os.WriteFile(absolutePath, []byte(writtenContent), 0o644); restoreErr != nil {
+		if restoreErr := restoreFormattedFile(root, relativePath, writtenContent, restoreMode); restoreErr != nil {
 			unformatted.RestoreFailed = true
+			unformatted.ContentKnown = false
+		} else if restored, info, readErr := readFormattedFile(root, relativePath); readErr != nil {
+			unformatted.ContentKnown = false
+		} else {
+			unformatted.Content = string(restored)
+			unformatted.Info = info
 		}
-		// OUR deadline, not the caller's cancellation and not the formatter's own
-		// exit status. A cancelled tool call is already being reported as
-		// cancelled, and a formatter that ran and refused the file usually means
-		// content it could not parse, which the write itself does not promise to
-		// fix. Neither is this notice's business; the restore above is, for all
-		// three.
 		if errors.Is(formatCtx.Err(), context.DeadlineExceeded) && ctx.Err() == nil {
 			unformatted.TimedOut = true
 		}
 		return unformatted
 	}
-	formatted, err := os.ReadFile(absolutePath)
+
+	formatted, info, err := readFormattedFile(root, relativePath)
 	if err != nil {
+		unformatted.ContentKnown = false
 		return unformatted
 	}
-	return formatOnWriteResult{Content: string(formatted), Formatter: command[0]}
+	return formatOnWriteResult{Content: string(formatted), ContentKnown: true, Info: info, Formatter: command[0]}
+}
+
+func restoreFormattedFile(root *os.Root, relativePath string, content string, mode os.FileMode) error {
+	file, err := root.OpenFile(relativePath, os.O_WRONLY|os.O_TRUNC|os.O_CREATE, mode)
+	if err != nil {
+		return err
+	}
+	if _, err := io.WriteString(file, content); err != nil {
+		_ = file.Close()
+		return err
+	}
+	return file.Close()
+}
+
+// openFormattedFileRoot opens the write root before the formatter runs and
+// computes the target relative to that descriptor-bound root. Atomic in-root
+// replacement remains valid; a formatter that swaps the target to an escaping
+// symlink is rejected when readFormattedFile opens it through the root.
+func openFormattedFileRoot(workspaceRoot string, scope PathScope, absolutePath string) (*os.Root, string, error) {
+	roots, err := scopedRoots(workspaceRoot, scope)
+	if err != nil {
+		return nil, "", err
+	}
+	var firstErr error
+	for _, configuredRoot := range roots {
+		resolvedRoot, err := filepath.Abs(configuredRoot)
+		if err == nil {
+			resolvedRoot, err = filepath.EvalSymlinks(resolvedRoot)
+		}
+		if err != nil {
+			if firstErr == nil {
+				firstErr = err
+			}
+			continue
+		}
+		candidate := sandbox.NormalizePrefixForRoot(absolutePath, resolvedRoot)
+		relativePath, err := filepath.Rel(resolvedRoot, candidate)
+		if err != nil || relativePath == ".." || strings.HasPrefix(relativePath, ".."+string(filepath.Separator)) || filepath.IsAbs(relativePath) {
+			continue
+		}
+		root, err := os.OpenRoot(resolvedRoot)
+		if err != nil {
+			if firstErr == nil {
+				firstErr = err
+			}
+			continue
+		}
+		return root, relativePath, nil
+	}
+	if firstErr != nil {
+		return nil, "", firstErr
+	}
+	return nil, "", fmt.Errorf("%s must stay inside the configured write roots", absolutePath)
 }

internal/tools/format_on_write_test.go

@@ -5,6 +5,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 )
@@ -98,7 +99,7 @@ func TestFormatOnWriteFormatsAndKeepsTrackerConsistent(t *testing.T) {
 func TestFormatOnWriteSkipsUnknownExtensions(t *testing.T) {
 	t.Setenv("ZERO_FORMAT_ON_WRITE", "1")
 	formatting := maybeFormatWrittenFile(context.Background(), filepath.Join(t.TempDir(), "notes.xyz"), "raw   text")
-	if formatting.Content != "raw   text" {
+	if formatting.Content != "raw   text" || !formatting.ContentKnown {
 		t.Fatalf("unknown extension must pass through: %q", formatting.Content)
 	}
 	if notice := formatting.notice("notes.xyz"); notice != "" {
@@ -115,10 +116,418 @@ func TestFormatOnWriteFormatterLookupFailure(t *testing.T) {
 		t.Fatal(err)
 	}
 	formatting := maybeFormatWrittenFile(context.Background(), targetPath, uglyContent)
-	if formatting.Content != uglyContent {
+	if formatting.Content != uglyContent || !formatting.ContentKnown {
 		t.Fatalf("missing formatter must return written content, got %q", formatting.Content)
 	}
 	if notice := formatting.notice("a.go"); notice != "" {
 		t.Fatalf("an uninstalled formatter is a standing fact, not a miss worth reporting, got %q", notice)
 	}
 }
+
+func TestFormatOnWriteReadsMutatedFileAfterFormatterFailure(t *testing.T) {
+	requireGofmt(t)
+	t.Setenv("ZERO_FORMAT_ON_WRITE", "1")
+	targetPath := filepath.Join(t.TempDir(), "a.go")
+	if err := os.WriteFile(targetPath, []byte("requested"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	priorRunner := runFormatOnWriteCommand
+	runFormatOnWriteCommand = func(_ context.Context, _ string, _ []string, _ string) error {
+		if err := os.WriteFile(targetPath, []byte("formatter-mutated"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		return exec.ErrNotFound
+	}
+	t.Cleanup(func() { runFormatOnWriteCommand = priorRunner })
+
+	formatting := maybeFormatWrittenFile(context.Background(), targetPath, "requested")
+	if !formatting.ContentKnown || formatting.Content != "requested" {
+		t.Fatalf("formatter failure content = %q, known=%t", formatting.Content, formatting.ContentKnown)
+	}
+}
+
+func TestFormatOnWriteReportsWhenFormatterFailureCannotBeRestored(t *testing.T) {
+	requireGofmt(t)
+	t.Setenv("ZERO_FORMAT_ON_WRITE", "1")
+	targetPath := filepath.Join(t.TempDir(), "a.go")
+	if err := os.WriteFile(targetPath, []byte("requested"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	priorRunner := runFormatOnWriteCommand
+	runFormatOnWriteCommand = func(_ context.Context, _ string, _ []string, _ string) error {
+		if err := os.Remove(targetPath); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Mkdir(targetPath, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		return exec.ErrNotFound
+	}
+	t.Cleanup(func() { runFormatOnWriteCommand = priorRunner })
+
+	formatting := maybeFormatWrittenFile(context.Background(), targetPath, "requested")
+	if !formatting.RestoreFailed {
+		t.Fatal("failed recovery was not reported")
+	}
+	if formatting.ContentKnown {
+		t.Fatalf("failed recovery reported known content %q", formatting.Content)
+	}
+	if notice := formatting.notice("a.go"); !strings.Contains(notice, "WARNING: a.go may not hold what was written") {
+		t.Fatalf("failed recovery notice = %q", notice)
+	}
+}
+
+func TestWriteFileRecreatesFormatterDeletedTargetWithOriginalMode(t *testing.T) {
+	requireGofmt(t)
+	t.Setenv("ZERO_FORMAT_ON_WRITE", "1")
+	for _, tc := range []struct {
+		name      string
+		existing  bool
+		wantMode  os.FileMode
+		overwrite bool
+	}{
+		{name: "create", wantMode: 0o644},
+		{name: "overwrite", existing: true, wantMode: 0o751, overwrite: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			root := t.TempDir()
+			targetPath := filepath.Join(root, "a.go")
+			if tc.existing {
+				if err := os.WriteFile(targetPath, []byte("before\n"), tc.wantMode); err != nil {
+					t.Fatal(err)
+				}
+			}
+			priorRunner := runFormatOnWriteCommand
+			runFormatOnWriteCommand = func(_ context.Context, _ string, _ []string, _ string) error {
+				if err := os.Remove(targetPath); err != nil {
+					t.Fatal(err)
+				}
+				return exec.ErrNotFound
+			}
+			t.Cleanup(func() { runFormatOnWriteCommand = priorRunner })
+
+			result := NewScopedWriteFileTool(root, nil).Run(context.Background(), map[string]any{
+				"path": "a.go", "content": "requested\n", "overwrite": tc.overwrite,
+			})
+			if result.Status != StatusOK {
+				t.Fatalf("write status = %s: %s", result.Status, result.Output)
+			}
+			content, err := os.ReadFile(targetPath)
+			if err != nil || string(content) != "requested\n" {
+				t.Fatalf("recreated content = %q, err=%v", content, err)
+			}
+			if runtime.GOOS != "windows" {
+				info, err := os.Stat(targetPath)
+				if err != nil {
+					t.Fatal(err)
+				}
+				if got := info.Mode().Perm(); got != tc.wantMode {
+					t.Fatalf("recreated mode = %o, want %o", got, tc.wantMode)
+				}
+			}
+		})
+	}
+}
+
+func TestFormatOnWriteMarksUnreadableFinalStateUnknown(t *testing.T) {
+	requireGofmt(t)
+	t.Setenv("ZERO_FORMAT_ON_WRITE", "1")
+	targetPath := filepath.Join(t.TempDir(), "a.go")
+	if err := os.WriteFile(targetPath, []byte("requested"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	priorRunner := runFormatOnWriteCommand
+	priorReader := readFormattedFile
+	runFormatOnWriteCommand = func(context.Context, string, []string, string) error { return nil }
+	readFormattedFile = func(*os.Root, string) ([]byte, os.FileInfo, error) { return nil, nil, os.ErrPermission }
+	t.Cleanup(func() {
+		runFormatOnWriteCommand = priorRunner
+		readFormattedFile = priorReader
+	})
+
+	formatting := maybeFormatWrittenFile(context.Background(), targetPath, "requested")
+	if formatting.ContentKnown || formatting.Content != "requested" {
+		t.Fatalf("unreadable formatter result = %q, known=%t", formatting.Content, formatting.ContentKnown)
+	}
+}
+
+func TestWriteFileUsesVerifiedBytesAfterFormatterFailure(t *testing.T) {
+	requireGofmt(t)
+	t.Setenv("ZERO_FORMAT_ON_WRITE", "1")
+	root := t.TempDir()
+	targetPath := filepath.Join(root, "a.go")
+	priorRunner := runFormatOnWriteCommand
+	runFormatOnWriteCommand = func(_ context.Context, _ string, _ []string, _ string) error {
+		if err := os.WriteFile(targetPath, []byte("formatter-mutated\n"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		return exec.ErrNotFound
+	}
+	t.Cleanup(func() { runFormatOnWriteCommand = priorRunner })
+
+	result := NewScopedWriteFileTool(root, nil).Run(context.Background(), map[string]any{
+		"path": "a.go", "content": "requested\n",
+	})
+	if result.Status != StatusOK {
+		t.Fatalf("write status = %s: %s", result.Status, result.Output)
+	}
+	if got := result.FileDiffs; len(got) != 1 || got[0].NewText != "requested\n" {
+		t.Fatalf("formatter-failure FileDiff = %#v", got)
+	}
+}
+
+func TestEditFileUsesVerifiedBytesAfterFormatterFailure(t *testing.T) {
+	requireGofmt(t)
+	t.Setenv("ZERO_FORMAT_ON_WRITE", "1")
+	root := t.TempDir()
+	targetPath := filepath.Join(root, "a.go")
+	if err := os.WriteFile(targetPath, []byte("before\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	priorRunner := runFormatOnWriteCommand
+	runFormatOnWriteCommand = func(_ context.Context, _ string, _ []string, _ string) error {
+		if err := os.WriteFile(targetPath, []byte("formatter-mutated\n"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		return exec.ErrNotFound
+	}
+	t.Cleanup(func() { runFormatOnWriteCommand = priorRunner })
+
+	result := NewScopedEditFileTool(root, nil).Run(context.Background(), map[string]any{
+		"path": "a.go", "old_string": "before", "new_string": "requested",
+	})
+	if result.Status != StatusOK {
+		t.Fatalf("edit status = %s: %s", result.Status, result.Output)
+	}
+	if got := result.FileDiffs; len(got) != 1 || got[0].OldText != "before\n" || got[0].NewText != "requested\n" {
+		t.Fatalf("formatter-failure edit FileDiff = %#v", got)
+	}
+}
+
+func TestWriteFileOmitsRichDiffWhenFormatterFinalReadFails(t *testing.T) {
+	requireGofmt(t)
+	t.Setenv("ZERO_FORMAT_ON_WRITE", "1")
+	root := t.TempDir()
+	priorRunner := runFormatOnWriteCommand
+	priorReader := readFormattedFile
+	runFormatOnWriteCommand = func(context.Context, string, []string, string) error { return nil }
+	readFormattedFile = func(*os.Root, string) ([]byte, os.FileInfo, error) { return nil, nil, os.ErrPermission }
+	t.Cleanup(func() {
+		runFormatOnWriteCommand = priorRunner
+		readFormattedFile = priorReader
+	})
+
+	result := NewScopedWriteFileTool(root, nil).Run(context.Background(), map[string]any{
+		"path": "a.go", "content": "requested\n",
+	})
+	if result.Status != StatusOK || len(result.ChangedFiles) != 1 || len(result.FileDiffs) != 0 {
+		t.Fatalf("unverified formatter result = status=%s changed=%#v diffs=%#v", result.Status, result.ChangedFiles, result.FileDiffs)
+	}
+	if result.Display.Preview != "" {
+		t.Fatalf("unverified formatter result exposed stale preview: %q", result.Display.Preview)
+	}
+}
+
+func TestEditFileOmitsPreviewWhenFormatterFinalReadFails(t *testing.T) {
+	requireGofmt(t)
+	t.Setenv("ZERO_FORMAT_ON_WRITE", "1")
+	root := t.TempDir()
+	targetPath := filepath.Join(root, "a.go")
+	if err := os.WriteFile(targetPath, []byte("before\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	priorRunner := runFormatOnWriteCommand
+	priorReader := readFormattedFile
+	runFormatOnWriteCommand = func(context.Context, string, []string, string) error { return nil }
+	readFormattedFile = func(*os.Root, string) ([]byte, os.FileInfo, error) { return nil, nil, os.ErrPermission }
+	t.Cleanup(func() {
+		runFormatOnWriteCommand = priorRunner
+		readFormattedFile = priorReader
+	})
+
+	result := NewScopedEditFileTool(root, nil).Run(context.Background(), map[string]any{
+		"path": "a.go", "old_string": "before", "new_string": "requested",
+	})
+	if result.Status != StatusOK || len(result.ChangedFiles) != 1 || len(result.FileDiffs) != 0 {
+		t.Fatalf("unverified formatter result = status=%s changed=%#v diffs=%#v", result.Status, result.ChangedFiles, result.FileDiffs)
+	}
+	if result.Display.Preview != "" {
+		t.Fatalf("unverified formatter result exposed stale preview: %q", result.Display.Preview)
+	}
+}
+
+func TestWriteFileOmitsRichEvidenceWhenFormatterReplacesTargetWithOutOfRootSymlink(t *testing.T) {
+	requireGofmt(t)
+	t.Setenv("ZERO_FORMAT_ON_WRITE", "1")
+	root := t.TempDir()
+	targetPath := filepath.Join(root, "a.go")
+	resolvedRoot, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	trackedPath := filepath.Join(resolvedRoot, "a.go")
+	outsidePath := filepath.Join(t.TempDir(), "outside.go")
+	outsideContent := "package external\n\nconst Secret = \"outside\"\n"
+	if err := os.WriteFile(outsidePath, []byte(outsideContent), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	priorRunner := runFormatOnWriteCommand
+	runFormatOnWriteCommand = func(context.Context, string, []string, string) error {
+		if err := os.Remove(targetPath); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Symlink(outsidePath, targetPath); err != nil {
+			t.Skipf("symlinks unavailable: %v", err)
+		}
+		return nil
+	}
+	t.Cleanup(func() { runFormatOnWriteCommand = priorRunner })
+	tracker := NewFileTracker()
+
+	diagnosticsCalled := false
+	result := NewScopedWriteFileTool(root, nil).(optionsAwareTool).RunWithOptions(context.Background(), map[string]any{
+		"path": "a.go", "content": "package requested\n",
+	}, RunOptions{FileTracker: tracker, Diagnostics: func(context.Context, string) string {
+		diagnosticsCalled = true
+		return "must not run"
+	}})
+	if result.Status != StatusOK || len(result.ChangedFiles) != 1 || len(result.FileDiffs) != 0 || result.Display.Preview != "" {
+		t.Fatalf("out-of-root formatter result = status=%s changed=%#v diffs=%#v preview=%q output=%q", result.Status, result.ChangedFiles, result.FileDiffs, result.Display.Preview, result.Output)
+	}
+	if diagnosticsCalled {
+		t.Fatal("diagnostics must not inspect an unverified formatter target")
+	}
+	if _, tracked := tracker.Version(trackedPath); tracked {
+		t.Fatal("out-of-root formatter target must not be recorded in the tracker")
+	}
+}
+
+func TestEditFileOmitsRichEvidenceWhenFormatterReplacesTargetWithOutOfRootSymlink(t *testing.T) {
+	requireGofmt(t)
+	t.Setenv("ZERO_FORMAT_ON_WRITE", "1")
+	root := t.TempDir()
+	targetPath := filepath.Join(root, "a.go")
+	resolvedRoot, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	trackedPath := filepath.Join(resolvedRoot, "a.go")
+	if err := os.WriteFile(targetPath, []byte("package before\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	outsidePath := filepath.Join(t.TempDir(), "outside.go")
+	outsideContent := "package external\n\nconst Secret = \"outside\"\n"
+	if err := os.WriteFile(outsidePath, []byte(outsideContent), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	priorRunner := runFormatOnWriteCommand
+	runFormatOnWriteCommand = func(context.Context, string, []string, string) error {
+		if err := os.Remove(targetPath); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Symlink(outsidePath, targetPath); err != nil {
+			t.Skipf("symlinks unavailable: %v", err)
+		}
+		return nil
+	}
+	t.Cleanup(func() { runFormatOnWriteCommand = priorRunner })
+	tracker := NewFileTracker()
+	read := NewScopedReadFileTool(root, nil).(optionsAwareTool).RunWithOptions(context.Background(), map[string]any{
+		"path": "a.go",
+	}, RunOptions{FileTracker: tracker})
+	if read.Status != StatusOK {
+		t.Fatalf("read before edit failed: %s", read.Output)
+	}
+
+	diagnosticsCalled := false
+	result := NewScopedEditFileTool(root, nil).(optionsAwareTool).RunWithOptions(context.Background(), map[string]any{
+		"path": "a.go", "old_string": "before", "new_string": "requested",
+	}, RunOptions{FileTracker: tracker, Diagnostics: func(context.Context, string) string {
+		diagnosticsCalled = true
+		return "must not run"
+	}})
+	if result.Status != StatusOK || len(result.ChangedFiles) != 1 || len(result.FileDiffs) != 0 || result.Display.Preview != "" {
+		t.Fatalf("out-of-root formatter result = status=%s changed=%#v diffs=%#v preview=%q output=%q", result.Status, result.ChangedFiles, result.FileDiffs, result.Display.Preview, result.Output)
+	}
+	if diagnosticsCalled {
+		t.Fatal("diagnostics must not inspect an unverified formatter target")
+	}
+	if _, tracked := tracker.Version(trackedPath); tracked {
+		t.Fatal("out-of-root formatter target must not be recorded in the tracker")
+	}
+}
+
+func TestWriteFileAcceptsInRootAtomicFormatterReplacement(t *testing.T) {
+	requireGofmt(t)
+	t.Setenv("ZERO_FORMAT_ON_WRITE", "1")
+	root := t.TempDir()
+	targetPath := filepath.Join(root, "a.go")
+	formatted := "package formatted\n"
+	priorRunner := runFormatOnWriteCommand
+	runFormatOnWriteCommand = func(context.Context, string, []string, string) error {
+		tempPath := filepath.Join(root, "formatter.tmp")
+		if err := os.WriteFile(tempPath, []byte(formatted), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		return os.Rename(tempPath, targetPath)
+	}
+	t.Cleanup(func() { runFormatOnWriteCommand = priorRunner })
+	tracker := NewFileTracker()
+
+	result := NewScopedWriteFileTool(root, nil).(optionsAwareTool).RunWithOptions(context.Background(), map[string]any{
+		"path": "a.go", "content": "package requested\n",
+	}, RunOptions{FileTracker: tracker})
+	if result.Status != StatusOK || len(result.FileDiffs) != 1 || result.FileDiffs[0].NewText != formatted {
+		t.Fatalf("atomic formatter write = status=%s diffs=%#v output=%q", result.Status, result.FileDiffs, result.Output)
+	}
+	resolvedRoot, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	version, tracked := tracker.Version(filepath.Join(resolvedRoot, "a.go"))
+	if !tracked || version.Hash != HashContent([]byte(formatted)) {
+		t.Fatalf("atomic formatter tracker = %#v, tracked=%t", version, tracked)
+	}
+}
+
+func TestEditFileAcceptsInRootAtomicFormatterReplacement(t *testing.T) {
+	requireGofmt(t)
+	t.Setenv("ZERO_FORMAT_ON_WRITE", "1")
+	root := t.TempDir()
+	targetPath := filepath.Join(root, "a.go")
+	if err := os.WriteFile(targetPath, []byte("package before\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	formatted := "package formatted\n"
+	priorRunner := runFormatOnWriteCommand
+	runFormatOnWriteCommand = func(context.Context, string, []string, string) error {
+		tempPath := filepath.Join(root, "formatter.tmp")
+		if err := os.WriteFile(tempPath, []byte(formatted), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		return os.Rename(tempPath, targetPath)
+	}
+	t.Cleanup(func() { runFormatOnWriteCommand = priorRunner })
+	tracker := NewFileTracker()
+	read := NewScopedReadFileTool(root, nil).(optionsAwareTool).RunWithOptions(context.Background(), map[string]any{
+		"path": "a.go",
+	}, RunOptions{FileTracker: tracker})
+	if read.Status != StatusOK {
+		t.Fatalf("read before edit failed: %s", read.Output)
+	}
+
+	result := NewScopedEditFileTool(root, nil).(optionsAwareTool).RunWithOptions(context.Background(), map[string]any{
+		"path": "a.go", "old_string": "before", "new_string": "requested",
+	}, RunOptions{FileTracker: tracker})
+	if result.Status != StatusOK || len(result.FileDiffs) != 1 || result.FileDiffs[0].NewText != formatted {
+		t.Fatalf("atomic formatter edit = status=%s diffs=%#v output=%q", result.Status, result.FileDiffs, result.Output)
+	}
+	resolvedRoot, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	version, tracked := tracker.Version(filepath.Join(resolvedRoot, "a.go"))
+	if !tracked || version.Hash != HashContent([]byte(formatted)) {
+		t.Fatalf("atomic formatter tracker = %#v, tracked=%t", version, tracked)
+	}
+}

internal/tools/registry.go

@@ -343,6 +343,33 @@ func scrubResultSecrets(res Result) Result {
 		res.Display.Preview = scrubbed
 		res.Redacted = true
 	}
+	fileDiffs := make([]FileDiff, 0, len(res.FileDiffs))
+	for _, diff := range res.FileDiffs {
+		// Never normalize control bytes in a diff: normalizing after redaction can
+		// reassemble a split credential. Decline unsafe rich content entirely and
+		// leave ChangedFiles as the safe fallback.
+		if unsafeDiffText(diff.OldText) || unsafeDiffText(diff.NewText) {
+			res.Redacted = true
+			continue
+		}
+		if scrubbed := redaction.RedactString(diff.OldText, redaction.Options{}); scrubbed != diff.OldText {
+			diff.OldText = scrubbed
+			res.Redacted = true
+		}
+		if scrubbed := redaction.RedactString(diff.NewText, redaction.Options{}); scrubbed != diff.NewText {
+			diff.NewText = scrubbed
+			res.Redacted = true
+		}
+		// Redaction can collapse two distinct credentials to the same token. At
+		// this final outbound boundary, retain rich evidence only when the
+		// transformed sides still describe a real transition; ChangedFiles
+		// remains the safe path-only fallback.
+		if diff.OldExists == diff.NewExists && diff.OldText == diff.NewText {
+			continue
+		}
+		fileDiffs = append(fileDiffs, diff)
+	}
+	res.FileDiffs = fileDiffs
 	// Meta values carry model-controlled strings (e.g. glob pattern, bash cwd) and
 	// are forwarded into the transcript, so they are part of the boundary too.
 	for key, value := range res.Meta {
@@ -354,6 +381,13 @@ func scrubResultSecrets(res Result) Result {
 	return res
 }
 
+// ScrubResultSecrets applies the registry's transcript boundary to a result
+// that was produced before Registry.RunWithOptions could own it, such as a
+// local pre-permission rejection in the agent loop.
+func ScrubResultSecrets(res Result) Result {
+	return scrubResultSecrets(res)
+}
+
 func CoreReadOnlyToolsScoped(workspaceRoot string, scope PathScope) []Tool {
 	return []Tool{
 		NewScopedReadMinifiedFileTool(workspaceRoot, scope),

internal/tools/registry_test.go

@@ -445,13 +445,120 @@ func (t denyTool) Run(context.Context, map[string]any) Result { return Result{St
 // must be scrubbed too, not just the tool-execution paths.
 func TestScrubResultSecretsRedactsPreview(t *testing.T) {
 	secret := "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
-	res := scrubResultSecrets(Result{Display: Display{Preview: "+++ b/x\n+token := \"" + secret + "\""}})
+	res := scrubResultSecrets(Result{
+		Display:   Display{Preview: "+++ b/x\n+token := \"" + secret + "\""},
+		FileDiffs: []FileDiff{{Path: filepath.Join(t.TempDir(), "x"), OldExists: true, NewExists: true, OldText: "before " + secret, NewText: "after " + secret}},
+	})
 	if strings.Contains(res.Display.Preview, secret) {
 		t.Errorf("Display.Preview (the card-only code preview) must be redacted, leaked: %q", res.Display.Preview)
 	}
 	if !res.Redacted {
 		t.Error("scrubbing a secret from the preview should set Redacted")
 	}
+	if len(res.FileDiffs) != 1 || strings.Contains(res.FileDiffs[0].OldText, secret) || strings.Contains(res.FileDiffs[0].NewText, secret) {
+		t.Errorf("FileDiff must be redacted: %#v", res.FileDiffs)
+	}
+}
+
+func TestScrubResultSecretsDropsControlSplitFileDiff(t *testing.T) {
+	secret := "sk-proj-abcdefghijklmnopqrstuvwxyz"
+	res := scrubResultSecrets(Result{FileDiffs: []FileDiff{{
+		Path:      filepath.Join(t.TempDir(), "x"),
+		OldExists: true,
+		NewExists: true,
+		OldText:   "token=" + secret[:12] + "\x00" + secret[12:],
+		NewText:   "safe",
+	}}})
+	if len(res.FileDiffs) != 0 || !res.Redacted {
+		t.Fatalf("unsafe FileDiff = %#v, redacted = %t", res.FileDiffs, res.Redacted)
+	}
+}
+
+func TestScrubResultSecretsDropsDefaultIgnorableSplitFileDiffOnEitherSide(t *testing.T) {
+	secret := "sk-ant-api03-AAAABBBBCCCCDDDDEEEEFFFFGGGG"
+	for name, separator := range map[string]string{
+		"combining grapheme joiner": "\u034f",
+		"variation selector":        "\ufe0f",
+	} {
+		for _, side := range []string{"old", "new"} {
+			t.Run(name+" "+side, func(t *testing.T) {
+				obfuscated := secret[:20] + separator + secret[20:]
+				diff := FileDiff{
+					Path: filepath.Join(t.TempDir(), "x"), OldExists: true, NewExists: true,
+					OldText: "safe old", NewText: "safe new",
+				}
+				if side == "old" {
+					diff.OldText = obfuscated
+				} else {
+					diff.NewText = obfuscated
+				}
+				res := scrubResultSecrets(Result{FileDiffs: []FileDiff{diff}})
+				if len(res.FileDiffs) != 0 || !res.Redacted {
+					t.Fatalf("unsafe FileDiff = %#v, redacted = %t", res.FileDiffs, res.Redacted)
+				}
+			})
+		}
+	}
+}
+
+func TestScrubResultSecretsDoesNotMutateCallerFileDiffSlice(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "x")
+	secret := "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	retainedOld := "before token=" + secret
+	retainedNew := "after token=" + secret
+	original := []FileDiff{
+		{Path: path, OldExists: true, NewExists: true, OldText: "token=sk-proj-abc\x00def", NewText: "unsafe"},
+		{Path: path, OldExists: true, NewExists: true, OldText: retainedOld, NewText: retainedNew},
+	}
+	result := scrubResultSecrets(Result{FileDiffs: original})
+	if len(result.FileDiffs) != 1 || strings.Contains(result.FileDiffs[0].OldText, secret) || strings.Contains(result.FileDiffs[0].NewText, secret) {
+		t.Fatalf("filtered FileDiffs = %#v", result.FileDiffs)
+	}
+	if original[0].NewText != "unsafe" || original[1].OldText != retainedOld || original[1].NewText != retainedNew {
+		t.Fatalf("caller slice was mutated: %#v", original)
+	}
+}
+
+func TestScrubResultSecretsDropsSemanticallyUnchangedRedactedDiff(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "credentials.txt")
+	oldSecret := "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	newSecret := "ghp_9876543210ZYXWVUTSRQPONMLKJIHGFEDCBA"
+	result := scrubResultSecrets(Result{
+		ChangedFiles: []string{"credentials.txt"},
+		FileDiffs: []FileDiff{{
+			Path: path, OldExists: true, NewExists: true,
+			OldText: "token=" + oldSecret, NewText: "token=" + newSecret,
+		}},
+	})
+	if len(result.FileDiffs) != 0 {
+		t.Fatalf("semantically unchanged redacted diff = %#v", result.FileDiffs)
+	}
+	if got, want := result.ChangedFiles, []string{"credentials.txt"}; !slices.Equal(got, want) {
+		t.Fatalf("ChangedFiles = %#v, want %#v", got, want)
+	}
+	if !result.Redacted {
+		t.Fatal("credential rotation must set Redacted")
+	}
+}
+
+func TestScrubResultSecretsKeepsRealTransitionAroundRedactedSecrets(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "credentials.txt")
+	oldSecret := "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	newSecret := "ghp_9876543210ZYXWVUTSRQPONMLKJIHGFEDCBA"
+	result := scrubResultSecrets(Result{FileDiffs: []FileDiff{{
+		Path: path, OldExists: true, NewExists: true,
+		OldText: "environment=staging token=" + oldSecret,
+		NewText: "environment=production token=" + newSecret,
+	}}})
+	if len(result.FileDiffs) != 1 {
+		t.Fatalf("redacted real transition = %#v", result.FileDiffs)
+	}
+	if result.FileDiffs[0].OldText == result.FileDiffs[0].NewText {
+		t.Fatalf("redacted transition became unchanged: %#v", result.FileDiffs[0])
+	}
+	if strings.Contains(result.FileDiffs[0].OldText, oldSecret) || strings.Contains(result.FileDiffs[0].NewText, newSecret) {
+		t.Fatalf("redacted transition leaked a secret: %#v", result.FileDiffs[0])
+	}
 }
 
 func TestRunWithOptionsScrubsSecretsOnDenialPaths(t *testing.T) {

internal/tools/rooted_file.go

@@ -0,0 +1,43 @@
+package tools
+
+import (
+	"fmt"
+	"io"
+	"os"
+)
+
+// readRootedFile returns bytes and identity from the same opened object, and
+// verifies that the rooted path still names that object after the read. Root.Open
+// binds symlink containment to use rather than relying on a pathname pre-check.
+func readRootedFile(root *os.Root, relativePath string) ([]byte, os.FileInfo, error) {
+	file, err := root.Open(relativePath)
+	if err != nil {
+		return nil, nil, err
+	}
+	closed := false
+	defer func() {
+		if !closed {
+			_ = file.Close()
+		}
+	}()
+	openedInfo, err := file.Stat()
+	if err != nil {
+		return nil, nil, err
+	}
+	if !openedInfo.Mode().IsRegular() {
+		return nil, nil, fmt.Errorf("%s is not a regular file", relativePath)
+	}
+	content, err := io.ReadAll(file)
+	if err != nil {
+		return nil, nil, err
+	}
+	pathInfo, err := root.Stat(relativePath)
+	if err != nil || !os.SameFile(openedInfo, pathInfo) {
+		return nil, nil, fmt.Errorf("%w: path identity changed", errFileChangedDuringWrite)
+	}
+	if err := file.Close(); err != nil {
+		return nil, nil, err
+	}
+	closed = true
+	return content, openedInfo, nil
+}

internal/tools/structured_patch.go

@@ -86,12 +86,13 @@ type structuredPatchTarget struct {
 }
 
 type structuredPatchChange struct {
-	kind   structuredPatchKind
-	from   structuredPatchTarget
-	to     structuredPatchTarget
-	before string
-	after  string
-	mode   os.FileMode
+	kind       structuredPatchKind
+	from       structuredPatchTarget
+	to         structuredPatchTarget
+	before     string
+	after      string
+	mode       os.FileMode
+	beforeInfo os.FileInfo
 }
 
 // unifiedHunkRangePattern recognises a unified-diff range header ("-12,4 +12,6",
@@ -156,8 +157,14 @@ func applyPatchOperations(applyRoot, relativeRoot string, operations []structure
 			}
 		}
 	}
-	if err := applyStructuredPatchChanges(workspace, changes, options.FileTracker); err != nil {
-		return errorResult("Error applying patch: " + err.Error())
+	applyOutcome, err := applyStructuredPatchChanges(workspace, relativeRoot, changes, options.FileTracker)
+	if err != nil {
+		result := errorResult("Error applying patch: " + err.Error())
+		result.ChangedFiles = changedFilesFromStructuredPatch(relativeRoot, applyOutcome.committed)
+		result.FileDiffs = fileDiffsFromStructuredPatch(relativeRoot, applyOutcome.committed)
+		result.Redacted = structuredPatchContainsObfuscatedSecret(applyOutcome.committed)
+		result.Display = Display{Summary: result.Output, Kind: "diff", Preview: structuredPatchPreview(applyOutcome.committed)}
+		return result
 	}
 
 	for _, change := range changes {
@@ -183,10 +190,78 @@ func applyPatchOperations(applyRoot, relativeRoot string, operations []structure
 	}
 	result := okResult(summary)
 	result.ChangedFiles = changedFilesFromStructuredPatch(relativeRoot, changes)
+	result.FileDiffs = fileDiffsFromStructuredPatch(relativeRoot, changes)
+	result.Redacted = structuredPatchContainsObfuscatedSecret(changes)
 	result.Display = Display{Summary: summary, Kind: "diff", Preview: structuredPatchPreview(changes)}
 	return result
 }
 
+func structuredPatchContainsObfuscatedSecret(changes []structuredPatchChange) bool {
+	for _, change := range changes {
+		if diffTextRevealsObfuscatedSecret(change.before) || diffTextRevealsObfuscatedSecret(change.after) {
+			return true
+		}
+	}
+	return false
+}
+
+func fileDiffsFromStructuredPatch(_ string, changes []structuredPatchChange) []FileDiff {
+	const maxToolResultFileDiffs = 64
+	diffs := make([]FileDiff, 0, len(changes)*2)
+	usedBytes := 0
+	appendGroup := func(group ...FileDiff) bool {
+		if len(group) == 0 || len(diffs)+len(group) > maxToolResultFileDiffs {
+			return false
+		}
+		groupBytes := 0
+		for _, diff := range group {
+			groupBytes += len(diff.OldText) + len(diff.NewText)
+		}
+		if usedBytes+groupBytes > maxToolResultFileDiffBytes {
+			return false
+		}
+		diffs = append(diffs, group...)
+		usedBytes += groupBytes
+		return true
+	}
+	makeDiff := func(path, before, after string, oldExists, newExists bool) (FileDiff, bool) {
+		return boundedFileDiff(path, before, after, oldExists, newExists)
+	}
+	for _, change := range changes {
+		var group []FileDiff
+		switch {
+		case change.kind == structuredPatchDelete:
+			if diff, ok := makeDiff(change.from.absolute, change.before, "", true, false); ok {
+				group = append(group, diff)
+			}
+		case change.kind == structuredPatchAdd:
+			if diff, ok := makeDiff(change.to.absolute, "", change.after, false, true); ok {
+				group = append(group, diff)
+			}
+		case change.kind == structuredPatchCopy && change.from.absolute != change.to.absolute:
+			// A copy leaves its source unchanged; the destination is a create.
+			if diff, ok := makeDiff(change.to.absolute, "", change.after, false, true); ok {
+				group = append(group, diff)
+			}
+		case change.kind == structuredPatchUpdate && change.from.absolute != change.to.absolute:
+			// A move is two filesystem changes, not a destination overwrite.
+			from, fromOK := makeDiff(change.from.absolute, change.before, "", true, false)
+			to, toOK := makeDiff(change.to.absolute, "", change.after, false, true)
+			if fromOK && toOK {
+				group = append(group, from, to)
+			}
+		default:
+			if diff, ok := makeDiff(change.to.absolute, change.before, change.after, true, true); ok {
+				group = append(group, diff)
+			}
+		}
+		if len(group) > 0 && !appendGroup(group...) {
+			break
+		}
+	}
+	return diffs
+}
+
 func parseStructuredPatch(patch string) ([]structuredPatchOperation, error) {
 	normalized := strings.TrimSpace(strings.TrimPrefix(strings.ReplaceAll(patch, "\r\n", "\n"), "\ufeff"))
 	if normalized == "" {
@@ -394,15 +469,12 @@ func planStructuredPatch(root *os.Root, operations []structuredPatchOperation, t
 			}
 			change.after = operation.contents
 		case structuredPatchDelete, structuredPatchUpdate, structuredPatchCopy:
-			info, err := root.Stat(from.relative)
-			if err != nil {
-				return nil, fmt.Errorf("stating %s: %w", from.relative, err)
-			}
-			change.mode = info.Mode()
-			content, err := root.ReadFile(from.relative)
+			content, info, err := readRootedFile(root, from.relative)
 			if err != nil {
 				return nil, fmt.Errorf("reading %s: %w", from.relative, err)
 			}
+			change.mode = info.Mode()
+			change.beforeInfo = info
 			if err := tracker.CheckConflict(from.absolute, content); err != nil {
 				return nil, fmt.Errorf("%s", fileConflictMessage(from.relative))
 			}
@@ -672,38 +744,112 @@ func findStructuredPatchSequence(lines, wanted []string, start int, endOfFile bo
 	return -1, false
 }
 
-func applyStructuredPatchChanges(root *os.Root, changes []structuredPatchChange, tracker *FileTracker) error {
+type structuredPatchApplyOutcome struct {
+	committed       []structuredPatchChange
+	incompletePaths []string
+}
+
+type structuredPatchChangeOutcome struct {
+	completed       []structuredPatchChange
+	incompletePaths []string
+}
+
+func applyStructuredPatchChanges(root *os.Root, relativeRoot string, changes []structuredPatchChange, tracker *FileTracker) (structuredPatchApplyOutcome, error) {
 	// committed lists, in order, the paths whose change reached disk before a
 	// later change failed, so the caller (and the model) knows exactly which
 	// files now hold the patched content and which were never touched.
-	var committed []string
+	var outcome structuredPatchApplyOutcome
 	for _, change := range changes {
-		done, err := applyStructuredPatchChange(root, change)
-		if done {
-			committed = append(committed, structuredPatchChangePaths(change)...)
-		}
+		changeOutcome, err := applyStructuredPatchChange(root, change)
+		outcome.committed = append(outcome.committed, changeOutcome.completed...)
+		outcome.incompletePaths = append(outcome.incompletePaths, changeOutcome.incompletePaths...)
 		if err != nil {
 			forgetStructuredPatchFiles(tracker, changes)
-			if len(committed) > 0 {
-				return fmt.Errorf("%w; patch was partially applied — already committed: %s; the remaining files are unchanged; re-read the committed files before retrying", err, strings.Join(committed, ", "))
+			committedPaths := changedFilesFromStructuredPatch(relativeRoot, outcome.committed)
+			unverifiedPaths := appendUniqueStructuredPatchPaths(nil, relativeRoot, outcome.incompletePaths)
+			if len(committedPaths) > 0 || len(unverifiedPaths) > 0 {
+				parts := []string{"patch was partially applied"}
+				if len(committedPaths) > 0 {
+					parts = append(parts, "already committed: "+strings.Join(committedPaths, ", "))
+				}
+				if len(unverifiedPaths) > 0 {
+					parts = append(parts, "published but unverified: "+strings.Join(unverifiedPaths, ", "))
+				}
+				parts = append(parts, "the remaining files are unchanged")
+				if len(unverifiedPaths) > 0 {
+					parts = append(parts, "re-read the listed files before retrying")
+				} else {
+					parts = append(parts, "re-read the committed files before retrying")
+				}
+				return outcome, fmt.Errorf("%w; %s", err, strings.Join(parts, "; "))
 			}
-			return err
+			return outcome, err
 		}
 	}
-	return nil
+	return outcome, nil
 }
 
-// structuredPatchChangePaths names the workspace-relative paths a committed
-// change touched: the destination, plus the source of a move or copy.
-func structuredPatchChangePaths(change structuredPatchChange) []string {
-	if change.kind == structuredPatchDelete {
-		return []string{change.from.relative}
+// completedStructuredPatchEffect turns a partially completed compound change
+// into the exact filesystem sub-effect that is still verifiable after the
+// error. In particular, a failed move may have published its destination while
+// leaving the source in place; that is a destination creation, not a move.
+func completedStructuredPatchEffect(root *os.Root, change structuredPatchChange) (structuredPatchChange, bool) {
+	if change.to.relative == "" {
+		return structuredPatchChange{}, false
 	}
-	paths := []string{change.to.relative}
-	if change.from.absolute != change.to.absolute && change.from.relative != "" {
-		paths = append([]string{change.from.relative}, paths...)
+	content, _, err := readRootedFile(root, change.to.relative)
+	if err != nil || string(content) != change.after {
+		return structuredPatchChange{}, false
 	}
-	return paths
+	switch change.kind {
+	case structuredPatchAdd, structuredPatchCopy:
+		return structuredPatchChange{
+			kind:  structuredPatchAdd,
+			to:    change.to,
+			after: change.after,
+			mode:  change.mode,
+		}, true
+	case structuredPatchUpdate:
+		if change.from.absolute != change.to.absolute {
+			return structuredPatchChange{
+				kind:  structuredPatchAdd,
+				to:    change.to,
+				after: change.after,
+				mode:  change.mode,
+			}, true
+		}
+	}
+	return structuredPatchChange{}, false
+}
+
+func incompleteStructuredPatchWrite(root *os.Root, change structuredPatchChange, published bool) structuredPatchChangeOutcome {
+	if !published {
+		return structuredPatchChangeOutcome{}
+	}
+	if completed, ok := completedStructuredPatchEffect(root, change); ok {
+		return structuredPatchChangeOutcome{completed: []structuredPatchChange{completed}}
+	}
+	if change.to.relative != "" {
+		return structuredPatchChangeOutcome{incompletePaths: []string{change.to.relative}}
+	}
+	return structuredPatchChangeOutcome{}
+}
+
+func appendUniqueStructuredPatchPaths(existing []string, relativeRoot string, paths []string) []string {
+	seen := make(map[string]bool, len(existing)+len(paths))
+	for _, path := range existing {
+		seen[path] = true
+	}
+	for _, path := range paths {
+		if relativeRoot != "" && relativeRoot != "." {
+			path = filepath.ToSlash(filepath.Join(relativeRoot, path))
+		}
+		if path != "" && !seen[path] {
+			seen[path] = true
+			existing = append(existing, path)
+		}
+	}
+	return existing
 }
 
 func forgetStructuredPatchFiles(tracker *FileTracker, changes []structuredPatchChange) {
@@ -723,7 +869,17 @@ func forgetStructuredPatchFiles(tracker *FileTracker, changes []structuredPatchC
 // deterministically; it is nil in production.
 var structuredPatchBeforeCommit func(change structuredPatchChange)
 
-func applyStructuredPatchChange(root *os.Root, change structuredPatchChange) (bool, error) {
+// structuredPatchBeforeRename runs after a same-path update has staged and
+// closed its replacement but before the final preimage recheck and rename.
+// Tests use it to reproduce a competing writer deterministically.
+var structuredPatchBeforeRename func(change structuredPatchChange)
+
+// structuredPatchRemove is a deterministic test seam for failures after a
+// move destination has been published. Production removes through the opened
+// workspace root.
+var structuredPatchRemove = func(root *os.Root, name string) error { return root.Remove(name) }
+
+func applyStructuredPatchChange(root *os.Root, change structuredPatchChange) (structuredPatchChangeOutcome, error) {
 	if structuredPatchBeforeCommit != nil {
 		structuredPatchBeforeCommit(change)
 	}
@@ -732,39 +888,63 @@ func applyStructuredPatchChange(root *os.Root, change structuredPatchChange) (bo
 	// by another process in between is refused rather than overwritten or
 	// removed.
 	if change.kind != structuredPatchAdd {
-		current, err := root.ReadFile(change.from.relative)
-		if err != nil {
-			return false, fmt.Errorf("re-reading %s before commit: %w", change.from.relative, err)
-		}
-		if string(current) != change.before {
-			return false, fmt.Errorf("%s changed on disk between planning and commit; re-read it and retry", change.from.relative)
+		if err := recheckStructuredPatchPreimage(root, change); err != nil {
+			return structuredPatchChangeOutcome{}, err
 		}
 	}
 	switch change.kind {
 	case structuredPatchDelete:
-		if err := root.Remove(change.from.relative); err != nil {
-			return false, fmt.Errorf("deleting %s: %w", change.from.relative, err)
+		if err := structuredPatchRemove(root, change.from.relative); err != nil {
+			return structuredPatchChangeOutcome{}, fmt.Errorf("deleting %s: %w", change.from.relative, err)
 		}
-		return true, nil
+		return structuredPatchChangeOutcome{completed: []structuredPatchChange{change}}, nil
 	case structuredPatchAdd, structuredPatchCopy:
-		return writeStructuredPatchFile(root, change.to, change.after, change.mode, true)
+		var beforePublish func() error
+		if change.kind == structuredPatchCopy {
+			beforePublish = structuredPatchPrePublishGuard(root, change)
+		}
+		published, err := writeStructuredPatchFile(root, change.to, change.after, change.mode, true, beforePublish)
+		if err != nil {
+			return incompleteStructuredPatchWrite(root, change, published), err
+		}
+		return structuredPatchChangeOutcome{completed: []structuredPatchChange{change}}, nil
 	case structuredPatchUpdate:
 		moving := change.from.absolute != change.to.absolute
-		committed, err := writeStructuredPatchFile(root, change.to, change.after, change.mode, moving)
+		published, err := writeStructuredPatchFile(root, change.to, change.after, change.mode, moving, structuredPatchPrePublishGuard(root, change))
 		if err != nil {
-			return committed, err
+			return incompleteStructuredPatchWrite(root, change, published), err
 		}
 		if moving {
-			if err := root.Remove(change.from.relative); err != nil {
-				return true, fmt.Errorf("removing moved source %s: %w", change.from.relative, err)
+			if err := structuredPatchRemove(root, change.from.relative); err != nil {
+				return incompleteStructuredPatchWrite(root, change, true), fmt.Errorf("removing moved source %s: %w", change.from.relative, err)
 			}
 		}
-		return true, nil
+		return structuredPatchChangeOutcome{completed: []structuredPatchChange{change}}, nil
 	}
-	return false, fmt.Errorf("unsupported structured patch operation")
+	return structuredPatchChangeOutcome{}, fmt.Errorf("unsupported structured patch operation")
 }
 
-func writeStructuredPatchFile(root *os.Root, target structuredPatchTarget, content string, mode os.FileMode, createOnly bool) (bool, error) {
+func recheckStructuredPatchPreimage(root *os.Root, change structuredPatchChange) error {
+	current, info, err := readRootedFile(root, change.from.relative)
+	if err != nil {
+		return fmt.Errorf("re-reading %s before commit: %w", change.from.relative, err)
+	}
+	if (change.beforeInfo != nil && !os.SameFile(change.beforeInfo, info)) || string(current) != change.before {
+		return fmt.Errorf("%s changed on disk between planning and commit; re-read it and retry", change.from.relative)
+	}
+	return nil
+}
+
+func structuredPatchPrePublishGuard(root *os.Root, change structuredPatchChange) func() error {
+	return func() error {
+		if change.kind == structuredPatchUpdate && change.from.absolute == change.to.absolute && structuredPatchBeforeRename != nil {
+			structuredPatchBeforeRename(change)
+		}
+		return recheckStructuredPatchPreimage(root, change)
+	}
+}
+
+func writeStructuredPatchFile(root *os.Root, target structuredPatchTarget, content string, mode os.FileMode, createOnly bool, beforePublish func() error) (bool, error) {
 	parent := filepath.Dir(target.relative)
 	if err := root.MkdirAll(parent, 0o755); err != nil {
 		return false, fmt.Errorf("creating parent directory for %s: %w", target.relative, err)
@@ -785,8 +965,13 @@ func writeStructuredPatchFile(root *os.Root, target structuredPatchTarget, conte
 	if err := temp.Close(); err != nil {
 		return false, fmt.Errorf("writing %s: %w", target.relative, err)
 	}
+	if beforePublish != nil {
+		if err := beforePublish(); err != nil {
+			return false, err
+		}
+	}
 	if createOnly {
-		return publishStructuredPatchNoReplace(root, tempName, target.relative, mode)
+		return structuredPatchPublishNoReplace(root, tempName, target.relative, mode)
 	}
 	if err := root.Rename(tempName, target.relative); err != nil {
 		return false, fmt.Errorf("writing %s: %w", target.relative, err)
@@ -798,6 +983,11 @@ func publishStructuredPatchNoReplace(root *os.Root, source, target string, mode
 	return publishStructuredPatchNoReplaceWith(root, source, target, mode, root.Link)
 }
 
+// structuredPatchPublishNoReplace is a deterministic test seam for failures
+// after a create-only target has become visible. Production uses the atomic
+// no-replace publisher above.
+var structuredPatchPublishNoReplace = publishStructuredPatchNoReplace
+
 func publishStructuredPatchNoReplaceWith(root *os.Root, source, target string, mode os.FileMode, link func(string, string) error) (bool, error) {
 	if linkErr := link(source, target); linkErr == nil {
 		cleanupErr := removeStructuredPatchTemp(root, source)
@@ -914,9 +1104,19 @@ func changedFilesFromStructuredPatch(relativeRoot string, changes []structuredPa
 	seen := make(map[string]bool)
 	var paths []string
 	for _, change := range changes {
-		targets := []structuredPatchTarget{change.to}
-		if change.from.absolute != change.to.absolute {
-			targets = append([]structuredPatchTarget{change.from}, targets...)
+		var targets []structuredPatchTarget
+		switch change.kind {
+		case structuredPatchDelete:
+			targets = []structuredPatchTarget{change.from}
+		case structuredPatchUpdate:
+			targets = []structuredPatchTarget{change.to}
+			if change.from.absolute != change.to.absolute {
+				targets = append([]structuredPatchTarget{change.from}, targets...)
+			}
+		default:
+			// Adds and copies mutate only their destination; the copy source is
+			// evidence for the operation, not a changed file.
+			targets = []structuredPatchTarget{change.to}
 		}
 		for _, target := range targets {
 			path := target.relative

internal/tools/types.go

@@ -120,6 +120,10 @@ type Result struct {
 	// entries under a granted extra write root are absolute, since
 	// workspace-relative would be ambiguous there.
 	ChangedFiles []string
+	// FileDiffs carries exact, bounded before/after text for built-in file
+	// mutations. A missing entry means the client must fall back to ChangedFiles
+	// rather than inventing a partial diff.
+	FileDiffs []FileDiff
 	// ChangeSummaries contains bounded generated-tree changes. These are shown
 	// in session evidence and the Files panel but are never treated as files to
 	// open or diagnose individually.

internal/tools/write_file.go

@@ -12,6 +12,7 @@ type writeFileTool struct {
 	baseTool
 	workspaceRoot string
 	scope         PathScope
+	readFile      func(string) ([]byte, error)
 }
 
 func NewScopedWriteFileTool(workspaceRoot string, scope PathScope) Tool {
@@ -34,6 +35,7 @@ func NewScopedWriteFileTool(workspaceRoot string, scope PathScope) Tool {
 		},
 		workspaceRoot: normalizeWorkspaceRoot(workspaceRoot),
 		scope:         scope,
+		readFile:      os.ReadFile,
 	}
 }
 
@@ -61,8 +63,10 @@ func (tool writeFileTool) RunWithOptions(ctx context.Context, args map[string]an
 	}
 
 	existed := false
-	if _, err := os.Stat(absolutePath); err == nil {
+	var priorInfo os.FileInfo
+	if info, err := os.Stat(absolutePath); err == nil {
 		existed = true
+		priorInfo = info
 		if !overwrite {
 			return errorResult("Error: " + relativePath + " already exists. Pass overwrite: true to replace it.")
 		}
@@ -82,7 +86,7 @@ func (tool writeFileTool) RunWithOptions(ctx context.Context, args map[string]an
 			// Fail CLOSED: if the tracked file can't be re-read to verify it, refuse
 			// the overwrite rather than clobbering a file whose current state is
 			// unknown (it may have been replaced or removed out from under us).
-			current, rerr := os.ReadFile(absolutePath)
+			current, rerr := tool.readFile(absolutePath)
 			if rerr != nil {
 				return errorResult(fileConflictMessage(relativePath))
 			}
@@ -95,9 +99,11 @@ func (tool writeFileTool) RunWithOptions(ctx context.Context, args map[string]an
 	// Capture the prior content (before we replace it) so an overwrite can show a
 	// real diff; a fresh create stays "" and previews as all-additions.
 	priorContent := ""
+	priorContentKnown := !existed
 	if existed {
-		if prev, rerr := os.ReadFile(absolutePath); rerr == nil {
+		if prev, rerr := tool.readFile(absolutePath); rerr == nil {
 			priorContent = string(prev)
+			priorContentKnown = true
 		}
 	}
 
@@ -107,20 +113,36 @@ func (tool writeFileTool) RunWithOptions(ctx context.Context, args map[string]an
 	if err := recheckScopedWriteTarget(tool.workspaceRoot, tool.scope, requestedPath); err != nil {
 		return errorResult("Error writing file " + relativePath + ": " + err.Error())
 	}
-	if err := os.WriteFile(absolutePath, []byte(content), 0o644); err != nil {
+	var expectedContent *string
+	if priorContentKnown {
+		expectedContent = &priorContent
+	}
+	if err := commitFileContents(absolutePath, priorInfo, expectedContent, content); err != nil {
 		return errorResult("Error writing file " + relativePath + ": " + err.Error())
 	}
 	modelKnownContent := content
 	// Optional format-on-write (ZERO_FORMAT_ON_WRITE). Must run BEFORE the
 	// FileTracker baseline: recording pre-format content would make the very
 	// next edit look like an external modification and trip the conflict guard.
-	formatting := maybeFormatWrittenFile(ctx, absolutePath, content)
+	restoreMode := os.FileMode(0o644)
+	if priorInfo != nil {
+		restoreMode = priorInfo.Mode().Perm()
+	}
+	formatting := maybeFormatWrittenFileScoped(ctx, tool.workspaceRoot, tool.scope, absolutePath, content, restoreMode)
 	content = formatting.Content
+	finalContentKnown := formatting.ContentKnown
 	// Baseline the freshly written content so a later edit/overwrite in this
 	// session compares against what is now on disk.
-	newInfo, _ := os.Stat(absolutePath)
-	options.FileTracker.Record(absolutePath, []byte(content), newInfo)
-	if content == modelKnownContent {
+	newInfo := formatting.Info
+	if newInfo == nil {
+		newInfo, _ = os.Stat(absolutePath)
+	}
+	if finalContentKnown {
+		options.FileTracker.Record(absolutePath, []byte(content), newInfo)
+	} else {
+		options.FileTracker.Forget(absolutePath)
+	}
+	if finalContentKnown && content == modelKnownContent {
 		options.FileTracker.RecordSeenRange(absolutePath, 1, trackedLineTotal(content), trackedLineTotal(content))
 	}
 	if !existed {
@@ -139,13 +161,28 @@ func (tool writeFileTool) RunWithOptions(ctx context.Context, args map[string]an
 	}
 	summary := fmt.Sprintf("%s %s (%d lines).", verb, relativePath, lines)
 	summary += formatting.notice(relativePath)
-	summary += inlineDiagnostics(ctx, options, absolutePath, relativePath)
+	if finalContentKnown {
+		summary += inlineDiagnostics(ctx, options, absolutePath, relativePath)
+	}
 	result := okResult(summary)
 	result.ChangedFiles = []string{relativePath}
+	// Do not pretend an unreadable overwrite was a creation. The write may be
+	// valid, but ACP only receives an exact before/after pair we actually saw.
+	if priorContentKnown && finalContentKnown {
+		if diff, ok := boundedFileDiff(absolutePath, priorContent, content, existed, true); ok {
+			result.FileDiffs = []FileDiff{diff}
+		} else if diffTextRevealsObfuscatedSecret(priorContent) || diffTextRevealsObfuscatedSecret(content) {
+			result.Redacted = true
+		}
+	}
 	// Card-only preview: a real unified diff (all-green for a create, red/green for
 	// an overwrite) on Display.Preview. Output stays the summary, so the model never
 	// re-reads the file — the rich preview costs zero model tokens.
-	result.Display = Display{Summary: summary, Kind: "file", Preview: boundedUnifiedDiff(relativePath, priorContent, content)}
+	preview := ""
+	if priorContentKnown && finalContentKnown {
+		preview = boundedUnifiedDiff(relativePath, priorContent, content)
+	}
+	result.Display = Display{Summary: summary, Kind: "file", Preview: preview}
 	return result
 }
 

internal/tools/write_tools_test.go

@@ -6,6 +6,8 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"reflect"
+	"slices"
 	"strings"
 	"testing"
 )
@@ -323,6 +325,10 @@ func TestEditFileToolReplacesExactStrings(t *testing.T) {
 	root := t.TempDir()
 	path := filepath.Join(root, "code.go")
 	writeTestFile(t, path, "const a = 1\nconst b = 2\n")
+	path, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		t.Fatal(err)
+	}
 
 	result := NewScopedEditFileTool(root, nil).Run(context.Background(), map[string]any{
 		"path":       "code.go",
@@ -367,7 +373,12 @@ func TestEditFileToolReplacesCRLF(t *testing.T) {
 
 func TestEditFileToolEmitsUnifiedDiff(t *testing.T) {
 	root := t.TempDir()
-	writeTestFile(t, filepath.Join(root, "code.go"), "const a = 1\nconst b = 2\n")
+	path := filepath.Join(root, "code.go")
+	writeTestFile(t, path, "const a = 1\nconst b = 2\n")
+	path, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		t.Fatal(err)
+	}
 	res := NewScopedEditFileTool(root, nil).Run(context.Background(), map[string]any{
 		"path": "code.go", "old_string": "const a = 1", "new_string": "const a = 42",
 	})
@@ -387,6 +398,9 @@ func TestEditFileToolEmitsUnifiedDiff(t *testing.T) {
 			t.Fatalf("edit preview missing diff marker %q: %q", want, res.Display.Preview)
 		}
 	}
+	if got := res.FileDiffs; len(got) != 1 || got[0].Path != path || !got[0].OldExists || !got[0].NewExists || got[0].OldText != "const a = 1\nconst b = 2\n" || got[0].NewText != "const a = 42\nconst b = 2\n" {
+		t.Fatalf("file diffs = %#v", got)
+	}
 }
 
 func TestWriteFileToolEmitsAdditionsDiff(t *testing.T) {
@@ -408,6 +422,13 @@ func TestWriteFileToolEmitsAdditionsDiff(t *testing.T) {
 	if strings.Contains(res.Display.Preview, "\n-line") {
 		t.Fatalf("a fresh-create diff must have no removed lines: %q", res.Display.Preview)
 	}
+	path, err := filepath.EvalSymlinks(filepath.Join(root, "new.txt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := res.FileDiffs; len(got) != 1 || got[0].Path != path || got[0].OldExists || !got[0].NewExists || got[0].OldText != "" || got[0].NewText != "line one\nline two\n" {
+		t.Fatalf("file diffs = %#v", got)
+	}
 }
 
 func TestWriteFileToolOverwriteEmitsRedGreenDiff(t *testing.T) {
@@ -429,6 +450,28 @@ func TestWriteFileToolOverwriteEmitsRedGreenDiff(t *testing.T) {
 	}
 }
 
+func TestWriteFileToolOmitsDiffWhenOverwritePreimageCannotBeRead(t *testing.T) {
+	root := t.TempDir()
+	path := filepath.Join(root, "private.txt")
+	writeTestFile(t, path, "before\n")
+	tool := NewScopedWriteFileTool(root, nil).(writeFileTool)
+	tool.readFile = func(string) ([]byte, error) { return nil, os.ErrPermission }
+	registry := NewRegistry()
+	registry.Register(tool)
+	result := registry.RunWithOptions(context.Background(), tool.Name(), map[string]any{
+		"path": "private.txt", "content": "after\n", "overwrite": true,
+	}, RunOptions{PermissionGranted: true})
+	if result.Status != StatusOK {
+		t.Fatalf("write = %s", result.Output)
+	}
+	if len(result.FileDiffs) != 0 {
+		t.Fatalf("unreadable preimage must not produce a create-like diff: %#v", result.FileDiffs)
+	}
+	if got, err := os.ReadFile(path); err != nil || string(got) != "after\n" {
+		t.Fatalf("written content = %q, err = %v", got, err)
+	}
+}
+
 func TestEditFileToolAllowsDeletingRegions(t *testing.T) {
 	root := t.TempDir()
 	path := filepath.Join(root, "notes.txt")
@@ -584,6 +627,17 @@ func TestApplyPatchToolAppliesStructuredAddAndMove(t *testing.T) {
 	if got := result.ChangedFiles; strings.Join(got, ",") != "nested/new.txt,old.txt,moved.txt" {
 		t.Fatalf("ChangedFiles = %v", got)
 	}
+	resolvedRoot, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := result.FileDiffs, []FileDiff{
+		{Path: filepath.Join(resolvedRoot, "nested", "new.txt"), OldExists: false, NewExists: true, OldText: "", NewText: "created\n"},
+		{Path: filepath.Join(resolvedRoot, "old.txt"), OldExists: true, NewExists: false, OldText: "old\n", NewText: ""},
+		{Path: filepath.Join(resolvedRoot, "moved.txt"), OldExists: false, NewExists: true, OldText: "", NewText: "moved\n"},
+	}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("FileDiffs = %#v, want %#v", got, want)
+	}
 }
 
 func TestApplyPatchToolStructuredPatchMatchesWhitespaceTolerantly(t *testing.T) {
@@ -831,7 +885,7 @@ func TestStructuredPatchAddDoesNotOverwriteRacedDestination(t *testing.T) {
 		after: "patch content\n", mode: 0o644,
 	}
 
-	err = applyStructuredPatchChanges(workspace, []structuredPatchChange{change}, nil)
+	_, err = applyStructuredPatchChanges(workspace, ".", []structuredPatchChange{change}, nil)
 	if err == nil || !errors.Is(err, os.ErrExist) {
 		t.Fatalf("raced add destination = %v, want os.ErrExist", err)
 	}
@@ -857,7 +911,7 @@ func TestStructuredPatchFailedDeleteDoesNotRecreateMissingFile(t *testing.T) {
 		before: "removed by another writer\n", mode: 0o644,
 	}
 
-	err = applyStructuredPatchChanges(workspace, []structuredPatchChange{change}, nil)
+	_, err = applyStructuredPatchChanges(workspace, ".", []structuredPatchChange{change}, nil)
 	if err == nil {
 		t.Fatal("delete of an already removed file should fail")
 	}
@@ -894,7 +948,7 @@ func TestStructuredPatchMoveWithMissingSourceIsRefusedBeforePublishing(t *testin
 	}
 	defer func() { structuredPatchBeforeCommit = nil }()
 
-	err = applyStructuredPatchChanges(workspace, []structuredPatchChange{change}, nil)
+	_, err = applyStructuredPatchChanges(workspace, ".", []structuredPatchChange{change}, nil)
 	if !removed {
 		t.Fatal("pre-commit hook did not run")
 	}
@@ -909,6 +963,59 @@ func TestStructuredPatchMoveWithMissingSourceIsRefusedBeforePublishing(t *testin
 	}
 }
 
+func TestStructuredPatchUpdatePreservesCompetingWriteBeforeRename(t *testing.T) {
+	for _, tc := range []struct {
+		name            string
+		competing       string
+		replaceIdentity bool
+	}{
+		{name: "content changed", competing: "competing writer\n"},
+		{name: "identity changed with same content", competing: "planned\n", replaceIdentity: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			root := t.TempDir()
+			targetPath := filepath.Join(root, "file.txt")
+			writeTestFile(t, targetPath, "planned\n")
+			patch := "*** Begin Patch\n*** Update File: file.txt\n@@\n-planned\n+patched\n*** End Patch\n"
+			hookRan := false
+			var competingInfo os.FileInfo
+			structuredPatchBeforeRename = func(change structuredPatchChange) {
+				if tc.replaceIdentity {
+					tempPath := filepath.Join(root, "competing.tmp")
+					writeTestFile(t, tempPath, tc.competing)
+					if err := os.Rename(tempPath, targetPath); err != nil {
+						t.Fatal(err)
+					}
+				} else if err := os.WriteFile(targetPath, []byte(tc.competing), 0o644); err != nil {
+					t.Fatal(err)
+				}
+				var err error
+				competingInfo, err = os.Stat(targetPath)
+				if err != nil {
+					t.Fatal(err)
+				}
+				hookRan = true
+			}
+			t.Cleanup(func() { structuredPatchBeforeRename = nil })
+
+			result := NewScopedApplyPatchTool(root, nil).Run(context.Background(), map[string]any{"patch": patch})
+			if !hookRan {
+				t.Fatal("pre-rename hook did not run")
+			}
+			if result.Status != StatusError || len(result.ChangedFiles) != 0 || len(result.FileDiffs) != 0 {
+				t.Fatalf("raced update = status=%s changed=%#v diffs=%#v output=%q", result.Status, result.ChangedFiles, result.FileDiffs, result.Output)
+			}
+			if got := mustReadTestFile(t, targetPath); got != tc.competing {
+				t.Fatalf("raced update overwrote competing content: %q", got)
+			}
+			finalInfo, err := os.Stat(targetPath)
+			if err != nil || !os.SameFile(competingInfo, finalInfo) {
+				t.Fatalf("raced update replaced the competing file identity: %v", err)
+			}
+		})
+	}
+}
+
 func TestStructuredPatchCreateOnlyFallsBackWhenHardLinksUnsupported(t *testing.T) {
 	root := t.TempDir()
 	workspace, err := os.OpenRoot(root)
@@ -978,6 +1085,45 @@ func TestStructuredPatchCopyFailureReportsSurvivingPartialTarget(t *testing.T) {
 	}
 }
 
+func TestIncompleteStructuredPatchNoReplaceWriteReportsOnlyVerifiedTarget(t *testing.T) {
+	for name, content := range map[string]string{
+		"complete publication": "complete content\n",
+		"partial publication":  "partial",
+	} {
+		t.Run(name, func(t *testing.T) {
+			root := t.TempDir()
+			workspace, err := os.OpenRoot(root)
+			if err != nil {
+				t.Fatal(err)
+			}
+			defer workspace.Close()
+			targetPath := filepath.Join(root, "target.txt")
+			writeTestFile(t, targetPath, content)
+			change := structuredPatchChange{
+				kind: structuredPatchAdd,
+				to: structuredPatchTarget{
+					requested: "target.txt",
+					relative:  "target.txt",
+					absolute:  targetPath,
+				},
+				after: "complete content\n",
+				mode:  0o644,
+			}
+
+			outcome := incompleteStructuredPatchWrite(workspace, change, true)
+			if content == change.after {
+				if len(outcome.completed) != 1 || outcome.completed[0].kind != structuredPatchAdd || len(outcome.incompletePaths) != 0 {
+					t.Fatalf("verified publication outcome = %#v", outcome)
+				}
+				return
+			}
+			if len(outcome.completed) != 0 || !slices.Equal(outcome.incompletePaths, []string{"target.txt"}) {
+				t.Fatalf("partial publication outcome = %#v", outcome)
+			}
+		})
+	}
+}
+
 func TestStructuredPatchPartialFailureLeavesCompletedChangeAndClearsTrackedState(t *testing.T) {
 	root := t.TempDir()
 	trackedPath := filepath.Join(root, "tracked.txt")
@@ -1017,7 +1163,7 @@ func TestStructuredPatchPartialFailureLeavesCompletedChangeAndClearsTrackedState
 		},
 	}
 
-	err = applyStructuredPatchChanges(workspace, changes, tracker)
+	_, err = applyStructuredPatchChanges(workspace, ".", changes, tracker)
 	if err == nil || !strings.Contains(err.Error(), "partially applied") {
 		t.Fatalf("second change = %v, want partial-application error", err)
 	}

internal/tui/attachment_preview.go

@@ -24,7 +24,7 @@ func (m model) attachmentThumbnailVisible(width int) bool {
 	}
 	if m.pendingPermission != nil || m.pendingAskUser != nil || m.pendingSpecReview != nil ||
 		m.providerWizard != nil || m.mcpAddWizard != nil || m.mcpManager != nil || m.picker != nil ||
-		m.sttKeyPrompt != nil || m.renamePrompt != nil || m.setup.visible || m.helpOverlay || m.leaderHelpOverlay {
+		m.sttKeyPrompt != nil || m.renamePrompt != nil || m.terminalAttach != nil || m.setup.visible || m.helpOverlay || m.leaderHelpOverlay {
 		return false
 	}
 	for index := 0; index < m.attachmentThumbnailSlots(width); index++ {

internal/tui/background_terminals.go

@@ -6,6 +6,8 @@ import (
 	"strings"
 	"time"
 
+	tea "charm.land/bubbletea/v2"
+
 	"github.com/Gitlawb/zero/internal/tools"
 )
 
@@ -30,15 +32,21 @@ func (m model) backgroundTerminalSessions() []tools.ExecSessionSnapshot {
 }
 
 func (m model) backgroundTerminalSummary() string {
-	count := len(m.backgroundTerminalSessions())
-	if count == 0 {
+	sessions := m.backgroundTerminalSessions()
+	if len(sessions) == 0 {
 		return ""
 	}
 	plural := ""
-	if count != 1 {
+	if len(sessions) != 1 {
 		plural = "s"
 	}
-	return fmt.Sprintf("%d background terminal%s running · /ps to view · /stop to close", count, plural)
+	summary := fmt.Sprintf("%d background terminal%s running · /ps to view · /stop to close", len(sessions), plural)
+	for _, session := range sessions {
+		if session.TTY {
+			return summary + " · /attach to type into it"
+		}
+	}
+	return summary
 }
 
 func (m model) stopAllBackgroundTerminalSessions() []int {
@@ -71,6 +79,12 @@ func (m model) backgroundTerminalsText() string {
 		Rows:  rows,
 	}}
 	card.Actions = []string{"/stop <session_id>", "/stop"}
+	for _, session := range sessions {
+		if session.TTY {
+			card.Actions = append([]string{"/attach <session_id>"}, card.Actions...)
+			break
+		}
+	}
 	return renderCommandCardTranscript(card)
 }
 
@@ -112,6 +126,82 @@ func (m model) stopBackgroundTerminalsText(input string) string {
 	return renderStopBackgroundTerminalsCard([]int{id}, "")
 }
 
+// attachTerminalCommand implements /attach: with an explicit session id it
+// validates and opens the attach overlay; bare, it picks the one interactive
+// session or lists the choices.
+func (m model) attachTerminalCommand(input string) (model, tea.Cmd) {
+	controller, ok := m.execSessionController()
+	if !ok {
+		m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: renderCommandCardTranscript(commandCard{
+			Title:   "Background Terminals",
+			Summary: []string{"unavailable"},
+			Sections: []commandCardSection{{
+				Rows: []commandRow{{Text: "exec_command is not registered."}},
+			}},
+		})})
+		return m, nil
+	}
+	// The overlay composites into the main transcript viewport; in a view that
+	// replaces it (subchat, detailed transcript, another overlay) it would
+	// capture keystrokes while invisible, so refuse to open there.
+	if !m.terminalAttachCanOpen() {
+		return m.showTransientNoticeInline("Leave the current view first", transientNoticeInfo), nil
+	}
+	input = strings.TrimSpace(input)
+	if input != "" {
+		id, err := strconv.Atoi(input)
+		if err != nil || id <= 0 {
+			return m.appendAttachCard("invalid session id", "Usage: /attach [session_id]"), nil
+		}
+		snapshot, found := controller.ExecSession(id)
+		if !found {
+			return m.appendAttachCard("not found", fmt.Sprintf("No running terminal session %d.", id)), nil
+		}
+		if !snapshot.TTY {
+			return m.appendAttachCard("not interactive", fmt.Sprintf("Session %d has no terminal — it was started without tty:true (or this platform has no PTY), so it can't take input. Use /stop %d to end it.", id, id)), nil
+		}
+		return m.openTerminalAttach(id)
+	}
+	var interactive []tools.ExecSessionSnapshot
+	for _, session := range controller.ExecSessions() {
+		if session.TTY {
+			interactive = append(interactive, session)
+		}
+	}
+	switch len(interactive) {
+	case 0:
+		return m.showTransientNoticeInline("No interactive terminal sessions running.", transientNoticeInfo), nil
+	case 1:
+		return m.openTerminalAttach(interactive[0].ID)
+	}
+	rows := make([]commandRow, 0, len(interactive))
+	now := m.now()
+	for _, session := range interactive {
+		rows = append(rows, commandRow{Text: formatBackgroundTerminalRow(session, now)})
+	}
+	m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: renderCommandCardTranscript(commandCard{
+		Title:   "Background Terminals",
+		Summary: []string{fmt.Sprintf("%d interactive sessions", len(interactive))},
+		Sections: []commandCardSection{{
+			Title: "running",
+			Rows:  rows,
+		}},
+		Actions: []string{"/attach <session_id>"},
+	})})
+	return m, nil
+}
+
+func (m model) appendAttachCard(summary string, text string) model {
+	m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: renderCommandCardTranscript(commandCard{
+		Title:   "Background Terminals",
+		Summary: []string{summary},
+		Sections: []commandCardSection{{
+			Rows: []commandRow{{Text: text}},
+		}},
+	})})
+	return m
+}
+
 func renderStopBackgroundTerminalsCard(stopped []int, note string) string {
 	card := commandCard{Title: "Background Terminals"}
 	if len(stopped) == 0 {

internal/tui/background_terminals_test.go

@@ -6,6 +6,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/Gitlawb/zero/internal/execution"
 	"github.com/Gitlawb/zero/internal/tools"
 )
 
@@ -13,6 +14,11 @@ type fakeExecSessionTool struct {
 	sessions []tools.ExecSessionSnapshot
 	stopped  []int
 	stopAll  bool
+	writes   [][]byte
+
+	resizeCalls int
+	resizeCols  int
+	resizeRows  int
 }
 
 func (tool *fakeExecSessionTool) Name() string { return tools.ExecCommandToolName }
@@ -35,6 +41,15 @@ func (tool *fakeExecSessionTool) ExecSessions() []tools.ExecSessionSnapshot {
 	return append([]tools.ExecSessionSnapshot(nil), tool.sessions...)
 }
 
+func (tool *fakeExecSessionTool) ExecSession(id int) (tools.ExecSessionSnapshot, bool) {
+	for _, session := range tool.sessions {
+		if session.ID == id {
+			return session, true
+		}
+	}
+	return tools.ExecSessionSnapshot{}, false
+}
+
 func (tool *fakeExecSessionTool) StopExecSession(id int) bool {
 	for _, session := range tool.sessions {
 		if session.ID == id {
@@ -54,6 +69,35 @@ func (tool *fakeExecSessionTool) StopAllExecSessions() []int {
 	return ids
 }
 
+func (tool *fakeExecSessionTool) WriteExecSessionInput(id int, data []byte) error {
+	for _, session := range tool.sessions {
+		if session.ID != id {
+			continue
+		}
+		if !session.TTY {
+			return execution.ErrProcessStdinDisabled
+		}
+		tool.writes = append(tool.writes, append([]byte(nil), data...))
+		return nil
+	}
+	return execution.ErrProcessNotFound
+}
+
+func (tool *fakeExecSessionTool) ResizeExecSession(id int, cols, rows int) error {
+	for _, session := range tool.sessions {
+		if session.ID != id {
+			continue
+		}
+		if !session.TTY {
+			return execution.ErrProcessStdinDisabled
+		}
+		tool.resizeCalls++
+		tool.resizeCols, tool.resizeRows = cols, rows
+		return nil
+	}
+	return execution.ErrProcessNotFound
+}
+
 func modelWithFakeExecSessions(tool *fakeExecSessionTool, now time.Time) model {
 	registry := tools.NewRegistry()
 	registry.Register(tool)
@@ -127,6 +171,103 @@ func TestStopBackgroundTerminalsTextRejectsInvalidSessionID(t *testing.T) {
 	}
 }
 
+func TestBackgroundTerminalsTextAdvertisesAttachForTTY(t *testing.T) {
+	now := time.Unix(200, 0)
+	m := modelWithFakeExecSessions(&fakeExecSessionTool{
+		sessions: []tools.ExecSessionSnapshot{{
+			ID: 1000, Command: "sudo apt install x", StartedAt: now, Status: "running", TTY: true,
+		}},
+	}, now)
+
+	text := m.backgroundTerminalsText()
+	if !strings.Contains(text, "/attach <session_id>") {
+		t.Fatalf("/ps card should offer /attach for a tty session:\n%s", text)
+	}
+	if summary := m.backgroundTerminalSummary(); !strings.HasSuffix(summary, " · /attach to type into it") {
+		t.Fatalf("summary = %q, want /attach hint", summary)
+	}
+}
+
+func TestAttachCommandNeedsController(t *testing.T) {
+	m := model{now: func() time.Time { return time.Unix(100, 0) }}
+	next, _ := m.attachTerminalCommand("7")
+	if !transcriptContains(next.transcript, "exec_command is not registered.") {
+		t.Fatalf("transcript = %#v", next.transcript)
+	}
+}
+
+func TestAttachCommandExplicitID(t *testing.T) {
+	now := time.Unix(200, 0)
+	tool := &fakeExecSessionTool{
+		sessions: []tools.ExecSessionSnapshot{
+			{ID: 7, TTY: true, Status: "running", Command: "cat", StartedAt: now},
+			{ID: 8, TTY: false, Status: "running", Command: "sleep 30", StartedAt: now},
+		},
+	}
+	m := modelWithFakeExecSessions(tool, now)
+
+	next, cmd := m.attachTerminalCommand("7")
+	if cmd == nil || next.terminalAttach == nil || next.terminalAttach.sessionID != 7 {
+		t.Fatalf("expected attach to session 7, state=%#v cmd=%v", next.terminalAttach, cmd)
+	}
+
+	next, _ = m.attachTerminalCommand("8")
+	if !transcriptContains(next.transcript, "Session 8 has no terminal") {
+		t.Fatalf("non-tty session should be refused: %#v", next.transcript)
+	}
+	next, _ = m.attachTerminalCommand("9")
+	if !transcriptContains(next.transcript, "No running terminal session 9.") {
+		t.Fatalf("missing session should be reported: %#v", next.transcript)
+	}
+	next, _ = m.attachTerminalCommand("abc")
+	if !transcriptContains(next.transcript, "Usage: /attach [session_id]") {
+		t.Fatalf("invalid id should show usage: %#v", next.transcript)
+	}
+}
+
+func TestAttachCommandBarePicksSingleTTY(t *testing.T) {
+	now := time.Unix(200, 0)
+	tool := &fakeExecSessionTool{
+		sessions: []tools.ExecSessionSnapshot{
+			{ID: 7, TTY: true, Status: "running", Command: "cat", StartedAt: now},
+			{ID: 8, TTY: false, Status: "running", Command: "sleep 30", StartedAt: now},
+		},
+	}
+	m := modelWithFakeExecSessions(tool, now)
+
+	next, _ := m.attachTerminalCommand("")
+	if next.terminalAttach == nil || next.terminalAttach.sessionID != 7 {
+		t.Fatalf("bare /attach should pick the only tty session, state=%#v", next.terminalAttach)
+	}
+}
+
+func TestAttachCommandBareNoneOrSeveral(t *testing.T) {
+	now := time.Unix(200, 0)
+	m := modelWithFakeExecSessions(&fakeExecSessionTool{
+		sessions: []tools.ExecSessionSnapshot{
+			{ID: 8, TTY: false, Status: "running", Command: "sleep 30", StartedAt: now},
+		},
+	}, now)
+	next, _ := m.attachTerminalCommand("")
+	if next.terminalAttach != nil || !strings.Contains(next.transientNotice.text, "No interactive terminal sessions running.") {
+		t.Fatalf("bare /attach with no tty sessions: notice=%q state=%#v", next.transientNotice.text, next.terminalAttach)
+	}
+
+	m = modelWithFakeExecSessions(&fakeExecSessionTool{
+		sessions: []tools.ExecSessionSnapshot{
+			{ID: 7, TTY: true, Status: "running", Command: "cat", StartedAt: now},
+			{ID: 9, TTY: true, Status: "running", Command: "top", StartedAt: now},
+		},
+	}, now)
+	next, _ = m.attachTerminalCommand("")
+	if next.terminalAttach != nil {
+		t.Fatal("bare /attach with several tty sessions should list, not attach")
+	}
+	if !transcriptContains(next.transcript, "/attach <session_id>") || !transcriptContains(next.transcript, "cat") || !transcriptContains(next.transcript, "top") {
+		t.Fatalf("expected a choice card listing both sessions: %#v", next.transcript)
+	}
+}
+
 func TestQuitStopsBackgroundTerminals(t *testing.T) {
 	tool := &fakeExecSessionTool{
 		sessions: []tools.ExecSessionSnapshot{{ID: 1000, StartedAt: time.Unix(100, 0), Status: "running"}},

internal/tui/btw.go

@@ -306,6 +306,10 @@ func btwMessageRunID(msg tea.Msg) (int, bool) {
 		return typed.runID, true
 	case toolCallStreamStartMsg:
 		return typed.runID, true
+	case interactiveExecStartMsg:
+		return typed.runID, true
+	case terminalAutoAttachTickMsg:
+		return typed.runID, true
 	case toolCallStreamDeltaMsg:
 		return typed.runID, true
 	case planUpdateMsg:

internal/tui/command_center.go

@@ -8,6 +8,7 @@ import (
 	"strconv"
 	"strings"
 	"time"
+	"unicode"
 
 	tea "charm.land/bubbletea/v2"
 
@@ -365,17 +366,30 @@ func (defaultModelSwitchCompactionPolicy) BeforeModelSwitch(request modelSwitchC
 
 var modelSwitchCompactionGuard modelSwitchCompactionPolicy = defaultModelSwitchCompactionPolicy{}
 
-// sanitizeCardField strips the card protocol's separator bytes from
-// user-controlled values (titles can legally contain anything --session-title
-// was given), so a hostile or accidental \x1f / newline cannot shift fields
-// or leak control characters into the transcript.
+// sanitizeCardField strips the card protocol's separator byte and every
+// control rune from user-controlled values (titles can legally contain
+// anything --session-title was given, and a directory name can legally
+// contain an ESC byte on Unix). Line separators and tabs become spaces so
+// words stay apart; the remaining controls — ESC/CSI/OSC initiators, BEL, BS,
+// VT, NEL, NUL — are dropped outright, since any of them can repaint the
+// terminal or shift cells when the value lands in a rendered row.
 func sanitizeCardField(value string) string {
-	value = strings.ReplaceAll(value, sessionsCardFieldSep, " ")
-	value = strings.ReplaceAll(value, "\n", " ")
-	return strings.ReplaceAll(value, "\x00", "")
+	var out strings.Builder
+	for _, r := range value {
+		switch {
+		case r == '\x1f' || r == '\n' || r == '\r' || r == '\t':
+			out.WriteRune(' ')
+		case unicode.IsControl(r):
+		default:
+			out.WriteRune(r)
+		}
+	}
+	return out.String()
 }
 
-// relativeAge renders an RFC3339 timestamp as a short age ("2h ago"); ""
+// relativeAge renders an RFC3339 timestamp as a short age ("2h ago"), falling
+// back to the month/day this year and the bare date for sessions older than a
+// month, so deep history reads as a calendar date rather than "400d ago"; ""
 // when the timestamp does not parse, so the card simply omits it.
 func relativeAge(timestamp string, now time.Time) string {
 	parsed, err := time.Parse(time.RFC3339, strings.TrimSpace(timestamp))
@@ -385,14 +399,19 @@ func relativeAge(timestamp string, now time.Time) string {
 	age := now.Sub(parsed)
 	switch {
 	case age < time.Minute:
-		return "just now"
+		return "now"
 	case age < time.Hour:
 		return fmt.Sprintf("%dm ago", int(age.Minutes()))
 	case age < 24*time.Hour:
 		return fmt.Sprintf("%dh ago", int(age.Hours()))
-	default:
+	case age <= 30*24*time.Hour:
 		return fmt.Sprintf("%dd ago", int(age.Hours()/24))
 	}
+	parsed, now = parsed.Local(), now.Local()
+	if parsed.Year() == now.Year() {
+		return parsed.Format("Jan _2")
+	}
+	return parsed.Format("2006-01-02")
 }
 
 // handleModelCommand applies a model switch against the ACTIVE provider (the

internal/tui/commands.go

@@ -17,6 +17,7 @@ const (
 	commandPermissions
 	commandPS
 	commandStop
+	commandAttach
 	commandSandboxSetup
 	commandProvider
 	commandModel
@@ -140,6 +141,13 @@ var commandDefinitions = []commandDefinition{
 		description: "Stop running background terminal sessions.",
 		kind:        commandStop,
 	},
+	{
+		name:        "/attach",
+		usage:       "/attach [session_id]",
+		group:       commandGroupRuntime,
+		description: "Type directly into a running interactive terminal session.",
+		kind:        commandAttach,
+	},
 	{
 		name:        "/sandbox-setup",
 		usage:       "/sandbox-setup",

internal/tui/commands_test.go

@@ -977,6 +977,8 @@ func TestParseBackgroundTerminalCommands(t *testing.T) {
 		{input: "/ps", kind: commandPS, text: ""},
 		{input: "/stop", kind: commandStop, text: ""},
 		{input: "/stop 1000", kind: commandStop, text: "1000"},
+		{input: "/attach", kind: commandAttach, text: ""},
+		{input: "/attach 7", kind: commandAttach, text: "7"},
 	}
 	for _, tc := range cases {
 		got := parseCommand(tc.input)

internal/tui/model.go

@@ -253,6 +253,9 @@ type model struct {
 	composerSelection      composerSelectionState
 	dictation              dictationController
 	sttKeyPrompt           *sttKeyPromptState
+	terminalAttach         *terminalAttachState
+	terminalAutoAttach     *terminalAutoAttachState
+	terminalAttachSeen     map[int]bool
 	// plan holds the sticky plan panel state (steps, expansion, timings)
 	// synced from the update_plan tool. See plan_panel.go.
 	plan            planPanelState
@@ -1245,7 +1248,7 @@ func (m *model) stopPRWatcher() {
 func (m model) noBlockingModal() bool {
 	return m.pendingPermission == nil && m.pendingAskUser == nil && m.pendingSpecReview == nil &&
 		m.providerWizard == nil && m.mcpAddWizard == nil && m.mcpManager == nil && m.picker == nil &&
-		m.sttKeyPrompt == nil && m.renamePrompt == nil
+		m.sttKeyPrompt == nil && m.renamePrompt == nil && m.terminalAttach == nil
 }
 
 func (m model) quit() (tea.Model, tea.Cmd) {
@@ -1447,6 +1450,11 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 		}
 		return m, nil
 	case tea.MouseMsg:
+		// Attached to a live terminal: the overlay owns the viewport, so mouse
+		// events go nowhere rather than hitting transcript selection below.
+		if m.terminalAttach != nil {
+			return m, nil
+		}
 		if m.setup.visible {
 			return m.handleSetupMouse(msg)
 		}
@@ -1533,6 +1541,11 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 		}
 		return m.attachClipboardImage(msg.data, msg.mediaType), nil
 	case tea.PasteMsg:
+		// While attached to a live terminal, a paste forwards verbatim to the
+		// PTY stdin — never into the composer or transcript.
+		if m.terminalAttach != nil {
+			return m.handleTerminalAttachPaste(msg.Content)
+		}
 		// A paste into the cloud-STT key prompt fills the key (the common way to
 		// enter an API key), not the composer.
 		if m.sttKeyPrompt != nil {
@@ -1565,6 +1578,20 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 			return m.handleVoiceCaptureRelease()
 		}
 		return m, nil
+	case terminalAttachTickMsg:
+		return m.refreshTerminalAttach()
+	case interactiveExecStartMsg:
+		if msg.runID != m.activeRunID {
+			return m, nil
+		}
+		m.terminalAutoAttach = &terminalAutoAttachState{
+			runID:    msg.runID,
+			known:    msg.known,
+			deadline: m.now().Add(terminalAutoAttachTimeout),
+		}
+		return m, terminalAutoAttachTickCmd(msg.runID)
+	case terminalAutoAttachTickMsg:
+		return m.pollTerminalAutoAttach(msg)
 	case tea.KeyPressMsg:
 		if m.petDragActive {
 			pixelDrag := m.petPixelDrag
@@ -1604,6 +1631,11 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 		if m.sttKeyPrompt != nil {
 			return m.handleSTTKeyPromptKey(msg)
 		}
+		// Attached to a live terminal session: keystrokes (including Ctrl+C,
+		// which maps to 0x03 for the process) go to the PTY until Esc detaches.
+		if m.terminalAttach != nil {
+			return m.handleTerminalAttachKey(msg)
+		}
 		if m.renamePrompt != nil {
 			return m.handleSessionRenameKey(msg)
 		}
@@ -2457,6 +2489,9 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 		// Size the composer so long input scrolls horizontally with the cursor
 		// visible instead of being clipped invisibly past the right edge.
 		m.input.SetWidth(maxInt(20, chatWidth(msg.Width)-14))
+		// An attached terminal fills the viewport, so the PTY tracks the
+		// live size instead of a fixed default.
+		m = m.resizeAttachedTerminalPTY()
 		// The title bar prints once into native scrollback when the inline
 		// renderer is active. In alt-screen mode it stays pinned inside View.
 		if !m.altScreen && !m.headerPrinted && msg.Width > 0 {
@@ -2632,6 +2667,7 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 		}
 		m.runCancel = nil
 		m.activeRunID = 0
+		m.terminalAutoAttach = nil
 		m.plan.frozenAt = m.now() // freeze the plan clock while idle (no run in flight)
 		// A fully successful turn means the task is done. Weaker models often
 		// forget the final update_plan, leaving the panel stuck mid-progress;
@@ -3135,8 +3171,11 @@ func (m model) transcriptView() string {
 	mcpOverlay := m.mcpManagerOverlay(width)
 	pickerOverlay := m.pickerOverlay(width)
 	sttKeyOverlay := m.sttKeyPromptOverlay(width)
+	terminalAttachOverlay := m.terminalAttachOverlay(width)
 	viewportOverlay := ""
 	switch {
+	case terminalAttachOverlay != "":
+		viewportOverlay = terminalAttachOverlay
 	case sttKeyOverlay != "":
 		viewportOverlay = sttKeyOverlay
 	case helpOverlayContent != "":
@@ -3204,6 +3243,13 @@ func (m model) pinnedTitleBar(width int) string {
 
 func (m model) footerView(width int) string {
 	var footer strings.Builder
+	// An attached terminal owns the keyboard and the viewport; the composer is
+	// inert, so like the ask_user and permission modals only the status line
+	// renders. Frame math routes through footerView, so this also shrinks the
+	// footer rect the overlay's row budget is derived from.
+	if m.terminalAttach != nil {
+		return m.footerStatusLine(width)
+	}
 	if m.renamePrompt != nil {
 		footer.WriteString(m.sessionRenamePromptView(width))
 		footer.WriteString("\n")
@@ -4739,6 +4785,8 @@ func (m model) dispatchCommand(command parsedCommand) (tea.Model, tea.Cmd) {
 	case commandStop:
 		m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: m.stopBackgroundTerminalsText(command.text)})
 		return m, nil
+	case commandAttach:
+		return m.attachTerminalCommand(command.text)
 	case commandSandboxSetup:
 		return m.startSandboxSetupCommand(command.text)
 	case commandProvider:
@@ -5240,6 +5288,7 @@ func (m model) beginRun(cancel context.CancelFunc) model {
 	}
 	m.runID++
 	m.activeRunID = m.runID
+	m.terminalAutoAttach = nil
 	m.runCancel = cancel
 	m.pending = true
 	// Clear per-run tracking state so stale specialists and plans from the
@@ -5397,6 +5446,7 @@ func (m *model) cancelRun() {
 	m.pending = false
 	m.runCancel = nil
 	m.activeRunID = 0
+	m.terminalAutoAttach = nil
 	m.cancelConfirmActive = false // whatever path got here, there's nothing left to confirm cancelling
 	m.plan.frozenAt = m.now()     // freeze the plan clock while idle (no run in flight)
 	m.pendingPermission = nil
@@ -5760,6 +5810,18 @@ func (m model) runAgentWithOptions(runID int, runCtx context.Context, prompt str
 			// live status. The child session ID is not known yet (it's created
 			// inside the executor), so we use the tool call ID as a temporary
 			// key and reconcile on the result.
+			// A tty exec_command wants the attach overlay: the session registers
+			// with the process manager inside the tool's Run, so the update loop
+			// polls for it on a tick.
+			if call.Name == tools.ExecCommandToolName && execCallWantsTTY(call.Arguments) && m.runtimeMessageSink != nil {
+				known := map[int]bool{}
+				if controller, ok := m.execSessionController(); ok {
+					for _, session := range controller.ExecSessions() {
+						known[session.ID] = true
+					}
+				}
+				m.runtimeMessageSink(interactiveExecStartMsg{runID: runID, known: known})
+			}
 			if call.Name == "Task" {
 				name, desc := parseTaskCallArgs(call.Arguments)
 				if m.runtimeMessageSink != nil {

internal/tui/model_test.go

@@ -1087,16 +1087,16 @@ func TestResumeCommandListsRecentSessions(t *testing.T) {
 }
 
 func TestSessionPickerLabelAlignsTitles(t *testing.T) {
-	today := sessionPickerLabel("20:47:50", "Today title")
-	older := sessionPickerLabel("Jul 24 10:47", "Older title")
+	recent := sessionPickerLabel("2h ago", "Recent title")
+	older := sessionPickerLabel("2006-01-02", "Older title")
 
-	todayColumn := strings.Index(today, "Today title")
+	recentColumn := strings.Index(recent, "Recent title")
 	olderColumn := strings.Index(older, "Older title")
-	if todayColumn < 0 || olderColumn < 0 {
-		t.Fatalf("sessionPickerLabel omitted a title: today=%q older=%q", today, older)
+	if recentColumn < 0 || olderColumn < 0 {
+		t.Fatalf("sessionPickerLabel omitted a title: recent=%q older=%q", recent, older)
 	}
-	if todayColumn != olderColumn {
-		t.Fatalf("title columns differ: today=%d (%q), older=%d (%q)", todayColumn, today, olderColumn, older)
+	if recentColumn != olderColumn {
+		t.Fatalf("title columns differ: recent=%d (%q), older=%d (%q)", recentColumn, recent, olderColumn, older)
 	}
 }
 

internal/tui/mouse.go

@@ -299,7 +299,7 @@ func (m model) wantsMouseCapture() bool {
 	if m.mouseReleased {
 		return false // user released the mouse for native text selection/copy
 	}
-	return m.altScreen && (m.setupWantsMouseCapture() || m.chatWantsMouseCapture() || m.providerWizard != nil || m.mcpAddWizard != nil || m.mcpManager != nil || m.picker != nil || m.suggestionsActive())
+	return m.altScreen && (m.setupWantsMouseCapture() || m.chatWantsMouseCapture() || m.providerWizard != nil || m.mcpAddWizard != nil || m.mcpManager != nil || m.picker != nil || m.terminalAttach != nil || m.suggestionsActive())
 }
 
 func (m model) setupWantsMouseCapture() bool {
@@ -513,10 +513,11 @@ func (m *model) selectGenericPickerAtMouse(msg tea.MouseMsg) (mouseSelectionTarg
 			return mouseSelectionTarget{}, false
 		}
 	}
-	maxVisible := minInt(pickerOverlayMaxVisible, len(m.picker.items))
+	maxVisible := pickerMaxVisible(m.picker, width)
 	selected := clampInt(m.picker.selected, 0, len(m.picker.items)-1)
 	start := selectableListStart(len(m.picker.items), maxVisible, selected)
 	visible := m.picker.items[start : start+maxVisible]
+	details := pickerShowsDetails(m.picker, width)
 	// y=0 titled top border, y=1 search line, y=2 separator; rows begin at y=3.
 	line := 3
 	lastGroup := ""
@@ -528,12 +529,18 @@ func (m *model) selectGenericPickerAtMouse(msg tea.MouseMsg) (mouseSelectionTarg
 			line++
 			lastGroup = item.Group
 		}
-		if hit.y == line {
+		// A rendered detail line belongs to its item: a click anywhere on the
+		// two-line block selects the same row.
+		rowLines := 1
+		if details && item.Detail != "" {
+			rowLines = 2
+		}
+		if hit.y >= line && hit.y < line+rowLines {
 			index := start + offset
 			m.picker.selected = index
 			return mouseSelectionTarget{Scope: "picker", Kind: int(m.picker.kind), Value: item.Value, Index: index}, true
 		}
-		line++
+		line += rowLines
 	}
 	return mouseSelectionTarget{}, false
 }

internal/tui/pets.go

@@ -411,7 +411,7 @@ func (m model) petLayoutActive() bool {
 func (m model) petObscuringModalActive() bool {
 	return m.pendingAskUser != nil || m.pendingSpecReview != nil || m.providerWizard != nil ||
 		m.mcpAddWizard != nil || m.mcpManager != nil || m.picker != nil ||
-		m.sttKeyPrompt != nil || m.renamePrompt != nil
+		m.sttKeyPrompt != nil || m.renamePrompt != nil || m.terminalAttach != nil
 }
 
 func (m model) petComposerReservedColumns(width int) int {

internal/tui/picker.go

@@ -34,12 +34,15 @@ const (
 // pickerItem is one selectable row: Label is shown, Value is passed to the
 // underlying command handler when chosen. Meta is the optional right-aligned
 // readout (ctx window · capabilities); the dot flags mark provider locality
-// for model rows (accent = remote, blue = local).
+// for model rows (accent = remote, blue = local). Detail is an optional faint
+// second line under the row (project · model · size for sessions), rendered
+// only on medium-and-wider tiers where the extra line reads cleanly.
 type pickerItem struct {
 	Group    string
 	Label    string
 	Value    string
 	Meta     string
+	Detail   string
 	Provider string // display tag (catalog id / locality)
 	// OwnerProvider is the saved provider profile name a model belongs to, so the
 	// /model picker can switch providers when a model from a non-active provider is
@@ -167,7 +170,7 @@ func (p *commandPicker) applyQuery() {
 // 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}, " "))
+	hay := strings.ToLower(strings.Join([]string{item.Group, item.Label, item.Value, item.Meta, item.Detail}, " "))
 	switch {
 	case label == query:
 		return 0, true

internal/tui/rendering_lime_test.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 	"testing"
 	"time"
+	"unicode"
 
 	"charm.land/lipgloss/v2"
 	"github.com/charmbracelet/colorprofile"
@@ -1973,8 +1974,27 @@ func TestPermissionCollapseIsRunScoped(t *testing.T) {
 }
 
 func TestSessionsCardFieldsAreSanitized(t *testing.T) {
-	if got := sanitizeCardField("evil\x1ftitle\nwith\x00bytes"); strings.ContainsAny(got, "\x1f\n\x00") {
-		t.Fatalf("sanitizeCardField left separator bytes: %q", got)
+	inputs := []string{
+		"evil\x1ftitle",
+		"line\nbreak",
+		"line\rbreak",
+		"nul\x00byte",
+		"esc\x1b[31mred",
+		"csi\x1b[2J\x1b[H",
+		"osc\x1b]0;pwned\a",
+		"bell\aring",
+		"back\bspace",
+		"tab\there",
+		"vert\vtab",
+		"nel\u0085here",
+	}
+	for _, input := range inputs {
+		got := sanitizeCardField(input)
+		for _, r := range got {
+			if unicode.IsControl(r) {
+				t.Fatalf("sanitizeCardField(%q) left control rune %q in %q", input, r, got)
+			}
+		}
 	}
 }
 

internal/tui/session.go

@@ -8,7 +8,6 @@ import (
 	"path/filepath"
 	"runtime"
 	"strings"
-	"time"
 
 	"github.com/Gitlawb/zero/internal/agent"
 	"github.com/Gitlawb/zero/internal/execution"
@@ -360,28 +359,10 @@ func (m model) formatResumeSummary(session sessions.Metadata, eventCount int) st
 	})
 }
 
-// sessionWhen formats a session's RFC3339 timestamp for the picker: a precise
-// clock time (with seconds) for today so same-minute sessions stay distinct, the
-// month/day and time earlier this year, else the date. Empty on a parse error.
-func sessionWhen(timestamp string, now time.Time) string {
-	parsed, err := time.Parse(time.RFC3339, strings.TrimSpace(timestamp))
-	if err != nil {
-		return ""
-	}
-	parsed, now = parsed.Local(), now.Local()
-	switch {
-	case parsed.Year() == now.Year() && parsed.YearDay() == now.YearDay():
-		return parsed.Format("15:04:05")
-	case parsed.Year() == now.Year():
-		return parsed.Format("Jan _2 15:04")
-	default:
-		return parsed.Format("2006-01-02")
-	}
-}
-
 // newSessionPicker builds the interactive /resume picker (mirrors /model & /provider):
-// one row per resumable session — title (Label) + id and relative age (Meta). Returns
-// nil when there are no resumable sessions so the caller falls back to the text path.
+// one row per resumable session — age + title (Label), session id (Value), and a
+// project/model/size line (Detail). Returns nil when there are no resumable
+// sessions so the caller falls back to the text path.
 func (m model) newSessionPicker() *commandPicker {
 	if m.sessionStore == nil {
 		return nil
@@ -414,13 +395,17 @@ func (m model) newSessionPicker() *commandPicker {
 		// Lead with a fixed-width timestamp so titles form one scannable column.
 		// The raw id remains the selection/search value but stays out of the row:
 		// rendering it consumed half the picker and truncated the useful title.
-		label := displayValue(meta.Title, "untitled")
-		if when := sessionWhen(meta.UpdatedAt, now); when != "" {
+		// Session metadata is persisted, user-controlled text — a title from
+		// --session-title or /rename can legally contain newlines, which would
+		// break the picker's fixed row geometry.
+		label := displayValue(sanitizeCardField(meta.Title), "untitled")
+		if when := relativeAge(meta.UpdatedAt, now); when != "" {
 			label = sessionPickerLabel(when, label)
 		}
 		items = append(items, pickerItem{
-			Label: label,
-			Value: meta.SessionID,
+			Label:  label,
+			Value:  meta.SessionID,
+			Detail: m.sessionPickerDetail(meta),
 		})
 	}
 	if len(items) == 0 {
@@ -435,12 +420,45 @@ func (m model) newSessionPicker() *commandPicker {
 	}
 }
 
-const sessionPickerTimeWidth = len("Jan 02 15:04")
+const sessionPickerTimeWidth = len("2006-01-02")
 
 func sessionPickerLabel(when, title string) string {
 	return fmt.Sprintf("%-*s  %s", sessionPickerTimeWidth, when, title)
 }
 
+// sessionPickerDetail composes the faint second line under a /resume row:
+// the session's project directory (~/-contracted), the model it ran on, and a
+// short status chip when the session is not a plain mainline run (forks,
+// tagged sessions such as btw side-chats). Missing fields are simply omitted —
+// the picker is workspace-scoped, so the project column is a confirmation,
+// not a disambiguator.
+func (m model) sessionPickerDetail(meta sessions.Metadata) string {
+	parts := make([]string, 0, 3)
+	if project := displayPath(m.cwd, meta.Cwd); project != "" {
+		parts = append(parts, project)
+	}
+	if modelID := strings.TrimSpace(meta.ModelID); modelID != "" {
+		parts = append(parts, modelID)
+	}
+	if status := sessionPickerStatus(meta); status != "" {
+		parts = append(parts, status)
+	}
+	return sanitizeCardField(strings.Join(parts, " · "))
+}
+
+// sessionPickerStatus is the concise status chip for a /resume row: an
+// explicit tag when the session carries one, otherwise a marker for forked
+// sessions. Plain mainline sessions get none — their shape is the default.
+func sessionPickerStatus(meta sessions.Metadata) string {
+	if tag := strings.TrimSpace(meta.Tag); tag != "" {
+		return tag
+	}
+	if meta.SessionKind == sessions.SessionKindFork {
+		return "fork"
+	}
+	return ""
+}
+
 // sessionHasResumableContent reports whether a session has anything worth
 // 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

internal/tui/session_test.go

@@ -9,6 +9,7 @@ import (
 	"sync/atomic"
 	"testing"
 	"time"
+	"unicode"
 
 	tea "charm.land/bubbletea/v2"
 
@@ -300,7 +301,7 @@ func TestPromptSubmitPersistsPermissionSessionEvents(t *testing.T) {
 		// not one of the 4 semantic steps this test drives — process them so the
 		// model state advances, but don't count them toward the budget.
 		switch runtimeMsg.(type) {
-		case toolCallStreamStartMsg, toolCallStreamDeltaMsg:
+		case toolCallStreamStartMsg, toolCallStreamDeltaMsg, interactiveExecStartMsg:
 			continue
 		}
 		received++
@@ -407,7 +408,7 @@ func TestPermissionWaitDoesNotCountTowardTurnElapsed(t *testing.T) {
 		updated, _ = next.Update(runtimeMsg)
 		next = updated.(model)
 		switch runtimeMsg.(type) {
-		case toolCallStreamStartMsg, toolCallStreamDeltaMsg:
+		case toolCallStreamStartMsg, toolCallStreamDeltaMsg, interactiveExecStartMsg:
 			continue
 		case permissionRequestMsg:
 			clockNanos.Store(base.Add(92 * time.Second).UnixNano())
@@ -1249,3 +1250,188 @@ func assertPayloadFieldContains(t *testing.T, event sessions.Event, key string,
 		t.Fatalf("expected payload %s to contain %q, got %#v in %#v", key, want, payload[key], payload)
 	}
 }
+
+func TestRelativeAgeFormatsLastActivity(t *testing.T) {
+	now := time.Date(2026, 9, 12, 15, 0, 0, 0, time.UTC)
+	cases := []struct {
+		name string
+		ts   time.Time
+		want string
+	}{
+		{"just now", now.Add(-10 * time.Second), "now"},
+		{"slight clock skew", now.Add(30 * time.Second), "now"},
+		{"minutes", now.Add(-42 * time.Minute), "42m ago"},
+		{"hours", now.Add(-3 * time.Hour), "3h ago"},
+		{"days", now.Add(-12 * 24 * time.Hour), "12d ago"},
+		{"exactly one month", now.Add(-30 * 24 * time.Hour), "30d ago"},
+		{"this year", time.Date(2026, 1, 5, 9, 0, 0, 0, time.UTC), "Jan  5"},
+		{"last year", time.Date(2025, 6, 1, 0, 0, 0, 0, time.UTC), "2025-06-01"},
+	}
+	for _, tc := range cases {
+		if got := relativeAge(tc.ts.Format(time.RFC3339), now); got != tc.want {
+			t.Errorf("%s: sessionAge = %q, want %q", tc.name, got, tc.want)
+		}
+	}
+	if got := relativeAge("not-a-time", now); got != "" {
+		t.Errorf("unparseable timestamp = %q, want empty", got)
+	}
+	if got := relativeAge("", now); got != "" {
+		t.Errorf("empty timestamp = %q, want empty", got)
+	}
+}
+
+func TestSessionPickerDetailComposesProjectAndModel(t *testing.T) {
+	m := model{cwd: "/repo"}
+	detail := m.sessionPickerDetail(sessions.Metadata{
+		Title:   "work",
+		Cwd:     "/repo",
+		ModelID: "gpt-5",
+	})
+	for _, want := range []string{"/repo", "gpt-5"} {
+		if !strings.Contains(detail, want) {
+			t.Fatalf("detail %q missing %q", detail, want)
+		}
+	}
+	// Missing fields are omitted rather than rendered as empty segments.
+	if sparse := m.sessionPickerDetail(sessions.Metadata{Title: "bare"}); sparse != "" {
+		t.Fatalf("empty metadata should produce no detail line, got %q", sparse)
+	}
+}
+
+func TestSessionPickerDetailStatusChips(t *testing.T) {
+	m := model{}
+	if got := m.sessionPickerDetail(sessions.Metadata{SessionKind: sessions.SessionKindFork}); !strings.Contains(got, "fork") {
+		t.Fatalf("fork session detail %q should carry the fork chip", got)
+	}
+	if got := m.sessionPickerDetail(sessions.Metadata{Tag: "btw"}); !strings.Contains(got, "btw") {
+		t.Fatalf("tagged session detail %q should carry the tag", got)
+	}
+	if got := m.sessionPickerDetail(sessions.Metadata{Title: "plain"}); got != "" {
+		t.Fatalf("plain session detail %q should have no status chip", got)
+	}
+}
+
+func TestResumePickerDetailRendersOnlyAtMediumWidth(t *testing.T) {
+	store := testSessionStore(t)
+	sess, err := store.Create(sessions.CreateInput{Title: "Detail row", ModelID: "gpt-5-pickertest", Provider: "openai"})
+	if err != nil {
+		t.Fatalf("Create returned error: %v", err)
+	}
+	if _, err := store.AppendEvent(sess.SessionID, sessions.AppendEventInput{
+		Type:    sessions.EventMessage,
+		Payload: map[string]any{"role": "assistant", "content": "hi"},
+	}); err != nil {
+		t.Fatalf("AppendEvent returned error: %v", err)
+	}
+	m := newModel(context.Background(), Options{SessionStore: store})
+	m.input.SetValue("/resume")
+	updated, _ := m.Update(testKey(tea.KeyEnter))
+	next := updated.(model)
+	if next.picker == nil || next.picker.kind != pickerSession {
+		t.Fatalf("expected /resume to open the session picker, got %#v", next.picker)
+	}
+
+	next.width = 120
+	if wide := viewString(next.View()); !strings.Contains(wide, "gpt-5-pickertest") {
+		t.Fatalf("wide picker should render the detail line with the model:\n%s", wide)
+	}
+	next.width = 60
+	if narrow := viewString(next.View()); strings.Contains(narrow, "gpt-5-pickertest") {
+		t.Fatalf("narrow picker should keep the single-line fallback:\n%s", narrow)
+	}
+}
+
+func TestResumePickerFilterMatchesDetailFields(t *testing.T) {
+	store := testSessionStore(t)
+	mk := func(title, modelID string) {
+		sess, err := store.Create(sessions.CreateInput{Title: title, ModelID: modelID, Provider: "openai"})
+		if err != nil {
+			t.Fatalf("Create %q returned error: %v", title, err)
+		}
+		if _, err := store.AppendEvent(sess.SessionID, sessions.AppendEventInput{
+			Type:    sessions.EventMessage,
+			Payload: map[string]any{"role": "assistant", "content": "hi"},
+		}); err != nil {
+			t.Fatalf("AppendEvent %q returned error: %v", title, err)
+		}
+	}
+	mk("alpha", "gpt-5")
+	mk("beta", "claude-sonnet-4.5")
+
+	m := newModel(context.Background(), Options{SessionStore: store})
+	m.input.SetValue("/resume")
+	updated, _ := m.Update(testKey(tea.KeyEnter))
+	next := updated.(model)
+	if next.picker == nil {
+		t.Fatal("expected /resume to open the session picker")
+	}
+	// The model id lives only on the detail line; it must still filter rows.
+	next.picker.query = "claude-sonnet"
+	next.picker.applyQuery()
+	if len(next.picker.items) != 1 || !strings.Contains(next.picker.items[0].Label, "beta") {
+		t.Fatalf("filter by model should keep only the matching session, got %#v", next.picker.items)
+	}
+}
+
+func TestResumePickerSanitizesMultilineMetadata(t *testing.T) {
+	// Persisted session metadata is user-controlled: a title or model id can
+	// legally contain newlines, which must not break the picker's fixed
+	// one-or-two-line row geometry (a stray line shifts every row below it and
+	// misaligns mouse hit-testing).
+	store := testSessionStore(t)
+	sess, err := store.Create(sessions.CreateInput{
+		Title:   "alpha\nbravo",
+		ModelID: "gpt\x1b[31m5",
+		Cwd:     "/repo",
+		Tag:     "side\x1b]0;x\achat",
+	})
+	if err != nil {
+		t.Fatalf("Create returned error: %v", err)
+	}
+	if _, err := store.AppendEvent(sess.SessionID, sessions.AppendEventInput{
+		Type:    sessions.EventMessage,
+		Payload: map[string]any{"role": "assistant", "content": "hi"},
+	}); err != nil {
+		t.Fatalf("AppendEvent returned error: %v", err)
+	}
+	m := newModel(context.Background(), Options{SessionStore: store, Cwd: "/repo"})
+	m.input.SetValue("/resume")
+	updated, _ := m.Update(testKey(tea.KeyEnter))
+	next := updated.(model)
+	if next.picker == nil || len(next.picker.items) != 1 {
+		t.Fatalf("expected one picker item, got %#v", next.picker)
+	}
+	item := next.picker.items[0]
+	for _, r := range item.Label + item.Detail {
+		if unicode.IsControl(r) {
+			t.Fatalf("picker row leaked control rune %q: label=%q detail=%q", r, item.Label, item.Detail)
+		}
+	}
+}
+
+func TestGenericPickerMouseSelectsItemFromDetailLine(t *testing.T) {
+	m := mouseTestModel()
+	m.width = 120
+	m.picker = &commandPicker{
+		kind: pickerSession,
+		items: []pickerItem{
+			{Label: "one", Value: "s1", Detail: "meta one"},
+			{Label: "two", Value: "s2", Detail: "meta two"},
+		},
+	}
+	m.picker.allItems = append([]pickerItem{}, m.picker.items...)
+
+	width := chatWidth(m.width)
+	overlay := m.pickerOverlay(width)
+	rect := m.overlayMouseRect(len(viewLines(overlay)), width)
+	// Rows begin at y=3 inside the overlay; item 1's detail line is y=6.
+	// Click near the horizontal middle so the point lands inside the
+	// centered overlay block.
+	target, ok := m.selectGenericPickerAtMouse(testMouseClick(tea.MouseLeft, width/2, rect.y+6))
+	if !ok {
+		t.Fatal("click on a detail line should select its item")
+	}
+	if target.Value != "s2" {
+		t.Fatalf("detail-line click selected %q, want s2", target.Value)
+	}
+}

internal/tui/terminal_attach.go

@@ -0,0 +1,446 @@
+package tui
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+	"unicode"
+
+	tea "charm.land/bubbletea/v2"
+	"charm.land/lipgloss/v2"
+	"github.com/charmbracelet/x/ansi"
+
+	"github.com/Gitlawb/zero/internal/execution"
+)
+
+// terminalAttachState is the modal "attach to a live terminal" overlay: while
+// it is set, keystrokes are forwarded verbatim to the session's PTY stdin and
+// the overlay shows a rolling tail of its output. The bytes the user types are
+// never inspected, stored, or logged — the PTY's own line discipline (e.g.
+// sudo's no-echo prompt) handles masking.
+type terminalAttachState struct {
+	sessionID      int
+	command        string
+	output         string
+	ptyCols        int
+	ptyRows        int
+	bracketedPaste bool
+}
+
+const terminalAttachTickInterval = 100 * time.Millisecond
+
+type terminalAttachTickMsg struct{}
+
+func terminalAttachTickCmd() tea.Cmd {
+	return tea.Tick(terminalAttachTickInterval, func(time.Time) tea.Msg {
+		return terminalAttachTickMsg{}
+	})
+}
+
+// terminalAutoAttachState watches a run for a brand-new tty exec session so the
+// attach overlay can open on it without the user typing /attach.
+type terminalAutoAttachState struct {
+	runID    int
+	known    map[int]bool
+	deadline time.Time
+}
+
+const terminalAutoAttachTimeout = 60 * time.Second
+
+// interactiveExecStartMsg signals that the active run just invoked exec_command
+// with tty:true; the session registers with the process manager moments later,
+// so the tick polls for it. The baseline session set is captured in OnToolCall,
+// before the tool runs: Program.Send only queues the message, so snapshotting
+// in Update could already see the new session and exclude it as pre-existing.
+type interactiveExecStartMsg struct {
+	runID int
+	known map[int]bool
+}
+
+// The tick carries the run it belongs to so the /btw router can deliver it to
+// the hidden parent model instead of dropping it on the visible side model.
+type terminalAutoAttachTickMsg struct {
+	runID int
+}
+
+func terminalAutoAttachTickCmd(runID int) tea.Cmd {
+	return tea.Tick(terminalAttachTickInterval, func(time.Time) tea.Msg {
+		return terminalAutoAttachTickMsg{runID: runID}
+	})
+}
+
+// execCallWantsTTY reports whether an exec_command tool call's arguments JSON
+// requests a PTY. Malformed JSON means false.
+func execCallWantsTTY(arguments string) bool {
+	var args struct {
+		TTY bool `json:"tty"`
+	}
+	if err := json.Unmarshal([]byte(arguments), &args); err != nil {
+		return false
+	}
+	return args.TTY
+}
+
+// openTerminalAttach attaches to an interactive exec session. Callers check
+// TTY eligibility first; a session that is already gone or exited surfaces as a
+// transient notice instead of an empty overlay.
+func (m model) openTerminalAttach(id int) (model, tea.Cmd) {
+	state := &terminalAttachState{sessionID: id}
+	if controller, ok := m.execSessionController(); ok {
+		snapshot, found := controller.ExecSession(id)
+		switch {
+		case !found:
+			return m.showTransientNoticeInline(fmt.Sprintf("Terminal session %d ended.", id), transientNoticeInfo), nil
+		case snapshot.Status != "running":
+			exitCode := 0
+			if snapshot.ExitCode != nil {
+				exitCode = *snapshot.ExitCode
+			}
+			return m.showTransientNoticeInline(fmt.Sprintf("Terminal session %d finished (exit %d).", id, exitCode), transientNoticeInfo), nil
+		default:
+			state.command = snapshot.Command
+			state.output = snapshot.RecentOutput
+			state.bracketedPaste = bracketedPasteMode(snapshot.RecentOutput, false)
+		}
+	}
+	m.terminalAttach = state
+	if m.terminalAttachSeen == nil {
+		m.terminalAttachSeen = map[int]bool{}
+	}
+	m.terminalAttachSeen[id] = true
+	m.clearSuggestions()
+	m = m.resizeAttachedTerminalPTY()
+	return m, terminalAttachTickCmd()
+}
+
+// resizeAttachedTerminalPTY reports the overlay's output area to the PTY so
+// the session lays out at the size it is actually displayed at. Errors are
+// ignored: platforms without PTY support have nothing to resize.
+func (m model) resizeAttachedTerminalPTY() model {
+	state := m.terminalAttach
+	if state == nil {
+		return m
+	}
+	width := chatWidth(m.width)
+	// The box border and inset take 4 cells; one more is the cursor
+	// reservation, matching the width renderTerminalTail draws at.
+	cols := maxInt(1, width-5)
+	rows := m.terminalAttachViewportRows(width)
+	if cols == state.ptyCols && rows == state.ptyRows {
+		return m
+	}
+	controller, ok := m.execSessionController()
+	if !ok {
+		return m
+	}
+	state.ptyCols, state.ptyRows = cols, rows
+	_ = controller.ResizeExecSession(state.sessionID, cols, rows)
+	return m
+}
+
+// refreshTerminalAttach polls the session snapshot for the overlay tail. When
+// the session exits or disappears the overlay closes itself with a notice;
+// detaching also stops the tick because the handler drops it while
+// terminalAttach is nil.
+func (m model) refreshTerminalAttach() (model, tea.Cmd) {
+	state := m.terminalAttach
+	if state == nil {
+		return m, nil
+	}
+	controller, ok := m.execSessionController()
+	if !ok {
+		m.terminalAttach = nil
+		return m, nil
+	}
+	snapshot, found := controller.ExecSession(state.sessionID)
+	if !found {
+		m.terminalAttach = nil
+		return m.showTransientNoticeInline(fmt.Sprintf("Terminal session %d ended.", state.sessionID), transientNoticeInfo), nil
+	}
+	state.output = snapshot.RecentOutput
+	state.bracketedPaste = bracketedPasteMode(snapshot.RecentOutput, state.bracketedPaste)
+	if snapshot.Status != "running" {
+		m.terminalAttach = nil
+		exitCode := 0
+		if snapshot.ExitCode != nil {
+			exitCode = *snapshot.ExitCode
+		}
+		return m.showTransientNoticeInline(fmt.Sprintf("Terminal session %d finished (exit %d).", state.sessionID, exitCode), transientNoticeInfo), nil
+	}
+	return m, terminalAttachTickCmd()
+}
+
+// pollTerminalAutoAttach runs the auto-attach watcher: while the run is live it
+// looks for a new tty session and opens the overlay on it, giving up at the
+// deadline (a permission prompt can hold the session start for a while).
+func (m model) pollTerminalAutoAttach(msg terminalAutoAttachTickMsg) (model, tea.Cmd) {
+	state := m.terminalAutoAttach
+	if state == nil || msg.runID != state.runID {
+		return m, nil
+	}
+	if m.activeRunID != state.runID || !m.pending || m.now().After(state.deadline) {
+		m.terminalAutoAttach = nil
+		return m, nil
+	}
+	controller, ok := m.execSessionController()
+	if !ok {
+		return m, terminalAutoAttachTickCmd(state.runID)
+	}
+	for _, session := range controller.ExecSessions() {
+		if !session.TTY || session.Status != "running" || state.known[session.ID] || m.terminalAttachSeen[session.ID] {
+			continue
+		}
+		if !m.terminalAttachCanOpen() || m.terminalAttach != nil {
+			// A modal (permission prompt, picker, …) or an existing attach owns
+			// the viewport; keep watching so the overlay opens once it clears.
+			return m, terminalAutoAttachTickCmd(state.runID)
+		}
+		m.terminalAutoAttach = nil
+		return m.openTerminalAttach(session.ID)
+	}
+	return m, terminalAutoAttachTickCmd(state.runID)
+}
+
+// terminalAttachCanOpen reports whether the attach overlay would actually be
+// rendered right now: beyond the modal prompts, the subchat drill-in, file
+// view, setup wizard, help/run-details overlays, the detailed transcript, and
+// active suggestions each replace or cover the viewport it draws into, so
+// opening then would capture keys into an invisible overlay.
+func (m model) terminalAttachCanOpen() bool {
+	return m.noBlockingModalExceptAttach() &&
+		!m.helpOverlay && !m.leaderHelpOverlay && !m.runDetailsOpen &&
+		!m.subchat.active && !m.fileView.active && !m.setup.visible &&
+		!m.transcriptDetailed && !m.suggestionsActive()
+}
+
+// noBlockingModalExceptAttach is noBlockingModal without the attach overlay's
+// own term, for the auto-attach watcher deciding whether another modal owns
+// the viewport.
+func (m model) noBlockingModalExceptAttach() bool {
+	return m.pendingPermission == nil && m.pendingAskUser == nil && m.pendingSpecReview == nil &&
+		m.providerWizard == nil && m.mcpAddWizard == nil && m.mcpManager == nil && m.picker == nil &&
+		m.sttKeyPrompt == nil && m.renamePrompt == nil
+}
+
+// writeTerminalAttachInput forwards bytes to the session stdin. The bytes are
+// written through untouched and never echoed into the transcript, a notice, or
+// the overlay. Errors only update overlay state or a generic notice.
+func (m model) writeTerminalAttachInput(state *terminalAttachState, data []byte) model {
+	controller, ok := m.execSessionController()
+	if !ok {
+		m.terminalAttach = nil
+		return m
+	}
+	err := controller.WriteExecSessionInput(state.sessionID, data)
+	switch {
+	case errors.Is(err, execution.ErrProcessNotFound):
+		m.terminalAttach = nil
+		return m.showTransientNoticeInline(fmt.Sprintf("Terminal session %d ended.", state.sessionID), transientNoticeInfo)
+	case errors.Is(err, execution.ErrProcessStdinDisabled):
+		m.terminalAttach = nil
+		return m.showTransientNoticeInline(fmt.Sprintf("Terminal session %d no longer accepts input.", state.sessionID), transientNoticeWarning)
+	case err != nil:
+		return m.showTransientNoticeInline("Could not send input to session "+strconv.Itoa(state.sessionID)+".", transientNoticeWarning)
+	}
+	return m
+}
+
+// handleTerminalAttachKey owns every keystroke while attached: Esc detaches,
+// anything else maps to PTY bytes and goes to the process (so Ctrl+C reaches
+// it as 0x03 instead of triggering the TUI's own exit confirmation).
+func (m model) handleTerminalAttachKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
+	state := m.terminalAttach
+	if keyIs(msg, tea.KeyEsc) {
+		m.terminalAttach = nil
+		return m.showTransientNoticeInline(
+			fmt.Sprintf("Detached from session %d — it keeps running; /attach %d to return.", state.sessionID, state.sessionID),
+			transientNoticeInfo), nil
+	}
+	data, ok := ptyInputBytes(msg)
+	if !ok {
+		return m, nil
+	}
+	return m.writeTerminalAttachInput(state, data), nil
+}
+
+// handleTerminalAttachPaste forwards a paste to the PTY. Bubble Tea strips
+// the outer terminal's bracketed-paste markers, so when the child enabled
+// bracketed paste itself the framing is re-added around the content.
+func (m model) handleTerminalAttachPaste(content string) (tea.Model, tea.Cmd) {
+	state := m.terminalAttach
+	if content == "" {
+		return m, nil
+	}
+	data := []byte(content)
+	if state.bracketedPaste {
+		data = append(append([]byte("\x1b[200~"), data...), "\x1b[201~"...)
+	}
+	return m.writeTerminalAttachInput(state, data), nil
+}
+
+// bracketedPasteMode tracks the child's bracketed-paste mode from its output:
+// the last enable/disable sequence wins, and output without either keeps the
+// previous state since RecentOutput is a rolling window that can lose it.
+func bracketedPasteMode(output string, current bool) bool {
+	on := strings.LastIndex(output, "\x1b[?2004h")
+	off := strings.LastIndex(output, "\x1b[?2004l")
+	switch {
+	case on < 0 && off < 0:
+		return current
+	case on > off:
+		return true
+	default:
+		return false
+	}
+}
+
+// ptyInputBytes maps a keystroke to the byte sequence a terminal would send.
+// Esc is deliberately unmapped: it detaches instead of reaching the process.
+func ptyInputBytes(msg tea.KeyMsg) ([]byte, bool) {
+	key := msg.Key()
+	if keyHasMod(msg, tea.ModCtrl) {
+		if key.Code >= 'a' && key.Code <= 'z' {
+			return []byte{byte(key.Code - 'a' + 1)}, true
+		}
+		return nil, false
+	}
+	if keyAlt(msg) {
+		if text := keyText(msg); text != "" {
+			return append([]byte{0x1b}, text...), true
+		}
+		return nil, false
+	}
+	switch key.Code {
+	case tea.KeyEnter:
+		return []byte("\r"), true
+	case tea.KeyTab:
+		return []byte("\t"), true
+	case tea.KeyBackspace:
+		return []byte{0x7f}, true
+	case tea.KeyDelete:
+		return []byte("\x1b[3~"), true
+	case tea.KeyUp:
+		return []byte("\x1b[A"), true
+	case tea.KeyDown:
+		return []byte("\x1b[B"), true
+	case tea.KeyRight:
+		return []byte("\x1b[C"), true
+	case tea.KeyLeft:
+		return []byte("\x1b[D"), true
+	case tea.KeyHome:
+		return []byte("\x1b[H"), true
+	case tea.KeyEnd:
+		return []byte("\x1b[F"), true
+	case tea.KeyPgUp:
+		return []byte("\x1b[5~"), true
+	case tea.KeyPgDown:
+		return []byte("\x1b[6~"), true
+	}
+	if text := keyText(msg); text != "" {
+		return []byte(text), true
+	}
+	return nil, false
+}
+
+// renderTerminalTail turns raw PTY output into display lines: carriage returns
+// overwrite their line from column 0 (progress-bar style), ANSI sequences are
+// stripped, remaining control runes are dropped (tab expands to spaces), and
+// the result is the last rows lines top-aligned and padded to exactly rows.
+func renderTerminalTail(raw string, width, rows int) []string {
+	if rows < 0 {
+		rows = 0
+	}
+	raw = strings.ReplaceAll(raw, "\r\n", "\n")
+	source := strings.Split(raw, "\n")
+	lines := make([]string, 0, len(source))
+	for _, line := range source {
+		lines = append(lines, sanitizeTerminalLine(line, width))
+	}
+	if len(lines) > rows {
+		lines = lines[len(lines)-rows:]
+	}
+	for len(lines) < rows {
+		lines = append(lines, "")
+	}
+	return lines
+}
+
+func sanitizeTerminalLine(line string, width int) string {
+	var resolved []rune
+	for _, segment := range strings.Split(line, "\r") {
+		runes := []rune(segment)
+		if len(runes) < len(resolved) {
+			runes = append(runes, resolved[len(runes):]...)
+		}
+		resolved = runes
+	}
+	stripped := ansi.Strip(string(resolved))
+	var builder strings.Builder
+	for _, r := range stripped {
+		switch {
+		case r == '\t':
+			builder.WriteString("    ")
+		case unicode.IsControl(r):
+		default:
+			builder.WriteRune(r)
+		}
+	}
+	if width <= 0 {
+		return builder.String()
+	}
+	return fitStyledLine(builder.String(), width)
+}
+
+// terminalAttachViewportRows is the number of output rows the attached
+// terminal gets: the transcript viewport's body height minus the box's two
+// border lines and its footer hint line, so the bordered overlay fills the
+// viewport exactly. The same frame math the compositor uses keeps the two in
+// sync — and footerView already collapses to the status line while attached.
+func (m model) terminalAttachViewportRows(width int) int {
+	if m.height <= 0 {
+		return 10
+	}
+	frame := m.scrollableTranscriptFrame(m.pinnedTitleBar(width), m.footerView(width))
+	return maxInt(6, frame.bodyRect.height-3)
+}
+
+func (m model) terminalAttachOverlay(width int) string {
+	state := m.terminalAttach
+	if state == nil {
+		return ""
+	}
+	command := compactCommandOutputText(state.command)
+	if command == "" {
+		command = "command"
+	}
+	// styledBlockFillTitle drops the title when it can't fit the top rule, so
+	// truncate the command to whatever the border can carry.
+	titlePrefix := zeroTheme.accent.Render("●") + " Terminal  "
+	titleSuffix := "  [running]"
+	titleBudget := width - 5 - lipgloss.Width(titleSuffix)
+	title := titlePrefix + truncateRunes(command, maxInt(0, titleBudget-lipgloss.Width(titlePrefix))) + titleSuffix
+	innerWidth := maxInt(1, width-4)
+	// Reserve one cell so the cursor never pushes a full line past the edge.
+	tail := renderTerminalTail(state.output, innerWidth-1, m.terminalAttachViewportRows(width))
+	cursor := -1
+	for index := len(tail) - 1; index >= 0; index-- {
+		if strings.TrimSpace(ansi.Strip(tail[index])) != "" {
+			cursor = index
+			break
+		}
+	}
+	if cursor < 0 && len(tail) > 0 {
+		cursor = 0
+	}
+	if cursor >= 0 {
+		tail[cursor] += zeroTheme.accent.Render("▌")
+	}
+	footer := fmt.Sprintf("Esc detach · Ctrl+C goes to the process · /stop %d to kill", state.sessionID)
+	lines := make([]string, 0, len(tail)+1)
+	lines = append(lines, tail...)
+	lines = append(lines, zeroTheme.faint.Render(footer))
+	return styledBlockFillTitle(width, title, lines, zeroTheme.lineStrong, lipgloss.NewStyle())
+}

internal/tui/terminal_attach_test.go

@@ -0,0 +1,748 @@
+package tui
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	tea "charm.land/bubbletea/v2"
+	"charm.land/lipgloss/v2"
+	"github.com/charmbracelet/x/ansi"
+
+	"github.com/Gitlawb/zero/internal/agent"
+	"github.com/Gitlawb/zero/internal/tools"
+)
+
+func attachedModel(t *testing.T) (model, *fakeExecSessionTool) {
+	t.Helper()
+	tool := &fakeExecSessionTool{
+		sessions: []tools.ExecSessionSnapshot{{
+			ID:           7,
+			TTY:          true,
+			Status:       "running",
+			Command:      "sudo apt install x",
+			RecentOutput: "[sudo] password for me: ",
+			StartedAt:    time.Unix(100, 0),
+		}},
+	}
+	m := modelWithFakeExecSessions(tool, time.Unix(200, 0))
+	m.width = 100
+	m.height = 30
+	return m, tool
+}
+
+func TestOpenTerminalAttachSetsState(t *testing.T) {
+	m, _ := attachedModel(t)
+	next, cmd := m.openTerminalAttach(7)
+	if cmd == nil {
+		t.Fatal("openTerminalAttach should schedule a refresh tick")
+	}
+	state := next.terminalAttach
+	if state == nil || state.sessionID != 7 {
+		t.Fatalf("state = %#v", state)
+	}
+	if state.command != "sudo apt install x" || state.output != "[sudo] password for me: " {
+		t.Fatalf("state did not pick up the snapshot: %#v", state)
+	}
+	if !next.terminalAttachSeen[7] {
+		t.Fatal("openTerminalAttach should mark the session as seen")
+	}
+}
+
+func TestTerminalAttachForwardsKeys(t *testing.T) {
+	m, tool := attachedModel(t)
+	next, _ := m.openTerminalAttach(7)
+
+	for _, msg := range []tea.Msg{testKeyText("s"), testKey(tea.KeyEnter)} {
+		updated, _ := next.Update(msg)
+		next = updated.(model)
+	}
+	if next.terminalAttach == nil {
+		t.Fatal("typing should stay attached")
+	}
+	if len(tool.writes) != 2 || string(tool.writes[0]) != "s" || string(tool.writes[1]) != "\r" {
+		t.Fatalf("writes = %#v, want [s \\r]", tool.writes)
+	}
+}
+
+func TestTerminalAttachForwardsCtrlC(t *testing.T) {
+	m, tool := attachedModel(t)
+	next, _ := m.openTerminalAttach(7)
+
+	updated, _ := next.Update(testKeyCtrl('c'))
+	next = updated.(model)
+	if len(tool.writes) != 1 || len(tool.writes[0]) != 1 || tool.writes[0][0] != 0x03 {
+		t.Fatalf("writes = %#v, want [0x03]", tool.writes)
+	}
+	if next.terminalAttach == nil {
+		t.Fatal("Ctrl+C detached the session — it should go to the process")
+	}
+	if next.exitConfirmActive {
+		t.Fatal("Ctrl+C armed the exit confirmation while attached")
+	}
+}
+
+func TestTerminalAttachForwardsPaste(t *testing.T) {
+	m, tool := attachedModel(t)
+	next, _ := m.openTerminalAttach(7)
+
+	updated, _ := next.Update(testPaste("pw"))
+	next = updated.(model)
+	if next.terminalAttach == nil {
+		t.Fatal("paste should stay attached")
+	}
+	if len(tool.writes) != 1 || string(tool.writes[0]) != "pw" {
+		t.Fatalf("writes = %#v, want [pw]", tool.writes)
+	}
+}
+
+func TestTerminalAttachPasteKeepsBracketedFraming(t *testing.T) {
+	m, tool := attachedModel(t)
+	tool.sessions[0].RecentOutput = "\x1b[?2004h[sudo] password for me: "
+	next, _ := m.openTerminalAttach(7)
+
+	updated, _ := next.Update(testPaste("pw"))
+	next = updated.(model)
+	want := "\x1b[200~pw\x1b[201~"
+	if len(tool.writes) != 1 || string(tool.writes[0]) != want {
+		t.Fatalf("writes = %q, want [%q]", tool.writes, want)
+	}
+
+	// A disable sequence in later output turns framing back off once the
+	// refresh tick observes it.
+	tool.sessions[0].RecentOutput += "\x1b[?2004l"
+	updated, _ = next.Update(terminalAttachTickMsg{})
+	next = updated.(model)
+	_, _ = next.Update(testPaste("pw3"))
+	if last := string(tool.writes[len(tool.writes)-1]); last != "pw3" {
+		t.Fatalf("write after disable = %q, want raw pw3", last)
+	}
+}
+
+func TestBracketedPasteMode(t *testing.T) {
+	cases := []struct {
+		name    string
+		output  string
+		current bool
+		want    bool
+	}{
+		{name: "enable last", output: "\x1b[?2004h", want: true},
+		{name: "disable last", output: "\x1b[?2004l", current: true, want: false},
+		{name: "neither keeps current", output: "plain output", current: true, want: true},
+		{name: "neither stays off", output: "plain output", want: false},
+		{name: "enable after disable", output: "\x1b[?2004ltext\x1b[?2004h", want: true},
+		{name: "disable after enable", output: "\x1b[?2004htext\x1b[?2004l", current: true, want: false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := bracketedPasteMode(tc.output, tc.current); got != tc.want {
+				t.Fatalf("bracketedPasteMode(%q, %v) = %v, want %v", tc.output, tc.current, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestTerminalAttachEscDetaches(t *testing.T) {
+	m, tool := attachedModel(t)
+	next, _ := m.openTerminalAttach(7)
+
+	updated, _ := next.Update(testKey(tea.KeyEsc))
+	next = updated.(model)
+	if next.terminalAttach != nil {
+		t.Fatal("Esc should detach")
+	}
+	if len(tool.writes) != 0 {
+		t.Fatalf("Esc forwarded bytes to the process: %#v", tool.writes)
+	}
+	if !strings.Contains(next.transientNotice.text, "Detached from session 7") {
+		t.Fatalf("notice = %q", next.transientNotice.text)
+	}
+}
+
+func TestTerminalAttachTickAutoClosesOnExit(t *testing.T) {
+	tool := &fakeExecSessionTool{
+		sessions: []tools.ExecSessionSnapshot{{
+			ID: 7, TTY: true, Status: "running", Command: "sudo apt install x",
+			StartedAt: time.Unix(100, 0),
+		}},
+	}
+	m := modelWithFakeExecSessions(tool, time.Unix(200, 0))
+	next, _ := m.openTerminalAttach(7)
+
+	exitCode := 1
+	tool.sessions[0].Status = "exited"
+	tool.sessions[0].ExitCode = &exitCode
+	updated, _ := next.Update(terminalAttachTickMsg{})
+	next = updated.(model)
+	if next.terminalAttach != nil {
+		t.Fatal("overlay should close itself when the session exits")
+	}
+	if !strings.Contains(next.transientNotice.text, "Terminal session 7 finished (exit 1).") {
+		t.Fatalf("notice = %q", next.transientNotice.text)
+	}
+}
+
+func TestTerminalAttachTickAutoClosesOnMissing(t *testing.T) {
+	tool := &fakeExecSessionTool{
+		sessions: []tools.ExecSessionSnapshot{{
+			ID: 7, TTY: true, Status: "running", Command: "cat", StartedAt: time.Unix(100, 0),
+		}},
+	}
+	m := modelWithFakeExecSessions(tool, time.Unix(200, 0))
+	next, _ := m.openTerminalAttach(7)
+
+	tool.sessions = nil
+	updated, _ := next.Update(terminalAttachTickMsg{})
+	next = updated.(model)
+	if next.terminalAttach != nil {
+		t.Fatal("overlay should close itself when the session disappears")
+	}
+	if !strings.Contains(next.transientNotice.text, "Terminal session 7 ended.") {
+		t.Fatalf("notice = %q", next.transientNotice.text)
+	}
+}
+
+func TestTerminalAttachOverlay(t *testing.T) {
+	m, _ := attachedModel(t)
+	next, _ := m.openTerminalAttach(7)
+
+	overlay := next.terminalAttachOverlay(80)
+	for _, want := range []string{"Terminal", "sudo apt install x", "[running]", "[sudo] password for me:", "Esc detach", "/stop 7"} {
+		if !strings.Contains(overlay, want) {
+			t.Fatalf("overlay missing %q:\n%s", want, overlay)
+		}
+	}
+}
+
+func TestTerminalAttachOverlayFillsViewport(t *testing.T) {
+	m, _ := attachedModel(t)
+	m.width, m.height = 120, 40
+	next, _ := m.openTerminalAttach(7)
+
+	overlay := next.terminalAttachOverlay(120)
+	lines := strings.Split(overlay, "\n")
+	frame := next.scrollableTranscriptFrame(next.pinnedTitleBar(120), next.footerView(120))
+	if len(lines) != frame.bodyRect.height {
+		t.Fatalf("overlay lines = %d, want viewport body height %d", len(lines), frame.bodyRect.height)
+	}
+	for index, line := range lines {
+		if width := lipgloss.Width(line); width != 120 {
+			t.Fatalf("overlay line %d width = %d, want 120: %q", index, width, line)
+		}
+	}
+	plain := ansi.Strip(overlay)
+	if !strings.Contains(plain, "Terminal") || !strings.Contains(plain, "[running]") {
+		t.Fatalf("overlay missing border title: %q", lines[0])
+	}
+	if !strings.HasPrefix(plain, "╭") || !strings.Contains(lines[len(lines)-1], "╰") {
+		t.Fatal("overlay should be a bordered box")
+	}
+}
+
+func TestFooterViewWhileAttachedDropsComposer(t *testing.T) {
+	m, _ := attachedModel(t)
+	next, _ := m.openTerminalAttach(7)
+
+	footer := ansi.Strip(next.footerView(100))
+	if strings.Contains(footer, "describe a task") {
+		t.Fatalf("attached footer still shows the composer: %q", footer)
+	}
+	if strings.TrimSpace(footer) == "" {
+		t.Fatal("attached footer should still render the status line")
+	}
+	m.input.SetValue("typed")
+	if plain := ansi.Strip(m.footerView(100)); !strings.Contains(plain, "typed") {
+		t.Fatalf("detached footer lost the composer: %q", plain)
+	}
+}
+
+func TestTerminalAttachResizesPTYOnOpenAndResize(t *testing.T) {
+	m, tool := attachedModel(t)
+
+	// A resize while nothing is attached must not reach the controller.
+	if updated, _ := m.Update(tea.WindowSizeMsg{Width: 110, Height: 35}); updated != nil {
+		m = updated.(model)
+	}
+	if tool.resizeCalls != 0 {
+		t.Fatalf("WindowSizeMsg while detached resized: %d calls", tool.resizeCalls)
+	}
+
+	next, _ := m.openTerminalAttach(7)
+	wantCols := chatWidth(m.width) - 5
+	wantRows := next.terminalAttachViewportRows(chatWidth(m.width))
+	if tool.resizeCalls != 1 || tool.resizeCols != wantCols || tool.resizeRows != wantRows {
+		t.Fatalf("open resize = %d calls %dx%d, want 1 call %dx%d", tool.resizeCalls, tool.resizeCols, tool.resizeRows, wantCols, wantRows)
+	}
+
+	updated, _ := next.Update(tea.WindowSizeMsg{Width: 120, Height: 40})
+	next = updated.(model)
+	wantCols, wantRows = 115, next.terminalAttachViewportRows(120)
+	if tool.resizeCalls != 2 || tool.resizeCols != wantCols || tool.resizeRows != wantRows {
+		t.Fatalf("resize = %d calls %dx%d, want 2 calls %dx%d", tool.resizeCalls, tool.resizeCols, tool.resizeRows, wantCols, wantRows)
+	}
+
+	// A no-change resize is not forwarded again.
+	_, _ = next.Update(tea.WindowSizeMsg{Width: 120, Height: 40})
+	if tool.resizeCalls != 2 {
+		t.Fatalf("unchanged size resized again: %d calls", tool.resizeCalls)
+	}
+}
+
+func TestExecCallWantsTTY(t *testing.T) {
+	cases := []struct {
+		name string
+		args string
+		want bool
+	}{
+		{"tty true", `{"cmd":"x","tty":true}`, true},
+		{"tty false", `{"cmd":"x","tty":false}`, false},
+		{"tty absent", `{"cmd":"x"}`, false},
+		{"garbage", `not json`, false},
+		{"empty", ``, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := execCallWantsTTY(tc.args); got != tc.want {
+				t.Fatalf("execCallWantsTTY(%q) = %v, want %v", tc.args, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestInteractiveExecStartAutoAttaches(t *testing.T) {
+	tool := &fakeExecSessionTool{}
+	m := modelWithFakeExecSessions(tool, time.Unix(200, 0))
+	m.activeRunID = 3
+	m.pending = true
+
+	updated, cmd := m.Update(interactiveExecStartMsg{runID: 3})
+	next := updated.(model)
+	if next.terminalAutoAttach == nil || cmd == nil {
+		t.Fatal("interactiveExecStartMsg should arm the watcher and a tick")
+	}
+
+	tool.sessions = append(tool.sessions, tools.ExecSessionSnapshot{
+		ID: 7, TTY: true, Status: "running", Command: "cat", StartedAt: time.Unix(100, 0),
+	})
+	updated, _ = next.Update(terminalAutoAttachTickMsg{runID: 3})
+	next = updated.(model)
+	if next.terminalAttach == nil || next.terminalAttach.sessionID != 7 {
+		t.Fatalf("auto-attach did not open on the new session: %#v", next.terminalAttach)
+	}
+	if !next.terminalAttachSeen[7] {
+		t.Fatal("session 7 should be marked seen")
+	}
+	if next.terminalAutoAttach != nil {
+		t.Fatal("watcher should stop once it attached")
+	}
+}
+
+func TestTerminalAutoAttachSkipsKnownSession(t *testing.T) {
+	tool := &fakeExecSessionTool{
+		sessions: []tools.ExecSessionSnapshot{
+			{ID: 5, TTY: true, Status: "running", Command: "top", StartedAt: time.Unix(100, 0)},
+		},
+	}
+	m := modelWithFakeExecSessions(tool, time.Unix(200, 0))
+	m.activeRunID = 3
+	m.pending = true
+
+	// Session 5 predates the tool call — it is not this call's session.
+	updated, _ := m.Update(interactiveExecStartMsg{runID: 3, known: map[int]bool{5: true}})
+	next := updated.(model)
+	updated, cmd := next.Update(terminalAutoAttachTickMsg{runID: 3})
+	next = updated.(model)
+	if next.terminalAttach != nil {
+		t.Fatal("watcher must not attach to a session that was already running")
+	}
+	if cmd == nil || next.terminalAutoAttach == nil {
+		t.Fatal("watcher should keep ticking while nothing new appears")
+	}
+
+	tool.sessions = append(tool.sessions, tools.ExecSessionSnapshot{
+		ID: 6, TTY: true, Status: "running", Command: "cat", StartedAt: time.Unix(200, 0),
+	})
+	updated, _ = next.Update(terminalAutoAttachTickMsg{runID: 3})
+	next = updated.(model)
+	if next.terminalAttach == nil || next.terminalAttach.sessionID != 6 {
+		t.Fatalf("watcher should attach to the new session 6: %#v", next.terminalAttach)
+	}
+}
+
+func TestInteractiveExecStartBaselinePredatesSessionRegistration(t *testing.T) {
+	// The baseline is captured when OnToolCall fires, before the tool's Run
+	// registers the session — a snapshot taken at Update time would already
+	// contain it and wrongly exclude it as pre-existing.
+	tool := &fakeExecSessionTool{
+		sessions: []tools.ExecSessionSnapshot{
+			{ID: 5, TTY: true, Status: "running", Command: "top", StartedAt: time.Unix(100, 0)},
+		},
+	}
+	m := modelWithFakeExecSessions(tool, time.Unix(200, 0))
+	m.activeRunID = 3
+	m.pending = true
+
+	msg := interactiveExecStartMsg{runID: 3, known: map[int]bool{5: true}}
+	tool.sessions = append(tool.sessions, tools.ExecSessionSnapshot{
+		ID: 6, TTY: true, Status: "running", Command: "cat", StartedAt: time.Unix(200, 0),
+	})
+
+	updated, _ := m.Update(msg)
+	next := updated.(model)
+	updated, _ = next.Update(terminalAutoAttachTickMsg{runID: 3})
+	next = updated.(model)
+	if next.terminalAttach == nil || next.terminalAttach.sessionID != 6 {
+		t.Fatalf("watcher should attach to the session registered after the baseline: %#v", next.terminalAttach)
+	}
+}
+
+func TestTerminalAutoAttachDoesNotReattachSeen(t *testing.T) {
+	tool := &fakeExecSessionTool{
+		sessions: []tools.ExecSessionSnapshot{
+			{ID: 7, TTY: true, Status: "running", Command: "cat", StartedAt: time.Unix(100, 0)},
+		},
+	}
+	m := modelWithFakeExecSessions(tool, time.Unix(200, 0))
+	m.activeRunID = 3
+	m.pending = true
+	m.terminalAttachSeen = map[int]bool{7: true} // user already attached and detached
+
+	updated, _ := m.Update(interactiveExecStartMsg{runID: 3})
+	next := updated.(model)
+	updated, cmd := next.Update(terminalAutoAttachTickMsg{runID: 3})
+	next = updated.(model)
+	if next.terminalAttach != nil {
+		t.Fatal("watcher must not re-open a session the user detached")
+	}
+	if cmd == nil {
+		t.Fatal("watcher should keep ticking")
+	}
+}
+
+func TestTerminalAutoAttachTickIgnoresStaleRun(t *testing.T) {
+	tool := &fakeExecSessionTool{
+		sessions: []tools.ExecSessionSnapshot{
+			{ID: 7, TTY: true, Status: "running", Command: "cat", StartedAt: time.Unix(100, 0)},
+		},
+	}
+	m := modelWithFakeExecSessions(tool, time.Unix(200, 0))
+	m.activeRunID = 3
+	m.pending = true
+	m.terminalAutoAttach = &terminalAutoAttachState{
+		runID: 3, known: map[int]bool{}, deadline: m.now().Add(terminalAutoAttachTimeout),
+	}
+
+	updated, cmd := m.Update(terminalAutoAttachTickMsg{runID: 9})
+	next := updated.(model)
+	if next.terminalAttach != nil {
+		t.Fatal("a stale tick must not attach")
+	}
+	if next.terminalAutoAttach == nil || cmd != nil {
+		t.Fatal("a stale tick should be dropped without touching the watcher")
+	}
+
+	updated, _ = next.Update(terminalAutoAttachTickMsg{runID: 3})
+	next = updated.(model)
+	if next.terminalAttach == nil || next.terminalAttach.sessionID != 7 {
+		t.Fatalf("the live tick should still attach: %#v", next.terminalAttach)
+	}
+}
+
+func TestBTWRoutesAutoAttachTickToHiddenParent(t *testing.T) {
+	tool := &fakeExecSessionTool{}
+	m := newBTWTestModel(t)
+	registry := tools.NewRegistry()
+	registry.Register(tool)
+	m.registry = registry
+	m.pending = true
+	m.runID = 7
+	m.activeRunID = 7
+
+	side, _ := m.handleBTWCommand("")
+	routed, _, ok := side.routeBTWParentMessage(interactiveExecStartMsg{runID: 7})
+	if !ok {
+		t.Fatal("interactiveExecStartMsg was not routed to the parent")
+	}
+	side = routed
+	if side.btw.parent == nil || side.btw.parent.terminalAutoAttach == nil {
+		t.Fatal("watcher was not armed on the hidden parent")
+	}
+
+	// A tick tagged for the side run must not reach the parent watcher.
+	if routed, _, ok := side.routeBTWParentMessage(terminalAutoAttachTickMsg{runID: side.btw.sideRunIDBase}); ok || routed.btw.parent.terminalAttach != nil {
+		t.Fatal("a side-run tick must not reach the parent watcher")
+	}
+
+	tool.sessions = append(tool.sessions, tools.ExecSessionSnapshot{
+		ID: 7, TTY: true, Status: "running", Command: "cat", StartedAt: time.Unix(100, 0),
+	})
+	routed, _, ok = side.routeBTWParentMessage(terminalAutoAttachTickMsg{runID: 7})
+	if !ok {
+		t.Fatal("parent-run tick was not routed to the parent")
+	}
+	side = routed
+	if side.btw.parent == nil || side.btw.parent.terminalAttach == nil || side.btw.parent.terminalAttach.sessionID != 7 {
+		t.Fatalf("parent overlay did not open: %#v", side.btw.parent)
+	}
+	if side.terminalAttach != nil {
+		t.Fatal("attach state leaked onto the side model")
+	}
+}
+
+func TestTerminalAutoAttachDefersToOtherViews(t *testing.T) {
+	newWatchingModel := func(t *testing.T) (model, *fakeExecSessionTool) {
+		t.Helper()
+		tool := &fakeExecSessionTool{
+			sessions: []tools.ExecSessionSnapshot{
+				{ID: 7, TTY: true, Status: "running", Command: "cat", StartedAt: time.Unix(100, 0)},
+			},
+		}
+		m := modelWithFakeExecSessions(tool, time.Unix(200, 0))
+		m.activeRunID = 3
+		m.pending = true
+		m.terminalAutoAttach = &terminalAutoAttachState{
+			runID: 3, known: map[int]bool{}, deadline: m.now().Add(terminalAutoAttachTimeout),
+		}
+		return m, tool
+	}
+
+	m, _ := newWatchingModel(t)
+	m.helpOverlay = true
+	updated, cmd := m.Update(terminalAutoAttachTickMsg{runID: 3})
+	next := updated.(model)
+	if next.terminalAttach != nil {
+		t.Fatal("overlay must not open over the help overlay")
+	}
+	if cmd == nil || next.terminalAutoAttach == nil {
+		t.Fatal("watcher should keep ticking while help owns the viewport")
+	}
+	next.helpOverlay = false
+	updated, _ = next.Update(terminalAutoAttachTickMsg{runID: 3})
+	next = updated.(model)
+	if next.terminalAttach == nil {
+		t.Fatal("overlay should open once help closes")
+	}
+
+	m, _ = newWatchingModel(t)
+	m.subchat.active = true
+	updated, cmd = m.Update(terminalAutoAttachTickMsg{runID: 3})
+	next = updated.(model)
+	if next.terminalAttach != nil {
+		t.Fatal("overlay must not open inside the subchat view")
+	}
+	if cmd == nil || next.terminalAutoAttach == nil {
+		t.Fatal("watcher should keep ticking while subchat owns the viewport")
+	}
+}
+
+func TestAttachCommandRefusesWhileSubchatActive(t *testing.T) {
+	m, _ := attachedModel(t)
+	m.subchat.active = true
+
+	next, _ := m.attachTerminalCommand("7")
+	if next.terminalAttach != nil {
+		t.Fatal("/attach must not open the overlay inside the subchat view")
+	}
+	if !strings.Contains(next.transientNotice.text, "Leave the current view first") {
+		t.Fatalf("expected the leave-view notice, got %q", next.transientNotice.text)
+	}
+	next.subchat.active = false
+	next, _ = next.attachTerminalCommand("7")
+	if next.terminalAttach == nil {
+		t.Fatal("/attach should open once the subchat view is left")
+	}
+}
+
+func TestTerminalAutoAttachIgnoresWrongRun(t *testing.T) {
+	m, _ := attachedModel(t)
+	m.activeRunID = 3
+	m.pending = true
+
+	updated, cmd := m.Update(interactiveExecStartMsg{runID: 9})
+	next := updated.(model)
+	if next.terminalAutoAttach != nil || cmd != nil {
+		t.Fatal("a msg for another run must not arm the watcher")
+	}
+}
+
+func TestTerminalAutoAttachWaitsForPermissionPrompt(t *testing.T) {
+	tool := &fakeExecSessionTool{
+		sessions: []tools.ExecSessionSnapshot{
+			{ID: 7, TTY: true, Status: "running", Command: "cat", StartedAt: time.Unix(100, 0)},
+		},
+	}
+	m := modelWithFakeExecSessions(tool, time.Unix(200, 0))
+	m.activeRunID = 3
+	m.pending = true
+	m.pendingPermission = &pendingPermissionPrompt{
+		request: agent.PermissionRequest{ToolName: "exec_command"},
+		decide:  func(agent.PermissionDecision) {},
+	}
+
+	// The watcher is armed before the session registers? Session already here —
+	// simplest equivalent: arm it directly and confirm the modal blocks opening.
+	m.terminalAutoAttach = &terminalAutoAttachState{
+		runID: 3, known: map[int]bool{}, deadline: m.now().Add(terminalAutoAttachTimeout),
+	}
+	updated, cmd := m.Update(terminalAutoAttachTickMsg{runID: 3})
+	next := updated.(model)
+	if next.terminalAttach != nil {
+		t.Fatal("overlay must not open over a permission prompt")
+	}
+	if cmd == nil {
+		t.Fatal("watcher should keep ticking while the modal is up")
+	}
+
+	next.pendingPermission = nil
+	updated, _ = next.Update(terminalAutoAttachTickMsg{runID: 3})
+	next = updated.(model)
+	if next.terminalAttach == nil || next.terminalAttach.sessionID != 7 {
+		t.Fatalf("overlay should open once the modal clears: %#v", next.terminalAttach)
+	}
+}
+
+// The user's keystrokes go to the PTY and nowhere else: not the transcript,
+// not the composer, not a notice.
+func TestTerminalAttachNeverEchoesInput(t *testing.T) {
+	m, tool := attachedModel(t)
+	next, _ := m.openTerminalAttach(7)
+
+	for _, msg := range []tea.Msg{testKeyText("s"), testKeyText("3"), testKeyText("c"), testKeyText("r"), testKeyText("e"), testKeyText("t"), testPaste("pw")} {
+		updated, _ := next.Update(msg)
+		next = updated.(model)
+	}
+	if len(tool.writes) == 0 {
+		t.Fatal("nothing was forwarded")
+	}
+	for _, row := range next.transcript {
+		if strings.Contains(row.text, "s3cret") || strings.Contains(row.text, "pw") {
+			t.Fatalf("typed bytes leaked into transcript row: %q", row.text)
+		}
+	}
+	if strings.Contains(next.transientNotice.text, "s3cret") || strings.Contains(next.transientNotice.text, "pw") {
+		t.Fatalf("typed bytes leaked into the notice: %q", next.transientNotice.text)
+	}
+	if strings.Contains(next.composerValue(), "s3cret") {
+		t.Fatal("typed bytes leaked into the composer")
+	}
+}
+
+func TestTerminalAttachSwallowsMouse(t *testing.T) {
+	m, _ := attachedModel(t)
+	next, _ := m.openTerminalAttach(7)
+	updated, _ := next.Update(testMouseClick(tea.MouseLeft, 5, 5))
+	next = updated.(model)
+	if next.terminalAttach == nil {
+		t.Fatal("mouse click detached the session")
+	}
+}
+
+func TestPtyInputBytes(t *testing.T) {
+	cases := []struct {
+		name string
+		msg  tea.KeyMsg
+		want string
+		ok   bool
+	}{
+		{"printable", testKeyText("a"), "a", true},
+		{"space", testKey(tea.KeySpace), " ", true},
+		{"enter", testKey(tea.KeyEnter), "\r", true},
+		{"tab", testKey(tea.KeyTab), "\t", true},
+		{"backspace", testKey(tea.KeyBackspace), "\x7f", true},
+		{"delete", testKey(tea.KeyDelete), "\x1b[3~", true},
+		{"up", testKey(tea.KeyUp), "\x1b[A", true},
+		{"down", testKey(tea.KeyDown), "\x1b[B", true},
+		{"right", testKey(tea.KeyRight), "\x1b[C", true},
+		{"left", testKey(tea.KeyLeft), "\x1b[D", true},
+		{"home", testKey(tea.KeyHome), "\x1b[H", true},
+		{"end", testKey(tea.KeyEnd), "\x1b[F", true},
+		{"pgup", testKey(tea.KeyPgUp), "\x1b[5~", true},
+		{"pgdn", testKey(tea.KeyPgDown), "\x1b[6~", true},
+		{"ctrl+c", testKeyCtrl('c'), "\x03", true},
+		{"ctrl+d", testKeyCtrl('d'), "\x04", true},
+		{"ctrl+a", testKeyCtrl('a'), "\x01", true},
+		{"alt+x", testKeyAltText("x"), "\x1bx", true},
+		{"esc unmapped", testKey(tea.KeyEsc), "", false},
+		{"ctrl+1 unmapped", testKeyCtrl('1'), "", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got, ok := ptyInputBytes(tc.msg)
+			if ok != tc.ok || string(got) != tc.want {
+				t.Fatalf("ptyInputBytes = %q, %v; want %q, %v", got, ok, tc.want, tc.ok)
+			}
+		})
+	}
+}
+
+func TestRenderTerminalTail(t *testing.T) {
+	cases := []struct {
+		name  string
+		raw   string
+		width int
+		rows  int
+		want  []string
+	}{
+		{
+			name:  "tail and padding",
+			raw:   "one\ntwo\nthree",
+			width: 10, rows: 4,
+			want: []string{"one", "two", "three", ""},
+		},
+		{
+			name:  "keeps last rows",
+			raw:   "a\nb\nc\nd",
+			width: 10, rows: 2,
+			want: []string{"c", "d"},
+		},
+		{
+			name:  "carriage return overwrites",
+			raw:   "progress 10%\rprogress 90%",
+			width: 20, rows: 1,
+			want: []string{"progress 90%"},
+		},
+		{
+			name:  "shorter overwrite keeps remainder",
+			raw:   "downloading...\r100%",
+			width: 20, rows: 1,
+			want: []string{"100%loading..."},
+		},
+		{
+			name:  "crlf normalized",
+			raw:   "line1\r\nline2",
+			width: 10, rows: 2,
+			want: []string{"line1", "line2"},
+		},
+		{
+			name:  "ansi stripped",
+			raw:   "\x1b[31mred\x1b[0m plain",
+			width: 20, rows: 1,
+			want: []string{"red plain"},
+		},
+		{
+			name:  "control runes dropped, tab expanded",
+			raw:   "a\x07b\tc",
+			width: 20, rows: 1,
+			want: []string{"ab    c"},
+		},
+		{
+			name:  "width truncation",
+			raw:   "abcdefghijklmnop",
+			width: 5, rows: 1,
+			want: []string{"abcd…"},
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := renderTerminalTail(tc.raw, tc.width, tc.rows)
+			if len(got) != len(tc.want) {
+				t.Fatalf("renderTerminalTail = %#v, want %#v", got, tc.want)
+			}
+			for i := range got {
+				if got[i] != tc.want[i] {
+					t.Fatalf("renderTerminalTail[%d] = %q, want %q (all: %#v)", i, got[i], tc.want[i], got)
+				}
+			}
+		})
+	}
+}

internal/tui/transcript_selection.go

@@ -1160,7 +1160,7 @@ func (m model) transcriptHitTestSource() (header string, items []transcriptBodyI
 // outright — a modal/overlay is up, or there's no alt-screen viewport at all.
 func (m model) transcriptHitTestBlocked() bool {
 	return !m.altScreen || m.height <= 0 || m.setup.visible || m.providerWizard != nil || m.mcpAddWizard != nil ||
-		m.mcpManager != nil || m.picker != nil || m.renamePrompt != nil || m.suggestionsActive()
+		m.mcpManager != nil || m.picker != nil || m.renamePrompt != nil || m.terminalAttach != nil || m.suggestionsActive()
 }
 
 // transcriptHitTestLayout computes the frame/window/layout mouse hit-testing needs,

internal/tui/view.go

@@ -773,7 +773,7 @@ func (m model) pickerOverlay(width int) string {
 		overlayWidth = width
 	}
 	innerWidth := maxInt(1, overlayWidth-4)
-	maxVisible := minInt(pickerOverlayMaxVisible, len(m.picker.items))
+	maxVisible := pickerMaxVisible(m.picker, width)
 	start := 0
 	visible := []pickerItem{}
 	if len(m.picker.items) > 0 {
@@ -781,6 +781,7 @@ func (m model) pickerOverlay(width int) string {
 		start = selectableListStart(len(m.picker.items), maxVisible, m.picker.selected)
 		visible = m.picker.items[start : start+maxVisible]
 	}
+	showDetails := pickerShowsDetails(m.picker, width)
 
 	lines := make([]string, 0, len(visible)+7)
 	title := strings.TrimSpace(m.picker.title)
@@ -821,6 +822,16 @@ func (m model) pickerOverlay(width int) string {
 		gap := innerWidth - lipgloss.Width(left) - lipgloss.Width(right)
 		line := left + surface(zeroTheme.ink).Render(strings.Repeat(" ", maxInt(1, gap))) + right
 		lines = append(lines, fitStyledLine(line, innerWidth))
+		if showDetails && item.Detail != "" {
+			// The detail line sits under the row on the same selection band,
+			// indented to the label column so it reads as part of the item.
+			// Pad the remainder like the row above so the band is full-width.
+			detailText := "  " + item.Detail
+			detailGap := innerWidth - lipgloss.Width(detailText)
+			detail := surface(zeroTheme.faint).Render(detailText) +
+				surface(zeroTheme.faint).Render(strings.Repeat(" ", maxInt(0, detailGap)))
+			lines = append(lines, fitStyledLine(detail, innerWidth))
+		}
 	}
 	if len(visible) == 0 {
 		if m.picker.loading {
@@ -845,6 +856,36 @@ func (m model) pickerOverlay(width int) string {
 	return centerRenderedBlock(styledBlockFillTitle(overlayWidth, title, lines, zeroTheme.lineStrong, lipgloss.NewStyle()), width)
 }
 
+// pickerShowsDetails reports whether the overlay renders each row's optional
+// Detail line: only when a row actually carries one and the terminal is at
+// least medium width, where the two-line treatment reads cleanly. Narrower
+// tiers keep the single-line list fallback.
+func pickerShowsDetails(p *commandPicker, width int) bool {
+	if p == nil || widthTier(width) < tierMedium {
+		return false
+	}
+	for _, item := range p.items {
+		if item.Detail != "" {
+			return true
+		}
+	}
+	return false
+}
+
+// pickerMaxVisible caps the visible window in items. When detail lines render,
+// each item costs two rows, so the budget halves to keep the overlay the same
+// height as the single-line list.
+func pickerMaxVisible(p *commandPicker, width int) int {
+	if p == nil {
+		return 0
+	}
+	budget := pickerOverlayMaxVisible
+	if pickerShowsDetails(p, width) {
+		budget = pickerOverlayMaxVisible / 2
+	}
+	return minInt(budget, len(p.items))
+}
+
 // themePickerOverlay keeps candidate rendering inside the picker. Moving through
 // themes therefore shows their hierarchy and code treatment without repainting the
 // transcript, terminal canvas, or any other active UI.

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@gitlawb/zero",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@gitlawb/zero",
-      "version": "0.8.0",
+      "version": "0.9.0",
       "cpu": [
         "x64",
         "arm64"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitlawb/zero",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Zero — a fast, multi-provider terminal coding agent.",
   "type": "module",
   "module": "bin/zero.js",