feat(sleep-cycle): memory budgeting — per-agent warm_tier hard cap (Sprint E)

[salishforge]

Summary

Adds memory budgeting per the ROADMAP Phase 2 milestone: "Hard limits on warm-tier size per agent with intelligent eviction. When an agent reaches capacity, the lowest-value memories are archived, not the oldest."

Opt-in via `WARM_TIER_MAX_PER_AGENT` env var. Default (unset or 0) = no cap, existing deployments unaffected.

Design

• Cap is per-agent, cross-namespace. Per-namespace caps are a future enhancement.
• Value = importance. Sleep cycle Phase 1 already computes importance as a weighted blend (recency, frequency, centrality, reflection, stability). Reusing it avoids duplicate scoring.
• Graduated memories are NOT exempt. Cap is a hard limit; graduation affects retrieval scoring, not budgeting. Documented inline.
• Runs as Phase 2b in the sleep cycle, immediately after threshold-based eviction (Phase 2). Kept separate from Phase 2 because the two have different invariants — threshold is "absolute below X", capacity is "relative rank bottom N" — and the log events / result fields are independently meaningful.
• Target state: count exactly equals cap. Simple invariant.

No schema migration

The existing `warm_tier_importance_idx (agent_id, importance DESC)` already supports the bottom-N-by-importance query efficiently.

Changes

• `src/sleep-cycle.ts` — new `phaseCapacityEviction` method, called after `phaseTriage`. Uses the same CTE pattern as threshold eviction (`WITH candidates / moved / deleted`), preserving namespace on cold rows.
• `src/types.ts` — `SleepCycleConfig.warmTierMaxPerAgent?: number`; `SleepCycleResult.capacity_evicted?: number` (optional, set only when cap configured).
• `src/server.ts` — parse `WARM_TIER_MAX_PER_AGENT` env var.
• `.env.example` — doc with opt-in + lowest-importance-first semantics.

Tests (`tests/memory-budgeting.test.ts`, 307 lines, 7 cases)

1. Cap disabled (default) → no evictions.
2. Below cap → no evictions.
3. Exactly at cap → no evictions.
4. Over cap → evicts exactly (count - cap) rows, bottom-importance first, with namespace preserved in cold_tier.
5. Cross-namespace cap — per-agent applies across all namespaces.
6. Threshold + capacity interaction — both passes run, counts sum correctly.
7. Graduated row gets capacity-evicted when it is lowest-importance.

All tests use explicit timestamps — no sleeps.

Test plan

• CI `type-check`, `lint`, `build` pass
• CI `test-integration` runs the new budgeting suite
• Existing sleep cycle tests still pass (behavior unchanged when `warmTierMaxPerAgent` is unset/0)

Out of scope

• Per-namespace caps — simpler per-agent cap first per ROADMAP wording.
• Dynamic cap adjustment based on memory health — belongs in Sprint F adaptive scheduling.
• Hot_tier caps — hot_tier drains via consolidation; only warm_tier needs budgeting.