Make explicit file updates atomic and harden filesystem handling

[Widthdom]

Summary

• Make explicit index --files updates fail atomically when any directly supplied input is invalid or resolves to a duplicate target.
• Keep real and dry-run rejection behavior aligned, while preserving valid cleanup of previously indexed control inputs.
• Harden symlink, path-casing, configuration-file, and watch-internal-artifact handling across platforms.

Root cause

The explicit-file pipeline could filter or normalize inputs before validating the complete user-supplied selection, allowing partial or empty updates instead of one atomic rejection. Related filesystem paths also relied on lexical or workspace-wide comparisons and path-based reopening, so aliases, target-specific casing, symlinks, special files, and watch-internal artifacts could be handled inconsistently.

Implementation

• Preserve direct --files token provenance and preflight the complete selection before database writes, with bounded structured rejection diagnostics.
• Reject bare --files, invalid paths, directories, unsupported inputs, and canonical duplicates while retaining indexed cleanup and reconciliation-control exceptions.
• Apply target-filesystem casing and native path identity rules, including Windows short-path handling and atomic rejection of invalid Windows filename components.
• Keep indexed exact-path lookups on their existing index and bound case-fold candidate discovery to at most one files scan per request.
• Propagate the active symlink policy through CLI workers and MCP direct extraction into TypeScript path-alias reads, and securely open regular configuration files without blocking on special files.
• Exclude resolved aliases of database, WAL, journal, lock, checkpoint, restore, backup, and temporary artifacts from polling-watch batches.
• Fall back from a watch-generated partial-update UsageError to one full-workspace rescan so valid sibling changes are reconciled.
• Isolate plugin and hook discovery fixtures from the large test assembly so the production 4,096-type safety limit remains unchanged and deterministic.
• Add focused coverage for real/dry-run parity, atomicity, casing, symlink policies, FIFOs, Windows aliases, polling-watch behavior, and fixture isolation.

Validation

• dotnet restore CodeIndex.sln --locked-mode -p:NuGetAudit=false
• dotnet build CodeIndex.sln -c Release --no-restore -p:UseSharedCompilation=false (0 warnings, 0 errors)
• Focused Release suite for Restore diagnostics when index --files selects no valid in-project paths #5091, Canonicalize Windows 8.3 aliases in targeted index updates #5122, CI fixture regressions, and package-lock contracts:
  • net8.0: 154 passed, 0 failed
  • net9.0: 149 passed, 3 expected platform skips, 0 failed
• dotnet format CodeIndex.sln --no-restore --verify-no-changes
• dotnet run --project tools/CodeIndex.Changelog -- check (26 fragments)
• Local Debug binary: full rebuild, backfill-fold, status --check, and workspace status --check
• Final adversarial audit: No blocking/actionable issues found.

Documentation and changelog

• Updated USER_GUIDE.md, DEVELOPER_GUIDE.md, and TESTING_GUIDE.md in English and Japanese.
• Added bilingual changelog.d/unreleased/5091.fixed.md.

Follow-ups

Remaining out-of-scope work is tracked in #5120 and #5124.

Fixes #5091
Fixes #5122