refactor(lib): break import cycles and enforce no-cycle in lint - #541

Summary

Breaks all 23 import cycles in lib/ and enforces zero-cycles with lint — audit roadmap §4.1.6 (docs/audits/AUDIT_2026-06-10.md, PR #522). The audit's premise ("no cycles exist today") was wrong — madge reported 23 chains on main — so this PR first makes it true, then locks it. Zero behavior change; the storage facade surface is byte-for-byte unchanged (every moved name re-exported).

Stacked on #530 (storage public-types) — its public-types.ts is the foundation. Merge that first.

Cycles broken, by technique

1. Import retargets (19 cycles) — all 22 from "../storage.js" back-imports inside lib/storage/* now point at the layer below (./public-types.js, ./backup-metadata.js, sibling modules), with import type on type-only edges.
2. Verbatim type moves — FlaggedAccount*V1, BackupMetadata/RestoreAssessment/RestoreReason out of the facade; Workspace out of accounts.ts (it was the public-types → accounts back-edge); ModelFamily/MODEL_FAMILIES from prompts/codex.ts to the leaf request/helpers/model-map.ts. Originals re-export, so no importer changes.
3. Value move — saveAccountsWithRetry/isRetryableStorageWriteError to new lib/storage/save-retry.ts, fixing the accounts → codex-manager layering violation (forecast-report-shared re-exports).

Enforcement

• import-x/no-cycle: ["error", { maxDepth: Infinity, ignoreExternal: true }] scoped to index.ts + lib/**/*.ts, with the TS resolver. New devDeps: [email protected] + [email protected] (flat-config native; lockfile diff is additions-only — the rollup libc entries the container npm strips were restored byte-identical).
• Non-obvious config note, documented in the eslint config: the rule silently no-ops on .ts files without "import-x/extensions": [".ts"] — import-x's traversal defaults to .js only. Verified the rule actually fires by temporarily reintroducing a cycle (eslint errored), then removing it.
• lib/AGENTS.md conventions now document the types/constants → storage → accounts → runtime → manager/CLI layering.

Validation

• npx madge --circular lib/ index.ts → 0 cycles (was 23)
• Full npm run lint (with the new rule active) + npm run typecheck
• 22 storage/accounts/codex-cli suites (596 tests): failure lists identical to base via stash diff (all known environment-only EACCES)
• Independently re-verified: madge 0, full lint, storage-parser + accounts 177/177

Risk / Rollback

Re-export-preserving moves + a lint rule; revert the single commit. The rule prevents the 23-cycle situation from regrowing.

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

breaks 23 import cycles in lib/ and enforces zero-cycles via import-x/no-cycle. all public-facade surfaces are preserved via re-exports; no runtime behavior changes.

• moves AccountMetadataV3, AccountStorageV3, FlaggedAccount*, Workspace, CooldownReason, RateLimitStateV3 to lib/storage/public-types.ts so sub-modules no longer back-import the storage.ts facade; moves BackupMetadata/RestoreAssessment to backup-metadata.ts; moves ModelFamily/MODEL_FAMILIES to the leaf model-map.ts.
• extracts saveAccountsWithRetry/isRetryableStorageWriteError from codex-manager/forecast-report-shared.ts into the new lib/storage/save-retry.ts, fixing the accounts → codex-manager layering violation; both original export paths re-export from the new location.
• wires up eslint-plugin-import-x + eslint-import-resolver-typescript in flat config, scoped to index.ts and lib/**/*.ts with \"import-x/extensions\": [\".ts\"] to ensure the plugin's ExportMap traversal includes TypeScript files.

Confidence Score: 5/5

safe to merge — pure structural refactor with all original export surfaces preserved via re-exports and no logic changes

every moved type and function is re-exported from its original location; the new no-cycle lint rule was author-verified by reintroducing a cycle; 596 tests pass with identical failure lists; no runtime behavior changed

lib/storage/save-retry.ts — new standalone module with no direct unit test

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph "types/constants (leaf)"
        MM["request/helpers/model-map.ts\nModelFamily, MODEL_FAMILIES"]
        UT["utils.ts\nsleep"]
        TY["types.ts\nAccountIdSource …"]
    end

    subgraph "storage layer"
        PT["storage/public-types.ts\nWorkspace, AccountMetadataV3\nAccountStorageV3, FlaggedAccount*\nCooldownReason, RateLimitStateV3"]
        BM["storage/backup-metadata.ts\nBackupMetadata, RestoreAssessment"]
        SR["storage/save-retry.ts\nsaveAccountsWithRetry\nisRetryableStorageWriteError"]
        MG["storage/migrations.ts\nAccountStorageV1 (legacy)"]
        ST["storage.ts (facade)\nre-exports all above"]
    end

    subgraph "accounts layer"
        AC["accounts.ts\nWorkspace re-export"]
    end

    subgraph "manager/CLI layer"
        FRS["codex-manager/forecast-report-shared.ts\nre-exports save-retry"]
        APW["codex-manager/account-pool-write.ts"]
    end

    MM --> PT
    TY --> PT
    PT --> SR
    UT --> SR
    PT --> MG
    MM --> MG
    BM --> ST
    PT --> ST
    MG --> ST
    SR --> AC
    ST --> AC
    SR --> FRS
    ST --> FRS
    AC --> APW

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
lib/storage/save-retry.ts:1-33
**no direct vitest coverage for the new module**

`save-retry.ts` is now a standalone shared utility but has no test file. the retry cap (`attempt >= 3` → 4 total attempts), the exponential delay formula (`10 * 2 ** attempt` → 10/20/40 ms), and the exact set of retryable codes are all observable contracts. indirect coverage exists via `codex-manager-cli.test.ts` and `issue-474-pin-safety.test.ts`, but those tests go through many layers. a direct unit test would catch a future change to the retry set or cap without having to exercise the full manager stack.

also: `RETRYABLE_STORAGE_WRITE_CODES` is `["EBUSY", "EPERM"]` — on windows, storage-path writes (e.g. under `AppData\`) can fail with `EACCES` when a competing process holds an exclusive lock. that code isn't retried today. this is verbatim from the original location, so not a regression here, but now that the set is a named shared constant it's a natural place to add it.

_{Reviews (2): Last reviewed commit: "refactor(lib): import MODEL_FAMILIES fro..." | Re-trigger Greptile}