README: Replace --threads with real cobra concurrency flags

Docs sync: align README with current install/CLI behavior.

Co-authored-by: s1d3sw1ped_bot <s1d3sw1ped+giteabot@gmail.com>
Co-committed-by: s1d3sw1ped_bot <s1d3sw1ped+giteabot@gmail.com>

.gitea/workflows/release-tag.yaml

@@ -7,6 +7,8 @@ on:
 jobs:
   release:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@main
         with:
@@ -21,4 +23,6 @@ jobs:
           version: 'latest'
           args: release
         env:
-          GITEA_TOKEN: ${{secrets.RELEASE_TOKEN}}     
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GORELEASER_FORCE_TOKEN: gitea

.gitea/workflows/test-pr.yaml

@@ -1,24 +1,38 @@
-name: PR Check
+name: CI
 on:
-  - pull_request
+  pull_request:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+      - 'CONTRIBUTING.md'
 
 jobs:
   check-and-test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@main
-      - uses: actions/setup-go@main
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
         with:
           go-version-file: 'go.mod'
       - run: go mod tidy
       - run: go build ./...
       - run: go vet ./...
       - name: golangci-lint
-        uses: golangci/golangci-lint-action@v4
+        uses: golangci/golangci-lint-action@v8
         with:
-          version: latest
+          version: v2.13.2
           args: --timeout=5m
+      - run: go test -race -v -shuffle=on -coverprofile=coverage.out -timeout=5m ./...
+      - run: go tool cover -func=coverage.out | tail -10  # basic coverage report
+
+  vulncheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'
       - run: go install golang.org/x/vuln/cmd/govulncheck@latest
       - run: govulncheck ./...
-      - run: go test -race -v -shuffle=on -coverprofile=coverage.out -timeout=5m ./...
-      - run: go tool cover -func=coverage.out | tail -10  # basic coverage report

.golangci.yml

@@ -1,86 +1,94 @@
-# .golangci.yml - steamcache2 lint config
+# .golangci.yml - steamcache2 lint config (golangci-lint v2)
 # Philosophy: enable reasonable linters by default (golangci curated set + key additions)
 # then use most specific suppressions possible (source //nosec with justification,
 # _ = discard for errcheck on unavoidable client writes, narrow exclude-rules only for tests).
 # This makes remaining accepted issues visible and actionable in the code.
 # Run with: make lint (or golangci-lint run ./...)
-# Install: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+version: "2"
 
 run:
   timeout: 5m
   modules-download-mode: readonly
 
 linters:
-  # No disable-all: use golangci defaults (errcheck, govet, ineffassign, staticcheck, unused, gosimple, etc.)
+  # No default: none — use golangci defaults (errcheck, govet, ineffassign, staticcheck, unused, etc.)
   # Explicitly enable the non-default linters we require for this LAN cache proxy.
   enable:
     - gosec     # security checks (re-audited; see source //nosec for justified cases)
     - misspell  # documentation hygiene
-    - goimports # import formatting (enforced)
-    # gofmt covered via linter or goimports; errcheck/govet etc. from defaults
+  settings:
+    errcheck:
+      check-type-assertions: false
+      check-blank: false
+    # gosec: keep source-level //nosec for G104/G115/G301/G304/G306.
+    # G704/G705 are new taint-analysis rules (SSRF/XSS) not present in v1.64.8;
+    # a CDN cache proxy forwards upstream URLs and response bodies by design.
+    gosec:
+      excludes:
+        - G704
+        - G705
+    # v1 staticcheck checks: ["all"] meant SA* only. v2 merged stylecheck (ST*)
+    # and quickfix (QF*) into staticcheck; keep the previous SA*+gosimple set.
+    staticcheck:
+      checks:
+        - all
+        - "-ST*"
+        - "-QF*"
+    govet:
+      enable-all: true
+      disable:
+        - fieldalignment # performance tuning not a priority for this proxy appliance
+        - shadow # common idiomatic "err" redeclarations in error-handling chains (large ServeHTTP, root, parse funcs); enabling adds noise with no real bugs; would require scope refactor for little gain
+  exclusions:
+    generated: lax
+    paths:
+      - dist
+      - bin
+    rules:
+      - path: _test\.go
+        linters:
+          - errcheck
+          - gosec # tests often use weak patterns intentionally (e.g. error injection, temp files)
+      # NOTE: narrow SA9003 exclude retained only for the one remaining intentional empty branch in test (best-effort status check; main assert is metrics side-effect).
+      - path: steamcache/steamcache_test.go
+        linters:
+          - staticcheck
+        text: "SA9003: empty branch"
+      # Narrow gosec excludes for unavoidable classes after re-audit (LAN proxy threat model):
+      # - G115: int64<->uint casts in eviction/GC math (all sizes positive, guarded by capacity checks; API uses uint for bytesNeeded)
+      # - G304: path vars for Read/Open/Remove under trusted disk.root or user config file (sanitized keys, no traversal, no arbitrary inclusion from untrusted URLs)
+      # G306 for config WriteFile kept as source //nosec (one site).
+      # G301 fixed at source (0700 dirs). G104 addressed via errcheck fixes.
+      - path: vfs/memory/memory.go
+        linters:
+          - gosec
+        text: "G115"
+      - path: vfs/disk/disk.go
+        linters:
+          - gosec
+        text: "G115"
+      - path: vfs/gc/gc.go
+        linters:
+          - gosec
+        text: "G115"
+      - path: config/config.go
+        linters:
+          - gosec
+        text: "G304"
+      - path: vfs/disk/disk.go
+        linters:
+          - gosec
+        text: "G304"
 
-linters-settings:
-  errcheck:
-    check-type-assertions: false
-    check-blank: false
-  gosec:
-    # Broad global excludes removed (G104/G115/G301/G304/G306).
-    # - G301 addressed by switching cache MkdirAll to 0700 (least privilege for CDN content).
-    # - Remaining justified cases documented with precise //nosec (or #nosec) + comments at the call sites.
-    # - G104 largely eliminated by errcheck + explicit _ = handling (or defer wrappers).
-  staticcheck:
-    checks: ["all"] # SA1019 exclusion removed (no deprecated API usages in tree)
-  govet:
-    enable-all: true
-    disable:
-      - fieldalignment # performance tuning not a priority for this proxy appliance
-      - shadow # common idiomatic "err" redeclarations in error-handling chains (large ServeHTTP, root, parse funcs); enabling adds noise with no real bugs; would require scope refactor for little gain
-
-# Old global errcheck disable + aspirational "re-enable after refactors" comments deleted.
-# errcheck is now on via defaults. Unavoidable cases handled at source with _ = or (rarely) narrow rules.
+formatters:
+  enable:
+    - goimports
+  exclusions:
+    generated: lax
+    paths:
+      - dist
+      - bin
 
 issues:
   max-issues-per-linter: 0
   max-same-issues: 0
-  exclude-use-default: false
-  exclude-dirs:
-    - dist
-    - bin
-  exclude-rules:
-    - path: _test\.go
-      linters:
-        - errcheck
-        - gosec # tests often use weak patterns intentionally (e.g. error injection, temp files)
-    # NOTE: narrow SA9003 exclude retained only for the one remaining intentional empty branch in test (best-effort status check; main assert is metrics side-effect).
-    # The config one was a truly redundant check (already errored above); deleted surgically in Fix Round 1 (Issue 1), eliminating its exclude-rule.
-    - path: steamcache/steamcache_test.go
-      linters:
-        - staticcheck
-      text: "SA9003: empty branch"
-    # Narrow gosec excludes for unavoidable classes after re-audit (LAN proxy threat model):
-    # - G115: int64<->uint casts in eviction/GC math (all sizes positive, guarded by capacity checks; API uses uint for bytesNeeded)
-    # - G304: path vars for Read/Open/Remove under trusted disk.root or user config file (sanitized keys, no traversal, no arbitrary inclusion from untrusted URLs)
-    # G306 for config WriteFile kept as source //nosec (one site).
-    # G301 fixed at source (0700 dirs). G104 addressed via errcheck fixes.
-    - path: vfs/memory/memory.go
-      linters:
-        - gosec
-      text: "G115"
-    - path: vfs/disk/disk.go
-      linters:
-        - gosec
-      text: "G115"
-    - path: vfs/gc/gc.go
-      linters:
-        - gosec
-      text: "G115"
-    - path: config/config.go
-      linters:
-        - gosec
-      text: "G304"
-    - path: vfs/disk/disk.go
-      linters:
-        - gosec
-      text: "G304"
-    # Predictive/* rules deleted: vfs/predictive/ removed in commit 0dbb2e0; rules were stale/dead.
-    # All other suppressions use source-level //nosec (gosec) or _= (errcheck) for precision and visibility.

CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+## Propose changes
+
+Open a pull request against `develop`. Keep the default branch for releases and
+stable tips; land work on `develop` first.
+
+Point at an existing issue when one fits. Prefer a short issue that states the
+symptom or request before a large PR.
+
+## Commits
+
+Subject form:
+
+```
+area: Imperative summary
+```
+
+- **Area** is a real package, directory, or subsystem token (`ci:`, `docs:`,
+  Go package name). Not a lone filename.
+- **Imperative** mood: Fix, Add, Remove — not "Fixed" or "This patch…".
+- No trailing period. Aim ≤ ~70–75 characters for the whole subject.
+- Not conventional-commits (`feat:` / `fix:` / `chore:` as types).
+
+Body explains **why**. Establish the problem, then say what you are doing.
+One logical change per commit; split fix and cleanup.
+
+## Pull requests
+
+Title matches the primary commit subject.
+
+- **What** changed
+- **Why** (problem and impact)
+- **Test** (concrete steps; "CI green" alone is weak)
+
+## Issues and closing
+
+Cite leftover issues by **full URL**. Gitea closes issues when `#N` appears in
+merge text, so do not put `#N` in the merge message unless that issue is actually
+done. Use `Fixes #N` / `Closes #N` only when the leftover work is finished.

README.md

@@ -160,8 +160,9 @@ While most configuration is done via the YAML file, some runtime options are sti
 # Set logging level
 ./steamcache2 --log-level debug --log-format json
 
-# Set number of worker threads
-./steamcache2 --threads 8
+# Override concurrency from the CLI (0 = use config.yaml)
+./steamcache2 --max-concurrent-requests 8
+./steamcache2 --max-requests-per-client 4
 
 # Show help
 ./steamcache2 --help
@@ -311,7 +312,7 @@ This will direct any requests to `lancache.steamcontent.com` to your SteamCache2
 
 ### Prerequisites
 
-- Go 1.19 or later
+- Go 1.27.0 or later
 - Make (optional, but recommended)
 
 ### Build Commands
@@ -319,7 +320,7 @@ This will direct any requests to `lancache.steamcontent.com` to your SteamCache2
 ```bash
 # Clone the repository
 git clone <repository-url>
-cd SteamCache2
+cd steamcache2
 
 # Download dependencies
 make deps

go.mod

@@ -1,6 +1,6 @@
 module s1d3sw1ped/steamcache2
 
-go 1.23.0
+go 1.27.0
 
 require (
 	github.com/docker/go-units v0.5.0

steamcache/handler.go

@@ -345,6 +345,18 @@ func (sc *SteamCache) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 			req.Host = r.Host
 		} else { // if no upstream server is configured, proxy the request to the host specified in the request
 			host := r.Host
+			if !hostAllowedForDirectFetch(host) {
+				logger.Logger.Warn().
+					Str("host", host).
+					Str("client_ip", clientIP).
+					Msg("Rejecting direct-fetch Host (not a Steam CDN name)")
+				sc.metrics.IncrementErrors()
+				if isNew {
+					coalescedReq.complete(nil, fmt.Errorf("host not allowed for direct fetch"))
+				}
+				http.Error(w, "Invalid URL", http.StatusBadRequest)
+				return
+			}
 			if r.Header.Get("X-Sls-Https") == "enable" {
 				host = "https://" + host
 			} else {

steamcache/service.go

@@ -5,6 +5,7 @@ import (
 	"crypto/sha256"
 	"encoding/hex"
 	"fmt"
+	"net"
 	"net/http"
 	"regexp"
 	"strings"
@@ -163,3 +164,44 @@ func generateServiceCacheKey(urlPath string, servicePrefix string) (string, erro
 	}
 	return servicePrefix + "/" + hash, nil
 }
+
+// requestHostName strips a port and brackets from an HTTP Host header.
+func requestHostName(host string) string {
+	host = strings.TrimSpace(host)
+	if host == "" {
+		return ""
+	}
+	if h, _, err := net.SplitHostPort(host); err == nil {
+		host = h
+	}
+	return strings.Trim(host, "[]")
+}
+
+func hostIsLiteralIP(host string) bool {
+	return net.ParseIP(requestHostName(host)) != nil
+}
+
+// defaultDirectFetchSuffixes are CDN names Steam actually uses. Applied only when
+// no configured upstream is set and the request Host is used as the fetch target.
+var defaultDirectFetchSuffixes = []string{
+	"steamcontent.com",
+	"steampowered.com",
+	"steamstatic.com",
+}
+
+// hostAllowedForDirectFetch reports whether Host may be used as an origin when
+// upstream is empty. Literal IPs are rejected (LAN/metadata SSRF). Names must
+// be Steam CDN suffixes so a spoofed User-Agent cannot turn the cache into an
+// open reverse proxy.
+func hostAllowedForDirectFetch(host string) bool {
+	name := strings.ToLower(requestHostName(host))
+	if name == "" || hostIsLiteralIP(host) {
+		return false
+	}
+	for _, suf := range defaultDirectFetchSuffixes {
+		if name == suf || strings.HasSuffix(name, "."+suf) {
+			return true
+		}
+	}
+	return false
+}

steamcache/steamcache.go

@@ -357,7 +357,7 @@ func newHTTPTransport() *http.Transport {
 		DialContext: (&net.Dialer{
 			Timeout:   10 * time.Second, // Faster connection timeout
 			KeepAlive: 60 * time.Second, // Longer keep-alive
-			DualStack: true,             // Enable dual-stack (IPv4/IPv6)
+			// Dual-stack Happy Eyeballs is the default since Go 1.12 (DualStack is deprecated).
 		}).DialContext,
 
 		// Timeout optimizations
@@ -387,11 +387,10 @@ func newHTTPClient(transport *http.Transport) *http.Client {
 		Timeout:   60 * time.Second, // Optimized timeout for better responsiveness
 		// Add redirect policy for better performance
 		CheckRedirect: func(req *http.Request, via []*http.Request) error {
-			// Limit redirects to prevent infinite loops
-			if len(via) >= 10 {
-				return http.ErrUseLastResponse
-			}
-			return nil
+			// Do not follow redirects. Steam CDN chunk/manifest fetches are
+			// expected to be 200; following Location would let an origin send
+			// the cache at an arbitrary internal URL.
+			return http.ErrUseLastResponse
 		},
 	}
 }

steamcache/steamcache_test.go

@@ -1165,3 +1165,61 @@ func TestClientRateLimiter_BlackBox(t *testing.T) {
 		t.Error("different clients must have distinct limiters")
 	}
 }
+
+func TestHostAllowedForDirectFetch(t *testing.T) {
+	allowed := []string{
+		"lancache.steamcontent.com",
+		"cache1-iad1.steamcontent.com:443",
+		"steamcontent.com",
+		"content.steampowered.com",
+		"cdn.steamstatic.com",
+	}
+	denied := []string{
+		"",
+		"127.0.0.1",
+		"127.0.0.1:80",
+		"[::1]:80",
+		"192.168.1.1",
+		"169.254.169.254",
+		"evil.example",
+		"example.com",
+		"notsteamcontent.com",
+	}
+	for _, h := range allowed {
+		if !hostAllowedForDirectFetch(h) {
+			t.Errorf("expected allowed: %q", h)
+		}
+	}
+	for _, h := range denied {
+		if hostAllowedForDirectFetch(h) {
+			t.Errorf("expected denied: %q", h)
+		}
+	}
+}
+
+func TestDirectFetchRejectsNonSteamHost(t *testing.T) {
+	td := t.TempDir()
+	sc, err := New("127.0.0.1:0", "1MB", "0", td, "", "lru", "lru", 200, 5, "0", nil)
+	if err != nil {
+		t.Fatalf("New: %v", err)
+	}
+	t.Cleanup(func() { sc.Shutdown() })
+
+	req := httptest.NewRequest("GET", "/depot/ssrf/chunk", nil)
+	req.Host = "127.0.0.1"
+	req.Header.Set("User-Agent", "Valve/Steam HTTP Client 1.0")
+	rec := httptest.NewRecorder()
+	sc.ServeHTTP(rec, req)
+	if rec.Code != http.StatusBadRequest {
+		t.Errorf("IP Host: expected 400, got %d", rec.Code)
+	}
+
+	req2 := httptest.NewRequest("GET", "/depot/ssrf/chunk2", nil)
+	req2.Host = "evil.example"
+	req2.Header.Set("User-Agent", "Valve/Steam HTTP Client 1.0")
+	rec2 := httptest.NewRecorder()
+	sc.ServeHTTP(rec2, req2)
+	if rec2.Code != http.StatusBadRequest {
+		t.Errorf("non-CDN Host: expected 400, got %d", rec2.Code)
+	}
+}

vfs/cache/cache.go

@@ -186,7 +186,7 @@ func (tc *TieredCache) Capacity() int64 {
 func (tc *TieredCache) promoteToFast(key string, reader io.ReadCloser) {
 	defer func() { _ = reader.Close() }() // best-effort close; error secondary to promotion attempt (async best-effort path)
 
-	// Get file info from slow tier to determine size
+	// Size for the space/ReadAll guards comes from a Stat snapshot, not the live in-map FileInfo.
 	var size int64
 	if slow := tc.slow.Load(); slow != nil {
 		if vfs, ok := slow.(vfs.VFS); ok {
@@ -210,7 +210,7 @@ func (tc *TieredCache) promoteToFast(key string, reader io.ReadCloser) {
 	}
 
 	// Guard promotion ReadAll using already-fetched size (in addition to space check above)
-	if size > 0 && size > (1<<30) { // conservative 1GB hard limit on promotion reads (aligns with typical max_object_size)
+	if size > (1 << 30) { // conservative 1GB hard limit on promotion reads (aligns with typical max_object_size)
 		return
 	}
 	// Read the entire file content
@@ -218,6 +218,8 @@ func (tc *TieredCache) promoteToFast(key string, reader io.ReadCloser) {
 	if err != nil {
 		return // Skip promotion if read fails
 	}
+	// Create with the bytes we actually hold so we never reuse a live FileInfo.Size.
+	size = int64(len(content))
 
 	// Create the file in fast tier
 	if fast := tc.fast.Load(); fast != nil {

vfs/disk/disk.go

@@ -248,15 +248,25 @@ func (d *DiskFS) calculateSizeAndPopulateIndex() {
 
 // insertBatch populates info/LRU under lock for a bounded batch (follows maxEvictBatch pattern for short critical sections).
 // Size is incremented here only for files actually added (prevents double-count vs. concurrent Create during window).
+// Fail-closed: re-stat each path under d.mu and skip if the file is gone. Create does not wait on
+// initDone, so a file the scanner observed can be Evict/Delete'd (info + os.Remove) before this
+// insert runs. Inserting without a live-file check would resurrect the key in d.info and make
+// Stat succeed while os.Stat fails.
 func (d *DiskFS) insertBatch(batch []discoveredFile) {
 	d.mu.Lock()
 	for _, df := range batch {
-		if _, exists := d.info[df.key]; !exists {
-			fi := vfs.NewFileInfoFromOS(df.osInfo, df.key)
-			d.info[df.key] = fi
-			d.LRU.Add(df.key, fi)
-			d.size += df.size
+		if _, exists := d.info[df.key]; exists {
+			continue
 		}
+		path := d.pathForKey(df.key)
+		st, err := os.Stat(path)
+		if err != nil {
+			continue
+		}
+		fi := vfs.NewFileInfoFromOS(st, df.key)
+		d.info[df.key] = fi
+		d.LRU.Add(df.key, fi)
+		d.size += st.Size()
 	}
 	d.mu.Unlock()
 }
@@ -602,7 +612,9 @@ func (d *DiskFS) Delete(key string) error {
 	return nil
 }
 
-// Stat returns file information with lazy discovery
+// Stat returns a snapshot of file information with lazy discovery.
+// The returned *FileInfo is not the live cache entry; Close may update Size
+// on the in-map object under d.mu.
 func (d *DiskFS) Stat(key string) (*vfs.FileInfo, error) {
 	if key == "" {
 		return nil, vfserror.ErrInvalidKey
@@ -617,9 +629,10 @@ func (d *DiskFS) Stat(key string) (*vfs.FileInfo, error) {
 	keyMu.RLock()
 	d.mu.RLock()
 	if fi, ok := d.info[key]; ok {
+		snap := fi.Clone()
 		d.mu.RUnlock()
 		keyMu.RUnlock()
-		return fi, nil
+		return snap, nil
 	}
 	d.mu.RUnlock()
 	keyMu.RUnlock()
@@ -639,8 +652,9 @@ func (d *DiskFS) Stat(key string) (*vfs.FileInfo, error) {
 	// Double-check after acquiring write lock
 	d.mu.Lock()
 	if fi, ok := d.info[key]; ok {
+		snap := fi.Clone()
 		d.mu.Unlock()
-		return fi, nil
+		return snap, nil
 	}
 
 	// Re-verify the file still exists on disk under the lock before inserting.
@@ -659,9 +673,10 @@ func (d *DiskFS) Stat(key string) (*vfs.FileInfo, error) {
 	fi.UpdateAccessBatched(d.timeUpdater)
 	// Note: size not updated on lazy discovery (preserves prior behavior; initial on-disk accounted via bg populate at New time,
 	// subsequent files come via Create which accounts size).
+	snap := fi.Clone()
 	d.mu.Unlock()
 
-	return fi, nil
+	return snap, nil
 }
 
 // EvictLRU evicts the least recently used files to free up space

vfs/disk/disk_test.go

@@ -371,7 +371,8 @@ func testKey(i int) string {
 // artifacts for victims are immediately gone (no resurrection via lazy discovery in Stat/Open),
 // and that recreating the same key produces independent content that is not subject to any
 // stale eviction unlinks. This exercises the coordinated WLock remove path for DiskFS.
-// Uses tolerant checks suitable for raw DiskFS lazy discovery + bg size.
+// Create does not wait on initDone, so this also covers insertBatch racing with eviction:
+// gone files must not be re-indexed (Stat present / disk missing).
 func TestDiskFS_EvictDiskVisibilityAndRecreateSafety(t *testing.T) {
 	t.Parallel()
 	td := t.TempDir()
@@ -400,47 +401,21 @@ func TestDiskFS_EvictDiskVisibilityAndRecreateSafety(t *testing.T) {
 		_ = d.EvictBySize(1024*1024, true)
 	}
 
-	// Consistency check: never have a key absent from Stat but with a file on disk (would indicate
-	// either resurrection risk or orphan). If Stat succeeds, file should exist.
-	// A few retries tolerate the documented lazy discovery + eviction coordination windows under
-	// artificial "force massive eviction then immediate audit" load (especially visible under -race).
-	for attempt := 0; attempt < 3; attempt++ {
-		bad := false
-		for _, k := range created {
-			p := d.pathForKey(k)
-			_, statErr := d.Stat(k)
-			_, diskErr := os.Stat(p)
-			if statErr != nil {
-				if !os.IsNotExist(diskErr) {
-					bad = true
-				}
-			} else {
-				if diskErr != nil {
-					bad = true
-				}
-			}
-		}
-		if !bad {
-			break
-		}
-		if attempt < 2 {
-			time.Sleep(10 * time.Millisecond)
-		} else {
-			// On final attempt, report the last observed state for the keys
-			for _, k := range created {
-				p := d.pathForKey(k)
-				_, statErr := d.Stat(k)
-				_, diskErr := os.Stat(p)
-				if statErr != nil {
-					if !os.IsNotExist(diskErr) {
-						t.Errorf("key %s absent via Stat but file lingers on disk at %s (resurrection risk)", k, p)
-					}
-				} else {
-					if diskErr != nil {
-						t.Errorf("key %s present via Stat but missing on disk: %v", k, diskErr)
-					}
-				}
+	// Drain bg population so insertBatch cannot still be in flight when we audit.
+	_ = d.Size()
+
+	// Consistency: Stat success iff the file exists on disk. insertBatch must not resurrect
+	// keys whose backing files were already evicted.
+	for _, k := range created {
+		p := d.pathForKey(k)
+		_, statErr := d.Stat(k)
+		_, diskErr := os.Stat(p)
+		if statErr != nil {
+			if !os.IsNotExist(diskErr) {
+				t.Errorf("key %s absent via Stat but file lingers on disk at %s (resurrection risk)", k, p)
 			}
+		} else if diskErr != nil {
+			t.Errorf("key %s present via Stat but missing on disk: %v", k, diskErr)
 		}
 	}
 
@@ -464,6 +439,64 @@ func TestDiskFS_EvictDiskVisibilityAndRecreateSafety(t *testing.T) {
 	}
 }
 
+// TestDiskFS_InsertBatchSkipsGoneFiles is the fail-closed contract for bg/lazy index
+// insert: a discoveredFile whose path was removed (evicted) must not be re-inserted
+// into d.info. That resurrection is what made Stat succeed while os.Stat failed.
+func TestDiskFS_InsertBatchSkipsGoneFiles(t *testing.T) {
+	t.Parallel()
+	td := t.TempDir()
+	d, err := New(td, 10*1024*1024, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = d.Size() // finish constructor scan so it cannot also index these keys
+
+	liveKey := "live"
+	goneKey := "gone"
+	writeKey := func(key, body string) os.FileInfo {
+		t.Helper()
+		p := d.pathForKey(key)
+		if err := os.MkdirAll(filepath.Dir(p), 0700); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(p, []byte(body), 0600); err != nil {
+			t.Fatal(err)
+		}
+		st, err := os.Stat(p)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return st
+	}
+	liveInfo := writeKey(liveKey, "still-here")
+	goneInfo := writeKey(goneKey, "about-to-vanish")
+	if err := os.Remove(d.pathForKey(goneKey)); err != nil {
+		t.Fatal(err)
+	}
+
+	d.insertBatch([]discoveredFile{
+		{key: liveKey, size: liveInfo.Size(), osInfo: liveInfo},
+		{key: goneKey, size: goneInfo.Size(), osInfo: goneInfo},
+	})
+
+	d.mu.RLock()
+	_, liveExists := d.info[liveKey]
+	_, goneExists := d.info[goneKey]
+	d.mu.RUnlock()
+	if !liveExists {
+		t.Errorf("insertBatch skipped live key %s", liveKey)
+	}
+	if goneExists {
+		t.Errorf("insertBatch resurrected gone key %s", goneKey)
+	}
+	if _, err := d.Stat(goneKey); err == nil {
+		t.Errorf("Stat succeeded for gone key %s", goneKey)
+	}
+	if _, err := os.Stat(d.pathForKey(liveKey)); err != nil {
+		t.Errorf("live key %s missing on disk: %v", liveKey, err)
+	}
+}
+
 // TestDiskFS_EvictBoundedLargeN exercises the maxEvictBatch early-break logic (Idea #2)
 // under a map size >> batch limit. Forces repeated eviction rounds via GC-style pressure
 // and asserts progress + consistency (no resurrection/orphans). Covers bounded collection

vfs/memory/memory.go

@@ -289,7 +289,8 @@ func (m *MemoryFS) Delete(key string) error {
 	return nil
 }
 
-// Stat returns file information
+// Stat returns a snapshot of file information. The returned *FileInfo is not
+// the live cache entry; Close may update Size on the in-map object under m.mu.
 func (m *MemoryFS) Stat(key string) (*types.FileInfo, error) {
 	if key == "" {
 		return nil, vfserror.ErrInvalidKey
@@ -310,7 +311,7 @@ func (m *MemoryFS) Stat(key string) (*types.FileInfo, error) {
 	defer m.mu.RUnlock()
 
 	if fi, ok := m.info[key]; ok {
-		return fi, nil
+		return fi.Clone(), nil
 	}
 
 	return nil, vfserror.ErrNotFound

vfs/memory/memory_test.go

@@ -346,6 +346,45 @@ func TestMemoryFS_ConcurrentCloseAndEvict_RaceFree(t *testing.T) {
 	_ = m.LRU.Len()
 }
 
+func TestMemoryFS_StatReturnsSnapshot(t *testing.T) {
+	t.Parallel()
+	m, err := New(1024)
+	if err != nil {
+		t.Fatal(err)
+	}
+	w, err := m.Create("k", 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := w.Write([]byte("hello")); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	fi, err := m.Stat("k")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if fi.Size != 5 {
+		t.Fatalf("size %d want 5", fi.Size)
+	}
+	fi.Size = 999
+	fi.AccessCount = 0
+
+	fi2, err := m.Stat("k")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if fi2.Size != 5 {
+		t.Errorf("Stat returned live FileInfo; store size became %d", fi2.Size)
+	}
+	if fi2.AccessCount == 0 {
+		t.Error("Stat returned live FileInfo; AccessCount mutation leaked")
+	}
+}
+
 func TestMemoryFS_EvictVariantsAndErrors(t *testing.T) {
 	t.Parallel()
 	m, err := New(800)

vfs/types/types.go

@@ -27,6 +27,17 @@ func NewFileInfo(key string, size int64) *FileInfo {
 	}
 }
 
+// Clone returns a snapshot copy of fi. Stat returns Clone() so callers can
+// read Size and other fields without racing Close/Open mutations of the
+// in-map FileInfo.
+func (fi *FileInfo) Clone() *FileInfo {
+	if fi == nil {
+		return nil
+	}
+	cp := *fi
+	return &cp
+}
+
 // NewFileInfoFromOS creates a FileInfo from os.FileInfo
 func NewFileInfoFromOS(info os.FileInfo, key string) *FileInfo {
 	return &FileInfo{

vfs/types/types_test.go

@@ -16,6 +16,34 @@ func TestNewFileInfo(t *testing.T) {
 	}
 }
 
+func TestFileInfoClone(t *testing.T) {
+	t.Parallel()
+	fi := NewFileInfo("k", 42)
+	fi.AccessCount = 7
+	cp := fi.Clone()
+	if cp == fi {
+		t.Fatal("Clone returned the same pointer")
+	}
+	if cp.Key != fi.Key || cp.Size != fi.Size || cp.AccessCount != fi.AccessCount {
+		t.Errorf("Clone mismatch: %+v vs %+v", cp, fi)
+	}
+	if !cp.ATime.Equal(fi.ATime) || !cp.CTime.Equal(fi.CTime) {
+		t.Error("Clone timestamps mismatch")
+	}
+	cp.Size = 99
+	cp.AccessCount = 1
+	if fi.Size != 42 || fi.AccessCount != 7 {
+		t.Error("mutating Clone affected original")
+	}
+	if NewFileInfo("x", 1).Clone() == nil {
+		t.Error("Clone of non-nil was nil")
+	}
+	var none *FileInfo
+	if none.Clone() != nil {
+		t.Error("Clone of nil was non-nil")
+	}
+}
+
 func TestUpdateAccess(t *testing.T) {
 	t.Parallel()
 	fi := NewFileInfo("k", 1)