feat(coding-agent): persist parent edges and derived depth for all sessions

Groundwork for the recursive agent tree (Track A PR 2): every session -
live, passive, or saved-only - carries its tree position without a runtime
and without inference.

- additive rlmDepth field in the session JSONL header (no format bump; old
  readers ignore it); surfaced through SessionInfo, the saved-session
  catalog, SessionSummary, and agent-connection types
- spawn edges derive child depth = parent depth + 1 at creation; fork and
  branch COPY the source depth (reference edges, not structural parents):
  a forked root stays a root
- RLM_DEPTH env seeds fresh parentless sessions; persisted header wins for
  resumed sessions; legacy children resolve depth via the subagent registry
  fallback, never chain walks at scan time
- one shared saved-session-info serializer (deduped from daemon-mode/
  daemon-supervisor); DAEMON_SCHEMA_REVISION 9 with regenerated id

Track A PR 2 of the recursive-agent-harness plan.

Author: snimu

packages/coding-agent/src/core/agent-session-runtime.ts

@@ -344,7 +344,10 @@ export class AgentSessionRuntime implements SubagentRuntimeHost {
 	async createRlmSubagentRuntime(options: CreateRlmSubagentRuntimeOptions): Promise<RlmSubagentRuntime> {
 		const sessionManager = SessionManager.create(options.parentSession.sessionManager.getCwd(), options.sessionDir);
 		if (options.parentSession.sessionFile) {
-			sessionManager.newSession({ parentSession: options.parentSession.sessionFile });
+			sessionManager.newSession({
+				parentSession: options.parentSession.sessionFile,
+				rlmDepth: options.rlmDepth,
+			});
 		}
 		const runtime = await this.scopedBuild(() =>
 			createAgentSessionRuntime(this.createRuntime, {
@@ -570,8 +573,12 @@ export class AgentSessionRuntime implements SubagentRuntimeHost {
 			}
 			const sessionDir = this.session.sessionManager.getSessionDir();
 			if (!targetLeafId) {
+				const sourceHeader = this.session.sessionManager.getHeader();
 				const sessionManager = SessionManager.create(this.cwd, sessionDir);
-				sessionManager.newSession({ parentSession: currentSessionFile });
+				sessionManager.newSession({
+					parentSession: currentSessionFile,
+					rlmDepth: sourceHeader?.rlmDepth,
+				});
 				const lease = this.acquireReplacementLease(sessionManager.getSessionFile());
 				await this.teardownForReplacement("fork", sessionManager.getSessionFile(), lease);
 				await this.buildAndApplyReplacement(
@@ -618,7 +625,11 @@ export class AgentSessionRuntime implements SubagentRuntimeHost {
 
 		const sessionManager = this.session.sessionManager;
 		if (!targetLeafId) {
-			sessionManager.newSession({ parentSession: this.session.sessionFile });
+			const sourceHeader = sessionManager.getHeader();
+			sessionManager.newSession({
+				parentSession: this.session.sessionFile,
+				rlmDepth: sourceHeader?.rlmDepth,
+			});
 		} else {
 			sessionManager.createBranchedSession(targetLeafId);
 		}

packages/coding-agent/src/core/agent-session.ts

@@ -1231,7 +1231,10 @@ export class AgentSession {
 		this._mcpManager = config.mcpManager;
 		this._baseToolsOverride = config.baseToolsOverride;
 		this._sessionStartEvent = config.sessionStartEvent ?? { type: "session_start", reason: "startup" };
-		this._rlmDepth = config.rlmDepth ?? parseDepth(process.env.RLM_DEPTH, 0, "RLM_DEPTH");
+		this._rlmDepth =
+			config.rlmDepth ??
+			this.sessionManager.getHeader()?.rlmDepth ??
+			parseDepth(process.env.RLM_DEPTH, 0, "RLM_DEPTH");
 		this._rlmMaxDepth = config.rlmMaxDepth ?? parseDepth(process.env.RLM_MAX_DEPTH, 1, "RLM_MAX_DEPTH");
 		this._prewarmIpythonKernel = (config.prewarmIpythonKernel ?? false) && this._rlmDepth === 0;
 		this._autoRefineReviewer = config.autoRefineReviewer;
@@ -3990,6 +3993,11 @@ export class AgentSession {
 		return this.sessionManager.getSessionId();
 	}
 
+	/** Current RLM spawn depth for this session. */
+	get rlmDepth(): number {
+		return this._rlmDepth;
+	}
+
 	/** Current session display name, if set */
 	get sessionName(): string | undefined {
 		return this.sessionManager.getSessionName();
@@ -8625,7 +8633,10 @@ export class AgentSession {
 	private _createInlineRlmSubagentRuntime(options: CreateRlmSubagentRuntimeOptions): RlmSubagentRuntime {
 		const childSessionManager = SessionManager.create(this._cwd, options.sessionDir);
 		if (options.parentSession.sessionFile) {
-			childSessionManager.newSession({ parentSession: options.parentSession.sessionFile });
+			childSessionManager.newSession({
+				parentSession: options.parentSession.sessionFile,
+				rlmDepth: options.rlmDepth,
+			});
 		}
 		childSessionManager.appendModelChange(options.model.provider, options.model.id);
 		childSessionManager.appendThinkingLevelChange(options.thinkingLevel);

packages/coding-agent/src/core/session-manager.ts

@@ -79,12 +79,16 @@ export interface SessionHeader {
 	timestamp: string;
 	cwd: string;
 	parentSession?: string;
+	/** RLM spawn depth. Optional for backward compatibility. Forks preserve the source depth. */
+	rlmDepth?: number;
 	git?: GitContext;
 }
 
 export interface NewSessionOptions {
 	id?: string;
 	parentSession?: string;
+	/** Explicit RLM spawn depth. An explicitly undefined value suppresses parent derivation. */
+	rlmDepth?: number;
 }
 
 export type SessionPersistListener = (sessionFile: string) => void;
@@ -291,6 +295,8 @@ export interface SessionInfo {
 	state?: SessionState;
 	/** Path to the parent session (if this session was forked). */
 	parentSessionPath?: string;
+	/** RLM spawn depth; absent when legacy metadata cannot establish it. */
+	rlmDepth?: number;
 	created: Date;
 	modified: Date;
 	messageCount: number;
@@ -692,6 +698,26 @@ function readSessionHeader(filePath: string): Partial<SessionHeader> | undefined
 	return JSON.parse(firstLine) as Partial<SessionHeader>;
 }
 
+function isValidRlmDepth(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function deriveChildRlmDepth(parentHeader: Partial<SessionHeader> | undefined): number | undefined {
+	return isValidRlmDepth(parentHeader?.rlmDepth) ? parentHeader.rlmDepth + 1 : undefined;
+}
+
+function rootRlmDepthFromEnv(): number {
+	const value = process.env.RLM_DEPTH;
+	if (value === undefined || value === "") {
+		return 0;
+	}
+	const parsed = Number.parseInt(value, 10);
+	if (!Number.isFinite(parsed) || parsed < 0) {
+		throw new Error("RLM_DEPTH must be a non-negative integer");
+	}
+	return parsed;
+}
+
 function isValidSessionFile(filePath: string): boolean {
 	try {
 		const header = readSessionHeader(filePath);
@@ -1021,6 +1047,7 @@ async function scanSessionInfo(filePath: string, stats: Awaited<ReturnType<typeo
 		if (!header) return null;
 		const cwd = typeof header.cwd === "string" ? header.cwd : "";
 		const parentSessionPath = header.parentSession;
+		const rlmDepth = isValidRlmDepth(header.rlmDepth) ? header.rlmDepth : parentSessionPath ? undefined : 0;
 		const modified = getSessionModifiedDateFromLastActivity(lastActivityTime, header, stats.mtime);
 
 		return {
@@ -1030,6 +1057,7 @@ async function scanSessionInfo(filePath: string, stats: Awaited<ReturnType<typeo
 			name,
 			state,
 			parentSessionPath,
+			rlmDepth,
 			created: new Date(header.timestamp),
 			modified,
 			messageCount,
@@ -1177,6 +1205,15 @@ export class SessionManager {
 	newSession(options?: NewSessionOptions): string | undefined {
 		let sessionId = options?.id ?? createSessionId();
 		let sessionFile: string | undefined;
+		const hasExplicitRlmDepth = options !== undefined && Object.hasOwn(options, "rlmDepth");
+		let parentHeader: Partial<SessionHeader> | undefined;
+		if (options?.parentSession && !hasExplicitRlmDepth) {
+			try {
+				parentHeader = readSessionHeader(options.parentSession);
+			} catch {
+				// Legacy-invalid or unavailable parents leave the child depth unknown.
+			}
+		}
 		if (this.persist) {
 			if (options?.id) {
 				sessionFile = getSessionFilePath(this.getSessionDir(), sessionId);
@@ -1193,13 +1230,19 @@ export class SessionManager {
 		this.sessionId = sessionId;
 		const timestamp = new Date().toISOString();
 		const git = this.persist ? (captureGitContext(this.cwd) ?? undefined) : undefined;
+		const rlmDepth = hasExplicitRlmDepth
+			? options?.rlmDepth
+			: options?.parentSession
+				? deriveChildRlmDepth(parentHeader)
+				: rootRlmDepthFromEnv();
 		const header: SessionHeader = {
 			type: "session",
 			version: CURRENT_SESSION_VERSION,
 			id: this.sessionId,
 			timestamp,
 			cwd: this.cwd,
 			parentSession: options?.parentSession,
+			rlmDepth,
 			git,
 		};
 		this.fileEntries = [header];
@@ -1305,6 +1348,7 @@ export class SessionManager {
 		if (!existsSync(dir)) {
 			mkdirSync(dir, { recursive: true });
 		}
+		const previousHeader = this.getHeader();
 		const target = createUniqueSessionFileTarget(dir);
 		this.sessionDir = dir;
 		this.sessionId = target.sessionId;
@@ -1318,6 +1362,8 @@ export class SessionManager {
 			id: this.sessionId,
 			timestamp,
 			cwd: this.cwd,
+			parentSession: previousHeader?.parentSession,
+			rlmDepth: previousHeader?.rlmDepth ?? (previousHeader?.parentSession ? undefined : 0),
 			git,
 		};
 		this.fileEntries = [header, ...this.getEntries()];
@@ -1941,6 +1987,7 @@ export class SessionManager {
 			timestamp,
 			cwd: this.cwd,
 			parentSession: this.persist ? previousSessionFile : undefined,
+			rlmDepth: this.getHeader()?.rlmDepth,
 			git: this.persist ? (captureGitContext(this.cwd) ?? undefined) : undefined,
 		};
 
@@ -2134,6 +2181,7 @@ export class SessionManager {
 			timestamp,
 			cwd: targetCwd,
 			parentSession: sourcePath,
+			rlmDepth: sourceHeader.rlmDepth,
 			git: captureGitContext(targetCwd) ?? undefined,
 		};
 		appendFileSync(newSessionFile, `${JSON.stringify(newHeader)}\n`);

packages/coding-agent/src/modes/agent-connection/types.ts

@@ -60,6 +60,7 @@ export interface AgentConnectionSessionHeader {
 	timestamp: string;
 	cwd: string;
 	parentSession?: string;
+	rlmDepth?: number;
 	git?: {
 		repoUrl?: string;
 		commit?: string;
@@ -122,6 +123,7 @@ export interface AgentConnectionSavedSessionInfo {
 	name?: string;
 	state?: AgentConnectionSavedSessionState;
 	parentSessionPath?: string;
+	rlmDepth?: number;
 	created: Date;
 	modified: Date;
 	messageCount: number;

packages/coding-agent/src/modes/daemon/daemon-mode.ts

@@ -141,7 +141,6 @@ import {
 	type DaemonCommand,
 	type DaemonOutbound,
 	type DaemonResponse,
-	type DaemonSavedSessionInfo,
 	type DaemonSessionClosedReason,
 	type DaemonSessionSnapshot,
 	type DaemonUpdateRestartManifest,
@@ -186,6 +185,7 @@ import {
 	SESSION_LEASES_ENABLED_ENV,
 } from "./daemon-worker-protocol.js";
 import { MutationDrainLatch } from "./mutation-drain-latch.js";
+import { serializeSavedSessionInfo } from "./saved-session-info.js";
 import {
 	createSnapshotTranscriptChunks,
 	SNAPSHOT_TARGET_CHUNK_BYTES,
@@ -1070,9 +1070,9 @@ export class AgentDaemon {
 					parentEntry?.sessionFile ??
 					passive.rootParentState?.runtime.session.sessionFile ??
 					passive.rootInfo?.path,
+				rlmDepth: passive.info.rlmDepth ?? passive.entry.rlmDepth,
 				rlmChildId: passive.entry.childId,
 				rlmParentNodeId: passive.entry.rlmParentNodeId ?? passive.entry.childId,
-				...(!passive.rootParentState ? { rlmDepth: passive.entry.rlmDepth } : {}),
 				spawnCode: passive.entry.spawnCode,
 			};
 		});
@@ -2146,7 +2146,10 @@ export class AgentDaemon {
 	): Promise<AgentSessionRuntime> {
 		const sessionManager = SessionManager.create(options.parentSession.sessionManager.getCwd(), options.sessionDir);
 		if (options.parentSession.sessionFile) {
-			sessionManager.newSession({ parentSession: options.parentSession.sessionFile });
+			sessionManager.newSession({
+				parentSession: options.parentSession.sessionFile,
+				rlmDepth: options.rlmDepth,
+			});
 		}
 		let stateRef: ActiveSessionState | undefined;
 		// Subagents inherit the parent's client env (e.g. herdr pane identity).
@@ -2364,7 +2367,7 @@ export class AgentDaemon {
 							},
 						},
 						rlmSessionDir: entry.sessionDir,
-						rlmDepth: entry.rlmDepth ?? 1,
+						rlmDepth: entry.rlmDepth,
 						rlmMaxDepth: entry.rlmMaxDepth ?? 1,
 						rlmParentNodeId: entry.rlmParentNodeId ?? entry.childId,
 					},
@@ -5580,23 +5583,6 @@ function hasDaemonOutboundActiveSessionId(
 	return "activeSessionId" in message && typeof message.activeSessionId === "string";
 }
 
-function serializeSavedSessionInfo(session: SessionInfo): DaemonSavedSessionInfo {
-	return {
-		path: session.path,
-		id: session.id,
-		cwd: session.cwd,
-		name: session.name,
-		state: session.state,
-		parentSessionPath: session.parentSessionPath,
-		created: session.created.toISOString(),
-		modified: session.modified.toISOString(),
-		messageCount: session.messageCount,
-		firstMessage: session.firstMessage,
-		allMessagesText: session.allMessagesText,
-		agentStatus: session.agentStatus,
-	};
-}
-
 export function getChildActiveSessionStates(
 	sessions: ReadonlyMap<string, ActiveSessionState>,
 	parentState: ActiveSessionState,

packages/coding-agent/src/modes/daemon/daemon-protocol.ts

@@ -52,8 +52,9 @@ export const DAEMON_PROTOCOL_NAME = "prime-agent.daemon";
 export const DAEMON_PROTOCOL_VERSION = 7;
 export const DAEMON_COMMAND_ENVELOPE_MIN_PROTOCOL_VERSION = 7;
 // Revision 9 publishes persisted RLM spawn depth on passive session rows.
-export const DAEMON_SCHEMA_REVISION = 9;
-export const DAEMON_SCHEMA_ID = "protocol-7-schema-9-b56e29842cfa";
+// Revision 10 publishes persisted RLM spawn depth on all session catalog rows.
+export const DAEMON_SCHEMA_REVISION = 10;
+export const DAEMON_SCHEMA_ID = "protocol-7-schema-10-37a654228732";
 
 export type DaemonProtocolName = typeof DAEMON_PROTOCOL_NAME;
 export type DaemonProtocolVersion = number;
@@ -779,6 +780,7 @@ export interface DaemonSavedSessionInfo {
 	name?: string;
 	state?: AgentConnectionSavedSessionState;
 	parentSessionPath?: string;
+	rlmDepth?: number;
 	created: string;
 	modified: string;
 	messageCount: number;

packages/coding-agent/src/modes/daemon/daemon-session-list.ts

@@ -32,7 +32,7 @@ export interface SessionSummary {
 	isSessionActive: boolean;
 	hasActiveHeartbeat?: boolean;
 	runtimeKind?: "top-level" | "subagent";
-	/** RLM spawn depth for persisted passive subagent rows. */
+	/** RLM spawn depth (0 for roots); fork edges preserve the source depth. */
 	rlmDepth?: number;
 	activeSessionId?: string;
 	sessionId: string;
@@ -167,6 +167,7 @@ export function summaryForActiveSession(
 		isSessionActive: session.isSessionActive,
 		hasActiveHeartbeat: hasActiveHeartbeat || undefined,
 		runtimeKind: metadata.kind,
+		rlmDepth: session.rlmDepth,
 		activeSessionId: activeSession.activeSessionId,
 		sessionId: session.sessionId,
 		sessionFile: session.sessionFile,
@@ -238,6 +239,7 @@ export function summaryForInactiveSession(session: SessionInfo): SessionSummary
 		modified: session.modified.toISOString(),
 		firstMessage: session.firstMessage,
 		parentSessionPath: session.parentSessionPath,
+		rlmDepth: session.rlmDepth,
 		// Carry the persisted recap/verdict so an off-daemon session keeps its
 		// agents-view bucket (e.g. Completed) instead of defaulting to Needs Input.
 		// Gate on message-count currency like isSummaryCurrent does for resident

packages/coding-agent/src/modes/daemon/daemon-supervisor.ts

@@ -56,7 +56,6 @@ import {
 	type DaemonCommand,
 	type DaemonOutbound,
 	type DaemonResponse,
-	type DaemonSavedSessionInfo,
 	type DaemonUpdateRestartManifest,
 	failure,
 	isDaemonCommandEnvelope,
@@ -100,6 +99,7 @@ import {
 	SESSION_LEASES_ENABLED_ENV,
 } from "./daemon-worker-protocol.js";
 import { MutationDrainLatch } from "./mutation-drain-latch.js";
+import { serializeSavedSessionInfo } from "./saved-session-info.js";
 import { SNAPSHOT_TARGET_CHUNK_BYTES, SnapshotTranscriptCache } from "./snapshot-transcript-cache.js";
 import { WorkerRecoveryJournal } from "./worker-recovery-journal.js";
 
@@ -456,23 +456,6 @@ function sortCronJobs(jobs: AgentCronJob[]): AgentCronJob[] {
 	});
 }
 
-function serializeSavedSessionInfo(session: SessionInfo): DaemonSavedSessionInfo {
-	return {
-		path: session.path,
-		id: session.id,
-		cwd: session.cwd,
-		name: session.name,
-		state: session.state,
-		parentSessionPath: session.parentSessionPath,
-		created: session.created.toISOString(),
-		modified: session.modified.toISOString(),
-		messageCount: session.messageCount,
-		firstMessage: session.firstMessage,
-		allMessagesText: session.allMessagesText,
-		agentStatus: session.agentStatus,
-	};
-}
-
 function descriptorKey(socketPath: string): string {
 	return createHash("sha256").update(socketPath).digest("hex").slice(0, 12);
 }