Skip to content

Frappucc1no/recall-loom / skills/recallloom

recallloom

Flagged

Use when a task involves continuing a project, restoring project context, maintaining file-based project memory, updating current-state summaries, or recording meaningful progress across sessions. Works best for long-horizon, file-based projects and supports research writing, product document collaboration, software project coordination, and broader cross-functional project continuity.

FileKindSize
LICENSEother10.0 KB
NOTICEother190 B
SKILL.mdskill md24.5 KB
managed-assets.jsonconfig1.1 KB
native_commands/README.mdmarkdown1.2 KB
native_commands/claude-code/rl-init.md.tmplother323 B
native_commands/claude-code/rl-resume.md.tmplother290 B
native_commands/claude-code/rl-status.md.tmplother299 B
native_commands/claude-code/rl-validate.md.tmplother277 B
native_commands/gemini-cli/rl-init.toml.tmplother295 B
native_commands/gemini-cli/rl-resume.toml.tmplother262 B
native_commands/gemini-cli/rl-status.toml.tmplother271 B
native_commands/gemini-cli/rl-validate.toml.tmplother249 B
native_commands/opencode/rl-init.md.tmplother286 B
native_commands/opencode/rl-resume.md.tmplother253 B
native_commands/opencode/rl-status.md.tmplother262 B
native_commands/opencode/rl-validate.md.tmplother240 B
package-metadata.jsonconfig1.0 KB
profiles/general-project-continuity.mdmarkdown2.4 KB
profiles/product-doc-collaboration.mdmarkdown2.2 KB
profiles/research-writing.mdmarkdown2.1 KB
profiles/software-project-coordination.mdmarkdown2.8 KB
references/anti-patterns.mdmarkdown2.5 KB
references/contract-registry.jsonconfig7.7 KB
references/contract-schema.jsonconfig7.7 KB
references/file-contracts.mdmarkdown23.4 KB
references/operation-playbooks.mdmarkdown26.5 KB
references/package-support-policy.mdmarkdown9.4 KB
references/profiles.mdmarkdown2.0 KB
references/protocol.mdmarkdown20.5 KB
references/recording-workflow.mdmarkdown9.9 KB
scripts/_common.pyscript87.8 KB
scripts/append_daily_log_entry.pyscript40.4 KB
scripts/archive_logs.pyscript17.6 KB
scripts/commit_context_file.pyscript31.6 KB
scripts/core/__init__.pyscript39 B
scripts/core/bridge/__init__.pyscript30 B
scripts/core/bridge/blocks.pyscript6.9 KB
scripts/core/coldstart/__init__.pyscript26 B
scripts/core/coldstart/sources.pyscript22.4 KB
scripts/core/coldstart/structured.pyscript5.4 KB
scripts/core/continuity/__init__.pyscript34 B
scripts/core/continuity/daily_log.pyscript16.1 KB
scripts/core/continuity/freshness.pyscript15.3 KB
scripts/core/continuity/preflight.pyscript41.0 KB
scripts/core/continuity/quick_summary.pyscript10.9 KB
scripts/core/continuity/workday.pyscript12.3 KB
scripts/core/errors.pyscript838 B
scripts/core/failure/__init__.pyscript47 B
scripts/core/failure/context.pyscript5.6 KB
scripts/core/failure/contracts.pyscript108.6 KB
scripts/core/output/__init__.pyscript35 B
scripts/core/output/confirmation_material.pyscript15.0 KB
scripts/core/output/privacy.pyscript10.5 KB
scripts/core/output/user_status.pyscript5.8 KB
scripts/core/protocol/__init__.pyscript60 B
scripts/core/protocol/contracts.pyscript8.3 KB
scripts/core/protocol/markers.pyscript4.9 KB
scripts/core/protocol/sections.pyscript3.4 KB
scripts/core/protocol/templates.pyscript6.5 KB
scripts/core/provenance/__init__.pyscript67 B
scripts/core/provenance/bindings.pyscript13.2 KB
scripts/core/provenance/evidence.pyscript58.2 KB
scripts/core/provenance/inconsistent_review.pyscript85.6 KB
scripts/core/provenance/receipts.pyscript20.2 KB
scripts/core/provenance/state.pyscript38.0 KB
scripts/core/provenance/store.pyscript43.8 KB
scripts/core/recording/__init__.pyscript1.6 KB
scripts/core/recording/contracts.pyscript31.7 KB
scripts/core/recording/daily_log_append.pyscript30.2 KB
scripts/core/recording/managed_write.pyscript52.8 KB
scripts/core/recording/planner.pyscript20.6 KB
scripts/core/recording/privacy.pyscript1.7 KB
scripts/core/recording/suggestions.pyscript8.6 KB
scripts/core/recording/transaction.pyscript93.3 KB
scripts/core/registry/__init__.pyscript58 B
scripts/core/registry/loader.pyscript18.8 KB
scripts/core/safety/__init__.pyscript30 B
scripts/core/safety/attached_text.pyscript6.9 KB
scripts/core/safety/input_transport.pyscript61.0 KB
scripts/core/safety/prepared_input.pyscript24.4 KB
scripts/core/safety/scratch_residue.pyscript18.8 KB
scripts/core/support/__init__.pyscript53 B
scripts/core/support/cache.pyscript19.4 KB
scripts/core/support/policy.pyscript8.8 KB
scripts/core/trust/__init__.pyscript42 B
scripts/core/trust/state.pyscript4.1 KB
scripts/core/workspace/__init__.pyscript33 B
scripts/core/workspace/atomic_io.pyscript12.2 KB
scripts/core/workspace/runtime.pyscript54.7 KB
scripts/detect_project_root.pyscript3.4 KB
scripts/generate_coldstart_proposal.pyscript7.5 KB
scripts/init_context.pyscript37.8 KB
scripts/install_native_commands.pyscript31.5 KB
scripts/manage_entry_bridge.pyscript20.8 KB
scripts/preflight_context_check.pyscript10.1 KB
scripts/prepare_recovery_promotion.pyscript22.1 KB
scripts/query_continuity.pyscript84.1 KB
scripts/recallloom.pyscript233.7 KB
scripts/recommend_workday.pyscript17.6 KB
scripts/record_recovery_review.pyscript50.9 KB
scripts/remove_context.pyscript13.9 KB
scripts/repair_daily_log_cursor.pyscript33.7 KB
scripts/stage_recovery_proposal.pyscript17.5 KB
scripts/summarize_continuity_status.pyscript43.7 KB
scripts/sync_contract_docs.pyscript11.3 KB
scripts/unlock_write_lock.pyscript8.1 KB
scripts/validate_context.pyscript54.9 KB

scripts/core/safety/prepared_input.py

View on GitHub
"""Prepared file-input containment for mutating helper inputs.

Single owner of the file-level token/path/link/identity safety checks. The
v0.5.0 §7.3 scratch orchestrator (core/safety/input_transport.py, T050-01C)
reuses the additive ``RegularFileIdentity`` / ``lstat_regular_file_identity`` /
``read_stable_regular_file_bytes`` primitives below; the pre-existing helper
validators above are byte-for-byte unchanged and keep their exact behavior.
"""

from __future__ import annotations

from dataclasses import dataclass
import errno
import hashlib
import json
import os
from pathlib import Path
import re
import stat


HELPER_SCRATCH_MARKER_FILENAME = ".recallloom-prepared-input-scratch.json"
HELPER_SCRATCH_MARKER_KIND = "recallloom.prepared_input_scratch.v1"
HELPER_SCRATCH_OWNER = "recallloom-helper"
HELPER_SCRATCH_TOKEN_ENV = "RECALLLOOM_PREPARED_INPUT_TOKEN"
MAX_SCRATCH_MARKER_BYTES = 16 * 1024

_SECRET_EXACT_NAMES = {
    ".env",
    ".env.local",
    ".env.development",
    ".env.production",
    ".npmrc",
    ".pypirc",
    ".netrc",
    "credentials",
    "credentials.json",
    "id_dsa",
    "id_ecdsa",
    "id_ed25519",
    "id_rsa",
}
_SECRET_SUFFIXES = {".key", ".pem", ".p12", ".pfx", ".kdbx"}
_SECRET_SEGMENT_RE = re.compile(
    r"(^|[._-])("
    r"api[_-]?key|auth|credential|credentials|oauth|passwd|password|private[_-]?key|"
    r"secret|secrets|token|tokens"
    r")([._-]|$)",
    re.I,
)

_TRANSCRIPT_EXACT_NAMES = {
    ".bash_history",
    ".fish_history",
    ".python_history",
    ".sqlite_history",
    ".zsh_history",
}
_TRANSCRIPT_SUFFIXES = {".log", ".trace"}
_TRANSCRIPT_SEGMENT_RE = re.compile(
    r"("
    r"agent[_-]?runtime[_-]?log|agent[_-]?log|chat[_-]?history|conversation|"
    r"debug[_-]?dump|debug|dump|runtime[_-]?log|session[_-]?log|shell[_-]?history|"
    r"transcript|trace"
    r")",
    re.I,
)
_IDE_HISTORY_SEGMENTS = {
    ".codex",
    ".continue",
    ".cursor",
    ".idea",
    ".vscode",
    ".windsurf",
}

_RELEASE_ARTIFACT_SEGMENTS = {
    "artifact",
    "artifacts",
    "dist",
    "release",
    "release-artifacts",
    "release_artifacts",
    "releases",
}
_RELEASE_ARTIFACT_SUFFIXES = {
    ".tar",
    ".tgz",
    ".whl",
    ".zip",
}
_RELEASE_ARTIFACT_COMPOUND_SUFFIXES = (".tar.gz", ".tar.bz2", ".tar.xz")


@dataclass(frozen=True)
class PreparedInputSource:
    """A prepared source path that passed deny-first source-file checks."""

    path: Path
    path_ref: str
    path_category: str
    st_dev: int
    st_ino: int
    st_mode: int
    st_nlink: int
    st_size: int
    scratch_root_ref: str | None = None


class PreparedInputSafetyError(Exception):
    """Public-safe prepared-input failure."""

    def __init__(
        self,
        *,
        reason_code: str,
        path_category: str,
        path_ref: str,
        message: str,
        extra: dict[str, object] | None = None,
    ) -> None:
        self.reason_code = reason_code
        self.path_category = path_category
        self.path_ref = path_ref
        self.message = message
        self.extra = dict(extra or {})
        super().__init__(message)

    @property
    def details(self) -> dict[str, object]:
        details: dict[str, object] = {
            "reason_code": self.reason_code,
            "path_category": self.path_category,
            "path_ref": self.path_ref,
            "side_effect": "none",
        }
        details.update(self.extra)
        return details


def helper_scratch_marker_payload(*, token: str) -> dict[str, object]:
    return {
        "kind": HELPER_SCRATCH_MARKER_KIND,
        "owner": HELPER_SCRATCH_OWNER,
        "token": token,
    }


def _path_ref(path: Path | str) -> str:
    return "sha256:" + hashlib.sha256(str(path).encode("utf-8", "surrogateescape")).hexdigest()[:16]


def _safe_path_for_ref(path: Path) -> Path:
    try:
        return path.resolve(strict=False)
    except OSError:
        return path.absolute()


def _safe_resolve_existing(path: Path) -> Path | None:
    try:
        return path.resolve(strict=True)
    except OSError:
        return None


def _is_relative_to(path: Path, base: Path) -> bool:
    try:
        path.relative_to(base)
        return True
    except ValueError:
        return False


def _fail(
    *,
    reason_code: str,
    path_category: str,
    path_ref: str,
    label: str,
    extra: dict[str, object] | None = None,
) -> PreparedInputSafetyError:
    return PreparedInputSafetyError(
        reason_code=reason_code,
        path_category=path_category,
        path_ref=path_ref,
        message=(
            f"Prepared {label} file was refused before reading "
            f"(reason_code={reason_code}, path_category={path_category}, path_ref={path_ref})."
        ),
        extra=extra,
    )


def _path_segments(path: Path) -> list[str]:
    return [part.casefold() for part in path.parts if part not in {path.anchor, ""}]


def _secret_like(path: Path) -> bool:
    for part in _path_segments(path):
        if part in _SECRET_EXACT_NAMES:
            return True
        suffix = Path(part).suffix.casefold()
        if suffix in _SECRET_SUFFIXES:
            return True
        if _SECRET_SEGMENT_RE.search(part):
            return True
    return False


def _transcript_or_runtime_log_like(path: Path) -> bool:
    for part in _path_segments(path):
        if part in _TRANSCRIPT_EXACT_NAMES or part in _IDE_HISTORY_SEGMENTS:
            return True
        suffix = Path(part).suffix.casefold()
        if suffix in _TRANSCRIPT_SUFFIXES:
            return True
        if _TRANSCRIPT_SEGMENT_RE.search(part):
            return True
    return False


def _release_artifact_like(path: Path) -> bool:
    parts = _path_segments(path)
    if any(part in _RELEASE_ARTIFACT_SEGMENTS for part in parts):
        return True
    name = path.name.casefold()
    return name.endswith(_RELEASE_ARTIFACT_COMPOUND_SUFFIXES) or any(
        name.endswith(suffix) for suffix in _RELEASE_ARTIFACT_SUFFIXES
    )


def _version_managed_like(path: Path) -> bool:
    parts = _path_segments(path)
    return any(
        current == "docs" and next_part == "versions"
        for current, next_part in zip(parts, parts[1:])
    )


def _project_relative_path(path: Path, project_root: Path) -> Path | None:
    try:
        return path.relative_to(project_root)
    except ValueError:
        return None


def _managed_project_path_category(
    *,
    resolved_path: Path,
    project_root: Path,
    storage_root: Path,
) -> tuple[str, str] | None:
    storage_root_resolved = _safe_resolve_existing(storage_root) or storage_root.resolve(strict=False)
    if _is_relative_to(resolved_path, storage_root_resolved):
        return "source_path_managed_path", "managed_sidecar"

    rel_path = _project_relative_path(resolved_path, project_root)
    if rel_path is None:
        return None
    parts = rel_path.parts
    if parts and parts[0] in {".recallloom", "recallloom"}:
        return "source_path_managed_path", "managed_sidecar"
    if len(parts) >= 3 and parts[0] == "docs" and parts[1] == "versions":
        return "source_path_version_managed", "version_managed"
    return None


def _read_scratch_marker(marker_path: Path) -> dict[str, object] | None:
    try:
        marker_stat = marker_path.lstat()
    except OSError:
        return None
    if stat.S_ISLNK(marker_stat.st_mode) or not stat.S_ISREG(marker_stat.st_mode):
        return None
    if marker_stat.st_size > MAX_SCRATCH_MARKER_BYTES:
        return None
    try:
        payload = json.loads(marker_path.read_text(encoding="utf-8"))
    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
        return None
    return payload if isinstance(payload, dict) else None


def _scratch_marker_authorizes(
    payload: dict[str, object],
    *,
    input_role: str,
    env: dict[str, str],
) -> bool:
    required_token = env.get(HELPER_SCRATCH_TOKEN_ENV)
    if not isinstance(required_token, str) or len(required_token) < 16:
        return False
    if payload.get("kind") != HELPER_SCRATCH_MARKER_KIND:
        return False
    if payload.get("owner") != HELPER_SCRATCH_OWNER:
        return False
    token = payload.get("token")
    if not isinstance(token, str) or len(token) < 16:
        return False
    if token != required_token:
        return False
    allowed_roles = payload.get("allowed_roles")
    if allowed_roles is not None:
        if not isinstance(allowed_roles, list) or not all(
            isinstance(item, str) for item in allowed_roles
        ):
            return False
        if input_role not in allowed_roles:
            return False
    return True


def _helper_scratch_root(
    *,
    resolved_path: Path,
    input_role: str,
    env: dict[str, str],
) -> Path | None:
    if resolved_path.name == HELPER_SCRATCH_MARKER_FILENAME:
        return None
    candidate_dir = resolved_path.parent
    marker_path = candidate_dir / HELPER_SCRATCH_MARKER_FILENAME
    payload = _read_scratch_marker(marker_path)
    if payload is not None and _scratch_marker_authorizes(
        payload,
        input_role=input_role,
        env=env,
    ):
        return candidate_dir
    return None


def _forbidden_scratch_root_category(
    *,
    scratch_root: Path,
    project_root: Path,
    storage_root: Path,
) -> tuple[str, str] | None:
    storage_root_resolved = _safe_resolve_existing(storage_root) or storage_root.resolve(strict=False)
    if _is_relative_to(scratch_root, storage_root_resolved):
        return "source_path_managed_path", "managed_sidecar"
    if _is_relative_to(scratch_root, project_root):
        return "source_path_project_file", "project_root_file"
    if _version_managed_like(scratch_root):
        return "source_path_version_managed", "version_managed"
    if _release_artifact_like(scratch_root):
        return "source_path_release_artifact", "release_artifact"
    return None


def validate_prepared_input_source_path(
    raw_path: str | Path,
    *,
    project_root: Path,
    storage_root: Path,
    input_role: str,
    label: str,
    env: dict[str, str] | None = None,
) -> PreparedInputSource:
    env = env or os.environ
    candidate = Path(raw_path).expanduser()
    if not candidate.is_absolute():
        candidate = Path.cwd() / candidate
    ref_seed = _safe_path_for_ref(candidate)
    path_ref = _path_ref(ref_seed)

    try:
        source_lstat = candidate.lstat()
    except FileNotFoundError:
        raise _fail(
            reason_code="source_path_missing",
            path_category="missing",
            path_ref=path_ref,
            label=label,
        )
    except OSError as exc:
        raise _fail(
            reason_code="source_path_inspect_failed",
            path_category="unknown",
            path_ref=path_ref,
            label=label,
            extra={"errno": exc.errno if exc.errno is not None else errno.EIO},
        )

    if stat.S_ISLNK(source_lstat.st_mode):
        raise _fail(
            reason_code="source_path_symlink",
            path_category="symlink",
            path_ref=path_ref,
            label=label,
        )
    if not stat.S_ISREG(source_lstat.st_mode):
        raise _fail(
            reason_code="source_path_not_regular_file",
            path_category="not_regular_file",
            path_ref=path_ref,
            label=label,
        )
    if source_lstat.st_nlink != 1:
        raise _fail(
            reason_code="source_path_hardlink",
            path_category="hardlink",
            path_ref=path_ref,
            label=label,
        )

    try:
        resolved_path = candidate.resolve(strict=True)
    except OSError as exc:
        raise _fail(
            reason_code="source_path_realpath_failed",
            path_category="unknown",
            path_ref=path_ref,
            label=label,
            extra={"errno": exc.errno if exc.errno is not None else errno.EIO},
        )
    path_ref = _path_ref(resolved_path)

    if resolved_path.name == HELPER_SCRATCH_MARKER_FILENAME:
        raise _fail(
            reason_code="source_path_scratch_marker",
            path_category="helper_scratch_marker",
            path_ref=path_ref,
            label=label,
        )

    if _secret_like(resolved_path):
        raise _fail(
            reason_code="source_path_secret_like",
            path_category="secret_like",
            path_ref=path_ref,
            label=label,
        )
    if _transcript_or_runtime_log_like(resolved_path):
        raise _fail(
            reason_code="source_path_transcript_like",
            path_category="transcript_or_runtime_log",
            path_ref=path_ref,
            label=label,
        )

    project_root_resolved = project_root.resolve(strict=True)
    managed_category = _managed_project_path_category(
        resolved_path=resolved_path,
        project_root=project_root_resolved,
        storage_root=storage_root,
    )
    if managed_category is not None:
        reason_code, path_category = managed_category
        raise _fail(
            reason_code=reason_code,
            path_category=path_category,
            path_ref=path_ref,
            label=label,
        )
    if _release_artifact_like(resolved_path):
        raise _fail(
            reason_code="source_path_release_artifact",
            path_category="release_artifact",
            path_ref=path_ref,
            label=label,
        )
    if _is_relative_to(resolved_path, project_root_resolved):
        raise _fail(
            reason_code="source_path_project_file",
            path_category="project_root_file",
            path_ref=path_ref,
            label=label,
        )

    scratch_root = _helper_scratch_root(
        resolved_path=resolved_path,
        input_role=input_role,
        env=env,
    )
    if scratch_root is not None:
        forbidden_scratch_root = _forbidden_scratch_root_category(
            scratch_root=scratch_root,
            project_root=project_root_resolved,
            storage_root=storage_root,
        )
        if forbidden_scratch_root is not None:
            reason_code, path_category = forbidden_scratch_root
            raise _fail(
                reason_code=reason_code,
                path_category=path_category,
                path_ref=path_ref,
                label=label,
            )
        return PreparedInputSource(
            path=resolved_path,
            path_ref=path_ref,
            path_category="helper_scratch",
            st_dev=source_lstat.st_dev,
            st_ino=source_lstat.st_ino,
            st_mode=source_lstat.st_mode,
            st_nlink=source_lstat.st_nlink,
            st_size=source_lstat.st_size,
            scratch_root_ref=_path_ref(scratch_root),
        )

    raise _fail(
        reason_code="source_path_external",
        path_category="external",
        path_ref=path_ref,
        label=label,
    )


def read_prepared_input_source_text(
    source: PreparedInputSource,
    *,
    max_input_bytes: int,
    label: str,
) -> str:
    flags = os.O_RDONLY
    if hasattr(os, "O_NOFOLLOW"):
        flags |= os.O_NOFOLLOW
    if hasattr(os, "O_NONBLOCK"):
        flags |= os.O_NONBLOCK
    try:
        fd = os.open(source.path, flags)
    except OSError as exc:
        reason_code = (
            "source_path_symlink" if exc.errno == errno.ELOOP else "source_path_open_failed"
        )
        raise _fail(
            reason_code=reason_code,
            path_category=source.path_category,
            path_ref=source.path_ref,
            label=label,
            extra={"errno": exc.errno if exc.errno is not None else errno.EIO},
        )
    try:
        with os.fdopen(fd, "rb") as handle:
            file_stat = os.fstat(handle.fileno())
            if not stat.S_ISREG(file_stat.st_mode):
                raise _fail(
                    reason_code="source_path_not_regular_file",
                    path_category="not_regular_file",
                    path_ref=source.path_ref,
                    label=label,
                )
            if file_stat.st_dev != source.st_dev or file_stat.st_ino != source.st_ino:
                raise _fail(
                    reason_code="source_path_changed_after_validation",
                    path_category=source.path_category,
                    path_ref=source.path_ref,
                    label=label,
                )
            if (
                file_stat.st_mode != source.st_mode
                or file_stat.st_nlink != source.st_nlink
                or file_stat.st_size != source.st_size
            ):
                raise _fail(
                    reason_code="source_path_changed_after_validation",
                    path_category=source.path_category,
                    path_ref=source.path_ref,
                    label=label,
                )
            if file_stat.st_size > max_input_bytes:
                raise _fail(
                    reason_code="source_path_size_limit",
                    path_category=source.path_category,
                    path_ref=source.path_ref,
                    label=label,
                    extra={"size": file_stat.st_size, "max_input_bytes": max_input_bytes},
                )
            raw = handle.read(max_input_bytes + 1)
    except PreparedInputSafetyError:
        raise
    except OSError as exc:
        raise _fail(
            reason_code="source_path_read_failed",
            path_category=source.path_category,
            path_ref=source.path_ref,
            label=label,
            extra={"errno": exc.errno if exc.errno is not None else errno.EIO},
        )
    if len(raw) > max_input_bytes:
        raise _fail(
            reason_code="source_path_size_limit",
            path_category=source.path_category,
            path_ref=source.path_ref,
            label=label,
            extra={"size": len(raw), "max_input_bytes": max_input_bytes},
        )
    try:
        return raw.decode("utf-8")
    except UnicodeDecodeError:
        raise _fail(
            reason_code="source_path_not_utf8",
            path_category=source.path_category,
            path_ref=source.path_ref,
            label=label,
        )


# --- additive stable-read primitives (v0.5.0 §7.3 scratch orchestration) ----
#
# Exposed for the single scratch orchestrator core/safety/input_transport.py
# (T050-01C) so the capability manifest/content reads reuse this module's
# token/path/link/identity checks instead of growing a second safety owner.
# The rejection vocabulary is exactly the pre-existing source_path_* family.


@dataclass(frozen=True)
class RegularFileIdentity:
    """lstat/fstat identity tuple of one regular file."""

    st_dev: int
    st_ino: int
    st_mode: int
    st_nlink: int
    st_size: int


def _identity_from_stat(result: os.stat_result) -> RegularFileIdentity:
    return RegularFileIdentity(
        st_dev=result.st_dev,
        st_ino=result.st_ino,
        st_mode=result.st_mode,
        st_nlink=result.st_nlink,
        st_size=result.st_size,
    )


def lstat_regular_file_identity(
    path: Path,
    *,
    label: str,
    path_category: str,
    path_ref: str,
) -> RegularFileIdentity:
    """lstat one candidate and reject symlink/hardlink/non-regular shapes."""
    try:
        candidate_lstat = path.lstat()
    except FileNotFoundError:
        raise _fail(
            reason_code="source_path_missing",
            path_category="missing",
            path_ref=path_ref,
            label=label,
        )
    except OSError as exc:
        raise _fail(
            reason_code="source_path_inspect_failed",
            path_category="unknown",
            path_ref=path_ref,
            label=label,
            extra={"errno": exc.errno if exc.errno is not None else errno.EIO},
        )
    if stat.S_ISLNK(candidate_lstat.st_mode):
        raise _fail(
            reason_code="source_path_symlink",
            path_category="symlink",
            path_ref=path_ref,
            label=label,
        )
    if not stat.S_ISREG(candidate_lstat.st_mode):
        raise _fail(
            reason_code="source_path_not_regular_file",
            path_category="not_regular_file",
            path_ref=path_ref,
            label=label,
        )
    if candidate_lstat.st_nlink != 1:
        raise _fail(
            reason_code="source_path_hardlink",
            path_category="hardlink",
            path_ref=path_ref,
            label=label,
        )
    return _identity_from_stat(candidate_lstat)


def _read_verified_regular_file_once(
    path: Path,
    *,
    max_input_bytes: int,
    label: str,
    path_category: str,
    path_ref: str,
) -> tuple[bytes, RegularFileIdentity]:
    """One lstat -> no-follow open -> fstat identity -> bounded read pass."""
    lstat_identity = lstat_regular_file_identity(
        path,
        label=label,
        path_category=path_category,
        path_ref=path_ref,
    )
    flags = os.O_RDONLY
    if hasattr(os, "O_NOFOLLOW"):
        flags |= os.O_NOFOLLOW
    if hasattr(os, "O_NONBLOCK"):
        flags |= os.O_NONBLOCK
    try:
        fd = os.open(path, flags)
    except OSError as exc:
        reason_code = (
            "source_path_symlink" if exc.errno == errno.ELOOP else "source_path_open_failed"
        )
        raise _fail(
            reason_code=reason_code,
            path_category=path_category,
            path_ref=path_ref,
            label=label,
            extra={"errno": exc.errno if exc.errno is not None else errno.EIO},
        )
    try:
        with os.fdopen(fd, "rb") as handle:
            opened_identity = _identity_from_stat(os.fstat(handle.fileno()))
            if not stat.S_ISREG(opened_identity.st_mode):
                raise _fail(
                    reason_code="source_path_not_regular_file",
                    path_category="not_regular_file",
                    path_ref=path_ref,
                    label=label,
                )
            if opened_identity != lstat_identity:
                raise _fail(
                    reason_code="source_path_changed_after_validation",
                    path_category=path_category,
                    path_ref=path_ref,
                    label=label,
                )
            if opened_identity.st_size > max_input_bytes:
                raise _fail(
                    reason_code="source_path_size_limit",
                    path_category=path_category,
                    path_ref=path_ref,
                    label=label,
                    extra={"size": opened_identity.st_size, "max_input_bytes": max_input_bytes},
                )
            raw = handle.read(max_input_bytes + 1)
            closing_identity = _identity_from_stat(os.fstat(handle.fileno()))
            if closing_identity != opened_identity:
                raise _fail(
                    reason_code="source_path_changed_after_validation",
                    path_category=path_category,
                    path_ref=path_ref,
                    label=label,
                )
    except PreparedInputSafetyError:
        raise
    except OSError as exc:
        raise _fail(
            reason_code="source_path_read_failed",
            path_category=path_category,
            path_ref=path_ref,
            label=label,
            extra={"errno": exc.errno if exc.errno is not None else errno.EIO},
        )
    if len(raw) > max_input_bytes:
        raise _fail(
            reason_code="source_path_size_limit",
            path_category=path_category,
            path_ref=path_ref,
            label=label,
            extra={"size": len(raw), "max_input_bytes": max_input_bytes},
        )
    return raw, lstat_identity


def read_stable_regular_file_bytes(
    path: Path,
    *,
    max_input_bytes: int,
    label: str,
    path_category: str,
    path_ref: str,
) -> tuple[bytes, RegularFileIdentity]:
    """Read one regular file with two consecutive identity-verified passes.

    Both passes run lstat -> no-follow open -> fstat identity -> bounded read;
    the file is accepted only when the identity tuples and the exact bytes of
    the two passes agree, so a source replaced or mutated mid-read is rejected
    with ``source_path_changed_after_validation`` instead of being acquired.
    """
    first_bytes, first_identity = _read_verified_regular_file_once(
        path,
        max_input_bytes=max_input_bytes,
        label=label,
        path_category=path_category,
        path_ref=path_ref,
    )
    second_bytes, second_identity = _read_verified_regular_file_once(
        path,
        max_input_bytes=max_input_bytes,
        label=label,
        path_category=path_category,
        path_ref=path_ref,
    )
    if second_identity != first_identity or second_bytes != first_bytes:
        raise _fail(
            reason_code="source_path_changed_after_validation",
            path_category=path_category,
            path_ref=path_ref,
            label=label,
        )
    return first_bytes, first_identity
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall