fix(store): tighten epoch validation, README no-clobber atomicity, and test mtime determinism

[seabearDEV]

Three targeted fixes addressing review feedback on the v1.10.0 store hardening PR.

Changes

• readEpoch() validation — replaced Number.isFinite with Number.isSafeInteger(x) && x >= 0. Fractional (1.5), negative, or out-of-range values now fall back to 0 instead of breaking the even/odd seqlock invariant.

• ensureReadme() atomicity — replaced the existsSync + atomicWriteFileSync two-step with a single writeFileSync(path, content, { flag: 'wx' }). The O_CREAT | O_EXCL kernel semantics close the TOCTOU window: a concurrently created or user-customized _README.md is never clobbered. EEXIST is silenced; other errors still route to debug().

  // before
  if (fs.existsSync(readmePath)) return;
  atomicWriteFileSync(readmePath, README_CONTENT);
  
  // after
  try {
    fs.writeFileSync(readmePath, README_CONTENT, { flag: 'wx' });
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === 'EEXIST') return;
    debug(`Failed to write ${README_FILE} in ${dir}: ${String(err)}`);
  }

• Test mtime determinism — replaced the busy-wait spin loop in the sidecar cache test with fs.utimesSync(path, mtime+1000, mtime+1000). The +1000 ms step is sufficient for filesystems with 1-second mtime granularity, eliminating CPU waste and flakiness.

[Copilot]

Pull request overview

Hardens the v1.10.0 file-per-entry directory store against concurrent access hazards (torn reads + first-run migration races), while improving sidecar read performance and adding an in-directory warning against hand-editing.

Changes:

• Add a seqlock-style _epoch.json commit epoch: save() marks odd/even epochs under the directory lock; load() retries scans when it detects overlap.
• Serialize migration with the store lock and seed new store artifacts (_epoch.json, _README.md) during tmp-dir creation before the atomic rename.
• Add mtime-based caching for _aliases.json / _confirm.json and return defensive copies from load(); document the changes in CHANGELOG.md.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
src/utils/directoryStore.ts	Implements _epoch.json seqlock, locked migration wrapper, sidecar mtime caching, and _README.md creation.
src/store.ts	Ensures ~/.codexcli/ exists before running directory migration so the lock file can be created.
src/tests/directoryStore.test.ts	Adds coverage for epoch behavior, locked migration idempotency, sidecar mtime caching, and README seeding/preservation.
CHANGELOG.md	Documents the store hardening, README addition, and sidecar mtime caching under [Unreleased].

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

ensureReadme() uses existsSync() followed by atomicWriteFileSync() (tmp + rename). That rename will overwrite an _README.md that appears between the check and the rename (e.g., a user-customized file created concurrently), which contradicts the “never overwritten” guarantee. Consider creating the file with an atomic no-clobber operation (e.g., writeFileSync with flag 'wx', or openSync O_CREAT|O_EXCL) and only falling back to overwrite-free behavior, even if that means the README write itself is non-atomic.

Suggested change

	* We check with existsSync rather than overwriting unconditionally so a
	* user who customized the wording (or replaced it with a symlink) isn't
	* stomped on every save.
	*/
	function ensureReadme(dir: string): void {
	const readmePath = path.join(dir, README_FILE);
	try {
	if (fs.existsSync(readmePath)) return;
	atomicWriteFileSync(readmePath, README_CONTENT);
	} catch (err) {
	* Use an atomic no-clobber create so a README that appears concurrently
	* (for example, a user-customized file) is preserved rather than replaced.
	*/
	function ensureReadme(dir: string): void {
	const readmePath = path.join(dir, README_FILE);
	try {
	fs.writeFileSync(readmePath, README_CONTENT, { flag: 'wx' });
	} catch (err) {
	if ((err as NodeJS.ErrnoException).code === 'EEXIST') return;

[Copilot]

readEpoch() accepts any finite number, including negatives and non-integers. A hand-edited or corrupted _epoch.json containing e.g. 1.5 will break the intended even/odd invariant and can cause the writer to perpetually advance fractional epochs. Suggest validating with Number.isSafeInteger(parsed.epoch) (and ideally >= 0) and treating anything else as 0.

Suggested change

	if (typeof parsed.epoch === 'number' && Number.isFinite(parsed.epoch)) {
	if (typeof parsed.epoch === 'number'
	&& Number.isSafeInteger(parsed.epoch)
	&& parsed.epoch >= 0) {

[Copilot]

The test uses a busy-wait loop (while Date.now() < target) to force an mtime change. This unnecessarily burns CPU and can still be flaky on systems with coarse mtime resolution or under heavy load. Prefer a deterministic approach like fs.utimesSync() to bump the sidecar’s mtime, or introduce a small real sleep via Atomics.wait/setTimeout in async test code.

Suggested change

	// Spin briefly so the mtime actually advances on coarse-grained filesystems.
	const target = Date.now() + 20;
	while (Date.now() < target) { /* spin */ }
	fs.writeFileSync(
	path.join(dir, '_aliases.json'),
	JSON.stringify({ y: 'a' }, null, 2)
	);
	const aliasesPath = path.join(dir, '_aliases.json');
	const previousStat = fs.statSync(aliasesPath);
	fs.writeFileSync(
	aliasesPath,
	JSON.stringify({ y: 'a' }, null, 2)
	);
	const newerMtime = new Date(previousStat.mtimeMs + 1000);
	fs.utimesSync(aliasesPath, newerMtime, newerMtime);

[seabearDEV]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Applied all three suggestions in commit 0d10506:

1. readEpoch() — replaced Number.isFinite with Number.isSafeInteger(x) && x >= 0, rejecting negatives and non-integers so the even/odd invariant can't be broken by a hand-edited or corrupted epoch file.
2. ensureReadme() — replaced the existsSync + atomicWriteFileSync pair with a single writeFileSync(path, content, { flag: 'wx' }) call. The O_CREAT|O_EXCL semantics make the create truly no-clobber even under concurrent access; EEXIST is caught and silenced, other errors are still logged via debug.
3. Test mtime advance — replaced the busy-wait spin loop with fs.statSync + fs.writeFileSync + fs.utimesSync(path, mtime+1000, mtime+1000). Added a comment explaining the +1000 ms value — it ensures the bump is visible even on filesystems with 1-second mtime granularity.