🗃️ SQLite the OrchestKit way

Our M168 session registry runs on the built-in node:sqlite (Node ≥22.5), shared by every CC session at ~/.local/state/orchestkit/sessions.db. These three views are the actual correctness rules from session-registry.ts — and what #2006 adds on top. Toggle things and watch them pass or break. 🧪

  every CC session ─┐   ┌─ register / heartbeat / lock / override
   primary ┐        │   │
  worktree ┤────────▼───▼──────────────────────────────────────────┐
   #2004   ┘   ~/.local/state/orchestkit/sessions.db  (node:sqlite) │
                WAL · lock-free reads · serialized writes           │
                001 sessions·locks·overrides·worktree_links   v1 ───┤
                002 skill_suggestion · skill_invocation   v2  #2006 ◀┘ 📊

open-time choices

The pragma order is load-bearing. node:sqlite has no default busy handler, unlike better-sqlite3 — so the WAL switch under concurrency throws instantly unless a timeout is already armed.

open sequence

write storm

Each session takes the RESERVED lock at BEGIN IMMEDIATE, so contention surfaces there — not mid-write. Losers see SQLITE_BUSY (errcode 5/261) and retry up to 15× with 20–150ms jitter (~1.3s worst case). Sync spin: hooks + DatabaseSync are synchronous.

what happens

Press fire ⚡

this session

skillsuggestedinvoked

A skill_suggestion row at suggest-time, a skill_invocation row when a /-skill runs. Both keyed by (session_id, skill) so the adoption query is a self-join — impossible against today's append-only skill-usage.log.

adoptionRate(window)

taken ÷ suggested = — 

        
🚧 Gate before any code: the issue assumes a skill-suggestions.jsonl writer that doesn't exist on main. smart-suggestions.ts only returns a string (and suggests rules, not skills). Phase 0 must pin the real suggest-side emitter, else these two tables model a ghost. Comment the drift on #2006 first.

      

    

  


  

    #2003 bundle loads ✅ →
    #2008 registry works ✅ →
    #2006 adoption 📊 (you are here) →
    analytics surface