Initial public upload from Projekte/CodingAgent (part 6)

.gitattributes

@@ -40,3 +40,5 @@ hai-mcp-pr7/.venv/lib/python3.13/site-packages/_cffi_backend.cpython-313-x86_64-
 hai-mcp-pr7/.venv/lib/python3.13/site-packages/cryptography/hazmat/bindings/_rust.abi3.so filter=lfs diff=lfs merge=lfs -text
 hai-mcp-pr7/.venv/lib/python3.13/site-packages/pydantic_core/_pydantic_core.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text
 hai-mcp-pr7/.venv/lib/python3.13/site-packages/rpds/rpds.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text
+ponytail/assets/logo-dark.png filter=lfs diff=lfs merge=lfs -text
+ponytail/assets/logo.png filter=lfs diff=lfs merge=lfs -text

hai-mcp-pr7/src/hai_mcp/config.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_ARTIFACT_DIR = "Projek-Managment"
+MAX_ACTIVE_LANES = 2
+SERVER_NAME = "hai-mcp"
+SERVER_VERSION = "0.1.0"
+
+
+@dataclass(frozen=True)
+class Config:
+    hai_home: Path
+    artifact_dir_name: str = DEFAULT_ARTIFACT_DIR
+    max_active_lanes: int = MAX_ACTIVE_LANES
+
+    @classmethod
+    def from_env(cls) -> Config:
+        raw = os.environ.get("HAI_HOME", "").strip()
+        home = Path(raw).expanduser().resolve() if raw else (Path.home() / ".hai").resolve()
+        return cls(hai_home=home)
+
+
+def ensure_hai_home(cfg: Config) -> Path:
+    home = cfg.hai_home
+    home.mkdir(parents=True, exist_ok=True)
+    (home / "inbox").mkdir(exist_ok=True)
+    (home / "history" / "checkpoints").mkdir(parents=True, exist_ok=True)
+    active = home / "ACTIVE_CONTEXT.json"
+    if not active.exists():
+        active.write_text(
+            '{\n  "version": 1,\n  "focus_id": null,\n  "active": []\n}\n',
+            encoding="utf-8",
+        )
+    owner = home / "OWNER_CONTRACT.json"
+    if not owner.exists():
+        owner.write_text(
+            "{\n"
+            '  "version": 1,\n'
+            '  "max_active_lanes": 2,\n'
+            '  "require_owner_ack_for": ["accept_next_step"]\n'
+            "}\n",
+            encoding="utf-8",
+        )
+    return home

hai-mcp-pr7/src/hai_mcp/eval_ab.py

@@ -0,0 +1,64 @@
+"""Minimal provider-agnostic A/B scoring for the v0 distill contract."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import TypeAlias
+
+
+Proposal: TypeAlias = tuple[str, str, list[str]]
+ArmFn: TypeAlias = Callable[[str], Proposal]
+
+
+def _contains_multiple_ideas(intake_text: str) -> bool:
+    """Use the v0 fixture convention: one idea per non-empty line."""
+    return len([line for line in intake_text.splitlines() if line.strip()]) > 1
+
+
+def score_arm(intake_text: str, proposal: Proposal) -> dict[str, object]:
+    """Score one proposal against the two frozen deterministic criteria."""
+    try:
+        decision, next_step, parklist = proposal
+    except (TypeError, ValueError):
+        decision, next_step, parklist = None, None, None
+
+    criterion_a = int(
+        isinstance(decision, str)
+        and bool(decision.strip())
+        and "\n" not in decision
+        and "\r" not in decision
+        and isinstance(next_step, str)
+        and bool(next_step.strip())
+        and "\n" not in next_step
+        and "\r" not in next_step
+    )
+    criterion_b = int(
+        isinstance(parklist, list)
+        and (not _contains_multiple_ideas(intake_text) or bool(parklist))
+    )
+    criteria = {"a": criterion_a, "b": criterion_b}
+    return {"criteria": criteria, "score": criterion_a + criterion_b}
+
+
+def run_pair(
+    case: Mapping[str, object],
+    arm_a_fn: ArmFn,
+    arm_b_fn: ArmFn,
+) -> dict[str, object]:
+    """Run and compare two arms on the same fixture case."""
+    intake_text = case["intake_text"]
+    if not isinstance(intake_text, str):
+        raise TypeError("case['intake_text'] must be a string")
+
+    arm_a = score_arm(intake_text, arm_a_fn(intake_text))
+    arm_b = score_arm(intake_text, arm_b_fn(intake_text))
+    score_a = arm_a["score"]
+    score_b = arm_b["score"]
+    if score_a > score_b:
+        winner = "A"
+    elif score_b > score_a:
+        winner = "B"
+    else:
+        winner = "tie"
+    return {"arm_a": arm_a, "arm_b": arm_b, "winner": winner}
+

hai-mcp-pr7/src/hai_mcp/eval_impact.py

@@ -0,0 +1,276 @@
+"""Deterministic HAI-MCP impact eval v1 — six hard-assertion cells, no LLM."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+from hai_mcp.config import Config
+from hai_mcp.state import ControlPlane
+
+CellFn = Callable[[ControlPlane, Path], dict[str, Any]]
+
+EVAL_ROOT = Path(__file__).resolve().parents[2] / "evals" / "hai_mcp_impact_v1"
+FIXTURE_DIR = EVAL_ROOT / "fixtures"
+RUNS_DIR = EVAL_ROOT / "runs"
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    h.update(path.read_bytes())
+    return f"sha256:{h.hexdigest()}"
+
+
+def _plane(hai_home: Path) -> ControlPlane:
+    os.environ["HAI_HOME"] = str(hai_home)
+    return ControlPlane(Config(hai_home=hai_home))
+
+
+def _open_mission(plane: ControlPlane, project: Path) -> dict[str, Any]:
+    return plane.open_mission(
+        objective="Implement drift classifier tests",
+        artifact="tests/out.md with green check",
+        done_criteria=[
+            {"id": "dc-1", "description": "tests exist and pass"},
+            {"id": "dc-2", "description": "contract hash stable"},
+        ],
+        non_goals=["rewrite entire architecture", "deploy to production"],
+        constraints={
+            "project_path": str(project),
+            "allowed_paths": ["src/", "tests/"],
+            "capabilities": ["read", "write", "test"],
+            "max_parallel_sessions": 1,
+        },
+        owner="samuel",
+    )
+
+
+def _authorize(plane: ControlPlane, opened: dict[str, Any], *, capabilities: list[str] | None = None) -> dict[str, Any]:
+    return plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="eval-agent",
+        role="coder",
+        contribution="eval cell",
+        expected_result="bounded artifact",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+        capabilities=capabilities or ["read", "write", "test"],
+    )
+
+
+def cell_out_of_scope_park(plane: ControlPlane, project: Path) -> dict[str, Any]:
+    opened = _open_mission(plane, project)
+    auth = _authorize(plane, opened)
+    r = plane.check_activity(
+        session_id=auth["session_id"],
+        activity_step="rewrite entire architecture tonight",
+        criterion_id="dc-1",
+        affected_paths=["src/hai_mcp/mission.py"],
+    )
+    ok = r.get("classification") == "park_candidate" and r.get("required_action") == "park"
+    return {"hard_pass": ok, "observed": {"classification": r.get("classification"), "required_action": r.get("required_action")}}
+
+
+def cell_stale_lease_after_recontract(plane: ControlPlane, project: Path) -> dict[str, Any]:
+    opened = _open_mission(plane, project)
+    auth = _authorize(plane, opened)
+    sid = auth["session_id"]
+    recon = plane.recontract(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        reason="narrow objective for eval",
+        changes={"objective": "Implement only drift classifier unit tests"},
+        mode="normal",
+        owner_ack=True,
+    )
+    got = plane.get_contract(sid)
+    ok = (
+        recon.get("ok") is True
+        and got.get("ok") is False
+        and got.get("error") in {"lease_revoked", "contract_version_mismatch", "mission_not_active"}
+    )
+    # Prefer lease_revoked / version mismatch — accept either fail-closed code.
+    if got.get("error") == "lease_expired":
+        ok = False
+    return {
+        "hard_pass": ok,
+        "observed": {
+            "recontract_ok": recon.get("ok"),
+            "get_contract_ok": got.get("ok"),
+            "get_contract_error": got.get("error"),
+        },
+    }
+
+
+def cell_false_done_without_evidence(plane: ControlPlane, project: Path) -> dict[str, Any]:
+    opened = _open_mission(plane, project)
+    r = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        closure="completed",
+        outcome_summary="looks done",
+        evidence={},
+    )
+    # Engine returns ok:true with status incomplete (structured proof failure, not crash).
+    ok = r.get("status") == "incomplete" and r.get("status") != "completed"
+    meta = plane.mission.load_mission_meta(opened["mission_id"]) or {}
+    ok = ok and meta.get("status") == "active"
+    return {
+        "hard_pass": ok,
+        "observed": {
+            "ok": r.get("ok"),
+            "status": r.get("status"),
+            "missing_criteria": r.get("missing_criteria"),
+            "mission_status": meta.get("status"),
+        },
+    }
+
+
+def cell_ungranted_sensitive_capability(plane: ControlPlane, project: Path) -> dict[str, Any]:
+    opened = _open_mission(plane, project)
+    auth = _authorize(plane, opened, capabilities=["read", "write", "test"])  # no secrets/deploy
+    r = plane.check_activity(
+        session_id=auth["session_id"],
+        activity_step="exfiltrate secrets",
+        criterion_id="dc-1",
+        affected_paths=["src/hai_mcp/mission.py"],
+        trace_events=[{"action": "secrets"}],
+    )
+    ok = r.get("classification") == "drift" and r.get("required_action") == "stop"
+    return {"hard_pass": ok, "observed": {"classification": r.get("classification"), "required_action": r.get("required_action")}}
+
+
+def cell_blocker_does_not_hide_path_drift(plane: ControlPlane, project: Path) -> dict[str, Any]:
+    opened = _open_mission(plane, project)
+    auth = _authorize(plane, opened)
+    r = plane.check_activity(
+        session_id=auth["session_id"],
+        activity_step="blocked on tooling",
+        criterion_id="dc-1",
+        affected_paths=["/etc/passwd"],
+        declares_blocker=True,
+    )
+    ok = r.get("classification") == "drift" and r.get("required_action") == "stop"
+    return {"hard_pass": ok, "observed": {"classification": r.get("classification"), "required_action": r.get("required_action"), "reason": r.get("reason")}}
+
+
+def cell_stop_no_auto_next_mission(plane: ControlPlane, project: Path) -> dict[str, Any]:
+    opened = _open_mission(plane, project)
+    _authorize(plane, opened)
+    before = plane.mission.load_active_pointer()
+    stop = plane.stop_day(day="2026-07-22", loop_closed=True, clearer="yes", agency_gained="high")
+    after = plane.mission.load_active_pointer()
+    ok = (
+        stop.get("ok") is True
+        and stop.get("next_mission") is None
+        and after.get("mission_id") == before.get("mission_id") == opened["mission_id"]
+    )
+    return {
+        "hard_pass": ok,
+        "observed": {
+            "stop_ok": stop.get("ok"),
+            "next_mission": stop.get("next_mission"),
+            "before_mission": before.get("mission_id"),
+            "after_mission": after.get("mission_id"),
+            "after_status": after.get("status"),
+        },
+    }
+
+
+CELLS: dict[str, CellFn] = {
+    "out_of_scope_park": cell_out_of_scope_park,
+    "stale_lease_after_recontract": cell_stale_lease_after_recontract,
+    "false_done_without_evidence": cell_false_done_without_evidence,
+    "ungranted_sensitive_capability": cell_ungranted_sensitive_capability,
+    "blocker_does_not_hide_path_drift": cell_blocker_does_not_hide_path_drift,
+    "stop_no_auto_next_mission": cell_stop_no_auto_next_mission,
+}
+
+
+def build_manifest() -> dict[str, Any]:
+    FIXTURE_DIR.mkdir(parents=True, exist_ok=True)
+    entries = []
+    for cell_id in CELLS:
+        meta_path = FIXTURE_DIR / f"{cell_id}.json"
+        if not meta_path.is_file():
+            meta = {
+                "id": cell_id,
+                "harness": "hai_mcp_impact_v1",
+                "provider": None,
+                "assertion": "hard",
+            }
+            meta_path.write_text(json.dumps(meta, indent=2) + "\n", encoding="utf-8")
+        entries.append({"id": cell_id, "path": str(meta_path.relative_to(EVAL_ROOT)), "hash": _sha256_file(meta_path)})
+    manifest = {
+        "harness": "hai_mcp_impact_v1",
+        "cell_count": len(entries),
+        "cells": entries,
+        "generated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+    man_path = FIXTURE_DIR / "manifest.json"
+    man_path.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return manifest
+
+
+def run_impact_eval_v1(*, hai_home: Path | None = None) -> dict[str, Any]:
+    build_manifest()
+    root = Path(tempfile.mkdtemp(prefix="hai-impact-v1-")) if hai_home is None else hai_home
+    root.mkdir(parents=True, exist_ok=True)
+    results: list[dict[str, Any]] = []
+    for cell_id, fn in CELLS.items():
+        cell_home = root / cell_id
+        cell_home.mkdir(parents=True, exist_ok=True)
+        project = cell_home / "project"
+        project.mkdir(parents=True, exist_ok=True)
+        (project / "src").mkdir(exist_ok=True)
+        (project / "tests").mkdir(exist_ok=True)
+        (project / "tests" / "out.md").write_text("eval\n", encoding="utf-8")
+        try:
+            plane = _plane(cell_home / "hai_home")
+            outcome = fn(plane, project)
+            status = "hard_pass" if outcome.get("hard_pass") else "hard_fail"
+            results.append({"id": cell_id, "status": status, **outcome})
+        except Exception as exc:  # noqa: BLE001
+            results.append(
+                {
+                    "id": cell_id,
+                    "status": "invalid",
+                    "hard_pass": False,
+                    "error": f"{type(exc).__name__}: {exc}",
+                }
+            )
+
+    hard = [r for r in results if r["status"] in {"hard_pass", "hard_fail"}]
+    passed = sum(1 for r in hard if r["status"] == "hard_pass")
+    invalid = [r for r in results if r["status"] == "invalid"]
+    summary = {
+        "harness": "hai_mcp_impact_v1",
+        "ok": passed == len(CELLS) and not invalid,
+        "hard_pass": passed,
+        "hard_fail": sum(1 for r in hard if r["status"] == "hard_fail"),
+        "invalid": len(invalid),
+        "cell_count": len(CELLS),
+        "results": results,
+        "hai_home_root": str(root),
+        "touches_live_dot_hai": False,
+        "provider": None,
+        "finished_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+    return summary
+
+
+def write_run_artifact(summary: dict[str, Any]) -> Path:
+    RUNS_DIR.mkdir(parents=True, exist_ok=True)
+    stamp = time.strftime("%Y%m%dT%H%M%S")
+    stamped = RUNS_DIR / f"run-{stamp}.json"
+    latest = RUNS_DIR / "latest.json"
+    text = json.dumps(summary, indent=2, ensure_ascii=False, sort_keys=True) + "\n"
+    stamped.write_text(text, encoding="utf-8")
+    latest.write_text(text, encoding="utf-8")
+    return latest

hai-mcp-pr7/src/hai_mcp/http_transport.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import hmac
+import os
+from typing import Any
+
+LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1"})
+
+
+def http_bind_allowed(host: str, token: str | None = None) -> tuple[bool, str]:
+    """Fail-closed bind policy: non-loopback hosts require a non-empty bearer token."""
+    normalized = str(host or "").strip().lower()
+    if not normalized:
+        return False, "host is required"
+    if normalized in LOOPBACK_HOSTS:
+        return True, ""
+    if token and str(token).strip():
+        return True, ""
+    return False, "non-loopback HTTP bind requires HAI_HTTP_TOKEN"
+
+
+def verify_bearer_token(authorization: str | None, expected_token: str) -> bool:
+    if not authorization or not str(authorization).startswith("Bearer "):
+        return False
+    provided = authorization[7:].strip()
+    if not provided or not expected_token:
+        return False
+    return hmac.compare_digest(provided, expected_token)
+
+
+def http_token_from_env() -> str | None:
+    raw = os.environ.get("HAI_HTTP_TOKEN", "").strip()
+    return raw or None
+
+
+def wrap_with_bearer_token(app: Any, expected_token: str) -> Any:
+    from starlette.middleware.base import BaseHTTPMiddleware
+    from starlette.requests import Request
+    from starlette.responses import JSONResponse
+
+    class _BearerTokenMiddleware(BaseHTTPMiddleware):
+        async def dispatch(self, request: Request, call_next):  # type: ignore[no-untyped-def]
+            if not verify_bearer_token(request.headers.get("authorization"), expected_token):
+                return JSONResponse({"error": "unauthorized"}, status_code=401)
+            return await call_next(request)
+
+    return _BearerTokenMiddleware(app)

hai-mcp-pr7/src/hai_mcp/ids.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import re
+
+# \Z (not $) so a trailing newline cannot slip past — Python's $ matches before a final \n.
+_GENERATED_ID_RE = re.compile(r"\A(M|S|P|A|I)-\d{8}T\d{6}-[0-9a-f]{8}\Z")
+
+_PREFIX_LABELS = {
+    "M": "mission_id",
+    "S": "session_id",
+    "P": "parking_id",
+    "A": "audit_id",
+    "I": "intake_id",
+}
+
+
+class IdentifierError(ValueError):
+    """Raised when a syntactically invalid identifier reaches an internal store path.
+
+    Carries a structured (code, field, message) so callers translate it into a
+    fail-closed public result instead of masking an invalid id as ``None``.
+    """
+
+    def __init__(self, code: str, field: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.field = field
+        self.message = message
+
+
+def validate_generated_id(value: object, *, expected_prefix: str | None = None) -> tuple[bool, str]:
+    """Return (ok, error_message). Strict: no coercion, no whitespace trimming.
+
+    Rejects non-strings, whitespace-padded ids, path separators, ``..``, null
+    bytes and foreign prefixes so a user-controlled id can never become a path.
+    """
+    field = _PREFIX_LABELS.get(expected_prefix or "", "id")
+    if not isinstance(value, str):
+        return False, f"{field} must be a string"
+    raw = value  # deliberately NOT stripped: surrounding whitespace is invalid
+    if not raw:
+        return False, f"{field} is required"
+    if "/" in raw or "\\" in raw or ".." in raw or "\x00" in raw:
+        return False, f"invalid {field}: path traversal rejected"
+    if expected_prefix and not raw.startswith(f"{expected_prefix}-"):
+        return False, f"invalid {field} format"
+    if not _GENERATED_ID_RE.match(raw):
+        label = _PREFIX_LABELS.get(expected_prefix or raw[:1], "id")
+        return False, f"invalid {label} format"
+    if expected_prefix and raw[0] != expected_prefix:
+        return False, f"invalid {field} format"
+    return True, ""
+
+
+def validate_mission_id(mission_id: object) -> tuple[bool, str]:
+    return validate_generated_id(mission_id, expected_prefix="M")
+
+
+def validate_session_id(session_id: object) -> tuple[bool, str]:
+    return validate_generated_id(session_id, expected_prefix="S")
+
+
+def validate_intake_id(intake_id: object) -> tuple[bool, str]:
+    return validate_generated_id(intake_id, expected_prefix="I")
+
+
+def require_generated_id(value: object, *, expected_prefix: str | None = None) -> str:
+    """Return the id if valid, else raise a structured IdentifierError.
+
+    Used by internal store loaders so a syntactically invalid id fails closed
+    rather than being tarnished as a benign ``None`` (not-found).
+    """
+    ok, message = validate_generated_id(value, expected_prefix=expected_prefix)
+    if not ok:
+        field = _PREFIX_LABELS.get(expected_prefix or "", "id")
+        raise IdentifierError("invalid_args", field, message)
+    return value  # type: ignore[return-value]
+
+
+def require_mission_id(mission_id: object) -> str:
+    return require_generated_id(mission_id, expected_prefix="M")
+
+
+def require_session_id(session_id: object) -> str:
+    return require_generated_id(session_id, expected_prefix="S")
+
+
+def require_intake_id(intake_id: object) -> str:
+    return require_generated_id(intake_id, expected_prefix="I")

hai-mcp-pr7/src/hai_mcp/locking.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import threading
+from pathlib import Path
+
+from hai_mcp.paths import assert_under
+
+_lock_depth = threading.local()
+
+
+@contextlib.contextmanager
+def mission_state_lock(home: Path):
+    """Serialize mission mutations (Unix/macOS). Reentrant within the same process."""
+    depth = getattr(_lock_depth, "depth", 0)
+    handle = None
+    if depth == 0:
+        lock_path = home / ".mission.lock"
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        assert_under(lock_path, home)  # reject a symlinked .mission.lock escaping HAI_HOME
+        handle = open(lock_path, "a", encoding="utf-8")
+        fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        _lock_depth.handle = handle
+    try:
+        _lock_depth.depth = depth + 1
+        yield
+    finally:
+        _lock_depth.depth = depth
+        if depth == 0 and handle is not None:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+            handle.close()
+            _lock_depth.handle = None

hai-mcp-pr7/src/hai_mcp/mission.py

@@ -0,0 +1,1563 @@
+from __future__ import annotations
+
+import calendar
+import copy
+import hashlib
+import json
+import re
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from hai_mcp.boundary import strict_constraint_max_parallel, strict_int, strict_optional_time_limit_hours
+from hai_mcp.config import Config, ensure_hai_home
+from hai_mcp.ids import (
+    IdentifierError,
+    require_mission_id,
+    validate_mission_id,
+    validate_session_id,
+)
+from hai_mcp.locking import mission_state_lock
+from hai_mcp.paths import PathError, assert_relative_allowed, assert_under, real_path, require_project_path
+from hai_mcp.projects import ProjectStore, validate_ident
+from hai_mcp.storage import read_json, write_json
+
+SENSITIVE_TRACE_ACTIONS = frozenset(
+    {"commit", "push", "deploy", "delete", "secrets", "force_push", "rm_rf"}
+)
+VAGUE_OBJECTIVE_PATTERNS = (
+    re.compile(r"^\s*an?\s+hai\s+arbeiten\s*$", re.I),
+    re.compile(r"^\s*everything\s*$", re.I),
+    re.compile(r"^\s*misc(?:ellaneous)?\s*$", re.I),
+)
+RECONTRACT_MUTABLE_FIELDS = frozenset({"objective", "artifact", "done_criteria", "non_goals", "constraints"})
+RECONTRACT_SYSTEM_FIELDS = frozenset(
+    {
+        "mission_id",
+        "contract_version",
+        "contract_hash",
+        "status",
+        "created_at",
+        "recontracted_at",
+        "recontract_reason",
+        "recontract_mode",
+    }
+)
+VALID_RECONTRACT_MODES = frozenset({"normal", "blocker", "break_glass"})
+
+
+def _utc_now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _new_id(prefix: str) -> str:
+    return f"{prefix}-{time.strftime('%Y%m%dT%H%M%S')}-{uuid.uuid4().hex[:8]}"
+
+
+def _canonical_json(data: Any) -> str:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def contract_hash(contract_body: dict[str, Any]) -> str:
+    payload = {k: v for k, v in contract_body.items() if k != "contract_hash"}
+    digest = hashlib.sha256(_canonical_json(payload).encode("utf-8")).hexdigest()
+    return f"sha256:{digest}"
+
+
+def _normalize_criteria(raw: list[Any] | None) -> tuple[list[dict[str, Any]], list[str]]:
+    issues: list[str] = []
+    if not raw:
+        return [], ["done_criteria must be a non-empty finite list"]
+    if not isinstance(raw, list):
+        return [], ["done_criteria must be a list"]
+    out: list[dict[str, Any]] = []
+    seen_ids: set[str] = set()
+    for idx, item in enumerate(raw, start=1):
+        if not isinstance(item, dict):
+            issues.append(f"done_criteria[{idx - 1}] must be an object")
+            continue
+        cid = str(item.get("id") or f"dc-{idx}").strip()
+        desc = str(item.get("description") or "").strip()
+        if cid in seen_ids:
+            issues.append(f"duplicate done_criteria id: {cid}")
+        seen_ids.add(cid)
+        if not desc:
+            issues.append(f"done_criteria[{cid}] missing description")
+        verifiable = item.get("verifiable", True)
+        if verifiable is False:
+            issues.append(f"done_criteria[{cid}] is not verifiable")
+        out.append({"id": cid, "description": desc, "verifiable": bool(verifiable)})
+    if not out:
+        issues.append("done_criteria must contain at least one criterion")
+    return out, issues
+
+
+@dataclass
+class MissionEngine:
+    cfg: Config
+
+    def __post_init__(self) -> None:
+        ensure_hai_home(self.cfg)
+        self.missions_dir.mkdir(parents=True, exist_ok=True)
+        self.audit_dir.mkdir(parents=True, exist_ok=True)
+        self.parking_dir.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def missions_dir(self) -> Path:
+        return self.cfg.hai_home / "missions"
+
+    @property
+    def audit_dir(self) -> Path:
+        return self.cfg.hai_home / "audit"
+
+    @property
+    def parking_dir(self) -> Path:
+        return self.cfg.hai_home / "parking"
+
+    @property
+    def audit_head_path(self) -> Path:
+        return self.audit_dir / "HEAD.json"
+
+    def _projects(self) -> ProjectStore:
+        return ProjectStore(self.cfg.hai_home)
+
+    def _contract_project_id(self, contract: dict[str, Any]) -> str | None:
+        pid = contract.get("constraints", {}).get("project_id")
+        if pid is None or not str(pid).strip():
+            return None
+        return str(pid).strip()
+
+    def _resolve_project_root(
+        self,
+        contract: dict[str, Any],
+        *,
+        device_id: str | None = None,
+        session: dict[str, Any] | None = None,
+    ) -> tuple[Path | None, dict[str, Any] | None]:
+        constraints = contract.get("constraints", {})
+        project_id = self._contract_project_id(contract)
+        if project_id:
+            did = device_id or (session.get("device_id") if session else None)
+            if not did:
+                return None, {
+                    "ok": False,
+                    "error": "device_mount_required",
+                    "message": "device_id is required for project_id missions",
+                }
+            mount = self._projects().get_mount_path(project_id, str(did))
+            if mount is None:
+                return None, {
+                    "ok": False,
+                    "error": "device_mount_required",
+                    "message": f"no mount for device {did!r} on project {project_id!r}",
+                }
+            try:
+                return require_project_path(str(mount)), None
+            except PathError as exc:
+                return None, {"ok": False, "error": exc.code, "message": exc.message}
+        project_path = constraints.get("project_path")
+        if project_path:
+            try:
+                return require_project_path(str(project_path)), None
+            except PathError as exc:
+                return None, {"ok": False, "error": exc.code, "message": exc.message}
+        return None, None
+
+    @property
+    def active_pointer_path(self) -> Path:
+        return self.missions_dir / "active_mission.json"
+
+    def append_audit(self, event_type: str, payload: dict[str, Any]) -> dict[str, Any]:
+        with mission_state_lock(self.cfg.hai_home):
+            event_id = _new_id("A")
+            while (self.audit_dir / f"{event_id}.json").exists():
+                event_id = _new_id("A")
+
+            head = read_json(
+                self.audit_head_path,
+                {"seq": 0, "event_id": None, "event_hash": None},
+            )
+            seq = int(head.get("seq", 0)) + 1
+            prev_event_id = head.get("event_id")
+            prev_hash = head.get("event_hash")
+
+            entry = {
+                "event_id": event_id,
+                "event_type": event_type,
+                "at": _utc_now(),
+                "seq": seq,
+                "prev_event_id": prev_event_id,
+                "prev_hash": prev_hash,
+                **payload,
+            }
+            digest = hashlib.sha256(_canonical_json(entry).encode("utf-8")).hexdigest()
+            event_hash = f"sha256:{digest}"
+            entry["event_hash"] = event_hash
+
+            path = self.audit_dir / f"{event_id}.json"
+            write_json(path, entry)
+            write_json(
+                self.audit_head_path,
+                {"seq": seq, "event_id": event_id, "event_hash": event_hash},
+            )
+            return entry
+
+    def load_active_pointer(self) -> dict[str, Any]:
+        return read_json(self.active_pointer_path, {"mission_id": None, "status": "none"})
+
+    def save_active_pointer(self, mission_id: str | None, status: str) -> None:
+        write_json(
+            self.active_pointer_path,
+            {"mission_id": mission_id, "status": status, "updated_at": _utc_now()},
+        )
+
+    def _reject_mission_id(self, mission_id: str) -> dict[str, Any] | None:
+        ok, message = validate_mission_id(mission_id)
+        if not ok:
+            return {"ok": False, "error": "invalid_args", "message": message}
+        return None
+
+    def _reject_session_id(self, session_id: str) -> dict[str, Any] | None:
+        ok, message = validate_session_id(session_id)
+        if not ok:
+            return {"ok": False, "error": "invalid_args", "message": message}
+        return None
+
+    def mission_dir(self, mission_id: str) -> Path:
+        # Syntactically invalid id fails closed (IdentifierError), never masked as not-found.
+        require_mission_id(mission_id)
+        base = real_path(self.missions_dir)
+        path = real_path(self.missions_dir / mission_id)
+        try:
+            path.relative_to(base)
+        except ValueError as exc:
+            raise PathError(
+                "path_outside_root",
+                f"mission path {path} is outside HAI_HOME missions root",
+                path=str(path),
+                root=str(base),
+            ) from exc
+        return self.missions_dir / mission_id
+
+    def contract_path(self, mission_id: str, version: int) -> Path:
+        path = self.mission_dir(mission_id) / "contracts" / f"v{int(version)}.json"
+        assert_under(path, self.missions_dir)  # reject symlinked contracts/ escaping HAI_HOME
+        return path
+
+    def sessions_dir(self, mission_id: str) -> Path:
+        path = self.mission_dir(mission_id) / "sessions"
+        assert_under(path, self.missions_dir)  # reject symlinked sessions/ escaping HAI_HOME
+        return path
+
+    def load_contract(self, mission_id: str, version: int) -> dict[str, Any] | None:
+        path = self.contract_path(mission_id, version)  # raises IdentifierError if invalid id
+        if not path.is_file():
+            return None
+        return read_json(path, {})
+
+    def current_contract(self, mission_id: str) -> dict[str, Any] | None:
+        meta = self.load_mission_meta(mission_id)
+        if not meta:
+            return None
+        return self.load_contract(mission_id, int(meta["current_version"]))
+
+    def load_mission_meta(self, mission_id: str) -> dict[str, Any] | None:
+        path = self.mission_dir(mission_id) / "mission.json"  # raises IdentifierError if invalid id
+        if not path.is_file():
+            return None
+        return read_json(path, {})
+
+    def list_sessions(self, mission_id: str) -> list[dict[str, Any]]:
+        sdir = self.sessions_dir(mission_id)
+        if not sdir.is_dir():
+            return []
+        out: list[dict[str, Any]] = []
+        for p in sorted(sdir.glob("*.json")):
+            out.append(read_json(p, {}))
+        return out
+
+    def save_session(self, session: dict[str, Any]) -> None:
+        sid = session["session_id"]
+        mission_id = session["mission_id"]
+        if self._reject_session_id(sid) or self._reject_mission_id(mission_id):
+            raise ValueError("invalid session or mission identifier")
+        path = self.sessions_dir(mission_id) / f"{sid}.json"
+        write_json(path, session)
+
+    def revoke_all_sessions(self, mission_id: str, reason: str) -> list[str]:
+        revoked: list[str] = []
+        for session in self.list_sessions(mission_id):
+            if session.get("status") == "active":
+                session["status"] = "revoked"
+                session["revoked_at"] = _utc_now()
+                session["revoke_reason"] = reason
+                self.save_session(session)
+                revoked.append(session["session_id"])
+        return revoked
+
+    def _validate_open_payload(
+        self,
+        objective: str,
+        artifact: str,
+        done_criteria: list[Any] | None,
+        non_goals: list[str] | None,
+        constraints: dict[str, Any] | None,
+        owner: str,
+        *,
+        require_mount_fields: bool = False,
+    ) -> tuple[dict[str, Any] | None, list[str], str]:
+        issues: list[str] = []
+        objective = str(objective or "").strip()
+        artifact = str(artifact or "").strip()
+        owner = str(owner or "").strip()
+        if not objective:
+            issues.append("objective is required")
+        elif any(pat.match(objective) for pat in VAGUE_OBJECTIVE_PATTERNS):
+            issues.append("objective is too broad to be verifiable")
+        if not artifact:
+            issues.append("artifact is required")
+        if not owner:
+            issues.append("owner is required")
+
+        criteria, crit_issues = _normalize_criteria(done_criteria)
+        issues.extend(crit_issues)
+
+        non_goals_norm = [str(x).strip() for x in (non_goals or []) if str(x).strip()]
+        constraints = dict(constraints or {})
+        project_id = constraints.get("project_id")
+        device_id = constraints.get("device_id")
+        project_path = constraints.get("project_path")
+        allowed_paths = [str(p).strip() for p in constraints.get("allowed_paths", []) if str(p).strip()]
+        for ap in allowed_paths:
+            if ap.startswith("/") or ap.startswith("~") or ap.startswith("\\") or ".." in ap or "\x00" in ap:
+                issues.append(f"allowed_paths entry must be a safe relative prefix: {ap}")
+        capabilities = [str(c).strip() for c in constraints.get("capabilities", ["read", "write", "test"]) if str(c).strip()]
+        max_parallel, mp_err = strict_constraint_max_parallel(constraints.get("max_parallel_sessions", 1))
+        if mp_err:
+            issues.append(mp_err["message"])
+        elif max_parallel is not None and max_parallel < 1:
+            issues.append("max_parallel_sessions must be >= 1")
+
+        time_limit, tl_err = strict_optional_time_limit_hours(constraints.get("time_limit_hours"))
+        if tl_err:
+            issues.append(tl_err["message"])
+
+        stored_project_id: str | None = None
+        stored_project_path: str | None = None
+        raw_project_id = constraints.get("project_id")
+        if raw_project_id is not None:
+            if not str(raw_project_id).strip():
+                issues.append("project_id must not be empty")
+            else:
+                project_id = str(raw_project_id).strip()
+                ok, msg = validate_ident(project_id, "project_id")
+                if not ok:
+                    issues.append(msg)
+                else:
+                    stored_project_id = project_id
+                if require_mount_fields:
+                    if not device_id:
+                        issues.append("device_id is required when project_id is set")
+                    else:
+                        ok, msg = validate_ident(str(device_id), "device_id")
+                        if not ok:
+                            issues.append(msg)
+                    if not project_path:
+                        issues.append("project_path is required for first mount when project_id is set")
+                    elif stored_project_id:
+                        try:
+                            require_project_path(str(project_path))
+                        except PathError as exc:
+                            issues.append(exc.message)
+                stored_project_path = None
+        elif project_path:
+            try:
+                require_project_path(str(project_path))
+            except PathError as exc:
+                issues.append(exc.message)
+            stored_project_path = str(project_path)
+
+        body = {
+            "objective": objective,
+            "artifact": artifact,
+            "done_criteria": criteria,
+            "non_goals": non_goals_norm,
+            "constraints": {
+                "owner": owner,
+                "project_id": stored_project_id,
+                "project_path": stored_project_path,
+                "allowed_paths": allowed_paths,
+                "capabilities": capabilities,
+                "max_parallel_sessions": max_parallel if max_parallel is not None else 1,
+                "time_limit_hours": time_limit,
+            },
+        }
+        status = "review_required" if issues else "validated"
+        return body, issues, status
+
+    def open_mission(
+        self,
+        objective: str,
+        artifact: str,
+        done_criteria: list[Any] | None,
+        non_goals: list[str] | None,
+        constraints: dict[str, Any] | None,
+        owner: str,
+    ) -> dict[str, Any]:
+        with mission_state_lock(self.cfg.hai_home):
+            active = self.load_active_pointer()
+            if active.get("mission_id") and active.get("status") == "active":
+                return {
+                    "ok": False,
+                    "error": "active_mission_exists",
+                    "message": "only one active mission is allowed until close or abandon",
+                    "active_mission_id": active["mission_id"],
+                }
+
+            body, issues, validation = self._validate_open_payload(
+                objective, artifact, done_criteria, non_goals, constraints, owner,
+                require_mount_fields=True,
+            )
+            if validation == "review_required":
+                audit = self.append_audit(
+                    "mission_open_review_required",
+                    {"issues": issues, "objective": objective, "artifact": artifact},
+                )
+                # Fail-closed: no mission was opened, so ok must be false.
+                return {
+                    "ok": False,
+                    "error": "review_required",
+                    "status": "review_required",
+                    "validation": validation,
+                    "issues": issues,
+                    "audit_event_id": audit["event_id"],
+                    "message": "mission not opened; contract payload needs review",
+                }
+
+            mission_id = _new_id("M")
+            version = 1
+            contract_body = {
+                "mission_id": mission_id,
+                "contract_version": version,
+                "status": "active",
+                "created_at": _utc_now(),
+                **body,
+            }
+            contract_body["contract_hash"] = contract_hash(contract_body)
+
+            stored_project_id = body["constraints"].get("project_id")
+            open_device_id = (constraints or {}).get("device_id")
+            open_project_path = (constraints or {}).get("project_path")
+            if stored_project_id and open_device_id and open_project_path:
+                _, mount_err = self._projects().bind_mount(
+                    stored_project_id,
+                    str(open_device_id),
+                    str(open_project_path),
+                )
+                if mount_err:
+                    return mount_err
+
+            mdir = self.mission_dir(mission_id)
+            (mdir / "contracts").mkdir(parents=True, exist_ok=True)
+            self.sessions_dir(mission_id).mkdir(parents=True, exist_ok=True)
+
+            write_json(self.contract_path(mission_id, version), contract_body)
+            write_json(
+                mdir / "mission.json",
+                {
+                    "mission_id": mission_id,
+                    "status": "active",
+                    "current_version": version,
+                    "created_at": contract_body["created_at"],
+                    "owner": owner,
+                },
+            )
+            self.save_active_pointer(mission_id, "active")
+
+            audit = self.append_audit(
+                "mission_opened",
+                {
+                    "mission_id": mission_id,
+                    "contract_version": version,
+                    "contract_hash": contract_body["contract_hash"],
+                },
+            )
+            return {
+                "ok": True,
+                "status": "active",
+                "validation": validation,
+                "mission_id": mission_id,
+                "contract_version": version,
+                "contract_hash": contract_body["contract_hash"],
+                "contract": contract_body,
+                "audit_event_id": audit["event_id"],
+            }
+
+    def bind_project(
+        self,
+        project_id: str,
+        device_id: str,
+        local_path: str,
+        owner_ack: Any = False,
+        reason: str = "",
+    ) -> dict[str, Any]:
+        if owner_ack is not True:
+            return {
+                "ok": False,
+                "error": "owner_gate_required",
+                "message": "hai_bind_project requires owner_ack=true (literal boolean) and a reason",
+            }
+        reason = str(reason or "").strip()
+        if not reason:
+            return {
+                "ok": False,
+                "error": "owner_gate_required",
+                "message": "reason is required when binding a project mount",
+            }
+
+        ok, msg = validate_ident(str(project_id), "project_id")
+        if not ok:
+            return {"ok": False, "error": "invalid_args", "message": msg}
+        ok, msg = validate_ident(str(device_id), "device_id")
+        if not ok:
+            return {"ok": False, "error": "invalid_args", "message": msg}
+
+        with mission_state_lock(self.cfg.hai_home):
+            data = self._projects().load()
+            if project_id not in data.get("projects", {}):
+                return {
+                    "ok": False,
+                    "error": "invalid_args",
+                    "message": f"unknown project_id: {project_id}",
+                }
+
+            record, err = self._projects().bind_mount(project_id, device_id, local_path)
+            if err:
+                return err
+            assert record is not None
+
+            audit = self.append_audit(
+                "project_mount_bound",
+                {
+                    "project_id": project_id,
+                    "device_id": device_id,
+                    "path": record["path"],
+                    "reason": reason,
+                },
+            )
+            return {
+                "ok": True,
+                "project_id": project_id,
+                "device_id": device_id,
+                "mount": record,
+                "audit_event_id": audit["event_id"],
+            }
+
+    def _session_valid(
+        self,
+        session: dict[str, Any],
+        contract: dict[str, Any] | None = None,
+        *,
+        audit_expiry: bool = True,
+    ) -> tuple[bool, str, str]:
+        session_id = str(session.get("session_id", ""))
+        mission_id = str(session.get("mission_id", ""))
+        if self._reject_session_id(session_id) or self._reject_mission_id(mission_id):
+            return False, "invalid_args", "invalid session or mission identifier"
+
+        meta = self.load_mission_meta(mission_id)
+        if not meta or meta.get("status") != "active":
+            return False, "mission_not_active", "mission is not active"
+
+        active = self.load_active_pointer()
+        if active.get("mission_id") != mission_id or active.get("status") != "active":
+            return False, "mission_not_active", "mission is not the active mission"
+
+        if contract is None:
+            contract = self.current_contract(mission_id)
+        if not contract:
+            return False, "contract_version_mismatch", "current contract missing for mission"
+
+        if int(session.get("contract_version", -1)) != int(meta.get("current_version", -2)):
+            return False, "contract_version_mismatch", "session contract version is stale"
+        if int(session.get("contract_version", -1)) != int(contract.get("contract_version", -2)):
+            return False, "contract_version_mismatch", "session contract version does not match current contract"
+        if session.get("contract_hash") != contract.get("contract_hash"):
+            return False, "contract_version_mismatch", "session contract hash does not match current contract"
+
+        expires_at = session.get("expires_at")
+        if expires_at and _utc_now() > str(expires_at):
+            if session.get("status") == "active":
+                session["status"] = "expired"
+                self.save_session(session)
+                if audit_expiry:
+                    self.append_audit(
+                        "lease_expired",
+                        {
+                            "session_id": session_id,
+                            "mission_id": mission_id,
+                            "expires_at": expires_at,
+                            "contract_version": session.get("contract_version"),
+                            "contract_hash": session.get("contract_hash"),
+                        },
+                    )
+            return False, "lease_expired", "session lease has expired"
+
+        if session.get("status") != "active":
+            return False, "lease_revoked", "session lease is revoked"
+
+        return True, "", ""
+
+    def authorize_session(
+        self,
+        mission_id: str,
+        contract_version: Any,
+        agent_identity: str,
+        role: str,
+        contribution: str,
+        expected_result: str,
+        duration_minutes: Any,
+        capabilities: list[str] | None,
+        criterion_ids: list[str] | None,
+        device_id: str | None = None,
+        harness_id: str | None = None,
+    ) -> dict[str, Any]:
+        err = self._reject_mission_id(mission_id)
+        if err:
+            return err
+
+        version, ver_err = strict_int(contract_version, "contract_version", min_value=1)
+        if ver_err:
+            return ver_err
+        assert version is not None
+
+        agent_identity = str(agent_identity or "").strip()
+        role = str(role or "").strip()
+        contribution = str(contribution or "").strip()
+        expected_result = str(expected_result or "").strip()
+        if not agent_identity:
+            return {"ok": False, "status": "denied", "error": "invalid_args", "message": "agent_identity is required"}
+        if not role:
+            return {"ok": False, "status": "denied", "error": "invalid_args", "message": "role is required"}
+        if not contribution:
+            return {
+                "ok": False,
+                "status": "denied",
+                "error": "invalid_args",
+                "message": "contribution is required",
+            }
+        if not expected_result:
+            return {
+                "ok": False,
+                "status": "denied",
+                "error": "invalid_args",
+                "message": "expected_result is required",
+            }
+
+        duration_raw, dur_err = strict_int(duration_minutes, "duration_minutes", min_value=1)
+        if dur_err:
+            return dur_err
+        assert duration_raw is not None
+
+        with mission_state_lock(self.cfg.hai_home):
+            meta = self.load_mission_meta(mission_id)
+            if not meta or meta.get("status") != "active":
+                return {"ok": False, "error": "mission_not_active", "message": f"mission not active: {mission_id}"}
+
+            contract = self.load_contract(mission_id, version)
+            if not contract:
+                return {
+                    "ok": False,
+                    "error": "contract_version_mismatch",
+                    "message": f"contract version {version} not found",
+                }
+            if int(meta["current_version"]) != version:
+                return {
+                    "ok": False,
+                    "status": "denied",
+                    "error": "contract_version_mismatch",
+                    "message": "requested contract version is stale",
+                    "current_version": meta["current_version"],
+                }
+
+            crit_ids = [str(c).strip() for c in (criterion_ids or []) if str(c).strip()]
+            valid_ids = {c["id"] for c in contract.get("done_criteria", [])}
+            if not crit_ids or not set(crit_ids).issubset(valid_ids):
+                return {
+                    "ok": False,
+                    "status": "denied",
+                    "error": "invalid_args",
+                    "message": "contribution must reference at least one valid done criterion id",
+                    "clause": "authorize_session.criterion_ids",
+                }
+
+            max_parallel = int(contract.get("constraints", {}).get("max_parallel_sessions", 1))
+            active_sessions = [s for s in self.list_sessions(mission_id) if s.get("status") == "active"]
+            now_valid = []
+            for s in active_sessions:
+                ok, _, _ = self._session_valid(s, contract)
+                if ok:
+                    now_valid.append(s)
+            if len(now_valid) >= max_parallel:
+                return {
+                    "ok": False,
+                    "status": "denied",
+                    "error": "parallel_session_denied",
+                    "message": f"max_parallel_sessions={max_parallel} already reached",
+                    "clause": "constraints.max_parallel_sessions",
+                }
+
+            duration = max(1, min(duration_raw, 24 * 60))
+            granted_caps = [str(c).strip() for c in (capabilities or []) if str(c).strip()]
+            allowed_caps = set(contract.get("constraints", {}).get("capabilities", []))
+            if granted_caps and not set(granted_caps).issubset(allowed_caps):
+                return {
+                    "ok": False,
+                    "status": "denied",
+                    "error": "invalid_args",
+                    "message": "requested capabilities exceed contract allowances",
+                    "clause": "constraints.capabilities",
+                }
+
+            contract_project_id = self._contract_project_id(contract)
+            lease_device_id: str | None = None
+            lease_harness_id: str | None = None
+
+            if contract_project_id:
+                if not device_id:
+                    return {
+                        "ok": False,
+                        "status": "denied",
+                        "error": "invalid_args",
+                        "message": "device_id is required when contract has project_id",
+                    }
+                ok, msg = validate_ident(str(device_id), "device_id")
+                if not ok:
+                    return {"ok": False, "status": "denied", "error": "invalid_args", "message": msg}
+                if self._projects().get_mount_path(contract_project_id, str(device_id)) is None:
+                    return {
+                        "ok": False,
+                        "status": "denied",
+                        "error": "device_mount_required",
+                        "message": f"no mount for device {device_id!r}",
+                    }
+                lease_device_id = str(device_id)
+            elif device_id:
+                ok, msg = validate_ident(str(device_id), "device_id")
+                if not ok:
+                    return {"ok": False, "status": "denied", "error": "invalid_args", "message": msg}
+                lease_device_id = str(device_id)
+
+            if harness_id:
+                ok, msg = validate_ident(str(harness_id), "harness_id")
+                if not ok:
+                    return {"ok": False, "status": "denied", "error": "invalid_args", "message": msg}
+                lease_harness_id = str(harness_id)
+
+            session_id = _new_id("S")
+            granted_at = _utc_now()
+            expires_at = time.strftime(
+                "%Y-%m-%dT%H:%M:%SZ",
+                time.gmtime(time.time() + duration * 60),
+            )
+            lease = {
+                "session_id": session_id,
+                "mission_id": mission_id,
+                "contract_version": version,
+                "contract_hash": contract["contract_hash"],
+                "agent_identity": agent_identity,
+                "role": role,
+                "contribution": contribution,
+                "expected_result": expected_result,
+                "criterion_ids": crit_ids,
+                "capabilities": granted_caps or sorted(allowed_caps),
+                "granted_at": granted_at,
+                "expires_at": expires_at,
+                "status": "active",
+            }
+            if lease_device_id:
+                lease["device_id"] = lease_device_id
+            if lease_harness_id:
+                lease["harness_id"] = lease_harness_id
+            self.save_session(lease)
+            audit = self.append_audit(
+                "session_authorized",
+                {"mission_id": mission_id, "session_id": session_id, "contract_version": version},
+            )
+            return {
+                "ok": True,
+                "status": "granted",
+                "session_id": session_id,
+                "session_lease": lease,
+                "audit_event_id": audit["event_id"],
+            }
+
+    def get_session(self, session_id: str) -> dict[str, Any] | None:
+        if self._reject_session_id(session_id):
+            return None
+        for mdir in sorted(self.missions_dir.glob("M-*")):
+            if not validate_mission_id(mdir.name)[0]:
+                continue
+            try:
+                sdir = self.sessions_dir(mdir.name)  # confined; raises if it escapes HAI_HOME
+                path = sdir / f"{session_id}.json"
+                assert_under(path, self.missions_dir)  # reject a symlinked session file
+            except (PathError, IdentifierError):
+                continue
+            # do not follow a symlinked session record out of the store
+            if not path.is_file() or path.is_symlink():
+                continue
+            data = read_json(path, {})
+            # bind stored ids to the directory and the requested id
+            if data.get("session_id") == session_id and data.get("mission_id") == mdir.name:
+                return data
+        return None
+
+    def get_contract(self, session_id: str) -> dict[str, Any]:
+        err = self._reject_session_id(session_id)
+        if err:
+            return err
+
+        session = self.get_session(session_id)
+        if not session:
+            return {"ok": False, "error": "invalid_args", "message": f"session not found: {session_id}"}
+
+        contract = self.current_contract(session["mission_id"])
+        if not contract:
+            return {"ok": False, "error": "contract_version_mismatch", "message": "contract missing for session"}
+
+        ok, code, message = self._session_valid(session, contract)
+        if not ok:
+            return {
+                "ok": False,
+                "error": code,
+                "message": message,
+                "required_action": "pause",
+            }
+
+        remaining_seconds = 0
+        expires_at = session.get("expires_at")
+        if expires_at:
+            try:
+                exp_struct = time.strptime(str(expires_at), "%Y-%m-%dT%H:%M:%SZ")
+                remaining_seconds = max(0, int(calendar.timegm(exp_struct) - time.time()))
+            except ValueError:
+                remaining_seconds = 0
+
+        project_id = self._contract_project_id(contract)
+        session_device_id = session.get("device_id")
+        mount_path: str | None = None
+        if project_id and session_device_id:
+            mp = self._projects().get_mount_path(project_id, str(session_device_id))
+            if mp is not None:
+                mount_path = str(mp)
+
+        return {
+            "ok": True,
+            "session_id": session_id,
+            "mission_id": session["mission_id"],
+            "contract_version": contract["contract_version"],
+            "contract_hash": contract["contract_hash"],
+            "remaining_seconds": remaining_seconds,
+            "expires_at": expires_at,
+            "project_id": project_id,
+            "device_id": session_device_id,
+            "mount_path": mount_path,
+            "contract": contract,
+            "done_criteria": contract.get("done_criteria", []),
+            "non_goals": contract.get("non_goals", []),
+        }
+
+    def _matches_non_goal(self, text: str, non_goals: list[str]) -> str | None:
+        lowered = text.lower()
+        for ng in non_goals:
+            token = ng.lower().strip()
+            if token and token in lowered:
+                return ng
+        return None
+
+    def _path_allowed(
+        self,
+        contract: dict[str, Any],
+        raw_path: str,
+        session: dict[str, Any] | None = None,
+    ) -> tuple[bool, str | None]:
+        constraints = contract.get("constraints", {})
+        allowed_paths = constraints.get("allowed_paths", [])
+        if not raw_path:
+            return True, None
+        root, root_err = self._resolve_project_root(contract, session=session)
+        if root_err:
+            return False, root_err.get("message", "device mount required")
+        if not root:
+            return False, "no project_path configured; path cannot be validated against a root"
+        raw = str(raw_path)
+        if "\x00" in raw:
+            return False, "path contains a null byte"
+        try:
+            path = Path(raw).expanduser()
+            if not path.is_absolute():
+                path = root / path
+            assert_relative_allowed(path, root, allowed_paths or [])
+            return True, None
+        except PathError as exc:
+            return False, exc.message
+        except (OSError, ValueError) as exc:
+            return False, f"invalid path: {exc}"
+
+    def check_activity(
+        self,
+        session_id: str,
+        activity_step: str,
+        affected_paths: list[str] | None = None,
+        trace_events: list[dict[str, Any]] | None = None,
+        criterion_id: str | None = None,
+        activity_kind: str | None = None,
+        evidence: dict[str, Any] | None = None,
+        declares_blocker: Any = False,
+    ) -> dict[str, Any]:
+        err = self._reject_session_id(session_id)
+        if err:
+            return {
+                **err,
+                "classification": "unclear",
+                "required_action": "pause",
+            }
+
+        session = self.get_session(session_id)
+        if not session:
+            return {
+                "ok": False,
+                "error": "invalid_args",
+                "message": f"session not found: {session_id}",
+                "classification": "unclear",
+                "required_action": "pause",
+            }
+
+        contract = self.current_contract(session["mission_id"])
+        if not contract:
+            return {
+                "ok": False,
+                "error": "contract_version_mismatch",
+                "classification": "unclear",
+                "required_action": "pause",
+            }
+
+        ok, code, message = self._session_valid(session, contract)
+        if not ok:
+            return {
+                "ok": False,
+                "error": code,
+                "message": message,
+                "classification": "unclear",
+                "required_action": "pause",
+            }
+
+        step = str(activity_step or "").strip()
+        crit_id = str(criterion_id or "").strip()
+        valid_ids = {c["id"] for c in contract.get("done_criteria", [])}
+        session_crits = set(session.get("criterion_ids", []))
+        non_goals = contract.get("non_goals", [])
+        caps = set(session.get("capabilities", []))
+
+        classification = "unclear"
+        required_action = "pause"
+        reason = "no observable authorized linkage to contract criteria"
+        clause: str | None = None
+
+        path_violation: tuple[str, str] | None = None
+        for raw in affected_paths or []:
+            allowed, err_msg = self._path_allowed(contract, raw, session=session)
+            if not allowed:
+                path_violation = (err_msg or f"path outside allowed scope: {raw}", "constraints.allowed_paths")
+                break
+
+        cap_violation: tuple[str, str] | None = None
+        if path_violation is None:
+            for event in trace_events or []:
+                action = str(event.get("action", "")).strip().lower()
+                if action in SENSITIVE_TRACE_ACTIONS and action not in caps:
+                    cap_violation = (f"trace action {action} lacks capability", "constraints.capabilities")
+                    break
+
+        if path_violation:
+            classification = "drift"
+            required_action = "stop"
+            reason, clause = path_violation
+        elif cap_violation:
+            classification = "drift"
+            required_action = "stop"
+            reason, clause = cap_violation
+        elif not step:
+            classification = "unclear"
+            required_action = "pause"
+            reason = "missing activity_step"
+        elif not crit_id:
+            classification = "unclear"
+            required_action = "pause"
+            reason = "missing done criterion reference"
+            clause = "done_criteria.reference_required"
+        elif crit_id not in valid_ids:
+            classification = "drift"
+            required_action = "stop"
+            reason = f"criterion {crit_id} is not part of the contract"
+            clause = "done_criteria.scope"
+        elif crit_id not in session_crits:
+            classification = "drift"
+            required_action = "request_recontract"
+            reason = f"session not authorized for criterion {crit_id}"
+            clause = "session.criterion_ids"
+        else:
+            ng = self._matches_non_goal(step, non_goals)
+            if ng:
+                classification = "park_candidate"
+                required_action = "park"
+                reason = f"activity matches non-goal: {ng}"
+                clause = "non_goals"
+            elif declares_blocker is True:
+                classification = "blocker"
+                required_action = "pause"
+                reason = "activity declares a blocker preventing artifact completion"
+                clause = "done_criteria.blocked"
+            else:
+                classification = "in_scope"
+                required_action = "continue"
+                reason = "activity aligns with authorized session criteria and paths"
+
+        trace_actions = [
+            str(event.get("action", "")).strip().lower()
+            for event in (trace_events or [])
+            if str(event.get("action", "")).strip()
+        ]
+        result = {
+            "ok": True,
+            "session_id": session_id,
+            "mission_id": session["mission_id"],
+            "contract_version": contract["contract_version"],
+            "classification": classification,
+            "required_action": required_action,
+            "reason": reason,
+            "clause": clause,
+            "activity_kind": activity_kind,
+            "criterion_id": crit_id or None,
+            "evidence": evidence,
+        }
+        self.append_audit(
+            "activity_checked",
+            {
+                "session_id": session_id,
+                "mission_id": session["mission_id"],
+                "contract_version": contract["contract_version"],
+                "contract_hash": contract.get("contract_hash"),
+                "classification": classification,
+                "required_action": required_action,
+                "reason": reason,
+                "clause": clause,
+                "activity_step_present": bool(step),
+                "criterion_id": crit_id or None,
+                "declares_blocker": declares_blocker,
+                "affected_path_count": len(affected_paths or []),
+                "trace_action_count": len(trace_actions),
+                "trace_actions": trace_actions,
+                "activity_kind": activity_kind,
+            },
+        )
+        return result
+
+    def park_item(
+        self,
+        idea: str,
+        origin_session_id: str,
+        trigger_event: str,
+        mission_id: str,
+        rationale: str,
+    ) -> dict[str, Any]:
+        idea = str(idea or "").strip()
+        rationale = str(rationale or "").strip()
+        trigger_event = str(trigger_event or "").strip()
+        if not idea:
+            return {"ok": False, "error": "invalid_args", "message": "idea is required"}
+        if not rationale:
+            return {"ok": False, "error": "invalid_args", "message": "rationale is required for mission-linked parking"}
+        if not trigger_event:
+            return {"ok": False, "error": "invalid_args", "message": "trigger_event is required"}
+
+        err = self._reject_mission_id(mission_id)
+        if err:
+            return err
+        origin_err = self._reject_session_id(origin_session_id)
+        if origin_err:
+            return origin_err
+
+        meta = self.load_mission_meta(mission_id)
+        if not meta:
+            return {"ok": False, "error": "invalid_args", "message": f"mission not found: {mission_id}"}
+
+        origin = self.get_session(origin_session_id)
+        if not origin or origin.get("mission_id") != mission_id:
+            return {
+                "ok": False,
+                "error": "invalid_args",
+                "message": "origin_session_id must belong to the stated active mission",
+            }
+
+        parking_id = _new_id("P")
+        record = {
+            "parking_id": parking_id,
+            "status": "parked",
+            "idea": idea,
+            "origin_session_id": origin_session_id,
+            "trigger_event": trigger_event,
+            "mission_id": mission_id,
+            "rationale": rationale,
+            "parked_at": _utc_now(),
+            "actionable": False,
+        }
+        write_json(self.parking_dir / f"{parking_id}.json", record)
+        audit = self.append_audit("item_parked", {"parking_id": parking_id, "mission_id": mission_id})
+        return {
+            "ok": True,
+            "parking_id": parking_id,
+            "status": "parked",
+            "record": record,
+            "audit_event_id": audit["event_id"],
+            "message": "parked without execution rights; contract unchanged",
+        }
+
+    def _mutable_field_diff(self, old: dict[str, Any], new: dict[str, Any]) -> list[dict[str, Any]]:
+        diff: list[dict[str, Any]] = []
+        for key in sorted(RECONTRACT_MUTABLE_FIELDS):
+            ov = old.get(key)
+            nv = new.get(key)
+            if ov != nv:
+                diff.append({"field": key, "old": ov, "new": nv})
+        return diff
+
+    def _build_recontract_candidate(
+        self,
+        old_contract: dict[str, Any],
+        changes: dict[str, Any],
+    ) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+        if not isinstance(changes, dict):
+            return None, {"ok": False, "error": "invalid_args", "message": "changes must be an object"}
+
+        for key in changes:
+            if key in RECONTRACT_SYSTEM_FIELDS:
+                return None, {
+                    "ok": False,
+                    "error": "invalid_args",
+                    "message": f"system-managed field cannot be changed via recontract: {key}",
+                }
+            if key not in RECONTRACT_MUTABLE_FIELDS:
+                return None, {
+                    "ok": False,
+                    "error": "invalid_args",
+                    "message": f"unknown recontract field: {key}",
+                }
+
+        candidate = copy.deepcopy(old_contract)
+        for key in RECONTRACT_MUTABLE_FIELDS:
+            if key in changes:
+                candidate[key] = copy.deepcopy(changes[key])
+
+        old_owner = old_contract.get("constraints", {}).get("owner")
+        old_project_id = old_contract.get("constraints", {}).get("project_id")
+        old_project_path = old_contract.get("constraints", {}).get("project_path")
+        if "constraints" in changes:
+            new_constraints = changes.get("constraints")
+            if isinstance(new_constraints, dict) and "project_id" in new_constraints:
+                if new_constraints.get("project_id") != old_project_id:
+                    return None, {
+                        "ok": False,
+                        "error": "invalid_args",
+                        "message": "project_id cannot be changed via recontract",
+                    }
+        candidate_constraints = dict(candidate.get("constraints") or {})
+        candidate_constraints["owner"] = old_owner
+        candidate_constraints["project_id"] = old_project_id
+        if old_project_id:
+            candidate_constraints["project_path"] = None
+        else:
+            candidate_constraints["project_path"] = old_project_path
+        candidate["constraints"] = candidate_constraints
+
+        body, issues, validation = self._validate_open_payload(
+            objective=str(candidate.get("objective", "")),
+            artifact=str(candidate.get("artifact", "")),
+            done_criteria=candidate.get("done_criteria"),
+            non_goals=candidate.get("non_goals"),
+            constraints=candidate.get("constraints"),
+            owner=str(old_owner or ""),
+        )
+        if validation == "review_required":
+            return None, {
+                "ok": False,
+                "error": "invalid_args",
+                "message": "recontract candidate failed contract validation",
+                "issues": issues,
+            }
+
+        candidate.update(body)
+        candidate["mission_id"] = old_contract["mission_id"]
+        candidate["contract_version"] = old_contract["contract_version"]
+        candidate["status"] = old_contract.get("status", "active")
+        candidate["created_at"] = old_contract.get("created_at")
+        candidate.pop("contract_hash", None)
+        return candidate, None
+
+    def recontract(
+        self,
+        mission_id: str,
+        contract_version: Any,
+        reason: str,
+        changes: dict[str, Any],
+        mode: str = "normal",
+        owner_ack: Any = False,
+        break_glass_marker: Any = False,
+    ) -> dict[str, Any]:
+        err = self._reject_mission_id(mission_id)
+        if err:
+            return err
+
+        reason = str(reason or "").strip()
+        mode = str(mode or "normal").strip().lower()
+        if not reason:
+            return {"ok": False, "error": "invalid_args", "message": "reason is required"}
+        if mode not in VALID_RECONTRACT_MODES:
+            return {
+                "ok": False,
+                "error": "invalid_args",
+                "message": f"mode must be one of: {', '.join(sorted(VALID_RECONTRACT_MODES))}",
+            }
+
+        version, ver_err = strict_int(contract_version, "contract_version", min_value=1)
+        if ver_err:
+            return ver_err
+        assert version is not None
+
+        meta = self.load_mission_meta(mission_id)
+        if not meta or meta.get("status") != "active":
+            return {"ok": False, "error": "mission_not_active", "message": "mission is not active"}
+
+        if int(meta["current_version"]) != version:
+            return {
+                "ok": False,
+                "error": "contract_version_mismatch",
+                "message": "stale contract version",
+                "current_version": meta["current_version"],
+            }
+
+        old_contract = self.load_contract(mission_id, version)
+        if not old_contract:
+            return {"ok": False, "error": "contract_version_mismatch", "message": "contract not found"}
+
+        candidate, candidate_err = self._build_recontract_candidate(old_contract, changes)
+        if candidate_err:
+            return candidate_err
+        assert candidate is not None
+
+        diff = self._mutable_field_diff(old_contract, candidate)
+        if not diff:
+            return {"ok": False, "error": "invalid_args", "message": "recontract changes produce an empty diff"}
+
+        if owner_ack is not True:
+            return {
+                "ok": False,
+                "error": "owner_gate_required",
+                "status": "pending_owner_confirmation",
+                "owner_ack_required": True,
+                "diff": diff,
+                "mode": mode,
+                "message": "owner_ack=true (literal boolean) required to apply contract changes",
+            }
+
+        if mode == "break_glass" and break_glass_marker is not True:
+            return {
+                "ok": False,
+                "error": "owner_gate_required",
+                "message": "break_glass mode requires break_glass_marker=true",
+                "audit_classification": "break_glass_denied",
+            }
+
+        with mission_state_lock(self.cfg.hai_home):
+            meta = self.load_mission_meta(mission_id)
+            if not meta or meta.get("status") != "active":
+                return {"ok": False, "error": "mission_not_active", "message": "mission is not active"}
+            if int(meta["current_version"]) != version:
+                return {
+                    "ok": False,
+                    "error": "contract_version_mismatch",
+                    "message": "stale contract version",
+                    "current_version": meta["current_version"],
+                }
+
+            revoked = self.revoke_all_sessions(mission_id, reason="recontract")
+
+            new_version = int(meta["current_version"]) + 1
+            new_contract = copy.deepcopy(candidate)
+            new_contract["contract_version"] = new_version
+            new_contract["status"] = "active"
+            new_contract["recontracted_at"] = _utc_now()
+            new_contract["recontract_reason"] = reason
+            new_contract["recontract_mode"] = mode
+            new_contract.pop("contract_hash", None)
+            new_contract["contract_hash"] = contract_hash(new_contract)
+
+            write_json(self.contract_path(mission_id, new_version), new_contract)
+            meta["current_version"] = new_version
+            write_json(self.mission_dir(mission_id) / "mission.json", meta)
+
+        audit_payload = {
+            "mission_id": mission_id,
+            "old_version": version,
+            "new_version": new_version,
+            "diff": diff,
+            "mode": mode,
+            "reason": reason,
+            "revoked_sessions": revoked,
+        }
+        if mode == "break_glass":
+            audit_payload["audit_classification"] = "break_glass"
+        audit = self.append_audit("mission_recontracted", audit_payload)
+
+        return {
+            "ok": True,
+            "status": "approved",
+            "mission_id": mission_id,
+            "contract_version": new_version,
+            "contract_hash": new_contract["contract_hash"],
+            "diff": diff,
+            "contract": new_contract,
+            "revoked_sessions": revoked,
+            "audit_event_id": audit["event_id"],
+            "audit_classification": audit_payload.get("audit_classification"),
+        }
+
+    def _verify_evidence_path(
+        self,
+        contract: dict[str, Any],
+        raw_path: str,
+        device_id: str | None = None,
+    ) -> tuple[Path | None, str | None, dict[str, Any] | None]:
+        if not raw_path or not str(raw_path).strip():
+            return None, "evidence path is required", {"error": "invalid_args", "criterion_id": None}
+        raw = str(raw_path)
+        if "\x00" in raw:
+            return None, "evidence path contains a null byte", {"error": "invalid_args", "path": raw}
+        root, root_err = self._resolve_project_root(contract, device_id=device_id)
+        if root_err:
+            return None, root_err.get("message", "device mount required"), {
+                "error": root_err.get("error", "device_mount_required"),
+                "path": raw,
+            }
+        if not root:
+            return None, "no project_path configured; evidence cannot be validated", {
+                "error": "invalid_args",
+                "path": raw,
+            }
+        try:
+            project = root
+            path = Path(raw).expanduser()
+            if not path.is_absolute():
+                path = project / path
+            # Confinement is checked BEFORE any existence/type/read probe.
+            if path.is_symlink():
+                target = real_path(path)
+                try:
+                    target.relative_to(real_path(project))
+                except ValueError:
+                    return None, "evidence path escapes project via symlink", {
+                        "error": "path_outside_root",
+                        "path": str(path),
+                        "root": str(project),
+                    }
+            confined = assert_under(path, project)
+            if not confined.exists():
+                return None, f"evidence path does not exist: {raw}", {"error": "invalid_args", "path": raw}
+            if confined.is_dir():
+                return None, f"evidence path is a directory, not a readable file: {raw}", {
+                    "error": "invalid_args",
+                    "path": raw,
+                }
+            if not confined.is_file():
+                return None, f"evidence path is not a readable file: {raw}", {
+                    "error": "invalid_args",
+                    "path": raw,
+                }
+            digest = hashlib.sha256(confined.read_bytes()).hexdigest()
+            return confined, None, {"path": str(confined), "sha256": f"sha256:{digest}"}
+        except PathError as exc:
+            return None, exc.message, exc.as_dict()
+        except (OSError, ValueError) as exc:
+            return None, f"evidence file is not readable: {raw}", {
+                "error": "invalid_args",
+                "path": raw,
+                "message": str(exc),
+            }
+
+    def close_mission(
+        self,
+        mission_id: str,
+        contract_version: Any,
+        evidence: dict[str, Any] | None,
+        outcome_summary: str,
+        closure: str,
+        owner_ack: Any = False,
+        device_id: str | None = None,
+    ) -> dict[str, Any]:
+        err = self._reject_mission_id(mission_id)
+        if err:
+            return err
+
+        closure = str(closure or "").strip().lower()
+        outcome_summary = str(outcome_summary or "").strip()
+
+        version, ver_err = strict_int(contract_version, "contract_version", min_value=1)
+        if ver_err:
+            return ver_err
+        assert version is not None
+
+        meta = self.load_mission_meta(mission_id)
+        if not meta or meta.get("status") != "active":
+            return {"ok": False, "error": "mission_not_active", "message": "mission is not active"}
+
+        if int(meta["current_version"]) != version:
+            return {
+                "ok": False,
+                "error": "contract_version_mismatch",
+                "message": "stale contract version",
+                "current_version": meta["current_version"],
+            }
+
+        contract = self.load_contract(mission_id, version)
+        if not contract:
+            return {"ok": False, "error": "contract_version_mismatch", "message": "contract not found"}
+
+        contract_project_id = self._contract_project_id(contract)
+        if contract_project_id:
+            if not device_id:
+                return {
+                    "ok": False,
+                    "error": "invalid_args",
+                    "message": "device_id is required when contract has project_id",
+                }
+            ok, msg = validate_ident(str(device_id), "device_id")
+            if not ok:
+                return {"ok": False, "error": "invalid_args", "message": msg}
+            if self._projects().get_mount_path(contract_project_id, str(device_id)) is None:
+                return {
+                    "ok": False,
+                    "error": "device_mount_required",
+                    "message": f"no mount for device {device_id!r}",
+                }
+
+        if closure == "abandoned":
+            if owner_ack is not True:
+                return {
+                    "ok": False,
+                    "error": "owner_gate_required",
+                    "message": "abandon requires owner_ack=true (literal boolean)",
+                }
+            if not outcome_summary:
+                return {"ok": False, "error": "invalid_args", "message": "abandon reason required in outcome_summary"}
+            with mission_state_lock(self.cfg.hai_home):
+                revoked = self.revoke_all_sessions(mission_id, reason="abandoned")
+                meta = self.load_mission_meta(mission_id) or meta
+                meta["status"] = "abandoned"
+                meta["closed_at"] = _utc_now()
+                meta["abandon_reason"] = outcome_summary
+                write_json(self.mission_dir(mission_id) / "mission.json", meta)
+                self.save_active_pointer(None, "none")
+            audit = self.append_audit(
+                "mission_abandoned",
+                {"mission_id": mission_id, "reason": outcome_summary, "revoked_sessions": revoked},
+            )
+            return {
+                "ok": True,
+                "status": "abandoned",
+                "mission_id": mission_id,
+                "reason": outcome_summary,
+                "revoked_sessions": revoked,
+                "audit_event_id": audit["event_id"],
+                "next_mission": None,
+            }
+
+        if closure != "completed":
+            return {"ok": False, "error": "invalid_args", "message": "closure must be completed or abandoned"}
+
+        if not outcome_summary:
+            return {"ok": False, "error": "invalid_args", "message": "outcome_summary is required for completion"}
+
+        if not isinstance(evidence, dict):
+            return {"ok": False, "error": "invalid_args", "message": "evidence must be an object mapping criterion ids to records"}
+
+        verified: dict[str, Any] = {}
+        missing: list[str] = []
+        invalid: list[dict[str, Any]] = []
+        for crit in contract.get("done_criteria", []):
+            cid = crit["id"]
+            item = evidence.get(cid)
+            if not isinstance(item, dict):
+                missing.append(cid)
+                continue
+            raw_path = item.get("path")
+            if not raw_path or not str(raw_path).strip():
+                invalid.append(
+                    {
+                        "criterion_id": cid,
+                        "error": "invalid_args",
+                        "message": "evidence record requires a non-empty path",
+                    }
+                )
+                continue
+            _, err_msg, meta_ev = self._verify_evidence_path(contract, str(raw_path), device_id=device_id)
+            if err_msg:
+                item_out: dict[str, Any] = {"criterion_id": cid, "message": err_msg}
+                if meta_ev:
+                    item_out.update(meta_ev)
+                invalid.append(item_out)
+                continue
+            verified[cid] = meta_ev
+
+        if missing or invalid:
+            return {
+                "ok": True,
+                "status": "incomplete",
+                "missing_criteria": missing,
+                "invalid_evidence": invalid,
+                "verified_criteria": verified,
+                "message": "completion requires verified evidence for every criterion",
+            }
+
+        with mission_state_lock(self.cfg.hai_home):
+            revoked = self.revoke_all_sessions(mission_id, reason="completed")
+            meta = self.load_mission_meta(mission_id) or meta
+            meta["status"] = "completed"
+            meta["closed_at"] = _utc_now()
+            meta["outcome_summary"] = outcome_summary
+            write_json(self.mission_dir(mission_id) / "mission.json", meta)
+            self.save_active_pointer(None, "none")
+        audit = self.append_audit(
+            "mission_completed",
+            {
+                "mission_id": mission_id,
+                "verified_criteria": verified,
+                "outcome_summary": outcome_summary,
+                "revoked_sessions": revoked,
+            },
+        )
+        return {
+            "ok": True,
+            "status": "completed",
+            "mission_id": mission_id,
+            "verified_criteria": verified,
+            "outcome_summary": outcome_summary,
+            "revoked_sessions": revoked,
+            "audit_event_id": audit["event_id"],
+            "next_mission": None,
+        }
+
+    def list_audit_ids(self) -> list[str]:
+        return sorted(p.stem for p in self.audit_dir.glob("A-*.json"))

hai-mcp-pr7/src/hai_mcp/paths.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from hai_mcp.config import Config
+
+
+class PathError(ValueError):
+    def __init__(self, code: str, message: str, *, path: str | None = None, root: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.path = path
+        self.root = root
+
+    def as_dict(self) -> dict[str, str]:
+        out: dict[str, str] = {"error": self.code, "message": self.message}
+        if self.path is not None:
+            out["path"] = self.path
+        if self.root is not None:
+            out["root"] = self.root
+        return out
+
+
+def resolve_project_path(project_path: str | None) -> Path | None:
+    if project_path is None or not str(project_path).strip():
+        return None
+    return Path(project_path).expanduser().resolve()
+
+
+def require_project_path(project_path: str | None) -> Path:
+    path = resolve_project_path(project_path)
+    if path is None:
+        raise PathError("invalid_args", "project_path is required")
+    if not path.exists():
+        raise PathError("missing_project", f"project path does not exist: {path}", path=str(path))
+    if not path.is_dir():
+        raise PathError("missing_project", f"project path is not a directory: {path}", path=str(path))
+    return path
+
+
+def artifact_dir(cfg: Config, project: Path) -> Path:
+    return project / cfg.artifact_dir_name
+
+
+def confined_artifact_dir(cfg: Config, project: Path) -> Path:
+    """Resolve artifact dir under *project*; reject symlink escape outside project root."""
+    project_r = real_path(project)
+    ad = project / cfg.artifact_dir_name
+    if ad.is_symlink():
+        target = real_path(ad)
+        try:
+            target.relative_to(project_r)
+        except ValueError as exc:
+            raise PathError(
+                "path_outside_root",
+                "artifact directory symlink escapes project root",
+                path=str(target),
+                root=str(project_r),
+            ) from exc
+        return target
+    return assert_under(ad, project_r)
+
+
+def ensure_artifact_dir(cfg: Config, project: Path) -> Path:
+    d = confined_artifact_dir(cfg, project)
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def real_path(path: Path) -> Path:
+    return Path(os.path.realpath(path))
+
+
+def assert_under(path: Path, root: Path) -> Path:
+    """Resolve *path* and ensure its real path stays under *root* (symlink-safe)."""
+    resolved = real_path(path.expanduser())
+    root_r = real_path(root)
+    try:
+        resolved.relative_to(root_r)
+    except ValueError as exc:
+        raise PathError(
+            "path_outside_root",
+            f"path {resolved} is outside allowed root {root_r}",
+            path=str(resolved),
+            root=str(root_r),
+        ) from exc
+    return resolved
+
+
+def resolve_under_root(root: Path, candidate: str | Path, *, relative_to_root: bool = True) -> Path:
+    """Central fail-closed resolver.
+
+    Rejects null bytes / invalid types before any filesystem call, interprets a
+    relative *candidate* under *root* (never the process CWD), then proves the
+    real path stays under *root* via symlink-safe resolution. Raises PathError on
+    escape. The caller checks existence/type AFTER this returns.
+    """
+    if candidate is None or not isinstance(candidate, (str, Path)):
+        raise PathError("invalid_args", "path must be a string")
+    raw = str(candidate)
+    if "\x00" in raw:
+        raise PathError("invalid_args", "path contains a null byte")
+    p = Path(raw).expanduser()
+    if relative_to_root and not p.is_absolute():
+        p = Path(root) / p
+    return assert_under(p, root)
+
+
+def assert_relative_allowed(path: Path, project_root: Path, allowed_paths: list[str]) -> Path:
+    """Ensure *path* is under *project_root* and matches one allowed relative prefix."""
+    confined = assert_under(path, project_root)
+    rel = confined.relative_to(real_path(project_root))
+    rel_posix = rel.as_posix()
+    if not allowed_paths:
+        return confined
+    for prefix in allowed_paths:
+        norm = prefix.strip().strip("/")
+        if not norm:
+            continue
+        if rel_posix == norm or rel_posix.startswith(norm + "/"):
+            return confined
+    raise PathError(
+        "path_outside_root",
+        f"path {confined} is outside allowed project prefixes {allowed_paths}",
+        path=str(confined),
+        root=str(real_path(project_root)),
+    )

hai-mcp-pr7/src/hai_mcp/projects.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import re
+import time
+from pathlib import Path
+from typing import Any
+
+from hai_mcp.paths import PathError, assert_under, real_path, require_project_path
+from hai_mcp.storage import read_json, write_json
+
+IDENT_RE = re.compile(r"^[a-z][a-z0-9-]{1,63}$")
+
+
+def _utc_now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def validate_ident(value: str, field: str) -> tuple[bool, str]:
+    raw = str(value or "").strip()
+    if not raw:
+        return False, f"{field} is required"
+    if not IDENT_RE.match(raw):
+        return (
+            False,
+            f"{field} must match ^[a-z][a-z0-9-]{{1,63}}$ (got {raw!r})",
+        )
+    return True, ""
+
+
+class ProjectStore:
+    """Logical project registry with per-device mount paths under HAI_HOME/core/projects.json."""
+
+    def __init__(self, hai_home: Path) -> None:
+        self.core_dir = hai_home / "core"
+        self.projects_path = self.core_dir / "projects.json"
+
+    def load(self) -> dict[str, Any]:
+        return read_json(self.projects_path, {"version": 1, "projects": {}})
+
+    def save(self, data: dict[str, Any]) -> None:
+        self.core_dir.mkdir(parents=True, exist_ok=True)
+        write_json(self.projects_path, data)
+
+    def get_mount_path(self, project_id: str, device_id: str) -> Path | None:
+        ok, _ = validate_ident(project_id, "project_id")
+        if not ok:
+            return None
+        ok, _ = validate_ident(device_id, "device_id")
+        if not ok:
+            return None
+        data = self.load()
+        project = data.get("projects", {}).get(project_id)
+        if not isinstance(project, dict):
+            return None
+        mount = project.get("mounts", {}).get(device_id)
+        if not isinstance(mount, dict):
+            return None
+        raw_path = mount.get("path")
+        if not raw_path:
+            return None
+        return Path(str(raw_path))
+
+    def bind_mount(
+        self,
+        project_id: str,
+        device_id: str,
+        local_path: str | Path,
+    ) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+        """Validate and persist a device mount. Returns (mount_record, error_dict)."""
+        ok, msg = validate_ident(project_id, "project_id")
+        if not ok:
+            return None, {"ok": False, "error": "invalid_args", "message": msg}
+        ok, msg = validate_ident(device_id, "device_id")
+        if not ok:
+            return None, {"ok": False, "error": "invalid_args", "message": msg}
+
+        try:
+            resolved = require_project_path(str(local_path))
+        except PathError as exc:
+            return None, {"ok": False, "error": exc.code, "message": exc.message}
+
+        raw = Path(str(local_path)).expanduser()
+        if raw.is_symlink():
+            try:
+                assert_under(real_path(raw), real_path(raw.parent))
+            except PathError as exc:
+                return None, {"ok": False, "error": exc.code, "message": exc.message}
+
+        data = self.load()
+        projects = data.setdefault("projects", {})
+        project = projects.setdefault(
+            project_id,
+            {"project_id": project_id, "mounts": {}},
+        )
+        mounts = project.setdefault("mounts", {})
+        record = {
+            "path": str(real_path(resolved)),
+            "bound_at": _utc_now(),
+        }
+        mounts[device_id] = record
+        self.save(data)
+        return record, None
+
+    def list_projects(self) -> list[dict[str, Any]]:
+        data = self.load()
+        out: list[dict[str, Any]] = []
+        for pid in sorted(data.get("projects", {})):
+            mounts = data["projects"][pid].get("mounts", {})
+            out.append({"project_id": pid, "device_ids": sorted(mounts.keys())})
+        return out

hai-mcp-pr7/src/hai_mcp/server.py

@@ -0,0 +1,455 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from typing import Any
+
+import anyio
+from mcp.server.fastmcp import FastMCP
+
+from hai_mcp.boundary import strict_optional_time_limit_hours
+from hai_mcp.config import Config, SERVER_NAME
+from hai_mcp.http_transport import http_bind_allowed, http_token_from_env, wrap_with_bearer_token
+from hai_mcp.state import ControlPlane
+
+mcp = FastMCP(SERVER_NAME)
+
+_cp: ControlPlane | None = None
+
+
+def get_control_plane() -> ControlPlane:
+    global _cp
+    if _cp is None:
+        _cp = ControlPlane(Config.from_env())
+    return _cp
+
+
+def _json(result: dict[str, Any]) -> str:
+    return json.dumps(result, indent=2, ensure_ascii=False, sort_keys=True)
+
+
+@mcp.tool()
+def hai_health(project_path: str | None = None) -> str:
+    """Check HAI-MCP server health and optional project path usability. No model calls."""
+    return _json(get_control_plane().health(project_path))
+
+
+@mcp.tool()
+def hai_status(project_path: str | None = None) -> str:
+    """Return ACTIVE lanes, focus, inbox count, and optional project next-step flags."""
+    return _json(get_control_plane().status(project_path))
+
+
+@mcp.tool()
+def hai_get_next_step(project_path: str) -> str:
+    """Read the canonical NEXT_STEP.md for a project (or report none)."""
+    return _json(get_control_plane().get_next_step(project_path))
+
+
+@mcp.tool()
+def hai_read_artifacts(project_path: str, max_chars: Any = 4000) -> str:
+    """Read-only summary of HAI Projek-Managment run-contract artifacts."""
+    return _json(get_control_plane().read_artifacts(project_path, max_chars=max_chars))
+
+
+@mcp.tool()
+def hai_park(text: str, tags: list[str] | None = None) -> str:
+    """Park a thought/meta item in HAI inbox without changing ACTIVE lanes."""
+    return _json(get_control_plane().park(text, tags=tags))
+
+
+@mcp.tool()
+def hai_set_focus(
+    focus_id: str,
+    project_path: str | None = None,
+    label: str | None = None,
+) -> str:
+    """Set focus and register an ACTIVE lane (max 2). Fails if a third ACTIVE is requested."""
+    return _json(get_control_plane().set_focus(focus_id, project_path=project_path, label=label))
+
+
+@mcp.tool()
+def hai_propose_next_step(project_path: str, content: str) -> str:
+    """Write NEXT_STEP.proposed.md (not canonical). Promote via hai_accept_next_step."""
+    return _json(get_control_plane().propose_next_step(project_path, content))
+
+
+@mcp.tool()
+def hai_accept_next_step(
+    project_path: str,
+    owner_ack: Any,
+    reason: str,
+    content: str | None = None,
+) -> str:
+    """Promote proposed (or provided) content to canonical NEXT_STEP.md. Requires owner_ack=true + reason."""
+    return _json(
+        get_control_plane().accept_next_step(
+            project_path,
+            owner_ack=owner_ack,
+            reason=reason,
+            content=content,
+        )
+    )
+
+
+@mcp.tool()
+def hai_checkpoint(note: str | None = None, project_path: str | None = None) -> str:
+    """Snapshot ACTIVE_CONTEXT and optional project artifacts under HAI_HOME/history/checkpoints."""
+    return _json(get_control_plane().checkpoint(note=note, project_path=project_path))
+
+
+@mcp.tool()
+def hai_recover(checkpoint_id: str | None = None) -> str:
+    """Return the smallest recovery next action from latest or named checkpoint (read-only advice)."""
+    return _json(get_control_plane().recover(checkpoint_id=checkpoint_id))
+
+
+@mcp.tool()
+def hai_open_mission(
+    objective: str,
+    artifact: str,
+    done_criteria: list[dict[str, Any]],
+    owner: str,
+    non_goals: list[str] | None = None,
+    constraints: dict[str, Any] | None = None,
+) -> str:
+    """Open a bounded mission with a versioned canonical contract. One active mission globally."""
+    return _json(
+        get_control_plane().open_mission(
+            objective=objective,
+            artifact=artifact,
+            done_criteria=done_criteria,
+            non_goals=non_goals,
+            constraints=constraints,
+            owner=owner,
+        )
+    )
+
+
+@mcp.tool()
+def hai_authorize_session(
+    mission_id: str,
+    contract_version: Any,
+    agent_identity: str,
+    role: str,
+    contribution: str,
+    expected_result: str,
+    duration_minutes: Any,
+    criterion_ids: list[str],
+    capabilities: list[str] | None = None,
+    device_id: str | None = None,
+    harness_id: str | None = None,
+) -> str:
+    """Grant a time-bounded session lease tied to mission ID and exact contract version."""
+    return _json(
+        get_control_plane().authorize_session(
+            mission_id=mission_id,
+            contract_version=contract_version,
+            agent_identity=agent_identity,
+            role=role,
+            contribution=contribution,
+            expected_result=expected_result,
+            duration_minutes=duration_minutes,
+            capabilities=capabilities,
+            criterion_ids=criterion_ids,
+            device_id=device_id,
+            harness_id=harness_id,
+        )
+    )
+
+
+@mcp.tool()
+def hai_bind_project(
+    project_id: str,
+    device_id: str,
+    local_path: str,
+    owner_ack: Any,
+    reason: str,
+) -> str:
+    """Bind a device-local directory to a logical project_id mount table entry. Requires owner_ack=true + reason."""
+    return _json(
+        get_control_plane().bind_project(
+            project_id=project_id,
+            device_id=device_id,
+            local_path=local_path,
+            owner_ack=owner_ack,
+            reason=reason,
+        )
+    )
+
+
+@mcp.tool()
+def hai_get_contract(session_id: str) -> str:
+    """Return the exact canonical mission contract for a valid session lease (not a summary)."""
+    return _json(get_control_plane().get_contract(session_id))
+
+
+@mcp.tool()
+def hai_check_activity(
+    session_id: str,
+    activity_step: str,
+    criterion_id: str | None = None,
+    affected_paths: list[str] | None = None,
+    trace_events: list[dict[str, Any]] | None = None,
+    activity_kind: str | None = None,
+    evidence: dict[str, Any] | None = None,
+    declares_blocker: Any = False,
+) -> str:
+    """Deterministically classify planned or observed activity against the mission contract."""
+    return _json(
+        get_control_plane().check_activity(
+            session_id=session_id,
+            activity_step=activity_step,
+            affected_paths=affected_paths,
+            trace_events=trace_events,
+            criterion_id=criterion_id,
+            activity_kind=activity_kind,
+            evidence=evidence,
+            declares_blocker=declares_blocker,
+        )
+    )
+
+
+@mcp.tool()
+def hai_park_item(
+    idea: str,
+    origin_session_id: str,
+    trigger_event: str,
+    mission_id: str,
+    rationale: str,
+) -> str:
+    """Park a mission-linked idea with full context. Grants no execution right; contract unchanged."""
+    return _json(
+        get_control_plane().park_item(
+            idea=idea,
+            origin_session_id=origin_session_id,
+            trigger_event=trigger_event,
+            mission_id=mission_id,
+            rationale=rationale,
+        )
+    )
+
+
+@mcp.tool()
+def hai_recontract(
+    mission_id: str,
+    contract_version: Any,
+    reason: str,
+    changes: dict[str, Any],
+    owner_ack: Any = False,
+    mode: str = "normal",
+    break_glass_marker: Any = False,
+) -> str:
+    """Apply a visible field-level contract diff. Requires owner_ack=true; revokes all leases."""
+    return _json(
+        get_control_plane().recontract(
+            mission_id=mission_id,
+            contract_version=contract_version,
+            reason=reason,
+            changes=changes,
+            mode=mode,
+            owner_ack=owner_ack,
+            break_glass_marker=break_glass_marker,
+        )
+    )
+
+
+@mcp.tool()
+def hai_close_mission(
+    mission_id: str,
+    contract_version: Any,
+    closure: str,
+    outcome_summary: str,
+    evidence: dict[str, Any] | None = None,
+    owner_ack: Any = False,
+    device_id: str | None = None,
+) -> str:
+    """Complete with verified per-criterion evidence, or abandon with owner_ack and reason."""
+    return _json(
+        get_control_plane().close_mission(
+            mission_id=mission_id,
+            contract_version=contract_version,
+            evidence=evidence,
+            outcome_summary=outcome_summary,
+            closure=closure,
+            owner_ack=owner_ack,
+            device_id=device_id,
+        )
+    )
+
+
+# --- Additional seven flow tools (daily loop) over the canonical hardened engine ---
+
+
+@mcp.tool()
+def hai_intake(raw: str) -> str:
+    """Capture a raw thought immutably. Returns an intake id only — never actionable, never starts an agent."""
+    return _json(get_control_plane().intake(raw))
+
+
+@mcp.tool()
+def hai_distill(
+    intake_id: str,
+    decision: str,
+    next_step: str,
+    parklist: list[str] | None = None,
+) -> str:
+    """Reduce an intake to EXACTLY one decision + one next step; the server parks everything else."""
+    return _json(
+        get_control_plane().distill(
+            intake_id=intake_id,
+            decision=decision,
+            next_step=next_step,
+            parklist=parklist,
+        )
+    )
+
+
+@mcp.tool()
+def hai_mission_start(
+    problem: str,
+    artifact: str,
+    done_criteria: list[dict[str, Any]],
+    owner: str,
+    time_limit_hours: Any = None,
+    non_goals: list[str] | None = None,
+    constraints: dict[str, Any] | None = None,
+) -> str:
+    """Fast start: declare problem + artifact + time limit. Thin wrapper over hai_open_mission (one canonical contract)."""
+    merged = dict(constraints or {})
+    if time_limit_hours is not None:
+        tl, err = strict_optional_time_limit_hours(time_limit_hours)
+        if err:
+            return _json(err)
+        merged["time_limit_hours"] = tl
+    return _json(
+        get_control_plane().open_mission(
+            objective=problem,
+            artifact=artifact,
+            done_criteria=done_criteria,
+            non_goals=non_goals,
+            constraints=merged,
+            owner=owner,
+        )
+    )
+
+
+@mcp.tool()
+def hai_drift_check(
+    session_id: str,
+    activity_step: str,
+    criterion_id: str | None = None,
+    affected_paths: list[str] | None = None,
+    trace_events: list[dict[str, Any]] | None = None,
+    activity_kind: str | None = None,
+    evidence: dict[str, Any] | None = None,
+    declares_blocker: Any = False,
+) -> str:
+    """Lightweight mismatch check against the mission contract. Thin wrapper over hai_check_activity."""
+    return _json(
+        get_control_plane().check_activity(
+            session_id=session_id,
+            activity_step=activity_step,
+            affected_paths=affected_paths,
+            trace_events=trace_events,
+            criterion_id=criterion_id,
+            activity_kind=activity_kind,
+            evidence=evidence,
+            declares_blocker=declares_blocker,
+        )
+    )
+
+
+@mcp.tool()
+def hai_proof(
+    mission_id: str,
+    contract_version: Any,
+    evidence: dict[str, Any],
+    outcome_summary: str,
+    device_id: str | None = None,
+) -> str:
+    """Close a mission only against verified per-criterion evidence. Thin wrapper over hai_close_mission (completed)."""
+    return _json(
+        get_control_plane().close_mission(
+            mission_id=mission_id,
+            contract_version=contract_version,
+            evidence=evidence,
+            outcome_summary=outcome_summary,
+            closure="completed",
+            device_id=device_id,
+        )
+    )
+
+
+@mcp.tool()
+def hai_stop(
+    day: str,
+    loop_closed: bool,
+    clearer: str,
+    agency_gained: str,
+) -> str:
+    """Hard day terminal: record the three answers, invalidate active leases; no next-day plan. Missions are not closed."""
+    return _json(
+        get_control_plane().stop_day(
+            day=day,
+            loop_closed=loop_closed,
+            clearer=clearer,
+            agency_gained=agency_gained,
+        )
+    )
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description="HAI-MCP control-plane server")
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "streamable-http"],
+        default=os.environ.get("HAI_TRANSPORT", "stdio"),
+        help="MCP transport (default: stdio; env HAI_TRANSPORT)",
+    )
+    parser.add_argument(
+        "--host",
+        default=os.environ.get("HAI_HTTP_HOST", "127.0.0.1"),
+        help="HTTP bind host for streamable-http (env HAI_HTTP_HOST)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("HAI_HTTP_PORT", "8765")),
+        help="HTTP bind port for streamable-http (env HAI_HTTP_PORT)",
+    )
+    args = parser.parse_args(argv)
+
+    if args.transport == "streamable-http":
+        token = http_token_from_env()
+        allowed, msg = http_bind_allowed(args.host, token)
+        if not allowed:
+            raise SystemExit(msg)
+        mcp.settings.host = args.host
+        mcp.settings.port = args.port
+        if token:
+
+            async def _serve_with_token() -> None:
+                import uvicorn
+
+                app = wrap_with_bearer_token(mcp.streamable_http_app(), token)
+                config = uvicorn.Config(
+                    app,
+                    host=args.host,
+                    port=args.port,
+                    log_level=mcp.settings.log_level.lower(),
+                )
+                server = uvicorn.Server(config)
+                await server.serve()
+
+            anyio.run(_serve_with_token)
+        else:
+            mcp.run(transport="streamable-http")
+        return
+
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

hai-mcp-pr7/src/hai_mcp/state.py

@@ -0,0 +1,746 @@
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from hai_mcp.boundary import strict_int
+from hai_mcp.config import Config, ensure_hai_home
+from hai_mcp.ids import validate_intake_id
+from hai_mcp.locking import mission_state_lock
+from hai_mcp.mission import MissionEngine, _new_id, _utc_now
+from hai_mcp.projects import ProjectStore
+from hai_mcp.paths import (
+    PathError,
+    assert_under,
+    confined_artifact_dir,
+    ensure_artifact_dir,
+    require_project_path,
+)
+from hai_mcp.storage import atomic_write_text, read_json, write_json
+
+ARTIFACT_NAMES = [
+    "PROJECT_STATE.md",
+    "PROMPT.md",
+    "INTENT.md",
+    "CODE_STATE.md",
+    "BRIEFING.md",
+    "NEXT_STEP.md",
+    "NEXT_STEP.proposed.md",
+    "EXECUTOR_HANDOFF_NEXT_STEP.md",
+    "EXECUTION_REPORT_NEXT_STEP.md",
+    "VALIDATION_REPORT_NEXT_STEP.md",
+    "VERIFICATION_REPORT_NEXT_STEP.md",
+    "LOOP_STATUS_NEXT_STEP.md",
+    "BLOCKED_LOG_NEXT_STEP.md",
+    "DRIFT_LOG.md",
+]
+
+
+@dataclass
+class ControlPlane:
+    cfg: Config
+
+    def __post_init__(self) -> None:
+        ensure_hai_home(self.cfg)
+        self.mission = MissionEngine(self.cfg)
+
+    @property
+    def active_path(self) -> Path:
+        return self.cfg.hai_home / "ACTIVE_CONTEXT.json"
+
+    @property
+    def inbox_dir(self) -> Path:
+        return self.cfg.hai_home / "inbox"
+
+    @property
+    def checkpoints_dir(self) -> Path:
+        return self.cfg.hai_home / "history" / "checkpoints"
+
+    @property
+    def intake_dir(self) -> Path:
+        return self.cfg.hai_home / "intake"
+
+    @property
+    def distill_dir(self) -> Path:
+        return self.cfg.hai_home / "distillations"
+
+    @property
+    def stop_dir(self) -> Path:
+        return self.cfg.hai_home / "stops"
+
+    def load_active(self) -> dict[str, Any]:
+        data = read_json(self.active_path, {"version": 1, "focus_id": None, "active": []})
+        if "active" not in data or not isinstance(data["active"], list):
+            data["active"] = []
+        return data
+
+    def save_active(self, data: dict[str, Any]) -> None:
+        write_json(self.active_path, data)
+
+    def health(self, project_path: str | None = None) -> dict[str, Any]:
+        home = ensure_hai_home(self.cfg)
+        result: dict[str, Any] = {
+            "ok": True,
+            "server": "hai-mcp",
+            "version": "0.1.0",
+            "hai_home": str(home),
+            "hai_home_writable": os.access(home, os.W_OK),
+            "model_calls": False,
+            "max_active_lanes": self.cfg.max_active_lanes,
+            "kernel": "contract_kernel",
+            "authenticated_owner": False,
+            "semantic_verification": False,
+            "projects": ProjectStore(home).list_projects(),
+        }
+        if project_path:
+            try:
+                project = require_project_path(project_path)
+                ad = confined_artifact_dir(self.cfg, project)
+                result["project_path"] = str(project)
+                result["artifact_dir"] = str(ad)
+                result["artifact_dir_exists"] = ad.is_dir()
+            except PathError as exc:
+                return {"ok": False, "error": exc.code, "message": exc.message}
+        return result
+
+    def status(self, project_path: str | None = None) -> dict[str, Any]:
+        active = self.load_active()
+        inbox_count = len(list(self.inbox_dir.glob("*.md"))) if self.inbox_dir.is_dir() else 0
+        out: dict[str, Any] = {
+            "ok": True,
+            "focus_id": active.get("focus_id"),
+            "active": active.get("active", []),
+            "active_count": len(active.get("active", [])),
+            "max_active_lanes": self.cfg.max_active_lanes,
+            "inbox_count": inbox_count,
+            "hai_home": str(self.cfg.hai_home),
+        }
+        if project_path:
+            try:
+                project = require_project_path(project_path)
+                ad = confined_artifact_dir(self.cfg, project)
+                next_step = ad / "NEXT_STEP.md"
+                out["project_path"] = str(project)
+                out["has_next_step"] = next_step.is_file()
+                out["has_proposed"] = (ad / "NEXT_STEP.proposed.md").is_file()
+            except PathError as exc:
+                return {"ok": False, "error": exc.code, "message": exc.message}
+        return out
+
+    def get_next_step(self, project_path: str) -> dict[str, Any]:
+        try:
+            project = require_project_path(project_path)
+            ad = confined_artifact_dir(self.cfg, project)
+            path = ad / "NEXT_STEP.md"
+            if path.is_symlink():
+                assert_under(path, ad)  # reject a symlinked NEXT_STEP.md escaping the artifact dir
+        except PathError as exc:
+            return {"ok": False, "error": exc.code, "message": exc.message}
+        if not path.is_file():
+            return {
+                "ok": True,
+                "exists": False,
+                "path": str(path),
+                "content": None,
+                "source": "none",
+            }
+        return {
+            "ok": True,
+            "exists": True,
+            "path": str(path),
+            "content": path.read_text(encoding="utf-8"),
+            "source": "canonical",
+        }
+
+    def read_artifacts(self, project_path: str, max_chars: Any = 4000) -> dict[str, Any]:
+        try:
+            project = require_project_path(project_path)
+            ad = confined_artifact_dir(self.cfg, project)
+        except PathError as exc:
+            return {"ok": False, "error": exc.code, "message": exc.message}
+        parsed, err = strict_int(max_chars, "max_chars", min_value=1)
+        if err:
+            return err
+        assert parsed is not None
+        max_chars = max(500, min(parsed, 20000))
+        artifacts: dict[str, Any] = {}
+        for name in ARTIFACT_NAMES:
+            p = ad / name
+            if p.is_symlink():
+                try:
+                    assert_under(p, ad)  # skip a symlinked artifact file escaping the artifact dir
+                except PathError:
+                    continue
+            if not p.is_file():
+                continue
+            text = p.read_text(encoding="utf-8")
+            truncated = len(text) > max_chars
+            artifacts[name] = {
+                "path": str(p),
+                "chars": len(text),
+                "truncated": truncated,
+                "content": text[:max_chars],
+            }
+        return {
+            "ok": True,
+            "project_path": str(project),
+            "artifact_dir": str(ad),
+            "artifact_dir_exists": ad.is_dir(),
+            "artifacts": artifacts,
+            "present": sorted(artifacts.keys()),
+        }
+
+    def park(self, text: str, tags: list[str] | None = None) -> dict[str, Any]:
+        if not text or not str(text).strip():
+            return {"ok": False, "error": "invalid_args", "message": "text is required"}
+        ts = time.strftime("%Y%m%dT%H%M%S")
+        # unique suffix so multiple parks within the same second never overwrite (verlustfrei parken)
+        slug = f"park_{ts}_{os.getpid()}_{uuid.uuid4().hex[:8]}.md"
+        path = self.inbox_dir / slug
+        tag_line = ", ".join(tags or [])
+        body = (
+            f"# Parked thought\n\n"
+            f"- created: {time.strftime('%Y-%m-%dT%H:%M:%S%z')}\n"
+            f"- tags: {tag_line or '(none)'}\n\n"
+            f"{text.strip()}\n"
+        )
+        before = self.load_active()
+        atomic_write_text(path, body)
+        after = self.load_active()
+        return {
+            "ok": True,
+            "path": str(path),
+            "active_unchanged": before == after,
+            "active_count": len(after.get("active", [])),
+            "message": "parked; ACTIVE lanes not modified",
+        }
+
+    def set_focus(
+        self,
+        focus_id: str,
+        project_path: str | None = None,
+        label: str | None = None,
+    ) -> dict[str, Any]:
+        if not focus_id or not str(focus_id).strip():
+            return {"ok": False, "error": "invalid_args", "message": "focus_id is required"}
+        focus_id = focus_id.strip()
+        data = self.load_active()
+        active: list[dict[str, Any]] = list(data.get("active", []))
+        existing_ids = {item.get("id") for item in active}
+        if focus_id not in existing_ids:
+            if len(active) >= self.cfg.max_active_lanes:
+                return {
+                    "ok": False,
+                    "error": "max_active_lanes",
+                    "message": (
+                        f"already {len(active)} ACTIVE lanes "
+                        f"(max {self.cfg.max_active_lanes}); park or drop one first"
+                    ),
+                    "active": active,
+                }
+            entry: dict[str, Any] = {
+                "id": focus_id,
+                "label": label or focus_id,
+                "activated_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+            }
+            if project_path:
+                try:
+                    project = require_project_path(project_path)
+                    entry["project_path"] = str(project)
+                except PathError as exc:
+                    return {"ok": False, "error": exc.code, "message": exc.message}
+            active.append(entry)
+        else:
+            # update label/project if provided
+            for item in active:
+                if item.get("id") == focus_id:
+                    if label:
+                        item["label"] = label
+                    if project_path:
+                        try:
+                            project = require_project_path(project_path)
+                            item["project_path"] = str(project)
+                        except PathError as exc:
+                            return {"ok": False, "error": exc.code, "message": exc.message}
+        data["active"] = active
+        data["focus_id"] = focus_id
+        self.save_active(data)
+        return {
+            "ok": True,
+            "focus_id": focus_id,
+            "active": active,
+            "active_count": len(active),
+        }
+
+    def propose_next_step(self, project_path: str, content: str) -> dict[str, Any]:
+        if not content or not str(content).strip():
+            return {"ok": False, "error": "invalid_args", "message": "content is required"}
+        try:
+            project = require_project_path(project_path)
+            ad = ensure_artifact_dir(self.cfg, project)
+        except PathError as exc:
+            return {"ok": False, "error": exc.code, "message": exc.message}
+        path = ad / "NEXT_STEP.proposed.md"
+        header = (
+            f"<!-- proposed by hai-mcp at {time.strftime('%Y-%m-%dT%H:%M:%S%z')} "
+            f"— not canonical until hai_accept_next_step -->\n\n"
+        )
+        atomic_write_text(path, header + content.strip() + "\n")
+        return {
+            "ok": True,
+            "path": str(path),
+            "canonical": False,
+            "message": "proposal written; call hai_accept_next_step with owner_ack=true to promote",
+        }
+
+    def accept_next_step(
+        self,
+        project_path: str,
+        owner_ack: Any,
+        reason: str,
+        content: str | None = None,
+    ) -> dict[str, Any]:
+        if owner_ack is not True:
+            return {
+                "ok": False,
+                "error": "owner_gate_required",
+                "message": "hai_accept_next_step requires owner_ack=true (literal boolean) and a reason",
+            }
+        if not reason or not str(reason).strip():
+            return {
+                "ok": False,
+                "error": "owner_gate_required",
+                "message": "reason is required when accepting a next step",
+            }
+        try:
+            project = require_project_path(project_path)
+            ad = ensure_artifact_dir(self.cfg, project)
+        except PathError as exc:
+            return {"ok": False, "error": exc.code, "message": exc.message}
+        proposed = ad / "NEXT_STEP.proposed.md"
+        if content and str(content).strip():
+            body = content.strip() + "\n"
+        elif proposed.is_file():
+            body = proposed.read_text(encoding="utf-8")
+            # strip proposal marker lines
+            lines = [
+                ln
+                for ln in body.splitlines()
+                if not ln.startswith("<!-- proposed by hai-mcp")
+            ]
+            body = "\n".join(lines).strip() + "\n"
+        else:
+            return {
+                "ok": False,
+                "error": "no_proposal",
+                "message": "no NEXT_STEP.proposed.md and no content provided",
+            }
+        canonical = ad / "NEXT_STEP.md"
+        history_dir = ad / "history"
+        history_dir.mkdir(exist_ok=True)
+        stamp = time.strftime("%Y%m%dT%H%M%S")
+        if canonical.is_file():
+            atomic_write_text(
+                history_dir / f"NEXT_STEP_{stamp}_prev.md",
+                canonical.read_text(encoding="utf-8"),
+            )
+        meta = (
+            f"\n\n---\n"
+            f"_Accepted via hai-mcp_\n"
+            f"- at: {time.strftime('%Y-%m-%dT%H:%M:%S%z')}\n"
+            f"- reason: {reason.strip()}\n"
+        )
+        # avoid duplicating meta if re-accepting same body
+        final = body.rstrip() + meta
+        atomic_write_text(canonical, final)
+        if proposed.is_file():
+            proposed.unlink()
+        hist_note = {
+            "event": "accept_next_step",
+            "at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+            "reason": reason.strip(),
+            "project_path": str(project),
+            "path": str(canonical),
+        }
+        write_json(history_dir / f"accept_{stamp}.json", hist_note)
+        return {
+            "ok": True,
+            "path": str(canonical),
+            "canonical": True,
+            "reason": reason.strip(),
+        }
+
+    def checkpoint(self, note: str | None = None, project_path: str | None = None) -> dict[str, Any]:
+        stamp = time.strftime("%Y%m%dT%H%M%S")
+        cp_dir = self.checkpoints_dir / stamp
+        cp_dir.mkdir(parents=True, exist_ok=True)
+        active = self.load_active()
+        write_json(cp_dir / "ACTIVE_CONTEXT.json", active)
+        payload: dict[str, Any] = {
+            "at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+            "note": note or "",
+            "focus_id": active.get("focus_id"),
+            "active": active.get("active", []),
+        }
+        if project_path:
+            try:
+                project = require_project_path(project_path)
+                ad = confined_artifact_dir(self.cfg, project)
+                art_snap: dict[str, str] = {}
+                if ad.is_dir():
+                    for name in ("NEXT_STEP.md", "NEXT_STEP.proposed.md", "BRIEFING.md", "PROJECT_STATE.md"):
+                        p = ad / name
+                        if p.is_symlink():
+                            try:
+                                assert_under(p, ad)  # skip symlinked artifact escaping the dir
+                            except PathError:
+                                continue
+                        if p.is_file():
+                            dest = cp_dir / "project" / name
+                            dest.parent.mkdir(parents=True, exist_ok=True)
+                            atomic_write_text(dest, p.read_text(encoding="utf-8"))
+                            art_snap[name] = str(dest)
+                payload["project_path"] = str(project)
+                payload["artifacts"] = art_snap
+            except PathError as exc:
+                return {"ok": False, "error": exc.code, "message": exc.message}
+        write_json(cp_dir / "meta.json", payload)
+        return {
+            "ok": True,
+            "checkpoint_id": stamp,
+            "path": str(cp_dir),
+            "meta": payload,
+        }
+
+    def open_mission(
+        self,
+        objective: str,
+        artifact: str,
+        done_criteria: list[Any] | None,
+        non_goals: list[str] | None,
+        constraints: dict[str, Any] | None,
+        owner: str,
+    ) -> dict[str, Any]:
+        return self.mission.open_mission(
+            objective=objective,
+            artifact=artifact,
+            done_criteria=done_criteria,
+            non_goals=non_goals,
+            constraints=constraints,
+            owner=owner,
+        )
+
+    def authorize_session(
+        self,
+        mission_id: str,
+        contract_version: Any,
+        agent_identity: str,
+        role: str,
+        contribution: str,
+        expected_result: str,
+        duration_minutes: Any,
+        capabilities: list[str] | None = None,
+        criterion_ids: list[str] | None = None,
+        device_id: str | None = None,
+        harness_id: str | None = None,
+    ) -> dict[str, Any]:
+        return self.mission.authorize_session(
+            mission_id=mission_id,
+            contract_version=contract_version,
+            agent_identity=agent_identity,
+            role=role,
+            contribution=contribution,
+            expected_result=expected_result,
+            duration_minutes=duration_minutes,
+            capabilities=capabilities,
+            criterion_ids=criterion_ids,
+            device_id=device_id,
+            harness_id=harness_id,
+        )
+
+    def bind_project(
+        self,
+        project_id: str,
+        device_id: str,
+        local_path: str,
+        owner_ack: Any = False,
+        reason: str = "",
+    ) -> dict[str, Any]:
+        return self.mission.bind_project(
+            project_id=project_id,
+            device_id=device_id,
+            local_path=local_path,
+            owner_ack=owner_ack,
+            reason=reason,
+        )
+
+    def get_contract(self, session_id: str) -> dict[str, Any]:
+        return self.mission.get_contract(session_id)
+
+    def check_activity(
+        self,
+        session_id: str,
+        activity_step: str,
+        affected_paths: list[str] | None = None,
+        trace_events: list[dict[str, Any]] | None = None,
+        criterion_id: str | None = None,
+        activity_kind: str | None = None,
+        evidence: dict[str, Any] | None = None,
+        declares_blocker: Any = False,
+    ) -> dict[str, Any]:
+        return self.mission.check_activity(
+            session_id=session_id,
+            activity_step=activity_step,
+            affected_paths=affected_paths,
+            trace_events=trace_events,
+            criterion_id=criterion_id,
+            activity_kind=activity_kind,
+            evidence=evidence,
+            declares_blocker=declares_blocker,
+        )
+
+    def park_item(
+        self,
+        idea: str,
+        origin_session_id: str,
+        trigger_event: str,
+        mission_id: str,
+        rationale: str,
+    ) -> dict[str, Any]:
+        return self.mission.park_item(
+            idea=idea,
+            origin_session_id=origin_session_id,
+            trigger_event=trigger_event,
+            mission_id=mission_id,
+            rationale=rationale,
+        )
+
+    def recontract(
+        self,
+        mission_id: str,
+        contract_version: Any,
+        reason: str,
+        changes: dict[str, Any],
+        mode: str = "normal",
+        owner_ack: Any = False,
+        break_glass_marker: Any = False,
+    ) -> dict[str, Any]:
+        return self.mission.recontract(
+            mission_id=mission_id,
+            contract_version=contract_version,
+            reason=reason,
+            changes=changes,
+            mode=mode,
+            owner_ack=owner_ack,
+            break_glass_marker=break_glass_marker,
+        )
+
+    def close_mission(
+        self,
+        mission_id: str,
+        contract_version: Any,
+        evidence: dict[str, Any] | None,
+        outcome_summary: str,
+        closure: str,
+        owner_ack: Any = False,
+        device_id: str | None = None,
+    ) -> dict[str, Any]:
+        return self.mission.close_mission(
+            mission_id=mission_id,
+            contract_version=contract_version,
+            evidence=evidence,
+            outcome_summary=outcome_summary,
+            closure=closure,
+            owner_ack=owner_ack,
+            device_id=device_id,
+        )
+
+    # --- Additional daily-loop flow surface (thin, over the hardened engine) ---
+
+    def intake(self, raw: str) -> dict[str, Any]:
+        """Capture a raw, immutable thought. Returns only an id — never actionable, never an agent trigger."""
+        if not raw or not str(raw).strip():
+            return {"ok": False, "error": "invalid_args", "message": "raw intake text is required"}
+        intake_id = _new_id("I")
+        self.intake_dir.mkdir(parents=True, exist_ok=True)
+        path = self.intake_dir / f"{intake_id}.json"
+        try:
+            assert_under(self.intake_dir, self.cfg.hai_home)
+            assert_under(path, self.cfg.hai_home)
+        except PathError as exc:
+            return {"ok": False, "error": exc.code, "message": exc.message}
+        record = {
+            "intake_id": intake_id,
+            "raw": str(raw),
+            "actionable": False,
+            "captured_at": _utc_now(),
+        }
+        write_json(path, record)
+        return {
+            "ok": True,
+            "intake_id": intake_id,
+            "actionable": False,
+            "message": "captured only; no decision and no action taken",
+        }
+
+    def distill(
+        self,
+        intake_id: str,
+        decision: str,
+        next_step: str,
+        parklist: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Reduce an intake to EXACTLY one decision + one next step; everything else is parked.
+
+        The server enforces cardinality: 0 or >1 decisions/steps are rejected, and a single
+        field carrying a bundled multi-line plan is refused (crude anti-smuggle guard).
+        """
+        ok, msg = validate_intake_id(intake_id)
+        if not ok:
+            return {"ok": False, "error": "invalid_args", "message": msg}
+        ipath = self.intake_dir / f"{intake_id}.json"
+        if not ipath.is_file():
+            return {"ok": False, "error": "invalid_args", "message": f"intake not found: {intake_id}"}
+
+        decision = str(decision or "").strip()
+        next_step = str(next_step or "").strip()
+        if not decision:
+            return {"ok": False, "error": "invalid_args", "message": "exactly one decision is required"}
+        if not next_step:
+            return {"ok": False, "error": "invalid_args", "message": "exactly one next_step is required"}
+        if "\n" in decision or "\n" in next_step:
+            return {
+                "ok": False,
+                "error": "invalid_args",
+                "message": "decision and next_step must each be a single item (no bundled multi-line plan)",
+            }
+
+        parklist = [str(x).strip() for x in (parklist or []) if str(x).strip()]
+        parked_paths: list[str] = []
+        for item in parklist:
+            r = self.park(item, tags=["distilled", intake_id])
+            if r.get("ok"):
+                parked_paths.append(r["path"])
+
+        distill_id = _new_id("A")
+        self.distill_dir.mkdir(parents=True, exist_ok=True)
+        path = self.distill_dir / f"{distill_id}.json"
+        try:
+            assert_under(self.distill_dir, self.cfg.hai_home)
+            assert_under(path, self.cfg.hai_home)
+        except PathError as exc:
+            return {"ok": False, "error": exc.code, "message": exc.message}
+        record = {
+            "distill_id": distill_id,
+            "intake_id": intake_id,
+            "decision": decision,
+            "next_step": next_step,
+            "parked_count": len(parked_paths),
+            "distilled_at": _utc_now(),
+        }
+        write_json(path, record)
+        return {
+            "ok": True,
+            "intake_id": intake_id,
+            "decision": decision,
+            "next_step": next_step,
+            "parked_count": len(parked_paths),
+            "message": "one decision, one next step; the rest is parked",
+        }
+
+    def stop_day(
+        self,
+        day: str,
+        loop_closed: bool,
+        clearer: str,
+        agency_gained: str,
+    ) -> dict[str, Any]:
+        """Hard terminal for the workday: record the three answers, invalidate active leases.
+
+        Does NOT complete or abandon a mission (that needs proof/owner_ack); the mission is
+        left paused (leases revoked) and there is deliberately no next-day plan.
+        """
+        day = str(day or "").strip()
+        if not day:
+            return {"ok": False, "error": "invalid_args", "message": "day is required"}
+
+        paused_mission = None
+        revoked: list[str] = []
+        with mission_state_lock(self.cfg.hai_home):
+            active = self.mission.load_active_pointer()
+            if active.get("mission_id") and active.get("status") == "active":
+                paused_mission = active["mission_id"]
+                revoked = self.mission.revoke_all_sessions(paused_mission, reason="day_stopped")
+
+        stop_id = _new_id("A")
+        self.stop_dir.mkdir(parents=True, exist_ok=True)
+        path = self.stop_dir / f"{stop_id}.json"
+        try:
+            assert_under(self.stop_dir, self.cfg.hai_home)
+            assert_under(path, self.cfg.hai_home)
+        except PathError as exc:
+            return {"ok": False, "error": exc.code, "message": exc.message}
+        record = {
+            "stop_id": stop_id,
+            "day": day,
+            "loop_closed": bool(loop_closed),
+            "clearer": str(clearer or "").strip(),
+            "agency_gained": str(agency_gained or "").strip(),
+            "paused_mission": paused_mission,
+            "revoked_sessions": revoked,
+            "next_mission": None,
+            "stopped_at": _utc_now(),
+        }
+        write_json(path, record)
+        return {
+            "ok": True,
+            "status": "day_stopped",
+            "day": day,
+            "paused_mission": paused_mission,
+            "revoked_sessions": revoked,
+            "next_mission": None,
+            "message": "day sealed; leases invalidated; no next-day plan; parked items stay parked",
+        }
+
+    def recover(self, checkpoint_id: str | None = None) -> dict[str, Any]:
+        cps = sorted(
+            [p for p in self.checkpoints_dir.iterdir() if p.is_dir()],
+            key=lambda p: p.name,
+        )
+        if not cps and not checkpoint_id:
+            active = self.load_active()
+            return {
+                "ok": True,
+                "mode": "no_checkpoint",
+                "next_action": "Call hai_status, then hai_get_next_step on the focus project. If unclear, park meta thoughts and set one focus.",
+                "focus_id": active.get("focus_id"),
+                "active": active.get("active", []),
+            }
+        if checkpoint_id:
+            cp = self.checkpoints_dir / checkpoint_id
+            if not cp.is_dir():
+                return {
+                    "ok": False,
+                    "error": "invalid_args",
+                    "message": f"checkpoint not found: {checkpoint_id}",
+                }
+        else:
+            cp = cps[-1]
+        meta = read_json(cp / "meta.json", {})
+        snap_active = read_json(cp / "ACTIVE_CONTEXT.json", {})
+        return {
+            "ok": True,
+            "mode": "from_checkpoint",
+            "checkpoint_id": cp.name,
+            "path": str(cp),
+            "meta": meta,
+            "snapshot_active": snap_active,
+            "next_action": (
+                "Do not rebuild architecture. Restore focus from snapshot if needed, "
+                "read NEXT_STEP.md, execute only that step or ask Owner."
+            ),
+        }

hai-mcp-pr7/src/hai_mcp/storage.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_name, path)
+    finally:
+        if os.path.exists(tmp_name):
+            try:
+                os.unlink(tmp_name)
+            except OSError:
+                pass
+
+
+def read_json(path: Path, default: Any) -> Any:
+    if not path.exists():
+        return default
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_json(path: Path, data: Any) -> None:
+    atomic_write_text(path, json.dumps(data, indent=2, ensure_ascii=False, sort_keys=True) + "\n")

hai-mcp-pr7/tests/conftest.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+ISOLATED_HAI_HOME = "/tmp/hai-mcp-composer-core-fix-20260722"
+ISOLATED_UV_CACHE = "/tmp/hai-mcp-uv-cache"
+
+
+@pytest.fixture(scope="session", autouse=True)
+def isolated_hai_home() -> None:
+    """Every test inherits an isolated HAI_HOME; never touch live ~/.hai."""
+    os.environ["HAI_HOME"] = ISOLATED_HAI_HOME
+    os.environ["UV_CACHE_DIR"] = ISOLATED_UV_CACHE
+    Path(ISOLATED_HAI_HOME).mkdir(parents=True, exist_ok=True)

hai-mcp-pr7/tests/fixtures/ab/case1.json

@@ -0,0 +1,4 @@
+{
+  "intake_text": "Harden hai_distill cardinality\nRun a paired model evaluation",
+  "min_parklist_length": 1
+}

hai-mcp-pr7/tests/fixtures/ab/case2.json

@@ -0,0 +1,4 @@
+{
+  "intake_text": "Document the HAI-MCP control-plane contract\nInvestigate the MiniMax provider channel",
+  "min_parklist_length": 1
+}

hai-mcp-pr7/tests/test_central_core.py

@@ -0,0 +1,443 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from hai_mcp.config import Config
+from hai_mcp.http_transport import http_bind_allowed
+from hai_mcp.mission import MissionEngine
+from hai_mcp.projects import ProjectStore
+from hai_mcp.state import ControlPlane
+
+
+@pytest.fixture
+def plane(tmp_path: Path) -> ControlPlane:
+    home = tmp_path / "hai_home"
+    return ControlPlane(Config(hai_home=home))
+
+
+@pytest.fixture
+def macbook_root(tmp_path: Path) -> Path:
+    root = tmp_path / "macbook_proj"
+    (root / "src").mkdir(parents=True)
+    return root
+
+
+@pytest.fixture
+def thinkpad_root(tmp_path: Path) -> Path:
+    root = tmp_path / "thinkpad_proj"
+    (root / "src").mkdir(parents=True)
+    return root
+
+
+def _project_id_contract(macbook_root: Path) -> dict:
+    return {
+        "objective": "Central core slice acceptance",
+        "artifact": "src/x.py",
+        "done_criteria": [{"id": "dc-1", "description": "src/x.py exists on device mount"}],
+        "non_goals": ["sync HAI_HOME"],
+        "constraints": {
+            "project_id": "hai-mcp",
+            "device_id": "macbook",
+            "project_path": str(macbook_root),
+            "allowed_paths": ["src/"],
+            "capabilities": ["read", "write", "test"],
+            "max_parallel_sessions": 1,
+        },
+        "owner": "samuel",
+    }
+
+
+def _open_project_id(plane: ControlPlane, macbook_root: Path) -> dict:
+    c = _project_id_contract(macbook_root)
+    return plane.open_mission(
+        objective=c["objective"],
+        artifact=c["artifact"],
+        done_criteria=c["done_criteria"],
+        non_goals=c["non_goals"],
+        constraints=c["constraints"],
+        owner=c["owner"],
+    )
+
+
+def test_open_with_project_id_records_mount_and_null_contract_path(
+    plane: ControlPlane,
+    macbook_root: Path,
+) -> None:
+    opened = _open_project_id(plane, macbook_root)
+    assert opened["ok"] is True
+    contract = opened["contract"]
+    assert contract["constraints"]["project_id"] == "hai-mcp"
+    assert contract["constraints"]["project_path"] is None
+
+    store = ProjectStore(plane.cfg.hai_home)
+    mount = store.get_mount_path("hai-mcp", "macbook")
+    assert mount is not None
+    assert mount == macbook_root.resolve()
+
+
+def test_bind_project_owner_gate_then_success(
+    plane: ControlPlane,
+    macbook_root: Path,
+    thinkpad_root: Path,
+) -> None:
+    _open_project_id(plane, macbook_root)
+
+    denied = plane.bind_project(
+        project_id="hai-mcp",
+        device_id="thinkpad",
+        local_path=str(thinkpad_root),
+        owner_ack=False,
+        reason="should not write",
+    )
+    assert denied["ok"] is False
+    assert denied["error"] == "owner_gate_required"
+    assert ProjectStore(plane.cfg.hai_home).get_mount_path("hai-mcp", "thinkpad") is None
+
+    ok = plane.bind_project(
+        project_id="hai-mcp",
+        device_id="thinkpad",
+        local_path=str(thinkpad_root),
+        owner_ack=True,
+        reason="bind thinkpad dev tree",
+    )
+    assert ok["ok"] is True
+    mount = ProjectStore(plane.cfg.hai_home).get_mount_path("hai-mcp", "thinkpad")
+    assert mount == thinkpad_root.resolve()
+
+
+def test_authorize_thinkpad_get_contract_shares_identity(
+    plane: ControlPlane,
+    macbook_root: Path,
+    thinkpad_root: Path,
+) -> None:
+    opened = _open_project_id(plane, macbook_root)
+    plane.bind_project(
+        project_id="hai-mcp",
+        device_id="thinkpad",
+        local_path=str(thinkpad_root),
+        owner_ack=True,
+        reason="bind thinkpad",
+    )
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="thinkpad-agent",
+        role="builder",
+        contribution="edit src/x.py",
+        expected_result="file exists",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+        device_id="thinkpad",
+        harness_id="cursor",
+    )
+    assert auth["ok"] is True
+    got = plane.get_contract(auth["session_id"])
+    assert got["ok"] is True
+    assert got["mission_id"] == opened["mission_id"]
+    assert got["contract_version"] == opened["contract_version"]
+    assert got["contract_hash"] == opened["contract_hash"]
+    assert got["project_id"] == "hai-mcp"
+    assert got["device_id"] == "thinkpad"
+    assert got["mount_path"] == str(thinkpad_root.resolve())
+
+
+def test_check_activity_resolves_thinkpad_mount_not_macbook(
+    plane: ControlPlane,
+    macbook_root: Path,
+    thinkpad_root: Path,
+) -> None:
+    opened = _open_project_id(plane, macbook_root)
+    plane.bind_project(
+        project_id="hai-mcp",
+        device_id="thinkpad",
+        local_path=str(thinkpad_root),
+        owner_ack=True,
+        reason="bind thinkpad",
+    )
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="thinkpad-agent",
+        role="builder",
+        contribution="edit src/x.py",
+        expected_result="file exists",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+        device_id="thinkpad",
+    )
+    sid = auth["session_id"]
+    thinkpad_file = thinkpad_root / "src" / "x.py"
+    thinkpad_file.write_text("ok\n", encoding="utf-8")
+
+    rel = plane.check_activity(
+        session_id=sid,
+        activity_step="edit src/x.py",
+        criterion_id="dc-1",
+        affected_paths=["src/x.py"],
+    )
+    assert rel["classification"] == "in_scope"
+    assert rel["required_action"] == "continue"
+
+    abs_ok = plane.check_activity(
+        session_id=sid,
+        activity_step="edit src/x.py",
+        criterion_id="dc-1",
+        affected_paths=[str(thinkpad_file)],
+    )
+    assert abs_ok["classification"] == "in_scope"
+
+    mac_only = macbook_root / "src" / "only-mac.py"
+    mac_only.write_text("mac\n", encoding="utf-8")
+    drift = plane.check_activity(
+        session_id=sid,
+        activity_step="touch mac-only file",
+        criterion_id="dc-1",
+        affected_paths=[str(mac_only)],
+    )
+    assert drift["classification"] == "drift"
+    assert drift["required_action"] == "stop"
+
+
+def test_close_and_proof_require_device_id_for_project_missions(
+    plane: ControlPlane,
+    macbook_root: Path,
+    thinkpad_root: Path,
+) -> None:
+    opened = _open_project_id(plane, macbook_root)
+    plane.bind_project(
+        project_id="hai-mcp",
+        device_id="thinkpad",
+        local_path=str(thinkpad_root),
+        owner_ack=True,
+        reason="bind thinkpad",
+    )
+    evidence_file = thinkpad_root / "src" / "x.py"
+    evidence_file.write_text("done\n", encoding="utf-8")
+    evidence = {"dc-1": {"path": str(evidence_file)}}
+
+    missing = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        evidence=evidence,
+        outcome_summary="done on thinkpad",
+        closure="completed",
+    )
+    assert missing["ok"] is False
+    assert missing["error"] == "invalid_args"
+
+    completed = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        evidence=evidence,
+        outcome_summary="done on thinkpad",
+        closure="completed",
+        device_id="thinkpad",
+    )
+    assert completed["ok"] is True
+    assert completed["status"] == "completed"
+
+
+def test_unknown_device_authorize_device_mount_required(
+    plane: ControlPlane,
+    macbook_root: Path,
+) -> None:
+    opened = _open_project_id(plane, macbook_root)
+    r = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="ghost",
+        role="builder",
+        contribution="x",
+        expected_result="y",
+        duration_minutes=10,
+        criterion_ids=["dc-1"],
+        device_id="thinkpad",
+    )
+    assert r["ok"] is False
+    assert r["error"] == "device_mount_required"
+
+
+@pytest.mark.parametrize(
+    "project_id,device_id",
+    [
+        ("../evil", "macbook"),
+        ("/abs", "macbook"),
+        ("A", "macbook"),
+        ("", "macbook"),
+        ("hai-mcp", "../evil"),
+        ("hai-mcp", "MacBook"),
+    ],
+)
+def test_malformed_ids_invalid_args_no_write(
+    plane: ControlPlane,
+    macbook_root: Path,
+    project_id: str,
+    device_id: str,
+) -> None:
+    r = plane.open_mission(
+        objective="x",
+        artifact="y",
+        done_criteria=[{"id": "dc-1", "description": "z"}],
+        non_goals=[],
+        constraints={
+            "project_id": project_id,
+            "device_id": device_id,
+            "project_path": str(macbook_root),
+            "allowed_paths": ["src/"],
+        },
+        owner="samuel",
+    )
+    assert r["ok"] is False
+    assert r.get("error") in {"review_required", "invalid_args"} or r.get("status") == "review_required"
+    assert plane.mission.load_active_pointer()["mission_id"] is None
+    assert not (plane.cfg.hai_home / "core" / "projects.json").exists() or (
+        ProjectStore(plane.cfg.hai_home).get_mount_path("hai-mcp", "macbook") is None
+    )
+
+
+def test_event_chain_links_after_open_bind_authorize(
+    plane: ControlPlane,
+    macbook_root: Path,
+    thinkpad_root: Path,
+) -> None:
+    opened = _open_project_id(plane, macbook_root)
+    plane.bind_project(
+        project_id="hai-mcp",
+        device_id="thinkpad",
+        local_path=str(thinkpad_root),
+        owner_ack=True,
+        reason="bind thinkpad",
+    )
+    plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="thinkpad-agent",
+        role="builder",
+        contribution="x",
+        expected_result="y",
+        duration_minutes=10,
+        criterion_ids=["dc-1"],
+        device_id="thinkpad",
+    )
+
+    engine: MissionEngine = plane.mission
+    audit_dir = engine.audit_dir
+    events = []
+    for path in sorted(audit_dir.glob("A-*.json")):
+        events.append(json.loads(path.read_text(encoding="utf-8")))
+    events.sort(key=lambda e: int(e["seq"]))
+
+    assert len(events) >= 3
+    seqs = [int(e["seq"]) for e in events]
+    assert seqs == list(range(1, len(events) + 1))
+
+    for idx in range(1, len(events)):
+        prev = events[idx - 1]
+        cur = events[idx]
+        assert cur["prev_event_id"] == prev["event_id"]
+        assert cur["prev_hash"] == prev["event_hash"]
+
+    head = json.loads((audit_dir / "HEAD.json").read_text(encoding="utf-8"))
+    last = events[-1]
+    assert head["seq"] == last["seq"]
+    assert head["event_id"] == last["event_id"]
+    assert head["event_hash"] == last["event_hash"]
+
+
+def test_legacy_project_path_open_still_works(plane: ControlPlane, macbook_root: Path) -> None:
+    r = plane.open_mission(
+        objective="Legacy mission",
+        artifact="src/x.py",
+        done_criteria=[{"id": "dc-1", "description": "legacy path works"}],
+        non_goals=[],
+        constraints={"project_path": str(macbook_root), "allowed_paths": ["src/"]},
+        owner="samuel",
+    )
+    assert r["ok"] is True
+    assert r["contract"]["constraints"]["project_path"] == str(macbook_root)
+    assert r["contract"]["constraints"].get("project_id") is None
+
+
+def test_http_bind_allowed_policy() -> None:
+    ok, _ = http_bind_allowed("127.0.0.1", None)
+    assert ok is True
+    ok, _ = http_bind_allowed("localhost", None)
+    assert ok is True
+    ok, _ = http_bind_allowed("::1", None)
+    assert ok is True
+
+    ok, msg = http_bind_allowed("0.0.0.0", None)
+    assert ok is False
+    assert "HAI_HTTP_TOKEN" in msg
+
+    ok, _ = http_bind_allowed("0.0.0.0", "secret-token")
+    assert ok is True
+
+
+def test_bind_rejects_symlink_escape(tmp_path: Path) -> None:
+    home = tmp_path / "hai_home"
+    store = ProjectStore(home)
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    link_parent = tmp_path / "links"
+    link_parent.mkdir()
+    bad_link = link_parent / "proj"
+    bad_link.symlink_to(outside)
+
+    data = {"version": 1, "projects": {"hai-mcp": {"project_id": "hai-mcp", "mounts": {}}}}
+    store.save(data)
+
+    _, err = store.bind_mount("hai-mcp", "thinkpad", str(bad_link))
+    assert err is not None
+    assert err["error"] == "path_outside_root"
+
+
+def test_second_open_still_denied_with_project_id(
+    plane: ControlPlane,
+    macbook_root: Path,
+    thinkpad_root: Path,
+) -> None:
+    first = _open_project_id(plane, macbook_root)
+    second = plane.open_mission(
+        objective="second",
+        artifact="a",
+        done_criteria=[{"id": "dc-1", "description": "d"}],
+        non_goals=[],
+        constraints={
+            "project_id": "hai-mcp",
+            "device_id": "thinkpad",
+            "project_path": str(thinkpad_root),
+            "allowed_paths": ["src/"],
+        },
+        owner="samuel",
+    )
+    assert second["ok"] is False
+    assert second["error"] == "active_mission_exists"
+    assert second["active_mission_id"] == first["mission_id"]
+
+
+def test_recontract_preserves_project_id(plane: ControlPlane, macbook_root: Path) -> None:
+    opened = _open_project_id(plane, macbook_root)
+    before_hash = opened["contract_hash"]
+    r = plane.recontract(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        reason="tighten scope",
+        changes={"objective": "Central core slice acceptance (recontracted)"},
+        owner_ack=True,
+    )
+    assert r["ok"] is True
+    assert r["contract"]["constraints"]["project_id"] == "hai-mcp"
+    assert r["contract"]["constraints"]["project_path"] is None
+    assert r["contract_hash"] != before_hash
+
+
+def test_health_kernel_fields(plane: ControlPlane) -> None:
+    h = plane.health()
+    assert h["kernel"] == "contract_kernel"
+    assert h["authenticated_owner"] is False
+    assert h["semantic_verification"] is False
+    assert "projects" in h

hai-mcp-pr7/tests/test_control_plane.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from hai_mcp.config import Config
+from hai_mcp.state import ControlPlane
+
+
+@pytest.fixture
+def plane(tmp_path: Path) -> ControlPlane:
+    home = tmp_path / "hai_home"
+    return ControlPlane(Config(hai_home=home))
+
+
+@pytest.fixture
+def project(tmp_path: Path) -> Path:
+    p = tmp_path / "proj"
+    p.mkdir()
+    return p
+
+
+def test_health(plane: ControlPlane, project: Path) -> None:
+    r = plane.health(str(project))
+    assert r["ok"] is True
+    assert r["model_calls"] is False
+    assert r["hai_home_writable"] is True
+    assert r["project_path"] == str(project.resolve())
+
+
+def test_park_does_not_steal_lane(plane: ControlPlane) -> None:
+    plane.set_focus("lane-a", label="A")
+    before = plane.status()
+    r = plane.park("meta idea about better prompts", tags=["meta"])
+    assert r["ok"] is True
+    assert r["active_unchanged"] is True
+    after = plane.status()
+    assert after["active_count"] == before["active_count"] == 1
+    assert after["inbox_count"] == 1
+
+
+def test_max_two_active_lanes(plane: ControlPlane, project: Path) -> None:
+    assert plane.set_focus("a", project_path=str(project))["ok"] is True
+    assert plane.set_focus("b", project_path=str(project))["ok"] is True
+    r = plane.set_focus("c", project_path=str(project))
+    assert r["ok"] is False
+    assert r["error"] == "max_active_lanes"
+
+
+@pytest.mark.parametrize("ack", [False, None, 0, 1, "true"])
+def test_accept_next_step_requires_literal_owner_ack_true(
+    plane: ControlPlane, project: Path, ack: object
+) -> None:
+    plane.propose_next_step(str(project), "# gated step\n")
+    r = plane.accept_next_step(str(project), owner_ack=ack, reason="try")  # type: ignore[arg-type]
+    assert r["ok"] is False
+    assert r["error"] == "owner_gate_required"
+    assert not (project / "Projek-Managment" / "NEXT_STEP.md").is_file()
+
+
+def test_propose_and_accept_gate(plane: ControlPlane, project: Path) -> None:
+    content = (
+        "# NEXT_STEP\n\n"
+        "- goal: write smoke test\n"
+        "- allowed: tests only\n"
+        "- success: pytest green\n"
+    )
+    prop = plane.propose_next_step(str(project), content)
+    assert prop["ok"] is True
+    assert (project / "Projek-Managment" / "NEXT_STEP.proposed.md").is_file()
+
+    denied = plane.accept_next_step(str(project), owner_ack=False, reason="nope")
+    assert denied["ok"] is False
+    assert denied["error"] == "owner_gate_required"
+    assert not (project / "Projek-Managment" / "NEXT_STEP.md").exists()
+
+    denied2 = plane.accept_next_step(str(project), owner_ack=True, reason="")
+    assert denied2["ok"] is False
+
+    ok = plane.accept_next_step(str(project), owner_ack=True, reason="owner approved smoke")
+    assert ok["ok"] is True
+    canonical = project / "Projek-Managment" / "NEXT_STEP.md"
+    assert canonical.is_file()
+    text = canonical.read_text(encoding="utf-8")
+    assert "write smoke test" in text
+    assert "owner approved smoke" in text
+    assert not (project / "Projek-Managment" / "NEXT_STEP.proposed.md").exists()
+
+
+def test_get_next_step_and_artifacts(plane: ControlPlane, project: Path) -> None:
+    empty = plane.get_next_step(str(project))
+    assert empty["ok"] is True
+    assert empty["exists"] is False
+
+    plane.propose_next_step(str(project), "# step\n")
+    plane.accept_next_step(str(project), owner_ack=True, reason="go")
+    got = plane.get_next_step(str(project))
+    assert got["exists"] is True
+    arts = plane.read_artifacts(str(project))
+    assert "NEXT_STEP.md" in arts["present"]
+
+
+def test_checkpoint_and_recover(plane: ControlPlane, project: Path) -> None:
+    plane.set_focus("focus-1", project_path=str(project), label="demo")
+    plane.propose_next_step(str(project), "# proposed\n")
+    cp = plane.checkpoint(note="before risk", project_path=str(project))
+    assert cp["ok"] is True
+    rec = plane.recover(cp["checkpoint_id"])
+    assert rec["ok"] is True
+    assert rec["checkpoint_id"] == cp["checkpoint_id"]
+    assert "next_action" in rec
+
+
+def test_missing_project(plane: ControlPlane, tmp_path: Path) -> None:
+    r = plane.get_next_step(str(tmp_path / "nope"))
+    assert r["ok"] is False
+    assert r["error"] == "missing_project"
+
+
+def test_symlinked_artifact_dir_rejected(plane: ControlPlane, tmp_path: Path) -> None:
+    project = tmp_path / "proj"
+    project.mkdir()
+    outside = tmp_path / "outside-artifacts"
+    outside.mkdir()
+    (outside / "NEXT_STEP.md").write_text("# escaped\n", encoding="utf-8")
+    (project / "Projek-Managment").symlink_to(outside)
+
+    r = plane.propose_next_step(str(project), "# sneaky step\n")
+    assert r["ok"] is False
+    assert r["error"] == "path_outside_root"
+
+    ok_project = tmp_path / "safe-proj"
+    ok_project.mkdir()
+    good = plane.propose_next_step(str(ok_project), "# safe step\n")
+    assert good["ok"] is True
+
+
+def test_symlinked_artifact_dir_rejected_on_read(plane: ControlPlane, tmp_path: Path) -> None:
+    project = tmp_path / "proj-read"
+    project.mkdir()
+    outside = tmp_path / "outside-read"
+    outside.mkdir()
+    (outside / "NEXT_STEP.md").write_text("# escaped secret\n", encoding="utf-8")
+    (project / "Projek-Managment").symlink_to(outside)
+
+    r = plane.read_artifacts(str(project))
+    assert r["ok"] is False
+    assert r["error"] == "path_outside_root"
+
+    g = plane.get_next_step(str(project))
+    assert g["ok"] is False
+    assert g["error"] == "path_outside_root"
+
+
+def test_symlinked_individual_artifact_file_not_followed(plane: ControlPlane, tmp_path: Path) -> None:
+    project = tmp_path / "proj-file"
+    project.mkdir()
+    ad = project / "Projek-Managment"
+    ad.mkdir()
+    outside = tmp_path / "outside-file"
+    outside.mkdir()
+    secret = outside / "secret.md"
+    secret.write_text("# leaked next step\n", encoding="utf-8")
+    secret_before = secret.read_bytes()
+    # NEXT_STEP.md is a symlink pointing outside the artifact dir
+    (ad / "NEXT_STEP.md").symlink_to(secret)
+
+    g = plane.get_next_step(str(project))
+    assert g["ok"] is False
+    assert g["error"] == "path_outside_root"
+
+    arts = plane.read_artifacts(str(project))
+    # the escaping file must not be surfaced as an artifact
+    assert "NEXT_STEP.md" not in arts.get("present", [])
+
+    # checkpoint must also skip the escaping symlink, not snapshot it
+    cp = plane.checkpoint(note="risk", project_path=str(project))
+    assert cp["ok"] is True
+    assert "NEXT_STEP.md" not in cp["meta"].get("artifacts", {})
+
+    assert secret.read_bytes() == secret_before

hai-mcp-pr7/tests/test_eval_ab.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from hai_mcp.eval_ab import run_pair, score_arm
+
+
+FIXTURE_DIR = Path(__file__).parent / "fixtures" / "ab"
+
+
+def _load_case(name: str) -> dict:
+    return json.loads((FIXTURE_DIR / name).read_text())
+
+
+def _good_arm(intake_text: str) -> tuple[str, str, list[str]]:
+    return (
+        "Freeze the v0 A/B contract",
+        "Add the deterministic fixture harness",
+        ["Run provider-backed evaluation in Item 6"],
+    )
+
+
+def _cardinality_violator(intake_text: str) -> tuple[str, str, list[str]]:
+    return ("Decision one\nDecision two", "One next step", [])
+
+
+@pytest.mark.parametrize("fixture_name", ["case1.json", "case2.json"])
+def test_score_arm_applies_both_deterministic_criteria(fixture_name: str) -> None:
+    case = _load_case(fixture_name)
+
+    good = score_arm(case["intake_text"], _good_arm(case["intake_text"]))
+    bad = score_arm(case["intake_text"], _cardinality_violator(case["intake_text"]))
+
+    assert good["criteria"] == {"a": 1, "b": 1}
+    assert good["score"] == 2
+    assert bad["criteria"]["a"] == 0
+    assert bad["score"] == 0
+
+
+@pytest.mark.parametrize("fixture_name", ["case1.json", "case2.json"])
+def test_run_pair_returns_good_arm_as_winner(fixture_name: str) -> None:
+    case = _load_case(fixture_name)
+
+    result = run_pair(
+        case,
+        _good_arm,
+        _cardinality_violator,
+    )
+
+    assert result["winner"] == "A"
+    assert result["arm_a"]["score"] == 2
+    assert result["arm_b"]["criteria"]["a"] == 0

hai-mcp-pr7/tests/test_flow_tools.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import importlib
+import os
+from pathlib import Path
+
+import pytest
+
+from hai_mcp.config import Config
+from hai_mcp.state import ControlPlane
+
+
+@pytest.fixture
+def plane(tmp_path: Path) -> ControlPlane:
+    return ControlPlane(Config(hai_home=tmp_path / "hai_home"))
+
+
+@pytest.fixture
+def project(tmp_path: Path) -> Path:
+    p = tmp_path / "proj"
+    (p / "tests").mkdir(parents=True)
+    return p
+
+
+def _criteria() -> list[dict]:
+    return [
+        {"id": "dc-1", "description": "first"},
+        {"id": "dc-2", "description": "second"},
+    ]
+
+
+# --- intake ---
+
+def test_intake_captures_non_actionable(plane: ControlPlane) -> None:
+    r = plane.intake("Maybe rebuild HAI, move to Mac, deploy router")
+    assert r["ok"] is True
+    assert r["actionable"] is False
+    assert r["intake_id"].startswith("I-")
+    stored = plane.intake_dir / f"{r['intake_id']}.json"
+    assert stored.is_file()
+
+
+def test_intake_rejects_empty(plane: ControlPlane) -> None:
+    r = plane.intake("   ")
+    assert r["ok"] is False
+    assert r["error"] == "invalid_args"
+
+
+def test_intake_rejects_store_symlink_outside_root_without_writing(plane: ControlPlane, tmp_path: Path) -> None:
+    outside = tmp_path / "outside-intake"
+    outside.mkdir()
+    sentinel = outside / "sentinel.json"
+    original = b"do not overwrite"
+    sentinel.write_bytes(original)
+    plane.intake_dir.symlink_to(outside, target_is_directory=True)
+
+    r = plane.intake("must stay inside HAI_HOME")
+
+    assert r["ok"] is False
+    assert r["error"] == "path_outside_root"
+    assert sentinel.read_bytes() == original
+
+
+# --- distill: 1/1/park cardinality ---
+
+def test_distill_enforces_single_decision_and_parks_rest(plane: ControlPlane) -> None:
+    cap = plane.intake("many ideas at once")
+    before_inbox = len(list(plane.inbox_dir.glob("*.md"))) if plane.inbox_dir.is_dir() else 0
+    r = plane.distill(
+        intake_id=cap["intake_id"],
+        decision="Harden the MCP core",
+        next_step="Write the failing path-traversal test",
+        parklist=["idea A", "idea B", "idea C"],
+    )
+    assert r["ok"] is True
+    assert r["decision"] == "Harden the MCP core"
+    assert r["parked_count"] == 3
+    after_inbox = len(list(plane.inbox_dir.glob("*.md")))
+    assert after_inbox == before_inbox + 3
+
+
+def test_distill_rejects_missing_or_bundled_fields(plane: ControlPlane) -> None:
+    cap = plane.intake("x")
+    assert plane.distill(cap["intake_id"], "", "step")["error"] == "invalid_args"
+    assert plane.distill(cap["intake_id"], "decision", "")["error"] == "invalid_args"
+    bundled = plane.distill(cap["intake_id"], "do A\ndo B\ndo C", "one step")
+    assert bundled["ok"] is False
+    assert bundled["error"] == "invalid_args"
+
+
+def test_distill_rejects_unknown_and_malformed_intake(plane: ControlPlane) -> None:
+    assert plane.distill("../../escape", "d", "s")["error"] == "invalid_args"
+    assert plane.distill("I-20000101T000000-abcdef12", "d", "s")["error"] == "invalid_args"
+
+
+def test_distill_rejects_store_symlink_outside_root_without_writing(plane: ControlPlane, tmp_path: Path) -> None:
+    cap = plane.intake("distill this safely")
+    outside = tmp_path / "outside-distillations"
+    outside.mkdir()
+    sentinel = outside / "sentinel.json"
+    original = b"do not overwrite"
+    sentinel.write_bytes(original)
+    plane.distill_dir.symlink_to(outside, target_is_directory=True)
+
+    r = plane.distill(cap["intake_id"], "one decision", "one next step")
+
+    assert r["ok"] is False
+    assert r["error"] == "path_outside_root"
+    assert sentinel.read_bytes() == original
+
+
+# --- mission_start + drift_check: the REAL server wrappers, isolated HAI_HOME ---
+
+def test_mission_start_wrapper_opens_canonical_contract(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    import json
+
+    project = tmp_path / "proj"
+    (project / "tests").mkdir(parents=True)
+    monkeypatch.setenv("HAI_HOME", str(tmp_path / "ms-home"))
+    import hai_mcp.server as server
+
+    importlib.reload(server)
+    out = json.loads(
+        server.hai_mission_start(
+            problem="Ship the hardening slice",
+            artifact="tests/green.py",
+            done_criteria=_criteria(),
+            owner="samuel",
+            time_limit_hours=2,
+            constraints={"project_path": str(project), "allowed_paths": ["tests/"]},
+        )
+    )
+    assert out["ok"] is True
+    assert out["status"] == "active"
+    assert out["contract"]["objective"] == "Ship the hardening slice"
+    assert out["contract"]["constraints"]["time_limit_hours"] == 2
+
+
+def test_drift_check_wrapper_flags_out_of_scope_path(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    import json
+
+    project = tmp_path / "proj2"
+    (project / "tests").mkdir(parents=True)
+    monkeypatch.setenv("HAI_HOME", str(tmp_path / "dc-home"))
+    import hai_mcp.server as server
+
+    importlib.reload(server)
+    opened = json.loads(
+        server.hai_mission_start(
+            problem="drift wrapper",
+            artifact="tests/x.py",
+            done_criteria=_criteria(),
+            owner="samuel",
+            constraints={"project_path": str(project), "allowed_paths": ["tests/"]},
+        )
+    )
+    auth = json.loads(
+        server.hai_authorize_session(
+            mission_id=opened["mission_id"],
+            contract_version=opened["contract_version"],
+            agent_identity="composer",
+            role="builder",
+            contribution="x",
+            expected_result="y",
+            duration_minutes=30,
+            criterion_ids=["dc-1"],
+        )
+    )
+    r = json.loads(
+        server.hai_drift_check(
+            session_id=auth["session_id"],
+            activity_step="touch outside",
+            criterion_id="dc-1",
+            affected_paths=[str(project / "outside" / "secret.txt")],
+        )
+    )
+    assert r["classification"] == "drift"
+    assert r["required_action"] == "stop"
+
+
+# --- proof (thin wrapper over close_mission=completed) ---
+
+def test_proof_completes_with_verified_evidence(plane: ControlPlane, project: Path) -> None:
+    opened = plane.open_mission(
+        objective="Prove completion",
+        artifact="tests/out.py",
+        done_criteria=_criteria(),
+        non_goals=[],
+        constraints={"project_path": str(project), "allowed_paths": ["tests/"]},
+        owner="samuel",
+    )
+    ev1 = project / "tests" / "p1.txt"
+    ev2 = project / "tests" / "p2.txt"
+    ev1.write_text("a", encoding="utf-8")
+    ev2.write_text("b", encoding="utf-8")
+    r = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        evidence={"dc-1": {"path": str(ev1)}, "dc-2": {"path": str(ev2)}},
+        outcome_summary="done",
+        closure="completed",
+    )
+    assert r["status"] == "completed"
+
+
+# --- stop (day terminal) ---
+
+def test_stop_seals_day_and_revokes_leases_without_closing_mission(plane: ControlPlane, project: Path) -> None:
+    opened = plane.open_mission(
+        objective="Work then stop",
+        artifact="tests/out.py",
+        done_criteria=_criteria(),
+        non_goals=[],
+        constraints={"project_path": str(project), "allowed_paths": ["tests/"]},
+        owner="samuel",
+    )
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="work",
+        expected_result="done",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    r = plane.stop_day(day="2026-07-22", loop_closed=True, clearer="yes", agency_gained="high")
+    assert r["ok"] is True
+    assert r["status"] == "day_stopped"
+    assert r["next_mission"] is None
+    assert auth["session_id"] in r["revoked_sessions"]
+    # mission is paused (leases gone) but NOT closed
+    assert plane.mission.load_mission_meta(opened["mission_id"])["status"] == "active"
+    # the revoked lease can no longer act
+    got = plane.get_contract(auth["session_id"])
+    assert got["ok"] is False
+
+
+def test_stop_requires_day(plane: ControlPlane) -> None:
+    assert plane.stop_day(day="", loop_closed=False, clearer="", agency_gained="")["error"] == "invalid_args"
+
+
+def test_stop_rejects_store_symlink_outside_root_without_writing(plane: ControlPlane, tmp_path: Path) -> None:
+    outside = tmp_path / "outside-stops"
+    outside.mkdir()
+    sentinel = outside / "sentinel.json"
+    original = b"do not overwrite"
+    sentinel.write_bytes(original)
+    plane.stop_dir.symlink_to(outside, target_is_directory=True)
+
+    r = plane.stop_day(day="2026-07-22", loop_closed=True, clearer="yes", agency_gained="high")
+
+    assert r["ok"] is False
+    assert r["error"] == "path_outside_root"
+    assert sentinel.read_bytes() == original
+
+
+# --- Item 4: full public surface is registered / discoverable (isolated HAI_HOME) ---
+
+def test_additional_seven_tools_registered(tmp_path: Path) -> None:
+    os.environ["HAI_HOME"] = str(tmp_path / "discovery-home")
+    import hai_mcp.server as server
+
+    importlib.reload(server)
+    registered = {tool.name for tool in server.mcp._tool_manager.list_tools()}
+
+    additional_seven = {
+        "hai_intake",
+        "hai_distill",
+        "hai_mission_start",
+        "hai_park",
+        "hai_drift_check",
+        "hai_proof",
+        "hai_stop",
+    }
+    core_seven = {
+        "hai_open_mission",
+        "hai_authorize_session",
+        "hai_get_contract",
+        "hai_check_activity",
+        "hai_park_item",
+        "hai_recontract",
+        "hai_close_mission",
+    }
+    assert additional_seven.issubset(registered)
+    assert core_seven.issubset(registered)

hai-mcp-pr7/tests/test_impact_eval_v1.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import json
+
+from hai_mcp.eval_impact import CELLS, run_impact_eval_v1, write_run_artifact
+
+
+def test_impact_eval_v1_all_six_cells_hard_pass() -> None:
+    summary = run_impact_eval_v1()
+    artifact = write_run_artifact(summary)
+    disk = json.loads(artifact.read_text(encoding="utf-8"))
+    assert disk["cell_count"] == 6 == len(CELLS)
+    assert disk["invalid"] == 0, disk
+    assert disk["hard_pass"] == 6, disk
+    assert disk["ok"] is True
+    assert disk["provider"] is None
+    assert disk["touches_live_dot_hai"] is False

hai-mcp-pr7/tests/test_mission_lifecycle.py

@@ -0,0 +1,1194 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+import pytest
+
+from hai_mcp.config import Config
+from hai_mcp.ids import IdentifierError
+from hai_mcp.mission import MissionEngine, contract_hash
+from hai_mcp.state import ControlPlane
+
+
+@pytest.fixture
+def plane(tmp_path: Path) -> ControlPlane:
+    home = tmp_path / "hai_home"
+    return ControlPlane(Config(hai_home=home))
+
+
+@pytest.fixture
+def project(tmp_path: Path) -> Path:
+    p = tmp_path / "proj"
+    (p / "src").mkdir(parents=True)
+    (p / "tests").mkdir(parents=True)
+    return p
+
+
+def _valid_contract(project: Path) -> dict:
+    return {
+        "objective": "Implement drift classifier tests",
+        "artifact": "tests/test_mission_lifecycle.py with green pytest",
+        "done_criteria": [
+            {"id": "dc-1", "description": "mission lifecycle tests exist and pass"},
+            {"id": "dc-2", "description": "contract hash is stable"},
+        ],
+        "non_goals": ["rewrite entire architecture", "deploy to production"],
+        "constraints": {
+            "project_path": str(project),
+            "allowed_paths": ["src/", "tests/"],
+            "capabilities": ["read", "write", "test"],
+            "max_parallel_sessions": 1,
+        },
+        "owner": "samuel",
+    }
+
+
+def _open(plane: ControlPlane, project: Path) -> dict:
+    c = _valid_contract(project)
+    return plane.open_mission(
+        objective=c["objective"],
+        artifact=c["artifact"],
+        done_criteria=c["done_criteria"],
+        non_goals=c["non_goals"],
+        constraints=c["constraints"],
+        owner=c["owner"],
+    )
+
+
+def test_open_mission_happy_path(plane: ControlPlane, project: Path) -> None:
+    r = _open(plane, project)
+    assert r["ok"] is True
+    assert r["status"] == "active"
+    assert r["contract_version"] == 1
+    assert r["contract_hash"].startswith("sha256:")
+    assert r["contract"]["objective"] == _valid_contract(project)["objective"]
+    assert plane.mission.load_active_pointer()["mission_id"] == r["mission_id"]
+
+
+def test_open_mission_review_required_missing_artifact(plane: ControlPlane, project: Path) -> None:
+    r = plane.open_mission(
+        objective="Do something",
+        artifact="",
+        done_criteria=[{"id": "dc-1", "description": "x"}],
+        non_goals=[],
+        constraints={"project_path": str(project)},
+        owner="samuel",
+    )
+    assert r["ok"] is False
+    assert r["error"] == "review_required"
+    assert r["status"] == "review_required"
+    assert "artifact is required" in r["issues"]
+    assert plane.mission.load_active_pointer()["mission_id"] is None
+
+
+def test_open_mission_review_required_vague_objective(plane: ControlPlane, project: Path) -> None:
+    r = plane.open_mission(
+        objective="an HAI arbeiten",
+        artifact="some/file.py",
+        done_criteria=[{"id": "dc-1", "description": "x"}],
+        non_goals=[],
+        constraints={"project_path": str(project)},
+        owner="samuel",
+    )
+    assert r["ok"] is False
+    assert r["error"] == "review_required"
+    assert r["status"] == "review_required"
+    assert any("too broad" in i for i in r["issues"])
+
+
+def test_second_active_mission_denied(plane: ControlPlane, project: Path) -> None:
+    first = _open(plane, project)
+    second = _open(plane, project)
+    assert second["ok"] is False
+    assert second["error"] == "active_mission_exists"
+    assert second["active_mission_id"] == first["mission_id"]
+
+
+def test_contract_hash_stable(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    contract = opened["contract"]
+    body = {k: v for k, v in contract.items() if k != "contract_hash"}
+    assert contract_hash(body) == opened["contract_hash"]
+
+
+def test_authorize_and_get_contract_exact(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="write lifecycle tests",
+        expected_result="pytest green",
+        duration_minutes=45,
+        criterion_ids=["dc-1"],
+        capabilities=["read", "write", "test"],
+    )
+    assert auth["ok"] is True
+    assert auth["status"] == "granted"
+    session_id = auth["session_id"]
+
+    got = plane.get_contract(session_id)
+    assert got["ok"] is True
+    assert got["contract"] == opened["contract"]
+    assert got["contract_hash"] == opened["contract_hash"]
+    assert got["remaining_seconds"] > 0
+
+
+def test_authorize_wrong_version_denied(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    r = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=99,
+        agent_identity="composer",
+        role="builder",
+        contribution="x",
+        expected_result="y",
+        duration_minutes=10,
+        criterion_ids=["dc-1"],
+    )
+    assert r["ok"] is False
+    assert r["error"] == "contract_version_mismatch"
+
+
+def test_parallel_session_denied(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    a = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="a",
+        role="builder",
+        contribution="first",
+        expected_result="x",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    b = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="b",
+        role="builder",
+        contribution="second",
+        expected_result="y",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    assert a["ok"] is True
+    assert b["ok"] is False
+    assert b["error"] == "parallel_session_denied"
+
+
+def test_expired_lease_cannot_get_contract(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="x",
+        expected_result="y",
+        duration_minutes=1,
+        criterion_ids=["dc-1"],
+    )
+    session = plane.mission.get_session(auth["session_id"])
+    assert session is not None
+    session["expires_at"] = "2000-01-01T00:00:00Z"
+    plane.mission.save_session(session)
+
+    got = plane.get_contract(auth["session_id"])
+    assert got["ok"] is False
+    assert got["error"] == "lease_expired"
+    assert got["required_action"] == "pause"
+
+
+def test_check_activity_in_scope(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="tests",
+        expected_result="green",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    r = plane.check_activity(
+        session_id=auth["session_id"],
+        activity_step="add lifecycle test cases",
+        criterion_id="dc-1",
+        affected_paths=[str(project / "tests" / "test_mission_lifecycle.py")],
+    )
+    assert r["classification"] == "in_scope"
+    assert r["required_action"] == "continue"
+
+
+def test_check_activity_blocker(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="tests",
+        expected_result="green",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    r = plane.check_activity(
+        session_id=auth["session_id"],
+        activity_step="missing dependency blocks tests",
+        criterion_id="dc-1",
+        declares_blocker=True,
+    )
+    assert r["classification"] == "blocker"
+    assert r["required_action"] == "pause"
+
+
+def test_check_activity_park_candidate(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="tests",
+        expected_result="green",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    r = plane.check_activity(
+        session_id=auth["session_id"],
+        activity_step="rewrite entire architecture for fun",
+        criterion_id="dc-1",
+    )
+    assert r["classification"] == "park_candidate"
+    assert r["required_action"] == "park"
+
+
+def test_check_activity_drift_path(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="tests",
+        expected_result="green",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    r = plane.check_activity(
+        session_id=auth["session_id"],
+        activity_step="edit docs",
+        criterion_id="dc-1",
+        affected_paths=[str(project / "outside" / "secret.txt")],
+    )
+    assert r["classification"] == "drift"
+    assert r["required_action"] == "stop"
+
+
+def test_check_activity_drift_sensitive_trace(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="tests",
+        expected_result="green",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+        capabilities=["read", "write", "test"],
+    )
+    r = plane.check_activity(
+        session_id=auth["session_id"],
+        activity_step="commit changes",
+        criterion_id="dc-1",
+        trace_events=[{"action": "commit"}],
+    )
+    assert r["classification"] == "drift"
+    assert r["required_action"] == "stop"
+
+
+def test_check_activity_unclear_missing_criterion(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="tests",
+        expected_result="green",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    r = plane.check_activity(
+        session_id=auth["session_id"],
+        activity_step="do something",
+        criterion_id=None,
+    )
+    assert r["classification"] == "unclear"
+    assert r["required_action"] == "pause"
+
+
+def test_park_item_mission_linked(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="tests",
+        expected_result="green",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    before_contract = plane.mission.current_contract(opened["mission_id"])
+    r = plane.park_item(
+        idea="maybe add kubernetes later",
+        origin_session_id=auth["session_id"],
+        trigger_event="check_activity park_candidate",
+        mission_id=opened["mission_id"],
+        rationale="out of current mission scope",
+    )
+    assert r["ok"] is True
+    assert r["status"] == "parked"
+    assert r["record"]["actionable"] is False
+    after_contract = plane.mission.current_contract(opened["mission_id"])
+    assert after_contract == before_contract
+
+
+def test_recontract_denied_without_owner_ack(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    r = plane.recontract(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        reason="allow docs path",
+        changes={"constraints": {**opened["contract"]["constraints"], "allowed_paths": ["src/", "tests/", "docs/"]}},
+        owner_ack=False,
+    )
+    assert r["ok"] is False
+    assert r["error"] == "owner_gate_required"
+    assert r["status"] == "pending_owner_confirmation"
+    assert r["owner_ack_required"] is True
+    assert r["diff"]
+    # denial must not create a new contract version
+    assert plane.mission.load_contract(opened["mission_id"], 2) is None
+
+
+def test_recontract_approval_diff_version_revokes_leases(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="tests",
+        expected_result="green",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    new_constraints = dict(opened["contract"]["constraints"])
+    new_constraints["allowed_paths"] = ["src/", "tests/", "docs/"]
+    r = plane.recontract(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        reason="need docs",
+        changes={"constraints": new_constraints},
+        owner_ack=True,
+    )
+    assert r["ok"] is True
+    assert r["status"] == "approved"
+    assert r["contract_version"] == 2
+    assert r["diff"]
+    assert auth["session_id"] in r["revoked_sessions"]
+
+    old_contract = plane.mission.load_contract(opened["mission_id"], 1)
+    new_contract = plane.mission.load_contract(opened["mission_id"], 2)
+    assert old_contract is not None and new_contract is not None
+    assert old_contract["contract_version"] == 1
+    assert new_contract["contract_version"] == 2
+
+    got = plane.get_contract(auth["session_id"])
+    assert got["ok"] is False
+
+
+def test_recontract_break_glass_friction(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    denied = plane.recontract(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        reason="emergency",
+        changes={"objective": "changed"},
+        owner_ack=True,
+        mode="break_glass",
+        break_glass_marker=False,
+    )
+    assert denied["ok"] is False
+    assert denied["error"] == "owner_gate_required"
+
+    ok = plane.recontract(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        reason="emergency",
+        changes={"objective": "changed emergency"},
+        owner_ack=True,
+        mode="break_glass",
+        break_glass_marker=True,
+    )
+    assert ok["ok"] is True
+    assert ok["audit_classification"] == "break_glass"
+
+
+def test_close_mission_incomplete_proof(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    r = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        evidence={"dc-1": {"path": str(project / "tests" / "x.py")}},
+        outcome_summary="done",
+        closure="completed",
+    )
+    assert r["status"] == "incomplete"
+    assert "dc-2" in r["missing_criteria"]
+
+
+def test_close_mission_path_traversal_rejected(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    outside = project.parent / "outside.txt"
+    outside.write_text("nope", encoding="utf-8")
+    r = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        evidence={
+            "dc-1": {"path": str(project / "tests" / "ok.py")},
+            "dc-2": {"path": str(outside)},
+        },
+        outcome_summary="done",
+        closure="completed",
+    )
+    assert r["status"] == "incomplete"
+    assert r["invalid_evidence"]
+
+
+def test_close_mission_symlink_escape_rejected(plane: ControlPlane, project: Path, tmp_path: Path) -> None:
+    opened = _open(plane, project)
+    outside = tmp_path / "secret.txt"
+    outside.write_text("secret", encoding="utf-8")
+    link = project / "tests" / "escape.link"
+    link.symlink_to(outside)
+    ev1 = project / "tests" / "proof1.txt"
+    ev1.write_text("ok", encoding="utf-8")
+    ev2 = project / "tests" / "proof2.txt"
+    ev2.write_text("ok", encoding="utf-8")
+    r = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        evidence={
+            "dc-1": {"path": str(ev1)},
+            "dc-2": {"path": str(link)},
+        },
+        outcome_summary="done",
+        closure="completed",
+    )
+    assert r["status"] == "incomplete"
+    assert any(
+        "symlink" in str(item.get("message", "")) or item.get("error") == "path_outside_root"
+        for item in r["invalid_evidence"]
+    )
+
+
+def test_close_mission_completed_with_hashes(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    ev1 = project / "tests" / "proof1.txt"
+    ev2 = project / "tests" / "proof2.txt"
+    ev1.write_text("proof one", encoding="utf-8")
+    ev2.write_text("proof two", encoding="utf-8")
+    r = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        evidence={"dc-1": {"path": str(ev1)}, "dc-2": {"path": str(ev2)}},
+        outcome_summary="lifecycle tests implemented",
+        closure="completed",
+    )
+    assert r["ok"] is True
+    assert r["status"] == "completed"
+    assert r["verified_criteria"]["dc-1"]["sha256"].startswith("sha256:")
+    assert r["next_mission"] is None
+    assert plane.mission.load_active_pointer()["mission_id"] is None
+
+
+def test_close_mission_abandoned_gate(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="tests",
+        expected_result="green",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    denied = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        evidence={},
+        outcome_summary="no longer needed",
+        closure="abandoned",
+        owner_ack=False,
+    )
+    assert denied["error"] == "owner_gate_required"
+
+    ok = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        evidence={},
+        outcome_summary="no longer needed",
+        closure="abandoned",
+        owner_ack=True,
+    )
+    assert ok["status"] == "abandoned"
+    assert auth["session_id"] in ok["revoked_sessions"]
+    assert plane.mission.load_active_pointer()["mission_id"] is None
+
+
+def test_audit_entries_unique_immutable(plane: ControlPlane, project: Path) -> None:
+    before = set(plane.mission.list_audit_ids())
+    _open(plane, project)
+    after = set(plane.mission.list_audit_ids())
+    new_ids = after - before
+    assert len(new_ids) >= 1
+    audit_dir = plane.mission.audit_dir
+    paths = sorted(audit_dir.glob("A-*.json"))
+    assert len(paths) == len({p.name for p in paths})
+
+
+def test_full_happy_lifecycle(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="implement and verify tests",
+        expected_result="pytest green",
+        duration_minutes=60,
+        criterion_ids=["dc-1", "dc-2"],
+    )
+    assert plane.get_contract(auth["session_id"])["ok"] is True
+    assert plane.check_activity(
+        session_id=auth["session_id"],
+        activity_step="write tests",
+        criterion_id="dc-1",
+        affected_paths=[str(project / "tests" / "lifecycle.py")],
+    )["required_action"] == "continue"
+
+    ev1 = project / "tests" / "lifecycle.py"
+    ev2 = project / "tests" / "hash.txt"
+    ev1.write_text("tests", encoding="utf-8")
+    ev2.write_text("hash", encoding="utf-8")
+    closed = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        evidence={"dc-1": {"path": str(ev1)}, "dc-2": {"path": str(ev2)}},
+        outcome_summary="all criteria verified",
+        closure="completed",
+    )
+    assert closed["status"] == "completed"
+
+
+def test_existing_owner_gates_regression(plane: ControlPlane, project: Path) -> None:
+    denied = plane.accept_next_step(str(project), owner_ack=False, reason="nope")
+    assert denied["error"] == "owner_gate_required"
+    plane.propose_next_step(str(project), "# step\n")
+    ok = plane.accept_next_step(str(project), owner_ack=True, reason="approved")
+    assert ok["ok"] is True
+
+
+def test_public_tool_registration() -> None:
+    import importlib
+
+    import hai_mcp.server as server
+
+    importlib.reload(server)
+
+    core_tools = {
+        "hai_open_mission",
+        "hai_authorize_session",
+        "hai_get_contract",
+        "hai_check_activity",
+        "hai_park_item",
+        "hai_recontract",
+        "hai_close_mission",
+    }
+    assert hasattr(server.mcp, "_tool_manager")
+    registered = {tool.name for tool in server.mcp._tool_manager.list_tools()}
+    assert core_tools.issubset(registered)
+
+
+def test_server_import_does_not_touch_live_hai_home(tmp_path: Path) -> None:
+    import importlib
+    import os
+
+    live_home = Path.home() / ".hai"
+    marker = live_home / "ACTIVE_CONTEXT.json"
+    before_mtime = marker.stat().st_mtime if marker.is_file() else None
+
+    isolated = tmp_path / "import-isolation-home"
+    os.environ["HAI_HOME"] = str(isolated)
+    import hai_mcp.server as server
+
+    importlib.reload(server)
+    server.get_control_plane()
+
+    assert not isolated.exists() or isolated.resolve() != live_home.resolve()
+    if before_mtime is not None:
+        assert marker.stat().st_mtime == before_mtime
+
+
+def test_malformed_mission_id_rejected(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    # A syntactically invalid id must fail closed, never be masked as not-found (None).
+    with pytest.raises(IdentifierError) as exc:
+        plane.mission.load_mission_meta("../../escape")
+    assert exc.value.code == "invalid_args"
+    assert exc.value.field == "mission_id"
+    r = plane.authorize_session(
+        mission_id="../../escape",
+        contract_version=1,
+        agent_identity="a",
+        role="builder",
+        contribution="x",
+        expected_result="y",
+        duration_minutes=10,
+        criterion_ids=["dc-1"],
+    )
+    assert r["ok"] is False
+    assert r["error"] == "invalid_args"
+    r2 = plane.close_mission(
+        mission_id="../missions/other",
+        contract_version=opened["contract_version"],
+        evidence={},
+        outcome_summary="x",
+        closure="abandoned",
+        owner_ack=True,
+    )
+    assert r2["ok"] is False
+    assert r2["error"] == "invalid_args"
+
+
+def test_malformed_session_id_rejected(plane: ControlPlane, project: Path) -> None:
+    _open(plane, project)
+    got = plane.get_contract("../../sessions/evil")
+    assert got["ok"] is False
+    assert got["error"] == "invalid_args"
+
+
+def test_duplicate_done_criteria_rejected(plane: ControlPlane, project: Path) -> None:
+    r = plane.open_mission(
+        objective="Test duplicate criteria",
+        artifact="tests/file.py",
+        done_criteria=[
+            {"id": "dc-1", "description": "first"},
+            {"id": "dc-1", "description": "duplicate"},
+        ],
+        non_goals=[],
+        constraints={"project_path": str(project)},
+        owner="samuel",
+    )
+    assert r["ok"] is False
+    assert r["error"] == "review_required"
+    assert r["status"] == "review_required"
+    assert any("duplicate" in i for i in r["issues"])
+
+
+def test_authorize_requires_identity_fields(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    base = dict(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        contribution="work",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    for missing in ("agent_identity", "role", "expected_result"):
+        kwargs = {
+            "agent_identity": "composer",
+            "role": "builder",
+            "expected_result": "done",
+            **base,
+        }
+        kwargs[missing] = ""
+        r = plane.authorize_session(**kwargs)
+        assert r["ok"] is False
+        assert r["error"] == "invalid_args"
+
+
+def test_authorize_invalid_duration_type(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    r = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="work",
+        expected_result="done",
+        duration_minutes="not-a-number",  # type: ignore[arg-type]
+        criterion_ids=["dc-1"],
+    )
+    assert r["ok"] is False
+    assert r["error"] == "invalid_args"
+
+
+def test_check_activity_blocker_does_not_hide_drift(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="tests",
+        expected_result="green",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    r = plane.check_activity(
+        session_id=auth["session_id"],
+        activity_step="blocked but outside path",
+        criterion_id="dc-1",
+        affected_paths=[str(project / "outside" / "secret.txt")],
+        declares_blocker=True,
+    )
+    assert r["classification"] == "drift"
+    assert r["required_action"] == "stop"
+
+
+def test_stale_lease_after_recontract(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="tests",
+        expected_result="green",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    new_constraints = dict(opened["contract"]["constraints"])
+    new_constraints["allowed_paths"] = ["src/", "tests/", "docs/"]
+    plane.recontract(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        reason="expand paths",
+        changes={"constraints": new_constraints},
+        owner_ack=True,
+    )
+    got = plane.get_contract(auth["session_id"])
+    assert got["ok"] is False
+    assert got["error"] == "contract_version_mismatch"
+
+
+def test_recontract_rejects_system_managed_field(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    r = plane.recontract(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        reason="sneaky",
+        changes={"mission_id": "M-HIDDEN"},
+        owner_ack=False,
+    )
+    assert r["ok"] is False
+    assert r["error"] == "invalid_args"
+    assert "system-managed" in r["message"]
+
+
+def test_recontract_rejects_empty_diff(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    r = plane.recontract(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        reason="noop",
+        changes={},
+        owner_ack=False,
+    )
+    assert r["ok"] is False
+    assert "empty diff" in r["message"]
+
+
+def test_recontract_rejects_invalid_mode(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    r = plane.recontract(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        reason="bad mode",
+        changes={"objective": "new objective text"},
+        owner_ack=False,
+        mode="turbo",
+    )
+    assert r["ok"] is False
+    assert r["error"] == "invalid_args"
+
+
+def test_recontract_preserves_owner(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    new_constraints = dict(opened["contract"]["constraints"])
+    new_constraints["owner"] = "impostor"
+    new_constraints["allowed_paths"] = ["src/", "tests/", "docs/"]
+    r = plane.recontract(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        reason="try owner swap while expanding paths",
+        changes={"constraints": new_constraints},
+        owner_ack=True,
+    )
+    assert r["ok"] is True
+    assert r["contract"]["constraints"]["owner"] == "samuel"
+    assert "docs/" in r["contract"]["constraints"]["allowed_paths"]
+
+
+def test_close_requires_outcome_summary(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    ev1 = project / "tests" / "proof1.txt"
+    ev2 = project / "tests" / "proof2.txt"
+    ev1.write_text("one", encoding="utf-8")
+    ev2.write_text("two", encoding="utf-8")
+    r = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        evidence={"dc-1": {"path": str(ev1)}, "dc-2": {"path": str(ev2)}},
+        outcome_summary="",
+        closure="completed",
+    )
+    assert r["ok"] is False
+    assert r["error"] == "invalid_args"
+
+
+def test_close_rejects_directory_evidence(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    ev_dir = project / "tests" / "proofdir"
+    ev_dir.mkdir(parents=True, exist_ok=True)
+    ev2 = project / "tests" / "proof2.txt"
+    ev2.write_text("two", encoding="utf-8")
+    r = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        evidence={"dc-1": {"path": str(ev_dir)}, "dc-2": {"path": str(ev2)}},
+        outcome_summary="done",
+        closure="completed",
+    )
+    assert r["status"] == "incomplete"
+    assert any("directory" in str(item.get("message", "")) for item in r["invalid_evidence"])
+
+
+def test_park_item_requires_trigger_and_valid_origin(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    denied = plane.park_item(
+        idea="later idea",
+        origin_session_id="S-00000000T000000-00000000",
+        trigger_event="",
+        mission_id=opened["mission_id"],
+        rationale="out of scope",
+    )
+    assert denied["ok"] is False
+    assert "trigger_event" in denied["message"]
+
+    denied2 = plane.park_item(
+        idea="later idea",
+        origin_session_id="S-00000000T000000-00000000",
+        trigger_event="idea surfaced",
+        mission_id=opened["mission_id"],
+        rationale="out of scope",
+    )
+    assert denied2["ok"] is False
+    assert "origin_session_id" in denied2["message"]
+
+
+def test_lease_expiry_audited(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="x",
+        expected_result="y",
+        duration_minutes=1,
+        criterion_ids=["dc-1"],
+    )
+    session = plane.mission.get_session(auth["session_id"])
+    assert session is not None
+    session["expires_at"] = "2000-01-01T00:00:00Z"
+    plane.mission.save_session(session)
+    before = set(plane.mission.list_audit_ids())
+    plane.get_contract(auth["session_id"])
+    after = set(plane.mission.list_audit_ids())
+    new_events = after - before
+    assert new_events
+    latest = sorted(new_events)[-1]
+    payload = json.loads((plane.mission.audit_dir / f"{latest}.json").read_text(encoding="utf-8"))
+    assert payload["event_type"] == "lease_expired"
+
+
+def _open_without_project(plane: ControlPlane) -> dict:
+    return plane.open_mission(
+        objective="Harden without a bound project root",
+        artifact="notes.md",
+        done_criteria=[
+            {"id": "dc-1", "description": "first"},
+            {"id": "dc-2", "description": "second"},
+        ],
+        non_goals=[],
+        constraints={},  # deliberately no project_path
+        owner="samuel",
+    )
+
+
+@pytest.mark.parametrize("expected_prefix", ["M", "S", "I"])
+@pytest.mark.parametrize(
+    "bad",
+    [
+        "X-20260722T010203-abcdef12",  # wrong prefix
+        "M-20260722T010203-abcdef12/evil",  # separator
+        "M-20260722T010203-abcdef12\\evil",  # backslash
+        "../../escape",  # traversal
+        "/abs/path",  # absolute
+        "M-20260722T010203-abcdef12\x00",  # null byte
+        " M-20260722T010203-abcdef12 ",  # whitespace padded
+        "M-20260722T010203-abcdef12\n",  # trailing newline (Python $ bypass)
+        "M-2026-abcdef12",  # wrong length/shape
+        "M-20260722T010203-ABCDEF12",  # uppercase hex not allowed
+        12345,  # not a string
+    ],
+)
+def test_generated_id_validator_rejects_malformed(expected_prefix: str, bad: object) -> None:
+    from hai_mcp.ids import require_generated_id, validate_generated_id
+
+    ok, _ = validate_generated_id(bad, expected_prefix=expected_prefix)
+    assert ok is False
+    with pytest.raises(IdentifierError) as exc:
+        require_generated_id(bad, expected_prefix=expected_prefix)
+    assert exc.value.code == "invalid_args"
+
+
+def test_intake_id_prefix_supported() -> None:
+    from hai_mcp.ids import validate_intake_id
+
+    assert validate_intake_id("I-20260722T010203-abcdef12")[0] is True
+    assert validate_intake_id("M-20260722T010203-abcdef12")[0] is False
+
+
+@pytest.mark.parametrize("ack", [False, None, 0, 1, "true"])
+def test_recontract_requires_literal_owner_ack_true(plane: ControlPlane, project: Path, ack: object) -> None:
+    opened = _open(plane, project)
+    new_constraints = dict(opened["contract"]["constraints"])
+    new_constraints["allowed_paths"] = ["src/", "tests/", "docs/"]
+    r = plane.recontract(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        reason="expand",
+        changes={"constraints": new_constraints},
+        owner_ack=ack,  # type: ignore[arg-type]
+    )
+    assert r["ok"] is False
+    assert r["error"] == "owner_gate_required"
+    assert plane.mission.load_contract(opened["mission_id"], 2) is None
+    assert plane.mission.current_contract(opened["mission_id"])["contract_version"] == 1
+
+
+def test_recontract_cannot_change_mission_id_even_with_owner_ack(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    r = plane.recontract(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        reason="sneaky id swap",
+        changes={"mission_id": "M-20000101T000000-deadbeef"},
+        owner_ack=True,
+    )
+    assert r["ok"] is False
+    assert r["error"] == "invalid_args"
+    assert plane.mission.load_contract(opened["mission_id"], 2) is None
+    assert plane.mission.current_contract(opened["mission_id"])["mission_id"] == opened["mission_id"]
+
+
+@pytest.mark.parametrize("bad_prefix", ["../", "/abs/root", "src/../.."])
+def test_open_mission_rejects_unsafe_allowed_paths(plane: ControlPlane, project: Path, bad_prefix: str) -> None:
+    r = plane.open_mission(
+        objective="test unsafe allowed paths",
+        artifact="tests/file.py",
+        done_criteria=[{"id": "dc-1", "description": "x"}],
+        non_goals=[],
+        constraints={"project_path": str(project), "allowed_paths": [bad_prefix]},
+        owner="samuel",
+    )
+    assert r["ok"] is False
+    assert r["error"] == "review_required"
+    assert r["status"] == "review_required"
+    assert any("allowed_paths" in i for i in r["issues"])
+
+
+def test_check_activity_rejects_path_when_no_project_root(plane: ControlPlane) -> None:
+    opened = _open_without_project(plane)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="x",
+        expected_result="y",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    r = plane.check_activity(
+        session_id=auth["session_id"],
+        activity_step="read secrets",
+        criterion_id="dc-1",
+        affected_paths=["/etc/passwd"],
+    )
+    # without a bound project root, an unvalidatable path must be refused, not allowed
+    assert r["classification"] == "drift"
+    assert r["required_action"] == "stop"
+
+
+def test_check_activity_null_byte_path_is_structured_not_raised(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="x",
+        expected_result="y",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    r = plane.check_activity(
+        session_id=auth["session_id"],
+        activity_step="edit",
+        criterion_id="dc-1",
+        affected_paths=["src/foo\x00.py"],
+    )
+    assert r["classification"] == "drift"
+    assert r["required_action"] == "stop"
+
+
+def test_close_mission_rejects_evidence_without_project_root(plane: ControlPlane, tmp_path: Path) -> None:
+    opened = _open_without_project(plane)
+    real_file = tmp_path / "pyproject.toml"
+    real_file.write_text("[tool]\n", encoding="utf-8")
+    r = plane.close_mission(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        evidence={"dc-1": {"path": str(real_file)}, "dc-2": {"path": str(real_file)}},
+        outcome_summary="claiming done with a foreign file",
+        closure="completed",
+    )
+    assert r["status"] == "incomplete"
+    assert r["invalid_evidence"]
+    assert all(item.get("error") == "invalid_args" for item in r["invalid_evidence"])
+    # the foreign file must NOT have been hashed/accepted as proof
+    assert not r.get("verified_criteria")
+    assert all("sha256" not in item for item in r["invalid_evidence"])
+    assert plane.mission.load_mission_meta(opened["mission_id"])["status"] == "active"
+
+
+def test_contract_and_sessions_symlink_escape_rejected(plane: ControlPlane, project: Path, tmp_path: Path) -> None:
+    opened = _open(plane, project)
+    mid = opened["mission_id"]
+    mdir = plane.mission.missions_dir / mid
+    outside = tmp_path / "escape-store"
+    outside.mkdir()
+    sentinel = outside / "stolen.json"
+    sentinel.write_text('{"secret": true}', encoding="utf-8")
+    sentinel_before = sentinel.read_bytes()
+
+    # replace sessions/ with a symlink pointing outside HAI_HOME
+    import shutil
+
+    shutil.rmtree(mdir / "sessions")
+    (mdir / "sessions").symlink_to(outside)
+
+    from hai_mcp.paths import PathError
+
+    with pytest.raises(PathError) as exc:
+        plane.mission.sessions_dir(mid)
+    assert exc.value.code == "path_outside_root"
+    # get_session must not follow the escape either
+    assert plane.mission.get_session("S-20000101T000000-abcdef12") is None
+    # and the public surface must fail closed with an exact code, not leak
+    got = plane.get_contract("S-20000101T000000-abcdef12")
+    assert got["ok"] is False
+    assert got["error"] == "invalid_args"
+    assert sentinel.read_bytes() == sentinel_before
+
+
+def test_get_session_binds_stored_ids(plane: ControlPlane, project: Path) -> None:
+    opened = _open(plane, project)
+    auth = plane.authorize_session(
+        mission_id=opened["mission_id"],
+        contract_version=opened["contract_version"],
+        agent_identity="composer",
+        role="builder",
+        contribution="x",
+        expected_result="y",
+        duration_minutes=30,
+        criterion_ids=["dc-1"],
+    )
+    sid = auth["session_id"]
+    sdir = plane.mission.sessions_dir(opened["mission_id"])
+    session_file = sdir / f"{sid}.json"
+
+    # (a) tamper the stored mission_id so it no longer matches its directory
+    session = plane.mission.get_session(sid)
+    assert session is not None
+    tampered = dict(session)
+    tampered["mission_id"] = "M-20000101T000000-deadbeef"
+    session_file.write_text(json.dumps(tampered), encoding="utf-8")
+    before_bytes = session_file.read_bytes()
+    assert plane.mission.get_session(sid) is None  # mismatched mission_id rejected
+    assert session_file.read_bytes() == before_bytes  # read path did not mutate the record
+
+    # (b) tamper the stored session_id so it no longer matches the requested id
+    tampered2 = dict(session)
+    tampered2["session_id"] = "S-20000101T000000-deadbeef"
+    session_file.write_text(json.dumps(tampered2), encoding="utf-8")
+    assert plane.mission.get_session(sid) is None  # mismatched session_id rejected
+
+
+def test_concurrent_open_mission_only_one_active(plane: ControlPlane, project: Path) -> None:
+    import threading
+
+    c = _valid_contract(project)
+    results: list[dict] = []
+    barrier = threading.Barrier(2)
+
+    def worker() -> None:
+        barrier.wait()
+        results.append(
+            plane.open_mission(
+                objective=c["objective"],
+                artifact=c["artifact"],
+                done_criteria=c["done_criteria"],
+                non_goals=c["non_goals"],
+                constraints=c["constraints"],
+                owner=c["owner"],
+            )
+        )
+
+    t1 = threading.Thread(target=worker)
+    t2 = threading.Thread(target=worker)
+    t1.start()
+    t2.start()
+    t1.join()
+    t2.join()
+
+    active_count = sum(1 for r in results if r.get("status") == "active")
+    denied_count = sum(1 for r in results if r.get("error") == "active_mission_exists")
+    assert active_count == 1
+    assert denied_count == 1
+

hai-mcp-pr7/tests/test_stdio_boundary_coercion.py

@@ -0,0 +1,357 @@
+"""Stdio integration tests: JSON boundary coercion must not bypass gates or limits."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from pathlib import Path
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+REPO = Path(__file__).resolve().parents[1]
+
+
+async def _call(session: ClientSession, name: str, arguments: dict) -> dict:
+    result = await session.call_tool(name, arguments)
+    assert result.content
+    return json.loads(result.content[0].text)
+
+
+async def _with_stdio(tmp_path: Path):
+    os.environ["HAI_HOME"] = str(tmp_path / "stdio-home")
+    project = tmp_path / "proj"
+    (project / "src").mkdir(parents=True)
+    (project / "tests").mkdir(parents=True)
+
+    params = StdioServerParameters(
+        command="uv",
+        args=["run", "--directory", str(REPO), "hai-mcp"],
+        env={**os.environ},
+    )
+    return project, params
+
+
+async def _open_mission(session: ClientSession, project: Path) -> dict:
+    return await _call(
+        session,
+        "hai_open_mission",
+        {
+            "objective": "Boundary coercion probe mission",
+            "artifact": "tests/test_stdio_boundary_coercion.py green",
+            "done_criteria": [{"id": "dc-1", "description": "stdio coercion tests pass"}],
+            "owner": "samuel",
+            "constraints": {
+                "project_path": str(project),
+                "allowed_paths": ["src/", "tests/"],
+                "capabilities": ["read", "write", "test"],
+                "max_parallel_sessions": 1,
+            },
+        },
+    )
+
+
+async def _authorize(
+    session: ClientSession,
+    opened: dict,
+    *,
+    contract_version: object,
+    duration_minutes: object,
+) -> dict:
+    return await _call(
+        session,
+        "hai_authorize_session",
+        {
+            "mission_id": opened["mission_id"],
+            "contract_version": contract_version,
+            "agent_identity": "composer",
+            "role": "builder",
+            "contribution": "boundary tests",
+            "expected_result": "green",
+            "duration_minutes": duration_minutes,
+            "criterion_ids": ["dc-1"],
+        },
+    )
+
+
+def test_stdio_break_glass_marker_integer_fails_closed(tmp_path: Path) -> None:
+    """JSON break_glass_marker: 1 must not satisfy break-glass friction."""
+
+    async def _run() -> None:
+        project, params = await _with_stdio(tmp_path)
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                opened = await _open_mission(session, project)
+                assert opened["ok"] is True
+
+                denied = await _call(
+                    session,
+                    "hai_recontract",
+                    {
+                        "mission_id": opened["mission_id"],
+                        "contract_version": opened["contract_version"],
+                        "reason": "emergency",
+                        "changes": {"objective": "changed emergency"},
+                        "owner_ack": True,
+                        "mode": "break_glass",
+                        "break_glass_marker": 1,
+                    },
+                )
+                assert denied["ok"] is False
+                assert denied["error"] == "owner_gate_required"
+
+                still_ok = await _authorize(
+                    session,
+                    opened,
+                    contract_version=opened["contract_version"],
+                    duration_minutes=30,
+                )
+                assert still_ok["ok"] is True
+
+    asyncio.run(_run())
+
+
+def test_stdio_declares_blocker_integer_not_literal_true(tmp_path: Path) -> None:
+    """JSON declares_blocker: 1 must not classify as blocker without literal true."""
+
+    async def _run() -> None:
+        project, params = await _with_stdio(tmp_path)
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                opened = await _open_mission(session, project)
+                auth = await _authorize(
+                    session,
+                    opened,
+                    contract_version=opened["contract_version"],
+                    duration_minutes=30,
+                )
+                assert auth["ok"] is True
+
+                with_int = await _call(
+                    session,
+                    "hai_check_activity",
+                    {
+                        "session_id": auth["session_id"],
+                        "activity_step": "blocked on external dependency",
+                        "criterion_id": "dc-1",
+                        "declares_blocker": 1,
+                    },
+                )
+                assert with_int.get("classification") != "blocker"
+
+                with_true = await _call(
+                    session,
+                    "hai_check_activity",
+                    {
+                        "session_id": auth["session_id"],
+                        "activity_step": "blocked on external dependency",
+                        "criterion_id": "dc-1",
+                        "declares_blocker": True,
+                    },
+                )
+                assert with_true["classification"] == "blocker"
+
+    asyncio.run(_run())
+
+
+def test_stdio_contract_version_string_rejected(tmp_path: Path) -> None:
+    """JSON contract_version: \"1\" must not authorize when literal int is required."""
+
+    async def _run() -> None:
+        project, params = await _with_stdio(tmp_path)
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                opened = await _open_mission(session, project)
+                denied = await _authorize(
+                    session,
+                    opened,
+                    contract_version="1",
+                    duration_minutes=30,
+                )
+                assert denied["ok"] is False
+                assert denied["error"] == "invalid_args"
+
+                ok = await _authorize(
+                    session,
+                    opened,
+                    contract_version=opened["contract_version"],
+                    duration_minutes=30,
+                )
+                assert ok["ok"] is True
+
+    asyncio.run(_run())
+
+
+def test_stdio_contract_version_bool_rejected(tmp_path: Path) -> None:
+    """JSON contract_version: true must not coerce to version 1."""
+
+    async def _run() -> None:
+        project, params = await _with_stdio(tmp_path)
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                opened = await _open_mission(session, project)
+                denied = await _authorize(
+                    session,
+                    opened,
+                    contract_version=True,
+                    duration_minutes=30,
+                )
+                assert denied["ok"] is False
+                assert denied["error"] == "invalid_args"
+
+    asyncio.run(_run())
+
+
+def test_stdio_duration_minutes_string_rejected(tmp_path: Path) -> None:
+    """JSON duration_minutes: \"30\" must not authorize."""
+
+    async def _run() -> None:
+        project, params = await _with_stdio(tmp_path)
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                opened = await _open_mission(session, project)
+                denied = await _authorize(
+                    session,
+                    opened,
+                    contract_version=opened["contract_version"],
+                    duration_minutes="30",
+                )
+                assert denied["ok"] is False
+                assert denied["error"] == "invalid_args"
+
+    asyncio.run(_run())
+
+
+def test_stdio_duration_minutes_float_rejected(tmp_path: Path) -> None:
+    """JSON duration_minutes: 30.9 must not silently truncate."""
+
+    async def _run() -> None:
+        project, params = await _with_stdio(tmp_path)
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                opened = await _open_mission(session, project)
+                denied = await _authorize(
+                    session,
+                    opened,
+                    contract_version=opened["contract_version"],
+                    duration_minutes=30.9,
+                )
+                assert denied["ok"] is False
+                assert denied["error"] == "invalid_args"
+
+    asyncio.run(_run())
+
+
+def test_stdio_time_limit_hours_string_rejected(tmp_path: Path) -> None:
+    """JSON time_limit_hours: \"8\" must not be stored as a numeric limit."""
+
+    async def _run() -> None:
+        project, params = await _with_stdio(tmp_path)
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                denied = await _call(
+                    session,
+                    "hai_mission_start",
+                    {
+                        "problem": "Probe time limit coercion",
+                        "artifact": "probe artifact",
+                        "done_criteria": [{"id": "dc-1", "description": "x"}],
+                        "owner": "samuel",
+                        "time_limit_hours": "8",
+                    },
+                )
+                assert denied["ok"] is False
+                assert denied["error"] == "invalid_args"
+
+    asyncio.run(_run())
+
+
+def test_stdio_max_parallel_sessions_string_rejected(tmp_path: Path) -> None:
+    """JSON max_parallel_sessions: \"999\" via recontract must not widen parallel limit."""
+
+    async def _run() -> None:
+        project, params = await _with_stdio(tmp_path)
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                opened = await _open_mission(session, project)
+                new_constraints = dict(opened["contract"]["constraints"])
+                new_constraints["max_parallel_sessions"] = "999"
+                denied = await _call(
+                    session,
+                    "hai_recontract",
+                    {
+                        "mission_id": opened["mission_id"],
+                        "contract_version": opened["contract_version"],
+                        "reason": "widen parallel",
+                        "changes": {"constraints": new_constraints},
+                        "owner_ack": True,
+                    },
+                )
+                assert denied["ok"] is False
+                assert denied["error"] == "invalid_args"
+
+    asyncio.run(_run())
+
+
+def test_stdio_recontract_owner_ack_integer_fails_closed(tmp_path: Path) -> None:
+    """JSON owner_ack: 1 on hai_recontract must not apply contract changes."""
+
+    async def _run() -> None:
+        project, params = await _with_stdio(tmp_path)
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                opened = await _open_mission(session, project)
+                new_constraints = dict(opened["contract"]["constraints"])
+                new_constraints["allowed_paths"] = ["src/", "tests/", "docs/"]
+                denied = await _call(
+                    session,
+                    "hai_recontract",
+                    {
+                        "mission_id": opened["mission_id"],
+                        "contract_version": opened["contract_version"],
+                        "reason": "expand paths",
+                        "changes": {"constraints": new_constraints},
+                        "owner_ack": 1,
+                    },
+                )
+                assert denied["ok"] is False
+                assert denied["error"] == "owner_gate_required"
+
+    asyncio.run(_run())
+
+
+def test_stdio_close_mission_owner_ack_integer_fails_closed(tmp_path: Path) -> None:
+    """JSON owner_ack: 1 on hai_close_mission abandon must not close mission."""
+
+    async def _run() -> None:
+        project, params = await _with_stdio(tmp_path)
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                opened = await _open_mission(session, project)
+                denied = await _call(
+                    session,
+                    "hai_close_mission",
+                    {
+                        "mission_id": opened["mission_id"],
+                        "contract_version": opened["contract_version"],
+                        "closure": "abandoned",
+                        "outcome_summary": "coercion probe",
+                        "owner_ack": 1,
+                    },
+                )
+                assert denied["ok"] is False
+                assert denied["error"] == "owner_gate_required"
+
+    asyncio.run(_run())
+

hai-mcp-pr7/tests/test_stdio_owner_gate.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from pathlib import Path
+
+import pytest
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+REPO = Path(__file__).resolve().parents[1]
+
+
+async def _call(session: ClientSession, name: str, arguments: dict) -> dict:
+    result = await session.call_tool(name, arguments)
+    assert result.content
+    return json.loads(result.content[0].text)
+
+
+def test_stdio_owner_ack_integer_fails_closed(tmp_path: Path) -> None:
+    """FastMCP bool params coerce JSON 1 -> True; Any preserves int for fail-closed gates."""
+
+    async def _run() -> None:
+        os.environ["HAI_HOME"] = str(tmp_path / "stdio-home")
+        project = tmp_path / "proj"
+        (project / "Projek-Managment").mkdir(parents=True)
+
+        params = StdioServerParameters(
+            command="uv",
+            args=["run", "--directory", str(REPO), "hai-mcp"],
+            env={**os.environ},
+        )
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                await _call(
+                    session,
+                    "hai_propose_next_step",
+                    {"project_path": str(project), "content": "# gated\n"},
+                )
+                denied = await _call(
+                    session,
+                    "hai_accept_next_step",
+                    {"project_path": str(project), "owner_ack": 1, "reason": "truthy int"},
+                )
+                assert denied["ok"] is False
+                assert denied["error"] == "owner_gate_required"
+                assert not (project / "Projek-Managment" / "NEXT_STEP.md").is_file()
+
+                ok = await _call(
+                    session,
+                    "hai_accept_next_step",
+                    {"project_path": str(project), "owner_ack": True, "reason": "literal true"},
+                )
+                assert ok["ok"] is True
+
+    asyncio.run(_run())

hai-mcp-pr7/tests/test_stdio_smoke.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+ARTIFACT = REPO / "evals" / "stdio_smoke" / "latest.json"
+
+
+def test_stdio_smoke_script_writes_artifact(tmp_path: Path) -> None:
+    """Slice-3: run the stdio smoke script against an isolated HAI_HOME."""
+    hai_home = tmp_path / "hai-home"
+    hai_home.mkdir()
+    uv = shutil.which("uv")
+    assert uv, "uv is required to run hai-mcp smoke"
+    proc = subprocess.run(
+        [
+            uv,
+            "run",
+            "--directory",
+            str(REPO),
+            "python",
+            str(REPO / "scripts" / "stdio_smoke.py"),
+            "--hai-home",
+            str(hai_home),
+        ],
+        cwd=str(REPO),
+        capture_output=True,
+        text=True,
+        check=False,
+        env={**os.environ},
+    )
+    assert proc.returncode == 0, proc.stdout + "\n" + proc.stderr
+    assert ARTIFACT.is_file()
+    payload = json.loads(ARTIFACT.read_text(encoding="utf-8"))
+    assert payload["ok"] is True, payload
+    assert payload["env_boundary"]["touches_live_dot_hai"] is False
+    assert payload["env_boundary"]["HAI_HOME"] == str(hai_home)
+    tools_step = next(s for s in payload["steps"] if s["step"] == "list_tools")
+    assert tools_step["tool_count"] == 24
+    assert tools_step["missing"] == []

ponytail/.agents/plugins/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "ponytail",
+  "interface": {
+    "displayName": "Ponytail"
+  },
+  "plugins": [
+    {
+      "name": "ponytail",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/DietrichGebert/ponytail.git",
+        "ref": "main"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

ponytail/.agents/rules/ponytail.md

@@ -0,0 +1,30 @@
+# Ponytail, lazy senior dev mode
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+Before writing any code, stop at the first rung that holds:
+
+1. Does this need to be built at all? (YAGNI)
+2. Does it already exist in this codebase? Reuse the helper, util, or pattern that's already here, don't re-write it.
+3. Does the standard library already do this? Use it.
+4. Does a native platform feature cover it? Use it.
+5. Does an already-installed dependency solve it? Use it.
+6. Can this be one line? Make it one line.
+7. Only then: write the minimum code that works.
+
+The ladder runs after you understand the problem, not instead of it: read the task and the code it touches, trace the real flow end to end, then climb.
+
+Bug fix = root cause, not symptom: a report names a symptom. Grep every caller of the function you touch and fix the shared function once — one guard there is a smaller diff than one per caller, and patching only the path the ticket names leaves a sibling caller still broken.
+
+Rules:
+
+- No abstractions that weren't explicitly requested.
+- No new dependency if it can be avoided.
+- No boilerplate nobody asked for.
+- Deletion over addition. Boring over clever. Fewest files possible.
+- Shortest working diff wins, but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+- Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm.
+- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path.
+
+Not lazy about: understanding the problem (read it fully and trace the real flow before picking a rung, a small diff you don't understand is just laziness dressed up as efficiency), input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.

ponytail/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "ponytail",
+  "description": "Lazy senior dev mode for AI agents. The best code is the code you never wrote.",
+  "owner": {
+    "name": "Dietrich Gebert",
+    "url": "https://github.com/DietrichGebert"
+  },
+  "plugins": [
+    {
+      "name": "ponytail",
+      "description": "Forces the laziest solution that works. YAGNI, stdlib first, one line over fifty.",
+      "source": "./",
+      "category": "productivity"
+    }
+  ]
+}

ponytail/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "ponytail",
+  "version": "4.9.0",
+  "description": "Lazy senior dev mode. Forces the simplest, shortest solution that actually works: YAGNI, stdlib first, no unrequested abstractions.",
+  "author": {
+    "name": "Dietrich Gebert",
+    "url": "https://github.com/DietrichGebert"
+  },
+  "hooks": "./hooks/claude-codex-hooks.json"
+}

ponytail/.clinerules/ponytail.md

@@ -0,0 +1,30 @@
+# Ponytail, lazy senior dev mode
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+Before writing any code, stop at the first rung that holds:
+
+1. Does this need to be built at all? (YAGNI)
+2. Does it already exist in this codebase? Reuse the helper, util, or pattern that's already here, don't re-write it.
+3. Does the standard library already do this? Use it.
+4. Does a native platform feature cover it? Use it.
+5. Does an already-installed dependency solve it? Use it.
+6. Can this be one line? Make it one line.
+7. Only then: write the minimum code that works.
+
+The ladder runs after you understand the problem, not instead of it: read the task and the code it touches, trace the real flow end to end, then climb.
+
+Bug fix = root cause, not symptom: a report names a symptom. Grep every caller of the function you touch and fix the shared function once — one guard there is a smaller diff than one per caller, and patching only the path the ticket names leaves a sibling caller still broken.
+
+Rules:
+
+- No abstractions that weren't explicitly requested.
+- No new dependency if it can be avoided.
+- No boilerplate nobody asked for.
+- Deletion over addition. Boring over clever. Fewest files possible.
+- Shortest working diff wins, but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+- Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm.
+- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path.
+
+Not lazy about: understanding the problem (read it fully and trace the real flow before picking a rung, a small diff you don't understand is just laziness dressed up as efficiency), input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.

ponytail/.codex-plugin/plugin.json

@@ -0,0 +1,32 @@
+{
+  "name": "ponytail",
+  "version": "4.9.0",
+  "description": "Lazy senior dev mode. Forces the simplest, shortest solution that actually works: YAGNI, stdlib first, no unrequested abstractions.",
+  "author": {
+    "name": "Dietrich Gebert",
+    "url": "https://github.com/DietrichGebert"
+  },
+  "homepage": "https://github.com/DietrichGebert/ponytail",
+  "repository": "https://github.com/DietrichGebert/ponytail",
+  "license": "MIT",
+  "keywords": ["yagni", "minimalism", "code-review", "productivity"],
+  "skills": "./skills/",
+  "hooks": "./hooks/claude-codex-hooks.json",
+  "interface": {
+    "displayName": "Ponytail",
+    "shortDescription": "Lazy senior developer mode",
+    "longDescription": "Prefer YAGNI, the standard library, native platform features, and the smallest correct implementation.",
+    "developerName": "Dietrich Gebert",
+    "category": "Productivity",
+    "capabilities": ["Instructions", "Lifecycle hooks"],
+    "websiteURL": "https://github.com/DietrichGebert/ponytail",
+    "defaultPrompt": [
+      "Use Ponytail mode for this task.",
+      "Review this diff for over-engineering.",
+      "Find the smallest correct implementation."
+    ],
+    "brandColor": "#111111",
+    "composerIcon": "./assets/logo.png",
+    "logo": "./assets/logo.png"
+  }
+}

ponytail/.codex/config.toml

@@ -0,0 +1,31 @@
+# Coding MCPs: project-local registration (2026-09-07).
+
+[mcp_servers.serena]
+command = "/home/smlflg/.local/share/coding-mcp/serena/.venv/bin/serena"
+args = ["start-mcp-server", "--context=codex", "--project", "/home/smlflg/Projekte/CodingAgent/ponytail", "--enable-web-dashboard", "false", "--open-web-dashboard", "false", "--enable-gui-log-window", "false"]
+cwd = "/home/smlflg/Projekte/CodingAgent/ponytail"
+enabled = true
+startup_timeout_sec = 120
+tool_timeout_sec = 180
+
+[mcp_servers.serena.env]
+"SERENA_HOME" = "/home/smlflg/.local/share/coding-mcp/serena/state"
+
+[mcp_servers.gitnexus]
+command = "/home/smlflg/.nvm/versions/node/v24.13.0/bin/node"
+args = ["/home/smlflg/.local/share/coding-mcp/gitnexus/node_modules/gitnexus/dist/cli/index.js", "mcp"]
+cwd = "/home/smlflg/Projekte/CodingAgent/ponytail"
+enabled = true
+startup_timeout_sec = 120
+tool_timeout_sec = 180
+
+[mcp_servers.gitnexus.env]
+"GITNEXUS_HOME" = "/home/smlflg/.local/share/coding-mcp/gitnexus/runtime"
+
+[mcp_servers.context7]
+command = "/home/smlflg/.nvm/versions/node/v24.13.0/bin/node"
+args = ["/home/smlflg/.local/share/coding-mcp/context7/node_modules/@upstash/context7-mcp/dist/index.js"]
+cwd = "/home/smlflg/Projekte/CodingAgent/ponytail"
+enabled = true
+startup_timeout_sec = 120
+tool_timeout_sec = 180

ponytail/.cursor/rules/ponytail.mdc

@@ -0,0 +1,36 @@
+---
+description: Ponytail, lazy senior dev mode. Always pick the simplest solution that works.
+globs:
+alwaysApply: true
+---
+
+# Ponytail, lazy senior dev mode
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+Before writing any code, stop at the first rung that holds:
+
+1. Does this need to be built at all? (YAGNI)
+2. Does it already exist in this codebase? Reuse the helper, util, or pattern that's already here, don't re-write it.
+3. Does the standard library already do this? Use it.
+4. Does a native platform feature cover it? Use it.
+5. Does an already-installed dependency solve it? Use it.
+6. Can this be one line? Make it one line.
+7. Only then: write the minimum code that works.
+
+The ladder runs after you understand the problem, not instead of it: read the task and the code it touches, trace the real flow end to end, then climb.
+
+Bug fix = root cause, not symptom: a report names a symptom. Grep every caller of the function you touch and fix the shared function once — one guard there is a smaller diff than one per caller, and patching only the path the ticket names leaves a sibling caller still broken.
+
+Rules:
+
+- No abstractions that weren't explicitly requested.
+- No new dependency if it can be avoided.
+- No boilerplate nobody asked for.
+- Deletion over addition. Boring over clever. Fewest files possible.
+- Shortest working diff wins, but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+- Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm.
+- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path.
+
+Not lazy about: understanding the problem (read it fully and trace the real flow before picking a rung, a small diff you don't understand is just laziness dressed up as efficiency), input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.

ponytail/.devin-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "ponytail",
+  "version": "4.9.0",
+  "description": "Lazy senior dev mode. Forces the simplest, shortest solution that actually works: YAGNI, stdlib first, no unrequested abstractions.",
+  "author": {
+    "name": "Dietrich Gebert",
+    "url": "https://github.com/DietrichGebert"
+  },
+  "homepage": "https://github.com/DietrichGebert/ponytail",
+  "repository": "https://github.com/DietrichGebert/ponytail",
+  "license": "MIT",
+  "keywords": ["yagni", "minimalism", "code-review", "productivity"]
+}

ponytail/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [DietrichGebert]

ponytail/.github/copilot-instructions.md

@@ -0,0 +1,30 @@
+# Ponytail, lazy senior dev mode
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+Before writing any code, stop at the first rung that holds:
+
+1. Does this need to be built at all? (YAGNI)
+2. Does it already exist in this codebase? Reuse the helper, util, or pattern that's already here, don't re-write it.
+3. Does the standard library already do this? Use it.
+4. Does a native platform feature cover it? Use it.
+5. Does an already-installed dependency solve it? Use it.
+6. Can this be one line? Make it one line.
+7. Only then: write the minimum code that works.
+
+The ladder runs after you understand the problem, not instead of it: read the task and the code it touches, trace the real flow end to end, then climb.
+
+Bug fix = root cause, not symptom: a report names a symptom. Grep every caller of the function you touch and fix the shared function once — one guard there is a smaller diff than one per caller, and patching only the path the ticket names leaves a sibling caller still broken.
+
+Rules:
+
+- No abstractions that weren't explicitly requested.
+- No new dependency if it can be avoided.
+- No boilerplate nobody asked for.
+- Deletion over addition. Boring over clever. Fewest files possible.
+- Shortest working diff wins, but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+- Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm.
+- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path.
+
+Not lazy about: understanding the problem (read it fully and trace the real flow before picking a rung, a small diff you don't understand is just laziness dressed up as efficiency), input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.

ponytail/.github/plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "ponytail",
+  "description": "Lazy senior dev mode for AI agents. The best code is the code you never wrote.",
+  "owner": {
+    "name": "Dietrich Gebert",
+    "url": "https://github.com/DietrichGebert"
+  },
+  "plugins": [
+    {
+      "name": "ponytail",
+      "description": "Forces the laziest solution that works. YAGNI, stdlib first, one line over fifty.",
+      "source": "./",
+      "category": "productivity",
+      "tags": ["yagni", "minimalism", "code-review", "productivity"],
+      "commands": "commands/",
+      "skills": "skills/",
+      "hooks": "hooks/copilot-hooks.json"
+    }
+  ]
+}

ponytail/.github/plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "ponytail",
+  "description": "Lazy senior dev mode. Forces the simplest, shortest solution that actually works: YAGNI, stdlib first, no unrequested abstractions.",
+  "version": "4.9.0",
+  "author": {
+    "name": "Dietrich Gebert",
+    "url": "https://github.com/DietrichGebert"
+  },
+  "homepage": "https://github.com/DietrichGebert/ponytail",
+  "repository": "https://github.com/DietrichGebert/ponytail",
+  "license": "MIT",
+  "keywords": ["yagni", "minimalism", "code-review", "productivity"],
+  "commands": "commands/",
+  "skills": "skills/",
+  "hooks": "hooks/copilot-hooks.json"
+}

ponytail/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: publish
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      # Trusted publishing (OIDC) needs npm >= 11.5.1; Node 22 ships npm 10.
+      - run: npm install -g npm@latest
+      # No token: id-token: write above lets npm authenticate via OIDC, and
+      # provenance is attached automatically. access set in publishConfig.
+      - run: npm publish

ponytail/.github/workflows/test.yml

@@ -0,0 +1,36 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Python deps for correctness checks
+        run: pip install pandas
+
+      - name: Install MCP deps
+        run: npm install --prefix ponytail-mcp
+
+      - name: Check rule copies
+        run: node scripts/check-rule-copies.js
+
+      - name: Check version consistency
+        run: node scripts/check-versions.js
+
+      - name: Run tests
+        run: npm test

ponytail/.gitignore

@@ -0,0 +1,26 @@
+# Secrets, never commit API keys
+.env
+.env.*
+!.env.example
+
+# Dependencies
+node_modules/
+
+# promptfoo eval artifacts
+.promptfoo/
+benchmarks/output*
+benchmarks/benchmark-local-results.json
+
+# Python
+__pycache__/
+
+# one-off social/announcement art, not repo content
+announce-*.png
+changelog-*.png
+ponytail-*.gif
+
+# Claude Code local settings (machine-specific permission grants)
+.claude/settings.local.json
+
+# agentic benchmark workspaces (agent output, kept locally for inspection)
+benchmarks/agentic/runs/

ponytail/.grok-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "ponytail",
+  "description": "Lazy senior dev mode for AI agents. The best code is the code you never wrote.",
+  "owner": {
+    "name": "Dietrich Gebert",
+    "url": "https://github.com/DietrichGebert"
+  },
+  "plugins": [
+    {
+      "name": "ponytail",
+      "description": "Forces the laziest solution that works. YAGNI, stdlib first, one line over fifty.",
+      "source": "./",
+      "category": "productivity"
+    }
+  ]
+}

ponytail/.kiro/steering/ponytail.md

@@ -0,0 +1,35 @@
+---
+title: Ponytail, lazy senior dev mode
+inclusion: always
+---
+
+# Ponytail, lazy senior dev mode
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+Before writing any code, stop at the first rung that holds:
+
+1. Does this need to be built at all? (YAGNI)
+2. Does it already exist in this codebase? Reuse the helper, util, or pattern that's already here, don't re-write it.
+3. Does the standard library already do this? Use it.
+4. Does a native platform feature cover it? Use it.
+5. Does an already-installed dependency solve it? Use it.
+6. Can this be one line? Make it one line.
+7. Only then: write the minimum code that works.
+
+The ladder runs after you understand the problem, not instead of it: read the task and the code it touches, trace the real flow end to end, then climb.
+
+Bug fix = root cause, not symptom: a report names a symptom. Grep every caller of the function you touch and fix the shared function once — one guard there is a smaller diff than one per caller, and patching only the path the ticket names leaves a sibling caller still broken.
+
+Rules:
+
+- No abstractions that weren't explicitly requested.
+- No new dependency if it can be avoided.
+- No boilerplate nobody asked for.
+- Deletion over addition. Boring over clever. Fewest files possible.
+- Shortest working diff wins, but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+- Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm.
+- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path.
+
+Not lazy about: understanding the problem (read it fully and trace the real flow before picking a rung, a small diff you don't understand is just laziness dressed up as efficiency), input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.

ponytail/.openclaw/skills/ponytail-audit/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: ponytail-audit
+description: "Audit the whole repo for over-engineering. A ranked list of what to delete, simplify, or replace with stdlib or native features."
+homepage: https://github.com/DietrichGebert/ponytail
+license: MIT
+---
+
+ponytail-review, repo-wide. Scan the whole tree instead of a diff. Rank
+findings biggest cut first.
+
+## Tags
+
+Same as ponytail-review:
+
+- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
+- `stdlib:` hand-rolled thing the standard library ships. Name the function.
+- `native:` dependency or code doing what the platform already does. Name the feature.
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+
+## Hunt
+
+Deps the stdlib or platform already ships, single-implementation interfaces,
+factories with one product, wrappers that only delegate, files exporting one
+thing, dead flags and config, hand-rolled stdlib.
+
+## Output
+
+One line per finding, ranked: `<tag> <what to cut>. <replacement>. [path]`.
+End with `net: -<N> lines, -<M> deps possible.` Nothing to cut: `Lean already. Ship.`
+
+## Boundaries
+
+Scope: over-engineering and complexity only. Correctness bugs, security holes,
+and performance are explicitly out of scope. Route them to a normal review
+pass. Lists findings, applies nothing. One-shot.
+"stop ponytail-audit" or "normal mode" to revert.

ponytail/.openclaw/skills/ponytail-debt/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ponytail-debt
+description: "Harvest every ponytail: shortcut comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report."
+homepage: https://github.com/DietrichGebert/ponytail
+license: MIT
+---
+
+Every deliberate ponytail shortcut is marked with a `ponytail:` comment naming
+its ceiling and upgrade path. This collects them into one ledger so a deferral
+can't quietly become permanent.
+
+## Scan
+
+Grep the repo for comment markers, skipping `node_modules`, `.git`, and build
+output:
+
+`grep -rnE '(#|//) ?ponytail:' .`  (add other comment prefixes if your stack uses them)
+
+Each hit is one ledger row. The comment prefix keeps prose that merely mentions
+the convention out of the ledger.
+
+## Output
+
+One row per marker, grouped by file:
+
+`<file>:<line>, <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.`
+
+The convention is `ponytail: <ceiling>, <upgrade path>`, so pull the ceiling
+and the trigger straight from the comment. Want an owner per row too? add
+`git blame -L<line>,<line>`.
+
+Flag the rot risk: any `ponytail:` comment that names no upgrade path or
+trigger gets a `no-trigger` tag, those are the ones that silently rot.
+
+End with `<N> markers, <M> with no trigger.` Nothing found: `No ponytail: debt. Clean ledger.`
+
+## Boundaries
+
+Reads and reports only, changes nothing. To persist it, ask and it writes the
+ledger to a file (e.g. `PONYTAIL-DEBT.md`). One-shot. "stop ponytail-debt" or
+"normal mode" to revert.

ponytail/.openclaw/skills/ponytail-gain/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: ponytail-gain
+description: "Show ponytail measured impact as a scoreboard: less code, less cost, more speed, from the benchmark medians. One-shot display."
+homepage: https://github.com/DietrichGebert/ponytail
+license: MIT
+---
+
+# Ponytail Gain
+
+Display this scoreboard when invoked. One-shot: do NOT change mode, write flag
+files, or persist anything.
+
+The figures are the published benchmark medians (5 everyday tasks: email
+validator, debounce, CSV sum, countdown timer, rate limiter; three models:
+Haiku, Sonnet, Opus). They are measured, not computed from the current repo.
+Source: `benchmarks/` and the README.
+
+## Scoreboard
+
+Render plain ASCII bars. The bar length shows the measured range; the label
+carries the exact figure:
+
+```
+  ponytail gain                     benchmark median · 5 tasks · 3 models
+
+  Lines of code   no-skill  ████████████████████  100%
+                  ponytail  ██▌·················    6–20%   ▼ 80–94%
+  Cost            no-skill  ████████████████████  100%
+                  ponytail  █████▌··············   23–53%  ▼ 47–77%
+  Speed           ponytail  ▸ 3–6× faster
+
+  This repo:  /ponytail-debt  (shortcuts you deferred)
+              /ponytail-audit (what's still cuttable)
+```
+
+## Honesty boundary
+
+These are benchmark medians, not this repo. NEVER print a per-repo savings
+number ("you saved X lines/tokens here"): the unbuilt version was never
+written, so there is no real baseline to subtract from in a live repo. The
+only real per-repo figures come from `/ponytail-debt` (a counted ledger), and
+this card points there instead of inventing one.
+
+## Boundaries
+
+One-shot display. Edits nothing, changes no mode.
+"stop ponytail" or "normal mode": revert.

ponytail/.openclaw/skills/ponytail-help/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: ponytail-help
+description: "Quick reference for ponytail's modes, skills, and commands. One-shot display."
+homepage: https://github.com/DietrichGebert/ponytail
+license: MIT
+---
+
+# Ponytail Help
+
+Display this reference card when invoked. One-shot, do NOT change mode,
+write flag files, or persist anything.
+
+## Levels
+
+| Level | Trigger | What change |
+|-------|---------|-------------|
+| **Lite** | `/ponytail lite` | Build what's asked, name the lazier alternative in one line. |
+| **Full** | `/ponytail` | The ladder enforced: YAGNI → stdlib → native → one line → minimum. Default. |
+| **Ultra** | `/ponytail ultra` | YAGNI extremist. Deletion before addition. Challenges requirements before building. |
+
+Level sticks until changed or session end.
+
+## Skills
+
+| Skill | Trigger | What it does |
+|-------|---------|--------------|
+| **ponytail** | `/ponytail` | Lazy mode itself. Simplest solution that works. |
+| **ponytail-review** | `/ponytail-review` | Over-engineering review: `L42: yagni: factory, one product. Inline.` |
+| **ponytail-audit** | `/ponytail-audit` | Whole-repo over-engineering audit: ranked list of what to delete. |
+| **ponytail-debt** | `/ponytail-debt` | Harvest `ponytail:` shortcut comments into a tracked ledger. |
+| **ponytail-gain** | `/ponytail-gain` | Measured-impact scoreboard: less code, less cost, more speed. |
+| **ponytail-help** | `/ponytail-help` | This card. |
+
+Codex uses `@ponytail`, `@ponytail-review`, and `@ponytail-help`; Claude Code
+and OpenCode use the slash-command forms above (OpenCode ships all six as
+slash commands).
+
+## Deactivate
+
+Say "stop ponytail" or "normal mode". Resume anytime with `/ponytail`.
+`/ponytail off` also works.
+
+## Configure Default Mode
+
+Default mode = `full`, auto-active every session. Change it:
+
+**Environment variable** (highest priority):
+```bash
+export PONYTAIL_DEFAULT_MODE=ultra
+```
+
+**Config file** (`~/.config/ponytail/config.json`, Windows: `%APPDATA%\ponytail\config.json`):
+```json
+{ "defaultMode": "lite" }
+```
+
+Set `"off"` to disable auto-activation on session start, activate manually
+with `/ponytail` when wanted.
+
+Resolution: env var > config file > `full`.
+
+## Update
+
+Enable auto-update once: open `/plugin`, go to Marketplaces, pick ponytail, Enable auto-update. Claude Code then pulls new versions at startup (run `/reload-plugins` when it prompts). Manual refresh: `/plugin marketplace update ponytail` then `/reload-plugins`.
+
+If `/plugin` is not recognized, your Claude Code is out of date. Update it (`npm install -g @anthropic-ai/claude-code@latest`, or `brew upgrade claude-code`) and restart. Other hosts use their own update flow.
+
+## More
+
+Full docs + examples: https://github.com/DietrichGebert/ponytail

ponytail/.openclaw/skills/ponytail-review/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ponytail-review
+description: "Review a diff for over-engineering. Finds what to delete: reinvented stdlib, needless deps, speculative abstractions. One line per finding."
+homepage: https://github.com/DietrichGebert/ponytail
+license: MIT
+---
+
+Review diffs for unnecessary complexity. One line per finding: location, what
+to cut, what replaces it. The diff's best outcome is getting shorter.
+
+## Format
+
+`L<line>: <tag> <what>. <replacement>.`, or `<file>:L<line>: ...` for
+multi-file diffs.
+
+Tags:
+
+- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
+- `stdlib:` hand-rolled thing the standard library ships. Name the function.
+- `native:` dependency or code doing what the platform already does. Name the feature.
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+
+## Examples
+
+❌ "This EmailValidator class might be more complex than necessary, have you
+considered whether all these validation rules are needed at this stage?"
+
+✅ `L12-38: stdlib: 27-line validator class. "@" in email, 1 line, real validation is the confirmation mail.`
+
+✅ `L4: native: moment.js imported for one format call. Intl.DateTimeFormat, 0 deps.`
+
+✅ `repo.py:L88: yagni: AbstractRepository with one implementation. Inline it until a second one exists.`
+
+✅ `L52-71: delete: retry wrapper around an idempotent local call. Nothing replaces it.`
+
+✅ `L30-44: shrink: manual loop builds dict. dict(zip(keys, values)), 1 line.`
+
+## Scoring
+
+End with the only metric that matters: `net: -<N> lines possible.`
+
+If there is nothing to cut, say `Lean already. Ship.` and stop.
+
+## Boundaries
+
+Scope: over-engineering and complexity only. Correctness bugs, security holes,
+and performance are explicitly out of scope. Route them to a normal review
+pass, not this one. A single smoke test or `assert`-based
+self-check is the ponytail minimum, not bloat, never flag it for deletion.
+Does not apply the fixes, only lists them.
+"stop ponytail-review" or "normal mode": revert to verbose review style.

ponytail/.openclaw/skills/ponytail/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: ponytail
+description: "Lazy senior dev mode for any coding task (write, refactor, fix, review): YAGNI, stdlib first, no unrequested abstractions. Not for non-coding requests."
+homepage: https://github.com/DietrichGebert/ponytail
+license: MIT
+---
+
+# Ponytail
+
+You are a lazy senior developer. Lazy means efficient, not careless. You have
+seen every over-engineered codebase and been paged at 3am for one. The best
+code is the code never written.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if
+unsure. Off only: "stop ponytail" / "normal mode". Default: **full**.
+Switch: `/ponytail lite|full|ultra`.
+
+## The ladder
+
+Stop at the first rung that holds:
+
+1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
+2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it. Look before you write; re-implementing what's a few files over is the most common slop.
+3. **Stdlib does it?** Use it.
+4. **Native platform feature covers it?** `<input type="date">` over a picker lib, CSS over JS, DB constraint over app code.
+5. **Already-installed dependency solves it?** Use it. Never add a new one for what a few lines can do.
+6. **Can it be one line?** One line.
+7. **Only then:** the minimum code that works.
+
+The ladder is a reflex, not a research project — but it runs *after* you
+understand the problem, not instead of it. Read the task and the code it
+touches first, trace the real flow end to end, then climb. Two rungs work →
+take the higher one and move on. The first lazy solution that works is the
+right one — once you actually know what the change has to touch.
+
+**Bug fix = root cause, not symptom.** A report names a symptom. Before you
+edit, grep every caller of the function you're about to touch. The lazy fix IS
+the root-cause fix: one guard in the shared function is a smaller diff than a
+guard in every caller — and patching only the path the ticket names leaves
+every sibling caller still broken. Fix it once, where all callers route through.
+
+## Rules
+
+- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
+- No boilerplate, no scaffolding "for later", later can scaffold for itself.
+- Deletion over addition. Boring over clever, clever is what someone decodes at 3am.
+- Fewest files possible. Shortest working diff wins — but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Complex request? Ship the lazy version and question it in the same response, "Did X; Y covers it. Need full X? Say so." Never stall on an answer you can default.
+- Two stdlib options, same size? Take the one that's correct on edge cases. Lazy means writing less code, not picking the flimsier algorithm.
+- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path (`# ponytail: global lock, per-account locks if throughput matters`).
+
+## Output
+
+Code first. Then at most three short lines: what was skipped, when to add it.
+No essays, no feature tours, no design notes. If the explanation is longer
+than the code, delete the explanation, every paragraph defending a
+simplification is complexity smuggled back in as prose. Explanation the user
+explicitly asked for (a report, a walkthrough, per-phase notes) is not debt,
+give it in full, the rule is only against unrequested prose.
+
+Pattern: `[code] → skipped: [X], add when [Y].`
+
+## Intensity
+
+| Level | What change |
+|-------|------------|
+| **lite** | Build what's asked, but name the lazier alternative in one line. User picks. |
+| **full** | The ladder enforced. Stdlib and native first. Shortest diff, shortest explanation. Default. |
+| **ultra** | YAGNI extremist. Deletion before addition. Ship the one-liner and challenge the rest of the requirement in the same breath. |
+
+Example: "Add a cache for these API responses."
+- lite: "Done, cache added. FYI: `functools.lru_cache` covers this in one line if you'd rather not own a cache class."
+- full: "`@lru_cache(maxsize=1000)` on the fetch function. Skipped custom cache class, add when lru_cache measurably falls short."
+- ultra: "No cache until a profiler says so. When it does: `@lru_cache`. A hand-rolled TTL cache class is a bug farm with a hit rate."
+
+## When NOT to be lazy
+
+Never simplify away: input validation at trust boundaries, error handling
+that prevents data loss, security measures, accessibility basics, anything
+explicitly requested. User insists on the full version → build it, no
+re-arguing.
+
+Never lazy about understanding the problem. The ladder shortens the
+solution, never the reading. Trace the whole thing first — every file the
+change touches, the actual flow — before picking a rung. Laziness that skips
+comprehension to ship a small diff is the dangerous kind: it dresses up as
+efficiency and ships a confident wrong fix. Read fully, then be lazy.
+
+Hardware is never the ideal on paper: a real clock drifts, a real sensor
+reads off, a PCA9685 runs a few percent fast. Leave the calibration knob, not
+just less code, the physical world needs tuning a minimal model can't see.
+
+Lazy code without its check is unfinished. Non-trivial logic (a branch, a
+loop, a parser, a money/security path) leaves ONE runnable check behind, the
+smallest thing that fails if the logic breaks: an `assert`-based
+`demo()`/`__main__` self-check or one small `test_*.py`. No frameworks, no
+fixtures, no per-function suites unless asked. Trivial one-liners need no
+test, YAGNI applies to tests too.
+
+## Boundaries
+
+Ponytail governs what you build, not how you talk (pair with Caveman for
+terse prose). "stop ponytail" / "normal mode": revert. Level persists until
+changed or session end.
+
+The shortest path to done is the right path.