feat(agent): finish the TextGenError migration across every path and consumer

Closes out the remaining gaps rather than deferring them, so this PR lands
complete. The unification previously stopped at the explain + non-streaming
GenerateText boundary; everything else fell through to the generic
"Failed to generate summary" branch with no classification and no remediation.

**Streaming path now classifies (the one with real user impact).**
TextGeneratorAdapter prefers streaming, so GenerateTextStreaming is the path
`explain --generate` actually takes for Claude — and nine of its ten failure
returns were plain fmt.Errorf. A stale key gave:

  claude stream failed: Invalid API key · Please run /login: exit status 2

and now gives:

  Claude authentication failed
    message: Invalid API key · Please run /login
    try:     run `claude login` and retry

All ten returns route through a shared streamFailure() that applies the same
stderr classification as generate.go (HTTP status, then auth phrase) and
attaches evidence. cmd.Start failures classify as CLIMissing via
IsExecNotFoundErr, so a missing binary reads "not installed or not on PATH"
instead of a raw exec error.

**External agents return *TextGenError.** They are selectable summary
providers, so without this the type's own doc claim ("every summary provider")
was false and their failures missed errors.As entirely.

**Pi is wired and covered.** PiAgent gained a CommandRunner field, so pi joins
TestGenerateText_Matrix — it previously had zero coverage of any failure kind.
Separately, pi/models.go no longer routes --list-models through
HandleTextGenResult: that builds the summary error surface, so a model-listing
failure could render as "Pi failed to generate the summary".

**Registry gaps now fail a test instead of degrading silently.**
TestSummaryProviderTablesAreComplete enumerates SummaryCapableAgents() (newly
exported) and asserts displayNameFor, syntheticFallback and
summaryProviderBinaries cover all six. Forgetting one previously shipped a raw
registry key in the label ("copilot-cli authentication failed"), a missing try
row, or an agent silently absent from the picker — none of which failed
anything. Also dropped //nolint:exhaustive from kindPrefix so a sixth Kind
fails lint where it has to be handled.

**Classifier completed.** ClassifyStderrHTTPStatus now maps every 4xx (matching
classifyEnvelopeFields' >=400 && <500 arm — 413/422 previously fell to Unknown
on one path and Config on the other), treats 402 as rate-limit rather than
config since credit exhaustion is a "wait or top up" problem, and matches the
parenthesized form ("Unauthorized (401)", "rate limit exceeded (429)").

Precedence changed from positional to specificity: Auth > RateLimit > Config.
Completing the 4xx mapping made "first recognized wins" degenerate to "first
wins", which let a leading 413 mask a later 401 — my own regression test caught
it. Auth and RateLimit carry specific remediations; Config is the catch-all, so
the actionable kind should win wherever it appears.

**Privacy.** manual_commit_condensation.go logged err.Error() verbatim, and
Message can be provider stdout — the model's prose summary of the user's
transcript — since stdout is the fallback for stdout-primary CLIs. Now logs
kind/provider/api_status/exit_code/message_len instead. CLAUDE.md forbids
logging user content.

**Hygiene:** removed the unreachable double-parse branch in GenerateText (the
only failure return not wrapped in withEvidence), and dropped a vacuous
errors.Is(err, context.Canceled) assertion in the streaming test that used
context.Background() and could never fire.

Verified: 8572 unit tests, 448 integration tests, lint 0 issues on a cleaned
cache.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: peyton-alt

cmd/entire/cli/agent/claudecode/generate.go

@@ -271,14 +271,20 @@ func (c *ClaudeCodeAgent) GenerateText(ctx context.Context, prompt string, model
 			Message:  "claude CLI returned empty output",
 		})
 	}
+	// classifyClaudeEnvelope already parsed these same bytes successfully — with
+	// runErr == nil it returns non-nil on any parse failure, so reaching here
+	// means the parse succeeded. The previous defensive branch here was
+	// unreachable and was the only failure return in this function not wrapped
+	// in withEvidence; parseGenerateTextResponse is pure, so the second call
+	// cannot disagree with the first.
 	result, _, parseErr := parseGenerateTextResponse(res.Stdout)
 	if parseErr != nil {
-		return "", &agent.TextGenError{
+		return "", withEvidence(&agent.TextGenError{
 			Kind:     agent.TextGenErrorUnknown,
 			Provider: agent.AgentNameClaudeCode,
-			Message:  fmt.Sprintf("unexpected parse failure on success path: %v", parseErr),
+			Message:  agent.TruncateStderr(fmt.Sprintf("failed to parse claude CLI response: %v", parseErr)),
 			Cause:    parseErr,
-		}
+		})
 	}
 	return result, nil
 }

cmd/entire/cli/agent/claudecode/generate_streaming.go

@@ -58,13 +58,24 @@ func (c *ClaudeCodeAgent) GenerateTextStreaming(
 
 	stdout, err := cmd.StdoutPipe()
 	if err != nil {
-		return "", fmt.Errorf("claude stream stdout pipe: %w", err)
+		return "", streamFailure("", 0, 0, err, fmt.Sprintf("claude stream stdout pipe: %v", err))
 	}
 	var stderr bytes.Buffer
 	cmd.Stderr = &stderr
 
 	if err := cmd.Start(); err != nil {
-		return "", fmt.Errorf("claude stream start: %w", err)
+		// A missing/unexecutable binary must classify as CLIMissing so the user
+		// gets "not installed or not on PATH" rather than a raw exec error.
+		if agent.IsExecNotFoundErr(err) {
+			return "", &agent.TextGenerationError{
+				Err: &agent.TextGenError{
+					Kind:     agent.TextGenErrorCLIMissing,
+					Provider: agent.AgentNameClaudeCode,
+					Cause:    err,
+				},
+			}
+		}
+		return "", streamFailure("", 0, 0, err, fmt.Sprintf("claude stream start: %v", err))
 	}
 
 	// Count stdout bytes so the timeout diagnostic can distinguish "provider
@@ -86,7 +97,11 @@ func (c *ClaudeCodeAgent) GenerateTextStreaming(
 
 	// Specific envelope error outranks a generic ctx-cancel message.
 	if final != nil && final.IsError {
-		return "", envelopeErrorMessage(final)
+		return "", &agent.TextGenerationError{
+			Err:         envelopeErrorMessage(final),
+			Stderr:      agent.TruncateStderr(stderr.String()),
+			StdoutBytes: counted.n,
+		}
 	}
 
 	if final != nil {
@@ -95,14 +110,11 @@ func (c *ClaudeCodeAgent) GenerateTextStreaming(
 		// result envelope and cmd.Wait). A non-context process failure — the
 		// CLI exiting non-zero on its own — remains authoritative.
 		if waitErr != nil && !isContextKill(ctx, waitErr) {
-			stderrStr := strings.TrimSpace(stderr.String())
-			if stderrStr != "" {
-				return "", fmt.Errorf("claude stream failed: %s: %w", stderrStr, waitErr)
-			}
-			return "", fmt.Errorf("claude stream failed: %w", waitErr)
+			return "", streamFailure(stderr.String(), counted.n, exitCodeOf(waitErr), waitErr,
+				fmt.Sprintf("claude stream failed: %v", waitErr))
 		}
 		if final.Result == nil {
-			return "", errors.New("claude returned empty result")
+			return "", streamFailure(stderr.String(), counted.n, 0, nil, "claude returned empty result")
 		}
 		if progress != nil {
 			progress(agent.GenerationProgress{
@@ -144,16 +156,61 @@ func (c *ClaudeCodeAgent) GenerateTextStreaming(
 				slog.String("stderr", strings.TrimSpace(stderrStr)))
 			return c.GenerateText(ctx, prompt, model)
 		}
-		if stderrStr != "" {
-			return "", fmt.Errorf("claude stream failed: %s: %w", strings.TrimSpace(stderrStr), waitErr)
-		}
-		return "", fmt.Errorf("claude stream failed: %w", waitErr)
+		return "", streamFailure(stderrStr, counted.n, exitCodeOf(waitErr), waitErr,
+			fmt.Sprintf("claude stream failed: %v", waitErr))
 	}
 
 	if parseErr != nil {
-		return "", fmt.Errorf("claude stream parse: %w", parseErr)
+		return "", streamFailure(stderr.String(), counted.n, 0, parseErr,
+			fmt.Sprintf("claude stream parse: %v", parseErr))
+	}
+	return "", streamFailure(stderr.String(), counted.n, 0, nil,
+		"claude exited without producing a result")
+}
+
+// streamFailure classifies a streaming failure the same way the non-streaming
+// path does — HTTP status on stderr, then Claude's auth-phrase fallback — and
+// attaches the captured evidence.
+//
+// Before this existed, nine of the ten failure returns in GenerateTextStreaming
+// were plain fmt.Errorf, so they reached the user through
+// formatCheckpointSummaryError's default branch as a raw Go error string with
+// no remediation row. That mattered more than it looked: TextGeneratorAdapter
+// prefers streaming, so this is the path `explain --generate` actually takes
+// for Claude. A stale key (claude exits 2, "Invalid API key" on stderr, no
+// envelope) got "claude stream failed: ... exit status 2" here while the
+// non-streaming fallback correctly said "Claude authentication failed".
+func streamFailure(stderrBuf string, stdoutBytes int, exitCode int, cause error, fallbackMsg string) error {
+	stderrStr := strings.TrimSpace(stderrBuf)
+	msg := stderrStr
+	if msg == "" {
+		msg = fallbackMsg
+	}
+	kind := agent.ClassifyStderrHTTPStatus(stderrStr)
+	if kind == agent.TextGenErrorUnknown && containsAuthPhrase(stderrStr) {
+		kind = agent.TextGenErrorAuth
+	}
+	return &agent.TextGenerationError{
+		Err: &agent.TextGenError{
+			Kind:     kind,
+			Provider: agent.AgentNameClaudeCode,
+			Message:  agent.TruncateStderr(msg),
+			ExitCode: exitCode,
+			Cause:    cause,
+		},
+		Stderr:      agent.TruncateStderr(stderrBuf),
+		StdoutBytes: stdoutBytes,
+	}
+}
+
+// exitCodeOf returns the process exit code from err, or 0 when err is not an
+// *exec.ExitError (a launch failure produces no exit code).
+func exitCodeOf(err error) int {
+	var exitErr *exec.ExitError
+	if errors.As(err, &exitErr) {
+		return exitErr.ExitCode()
 	}
-	return "", errors.New("claude exited without producing a result")
+	return 0
 }
 
 // envelopeErrorMessage formats an is_error result envelope as a typed

cmd/entire/cli/agent/claudecode/generate_streaming_test.go

@@ -182,9 +182,6 @@ func TestGenerateTextStreaming_EnvelopeErrorSurfaced(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error from is_error envelope")
 	}
-	if errors.Is(err, context.Canceled) {
-		t.Errorf("expected envelope error, got Canceled")
-	}
 	// Streaming envelope errors must surface as a typed *agent.TextGenError so
 	// the explain layer's renderTextGenError can route on Kind
 	// (auth/rate-limit/config) instead of substring-matching err.Error().
@@ -345,3 +342,51 @@ func equalPhases(a, b []agent.ProgressPhase) bool {
 	}
 	return true
 }
+
+// TestGenerateTextStreaming_ClassifiesStderrFailures pins that the streaming
+// path classifies envelope-less failures the same way GenerateText does.
+//
+// This is the path `explain --generate` actually takes for Claude
+// (TextGeneratorAdapter prefers streaming), and until now nine of its ten
+// failure returns were plain fmt.Errorf. A stale key produced
+// "claude stream failed: Invalid API key ... exit status 2" with no
+// remediation, while the non-streaming fallback correctly said
+// "Claude authentication failed".
+func TestGenerateTextStreaming_ClassifiesStderrFailures(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name     string
+		stderr   string
+		wantKind agent.TextGenErrorKind
+	}{
+		{"auth phrase", "Invalid API key · Please run /login", agent.TextGenErrorAuth},
+		{"http 401", "ERROR: 401 Unauthorized", agent.TextGenErrorAuth},
+		{"http 429", "ERROR: 429 Too Many Requests", agent.TextGenErrorRateLimit},
+		{"http 404", "ERROR: 404 Not Found", agent.TextGenErrorConfig},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			ag := &ClaudeCodeAgent{CommandRunner: testutil.FakeStreamCmd("", tc.stderr, 2)}
+			_, err := ag.GenerateTextStreaming(context.Background(), "test", "haiku", nil)
+			if err == nil {
+				t.Fatal("expected an error")
+			}
+			var tge *agent.TextGenError
+			if !errors.As(err, &tge) {
+				t.Fatalf("errors.As(*TextGenError) failed: %T %v", err, err)
+			}
+			if tge.Kind != tc.wantKind {
+				t.Errorf("Kind = %q; want %q", tge.Kind, tc.wantKind)
+			}
+			if tge.Provider != agent.AgentNameClaudeCode {
+				t.Errorf("Provider = %q; want claude-code", tge.Provider)
+			}
+			// Evidence must ride along too, same as every other failure site.
+			var failure *agent.TextGenerationError
+			if !errors.As(err, &failure) {
+				t.Errorf("errors.As(*TextGenerationError) failed — evidence lost: %T", err)
+			}
+		})
+	}
+}

cmd/entire/cli/agent/external/external.go

@@ -374,14 +374,40 @@ func (e *Agent) CalculateTokenUsage(transcriptData []byte, fromOffset int) (*age
 
 // --- TextGenerator methods ---
 
+// GenerateText implements agent.TextGenerator for external plugins.
+//
+// Failures return *agent.TextGenError like every built-in provider. External
+// agents are selectable summary providers, so without this the explain layer's
+// errors.As would miss them and they would fall through to the generic
+// "Failed to generate summary" branch with no classification and no
+// remediation row — and agent.TextGenError's own doc claim ("every summary
+// provider") would be false.
+//
+// Provider is the plugin's dynamic name, so it cannot appear in the
+// compile-time display/remediation tables; displayNameFor falls back to the
+// registry key, which is the right answer for a third-party plugin.
 func (e *Agent) GenerateText(ctx context.Context, prompt string, model string) (string, error) {
 	stdout, err := e.run(ctx, []byte(prompt), "generate-text", "--model", model)
 	if err != nil {
-		return "", fmt.Errorf("generate-text: %w", err)
+		kind := agent.TextGenErrorUnknown
+		if agent.IsExecNotFoundErr(err) {
+			kind = agent.TextGenErrorCLIMissing
+		}
+		return "", &agent.TextGenError{
+			Kind:     kind,
+			Provider: e.Name(),
+			Message:  agent.TruncateStderr(err.Error()),
+			Cause:    err,
+		}
 	}
 	var resp GenerateTextResponse
 	if err := json.Unmarshal(stdout, &resp); err != nil {
-		return "", fmt.Errorf("generate-text: invalid JSON: %w", err)
+		return "", &agent.TextGenError{
+			Kind:     agent.TextGenErrorUnknown,
+			Provider: e.Name(),
+			Message:  agent.TruncateStderr(fmt.Sprintf("invalid JSON from generate-text: %v", err)),
+			Cause:    err,
+		}
 	}
 	return resp.Text, nil
 }

cmd/entire/cli/agent/generate_matrix_test.go

@@ -14,6 +14,7 @@ import (
 	"github.com/entireio/cli/cmd/entire/cli/agent/copilotcli"
 	"github.com/entireio/cli/cmd/entire/cli/agent/cursor"
 	"github.com/entireio/cli/cmd/entire/cli/agent/geminicli"
+	"github.com/entireio/cli/cmd/entire/cli/agent/pi"
 	"github.com/entireio/cli/cmd/entire/cli/agent/types"
 )
 
@@ -27,9 +28,8 @@ const windowsOSTest = "windows"
 // Gemini's provider-specific phrase heuristic is covered separately in
 // geminicli/ since it is the only agent with an extraClassify hook.
 //
-// Pi is absent: PiAgent has no CommandRunner field and hardcodes nil in
-// RunIsolatedTextGeneratorCLIRaw, so its subprocess cannot be stubbed. Adding
-// that field would let pi join this table.
+// All five non-Claude summary providers are covered, pi included since it
+// gained a CommandRunner field.
 func TestGenerateText_Matrix(t *testing.T) {
 	t.Parallel()
 	if runtime.GOOS == windowsOSTest {
@@ -59,6 +59,9 @@ func TestGenerateText_Matrix(t *testing.T) {
 		{"geminicli", agent.AgentNameGemini, "gemini CLI returned empty output", func(r agent.TextCommandRunner) textGenerator {
 			return &geminicli.GeminiCLIAgent{CommandRunner: r}
 		}},
+		{"pi", agent.AgentNamePi, "pi CLI returned empty output", func(r agent.TextCommandRunner) textGenerator {
+			return &pi.PiAgent{CommandRunner: r}
+		}},
 	}
 
 	// assertComposition pins the contract the #964/#1005 reconciliation created:

cmd/entire/cli/agent/pi/generate.go

@@ -20,6 +20,6 @@ func (a *PiAgent) GenerateText(ctx context.Context, prompt string, model string)
 	}
 	args = append(args, prompt)
 
-	res, runErr := agent.RunIsolatedTextGeneratorCLIRaw(ctx, nil, "pi", args, "")
+	res, runErr := agent.RunIsolatedTextGeneratorCLIRaw(ctx, a.CommandRunner, "pi", args, "")
 	return agent.HandleTextGenResult(res, runErr, agent.AgentNamePi, "pi CLI returned empty output", nil) //nolint:wrapcheck // return unwrapped: the explain layer renders label+message from the typed error, so a wrap prefix would leak into user output. errors.As (*TextGenError) / errors.Is (ctx sentinel) must reach it unflattened.
 }

cmd/entire/cli/agent/pi/models.go

@@ -3,6 +3,7 @@ package pi
 import (
 	"bufio"
 	"context"
+	"errors"
 	"fmt"
 	"strings"
 
@@ -16,10 +17,24 @@ var _ agent.ModelLister = (*PiAgent)(nil)
 // Pi has a real enumeration command spanning every configured provider, so the
 // result reflects what this machine/account can actually use.
 func (a *PiAgent) ListModels(ctx context.Context) ([]agent.ModelInfo, error) {
-	res, runErr := agent.RunIsolatedTextGeneratorCLIRaw(ctx, nil, "pi", []string{"--list-models"}, "")
-	out, err := agent.HandleTextGenResult(res, runErr, agent.AgentNamePi, "pi --list-models returned empty output", nil)
-	if err != nil {
-		return nil, fmt.Errorf("pi --list-models: %w", err)
+	// Deliberately NOT HandleTextGenResult: that helper builds the summary-path
+	// error surface, so a model-listing failure would render as "Pi failed to
+	// generate the summary" if it ever reached formatCheckpointSummaryError.
+	// Listing models is a different operation and gets a plain error.
+	res, runErr := agent.RunIsolatedTextGeneratorCLIRaw(ctx, a.CommandRunner, "pi", []string{"--list-models"}, "")
+	if runErr != nil {
+		detail := strings.TrimSpace(string(res.Stderr))
+		if detail == "" {
+			detail = strings.TrimSpace(string(res.Stdout))
+		}
+		if detail == "" {
+			detail = runErr.Error()
+		}
+		return nil, fmt.Errorf("pi --list-models: %s", agent.TruncateStderr(detail))
+	}
+	out := strings.TrimSpace(string(res.Stdout))
+	if out == "" {
+		return nil, errors.New("pi --list-models returned empty output")
 	}
 	return parsePiModelList(out), nil
 }

cmd/entire/cli/agent/pi/pi.go

@@ -43,7 +43,12 @@ func init() {
 // PiAgent implements agent.Agent for the pi coding agent.
 //
 //nolint:revive // PiAgent is clearer than Agent in this context
-type PiAgent struct{}
+type PiAgent struct {
+	// CommandRunner lets tests stub the pi subprocess. Nil means
+	// exec.CommandContext. Without this field pi could not join
+	// TestGenerateText_Matrix and its failure classification was unverified.
+	CommandRunner agent.TextCommandRunner
+}
 
 // NewPiAgent returns a new Pi agent instance.
 func NewPiAgent() agent.Agent {