openclaw - 💡(How to fix) Fix [Feature]: Expose durable session lineage and sessionId discovery across rotations [3 pull requests]

Summary

Expose durable session lineage and sessionId discovery helpers across rotations on top of the new SQLite runtime.

Related:

• umbrella: #79902
• active refactor: #78595

Problem to solve

The new runtime correctly treats reset/rotation/session-family behavior as a core concern, but companion consumers still lack a clean public way to resolve:

• which canonical/current session key owns a given {agentId, sessionId}
• which predecessor/successor session ids belong to the same logical family
• which rotated session should be treated as the live continuation point

Without a public seam, consumers must scan session rows or parse row blobs to recover lineage.

The relevant lineage data already exists:

• usageFamilyKey and usageFamilySessionIds are part of SessionEntry in types.ts
• ordinary session updates write those fields in session.ts
• reset and silent rotation extend them in agent-runner-session-reset.ts

The remaining gap is public discovery and selection:

• sessionId matching is alias-aware and freshness-biased in session-id-resolution.ts
• gateway resolution currently scans the combined store in session-transcript-key.ts
• run-id lookup and usage discovery reassemble related selection logic in server-session-key.ts and usage.ts
• current gateway row/event projections expose sessionId but omit lineage-family fields in session-utils.types.ts, session-utils.ts, and server-session-events.ts

Proposed solution

Expose a stable public helper surface, keyed by {agentId, sessionId}, for:

• current canonical session-key resolution
• family/lineage membership across rotations
• predecessor/successor identity lookup where available
• explicit alias/ambiguity policy and output-key-shape policy, not just a bare preferred string key

Implementation detail is flexible:

• if the existing row fields are already sufficient, expose helpers over them
• if one or two small row-level projections are needed, add those instead of forcing every consumer to parse entry_json
• this still looks like a public helper/projection gap, not a missing persistence-layer schema feature

Suggested minimum contract:

• return canonical key resolution or explicit ambiguity
• expose stable family identity and known family member sessionIds
• keep lineage ownership in core rather than consumer conventions
• allow consumers to discover canonical family membership without reconstructing it from raw session-row blobs

Alternatives considered

1. Let consumers scan session_entries

This is workable but fragile, especially as session metadata evolves.

2. Keep lineage implicit and consumer-defined

This risks each companion interpreting resets/rotations differently from core.

Impact

Affected:

• companions that preserve one logical history across multiple runtime sessionIds
• multi-entity / reset-heavy deployments
• any future first-party feature that needs accurate session-family resolution

Severity:

• high for continuity-sensitive consumers

Frequency:

• common anywhere resets, compaction rotation, or session-family tracking exist

Consequence:

• continuity bugs
• duplicate or split histories
• drift between core semantics and consumer semantics

Platform value:

• future first-party memory/search/audit features can share one continuity policy
• multi-entity and reset-heavy deployments stay consistent across consumers
• advanced plugins avoid importing gateway internals just to preserve conversation continuity

Evidence/examples

#78595 already carries lineage-oriented fields such as usageFamilyKey and usageFamilySessionIds, which strongly suggests this should be a reusable public seam rather than a private convention.

Representative anchors:

• session row schema: openclaw-agent-schema.sql
• lineage fields in type contract: types.ts
• private resolver selection policy: session-id-resolution.ts
• combined store merge/canonical-key collapse: combined-session-entries-gateway.ts

Additional information

Acceptance scenarios:

• sessionId -> current logical session resolution works after reset/rotation
• family membership is stable across multi-entity and rotated sessions
• public consumers do not need to inspect raw row blobs to preserve continuity
• ambiguity can be surfaced explicitly instead of guessed differently by each consumer
• output-key shape is canonical and reusable across transcript, run-id, and usage consumers

Non-goals:

• exposing every session-row field as a top-level normalized table
• moving consumer-specific conversation split policy into core beyond lineage truth