Skip to content

dse120071750/m8m-harness-builder / skills/m8m/m8m-harness-builder

m8m-harness-builder

Flagged

Build and edit M8M harnesses that coordinate existing tools and FlowSteps, validate milestone outputs, and track progress and resume. Reuse working implementations in place. Compile workflow changes without runtime packaging; build portable packages when requested and deliver server installations through the dedicated M8M server installer.

FileKindSize
.gitattributesother112 B
.gitignoreother208 B
LICENSEother673 B
README.mdmarkdown29.8 KB
SKILL.mdskill md1.3 KB
agents/audit_complete.yamlconfig1.6 KB
agents/flow_generated.yamlconfig2.2 KB
agents/harness_validated.yamlconfig2.3 KB
agents/openai.yamlconfig4.6 KB
agents/skill_shipped.yamlconfig2.1 KB
agents/toolbox_ready.yamlconfig1.6 KB
conftest.pyscript275 B
contracts/conformance/expectation_first_runtime/candidate-cases.jsonconfig4.1 KB
contracts/conformance/expectation_first_runtime/common-linear.jsonconfig2.7 KB
contracts/conformance/expectation_first_runtime/schemas/judge-decision.schema.jsonconfig373 B
contracts/conformance/expectation_first_runtime/schemas/result.output.schema.jsonconfig589 B
contracts/conformance/expectation_first_runtime/schemas/source.output.schema.jsonconfig500 B
contracts/conformance/flowstep_flow_v4/invalid/judge-loop-unbound.jsonconfig483 B
contracts/conformance/flowstep_flow_v4/invalid/malformed-execution.jsonconfig571 B
contracts/conformance/flowstep_flow_v4/invalid/no-required-output.jsonconfig455 B
contracts/conformance/flowstep_flow_v4/invalid/nonjudge-bound.jsonconfig763 B
contracts/conformance/flowstep_flow_v4/invalid/unknown-field.jsonconfig469 B
contracts/conformance/flowstep_flow_v4/valid/authoring-union.jsonconfig4.3 KB
contracts/conformance/flowstep_flow_v4/valid/platform-dag.jsonconfig1.9 KB
contracts/file_ref_v2.schema.jsonconfig484 B
contracts/flow_sequence_action_v2.schema.jsonconfig1.5 KB
contracts/flowstep_flow_v4.schema.jsonconfig13.6 KB
contracts/flowstep_output_v2.schema.jsonconfig2.8 KB
contracts/flowstep_output_v3.schema.jsonconfig3.0 KB
contracts/flowstep_skill_audit_v1.schema.jsonconfig5.1 KB
contracts/m8m_builder_configuration_v1.schema.jsonconfig252 B
contracts/m8m_builder_input_v1.schema.jsonconfig183 B
contracts/m8m_builder_installation_receipt_v2.schema.jsonconfig2.9 KB
contracts/m8m_builder_output_v1.schema.jsonconfig453 B
contracts/m8m_builder_request_v3.schema.jsonconfig707 B
contracts/m8m_builder_result_v3.schema.jsonconfig422 B
contracts/m8m_builder_source_audit_v2.schema.jsonconfig6.1 KB
contracts/m8m_builder_source_bundle_v2.schema.jsonconfig8.6 KB
contracts/m8m_builder_toolbox_manifest_v2.schema.jsonconfig2.6 KB
contracts/m8m_builder_validation_report_v2.schema.jsonconfig3.4 KB
contracts/m8m_cache_receipt_v1.schema.jsonconfig1.2 KB
contracts/m8m_candidate_cache_entry_v1.schema.jsonconfig2.8 KB
contracts/m8m_chosen_output_v1.schema.jsonconfig2.3 KB
contracts/m8m_context_capsule_v1.schema.jsonconfig1.9 KB
contracts/m8m_contract_bundle_lock_v1.schema.jsonconfig648 B
contracts/m8m_goal_ledger_v1.schema.jsonconfig1.8 KB
contracts/m8m_milestone_agent_v1.schema.jsonconfig13.8 KB
contracts/m8m_milestone_expectation_v1.schema.jsonconfig1.9 KB
contracts/m8m_milestone_judge_receipt_v1.schema.jsonconfig1.7 KB
contracts/m8m_milestone_judge_request_v1.schema.jsonconfig3.0 KB
contracts/m8m_run_context_v1.schema.jsonconfig994 B
contracts/m8m_run_context_v2.schema.jsonconfig1.2 KB
contracts/m8m_run_storage_contract_v1.schema.jsonconfig894 B
contracts/m8m_runtime_lock_v1.schema.jsonconfig1.7 KB
contracts/m8m_runtime_release_v1.schema.jsonconfig2.2 KB
contracts/m8m_skill_canvas_v1.schema.jsonconfig4.0 KB
contracts/m8m_source_asset_manifest_v1.schema.jsonconfig1.2 KB
contracts/m8m_workflow_package_archive_v1.schema.jsonconfig1.1 KB
contracts/m8m_workflow_source_bundle_proof_v1.schema.jsonconfig1.6 KB
contracts/m8m_workflow_source_bundle_v1.schema.jsonconfig19.5 KB
contracts/tool_vs_intelligence_table_v1.schema.jsonconfig1.3 KB
docs/m8m-chart.jpgbinary172.2 KB
docs/m8m-task-builder-design.zh-HK.mdmarkdown66.9 KB
examples/article_infographic/README.mdmarkdown598 B
examples/article_infographic/planning/m8m-flowchart.jpgbinary186.0 KB
examples/article_infographic/planning/m8m-flowchart.mdmarkdown4.2 KB
flows/m8m_build_v2.yamlconfig9.9 KB
flowsteps/tools/audit_complete_judge/input.schema.jsonconfig190 B
flowsteps/tools/audit_complete_judge/output.schema.jsonconfig477 B
flowsteps/tools/audit_complete_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/audit_complete_judge/tool.pyscript1.2 KB
flowsteps/tools/audit_skill/input.schema.jsonconfig250 B
flowsteps/tools/audit_skill/output.schema.jsonconfig136 B
flowsteps/tools/audit_skill/tests/test_tool.pyscript1.9 KB
flowsteps/tools/audit_skill/tool.pyscript2.9 KB
flowsteps/tools/flow_generated_judge/input.schema.jsonconfig190 B
flowsteps/tools/flow_generated_judge/output.schema.jsonconfig475 B
flowsteps/tools/flow_generated_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/flow_generated_judge/tool.pyscript1.5 KB
flowsteps/tools/generate_from_audit/input.schema.jsonconfig562 B
flowsteps/tools/generate_from_audit/output.schema.jsonconfig137 B
flowsteps/tools/generate_from_audit/tests/test_tool.pyscript2.2 KB
flowsteps/tools/generate_from_audit/tool.pyscript3.0 KB
flowsteps/tools/harness_validated_judge/input.schema.jsonconfig193 B
flowsteps/tools/harness_validated_judge/output.schema.jsonconfig488 B
flowsteps/tools/harness_validated_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/harness_validated_judge/tool.pyscript1.3 KB
flowsteps/tools/install_local_skill/input.schema.jsonconfig733 B
flowsteps/tools/install_local_skill/output.schema.jsonconfig144 B
flowsteps/tools/install_local_skill/tests/test_tool.pyscript2.1 KB
flowsteps/tools/install_local_skill/tool.pyscript3.0 KB
flowsteps/tools/install_toolbox/input.schema.jsonconfig400 B
flowsteps/tools/install_toolbox/output.schema.jsonconfig140 B
flowsteps/tools/install_toolbox/tests/test_tool.pyscript1.9 KB
flowsteps/tools/install_toolbox/tool.pyscript3.0 KB
flowsteps/tools/skill_shipped_judge/input.schema.jsonconfig189 B
flowsteps/tools/skill_shipped_judge/output.schema.jsonconfig484 B
flowsteps/tools/skill_shipped_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/skill_shipped_judge/tool.pyscript1.3 KB
flowsteps/tools/toolbox_ready_judge/input.schema.jsonconfig189 B
flowsteps/tools/toolbox_ready_judge/output.schema.jsonconfig490 B
flowsteps/tools/toolbox_ready_judge/tests/test_tool.pyscript1.3 KB
flowsteps/tools/toolbox_ready_judge/tool.pyscript1.6 KB
flowsteps/tools/validate_harness/input.schema.jsonconfig563 B
flowsteps/tools/validate_harness/output.schema.jsonconfig141 B
flowsteps/tools/validate_harness/tests/test_tool.pyscript2.1 KB
flowsteps/tools/validate_harness/tool.pyscript3.0 KB
planning/upgrade.mdmarkdown16.2 KB
references/architecture.mdmarkdown28.1 KB
references/audit_complete.mdmarkdown739 B
references/builder-authoring.mdmarkdown9.8 KB
references/flow_generated.mdmarkdown1.2 KB
references/flowstep-development.mdmarkdown4.3 KB
references/harness-invocation.mdmarkdown2.9 KB
references/harness_validated.mdmarkdown786 B
references/master-prompts.mdmarkdown14.0 KB
references/milestone.mdmarkdown11.4 KB
references/output-lineage.mdmarkdown4.4 KB
references/runtime-packaging.mdmarkdown35.2 KB
references/server-delivery.mdmarkdown6.8 KB
references/skill_shipped.mdmarkdown798 B
references/tool-vs-intelligence.mdmarkdown10.0 KB
references/toolbox_ready.mdmarkdown612 B
requirements.txtmanifest150 B
scripts/audit_harness.pyscript80.7 KB
scripts/candidate_cache.pyscript27.6 KB
scripts/coordinate_workflow.pyscript4.3 KB
scripts/execution_identity.pyscript1.0 KB
scripts/flowchart_jpg.pyscript16.1 KB
scripts/flowstep_instruction.pyscript14.1 KB
scripts/flowstep_runtime.pyscript108.6 KB
scripts/flowstep_tools.pyscript5.7 KB
scripts/gem_text.pyscript5.7 KB
scripts/generate_harness.pyscript61.4 KB
scripts/humanize_chart.pyscript5.6 KB
scripts/humanize_chart_zh.pyscript5.2 KB
scripts/import_flow_v4.pyscript62.3 KB
scripts/m8m_build_steps.pyscript143.2 KB
scripts/m8m_cache.pyscript1.7 KB
scripts/m8m_delivery_common.pyscript3.8 KB
scripts/m8m_deploy.pyscript5.6 KB
scripts/m8m_factory.pyscript10.1 KB
scripts/m8m_flowchart.pyscript16.6 KB
scripts/m8m_local_bundle.pyscript4.5 KB
scripts/migrate_skill_source.pyscript34.2 KB
scripts/milestone_expectation.pyscript3.3 KB
scripts/milestone_pair.pyscript3.1 KB
scripts/package_archive.pyscript7.1 KB
scripts/project_imports.pyscript10.8 KB
scripts/run_flow.pyscript153.8 KB
scripts/run_goal.pyscript14.1 KB
scripts/run_m8m.pyscript3.8 KB
scripts/runtime_release.pyscript45.0 KB
scripts/schema_gate.pyscript5.6 KB
scripts/session_layout.pyscript74.4 KB
scripts/skill_source.pyscript65.3 KB
scripts/source_bundle.pyscript87.7 KB
scripts/teaching_contracts.pyscript8.9 KB
scripts/tool_vs_intelligence.pyscript9.3 KB
scripts/toolbox_plan.pyscript6.1 KB
scripts/validate_harness.pyscript24.1 KB
scripts/verify_platform_contract_parity.pyscript2.9 KB
seeds/branch_receipt/input.schema.jsonconfig1.0 KB
seeds/branch_receipt/output.schema.jsonconfig359 B
seeds/branch_receipt/tests/test_tool.pyscript2.0 KB
seeds/branch_receipt/tool.pyscript3.7 KB
seeds/cycle_receipt/input.schema.jsonconfig1.0 KB
seeds/cycle_receipt/output.schema.jsonconfig319 B
seeds/cycle_receipt/tests/test_tool.pyscript1.5 KB
seeds/cycle_receipt/tool.pyscript2.0 KB
seeds/hash_bind/input.schema.jsonconfig213 B
seeds/hash_bind/output.schema.jsonconfig288 B
seeds/hash_bind/tests/test_tool.pyscript814 B
seeds/hash_bind/tool.pyscript527 B
seeds/ledger_receipt/input.schema.jsonconfig278 B
seeds/ledger_receipt/output.schema.jsonconfig355 B
seeds/ledger_receipt/tests/test_tool.pyscript842 B
seeds/ledger_receipt/tool.pyscript747 B
seeds/ok_receipt/input.schema.jsonconfig280 B
seeds/ok_receipt/output.schema.jsonconfig280 B
seeds/ok_receipt/tests/test_tool.pyscript667 B
seeds/ok_receipt/tool.pyscript682 B
seeds/schema_validate/input.schema.jsonconfig265 B
seeds/schema_validate/output.schema.jsonconfig196 B
seeds/schema_validate/tests/test_tool.pyscript1.0 KB
seeds/schema_validate/tool.pyscript844 B
seeds/slot_write/input.schema.jsonconfig558 B
seeds/slot_write/output.schema.jsonconfig346 B
seeds/slot_write/tests/test_tool.pyscript1.2 KB
seeds/slot_write/tool.pyscript1015 B
tests/__init__.pyscript0 B
tests/support.pyscript668 B
tests/test_audit_harness.pyscript23.5 KB
tests/test_branch.pyscript14.4 KB
tests/test_builder3_templates.pyscript2.4 KB
tests/test_builder_install_integrity.pyscript30.6 KB
tests/test_builder_native_snapshot.pyscript5.0 KB
tests/test_builder_requirements.pyscript26.8 KB
tests/test_builder_self_dogfood.pyscript7.0 KB
tests/test_builder_self_source.pyscript10.3 KB

scripts/runtime_release.py

View on GitHub
"""Build and verify immutable, codebase-owned M8M runtime releases.

The Builder is a compiler/packager.  Product execution must never import the
mutable Builder installation.  A build copies this closed runtime payload into
the owning codebase beside the compiled harness, addresses it by its payload
digest, and pins that digest in every run before workflow execution starts.
The product skill contains only a pointer to the codebase launcher.
"""

from __future__ import annotations

import hashlib
import importlib.metadata
import json
import os
import re
import secrets
import shutil
import sys
import zipfile
from copy import deepcopy
from contextlib import contextmanager
import platform
import threading
from pathlib import Path, PurePosixPath
from typing import Any, Iterable, Mapping, Sequence


RUNTIME_RELEASE_SCHEMA = "m8m.runtime_release.v1"
RUNTIME_LOCK_SCHEMA = "m8m.runtime_lock.v1"
RUNTIME_NAME = "m8m-runtime"
RUNTIME_VERSION = "1.0.0"
RUNTIME_CLI_ABI = "m8m_runtime_cli_v1"
RUNTIME_ENTRYPOINT = "scripts/run_flow.py"
RUNTIME_LOCK_FILENAME = "m8m-runtime-lock.json"
RUNTIME_MANIFEST_ENV = "M8M_RUNTIME_MANIFEST"
# A one-use result created only by full verification inside the isolated
# bootstrap. Never persisted, inherited from an environment flag or reused by
# another process/resume.
_startup_verification = None
RUNTIME_DEPENDENCIES = (
    "attrs",
    "jsonschema",
    "jsonschema-specifications",
    "PyYAML",
    "referencing",
    "rpds-py",
)

# This is the product execution closure.  Compiler, source-bundle, chart, and
# Builder dogfood modules are deliberately absent.
RUNTIME_SCRIPT_FILES = (
    "candidate_cache.py",
    "execution_identity.py",
    "flowstep_runtime.py",
    "flowstep_tools.py",
    "gem_text.py",
    "m8m_cache.py",
    "milestone_expectation.py",
    "project_imports.py",
    "run_flow.py",
    "run_goal.py",
    "runtime_release.py",
    "schema_gate.py",
    "session_layout.py",
)

RUNTIME_CONTRACT_FILES = (
    "file_ref_v2.schema.json",
    "flow_sequence_action_v2.schema.json",
    "flowstep_flow_v4.schema.json",
    "flowstep_output_v3.schema.json",
    "m8m_cache_receipt_v1.schema.json",
    "m8m_candidate_cache_entry_v1.schema.json",
    "m8m_chosen_output_v1.schema.json",
    "m8m_context_capsule_v1.schema.json",
    "m8m_goal_ledger_v1.schema.json",
    "m8m_milestone_expectation_v1.schema.json",
    "m8m_milestone_judge_receipt_v1.schema.json",
    "m8m_milestone_judge_request_v1.schema.json",
    "m8m_run_context_v1.schema.json",
    "m8m_run_context_v2.schema.json",
    "m8m_run_storage_contract_v1.schema.json",
    "m8m_runtime_lock_v1.schema.json",
    "m8m_runtime_release_v1.schema.json",
    "m8m_source_asset_manifest_v1.schema.json",
)


class RuntimeReleaseError(ValueError):
    """The runtime release, lock, or launch boundary is invalid."""


def _is_unsafe_link(path: Path) -> bool:
    """Treat Windows junctions/reparse directories like symbolic links."""

    try:
        is_junction = getattr(path, "is_junction", None)
        return path.is_symlink() or bool(is_junction and is_junction())
    except OSError:
        return True


def _canonical_bytes(value: Any) -> bytes:
    return (
        json.dumps(
            value,
            ensure_ascii=False,
            sort_keys=True,
            separators=(",", ":"),
            allow_nan=False,
        )
        + "\n"
    ).encode("utf-8")


def _digest_bytes(value: bytes) -> str:
    return "sha256:" + hashlib.sha256(value).hexdigest()


def _sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as handle:
        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def _pretty_json_bytes(value: Mapping[str, Any]) -> bytes:
    return (
        json.dumps(value, ensure_ascii=False, sort_keys=True, indent=2) + "\n"
    ).encode("utf-8")


def _safe_relative(value: str) -> str:
    if not value or "\\" in value:
        raise RuntimeReleaseError(f"unsafe runtime member path: {value!r}")
    pure = PurePosixPath(value)
    if pure.is_absolute() or any(part in {"", ".", ".."} for part in pure.parts):
        raise RuntimeReleaseError(f"unsafe runtime member path: {value!r}")
    return pure.as_posix()


def _source_members(builder_root: Path) -> list[tuple[str, Path]]:
    root = builder_root.resolve()
    members: list[tuple[str, Path]] = []
    for name in RUNTIME_SCRIPT_FILES:
        members.append((f"scripts/{name}", root / "scripts" / name))
    for name in RUNTIME_CONTRACT_FILES:
        members.append((f"contracts/{name}", root / "contracts" / name))
    missing = [str(path) for _, path in members if not path.is_file()]
    if missing:
        raise RuntimeReleaseError(
            "runtime release source is incomplete: " + ", ".join(missing)
        )
    return members


def _python_identity() -> tuple[str, str]:
    python_abi = str(sys.implementation.cache_tag or "")
    if not python_abi:
        raise RuntimeReleaseError("cannot determine the Python runtime ABI")
    # Hosted Python installs and virtualenvs commonly expose a symlink. Bind
    # identity to the actual interpreter bytes, not the installation alias.
    try:
        executable = Path(sys.executable).resolve(strict=True)
    except (OSError, RuntimeError) as exc:
        raise RuntimeReleaseError("cannot resolve the Python interpreter executable") from exc
    if not executable.is_file() or _is_unsafe_link(executable):
        raise RuntimeReleaseError(
            "cannot determine a safe Python interpreter executable identity"
        )
    return python_abi, f"sha256:{_sha256_file(executable)}"


def validate_product_distributions(value: Any) -> list[dict[str, str]]:
    """Validate exact authored roots without consulting host packages."""
    if value is None:
        return []
    if not isinstance(value, list) or not 1 <= len(value) <= 32:
        raise RuntimeReleaseError("runtime_distributions must contain 1–32 exact distribution pins")
    result: list[dict[str, str]] = []
    seen: set[str] = set()
    for row in value:
        if not isinstance(row, dict) or set(row) != {"name", "version"}:
            raise RuntimeReleaseError("runtime_distributions rows require only name and version")
        name, version = row["name"], row["version"]
        if not isinstance(name, str) or not re.fullmatch(r"[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?", name):
            raise RuntimeReleaseError("runtime_distributions has an invalid distribution name")
        if not isinstance(version, str) or not re.fullmatch(r"[0-9][A-Za-z0-9.!+_-]*", version):
            raise RuntimeReleaseError("runtime_distributions requires exact versions, without ranges, extras or URLs")
        canonical = re.sub(r"[-_.]+", "-", name).lower()
        if canonical in seen:
            raise RuntimeReleaseError(f"duplicate canonical runtime distribution: {canonical}")
        seen.add(canonical)
        result.append({"name": name, "version": version})
    return result


def assert_product_distribution_lock(value: Any, dependencies: Sequence[Mapping[str, Any]]) -> None:
    """Compare authored roots only with the already verified runtime lock."""
    locked = {re.sub(r"[-_.]+", "-", str(row["name"])).lower(): str(row["version"])
              for row in dependencies}
    for row in validate_product_distributions(value):
        canonical = re.sub(r"[-_.]+", "-", row["name"]).lower()
        if locked.get(canonical) != row["version"]:
            raise RuntimeReleaseError(
                f"declared runtime distribution is absent or differs from the verified runtime lock: "
                f"{row['name']}=={row['version']} (locked {locked.get(canonical)!r})"
            )


_marker_environment_lock = threading.RLock()


@contextmanager
def _local_windows_marker_queries():
    """Use CPython's local OS fallback, not a potentially stuck WMI service.

Packaging re-queries the default environment even when evaluate() receives an
explicit environment. Keep the fallback scoped over the entire closure pass;
restore the process hook on both success and error. No OS service is modified.
"""
    if sys.platform != 'win32' or not hasattr(platform, '_wmi_query'):
        yield
        return
    with _marker_environment_lock:
        original = platform._wmi_query
        def unavailable(*args, **kwargs):
            raise OSError('Builder uses local Windows marker information')
        platform._wmi_query = unavailable
        try:
            yield
        finally:
            platform._wmi_query = original


def _resolved_runtime_distributions(product_distributions: Any = None) -> list[tuple[str, Any]]:
    with _local_windows_marker_queries():
        return _resolve_runtime_distributions_local(product_distributions)


def _resolve_runtime_distributions_local(product_distributions: Any = None) -> list[tuple[str, Any]]:
    """Resolve the marker-aware transitive dependency closure for this host."""

    try:
        from packaging.markers import default_environment
        from packaging.requirements import Requirement
        from packaging.utils import canonicalize_name
    except ImportError as exc:
        raise RuntimeReleaseError(
            "runtime dependency closure requires the Builder's packaging library"
        ) from exc

    environment = default_environment()
    environment["extra"] = ""
    roots = validate_product_distributions(product_distributions)
    try:
        pending = [Requirement(name) for name in RUNTIME_DEPENDENCIES]
        pending.extend(Requirement(f"{row['name']}=={row['version']}") for row in roots)
    except Exception as exc:
        raise RuntimeReleaseError(f"invalid exact runtime distribution pin: {exc}") from exc
    resolved: dict[str, tuple[str, Any]] = {}
    while pending:
        pending.sort(key=lambda item: canonicalize_name(item.name))
        requirement = pending.pop(0)
        if requirement.marker is not None and not requirement.marker.evaluate(environment):
            continue
        if requirement.extras or requirement.url:
            raise RuntimeReleaseError(f"runtime dependency extras/direct URLs are unsupported: {requirement}")
        canonical = canonicalize_name(requirement.name)
        try:
            distribution = importlib.metadata.distribution(requirement.name)
        except importlib.metadata.PackageNotFoundError as exc:
            raise RuntimeReleaseError(
                f"transitive runtime dependency is not installed: {requirement.name}"
            ) from exc
        if requirement.specifier and not requirement.specifier.contains(
            str(distribution.version), prereleases=True
        ):
            raise RuntimeReleaseError(
                "installed transitive runtime dependency does not satisfy its "
                f"requirement: {requirement} (found {distribution.version})"
            )
        if canonical in resolved:
            continue
        declared_name = str(distribution.metadata.get("Name") or requirement.name)
        resolved[canonical] = (declared_name, distribution)
        child_requirements = []
        for raw_requirement in distribution.requires or []:
            try:
                child = Requirement(raw_requirement)
            except Exception as exc:
                raise RuntimeReleaseError(
                    f"invalid Requires-Dist for {declared_name}: {raw_requirement}"
                ) from exc
            if child.marker is None or child.marker.evaluate(environment):
                child_requirements.append(child)
        pending.extend(child_requirements)
    rows = [resolved[key] for key in sorted(resolved)]
    # Exact strings also reject a host's local-version substitution for an
    # authored public version, even where PEP 440 equality would allow it.
    assert_product_distribution_lock(product_distributions,
        [{"name": name, "version": str(dist.version)} for name, dist in rows])
    return rows


def _dependency_sources(product_distributions: Any = None, *, member_rows=None) -> tuple[list[dict[str, Any]], list[tuple[str, Path]]]:
    """Freeze every installed distribution into its own import root.

    Distribution paths that deliberately escape site-packages (for example a
    generated console script) are not importable package members and are
    excluded.  Everything inside the distribution root is copied and hashed.
    Separate vendor roots avoid cross-distribution path collisions while the
    dispatcher prepends all locked vendor roots to the isolated interpreter.
    """

    dependencies: list[dict[str, Any]] = []
    sources: list[tuple[str, Path]] = []
    vendor_roots: set[str] = set()
    for name, distribution in _resolved_runtime_distributions(product_distributions):
        raw_files = distribution.files
        if not raw_files:
            raise RuntimeReleaseError(
                f"runtime dependency has no deterministic file inventory: {name}"
            )
        vendor_id = "".join(
            character.lower() if character.isalnum() else "-"
            for character in name
        ).strip("-")
        vendor_path = f"vendor/{vendor_id}"
        if not vendor_id or vendor_path in vendor_roots:
            raise RuntimeReleaseError(
                f"runtime dependency vendor root collides: {name}"
            )
        vendor_roots.add(vendor_path)
        file_rows: list[dict[str, Any]] = []
        seen: set[str] = set()
        for raw_file in sorted(raw_files, key=lambda item: str(item).casefold()):
            raw_relative = str(raw_file).replace("\\", "/")
            pure = PurePosixPath(raw_relative)
            # Console entrypoints may live outside site-packages. They are not
            # imported by the runtime and must not escape the vendor root.
            if (
                not raw_relative
                or pure.is_absolute()
                or any(part in {"", ".", ".."} for part in pure.parts)
            ):
                continue
            # Bytecode caches are interpreter-generated, may disappear during
            # clean installation, and are never an authored dependency asset.
            # Source files and native extension modules remain in the lock.
            if "__pycache__" in pure.parts or pure.suffix.lower() in {".pyc", ".pyo"}:
                continue
            relative = pure.as_posix()
            if relative in seen:
                raise RuntimeReleaseError(
                    f"runtime dependency contains a duplicate file: {name}: {relative}"
                )
            source = Path(distribution.locate_file(raw_file)).absolute()
            if not source.is_file() or _is_unsafe_link(source):
                raise RuntimeReleaseError(
                    f"runtime dependency file is missing or unsafe: {name}: {relative}"
                )
            seen.add(relative)
            member_path = f"{vendor_path}/{relative}"
            row = {
                "path": member_path,
                "byte_count": source.stat().st_size,
                "digest": f"sha256:{_sha256_file(source)}",
            }
            file_rows.append(row)
            if member_rows is not None:
                member_rows[member_path] = row
            sources.append((member_path, source))
        if not file_rows:
            raise RuntimeReleaseError(
                f"runtime dependency has no vendorable files: {name}"
            )
        dependencies.append(
            {
                "name": name,
                "version": str(distribution.version),
                "vendor_path": vendor_path,
                "file_count": len(file_rows),
                "files_digest": _digest_bytes(_canonical_bytes(file_rows)),
            }
        )
    return dependencies, sources


def _runtime_identity(manifest: Mapping[str, Any]) -> dict[str, Any]:
    """Return every field that can change runtime execution semantics."""

    return {
        "schema": manifest["schema"],
        "runtime_name": manifest["runtime_name"],
        "runtime_version": manifest["runtime_version"],
        "cli_abi": manifest["cli_abi"],
        "entrypoint": manifest["entrypoint"],
        "python_abi": manifest["python_abi"],
        "python_executable_digest": manifest["python_executable_digest"],
        "dependencies": manifest["dependencies"],
        "members": manifest["members"],
    }


def _manifest_from_sources(builder_root: Path, product_distributions: Any = None) -> tuple[dict[str, Any], list[tuple[str, Path]]]:
    sources = _source_members(builder_root)
    dependency_rows = {}
    dependencies, dependency_sources = _dependency_sources(product_distributions, member_rows=dependency_rows)
    sources.extend(dependency_sources)
    members = [
        dependency_rows[relative] if relative in dependency_rows else {
            "path": relative,
            "byte_count": source.stat().st_size,
            "digest": f"sha256:{_sha256_file(source)}",
        }
        for relative, source in sources
    ]
    python_abi, python_executable_digest = _python_identity()
    identity = {
        "schema": RUNTIME_RELEASE_SCHEMA,
        "runtime_name": RUNTIME_NAME,
        "runtime_version": RUNTIME_VERSION,
        "cli_abi": RUNTIME_CLI_ABI,
        "entrypoint": RUNTIME_ENTRYPOINT,
        "python_abi": python_abi,
        "python_executable_digest": python_executable_digest,
        "dependencies": dependencies,
        "members": members,
    }
    payload_digest = _digest_bytes(
        _canonical_bytes(_runtime_identity(identity))
    )
    runtime_id = payload_digest.split(":", 1)[1]
    return (
        {
            "schema": RUNTIME_RELEASE_SCHEMA,
            "runtime_name": RUNTIME_NAME,
            "runtime_version": RUNTIME_VERSION,
            "runtime_id": runtime_id,
            "cli_abi": RUNTIME_CLI_ABI,
            "entrypoint": RUNTIME_ENTRYPOINT,
            "python_abi": python_abi,
            "python_executable_digest": python_executable_digest,
            "dependencies": dependencies,
            "payload_digest": payload_digest,
            "members": members,
        },
        sources,
    )


def _runtime_lock(manifest: Mapping[str, Any]) -> dict[str, Any]:
    return {
        "schema": RUNTIME_LOCK_SCHEMA,
        "runtime_name": str(manifest["runtime_name"]),
        "runtime_version": str(manifest["runtime_version"]),
        "runtime_id": str(manifest["runtime_id"]),
        "cli_abi": str(manifest["cli_abi"]),
        "entrypoint": str(manifest["entrypoint"]),
        "python_abi": str(manifest["python_abi"]),
        "python_executable_digest": str(manifest["python_executable_digest"]),
        "dependencies": [dict(item) for item in manifest["dependencies"]],
        "payload_digest": str(manifest["payload_digest"]),
        "manifest_digest": _digest_bytes(_canonical_bytes(dict(manifest))),
    }


def _write_json(path: Path, value: Mapping[str, Any]) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    encoded = _pretty_json_bytes(value)
    if path.is_file() and path.read_bytes() == encoded:
        return
    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
    temporary.write_bytes(encoded)
    os.replace(temporary, path)


def _assert_release_bytes(
    release_dir: Path,
    manifest: Mapping[str, Any],
    sources: Sequence[tuple[str, Path]],
) -> Path:
    """Accept an existing release only when every byte is already identical."""

    manifest_path = release_dir / "runtime-manifest.json"
    expected = {relative for relative, _ in sources}
    expected.add("runtime-manifest.json")
    actual: set[str] = set()
    for candidate in release_dir.rglob("*"):
        if _is_unsafe_link(candidate):
            raise RuntimeReleaseError(
                f"immutable runtime release contains an unsafe link: {candidate}"
            )
        if candidate.is_file():
            actual.add(candidate.relative_to(release_dir).as_posix())
    if actual != expected:
        raise RuntimeReleaseError(
            "immutable runtime release directory already exists with different bytes"
        )
    for relative, source in sources:
        destination = release_dir.joinpath(*PurePosixPath(relative).parts)
        if (
            not destination.is_file()
            or destination.stat().st_size != source.stat().st_size
            or _sha256_file(destination) != _sha256_file(source)
        ):
            raise RuntimeReleaseError(
                "immutable runtime release directory already exists with different bytes"
            )
    if not manifest_path.is_file() or manifest_path.read_bytes() != _pretty_json_bytes(manifest):
        raise RuntimeReleaseError(
            "immutable runtime release directory already exists with different bytes"
        )
    verify_runtime_release(manifest_path)
    return manifest_path


def _copy_release(
    release_dir: Path,
    manifest: Mapping[str, Any],
    sources: Sequence[tuple[str, Path]],
) -> Path:
    parent = release_dir.parent
    parent.mkdir(parents=True, exist_ok=True)
    if release_dir.exists():
        if not release_dir.is_dir() or _is_unsafe_link(release_dir):
            raise RuntimeReleaseError("immutable runtime release path is unsafe")
        return _assert_release_bytes(release_dir, manifest, sources)

    temporary = parent / (
        f".{release_dir.name}.{os.getpid()}.{secrets.token_hex(8)}.tmp"
    )
    temporary.mkdir(parents=False, exist_ok=False)
    try:
        for relative, source in sources:
            destination = temporary.joinpath(*PurePosixPath(relative).parts)
            destination.parent.mkdir(parents=True, exist_ok=True)
            shutil.copy2(source, destination)
        manifest_path = temporary / "runtime-manifest.json"
        manifest_path.write_bytes(_pretty_json_bytes(manifest))
        verify_runtime_release(manifest_path)
        try:
            os.rename(temporary, release_dir)
        except OSError:
            # A concurrent writer may have won. It is acceptable only when it
            # published the exact same immutable release.
            if not release_dir.is_dir() or _is_unsafe_link(release_dir):
                raise
            _assert_release_bytes(release_dir, manifest, sources)
        return release_dir / "runtime-manifest.json"
    finally:
        if temporary.exists():
            shutil.rmtree(temporary)


def _write_release_archive(
    archive_path: Path,
    manifest: Mapping[str, Any],
    sources: Sequence[tuple[str, Path]],
) -> None:
    archive_path.parent.mkdir(parents=True, exist_ok=True)
    temporary = archive_path.with_name(f".{archive_path.name}.{os.getpid()}.tmp")
    with zipfile.ZipFile(temporary, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=9) as archive:
        payloads = [(relative, source.read_bytes()) for relative, source in sources]
        payloads.append(("runtime-manifest.json", _canonical_bytes(dict(manifest))))
        for relative, payload in sorted(payloads):
            info = zipfile.ZipInfo(relative, date_time=(1980, 1, 1, 0, 0, 0))
            info.compress_type = zipfile.ZIP_DEFLATED
            info.external_attr = 0o100644 << 16
            info.create_system = 3
            archive.writestr(info, payload)
    if archive_path.is_file():
        if archive_path.read_bytes() != temporary.read_bytes():
            temporary.unlink(missing_ok=True)
            raise RuntimeReleaseError(
                "immutable runtime release archive already exists with different bytes"
            )
        temporary.unlink(missing_ok=True)
        return
    os.replace(temporary, archive_path)


def stage_runtime_release(
    *,
    builder_root: Path,
    harness: Path,
    product_roots: Sequence[Path],
    flow_id: str,
    codebase: Path,
    product_distributions: Any = None,
) -> dict[str, Any]:
    """Stage one immutable runtime owned by the compiled codebase harness.

    Product skills receive only a tiny pointer to ``harness/launch.py``.  They
    never receive or import runtime implementation modules.
    """

    manifest, sources = _manifest_from_sources(builder_root, product_distributions)
    runtime_id = str(manifest["runtime_id"])
    lock = _runtime_lock(manifest)
    harness = harness.absolute()
    if _is_unsafe_link(harness):
        raise RuntimeReleaseError("staged harness uses an unsafe link")
    harness.mkdir(parents=True, exist_ok=True)
    (harness / "BUILD_REQUIRED_RUNTIME").unlink(missing_ok=True)
    release_dir = harness / "runtime" / "releases" / runtime_id
    for boundary in (
        harness / "runtime",
        harness / "runtime" / "releases",
        release_dir,
    ):
        if boundary.exists() and _is_unsafe_link(boundary):
            raise RuntimeReleaseError(
                f"runtime release staging boundary uses an unsafe link: {boundary}"
            )
    manifest_path = _copy_release(release_dir, manifest, sources)
    _write_json(harness / "runtime" / "active.json", lock)
    codebase_launcher_source = (
        builder_root.resolve() / "templates" / "codebase-launcher.py"
    )
    skill_pointer_source = builder_root.resolve() / "templates" / "run.py"
    if not codebase_launcher_source.is_file() or not skill_pointer_source.is_file():
        raise RuntimeReleaseError("codebase launcher templates are missing")
    codebase_launcher = harness / "launch.py"
    codebase_launcher.write_text(
        codebase_launcher_source.read_text(encoding="utf-8"),
        encoding="utf-8",
        newline="\n",
    )
    codebase_launcher_sha256 = _sha256_file(codebase_launcher)
    for product_root in product_roots:
        root = product_root.resolve()
        launcher = root / "scripts" / "m8m_run.py"
        launcher.parent.mkdir(parents=True, exist_ok=True)
        installed_launcher = (
            codebase.resolve() / "flowsteps" / "flows" / flow_id / "launch.py"
        )
        pointer = (
            skill_pointer_source.read_text(encoding="utf-8")
            .replace(
                "__CODEBASE_LAUNCHER__",
                str(installed_launcher).replace("\\", "/"),
            )
            .replace("__CODEBASE_LAUNCHER_SHA256__", codebase_launcher_sha256)
        )
        launcher.write_text(pointer, encoding="utf-8", newline="\n")
    harness_lock_path = harness / RUNTIME_LOCK_FILENAME
    _write_json(harness_lock_path, lock)
    compiled = harness / "compiled" / "runtime"
    archive_path = compiled / f"m8m-runtime-{runtime_id}.zip"
    _write_release_archive(archive_path, manifest, sources)
    archive_manifest_path = compiled / "runtime-manifest.json"
    _write_json(archive_manifest_path, manifest)
    return {
        "schema": RUNTIME_RELEASE_SCHEMA,
        "runtime_name": RUNTIME_NAME,
        "runtime_version": RUNTIME_VERSION,
        "runtime_id": runtime_id,
        "cli_abi": RUNTIME_CLI_ABI,
        "entrypoint": RUNTIME_ENTRYPOINT,
        "python_abi": str(manifest["python_abi"]),
        "python_executable_digest": str(manifest["python_executable_digest"]),
        "dependencies": [dict(item) for item in manifest["dependencies"]],
        "payload_digest": str(manifest["payload_digest"]),
        "manifest_digest": str(lock["manifest_digest"]),
        "manifest_path": str(manifest_path),
        "manifest_sha256": _sha256_file(manifest_path),
        "codebase_launcher_path": str(codebase_launcher),
        "codebase_launcher_sha256": codebase_launcher_sha256,
        "archive_path": str(archive_path),
        "archive_sha256": _sha256_file(archive_path),
        "harness_lock_path": str(harness_lock_path),
        "harness_lock_sha256": _sha256_file(harness_lock_path),
        "member_count": len(manifest["members"]),
    }


def verify_runtime_release(manifest_path: Path) -> dict[str, Any]:
    path = manifest_path.absolute()
    for boundary in (path, path.parent, path.parent.parent, path.parent.parent.parent):
        if boundary.exists() and _is_unsafe_link(boundary):
            raise RuntimeReleaseError(
                f"runtime release path uses an unsafe link: {boundary}"
            )
    try:
        manifest = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
        raise RuntimeReleaseError(f"cannot read runtime release manifest: {path}: {exc}") from exc
    required = {
        "schema",
        "runtime_name",
        "runtime_version",
        "runtime_id",
        "cli_abi",
        "entrypoint",
        "python_abi",
        "python_executable_digest",
        "dependencies",
        "payload_digest",
        "members",
    }
    if not isinstance(manifest, dict) or set(manifest) != required:
        raise RuntimeReleaseError("runtime release manifest has an invalid closed shape")
    if manifest.get("schema") != RUNTIME_RELEASE_SCHEMA:
        raise RuntimeReleaseError("runtime release schema is invalid")
    if manifest.get("runtime_name") != RUNTIME_NAME:
        raise RuntimeReleaseError("runtime release name is invalid")
    if manifest.get("cli_abi") != RUNTIME_CLI_ABI:
        raise RuntimeReleaseError("runtime release CLI ABI is unsupported")
    members = manifest.get("members")
    if not isinstance(members, list) or not members:
        raise RuntimeReleaseError("runtime release has no members")
    dependencies = manifest.get("dependencies")
    if not isinstance(dependencies, list) or not dependencies:
        raise RuntimeReleaseError("runtime release has no dependency lock")
    normalized_dependencies: list[dict[str, Any]] = []
    dependency_names: set[str] = set()
    dependency_vendor_paths: set[str] = set()
    for item in dependencies:
        if not isinstance(item, dict) or set(item) != {
            "name",
            "version",
            "vendor_path",
            "file_count",
            "files_digest",
        }:
            raise RuntimeReleaseError("runtime dependency lock has an invalid closed shape")
        name = str(item.get("name") or "")
        version = str(item.get("version") or "")
        vendor_path = _safe_relative(str(item.get("vendor_path") or ""))
        file_count = item.get("file_count")
        files_digest = str(item.get("files_digest") or "")
        if (
            not name
            or not version
            or name in dependency_names
            or vendor_path in dependency_vendor_paths
            or len(PurePosixPath(vendor_path).parts) != 2
            or PurePosixPath(vendor_path).parts[0] != "vendor"
            or not isinstance(file_count, int)
            or isinstance(file_count, bool)
            or file_count < 1
            or len(files_digest) != 71
            or not files_digest.startswith("sha256:")
            or any(character not in "0123456789abcdef" for character in files_digest[7:])
        ):
            raise RuntimeReleaseError("runtime dependency lock has an invalid entry")
        dependency_names.add(name)
        dependency_vendor_paths.add(vendor_path)
        normalized_dependencies.append(
            {
                "name": name,
                "version": version,
                "vendor_path": vendor_path,
                "file_count": file_count,
                "files_digest": files_digest,
            }
        )
    python_abi = str(manifest.get("python_abi") or "")
    python_executable_digest = str(manifest.get("python_executable_digest") or "")
    current_abi, current_executable_digest = _python_identity()
    if (
        python_abi != current_abi
        or python_executable_digest != current_executable_digest
    ):
        raise RuntimeReleaseError(
            "runtime host interpreter does not match the immutable release"
        )
    normalized: list[dict[str, Any]] = []
    seen: set[str] = set()
    release_root = path.parent
    for item in members:
        if not isinstance(item, dict) or set(item) != {"path", "byte_count", "digest"}:
            raise RuntimeReleaseError("runtime release member has an invalid closed shape")
        relative = _safe_relative(str(item.get("path") or ""))
        if relative in seen:
            raise RuntimeReleaseError(f"duplicate runtime release member: {relative}")
        seen.add(relative)
        member = release_root.joinpath(*PurePosixPath(relative).parts).resolve()
        if release_root != member and release_root not in member.parents:
            raise RuntimeReleaseError(f"runtime release member escapes its root: {relative}")
        if not member.is_file() or _is_unsafe_link(member):
            raise RuntimeReleaseError(f"runtime release member is missing: {relative}")
        actual = f"sha256:{_sha256_file(member)}"
        if actual != item.get("digest") or member.stat().st_size != item.get("byte_count"):
            raise RuntimeReleaseError(f"runtime release member digest mismatch: {relative}")
        normalized.append(
            {"path": relative, "byte_count": member.stat().st_size, "digest": actual}
        )
    covered_vendor_members: set[str] = set()
    for dependency in normalized_dependencies:
        prefix = str(dependency["vendor_path"]) + "/"
        dependency_members = [
            item for item in normalized if str(item["path"]).startswith(prefix)
        ]
        if (
            len(dependency_members) != dependency["file_count"]
            or _digest_bytes(_canonical_bytes(dependency_members))
            != dependency["files_digest"]
        ):
            raise RuntimeReleaseError(
                f"runtime dependency file identity is invalid: {dependency['name']}"
            )
        covered_vendor_members.update(str(item["path"]) for item in dependency_members)
    all_vendor_members = {
        str(item["path"])
        for item in normalized
        if str(item["path"]).startswith("vendor/")
    }
    if all_vendor_members != covered_vendor_members:
        raise RuntimeReleaseError(
            "runtime release has dependency files outside its closed vendor locks"
        )
    expected_files = {"runtime-manifest.json", *seen}
    actual_files: set[str] = set()
    for member in release_root.rglob("*"):
        if _is_unsafe_link(member):
            raise RuntimeReleaseError(
                f"runtime release contains an undeclared link: {member.relative_to(release_root)}"
            )
        if member.is_file():
            actual_files.add(member.relative_to(release_root).as_posix())
    extras = sorted(actual_files - expected_files)
    missing = sorted(expected_files - actual_files)
    if extras or missing:
        detail = []
        if extras:
            detail.append("undeclared files: " + ", ".join(extras))
        if missing:
            detail.append("missing files: " + ", ".join(missing))
        raise RuntimeReleaseError("runtime release is not a closed directory: " + "; ".join(detail))
    normalized_manifest = {
        **manifest,
        "python_abi": python_abi,
        "python_executable_digest": python_executable_digest,
        "dependencies": normalized_dependencies,
        "members": normalized,
    }
    payload_digest = _digest_bytes(
        _canonical_bytes(_runtime_identity(normalized_manifest))
    )
    runtime_id = payload_digest.split(":", 1)[1]
    if manifest.get("payload_digest") != payload_digest or manifest.get("runtime_id") != runtime_id:
        raise RuntimeReleaseError("runtime release payload identity is invalid")
    if str(manifest.get("entrypoint") or "") not in seen:
        raise RuntimeReleaseError("runtime release entrypoint is not a declared member")
    return manifest


def verify_harness_runtime(harness: Path) -> dict[str, Any]:
    """Verify positive codebase-owned runtime packaging evidence for a harness."""

    root = harness.absolute()
    launcher = root / "launch.py"
    harness_lock_path = root / RUNTIME_LOCK_FILENAME
    active_lock_path = root / "runtime" / "active.json"
    missing = [
        path.name if path.parent == root else path.relative_to(root).as_posix()
        for path in (launcher, harness_lock_path, active_lock_path)
        if not path.is_file()
    ]
    if missing:
        raise RuntimeReleaseError(
            "codebase-owned runtime packaging is incomplete: " + ", ".join(missing)
        )
    link_boundaries = (
        root,
        root.parent,
        root.parent.parent,
        launcher,
        harness_lock_path,
        root / "runtime",
        root / "runtime" / "releases",
        active_lock_path,
    )
    if any(_is_unsafe_link(path) for path in link_boundaries):
        raise RuntimeReleaseError("codebase-owned runtime packaging uses an unsafe link")
    if launcher.stat().st_size == 0:
        raise RuntimeReleaseError("codebase-owned runtime launcher is empty")
    harness_lock = _read_lock(harness_lock_path, label="workflow runtime lock")
    active_lock = _read_lock(active_lock_path, label="active runtime lock")
    if not _lock_matches(harness_lock, active_lock):
        raise RuntimeReleaseError("workflow and active runtime locks do not match")
    runtime_id = str(harness_lock.get("runtime_id") or "")
    release_root = root / "runtime" / "releases" / runtime_id
    manifest_path = release_root / "runtime-manifest.json"
    if _is_unsafe_link(release_root) or _is_unsafe_link(manifest_path):
        raise RuntimeReleaseError("codebase-owned runtime release uses an unsafe link")
    manifest = verify_runtime_release(manifest_path)
    expected_lock = _runtime_lock(manifest)
    if not _lock_matches(harness_lock, expected_lock):
        raise RuntimeReleaseError("workflow runtime lock does not match its release")
    return manifest


def _read_lock(path: Path, *, label: str) -> dict[str, Any]:
    try:
        lock = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
        raise RuntimeReleaseError(f"cannot read {label}: {path}: {exc}") from exc
    expected = {
        "schema",
        "runtime_name",
        "runtime_version",
        "runtime_id",
        "cli_abi",
        "entrypoint",
        "python_abi",
        "python_executable_digest",
        "dependencies",
        "payload_digest",
        "manifest_digest",
    }
    if not isinstance(lock, dict) or set(lock) != expected:
        raise RuntimeReleaseError(f"{label} has an invalid closed shape")
    if lock.get("schema") != RUNTIME_LOCK_SCHEMA:
        raise RuntimeReleaseError(f"{label} schema is invalid")
    return lock


def _lock_matches(left: Mapping[str, Any], right: Mapping[str, Any]) -> bool:
    return all(left.get(key) == right.get(key) for key in _runtime_lock_keys())


def _runtime_lock_keys() -> tuple[str, ...]:
    return (
        "schema",
        "runtime_name",
        "runtime_version",
        "runtime_id",
        "cli_abi",
        "entrypoint",
        "python_abi",
        "python_executable_digest",
        "dependencies",
        "payload_digest",
        "manifest_digest",
    )


def verify_runtime_for_startup(manifest_path: Path) -> dict[str, Any]:
    """Verify before loading vendor/product code, then allow one same-process bind."""
    global _startup_verification
    _startup_verification = None
    if not (sys.flags.isolated and sys.flags.no_site and sys.dont_write_bytecode):
        raise RuntimeReleaseError("runtime bootstrap requires isolated, no-site, no-bytecode Python")
    manifest = verify_runtime_release(manifest_path)
    _startup_verification = (os.getpid(), str(manifest_path.absolute()), deepcopy(manifest))
    return manifest


def _runtime_for_binding(manifest_path: Path) -> dict[str, Any]:
    global _startup_verification
    verified, _startup_verification = _startup_verification, None
    if verified is not None:
        pid, path, manifest = verified
        if pid == os.getpid() and path == str(manifest_path.absolute()):
            # Detect changed manifest identity between bootstrap and bind.
            current = json.loads(manifest_path.read_text(encoding="utf-8"))
            if current != manifest:
                raise RuntimeReleaseError("runtime manifest changed after bootstrap verification")
            return manifest
    return verify_runtime_release(manifest_path)


def bind_runtime_to_run(
    harness: Path,
    run_dir: Path,
    *,
    run_mode: str,
    executing_entrypoint: Path | None = None,
    product_distributions: Any = None,
    execution_mode: str = "packaged",
) -> dict[str, Any] | None:
    """Pin/verify the executing runtime before any milestone work starts."""

    harness_lock_path = harness.resolve() / RUNTIME_LOCK_FILENAME
    run_lock_path = run_dir.resolve() / RUNTIME_LOCK_FILENAME
    manifest_value = os.environ.get(RUNTIME_MANIFEST_ENV, "").strip()
    if execution_mode not in {"coordination", "packaged"}:
        raise RuntimeReleaseError("execution mode must be coordination or packaged")
    if execution_mode == "coordination":
        if manifest_value or harness_lock_path.exists() or run_lock_path.exists():
            raise RuntimeReleaseError(
                "a packaged workflow or run must use its existing codebase launcher; "
                "coordination cannot bypass a runtime pin"
            )
        return None
    if not manifest_value:
        if harness.resolve() == Path(__file__).resolve().parents[1]:
            return None
        if harness_lock_path.is_file() or run_lock_path.is_file():
            raise RuntimeReleaseError(
                "this workflow is pinned to a codebase-owned M8M runtime; invoke the "
                "built skill's scripts/m8m_run.py instead of the Builder runtime"
            )
        raise RuntimeReleaseError(
            "this product harness has no codebase-owned M8M runtime release; "
            "run the complete m8m-harness-builder workflow and invoke the built "
            "skill's scripts/m8m_run.py"
        )
    manifest_path = Path(manifest_value).resolve()
    manifest = _runtime_for_binding(manifest_path)
    release_root = manifest_path.parent.resolve()
    expected_runtime_module = release_root / "scripts" / "runtime_release.py"
    if Path(__file__).resolve() != expected_runtime_module.resolve():
        raise RuntimeReleaseError(
            "the runtime manifest does not describe the M8M runtime code that is "
            "actually executing; invoke the built skill's codebase launcher"
        )
    if executing_entrypoint is not None:
        entrypoint = Path(executing_entrypoint).resolve()
        scripts_root = (release_root / "scripts").resolve()
        if entrypoint.parent != scripts_root or entrypoint.name not in {
            "run_flow.py",
            "run_goal.py",
        }:
            raise RuntimeReleaseError(
                "the executing M8M entrypoint is outside the pinned codebase runtime release"
            )
        declared_members = {
            str(item.get("path") or "")
            for item in manifest.get("members", [])
            if isinstance(item, dict)
        }
        if f"scripts/{entrypoint.name}" not in declared_members:
            raise RuntimeReleaseError(
                "the executing M8M entrypoint is not declared by the pinned runtime release"
            )
    executing_lock = _runtime_lock(manifest)
    assert_product_distribution_lock(product_distributions, manifest["dependencies"])
    if run_mode == "resume":
        if not run_lock_path.is_file():
            raise RuntimeReleaseError("resume is missing its pinned M8M runtime lock")
        pinned = _read_lock(run_lock_path, label="run runtime lock")
        if not _lock_matches(pinned, executing_lock):
            raise RuntimeReleaseError(
                "resume attempted with a runtime different from the run's pinned M8M runtime"
            )
        return executing_lock
    if harness_lock_path.is_file():
        declared = _read_lock(harness_lock_path, label="workflow runtime lock")
        if not _lock_matches(declared, executing_lock):
            raise RuntimeReleaseError(
                "fresh execution runtime does not match the workflow's pinned M8M runtime"
            )
    if run_lock_path.is_file():
        existing = _read_lock(run_lock_path, label="run runtime lock")
        if not _lock_matches(existing, executing_lock):
            raise RuntimeReleaseError("fresh run already has a different pinned M8M runtime")
    else:
        _write_json(run_lock_path, executing_lock)
    return executing_lock


def _argument_value(argv: Sequence[str], names: Iterable[str]) -> str | None:
    accepted = tuple(names)
    for index, value in enumerate(argv):
        for name in accepted:
            if value == name and index + 1 < len(argv):
                return argv[index + 1]
            prefix = f"{name}="
            if value.startswith(prefix):
                return value[len(prefix) :]
    return None


def resolve_runtime_manifest(harness: Path, argv: Sequence[str]) -> Path:
    root = harness.resolve()
    run_value = _argument_value(argv, ("--run-dir", "--output", "--goal-dir"))
    lock: dict[str, Any]
    if run_value and (Path(run_value).resolve() / RUNTIME_LOCK_FILENAME).is_file():
        lock = _read_lock(
            Path(run_value).resolve() / RUNTIME_LOCK_FILENAME,
            label="run runtime lock",
        )
    else:
        lock = _read_lock(root / "runtime" / "active.json", label="active runtime lock")
    runtime_id = str(lock.get("runtime_id") or "")
    manifest = root / "runtime" / "releases" / runtime_id / "runtime-manifest.json"
    if not manifest.is_file():
        raise RuntimeReleaseError(
            f"pinned M8M runtime release is not installed in the codebase harness: {runtime_id}"
        )
    return manifest


__all__ = [
    "RUNTIME_CLI_ABI",
    "RUNTIME_LOCK_FILENAME",
    "RUNTIME_MANIFEST_ENV",
    "RUNTIME_NAME",
    "RUNTIME_RELEASE_SCHEMA",
    "RUNTIME_VERSION",
    "RuntimeReleaseError",
    "bind_runtime_to_run",
    "resolve_runtime_manifest",
    "stage_runtime_release",
    "verify_harness_runtime",
    "verify_runtime_release",
]
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall