feat: harden cache mount lifecycle with guard pins

docs/CACHE_AND_WORKSPACE.md

@@ -179,3 +179,28 @@ Current evidence proves deterministic source behavior and macOS execution of
 the test suite. Windows and Linux native cache/path behavior remains PENDING
 until it is executed on those platforms; no macOS result is relabeled as native
 evidence for another platform.
+
+Standard `run` retains its prepared-entry lock for the full execution
+lifecycle and revalidates the exact staging generation immediately before
+Docker creation. A changed, missing, or ambiguous generation fails closed.
+
+`guard exec` may opt into a cooperative pin for an already completed source:
+
+```console
+commit-ci-preflight guard exec \
+  --managed-cache-root /absolute/owned/cache-root \
+  --managed-cache-source /absolute/owned/cache-root/entries/sha256-<64>/data \
+  -- <program> [args...]
+```
+
+`--managed-cache-source` is repeatable and requires one owned root. Each source
+must be the exact completed `entries/sha256-<64>/data` directory beneath it;
+staging paths, workspaces, incomplete entries, symlinks, wrong object types,
+and escapes fail closed. Sources must already be canonical; aliases are
+rejected. Accepted sources are deduplicated and locked in stable order. The
+existing advisory entry lock is held through child
+cleanup and guard-session release; no additional TTL or heartbeat format is
+introduced. The declaration is cooperative and non-attesting: undeclared
+paths are not pinned, and manual or non-cooperative replacement is unsupported.
+Pinning does not initialize, repair, delete, quarantine, publish, or attest
+cache contents.

docs/COORDINATION_RUNBOOK.md

@@ -37,6 +37,28 @@ CCP's own integration tests and any command that invokes `run`, `benchmark`, or
 `guard exec` internally must not be wrapped in another `guard exec`. Admission
 is intentionally non-reentrant.
 
+### Standard run lock and opt-in cache pins
+
+The host-wide admission slot remains the primary coordination mechanism for
+`run`, `benchmark`, and `guard exec`. An opt-in `guard exec` managed-cache pin
+is an additional filesystem-use boundary for already-complete cache entries;
+it is not a second scheduler, a replacement for admission, or a receipt
+qualification signal. Pins use the entry's existing advisory lock and remain
+held for the guarded child lifecycle; they have no TTL and are released when
+the guarded operation returns.
+
+Only explicitly declared, completed managed-cache sources are pinned; in
+particular, `undeclared paths are not pinned`. A path used by a raw launcher
+but omitted from the pin arguments receives no CCP ownership or race
+protection. Pin acquisition and spawn-boundary revalidation
+must succeed before the child starts. A cooperative mutator must use the same
+entry lock and revalidate after acquiring it; manual deletion, quarantine,
+replacement, or other non-cooperative mutation is outside this guarantee.
+
+Pins do not initialize, repair, delete, quarantine, or publish receipts. A
+qualification result remains separate and requires its own exact source,
+configuration, runtime, and receipt evidence.
+
 ## Required preflight before heavy work
 
 Every activity must perform these checks immediately before reserving a heavy

docs/LOCAL_RUN.md

@@ -191,3 +191,23 @@ These are macOS-hosted OrbStack results. They are not Windows-native,
 Linux-host-native, hosted-runner, identity-attestation, or GitHub policy
 evidence. PR 06 adds an independent verifier; later plan tranches add the small
 remote gate and cross-platform qualification.
+
+For a cooperative child using a completed CCP cache entry, declare one
+`--managed-cache-root` and repeatable `--managed-cache-source` options:
+
+```console
+commit-ci-preflight guard exec \
+  --managed-cache-root /absolute/owned/cache-root \
+  --managed-cache-source /absolute/owned/cache-root/entries/sha256-<64>/data \
+  -- <program> [args...]
+```
+
+The source must be the exact completed `entries/sha256-<64>/data` directory
+under that root. Sources must already be canonical; aliases are rejected.
+Accepted declarations are deduplicated and locked in a stable order, then
+revalidated immediately before child spawn. The
+existing advisory entry lock stays held through child cleanup and guard-session
+release. This declaration is cooperative and non-attesting: undeclared paths
+are not pinned, and manual or non-cooperative replacement is unsupported. The
+flags do not initialize, repair, delete, quarantine, publish, or attest cache
+contents. Legacy `guard exec` without these flags remains unchanged.

docs/RUNTIME.md

@@ -163,3 +163,15 @@ runner does not mount the Docker socket into a job, enable privileged mode,
 insert a shell, or expose undeclared host paths. Network remains disabled unless
 the configuration explicitly enables it. See `docs/LOCAL_RUN.md` for evidence
 and remaining platform limitations.
+
+The standard `run` path retains its prepared-entry lock through execution and
+performs spawn-boundary revalidation of the exact staging generation
+immediately before Docker creation. A changed, missing, or ambiguous source
+fails closed at that boundary.
+
+`guard exec` supports an opt-in cooperative pin for exact completed managed
+cache sources. The existing advisory entry lock remains held through child
+cleanup and session release. Only sources declared beneath one managed root
+are covered; undeclared paths are not pinned, and arbitrary child argv is not
+parsed or attested. No additional TTL or heartbeat lease is introduced.
+Manual or non-cooperative replacement remains unsupported.

docs/TESTING_AND_FAULT_INJECTION.md

@@ -86,6 +86,24 @@ journal avoids the limitation by publishing immutable create-new events.
 Native crash/power-loss and Windows-host qualification remain separate gates.
 Deterministic source tests do not claim either result.
 
+## Managed-cache pin contract
+
+The managed-cache pin tests are deterministic contract tests over an owned
+fixture root. They cover canonical completed-entry selection, duplicate
+deduplication and stable ordering, advisory-lock lifetime, invalid roots and
+components, missing or incomplete entries, symlink and wrong-type rejection,
+and release of previously acquired pins when a later acquisition fails. The
+pin API does not initialize, repair, delete, quarantine, or publish receipts.
+
+The lifecycle tests separately verify spawn-boundary revalidation and that a
+failed validation makes zero child calls. The non-cooperative race test is
+bounded to a change after pin acquisition but before the child spawn: the
+validator must fail and the child-call count must remain zero. Replacement
+after spawn-boundary revalidation is not prevented or guaranteed by this pin;
+it is an unsupported external race and must not be converted into a success
+claim. Qualification of a real runtime or receipt is a separate
+native/evidence-gated activity.
+
 ## Compatibility fixtures
 
 The v1 compatibility baseline remains pinned in:

docs/THREAT_MODEL.md

@@ -72,6 +72,8 @@ Boundary rules:
 - project checks are trusted build/test code, not arbitrary hostile workloads;
 - the source checkout is read-only inside the container;
 - only declared cache and artifact mounts are writable;
+- managed-cache pins are opt-in, apply only to explicitly declared completed
+  entries, and are revalidated at the spawn boundary;
 - the evidence branch is untrusted data;
 - verifier code and policy come from the reviewed base branch;
 - GitHub event identity and permissions remain remote facts.
@@ -94,13 +96,13 @@ Boundary rules:
 | T12 | Workflow privilege escalation | Minimal permissions, pinned official actions, no secrets/cache/deployment credential | Compromise of GitHub or a pinned action commit remains upstream risk |
 | T13 | Marketplace action execution during migration | Migration assistant parses bounded YAML as data and emits inert classifications | Human reviewers can still make a bad manual translation |
 | T14 | GitHub expression or secret misinterpretation | Unsupported expressions, permissions, secrets, reusable workflows, and arbitrary actions fail closed or require review | Compatibility is deliberately incomplete |
-| T15 | Cache poisoning | Versioned ownership marker, content-addressed keys, completion marker, active-run lock | Caches accelerate execution but are not attestation evidence |
+| T15 | Cache poisoning or cache-use race | Versioned ownership marker, content-addressed keys, completion marker, active-run lock, opt-in managed-cache pin with spawn-boundary revalidation | Caches accelerate execution but are not attestation evidence; undeclared paths are not pinned |
 | T16 | Destructive cleanup | 0.1.0 exposes preview-only cleanup; resolved-root and containment checks | Operators retain responsibility for manual filesystem deletion |
 | T17 | Image drift | OCI digest is mandatory and included in plan, receipt, and policy | A multi-platform index can resolve to different platform manifests by design |
 | T18 | Dependency compromise | Committed lockfile, exact critical pins, SPDX SBOM, bundled notices, advisory review | Registry and compiler compromise cannot be eliminated locally |
 | T19 | Platform overclaim | Native receipts name OS/architecture; emulation and runtime probes are separate; PASS/PENDING/NOT_RUN are explicit | Benchmark qualification is narrower than full runtime qualification |
 | T20 | Identity overclaim | Structural, integrity, policy, and identity levels are separate; identity is not implemented | No cryptographic proof of operator or machine exists in 0.1.0 |
-| T21 | Symlink or filesystem race | Canonical path checks, managed roots, create-new/atomic writes, runtime revalidation | Host filesystem and privileged local actors remain trusted |
+| T21 | Symlink or filesystem race | Canonical path checks, managed roots, create-new/atomic writes, runtime revalidation, existing advisory-lock pin held through the guarded child lifecycle | Cooperative mutators must use the same lock and revalidate after acquisition; manual deletion remains unsupported; privileged local actors remain trusted |
 | T22 | Evidence parser denial of service | One MiB remote input cap, strict unknown-field rejection, bounded summaries | Base verifier compilation still consumes bounded remote time |
 | T23 | Release substitution | Local SHA-256 manifest, SBOM, notices, checksum verification instructions | Checksums are not signatures and must come through an independent channel |
 | T24 | Unsafe upgrade or rollback | Isolated install, version smoke test, preserved previous binary, versioned schemas and cache markers | Operator mistakes remain possible; no automatic updater exists |
@@ -151,6 +153,11 @@ before publication.
   deduplicated license/notice texts found in packaged crates.
 - The host admission coordinator does not infer liveness from PIDs or wall
   clocks; it reclaims only tickets whose advisory locks are demonstrably free.
+- The standard run lock coordinates the host-wide heavy slot. An opt-in
+  managed-cache pin is a separate advisory-lock pin for an explicitly
+  declared completed entry; it has no TTL and does not provide receipt or
+  qualification evidence. Spawn-boundary revalidation is required before the
+  child starts, and undeclared paths are not pinned.
 - The macOS resource guard uses only bounded, strict output from absolute system
   tools and fails closed on unavailable or contradictory samples. Its status
   surface is bounded and excludes identity, path, command, and process data.