From c09fb2041cf2014dd54f9f0dc7841ab4aff2a991 Mon Sep 17 00:00:00 2001
From: David Brailovsky <davidbrai@gmail.com>
Date: Fri, 14 Aug 2026 12:34:52 +0200
Subject: [PATCH] docs(agent): document session fork options

---
 packages/agent/src/harness/session/types.ts | 30 +++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/packages/agent/src/harness/session/types.ts b/packages/agent/src/harness/session/types.ts
index 92237c383..da10e9089 100644
--- a/packages/agent/src/harness/session/types.ts
+++ b/packages/agent/src/harness/session/types.ts
@@ -534,8 +534,34 @@ export interface SessionCreateOptions {
 }
 
 export type ForkOptions =
-	| { scope?: "branch"; entryId?: string; position?: "before" | "at"; id?: string }
-	| { scope: "tree"; id?: string };
+	| {
+			/**
+			 * Copy one branch path into the destination session's main lane. This is
+			 * the default scope. The destination starts idle with a fresh lane state,
+			 * no operation registers, no pending entries, no last result, and an empty
+			 * usage ledger.
+			 */
+			scope?: "branch";
+			/** Entry to fork from. Defaults to the source main lane's current leaf. */
+			entryId?: string;
+			/**
+			 * Whether the fork includes the selected entry or stops at its parent.
+			 * Defaults to including the selected entry.
+			 */
+			position?: "before" | "at";
+			/** Optional destination session id. */
+			id?: string;
+	  }
+	| {
+			/**
+			 * Copy the whole conversation tree and every lane leaf/configuration. The
+			 * destination starts idle with fresh lane states, no operation registers,
+			 * no pending entries, no last results, and an empty usage ledger.
+			 */
+			scope: "tree";
+			/** Optional destination session id. */
+			id?: string;
+	  };
 
 export interface SessionRepo<
 	TMetadata extends SessionMetadata = SessionMetadata,