fix(history): isolate consolidation sessions

[Premshay]

Problem / Motivation

History consolidation uses the shared _bg session, coupling long memory extraction to latency-sensitive background micro-jobs.

Why it matters

Lightweight maintenance queues behind consolidation even though it neither needs its context nor its admission path.

What changed

Use a persistent stateless _consolidate session with its own lifecycle and telemetry classification, while preserving current _bg behavior.

Pattern harvest

Rule candidate: long-running maintenance needs a distinct admission identity from latency-sensitive background work.

Tests

python -m pytest -q test/metrics/test_startup_channel_attrs.py test/test_background_turn_accounting.py test/test_history.py — 389 passed.

What changed (motivation → approach → change)

N/A — covered by the existing ## What changed section.

Manual verification

N/A — focused automated coverage is sufficient.

Related Issues

N/A.

Checklist

• Existing tests pass and regression coverage is included.
• Self-review completed; code follows project style guidelines.
• Documentation updated where applicable.
• No secrets, credentials, or internal references in the diff.

Contribution License Agreement

N/A — template placeholder; no CLA wording is supplied.

[github-actions]

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed f7e44aaf5366b19a6d6cc638cda3857dd7a7bec1 via the fork AI-review pipeline; updated in place on each push.

Review details

FINDING -- src/kiro_crew/history_consolidation.py:1957 -- in-method from kiro_crew.session import CONSOLIDATE_KEY violates top-level-imports -> Fix: pass the fixed session key directly and remove the local import.
[GPT-REVIEWED] f7e44aa

[github-actions]

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of f7e44aaf5366b19a6d6cc638cda3857dd7a7bec1 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

All design questions are answered. One real gap remains: docs/system-specs/modules/session.md — the owning spec for session keys per the AGENTS.md routing table — still documents consolidation on _bg (the "Shared by" list, recycle callers, and the Resource Budget table), and the new permanently-resident _consolidate process is absent from that budget. The PR updated only history.md. Everything else checks out: the contention problem is real (auto-title, plan-rephrase and consolidation share one _bg semaphore), the fix follows the existing HEARTBEAT_KEY precedent, the generalized recycle_background is genuinely key-agnostic, the two remaining _bg call sites in the consolidator are the cheap micro-turns that belong there, and the change is cleanly revertible with no persisted state.

Design-Verdict: CONCERNS

Sound split along an existing precedent, but the owning session spec still documents the old _bg topology and omits the new resident process.

Watch

• docs/system-specs/modules/session.md (the AGENTS.md-designated owning spec for session keys) still lists consolidation-adjacent work as _bg-shared and its "Resource Budget (Gateway Mode)" table has no row for _consolidate — a persistent, never-idle-expired kiro-cli process this PR adds. Future contributors sizing gateway footprint or reasoning about _bg contention from that spec will reason from a wrong process model; session.py's module docstring ("Protected keys: _bg and _hb") drifts the same way.
  Clears when: session.md's Background Session section and Resource Budget table (and the session.py docstring) are updated in this PR to include _consolidate.

Suggestions

• Consider letting _consolidate idle-expire instead of adding it to _PERSISTENT_KEYS: consolidation is latency-insensitive by this PR's own framing, get_or_create recreates the stateless session lazily, and you avoid pinning a third resident kiro-cli process through long idle periods.

[DESIGN-REVIEWED] f7e44aa

[github-actions]

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed f7e44aaf5366b19a6d6cc638cda3857dd7a7bec1 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] f7e44aa

[github-actions]

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of f7e44aaf5366b19a6d6cc638cda3857dd7a7bec1 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

All mechanisms verified. I have what I need: the defect's provenance, the existing _TELEMETRY_EXACT_KEYS mechanism, the consumer counts for the new parameters, and the persistence cost. Emitting the review.

First-Principles-Verdict: CONCERNS

The "consolidation" telemetry label re-implements _TELEMETRY_EXACT_KEYS via a new generic underscore branch, and the session's immortality in _PERSISTENT_KEYS is never justified.

Not justified as shipped

• Item 2 — oversized: nothing in the description says why the session must never idle-expire; expiry + cold start on the next ≥10-message batch removes the same harm.
• Item 3 — duplicate: _TELEMETRY_EXACT_KEYS (src/kiro_crew/messaging/link.py:122) already labels singleton keys _bg/_hb; one dict entry does this job.
• Items 4, 5 — one consumer, generalized: of 6 background_turn call sites, only history_consolidation.py:1960 passes session_key; only that path passes recycle_background's new args.

What this change ships

Intent: stop long history-consolidation turns and short background micro-jobs from queueing on one shared session — a FIX.

1. Consolidation's extraction turn runs on its own _consolidate session, off _bg — justified
2. That session, once created, is never idle-expired (a third permanently resident provider process) — oversized
3. Consolidation turns get their own "consolidation" metric label — duplicate of src/kiro_crew/messaging/link.py:122
4. background_turn gains a session_key parameter — one consumer, generalized
5. recycle_background gains session_key/agent parameters — one consumer, generalized
6. _consolidate skips resume across restarts — justified
7. history.md spec updated in the same commit — justified

Watch

• The queueing harm is asserted only by the description ("Lightweight maintenance queues behind consolidation") — no issue, no measurement; the base instrumentation comment it deletes was aimed the opposite way ("queue contention behind other _bg consumers like chat_nav link-preview"). The semaphore coupling is real, so the fix is mechanism-level either way.
  Clears when: a logged queue-wait measurement or linked report names either direction.
• _dedupe_judge's docstring (history_consolidation.py:1418) still justifies its no-set_model rule by "the BACKGROUND_KEY session is shared with consolidation" — this PR ends that sharing and leaves the pin's premise false.
  Clears when: that comment no longer rests on the shared-with-consolidation premise.

Subtractions

• Delete the ("_consolidate", "consolidation") prefix row and the prefix.startswith("_") branch in telemetry_channel_of; add one _TELEMETRY_EXACT_KEYS entry instead — the branch serves exactly 1 prefix (grep: _TELEMETRY_LOCAL_PREFIXES).
• Drop CONSOLIDATE_KEY from _PERSISTENT_KEYS (session.py) — idle expiry reclaims the process between consolidations; this also keeps session.py:75 ("_bg and _hb") true.

[FIRST-PRINCIPLES-REVIEWED] f7e44aa

[bolichen97]

Rebased onto main 6fbb06bc by a maintainer as part of the 2026-09-08 open-PR audit. Old head 7ae89048, new head f7e44aaf.

Clean rebase — no conflicts. The diff is unchanged (9 files, +102/-30); the only drift main introduced was the removal of the else: LLMProvider = Any fallback in session_background.py, ~500 lines from this PR's hunk, so main's version now stands.

Gates run locally on changed files only: isort pass, flake8 pass, pytest pass (test_background_turn_accounting.py, test_startup_channel_attrs.py, session tests, consolidation tests — 203 passed). black flags test/metrics/test_startup_channel_attrs.py, which is pre-existing (it is in .github/black-baseline.txt and main's own copy fails too).

Please review the rebase. A maintainer push makes the maintainer the last pusher, so a second approver is needed under the repo's last-push rule. Reply if anything looks wrong.