@researai/deepscientist 1.5.14 → 1.5.15

package/src/deepscientist/doctor.py

@@ -11,6 +11,7 @@ from typing import Any
 from urllib.error import URLError
 from urllib.request import Request, urlopen
 
+from .bash_exec.shells import build_exec_shell_launch, build_terminal_shell_launch
 from .config import ConfigManager
 from .home import ensure_home_layout
 from .runtime_tools import RuntimeToolService
@@ -321,6 +322,55 @@ def _check_bundles(repo_root: Path) -> dict[str, Any]:
     )
 
 
+def _check_shell_backend() -> dict[str, Any]:
+    exec_launch = build_exec_shell_launch("echo ok")
+    terminal_launch = build_terminal_shell_launch(Path("doctor-terminal-probe"))
+
+    def resolve_binary(binary: str) -> str | None:
+        candidate = str(binary or "").strip()
+        if not candidate:
+            return None
+        if os.path.isabs(candidate) or os.path.sep in candidate or (os.path.altsep and os.path.altsep in candidate):
+            return candidate if Path(candidate).exists() else None
+        return which(candidate)
+
+    details = {
+        "exec_shell": exec_launch.shell_name,
+        "exec_shell_family": exec_launch.family,
+        "exec_argv": exec_launch.argv,
+        "terminal_shell": terminal_launch.shell_name,
+        "terminal_shell_family": terminal_launch.family,
+        "terminal_argv": terminal_launch.argv,
+    }
+    warnings: list[str] = []
+    guidance: list[str] = []
+    errors: list[str] = []
+
+    exec_binary = resolve_binary(exec_launch.argv[0])
+    terminal_binary = resolve_binary(terminal_launch.argv[0])
+    details["exec_resolved_binary"] = exec_binary
+    details["terminal_resolved_binary"] = terminal_binary
+
+    if sys.platform == "win32":
+        warnings.append("Native Windows support is currently experimental; WSL2 remains the most battle-tested path.")
+        if not exec_binary:
+            errors.append("DeepScientist could not resolve a Windows command shell for bash_exec.")
+            guidance.append("Install PowerShell (`pwsh`) or ensure `powershell.exe` is available on PATH.")
+        if not terminal_binary:
+            errors.append("DeepScientist could not resolve a Windows interactive shell backend.")
+            guidance.append("Ensure `powershell.exe` is available on PATH for the interactive terminal surface.")
+    return _make_check(
+        check_id="shell_backend",
+        label="Shell backend",
+        ok=len(errors) == 0,
+        summary="DeepScientist resolved platform shell backends for command and terminal sessions." if len(errors) == 0 else "DeepScientist could not resolve a required shell backend.",
+        warnings=warnings,
+        errors=errors,
+        guidance=guidance,
+        details=details,
+    )
+
+
 def _check_latex_runtime(home: Path) -> dict[str, Any]:
     runtime = RuntimeToolService(home).status("tinytex")
     pdflatex = runtime.get("binaries", {}).get("pdflatex") or {}
@@ -436,6 +486,7 @@ def run_doctor(home: Path, *, repo_root: Path) -> dict[str, Any]:
         _check_python_runtime(),
         _check_home_writable(home),
         _check_uv(home),
+        _check_shell_backend(),
         _check_git(config_manager),
         _check_config_validation(config_manager),
         _check_runner_support(config_manager),

package/src/deepscientist/file_lock.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+import os
+from pathlib import Path
+from typing import Iterator, TextIO
+
+if os.name == "nt":  # pragma: no cover - exercised on Windows
+    import msvcrt
+else:  # pragma: no cover - exercised on POSIX
+    import fcntl
+
+
+def _ensure_lockable_file(handle: TextIO) -> None:
+    handle.seek(0, os.SEEK_END)
+    if handle.tell() > 0:
+        handle.seek(0)
+        return
+    handle.write("\0")
+    handle.flush()
+    handle.seek(0)
+
+
+def _lock_handle(handle: TextIO) -> None:
+    if os.name == "nt":  # pragma: no cover - exercised on Windows
+        _ensure_lockable_file(handle)
+        msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
+        return
+    fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+
+
+def _unlock_handle(handle: TextIO) -> None:
+    if os.name == "nt":  # pragma: no cover - exercised on Windows
+        handle.seek(0)
+        msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+        return
+    fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+@contextmanager
+def advisory_file_lock(path: Path) -> Iterator[TextIO]:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a+", encoding="utf-8") as handle:
+        _lock_handle(handle)
+        try:
+            yield handle
+        finally:
+            _unlock_handle(handle)

package/src/deepscientist/gitops/diff.py

@@ -5,7 +5,7 @@ from pathlib import Path
 from typing import Any
 
 from ..artifact.metrics import extract_latest_metric
-from ..shared import read_json, run_command
+from ..shared import read_json, run_command, slugify
 from .service import branch_exists, current_branch, head_commit
 
 
@@ -68,6 +68,12 @@ def list_branch_canvas(repo: Path, *, quest_id: str) -> dict[str, Any]:
             "run_id": state.get("run_id"),
             "run_kind": state.get("run_kind"),
             "idea_id": state.get("idea_id"),
+            "paper_line_id": state.get("paper_line_id"),
+            "paper_line_branch": state.get("paper_line_branch"),
+            "selected_outline_ref": state.get("selected_outline_ref"),
+            "source_branch": state.get("source_branch"),
+            "source_run_id": state.get("source_run_id"),
+            "source_idea_id": state.get("source_idea_id"),
             "parent_branch_recorded": state.get("parent_branch"),
             "worktree_root": state.get("worktree_root"),
             "latest_metric": state.get("latest_metric"),
@@ -356,9 +362,158 @@ def _collect_branch_state(repo: Path) -> dict[str, dict[str, Any]]:
         for item in state.get("recent_artifacts", []):
             if isinstance(item, dict):
                 item.pop("_sort_key", None)
+    for workspace_root in _canvas_workspace_roots(repo):
+        state_path = workspace_root / "paper" / "paper_line_state.json"
+        if not state_path.exists():
+            continue
+        payload = read_json(state_path, {})
+        if not isinstance(payload, dict) or not payload:
+            continue
+        paper_branch = str(payload.get("paper_branch") or "").strip() or current_branch(workspace_root)
+        if not paper_branch:
+            continue
+        state = branch_state[paper_branch]
+        state.setdefault("branch", paper_branch)
+        state["worktree_root"] = str(workspace_root)
+        state["paper_line_id"] = str(payload.get("paper_line_id") or "").strip() or state.get("paper_line_id")
+        state["paper_line_branch"] = paper_branch
+        state["selected_outline_ref"] = str(payload.get("selected_outline_ref") or "").strip() or state.get("selected_outline_ref")
+        state["source_branch"] = str(payload.get("source_branch") or "").strip() or state.get("source_branch")
+        state["source_run_id"] = str(payload.get("source_run_id") or "").strip() or state.get("source_run_id")
+        state["source_idea_id"] = str(payload.get("source_idea_id") or "").strip() or state.get("source_idea_id")
+        state["updated_at"] = str(payload.get("updated_at") or state.get("updated_at") or "")
+        if not state.get("parent_branch") and state.get("source_branch"):
+            state["parent_branch"] = state.get("source_branch")
+    for workspace_root in _canvas_workspace_roots(repo):
+        paper_root = workspace_root / "paper"
+        if not paper_root.exists():
+            continue
+        state_path = paper_root / "paper_line_state.json"
+        if state_path.exists():
+            continue
+        selected_outline = read_json(paper_root / "selected_outline.json", {})
+        bundle_manifest = read_json(paper_root / "paper_bundle_manifest.json", {})
+        selected_outline = selected_outline if isinstance(selected_outline, dict) else {}
+        bundle_manifest = bundle_manifest if isinstance(bundle_manifest, dict) else {}
+        if not selected_outline and not bundle_manifest:
+            continue
+        paper_branch = str(bundle_manifest.get("paper_branch") or "").strip() or current_branch(workspace_root)
+        if not paper_branch:
+            continue
+        selected_outline_ref = str(
+            selected_outline.get("outline_id") or bundle_manifest.get("selected_outline_ref") or ""
+        ).strip() or None
+        source_run_id = str(bundle_manifest.get("source_run_id") or "").strip() or None
+        state = branch_state[paper_branch]
+        state.setdefault("branch", paper_branch)
+        state["worktree_root"] = str(workspace_root)
+        state["paper_line_id"] = state.get("paper_line_id") or slugify(
+            "::".join([paper_branch or "paper", selected_outline_ref or "outline", source_run_id or "run"]),
+            "paper-line",
+        )
+        state["paper_line_branch"] = paper_branch
+        state["selected_outline_ref"] = selected_outline_ref or state.get("selected_outline_ref")
+        state["source_branch"] = str(bundle_manifest.get("source_branch") or "").strip() or state.get("source_branch")
+        state["source_run_id"] = source_run_id or state.get("source_run_id")
+        state["source_idea_id"] = str(bundle_manifest.get("source_idea_id") or "").strip() or state.get("source_idea_id")
+        if not state.get("parent_branch") and state.get("source_branch"):
+            state["parent_branch"] = state.get("source_branch")
+    campaigns_root = repo / ".ds" / "analysis_campaigns"
+    if campaigns_root.exists():
+        for path in sorted(campaigns_root.glob("*.json")):
+            manifest = read_json(path, {})
+            if not isinstance(manifest, dict) or not manifest:
+                continue
+            campaign_id = str(manifest.get("campaign_id") or path.stem).strip() or path.stem
+            paper_line_id = str(manifest.get("paper_line_id") or "").strip() or None
+            paper_line_branch = str(manifest.get("paper_line_branch") or "").strip() or None
+            analysis_parent_branch = str(manifest.get("parent_branch") or "").strip() or None
+            selected_outline_ref = str(manifest.get("selected_outline_ref") or "").strip() or None
+            source_idea_id = str(manifest.get("active_idea_id") or "").strip() or None
+            if not paper_line_branch:
+                paper_line_branch = _infer_paper_line_branch_for_campaign(
+                    manifest,
+                    branch_state=branch_state,
+                )
+            for item in manifest.get("slices") or []:
+                if not isinstance(item, dict):
+                    continue
+                branch_name = str(item.get("branch") or "").strip()
+                if not branch_name:
+                    continue
+                state = branch_state[branch_name]
+                state.setdefault("branch", branch_name)
+                state["campaign_id"] = campaign_id
+                state["paper_line_id"] = paper_line_id or state.get("paper_line_id")
+                state["paper_line_branch"] = paper_line_branch or state.get("paper_line_branch")
+                state["analysis_parent_branch"] = analysis_parent_branch or state.get("analysis_parent_branch")
+                state["selected_outline_ref"] = selected_outline_ref or state.get("selected_outline_ref")
+                state["source_idea_id"] = source_idea_id or state.get("source_idea_id")
+                if item.get("worktree_root"):
+                    state["worktree_root"] = item.get("worktree_root")
     return branch_state
 
 
+def _canvas_workspace_roots(repo: Path) -> list[Path]:
+    roots: list[Path] = [repo]
+    research_state = read_json(repo / ".ds" / "research_state.json", {})
+    preferred_raw = str((research_state or {}).get("research_head_worktree_root") or "").strip()
+    if preferred_raw:
+        preferred = Path(preferred_raw)
+        if preferred.exists():
+            roots.append(preferred)
+    worktrees_root = repo / ".ds" / "worktrees"
+    if worktrees_root.exists():
+        roots.extend(path for path in sorted(worktrees_root.iterdir()) if path.is_dir())
+    deduped: list[Path] = []
+    seen: set[str] = set()
+    for root in roots:
+        key = str(root.resolve())
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(root)
+    return deduped
+
+
+def _infer_paper_line_branch_for_campaign(
+    manifest: dict[str, Any],
+    *,
+    branch_state: dict[str, dict[str, Any]],
+) -> str | None:
+    selected_outline_ref = str(manifest.get("selected_outline_ref") or "").strip() or None
+    source_idea_id = str(manifest.get("active_idea_id") or "").strip() or None
+    source_run_id = str(manifest.get("parent_run_id") or "").strip() or None
+    source_branch = str(manifest.get("parent_branch") or "").strip() or None
+    ranked: list[tuple[int, str]] = []
+    for branch_name, state in branch_state.items():
+        if not branch_name.startswith("paper/"):
+            continue
+        score = 0
+        candidate_outline = str(state.get("selected_outline_ref") or "").strip() or None
+        candidate_idea = str(state.get("source_idea_id") or "").strip() or None
+        candidate_run = str(state.get("source_run_id") or "").strip() or None
+        candidate_branch = str(state.get("source_branch") or "").strip() or None
+        if selected_outline_ref:
+            if candidate_outline != selected_outline_ref:
+                continue
+            score += 2
+        if source_idea_id and candidate_idea == source_idea_id:
+            score += 4
+        if source_run_id and candidate_run == source_run_id:
+            score += 3
+        if source_branch and candidate_branch == source_branch:
+            score += 2
+        if score > 0:
+            ranked.append((score, branch_name))
+    if not ranked:
+        return None
+    ranked.sort(key=lambda item: (item[0], item[1]), reverse=True)
+    if len(ranked) > 1 and ranked[0][0] == ranked[1][0]:
+        return None
+    return ranked[0][1]
+
+
 def _resolve_run_result_payload(repo: Path, record: dict[str, Any]) -> dict[str, Any]:
     details = dict(record.get("details") or {}) if isinstance(record.get("details"), dict) else {}
     paths = dict(record.get("paths") or {}) if isinstance(record.get("paths"), dict) else {}
@@ -469,9 +624,17 @@ def _infer_parent_ref(
 ) -> str | None:
     if ref == default_ref:
         return None
+    if classifications[ref]["branch_kind"] == "analysis":
+        paper_line_branch = str(state.get("paper_line_branch") or "").strip()
+        if paper_line_branch and paper_line_branch in refs and paper_line_branch != ref:
+            return paper_line_branch
     parent_branch = str(state.get("parent_branch") or "").strip()
     if parent_branch and parent_branch in refs and parent_branch != ref:
         return parent_branch
+    if classifications[ref]["branch_kind"] == "paper":
+        source_branch = str(state.get("source_branch") or "").strip()
+        if source_branch and source_branch in refs and source_branch != ref:
+            return source_branch
     if ref.startswith("idea/"):
         return default_ref
     if state.get("idea_id"):
@@ -479,6 +642,9 @@ def _infer_parent_ref(
         if candidate in refs:
             return candidate
     if classifications[ref]["branch_kind"] == "analysis":
+        analysis_parent_branch = str(state.get("analysis_parent_branch") or "").strip()
+        if analysis_parent_branch and analysis_parent_branch in refs and analysis_parent_branch != ref:
+            return analysis_parent_branch
         major_refs = [
             candidate
             for candidate, meta in classifications.items()

package/src/deepscientist/mcp/server.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import Any
 
 from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
 
 from ..artifact import ArtifactService
 from ..artifact.metrics import MetricContractValidationError
@@ -54,6 +55,16 @@ ARTIFACT_STATE_CHANGE_WATCHDOG_NOTES = {
 }
 
 
+def _read_only_tool_annotations(*, title: str | None = None) -> ToolAnnotations:
+    return ToolAnnotations(
+        title=title,
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+
+
 def _metric_validation_error_payload(exc: MetricContractValidationError) -> dict[str, Any]:
     return exc.as_payload()
 
@@ -62,7 +73,7 @@ def _progress_watchdog_note(tool_call_count: int) -> str:
     return (
         "By the way, you have gone "
         f"{tool_call_count} tool calls without notifying the user via artifact.interact(...). "
-        "Please report your latest progress now."
+        "Inspect whether the user-visible state actually changed; only send a progress update if there is a real new checkpoint, blocker, or route change."
     )
 
 
@@ -71,7 +82,7 @@ def _visibility_watchdog_note(seconds_since_last_update: int) -> str:
     return (
         "By the way, it has been "
         f"{minutes} minutes since the last user-visible artifact.interact(...). "
-        "Send one concise progress update now before continuing with background work."
+        "Inspect the current run or task state now. Only send a new user-visible update if the frontier materially changed or the user explicitly needs a fresh checkpoint."
     )
 
 
@@ -114,11 +125,16 @@ def _attach_interaction_watchdog(
     state_change_note: str | None = None,
 ) -> dict[str, Any]:
     enriched = dict(payload)
-    enriched["interaction_watchdog"] = dict(watchdog or {})
+    interaction_watchdog = dict(watchdog or {})
     notes = _collect_interaction_watchdog_notes(
         watchdog,
         state_change_note=state_change_note,
     )
+    interaction_watchdog["user_update_due"] = bool(
+        interaction_watchdog.get("user_update_due")
+        or any(str(item.get("kind") or "") == "state_change" for item in notes)
+    )
+    enriched["interaction_watchdog"] = interaction_watchdog
     if not notes:
         return enriched
     enriched["watchdog_notes"] = notes
@@ -377,6 +393,7 @@ def build_memory_server(context: McpContext) -> FastMCP:
             "Read a memory card by id or path. "
             "Use after list_recent or search surfaced a specific card worth reusing now."
         ),
+        annotations=_read_only_tool_annotations(title="Read memory card"),
     )
     def read(
         card_id: str | None = None,
@@ -394,6 +411,7 @@ def build_memory_server(context: McpContext) -> FastMCP:
             "Search memory cards by metadata or body text. "
             "Use before broad literature search, retries, route decisions, or repeated debugging."
         ),
+        annotations=_read_only_tool_annotations(title="Search memory cards"),
     )
     def search(
         query: str,
@@ -413,6 +431,7 @@ def build_memory_server(context: McpContext) -> FastMCP:
             "List the most recently updated memory cards. "
             "Use to recover quest context at turn start, after resume, or after a long pause."
         ),
+        annotations=_read_only_tool_annotations(title="List recent memory cards"),
     )
     def list_recent(
         scope: str = "quest",
@@ -557,19 +576,26 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         name="submit_idea",
         description=(
             "Create or revise the active research idea. "
-            "Normal research flow should use mode=create together with lineage_intent=continue_line or branch_alternative, so each durable idea submission becomes a new branch/worktree and a new user-visible research node. "
+            "Normal research flow should use mode=create together with submission_mode='line' and lineage_intent=continue_line or branch_alternative, so each durable idea submission becomes a new branch/worktree and a new user-visible research node. "
+            "submission_mode='candidate' records a candidate idea brief without opening a new branch yet. "
             "mode=revise is maintenance-only for refining the current active idea.md in place. "
             "When foundation_ref is omitted, lineage_intent infers the parent and default foundation from the active research line."
         ),
     )
     def submit_idea(
         mode: str = "create",
+        submission_mode: str = "line",
         idea_id: str | None = None,
         lineage_intent: str | None = None,
         title: str = "",
         problem: str = "",
         hypothesis: str = "",
         mechanism: str = "",
+        method_brief: str = "",
+        selection_scores: dict[str, Any] | None = None,
+        mechanism_family: str = "",
+        change_layer: str = "",
+        source_lens: str = "",
         expected_gain: str = "",
         evidence_paths: list[str] | None = None,
         risks: list[str] | None = None,
@@ -578,17 +604,24 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         foundation_reason: str = "",
         next_target: str = "experiment",
         draft_markdown: str = "",
+        source_candidate_id: str | None = None,
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         return service.submit_idea(
             context.require_quest_root(),
             mode=mode,
+            submission_mode=submission_mode,
             idea_id=idea_id,
             lineage_intent=lineage_intent,
             title=title,
             problem=problem,
             hypothesis=hypothesis,
             mechanism=mechanism,
+            method_brief=method_brief,
+            selection_scores=selection_scores,
+            mechanism_family=mechanism_family,
+            change_layer=change_layer,
+            source_lens=source_lens,
             expected_gain=expected_gain,
             evidence_paths=evidence_paths,
             risks=risks,
@@ -597,6 +630,7 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             foundation_reason=foundation_reason,
             next_target=next_target,
             draft_markdown=draft_markdown,
+            source_candidate_id=source_candidate_id,
         )
 
     @server.tool(
@@ -605,6 +639,7 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             "List research branches with branch number, active idea, foundation info, and corresponding main-experiment results. "
             "Use before creating the next idea when you need to compare possible foundations."
         ),
+        annotations=_read_only_tool_annotations(title="List research branches"),
     )
     def list_research_branches(comment: str | dict[str, Any] | None = None) -> dict[str, Any]:
         return service.list_research_branches(context.require_quest_root())
@@ -615,16 +650,135 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             "Resolve the current canonical research ids and refs. "
             "Use this before supplementary work when you need the active idea, latest main run, active campaign, outline, or reply-thread ids without guessing."
         ),
+        annotations=_read_only_tool_annotations(title="Resolve runtime refs"),
     )
     def resolve_runtime_refs(comment: str | dict[str, Any] | None = None) -> dict[str, Any]:
         return service.resolve_runtime_refs(context.require_quest_root())
 
+    @server.tool(
+        name="get_paper_contract_health",
+        description=(
+            "Inspect whether the active paper line is actually unblocked for writing or finalize work. "
+            "Use detail='summary' for a compact decision surface or detail='full' for exact blocking items."
+        ),
+        annotations=_read_only_tool_annotations(title="Get paper contract health"),
+    )
+    def get_paper_contract_health(
+        detail: str = "summary",
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.get_paper_contract_health(
+            context.require_quest_root(),
+            detail=detail,
+        )
+
+    @server.tool(
+        name="get_quest_state",
+        description=(
+            "Read the current quest runtime state without mutating anything. "
+            "Use detail='summary' for a compact operational view or detail='full' for recent artifacts, runs, and active interactions."
+        ),
+        annotations=_read_only_tool_annotations(title="Get quest state"),
+    )
+    def get_quest_state(
+        detail: str = "summary",
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.get_quest_state(
+            context.require_quest_root(),
+            detail=detail,
+        )
+
+    @server.tool(
+        name="get_global_status",
+        description=(
+            "Read a concise quest-global status summary for direct user questions such as overall progress, paper readiness, or the latest measured result. "
+            "Use detail='brief' for a compact answer surface or detail='full' for more structured context."
+        ),
+        annotations=_read_only_tool_annotations(title="Get global status"),
+    )
+    def get_global_status(
+        detail: str = "brief",
+        locale: str = "zh",
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.get_global_status(
+            context.require_quest_root(),
+            detail=detail,
+            locale=locale,
+        )
+
+    @server.tool(
+        name="get_method_scoreboard",
+        description=(
+            "Read or refresh the quest-level method scoreboard so overall experiment history and the current incumbent line are explicit."
+        ),
+    )
+    def get_method_scoreboard(comment: str | dict[str, Any] | None = None) -> dict[str, Any]:
+        return service.refresh_method_scoreboard(context.require_quest_root())
+
+    @server.tool(
+        name="get_optimization_frontier",
+        description=(
+            "Read a compact optimization-frontier summary for algorithm-first quests. "
+            "It summarizes candidate briefs, promoted lines, recent implementation candidates, stagnant branches, fusion opportunities, and the recommended next mode."
+        ),
+        annotations=_read_only_tool_annotations(title="Get optimization frontier"),
+    )
+    def get_optimization_frontier(
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.get_optimization_frontier(
+            context.require_quest_root(),
+        )
+
+    @server.tool(
+        name="read_quest_documents",
+        description=(
+            "Read durable quest documents such as brief, plan, status, summary, and active user requirements. "
+            "Use mode='excerpt' for compact recovery or mode='full' when exact document wording matters."
+        ),
+        annotations=_read_only_tool_annotations(title="Read quest documents"),
+    )
+    def read_quest_documents(
+        names: list[str] | None = None,
+        mode: str = "excerpt",
+        max_lines: int = 12,
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.read_quest_documents(
+            context.require_quest_root(),
+            names=names,
+            mode=mode,
+            max_lines=max_lines,
+        )
+
+    @server.tool(
+        name="get_conversation_context",
+        description=(
+            "Read a recent window of quest conversation history. "
+            "Use this when earlier user/assistant continuity matters and the current prompt intentionally keeps only a compact turn launcher."
+        ),
+        annotations=_read_only_tool_annotations(title="Get conversation context"),
+    )
+    def get_conversation_context(
+        limit: int = 12,
+        include_attachments: bool = False,
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.get_conversation_context(
+            context.require_quest_root(),
+            limit=limit,
+            include_attachments=include_attachments,
+        )
+
     @server.tool(
         name="get_analysis_campaign",
         description=(
             "Get one analysis campaign manifest with todo items, slice status, and next pending slice. "
             "Pass campaign_id='active' or omit it to recover the active campaign."
         ),
+        annotations=_read_only_tool_annotations(title="Get analysis campaign"),
     )
     def get_analysis_campaign(
         campaign_id: str | None = "active",
@@ -762,6 +916,7 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             "List candidate/revised paper outlines and the selected outline reference. "
             "Use this before writing-facing analysis campaigns or when you need a valid outline_id."
         ),
+        annotations=_read_only_tool_annotations(title="List paper outlines"),
     )
     def list_paper_outlines(comment: str | dict[str, Any] | None = None) -> dict[str, Any]:
         return service.list_paper_outlines(context.require_quest_root())
@@ -957,7 +1112,14 @@ def build_artifact_server(context: McpContext) -> FastMCP:
     def render_git_graph(comment: str | dict[str, Any] | None = None) -> dict[str, Any]:
         return service.render_git_graph(context.require_quest_root())
 
-    @server.tool(name="interact", description="Send a structured user-facing update and optionally fetch new inbound messages.")
+    @server.tool(
+        name="interact",
+        description=(
+            "Send a structured user-facing interaction and optionally fetch new inbound messages. "
+            "Use kind='answer' for direct user questions, kind='progress' for long-running checkpoint updates, "
+            "kind='milestone' for material state changes, and kind='decision_request' only for true blocking decisions."
+        ),
+    )
     def interact(
         kind: str = "progress",
         message: str = "",
@@ -977,6 +1139,9 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         reply_schema: dict[str, Any] | None = None,
         reply_to_interaction_id: str | None = None,
         supersede_open_requests: bool = True,
+        dedupe_key: str | None = None,
+        suppress_if_unchanged: bool | None = None,
+        min_interval_seconds: int | None = None,
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         result = service.interact(
@@ -999,6 +1164,9 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             reply_schema=reply_schema,
             reply_to_interaction_id=reply_to_interaction_id,
             supersede_open_requests=supersede_open_requests,
+            dedupe_key=dedupe_key,
+            suppress_if_unchanged=suppress_if_unchanged,
+            min_interval_seconds=min_interval_seconds,
         )
         result["interaction_watchdog"] = quest_service.artifact_interaction_watchdog_status(context.require_quest_root())
         return result