@researai/deepscientist 1.5.16 → 1.6.0

package/src/deepscientist/mcp/server.py

@@ -2,8 +2,13 @@ from __future__ import annotations
 
 import argparse
 from collections import deque
+import json
 from pathlib import Path
+import shlex
+import sys
 from typing import Any
+from urllib import error as urllib_error
+from urllib import request as urllib_request
 
 from mcp.server.fastmcp import FastMCP
 from mcp.types import ToolAnnotations
@@ -11,21 +16,183 @@ from mcp.types import ToolAnnotations
 from ..artifact import ArtifactService
 from ..artifact.metrics import MetricContractValidationError
 from ..bash_exec import BashExecService
+from ..evidence_packets import cached_compact_mcp_tool_result, compact_mcp_tool_result
 from ..memory import MemoryService
 from ..quest import QuestService
+from ..shared import read_json
 from .context import McpContext
+from .schemas import MetricContractPayload, PrimaryMetricPayload, SupplementaryBaselinePayload
 
 DEFAULT_INLINE_BASH_LOG_LINE_LIMIT = 2000
 DEFAULT_INLINE_BASH_LOG_HEAD_LINES = 500
 DEFAULT_INLINE_BASH_LOG_TAIL_LINES = 1500
 DEFAULT_INLINE_BASH_LOG_WINDOW_LINES = 200
 MAX_INLINE_BASH_LOG_WINDOW_LINES = 2000
+DEFAULT_BASH_EXEC_AWAIT_WAIT_TIMEOUT_SECONDS = 1800
+BASH_EXEC_TERMINAL_STATUSES = {"completed", "failed", "terminated"}
 INTERACTION_WATCHDOG_TOOL_CALL_THRESHOLD = 25
 INTERACTION_WATCHDOG_SILENCE_THRESHOLD_SECONDS = 30 * 60
 LONG_BASH_LOG_HINT = (
     "Use `bash_exec(mode='read', id=..., start=..., tail=...)` to inspect a specific log window, "
     "or `bash_exec(mode='read', id=..., tail=...)` to inspect the latest rendered lines."
 )
+
+
+def _attach_bash_log_truncation_metadata(payload: dict[str, Any]) -> dict[str, Any]:
+    result = dict(payload)
+
+    log_line_count = result.get("log_line_count")
+    latest_seq = result.get("latest_seq")
+    tail_start_seq = result.get("tail_start_seq")
+    line_start = result.get("line_start")
+    line_end = result.get("line_end")
+
+    def _as_int(value: object) -> int | None:
+        if isinstance(value, bool):
+            return None
+        if isinstance(value, int):
+            return value
+        try:
+            return int(str(value))
+        except (TypeError, ValueError):
+            return None
+
+    total_lines = _as_int(log_line_count) or 0
+    latest_seq_value = _as_int(latest_seq)
+    tail_start_seq_value = _as_int(tail_start_seq)
+    line_start_value = _as_int(line_start)
+    line_end_value = _as_int(line_end)
+
+    if result.get("log_truncated") is True:
+        head_lines = _as_int(result.get("log_preview_head_lines")) or 0
+        tail_lines = _as_int(result.get("log_preview_tail_lines")) or 0
+        omitted_lines = _as_int(result.get("log_preview_omitted_lines")) or max(total_lines - head_lines - tail_lines, 0)
+        after_preview_lines = tail_lines
+        before_preview_lines = head_lines
+        result["log_is_partial"] = True
+        result["log_visible_line_start"] = 1 if total_lines else 0
+        result["log_visible_line_end"] = total_lines if total_lines and total_lines <= head_lines + tail_lines else head_lines + tail_lines
+        result["log_lines_before_window"] = 0
+        result["log_lines_after_window"] = max(total_lines - tail_lines, 0) if total_lines else 0
+        result["seq_has_more_before"] = False
+        result["seq_has_more_after"] = omitted_lines > 0
+        result["seqs_before_window"] = 0
+        result["seqs_after_window"] = omitted_lines
+        result["log_truncation_notice"] = (
+            "This log payload is truncated to a preview window rather than the full output. "
+            f"It shows the first {head_lines} line(s) and the last {tail_lines} line(s), omitting {omitted_lines} middle line(s). "
+            "Do not treat this preview as exhaustive evidence. "
+            "Use bash_exec(mode='read', id=..., start=..., tail=...) for a specific line window, "
+            "or bash_exec(mode='read', id=..., tail_limit=..., before_seq=..., after_seq=...) for seq-based continuation."
+        )
+        return result
+
+    if result.get("log_windowed") is True:
+        if line_start_value is None:
+            line_start_value = 1 if total_lines else 0
+        if line_end_value is None:
+            line_end_value = line_start_value - 1 if line_start_value else 0
+        lines_before = max((line_start_value - 1) if line_start_value else 0, 0)
+        lines_after = max(total_lines - max(line_end_value or 0, 0), 0)
+        result["log_is_partial"] = bool(result.get("has_more_before")) or bool(result.get("has_more_after"))
+        result["log_lines_before_window"] = lines_before
+        result["log_lines_after_window"] = lines_after
+        result["log_visible_line_start"] = line_start_value
+        result["log_visible_line_end"] = line_end_value
+
+        if tail_start_seq_value is not None:
+            seq_window_start = tail_start_seq_value
+            seq_window_end = (
+                tail_start_seq_value + (_as_int(result.get("returned_line_count")) or 0) - 1
+                if (_as_int(result.get("returned_line_count")) or 0) > 0
+                else tail_start_seq_value - 1
+            )
+        else:
+            seq_window_start = line_start_value
+            seq_window_end = line_end_value
+        seqs_before = max((seq_window_start or 0) - 1, 0)
+        seqs_after = (
+            max(latest_seq_value - max(seq_window_end or 0, 0), 0)
+            if latest_seq_value is not None
+            else lines_after
+        )
+        result["seq_window_start"] = seq_window_start
+        result["seq_window_end"] = seq_window_end
+        result["seq_has_more_before"] = seqs_before > 0
+        result["seq_has_more_after"] = seqs_after > 0
+        result["seqs_before_window"] = seqs_before
+        result["seqs_after_window"] = seqs_after
+
+        if result["log_is_partial"]:
+            result["log_truncation_notice"] = (
+                "This log payload is only a partial window, not the full output. "
+                f"It currently covers lines {line_start_value} to {line_end_value} out of {total_lines}, "
+                f"with {lines_before} line(s) before and {lines_after} line(s) after this window. "
+                "If you need adjacent output, continue with bash_exec(mode='read', id=..., start=..., tail=...) "
+                "or use the seq-based before_seq / after_seq parameters."
+            )
+        return result
+
+    if total_lines > 0:
+        result["log_is_partial"] = False
+        result["log_lines_before_window"] = 0
+        result["log_lines_after_window"] = 0
+        if latest_seq_value is not None:
+            result["seq_has_more_before"] = False
+            result["seq_has_more_after"] = False
+            result["seqs_before_window"] = 0
+            result["seqs_after_window"] = 0
+            result["seq_window_start"] = 1
+            result["seq_window_end"] = latest_seq_value
+    return result
+
+
+def _normalize_positive_timeout_seconds(value: Any, *, field_name: str) -> int | None:
+    if value is None or value == "":
+        return None
+    if isinstance(value, bool):
+        raise ValueError(f"{field_name} must be a positive integer.")
+    try:
+        normalized = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{field_name} must be a positive integer.") from exc
+    if normalized <= 0:
+        raise ValueError(f"{field_name} must be a positive integer.")
+    return normalized
+
+
+def _build_bash_exec_wait_notice(
+    *,
+    bash_id: str,
+    wait_timeout_seconds: int,
+    status: str,
+) -> dict[str, Any]:
+    suggested_poll_interval_seconds = DEFAULT_BASH_EXEC_AWAIT_WAIT_TIMEOUT_SECONDS
+    suggested_sleep_timeout = suggested_poll_interval_seconds + 60
+    return {
+        "wait_timed_out": True,
+        "still_running": status in {"running", "terminating"},
+        "wait_timeout_seconds": wait_timeout_seconds,
+        "suggested_poll_interval_seconds": suggested_poll_interval_seconds,
+        "suggested_read_command": f"bash_exec(mode='read', id='{bash_id}')",
+        "suggested_await_command": (
+            f"bash_exec(mode='await', id='{bash_id}', "
+            f"wait_timeout_seconds={suggested_poll_interval_seconds})"
+        ),
+        "suggested_sleep_command": (
+            f"bash_exec(command='sleep {suggested_poll_interval_seconds}', mode='await', "
+            f"timeout_seconds={suggested_sleep_timeout})"
+        ),
+        "long_wait_notice": (
+            "This managed bash_exec session is still running, so the bounded await window ended without final completion. "
+            f"Read the saved log with bash_exec(mode='read', id='{bash_id}') and check again in about "
+            f"{suggested_poll_interval_seconds} seconds. Prefer "
+            f"bash_exec(mode='await', id='{bash_id}', wait_timeout_seconds={suggested_poll_interval_seconds}) "
+            "for the next bounded wait on this managed session; if you only need wall-clock waiting between checks, "
+            f"you may use bash_exec(command='sleep {suggested_poll_interval_seconds}', mode='await', "
+            f"timeout_seconds={suggested_sleep_timeout}) before reading the log again."
+        ),
+    }
 ARTIFACT_STATE_CHANGE_WATCHDOG_NOTES = {
     "confirm_baseline": (
         "Baseline confirmation changed durable quest state and this tool does not send a user-visible "
@@ -39,6 +206,10 @@ ARTIFACT_STATE_CHANGE_WATCHDOG_NOTES = {
         "Paper outline state changed durably and this tool does not send a user-visible summary on its own. "
         "Send one concise artifact.interact(...) update now."
     ),
+    "compile_outline_to_writing_plan": (
+        "Paper writing plan state changed durably and this tool does not send a user-visible summary on its own. "
+        "Send one concise artifact.interact(...) update now."
+    ),
     "publish_baseline": (
         "Baseline publication changed durable state and this tool does not send a user-visible summary "
         "on its own. Send one concise artifact.interact(...) update now."
@@ -53,6 +224,85 @@ ARTIFACT_STATE_CHANGE_WATCHDOG_NOTES = {
         "received an equivalent completion summary."
     ),
 }
+START_SETUP_FORM_FIELDS: tuple[str, ...] = (
+    "title",
+    "goal",
+    "baseline_id",
+    "baseline_variant_id",
+    "baseline_source_mode",
+    "execution_start_mode",
+    "baseline_acceptance_target",
+    "baseline_urls",
+    "paper_urls",
+    "runtime_constraints",
+    "objectives",
+    "need_research_paper",
+    "research_intensity",
+    "decision_policy",
+    "launch_mode",
+    "standard_profile",
+    "custom_profile",
+    "review_followup_policy",
+    "baseline_execution_policy",
+    "manuscript_edit_mode",
+    "entry_state_summary",
+    "review_summary",
+    "review_materials",
+    "custom_brief",
+    "user_language",
+)
+START_SETUP_SESSION_FIELDS: tuple[str, ...] = (
+    "fit_assessment",
+    "recommended_workspace_mode",
+    "launch_readiness",
+    "missing_confirmations",
+    "preview_plan",
+    "materials_summary",
+    "copilot_handoff",
+    "science_task",
+    "science_task_brief",
+    "science_package_cards",
+)
+
+
+def _split_nested_start_setup_payload(payload: dict[str, Any] | None) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    if not isinstance(payload, dict):
+        return None, None
+    form_patch = payload.get("form_patch") if isinstance(payload.get("form_patch"), dict) else None
+    session_patch = payload.get("session_patch") if isinstance(payload.get("session_patch"), dict) else None
+    suggested_form = payload.get("suggested_form") if isinstance(payload.get("suggested_form"), dict) else None
+    if isinstance(suggested_form, dict):
+        if form_patch is None and isinstance(suggested_form.get("form_patch"), dict):
+            form_patch = suggested_form.get("form_patch")
+        if session_patch is None and isinstance(suggested_form.get("session_patch"), dict):
+            session_patch = suggested_form.get("session_patch")
+    return form_patch, session_patch
+
+
+def _normalize_bash_exec_command_input(raw_command: Any) -> str:
+    if isinstance(raw_command, str):
+        return raw_command
+    if isinstance(raw_command, (list, tuple)):
+        items = [str(item).strip() for item in raw_command if str(item).strip()]
+        if not items:
+            return ""
+        if len(items) == 1:
+            return items[0]
+        return shlex.join(items)
+    return str(raw_command or "")
+
+
+def _normalize_bash_exec_command_input(raw_command: Any) -> str:
+    if isinstance(raw_command, str):
+        return raw_command
+    if isinstance(raw_command, (list, tuple)):
+        items = [str(item).strip() for item in raw_command if str(item).strip()]
+        if not items:
+            return ""
+        if len(items) == 1:
+            return items[0]
+        return shlex.join(items)
+    return str(raw_command or "")
 
 
 def _read_only_tool_annotations(*, title: str | None = None) -> ToolAnnotations:
@@ -69,6 +319,158 @@ def _metric_validation_error_payload(exc: MetricContractValidationError) -> dict
     return exc.as_payload()
 
 
+def _artifact_call(name: str, why: str) -> dict[str, str]:
+    return {"name": name, "why": why}
+
+
+def _artifact_guided_error_payload(
+    service: ArtifactService,
+    quest_root: Path,
+    *,
+    tool_name: str,
+    exc: Exception,
+) -> dict[str, Any]:
+    message = str(exc).strip() or f"`artifact.{tool_name}` failed."
+    guidance: list[str] = []
+    suggested_artifact_calls: list[dict[str, str]] = []
+    extra: dict[str, Any] = {}
+
+    if "selected_outline_ref" in message or "No selected outline is available" in message:
+        outlines = service.list_paper_outlines(quest_root)
+        outline_items = [dict(item) for item in (outlines.get("outlines") or []) if isinstance(item, dict)]
+        candidate_ids = [
+            str(item.get("outline_id") or "").strip()
+            for item in outline_items
+            if str(item.get("status") or "").strip() in {"candidate", "revised"}
+            and str(item.get("outline_id") or "").strip()
+        ]
+        extra["outline_candidates"] = outline_items
+        if candidate_ids:
+            guidance.append(f"Select a candidate outline first. Available candidates: {', '.join(candidate_ids[:5])}.")
+            guidance.append(
+                "Use `artifact.submit_paper_outline(mode='select', outline_id='...', selected_reason='...')` "
+                "to promote one of those candidates before retrying the writing-facing campaign."
+            )
+            suggested_artifact_calls.append(
+                _artifact_call(
+                    "artifact.submit_paper_outline(mode='select', outline_id='...', selected_reason='...')",
+                    "Promote one candidate outline into the active paper line.",
+                )
+            )
+        else:
+            guidance.append("Create a candidate outline first, then select it before launching a writing-facing analysis campaign.")
+            suggested_artifact_calls.append(
+                _artifact_call(
+                    "artifact.submit_paper_outline(mode='candidate', ...)",
+                    "Create the first paper outline candidate for this quest.",
+                )
+            )
+        guidance.append(
+            "If the work is only exploratory evidence and not yet bound to the paper contract, downgrade it to a pre-outline analysis-lite / non-writing-facing campaign instead."
+        )
+        suggested_artifact_calls.append(
+            _artifact_call(
+                "artifact.create_analysis_campaign(...)",
+                "Retry only after the selected outline and paper-facing fields are explicit, or simplify the campaign so it is no longer writing-facing.",
+            )
+        )
+    elif "research_questions" in message:
+        guidance.append("Provide non-empty research_questions before launching a writing-facing analysis campaign.")
+        guidance.append("The cleanest fix is to revise the selected outline so the paper contract and campaign input agree.")
+        suggested_artifact_calls.extend(
+            [
+                _artifact_call(
+                    "artifact.submit_paper_outline(mode='revise', ...)",
+                    "Add research_questions to the selected outline.",
+                ),
+                _artifact_call(
+                    "artifact.create_analysis_campaign(..., research_questions=[...], experimental_designs=[...], todo_items=[...])",
+                    "Retry the campaign with explicit writing-facing fields.",
+                ),
+            ]
+        )
+    elif "experimental_designs" in message:
+        guidance.append("Provide non-empty experimental_designs before launching a writing-facing analysis campaign.")
+        guidance.append("If the paper contract is still thin, revise the selected outline before retrying.")
+        suggested_artifact_calls.extend(
+            [
+                _artifact_call(
+                    "artifact.submit_paper_outline(mode='revise', ...)",
+                    "Add experimental_designs to the selected outline.",
+                ),
+                _artifact_call(
+                    "artifact.create_analysis_campaign(..., experimental_designs=[...])",
+                    "Retry the campaign with explicit experimental designs.",
+                ),
+            ]
+        )
+    elif "todo_items" in message or "outline-bound paper contract fields" in message:
+        guidance.append("Every writing-facing analysis slice needs a todo item with section_id, item_id, paper_role, and claim_links.")
+        guidance.append("Do not launch a paper-facing campaign until every slice is mapped back into the outline contract.")
+        suggested_artifact_calls.append(
+            _artifact_call(
+                "artifact.create_analysis_campaign(..., todo_items=[...])",
+                "Retry with one outline-bound todo item per slice.",
+            )
+        )
+    elif "confirmed or waived baseline gate" in message:
+        guidance.append("Open the baseline gate first, or explicitly waive it if skipping is justified.")
+        suggested_artifact_calls.extend(
+            [
+                _artifact_call("artifact.confirm_baseline(...)", "Confirm the active baseline and metric contract."),
+                _artifact_call("artifact.waive_baseline(...)", "Record an explicit waiver if baseline work should be skipped."),
+            ]
+        )
+    elif "An active idea is required before starting an analysis campaign." in message:
+        guidance.append("Create or activate an idea before launching an analysis campaign.")
+        suggested_artifact_calls.extend(
+            [
+                _artifact_call("artifact.submit_idea(...)", "Create the next durable idea route first."),
+                _artifact_call("artifact.activate_branch(...)", "Switch back to the branch that owns the accepted idea line."),
+            ]
+        )
+    elif "baseline_path" in message:
+        guidance.append("Use a quest-local baseline path under `baselines/local/...` or `baselines/imported/...`.")
+        guidance.append("If the baseline lives outside the quest, materialize or attach it first instead of passing an external path directly.")
+        suggested_artifact_calls.extend(
+            [
+                _artifact_call("artifact.attach_baseline(...)", "Attach a reusable baseline package when one already exists."),
+                _artifact_call("artifact.confirm_baseline(...)", "Confirm the quest-local baseline after it is materialized."),
+            ]
+        )
+    elif "imported baseline" in message or "protocol-breaking" in message:
+        guidance.append("Do not overwrite the accepted baseline in place when comparability changed materially.")
+        guidance.append("Use a new baseline id or a new variant when the path, protocol, or comparator meaning changed.")
+        suggested_artifact_calls.extend(
+            [
+                _artifact_call("artifact.confirm_baseline(...)", "Confirm the new baseline or variant as a separate comparator."),
+                _artifact_call("artifact.overwrite_baseline(...)", "Use overwrite only when the baseline is still the same accepted comparator."),
+            ]
+        )
+    elif "submit_paper_bundle requires a selected outline" in message:
+        guidance.append("Select an outline before bundling the paper package.")
+        suggested_artifact_calls.append(
+            _artifact_call(
+                "artifact.submit_paper_outline(mode='select', outline_id='...', selected_reason='...')",
+                "Select the active outline before generating the final paper bundle.",
+            )
+        )
+    else:
+        guidance.append("Inspect the current quest state and the tool-specific required fields before retrying.")
+        suggested_artifact_calls.append(
+            _artifact_call("artifact.get_quest_state(detail='full')", "Read the current durable quest state before retrying the tool.")
+        )
+
+    return {
+        "ok": False,
+        "tool_name": f"artifact.{tool_name}",
+        "message": message,
+        "guidance": guidance,
+        "suggested_artifact_calls": suggested_artifact_calls,
+        **extra,
+    }
+
+
 def _progress_watchdog_note(tool_call_count: int) -> str:
     return (
         "By the way, you have gone "
@@ -152,6 +554,180 @@ def _attach_interaction_watchdog(
     return enriched
 
 
+def _local_daemon_api_base_url(home: Path) -> tuple[str | None, dict[str, Any]]:
+    state = read_json(home / "runtime" / "daemon.json", {})
+    if not isinstance(state, dict):
+        return None, {}
+    for key in ("url", "bind_url"):
+        value = str(state.get(key) or "").strip()
+        if value:
+            return value.rstrip("/"), state
+    return None, state
+
+
+def _issue_draft_route_effect(payload: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "name": "route:navigate",
+        "data": {
+            "to": "/settings/issues",
+            "issueDraft": {
+                "ok": True,
+                "title": str(payload.get("title") or "").strip(),
+                "body_markdown": str(payload.get("body_markdown") or "").strip(),
+                "issue_url_base": str(payload.get("issue_url_base") or "").strip(),
+                "repo_url": str(payload.get("repo_url") or "").strip(),
+                "generated_at": payload.get("generated_at"),
+            },
+        },
+    }
+
+
+def _coerce_prepare_bool(value: Any, *, field_name: str) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"true", "1", "yes", "on"}:
+            return True
+        if normalized in {"false", "0", "no", "off"}:
+            return False
+    raise ValueError(f"`{field_name}` must be a boolean.")
+
+
+def _sanitize_start_setup_form_patch(form_patch: dict[str, Any] | None) -> dict[str, Any]:
+    if form_patch is None:
+        return {}
+    if not isinstance(form_patch, dict):
+        raise ValueError("`form_patch` must be an object.")
+    patch: dict[str, Any] = {}
+    for key in START_SETUP_FORM_FIELDS:
+        if key not in form_patch:
+            continue
+        value = form_patch.get(key)
+        if value is None:
+            continue
+        if key == "need_research_paper":
+            patch[key] = _coerce_prepare_bool(value, field_name=key)
+            continue
+        if isinstance(value, (str, int, float, bool)):
+            patch[key] = str(value).strip() if not isinstance(value, bool) else value
+            continue
+        raise ValueError(f"`form_patch.{key}` must be a string or boolean.")
+    return patch
+
+
+def _sanitize_start_setup_session_patch(session_patch: dict[str, Any] | None) -> dict[str, Any]:
+    if session_patch is None:
+        return {}
+    if not isinstance(session_patch, dict):
+        raise ValueError("`session_patch` must be an object.")
+    patch: dict[str, Any] = {}
+    for key in START_SETUP_SESSION_FIELDS:
+        if key not in session_patch:
+            continue
+        value = session_patch.get(key)
+        if value is None:
+            continue
+        if key in {"recommended_workspace_mode", "launch_readiness"}:
+            patch[key] = str(value).strip()
+            continue
+        if key == "missing_confirmations":
+            if not isinstance(value, list):
+                raise ValueError("`session_patch.missing_confirmations` must be an array of strings.")
+            patch[key] = [str(item).strip() for item in value if str(item).strip()]
+            continue
+        if key == "science_package_cards":
+            if not isinstance(value, list):
+                raise ValueError("`session_patch.science_package_cards` must be an array of strings.")
+            patch[key] = [str(item).strip() for item in value if str(item).strip()]
+            continue
+        if key in {"fit_assessment", "preview_plan", "copilot_handoff", "science_task", "science_task_brief"}:
+            if not isinstance(value, dict):
+                raise ValueError(f"`session_patch.{key}` must be an object.")
+            patch[key] = json.loads(json.dumps(value, ensure_ascii=False))
+            continue
+        if key == "materials_summary":
+            if not isinstance(value, list):
+                raise ValueError("`session_patch.materials_summary` must be an array.")
+            patch[key] = [dict(item) for item in value if isinstance(item, dict)]
+            continue
+    return patch
+
+
+def _start_setup_patch_effect(
+    form_patch: dict[str, Any],
+    *,
+    session_patch: dict[str, Any] | None = None,
+    message: str | None = None,
+) -> dict[str, Any]:
+    return {
+        "name": "start_setup:patch",
+        "data": {
+            "patch": dict(form_patch),
+            "session_patch": dict(session_patch or {}),
+            "message": str(message or "").strip() or None,
+        },
+    }
+
+
+def _prepare_github_issue_payload_via_daemon(
+    home: Path,
+    *,
+    summary: str | None = None,
+    user_notes: str | None = None,
+    include_doctor: bool = True,
+    include_logs: bool = True,
+    include_system_quirks: bool = False,
+) -> dict[str, Any]:
+    base_url, daemon_state = _local_daemon_api_base_url(home)
+    if not base_url:
+        raise ValueError("The local daemon URL is unavailable. Start DeepScientist before preparing a GitHub issue draft.")
+
+    token = str((daemon_state or {}).get("auth_token") or "").strip()
+    auth_enabled = bool((daemon_state or {}).get("auth_enabled"))
+    if auth_enabled and not token:
+        raise ValueError("Browser auth is enabled for the local daemon, but no auth token was found in runtime/daemon.json.")
+
+    body = {
+        "summary": str(summary or "").strip() or None,
+        "user_notes": str(user_notes or "").strip() or None,
+        "include_doctor": bool(include_doctor),
+        "include_logs": bool(include_logs),
+        "include_system_quirks": bool(include_system_quirks),
+    }
+    headers = {
+        "Content-Type": "application/json",
+    }
+    if auth_enabled and token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    request = urllib_request.Request(
+        f"{base_url}/api/system/issues/draft",
+        data=json.dumps(body).encode("utf-8"),
+        headers=headers,
+        method="POST",
+    )
+    try:
+        with urllib_request.urlopen(request, timeout=15) as response:
+            raw = response.read().decode("utf-8", errors="replace")
+    except urllib_error.HTTPError as exc:  # pragma: no cover - exercised via unit monkeypatching
+        detail = exc.read().decode("utf-8", errors="replace").strip()
+        message = detail or getattr(exc, "reason", "") or "request failed"
+        raise ValueError(f"Local daemon issue draft request failed with HTTP {exc.code}: {message}") from exc
+    except OSError as exc:
+        raise ValueError(f"Unable to reach the local daemon at `{base_url}`: {exc}") from exc
+
+    try:
+        payload = json.loads(raw or "{}")
+    except json.JSONDecodeError as exc:
+        raise ValueError("The local daemon returned an invalid issue draft payload.") from exc
+    if not isinstance(payload, dict):
+        raise ValueError("The local daemon returned a non-object issue draft payload.")
+    if payload.get("ok") is False:
+        raise ValueError(str(payload.get("message") or "The local daemon rejected the issue draft request."))
+    return payload
+
+
 def _split_bash_log_lines(log_text: str) -> list[str]:
     return log_text.splitlines()
 
@@ -421,8 +997,31 @@ def build_memory_server(context: McpContext) -> FastMCP:
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         resolved_scope = _resolve_search_scope(context, scope)
-        quest_root = context.quest_root if resolved_scope in {"quest", "both"} else None
-        items = service.search(query, scope=resolved_scope, quest_root=quest_root, limit=limit, kind=kind)
+        if resolved_scope == "quest" and context.quest_root is not None and service.shared_read_enabled():
+            items = service.search_visible_quest_cards(
+                query,
+                active_quest_root=context.quest_root,
+                active_quest_id=context.quest_id,
+                limit=limit,
+                kind=kind,
+                include_shared=True,
+            )
+        elif resolved_scope == "both" and context.quest_root is not None:
+            quest_items = service.search_visible_quest_cards(
+                query,
+                active_quest_root=context.quest_root,
+                active_quest_id=context.quest_id,
+                limit=limit,
+                kind=kind,
+                include_shared=service.shared_read_enabled(),
+            )
+            global_items = service.search(query, scope="global", limit=limit, kind=kind)
+            items = quest_items + global_items
+            items.sort(key=lambda item: service._visible_card_sort_key(item, active_quest_id=context.quest_id))
+            items = items[:limit]
+        else:
+            quest_root = context.quest_root if resolved_scope in {"quest", "both"} else None
+            items = service.search(query, scope=resolved_scope, quest_root=quest_root, limit=limit, kind=kind)
         return {"ok": True, "count": len(items), "items": items}
 
     @server.tool(
@@ -440,10 +1039,30 @@ def build_memory_server(context: McpContext) -> FastMCP:
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         resolved_scope = _resolve_search_scope(context, scope)
-        if resolved_scope == "both":
-            quest_items = service.list_recent(scope="quest", quest_root=context.require_quest_root(), limit=limit, kind=kind)
+        if resolved_scope == "quest" and context.quest_root is not None and service.shared_read_enabled():
+            items = service.list_visible_quest_cards(
+                active_quest_root=context.quest_root,
+                active_quest_id=context.quest_id,
+                limit=limit,
+                kind=kind,
+                include_shared=True,
+            )
+        elif resolved_scope == "both":
+            quest_items = (
+                service.list_visible_quest_cards(
+                    active_quest_root=context.require_quest_root(),
+                    active_quest_id=context.quest_id,
+                    limit=limit,
+                    kind=kind,
+                    include_shared=service.shared_read_enabled(),
+                )
+                if context.quest_root is not None
+                else []
+            )
             global_items = service.list_recent(scope="global", limit=limit, kind=kind)
-            items = (quest_items + global_items)[-limit:]
+            items = quest_items + global_items
+            items.sort(key=lambda item: service._visible_card_sort_key(item, active_quest_id=context.quest_id))
+            items = items[:limit]
         else:
             quest_root = context.quest_root if resolved_scope == "quest" else None
             items = service.list_recent(scope=resolved_scope, quest_root=quest_root, limit=limit, kind=kind)
@@ -469,6 +1088,9 @@ def build_memory_server(context: McpContext) -> FastMCP:
 def build_artifact_server(context: McpContext) -> FastMCP:
     service = ArtifactService(context.home)
     quest_service = service.quest_service
+    custom_profile = str(context.custom_profile or "").strip().lower()
+    issue_only_profile = custom_profile == "settings_issue"
+    start_setup_prepare_profile = custom_profile == "start_setup_prepare"
     server = FastMCP(
         "artifact",
         instructions=(
@@ -479,7 +1101,12 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         log_level="ERROR",
     )
 
-    def finalize_state_changing_artifact_tool(payload: dict[str, Any], *, tool_name: str) -> dict[str, Any]:
+    def finalize_artifact_tool(
+        payload: dict[str, Any],
+        *,
+        tool_name: str,
+        state_change_note: str | None = None,
+    ) -> dict[str, Any]:
         quest_root = context.require_quest_root().resolve()
         quest_service.record_tool_activity(
             quest_root,
@@ -489,9 +1116,188 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         return _attach_interaction_watchdog(
             payload,
             watchdog,
+            state_change_note=state_change_note,
+        )
+
+    def finalize_state_changing_artifact_tool(payload: dict[str, Any], *, tool_name: str) -> dict[str, Any]:
+        return finalize_artifact_tool(
+            payload,
+            tool_name=tool_name,
             state_change_note=ARTIFACT_STATE_CHANGE_WATCHDOG_NOTES.get(tool_name),
         )
 
+    def _quest_relative_path(value: Any) -> str | None:
+        text = str(value or "").strip()
+        if not text:
+            return None
+        path = Path(text)
+        if not path.is_absolute():
+            return text
+        quest_root = context.require_quest_root().resolve()
+        try:
+            active_workspace_root = quest_service.active_workspace_root(quest_root)
+        except Exception:
+            active_workspace_root = None
+        roots = [context.worktree_root, active_workspace_root, context.quest_root]
+        seen: set[str] = set()
+        for raw_root in roots:
+            if raw_root is None:
+                continue
+            root = raw_root.resolve()
+            key = str(root)
+            if key in seen:
+                continue
+            seen.add(key)
+            try:
+                return path.resolve().relative_to(root).as_posix()
+            except ValueError:
+                continue
+        try:
+            return path.resolve().relative_to(quest_root).as_posix()
+        except ValueError:
+            return text
+
+    def _compact_artifact_delta(value: Any) -> dict[str, Any] | None:
+        if not isinstance(value, dict):
+            return None
+        return {
+            key: value.get(key)
+            for key in (
+                "schema_version",
+                "delta_id",
+                "delta_kind",
+                "sidecar_rel_path",
+                "path_count",
+                "changed_paths",
+            )
+            if value.get(key) is not None
+        }
+
+    def _compact_paths(payload: dict[str, Any], keys: tuple[str, ...]) -> dict[str, str]:
+        paths: dict[str, str] = {}
+        for key in keys:
+            relative = _quest_relative_path(payload.get(key))
+            if relative:
+                paths[key] = relative
+        return paths
+
+    def compact_paper_write_result(payload: dict[str, Any], *, tool_name: str) -> dict[str, Any]:
+        compact: dict[str, Any] = {
+            "ok": bool(payload.get("ok")),
+            "tool_name": tool_name,
+            "artifact_delta": _compact_artifact_delta(payload.get("artifact_delta")),
+            "hint": "Full paper artifact content was written to files; read the listed paths or artifact_delta sidecar only when needed.",
+        }
+        if tool_name == "submit_paper_outline":
+            compact.update(
+                {
+                    "mode": payload.get("mode"),
+                    "outline_id": payload.get("outline_id"),
+                    "paths": _compact_paths(
+                        payload,
+                        (
+                            "outline_path",
+                            "selected_outline_path",
+                            "outline_manifest_path",
+                            "paper_line_state_path",
+                            "outline_selection_path",
+                            "revised_outline_path",
+                        ),
+                    ),
+                }
+            )
+            return compact
+
+        manifest = payload.get("manifest") if isinstance(payload.get("manifest"), dict) else {}
+        paper_line_state = payload.get("paper_line_state") if isinstance(payload.get("paper_line_state"), dict) else {}
+        continuation = payload.get("continuation") if isinstance(payload.get("continuation"), dict) else {}
+        compact.update(
+            {
+                "package_type": manifest.get("package_type"),
+                "title": manifest.get("title"),
+                "selected_outline_ref": manifest.get("selected_outline_ref"),
+                "paper_branch": manifest.get("paper_branch") or paper_line_state.get("paper_branch"),
+                "next_anchor": continuation.get("anchor") or "decision",
+                "paths": _compact_paths(
+                    payload,
+                    (
+                        "manifest_path",
+                        "baseline_inventory_path",
+                        "evidence_ledger_path",
+                        "paper_line_state_path",
+                        "manuscript_coverage_path",
+                        "open_source_manifest_path",
+                    ),
+                ),
+            }
+        )
+        return compact
+
+    if issue_only_profile:
+        @server.tool(
+            name="prepare_github_issue",
+            description=(
+                "Generate a prefilled GitHub issue draft from the live local daemon's settings diagnostics. "
+                "By default this also asks the browser UI to navigate to `/settings/issues` and preload the generated draft."
+            ),
+        )
+        def prepare_github_issue(
+            summary: str = "",
+            user_notes: str = "",
+            include_doctor: bool = True,
+            include_logs: bool = True,
+            include_system_quirks: bool = False,
+            open_settings_page: bool = True,
+            comment: str | dict[str, Any] | None = None,
+        ) -> dict[str, Any]:
+            result = _prepare_github_issue_payload_via_daemon(
+                context.home,
+                summary=summary,
+                user_notes=user_notes,
+                include_doctor=include_doctor,
+                include_logs=include_logs,
+                include_system_quirks=include_system_quirks,
+            )
+            if open_settings_page:
+                result["ui_effects"] = [_issue_draft_route_effect(result)]
+            return finalize_artifact_tool(result, tool_name="prepare_github_issue")
+
+        return server
+
+    if start_setup_prepare_profile:
+        @server.tool(
+            name="prepare_start_setup_form",
+            description=(
+                "Prepare and apply a structured patch for the autonomous start form. "
+                "Use this when the setup agent has enough information to fill or refine the form automatically."
+            ),
+        )
+        def prepare_start_setup_form(
+            form_patch: dict[str, Any] | None = None,
+            session_patch: dict[str, Any] | None = None,
+            message: str = "",
+            comment: str | dict[str, Any] | None = None,
+        ) -> dict[str, Any]:
+            nested_form_patch, nested_session_patch = _split_nested_start_setup_payload(form_patch)
+            if nested_form_patch is not None:
+                form_patch = nested_form_patch
+            if session_patch is None and nested_session_patch is not None:
+                session_patch = nested_session_patch
+            sanitized_patch = _sanitize_start_setup_form_patch(form_patch)
+            sanitized_session_patch = _sanitize_start_setup_session_patch(session_patch)
+            if not sanitized_patch and not sanitized_session_patch:
+                raise ValueError("At least one of `form_patch` or `session_patch` must include supported fields.")
+            result = service.apply_start_setup_form_patch(
+                context.require_quest_root(),
+                form_patch=sanitized_patch,
+                session_patch=sanitized_session_patch,
+                message=message,
+            )
+            result["ui_effects"] = [_start_setup_patch_effect(sanitized_patch, session_patch=sanitized_session_patch, message=message)]
+            return finalize_artifact_tool(result, tool_name="prepare_start_setup_form")
+
+        return server
+
     @server.tool(name="record", description="Write a structured artifact record under the current quest.")
     def record(payload: dict[str, Any], comment: str | dict[str, Any] | None = None) -> dict[str, Any]:
         enriched = dict(payload)
@@ -514,6 +1320,94 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             workspace_root=context.worktree_root,
         )
 
+    @server.tool(
+        name="science",
+        description=(
+            "Record and update Science Evidence Graph nodes under the artifact namespace. "
+            "Use this for natural-science and engineering package checks, computational runs, dataset analyses, "
+            "parameter sweeps, validation results, and scientific claims. Do not use it for execution; "
+            "all commands, solver runs, SSH, and HPC work must go through bash_exec."
+        ),
+    )
+    def science(
+        action: str,
+        node_type: str | None = None,
+        node_id: str | None = None,
+        title: str | None = None,
+        summary: str | None = None,
+        status: str | None = None,
+        domain: str | None = None,
+        package_id: str | None = None,
+        task_type: str | None = None,
+        key_results: list[dict[str, Any]] | None = None,
+        evidence_paths: list[str] | None = None,
+        input_paths: list[str] | None = None,
+        output_paths: list[str] | None = None,
+        log_paths: list[str] | None = None,
+        validation_paths: list[str] | None = None,
+        parent_node_ids: list[str] | None = None,
+        related_node_ids: list[str] | None = None,
+        claim_type: str | None = None,
+        trust: str | None = None,
+        canvas: dict[str, Any] | None = None,
+        notify: bool = False,
+        relation_type: str | None = None,
+        relation_summary: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        def _normalize_paths(values: list[str] | None) -> list[str]:
+            if not isinstance(values, list):
+                return []
+            normalized: list[str] = []
+            seen: set[str] = set()
+            for value in values:
+                path = _quest_relative_path(value)
+                if not path or path in seen:
+                    continue
+                seen.add(path)
+                normalized.append(path)
+            return normalized
+
+        source: dict[str, Any] = {"kind": "agent"}
+        if context.agent_role:
+            source["role"] = context.agent_role
+        if context.run_id:
+            source["run_id"] = context.run_id
+        if context.worker_id:
+            source["worker_id"] = context.worker_id
+        result = service.science(
+            context.require_quest_root(),
+            action=action,
+            node_type=node_type,
+            node_id=node_id,
+            title=title,
+            summary=summary,
+            status=status,
+            domain=domain,
+            package_id=package_id,
+            task_type=task_type,
+            key_results=key_results,
+            evidence_paths=_normalize_paths(evidence_paths),
+            input_paths=_normalize_paths(input_paths),
+            output_paths=_normalize_paths(output_paths),
+            log_paths=_normalize_paths(log_paths),
+            validation_paths=_normalize_paths(validation_paths),
+            parent_node_ids=parent_node_ids,
+            related_node_ids=related_node_ids,
+            claim_type=claim_type,
+            trust=trust,
+            canvas=canvas,
+            notify=notify,
+            relation_type=relation_type,
+            relation_summary=relation_summary,
+            metadata=metadata,
+            source=source,
+            run_id=context.run_id,
+            workspace_root=context.worktree_root,
+        )
+        return finalize_artifact_tool(result, tool_name="science")
+
     @server.tool(name="checkpoint", description="Create a Git checkpoint in the current quest repository.")
     def checkpoint(
         message: str,
@@ -601,15 +1495,26 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         create_worktree_if_missing: bool = True,
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        return service.activate_branch(
-            context.require_quest_root(),
-            branch=branch,
-            idea_id=idea_id,
-            run_id=run_id,
-            anchor=anchor,
-            promote_to_head=promote_to_head,
-            create_worktree_if_missing=create_worktree_if_missing,
-        )
+        try:
+            return service.activate_branch(
+                context.require_quest_root(),
+                branch=branch,
+                idea_id=idea_id,
+                run_id=run_id,
+                anchor=anchor,
+                promote_to_head=promote_to_head,
+                create_worktree_if_missing=create_worktree_if_missing,
+            )
+        except (ValueError, FileNotFoundError, RuntimeError) as exc:
+            return finalize_artifact_tool(
+                _artifact_guided_error_payload(
+                    service,
+                    context.require_quest_root(),
+                    tool_name="activate_branch",
+                    exc=exc,
+                ),
+                tool_name="activate_branch",
+            )
 
     @server.tool(
         name="submit_idea",
@@ -646,31 +1551,42 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         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,
-            decision_reason=decision_reason,
-            foundation_ref=foundation_ref,
-            foundation_reason=foundation_reason,
-            next_target=next_target,
-            draft_markdown=draft_markdown,
-            source_candidate_id=source_candidate_id,
-        )
+        try:
+            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,
+                decision_reason=decision_reason,
+                foundation_ref=foundation_ref,
+                foundation_reason=foundation_reason,
+                next_target=next_target,
+                draft_markdown=draft_markdown,
+                source_candidate_id=source_candidate_id,
+            )
+        except (ValueError, FileNotFoundError, RuntimeError) as exc:
+            return finalize_artifact_tool(
+                _artifact_guided_error_payload(
+                    service,
+                    context.require_quest_root(),
+                    tool_name="submit_idea",
+                    exc=exc,
+                ),
+                tool_name="submit_idea",
+            )
 
     @server.tool(
         name="list_research_branches",
@@ -694,6 +1610,23 @@ def build_artifact_server(context: McpContext) -> FastMCP:
     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",
+        description=(
+            "Read the active paper contract, including selected outline, section result tables, evidence ledger items, "
+            "analysis inventory, and experiment matrix rows. Use detail='full' by default when writing or finalizing from paper evidence."
+        ),
+        annotations=_read_only_tool_annotations(title="Get paper contract"),
+    )
+    def get_paper_contract(
+        detail: str = "full",
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.get_paper_contract(
+            context.require_quest_root(),
+            detail=detail,
+        )
+
     @server.tool(
         name="get_paper_contract_health",
         description=(
@@ -706,10 +1639,107 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         detail: str = "summary",
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        return service.get_paper_contract_health(
+        result = service.get_paper_contract_health(
             context.require_quest_root(),
             detail=detail,
         )
+        normalized_detail = str(detail or "summary").strip().lower() or "summary"
+        return compact_mcp_tool_result(
+            result,
+            quest_root=context.require_quest_root(),
+            run_id=context.run_id,
+            tool_name="artifact.get_paper_contract_health",
+            detail=normalized_detail,
+            force=normalized_detail == "full",
+            reason="artifact_full_detail_context_budget",
+            full_detail_requested=normalized_detail == "full",
+        )
+
+    @server.tool(
+        name="validate_manuscript_coverage",
+        description=(
+            "Validate whether the current paper is only a draft checkpoint or a full manuscript/submission package. "
+            "Checks section coverage, figures/tables, ready analysis groups, PDF, and submission checklist state."
+        ),
+        annotations=_read_only_tool_annotations(title="Validate manuscript coverage"),
+    )
+    def validate_manuscript_coverage(
+        detail: str = "summary",
+        minimum_sections: int = 5,
+        minimum_analysis_groups: int = 5,
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.validate_manuscript_coverage(
+            context.require_quest_root(),
+            detail=detail,
+            minimum_sections=minimum_sections,
+            minimum_analysis_groups=minimum_analysis_groups,
+        )
+
+    @server.tool(
+        name="validate_academic_outline",
+        description=(
+            "Validate that the selected outline is a real paper plan before drafting. "
+            "Checks the one-sentence paper idea, story spine, evidence boundaries, core claims, method, evaluation plan, "
+            "4-8 planned analyses or an explicit waiver, and implementation wording leakage."
+        ),
+        annotations=_read_only_tool_annotations(title="Validate academic outline"),
+    )
+    def validate_academic_outline(
+        detail: str = "summary",
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.validate_academic_outline(
+            context.require_quest_root(),
+            detail=detail,
+        )
+
+    @server.tool(
+        name="validate_manuscript_language",
+        description=(
+            "Scan paper draft/LaTeX for main-text implementation or route terms that should stay in artifact records "
+            "or appendix reproducibility details."
+        ),
+        annotations=_read_only_tool_annotations(title="Validate manuscript language"),
+    )
+    def validate_manuscript_language(
+        detail: str = "summary",
+        scope: str = "main_text",
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.validate_manuscript_language(
+            context.require_quest_root(),
+            detail=detail,
+            scope=scope,
+        )
+
+    @server.tool(
+        name="compile_outline_to_writing_plan",
+        description=(
+            "Turn the selected outline into concrete writing jobs for introduction, method, setup, results, analyses, "
+            "limitations, and abstract. Use after validate_academic_outline and before drafting."
+        ),
+    )
+    def compile_outline_to_writing_plan(
+        detail: str = "summary",
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        try:
+            result = service.compile_outline_to_writing_plan(
+                context.require_quest_root(),
+                detail=detail,
+            )
+            return finalize_state_changing_artifact_tool(result, tool_name="compile_outline_to_writing_plan")
+        except (ValueError, FileNotFoundError, RuntimeError) as exc:
+            return finalize_artifact_tool(
+                _artifact_guided_error_payload(
+                    service,
+                    context.require_quest_root(),
+                    tool_name="compile_outline_to_writing_plan",
+                    exc=exc,
+                ),
+                tool_name="compile_outline_to_writing_plan",
+            )
 
     @server.tool(
         name="get_quest_state",
@@ -723,10 +1753,22 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         detail: str = "summary",
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        return service.get_quest_state(
+        result = service.get_quest_state(
             context.require_quest_root(),
             detail=detail,
         )
+        normalized_detail = str(detail or "summary").strip().lower() or "summary"
+        return cached_compact_mcp_tool_result(
+            result,
+            quest_root=context.require_quest_root(),
+            run_id=context.run_id,
+            tool_name="artifact.get_quest_state",
+            detail=normalized_detail,
+            cache_key={"detail": normalized_detail},
+            force=normalized_detail == "full",
+            reason="artifact_full_detail_context_budget",
+            full_detail_requested=normalized_detail == "full",
+        )
 
     @server.tool(
         name="get_global_status",
@@ -741,12 +1783,71 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         locale: str = "zh",
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        return service.get_global_status(
+        result = service.get_global_status(
+            context.require_quest_root(),
+            detail=detail,
+            locale=locale,
+        )
+        normalized_detail = str(detail or "brief").strip().lower() or "brief"
+        normalized_locale = str(locale or "zh").strip().lower() or "zh"
+        return cached_compact_mcp_tool_result(
+            result,
+            quest_root=context.require_quest_root(),
+            run_id=context.run_id,
+            tool_name="artifact.get_global_status",
+            detail=normalized_detail,
+            cache_key={"detail": normalized_detail, "locale": normalized_locale},
+            force=normalized_detail == "full",
+            reason="artifact_full_detail_context_budget",
+            full_detail_requested=normalized_detail == "full",
+        )
+
+    @server.tool(
+        name="get_research_map_status",
+        description=(
+            "Read the current research-node progress state that corresponds to the quest canvas. "
+            "Returns the active workspace node, research head node, node history, runtime refs, canvas freshness, recommended activation ref, and Git identifiers so agents can recover progress or switch branches without guessing."
+        ),
+        annotations=_read_only_tool_annotations(title="Get research map status"),
+    )
+    def get_research_map_status(
+        detail: str = "summary",
+        locale: str = "zh",
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.get_research_map_status(
             context.require_quest_root(),
             detail=detail,
             locale=locale,
         )
 
+    @server.tool(
+        name="get_benchstore_catalog",
+        description=(
+            "Read the BenchStore catalog with current-device recommendation hints. "
+            "Use detail='summary' for compact recommendations or detail='full' for the full structured catalog."
+        ),
+        annotations=_read_only_tool_annotations(title="Get BenchStore catalog"),
+    )
+    def get_benchstore_catalog(
+        detail: str = "summary",
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return service.get_benchstore_catalog(
+            context.require_quest_root(),
+            detail=detail,
+        )
+
+    @server.tool(
+        name="get_start_setup_context",
+        description=(
+            "Read the current autonomous start-setup context, including the suggested form and selected benchmark context when present."
+        ),
+        annotations=_read_only_tool_annotations(title="Get start setup context"),
+    )
+    def get_start_setup_context(comment: str | dict[str, Any] | None = None) -> dict[str, Any]:
+        return service.get_start_setup_context(context.require_quest_root())
+
     @server.tool(
         name="get_method_scoreboard",
         description=(
@@ -883,6 +1984,16 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             )
         except MetricContractValidationError as exc:
             return _metric_validation_error_payload(exc)
+        except (ValueError, FileNotFoundError, RuntimeError) as exc:
+            return finalize_artifact_tool(
+                _artifact_guided_error_payload(
+                    service,
+                    context.require_quest_root(),
+                    tool_name="record_main_experiment",
+                    exc=exc,
+                ),
+                tool_name="record_main_experiment",
+            )
 
     @server.tool(
         name="create_analysis_campaign",
@@ -903,24 +2014,39 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         todo_items: list[dict[str, Any]] | None = None,
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        return service.create_analysis_campaign(
-            context.require_quest_root(),
-            campaign_title=campaign_title,
-            campaign_goal=campaign_goal,
-            parent_run_id=parent_run_id,
-            slices=slices,
-            campaign_origin=campaign_origin,
-            selected_outline_ref=selected_outline_ref,
-            research_questions=research_questions,
-            experimental_designs=experimental_designs,
-            todo_items=todo_items,
-        )
+        try:
+            return service.create_analysis_campaign(
+                context.require_quest_root(),
+                campaign_title=campaign_title,
+                campaign_goal=campaign_goal,
+                parent_run_id=parent_run_id,
+                slices=slices,
+                campaign_origin=campaign_origin,
+                selected_outline_ref=selected_outline_ref,
+                research_questions=research_questions,
+                experimental_designs=experimental_designs,
+                todo_items=todo_items,
+            )
+        except (ValueError, FileNotFoundError, RuntimeError) as exc:
+            return finalize_artifact_tool(
+                _artifact_guided_error_payload(
+                    service,
+                    context.require_quest_root(),
+                    tool_name="create_analysis_campaign",
+                    exc=exc,
+                ),
+                tool_name="create_analysis_campaign",
+            )
 
     @server.tool(
         name="submit_paper_outline",
         description=(
             "Persist a paper outline candidate, select an approved outline, or revise the selected outline. "
-            "Use this before analysis campaigns that should support final writing claims."
+            "Use this before analysis campaigns that should support final writing claims. "
+            "For paper-facing work, put the paper idea and section plan in detailed_outline.paper_view, "
+            "and keep result rows, paths, run ids, and reproducibility details in detailed_outline.evidence_view. "
+            "Good paper_view records a one-sentence thesis, what the reader should learn, evidence boundaries, "
+            "and a 4-8 item analysis plan when the paper is mature."
         ),
     )
     def submit_paper_outline(
@@ -935,19 +2061,33 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         selected_reason: str | None = None,
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        result = service.submit_paper_outline(
-            context.require_quest_root(),
-            mode=mode,
-            outline_id=outline_id,
-            title=title,
-            note=note,
-            story=story,
-            ten_questions=ten_questions,
-            detailed_outline=detailed_outline,
-            review_result=review_result,
-            selected_reason=selected_reason,
-        )
-        return finalize_state_changing_artifact_tool(result, tool_name="submit_paper_outline")
+        try:
+            result = service.submit_paper_outline(
+                context.require_quest_root(),
+                mode=mode,
+                outline_id=outline_id,
+                title=title,
+                note=note,
+                story=story,
+                ten_questions=ten_questions,
+                detailed_outline=detailed_outline,
+                review_result=review_result,
+                selected_reason=selected_reason,
+            )
+            return finalize_state_changing_artifact_tool(
+                compact_paper_write_result(result, tool_name="submit_paper_outline"),
+                tool_name="submit_paper_outline",
+            )
+        except (ValueError, FileNotFoundError, RuntimeError) as exc:
+            return finalize_artifact_tool(
+                _artifact_guided_error_payload(
+                    service,
+                    context.require_quest_root(),
+                    tool_name="submit_paper_outline",
+                    exc=exc,
+                ),
+                tool_name="submit_paper_outline",
+            )
 
     @server.tool(
         name="list_paper_outlines",
@@ -958,12 +2098,20 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         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())
+        return cached_compact_mcp_tool_result(
+            service.list_paper_outlines(context.require_quest_root()),
+            quest_root=context.require_quest_root(),
+            run_id=context.run_id,
+            tool_name="artifact.list_paper_outlines",
+            detail="inventory",
+            cache_key={"detail": "inventory"},
+            reason="artifact_inventory_context_budget",
+        )
 
     @server.tool(
         name="submit_paper_bundle",
         description=(
-            "Persist the final paper bundle manifest, including outline, draft, LaTeX/PDF outputs, and build reports."
+            "Persist a paper bundle manifest. Defaults to a draft checkpoint; use package_type='submission_package' only for submission-ready manuscripts."
         ),
     )
     def submit_paper_bundle(
@@ -977,21 +2125,38 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         compile_report_path: str | None = None,
         pdf_path: str | None = None,
         latex_root_path: str | None = None,
+        package_type: str = "draft_checkpoint",
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        return service.submit_paper_bundle(
-            context.require_quest_root(),
-            title=title,
-            summary=summary,
-            outline_path=outline_path,
-            draft_path=draft_path,
-            writing_plan_path=writing_plan_path,
-            references_path=references_path,
-            claim_evidence_map_path=claim_evidence_map_path,
-            compile_report_path=compile_report_path,
-            pdf_path=pdf_path,
-            latex_root_path=latex_root_path,
-        )
+        try:
+            result = service.submit_paper_bundle(
+                context.require_quest_root(),
+                title=title,
+                summary=summary,
+                outline_path=outline_path,
+                draft_path=draft_path,
+                writing_plan_path=writing_plan_path,
+                references_path=references_path,
+                claim_evidence_map_path=claim_evidence_map_path,
+                compile_report_path=compile_report_path,
+                pdf_path=pdf_path,
+                latex_root_path=latex_root_path,
+                package_type=package_type,
+            )
+            return finalize_state_changing_artifact_tool(
+                compact_paper_write_result(result, tool_name="submit_paper_bundle"),
+                tool_name="submit_paper_bundle",
+            )
+        except (ValueError, FileNotFoundError, RuntimeError) as exc:
+            return finalize_artifact_tool(
+                _artifact_guided_error_payload(
+                    service,
+                    context.require_quest_root(),
+                    tool_name="submit_paper_bundle",
+                    exc=exc,
+                ),
+                tool_name="submit_paper_bundle",
+            )
 
     @server.tool(
         name="record_analysis_slice",
@@ -1050,8 +2215,19 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         if comment is not None and "comment" not in enriched:
             enriched["comment"] = comment
         enriched.setdefault("source", {"kind": "artifact_publish", "quest_id": context.quest_id, "quest_root": str(context.require_quest_root())})
-        result = service.publish_baseline(context.require_quest_root(), enriched)
-        return finalize_state_changing_artifact_tool(result, tool_name="publish_baseline")
+        try:
+            result = service.publish_baseline(context.require_quest_root(), enriched)
+            return finalize_state_changing_artifact_tool(result, tool_name="publish_baseline")
+        except (ValueError, FileNotFoundError, RuntimeError) as exc:
+            return finalize_artifact_tool(
+                _artifact_guided_error_payload(
+                    service,
+                    context.require_quest_root(),
+                    tool_name="publish_baseline",
+                    exc=exc,
+                ),
+                tool_name="publish_baseline",
+            )
 
     @server.tool(name="attach_baseline", description="Attach a published baseline to the current quest.")
     def attach_baseline(
@@ -1059,14 +2235,27 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         variant_id: str | None = None,
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        result = service.attach_baseline(context.require_quest_root(), baseline_id, variant_id)
-        return finalize_state_changing_artifact_tool(result, tool_name="attach_baseline")
+        try:
+            result = service.attach_baseline(context.require_quest_root(), baseline_id, variant_id)
+            return finalize_state_changing_artifact_tool(result, tool_name="attach_baseline")
+        except (ValueError, FileNotFoundError, RuntimeError) as exc:
+            return finalize_artifact_tool(
+                _artifact_guided_error_payload(
+                    service,
+                    context.require_quest_root(),
+                    tool_name="attach_baseline",
+                    exc=exc,
+                ),
+                tool_name="attach_baseline",
+            )
 
     @server.tool(
         name="confirm_baseline",
         description=(
             "Confirm the active quest baseline and open the stage gate into idea work. "
-            "The baseline path must point at a quest-local baseline under baselines/local or baselines/imported."
+            "The baseline path must point at a quest-local baseline under baselines/local or baselines/imported. "
+            "Descriptions, derivations, and source refs must live on entries inside "
+            "`metric_contract.metrics`."
         ),
     )
     def confirm_baseline(
@@ -1075,13 +2264,13 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         variant_id: str | None = None,
         summary: str | None = None,
         baseline_kind: str | None = None,
-        metric_contract: dict[str, Any] | None = None,
+        metric_contract: MetricContractPayload | None = None,
         metric_directions: dict[str, str] | None = None,
         metrics_summary: dict[str, Any] | None = None,
-        primary_metric: dict[str, Any] | None = None,
+        primary_metric: PrimaryMetricPayload | None = None,
         auto_advance: bool = True,
         comment: str | dict[str, Any] | None = None,
-    ) -> dict[str, Any]:
+        ) -> dict[str, Any]:
         try:
             result = service.confirm_baseline(
                 context.require_quest_root(),
@@ -1091,16 +2280,156 @@ def build_artifact_server(context: McpContext) -> FastMCP:
                 variant_id=variant_id,
                 summary=summary,
                 baseline_kind=baseline_kind,
-                metric_contract=metric_contract,
+                metric_contract=metric_contract.model_dump(exclude_none=True) if metric_contract is not None else None,
                 metric_directions=metric_directions,
                 metrics_summary=metrics_summary,
-                primary_metric=primary_metric,
+                primary_metric=primary_metric.model_dump(exclude_none=True) if primary_metric is not None else None,
                 auto_advance=auto_advance,
                 strict_metric_contract=True,
             )
             return finalize_state_changing_artifact_tool(result, tool_name="confirm_baseline")
         except MetricContractValidationError as exc:
             return _metric_validation_error_payload(exc)
+        except (ValueError, FileNotFoundError, RuntimeError) as exc:
+            return finalize_artifact_tool(
+                _artifact_guided_error_payload(
+                    service,
+                    context.require_quest_root(),
+                    tool_name="confirm_baseline",
+                    exc=exc,
+                ),
+                tool_name="confirm_baseline",
+            )
+
+    @server.tool(
+        name="overwrite_baseline",
+        description=(
+            "Refresh an already accepted baseline after verified code, variant, or canonical metric changes. "
+            "This rewrites the active baseline reference and downstream inventories, so comparator-breaking changes "
+            "should usually become a new baseline id or variant instead of an in-place overwrite."
+        ),
+    )
+    def overwrite_baseline(
+        change_summary: str,
+        baseline_id: str | None = None,
+        baseline_path: str | None = None,
+        variant_id: str | None = None,
+        summary: str | None = None,
+        baseline_kind: str | None = None,
+        metric_contract: MetricContractPayload | None = None,
+        metric_directions: dict[str, str] | None = None,
+        metrics_summary: dict[str, Any] | None = None,
+        primary_metric: PrimaryMetricPayload | None = None,
+        supplementary_baselines: list[SupplementaryBaselinePayload] | None = None,
+        overwrite_scope: str = "full_refresh",
+        allow_path_change: bool = False,
+        allow_protocol_breaking_change: bool = False,
+        sync_requested_baseline_ref: bool = True,
+        refresh_analysis_inventory: bool = True,
+        refresh_paper_inventory: bool = True,
+        auto_advance: bool = True,
+        comment: str | dict[str, Any] | None = None,
+        ) -> dict[str, Any]:
+        try:
+            result = service.overwrite_baseline(
+                context.require_quest_root(),
+                baseline_id=baseline_id,
+                baseline_path=baseline_path,
+                variant_id=variant_id,
+                summary=summary,
+                change_summary=change_summary,
+                baseline_kind=baseline_kind,
+                metric_contract=metric_contract.model_dump(exclude_none=True) if metric_contract is not None else None,
+                metric_directions=metric_directions,
+                metrics_summary=metrics_summary,
+                primary_metric=primary_metric.model_dump(exclude_none=True) if primary_metric is not None else None,
+                supplementary_baselines=[
+                    item.model_dump(exclude_none=True) for item in (supplementary_baselines or [])
+                ]
+                or None,
+                overwrite_scope=overwrite_scope,
+                allow_path_change=allow_path_change,
+                allow_protocol_breaking_change=allow_protocol_breaking_change,
+                sync_requested_baseline_ref=sync_requested_baseline_ref,
+                refresh_analysis_inventory=refresh_analysis_inventory,
+                refresh_paper_inventory=refresh_paper_inventory,
+                auto_advance=auto_advance,
+                strict_metric_contract=True,
+                comment=comment,
+            )
+            return finalize_state_changing_artifact_tool(result, tool_name="overwrite_baseline")
+        except MetricContractValidationError as exc:
+            return _metric_validation_error_payload(exc)
+        except (ValueError, FileNotFoundError, RuntimeError) as exc:
+            return finalize_artifact_tool(
+                _artifact_guided_error_payload(
+                    service,
+                    context.require_quest_root(),
+                    tool_name="overwrite_baseline",
+                    exc=exc,
+                ),
+                tool_name="overwrite_baseline",
+            )
+
+    @server.tool(
+        name="overwrite_baseline",
+        description=(
+            "Refresh an already accepted baseline after verified code, variant, or canonical metric changes. "
+            "This rewrites the active baseline reference and downstream inventories, so comparator-breaking changes "
+            "should usually become a new baseline id or variant instead of an in-place overwrite."
+        ),
+    )
+    def overwrite_baseline(
+        change_summary: str,
+        baseline_id: str | None = None,
+        baseline_path: str | None = None,
+        variant_id: str | None = None,
+        summary: str | None = None,
+        baseline_kind: str | None = None,
+        metric_contract: MetricContractPayload | None = None,
+        metric_directions: dict[str, str] | None = None,
+        metrics_summary: dict[str, Any] | None = None,
+        primary_metric: PrimaryMetricPayload | None = None,
+        supplementary_baselines: list[SupplementaryBaselinePayload] | None = None,
+        overwrite_scope: str = "full_refresh",
+        allow_path_change: bool = False,
+        allow_protocol_breaking_change: bool = False,
+        sync_requested_baseline_ref: bool = True,
+        refresh_analysis_inventory: bool = True,
+        refresh_paper_inventory: bool = True,
+        auto_advance: bool = True,
+        comment: str | dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        try:
+            result = service.overwrite_baseline(
+                context.require_quest_root(),
+                baseline_id=baseline_id,
+                baseline_path=baseline_path,
+                variant_id=variant_id,
+                summary=summary,
+                change_summary=change_summary,
+                baseline_kind=baseline_kind,
+                metric_contract=metric_contract.model_dump(exclude_none=True) if metric_contract is not None else None,
+                metric_directions=metric_directions,
+                metrics_summary=metrics_summary,
+                primary_metric=primary_metric.model_dump(exclude_none=True) if primary_metric is not None else None,
+                supplementary_baselines=[
+                    item.model_dump(exclude_none=True) for item in (supplementary_baselines or [])
+                ]
+                or None,
+                overwrite_scope=overwrite_scope,
+                allow_path_change=allow_path_change,
+                allow_protocol_breaking_change=allow_protocol_breaking_change,
+                sync_requested_baseline_ref=sync_requested_baseline_ref,
+                refresh_analysis_inventory=refresh_analysis_inventory,
+                refresh_paper_inventory=refresh_paper_inventory,
+                auto_advance=auto_advance,
+                strict_metric_contract=True,
+                comment=comment,
+            )
+            return finalize_state_changing_artifact_tool(result, tool_name="overwrite_baseline")
+        except MetricContractValidationError as exc:
+            return _metric_validation_error_payload(exc)
 
     @server.tool(
         name="waive_baseline",
@@ -1111,13 +2440,24 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         auto_advance: bool = True,
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        result = service.waive_baseline(
-            context.require_quest_root(),
-            reason=reason,
-            comment=comment,
-            auto_advance=auto_advance,
-        )
-        return finalize_state_changing_artifact_tool(result, tool_name="waive_baseline")
+        try:
+            result = service.waive_baseline(
+                context.require_quest_root(),
+                reason=reason,
+                comment=comment,
+                auto_advance=auto_advance,
+            )
+            return finalize_state_changing_artifact_tool(result, tool_name="waive_baseline")
+        except (ValueError, FileNotFoundError, RuntimeError) as exc:
+            return finalize_artifact_tool(
+                _artifact_guided_error_payload(
+                    service,
+                    context.require_quest_root(),
+                    tool_name="waive_baseline",
+                    exc=exc,
+                ),
+                tool_name="waive_baseline",
+            )
 
     @server.tool(
         name="arxiv",
@@ -1248,7 +2588,8 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
         name="bash_exec",
         description=(
             "Execute a bash command inside the current quest. "
-            "mode=detach returns immediately. mode=await/create waits for completion. "
+            "mode=detach returns immediately. mode=await/create waits for completion up to a bounded wait window, "
+            "then returns a running-session notice if the command is still active. "
             "mode=read returns the saved log. It returns the full saved log up to 2000 lines, "
             "or a 500-line head plus 1500-line tail preview for longer logs. "
             "Use start/tail for rendered line windows and tail_limit/after_seq for seq-based monitoring. "
@@ -1257,7 +2598,7 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
         ),
     )
     def bash_exec(
-        command: str = "",
+        command: Any = "",
         mode: str = "detach",
         id: str | None = None,
         reason: str | None = None,
@@ -1266,6 +2607,7 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
         export_log: bool = False,
         export_log_to: str | None = None,
         timeout_seconds: int | None = None,
+        wait_timeout_seconds: int | None = None,
         status: str | None = None,
         kind: str | None = None,
         agent_ids: list[str] | None = None,
@@ -1286,6 +2628,28 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
         quest_root = context.require_quest_root().resolve()
 
         def finalize(payload: dict[str, Any]) -> dict[str, Any]:
+            if normalized_mode == "read":
+                bash_id = str(payload.get("bash_id") or payload.get("id") or id or "")
+                payload = cached_compact_mcp_tool_result(
+                    payload,
+                    quest_root=quest_root,
+                    run_id=context.run_id,
+                    tool_name="bash_exec.bash_exec",
+                    detail="read",
+                    cache_key={
+                        "mode": "read",
+                        "bash_id": bash_id,
+                        "start": start,
+                        "tail": tail,
+                        "tail_limit": tail_limit,
+                        "before_seq": before_seq,
+                        "after_seq": after_seq,
+                        "order": order,
+                        "include_log": include_log,
+                    },
+                    source_path=service.terminal_log_path(quest_root, bash_id) if bash_id else None,
+                    reason="bash_exec_read_context_budget",
+                )
             quest_service.record_tool_activity(
                 quest_root,
                 tool_name=f"bash_exec.{normalized_mode}",
@@ -1298,6 +2662,35 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
             normalized_mode = "await"
         if normalized_mode not in {"detach", "await", "read", "kill", "list", "history"}:
             raise ValueError("Mode must be one of `detach`, `await`, `create`, `read`, `kill`, `list`, or `history`.")
+        normalized_command = _normalize_bash_exec_command_input(command)
+        normalized_timeout_seconds = _normalize_positive_timeout_seconds(
+            timeout_seconds,
+            field_name="timeout_seconds",
+        )
+        normalized_wait_timeout_seconds = _normalize_positive_timeout_seconds(
+            wait_timeout_seconds,
+            field_name="wait_timeout_seconds",
+        )
+
+        def build_await_payload(session: dict[str, Any], *, wait_timeout: int | None) -> dict[str, Any]:
+            payload = service.build_tool_result(
+                context,
+                session=session,
+                include_log=False,
+                export_log=export_log,
+                export_log_to=export_log_to,
+            )
+            session_status = str(session.get("status") or "").strip().lower()
+            if wait_timeout is not None and session_status not in BASH_EXEC_TERMINAL_STATUSES:
+                payload.update(
+                    _build_bash_exec_wait_notice(
+                        bash_id=str(session["bash_id"]),
+                        wait_timeout_seconds=wait_timeout,
+                        status=session_status,
+                    )
+                )
+            return payload
+
         if normalized_mode in {"list", "history"}:
             resolved_limit = 500 if normalized_mode == "history" and limit == 20 else max(1, min(limit, 500))
             items = service.list_sessions(
@@ -1356,7 +2749,7 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
                         tail=tail if tail is not None else tail_limit,
                     )
                 )
-                return finalize(payload)
+                return finalize(_attach_bash_log_truncation_metadata(payload))
             use_tail = tail_limit is not None or before_seq is not None or after_seq is not None or normalized_order != "asc"
             if use_tail:
                 resolved_tail_limit = max(1, min(int(tail_limit or 200), 1000))
@@ -1383,6 +2776,39 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
                 payload["after_seq"] = tail_meta.get("after_seq")
                 payload["before_seq"] = tail_meta.get("before_seq")
                 payload["order"] = normalized_order
+                visible_seqs = [int(entry.get("seq") or 0) for entry in entries if int(entry.get("seq") or 0) > 0]
+                seq_window_start = min(visible_seqs) if visible_seqs else None
+                seq_window_end = max(visible_seqs) if visible_seqs else None
+                latest_seq_value = tail_meta.get("latest_seq")
+                seqs_before_window = max(int(seq_window_start or 0) - 1, 0) if seq_window_start is not None else None
+                seqs_after_window = (
+                    max(int(latest_seq_value or 0) - int(seq_window_end or 0), 0)
+                    if seq_window_end is not None and latest_seq_value is not None
+                    else None
+                )
+                payload["seq_window_start"] = seq_window_start
+                payload["seq_window_end"] = seq_window_end
+                payload["seq_has_more_before"] = bool(seqs_before_window and seqs_before_window > 0)
+                payload["seq_has_more_after"] = bool(seqs_after_window and seqs_after_window > 0)
+                payload["seqs_before_window"] = seqs_before_window
+                payload["seqs_after_window"] = seqs_after_window
+                payload["tail_is_partial"] = payload["seq_has_more_before"] or payload["seq_has_more_after"]
+                if payload["tail_is_partial"]:
+                    before_text = (
+                        f"{seqs_before_window} seq(s) before"
+                        if seqs_before_window is not None
+                        else "some earlier seqs outside this filtered window"
+                    )
+                    after_text = (
+                        f"{seqs_after_window} seq(s) after"
+                        if seqs_after_window is not None
+                        else "some later seqs outside this filtered window"
+                    )
+                    payload["log_truncation_notice"] = (
+                        "This seq-based bash_exec read is only a partial window, not the full log. "
+                        f"It currently covers seq {seq_window_start} to {seq_window_end}; there are {before_text} and {after_text}. "
+                        "Continue with before_seq / after_seq or adjust tail_limit if you need more surrounding output."
+                    )
                 return finalize(payload)
             payload = service.build_tool_result(
                 context,
@@ -1392,7 +2818,7 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
                 export_log_to=export_log_to,
             )
             payload.update(_build_default_bash_log_payload_from_path(service.terminal_log_path(quest_root, bash_id)))
-            return finalize(payload)
+            return finalize(_attach_bash_log_truncation_metadata(payload))
         if normalized_mode == "kill":
             bash_id = service.resolve_session_id(quest_root, id)
             session = service.request_stop(
@@ -1403,39 +2829,41 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
                 force=force,
             )
             if wait:
-                session = service.wait_for_session(quest_root, bash_id, timeout_seconds=timeout_seconds)
+                resolved_wait_timeout = normalized_wait_timeout_seconds or normalized_timeout_seconds
+                session = service.wait_for_session(quest_root, bash_id, timeout_seconds=resolved_wait_timeout)
             return finalize(service.build_tool_result(context, session=session, include_log=False))
-        if normalized_mode == "await" and not command:
+        if normalized_mode == "await" and not normalized_command:
             bash_id = service.resolve_session_id(quest_root, id)
-            session = service.wait_for_session(quest_root, bash_id, timeout_seconds=timeout_seconds)
-            return finalize(service.build_tool_result(
-                context,
-                session=session,
-                include_log=False,
-                export_log=export_log,
-                export_log_to=export_log_to,
-            ))
-        if not (command or "").strip():
+            resolved_wait_timeout = (
+                normalized_wait_timeout_seconds
+                or normalized_timeout_seconds
+                or DEFAULT_BASH_EXEC_AWAIT_WAIT_TIMEOUT_SECONDS
+            )
+            session = service.wait_for_session(quest_root, bash_id, timeout_seconds=resolved_wait_timeout)
+            return finalize(build_await_payload(session, wait_timeout=resolved_wait_timeout))
+        if not normalized_command.strip():
             raise ValueError("command is required for `detach` and `await`.")
         session = service.start_session(
             context,
-            command=command,
+            command=normalized_command,
             mode=normalized_mode,
             workdir=workdir,
             env=env,
-            timeout_seconds=timeout_seconds,
+            timeout_seconds=normalized_timeout_seconds,
             comment=comment,
         )
         if normalized_mode == "detach":
             return finalize(service.build_tool_result(context, session=session, include_log=False))
-        session = service.wait_for_session(quest_root, str(session["bash_id"]), timeout_seconds=timeout_seconds)
-        return finalize(service.build_tool_result(
-            context,
-            session=session,
-            include_log=False,
-            export_log=export_log,
-            export_log_to=export_log_to,
-        ))
+        resolved_wait_timeout = (
+            normalized_wait_timeout_seconds
+            or DEFAULT_BASH_EXEC_AWAIT_WAIT_TIMEOUT_SECONDS
+        )
+        session = service.wait_for_session(
+            quest_root,
+            str(session["bash_id"]),
+            timeout_seconds=resolved_wait_timeout,
+        )
+        return finalize(build_await_payload(session, wait_timeout=resolved_wait_timeout))
 
     return server
 
@@ -1458,7 +2886,19 @@ def _resolve_search_scope(context: McpContext, scope: str) -> str:
     return normalized
 
 
+def _ensure_utf8_stdio() -> None:
+    for stream in (sys.stdin, sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if not callable(reconfigure):
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            continue
+
+
 def main() -> int:
+    _ensure_utf8_stdio()
     parser = argparse.ArgumentParser(description="DeepScientist built-in MCP server")
     parser.add_argument("--namespace", choices=("memory", "artifact", "bash_exec"), required=True)
     args = parser.parse_args()