agent-hitch 0.2.16 → 0.2.17

package/integrations/harbor/hitch_build_inputs.py

@@ -0,0 +1,213 @@
+"""Conservative, content-addressed local Docker build inputs.
+
+Unsupported inputs keep Harbor's original build path. Snapshot before hashing:
+the builder consumes exactly the bytes named by the key, never a mutable source
+directory. Task names, runtime mounts and ownership labels are not build inputs.
+"""
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager
+import hashlib
+import json
+import os
+import re
+import shutil
+import stat
+from pathlib import Path
+
+
+class UnsupportedBuild(ValueError):
+    pass
+
+
+@contextmanager
+def read_context():
+    # Docker can ignore unreadable entries using .dockerignore; our complete
+    # snapshot cannot. Only source I/O becomes fallback, not destination errors.
+    try:
+        yield
+    except OSError as error:
+        raise UnsupportedBuild("context-read") from error
+
+
+def digest(value):
+    return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def build_spec(service, default_platform):
+    build = service.get("build")
+    if not isinstance(build, dict) or set(build) - {"context", "dockerfile", "args", "target", "labels"}:
+        raise UnsupportedBuild("build-options")
+    if service.get("pull_policy") not in (None, "build", "missing", "if_not_present", "never"):
+        raise UnsupportedBuild("pull-policy")
+    context = build.get("context")
+    dockerfile = build.get("dockerfile", "Dockerfile")
+    # Resolved config re-escapes paths too, so an existing '$$' sibling could
+    # otherwise be mistaken for Compose's actual '$' input tree or Dockerfile.
+    if any(isinstance(value, str) and "$" in value for value in (context, dockerfile)):
+        raise UnsupportedBuild("escaped-build-paths")
+    if not isinstance(context, str) or not Path(context).is_absolute():
+        raise UnsupportedBuild("nonlocal-context")
+    source = Path(context)
+    if source.resolve() != source or not source.is_dir():
+        raise UnsupportedBuild("context-path")
+    if (not isinstance(dockerfile, str) or not dockerfile or "\\" in dockerfile
+            or Path(dockerfile).is_absolute() or any(p in ("", ".", "..") for p in dockerfile.split("/"))):
+        raise UnsupportedBuild("dockerfile-path")
+    platform = service.get("platform") or default_platform
+    if platform not in ("linux/amd64", "linux/arm64"):
+        raise UnsupportedBuild("platform")
+    args, labels = build.get("args", {}), build.get("labels", {})
+    for values in (args, labels):
+        if not isinstance(values, dict) or any(not isinstance(k, str) or not k or not isinstance(v, str) for k, v in values.items()):
+            raise UnsupportedBuild("unresolved-build-values")
+        # Compose config serializes literal dollars differently from its
+        # execution plan. Keep native interpolation/escaping for such inputs.
+        if any("$" in key or "$" in value for key, value in values.items()):
+            raise UnsupportedBuild("escaped-build-values")
+    if "BUILDKIT_SYNTAX" in args:
+        # This reserved argument selects a frontend just like a # syntax
+        # directive; even pinned frontends can introduce untracked inputs.
+        raise UnsupportedBuild("custom-frontend")
+    if "io.hitch.prepared-key" in labels:
+        raise UnsupportedBuild("reserved-cache-label")
+    target = build.get("target")
+    if target is not None and (not isinstance(target, str) or not re.fullmatch(r"[a-zA-Z0-9_.-]+", target)):
+        raise UnsupportedBuild("build-target")
+    return source, {"dockerfile": dockerfile, "platform": platform, "args": args, "labels": labels, "target": target}
+
+
+def pinned_dockerfile(source):
+    with read_context():
+        if source.stat().st_size > 1024 * 1024:
+            raise UnsupportedBuild("dockerfile-size")
+        try:
+            content = source.read_text(encoding="utf-8")
+        except UnicodeDecodeError as error:
+            # Docker can accept non-UTF-8 comment bytes. Preserve its parser
+            # and the original input instead of decoding lossily for caching.
+            raise UnsupportedBuild("dockerfile-encoding") from error
+    # Restrict parser directives and syntax we cannot unambiguously inspect.
+    if "\0" in content or "<<" in content or re.search(r"(?im)^\s*#\s*escape\s*=", content):
+        raise UnsupportedBuild("dockerfile-syntax")
+    if re.search(r"(?im)^\s*#\s*syntax\s*=", content):
+        # Even a pinned custom frontend can introduce untracked input sources.
+        raise UnsupportedBuild("custom-frontend")
+    stages, bases = set(), []
+    logical = re.sub(r"\\\r?\n", " ", "\n".join(line for line in content.splitlines() if not line.lstrip().startswith("#")))
+    for line in logical.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        tokens = re.split(r"\s+", line, maxsplit=1)
+        instruction, body = tokens[0], tokens[1] if len(tokens) == 2 else ""
+        instruction = instruction.upper()
+        if instruction not in {"FROM", "RUN", "CMD", "LABEL", "MAINTAINER", "EXPOSE", "ENV", "ENTRYPOINT", "VOLUME", "USER", "WORKDIR", "ARG", "STOPSIGNAL", "HEALTHCHECK", "SHELL", "COPY", "ADD", "ONBUILD"}:
+            raise UnsupportedBuild("dockerfile-instruction")
+        if instruction == "FROM":
+            match = re.fullmatch(r"(?:--platform=(linux/(?:amd64|arm64))\s+)?(\S+)(?:\s+[Aa][Ss]\s+([\w.-]+))?", body.strip())
+            if not match:
+                raise UnsupportedBuild("dynamic-base")
+            if match[1]:
+                raise UnsupportedBuild("per-stage-platform")
+            base, alias = match[2], match[3]
+            if base.lower() not in stages and base != "scratch":
+                if not re.fullmatch(r"[^\s$]+@sha256:[a-f0-9]{64}", base):
+                    raise UnsupportedBuild("mutable-base")
+                bases.append(base)
+            if alias:
+                stages.add(alias.lower())
+        elif instruction == "ADD":
+            # ADD can read remote URLs or Git trees, independent of the context.
+            raise UnsupportedBuild("add-input")
+        elif instruction == "COPY":
+            if "--from" in body and not re.search(r"--from=\S+", body):
+                raise UnsupportedBuild("copy-source-syntax")
+            for external in re.findall(r"--from=(\S+)", body):
+                if external.lower() not in stages and not external.isdigit() and not re.fullmatch(r"[^\s$]+@sha256:[a-f0-9]{64}", external):
+                    raise UnsupportedBuild("mutable-copy-source")
+        elif instruction == "RUN" and re.search(r"--(?:mount|device|security)=", body):
+            raise UnsupportedBuild("external-run-input")
+        elif instruction == "ONBUILD":
+            raise UnsupportedBuild("onbuild-input")
+    if not re.search(r"(?im)^\s*FROM\s", logical):
+        raise UnsupportedBuild("missing-base")
+    return sorted(set(bases))
+
+
+async def snapshot_context(source, target):
+    listxattr = getattr(os, "listxattr", None)
+    if not callable(listxattr):
+        raise UnsupportedBuild("context-xattr-inspection")
+    entries = []
+
+    async def copy(current, destination, relative):
+        with read_context():
+            info = current.lstat()
+        mode = stat.S_IMODE(info.st_mode)
+        try:
+            attributes = listxattr(current, follow_symlinks=False)
+        except (OSError, NotImplementedError) as error:
+            # An uninspectable context must use the original build path; never
+            # assume unsupported metadata is absent from the cache identity.
+            raise UnsupportedBuild("context-xattr-inspection") from error
+        if attributes:
+            raise UnsupportedBuild("context-xattrs")
+        if stat.S_ISDIR(info.st_mode):
+            destination.mkdir(mode=0o700)
+            with read_context():
+                children = sorted(current.iterdir(), key=lambda p: os.fsencode(p.name))
+            entries.append([relative, "directory", mode])
+            for child in children:
+                await copy(child, destination / child.name, f"{relative}/{child.name}" if relative else child.name)
+            with read_context():
+                if [p.name for p in children] != sorted(os.listdir(current), key=os.fsencode):
+                    raise UnsupportedBuild("context-changed")
+            os.chmod(destination, mode)
+            os.utime(destination, ns=(info.st_atime_ns, info.st_mtime_ns))
+        elif stat.S_ISREG(info.st_mode):
+            if info.st_nlink != 1:
+                # COPY can preserve link relationships. Separate copies and a
+                # byte-only identity cannot represent them, even on a hit.
+                raise UnsupportedBuild("context-hardlinks")
+            checksum = hashlib.sha256()
+            with read_context():
+                fd = os.open(current, os.O_RDONLY | os.O_NOFOLLOW)
+            with os.fdopen(fd, "rb") as reader, destination.open("xb") as writer:
+                with read_context():
+                    before = os.fstat(reader.fileno())
+                if (before.st_ino, before.st_dev) != (info.st_ino, info.st_dev):
+                    raise UnsupportedBuild("context-changed")
+                while True:
+                    with read_context():
+                        chunk = reader.read(1024 * 1024)
+                    if not chunk:
+                        break
+                    checksum.update(chunk)
+                    writer.write(chunk)
+                    await asyncio.sleep(0)
+                with read_context():
+                    after = os.fstat(reader.fileno())
+                if (before.st_size, before.st_mtime_ns, before.st_ctime_ns) != (after.st_size, after.st_mtime_ns, after.st_ctime_ns):
+                    raise UnsupportedBuild("context-changed")
+            os.chmod(destination, mode)
+            os.utime(destination, ns=(info.st_atime_ns, info.st_mtime_ns))
+            entries.append([relative, "file", mode, checksum.hexdigest()])
+        else:
+            raise UnsupportedBuild("special-context-entry")
+        await asyncio.sleep(0)
+
+    await copy(source, target, "")
+    return digest(entries)
+
+
+def remove_snapshot(directory):
+    # Source modes may be read-only. Never follow a symlink while cleaning up.
+    for base, directories, _ in os.walk(directory, followlinks=False):
+        os.chmod(base, 0o700)
+        for child in directories:
+            candidate = Path(base) / child
+            if not candidate.is_symlink():
+                os.chmod(candidate, 0o700)
+    shutil.rmtree(directory)

package/integrations/harbor/hitch_build_process.py

@@ -0,0 +1,126 @@
+"""Supervise one Docker command across loss of its Harbor parent.
+
+The parent owns stdin's write end and sends one byte only after both output
+pipes close. EOF without that handshake means cancellation or parent death.
+Inherited cache locks remain held here until the command group is terminated.
+This file deliberately depends only on the Python standard library.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import signal
+import sys
+import time
+
+
+def group_has_live_members(pgid):
+    try:
+        os.killpg(pgid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        # macOS can return EPERM for a group awaiting zombie reaping. A real
+        # permission failure also cannot establish that its members exited.
+        return True
+    if sys.platform != "linux":
+        return True
+    # An orphan zombie can remain until init reaps it, but cannot hold files
+    # or execute. A live D-state helper, however, can outlast SIGKILL.
+    try:
+        with os.scandir("/proc") as entries:
+            for entry in entries:
+                if not entry.name.isdecimal():
+                    continue
+                try:
+                    with open(f"{entry.path}/stat") as stream:
+                        fields = stream.read().rpartition(")")[2].split()
+                except (FileNotFoundError, ProcessLookupError):
+                    continue
+                if int(fields[2]) == pgid and fields[0] not in ("Z", "X"):
+                    return True
+    except (OSError, ValueError, IndexError):
+        # Failed observation cannot authorize release of build ownership.
+        return True
+    return False
+
+
+async def stop_group(process):
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        await process.wait()
+        return
+    except PermissionError:
+        pass
+    deadline = time.monotonic() + 5
+    while time.monotonic() < deadline:
+        try:
+            os.killpg(process.pid, 0)
+        except ProcessLookupError:
+            break
+        except PermissionError:
+            pass
+        await asyncio.sleep(0.02)
+    else:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except (ProcessLookupError, PermissionError):
+            pass
+    await process.wait()
+    while group_has_live_members(process.pid):
+        await asyncio.sleep(0.05)
+
+
+async def supervise(command):
+    loop = asyncio.get_running_loop()
+    interrupted = asyncio.Event()
+    for signum in (signal.SIGTERM, signal.SIGINT):
+        loop.add_signal_handler(signum, interrupted.set)
+    reader = asyncio.StreamReader()
+    transport, _ = await loop.connect_read_pipe(lambda: asyncio.StreamReaderProtocol(reader), sys.stdin.buffer)
+    process = None
+    pending = []
+    try:
+        # The liveness pipe and inherited locks belong to this supervisor only;
+        # Docker and its plugins receive neither, including through stdin.
+        process = await asyncio.create_subprocess_exec(*command, stdin=asyncio.subprocess.DEVNULL, start_new_session=True)
+        # Release our copies of the output pipes while keeping Python's
+        # streams valid. Buffered output or shutdown diagnostics must not
+        # replace the command's exit status with a stream-flush failure.
+        with open(os.devnull, "wb") as sink:
+            os.dup2(sink.fileno(), sys.stdout.fileno())
+            os.dup2(sink.fileno(), sys.stderr.fileno())
+        exited = asyncio.create_task(process.wait())
+        control = asyncio.create_task(reader.read(1))
+        stopped = asyncio.create_task(interrupted.wait())
+        pending = [exited, control, stopped]
+        acknowledged = False
+        while True:
+            watched = [control, stopped] if exited.done() and not acknowledged else [exited, control, stopped]
+            done, _ = await asyncio.wait(watched, return_when=asyncio.FIRST_COMPLETED)
+            if stopped in done:
+                return 125
+            if control in done:
+                if control.result() != b"1" or acknowledged:
+                    return 125
+                acknowledged = True
+                control = asyncio.create_task(reader.read(1))
+                pending.append(control)
+            if acknowledged and exited.done():
+                code = exited.result()
+                return code if code >= 0 else 128 - code
+    finally:
+        # A successful leader and closed output pipes do not prove that a
+        # plugin's silent helper stopped. Reclaim the group on every exit.
+        if process is not None:
+            await stop_group(process)
+        for task in pending:
+            if not task.done():
+                task.cancel()
+        await asyncio.gather(*pending, return_exceptions=True)
+        transport.close()
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(supervise(sys.argv[1:])))

package/integrations/harbor/hitch_compose_preparation.py

@@ -0,0 +1,274 @@
+"""Prepare immutable images and Harbor's own keepalive without pooling tasks."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import tempfile
+
+import yaml
+
+from hitch_build_inputs import UnsupportedBuild, build_spec, digest, pinned_dockerfile
+from hitch_image_cache import ImagePreparationCache, atomic_json, docker, image_matches_platform
+
+_DEFAULT_COMMAND = ["sh", "-c", "sleep infinity"]
+_MANAGED_COMMAND = ["sh", "-c", 'trap \'kill "$child"; wait "$child"; exit 0\' TERM INT; sleep infinity & child=$!; wait "$child"']
+_LIFECYCLE_FIELDS = ("init", "stop_signal", "stop_grace_period", "pre_stop")
+_RUNTIME_PLATFORM_LABEL = "io.hitch.preparation.default-platform"
+
+
+def compose_document(output):
+    # Harbor merges stderr into stdout. Benign Compose interpolation warnings
+    # may precede the document; only accept a complete trailing JSON object.
+    lines = output.splitlines(keepends=True)
+    for index, line in enumerate(lines):
+        if line.lstrip().startswith("{"):
+            try:
+                document = json.loads("".join(lines[index:]))
+                if isinstance(document, dict):
+                    return document
+            except ValueError:
+                pass
+    raise UnsupportedBuild("compose-config-output")
+
+
+def compose_services(output):
+    services = compose_document(output).get("services")
+    if not isinstance(services, dict):
+        raise UnsupportedBuild("compose-config-output")
+    return services
+
+
+def resolved_build_platforms(builds, output):
+    # The project .env participates in build defaults without appearing in
+    # service config or the parent's process environment. Ask Compose itself.
+    targets = compose_document(output).get("target")
+    if not isinstance(targets, dict) or set(targets) != set(builds):
+        raise UnsupportedBuild("compose-build-plan")
+    resolved = {}
+    for name, service in builds.items():
+        target = targets[name]
+        if not isinstance(target, dict):
+            raise UnsupportedBuild("compose-build-plan")
+        platforms = target.get("platforms", [])
+        if not isinstance(platforms, list) or len(platforms) > 1 or any(p not in ("linux/amd64", "linux/arm64") for p in platforms):
+            raise UnsupportedBuild("compose-build-platform")
+        resolved[name] = {**service, "platform": platforms[0]} if platforms else service
+    return resolved
+
+
+def image_tag_key(reference):
+    # Compare Compose-resolved names using Docker's familiar-name defaults.
+    # Digest references are not mutable build tags. Keep their identity intact.
+    if "@" in reference:
+        return reference
+    registry, separator, repository = reference.partition("/")
+    if not separator or (registry != "localhost" and "." not in registry
+                         and ":" not in registry and registry == registry.lower()):
+        registry, repository = "docker.io", reference
+    if registry == "index.docker.io":
+        registry = "docker.io"
+    if registry == "docker.io" and "/" not in repository:
+        repository = "library/" + repository
+    if ":" not in repository.rsplit("/", 1)[-1]:
+        repository += ":latest"
+    return f"{registry}/{repository}"
+
+
+def refreshes_latest(reference, policy):
+    return policy not in ("never", "build") and image_tag_key(reference).endswith(":latest")
+
+
+def require_independent_build_images(services):
+    references = {}
+    unnamed_build = False
+    image_only = False
+    for service in services.values():
+        builds = bool(service.get("build"))
+        reference = service.get("image")
+        if reference:
+            references.setdefault(image_tag_key(reference), []).append(builds)
+        elif builds:
+            unnamed_build = True
+        for mount in service.get("volumes") or []:
+            if isinstance(mount, dict) and mount.get("type") == "image":
+                source = mount.get("source")
+                if not isinstance(source, str) or not source:
+                    raise UnsupportedBuild("image-mount-source")
+                references.setdefault(image_tag_key(source), []).append(False)
+        if not builds:
+            image_only = True
+    # Cached builds publish private tags, not Compose's shared mutable names.
+    # Leave tag publication, pull policy and competing producers to Compose.
+    if any(len(uses) > 1 and any(uses) for uses in references.values()):
+        raise UnsupportedBuild("shared-build-image")
+    # Any explicitly named service can consume or overwrite a generated tag,
+    # including another builder. Do not guess Compose's project-name rules.
+    # All-unnamed builders remain independent: service names are unique.
+    if unnamed_build and (references or image_only):
+        raise UnsupportedBuild("implicit-build-image")
+
+
+class ComposePreparation:
+    def __init__(self, environment, cache_directory=None, build_slots=2, managed_keepalive=False):
+        self.environment = environment
+        self.cache_directory, self.build_slots = cache_directory, build_slots
+        self.managed_keepalive = managed_keepalive
+        self.images = {}
+        self.overlay = {}
+        self.path = None
+        self.temporary = None
+        self.receipts = []
+        self.force_build = False
+        self.runtime_prepared = False
+
+    def reset(self, force_build):
+        if self.temporary is not None:
+            self.temporary.cleanup()
+        self.images, self.overlay, self.receipts = {}, {}, []
+        self.path, self.temporary = None, None
+        self.runtime_prepared, self.force_build = False, force_build
+        if force_build and self.cache_directory:
+            self.record({"event": "bypass", "reason": "force-build"})
+
+    async def build(self, run):
+        if not self.cache_directory or self.force_build:
+            return None
+        env = self.environment
+        cache = ImagePreparationCache(self.cache_directory, env._compose_env_vars(), self.build_slots)
+        result = await run(["config", "--format", "json"])
+        try:
+            services = compose_services(result.stdout)
+            builds = {name: value for name, value in services.items() if value.get("build")}
+            if not builds:
+                return result.model_copy(update={"stdout": "", "stderr": ""})
+            # A composition with unsupported inputs uses its original build path
+            # as a whole, including inter-service dependencies and extra contexts.
+            require_independent_build_images(services)
+            # Preserve documented latest refresh semantics across Compose
+            # versions. Leave the native choice of local or pulled image to up.
+            if any(service.get("image") and refreshes_latest(service["image"], service.get("pull_policy"))
+                   for service in builds.values()):
+                raise UnsupportedBuild("refreshable-build-image")
+            plan = await run(["build", "--print"], check=False)
+            if plan.return_code != 0:
+                # Older Compose versions and conflicting defaults retain their
+                # native build behavior, including the original error handling.
+                raise UnsupportedBuild("compose-build-plan")
+            builds = resolved_build_platforms(builds, plan.stdout)
+            daemon = await cache.identity()
+            for service in builds.values():
+                context, spec = build_spec(service, cache.env.get("DOCKER_DEFAULT_PLATFORM") or daemon["platform"])
+                pinned_dockerfile(context / spec["dockerfile"])
+            prepared = {name: await cache.prepare(value) for name, value in builds.items()}
+        except UnsupportedBuild as error:
+            self.record({"event": "fallback", "reason": str(error)})
+            return None
+        for name, receipt in prepared.items():
+            self.images[name] = receipt["image"]
+            self.overlay[name] = {"image": receipt["image"], "build": "__RESET__", "pull_policy": "never"}
+            self.record({"event": "image", "service": name, **receipt})
+        if prepared:
+            self.write_overlay()
+        return result.model_copy(update={"stdout": "", "stderr": ""})
+
+    async def runtime(self, run):
+        if self.runtime_prepared or not self.managed_keepalive:
+            return
+        self.runtime_prepared = True
+        env = self.environment
+        if getattr(env, "_is_windows_container", False) or self.custom_keepalive():
+            return
+        # Resolve dotenv defaults through Compose itself. A config-only label
+        # yields an unambiguous JSON value even when other environment values
+        # contain newlines. This temporary probe never reaches container up.
+        with tempfile.TemporaryDirectory(prefix="hitch-compose-platform-") as directory:
+            probe = Path(directory) / "compose.json"
+            probe.write_text(json.dumps({"services": {"main": {"labels": {
+                _RUNTIME_PLATFORM_LABEL: "${DOCKER_DEFAULT_PLATFORM:-}",
+            }}}}))
+            result = await run(["-f", str(probe), "config", "--format", "json"])
+        try:
+            service = compose_services(result.stdout)["main"]
+        except UnsupportedBuild:
+            return
+        platform = service.get("platform") or (service.get("labels") or {}).get(_RUNTIME_PLATFORM_LABEL)
+        if platform not in (None, "", "linux/amd64", "linux/arm64"):
+            return
+        if (service.get("command") != _DEFAULT_COMMAND or service.get("entrypoint")
+                or any(key in service for key in _LIFECYCLE_FIELDS)):
+            return
+        reference = service.get("image") or env._main_image_name
+        policy = service.get("pull_policy")
+        # A successful local inspection says nothing about a replacement image
+        # pulled or rebuilt by up. Compose also refreshes latest under missing.
+        if (policy not in (None, "never", "missing", "if_not_present")
+                or refreshes_latest(reference, policy)):
+            return
+        try:
+            raw = await docker(["image", "inspect", "--format", "{{json .}}", reference],
+                               env=env._compose_env_vars(), timeout=30, check=False)
+            if not raw:
+                return
+            image = json.loads(raw)
+        except (TimeoutError, OSError, ValueError):
+            # Metadata is optional for native startup. The Docker supervisor
+            # has already drained command cleanup before a timeout reaches us.
+            self.record({"event": "fallback", "reason": "keepalive-image-inspection"})
+            return
+        if not isinstance(image, dict) or not isinstance(image.get("Config", {}), dict):
+            return
+        if platform and not image_matches_platform(image, platform):
+            # Compose may pull/select a different variant if its default
+            # local inspection does not match the requested runtime platform.
+            return
+        config = image.get("Config", {})
+        stop_signal = service.get("stop_signal", config.get("StopSignal") or "SIGTERM")
+        if image.get("Os") != "linux" or config.get("Entrypoint") or stop_signal not in ("SIGTERM", "SIGINT", "15", "2"):
+            return
+        self.overlay.setdefault("main", {})["command"] = _MANAGED_COMMAND
+        self.write_overlay()
+        self.record({"event": "managed-keepalive", "service": "main"})
+
+    def custom_keepalive(self):
+        env = self.environment
+        for source in [env._environment_docker_compose_path, *env.extra_docker_compose_paths]:
+            if source.exists():
+                try:
+                    document = yaml.safe_load(source.read_text(encoding="utf-8"))
+                except yaml.YAMLError:
+                    # Compose supports tags such as !reset and !override that
+                    # PyYAML does not. Leave their interpretation to Compose.
+                    return True
+                if document is None:
+                    continue
+                if not isinstance(document, dict) or "include" in document:
+                    return True
+                services = document.get("services") or {}
+                if not isinstance(services, dict):
+                    return True
+                main = services.get("main") or {}
+                # An extended/included definition may explicitly choose even
+                # the default command; we cannot attribute it to Harbor.
+                if not isinstance(main, dict) or any(key in main for key in ("extends", "command", "entrypoint", *_LIFECYCLE_FIELDS)):
+                    return True
+        return False
+
+    def write_overlay(self):
+        if self.temporary is None:
+            self.temporary = tempfile.TemporaryDirectory(prefix="hitch-compose-prepared-")
+            self.path = Path(self.temporary.name) / "compose.yaml"
+        # Compose interpolates '$' even in JSON/YAML list-form commands.
+        content = json.dumps({"services": self.overlay}, sort_keys=True).replace("$", "$$")
+        self.path.write_text(content.replace('"build": "__RESET__"', '"build": !reset null'))
+
+    def record(self, value):
+        self.receipts.append(value)
+        env = self.environment
+        env.logger.info("Hitch image preparation: %s", json.dumps(value, sort_keys=True))
+        # Host-only evidence; do not expose context paths/args/credentials or
+        # mount this cache into candidates, sidecars, or verifier containers.
+        directory = env.trial_paths.trial_dir
+        directory.mkdir(parents=True, exist_ok=True)
+        atomic_json(directory / f"hitch-preparation-{digest(env.session_id)[:16]}.json", {
+            "schema_version": "1", "session_id": env.session_id, "events": self.receipts,
+        })