session-steward 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.5.0] - 2026-08-10
+
+### Added
+
+- A session timeline. Opening a session now shows what actually happened inside it: what you asked, what the assistant concluded, which files it changed, and which commands it ran along with whether they succeeded. Deciding whether a large session is worth keeping no longer means guessing from a size and a date.
+- The same timeline in the terminal through `--events`, shown when you inspect a session, or attached to every record under `--json` for other tools to read.
+- Coverage on every timeline: how much of a transcript Session Steward recognized, and which kinds of records it did not. If a future Codex or Claude release changes its transcript format, an incomplete timeline will say so rather than quietly looking complete.
+
+### Changed
+
+- Timelines are read on demand and never stored, cached, or indexed. Nothing is written to your Codex or Claude folders, so reading a session cannot alter it.
+- Reading a transcript costs the same memory whether it is one megabyte or several hundred. Unusually large records are counted and passed over instead of loaded, and a session that is still being written is read up to a fixed point rather than chased as it grows.
+- Sessions with nothing to show now explain which case applies — the transcript file is gone, no transcript was ever recorded, or nothing in it was recognized — instead of appearing empty for no stated reason.
+- Sessions recorded twice by Codex under different internal envelopes are shown once, without dropping messages that appear in only one of them.
+
+## [0.4.0] - 2026-08-04
+
+### Added
+
+- Support for versioned Codex state, log, memory, and goal databases, including old and new stores that coexist after a migration.
+- Permanent Codex and Claude layout fixtures, cross-store cleanup coverage, and a two-store scale benchmark.
+- Storage provenance in recovery manifests while retaining restore support for backups from 0.3.0.
+
+### Changed
+
+- Codex sessions from every recognized state store now share one deduplicated, globally sorted, paginated list.
+- Compatibility states now describe capability as ready, partial, or unsupported.
+- Codex continues with reduced metadata when optional fields or relationship tables are unavailable.
+- Claude thorough cleanup leaves unrecognized locations untouched, reports them clearly, and remains available when its required projects folder is readable.
+
 ## [0.3.0] - 2026-08-03
 
 ### Added
@@ -51,6 +81,7 @@
 - Support for custom Codex home folders and a saved folder preference.
 - Streaming and bounded-memory discovery for large session collections and transcripts.
 
+[0.4.0]: https://github.com/mallikcheripally/session-steward/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/mallikcheripally/session-steward/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/mallikcheripally/session-steward/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/mallikcheripally/session-steward/compare/v0.1.0...v0.1.1

package/README.md

@@ -20,21 +20,10 @@ Session Steward makes session cleanup safer by finding those records, showing wh
 - Find sessions inactive for 30, 60, or 90 days.
 - Filter active or archived sessions by workspace, name, or session ID.
 - Inspect session details and affected records before deletion.
+- Read a session timeline of what you asked, what changed, and which commands ran.
 - Choose standard or thorough cleanup.
 - Use custom Codex or Claude home folders across browser and terminal sessions.
 
-## Built for large session libraries
-
-Current synthetic benchmarks on an arm64 Mac with Node.js 24.15.0:
-
-| Scenario | Scale | Time | Measured memory growth |
-| --- | ---: | ---: | ---: |
-| Paginated session listing | 50,003 sessions | 26 ms | 0.16 MB heap |
-| Session size index | 20,003 sessions | 85 ms cold, 9.7 ms warm | 30 MB peak RSS |
-| Transcript-only discovery | 5,003 sessions | 662 ms | 4.02 MB heap |
-
-Results vary with hardware, disk speed, and session layout. The benchmark commands are included in the repository and use temporary synthetic data.
-
 ## Safe by default
 
 - Cleanup happens entirely on your computer.
@@ -162,6 +151,18 @@ session-steward-cli --workspace /path/to/project
 
 Use `--include-internals` to include subagents and `--include-supporting` to include supporting sessions. Session sizes are shown in the interactive list, and `--sort size` places the largest sessions first.
 
+Start with `--events` to read what happened inside a session — what you asked, what the assistant concluded, which files changed, and which commands ran or failed. In the interactive list, `inspect <number>` then shows that session's timeline:
+
+```bash
+session-steward-cli --events --events-limit 50
+```
+
+With `--json`, each session carries its own `events`, plus a `coverage` summary of how much of the transcript was recognized:
+
+```bash
+session-steward-cli --json --limit 5 --events
+```
+
 The interactive terminal accepts the same filters:
 
 ```text
@@ -244,7 +245,19 @@ npm test
 npm run build
 ```
 
-Scale benchmarks are also available:
+## Performance and scale
+
+Session Steward uses paginated listings, incremental transcript reads, and bounded caches to remain responsive with large session libraries.
+
+Current synthetic benchmarks on an arm64 Mac with Node.js 24.15.0:
+
+| Scenario | Scale | Time | Measured memory growth |
+| --- | ---: | ---: | ---: |
+| Paginated session listing | 50,003 sessions | 26 ms | 0.16 MB heap |
+| Session size index | 20,003 sessions | 85 ms cold, 9.7 ms warm | 30 MB peak RSS |
+| Transcript-only discovery | 5,003 sessions | 662 ms | 4.02 MB heap |
+
+Run the scale benchmarks with:
 
 ```bash
 npm run benchmark:scale
@@ -254,7 +267,7 @@ npm run benchmark:discovery
 npm run benchmark:transcripts
 ```
 
-Tests and benchmarks use temporary synthetic session data. They do not read or modify your local sessions.
+Results vary with hardware, disk speed, and session layout. Tests and benchmarks use temporary synthetic data and do not read or modify your local sessions.
 
 ## Support
 

package/bin/session-steward-cli.mjs

@@ -26,6 +26,12 @@ const { values } = parseArgs({
     cleanup: {
       type: "string",
     },
+    events: {
+      type: "boolean",
+    },
+    "events-limit": {
+      type: "string",
+    },
     help: {
       short: "h",
       type: "boolean",
@@ -67,6 +73,9 @@ const numericLimit =
   values.limit && Number.isFinite(Number.parseInt(values.limit, 10))
     ? Number.parseInt(values.limit, 10)
     : null;
+const eventsLimit = values["events-limit"] === undefined
+  ? 100
+  : Number(values["events-limit"]);
 
 async function main() {
   const help = values.help ?? false;
@@ -86,11 +95,16 @@ async function main() {
     });
   }
   const providerHome = settings.getHome(providerId);
+  if (!Number.isSafeInteger(eventsLimit) || eventsLimit < 1 || eventsLimit > 1_000) {
+    throw new Error("Events limit must be between 1 and 1000.");
+  }
 
   await runCli({
     archiveStatus: values["archive-status"],
     backups: values.backups ?? false,
     cleanup: values.cleanup,
+    events: values.events ?? false,
+    eventsLimit,
     help,
     inactiveDays: values["inactive-days"],
     includeInternals: values["include-internals"] ?? false,