fix(hermes): bind retain work to enqueue-time session identity

[yingliang-zhang]

Problem

_make_turn_retain_job snapshotted the turn payload at enqueue time but still built the aretain_batch item at run time via _build_retain_kwargs(), which reads mutable per-session attributes:

def _job() -> None:
    item = self._build_retain_kwargs(content, ...)   # reads self._retain_tags,
                                                     #      self._observation_scopes,
                                                     #      self._retain_source, _METADATA_ATTRS …

When a session switch lands between enqueue and the writer drain (easy with retain_every_n_turns > 1 or any queue backlog), an OLD-session retain ships with the NEW session's tags / observation scopes / source. The snapshotted metadata session_id then contradicts the lineage tag session:OLD — a self-inconsistent document in the memory bank.

Fix

Build the complete item at enqueue time. The writer job only ships the frozen item:

item = self._build_retain_kwargs(..., tags=..., update_mode=update_mode)
def _job() -> None:
    resp = self._retain_batch(item, ...)

No new surface, no new state: _build_retain_kwargs / _retain_batch are unchanged; only the when moved.

Tests

tests/test_retain_identity_isolation.py — test_queued_retain_keeps_enqueue_time_item_config (port of the original TestRetainIdentityIsolation regression): gates the writer between dequeue and execution, mutates _retain_tags / _observation_scopes / _retain_source mid-flight (exactly what on_session_switch() does to a queued retain), then asserts the shipped item keeps the enqueue-time values. Fails on main, passes at this head.

Verification

Pre-fix (test only, main's _make_turn_retain_job) — RED:

  Full diff:
    [
  -     'old-tag',
  ?      ^^^
  +     'new-tag',
  ?      ^^^
        'session:session-1',
    ]
============================== 1 failed in 0.06s ===============================

Post-fix, uv run pytest tests/test_retain_identity_isolation.py -v (only the touched test file):

collecting ... collected 1 item

tests/test_retain_identity_isolation.py::test_queued_retain_keeps_enqueue_time_item_config PASSED [100%]

============================== 1 passed in 0.04s ===============================

uv run pytest tests/test_provider.py (existing suite exercising the touched path — sync_turn, flush-on-switch, append/overwrite — unchanged): 15 passed in 0.08s.

Provenance

Ported from NousResearch/hermes-agent#64499 (closed in the hindsight-move close pass; the bundled provider moved to hindsight-integrations/hermes in NousResearch/hermes-agent#119888). Original fix, audit trail and regression test by @yingliang-zhang; the mechanism was confirmed by @teknium1's automated review there ("A queued old-session retain can therefore be assembled with new-session identity/configuration"). Tracked in #4662.

Stacked PR (pre-chained 2026-09-30): the diff vs main is cumulative with #4674, #4671, #4672; this PR's own change is snapshotting the retain item at enqueue time so retains carry enqueue-time session identity. Merge top-down: 4674 -> 4671 -> 4672 -> 4673 -> 4675 -> 4676. Identical shared commits merge cleanly in any order (git dedups same-patch-both-sides).

[yingliang-zhang]

CI note: verify-generated-files fails here for a pre-existing reason — ./scripts/generate-docs-skill.sh on a clean upstream/main (7a593e8) reproduces the same skills/hindsight-docs/references/developer/oracle.md drift, so the gate is red on every PR including unmodified main. Fixed by #4678 (single-file regeneration); once it merges, this PR's gate goes green with no changes needed here.

[yingliang-zhang]

Generated-files sync commit added atop the substantive commit(s): the verify-generated-files gate runs its generators against the PR head (actions/checkout at ref: head.sha), so this branch now carries its own regenerated skills/hindsight-docs/references/developer/oracle.md plus the lint.sh ruff formatting, committed as chore: sync generated files for verify-generated-files. No substantive changes — the review surface is exactly as before.

[nicoloboschi]

Thanks for this! We no longer merge pull requests from outside the team (see CONTRIBUTING.md), so I'm closing this one.

If the problem still affects you, please open an issue with steps to reproduce and we'll take it from there.