Polish per review: clarify doc comment, add null-safe parent test

Update the LinkSubagentSessions doc comment to cover the re-parenting of nested
subagents (it previously described only the type upgrade). Add
TestLinkSubagentSessionsLinksNullParentSubagent: a 'subagent'-tagged session
with a NULL parent plus a spawn edge must be linked to its spawner. The test
fails if the null-safe `IS NOT` is replaced with `!=` (mutation-verified), and
was suggested independently by two reviewers.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Nick

internal/db/link_subagent_nested_test.go

@@ -142,3 +142,43 @@ func TestLinkSubagentSessionsUpgradesTypeWhenParentAlreadyMatches(t *testing.T)
 			"child.parent_session_id")
 	}
 }
+
+// TestLinkSubagentSessionsLinksNullParentSubagent guards the null-safe `IS NOT`
+// predicate. A session already tagged 'subagent' but with a NULL parent (and a
+// tool_calls spawn edge) must be linked to its spawner. Replacing `IS NOT` with
+// `!=` would leave the parent NULL (`NULL != 'x'` is NULL, not true), so this
+// test fails under that mutation.
+func TestLinkSubagentSessionsLinksNullParentSubagent(t *testing.T) {
+	d := testDB(t)
+
+	insertSession(t, d, "spawner", "p", func(s *Session) {
+		s.MessageCount = 1
+	})
+
+	// Already tagged 'subagent' (so the type branch is false) but its parent
+	// was never set. Only the null-safe parent branch can link it.
+	insertSession(t, d, "orphan", "p", func(s *Session) {
+		s.MessageCount = 1
+		s.RelationshipType = "subagent"
+		// ParentSessionID left nil -> NULL in the DB.
+	})
+
+	insertMessages(t, d, Message{
+		SessionID: "spawner", Ordinal: 0, Role: "assistant",
+		Content: "spawn orphan", HasToolUse: true,
+		ToolCalls: []ToolCall{{
+			ToolName: "Agent", Category: "Task",
+			SubagentSessionID: "orphan",
+		}},
+	})
+
+	require.NoError(t, d.LinkSubagentSessions(), "LinkSubagentSessions")
+
+	orphan, err := d.GetSession(context.Background(), "orphan")
+	requireNoError(t, err, "GetSession orphan")
+	if assert.NotNil(t, orphan.ParentSessionID,
+		"NULL-parent subagent must be linked to its spawner (null-safe IS NOT)") {
+		assert.Equal(t, "spawner", *orphan.ParentSessionID,
+			"orphan.parent_session_id")
+	}
+}

internal/db/sessions.go

@@ -1544,11 +1544,15 @@ func (db *DB) GetChildSessions(
 }
 
 // LinkSubagentSessions sets parent_session_id and
-// relationship_type on sessions that are referenced by
-// tool_calls.subagent_session_id. Updates sessions that either
-// have no parent yet or have a non-subagent relationship (e.g.
-// a Zencoder session classified as "continuation" from header
-// parentId that is actually a spawned subagent).
+// relationship_type on sessions referenced by
+// tool_calls.subagent_session_id (the authoritative spawn edge).
+// A session is updated when it is not yet tagged 'subagent' (e.g.
+// a Zencoder session classified as "continuation" from a header
+// parentId that is actually a spawned subagent) OR when its stored
+// parent disagrees with the spawn edge. The latter re-parents
+// nested subagents (depth >= 2), which the parser pins to the main
+// session because Claude Code stores every subagent flat under
+// <main>/subagents/. Already-correct subagents are left untouched.
 func (db *DB) LinkSubagentSessions() error {
 	db.mu.Lock()
 	defer db.mu.Unlock()