feat: populate parentTargetRef on clarification entities

Derive from resolvedOperation.targetRef when creating clarifications.
Close prior open clarifications (one-open-per-workflow invariant).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: MaxLinCode

apps/web/src/lib/server/conversation-state.test.ts

@@ -154,6 +154,7 @@ describe("deriveConversationReplyState", () => {
           prompt: "What time should I schedule it?",
           reason: "time",
           open: true,
+          parentTargetRef: null,
         },
       },
     ];
@@ -276,6 +277,7 @@ describe("deriveConversationReplyState", () => {
           prompt: "What time should I schedule it?",
           reason: "time",
           open: true,
+          parentTargetRef: null,
         },
       },
     ];
@@ -331,6 +333,134 @@ describe("deriveConversationReplyState", () => {
       ]),
     );
   });
+
+  it("sets parentTargetRef on clarification entity from resolvedOperation targetRef", () => {
+    const op = buildPendingWriteOperation({
+      targetRef: { entityId: "task-1" },
+      resolvedFields: { scheduleFields: { day: "tomorrow" } },
+      missingFields: ["scheduleFields.time"],
+    });
+
+    const result = deriveConversationReplyState({
+      snapshot: buildSnapshot(),
+      policy: {
+        action: "ask_clarification",
+        clarificationSlots: ["scheduleFields.time"],
+        resolvedOperation: op,
+      },
+      interpretation: {
+        turnType: "planning_request",
+        confidence: 0.58,
+        resolvedEntityIds: [],
+        ambiguity: "high",
+        missingFields: ["scheduleFields.time"],
+      },
+      reply: "What time should I schedule it?",
+      userTurnText: "schedule gym tomorrow",
+      summaryText: null,
+      occurredAt: "2026-03-22T16:05:00.000Z",
+    });
+
+    const clarEntity = result.entityRegistry.find((e) => e.kind === "clarification");
+    expect(clarEntity).toBeDefined();
+    expect(clarEntity!.data.parentTargetRef).toEqual({ entityId: "task-1" });
+  });
+
+  it("sets parentTargetRef to null on clarification entity for new plans", () => {
+    const op = buildPendingWriteOperation({
+      targetRef: null,
+      resolvedFields: { scheduleFields: { day: "tomorrow" } },
+      missingFields: ["scheduleFields.time"],
+    });
+
+    const result = deriveConversationReplyState({
+      snapshot: buildSnapshot(),
+      policy: {
+        action: "ask_clarification",
+        clarificationSlots: ["scheduleFields.time"],
+        resolvedOperation: op,
+      },
+      interpretation: {
+        turnType: "planning_request",
+        confidence: 0.58,
+        resolvedEntityIds: [],
+        ambiguity: "high",
+        missingFields: ["scheduleFields.time"],
+      },
+      reply: "What time should I schedule it?",
+      userTurnText: "schedule gym tomorrow",
+      summaryText: null,
+      occurredAt: "2026-03-22T16:05:00.000Z",
+    });
+
+    const clarEntity = result.entityRegistry.find((e) => e.kind === "clarification");
+    expect(clarEntity).toBeDefined();
+    expect(clarEntity!.data.parentTargetRef).toBeNull();
+  });
+
+  it("closes prior open clarification when a new one is created", () => {
+    const snapshot = buildSnapshot();
+    snapshot.entityRegistry = [
+      {
+        id: "clar-old",
+        conversationId: "conversation-1",
+        kind: "clarification",
+        label: "Need a time",
+        status: "active",
+        createdAt: "2026-03-22T16:01:00.000Z",
+        updatedAt: "2026-03-22T16:01:00.000Z",
+        data: { prompt: "What time?", reason: "scheduleFields.time", open: true, parentTargetRef: null },
+      },
+    ];
+    snapshot.discourseState = {
+      focus_entity_id: "clar-old",
+      currently_editable_entity_id: null,
+      last_user_mentioned_entity_ids: [],
+      last_presented_items: [],
+      pending_clarifications: [
+        { id: "clar-old", slot: "scheduleFields.time", question: "What time?", status: "pending", createdAt: "2026-03-22T16:01:00.000Z", createdTurnId: "assistant:1", parentTargetRef: null },
+      ],
+      mode: "clarifying",
+    };
+
+    const op = buildPendingWriteOperation({
+      targetRef: null,
+      resolvedFields: { scheduleFields: { day: "tomorrow" } },
+      missingFields: ["scheduleFields.duration"],
+    });
+
+    const result = deriveConversationReplyState({
+      snapshot,
+      policy: {
+        action: "ask_clarification",
+        clarificationSlots: ["scheduleFields.duration"],
+        resolvedOperation: op,
+      },
+      interpretation: {
+        turnType: "clarification_answer",
+        confidence: 0.8,
+        resolvedEntityIds: [],
+        ambiguity: "high",
+        missingFields: ["scheduleFields.duration"],
+      },
+      reply: "Got it, 5pm. How long should it be?",
+      userTurnText: "5pm",
+      summaryText: null,
+      occurredAt: "2026-03-22T16:06:00.000Z",
+    });
+
+    const oldClar = result.entityRegistry.find((e) => e.id === "clar-old");
+    expect(oldClar).toMatchObject({
+      status: "resolved",
+      data: expect.objectContaining({ open: false }),
+    });
+
+    const newClars = result.entityRegistry.filter(
+      (e) => e.kind === "clarification" && e.data.open === true,
+    );
+    expect(newClars).toHaveLength(1);
+    expect(newClars[0]!.data).toMatchObject({ reason: "scheduleFields.duration" });
+  });
 });
 
 describe("deriveMutationState", () => {
@@ -349,6 +479,7 @@ describe("deriveMutationState", () => {
           prompt: "What time should I schedule it?",
           reason: "time",
           open: true,
+          parentTargetRef: null,
         },
       },
     ];

apps/web/src/lib/server/conversation-state.ts

@@ -129,6 +129,23 @@ export function deriveConversationReplyState(
       );
     }
 
+    const parentTargetRef =
+      input.policy.resolvedOperation?.targetRef ?? null;
+
+    // Close any prior open clarifications (one-open-per-workflow)
+    for (let i = 0; i < entityRegistry.length; i++) {
+      const entity = entityRegistry[i]!;
+      if (entity.kind === "clarification" && entity.data.open) {
+        entityRegistry[i] = {
+          ...entity,
+          status: "resolved" as const,
+          updatedAt: occurredAt,
+          data: { ...entity.data, open: false },
+        };
+        resolvedClarificationIds.push(entity.id);
+      }
+    }
+
     const clarificationEntity = buildConversationEntity(
       input.snapshot.conversation.id,
       {
@@ -141,6 +158,7 @@ export function deriveConversationReplyState(
           prompt: input.reply,
           reason: clarificationSlot,
           open: true,
+          parentTargetRef,
         },
       },
     );
@@ -277,6 +295,7 @@ export function deriveMutationState(input: DeriveMutationStateInput) {
           prompt: input.processing.followUpMessage,
           reason: input.processing.reason,
           open: true,
+          parentTargetRef: null,
         },
       },
     );