fix(coding-agent): correct rlmDepth semantics on reference edges, env parsing, and legacy fallbacks

- Finding 8: new-session parent links were deriving spawn depth; copy the source header depth across the reference edge and add a runtime regression test (origin: PR #584).
- Finding 9: first-entry forks of legacy sessions discarded effective runtime depth; fall back to session.rlmDepth in persisted and in-memory branches and test both (origin: PR #584).
- Finding 10: root RLM_DEPTH parsing accepted malformed and unsafe values; require decimal digits and a valid safe non-negative integer, with probe cases as tests (origin: PR #584).
- Finding 11: child-depth derivation could overflow MAX_SAFE_INTEGER; guard the increment and test the boundary (origin: PR #584).
- Finding 12: daemon children of in-memory parents skipped explicit depth persistence; always create the child header with explicit depth and test --no-session ancestry (origin: PR #584).
- Finding 13: legacy completed subagents rehydrated at root depth; restore the depth-one fallback and test a registry/header pair without depth (origin: PR #584).

Author: snimu

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

@@ -512,7 +512,10 @@ export class AgentSessionRuntime implements SubagentRuntimeHost {
 		const sessionDir = this.session.sessionManager.getSessionDir();
 		const sessionManager = SessionManager.create(this.cwd, sessionDir);
 		if (options?.parentSession) {
-			sessionManager.newSession({ parentSession: options.parentSession });
+			sessionManager.newSession({
+				parentSession: options.parentSession,
+				rlmDepth: this.session.sessionManager.getHeader()?.rlmDepth,
+			});
 		}
 		const lease = this.acquireReplacementLease(sessionManager.getSessionFile());
 
@@ -577,7 +580,7 @@ export class AgentSessionRuntime implements SubagentRuntimeHost {
 				const sessionManager = SessionManager.create(this.cwd, sessionDir);
 				sessionManager.newSession({
 					parentSession: currentSessionFile,
-					rlmDepth: sourceHeader?.rlmDepth,
+					rlmDepth: sourceHeader?.rlmDepth ?? this.session.rlmDepth,
 				});
 				const lease = this.acquireReplacementLease(sessionManager.getSessionFile());
 				await this.teardownForReplacement("fork", sessionManager.getSessionFile(), lease);
@@ -628,7 +631,7 @@ export class AgentSessionRuntime implements SubagentRuntimeHost {
 			const sourceHeader = sessionManager.getHeader();
 			sessionManager.newSession({
 				parentSession: this.session.sessionFile,
-				rlmDepth: sourceHeader?.rlmDepth,
+				rlmDepth: sourceHeader?.rlmDepth ?? this.session.rlmDepth,
 			});
 		} else {
 			sessionManager.createBranchedSession(targetLeafId);

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

@@ -703,16 +703,17 @@ function isValidRlmDepth(value: unknown): value is number {
 }
 
 function deriveChildRlmDepth(parentHeader: Partial<SessionHeader> | undefined): number | undefined {
-	return isValidRlmDepth(parentHeader?.rlmDepth) ? parentHeader.rlmDepth + 1 : undefined;
+	const depth = parentHeader?.rlmDepth;
+	return isValidRlmDepth(depth) && depth < Number.MAX_SAFE_INTEGER ? depth + 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) {
+	const parsed = Number(value);
+	if (!/^\d+$/.test(value) || !isValidRlmDepth(parsed)) {
 		throw new Error("RLM_DEPTH must be a non-negative integer");
 	}
 	return parsed;

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

@@ -2179,12 +2179,10 @@ export class AgentDaemon {
 		options: CreateRlmSubagentRuntimeOptions,
 	): Promise<AgentSessionRuntime> {
 		const sessionManager = SessionManager.create(options.parentSession.sessionManager.getCwd(), options.sessionDir);
-		if (options.parentSession.sessionFile) {
-			sessionManager.newSession({
-				parentSession: options.parentSession.sessionFile,
-				rlmDepth: options.rlmDepth,
-			});
-		}
+		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).
 		const runtime = await withClientEnv(parentState.clientEnv, () =>
@@ -2530,7 +2528,7 @@ export class AgentDaemon {
 							},
 						},
 						rlmSessionDir: entry.sessionDir,
-						rlmDepth: entry.rlmDepth,
+						rlmDepth: entry.rlmDepth ?? 1,
 						rlmMaxDepth: entry.rlmMaxDepth,
 						rlmParentNodeId: entry.rlmParentNodeId ?? entry.childId,
 					},

packages/coding-agent/test/daemon-mode.test.ts

@@ -483,6 +483,58 @@ describe("daemon mode helpers", () => {
 		}
 	});
 
+	it("persists explicit child depth for an in-memory daemon parent", async () => {
+		const tempDir = mkdtempSync(join(tmpdir(), "prime-agent-daemon-in-memory-parent-depth-"));
+		try {
+			const createRuntime = vi.fn(async (options: Parameters<CreateAgentSessionRuntimeFactory>[0]) => ({
+				session: makeRuntimeSession(options.sessionManager),
+				extensionsResult: { extensions: [], errors: [], runtime: {} } as unknown as Awaited<
+					ReturnType<CreateAgentSessionRuntimeFactory>
+				>["extensionsResult"],
+				services: { cwd: options.cwd, agentDir: options.agentDir } as Awaited<
+					ReturnType<CreateAgentSessionRuntimeFactory>
+				>["services"],
+				diagnostics: [],
+			}));
+			const daemon = new AgentDaemon(join(tempDir, "daemon.sock"), {
+				defaultSessionConfig: { agentDir: tempDir, cwd: tempDir, sessionDir: join(tempDir, "sessions") },
+				createRuntime,
+			});
+			const internals = daemon as unknown as {
+				createRuntime(command: Extract<DaemonCommand, { type: "create" }>): Promise<ActiveSessionState>;
+				createRlmSubagentRuntime(
+					parentState: ActiveSessionState,
+					options: CreateRlmSubagentRuntimeOptions,
+				): Promise<ActiveSessionState["runtime"]>;
+			};
+			const parentState = await internals.createRuntime({ type: "create", noSession: true });
+			const child = await internals.createRlmSubagentRuntime(parentState, {
+				parentSession: parentState.runtime.session,
+				id: "child-1",
+				prompt: "persist depth",
+				sessionName: "depth-child",
+				sessionDir: join(tempDir, "child"),
+				model: {} as Model<Api>,
+				thinkingLevel: "off",
+				serviceTier: null,
+				scopedModels: [],
+				activeToolNames: [],
+				customTools: [],
+				includeGoals: false,
+				includeCompactSkill: false,
+				rlmDepth: 1,
+				rlmMaxDepth: 2,
+				rlmParentNodeId: "child-1",
+			});
+
+			expect(parentState.runtime.session.sessionFile).toBeUndefined();
+			expect(child.session.sessionManager.getHeader()).toMatchObject({ rlmDepth: 1 });
+			expect(child.session.sessionManager.getHeader()?.parentSession).toBeUndefined();
+		} finally {
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
 	it("defers RLM heartbeats while a subagent is binding", async () => {
 		const tempDir = mkdtempSync(join(tmpdir(), "prime-agent-daemon-binding-heartbeat-"));
 		let releaseChildBinding: (() => void) | undefined;
@@ -3943,6 +3995,42 @@ describe("daemon mode helpers", () => {
 		}
 	});
 
+	it("rehydrates a legacy passive subagent at depth one", async () => {
+		const tempDir = mkdtempSync(join(tmpdir(), "prime-agent-daemon-legacy-rlm-depth-"));
+		try {
+			const fixture = makePersistedRlmDaemonFixture(tempDir);
+			const childLines = readFileSync(fixture.childSessionFile, "utf8").split("\n");
+			const childHeader = JSON.parse(childLines[0] ?? "{}") as Record<string, unknown>;
+			delete childHeader.rlmDepth;
+			childLines[0] = JSON.stringify(childHeader);
+			writeFileSync(fixture.childSessionFile, childLines.join("\n"));
+
+			const registryPath = join(fixture.parentArtifactDir, "rlm-subagents.jsonl");
+			const registryEntry = JSON.parse(readFileSync(registryPath, "utf8").trim()) as Record<string, unknown>;
+			delete registryEntry.rlmDepth;
+			writeFileSync(registryPath, `${JSON.stringify(registryEntry)}\n`);
+
+			const internals = fixture.daemon as unknown as {
+				createRuntime(command: Extract<DaemonCommand, { type: "create" }>): Promise<ActiveSessionState>;
+				createAgentMessageController(
+					getCurrentState: () => ActiveSessionState | undefined,
+				): AgentSessionMessageController;
+			};
+			const parentState = await internals.createRuntime({
+				type: "create",
+				sessionPath: fixture.parentSessionFile,
+			});
+
+			await internals
+				.createAgentMessageController(() => parentState)
+				.sendAgentMessage({ target: "renamed-worker", message: "report progress" });
+
+			expect(fixture.createRuntime.mock.calls[1]?.[0].sessionOptions?.rlmDepth).toBe(1);
+		} finally {
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
 	it("hydrates only the ancestor chain when a nested passive child is messaged", async () => {
 		const tempDir = mkdtempSync(join(tmpdir(), "prime-agent-daemon-lazy-nested-message-"));
 		try {

packages/coding-agent/test/session-manager/file-operations.test.ts

@@ -157,6 +157,37 @@ describe("loadEntriesFromFile", () => {
 });
 
 describe("session tree metadata", () => {
+	it.each(["2.5", "2oops", "9007199254740993"])("rejects invalid RLM_DEPTH value %s", (value) => {
+		const tempDir = join(tmpdir(), `invalid-root-depth-test-${Date.now()}-${Math.random()}`);
+		mkdirSync(tempDir, { recursive: true });
+		vi.stubEnv("RLM_DEPTH", value);
+		try {
+			expect(() => SessionManager.create(tempDir, tempDir)).toThrow("RLM_DEPTH must be a non-negative integer");
+		} finally {
+			vi.unstubAllEnvs();
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it("does not persist an unsafe derived depth", () => {
+		const tempDir = join(tmpdir(), `max-parent-depth-test-${Date.now()}-${Math.random()}`);
+		mkdirSync(tempDir, { recursive: true });
+		try {
+			const parent = SessionManager.create(tempDir, tempDir);
+			parent.newSession({ rlmDepth: Number.MAX_SAFE_INTEGER });
+			parent.flushNow();
+			const parentFile = parent.getSessionFile();
+			if (!parentFile) throw new Error("Missing parent session file");
+
+			const child = SessionManager.create(tempDir, tempDir);
+			child.newSession({ parentSession: parentFile });
+
+			expect(child.getHeader()?.rlmDepth).toBeUndefined();
+		} finally {
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
 	it("persists a derived depth and exposes parent linkage from the header", async () => {
 		const tempDir = join(tmpdir(), `session-tree-test-${Date.now()}-${Math.random()}`);
 		mkdirSync(tempDir, { recursive: true });

packages/coding-agent/test/suite/agent-session-runtime.test.ts

@@ -52,6 +52,8 @@ describe("AgentSessionRuntime characterization", () => {
 			bootstrapThinkingLevel?: boolean;
 			inMemory?: boolean;
 			sessionConfig?: AgentSessionRuntimeConfig;
+			sessionManager?: SessionManager;
+			sessionOptions?: Parameters<CreateAgentSessionRuntimeFactory>[0]["sessionOptions"];
 			onCreateRuntime?: (options: Parameters<CreateAgentSessionRuntimeFactory>[0]) => void;
 		},
 	) {
@@ -115,6 +117,7 @@ describe("AgentSessionRuntime characterization", () => {
 					sessionStartEvent,
 					model: serviceOptions.model,
 					thinkingLevel: serviceOptions.thinkingLevel,
+					...runtimeOptions.sessionOptions,
 				})),
 				services,
 				diagnostics: services.diagnostics,
@@ -123,10 +126,13 @@ describe("AgentSessionRuntime characterization", () => {
 		const runtime = await createAgentSessionRuntime(createRuntime, {
 			cwd: tempDir,
 			agentDir: tempDir,
-			sessionManager: options?.inMemory
-				? SessionManager.inMemory(tempDir)
-				: SessionManager.create(tempDir, join(tempDir, "sessions")),
+			sessionManager:
+				options?.sessionManager ??
+				(options?.inMemory
+					? SessionManager.inMemory(tempDir)
+					: SessionManager.create(tempDir, join(tempDir, "sessions"))),
 			sessionConfig: options?.sessionConfig,
+			sessionOptions: options?.sessionOptions,
 		});
 		await runtime.session.bindExtensions({});
 
@@ -183,6 +189,38 @@ describe("AgentSessionRuntime characterization", () => {
 		expect(calls[1]?.sessionConfig).toBe(sessionConfig);
 	});
 
+	it("copies depth across new-session parent reference edges", async () => {
+		const { runtime } = await createRuntimeForTest(() => {});
+		const parentSession = runtime.session.sessionFile;
+		if (!parentSession) throw new Error("Missing parent session file");
+
+		await runtime.newSession({ parentSession });
+
+		expect(runtime.session.sessionManager.getHeader()).toMatchObject({ parentSession, rlmDepth: 0 });
+	});
+
+	it.each([false, true])(
+		"uses the effective runtime depth when forking a legacy session before its first entry (inMemory=%s)",
+		async (inMemory) => {
+			const tempDir = join(tmpdir(), `pi-runtime-legacy-fork-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+			const sessionManager = inMemory
+				? SessionManager.inMemory(tempDir)
+				: SessionManager.create(tempDir, join(tempDir, "sessions"));
+			sessionManager.newSession({ rlmDepth: undefined });
+			const firstEntry = sessionManager.appendMessage({ role: "user", content: "fork here", timestamp: 1 });
+			const { runtime } = await createRuntimeForTest(() => {}, {
+				cwd: tempDir,
+				sessionManager,
+				sessionOptions: { rlmDepth: 2 },
+			});
+
+			await runtime.fork(firstEntry);
+
+			expect(runtime.session.sessionManager.getHeader()?.rlmDepth).toBe(2);
+			expect(runtime.session.rlmDepth).toBe(2);
+		},
+	);
+
 	it("disposes a runtime only once across repeated teardown calls", async () => {
 		const shutdownEvents: SessionShutdownEvent[] = [];
 		const beforeInvalidate = vi.fn();
@@ -694,6 +732,7 @@ describe("AgentSessionRuntime characterization", () => {
 		});
 		await otherRuntime.session.prompt("other");
 		const otherSessionFile = otherRuntime.session.sessionFile!;
+		await otherRuntime.dispose();
 
 		await runtime.switchSession(otherSessionFile);
 
@@ -769,6 +808,7 @@ describe("AgentSessionRuntime characterization", () => {
 		otherRuntime.session.setThinkingLevel("off");
 		await otherRuntime.session.prompt("hello");
 		const targetSessionFile = otherRuntime.session.sessionFile!;
+		await otherRuntime.dispose();
 
 		await runtime.switchSession(targetSessionFile);