@yurtsever/capsa 0.1.0-alpha.6 → 0.1.0-alpha.7

package/dist/index.js

@@ -10074,7 +10074,10 @@ function loadSqlite() {
 }
 var DB_DIR = ".capsa";
 var DB_FILE = "index.db";
-var SCHEMA_VERSION = 5;
+var SCHEMA_VERSION = 7;
+var META_INDEXED_AT = "indexed_at";
+var META_INDEX_FAILED_AT = "index_failed_at";
+var META_INDEX_ERROR = "index_error";
 var CONTEXT_LOG_DDL = `
       -- Every context delivery. This is the measurement for the MVP gate and
       -- the seed of the organisation tier's audit log. Alone among these
@@ -10088,6 +10091,12 @@ var CONTEXT_LOG_DDL = `
         query        TEXT NOT NULL,
         delivered    TEXT NOT NULL,
         tokens_est   INTEGER NOT NULL,
+        -- The ceiling this call ran under. Without it a row says what was
+        -- spent but not what it was allowed to spend, and two deliveries are
+        -- only comparable when that number matches. NULL on rows written
+        -- before v6: they ran under a budget nobody recorded, and filling in
+        -- today's default would be a guess wearing the costume of data.
+        tokens_budget INTEGER,
         duration_ms  INTEGER NOT NULL
       );
 `;
@@ -10109,24 +10118,44 @@ var Store = class {
   }
   /** True when this index was written by an older schema and must be rebuilt. */
   needsRebuild() {
-    const row = this.db.prepare("SELECT value FROM meta WHERE key = 'schema'").get();
-    return row?.value !== String(SCHEMA_VERSION);
+    return this.getMeta("schema") !== String(SCHEMA_VERSION);
+  }
+  getMeta(key) {
+    const row = this.db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+    return row?.value;
+  }
+  setMeta(key, value) {
+    this.db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES (?, ?)").run(key, value);
+  }
+  deleteMeta(key) {
+    this.db.prepare("DELETE FROM meta WHERE key = ?").run(key);
   }
   /**
     * Drop all indexed content (not the log, not decisions) and mark the schema
-    * current. The virtual tables are dropped and recreated, not emptied:
-    * `CREATE VIRTUAL TABLE IF NOT EXISTS` would keep an old tokenizer alive
-    * through a rebuild — which once left FTS without stemming after v2.
+    * current. Every one of these tables is dropped and recreated, not emptied,
+    * because `CREATE TABLE IF NOT EXISTS` in migrate() is a no-op against a
+    * table that already exists under its old shape. For the virtual tables that
+    * once left FTS without stemming after v2; for `items` it meant a schema
+    * bump could not add a column at all — v7 added `title` and the rebuild it
+    * asked for failed with "table items has no column named title", because
+    * DELETE had emptied the v6 table and left it standing.
+    *
+    * Nothing here is a source of truth: items and chunks are derived from files
+    * on disk and from `decisions`, which is one of the two tables a reset
+    * spares.
     */
   reset() {
     this.db.exec(`
       DROP TABLE IF EXISTS chunks_fts;
       DROP TABLE IF EXISTS chunks_vec;
-      DELETE FROM chunks;
-      DELETE FROM items;
+      DROP TABLE IF EXISTS chunks;
+      DROP TABLE IF EXISTS items;
     `);
     this.migrate();
-    this.db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES ('schema', ?)").run(String(SCHEMA_VERSION));
+    this.setMeta("schema", String(SCHEMA_VERSION));
+    this.deleteMeta(META_INDEXED_AT);
+    this.deleteMeta(META_INDEX_FAILED_AT);
+    this.deleteMeta(META_INDEX_ERROR);
   }
   migrate() {
     this.db.exec(`
@@ -10137,6 +10166,7 @@ var Store = class {
         format       TEXT NOT NULL,
         kind         TEXT NOT NULL,
         name         TEXT NOT NULL,
+        title        TEXT NOT NULL,
         path         TEXT NOT NULL UNIQUE,
         rel_path     TEXT NOT NULL,
         content_hash TEXT NOT NULL,
@@ -10179,27 +10209,40 @@ var Store = class {
       ${CONTEXT_LOG_DDL}
     `);
     this.migrateContextLog();
-    this.db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES ('dimensions', ?)").run(String(this.dimensions));
+    this.setMeta("dimensions", String(this.dimensions));
   }
   /**
    * `context_log` outlives every rebuild, so it is the one table that has to
-   * be migrated in place instead of recreated. v5 replaced `chunk_ids` with
-   * `delivered`: a chunk id is a rowid the next `capsa index` reassigns, so an
-   * older row ended up naming whatever text inherited its ids — the measurement
-   * quietly decayed. Rows written before v5 keep everything that still means
-   * something (when, who asked, what for, at what cost) and carry an empty
-   * delivery, because their ids can no longer be resolved honestly.
+   * be migrated in place instead of recreated — twice now.
+   *
+   * v5 replaced `chunk_ids` with `delivered`: a chunk id is a rowid the next
+   * `capsa index` reassigns, so an older row ended up naming whatever text
+   * inherited its ids — the measurement quietly decayed. Rows written before
+   * v5 keep everything that still means something (when, who asked, what for,
+   * at what cost) and carry an empty delivery, because their ids can no longer
+   * be resolved honestly.
+   *
+   * v6 added `tokens_budget`. A delivery of 1727 tokens against one of 758
+   * reads like a saving until you learn the first ran on a larger ceiling;
+   * that comparison was attempted on this repo's own log and could not be
+   * settled, because the number was never written down. Old rows get NULL
+   * rather than a backfilled default — an unknown budget is a fact about the
+   * measurement, and inventing one would hide exactly the gap this closes.
+   *
+   * Keyed on the newest column, so a v4 database reaches v6 in one pass.
    */
   migrateContextLog() {
     const columns = this.db.prepare("PRAGMA table_info(context_log)").all();
-    if (columns.some((c) => c.name === "delivered"))
+    const names = new Set(columns.map((c) => c.name));
+    if (names.has("tokens_budget"))
       return;
+    const delivered = names.has("delivered") ? "delivered" : "'[]'";
     this.db.exec(`
-      ALTER TABLE context_log RENAME TO context_log_v4;
+      ALTER TABLE context_log RENAME TO context_log_old;
       ${CONTEXT_LOG_DDL}
-      INSERT INTO context_log (id, created_at, source, query, delivered, tokens_est, duration_ms)
-        SELECT id, created_at, source, query, '[]', tokens_est, duration_ms FROM context_log_v4;
-      DROP TABLE context_log_v4;
+      INSERT INTO context_log (id, created_at, source, query, delivered, tokens_est, tokens_budget, duration_ms)
+        SELECT id, created_at, source, query, ${delivered}, tokens_est, NULL, duration_ms FROM context_log_old;
+      DROP TABLE context_log_old;
     `);
   }
   getItem(path) {
@@ -10217,13 +10260,14 @@ var Store = class {
     this.db.prepare("DELETE FROM items WHERE id = ?").run(id);
   }
   upsertItem(row) {
-    this.db.prepare(`INSERT INTO items (id, format, kind, name, path, rel_path, content_hash, status, updated_at, tags)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    this.db.prepare(`INSERT INTO items (id, format, kind, name, title, path, rel_path, content_hash, status, updated_at, tags)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
          ON CONFLICT(id) DO UPDATE SET
            format = excluded.format, kind = excluded.kind, name = excluded.name,
+           title = excluded.title,
            rel_path = excluded.rel_path, content_hash = excluded.content_hash,
            status = excluded.status, updated_at = excluded.updated_at, tags = excluded.tags,
-           indexed_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')`).run(row.id, row.format, row.kind, row.name, row.path, row.rel_path, row.content_hash, row.status, row.updated_at, row.tags);
+           indexed_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')`).run(row.id, row.format, row.kind, row.name, row.title, row.path, row.rel_path, row.content_hash, row.status, row.updated_at, row.tags);
   }
   /**
    * `text` is what the user sees; `searchText` (chunk + provenance header)
@@ -10254,7 +10298,7 @@ var Store = class {
       return [];
     const placeholders = ids.map(() => "?").join(",");
     const rows = this.db.prepare(`SELECT c.id, c.item_id, c.idx, c.heading_path, c.text,
-                i.id AS i_id, i.format, i.kind, i.name, i.path, i.rel_path, i.content_hash, i.status, i.updated_at, i.tags
+                i.id AS i_id, i.format, i.kind, i.name, i.title, i.path, i.rel_path, i.content_hash, i.status, i.updated_at, i.tags
          FROM chunks c JOIN items i ON i.id = c.item_id WHERE c.id IN (${placeholders})`).all(...ids);
     return rows.map((r) => ({
       id: r["id"],
@@ -10267,6 +10311,7 @@ var Store = class {
         format: r["format"],
         kind: r["kind"],
         name: r["name"],
+        title: r["title"],
         path: r["path"],
         rel_path: r["rel_path"],
         content_hash: r["content_hash"],
@@ -10284,7 +10329,7 @@ var Store = class {
     return this.db.prepare("SELECT * FROM items ORDER BY kind, rel_path").all();
   }
   logContext(entry) {
-    this.db.prepare("INSERT INTO context_log (source, query, delivered, tokens_est, duration_ms) VALUES (?, ?, ?, ?, ?)").run(entry.source, entry.query, JSON.stringify(entry.delivered), entry.tokensEst, entry.durationMs);
+    this.db.prepare("INSERT INTO context_log (source, query, delivered, tokens_est, tokens_budget, duration_ms) VALUES (?, ?, ?, ?, ?, ?)").run(entry.source, entry.query, JSON.stringify(entry.delivered), entry.tokensEst, entry.tokensBudget, entry.durationMs);
   }
   /**
    * Returns the stored row, not just its id: `created_at` is SQL's to write,
@@ -10720,76 +10765,116 @@ function openStore(projectRoot, embedder) {
   return new Store(dbPath(projectRoot), embedder.dimensions);
 }
 async function indexProject(projectRoot, embedder, onProgress) {
-  const started = Date.now();
   const store = openStore(projectRoot, embedder);
   try {
-    if (store.needsRebuild()) {
-      onProgress?.({ phase: "rebuild" });
-      store.reset();
-    }
-    onProgress?.({ phase: "scan" });
-    const result = await scan(knowledgeAdapters(), { roots: [projectRoot] });
-    const items = result.items.filter((i) => i.scope === "project" && isInside(projectRoot, i.path));
-    let indexed = 0;
-    let skipped = 0;
-    const seen = /* @__PURE__ */ new Set();
-    for (const item of items) {
-      seen.add(item.path);
-      const hash2 = sha1(item.content);
-      const existing = store.getItem(item.path);
-      if (existing && existing.content_hash === hash2) {
-        skipped++;
-        continue;
-      }
-      if (existing)
-        store.deleteItem(existing.id);
-      await indexItem(store, embedder, item, projectRoot, hash2);
-      indexed++;
-      onProgress?.({ phase: "embed", scanned: items.length, indexed, skipped });
-    }
-    const decisions = await indexDecisions(store, embedder, projectRoot);
-    for (const path of decisions.paths)
-      seen.add(path);
-    indexed += decisions.indexed;
-    skipped += decisions.skipped;
-    let removed = 0;
-    for (const row of store.listItems()) {
-      if (!seen.has(row.path)) {
-        store.deleteItem(row.id);
-        removed++;
-      }
-    }
-    const out = {
-      scanned: items.length + decisions.paths.length,
-      indexed,
-      skipped,
-      removed,
-      issues: result.issues.map((i) => ({ path: i.path, message: i.message })),
-      durationMs: Date.now() - started
-    };
-    onProgress?.({ phase: "done", ...out, issues: out.issues.length });
-    return out;
+    return await indexInto(store, projectRoot, embedder, { onProgress });
   } finally {
     store.close();
   }
 }
-async function indexDecisions(store, embedder, projectRoot) {
-  const out = { paths: [], indexed: 0, skipped: 0 };
-  for (const row of store.listDecisions()) {
-    const item = decisionItem(projectRoot, row);
-    out.paths.push(item.path);
+var TooManyChangesError = class extends Error {
+  changed;
+  limit;
+  constructor(changed, limit) {
+    super(`${changed} items changed since the last index \u2014 run \`capsa index\``);
+    this.changed = changed;
+    this.limit = limit;
+    this.name = "TooManyChangesError";
+  }
+};
+async function indexInto(store, projectRoot, embedder, options = {}) {
+  const { onProgress, maxChanges } = options;
+  const started = Date.now();
+  if (store.needsRebuild()) {
+    onProgress?.({ phase: "rebuild" });
+    store.reset();
+  }
+  onProgress?.({ phase: "scan" });
+  const result = await scan(knowledgeAdapters(), { roots: [projectRoot] });
+  const items = result.items.filter((i) => i.scope === "project" && isInside(projectRoot, i.path));
+  const all = [...items, ...decisionItems(store, projectRoot)];
+  const { changed, skipped } = changedItems(store, all);
+  if (maxChanges !== void 0 && changed.length > maxChanges) {
+    throw new TooManyChangesError(changed.length, maxChanges);
+  }
+  let indexed = 0;
+  for (const c of changed) {
+    await indexItem(store, embedder, c.item, projectRoot, c.hash, c.previousId);
+    indexed++;
+    onProgress?.({ phase: "embed", scanned: all.length, indexed, skipped });
+  }
+  const seen = new Set(all.map((i) => i.path));
+  let removed = 0;
+  for (const row of store.listItems()) {
+    if (!seen.has(row.path)) {
+      store.deleteItem(row.id);
+      removed++;
+    }
+  }
+  const out = {
+    scanned: all.length,
+    indexed,
+    skipped,
+    removed,
+    issues: result.issues.map((i) => ({ path: i.path, message: i.message })),
+    durationMs: Date.now() - started
+  };
+  store.setMeta(META_INDEXED_AT, new Date(started).toISOString());
+  store.deleteMeta(META_INDEX_FAILED_AT);
+  store.deleteMeta(META_INDEX_ERROR);
+  onProgress?.({ phase: "done", ...out, issues: out.issues.length });
+  return out;
+}
+var DEFAULT_MAX_INDEX_AGE_MS = 6e4;
+var DEFAULT_MAX_REFRESH_CHANGES = 20;
+async function freshenIndex(store, projectRoot, embedder, options = {}) {
+  const maxAge = options.maxAgeMs ?? DEFAULT_MAX_INDEX_AGE_MS;
+  const maxChanges = options.maxChanges ?? DEFAULT_MAX_REFRESH_CHANGES;
+  const now = Date.now();
+  if (ageMs(store.getMeta(META_INDEXED_AT), now) <= maxAge)
+    return { refreshed: false, stale: false };
+  if (store.needsRebuild()) {
+    return {
+      refreshed: false,
+      stale: true,
+      reason: "this index was never built or its schema changed \u2014 run `capsa index`"
+    };
+  }
+  if (ageMs(store.getMeta(META_INDEX_FAILED_AT), now) <= maxAge) {
+    return { refreshed: false, stale: true, reason: store.getMeta(META_INDEX_ERROR) ?? "the last index run failed" };
+  }
+  try {
+    const res = await indexInto(store, projectRoot, embedder, { maxChanges });
+    return { refreshed: true, stale: false, indexed: res.indexed, removed: res.removed };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    store.setMeta(META_INDEX_FAILED_AT, (/* @__PURE__ */ new Date()).toISOString());
+    store.setMeta(META_INDEX_ERROR, reason);
+    return { refreshed: false, stale: true, reason };
+  }
+}
+function ageMs(iso, now) {
+  if (!iso)
+    return Number.POSITIVE_INFINITY;
+  const t = Date.parse(iso);
+  return Number.isNaN(t) ? Number.POSITIVE_INFINITY : now - t;
+}
+function changedItems(store, items) {
+  const changed = [];
+  let skipped = 0;
+  for (const item of items) {
     const hash2 = sha1(item.content);
     const existing = store.getItem(item.path);
     if (existing && existing.content_hash === hash2) {
-      out.skipped++;
+      skipped++;
       continue;
     }
-    if (existing)
-      store.deleteItem(existing.id);
-    await indexItem(store, embedder, item, projectRoot, hash2);
-    out.indexed++;
+    changed.push({ item, hash: hash2, previousId: existing?.id });
   }
-  return out;
+  return { changed, skipped };
+}
+function decisionItems(store, projectRoot) {
+  return store.listDecisions().map((row) => decisionItem(projectRoot, row));
 }
 async function recordDecision(store, embedder, projectRoot, input2) {
   const row = store.recordDecision(input2.title, input2.body, input2.related);
@@ -10801,16 +10886,22 @@ async function recordDecision(store, embedder, projectRoot, input2) {
     return { id: row.id, indexed: false, reason: err.message };
   }
 }
-async function indexItem(store, embedder, item, projectRoot, hash2) {
+async function indexItem(store, embedder, item, projectRoot, hash2, previousId) {
   const chunks = chunkMarkdown(item.content);
   const searchTexts = chunks.map((c) => withContext(item, c.headingPath, c.text));
   const vectors = searchTexts.length ? await embedder.embed(searchTexts) : [];
+  if (previousId)
+    store.deleteItem(previousId);
   const k = item.knowledge;
   store.upsertItem({
     id: item.id,
     format: item.format,
     kind: k?.kind ?? "instruction",
     name: item.name,
+    // The same expression the provenance header uses (see withContext): the
+    // title an item claims for itself, falling back to its name when the
+    // format has none to give.
+    title: item.description ?? item.name,
     path: item.path,
     rel_path: relative5(projectRoot, item.path),
     content_hash: hash2,
@@ -10968,9 +11059,17 @@ async function retrieve(store, embedder, query, options = {}) {
   const pinnedIds = new Set(pinned.map((i) => i.id));
   const neighbourCutoff = pinned.length ? Math.max(minRelative, 0.75) : minRelative;
   const neighbourBudget = pinned.length ? Math.min(maxTokens, tokens + Math.floor(maxTokens / 3)) : maxTokens;
-  const [qv] = await embedder.embed([query]);
-  const vec = qv ? store.vectorSearch(qv, candidates).map((r) => r.chunkId) : [];
-  const fts = store.textSearch(query, candidates).map((r) => r.chunkId);
+  const searchText = neighbourQuery(query, pinned);
+  let vec = [];
+  let degraded;
+  try {
+    const [qv] = await embedder.embed([searchText]);
+    if (qv)
+      vec = store.vectorSearch(qv, candidates).map((r) => r.chunkId);
+  } catch (err) {
+    degraded = err instanceof Error ? err.message : String(err);
+  }
+  const fts = store.textSearch(searchText, candidates).map((r) => r.chunkId);
   const fused = rrf([vec, fts], weights.rrfK);
   const rows = store.chunksWithItems([...fused.keys()]).filter((r) => !pinnedIds.has(r.item_id));
   const now = Date.now();
@@ -10979,10 +11078,33 @@ async function retrieve(store, embedder, query, options = {}) {
     const factor = signalFactor({ kind: r.item.kind, status: r.item.status, updatedAt: r.item.updated_at }, weights, now);
     return { row: r, fusedScore, factor, score: fusedScore * factor };
   }).sort((a, b) => b.score - a.score);
-  const best = scored[0]?.score ?? 0;
+  const neighbourhood = [];
+  for (const c of scored) {
+    if (options.excludeRootInstructions && isRootInstruction(c.row.item.rel_path)) {
+      if (options.debug) {
+        debug.push({
+          chunkId: c.row.id,
+          relPath: c.row.item.rel_path,
+          headingPath: JSON.parse(c.row.heading_path),
+          kind: c.row.item.kind,
+          status: c.row.item.status,
+          vecRank: rankIn(vec, c.row.id),
+          ftsRank: rankIn(fts, c.row.id),
+          fused: c.fusedScore,
+          factor: c.factor,
+          score: c.score,
+          kept: false,
+          why: "in prompt"
+        });
+      }
+      continue;
+    }
+    neighbourhood.push(c);
+  }
+  const best = neighbourhood[0]?.score ?? 0;
   let cut = tokens >= maxTokens;
   let kept = 0;
-  for (const { row, fusedScore, factor, score } of scored) {
+  for (const { row, fusedScore, factor, score } of neighbourhood) {
     let why = "kept";
     if (cut || kept > 0 && score < best * neighbourCutoff) {
       cut = true;
@@ -11030,13 +11152,37 @@ async function retrieve(store, embedder, query, options = {}) {
   }
   const durationMs = Date.now() - started;
   store.logContext({
-    source: options.source ?? "unknown",
+    // A keyword-only delivery is logged under its own source. The week-4
+    // gate is read from this table, and a run with half the retriever
+    // missing is not a sample of how the ranking performs — it should show
+    // up as its own bucket in a `group by source`, not quietly average in.
+    source: (options.source ?? "unknown") + (degraded ? ":degraded" : ""),
     query,
     delivered: chunks.map((c) => ({ rel_path: c.relPath, heading_path: c.headingPath, tokens: c.tokens })),
     tokensEst: tokens,
+    // The ceiling, not the spend: two rows are only comparable when this
+    // matches, and retrieval stops at the relevance cliff well before it.
+    tokensBudget: maxTokens,
     durationMs
   });
-  return { query, chunks, tokensEst: tokens, durationMs, ...options.debug ? { debug } : {} };
+  return {
+    query,
+    searchText,
+    chunks,
+    tokensEst: tokens,
+    durationMs,
+    ...degraded ? { degraded } : {},
+    ...options.debug ? { debug } : {}
+  };
+}
+function neighbourQuery(query, pinned) {
+  if (pinned.length === 0)
+    return query;
+  return pinned.map((i) => i.title).join("; ");
+}
+var ROOT_INSTRUCTION_FILES = /* @__PURE__ */ new Set(["CLAUDE.md", "CLAUDE.local.md", "AGENTS.md"]);
+function isRootInstruction(relPath) {
+  return ROOT_INSTRUCTION_FILES.has(relPath);
 }
 function rankIn(list, id) {
   const i = list.indexOf(id);
@@ -11045,7 +11191,11 @@ function rankIn(list, id) {
 function formatDebug(result) {
   if (!result.debug)
     return "";
-  const lines = ["  vec  fts  factor  score    keep         where"];
+  const lines = [
+    `stage 2 searched: ${JSON.stringify(result.searchText)}${result.searchText === result.query ? "" : " (from the pinned titles)"}`,
+    "",
+    "  vec  fts  factor  score    keep         where"
+  ];
   for (const d of result.debug) {
     const where = [d.relPath, ...d.headingPath].join(" \u203A ").slice(0, 70);
     lines.push([
@@ -40384,21 +40534,31 @@ var StdioServerTransport = class {
 function createCapsaServer(options) {
   const embedder = options.embedder ?? ollamaEmbedder();
   const server = new McpServer({ name: "capsa", version: "0.0.1" });
+  const ensureFresh = freshener(options, embedder);
   server.registerTool("get_context", {
     title: "Get project context",
     description: "Return the smallest set of project knowledge (runbooks, tickets, plans, decisions, instruction files) relevant to a task. Call this before starting work on a task; pass the task as you understand it.",
     inputSchema: {
       task: external_exports.string().describe("The task or question, in one or two sentences"),
-      maxTokens: external_exports.number().int().min(200).max(6e3).optional().describe("Token budget, default 1500")
+      // 3000 is a ceiling on a ceiling: retrieval stops at the relevance
+      // cliff long before it fills a budget, so a larger number only ever
+      // buys a longer tail of near-misses.
+      maxTokens: external_exports.number().int().min(200).max(3e3).optional().describe("Token budget, default 1500")
     }
   }, async ({ task, maxTokens }) => {
+    const freshness = await ensureFresh();
     const store = openStore(options.projectRoot, embedder);
     try {
-      const result = await retrieve(store, embedder, task, { maxTokens, source: "mcp:get_context" });
+      const result = await retrieve(store, embedder, task, {
+        maxTokens,
+        source: "mcp:get_context",
+        excludeRootInstructions: true
+      });
+      const caveat = caveats(freshness, result.degraded);
       const footer = `
 
 ---
-_capsa: ${result.chunks.length} chunks, ~${result.tokensEst} tokens, ${result.durationMs} ms_`;
+_capsa: ${result.chunks.length} chunks, ~${result.tokensEst} tokens, ${result.durationMs} ms${caveat ? ` \xB7 ${caveat}` : ""}_`;
       return { content: [{ type: "text", text: formatContext(result) + footer }] };
     } finally {
       store.close();
@@ -40409,9 +40569,14 @@ _capsa: ${result.chunks.length} chunks, ~${result.tokensEst} tokens, ${result.du
     description: "Where the project stands: open tickets and plans, recent decisions, recently changed knowledge.",
     inputSchema: {}
   }, async () => {
+    const freshness = await ensureFresh();
     const store = openStore(options.projectRoot, embedder);
     try {
-      return { content: [{ type: "text", text: formatState(projectState(store)) }] };
+      const caveat = caveats(freshness);
+      const text = formatState(projectState(store)) + (caveat ? `
+
+_${caveat}_` : "");
+      return { content: [{ type: "text", text }] };
     } finally {
       store.close();
     }
@@ -40440,6 +40605,41 @@ _capsa: ${result.chunks.length} chunks, ~${result.tokensEst} tokens, ${result.du
   });
   return server;
 }
+function freshener(options, embedder) {
+  const maxAgeMs = options.maxIndexAgeMs ?? DEFAULT_MAX_INDEX_AGE_MS;
+  let inFlight = null;
+  return () => {
+    if (!inFlight) {
+      const run = (async () => {
+        let store;
+        try {
+          store = openStore(options.projectRoot, embedder);
+          return await freshenIndex(store, options.projectRoot, embedder, { maxAgeMs });
+        } catch (err) {
+          return { refreshed: false, stale: true, reason: err instanceof Error ? err.message : String(err) };
+        } finally {
+          store?.close();
+        }
+      })();
+      inFlight = run;
+      void run.finally(() => {
+        if (inFlight === run)
+          inFlight = null;
+      });
+    }
+    return inFlight;
+  };
+}
+function caveats(freshness, degraded) {
+  const parts = [];
+  if (freshness.stale) {
+    parts.push(`index may be out of date \u2014 ${freshness.reason ?? "the last index run did not finish"}`);
+  }
+  if (degraded) {
+    parts.push(freshness.stale ? "keyword-only search (no embeddings)" : `keyword-only search \u2014 ${degraded}`);
+  }
+  return parts.join(" \xB7 ");
+}
 async function serveStdio(options) {
   const server = createCapsaServer(options);
   await server.connect(new StdioServerTransport());
@@ -40516,6 +40716,8 @@ async function runSearchCommand(args) {
     } else {
       console.log(formatContext(res));
     }
+    if (res.degraded) console.error(`
+capsa: keyword-only search \u2014 ${res.degraded}`);
     console.error(`
 ${res.chunks.length} chunks, ~${res.tokensEst} tokens, ${res.durationMs} ms`);
   } finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yurtsever/capsa",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "description": "Your project's knowledge in one capsule. Local-first project memory and cockpit for AI coding agents: indexes runbooks, tickets, plans and instruction files, serves the smallest relevant context over MCP.",
   "type": "module",
   "license": "MIT",