✨ feat(app): add follow-imports health diagnostics to doctor and readiness check

- Add poll-catchup event tracking when notify mode safety poll consumes bytes
- Track cumulative poll-catchup counts and emit warning after threshold
- Persist follow-imports health snapshot to log directory on each report
- Expose last-known follow health through `doctor` command with stale detection
- Echo follow-imports health fields in `scripts/readiness-check` output
- Add WARN_FOLLOW_IMPORTS_POLL_CATCHUP and WARN_FOLLOW_IMPORTS_HEALTH_STALE codes

Author: cocosip

README.md

@@ -73,13 +73,13 @@ These commands are for operators, packagers, and CI.
 They are not MCP tools and are not the normal end-user interaction path.
 
 - `codex-mem doctor`
-  Prints effective config plus runtime readiness and audit diagnostics.
+  Prints effective config plus runtime readiness, audit diagnostics, and the last-known `follow-imports` watch-health snapshot when one has been written, including stale-snapshot detection for continuous follow mode.
 - `codex-mem doctor --json`
   Prints the same diagnostics in machine-readable JSON for automation or CI checks.
 - `codex-mem ingest-imports --source watcher_import [--input events.jsonl] [--json] [--continue-on-error] [--failed-output failed.jsonl] [--failed-manifest failed.json]`
   Imports newline-delimited watcher or relay note events into durable imported notes plus audit records, with optional partial-success handling plus retry-oriented failure exports.
 - `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 alongside per-input imported-note results.
+  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 migrate`
   Opens the configured SQLite database and applies embedded migrations.
 - `codex-mem serve`
@@ -151,7 +151,7 @@ See [onboarding-flows.md](docs/spec/appendices/onboarding-flows.md) for the full
 - MCP transport/tool availability
 
 Use `codex-mem doctor --json` when the output needs to be consumed by scripts.
-The combined readiness gate under `scripts/readiness-check` is for CI and maintainers, not end users.
+The combined readiness gate under `scripts/readiness-check` is for CI and maintainers, not end users. It now echoes the last-known `follow-imports` doctor fields as informational runtime summary lines for automation, without turning stale or degraded follow health into a hard startup/readiness failure by itself.
 
 For setup and integration failures, use the Go troubleshooting guide in [troubleshooting.md](docs/go/operator/troubleshooting.md).
 

docs/go/maintainer/development-tracker.md

@@ -379,6 +379,36 @@ Current blockers:
 - In progress: none.
 - Blockers: none.
 - Next step: decide whether the next `follow-imports` slice should focus on explicitly detecting poll-caught dropped events during notify mode, or whether the current fallback-plus-recovery behavior is sufficient for operators.
+### 2026-03-16 Session Update
+
+- Completed: Added explicit notify safety-poll catchup observability to `follow-imports`. The runtime loop now distinguishes notify-event-triggered runs from poll-tick runs, and when notify mode remains active but a poll tick consumes appended bytes, the report emits a structured `watch_poll_catchup` event with consumed input and byte counts. This makes it visible when the polling safety net materially contributed to ingestion even though the watcher never fully fell back.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether the next import slice should escalate `watch_poll_catchup` repeated occurrences into stronger operator warnings/metrics, or whether the current event stream is enough.
+### 2026-03-16 Session Update
+
+- Completed: Escalated repeated notify safety-poll catchup into summary-level warnings. `follow-imports` now keeps cumulative `watch_poll_catchups` and `watch_poll_catchup_bytes` counters in runtime state, surfaces them on both single-input and aggregate reports, and emits `WARN_FOLLOW_IMPORTS_POLL_CATCHUP` once the same process has needed poll catchup at least three times. App coverage now verifies the counters, threshold warning, and text output fields.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether the next import slice should export these watch-health counters through `doctor` or another machine-readable diagnostics surface, or whether keeping them scoped to runtime follow reports is enough.
+### 2026-03-16 Session Update
+
+- Completed: Exposed last-known `follow-imports` watch health through `doctor`. Each emitted follow report now refreshes a `follow-imports.health.json` snapshot in the configured log directory, and `doctor` now reports whether that snapshot exists plus its last-known watch mode, fallback counts, poll-catchup counters, and follow-level warnings. App coverage now verifies both the empty-doctor case and the populated follow-health case.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether the next import slice should age or prune stale follow-health snapshots, or whether simple last-known state is sufficient for operators.
+### 2026-03-16 Session Update
+
+- Completed: Added stale-snapshot detection to the `doctor` follow-health view. Follow-health snapshots now persist whether they came from continuous mode and which poll interval they used, and `doctor` marks a snapshot stale when a continuous follow process has not refreshed it for roughly three poll intervals with a 30-second minimum freshness window. Stale snapshots now add `WARN_FOLLOW_IMPORTS_HEALTH_STALE`, and app coverage verifies both fresh and stale follow-health reporting.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether the next import slice should prune stale health files automatically, or whether operators should keep last-known stale state available until the next follow run overwrites it.
+### 2026-03-16 Session Update
+
+- Completed: Surfaced `doctor` follow-health into the broader `scripts/readiness-check` machine-readable summary without creating a second runtime source of truth. The readiness helper now echoes flat `doctor_follow_imports_*` lines for last-known follow status, staleness, watch mode, fallback/catchup counters, and warning codes straight from `doctor --json`; script-level tests cover both populated and missing follow-health cases; and maintainer/operator docs now call out that these lines are informational by default rather than a hard readiness gate.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether a later slice should add an explicit JSON summary mode for `scripts/readiness-check`, or whether the flat key/value output is enough for current automation consumers.
 
 ## Recommended Next Step
 

docs/go/maintainer/mcp-integration.md

@@ -144,6 +144,8 @@ That combined check now covers:
 2. stdio MCP smoke test
 3. HTTP MCP smoke test
 
+The summary output from `scripts/readiness-check` also echoes the `doctor.follow_imports` fields as flat `doctor_follow_imports_*` lines so CI or local automation can inspect last-known runtime watch health from the existing sidecar without having to parse the full doctor JSON again. Those fields are informational by default and do not make the readiness helper fail on their own.
+
 ## Manual Client Checklist
 
 If you are wiring a real MCP client, confirm this order:

docs/go/operator/import-ingestion.md

@@ -188,8 +188,8 @@ JSON mode returns the same summary plus per-line results, including the created
 When a line fails in `--continue-on-error` mode, that result entry includes a structured `error` payload instead.
 If `--failed-output` is set, the report also includes the resolved output path and how many failed lines were written there.
 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, last fallback reason, 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, per-process watch events, total consumed and pending bytes, and one nested per-input report for each followed file.
+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.
 
 ## Operational Notes
 
@@ -200,8 +200,12 @@ Multi-input `follow-imports` returns one aggregate report with command-level wat
 - In `auto` mode, if watcher setup fails or a running watcher later closes/errors, `follow-imports` falls back to polling and keeps retrying watcher setup on later poll intervals. When watcher setup succeeds again, the process switches back to notify mode instead of staying degraded forever.
 - In `notify` mode, watcher setup or runtime failures stop the command instead of silently switching to polling.
 - The follow-mode report now exposes both the requested watch mode and the currently active mode, so operators can tell when `auto` has fallen back to polling and how many fallbacks have happened in the current process.
-- Follow-mode reports now also emit structured watch events when the active mode changes, a fallback occurs, or auto mode successfully recovers from polling back to notify. In JSON mode these appear under `watch_events`; in text mode they are flattened as `watch_event_<n>_*` lines.
+- Follow-mode reports now also emit structured watch events when the active mode changes, a fallback occurs, auto mode successfully recovers from polling back to notify, or notify mode's safety poll is the thing that actually catches newly appended bytes. In JSON mode these appear under `watch_events`; in text mode they are flattened as `watch_event_<n>_*` lines.
 - A watch-state transition or fallback now forces one emitted `follow-imports` report even when the ingestion pass itself is otherwise idle, so long-lived operators can observe notify activation and fallback transitions without waiting for the next imported batch.
+- When a notify-mode safety poll catches appended bytes, `follow-imports` records a `watch_poll_catchup` event with consumed input and byte counts. Treat that as evidence that the polling safety net was materially useful, not necessarily proof that the platform dropped an fsnotify event.
+- `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.
 - 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.

docs/go/operator/release-readiness.md

@@ -80,6 +80,8 @@ Confirm:
 - `exclusion_audit_ready=true`
 - `mcp_tool_count=11`
 
+If your deployment uses `follow-imports`, also inspect the echoed `doctor_follow_imports_*` lines from `go run ./scripts/readiness-check`. Those lines surface the last-known runtime watch-health snapshot from `doctor` for automation, but they remain informational unless your own release gate chooses to fail on stale or degraded follow state.
+
 ### 2. Test Suite
 
 Run: