@cstart/coldstart 2.0.0

package/dist/keeper-state.js

@@ -0,0 +1,89 @@
+/**
+ * Keeper observability — two small files beside the cache segments:
+ *
+ *   keeper-state.json  — last reconcile / patch / rebuild / save, one record,
+ *                        overwritten in place (atomic). `coldstart status`
+ *                        renders it so "is my index fresh, and why?" is
+ *                        answerable without reading the daemon log.
+ *   repair.jsonl       — append-only log of FAILURES (patch failed, rebuild
+ *                        failed, invariant violation). Persistent across
+ *                        keeper restarts — a keeper that silently rebuilds
+ *                        every hour shows up here even if each individual
+ *                        log rotated away.
+ *
+ * Neither filename matches saveCachedIndex's cleanup sweep (index.json,
+ * graph.json, files-*, *.gz, *.gz.tmp, fingerprints.json) — same survival
+ * reasoning as kb-notes.json.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { writeFile, rename, mkdir, appendFile, rm } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { getCacheDir } from './cache/disk-cache.js';
+const STATE_FILE = 'keeper-state.json';
+const REPAIR_FILE = 'repair.jsonl';
+const REPAIR_MAX_BYTES = 256 * 1024;
+export function keeperStatePath(rootDir, baseCacheDir) {
+    return join(getCacheDir(rootDir, baseCacheDir), STATE_FILE);
+}
+export function repairLogPath(rootDir, baseCacheDir) {
+    return join(getCacheDir(rootDir, baseCacheDir), REPAIR_FILE);
+}
+/** Read-merge-write. Best-effort and atomic — observability must never take
+ *  the keeper down, so all failures are swallowed. */
+export async function updateKeeperState(rootDir, patch, baseCacheDir) {
+    try {
+        const path = keeperStatePath(rootDir, baseCacheDir);
+        const current = readKeeperState(rootDir, baseCacheDir) ?? { pid: process.pid, startedAt: Date.now() };
+        const next = { ...current, ...patch, pid: process.pid };
+        await mkdir(dirname(path), { recursive: true });
+        const tmp = path + '.tmp';
+        await writeFile(tmp, JSON.stringify(next));
+        await rename(tmp, path);
+    }
+    catch { /* best-effort */ }
+}
+export function readKeeperState(rootDir, baseCacheDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(keeperStatePath(rootDir, baseCacheDir), 'utf8'));
+        return typeof parsed?.pid === 'number' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Append one failure record. Size-capped: past the cap the file starts over
+ *  (the tail is what matters; a growing failure log IS the signal). */
+export async function appendRepairLog(rootDir, event, detail, baseCacheDir) {
+    try {
+        const path = repairLogPath(rootDir, baseCacheDir);
+        await mkdir(dirname(path), { recursive: true });
+        try {
+            if (statSync(path).size > REPAIR_MAX_BYTES)
+                await rm(path, { force: true });
+        }
+        catch { /* absent — fine */ }
+        const record = { at: Date.now(), event, detail: detail.slice(0, 500) };
+        await appendFile(path, JSON.stringify(record) + '\n');
+    }
+    catch { /* best-effort */ }
+}
+/** Last N repair events (tolerant reader — skips corrupt lines). */
+export function readRepairTail(rootDir, n = 3, baseCacheDir) {
+    try {
+        const lines = readFileSync(repairLogPath(rootDir, baseCacheDir), 'utf8').trim().split('\n');
+        const out = [];
+        for (const line of lines.slice(-n * 2)) {
+            try {
+                const parsed = JSON.parse(line);
+                if (typeof parsed?.at === 'number' && typeof parsed?.event === 'string')
+                    out.push(parsed);
+            }
+            catch { /* skip corrupt line */ }
+        }
+        return out.slice(-n);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=keeper-state.js.map

package/dist/keeper-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keeper-state.js","sourceRoot":"","sources":["../src/keeper-state.ts"],"names":[],"mappings":"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"}

package/dist/keeper.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Ensure a background keeper is running for `finalRoot`. Spawns one (detached)
+ * if none is alive, or replaces a keeper left by an older coldstart version
+ * (cache-format compatibility). Best-effort — any failure is swallowed so the
+ * reader still works off the (possibly staler) cache.
+ */
+export declare function ensureKeeper(finalRoot: string): Promise<void>;
+export type CacheWait = 'ready' | 'no-keeper' | 'timeout';
+/**
+ * Wait for the keeper's cache to exist. 'no-keeper' = no live keeper after a
+ * spawn grace period (caller may build in-process as a last resort);
+ * 'timeout' = a keeper is alive but still building (caller should tell the
+ * user to retry rather than start a competing build).
+ */
+export declare function waitForKeeperCache(rootDir: string, cacheDir: string | undefined, timeoutMs?: number, note?: (msg: string) => void): Promise<CacheWait>;
+/**
+ * Wait for the cache to be REWRITTEN (meta.json mtime to advance past its
+ * value at call time). Used when a reader sees the cache behind the current
+ * git HEAD: the freshly ensured keeper reconciles and re-saves within a few
+ * seconds. false = no rewrite within the window (serve the stale index).
+ */
+export declare function waitForCacheAdvance(rootDir: string, cacheDir: string | undefined, timeoutMs?: number): Promise<boolean>;
+//# sourceMappingURL=keeper.d.ts.map

package/dist/keeper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keeper.d.ts","sourceRoot":"","sources":["../src/keeper.ts"],"names":[],"mappings":"AAuBA;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBnE;AAaD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,CAAC;AAE1D;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,SAAU,EACnB,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAC3B,OAAO,CAAC,SAAS,CAAC,CAiBpB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,SAAS,GACjB,OAAO,CAAC,OAAO,CAAC,CAUlB"}

package/dist/keeper.js

@@ -0,0 +1,105 @@
+/**
+ * Keeper spawn helper — shared by the MCP reader (index.ts) and the CLI readers
+ * (cli.ts). Lives in its own module so cli.ts can use it without importing
+ * index.ts (whose top-level `main()` would run on import).
+ *
+ * The keeper is a detached background process (`--daemon`) that keeps the
+ * on-disk cache fresh. Readers call ensureKeeper() so a single keeper is alive
+ * per root; it short-circuits cheaply (one lock read + a liveness check) when
+ * one already runs.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { readLock, isDaemonAlive, getCurrentVersion, killDaemon, deleteLock, tryAcquireSpawnLock, } from './daemon-lock.js';
+import { getCacheDir } from './cache/disk-cache.js';
+/**
+ * Ensure a background keeper is running for `finalRoot`. Spawns one (detached)
+ * if none is alive, or replaces a keeper left by an older coldstart version
+ * (cache-format compatibility). Best-effort — any failure is swallowed so the
+ * reader still works off the (possibly staler) cache.
+ */
+export async function ensureKeeper(finalRoot) {
+    try {
+        const lock = await readLock(finalRoot);
+        const version = getCurrentVersion();
+        if (lock && isDaemonAlive(lock.pid)) {
+            if (!lock.version || lock.version === version)
+                return; // alive & current
+            await killDaemon(lock.pid);
+            await deleteLock(finalRoot).catch(() => { });
+        }
+        const release = await tryAcquireSpawnLock(finalRoot);
+        if (!release)
+            return; // another reader is already spawning it
+        try {
+            const entry = process.argv[1];
+            const child = spawn(process.execPath, [entry, '--root', finalRoot, '--daemon', '--quiet'], { detached: true, stdio: 'ignore' });
+            child.unref();
+        }
+        finally {
+            await release();
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+}
+// ---------------------------------------------------------------------------
+// Readers never build (B4): on a cache miss they wait for the keeper's first
+// save instead of building a second index in-process (the double-build spike).
+// ---------------------------------------------------------------------------
+function metaPath(rootDir, cacheDir) {
+    return join(getCacheDir(rootDir, cacheDir), 'meta.json');
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Wait for the keeper's cache to exist. 'no-keeper' = no live keeper after a
+ * spawn grace period (caller may build in-process as a last resort);
+ * 'timeout' = a keeper is alive but still building (caller should tell the
+ * user to retry rather than start a competing build).
+ */
+export async function waitForKeeperCache(rootDir, cacheDir, timeoutMs = 180_000, note) {
+    const meta = metaPath(rootDir, cacheDir);
+    const start = Date.now();
+    let lastNote = start;
+    while (Date.now() - start < timeoutMs) {
+        if (existsSync(meta))
+            return 'ready';
+        if (Date.now() - start > 3_000) {
+            const lock = await readLock(rootDir);
+            if (!lock || !isDaemonAlive(lock.pid))
+                return 'no-keeper';
+        }
+        if (note && Date.now() - lastNote >= 5_000) {
+            note(`[coldstart] keeper is building the index… (${Math.round((Date.now() - start) / 1000)}s)`);
+            lastNote = Date.now();
+        }
+        await sleep(250);
+    }
+    return existsSync(meta) ? 'ready' : 'timeout';
+}
+/**
+ * Wait for the cache to be REWRITTEN (meta.json mtime to advance past its
+ * value at call time). Used when a reader sees the cache behind the current
+ * git HEAD: the freshly ensured keeper reconciles and re-saves within a few
+ * seconds. false = no rewrite within the window (serve the stale index).
+ */
+export async function waitForCacheAdvance(rootDir, cacheDir, timeoutMs = 12_000) {
+    const meta = metaPath(rootDir, cacheDir);
+    const mtime = () => { try {
+        return statSync(meta).mtimeMs;
+    }
+    catch {
+        return 0;
+    } };
+    const baseline = mtime();
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        if (mtime() > baseline)
+            return true;
+        await sleep(250);
+    }
+    return mtime() > baseline;
+}
+//# sourceMappingURL=keeper.js.map

package/dist/keeper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keeper.js","sourceRoot":"","sources":["../src/keeper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,SAAiB;IAClD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;QACpC,IAAI,IAAI,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACpC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,KAAK,OAAO;gBAAE,OAAO,CAAC,kBAAkB;YACzE,MAAM,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3B,MAAM,UAAU,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC9C,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,SAAS,CAAC,CAAC;QACrD,IAAI,CAAC,OAAO;YAAE,OAAO,CAAC,wCAAwC;QAC9D,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC9B,MAAM,KAAK,GAAG,KAAK,CACjB,OAAO,CAAC,QAAQ,EAChB,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,EACnD,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CACpC,CAAC;YACF,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC;gBAAS,CAAC;YACT,MAAM,OAAO,EAAE,CAAC;QAClB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,iBAAiB;IACnB,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,6EAA6E;AAC7E,+EAA+E;AAC/E,8EAA8E;AAE9E,SAAS,QAAQ,CAAC,OAAe,EAAE,QAA4B;IAC7D,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,WAAW,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAInF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAe,EACf,QAA4B,EAC5B,SAAS,GAAG,OAAO,EACnB,IAA4B;IAE5B,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,SAAS,EAAE,CAAC;QACtC,IAAI,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,OAAO,CAAC;QACrC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,KAAK,EAAE,CAAC;YAC/B,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;YACrC,IAAI,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;gBAAE,OAAO,WAAW,CAAC;QAC5D,CAAC;QACD,IAAI,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,IAAI,KAAK,EAAE,CAAC;YAC3C,IAAI,CAAC,8CAA8C,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;YAChG,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACxB,CAAC;QACD,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAe,EACf,QAA4B,EAC5B,SAAS,GAAG,MAAM;IAElB,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,GAAW,EAAE,GAAG,IAAI,CAAC;QAAC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,CAAC,CAAC;IAAC,CAAC,CAAC,CAAC,CAAC;IAC3F,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAC;IACzB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,SAAS,EAAE,CAAC;QACtC,IAAI,KAAK,EAAE,GAAG,QAAQ;YAAE,OAAO,IAAI,CAAC;QACpC,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,EAAE,GAAG,QAAQ,CAAC;AAC5B,CAAC"}

package/dist/migrate.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Auto-migrate legacy npx-based .mcp.json entries to direct node invocation.
+ */
+/**
+ * Auto-migrate legacy npx-based .mcp.json entries to direct node invocation.
+ * Called at server startup; failures are non-fatal (logged but don't block).
+ */
+export declare function migrateLegacyMcpConfig(rootDir: string): Promise<void>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA;;GAEG;AA8DH;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmD3E"}

package/dist/migrate.js

@@ -0,0 +1,102 @@
+/**
+ * Auto-migrate legacy npx-based .mcp.json entries to direct node invocation.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+/**
+ * Detect if an MCP entry is the legacy npx-based coldstart form.
+ */
+function isLegacyNpxEntry(entry) {
+    if (!entry || typeof entry !== 'object')
+        return false;
+    const e = entry;
+    return (e.command === 'npx' &&
+        Array.isArray(e.args) &&
+        e.args.some(a => a === 'coldstart-mcp' || a === 'coldstart'));
+}
+/**
+ * Resolve the `dist/index.js` of the running coldstart install.
+ *
+ * Derived from this module's own location (`<install>/dist/migrate.js`), so it
+ * points at the live install regardless of how it was launched. There is no
+ * version-pinned copy to consult — `npx` is no longer a supported flow, so the
+ * running path is always stable.
+ */
+async function findStableInstall() {
+    try {
+        const entryPath = path.join(path.dirname(path.dirname(__filename)), 'dist', 'index.js');
+        return fs.existsSync(entryPath) ? entryPath : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build the new MCP entry for fast (direct node) invocation.
+ */
+async function buildFastEntry(rootDir) {
+    const entryPath = await findStableInstall();
+    if (!entryPath)
+        return null;
+    return {
+        command: 'node',
+        args: [entryPath, '--root', rootDir],
+    };
+}
+/**
+ * Auto-migrate legacy npx-based .mcp.json entries to direct node invocation.
+ * Called at server startup; failures are non-fatal (logged but don't block).
+ */
+export async function migrateLegacyMcpConfig(rootDir) {
+    // Opt-out via environment variable
+    if (process.env.COLDSTART_NO_AUTO_MIGRATE === '1')
+        return;
+    const candidates = [
+        path.join(rootDir, '.mcp.json'),
+        path.join(rootDir, '.cursor', 'mcp.json'),
+    ];
+    for (const file of candidates) {
+        if (!fs.existsSync(file))
+            continue;
+        let config;
+        try {
+            config = JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const entry = config.mcpServers?.coldstart;
+        if (!entry)
+            continue;
+        // Only migrate if it's the exact legacy pattern we generated
+        if (!isLegacyNpxEntry(entry))
+            continue;
+        // Resolve a stable install
+        const newEntry = await buildFastEntry(rootDir);
+        if (!newEntry) {
+            process.stderr.write('[coldstart] Detected legacy npx-based .mcp.json but could not resolve the running install path. Reinstall (`npm i -g @cstart/coldstart`) and run `coldstart init` to migrate.\n');
+            continue;
+        }
+        // Create backup with timestamp
+        const backup = `${file}.bak-${Date.now()}`;
+        try {
+            fs.copyFileSync(file, backup);
+        }
+        catch (err) {
+            process.stderr.write(`[coldstart] Failed to create backup at ${backup}: ${err}\n`);
+            continue;
+        }
+        // Update the config
+        config.mcpServers.coldstart = newEntry;
+        try {
+            fs.writeFileSync(file, JSON.stringify(config, null, 2) + '\n');
+            process.stderr.write(`[coldstart] Migrated ${path.basename(file)} from npx to direct node (backup at ${path.basename(backup)}). Faster startup next session.\n`);
+        }
+        catch (err) {
+            process.stderr.write(`[coldstart] Failed to write migrated config: ${err}\n`);
+        }
+    }
+}
+//# sourceMappingURL=migrate.js.map

package/dist/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"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"}

package/dist/restart.d.ts

@@ -0,0 +1,15 @@
+/**
+ * coldstart restart [--all] [--root <dir>] — Kill the background keeper and
+ * clear its lock.
+ *
+ * Without flags: the keeper for the current working directory.
+ * With --root: the keeper for that directory (a silently-ignored --root
+ * killed the wrong keeper once — never accept-and-ignore a flag).
+ * With --all: every keeper the user has running.
+ *
+ * The keeper respawns lazily on the next `coldstart find` (or MCP call), so
+ * "restart" = stop now, fresh keeper on next use. Use this to clear a wedged
+ * keeper or a stale lockfile.
+ */
+export declare function runRestart(): Promise<void>;
+//# sourceMappingURL=restart.d.ts.map

package/dist/restart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart.d.ts","sourceRoot":"","sources":["../src/restart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAgChD"}

package/dist/restart.js

@@ -0,0 +1,48 @@
+/**
+ * coldstart restart [--all] [--root <dir>] — Kill the background keeper and
+ * clear its lock.
+ *
+ * Without flags: the keeper for the current working directory.
+ * With --root: the keeper for that directory (a silently-ignored --root
+ * killed the wrong keeper once — never accept-and-ignore a flag).
+ * With --all: every keeper the user has running.
+ *
+ * The keeper respawns lazily on the next `coldstart find` (or MCP call), so
+ * "restart" = stop now, fresh keeper on next use. Use this to clear a wedged
+ * keeper or a stale lockfile.
+ */
+import { resolve } from 'node:path';
+import { readLock, listDaemonLocks, deleteLock, killDaemon } from './daemon-lock.js';
+export async function runRestart() {
+    const all = process.argv.includes('--all');
+    let killed = 0;
+    if (all) {
+        // Kill every keeper.
+        const listings = await listDaemonLocks();
+        for (const listing of listings) {
+            await killDaemon(listing.lock.pid);
+            await deleteLock(listing.lock.rootDir || '.').catch(() => { });
+            process.stdout.write(`[coldstart] Killed keeper ${listing.basename} (PID ${listing.lock.pid})\n`);
+            killed++;
+        }
+    }
+    else {
+        // Kill the keeper for --root <dir>, or cwd when absent.
+        const rootFlag = process.argv.indexOf('--root');
+        const target = rootFlag !== -1 ? process.argv[rootFlag + 1] : undefined;
+        const finalRoot = resolve(target ?? process.cwd());
+        const lock = await readLock(finalRoot);
+        if (!lock) {
+            process.stdout.write(`[coldstart] No keeper found for ${finalRoot}\n`);
+            return;
+        }
+        await killDaemon(lock.pid);
+        await deleteLock(finalRoot).catch(() => { });
+        process.stdout.write(`[coldstart] Killed keeper (PID ${lock.pid}) — respawns on next \`coldstart find\`\n`);
+        killed++;
+    }
+    if (killed === 0) {
+        process.stdout.write(`[coldstart] No keepers to restart\n`);
+    }
+}
+//# sourceMappingURL=restart.js.map

package/dist/restart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart.js","sourceRoot":"","sources":["../src/restart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAErF,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,IAAI,GAAG,EAAE,CAAC;QACR,qBAAqB;QACrB,MAAM,QAAQ,GAAG,MAAM,eAAe,EAAE,CAAC;QACzC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,MAAM,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACnC,MAAM,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAC9D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,OAAO,CAAC,QAAQ,SAAS,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;YAClG,MAAM,EAAE,CAAC;QACX,CAAC;IACH,CAAC;SAAM,CAAC;QACN,wDAAwD;QACxD,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACxE,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACnD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,SAAS,IAAI,CAAC,CAAC;YACvE,OAAO;QACT,CAAC;QACD,MAAM,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,UAAU,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC5C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,IAAI,CAAC,GAAG,2CAA2C,CAAC,CAAC;QAC5G,MAAM,EAAE,CAAC;IACX,CAAC;IAED,IAAI,MAAM,KAAK,CAAC,EAAE,CAAC;QACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC"}

package/dist/server/find.d.ts

@@ -0,0 +1,39 @@
+import type { CodebaseIndex } from '../types.js';
+import type { FoldedNote } from '../kb/types.js';
+/** Separator-fold for the NAME/PATH/SYMBOL channels: query vocabulary and code
+ * naming disagree on separators for the same compound — `spatial-view` vs
+ * `spatial_view` vs `SpatialView` vs `spatialview` are one concept. Folding
+ * `-`/`_` out of BOTH sides makes those channels separator-invariant (a strict
+ * superset of the literal matches). Body/grep matching stays literal — text is
+ * matched as written. (Root-caused from the q16 three-arm trace: the gold
+ * migration ranked tail-[1/3] purely because the agent hyphenated its query.) */
+export declare function foldSep(s: string): string;
+/** Clean a raw query into distinct, matchable terms (identifiers ≥3 chars). */
+export declare function parseTerms(raw: string): string[];
+/**
+ * Build term-coverage per indexed file. External searchers run per-term; the
+ * Node fallback reads each indexed file once and tests all terms together.
+ * Only files present in the index count (restricts to indexed code files).
+ */
+export declare function collectCoverage(index: CodebaseIndex, root: string, terms: string[]): Promise<Map<string, Set<string>>>;
+export declare function buildNoteMap(root: string, lterms: string[]): Map<string, {
+    note: FoldedNote;
+    role?: string;
+}>;
+/** Empty line → the caller drops it: a Summary: that only restates the path is
+ *  noise, not evidence (a file note's title IS the path).
+ *  `summary` — the gist is summary-grade prose (a single's body sentence or a
+ *  query-matched facet detail): a past agent's verified description of THIS
+ *  file. find then drops the convergence preview for the file — the summary
+ *  IS the preview (user ruling 2026-07-06: file summaries live in find; flows
+ *  live in kb search). Stale notes still surface — most of a note survives
+ *  an edit — with [evidence changed] marking what to re-verify. */
+export declare function noteLine(root: string, rel: string, entry: {
+    note: FoldedNote;
+    role?: string;
+}, lterms?: string[]): {
+    line: string;
+    summary: boolean;
+};
+export declare function buildRichPage(index: CodebaseIndex, root: string, rawQuery: string, asData?: boolean, via?: boolean): Promise<string>;
+//# sourceMappingURL=find.d.ts.map

package/dist/server/find.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../src/server/find.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,aAAa,EAA2B,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAmJjD;;;;;;iFAMiF;AACjF,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAWhD;AA4DD;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CA6D5H;AA+ID,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0B7G;AAWD;;;;;;;mEAOmE;AACnE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,GAAE,MAAM,EAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAyCzJ;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,UAAQ,EAAE,GAAG,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CA4XtI"}