refactor: abort unreadable config saves with a typed StorageError - #587

Summary

• Second slice of the audit's §4.3 error-contract adoption (finding M11), unblocked by refactor: migrate the last two hand-rolled retry loops to withRetry #585's merge: the three Aborting config save because <path> is unreadable. throws in savePluginConfig now produce a typed StorageError instead of a bare Error. With refactor: throw CodexValidationError from rotation-proxy startup guards #586 (merged) and this PR, the three files §4.3 names carry no bare throws — M11 is fully executed.

What Changed

lib/config.ts — one new unreadableConfigSaveError(configPath, errorMessage) helper replaces the three inline throws (env-path branch inside the ESTALE CAS, unified path, legacy path). It returns a StorageError carrying:

• the byte-identical historical message (existing rejects.toThrow("unreadable") assertions and CLI output are unchanged),
• code: "UNREADABLE" (following the existing non-errno precedent of "UNKNOWN" in the storage layer),
• path = the offending config file,
• an actionable hint ("Fix or remove the unreadable config file, then retry the save."),
• the read-classifier's message as cause for debuggability.

The typed throw still propagates immediately through the ESTALE withRetry (its code is not ESTALE → non-retryable), exactly as before.

docs/reference/error-contracts.md — adds the savePluginConfig guarantee to the "Typed Error Classes" section that #586 introduced (branch rebased onto post-#586 main so the section exists here).

test/config-save.test.ts — new test pinning the class, path, code, and exact message through the real savePluginConfig env path, alongside the three existing unreadable tests which pass unchanged.

Validation

• npm run typecheck (also in the pre-commit hook)
• npx eslint lib/config.ts test/config-save.test.ts --max-warnings=0
• npm test -- test/config-save.test.ts — 21/21 (the three pre-existing unreadable-abort tests pass without modification, proving message compatibility)
• Full-suite canary on clean post-merge-storm main completed just before this branch: exactly the 58-name environment baseline, zero new names
• npm run build deferred to CI

Docs and Governance Checklist

• docs/reference/error-contracts.md updated in the same PR as the behavior it documents
• No user-visible message, command, or path changed; StorageError extends CodexError extends Error, so all instanceof Error handling is unaffected

Risk and Rollback

• Risk level: low — error class tightened, message and throw conditions identical; the only observable difference is richer metadata on the error object.
• Rollback plan: revert the two commits.

https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB

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

replaces three inline new Error(...) throws in savePluginConfig with a typed StorageError via a new unreadableConfigSaveError factory, satisfying audit §4.3. the "UNREADABLE" code is not in the ESTALE withRetry's retryableCodes list, so retry behavior is unchanged; message text is byte-identical, preserving existing test assertions.

• lib/config.ts: adds the unreadableConfigSaveError factory returning a StorageError with code, path, hint, and cause; all three unreadable-abort throw sites updated.
• test/config-save.test.ts: new test verifies instanceof StorageError, path, code, and message through the env-path branch with an EBUSY read spy.
• docs/reference/error-contracts.md: one-line contract guarantee added for savePluginConfig's new typed error.

Confidence Score: 4/5

safe to merge; the only observable change is richer metadata on the thrown error object — message text, throw conditions, and retry behavior are all identical to before

the three throw sites are straightforward substitutions, the ESTALE retry loop correctly non-retries the new StorageError (code "UNREADABLE" is absent from retryableCodes: ["ESTALE"]), and the new test covers the core contract. the savePluginConfig JSDoc block is left orphaned above the helper, which is a cosmetic gap but doesn't affect runtime behavior.

lib/config.ts — the original savePluginConfig JSDoc block is now detached from the function; worth fixing before merging to keep IDE hover docs accurate

Important Files Changed

Sequence Diagram

sequenceDiagram
    participant C as Caller
    participant S as savePluginConfig
    participant R as readConfigRecordForSave
    participant F as unreadableConfigSaveError
    participant W as withRetry (ESTALE)

    C->>S: savePluginConfig(patch)
    S->>W: withRetry([ESTALE], op)
    W->>R: readConfigRecordForSave(path)
    alt "status === "unreadable""
        R-->>W: "{ status: "unreadable", errorMessage }"
        W->>F: unreadableConfigSaveError(path, msg)
        F-->>W: "StorageError(code="UNREADABLE")"
        note over W: "UNREADABLE" not in ["ESTALE"] → rethrow immediately
        W-->>S: throws StorageError
        S-->>C: throws StorageError
    else "status === "ok" or "missing""
        R-->>W: config record
        W->>W: merge + write
        W-->>S: void
        S-->>C: void
    end

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

---

### Issue 1 of 1
lib/config.ts:850-881
**JSDoc block orphaned from `savePluginConfig`**

inserting `unreadableConfigSaveError` between the existing JSDoc and the `savePluginConfig` declaration means TypeScript/IDEs now attach the `@param configPatch` / `@returns void` block to the helper (as the immediately-preceding comment) and `savePluginConfig` itself has no JSDoc at all. the fix is to move the `unreadableConfigSaveError` function (with its own JSDoc) above the savePluginConfig documentation block, or move the savePluginConfig JSDoc block to sit directly above its `export async function` declaration.

_{Reviews (1): Last reviewed commit: "docs: record the savePluginConfig typed-..." | Re-trigger Greptile}