fix(hooks): persist session-sync cache to disk — Mac CPU fix E

[namastex888]

Summary

Fix E of the 5-step .19 Mac-CPU root-cause plan. Last big remaining hook-fork DB call.

The per-process Map<executorId, sessionId> in session-sync.ts caches NOTHING across genie hook dispatch bun forks (each fork starts with empty Map). Every cold-start hook fork did 3 DB round-trips (getAgentByName + getExecutor + audit) even when the (executorId, sessionId) pair was already-reconciled by a previous fork.

Fix

• Disk-backed cache at ~/.genie/cache/session-sync.json (overridable via __GENIE_SESSION_SYNC_CACHE_FILE for tests)
• loadDiskCache() runs once per fork before any DB call, replacing the empty Map with previously-persisted (executorId, sessionId) pairs
• persistDiskCache() writes after every cache mutation (atomic via write-temp + rename)
• MAX_CACHE_ENTRIES=1000 with insertion-order trim — bounded growth across weeks of use
• Concurrency: rename races can lose one fork's writes for OTHER executor entries (benign: at most occasional redundant DB syncs from later forks)
• Corrupt cache is tolerated — falls through to DB (handler must never throw)

Effect

After this PR, hook forks have ZERO DB calls in the steady state for already-reconciled sessions. DB is only hit on:

• First capture (executor never reconciled before)
• Session-id rotation (Claude Code resume / compaction)
• Cache miss (new executor)

Validation

• bun test src/hooks/__tests__/session-sync.test.ts — 18/18 pass (14 prior + 4 new):
  • writes cache file after a successful session.reconciled
  • cold-start fork loads cache from disk and skips DB calls
  • disk cache miss falls through to DB and persists result
  • corrupt cache file is tolerated — falls back to DB
• bun x tsc --noEmit clean
• bun x biome check clean

Mac-CPU sprint complete after this merges

• A ✓ fix(db): drop runRetention from getConnection — Mac CPU fix A (hook-dispatch coldstart) #1475 — drop runRetention from getConnection
• filewatch ✓ fix(filewatch): replace fs.watch recursive with chokidar (Mac CPU partial mitigation) #1474 — chokidar replacement
• C ✓ fix(hooks): skip db boot for dispatch — Mac CPU fix C #1476 — GENIE_SKIP_DB_BOOT for hook dispatch
• D open fix(hooks): narrow inject matchers — Mac CPU fix D #1479 — narrow inject matchers
• E — this PR
• B in flight — dog-fooder twin on fix/mac-cpu-needsseed-mtime-marker

Combined effect on Mac CPU

A typical hook fork on a busy Mac dev machine before .19:

1. PG connect → runMigrations (~50ms)
2. needsSeed() loops 92 ~/.claude/teams entries (~10ms) → runSeed (~20ms)
3. runRetention 4 DELETEs against unbounded tables (~30ms)
4. session-sync 3 DB round-trips on every PreToolUse + UserPromptSubmit (~15ms each)
5. PostToolUse, SessionStart, SessionEnd, TeammateIdle, TaskCompleted bun forks for nothing (~30ms each)

After A+C+D+E: hook fork connects to PG only when a handler actually needs DB, AND session-sync skips even THAT for already-reconciled pairs. PostToolUse only fires for SendMessage. Unused events don't fire bun at all.

Ready for the .19 cut + dogfood validation pass + PR #1446 dev→main flip after the remaining release-blockers (#1465–#1471) are fixed.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 476c4072-4e5d-4ed4-bd42-cacd7f0797e2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/mac-cpu-session-sync-cache-file

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces a disk-backed cache for session synchronization to optimize performance by reducing database calls during hook execution. The implementation includes logic for loading, persisting, and bounding the cache size, supported by new unit tests. Review feedback identifies a critical race condition in the cache persistence logic that could result in data loss across concurrent processes and recommends adding structural validation when parsing the cache file to avoid potential runtime exceptions.

[gemini-code-assist]

The current implementation of persistDiskCache suffers from a significant race condition that leads to data loss in multi-agent environments.

Because each genie hook dispatch is a fresh process, it loads the cache once at startup. When persistDiskCache is called, it converts the current process's in-memory Map back to an object and overwrites the entire file. If two different agents (Executors A and B) run hooks simultaneously:

1. Fork A loads {}.
2. Fork B loads {}.
3. Fork A reconciles A and writes {'A': 'sessA'} to disk.
4. Fork B reconciles B and writes {'B': 'sessB'} to disk.
5. Result: Executor A's reconciliation is lost from the disk cache.

To fix this, persistDiskCache should read the file again, merge its in-memory updates with the current disk content, and then write. While a race still exists between the read and the rename, the window for data loss is reduced from the entire process lifetime to a few milliseconds.

[gemini-code-assist]

The loadDiskCache function lacks validation for the parsed JSON structure. If the cache file contains null (valid JSON), Object.entries(parsed) will throw a TypeError, which is caught by the generic catch block but could be avoided with a simple type check.

    const parsed = JSON.parse(readFileSync(cacheFile, 'utf-8'));
    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
      for (const [executorId, sessionId] of Object.entries(parsed)) {
        if (typeof sessionId === 'string' && sessionId.length > 0) {
          syncedSessions.set(executorId, sessionId);
        }
      }
    }