SessionStore

Category: Storage

Source: session_store.dart

Enums

SessionTitleSource

Metadata for a saved session, including model ref and timing.

Value	Description
auto
user

SessionTitleState

Value	Description
provisional
stable

Classes

SessionMeta

Constructor

SessionMeta({
    this.schemaVersion = currentSchemaVersion,
    required this.id,
    required this.cwd,
    this.projectPath,
    required this.modelRef,
    required this.startTime,
    this.endTime,
    this.forkedFrom,
    this.worktreePath,
    this.branch,
    this.baseBranch,
    this.repoRemote,
    this.headSha,
    this.title,
    this.titleSource,
    this.titleState,
    this.titleGenerationCount = 0,
    this.titleGeneratedAt,
    this.titleLastEvaluatedAt,
    this.titleRenamedAt,
    this.tags = const [],
    this.prUrl,
    this.prStatus,
    this.tokenCount,
    this.cacheReadTokens,
    this.cacheCreationTokens,
    this.messageCount,
    this.summary,
    this.runtimeId,
    this.sandboxId,
    this.runtimeBootstrapSha,
    this.runtimeRemoteUrl,
    this.runtimePatchPath,
    this.runtimeClosedAt,
  })

factory SessionMeta.fromJson(Map<String, dynamic> json)

Properties

Property	Type	Description
currentSchemaVersion	const int
schemaVersion	int
id	SessionId
cwd	String
projectPath	String?
modelRef	String	Fully-qualified model reference: <provider>/<model>. Schema v3+ writes this as model_ref. Schema ≤ 2 is read-compatible: if the stored value has no slash, the legacy provider field is prepended on read (see [fromJson]).
startTime	DateTime
endTime	DateTime?
forkedFrom	String?
worktreePath	String?
branch	String?
baseBranch	String?
repoRemote	String?
headSha	String?
title	String?
titleSource	SessionTitleSource?
titleState	SessionTitleState?
titleGenerationCount	int
titleGeneratedAt	DateTime?
titleLastEvaluatedAt	DateTime?
titleRenamedAt	DateTime?
tags	List<String>
prUrl	String?
prStatus	String?
tokenCount	int?
cacheReadTokens	int?
cacheCreationTokens	int?
messageCount	int?
summary	String?
runtimeId	String?
sandboxId	String?
runtimeBootstrapSha	String?
runtimeRemoteUrl	String?
runtimePatchPath	String?
runtimeClosedAt	DateTime?
sessionDir	String
holderPid	int?
sessionDir	String
meta	SessionMeta

Methods

String toString()

static SessionLock acquire(String sessionDir)

Claims [sessionDir] for the current process, or throws [SessionInUseException] if a foreign PID already holds it.

void release()

Releases the lock if we still own it. Idempotent.

`void setTitle(

String title, {
SessionTitleSource? source,
SessionTitleState? state,
int? generationCount,
DateTime? generatedAt,
DateTime? lastEvaluatedAt,
DateTime? renamedAt,

})`

void updateMeta()

Writes the current metadata to disk.

void logEvent(String type, Map<String, dynamic> data)

Appends a timestamped event record to the conversation log. Uses a single append-mode write — the session dir already exists (constructor).

Flushes each append so a crash can't strip the tail line (M12). The log is chmod'd to owner-only (0600) on its first write (L3).

TODO(L7): the conversation log grows unbounded — full request/response content is retained forever. A size/age cap or rollup should be added before this becomes a disk-usage problem on long-lived sessions.

Future<void> close()

Closes this session, recording the end time and releasing the advisory lock (M11) so another process may resume it.

static List<SessionMeta> listSessions(String sessionsDir)

Lists all saved sessions in [sessionsDir], sorted newest first.

SessionInUseException

Thrown when a session directory is already claimed by another live Glue process (M11) and cannot be opened for writing.

Constructor

SessionInUseException(this.sessionDir, {this.holderPid})

Properties

Property	Type	Description
sessionDir	String
holderPid	int?

Methods

String toString()

SessionLock

Advisory PID lock guarding a session directory against two Glue processes writing the same conversation.jsonl concurrently (M11).

It is a plain .lock file recording the owning PID — deliberately not an OS file lock, which would keep an open handle and (on Windows) block temp dir cleanup. Re-entry by the same process is allowed; a .lock owned by a different PID fails acquisition. Released (file deleted) on [release].

Limitation: a hard crash leaves a stale .lock. There is no portable liveness probe in Dart (no signal-0), so a stale lock blocks resume until removed — the raised [SessionInUseException] names the file so it can be deleted manually. TODO: portable staleness detection.

Methods

static SessionLock acquire(String sessionDir)

Claims [sessionDir] for the current process, or throws [SessionInUseException] if a foreign PID already holds it.

void release()

Releases the lock if we still own it. Idempotent.

SessionStore

Persistent storage for a single session's metadata and conversation log.

Constructor

SessionStore({required this.sessionDir, required this.meta, this._lock})

Properties

Property	Type	Description
sessionDir	String
meta	SessionMeta

Methods

`void setTitle(

String title, {
SessionTitleSource? source,
SessionTitleState? state,
int? generationCount,
DateTime? generatedAt,
DateTime? lastEvaluatedAt,
DateTime? renamedAt,

})`

void updateMeta()

Writes the current metadata to disk.

void logEvent(String type, Map<String, dynamic> data)

Appends a timestamped event record to the conversation log. Uses a single append-mode write — the session dir already exists (constructor).

Flushes each append so a crash can't strip the tail line (M12). The log is chmod'd to owner-only (0600) on its first write (L3).

TODO(L7): the conversation log grows unbounded — full request/response content is retained forever. A size/age cap or rollup should be added before this becomes a disk-usage problem on long-lived sessions.

Future<void> close()

Closes this session, recording the end time and releasing the advisory lock (M11) so another process may resume it.

static List<SessionMeta> listSessions(String sessionsDir)

Lists all saved sessions in [sessionsDir], sorted newest first.