@researai/deepscientist 1.5.16 → 1.6.0

package/src/deepscientist/quest/service.py

@@ -5,10 +5,10 @@ from collections import deque
 from contextlib import contextmanager
 from datetime import UTC, datetime, timedelta
 import hashlib
-import subprocess
 import json
 import mimetypes
 import re
+import shutil
 import threading
 import time
 from pathlib import Path, PurePosixPath
@@ -27,11 +27,12 @@ from ..file_lock import advisory_file_lock
 from ..gitops import current_branch, export_git_graph, head_commit, init_repo, list_branch_canvas, list_commit_canvas
 from ..home import repo_root
 from ..registries import BaselineRegistry
-from ..shared import append_jsonl, ensure_dir, generate_id, iter_jsonl, read_json, read_jsonl, read_jsonl_tail, read_text, read_yaml, resolve_within, run_command, sha256_text, slugify, utc_now, write_json, write_text, write_yaml
+from ..shared import append_jsonl, ensure_dir, generate_id, iter_jsonl, read_json, read_jsonl, read_jsonl_tail, read_text, read_yaml, resolve_within, run_command, run_command_bytes, sha256_text, slugify, utc_now, write_json, write_text, write_yaml
 from ..skills import SkillInstaller
 from ..web_search import extract_web_search_payload
 from .layout import (
     QUEST_DIRECTORIES,
+    default_active_anchor,
     gitignore,
     initial_brief,
     initial_plan,
@@ -44,21 +45,34 @@ from .stage_views import QuestStageViewBuilder
 
 _UNSET = object()
 _NUMERIC_QUEST_ID_PATTERN = re.compile(r"^\d{1,10}$")
+_SYSTEM_NUMERIC_QUEST_ID_PATTERN = re.compile(r"^(?P<prefix>[SB])-(?P<number>\d{1,10})$", re.IGNORECASE)
 _MAX_NUMERIC_QUEST_ID_VALUE = 9_999_999_999
 _NUMERIC_QUEST_ID_PAD_WIDTH = 3
 _CRASH_AUTO_RESUME_WINDOW = timedelta(hours=24)
 _JSONL_CACHE_MAX_BYTES = 4 * 1024 * 1024
 _CODEX_HISTORY_TAIL_LIMIT = 400
 _JSONL_STREAM_CHUNK_BYTES = 64 * 1024
+_JSONL_LINE_COUNT_CACHE_SUFFIX = ".linecount.json"
 _EVENTS_OVERSIZED_LINE_BYTES = 8 * 1024 * 1024
 _OVERSIZED_EVENT_PREFIX_BYTES = 4096
 _PROJECTION_SCHEMA_VERSION = 1
 _PROJECTION_BUILD_TOTAL_STEPS = 3
 _PROJECTION_REFRESH_THROTTLE_SECONDS = 1.0
+_SHARED_MEMORY_DOCUMENT_PREFIX = "sharedmemory::"
 _EVENT_TYPE_BYTES_RE = re.compile(rb'"(?:type|event_type)"\s*:\s*"([^"]+)"')
 _EVENT_TOOL_NAME_BYTES_RE = re.compile(rb'"tool_name"\s*:\s*"([^"]+)"')
 _EVENT_RUN_ID_BYTES_RE = re.compile(rb'"run_id"\s*:\s*"([^"]+)"')
 CONTINUATION_POLICIES = {"auto", "when_external_progress", "wait_for_user_or_resume", "none"}
+AUTONOMOUS_BLOCKING_WAIT_REASONS = {
+    "completion_approval",
+    "credential_required",
+    "privacy_or_data_export_boundary",
+    "large_cost_or_external_paid_api",
+    "user_gated_decision_request",
+}
+_CHAT_ATTACHMENT_TEXT_EXTENSIONS = {".txt", ".md", ".markdown", ".mdx", ".json", ".csv", ".log", ".yaml", ".yml"}
+_CHAT_ATTACHMENT_TEXT_MIME_PREFIXES = ("text/",)
+_CHAT_ATTACHMENT_TEXT_MIME_TYPES = {"application/json", "application/x-yaml", "text/csv"}
 
 
 def _oversized_event_placeholder(*, prefix: bytes, line_bytes: int) -> dict[str, Any]:
@@ -101,6 +115,7 @@ def _iter_jsonl_records_safely(
         prefix = bytearray()
         current_bytes = 0
         oversized = False
+        cursor = 0
         while True:
             chunk = handle.read(_JSONL_STREAM_CHUNK_BYTES)
             if not chunk:
@@ -114,7 +129,8 @@ def _iter_jsonl_records_safely(
                 if oversized:
                     current_bytes += len(segment)
                     if has_newline:
-                        yield _oversized_event_placeholder(prefix=bytes(prefix), line_bytes=current_bytes)
+                        cursor += 1
+                        yield cursor, _oversized_event_placeholder(prefix=bytes(prefix), line_bytes=current_bytes)
                         prefix = bytearray()
                         current_bytes = 0
                         oversized = False
@@ -133,7 +149,8 @@ def _iter_jsonl_records_safely(
                     current_bytes = next_bytes
                     oversized = True
                     if has_newline:
-                        yield _oversized_event_placeholder(prefix=bytes(prefix), line_bytes=current_bytes)
+                        cursor += 1
+                        yield cursor, _oversized_event_placeholder(prefix=bytes(prefix), line_bytes=current_bytes)
                         prefix = bytearray()
                         current_bytes = 0
                         oversized = False
@@ -148,28 +165,27 @@ def _iter_jsonl_records_safely(
                     buffer.clear()
                     line_bytes = current_bytes
                     current_bytes = 0
-                    if raw:
-                        try:
-                            payload = json.loads(raw)
-                        except json.JSONDecodeError:
-                            payload = None
-                        if isinstance(payload, dict):
-                            yield payload
+                    cursor += 1
+                    payload = _parse_jsonl_record_line_safely(
+                        raw,
+                        oversized_line_bytes=oversized_line_bytes,
+                    )
+                    yield cursor, payload
                     start = newline_index + 1
                     continue
                 break
 
         if oversized:
-            yield _oversized_event_placeholder(prefix=bytes(prefix), line_bytes=current_bytes)
+            cursor += 1
+            yield cursor, _oversized_event_placeholder(prefix=bytes(prefix), line_bytes=current_bytes)
         elif buffer:
             raw = bytes(buffer).strip()
-            if raw:
-                try:
-                    payload = json.loads(raw)
-                except json.JSONDecodeError:
-                    payload = None
-                if isinstance(payload, dict):
-                    yield payload
+            cursor += 1
+            payload = _parse_jsonl_record_line_safely(
+                raw,
+                oversized_line_bytes=oversized_line_bytes,
+            )
+            yield cursor, payload
 
 
 def _parse_jsonl_record_line_safely(
@@ -188,11 +204,69 @@ def _parse_jsonl_record_line_safely(
         )
     try:
         payload = json.loads(raw)
-    except json.JSONDecodeError:
+    except (UnicodeDecodeError, json.JSONDecodeError):
         return None
     return payload if isinstance(payload, dict) else None
 
 
+def _jsonl_line_count_cache_path(path: Path) -> Path:
+    return path.with_name(f".{path.name}{_JSONL_LINE_COUNT_CACHE_SUFFIX}")
+
+
+def _jsonl_path_state(path: Path) -> tuple[int, int, int] | None:
+    if not path.exists():
+        return None
+    stat = path.stat()
+    return (
+        stat.st_ino,
+        getattr(stat, "st_mtime_ns", int(stat.st_mtime * 1_000_000_000)),
+        stat.st_size,
+    )
+
+
+def _jsonl_line_count_from_cache(path: Path) -> int | None:
+    current_state = _jsonl_path_state(path)
+    if current_state is None:
+        return 0
+
+    cache_path = _jsonl_line_count_cache_path(path)
+    payload = read_json(cache_path, {})
+    if not isinstance(payload, dict):
+        payload = {}
+    raw_state = payload.get("state")
+    raw_total = payload.get("total")
+    if not isinstance(raw_state, (list, tuple)) or len(raw_state) != 3:
+        return None
+    try:
+        cached_state = tuple(int(item) for item in raw_state)
+        cached_total = int(raw_total)
+    except (TypeError, ValueError):
+        return None
+    if cached_total < 0:
+        return None
+    if cached_state == current_state:
+        return cached_total
+
+    # If the file only grew through append-only writes, count just the delta.
+    if cached_state[0] == current_state[0] and current_state[2] > cached_state[2]:
+        appended_count = 0
+        for relative_cursor, _payload in _iter_jsonl_records_from_offset_safely(
+            path,
+            start_offset=cached_state[2],
+        ):
+            appended_count = relative_cursor
+        total = cached_total + appended_count
+        write_json(
+            cache_path,
+            {
+                "state": list(current_state),
+                "total": total,
+            },
+        )
+        return total
+    return None
+
+
 def _tail_jsonl_records_safely(
     path: Path,
     *,
@@ -225,6 +299,9 @@ def _tail_jsonl_records_safely(
 def _count_jsonl_lines_fast(path: Path, *, chunk_size: int = 1024 * 1024) -> int:
     if not path.exists():
         return 0
+    cached_total = _jsonl_line_count_from_cache(path)
+    if cached_total is not None:
+        return cached_total
     total = 0
     last_byte = b""
     with path.open("rb") as handle:
@@ -235,9 +312,18 @@ def _count_jsonl_lines_fast(path: Path, *, chunk_size: int = 1024 * 1024) -> int
             total += chunk.count(b"\n")
             last_byte = chunk[-1:]
     if total == 0 and last_byte:
-        return 1
-    if last_byte not in {b"", b"\n"}:
+        total = 1
+    elif last_byte not in {b"", b"\n"}:
         total += 1
+    state = _jsonl_path_state(path)
+    if state is not None:
+        write_json(
+            _jsonl_line_count_cache_path(path),
+            {
+                "state": list(state),
+                "total": total,
+            },
+        )
     return total
 
 
@@ -284,13 +370,12 @@ def _iter_jsonl_records_from_offset_safely(
         return
     with path.open("rb") as handle:
         handle.seek(max(int(start_offset or 0), 0))
-        for raw_line in handle:
+        for relative_cursor, raw_line in enumerate(handle, start=1):
             payload = _parse_jsonl_record_line_safely(
                 raw_line,
                 oversized_line_bytes=oversized_line_bytes,
             )
-            if isinstance(payload, dict):
-                yield payload
+            yield relative_cursor, payload
 
 
 class QuestService:
@@ -319,36 +404,71 @@ class QuestService:
         self._quest_projection_refresh_lock = threading.Lock()
         self._quest_projection_refresh_at: dict[str, float] = {}
 
+    def _configured_default_runner(self) -> str:
+        config = ConfigManager(self.home).load_named("config")
+        return self._resolve_enabled_runner_name(config.get("default_runner"))
+
+    def _resolve_enabled_runner_name(self, *candidates: Any) -> str:
+        runners = ConfigManager(self.home).load_runners_config()
+        seen: set[str] = set()
+        enabled: list[str] = []
+        for name, cfg in runners.items():
+            normalized = str(name or "").strip().lower()
+            if not normalized or normalized in seen:
+                continue
+            seen.add(normalized)
+            if isinstance(cfg, dict) and cfg.get("enabled") is not False:
+                enabled.append(normalized)
+
+        checked: set[str] = set()
+        for raw in [*candidates, "codex"]:
+            normalized = str(raw or "").strip().lower()
+            if not normalized or normalized in checked:
+                continue
+            checked.add(normalized)
+            cfg = runners.get(normalized)
+            if isinstance(cfg, dict) and cfg.get("enabled") is not False:
+                return normalized
+        return enabled[0] if enabled else "codex"
+
     def _quest_root(self, quest_id: str) -> Path:
         return self.quests_root / quest_id
 
+    def _require_initialized_quest_root(self, quest_id: str) -> Path:
+        quest_root = self._quest_root(quest_id)
+        if not quest_root.exists() or not self._quest_yaml_path(quest_root).exists():
+            raise FileNotFoundError(f"Unknown quest `{quest_id}`.")
+        return quest_root
+
     def _normalized_binding_sources(self, sources: list[Any] | None) -> list[str]:
         local_present = False
-        external_source: str | None = None
+        external_sources: list[str] = []
+        external_index: dict[str, int] = {}
         for raw in sources or []:
             normalized = self._normalize_binding_source(raw)
             if not normalized:
                 continue
-            if normalized == "local:default":
-                local_present = True
-                continue
             parsed = parse_conversation_id(normalized)
             connector = str((parsed or {}).get("connector") or "").strip().lower()
-            if connector == "local":
+            if normalized == "local:default" or connector == "local":
                 local_present = True
                 continue
-            external_source = normalized
-        if external_source:
-            return ["local:default", external_source]
+            identity = conversation_identity_key(normalized)
+            existing_index = external_index.get(identity)
+            if existing_index is None:
+                external_index[identity] = len(external_sources)
+                external_sources.append(normalized)
+            else:
+                external_sources[existing_index] = normalized
         if local_present:
-            return ["local:default"]
-        return ["local:default"]
+            return ["local:default", *external_sources]
+        return external_sources
 
     def _binding_sources_payload(self, quest_root: Path) -> dict[str, list[str]]:
         bindings_path = quest_root / ".ds" / "bindings.json"
-        payload = read_json(bindings_path, {"sources": ["local:default"]})
-        raw_sources = payload.get("sources") if isinstance(payload, dict) else ["local:default"]
-        sources = self._normalized_binding_sources(raw_sources if isinstance(raw_sources, list) else ["local:default"])
+        payload = read_json(bindings_path, {"sources": []})
+        raw_sources = payload.get("sources") if isinstance(payload, dict) else []
+        sources = self._normalized_binding_sources(raw_sources if isinstance(raw_sources, list) else [])
         return {"sources": sources}
 
     def preferred_locale(self, quest_root: Path | None = None) -> str:
@@ -394,11 +514,21 @@ class QuestService:
         if not isinstance(payload, dict):
             payload = {}
         normalized = dict(payload)
-        normalized.setdefault("active_anchor", "baseline")
+        startup_contract = dict(normalized.get("startup_contract") or {}) if isinstance(normalized.get("startup_contract"), dict) else None
+        normalized.setdefault("startup_contract", startup_contract)
         normalized.setdefault("baseline_gate", "pending")
         normalized.setdefault("confirmed_baseline_ref", None)
         normalized.setdefault("requested_baseline_ref", None)
-        normalized.setdefault("startup_contract", None)
+        active_anchor = str(normalized.get("active_anchor") or "").strip()
+        if not active_anchor:
+            normalized["active_anchor"] = default_active_anchor(startup_contract)
+        elif (
+            active_anchor == "baseline"
+            and str((startup_contract or {}).get("workspace_mode") or "").strip().lower() == "copilot"
+            and not isinstance(normalized.get("confirmed_baseline_ref"), dict)
+            and not isinstance(normalized.get("requested_baseline_ref"), dict)
+        ):
+            normalized["active_anchor"] = "scout"
         return normalized
 
     @staticmethod
@@ -876,7 +1006,7 @@ class QuestService:
             if not artifacts_root.exists():
                 continue
             for folder in sorted(artifacts_root.iterdir()):
-                if not folder.is_dir():
+                if not folder.is_dir() or folder.name == "graphs":
                     continue
                 for path in sorted(folder.glob("*.json")):
                     item = self._read_cached_json(path, {})
@@ -1509,16 +1639,18 @@ class QuestService:
         for artifact in recent_artifacts:
             payload = artifact.get("payload") if isinstance(artifact.get("payload"), dict) else {}
             artifact_path = artifact.get("path")
+            artifact_kind = str(payload.get("kind") or artifact.get("kind") or "").strip()
             entries.append(
                 {
                     "id": f"artifact:{payload.get('artifact_id') or artifact_path}",
                     "kind": "artifact",
-                    "title": str(payload.get("artifact_id") or artifact.get("kind") or "artifact"),
+                    "title": str(payload.get("title") or payload.get("artifact_id") or artifact.get("kind") or "artifact"),
                     "summary": payload.get("summary") or payload.get("message") or payload.get("reason") or "Artifact updated.",
                     "status": payload.get("status"),
                     "reason": payload.get("reason"),
                     "created_at": payload.get("updated_at") or payload.get("created_at"),
                     "paths": list((payload.get("paths") or {}).values()) + ([str(artifact_path)] if artifact_path else []),
+                    "stage_key": "science" if artifact_kind.startswith("science.") else payload.get("stage_key"),
                 }
             )
             add_file(str(artifact_path) if artifact_path else None, source="artifact")
@@ -1826,6 +1958,37 @@ class QuestService:
                 best_root = paper_root
         return best_root
 
+    @staticmethod
+    def _paper_line_state_from_root(paper_root: Path) -> dict[str, Any]:
+        path = paper_root / "paper_line_state.json"
+        payload = read_json(path, {})
+        return payload if isinstance(payload, dict) else {}
+
+    @staticmethod
+    def _filter_paper_evidence_items(
+        items: list[dict[str, Any]],
+        *,
+        selected_outline_ref: str | None = None,
+        paper_line_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        normalized_outline = str(selected_outline_ref or "").strip() or None
+        normalized_line = str(paper_line_id or "").strip() or None
+        filtered: list[dict[str, Any]] = []
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            item_outline = str(item.get("selected_outline_ref") or "").strip() or None
+            item_line = str(item.get("paper_line_id") or "").strip() or None
+            if normalized_line:
+                if item_line and item_line != normalized_line:
+                    continue
+                if not item_line and normalized_outline and item_outline and item_outline != normalized_outline:
+                    continue
+            elif normalized_outline and item_outline and item_outline != normalized_outline:
+                continue
+            filtered.append(dict(item))
+        return filtered
+
     def _outline_record_from_paper_root(self, paper_root: Path) -> dict[str, Any]:
         outline_root = paper_root / "outline"
         manifest_path = outline_root / "manifest.json"
@@ -1887,52 +2050,49 @@ class QuestService:
         return payload if isinstance(payload, dict) else {}
 
     def _paper_evidence_payload(self, quest_root: Path, workspace_root: Path) -> dict[str, Any] | None:
-        best_payload: dict[str, Any] | None = None
-        best_rank: tuple[str, float] = ("", -1.0)
-        for candidate in self._snapshot_workspace_candidates(quest_root, workspace_root):
-            paper_root = candidate / "paper"
-            ledger_json_path = paper_root / "evidence_ledger.json"
-            if not ledger_json_path.exists():
-                continue
-            payload = read_json(ledger_json_path, {})
-            if not isinstance(payload, dict) or not payload:
-                continue
-            items = [dict(item) for item in (payload.get("items") or []) if isinstance(item, dict)]
-            latest = max(
-                self._path_mtime(ledger_json_path),
-                self._path_mtime(paper_root / "evidence_ledger.md"),
-                self._path_mtime(paper_root),
-            )
-            rank = (str(payload.get("updated_at") or payload.get("created_at") or ""), latest)
-            if rank < best_rank:
-                continue
-            best_rank = rank
-            best_payload = {
-                "paper_root": str(paper_root),
-                "workspace_root": str(paper_root.parent),
-                "selected_outline_ref": str(payload.get("selected_outline_ref") or "").strip() or None,
-                "item_count": len(items),
-                "main_text_ready_count": sum(
-                    1
-                    for item in items
-                    if str(item.get("paper_role") or "").strip() == "main_text"
-                    and str(item.get("status") or "").strip().lower() in {"ready", "completed", "analyzed", "written", "recorded", "supported"}
-                ),
-                "appendix_item_count": sum(
-                    1 for item in items if str(item.get("paper_role") or "").strip() == "appendix"
-                ),
-                "unmapped_item_count": sum(
-                    1
-                    for item in items
-                    if not str(item.get("section_id") or "").strip() or not str(item.get("paper_role") or "").strip()
-                ),
-                "items": items[:40],
-                "paths": {
-                    "ledger_json": str(ledger_json_path),
-                    "ledger_md": str(paper_root / "evidence_ledger.md") if (paper_root / "evidence_ledger.md").exists() else None,
-                },
-            }
-        return best_payload
+        paper_root = self._best_paper_root(quest_root, workspace_root)
+        if paper_root is None:
+            return None
+        ledger_json_path = paper_root / "evidence_ledger.json"
+        if not ledger_json_path.exists():
+            return None
+        payload = read_json(ledger_json_path, {})
+        if not isinstance(payload, dict) or not payload:
+            return None
+        selected_outline_ref = str(payload.get("selected_outline_ref") or "").strip() or None
+        line_state = self._paper_line_state_from_root(paper_root)
+        paper_line_id = str(line_state.get("paper_line_id") or "").strip() or None
+        items = self._filter_paper_evidence_items(
+            [dict(item) for item in (payload.get("items") or []) if isinstance(item, dict)],
+            selected_outline_ref=selected_outline_ref,
+            paper_line_id=paper_line_id,
+        )
+        return {
+            "paper_root": str(paper_root),
+            "workspace_root": str(paper_root.parent),
+            "selected_outline_ref": selected_outline_ref,
+            "paper_line_id": paper_line_id,
+            "item_count": len(items),
+            "main_text_ready_count": sum(
+                1
+                for item in items
+                if str(item.get("paper_role") or "").strip() == "main_text"
+                and str(item.get("status") or "").strip().lower() in {"ready", "completed", "analyzed", "written", "recorded", "supported"}
+            ),
+            "appendix_item_count": sum(
+                1 for item in items if str(item.get("paper_role") or "").strip() == "appendix"
+            ),
+            "unmapped_item_count": sum(
+                1
+                for item in items
+                if not str(item.get("section_id") or "").strip() or not str(item.get("paper_role") or "").strip()
+            ),
+            "items": items[:40],
+            "paths": {
+                "ledger_json": str(ledger_json_path),
+                "ledger_md": str(paper_root / "evidence_ledger.md") if (paper_root / "evidence_ledger.md").exists() else None,
+            },
+        }
 
     def _paper_contract_payload(self, quest_root: Path, workspace_root: Path) -> dict[str, Any] | None:
         paper_root = self._best_paper_root(quest_root, workspace_root)
@@ -1952,6 +2112,7 @@ class QuestService:
         bundle_manifest = bundle_manifest if isinstance(bundle_manifest, dict) else {}
         experiment_matrix_path = paper_root / "paper_experiment_matrix.md"
         experiment_matrix_json_path = paper_root / "paper_experiment_matrix.json"
+        manuscript_coverage_path = paper_root / "manuscript_coverage.json"
         claim_map_path = paper_root / "claim_evidence_map.json"
         paper_line_state_path = paper_root / "paper_line_state.json"
         evidence_ledger = self._paper_evidence_payload(quest_root, workspace_root)
@@ -2002,11 +2163,14 @@ class QuestService:
         return {
             "paper_root": str(paper_root),
             "workspace_root": str(paper_root.parent),
+            "paper_line_id": str(self._paper_line_state_from_root(paper_root).get("paper_line_id") or "").strip() or None,
             "paper_branch": str(bundle_manifest.get("paper_branch") or "").strip() or current_branch(paper_root.parent),
             "source_branch": str(bundle_manifest.get("source_branch") or "").strip() or None,
             "selected_outline_ref": str(selected_outline.get("outline_id") or bundle_manifest.get("selected_outline_ref") or "").strip() or None,
             "title": str(selected_outline.get("title") or bundle_manifest.get("title") or "").strip() or None,
             "story": str(selected_outline.get("story") or "").strip() or None,
+            "paper_view": selected_outline.get("paper_view") if isinstance(selected_outline.get("paper_view"), dict) else None,
+            "evidence_view": selected_outline.get("evidence_view") if isinstance(selected_outline.get("evidence_view"), dict) else None,
             "research_questions": detailed_outline.get("research_questions") if isinstance(detailed_outline.get("research_questions"), list) else [],
             "experimental_designs": detailed_outline.get("experimental_designs") if isinstance(detailed_outline.get("experimental_designs"), list) else [],
             "contributions": detailed_outline.get("contributions") if isinstance(detailed_outline.get("contributions"), list) else [],
@@ -2024,6 +2188,7 @@ class QuestService:
                 "outline_manifest": str(outline_manifest_path) if outline_manifest_path.exists() else None,
                 "experiment_matrix": str(experiment_matrix_path) if experiment_matrix_path.exists() else None,
                 "experiment_matrix_json": str(experiment_matrix_json_path) if experiment_matrix_json_path.exists() else None,
+                "manuscript_coverage": str(manuscript_coverage_path) if manuscript_coverage_path.exists() else None,
                 "bundle_manifest": str(bundle_manifest_path) if bundle_manifest_path.exists() else None,
                 "claim_evidence_map": str(claim_map_path) if claim_map_path.exists() else None,
                 "paper_line_state": str(paper_line_state_path) if paper_line_state_path.exists() else None,
@@ -2417,11 +2582,25 @@ class QuestService:
         evidence_items = [
             dict(item) for item in ((paper_evidence or {}).get("items") or []) if isinstance(item, dict)
         ]
-        ledger_by_item = {
-            str(item.get("item_id") or "").strip(): item
-            for item in evidence_items
-            if str(item.get("item_id") or "").strip()
-        }
+        ledger_by_item: dict[str, list[dict[str, Any]]] = {}
+        for item in evidence_items:
+            item_id = str(item.get("item_id") or "").strip()
+            if item_id:
+                ledger_by_item.setdefault(item_id, []).append(item)
+
+        def ready_ledger_item(item_id: str) -> dict[str, Any] | None:
+            candidates = ledger_by_item.get(item_id) or []
+            ready_statuses = {"ready", "completed", "analyzed", "written", "recorded", "supported"}
+            ready = [
+                item
+                for item in candidates
+                if str(item.get("status") or "").strip().lower() in ready_statuses
+            ]
+            if ready:
+                main = [item for item in ready if str(item.get("paper_role") or "").strip() == "main_text"]
+                return main[0] if main else ready[0]
+            return candidates[0] if candidates else None
+
         unresolved_required_items: list[dict[str, Any]] = []
         ready_section_count = 0
         for section in paper_contract.get("sections") or []:
@@ -2430,7 +2609,7 @@ class QuestService:
             required_items = [str(item).strip() for item in (section.get("required_items") or []) if str(item).strip()]
             section_ready = True
             for item_id in required_items:
-                ledger_item = ledger_by_item.get(item_id)
+                ledger_item = ready_ledger_item(item_id)
                 status = str((ledger_item or {}).get("status") or "").strip().lower()
                 if status not in {"ready", "completed", "analyzed", "written", "recorded", "supported"}:
                     unresolved_required_items.append(
@@ -2517,6 +2696,18 @@ class QuestService:
             if isinstance(paper_contract.get("bundle_manifest"), dict)
             else {}
         )
+        package_type = str(bundle_manifest.get("package_type") or "draft_checkpoint").strip().lower().replace("-", "_")
+        if package_type in {"", "draft", "memo", "checkpoint", "paper_memo"}:
+            package_type = "draft_checkpoint"
+        elif package_type in {"review", "review_bundle"}:
+            package_type = "review_package"
+        elif package_type in {"final", "final_bundle", "submission", "submission_bundle"}:
+            package_type = "submission_package"
+        elif package_type not in {"draft_checkpoint", "review_package", "submission_package"}:
+            package_type = "draft_checkpoint"
+        coverage_path = str(((paper_contract.get("paths") or {}).get("manuscript_coverage") or "")).strip()
+        manuscript_coverage = read_json(Path(coverage_path), {}) if coverage_path else {}
+        manuscript_coverage = manuscript_coverage if isinstance(manuscript_coverage, dict) else {}
         submission_checklist_path = str(((paper_contract.get("paths") or {}).get("submission_checklist") or "")).strip()
         submission_checklist = read_json(Path(submission_checklist_path), {}) if submission_checklist_path else {}
         submission_checklist = submission_checklist if isinstance(submission_checklist, dict) else {}
@@ -2530,9 +2721,23 @@ class QuestService:
         closure_state = "bundle_not_ready"
         delivery_state = "not_ready"
         keep_bundle_fixed_by_default = False
-        if bundle_status == "present":
+        evidence_ready = contract_ok
+        analysis_ready = writing_ready
+        academic_outline_ready = bool(manuscript_coverage.get("academic_outline_ready"))
+        analysis_plan_ready = bool(manuscript_coverage.get("analysis_plan_ready"))
+        language_firewall_ok = bool(manuscript_coverage.get("language_firewall_ok"))
+        draft_checkpoint_ready = bool(active_line.get("draft_checkpoint_ready")) or draft_status == "present" or bundle_status == "present"
+        manuscript_ready = bool(active_line.get("manuscript_ready")) or bool(manuscript_coverage.get("manuscript_ready"))
+        submission_ready = bool(active_line.get("submission_ready")) or bool(manuscript_coverage.get("submission_ready"))
+        if submission_ready:
             closure_state = "delivery_ready"
-            delivery_state = "bundle_ready"
+            delivery_state = "submission_ready"
+        elif manuscript_ready:
+            closure_state = "review_before_submission"
+            delivery_state = "manuscript_ready"
+        elif draft_checkpoint_ready:
+            closure_state = "draft_checkpoint_continue_writing"
+            delivery_state = "draft_checkpoint_ready"
         if delivered_at or "delivered" in overall_status:
             delivery_state = "delivered"
             closure_state = "delivered_continue_research" if "continue" in overall_status else "delivered_parked"
@@ -2541,15 +2746,30 @@ class QuestService:
         if unmapped_completed_items:
             recommended_next_stage = "write"
             recommended_action = "sync_paper_contract"
+        elif manuscript_coverage and not academic_outline_ready:
+            recommended_next_stage = "write"
+            recommended_action = "repair_academic_outline_with_paper_outline"
+        elif manuscript_coverage and not analysis_plan_ready:
+            recommended_next_stage = "write"
+            recommended_action = "repair_analysis_plan_with_paper_outline"
         elif unresolved_required_items or blocking_pending_slices:
             recommended_next_stage = "analysis-campaign"
             recommended_action = "complete_required_supplementary"
+        elif manuscript_coverage and not language_firewall_ok and draft_checkpoint_ready:
+            recommended_next_stage = "write"
+            recommended_action = "repair_manuscript_language"
         elif draft_status != "present":
             recommended_next_stage = "write"
             recommended_action = "draft_paper"
         elif bundle_status != "present":
             recommended_next_stage = "write"
-            recommended_action = "prepare_bundle"
+            recommended_action = "submit_draft_checkpoint"
+        elif not manuscript_ready:
+            recommended_next_stage = "write"
+            recommended_action = "expand_manuscript_and_figures"
+        elif not submission_ready:
+            recommended_next_stage = "review"
+            recommended_action = "prepare_submission_package"
         else:
             recommended_next_stage = "finalize"
             recommended_action = "finalize_paper_line"
@@ -2568,7 +2788,16 @@ class QuestService:
             "selected_outline_ref": selected_outline_ref,
             "contract_ok": contract_ok,
             "writing_ready": writing_ready,
-            "finalize_ready": writing_ready and bundle_status == "present",
+            "evidence_ready": evidence_ready,
+            "analysis_ready": analysis_ready,
+            "academic_outline_ready": academic_outline_ready,
+            "analysis_plan_ready": analysis_plan_ready,
+            "language_firewall_ok": language_firewall_ok,
+            "draft_checkpoint_ready": draft_checkpoint_ready,
+            "manuscript_ready": manuscript_ready,
+            "submission_ready": submission_ready,
+            "finalize_ready": submission_ready,
+            "package_type": package_type,
             "closure_state": closure_state,
             "delivery_state": delivery_state,
             "delivered_at": delivered_at,
@@ -2597,6 +2826,27 @@ class QuestService:
             "draft_status": draft_status,
             "bundle_status": bundle_status,
             "blocking_reasons": blocking_reasons,
+            "manuscript_blocking_reasons": list(
+                active_line.get("manuscript_blocking_reasons")
+                or manuscript_coverage.get("manuscript_blockers")
+                or []
+            ),
+            "manuscript_warning_reasons": list(
+                active_line.get("manuscript_warning_reasons")
+                or manuscript_coverage.get("manuscript_warnings")
+                or []
+            ),
+            "submission_blocking_reasons": list(
+                active_line.get("submission_blocking_reasons")
+                or manuscript_coverage.get("submission_blockers")
+                or []
+            ),
+            "submission_warning_reasons": list(
+                active_line.get("submission_warning_reasons")
+                or manuscript_coverage.get("submission_warnings")
+                or []
+            ),
+            "manuscript_coverage": manuscript_coverage or None,
             "recommended_next_stage": recommended_next_stage,
             "recommended_action": recommended_action,
             "unresolved_required_items": unresolved_required_items[:12],
@@ -2629,6 +2879,40 @@ class QuestService:
             return text
         return text.zfill(_NUMERIC_QUEST_ID_PAD_WIDTH)
 
+    @staticmethod
+    def _parse_reserved_numeric_quest_id(value: str | None) -> int | None:
+        numeric_value = QuestService._parse_numeric_quest_id(value)
+        if numeric_value is not None:
+            return numeric_value
+        raw = str(value or "").strip()
+        match = _SYSTEM_NUMERIC_QUEST_ID_PATTERN.fullmatch(raw)
+        if match is None:
+            return None
+        return QuestService._parse_numeric_quest_id(match.group("number"))
+
+    @staticmethod
+    def _quest_class_for(
+        *,
+        quest_id: str | None,
+        startup_contract: dict[str, Any] | None = None,
+    ) -> str:
+        normalized_quest_id = str(quest_id or "").strip()
+        match = _SYSTEM_NUMERIC_QUEST_ID_PATTERN.fullmatch(normalized_quest_id)
+        if match is not None:
+            prefix = str(match.group("prefix") or "").strip().upper()
+            if prefix == "S":
+                return "settings"
+            if prefix == "B":
+                return "benchstore"
+
+        contract = startup_contract if isinstance(startup_contract, dict) else {}
+        custom_profile = str(contract.get("custom_profile") or "").strip().lower()
+        if custom_profile in {"admin_ops", "settings_issue"}:
+            return "settings"
+        if isinstance(contract.get("benchstore_context"), dict) or isinstance(contract.get("start_setup_session"), dict):
+            return "benchstore"
+        return "research"
+
     @contextmanager
     def _quest_id_state_lock(self):
         lock_path = self._quest_id_lock_path()
@@ -2714,7 +2998,7 @@ class QuestService:
             return self._format_numeric_quest_id(next_numeric_id)
 
     def _reserve_numeric_quest_id(self, quest_id: str) -> None:
-        numeric_value = self._parse_numeric_quest_id(quest_id)
+        numeric_value = self._parse_reserved_numeric_quest_id(quest_id)
         if numeric_value is None:
             return
         with self._quest_id_state_lock():
@@ -2724,24 +3008,28 @@ class QuestService:
                 self._write_quest_id_state_locked(next_numeric_id)
 
     def _normalize_quest_id(self, quest_id: str | None) -> tuple[str, bool]:
-        raw = str(quest_id or "").strip().lower()
+        raw = str(quest_id or "").strip()
         if not raw:
             return self._allocate_next_numeric_quest_id(), True
-        slug = re.sub(r"[^a-z0-9._-]+", "-", raw).strip("._-")
+        slug = re.sub(r"[^A-Za-z0-9._-]+", "-", raw).strip("._-")
         if not slug:
             return self._allocate_next_numeric_quest_id(), True
+        system_match = _SYSTEM_NUMERIC_QUEST_ID_PATTERN.fullmatch(slug)
+        if system_match is not None:
+            slug = f"{str(system_match.group('prefix') or '').upper()}-{system_match.group('number')}"
         return slug[:80], False
 
     def create(
         self,
         goal: str,
         quest_id: str | None = None,
-        runner: str = "codex",
+        runner: str | None = None,
         title: str | None = None,
         *,
         requested_baseline_ref: dict[str, Any] | None = None,
         startup_contract: dict[str, Any] | None = None,
     ) -> dict:
+        resolved_runner = str(runner or self._configured_default_runner()).strip().lower() or "codex"
         quest_id, auto_generated = self._normalize_quest_id(quest_id)
         quest_root = self._quest_root(quest_id)
         if quest_root.exists():
@@ -2757,7 +3045,7 @@ class QuestService:
                 quest_id,
                 goal,
                 quest_root,
-                runner,
+                resolved_runner,
                 title=title,
                 requested_baseline_ref=dict(requested_baseline_ref) if isinstance(requested_baseline_ref, dict) else None,
                 startup_contract=dict(startup_contract) if isinstance(startup_contract, dict) else None,
@@ -2782,6 +3070,87 @@ class QuestService:
         self._initialize_runtime_files(quest_root)
         return self.snapshot(quest_id)
 
+    def repair_orphaned_quest_scaffold(
+        self,
+        quest_id: str,
+        *,
+        title: str | None = None,
+        goal: str | None = None,
+        runner: str | None = None,
+    ) -> dict[str, Any]:
+        resolved_runner = str(runner or self._configured_default_runner()).strip().lower() or "codex"
+        quest_root = self._quest_root(quest_id)
+        if not quest_root.exists():
+            raise FileNotFoundError(f"Unknown quest `{quest_id}`.")
+        quest_yaml_path = self._quest_yaml_path(quest_root)
+        if quest_yaml_path.exists():
+            raise FileExistsError(f"Quest `{quest_id}` already has a scaffold.")
+
+        restored_goal = str(goal or f"Recovered quest {quest_id}").strip() or f"Recovered quest {quest_id}"
+        restored_title = str(title or quest_id).strip() or quest_id
+
+        for relative in QUEST_DIRECTORIES:
+            ensure_dir(quest_root / relative)
+
+        write_yaml(
+            quest_yaml_path,
+            initial_quest_yaml(
+                quest_id,
+                restored_goal,
+                quest_root,
+                resolved_runner,
+                title=restored_title,
+            ),
+        )
+        write_text(
+            quest_root / "brief.md",
+            "\n".join(
+                [
+                    "# Quest Brief",
+                    "",
+                    "## Recovery Note",
+                    "",
+                    "This quest scaffold was recreated because the core quest files were missing.",
+                    "Existing runtime traces under `.ds/` were preserved.",
+                    "",
+                    "## Goal",
+                    "",
+                    restored_goal,
+                    "",
+                ]
+            ),
+        )
+        write_text(
+            quest_root / "plan.md",
+            "\n".join(
+                [
+                    "# Plan",
+                    "",
+                    "- [ ] Inspect preserved runtime traces under `.ds/`",
+                    "- [ ] Re-establish the baseline context",
+                    "- [ ] Recreate any missing durable files or artifacts",
+                    "",
+                ]
+            ),
+        )
+        write_text(
+            quest_root / "status.md",
+            "# Status\n\nRecovered scaffold. Review preserved runtime state before continuing.\n",
+        )
+        write_text(
+            quest_root / "SUMMARY.md",
+            "# Summary\n\nRecovered quest scaffold. Original top-level quest files were missing.\n",
+        )
+        write_text(quest_root / ".gitignore", gitignore())
+        self._write_active_user_requirements(
+            quest_root,
+            latest_requirement=None,
+        )
+        if not (quest_root / ".git").exists():
+            init_repo(quest_root)
+        self._initialize_runtime_files(quest_root)
+        return self.snapshot(quest_id)
+
     def list_quests(self) -> list[dict]:
         items: list[dict] = []
         if not self.quests_root.exists():
@@ -2879,7 +3248,7 @@ class QuestService:
         )
 
     def summary_compact(self, quest_id: str) -> dict[str, Any]:
-        quest_root = self._quest_root(quest_id)
+        quest_root = self._require_initialized_quest_root(quest_id)
         cache_key = f"compact:{self._cache_key_for_path(quest_root)}"
         state = self._compact_summary_state(quest_root)
         with self._snapshot_cache_lock:
@@ -2935,9 +3304,16 @@ class QuestService:
 
         bash_summary = BashExecService(self.home).summary(quest_root)
         interaction_watchdog = self.artifact_interaction_watchdog_status(quest_root)
+        quest_class = self._quest_class_for(
+            quest_id=str(quest_yaml.get("quest_id") or quest_id).strip(),
+            startup_contract=quest_yaml.get("startup_contract") if isinstance(quest_yaml.get("startup_contract"), dict) else None,
+        )
+        workspace_mode = str(research_state.get("workspace_mode") or "quest").strip().lower() or "quest"
+        listed_in_projects = quest_class == "research" and workspace_mode in {"copilot", "autonomous"}
         payload = {
             "quest_id": quest_yaml.get("quest_id", quest_id),
             "title": quest_yaml.get("title", quest_id),
+            "goal": quest_yaml.get("goal"),
             "quest_root": str(quest_root.resolve()),
             "status": runtime_state.get("display_status") or runtime_state.get("status") or quest_yaml.get("status", "idle"),
             "runtime_status": runtime_state.get("status") or quest_yaml.get("status", "idle"),
@@ -2953,7 +3329,9 @@ class QuestService:
             "research_head_worktree_root": research_state.get("research_head_worktree_root"),
             "current_workspace_branch": research_state.get("current_workspace_branch"),
             "current_workspace_root": research_state.get("current_workspace_root"),
-            "workspace_mode": research_state.get("workspace_mode") or "quest",
+            "workspace_mode": workspace_mode,
+            "quest_class": quest_class,
+            "listed_in_projects": listed_in_projects,
             "active_idea_id": research_state.get("active_idea_id"),
             "active_baseline_id": active_baseline_id,
             "active_baseline_variant_id": active_baseline_variant_id,
@@ -2962,6 +3340,7 @@ class QuestService:
             "continuation_anchor": runtime_state.get("continuation_anchor"),
             "continuation_reason": runtime_state.get("continuation_reason"),
             "continuation_updated_at": runtime_state.get("continuation_updated_at"),
+            "waiting_notice": runtime_state.get("waiting_notice"),
             "last_resume_source": runtime_state.get("last_resume_source"),
             "last_resume_at": runtime_state.get("last_resume_at"),
             "last_recovery_abandoned_run_id": runtime_state.get("last_recovery_abandoned_run_id"),
@@ -3056,18 +3435,18 @@ class QuestService:
                 self._jsonl_tail_cache.pop(cache_key, None)
             return [], 0, False
         if normalized_limit <= 0:
-            total = sum(1 for _ in _iter_jsonl_records_safely(path))
+            total = _count_jsonl_lines_fast(path)
             return [], total, False
 
         if before is not None:
-            stop_cursor = max(int(before) - 1, 0)
             window: deque[tuple[int, dict[str, Any]]] = deque(maxlen=normalized_limit)
             total = 0
-            for payload in _iter_jsonl_records_safely(path):
-                total += 1
-                if total >= before:
+            for cursor, payload in _iter_jsonl_records_safely(path):
+                total = cursor
+                if cursor >= before:
                     break
-                window.append((total, payload))
+                if isinstance(payload, dict):
+                    window.append((cursor, payload))
             has_more = bool(window and window[0][0] > 1)
             return list(window), total, has_more
 
@@ -3087,6 +3466,17 @@ class QuestService:
                     window = cached_records[-normalized_limit:]
                     has_more = cached_total > len(window)
                     return window, cached_total, has_more
+                if cached_limit < normalized_limit:
+                    window, total = _tail_jsonl_records_safely(path, limit=normalized_limit)
+                    with self._jsonl_cache_lock:
+                        self._jsonl_tail_cache[cache_key] = {
+                            "state": state,
+                            "limit": normalized_limit,
+                            "total": total,
+                            "records": list(window),
+                        }
+                    has_more = total > len(window)
+                    return list(window), total, has_more
 
             if (
                 cached_tail
@@ -3110,11 +3500,11 @@ class QuestService:
                     )
                 )
                 if appended_records:
-                    next_cursor = cached_total + 1
-                    for payload in appended_records:
-                        window.append((next_cursor, payload))
-                        next_cursor += 1
-                    total = cached_total + len(appended_records)
+                    total = cached_total
+                    for relative_cursor, payload in appended_records:
+                        total = cached_total + relative_cursor
+                        if isinstance(payload, dict):
+                            window.append((total, payload))
                 else:
                     total = cached_total
                 stored_records = list(window)
@@ -3125,6 +3515,13 @@ class QuestService:
                         "total": total,
                         "records": stored_records,
                     }
+                write_json(
+                    _jsonl_line_count_cache_path(path),
+                    {
+                        "state": list(state),
+                        "total": total,
+                    },
+                )
                 selected = stored_records[-normalized_limit:]
                 has_more = total > len(selected)
                 return selected, total, has_more
@@ -3144,12 +3541,14 @@ class QuestService:
         total = 0
         saw_more = False
         normalized_after = max(int(after or 0), 0)
-        for payload in _iter_jsonl_records_safely(path):
-            total += 1
-            if total <= normalized_after:
+        for cursor, payload in _iter_jsonl_records_safely(path):
+            total = cursor
+            if cursor <= normalized_after:
+                continue
+            if not isinstance(payload, dict):
                 continue
             if len(collected) < normalized_limit:
-                collected.append((total, payload))
+                collected.append((cursor, payload))
                 continue
             saw_more = True
         return collected, total, saw_more
@@ -3254,7 +3653,7 @@ class QuestService:
         return self._snapshot(quest_id)
 
     def _snapshot(self, quest_id: str) -> dict:
-        quest_root = self._quest_root(quest_id)
+        quest_root = self._require_initialized_quest_root(quest_id)
         cache_key = f"snapshot:{self._cache_key_for_path(quest_root)}"
         state = self._snapshot_state(quest_root)
         with self._snapshot_cache_lock:
@@ -3428,6 +3827,7 @@ class QuestService:
         payload = {
             "quest_id": quest_yaml.get("quest_id", quest_id),
             "title": quest_yaml.get("title", quest_id),
+            "goal": quest_yaml.get("goal"),
             "quest_root": str(quest_root.resolve()),
             "status": runtime_state.get("display_status") or runtime_state.get("status") or quest_yaml.get("status", "idle"),
             "runtime_status": runtime_state.get("status") or quest_yaml.get("status", "idle"),
@@ -3466,6 +3866,7 @@ class QuestService:
             "continuation_anchor": runtime_state.get("continuation_anchor"),
             "continuation_reason": runtime_state.get("continuation_reason"),
             "continuation_updated_at": runtime_state.get("continuation_updated_at"),
+            "waiting_notice": runtime_state.get("waiting_notice"),
             "last_resume_source": runtime_state.get("last_resume_source"),
             "last_resume_at": runtime_state.get("last_resume_at"),
             "last_recovery_abandoned_run_id": runtime_state.get("last_recovery_abandoned_run_id"),
@@ -3764,9 +4165,12 @@ class QuestService:
     def bind_source(self, quest_id: str, source: str) -> dict:
         quest_root = self._quest_root(quest_id)
         bindings_path = quest_root / ".ds" / "bindings.json"
+        existing_payload = read_json(bindings_path, {"sources": []})
+        existing_sources = existing_payload.get("sources") if isinstance(existing_payload, dict) else []
         bindings = self._binding_sources_payload(quest_root)
         normalized_source = self._normalize_binding_source(source)
-        next_sources = self._normalized_binding_sources([*(bindings.get("sources") or []), normalized_source])
+        seed_sources = list(existing_sources) if isinstance(existing_sources, list) else list(bindings.get("sources") or [])
+        next_sources = self._normalized_binding_sources([*seed_sources, normalized_source])
         changed = list(bindings.get("sources") or []) != next_sources
         if changed:
             bindings["sources"] = next_sources
@@ -3824,6 +4228,8 @@ class QuestService:
         title: str | None = None,
         active_anchor: str | None = None,
         default_runner: str | None = None,
+        workspace_mode: str | None = None,
+        decision_policy: str | None = None,
     ) -> dict:
         quest_root = self._quest_root(quest_id)
         quest_yaml_path = self._quest_yaml_path(quest_root)
@@ -3832,6 +4238,8 @@ class QuestService:
 
         quest_data = self.read_quest_yaml(quest_root)
         changed = False
+        research_state_updates: dict[str, Any] = {}
+        runtime_state_updates: dict[str, Any] = {}
 
         if title is not None:
             normalized_title = str(title).strip()
@@ -3865,13 +4273,73 @@ class QuestService:
             if normalized_runner not in available_runners:
                 allowed = ", ".join(sorted(available_runners))
                 raise ValueError(f"Unsupported runner `{normalized_runner}`. Available runners: {allowed}.")
+            runners = ConfigManager(self.home).load_runners_config()
+            runner_cfg = runners.get(normalized_runner, {}) if isinstance(runners.get(normalized_runner), dict) else {}
+            if runner_cfg.get("enabled") is False:
+                fallback = self._resolve_enabled_runner_name(normalized_runner)
+                if fallback == normalized_runner:
+                    raise ValueError(f"Runner `{normalized_runner}` is disabled and no enabled fallback runner is available.")
+                normalized_runner = fallback
             if quest_data.get("default_runner") != normalized_runner:
                 quest_data["default_runner"] = normalized_runner
                 changed = True
 
+        if workspace_mode is not None:
+            normalized_workspace_mode = str(workspace_mode).strip().lower()
+            if normalized_workspace_mode not in {"copilot", "autonomous"}:
+                raise ValueError("Unsupported workspace mode. Allowed values: copilot, autonomous.")
+            startup_contract = (
+                dict(quest_data.get("startup_contract") or {})
+                if isinstance(quest_data.get("startup_contract"), dict)
+                else {}
+            )
+            if str(startup_contract.get("workspace_mode") or "").strip().lower() != normalized_workspace_mode:
+                startup_contract["workspace_mode"] = normalized_workspace_mode
+                quest_data["startup_contract"] = startup_contract
+                changed = True
+            if str(self.read_research_state(quest_root).get("workspace_mode") or "").strip().lower() != normalized_workspace_mode:
+                research_state_updates["workspace_mode"] = normalized_workspace_mode
+            runtime_state_updates["continuation_policy"] = (
+                "wait_for_user_or_resume" if normalized_workspace_mode == "copilot" else "auto"
+            )
+            runtime_state_updates["continuation_reason"] = (
+                "copilot_mode" if normalized_workspace_mode == "copilot" else "autonomous_mode"
+            )
+
+        if decision_policy is not None:
+            normalized_decision_policy = str(decision_policy).strip().lower()
+            if normalized_decision_policy not in {"autonomous", "user_gated"}:
+                raise ValueError("Unsupported decision policy. Allowed values: autonomous, user_gated.")
+            startup_contract = (
+                dict(quest_data.get("startup_contract") or {})
+                if isinstance(quest_data.get("startup_contract"), dict)
+                else {}
+            )
+            if str(startup_contract.get("decision_policy") or "").strip().lower() != normalized_decision_policy:
+                startup_contract["decision_policy"] = normalized_decision_policy
+                quest_data["startup_contract"] = startup_contract
+                changed = True
+            effective_workspace_mode = str(
+                research_state_updates.get("workspace_mode")
+                or self.read_research_state(quest_root).get("workspace_mode")
+                or startup_contract.get("workspace_mode")
+                or ""
+            ).strip().lower()
+            if normalized_decision_policy == "autonomous" and effective_workspace_mode == "autonomous":
+                runtime_state = self._read_runtime_state(quest_root)
+                current_policy = str(runtime_state.get("continuation_policy") or "").strip().lower()
+                current_reason = str(runtime_state.get("continuation_reason") or "").strip()
+                if current_policy == "wait_for_user_or_resume" and current_reason not in AUTONOMOUS_BLOCKING_WAIT_REASONS:
+                    runtime_state_updates["continuation_policy"] = "auto"
+                    runtime_state_updates["continuation_reason"] = "autonomous_decision_policy"
+
         if changed:
             quest_data["updated_at"] = utc_now()
             write_yaml(quest_yaml_path, quest_data)
+        if research_state_updates:
+            self.update_research_state(quest_root, **research_state_updates)
+        if runtime_state_updates:
+            self.update_runtime_state(quest_root=quest_root, **runtime_state_updates)
 
         return self.snapshot(quest_id)
 
@@ -3973,11 +4441,26 @@ class QuestService:
                 active_run_id=active_run_id or None,
                 last_transition_at=last_transition_at,
             )
+            # Reconcile continuation_policy with current workspace_mode so that
+            # a mode switch that happened before/during the crash is respected.
+            research_state = self.read_research_state(quest_root)
+            workspace_mode = str(research_state.get("workspace_mode") or "").strip().lower()
+            current_policy = str(runtime_state.get("continuation_policy") or "").strip().lower()
+            reconciled_policy_updates: dict[str, Any] = {}
+            if workspace_mode == "autonomous" and current_policy == "wait_for_user_or_resume":
+                reconciled_policy_updates["continuation_policy"] = "auto"
+                reconciled_policy_updates["continuation_reason"] = "autonomous_mode_reconciled"
+                reconciled_policy_updates["continuation_updated_at"] = utc_now()
+            elif workspace_mode == "copilot" and current_policy == "auto":
+                reconciled_policy_updates["continuation_policy"] = "wait_for_user_or_resume"
+                reconciled_policy_updates["continuation_reason"] = "copilot_mode_reconciled"
+                reconciled_policy_updates["continuation_updated_at"] = utc_now()
             self.update_runtime_state(
                 quest_root=quest_root,
                 status="stopped",
                 active_run_id=None,
                 stop_reason="crash_recovered",
+                **reconciled_policy_updates,
             )
             summary = (
                 f"Recovered quest from stale runtime state; previous status `{previous_status}`"
@@ -4117,8 +4600,15 @@ class QuestService:
 
     def node_traces(self, quest_id: str, *, selection_type: str | None = None) -> dict:
         quest_root = self._quest_root(quest_id)
-        workflow = self.workflow(quest_id)
         snapshot = self.snapshot(quest_id)
+        try:
+            workflow = self._build_details_projection_payload(
+                quest_root,
+                source_signature=self._projection_source_signature(quest_root, "details"),
+                update_progress=lambda *_args, **_kwargs: None,
+            )
+        except Exception:
+            workflow = self.workflow(quest_id)
         payload = QuestNodeTraceManager(quest_root).materialize(
             quest_id=quest_id,
             workflow=workflow,
@@ -4308,7 +4798,7 @@ class QuestService:
             return payload
 
     def list_documents(self, quest_id: str) -> list[dict]:
-        quest_root = self._quest_root(quest_id)
+        quest_root = self._require_initialized_quest_root(quest_id)
         workspace_root = self.active_workspace_root(quest_root)
         documents = []
         for relative in ("brief.md", "plan.md", "status.md", "SUMMARY.md"):
@@ -4359,10 +4849,11 @@ class QuestService:
         mode: str | None = None,
         profile: str | None = None,
     ) -> dict:
+        profile = str(profile or "").strip().lower() or None
         if revision:
             return self._revision_explorer(quest_id, revision=revision, mode=mode or "ref")
 
-        quest_root = self._quest_root(quest_id)
+        quest_root = self._require_initialized_quest_root(quest_id)
         workspace_root = self.active_workspace_root(quest_root)
         git_status = self._git_status_map(workspace_root)
 
@@ -4389,9 +4880,9 @@ class QuestService:
         }
 
     def search_files(self, quest_id: str, term: str, limit: int = 50) -> dict[str, Any]:
-        query = term.strip()
+        query = self._normalize_explorer_search_query(term)
         normalized_query = query.casefold()
-        workspace_root = self.active_workspace_root(self._quest_root(quest_id))
+        workspace_root = self.active_workspace_root(self._require_initialized_quest_root(quest_id))
         resolved_limit = max(1, min(limit, 200))
         if not normalized_query:
             return {
@@ -4415,6 +4906,41 @@ class QuestService:
             except OSError:
                 continue
 
+            relative = path.relative_to(workspace_root).as_posix()
+            scope, writable = self._classify_path_scope(workspace_root, path)
+            path_haystack = relative.casefold()
+            name_haystack = path.name.casefold()
+            if normalized_query in path_haystack or normalized_query in name_haystack:
+                haystack = path_haystack
+                match_spans: list[dict[str, int]] = []
+                start = 0
+                while True:
+                    found = haystack.find(normalized_query, start)
+                    if found < 0:
+                        break
+                    match_spans.append({"start": found, "end": found + len(query)})
+                    start = found + max(1, len(query))
+                renderer_hint, mime_type = self._renderer_hint_for(path)
+                items.append(
+                    {
+                        "id": f"{relative}:path",
+                        "document_id": f"path::{relative}",
+                        "title": path.name,
+                        "path": relative,
+                        "scope": scope,
+                        "writable": writable,
+                        "line_number": 0,
+                        "line_text": relative,
+                        "snippet": relative[:320],
+                        "match_spans": match_spans,
+                        "open_kind": renderer_hint,
+                        "mime_type": mime_type,
+                    }
+                )
+                if len(items) >= resolved_limit:
+                    truncated = True
+                    break
+
             renderer_hint, mime_type = self._renderer_hint_for(path)
             if not self._is_text_document(path, mime_type, renderer_hint):
                 continue
@@ -4437,8 +4963,6 @@ class QuestService:
                 continue
 
             files_scanned += 1
-            relative = path.relative_to(workspace_root).as_posix()
-            scope, writable = self._classify_path_scope(workspace_root, path)
 
             for line_index, line in enumerate(content.splitlines(), start=1):
                 haystack = line.casefold()
@@ -4485,8 +5009,17 @@ class QuestService:
             "files_scanned": files_scanned,
         }
 
+    @staticmethod
+    def _normalize_explorer_search_query(term: str) -> str:
+        query = str(term or "").strip()
+        if len(query) >= 2 and query.startswith("*") and query.endswith("*"):
+            inner = query.strip("*").strip()
+            if inner and not any(marker in inner for marker in "*?[]"):
+                return inner
+        return query
+
     def open_document(self, quest_id: str, document_id: str) -> dict:
-        quest_root = self._quest_root(quest_id)
+        quest_root = self._require_initialized_quest_root(quest_id)
         workspace_root = self.active_workspace_root(quest_root)
         if document_id.startswith("git::"):
             revision, relative = self._parse_git_document_id(document_id)
@@ -4522,12 +5055,16 @@ class QuestService:
                 },
             }
 
+        shared_source_quest_id = None
+        parsed_shared_memory = self._parse_shared_memory_document_id(document_id)
+        if parsed_shared_memory is not None:
+            shared_source_quest_id = parsed_shared_memory[0]
         path, writable, scope, source_kind = self.resolve_document(quest_id, document_id)
         renderer_hint, mime_type = self._renderer_hint_for(path)
         is_text = self._is_text_document(path, mime_type, renderer_hint)
         content = read_text(path) if is_text else ""
         revision = f"sha256:{sha256_text(content)}" if is_text else f"sha256:{hashlib.sha256(path.read_bytes()).hexdigest()}"
-        return {
+        payload = {
             "document_id": document_id,
             "quest_id": quest_id,
             "title": path.name if "::" in document_id else document_id,
@@ -4549,9 +5086,17 @@ class QuestService:
                 "renderer_hint": renderer_hint,
             },
         }
+        if shared_source_quest_id:
+            payload["source_quest_id"] = shared_source_quest_id
+            if isinstance(payload.get("meta"), dict):
+                payload["meta"]["source_quest_id"] = shared_source_quest_id
+                payload["meta"]["shared"] = True
+        return payload
 
     def resolve_document(self, quest_id: str, document_id: str) -> tuple[Path, bool, str, str]:
-        quest_root = self._quest_root(quest_id)
+        quest_root = self._require_initialized_quest_root(quest_id)
+        if document_id.startswith(_SHARED_MEMORY_DOCUMENT_PREFIX):
+            return self._resolve_shared_memory_document(document_id)
         workspace_root = self.active_workspace_root(quest_root)
         resolution_root = self._document_resolution_root(
             quest_root=quest_root,
@@ -4568,6 +5113,32 @@ class QuestService:
                 return self._resolve_document(quest_root, f"questpath::{legacy_relative}")
             raise
 
+    def _resolve_shared_memory_document(self, document_id: str) -> tuple[Path, bool, str, str]:
+        parsed = self._parse_shared_memory_document_id(document_id)
+        if parsed is None:
+            raise FileNotFoundError(f"Unknown shared memory document `{document_id}`.")
+        source_quest_id, relative = parsed
+        source_quest_root = self._require_initialized_quest_root(source_quest_id)
+        root = (source_quest_root / "memory").resolve()
+        path = (root / relative).resolve()
+        if path != root and root not in path.parents:
+            raise ValueError("Document ID escapes shared quest memory.")
+        if not path.exists() or not path.is_file():
+            raise FileNotFoundError(f"Unknown shared quest memory `{source_quest_id}:{relative}`.")
+        return path, False, "shared_quest_memory", "shared_quest_memory"
+
+    @staticmethod
+    def _parse_shared_memory_document_id(document_id: str) -> tuple[str, str] | None:
+        raw = str(document_id or "").strip()
+        if not raw.startswith(_SHARED_MEMORY_DOCUMENT_PREFIX):
+            return None
+        _prefix, source_quest_id, relative = (raw.split("::", 2) + ["", "", ""])[:3]
+        source_quest_id = source_quest_id.strip()
+        relative = relative.lstrip("/")
+        if not source_quest_id or not relative:
+            return None
+        return source_quest_id, relative
+
     def save_document(self, quest_id: str, document_id: str, content: str, previous_revision: str | None = None) -> dict:
         current = self.open_document(quest_id, document_id)
         if not current.get("writable", False):
@@ -4744,20 +5315,545 @@ class QuestService:
             "saved_at": utc_now(),
         }
 
-    def _revision_explorer(self, quest_id: str, *, revision: str, mode: str) -> dict:
+    def save_chat_attachment_draft(
+        self,
+        quest_id: str,
+        *,
+        file_name: str,
+        mime_type: str | None,
+        content: bytes,
+        draft_id: str | None = None,
+    ) -> dict[str, Any]:
         quest_root = self._quest_root(quest_id)
-        if not self._git_revision_exists(quest_root, revision):
-            raise FileNotFoundError(f"Unknown git revision `{revision}`.")
-
-        snapshot_paths = self._git_snapshot_paths(quest_root, revision)
-        snapshot_tree = self._build_snapshot_tree(snapshot_paths)
-        root_nodes = self._snapshot_children(snapshot_tree, revision=revision, prefix="")
-        sections = self._group_explorer_sections(root_nodes)
-
+        normalized_draft_id = slugify(str(draft_id or generate_id("draft")), default=generate_id("draft"))
+        draft_root = self._chat_attachment_draft_root(quest_root, normalized_draft_id)
+        original_name = Path(file_name).name or "attachment.bin"
+        suffix = Path(original_name).suffix.lower()
+        if not suffix:
+            guessed_suffix = mimetypes.guess_extension(mime_type or "", strict=False) or ""
+            suffix = ".jpg" if guessed_suffix == ".jpe" else guessed_suffix
+        safe_stem = slugify(Path(original_name).stem or "attachment", default="attachment")
+        stored_name = f"{safe_stem}{suffix or '.bin'}"
+        asset_path = resolve_within(draft_root, stored_name)
+        if draft_root.exists():
+            for child in draft_root.iterdir():
+                if child.is_file():
+                    child.unlink(missing_ok=True)
+                elif child.is_dir():
+                    shutil.rmtree(child, ignore_errors=True)
+        ensure_dir(draft_root)
+        asset_path.write_bytes(content)
+        quest_relative_path = asset_path.relative_to(quest_root).as_posix()
+        asset_document_id = f"path::{quest_relative_path}"
+        attachment = self._chat_attachment_payload(
+            quest_id=quest_id,
+            name=original_name,
+            stored_name=stored_name,
+            mime_type=mime_type,
+            asset_path=asset_path,
+            draft_id=normalized_draft_id,
+        )
+        attachment["status"] = "success"
+        write_json(
+            draft_root / "manifest.json",
+            {
+                "draft_id": normalized_draft_id,
+                "quest_id": quest_id,
+                "created_at": utc_now(),
+                "attachment": attachment,
+                "asset_document_id": asset_document_id,
+            },
+        )
         return {
+            "ok": True,
             "quest_id": quest_id,
-            "quest_root": str(quest_root.resolve()),
-            "view": {
+            "draft_id": normalized_draft_id,
+            **attachment,
+        }
+
+    def delete_chat_attachment_draft(self, quest_id: str, *, draft_id: str) -> dict[str, Any]:
+        self._quest_root(quest_id)
+        normalized_draft_id = slugify(str(draft_id or "").strip(), default="")
+        if not normalized_draft_id:
+            return {"ok": False, "message": "`draft_id` is required."}
+        draft_root = self._chat_attachment_draft_root(self._quest_root(quest_id), normalized_draft_id)
+        if not draft_root.exists():
+            return {
+                "ok": True,
+                "status": "already_deleted",
+                "quest_id": quest_id,
+                "draft_id": normalized_draft_id,
+            }
+        shutil.rmtree(draft_root, ignore_errors=True)
+        return {
+            "ok": True,
+            "status": "deleted",
+            "quest_id": quest_id,
+            "draft_id": normalized_draft_id,
+        }
+
+    def import_chat_attachment_drafts(
+        self,
+        target_quest_id: str,
+        *,
+        source_quest_id: str,
+        attachments: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        target_quest_root = self._quest_root(target_quest_id)
+        source_quest_root = self._quest_root(source_quest_id)
+        imported: list[dict[str, Any]] = []
+        for index, raw_attachment in enumerate(attachments, start=1):
+            if not isinstance(raw_attachment, dict):
+                continue
+            quest_relative_path = str(raw_attachment.get("quest_relative_path") or "").strip()
+            absolute_path = str(raw_attachment.get("path") or "").strip()
+            source_path: Path | None = None
+            if quest_relative_path:
+                source_path = resolve_within(source_quest_root, quest_relative_path)
+            elif absolute_path:
+                candidate = Path(absolute_path).resolve()
+                if candidate == source_quest_root or source_quest_root in candidate.parents:
+                    source_path = candidate
+            if source_path is None or not source_path.exists() or not source_path.is_file():
+                continue
+            file_name = str(
+                raw_attachment.get("name")
+                or raw_attachment.get("file_name")
+                or source_path.name
+                or f"attachment-{index:03d}"
+            ).strip() or f"attachment-{index:03d}"
+            mime_type = str(raw_attachment.get("content_type") or raw_attachment.get("mime_type") or "").strip() or None
+            created = self.save_chat_attachment_draft(
+                target_quest_root.name,
+                file_name=file_name,
+                mime_type=mime_type,
+                content=source_path.read_bytes(),
+            )
+            imported.append(created)
+        return {
+            "ok": True,
+            "quest_id": target_quest_id,
+            "source_quest_id": source_quest_id,
+            "imported_count": len(imported),
+            "attachments": imported,
+        }
+
+    def finalize_chat_attachment_drafts(
+        self,
+        quest_id: str,
+        *,
+        draft_ids: list[str],
+        client_message_id: str | None,
+    ) -> list[dict[str, Any]]:
+        quest_root = self._quest_root(quest_id)
+        normalized_draft_ids = [
+            slugify(str(item or "").strip(), default="")
+            for item in draft_ids
+            if str(item or "").strip()
+        ]
+        if not normalized_draft_ids:
+            return []
+        batch_slug = slugify(
+            str(client_message_id or generate_id("userfile")).strip(),
+            default=generate_id("userfile"),
+        )
+        batch_root = ensure_dir(quest_root / "userfiles" / "web" / batch_slug)
+        materialized: list[dict[str, Any]] = []
+        for index, normalized_draft_id in enumerate(normalized_draft_ids, start=1):
+            draft_root = self._chat_attachment_draft_root(quest_root, normalized_draft_id)
+            manifest = read_json(draft_root / "manifest.json", {})
+            attachment = dict(manifest.get("attachment") or {})
+            source_path = Path(str(attachment.get("path") or "").strip())
+            if not draft_root.exists() or not source_path.exists():
+                raise FileNotFoundError(f"Unknown chat attachment draft `{normalized_draft_id}`.")
+            target_name = self._dedupe_attachment_filename(
+                batch_root,
+                str(attachment.get("stored_name") or source_path.name or f"attachment-{index:03d}.bin"),
+            )
+            target_path = resolve_within(batch_root, target_name)
+            ensure_dir(target_path.parent)
+            shutil.move(str(source_path), str(target_path))
+            finalized = self._chat_attachment_payload(
+                quest_id=quest_id,
+                name=str(attachment.get("name") or target_name),
+                stored_name=target_name,
+                mime_type=str(attachment.get("content_type") or "").strip() or None,
+                asset_path=target_path,
+                draft_id=None,
+            )
+            finalized["source_path"] = str(source_path)
+            finalized["materialized"] = True
+            finalized["uploaded_at"] = str(attachment.get("uploaded_at") or utc_now())
+            materialized.append(finalized)
+            shutil.rmtree(draft_root, ignore_errors=True)
+        write_json(
+            batch_root / "manifest.json",
+            {
+                "quest_id": quest_id,
+                "client_message_id": str(client_message_id or "").strip() or None,
+                "materialized_at": utc_now(),
+                "attachments": materialized,
+            },
+        )
+        return materialized
+
+    @staticmethod
+    def _chat_attachment_draft_root(quest_root: Path, draft_id: str) -> Path:
+        return quest_root / "userfiles" / "web" / "_staging" / draft_id
+
+    @staticmethod
+    def _dedupe_attachment_filename(batch_root: Path, file_name: str) -> str:
+        base_name = Path(file_name).name or "attachment.bin"
+        stem = Path(base_name).stem or "attachment"
+        suffix = Path(base_name).suffix
+        candidate = base_name
+        counter = 2
+        while (batch_root / candidate).exists():
+            candidate = f"{stem}-{counter}{suffix}"
+            counter += 1
+        return candidate
+
+    @staticmethod
+    def _is_readable_chat_attachment(path: Path, mime_type: str | None) -> bool:
+        normalized_mime = str(mime_type or "").strip().lower()
+        if any(normalized_mime.startswith(prefix) for prefix in _CHAT_ATTACHMENT_TEXT_MIME_PREFIXES):
+            return True
+        if normalized_mime in _CHAT_ATTACHMENT_TEXT_MIME_TYPES:
+            return True
+        return path.suffix.lower() in _CHAT_ATTACHMENT_TEXT_EXTENSIONS
+
+    def _chat_attachment_payload(
+        self,
+        *,
+        quest_id: str,
+        name: str,
+        stored_name: str,
+        mime_type: str | None,
+        asset_path: Path,
+        draft_id: str | None,
+    ) -> dict[str, Any]:
+        quest_root = self._quest_root(quest_id)
+        resolved_path = asset_path.resolve()
+        content_type = mimetypes.guess_type(resolved_path.name)[0] or mime_type or "application/octet-stream"
+        quest_relative_path = resolved_path.relative_to(quest_root).as_posix()
+        payload: dict[str, Any] = {
+            "kind": "image" if str(content_type).startswith("image/") else "path",
+            "name": name,
+            "file_name": stored_name,
+            "content_type": content_type,
+            "path": str(resolved_path),
+            "quest_relative_path": quest_relative_path,
+            "asset_document_id": f"path::{quest_relative_path}",
+            "asset_url": f"/api/quests/{quest_id}/documents/asset?document_id={quote(f'path::{quest_relative_path}', safe='')}",
+            "size_bytes": resolved_path.stat().st_size if resolved_path.exists() else 0,
+            "uploaded_at": utc_now(),
+            "upload_origin": "web",
+        }
+        if draft_id:
+            payload["draft_id"] = draft_id
+        if self._is_readable_chat_attachment(resolved_path, content_type):
+            payload["extracted_text_path"] = quest_relative_path
+        return payload
+
+    @staticmethod
+    def _normalize_workspace_relative_path(
+        relative: str | None,
+        *,
+        field_name: str,
+        allow_root: bool = True,
+    ) -> str | None:
+        if relative is None:
+            if allow_root:
+                return None
+            raise ValueError(f"`{field_name}` is required.")
+        raw = str(relative).strip().replace("\\", "/")
+        if not raw:
+            if allow_root:
+                return None
+            raise ValueError(f"`{field_name}` is required.")
+        normalized = raw.lstrip("/").rstrip("/")
+        if normalized in {"", "."}:
+            if allow_root:
+                return None
+            raise ValueError(f"`{field_name}` must point to a workspace entry.")
+        return normalized
+
+    @staticmethod
+    def _normalize_workspace_entry_name(name: str | None, *, field_name: str) -> str:
+        raw = str(name or "").strip().replace("\\", "/")
+        if not raw:
+            raise ValueError(f"`{field_name}` is required.")
+        if "/" in raw:
+            raise ValueError(f"`{field_name}` must be a single path segment.")
+        candidate = Path(raw).name
+        if candidate != raw or candidate in {"", ".", ".."}:
+            raise ValueError(f"`{field_name}` must be a valid file or folder name.")
+        if candidate == ".git":
+            raise ValueError("`.git` cannot be created or renamed from the explorer.")
+        return candidate
+
+    @staticmethod
+    def _normalize_workspace_path_list(paths: Any, *, field_name: str) -> list[str]:
+        if not isinstance(paths, list) or not paths:
+            raise ValueError(f"`{field_name}` must be a non-empty list.")
+        normalized: list[str] = []
+        seen: set[str] = set()
+        for raw in paths:
+            item = QuestService._normalize_workspace_relative_path(
+                raw,
+                field_name=field_name,
+                allow_root=False,
+            )
+            if not item or item in seen:
+                continue
+            seen.add(item)
+            normalized.append(item)
+        if not normalized:
+            raise ValueError(f"`{field_name}` must include at least one valid path.")
+        return normalized
+
+    @staticmethod
+    def _filter_nested_workspace_paths(paths: list[str]) -> list[str]:
+        kept: list[str] = []
+        for path in paths:
+            if any(path == parent or path.startswith(f"{parent}/") for parent in kept):
+                continue
+            kept.append(path)
+        return kept
+
+    def _workspace_entry_payload(self, workspace_root: Path, path: Path) -> dict:
+        if path.is_dir():
+            return self._directory_node(
+                workspace_root,
+                path=path,
+                children=[],
+                git_status={},
+                changed_paths={},
+            )
+        payload = self._file_node(
+            workspace_root,
+            path=path,
+            git_status={},
+            changed_paths={},
+        )
+        if payload is None:
+            raise FileNotFoundError(f"Unknown workspace entry `{path}`.")
+        return payload
+
+    def create_workspace_folder(
+        self,
+        quest_id: str,
+        *,
+        name: str | None,
+        parent_path: str | None = None,
+    ) -> dict:
+        workspace_root = self.active_workspace_root(self._require_initialized_quest_root(quest_id))
+        normalized_parent = self._normalize_workspace_relative_path(
+            parent_path,
+            field_name="parent_path",
+            allow_root=True,
+        )
+        folder_name = self._normalize_workspace_entry_name(name, field_name="name")
+        parent = resolve_within(workspace_root, normalized_parent) if normalized_parent else workspace_root
+        if not parent.exists() or not parent.is_dir():
+            raise FileNotFoundError(
+                f"Unknown destination folder `{normalized_parent or '.'}`."
+            )
+        target = resolve_within(parent, folder_name)
+        if target.exists():
+            raise FileExistsError(
+                f"`{target.relative_to(workspace_root).as_posix()}` already exists."
+            )
+        ensure_dir(target)
+        return {
+            "ok": True,
+            "quest_id": quest_id,
+            "parent_path": normalized_parent,
+            "item": self._workspace_entry_payload(workspace_root, target),
+            "saved_at": utc_now(),
+        }
+
+    def upload_workspace_file(
+        self,
+        quest_id: str,
+        *,
+        file_name: str | None,
+        content: bytes,
+        mime_type: str | None = None,
+        parent_path: str | None = None,
+    ) -> dict:
+        workspace_root = self.active_workspace_root(self._require_initialized_quest_root(quest_id))
+        normalized_parent = self._normalize_workspace_relative_path(
+            parent_path,
+            field_name="parent_path",
+            allow_root=True,
+        )
+        safe_name = self._normalize_workspace_entry_name(file_name, field_name="file_name")
+        parent = resolve_within(workspace_root, normalized_parent) if normalized_parent else workspace_root
+        if not parent.exists() or not parent.is_dir():
+            raise FileNotFoundError(
+                f"Unknown destination folder `{normalized_parent or '.'}`."
+            )
+        target = resolve_within(parent, safe_name)
+        if target.exists():
+            raise FileExistsError(
+                f"`{target.relative_to(workspace_root).as_posix()}` already exists."
+            )
+        ensure_dir(target.parent)
+        target.write_bytes(content)
+        payload = self._workspace_entry_payload(workspace_root, target)
+        guessed_mime = mimetypes.guess_type(target.name)[0] or mime_type or "application/octet-stream"
+        payload["mime_type"] = guessed_mime
+        return {
+            "ok": True,
+            "quest_id": quest_id,
+            "parent_path": normalized_parent,
+            "item": payload,
+            "saved_at": utc_now(),
+        }
+
+    def rename_workspace_entry(
+        self,
+        quest_id: str,
+        *,
+        path: str | None,
+        new_name: str | None,
+    ) -> dict:
+        workspace_root = self.active_workspace_root(self._require_initialized_quest_root(quest_id))
+        normalized_path = self._normalize_workspace_relative_path(
+            path,
+            field_name="path",
+            allow_root=False,
+        )
+        source = resolve_within(workspace_root, normalized_path)
+        if not source.exists():
+            raise FileNotFoundError(f"Unknown workspace entry `{normalized_path}`.")
+        safe_name = self._normalize_workspace_entry_name(new_name, field_name="new_name")
+        target = resolve_within(source.parent, safe_name)
+        if target.exists() and target != source:
+            raise FileExistsError(
+                f"`{target.relative_to(workspace_root).as_posix()}` already exists."
+            )
+        if target != source:
+            source.rename(target)
+        payload = self._workspace_entry_payload(workspace_root, target)
+        return {
+            "ok": True,
+            "quest_id": quest_id,
+            "previous_path": normalized_path,
+            "item": payload,
+            "saved_at": utc_now(),
+        }
+
+    def move_workspace_entries(
+        self,
+        quest_id: str,
+        *,
+        paths: Any,
+        target_parent_path: str | None = None,
+    ) -> dict:
+        workspace_root = self.active_workspace_root(self._require_initialized_quest_root(quest_id))
+        normalized_paths = self._filter_nested_workspace_paths(
+            self._normalize_workspace_path_list(paths, field_name="paths")
+        )
+        normalized_target_parent = self._normalize_workspace_relative_path(
+            target_parent_path,
+            field_name="target_parent_path",
+            allow_root=True,
+        )
+        target_parent = (
+            resolve_within(workspace_root, normalized_target_parent)
+            if normalized_target_parent
+            else workspace_root
+        )
+        if not target_parent.exists() or not target_parent.is_dir():
+            raise FileNotFoundError(
+                f"Unknown destination folder `{normalized_target_parent or '.'}`."
+            )
+
+        moves: list[tuple[str, Path, Path]] = []
+        destination_keys: set[str] = set()
+        target_parent_resolved = target_parent.resolve()
+        for normalized_path in normalized_paths:
+            source = resolve_within(workspace_root, normalized_path)
+            if not source.exists():
+                raise FileNotFoundError(f"Unknown workspace entry `{normalized_path}`.")
+            source_resolved = source.resolve()
+            if source_resolved == target_parent_resolved or source_resolved in target_parent_resolved.parents:
+                raise ValueError(
+                    f"`{normalized_path}` cannot be moved into itself or one of its descendants."
+                )
+            destination = resolve_within(target_parent, source.name)
+            if destination.exists() and destination.resolve() != source_resolved:
+                raise FileExistsError(
+                    f"`{destination.relative_to(workspace_root).as_posix()}` already exists."
+                )
+            destination_key = str(destination.resolve())
+            if destination_key in destination_keys and destination != source:
+                raise FileExistsError(
+                    f"`{destination.relative_to(workspace_root).as_posix()}` would conflict with another moved entry."
+                )
+            destination_keys.add(destination_key)
+            moves.append((normalized_path, source, destination))
+
+        items: list[dict] = []
+        for _normalized_path, source, destination in moves:
+            if destination != source:
+                source.rename(destination)
+            items.append(self._workspace_entry_payload(workspace_root, destination))
+        return {
+            "ok": True,
+            "quest_id": quest_id,
+            "target_parent_path": normalized_target_parent,
+            "items": items,
+            "saved_at": utc_now(),
+        }
+
+    def delete_workspace_entries(
+        self,
+        quest_id: str,
+        *,
+        paths: Any,
+    ) -> dict:
+        workspace_root = self.active_workspace_root(self._require_initialized_quest_root(quest_id))
+        normalized_paths = self._filter_nested_workspace_paths(
+            self._normalize_workspace_path_list(paths, field_name="paths")
+        )
+        sources: list[Path] = []
+        items: list[dict] = []
+        for normalized_path in normalized_paths:
+            source = resolve_within(workspace_root, normalized_path)
+            if not source.exists():
+                raise FileNotFoundError(f"Unknown workspace entry `{normalized_path}`.")
+            sources.append(source)
+            items.append(self._workspace_entry_payload(workspace_root, source))
+
+        for source in sorted(sources, key=lambda item: len(item.parts), reverse=True):
+            if source.is_dir():
+                shutil.rmtree(source)
+            else:
+                source.unlink()
+        return {
+            "ok": True,
+            "quest_id": quest_id,
+            "items": items,
+            "saved_at": utc_now(),
+        }
+
+    def _revision_explorer(self, quest_id: str, *, revision: str, mode: str) -> dict:
+        quest_root = self._quest_root(quest_id)
+        if not self._git_revision_exists(quest_root, revision):
+            raise FileNotFoundError(f"Unknown git revision `{revision}`.")
+
+        snapshot_paths = self._git_snapshot_paths(quest_root, revision)
+        snapshot_tree = self._build_snapshot_tree(snapshot_paths)
+        root_nodes = self._snapshot_children(snapshot_tree, revision=revision, prefix="")
+        sections = self._group_explorer_sections(root_nodes)
+
+        return {
+            "quest_id": quest_id,
+            "quest_root": str(quest_root.resolve()),
+            "view": {
                 "mode": mode,
                 "revision": revision,
                 "label": revision,
@@ -4874,9 +5970,10 @@ class QuestService:
     @staticmethod
     def _default_message_queue() -> dict[str, Any]:
         return {
-            "version": 1,
+            "version": 2,
             "pending": [],
             "completed": [],
+            "message_states": {},
         }
 
     def _default_runtime_state(
@@ -4907,6 +6004,7 @@ class QuestService:
             "continuation_anchor": None,
             "continuation_reason": None,
             "continuation_updated_at": None,
+            "waiting_notice": None,
             "last_resume_source": None,
             "last_resume_at": None,
             "last_recovery_abandoned_run_id": None,
@@ -4918,6 +6016,7 @@ class QuestService:
             "last_delivered_batch_id": None,
             "last_delivered_at": None,
             "retry_state": None,
+            "turn_message_override": None,
         }
 
     def _default_agent_status(self, quest_root: Path) -> dict[str, Any]:
@@ -4936,6 +6035,8 @@ class QuestService:
         }
 
     def _initialize_runtime_files(self, quest_root: Path) -> None:
+        if not self._quest_yaml_path(quest_root).exists():
+            raise FileNotFoundError(f"Unknown quest `{quest_root.name}`.")
         queue_path = self._message_queue_path(quest_root)
         if not queue_path.exists():
             write_json(queue_path, self._default_message_queue())
@@ -4956,9 +6057,11 @@ class QuestService:
         payload = self._read_cached_json(self._message_queue_path(quest_root), self._default_message_queue())
         if not isinstance(payload, dict):
             payload = self._default_message_queue()
-        payload.setdefault("version", 1)
+        payload.setdefault("version", 2)
         payload.setdefault("pending", [])
         payload.setdefault("completed", [])
+        message_states = payload.get("message_states")
+        payload["message_states"] = dict(message_states) if isinstance(message_states, dict) else {}
         return payload
 
     def _write_message_queue(self, quest_root: Path, payload: dict[str, Any]) -> None:
@@ -4986,6 +6089,7 @@ class QuestService:
         merged["continuation_anchor"] = str(merged.get("continuation_anchor") or "").strip() or None
         merged["continuation_reason"] = str(merged.get("continuation_reason") or "").strip() or None
         merged["continuation_updated_at"] = str(merged.get("continuation_updated_at") or "").strip() or None
+        merged["waiting_notice"] = dict(merged.get("waiting_notice") or {}) if isinstance(merged.get("waiting_notice"), dict) else None
         merged["last_resume_source"] = str(merged.get("last_resume_source") or "").strip() or None
         merged["last_resume_at"] = str(merged.get("last_resume_at") or "").strip() or None
         merged["last_recovery_abandoned_run_id"] = str(merged.get("last_recovery_abandoned_run_id") or "").strip() or None
@@ -4994,6 +6098,11 @@ class QuestService:
         merged["last_stage_fingerprint_at"] = str(merged.get("last_stage_fingerprint_at") or "").strip() or None
         merged["same_fingerprint_auto_turn_count"] = int(merged.get("same_fingerprint_auto_turn_count") or 0)
         merged["retry_state"] = dict(merged.get("retry_state") or {}) if isinstance(merged.get("retry_state"), dict) else None
+        merged["turn_message_override"] = (
+            dict(merged.get("turn_message_override") or {})
+            if isinstance(merged.get("turn_message_override"), dict)
+            else None
+        )
         return merged
 
     def _write_runtime_state(self, quest_root: Path, payload: dict[str, Any]) -> None:
@@ -5016,6 +6125,7 @@ class QuestService:
         continuation_anchor: str | None | object = _UNSET,
         continuation_reason: str | None | object = _UNSET,
         continuation_updated_at: str | None | object = _UNSET,
+        waiting_notice: dict[str, Any] | None | object = _UNSET,
         last_resume_source: str | None | object = _UNSET,
         last_resume_at: str | None | object = _UNSET,
         last_recovery_abandoned_run_id: str | None | object = _UNSET,
@@ -5028,6 +6138,7 @@ class QuestService:
         last_delivered_at: str | None | object = _UNSET,
         display_status: str | None | object = _UNSET,
         retry_state: dict[str, Any] | None | object = _UNSET,
+        turn_message_override: dict[str, Any] | None | object = _UNSET,
     ) -> dict[str, Any]:
         with self._runtime_state_lock(quest_root):
             state = self._read_runtime_state(quest_root)
@@ -5084,6 +6195,8 @@ class QuestService:
                 state["continuation_updated_at"] = str(continuation_updated_at or "").strip() or None
             elif continuation_changed:
                 state["continuation_updated_at"] = now
+            if waiting_notice is not _UNSET:
+                state["waiting_notice"] = dict(waiting_notice) if isinstance(waiting_notice, dict) else None
             if last_resume_source is not _UNSET:
                 state["last_resume_source"] = str(last_resume_source or "").strip() or None
             if last_resume_at is not _UNSET:
@@ -5106,6 +6219,12 @@ class QuestService:
                 state["last_delivered_at"] = last_delivered_at
             if retry_state is not _UNSET:
                 state["retry_state"] = dict(retry_state) if isinstance(retry_state, dict) else None
+            if turn_message_override is not _UNSET:
+                state["turn_message_override"] = (
+                    dict(turn_message_override)
+                    if isinstance(turn_message_override, dict)
+                    else None
+                )
             if last_transition_at is not _UNSET:
                 state["last_transition_at"] = last_transition_at
             elif status_changed or run_changed:
@@ -5147,11 +6266,369 @@ class QuestService:
             continuation_reason=reason,
         )
 
+    @staticmethod
+    def _normalize_message_read_state(value: object, *, default: str = "read") -> str:
+        normalized = str(value or "").strip().lower() or default
+        return normalized if normalized in {"read", "unread"} else default
+
+    def _update_message_read_state(
+        self,
+        queue_payload: dict[str, Any],
+        *,
+        message_id: str | None,
+        client_message_id: str | None = None,
+        source: str | None = None,
+        conversation_id: str | None = None,
+        created_at: str | None = None,
+        read_state: str,
+        read_reason: str | None = None,
+        read_at: str | None = None,
+        read_interaction_id: str | None = None,
+        read_run_id: str | None = None,
+    ) -> dict[str, Any] | None:
+        normalized_message_id = str(message_id or "").strip()
+        normalized_client_message_id = str(client_message_id or "").strip() or None
+        if not normalized_message_id and not normalized_client_message_id:
+            return None
+        states = dict(queue_payload.get("message_states") or {})
+        key = normalized_message_id or f"client:{normalized_client_message_id}"
+        current = dict(states.get(key) or {})
+        current["message_id"] = normalized_message_id or current.get("message_id")
+        if normalized_client_message_id:
+            current["client_message_id"] = normalized_client_message_id
+        if source:
+            current["source"] = str(source)
+        if conversation_id:
+            current["conversation_id"] = str(conversation_id)
+        if created_at:
+            current["created_at"] = str(created_at)
+        current["read_state"] = self._normalize_message_read_state(read_state)
+        current["read_reason"] = str(read_reason or "").strip() or None
+        current["read_at"] = str(read_at or "").strip() or None
+        current["read_interaction_id"] = str(read_interaction_id or "").strip() or None
+        current["read_run_id"] = str(read_run_id or "").strip() or None
+        current["updated_at"] = utc_now()
+        states[key] = current
+        if normalized_message_id:
+            for existing_key, item in list(states.items()):
+                if existing_key == key or not isinstance(item, dict):
+                    continue
+                if str(item.get("message_id") or "").strip() == normalized_message_id:
+                    states.pop(existing_key, None)
+            if normalized_client_message_id:
+                states[normalized_message_id] = current
+                if key != normalized_message_id:
+                    states.pop(key, None)
+                key = normalized_message_id
+        queue_payload["message_states"] = states
+        return dict(states.get(key) or current)
+
+    def _message_read_state(
+        self,
+        quest_root: Path,
+        *,
+        message_id: str | None = None,
+        client_message_id: str | None = None,
+    ) -> dict[str, Any] | None:
+        queue_payload = self._read_message_queue(quest_root)
+        states = queue_payload.get("message_states")
+        if not isinstance(states, dict):
+            return None
+        normalized_message_id = str(message_id or "").strip()
+        normalized_client_message_id = str(client_message_id or "").strip()
+        if normalized_message_id:
+            direct = states.get(normalized_message_id)
+            if isinstance(direct, dict):
+                return dict(direct)
+        for item in states.values():
+            if not isinstance(item, dict):
+                continue
+            if normalized_message_id and str(item.get("message_id") or "").strip() == normalized_message_id:
+                return dict(item)
+            if normalized_client_message_id and str(item.get("client_message_id") or "").strip() == normalized_client_message_id:
+                return dict(item)
+        return None
+
+    @staticmethod
+    def _find_message_queue_entry(
+        items: list[dict[str, Any]],
+        *,
+        message_id: str | None = None,
+        client_message_id: str | None = None,
+    ) -> tuple[int, dict[str, Any]] | tuple[None, None]:
+        normalized_message_id = str(message_id or "").strip()
+        normalized_client_message_id = str(client_message_id or "").strip()
+        if not normalized_message_id and not normalized_client_message_id:
+            return None, None
+        for index in range(len(items) - 1, -1, -1):
+            item = items[index]
+            if normalized_message_id and str(item.get("message_id") or "").strip() == normalized_message_id:
+                return index, dict(item)
+            if normalized_client_message_id and str(item.get("client_message_id") or "").strip() == normalized_client_message_id:
+                return index, dict(item)
+        return None, None
+
+    def pending_user_message_status(
+        self,
+        quest_root: Path,
+        *,
+        message_id: str | None = None,
+        client_message_id: str | None = None,
+    ) -> dict[str, Any]:
+        queue_payload = self._read_message_queue(quest_root)
+        pending = [dict(item) for item in (queue_payload.get("pending") or []) if isinstance(item, dict)]
+        completed = [dict(item) for item in (queue_payload.get("completed") or []) if isinstance(item, dict)]
+        pending_index, pending_item = self._find_message_queue_entry(
+            pending,
+            message_id=message_id,
+            client_message_id=client_message_id,
+        )
+        state_record = self._message_read_state(
+            quest_root,
+            message_id=message_id,
+            client_message_id=client_message_id,
+        )
+        completed_index, completed_item = self._find_message_queue_entry(
+            completed,
+            message_id=message_id,
+            client_message_id=client_message_id,
+        )
+        queue_state = "missing"
+        if pending_index is not None and pending_item is not None:
+            queue_state = "pending"
+        elif state_record:
+            read_reason = str(state_record.get("read_reason") or "").strip()
+            queue_state = "withdrawn" if read_reason == "withdrawn_by_user" else "read"
+        elif completed_index is not None and completed_item is not None:
+            completed_status = str(completed_item.get("status") or "").strip()
+            queue_state = "withdrawn" if completed_status == "withdrawn_by_user" else "read"
+        return {
+            "queue_state": queue_state,
+            "pending_index": pending_index,
+            "pending_item": pending_item,
+            "completed_index": completed_index,
+            "completed_item": completed_item,
+            "message_state": state_record,
+        }
+
+    def latest_pending_user_message(self, quest_id: str) -> dict[str, Any] | None:
+        quest_root = self._quest_root(quest_id)
+        queue_payload = self._read_message_queue(quest_root)
+        pending = [dict(item) for item in (queue_payload.get("pending") or []) if isinstance(item, dict)]
+        if not pending:
+            return None
+        latest = dict(pending[-1])
+        return {
+            "id": latest.get("message_id"),
+            "message_id": latest.get("message_id"),
+            "client_message_id": latest.get("client_message_id"),
+            "role": "user",
+            "source": latest.get("source"),
+            "content": latest.get("content") or "",
+            "created_at": latest.get("created_at"),
+            "reply_to_interaction_id": latest.get("reply_to_interaction_id"),
+            "attachments": [dict(item) for item in (latest.get("attachments") or []) if isinstance(item, dict)],
+        }
+
+    def withdraw_pending_user_message(
+        self,
+        quest_id: str,
+        *,
+        message_id: str | None,
+        source: str,
+    ) -> dict[str, Any]:
+        normalized_message_id = str(message_id or "").strip()
+        if not normalized_message_id:
+            return {
+                "ok": False,
+                "status": "invalid_request",
+                "message": "Message id is required.",
+            }
+        quest_root = self._quest_root(quest_id)
+        queue_payload = self._read_message_queue(quest_root)
+        status_payload = self.pending_user_message_status(
+            quest_root,
+            message_id=normalized_message_id,
+        )
+        pending_index = status_payload.get("pending_index")
+        pending_item = dict(status_payload.get("pending_item") or {}) if isinstance(status_payload.get("pending_item"), dict) else None
+        if pending_index is None or pending_item is None:
+            queue_state = str(status_payload.get("queue_state") or "missing")
+            message_state = (
+                dict(status_payload.get("message_state") or {})
+                if isinstance(status_payload.get("message_state"), dict)
+                else None
+            )
+            if queue_state == "read":
+                return {
+                    "ok": False,
+                    "status": "already_read",
+                    "message": "Withdrawal failed because this message was already sent to the agent.",
+                    "message_id": normalized_message_id,
+                    "current_message_state": message_state,
+                }
+            if queue_state == "withdrawn":
+                return {
+                    "ok": True,
+                    "status": "already_withdrawn",
+                    "message": "This message was already withdrawn from the waiting queue.",
+                    "message_id": normalized_message_id,
+                    "current_message_state": message_state,
+                }
+            return {
+                "ok": False,
+                "status": "missing",
+                "message": f"Message `{normalized_message_id}` is not waiting in the queue.",
+                "message_id": normalized_message_id,
+                "current_message_state": message_state,
+            }
+
+        pending = [dict(item) for item in (queue_payload.get("pending") or []) if isinstance(item, dict)]
+        completed = [dict(item) for item in (queue_payload.get("completed") or []) if isinstance(item, dict)]
+        withdrawn_at = utc_now()
+        withdrawn = {
+            **pending.pop(int(pending_index)),
+            "status": "withdrawn_by_user",
+            "withdrawn_at": withdrawn_at,
+            "withdrawn_by_source": source,
+        }
+        queue_payload["pending"] = pending
+        queue_payload["completed"] = [*completed, withdrawn][-200:]
+        state_record = self._update_message_read_state(
+            queue_payload,
+            message_id=str(withdrawn.get("message_id") or "").strip() or None,
+            client_message_id=str(withdrawn.get("client_message_id") or "").strip() or None,
+            source=str(withdrawn.get("source") or "").strip() or None,
+            conversation_id=str(withdrawn.get("conversation_id") or "").strip() or None,
+            created_at=str(withdrawn.get("created_at") or "").strip() or None,
+            read_state="read",
+            read_reason="withdrawn_by_user",
+            read_at=withdrawn_at,
+        )
+        self._write_message_queue(quest_root, queue_payload)
+        self.update_runtime_state(
+            quest_root=quest_root,
+            pending_user_message_count=len(pending),
+        )
+        self.append_message_read_state_event(
+            quest_id,
+            message_id=str(withdrawn.get("message_id") or "").strip() or None,
+            client_message_id=str(withdrawn.get("client_message_id") or "").strip() or None,
+            read_state=str((state_record or {}).get("read_state") or "read"),
+            read_reason=str((state_record or {}).get("read_reason") or "withdrawn_by_user"),
+            read_at=str((state_record or {}).get("read_at") or withdrawn_at),
+        )
+        append_jsonl(
+            self._interaction_journal_path(quest_root),
+            {
+                "event_id": generate_id("evt"),
+                "type": "user_message_withdrawn",
+                "quest_id": quest_id,
+                "message_id": normalized_message_id,
+                "source": source,
+                "created_at": withdrawn_at,
+            },
+        )
+        self._write_active_user_requirements(quest_root, latest_requirement=None)
+        return {
+            "ok": True,
+            "status": "withdrawn",
+            "message": "The message was removed from the waiting queue.",
+            "message_id": normalized_message_id,
+            "pending_user_message_count": len(pending),
+            "current_message_state": state_record,
+        }
+
+    def enrich_conversation_message_event(self, quest_id: str, event: dict[str, Any]) -> dict[str, Any]:
+        if str(event.get("type") or "").strip() != "conversation.message":
+            return dict(event)
+        quest_root = self._quest_root(quest_id)
+        read_state = self._message_read_state(
+            quest_root,
+            message_id=str(event.get("message_id") or "").strip() or None,
+            client_message_id=str(event.get("client_message_id") or "").strip() or None,
+        )
+        enriched = dict(event)
+        if read_state:
+            enriched["read_state"] = read_state.get("read_state")
+            enriched["read_reason"] = read_state.get("read_reason")
+            enriched["read_at"] = read_state.get("read_at")
+        return enriched
+
+    def append_message_read_state_event(
+        self,
+        quest_id: str,
+        *,
+        message_id: str | None,
+        client_message_id: str | None = None,
+        read_state: str,
+        read_reason: str | None = None,
+        read_at: str | None = None,
+    ) -> dict[str, Any]:
+        payload = {
+            "event_id": generate_id("evt"),
+            "type": "conversation.message_state",
+            "quest_id": quest_id,
+            "message_id": str(message_id or "").strip() or None,
+            "client_message_id": str(client_message_id or "").strip() or None,
+            "read_state": self._normalize_message_read_state(read_state),
+            "read_reason": str(read_reason or "").strip() or None,
+            "read_at": str(read_at or "").strip() or None,
+            "created_at": utc_now(),
+        }
+        append_jsonl(self._quest_root(quest_id) / ".ds" / "events.jsonl", payload)
+        return payload
+
+    def set_turn_message_override(
+        self,
+        quest_root: Path,
+        *,
+        turn_reason: str,
+        message: str,
+        message_ids: list[str] | None = None,
+        delivery_batch_id: str | None = None,
+        source: str | None = None,
+    ) -> dict[str, Any]:
+        payload = {
+            "turn_reason": str(turn_reason or "").strip() or "user_message",
+            "message": str(message or "").strip(),
+            "message_ids": [str(item).strip() for item in (message_ids or []) if str(item).strip()],
+            "delivery_batch_id": str(delivery_batch_id or "").strip() or None,
+            "source": str(source or "").strip() or None,
+            "created_at": utc_now(),
+        }
+        self.update_runtime_state(
+            quest_root=quest_root,
+            turn_message_override=payload,
+        )
+        return payload
+
+    def consume_turn_message_override(
+        self,
+        quest_root: Path,
+        *,
+        expected_turn_reason: str | None = None,
+    ) -> dict[str, Any] | None:
+        with self._runtime_state_lock(quest_root):
+            state = self._read_runtime_state(quest_root)
+            override = dict(state.get("turn_message_override") or {}) if isinstance(state.get("turn_message_override"), dict) else None
+            if not override:
+                return None
+            if expected_turn_reason:
+                normalized_expected = str(expected_turn_reason or "").strip()
+                normalized_actual = str(override.get("turn_reason") or "").strip()
+                if normalized_expected and normalized_actual != normalized_expected:
+                    return None
+            state["turn_message_override"] = None
+            self._write_runtime_state(quest_root, state)
+            return override
+
     def _enqueue_user_message(self, quest_root: Path, record: dict[str, Any]) -> dict[str, Any]:
         queue_payload = self._read_message_queue(quest_root)
         source = str(record.get("source") or "local")
         queue_record = {
             "message_id": record.get("id"),
+            "client_message_id": str(record.get("client_message_id") or "").strip() or None,
             "source": source,
             "conversation_id": self._normalize_binding_source(source),
             "content": record.get("content") or "",
@@ -5161,6 +6638,17 @@ class QuestService:
             "status": "queued",
         }
         queue_payload["pending"] = [*list(queue_payload.get("pending") or []), queue_record]
+        self._update_message_read_state(
+            queue_payload,
+            message_id=str(queue_record.get("message_id") or "").strip() or None,
+            client_message_id=str(queue_record.get("client_message_id") or "").strip() or None,
+            source=source,
+            conversation_id=str(queue_record.get("conversation_id") or "").strip() or None,
+            created_at=str(queue_record.get("created_at") or "").strip() or None,
+            read_state="unread",
+            read_reason="queued",
+            read_at=None,
+        )
         self._write_message_queue(quest_root, queue_payload)
         self.update_runtime_state(
             quest_root=quest_root,
@@ -5190,7 +6678,27 @@ class QuestService:
             for item in read_jsonl(quest_root / ".ds" / "conversations" / "main.jsonl")
             if str(item.get("role") or "") == "user"
         ]
-        latest = latest_requirement or (user_messages[-1] if user_messages else None)
+        filtered_user_messages = []
+        for item in user_messages:
+            state = self._message_read_state(
+                quest_root,
+                message_id=str(item.get("id") or "").strip() or None,
+                client_message_id=str(item.get("client_message_id") or "").strip() or None,
+            )
+            if str((state or {}).get("read_reason") or "").strip() == "withdrawn_by_user":
+                continue
+            filtered_user_messages.append(item)
+        latest = latest_requirement
+        if latest is not None:
+            latest_state = self._message_read_state(
+                quest_root,
+                message_id=str(latest.get("id") or "").strip() or None,
+                client_message_id=str(latest.get("client_message_id") or "").strip() or None,
+            )
+            if str((latest_state or {}).get("read_reason") or "").strip() == "withdrawn_by_user":
+                latest = None
+        if latest is None:
+            latest = filtered_user_messages[-1] if filtered_user_messages else None
         lines = [
             "# Active User Requirements",
             "",
@@ -5209,12 +6717,17 @@ class QuestService:
             "",
         ]
         if latest:
+            latest_rendered = self._agent_visible_user_message_content(
+                quest_root,
+                content=str(latest.get("content") or ""),
+                attachments=[dict(item) for item in (latest.get("attachments") or []) if isinstance(item, dict)],
+            )
             lines.extend(
                 [
                     f"- source: {latest.get('source') or 'local'}",
                     f"- created_at: {latest.get('created_at') or utc_now()}",
                     "",
-                    str(latest.get("content") or "").strip() or "No latest requirement text was captured.",
+                    latest_rendered or "No latest requirement text was captured.",
                     "",
                 ]
             )
@@ -5231,11 +6744,15 @@ class QuestService:
                 "",
             ]
         )
-        if user_messages:
-            for index, item in enumerate(user_messages[-12:], start=1):
+        if filtered_user_messages:
+            for index, item in enumerate(filtered_user_messages[-12:], start=1):
                 source = str(item.get("source") or "local").strip() or "local"
                 created_at = str(item.get("created_at") or "").strip() or "unknown"
-                content = str(item.get("content") or "").strip() or "(empty)"
+                content = self._agent_visible_user_message_content(
+                    quest_root,
+                    content=str(item.get("content") or ""),
+                    attachments=[dict(value) for value in (item.get("attachments") or []) if isinstance(value, dict)],
+                ) or "(empty)"
                 lines.append(f"{index}. [{source}] [{created_at}] {content}")
         else:
             lines.append("1. No user messages yet.")
@@ -5277,11 +6794,31 @@ class QuestService:
         }
         queue_payload["pending"] = pending
         queue_payload["completed"] = [*list(queue_payload.get("completed") or []), claimed][-200:]
+        state_record = self._update_message_read_state(
+            queue_payload,
+            message_id=str(claimed.get("message_id") or "").strip() or None,
+            client_message_id=str(claimed.get("client_message_id") or "").strip() or None,
+            source=str(claimed.get("source") or "").strip() or None,
+            conversation_id=str(claimed.get("conversation_id") or "").strip() or None,
+            created_at=str(claimed.get("created_at") or "").strip() or None,
+            read_state="read",
+            read_reason="accepted_by_run",
+            read_at=now,
+            read_run_id=run_id,
+        )
         self._write_message_queue(quest_root, queue_payload)
         self.update_runtime_state(
             quest_root=quest_root,
             pending_user_message_count=len(pending),
         )
+        self.append_message_read_state_event(
+            quest_id,
+            message_id=str(claimed.get("message_id") or "").strip() or None,
+            client_message_id=str(claimed.get("client_message_id") or "").strip() or None,
+            read_state=str((state_record or {}).get("read_state") or "read"),
+            read_reason=str((state_record or {}).get("read_reason") or "accepted_by_run"),
+            read_at=str((state_record or {}).get("read_at") or now),
+        )
         append_jsonl(
             self._interaction_journal_path(quest_root),
             {
@@ -5331,6 +6868,26 @@ class QuestService:
         ]
         queue_payload["pending"] = []
         queue_payload["completed"] = [*list(queue_payload.get("completed") or []), *cancelled][-200:]
+        for item in cancelled:
+            self._update_message_read_state(
+                queue_payload,
+                message_id=str(item.get("message_id") or "").strip() or None,
+                client_message_id=str(item.get("client_message_id") or "").strip() or None,
+                source=str(item.get("source") or "").strip() or None,
+                conversation_id=str(item.get("conversation_id") or "").strip() or None,
+                created_at=str(item.get("created_at") or "").strip() or None,
+                read_state="read",
+                read_reason=reason,
+                read_at=now,
+            )
+            self.append_message_read_state_event(
+                quest_id,
+                message_id=str(item.get("message_id") or "").strip() or None,
+                client_message_id=str(item.get("client_message_id") or "").strip() or None,
+                read_state="read",
+                read_reason=reason,
+                read_at=now,
+            )
         self._write_message_queue(quest_root, queue_payload)
         append_jsonl(
             self._interaction_journal_path(quest_root),
@@ -5490,11 +7047,13 @@ class QuestService:
         *,
         interaction_id: str | None,
         limit: int = 10,
+        delivery_reason: str = "artifact_mailbox",
     ) -> dict[str, Any]:
         queue_payload = self._read_message_queue(quest_root)
         pending = [dict(item) for item in (queue_payload.get("pending") or [])]
         recent_records = self.latest_artifact_interaction_records(quest_root, limit=max(limit, 10))
         delivered_messages: list[dict[str, Any]] = []
+        delivered_state_records: list[dict[str, Any]] = []
         delivery_batch = None
         now = utc_now()
 
@@ -5511,6 +7070,29 @@ class QuestService:
                 delivered_messages.append(delivered)
             queue_payload["pending"] = []
             queue_payload["completed"] = [*list(queue_payload.get("completed") or []), *delivered_messages][-200:]
+            for item in delivered_messages:
+                state_record = self._update_message_read_state(
+                    queue_payload,
+                    message_id=str(item.get("message_id") or "").strip() or None,
+                    client_message_id=str(item.get("client_message_id") or "").strip() or None,
+                    source=str(item.get("source") or "").strip() or None,
+                    conversation_id=str(item.get("conversation_id") or "").strip() or None,
+                    created_at=str(item.get("created_at") or "").strip() or None,
+                    read_state="read",
+                    read_reason=delivery_reason,
+                    read_at=now,
+                    read_interaction_id=interaction_id,
+                )
+                self.append_message_read_state_event(
+                    quest_root.name,
+                    message_id=str(item.get("message_id") or "").strip() or None,
+                    client_message_id=str(item.get("client_message_id") or "").strip() or None,
+                    read_state=str((state_record or {}).get("read_state") or "read"),
+                    read_reason=str((state_record or {}).get("read_reason") or delivery_reason),
+                    read_at=str((state_record or {}).get("read_at") or now),
+                )
+                if state_record:
+                    delivered_state_records.append(dict(state_record))
             self._write_message_queue(quest_root, queue_payload)
             append_jsonl(
                 self._interaction_journal_path(quest_root),
@@ -5533,6 +7115,8 @@ class QuestService:
             delivery_batch = {
                 "batch_id": batch_id,
                 "message_ids": [item.get("message_id") for item in delivered_messages],
+                "client_message_ids": [item.get("client_message_id") for item in delivered_messages],
+                "delivered_at": now,
             }
         else:
             self.update_runtime_state(
@@ -5540,15 +7124,45 @@ class QuestService:
                 pending_user_message_count=0,
             )
 
+        state_by_message_id = {
+            str(item.get("message_id") or "").strip(): dict(item)
+            for item in delivered_state_records
+            if str(item.get("message_id") or "").strip()
+        }
+        state_by_client_message_id = {
+            str(item.get("client_message_id") or "").strip(): dict(item)
+            for item in delivered_state_records
+            if str(item.get("client_message_id") or "").strip()
+        }
         recent_inbound_messages = [
             {
                 "message_id": item.get("message_id"),
+                "client_message_id": item.get("client_message_id"),
                 "source": str(item.get("conversation_id") or item.get("source") or "local").split(":", 1)[0],
                 "conversation_id": item.get("conversation_id") or self._normalize_binding_source(str(item.get("source") or "local")),
                 "sender": "user",
                 "created_at": item.get("created_at"),
+                "read_state": (
+                    state_by_message_id.get(str(item.get("message_id") or "").strip())
+                    or state_by_client_message_id.get(str(item.get("client_message_id") or "").strip())
+                    or {}
+                ).get("read_state") or "read",
+                "read_reason": (
+                    state_by_message_id.get(str(item.get("message_id") or "").strip())
+                    or state_by_client_message_id.get(str(item.get("client_message_id") or "").strip())
+                    or {}
+                ).get("read_reason") or delivery_reason,
+                "read_at": (
+                    state_by_message_id.get(str(item.get("message_id") or "").strip())
+                    or state_by_client_message_id.get(str(item.get("client_message_id") or "").strip())
+                    or {}
+                ).get("read_at") or now,
                 "text": item.get("content") or "",
-                "content": item.get("content") or "",
+                "content": self._agent_visible_user_message_content(
+                    quest_root,
+                    content=str(item.get("content") or ""),
+                    attachments=[dict(attachment) for attachment in (item.get("attachments") or []) if isinstance(attachment, dict)],
+                ),
                 "attachments": [dict(attachment) for attachment in (item.get("attachments") or []) if isinstance(attachment, dict)],
                 "reply_to_interaction_id": item.get("reply_to_interaction_id"),
             }
@@ -5596,7 +7210,12 @@ class QuestService:
             ]
             for index, item in enumerate(delivered_messages, start=1):
                 source = str(item.get("conversation_id") or item.get("source") or "local")
-                lines.append(f"{index}. [{source}] {item.get('content') or ''}")
+                rendered_content = self._agent_visible_user_message_content(
+                    quest_root,
+                    content=str(item.get("content") or ""),
+                    attachments=[dict(attachment) for attachment in (item.get("attachments") or []) if isinstance(attachment, dict)],
+                )
+                lines.append(f"{index}. [{source}] {rendered_content}")
             agent_instruction = "\n".join(lines).strip()
         else:
             lines = [
@@ -5637,12 +7256,60 @@ class QuestService:
         return {
             "delivery_batch": delivery_batch,
             "recent_inbound_messages": recent_inbound_messages,
+            "message_states": delivered_state_records,
             "recent_interaction_records": recent_records[-10:],
             "agent_instruction": agent_instruction,
             "queued_message_count_before_delivery": len(pending),
             "queued_message_count_after_delivery": len(queue_payload.get("pending") or []),
         }
 
+    def _agent_visible_user_message_content(
+        self,
+        quest_root: Path,
+        *,
+        content: str,
+        attachments: list[dict[str, Any]] | None = None,
+    ) -> str:
+        base = str(content or "").strip()
+        normalized_attachments = [dict(item) for item in (attachments or []) if isinstance(item, dict)]
+        if not normalized_attachments:
+            return base
+        lines: list[str] = []
+        if base:
+            lines.extend([base, ""])
+        lines.append(
+            self.localized_copy(
+                quest_root=quest_root,
+                zh="系统提示：用户刚刚发送了附件。请优先阅读这些 quest 本地文件，再继续处理这条请求：",
+                en="System note: the user just sent attachments. Read these quest-local files first before continuing this request:",
+            )
+        )
+        for index, item in enumerate(normalized_attachments, start=1):
+            label = str(
+                item.get("name")
+                or item.get("file_name")
+                or item.get("quest_relative_path")
+                or item.get("path")
+                or item.get("url")
+                or f"attachment-{index}"
+            ).strip()
+            content_type = str(item.get("content_type") or item.get("mime_type") or "").strip()
+            location = str(
+                item.get("extracted_text_path")
+                or item.get("ocr_text_path")
+                or item.get("archive_manifest_path")
+                or item.get("quest_relative_path")
+                or item.get("url")
+                or ("hidden" if str(item.get("path") or "").strip() else "unavailable")
+            ).strip()
+            error = str(item.get("download_error") or item.get("path_error") or "").strip()
+            suffix = f" ({content_type})" if content_type else ""
+            if error:
+                lines.append(f"- {label}{suffix}: {location} | attachment_error={error}")
+            else:
+                lines.append(f"- {label}{suffix}: {location}")
+        return "\n".join(lines).strip()
+
     @staticmethod
     def _document_resolution_root(quest_root: Path, workspace_root: Path, document_id: str) -> Path:
         if document_id.startswith(("questpath::", "memory::")):
@@ -5835,12 +7502,10 @@ class QuestService:
 
     @staticmethod
     def _read_git_bytes(quest_root: Path, revision: str, relative: str) -> bytes:
-        result = subprocess.run(
+        result = run_command_bytes(
             ["git", "show", f"{revision}:{relative}"],
-            cwd=str(quest_root),
+            cwd=quest_root,
             check=False,
-            text=False,
-            capture_output=True,
         )
         if result.returncode != 0:
             raise FileNotFoundError(f"File `{relative}` does not exist at `{revision}`.")
@@ -6006,19 +7671,36 @@ class QuestService:
             return True
         if relative.startswith(".ds/worktrees/"):
             return True
+        heavy_runtime_roots = {
+            ".ds/bash_exec",
+            ".ds/runs",
+            ".ds/codex_history",
+            ".ds/codex_homes",
+            ".ds/claude-home",
+            ".ds/opencode-home",
+            ".ds/evidence_packets",
+            ".ds/slim_backups",
+            ".ds/cold_archive",
+        }
+        normalized = relative.strip("/")
+        if any(normalized == root or normalized.startswith(f"{root}/") for root in heavy_runtime_roots):
+            return True
         parts = PurePosixPath(relative).parts
         return "__pycache__" in parts or ".pytest_cache" in parts
 
     @staticmethod
     def _skip_explorer_profile_relative(relative: str, profile: str | None) -> bool:
-        if profile != "mobile":
+        profile = str(profile or "").strip().lower()
+        if profile not in {"mobile", "workspace"}:
             return False
         normalized = relative.strip("/")
         if not normalized:
             return False
         parts = PurePosixPath(normalized).parts
         top = parts[0] if parts else normalized
-        if top in {".codex", ".claude", ".ds", "tmp", "userfiles", "artifacts"}:
+        if top in {".codex", ".claude", ".kimi", ".opencode", ".ds", "tmp", "userfiles"}:
+            return True
+        if profile == "mobile" and top == "artifacts":
             return True
         if top.startswith(".") and normalized not in {".gitignore"}:
             return True
@@ -6026,7 +7708,8 @@ class QuestService:
 
     @staticmethod
     def _truncate_explorer_directory(relative: str, *, profile: str | None, depth: int) -> bool:
-        if profile != "mobile":
+        profile = str(profile or "").strip().lower()
+        if profile not in {"mobile", "workspace"}:
             return False
         normalized = relative.strip("/")
         if not normalized:
@@ -6035,11 +7718,19 @@ class QuestService:
         top = parts[0] if parts else normalized
         if top == "memory":
             return False
+        if profile == "mobile":
+            if top == "baselines":
+                return depth >= 1
+            if top in {"literature", "paper", "experiments", "handoffs"}:
+                return depth >= 2
+            return depth >= 1
         if top == "baselines":
+            return depth >= 2
+        if top == "artifacts":
             return depth >= 1
         if top in {"literature", "paper", "experiments", "handoffs"}:
-            return depth >= 2
-        return depth >= 1
+            return depth >= 3
+        return depth >= 2
 
     @staticmethod
     def _classify_path_scope(quest_root: Path, path: Path) -> tuple[str, bool]: