core/agent: todo stack is LIFO of task groups, not per-task push

push(titles) creates one group of siblings; pop removes the whole top
group. Matches breakdown: push[T1,T2] → push[T1.1,T1.2] → pop → push[T2.1].

tests/test_agent/test_todo_stack.py

@@ -30,46 +30,54 @@ def test_parse_push_titles() -> None:
     assert parse_push_titles('["A", "B"]') == ["A", "B"]
 
 
-def test_lifo_not_queue() -> None:
-    """Stack is LIFO: push A then B → top is B; pop is B then A — never FIFO."""
+def test_push_is_group_not_per_task_stack() -> None:
+    """Multi-title push is one group; pop removes the whole group."""
     stack = TodoStack()
-    _ = stack.push("A")
-    _ = stack.push("B")
-    assert stack.top is not None
-    assert stack.top.title == "B"
-    first = stack.pop()
-    second = stack.pop()
-    assert first is not None and first.title == "B"
-    assert second is not None and second.title == "A"
-    assert stack.pop() is None
+    g = stack.push_group(["T1", "T2"])
+    assert stack.depth == 1
+    assert [i.title for i in g.items] == ["T1", "T2"]
+    assert stack.top_group is g
+    # Not two stack levels of single tasks
+    assert len(stack.groups) == 1
+
+    g2 = stack.push_group(["T1.1", "T1.2"])
+    assert stack.depth == 2
+    assert [i.title for i in g2.items] == ["T1.1", "T1.2"]
+
+    popped = stack.pop()
+    assert popped is not None
+    assert [i.title for i in popped.items] == ["T1.1", "T1.2"]
+    assert stack.depth == 1
+    assert stack.top_group is not None
+    assert [i.title for i in stack.top_group.items] == ["T1", "T2"]
 
 
-def test_dfs_breakdown_pattern() -> None:
-    """push [T1,T2] → top T1; push [T1.1,T1.2] → top T1.1; pop children; then T2.1."""
+def test_dfs_breakdown_with_groups() -> None:
+    """push [T1,T2] → push [T1.1,T1.2] → pop → push [T2.1]."""
     stack = TodoStack()
-    root = stack.push_titles(["T1", "T2"])
-    assert [i.title for i in root] == ["T1", "T2"]
-    assert stack.top is not None
-    assert stack.top.title == "T1"
-    # bottom→top: T2, T1
-    assert [i.title for i in stack.items] == ["T2", "T1"]
+    root = stack.push_group(["T1", "T2"])
+    children = stack.push_group(["T1.1", "T1.2"])
+    assert stack.depth == 2
+    stack.update(children.items[0].id, status="done")
+    stack.update(children.items[1].id, status="done")
+    _ = stack.pop()
+    assert stack.depth == 1
+    stack.update(root.items[0].id, status="done")
+    _ = stack.push_group(["T2.1"])
+    assert stack.depth == 2
+    assert stack.top_group is not None
+    assert stack.top_group.items[0].title == "T2.1"
+    assert stack.groups[0].items[1].title == "T2"
 
-    children = stack.push_titles(["T1.1", "T1.2"])
-    assert [i.title for i in children] == ["T1.1", "T1.2"]
-    assert stack.top is not None and stack.top.title == "T1.1"
-    # bottom→top: T2, T1, T1.2, T1.1
-    assert [i.title for i in stack.items] == ["T2", "T1", "T1.2", "T1.1"]
 
-    p1 = stack.pop()
-    p2 = stack.pop()
-    assert p1 is not None and p1.title == "T1.1"
-    assert p2 is not None and p2.title == "T1.2"
-    p3 = stack.pop()
-    assert p3 is not None and p3.title == "T1"
-    assert stack.top is not None and stack.top.title == "T2"
-    _ = stack.push_titles(["T2.1"])
-    assert stack.top is not None and stack.top.title == "T2.1"
-    assert [i.title for i in stack.items] == ["T2", "T2.1"]
+def test_single_title_still_one_group() -> None:
+    stack = TodoStack()
+    item = stack.push("only")
+    assert stack.depth == 1
+    assert item.title == "only"
+    g = stack.pop()
+    assert g is not None and len(g.items) == 1
+    assert stack.is_empty()
 
 
 def test_todo_stack_needs_review() -> None:
@@ -82,8 +90,17 @@ def test_todo_stack_needs_review() -> None:
     assert not stack.needs_review()
 
 
-def test_legacy_frames_flatten() -> None:
-    stack = TodoStack.from_raw(
+def test_legacy_flat_and_frames_migrate() -> None:
+    flat = TodoStack.from_raw(
+        {
+            "items": [{"id": "t1", "title": "old", "status": "pending", "notes": ""}],
+            "next_id": 2,
+        }
+    )
+    assert flat.depth == 1
+    assert flat.all_items()[0].title == "old"
+
+    framed = TodoStack.from_raw(
         {
             "frames": [
                 {"items": [{"id": "t1", "title": "T1", "status": "pending", "notes": ""}]},
@@ -92,17 +109,19 @@ def test_legacy_frames_flatten() -> None:
             "next_id": 3,
         }
     )
-    assert [i.title for i in stack.items] == ["T1", "T1.1"]
-    assert stack.top is not None and stack.top.title == "T1.1"
+    assert framed.depth == 2
+    assert framed.top_group is not None
+    assert framed.top_group.items[0].title == "T1.1"
 
 
 def test_todo_stack_roundtrip_raw() -> None:
     stack = TodoStack()
-    _ = stack.push_titles(["x", "y"], notes="n")
+    _ = stack.push_group(["x", "y"], notes="n")
     raw = stack.to_raw()
+    assert "groups" in raw
     restored = TodoStack.from_raw(raw)
-    assert [i.title for i in restored.items] == ["y", "x"]  # bottom y, top x
-    assert restored.top is not None and restored.top.title == "x"
+    assert restored.depth == 1
+    assert [i.title for i in restored.groups[0].items] == ["x", "y"]
 
 
 async def test_todo_tools_and_persist(tmp_path: object) -> None:
@@ -114,18 +133,20 @@ async def test_todo_tools_and_persist(tmp_path: object) -> None:
         set_todo_stack(stack, on_change=None)
         registry = ToolRegistry(list(TODO_TOOLS))
         out = await registry.execute("todo_push", '{"titles": "T1\\nT2"}')
-        assert "top" in out.lower() or "pushed" in out
-        assert stack.top is not None and stack.top.title == "T1"
+        assert "group" in out.lower() or "pushed" in out
+        assert stack.depth == 1
+        assert [i.title for i in stack.groups[0].items] == ["T1", "T2"]
         _ = await registry.execute("todo_push", '{"titles": "T1.1; T1.2"}')
-        assert stack.top is not None and stack.top.title == "T1.1"
+        assert stack.depth == 2
         out3 = await registry.execute("todo_pop", "{}")
         assert "popped" in out3
-        assert stack.top is not None and stack.top.title == "T1.2"
+        assert stack.depth == 1
         _ = await memory.update_session_todo_stack(session.sid, stack.to_raw())
         loaded = await memory.get_session_todo_stack(session.sid)
         assert loaded is not None
         again = TodoStack.from_raw(loaded)
-        assert again.top is not None and again.top.title == "T1.2"
+        assert again.depth == 1
+        assert [i.title for i in again.groups[0].items] == ["T1", "T2"]
     finally:
         set_todo_stack(None)
         await memory.close()