refactor(fs-retry): consolidate file-retry loops behind withRetry - #526

Summary

Consolidates the divergent hand-rolled file-retry loops behind a single withRetry helper in lib/fs-retry.ts (the existing home of FILE_RETRY_CODES), per audit roadmap §4.2 (docs/audits/AUDIT_2026-06-10.md, PR #522). Mechanical migration only — every call site keeps its exact attempt count, backoff schedule, jitter, retryable code set, and error propagation. Tuning, if any, belongs in a follow-up PR.

Changes

New API in lib/fs-retry.ts:

withRetry<T>(operation, { maxAttempts, backoffMs, jitterMs?, retryableCodes?, onRetry? }): Promise<T>
withRetrySync<T>(operation, options): T   // for the synchronous recovery paths

backoffMs accepts a number or a per-attempt function (covers the existing linear/exponential schedules); retryableCodes defaults to FILE_RETRY_CODES; non-retryable errors rethrow immediately; exhaustion rethrows the final error unchanged. withFileOperationRetry is now a thin delegate.

14 loops migrated across lib/config.ts (×5), lib/storage.ts (×2), lib/quota-cache.ts (×2, including removing a local duplicate of FILE_RETRY_CODES), lib/recovery/storage.ts (×2, sync), lib/codex-manager/commands/uninstall.ts (local withFileOperationRetry duplicate deleted in favor of the shared one), and lib/fs-retry.ts itself.

3 loops deliberately skipped (semantics don't fit attempt-bounded retry; forcing them would change behavior):

• withConfigFileLock acquisition — deadline-based wait with interleaved stale-lock takeover
• savePluginConfig ESTALE CAS loop — re-read/re-merge runs between attempts outside the retryable region
• storage.ts renameTempToPath — sleeps after the final failed attempt before rethrowing, a schedule withRetry intentionally cannot express

New tests: test/fs-retry.test.ts (18 cases) — first-try success, retry-then-success, exhaustion rethrow, non-retryable immediate throw, fake-timer backoff schedules (including jitter and the shared 25/50/100/200/400ms ladder), zero-delay paths, onRetry, and the sync variant.

Validation

• npm run typecheck
• npx eslint <all touched files> --max-warnings=0
• Migrated-module suites (config ×7, quota-cache, recovery-storage, recovery, uninstall ×3, fs-retry): 14 files, 375/375 passed
• test/storage.test.ts and test/storage-recovery-paths.test.ts: failure lists diffed before (clean base) vs after — identical; all failures are the known container sandbox-EACCES environment issues documented in docs/audits/evidence/test-baseline-2026-06-10.txt
• Independently re-verified: typecheck + fs-retry/quota-cache suites, 34/34

Risk / Rollback

Single-commit mechanical migration; revert to roll back. The three skipped sites are unchanged on purpose and listed above for the next pass.

https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB

Generated by Claude Code

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

this pr consolidates 14 hand-rolled file-retry loops across 6 modules into a single withRetry / withRetrySync helper in lib/fs-retry.ts. the migration is mechanical: every call site's attempt count, backoff formula, retryable code set, and error-propagation contract is preserved.

• new api (withRetry, withRetrySync, RetryOptions) replaces per-module duplicates; withFileOperationRetry is now a thin delegate with identical behavior.
• backoff translations from 0-based to 1-based attempt indices are all consistent: 10 * 2 ** attempt (0-based) ↔ 10 * 2 ** (attempt - 1) (1-based), verified across every migrated site.
• error-propagation semantics — ENOENT, non-retryable codes, and exhaustion paths — are semantically equivalent in all migrated functions, including the ENOENT-inside-operation pattern in getConfigFileMtimeMs and the best-effort-swallow pattern in unlinkConfigLockWithRetry.

Confidence Score: 5/5

mechanical migration only — every backoff schedule, attempt count, retryable code set, and error-propagation contract has been faithfully preserved across all 14 migrated sites; no new logic is introduced.

all 0-based-to-1-based backoff conversions are verified correct; ENOENT and non-retryable errors still escape immediately at every call site; the three skipped sites are unchanged and explicitly documented; 375/375 migrated-module tests pass; the only open items were raised in prior review cycles and are all non-blocking.

no files require special attention; lib/fs-retry.ts is the new shared owner of retry semantics and is well covered by the new test suite.

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["caller: operation()"] --> B["withRetry / withRetrySync"]
    B --> C{"attempt\nsucceeds?"}
    C -- yes --> D["return result"]
    C -- no --> E{"isRetryableError?\n(code in retryableCodes)"}
    E -- no --> F["rethrow immediately"]
    E -- yes --> G{"attempt >=\nmaxAttempts?"}
    G -- yes --> F
    G -- no --> H["onRetry?.(error, attempt)"]
    H --> I["computeDelayMs\n(backoffMs + jitter)"]
    I --> J{"delayMs > 0?"}
    J -- no --> B
    J -- yes --> K["async: await sleep(ms)\nsync: busy-wait loop"]
    K --> B

    subgraph callers["migrated call sites"]
        L["lib/config.ts ×4"]
        M["lib/storage.ts ×2"]
        N["lib/quota-cache.ts ×2"]
        O["lib/recovery/storage.ts ×2"]
        P["lib/codex-manager/uninstall.ts"]
    end

    callers --> B

_{Reviews (2): Last reviewed commit: "refactor(recovery): keep the ENOENT bran..." | Re-trigger Greptile}