@team-agent/installer 0.1.3 → 0.1.7

package/README.md

@@ -83,8 +83,6 @@ Three design choices make this possible:
 
 **3. Standards over inventions.** MCP for tool calls, Skill files for role definitions. Anything the broader ecosystem ships, this picks up automatically.
 
-For the full design philosophy and boundaries, see [`docs/team-agent-foundation-and-boundaries.md`](./docs/team-agent-foundation-and-boundaries.md).
-
 ---
 
 ## Quick start

package/README.zh.md

@@ -82,8 +82,6 @@ Lead 自己想清楚:
 
 **3. 用标准协议,不发明协议。** 用 MCP 做工具调用,用 Skill 文件做角色定义。生态发什么,本项目自动获得什么。
 
-完整设计哲学和边界,见 [`docs/team-agent-foundation-and-boundaries.md`](./docs/team-agent-foundation-and-boundaries.md)。
-
 ---
 
 ## 快速开始

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.1.3",
+  "version": "0.1.7",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",
@@ -29,11 +29,11 @@
     "npm",
     "scripts",
     "src",
+    "tests",
     "skills",
     "templates",
     "examples",
     "schemas",
-    "docs/team-agent-foundation-and-boundaries.md",
     "crates/team-agent-core/Cargo.toml",
     "crates/team-agent-core/src",
     "pyproject.toml",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "teamspec-agent-mode"
-version = "0.1.0"
+version = "0.1.4"
 description = "Spec-first CLI-native team agent runtime for Claude Code, Codex CLI, and Gemini CLI workers."
 readme = "README.md"
 requires-python = ">=3.10"

package/scripts/run_regression_tests.py

@@ -10,6 +10,9 @@ from pathlib import Path
 
 REGRESSION_TESTS = [
     "tests.run_tests.RuntimeTests.test_send_default_timeout_reports_submitted_unverified",
+    "tests.run_tests.RuntimeTests.test_message_fragment_matching_ignores_generic_header",
+    "tests.run_tests.RuntimeTests.test_wait_for_message_ready_does_not_accept_old_header",
+    "tests.run_tests.RuntimeTests.test_wait_for_message_ready_accepts_only_new_pasted_prompt",
     "tests.run_tests.RuntimeTests.test_worker_delivery_retries_paste_until_message_ready",
     "tests.run_tests.RuntimeTests.test_worker_pasted_content_prompt_retries_enter_until_submitted",
     "tests.run_tests.RuntimeTests.test_worker_pasted_content_prompt_reports_unverified_when_enter_does_not_submit",
@@ -26,6 +29,7 @@ REGRESSION_TESTS = [
     "tests.run_tests.RuntimeTests.test_start_agent_falls_back_to_fresh_when_resume_window_exits",
     "tests.run_tests.RuntimeTests.test_broadcast_sends_only_to_current_team_and_excludes_sender",
     "tests.run_tests.RuntimeTests.test_status_and_collect_expose_uncollected_report_result",
+    "tests.run_tests.RuntimeTests.test_collect_accepts_message_scoped_report_result",
     "tests.run_tests.RuntimeTests.test_report_result_queues_leader_notification_without_blocking_mcp",
     "tests.run_tests.RuntimeTests.test_mcp_send_message_accepts_thin_args_and_returns_compact_result",
     "tests.run_tests.RuntimeTests.test_mcp_send_message_accepts_broadcast_target",

package/src/team_agent/__init__.py

@@ -1,3 +1,3 @@
 """TeamSpec Agent Mode runtime."""
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"

package/src/team_agent/mcp_server.py

@@ -505,7 +505,7 @@ def handle_mcp(tools: TeamOrchestratorTools, request: dict[str, Any]) -> dict[st
             "result": {
                 "protocolVersion": request.get("params", {}).get("protocolVersion", "2024-11-05"),
                 "capabilities": {"tools": {}},
-                "serverInfo": {"name": "team_orchestrator", "version": "0.1.3"},
+                "serverInfo": {"name": "team_orchestrator", "version": "0.1.4"},
             },
         }
     if method == "tools/list":

package/src/team_agent/message_store.py

@@ -475,6 +475,29 @@ class MessageStore:
                 )
         return ids
 
+    def acknowledge_message(self, message_id: str, agent_id: str) -> list[str]:
+        now = utcnow()
+        with closing(self.connect()) as conn:
+            with conn:
+                row = conn.execute(
+                    """
+                    select message_id from messages
+                    where message_id = ? and recipient = ? and status in ('pending', 'accepted', 'target_resolved', 'injected', 'visible', 'submitted', 'delivered')
+                    """,
+                    (message_id, agent_id),
+                ).fetchone()
+                if not row:
+                    return []
+                conn.execute(
+                    """
+                    update messages
+                    set status = 'acknowledged', acknowledged_at = ?, updated_at = ?
+                    where message_id = ? and recipient = ? and status in ('pending', 'accepted', 'target_resolved', 'injected', 'visible', 'submitted', 'delivered')
+                    """,
+                    (now, now, message_id, agent_id),
+                )
+        return [message_id]
+
     def results(self, uncollected_only: bool = False) -> list[dict[str, Any]]:
         query = "select * from results order by created_at"
         if uncollected_only:

package/src/team_agent/runtime.py

@@ -35,7 +35,15 @@ from team_agent.providers import ResumeUnavailable, get_adapter, shell_command_f
 from team_agent.routing import route_task
 from team_agent.simple_yaml import dumps
 from team_agent.spec import load_spec, validate_result_envelope, workspace_from_spec
-from team_agent.state import load_runtime_state, runtime_state_path, save_runtime_state, write_team_state
+from team_agent.state import (
+    SESSION_CAPTURE_FIELDS,
+    SESSION_STATE_FIELDS,
+    load_runtime_state,
+    normalize_agent_session_state,
+    runtime_state_path,
+    save_runtime_state,
+    write_team_state,
+)
 from team_agent.task_graph import ready_tasks, update_task_status
 from team_agent.task_graph import TASK_STATUSES
 
@@ -520,10 +528,7 @@ def _load_snapshot_state(path: Path) -> dict[str, Any] | None:
         state = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError):
         return None
-    for agent_state in state.get("agents", {}).values():
-        if isinstance(agent_state, dict):
-            for field in ["session_id", "rollout_path", "captured_at", "captured_via", "attribution_confidence", "spawn_cwd"]:
-                agent_state.setdefault(field, None)
+    normalize_agent_session_state(state)
     return state
 
 
@@ -1290,13 +1295,15 @@ def collect(workspace: Path, result_file: Path | None = None) -> dict[str, Any]:
             store.add_result(envelope)
 
     rows = store.results(uncollected_only=True)
-    valid_rows: list[tuple[dict[str, Any], dict[str, Any]]] = []
+    valid_rows: list[tuple[dict[str, Any], dict[str, Any], dict[str, Any] | None]] = []
     for row in rows:
         envelope: Any = None
         try:
             envelope = json.loads(row["envelope"])
             validate_result_envelope(envelope)
-            _find_task(state["tasks"], envelope["task_id"])
+            task = _find_task_or_none(state["tasks"], envelope["task_id"])
+            if task is None and not _is_message_scoped_result(store, envelope):
+                raise RuntimeError(f"unknown task id: {envelope['task_id']}")
         except (json.JSONDecodeError, ValidationError, RuntimeError) as exc:
             invalid_results.append(
                 _record_invalid_result(
@@ -1308,7 +1315,7 @@ def collect(workspace: Path, result_file: Path | None = None) -> dict[str, Any]:
             )
             store.mark_result_invalid(row["result_id"], str(exc))
         else:
-            valid_rows.append((row, envelope))
+            valid_rows.append((row, envelope, task))
 
     if invalid_results:
         save_runtime_state(workspace, state)
@@ -1326,17 +1333,20 @@ def collect(workspace: Path, result_file: Path | None = None) -> dict[str, Any]:
     collected: list[dict[str, Any]] = []
     collected_results: list[dict[str, Any]] = []
     next_state = copy.deepcopy(state)
-    for row, envelope in valid_rows:
-        task = _find_task(next_state["tasks"], envelope["task_id"])
-        task_status = _result_status_to_task_status(task, envelope["status"])
-        update_task_status(
-            next_state["tasks"],
-            envelope["task_id"],
-            task_status,
-            envelope.get("summary"),
-            envelope.get("artifacts", []),
-        )
-        task["accepted_result_id"] = row["result_id"]
+    for row, envelope, task in valid_rows:
+        if task is not None:
+            next_task = _find_task(next_state["tasks"], envelope["task_id"])
+            task_status = _result_status_to_task_status(next_task, envelope["status"])
+            update_task_status(
+                next_state["tasks"],
+                envelope["task_id"],
+                task_status,
+                envelope.get("summary"),
+                envelope.get("artifacts", []),
+            )
+            next_task["accepted_result_id"] = row["result_id"]
+        else:
+            task_status = "message_scoped"
         collected.append(envelope)
         collected_results.append(
             {
@@ -1346,6 +1356,7 @@ def collect(workspace: Path, result_file: Path | None = None) -> dict[str, Any]:
                 "status": envelope["status"],
                 "summary": envelope.get("summary"),
                 "tests": envelope.get("tests", []),
+                "scope": "task" if task is not None else "message",
             }
         )
         event_log.write(
@@ -1354,12 +1365,13 @@ def collect(workspace: Path, result_file: Path | None = None) -> dict[str, Any]:
             task_id=envelope["task_id"],
             status=envelope["status"],
             task_status=task_status,
-            retry_count=task.get("retry_count"),
-            retry_limit=task.get("retry_limit"),
+            retry_count=task.get("retry_count") if task else None,
+            retry_limit=task.get("retry_limit") if task else None,
+            scope="task" if task is not None else "message",
         )
     state_path = write_team_state(workspace, spec, next_state, [{"envelope": env} for env in collected])
     save_runtime_state(workspace, next_state)
-    for row, _ in valid_rows:
+    for row, _, _ in valid_rows:
         store.mark_result_collected(row["result_id"])
     return {
         "ok": not invalid_results,
@@ -1377,6 +1389,8 @@ def report_result(workspace: Path, envelope: dict[str, Any]) -> dict[str, Any]:
     store = MessageStore(workspace)
     result_id = store.add_result(envelope)
     acknowledged = store.acknowledge_task_messages(envelope["task_id"], envelope["agent_id"])
+    if not acknowledged:
+        acknowledged = store.acknowledge_message(envelope["task_id"], envelope["agent_id"])
     event_log = EventLog(workspace)
     notification = _notify_leader_of_report_result(workspace, envelope, result_id, event_log)
     leader_notified = bool(notification.get("ok")) and notification.get("status") in {"submitted", "visible", "delivered", "acknowledged"}
@@ -1561,8 +1575,7 @@ def _capture_agent_session(
     result = adapter.capture_session_id(agent_id, spawn_context, timeout_s=timeout_s)
     if not isinstance(result, dict) or not result.get("session_id"):
         return None
-    for key in ["session_id", "rollout_path", "captured_at", "captured_via", "attribution_confidence", "spawn_cwd"]:
-        agent_state[key] = result.get(key)
+    _copy_session_metadata(agent_state, result)
     agent_state.pop("_pending_session_id", None)
     event_log.write(
         "session.captured",
@@ -1576,6 +1589,16 @@ def _capture_agent_session(
     return result
 
 
+def _copy_session_metadata(target: dict[str, Any], source: dict[str, Any]) -> None:
+    for key in SESSION_STATE_FIELDS:
+        target[key] = source.get(key)
+
+
+def _clear_session_capture_fields(target: dict[str, Any]) -> None:
+    for key in SESSION_CAPTURE_FIELDS:
+        target[key] = None
+
+
 def _attach_profile_resume_root(workspace: Path, command_agent: dict[str, Any], previous: dict[str, Any]) -> dict[str, Any]:
     profile_launch = command_agent.get("_provider_profile") or prepare_agent_profile_launch(workspace, command_agent)
     if not profile_launch:
@@ -1622,8 +1645,7 @@ def _prepare_resume_state(
     if not repaired:
         repaired = adapter.recover_session_id(agent_id, prepared, workspace, exclude_session_ids or set())
     if repaired:
-        for key in ["session_id", "rollout_path", "captured_at", "captured_via", "attribution_confidence", "spawn_cwd"]:
-            prepared[key] = repaired.get(key)
+        _copy_session_metadata(prepared, repaired)
         event_log.write(
             "resume.session_repaired",
             agent_id=agent_id,
@@ -1648,8 +1670,7 @@ def _prepare_resume_state(
             f"Cannot resume agent {agent_id}: stored session {session_id} is not available. "
             "Use --allow-fresh only if losing that worker context is acceptable."
         )
-    for key in ["session_id", "rollout_path", "captured_at", "captured_via", "attribution_confidence"]:
-        prepared[key] = None
+    _clear_session_capture_fields(prepared)
     event_log.write(
         "resume.session_unavailable",
         agent_id=agent_id,
@@ -1963,8 +1984,7 @@ def restart(workspace: Path, allow_fresh: bool = False, team: str | None = None)
         if profile_launch.get("claude_projects_root"):
             agent_state["claude_projects_root"] = profile_launch["claude_projects_root"]
         if restart_mode == "fresh":
-            for key in ["session_id", "rollout_path", "captured_at", "captured_via", "attribution_confidence"]:
-                agent_state[key] = None
+            _clear_session_capture_fields(agent_state)
             if command_agent.get("_session_id"):
                 agent_state["_pending_session_id"] = command_agent["_session_id"]
             _capture_agent_session(
@@ -2222,8 +2242,7 @@ def _start_agent_unlocked(workspace: Path, agent_id: str, force: bool, open_disp
     if profile_launch.get("claude_projects_root"):
         agent_state["claude_projects_root"] = profile_launch["claude_projects_root"]
     if start_mode == "fresh":
-        for key in ["session_id", "rollout_path", "captured_at", "captured_via", "attribution_confidence"]:
-            agent_state[key] = None
+        _clear_session_capture_fields(agent_state)
         if command_agent.get("_session_id"):
             agent_state["_pending_session_id"] = command_agent["_session_id"]
         _capture_agent_session(workspace, agent_id, agent_state, event_log, timeout_s=1.5, exclude_session_ids=known_session_ids)
@@ -4018,8 +4037,24 @@ def _tmux_inject_text(target: str, text: str, submit_key: str, buffer_name: str,
                 "attempts": attempt_log,
                 "verification": prepared["verification"],
             }
+        baseline = _capture_tmux_pane_text(target)
+        if not baseline["ok"]:
+            return {
+                "ok": False,
+                "stage": "pre-paste-capture",
+                "error": baseline.get("error"),
+                "attempts": attempt_log,
+                "verification": "pre_paste_capture_failed",
+            }
+        baseline_capture = baseline["capture"]
         if token:
-            pre_visible, pre_verification, pre_capture = _wait_for_message_ready(target, token, 0.0, expected_text=text)
+            pre_visible, pre_verification, pre_capture = _wait_for_message_ready(
+                target,
+                token,
+                0.0,
+                expected_text=text,
+                allow_pasted_prompt=False,
+            )
             if pre_visible:
                 attempt_entry = {
                     "attempt": attempt,
@@ -4060,6 +4095,23 @@ def _tmux_inject_text(target: str, text: str, submit_key: str, buffer_name: str,
                     "attempts": attempt_log,
                     "submit_attempts": submit.get("attempts"),
                 }
+            if _capture_has_pasted_content_prompt(baseline_capture):
+                attempt_log.append(
+                    {
+                        "attempt": attempt,
+                        "visible": False,
+                        "verification": "preexisting_unverified_pasted_content_prompt",
+                        "text_bytes": text_bytes,
+                        "ready_timeout_sec": 0.0,
+                    }
+                )
+                return {
+                    "ok": False,
+                    "stage": "preexisting-input",
+                    "error": "target pane already has an unverified pasted-content prompt; refusing to paste again to avoid duplicate messages",
+                    "attempts": attempt_log,
+                    "verification": "preexisting_unverified_pasted_content_prompt",
+                }
         buffered = _tmux_set_buffer_text(buffer_name, text)
         if not buffered["ok"]:
             return {"ok": False, "stage": buffered["stage"], "error": buffered.get("error"), "attempts": attempt_log}
@@ -4068,7 +4120,13 @@ def _tmux_inject_text(target: str, text: str, submit_key: str, buffer_name: str,
             return {"ok": False, "stage": "paste-buffer", "error": proc.stderr.strip(), "attempts": attempt_log}
         time.sleep(0.25)
         if token:
-            visible, verification, capture_text = _wait_for_message_ready(target, token, ready_timeout, expected_text=text)
+            visible, verification, capture_text = _wait_for_message_ready(
+                target,
+                token,
+                ready_timeout,
+                expected_text=text,
+                baseline_capture=baseline_capture,
+            )
         else:
             visible, verification, capture_text = True, "no_token", ""
         last_verification = verification
@@ -4237,35 +4295,51 @@ def _wait_for_visible_token(target: str, token: str, timeout: float) -> tuple[bo
     deadline = time.monotonic() + max(timeout, 0.0)
     last = "not_checked"
     while True:
-        capture = run_cmd(["tmux", "capture-pane", "-p", "-S", f"-{DELIVERY_CAPTURE_LINES}", "-t", target], timeout=5)
-        if capture.returncode == 0:
-            if token in capture.stdout or f"[team-agent-token:{token}]" in capture.stdout:
+        capture = _capture_tmux_pane_text(target)
+        if capture["ok"]:
+            if token in capture["capture"] or f"[team-agent-token:{token}]" in capture["capture"]:
                 return True, "capture_contains_token"
             last = "capture_missing_token"
         else:
-            last = f"capture_failed: {capture.stderr.strip()}"
+            last = f"capture_failed: {capture.get('error')}"
         if time.monotonic() >= deadline:
             return False, last
         time.sleep(0.1)
 
 
-def _wait_for_message_ready(target: str, message_id: str, timeout: float, expected_text: str = "") -> tuple[bool, str, str]:
+def _capture_tmux_pane_text(target: str) -> dict[str, Any]:
+    capture = run_cmd(["tmux", "capture-pane", "-p", "-S", f"-{DELIVERY_CAPTURE_LINES}", "-t", target], timeout=5)
+    if capture.returncode != 0:
+        return {"ok": False, "capture": "", "error": capture.stderr.strip() or "tmux capture-pane failed"}
+    return {"ok": True, "capture": capture.stdout}
+
+
+def _wait_for_message_ready(
+    target: str,
+    message_id: str,
+    timeout: float,
+    expected_text: str = "",
+    allow_pasted_prompt: bool = True,
+    baseline_capture: str = "",
+) -> tuple[bool, str, str]:
     deadline = time.monotonic() + max(timeout, 0.0)
     last = "not_checked"
     last_capture = ""
+    baseline_had_pasted_prompt = _capture_has_pasted_content_prompt(baseline_capture)
     while True:
-        capture = run_cmd(["tmux", "capture-pane", "-p", "-S", f"-{DELIVERY_CAPTURE_LINES}", "-t", target], timeout=5)
-        if capture.returncode == 0:
-            last_capture = capture.stdout
-            if message_id in capture.stdout or f"[team-agent-token:{message_id}]" in capture.stdout:
-                return True, "capture_contains_token", capture.stdout
-            if _capture_has_pasted_content_prompt(capture.stdout):
-                return True, "capture_contains_pasted_content_prompt", capture.stdout
-            if expected_text and _capture_contains_message_fragment(capture.stdout, expected_text):
-                return True, "capture_contains_message_fragment", capture.stdout
+        capture = _capture_tmux_pane_text(target)
+        if capture["ok"]:
+            capture_text = capture["capture"]
+            last_capture = capture_text
+            if message_id in capture_text or f"[team-agent-token:{message_id}]" in capture_text:
+                return True, "capture_contains_token", capture_text
+            if expected_text and _capture_contains_message_fragment(capture_text, expected_text):
+                return True, "capture_contains_message_fragment", capture_text
+            if allow_pasted_prompt and _capture_has_pasted_content_prompt(capture_text) and not baseline_had_pasted_prompt:
+                return True, "capture_contains_new_pasted_content_prompt", capture_text
             last = "capture_missing_token"
         else:
-            last = f"capture_failed: {capture.stderr.strip()}"
+            last = f"capture_failed: {capture.get('error')}"
         if time.monotonic() >= deadline:
             return False, last, last_capture
         time.sleep(0.1)
@@ -4299,15 +4373,18 @@ def _capture_contains_message_fragment(capture_text: str, expected_text: str) ->
     haystack = _compact_visible_text(capture_text)
     if not haystack:
         return False
-    return any(fragment in haystack for fragment in _message_fragment_candidates(expected_text))
+    fragments = _message_fragment_candidates(expected_text)
+    if not fragments:
+        return False
+    return any(fragment in haystack for fragment in fragments)
 
 
 def _message_fragment_candidates(text: str) -> list[str]:
     sanitized = re.sub(r"\[team-agent-token:[^\]]+\]", "", text)
     fragments: list[str] = []
-    for line in sanitized.splitlines():
+    for line in _message_content_lines(sanitized):
         compact = _compact_visible_text(line)
-        if len(compact) < 18:
+        if not _is_strong_message_fragment(compact):
             continue
         if len(compact) <= 72:
             fragments.append(compact)
@@ -4330,6 +4407,35 @@ def _message_fragment_candidates(text: str) -> list[str]:
     return unique
 
 
+def _message_content_lines(text: str) -> list[str]:
+    lines = text.splitlines()
+    if lines and lines[0].strip().startswith("Team Agent message from "):
+        lines = lines[1:]
+    return [line for line in lines if line.strip()]
+
+
+def _is_strong_message_fragment(compact: str) -> bool:
+    if not compact:
+        return False
+    generic_prefixes = (
+        "TeamAgentmessagefrom",
+        "TeamAgentpeermessagefrom",
+        "TeamAgentstoredthisresult",
+        "TeamAgenthascollectedthisresult",
+        "Nomanualpolling",
+    )
+    if compact.startswith(generic_prefixes):
+        return False
+    if re.fullmatch(r"[-:：>›❯]+", compact):
+        return False
+    if re.search(r"(msg|res)_[0-9A-Fa-f]{8,}", compact):
+        return True
+    cjk_count = len(re.findall(r"[\u4e00-\u9fff]", compact))
+    if cjk_count >= 4 and len(compact) >= 6:
+        return True
+    return len(compact) >= 18
+
+
 def _compact_visible_text(text: str) -> str:
     return re.sub(r"\s+", "", text)
 
@@ -4668,7 +4774,12 @@ def _deliver_pending_message(
             if ready:
                 status = (
                     "submitted"
-                    if verification in {"capture_contains_pasted_content_prompt", "capture_contains_message_fragment"}
+                    if verification
+                    in {
+                        "capture_contains_pasted_content_prompt",
+                        "capture_contains_new_pasted_content_prompt",
+                        "capture_contains_message_fragment",
+                    }
                     else "visible"
                 )
                 store.mark(message_id, status)
@@ -5200,6 +5311,22 @@ def _find_task(tasks: list[dict[str, Any]], task_id: str) -> dict[str, Any]:
     raise RuntimeError(f"unknown task id: {task_id}")
 
 
+def _find_task_or_none(tasks: list[dict[str, Any]], task_id: str) -> dict[str, Any] | None:
+    for task in tasks:
+        if task.get("id") == task_id:
+            return task
+    return None
+
+
+def _is_message_scoped_result(store: MessageStore, envelope: dict[str, Any]) -> bool:
+    task_id = str(envelope.get("task_id") or "")
+    agent_id = str(envelope.get("agent_id") or "")
+    if not task_id.startswith("msg_"):
+        return False
+    message = _message_by_id(store, task_id)
+    return bool(message and message.get("recipient") == agent_id)
+
+
 def _find_agent(spec: dict[str, Any], agent_id: str | None) -> dict[str, Any] | None:
     if not agent_id:
         return None

package/src/team_agent/state.py

@@ -10,12 +10,15 @@ from team_agent.paths import runtime_dir
 from team_agent.simple_yaml import dumps
 
 
-SESSION_STATE_FIELDS = [
+SESSION_CAPTURE_FIELDS = [
     "session_id",
     "rollout_path",
     "captured_at",
     "captured_via",
     "attribution_confidence",
+]
+SESSION_STATE_FIELDS = [
+    *SESSION_CAPTURE_FIELDS,
     "spawn_cwd",
 ]
 
@@ -24,15 +27,22 @@ def runtime_state_path(workspace: Path) -> Path:
     return runtime_dir(workspace) / "state.json"
 
 
+def normalize_agent_session_state(state: dict[str, Any]) -> None:
+    agents = state.get("agents", {})
+    if not isinstance(agents, dict):
+        return
+    for agent_state in agents.values():
+        if isinstance(agent_state, dict):
+            for field in SESSION_STATE_FIELDS:
+                agent_state.setdefault(field, None)
+
+
 def load_runtime_state(workspace: Path) -> dict[str, Any]:
     path = runtime_state_path(workspace)
     if not path.exists():
         return {"agents": {}, "tasks": [], "session_name": None}
     state = json.loads(path.read_text(encoding="utf-8"))
-    for agent_state in state.get("agents", {}).values():
-        if isinstance(agent_state, dict):
-            for field in SESSION_STATE_FIELDS:
-                agent_state.setdefault(field, None)
+    normalize_agent_session_state(state)
     return state