refactor(gateway): extract history-build helpers from run.py (slice 13 of #54962)

[andrexibiza]

Related #54962 #55138 #77452 #77706

What / Why

Slice 13 of the gateway/run.py god-file unpacking (#54962): extracts the history-build cluster into a new gateway/history_helpers.py module — pure move, zero behavior change.

Moved (byte-identical, AST-verified against origin/main):

• _uses_telegram_observed_group_context
• _select_cached_agent_history
• _wrap_current_message_with_observed_context
• _TELEGRAM_OBSERVED_CONTEXT_PROMPT_MARKER (exclusive to the moved function)
• _OBSERVED_GROUP_CONTEXT_HEADER (exclusive to the moved function)
• _CURRENT_ADDRESSED_MESSAGE_HEADER (exclusive to the moved function)

gateway/run.py keeps a module-attribute import so gateway.run.<name> stays green for existing callers and tests — no re-exports, no test churn.

Why this matters to users: no user-visible behavior change. This is pure refactor — the same transcript-replay, observed-context wrapping, and cached-history selection logic runs from a smaller, focused module so the 26.8k-line god file becomes reviewable and maintainable.

Scope note (honest)

_build_gateway_agent_history stays in gateway/run.py for now. It depends on two helpers that are being extracted in parallel by sibling slices that have not merged yet:

• _strip_auto_continue_noise → gateway/auto_continue_helpers.py (PR refactor(gateway): extract auto-continue helpers from run.py (slice 8 of #54962) #77706)
• _build_replay_entry → gateway/resume_replay_helpers.py (PR refactor(gateway): extract resume/replay helpers from run.py (slice 3 of #54962) #77452)

Importing them cross-PR would break import gateway.run today (modules don't exist on main). Once those PRs merge, this function can be moved as a follow-up with zero further change to its body.

The Slack-ignored-channel helpers (_slack_*, _csv_or_list_to_set) and _message_timestamps_enabled adjacent to this cluster were not touched — they belong to other slices.

How to test

python -c "import gateway.run"            # module-attribute import keeps run.py green
python -m pytest tests/gateway/test_auto_continue.py \
  tests/gateway/test_message_timestamps.py \
  tests/gateway/test_replay_entry_fields.py \
  tests/gateway/test_stale_confirmation_expiry.py -q
git diff --check

Verification

• AST-fidelity gate: all moved functions byte-identical to origin/main (ast.dump equality)
• Orphan scan on post-extraction run.py: no orphaned references
• import gateway.run + import gateway.history_helpers OK
• Targeted suites: 19 passed (test_auto_continue, test_message_timestamps, test_replay_entry_fields, test_stale_confirmation_expiry)
• git diff --check clean; scripts/check-windows-footguns.py clean
• Constants verified exclusive (2 hits each: definition + single use inside moved functions)

Shrink

gateway/run.py: 26,823 → 26,725 lines (−98 net; −104 moved, +6 import block). New module: 77 lines.

Part of #54962
Part of #55138

Part of #78207
Part of #78647

[andrexibiza]

FILE-LIST coordination — history-cluster adjacency with #86050.

#86050 (fix(gateway): preserve reasoning-only assistant turns on reload) adds a third dispatch arm inside _build_gateway_agent_history (after elif content:) plus the _has_replay_payload helper beside _build_replay_entry. This slice moves the history-build cluster that follows the builder. The regions are adjacent, not overlapping — the new arm lives inside the builder (which stays in run.py), and this slice's move begins at the builder's closing context — so git context matching resolves both merge orders. If #86050 lands first, its added lines shift the closing-return context this slice anchors on; a routine rebase handles it (this slice is already stale against current main independently).

Note: _has_replay_payload belongs with the replay contract in #77452's extraction, not the history cluster — no symbol move is needed here.

[spfcraze]

This was generated by AI during triage.

Summary:
The _select_cached_agent_history extracted into gateway/history_helpers.py is the stale pre-v0.20.1 version; main has since made the same function require a non-ephemeral _db_persisted row, so this slice re-homes the length-only copy rather than the FTS-corruption guard main now uses.

Problems:

• gateway/history_helpers.py:49 keeps the live transcript whenever len(live_history) > len(persisted_history), the length-only behavior current when the branch diverged (2026-08-03).
• 720f044 (v0.20.1, 2026-08-13) rewrote the same function on main: it now also requires at least one non-ephemeral unpersisted row (_is_ephemeral_scaffolding from run_agent.py, checked against _db_persisted) before returning the live list, so an all-durable longer list is no longer retained.
• The other two moved functions and the three constants are byte-identical to current main; this one is not.

Solution:
On the rebase this CONFLICTING branch needs against current main, carry main's current _select_cached_agent_history body (the _db_persisted / _is_ephemeral_scaffolding check) into gateway/history_helpers.py rather than the length-only copy now in the new module.

Evidence

no deterministic fact backs this claim — model belief, not executed or read evidence

---

Checked against dd7fbe3 — the tip of fix/gateway-history-helpers when this was written — and c896c09, main at the same moment.