feat(sessions): list and resume past sessions (#51)

Author: danielkov

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "kit"
-version = "0.1.105"
+version = "0.1.106"
 edition = "2024"
 rust-version = "1.94.0"
 publish = false

Cargo.toml

@@ -99,12 +99,15 @@ remain resumable and are copied to the global location on resume. When reported
 context use reaches 80% of the model's window, Kit automatically checkpoints older
 history while preserving bootstrap instructions and a tool-safe recent tail; the
 replacement is persisted for resume.
-The session id is shown in the header. Resume it with:
+The session id is shown in the header. List workspace sessions or resume one with:
 
 ```sh
+cargo run -- sessions --root /path/to/project
 cargo run -- tui --root /path/to/project --resume <session-id>
 ```
 
+`kit sessions` prints the shared newest-first session catalog with ID, updated time, title, and preview.
+
 A per-session filesystem lock prevents two live Kit processes from mutating the
 same transcript. If a crashed process left its lock file behind, add `--force`;
 Kit will reclaim it only when no live process still holds the OS lock.
@@ -583,6 +586,7 @@ child process with `KIT_RUNTIME_EVENTS=1`; other ACP hosts never see them.
 | --- | --- |
 | `⏎` | send |
 | `/new` | start a fresh persisted session (`/new prompt` sends its first prompt) |
+| `/sessions` | choose a workspace session and resume it |
 | `/compact` | compact context now (`/compact prompt` starts the next turn with `prompt`) |
 | `/effort` | choose `default`, `low`, `medium`, or `high`; Tab toggles saving the default |
 | `/model` | open the searchable provider-grouped model picker |
@@ -607,7 +611,7 @@ no credentials — the client exits with that agent's own last diagnostic rather
 than waiting on a handshake that will never finish.
 
 `/new` clears the visible transcript but leaves the prior persisted session
-intact and resumable. `/model` switches the main agent and compactor in the same
+intact and resumable. `/sessions` opens the newest-first workspace catalog; Enter resumes the selected session through the same path as `/resume <session-id>`. `/model` switches the main agent and compactor in the same
 live ACP session at the next safe turn boundary; it does not rewrite transcript
 history or restart the child process. The picker groups models by provider and
 ranks fuzzy matches as you type. Press `tab` before confirming to also replace the `provider`

README.md

@@ -10,12 +10,15 @@ Start an interactive session at a project root with the installed binary:
 kit tui --root /path/to/project
 ```
 
-Resume the ID shown in the header:
+List sessions for the workspace, then resume the ID shown in the header or catalog:
 
 ```sh
+kit sessions --root /path/to/project
 kit tui --root /path/to/project --resume <session-id>
 ```
 
+The catalog requires an existing directory and is workspace-filtered and newest-first. It reports each durable ID and updated time. The title comes from the earliest retained useful user text so compaction does not rename a session; the preview describes the current retained history. Display metadata removes terminal controls and Unicode default-ignorable formatting characters.
+
 A session ID must be 1–128 ASCII letters, digits, `-`, or `_`. `kit prompt` uses the same durable sessions: it prints `session_id: <id>` after its answer, and that ID can be continued by either `kit prompt --resume <session-id>` or `kit tui --resume <session-id>`.
 
 ## TUI keys, prompt editing, and navigation
@@ -72,12 +75,13 @@ At an idle, non-empty editor, `Ctrl+C` clears the prompt instead of unexpectedly
 
 ## Manage sessions and compact from the TUI
 
-The TUI handles `/new`, `/resume`, `/close`, `/model`, and `/effort` as exact local slash-command tokens. It also discovers agent commands through ACP and highlights them without interpreting them locally:
+The TUI handles `/new`, `/resume`, `/sessions`, `/close`, `/model`, and `/effort` as exact local slash-command tokens. It also discovers agent commands through ACP and highlights them without interpreting them locally:
 
 ```text
 /new
 /new Start by reviewing the tests
 /resume <session-id>
+/sessions
 /close
 /compact
 /compact Continue with the migration
@@ -86,7 +90,7 @@ The TUI handles `/new`, `/resume`, `/close`, `/model`, and `/effort` as exact lo
 /effort high
 ```
 
-These local commands are available only while the session is idle. `/new` closes the current session and starts a fresh persisted session. It clears the visible transcript but does not delete or alter the previous session, which remains resumable by its ID. Text following `/new` becomes the new session's first prompt. `/resume <session-id>` closes the current session, resumes the requested durable session, and replays its transcript. `/close` closes the current session and exits the TUI.
+These local commands are available only while the session is idle. `/new` closes the current session and starts a fresh persisted session. It clears the visible transcript but does not delete or alter the previous session, which remains resumable by its ID. Text following `/new` becomes the new session's first prompt. `/resume <session-id>` closes the current session, resumes the requested durable session, and replays its transcript; selecting the already-active ID is a no-op. `/sessions` opens a visible newest-first selector for the same workspace; Up and Down move, Enter uses the existing resume flow, and Esc closes the dialog. `/close` closes the current session and exits the TUI.
 
 `/model` opens the model selector. `/effort` opens the advertised ACP reasoning-effort selector; `/effort default|low|medium|high` selects directly. In either dialog, Tab toggles saving the selection to `~/.kit/config.toml`, Enter selects, and Esc closes. Saving `default` removes top-level `reasoning_effort`; other values update it without replacing unrelated TOML. A new or resumed process starts from the resolved CLI/TOML default unless the selection was saved.
 
@@ -97,24 +101,26 @@ The ACP server advertises `compact` for every new session. The TUI submits `/com
 Kit stores durable JSONL transcripts, locks, and session-associated fatal error logs in:
 
 ```text
-~/.kit/sessions/<session-id>.jsonl
-~/.kit/sessions/<session-id>.lock
+~/.kit/sessions/w-<workspace-hash>/<session-id>.jsonl
+~/.kit/sessions/w-<workspace-hash>/<session-id>.lock
 ~/.kit/errors/<session-id>/<event-id>.json
 ```
 
+The workspace hash is the BLAKE3 digest of the canonical workspace-root path. It keeps identical session IDs in different workspaces in separate storage directories.
+
 Fatal error records use their own versioned JSON schema and are not transcript content. Schema v2 adds optional structured transport diagnostics; schema v1 records remain readable. Transport diagnostics contain only bounded, allowlisted request/stream stage, retry, attempt, the provider's strictly validated `x-request-id` value, reqwest classification, and typed Hyper, HTTP/2, and I/O fields. Unknown or truncated source chains are identified without storing source text. Kit never stores raw error display/debug text, arbitrary headers, prompts, tool arguments, response bodies, credentials, URLs, or peer-controlled HTTP/2 debug text in these records. Files are written atomically with owner-only permissions on Unix, and Kit retains the newest 50 records per session. Cancellation is not a fatal error and does not create a record. When persistence succeeds, local prompt and ACP terminal errors include the log path; A2A records stay server-local.
 
 `HOME is unset; cannot locate durable sessions` means Kit cannot determine this directory. Set `HOME` to the intended home directory before starting Kit.
 
 Transcript records are versioned and have consecutive generations. Transcript schema v3 records the canonical workspace root so ACP discovery and resume cannot expose a session to another project; schema v1 and v2 records remain readable and gain that binding when they are next resumed. Normal items are appended and synced to disk before they are accepted into the in-memory conversation. Operations such as compaction append a replacement record; older records remain in the JSONL file, but readers treat the latest valid replacement as the canonical transcript.
 
-Older sessions under `<root>/.kit/sessions` remain readable. The first resume validates and copies a legacy transcript into `~/.kit/sessions`; a live legacy lock produces `legacy session is actively locked by another Kit instance ...; stop it before resuming with this Kit version`. When both locations contain the ID, the global transcript is preferred.
+Older sessions stored directly under `~/.kit/sessions` or under `<root>/.kit/sessions` remain readable. On resume, Kit compares workspace-hashed, workspace-bound global, and project-local candidates and selects the history that descends from the others; equivalent histories prefer the workspace-hashed copy, while divergent histories fail instead of choosing silently. An old global transcript without workspace metadata is a fallback only for an explicit resume when no workspace-hashed or project-local candidate has that ID. The first successful resume copies the authoritative history into the workspace-hashed directory and leaves redirects in applicable legacy files. A live legacy lock produces `legacy session is actively locked by another Kit instance ...; stop it before resuming with this Kit version`.
 
 ### ACP session loading
 
-ACP v1 clients restore a closed durable session with `session/load`. The v1 endpoint advertises only the protocol's top-level `loadSession` capability; it does not advertise `session/resume` or `session/list`. ACP v2 clients use `session/list` and `session/resume` instead. Both versions use the exact durable session ID and return the same model and reasoning configuration options as `session/new`.
+ACP v1 clients restore a closed durable session with `session/load` and discover sessions with the optional `session/list` capability. ACP v2 clients use `session/list` and `session/resume`. Both list variants use the same newest-first catalog, optional exact-cwd filter, and opaque `offset:<n>` pagination cursors, and return titles and RFC 3339 updated times. Both versions use the exact durable session ID and return the same model and reasoning configuration options as `session/new`.
 
-Session discovery and restoration are isolated to the server's canonical workspace root. A requested workspace must match that root, and additional directories are not accepted. Legacy transcripts under a project-local `.kit/sessions` directory follow the same migration and root checks as CLI resume; they do not make a same-named session visible from another workspace.
+Session discovery and restoration are isolated to the server's canonical workspace root. A requested workspace must match that root, and additional directories are not accepted. Legacy transcripts under a project-local `.kit/sessions` directory follow the same migration and root checks as CLI resume; they do not make a same-named session visible from another workspace. Old global transcripts without workspace metadata are excluded from discovery in every workspace, but an explicit resume by ID remains supported and binds the transcript to that workspace. An individually malformed or concurrently incomplete transcript is omitted from catalog results without preventing valid sessions from being listed; explicit resume remains strict and reports its error.
 
 An arbitrary ACP load or resume never applies the server process's configured `--force` setting. The one exception is the initial resume requested by `kit tui --resume <id> --force`: only that matching configured session may use the explicit stale-lock override. If another live Kit instance owns the session lock, restoration fails instead of taking over the session. A missing or invalid ID also fails normally. After the session closes and releases its lock, an ACP client can restore it again.
 

docs/user/tui-and-sessions.md

@@ -405,6 +405,12 @@ enum Command {
         #[command(flatten)]
         credentials: CredentialArgs,
     },
+    /// List durable sessions for a workspace, newest first.
+    Sessions {
+        /// Working directory and project context (defaults to config or `.`).
+        #[arg(long)]
+        root: Option<PathBuf>,
+    },
     /// Serve ACP on stdio with A2A, remote ACP, or both over HTTP.
     Serve {
         /// Working directory and project context (defaults to config or `.`).
@@ -534,6 +540,21 @@ fn initial_config(home: &Path) -> String {
     )
 }
 
+fn format_sessions(entries: &[kit::session::CatalogEntry]) -> String {
+    let mut output = String::from("UPDATED\tID\tTITLE\tPREVIEW\n");
+    for entry in entries {
+        output.push_str(&entry.updated_at_rfc3339());
+        output.push('\t');
+        output.push_str(&entry.id);
+        output.push('\t');
+        output.push_str(entry.title.as_deref().unwrap_or("-"));
+        output.push('\t');
+        output.push_str(entry.preview.as_deref().unwrap_or("-"));
+        output.push('\n');
+    }
+    output
+}
+
 fn write_if_missing(path: &Path, contents: &[u8]) -> io::Result<()> {
     match fs::OpenOptions::new()
         .write(true)
@@ -750,6 +771,11 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         return Ok(());
     }
     let config = Config::load_default()?;
+    if let Command::Sessions { root } = &cli.command {
+        let root = config.root(root.clone());
+        print!("{}", format_sessions(&kit::session::catalog(&root)?));
+        return Ok(());
+    }
     let openrouter_api_key =
         resolve_openrouter_api_key(cli.openrouter.openrouter_api_key.clone(), |name| {
             env::var(name).ok()
@@ -773,6 +799,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     match cli.command {
         Command::Init => unreachable!("init returns before loading runtime config"),
         Command::Auth { .. } => unreachable!("auth commands return before loading runtime config"),
+        Command::Sessions { .. } => unreachable!("sessions returns before starting a runtime"),
         Command::Serve {
             root,
             model,
@@ -1014,9 +1041,10 @@ mod tests {
     use kit::tools::CredentialStorage;
 
     use super::{
-        AuthAction, AuthProvider, Cli, Config, CredentialArgs, CredentialStoreKind, McpArgs,
-        OTEL_CAPTURE_MESSAGE_CONTENT_ENV, ReasoningEffortArg, init_config,
-        resolve_openrouter_api_key, supervise_serve_with_trigger, validate_auth_storage,
+        AuthAction, AuthProvider, Cli, Command, Config, CredentialArgs, CredentialStoreKind,
+        McpArgs, OTEL_CAPTURE_MESSAGE_CONTENT_ENV, ReasoningEffortArg, format_sessions,
+        init_config, resolve_openrouter_api_key, supervise_serve_with_trigger,
+        validate_auth_storage,
     };
 
     #[test]
@@ -1380,6 +1408,27 @@ future_option = true
         assert!(Config::load(&path).is_err());
     }
 
+    #[test]
+    fn sessions_command_accepts_a_workspace_root_and_formats_catalog_rows() {
+        let cli = Cli::try_parse_from(["kit", "sessions", "--root", "/tmp/project"]).unwrap();
+        assert!(matches!(
+            cli.command,
+            Command::Sessions { root: Some(root) }
+                if root.as_path() == std::path::Path::new("/tmp/project")
+        ));
+
+        let output = format_sessions(&[kit::session::CatalogEntry {
+            id: "session-1".into(),
+            title: Some("Fix tests".into()),
+            preview: Some("Fix tests in the catalog".into()),
+            updated_at: 0,
+        }]);
+        assert_eq!(
+            output,
+            "UPDATED\tID\tTITLE\tPREVIEW\n1970-01-01T00:00:00.000Z\tsession-1\tFix tests\tFix tests in the catalog\n"
+        );
+    }
+
     #[test]
     fn otel_endpoint_is_a_global_command_line_option() {
         let cli = Cli::try_parse_from([