@researai/deepscientist 1.5.9 → 1.5.12

package/src/deepscientist/prompts/builder.py

@@ -257,7 +257,7 @@ class PromptBuilder:
             f"- bound_external_connector_count: {surface_context['bound_external_connector_count']}",
             "- surface_rule: treat web, TUI, and connector threads as one continuous quest, but adapt the amount of detail to the active surface.",
             "- surface_reply_rule: use artifact.interact(...) for durable user-visible continuity; do not dump raw internal tool chatter into connector replies.",
-            "- connector_contract_rule: load connector-specific prompt fragments only for the active or bound external connector; do not load unused connector contracts.",
+            "- connector_contract_rule: choose the active connector surface from the latest inbound external user turn when one exists; otherwise fall back to the bound external connector; keep purely local web/TUI turns on the local surface even if the quest is externally bound.",
         ]
 
         if connector == "qq":
@@ -283,6 +283,21 @@ class PromptBuilder:
                     "- qq_structured_delivery_rule: when you want native QQ markdown or native QQ image/file delivery, request it through artifact.interact(connector_hints=..., attachments=[...]) instead of inventing connector-specific inline tag syntax.",
                 ]
             )
+        elif connector == "weixin":
+            lines.extend(
+                [
+                    "- weixin_surface_rule: Weixin is a concise operator surface, not a full artifact browser.",
+                    "- weixin_default_mode: keep outbound replies concise, respectful, text-first, and progress-aware.",
+                    "- weixin_length_rule: for ordinary Weixin progress replies, normally use only 2 to 4 short sentences, or 3 very short bullets at most.",
+                    "- weixin_summary_first_rule: start with the user-facing conclusion, then the immediate meaning, then the next action.",
+                    "- weixin_progress_shape_rule: make the current task, the main difficulty or latest real progress, and the next concrete next step explicit whenever possible.",
+                    "- weixin_eta_rule: for important long-running phases, include a rough ETA or next check-in window when it is helpful and defensible.",
+                    "- weixin_internal_detail_rule: do not proactively dump file inventories, path lists, retry counters, or monitor-log style telemetry unless the user asked for them or they explain a real risk.",
+                    "- weixin_context_token_rule: reply continuity is managed by the runtime through `context_token`; do not invent your own reply token scheme.",
+                    "- weixin_media_rule: when you want native Weixin image, video, or file delivery, request it through artifact.interact(..., attachments=[...]) with `connector_delivery={'weixin': {'media_kind': ...}}` instead of inventing connector-specific inline tag syntax.",
+                    "- weixin_inbound_media_rule: inbound Weixin image, video, and file messages can arrive as quest-local attachments under `userfiles/weixin/...`; read those files when the user sent media.",
+                ]
+            )
         else:
             lines.append("- connector_media_rule: if the active surface is not QQ, keep using the general artifact interaction discipline for milestone delivery.")
 
@@ -301,12 +316,23 @@ class PromptBuilder:
             if str(parsed.get("connector") or "").strip().lower() == "local":
                 continue
             bound_external.append(parsed)
-        active = bound_external[0] if bound_external else None
-        origin = "bound_external_binding" if active is not None else "latest_user_source"
-        if active is None and latest_user_parsed is not None:
-            latest_connector = str(latest_user_parsed.get("connector") or "").strip().lower()
-            if latest_connector and latest_connector != "local":
-                active = latest_user_parsed
+        latest_connector = str((latest_user_parsed or {}).get("connector") or "").strip().lower()
+        if latest_connector and latest_connector != "local":
+            active = latest_user_parsed
+            origin = "latest_user_source"
+        elif latest_user is not None:
+            return {
+                "latest_user_source": latest_user_source,
+                "active_surface": "local",
+                "active_connector": "local",
+                "active_chat_type": "local",
+                "active_chat_id": "default",
+                "active_connector_origin": "latest_user_source_local",
+                "bound_external_connector_count": len(bound_external),
+            }
+        else:
+            active = bound_external[0] if bound_external else None
+            origin = "bound_external_binding" if active is not None else "none"
         if active is None:
             return {
                 "latest_user_source": latest_user_source,
@@ -672,18 +698,51 @@ class PromptBuilder:
         startup_contract = snapshot.get("startup_contract")
         if isinstance(startup_contract, dict):
             value = str(startup_contract.get("custom_profile") or "").strip().lower()
-            if value in {"continue_existing_state", "revision_rebuttal", "freeform"}:
+            if value in {"continue_existing_state", "review_audit", "revision_rebuttal", "freeform"}:
                 return value
         return "freeform"
 
+    @staticmethod
+    def _baseline_execution_policy(snapshot: dict) -> str:
+        startup_contract = snapshot.get("startup_contract")
+        if isinstance(startup_contract, dict):
+            value = str(startup_contract.get("baseline_execution_policy") or "").strip().lower()
+            if value in {"auto", "must_reproduce_or_verify", "reuse_existing_only", "skip_unless_blocking"}:
+                return value
+        return "auto"
+
+    @staticmethod
+    def _review_followup_policy(snapshot: dict) -> str:
+        startup_contract = snapshot.get("startup_contract")
+        if isinstance(startup_contract, dict):
+            value = str(startup_contract.get("review_followup_policy") or "").strip().lower()
+            if value in {"audit_only", "auto_execute_followups", "user_gated_followups"}:
+                return value
+        return "audit_only"
+
+    @staticmethod
+    def _manuscript_edit_mode(snapshot: dict) -> str:
+        startup_contract = snapshot.get("startup_contract")
+        if isinstance(startup_contract, dict):
+            value = str(startup_contract.get("manuscript_edit_mode") or "").strip().lower()
+            if value in {"none", "copy_ready_text", "latex_required"}:
+                return value
+        return "none"
+
     def _research_delivery_policy_block(self, snapshot: dict) -> str:
         need_research_paper = self._need_research_paper(snapshot)
         launch_mode = self._launch_mode(snapshot)
         custom_profile = self._custom_profile(snapshot)
+        baseline_execution_policy = self._baseline_execution_policy(snapshot)
+        review_followup_policy = self._review_followup_policy(snapshot)
+        manuscript_edit_mode = self._manuscript_edit_mode(snapshot)
         lines = [
             f"- need_research_paper: {need_research_paper}",
             f"- launch_mode: {launch_mode}",
             f"- custom_profile: {custom_profile if launch_mode == 'custom' else 'n/a'}",
+            f"- review_followup_policy: {review_followup_policy if custom_profile == 'review_audit' else 'n/a'}",
+            f"- baseline_execution_policy: {baseline_execution_policy if launch_mode == 'custom' else 'n/a'}",
+            f"- manuscript_edit_mode: {manuscript_edit_mode if custom_profile in {'review_audit', 'revision_rebuttal'} else 'n/a'}",
             f"- delivery_mode: {'paper_required' if need_research_paper else 'algorithm_first'}",
             "- idea_stage_rule: every accepted idea submission should normally create a new branch/worktree and a new user-visible research node.",
             "- idea_draft_rule: before `artifact.submit_idea(...)`, first finish a concise durable Markdown draft for the chosen route; keep `idea.md` compact and `draft.md` richer.",
@@ -698,7 +757,7 @@ class PromptBuilder:
             lines.extend(
                 [
                     "- custom_launch_rule: do not force the canonical full-research path when the custom startup contract is narrower.",
-                    "- custom_context_rule: treat `entry_state_summary`, `review_summary`, and `custom_brief` as active runtime context rather than decorative metadata.",
+                    "- custom_context_rule: treat `entry_state_summary`, `review_summary`, `review_materials`, and `custom_brief` as active runtime context rather than decorative metadata.",
                 ]
             )
             if custom_profile == "continue_existing_state":
@@ -708,6 +767,31 @@ class PromptBuilder:
                         "- reuse_first_rule: trust-rank and reconcile existing assets before deciding to rerun anything costly.",
                     ]
                 )
+            elif custom_profile == "review_audit":
+                lines.extend(
+                    [
+                        "- review_entry_rule: treat the current draft/paper state as the active contract; open `review` before more writing or finalization.",
+                        "- review_routing_rule: if that audit finds real evidence gaps, route to `analysis-campaign`, `baseline`, `scout`, or `write` instead of polishing blindly.",
+                    ]
+                )
+                if review_followup_policy == "auto_execute_followups":
+                    lines.extend(
+                        [
+                            "- review_followup_rule: after the audit artifacts are durable, continue automatically into the required experiments, manuscript deltas, and review-closure work instead of stopping at the audit report.",
+                        ]
+                    )
+                elif review_followup_policy == "user_gated_followups":
+                    lines.extend(
+                        [
+                            "- review_followup_rule: after the audit artifacts are durable, package the next expensive follow-up step into one structured decision instead of continuing silently.",
+                        ]
+                    )
+                else:
+                    lines.extend(
+                        [
+                            "- review_followup_rule: stop after the durable audit artifacts and route recommendation unless the user later asks for execution follow-up.",
+                        ]
+                    )
             elif custom_profile == "revision_rebuttal":
                 lines.extend(
                     [
@@ -721,6 +805,36 @@ class PromptBuilder:
                         "- freeform_entry_rule: prefer the custom brief over the default stage order and open only the skills actually needed.",
                     ]
                 )
+            if baseline_execution_policy == "must_reproduce_or_verify":
+                lines.extend(
+                    [
+                        "- baseline_execution_rule: before reviewer-linked follow-up work, explicitly verify or recover the rebuttal-critical baseline/comparator instead of assuming the stored evidence is still trustworthy.",
+                    ]
+                )
+            elif baseline_execution_policy == "reuse_existing_only":
+                lines.extend(
+                    [
+                        "- baseline_execution_rule: prefer the existing trusted baseline/results and do not rerun them unless you find concrete inconsistency, corruption, or missing-evidence problems.",
+                    ]
+                )
+            elif baseline_execution_policy == "skip_unless_blocking":
+                lines.extend(
+                    [
+                        "- baseline_execution_rule: do not spend time on baseline reruns by default; only open `baseline` if a named review/rebuttal issue truly depends on a missing comparator or unusable prior evidence.",
+                    ]
+                )
+            if manuscript_edit_mode == "latex_required":
+                lines.extend(
+                    [
+                        "- manuscript_edit_rule: when manuscript revision is needed, treat the provided LaTeX tree or `paper/latex/` as the authoritative writing surface; if LaTeX source is unavailable, produce LaTeX-ready replacement text and make that blocker explicit instead of pretending the manuscript was edited.",
+                    ]
+                )
+            elif manuscript_edit_mode == "copy_ready_text":
+                lines.extend(
+                    [
+                        "- manuscript_edit_rule: when manuscript revision is needed, provide section-level copy-ready replacement text and explicit deltas even if no LaTeX source is available.",
+                    ]
+                )
         if need_research_paper:
             lines.extend(
                 [
@@ -768,7 +882,10 @@ class PromptBuilder:
             "- interaction_protocol: first message may be plain conversation; after that, treat artifact.interact threads and mailbox polls as the main continuity spine across TUI, web, and connectors",
             "- mailbox_protocol: artifact.interact(include_recent_inbound_messages=True) is the queued human-message mailbox; when it returns user text, treat that input as higher priority than background subtasks until it has been acknowledged",
             "- acknowledgment_protocol: after artifact.interact returns any human message, immediately send one substantive artifact.interact(...) follow-up; if the active connector runtime already emitted a transport-level receipt acknowledgement, do not send a redundant receipt-only message; if answerable, answer directly, otherwise state the short plan, nearest checkpoint, and that the current background subtask is paused",
-            "- progress_protocol: emit artifact.interact(kind='progress', reply_mode='threaded', ...) at real human-meaningful checkpoints; if no natural checkpoint appears during active user-relevant work, prefer a concise keepalive once work has crossed roughly 10 tool calls with a human-meaningful delta, and do not drift beyond roughly 20 tool calls or about 15 minutes without a user-visible update",
+            "- progress_protocol: emit artifact.interact(kind='progress', reply_mode='threaded', ...) at real human-meaningful checkpoints; if no natural checkpoint appears during active user-relevant work, prefer a concise keepalive once work has crossed roughly 6 tool calls with a human-meaningful delta, and do not drift beyond roughly 12 tool calls or about 8 minutes without a user-visible update",
+            "- stage_kickoff_protocol: after entering any stage or companion skill, send one user-visible artifact.interact progress update within the first 3 tool calls of substantial work",
+            "- read_plan_keepalive_protocol: if work is still mostly reading, searching, comparison, or planning, do not wait too long for a 'big result'; send one concise user-visible checkpoint after about 5 consecutive tool calls if the user would otherwise see silence",
+            "- subtask_boundary_protocol: send a user-visible update whenever the active subtask changes materially, especially across intake -> audit, audit -> experiment planning, experiment planning -> run launch, run result -> drafting, or drafting -> review/rebuttal",
             "- smoke_then_detach_protocol: for baseline reproduction, main experiments, and analysis experiments, first validate the command path with a bounded smoke test; once the smoke test passes, launch the real long run with bash_exec(mode='detach', ...) and usually leave timeout_seconds unset rather than guessing a fake deadline",
             "- progress_first_monitoring_protocol: when supervising a long-running bash_exec session, judge health by forward progress rather than by whether the final artifact has already appeared within a short window",
             "- delta_monitoring_protocol: compare deltas such as new sample counters, new task counters, new saved files, new last_output_seq values, or changed last_progress payloads; if any of these move forward, treat the run as alive and keep observing",
@@ -789,7 +906,7 @@ class PromptBuilder:
             "- respect_protocol: write user-facing updates as natural, respectful, easy-to-follow chat; do not sound like a formal status report or internal tool log",
             "- omission_protocol: for ordinary user-facing updates, omit file paths, artifact ids, branch/worktree ids, session ids, raw commands, raw logs, and internal tool names unless the user asked for them or needs them to act",
             "- compaction_protocol: ordinary artifact.interact progress updates should usually fit in 2 to 4 short sentences and should not read like a monitoring transcript or execution diary",
-            "- tool_call_keepalive_protocol: for active multi-step work outside long detached experiment waits, prefer sending one concise artifact.interact progress update after roughly 10 tool calls when there is already a human-meaningful delta, and do not exceed roughly 20 tool calls or about 15 minutes without a user-visible checkpoint",
+            "- tool_call_keepalive_protocol: for active multi-step work outside long detached experiment waits, prefer sending one concise artifact.interact progress update after roughly 6 tool calls when there is already a human-meaningful delta, and do not exceed roughly 12 tool calls or about 8 minutes without a user-visible checkpoint",
             "- human_progress_shape_protocol: ordinary progress updates should usually make three things explicit in human language: the current task, the main difficulty or latest real progress, and the concrete next measure you will take",
             "- milestone_graduation_protocol: keep ordinary subtask completions concise; upgrade to a richer milestone report only when a stage-significant deliverable or route-changing checkpoint becomes durably true",
             "- eta_visibility_protocol: for baseline reproduction, main experiments, analysis experiments, and other important long-running phases, progress updates should also make the expected time to the next meaningful result, next milestone, or next user-visible update explicit; use roughly 10 to 30 minutes as the normal update window, and if the ETA is unreliable, say that and give a realistic next check-in window instead",

package/src/deepscientist/qq_profiles.py

@@ -1,196 +1 @@
-from __future__ import annotations
-
-from copy import deepcopy
-from typing import Any
-
-from .shared import slugify
-
-
-QQ_PROFILE_ID_PREFIX = "qq-profile"
-def default_qq_profile() -> dict[str, Any]:
-    return {
-        "profile_id": None,
-        "enabled": True,
-        "app_id": None,
-        "app_secret": None,
-        "app_secret_env": None,
-        "bot_name": "DeepScientist",
-        "main_chat_id": None,
-    }
-
-
-def _as_text(value: Any) -> str | None:
-    text = str(value or "").strip()
-    return text or None
-
-
-def _normalize_secret_pair(payload: dict[str, Any], direct_key: str, env_key: str) -> None:
-    direct = _as_text(payload.get(direct_key))
-    env_name = _as_text(payload.get(env_key))
-    payload[direct_key] = direct
-    payload[env_key] = None if direct else env_name
-
-
-def _profile_id_seed(*, profile_id: Any, app_id: Any, bot_name: Any, index: int) -> str:
-    explicit = _as_text(profile_id)
-    if explicit:
-        return explicit
-    app_text = _as_text(app_id)
-    if app_text:
-        return f"qq-{app_text}"
-    bot_text = slugify(str(bot_name or "").strip(), default="")
-    if bot_text:
-        return f"{QQ_PROFILE_ID_PREFIX}-{bot_text}"
-    return f"{QQ_PROFILE_ID_PREFIX}-{index:03d}"
-
-
-def _unique_profile_id(seed: str, *, used: set[str]) -> str:
-    base = slugify(seed, default=QQ_PROFILE_ID_PREFIX)
-    candidate = base
-    suffix = 2
-    while candidate in used:
-        candidate = f"{base}-{suffix}"
-        suffix += 1
-    used.add(candidate)
-    return candidate
-
-
-def list_qq_profiles(config: dict[str, Any] | None) -> list[dict[str, Any]]:
-    normalized = normalize_qq_connector_config(config)
-    profiles = normalized.get("profiles")
-    return [dict(item) for item in profiles] if isinstance(profiles, list) else []
-
-
-def find_qq_profile(
-    config: dict[str, Any] | None,
-    *,
-    profile_id: str | None = None,
-    app_id: str | None = None,
-) -> dict[str, Any] | None:
-    normalized_profile_id = _as_text(profile_id)
-    normalized_app_id = _as_text(app_id)
-    for profile in list_qq_profiles(config):
-        if normalized_profile_id and str(profile.get("profile_id") or "").strip() == normalized_profile_id:
-            return profile
-        if normalized_app_id and str(profile.get("app_id") or "").strip() == normalized_app_id:
-            return profile
-    return None
-
-
-def merge_qq_profile_config(shared_config: dict[str, Any] | None, profile: dict[str, Any]) -> dict[str, Any]:
-    normalized = normalize_qq_connector_config(shared_config)
-    merged = deepcopy(normalized)
-    merged.pop("profiles", None)
-    app_secret = _as_text(profile.get("app_secret"))
-    app_secret_env = _as_text(profile.get("app_secret_env"))
-    merged.update(
-        {
-            "profile_id": str(profile.get("profile_id") or "").strip() or None,
-            "app_id": _as_text(profile.get("app_id")),
-            "app_secret": app_secret,
-            "app_secret_env": None if app_secret else app_secret_env,
-            "bot_name": _as_text(profile.get("bot_name")) or str(normalized.get("bot_name") or "DeepScientist"),
-            "main_chat_id": _as_text(profile.get("main_chat_id")),
-            "enabled": bool(normalized.get("enabled", False)) and bool(profile.get("enabled", True)),
-            "transport": "gateway_direct",
-        }
-    )
-    return merged
-
-
-def qq_profile_label(profile: dict[str, Any] | None) -> str:
-    if not isinstance(profile, dict):
-        return "QQ"
-    bot_name = _as_text(profile.get("bot_name"))
-    app_id = _as_text(profile.get("app_id"))
-    if bot_name and app_id:
-        return f"{bot_name} · {app_id}"
-    if bot_name:
-        return bot_name
-    if app_id:
-        return f"QQ · {app_id}"
-    return "QQ"
-
-
-def normalize_qq_connector_config(config: dict[str, Any] | None) -> dict[str, Any]:
-    payload = deepcopy(config or {})
-    shared_defaults = {
-        "enabled": False,
-        "transport": "gateway_direct",
-        "app_id": None,
-        "app_secret": None,
-        "app_secret_env": None,
-        "bot_name": "DeepScientist",
-        "command_prefix": "/",
-        "main_chat_id": None,
-        "require_at_in_groups": True,
-        "auto_bind_dm_to_active_quest": True,
-        "gateway_restart_on_config_change": True,
-        "auto_send_main_experiment_png": True,
-        "auto_send_analysis_summary_png": True,
-        "auto_send_slice_png": True,
-        "auto_send_paper_pdf": True,
-        "enable_markdown_send": False,
-        "enable_file_upload_experimental": False,
-        "profiles": [],
-    }
-    shared = {**shared_defaults, **payload}
-    shared["transport"] = "gateway_direct"
-    shared["command_prefix"] = _as_text(shared.get("command_prefix")) or "/"
-    shared["bot_name"] = _as_text(shared.get("bot_name")) or "DeepScientist"
-    _normalize_secret_pair(shared, "app_secret", "app_secret_env")
-
-    raw_profiles = payload.get("profiles")
-    items = list(raw_profiles) if isinstance(raw_profiles, list) else []
-    legacy_profile_seed = {
-        "app_id": payload.get("app_id"),
-        "app_secret": payload.get("app_secret"),
-        "app_secret_env": payload.get("app_secret_env"),
-        "bot_name": payload.get("bot_name"),
-        "main_chat_id": payload.get("main_chat_id"),
-    }
-    if not items:
-        has_direct_profile_seed = any(_as_text(legacy_profile_seed.get(key)) for key in ("app_id", "app_secret", "main_chat_id"))
-        has_env_profile_seed = bool(payload.get("enabled")) and bool(_as_text(legacy_profile_seed.get("app_secret_env")))
-        if has_direct_profile_seed or has_env_profile_seed:
-            items = [legacy_profile_seed]
-
-    profiles: list[dict[str, Any]] = []
-    used_ids: set[str] = set()
-    for index, raw in enumerate(items, start=1):
-        if not isinstance(raw, dict):
-            continue
-        current = {**default_qq_profile(), **raw}
-        current["enabled"] = bool(current.get("enabled", True))
-        current["app_id"] = _as_text(current.get("app_id"))
-        current["app_secret"] = _as_text(current.get("app_secret"))
-        current["app_secret_env"] = _as_text(current.get("app_secret_env")) or shared["app_secret_env"]
-        _normalize_secret_pair(current, "app_secret", "app_secret_env")
-        current["bot_name"] = _as_text(current.get("bot_name")) or shared["bot_name"]
-        current["main_chat_id"] = _as_text(current.get("main_chat_id"))
-        current["profile_id"] = _unique_profile_id(
-            _profile_id_seed(
-                profile_id=current.get("profile_id"),
-                app_id=current.get("app_id"),
-                bot_name=current.get("bot_name"),
-                index=index,
-            ),
-            used=used_ids,
-        )
-        profiles.append(current)
-
-    shared["profiles"] = profiles
-    if len(profiles) == 1:
-        mirror = profiles[0]
-        shared["app_id"] = mirror.get("app_id")
-        shared["app_secret"] = mirror.get("app_secret")
-        shared["app_secret_env"] = mirror.get("app_secret_env")
-        shared["bot_name"] = mirror.get("bot_name")
-        shared["main_chat_id"] = mirror.get("main_chat_id")
-    else:
-        shared["app_id"] = None
-        shared["app_secret"] = None
-        shared["app_secret_env"] = None
-        shared["main_chat_id"] = None
-
-    return shared
+from .connector.qq_profiles import *  # noqa: F401,F403

package/src/deepscientist/quest/node_traces.py

@@ -6,6 +6,8 @@ from typing import Any
 
 from ..shared import ensure_dir, read_json, sha256_text, utc_now, write_json
 
+NODE_TRACE_SCHEMA_VERSION = 2
+
 
 def _format_state_label(value: str | None) -> str:
     normalized = str(value or "").strip().replace("_", " ").replace("-", " ")
@@ -36,6 +38,23 @@ def _normalize_branch_name(value: object, *, fallback: str) -> str:
     return text or fallback
 
 
+def _infer_stage_from_branch_name(value: object) -> str | None:
+    normalized = str(value or "").strip().lower()
+    if not normalized:
+        return None
+    if normalized.startswith("analysis/"):
+        return "analysis"
+    if normalized.startswith("run/"):
+        return "experiment"
+    if normalized.startswith("idea/"):
+        return "idea"
+    if normalized.startswith("paper/") or normalized.startswith("write/"):
+        return "writing"
+    if normalized.startswith("baseline/"):
+        return "baseline"
+    return None
+
+
 def _infer_stage_from_skill(skill_id: object) -> str | None:
     normalized = str(skill_id or "").strip().lower()
     if not normalized:
@@ -240,6 +259,7 @@ def _resolve_entry_context(
         or _infer_stage_from_artifact((((run_artifact or {}).get("record") or {}) if run_artifact else {}))
         or (run_context or {}).get("stage_key")
         or _infer_stage_from_event_type(raw_event_type)
+        or _infer_stage_from_branch_name(branch_name)
         or "general"
     )
     return {
@@ -440,6 +460,7 @@ class QuestNodeTraceManager:
         source_signature = sha256_text(
             json.dumps(
                 {
+                    "schema_version": NODE_TRACE_SCHEMA_VERSION,
                     "entries": workflow.get("entries") or [],
                     "branch": (snapshot or {}).get("branch"),
                 },
@@ -451,6 +472,7 @@ class QuestNodeTraceManager:
         if (
             isinstance(existing, dict)
             and existing.get("quest_id") == quest_id
+            and existing.get("schema_version") == NODE_TRACE_SCHEMA_VERSION
             and existing.get("source_signature") == source_signature
             and isinstance(existing.get("items"), list)
         ):
@@ -545,6 +567,7 @@ class QuestNodeTraceManager:
 
         payload = {
             "quest_id": quest_id,
+            "schema_version": NODE_TRACE_SCHEMA_VERSION,
             "generated_at": utc_now(),
             "source_signature": source_signature,
             "items": items,