Skip to content

A failed settings save can no longer empty config.json - #3473

Merged
backnotprop merged 4 commits into
mainfrom
fix/config-write-never-truncates
Nov 16, 2026
Merged

backnotprop merged 4 commits into
mainfrom
fix/config-write-never-truncates

Conversation

@backnotprop

@backnotprop backnotprop commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

How settings get lost today

  1. A save runs writeConfigAtomic. It writes a temp file beside config.json, then renames it over config.json.
  2. That fails: the temp file cannot be written (disk full, quota, a folder that is not writable), or the rename fails.
  3. The catch block then wrote straight to the real file with writeFileSync(targetPath, contents). A plain write empties the file first. If that write also stops partway (the disk is still full, an I/O error, the process is killed), config.json is left empty or cut short.
  4. The next save merges its own keys onto the empty file and writes the result. Every other setting the person had is gone, with no warning.

Why the fallback existed

#1364 added the fallback together with the temp-and-rename write, which replaced a plain write. Its comment says: "Same-directory rename should not fail, but a write that lands is better than a settings change that is lost to an exotic filesystem." No test pinned the fallback. These are the cases it actually served:

  • Symlinked config.json (dotfiles): not a fallback case. Before the fallback runs, the link is resolved with realpathSync and the temp file goes beside the target, so the rename never replaces the link.
  • Rename across devices: cannot happen, because the temp file is always in the target's own folder.
  • Windows, with another program holding the file (antivirus, a sync client, an indexer): the rename fails with EPERM / EACCES / EBUSY until that program lets go.
  • A folder that is not writable, holding a file that is: the temp file cannot be created, so only a write in place could land.
  • Filesystems that refuse a rename over an existing file (some network or FUSE mounts).

The fix, per case

  • The real file is never written in place. When the temp-and-rename write fails, writeConfigAtomic deletes the temp file and throws. saveConfig and saveCookieHost already catch that: they print the existing failed to write config.json warning and report the save as failed (false / failed). The old bytes stay. state.json uses the same writer, so it gets the same protection.
  • fsync before the rename, and stop if it fails. The temp file is fsynced, so a crash right after the rename cannot leave a renamed but empty file. On a network home folder, or with a quota, a full disk can show up only at fsync. Any fsync error (ENOSPC, EDQUOT, EIO, ...) therefore stops the write before the rename, and config.json keeps its bytes. The only errors ignored are EINVAL, ENOTSUP and EOPNOTSUPP, which mean "this filesystem has no fsync".
  • Symlink: works as before. The temp file still goes beside the link's target. A new test covers this with the link's own folder not writable.
  • Windows lock: on EPERM / EACCES / EBUSY, the rename is retried with backoff for about 2 s in total. Before each wait the config lock's mtime is refreshed, so another writer never takes the lock over as stale (its stale window is 1.5 s). If the file is still held after that, the save fails as above and the old file is untouched. Other errors are not retried.
  • A folder that is not writable, holding a file that is: the save now fails with a warning instead of writing in place. A folder where no file can be created also has no room for a .bak copy beside config.json, and a write in place there risks exactly the empty file this PR removes. In that setup the lock file and state.json already cannot be written either, and the lock warning already shows.
  • Exotic filesystems: same as above. The save fails and the file is kept.
  • An empty config.json (zero bytes or whitespace only) still reads as defaults, and a save writes over it: it holds nothing to lose. Plannotator can no longer produce such a file itself. A file whose content cannot be parsed is still refused, as before.

Tests

packages/shared/config.test.ts:

  • Empty file: with a zero-byte and a whitespace-only config.json, loadConfig gives {}, the save succeeds, and nothing is warned.
  • Failed rename: the failure is injected through a new test-only seam, __setConfigWriteForTest({ rename, fsync, sleep }), built like the existing lock seams. For ENOSPC and EPERM, the save returns false, config.json is byte for byte the same, and no .tmp file is left. ENOSPC is tried once with no wait. EPERM is retried with growing waits that add up to 1.8–2.5 s, and the lock is held during every wait.
  • Retry that lands: EBUSY six times and then success, so the save lands with no warning.
  • Failed fsync: for ENOSPC, EDQUOT and EIO, the rename never runs, the bytes are intact and no temp file is left. For EINVAL and ENOTSUP, the save lands.
  • Folder not writable: a data folder at 0555 with a writable config.json. The save fails and the file keeps its bytes. The old code wrote the file in place here.
  • Symlink in a folder that is not writable: a symlinked config.json in a 0555 folder, pointing into a writable folder. The save goes through the link, and the link survives.

apps/pi-extension/vendored-config-write.test.ts: in the vendored copy, a failed rename and a failed fsync both keep config.json's bytes, and an empty config.json is saved over.

Results: config.test.ts 160 pass, vendored-config-write.test.ts 4 pass, and these neighbouring files run one at a time all pass: config.auto-update, data-dir, inbox-reminder-text, shared-handlers, both update-advert files and update-lifecycle.model. tsc --noEmit is clean for packages/shared and apps/pi-extension. One sentence is added to docs/agent-guides/environment.md.

e2e: none

Not verified

  • No run against a real full disk, quota or I/O error. All failures were injected through the seam or through folder permissions.
  • No Windows run. The lock retry is tested with injected EBUSY / EPERM, not a really locked file.
  • No run on a filesystem that refuses a rename over an existing file.

#3458 (which this PR was built on) is merged, and origin/main is merged into this branch, so the diff shows only this change.

writeConfigAtomic fell back to a plain writeFileSync on the real file when
the temp-file-and-rename path failed. A plain write truncates first, so one
that stopped partway left config.json empty, and readConfigForSave then read
an empty file as {} and the next save wrote only its own keys.

The fallback is gone: a rename Windows reports as locked is retried for a
moment, anything else throws and the caller reports the save as failed with
the old bytes intact. The temp file is fsynced before the rename. An empty
config.json is now refused by every save like corrupt JSON; reads still
give defaults.
…d rename for 2 s

An fsync error other than "no fsync here" (EINVAL, ENOTSUP) now stops the
write before the rename: on a network home or under a quota the full-disk
error can show up only at fsync, and the rename would put a short file in
place of config.json. An empty config.json holds nothing to lose and is
saved over again. A rename Windows reports as locked is retried with
backoff for about 2 s, touching the config lock so it never looks stale.
@backnotprop
backnotprop merged commit 381bca8 into main Nov 16, 2026
57 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant