feat(sessions): support custom display names

[alx-xo]

Problem

Kit derives a session title from the first useful user message. This helps identify sessions in kit sessions and the TUI /sessions picker, but generated titles are not always memorable or descriptive.

Users should be able to assign persistent display names to sessions so they can easily identify and resume the correct session later.

Current behavior and reproduction

1. Start Kit's TUI in a workspace containing durable sessions.
2. Run /sessions.
3. Observe that sessions can be listed and resumed, but their generated titles cannot be renamed.
4. Run kit sessions for the same workspace.
5. Observe that the CLI lists generated titles but provides no command for assigning a persistent display name.

Expected behavior

Users can assign, replace, and clear persistent session display names from both the TUI and CLI. Session listings prefer the custom display name and fall back to Kit's generated title when no custom name exists.

Environment

kit 0.1.114
Darwin
arm64

Surfaces involved: Kit TUI and kit sessions CLI.

Related work

• feat(sessions): list and resume past sessions #51 introduced listing and resuming past sessions.

Proposed behavior

Add an optional, user-defined display name for durable sessions.

• A custom display name overrides the generated title in session listings.
• The immutable session ID does not change.
• Clearing the display name restores the generated title.
• Display names are workspace-scoped and persist across Kit processes and restarts.
• Active sessions can be renamed.
• Concurrent renames use last-write-wins behavior.

TUI

Extend the existing /sessions picker:

• ↑ / ↓: select a session.
• Enter: resume the selected session.
• R: rename the selected session using a simple inline prompt.
• Submitting an empty name offers to clear the custom name.
• Esc: cancel renaming or close the picker.
• After saving, keep the picker open, preserve the selection, and refresh the displayed name.
• Show the relevant controls in the picker footer.
• Display the custom name when present; otherwise, fall back to the generated title.

A richer session detail menu is explicitly out of scope for the initial implementation.

CLI

Preserve the existing listing command:

kit sessions

The listing should show each session’s custom display name when one exists and otherwise show its generated title.

Add commands to set, replace, and clear a display name:

kit sessions rename <session-id> "OAuth token bug"
kit sessions rename <session-id> --clear

Workspace selection should remain supported:

kit sessions --root /path/to/project
kit sessions rename <session-id> "OAuth token bug" --root /path/to/project
kit sessions rename <session-id> --clear --root /path/to/project

Validation

• Trim leading and trailing whitespace.
• Allow Unicode.
• Limit names to 100 characters.
• Reject line breaks and terminal control characters.
• Truncate long names only for TUI presentation; retain the full value in storage and CLI output.
• Require explicit --clear in the CLI.
• In the TUI, confirm before treating an empty value as clearing the name.

Persistence

Prefer a small, workspace-scoped metadata sidecar stored alongside the durable session rather than modifying the append-only transcript.

This should:

• Allow active sessions to be renamed without acquiring their transcript mutation lock.
• Use atomic writes.
• Treat absent metadata as an unnamed legacy session.
• Avoid hiding an otherwise valid session when metadata is malformed.
• Preserve custom names through existing session discovery and migration paths.
• Follow the repository’s persistent-artifact schema and compatibility requirements.

Acceptance criteria

• Users can rename a selected session from the /sessions picker.
• Users can set or replace a name with kit sessions rename.
• Users can clear a name from both the TUI and CLI.
• TUI and CLI listings prefer the custom name and fall back to the generated title.
• Renaming does not change the session ID or transcript.
• Names persist across restarts and session resumes.
• Active sessions can be renamed.
• Concurrent renames are safe, with the last completed write winning.
• Invalid names produce clear, actionable errors.
• Missing or malformed name metadata does not hide valid sessions.
• Tests cover listing, renaming, clearing, validation, active sessions, concurrent writes, legacy sessions, malformed metadata, and writer output.
• User documentation and command help are updated.
• Kit receives the required patch-version bump.

Out of scope

• A session detail screen or context menu.
• Editing the generated title itself.
• Changing session IDs.
• Viewing full transcripts from the CLI.
• Deleting, tagging, grouping, or searching sessions.

[alx-xo]

@danielkov 🙏