Fall back from unwritable installation-adjacent CAS storage and migrate persisted paths

[bobtista]

Problem

GenHub automatically selects an installation-adjacent CAS pool at <installation>/.genhub-cas.

Both ContentOrchestrator and CommunityOutpostDeliverer persist that location as UserSettings.CasConfiguration.InstallationPoolRootPath and mark the automatically derived value as explicitly set.

CasPoolResolver.IsInstallationPoolAvailable() currently considers any nonempty path available. It does not verify that the packaged application can create or modify the pool.

The resolver routes these content types to the installation pool when that setting is nonempty:

• GameInstallation
• GameClient
• Addon
• Patch
• Map
• Mod

When the installation is under Program Files, a packaged non-administrator process may be able to read the installation but cannot write <installation>/.genhub-cas. Content acquisition and CAS maintenance can therefore fail.

Launches using already-populated content appear to require only CAS reads during workspace preparation, but that must be verified with the packaged Windows build rather than treated as established behavior.

Existing-user impact

This is not only a clean-install path-selection problem.

Users may already have an unwritable installation-adjacent path persisted in InstallationPoolRootPath. Changing the default resolver alone will not repair those settings.

Changing the selected pool can also leave existing CAS objects under the previous root. Migration must not silently delete or orphan usable content.

Expected behavior

GenHub should prefer installation-adjacent CAS storage when it is writable, preserving same-volume hard-link efficiency.

When that location is not writable, GenHub should select a user-writable CAS pool. Cross-volume workspace materialization may use the copy fallback enabled by #346.

Automatically derived paths should not be treated as permanent user overrides.

Requirements

• Probe an installation-adjacent CAS location before persisting or adopting it.
• Treat an empty, invalid, missing, or unwritable installation-pool path as unavailable.
• Fall back to a configured writable CAS root or the application-data CAS pool.
• Distinguish automatically derived paths from paths deliberately configured by the user.
• Detect previously persisted auto-derived paths that point into a protected installation.
• Migrate or clear those settings and reinitialize the installation pool without requiring users to reset their configuration manually.
• Define safe handling for CAS objects under the previous root:
  • do not delete existing content automatically;
  • preserve readable content, migrate it safely, or allow it to be reacquired;
  • avoid leaving manifests or references pointing at an inaccessible pool.
• Log the selected pool and the reason for fallback without repeatedly probing on every operation.
• Preserve writable installation-adjacent pools.

Acceptance criteria

• A packaged non-administrator Windows build can acquire GameClient content when the game is installed under Program Files.
• All installation-pool content types resolve to a writable effective pool.
• A writable installation-adjacent pool remains selected.
• A writable user-configured CAS path remains honored.
• An existing persisted protected path is repaired automatically.
• CasPoolManager is reinitialized after the effective installation-pool path changes.
• Existing CAS content is not deleted or silently orphaned during migration.
• CAS garbage collection does not attempt to mutate an unwritable protected pool.
• Cross-volume workspace preparation succeeds through the copy path.
• Tests cover clean settings, migrated settings, writable adjacent storage, unwritable adjacent storage, custom CAS storage, and pool reinitialization.
• Packaged Windows validation covers acquisition followed by profile creation and launch.

Related work

• Alpha 4 readiness: Release: Alpha 4 readiness checklist #307
• Workspace protected-path report: Fall back from protected installation-adjacent workspaces to user-writable storage #344
• Workspace fallback and cross-volume copying: fix(workspace): fall back from protected adjacent storage #346

[coderabbitai]

🔗 Related PRs

#312 - fix: disable unsafe CAS garbage collection [merged]
#328 - feat(platform): make paths, manifests, and Unix workspaces platform-aware [merged]
#329 - feat(macos): add native host, installation detection, and CI [merged]
#331 - fix(macos): register the platform services the merged state requires [merged]
#332 - feat(launching): launch the native BGFX client against retail archives [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Add a shared writability probe and protected-path helper, and record installation-pool path provenance on CasConfiguration, so availability decisions and repair logic can be based on real write access.
• Change CasPoolResolver to treat empty, invalid, missing, or unwritable installation-pool paths as unavailable, cache the probe result, extend routing to Addon, Patch, Map, and Mod, and thread ContentType through storage and materialization so pool routing is consistent.
• Create the probe-and-persist flow, add a startup migration step that repairs auto-derived protected paths without deleting CAS content, and add ReinitializeInstallationPool so the effective path change takes effect without a restart.
• Make garbage collection pool-aware and skip unwritable pools, and add unit, integration, and migration tests plus documented packaged Windows validation.

Design Choices

Design Choice 1: Location of the probe-and-persist flow for InstallationPoolRootPath

Options Considered:

1. Add the persistence and provenance logic to ContentOrchestrator/CommunityOutpostDeliverer as the ticket names them.
2. Add the persistence logic at the installation-detection choke point and the launch/prepare choke point, where the installation path is fully known.

Chosen Option: 2

Rationale: The installation-detection orchestrator and ProfileLauncherFacade.ResolveOrRebindInstallationAsync are the natural single choke points where an installation is confirmed and its adjacent path can be probed once, before any CAS path is used. The ticket states that ContentOrchestrator and CommunityOutpostDeliverer already persist InstallationPoolRootPath and mark it explicitly set, but exploration confirmed no such code exists anywhere in the solution. This feature area is greenfield. The plan must create the probe-and-persist flow, not modify an existing one.

Design Choice 2: Provenance model for distinguishing an auto-derived path from a user-configured path

Options Considered:

1. Add a boolean IsInstallationPoolAutoDerived field to CasConfiguration.
2. Reuse the existing UserSettings.ExplicitlySetProperties mechanism with a CasConfiguration.InstallationPoolRootPath key.

Chosen Option: 1

Rationale: A self-contained boolean on CasConfiguration survives serialization, is read directly by CasPoolResolver and the migration step, and does not require extending the top-level ExplicitlySetProperties switch to nested properties. The resolver and migration logic must know whether a persisted InstallationPoolRootPath was chosen automatically or set by the user.

Design Choice 3: Mechanism to propagate an effective installation-pool path change to the singleton CAS services

Options Considered:

1. Switch all CAS services to IOptionsMonitor.
2. Add an explicit ReinitializeInstallationPool method on ICasPoolManager plus a shared current-config source that the resolver reads live.

Chosen Option: 2

Rationale: An explicit reinitialize method is simpler to reason about, maps directly to the acceptance criterion that CasPoolManager is reinitialized after the effective installation-pool path changes, and avoids introducing a live options-change source for a value that changes rarely. IOptions caches its value at first resolution, so settings changes do not reach CasPoolResolver/CasPoolManager without a restart.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Writability Probing and Provenance Foundation

This phase adds the shared building blocks the later phases depend on. It provides a reusable way to test whether a directory is writable, a way to detect protected installation paths, and a way to record whether a persisted installation-pool path was derived automatically.

Task 1: Add a reusable writability probe and protected-path helper

Create shared logic to test write access and to detect protected system directories.

• Add a static helper (extend GenHub.Core/Helpers/PathHelper.cs) that reports whether a path is writable. It must attempt to create and delete a uniquely named temporary file under the target directory and catch UnauthorizedAccessException, IOException, and SecurityException, returning false on failure and true on success.
• Add a helper that reports whether a path resides under a protected installation directory (for example Program Files). Model the write-probe body on the existing temp-file pattern in WorkspaceValidator.ValidateConfigurationAsync. Keep the helpers platform-aware.
• Do not throw from these helpers. They must return boolean results and never mutate state beyond the temporary probe file they clean up.

Task 2: Add auto-derived provenance to CasConfiguration

Record whether the installation-pool path was chosen automatically.

• Add a boolean field (for example IsInstallationPoolAutoDerived) to GenHub.Core/Models/Storage/CasConfiguration.cs, defaulting to false.
• Update CasConfiguration.Clone() to copy the new field.
• Update CasModule.cs and ConfigurationProviderService.GetCasConfiguration() so the new field and InstallationPoolRootPath are copied through the options binding. Fix the existing gap where GetCasConfiguration() builds a new CasConfiguration for the default CasRootPath case but drops InstallationPoolRootPath.

🤖 Prompt for AI agents

Implement the shared foundation that later phases depend on: a writability
probe, a protected-path helper, and provenance tracking for the
installation-pool path.

- Extend `GenHub.Core/Helpers/PathHelper.cs` with a static helper that reports
whether a path is writable. Implement it by creating and deleting a uniquely
named temporary file under the target directory, catching
`UnauthorizedAccessException`, `IOException`, and `SecurityException`. Return
`false` on failure, `true` on success. Model the temp-file probe body on the
existing pattern in `WorkspaceValidator.ValidateConfigurationAsync`.
- Add a helper that reports whether a path resides under a protected
installation directory (for example `Program Files`). Keep both helpers
platform-aware.
- Ensure neither helper throws. Both must return boolean results and clean up
any temporary probe file they create.
- Add a boolean field named `IsInstallationPoolAutoDerived` to
`GenHub.Core/Models/Storage/CasConfiguration.cs`, defaulting to `false`.
- Update `CasConfiguration.Clone()` to copy this new field.
- Update `CasModule.cs` and `ConfigurationProviderService.GetCasConfiguration()`
so both the new field and `InstallationPoolRootPath` are copied through options
binding. Fix the gap where `GetCasConfiguration()` builds a new
`CasConfiguration` for the default `CasRootPath` case but currently drops
`InstallationPoolRootPath`.

Phase 2: Pool Availability Resolution and Routing

This phase changes how the resolver decides pool availability and which content types route to the installation pool. It makes availability depend on real writability, adds the required content types, and caches the probe result to avoid repeated filesystem probing.

Task 1: Make installation-pool availability depend on writability

Treat empty, invalid, missing, or unwritable installation-pool paths as unavailable.

• Update IsInstallationPoolAvailable() in GenHub/GenHub/Features/Storage/Services/CasPoolResolver.cs. It must return true only when InstallationPoolRootPath is non-empty, the path is valid and reachable, and the writability probe from Task 1.1 succeeds.
• Cache the probe result in the resolver so it does not probe on every call. Add an internal method to invalidate the cached result so Phase 4 can force a recheck after reinitialization. Log the selected pool and the fallback reason once per resolution, not per operation.
• Update GetPoolRootPath(CasPoolType) and GetPoolRootPath(ContentType) so that when the installation pool is unavailable they return the configured CasRootPath, and when CasRootPath is empty they return the application-data CAS pool path.

Task 2: Extend installation-pool content-type routing

Route the additional content types the ticket specifies.

• Extend the InstallationPoolTypes set in CasPoolResolver.cs to include ContentType.Addon, ContentType.Patch, ContentType.Map, and ContentType.Mod, in addition to the existing GameInstallation and GameClient.
• Keep the fallback behavior: any content type resolves to CasPoolType.Primary when the installation pool is unavailable.

🤖 Prompt for AI agents

Implement writability-based availability resolution and expanded content-type
routing in `CasPoolResolver`.

- Update `IsInstallationPoolAvailable()` in
`GenHub/GenHub/Features/Storage/Services/CasPoolResolver.cs` so it returns
`true` only when `InstallationPoolRootPath` is non-empty, the path is valid and
reachable, and the Task 1.1 writability probe succeeds.
- Cache the probe result inside the resolver to avoid probing on every call. Add
an internal method to invalidate the cached result, for later use when the pool
is reinitialized. Log the selected pool and the fallback reason once per
resolution, not once per operation.
- Update `GetPoolRootPath(CasPoolType)` and `GetPoolRootPath(ContentType)`:
return the configured `CasRootPath` when the installation pool is unavailable,
and return the application-data CAS pool path when `CasRootPath` is empty.
- Extend the `InstallationPoolTypes` set in `CasPoolResolver.cs` to include
`ContentType.Addon`, `ContentType.Patch`, `ContentType.Map`, and
`ContentType.Mod`, in addition to the existing `GameInstallation` and
`GameClient`.
- Preserve the fallback behavior so any content type resolves to
`CasPoolType.Primary` when the installation pool is unavailable.

Phase 3: Thread ContentType Through Storage and Materialization

This phase makes the pool routing take real effect. Storage and retrieval must both honor the resolved pool, or content stored in the installation pool would not be found during workspace materialization. Without this phase, enabling the installation pool would break read/write consistency.

Task 1: Route content storage and retrieval through the resolved pool

Pass content type to the pool-aware CAS operations during acquisition.

• Update ContentStorageService.StoreContentFilesAsync and RetrieveContentAsync in GenHub/GenHub/Features/Content/Services/ContentStorageService.cs to call the pool-aware ICasService.StoreContentAsync(..., ContentType, ...) and GetContentPathAsync(hash, ContentType, ...) overloads, passing manifest.ContentType.
• Do not change the public IContentStorageService signatures unless required; ContentManifest.ContentType is already available inside these methods.

Task 2: Make workspace CAS materialization pool-aware

Thread content type into the linking and copying calls.

• Add a ContentType parameter to IFileOperationsService.LinkFromCasAsync and CopyFromCasAsync, and update their implementations in GenHub/GenHub/Features/Workspace/FileOperationsService.cs to call the pool-aware ICasService.GetContentPathAsync(hash, contentType, ...) overload.
• Thread manifest.ContentType from ProcessManifestFileAsync down through ProcessCasFileAsync and CreateCasLinkAsync in GenHub/GenHub/Features/Workspace/Strategies/WorkspaceStrategyBase.cs and the concrete strategies, so per-file linking resolves the same pool used at storage time.
• Preserve the existing cross-volume copy fallback (#346). Verify the fallback still runs when the resolved installation pool is on a different volume than the workspace.

🤖 Prompt for AI agents

Thread `ContentType` through the content storage, retrieval, and workspace
materialization paths so pool routing takes real effect end to end.

- Update `ContentStorageService.StoreContentFilesAsync` and
`RetrieveContentAsync` in
`GenHub/GenHub/Features/Content/Services/ContentStorageService.cs` to call the
pool-aware `ICasService.StoreContentAsync(..., ContentType, ...)` and
`GetContentPathAsync(hash, ContentType, ...)` overloads, passing
`manifest.ContentType`. Do not change the public `IContentStorageService`
signatures unless required, since `ContentManifest.ContentType` is already
available inside these methods.
- Add a `ContentType` parameter to `IFileOperationsService.LinkFromCasAsync` and
`CopyFromCasAsync`. Update their implementations in
`GenHub/GenHub/Features/Workspace/FileOperationsService.cs` to call the
pool-aware `ICasService.GetContentPathAsync(hash, contentType, ...)` overload.
- Thread `manifest.ContentType` from `ProcessManifestFileAsync` down through
`ProcessCasFileAsync` and `CreateCasLinkAsync` in
`GenHub/GenHub/Features/Workspace/Strategies/WorkspaceStrategyBase.cs` and the
concrete strategies, so per-file linking resolves the same pool used at storage
time.
- Preserve the existing cross-volume copy fallback (`#346`). Confirm the fallback
still runs when the resolved installation pool is on a different volume than the
workspace.

Phase 4: Persistence, Migration, and Pool Reinitialization

This phase creates the probe-and-persist flow that does not exist today, repairs previously persisted protected paths, and reinitializes the installation pool at runtime after the effective path changes. It also defines safe handling for CAS objects under a previous root.

Task 1: Probe and persist an installation-adjacent path as auto-derived

Adopt the adjacent path only when it is writable.

• At the installation-detection choke point (GameInstallationDetectionOrchestrator.DetectAllInstallationsAsync) and/or ProfileLauncherFacade.ResolveOrRebindInstallationAsync, derive the candidate installation-adjacent CAS path with IStorageLocationService.GetCasPoolPath.
• Probe the candidate path with the Task 1.1 helper. When it is writable and the user has not deliberately configured a CAS path, persist it to UserSettings.CasConfiguration.InstallationPoolRootPath through IUserSettingsService.TryUpdateAndSaveAsync, and set IsInstallationPoolAutoDerived = true.
• When the candidate path is not writable, do not persist it. Leave the installation pool unavailable so routing falls back to the primary or application-data pool.

Task 2: Add startup migration/repair for persisted protected paths

Repair previously persisted auto-derived paths automatically.

• Add a startup migration step (a small hosted service, or a step invoked during CAS startup) that reads UserSettings.CasConfiguration.
• When InstallationPoolRootPath is non-empty, IsInstallationPoolAutoDerived is true, and the path is protected or not writable, clear or re-derive the value through IUserSettingsService.TryUpdateAndSaveAsync. Do not modify paths that the user configured deliberately (IsInstallationPoolAutoDerived == false).
• Do not delete any CAS objects under the previous root. Preserve the previous root's content so it can be read or reacquired. Because manifests and reference files store only hashes and live under the primary CasRootPath, no manifest or reference rewrite is required; document that content only present under the abandoned root will be reacquired on next demand.
• Log the repair action and the reason once.

Task 3: Add installation-pool reinitialization to CasPoolManager

Rebuild the installation pool after the effective path changes.

• Add a ReinitializeInstallationPool() method to ICasPoolManager and implement it in GenHub/GenHub/Features/Storage/Services/CasPoolManager.cs. It must remove the cached CasPoolType.Installation entry from _storages, re-read the current effective configuration, invalidate the resolver's cached probe result (Task 2.1), and rebuild the installation storage only when the pool is available.
• Make CasPoolResolver read the current effective installation-pool configuration rather than a value captured once, so the reinitialized manager and resolver agree. Use the shared current-config source described in Assumption 3.
• Call ReinitializeInstallationPool() from the persistence flow (Task 4.1) and the migration step (Task 4.2) after the effective path changes.

🤖 Prompt for AI agents

Build the probe-and-persist flow, a startup migration/repair step for protected
persisted paths, and a runtime reinitialization mechanism for the installation
pool.

- At the installation-detection choke point
(`GameInstallationDetectionOrchestrator.DetectAllInstallationsAsync`) and/or
`ProfileLauncherFacade.ResolveOrRebindInstallationAsync`, derive the candidate
installation-adjacent CAS path using `IStorageLocationService.GetCasPoolPath`.
- Probe the candidate path with the Task 1.1 writability helper. When it is
writable and the user has not deliberately configured a CAS path, persist it to
`UserSettings.CasConfiguration.InstallationPoolRootPath` through
`IUserSettingsService.TryUpdateAndSaveAsync`, and set
`IsInstallationPoolAutoDerived = true`. When the candidate path is not writable,
do not persist it, and leave the installation pool unavailable so routing falls
back to the primary or application-data pool.
- Add a startup migration step (a small hosted service or a step invoked during
CAS startup) that reads `UserSettings.CasConfiguration`. When
`InstallationPoolRootPath` is non-empty, `IsInstallationPoolAutoDerived` is
`true`, and the path is protected or not writable, clear or re-derive the value
through `IUserSettingsService.TryUpdateAndSaveAsync`. Do not modify paths the
user configured deliberately (`IsInstallationPoolAutoDerived == false`).
- Do not delete any CAS objects under the previous root during migration.
Preserve the previous root's content so it can be read or reacquired. Because
manifests and reference files store only hashes and live under the primary
`CasRootPath`, no manifest or reference rewrite is required. Document that
content only present under the abandoned root will be reacquired on next demand.
Log the repair action and the reason once.
- Add a `ReinitializeInstallationPool()` method to `ICasPoolManager`,
implemented in `GenHub/GenHub/Features/Storage/Services/CasPoolManager.cs`. It
must remove the cached `CasPoolType.Installation` entry from `_storages`,
re-read the current effective configuration, invalidate the resolver's cached
probe result, and rebuild the installation storage only when the pool is
available.
- Make `CasPoolResolver` read the current effective installation-pool
configuration rather than a value captured once, using the shared current-config
source, so the reinitialized manager and resolver stay in agreement.
- Call `ReinitializeInstallationPool()` from both the persistence flow and the
migration step after the effective path changes.

Phase 5: Garbage Collection Pool Safety

This phase makes garbage collection pool-aware and prevents it from mutating an unwritable pool.

Make garbage collection iterate pools and skip unwritable pools

Protect the installation pool from write attempts during maintenance.

• Update CasService.RunGarbageCollectionAsync (and ValidateIntegrityAsync/GetStatsAsync as needed) in GenHub/GenHub/Features/Storage/Services/CasService.cs to iterate pools through ICasPoolManager.GetAllStorages() when a pool manager is present, instead of using only the single default ICasStorage.
• Before performing any mutation on a pool, check pool writability using the Task 1.1 helper (or a resolver/manager writability check). Skip a pool that is not writable and log the skip once. Do not attempt DeleteObjectAsync or directory creation against an unwritable pool.
• Guard CasStorage.DeleteObjectAsync so its EnsureDirectoriesCreated() call cannot throw UnauthorizedAccessException up to the caller; wrap or precede it with a writability check so an unwritable pool degrades gracefully instead of throwing on every unreferenced hash.

🤖 Prompt for AI agents

Make garbage collection and related maintenance operations iterate all pools and
skip pools that are not writable, so an unwritable installation pool is never
mutated.

- Update `CasService.RunGarbageCollectionAsync` (and
`ValidateIntegrityAsync`/`GetStatsAsync` as needed) in
`GenHub/GenHub/Features/Storage/Services/CasService.cs` to iterate pools through
`ICasPoolManager.GetAllStorages()` when a pool manager is present, instead of
operating only on the single default `ICasStorage`.
- Before any mutation on a pool, check pool writability using the Task 1.1
helper (or a resolver/manager writability check). Skip a pool that is not
writable and log the skip once. Do not attempt `DeleteObjectAsync` or directory
creation against an unwritable pool.
- Guard `CasStorage.DeleteObjectAsync` so its `EnsureDirectoriesCreated()` call
cannot throw `UnauthorizedAccessException` up to the caller. Wrap or precede it
with a writability check so an unwritable pool degrades gracefully instead of
throwing on every unreferenced hash.

Phase 6: Tests and Packaged Validation

This phase adds automated coverage for the new behavior and documents the manual packaged Windows validation the acceptance criteria require.

Task 1: Add unit tests for resolver, manager, and provenance

Cover pool selection, writability fallback, and reinitialization.

• Add CasPoolResolverTests.cs and CasPoolManagerTests.cs under GenHub.Tests/GenHub.Tests.Core/Features/Storage/. Follow the direct-construction Moq pattern from WorkspaceManagerTests.cs, using Mock<IOptions<CasConfiguration>>, Mock<ILogger<T>>, and Mock<ILoggerFactory>.
• Cover: empty installation-pool path resolves to Primary; writable installation-pool path resolves to Installation for each routed content type; unwritable installation-pool path resolves to Primary; the additional content types (Addon, Patch, Map, Mod) route correctly; probe result is cached and invalidated on reinitialization; ReinitializeInstallationPool rebuilds the installation storage after the path changes.

Task 2: Add migration and integration tests

Cover clean, migrated, and custom settings scenarios.

• Add tests for the startup migration step: an auto-derived protected path is cleared or re-derived; a user-configured path is preserved; a writable auto-derived path is preserved; no CAS objects are deleted during migration.
• Add an integration test modeled on GameProfileWorkspaceIntegrationTest.cs that creates a temporary directory marked read-only (via FileAttributes.ReadOnly on Windows or the Unix-mode equivalent) and asserts the installation pool is treated as unavailable and routing falls back to Primary.
• Add a garbage-collection test asserting that an unwritable pool is skipped and not mutated.

Task 3: Document packaged Windows validation steps

Define the manual validation the acceptance criteria require.

• Document the packaged, non-administrator Windows validation: install the game under Program Files, acquire GameClient content, create a profile, and launch. Confirm acquisition succeeds through the fallback pool and that a cross-volume workspace preparation succeeds through the copy path.
• Record whether launches with pre-populated content require only CAS reads, as the ticket asks this to be verified rather than assumed.

🤖 Prompt for AI agents

Add automated test coverage for the resolver, manager, migration, and garbage
collection behavior, and document the manual packaged Windows validation.

- Add `CasPoolResolverTests.cs` and `CasPoolManagerTests.cs` under
`GenHub.Tests/GenHub.Tests.Core/Features/Storage/`, following the
direct-construction Moq pattern from `WorkspaceManagerTests.cs`, using
`Mock<IOptions<CasConfiguration>>`, `Mock<ILogger<T>>`, and
`Mock<ILoggerFactory>`.
- Cover in these unit tests: an empty installation-pool path resolves to
Primary; a writable installation-pool path resolves to Installation for each
routed content type; an unwritable installation-pool path resolves to Primary;
the additional content types (`Addon`, `Patch`, `Map`, `Mod`) route correctly;
the probe result is cached and invalidated on reinitialization;
`ReinitializeInstallationPool` rebuilds the installation storage after the path
changes.
- Add tests for the startup migration step: an auto-derived protected path is
cleared or re-derived; a user-configured path is preserved; a writable
auto-derived path is preserved; no CAS objects are deleted during migration.
- Add an integration test modeled on `GameProfileWorkspaceIntegrationTest.cs`
that creates a temporary directory marked read-only (via
`FileAttributes.ReadOnly` on Windows or the Unix-mode equivalent), and asserts
the installation pool is treated as unavailable with routing falling back to
Primary.
- Add a garbage-collection test asserting that an unwritable pool is skipped and
not mutated.
- Document the packaged, non-administrator Windows validation steps: install the
game under `Program Files`, acquire `GameClient` content, create a profile, and
launch. Confirm acquisition succeeds through the fallback pool, and confirm a
cross-volume workspace preparation succeeds through the copy path. Record
whether launches with pre-populated content require only CAS reads, since the
ticket asks for this to be verified rather than assumed.

Research

The CAS subsystem uses a two-pool model (CasPoolType.Primary and CasPoolType.Installation). CasPoolResolver maps a ContentType to a pool and returns a root path. CasPoolManager builds and caches one ICasStorage per pool in a ConcurrentDictionary. CasService exposes pool-aware and non-pool-aware operations. Production callers use only the non-pool-aware overloads. CasMaintenanceService runs periodic garbage collection through CasService, which operates only on the single default ICasStorage. Configuration flows one way: CasModule binds IOptions<CasConfiguration> once at startup from IConfigurationProviderService.GetCasConfiguration(). Runtime settings changes do not propagate until restart.

Exploration found several gaps that differ from the ticket text. InstallationPoolRootPath has no writer anywhere in the codebase. ContentOrchestrator and CommunityOutpostDeliverer do not persist it. IsInstallationPoolAvailable() performs only a non-empty string check. Routing to the installation pool covers only GameInstallation and GameClient. No writability probe or protected-path helper exists. ICasPoolManager has no reinitialize method, and GetAllStorages() is defined but unused. CasConfiguration has no auto-derived/user-set provenance flag. Manifests store only hashes, so pool migration does not require rewriting manifest data. The staleness risk is the cached CasStorage instances inside CasPoolManager.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the shared foundation that later phases depend on: a writability
probe, a protected-path helper, and provenance tracking for the
installation-pool path.

- Extend `GenHub.Core/Helpers/PathHelper.cs` with a static helper that reports
whether a path is writable. Implement it by creating and deleting a uniquely
named temporary file under the target directory, catching
`UnauthorizedAccessException`, `IOException`, and `SecurityException`. Return
`false` on failure, `true` on success. Model the temp-file probe body on the
existing pattern in `WorkspaceValidator.ValidateConfigurationAsync`.
- Add a helper that reports whether a path resides under a protected
installation directory (for example `Program Files`). Keep both helpers
platform-aware.
- Ensure neither helper throws. Both must return boolean results and clean up
any temporary probe file they create.
- Add a boolean field named `IsInstallationPoolAutoDerived` to
`GenHub.Core/Models/Storage/CasConfiguration.cs`, defaulting to `false`.
- Update `CasConfiguration.Clone()` to copy this new field.
- Update `CasModule.cs` and `ConfigurationProviderService.GetCasConfiguration()`
so both the new field and `InstallationPoolRootPath` are copied through options
binding. Fix the gap where `GetCasConfiguration()` builds a new
`CasConfiguration` for the default `CasRootPath` case but currently drops
`InstallationPoolRootPath`.
===============================================================================

Task: 2

Implement writability-based availability resolution and expanded content-type
routing in `CasPoolResolver`.

- Update `IsInstallationPoolAvailable()` in
`GenHub/GenHub/Features/Storage/Services/CasPoolResolver.cs` so it returns
`true` only when `InstallationPoolRootPath` is non-empty, the path is valid and
reachable, and the Task 1.1 writability probe succeeds.
- Cache the probe result inside the resolver to avoid probing on every call. Add
an internal method to invalidate the cached result, for later use when the pool
is reinitialized. Log the selected pool and the fallback reason once per
resolution, not once per operation.
- Update `GetPoolRootPath(CasPoolType)` and `GetPoolRootPath(ContentType)`:
return the configured `CasRootPath` when the installation pool is unavailable,
and return the application-data CAS pool path when `CasRootPath` is empty.
- Extend the `InstallationPoolTypes` set in `CasPoolResolver.cs` to include
`ContentType.Addon`, `ContentType.Patch`, `ContentType.Map`, and
`ContentType.Mod`, in addition to the existing `GameInstallation` and
`GameClient`.
- Preserve the fallback behavior so any content type resolves to
`CasPoolType.Primary` when the installation pool is unavailable.
===============================================================================

Task: 3

Thread `ContentType` through the content storage, retrieval, and workspace
materialization paths so pool routing takes real effect end to end.

- Update `ContentStorageService.StoreContentFilesAsync` and
`RetrieveContentAsync` in
`GenHub/GenHub/Features/Content/Services/ContentStorageService.cs` to call the
pool-aware `ICasService.StoreContentAsync(..., ContentType, ...)` and
`GetContentPathAsync(hash, ContentType, ...)` overloads, passing
`manifest.ContentType`. Do not change the public `IContentStorageService`
signatures unless required, since `ContentManifest.ContentType` is already
available inside these methods.
- Add a `ContentType` parameter to `IFileOperationsService.LinkFromCasAsync` and
`CopyFromCasAsync`. Update their implementations in
`GenHub/GenHub/Features/Workspace/FileOperationsService.cs` to call the
pool-aware `ICasService.GetContentPathAsync(hash, contentType, ...)` overload.
- Thread `manifest.ContentType` from `ProcessManifestFileAsync` down through
`ProcessCasFileAsync` and `CreateCasLinkAsync` in
`GenHub/GenHub/Features/Workspace/Strategies/WorkspaceStrategyBase.cs` and the
concrete strategies, so per-file linking resolves the same pool used at storage
time.
- Preserve the existing cross-volume copy fallback (`#346`). Confirm the fallback
still runs when the resolved installation pool is on a different volume than the
workspace.
===============================================================================

Task: 4

Build the probe-and-persist flow, a startup migration/repair step for protected
persisted paths, and a runtime reinitialization mechanism for the installation
pool.

- At the installation-detection choke point
(`GameInstallationDetectionOrchestrator.DetectAllInstallationsAsync`) and/or
`ProfileLauncherFacade.ResolveOrRebindInstallationAsync`, derive the candidate
installation-adjacent CAS path using `IStorageLocationService.GetCasPoolPath`.
- Probe the candidate path with the Task 1.1 writability helper. When it is
writable and the user has not deliberately configured a CAS path, persist it to
`UserSettings.CasConfiguration.InstallationPoolRootPath` through
`IUserSettingsService.TryUpdateAndSaveAsync`, and set
`IsInstallationPoolAutoDerived = true`. When the candidate path is not writable,
do not persist it, and leave the installation pool unavailable so routing falls
back to the primary or application-data pool.
- Add a startup migration step (a small hosted service or a step invoked during
CAS startup) that reads `UserSettings.CasConfiguration`. When
`InstallationPoolRootPath` is non-empty, `IsInstallationPoolAutoDerived` is
`true`, and the path is protected or not writable, clear or re-derive the value
through `IUserSettingsService.TryUpdateAndSaveAsync`. Do not modify paths the
user configured deliberately (`IsInstallationPoolAutoDerived == false`).
- Do not delete any CAS objects under the previous root during migration.
Preserve the previous root's content so it can be read or reacquired. Because
manifests and reference files store only hashes and live under the primary
`CasRootPath`, no manifest or reference rewrite is required. Document that
content only present under the abandoned root will be reacquired on next demand.
Log the repair action and the reason once.
- Add a `ReinitializeInstallationPool()` method to `ICasPoolManager`,
implemented in `GenHub/GenHub/Features/Storage/Services/CasPoolManager.cs`. It
must remove the cached `CasPoolType.Installation` entry from `_storages`,
re-read the current effective configuration, invalidate the resolver's cached
probe result, and rebuild the installation storage only when the pool is
available.
- Make `CasPoolResolver` read the current effective installation-pool
configuration rather than a value captured once, using the shared current-config
source, so the reinitialized manager and resolver stay in agreement.
- Call `ReinitializeInstallationPool()` from both the persistence flow and the
migration step after the effective path changes.
===============================================================================

Task: 5

Make garbage collection and related maintenance operations iterate all pools and
skip pools that are not writable, so an unwritable installation pool is never
mutated.

- Update `CasService.RunGarbageCollectionAsync` (and
`ValidateIntegrityAsync`/`GetStatsAsync` as needed) in
`GenHub/GenHub/Features/Storage/Services/CasService.cs` to iterate pools through
`ICasPoolManager.GetAllStorages()` when a pool manager is present, instead of
operating only on the single default `ICasStorage`.
- Before any mutation on a pool, check pool writability using the Task 1.1
helper (or a resolver/manager writability check). Skip a pool that is not
writable and log the skip once. Do not attempt `DeleteObjectAsync` or directory
creation against an unwritable pool.
- Guard `CasStorage.DeleteObjectAsync` so its `EnsureDirectoriesCreated()` call
cannot throw `UnauthorizedAccessException` up to the caller. Wrap or precede it
with a writability check so an unwritable pool degrades gracefully instead of
throwing on every unreferenced hash.
===============================================================================

Task: 6

Add automated test coverage for the resolver, manager, migration, and garbage
collection behavior, and document the manual packaged Windows validation.

- Add `CasPoolResolverTests.cs` and `CasPoolManagerTests.cs` under
`GenHub.Tests/GenHub.Tests.Core/Features/Storage/`, following the
direct-construction Moq pattern from `WorkspaceManagerTests.cs`, using
`Mock<IOptions<CasConfiguration>>`, `Mock<ILogger<T>>`, and
`Mock<ILoggerFactory>`.
- Cover in these unit tests: an empty installation-pool path resolves to
Primary; a writable installation-pool path resolves to Installation for each
routed content type; an unwritable installation-pool path resolves to Primary;
the additional content types (`Addon`, `Patch`, `Map`, `Mod`) route correctly;
the probe result is cached and invalidated on reinitialization;
`ReinitializeInstallationPool` rebuilds the installation storage after the path
changes.
- Add tests for the startup migration step: an auto-derived protected path is
cleared or re-derived; a user-configured path is preserved; a writable
auto-derived path is preserved; no CAS objects are deleted during migration.
- Add an integration test modeled on `GameProfileWorkspaceIntegrationTest.cs`
that creates a temporary directory marked read-only (via
`FileAttributes.ReadOnly` on Windows or the Unix-mode equivalent), and asserts
the installation pool is treated as unavailable with routing falling back to
Primary.
- Add a garbage-collection test asserting that an unwritable pool is skipped and
not mutated.
- Document the packaged, non-administrator Windows validation steps: install the
game under `Program Files`, acquire `GameClient` content, create a profile, and
launch. Confirm acquisition succeeds through the fallback pool, and confirm a
cross-volume workspace preparation succeeds through the copy path. Record
whether launches with pre-populated content require only CAS reads, since the
ticket asks for this to be verified rather than assumed.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!