✨ feat(readiness-check): add --list-examples and subset refresh support

- Add --list-examples flag to list available fixture names
- Support --refresh-examples=<name[,name...]> for selective refresh
- Validate requested fixture names upfront before processing
- Add test coverage for list output and subset rewrites

✨ feat(doctor): add --prune-stale-follow-health for explicit cleanup

- Add --prune-stale-follow-health flag to remove stale snapshots
- Report prune status and reason in text/JSON output
- Preserve fresh snapshots when prune is requested
- Add test coverage for prune behavior

Author: cocosip

docs/go/maintainer/development-tracker.md

@@ -498,6 +498,20 @@ Current blockers:
 - Blockers: none.
 - Next step: decide whether the refresh helper should remain a mode on `readiness-check`, or move to a separate maintainer script if the checked-in example catalog grows further.
 
+### 2026-03-17 Session Update
+
+- Completed: Made the readiness example helper scale a bit better as the fixture catalog grows. `scripts/readiness-check` now supports `--list-examples` plus `--refresh-examples=<name[,name...]>`, validates requested fixture names up front, and test coverage now checks list output plus subset-only rewrites instead of assuming every refresh touches the full catalog.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether the current list-and-subset workflow is enough for maintainers, or whether the example catalog should eventually move into a small manifest file with richer metadata.
+
+### 2026-03-17 Session Update
+
+- Completed: Added explicit stale follow-health pruning to `doctor`. Operators can now run `doctor --prune-stale-follow-health` to remove only stale `follow-imports.health.json` sidecars, and the doctor text/JSON report now surfaces whether a snapshot was pruned plus the prune reason. App coverage now verifies stale snapshots are removed only when requested and that fresh snapshots are preserved.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether explicit stale pruning is enough operator hygiene, or whether a later slice should add a broader import/follow cleanup surface for old checkpoints and retry artifacts too.
+
 ## Recommended Next Step
 
 Recommended next implementation slice:

docs/go/maintainer/mcp-integration.md

@@ -220,6 +220,13 @@ If a deliberate readiness-output change makes those fixtures drift, refresh them
 go run ./scripts/readiness-check --refresh-examples
 ```
 
+If you only need one or two fixtures while iterating on a specific output shape, first list the available fixture names and then refresh just the subset you want:
+
+```powershell
+go run ./scripts/readiness-check --list-examples
+go run ./scripts/readiness-check --refresh-examples=ci-json
+```
+
 Then rerun `go test ./scripts/readiness-check -run TestReadinessExampleOutputsStayInSync` plus the normal repo checks so the updated fixtures are verified in read-only mode again.
 
 That combined check now covers:

docs/go/operator/import-ingestion.md

@@ -206,6 +206,7 @@ Multi-input `follow-imports` returns one aggregate report with command-level wat
 - `follow-imports` also keeps cumulative `watch_poll_catchups` and `watch_poll_catchup_bytes` counters for the lifetime of the process. Once poll catchup happens at least three times in the same process, the report adds a `WARN_FOLLOW_IMPORTS_POLL_CATCHUP` warning so operators and automation can treat notify mode as degraded even if it never fully falls back.
 - Each emitted `follow-imports` report also refreshes a last-known health sidecar under the normal log directory. `codex-mem doctor` reads that snapshot so operators can inspect the most recent follow-mode watch health even after the long-lived process has already exited.
 - For continuous follow mode, `doctor` now marks that sidecar as stale when it has not been refreshed for roughly three poll intervals, with a minimum freshness window of 30 seconds. Stale follow health adds `WARN_FOLLOW_IMPORTS_HEALTH_STALE` so operators can distinguish a healthy last-known state from an old snapshot left behind by a stopped process.
+- If you want to clear only stale follow-health sidecars without touching fresh ones, run `codex-mem.exe doctor --prune-stale-follow-health`. The doctor report then tells you whether it actually removed a stale snapshot via `follow_imports_health_pruned` and `follow_imports_health_prune_reason`.
 - When multi-input follow mode shares `--failed-output` or `--failed-manifest` base paths, `codex-mem` derives per-input file names before adding the byte-range suffix so retry artifacts from different inputs do not overwrite each other.
 - Each event uses the same imported-note workflow as `memory_save_imported_note`.
 - Existing explicit memory wins over weaker imported duplicates in the same project.

internal/app/doctor.go

@@ -13,7 +13,8 @@ import (
 )
 
 type doctorOptions struct {
-	JSON bool
+	JSON                   bool
+	PruneStaleFollowHealth bool
 }
 
 type doctorReport struct {
@@ -92,6 +93,8 @@ type doctorLoggingReport struct {
 type doctorFollowReport struct {
 	HealthFile            string           `json:"health_file"`
 	HealthPresent         bool             `json:"health_present"`
+	HealthPruned          bool             `json:"health_pruned"`
+	HealthPruneReason     string           `json:"health_prune_reason,omitempty"`
 	LastUpdatedAt         *time.Time       `json:"last_updated_at,omitempty"`
 	Status                string           `json:"status,omitempty"`
 	Source                string           `json:"source,omitempty"`
@@ -117,6 +120,7 @@ type doctorMCPReport struct {
 
 const (
 	doctorJSONFlag                    = "--json"
+	doctorPruneStaleFollowHealthFlag  = "--prune-stale-follow-health"
 	stringNone                        = "none"
 	doctorFollowHealthStaleMultiplier = 3
 	doctorFollowHealthMinimumWindow   = 30 * time.Second
@@ -130,18 +134,22 @@ func parseDoctorOptions(args []string) (doctorOptions, error) {
 			continue
 		case doctorJSONFlag:
 			options.JSON = true
+		case doctorPruneStaleFollowHealthFlag:
+			options.PruneStaleFollowHealth = true
 		default:
 			return doctorOptions{}, fmt.Errorf("unknown doctor flag %q", arg)
 		}
 	}
 	return options, nil
 }
 
-func buildDoctorReport(cfg config.Config, runtime db.RuntimeDiagnostics, toolCount int, followHealth *followImportsHealthSnapshot) doctorReport {
+func buildDoctorReport(cfg config.Config, runtime db.RuntimeDiagnostics, toolCount int, followHealth *followImportsHealthSnapshot, healthPruned bool, healthPruneReason string) doctorReport {
 	now := time.Now().UTC()
 	followReport := doctorFollowReport{
-		HealthFile:    followImportsHealthPath(cfg.Meta.LogDir),
-		HealthPresent: followHealth != nil,
+		HealthFile:        followImportsHealthPath(cfg.Meta.LogDir),
+		HealthPresent:     followHealth != nil,
+		HealthPruned:      healthPruned,
+		HealthPruneReason: strings.TrimSpace(healthPruneReason),
 	}
 	if followHealth != nil {
 		age, stale := evaluateFollowImportsHealthStaleness(*followHealth, now)
@@ -281,6 +289,8 @@ func formatDoctorReport(report doctorReport) string {
 		fmt.Sprintf("log_stderr=%t", report.Logging.LogStderr),
 		fmt.Sprintf("follow_imports_health_file=%s", report.Follow.HealthFile),
 		fmt.Sprintf("follow_imports_health_present=%t", report.Follow.HealthPresent),
+		fmt.Sprintf("follow_imports_health_pruned=%t", report.Follow.HealthPruned),
+		fmt.Sprintf("follow_imports_health_prune_reason=%s", fallbackString(report.Follow.HealthPruneReason)),
 		fmt.Sprintf("follow_imports_last_updated_at=%s", pointerTimeOrNone(report.Follow.LastUpdatedAt)),
 		fmt.Sprintf("follow_imports_status=%s", fallbackString(report.Follow.Status)),
 		fmt.Sprintf("follow_imports_source=%s", fallbackString(report.Follow.Source)),
@@ -367,3 +377,21 @@ func followImportsHealthStaleWarnings(_ followImportsHealthSnapshot, age time.Du
 		Message: fmt.Sprintf("follow-imports health snapshot is stale at %s", age.Truncate(time.Second)),
 	}}
 }
+
+func loadDoctorFollowImportsHealth(logDir string, pruneStale bool, now time.Time) (*followImportsHealthSnapshot, bool, string, error) {
+	followHealth, err := loadFollowImportsHealthSnapshot(logDir)
+	if err != nil {
+		return nil, false, "", err
+	}
+	if !pruneStale || followHealth == nil {
+		return followHealth, false, "", nil
+	}
+	_, stale := evaluateFollowImportsHealthStaleness(*followHealth, now)
+	if !stale {
+		return followHealth, false, "", nil
+	}
+	if err := pruneFollowImportsHealthSnapshot(logDir); err != nil {
+		return nil, false, "", err
+	}
+	return nil, true, "stale", nil
+}

internal/app/import_follow.go

@@ -1403,6 +1403,17 @@ func loadFollowImportsHealthSnapshot(logDir string) (*followImportsHealthSnapsho
 	return &snapshot, nil
 }
 
+func pruneFollowImportsHealthSnapshot(logDir string) error {
+	path := followImportsHealthPath(logDir)
+	if err := os.Remove(path); err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return fmt.Errorf("remove follow-imports health snapshot: %w", err)
+	}
+	return nil
+}
+
 func newFollowImportsHealthSnapshotFromReport(report followImportsReport, options followImportsOptions) followImportsHealthSnapshot {
 	return followImportsHealthSnapshot{
 		Status:              report.Status,

internal/app/run.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"log/slog"
 	"os"
+	"time"
 
 	"codex-mem/internal/buildinfo"
 	"codex-mem/internal/config"
@@ -63,7 +64,7 @@ func Run(ctx context.Context, cfg config.Config, args []string, stdin io.Reader,
 		if err != nil {
 			return err
 		}
-		followHealth, err := loadFollowImportsHealthSnapshot(cfg.Meta.LogDir)
+		followHealth, healthPruned, healthPruneReason, err := loadDoctorFollowImportsHealth(cfg.Meta.LogDir, options.PruneStaleFollowHealth, time.Now().UTC())
 		if err != nil {
 			return err
 		}
@@ -75,8 +76,10 @@ func Run(ctx context.Context, cfg config.Config, args []string, stdin io.Reader,
 			"required_schema_ok", runtimeDiagnostics.RequiredSchemaOK,
 			"fts_ready", runtimeDiagnostics.FTSReady,
 			"json", options.JSON,
+			"prune_stale_follow_health", options.PruneStaleFollowHealth,
+			"follow_health_pruned", healthPruned,
 		)
-		report := buildDoctorReport(cfg, runtimeDiagnostics, mcp.ToolCount(), followHealth)
+		report := buildDoctorReport(cfg, runtimeDiagnostics, mcp.ToolCount(), followHealth, healthPruned, healthPruneReason)
 		output := formatDoctorReport(report)
 		if options.JSON {
 			output, err = formatDoctorReportJSON(report)

internal/app/run_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"os"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -195,6 +196,8 @@ func TestRunDoctorFlagsStaleFollowImportsHealthSnapshot(t *testing.T) {
 	output := stdout.String()
 	for _, fragment := range []string{
 		"follow_imports_health_present=true",
+		"follow_imports_health_pruned=false",
+		"follow_imports_health_prune_reason=none",
 		"follow_imports_health_stale=true",
 		"follow_imports_warnings=1",
 		"follow_imports_warning_1_code=WARN_FOLLOW_IMPORTS_HEALTH_STALE",
@@ -205,6 +208,125 @@ func TestRunDoctorFlagsStaleFollowImportsHealthSnapshot(t *testing.T) {
 	}
 }
 
+func TestRunDoctorPrunesStaleFollowImportsHealthSnapshotWhenRequested(t *testing.T) {
+	root := t.TempDir()
+	cfg := config.Config{
+		File: config.FileConfig{
+			DatabasePath:      filepath.Join(root, "data", "codex-mem.db"),
+			DefaultSystemName: "codex-mem",
+			SQLiteDriver:      "sqlite",
+			BusyTimeout:       5 * time.Second,
+			JournalMode:       "WAL",
+			LogFilePath:       filepath.Join(root, "logs", "codex-mem.log"),
+			LogMaxSizeMB:      20,
+			LogMaxBackups:     10,
+			LogMaxAgeDays:     30,
+			LogCompress:       true,
+			LogAlsoStderr:     false,
+		},
+		Meta: config.LoadMetadata{
+			ConfigDir:      filepath.Join(root, "configs"),
+			ConfigFilePath: filepath.Join(root, "configs", "codex-mem.json"),
+			LogDir:         filepath.Join(root, "logs"),
+		},
+	}
+
+	snapshot := followImportsHealthSnapshot{
+		Status:              "ok",
+		UpdatedAt:           time.Now().UTC().Add(-2 * time.Minute),
+		Source:              "watcher_import",
+		InputCount:          1,
+		Continuous:          true,
+		PollIntervalSeconds: 5,
+		RequestedWatchMode:  "auto",
+		ActiveWatchMode:     "notify",
+	}
+	if err := saveFollowImportsHealthSnapshot(cfg.Meta.LogDir, snapshot); err != nil {
+		t.Fatalf("saveFollowImportsHealthSnapshot: %v", err)
+	}
+
+	var stdout bytes.Buffer
+	if err := Run(context.Background(), cfg, []string{"doctor", "--prune-stale-follow-health"}, strings.NewReader(""), &stdout); err != nil {
+		t.Fatalf("Run doctor --prune-stale-follow-health: %v", err)
+	}
+
+	output := stdout.String()
+	for _, fragment := range []string{
+		"follow_imports_health_present=false",
+		"follow_imports_health_pruned=true",
+		"follow_imports_health_prune_reason=stale",
+		"follow_imports_health_stale=false",
+		"follow_imports_warnings=0",
+	} {
+		if !strings.Contains(output, fragment) {
+			t.Fatalf("doctor output missing %q:\n%s", fragment, output)
+		}
+	}
+
+	if _, err := os.Stat(followImportsHealthPath(cfg.Meta.LogDir)); !os.IsNotExist(err) {
+		t.Fatalf("expected stale follow health snapshot to be removed, stat err=%v", err)
+	}
+}
+
+func TestRunDoctorDoesNotPruneFreshFollowImportsHealthSnapshot(t *testing.T) {
+	root := t.TempDir()
+	cfg := config.Config{
+		File: config.FileConfig{
+			DatabasePath:      filepath.Join(root, "data", "codex-mem.db"),
+			DefaultSystemName: "codex-mem",
+			SQLiteDriver:      "sqlite",
+			BusyTimeout:       5 * time.Second,
+			JournalMode:       "WAL",
+			LogFilePath:       filepath.Join(root, "logs", "codex-mem.log"),
+			LogMaxSizeMB:      20,
+			LogMaxBackups:     10,
+			LogMaxAgeDays:     30,
+			LogCompress:       true,
+			LogAlsoStderr:     false,
+		},
+		Meta: config.LoadMetadata{
+			ConfigDir:      filepath.Join(root, "configs"),
+			ConfigFilePath: filepath.Join(root, "configs", "codex-mem.json"),
+			LogDir:         filepath.Join(root, "logs"),
+		},
+	}
+
+	snapshot := followImportsHealthSnapshot{
+		Status:              "partial",
+		UpdatedAt:           time.Now().UTC(),
+		Source:              "watcher_import",
+		InputCount:          1,
+		Continuous:          true,
+		PollIntervalSeconds: 5,
+		RequestedWatchMode:  "auto",
+		ActiveWatchMode:     "notify",
+	}
+	if err := saveFollowImportsHealthSnapshot(cfg.Meta.LogDir, snapshot); err != nil {
+		t.Fatalf("saveFollowImportsHealthSnapshot: %v", err)
+	}
+
+	var stdout bytes.Buffer
+	if err := Run(context.Background(), cfg, []string{"doctor", "--prune-stale-follow-health"}, strings.NewReader(""), &stdout); err != nil {
+		t.Fatalf("Run doctor --prune-stale-follow-health: %v", err)
+	}
+
+	output := stdout.String()
+	for _, fragment := range []string{
+		"follow_imports_health_present=true",
+		"follow_imports_health_pruned=false",
+		"follow_imports_health_prune_reason=none",
+		"follow_imports_health_stale=false",
+	} {
+		if !strings.Contains(output, fragment) {
+			t.Fatalf("doctor output missing %q:\n%s", fragment, output)
+		}
+	}
+
+	if _, err := os.Stat(followImportsHealthPath(cfg.Meta.LogDir)); err != nil {
+		t.Fatalf("expected fresh follow health snapshot to remain, stat err=%v", err)
+	}
+}
+
 func TestRunDoctorReportsMissingConfigFileAsNone(t *testing.T) {
 	root := t.TempDir()
 	cfg := config.Config{
@@ -483,3 +605,13 @@ func TestRunDoctorRejectsUnknownFlag(t *testing.T) {
 		t.Fatalf("unexpected error: %v", err)
 	}
 }
+
+func TestParseDoctorOptionsEnablesPruneStaleFollowHealth(t *testing.T) {
+	options, err := parseDoctorOptions([]string{"--prune-stale-follow-health"})
+	if err != nil {
+		t.Fatalf("parseDoctorOptions: %v", err)
+	}
+	if !options.PruneStaleFollowHealth {
+		t.Fatal("expected prune-stale-follow-health option to be enabled")
+	}
+}