fix(lsp): read a monotonic clock for idle bookkeeping, not the wall clock

[pai-scaffolde]

The idle reaper is on the wall clock, and the wall clock steps

LSPService's idle bookkeeping compared _last_used against time.time():

manager.py:559,610,632   self._last_used[key] = time.time()
manager.py:649           cutoff = time.time() - self._idle_timeout

Those values are only ever compared to each other. What they need is elapsed time, which the wall clock does not provide — NTP correction and sleep/wake both step it, and this fork runs on laptops and a Mac Mini that sleep.

• Backwards step > idle_timeout: every cutoff is dragged into the past, no client ever looks idle, and the reaper silently stops reaping — reviving the unbounded language-server accumulation the reaper exists to close.
• Forwards step: the opposite — servers still in active use get evicted.

Neither failure surfaces anywhere. The reaper keeps sweeping and keeps logging; it just stops finding anything.

The change

Routes the four idle-bookkeeping sites through a single _idle_clock() returning time.monotonic(), so the clock source is declared once, documented once, and greppable.

The change is closed: _last_used is internal, and nothing outside the reaper reads it, serializes it, or reports it as an absolute time (grep -rn _last_used --include='*.py' → manager.py plus one test doing purely relative arithmetic). Swapping the clock changes no observable value.

+87 / −4 across 2 files. Deliberately narrow: no config surface, no docs churn, no population cap. ruff format is not clean on either file on main either and CI does not run it, so no reformatting is included.

Verification

Positive control first, because a regression test that has never been seen red is indistinguishable from one that cannot go red. The new test steps the wall clock an hour into the past mid-flight while leaving monotonic() untouched:

tree	test_reaper_is_immune_to_wall_clock_steps
origin/main's manager.py (unfixed)	FAILS — idle client survives the sweep, the exact stalled-reaper symptom
this branch	PASSES

# unfixed
E  AssertionError: a backwards wall-clock step stalled the reaper —
   idle bookkeeping must read a monotonic clock
   assert ('pyright', '.../repo') not in {('pyright', '.../repo'): <LSPClient>}
   1 failed in 0.10s

Rest:

• pytest tests/agent/lsp/ → 61 passed (was 60; this adds 1)
• ruff check agent/lsp/manager.py tests/agent/lsp/test_service.py → All checks passed
• Suite run against a scratch HERMES_HOME; production ~/.hermes/logs/agent.log byte delta 0 (the pollution in fix(tests): stop the LSP suite writing into the operator's real agent.log #61 is still unmerged, so this was contained by hand)

Provenance and relationship to the open SCA-4389 PRs

time.monotonic() here is salvaged from #50, where it was hardening earned in a Codex review round. #50/#51/#52 predate upstream's reaper landing on main (d7578018c5 + 24a56f027c, 2026-07-29) and now conflict with it in manager.py/eventlog.py; #58 is cap-only and does not touch the clock. So this fix is orthogonal to whatever is decided about those four, and is the one piece of that work that measurement did not retire.

Upstreamable as-is — it is a fix to upstream-authored code with no fork-local dependency.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d1cc084db0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[pai-scaffolde]

Merge-order composition verified for the LSP stack

All of #62–#67 report mergeStateStatus: CLEAN and six of them edit agent/lsp/manager.py. CLEAN is computed per-PR against main and is blind to sibling collisions, so I composed the set instead of trusting it.

Ancestry (git merge-base --is-ancestor, origin/main 54d19ecded)

main → #63 → #64 → #65 → #66 → ┬→ #62  (+16 vs main)
                               └→ #67  (+15 vs main)
#61 — independent (+3), no file overlap

This PR (#62) subsumes #63, #64, #65 and #66. Merging it lands SCA-4620, SCA-4623, SCA-4627, SCA-4628 and SCA-4639 in one go, and those four PRs close as merged.

#62 vs #67 — the one real sibling pair, and it composes

I expected these to collide (both edit manager.py and test_client_cap_e2e.py). They don't:

• git merge-tree --write-tree → clean, exit 0, no conflicting paths.
• Real compose on a scratch worktree (6d3296d838): Auto-merging agent/lsp/manager.py, Auto-merging tests/agent/lsp/test_client_cap_e2e.py, exit 0.
• Clean text ≠ correct semantics, so I ran the suite on the composed tree:
  • pytest tests/agent/lsp → 139 passed (13.13s)
  • + tests/hermes_cli/test_tui_heap_sizing.py → 148 passed (12.19s)

No restack of #67 needed.

Please merge-commit, don't squash

main has required_status_checks.strict = true. Squashing this PR rewrites its 16 commits into one new SHA; #66's commits would then be in main by content but not by SHA, and #67 — built on #66 — would need a rebase and would likely conflict in manager.py. A merge commit keeps #67 mergeable.

Suggested order

1. fix(tests): stop the LSP suite writing into the operator's real agent.log #61 — independent, any time
2. fix(lsp): read a monotonic clock for idle bookkeeping, not the wall clock #62 (this PR, merge commit) — closes fix(lsp): bound concurrent language servers with an LRU cap (SCA-4389) #63, fix(lsp): read the memory limit from this process's cgroup, not the hierarchy root (SCA-4623) #64, fix(cli): size the TUI V8 heap from this process's cgroup, not the hierarchy root (SCA-4627) #65, fix(lsp): keep a wedged eviction off the caller's diagnostics budget (SCA-4628) #66
3. fix(lsp): charge each language server its own measured footprint (SCA-4688) #67 — update branch, then merge (SCA-4688)

3 merges for 7 PRs. A GraphQL sweep for unresolved review threads across #61–#72 returns empty on every PR.

Posted by the Engineer agent. Merge authority remains with the operator.