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/input_transport.py

View on GitHub
"""Single input-acquisition owner for RecallLoom mutation input (T050-01B seed).

Frozen by the v0.5.0 unique construction plan (§7.2 public CLI x input mode,
§7.3 capsule wire + scratch handoff, §7.4 frozen callable contracts, §7.8
landing map row 01B/01C) and the Gate P freeze record §4
(``max_raw_bytes = 4096``, ``max_envelope_bytes = 5600``).

What lives here (single owner):

- The RLCP1 ASCII capsule decoder for the exact frozen wire form
  ``RLCP1:<role>:<raw_byte_length>:<raw_sha256>:<base64url_no_padding>`` with
  the frozen §7.3 validation order: ASCII -> five-segment structure -> role ->
  decimal length -> 64-hex lowercase digest -> base64url canonical re-encode
  -> P050-E1 limits (4096 raw / 5600 envelope) -> strict UTF-8. Every step has
  a typed rejection reason (P050-E1 evidence vocabulary, now product
  vocabulary). The decoder records the distinct evidence digests
  ``producer_raw_sha256`` / ``received_raw_sha256`` / ``canonical_text_sha256``
  and never passes a canonical digest off as a raw digest.
- The frozen ``AcquiredInput`` (§7.4): the only acquisition output of this
  module. Bytes and text stay strictly separated; ``source_identity`` is a
  path-independent stable identity; no field can leak a public-unsafe secret
  or host path.
- The two mutation helpers' legacy input acquisition (``read_limited_stdin``,
  ``read_limited_file_text``, ``load_prepared_text``, ``load_entry_source``)
  and their prepared-input failure mapping, extracted verbatim
  (extract -> delegate -> parity). The helpers keep thin delegating wrappers
  and remain the only layer that projects typed failures onto legacy exit
  codes; the helper originals are deleted only after V050-09/10 (§7.8). The
  existing safety validators in ``core/safety/prepared_input.py`` and
  ``core/safety/scratch_residue.py`` are reused as-is, never reimplemented or
  weakened.

Typed failure model: this module raises ``InputTransportError`` carrying the
exact legacy projection (message, blocked-reason family, exit code, details);
it never calls ``SystemExit`` and never imports ``scripts/`` or ``_common.py``
(core must not depend on adapter facades).

Derived (not contract-frozen) vocabulary introduced here, flagged for the
review record: ``capsule_role_mismatch`` (capsule role must equal the calling
command's operation), ``expected_input_digest_mismatch``,
``invalid_expected_input_digest``, ``missing_expected_input_digest``,
``prepared_input_ref_invalid``, and ``input_mode_not_available`` (fail-closed
reason while capsule/scratch mutation execution awaits the T050-04+ wiring).
``host_handoff_unavailable`` is the frozen §7.3 spelling. ``both_input_sources``
reuses the existing legacy conflict vocabulary.

T050-01C adds the §7.3 authenticated-scratch capability lifecycle, orchestrated
here without a second token/path/symlink owner: the file-level checks are the
single-owner primitives in ``core/safety/prepared_input.py``
(``lstat_regular_file_identity`` / ``read_stable_regular_file_bytes``) and the
residue report shapes come from ``core/safety/scratch_residue.py``. What lives
here (single orchestrator):

- The frozen ``PreparedInputHandoff`` (§7.4): frozen, deliberately
  non-serializable (no JSON/compact codec, no dict projection); the host
  ``write_target`` path never appears in any public payload.
- ``provision_prepared_input_capability`` (PROVISIONED row): dispatcher-callable;
  creates the external system-temp capability (mode 0700 token dir, random
  256-bit token, ``RLS1.<base64url>`` ref, open role/expiry/max_raw_bytes
  manifest, single empty ``content.bin``).
- Identity + stable-read acquisition (``acquire_prepared_input_scratch``) and
  the §7.3 state transitions: WRITTEN_UNCLAIMED -> CLAIMED
  (``claim_prepared_input_scratch``, product-owned atomic manifest temp+replace;
  validation failure keeps the capability open), CLAIMED -> open release with
  identity/digest re-check (``release_prepared_input_scratch_claim``), CLAIMED
  -> CONSUMED cleanup (``consume_prepared_input_scratch``; cleanup failure is
  an explicit public-safe diagnostic, never a false success), CLAIMED ->
  INSPECT_REQUIRED (``mark_prepared_input_scratch_inspect_required``;
  afterwards read-only, never auto-cleanup, never auto-replay), the read-only
  residue report (``inspect_prepared_input_scratch``) and the expiry residue
  scan (``scan_expired_prepared_input_capabilities``; reports only, never
  deletes unverified content). The manifest ``os.replace`` transition is the
  §7.3-assigned product-owned atomic claim, a non-write-path metadata replace
  owned here (registered for the T050-09A replace-audit allowlist).

Derived (not contract-frozen) 01C vocabulary, flagged for the review record:
``scratch_capability_missing`` / ``scratch_capability_invalid`` /
``scratch_capability_expired`` / ``scratch_capability_role_mismatch`` /
``scratch_capability_state_invalid`` / ``scratch_capability_provision_failed``
/ ``scratch_capability_transition_failed`` /
``scratch_capability_cleanup_failed``, the residue finding reasons
``prepared_input_capability_expired`` /
``prepared_input_capability_inspect_required`` /
``prepared_input_capability_malformed``, and the path category
``scratch_capability``. The manifest state spellings ``open`` / ``claimed`` /
``inspect_required`` follow §7.3 ("manifest.open -> manifest.claimed");
WRITTEN_UNCLAIMED is the logical open state after the host write returns (the
commit itself is the ready signal; no host-created ready marker). The 0700
directory mode is the POSIX shape proven by P050-E1; the Windows ACL-equivalent
verification is residual W1 (provisioning fails closed where the mode cannot
hold, and no trusted host integration exists on any host yet, so bare CLI
``--prepare-input`` stays ``host_handoff_unavailable`` everywhere today).
"""

from __future__ import annotations

import base64
from dataclasses import dataclass, replace
from datetime import datetime, timedelta, timezone
import hashlib
import json
import os
from pathlib import Path
import re
import secrets
import shutil
import stat
import sys
import tempfile
from typing import Optional

from core.failure.context import (
    COMMAND_APPEND,
    COMMAND_WRITE,
    OPERATION_DAILY_LOG_APPEND,
    OPERATION_DOMAIN,
    OPERATION_MANAGED_WRITE,
    STAGE_INPUT,
    OperationContext,
)
from core.safety.prepared_input import (
    MAX_SCRATCH_MARKER_BYTES,
    PreparedInputSafetyError,
    PreparedInputSource,
    RegularFileIdentity,
    read_prepared_input_source_text,
    read_stable_regular_file_bytes,
    validate_prepared_input_source_path,
)
from core.safety.scratch_residue import (
    MAX_RESIDUE_COUNT,
    ScratchResidueFinding,
    ScratchResidueReport,
    public_scratch_path_ref,
)


# --- frozen capsule wire constants (§7.3 + Gate P freeze record §4) ----------

CAPSULE_WIRE_PREFIX = "RLCP1"
CAPSULE_MAX_RAW_BYTES = 4096
CAPSULE_MAX_ENVELOPE_BYTES = 5600
# Dispatcher legacy stdin has no frozen lower limit. Keep its established
# 4 MiB default owned beside the byte-level acquisition primitive.
DEFAULT_STDIN_MAX_INPUT_BYTES = 4 * 1024 * 1024

# Input-mode vocabulary. The legacy channel spellings ("entry-json", "file",
# "stdin") predate v0.5.0 and stay byte-identical; "capsule" and "scratch" are
# the additive §7.2 channels.
INPUT_MODE_ENTRY_JSON = "entry-json"
INPUT_MODE_FILE = "file"
INPUT_MODE_STDIN = "stdin"
INPUT_MODE_CAPSULE = "capsule"
INPUT_MODE_SCRATCH = "scratch"
INPUT_MODE_DOMAIN = frozenset(
    (
        INPUT_MODE_ENTRY_JSON,
        INPUT_MODE_FILE,
        INPUT_MODE_STDIN,
        INPUT_MODE_CAPSULE,
        INPUT_MODE_SCRATCH,
    )
)

# Decoder typed rejection vocabulary (P050-E1 evidence names; the §7.3
# validation order fixes the sequence in which they fire).
CAPSULE_NOT_ASCII = "capsule_not_ascii"
CAPSULE_STRUCTURE_INVALID = "capsule_structure_invalid"
CAPSULE_ROLE_INVALID = "role_invalid"
CAPSULE_ROLE_MISMATCH = "capsule_role_mismatch"
CAPSULE_LENGTH_INVALID = "capsule_length_invalid"
CAPSULE_DIGEST_INVALID = "capsule_digest_invalid"
CAPSULE_BASE64_NOT_CANONICAL = "capsule_base64_not_canonical"
CAPSULE_LENGTH_MISMATCH = "capsule_length_mismatch"
CAPSULE_DIGEST_MISMATCH = "capsule_digest_mismatch"
CAPSULE_ENVELOPE_TOO_LONG = "capsule_envelope_too_long"
CAPSULE_RAW_TOO_LONG = "capsule_raw_too_long"
CAPSULE_NOT_UTF8 = "capsule_not_utf8"
EXPECTED_INPUT_DIGEST_MISMATCH = "expected_input_digest_mismatch"

# Input-transport failure vocabulary shared with the dispatcher matrix (the
# first is the frozen §7.3 spelling; "both_input_sources" is legacy vocabulary).
REASON_HOST_HANDOFF_UNAVAILABLE = "host_handoff_unavailable"
REASON_INPUT_MODE_NOT_AVAILABLE = "input_mode_not_available"
REASON_INVALID_EXPECTED_INPUT_DIGEST = "invalid_expected_input_digest"
REASON_MISSING_EXPECTED_INPUT_DIGEST = "missing_expected_input_digest"
REASON_PREPARED_INPUT_REF_INVALID = "prepared_input_ref_invalid"
REASON_BOTH_INPUT_SOURCES = "both_input_sources"
REASON_MISSING_INPUT_SOURCE = "missing_input_source"

# --expected-input-digest is a 64-char lowercase SHA-256 hex (§7.2).
EXPECTED_INPUT_DIGEST_RE = re.compile(r"^[0-9a-f]{64}$")

# prepared_input_ref is exactly "RLS1.<base64url 256-bit token, no padding>"
# (§7.3): no path, no role, no user text.
PREPARED_INPUT_REF_PREFIX = "RLS1."
PREPARED_INPUT_REF_TOKEN_BYTES = 32


class InputTransportError(Exception):
    """Typed acquisition failure carrying the exact legacy exit projection.

    Helpers and the dispatcher adapter project ``message`` / ``reason`` /
    ``exit_code`` / ``details`` onto the existing failure contract
    (``invalid_prepared_input`` family, exit 2); this module never raises
    ``SystemExit`` itself.
    """

    def __init__(
        self,
        *,
        message: str,
        reason: str = "invalid_prepared_input",
        exit_code: int = 2,
        details: Optional[dict] = None,
    ) -> None:
        self.message = message
        self.reason = reason
        self.exit_code = exit_code
        self.details = details
        super().__init__(message)

    @property
    def reason_code(self) -> Optional[str]:
        """The typed ``details.reason_code``, when the failure carries one."""
        if isinstance(self.details, dict):
            value = self.details.get("reason_code")
            if isinstance(value, str):
                return value
        return None


@dataclass(frozen=True)
class AcquiredInput:
    """Frozen §7.4 acquisition output (single representation of any input).

    ``raw_bytes`` / ``decoded_text`` / ``canonical_text`` are strictly
    separated; the digests are independently computed evidence (a canonical
    digest never masquerades as a raw digest). ``producer_raw_sha256`` is the
    producer-declared digest and exists only for channels that carry one
    (capsule today); it must equal ``received_raw_sha256`` because the decoder
    rejects mismatches before construction. ``source_identity`` is a
    path-independent stable identity (the prepared-input public path ref for
    file channels); no field may carry a public-unsafe secret or host path.
    ``scratch_ref`` / ``scratch_disposition`` stay ``None`` until the §7.3
    scratch orchestration lands (T050-01C).
    """

    raw_bytes: bytes
    decoded_text: str
    canonical_text: str
    raw_byte_length: int
    producer_raw_sha256: Optional[str]
    received_raw_sha256: str
    canonical_text_sha256: str
    input_mode: str
    role: str
    source_identity: Optional[str]
    scratch_ref: Optional[str]
    scratch_disposition: Optional[str]

    def __post_init__(self) -> None:
        if self.role not in OPERATION_DOMAIN:
            raise ValueError(f"unknown input role: {self.role!r}")
        if self.input_mode not in INPUT_MODE_DOMAIN:
            raise ValueError(f"unknown input mode: {self.input_mode!r}")
        if not isinstance(self.raw_bytes, bytes):
            raise TypeError("raw_bytes must be bytes")
        if self.raw_byte_length != len(self.raw_bytes):
            raise ValueError("raw_byte_length must equal len(raw_bytes)")
        # decoded_text must be the exact strict UTF-8 decoding of raw_bytes
        # (raises UnicodeDecodeError, a ValueError, when that is impossible).
        if self.decoded_text != self.raw_bytes.decode("utf-8"):
            raise ValueError("decoded_text must be the strict UTF-8 decoding of raw_bytes")
        if self.received_raw_sha256 != _sha256_hex(self.raw_bytes):
            raise ValueError("received_raw_sha256 must be the SHA-256 of raw_bytes")
        if self.canonical_text_sha256 != _sha256_hex(self.canonical_text.encode("utf-8")):
            raise ValueError("canonical_text_sha256 must be the SHA-256 of canonical_text")
        if self.producer_raw_sha256 is not None:
            if not EXPECTED_INPUT_DIGEST_RE.match(self.producer_raw_sha256):
                raise ValueError("producer_raw_sha256 must be 64 lowercase hex")
            if self.producer_raw_sha256 != self.received_raw_sha256:
                raise ValueError(
                    "producer_raw_sha256 must equal received_raw_sha256 after validation"
                )


def _sha256_hex(data: bytes) -> str:
    return hashlib.sha256(data).hexdigest()


def acquired_input_from_text(
    *,
    text: str,
    input_mode: str,
    role: str,
    producer_raw_sha256: Optional[str] = None,
    source_identity: Optional[str] = None,
    scratch_ref: Optional[str] = None,
    scratch_disposition: Optional[str] = None,
) -> AcquiredInput:
    """Build a digest-consistent AcquiredInput for text-carrying channels."""
    raw = text.encode("utf-8")
    return AcquiredInput(
        raw_bytes=raw,
        decoded_text=text,
        canonical_text=text,
        raw_byte_length=len(raw),
        producer_raw_sha256=producer_raw_sha256,
        received_raw_sha256=_sha256_hex(raw),
        canonical_text_sha256=_sha256_hex(text.encode("utf-8")),
        input_mode=input_mode,
        role=role,
        source_identity=source_identity,
        scratch_ref=scratch_ref,
        scratch_disposition=scratch_disposition,
    )


# --- prepared-input failure mapping (extracted from both helpers, verbatim) --

def prepared_input_failure_details(
    error: PreparedInputSafetyError,
    *,
    input_mode: Optional[str] = None,
) -> dict[str, object]:
    """The single owner of PreparedInputSafetyError -> public details mapping."""
    details = error.details
    if input_mode is not None:
        details["input_mode"] = input_mode
    return details


def prepared_input_transport_error(
    error: PreparedInputSafetyError,
    *,
    input_mode: Optional[str] = None,
) -> InputTransportError:
    """Map a safety validator rejection onto the typed transport failure."""
    return InputTransportError(
        message=error.message,
        details=prepared_input_failure_details(error, input_mode=input_mode),
    )


# --- RLCP1 capsule decoder (§7.3, frozen validation order) -------------------

def _capsule_reject(
    reason_code: str,
    message: str,
    *,
    extra: Optional[dict] = None,
) -> InputTransportError:
    return InputTransportError(
        message=message,
        details={"reason_code": reason_code, "side_effect": "none", **(extra or {})},
    )


def decode_input_capsule(
    envelope: str,
    *,
    expected_role: Optional[str] = None,
    expected_digest: Optional[str] = None,
) -> AcquiredInput:
    """Decode one RLCP1 ASCII capsule in the frozen §7.3 validation order.

    ``expected_role`` binds the capsule role to the calling command's typed
    operation; ``expected_digest`` is the optional --expected-input-digest
    binding, compared against the capsule-carried raw digest (§7.2). Every
    rejection raises ``InputTransportError`` with a typed reason code; the
    capsule content itself is never echoed into failure details.
    """
    if not isinstance(envelope, str):
        raise TypeError("input capsule envelope must be a string")
    try:
        envelope.encode("ascii")
    except UnicodeEncodeError:
        raise _capsule_reject(
            CAPSULE_NOT_ASCII,
            "Input capsule is not pure ASCII; RLCP1 capsules must be ASCII-only.",
        )
    parts = envelope.split(":")
    if len(parts) != 5 or parts[0] != CAPSULE_WIRE_PREFIX:
        raise _capsule_reject(
            CAPSULE_STRUCTURE_INVALID,
            "Input capsule must use the wire form "
            "RLCP1:<role>:<raw_byte_length>:<raw_sha256>:<base64url_no_padding>.",
        )
    _, role, length_s, digest_s, body = parts
    if role not in OPERATION_DOMAIN:
        raise _capsule_reject(
            CAPSULE_ROLE_INVALID,
            "Input capsule role is not one of the frozen mutation roles "
            "(managed_write, daily_log_append, post_append_summary_sync).",
        )
    if expected_role is not None and role != expected_role:
        raise _capsule_reject(
            CAPSULE_ROLE_MISMATCH,
            f"Input capsule role {role!r} does not match this command's operation "
            f"{expected_role!r}.",
        )
    if not length_s.isdecimal():
        raise _capsule_reject(
            CAPSULE_LENGTH_INVALID,
            "Input capsule raw_byte_length segment is not a decimal byte count.",
        )
    if (
        len(digest_s) != 64
        or digest_s != digest_s.lower()
        or any(char not in "0123456789abcdef" for char in digest_s)
    ):
        raise _capsule_reject(
            CAPSULE_DIGEST_INVALID,
            "Input capsule raw_sha256 segment is not 64 lowercase hex characters.",
        )
    if expected_digest is not None and expected_digest != digest_s:
        raise _capsule_reject(
            EXPECTED_INPUT_DIGEST_MISMATCH,
            "Input capsule raw digest does not equal --expected-input-digest.",
        )
    try:
        raw = base64.urlsafe_b64decode(body + "=" * (-len(body) % 4))
    except ValueError:
        raise _capsule_reject(
            CAPSULE_BASE64_NOT_CANONICAL,
            "Input capsule payload is not canonical base64url without padding.",
        )
    if base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=") != body:
        raise _capsule_reject(
            CAPSULE_BASE64_NOT_CANONICAL,
            "Input capsule payload is not canonical base64url without padding.",
        )
    declared_length = int(length_s)
    if len(raw) != declared_length:
        raise _capsule_reject(
            CAPSULE_LENGTH_MISMATCH,
            "Input capsule declared raw_byte_length does not match the decoded "
            "payload length.",
            extra={
                "declared_raw_byte_length": declared_length,
                "received_raw_byte_length": len(raw),
            },
        )
    received_raw_sha256 = _sha256_hex(raw)
    if received_raw_sha256 != digest_s:
        raise _capsule_reject(
            CAPSULE_DIGEST_MISMATCH,
            "Input capsule raw_sha256 does not match the decoded payload bytes.",
        )
    if len(envelope) > CAPSULE_MAX_ENVELOPE_BYTES:
        raise _capsule_reject(
            CAPSULE_ENVELOPE_TOO_LONG,
            f"Input capsule envelope exceeds the frozen {CAPSULE_MAX_ENVELOPE_BYTES}-byte "
            "limit.",
            extra={
                "envelope_bytes": len(envelope),
                "max_envelope_bytes": CAPSULE_MAX_ENVELOPE_BYTES,
            },
        )
    if len(raw) > CAPSULE_MAX_RAW_BYTES:
        raise _capsule_reject(
            CAPSULE_RAW_TOO_LONG,
            f"Input capsule payload exceeds the frozen {CAPSULE_MAX_RAW_BYTES}-byte raw "
            "limit.",
            extra={
                "raw_byte_length": len(raw),
                "max_raw_bytes": CAPSULE_MAX_RAW_BYTES,
            },
        )
    try:
        text = raw.decode("utf-8", "strict")
    except UnicodeDecodeError:
        raise _capsule_reject(
            CAPSULE_NOT_UTF8,
            "Input capsule payload is not valid UTF-8.",
        )
    return AcquiredInput(
        raw_bytes=raw,
        decoded_text=text,
        canonical_text=text,
        raw_byte_length=len(raw),
        producer_raw_sha256=digest_s,
        received_raw_sha256=received_raw_sha256,
        canonical_text_sha256=_sha256_hex(text.encode("utf-8")),
        input_mode=INPUT_MODE_CAPSULE,
        role=role,
        source_identity=None,
        scratch_ref=None,
        scratch_disposition=None,
    )


def validate_prepared_input_ref_shape(ref: str) -> None:
    """Enforce the frozen ``RLS1.<base64url-256-bit-token>`` ref shape (§7.3).

    Shape validation only: no path, role, or user text may ride in the ref,
    and the token must be a canonical no-padding base64url encoding of exactly
    256 bits. Raises ``InputTransportError`` with reason
    ``prepared_input_ref_invalid``.
    """
    if not isinstance(ref, str):
        raise TypeError("prepared input ref must be a string")
    token = None
    if ref.startswith(PREPARED_INPUT_REF_PREFIX):
        token = ref[len(PREPARED_INPUT_REF_PREFIX):]
    if not token:
        raise InputTransportError(
            message="--prepared-input-ref must use the form RLS1.<base64url-256-bit-token>.",
            details={"reason_code": REASON_PREPARED_INPUT_REF_INVALID, "side_effect": "none"},
        )
    try:
        raw = base64.urlsafe_b64decode(token + "=" * (-len(token) % 4))
    except ValueError:
        raw = b""
    if (
        len(raw) != PREPARED_INPUT_REF_TOKEN_BYTES
        or base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=") != token
    ):
        raise InputTransportError(
            message="--prepared-input-ref must use the form RLS1.<base64url-256-bit-token>.",
            details={"reason_code": REASON_PREPARED_INPUT_REF_INVALID, "side_effect": "none"},
        )


# --- §7.3 authenticated scratch capability orchestration (T050-01C) ----------
#
# Single orchestrator for the external system-temp capability lifecycle
# PROVISIONED -> WRITTEN_UNCLAIMED -> CLAIMED -> CONSUMED / INSPECT_REQUIRED.
# File-level token/path/link/identity checks stay with their single owner
# core/safety/prepared_input.py; residue report shapes stay with
# core/safety/scratch_residue.py. None of this is wired into mutation
# execution (T050-04+): the claim path is the product-owned primitive the
# transaction will call inside the identity lock, and dry-run/preview callers
# must only ever run the read-only acquisition, never claim/consume.

SCRATCH_CAPABILITY_DIR_PREFIX = "recallloom-prepared-input-"
SCRATCH_CONTENT_FILENAME = "content.bin"
SCRATCH_MANIFEST_FILENAME = "manifest.json"
SCRATCH_MANIFEST_SCHEMA_VERSION = "recallloom.prepared-input/1.0"
SCRATCH_MANIFEST_MAX_BYTES = MAX_SCRATCH_MARKER_BYTES

# Manifest state spellings (§7.3 "manifest.open -> manifest.claimed").
SCRATCH_STATE_OPEN = "open"
SCRATCH_STATE_CLAIMED = "claimed"
SCRATCH_STATE_INSPECT_REQUIRED = "inspect_required"
SCRATCH_STATE_DOMAIN = frozenset(
    (SCRATCH_STATE_OPEN, SCRATCH_STATE_CLAIMED, SCRATCH_STATE_INSPECT_REQUIRED)
)

# §7.3 logical dispositions (AcquiredInput.scratch_disposition / reports).
SCRATCH_DISPOSITION_PROVISIONED = "provisioned"
SCRATCH_DISPOSITION_WRITTEN_UNCLAIMED = "written_unclaimed"
SCRATCH_DISPOSITION_CLAIMED = "claimed"
SCRATCH_DISPOSITION_INSPECT_REQUIRED = "inspect_required"
SCRATCH_DISPOSITION_CONSUMED = "consumed"

# Derived typed failure vocabulary (flagged in the module docstring).
REASON_SCRATCH_CAPABILITY_MISSING = "scratch_capability_missing"
REASON_SCRATCH_CAPABILITY_INVALID = "scratch_capability_invalid"
REASON_SCRATCH_CAPABILITY_EXPIRED = "scratch_capability_expired"
REASON_SCRATCH_CAPABILITY_ROLE_MISMATCH = "scratch_capability_role_mismatch"
REASON_SCRATCH_CAPABILITY_STATE_INVALID = "scratch_capability_state_invalid"
REASON_SCRATCH_CAPABILITY_PROVISION_FAILED = "scratch_capability_provision_failed"
REASON_SCRATCH_CAPABILITY_TRANSITION_FAILED = "scratch_capability_transition_failed"
REASON_SCRATCH_CAPABILITY_CLEANUP_FAILED = "scratch_capability_cleanup_failed"

SCRATCH_PATH_CATEGORY = "scratch_capability"

# Derived residue finding reasons (report-only; scratch_residue shapes).
SCRATCH_FINDING_EXPIRED = "prepared_input_capability_expired"
SCRATCH_FINDING_INSPECT_REQUIRED = "prepared_input_capability_inspect_required"
SCRATCH_FINDING_MALFORMED = "prepared_input_capability_malformed"


def _utc_now() -> datetime:
    return datetime.now(timezone.utc)


def _iso_utc(instant: datetime) -> str:
    return instant.astimezone(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")


def _parse_iso_utc(value: object) -> datetime:
    if not isinstance(value, str):
        raise ValueError("timestamp must be an ISO-8601 string")
    text = value[:-1] + "+00:00" if value.endswith("Z") else value
    parsed = datetime.fromisoformat(text)
    if parsed.tzinfo is None:
        raise ValueError("timestamp must be timezone-aware")
    return parsed.astimezone(timezone.utc)


def _scratch_reject(
    reason_code: str,
    message: str,
    *,
    extra: Optional[dict] = None,
) -> InputTransportError:
    return InputTransportError(
        message=message,
        details={"reason_code": reason_code, "side_effect": "none", **(extra or {})},
    )


def _scratch_temp_root(temp_root: Optional[Path]) -> Path:
    return Path(temp_root) if temp_root is not None else Path(tempfile.gettempdir())


@dataclass(frozen=True)
class PreparedInputHandoff:
    """Frozen §7.4 prepared-input handoff (trusted host integration only).

    Frozen and deliberately non-serializable: there is no JSON/compact codec
    and no dict projection, so the host ``write_target`` path can never ride
    into public output. Public payloads only ever carry ``ref`` /
    ``expires_at`` / ``max_raw_bytes`` (§7.3). A bare CLI never obtains this
    object; only the dispatcher's trusted in-process host integration does.
    """

    ref: str
    write_target: Path
    role: str
    expires_at: str
    max_raw_bytes: int

    def __repr__(self) -> str:
        # The host path must never leak, even into logs/diagnostics.
        return (
            f"PreparedInputHandoff(ref={self.ref!r}, write_target=<host-only>, "
            f"role={self.role!r}, expires_at={self.expires_at!r}, "
            f"max_raw_bytes={self.max_raw_bytes!r})"
        )

    def __post_init__(self) -> None:
        validate_prepared_input_ref_shape(self.ref)
        if not isinstance(self.write_target, Path):
            raise TypeError("write_target must be a pathlib.Path")
        if self.role not in OPERATION_DOMAIN:
            raise ValueError(f"unknown input role: {self.role!r}")
        _parse_iso_utc(self.expires_at)
        if isinstance(self.max_raw_bytes, bool) or not isinstance(self.max_raw_bytes, int):
            raise TypeError("max_raw_bytes must be an int")
        if self.max_raw_bytes <= 0:
            raise ValueError("max_raw_bytes must be positive")


def scratch_capability_dir_for_ref(ref: str, *, temp_root: Optional[Path] = None) -> Path:
    """Resolve the capability dir for a shape-valid RLS1 ref (path math only)."""
    validate_prepared_input_ref_shape(ref)
    token = ref[len(PREPARED_INPUT_REF_PREFIX):]
    return _scratch_temp_root(temp_root) / (SCRATCH_CAPABILITY_DIR_PREFIX + token)


def provision_prepared_input_capability(
    *,
    role: str,
    max_raw_bytes: int,
    ttl_seconds: int,
    temp_root: Optional[Path] = None,
    now: Optional[datetime] = None,
) -> PreparedInputHandoff:
    """Create the §7.3 PROVISIONED external system-temp capability.

    Mode 0700 token dir, random 256-bit token, ``RLS1.<base64url>`` ref, an
    open role/expiry/max_raw_bytes manifest and a single empty
    ``content.bin`` write target. Returns the frozen non-serializable
    ``PreparedInputHandoff``; only a trusted in-process host integration may
    receive it (a bare CLI must stay ``host_handoff_unavailable``).
    """
    if role not in OPERATION_DOMAIN:
        raise ValueError(f"unknown input role: {role!r}")
    if isinstance(max_raw_bytes, bool) or not isinstance(max_raw_bytes, int) or max_raw_bytes <= 0:
        raise ValueError("max_raw_bytes must be a positive int")
    if isinstance(ttl_seconds, bool) or not isinstance(ttl_seconds, int) or ttl_seconds <= 0:
        raise ValueError("ttl_seconds must be a positive int")
    created = now if now is not None else _utc_now()
    expires = created + timedelta(seconds=ttl_seconds)
    token = secrets.token_bytes(PREPARED_INPUT_REF_TOKEN_BYTES)
    ref = PREPARED_INPUT_REF_PREFIX + base64.urlsafe_b64encode(token).decode("ascii").rstrip("=")
    capability_dir = _scratch_temp_root(temp_root) / (
        SCRATCH_CAPABILITY_DIR_PREFIX + ref[len(PREPARED_INPUT_REF_PREFIX):]
    )
    try:
        os.mkdir(capability_dir, 0o700)
    except OSError as exc:
        raise _scratch_reject(
            REASON_SCRATCH_CAPABILITY_PROVISION_FAILED,
            "Could not create the prepared-input capability directory; nothing was provisioned.",
            extra={"errno": exc.errno if exc.errno is not None else 5},
        ) from exc
    try:
        _validate_scratch_capability_dir(capability_dir)
        content_fd = os.open(
            capability_dir / SCRATCH_CONTENT_FILENAME,
            os.O_WRONLY | os.O_CREAT | os.O_EXCL,
            0o600,
        )
        os.close(content_fd)
        _write_scratch_manifest_atomic(
            capability_dir,
            {
                "schema_version": SCRATCH_MANIFEST_SCHEMA_VERSION,
                "ref": ref,
                "role": role,
                "state": SCRATCH_STATE_OPEN,
                "created_at": _iso_utc(created),
                "expires_at": _iso_utc(expires),
                "max_raw_bytes": max_raw_bytes,
            },
        )
    except Exception:
        # Only the directory this call just created is removed, best effort.
        shutil.rmtree(capability_dir, ignore_errors=True)
        raise
    return PreparedInputHandoff(
        ref=ref,
        write_target=capability_dir / SCRATCH_CONTENT_FILENAME,
        role=role,
        expires_at=_iso_utc(expires),
        max_raw_bytes=max_raw_bytes,
    )


def _validate_scratch_capability_dir(capability_dir: Path) -> str:
    """lstat the capability dir (0700, real directory); return its public ref."""
    path_ref = public_scratch_path_ref(capability_dir)
    try:
        dir_lstat = capability_dir.lstat()
    except FileNotFoundError:
        raise _scratch_reject(
            REASON_SCRATCH_CAPABILITY_MISSING,
            "Prepared input capability does not exist (unknown or already consumed ref).",
            extra={"path_ref": path_ref},
        )
    except OSError as exc:
        raise _scratch_reject(
            REASON_SCRATCH_CAPABILITY_INVALID,
            "Prepared input capability directory could not be inspected.",
            extra={"path_ref": path_ref, "errno": exc.errno if exc.errno is not None else 5},
        )
    if stat.S_ISLNK(dir_lstat.st_mode) or not stat.S_ISDIR(dir_lstat.st_mode):
        raise _scratch_reject(
            REASON_SCRATCH_CAPABILITY_INVALID,
            "Prepared input capability path is not a product-created directory.",
            extra={"path_ref": path_ref},
        )
    if stat.S_IMODE(dir_lstat.st_mode) != 0o700:
        raise _scratch_reject(
            REASON_SCRATCH_CAPABILITY_INVALID,
            "Prepared input capability directory does not have mode 0700.",
            extra={"path_ref": path_ref},
        )
    return path_ref


def _write_scratch_manifest_atomic(capability_dir: Path, manifest: dict) -> None:
    """Product-owned atomic manifest transition: same-dir temp file + replace.

    A failure before the replace leaves the previous manifest byte-identical,
    so the capability keeps its prior state and a partial transition is never
    replayable.
    """
    manifest_path = capability_dir / SCRATCH_MANIFEST_FILENAME
    temp_path = capability_dir / (SCRATCH_MANIFEST_FILENAME + ".tmp")
    data = json.dumps(manifest, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode("ascii")
    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
    if hasattr(os, "O_NOFOLLOW"):
        flags |= os.O_NOFOLLOW
    try:
        fd = os.open(temp_path, flags, 0o600)
    except OSError as exc:
        raise _scratch_reject(
            REASON_SCRATCH_CAPABILITY_TRANSITION_FAILED,
            "Prepared input manifest transition failed before commit; prior state is unchanged.",
            extra={"errno": exc.errno if exc.errno is not None else 5},
        ) from exc
    try:
        with os.fdopen(fd, "wb") as handle:
            if not stat.S_ISREG(os.fstat(handle.fileno()).st_mode):
                raise _scratch_reject(
                    REASON_SCRATCH_CAPABILITY_TRANSITION_FAILED,
                    "Prepared input manifest transition failed before commit; prior state is unchanged.",
                )
            handle.write(data)
            handle.flush()
            os.fsync(handle.fileno())
        os.replace(temp_path, manifest_path)
    except InputTransportError:
        raise
    except OSError as exc:
        raise _scratch_reject(
            REASON_SCRATCH_CAPABILITY_TRANSITION_FAILED,
            "Prepared input manifest transition failed before commit; prior state is unchanged.",
            extra={"errno": exc.errno if exc.errno is not None else 5},
        ) from exc


def _load_scratch_manifest(capability_dir: Path, *, ref: str, path_ref: str) -> dict:
    """Read and strictly validate the capability manifest (stable read)."""
    try:
        raw, _identity = read_stable_regular_file_bytes(
            capability_dir / SCRATCH_MANIFEST_FILENAME,
            max_input_bytes=SCRATCH_MANIFEST_MAX_BYTES,
            label="scratch manifest",
            path_category=SCRATCH_PATH_CATEGORY,
            path_ref=path_ref,
        )
    except PreparedInputSafetyError as exc:
        raise prepared_input_transport_error(exc, input_mode=INPUT_MODE_SCRATCH) from exc

    def invalid(message: str) -> InputTransportError:
        return _scratch_reject(
            REASON_SCRATCH_CAPABILITY_INVALID, message, extra={"path_ref": path_ref}
        )

    try:
        manifest = json.loads(raw.decode("utf-8"))
    except (UnicodeDecodeError, json.JSONDecodeError):
        raise invalid("Prepared input manifest is not valid UTF-8 JSON.")
    if not isinstance(manifest, dict):
        raise invalid("Prepared input manifest is not a JSON object.")
    if manifest.get("schema_version") != SCRATCH_MANIFEST_SCHEMA_VERSION:
        raise invalid("Prepared input manifest schema_version is not supported.")
    if manifest.get("ref") != ref:
        raise invalid("Prepared input manifest does not match the requested ref.")
    if manifest.get("role") not in OPERATION_DOMAIN:
        raise invalid("Prepared input manifest carries an unknown role.")
    if manifest.get("state") not in SCRATCH_STATE_DOMAIN:
        raise invalid("Prepared input manifest carries an unknown state.")
    try:
        _parse_iso_utc(manifest.get("created_at"))
        _parse_iso_utc(manifest.get("expires_at"))
    except ValueError:
        raise invalid("Prepared input manifest timestamps are not valid ISO-8601 UTC.")
    max_raw_bytes = manifest.get("max_raw_bytes")
    if (
        isinstance(max_raw_bytes, bool)
        or not isinstance(max_raw_bytes, int)
        or max_raw_bytes <= 0
    ):
        raise invalid("Prepared input manifest max_raw_bytes is not a positive int.")
    if manifest["state"] in (SCRATCH_STATE_CLAIMED, SCRATCH_STATE_INSPECT_REQUIRED):
        claimed_digest = manifest.get("claimed_raw_sha256")
        if not isinstance(claimed_digest, str) or not EXPECTED_INPUT_DIGEST_RE.match(claimed_digest):
            raise invalid("Prepared input manifest claim record has no valid content digest.")
        claimed_identity = manifest.get("claimed_identity")
        if not isinstance(claimed_identity, dict) or any(
            isinstance(claimed_identity.get(key), bool)
            or not isinstance(claimed_identity.get(key), int)
            or claimed_identity[key] < 0
            for key in ("st_dev", "st_ino", "st_size")
        ):
            raise invalid("Prepared input manifest claim record has no valid identity.")
        try:
            _parse_iso_utc(manifest.get("claimed_at"))
        except ValueError:
            raise invalid("Prepared input manifest claim record timestamp is invalid.")
    return manifest


def _read_scratch_content(
    capability_dir: Path,
    manifest: dict,
    *,
    path_ref: str,
) -> tuple[bytes, RegularFileIdentity]:
    """Stable-read content.bin under the single-owner identity checks."""
    try:
        return read_stable_regular_file_bytes(
            capability_dir / SCRATCH_CONTENT_FILENAME,
            max_input_bytes=manifest["max_raw_bytes"],
            label="scratch content",
            path_category=SCRATCH_PATH_CATEGORY,
            path_ref=path_ref,
        )
    except PreparedInputSafetyError as exc:
        raise prepared_input_transport_error(exc, input_mode=INPUT_MODE_SCRATCH) from exc


def _validated_open_scratch(
    ref: str,
    *,
    expected_role: str,
    temp_root: Optional[Path],
    now: Optional[datetime],
) -> tuple[Path, dict, str]:
    capability_dir = scratch_capability_dir_for_ref(ref, temp_root=temp_root)
    path_ref = _validate_scratch_capability_dir(capability_dir)
    manifest = _load_scratch_manifest(capability_dir, ref=ref, path_ref=path_ref)
    state = manifest["state"]
    if state != SCRATCH_STATE_OPEN:
        raise _scratch_reject(
            REASON_SCRATCH_CAPABILITY_STATE_INVALID,
            f"Prepared input capability is {state}, not open; claimed or inspect-required "
            "capabilities are never auto-replayed.",
            extra={"path_ref": path_ref, "capability_state": state},
        )
    if manifest["role"] != expected_role:
        raise _scratch_reject(
            REASON_SCRATCH_CAPABILITY_ROLE_MISMATCH,
            f"Prepared input capability role {manifest['role']!r} does not match this "
            f"command's operation {expected_role!r}.",
            extra={"path_ref": path_ref},
        )
    current = now if now is not None else _utc_now()
    if current > _parse_iso_utc(manifest["expires_at"]):
        raise _scratch_reject(
            REASON_SCRATCH_CAPABILITY_EXPIRED,
            "Prepared input capability has expired; it is reported as residue and never "
            "silently deleted.",
            extra={"path_ref": path_ref, "expires_at": manifest["expires_at"]},
        )
    return capability_dir, manifest, path_ref


def _acquire_scratch(
    *,
    ref: str,
    expected_role: str,
    expected_digest: Optional[str],
    temp_root: Optional[Path],
    now: Optional[datetime],
) -> tuple[AcquiredInput, Path, dict, RegularFileIdentity, str]:
    capability_dir, manifest, path_ref = _validated_open_scratch(
        ref,
        expected_role=expected_role,
        temp_root=temp_root,
        now=now,
    )
    raw, identity = _read_scratch_content(capability_dir, manifest, path_ref=path_ref)
    try:
        text = raw.decode("utf-8", "strict")
    except UnicodeDecodeError:
        raise _scratch_reject(
            "source_path_not_utf8",
            "Prepared input scratch content is not valid UTF-8.",
            extra={"path_ref": path_ref},
        )
    if expected_digest is not None:
        if not EXPECTED_INPUT_DIGEST_RE.match(expected_digest):
            raise _scratch_reject(
                REASON_INVALID_EXPECTED_INPUT_DIGEST,
                "--expected-input-digest must be a 64-character lowercase SHA-256 hex digest.",
            )
        if _sha256_hex(raw) != expected_digest:
            raise _scratch_reject(
                EXPECTED_INPUT_DIGEST_MISMATCH,
                "Prepared input scratch content digest does not equal --expected-input-digest.",
                extra={"path_ref": path_ref},
            )
    acquired = acquired_input_from_text(
        text=text,
        input_mode=INPUT_MODE_SCRATCH,
        role=expected_role,
        producer_raw_sha256=expected_digest,
        source_identity=ref,
        scratch_ref=ref,
        scratch_disposition=SCRATCH_DISPOSITION_WRITTEN_UNCLAIMED,
    )
    return acquired, capability_dir, manifest, identity, path_ref


def acquire_prepared_input_scratch(
    *,
    ref: str,
    expected_role: str,
    expected_digest: Optional[str] = None,
    temp_root: Optional[Path] = None,
    now: Optional[datetime] = None,
) -> AcquiredInput:
    """Read-only WRITTEN_UNCLAIMED acquisition (the only dry-run/preview form).

    Validates ref/dir/manifest/state/role/expiry, stable-reads the content
    under the single-owner identity checks, and binds the optional
    --expected-input-digest. Never writes the manifest, never touches the
    content, and never claims: scratch bytes and status are unchanged.
    """
    acquired, _dir, _manifest, _identity, _path_ref = _acquire_scratch(
        ref=ref,
        expected_role=expected_role,
        expected_digest=expected_digest,
        temp_root=temp_root,
        now=now,
    )
    return acquired


def claim_prepared_input_scratch(
    *,
    ref: str,
    expected_role: str,
    expected_digest: Optional[str],
    temp_root: Optional[Path] = None,
    now: Optional[datetime] = None,
) -> AcquiredInput:
    """WRITTEN_UNCLAIMED -> CLAIMED via the product-owned atomic transition.

    The caller holds the workspace identity lock (T050-04+); the commit
    itself is the ready signal (no host-created marker). Any validation
    failure keeps the capability open; the claim record binds the exact
    content digest and identity that were stably read.
    """
    if expected_digest is None:
        raise _scratch_reject(
            REASON_MISSING_EXPECTED_INPUT_DIGEST,
            "Scratch commit requires --expected-input-digest (64 lowercase hex).",
        )
    acquired, capability_dir, manifest, identity, path_ref = _acquire_scratch(
        ref=ref,
        expected_role=expected_role,
        expected_digest=expected_digest,
        temp_root=temp_root,
        now=now,
    )
    claim_instant = now if now is not None else _utc_now()
    _write_scratch_manifest_atomic(
        capability_dir,
        {
            "schema_version": SCRATCH_MANIFEST_SCHEMA_VERSION,
            "ref": ref,
            "role": manifest["role"],
            "state": SCRATCH_STATE_CLAIMED,
            "created_at": manifest["created_at"],
            "expires_at": manifest["expires_at"],
            "max_raw_bytes": manifest["max_raw_bytes"],
            "claimed_at": _iso_utc(claim_instant),
            "claimed_raw_sha256": acquired.received_raw_sha256,
            "claimed_identity": {
                "st_dev": identity.st_dev,
                "st_ino": identity.st_ino,
                "st_size": identity.st_size,
            },
        },
    )
    reloaded = _load_scratch_manifest(capability_dir, ref=ref, path_ref=path_ref)
    if (
        reloaded.get("state") != SCRATCH_STATE_CLAIMED
        or reloaded.get("claimed_raw_sha256") != acquired.received_raw_sha256
    ):
        raise _scratch_reject(
            REASON_SCRATCH_CAPABILITY_TRANSITION_FAILED,
            "Prepared input claim transition could not be verified; the capability is "
            "left for inspection and never auto-replayed.",
            extra={"path_ref": path_ref},
        )
    return replace(acquired, scratch_disposition=SCRATCH_DISPOSITION_CLAIMED)


def _load_claimed_scratch(
    ref: str,
    *,
    temp_root: Optional[Path],
) -> tuple[Path, dict, str]:
    capability_dir = scratch_capability_dir_for_ref(ref, temp_root=temp_root)
    path_ref = _validate_scratch_capability_dir(capability_dir)
    manifest = _load_scratch_manifest(capability_dir, ref=ref, path_ref=path_ref)
    if manifest["state"] != SCRATCH_STATE_CLAIMED:
        raise _scratch_reject(
            REASON_SCRATCH_CAPABILITY_STATE_INVALID,
            f"Prepared input capability is {manifest['state']}, not claimed.",
            extra={"path_ref": path_ref, "capability_state": manifest["state"]},
        )
    return capability_dir, manifest, path_ref


def _verify_claimed_content_unchanged(
    capability_dir: Path,
    manifest: dict,
    *,
    path_ref: str,
) -> None:
    """Re-check the claimed content identity/digest (rotate/refuse on drift)."""
    raw, identity = _read_scratch_content(capability_dir, manifest, path_ref=path_ref)
    claimed_identity = manifest["claimed_identity"]
    if (
        _sha256_hex(raw) != manifest["claimed_raw_sha256"]
        or identity.st_dev != claimed_identity["st_dev"]
        or identity.st_ino != claimed_identity["st_ino"]
        or identity.st_size != claimed_identity["st_size"]
    ):
        raise _scratch_reject(
            "source_path_changed_after_validation",
            "Prepared input scratch content changed after the claim; refusing to reopen "
            "or consume unverified content.",
            extra={"path_ref": path_ref},
        )


def release_prepared_input_scratch_claim(
    *,
    ref: str,
    temp_root: Optional[Path] = None,
) -> None:
    """CLAIMED -> open release after a pre-mutation failure.

    Allowed only when the content identity/digest still exactly match the
    claim record; on any drift the capability stays claimed and the release
    is refused (§7.3 rotate/refuse, never an automatic replay).
    """
    capability_dir, manifest, path_ref = _load_claimed_scratch(ref, temp_root=temp_root)
    _verify_claimed_content_unchanged(capability_dir, manifest, path_ref=path_ref)
    _write_scratch_manifest_atomic(
        capability_dir,
        {
            "schema_version": SCRATCH_MANIFEST_SCHEMA_VERSION,
            "ref": ref,
            "role": manifest["role"],
            "state": SCRATCH_STATE_OPEN,
            "created_at": manifest["created_at"],
            "expires_at": manifest["expires_at"],
            "max_raw_bytes": manifest["max_raw_bytes"],
        },
    )


def consume_prepared_input_scratch(
    *,
    ref: str,
    temp_root: Optional[Path] = None,
) -> str:
    """CLAIMED -> CONSUMED cleanup after final evidence passed.

    Re-verifies the claimed identity/digest before deleting (never silently
    deletes unverified content). A deletion failure raises a typed diagnostic
    carrying the public-safe residue ref; it must be surfaced explicitly and
    never folded into a transaction false success (§7.3 CONSUMED row).
    """
    capability_dir, manifest, path_ref = _load_claimed_scratch(ref, temp_root=temp_root)
    _verify_claimed_content_unchanged(capability_dir, manifest, path_ref=path_ref)
    try:
        (capability_dir / SCRATCH_CONTENT_FILENAME).unlink()
        (capability_dir / SCRATCH_MANIFEST_FILENAME).unlink()
        capability_dir.rmdir()
    except OSError as exc:
        raise InputTransportError(
            message=(
                "Prepared input capability cleanup failed after a successful mutation; "
                "the residue is reported and never silently retried."
            ),
            details={
                "reason_code": REASON_SCRATCH_CAPABILITY_CLEANUP_FAILED,
                "side_effect": "none",
                "path_ref": path_ref,
                "scratch_ref": ref,
                "errno": exc.errno if exc.errno is not None else 5,
            },
        ) from exc
    return SCRATCH_DISPOSITION_CONSUMED


def mark_prepared_input_scratch_inspect_required(
    *,
    ref: str,
    temp_root: Optional[Path] = None,
    now: Optional[datetime] = None,
) -> None:
    """CLAIMED -> INSPECT_REQUIRED after a target attempt or partial evidence.

    Afterwards the capability is inspect-first residue: read-only, never
    auto-cleanup, never auto-replay, never restored to ready (§7.3).
    """
    capability_dir, manifest, path_ref = _load_claimed_scratch(ref, temp_root=temp_root)
    marked = dict(manifest)
    marked["state"] = SCRATCH_STATE_INSPECT_REQUIRED
    marked["inspect_required_at"] = _iso_utc(now if now is not None else _utc_now())
    _write_scratch_manifest_atomic(capability_dir, marked)


def inspect_prepared_input_scratch(
    *,
    ref: str,
    temp_root: Optional[Path] = None,
    now: Optional[datetime] = None,
) -> dict:
    """Read-only public-safe residue report for one capability (never mutates)."""
    validate_prepared_input_ref_shape(ref)
    capability_dir = scratch_capability_dir_for_ref(ref, temp_root=temp_root)
    path_ref = public_scratch_path_ref(capability_dir)
    report: dict[str, object] = {
        "ref": ref,
        "path_ref": path_ref,
        "present": False,
        "state": None,
        "role": None,
        "expires_at": None,
        "expired": None,
        "max_raw_bytes": None,
        "content_present": False,
        "content_raw_sha256": None,
        "content_error": None,
        "claimed_raw_sha256": None,
        "scratch_disposition": None,
        "manifest_error": None,
    }
    try:
        dir_lstat = capability_dir.lstat()
    except OSError:
        return report
    report["present"] = True
    if stat.S_ISLNK(dir_lstat.st_mode) or not stat.S_ISDIR(dir_lstat.st_mode):
        report["manifest_error"] = REASON_SCRATCH_CAPABILITY_INVALID
        return report
    try:
        manifest = _load_scratch_manifest(capability_dir, ref=ref, path_ref=path_ref)
    except InputTransportError as exc:
        report["manifest_error"] = exc.reason_code or REASON_SCRATCH_CAPABILITY_INVALID
        return report
    content_sha256 = None
    content_error = None
    content_size = 0
    try:
        raw, _identity = _read_scratch_content(capability_dir, manifest, path_ref=path_ref)
        content_sha256 = _sha256_hex(raw)
        content_size = len(raw)
    except InputTransportError as exc:
        content_error = exc.reason_code or REASON_SCRATCH_CAPABILITY_INVALID
    current = now if now is not None else _utc_now()
    state = manifest["state"]
    if state == SCRATCH_STATE_OPEN:
        disposition = (
            SCRATCH_DISPOSITION_WRITTEN_UNCLAIMED
            if content_sha256 is not None and content_size > 0
            else SCRATCH_DISPOSITION_PROVISIONED
        )
    else:
        disposition = state
    report.update(
        {
            "state": state,
            "role": manifest["role"],
            "expires_at": manifest["expires_at"],
            "expired": current > _parse_iso_utc(manifest["expires_at"]),
            "max_raw_bytes": manifest["max_raw_bytes"],
            "content_present": content_sha256 is not None,
            "content_raw_sha256": content_sha256,
            "content_error": content_error,
            "claimed_raw_sha256": manifest.get("claimed_raw_sha256"),
            "scratch_disposition": disposition,
        }
    )
    return report


def _capability_residue_count(capability_dir: Path) -> int:
    count = 1
    try:
        children = list(capability_dir.iterdir())
    except OSError:
        return count
    return min(count + len(children), MAX_RESIDUE_COUNT)


def scan_expired_prepared_input_capabilities(
    *,
    temp_root: Optional[Path] = None,
    now: Optional[datetime] = None,
) -> ScratchResidueReport:
    """Expiry/inspect residue scan over the system-temp capability area.

    Report-only: expired, inspect-required, or malformed capabilities become
    public-safe report-only findings. Nothing is ever deleted or modified
    here (§7.3: after expiry only report residue; never silently delete
    unverified content).
    """
    root = _scratch_temp_root(temp_root)
    current = now if now is not None else _utc_now()
    findings: list[ScratchResidueFinding] = []
    try:
        children = sorted(root.iterdir(), key=lambda path: path.name)
    except OSError:
        children = []
    for child in children:
        if not child.name.startswith(SCRATCH_CAPABILITY_DIR_PREFIX):
            continue
        path_ref = public_scratch_path_ref(child)
        reason_code: Optional[str] = None
        try:
            child_lstat = child.lstat()
        except OSError:
            reason_code = SCRATCH_FINDING_MALFORMED
        else:
            if stat.S_ISLNK(child_lstat.st_mode) or not stat.S_ISDIR(child_lstat.st_mode):
                reason_code = SCRATCH_FINDING_MALFORMED
        if reason_code is None:
            ref = PREPARED_INPUT_REF_PREFIX + child.name[len(SCRATCH_CAPABILITY_DIR_PREFIX):]
            try:
                validate_prepared_input_ref_shape(ref)
                manifest = _load_scratch_manifest(child, ref=ref, path_ref=path_ref)
            except InputTransportError:
                reason_code = SCRATCH_FINDING_MALFORMED
            else:
                if manifest["state"] == SCRATCH_STATE_INSPECT_REQUIRED:
                    reason_code = SCRATCH_FINDING_INSPECT_REQUIRED
                elif current > _parse_iso_utc(manifest["expires_at"]):
                    reason_code = SCRATCH_FINDING_EXPIRED
        if reason_code is None:
            continue
        findings.append(
            ScratchResidueFinding(
                reason_code=reason_code,
                path_category="external_helper_scratch",
                path_ref=path_ref,
                scope="report_only",
                residue_count=_capability_residue_count(child),
                blocking=False,
            )
        )
    return ScratchResidueReport(
        blocking_findings=(),
        report_only_findings=tuple(findings),
    )


# --- legacy loader extraction (byte-identical behavior; §7.8 row 01B/01C) ----

def read_limited_stdin_bytes(*, max_input_bytes: int) -> bytes:
    """The two helpers' former ``read_limited_stdin``, verbatim."""
    try:
        raw = sys.stdin.buffer.read(max_input_bytes + 1)
    except OSError as exc:
        raise InputTransportError(message=f"Failed to read stdin: {exc}")
    if len(raw) > max_input_bytes:
        raise InputTransportError(
            message=(
                f"Stdin input exceeds --max-input-bytes ({len(raw)} > {max_input_bytes})."
            ),
            details={"size": len(raw), "max_input_bytes": max_input_bytes},
        )
    return raw


def acquire_stdin_text(*, max_input_bytes: int) -> str:
    """The shared stdin tail of both legacy loaders (isatty/empty/UTF-8)."""
    if sys.stdin.isatty():
        raise InputTransportError(
            message="Stdin input is empty. Pipe or redirect UTF-8 prepared content when using --stdin."
        )
    raw = read_limited_stdin_bytes(max_input_bytes=max_input_bytes)
    if raw == b"":
        raise InputTransportError(
            message="Stdin input is empty. Pipe or redirect UTF-8 prepared content when using --stdin."
        )
    try:
        return raw.decode("utf-8")
    except UnicodeDecodeError:
        raise InputTransportError(message="Stdin input must be valid UTF-8.")


def read_validated_source_text(
    source: PreparedInputSource,
    *,
    max_input_bytes: int,
    label: str,
) -> str:
    """The two helpers' former ``read_limited_file_text`` core, verbatim."""
    try:
        return read_prepared_input_source_text(
            source,
            max_input_bytes=max_input_bytes,
            label=label,
        )
    except PreparedInputSafetyError as exc:
        raise prepared_input_transport_error(exc) from exc


@dataclass(frozen=True)
class EntryInputAcquisition:
    """Daily-log-append acquisition: the AcquiredInput plus the validated
    prepared-source path (file channel only; a non-public transport handle the
    legacy helper still returns downstream)."""

    acquired: AcquiredInput
    source_path: Optional[Path]


def acquire_daily_log_entry_input(
    *,
    entry_json: Optional[str],
    entry_file: Optional[str],
    use_stdin: bool,
    max_input_bytes: int,
    project_root: Optional[Path] = None,
    storage_root: Optional[Path] = None,
) -> EntryInputAcquisition:
    """append_daily_log_entry.py's former ``load_entry_source``, verbatim."""
    selected_sources = int(entry_json is not None) + int(entry_file is not None) + int(use_stdin)
    if selected_sources != 1:
        input_mode = "ambiguous" if selected_sources > 1 else "missing"
        details = {
            **OperationContext(
                command=COMMAND_APPEND,
                operation=OPERATION_DAILY_LOG_APPEND,
                write_type=None,
                input_mode=input_mode,
                stage=STAGE_INPUT,
            ).legacy_details_fields(),
            "input_contract": "entry-json_xor_entry-file_xor_stdin",
            "entry_json_present": entry_json is not None,
            "entry_file_present": entry_file is not None,
            "stdin_present": bool(use_stdin),
            "side_effect": "none",
            "trust_effect": "none",
            "reason_code": (
                REASON_BOTH_INPUT_SOURCES if selected_sources > 1 else REASON_MISSING_INPUT_SOURCE
            ),
        }
        if selected_sources > 1:
            raise InputTransportError(
                message="Use exactly one prepared-entry input: --entry-json, --entry-file, or --stdin.",
                details=details,
            )
        raise InputTransportError(
            message="Provide prepared entry content with exactly one of --entry-json, --entry-file, or --stdin.",
            details=details,
        )

    if entry_json is not None:
        entry_json_size = len(entry_json.encode("utf-8"))
        if entry_json_size > max_input_bytes:
            raise InputTransportError(
                message=(
                    f"Entry JSON input exceeds --max-input-bytes ({entry_json_size} > {max_input_bytes})."
                ),
                details={"size": entry_json_size, "max_input_bytes": max_input_bytes},
            )
        return EntryInputAcquisition(
            acquired=acquired_input_from_text(
                text=entry_json,
                input_mode=INPUT_MODE_ENTRY_JSON,
                role=OPERATION_DAILY_LOG_APPEND,
            ),
            source_path=None,
        )

    if entry_file:
        if project_root is None or storage_root is None:
            raise InputTransportError(
                message="Internal error: project root is required before reading --entry-file.",
                details={"input_mode": "file", "reason_code": "prepared_input_context_missing"},
            )
        try:
            entry_source = validate_prepared_input_source_path(
                entry_file,
                project_root=project_root,
                storage_root=storage_root,
                input_role="entry-file",
                label="entry",
            )
        except PreparedInputSafetyError as exc:
            raise prepared_input_transport_error(exc, input_mode="file") from exc
        return EntryInputAcquisition(
            acquired=acquired_input_from_text(
                text=read_validated_source_text(
                    entry_source,
                    max_input_bytes=max_input_bytes,
                    label="entry",
                ),
                input_mode=INPUT_MODE_FILE,
                role=OPERATION_DAILY_LOG_APPEND,
                source_identity=entry_source.path_ref,
            ),
            source_path=entry_source.path,
        )

    return EntryInputAcquisition(
        acquired=acquired_input_from_text(
            text=acquire_stdin_text(max_input_bytes=max_input_bytes),
            input_mode=INPUT_MODE_STDIN,
            role=OPERATION_DAILY_LOG_APPEND,
        ),
        source_path=None,
    )


def acquire_managed_write_input(
    *,
    source_file: Optional[str],
    use_stdin: bool,
    max_input_bytes: int,
    file_key: Optional[str] = None,
    write_type: Optional[str] = None,
    project_root: Optional[Path] = None,
    storage_root: Optional[Path] = None,
    role: str = OPERATION_MANAGED_WRITE,
) -> AcquiredInput:
    """commit_context_file.py's former ``load_prepared_text``, verbatim."""
    if bool(source_file) == bool(use_stdin):
        details = {
            **OperationContext(
                command=COMMAND_WRITE,
                operation=OPERATION_MANAGED_WRITE,
                write_type=None,
                input_mode=None,
                stage=STAGE_INPUT,
            ).legacy_details_fields(),
            "input_contract": "source-file_xor_stdin",
            "source_file_present": source_file is not None,
            "stdin_present": bool(use_stdin),
            "side_effect": "none",
            "reason_code": (
                REASON_BOTH_INPUT_SOURCES if source_file and use_stdin else REASON_MISSING_INPUT_SOURCE
            ),
        }
        if file_key is not None:
            details["file_key"] = file_key
        if write_type is not None:
            details["write_type"] = write_type
        if source_file and use_stdin:
            raise InputTransportError(
                message="Use exactly one prepared-content input: --source-file or --stdin.",
                details=details,
            )
        raise InputTransportError(
            message="Provide prepared content with --source-file or --stdin.",
            details=details,
        )

    if source_file:
        if project_root is None or storage_root is None:
            raise InputTransportError(
                message="Internal error: project root is required before reading --source-file.",
                details={"input_mode": "file", "reason_code": "prepared_input_context_missing"},
            )
        try:
            source = validate_prepared_input_source_path(
                source_file,
                project_root=project_root,
                storage_root=storage_root,
                input_role="source-file",
                label="source",
            )
        except PreparedInputSafetyError as exc:
            raise prepared_input_transport_error(exc, input_mode="file") from exc
        return acquired_input_from_text(
            text=read_validated_source_text(
                source,
                max_input_bytes=max_input_bytes,
                label="source",
            ),
            input_mode=INPUT_MODE_FILE,
            role=role,
            source_identity=source.path_ref,
        )

    return acquired_input_from_text(
        text=acquire_stdin_text(max_input_bytes=max_input_bytes),
        input_mode=INPUT_MODE_STDIN,
        role=role,
    )
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