diff --git a/packages/agent/src/harness/session/types.ts b/packages/agent/src/harness/session/types.ts
index 77b05ad24..9b3fbf523 100644
--- a/packages/agent/src/harness/session/types.ts
+++ b/packages/agent/src/harness/session/types.ts
@@ -14,9 +14,9 @@ export interface IdGenerator {
 export interface EntryBase {
 	type: string;
 	id: string;
-	seq: number;
-	parentId: string | null;
-	timestamp: number;
+	seq: number; // shared sequence; read-side, storage-assigned
+	parentId: string | null; // storage-assigned: the appending lane's leaf
+	timestamp: number; // Unix ms, storage-assigned
 }
 
 export interface MessageEntry extends EntryBase {
@@ -222,15 +222,16 @@ export interface EntryCursor {
 
 export interface EntryQuery {
 	type?: Entry["type"];
-	customType?: string;
-	order?: EntryOrder;
+	customType?: string; // for type "custom"
+	order?: EntryOrder; // default newestFirst
 	limit?: number;
 	cursor?: EntryCursor;
 }
 
+/** Bounds of a branch scan. Default: the whole path, leaf to root. */
 export interface BranchBounds {
-	start?: string;
-	stopAtType?: Entry["type"];
+	start?: string; // default: the view's lane leaf
+	stopAtType?: Entry["type"]; // scan ends after the first match, inclusive
 	stopAtId?: string;
 }
 
@@ -318,14 +319,24 @@ export interface SessionTree {
 	getLeafId(): Promise<string | null>;
 	getEntry(id: string): Promise<Entry | undefined>;
 	getStats(): Promise<SessionStats>;
+
+	// Global facts. Latest wins; not branch-scoped. "set", not "append":
+	// append vocabulary is reserved for tree writes.
 	getName(): Promise<string | undefined>;
 	setName(name: string): Promise<void>;
 	getLabel(targetId: string): Promise<string | undefined>;
 	setLabel(targetId: string, label: string | undefined): Promise<void>;
+
+	/** Session-wide, all branches, sequence order. */
 	findEntries(query?: EntryQuery): Promise<Entry[]>;
 	findEntry(query?: EntryQuery): Promise<Entry | undefined>;
+
+	/** Branch-scoped: the path from start toward root. */
 	findEntriesOnBranch(query?: EntryQuery & BranchBounds): Promise<Entry[]>;
 	findEntryOnBranch(query?: EntryQuery & BranchBounds): Promise<Entry | undefined>;
+
+	// Writes. Resolve on durable acceptance; the returned id is the entry's
+	// id (provisioned when the write defers).
 	appendMessage(message: AgentMessage): Promise<string>;
 	appendCustomEntry(customType: string, data?: unknown): Promise<string>;
 }