Slice 3: session retention that relocates + the generated session index

[aarontrowbridge]

Spec: spec-20260905-045114-session-device-lifecycle (D4). Label: afk.

Important

Problem — Session history grows forever with no lifecycle: today 1450
sessions span active work, dead scratch paths, and months of engine logs, all
in one undifferentiated list, with the only index being a hand-written vault
note. Retention is folklore practiced by SQL.
Approach — Make the practiced-by-hand model contractual: an active tail
(workspace preference, default 30 days), archived deep history (hidden from
default lists, queryable by explicit opt-in, restorable by clearing one
field — never deleted), and a session index generated from the database by a
command, carrying directory provenance. The boot fetch stays paginated so the
contract survives growth.
Approaches considered — True deletion after a horizon: rejected, deletion
is never part of retention. A fixed global cutoff: rejected, the tail length
is a workspace preference, not a constant.
Scope — in: retention policy as preference, archive visibility rules, the
generated index command, paginated fetch wiring. · out: the vault ledger
plane and agent-coordination data (separate transports, never touched by
archive — per the spec's disjointness invariant).

Acceptance Criteria

• Archiving removes sessions from default lists; an explicit archived-query opt-in lists them; clearing the archived field restores them
• Archive affects product lists only — no vault-plane or coordination-plane data changes state
• The archive cutoff is a workspace preference with default 30 days
• The index command regenerates a complete, provenance-carrying session index that matches the database (verified against a seeded DB)
• The boot list fetch remains paginated under a seeded 1000+ session store

Testing Decisions

Archive visibility matrix + index-regeneration-vs-DB check per the spec's
verification matrix (slice 3 row); pagination-under-growth test with a seeded
store.

Key Decisions

• Retention relocates; deletion is out of the vocabulary.
• The index is generated, never authored — the hand-written index that
  motivated this is the anti-pattern.

Constraints & Invariants

• Restoring an archived session re-resolves its project row by worktree even if
  the home was pruned (pairs with slice 1).

Prior Art

The existing archived-field mechanics and the hand-built 2026-09-05 index; the
open-threads skill's DB sweep as a reader of the same store.

Source

spec-20260905-045114-session-device-lifecycle (D4) · slice 3 of 4