RFD 130: Session Record Retention and Read Surface
Summary
JP deletes session records as soon as their originating process exits, omits the checkout where each conversation was activated, and provides no way to read a record without parsing an internal on-disk format. This RFD records the checkout root of each activation, retains closed session records for a 30-day window, and adds a jp session read surface.
Motivation
Workspace::cleanup_stale_files runs at the end of every invocation and unlinks any session mapping whose session-leader PID is confirmed dead. Eager deletion causes three problems, and an omission in the session record causes a fourth:
Session records are deleted before restore tools can read them. A terminal emulator that restores its window layout restores surfaces, not processes: every restored tab gets a fresh shell with a new PID, so every existing getsid-<pid>.json names a dead process. Any tool that rebuilds tab-to-conversation bindings must run before the next jp invocation in that workspace. Because any tab can trigger the cleanup sweep, the restore tool races against normal use.
Reading a record requires depending on a private encoding. Outside the workspace crates, which can call Workspace::session_overviews(), there is no supported command to query a session's active conversation, so external tooling parses the JSON files directly. That encoding is not obvious: ConversationId serializes through jp_id::serde as a bare decisecond integer, whereas RFD 020's illustrative session-mapping payload shows "id": "jp-c17528832001". A script written against the documented format does not match the on-disk format and silently selects nothing.
A recycled PID can adopt a closed session's history. read_matching_mapping guards against filename aliasing by comparing the stored id and source against the current session, but for SessionSource::Getsid the stored id is the PID. A new shell assigned a recycled PID matches the old record. Eager deletion makes this unlikely rather than impossible, because nothing guarantees that the cleanup sweep runs before the new shell's first jp call.
Records omit the checkout where a conversation was activated. Every checkout of a workspace shares one session directory, and a shell can cd between checkouts, so a session's history names its conversations without the checkout each one ran in. A tool that displays each checkout's recent activity, such as a workspace dashboard, can only associate a conversation with a checkout through the working directory of the session's live shell. Once that shell exits, the checkout association is lost and eager deletion removes the record. The roots registry (RFD 087) tracks checkouts without their conversations; the session record is the only place that observes both at activation time.
Design
Activation Root
SessionHistoryEntry records the checkout root where the activation occurred:
/// The canonical root of the checkout this conversation was activated in.
///
/// `None` for entries written before this field existed.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub root: Option<Utf8PathBuf>,Workspace::record_session_activation populates root from the workspace root directory (the directory containing the workspace's storage, matching the roots registry), regardless of how the checkout was created or which subdirectory the process ran from. Every activation path records root without caller changes: jp query, jp conversation use (including its lock-contention fallback), and jp conversation fork. Re-activating a conversation in another checkout moves its entry to the front of the history and updates both activated_at and root. Because the session directory is user-local and never projected into the workspace, storing an absolute path is safe.
Closed Sessions
A session is open while its originating process is running and closed once that process exits, whether cleanly, by crashing, or across a reboot. SessionMapping gains one field:
/// When JP first observed that the session's originating process was gone.
///
/// `None` while the session is open, while liveness is unknown, and before
/// any cleanup pass has observed it close.
pub closed_at: Option<DateTime<Utc>>,When cleanup_session_file first observes Liveness::Dead, it sets closed_at to the current time and renames the record from <key>.json to <key>~<closed_at as Unix seconds>.json instead of deleting it. Renaming frees <key>.json so a new session assigned the same PID starts a fresh record without overwriting the closed one, which retains its own key for the retention window.
closed_at records when JP observed that the session closed, not when the process exited. It is never derived from activated_at, because an open session can sit idle for months and expiring records from last activation would collect sessions that are still in use.
For SessionSource::Env, process liveness is unknown, so the existing conversation-existence heuristic remains the trigger: the record closes when no conversation in its history still exists. Because an empty record has no history left to retain, cleanup removes it immediately, preserving existing behavior for Env sessions.
Records written before this field existed deserialize with closed_at: None and are treated as open until observed closed.
Matching Open Sessions
An open session reads only <key>.json, ignoring renamed closed records. read_matching_mapping also rejects any record with closed_at set, covering the window between writing closed_at and renaming the file.
This prevents PID reuse from adopting any session that JP has observed closed. It does not prevent PID reuse if a shell exits and the OS recycles its PID before a cleanup pass runs (for example, across a reboot), because the unmarked record still matches the new shell (see Risks and Open Questions).
Retention and Garbage Collection
Cleanup removes a closed record once now - closed_at exceeds the retention window. This RFD fixes the window at a 30-day constant rather than a configuration key, leaving configuration until a concrete need arises.
History pruning applies to closed records the same way it applies to open ones: cleanup drops any entry whose conversation is neither live, archived, nor locked, and removes any closed record whose history becomes empty. Retention preserves a session's surviving conversations, not an audit log of deleted ones.
Closed records must not keep ephemeral conversations alive. all_active_conversation_ids, which feeds remove_ephemeral_conversations, skips closed records so a --tmp conversation whose terminal has closed is still collected on schedule.
Read Surface
$ jp session ls
KEY SOURCE STATE ACTIVE LAST ACTIVE
getsid-79800 getsid open jp-c17864439611 2 minutes ago
getsid-12057 getsid open jp-c17862201040 4 hours ago
env-JP_SESSION-a1b2 env:JP_SESSION unknown jp-c17858834912 yesterday
$ jp session ls --all
KEY SOURCE STATE ACTIVE LAST ACTIVE
getsid-79800 getsid open jp-c17864439611 2 minutes ago
getsid-12057 getsid open jp-c17862201040 4 hours ago
env-JP_SESSION-a1b2 env:JP_SESSION unknown jp-c17858834912 yesterday
getsid-61004~1762333920 getsid closed jp-c17851190372 3 days ago
$ jp session show getsid-79800
$ jp -F json session lsA record's state is computed at read time using the same process liveness check as cleanup: open, closed, or unknown when liveness cannot be checked (such as Env sessions). Checking closed_at alone is not sufficient because cleanup runs only at the end of a writable jp invocation; a reader such as session_overviews() observes a recently exited shell as closed with closed_at: null until the next cleanup pass.
jp session ls and jp session show run session-record maintenance before reading rather than waiting until the end of the invocation. Marking and renaming closed records up front ensures that every key printed by ls stays stable for the retention window; if a session closes after ls runs, show on its old key reports it missing and ls --all lists it under its renamed key. Running maintenance early adds no writes beyond what a normal jp invocation performs at exit, and read-only invocations that cannot write session state skip maintenance and list the records as they stand on disk.
ls lists open and unknown records, while --all includes closed records under their renamed keys. show prints a single record and its history of live and archived conversations, including each entry's activated_at and root.
ACTIVE is the session's active conversation, resolved using the same rules the session itself uses: deleted conversations are skipped, and if the most recent remaining entry is archived, the session has no active conversation. For a closed record, ACTIVE is the conversation the session would have continued.
The JSON output is the supported contract for external tooling and formats conversation IDs in their display form (jp-c17864439611) rather than as the on-disk integer:
{
"key": "getsid-79800",
"source": "getsid",
"state": "open",
"closed_at": null,
"active": "jp-c17864439611",
"history": [
{
"id": "jp-c17864439611",
"activated_at": "2026-11-05T09:12:00Z",
"root": "/Users/jean/Projects/jp.git/ticket-0yh5hqj"
}
]
}External scripts querying a session's active conversation should read active rather than history[0].
In-process callers use Workspace::session_overviews(), which returns each record's state, closed_at, active conversation, and history entries (including activated_at and root) for both open and closed records, without shelling out to the CLI or parsing session files directly.
The record type remains in jp_workspace, and the command lives in jp_cli.
Drawbacks
The session directory grows with terminal tab churn over the 30-day retention window rather than staying bounded by the number of open sessions.
jp session ls --format=json becomes a public contract that JP must keep stable, replacing an implicit dependency on the file layout with an explicit CLI schema.
Persisted session types gain two fields (root and closed_at) and an additional lifecycle state: a record on disk can be either open or closed, and closed records sit alongside open ones in the session directory under ~ keys.
Session records store absolute paths to the user's checkouts and jp session prints them in JSON output. Because session records already live in user-local storage alongside conversations that reference those paths in tool calls, this does not expose new data on disk.
Alternatives
Read session files from a command plugin. Although the plugin API exposes paths.user_workspace, reading session files directly from a plugin would make the on-disk record format a public contract. Changing that format (as this RFD does) would silently break plugin filters rather than failing with a parse error.
Keep eager deletion and have external tools snapshot before quitting. This requires users or hooks to snapshot state before exiting and loses all session bindings on crashes or forced restarts, when recovery matters most.
Never collect closed records. Without garbage collection, the session directory grows without bound and closed keys accumulate in every listing.
Record the last conversation on the checkout's roots registry entry. Adding an optional conversation field to RootEntry (updated by jp query) would duplicate activation state across two unlinked stores: the roots registry would know each checkout's last conversation without its session, and the session record would know its conversations without their checkouts. Neither store would record which session ran which conversation in which checkout. Keeping activation history in the session record leaves the roots registry responsible only for tracking workspace checkouts.
Record the checkout directory on the conversation (in conversation metadata or on TurnStart). Conversations can be projected into the workspace and committed to version control, where local absolute paths do not belong. Storing the checkout on the conversation would also require scanning every conversation to find which conversation last ran in a given checkout.
Non-Goals
- Automatic session restoration. Matching a restored terminal surface to a closed session record requires window and tab metadata that only the client has. This RFD makes an external restore script possible rather than restoring bindings inside JP.
- Cross-client session semantics. Defining what a session means outside the CLI is out of scope; the read surface and retention policy hold under any later definition.
- Merging the per-workspace and user-global session stores. Both the per-workspace session mapping (RFD 020) and the user-global workspace session store (RFD 087) keep a most-recent-first history per session; whether to unify them is left to a future cross-client session RFD.
- Recording sessionless invocations. An invocation for which JP cannot derive a session identity activates no conversation and writes no session record.
- Cross-session targeting. This RFD does not add a session-scoping flag for addressing another session's records.
- Configurable retention. The 30-day retention window is not configurable.
Risks and Open Questions
Retention duration. The 30-day window is an estimate. Tab churn varies across users, though because session records are small, a longer window only costs minor disk space.
Unobserved session exit and PID reuse. A session that exits without being observed by a cleanup pass can still be adopted via PID reuse if the OS recycles its PID before the next jp invocation (for example, across a reboot), causing the new shell to inherit the old session's conversation. This limitation already exists and is not widened by this RFD. Fixing it requires a per-process-lifetime identity (such as boot ID plus process start time), which belongs in future cross-client session identity work.
Command naming. jp session uses the current domain term. If a future cross-client session RFD settles on a different term, the command can be renamed without affecting the underlying storage or retention model.
Alignment with RFD 087. RFD 087's user-global session store has its own cleanup pass that deletes records when their session source is dead. Both stores should share the same retention policy so they do not diverge; Phase 4 applies this RFD's policy to the user-global store.
Read amplification across retained records. A reader querying every checkout's last activation, such as a dashboard polling every few seconds, must read every session file retained within the 30-day window (one small file per terminal tab opened in that period). If directory scans become a bottleneck, session_overviews() can maintain an index internally without changing the on-disk record format or CLI output.
Implementation Plan
Phase 1: Activation root. Add root to SessionHistoryEntry and populate it in record_session_activation. Update session_overviews() to report every retained history entry (both live and archived) with its activated_at and root, rather than only live conversation IDs. This phase is contained in jp_workspace, independent of the other phases, and can merge on its own.
Phase 2: Record and retention policy. Add closed_at, mark and rename closed records instead of unlinking them, reject closed records in read_matching_mapping, prune their history like open records and remove empty ones, remove expired records after the 30-day retention window, exclude closed records from all_active_conversation_ids, and include closed records in session_overviews() with each record's state computed at read time. Add characterization tests for the existing cleanup paths first, because session_mapping_tests.rs asserts the delete-on-dead behavior that this change inverts. This phase is contained in jp_workspace and can merge on its own.
Phase 3: Read surface. Implement jp session ls, jp session ls --all, and jp session show in jp_cli with table and JSON output (including state, closed_at, and active), running session maintenance before reading. This phase depends on Phases 1 and 2 for the root and closed_at fields and can merge on its own.
Phase 4: User-global session store. Apply the same marking, renaming, and retention policy to RFD 087's user-global session store. This phase depends on Phase 2.