session-steward 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 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

package/README.md

@@ -20,6 +20,7 @@ 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.
 
@@ -150,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

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,