Status controller perf: monotonic clock + drop wasted SELECT + gate type-only imports

[ajslater]

Summary

Three findings on review of codex/librarian/status_controller.py.
The controller is instantiated per librarian thread (via
WorkerStatusMixin) and called 168 times across the codebase
via status_controller.{start,update,finish} — improvements
multiply across the librarian.

F5 — time.time() → time.monotonic() for status.since_updated

The update method rate-limits DB writes via
time() - status.since_updated < _UPDATE_DELTA. Wall-clock jumps
(NTP / DST / manual clock adjustment) skew the comparison and
either drop legitimate updates or fire premature ones. Same fix
shape as PR #623 in threads.py.

F8 — Drop wasted SELECT in finish_many + dead _log_finish path

The previous shape captured an updated_statii = update_statii.values() queryset for "individual reporting", but
the downstream iteration in _finish_many_log checked
isinstance(row, Status) against values() outputs that are
always dict. Verified empirically:

>>> from codex.models.admin import LibrarianStatus
>>> from codex.librarian.status import Status
>>> sample = next(iter(LibrarianStatus.objects.all().values()[:1]))
>>> type(sample).__name__
'dict'
>>> isinstance(sample, Status)
False

So the per-status branch in _finish_many_log never fired.
For the single finish(status) call shape (every task completion
across the librarian), that's one wasted SELECT per finish.

Drop the capture (single round-trip remains, no extra SELECT) and
the now-unreachable _log_finish + per-status iteration. The
"Cleared all librarian statuses" log on the empty-statii path
is preserved.

If per-status finish logs are wanted in the future, iterate
positive_statii.values() directly — those genuinely yield
Status instances.

F1 — Gate type-only imports behind TYPE_CHECKING

After F8 removed the runtime Status use, four imports become
type-hint-only: Iterable, Queue, Logger, Status. Added
from __future__ import annotations to make the annotations
forward-references at runtime so the imports move into a
TYPE_CHECKING block.

codex.librarian.status_controller no longer pulls in
multiprocessing.queues at all — verified:

import codex.librarian.status_controller
import sys
assert 'multiprocessing.queues' not in sys.modules  # passes

Same shape as PR #623; saves ~14 ms cold whenever this is the
triggering import.

Net change

• -22 LOC (mostly the dead _log_finish / _finish_many_log
  removal)
• One fewer SELECT per finish_many call
• No more wall-clock-jump bugs in update rate-limiting
• multiprocessing.queues no longer transitively loaded from
  this module

Test plan

• make lint-python clean.
• make test-python clean (26 tests pass).
• import codex.librarian.status_controller no longer loads
  multiprocessing.queues (verified via sys.modules).
• values() of a LibrarianStatus queryset yields dict,
  never Status (confirms F8's dead-code claim).
• On a populated librarian: trigger CoverCreateAllTask etc.,
  watch the librarian log. The status flush rate (per _UPDATE_DELTA = 5s) should be unchanged — only the underlying clock source
  switched. The "Created N covers in Xs" log line from the cover
  thread itself still fires (that one was always there; the
  status-controller's never-fired duplicate is gone).

🤖 Generated with Claude Code