hermes - 💡(How to fix) Fix [Feature]: persist session kind/provenance metadata [1 participants]

Problem or Use Case

Hermes has several workflows that create sessions which are not all equivalent from a consumer/UI perspective: normal user-facing sessions, delegated/subagent sessions, background or runner-created sessions, branches/forks, and continuation/compression-related sessions.

Today downstream consumers appear to have to infer those semantics from indirect signals such as source, model, blank titles, parent_session_id, message count, or model_config. Those are brittle:

• a model name is not a reliable proxy for whether a session is auxiliary;
• parent_session_id can represent multiple different relationships, including delegation, branches/forks, and continuation/compression lineage;
• blank titles or tiny transcripts can be useful hints, but are not a stable data contract;
• consumers such as session lists, session_search, resume flows, dashboards, or custom viewers need different visibility/grouping behavior.

This makes it hard to answer basic questions like “is this a primary session I should show in the main resume list?” vs “is this a child/background/auxiliary session that should be grouped under its parent or hidden by default?” without encoding fragile heuristics in every consumer.

Proposed Solution

Add explicit, persisted session provenance/kind metadata at session creation time. A minimal additive version could be something like:

session_kind TEXT DEFAULT 'main'

or the equivalent in the existing session metadata/model-config storage, as long as it is exposed consistently to session readers.

Suggested enum-like values could include:

• main — normal user-facing session; default for legacy/unspecified rows;
• auxiliary — delegated/subagent/tool-created helper session;
• background or cron — autonomous/background runner session;
• branch — user-visible fork/branch session;
• continuation — continuation/compression/resume lineage where applicable.

The exact names are less important than having a first-class, stable field that producers set and consumers can rely on.

Potential propagation points:

• CLI/TUI/gateway/API-created user sessions default to main;
• delegate_task/subagent creation marks child sessions as auxiliary;
• /branch or /fork marks child sessions as branch;
• cron/background job sessions can mark themselves as background/cron;
• continuation/compression flows can mark relationship type separately from generic parent linkage.

Optional richer metadata, e.g. session_meta, could record creator tool, parent relationship reason, display defaults, or originating workflow, but consumers should not have to parse an opaque blob just to determine the top-level kind.

Acceptance Criteria

• New sessions have an explicit kind/provenance value persisted with the session record.
• Existing sessions remain readable without migration breakage; missing values default to main or a well-documented legacy fallback.
• Delegated/subagent sessions are distinguishable from branches and continuations without relying only on parent_session_id.
• Session readers/search/listing APIs expose the kind so UIs and tools can filter, group, or label sessions consistently.
• Tests cover legacy rows, normal sessions, delegated sessions, and branch/continuation-like sessions.

Alternatives Considered

Viewer-specific heuristics

Consumers can try to infer auxiliary sessions from combinations like model name, blank title, tiny transcript, or parent linkage. This works only as a temporary workaround and will keep drifting as new providers/workflows are added.

Boolean is_auxiliary

A boolean would solve one case but would not distinguish branches, continuations, background jobs, and future role/team sessions. An enum-like session_kind/provenance field is more extensible while still being simple.

Opaque metadata only

A generic metadata blob is useful for extra context, but a stable top-level kind is better for common list/search/resume behavior.

Related Context

This is related to, but narrower than:

• #15153, which discusses persistent canonical role sessions for role/team workflows.
• #20856, which highlights fragility around branch/fork lineage and visibility in session listings.

This issue is intentionally smaller in scope: persist a simple session-kind/provenance marker so session consumers do not have to infer user-facing vs auxiliary/background semantics from model names, blank titles, or parent links.

Feature Type

Other / developer experience / session metadata reliability.

Scope

Medium. The schema/data-model change can be small and backward-compatible, but the value needs to be propagated from multiple session creation paths and exposed consistently to consumers.

Non-goals

• Do not require consumers to hide auxiliary/background sessions by default.
• Do not remove or redefine parent_session_id.
• Do not require a breaking schema/API migration.
• Do not solve the full canonical-role workflow described in #15153.