cursorfleet 0.1.0__py3-none-any.whl

cursorfleet/git/runner.py

@@ -0,0 +1,135 @@
+"""Read-only git invocation: argv lists, explicit timeouts, no fetch, no mutation.
+
+Hardening for hostile repositories (threat model, "Malicious repository"):
+
+- ``core.fsmonitor`` is forced off, because a repo-local fsmonitor hook would otherwise run
+  an arbitrary program when we call ``git status``.
+- ``--no-optional-locks`` / ``GIT_OPTIONAL_LOCKS=0`` stop ``status`` from refreshing (writing)
+  the index.
+- Inherited ``GIT_DIR``/``GIT_WORK_TREE``/``GIT_INDEX_FILE`` are dropped so a hook context
+  cannot redirect us, and prompts/pagers are disabled.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from cursorfleet.safeexe import find_executable
+
+DEFAULT_TIMEOUT_S = 10.0
+MAX_OUTPUT_BYTES = 8 * 1024 * 1024
+
+_DROP_ENV = (
+    "GIT_DIR",
+    "GIT_WORK_TREE",
+    "GIT_INDEX_FILE",
+    "GIT_OBJECT_DIRECTORY",
+    "GIT_COMMON_DIR",
+    "GIT_NAMESPACE",
+    "GIT_EXTERNAL_DIFF",
+    "GIT_ASKPASS",
+    "GIT_SSH_COMMAND",
+)
+_BASE_ARGS = ("--no-optional-locks", "-c", "core.fsmonitor=false")
+
+
+class GitError(Exception):
+    """Base class for collector failures."""
+
+
+class GitUnavailable(GitError):
+    """The ``git`` executable could not be run."""
+
+
+class NotAGitRepo(GitError):
+    """The path is not inside a git repository."""
+
+
+@dataclass(frozen=True)
+class GitResult:
+    returncode: int
+    stdout: bytes
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+    def text(self) -> str:
+        return self.stdout.decode("utf-8", "replace")
+
+
+def git_env() -> dict[str, str]:
+    env = {k: v for k, v in os.environ.items() if k not in _DROP_ENV}
+    env.update(
+        {
+            "GIT_OPTIONAL_LOCKS": "0",
+            "GIT_TERMINAL_PROMPT": "0",
+            "GIT_PAGER": "cat",
+            "LC_ALL": "C",
+            "LANG": "C",
+        }
+    )
+    return env
+
+
+def run_git(
+    args: Sequence[str], cwd: str, *, timeout: float = DEFAULT_TIMEOUT_S
+) -> GitResult | None:
+    """Run ``git <args>`` in ``cwd``. Returns ``None`` on timeout or OS-level failure.
+
+    Raises :class:`GitUnavailable` only when the executable itself is missing.
+    """
+    exe = find_executable("git")  # never the current directory (hostile repositories)
+    if exe is None:
+        msg = "git executable not found"
+        raise GitUnavailable(msg)
+    argv = [exe, *_BASE_ARGS, *args]
+    try:
+        completed = subprocess.run(  # noqa: S603 - argv list, fixed executable, no shell
+            argv,
+            cwd=cwd,
+            capture_output=True,
+            timeout=timeout,
+            check=False,
+            env=git_env(),
+            stdin=subprocess.DEVNULL,
+        )
+    except FileNotFoundError as exc:
+        if not os.path.isdir(cwd):
+            return None
+        msg = "git executable not found"
+        raise GitUnavailable(msg) from exc
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+    return GitResult(completed.returncode, completed.stdout[:MAX_OUTPUT_BYTES])
+
+
+def git_common_dir(start: str, *, timeout: float = DEFAULT_TIMEOUT_S) -> str:
+    """``git rev-parse --git-common-dir`` from ``start``, absolute and realpath-resolved.
+
+    The contract of ADR 0002; the hook hot path uses an equivalent file walk instead and
+    a contract test compares the two.
+    """
+    start = os.path.realpath(start)
+    result = run_git(["rev-parse", "--git-common-dir"], start, timeout=timeout)
+    if result is None or not result.ok:
+        msg = f"not a git repository (or git failed): {start}"
+        raise NotAGitRepo(msg)
+    value = result.text().strip()
+    if not value:
+        msg = "git returned an empty common dir"
+        raise NotAGitRepo(msg)
+    return os.path.realpath(value if os.path.isabs(value) else os.path.join(start, value))
+
+
+def git_toplevel(start: str, *, timeout: float = DEFAULT_TIMEOUT_S) -> str | None:
+    """``git rev-parse --show-toplevel`` (realpath), or ``None`` for bare repos / non-repos."""
+    real = os.path.realpath(start)
+    result = run_git(["rev-parse", "--show-toplevel"], real, timeout=timeout)
+    if result is None or not result.ok:
+        return None
+    value = result.text().strip()
+    return os.path.realpath(value) if value else None

cursorfleet/git/worktrees.py

@@ -0,0 +1,71 @@
+"""Parse ``git worktree list --porcelain`` output (NUL- or newline-separated)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+MAX_WORKTREES = 500
+
+
+@dataclass(frozen=True)
+class WorktreeEntry:
+    """One record of the porcelain listing (git's own view; nothing is verified here)."""
+
+    path: str
+    head: str | None = None
+    branch: str | None = None  # short name for refs/heads/*, else the ref without ``refs/``
+    detached: bool = False
+    bare: bool = False
+    locked: bool = False
+    prunable: bool = False
+
+
+def _branch_name(ref: str) -> str:
+    if ref.startswith("refs/heads/"):
+        return ref[len("refs/heads/") :]
+    return ref.removeprefix("refs/")
+
+
+def parse_porcelain(text: str, *, nul: bool) -> list[WorktreeEntry]:
+    """Parse porcelain text. ``nul=True`` for ``-z`` output, else newline-separated."""
+    separator = "\0" if nul else "\n"
+    entries: list[WorktreeEntry] = []
+    current: dict[str, str | bool] = {}
+
+    def flush() -> None:
+        path = current.get("path")
+        if isinstance(path, str) and path:
+            head = current.get("head")
+            branch = current.get("branch")
+            entries.append(
+                WorktreeEntry(
+                    path=path,
+                    head=head if isinstance(head, str) and head else None,
+                    branch=branch if isinstance(branch, str) and branch else None,
+                    detached=current.get("detached") is True,
+                    bare=current.get("bare") is True,
+                    locked=current.get("locked") is True,
+                    prunable=current.get("prunable") is True,
+                )
+            )
+        current.clear()
+
+    for line in text.split(separator):
+        if not line:
+            flush()
+            continue
+        key, _, value = line.partition(" ")
+        if key == "worktree":
+            if current:
+                flush()
+            current["path"] = value
+        elif key == "HEAD":
+            current["head"] = value
+        elif key == "branch":
+            current["branch"] = _branch_name(value)
+        elif key in {"bare", "detached", "locked", "prunable"}:
+            current[key] = True  # the optional reason text is free text and is dropped
+        if len(entries) >= MAX_WORKTREES:
+            break
+    flush()
+    return entries[:MAX_WORKTREES]

cursorfleet/safeexe.py

@@ -0,0 +1,70 @@
+"""Locate external programs (``git``, ``cursor``) without trusting the current directory.
+
+``shutil.which`` and ``CreateProcess`` search the current directory first on Windows, and
+a ``PATH`` with an empty or ``.`` entry does the same on POSIX. CursorFleet is routinely run
+inside repositories it does not control, so a repository that ships ``git.exe`` or
+``cursor.cmd`` could otherwise get it executed (security review SR-05). :func:`find_executable`
+searches only absolute ``PATH`` entries that are not the current directory, and returns an
+absolute path, which callers then pass as ``argv[0]``.
+"""
+
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+
+
+def _search_dirs(path_env: str, cwd: str | None) -> list[str]:
+    real_cwd = os.path.normcase(os.path.realpath(cwd)) if cwd else None
+    found: list[str] = []
+    for entry in path_env.split(os.pathsep):
+        entry = entry.strip().strip('"')  # noqa: PLW2901 - normalising the loop value
+        if not entry or entry == os.curdir or not os.path.isabs(entry):
+            continue
+        if os.path.normcase(os.path.realpath(entry)) == real_cwd:
+            continue
+        found.append(entry)
+    return found
+
+
+def _candidate_names(name: str, pathext: str) -> list[str]:
+    if os.name != "nt":
+        return [name]
+    suffixes = [s for s in pathext.split(os.pathsep) if s] or [".EXE", ".CMD", ".BAT", ".COM"]
+    if os.path.splitext(name)[1].upper() in {s.upper() for s in suffixes}:
+        return [name]
+    return [name + s for s in suffixes]
+
+
+@lru_cache(maxsize=32)
+def _lookup(name: str, path_value: str, pathext_value: str, cwd: str | None) -> str | None:
+    for directory in _search_dirs(path_value, cwd):
+        for candidate in _candidate_names(name, pathext_value):
+            full = os.path.join(directory, candidate)
+            if os.path.isfile(full) and os.access(full, os.X_OK):
+                return full
+    return None
+
+
+def find_executable(
+    name: str,
+    *,
+    path_env: str | None = None,
+    pathext: str | None = None,
+    cwd: str | None = None,
+) -> str | None:
+    """Return the absolute path of ``name`` on ``PATH`` or ``None``. Never searches ``cwd``."""
+    if os.path.basename(name) != name:
+        return None  # only bare program names are looked up
+    path_value = os.environ.get("PATH", "") if path_env is None else path_env
+    pathext_value = os.environ.get("PATHEXT", "") if pathext is None else pathext
+    if cwd is None:
+        try:
+            cwd = os.getcwd()
+        except OSError:  # the directory was deleted under us: nothing to exclude
+            cwd = None
+    found = _lookup(name, path_value, pathext_value, cwd)
+    if found is not None and not os.path.isfile(found):
+        _lookup.cache_clear()  # the cached program vanished: search again
+        return _lookup(name, path_value, pathext_value, cwd)
+    return found

cursorfleet/schema_gen.py

@@ -0,0 +1,73 @@
+"""Generate the checked-in JSON Schemas from the Pydantic models.
+
+Usage: ``uv run python scripts/gen_schemas.py [--check]``. ``--check`` exits 1 if
+the files under ``schemas/`` differ from the models (also enforced by a test).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from cursorfleet.config.models import FleetConfig
+from cursorfleet.config.roster import Roster
+from cursorfleet.events.models import Event
+
+DIALECT = "https://json-schema.org/draft/2020-12/schema"
+ID_BASE = "https://raw.githubusercontent.com/M9nx/cursorfleet/main/schemas/"  # identifier only
+
+
+def _from_model(model: type[BaseModel], filename: str, title: str) -> dict[str, Any]:
+    schema = model.model_json_schema(mode="validation")
+    schema["title"] = title
+    return {"$schema": DIALECT, "$id": ID_BASE + filename, **schema}
+
+
+def _policy_placeholder() -> dict[str, Any]:
+    return {
+        "$schema": DIALECT,
+        "$id": ID_BASE + "policy.schema.json",
+        "title": "CursorFleet policy (reserved for v0.2)",
+        "description": (
+            "Placeholder. The policy engine (v0.2 Guard) does not exist in v0.1, so no policy "
+            "file is valid yet: this schema accepts only an empty object. Do not rely on its shape."
+        ),
+        "x-cursorfleet-status": "reserved-for-v0.2",
+        "type": "object",
+        "additionalProperties": False,
+        "properties": {},
+    }
+
+
+def generate_schemas() -> dict[str, dict[str, Any]]:
+    """Return ``{filename: schema}`` for every schema we ship."""
+    return {
+        "config.schema.json": _from_model(FleetConfig, "config.schema.json", "CursorFleet config"),
+        "roster.schema.json": _from_model(Roster, "roster.schema.json", "CursorFleet roster"),
+        "event.schema.json": _from_model(Event, "event.schema.json", "CursorFleet event"),
+        "policy.schema.json": _policy_placeholder(),
+    }
+
+
+def render(schema: dict[str, Any]) -> str:
+    return json.dumps(schema, indent=2, ensure_ascii=False) + "\n"
+
+
+def main(schemas_dir: Path, *, check: bool) -> int:
+    drifted: list[str] = []
+    for name, schema in generate_schemas().items():
+        target = schemas_dir / name
+        text = render(schema)
+        if check:
+            if not target.is_file() or json.loads(target.read_text("utf-8")) != schema:
+                drifted.append(name)
+        else:
+            target.write_text(text, encoding="utf-8")
+    if drifted:
+        sys.stderr.write(f"schema drift: {', '.join(drifted)} (run scripts/gen_schemas.py)\n")
+        return 1
+    return 0

cursorfleet/state/artifact_scan.py

@@ -0,0 +1,309 @@
+"""Read-only scanner turning agent-declared artifacts into self-reported events (ADR 0006).
+
+Artifacts (``<work dir>/<task>/<NN>-<kind>-<role>.md``, schema ``cursorfleet.artifact/1``)
+are the only producer of ``plan.created``, ``handoff.created``, ``blocker.raised`` and
+``context.loaded``. Everything here is SELF-REPORTED and untrusted:
+
+- Only the validated frontmatter fields are kept (task slug, kind, author/target role,
+  ``created``, ``issue_ref``, ``context_refs`` paths). The Markdown body is never stored,
+  hashed, logged or displayed; there are no title or summary fields in the schema.
+- An invalid artifact becomes an :class:`ArtifactIssue` carrying a *fixed* description for
+  its problem code, never the parser's message (which may quote file content). The scan
+  never raises: unreadable, oversized, symlinked and malformed files are reported.
+- The scan never writes, follows symlinks, or reads past the size cap, and stops after
+  ``MAX_ARTIFACT_FILES`` files.
+
+Events derived from records use ``producer=work_artifact``, ``source=self_reported`` and
+``attribution=unknown`` (``author_role`` is spoofable) in the synthetic session
+``work:<task>``. Ids are deterministic (path + frontmatter hash), so rescans and the same
+file appearing in several worktrees dedupe.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import PurePosixPath
+
+from pydantic import ValidationError
+
+from cursorfleet import __version__
+from cursorfleet.events.ids import new_event_id
+from cursorfleet.events.models import Event
+from cursorfleet.state.models import utc
+from cursorfleet.workflow.artifacts import MAX_ARTIFACT_BYTES, validate_artifact_text
+from cursorfleet.workflow.frontmatter import FrontmatterError, parse_frontmatter
+
+DEFAULT_WORK_DIR = ".cursorfleet/work"
+MAX_ARTIFACT_FILES = 2000
+SESSION_PREFIX = "work:"
+
+_MIN_TS = datetime(1971, 1, 1, tzinfo=UTC)
+_MAX_TS = datetime(2200, 1, 1, tzinfo=UTC)
+
+# Fixed, content-free descriptions. The parser's own messages can quote file content.
+PROBLEM_TEXT: dict[str, str] = {
+    "artifact.too_large": "file is larger than the 64 KiB artifact limit",
+    "artifact.frontmatter": "frontmatter is missing or not in the strict subset",
+    "artifact.missing_key": "a required frontmatter key is missing",
+    "artifact.unknown_key": "frontmatter has a key outside the schema",
+    "artifact.schema": "schema is not a supported cursorfleet.artifact version",
+    "artifact.kind": "kind is not plan/handoff/blocker/context",
+    "artifact.location": "artifact must live in <work dir>/<task>/<file>.md",
+    "artifact.task": "task is not a slug equal to the directory name",
+    "artifact.author_role": "author_role is not a safe id",
+    "artifact.to_role": "to_role is not a safe id",
+    "artifact.created": "created is not an ISO 8601 timestamp in a sane range",
+    "artifact.issue_ref": "issue_ref is not short printable text",
+    "artifact.context_refs": "context_refs is not a list of workspace-relative paths",
+    "artifact.symlink": "symlinks are not read",
+    "artifact.unreadable": "file could not be read",
+    "artifact.encoding": "file is not valid UTF-8",
+    "artifact.too_many": f"scan stopped after {MAX_ARTIFACT_FILES} files",
+    "artifact.event_invalid": "frontmatter values do not fit the event model",
+}
+
+
+@dataclass(frozen=True)
+class ArtifactRecord:
+    """Validated frontmatter of one artifact. Self-reported; the body is not kept."""
+
+    path: str  # relative to the work dir, "/" separated: "<task>/<file>.md"
+    task: str
+    kind: str  # plan.created | handoff.created | blocker.raised | context.loaded
+    author_role: str
+    created: datetime
+    to_role: str | None = None
+    issue_ref: str | None = None
+    context_refs: tuple[str, ...] = ()
+    fingerprint: str = ""  # sha256(path + frontmatter)[:16]
+
+    @property
+    def session_id(self) -> str:
+        return SESSION_PREFIX + self.task
+
+
+@dataclass(frozen=True)
+class ArtifactIssue:
+    path: str  # relative to the work dir
+    code: str
+
+    @property
+    def message(self) -> str:
+        return PROBLEM_TEXT.get(self.code, "artifact problem")
+
+
+@dataclass
+class ArtifactScan:
+    records: list[ArtifactRecord] = field(default_factory=list)
+    issues: list[ArtifactIssue] = field(default_factory=list)
+    events: list[Event] = field(default_factory=list)  # self-reported, one per valid record
+    files: int = 0  # candidate files examined
+
+
+def record_to_event(record: ArtifactRecord) -> Event | None:
+    """Map a record onto the event model; ``None`` if the values do not fit it."""
+    millis = int(record.created.timestamp() * 1000)
+    seed = hashlib.sha256(f"{record.path}\0{record.fingerprint}".encode()).digest()[:10]
+    refs: list[dict[str, str]] = [{"path": ref} for ref in record.context_refs]
+    data: dict[str, object] = {
+        "event_id": new_event_id(millis, seed),
+        "ts": record.created.isoformat(),
+        "producer": "work_artifact",
+        "producer_version": __version__,
+        "source": "self_reported",
+        "kind": record.kind,
+        "session_id": record.session_id,
+        "agent_role": record.author_role,
+        "attribution": "unknown",
+        "paths": refs,
+    }
+    if record.issue_ref is not None:
+        data["issue_ref"] = record.issue_ref
+    try:
+        return Event.model_validate(data)
+    except ValidationError:
+        # issue_ref allows more characters than the event field does: retry without it.
+        data.pop("issue_ref", None)
+        try:
+            return Event.model_validate(data)
+        except ValidationError:
+            return None
+
+
+def _parse_created(value: object) -> datetime | None:
+    if not isinstance(value, str):
+        return None
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    parsed = utc(parsed)
+    return parsed if _MIN_TS <= parsed <= _MAX_TS else None
+
+
+def _record_from_text(text: str, rel: str) -> ArtifactRecord | list[str]:
+    """Validate ``text``; return the record, or the list of problem codes."""
+    problems = [p.code for p in validate_artifact_text(text, rel)]
+    if problems:
+        return sorted(set(problems))
+    try:
+        doc = parse_frontmatter(text)
+    except FrontmatterError:  # pragma: no cover - validate_artifact_text already parsed it
+        return ["artifact.frontmatter"]
+    meta = doc.meta
+    created = _parse_created(meta.get("created"))
+    if created is None:
+        return ["artifact.created"]
+    refs_raw = meta.get("context_refs", [])
+    refs = tuple(r for r in refs_raw if isinstance(r, str)) if isinstance(refs_raw, list) else ()
+    to_role = meta.get("to_role")
+    issue = meta.get("issue_ref")
+    # Fingerprint covers the frontmatter only, so editing the body never changes identity.
+    frontmatter_only = text.replace("\r\n", "\n").split("\n---", 2)[0]
+    fingerprint = hashlib.sha256(f"{rel}\0{frontmatter_only}".encode()).hexdigest()[:16]
+    return ArtifactRecord(
+        path=rel,
+        task=str(meta["task"]),
+        kind=str(meta["kind"]),
+        author_role=str(meta["author_role"]),
+        created=created,
+        to_role=to_role if isinstance(to_role, str) else None,
+        issue_ref=issue if isinstance(issue, str) else None,
+        context_refs=refs,
+        fingerprint=fingerprint,
+    )
+
+
+_CacheValue = tuple[int, int, "ArtifactRecord | list[str]"]
+
+
+class ArtifactScanner:
+    """Scans the work dir of one or more worktree roots; caches by ``(mtime_ns, size)``."""
+
+    def __init__(self, work_rel: str = DEFAULT_WORK_DIR) -> None:
+        self._work_rel = work_rel
+        self._cache: dict[str, _CacheValue] = {}
+
+    def scan(self, roots: Sequence[str]) -> ArtifactScan:
+        """Scan every root (first one wins on duplicates). Never raises."""
+        result = ArtifactScan()
+        seen: set[tuple[str, str]] = set()
+        live: set[str] = set()
+        for root in dict.fromkeys(roots):
+            try:
+                self._scan_root(root, result, seen, live)
+            except OSError:
+                continue
+            if result.files > MAX_ARTIFACT_FILES:
+                break
+        for stale in set(self._cache) - live:
+            del self._cache[stale]
+        result.records.sort(key=lambda r: (r.created, r.path))
+        for record in result.records:
+            event = record_to_event(record)
+            if event is None:
+                result.issues.append(ArtifactIssue(record.path, "artifact.event_invalid"))
+            else:
+                result.events.append(event)
+        return result
+
+    # ------------------------------------------------------------------ internals
+
+    def _scan_root(
+        self, root: str, result: ArtifactScan, seen: set[tuple[str, str]], live: set[str]
+    ) -> None:
+        base = os.path.join(root, *self._work_rel.split("/"))
+        if not os.path.isdir(base) or os.path.islink(base):
+            return
+        for rel, full in self._candidates(base, result):
+            if result.files >= MAX_ARTIFACT_FILES:
+                result.issues.append(ArtifactIssue(rel, "artifact.too_many"))
+                result.files += 1  # sentinel: stop the outer loop
+                return
+            result.files += 1
+            live.add(full)
+            outcome = self._load(full, rel)
+            if isinstance(outcome, list):
+                result.issues.extend(ArtifactIssue(rel, code) for code in outcome)
+            elif (outcome.path, outcome.fingerprint) not in seen:
+                seen.add((outcome.path, outcome.fingerprint))
+                result.records.append(outcome)
+
+    def _candidates(self, base: str, result: ArtifactScan) -> list[tuple[str, str]]:
+        found: list[tuple[str, str]] = []
+        for entry in sorted(_scandir(base), key=lambda e: e.name):
+            if entry.is_symlink():
+                result.issues.append(ArtifactIssue(entry.name, "artifact.symlink"))
+                continue
+            if entry.is_file(follow_symlinks=False):
+                if entry.name.endswith(".md") and entry.name != "AGENTS.md":
+                    found.append((entry.name, entry.path))  # not under a task directory
+                continue
+            if not entry.is_dir(follow_symlinks=False):
+                continue
+            for inner in sorted(_scandir(entry.path), key=lambda e: e.name):
+                rel = str(PurePosixPath(entry.name, inner.name))
+                if not inner.name.endswith(".md") or inner.name == "AGENTS.md":
+                    continue
+                if inner.is_symlink():
+                    result.issues.append(ArtifactIssue(rel, "artifact.symlink"))
+                elif inner.is_file(follow_symlinks=False):
+                    found.append((rel, inner.path))
+        return found
+
+    def _load(self, full: str, rel: str) -> ArtifactRecord | list[str]:
+        try:
+            st = os.stat(full, follow_symlinks=False)
+        except OSError:
+            return ["artifact.unreadable"]
+        cached = self._cache.get(full)
+        if cached is not None and cached[0] == st.st_mtime_ns and cached[1] == st.st_size:
+            return cached[2]
+        outcome = self._read(full, rel, st.st_size)
+        self._cache[full] = (st.st_mtime_ns, st.st_size, outcome)
+        return outcome
+
+    @staticmethod
+    def _read(full: str, rel: str, size: int) -> ArtifactRecord | list[str]:
+        if size > MAX_ARTIFACT_BYTES:
+            return ["artifact.too_large"]
+        # O_NOFOLLOW: a file swapped for a symlink after the scan's lstat is refused (ELOOP).
+        flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
+        try:
+            fd = os.open(full, flags)
+            with os.fdopen(fd, "rb") as handle:
+                raw = handle.read(MAX_ARTIFACT_BYTES + 1)
+        except OSError:
+            return ["artifact.unreadable"]
+        try:
+            text = raw.decode("utf-8")
+        except UnicodeDecodeError:
+            return ["artifact.encoding"]
+        return _record_from_text(text, rel)
+
+
+def _scandir(path: str) -> list[os.DirEntry[str]]:
+    try:
+        with os.scandir(path) as it:
+            return list(it)
+    except OSError:
+        return []
+
+
+__all__ = [
+    "DEFAULT_WORK_DIR",
+    "MAX_ARTIFACT_FILES",
+    "PROBLEM_TEXT",
+    "SESSION_PREFIX",
+    "ArtifactIssue",
+    "ArtifactRecord",
+    "ArtifactScan",
+    "ArtifactScanner",
+    "record_to_event",
+]