fix(context): refresh get_docs when packages change on disk

[gsdali]

context add writes to ~/.context/packages from a separate process, but a running serve reads that directory once at startup. A long-lived stdio server therefore keeps serving the package list it saw when it launched, so get_docs reports a package as missing when it is already installed, and the only way out is to reconnect the client.

I hit this adding a locally-built docs package while a Claude Code session was open: context query saw it instantly, get_docs could not see it at all.

The mechanism already existed

refreshGetDocsTool rebuilds the tool's library enum and calls sendToolListChanged, the MCP notification that tells a client to re-fetch the tool list. It had exactly one caller, the download_package handler, so a package arriving any other way was invisible.

This adds a second trigger, not a second mechanism.

The change

• watch.ts, a small debounced directory watcher. Debounced because one install is several filesystem events (a temp file, then a rename into place), which would otherwise rebuild the schema three or four times for one logical change. The watcher is unref'd so it never holds the process open by itself, and a callback that throws cannot tear it down.
• serve watches the data directory, reloads the store, refreshes the tool. Skipped when --libs is set, since that flag pins the session to a fixed library set on purpose and picking up new packages would defeat it.
• refreshGetDocsTool is now public, because the trigger lives outside the class. That is the only public surface change; happy to bump the changeset to minor if you would rather treat it as one.
• loadPackages now syncs rather than only adding. It is called repeatedly now, so a package removed from disk has to leave the store too, which the add-only version could not express.

HTTP needed no change. It builds a fresh ContextServer per session over the same store, so a session started after an install already sees it. Only the long-lived stdio server needed the live notification.

Tests

Five, against the watcher directly: a single change fires once, a burst collapses to one call, stopping prevents further calls, a throwing callback does not kill the watcher, and a missing directory is a no-op.

Verified discriminating rather than merely passing: removing the debounce fails three of the five.

The watcher went into its own module partly so it could be tested at all. cli.ts builds a commander program at module scope, so importing it from a test would run the CLI.

About the local test run

pnpm lint and pnpm build are clean. pnpm test reports 40 failures in my environment, identical before and after this change (I ran the baseline on a stash to be sure). They are all better-sqlite3@11.10.0 failing to build against Node v26, so every sqlite-backed test errors on missing bindings:

Error: Could not locate the bindings file. Tried:
 → .../better-sqlite3/build/Release/better_sqlite3.node

My five new tests pass, taking the suite from 181 to 186 passing. I could not verify the sqlite-backed suites locally, so those are worth a look on your CI rather than taking my word for it.

Housekeeping

Followed the CLAUDE.md conventions: searched open and recently closed PRs and /.plans/ first (nothing related), and added a changeset. No plan file to delete, since there was none to claim.

[changeset-bot]

🦋 Changeset detected

Latest commit: f093bce

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@neuledge/context	Patch
@neuledge/registry	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[moshest]

Thanks for this — the mechanism is right and the debounce, the --libs skip, and the unref() are all well judged. Reviewed it in depth and I can't merge it yet. Three blocking issues, the first serious.

1. A package that's merely unreadable gets evicted as if deleted.

loadPackages adds to onDisk only when readPackageInfo succeeds, then removes anything not in that set. So "unparseable right now" and "deleted" collapse into the same outcome.

That would be a narrow race, except buildPackage does this to the same directory:

if (existsSync(outputPath)) unlinkSync(outputPath);  // removes the installed package
const db = openDatabase(outputPath);                 // rebuilds in place

So context add on an already-installed package makes it unreadable for the whole rebuild — minutes for a crawled site. Reproduced against a live server: the get_docs enum went ["demo-lib@1.0.0"] → empty → back. A running agent is told mid-conversation that nothing is installed. Before this PR it kept serving its startup snapshot, so this is a regression.

Worse, a half-built DB passes validatePackageSchema (the tables exist before any rows are inserted), so the package can also come back with sectionCount: 0 — a wrong answer rather than a stale one.

Fix: evict only on real absence.

for (const pkg of store.list()) {
  if (onDisk.has(packageKey(pkg))) continue;
  if (existsSync(pkg.path)) continue;  // unreadable != gone
  store.remove(packageKey(pkg));
}

2. In-flight downloads get advertised. Both download paths write .downloading-${Date.now()}-*.db, which ends in .db and now loads on the event that creates it. The store then points at a path about to be renamed, or unlinked if the download fails. One-line fix:

if (!file.endsWith(".db") || file.startsWith(".")) continue;

3. serve never calls ensureDataDir() — the only command that doesn't — so on a fresh machine watchDirectory takes its no-op path and this does nothing. That's the first-run flow the PR is for. Confirmed: fresh HOME gets no list_changed and the enum never populates. Add ensureDataDir(); before loadPackages(store).

Two more worth doing: watch() at watch.ts:22 is unguarded and throws synchronously on ENOSPC (inotify limit — routine), which would take down a server that worked fine before; and the watcher dies permanently if the data dir is deleted and recreated.

On the tests — I mutation-tested them. Removing the try/catch entirely leaves all 5 green (Vitest absorbs the uncaught timer exception; plain Node exits 1), and DEBOUNCE_MS = 1 also passes everything. The debounce test fires its three writes in one tick, so any nonzero value coalesces them. Spacing the writes across macrotasks would make it real.

Happy to push these myself if you'd rather not — say the word and I'll do it, keeping you as author. Otherwise take your time; nothing here is far off.

---

Generated by Claude Code