@guanlin4924/devflow-pi 0.1.95 → 0.1.96

package/README.md

@@ -11,7 +11,7 @@ Devflow Pi 是一个面向项目研发交付的独立 OMP 产品入口，内置
 安装与启动：
 
 ```bash
-npm install -g @guanlin4924/devflow-pi@0.1.95
+npm install -g @guanlin4924/devflow-pi@0.1.96
 cd /path/to/your-project
 devflow-pi init
 devflow-pi doctor
@@ -115,7 +115,7 @@ Devflow 会在输入框上方显示“当前 Feature 交付链路”：它基于
 - 验收失败不会创建另一套人工台账，而是进入 `acceptance-remediation`：诊断 → 修复 → code-index 刷新 → 原冻结 `TC-*` 重跑。
 - CP-4 通过后只进入一个 `workflow-release-closeout` 步骤，统一写入 `.devflow/planning/milestones/current-CLOSEOUT.md` 并更新项目状态、导航和版本记录。
 
-正常使用不需要记忆底层命令：在 Devflow 工作流中按步骤继续即可。需要排查时，可用 `devflow_acceptance_tests` 查看冻结套件，或由工作流调用 `devflow_tdd_evidence` 与 `devflow_run_acceptance_tests` 生成 Core 指定写入的证据；不要手写“已测试”来替代结果文件。本地 hook 拒绝 Agent 文件工具与 shell 访问 `control.db` 及 Devflow 数据目录 `projects/`、拒绝写入 canonical 验收结果文件（Read 类读取工具仍可读取结果文件；shell 命令仅在指向真实控制库路径时才被拒，单纯出现 `control.db` 文本不受影响）。它是误操作防护，不构成对同系统用户恶意进程的安全隔离。
+正常使用不需要记忆底层命令：在 Devflow 工作流中按步骤继续即可。需要排查时，可用 `devflow_acceptance_tests` 查看冻结套件，或由工作流调用 `devflow_tdd_evidence` 与 `devflow_run_acceptance_tests` 生成 Core 指定写入的证据；不要手写“已测试”来替代结果文件。本地 hook 拒绝 Agent 文件工具与 shell 访问 `control.db` 及 Devflow 数据目录 `projects/`、拒绝写入 canonical 验收结果文件，并默认拒绝访问 `.devflow/runs/` 运行工件，仅白名单放行 `result.json`（Read 类读取工具仍可读取 `acceptance-results.json`；trace、截图、网络工件和 `runtime.log` 由用户本地查看）。它是防误用，不构成对同系统用户恶意进程的安全隔离。
 
 ### Core 软门禁模式
 
@@ -151,3 +151,33 @@ npm install -g @guanlin4924/devflow-pi@latest
 - 索引是加速器，不是真相源；过期时回退到 LSP、搜索、源码和测试。
 - 人工 checkpoint 不得在 headless 模式静默通过。
 - semantic correctness 不能靠 prompt 保证，必须由契约、确定性校验、独立审查和可复现测试共同约束。
+## Devflow MCP（阶段 B）
+
+`devflow-pi mcp --client <name>` 通过 stdio 提供四个 feature 级工具：`validate_feature`、`run_feature`、`get_feature_report` 和 `dsl_draft_validate`。Server 只做输入校验、授权、审计和调用包内 Core；不读取或导出 trace、截图等运行工件，也不能确认批准。缺批准的用例仍需在 `/devflow` 面板完成批准。
+
+授权文件位于 `$DEVFLOW_HOME/mcp.json`（默认 `~/.devflow-pi/mcp.json`），例如：
+
+```json
+{
+  "schema_version": 1,
+  "clients": { "claude-code": { "projects": {
+    "/abs/path/to/project": {
+      "features": ["order"],
+      "permissions": ["validate", "run", "report", "dsl_draft"],
+      "environment_profiles": ["local"]
+    }
+  } } }
+}
+```
+
+这里的 `--client` 是声明式身份，用于匹配授权和写入审计，不是密码学认证；stdio 调用方与 Server 是同一台机器上的同一用户。Claude Code 注册：`claude mcp add devflow-acceptance -- devflow-pi mcp --client claude-code`。Codex 在 `config.toml` 中注册：
+
+```toml
+[mcp_servers.devflow-acceptance]
+command = "devflow-pi"
+args = ["mcp", "--client", "codex"]
+```
+
+`run_feature` 是同步调用，默认最多运行 2 小时，可用 `--run-timeout-seconds` 下调；客户端也应把 MCP 请求超时设得足够长，并启用 progress。审计写入 `$DEVFLOW_HOME/mcp-audit/`。批准仍只能在 `/devflow` 面板完成。
+
+Core 在 MCP Server 的进程环境中执行，因此注册 Server 时要把被测环境需要的变量一并传入：HTTP adapter 的基础地址变量（如 `DEVFLOW_TEST_BASE_URL`）和环境 profile 中 `secret_env` 声明的密钥变量；缺失时对应用例会是 failed 或 blocked。`mcp.json` 的 `environment_profiles` 只约束 `devflow_playwright` 绑定引用的 profile；HTTP adapter 的目标地址来自这些环境变量，不受 `mcp.json` 授权约束，应由启动 Server 的人控制。`run_feature` 在有用例未通过时仍返回报告，是否通过以其中的 `gate` 为准。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.95",
+  "version": "0.1.96",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",
@@ -23,6 +23,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
     "@oh-my-pi/pi-coding-agent": "17.2.7",
     "@playwright/test": "1.63.0",
     "@plurnk/plurnk-mimetypes-grammar-cpp": "1.16.1",

package/plugins/devflow-core/extensions/devflow-core.ts

@@ -3781,6 +3781,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     description: [
       "Validate or execute the adapters bound to the frozen TC acceptance suite: command, portable HTTP, and devflow_playwright (the Core-owned Playwright Runtime driven by a pinned DSL).",
       "Actions: validate (bindings and suite), validate_human (manual TCs), run (executes every automated TC and writes the canonical acceptance-results.json; Core is the only writer), validate_results (re-checks recorded results against current approvals and hashes), gc_runs (prunes .devflow/runs/<feature> execution directories per retention rules; dry-run by default, pass write=true to delete; optional retentionDays / unreferencedTtlDays).",
+      "Failure analysis reads only the Core-produced result.json summary; trace files and screenshots are not readable by Agent tools and are for the user to inspect locally with Playwright in a terminal.",
       "devflow_playwright bindings require CURRENT human approvals created with devflow_approval and confirmed by the user in /devflow control: an execution_plan approval per TC (pins the DSL, TC and suite) and an environment_profile approval for the target profile; manual or downgraded TCs need a human_result / mode_override approval. You cannot confirm approvals yourself.",
       "Hard gate: a missing, superseded or expired approval, or a DSL/profile/suite/evidence hash that changed after the approval or the run, makes run and validate_results return ok=false and blocks run-acceptance-tests from completing; there is no soft override and results must never be written by hand.",
     ].join(" "),

package/plugins/devflow-core/runtime/hooks/hook_common.py

@@ -711,6 +711,251 @@ def tool_touches_control_store(event: dict[str, Any], root: Path) -> tuple[bool,
     return False, []
 
 
+# MCP authorization and audit data are user-local security state.  This guard
+# is deliberately narrower than DEVFLOW_HOME: only mcp.json and mcp-audit/
+# are protected, and the decision is independent of soft-gate policy.
+def path_is_mcp_protected(raw: str, cwd: Path) -> bool:
+    candidate = Path(_expand_shell_path(str(raw)))
+    if not candidate.is_absolute():
+        candidate = cwd / candidate
+    lexical = Path(os.path.normpath(str(candidate)))
+    resolved = Path(os.path.realpath(str(candidate)))
+    home = devflow_home()
+    config = home / "mcp.json"
+    audit = home / "mcp-audit"
+    for item in (lexical, resolved):
+        if item == config or _under(item, audit):
+            return True
+    return False
+
+
+def _analyze_mcp_command(command: str, cwd: Path, depth: int = 0) -> bool:
+    tokens = _shell_tokens(command)
+    for segment in _segments(tokens):
+        index = 0
+        while index < len(segment) and (ASSIGNMENT_RE.match(segment[index]) or segment[index] in WRAPPER_PROGRAMS):
+            index += 1
+        if index >= len(segment):
+            continue
+        program = os.path.basename(segment[index]).lower()
+        operands = segment[index + 1:]
+        if program in SHELL_PROGRAMS and depth < 3:
+            for pos, operand in enumerate(operands):
+                if operand.startswith("-") and "c" in operand[1:] and pos + 1 < len(operands):
+                    if _analyze_mcp_command(operands[pos + 1], cwd, depth + 1):
+                        return True
+        ignored: set[int] = set()
+        if program in {"echo", "printf"}:
+            ignored.update(range(len(operands)))
+        elif program in {"rg", "grep", "ag", "ack"}:
+            seen_pattern = False
+            pos = 0
+            while pos < len(operands):
+                operand = operands[pos]
+                if operand in {"-e", "--regexp"} and pos + 1 < len(operands):
+                    ignored.add(pos + 1)
+                    pos += 2
+                    continue
+                if operand.startswith("--regexp=") or (not operand.startswith("-") and not seen_pattern):
+                    ignored.add(pos)
+                    seen_pattern = True
+                pos += 1
+        elif program == "git":
+            for pos, operand in enumerate(operands):
+                if operand in {"-m", "--message"} and pos + 1 < len(operands):
+                    ignored.add(pos + 1)
+        previous = ""
+        for pos, operand in enumerate(operands):
+            if previous in REDIRECT_OPERATORS and path_is_mcp_protected(operand, cwd):
+                return True
+            if pos in ignored:
+                previous = operand
+                continue
+            if operand in REDIRECT_OPERATORS or operand.startswith("-"):
+                previous = operand
+                continue
+            if path_is_mcp_protected(operand, cwd):
+                return True
+            previous = operand
+    return False
+
+
+def tool_touches_mcp_config(event: dict[str, Any], root: Path) -> tuple[bool, list[str]]:
+    cwd = Path(str(event.get("cwd") or root)).expanduser()
+    blocked = [raw for raw in _raw_tool_paths(event) if path_is_mcp_protected(raw, cwd)]
+    if blocked:
+        return True, sorted(dict.fromkeys(blocked))
+    command = command_text(event)
+    if command and _analyze_mcp_command(command, cwd):
+        return True, ["<shell command>"]
+    return False, []
+
+
+# Run artifacts are user-local evidence, not agent-readable source.  Keep this
+# guard separate from the control-store guard: it is always on and its only
+# read exception is the Core-produced result.json summary.
+def _run_root(cwd: Path) -> Path:
+    # macOS commonly exposes /var as a symlink to /private/var; use the
+    # canonical cwd so lexical and realpath checks compare in one namespace.
+    return Path(os.path.realpath(str(cwd))) / ".devflow" / "runs"
+
+
+def _run_relative(raw: str, cwd: Path, anchor: Path | None = None) -> tuple[Path, Path, Path]:
+    # The protected root is anchored at the project root, never at the current
+    # shell cwd, so `cd .devflow && cat runs/...` still resolves into it.
+    expanded = _expand_shell_path(raw)
+    cwd_text = str(cwd)
+    expanded = re.sub(r"\$\{PWD\}|\$PWD\b", cwd_text, expanded)
+    candidate = Path(expanded.replace("\\", "/"))
+    if not candidate.is_absolute():
+        candidate = cwd / candidate
+    lexical = Path(os.path.normpath(str(candidate)))
+    resolved = Path(os.path.realpath(str(candidate)))
+    return lexical, resolved, _run_root(anchor or cwd)
+
+
+def _under_run(path: Path, run_root: Path) -> bool:
+    return _under(path, run_root)
+
+
+def path_is_run_artifact(raw: str, cwd: Path, tool: dict[str, Any] | str) -> bool:
+    """Return whether a tool path enters .devflow/runs.
+
+    ``result.json`` is readable only by pure-read tools.  Glob may list the
+    runs directory itself; every other path, including result.json writes and
+    symlink aliases, remains protected.
+    """
+    lexical, resolved, run_root = _run_relative(raw, cwd)
+    paths = (lexical, resolved)
+    tool_event = tool if isinstance(tool, dict) else {"tool_name": tool}
+    pure_read = is_pure_read_tool(tool_event)
+    name = tool_name(tool_event)
+    for item in paths:
+        if not _under_run(item, run_root):
+            continue
+        relative = item.relative_to(run_root).parts
+        if name == "glob" and len(relative) == 0:
+            continue
+        if pure_read and len(relative) == 3 and relative[-1] == "result.json":
+            continue
+        return True
+    return False
+
+
+RUN_FILE_PROGRAMS = {
+    "cat", "cp", "mv", "rm", "tee", "touch", "truncate", "install", "rsync", "scp",
+    "tar", "unzip", "zip", "base64", "xxd", "strings", "od", "hexdump", "file", "stat",
+    "head", "tail", "less", "more", "sed", "awk", "nl", "bat", "rg", "grep", "find", "fd",
+    "ls", "tree", "du", "open", "sha256sum", "shasum", "md5sum", "md5", "cksum", "chmod",
+    "chown", "unlink", "shred", "dd", "gzip", "gunzip", "bzip2", "xz", "python", "python3",
+    "node", "bun", "deno", "ruby", "perl", "php", "lua",
+}
+
+
+def _token_is_run_target(token: str, cwd: Path, anchor: Path | None = None) -> bool:
+    if not token or token in REDIRECT_OPERATORS or token.startswith("-"):
+        return False
+    lexical, resolved, run_root = _run_relative(token, cwd, anchor)
+    return _under_run(lexical, run_root) or _under_run(resolved, run_root)
+
+
+def _analyze_run_command(command: str, cwd: Path, depth: int = 0, anchor: Path | None = None) -> bool:
+    anchor = anchor or cwd
+    tokens = _shell_tokens(command)
+    current_cwd = cwd
+    for segment in _segments(tokens):
+        index = 0
+        while index < len(segment) and (ASSIGNMENT_RE.match(segment[index]) or segment[index] in WRAPPER_PROGRAMS):
+            index += 1
+        if index >= len(segment):
+            continue
+        program = os.path.basename(segment[index]).lower()
+        operands = segment[index + 1:]
+        if program in SHELL_PROGRAMS and depth < 3:
+            for pos, operand in enumerate(operands):
+                if operand.startswith("-") and "c" in operand[1:] and pos + 1 < len(operands):
+                    if _analyze_run_command(operands[pos + 1], current_cwd, depth + 1, anchor):
+                        return True
+        if program == "cd" and operands:
+            if _token_is_run_target(operands[-1], current_cwd, anchor):
+                return True
+            candidate = Path(_expand_shell_path(operands[-1]))
+            current_cwd = candidate if candidate.is_absolute() else current_cwd / candidate
+            current_cwd = Path(os.path.normpath(str(current_cwd)))
+            continue
+        # Any shell redirection is a real filesystem access, even when the
+        # command producing the bytes is otherwise harmless (e.g. echo).
+        previous = ""
+        for operand in operands:
+            if previous in REDIRECT_OPERATORS and _token_is_run_target(operand, current_cwd, anchor):
+                return True
+            previous = operand
+        # Inline interpreters can open arbitrary files.  Reject the source
+        # text conservatively whenever it names the protected tree.
+        if program in {"python", "python3", "node", "bun", "deno", "ruby", "perl", "php"}:
+            for pos, operand in enumerate(operands):
+                if operand in {"-c", "-e", "--eval"} and pos + 1 < len(operands):
+                    if ".devflow/runs" in operands[pos + 1]:
+                        return True
+                if any(operand.startswith(prefix) for prefix in ("--eval=", "-e=")) and ".devflow/runs" in operand.split("=", 1)[1]:
+                    return True
+
+        # Every non-option operand is a potential filesystem target, regardless
+        # of the executable.  Only documented text positions are exempt.
+        ignored: set[int] = set()
+        if program in {"echo", "printf"}:
+            ignored.update(range(len(operands)))
+        elif program in {"rg", "grep", "ag", "ack"}:
+            seen_pattern = False
+            pos = 0
+            while pos < len(operands):
+                operand = operands[pos]
+                if operand in {"-e", "--regexp"} and pos + 1 < len(operands):
+                    ignored.add(pos + 1)
+                    pos += 2
+                    continue
+                if operand.startswith("--regexp="):
+                    ignored.add(pos)
+                elif not operand.startswith("-") and not seen_pattern:
+                    ignored.add(pos)
+                    seen_pattern = True
+                pos += 1
+        elif program == "git":
+            for pos, operand in enumerate(operands):
+                if operand in {"-m", "--message"} and pos + 1 < len(operands):
+                    ignored.add(pos + 1)
+                elif operand.startswith("--message=") or operand.startswith("-m="):
+                    ignored.add(pos)
+
+        for pos, operand in enumerate(operands):
+            if pos in ignored or operand in REDIRECT_OPERATORS:
+                continue
+            target = operand
+            if operand.startswith("--") and "=" in operand:
+                target = operand.split("=", 1)[1]
+            if not target or target.startswith("-"):
+                continue
+            if _token_is_run_target(target, current_cwd, anchor):
+                return True
+    return False
+
+
+def command_touches_run_artifacts(command: str, cwd: Path | None = None) -> bool:
+    """Deny shell access to real run-artifact paths, not textual mentions."""
+    return _analyze_run_command(command, cwd or Path.cwd())
+
+
+def tool_touches_run_artifacts(event: dict[str, Any], root: Path) -> tuple[bool, list[str]]:
+    cwd = Path(str(event.get("cwd") or root)).expanduser()
+    blocked = [raw for raw in _raw_tool_paths(event) if path_is_run_artifact(raw, cwd, event)]
+    if blocked:
+        return True, sorted(dict.fromkeys(blocked))
+    command = command_text(event)
+    if command and command_touches_run_artifacts(command, cwd):
+        return True, ["<shell command>"]
+    return False, []
+
+
 def evidence_observed(event: dict[str, Any], root: Path, artifacts: list[str]) -> list[str]:
     name = tool_name(event)
     if not (any(marker in name for marker in READ_TOOL_MARKERS) or is_command_tool(event)):

package/plugins/devflow-core/runtime/hooks/index_gate.py

@@ -15,8 +15,10 @@ from hook_common import (
     read_event,
     record_prechange_fingerprints,
     required_evidence,
+    tool_touches_mcp_config,
     tool_requests_protected_source,
     tool_touches_control_store,
+    tool_touches_run_artifacts,
 )
 
 
@@ -40,6 +42,13 @@ def main() -> int:
     event = read_event()
     root = project_root(event)
     # Hard protection, evaluated before any soft/strict policy handling.
+    mcp_blocked, mcp_paths = tool_touches_mcp_config(event, root)
+    if mcp_blocked:
+        return deny(
+            "MCP_CONFIG_PROTECTED: $DEVFLOW_HOME/mcp.json and $DEVFLOW_HOME/mcp-audit/ are reserved for "
+            "Devflow MCP authorization and audit records; ordinary agent file and shell access is denied "
+            "regardless of DEVFLOW_SOFT_GATES. Blocked target: " + ", ".join(mcp_paths) + "."
+        )
     control_blocked, control_paths = tool_touches_control_store(event, root)
     if control_blocked:
         return deny(
@@ -49,6 +58,15 @@ def main() -> int:
             "Canonical acceptance-results*.json may be read with the Read/Grep file tools. "
             f"Use devflow_approval(action=\"propose\"|\"list\") for approvals. Blocked target: {', '.join(control_paths)}."
         )
+    run_blocked, run_paths = tool_touches_run_artifacts(event, root)
+    if run_blocked:
+        return deny(
+            "RUN_ARTIFACTS_PROTECTED: .devflow/runs/ contains trace, screenshots, runtime logs and other "
+            "user-local evidence that Agent tools may not read, write or access through bash. Trace and screenshots "
+            "are for the user to inspect locally with Playwright in a terminal; Agent failure analysis must read "
+            "the Core-produced result.json summary instead. Only pure-read access to a feature execution's "
+            "result.json is allowed. Blocked target: " + ", ".join(run_paths) + "."
+        )
     policy = load_policy(root)
     session_id = ensure_session(root, event)
     required = required_evidence(root, policy)

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/acceptance_test_runner.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import argparse
+import contextlib
+import fcntl
 import hashlib
 import json
 import os
@@ -35,6 +37,8 @@ ALLOWED_BINDING_MODES = {"automated": ("automated", "manual", "blocked"), "manua
 RESULT_ORIGINS = {"command": "project_test_command", "http": "core_http_adapter", playwright_adapter.ADAPTER_KIND: playwright_adapter.RESULT_ORIGIN}
 DEFAULT_RUN_RETENTION_DAYS = 30
 DEFAULT_UNREFERENCED_RUN_TTL_DAYS = 7
+MAX_REPORT_ERRORS = 50
+MAX_REPORT_ERROR_CHARS = 500
 
 
 def utc_now() -> str:
@@ -427,7 +431,36 @@ def run_command_case(root: Path, argv: list[str]) -> tuple[int, str]:
         return 127, f"command could not start: {error}"
 
 
+@contextlib.contextmanager
+def acceptance_run_lock(root: Path, feature: str):
+    """Hold the feature write lock for the complete run, including result writes."""
+    lock_path = root / ".devflow/planning/test-runs" / feature / ".run.lock"
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    handle = lock_path.open("a+")
+    try:
+        try:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            yield False
+            return
+        yield True
+    finally:
+        try:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        finally:
+            handle.close()
+
+
 def run(root: Path, feature: str, write: bool) -> dict[str, Any]:
+    if write:
+        with acceptance_run_lock(root, feature) as acquired:
+            if not acquired:
+                return {"ok": False, "feature": feature, "reason": "acceptance_run_in_progress", "errors": []}
+            return _run_locked(root, feature, write)
+    return _run_locked(root, feature, write)
+
+
+def _run_locked(root: Path, feature: str, write: bool) -> dict[str, Any]:
     validation, suite, bindings = validate(root, feature)
     if not validation["ok"]:
         return validation
@@ -527,6 +560,52 @@ def run(root: Path, feature: str, write: bool) -> dict[str, Any]:
             "errors": [] if all_passed else ["one or more frozen TC cases failed or are blocked"]}
 
 
+def _report_error(value: Any) -> dict[str, Any]:
+    text = str(value)
+    # Reports are safe summaries: do not expose project or run locations from gate diagnostics.
+    text = re.sub(r"(?:[A-Za-z]:)?[^\s,;()]+(?:/|\\)[^\s,;()]+", "<path>", text)
+    text = re.sub(r"(?:^|\s)(?:/|~/?|\.\.?/)[^\s,;()]+", " <path>", text)
+    truncated = len(text) > MAX_REPORT_ERROR_CHARS
+    return {"message": text[:MAX_REPORT_ERROR_CHARS], "truncated": True} if truncated else {"message": text, "truncated": False}
+
+
+def _result_summary(entry: dict[str, Any]) -> dict[str, Any]:
+    approval = entry.get("dsl_approval")
+    if isinstance(approval, dict):
+        approval = "approved" if approval.get("status") == "approved" else "none"
+    elif approval not in {"approved", "none"}:
+        approval = None
+    return {key: entry.get(key) for key in (
+        "tc_id", "status", "mode", "adapter_kind", "execution_surface", "error_code"
+    )} | {"dsl_approval": approval, "legacy_unclassified": bool(entry.get("legacy_unclassified")),
+        "downgrade": entry.get("downgrade")}
+
+
+def report(root: Path, feature: str) -> dict[str, Any]:
+    _, _, result_path = paths(root, feature)
+    if not result_path.is_file():
+        return {"ok": False, "feature": feature, "reason": "acceptance_results_missing"}
+    try:
+        payload = json.loads(result_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {"ok": False, "feature": feature, "reason": "acceptance_results_missing"}
+    if not isinstance(payload, dict) or not isinstance(payload.get("results"), list):
+        return {"ok": False, "feature": feature, "reason": "acceptance_results_missing"}
+    entries = [entry for entry in payload["results"] if isinstance(entry, dict)]
+    statuses = {status: sum(1 for entry in entries if entry.get("status") == status)
+                for status in ("passed", "failed", "blocked")}
+    counts = {"passed": statuses["passed"], "failed": statuses["failed"], "blocked": statuses["blocked"],
+              "legacy_unclassified": sum(bool(entry.get("legacy_unclassified")) for entry in entries),
+              "downgraded": sum(bool(entry.get("downgrade")) for entry in entries)}
+    gate = validate_results(root, feature)
+    raw_errors = gate.get("errors", []) if isinstance(gate, dict) else []
+    return {"ok": True, "feature": feature,
+            "gate": {"ok": bool(gate.get("ok")), "reason": gate.get("reason"),
+                     "errors": [_report_error(error) for error in raw_errors[:MAX_REPORT_ERRORS]]},
+            "executed_at": payload.get("executed_at"), "test_suite": payload.get("test_suite"),
+            "counts": counts, "results": [_result_summary(entry) for entry in entries]}
+
+
 def run_evidence_expired(root: Path, feature: str, today: date | None = None) -> bool:
     """True only once release-closeout completed and the post-closeout retention window has elapsed.
 
@@ -764,7 +843,7 @@ def gc_runs(root: Path, feature: str, write: bool, retention_days: int = DEFAULT
 
 def main() -> int:
     parser = argparse.ArgumentParser()
-    parser.add_argument("action", choices=("validate", "validate-human", "run", "validate-results", "gc-runs"))
+    parser.add_argument("action", choices=("validate", "validate-human", "run", "validate-results", "report", "gc-runs"))
     parser.add_argument("--feature", required=True)
     parser.add_argument("--write", action="store_true")
     parser.add_argument("--retention-days", type=int, default=DEFAULT_RUN_RETENTION_DAYS)
@@ -785,6 +864,8 @@ def main() -> int:
         result = run(root, args.feature, args.write) if args.write else {"ok": False, "errors": ["--write is required for run"]}
     elif args.action == "gc-runs":
         result = gc_runs(root, args.feature, args.write, max(args.retention_days, 0), max(args.unreferenced_ttl_days, 0))
+    elif args.action == "report":
+        result = report(root, args.feature)
     else:
         result = validate_results(root, args.feature)
     print(json.dumps(result, ensure_ascii=False, indent=2))

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/dsl_draft.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Validate an unapproved DSL draft without making it executable."""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from dsl_coverage import check as dsl_coverage_check
+from dsl_v1 import validate as validate_dsl
+
+
+MAX_INPUT_BYTES = 2 * 1024 * 1024
+
+
+def main() -> int:
+    raw = sys.stdin.buffer.read(MAX_INPUT_BYTES + 1)
+    if len(raw) > MAX_INPUT_BYTES:
+        result = {"ok": False, "errors": ["input exceeds 2 MiB"], "warnings": [],
+                  "eligible_for_execution": False,
+                  "note": "Draft validation never grants execution eligibility."}
+    else:
+        parse_error: str | None = None
+        try:
+            payload = json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            payload = None
+            parse_error = f"input must be UTF-8 JSON: {error}"
+        errors: list[str] = []
+        if payload is None:
+            errors.append(parse_error or "input must be a JSON object")
+        elif not isinstance(payload, dict):
+            errors.append("input must be an object")
+        else:
+            dsl = payload.get("dsl")
+            tc_data = payload.get("tc_data")
+            if not isinstance(dsl, dict):
+                errors.append("dsl must be an object")
+            else:
+                errors.extend(f"DSL is invalid: {error}" for error in validate_dsl(dsl))
+            if not isinstance(tc_data, dict):
+                errors.append("tc_data must be an object")
+            elif isinstance(dsl, dict) and not validate_dsl(dsl):
+                errors.extend(f"DSL coverage: {error}" for error in dsl_coverage_check(tc_data, dsl))
+        result = {"ok": not errors, "errors": errors, "warnings": [],
+                  "eligible_for_execution": False,
+                  "note": "Draft validation never grants execution eligibility."}
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugins/devflow-intel/extensions/devflow-intel.ts

@@ -76,7 +76,7 @@ export default function devflowIntel(pi: ExtensionAPI) {
   pi.registerTool({
     name: "devflow_code_index",
     label: "Devflow Code Index",
-    description: "Scan, validate, audit, or query the deterministic project code index.",
+    description: "Query the project code index. Choose query/relations/impact for known symbols and structural relationships; search-content only for literal source text, paths, or config values; resolve-domain only when an imported domain mapping exists. scan/validate/audit build and check the index. If the index is unavailable, stale, unsupported, or cannot answer the question, use bounded source search and report degraded index coverage.",
     parameters: z.object({
       action: z.enum(["scan", "validate", "audit", "query", "relations", "impact", "search-content", "resolve-domain", "query-plan", "domain-import"]),
       term: z.string().optional(),

package/plugins/devflow-quality/skills/workflow-human-acceptance/SKILL.md

@@ -17,7 +17,7 @@ description: "Use after code review to execute frozen manual TC cases, capture h
 
 1. 确认 `code-review` 已完成，测试套件已由 CP-3 冻结。
 2. 只筛选 `automation_mode: manual` 的 TC；`automated` 由后续 Core runner 执行，`blocked` 保持阻塞。
-3. 人工按冻结步骤执行，逐条收集实际结果和项目内证据文件；Agent 不得代填 `passed|failed|blocked` 结论。
+3. 人工按冻结步骤执行，逐条收集实际结果和项目内证据文件；Agent 不得代填 `passed|failed|blocked` 结论。失败分析只依据 `result.json` 与 `acceptance-results.json`；`.devflow/runs/**` 下的 trace、截图、网络工件和 `runtime.log` 由用户在本地查看，Agent 不得读取（hook 会拒绝）。
 4. 本步骤不生成自动化用例，也不改变自动化 TC 的模式；需要降级为 `manual` 的自动化 TC 必须先有有效的 `mode_override` approval，随后才按人工 TC 处理。
 5. 对每个 manual TC 调用 `devflow_approval(action="propose", feature="...", kind="human_result", items=[{"subject":"TC-xxxx","evidence_files":[...]}])`。Agent 只能提交证据，不得提交 status、actual_result 或 pins。
 6. 用户在 `/devflow` → “待审批”中逐 TC 查看 oracle、步骤和证据，自行选择 `passed|failed|blocked` 并填写实际结果；只有该 UI 确认产生的 `human_result` approval 才是最终人工结果。
@@ -49,6 +49,8 @@ description: "Use after code review to execute frozen manual TC cases, capture h
 
 草稿不得作为版本通过证据。每个 manual TC 的最终 verdict 和 actual_result 只从 control.db 中仍有效的 `human_result` approval 读取；`passed` 必须固定至少一个项目内证据文件及其哈希。
 
+人工 TC 的项目内证据文件不属于 `.devflow/runs/**` Runtime 运行工件；Agent 只登记其路径并提交审批，不据其内容替用户下结论。
+
 ## 开发者交接
 
 写入 `.devflow/planning/test-runs/{feature}/developer-handoff.md`，至少包含：

package/plugins/devflow-quality/skills/workflow-release-closeout/SKILL.md

@@ -31,7 +31,7 @@ description: "在冻结需求验收测试全部通过后，执行 Devflow 自有
 
 ## 收口动作
 
-1. 调用 `devflow_run_acceptance_tests(action="validate_results", feature=...)`，让 Core 重新校验 `acceptance-results.json`（suite pins、`execution_surface` 兼容、当前仍有效的 `execution_plan`/`environment_profile`/`human_result`/`mode_override` 批准、运行目录与工件哈希）；运行后 DSL 或 profile 被修改、批准被替换，都会使已记录结果失效，需要回到 `run-acceptance-tests` 重跑；不通过则停止收口。通过后读取该文件（读取即可，不得写入），计算通过/失败/阻塞数量，并展示 `legacy_unclassified`、有效降级记录和逐 TC `dsl_approval`。任何 `dsl_approval: none` 必须对应 blocked；若其被标为 passed、结果未全 passed 或存在未批准降级，立即拒绝收口。人工 TC 的 passed 只来自已确认的 `human_result` approval，`human-acceptance-results.json` 草稿不算证据。
+1. 调用 `devflow_run_acceptance_tests(action="validate_results", feature=...)`，让 Core 重新校验 `acceptance-results.json`（suite pins、`execution_surface` 兼容、当前仍有效的 `execution_plan`/`environment_profile`/`human_result`/`mode_override` 批准、运行目录与工件哈希）；运行后 DSL 或 profile 被修改、批准被替换，都会使已记录结果失效，需要回到 `run-acceptance-tests` 重跑；不通过则停止收口。通过后读取该文件（读取即可，不得写入），计算通过/失败/阻塞数量，并展示 `legacy_unclassified`、有效降级记录和逐 TC `dsl_approval`。任何 `dsl_approval: none` 必须对应 blocked；若其被标为 passed、结果未全 passed 或存在未批准降级，立即拒绝收口。人工 TC 的 passed 只来自已确认的 `human_result` approval，`human-acceptance-results.json` 草稿不算证据。失败分析和证据读取只依据 `result.json` 与 `acceptance-results.json`；Agent 不得读取 trace、截图、网络工件或 `runtime.log`，这些由用户本地查看（hook 会拒绝 Agent 读取）。
 2. 更新 `.devflow/planning/navigation/INDEX.md`，记录本次 code-index revision 和验收结果 fingerprint。
 3. 在 `.devflow/planning/milestones/` 写入本版本的 ROADMAP、需求覆盖、测试结果、变更清单和已接受风险摘要。
 4. 更新 `.devflow/planning/PROJECT.md` 的当前版本与下一步目标。

package/plugins/devflow-quality/skills/workflow-run-acceptance-tests/SKILL.md

@@ -48,9 +48,11 @@ description: "Execute the frozen TC acceptance suite after code review. Use the
 7. 调用 `devflow_run_acceptance_tests(action="run", feature=...)`。该 Core 工具执行 automated TC（`devflow_playwright` 在净化环境和独立运行目录中执行，并校验 Runtime 完整性与结果 nonce），合并已校验的 manual TC 结果，并记录命令/证据哈希、退出码、`dsl_approval`、`execution_surface`、`legacy_unclassified` 和降级记录。
 8. 失败、未执行或 blocked 的 TC 只能报告为 `blocked`/`failed`，不得进入版本收口。验收未全 passed 是硬门禁：即使默认 soft 模式，`run-acceptance-tests` 完成和 `release-closeout` 确认时 Core 也会重新校验结果并以 `acceptance_results_not_passed` 拒绝。可用 `devflow_run_acceptance_tests(action="validate_results", feature=...)` 预先检查。该校验会对照当前批准、DSL/profile 哈希与运行目录重新验证每条记录：运行后修改 DSL 或 profile、或批准被新的批准替换，都会使已记录的 passed 失效，必须重跑。
 
+失败分析和证据读取只依据 Runtime 的 `result.json` 与 Core 的 `acceptance-results.json`。Agent 不得读取 trace、截图、网络工件或 `runtime.log`；这些工件由用户在本地查看（hook 会拒绝 Agent 读取）。
+
 ## 输出
 
 - `.devflow/planning/features/{feature}/acceptance-test-bindings.json`
 - `.devflow/planning/test-runs/{feature}/acceptance-results.json`
 
-`acceptance-results.json` 是 Core 指定写入的本地执行缓存（Agent 不得写入，可读取用于展示）；Markdown 结论不能替代它，收口以 Core 对它的重新校验（`validate_results`）为准。Hook 会拦截常规 Write/Edit/Bash 误写，但不是对同一系统用户下任意进程的安全隔离；未配置外部受保护信任根时，不得宣称结果在密码学意义上不可伪造。
+`acceptance-results.json` 是 Core 指定写入的本地执行缓存（Agent 不得写入，可读取用于展示）；Markdown 结论不能替代它，收口以 Core 对它的重新校验（`validate_results`）为准。失败分析和证据读取仍只使用 `result.json` 与 `acceptance-results.json`；trace、截图、网络工件和 `runtime.log` 由用户本地查看，Agent 不得读取（hook 会拒绝）。Hook 会拦截常规 Write/Edit/Bash 误写，但不是对同一系统用户下任意进程的安全隔离；未配置外部受保护信任根时，不得宣称结果在密码学意义上不可伪造。

package/src/cli.ts

@@ -16,6 +16,7 @@ function usage(): string {
     "  devflow-pi init [project] [--scan]",
     "  devflow-pi migrate [project] --confirm-active",
     "  devflow-pi doctor [project]",
+    "  devflow-pi mcp --client <name> [--run-timeout-seconds <seconds>]",
     "  devflow-pi usage [project]",
     "  devflow-pi [project] [--resume [session-id]] [--prompt <text>] [--mcp] [--yolo]",
   ].join("\n");
@@ -80,6 +81,15 @@ async function main(): Promise<void> {
     console.log(JSON.stringify({ status: "migrated", root, migrated }, null, 2));
     return;
   }
+  if (command === "mcp") {
+    const client = option(args, "--client");
+    if (!client) throw new Error("devflow-pi mcp requires --client <name>");
+    const timeout = option(args, "--run-timeout-seconds");
+    if (timeout !== undefined && (!Number.isFinite(Number(timeout)) || Number(timeout) <= 0 || Number(timeout) > 7200)) throw new Error("--run-timeout-seconds must be between 1 and 7200");
+    const { startMcpServer } = await import("./mcp/server.ts");
+    await startMcpServer({ client, runTimeoutSeconds: timeout === undefined ? undefined : Number(timeout) });
+    return;
+  }
   const positionalProject = command && !["doctor", "usage"].includes(command) && !command.startsWith("-") ? command : undefined;
   const requestedProject = ["doctor", "usage"].includes(command || "") ? args[1] : positionalProject;
   const root = await resolveProjectRoot(process.cwd(), { explicit: requestedProject });

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.95";
+export const PRODUCT_VERSION = "0.1.96";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";
 

package/src/doctor.ts

@@ -316,6 +316,15 @@ export async function runHostDoctor(project: ProjectContext, options: DoctorOpti
   add("agent-dir", true, devflowAgentDir());
   add("session-isolation", true, projectSessionDir(project.manifest.projectId));
   add("devflow-home", true, devflowHome());
+  const mcpConfig = path.join(devflowHome(), "mcp.json");
+  if (!(await exists(mcpConfig))) add("mcp", true, "MCP 未配置");
+  else {
+    try {
+      const config = JSON.parse(await readFile(mcpConfig, "utf8")) as Record<string, unknown>;
+      const valid = config.schema_version === 1 && config.clients !== null && typeof config.clients === "object" && !Array.isArray(config.clients);
+      add("mcp", valid, valid ? `${mcpConfig} (schema_version 1)` : `${mcpConfig}: schema_version must be 1 and clients must be an object`);
+    } catch (error) { add("mcp", false, `${mcpConfig}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`); }
+  }
   return { ok: checks.every(check => check.ok), checks };
 }
 

package/src/mcp/auth.ts

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+
+import { normalizeDevflowHome } from "../paths.ts";
+import type { McpToolName } from "./types.ts";
+
+export const FEATURE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export const TOOLS = ["validate_feature", "run_feature", "get_feature_report", "dsl_draft_validate"] as const;
+export const MAX_DSL_BYTES = 2 * 1024 * 1024;
+const PERMISSIONS = new Set(["validate", "report", "run", "dsl_draft"]);
+
+export type ProjectGrant = { features: string[] | "*"; permissions: string[]; environment_profiles: string[] };
+export type McpConfig = { schema_version: 1; clients: Record<string, { projects: Record<string, ProjectGrant> }> };
+
+export class McpError extends Error {
+  constructor(public readonly code: string, message: string) { super(message); }
+}
+
+function invalidConfig(message: string): never {
+  throw new McpError("mcp_permission_denied", `invalid mcp.json: ${message}`);
+}
+
+function stringArray(value: unknown, label: string): string[] {
+  if (!Array.isArray(value) || value.some(item => typeof item !== "string")) invalidConfig(`${label} must be an array of strings`);
+  return value as string[];
+}
+
+function validateGrant(value: unknown, label: string): ProjectGrant {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalidConfig(`${label} must be an object`);
+  const grant = value as Record<string, unknown>;
+  const features = grant.features === "*" ? "*" : stringArray(grant.features, `${label}.features`);
+  const permissions = stringArray(grant.permissions, `${label}.permissions`);
+  if (permissions.some(permission => !PERMISSIONS.has(permission))) invalidConfig(`${label}.permissions contains an unsupported permission`);
+  const environmentProfiles = grant.environment_profiles === undefined ? [] : stringArray(grant.environment_profiles, `${label}.environment_profiles`);
+  return { features, permissions, environment_profiles: environmentProfiles };
+}
+
+function validateConfig(value: unknown): McpConfig {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalidConfig("root must be an object");
+  const root = value as Record<string, unknown>;
+  if (root.schema_version !== 1) invalidConfig("schema_version must be 1");
+  if (!root.clients || typeof root.clients !== "object" || Array.isArray(root.clients)) invalidConfig("clients must be an object");
+  const clients: McpConfig["clients"] = {};
+  for (const [clientName, clientValue] of Object.entries(root.clients as Record<string, unknown>)) {
+    if (!clientValue || typeof clientValue !== "object" || Array.isArray(clientValue)) invalidConfig(`clients.${clientName} must be an object`);
+    const projectsValue = (clientValue as Record<string, unknown>).projects;
+    if (!projectsValue || typeof projectsValue !== "object" || Array.isArray(projectsValue)) invalidConfig(`clients.${clientName}.projects must be an object`);
+    const projects: Record<string, ProjectGrant> = {};
+    for (const [project, grant] of Object.entries(projectsValue as Record<string, unknown>)) {
+      if (!path.isAbsolute(project)) invalidConfig(`project key must be absolute: ${project}`);
+      projects[project] = validateGrant(grant, `clients.${clientName}.projects.${project}`);
+    }
+    clients[clientName] = { projects };
+  }
+  return { schema_version: 1, clients };
+}
+
+export async function loadAuthorization(client: string, home = normalizeDevflowHome(process.env.DEVFLOW_HOME)): Promise<McpConfig> {
+  const file = path.join(home, "mcp.json");
+  let value: unknown;
+  try {
+    value = JSON.parse(await readFile(file, "utf8"));
+  } catch (error) {
+    throw new McpError("mcp_permission_denied", `MCP authorization is unavailable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const config = validateConfig(value);
+  if (!Object.prototype.hasOwnProperty.call(config.clients, client)) throw new McpError("mcp_permission_denied", `unknown MCP client: ${client}`);
+  return config;
+}
+
+function permissionFor(tool: McpToolName): string {
+  if (tool === "dsl_draft_validate") return "dsl_draft";
+  if (tool === "get_feature_report") return "report";
+  if (tool === "validate_feature") return "validate";
+  return "run";
+}
+
+export async function authorize(config: McpConfig, client: string, tool: McpToolName, project: unknown, feature?: unknown): Promise<{ project: string; grant: ProjectGrant }> {
+  if (typeof project !== "string" || !path.isAbsolute(project)) throw new McpError("mcp_input_invalid", "project must be an absolute path");
+  let resolved: string;
+  try { resolved = await realpath(project); } catch { throw new McpError("mcp_project_not_allowed", "project does not exist"); }
+  const grants = config.clients[client]?.projects ?? {};
+  let grant: ProjectGrant | undefined;
+  for (const [key, candidate] of Object.entries(grants)) {
+    try {
+      if (await realpath(key) === resolved) { grant = candidate; break; }
+    } catch {
+      // A missing configured project cannot authorize a request.
+    }
+  }
+  if (!grant) throw new McpError("mcp_project_not_allowed", "project is not authorized");
+  if (tool !== "dsl_draft_validate") {
+    if (typeof feature !== "string" || !FEATURE_RE.test(feature)) throw new McpError("mcp_input_invalid", "feature is invalid");
+    if (grant.features !== "*" && !grant.features.includes(feature)) throw new McpError("mcp_feature_not_allowed", "feature is not authorized");
+  }
+  if (!grant.permissions.includes(permissionFor(tool))) throw new McpError("mcp_permission_denied", "permission is not authorized");
+  return { project: resolved, grant };
+}
+
+export function requestHash(value: unknown): string {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}

package/src/mcp/core.ts

@@ -0,0 +1,102 @@
+import path from "node:path";
+
+import { packageRoot } from "../paths.ts";
+import type { CoreRunner, CoreResult } from "./types.ts";
+
+export const runnerScript = path.join(packageRoot(), "plugins/devflow-core/skills/workflow-orchestrator/scripts/acceptance_test_runner.py");
+export const dslScript = path.join(packageRoot(), "plugins/devflow-core/skills/workflow-orchestrator/scripts/dsl_draft.py");
+
+const DEFAULT_TIMEOUT_MS = 7_200_000;
+const TERMINATION_GRACE_MS = 5_000;
+const PROGRESS_INTERVAL_MS = 10_000;
+
+function terminateProcessGroup(pid: number | undefined, signal: "SIGTERM" | "SIGKILL"): void {
+  if (pid === undefined) return;
+  try { process.kill(-pid, signal); } catch { /* process group may already be gone */ }
+}
+
+async function settleText(value: Promise<string>, timeoutMs: number): Promise<string> {
+  return Promise.race([
+    value,
+    new Promise<string>(resolve => setTimeout(() => resolve(""), timeoutMs)),
+  ]);
+}
+
+export const runPython: CoreRunner = async (script, args, cwd, stdin, timeoutMs = DEFAULT_TIMEOUT_MS, onProgress) => {
+  // -E/-s ignore PYTHON* variables and user site-packages.  Not -I: isolated mode also drops the
+  // script directory from sys.path, and the Core scripts import their sibling modules.
+  const child = Bun.spawn(["python3", "-E", "-s", script, ...args], {
+    cwd,
+    detached: true,
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const stdoutPromise = new Response(child.stdout).text();
+  const stderrPromise = new Response(child.stderr).text();
+  if (stdin !== undefined) child.stdin.write(stdin);
+  child.stdin.end();
+  const progressTimer = onProgress === undefined ? undefined : setInterval(() => {
+    void Promise.resolve(onProgress()).catch(() => undefined);
+  }, PROGRESS_INTERVAL_MS);
+
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  let timedOut = false;
+  const timeoutPromise = new Promise<"timeout">(resolve => {
+    timeoutHandle = setTimeout(() => resolve("timeout"), timeoutMs);
+  });
+  const exitPromise = child.exited.then(exitCode => ({ exitCode }));
+  const winner = await Promise.race([exitPromise, timeoutPromise]);
+  if (winner === "timeout") {
+    timedOut = true;
+    terminateProcessGroup(child.pid, "SIGTERM");
+    try { child.kill("SIGTERM"); } catch { /* already exited */ }
+    await new Promise(resolve => setTimeout(resolve, TERMINATION_GRACE_MS));
+    terminateProcessGroup(child.pid, "SIGKILL");
+    try { child.kill("SIGKILL"); } catch { /* already exited */ }
+    if (progressTimer !== undefined) clearInterval(progressTimer);
+    clearTimeout(timeoutHandle);
+    return {
+      exitCode: null,
+      stdout: await settleText(stdoutPromise, 100),
+      stderr: await settleText(stderrPromise, 100),
+      timedOut,
+    };
+  }
+
+  if (progressTimer !== undefined) clearInterval(progressTimer);
+  clearTimeout(timeoutHandle);
+  return {
+    exitCode: winner.exitCode,
+    stdout: await stdoutPromise,
+    stderr: await stderrPromise,
+    timedOut,
+  };
+};
+
+export async function invokeCore(
+  runner: CoreRunner,
+  action: string,
+  project: string,
+  feature: string,
+  timeoutMs?: number,
+  onProgress?: () => void | Promise<void>,
+): Promise<CoreResult> {
+  const result = await runner(
+    runnerScript,
+    [action, "--feature", feature, "--json", ...(action === "run" ? ["--write"] : [])],
+    project,
+    undefined,
+    timeoutMs,
+    onProgress,
+  );
+  if (result.timedOut) return { ok: false, reason: "mcp_run_timeout", error_code: "mcp_run_timeout" };
+  try {
+    return JSON.parse(result.stdout) as CoreResult;
+  } catch {
+    // Keep the tail of the diagnostic (where Python tracebacks end), without project paths.
+    const detail = (result.stderr || result.stdout || `Core exited ${result.exitCode}`).slice(-1000)
+      .replace(/(?:[A-Za-z]:)?[^\s,;()"']+[\/][^\s,;()"']+/g, "<path>");
+    return { ok: false, reason: "core_failed", error_code: "core_failed", errors: [detail] };
+  }
+}

package/src/mcp/server.ts

@@ -0,0 +1,193 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { devflowHome } from "../paths.ts";
+import { authorize, FEATURE_RE, loadAuthorization, MAX_DSL_BYTES, McpError, requestHash } from "./auth.ts";
+import { dslScript, invokeCore, runPython } from "./core.ts";
+import type { CoreRunner, McpServerOptions, McpToolName } from "./types.ts";
+
+const RESPONSE_LIMIT = 64 * 1024;
+
+type ProgressCallback = () => void | Promise<void>;
+
+function bounded(value: unknown): string {
+  const text = JSON.stringify(value);
+  if (text.length <= RESPONSE_LIMIT) return text;
+  return JSON.stringify({
+    ok: false,
+    reason: "response_truncated",
+    truncated: true,
+    output: text.slice(0, RESPONSE_LIMIT - 80),
+  });
+}
+
+function toolResult(value: unknown) {
+  return {
+    content: [{ type: "text" as const, text: bounded(value) }],
+    isError: Boolean(value && typeof value === "object" && (value as { ok?: unknown }).ok === false),
+  };
+}
+
+async function audit(home: string, row: Record<string, unknown>): Promise<void> {
+  const directory = path.join(home, "mcp-audit");
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const file = path.join(directory, `${new Date().toISOString().slice(0, 7)}.jsonl`);
+  await appendFile(file, `${JSON.stringify(row)}\n`, { mode: 0o600 });
+}
+
+function collectEnvironmentProfiles(value: unknown): Set<string> {
+  const profiles = new Set<string>();
+  const visit = (current: unknown): void => {
+    if (Array.isArray(current)) {
+      current.forEach(visit);
+      return;
+    }
+    if (!current || typeof current !== "object") return;
+    const record = current as Record<string, unknown>;
+    if ((record.kind === "devflow_playwright" || record.adapter_kind === "devflow_playwright") && typeof record.environment_profile === "string") {
+      profiles.add(record.environment_profile);
+    }
+    Object.values(record).forEach(visit);
+  };
+  visit(value);
+  return profiles;
+}
+
+const MAX_FAILURE_ERRORS = 50;
+const MAX_FAILURE_ERROR_CHARS = 500;
+
+// Failure details must not expose project or run locations (same rule as the Core report).
+function scrubPaths(text: string): string {
+  return text
+    .replace(/(?:[A-Za-z]:)?[^\s,;()"']+[\/][^\s,;()"']+/g, "<path>")
+    .slice(0, MAX_FAILURE_ERROR_CHARS);
+}
+
+// A run that executed TCs always answers with the Core report, even when TCs failed or are
+// blocked: the report's gate says whether acceptance passed.  Only runs that never produced
+// results (lock held, invalid bindings/approvals, Core crash) short-circuit with an error.
+function runFailure(value: Record<string, unknown>): Record<string, unknown> {
+  const code = typeof value.error_code === "string" ? value.error_code
+    : typeof value.reason === "string" && value.reason ? value.reason
+    : Array.isArray(value.errors) && value.errors.length > 0 ? "acceptance_validation_failed"
+    : "core_failed";
+  const errors = Array.isArray(value.errors) ? value.errors.slice(0, MAX_FAILURE_ERRORS).map(item => scrubPaths(String(item))) : [];
+  return { ok: false, error_code: code, reason: code, errors };
+}
+
+export async function createMcpServer(options: McpServerOptions) {
+  const home = options.home ?? devflowHome();
+  const config = await loadAuthorization(options.client, home);
+  const runner: CoreRunner = options.runner ?? runPython;
+  let running = false;
+
+  const server = new McpServer({ name: "devflow-acceptance", version: "1.0.0" });
+
+  const call = async (tool: McpToolName, args: Record<string, unknown>, onProgress?: ProgressCallback): Promise<Record<string, unknown>> => {
+    const started = Date.now();
+    let ok = false;
+    let reason: string | null = null;
+    try {
+      if (tool === "dsl_draft_validate") {
+        const dslText = JSON.stringify(args.dsl);
+        if (typeof dslText !== "string" || Buffer.byteLength(dslText) > MAX_DSL_BYTES) {
+          throw new McpError("mcp_input_invalid", "DSL exceeds 2 MiB or is not JSON");
+        }
+        const auth = await authorize(config, options.client, tool, args.project ?? process.cwd());
+        const raw = await runner(dslScript, [], auth.project, JSON.stringify({ dsl: args.dsl, tc_data: args.tc_data }));
+        if (raw.timedOut) return { ok: false, error_code: "core_failed", reason: "core_failed" };
+        try {
+          const parsed = JSON.parse(raw.stdout) as Record<string, unknown>;
+          ok = parsed.ok === true;
+          return parsed;
+        } catch {
+          return { ok: false, error_code: "core_failed", reason: raw.stderr || raw.stdout };
+        }
+      }
+
+      const feature = args.feature;
+      const auth = await authorize(config, options.client, tool, args.project, feature);
+      if (tool === "run_feature" && running) throw new McpError("mcp_busy", "another run_feature is in progress");
+
+      if (tool === "run_feature") {
+        const bindingFile = path.join(auth.project, ".devflow/planning/features", String(feature), "acceptance-test-bindings.json");
+        let bindings: unknown;
+        try {
+          bindings = JSON.parse(await readFile(bindingFile, "utf8"));
+        } catch {
+          throw new McpError("mcp_input_invalid", "acceptance-test-bindings.json is missing or invalid");
+        }
+        const profiles = collectEnvironmentProfiles(bindings);
+        if ([...profiles].some(profile => !auth.grant.environment_profiles.includes(profile))) {
+          throw new McpError("mcp_environment_not_allowed", "environment profile is not authorized");
+        }
+
+        running = true;
+        try {
+          const runResult = await invokeCore(
+            runner,
+            "run",
+            auth.project,
+            String(feature),
+            Math.min(7_200_000, Math.max(1, options.runTimeoutSeconds ?? 7200) * 1000),
+            onProgress,
+          );
+          if (!Array.isArray(runResult.results)) return runFailure(runResult);
+          const report = await invokeCore(runner, "report", auth.project, String(feature));
+          ok = report.ok === true;
+          return report;
+        } finally {
+          running = false;
+        }
+      }
+
+      const coreResult = await invokeCore(runner, tool === "validate_feature" ? "validate" : "report", auth.project, String(feature));
+      ok = coreResult.ok === true;
+      return coreResult;
+    } catch (error) {
+      const mcpError = error instanceof McpError
+        ? error
+        : new McpError("core_failed", error instanceof Error ? error.message : String(error));
+      reason = mcpError.code;
+      return { ok: false, error_code: mcpError.code, reason: mcpError.message };
+    } finally {
+      await audit(home, {
+        ts: new Date().toISOString(),
+        client: options.client,
+        project_id: typeof args.project === "string" ? requestHash(path.resolve(args.project)) : null,
+        tool,
+        feature: args.feature ?? null,
+        ok,
+        reason,
+        duration_ms: Date.now() - started,
+        request_sha256: requestHash(args),
+      });
+    }
+  };
+
+  const input = z.object({ project: z.string(), feature: z.string().regex(FEATURE_RE) });
+  const withProgress = (tool: McpToolName) => (args: any, extra: any) => {
+    const token = extra._meta?.progressToken;
+    const progress = token === undefined
+      ? undefined
+      : () => extra.sendNotification({ method: "notifications/progress", params: { progressToken: token, progress: Date.now(), message: "run_feature is still running" } });
+    return call(tool, args, progress).then(toolResult);
+  };
+
+  server.registerTool("validate_feature", { description: "Validate a feature; no artifacts are returned.", inputSchema: input.shape }, withProgress("validate_feature"));
+  server.registerTool("run_feature", { description: "Run a feature, then return only the Core report. Approval is never confirmed here; blocked tests require /devflow.", inputSchema: input.shape }, withProgress("run_feature"));
+  server.registerTool("get_feature_report", { description: "Get the Core feature report; no artifacts are returned.", inputSchema: input.shape }, withProgress("get_feature_report"));
+  server.registerTool("dsl_draft_validate", { description: "Validate DSL schema and coverage only; this does not make the draft executable and does not check approvals or manifests.", inputSchema: { project: z.string(), dsl: z.unknown(), tc_data: z.unknown() } }, withProgress("dsl_draft_validate"));
+
+  Object.assign(server, { invoke: call, boundedForTest: bounded });
+  return server;
+}
+
+export async function startMcpServer(options: McpServerOptions): Promise<void> {
+  const server = await createMcpServer(options);
+  await server.connect(new StdioServerTransport());
+}

package/src/mcp/types.ts

@@ -0,0 +1,5 @@
+export type McpToolName = "validate_feature" | "run_feature" | "get_feature_report" | "dsl_draft_validate";
+export type CoreResult = { ok: boolean; [key: string]: unknown };
+export type CoreRunnerResult = { exitCode: number | null; stdout: string; stderr: string; timedOut?: boolean };
+export type CoreRunner = (script: string, args: string[], cwd: string, stdin?: string, timeoutMs?: number, onProgress?: () => void | Promise<void>) => Promise<CoreRunnerResult>;
+export type McpServerOptions = { client: string; runTimeoutSeconds?: number; runner?: CoreRunner; home?: string };