@pi-in-go/pigpen-pi-typesafe-api 0.1.0

package/CREDITS.md

@@ -0,0 +1,14 @@
+# Credits
+
+This Package is a Go port of **pi-typesafe** 0.8.0, https://github.com/DevMortimer/pi-typesafe, by
+**Ryan Gapac** (MIT, Copyright (c) 2026 Ryan Gapac). It is an independent project, not affiliated with TypeSafe AI or
+the Pi authors, and so is this port.
+
+- Pinned commit: `ed439f834665ad6fc652787f5ba7c23852566d49` (release 0.8.0, "Add Command Code backend and caller-supplied endpoints")
+- The unmodified original, with its tests, is vendored in `components/pi-typesafe/port/oracle/`; its license is in `LICENSE`
+  of this Package and in `components/pi-typesafe/port/oracle/LICENSE`.
+- What is modified: everything. The behavior, wording and structure follow the original; the code is a Go
+  implementation over the shared TypeSafe client (`components/typesafe`, a port of the official `@typesafe-ai/sdk`).
+  The mapping from each original file to its Go file is in `components/pi-typesafe/port/PORT.md`, with every deliberate difference.
+
+The Go code, scenarios and tests were written for Pigpen by Michael Kinsy.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ryan Gapac
+Copyright (c) 2026 Michael Kinsy (the Go port)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# pi-typesafe-api (typed Go API)
+
+The library half of the [pi-typesafe](../pi-typesafe/README.md) port: what an extension author imports to ask Jev typed
+questions safely. Go module `github.com/MichaelKinsy/pigpen/components/pi-typesafe-api`, package `pitypesafe`, over the shared
+client `components/typesafe`. A consumer extension's `go.mod` requires it at `v0.0.0` (no `replace`) and its directory has a
+`go.work` with `use ( . ../../../pi-typesafe-api ../../../typesafe )`.
+
+```go
+client, err := pitypesafe.New(pitypesafe.Options{MaxRequests: 5, MaxUSDPerDay: 1}) // key: TYPESAFE_API_KEY, else the login store
+answer := pitypesafe.Ask(ctx, client, typesafe.SystemOneRequest{
+	State: typesafe.Text("I was charged twice."),
+	Questions: typesafe.Questions{typesafe.Ask("billing", typesafe.Noul("Is this about billing?"))},
+}, pitypesafe.AskOptions{Timeout: 5 * time.Second})
+if !answer.OK { /* answer.ErrorCode == pitypesafe.CodeBudget: stop asking; never an error value */ }
+```
+
+| Piece | Where |
+|---|---|
+| Admission (`PrepareEvaluationRequest`: normalize model near-misses, validate, byte budget), `EvaluationSchema` | `schema.go`, `evaluation_schema.json` |
+| Client with request budget, day caps, ledger, auth recording (`New`, `Evaluate`, `EvaluateRaw`, `ListModels`, `GetSpend`) | `client.go`, `usage.go`, `auth.go` |
+| Backends: `typesafe`, `openrouter`, `commandcode`, a caller-supplied endpoint, and `ownmodel` | `backends.go` |
+| Key store, key situations, `AgentDir` (PiG's directory) | `credentials.go` |
+| `Ask`, `EvaluateMany`, `EvaluateAll`, `ChunkRequest`, `FanOut` | `ask.go`, `batch.go` |
+| Calibration kit (`Calibrate`, `Replay`, `AUC`, ...) | `calibrate.go` |
+| Own model on the PiG SDK's model access | `hostmodel/` |
+| Hidden-input key prompt, `LoginWithPrompt`, `EnsureAPIKey` | `ui/` |
+
+**Where content goes.** TypeSafe, OpenRouter, Command Code and custom-endpoint backends send it to that host
+(`BackendHost` names it for consent text); the `ownmodel` backend sends it to the provider of the model PiG is configured with. A
+key for one backend is never sent to another. Credit and license: [CREDITS.md](CREDITS.md). Mapping: [port/PORT.md](port/PORT.md).

package/ask.go

@@ -0,0 +1,62 @@
+package pitypesafe
+
+import (
+	"context"
+	"time"
+
+	"github.com/MichaelKinsy/pigpen/components/typesafe/libraries/typesafe"
+)
+
+// Judge is anything with a client's Evaluate: the real client in a session, a stub in tests.
+type Judge interface {
+	Evaluate(ctx context.Context, request typesafe.SystemOneRequest) (*Evaluation, error)
+}
+
+// DefaultAskTimeout is the default per-ask deadline; it matches the client's own request timeout.
+const DefaultAskTimeout = 15 * time.Second
+
+const askFallbackMessage = "TypeSafe request failed."
+
+// AskOptions configure Ask.
+type AskOptions struct {
+	// Timeout is the per-ask deadline, merged with the caller's own context. Default: DefaultAskTimeout.
+	Timeout time.Duration
+}
+
+// AskAnswer is the outcome of Ask.
+type AskAnswer struct {
+	OK bool
+	// The fields below are set when OK.
+	Answers   map[string]typesafe.Answer
+	Order     []string
+	Model     string
+	Usage     typesafe.Usage
+	ElapsedMs int64
+	// Error and ErrorCode are set when not OK; ErrorCode is empty for a failure that is not an IntegrationError.
+	Error     string
+	ErrorCode ErrorCode
+}
+
+// Ask is one typed Jev request that never fails: a failure comes back as an AskAnswer with OK false, this
+// package's own message (which carries no upstream body, header, key, or submitted state) and its code, so a
+// caller can stop asking after a budget error. The per-ask timeout is merged into the caller's context, so
+// either can cancel the request.
+//
+// This is the author-facing "ask Jev" seam. Agents get the same admission through the typesafe_evaluate tool;
+// the two share PrepareEvaluationRequest, so what one accepts the other accepts.
+func Ask(ctx context.Context, judge Judge, request typesafe.SystemOneRequest, opts AskOptions) AskAnswer {
+	timeout := opts.Timeout
+	if timeout <= 0 {
+		timeout = DefaultAskTimeout
+	}
+	ctx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+	result, err := judge.Evaluate(ctx, request)
+	if err != nil {
+		if ie, ok := err.(*IntegrationError); ok {
+			return AskAnswer{Error: ie.Message, ErrorCode: ie.Code}
+		}
+		return AskAnswer{Error: askFallbackMessage}
+	}
+	return AskAnswer{OK: true, Answers: result.Answers, Order: result.Order, Model: result.Model, Usage: result.Usage, ElapsedMs: result.ElapsedMs}
+}

package/ask_test.go

@@ -0,0 +1,76 @@
+package pitypesafe
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"reflect"
+	"testing"
+	"time"
+
+	"github.com/MichaelKinsy/pigpen/components/typesafe/libraries/typesafe"
+)
+
+type judgeFunc func(ctx context.Context, r typesafe.SystemOneRequest) (*Evaluation, error)
+
+func (f judgeFunc) Evaluate(ctx context.Context, r typesafe.SystemOneRequest) (*Evaluation, error) {
+	return f(ctx, r)
+}
+
+func TestAsk(t *testing.T) {
+	tw(t, "ask", "a successful ask returns the typed answers, model, usage, and duration", func(t *testing.T) {
+		judge := judgeFunc(func(context.Context, typesafe.SystemOneRequest) (*Evaluation, error) {
+			return &Evaluation{SystemOneResult: &typesafe.SystemOneResult{Model: "jev-test", Answers: map[string]typesafe.Answer{"yes": typesafe.NoulAnswer{Noul: 0.9}}, Usage: typesafe.Usage{InputTokens: 12}}, ElapsedMs: 7, Order: []string{"yes"}}, nil
+		})
+		a := Ask(context.Background(), judge, sampleRequest(), AskOptions{})
+		yes, _ := a.Answers["yes"].(typesafe.NoulAnswer)
+		if !a.OK || yes.Noul != 0.9 || a.Model != "jev-test" || a.Usage.InputTokens != 12 || a.ElapsedMs != 7 {
+			t.Fatalf("answer = %+v", a)
+		}
+	})
+	tw(t, "ask", "a typed failure comes back as data, with pi-typesafe's own code and message", func(t *testing.T) {
+		fail := func(err error) Judge {
+			return judgeFunc(func(context.Context, typesafe.SystemOneRequest) (*Evaluation, error) { return nil, err })
+		}
+		budget := Ask(context.Background(), fail(newError(CodeBudget, "TypeSafe request limit reached (1 attempts per client instance).")), sampleRequest(), AskOptions{})
+		if !reflect.DeepEqual(budget, AskAnswer{Error: "TypeSafe request limit reached (1 attempts per client instance).", ErrorCode: CodeBudget}) {
+			t.Fatalf("budget = %+v", budget)
+		}
+		e := &IntegrationError{Code: CodeHTTP, Message: "TypeSafe returned HTTP 401. Check TYPESAFE_API_KEY. No automatic retry was made.", Status: 401}
+		if h := Ask(context.Background(), fail(e), sampleRequest(), AskOptions{}); h.OK || h.ErrorCode != CodeHTTP {
+			t.Fatalf("http = %+v", h)
+		}
+	})
+	tw(t, "ask", "an unknown failure is replaced by a fixed message so nothing from the transport escapes", func(t *testing.T) {
+		judge := judgeFunc(func(context.Context, typesafe.SystemOneRequest) (*Evaluation, error) {
+			return nil, errors.New("upstream body with a key: sk-secret")
+		})
+		a := Ask(context.Background(), judge, sampleRequest(), AskOptions{})
+		if !reflect.DeepEqual(a, AskAnswer{Error: "TypeSafe request failed."}) {
+			t.Fatalf("answer = %+v", a)
+		}
+		if data, _ := json.Marshal(a); contains(string(data), "sk-secret") {
+			t.Fatal("secret escaped")
+		}
+	})
+	tw(t, "ask", "the ask deadline and the caller's signal both cancel the request", func(t *testing.T) {
+		slow := judgeFunc(func(ctx context.Context, _ typesafe.SystemOneRequest) (*Evaluation, error) {
+			<-ctx.Done()
+			return nil, newError(CodeAborted, "TypeSafe request cancelled before submission.")
+		})
+		timedOut := Ask(context.Background(), slow, sampleRequest(), AskOptions{Timeout: 5 * time.Millisecond})
+		if !reflect.DeepEqual(timedOut, AskAnswer{Error: "TypeSafe request cancelled before submission.", ErrorCode: CodeAborted}) {
+			t.Fatalf("timed out = %+v", timedOut)
+		}
+		ctx, cancel := context.WithCancel(context.Background())
+		done := make(chan AskAnswer, 1)
+		go func() { done <- Ask(ctx, slow, sampleRequest(), AskOptions{Timeout: 5 * time.Second}) }()
+		cancel()
+		if a := <-done; a.OK {
+			t.Fatal("a cancelled ask must fail")
+		}
+		if DefaultAskTimeout != 15*time.Second {
+			t.Errorf("default = %v", DefaultAskTimeout)
+		}
+	})
+}

package/auth.go

@@ -0,0 +1,249 @@
+package pitypesafe
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+const authVersion = 1
+
+// AuthFailure is the last request that degraded TypeSafe, with no upstream body, header, key, or submitted state.
+type AuthFailure struct {
+	Code    ErrorCode `json:"code"`
+	Status  int       `json:"status,omitempty"`
+	Message string    `json:"message"`
+	At      string    `json:"at"`
+}
+
+// AuthState is the whole answer to "is Jev actually available right now": which key is in effect, whether it
+// has been accepted, and the last failure that degraded it. Consumers must consult it instead of treating their
+// own consent flag as proof that judgments will happen.
+type AuthState struct {
+	// Backend is the value the caller passed (nil means the default).
+	Backend any
+	Kind    KeyKind
+	Source  KeySource
+	// Path is where the key would be read from.
+	Path string
+	// Reason says why a stored key cannot be used.
+	Reason string
+	// KeyName is a short label for the key source: TYPESAFE_API_KEY, /typesafe login, no key, unusable key.
+	KeyName string
+	// Verified is true when the key in effect was accepted by the backend.
+	Verified   bool
+	VerifiedAt string
+	// LastFailure is cleared by the next successful request.
+	LastFailure *AuthFailure
+	// Usable means a key is present and the last authentication outcome was not a rejection. False means judgments are skipped.
+	Usable bool
+}
+
+// AuthOptions selects the state file and backend.
+type AuthOptions struct {
+	Path    string
+	Backend any
+}
+
+// AuthStatePath is the auth-state file: one small, owner-only record that outlives the process that wrote it.
+func AuthStatePath() string { return filepath.Join(TypeSafeDir(), "auth-state.json") }
+
+type storedAuth struct {
+	Version     int          `json:"version"`
+	VerifiedAt  string       `json:"verifiedAt,omitempty"`
+	LastFailure *AuthFailure `json:"lastFailure,omitempty"`
+}
+
+var errorCodes = map[ErrorCode]bool{CodeConfiguration: true, CodeValidation: true, CodeBudget: true, CodeAborted: true, CodeTimeout: true, CodeHTTP: true, CodeConnection: true, CodeResponse: true}
+
+func readAuthState(path string) storedAuth {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return storedAuth{}
+	}
+	var raw struct {
+		VerifiedAt  any `json:"verifiedAt"`
+		LastFailure *struct {
+			Code    any `json:"code"`
+			Status  any `json:"status"`
+			Message any `json:"message"`
+			At      any `json:"at"`
+		} `json:"lastFailure"`
+	}
+	if json.Unmarshal(data, &raw) != nil {
+		return storedAuth{}
+	}
+	var out storedAuth
+	if v, ok := raw.VerifiedAt.(string); ok && utf16Len(v) <= 40 {
+		out.VerifiedAt = v
+	}
+	if f := raw.LastFailure; f != nil {
+		code, _ := f.Code.(string)
+		message, _ := f.Message.(string)
+		at, _ := f.At.(string)
+		if errorCodes[ErrorCode(code)] && message != "" && at != "" && utf16Len(at) <= 40 {
+			failure := &AuthFailure{Code: ErrorCode(code), Message: truncateUTF16(message, 300), At: at}
+			if s, ok := f.Status.(float64); ok && s == float64(int(s)) {
+				failure.Status = int(s)
+			}
+			out.LastFailure = failure
+		}
+	}
+	return out
+}
+
+func truncateUTF16(s string, n int) string {
+	if utf16Len(s) <= n {
+		return s
+	}
+	count := 0
+	for i, r := range s {
+		w := 1
+		if r >= 0x10000 {
+			w = 2
+		}
+		if count+w > n {
+			return s[:i]
+		}
+		count += w
+	}
+	return s
+}
+
+// writeAuthState is owner-only, atomic, and best-effort: an unwritable auth record never changes how a request behaves.
+func writeAuthState(path string, state storedAuth) {
+	state.Version = authVersion
+	body, err := json.MarshalIndent(state, "", "  ")
+	if err != nil {
+		return
+	}
+	_ = writeOwnerOnly(path, append(body, '\n'))
+}
+
+func rejected(f *AuthFailure) bool {
+	return f != nil && f.Code == CodeHTTP && (f.Status == 401 || f.Status == 403)
+}
+
+// GetAuthState adds the key situation, the last outcome, and the clock up for a valid backend. An invalid
+// backend returns the same configuration error as ResolveBackend, so validate a user-supplied endpoint with
+// ResolveBackend first.
+func GetAuthState(opts AuthOptions) (AuthState, error) {
+	path := opts.Path
+	if path == "" {
+		path = AuthStatePath()
+	}
+	backend := opts.Backend
+	if backend == nil {
+		backend = DefaultBackend
+	}
+	situation, err := KeySituationFor(backend)
+	if err != nil {
+		return AuthState{}, err
+	}
+	stored := readAuthState(path)
+	var source KeySource
+	switch situation.Kind {
+	case KeyEnvironment:
+		source = SourceEnvironment
+	case KeyStored:
+		source = SourceStored
+	}
+	isRejected := rejected(stored.LastFailure)
+	present := source != "" || situation.Kind == KeyNotRequired
+	state := AuthState{
+		Backend:     backend,
+		Kind:        situation.Kind,
+		Source:      source,
+		Path:        CredentialsPath(),
+		KeyName:     KeySourceLabel(situation),
+		Verified:    stored.VerifiedAt != "" && !isRejected,
+		VerifiedAt:  stored.VerifiedAt,
+		LastFailure: stored.LastFailure,
+		Usable:      present && !isRejected,
+	}
+	if situation.Kind == KeyUnusable {
+		state.Path = situation.Path
+		state.Reason = situation.Reason
+	}
+	return state, nil
+}
+
+// RecordAuthVerified records that the key was accepted: login verification, or any successful request. It clears the last failure.
+func RecordAuthVerified(at time.Time) {
+	writeAuthState(AuthStatePath(), storedAuth{VerifiedAt: isoTime(at)})
+}
+
+// RecordAuthFailure records the failure that degraded TypeSafe. The verification timestamp is kept so a recovered key stays known.
+func RecordAuthFailure(err *IntegrationError, at time.Time) {
+	current := readAuthState(AuthStatePath())
+	writeAuthState(AuthStatePath(), storedAuth{
+		VerifiedAt:  current.VerifiedAt,
+		LastFailure: &AuthFailure{Code: err.Code, Status: err.Status, Message: err.Message, At: isoTime(at)},
+	})
+}
+
+// ClearAuthState forgets verification and degradation: used when the key itself changes (login or logout).
+func ClearAuthState() { _ = os.Remove(AuthStatePath()) }
+
+func isoTime(t time.Time) string { return t.UTC().Format("2006-01-02T15:04:05.000Z") }
+
+// AuthLevel is the severity of an AuthReport.
+type AuthLevel string
+
+// The levels: error when judgments are skipped or were rejected, warning when the key is unverified, else ok.
+const (
+	LevelOK      AuthLevel = "ok"
+	LevelWarning AuthLevel = "warning"
+	LevelError   AuthLevel = "error"
+)
+
+// AuthReport is one line plus a level, so a status command, a headless log, or a consumer's own status line
+// can call out a degraded state instead of reporting "enabled".
+type AuthReport struct {
+	Level AuthLevel
+	Text  string
+}
+
+// DescribeAuth turns a state into a level and one safe line.
+func DescribeAuth(state AuthState) (AuthReport, error) {
+	config, err := ResolveBackend(state.Backend)
+	if err != nil {
+		return AuthReport{}, err
+	}
+	label := config.Label + " key"
+	since := ""
+	if f := state.LastFailure; f != nil {
+		since = " Last failure: " + f.Message
+		if f.At != "" {
+			since += " (" + f.At + ")"
+		}
+	}
+	switch state.Kind {
+	case KeyNotRequired:
+		return AuthReport{LevelOK, config.Label + ": no key needed; judgments use the model PiG is configured with." + since}, nil
+	case KeyMissing:
+		how := config.KeyEnv + " is set in the environment"
+		if UsesTypeSafeKey(config.BackendConfig) {
+			how = "a key is configured (/typesafe login or " + typesafeKeyEnv + ")"
+		}
+		return AuthReport{LevelError, label + ": missing — every Jev judgment is skipped until " + how + "." + since}, nil
+	case KeyUnusable:
+		reason := state.Reason
+		if reason == "" {
+			reason = "unknown reason"
+		}
+		return AuthReport{LevelError, label + ": unusable (" + reason + ") — judgments are skipped until the key is fixed." + since}, nil
+	}
+	if rejected(state.LastFailure) {
+		return AuthReport{LevelError, label + ": " + state.KeyName + " was rejected." + since}, nil
+	}
+	if !state.Verified {
+		return AuthReport{LevelWarning, label + ": " + state.KeyName + " (not verified yet — the first request proves it)." + since}, nil
+	}
+	verified := "verified"
+	if state.VerifiedAt != "" {
+		verified += " " + state.VerifiedAt
+	}
+	return AuthReport{LevelOK, label + ": " + state.KeyName + " (" + verified + ")." + since}, nil
+}

package/auth_test.go

@@ -0,0 +1,131 @@
+package pitypesafe
+
+import (
+	"os"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+)
+
+func mustAuth(t *testing.T, backend any) AuthState {
+	t.Helper()
+	s, err := GetAuthState(AuthOptions{Backend: backend})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return s
+}
+
+func mustDescribe(t *testing.T, s AuthState) AuthReport {
+	t.Helper()
+	r, err := DescribeAuth(s)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return r
+}
+
+func TestAuth(t *testing.T) {
+	tw(t, "auth", "no key at all is an error the consumer cannot mistake for a working setup", func(t *testing.T) {
+		isolate(t)
+		s := mustAuth(t, nil)
+		if s.Kind != KeyMissing || s.KeyName != "no key" || s.Usable || s.Verified {
+			t.Fatalf("state = %+v", s)
+		}
+		r := mustDescribe(t, s)
+		if r.Level != LevelError || !strings.Contains(r.Text, "every Jev judgment is skipped") {
+			t.Fatalf("report = %+v", r)
+		}
+	})
+	tw(t, "auth", "another backend reports its own key and never the TypeSafe login hint", func(t *testing.T) {
+		isolate(t)
+		t.Setenv("TYPESAFE_API_KEY", "env-key-0123456789abcdef")
+		if mustAuth(t, nil).Backend != "typesafe" {
+			t.Error("the default backend is typesafe")
+		}
+		missing := mustAuth(t, "openrouter")
+		if missing.Backend != "openrouter" || missing.Kind != KeyMissing || missing.Usable {
+			t.Fatalf("missing = %+v", missing)
+		}
+		r := mustDescribe(t, missing)
+		if r.Level != LevelError || !strings.HasPrefix(r.Text, "OpenRouter key: missing") || !strings.Contains(r.Text, "OPENROUTER_API_KEY is set") || strings.Contains(r.Text, "/typesafe login") {
+			t.Fatalf("report = %+v", r)
+		}
+		t.Setenv("OPENROUTER_API_KEY", "sk-or-0123456789abcdef")
+		present := mustAuth(t, "openrouter")
+		if present.Kind != KeyEnvironment || present.KeyName != "OPENROUTER_API_KEY" || !present.Usable || !strings.HasPrefix(mustDescribe(t, present).Text, "OpenRouter key: OPENROUTER_API_KEY") {
+			t.Fatalf("present = %+v", present)
+		}
+	})
+	tw(t, "auth", "an environment key is usable but unverified until something proves it", func(t *testing.T) {
+		isolate(t)
+		t.Setenv("TYPESAFE_API_KEY", "env-key-0123456789abcdef")
+		before := mustDescribe(t, mustAuth(t, nil))
+		if before.Level != LevelWarning || !strings.Contains(before.Text, "TYPESAFE_API_KEY") || !strings.Contains(before.Text, "not verified yet") {
+			t.Fatalf("before = %+v", before)
+		}
+		RecordAuthVerified(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC))
+		s := mustAuth(t, nil)
+		if !s.Usable || !s.Verified || s.VerifiedAt != "2026-01-01T00:00:00.000Z" || mustDescribe(t, s).Level != LevelOK {
+			t.Fatalf("state = %+v", s)
+		}
+		if info, _ := os.Stat(AuthStatePath()); runtime.GOOS != "windows" && info.Mode().Perm() != 0o600 {
+			t.Errorf("mode = %v", info.Mode().Perm())
+		}
+	})
+	tw(t, "auth", "a rejected key degrades loudly and a later success clears it", func(t *testing.T) {
+		isolate(t)
+		_, _ = StoreAPIKey("stored-key-0123456789abcdef")
+		RecordAuthVerified(time.Date(2026, 1, 2, 0, 0, 0, 0, time.UTC))
+		msg := "TypeSafe returned HTTP 401. Check TYPESAFE_API_KEY. No automatic retry was made."
+		RecordAuthFailure(&IntegrationError{Code: CodeHTTP, Message: msg, Status: 401}, time.Date(2026, 1, 2, 1, 0, 0, 0, time.UTC))
+		d := mustAuth(t, nil)
+		want := AuthFailure{Code: CodeHTTP, Status: 401, Message: msg, At: "2026-01-02T01:00:00.000Z"}
+		if d.Kind != KeyStored || d.Usable || d.Verified || d.LastFailure == nil || *d.LastFailure != want {
+			t.Fatalf("degraded = %+v", d)
+		}
+		if r := mustDescribe(t, d); r.Level != LevelError || !strings.Contains(r.Text, "was rejected") {
+			t.Fatalf("report = %+v", r)
+		}
+		// A successful request proves the key again and drops the failure.
+		RecordAuthVerified(time.Date(2026, 1, 2, 2, 0, 0, 0, time.UTC))
+		if r := mustAuth(t, nil); !r.Usable || !r.Verified || r.LastFailure != nil {
+			t.Fatalf("recovered = %+v", r)
+		}
+	})
+	tw(t, "auth", "a non-authentication failure degrades the signal without pretending the key is gone", func(t *testing.T) {
+		isolate(t)
+		_, _ = StoreAPIKey("stored-key-0123456789abcdef")
+		RecordAuthVerified(time.Date(2026, 1, 3, 0, 0, 0, 0, time.UTC))
+		RecordAuthFailure(&IntegrationError{Code: CodeTimeout, Message: "TypeSafe request timed out; it was not retried and may still be billed."}, time.Date(2026, 1, 3, 0, 5, 0, 0, time.UTC))
+		s := mustAuth(t, nil)
+		r := mustDescribe(t, s)
+		if !s.Usable || !s.Verified || r.Level != LevelOK || !strings.Contains(r.Text, "Last failure") {
+			t.Fatalf("state = %+v report = %+v", s, r)
+		}
+	})
+	tw(t, "auth", "a stored key readable by other users is reported as unusable, never as enabled", func(t *testing.T) {
+		if runtime.GOOS == "windows" {
+			t.Skip("POSIX permission bits")
+		}
+		isolate(t)
+		writeFile(t, CredentialsPath(), `{"apiKey":"stored-key-0123456789abcdef"}`, 0o644)
+		s := mustAuth(t, nil)
+		if s.Kind != KeyUnusable || s.Usable || s.Reason == "" || mustDescribe(t, s).Level != LevelError {
+			t.Fatalf("state = %+v", s)
+		}
+	})
+	tw(t, "auth", "a corrupt auth record is ignored and clearing forgets both facts", func(t *testing.T) {
+		isolate(t)
+		writeFile(t, AuthStatePath(), "{ not json", 0o600)
+		if s := mustAuth(t, nil); s.Verified || s.LastFailure != nil {
+			t.Fatalf("corrupt = %+v", s)
+		}
+		RecordAuthVerified(time.Date(2026, 1, 4, 0, 0, 0, 0, time.UTC))
+		ClearAuthState()
+		if s := mustAuth(t, nil); s.Verified || s.LastFailure != nil {
+			t.Fatalf("cleared = %+v", s)
+		}
+	})
+}