DSH plugin session candidate names: label vs displayTitle
In DSH plugin, a candidate name is not arbitrary: label walks a title-to-id fallback chain, displayTitle prefers a subagent's durable creation label, and the canonical mention prefers displayTitle. Understand those three sources and "it shows an id" stops looking like a bug.
DeepSeek Harness: Three names for one session
Three names mean three sources, not three copies of data. (source) Breaking it down:
sessionId opaque identity, always present
label latest title, equals sessionId when missing
displayTitle subagent creation label, optional
A user may see any of them depending on whether the session has a title, whether it is a subagent, and which field the host picked.
The priorities are not accidental: identity always uses the id, display prefers readable text, and mentions choose the most stable readable text.
DeepSeek Harness: Where label comes from
Look for the latest log-backed title first, fall back to the id otherwise. (source) Two levels only:
- The session has a title —
labelequals that title; - The session has none —
labelequals the opaque session id.
The official comment is explicit about the second level: fall back to the opaque session id. Seeing an id string is designed behavior, not a broken projection.
The benefit is that a candidate always has displayable text, so hosts never need a "name is empty" branch.
DeepSeek Harness: When displayTitle wins
It wins for subagents, because a creation label says more about role than a title says about content. (source) The rule: when a durable subagent creation label exists, displayTitle uses it; otherwise the field is absent.
A comparison makes it concrete:
| Session | label | displayTitle |
|---|---|---|
| Ordinary session with a title | Fix login timeout | none |
| Subagent with a creation label | Fix login timeout | reviewer |
| Untitled ordinary session | 8f3c… (id) | none |
Row two explains why both fields exist: the title describes what is being done, the creation label describes the role doing it. In a picker, the role is often easier to recognize.
DeepSeek Harness: Display vs mention: two different choices
The list may choose freely; a mention follows what the service returned. (source) Division:
- Primary list title:
displayTitlewhen present, otherwiselabel; - Subtitle or source hint:
labelor cwd; - Mention: the canonical text carried by the candidate — never hand-built.
The official description says remote candidates mark the canonical mention with displayTitle when it exists. That means the text inserted into the draft may differ from the label shown in the list.
That is not an inconsistency: a mention needs stable, readable, parseable text, while a list can combine fields to fit the UI.
DeepSeek Harness: Why names come from projections
Because discovery runs at typing frequency and cannot scan logs each time. (source) The official comment states that titles and subagent labels come only from projection reads, falling back to the id when neither exists.
Two observable consequences follow:
- Right after a rename, the candidate may still show the old name;
- Sessions without a projection yet display the id.
Both are expected. The way to tell whether something is wrong is not name freshness but whether it updates after the projection refreshes.
If it never updates, inspect projection generation rather than changing the candidate fallback; replacing projection reads with log scans buys correctness at a large performance cost.
DeepSeek Harness: A verification matrix
Three session types, three expectations, one pass. (source) Matrix:
| Session type | Expected label | Expected displayTitle |
|---|---|---|
| Ordinary session with a title | Title | none |
| Subagent with a creation label | Title or id | Creation label |
| Untitled ordinary session | id | none |
Add one dynamic check: rename a session, wait for the projection to refresh, and confirm label changes while displayTitle does not.
Three static cases plus one dynamic case prove the fields are not swapped.
Write the selection order as fixed branches: use displayTitle if present, otherwise label, which has already fallen back to the id. Do not decide ad hoc by "whichever is non-empty", or the same session will show two different names in the list and on the reference card.
If a host caches candidates, keep the cache shorter than the projection refresh interval; otherwise a stale name outlives the lag it came from.
Names answer "can I recognize it"; the next question is "can I find it". Read why DSH plugin candidates search metadata only; for ordering, read DSH plugin candidate ranking and self exclusion; for the wider picture, read how DSH plugin implements session references.
Sources: DeepSeek Harness reference - Session references, session-reference/src/types.ts
FAQ
Because DSH plugin has no title for that session yet. DSH plugin prefers the latest log-backed title for label and falls back to the session id; seeing an id means the fallback worked, not that data is broken.
They have different sources in DSH plugin. label comes from the session title, while displayTitle prefers the subagent's durable creation label. One describes content, the other describes the role at creation.
The DSH plugin mention uses displayTitle when present. label stays in the candidate for other display uses.
Because DSH plugin names come from projection reads rather than a log scan on every keystroke. DSH plugin only reads projections at typing frequency, so a title change appears after the projection refreshes.
Related Terms
- label
- label is a session candidate's display name; it prefers the latest log-backed title and falls back to the opaque session id.— DeepSeek Harness reference - Session references
- displayTitle
- displayTitle prefers a subagent's durable creation label and, when present, also marks the canonical mention.— DeepSeek Harness reference - Session references
- projection read
- A projection read obtains titles and labels from session projections instead of scanning full logs, which suits discovery at keystroke rate.— DeepSeek Harness reference - Session references
- subagent creation label
- A subagent creation label is a role label written when the subagent is created and persisted so sibling subagents can be told apart.— DeepSeek Harness reference - Session references
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/types.ts· deepseek-ai