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/workspace/runtime.py

View on GitHub
#!/usr/bin/env python3
"""Workspace, state, lock, and storage-root helpers for RecallLoom."""

from __future__ import annotations

from contextlib import contextmanager
from dataclasses import dataclass
from datetime import date, datetime
import hashlib
import json
import os
from pathlib import Path, PurePosixPath
import re
import secrets
import stat
import sys
import tempfile

from core.errors import (
    ConfigContractError,
    LockBusyError,
    StorageResolutionError,
)
from core.bridge import blocks as bridge_blocks
from core.provenance.state import initial_provenance_metadata
from core.protocol import contracts as protocol_contracts
from core.workspace import atomic_io

PROTOCOL_VERSION_RE = re.compile(r"^[0-9]+\.[0-9]+(?:\.[0-9]+)*$")
DATE_FILE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}\.md$")
RECOVERY_PROPOSAL_FILE_RE = re.compile(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{6}-[A-Za-z0-9._-]+\.md$")
REVIEW_RECORD_FILE_RE = re.compile(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{6}-[A-Za-z0-9._-]+\.review\.md$")

CONTEXT_DIRNAME = ".recallloom"
VISIBLE_DIRNAME = "recallloom"
DEFAULT_STORAGE_MODE = "hidden"
VISIBLE_STORAGE_MODE = "visible"
WORKSPACE_LOCK_FILENAME = ".recallloom.write.lock"
DAILY_LOG_PATH_PATTERN = protocol_contracts.DAILY_LOG_PATH_PATTERN
DAILY_LOGS_DIRNAME = protocol_contracts.DAILY_LOGS_DIRNAME


@dataclass(frozen=True)
class WorkspaceInfo:
    project_root: Path
    storage_root: Path
    storage_mode: str
    workspace_language: str
    config_path: Path | None
    declared_storage_mode: str | None = None
    storage_mode_matches_path: bool = True
    protocol_version: str | None = None
    protocol_version_supported: bool = True


@dataclass(frozen=True)
class RecoveryWorkspaceInfo:
    project_root: Path
    storage_root: Path
    storage_mode: str


def now_iso_timestamp() -> str:
    return datetime.now().astimezone().isoformat(timespec="seconds")


def read_text(path: Path) -> str:
    return path.read_bytes().decode("utf-8")


def write_text(path: Path, text: str) -> None:
    atomic_io.atomic_write_text(path, text)


def load_json(path: Path) -> dict:
    return json.loads(read_text(path))


def validate_storage_mode(value: str) -> str:
    if value not in protocol_contracts.SUPPORTED_STORAGE_MODES:
        raise ConfigContractError(f"Unsupported storage_mode: {value}")
    return value


def validate_workspace_language(value: str) -> str:
    if value not in protocol_contracts.SUPPORTED_WORKSPACE_LANGUAGES:
        raise ConfigContractError(f"Unsupported workspace_language: {value}")
    return value


def validate_protocol_version(value: str) -> str:
    if not isinstance(value, str) or not value.strip():
        raise ConfigContractError("protocol_version must be a non-empty string")
    if not PROTOCOL_VERSION_RE.match(value):
        raise ConfigContractError(
            f"protocol_version must use dotted string form such as '1.0', got: {value}"
        )
    return value


def validate_daily_log_protocol_path(value: str | None, *, field_name: str, path: Path) -> str | None:
    if value is None:
        return None
    if not isinstance(value, str) or not value.strip():
        raise ConfigContractError(f"{field_name} must be null or a non-empty string: {path}")
    parts = PurePosixPath(value).parts
    if len(parts) != 2 or parts[0] != DAILY_LOGS_DIRNAME or not DATE_FILE_RE.match(parts[1]):
        raise ConfigContractError(
            f"{field_name} must point to an active ISO-dated daily log under {DAILY_LOGS_DIRNAME}/: {path}"
        )
    try:
        date.fromisoformat(Path(parts[1]).stem)
    except ValueError as exc:
        raise ConfigContractError(
            f"{field_name} must use a valid ISO-dated daily log filename under {DAILY_LOGS_DIRNAME}/: {path}"
        ) from exc
    return value


def config_payload(
    *,
    storage_mode: str,
    workspace_language: str,
    created_by: str,
    created_at: str,
    protocol_version: str = protocol_contracts.CURRENT_PROTOCOL_VERSION,
) -> dict:
    return {
        "protocol_version": protocol_version,
        "storage_mode": storage_mode,
        "workspace_language": workspace_language,
        "created_by": created_by,
        "created_at": created_at,
    }


def initial_workspace_state(
    *,
    tool_name: str,
    timestamp: str,
    git_exclude_mode: str,
) -> dict:
    return {
        "workspace_revision": 1,
        "update_protocol_revision": 1,
        "git_exclude_mode": git_exclude_mode,
        "bridged_entries": {},
        "files": {
            "context_brief": {
                "file_revision": 1,
                "updated_at": timestamp,
                "writer_id": tool_name,
                "base_workspace_revision": 1,
            },
            "rolling_summary": {
                "file_revision": 1,
                "updated_at": timestamp,
                "writer_id": tool_name,
                "base_workspace_revision": 1,
            },
            "update_protocol": {
                "file_revision": 1,
                "updated_at": timestamp,
                "writer_id": tool_name,
                "base_workspace_revision": 1,
            },
        },
        "daily_logs": {
            "latest_file": None,
            "latest_entry_id": None,
            "latest_entry_seq": 0,
            "entry_count": 0,
        },
        "provenance": initial_provenance_metadata(timestamp=timestamp),
    }


def load_workspace_state(path: Path) -> dict:
    try:
        data = load_json(path)
    except FileNotFoundError as exc:
        raise ConfigContractError(f"Missing state file: {path}") from exc
    except json.JSONDecodeError as exc:
        raise ConfigContractError(f"Malformed JSON in state file: {path}") from exc
    except UnicodeDecodeError as exc:
        raise ConfigContractError(f"State file is not valid UTF-8: {path}") from exc
    if not isinstance(data, dict):
        raise ConfigContractError(f"State file must contain a JSON object: {path}")
    required = {
        "workspace_revision",
        "update_protocol_revision",
        "git_exclude_mode",
        "bridged_entries",
        "files",
        "daily_logs",
    }
    missing = sorted(required.difference(data.keys()))
    if missing:
        raise ConfigContractError(f"State file is missing required fields {missing}: {path}")

    if not isinstance(data["workspace_revision"], int) or data["workspace_revision"] < 1:
        raise ConfigContractError(
            f"state.json workspace_revision must be a positive integer: {path}"
        )
    if not isinstance(data["update_protocol_revision"], int) or data["update_protocol_revision"] < 1:
        raise ConfigContractError(
            f"state.json update_protocol_revision must be a positive integer: {path}"
        )
    if data["git_exclude_mode"] not in {"managed", "skipped", "not_applicable"}:
        raise ConfigContractError(
            f"state.json git_exclude_mode must be one of managed/skipped/not_applicable: {path}"
        )

    bridged_entries = data["bridged_entries"]
    if not isinstance(bridged_entries, dict):
        raise ConfigContractError(f"state.json bridged_entries must be an object: {path}")
    for rel_target, bridge_state in bridged_entries.items():
        if not isinstance(rel_target, str) or not rel_target.strip():
            raise ConfigContractError(
                f"state.json bridged_entries keys must be non-empty strings: {path}"
            )
        if rel_target not in protocol_contracts.ROOT_ENTRY_CANDIDATE_STRINGS:
            raise ConfigContractError(
                "state.json bridged_entries keys must be supported root entry file paths "
                f"{sorted(protocol_contracts.ROOT_ENTRY_CANDIDATE_STRINGS)}: {path}"
            )
        if not isinstance(bridge_state, dict):
            raise ConfigContractError(
                f"state.json bridged_entries values must be objects: {path}"
            )
        if "update_protocol_revision_seen" in bridge_state:
            value = bridge_state["update_protocol_revision_seen"]
            if not isinstance(value, int) or value < 1:
                raise ConfigContractError(
                    f"state.json bridged_entries.{rel_target}.update_protocol_revision_seen must be a positive integer: {path}"
                )
        if "latest_daily_log_seen" in bridge_state:
            validate_daily_log_protocol_path(
                bridge_state["latest_daily_log_seen"],
                field_name=f"state.json bridged_entries.{rel_target}.latest_daily_log_seen",
                path=path,
            )
        if "updated_at" in bridge_state:
            value = bridge_state["updated_at"]
            if not isinstance(value, str) or not value.strip():
                raise ConfigContractError(
                    f"state.json bridged_entries.{rel_target}.updated_at must be a non-empty string: {path}"
                )

    files = data["files"]
    if not isinstance(files, dict):
        raise ConfigContractError(f"state.json files must be an object: {path}")
    for file_key in ("context_brief", "rolling_summary", "update_protocol"):
        entry = files.get(file_key)
        if not isinstance(entry, dict):
            raise ConfigContractError(
                f"state.json files.{file_key} must be an object: {path}"
            )
        if not isinstance(entry.get("file_revision"), int) or entry["file_revision"] < 1:
            raise ConfigContractError(
                f"state.json files.{file_key}.file_revision must be a positive integer: {path}"
            )
        if not isinstance(entry.get("updated_at"), str) or not entry["updated_at"].strip():
            raise ConfigContractError(
                f"state.json files.{file_key}.updated_at must be a non-empty string: {path}"
            )
        if not isinstance(entry.get("writer_id"), str) or not entry["writer_id"].strip():
            raise ConfigContractError(
                f"state.json files.{file_key}.writer_id must be a non-empty string: {path}"
            )
        if (
            not isinstance(entry.get("base_workspace_revision"), int)
            or entry["base_workspace_revision"] < 1
        ):
            raise ConfigContractError(
                f"state.json files.{file_key}.base_workspace_revision must be a positive integer: {path}"
            )

    daily_logs = data["daily_logs"]
    if not isinstance(daily_logs, dict):
        raise ConfigContractError(f"state.json daily_logs must be an object: {path}")
    latest_file = validate_daily_log_protocol_path(
        daily_logs.get("latest_file"),
        field_name="state.json daily_logs.latest_file",
        path=path,
    )
    latest_entry_id = daily_logs.get("latest_entry_id")
    if latest_entry_id is not None and (
        not isinstance(latest_entry_id, str) or not latest_entry_id.strip()
    ):
        raise ConfigContractError(
            f"state.json daily_logs.latest_entry_id must be null or a non-empty string: {path}"
        )
    latest_entry_seq = daily_logs.get("latest_entry_seq")
    if latest_entry_seq is not None and (
        not isinstance(latest_entry_seq, int) or latest_entry_seq < 0
    ):
        raise ConfigContractError(
            f"state.json daily_logs.latest_entry_seq must be null or a non-negative integer: {path}"
        )
    entry_count = daily_logs.get("entry_count")
    if not isinstance(entry_count, int) or entry_count < 0:
        raise ConfigContractError(
            f"state.json daily_logs.entry_count must be a non-negative integer: {path}"
        )
    latest_entry_seq_value = 0 if latest_entry_seq is None else latest_entry_seq
    if entry_count < latest_entry_seq_value:
        raise ConfigContractError(
            f"state.json daily_logs.entry_count cannot be smaller than latest_entry_seq: {path}"
        )
    if latest_file is None:
        if latest_entry_id is not None or latest_entry_seq not in {0, None} or entry_count != 0:
            raise ConfigContractError(
                "state.json daily_logs must use the null/zero cursor shape when no active daily log exists: "
                f"{path}"
            )
    else:
        empty_scaffold_cursor = (
            latest_entry_id is None
            and latest_entry_seq in {0, None}
            and entry_count == 0
        )
        populated_cursor = (
            latest_entry_id is not None
            and isinstance(latest_entry_seq, int)
            and latest_entry_seq >= 1
            and entry_count >= 1
        )
        if not empty_scaffold_cursor and not populated_cursor:
            raise ConfigContractError(
                "state.json daily_logs must record either an empty-scaffold cursor or a populated cursor "
                f"when latest_file is set: {path}"
            )
    if "updated_at" in daily_logs:
        updated_at = daily_logs["updated_at"]
        if not isinstance(updated_at, str) or not updated_at.strip():
            raise ConfigContractError(
                f"state.json daily_logs.updated_at must be a non-empty string when present: {path}"
            )
    return data


def load_and_validate_config(
    path: Path,
    default_storage_mode: str,
    *,
    allow_unsupported_version: bool = False,
    allow_storage_mode_mismatch: bool = False,
) -> dict:
    try:
        data = load_json(path)
    except FileNotFoundError as exc:
        raise ConfigContractError(f"Missing config file: {path}") from exc
    except json.JSONDecodeError as exc:
        raise ConfigContractError(f"Malformed JSON in config file: {path}") from exc
    except UnicodeDecodeError as exc:
        raise ConfigContractError(f"Config file is not valid UTF-8: {path}") from exc
    except OSError as exc:
        raise ConfigContractError(f"Config file is not readable: {path} ({exc})") from exc

    if not isinstance(data, dict):
        raise ConfigContractError(f"Config file must contain a JSON object: {path}")

    required = {
        "protocol_version",
        "storage_mode",
        "workspace_language",
        "created_by",
        "created_at",
    }
    missing = sorted(required.difference(data.keys()))
    if missing:
        raise ConfigContractError(
            f"Config file is missing required fields {missing}: {path}"
        )

    storage_mode = validate_storage_mode(data.get("storage_mode", default_storage_mode))
    storage_mode_matches_path = storage_mode == default_storage_mode
    if not storage_mode_matches_path and not allow_storage_mode_mismatch:
        raise ConfigContractError(
            f"storage_mode '{storage_mode}' does not match the storage root implied by {path}"
        )
    workspace_language = validate_workspace_language(
        data.get("workspace_language", protocol_contracts.DEFAULT_WORKSPACE_LANGUAGE)
    )

    protocol_version = validate_protocol_version(data.get("protocol_version"))
    protocol_version_supported = protocol_version in protocol_contracts.SUPPORTED_PROTOCOL_VERSIONS
    if not protocol_version_supported and not allow_unsupported_version:
        raise ConfigContractError(
            f"Unsupported protocol_version {protocol_version} in config file: {path}"
        )

    created_by = data.get("created_by")
    created_at = data.get("created_at")
    if not isinstance(created_by, str) or not created_by.strip():
        raise ConfigContractError(f"created_by must be a non-empty string in config file: {path}")
    if not isinstance(created_at, str) or not created_at.strip():
        raise ConfigContractError(f"created_at must be a non-empty string in config file: {path}")

    return {
        "protocol_version": protocol_version,
        "protocol_version_supported": protocol_version_supported,
        "storage_mode": storage_mode,
        "storage_mode_matches_path": storage_mode_matches_path,
        "workspace_language": workspace_language,
        "created_by": created_by,
        "created_at": created_at,
    }


def normalize_start_path(raw_path: str | Path) -> Path:
    try:
        path = Path(raw_path).expanduser().resolve()
        return path.parent if path.is_file() else path
    except OSError as exc:
        raise StorageResolutionError(
            f"Failed to resolve start path {raw_path}: {exc}",
            failure_reason="not_project_root",
        ) from exc


def project_lock_path(project_root: Path) -> Path:
    return project_root / WORKSPACE_LOCK_FILENAME


def load_lock_payload(lock_path: Path) -> dict:
    try:
        data = json.loads(read_text(lock_path))
    except (FileNotFoundError, json.JSONDecodeError, UnicodeDecodeError, OSError):
        return {}
    return data if isinstance(data, dict) else {}


def parse_lock_timestamp(value: str | None) -> datetime | None:
    if not isinstance(value, str) or not value.strip():
        return None
    try:
        parsed = datetime.fromisoformat(value)
    except ValueError:
        return None
    if parsed.tzinfo is None:
        return parsed.astimezone()
    return parsed


# Windows process-liveness probe seam. On Windows os.kill(pid, 0) maps to
# TerminateProcess for a live pid and raises OSError WinError 87 for a dead one,
# so liveness is probed through OpenProcess/GetExitCodeProcess instead and
# TerminateProcess is never called. Tests may monkeypatch _WINDOWS_PLATFORM to
# force the Windows branch and pass a fake ctypes module to _pid_is_alive_windows.
_WINDOWS_PLATFORM = sys.platform.startswith("win")
_PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
_STILL_ACTIVE = 259
_ERROR_INVALID_PARAMETER = 87


def _pid_is_alive_windows(pid: int, ctypes_module=None, wintypes_module=None) -> bool:
    """Probe pid liveness via OpenProcess + GetExitCodeProcess.

    Fail-safe mapping: only ERROR_INVALID_PARAMETER (pid does not exist) reports
    dead; ERROR_ACCESS_DENIED or any other probe failure reports alive so a live
    owner's lock is never reclaimed. ``ctypes_module`` is injectable for tests.
    """
    if ctypes_module is None:
        import ctypes as ctypes_module
    if wintypes_module is None:
        from ctypes import wintypes as wintypes_module
    try:
        kernel32 = ctypes_module.WinDLL("kernel32", use_last_error=True)
        kernel32.OpenProcess.argtypes = [
            wintypes_module.DWORD,
            wintypes_module.BOOL,
            wintypes_module.DWORD,
        ]
        kernel32.OpenProcess.restype = wintypes_module.HANDLE
        kernel32.GetExitCodeProcess.argtypes = [
            wintypes_module.HANDLE,
            ctypes_module.POINTER(wintypes_module.DWORD),
        ]
        kernel32.GetExitCodeProcess.restype = wintypes_module.BOOL
        kernel32.CloseHandle.argtypes = [wintypes_module.HANDLE]
        kernel32.CloseHandle.restype = wintypes_module.BOOL
        handle = kernel32.OpenProcess(_PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
        if not handle:
            return ctypes_module.get_last_error() != _ERROR_INVALID_PARAMETER
        try:
            exit_code = wintypes_module.DWORD()
            if not kernel32.GetExitCodeProcess(handle, ctypes_module.byref(exit_code)):
                return True
            return exit_code.value == _STILL_ACTIVE
        finally:
            kernel32.CloseHandle(handle)
    except Exception:
        return True


def pid_is_alive(pid: int) -> bool:
    if pid <= 0:
        return False
    if _WINDOWS_PLATFORM:
        return _pid_is_alive_windows(pid)
    try:
        os.kill(pid, 0)
    except ProcessLookupError:
        return False
    except PermissionError:
        return True
    else:
        return True


# ---------------------------------------------------------------------------
# Guard-serialized token-file identity lock (v0.5.0 unique construction plan
# §7.7). The public workspace lock is still ``.recallloom.write.lock`` at the
# project root with the v0.4.8.3 payload plus an additive random 256-bit
# ``instance_token``. Every acquire / stale reclaim / finalizer / manual
# unlock path first holds an internal per-user guard (POSIX ``fcntl.flock``,
# Windows ``msvcrt.locking``) named by sha256 of the canonical workspace
# identity inside a per-user system-temp safe directory, then re-verifies the
# lock file (lstat -> no-follow open -> fstat -> payload/token/identity)
# before any unlink. A lock is unlinked only when the pid is dead or an
# explicit unlock is legitimate AND the final identity+token still equals the
# acquiring handle's snapshot, so a new lock instance is never deleted by an
# old owner's finalizer or reclaimer. The guard only serializes RecallLoom
# product instances; it never replaces the token lock and never appears in
# public output. Unsupported backends and guard-identity anomalies fail
# closed (LockBusyError, with no guard detail in the message).
# ---------------------------------------------------------------------------

_GUARD_BACKEND_FCNTL = "fcntl"
_GUARD_BACKEND_MSVCRT = "msvcrt"
_O_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)


@dataclass(frozen=True)
class WorkspaceLockHandle:
    """Frozen identity snapshot of one acquired workspace write lock."""

    lock_path: Path
    lock_identity: tuple[int, int]
    instance_token: str
    guard_path: Path
    guard_handle: int
    backend: str


@dataclass(frozen=True)
class WorkspaceLockObservation:
    """One no-follow observation of the workspace token lock.

    ``identity`` is the (st_dev, st_ino) pair proven identical between the
    lstat'd directory entry and the no-follow opened handle. It is None when
    the path is absent or when an anomaly forced a fail-closed observation.
    """

    exists: bool
    identity: tuple[int, int] | None
    payload: dict
    anomaly: str | None


def _guard_backend_for_platform() -> str | None:
    if os.name == "posix":
        return _GUARD_BACKEND_FCNTL
    if os.name == "nt":
        return _GUARD_BACKEND_MSVCRT
    return None


def _lock_guard_msvcrt(fd: int, msvcrt_module=None) -> None:
    """Take the guard through msvcrt.locking; fail closed when unavailable.

    Residual W3 (Gate P freeze record): real Windows locking behaviour is
    proven on the Gate R Windows matrix; on other hosts this branch is
    exercised only through the injectable ``msvcrt_module`` seam.
    """
    if msvcrt_module is None:
        try:
            import msvcrt as msvcrt_module
        except ImportError as exc:
            raise LockBusyError(
                "Refusing to continue because the RecallLoom write-lock guard backend "
                "msvcrt is unavailable on this platform; failing closed."
            ) from exc
    os.lseek(fd, 0, os.SEEK_SET)
    try:
        msvcrt_module.locking(fd, msvcrt_module.LK_NBLCK, 1)
    except OSError as exc:
        raise LockBusyError(
            "Refusing to continue because another RecallLoom operation holds the "
            "write-lock guard for this workspace."
        ) from exc


def _unlock_guard_msvcrt(fd: int, msvcrt_module=None) -> None:
    if msvcrt_module is None:
        import msvcrt as msvcrt_module
    os.lseek(fd, 0, os.SEEK_SET)
    msvcrt_module.locking(fd, msvcrt_module.LK_UNLCK, 1)


def _lock_guard_fd(fd: int, backend: str) -> None:
    if backend == _GUARD_BACKEND_FCNTL:
        try:
            import fcntl
        except ImportError as exc:
            raise LockBusyError(
                "Refusing to continue because the RecallLoom write-lock guard backend "
                "fcntl is unavailable on this platform; failing closed."
            ) from exc
        try:
            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
        except OSError as exc:
            raise LockBusyError(
                "Refusing to continue because another RecallLoom operation holds the "
                "write-lock guard for this workspace."
            ) from exc
        return
    if backend == _GUARD_BACKEND_MSVCRT:
        _lock_guard_msvcrt(fd)
        return
    raise LockBusyError(
        "Refusing to continue because the RecallLoom write-lock guard has no supported "
        "backend on this platform; failing closed."
    )


def _guard_dir() -> Path:
    base = Path(tempfile.gettempdir())
    if os.name == "posix":
        return base / f"recallloom-lock-guards-{os.getuid()}"
    return base / "recallloom-lock-guards"


def _ensure_guard_dir() -> Path:
    guard_dir = _guard_dir()
    try:
        dir_stat = os.lstat(guard_dir)
    except FileNotFoundError:
        try:
            os.mkdir(guard_dir, 0o700)
        except FileExistsError:
            pass
        dir_stat = os.lstat(guard_dir)
    if not stat.S_ISDIR(dir_stat.st_mode):
        raise LockBusyError(
            "Refusing to continue because the RecallLoom write-lock guard location "
            "is not a directory; failing closed."
        )
    if os.name == "posix" and (
        dir_stat.st_uid != os.getuid() or stat.S_IMODE(dir_stat.st_mode) & 0o077
    ):
        raise LockBusyError(
            "Refusing to continue because the RecallLoom write-lock guard directory "
            "is not private to the current user; failing closed."
        )
    return guard_dir


def _workspace_guard_path(project_root: Path) -> Path:
    canonical_identity = str(Path(project_root).resolve())
    digest = hashlib.sha256(canonical_identity.encode("utf-8")).hexdigest()
    return _ensure_guard_dir() / f"write-lock-{digest}.guard"


def _acquire_guard(project_root: Path) -> tuple[Path, int, str]:
    """Open and lock the internal guard; fail closed on any guard anomaly."""
    backend = _guard_backend_for_platform()
    if backend is None:
        raise LockBusyError(
            "Refusing to continue because the RecallLoom write-lock guard has no supported "
            "backend on this platform; failing closed."
        )
    guard_path = _workspace_guard_path(project_root)
    fd = os.open(guard_path, os.O_RDWR | os.O_CREAT, 0o600)
    try:
        _lock_guard_fd(fd, backend)
        handle_stat = os.fstat(fd)
        try:
            path_stat = os.lstat(guard_path)
        except FileNotFoundError as exc:
            raise LockBusyError(
                "Refusing to continue because the RecallLoom write-lock guard identity "
                "changed while it was being acquired; failing closed."
            ) from exc
        if not stat.S_ISREG(path_stat.st_mode) or (
            (path_stat.st_dev, path_stat.st_ino) != (handle_stat.st_dev, handle_stat.st_ino)
        ):
            raise LockBusyError(
                "Refusing to continue because the RecallLoom write-lock guard identity "
                "changed while it was being acquired; failing closed."
            )
    except BaseException:
        os.close(fd)
        raise
    return guard_path, fd, backend


def _release_guard(guard_handle: int, backend: str) -> None:
    """Best-effort unlock then close; closing always releases OS-level locks."""
    try:
        if backend == _GUARD_BACKEND_FCNTL:
            try:
                import fcntl
            except ImportError:
                fcntl = None
            if fcntl is not None:
                fcntl.flock(guard_handle, fcntl.LOCK_UN)
        elif backend == _GUARD_BACKEND_MSVCRT:
            _unlock_guard_msvcrt(guard_handle)
    except Exception:
        pass
    finally:
        os.close(guard_handle)


@contextmanager
def workspace_lock_guard(project_root: Path):
    """Hold the internal write-lock guard for one workspace.

    Every acquire/reclaim/finalizer/manual-unlock path holds this guard before
    inspecting or unlinking the token lock. The guard only serializes product
    instances and never appears in public output.
    """
    guard_path, guard_handle, backend = _acquire_guard(project_root)
    try:
        yield guard_path
    finally:
        _release_guard(guard_handle, backend)


def observe_workspace_lock(lock_path: Path) -> WorkspaceLockObservation:
    """lstat -> no-follow open -> fstat -> payload; fail closed on anomalies."""
    try:
        path_stat = os.lstat(lock_path)
    except FileNotFoundError:
        return WorkspaceLockObservation(False, None, {}, None)
    except OSError as exc:
        return WorkspaceLockObservation(False, None, {}, f"lstat_failed:{exc.errno}")
    if not stat.S_ISREG(path_stat.st_mode):
        return WorkspaceLockObservation(True, None, {}, "not_regular_file")
    try:
        fd = os.open(lock_path, os.O_RDONLY | _O_NOFOLLOW)
    except FileNotFoundError:
        return WorkspaceLockObservation(False, None, {}, None)
    except OSError as exc:
        return WorkspaceLockObservation(True, None, {}, f"open_failed:{exc.errno}")
    try:
        try:
            handle_stat = os.fstat(fd)
        except OSError as exc:
            return WorkspaceLockObservation(True, None, {}, f"fstat_failed:{exc.errno}")
        if (handle_stat.st_dev, handle_stat.st_ino) != (path_stat.st_dev, path_stat.st_ino):
            return WorkspaceLockObservation(True, None, {}, "identity_mismatch")
        try:
            raw = os.read(fd, 65536)
        except OSError as exc:
            return WorkspaceLockObservation(True, None, {}, f"read_failed:{exc.errno}")
    finally:
        os.close(fd)
    try:
        data = json.loads(raw.decode("utf-8"))
    except (json.JSONDecodeError, UnicodeDecodeError):
        data = {}
    payload = data if isinstance(data, dict) else {}
    return WorkspaceLockObservation(
        True, (handle_stat.st_dev, handle_stat.st_ino), payload, None
    )


def remove_workspace_lock_if_unchanged(
    lock_path: Path,
    *,
    expected_identity: tuple[int, int] | None,
    expected_token: str | None,
) -> bool:
    """Unlink the token lock only while the expected identity+token hold.

    The caller must already hold the workspace guard. The final identity and
    instance token are re-observed immediately before the unlink; a replaced
    or foreign lock instance is never removed.
    """
    final = observe_workspace_lock(lock_path)
    if not final.exists or final.anomaly is not None:
        return False
    if final.identity != expected_identity:
        return False
    if final.payload.get("instance_token") != expected_token:
        return False
    try:
        lock_path.unlink()
    except FileNotFoundError:
        return False
    return True


def _reclaim_observed_stale_lock(lock_path: Path, observation: WorkspaceLockObservation) -> bool:
    """Unlink a verified-stale observed lock; the guard must already be held."""
    pid = observation.payload.get("pid")
    if not isinstance(pid, int):
        return False
    if pid_is_alive(pid):
        return False
    return remove_workspace_lock_if_unchanged(
        lock_path,
        expected_identity=observation.identity,
        expected_token=observation.payload.get("instance_token"),
    )


def reclaim_stale_workspace_lock(lock_path: Path) -> bool:
    if not lock_path.exists():
        return False
    with workspace_lock_guard(lock_path.parent):
        observation = observe_workspace_lock(lock_path)
        if not observation.exists or observation.anomaly is not None:
            return False
        try:
            return _reclaim_observed_stale_lock(lock_path, observation)
        except PermissionError:
            # A sharing violation or denied delete means the lock file may still be
            # held open; treat the lock as busy and let LockBusyError surface.
            if _WINDOWS_PLATFORM:
                return False
            raise


def _acquire_workspace_lock(project_root: Path, owner: str) -> WorkspaceLockHandle:
    lock_path = project_lock_path(project_root)
    guard_path, guard_handle, backend = _acquire_guard(project_root)
    try:
        fd: int | None = None
        instance_token = ""
        for _ in range(2):
            try:
                fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY | _O_NOFOLLOW)
            except FileExistsError:
                observation = observe_workspace_lock(lock_path)
                reclaimed = False
                if observation.exists and observation.anomaly is None:
                    try:
                        reclaimed = _reclaim_observed_stale_lock(lock_path, observation)
                    except PermissionError:
                        # v0.4.8.3 semantics: a denied delete is "busy" on
                        # Windows and propagates on POSIX.
                        if _WINDOWS_PLATFORM:
                            reclaimed = False
                        else:
                            raise
                if not reclaimed:
                    lock_payload = load_lock_payload(lock_path)
                    lock_owner = lock_payload.get("owner", "unknown")
                    lock_pid = lock_payload.get("pid", "unknown")
                    lock_created_at = lock_payload.get("created_at", "unknown")
                    raise LockBusyError(
                        "Refusing to continue because another RecallLoom mutating operation appears to be running for "
                        f"{project_root} (owner={lock_owner}, pid={lock_pid}, created_at={lock_created_at}). "
                        "If this lock is stale or malformed, inspect or remove it explicitly with unlock_write_lock.py."
                    )
                continue
            instance_token = secrets.token_hex(32)
            payload = json.dumps(
                {
                    "owner": owner,
                    "pid": os.getpid(),
                    "created_at": now_iso_timestamp(),
                    "instance_token": instance_token,
                }
            )
            try:
                os.write(fd, payload.encode("utf-8"))
                os.fsync(fd)
            except BaseException:
                os.close(fd)
                raise
            break
        else:
            raise LockBusyError(
                f"Refusing to continue because a stale RecallLoom lock could not be reclaimed for {project_root}."
            )
        try:
            handle_stat = os.fstat(fd)
        finally:
            os.close(fd)
        return WorkspaceLockHandle(
            lock_path=lock_path,
            lock_identity=(handle_stat.st_dev, handle_stat.st_ino),
            instance_token=instance_token,
            guard_path=guard_path,
            guard_handle=guard_handle,
            backend=backend,
        )
    except BaseException:
        _release_guard(guard_handle, backend)
        raise


def _finalize_workspace_lock(handle: WorkspaceLockHandle) -> None:
    """Delete ONLY this handle's own lock instance, then release the guard."""
    try:
        remove_workspace_lock_if_unchanged(
            handle.lock_path,
            expected_identity=handle.lock_identity,
            expected_token=handle.instance_token,
        )
    finally:
        _release_guard(handle.guard_handle, handle.backend)


@contextmanager
def workspace_write_lock(project_root: Path, owner: str):
    handle = _acquire_workspace_lock(project_root, owner)
    try:
        yield handle.lock_path
    finally:
        _finalize_workspace_lock(handle)


def hidden_storage_root(project_root: Path) -> Path:
    return project_root / CONTEXT_DIRNAME


def visible_storage_root(project_root: Path) -> Path:
    return project_root / VISIBLE_DIRNAME


def daily_logs_dir(storage_root: Path) -> Path:
    return storage_root / DAILY_LOGS_DIRNAME


def storage_root_boundary_issue(project_root: Path, storage_root: Path, storage_mode: str) -> str | None:
    if not storage_root.exists() and not storage_root.is_symlink():
        return None
    mode_label = "hidden" if storage_mode == DEFAULT_STORAGE_MODE else "visible"
    try:
        project_root_resolved = project_root.resolve()
    except OSError as exc:
        raise ConfigContractError(
            f"Failed to resolve RecallLoom project root {project_root}: {exc}"
        ) from exc
    if storage_root.is_symlink():
        return (
            f"Refusing to continue because the {mode_label} RecallLoom storage root is a symlink: "
            f"{storage_root}. RecallLoom sidecars must be real directories directly under the project root."
        )
    try:
        resolved_storage_root = storage_root.resolve()
    except OSError as exc:
        raise ConfigContractError(
            f"Failed to resolve RecallLoom storage root {storage_root}: {exc}"
        ) from exc
    if resolved_storage_root.parent != project_root_resolved:
        return (
            f"Refusing to continue because the {mode_label} RecallLoom storage root resolves outside the project root: "
            f"{storage_root} -> {resolved_storage_root}."
        )
    return None


def recovery_storage_roots(project_root: Path) -> list[Path]:
    roots: list[Path] = []
    hidden = hidden_storage_root(project_root)
    visible = visible_storage_root(project_root)
    hidden_issue = storage_root_boundary_issue(project_root, hidden, DEFAULT_STORAGE_MODE)
    if hidden_issue is not None:
        raise ConfigContractError(hidden_issue)
    if is_recovery_storage_candidate(project_root, hidden, DEFAULT_STORAGE_MODE):
        roots.append(hidden)
    visible_issue = storage_root_boundary_issue(project_root, visible, VISIBLE_STORAGE_MODE)
    if visible_issue is not None:
        raise ConfigContractError(visible_issue)
    if is_recovery_storage_candidate(project_root, visible, VISIBLE_STORAGE_MODE):
        roots.append(visible)
    return roots


def visible_root_has_sidecar_signals(storage_root: Path) -> bool:
    signals = set(protocol_contracts.FILE_KEYS.values())
    signals.add(DAILY_LOGS_DIRNAME)
    if not storage_root.is_dir():
        return False
    return any((storage_root / name).exists() for name in signals)


def looks_like_installable_package_dir(storage_root: Path) -> bool:
    if not storage_root.is_dir():
        return False
    return (
        (storage_root / "package-metadata.json").is_file()
        and (storage_root / "SKILL.md").is_file()
        and (storage_root / "scripts").is_dir()
    )


def damaged_sidecar_reason(project_root: Path, storage_root: Path, storage_mode: str) -> str | None:
    boundary_issue = storage_root_boundary_issue(project_root, storage_root, storage_mode)
    if boundary_issue is not None:
        return boundary_issue
    config_path = storage_root / protocol_contracts.FILE_KEYS["config"]
    if config_path.is_file():
        return None

    if storage_mode == DEFAULT_STORAGE_MODE:
        if storage_root.is_file():
            return (
                f"Detected a damaged RecallLoom hidden sidecar under {project_root}: "
                f"{storage_root} exists but {config_path} is missing."
            )
        if storage_root.is_dir() and any(storage_root.iterdir()):
            return (
                f"Detected a damaged RecallLoom hidden sidecar under {project_root}: "
                f"{storage_root} exists and is non-empty, but {config_path} is missing."
            )
        return None

    if storage_root.is_dir():
        if looks_like_installable_package_dir(storage_root):
            return None
        if visible_root_has_sidecar_signals(storage_root):
            return (
                f"Detected a damaged RecallLoom visible sidecar under {project_root}: "
                f"{storage_root} contains RecallLoom sidecar files, but {config_path} is missing."
            )
    return None


def is_recovery_storage_candidate(project_root: Path, storage_root: Path, storage_mode: str) -> bool:
    if (storage_root / protocol_contracts.FILE_KEYS["config"]).is_file():
        return True
    return damaged_sidecar_reason(project_root, storage_root, storage_mode) is not None


def infer_storage_mode_from_root(storage_root: Path) -> str:
    if storage_root.name == CONTEXT_DIRNAME:
        return DEFAULT_STORAGE_MODE
    if storage_root.name == VISIBLE_DIRNAME:
        return VISIBLE_STORAGE_MODE
    raise StorageResolutionError(f"Cannot infer RecallLoom storage mode from path: {storage_root}")


def storage_root_for_mode(project_root: Path, storage_mode: str) -> Path:
    storage_mode = validate_storage_mode(storage_mode)
    if storage_mode == DEFAULT_STORAGE_MODE:
        return hidden_storage_root(project_root)
    return visible_storage_root(project_root)


def find_recovery_workspace(
    start_path: str | Path,
    *,
    requested_storage_mode: str | None = None,
) -> RecoveryWorkspaceInfo | None:
    start = normalize_start_path(start_path)
    if requested_storage_mode is not None:
        requested_storage_mode = validate_storage_mode(requested_storage_mode)

    for candidate in (start, *start.parents):
        roots = recovery_storage_roots(candidate)
        if not roots:
            continue

        if requested_storage_mode is not None:
            target_root = storage_root_for_mode(candidate, requested_storage_mode)
            if is_recovery_storage_candidate(candidate, target_root, requested_storage_mode):
                return RecoveryWorkspaceInfo(
                    project_root=candidate,
                    storage_root=target_root,
                    storage_mode=requested_storage_mode,
                )
            continue

        for root in roots:
            if start == root or root in start.parents:
                return RecoveryWorkspaceInfo(
                    project_root=candidate,
                    storage_root=root,
                    storage_mode=infer_storage_mode_from_root(root),
                )

        if len(roots) == 1:
            root = roots[0]
            return RecoveryWorkspaceInfo(
                project_root=candidate,
                storage_root=root,
                storage_mode=infer_storage_mode_from_root(root),
            )

        raise StorageResolutionError(
            f"Multiple RecallLoom storage roots exist under {candidate}. "
            "Re-run with an explicit storage mode or target a path inside the desired sidecar.",
            failure_reason="dual_sidecar_conflict",
        )

    return None


def find_recovery_project_root(start_path: str | Path) -> Path:
    start = normalize_start_path(start_path)
    for candidate in (start, *start.parents):
        if project_lock_path(candidate).exists():
            return candidate
        if recovery_storage_roots(candidate):
            return candidate
    return start


def config_path_for_mode(project_root: Path, storage_mode: str) -> Path:
    return storage_root_for_mode(project_root, storage_mode) / protocol_contracts.FILE_KEYS["config"]


def file_path(workspace: WorkspaceInfo, file_key: str) -> Path:
    if file_key == "daily_logs_dir":
        return daily_logs_dir(workspace.storage_root)
    return workspace.storage_root / protocol_contracts.FILE_KEYS[file_key]


def detect_workspace(
    project_root: Path,
    *,
    allow_unsupported_version: bool = False,
    allow_storage_mode_mismatch: bool = False,
) -> WorkspaceInfo | None:
    hidden_root = hidden_storage_root(project_root)
    hidden_config = hidden_root / protocol_contracts.FILE_KEYS["config"]
    visible_root = visible_storage_root(project_root)
    visible_config = visible_root / protocol_contracts.FILE_KEYS["config"]

    hidden_boundary_issue = storage_root_boundary_issue(project_root, hidden_root, DEFAULT_STORAGE_MODE)
    if hidden_boundary_issue is not None:
        raise ConfigContractError(hidden_boundary_issue, failure_reason="invalid_storage_boundary")
    visible_boundary_issue = storage_root_boundary_issue(project_root, visible_root, VISIBLE_STORAGE_MODE)
    if visible_boundary_issue is not None:
        raise ConfigContractError(visible_boundary_issue, failure_reason="invalid_storage_boundary")

    try:
        hidden_exists = hidden_config.is_file()
        visible_exists = visible_config.is_file()
        hidden_damaged = damaged_sidecar_reason(project_root, hidden_root, DEFAULT_STORAGE_MODE)
        visible_damaged = damaged_sidecar_reason(project_root, visible_root, VISIBLE_STORAGE_MODE)
    except OSError as exc:
        raise ConfigContractError(
            f"Failed to inspect RecallLoom storage roots under {project_root}: {exc}"
        ) from exc

    if hidden_exists and visible_exists:
        raise StorageResolutionError(
            f"Conflicting RecallLoom storage roots found under {project_root}: "
            f"{hidden_root} and {visible_root}. Resolve the conflict before continuing.",
            failure_reason="dual_sidecar_conflict",
        )

    if hidden_exists:
        if visible_damaged is not None:
            raise StorageResolutionError(
                f"Conflicting RecallLoom storage roots found under {project_root}: "
                f"{hidden_root} is valid, but {visible_root} is a damaged visible sidecar. "
                "Resolve the conflict before continuing.",
                failure_reason="dual_sidecar_conflict",
            )
        data = load_and_validate_config(
            hidden_config,
            DEFAULT_STORAGE_MODE,
            allow_unsupported_version=allow_unsupported_version,
            allow_storage_mode_mismatch=allow_storage_mode_mismatch,
        )
        return WorkspaceInfo(
            project_root=project_root,
            storage_root=hidden_root,
            storage_mode=DEFAULT_STORAGE_MODE,
            workspace_language=data["workspace_language"],
            config_path=hidden_config,
            declared_storage_mode=data["storage_mode"],
            storage_mode_matches_path=data["storage_mode_matches_path"],
            protocol_version=data["protocol_version"],
            protocol_version_supported=data["protocol_version_supported"],
        )

    if visible_exists:
        if hidden_damaged is not None:
            raise StorageResolutionError(
                f"Conflicting RecallLoom storage roots found under {project_root}: "
                f"{visible_root} is valid, but {hidden_root} is a damaged hidden sidecar. "
                "Resolve the conflict before continuing.",
                failure_reason="dual_sidecar_conflict",
            )
        data = load_and_validate_config(
            visible_config,
            VISIBLE_STORAGE_MODE,
            allow_unsupported_version=allow_unsupported_version,
            allow_storage_mode_mismatch=allow_storage_mode_mismatch,
        )
        return WorkspaceInfo(
            project_root=project_root,
            storage_root=visible_root,
            storage_mode=VISIBLE_STORAGE_MODE,
            workspace_language=data["workspace_language"],
            config_path=visible_config,
            declared_storage_mode=data["storage_mode"],
            storage_mode_matches_path=data["storage_mode_matches_path"],
            protocol_version=data["protocol_version"],
            protocol_version_supported=data["protocol_version_supported"],
        )

    if hidden_damaged is not None and visible_damaged is not None:
        raise StorageResolutionError(
            f"Detected conflicting damaged RecallLoom storage roots under {project_root}: "
            f"{hidden_root} and {visible_root}. Resolve the conflict before continuing.",
            failure_reason="dual_sidecar_conflict",
        )
    if hidden_damaged is not None:
        raise ConfigContractError(hidden_damaged, failure_reason="damaged_sidecar")
    if visible_damaged is not None:
        raise ConfigContractError(visible_damaged, failure_reason="damaged_sidecar")

    return None


def find_recallloom_root(
    start_path: str | Path,
    *,
    allow_unsupported_version: bool = False,
    allow_storage_mode_mismatch: bool = False,
) -> WorkspaceInfo | None:
    start = normalize_start_path(start_path)
    for candidate in (start, *start.parents):
        workspace = detect_workspace(
            candidate,
            allow_unsupported_version=allow_unsupported_version,
            allow_storage_mode_mismatch=allow_storage_mode_mismatch,
        )
        if workspace is not None:
            return workspace
    return None


def ensure_git_exclude_entry(project_root: Path, entry: str = f"{CONTEXT_DIRNAME}/") -> bool:
    git_dir = project_root / ".git"
    if not git_dir.is_dir():
        return False

    exclude_path = git_dir / "info" / "exclude"
    exclude_path.parent.mkdir(parents=True, exist_ok=True)
    block = [
        protocol_contracts.EXCLUDE_BLOCK_START,
        entry,
        protocol_contracts.EXCLUDE_BLOCK_END,
    ]
    if exclude_path.exists():
        current = read_text(exclude_path)
        ok, reason = bridge_blocks.exclude_block_integrity(current)
        if not ok:
            detail_map = {
                "exclude_start_end_mismatch": "managed block start/end markers are mismatched",
                "exclude_duplicate_blocks": "multiple managed exclude blocks are present",
                "exclude_order_invalid": "managed block markers are out of order",
            }
            detail = detail_map.get(reason, "the managed exclude block is malformed")
            raise ConfigContractError(
                f"Refusing to update .git/info/exclude because {detail}: {exclude_path}"
            )
        managed_block = bridge_blocks.managed_exclude_block_text(current)
        if managed_block is not None and entry in managed_block:
            return True
        text = current.rstrip("\n") + "\n\n" + "\n".join(block) + "\n"
        atomic_io.atomic_write_if_unchanged(exclude_path, expected_text=current, new_text=text)
    else:
        text = "\n".join(block) + "\n"
        write_text(exclude_path, text)
    return True


def remove_git_exclude_block(project_root: Path) -> bool:
    git_dir = project_root / ".git"
    if not git_dir.is_dir():
        return False

    exclude_path = git_dir / "info" / "exclude"
    if not exclude_path.exists():
        return False

    current = read_text(exclude_path)
    ok, reason = bridge_blocks.exclude_block_integrity(current)
    if not ok:
        detail_map = {
            "exclude_start_end_mismatch": "managed block start/end markers are mismatched",
            "exclude_duplicate_blocks": "multiple managed exclude blocks are present",
            "exclude_order_invalid": "managed block markers are out of order",
        }
        detail = detail_map.get(reason, "the managed exclude block is malformed")
        raise ConfigContractError(
            f"Refusing to update .git/info/exclude because {detail}: {exclude_path}"
        )

    if bridge_blocks.managed_exclude_block_text(current) is None:
        return False

    lines = current.splitlines()
    start_marker = protocol_contracts.EXCLUDE_BLOCK_START
    end_marker = protocol_contracts.EXCLUDE_BLOCK_END
    start_idx = lines.index(start_marker)
    end_idx = lines.index(end_marker, start_idx)
    new_lines = lines[:start_idx] + lines[end_idx + 1 :]
    text = "\n".join(new_lines).strip("\n")
    atomic_io.atomic_write_if_unchanged(exclude_path, expected_text=current, new_text=((text + "\n") if text else ""))
    return True


def known_storage_assets(
    storage_root: Path,
    *,
    required_files: tuple[str, ...],
    optional_files: tuple[str, ...],
    required_directories: tuple[str, ...],
    managed_directories: tuple[str, ...],
) -> set[Path]:
    assets: set[Path] = set()
    for rel_path in [
        *required_files,
        *optional_files,
        *required_directories,
        *managed_directories,
    ]:
        assets.add(storage_root / PurePosixPath(rel_path))
    return assets


def known_storage_asset_kind_map(
    storage_root: Path,
    *,
    required_files: tuple[str, ...],
    optional_files: tuple[str, ...],
    required_directories: tuple[str, ...],
    managed_directories: tuple[str, ...],
) -> dict[Path, str]:
    asset_kinds: dict[Path, str] = {}
    for rel_path in [*required_files, *optional_files]:
        asset_kinds[storage_root / PurePosixPath(rel_path)] = "file"
    for rel_path in required_directories:
        asset_kinds[storage_root / PurePosixPath(rel_path)] = "directory"
    for rel_path in managed_directories:
        asset_kinds[storage_root / PurePosixPath(rel_path)] = "directory"
    return asset_kinds


def matches_dynamic_storage_asset_rule(
    path: Path,
    storage_root: Path,
    *,
    dynamic_rules: tuple[dict[str, str], ...],
) -> bool:
    if not path.is_file():
        return False
    for rule in dynamic_rules:
        base_dir = storage_root / PurePosixPath(rule["base_dir"])
        if path.parent != base_dir:
            continue
        kind = rule["kind"]
        if kind == "iso_daily_log" and DATE_FILE_RE.match(path.name):
            try:
                date.fromisoformat(path.stem)
            except ValueError:
                continue
            return True
        if kind == "recovery_proposal" and RECOVERY_PROPOSAL_FILE_RE.match(path.name):
            return True
        if kind == "review_record" and REVIEW_RECORD_FILE_RE.match(path.name):
            return True
    return False


def _matches_dynamic_storage_asset_rule(
    path: Path,
    storage_root: Path,
    *,
    dynamic_rules: tuple[dict[str, str], ...],
) -> bool:
    return matches_dynamic_storage_asset_rule(
        path,
        storage_root,
        dynamic_rules=dynamic_rules,
    )


def is_official_temp_storage_asset(
    path: Path,
    storage_root: Path,
    *,
    required_files: tuple[str, ...],
    optional_files: tuple[str, ...],
    dynamic_rules: tuple[dict[str, str], ...],
) -> bool:
    if not path.is_file():
        return False
    if not path.name.startswith("."):
        return False
    candidate_name, sep, _suffix = path.name[1:].partition(".tmp-")
    if not sep or not candidate_name:
        return False

    for rel_path in [*required_files, *optional_files]:
        rel = PurePosixPath(rel_path)
        if rel.name != candidate_name:
            continue
        expected_parent = storage_root if rel.parent.as_posix() in {".", ""} else storage_root / rel.parent
        if path.parent == expected_parent:
            return True

    for rule in dynamic_rules:
        base_dir = storage_root / PurePosixPath(rule["base_dir"])
        if path.parent != base_dir:
            continue
        kind = rule["kind"]
        if kind == "iso_daily_log" and DATE_FILE_RE.match(candidate_name):
            try:
                date.fromisoformat(Path(candidate_name).stem)
            except ValueError:
                return False
            return True
        if kind == "recovery_proposal" and RECOVERY_PROPOSAL_FILE_RE.match(candidate_name):
            return True
        if kind == "review_record" and REVIEW_RECORD_FILE_RE.match(candidate_name):
            return True

    return False


def unknown_storage_assets(
    storage_root: Path,
    *,
    required_files: tuple[str, ...],
    optional_files: tuple[str, ...],
    required_directories: tuple[str, ...],
    managed_directories: tuple[str, ...],
    dynamic_rules: tuple[dict[str, str], ...],
) -> list[Path]:
    if not storage_root.is_dir():
        return []
    known = known_storage_asset_kind_map(
        storage_root,
        required_files=required_files,
        optional_files=optional_files,
        required_directories=required_directories,
        managed_directories=managed_directories,
    )
    unknown: list[Path] = []

    for path in sorted(storage_root.rglob("*")):
        if path.name == ".DS_Store":
            continue
        if is_official_temp_storage_asset(
            path,
            storage_root,
            required_files=required_files,
            optional_files=optional_files,
            dynamic_rules=dynamic_rules,
        ):
            continue
        expected_kind = known.get(path)
        if expected_kind == "file" and path.is_file():
            continue
        if expected_kind == "directory" and path.is_dir():
            continue
        if matches_dynamic_storage_asset_rule(
            path,
            storage_root,
            dynamic_rules=dynamic_rules,
        ):
            continue
        unknown.append(path)

    return unknown
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