✨ feat(import-follow): add summary-only hygiene reports

- add --summary-only to cleanup-follow-imports and audit-follow-imports
- suppress per-path detail output while preserving counts and follow-health status
- cover compact reporting in tests and operator documentation

Author: cocosip

README.md

@@ -81,9 +81,9 @@ They are not MCP tools and are not the normal end-user interaction path.
 - `codex-mem follow-imports --source watcher_import --input events-a.jsonl [--input events-b.jsonl ...] [--state-file events-a.offset.json --state-file events-b.offset.json ...] [--watch-mode auto|notify|poll] [--poll-interval 5s] [--once] [--json]`
   Follows one or more watcher or relay JSONL files incrementally, prefers filesystem notifications with polling fallback by default, keeps one checkpoint per input, automatically retries watcher recovery in `auto` mode, and reports command-level watch state plus poll-catchup/recovery events and warnings alongside per-input imported-note results.
 - `codex-mem cleanup-follow-imports [--target-profile all|artifacts|state|retry|health] [...]`
-  Removes selected follow-imports checkpoint, retry-artifact, and stale-health artifacts. `--target-profile` can enable common cleanup target sets before you add path, age, or dry-run filters.
+  Removes selected follow-imports checkpoint, retry-artifact, and stale-health artifacts. `--target-profile` can enable common cleanup target sets before you add path, age, dry-run, or `--summary-only` report filters.
 - `codex-mem audit-follow-imports [--target-profile all|artifacts|state|retry|health] [...]`
-  Reports the same hygiene targets without deleting them. `--target-profile` can enable common audit target sets before you add path, age, or fail-if-matched controls.
+  Reports the same hygiene targets without deleting them. `--target-profile` can enable common audit target sets before you add path, age, fail-if-matched, or `--summary-only` controls.
 - `codex-mem migrate`
   Opens the configured SQLite database and applies embedded migrations.
 - `codex-mem serve`

docs/go/maintainer/development-tracker.md

@@ -151,6 +151,13 @@ Immediate next tasks:
 
 ### 2026-03-17 Session Update
 
+- Completed: Added `--summary-only` to `cleanup-follow-imports` and `audit-follow-imports` for automation-friendly compact reports. The hygiene commands still compute the same target counts, fail-if-matched behavior, and follow-health status, but they now omit detailed checkpoint and retry-artifact path lists from text and JSON output when summary-only mode is requested. Parser coverage plus end-to-end run tests now verify both flag parsing and the suppression of per-path details, and the operator docs/README now show when to use the compact mode for scheduled hygiene runs.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether follow/import operators would benefit more from another report-shaping control such as capped path samples, or whether the next slice should move back to a new ingestion/follow capability.
+
+### 2026-03-17 Session Update
+
 - Completed: Added a fifth follow-import hygiene target preset: `--target-profile artifacts`. It expands to checkpoint-sidecar plus retry-artifact targets without touching follow-health snapshots, which fills the gap between `all` and the narrower `state` / `retry` profiles. Parser and end-to-end CLI tests now verify that `artifacts` selects state plus retry work while leaving follow-health out of both cleanup and audit reports, and the operator docs/README now advertise the new preset.
 - In progress: none.
 - Blockers: none.

docs/go/operator/import-ingestion.md

@@ -129,6 +129,12 @@ Focus that audit on retry exports only:
 codex-mem.exe audit-follow-imports --target-profile retry --failed-output .\failed-events.jsonl --failed-manifest .\failed-events.json --retention-profile daily --fail-if-matched
 ```
 
+Keep scheduled hygiene logs compact while preserving the matched counts:
+
+```powershell
+codex-mem.exe audit-follow-imports --target-profile artifacts --input .\events.jsonl --failed-output .\failed-events.jsonl --failed-manifest .\failed-events.json --summary-only --json
+```
+
 Cover checkpoint plus retry artifacts together while leaving follow-health untouched:
 
 ```powershell
@@ -195,6 +201,8 @@ Useful flags:
   `cleanup-follow-imports` only. Optional. Computes the same cleanup candidates and reports what would be removed, but leaves every file in place.
 - `--fail-if-matched`
   `cleanup-follow-imports` and `audit-follow-imports` only. Optional. Returns a non-zero exit after writing the report when the selected target set matched at least one checkpoint sidecar, retry artifact, or stale follow-health snapshot. This is especially useful for CI or scheduled hygiene audits.
+- `--summary-only`
+  `cleanup-follow-imports` and `audit-follow-imports` only. Optional. Keeps the same aggregate counts, target metadata, and follow-health status, but omits enumerated checkpoint and retry-artifact path lists from the text or JSON report. This is useful for scheduled automation where path-by-path detail would create noisy logs.
 - `--include <glob>`
   `cleanup-follow-imports` and `audit-follow-imports` only. Optional. Repeats or accepts comma-separated glob patterns that act as a whitelist for checkpoint and retry-artifact candidate paths. Patterns are matched against both the absolute path and the basename.
 - `--exclude <glob>`
@@ -279,8 +287,9 @@ If `--failed-output` is set, the report also includes the resolved output path a
 If `--failed-manifest` is set, the report also includes the manifest path and how many failures were captured there.
 Single-input `follow-imports` reports the input path, checkpoint file, requested watch mode, active watch mode, fallback count, transition count, cumulative poll-catchup count and bytes, any warning summaries, any structured watch events since the previous emitted report, consumed offset, pending trailing bytes, whether the checkpoint was reset, the reset reason, truncation detection, and the nested batch report for whatever newly appended complete lines were imported during that poll.
 Multi-input `follow-imports` returns one aggregate report with command-level watch state, cumulative poll-catchup counters, warning summaries, per-process watch events, total consumed and pending bytes, and one nested per-input report for each followed file.
-`cleanup-follow-imports` reports whether the run was a dry-run, whether `--fail-if-matched` was active, whether the selected target set matched anything, the named retention profile when one is active, the configured age gate in seconds, any include/exclude patterns in effect, how many checkpoint sidecars and derived retry artifacts matched cleanup versus were actually removed, which files were skipped because they were filtered out by pattern or were too new, which explicit state files were already missing, and whether it pruned or would prune the stale follow-health sidecar.
-`audit-follow-imports` reports the same target-selection metadata and matched-versus-skipped counts as a read-only hygiene pass, plus whether the follow-health snapshot is present, when it was last updated, whether it is stale, and any warning summaries carried by that snapshot.
+`cleanup-follow-imports` reports whether the run was a dry-run, whether `--fail-if-matched` was active, whether the selected target set matched anything, whether `--summary-only` was active, the named retention profile when one is active, the configured age gate in seconds, any include/exclude patterns in effect, how many checkpoint sidecars and derived retry artifacts matched cleanup versus were actually removed, which files were skipped because they were filtered out by pattern or were too new, which explicit state files were already missing, and whether it pruned or would prune the stale follow-health sidecar.
+`audit-follow-imports` reports the same target-selection metadata and matched-versus-skipped counts as a read-only hygiene pass, plus whether `--summary-only` was active, whether the follow-health snapshot is present, when it was last updated, whether it is stale, and any warning summaries carried by that snapshot.
+When `--summary-only` is set, the aggregate counts stay the same but the detailed checkpoint and retry-artifact path lists are omitted from both text and JSON output.
 
 Checked-in sample outputs for common cleanup flows live under [../../../internal/app/testdata](../../../internal/app/testdata/):
 
@@ -345,6 +354,7 @@ go test ./internal/app -run "Test(Audit|Cleanup)FollowImportsExampleOutputsStayI
 - If you want the same target selection and age/pattern filtering logic without any deletion, use `codex-mem.exe audit-follow-imports`. It is the cleaner fit for scheduled reports, pre-cleanup review, and automation that should fail on pending hygiene work before anything is removed.
 - Add `--dry-run` first when you are not fully sure about the target set. The report shows the same matched file list and stale-health outcome it would use for a real cleanup pass, but without deleting anything.
 - Add `--fail-if-matched` when the command should act as a hygiene gate instead of only as an informational report. On `audit-follow-imports` the command stays read-only; on `cleanup-follow-imports --dry-run` it behaves the same way while still showing what a future deletion pass would remove.
+- Add `--summary-only` when scheduled automation or CI should preserve the counts and status metadata but avoid printing long per-path lists into logs or inbox output.
 - Add `--older-than <duration>` when you want cleanup or audit to ignore very recent checkpoint or retry files. This age gate applies to checkpoint sidecars plus range-suffixed retry artifacts, not to the stale-health decision, which still uses the existing follow-health staleness policy.
 - Add `--include` when the cleanup or audit target should stay inside one file family, input label, or path prefix. This is especially useful for multi-input runs where you only want to inspect or clean artifacts related to one input at a time.
 - Add `--exclude` for the final guardrail when a broad include or input set still catches more than you want. Exclude patterns override includes, so they are the safer place to carve out known paths or suffixes.

internal/app/import_follow.go

@@ -67,6 +67,7 @@ type followImportsHygieneOptions struct {
 	CWD                string
 	JSON               bool
 	FailIfMatched      bool
+	SummaryOnly        bool
 	OlderThan          time.Duration
 	olderThanExplicit  bool
 }
@@ -221,6 +222,7 @@ type cleanupFollowImportsReport struct {
 	DryRun           bool                                 `json:"dry_run"`
 	FailIfMatched    bool                                 `json:"fail_if_matched"`
 	MatchFound       bool                                 `json:"match_found"`
+	SummaryOnly      bool                                 `json:"summary_only,omitempty"`
 	TargetProfile    string                               `json:"target_profile,omitempty"`
 	RetentionProfile string                               `json:"retention_profile,omitempty"`
 	OlderThanSeconds int64                                `json:"older_than_seconds,omitempty"`
@@ -270,6 +272,7 @@ type cleanupFollowImportsFollowHealthView struct {
 type auditFollowImportsReport struct {
 	FailIfMatched    bool                             `json:"fail_if_matched"`
 	MatchFound       bool                             `json:"match_found"`
+	SummaryOnly      bool                             `json:"summary_only,omitempty"`
 	TargetProfile    string                           `json:"target_profile,omitempty"`
 	RetentionProfile string                           `json:"retention_profile,omitempty"`
 	OlderThanSeconds int64                            `json:"older_than_seconds,omitempty"`
@@ -810,6 +813,9 @@ func parseFollowImportsHygieneBooleanFlag(arg string, options *followImportsHygi
 	case "--fail-if-matched":
 		options.FailIfMatched = true
 		return true
+	case "--summary-only":
+		options.SummaryOnly = true
+		return true
 	default:
 		return false
 	}
@@ -1853,6 +1859,7 @@ func cleanupFollowImportsAt(cfg config.Config, options cleanupFollowImportsOptio
 	report := cleanupFollowImportsReport{
 		DryRun:           options.DryRun,
 		FailIfMatched:    options.FailIfMatched,
+		SummaryOnly:      options.SummaryOnly,
 		TargetProfile:    options.TargetProfile,
 		RetentionProfile: options.RetentionProfile,
 		OlderThanSeconds: int64(options.OlderThan / time.Second),
@@ -1889,6 +1896,9 @@ func cleanupFollowImportsAt(cfg config.Config, options cleanupFollowImportsOptio
 		}
 	}
 	report.MatchFound = cleanupFollowImportsHasMatches(report)
+	if options.SummaryOnly {
+		report = cleanupFollowImportsSummaryOnlyReport(report)
+	}
 
 	return report, nil
 }
@@ -1921,6 +1931,7 @@ func auditFollowImportsAt(cfg config.Config, options auditFollowImportsOptions,
 	scanOptions := options.cleanupDryRunOptions()
 	report := auditFollowImportsReport{
 		FailIfMatched:    options.FailIfMatched,
+		SummaryOnly:      options.SummaryOnly,
 		TargetProfile:    options.TargetProfile,
 		RetentionProfile: options.RetentionProfile,
 		OlderThanSeconds: int64(options.OlderThan / time.Second),
@@ -1961,9 +1972,47 @@ func auditFollowImportsAt(cfg config.Config, options auditFollowImportsOptions,
 	}
 
 	report.MatchFound = auditFollowImportsHasMatches(report)
+	if options.SummaryOnly {
+		report = auditFollowImportsSummaryOnlyReport(report)
+	}
 	return report, nil
 }
 
+func cleanupFollowImportsSummaryOnlyReport(report cleanupFollowImportsReport) cleanupFollowImportsReport {
+	report.StateFiles.MatchedPaths = nil
+	report.StateFiles.RemovedPaths = nil
+	report.StateFiles.MissingPaths = nil
+	report.StateFiles.SkippedByPatternPaths = nil
+	report.StateFiles.SkippedByAgePaths = nil
+	report.FailedOutputs.BasePaths = nil
+	report.FailedOutputs.MatchedPaths = nil
+	report.FailedOutputs.RemovedPaths = nil
+	report.FailedOutputs.SkippedByPatternPaths = nil
+	report.FailedOutputs.SkippedByAgePaths = nil
+	report.FailedManifests.BasePaths = nil
+	report.FailedManifests.MatchedPaths = nil
+	report.FailedManifests.RemovedPaths = nil
+	report.FailedManifests.SkippedByPatternPaths = nil
+	report.FailedManifests.SkippedByAgePaths = nil
+	return report
+}
+
+func auditFollowImportsSummaryOnlyReport(report auditFollowImportsReport) auditFollowImportsReport {
+	report.StateFiles.MatchedPaths = nil
+	report.StateFiles.MissingPaths = nil
+	report.StateFiles.SkippedByPatternPaths = nil
+	report.StateFiles.SkippedByAgePaths = nil
+	report.FailedOutputs.BasePaths = nil
+	report.FailedOutputs.MatchedPaths = nil
+	report.FailedOutputs.SkippedByPatternPaths = nil
+	report.FailedOutputs.SkippedByAgePaths = nil
+	report.FailedManifests.BasePaths = nil
+	report.FailedManifests.MatchedPaths = nil
+	report.FailedManifests.SkippedByPatternPaths = nil
+	report.FailedManifests.SkippedByAgePaths = nil
+	return report
+}
+
 func newAuditFollowImportsPathSummary(summary cleanupFollowImportsPathSummary) auditFollowImportsPathSummary {
 	return auditFollowImportsPathSummary{
 		Requested:             summary.Requested,
@@ -2531,6 +2580,9 @@ func formatCleanupFollowImportsReport(report cleanupFollowImportsReport) string
 		fmt.Sprintf("follow_health_pruned=%t", report.FollowHealth.Pruned),
 		fmt.Sprintf("follow_health_prune_reason=%s", fallbackString(report.FollowHealth.PruneReason)),
 	}
+	if report.SummaryOnly {
+		lines = append(lines, "summary_only=true")
+	}
 	if report.TargetProfile != "" {
 		lines = append(lines, fmt.Sprintf("target_profile=%s", report.TargetProfile))
 	}
@@ -2630,6 +2682,9 @@ func formatAuditFollowImportsReport(report auditFollowImportsReport) string {
 		fmt.Sprintf("follow_health_watch_poll_catchup_bytes=%d", report.FollowHealth.WatchPollCatchupBytes),
 		fmt.Sprintf("follow_health_warnings=%d", len(report.FollowHealth.Warnings)),
 	}
+	if report.SummaryOnly {
+		lines = append(lines, "summary_only=true")
+	}
 	if report.TargetProfile != "" {
 		lines = append(lines, fmt.Sprintf("target_profile=%s", report.TargetProfile))
 	}

internal/app/import_follow_test.go

@@ -143,6 +143,7 @@ func TestParseCleanupFollowImportsOptions(t *testing.T) {
 		"--older-than", "2h",
 		"--dry-run",
 		"--fail-if-matched",
+		"--summary-only",
 		"--prune-state",
 		"--prune-failed-output",
 		"--prune-failed-manifest",
@@ -164,6 +165,9 @@ func TestParseCleanupFollowImportsOptions(t *testing.T) {
 	if !options.FailIfMatched {
 		t.Fatal("expected fail-if-matched option")
 	}
+	if !options.SummaryOnly {
+		t.Fatal("expected summary-only option")
+	}
 	if got, want := options.OlderThan, 2*time.Hour; got != want {
 		t.Fatalf("older-than mismatch: got %s want %s", got, want)
 	}
@@ -339,6 +343,7 @@ func TestParseAuditFollowImportsOptions(t *testing.T) {
 		"--cwd", "D:/Code/go/codex-mem",
 		"--older-than", "2h",
 		"--fail-if-matched",
+		"--summary-only",
 		"--check-state",
 		"--check-failed-output",
 		"--check-failed-manifest",
@@ -357,6 +362,9 @@ func TestParseAuditFollowImportsOptions(t *testing.T) {
 	if !options.FailIfMatched {
 		t.Fatal("expected fail-if-matched option")
 	}
+	if !options.SummaryOnly {
+		t.Fatal("expected summary-only option")
+	}
 	if got, want := options.OlderThan, 2*time.Hour; got != want {
 		t.Fatalf("older-than mismatch: got %s want %s", got, want)
 	}