chore(main): release 0.6.0 (#786 )

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
fix(acp): interrupt idle reads on cancellation (#782 )
2026-11-08 17:56:14 -10:00 · 2026-07-29 09:56:37 +08:00 · 2026-07-29 09:46:55 +08:00 · 2026-07-29 09:46:25 +08:00 · 2026-07-28 22:42:01 +08:00 · 2026-07-28 22:41:09 +08:00
257 changed files with 9916 additions and 3554 deletions
@@ -0,0 +1,3 @@
+*.go text eol=lf
+*.mod text eol=lf
+*.sum text eol=lf
@@ -30,6 +30,36 @@ jobs:
          go-version-file: go.mod
          cache: true

+      - name: Install Make on Windows
+        if: matrix.os == 'windows-latest'
+        shell: pwsh
+        run: choco install make --no-progress -y
+
+      - name: Validate quality targets with stock macOS Make
+        if: matrix.os == 'macos-latest'
+        env:
+          GIT_CONFIG_COUNT: 1
+          GIT_CONFIG_KEY_0: grep.patternType
+          GIT_CONFIG_VALUE_0: fixed
+        run: make -n vulncheck
+
+      - name: Check vulnerabilities through native Windows Make
+        if: matrix.os == 'windows-latest'
+        shell: cmd
+        run: make vulncheck
+
+      - name: Check dead code through native Windows Make
+        if: matrix.os == 'windows-latest'
+        continue-on-error: true
+        shell: cmd
+        run: make deadcode
+
+      - name: Run static lint through native Windows Make
+        if: matrix.os == 'windows-latest'
+        continue-on-error: true
+        shell: cmd
+        run: make lint-static
+
      - name: Check formatting
        if: matrix.os == 'ubuntu-latest'
        shell: bash
@@ -100,27 +130,18 @@ jobs:
          go-version-file: go.mod
          cache: true

-      # govulncheck, deadcode, and golangci-lint each resolve a toolchain from
-      # their own modules, which can drop below the version go.mod requires and
-      # then fail to load our packages. Pin GOTOOLCHAIN to the go.mod toolchain
-      # so all three run under it.
-      - name: Pin toolchain from go.mod
-        run: |
-          toolchain="$(awk '/^toolchain /{print $2}' go.mod)"
-          echo "GOTOOLCHAIN=${toolchain:-auto}" >> "$GITHUB_ENV"
-
      # Hard gate: fails the build when code reaches a known vulnerability. A stdlib
      # CVE is cleared by a toolchain bump (see go.mod). May also flag a newly
      # published advisory on an unrelated PR — intentional: do not ship known vulns.
      - name: govulncheck
-        run: go run golang.org/x/vuln/cmd/[email protected] ./...
+        run: make vulncheck

      # Advisory: reports functions unreachable from any cmd/* main so dormant
      # code is visible in CI. Non-blocking while the dormant subsystems are
      # still being wired or removed.
      - name: deadcode (advisory)
        continue-on-error: true
-        run: go run golang.org/x/tools/cmd/[email protected] -test=false ./...
+        run: make deadcode

      # Advisory: catches what deadcode's whole-program reachability analysis
      # doesn't, unused private functions/assignments reachable within a
@@ -130,4 +151,4 @@ jobs:
      # the repo are cleaned up incrementally (see #527).
      - name: golangci-lint (advisory)
        continue-on-error: true
-        run: go run github.com/golangci/golangci-lint/v2/cmd/[email protected] run --enable-only unused,ineffassign,staticcheck ./...
+        run: make lint-static
@@ -1 +1 @@
-{".":"0.5.0"}
+{".":"0.6.0"}
@@ -51,10 +51,8 @@ request, or completing an implementation task:
   or run focused tests with `-race`, when concurrency is affected.
 4. **Build**: `go run ./cmd/zero-release build`.
 5. **Smoke test**: `go run ./cmd/zero-release smoke`.
-6. **Advisory lint**:
-   `go run github.com/golangci/golangci-lint/v2/cmd/[email protected] run --enable-only unused,ineffassign,staticcheck ./...`.
-7. **Security**:
-   `go run golang.org/x/vuln/cmd/[email protected] ./...`.
+6. **Advisory lint**: `make lint-static`.
+7. **Security**: `make vulncheck`.
 8. **Diff hygiene**: `git diff HEAD --check` (covers staged and unstaged
   tracked changes).

@@ -6,6 +6,37 @@ 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.6.0](https://github.com/Gitlawb/zero/compare/v0.5.0...v0.6.0) (2026-07-29)
+
+
+### Features
+
+* add persistent session goals ([#803](https://github.com/Gitlawb/zero/issues/803)) ([5d1869e](https://github.com/Gitlawb/zero/commit/5d1869e7bc193c97e07418b57b823905c1151d5d))
+* **providers:** add Fireworks AI provider preset ([#772](https://github.com/Gitlawb/zero/issues/772)) ([58daea7](https://github.com/Gitlawb/zero/commit/58daea7a482927e5ab35afaf97761c60bb35e113))
+* **skills:** report hash drift in skill info ([#795](https://github.com/Gitlawb/zero/issues/795)) ([9fbdc34](https://github.com/Gitlawb/zero/commit/9fbdc341551601c13434cf7b9b6f5e4ea4c483b1))
+
+
+### Bug Fixes
+
+* **acp:** interrupt idle reads on cancellation ([#782](https://github.com/Gitlawb/zero/issues/782)) ([15b7a54](https://github.com/Gitlawb/zero/commit/15b7a5475cfeefddbc59634551451a8872b996b7))
+* **cli:** include plugins info in shell completions ([#794](https://github.com/Gitlawb/zero/issues/794)) ([fa8734f](https://github.com/Gitlawb/zero/commit/fa8734f17927de8832dfe041e043cfb86f93d12a))
+* **config:** kill provider-command process tree via job object on Windows ([#690](https://github.com/Gitlawb/zero/issues/690)) ([5c58256](https://github.com/Gitlawb/zero/commit/5c58256abc29c185b449f8ce79647eb3fae61882))
+* **config:** make the provider-command timeout an upper bound ([#811](https://github.com/Gitlawb/zero/issues/811)) ([#813](https://github.com/Gitlawb/zero/issues/813)) ([1c38e8c](https://github.com/Gitlawb/zero/commit/1c38e8cba50db255f3cda8b7cf4298712b2933e1))
+* **config:** stop billing provider-command fixtures to the 5s timeout ([#810](https://github.com/Gitlawb/zero/issues/810)) ([f5fa4ff](https://github.com/Gitlawb/zero/commit/f5fa4ffc64537897aa78a56edca36d8f1dacd021))
+* **cron:** reserve job IDs atomically ([#686](https://github.com/Gitlawb/zero/issues/686)) ([d9b882e](https://github.com/Gitlawb/zero/commit/d9b882eb0a94f38de8447cb54b57860ccd8ed053))
+* **lint:** resolve static analysis baseline ([#769](https://github.com/Gitlawb/zero/issues/769)) ([583e653](https://github.com/Gitlawb/zero/commit/583e6530bd849a8efcb2b88bbe8c297e8592e62c))
+* **providers:** retry provably pre-send transport failures ([#447](https://github.com/Gitlawb/zero/issues/447)) ([#750](https://github.com/Gitlawb/zero/issues/750)) ([8acd42a](https://github.com/Gitlawb/zero/commit/8acd42a3bd743a35807d762f23a33fb61c171839))
+* **sandbox:** add platform-specific write lock around grant state file ([#752](https://github.com/Gitlawb/zero/issues/752)) ([#755](https://github.com/Gitlawb/zero/issues/755)) ([88fb7b6](https://github.com/Gitlawb/zero/commit/88fb7b6192c1ac8173089967d5e9119f92d7a101))
+* **sandbox:** clarify scoped permission prompts ([#798](https://github.com/Gitlawb/zero/issues/798)) ([9fe02ae](https://github.com/Gitlawb/zero/commit/9fe02ae52e3234cb9dae76e0c5594a287ccbb52a))
+* **sandbox:** deny reads of git's credential stores ([#815](https://github.com/Gitlawb/zero/issues/815)) ([#816](https://github.com/Gitlawb/zero/issues/816)) ([33c94ec](https://github.com/Gitlawb/zero/commit/33c94ec7a3e7987e6e36b5fd5e037ff4e6e84c26))
+* **sandbox:** preserve user config and retry denied writes ([#801](https://github.com/Gitlawb/zero/issues/801)) ([81a5e6c](https://github.com/Gitlawb/zero/commit/81a5e6cb716ba4b7ecf7ff3ff261dfa51fd01098))
+* **sandbox:** scrub the daemon token file pointer ([#677](https://github.com/Gitlawb/zero/issues/677)) ([#818](https://github.com/Gitlawb/zero/issues/818)) ([3e7692d](https://github.com/Gitlawb/zero/commit/3e7692d8f0885d346809869935c81a9cf055d89e))
+* **swarm:** close lifecycle admission on shutdown ([#776](https://github.com/Gitlawb/zero/issues/776)) ([bdbda89](https://github.com/Gitlawb/zero/commit/bdbda89f3e42d93e8058ab3e1e9ef402659530cd))
+* **tui:** fix rendering corruption over multipass + Windows Terminal ([#709](https://github.com/Gitlawb/zero/issues/709)) ([5bb1bc1](https://github.com/Gitlawb/zero/commit/5bb1bc11c3188dcea7709ff07c8b25dda3541de8))
+* **tui:** paste clipboard images with Ctrl+V ([#534](https://github.com/Gitlawb/zero/issues/534)) ([#807](https://github.com/Gitlawb/zero/issues/807)) ([ec3b822](https://github.com/Gitlawb/zero/commit/ec3b8225050eb62f0f41a9582ed2881d2f9dcc8e))
+* **tui:** reset quiet clock for new runs ([#799](https://github.com/Gitlawb/zero/issues/799)) ([a4a805a](https://github.com/Gitlawb/zero/commit/a4a805a6c82c51cb255e909bd87ca183c8805cf2))
+* **windows:** use PowerShell for command execution ([#804](https://github.com/Gitlawb/zero/issues/804)) ([518d2e5](https://github.com/Gitlawb/zero/commit/518d2e53ba3fa073090a9b41c278face85b59b64))
+
 ## [0.5.0](https://github.com/Gitlawb/zero/compare/v0.4.0...v0.5.0) (2026-07-22)


@@ -1,7 +1,13 @@
-# Zero build/test/lint targets. AGENTS.md says "Build with `make`" and "Run `make
-# lint` before opening a PR" — these targets back those instructions.
+# Zero build/test/lint targets. AGENTS.md says to build and run quality checks
+# with `make` — these targets back those instructions.
 .DEFAULT_GOAL := build
-.PHONY: build build-all test test-race vet fmt fmt-check lint tidy clean baseline help
+GO_VERSION = $(word 2,$(shell git grep -G -h "^go[[:space:]]" -- go.mod))
+GO_TOOLCHAIN = go$(GO_VERSION)
+DEADCODE_VERSION := v0.46.0
+GOLANGCI_LINT_VERSION := v2.12.2
+GOVULNCHECK_VERSION := v1.3.0
+
+.PHONY: build build-all test test-race vet fmt fmt-check lint lint-static deadcode vulncheck tidy clean baseline help

 # Build the main CLI binary into ./zero.
 build:
@@ -33,6 +39,22 @@ fmt-check:
 # Lint = formatting check + vet (no extra tooling required).
 lint: fmt-check vet

+# Versioned tools select the toolchain from their own modules when invoked with
+# package@version. Read this module's go directive directly, without invoking
+# the possibly stale Go toolchain or consulting a multi-module GOWORK. git grep
+# works with both POSIX shells and cmd.exe, including GNU Make 3.81 on macOS.
+# The target-specific export is shell-independent.
+lint-static deadcode vulncheck: export GOTOOLCHAIN = $(GO_TOOLCHAIN)
+
+lint-static:
+	go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(GOLANGCI_LINT_VERSION) run --enable-only unused,ineffassign,staticcheck ./...
+
+deadcode:
+	go run golang.org/x/tools/cmd/deadcode@$(DEADCODE_VERSION) -test=false ./...
+
+vulncheck:
+	go run golang.org/x/vuln/cmd/govulncheck@$(GOVULNCHECK_VERSION) ./...
+
 tidy:
 	go mod tidy

@@ -55,4 +77,4 @@ baseline: build
 		--output internal/perfbench/reports/baseline.json

 help:
-	@echo "Targets: build (default), build-all, test, test-quick, vet, fmt, fmt-check, lint, tidy, clean, baseline"
+	@echo "Targets: build (default), build-all, test, test-quick, vet, fmt, fmt-check, lint, lint-static, deadcode, vulncheck, tidy, clean, baseline"
@@ -131,6 +131,7 @@ export ANTHROPIC_API_KEY=...
 export GEMINI_API_KEY=...
 export AIMLAPI_API_KEY=...
 export LONGCAT_API_KEY=...
+export FIREWORKS_API_KEY=...
 export MINIMAX_API_KEY=...
 export MINIMAXI_API_KEY=...
 ```
@@ -147,6 +148,12 @@ To configure Meituan LongCat (LongCat-2.0) directly, run:
 zero providers setup longcat --set-active
 ```

+To configure Fireworks AI directly, run:
+
+```bash
+zero providers setup fireworks --set-active
+```
+
 MiniMax presets use the Anthropic-compatible endpoints for the global and China
 regions:

@@ -367,22 +374,16 @@ variable unset and set.

 ### Code Quality and Security Checks

-Before committing any changes, ensure all Go code quality and security checks pass. Pinned `go run` commands matching CI constraints can be used directly without prior installation:
+Before committing any changes, ensure all Go code quality and security checks pass. The `make` targets below pin each tool to this module's Go version, so they load correctly even when your default `go` toolchain is older — running the plain `go run ...@version` form yourself can select the tool module's own (older) toolchain and fail to load this module instead.

-1. **Formatting**: Run `go fmt ./...` (or `make fmt`).
-2. **Vetting**: Run `go vet ./...` (or `make vet`).
-3. **Linting**: Run `go run github.com/golangci/golangci-lint/v2/cmd/[email protected] run --enable-only unused,ineffassign,staticcheck ./...`.
-4. **Vulnerability Scan**: Run `go run golang.org/x/vuln/cmd/[email protected] ./...`.
+1. **Formatting**: Run `make fmt` (or `go fmt ./...`).
+2. **Vetting**: Run `make vet` (or `go vet ./...`).
+3. **Linting**: Run `make lint-static`.
+4. **Vulnerability Scan**: Run `make vulncheck`.

-If you prefer to install these tools globally on your path, you can run:
-
-```bash
-# Install golangci-lint
-go install github.com/golangci/golangci-lint/v2/cmd/[email protected]
-
-# Install govulncheck
-go install golang.org/x/vuln/cmd/[email protected]
-```
+Use the repository-managed targets rather than globally installed binaries:
+the targets apply the module's required Go toolchain as well as the reviewed,
+pinned tool versions.

 The installed binaries land in `$GOBIN` when it is set, otherwise in
 `$GOPATH/bin` (default `~/go/bin`). That directory must be on your `PATH` to
@@ -108,10 +108,10 @@ Discovery roots (earlier wins on name collisions):
 2. **Shared multi-agent dir** — `~/.agents/skills/` when present (read-only discovery; never an install target)
 3. **Plugin skill roots** — skills bundled by active plugins (section 6)

-A missing directory is fine — Zero just omits it. Management commands (`zero skills add` / `remove` / `lock`) always write to the primary Zero dir only; `list` / `info` search primary + `~/.agents/skills`.
+A missing directory is fine — Zero just omits it. Management commands (`zero skill add` / `zero skill remove`) always write to the primary Zero dir only; `list` / `info` search primary + `~/.agents/skills`. `skill info` reports lock source/hash when present and whether the on-disk `SKILL.md` has drifted from the recorded hash.

 ```text
-~/.local/share/zero/skills/          # primary (install/remove/lock target)
+~/.local/share/zero/skills/          # primary (install/remove target)
  run-benchmarks/
    SKILL.md
  write-changelog/
@@ -749,7 +749,7 @@ flowchart TD
 - **Plugins** can add tools, hooks, and skill roots. Bootstrap always registers a
  multi-root skill tool: primary Zero skills dir, optional `~/.agents/skills`,
  then plugin skill roots (earlier wins). `internal/skills` owns that merge via
-  `LoadFromRoots` / `DiscoveryRoots`; single-root `Load` remains for install/write.
+  `LoadFromRoots`; single-root `Load` remains for install/write.
 - **Hooks** can observe or block tool lifecycle events.

 ## End-to-End Data Flow
@@ -90,9 +90,6 @@ func NewAgent(conn *Conn, deps Deps) *Agent {
 	return a
 }

-// Serve runs the connection read loop until the stream closes or ctx is done.
-func (a *Agent) Serve(ctx context.Context) error { return a.conn.Serve(ctx) }
-
 // ---- initialize ----

 func (a *Agent) handleInitialize(_ context.Context, params json.RawMessage) (any, error) {
@@ -0,0 +1,11 @@
+// Test seams: helpers only test code uses, kept out of the production binary.
+package acp
+
+import "context"
+
+// Serve runs the connection read loop until the stream closes or ctx is done.
+func (a *Agent) Serve(ctx context.Context) error { return a.conn.Serve(ctx) }
+
+func ImageBlock(base64Data, mimeType string) ContentBlock {
+	return ContentBlock{Type: "image", Data: base64Data, MimeType: mimeType}
+}
@@ -17,6 +17,7 @@ import (
 	"fmt"
 	"io"
 	"sync"
+	"sync/atomic"
 )

 // JSON-RPC 2.0 standard error codes.
@@ -80,8 +81,9 @@ type NotifyFunc func(ctx context.Context, params json.RawMessage)
 // requests/notifications — needed because ACP is bidirectional (the agent calls
 // the client for session/request_permission, fs/*, terminal/*).
 type Conn struct {
-	reader *bufio.Reader
-	w      io.Writer
+	rawReader    io.Reader // wrapped lazily in Serve, once ctx is known — see interruptibleReader
+	readerCloser io.Closer
+	w            io.Writer

 	writeMu sync.Mutex // serializes all writes to w

@@ -96,10 +98,15 @@ type Conn struct {
 	wg sync.WaitGroup // tracks in-flight inbound handlers
 }

-// NewConn builds a peer reading ndjson from r and writing ndjson to w.
+// NewConn builds a peer reading ndjson from r and writing ndjson to w. This
+// Conn does not own r: cancelling Serve's context cannot forcibly close it, so
+// a Read on r that's genuinely idle (never returns on its own) leaves Serve
+// blocked until r itself produces something — e.g. a test that closes r's own
+// write side to unblock it. Use NewOwnedConn when this Conn should own r's
+// lifetime.
 func NewConn(r io.Reader, w io.Writer) *Conn {
 	return &Conn{
-		reader:    bufio.NewReader(r),
+		rawReader: r,
 		w:         w,
 		handlers:  make(map[string]HandlerFunc),
 		notifiers: make(map[string]NotifyFunc),
@@ -107,6 +114,18 @@ func NewConn(r io.Reader, w io.Writer) *Conn {
 	}
 }

+// NewOwnedConn is like NewConn but declares that this Conn exclusively owns r:
+// if r implements io.Closer, Serve closes it on context cancellation to
+// interrupt an otherwise-idle blocking Read. Only pass a reader whose lifetime
+// this Conn should control — e.g. the process's own stdin — never a reader a
+// caller retains or shares elsewhere, since cancellation tears it down
+// permanently for every consumer, not just this Conn.
+func NewOwnedConn(r io.Reader, w io.Writer) *Conn {
+	c := NewConn(r, w)
+	c.readerCloser, _ = r.(io.Closer)
+	return c
+}
+
 // Handle registers a request handler for method.
 func (c *Conn) Handle(method string, fn HandlerFunc) { c.handlers[method] = fn }

@@ -128,17 +147,36 @@ func (c *Conn) Serve(ctx context.Context) error {
 		c.wg.Wait()
 	}()

+	interruptible := newInterruptibleReader(ctx, c.rawReader, c.readerCloser)
+	reader := bufio.NewReader(interruptible)
+
 	for {
 		// One ndjson value per line. Framing per line (rather than streaming the
 		// decoder) keeps a single malformed line from making the whole connection
 		// unrecoverable — we report -32700 and continue.
-		line, err := c.reader.ReadBytes('\n')
+		//
+		// generation brackets this SPECIFIC ReadBytes call: bufio may invoke
+		// interruptible.Read zero or more times underneath it (zero when the
+		// answer is already sitting in bufio's own buffer — including a
+		// previously-buffered, not-yet-surfaced error: bufio can return a
+		// complete line with a nil error while quietly caching an error it
+		// received ALONGSIDE that line's bytes, which then surfaces on the VERY
+		// NEXT call with no further contact with interruptible.Read at all). The
+		// generation only advances inside interruptible.Read's own cancellation
+		// branch, so "unchanged across this call" is proof this call's outcome
+		// didn't pass through that branch — whether because it was answered from
+		// the buffer or because it raced ctx.Done() and won. Only that proof
+		// makes it safe to call the outcome genuine.
+		before := interruptible.generation()
+		line, err := reader.ReadBytes('\n')
+		interrupted := interruptible.generation() != before
+
 		if len(bytes.TrimSpace(line)) > 0 {
 			c.handleLine(ctx, line)
 		}
 		if err != nil {
 			c.failAllPending(err)
-			if errors.Is(err, io.EOF) || ctx.Err() != nil {
+			if errors.Is(err, io.EOF) || interrupted {
 				return nil
 			}
 			return err
@@ -146,6 +184,100 @@ func (c *Conn) Serve(ctx context.Context) error {
 	}
 }

+// interruptibleReader wraps a reader so a context cancellation can unblock a
+// currently in-flight Read without ever discarding — or misattributing — the
+// real outcome of a call that wasn't actually blocked.
+//
+// Each Read runs the underlying call on its own goroutine and races it against
+// ctx.Done(). If the underlying call finishes first, its result is returned
+// exactly as received; ctx being cancelled a moment later has no bearing on a
+// call that already had its answer. If ctx.Done() fires first, closer (when
+// non-nil) is closed to nudge a genuinely blocked read, the generation counter
+// is bumped, and the call STILL waits for and returns the underlying call's own
+// result — never a synthesized one — since closing a reader's outcome is
+// whatever the reader itself reports for it, not ours to invent.
+//
+// The counter is what lets Serve tell a call that was actually raced against
+// cancellation apart from one merely answered while cancellation happened to be
+// pending — the distinction the read loop's own doc comment explains.
+type interruptibleReader struct {
+	inner  io.Reader
+	closer io.Closer
+	ctx    context.Context
+
+	closeOnce sync.Once
+	gen       atomic.Int64
+}
+
+func newInterruptibleReader(ctx context.Context, inner io.Reader, closer io.Closer) *interruptibleReader {
+	return &interruptibleReader{inner: inner, closer: closer, ctx: ctx}
+}
+
+func (r *interruptibleReader) generation() int64 { return r.gen.Load() }
+
+type interruptibleReadResult struct {
+	n   int
+	err error
+}
+
+// interruptibleReadDecision arbitrates whether an underlying Read completed or
+// cancellation claimed it first. Completion is recorded before the result is
+// published so cancellation cannot misclassify a finished read merely because
+// its goroutine has not sent the result yet.
+type interruptibleReadDecision struct {
+	once sync.Once
+}
+
+func (d *interruptibleReadDecision) complete() { d.once.Do(func() {}) }
+
+func (d *interruptibleReadDecision) interrupt() (claimed bool) {
+	d.once.Do(func() { claimed = true })
+	return claimed
+}
+
+// readInner records completion in the Read call's deferred epilogue. It also
+// converts a reader panic into a terminal error so the helper goroutine always
+// publishes a result for Read to join.
+func (r *interruptibleReader) readInner(p []byte, decision *interruptibleReadDecision) (res interruptibleReadResult) {
+	defer func() {
+		if recovered := recover(); recovered != nil {
+			res = interruptibleReadResult{err: fmt.Errorf("acp: reader panicked: %v", recovered)}
+		}
+		decision.complete()
+	}()
+	res.n, res.err = r.inner.Read(p)
+	return res
+}
+
+func (r *interruptibleReader) Read(p []byte) (int, error) {
+	resultCh := make(chan interruptibleReadResult, 1)
+	var decision interruptibleReadDecision
+	go func() {
+		resultCh <- r.readInner(p, &decision)
+	}()
+	select {
+	case res := <-resultCh:
+		return res.n, res.err
+	case <-r.ctx.Done():
+		// resultCh may not be readable yet even when inner.Read has returned: its
+		// goroutine can be descheduled between recording completion and publishing
+		// the result. Only interrupt a call that cancellation actually claims.
+		if decision.interrupt() {
+			r.gen.Add(1)
+			if r.closer != nil {
+				r.closeOnce.Do(func() { _ = r.closer.Close() })
+			}
+		}
+		// Wait for the real result rather than returning synthetically: p is
+		// still being written by the goroutine above until it does, so returning
+		// early would race that write, and the actual error (whatever closing
+		// the reader produced, or whatever the reader was already about to
+		// report) is what the caller should see.
+		res := <-resultCh
+		return res.n, res.err
+	}
+}
+
 // handleLine decodes and dispatches one ndjson frame. A parse failure replies
 // with -32700 (id null) and keeps the connection alive.
 func (c *Conn) handleLine(ctx context.Context, line []byte) {
@@ -3,11 +3,30 @@ package acp
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"io"
+	"sync"
+	"sync/atomic"
 	"testing"
 	"time"
 )

+type testReadCloser struct {
+	read  func([]byte) (int, error)
+	close func() error
+}
+
+func (r testReadCloser) Read(p []byte) (int, error) { return r.read(p) }
+func (r testReadCloser) Close() error               { return r.close() }
+
+type testReader func([]byte) (int, error)
+
+func (r testReader) Read(p []byte) (int, error) { return r(p) }
+
+type testWriter func([]byte) (int, error)
+
+func (w testWriter) Write(p []byte) (int, error) { return w(p) }
+
 // connPair wires two Conns together over in-memory pipes and serves both.
 func connPair(t *testing.T) (a, b *Conn, stop func()) {
 	t.Helper()
@@ -25,6 +44,275 @@ func connPair(t *testing.T) (a, b *Conn, stop func()) {
 	}
 }

+func TestConnServeCancellationInterruptsIdleRead(t *testing.T) {
+	pipeReader, writer := io.Pipe()
+	t.Cleanup(func() { _ = writer.Close() })
+	// Buffered + non-blocking send, not close: interruptibleReader retries each
+	// underlying Read on its own goroutine, so if bufio ever calls this more than
+	// once, a close() here would panic on the second call.
+	readStarted := make(chan struct{}, 1)
+	closeCalls := make(chan struct{}, 2)
+	reader := testReadCloser{
+		read: func(p []byte) (int, error) {
+			select {
+			case readStarted <- struct{}{}:
+			default:
+			}
+			return pipeReader.Read(p)
+		},
+		close: func() error {
+			closeCalls <- struct{}{}
+			return pipeReader.Close()
+		},
+	}
+	conn := NewOwnedConn(reader, io.Discard)
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { done <- conn.Serve(ctx) }()
+
+	<-readStarted
+	cancel()
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("Serve returned %v after cancellation, want nil", err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("Serve did not return after cancelling an idle connection")
+	}
+	if got := len(closeCalls); got != 1 {
+		t.Fatalf("reader Close calls = %d, want 1", got)
+	}
+}
+
+func TestConnServePreservesTerminalReadErrorDuringCancellation(t *testing.T) {
+	for _, closable := range []bool{false, true} {
+		name := "non-closable"
+		if closable {
+			name = "closable"
+		}
+		t.Run(name, func(t *testing.T) {
+			wantErr := errors.New("read failed")
+			read := testReader(func(p []byte) (int, error) {
+				return copy(p, "not json"), wantErr
+			})
+			closeCalls := make(chan struct{}, 1)
+			var reader io.Reader = read
+			if closable {
+				reader = testReadCloser{
+					read: read,
+					close: func() error {
+						closeCalls <- struct{}{}
+						return nil
+					},
+				}
+			}
+			// Buffered + non-blocking send, not close: a later change adding a
+			// second write (e.g. an additional error frame) must not panic on a
+			// repeated close of an already-closed channel.
+			writeStarted := make(chan struct{}, 1)
+			releaseWrite := make(chan struct{})
+			writer := testWriter(func(p []byte) (int, error) {
+				select {
+				case writeStarted <- struct{}{}:
+				default:
+				}
+				<-releaseWrite
+				return len(p), nil
+			})
+			newConn := NewConn
+			if closable {
+				// Ownership matters here: this case exists to prove that even a
+				// Conn entitled to close its reader on cancellation still
+				// preserves a terminal error that was already decided.
+				newConn = NewOwnedConn
+			}
+			conn := newConn(reader, writer)
+			ctx, cancel := context.WithCancel(context.Background())
+			done := make(chan error, 1)
+			go func() { done <- conn.Serve(ctx) }()
+
+			<-writeStarted
+			cancel()
+			close(releaseWrite)
+			select {
+			case err := <-done:
+				if !errors.Is(err, wantErr) {
+					t.Fatalf("Serve returned %v, want terminal read error %v", err, wantErr)
+				}
+			case <-time.After(time.Second):
+				t.Fatal("Serve did not return after terminal read error")
+			}
+			if got := len(closeCalls); got != 0 {
+				t.Fatalf("reader Close calls = %d, want 0 after terminal read", got)
+			}
+		})
+	}
+}
+
+// TestConnServePreservesReadErrorBufferedAlongsideAPriorLine is the deterministic
+// regression test for jatmn's #782 finding: a real, non-EOF ReadBytes failure can
+// be DECIDED before cancellation ever happens, yet only SURFACE afterward, and
+// must still be reported rather than swallowed as a clean shutdown.
+//
+// bufio.Reader can obtain data AND a terminal error from ONE underlying Read call
+// (io.Reader explicitly permits returning (n>0, err) together). If a delimiter is
+// found within that data, ReadBytes returns the line with a nil error for THIS
+// call, but bufio caches the error internally and returns it — WITHOUT calling the
+// underlying reader again — on the very next ReadBytes call. This test forces that
+// exact sequence: the underlying reader hands back one complete, validly-framed
+// line together with wantErr in a SINGLE call (asserted below to be its ONLY
+// call), the loop dispatches that line through a synchronous path that blocks the
+// read loop, cancellation is asserted to have happened before the loop attempts
+// its next read, and only then is the block released. By the time the read loop
+// asks for more input, cancellation is already in effect and the underlying
+// reader is never touched again — so if Serve attributed the resulting error to
+// cancellation merely because ctx was already done, it would incorrectly return
+// nil. It must instead recognize that this read was answered entirely from
+// bufio's own cache, never raced against ctx.Done(), and report wantErr.
+func TestConnServePreservesReadErrorBufferedAlongsideAPriorLine(t *testing.T) {
+	wantErr := errors.New("read failed")
+	var readCalls atomic.Int32
+	read := testReader(func(p []byte) (int, error) {
+		readCalls.Add(1)
+		// An unsupported jsonrpc version with an id takes the SYNCHRONOUS
+		// writeError path in handleLine (not a dispatched goroutine), giving this
+		// test a reliable blocking point between processing this line and the
+		// loop's next ReadBytes call.
+		return copy(p, `{"jsonrpc":"1.0","id":1}`+"\n"), wantErr
+	})
+	writeStarted := make(chan struct{}, 1)
+	releaseWrite := make(chan struct{})
+	var releaseWriteOnce sync.Once
+	release := func() { releaseWriteOnce.Do(func() { close(releaseWrite) }) }
+	t.Cleanup(release)
+	writer := testWriter(func(p []byte) (int, error) {
+		select {
+		case writeStarted <- struct{}{}:
+		default:
+		}
+		<-releaseWrite
+		return len(p), nil
+	})
+	conn := NewConn(read, writer)
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { done <- conn.Serve(ctx) }()
+
+	// The synchronous write confirms the first (and, per the panic guard above,
+	// only) read has already returned and is being processed — cancelling now
+	// lands squarely in the gap between that read and the loop's next one, never
+	// racing an in-flight interruptibleReader.Read call.
+	select {
+	case <-writeStarted:
+	case <-time.After(time.Second):
+		t.Fatal("Serve did not reach the synchronous write")
+	}
+	cancel()
+	release()
+
+	select {
+	case err := <-done:
+		if !errors.Is(err, wantErr) {
+			t.Fatalf("Serve returned %v, want the buffered terminal read error %v", err, wantErr)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("Serve did not return after the buffered terminal read error")
+	}
+	if got := readCalls.Load(); got != 1 {
+		t.Fatalf("underlying Read calls = %d, want exactly 1 (bufio must have served the second ReadBytes from its cache)", got)
+	}
+}
+
+// TestInterruptibleReaderPrefersDecidedResultOverCancellation is the regression
+// test for jatmn's second #782 finding: interruptibleReader.Read's select
+// between resultCh and ctx.Done() chooses pseudo-randomly when both are ready,
+// so a real, already-decided outcome (e.g. a terminal transport error) could be
+// misattributed to cancellation purely because ctx also happened to be done by
+// the time the select ran. Each iteration lets the underlying Read return (so
+// resultCh already holds the real outcome) before cancelling, maximizing the
+// odds of landing exactly in that ambiguous window; the generation counter must
+// never advance when the real, already-decided result is what gets returned.
+func TestInterruptibleReaderPrefersDecidedResultOverCancellation(t *testing.T) {
+	wantErr := errors.New("read failed")
+	for i := 0; i < 100; i++ {
+		resultReady := make(chan struct{})
+		read := testReader(func(p []byte) (int, error) {
+			defer close(resultReady)
+			return copy(p, "x"), wantErr
+		})
+		ctx, cancel := context.WithCancel(context.Background())
+		r := newInterruptibleReader(ctx, read, nil)
+
+		readDone := make(chan interruptibleReadResult, 1)
+		go func() {
+			n, err := r.Read(make([]byte, 8))
+			readDone <- interruptibleReadResult{n, err}
+		}()
+
+		<-resultReady
+		time.Sleep(time.Millisecond) // bias resultCh's send ahead of cancel
+		cancel()
+
+		res := <-readDone
+		if !errors.Is(res.err, wantErr) {
+			t.Fatalf("iteration %d: Read returned %v, want %v", i, res.err, wantErr)
+		}
+		if got := r.generation(); got != 0 {
+			t.Fatalf("iteration %d: generation = %d, want 0 (a decided result must never be attributed to cancellation)", i, got)
+		}
+		cancel()
+	}
+}
+
+// TestInterruptibleReadCompletionWinsBeforeResultPublication exercises the
+// actual inner-read wrapper at the handoff between the underlying Read and the
+// helper goroutine's result publication. Cancellation must not reclassify a
+// result returned by this wrapper as interrupted.
+func TestInterruptibleReadCompletionWinsBeforeResultPublication(t *testing.T) {
+	wantErr := errors.New("read failed")
+	read := testReader(func(p []byte) (int, error) {
+		return copy(p, "x"), wantErr
+	})
+	r := newInterruptibleReader(context.Background(), read, nil)
+	var decision interruptibleReadDecision
+	readComplete := make(chan struct{})
+	resultCh := make(chan interruptibleReadResult)
+	go func() {
+		res := r.readInner(make([]byte, 8), &decision)
+		close(readComplete)
+		resultCh <- res
+	}()
+
+	<-readComplete
+	if decision.interrupt() {
+		t.Fatal("cancellation claimed a read that completed before result publication")
+	}
+	res := <-resultCh
+	if res.n != 1 || !errors.Is(res.err, wantErr) {
+		t.Fatalf("inner read result = (%d, %v), want (1, %v)", res.n, res.err, wantErr)
+	}
+}
+
+func TestConnServeReportsReaderPanicAsTerminalError(t *testing.T) {
+	read := testReader(func([]byte) (int, error) {
+		panic("boom")
+	})
+	conn := NewConn(read, io.Discard)
+	done := make(chan error, 1)
+	go func() { done <- conn.Serve(context.Background()) }()
+
+	select {
+	case err := <-done:
+		const want = "acp: reader panicked: boom"
+		if err == nil || err.Error() != want {
+			t.Fatalf("Serve returned %v, want %q", err, want)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("Serve did not return after reader panic")
+	}
+}
+
 func TestConnRequestResponse(t *testing.T) {
 	a, b, stop := connPair(t)
 	defer stop()
@@ -103,10 +103,6 @@ type ContentBlock struct {

 func TextBlock(text string) ContentBlock { return ContentBlock{Type: "text", Text: text} }

-func ImageBlock(base64Data, mimeType string) ContentBlock {
-	return ContentBlock{Type: "image", Data: base64Data, MimeType: mimeType}
-}
-
 // ---- sessions ----

 // McpServer mirrors the editor-provided MCP server entry. ZERO owns its own MCP
@@ -233,10 +229,6 @@ func ToolContent(block ContentBlock) ToolCallContent {
 	return ToolCallContent{Type: "content", Content: &block}
 }

-func ToolDiff(path, oldText, newText string) ToolCallContent {
-	return ToolCallContent{Type: "diff", Path: path, OldText: oldText, NewText: newText}
-}
-
 type ToolCallLocation struct {
 	Path string `json:"path"`
 	Line *int   `json:"line,omitempty"`
@@ -16,7 +16,7 @@ import (
 func TestExecuteToolCallRejectsMissingAdditionalPermissionsBeforePrompt(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewBashTool(root))
+	registry.Register(tools.NewScopedBashTool(root, nil))

 	promptCalls := 0
 	result, err := executeToolCall(
@@ -51,7 +51,7 @@ func TestExecuteToolCallRejectsMissingAdditionalPermissionsBeforePrompt(t *testi
 func TestExecuteToolCallRejectsAdditionalPermissionsWithoutFlagBeforePrompt(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewBashTool(root))
+	registry.Register(tools.NewScopedBashTool(root, nil))

 	promptCalls := 0
 	result, err := executeToolCall(
@@ -88,7 +88,7 @@ func TestExecuteToolCallRejectsAdditionalPermissionsWithoutFlagBeforePrompt(t *t
 func TestExecuteToolCallMissingAdditionalPermissionsErrorIsActionable(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewBashTool(root))
+	registry.Register(tools.NewScopedBashTool(root, nil))

 	result, err := executeToolCall(
 		context.Background(),
@@ -117,7 +117,7 @@ func TestExecuteToolCallMissingAdditionalPermissionsErrorIsActionable(t *testing
 func TestExecuteToolCallStillPromptsForValidAdditionalPermissions(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewBashTool(root))
+	registry.Register(tools.NewScopedBashTool(root, nil))

 	promptCalls := 0
 	_, err := executeToolCall(
@@ -501,15 +501,3 @@ func hasStringPrefix(values []string, prefix []string) bool {
 	}
 	return true
 }
-
-func equalStringSlices(left []string, right []string) bool {
-	if len(left) != len(right) {
-		return false
-	}
-	for index := range left {
-		if left[index] != right[index] {
-			return false
-		}
-	}
-	return true
-}
@@ -610,15 +610,6 @@ func formatPreservedState(plan string, task *preservedTaskState, edits, tools, s
 	return preservedStateLabel + "\n" + string(encoded)
 }

-// parsePreservedState recovers the plan + skills from a prior summary's preserved
-// block. JSON escaping makes this lossless even when a skill body contains
-// markdown headings, code fences, or quotes. Returns ("", nil) when absent or
-// malformed.
-func parsePreservedState(summaryContent string) (string, []skillEntry) {
-	state := parsePreservedStateBlock(summaryContent)
-	return state.Plan, preservedSkillsToEntries(state.Skills)
-}
-
 func parsePreservedStateBlock(summaryContent string) preservedState {
 	idx := strings.LastIndex(summaryContent, preservedStateLabel)
 	if idx < 0 {
@@ -336,7 +336,7 @@ func TestRunProactiveCompactionTriggers(t *testing.T) {
 	}

 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(t.TempDir()))
+	registry.Register(tools.NewScopedReadFileTool(t.TempDir(), nil))

 	result, err := Run(context.Background(), strings.Repeat("y", 8000), provider, Options{
 		Registry:               registry,
@@ -364,7 +364,7 @@ func TestRunNoCompactionWhenContextWindowZero(t *testing.T) {
 		},
 	}
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(t.TempDir()))
+	registry.Register(tools.NewScopedReadFileTool(t.TempDir(), nil))

 	_, err := Run(context.Background(), strings.Repeat("y", 8000), provider, Options{
 		Registry:       registry,
@@ -427,7 +427,7 @@ func TestRunReactiveCompactionRecovers(t *testing.T) {
 	// the compaction closure. read_file also returns a sizeable result that
 	// bloats the history.
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(t.TempDir()))
+	registry.Register(tools.NewScopedReadFileTool(t.TempDir(), nil))

 	// ContextWindow large enough that proactive compaction never triggers, so
 	// only the reactive path can save the run.
@@ -491,7 +491,7 @@ func TestRunReactiveRetryDoesNotDoubleEmitText(t *testing.T) {
 		finalText:   "recovered",
 	}
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(t.TempDir()))
+	registry.Register(tools.NewScopedReadFileTool(t.TempDir(), nil))

 	var deltas []string
 	result, err := Run(context.Background(), strings.Repeat("z", 6000), provider, Options{
@@ -150,7 +150,7 @@ func assertNoDeferredDiscoveryMessage(t *testing.T, request zeroruntime.Completi
 func TestPartitionToolsInactiveIsByteIdenticalAndDropsToolSearch(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
 	registry.Register(fakeDeferredTool{name: "mcp__srv__a", desc: "tool a"})
 	registry.Register(fakeToolSearchTool{})

@@ -305,8 +305,8 @@ func TestPartitionToolsActiveExcludesDisabledDeferredFromDiscoveryAndExposed(t *
 func TestPartitionToolsActiveHidesUnloadedExposesLoaded(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root)) // non-deferred builtin
-	registry.Register(fakeToolSearchTool{})        // non-deferred, must stay exposed
+	registry.Register(tools.NewScopedReadFileTool(root, nil)) // non-deferred builtin
+	registry.Register(fakeToolSearchTool{})                   // non-deferred, must stay exposed
 	registry.Register(fakeDeferredTool{name: "mcp__srv__alpha", desc: "alpha tool"})
 	registry.Register(fakeDeferredTool{name: "mcp__srv__beta", desc: "beta tool"})

@@ -11,7 +11,7 @@ import (
 func TestExecuteToolCallCategorizesFilteredDenial(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))

 	result, _ := executeToolCall(context.Background(), registry, ToolCall{ID: "c1", Name: "read_file", Arguments: `{"path":"x"}`}, PermissionModeAuto, Options{
 		DisabledTools: []string{"read_file"},
@@ -0,0 +1,41 @@
+// Test seams: helpers only test code uses, kept out of the production binary.
+package agent
+
+import (
+	"github.com/Gitlawb/zero/internal/tools"
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+func equalStringSlices(left []string, right []string) bool {
+	if len(left) != len(right) {
+		return false
+	}
+	for index := range left {
+		if left[index] != right[index] {
+			return false
+		}
+	}
+	return true
+}
+
+// parsePreservedState recovers the plan + skills from a prior summary's preserved
+// block. JSON escaping makes this lossless even when a skill body contains
+// markdown headings, code fences, or quotes. Returns ("", nil) when absent or
+// malformed.
+func parsePreservedState(summaryContent string) (string, []skillEntry) {
+	state := parsePreservedStateBlock(summaryContent)
+	return state.Plan, preservedSkillsToEntries(state.Skills)
+}
+
+// partitionTools builds the per-turn advertised tool list and optional
+// tool_search discovery text. INACTIVE (DeferThreshold <= 0 or the eligible count is
+// below it): every visible tool is exposed with its full schema EXCEPT tool_search
+// (dropped so it is never advertised when it cannot help), and the discovery text is
+// empty — byte-identical to the pre-deferral output. ACTIVE: a deferred-eligible
+// tool is exposed only when loaded[name]; otherwise it is hidden and searchable
+// through tool_search. Non-deferred tools (including tool_search) are always
+// exposed. The exposed slice is alpha-sorted by name, matching the legacy order
+// so the inactive path is stable.
+func partitionTools(registry *tools.Registry, permissionMode PermissionMode, options Options, loaded map[string]bool) ([]zeroruntime.ToolDefinition, string) {
+	return partitionToolsCached(registry, permissionMode, options, loaded, nil)
+}
@@ -138,7 +138,7 @@ func TestRunResetsEmptyTurnCounterOnToolCall(t *testing.T) {
 	root := t.TempDir()
 	writeAgentTestFile(t, root+"/notes.txt", "alpha")
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))

 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
@@ -260,7 +260,7 @@ func TestRunInjectsPlanNotCalledReminderForMultiStepTask(t *testing.T) {
 	root := t.TempDir()
 	writeAgentTestFile(t, root+"/notes.txt", "alpha")
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))

 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
@@ -291,7 +291,7 @@ func TestRunDoesNotInjectPlanReminderForTrivialTask(t *testing.T) {
 	root := t.TempDir()
 	writeAgentTestFile(t, root+"/notes.txt", "alpha")
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))

 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
@@ -319,7 +319,7 @@ func TestRunDoesNotInjectNotCalledReminderWhenPlanUsed(t *testing.T) {
 	root := t.TempDir()
 	writeAgentTestFile(t, root+"/notes.txt", "alpha")
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
 	registry.Register(tools.NewUpdatePlanTool())

 	provider := &mockProvider{
@@ -349,7 +349,7 @@ func TestRunInjectsStalePlanReminderAfterManyToolCalls(t *testing.T) {
 	root := t.TempDir()
 	writeAgentTestFile(t, root+"/notes.txt", "alpha")
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
 	registry.Register(tools.NewUpdatePlanTool())

 	// Turn 1 calls update_plan (so the not-called reminder never triggers), then
@@ -383,7 +383,7 @@ func TestRunStalePlanReminderIsOneShotPerInterval(t *testing.T) {
 	root := t.TempDir()
 	writeAgentTestFile(t, root+"/notes.txt", "alpha")
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
 	registry.Register(tools.NewUpdatePlanTool())

 	turns := [][]zeroruntime.StreamEvent{
@@ -418,7 +418,7 @@ func TestRunInjectsToolOnlyProgressReminder(t *testing.T) {
 	root := t.TempDir()
 	writeAgentTestFile(t, root+"/notes.txt", "alpha")
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))

 	turns := make([][]zeroruntime.StreamEvent, 0, toolOnlyProgressReminderAt+1)
 	for i := 0; i < toolOnlyProgressReminderAt; i++ {
@@ -267,10 +267,6 @@ func Run(ctx context.Context, prompt string, provider Provider, options Options)
 			})
 		}

-		// Build the per-turn tool list first so proactive compaction can include
-		// the tool-definition tokens (they ride on every request) in its estimate.
-		// partitionTools depends only on registry/permissions/options/loaded, not on
-		// the messages, so computing it before compaction is safe.
 		// Build the per-turn tool list first so proactive compaction can include
 		// the tool-definition tokens (they ride on every request) in its estimate.
 		// partitionTools depends only on registry/permissions/options/loaded, not on
@@ -1621,9 +1617,15 @@ func sandboxRestrictedShellRetryCandidate(call ToolCall, args map[string]any, re

 func sandboxDeniedShellResult(result tools.Result) bool {
 	if result.ExecutionOutcome != nil {
-		// Typed denials must be handled by their exact capability path. Never
-		// turn a structured narrow denial into the legacy unrestricted retry.
-		return false
+		// Only a typed platform denial that explicitly requests unrestricted
+		// recovery may enter the legacy retry path. Narrow capability denials
+		// remain on their exact capability path.
+		denial := result.ExecutionOutcome.Denial
+		return denial != nil &&
+			denial.Source == execution.DenialSourcePlatformSandbox &&
+			denial.Capability.Kind == execution.CapabilityUnrestricted &&
+			denial.Recoverable &&
+			denial.NextAction == execution.DenialNextActionRequestApproval
 	}
 	return result.Status == tools.StatusError && result.Meta[tools.SandboxLikelyDeniedMeta] == "true"
 }
@@ -2866,19 +2868,6 @@ func permissionActionFromSandbox(action sandbox.Action) PermissionAction {
 	}
 }

-// partitionTools builds the per-turn advertised tool list and optional
-// tool_search discovery text. INACTIVE (DeferThreshold <= 0 or the eligible count is
-// below it): every visible tool is exposed with its full schema EXCEPT tool_search
-// (dropped so it is never advertised when it cannot help), and the discovery text is
-// empty — byte-identical to the pre-deferral output. ACTIVE: a deferred-eligible
-// tool is exposed only when loaded[name]; otherwise it is hidden and searchable
-// through tool_search. Non-deferred tools (including tool_search) are always
-// exposed. The exposed slice is alpha-sorted by name, matching the legacy order
-// so the inactive path is stable.
-func partitionTools(registry *tools.Registry, permissionMode PermissionMode, options Options, loaded map[string]bool) ([]zeroruntime.ToolDefinition, string) {
-	return partitionToolsCached(registry, permissionMode, options, loaded, nil)
-}
-
 // partitionToolsCached is partitionTools with an optional per-tool definition
 // cache. The partitioning itself (visibility, deferral, ordering) is recomputed
 // every call — it must be, because a tool's deferred state can flip mid-run (e.g.
@@ -64,6 +64,22 @@ func TestTypedExecutionOutcomeOverridesLegacySandboxHeuristics(t *testing.T) {
 		t.Fatal("narrow protected-metadata denial must not become an unrestricted retry")
 	}

+	nonRecoverableDenial := protectedDenial
+	nonRecoverableDenial.ExecutionOutcome = &execution.Outcome{
+		State: execution.StateDenied,
+		Kind:  execution.OutcomeEnforcementDenied,
+		Denial: &execution.Denial{
+			Capability:  execution.Capability{Kind: execution.CapabilityUnrestricted, Scope: "host"},
+			Source:      execution.DenialSourcePlatformSandbox,
+			Reason:      "sandbox enforcement failed closed",
+			Recoverable: false,
+			NextAction:  execution.DenialNextActionRequestApproval,
+		},
+	}
+	if sandboxRestrictedShellRetryCandidate(call, nil, nonRecoverableDenial, options) {
+		t.Fatal("non-recoverable sandbox denial must not become an unrestricted retry")
+	}
+
 	networkDenial := protectedDenial
 	networkDenial.ExecutionOutcome = &execution.Outcome{
 		State: execution.StateDenied,
@@ -288,6 +304,18 @@ func (tool *sandboxDeniedRetryTool) Run(_ context.Context, args map[string]any)
 	return tools.Result{
 		Status: tools.StatusError,
 		Output: "touch: cannot touch '/home/user/.npm/cache': Read-only file system",
+		ExecutionOutcome: &execution.Outcome{
+			State: execution.StateDenied,
+			Kind:  execution.OutcomeEnforcementDenied,
+			Exit:  &execution.Exit{Code: 1},
+			Denial: &execution.Denial{
+				Capability:  execution.Capability{Kind: execution.CapabilityUnrestricted, Scope: "host"},
+				Source:      execution.DenialSourcePlatformSandbox,
+				Reason:      "sandbox blocked command execution",
+				Recoverable: true,
+				NextAction:  execution.DenialNextActionRequestApproval,
+			},
+		},
 		Meta: map[string]string{
 			"exit_code":                    "1",
 			tools.SandboxLikelyDeniedMeta:  "true",
@@ -863,9 +891,6 @@ func TestRunReportsTruncationFinishReason(t *testing.T) {
 	if result.FinishReason != zeroruntime.FinishReasonLength {
 		t.Fatalf("FinishReason = %q, want %q", result.FinishReason, zeroruntime.FinishReasonLength)
 	}
-	if !result.Truncated() {
-		t.Fatal("Truncated() = false, want true for a length-capped response")
-	}
 	if result.TruncationNotice() == "" {
 		t.Fatal("TruncationNotice() empty for a truncated response")
 	}
@@ -883,7 +908,7 @@ func TestRunNormalCompletionIsNotTruncated(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if result.Truncated() || result.TruncationNotice() != "" {
+	if result.TruncationNotice() != "" {
 		t.Fatalf("normal completion reported as truncated: reason=%q", result.FinishReason)
 	}
 }
@@ -960,7 +985,7 @@ func TestRunEmitsUsageEvents(t *testing.T) {
 func TestRunAdvertisesRuntimeToolDefinitions(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{{
 			{Type: zeroruntime.StreamEventText, Content: "done"},
@@ -1167,9 +1192,9 @@ func TestRunRequestsPermissionBeforeWebSearchExecution(t *testing.T) {
 func TestRunFiltersAdvertisedTools(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
-	registry.Register(tools.NewGrepTool(root))
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
+	registry.Register(tools.NewScopedGrepTool(root, nil))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{{
 			{Type: zeroruntime.StreamEventText, Content: "done"},
@@ -1197,7 +1222,7 @@ func TestRunFiltersAdvertisedTools(t *testing.T) {
 func TestRunRejectsFilteredToolCalls(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
@@ -1234,7 +1259,7 @@ func TestRunRejectsFilteredToolCalls(t *testing.T) {
 func TestRunRejectsToolCallsOutsideEnabledList(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
@@ -1272,7 +1297,7 @@ func TestRunExecutesToolCallThroughRegistry(t *testing.T) {
 	root := t.TempDir()
 	writeAgentTestFile(t, filepath.Join(root, "notes.txt"), "alpha\nbeta\n")
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
@@ -1356,7 +1381,7 @@ func TestRunPreservesRequestPrefixAcrossTurns(t *testing.T) {
 func TestRunSanitizesMalformedToolCallArgumentsBeforeRetry(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
@@ -1424,7 +1449,7 @@ func TestRunRecoversFirstObjectFromConcatenatedToolArgs(t *testing.T) {
 		t.Fatal(err)
 	}
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
@@ -1471,8 +1496,8 @@ func TestRunDefersSelfCorrectFeedbackUntilAfterToolBatch(t *testing.T) {
 		t.Fatal(err)
 	}
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))

 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
@@ -1547,7 +1572,7 @@ func TestRunBatchesSelfCorrectOncePerTurn(t *testing.T) {
 	// after a later call in the same turn supersedes it.
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))

 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
@@ -1604,7 +1629,7 @@ func TestRunBatchesSelfCorrectOncePerTurn(t *testing.T) {
 func TestRunDeniesPromptToolWithoutUnsafePermission(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
 	provider := providerCallingWriteFileThenAnswer("write denied")
 	var permissionEvents []PermissionEvent

@@ -1647,7 +1672,7 @@ func TestRunDeniesPromptToolWithoutUnsafePermission(t *testing.T) {
 func TestRunRequestsPromptToolPermissionBeforeExecution(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
 	provider := providerCallingWriteFileThenAnswer("write approved")
 	var requests []PermissionRequest
 	var permissionEvents []PermissionEvent
@@ -1703,7 +1728,7 @@ func TestRunRequestsPromptToolPermissionBeforeExecution(t *testing.T) {
 func TestRunAllowsWorkspaceWriteWithoutPromptWhenSandboxPolicyPermits(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
 	provider := providerCallingWriteFileThenAnswer("write done")
 	var permissionEvents []PermissionEvent

@@ -1752,7 +1777,7 @@ func TestRunAllowsWorkspaceWriteWithoutPromptWhenSandboxPolicyPermits(t *testing
 func TestRunDeniesPromptToolWhenPermissionRequestDenied(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
 	provider := providerCallingWriteFileThenAnswer("write denied")
 	var requests []PermissionRequest
 	var permissionEvents []PermissionEvent
@@ -1800,7 +1825,7 @@ func TestRunDeniesPromptToolWhenPermissionRequestDenied(t *testing.T) {
 func TestRunAbortsWhenPermissionRequestCanceled(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
 	provider := providerCallingWriteFileThenAnswer("write should not continue")
 	var permissionEvents []PermissionEvent

@@ -1896,7 +1921,7 @@ func TestRunPersistsAlwaysAllowPermissionDecision(t *testing.T) {
 		t.Fatal(err)
 	}
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
 	provider := providerCallingWriteFileThenAnswer("write approved")
 	var permissionEvents []PermissionEvent
 	policy := sandbox.DefaultPolicy()
@@ -1968,7 +1993,7 @@ func TestRunSessionAllowSkipsMatchingPromptWithoutPersistentGrant(t *testing.T)
 		t.Fatal(err)
 	}
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
@@ -2049,7 +2074,7 @@ func TestRunSessionAllowSkipsMatchingPromptWithoutPersistentGrant(t *testing.T)
 func TestRunCommandPrefixApprovalSkipsLaterMatchingBashPrompt(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewBashTool(root))
+	registry.Register(tools.NewScopedBashTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
@@ -2251,7 +2276,7 @@ func TestRunPersistentCommandPrefixApprovalSkipsFutureSessionPrompt(t *testing.T
 		t.Fatal(err)
 	}
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewBashTool(root))
+	registry.Register(tools.NewScopedBashTool(root, nil))
 	policy := sandbox.DefaultPolicy()
 	policy.Network = sandbox.NetworkAllow

@@ -2358,7 +2383,7 @@ func TestRunPersistentCommandPrefixStillPromptsForNetwork(t *testing.T) {
 		t.Fatalf("seed command prefix: %v", err)
 	}
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewBashTool(root))
+	registry.Register(tools.NewScopedBashTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
@@ -2407,7 +2432,11 @@ func TestRunApprovedNetworkBashPromptAppliesTurnNetworkGrant(t *testing.T) {
 	root := t.TempDir()
 	command := "PATH=.:$PATH curl https://example.com"
 	if runtime.GOOS == "windows" {
-		command = "set PATH=.;%PATH% && curl https://example.com"
+		if windowsTestUsesPowerShell() {
+			command = `$env:PATH = '.;' + $env:PATH; curl.cmd https://example.com`
+		} else {
+			command = "set PATH=.;%PATH% && curl https://example.com"
+		}
 		fakeCurl := filepath.Join(root, "curl.cmd")
 		if err := os.WriteFile(fakeCurl, []byte("@echo fake curl %*\r\n"), 0o755); err != nil {
 			t.Fatal(err)
@@ -2419,7 +2448,7 @@ func TestRunApprovedNetworkBashPromptAppliesTurnNetworkGrant(t *testing.T) {
 		}
 	}
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewBashTool(root))
+	registry.Register(tools.NewScopedBashTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
@@ -2486,7 +2515,7 @@ func TestRunApprovedNetworkBashPromptAppliesTurnNetworkGrant(t *testing.T) {
 func TestRunDoesNotOfferPrefixApprovalForUnsafeBashCommand(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewBashTool(root))
+	registry.Register(tools.NewScopedBashTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
@@ -2528,13 +2557,17 @@ func TestRunDoesNotOfferPrefixApprovalForUnsafeBashCommand(t *testing.T) {

 func TestRunPromptsForDestructiveShellInsteadOfSandboxDeny(t *testing.T) {
 	root := t.TempDir()
+	command := "echo rm -rf /"
+	if runtime.GOOS == "windows" && windowsTestUsesPowerShell() {
+		command = `Write-Output 'rm -rf /'`
+	}
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewBashTool(root))
+	registry.Register(tools.NewScopedBashTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
 				{Type: zeroruntime.StreamEventToolCallStart, ToolCallID: "call-1", ToolName: "bash"},
-				{Type: zeroruntime.StreamEventToolCallDelta, ToolCallID: "call-1", ArgumentsFragment: `{"command":"echo rm -rf /"}`},
+				{Type: zeroruntime.StreamEventToolCallDelta, ToolCallID: "call-1", ArgumentsFragment: `{"command":` + quoteJSONString(command) + `}`},
 				{Type: zeroruntime.StreamEventToolCallEnd, ToolCallID: "call-1"},
 				{Type: zeroruntime.StreamEventDone},
 			},
@@ -2598,7 +2631,7 @@ func TestRunAlwaysAllowWithoutSandboxStillAllowsCall(t *testing.T) {
 	// prior code denied it because persistPermissionGrant errors when Sandbox==nil.
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
 	provider := providerCallingWriteFileThenAnswer("write approved")
 	var permissionEvents []PermissionEvent

@@ -2630,6 +2663,12 @@ func TestRunAlwaysAllowWithoutSandboxStillAllowsCall(t *testing.T) {
 	}
 }

+func windowsTestUsesPowerShell() bool {
+	executable, _ := tools.HostShellCommand("")
+	name := strings.ToLower(filepath.Base(executable))
+	return strings.Contains(name, "powershell") || strings.HasPrefix(name, "pwsh")
+}
+
 func containsPermissionDecision(decisions []PermissionDecisionAction, want PermissionDecisionAction) bool {
 	for _, decision := range decisions {
 		if decision == want {
@@ -2662,7 +2701,7 @@ func TestRunCancellationPreservesContextCanceledIdentity(t *testing.T) {
 func TestRunGrantsPromptToolInUnsafeMode(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
 	provider := providerCallingWriteFileThenAnswer("write done")
 	var permissionEvents []PermissionEvent

@@ -2714,7 +2753,7 @@ func TestRunEmitsPermissionEventForPersistentSandboxGrant(t *testing.T) {
 		t.Fatal(err)
 	}
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
 	provider := providerCallingWriteFileThenAnswer("write done")
 	var permissionEvents []PermissionEvent

@@ -2893,7 +2932,7 @@ func TestRunAppliesSandboxEvenInUnsafeMode(t *testing.T) {
 	root := t.TempDir()
 	outside := filepath.Join(tempDirOutsideDefaultTemp(t), "escape.txt")
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
 	provider := providerCallingWritePathThenAnswer(outside, "sandbox handled")
 	var permissionEvents []PermissionEvent

@@ -2942,7 +2981,7 @@ func TestRunStopsAfterMaxTurns(t *testing.T) {
 	root := t.TempDir()
 	writeAgentTestFile(t, filepath.Join(root, "notes.txt"), "alpha")
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{{
 			{Type: zeroruntime.StreamEventToolCallStart, ToolCallID: "call-1", ToolName: "read_file"},
@@ -2972,7 +3011,7 @@ func TestRunRequestsFinalAnswerAfterMaxTurns(t *testing.T) {
 	root := t.TempDir()
 	writeAgentTestFile(t, filepath.Join(root, "notes.txt"), "alpha")
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
@@ -3163,22 +3202,17 @@ func TestBuildSystemPromptInjectsHostShellContext(t *testing.T) {
 		t.Fatalf("expected operating system in environment block, got %q", prompt)
 	}
 	if runtime.GOOS == "windows" {
-		for _, want := range []string{"Windows cmd.exe syntax", "cwd argument", "MSYS binaries", "grep", "require_escalated", "use double quotes around the value"} {
-			if !strings.Contains(prompt, want) {
-				t.Fatalf("expected Windows shell guidance to mention %q, got %q", want, prompt)
-			}
+		wants := []string{"workdir/cwd", "MSYS binaries"}
+		if windowsTestUsesPowerShell() {
+			wants = append(wants, "PowerShell", "Get-ChildItem", "Select-String", "$env:NAME", "require_escalated")
+		} else {
+			wants = append(wants, "cmd.exe", "double quotes")
 		}
-		// The examples must themselves use the safe (double-quoted) form; a
-		// single-quoted example here would teach the model the exact syntax
-		// that fails under cmd.exe.
-		for _, want := range []string{`--jq ".a | b"`, `-run "A|B"`} {
+		for _, want := range wants {
 			if !strings.Contains(prompt, want) {
-				t.Fatalf("expected double-quoted example %q in Windows shell guidance, got %q", want, prompt)
+				t.Fatalf("expected selected Windows shell guidance to mention %q, got %q", want, prompt)
 			}
 		}
-		if strings.Contains(prompt, `'.a | b'`) || strings.Contains(prompt, `'A|B'`) {
-			t.Fatalf("Windows shell guidance must not show the unsafe single-quoted form, got %q", prompt)
-		}
 	} else if !strings.Contains(prompt, "/bin/sh syntax") {
 		t.Fatalf("expected POSIX shell guidance in prompt, got %q", prompt)
 	}
@@ -3231,7 +3265,7 @@ func TestBuildSystemPromptAllowsSpecModeOverride(t *testing.T) {
 func TestSpecDraftAdvertisesOnlySafeDraftTools(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	for _, tool := range tools.CoreTools(root) {
+	for _, tool := range tools.CoreToolsScoped(root, nil) {
 		registry.Register(tool)
 	}
 	specmode.RegisterDraftTools(registry, root, nil)
@@ -3268,7 +3302,7 @@ func TestSpecDraftAdvertisesOnlySafeDraftTools(t *testing.T) {
 func TestSpecDraftDeniesHiddenToolCalls(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewWriteFileTool(root))
+	registry.Register(tools.NewScopedWriteFileTool(root, nil))
 	provider := providerCallingWriteFileThenAnswer("done")

 	result, err := Run(context.Background(), "draft", provider, Options{
@@ -3301,7 +3335,7 @@ func TestSpecDraftDeniesHiddenToolCalls(t *testing.T) {
 func TestSpecDraftDeniesBashToolCalls(t *testing.T) {
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewBashTool(root))
+	registry.Register(tools.NewScopedBashTool(root, nil))
 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
 			{
@@ -3442,7 +3476,7 @@ func TestRunSurfacesDroppedToolCallAlongsideValidCall(t *testing.T) {
 		t.Fatal(err)
 	}
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root))
+	registry.Register(tools.NewScopedReadFileTool(root, nil))

 	provider := &mockProvider{
 		turns: [][]zeroruntime.StreamEvent{
@@ -14,7 +14,7 @@ func TestPartitionToolsActiveAppendsLoadedToolAfterEagerBlock(t *testing.T) {
 	// "read_file".
 	root := t.TempDir()
 	registry := tools.NewRegistry()
-	registry.Register(tools.NewReadFileTool(root)) // non-deferred, "read_file"
+	registry.Register(tools.NewScopedReadFileTool(root, nil)) // non-deferred, "read_file"
 	registry.Register(fakeToolSearchTool{})
 	registry.Register(fakeDeferredTool{name: "mcp__srv__alpha", desc: "alpha"})
 	registry.Register(fakeDeferredTool{name: "mcp__srv__beta", desc: "beta"})
@@ -91,7 +91,7 @@ func (c *profileController) maybeEscalate() (PostureEscalation, bool) {
 	if c.policy == nil || c.escalated {
 		return PostureEscalation{}, false
 	}
-	if !(c.failureTripped || c.riskTripped || c.scTripped || c.uncertainTrip) {
+	if !c.failureTripped && !c.riskTripped && !c.scTripped && !c.uncertainTrip {
 		return PostureEscalation{}, false
 	}
 	c.escalated = true
@@ -180,7 +180,7 @@ func TestInlineAdditionalPermissionsRequiresPromptUnderAutoAllow(t *testing.T) {
 		},
 	}
 	decision := &sandbox.Decision{Action: sandbox.ActionAllow, AutoAllowed: true}
-	if !shouldRequestPermission(tools.NewBashTool(t.TempDir()), args, false, decision) {
+	if !shouldRequestPermission(tools.NewScopedBashTool(t.TempDir(), nil), args, false, decision) {
 		t.Fatal("inline additional permissions must request approval even when a sandboxed shell would otherwise auto-allow")
 	}
 }
@@ -11,6 +11,7 @@ import (

 	"github.com/Gitlawb/zero/internal/config"
 	"github.com/Gitlawb/zero/internal/repomap"
+	"github.com/Gitlawb/zero/internal/tools"
 	"github.com/Gitlawb/zero/internal/workspaceseed"
 )

@@ -310,11 +311,7 @@ func workspaceContext(cwd string) string {
 	b.WriteString("<environment>\n")
 	b.WriteString("Working directory: " + cwd + "\n")
 	b.WriteString("Operating system: " + runtime.GOOS + "\n")
-	if runtime.GOOS == "windows" {
-		b.WriteString("Shell syntax: Windows cmd.exe syntax for exec_command/bash tools. To put | & > < etc inside an arg value, use double quotes around the value, not single quotes (single quotes do not protect metachars in cmd.exe): gh --jq \".a | b\", go test -run \"A|B\". Do not pipe to or invoke POSIX coreutils from Git for Windows (usr\\bin head/grep/tail/cat/...): they are MSYS binaries and fail under the write-restricted sandbox; use native Zero tools (grep, read_file, list_directory, glob) or cmd.exe findstr/more instead, or sandbox_permissions require_escalated only when host-level execution is truly required. Prefer the workdir/cwd argument over cd when changing directories.\n")
-	} else {
-		b.WriteString("Shell syntax: /bin/sh syntax for exec_command/bash tools; prefer the workdir/cwd argument instead of cd when changing directories.\n")
-	}
+	b.WriteString(tools.HostShellEnvironmentGuidance() + "\n")
 	if branch := gitBranchForPrompt(cwd); branch != "" {
 		b.WriteString("Git branch: " + branch + "\n")
 	}
@@ -427,13 +427,6 @@ type Result struct {
 	IncompleteReason string
 }

-// Truncated reports whether the final response ended abnormally (cut off at the
-// output token cap or withheld by a content filter) rather than completing
-// naturally. Callers can use it to warn the user that FinalAnswer is incomplete.
-func (result Result) Truncated() bool {
-	return result.FinishReason != ""
-}
-
 // TruncationNotice returns a user-facing warning when the final response was
 // truncated, or "" for a normal completion. Shared by the CLI and TUI so the
 // wording stays consistent.
@@ -31,10 +31,6 @@ type AgentRunner interface {

 type AgentRunnerFunc func(context.Context, AgentRunInput) AgentRunResult

-func (fn AgentRunnerFunc) Run(ctx context.Context, input AgentRunInput) AgentRunResult {
-	return fn(ctx, input)
-}
-
 // defaultAgentOutputLimit caps captured stdout/stderr per stream so a chatty or
 // runaway agent cannot exhaust memory or bloat the benchmark report.
 const defaultAgentOutputLimit = 1 << 20 // 1 MiB per stream
@@ -0,0 +1,8 @@
+// Test seams: helpers only test code uses, kept out of the production binary.
+package agenteval
+
+import "context"
+
+func (fn AgentRunnerFunc) Run(ctx context.Context, input AgentRunInput) AgentRunResult {
+	return fn(ctx, input)
+}
@@ -125,9 +125,7 @@ func Score(suite Suite, input ScoreInput) Report {
 	if len(task.RequiredTraceEvents) > 0 {
 		report.Results = append(report.Results, scoreTraceEvents(task.RequiredTraceEvents, input))
 	}
-	for _, result := range unknownCommandResults(input.CommandResults, seenCommands, input) {
-		report.Results = append(report.Results, result)
-	}
+	report.Results = append(report.Results, unknownCommandResults(input.CommandResults, seenCommands, input)...)
 	report.finishSummary()
 	return report
 }
@@ -40,14 +40,14 @@ func FormatFacts(info repoinfo.Info) string {
 	b.WriteString("Pre-computed repository facts (from a local scan — verify and fill gaps):\n")

 	if info.PrimaryLanguage != "" {
-		b.WriteString(fmt.Sprintf("- Primary language: %s (of %d detected)\n", info.PrimaryLanguage, info.LanguageCount))
+		fmt.Fprintf(&b, "- Primary language: %s (of %d detected)\n", info.PrimaryLanguage, info.LanguageCount)
 	}
 	if langs := topLanguages(info.Languages, 5); langs != "" {
 		b.WriteString("- Languages: " + langs + "\n")
 	}
-	b.WriteString(fmt.Sprintf("- Size: ~%d files, ~%d LOC, max dir depth %d\n", info.FileCount, info.LOCEstimate, info.MaxDepth))
+	fmt.Fprintf(&b, "- Size: ~%d files, ~%d LOC, max dir depth %d\n", info.FileCount, info.LOCEstimate, info.MaxDepth)
 	if info.WorkspaceType != "" && info.WorkspaceType != "none" {
-		b.WriteString(fmt.Sprintf("- Workspace: %s (%d packages)\n", info.WorkspaceType, info.WorkspacePackageCount))
+		fmt.Fprintf(&b, "- Workspace: %s (%d packages)\n", info.WorkspaceType, info.WorkspacePackageCount)
 	}
 	if len(info.BuildTools) > 0 {
 		b.WriteString("- Build tools: " + strings.Join(info.BuildTools, ", ") + "\n")
@@ -149,12 +149,9 @@ func TestTerminateProcessKillsForkedChildren(t *testing.T) {

 	// The forked child must be gone too (poll until reaped by init).
 	deadline := time.Now().Add(2 * time.Second)
-	for {
-		// Only ESRCH proves the child is gone; any other error (e.g. EPERM) would
-		// wrongly pass the test, so treat it as still-present and keep polling.
-		if errors.Is(syscall.Kill(childPID, syscall.Signal(0)), syscall.ESRCH) {
-			break // child no longer exists
-		}
+	// Only ESRCH proves the child is gone; any other error (e.g. EPERM) would
+	// wrongly pass the test, so treat it as still-present and keep polling.
+	for !errors.Is(syscall.Kill(childPID, syscall.Signal(0)), syscall.ESRCH) {
 		if time.Now().After(deadline) {
 			_ = syscall.Kill(childPID, syscall.SIGKILL)
 			t.Fatalf("forked child %d survived terminateProcess — group kill failed", childPID)
@@ -27,6 +27,8 @@ Usage:
 Not meant to be run interactively — point your editor's ACP / external-agent
 setting at "zero acp".`

+var acpSignalContext = signalContext
+
 // runACP serves ACP over stdio so an editor can drive ZERO's agent core. It
 // speaks JSON-RPC 2.0 (newline-delimited JSON) on stdin/stdout; stderr stays free
 // for human-readable diagnostics. The session lifecycle maps onto ZERO's own
@@ -42,7 +44,9 @@ func runACP(args []string, stdout io.Writer, stderr io.Writer, deps appDeps) int
 		}
 	}

-	conn := acp.NewConn(deps.stdin, stdout)
+	// The process's own stdin belongs exclusively to this Conn for the life of
+	// the command, so cancellation may close it to interrupt an idle read.
+	conn := acp.NewOwnedConn(deps.stdin, stdout)
 	acp.NewAgent(conn, acp.Deps{
 		ResolveConfig: deps.resolveConfig,
 		DiscoverModels: func(ctx context.Context, profile config.ProviderProfile) ([]providermodeldiscovery.Model, error) {
@@ -73,9 +77,9 @@ func runACP(args []string, stdout io.Writer, stderr io.Writer, deps appDeps) int
 		AgentInfo:            acp.Implementation{Name: "zero", Version: version},
 	})

-	ctx, stop := signalContext()
+	ctx, stop := acpSignalContext()
 	defer stop()
-	if err := conn.Serve(ctx); err != nil && ctx.Err() == nil {
+	if err := conn.Serve(ctx); err != nil {
 		return writeAppError(stderr, "acp: "+err.Error(), exitCrash)
 	}
 	return exitSuccess
@@ -0,0 +1,120 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+type acpTestReader func([]byte) (int, error)
+
+func (r acpTestReader) Read(p []byte) (int, error) { return r(p) }
+
+type acpTestWriter func([]byte) (int, error)
+
+func (w acpTestWriter) Write(p []byte) (int, error) { return w(p) }
+
+func installACPTestContext(t *testing.T) context.CancelFunc {
+	t.Helper()
+	ctx, cancel := context.WithCancel(context.Background())
+	previous := acpSignalContext
+	acpSignalContext = func() (context.Context, context.CancelFunc) {
+		return ctx, cancel
+	}
+	t.Cleanup(func() {
+		cancel()
+		acpSignalContext = previous
+	})
+	return cancel
+}
+
+func TestRunACPCancellationPreservesTerminalReadError(t *testing.T) {
+	cancel := installACPTestContext(t)
+	wantErr := errors.New("transport read failed")
+	reader := acpTestReader(func(p []byte) (int, error) {
+		return copy(p, `{"jsonrpc":"1.0","id":1}`+"\n"), wantErr
+	})
+	writeStarted := make(chan struct{}, 1)
+	releaseWrite := make(chan struct{})
+	var stdout bytes.Buffer
+	writer := acpTestWriter(func(p []byte) (int, error) {
+		writeStarted <- struct{}{}
+		<-releaseWrite
+		return stdout.Write(p)
+	})
+	var stderr bytes.Buffer
+	done := make(chan int, 1)
+	go func() {
+		done <- runACP(nil, writer, &stderr, fillAppDeps(appDeps{stdin: reader}))
+	}()
+
+	select {
+	case <-writeStarted:
+	case <-time.After(time.Second):
+		t.Fatal("ACP did not reach the response write")
+	}
+	// Keep Serve in the synchronous write until cancellation is observable. The
+	// regression requires the genuine read error to win over that cancellation.
+	cancel()
+	close(releaseWrite)
+
+	select {
+	case code := <-done:
+		if code != exitCrash {
+			t.Fatalf("exit code = %d, want crash %d", code, exitCrash)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("ACP did not exit after terminal read error")
+	}
+	if got := stderr.String(); !strings.Contains(got, "acp: "+wantErr.Error()) {
+		t.Fatalf("stderr = %q, want terminal read error", got)
+	}
+}
+
+func TestRunACPIdleCancellationExitsCleanly(t *testing.T) {
+	cancel := installACPTestContext(t)
+	pipeReader, pipeWriter := io.Pipe()
+	t.Cleanup(func() { _ = pipeWriter.Close() })
+	readStarted := make(chan struct{}, 1)
+	reader := &acpNotifyingReadCloser{ReadCloser: pipeReader, readStarted: readStarted}
+	var stdout, stderr bytes.Buffer
+	done := make(chan int, 1)
+	go func() {
+		done <- runACP(nil, &stdout, &stderr, fillAppDeps(appDeps{stdin: reader}))
+	}()
+
+	select {
+	case <-readStarted:
+	case <-time.After(time.Second):
+		t.Fatal("ACP did not begin reading")
+	}
+	cancel()
+
+	select {
+	case code := <-done:
+		if code != exitSuccess {
+			t.Fatalf("exit code = %d, want success %d; stderr: %s", code, exitSuccess, stderr.String())
+		}
+	case <-time.After(time.Second):
+		t.Fatal("ACP did not exit after cancellation")
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+type acpNotifyingReadCloser struct {
+	io.ReadCloser
+	readStarted chan<- struct{}
+	once        sync.Once
+}
+
+func (r *acpNotifyingReadCloser) Read(p []byte) (int, error) {
+	r.once.Do(func() { r.readStarted <- struct{}{} })
+	return r.ReadCloser.Read(p)
+}
@@ -515,9 +515,7 @@ func agentEvalReportFromBenchmark(suite agenteval.Suite, report agenteval.Benchm
 		if task.Agent.Truncated {
 			converted.Truncated = true
 		}
-		for _, failure := range agentEvalFailuresFromTaskReport(task) {
-			converted.Failures = append(converted.Failures, failure)
-		}
+		converted.Failures = append(converted.Failures, agentEvalFailuresFromTaskReport(task)...)
 	}
 	return converted
 }
@@ -59,7 +59,7 @@ var completionRoot = completionNode{
 			{names: []string{"delete", "rm"}}, {names: []string{"edit"}}, {names: []string{"path"}},
 		}},
 		{names: []string{"plugins", "plugin"}, children: []completionNode{
-			{names: []string{"list"}}, {names: []string{"add"}}, {names: []string{"remove", "rm"}},
+			{names: []string{"list"}}, {names: []string{"add"}}, {names: []string{"info"}}, {names: []string{"remove", "rm"}},
 		}},
 		{names: []string{"backends", "backend"}, children: leafNodes("doctor")},
 		{names: []string{"skills", "skill"}, children: []completionNode{
@@ -159,6 +159,8 @@ func TestCompletionTreeCoversAliasesNestingAndCommonFlags(t *testing.T) {
 	assertCandidates(t, byPath["mcp oauth"], "login", "logout", "status")
 	assertCandidates(t, byPath["sandbox grants"], "list", "allow", "deny", "revoke", "clear")
 	assertCandidates(t, byPath["completions"], "bash", "zsh", "fish", "powershell", "elvish")
+	assertCandidates(t, byPath["plugins"], "list", "add", "info", "remove", "rm")
+	assertCandidates(t, byPath["plugin"], "list", "add", "info", "remove", "rm")
 }

 func assertCandidates(t *testing.T, got []string, wants ...string) {
@@ -139,6 +139,7 @@ func runSkillInfo(args []string, dir string, stdout io.Writer, stderr io.Writer)
 	}
 	if info.Hash != "" {
 		lines = append(lines, "  hash: "+info.Hash)
+		lines = append(lines, fmt.Sprintf("  hash drift: %t", info.HashDrift))
 	}
 	lines = append(lines, "  path: "+info.Skill.Path)
 	if _, err := fmt.Fprintln(stdout, redaction.RedactString(strings.Join(lines, "\n"), redaction.Options{})); err != nil {
@@ -83,6 +83,48 @@ func TestRunSkillAddInfoRemove(t *testing.T) {
 	if !strings.Contains(info, src) || !strings.Contains(info, "sha256:") {
 		t.Fatalf("info missing source/hash:\n%s", info)
 	}
+	if !strings.Contains(info, "hash drift: false") {
+		t.Fatalf("info missing hash drift status:\n%s", info)
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	if exit := runWithDeps([]string{"skill", "info", "confirmation-policy", "--json"}, &stdout, &stderr, deps); exit != 0 {
+		t.Fatalf("skill info --json exit = %d, stderr = %s", exit, stderr.String())
+	}
+	var beforeJSON map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &beforeJSON); err != nil {
+		t.Fatalf("parse skill info json: %v\n%s", err, stdout.String())
+	}
+	if beforeJSON["hashDrift"] != false {
+		t.Fatalf("hashDrift before edit = %#v, want false", beforeJSON["hashDrift"])
+	}
+
+	skillPath := filepath.Join(skillsDir, "confirmation-policy", "SKILL.md")
+	if err := os.WriteFile(skillPath, []byte("---\ndescription: edited\n---\nchanged\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	stdout.Reset()
+	stderr.Reset()
+	if exit := runWithDeps([]string{"skill", "info", "confirmation-policy"}, &stdout, &stderr, deps); exit != 0 {
+		t.Fatalf("skill info after edit exit = %d, stderr = %s", exit, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "hash drift: true") {
+		t.Fatalf("info missing hash drift after edit:\n%s", stdout.String())
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	if exit := runWithDeps([]string{"skill", "info", "confirmation-policy", "--json"}, &stdout, &stderr, deps); exit != 0 {
+		t.Fatalf("skill info --json after edit exit = %d, stderr = %s", exit, stderr.String())
+	}
+	var afterJSON map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &afterJSON); err != nil {
+		t.Fatalf("parse skill info json after edit: %v\n%s", err, stdout.String())
+	}
+	if afterJSON["hashDrift"] != true {
+		t.Fatalf("hashDrift after edit = %#v, want true", afterJSON["hashDrift"])
+	}

 	// remove deletes it
 	stdout.Reset()
@@ -5,6 +5,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"strings"
+	"sync"
 	"sync/atomic"
 	"testing"
 	"time"
@@ -24,12 +25,47 @@ func TestRunExecOptimizedSessionUnderGate(t *testing.T) {
 	cwd := t.TempDir()

 	var heads, posts atomic.Int64
+	// Closed when the prewarm probe lands, so the turn can be held open until it
+	// does. See the POST handler for why that ordering has to be forced.
+	headSeen := make(chan struct{})
+	var headOnce sync.Once
+	var prewarmWaitTimedOut atomic.Bool
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		switch {
 		case r.Method == http.MethodHead:
 			heads.Add(1)
+			headOnce.Do(func() { close(headSeen) })
 			w.WriteHeader(http.StatusMethodNotAllowed)
 		case r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/chat/completions"):
+			// Hold the turn open until the prewarm probe arrives. The probe is
+			// issued on the run's context, and runExec cancels that context the
+			// moment it returns, because the stop function signalContext hands
+			// back is a CancelFunc. A probe that has not reached the wire by the
+			// end of the run therefore never reaches it at all. That is why the
+			// poll this replaced could not work at any deadline: once the run is
+			// over the probe is cancelled, not merely slow.
+			//
+			// This widens the window, it does not close it. Once the goroutine is
+			// scheduled it still has only prewarmTimeout to dial loopback and
+			// write the request, and that timeout is armed inside the goroutine
+			// itself, so holding the turn here cannot extend it. If this test
+			// ever fails again, prewarmTimeout is where to look, not this hold.
+			//
+			// No self-deadlock: the pinned transport leaves MaxConnsPerHost at 0,
+			// so the HEAD dials its own connection instead of queueing behind
+			// this held POST. Do not set a per-host connection limit there.
+			//
+			// Bounded, so a probe that genuinely never fires fails the assertion
+			// below with a useful message instead of hanging the test.
+			select {
+			case <-headSeen:
+			case <-time.After(10 * time.Second):
+				// Record it. A probe that shows up after this gave up would still
+				// leave heads at 1, so the count alone proves the probe was
+				// eventually received, not that it was ordered before the turn,
+				// which is the whole claim of this test.
+				prewarmWaitTimedOut.Store(true)
+			}
 			posts.Add(1)
 			w.Header().Set("Content-Type", "text/event-stream")
 			_, _ = w.Write([]byte("data: {\"choices\":[{\"delta\":{\"content\":\"done\"}}]}\n\n"))
@@ -75,14 +111,13 @@ func TestRunExecOptimizedSessionUnderGate(t *testing.T) {
 	if got := posts.Load(); got < 1 {
 		t.Fatalf("server saw %d chat-completions POSTs, want >= 1", got)
 	}
-	// The prewarm probe is asynchronous; it fires well before the model turn
-	// finishes, but poll rather than assuming scheduling order. The deadline
-	// exceeds the production prewarmTimeout (3s) so a slow probe cannot flake
-	// this assertion.
-	deadline := time.Now().Add(5 * time.Second)
-	for heads.Load() == 0 && time.Now().Before(deadline) {
-		time.Sleep(10 * time.Millisecond)
+	// Checked before the count, because the count cannot tell the two apart: a
+	// probe that arrived only after the guard expired still leaves heads at 1.
+	if prewarmWaitTimedOut.Load() {
+		t.Fatal("the turn was not held until the prewarm probe arrived; the probe did not precede it")
 	}
+	// No polling: the turn above could not complete until the probe landed, so
+	// the count is settled by this point.
 	if got := heads.Load(); got != 1 {
 		t.Fatalf("server saw %d prewarm HEAD probes, want exactly 1", got)
 	}
@@ -734,14 +734,12 @@ func (cfg *mcpWritableConfig) setServerDisabled(name string, disabled bool) (boo
 		switch {
 		case legacyFound:
 			raw = legacyRaw
-			found = true
 		case config.IsDefaultMCPServer(name):
 			// A built-in default server isn't written to the file until the user
 			// overrides it. Treat it as present with an empty base so disabling it
 			// writes a minimal {"disabled":true} entry that merges over the default —
 			// letting `zero mcp disable <default>` work even though it lives in code.
 			raw = nil
-			found = true
 		default:
 			return false, false, nil
 		}
@@ -19,6 +19,7 @@ func TestProviderCatalogRuntimeProvidersShowOnboardingSetupHints(t *testing.T) {
 		{id: "openai", name: "OpenAI", transport: "openai", defaultModel: "gpt-4.1"},
 		{id: "groq", name: "Groq", transport: "openai-compatible", defaultModel: "llama-3.3-70b-versatile"},
 		{id: "longcat", name: "LongCat", transport: "openai-compatible", defaultModel: "LongCat-2.0"},
+		{id: "fireworks", name: "Fireworks AI", transport: "openai-compatible", defaultModel: "accounts/fireworks/models/kimi-k2p7-code"},
 		{id: "ollama-cloud", name: "Ollama Cloud", transport: "openai-compatible", defaultModel: "qwen3-coder:480b"},
 		{id: "ollama", name: "Ollama Local", transport: "openai-compatible", defaultModel: "llama3.1"},
 	}
@@ -83,10 +83,10 @@ func runProvidersDetect(args []string, stdout io.Writer, stderr io.Writer, deps
 func parseProviderDetectArgs(args []string) (providerDetectOptions, bool, error) {
 	options := providerDetectOptions{}
 	for _, arg := range args {
-		switch {
-		case arg == "-h" || arg == "--help" || arg == "help":
+		switch arg {
+		case "-h", "--help", "help":
 			return options, true, nil
-		case arg == "--json":
+		case "--json":
 			options.json = true
 		default:
 			return options, false, execUsageError{fmt.Sprintf("unexpected argument %q", arg)}
@@ -244,19 +244,19 @@ func parseUsageArgs(args []string) (usageOptions, bool, error) {
 func FormatReport(report usage.Report, insertions int, deletions int) string {
 	var builder strings.Builder
 	builder.WriteString("Usage report (cost is a reconstructed estimate)\n\n")
-	builder.WriteString(fmt.Sprintf("%-12s %10s %14s %14s\n", "date", "requests", "tokens", "est. cost"))
+	fmt.Fprintf(&builder, "%-12s %10s %14s %14s\n", "date", "requests", "tokens", "est. cost")
 	for _, bucket := range report.Buckets {
-		builder.WriteString(fmt.Sprintf("%-12s %10d %14s %14s\n",
-			bucket.Date, bucket.Requests, groupThousands(bucket.TotalTokens), formatUSD(bucket.TotalCost)))
+		fmt.Fprintf(&builder, "%-12s %10d %14s %14s\n",
+			bucket.Date, bucket.Requests, groupThousands(bucket.TotalTokens), formatUSD(bucket.TotalCost))
 	}
-	builder.WriteString(fmt.Sprintf("\n%-12s %10d %14s %14s\n",
-		"total", report.Total.Requests, groupThousands(report.Total.TotalTokens), formatUSD(report.Total.TotalCost)))
+	fmt.Fprintf(&builder, "\n%-12s %10d %14s %14s\n",
+		"total", report.Total.Requests, groupThousands(report.Total.TotalTokens), formatUSD(report.Total.TotalCost))

-	builder.WriteString(fmt.Sprintf("\nnet LOC (estimate): +%d / -%d = %d\n",
-		insertions, deletions, report.NetLOC))
+	fmt.Fprintf(&builder, "\nnet LOC (estimate): +%d / -%d = %d\n",
+		insertions, deletions, report.NetLOC)
 	if report.NetLOCPositive {
-		builder.WriteString(fmt.Sprintf("tokens per net LOC: %.1f\n", report.TokensPerNetLOC))
-		builder.WriteString(fmt.Sprintf("est. cost per net LOC: %s\n", formatUSD(report.CostPerNetLOC)))
+		fmt.Fprintf(&builder, "tokens per net LOC: %.1f\n", report.TokensPerNetLOC)
+		fmt.Fprintf(&builder, "est. cost per net LOC: %s\n", formatUSD(report.CostPerNetLOC))
 	} else {
 		builder.WriteString("tokens per net LOC: n/a (net LOC <= 0)\n")
 		builder.WriteString("est. cost per net LOC: n/a (net LOC <= 0)\n")
@@ -8,6 +8,7 @@ import (
 	"os/exec"
 	"runtime"
 	"strings"
+	"sync"
 	"time"
 )

@@ -17,7 +18,11 @@ func LoadProviderCommand(command string) (FileConfig, error) {
 	stdout, stderr, err := runProviderCommand(command, providerCommandTimeout)
 	if err != nil {
 		if errors.Is(err, errProviderCommandTimeout) {
-			return FileConfig{}, fmt.Errorf("provider command timed out after 5s")
+			// Report which phase ran out of time, and anything the command
+			// managed to say. This used to be a bare string with the underlying
+			// error and stderr both dropped, which left a user whose command was
+			// slow on a cold machine with nothing to act on.
+			return FileConfig{}, fmt.Errorf("provider command timed out after %s: %w%s", providerCommandTimeout, err, commandOutput(stderr))
 		}
 		return FileConfig{}, fmt.Errorf("provider command failed: %w%s", err, commandOutput(stderr))
 	}
@@ -40,34 +45,150 @@ func LoadProviderCommand(command string) (FileConfig, error) {

 var errProviderCommandTimeout = errors.New("provider command timeout")

+// providerCommandDrainGrace bounds how long the timeout path waits for cmd.Wait
+// to return after the process tree has been terminated. Terminate normally makes
+// that immediate; this exists so a descendant that refuses to die cannot extend
+// a call whose deadline has already expired.
+const providerCommandDrainGrace = 2 * time.Second
+
+// syncBuffer serialises the command's I/O pump against reads from this package.
+// On the timeout path runProviderCommand can return while cmd.Wait is still
+// draining, so the buffers outlive the call and a plain bytes.Buffer would be
+// read and written concurrently.
+type syncBuffer struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+func (b *syncBuffer) Write(p []byte) (int, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.Write(p)
+}
+
+// snapshot copies out what has been written so far. A copy rather than the
+// buffer's own slice, which the pump may still append to.
+func (b *syncBuffer) snapshot() []byte {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return append([]byte(nil), b.buf.Bytes()...)
+}
+
+// awaitWithGrace waits for done and gives up after grace, reporting whether the
+// wait completed rather than expired.
+//
+// Split out from the timeout path so the bound can be asserted on its own. In
+// place it is effectively untestable: Terminate kills the tree, so Wait returns
+// promptly and an unbounded receive would behave identically in every test that
+// is not pathological, which is exactly how the old unbounded receive survived.
+func awaitWithGrace(done <-chan error, grace time.Duration) bool {
+	timer := time.NewTimer(grace)
+	defer timer.Stop()
+	select {
+	case <-done:
+		return true
+	case <-timer.C:
+		return false
+	}
+}
+
+// runProviderCommand runs a provider command under a real deadline.
+//
+// "Real" is the point: timeout used to bound only the wait, so the call could
+// take arbitrarily longer than it. Two phases sat outside it. Starting the
+// process ran before the clock began, and on Windows that is CREATE_SUSPENDED,
+// job-object creation and assignment, and a system-wide thread snapshot, none of
+// which is fast on a cold or contended machine. Draining after termination was
+// unbounded as well. Both are inside the budget now, so the deadline is an upper
+// bound rather than a floor.
 func runProviderCommand(command string, timeout time.Duration) ([]byte, []byte, error) {
 	cmd := shellCommand(command)
-	configureCommandProcess(cmd)
+	// Bound the time Wait spends draining I/O pipes after the process exits,
+	// in case an orphaned descendant still holds the write ends open.
+	cmd.WaitDelay = time.Second

-	var stdout bytes.Buffer
-	var stderr bytes.Buffer
-	cmd.Stdout = &stdout
-	cmd.Stderr = &stderr
+	stdout := &syncBuffer{}
+	stderr := &syncBuffer{}
+	cmd.Stdout = stdout
+	cmd.Stderr = stderr

-	if err := cmd.Start(); err != nil {
-		return nil, nil, err
+	// Armed before the process is started, so process creation is inside the
+	// budget rather than ahead of it.
+	deadline := time.NewTimer(timeout)
+	defer deadline.Stop()
+
+	type startResult struct {
+		proc *commandProcess
+		err  error
 	}
+	// Buffered, so the goroutine can finish and exit even when nobody is left
+	// waiting on it because the deadline already fired.
+	started := make(chan startResult, 1)
+	go func() {
+		proc, err := startCommandProcess(cmd)
+		started <- startResult{proc: proc, err: err}
+	}()
+
+	var proc *commandProcess
+	select {
+	case result := <-started:
+		if result.err != nil {
+			return stdout.snapshot(), stderr.snapshot(), result.err
+		}
+		proc = result.proc
+	case <-deadline.C:
+		// The start is still in flight and will eventually hand back whatever it
+		// created, so cleanup is handed off rather than abandoned. Wait reaps the
+		// process; without it a started-but-orphaned command becomes a zombie.
+		go func() {
+			result := <-started
+			if result.err != nil {
+				return
+			}
+			result.proc.Terminate()
+			_ = cmd.Wait()
+			result.proc.Close()
+		}()
+		return stdout.snapshot(), stderr.snapshot(), fmt.Errorf("%w: starting the command exceeded %s", errProviderCommandTimeout, timeout)
+	}
+	defer proc.Close()

 	done := make(chan error, 1)
 	go func() {
 		done <- cmd.Wait()
 	}()

-	timer := time.NewTimer(timeout)
-	defer timer.Stop()
-
 	select {
 	case err := <-done:
-		return stdout.Bytes(), stderr.Bytes(), err
-	case <-timer.C:
-		terminateCommandProcess(cmd)
-		<-done
-		return stdout.Bytes(), stderr.Bytes(), errProviderCommandTimeout
+		if err != nil {
+			// The shell exited (whether via ErrWaitDelay because a
+			// background descendant kept the inherited stdout/stderr pipes
+			// open, or via a nonzero exit status) but a leftover descendant
+			// may still be running. Terminate is a no-op against an
+			// already-dead tree, so always call it rather than gating on
+			// the specific error to avoid leaking that descendant.
+			proc.Terminate()
+		}
+		if errors.Is(err, exec.ErrWaitDelay) {
+			// Wrap rather than replace. A descendant holding the inherited pipes
+			// open and the command never finishing at all are different failures
+			// that both collapsed into the same bare sentinel, which left callers
+			// and tests unable to tell which one happened. Callers that only ask
+			// errors.Is(err, errProviderCommandTimeout) are unaffected, so the
+			// message LoadProviderCommand reports is unchanged.
+			return stdout.snapshot(), stderr.snapshot(), fmt.Errorf("%w: %w", errProviderCommandTimeout, err)
+		}
+		return stdout.snapshot(), stderr.snapshot(), err
+	case <-deadline.C:
+		proc.Terminate()
+		// Bounded, unlike the bare receive this replaces. Terminate kills the
+		// tree so Wait almost always returns at once, but "almost always" was
+		// doing real work here: a tree that resists termination used to hold the
+		// call open indefinitely, long past the deadline that had just expired.
+		// Returning early leaves cmd.Wait running, which is why the buffers are
+		// synchronised.
+		awaitWithGrace(done, providerCommandDrainGrace)
+		return stdout.snapshot(), stderr.snapshot(), fmt.Errorf("%w: the command did not finish within %s", errProviderCommandTimeout, timeout)
 	}
 }

@@ -1,9 +1,12 @@
 package config

 import (
+	"errors"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"runtime"
+	"strconv"
 	"strings"
 	"testing"
 	"time"
@@ -67,7 +70,8 @@ func TestLoadProviderCommandFailureIncludesExitAndRedactsOutput(t *testing.T) {
 }

 func TestLoadProviderCommandTimeout(t *testing.T) {
-	command := writeCommand(t, commandScript{SleepSeconds: 10})
+	pidFile := filepath.Join(t.TempDir(), "sleep.pid")
+	command := writeCommand(t, commandScript{SleepSeconds: 10, PidFile: pidFile})

 	start := time.Now()
 	_, err := LoadProviderCommand(command)
@@ -85,6 +89,175 @@ func TestLoadProviderCommandTimeout(t *testing.T) {
 	if elapsed > maxElapsed {
 		t.Fatalf("timeout returned after %s, want roughly 5s", elapsed)
 	}
+	assertProcessTerminatedIfStarted(t, pidFile)
+}
+
+// providerCommandTestBudget bounds the two background-child tests below, and is
+// deliberately NOT providerCommandTimeout. Those tests assert which error each
+// cmd.Wait path yields and that the leftover descendant is killed; neither is a
+// claim about how fast Windows can start a process. Driving them through
+// LoadProviderCommand billed the fixture's own startup to the production 5s
+// budget, so on a loaded runner the outer timer won the select in
+// runProviderCommand: the nonzero-exit test saw a timeout instead of the exit
+// status it asserts, and the timer's Terminate killed the background child
+// before it recorded its PID, putting the PID file permanently out of reach no
+// matter how long the assertion polled for it.
+//
+// This is a hang-breaker, not a tuned margin. Nothing in a healthy run waits on
+// it, since both tests return about one WaitDelay after the fixture exits.
+const providerCommandTestBudget = 60 * time.Second
+
+// backgroundChildLifetime must exceed providerCommandTestBudget so that a child
+// dying of old age is unobservable: any run where runProviderCommand has not
+// returned yet trips the budget first. That is what lets both tests drop their
+// old elapsed-versus-lifetime bounds. "Still alive when the call returned" is
+// now true by construction, so a child found dead afterwards can only have been
+// killed by proc.Terminate.
+const backgroundChildLifetime = 120 * time.Second
+
+// TestLoadProviderCommandTerminatesBackgroundChild covers a command that
+// exits immediately but leaves a detached child holding the inherited
+// stdout/stderr pipes open (e.g. `sleep 600 & exit`). cmd.Wait() only
+// unblocks once WaitDelay elapses, and that path must still terminate the
+// leftover child instead of just returning and leaking it.
+func TestLoadProviderCommandTerminatesBackgroundChild(t *testing.T) {
+	pidFile := filepath.Join(t.TempDir(), "bg.pid")
+	command := writeCommand(t, commandScript{
+		Stdout:                 `{"name":"cmd","provider":"openai","apiKey":"sk-command","model":"gpt-command"}`,
+		BackgroundSleepSeconds: int(backgroundChildLifetime / time.Second),
+		BackgroundPidFile:      pidFile,
+	})
+
+	_, _, err := runProviderCommand(command, providerCommandTestBudget)
+	if err == nil {
+		t.Fatal("runProviderCommand() error = nil, want error from WaitDelay-bounded wait")
+	}
+	// Name the exact path. The outer-timer path reports the bare sentinel, so
+	// matching only that, or the "timed out after 5s" text this test used to
+	// match, would also be satisfied by a slow runner taking precisely the path
+	// this test exists to rule out.
+	if !errors.Is(err, errProviderCommandTimeout) || !errors.Is(err, exec.ErrWaitDelay) {
+		t.Fatalf("error = %v, want errProviderCommandTimeout wrapping exec.ErrWaitDelay", err)
+	}
+	assertProcessTerminated(t, pidFile)
+}
+
+// TestLoadProviderCommandTerminatesBackgroundChildOnFailure covers the same
+// leaked-descendant scenario as TestLoadProviderCommandTerminatesBackgroundChild,
+// but with a shell that exits nonzero. Go's exec.Cmd.Wait only returns
+// exec.ErrWaitDelay when the command itself exited successfully; a nonzero
+// exit yields the bare *ExitError instead, so the leftover child must still
+// be terminated on that path.
+func TestLoadProviderCommandTerminatesBackgroundChildOnFailure(t *testing.T) {
+	pidFile := filepath.Join(t.TempDir(), "bg-fail.pid")
+	command := writeCommand(t, commandScript{
+		Stderr:                 "boom",
+		ExitCode:               7,
+		BackgroundSleepSeconds: int(backgroundChildLifetime / time.Second),
+		BackgroundPidFile:      pidFile,
+	})
+
+	_, _, err := runProviderCommand(command, providerCommandTestBudget)
+	// The shell's own exit status has to survive. A timeout here means the
+	// budget swallowed it, which is exactly what this test kept reporting on CI.
+	if errors.Is(err, errProviderCommandTimeout) {
+		t.Fatalf("error = %v, want the shell's exit status rather than a timeout", err)
+	}
+	var exitErr *exec.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("error = %v, want *exec.ExitError from the nonzero exit", err)
+	}
+	if exitErr.ExitCode() != 7 {
+		t.Fatalf("exit code = %d, want 7", exitErr.ExitCode())
+	}
+	assertProcessTerminated(t, pidFile)
+}
+
+func TestAssertProcessTerminatedWaitsForDelayedPIDFile(t *testing.T) {
+	pidFile := filepath.Join(t.TempDir(), "delayed.pid")
+	firstMissing := make(chan struct{})
+	writeDone := make(chan error, 1)
+	go func() {
+		<-firstMissing
+		tempFile := pidFile + ".tmp"
+		if err := os.WriteFile(tempFile, []byte("2147483647\n"), 0o600); err != nil {
+			writeDone <- err
+			return
+		}
+		writeDone <- os.Rename(tempFile, pidFile)
+	}()
+
+	missingObserved := false
+	assertProcessTerminatedAfterMissing(t, pidFile, func() {
+		missingObserved = true
+		close(firstMissing)
+	})
+	if !missingObserved {
+		t.Fatal("PID file existed before the missing-file polling path was exercised")
+	}
+	if err := <-writeDone; err != nil {
+		t.Fatalf("write delayed pid file: %v", err)
+	}
+}
+
+func assertProcessTerminatedIfStarted(t *testing.T, pidFile string) {
+	t.Helper()
+
+	// The basic timeout fixture is intentionally unsynchronized. On a loaded
+	// Windows runner, the cold PowerShell child can be terminated before it
+	// records its PID; the synchronized background-child tests below retain
+	// the strict PID and liveness checks.
+	if _, err := os.Stat(pidFile); errors.Is(err, os.ErrNotExist) {
+		return
+	}
+	assertProcessTerminated(t, pidFile)
+}
+
+func assertProcessTerminated(t *testing.T, pidFile string) {
+	t.Helper()
+
+	assertProcessTerminatedAfterMissing(t, pidFile, nil)
+}
+
+func assertProcessTerminatedAfterMissing(t *testing.T, pidFile string, onMissing func()) {
+	t.Helper()
+
+	deadline := time.Now().Add(3 * time.Second)
+	var data []byte
+	var err error
+	missingObserved := false
+	for time.Now().Before(deadline) {
+		data, err = os.ReadFile(pidFile)
+		if err == nil {
+			break
+		}
+		if !errors.Is(err, os.ErrNotExist) {
+			t.Fatalf("read sleeper pid file: %v", err)
+		}
+		if !missingObserved {
+			missingObserved = true
+			if onMissing != nil {
+				onMissing()
+			}
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	if err != nil {
+		t.Fatalf("read sleeper pid file before timeout: %v", err)
+	}
+	pid, err := strconv.Atoi(strings.TrimSpace(string(data)))
+	if err != nil {
+		t.Fatalf("parse sleeper pid %q: %v", data, err)
+	}
+
+	deadline = time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		if !processAlive(pid) {
+			return
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+	t.Fatalf("sleeper process %d still alive after timeout", pid)
 }

 func TestLoadProviderCommandInvalidJSON(t *testing.T) {
@@ -118,6 +291,14 @@ type commandScript struct {
 	Stderr       string
 	ExitCode     int
 	SleepSeconds int
+	PidFile      string
+
+	// BackgroundSleepSeconds, if set, spawns a detached child that keeps the
+	// inherited stdout/stderr handles open well after the script itself
+	// exits, simulating a `sleep 600 & exit` style command. BackgroundPidFile
+	// records the detached child's PID.
+	BackgroundSleepSeconds int
+	BackgroundPidFile      string
 }

 func writeCommand(t *testing.T, script commandScript) string {
@@ -128,7 +309,11 @@ func writeCommand(t *testing.T, script commandScript) string {
 		path := filepath.Join(dir, "provider.cmd")
 		lines := []string{"@echo off"}
 		if script.SleepSeconds > 0 {
-			lines = append(lines, "powershell -NoProfile -Command \"Start-Sleep -Seconds "+itoa(script.SleepSeconds)+"\"")
+			sleep := "Start-Sleep -Seconds " + itoa(script.SleepSeconds)
+			if script.PidFile != "" {
+				sleep = "Set-Content -Path '" + psSingleQuote(script.PidFile) + "' -Value $PID -Encoding Ascii; " + sleep
+			}
+			lines = append(lines, "powershell -NoProfile -Command \""+sleep+"\"")
 		}
 		if script.Stdout != "" {
 			lines = append(lines, "echo "+script.Stdout)
@@ -136,6 +321,40 @@ func writeCommand(t *testing.T, script commandScript) string {
 		if script.Stderr != "" {
 			lines = append(lines, "echo "+script.Stderr+" 1>&2")
 		}
+		if script.BackgroundSleepSeconds > 0 {
+			readyFile := script.BackgroundPidFile + ".ready"
+			bgSleep := "Set-Content -LiteralPath '" + psSingleQuote(script.BackgroundPidFile) + "' -Value $PID -Encoding Ascii; " +
+				"Set-Content -LiteralPath '" + psSingleQuote(readyFile) + "' -Value ready -Encoding Ascii; " +
+				"Start-Sleep -Seconds " + itoa(script.BackgroundSleepSeconds)
+			lines = append(lines, "start /B powershell -NoProfile -Command \""+bgSleep+"\"")
+			// Wait for the child to record its PID before exiting, so the PID is
+			// on disk while the tree is still alive: runProviderCommand kills the
+			// tree one WaitDelay after the script exits, and a child that has not
+			// written by then never will.
+			//
+			// This waits in cmd itself. Spawning a second PowerShell just to poll
+			// cost another interpreter cold start, and that start is pure overhead
+			// added AFTER the PID is already written. On a loaded runner it pushed
+			// the script's exit past the 5s provider-command timeout, so the
+			// nonzero-exit test saw a timeout instead of the exit status it
+			// asserts. The wait is also bounded now: giving up and letting the PID
+			// assertion fail is far more diagnosable than blocking until the
+			// timeout fires and reporting an unrelated error. Each iteration is
+			// about a second, since `ping -n 2` sleeps between its two echoes,
+			// so the ceiling is roughly 15s: far longer than any cold PowerShell
+			// start seen on a runner, and far shorter than
+			// providerCommandTestBudget, so giving up surfaces a legible
+			// PID-file failure rather than a timeout that hides the real cause.
+			lines = append(lines,
+				":zeroWaitReady",
+				"if exist \""+readyFile+"\" goto zeroReady",
+				"set /a ZERO_READY_TRIES+=1",
+				"if %ZERO_READY_TRIES% GEQ 15 goto zeroReady",
+				"ping -n 2 127.0.0.1 >nul",
+				"goto zeroWaitReady",
+				":zeroReady",
+			)
+		}
 		lines = append(lines, "exit /b "+itoa(script.ExitCode))
 		if err := os.WriteFile(path, []byte(strings.Join(lines, "\r\n")), 0o700); err != nil {
 			t.Fatalf("write command: %v", err)
@@ -146,6 +365,9 @@ func writeCommand(t *testing.T, script commandScript) string {
 	path := filepath.Join(dir, "provider.sh")
 	lines := []string{"#!/bin/sh"}
 	if script.SleepSeconds > 0 {
+		if script.PidFile != "" {
+			lines = append(lines, "echo $$ > '"+shSingleQuote(script.PidFile)+"'")
+		}
 		lines = append(lines, "sleep "+itoa(script.SleepSeconds))
 	}
 	if script.Stdout != "" {
@@ -154,6 +376,10 @@ func writeCommand(t *testing.T, script commandScript) string {
 	if script.Stderr != "" {
 		lines = append(lines, "printf '%s\\n' '"+script.Stderr+"' >&2")
 	}
+	if script.BackgroundSleepSeconds > 0 {
+		lines = append(lines, "sleep "+itoa(script.BackgroundSleepSeconds)+" &")
+		lines = append(lines, "echo $! > '"+shSingleQuote(script.BackgroundPidFile)+"'")
+	}
 	lines = append(lines, "exit "+itoa(script.ExitCode))
 	if err := os.WriteFile(path, []byte(strings.Join(lines, "\n")), 0o700); err != nil {
 		t.Fatalf("write command: %v", err)
@@ -161,6 +387,19 @@ func writeCommand(t *testing.T, script commandScript) string {
 	return path
 }

+// psSingleQuote escapes a value for interpolation inside a PowerShell
+// single-quoted string literal, where a literal quote is doubled.
+func psSingleQuote(value string) string {
+	return strings.ReplaceAll(value, "'", "''")
+}
+
+// shSingleQuote escapes a value for interpolation inside a POSIX shell
+// single-quoted string literal, where a literal quote must close the
+// quoted section, emit an escaped quote, then reopen it.
+func shSingleQuote(value string) string {
+	return strings.ReplaceAll(value, "'", `'\''`)
+}
+
 func itoa(value int) string {
 	if value == 0 {
 		return "0"
@@ -175,3 +414,133 @@ func itoa(value int) string {
 	}
 	return string(digits[index:])
 }
+
+// The whole point of #811: providerCommandTimeout has to be an upper bound on
+// how long the call takes, not a floor. Process creation used to run before the
+// clock started and the post-termination drain was unbounded, so a slow or
+// contended machine could block startup for far longer than the error text
+// promised.
+//
+// This one guards the end-to-end contract against gross regressions. It is NOT
+// the assertion that pins the drain bound: Terminate kills the tree, so Wait
+// returns promptly and this passes even with the drain unbounded. That property
+// is pinned by TestAwaitWithGraceGivesUp, and the start-phase bound by
+// TestRunProviderCommandCountsProcessStartAgainstTheDeadline.
+func TestRunProviderCommandBoundsTotalDuration(t *testing.T) {
+	pidFile := filepath.Join(t.TempDir(), "bound.pid")
+	command := writeCommand(t, commandScript{SleepSeconds: 60, PidFile: pidFile})
+
+	const budget = 2 * time.Second
+	start := time.Now()
+	_, _, err := runProviderCommand(command, budget)
+	elapsed := time.Since(start)
+
+	if !errors.Is(err, errProviderCommandTimeout) {
+		t.Fatalf("error = %v, want the timeout sentinel", err)
+	}
+	// Budget, plus the bounded drain, plus room for a loaded runner. A failure
+	// here means some phase is outside the deadline again, which is the bug.
+	ceiling := budget + providerCommandDrainGrace + 8*time.Second
+	if elapsed > ceiling {
+		t.Fatalf("returned after %s with a %s budget; the timeout is not bounding the call (ceiling %s)", elapsed, budget, ceiling)
+	}
+	assertProcessTerminatedIfStarted(t, pidFile)
+}
+
+// The timeout error has to carry something an operator can act on. It used to be
+// a bare string with the underlying error and the command's stderr both dropped,
+// so a user whose provider command was slow got no clue which phase ran out or
+// what the command had said.
+func TestLoadProviderCommandTimeoutReportsDiagnostics(t *testing.T) {
+	command := writeCommand(t, commandScript{
+		Stderr:       "provider is warming up",
+		SleepSeconds: 30,
+		PidFile:      filepath.Join(t.TempDir(), "diag.pid"),
+	})
+
+	_, err := LoadProviderCommand(command)
+	if err == nil {
+		t.Fatal("LoadProviderCommand() error = nil, want timeout")
+	}
+	if !strings.Contains(err.Error(), "timed out") {
+		t.Fatalf("error = %q, want a timeout message", err.Error())
+	}
+	// Wrapped, so callers can still classify it.
+	if !errors.Is(err, errProviderCommandTimeout) {
+		t.Fatalf("error = %v, want errors.Is against the timeout sentinel", err)
+	}
+	// And it must say which phase, rather than only that time ran out.
+	if !strings.Contains(err.Error(), "did not finish") && !strings.Contains(err.Error(), "starting the command") {
+		t.Fatalf("error = %q, want it to name the phase that exceeded the deadline", err.Error())
+	}
+}
+
+// The output buffers are written by cmd.Wait's I/O pump, which keeps running
+// after the timeout path has returned them to the caller, so a plain
+// bytes.Buffer would be read and written concurrently. Asserted on the buffer
+// directly: driving it end to end does not reliably produce the overlap, because
+// a terminated command usually stops writing before the snapshot is taken, so
+// such a test passes with the locking removed and proves nothing.
+//
+// Only meaningful under -race, which CI runs.
+func TestSyncBufferAllowsConcurrentWriteAndSnapshot(t *testing.T) {
+	buffer := &syncBuffer{}
+	writing := make(chan struct{})
+	go func() {
+		defer close(writing)
+		for i := 0; i < 2000; i++ {
+			_, _ = buffer.Write([]byte("x"))
+		}
+	}()
+	for i := 0; i < 2000; i++ {
+		_ = buffer.snapshot()
+	}
+	<-writing
+	if len(buffer.snapshot()) != 2000 {
+		t.Fatalf("buffer holds %d bytes, want 2000", len(buffer.snapshot()))
+	}
+}
+
+// The drain after termination must be bounded. Asserted directly on the helper,
+// because in place it is untestable without a tree that refuses to die: Wait
+// normally returns at once, which is precisely why an unbounded receive sat
+// there unnoticed. A channel that never fires is the pathological case made
+// cheap.
+func TestAwaitWithGraceGivesUp(t *testing.T) {
+	never := make(chan error)
+	start := time.Now()
+	if awaitWithGrace(never, 50*time.Millisecond) {
+		t.Fatal("reported completion for a wait that never finished")
+	}
+	if elapsed := time.Since(start); elapsed > 5*time.Second {
+		t.Fatalf("gave up after %s, want roughly the grace period", elapsed)
+	}
+	// Still reports completion when the wait does finish, or the timeout path
+	// would always claim the tree hung.
+	done := make(chan error, 1)
+	done <- nil
+	if !awaitWithGrace(done, time.Second) {
+		t.Fatal("reported expiry for a wait that had already finished")
+	}
+}
+
+// Process creation has to be inside the budget. It used to run before the clock
+// started, and on Windows that phase is CREATE_SUSPENDED plus job-object setup
+// plus a system-wide thread snapshot, none of it fast on a contended machine.
+//
+// A budget that is already spent when the call begins can only be exceeded
+// during the start, so the phase named in the error is what distinguishes the
+// two orderings: with the clock started afterwards, the start would always
+// complete first and the failure would come from the wait instead.
+func TestRunProviderCommandCountsProcessStartAgainstTheDeadline(t *testing.T) {
+	command := writeCommand(t, commandScript{Stdout: `{"name":"cmd","provider":"openai","apiKey":"sk-x","model":"m"}`})
+
+	_, _, err := runProviderCommand(command, time.Nanosecond)
+	if !errors.Is(err, errProviderCommandTimeout) {
+		t.Fatalf("error = %v, want the timeout sentinel", err)
+	}
+	if !strings.Contains(err.Error(), "starting the command") {
+		t.Fatalf("error = %q, want the start phase to be the one that exceeded the deadline; "+
+			"anything else means process creation is outside the budget again", err.Error())
+	}
+}
@@ -0,0 +1,72 @@
+// Test seams: helpers only test code uses, kept out of the production binary.
+package config
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+)
+
+// ToolsOverride builds a ToolsConfig that explicitly overrides the deferred-tool
+// threshold (including to 0, which disables deferral). Use this for programmatic
+// Overrides — a bare ToolsConfig{DeferThreshold: 0} is indistinguishable from
+// "unset" and will not override.
+func ToolsOverride(deferThreshold int) ToolsConfig {
+	return ToolsConfig{DeferThreshold: deferThreshold, deferThresholdSet: true}
+}
+
+// ValidateFile reads and parses path as a Zero FileConfig and runs the same
+// semantic provider/model rules used during resolution. It returns the parsed
+// config (zero value on parse failure) plus any structured issues. A parse
+// failure yields a single issue whose Message is the underlying JSON error's
+// text (already flattened via Error(), not chained — callers cannot recover
+// the original *json.SyntaxError / *json.UnmarshalTypeError via errors.As).
+func ValidateFile(path string) (FileConfig, []Issue) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return FileConfig{}, []Issue{{Message: fmt.Sprintf("read config %s: %v", path, err)}}
+	}
+
+	var cfg FileConfig
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		return FileConfig{}, []Issue{{Message: fmt.Sprintf("invalid config JSON %s: %v", path, err)}}
+	}
+
+	issues := validateSemantics(cfg)
+	issues = append(issues, unknownFieldIssues(data)...)
+	return cfg, issues
+}
+
+// SetProviderDescription sets a provider's description VERBATIM — including to
+// empty. The generic UpsertProvider merge treats empty fields as "leave
+// unchanged", so clearing a description needs this dedicated setter.
+func SetProviderDescription(path string, name string, description string) (FileConfig, error) {
+	path = strings.TrimSpace(path)
+	if path == "" {
+		return FileConfig{}, fmt.Errorf("config path is required")
+	}
+	name = strings.TrimSpace(name)
+	if name == "" {
+		return FileConfig{}, fmt.Errorf("provider name is required")
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return FileConfig{}, fmt.Errorf("read config %s: %w", path, err)
+	}
+	cfg := FileConfig{}
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		return FileConfig{}, fmt.Errorf("invalid config JSON %s: %w", path, err)
+	}
+	for index := range cfg.Providers {
+		if strings.EqualFold(strings.TrimSpace(cfg.Providers[index].Name), name) {
+			cfg.Providers[index].Description = strings.TrimSpace(description)
+			if err := writeConfigFile(path, cfg); err != nil {
+				return FileConfig{}, err
+			}
+			return cfg, nil
+		}
+	}
+	return FileConfig{}, fmt.Errorf("provider %q not found", name)
+}
@@ -87,7 +87,7 @@ func mergeMCPServer(base MCPServerConfig, next MCPServerConfig, canReenable bool
 		// server the user explicitly enabled. The only layer allowed to
 		// override an explicit higher-scope decision is the CLI override scope
 		// (canReenable=true).
-		if canReenable || !(baseDisabledSet && baseDisabled != next.Disabled) {
+		if canReenable || !baseDisabledSet || baseDisabled == next.Disabled {
 			base.Disabled = next.Disabled
 		}
 	}
@@ -3,18 +3,59 @@
 package config

 import (
+	"io"
 	"os/exec"
 	"syscall"
 )

-func configureCommandProcess(cmd *exec.Cmd) {
-	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+type commandProcess struct {
+	groupID     int
+	anchor      *exec.Cmd
+	anchorInput io.WriteCloser
 }

-func terminateCommandProcess(cmd *exec.Cmd) {
-	if cmd.Process == nil {
-		return
+// startCommandProcess retains a live process-group leader until cleanup. The
+// provider shell may be reaped before Wait finishes draining descendant-held
+// pipes, so its PID cannot safely identify the group after Wait returns.
+func startCommandProcess(cmd *exec.Cmd) (*commandProcess, error) {
+	anchor := exec.Command("sh", "-c", "read _")
+	anchor.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	anchorInput, err := anchor.StdinPipe()
+	if err != nil {
+		return nil, err
 	}
-	_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
-	_ = cmd.Process.Kill()
+	if err := anchor.Start(); err != nil {
+		_ = anchorInput.Close()
+		return nil, err
+	}
+
+	proc := &commandProcess{groupID: anchor.Process.Pid, anchor: anchor, anchorInput: anchorInput}
+	if cmd.SysProcAttr == nil {
+		cmd.SysProcAttr = &syscall.SysProcAttr{}
+	}
+	cmd.SysProcAttr.Setpgid = true
+	cmd.SysProcAttr.Pgid = proc.groupID
+	if err := cmd.Start(); err != nil {
+		proc.Close()
+		return nil, err
+	}
+	return proc, nil
+}
+
+func (p *commandProcess) Terminate() {
+	if p.groupID != 0 {
+		_ = syscall.Kill(-p.groupID, syscall.SIGKILL)
+	}
+}
+
+func (p *commandProcess) Close() {
+	if p.anchorInput != nil {
+		_ = p.anchorInput.Close()
+		p.anchorInput = nil
+	}
+	if p.anchor != nil {
+		_ = p.anchor.Wait()
+		p.anchor = nil
+	}
+	p.groupID = 0
 }
@@ -0,0 +1,66 @@
+//go:build !windows
+
+package config
+
+import (
+	"os/exec"
+	"syscall"
+	"testing"
+)
+
+func TestCommandProcessPreservesSysProcAttr(t *testing.T) {
+	cmd := exec.Command("sh", "-c", "exit 0")
+	attr := &syscall.SysProcAttr{}
+	cmd.SysProcAttr = attr
+
+	proc, err := startCommandProcess(cmd)
+	if err != nil {
+		t.Fatalf("startCommandProcess: %v", err)
+	}
+	defer proc.Close()
+
+	if cmd.SysProcAttr != attr {
+		t.Fatal("startCommandProcess replaced SysProcAttr")
+	}
+	if !cmd.SysProcAttr.Setpgid || cmd.SysProcAttr.Pgid != proc.groupID {
+		t.Fatalf("process group = Setpgid %v, Pgid %d; want true, %d", cmd.SysProcAttr.Setpgid, cmd.SysProcAttr.Pgid, proc.groupID)
+	}
+	if err := cmd.Wait(); err != nil {
+		t.Fatalf("Wait: %v", err)
+	}
+}
+
+func TestCommandProcessRetainsGroupIdentityAfterProviderWait(t *testing.T) {
+	cmd := exec.Command("sh", "-c", "exit 7")
+	proc, err := startCommandProcess(cmd)
+	if err != nil {
+		t.Fatalf("startCommandProcess: %v", err)
+	}
+	defer func() {
+		proc.Terminate()
+		proc.Close()
+	}()
+
+	providerPID := cmd.Process.Pid
+	anchorPID := proc.groupID
+	if err := cmd.Wait(); err == nil {
+		t.Fatal("Wait error = nil, want nonzero exit")
+	}
+	if anchorPID == providerPID {
+		t.Fatalf("group identity reused provider PID %d", providerPID)
+	}
+	if !processAlive(anchorPID) {
+		t.Fatalf("group leader %d exited before cleanup", anchorPID)
+	}
+
+	proc.Terminate()
+	proc.Close()
+	if processAlive(anchorPID) {
+		t.Fatalf("group leader %d still alive after cleanup", anchorPID)
+	}
+}
+
+func processAlive(pid int) bool {
+	err := syscall.Kill(pid, 0)
+	return err == nil || err == syscall.EPERM
+}
@@ -3,23 +3,165 @@
 package config

 import (
+	"context"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"strconv"
+	"syscall"
+	"time"
+	"unsafe"
+
+	"golang.org/x/sys/windows"
 )

-func configureCommandProcess(cmd *exec.Cmd) {}
+// configureCommandProcess starts the process suspended so it can be
+// assigned to the job object before its main thread (and therefore any
+// code it runs) executes. Without this, a fast command can spawn and
+// detach a descendant before AssignProcessToJobObject runs, letting that
+// descendant escape the job and survive termination.
+func configureCommandProcess(cmd *exec.Cmd) {
+	cmd.SysProcAttr = &syscall.SysProcAttr{CreationFlags: windows.CREATE_SUSPENDED}
+}

-func terminateCommandProcess(cmd *exec.Cmd) {
+func startCommandProcess(cmd *exec.Cmd) (*commandProcess, error) {
+	configureCommandProcess(cmd)
+	if err := cmd.Start(); err != nil {
+		return nil, err
+	}
+	return attachCommandProcess(cmd), nil
+}
+
+// commandProcess tracks a started provider command so its entire process
+// tree can be terminated on timeout. It prefers a job object: taskkill /T
+// walks the tree by parent PID in user space and can miss descendants,
+// letting them run to completion while Wait blocks on inherited pipes.
+type commandProcess struct {
+	cmd           *exec.Cmd
+	job           windows.Handle
+	processHandle windows.Handle
+}
+
+func attachCommandProcess(cmd *exec.Cmd) *commandProcess {
+	proc := &commandProcess{cmd: cmd}
 	if cmd.Process == nil {
+		return proc
+	}
+	// The main thread is suspended (see configureCommandProcess); resume it
+	// once we're done attaching, however that turns out. If resuming fails
+	// outright (Toolhelp/OpenThread/ResumeThread errors are otherwise
+	// swallowed), the process would sit suspended forever and never exit on
+	// its own, making the failure look like an ordinary 5s provider-command
+	// timeout. Terminate it immediately instead so the real cause surfaces
+	// quickly and no suspended process is left behind.
+	defer func() {
+		if !resumeMainThread(cmd.Process.Pid) {
+			proc.Terminate()
+		}
+	}()
+
+	handle, err := windows.OpenProcess(windows.PROCESS_SET_QUOTA|windows.PROCESS_TERMINATE|windows.PROCESS_QUERY_LIMITED_INFORMATION, false, uint32(cmd.Process.Pid))
+	if err != nil {
+		return proc
+	}
+	proc.processHandle = handle
+
+	job, err := windows.CreateJobObject(nil, nil)
+	if err != nil {
+		return proc
+	}
+	if err := windows.AssignProcessToJobObject(job, handle); err != nil {
+		_ = windows.CloseHandle(job)
+		return proc
+	}
+	proc.job = job
+	return proc
+}
+
+// resumeMainThread resumes every (assumed suspended) thread of pid and
+// reports whether at least one was actually resumed. Callers must treat a
+// false result as a failed resume, not a benign no-op: a suspended process
+// that's never woken up will neither exit nor produce output on its own.
+func resumeMainThread(pid int) bool {
+	snapshot, err := windows.CreateToolhelp32Snapshot(windows.TH32CS_SNAPTHREAD, 0)
+	if err != nil {
+		return false
+	}
+	defer func() { _ = windows.CloseHandle(snapshot) }()
+
+	var entry windows.ThreadEntry32
+	entry.Size = uint32(unsafe.Sizeof(entry))
+	resumed := false
+	for err := windows.Thread32First(snapshot, &entry); err == nil; err = windows.Thread32Next(snapshot, &entry) {
+		if entry.OwnerProcessID != uint32(pid) {
+			continue
+		}
+		thread, err := windows.OpenThread(windows.THREAD_SUSPEND_RESUME, false, entry.ThreadID)
+		if err != nil {
+			continue
+		}
+		if _, err := windows.ResumeThread(thread); err == nil {
+			resumed = true
+		}
+		_ = windows.CloseHandle(thread)
+	}
+	return resumed
+}
+
+func (p *commandProcess) Terminate() {
+	if p.job != 0 {
+		// A job handle means the process tree was contained from launch, so
+		// TerminateJobObject alone kills every member atomically. Don't also
+		// fall through to the taskkill/PID path below: by the time
+		// Terminate runs on the ErrWaitDelay path, cmd.Wait has already
+		// reaped the root process, so its PID may have been reused by an
+		// unrelated process, and forcing /T /PID against a reused PID would
+		// kill the wrong tree.
+		_ = windows.TerminateJobObject(p.job, 1)
 		return
 	}
-	taskkill := taskkillPath()
-	_ = exec.Command(taskkill, "/T", "/F", "/PID", strconv.Itoa(cmd.Process.Pid)).Run()
-	_ = cmd.Process.Kill()
+	if p.cmd.Process == nil {
+		return
+	}
+	if p.processHandle == 0 {
+		// Without a retained identity, never target a numeric PID that may
+		// have been reaped and reused. os.Process.Kill uses Go's original
+		// process state instead.
+		_ = p.cmd.Process.Kill()
+		return
+	}
+	// Fallback for the rare case where job creation or assignment failed:
+	// only invoke taskkill while the identity-preserving handle confirms the
+	// original root is still active. Keeping that handle open through Run
+	// prevents Windows from reusing its PID for an unrelated process.
+	var exitCode uint32
+	if err := windows.GetExitCodeProcess(p.processHandle, &exitCode); err == nil && exitCode == stillActive {
+		taskkill := taskkillPath()
+		ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+		_ = exec.CommandContext(ctx, taskkill, "/T", "/F", "/PID", strconv.Itoa(p.cmd.Process.Pid)).Run()
+		cancel()
+	}
+	_ = windows.TerminateProcess(p.processHandle, 1)
 }

+// Close releases the retained handles without touching any still-running
+// descendants: the job carries no KILL_ON_JOB_CLOSE limit, so on the success
+// path a provider command's detached helpers keep running exactly as they did
+// before job objects were introduced. Descendant termination happens
+// explicitly via Terminate, called only on timeout/error.
+func (p *commandProcess) Close() {
+	if p.job != 0 {
+		_ = windows.CloseHandle(p.job)
+		p.job = 0
+	}
+	if p.processHandle != 0 {
+		_ = windows.CloseHandle(p.processHandle)
+		p.processHandle = 0
+	}
+}
+
+const stillActive = uint32(259) // STILL_ACTIVE
+
 func taskkillPath() string {
 	systemRoot := os.Getenv("SystemRoot")
 	if systemRoot == "" {
@@ -0,0 +1,65 @@
+//go:build windows
+
+package config
+
+import (
+	"os/exec"
+	"testing"
+
+	"golang.org/x/sys/windows"
+)
+
+// TestResumeMainThreadReportsFailureForUnknownPID covers the contract
+// attachCommandProcess relies on: when no thread belonging to pid can be
+// found (here, because the pid doesn't correspond to a live process),
+// resumeMainThread must report false rather than silently doing nothing,
+// so a caller can react (e.g. terminate the process) instead of leaving it
+// suspended indefinitely.
+func TestResumeMainThreadReportsFailureForUnknownPID(t *testing.T) {
+	if resumeMainThread(0) {
+		t.Fatal("resumeMainThread(0) = true, want false for a pid with no threads")
+	}
+}
+
+func TestCommandProcessRetainsIdentityAfterWait(t *testing.T) {
+	cmd := exec.Command("cmd", "/C", "exit /b 0")
+	configureCommandProcess(cmd)
+	if err := cmd.Start(); err != nil {
+		t.Fatalf("Start: %v", err)
+	}
+	proc := attachCommandProcess(cmd)
+	t.Cleanup(proc.Close)
+	if proc.processHandle == 0 {
+		t.Fatal("attachCommandProcess did not retain a process handle")
+	}
+	if err := cmd.Wait(); err != nil {
+		t.Fatalf("Wait: %v", err)
+	}
+
+	var code uint32
+	if err := windows.GetExitCodeProcess(proc.processHandle, &code); err != nil {
+		t.Fatalf("GetExitCodeProcess after Wait: %v", err)
+	}
+	if code == stillActive {
+		t.Fatalf("exit code = STILL_ACTIVE after Wait")
+	}
+
+	proc.Close()
+	if proc.job != 0 || proc.processHandle != 0 {
+		t.Fatalf("Close left handles open: job=%v process=%v", proc.job, proc.processHandle)
+	}
+}
+
+func processAlive(pid int) bool {
+	handle, err := windows.OpenProcess(windows.PROCESS_QUERY_LIMITED_INFORMATION, false, uint32(pid))
+	if err != nil {
+		return false
+	}
+	defer func() { _ = windows.CloseHandle(handle) }()
+
+	var code uint32
+	if err := windows.GetExitCodeProcess(handle, &code); err != nil {
+		return false
+	}
+	return code == stillActive
+}
@@ -322,14 +322,6 @@ type SwarmConfig struct {
 	MaxTeamSize int `json:"maxTeamSize,omitempty"`
 }

-// ToolsOverride builds a ToolsConfig that explicitly overrides the deferred-tool
-// threshold (including to 0, which disables deferral). Use this for programmatic
-// Overrides — a bare ToolsConfig{DeferThreshold: 0} is indistinguishable from
-// "unset" and will not override.
-func ToolsOverride(deferThreshold int) ToolsConfig {
-	return ToolsConfig{DeferThreshold: deferThreshold, deferThresholdSet: true}
-}
-
 func (cfg *ToolsConfig) UnmarshalJSON(data []byte) error {
 	type rawTools struct {
 		DeferThreshold *int `json:"deferThreshold"`
@@ -3,7 +3,6 @@ package config
 import (
 	"encoding/json"
 	"fmt"
-	"os"
 )

 // Issue is a single structured problem found while validating a config file.
@@ -13,28 +12,6 @@ type Issue struct {
 	Message   string `json:"message"`
 }

-// ValidateFile reads and parses path as a Zero FileConfig and runs the same
-// semantic provider/model rules used during resolution. It returns the parsed
-// config (zero value on parse failure) plus any structured issues. A parse
-// failure yields a single issue whose Message wraps the underlying JSON error
-// so callers can extract *json.SyntaxError / *json.UnmarshalTypeError offsets
-// via errors.As.
-func ValidateFile(path string) (FileConfig, []Issue) {
-	data, err := os.ReadFile(path)
-	if err != nil {
-		return FileConfig{}, []Issue{{Message: fmt.Sprintf("read config %s: %v", path, err)}}
-	}
-
-	var cfg FileConfig
-	if err := json.Unmarshal(data, &cfg); err != nil {
-		return FileConfig{}, []Issue{{Message: fmt.Errorf("invalid config JSON %s: %w", path, err).Error()}}
-	}
-
-	issues := validateSemantics(cfg)
-	issues = append(issues, unknownFieldIssues(data)...)
-	return cfg, issues
-}
-
 // ValidateBytes parses data as a Zero FileConfig and runs the same semantic
 // provider/model rules as ValidateFile. It returns the parsed config (zero
 // value on parse failure) plus any structured issues. A parse failure yields a
@@ -431,39 +431,6 @@ func EditProvider(path string, edit ProviderEdit) (FileConfig, error) {
 	return cfg, nil
 }

-// SetProviderDescription sets a provider's description VERBATIM — including to
-// empty. The generic UpsertProvider merge treats empty fields as "leave
-// unchanged", so clearing a description needs this dedicated setter.
-func SetProviderDescription(path string, name string, description string) (FileConfig, error) {
-	path = strings.TrimSpace(path)
-	if path == "" {
-		return FileConfig{}, fmt.Errorf("config path is required")
-	}
-	name = strings.TrimSpace(name)
-	if name == "" {
-		return FileConfig{}, fmt.Errorf("provider name is required")
-	}
-
-	data, err := os.ReadFile(path)
-	if err != nil {
-		return FileConfig{}, fmt.Errorf("read config %s: %w", path, err)
-	}
-	cfg := FileConfig{}
-	if err := json.Unmarshal(data, &cfg); err != nil {
-		return FileConfig{}, fmt.Errorf("invalid config JSON %s: %w", path, err)
-	}
-	for index := range cfg.Providers {
-		if strings.EqualFold(strings.TrimSpace(cfg.Providers[index].Name), name) {
-			cfg.Providers[index].Description = strings.TrimSpace(description)
-			if err := writeConfigFile(path, cfg); err != nil {
-				return FileConfig{}, err
-			}
-			return cfg, nil
-		}
-	}
-	return FileConfig{}, fmt.Errorf("provider %q not found", name)
-}
-
 // migrateStoredProviderKey moves a credential-store entry to a new provider
 // name: write-new-then-delete-old, so an interruption can leave a duplicate but
 // never a missing key. A missing source entry is a no-op (the marker may be
@@ -16,7 +16,7 @@ func TestBuildCountsProjectGuidelinesAndFreeBudget(t *testing.T) {
 	writeTestFile(t, root, "AGENTS.md", strings.Repeat("project rules\n", 200))

 	registry := tools.NewRegistry()
-	for _, tool := range tools.CoreTools(root) {
+	for _, tool := range tools.CoreToolsScoped(root, nil) {
 		registry.Register(tool)
 	}

@@ -80,7 +80,7 @@ func TestBuildHasStableJSONContractAndCategoryMath(t *testing.T) {
 	writeTestFile(t, root, "ZERO.md", strings.Repeat("zero rules\n", 16))

 	registry := tools.NewRegistry()
-	for _, tool := range tools.CoreTools(root) {
+	for _, tool := range tools.CoreToolsScoped(root, nil) {
 		registry.Register(tool)
 	}

@@ -0,0 +1,4 @@
+// Test seams: helpers only test code uses, kept out of the production binary.
+package cron
+
+func (s Schedule) String() string { return s.expr }
@@ -23,8 +23,6 @@ type Schedule struct {
 	expr    string
 }

-func (s Schedule) String() string { return s.expr }
-
 // full returns a bitset with every value in [min,max] set.
 func full(min, max int) uint64 {
 	var m uint64
@@ -99,35 +99,60 @@ func (s *Store) Add(job Job) (Job, error) {
 		job.Status = StatusActive
 	}
 	job.CreatedAt = s.now().UTC()
-	id, err := s.allocID()
+	id, unlock, err := s.reserveID()
 	if err != nil {
 		return Job{}, err
 	}
+	// Held from reservation through initial persistence: without this, Remove
+	// (which takes the same per-ID lock before deleting) could delete the
+	// bare reservation directory the instant after Mkdir and report success,
+	// then writeJob's MkdirAll would silently resurrect it and persist the
+	// job anyway — or a second Add could re-reserve the freed id while this
+	// writer is still running, putting two writers on the same metadata path.
+	defer unlock()
 	job.ID = id
-	if err := s.writeJob(job); err != nil {
+	if err := s.writeReservedJob(job); err != nil {
 		return Job{}, err
 	}
 	return job, nil
 }

-func (s *Store) allocID() (string, error) {
+// reserveID atomically reserves an unused job id (by os.Mkdir-ing its
+// directory) and returns the per-ID lock held for that id, still acquired.
+// The caller must release it (via the returned unlock) only once the
+// reservation has been committed (metadata.json written) or torn down —
+// see Add.
+func (s *Store) reserveID() (string, func(), error) {
+	if err := os.MkdirAll(s.root, 0o700); err != nil {
+		return "", nil, fmt.Errorf("create cron store root: %w", err)
+	}
 	base := s.now().UTC().Format("20060102-150405")
 	for n := 0; n < 100; n++ {
 		id := base
 		if n > 0 {
 			id = fmt.Sprintf("%s-%d", base, n)
 		}
-		if _, err := os.Stat(filepath.Join(s.root, id)); errors.Is(err, os.ErrNotExist) {
-			return id, nil
+		unlock, err := s.lockJob(id)
+		if err != nil {
+			return "", nil, err
 		}
+		mkErr := os.Mkdir(s.jobDir(id), 0o700)
+		if mkErr == nil {
+			return id, unlock, nil
+		}
+		unlock()
+		if errors.Is(mkErr, os.ErrExist) {
+			continue
+		}
+		return "", nil, fmt.Errorf("reserve cron job id %q: %w", id, mkErr)
 	}
-	return "", errors.New("could not allocate a unique cron job id")
+	return "", nil, errors.New("could not allocate a unique cron job id")
 }

 func (s *Store) jobDir(id string) string { return filepath.Join(s.root, id) }

 // validID rejects ids that could escape the store root (path separators or
-// traversal). allocID-generated timestamp ids always pass; this guards
+// traversal). reserveID-generated timestamp ids always pass; this guards
 // externally-supplied ids (get/update/remove/append).
 func validID(id string) bool {
 	return id != "" && id != "." && id != ".." && !strings.ContainsAny(id, `/\`) && filepath.Base(id) == id
@@ -153,6 +178,16 @@ func (s *Store) writeJob(job Job) error {
 	return nil
 }

+func (s *Store) writeReservedJob(job Job) error {
+	if err := s.writeJob(job); err != nil {
+		if cleanupErr := os.RemoveAll(s.jobDir(job.ID)); cleanupErr != nil {
+			return errors.Join(err, fmt.Errorf("remove failed cron job reservation: %w", cleanupErr))
+		}
+		return err
+	}
+	return nil
+}
+
 func (s *Store) Get(id string) (Job, error) {
 	if !validID(id) {
 		return Job{}, fmt.Errorf("invalid cron job id %q", id)
@@ -2,9 +2,11 @@ package cron

 import (
 	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
 	"testing"
 	"time"
 )
@@ -74,6 +76,160 @@ func TestStoreAddListGetRemove(t *testing.T) {
 	}
 }

+func TestStoreAddReservesUniqueIDsAcrossConcurrentStores(t *testing.T) {
+	root := t.TempDir()
+	now := func() time.Time { return time.Unix(1000, 0).UTC() }
+	const adds = 32
+
+	start := make(chan struct{})
+	results := make(chan Job, adds)
+	errs := make(chan error, adds)
+	var wg sync.WaitGroup
+	for i := 0; i < adds; i++ {
+		wg.Add(1)
+		go func(index int) {
+			defer wg.Done()
+			store := NewStore(StoreOptions{RootDir: root, Now: now})
+			<-start
+			job, err := store.Add(Job{Expr: "* * * * *", Prompt: fmt.Sprintf("job-%d", index)})
+			if err != nil {
+				errs <- err
+				return
+			}
+			results <- job
+		}(i)
+	}
+	close(start)
+	wg.Wait()
+	close(results)
+	close(errs)
+
+	for err := range errs {
+		t.Errorf("concurrent Add: %v", err)
+	}
+	seen := make(map[string]struct{}, adds)
+	reader := NewStore(StoreOptions{RootDir: root, Now: now})
+	for job := range results {
+		if _, duplicate := seen[job.ID]; duplicate {
+			t.Errorf("concurrent Add returned duplicate ID %q", job.ID)
+		}
+		seen[job.ID] = struct{}{}
+		persisted, err := reader.Get(job.ID)
+		if err != nil {
+			t.Errorf("Get(%q): %v", job.ID, err)
+			continue
+		}
+		if persisted.Prompt != job.Prompt {
+			t.Errorf("Get(%q).Prompt = %q, want %q", job.ID, persisted.Prompt, job.Prompt)
+		}
+	}
+	if len(seen) != adds {
+		t.Fatalf("unique jobs = %d, want %d", len(seen), adds)
+	}
+}
+
+// TestAddDoesNotLeakReservationToConcurrentRemove reproduces the audit
+// finding that Remove could observe and delete an in-flight Add's bare
+// reservation directory (Mkdir'd but not yet holding metadata.json) and
+// report success — after which Add's writeJob would silently resurrect the
+// directory and persist the job anyway. Add now holds the same per-ID lock
+// Remove takes, from reservation through initial persistence, so a
+// concurrent Remove for that id must wait until the reservation is either
+// committed or torn down, never observing the bare reservation in between.
+func TestAddDoesNotLeakReservationToConcurrentRemove(t *testing.T) {
+	store := newTestStore(t)
+
+	// Simulate the in-flight window Add now holds the lock across: the id is
+	// reserved (its directory exists) but metadata.json has not been written.
+	id, unlock, err := store.reserveID()
+	if err != nil {
+		t.Fatalf("reserveID: %v", err)
+	}
+	if _, statErr := os.Stat(store.jobDir(id)); statErr != nil {
+		t.Fatalf("reservation directory missing: %v", statErr)
+	}
+
+	removeErr := make(chan error, 1)
+	go func() {
+		removeErr <- store.Remove(id)
+	}()
+
+	// Remove cannot proceed past the shared per-ID lock we're holding, so it's
+	// safe to commit the job here, before releasing it: if Remove could race
+	// ahead of this write, it would delete the bare reservation instead of
+	// waiting to observe (and remove) the committed job.
+	job := Job{ID: id, Expr: "* * * * *", Prompt: "job", Status: StatusActive}
+	if err := store.writeJob(job); err != nil {
+		t.Fatalf("writeJob: %v", err)
+	}
+	unlock()
+
+	if err := <-removeErr; err != nil {
+		t.Fatalf("Remove of the committed job: %v", err)
+	}
+	if _, err := os.Stat(store.jobDir(id)); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("job directory should be gone after Remove: %v", err)
+	}
+	if _, err := store.Get(id); !errors.Is(err, ErrJobNotFound) {
+		t.Fatalf("Get after Remove = %v, want ErrJobNotFound", err)
+	}
+}
+
+// TestReserveIDSerializesOnPerIDLock covers the other half of the audit
+// finding: a second Add attempting the SAME candidate id while the first
+// reservation is still held must block on the shared per-ID lock (not just
+// race the directory Mkdir), so it never ends up writing metadata.json for
+// an id whose first writer is still in flight. It moves on to the next
+// candidate id instead.
+func TestReserveIDSerializesOnPerIDLock(t *testing.T) {
+	store := newTestStore(t)
+
+	id, unlock, err := store.reserveID()
+	if err != nil {
+		t.Fatalf("first reserveID: %v", err)
+	}
+
+	type reservation struct {
+		id  string
+		err error
+	}
+	second := make(chan reservation, 1)
+	go func() {
+		id2, unlock2, err := store.reserveID()
+		if err == nil {
+			unlock2()
+		}
+		second <- reservation{id: id2, err: err}
+	}()
+
+	// The second reserveID cannot observe an id until this lock is released:
+	// it contends on the same per-ID lock file before ever attempting Mkdir.
+	unlock()
+
+	got := <-second
+	if got.err != nil {
+		t.Fatalf("second reserveID: %v", got.err)
+	}
+	if got.id == id {
+		t.Fatalf("second reserveID returned the first id %q while its reservation was still held", got.id)
+	}
+}
+
+func TestWriteReservedJobRemovesReservationOnFailure(t *testing.T) {
+	store := newTestStore(t)
+	job := Job{ID: "reserved", Expr: "* * * * *", Prompt: "job"}
+	if err := os.MkdirAll(filepath.Join(store.jobDir(job.ID), "metadata.json.tmp"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := store.writeReservedJob(job); err == nil {
+		t.Fatal("writeReservedJob error = nil, want metadata write failure")
+	}
+	if _, err := os.Stat(store.jobDir(job.ID)); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("failed reservation still exists: %v", err)
+	}
+}
+
 func TestStoreAppendRun(t *testing.T) {
 	s := newTestStore(t)
 	job, _ := s.Add(Job{Expr: "* * * * *", Prompt: "x", Status: StatusActive})
@@ -37,16 +37,6 @@ const (
 	StreamProviderOpenAI   = "openai"
 )

-// BatchProviders lists valid stt.provider values, for config validation.
-func BatchProviders() []string {
-	return []string{ProviderLocal, ProviderGroq, ProviderOpenAI}
-}
-
-// StreamProviders lists valid stt.streamProvider values, for config validation.
-func StreamProviders() []string {
-	return []string{StreamProviderLocal, StreamProviderDeepgram, StreamProviderOpenAI}
-}
-
 // AudioFormat identifies a recorded container format, sniffed from the bytes —
 // desktop recorders produce WAV, Termux's recorder produces M4A/AAC.
 type AudioFormat string
@@ -100,7 +100,7 @@ func (d *deepgramTranscriber) StreamTranscribe(ctx context.Context, chunks <-cha
 				}
 			default:
 			}
-			return compose(), fmt.Errorf("Deepgram stream error: %w", err)
+			return compose(), fmt.Errorf("Deepgram stream error: %w", err) //nolint:staticcheck // Preserve established user-facing error text.
 		}
 		if typ != websocket.MessageText {
 			continue
@@ -2,6 +2,7 @@ package imageinput

 import (
 	"bytes"
+	"errors"
 	"fmt"
 	"net/http"
 	"os"
@@ -16,6 +17,13 @@ import (
 // clipboard, or (nil, "", nil) when the clipboard has no image. Called when
 // text clipboard is empty (the user pasted a screenshot). The media type is
 // sniffed from the bytes, not trusted from the clipboard.
+// ErrClipboardImageUnreadable reports that the clipboard holds an image the host
+// has no way to extract. It is deliberately distinct from "no image on the
+// clipboard", which is an ordinary no-op: this one is actionable, and silence is
+// the wrong response to it.
+var ErrClipboardImageUnreadable = errors.New(
+	"the clipboard holds an image but no helper on this host can read it; on macOS install pngpaste (brew install pngpaste) or a Python with pyobjc")
+
 func ReadClipboardImage() ([]byte, string, error) {
 	data, err := readClipboardImageBytes()
 	if err != nil {
@@ -95,35 +103,71 @@ func readClipboardImageWindows() ([]byte, error) {

 // readClipboardImageDarwin uses osascript to check for and read a clipboard
 // image. Returns (nil, nil) when no image is present.
-func readClipboardImageDarwin() ([]byte, error) {
-	// Check clipboard info for image classes.
-	check := `osascript -e 'clipboard info'`
-	out, err := exec.Command("sh", "-c", check).Output()
-	if err != nil {
-		return nil, nil
+// darwinClipboardInfo reports what the pasteboard is currently offering, and
+// darwinClipboardExtract pulls the PNG bytes out of it.
+//
+// Both are vars so the two-step logic below can be driven in a test. The step
+// that matters, "the clipboard holds an image and nothing here can extract it",
+// only happens when the first succeeds and the second fails, which cannot be
+// arranged by stubbing the caller: a test that substitutes ReadClipboardImage
+// asserts the plumbing around this function rather than the decision inside it,
+// and stays green with that decision reverted.
+var (
+	darwinClipboardInfo = func() (string, error) {
+		out, err := exec.Command("sh", "-c", `osascript -e 'clipboard info'`).Output()
+		return string(out), err
 	}
-	info := string(out)
-	if !strings.Contains(info, "PNG") && !strings.Contains(info, "JPEG") && !strings.Contains(info, "TIFF") && !strings.Contains(info, "GIF") {
-		return nil, nil
-	}
-	// Write clipboard image to a temp file via AppleScript, then read it.
-	// Using pngpaste if available, falling back to a Python one-liner.
-	cmd := exec.Command("sh", "-c", `pngpaste - 2>/dev/null || python3 -c "
+	darwinClipboardExtract = func() ([]byte, error) {
+		// pngpaste if available, falling back to a Python one-liner. Neither
+		// ships with macOS: pngpaste is Homebrew-only and Apple dropped the
+		// bundled PyObjC, so a stock Mac fails here every time.
+		cmd := exec.Command("sh", "-c", `pngpaste - 2>/dev/null || python3 -c "
 import AppKit, sys
 pb = AppKit.NSPasteboard.generalPasteboard()
 data = pb.dataForType_(AppKit.NSPasteboardTypePNG)
 if data:
    sys.stdout.buffer.write(data.bytes())
 "`)
-	var stdout bytes.Buffer
-	cmd.Stdout = &stdout
-	if err := cmd.Run(); err != nil {
+		var stdout bytes.Buffer
+		cmd.Stdout = &stdout
+		if err := cmd.Run(); err != nil {
+			return nil, err
+		}
+		return stdout.Bytes(), nil
+	}
+)
+
+// darwinClipboardOffersImage reports whether the pasteboard info line names an
+// image class.
+func darwinClipboardOffersImage(info string) bool {
+	for _, class := range []string{"PNG", "JPEG", "TIFF", "GIF"} {
+		if strings.Contains(info, class) {
+			return true
+		}
+	}
+	return false
+}
+
+func readClipboardImageDarwin() ([]byte, error) {
+	info, err := darwinClipboardInfo()
+	if err != nil {
 		return nil, nil
 	}
-	if stdout.Len() == 0 {
+	if !darwinClipboardOffersImage(info) {
 		return nil, nil
 	}
-	return stdout.Bytes(), nil
+	// Past this point the clipboard is KNOWN to hold an image, because the probe
+	// above said so. A failure here is therefore not "no image", it is "there is
+	// an image and nothing on this host can extract it". Reporting that as
+	// absence is what left users staring at a paste that silently did nothing.
+	data, err := darwinClipboardExtract()
+	if err != nil {
+		return nil, ErrClipboardImageUnreadable
+	}
+	if len(data) == 0 {
+		return nil, ErrClipboardImageUnreadable
+	}
+	return data, nil
 }

 // readClipboardImageLinux tries wl-paste (Wayland) then xclip (X11) to read
@@ -0,0 +1,84 @@
+package imageinput
+
+import (
+	"errors"
+	"testing"
+)
+
+// Drives readClipboardImageDarwin's own decision rather than the plumbing around
+// it. Both shell steps are substituted, so this runs on any platform and, more
+// importantly, actually reaches the branch under test: a test that stubs
+// ReadClipboardImage instead stays green with the production change reverted,
+// which is how the first version of this coverage slipped through.
+func TestReadClipboardImageDarwinDistinguishesUnreadableFromAbsent(t *testing.T) {
+	restore := func() func() {
+		info, extract := darwinClipboardInfo, darwinClipboardExtract
+		return func() { darwinClipboardInfo, darwinClipboardExtract = info, extract }
+	}()
+	t.Cleanup(restore)
+
+	const pngInfo = `«class PNGf», «class 8BPS»`
+
+	t.Run("image present but no extractor is actionable", func(t *testing.T) {
+		darwinClipboardInfo = func() (string, error) { return pngInfo, nil }
+		darwinClipboardExtract = func() ([]byte, error) { return nil, errors.New("exit status 127") }
+
+		data, err := readClipboardImageDarwin()
+		if !errors.Is(err, ErrClipboardImageUnreadable) {
+			t.Fatalf("err = %v, want ErrClipboardImageUnreadable; a stock Mac gets silence instead of a remedy", err)
+		}
+		if data != nil {
+			t.Fatalf("data = %q, want none", data)
+		}
+	})
+
+	t.Run("extractor producing nothing is also actionable", func(t *testing.T) {
+		darwinClipboardInfo = func() (string, error) { return pngInfo, nil }
+		darwinClipboardExtract = func() ([]byte, error) { return nil, nil }
+
+		if _, err := readClipboardImageDarwin(); !errors.Is(err, ErrClipboardImageUnreadable) {
+			t.Fatalf("err = %v, want ErrClipboardImageUnreadable for an extractor that exits 0 with no bytes", err)
+		}
+	})
+
+	// The other half of the distinction, and the reason this cannot simply always
+	// report an error: an empty clipboard is an ordinary no-op, and turning that
+	// into a notice would make every stray Ctrl+V nag the user.
+	t.Run("no image on the clipboard stays silent", func(t *testing.T) {
+		darwinClipboardInfo = func() (string, error) { return `«class utf8»`, nil }
+		darwinClipboardExtract = func() ([]byte, error) {
+			t.Fatal("extractor ran despite the clipboard offering no image")
+			return nil, nil
+		}
+
+		data, err := readClipboardImageDarwin()
+		if err != nil || data != nil {
+			t.Fatalf("data=%q err=%v, want a silent no-op", data, err)
+		}
+	})
+
+	t.Run("probe failure stays silent", func(t *testing.T) {
+		darwinClipboardInfo = func() (string, error) { return "", errors.New("osascript missing") }
+		darwinClipboardExtract = func() ([]byte, error) {
+			t.Fatal("extractor ran despite the info probe failing")
+			return nil, nil
+		}
+
+		if data, err := readClipboardImageDarwin(); err != nil || data != nil {
+			t.Fatalf("data=%q err=%v, want a silent no-op", data, err)
+		}
+	})
+
+	t.Run("working extractor returns the bytes", func(t *testing.T) {
+		darwinClipboardInfo = func() (string, error) { return pngInfo, nil }
+		darwinClipboardExtract = func() ([]byte, error) { return []byte("png-bytes"), nil }
+
+		data, err := readClipboardImageDarwin()
+		if err != nil {
+			t.Fatalf("err = %v, want none", err)
+		}
+		if string(data) != "png-bytes" {
+			t.Fatalf("data = %q, want the extractor's bytes", data)
+		}
+	})
+}
@@ -48,7 +48,7 @@ func buildMinimalPDF(text string) []byte {
 	buf.WriteString("0 " + strconv.Itoa(len(offsets)+1) + "\n")
 	buf.WriteString("0000000000 65535 f \n")
 	for _, off := range offsets {
-		buf.WriteString(fmt.Sprintf("%010d 00000 n \n", off))
+		fmt.Fprintf(&buf, "%010d 00000 n \n", off)
 	}
 	buf.WriteString("trailer\n<< /Size " + strconv.Itoa(len(offsets)+1) + " /Root 1 0 R >>\n")
 	buf.WriteString("startxref\n" + strconv.Itoa(xrefStart) + "\n%%EOF\n")
@@ -277,7 +277,7 @@ func buildEmptyTextPDF() []byte {
 	buf.WriteString("0 " + strconv.Itoa(len(offsets)+1) + "\n")
 	buf.WriteString("0000000000 65535 f \n")
 	for _, off := range offsets {
-		buf.WriteString(fmt.Sprintf("%010d 00000 n \n", off))
+		fmt.Fprintf(&buf, "%010d 00000 n \n", off)
 	}
 	buf.WriteString("trailer\n<< /Size " + strconv.Itoa(len(offsets)+1) + " /Root 1 0 R >>\n")
 	buf.WriteString("startxref\n" + strconv.Itoa(xrefStart) + "\n%%EOF\n")
@@ -0,0 +1,14 @@
+// Test seams: helpers only test code uses, kept out of the production binary.
+package lsp
+
+import "os/exec"
+
+// Available reports whether a configured server for the path exists on PATH.
+func Available(path string) bool {
+	cmd, ok := ServerFor(path)
+	if !ok {
+		return false
+	}
+	_, err := exec.LookPath(cmd[0])
+	return err == nil
+}
@@ -1,6 +1,7 @@
 package lsp

 import (
+	"context"
 	"encoding/json"
 	"testing"
 )
@@ -64,7 +65,7 @@ func TestDecodeSymbols(t *testing.T) {

 func TestNavigateUnknownOp(t *testing.T) {
 	m := NewManager(t.TempDir())
-	_, _, ok, err := m.Navigate(nil, NavRequest{Op: "bogus", Path: "x.go"})
+	_, _, ok, err := m.Navigate(context.TODO(), NavRequest{Op: "bogus", Path: "x.go"})
 	if err == nil {
 		t.Fatal("expected an error for an unknown nav op")
 	}
@@ -76,7 +77,7 @@ func TestNavigateUnknownOp(t *testing.T) {
 func TestNavigateUnsupportedExtensionDegrades(t *testing.T) {
 	// A file type with no configured server degrades to ok=false, no error.
 	m := NewManager(t.TempDir())
-	_, _, ok, err := m.Navigate(nil, NavRequest{Op: NavDefinition, Path: "notes.unknownext", Line: 1, Character: 1})
+	_, _, ok, err := m.Navigate(context.TODO(), NavRequest{Op: NavDefinition, Path: "notes.unknownext", Line: 1, Character: 1})
 	if err != nil {
 		t.Fatalf("unsupported extension should not error, got %v", err)
 	}
@@ -1,7 +1,6 @@
 package lsp

 import (
-	"os/exec"
 	"path/filepath"
 	"sort"
 	"strings"
@@ -176,16 +175,6 @@ func LanguageID(path string) (string, bool) {
 	return id, ok
 }

-// Available reports whether a configured server for the path exists on PATH.
-func Available(path string) bool {
-	cmd, ok := ServerFor(path)
-	if !ok {
-		return false
-	}
-	_, err := exec.LookPath(cmd[0])
-	return err == nil
-}
-
 func extKey(path string) string {
 	return strings.ToLower(filepath.Ext(path))
 }
@@ -4,7 +4,6 @@ import (
 	"context"
 	"errors"
 	"path/filepath"
-	"strings"
 	"testing"
 	"time"

@@ -289,7 +288,7 @@ func TestRegistryToolIsDeferredEligible(t *testing.T) {

 // TestRegistryToolReportsMCPServerName verifies the registryTool reports its true
 // configured server name (not the sanitized tool-name token) so the deferred-tools
-// reminder labels a multi-token server correctly via tools.DeferredLine.
+// discovery label names a multi-token server correctly via tools.DeferredSource.
 func TestRegistryToolReportsMCPServerName(t *testing.T) {
 	client := &fakeToolClient{}
 	// A server name that sanitizes to a token containing an underscore ("git_hub"):
@@ -305,14 +304,9 @@ func TestRegistryToolReportsMCPServerName(t *testing.T) {
 		t.Fatalf("MCPServerName() = %q, want %q", tool.MCPServerName(), "git hub")
 	}

-	// DeferredLine must prefer the reported server name over the name-derived token.
-	line := tools.DeferredLine(tool)
-	if !strings.Contains(line, "server: git hub") {
-		t.Fatalf("DeferredLine = %q, want it to label server as %q via MCPServerName()", line, "git hub")
-	}
-	// The truncated token-only label ("git") must NOT be the server segment.
-	if strings.Contains(line, "server: git |") {
-		t.Fatalf("DeferredLine = %q, mislabeled multi-token server with the truncated token", line)
+	// DeferredSource must prefer the reported server name over the name-derived token.
+	if source := tools.DeferredSource(tool); source != "git hub" {
+		t.Fatalf("DeferredSource = %q, want %q via MCPServerName()", source, "git hub")
 	}
 }

@@ -0,0 +1,21 @@
+package modelregistry
+
+import "sync"
+
+// resetModelsDevCacheForTest clears the process-level cache memoization and
+// disables the overlay.
+func resetModelsDevCacheForTest() {
+	modelsDevOnce = sync.Once{}
+	modelsDevCached = nil
+	modelsDevEnabled.Store(false)
+}
+
+// Modes returns a copy of the preset catalog, preserving declaration order so
+// list output and help text stay stable.
+func Modes() []Mode {
+	modes := make([]Mode, len(defaultModes))
+	for index, mode := range defaultModes {
+		modes[index] = cloneMode(mode)
+	}
+	return modes
+}
@@ -197,14 +197,6 @@ func cachedModelsDevProviders() map[string]map[string]modelsDevModel {
 	return modelsDevCached
 }

-// resetModelsDevCacheForTest clears the process-level cache memoization and
-// disables the overlay.
-func resetModelsDevCacheForTest() {
-	modelsDevOnce = sync.Once{}
-	modelsDevCached = nil
-	modelsDevEnabled.Store(false)
-}
-
 // RefreshModelsDevCache fetches models.dev/api.json into the on-disk cache
 // when the cache is missing or older than modelsDevRefreshAfter. It is safe to
 // call fire-and-forget from startup (use a goroutine); it never affects the
@@ -62,16 +62,6 @@ var defaultModes = []Mode{
 	},
 }

-// Modes returns a copy of the preset catalog, preserving declaration order so
-// list output and help text stay stable.
-func Modes() []Mode {
-	modes := make([]Mode, len(defaultModes))
-	for index, mode := range defaultModes {
-		modes[index] = cloneMode(mode)
-	}
-	return modes
-}
-
 // LookupMode returns the preset registered under name (case-insensitive,
 // whitespace-trimmed). The second result reports whether a preset matched.
 func LookupMode(name string) (Mode, bool) {
@@ -0,0 +1,7 @@
+// Test seams: helpers only test code uses, kept out of the production binary.
+package notify
+
+// Enabled reports whether mode will ever emit a notification.
+func Enabled(mode Mode) bool {
+	return mode != "" && mode != ModeOff
+}
@@ -167,11 +167,6 @@ func sequence(mode Mode, message string) string {
 	}
 }

-// Enabled reports whether mode will ever emit a notification.
-func Enabled(mode Mode) bool {
-	return mode != "" && mode != ModeOff
-}
-
 // sanitizeMessage drops control bytes (so the message can't break the escape or
 // inject terminal control) and clamps to maxMessageLen runes.
 func sanitizeMessage(s string) string {
@@ -284,7 +284,7 @@ const skillFileName = "SKILL.md"

 // MergedSkills loads the default skills directory, the shared ~/.agents/skills
 // root when present, plus the supplied plugin skill roots and returns one
-// merged, name-deduplicated list (Content stripped, like skills.List) alongside
+// merged, name-deduplicated list (Content stripped, like skills.ListFromRoots) alongside
 // the duplicate-name collisions across all roots. Earlier roots win a name
 // clash, matching skills.Load's first-wins rule; the default dir is always
 // considered first so a user skill shadows agents and plugins. A bad root simply
@@ -138,6 +138,7 @@ var descriptors = []Descriptor{
 	openAICompat("groq", "Groq", "https://api.groq.com/openai/v1", "llama-3.3-70b-versatile", []string{"GROQ_API_KEY"}),
 	openAICompat("deepseek", "DeepSeek", "https://api.deepseek.com/v1", "deepseek-chat", []string{"DEEPSEEK_API_KEY"}),
 	openAICompat("together", "Together AI", "https://api.together.xyz/v1", "meta-llama/Llama-3.3-70B-Instruct-Turbo", []string{"TOGETHER_API_KEY"}),
+	openAICompat("fireworks", "Fireworks AI", "https://api.fireworks.ai/inference/v1", "accounts/fireworks/models/kimi-k2p7-code", []string{"FIREWORKS_API_KEY"}, "fireworks-ai"),
 	openAICompat("dashscope", "DashScope", "https://dashscope-intl.aliyuncs.com/compatible-mode/v1", "qwen-plus", []string{"DASHSCOPE_API_KEY", "QWEN_API_KEY"}, "qwen"),
 	openAICompat("moonshot", "Moonshot AI", "https://api.moonshot.ai/v1", "kimi-k2-0905-preview", []string{"MOONSHOT_API_KEY"}, "kimi"),
 	openAICompat("atlascloud", "Atlas Cloud", "https://api.atlascloud.ai/v1", "qwen/qwen3.5-flash", []string{"ATLASCLOUD_API_KEY"}, "atlas cloud", "atlas"),
@@ -187,14 +188,6 @@ func All() []Descriptor {
 	return copied
 }

-func IDs() []string {
-	ids := make([]string, 0, len(descriptors))
-	for _, descriptor := range descriptors {
-		ids = append(ids, descriptor.ID)
-	}
-	return ids
-}
-
 func Get(id string) (Descriptor, bool) {
 	normalized := NormalizeID(id)
 	for _, descriptor := range descriptors {
@@ -219,35 +212,6 @@ func Require(id string) (Descriptor, error) {
 	return descriptor, nil
 }

-func ListByTransport(transport Transport) []Descriptor {
-	normalized := Transport(NormalizeID(string(transport)))
-	items := make([]Descriptor, 0)
-	for _, descriptor := range descriptors {
-		if descriptor.Transport == normalized {
-			items = append(items, cloneDescriptor(descriptor))
-		}
-	}
-	return items
-}
-
-func ValidTransport(transport Transport) bool {
-	switch Transport(NormalizeID(string(transport))) {
-	case TransportOpenAI, TransportAnthropic, TransportGoogle, TransportBedrock, TransportVertex, TransportOpenAICompatible, TransportAnthropicCompatible:
-		return true
-	default:
-		return false
-	}
-}
-
-func ValidAPIFormat(format APIFormat) bool {
-	switch format {
-	case APIFormatOpenAIResponses, APIFormatOpenAIChatCompletions, APIFormatAnthropicMessages, APIFormatGoogleGenerateContent, APIFormatBedrockConverse, APIFormatVertexGenerateContent:
-		return true
-	default:
-		return false
-	}
-}
-
 func NormalizeID(id string) string {
 	var builder strings.Builder
 	lastDash := false
@@ -22,6 +22,7 @@ var expectedCatalogIDs = []string{
 	"groq",
 	"deepseek",
 	"together",
+	"fireworks",
 	"dashscope",
 	"moonshot",
 	"atlascloud",
@@ -155,6 +156,28 @@ func TestLongCatDescriptor(t *testing.T) {
 	}
 }

+func TestFireworksDescriptor(t *testing.T) {
+	descriptor, err := Require("fireworks")
+	if err != nil {
+		t.Fatalf("Require(fireworks) error = %v", err)
+	}
+	if descriptor.Name != "Fireworks AI" {
+		t.Fatalf("Name = %q, want Fireworks AI", descriptor.Name)
+	}
+	if descriptor.DefaultBaseURL != "https://api.fireworks.ai/inference/v1" {
+		t.Fatalf("DefaultBaseURL = %q, want Fireworks OpenAI-compatible endpoint", descriptor.DefaultBaseURL)
+	}
+	if descriptor.DefaultModel != "accounts/fireworks/models/kimi-k2p7-code" {
+		t.Fatalf("DefaultModel = %q, want accounts/fireworks/models/kimi-k2p7-code", descriptor.DefaultModel)
+	}
+	if descriptor.Transport != TransportOpenAICompatible {
+		t.Fatalf("Transport = %q, want %q", descriptor.Transport, TransportOpenAICompatible)
+	}
+	if !reflect.DeepEqual(descriptor.AuthEnvVars, []string{"FIREWORKS_API_KEY"}) {
+		t.Fatalf("AuthEnvVars = %#v, want FIREWORKS_API_KEY", descriptor.AuthEnvVars)
+	}
+}
+
 func TestAtlasCloudDescriptor(t *testing.T) {
 	descriptor, err := Require("atlascloud")
 	if err != nil {
@@ -346,7 +369,7 @@ func TestListByTransportPreservesCatalogOrder(t *testing.T) {
 		TransportBedrock:         {"bedrock"},
 		TransportVertex:          {"vertex"},
 		TransportAnthropicCompat: {"minimax", "minimaxi-cn", "opencode-go-anthropic-compatible", "custom-anthropic-compatible"},
-		TransportOpenAICompat:    {"gitlawb-opengateway", "aimlapi", "ollama-cloud", "ollama", "lmstudio", "openrouter", "huggingface", "chatgpt", "groq", "deepseek", "together", "dashscope", "moonshot", "atlascloud", "longcat", "nvidia-nim", "mistral", "github", "xai", "venice", "xiaomi-mimo", "bankr", "zai", "zai-cn", "kilocode", "opencode", "opencode-go", "atomic-chat", "chatgpt-proxy", "custom-openai-compatible"},
+		TransportOpenAICompat:    {"gitlawb-opengateway", "aimlapi", "ollama-cloud", "ollama", "lmstudio", "openrouter", "huggingface", "chatgpt", "groq", "deepseek", "together", "fireworks", "dashscope", "moonshot", "atlascloud", "longcat", "nvidia-nim", "mistral", "github", "xai", "venice", "xiaomi-mimo", "bankr", "zai", "zai-cn", "kilocode", "opencode", "opencode-go", "atomic-chat", "chatgpt-proxy", "custom-openai-compatible"},
 	}

 	for transport, wantIDs := range cases {
@@ -0,0 +1,39 @@
+// Test seams: helpers only test code uses, kept out of the production binary.
+package providercatalog
+
+func IDs() []string {
+	ids := make([]string, 0, len(descriptors))
+	for _, descriptor := range descriptors {
+		ids = append(ids, descriptor.ID)
+	}
+	return ids
+}
+
+func ListByTransport(transport Transport) []Descriptor {
+	normalized := Transport(NormalizeID(string(transport)))
+	items := make([]Descriptor, 0)
+	for _, descriptor := range descriptors {
+		if descriptor.Transport == normalized {
+			items = append(items, cloneDescriptor(descriptor))
+		}
+	}
+	return items
+}
+
+func ValidAPIFormat(format APIFormat) bool {
+	switch format {
+	case APIFormatOpenAIResponses, APIFormatOpenAIChatCompletions, APIFormatAnthropicMessages, APIFormatGoogleGenerateContent, APIFormatBedrockConverse, APIFormatVertexGenerateContent:
+		return true
+	default:
+		return false
+	}
+}
+
+func ValidTransport(transport Transport) bool {
+	switch Transport(NormalizeID(string(transport))) {
+	case TransportOpenAI, TransportAnthropic, TransportGoogle, TransportBedrock, TransportVertex, TransportOpenAICompatible, TransportAnthropicCompatible:
+		return true
+	default:
+		return false
+	}
+}
@@ -391,7 +391,7 @@ func validateEndpoint(ctx context.Context, endpoint string, resolver Resolver, a
 		return endpointSafetyError{message: "provider connectivity URL is unsafe: localhost hosts are blocked"}
 	}
 	if addr, err := netip.ParseAddr(normalized); err == nil {
-		if reason := blockedAddrReason(addr); reason != "" && !(allowLoopbackOrPrivate && (addr.IsLoopback() || addr.IsPrivate())) {
+		if reason := blockedAddrReason(addr); reason != "" && (!allowLoopbackOrPrivate || (!addr.IsLoopback() && !addr.IsPrivate())) {
 			return endpointSafetyError{message: "provider connectivity URL is unsafe: " + reason}
 		}
 		return nil
@@ -407,7 +407,7 @@ func validateEndpoint(ctx context.Context, endpoint string, resolver Resolver, a
 		return endpointSafetyError{message: "provider connectivity host resolved to no addresses"}
 	}
 	for _, addr := range addrs {
-		if reason := blockedAddrReason(addr); reason != "" && !(allowLoopbackOrPrivate && (addr.IsLoopback() || addr.IsPrivate())) {
+		if reason := blockedAddrReason(addr); reason != "" && (!allowLoopbackOrPrivate || (!addr.IsLoopback() && !addr.IsPrivate())) {
 			return endpointSafetyError{message: "provider connectivity URL is unsafe: " + reason}
 		}
 	}
@@ -529,7 +529,7 @@ func safeDialContext(resolver Resolver, allowLoopbackOrPrivate bool) func(contex
 			return nil, err
 		}
 		if addr, parseErr := netip.ParseAddr(host); parseErr == nil {
-			if reason := blockedAddrReason(addr); reason != "" && !(allowLoopbackOrPrivate && (addr.IsLoopback() || addr.IsPrivate())) {
+			if reason := blockedAddrReason(addr); reason != "" && (!allowLoopbackOrPrivate || (!addr.IsLoopback() && !addr.IsPrivate())) {
 				return nil, endpointSafetyError{message: "provider connectivity URL is unsafe: " + reason}
 			}
 			return dialer.DialContext(ctx, network, address)
@@ -542,7 +542,7 @@ func safeDialContext(resolver Resolver, allowLoopbackOrPrivate bool) func(contex
 			return nil, endpointSafetyError{message: "provider connectivity host resolved to no addresses"}
 		}
 		for _, addr := range addrs {
-			if reason := blockedAddrReason(addr); reason != "" && !(allowLoopbackOrPrivate && (addr.IsLoopback() || addr.IsPrivate())) {
+			if reason := blockedAddrReason(addr); reason != "" && (!allowLoopbackOrPrivate || (!addr.IsLoopback() && !addr.IsPrivate())) {
 				return nil, endpointSafetyError{message: "provider connectivity URL is unsafe: " + reason}
 			}
 		}
@@ -122,6 +122,14 @@ var curatedModels = map[string][]Model{
 		{ID: "deepseek-ai/DeepSeek-R1", Description: "reasoning model"},
 		{ID: "meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8", Description: "multimodal model"},
 	},
+	"fireworks": {
+		// Serverless-only curated set: ordinary API-key setups hit /inference/v1
+		// and cannot use on-demand deployment IDs.
+		{ID: "accounts/fireworks/models/kimi-k2p7-code", Description: "catalog default"},
+		{ID: "accounts/fireworks/models/deepseek-v4-flash", Description: "fast coding model"},
+		{ID: "accounts/fireworks/models/gpt-oss-120b", Description: "general model"},
+		{ID: "accounts/fireworks/models/deepseek-v4-pro", Description: "reasoning model"},
+	},
 	"dashscope": {
 		{ID: "qwen-plus", Description: "catalog default"},
 		{ID: "qwen-max", Description: "strong general model"},
@@ -28,6 +28,11 @@ func TestModelsAreProviderScoped(t *testing.T) {
 			want:     []string{"llama-3.3-70b-versatile", "openai/gpt-oss-120b"},
 			notWant:  []string{"gpt-4.1", "claude-sonnet-4.5"},
 		},
+		{
+			provider: "fireworks",
+			want:     []string{"accounts/fireworks/models/kimi-k2p7-code", "accounts/fireworks/models/deepseek-v4-flash"},
+			notWant:  []string{"gpt-4.1", "llama-3.3-70b-versatile"},
+		},
 		{
 			provider: "chatgpt",
 			want:     []string{"gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark"},
@@ -132,6 +132,8 @@ func ModelsDevProviderID(provider providercatalog.Descriptor) string {
 		return "zai"
 	case "minimaxi-cn":
 		return "minimax"
+	case "fireworks":
+		return "fireworks-ai"
 	default:
 		return strings.TrimSpace(provider.ID)
 	}
@@ -131,6 +131,7 @@ func TestModelsDevProviderIDMapsZeroAliases(t *testing.T) {
 		"ollama-cloud": "ollama-cloud",
 		"zai-cn":       "zai",
 		"minimaxi-cn":  "minimax",
+		"fireworks":    "fireworks-ai",
 	}
 	for zeroID, want := range tests {
 		provider, ok := providercatalog.Get(zeroID)
@@ -62,7 +62,7 @@ func TestDetectLocalRuntimesReportsReachableRuntime(t *testing.T) {
 	if !detected[0].Reachable {
 		t.Fatalf("runtime should be reachable: %#v", detected[0])
 	}
-	if detected[0].Models == nil || len(detected[0].Models) == 0 || detected[0].Models[0] != "llama3.1" {
+	if len(detected[0].Models) == 0 || detected[0].Models[0] != "llama3.1" {
 		t.Fatalf("expected discovered model list, got %#v", detected[0].Models)
 	}
 }
@@ -3,7 +3,6 @@ package openai
 import (
 	"context"
 	"encoding/json"
-	"errors"
 	"fmt"
 	"net/http"
 	"strings"
@@ -207,14 +206,3 @@ func (p *CodexProvider) resolveAccount(ctx context.Context) (string, bool, error
 	}
 	return "", false, nil
 }
-
-// ValidateAccount is a convenience for tests/callers that want to confirm the
-// account id is the right shape (non-empty, trimmed). It is a no-op helper
-// rather than a constructor check so a Codex provider can be built before the
-// first login completes.
-func ValidateAccount(account string) error {
-	if strings.TrimSpace(account) == "" {
-		return errors.New("openai codex: account id is empty")
-	}
-	return nil
-}
@@ -0,0 +1,18 @@
+// Test seams: helpers only test code uses, kept out of the production binary.
+package openai
+
+import (
+	"errors"
+	"strings"
+)
+
+// ValidateAccount is a convenience for tests/callers that want to confirm the
+// account id is the right shape (non-empty, trimmed). It is a no-op helper
+// rather than a constructor check so a Codex provider can be built before the
+// first login completes.
+func ValidateAccount(account string) error {
+	if strings.TrimSpace(account) == "" {
+		return errors.New("openai codex: account id is empty")
+	}
+	return nil
+}
@@ -945,9 +945,9 @@ func TestStreamCompletionSurfacesLengthFinishReason(t *testing.T) {
 		t.Fatalf("done FinishReason = %q, want %q", doneReason, zeroruntime.FinishReasonLength)
 	}

-	// And it round-trips through the runtime collector as Truncated.
+	// And it round-trips through the runtime collector's FinishReason.
 	collected := zeroruntime.CollectStream(context.Background(), replay(events))
-	if !collected.Truncated() || collected.FinishReason != zeroruntime.FinishReasonLength {
+	if collected.FinishReason != zeroruntime.FinishReasonLength {
 		t.Fatalf("collected = %+v, want truncated length", collected)
 	}
 }
@@ -25,7 +25,9 @@ type TokenResolver func(ctx context.Context, forceRefresh bool) (header string,
 //
 // base carries the API-key auth config (key + default header/scheme). setExtra
 // (optional) sets the provider's non-auth headers on every attempt. Transient
-// retries (429/503/529) are handled by the inner SendWithRetry.
+// retries are handled by the inner SendWithRetry: 429/503/529 on their own
+// budget, and provably pre-send transport failures (refused or timed-out
+// connect, DNS, TLS handshake) on a separate, shorter one.
 func SendWithAuthRetry(
 	ctx context.Context,
 	client *http.Client,
@@ -0,0 +1,14 @@
+// Test seams: helpers only test code uses, kept out of the production binary.
+package providerio
+
+import (
+	"bufio"
+	"io"
+)
+
+// ScanSSEData parses Server-Sent Event data fields from a streaming response.
+func ScanSSEData(reader io.Reader, handle func(data string) bool) error {
+	scanner := bufio.NewScanner(reader)
+	scanner.Buffer(make([]byte, 0, 4096), maxSSELineBytes)
+	return scanSSEPayloads(scanner, handle, nil)
+}
@@ -195,13 +195,6 @@ func SendEvent(ctx context.Context, events chan<- zeroruntime.StreamEvent, event
 	}
 }

-// ScanSSEData parses Server-Sent Event data fields from a streaming response.
-func ScanSSEData(reader io.Reader, handle func(data string) bool) error {
-	scanner := bufio.NewScanner(reader)
-	scanner.Buffer(make([]byte, 0, 4096), maxSSELineBytes)
-	return scanSSEPayloads(scanner, handle, nil)
-}
-
 // scanSSEPayloads accumulates SSE "data:" lines into payloads (joined across
 // continuation lines, flushed on a blank line or EOF) and forwards each to
 // handle. It is the shared core of ScanSSEData and the idle-aware variant.
@@ -3,6 +3,9 @@ package providerio
 import (
 	"bytes"
 	"context"
+	"errors"
+	"io"
+	"net"
 	"net/http"
 	"strconv"
 	"strings"
@@ -17,13 +20,22 @@ import (
 // (previously only the OpenAI provider retried; Anthropic and Gemini surfaced the
 // first failure).
 //
-// What is retried: ONLY 429 (rate limit) and 503 (service unavailable) — the
-// statuses where the server explicitly did NOT accept the request, so replaying
-// it cannot duplicate work. Other 5xx (500/502/504) and transport/network errors
-// are NOT retried: a completion POST is non-idempotent and may have reached and
-// been processed by the server, so replaying it could duplicate
-// (billable) work. Only the INITIAL request is ever in scope; once the response
-// body starts streaming it is never re-issued.
+// What is retried: 429 (rate limit) and 503 (service unavailable) — the statuses
+// where the server explicitly did NOT accept the request — plus PROVABLY
+// pre-send transport failures (DNS resolution, a refused/unreachable dial, a TLS
+// handshake timeout) where no request bytes ever left this host. In every one of
+// those cases we KNOW the server did not receive and process the request, so a
+// replay cannot duplicate work. Other 5xx (500/502/504) and every ambiguous or
+// post-send transport error (connection reset, broken pipe, EOF, a generic i/o
+// timeout, context deadline) are NOT retried: a completion POST is
+// non-idempotent and may already have reached and been processed by the server,
+// so replaying it could duplicate (billable) work. Only the INITIAL request is
+// ever in scope; once the response body starts streaming it is never re-issued.
+// Pre-send classification is by syscall errno (portable across POSIX and
+// Windows), scoped to an Op=="dial" *net.OpError so the same errno raised on a
+// post-send read/write can't be misread as pre-send. NXDOMAIN is treated as
+// permanent (not retried), and the pre-send path fails fast on its own
+// sub-second schedule rather than the seconds-long 429 backoff.

 const defaultMaxRetryAttempts = 6

@@ -37,12 +49,32 @@ const maxBackoff = 30 * time.Second
 // schedule is 2s, 4s, 8s, 16s, then maxBackoff. A var so tests can shrink it.
 var retryBackoffBase = 2 * time.Second

+// preSendMaxAttempts bounds retries of a provably pre-send transport failure.
+// Unlike a 429 (whose window is measured in seconds), a refused/unreachable dial
+// either recovers within a few hundred ms or is a deterministic misconfiguration
+// (wrong host/port, dead local daemon) that will never recover — so a short,
+// low-count schedule fails fast instead of stalling the agent ~60s on the
+// rate-limit schedule. This bounds the pre-send path independently of the caller's
+// maxAttempts, which is tuned for 429/503.
+const preSendMaxAttempts = 3
+
+// preSendBackoffBase is the first wait before replaying a pre-send transport
+// failure. Modeled on the mid-stream reconnect base (internal/agent/reconnect.go),
+// it is sub-second so a transient dial blip recovers quickly and a permanent one
+// fails fast. A var so tests can shrink it.
+var preSendBackoffBase = 500 * time.Millisecond
+
 // SendWithRetry issues an HTTP request, retrying ONLY the safe-to-replay server
 // responses (429 and 503, see ShouldRetryStatus) up to maxAttempts — backing off
 // between tries and honoring a server Retry-After header and context
-// cancellation. Other 5xx and transport/network errors are returned immediately,
-// never replayed (see the package note). The request is rebuilt from body each
-// attempt; setHeader (if non-nil) sets headers on every attempt.
+// cancellation. The one transport-error exception is a PROVABLY pre-send failure
+// (see isPreSendTransportError): a refused/unreachable dial or DNS failure where
+// no request bytes left this host, retried on its own short schedule
+// (preSendMaxAttempts / preSendBackoff). Every other 5xx and every ambiguous or
+// post-send transport error is returned immediately, never replayed, because a
+// non-idempotent completion POST may already have been received. The request is
+// rebuilt from body each attempt; setHeader (if non-nil) sets headers on every
+// attempt.
 //
 // It returns the final *http.Response (which the caller inspects for a non-2xx
 // status, exactly as before) or an error for a network failure / context
@@ -60,7 +92,47 @@ func SendWithRetry(
 	if maxAttempts <= 0 {
 		maxAttempts = defaultMaxRetryAttempts
 	}
-	for attempt := 1; ; attempt++ {
+	if client == nil {
+		client = http.DefaultClient
+	}
+	// Redirects are still FOLLOWED, so a redirecting gateway keeps working, but
+	// entering one makes that attempt non-retryable. The hazard is that client.Do
+	// can transmit the original POST to the first host, follow a 307/308, and then
+	// fail the dial to the redirect target: that error is an Op=="dial" error, so
+	// isPreSendTransportError would read it as "nothing was sent" and replay a
+	// completion the first host already received. Observing the redirect rather
+	// than blocking it keeps both properties, since a request that was redirected
+	// is never replayed while redirecting endpoints stay usable. The caller's own
+	// CheckRedirect still runs and still decides whether to proceed.
+	redirected := false
+	callerCheckRedirect := client.CheckRedirect
+	redirectAwareClient := *client
+	redirectAwareClient.CheckRedirect = func(request *http.Request, via []*http.Request) error {
+		redirected = true
+		if callerCheckRedirect != nil {
+			return callerCheckRedirect(request, via)
+		}
+		// Mirror net/http's default policy, which a nil CheckRedirect would have
+		// applied: stop after 10 hops.
+		if len(via) >= 10 {
+			return errors.New("stopped after 10 redirects")
+		}
+		return nil
+	}
+	// The two retry budgets are fully independent, each with its own counter and
+	// its own backoff ordinal, because they answer different questions: a
+	// dial/DNS/TLS failure is a fast local blip (preSendMaxAttempts, sub-second
+	// schedule) while a 429/503 is a server-side window measured in seconds
+	// (maxAttempts, retryBackoffBase). A single shared loop counter coupled them
+	// in both directions: status retries starved the pre-send budget, and
+	// pre-send retries shortened the status window and started its backoff at a
+	// later rung. Neither kind of failure now consumes or advances the other.
+	preSendAttempts := 0
+	statusAttempts := 0
+	for {
+		// Per attempt: only a redirect entered by THIS attempt can make its own
+		// transport error unsafe to replay.
+		redirected = false
 		request, err := http.NewRequestWithContext(ctx, method, url, bytes.NewReader(body))
 		if err != nil {
 			return nil, err
@@ -70,32 +142,78 @@ func SendWithRetry(
 		}

 		connectSpan := trace.FromContext(ctx).Span(trace.SpanProviderConnect)
-		response, err := client.Do(request)
+		response, err := redirectAwareClient.Do(request)
 		connectSpan.End()
 		if err != nil {
-			// A transport failure on a POST does NOT mean the server didn't receive
-			// it — the request may have arrived and be generating a (billable,
-			// non-idempotent) completion while only the response/connection failed.
-			// Replaying it could duplicate that work, so surface the error instead
-			// of retrying. Only 429/503 responses (below), where we KNOW the request
-			// was not accepted, are safe to retry.
+			// Context cancellation always surfaces as cancellation, never a retry.
 			if ctx.Err() != nil {
 				return nil, ctx.Err()
 			}
+			// A transport failure on a POST does NOT usually mean the server didn't
+			// receive it — the request may have arrived and be generating a
+			// (billable, non-idempotent) completion while only the response or
+			// connection failed. Replaying that could duplicate work, so it is
+			// surfaced immediately. The one safe exception is a PROVABLY pre-send
+			// failure (see isPreSendTransportError): the request never left this
+			// host, so a replay cannot duplicate anything — exactly like a 429/503
+			// where we KNOW the request was not accepted. The pre-send path uses
+			// its own short bound and sub-second schedule (preSendMaxAttempts /
+			// preSendBackoff), not the seconds-long 429 schedule, so a permanent
+			// dial failure fails fast instead of stalling the agent for ~60s.
+			// A redirect means the original POST already left this host, so the
+			// dial that failed belongs to a later hop and replaying would duplicate
+			// a completion the first host may already have processed.
+			if isPreSendTransportError(err) && !redirected {
+				preSendAttempts++
+				if preSendAttempts < preSendMaxAttempts {
+					if r := trace.FromContext(ctx); r != nil {
+						r.Counter(trace.CounterRetryCount, 1)
+					}
+					if preSendBackoff(ctx, preSendAttempts) {
+						continue
+					}
+					return nil, ctx.Err()
+				}
+			}
 			return nil, err
 		}

-		if ShouldRetryStatus(response.StatusCode) && attempt < maxAttempts {
-			if r := trace.FromContext(ctx); r != nil {
-				r.Counter(trace.CounterRetryCount, 1)
+		// Deliberately NOT guarded on `redirected`, unlike the transport-error
+		// branch above. The two differ in what is known about the request. A
+		// transport failure after a redirect leaves it unknown whether the
+		// redirect target received and began processing the POST, so replaying
+		// could duplicate billable work. Here every hop answered: a 307/308 is the
+		// origin declining and delegating, and a retryable status is the target
+		// declining as well, so nothing accepted the request and a replay
+		// duplicates nothing.
+		//
+		// The exposure is also identical to a retryable status with no redirect in
+		// play, which this package has always retried. Guarding on redirects here
+		// would not close a gap, it would make a rate-limited completion behind a
+		// redirecting gateway fail outright instead of backing off.
+		// The transport hop succeeded, so the connect phase is healthy again and
+		// the pre-send budget starts over. It bounds CONSECUTIVE connect failures,
+		// not the lifetime of the call: without this reset, two early dial retries
+		// followed by a 429 and then one more dial blip would surface a transport
+		// error while the status budget still had room, which is the coupling
+		// these two counters were split apart to remove. Total work stays bounded,
+		// since every reset costs a status attempt and those are capped.
+		preSendAttempts = 0
+
+		if ShouldRetryStatus(response.StatusCode) {
+			statusAttempts++
+			if statusAttempts < maxAttempts {
+				if r := trace.FromContext(ctx); r != nil {
+					r.Counter(trace.CounterRetryCount, 1)
+				}
+				wait := RetryAfter(response)
+				_ = response.Body.Close()
+				if Backoff(ctx, statusAttempts, wait) {
+					continue
+				}
+				// Backoff aborted: the only reason it returns false is ctx cancellation.
+				return nil, ctx.Err()
 			}
-			wait := RetryAfter(response)
-			_ = response.Body.Close()
-			if Backoff(ctx, attempt, wait) {
-				continue
-			}
-			// Backoff aborted: the only reason it returns false is ctx cancellation.
-			return nil, ctx.Err()
 		}

 		// Success, a non-retryable status, or retries exhausted on a retryable
@@ -109,6 +227,119 @@ func SendWithRetry(
 	}
 }

+// isPreSendTransportError reports whether a transport error PROVES no request
+// bytes reached the server, so replaying the request cannot duplicate a
+// billable completion. Only narrow, unambiguous pre-connect failures qualify: a
+// recoverable DNS lookup failure, a refused/unreachable dial, and a TLS
+// handshake timeout (the handshake completes before any HTTP request bytes are
+// written).
+//
+// The refused/unreachable errnos (ECONNREFUSED/ENETUNREACH/EHOSTUNREACH) are
+// matched by syscall errno via errors.Is — portable across platforms, since Go
+// maps the WSA* codes on Windows too — but ONLY when carried by an Op=="dial"
+// *net.OpError. errors.Is matches an errno anywhere in the chain regardless of
+// which socket operation raised it, and the kernel raises these same errnos on
+// an established connection when a route drops mid-generation; scoping to the
+// dial phase is what makes "no request bytes were sent" structural rather than
+// argued, so a post-send read/write can never replay a non-idempotent POST.
+// NXDOMAIN is treated as permanent (deterministic) and is NOT retried.
+//
+// Ambiguous or post-send failures are deliberately excluded and checked FIRST,
+// so an error that is both is never treated as pre-send: a reset or broken pipe
+// can follow a request that was already sent, and a bare "i/o timeout" covers
+// read timeouts after send as well as dial timeouts, so none of these prove the
+// request was not received and a non-idempotent POST must not be replayed on
+// them.
+func isPreSendTransportError(err error) bool {
+	if err == nil {
+		return false
+	}
+	// DNS resolution precedes any connection, so a lookup failure proves nothing
+	// was sent — but only retry a lookup that could plausibly succeed on a replay.
+	// NXDOMAIN (IsNotFound) is authoritative and deterministic (a mistyped or
+	// non-existent host), so retrying it just stalls the agent through the whole
+	// backoff schedule before failing anyway; a timeout or temporary SERVFAIL is
+	// worth another try. errors.As unwraps url.Error/OpError to reach the DNSError.
+	var dnsErr *net.DNSError
+	if errors.As(err, &dnsErr) {
+		return !dnsErr.IsNotFound
+	}
+	// Post-send / ambiguous failures, excluded first. EOF and reset are matched
+	// by identity so wording (or a hostname containing "eof") can't fool them.
+	if errors.Is(err, io.EOF) || errors.Is(err, io.ErrUnexpectedEOF) || isConnResetErrno(err) {
+		return false
+	}
+	// A CONNECT-phase timeout is provably pre-send for the same structural reason
+	// a refused dial is: the connection was never established, so no request
+	// bytes left this host. It has to be admitted BEFORE the wording exclusions
+	// below, because net surfaces it with "i/o timeout" in the message, which the
+	// blanket exclusion would otherwise reject. The gate is what keeps that safe:
+	// a post-send read timeout is also Timeout(), but carries Op "read", so it
+	// never reaches here.
+	if opErr := connectOpError(err); opErr != nil && opErr.Timeout() {
+		return true
+	}
+	msg := strings.ToLower(err.Error())
+	if strings.Contains(msg, "connection reset") ||
+		strings.Contains(msg, "broken pipe") ||
+		strings.Contains(msg, "i/o timeout") {
+		return false
+	}
+	// A refused/unreachable connection is provably pre-send ONLY when it was
+	// raised during the DIAL (connection-establishment) phase. The same errnos
+	// are also raised by the kernel on an ESTABLISHED connection — when a route
+	// drops or an ICMP unreachable arrives mid-generation — which is post-send.
+	// errors.Is matches an errno anywhere in the chain regardless of the
+	// operation, so we first require an Op=="dial" *net.OpError: that makes "no
+	// request bytes left this host" structural, so a post-send read/write carrying
+	// one of these can never replay a non-idempotent POST. dialPreSendErrnos is
+	// platform-specific: on Windows a refused dial carries the raw WSA* errno
+	// (WSAECONNREFUSED etc.), which does NOT satisfy errors.Is against the POSIX
+	// syscall.ECONNREFUSED, so the Windows list adds those codes. The string
+	// markers only catch a POSIX dial error already flattened past its errno.
+	if connectOpError(err) != nil {
+		for _, errno := range dialPreSendErrnos {
+			if errors.Is(err, errno) {
+				return true
+			}
+		}
+		switch {
+		case strings.Contains(msg, "connection refused"),
+			strings.Contains(msg, "network is unreachable"),
+			strings.Contains(msg, "no route to host"):
+			return true
+		}
+	}
+	// A TLS handshake times out after the TCP dial connects but before any HTTP
+	// request bytes are written, so it is structurally pre-send. net/http surfaces
+	// it as its own error string, not a *net.OpError, so it is matched by wording
+	// independent of the dial gate.
+	if strings.Contains(msg, "tls handshake timeout") {
+		return true
+	}
+	return false
+}
+
+// connectOpError returns the outermost *net.OpError in err's chain when it comes
+// from the connection-establishment phase, else nil. Go tags a direct dial with
+// Op "dial" and a failed CONNECT through an HTTP proxy with Op "proxyconnect";
+// a failure on an already-established connection carries Op "read"/"write".
+// This is how isPreSendTransportError scopes the pre-send match to the connect
+// phase so a post-send failure can't be misclassified as pre-send.
+//
+// "proxyconnect" belongs here for the same reason "dial" does: when HTTPS_PROXY
+// is set and the CONNECT fails, the tunnel to the model host was never built, so
+// no request bytes reached it. Omitting it meant every pre-send failure behind a
+// corporate proxy fell through to no-retry, which is the environment where
+// transient connect failures are most common.
+func connectOpError(err error) *net.OpError {
+	var opErr *net.OpError
+	if errors.As(err, &opErr) && (opErr.Op == "dial" || opErr.Op == "proxyconnect") {
+		return opErr
+	}
+	return nil
+}
+
 // ShouldRetryStatus reports whether an HTTP status is safe to retry for a
 // non-idempotent completion POST: 429 (Too Many Requests), 503 (Service
 // Unavailable), and 529 (Anthropic's "overloaded"). All mean the server
@@ -137,6 +368,39 @@ func Backoff(ctx context.Context, attempt int, retryAfter time.Duration) bool {
 	}
 }

+// preSendBackoff waits before pre-send retry attempt N (1-based) on a short
+// sub-second schedule (500ms, 1s, ...), returning false if the context is
+// cancelled during the wait. Separate from Backoff's seconds-long rate-limit
+// schedule because a pre-send dial failure recovers in milliseconds or never.
+func preSendBackoff(ctx context.Context, attempt int) bool {
+	timer := time.NewTimer(preSendBackoffWait(attempt))
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return false
+	case <-timer.C:
+		return true
+	}
+}
+
+// preSendBackoffWait computes the pre-send wait before retry attempt N (1-based):
+// exponential from preSendBackoffBase (500ms, 1s, 2s, ...), capped at maxBackoff.
+// The exponent is clamped so a large attempt count cannot overflow.
+func preSendBackoffWait(attempt int) time.Duration {
+	exponent := attempt - 1
+	if exponent > 5 {
+		exponent = 5
+	}
+	if exponent < 0 {
+		exponent = 0
+	}
+	wait := preSendBackoffBase * time.Duration(1<<exponent)
+	if wait > maxBackoff {
+		wait = maxBackoff
+	}
+	return wait
+}
+
 // backoffWait computes the wait before retry attempt N (1-based): Retry-After
 // when supplied, else exponential from retryBackoffBase, both capped at
 // maxBackoff. The exponent is clamped so a large attempt count cannot overflow.
@@ -0,0 +1,32 @@
+//go:build !windows && !plan9
+
+package providerio
+
+import (
+	"errors"
+	"syscall"
+)
+
+// dialPreSendErrnos are the syscall errnos a refused or unreachable DIAL raises
+// on this platform. On POSIX the standard syscall constants are exactly what the
+// net package surfaces, so matching them via errors.Is is sufficient. Plan 9 is
+// excluded because it does not define these BSD-style errno constants (it uses
+// string errors), so the constants below would not compile there; Zero targets
+// linux/darwin/windows, so no Plan 9 variant is needed.
+var dialPreSendErrnos = []error{
+	syscall.ECONNREFUSED,
+	syscall.ENETUNREACH,
+	syscall.EHOSTUNREACH,
+	// A connect timeout is normally caught by the Timeout() check on the connect
+	// gate; this covers the case where the errno survives but the timeout flag
+	// does not, e.g. an error rebuilt from the errno alone.
+	syscall.ETIMEDOUT,
+}
+
+// isConnResetErrno reports whether err carries a connection-reset errno, the
+// post-send exclusion in isPreSendTransportError. It lives here (per platform)
+// so retry.go references no syscall constants and stays buildable on Plan 9,
+// which defines none of them.
+func isConnResetErrno(err error) bool {
+	return errors.Is(err, syscall.ECONNRESET)
+}
@@ -0,0 +1,15 @@
+//go:build plan9
+
+package providerio
+
+// Plan 9 has no BSD-style errno constants (it uses string errors), so the
+// errno-based classification is unavailable here: isConnResetErrno returns false
+// and dialPreSendErrnos is empty. retry.go still classifies via its string
+// markers on this platform, the pre-send inclusions (connection refused /
+// network unreachable / no route to host) and the separate post-send
+// "connection reset" exclusion each keep working through the wording checks.
+// Zero targets linux/darwin/windows, so this variant only keeps the package
+// building on Plan 9 rather than adding real support.
+var dialPreSendErrnos = []error{}
+
+func isConnResetErrno(error) bool { return false }
@@ -0,0 +1,40 @@
+//go:build windows
+
+package providerio
+
+import (
+	"errors"
+	"syscall"
+
+	"golang.org/x/sys/windows"
+)
+
+// dialPreSendErrnos are the errnos a refused or unreachable DIAL raises on
+// Windows. A real Windows dial failure carries the raw Winsock error
+// (WSAECONNREFUSED = 10061, WSAENETUNREACH = 10051, WSAEHOSTUNREACH = 10065), and
+// errors.Is against the POSIX syscall.ECONNREFUSED returns FALSE there because
+// Go's Windows syscall.ECONNREFUSED is a distinct value the net package never
+// produces. So the WSA codes must be matched explicitly, or a refused dial would
+// silently never be retried on Windows. The POSIX constants stay in the list too
+// so an error built with them (e.g. a test fixture) still classifies.
+var dialPreSendErrnos = []error{
+	syscall.ECONNREFUSED,
+	syscall.ENETUNREACH,
+	syscall.EHOSTUNREACH,
+	syscall.ETIMEDOUT,
+	windows.WSAECONNREFUSED,
+	windows.WSAENETUNREACH,
+	windows.WSAEHOSTUNREACH,
+	// Same reasoning as the POSIX ETIMEDOUT entry, with the Winsock code a real
+	// Windows connect timeout actually carries.
+	windows.WSAETIMEDOUT,
+}
+
+// isConnResetErrno reports whether err carries a connection-reset errno, the
+// post-send exclusion in isPreSendTransportError. It matches the same
+// syscall.ECONNRESET the shared path used before the errno classification was
+// split out per platform, so behavior on Windows is unchanged; it lives here
+// so retry.go references no syscall constants and stays buildable on Plan 9.
+func isConnResetErrno(err error) bool {
+	return errors.Is(err, syscall.ECONNRESET)
+}
@@ -1,15 +1,34 @@
+//go:build !plan9
+
 package providerio

 import (
 	"context"
 	"errors"
+	"io"
+	"net"
 	"net/http"
 	"net/http/httptest"
+	"os"
 	"sync/atomic"
+	"syscall"
 	"testing"
 	"time"
 )

+// wrapDialErrno builds the error shape a dial failure has (a *net.OpError
+// wrapping an *os.SyscallError wrapping the errno) so errors.Is reaches the
+// errno exactly as in production. These fixtures use the POSIX syscall.Exxx
+// constants, which do NOT reproduce a real Windows dial: that carries distinct
+// windows.WSA* errnos (Go's syscall.ECONNREFUSED is a value the net package
+// never produces on Windows). They still classify on Windows only because
+// dialPreSendErrnos there also lists the POSIX constants for exactly this
+// fixture reason; the real Windows dial branch is covered separately by
+// TestIsPreSendTransportErrorRealRefusedDial, which makes an actual refused dial.
+func wrapDialErrno(op string, errno syscall.Errno) error {
+	return &net.OpError{Op: op, Net: "tcp", Err: os.NewSyscallError("connectex", errno)}
+}
+
 type roundTripperFunc func(*http.Request) (*http.Response, error)

 func (f roundTripperFunc) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }
@@ -35,6 +54,152 @@ func TestSendWithRetryDoesNotReplayTransportErrors(t *testing.T) {
 	}
 }

+// A PROVABLY pre-send transport failure (no request bytes left this host) is
+// safe to replay and must be retried, bounded by preSendMaxAttempts (its own
+// short schedule), unlike an ambiguous post-send failure. Real dial failures
+// arrive as an Op=="dial" *net.OpError, so the errno cases are the production
+// shape on every platform (Windows included); the string case exercises the
+// wording fallback for a dial error already flattened past its errno.
+func TestSendWithRetryReplaysProvablyPreSendErrors(t *testing.T) {
+	shrinkBackoff(t)
+	cases := map[string]error{
+		"errno refused (dial)":      wrapDialErrno("dial", syscall.ECONNREFUSED),
+		"errno network unreachable": wrapDialErrno("dial", syscall.ENETUNREACH),
+		"errno host unreachable":    wrapDialErrno("dial", syscall.EHOSTUNREACH),
+		"dial string fallback":      &net.OpError{Op: "dial", Net: "tcp", Err: errors.New("connect: connection refused")},
+		"tls handshake timeout":     errors.New("net/http: TLS handshake timeout"),
+		"dns timeout":               &net.DNSError{Err: "server misbehaving", Name: "nope.invalid", IsTimeout: true},
+	}
+	for name, transportErr := range cases {
+		t.Run(name, func(t *testing.T) {
+			var calls int32
+			client := &http.Client{Transport: roundTripperFunc(func(*http.Request) (*http.Response, error) {
+				atomic.AddInt32(&calls, 1)
+				return nil, transportErr
+			})}
+			// maxAttempts=6 (the default) proves the pre-send path is bounded by
+			// preSendMaxAttempts, not the caller's 429-tuned maxAttempts.
+			resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "http://example.invalid", []byte("{}"), nil, 6)
+			if resp != nil {
+				_ = resp.Body.Close()
+			}
+			if err == nil {
+				t.Fatal("expected the transport error to surface after retries are exhausted")
+			}
+			if got := atomic.LoadInt32(&calls); got != preSendMaxAttempts {
+				t.Fatalf("pre-send error tried %d times, want %d (preSendMaxAttempts)", got, preSendMaxAttempts)
+			}
+		})
+	}
+}
+
+// An ambiguous transport failure that could have followed a sent request must
+// NOT be replayed: a non-idempotent completion POST could duplicate billable
+// work. This is the safety line the fix must not cross.
+func TestSendWithRetryDoesNotReplayAmbiguousTransportErrors(t *testing.T) {
+	for name, transportErr := range map[string]error{
+		"generic i/o timeout": errors.New("dial tcp 1.2.3.4:443: i/o timeout"),
+		"broken pipe":         errors.New("write tcp: broken pipe"),
+		"unexpected eof":      io.ErrUnexpectedEOF,
+		// The pre-send errnos are also raised on an ESTABLISHED connection: a route
+		// dropping mid-generation surfaces on the pending read/write, which is
+		// post-send. Scoping to Op=="dial" must keep these from replaying the POST.
+		"host unreachable on read is post-send": wrapDialErrno("read", syscall.EHOSTUNREACH),
+		"net unreachable on write is post-send": wrapDialErrno("write", syscall.ENETUNREACH),
+		// NXDOMAIN is authoritative and deterministic, so retrying it would only
+		// stall the agent before failing anyway.
+		"dns nxdomain": &net.DNSError{Err: "no such host", Name: "nope.invalid", IsNotFound: true},
+	} {
+		t.Run(name, func(t *testing.T) {
+			var calls int32
+			client := &http.Client{Transport: roundTripperFunc(func(*http.Request) (*http.Response, error) {
+				atomic.AddInt32(&calls, 1)
+				return nil, transportErr
+			})}
+			resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "http://example.invalid", []byte("{}"), nil, 3)
+			if resp != nil {
+				_ = resp.Body.Close()
+			}
+			if err == nil {
+				t.Fatal("expected the transport error to surface")
+			}
+			if got := atomic.LoadInt32(&calls); got != 1 {
+				t.Fatalf("ambiguous transport error replayed %d times, want 1 (no retry)", got)
+			}
+		})
+	}
+}
+
+// A REAL refused dial (nothing listening on the target) must classify as
+// pre-send on every platform. This is the regression the errno-constant fixtures
+// miss: on Windows the kernel raises WSAECONNREFUSED, which errors.Is does NOT
+// match against syscall.ECONNREFUSED, so before dialPreSendErrnos carried the WSA
+// codes a refused dial returned false here and Windows never retried it. Using a
+// real Dial exercises the platform's true error shape.
+func TestIsPreSendTransportErrorRealRefusedDial(t *testing.T) {
+	// Reserve an ephemeral port, then close it, so a dial there is refused.
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	addr := ln.Addr().String()
+	if cerr := ln.Close(); cerr != nil {
+		t.Fatalf("close listener: %v", cerr)
+	}
+	conn, dialErr := (&net.Dialer{Timeout: 2 * time.Second}).Dial("tcp", addr)
+	if dialErr == nil {
+		_ = conn.Close()
+		t.Skip("expected a refused dial but the port accepted a connection")
+	}
+	if !isPreSendTransportError(dialErr) {
+		t.Fatalf("real refused dial not classified pre-send: %v", dialErr)
+	}
+}
+
+func TestIsPreSendTransportError(t *testing.T) {
+	cases := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{"nil", nil, false},
+		// DNS: a lookup that could recover is pre-send; NXDOMAIN is permanent.
+		{"dns timeout", &net.DNSError{Err: "server misbehaving", Name: "x.invalid", IsTimeout: true}, true},
+		{"dns temporary", &net.DNSError{Err: "server misbehaving", Name: "x.invalid", IsTemporary: true}, true},
+		{"dns nxdomain is permanent", &net.DNSError{Err: "no such host", Name: "x.invalid", IsNotFound: true}, false},
+		{"tls handshake timeout", errors.New("net/http: TLS handshake timeout"), true},
+		// Errno-wrapped DIAL failures: how a real refused/unreachable dial arrives
+		// on EVERY platform, including Windows where the wording differs entirely.
+		{"errno refused (dial)", wrapDialErrno("dial", syscall.ECONNREFUSED), true},
+		{"errno network unreachable (dial)", wrapDialErrno("dial", syscall.ENETUNREACH), true},
+		{"errno host unreachable (dial)", wrapDialErrno("dial", syscall.EHOSTUNREACH), true},
+		{"dial operror string fallback", &net.OpError{Op: "dial", Net: "tcp", Err: errors.New("connect: connection refused")}, true},
+		// The SAME errnos raised on a post-send read/write are NOT pre-send — the
+		// kernel reports them on an established connection when a route drops.
+		{"host unreachable on read is post-send", wrapDialErrno("read", syscall.EHOSTUNREACH), false},
+		{"net unreachable on write is post-send", wrapDialErrno("write", syscall.ENETUNREACH), false},
+		{"errno reset is post-send", wrapDialErrno("read", syscall.ECONNRESET), false},
+		// A refused/unreachable error already flattened past its *net.OpError can't
+		// be proven pre-send, so it is NOT retried (conservative direction).
+		{"flattened refused, no opError", errors.New("dial tcp 127.0.0.1:1: connect: connection refused"), false},
+		{"connection reset", errors.New("read tcp: connection reset by peer"), false},
+		{"broken pipe", errors.New("write tcp: broken pipe"), false},
+		{"unexpected eof", io.ErrUnexpectedEOF, false},
+		{"eof", io.EOF, false},
+		{"generic io timeout", errors.New("dial tcp: i/o timeout"), false},
+		{"context deadline", context.DeadlineExceeded, false},
+		// Exclusion is checked before inclusion, even for a dial OpError: an "i/o
+		// timeout" in the message wins over the refused wording.
+		{"exclusion wins over inclusion", &net.OpError{Op: "dial", Net: "tcp", Err: errors.New("connection refused / i/o timeout")}, false},
+		{"unrelated", errors.New("some other error"), false},
+	}
+	for _, c := range cases {
+		if got := isPreSendTransportError(c.err); got != c.want {
+			t.Errorf("%s: isPreSendTransportError(%v) = %v, want %v", c.name, c.err, got, c.want)
+		}
+	}
+}
+
 func TestShouldRetryStatus(t *testing.T) {
 	cases := map[int]bool{
 		http.StatusOK:                  false,
@@ -94,12 +259,17 @@ func TestBackoffWaitsThenReturnsTrue(t *testing.T) {
 	}
 }

-// shrinkBackoff makes retry waits negligible for the duration of a test.
+// shrinkBackoff makes both retry schedules (429 and pre-send) negligible for the
+// duration of a test.
 func shrinkBackoff(t *testing.T) {
 	t.Helper()
-	saved := retryBackoffBase
+	savedRetry, savedPreSend := retryBackoffBase, preSendBackoffBase
 	retryBackoffBase = time.Millisecond
-	t.Cleanup(func() { retryBackoffBase = saved })
+	preSendBackoffBase = time.Millisecond
+	t.Cleanup(func() {
+		retryBackoffBase = savedRetry
+		preSendBackoffBase = savedPreSend
+	})
 }

 func TestBackoffWaitSchedule(t *testing.T) {
@@ -126,6 +296,30 @@ func TestBackoffWaitSchedule(t *testing.T) {
 	}
 }

+// The pre-send schedule is sub-second and doubles, far shorter than the 429
+// schedule: a permanent dial failure fails in ~1.5s across preSendMaxAttempts
+// (500ms + 1s) instead of stalling the agent ~60s on 2/4/8/16/30s. This is the
+// second half of the fix for a mistyped host / dead local daemon hanging a turn.
+func TestPreSendBackoffWaitSchedule(t *testing.T) {
+	cases := []struct {
+		attempt int
+		want    time.Duration
+	}{
+		{1, 500 * time.Millisecond},
+		{2, 1 * time.Second},
+		{3, 2 * time.Second},
+		// The exponent clamps at 5 (500ms<<5 = 16s) so a large attempt count can't
+		// overflow; in practice preSendMaxAttempts caps retries at attempt 2, so
+		// only the 500ms/1s rungs are ever reached.
+		{50, 16 * time.Second},
+	}
+	for _, c := range cases {
+		if got := preSendBackoffWait(c.attempt); got != c.want {
+			t.Errorf("preSendBackoffWait(%d) = %v, want %v", c.attempt, got, c.want)
+		}
+	}
+}
+
 func TestSendWithRetryRetriesThenSucceeds(t *testing.T) {
 	shrinkBackoff(t)
 	var hits int32
@@ -193,3 +387,316 @@ func TestSendWithRetryReturnsLastResponseAfterMaxAttempts(t *testing.T) {
 		t.Fatalf("server hit %d times, want 2 (maxAttempts)", got)
 	}
 }
+
+// Redirects are still followed, so a gateway that answers the completion endpoint
+// with a 307/308 keeps working: the caller gets the final response, not the 3xx.
+func TestSendWithRetryFollowsRedirects(t *testing.T) {
+	var calls int32
+	client := &http.Client{Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+		if atomic.AddInt32(&calls, 1) == 1 {
+			return &http.Response{
+				StatusCode: http.StatusTemporaryRedirect,
+				Header:     http.Header{"Location": {"https://redirect-target.invalid/v1"}},
+				Body:       http.NoBody,
+				Request:    r,
+			}, nil
+		}
+		return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody, Request: r}, nil
+	})}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://origin.invalid/v1", []byte("{}"), nil, 3)
+	if err != nil {
+		t.Fatalf("a redirected completion must succeed: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (the redirect should have been followed)", resp.StatusCode)
+	}
+	if got := atomic.LoadInt32(&calls); got != 2 {
+		t.Fatalf("transport called %d times, want 2 (origin then redirect target)", got)
+	}
+}
+
+// Once an attempt has entered a redirect, the original POST has already left this
+// host, so a dial failure on the redirect hop must NOT be replayed even though it
+// arrives as an Op=="dial" error that isPreSendTransportError would otherwise
+// treat as provably pre-send. Replaying it would re-bill a completion the first
+// host may already have processed.
+func TestSendWithRetryDoesNotReplayAfterRedirect(t *testing.T) {
+	shrinkBackoff(t)
+	var calls int32
+	client := &http.Client{Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+		if atomic.AddInt32(&calls, 1) == 1 {
+			return &http.Response{
+				StatusCode: http.StatusTemporaryRedirect,
+				Header:     http.Header{"Location": {"https://redirect-target.invalid/v1"}},
+				Body:       http.NoBody,
+				Request:    r,
+			}, nil
+		}
+		// The dial to the redirect target fails: pre-send in shape, but post-send
+		// in fact, because the origin already received the POST.
+		return nil, wrapDialErrno("dial", syscall.ECONNREFUSED)
+	})}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://origin.invalid/v1", []byte("{}"), nil, 6)
+	if resp != nil {
+		_ = resp.Body.Close()
+	}
+	if err == nil {
+		t.Fatal("expected the redirect-hop dial failure to surface as an error")
+	}
+	// Exactly two: the origin request and the single redirect hop. A third would
+	// mean the redirected POST was replayed.
+	if got := atomic.LoadInt32(&calls); got != 2 {
+		t.Fatalf("redirected POST was replayed: transport called %d times, want 2", got)
+	}
+}
+
+// A caller that supplies its own CheckRedirect keeps it: the retry path observes
+// redirects, it does not take the decision away from the caller.
+func TestSendWithRetryPreservesCallerRedirectPolicy(t *testing.T) {
+	var policyCalls int32
+	client := &http.Client{
+		CheckRedirect: func(*http.Request, []*http.Request) error {
+			atomic.AddInt32(&policyCalls, 1)
+			return http.ErrUseLastResponse
+		},
+		Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode: http.StatusTemporaryRedirect,
+				Header:     http.Header{"Location": {"https://redirect-target.invalid/v1"}},
+				Body:       http.NoBody,
+				Request:    r,
+			}, nil
+		}),
+	}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://origin.invalid/v1", []byte("{}"), nil, 3)
+	if err != nil {
+		t.Fatalf("caller policy asked to stop at the 3xx, so it must surface: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusTemporaryRedirect {
+		t.Fatalf("status = %d, want the 307 surfaced per the caller's policy", resp.StatusCode)
+	}
+	if got := atomic.LoadInt32(&policyCalls); got != 1 {
+		t.Fatalf("caller CheckRedirect called %d times, want 1 (it must not be discarded)", got)
+	}
+}
+
+// The pre-send retry budget is independent of the 429/503 status retries: two
+// rate-limit responses must not consume the pre-send allowance, so the first
+// refused dial after them still gets its own preSendMaxAttempts tries.
+func TestSendWithRetryPreSendBudgetSurvivesStatusRetries(t *testing.T) {
+	shrinkBackoff(t)
+	var calls int32
+	client := &http.Client{Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+		if atomic.AddInt32(&calls, 1) <= 2 {
+			return &http.Response{StatusCode: http.StatusTooManyRequests, Body: http.NoBody, Request: r}, nil
+		}
+		return nil, wrapDialErrno("dial", syscall.ECONNREFUSED)
+	})}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://x.invalid/v1", []byte("{}"), nil, 6)
+	if resp != nil {
+		_ = resp.Body.Close()
+	}
+	if err == nil {
+		t.Fatal("expected the exhausted pre-send failure to surface as an error")
+	}
+	// Two status responses (calls 1-2), then the pre-send failure gets its own
+	// budget: preSendMaxAttempts=3 means it retries twice more before returning.
+	if got := atomic.LoadInt32(&calls); got != 2+preSendMaxAttempts {
+		t.Fatalf("pre-send budget eaten by status retries: transport called %d times, want %d (2 status + %d pre-send)", got, 2+preSendMaxAttempts, preSendMaxAttempts)
+	}
+}
+
+// The inverse sequence: pre-send retries must not consume the 429/503 budget or
+// advance its backoff rung either. Two safely replayed refused dials followed by
+// rate limiting must still leave the status path its full maxAttempts window,
+// otherwise a couple of dial blips silently shorten every later rate-limit wait.
+func TestSendWithRetryStatusBudgetSurvivesPreSendRetries(t *testing.T) {
+	shrinkBackoff(t)
+	const maxAttempts = 3
+	var calls int32
+	client := &http.Client{Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+		if atomic.AddInt32(&calls, 1) <= 2 {
+			return nil, wrapDialErrno("dial", syscall.ECONNREFUSED)
+		}
+		return &http.Response{StatusCode: http.StatusTooManyRequests, Body: http.NoBody, Request: r}, nil
+	})}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://x.invalid/v1", []byte("{}"), nil, maxAttempts)
+	if err != nil {
+		t.Fatalf("exhausted status retries surface the response, not an error: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusTooManyRequests {
+		t.Fatalf("status = %d, want 429", resp.StatusCode)
+	}
+	// Calls 1-2 are the retried dial failures; the status path then gets its own
+	// full window (maxAttempts requests) before the 429 is surfaced.
+	if got := atomic.LoadInt32(&calls); got != 2+maxAttempts {
+		t.Fatalf("status budget eaten by pre-send retries: transport called %d times, want %d (2 pre-send + %d status)", got, 2+maxAttempts, maxAttempts)
+	}
+}
+
+// A redirect followed by a RETRYABLE STATUS is still retried, and deliberately
+// so. This is the case a reviewer flagged as a possible replay of billable work,
+// and the asymmetry with the transport-error guard above is intentional rather
+// than an oversight, so it is pinned here.
+//
+// The two situations differ in what is known about the request:
+//
+//   - Transport error after a redirect: the original POST reached the origin and
+//     the dial to the redirect target then failed, so whether the target received
+//     and began processing it is UNKNOWN. Replaying could duplicate work, which
+//     is why that path refuses to retry.
+//   - Retryable status after a redirect: every hop answered. A 307/308 is the
+//     origin declining to process and delegating, and a 429/503/529 is the target
+//     declining as well. Nothing accepted the request, so replaying duplicates
+//     nothing.
+//
+// The risk here is also exactly the risk of a 429 without any redirect, which
+// this package has always retried; the redirect adds no new ambiguity. Refusing
+// to retry would instead make a rate-limited completion behind a redirecting
+// gateway fail outright rather than back off.
+func TestSendWithRetryRetriesRedirectedRetryableStatus(t *testing.T) {
+	var calls int32
+	client := &http.Client{Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+		switch atomic.AddInt32(&calls, 1) {
+		case 1, 3:
+			// The origin declines and delegates, both times.
+			return &http.Response{
+				StatusCode: http.StatusTemporaryRedirect,
+				Header:     http.Header{"Location": {"https://redirect-target.invalid/v1"}},
+				Body:       http.NoBody,
+				Request:    r,
+			}, nil
+		case 2:
+			// The target declines too: rate limited, so nothing was accepted.
+			return &http.Response{StatusCode: http.StatusTooManyRequests, Body: http.NoBody, Request: r}, nil
+		default:
+			return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody, Request: r}, nil
+		}
+	})}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://origin.invalid/v1", []byte("{}"), nil, 3)
+	if err != nil {
+		t.Fatalf("a rate-limited completion behind a redirect must still retry: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200 after the retry succeeded", resp.StatusCode)
+	}
+	// origin, target(429), origin, target(200).
+	if got := atomic.LoadInt32(&calls); got != 4 {
+		t.Fatalf("transport called %d times, want 4 (redirect, 429, redirect, 200)", got)
+	}
+}
+
+// A CONNECT-phase timeout is provably pre-send: the connection was never
+// established, so no request bytes left this host. It reaches the classifier
+// carrying "i/o timeout", which the blanket wording exclusion rejects, so
+// admitting it depends on the connect gate running first.
+//
+// The post-send counterpart is the point of the table: a read timeout is also
+// Timeout(), and must stay excluded, or a reply that timed out mid-generation
+// would replay a completion the server already billed.
+func TestPreSendClassifiesConnectTimeouts(t *testing.T) {
+	timeoutErr := &timeoutError{}
+	for name, testCase := range map[string]struct {
+		err  error
+		want bool
+	}{
+		"dial timeout": {
+			err:  &net.OpError{Op: "dial", Net: "tcp", Err: timeoutErr},
+			want: true,
+		},
+		"proxy connect timeout": {
+			err:  &net.OpError{Op: "proxyconnect", Net: "tcp", Err: timeoutErr},
+			want: true,
+		},
+		"read timeout stays post-send": {
+			err:  &net.OpError{Op: "read", Net: "tcp", Err: timeoutErr},
+			want: false,
+		},
+		"write timeout stays post-send": {
+			err:  &net.OpError{Op: "write", Net: "tcp", Err: timeoutErr},
+			want: false,
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			if got := isPreSendTransportError(testCase.err); got != testCase.want {
+				t.Fatalf("isPreSendTransportError(%v) = %v, want %v", testCase.err, got, testCase.want)
+			}
+		})
+	}
+}
+
+// A failed CONNECT through an HTTP proxy is pre-send for the same structural
+// reason a refused dial is, but net tags it Op "proxyconnect", so a gate
+// matching only "dial" left every pre-send failure behind a corporate proxy
+// unretried.
+func TestPreSendClassifiesProxyConnectRefusal(t *testing.T) {
+	err := &net.OpError{Op: "proxyconnect", Net: "tcp", Err: syscall.ECONNREFUSED}
+	if !isPreSendTransportError(err) {
+		t.Fatal("a refused proxy CONNECT was not classified pre-send; no request bytes reached the model host")
+	}
+	// The op still has to be a connect phase. The same errno on an established
+	// connection is post-send and must not replay a POST.
+	post := &net.OpError{Op: "read", Net: "tcp", Err: syscall.ECONNREFUSED}
+	if isPreSendTransportError(post) {
+		t.Fatal("a read-phase error was classified pre-send")
+	}
+}
+
+// timeoutError is a net.Error whose Timeout() is true, matching the shape
+// net/http surfaces for a connect deadline.
+type timeoutError struct{}
+
+func (timeoutError) Error() string   { return "i/o timeout" }
+func (timeoutError) Timeout() bool   { return true }
+func (timeoutError) Temporary() bool { return true }
+
+// The pre-send budget bounds CONSECUTIVE connect failures, not the lifetime of
+// the call. Without a reset on a successful hop, an early run of dial blips
+// permanently spends the budget, so a later blip surfaces as a transport error
+// while the status budget still has room. That is the coupling the two counters
+// were split apart to remove, in the one ordering the earlier tests did not
+// cover: pre-send, then status, then pre-send again.
+func TestPreSendBudgetResetsAfterSuccessfulHop(t *testing.T) {
+	refused := &net.OpError{Op: "dial", Net: "tcp", Err: syscall.ECONNREFUSED}
+	var calls int32
+	client := &http.Client{Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+		switch atomic.AddInt32(&calls, 1) {
+		case 1, 2:
+			// Two connect failures, spending the pre-send budget under the old
+			// lifetime accounting.
+			return nil, refused
+		case 3:
+			// A hop that reaches the server. It declines, so the request was not
+			// accepted and retrying stays safe.
+			return &http.Response{StatusCode: http.StatusTooManyRequests, Body: http.NoBody, Request: r}, nil
+		case 4:
+			// One more connect blip. With a lifetime cap this surfaces as an
+			// error; the call should still recover.
+			return nil, refused
+		default:
+			return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody, Request: r}, nil
+		}
+	})}
+
+	resp, err := SendWithRetry(context.Background(), client, http.MethodPost, "https://origin.invalid/v1", []byte("{}"), nil, 3)
+	if err != nil {
+		t.Fatalf("interleaved connect and status failures returned %v; the pre-send budget did not reset after the hop that reached the server", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+	if got := atomic.LoadInt32(&calls); got != 5 {
+		t.Fatalf("transport called %d times, want 5 (dial, dial, 429, dial, 200)", got)
+	}
+}
@@ -1,147 +0,0 @@
-// Package reasoning models how each provider's models expose reasoning-effort
-// control. Providers disagree on the concept — OpenAI uses a discrete effort
-// enum, Anthropic and Gemini 2.5 use a thinking-token budget, some models only
-// toggle thinking on/off — so a single flat effort string cannot describe them.
-//
-// Capability is the typed, per-model description of that control, sourced from a
-// community capability catalog (models.dev). It is the data the rest of Zero
-// consults to decide which reasoning tiers a model actually supports, replacing
-// model-name guessing. This package depends only on the standard library, so the
-// model registry and provider adapters can import it without a cycle.
-//
-// Source of truth: this catalog is intended to become the authoritative reasoning
-// -capability source. When it is wired into the live path, modelregistry's
-// name-pattern inference (reasoningEffortsForModelName) is demoted to a fallback
-// for models the catalog does not cover; the catalog wins where it has an entry.
-// This commit is additive groundwork — nothing consumes it yet — so there is no
-// behavioral divergence until that wiring lands.
-package reasoning
-
-import "strings"
-
-// ControlKind enumerates how a model exposes reasoning control. The values
-// mirror the models.dev reasoning_options[].type field.
-type ControlKind string
-
-const (
-	// ControlEffort is a discrete effort enum (OpenAI reasoning_effort, Gemini 3
-	// thinkingLevel, newer Claude output_config.effort).
-	ControlEffort ControlKind = "effort"
-	// ControlBudget is a thinking-token budget (Gemini 2.5 thinkingBudget, legacy
-	// Claude thinking.budget_tokens).
-	ControlBudget ControlKind = "budget_tokens"
-	// ControlToggle is an on/off thinking switch with no levels.
-	ControlToggle ControlKind = "toggle"
-)
-
-// Control is one reasoning control a model accepts. For an effort control,
-// Values lists the accepted tiers ordered weakest to strongest. For a budget
-// control, Min/Max bound the thinking-token budget; each is nil when the
-// provider does not bound that side, kept distinct from an explicit 0 (Gemini
-// uses min: 0 to mean "thinking can be disabled", which a plain int would lose).
-type Control struct {
-	Kind   ControlKind `json:"type"`
-	Values []string    `json:"values,omitempty"`
-	Min    *int        `json:"min,omitempty"`
-	Max    *int        `json:"max,omitempty"`
-}
-
-// clone returns a deep copy of the control so the embedded catalog cannot be
-// mutated through a returned Control's slice or budget pointers.
-func (ctrl Control) clone() Control {
-	out := Control{Kind: ctrl.Kind}
-	if ctrl.Values != nil {
-		out.Values = append([]string(nil), ctrl.Values...)
-	}
-	if ctrl.Min != nil {
-		min := *ctrl.Min
-		out.Min = &min
-	}
-	if ctrl.Max != nil {
-		max := *ctrl.Max
-		out.Max = &max
-	}
-	return out
-}
-
-// Capability is the reasoning capability of a single model: whether it reasons
-// at all, and through which controls. A model may carry more than one control
-// (e.g. a newer Claude model exposes both an effort enum and a token budget); a
-// reasoning model with no controls reasons but exposes no knob (always-on).
-type Capability struct {
-	Reasoning bool      `json:"reasoning"`
-	Controls  []Control `json:"reasoning_options,omitempty"`
-}
-
-// clone returns a deep copy of the capability, cloning each control, so a caller
-// cannot mutate the shared catalog through the returned value's slices.
-func (c Capability) clone() Capability {
-	out := Capability{Reasoning: c.Reasoning}
-	if c.Controls != nil {
-		out.Controls = make([]Control, len(c.Controls))
-		for i, ctrl := range c.Controls {
-			out.Controls[i] = ctrl.clone()
-		}
-	}
-	return out
-}
-
-// Supported reports whether the model performs any reasoning.
-func (c Capability) Supported() bool { return c.Reasoning }
-
-// EffortControl returns the model's effort control and whether it has one. The
-// returned Control is a deep copy, so a caller cannot mutate the shared catalog
-// through its Values slice.
-func (c Capability) EffortControl() (Control, bool) {
-	for _, ctrl := range c.Controls {
-		if ctrl.Kind == ControlEffort {
-			return ctrl.clone(), true
-		}
-	}
-	return Control{}, false
-}
-
-// EffortValues returns the ordered effort tiers the model accepts, or nil when
-// it has no effort control (a budget- or toggle-only model, or a non-reasoning
-// model).
-func (c Capability) EffortValues() []string {
-	if ctrl, ok := c.EffortControl(); ok {
-		return ctrl.Values
-	}
-	return nil
-}
-
-// SupportsEffort reports whether tier is one of the model's accepted effort
-// values (case-insensitive).
-func (c Capability) SupportsEffort(tier string) bool {
-	tier = strings.ToLower(strings.TrimSpace(tier))
-	for _, v := range c.EffortValues() {
-		if strings.ToLower(v) == tier {
-			return true
-		}
-	}
-	return false
-}
-
-// BudgetControl returns the model's token-budget control and whether it has one.
-// The returned Control is a deep copy: its Min/Max are independent pointers, so a
-// caller cannot mutate the shared catalog through them. Min/Max are nil when that
-// bound is unspecified (a real 0, e.g. Gemini's min: 0, is a non-nil pointer to 0).
-func (c Capability) BudgetControl() (Control, bool) {
-	for _, ctrl := range c.Controls {
-		if ctrl.Kind == ControlBudget {
-			return ctrl.clone(), true
-		}
-	}
-	return Control{}, false
-}
-
-// HasControl reports whether the model exposes a control of the given kind.
-func (c Capability) HasControl(kind ControlKind) bool {
-	for _, ctrl := range c.Controls {
-		if ctrl.Kind == kind {
-			return true
-		}
-	}
-	return false
-}
@@ -1,99 +0,0 @@
-package reasoning
-
-import (
-	_ "embed"
-	"encoding/json"
-	"fmt"
-	"strings"
-)
-
-// modelsdev_snapshot.json is a trimmed snapshot of https://models.dev/api.json:
-// for a set of first-party providers, each model's api id mapped to its
-// reasoning capability (the `reasoning` flag and `reasoning_options`). Routers
-// (OpenRouter/Azure/etc.) are intentionally excluded — they carry generic or
-// stale option lists, so a lookup resolves to the first-party provider instead.
-//
-// Provenance is recorded in the snapshot's `_source`/`_fetched` header fields.
-// To regenerate: fetch api.json, then for each provider in
-// {anthropic, openai, google, xai, groq, deepseek} keep `{reasoning,
-// reasoning_options}` per api id, and bump `_fetched`. Runtime auto-refresh is a
-// separate change.
-//
-//go:embed modelsdev_snapshot.json
-var snapshotBytes []byte
-
-// snapshotDoc is the on-disk shape of the embedded snapshot.
-type snapshotDoc struct {
-	Providers map[string]map[string]Capability `json:"providers"`
-}
-
-// Catalog is a reasoning-capability lookup keyed by provider slug and api model
-// id. It is read-only after construction.
-type Catalog struct {
-	byProvider map[string]map[string]Capability
-}
-
-// ParseCatalog builds a Catalog from a models.dev-style snapshot document.
-func ParseCatalog(data []byte) (Catalog, error) {
-	var doc snapshotDoc
-	if err := json.Unmarshal(data, &doc); err != nil {
-		return Catalog{}, fmt.Errorf("reasoning: parse catalog: %w", err)
-	}
-	if len(doc.Providers) == 0 {
-		return Catalog{}, fmt.Errorf("reasoning: catalog has no providers")
-	}
-	return Catalog{byProvider: doc.Providers}, nil
-}
-
-// embedded is the catalog parsed from the bundled snapshot. A malformed embed is
-// a build/release error, so it panics at init rather than failing silently.
-var embedded = mustParseEmbedded()
-
-func mustParseEmbedded() Catalog {
-	c, err := ParseCatalog(snapshotBytes)
-	if err != nil {
-		panic("reasoning: invalid embedded snapshot: " + err.Error())
-	}
-	return c
-}
-
-// Embedded returns the catalog parsed from the bundled models.dev snapshot.
-func Embedded() Catalog { return embedded }
-
-// Lookup returns the reasoning capability for a model identified by its Zero
-// provider kind and the API model id — the provider's wire name (e.g.
-// "claude-opus-4-1-20250805"), NOT the friendly registry id ("claude-opus-4.1").
-// The match is exact: the api model id is only trimmed, not case-folded, and no
-// router prefixes ("openai/…") or suffixes (":cloud") are stripped. ok is false
-// when the provider or model is not in the snapshot, in which case the caller
-// falls back to its next capability source.
-func (c Catalog) Lookup(provider, apiModel string) (Capability, bool) {
-	apiModel = strings.TrimSpace(apiModel)
-	if apiModel == "" {
-		return Capability{}, false
-	}
-	for _, slug := range providerSlugs(provider) {
-		models, ok := c.byProvider[slug]
-		if !ok {
-			continue
-		}
-		if entry, ok := models[apiModel]; ok {
-			// Deep copy so callers cannot mutate the shared catalog through the
-			// returned Controls / Values slices or budget pointers.
-			return entry.clone(), true
-		}
-	}
-	return Capability{}, false
-}
-
-// providerSlugs maps a Zero provider kind to the models.dev provider slug to
-// look up. Gemini and Google both resolve to "google" (AI Studio), the
-// first-party source for Gemini models.
-func providerSlugs(provider string) []string {
-	switch strings.ToLower(strings.TrimSpace(provider)) {
-	case "gemini":
-		return []string{"google"}
-	default:
-		return []string{strings.ToLower(strings.TrimSpace(provider))}
-	}
-}
@@ -1,249 +0,0 @@
-package reasoning
-
-import "testing"
-
-func TestEmbeddedCatalogLoads(t *testing.T) {
-	c := Embedded()
-	if len(c.byProvider) == 0 {
-		t.Fatal("embedded catalog is empty")
-	}
-	if _, ok := c.Lookup("openai", "gpt-5"); !ok {
-		t.Fatal("embedded catalog missing a well-known model (gpt-5)")
-	}
-}
-
-func TestParseCatalogRejectsEmpty(t *testing.T) {
-	if _, err := ParseCatalog([]byte(`{}`)); err == nil {
-		t.Fatal("expected an error for a catalog with no providers")
-	}
-	if _, err := ParseCatalog([]byte(`not json`)); err == nil {
-		t.Fatal("expected an error for malformed json")
-	}
-}
-
-func TestGroundTruthOpenAI(t *testing.T) {
-	c := Embedded()
-	cases := []struct {
-		api    string
-		reason bool
-		kind   ControlKind
-		values []string
-	}{
-		{"gpt-5", true, ControlEffort, []string{"minimal", "low", "medium", "high"}},
-		{"gpt-5-codex", true, ControlEffort, []string{"low", "medium", "high"}},
-		{"gpt-5-pro", true, ControlEffort, []string{"high"}},
-		{"gpt-5.1", true, ControlEffort, []string{"none", "low", "medium", "high"}},
-		{"gpt-5.1-codex-max", true, ControlEffort, []string{"low", "medium", "high", "xhigh"}},
-		{"o3", true, ControlEffort, []string{"low", "medium", "high"}},
-	}
-	for _, tc := range cases {
-		entry, ok := c.Lookup("openai", tc.api)
-		if !ok {
-			t.Errorf("%s: not found", tc.api)
-			continue
-		}
-		if entry.Supported() != tc.reason {
-			t.Errorf("%s: Supported=%v want %v", tc.api, entry.Supported(), tc.reason)
-		}
-		if !equalStrings(entry.EffortValues(), tc.values) {
-			t.Errorf("%s: efforts=%v want %v", tc.api, entry.EffortValues(), tc.values)
-		}
-	}
-
-	// Non-reasoning models report reasoning:false and expose no effort.
-	for _, api := range []string{"gpt-4o", "gpt-4o-mini", "gpt-4.1", "gpt-4-turbo"} {
-		entry, ok := c.Lookup("openai", api)
-		if !ok {
-			t.Errorf("%s: not found", api)
-			continue
-		}
-		if entry.Supported() {
-			t.Errorf("%s: Supported=true, want false (non-reasoning)", api)
-		}
-		if entry.EffortValues() != nil {
-			t.Errorf("%s: efforts=%v, want nil", api, entry.EffortValues())
-		}
-	}
-
-	// Version splits: minimal vs none are not interchangeable.
-	gpt5, _ := c.Lookup("openai", "gpt-5")
-	if !gpt5.SupportsEffort("minimal") || gpt5.SupportsEffort("none") {
-		t.Error("gpt-5 should support minimal, not none")
-	}
-	gpt51, _ := c.Lookup("openai", "gpt-5.1")
-	if gpt51.SupportsEffort("minimal") || !gpt51.SupportsEffort("none") {
-		t.Error("gpt-5.1 should support none, not minimal")
-	}
-}
-
-func TestGroundTruthAnthropic(t *testing.T) {
-	c := Embedded()
-
-	// Legacy / budget-only models: a thinking-token budget, no effort enum. The
-	// budget carries an explicit min (1024) and no max — Max stays nil.
-	for _, api := range []string{
-		"claude-opus-4-1-20250805", "claude-sonnet-4-5-20250929", "claude-haiku-4-5-20251001",
-	} {
-		entry, ok := c.Lookup("anthropic", api)
-		if !ok {
-			t.Errorf("%s: not found", api)
-			continue
-		}
-		ctrl, ok := entry.BudgetControl()
-		if !ok {
-			t.Errorf("%s: expected a budget control", api)
-			continue
-		}
-		if ctrl.Min == nil || *ctrl.Min != 1024 {
-			t.Errorf("%s: budget Min=%v, want non-nil 1024", api, ctrl.Min)
-		}
-		if ctrl.Max != nil {
-			t.Errorf("%s: budget Max=%d, want nil (unbounded)", api, *ctrl.Max)
-		}
-		if _, ok := entry.EffortControl(); ok {
-			t.Errorf("%s: did not expect an effort control", api)
-		}
-	}
-
-	// Newer models: native effort enum with xhigh and the budget control removed.
-	opus48, ok := c.Lookup("anthropic", "claude-opus-4-8")
-	if !ok {
-		t.Fatal("claude-opus-4-8 not found")
-	}
-	if !equalStrings(opus48.EffortValues(), []string{"low", "medium", "high", "xhigh", "max"}) {
-		t.Errorf("opus-4-8 efforts=%v", opus48.EffortValues())
-	}
-	if _, ok := opus48.BudgetControl(); ok {
-		t.Error("opus-4-8 should not carry a budget control (removed)")
-	}
-}
-
-func TestGroundTruthGemini(t *testing.T) {
-	c := Embedded()
-
-	pro, ok := c.Lookup("gemini", "gemini-2.5-pro") // gemini kind -> google slug
-	if !ok {
-		t.Fatal("gemini-2.5-pro not found via the gemini provider kind")
-	}
-	ctrl, ok := pro.BudgetControl()
-	if !ok || ctrl.Min == nil || *ctrl.Min != 128 || ctrl.Max == nil || *ctrl.Max != 32768 {
-		t.Errorf("gemini-2.5-pro budget=%+v ok=%v, want min=128 max=32768", ctrl, ok)
-	}
-	if _, ok := pro.EffortControl(); ok {
-		t.Error("gemini-2.5-pro should be budget-only, no effort control")
-	}
-
-	// gemini-2.5-flash can disable thinking: a toggle plus a budget whose explicit
-	// min: 0 must survive (a plain int + omitempty would drop it).
-	flash, _ := c.Lookup("google", "gemini-2.5-flash")
-	if !flash.HasControl(ControlToggle) {
-		t.Error("gemini-2.5-flash should expose a toggle (thinking can be disabled)")
-	}
-	if fctrl, ok := flash.BudgetControl(); !ok || fctrl.Min == nil || *fctrl.Min != 0 {
-		t.Errorf("gemini-2.5-flash budget Min=%v, want a non-nil pointer to 0", fctrl.Min)
-	}
-
-	// Gemini 3.x switched to an effort enum.
-	if g3, ok := c.Lookup("google", "gemini-3-pro-preview"); ok {
-		if _, ok := g3.EffortControl(); !ok {
-			t.Error("gemini-3-pro-preview should expose an effort control")
-		}
-	}
-}
-
-// TestCoversZeroShippedReasoningModels pins that every reasoning model Zero
-// currently ships resolves in the catalog (by its api model id), so the
-// models.dev fallback actually covers Zero's catalog rather than just well-known
-// ids. The api ids mirror internal/modelregistry's curated entries.
-func TestCoversZeroShippedReasoningModels(t *testing.T) {
-	c := Embedded()
-	shipped := []struct {
-		provider, api string
-		wantKind      ControlKind
-	}{
-		{"anthropic", "claude-opus-4-1-20250805", ControlBudget},
-		{"anthropic", "claude-sonnet-4-5-20250929", ControlBudget},
-		{"anthropic", "claude-haiku-4-5-20251001", ControlBudget},
-		{"google", "gemini-2.5-pro", ControlBudget},
-		{"google", "gemini-2.5-flash", ControlToggle},
-		{"google", "gemini-2.5-flash-lite", ControlToggle},
-	}
-	for _, m := range shipped {
-		entry, ok := c.Lookup(m.provider, m.api)
-		if !ok {
-			t.Errorf("%s/%s: not covered by the snapshot", m.provider, m.api)
-			continue
-		}
-		if !entry.Supported() {
-			t.Errorf("%s/%s: Supported=false, want a reasoning model", m.provider, m.api)
-		}
-		if !entry.HasControl(m.wantKind) {
-			t.Errorf("%s/%s: missing expected control %q (controls=%+v)", m.provider, m.api, m.wantKind, entry.Controls)
-		}
-	}
-}
-
-// TestLookupReturnsDeepCopy pins that a caller cannot corrupt the shared
-// embedded catalog by mutating a returned Capability's slices.
-func TestLookupReturnsDeepCopy(t *testing.T) {
-	c := Embedded()
-	first, ok := c.Lookup("openai", "gpt-5")
-	if !ok || len(first.Controls) == 0 || len(first.Controls[0].Values) == 0 {
-		t.Fatal("setup: gpt-5 should have an effort control with values")
-	}
-	first.Controls[0].Values[0] = "MUTATED"
-	first.Controls[0].Kind = "MUTATED"
-
-	second, _ := c.Lookup("openai", "gpt-5")
-	if second.Controls[0].Values[0] == "MUTATED" || second.Controls[0].Kind == "MUTATED" {
-		t.Error("Lookup leaked a shared reference; a caller's mutation reached the catalog")
-	}
-}
-
-// TestAccessorsReturnDeepCopies pins that EffortControl/BudgetControl hand back
-// independent copies, so a caller holding a Capability that shares state with the
-// catalog cannot corrupt it by mutating an accessor result's slice or pointers.
-func TestAccessorsReturnDeepCopies(t *testing.T) {
-	min := 100
-	c := Capability{Reasoning: true, Controls: []Control{
-		{Kind: ControlEffort, Values: []string{"low", "high"}},
-		{Kind: ControlBudget, Min: &min},
-	}}
-
-	eff, _ := c.EffortControl()
-	eff.Values[0] = "MUTATED"
-	if c.Controls[0].Values[0] != "low" {
-		t.Error("EffortControl leaked the Values slice")
-	}
-
-	bud, _ := c.BudgetControl()
-	*bud.Min = 999
-	if *c.Controls[1].Min != 100 {
-		t.Error("BudgetControl leaked the Min pointer")
-	}
-}
-
-func TestLookupMissFallsThrough(t *testing.T) {
-	c := Embedded()
-	if _, ok := c.Lookup("openai", "totally-made-up-model"); ok {
-		t.Error("unknown model should miss")
-	}
-	if _, ok := c.Lookup("no-such-provider", "gpt-5"); ok {
-		t.Error("unknown provider should miss")
-	}
-	if _, ok := c.Lookup("openai", "  "); ok {
-		t.Error("blank api model should miss")
-	}
-}
-
-func equalStrings(a, b []string) bool {
-	if len(a) != len(b) {
-		return false
-	}
-	for i := range a {
-		if a[i] != b[i] {
-			return false
-		}
-	}
-	return true
-}