fix(agents): validate explicit side-branch cursors

steipete · scotthuang · steipete · commit 766166bcc2d9 · 2026-07-06T01:08:36.000+01:00
Co-authored-by: scotthuang &lt;scotthuang@tencent.com&gt;
diff --git a/src/agents/sessions/session-manager.test.ts b/src/agents/sessions/session-manager.test.ts
@@ -2042,6 +2042,83 @@ describe("SessionManager.open", () => {
     expect(sessionManager.getEntries()).toHaveLength(entryCount);
   });
 
+  it("rejects an unowned side leaf that resets a non-root side cursor", async () => {
+    const dir = await makeTempDir();
+    const sessionManager = SessionManager.create(dir, dir);
+    sessionManager.appendMessage({ role: "user", content: "question", timestamp: 1 });
+    const activeLeafId = sessionManager.appendMessage(buildAssistantMessage("base answer"));
+    const entryCount = sessionManager.getEntries().length;
+    const sideEntry = {
+      type: "message" as const,
+      id: "side-delivery-before-root-reset",
+      parentId: activeLeafId,
+      timestamp: "2026-07-05T00:00:01.000Z",
+      message: buildAssistantMessage("side delivery"),
+    };
+
+    expect(() =>
+      sessionManager.mergePromptReleasedSessionEntries([
+        sideEntry,
+        {
+          type: "prompt_released_opaque",
+          preserveActiveLeaf: true,
+          record: {
+            type: "leaf",
+            id: "unowned-root-reset-leaf",
+            parentId: sideEntry.id,
+            timestamp: "2026-07-05T00:00:02.000Z",
+            targetId: activeLeafId,
+            appendParentId: null,
+            appendMode: "side",
+          },
+        },
+      ]),
+    ).toThrow("prompt-released side leaf changed the active branch");
+    expect(sessionManager.getLeafId()).toBe(activeLeafId);
+    expect(sessionManager.getEntries()).toHaveLength(entryCount);
+  });
+
+  it("accepts an explicit root side cursor when it matches the current side branch", async () => {
+    const dir = await makeTempDir();
+    const sessionManager = SessionManager.create(dir, dir);
+    sessionManager.appendMessage({ role: "user", content: "question", timestamp: 1 });
+    const activeLeafId = sessionManager.appendMessage(buildAssistantMessage("base answer"));
+
+    sessionManager.mergePromptReleasedSessionEntries([
+      {
+        type: "prompt_released_opaque",
+        record: {
+          type: "leaf",
+          id: "owned-root-side-leaf",
+          parentId: activeLeafId,
+          timestamp: "2026-07-05T00:00:01.000Z",
+          targetId: activeLeafId,
+          appendParentId: null,
+          appendMode: "side",
+        },
+      },
+    ]);
+
+    expect(() =>
+      sessionManager.mergePromptReleasedSessionEntries([
+        {
+          type: "prompt_released_opaque",
+          preserveActiveLeaf: true,
+          record: {
+            type: "leaf",
+            id: "unowned-root-side-leaf",
+            parentId: null,
+            timestamp: "2026-07-05T00:00:02.000Z",
+            targetId: activeLeafId,
+            appendParentId: null,
+            appendMode: "side",
+          },
+        },
+      ]),
+    ).not.toThrow();
+    expect(sessionManager.getLeafId()).toBe(activeLeafId);
+  });
+
   it("applies merged leaf controls across separate callbacks", async () => {
     const dir = await makeTempDir();
     const sessionManager = SessionManager.create(dir, dir);
diff --git a/src/agents/sessions/session-manager.ts b/src/agents/sessions/session-manager.ts
@@ -2342,7 +2342,8 @@ export class SessionManager {
       }
       const leaf = parseOpaqueLeafEntry(entry.record);
       if (leaf && entry.preserveActiveLeaf) {
-        const appendParentId = leaf.appendParentId ?? leaf.targetId;
+        const appendParentId =
+          leaf.appendParentId === undefined ? leaf.targetId : leaf.appendParentId;
         if (
           leaf.appendMode !== "side" ||
           leaf.targetId !== this.leafId ||
