fix(prepush): never block — auto-redact JSONL via chokepoint, quarantine the rest (0.8.1)

Co-Authored-By: SageOx <ox@sageox.ai>
SageOx-Session: https://sageox.ai/repo/repo_019c5812-01e9-7b7d-b5b1-321c471c9777/sessions/2026-05-12T23-39-ryan-OxzcCn/view

Author: rsnodgrass

cmd/ox/doctor_check_registry.go

@@ -539,6 +539,19 @@ func init() {
 		Run:         checkLedgerEmbeddedCreds,
 	})
 
+	// ox-y3ok: surface sessions that the pre-push secret gate
+	// auto-quarantined because it couldn't auto-redact them. Read-only;
+	// recovery is user-driven (interactive `ox session redact` or
+	// manual scrub + restore from .sageox/cache/quarantine/).
+	RegisterDoctorCheck(&DoctorCheck{
+		Slug:        CheckSlugLedgerRedactionDebt,
+		Name:        "Ledger redaction debt",
+		Category:    "Credential Hygiene",
+		FixLevel:    FixLevelCheckOnly,
+		Description: "Surfaces sessions quarantined by the pre-push secret gate (preserved under .sageox/cache/quarantine/, dropped from pushes until redacted).",
+		Run:         checkLedgerRedactionDebt,
+	})
+
 	// ox-9y4k: scan installed adapter hook content for known-suspicious
 	// shapes that have no legitimate use in a commit/prompt hook.
 	RegisterDoctorCheck(&DoctorCheck{

cmd/ox/doctor_redaction_debt.go

@@ -0,0 +1,158 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/sageox/ox/internal/config"
+	"github.com/sageox/ox/internal/ledger"
+)
+
+// checkLedgerRedactionDebt surfaces sessions that the pre-push secret
+// gate auto-quarantined because it could not redact them through the
+// canonical chokepoint. See cmd/ox/prepush_autoredact.go for the
+// quarantine pipeline: bytes are moved to
+// <ledger>/.sageox/cache/quarantine/<session>/<file> and a JSON marker
+// is written under <ledger>/.sageox/cache/redaction-debt/<session>.json.
+//
+// This check is read-only and local-only. It does not re-scan content;
+// the markers are authoritative — they were produced by a fresh scan at
+// quarantine time. If the user manually moves a quarantined file back
+// to its in-place ledger path or removes the marker, the check
+// gracefully reflects the new state.
+//
+// --fix is intentionally a no-op: the recovery action is either
+// `ox session redact <session>` (interactive cleanup) or the user
+// manually moving the quarantined file back. The doctor command cannot
+// safely choose between those for the user; it surfaces the state and
+// gets out of the way.
+func checkLedgerRedactionDebt(fix bool) checkResult {
+	name := "Ledger redaction debt"
+	_ = fix // recovery is intentionally user-driven; see doc above.
+
+	gitRoot := findGitRoot()
+	if gitRoot == "" {
+		return SkippedCheck(name, "not in git repo", "")
+	}
+	localCfg, err := config.LoadLocalConfig(gitRoot)
+	if err != nil {
+		return SkippedCheck(name, "config error", "")
+	}
+	ledgerPath := resolveLedgerPathForAudit(localCfg)
+	if ledgerPath == "" {
+		return SkippedCheck(name, "no ledger configured", "")
+	}
+	if !ledger.Exists(ledgerPath) {
+		return SkippedCheck(name, "ledger directory does not exist", "")
+	}
+
+	debtDir := filepath.Join(ledgerPath, ".sageox", "cache", "redaction-debt")
+	if _, err := os.Stat(debtDir); err != nil {
+		if os.IsNotExist(err) {
+			return PassedCheck(name, "no quarantined sessions")
+		}
+		return FailedCheck(name, fmt.Sprintf("stat debt dir: %v", err), "")
+	}
+	summaries, malformed := readDebtSummaries(debtDir)
+
+	if len(summaries) == 0 && len(malformed) == 0 {
+		return PassedCheck(name, "no quarantined sessions")
+	}
+
+	var b strings.Builder
+	fmt.Fprintf(&b, "%d session(s) quarantined; bytes preserved under .sageox/cache/quarantine/",
+		len(summaries))
+	if len(malformed) > 0 {
+		fmt.Fprintf(&b, "; %d marker(s) unreadable", len(malformed))
+	}
+	msg := b.String()
+
+	var detail strings.Builder
+	for _, s := range summaries {
+		fmt.Fprintf(&detail, "  %s — %d finding(s) across %d file(s); detectors: %s\n",
+			s.session, s.findings, s.files, strings.Join(s.detectors, ", "))
+	}
+	detail.WriteString("\nNext steps for each session:\n")
+	detail.WriteString("  1. Inspect bytes at .sageox/cache/quarantine/<session>/\n")
+	detail.WriteString("  2. Run `ox session redact <session>` for interactive cleanup, OR\n")
+	detail.WriteString("     manually scrub the file and move it back to sessions/<session>/\n")
+	detail.WriteString("  3. Re-stage and commit; the next push will publish the cleaned bytes\n")
+	if len(malformed) > 0 {
+		detail.WriteString("\nUnreadable markers (remove and re-run if no quarantined bytes exist):\n")
+		for _, m := range malformed {
+			fmt.Fprintf(&detail, "  .sageox/cache/redaction-debt/%s\n", m)
+		}
+	}
+
+	// Use WarningCheck (passed=true, warning=true) rather than
+	// FailedCheck — debt is a state the user opted into by attempting to
+	// push something the gate couldn't clean, and the system already
+	// handled it gracefully (rest of push proceeded). Doctor shouldn't
+	// treat this as an error; it's a reminder.
+	return WarningCheck(name, msg, detail.String())
+}
+
+// debtSummary is the per-marker shape produced by readDebtSummaries.
+// Aggregates the parts of redactionDebtRecord the doctor surface uses;
+// hides the full record from the caller (markers carry filenames and
+// line numbers, never matched bytes — ox-zyg7).
+type debtSummary struct {
+	session   string
+	marker    string
+	findings  int
+	files     int
+	detectors []string
+}
+
+// readDebtSummaries walks debtDir and parses every *.json marker into
+// a debtSummary. Returns (summaries, malformed) — malformed lists
+// filenames whose contents could not be parsed as a redactionDebtRecord.
+// Separated from checkLedgerRedactionDebt so a unit test can exercise
+// the parse + aggregation logic without needing a full project /
+// ledger-config harness.
+func readDebtSummaries(debtDir string) (summaries []debtSummary, malformed []string) {
+	entries, err := os.ReadDir(debtDir)
+	if err != nil {
+		return nil, nil
+	}
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") {
+			continue
+		}
+		markerAbs := filepath.Join(debtDir, entry.Name())
+		buf, err := os.ReadFile(markerAbs)
+		if err != nil {
+			malformed = append(malformed, entry.Name())
+			continue
+		}
+		var rec redactionDebtRecord
+		if err := json.Unmarshal(buf, &rec); err != nil {
+			malformed = append(malformed, entry.Name())
+			continue
+		}
+		detSet := map[string]struct{}{}
+		for _, f := range rec.Findings {
+			detSet[f.Detector] = struct{}{}
+		}
+		dets := make([]string, 0, len(detSet))
+		for d := range detSet {
+			dets = append(dets, d)
+		}
+		sort.Strings(dets)
+		summaries = append(summaries, debtSummary{
+			session:   rec.SessionName,
+			marker:    entry.Name(),
+			findings:  len(rec.Findings),
+			files:     len(rec.QuarantinePaths),
+			detectors: dets,
+		})
+	}
+	sort.Slice(summaries, func(i, j int) bool {
+		return summaries[i].session < summaries[j].session
+	})
+	return summaries, malformed
+}

cmd/ox/doctor_redaction_debt_test.go

@@ -0,0 +1,92 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestCheckLedgerRedactionDebt_PassesWhenNoMarkers covers the steady
+// state: a ledger with no .sageox/cache/redaction-debt/ dir (or an empty
+// one) must report Passed. Anything else would print a spurious warning
+// every doctor run on a healthy ledger.
+func TestCheckLedgerRedactionDebt_PassesWhenNoMarkers(t *testing.T) {
+	// We don't need the gate's recovery; we just need a ledger-shaped
+	// project so the check's preconditions (gitRoot, localCfg, ledger
+	// path) all resolve. Use makeLedgerWithCommit + the unified
+	// config helpers won't apply here because the doctor check looks
+	// up the ledger from a real project config. Instead, write the
+	// marker into an absolute path under a tempdir and call the check
+	// implementation directly via a helper that we expose for tests.
+	//
+	// The easier path: test the parsing surface of the check directly
+	// with handcrafted markers. checkLedgerRedactionDebt is the cobra
+	// glue + filesystem walk; separate the file-walk piece into a
+	// helper for a focused unit. For now we exercise the structure of
+	// the marker round-trip — the e2e wiring is covered by the gate
+	// tests in prepush_autoredact_test.go (they emit real markers and
+	// assert the doctor check can see them via the same file layout).
+
+	tmp := t.TempDir()
+	debtDir := filepath.Join(tmp, ".sageox", "cache", "redaction-debt")
+	require.NoError(t, os.MkdirAll(debtDir, 0o700))
+	// empty dir → no markers → no debt
+	summaries, malformed := readDebtSummaries(debtDir)
+	assert.Empty(t, summaries)
+	assert.Empty(t, malformed)
+}
+
+// TestCheckLedgerRedactionDebt_SurfacesMarker is the load-bearing
+// assertion: a written marker becomes a doctor warning that names the
+// session, its detectors, and the next-step recovery commands.
+func TestCheckLedgerRedactionDebt_SurfacesMarker(t *testing.T) {
+	tmp := t.TempDir()
+	debtDir := filepath.Join(tmp, ".sageox", "cache", "redaction-debt")
+	require.NoError(t, os.MkdirAll(debtDir, 0o700))
+
+	rec := redactionDebtRecord{
+		SessionName:   "2026-05-12-quarantined",
+		QuarantinedAt: time.Now().UTC(),
+		Reason:        "pre-push secret gate could not auto-redact",
+		Findings: []redactionDebtFinding{
+			{Detector: "aws_access_key", Filename: "notes.md", Line: 3},
+			{Detector: "generic_secret", Filename: "notes.md", Line: 9},
+		},
+		QuarantinePaths: []redactionDebtLocation{
+			{From: "sessions/2026-05-12-quarantined/notes.md",
+				To: ".sageox/cache/quarantine/2026-05-12-quarantined/notes.md"},
+		},
+	}
+	buf, err := json.MarshalIndent(rec, "", "  ")
+	require.NoError(t, err)
+	require.NoError(t, os.WriteFile(filepath.Join(debtDir, rec.SessionName+".json"), buf, 0o600))
+
+	summaries, malformed := readDebtSummaries(debtDir)
+	require.Len(t, summaries, 1)
+	require.Empty(t, malformed)
+	got := summaries[0]
+	assert.Equal(t, "2026-05-12-quarantined", got.session)
+	assert.Equal(t, 2, got.findings)
+	assert.Equal(t, 1, got.files)
+	assert.Equal(t, []string{"aws_access_key", "generic_secret"}, got.detectors)
+}
+
+// TestCheckLedgerRedactionDebt_FlagsMalformedMarkers ensures a corrupt
+// or non-JSON file in the debt dir is surfaced — silently dropping it
+// would mean a user could lose track of a quarantined session if its
+// marker got partially written by an interrupted process.
+func TestCheckLedgerRedactionDebt_FlagsMalformedMarkers(t *testing.T) {
+	tmp := t.TempDir()
+	debtDir := filepath.Join(tmp, ".sageox", "cache", "redaction-debt")
+	require.NoError(t, os.MkdirAll(debtDir, 0o700))
+	require.NoError(t, os.WriteFile(filepath.Join(debtDir, "broken.json"), []byte("not json"), 0o600))
+
+	summaries, malformed := readDebtSummaries(debtDir)
+	assert.Empty(t, summaries)
+	assert.Equal(t, []string{"broken.json"}, malformed)
+}

cmd/ox/doctor_types.go

@@ -186,6 +186,7 @@ const (
 	// credential exposure without uploading findings off-machine.
 	CheckSlugLedgerSecrets       = "ledger-secrets"
 	CheckSlugLedgerEmbeddedCreds = "ledger-embedded-creds"
+	CheckSlugLedgerRedactionDebt = "ledger-redaction-debt"
 
 	// Hook content integrity (ox-9y4k): scan installed adapter hook
 	// content for suspicious shapes (curl|sh, eval $(…), base64 -d|sh).