@cortexkit/aft-opencode 0.31.1 → 0.32.0

package/dist/index.js

@@ -31990,6 +31990,19 @@ function formatFlag(enabled) {
 function formatCount(value) {
   return value == null ? "—" : value.toLocaleString("en-US");
 }
+function formatSemanticIndexStatus(status, stage) {
+  if ((status === "loading" || status === "building") && stage === "fingerprint_change") {
+    return "Rebuilding (model changed)";
+  }
+  return status;
+}
+function formatSemanticRefreshing(refreshingCount) {
+  if (!Number.isFinite(refreshingCount) || refreshingCount <= 0)
+    return null;
+  if (refreshingCount > 20)
+    return "Ready (many files refreshing)";
+  return `Ready (${refreshingCount} file(s) refreshing)`;
+}
 function formatBytes(bytes) {
   if (!Number.isFinite(bytes) || bytes <= 0)
     return "0 B";
@@ -32041,6 +32054,7 @@ function coerceAftStatus(response) {
       files: readOptionalNumber(semanticIndex.files),
       entries_done: readOptionalNumber(semanticIndex.entries_done),
       entries_total: readOptionalNumber(semanticIndex.entries_total),
+      refreshing_count: readNumber(semanticIndex.refreshing_count),
       entries: readOptionalNumber(semanticIndex.entries),
       dimension: readOptionalNumber(semanticIndex.dimension),
       error: readNullableString(semanticIndex.error)
@@ -32086,9 +32100,13 @@ function formatStatusMarkdown(status) {
     `- **Trigrams:** ${formatCount(status.search_index.trigrams)}`,
     "",
     "### Semantic index",
-    `- **Status:** \`${status.semantic_index.status}\``,
-    `- **Entries:** ${formatCount(status.semantic_index.entries)}`
+    `- **Status:** \`${formatSemanticIndexStatus(status.semantic_index.status, status.semantic_index.stage)}\``
   ];
+  const refreshing = formatSemanticRefreshing(status.semantic_index.refreshing_count);
+  if (refreshing) {
+    lines.push(`- **Refresh:** ${refreshing}`);
+  }
+  lines.push(`- **Entries:** ${formatCount(status.semantic_index.entries)}`);
   if (status.semantic_index.backend) {
     lines.push(`- **Backend:** ${status.semantic_index.backend}`);
   }
@@ -32249,6 +32267,17 @@ import * as path2 from "node:path";
 import { tool as tool2 } from "@opencode-ai/plugin";
 var z2 = tool2.schema;
 var optionalInt = (min, max) => z2.number().int().min(min).max(max).optional();
+function isEmptyParam(value) {
+  if (value === undefined || value === null)
+    return true;
+  if (typeof value === "string")
+    return value.length === 0;
+  if (Array.isArray(value))
+    return value.length === 0;
+  if (typeof value === "object")
+    return Object.keys(value).length === 0;
+  return false;
+}
 var LONG_RUNNING_COMMAND_TIMEOUT_MS = {
   callers: 60000,
   trace_to: 60000,
@@ -32257,7 +32286,7 @@ var LONG_RUNNING_COMMAND_TIMEOUT_MS = {
   impact: 60000,
   grep: 60000,
   glob: 60000,
-  semantic_search: 45000
+  semantic_search: 60000
 };
 function timeoutForCommand(command) {
   return LONG_RUNNING_COMMAND_TIMEOUT_MS[command];
@@ -32569,9 +32598,9 @@ function astTools(ctx) {
         pattern: args.pattern,
         lang: args.lang
       };
-      if (args.paths)
+      if (!isEmptyParam(args.paths))
         params.paths = args.paths;
-      if (args.globs)
+      if (!isEmptyParam(args.globs))
         params.globs = args.globs;
       if (args.contextLines !== undefined)
         params.context = Number(args.contextLines);
@@ -32689,9 +32718,9 @@ ${hint}`;
         rewrite: args.rewrite,
         lang: args.lang
       };
-      if (args.paths)
+      if (!isEmptyParam(args.paths))
         params.paths = args.paths;
-      if (args.globs)
+      if (!isEmptyParam(args.globs))
         params.globs = args.globs;
       params.dry_run = args.dryRun === true;
       const response = await callBridge(ctx, context, "ast_replace", params);
@@ -35174,7 +35203,7 @@ function getCallID3(ctx) {
   return c.callID ?? c.callId ?? c.call_id;
 }
 function buildZoomTitle(args) {
-  if (args.targets !== undefined && args.targets !== null) {
+  if (!isEmptyParam(args.targets)) {
     if (Array.isArray(args.targets)) {
       if (args.targets.length === 1 && args.targets[0]) {
         return `${args.targets[0].filePath}#${args.targets[0].symbol}`;
@@ -35303,14 +35332,26 @@ function readingTools(ctx) {
         contextLines: optionalInt(1, Number.MAX_SAFE_INTEGER).describe("Lines of context before/after the symbol (default: 3)")
       },
       execute: async (args, context) => {
-        const hasFilePath = typeof args.filePath === "string" && args.filePath.length > 0;
-        const hasUrl = typeof args.url === "string" && args.url.length > 0;
-        const hasTargets = args.targets !== undefined && args.targets !== null;
-        const hasSymbols = args.symbols !== undefined && args.symbols !== null && (typeof args.symbols === "string" ? args.symbols.length > 0 : Array.isArray(args.symbols) && args.symbols.length > 0);
+        const hasFilePath = !isEmptyParam(args.filePath);
+        const hasUrl = !isEmptyParam(args.url);
+        const hasTargets = !isEmptyParam(args.targets);
+        const hasSymbols = !isEmptyParam(args.symbols);
         const zoomCallID = getCallID3(context);
         if (zoomCallID) {
           const title = buildZoomTitle(args);
-          storeToolMetadata(context.sessionID, zoomCallID, { title, metadata: { title } });
+          const display = { title };
+          if (hasFilePath)
+            display.filePath = args.filePath;
+          if (hasUrl)
+            display.url = args.url;
+          if (hasSymbols) {
+            display.symbols = typeof args.symbols === "string" ? args.symbols : JSON.stringify(args.symbols);
+          }
+          if (hasTargets)
+            display.targets = JSON.stringify(args.targets);
+          if (args.contextLines !== undefined)
+            display.contextLines = args.contextLines;
+          storeToolMetadata(context.sessionID, zoomCallID, { title, metadata: display });
         }
         if (hasTargets) {
           if (hasFilePath || hasUrl || hasSymbols) {
@@ -35560,14 +35601,14 @@ function refactoringTools(ctx) {
       },
       execute: async (args, context) => {
         const op = args.op;
-        if ((op === "move" || op === "inline") && typeof args.symbol !== "string") {
+        if ((op === "move" || op === "inline") && isEmptyParam(args.symbol)) {
           throw new Error(`'symbol' is required for '${op}' op`);
         }
-        if (op === "move" && typeof args.destination !== "string") {
+        if (op === "move" && isEmptyParam(args.destination)) {
           throw new Error("'destination' is required for 'move' op");
         }
         if (op === "extract") {
-          if (typeof args.name !== "string")
+          if (isEmptyParam(args.name))
             throw new Error("'name' is required for 'extract' op");
           if (args.startLine === undefined)
             throw new Error("'startLine' is required for 'extract' op");
@@ -35950,32 +35991,46 @@ function arg2(schema) {
 function semanticTools(ctx) {
   const searchTool = {
     description: [
-      "Find symbols by concept using hybrid semantic + lexical search. Returns ranked code matches with similarity scores and provenance tags.",
+      "Find code with unified semantic, lexical, literal, and regex search. Returns ranked symbol/file results or exact matching lines, with routing metadata.",
       "",
       "When to reach for it:",
       "- Exploring an unfamiliar area: 'where is rate limiting handled', 'how does auth flow work'",
       "- Concept doesn't appear as a literal string: 'retry logic', 'cache invalidation', 'graceful shutdown'",
       "- Filename-shaped concepts: 'the bridge spawn helper', 'the session detection module'",
-      "- After 2+ grep attempts that came back empty or noisy",
+      "- Regex-shaped or exact text queries when you want AFT to classify and route automatically",
       "- You know roughly what the function does but not what it's named",
       "",
       "When NOT to use:",
-      "- You have an error message or stack trace → use grep",
+      "- You need exhaustive literal enumeration → use grep directly",
       "- You want the file/module structure → use aft_outline",
       "- You're following a call chain → use aft_navigate",
       "",
-      "Each result tags `source` as one of: 'semantic' (embedding match only), 'lexical' (trigram exact-token match the embedding lane missed), or 'hybrid' (both lanes agreed — strongest signal)."
+      "Set hint to 'regex', 'literal', 'semantic', or 'auto' to override or document routing intent."
     ].join(`
 `),
     args: {
-      query: arg2(z14.string().describe("Concept or capability to find, phrased as a programmer would describe the code. Examples: 'fuzzy match with whitespace tolerance', 'undo backup before edit', 'retry failed network request'.")),
-      topK: arg2(optionalInt(1, 100).describe("Number of results (default: 10, max: 100)"))
+      query: arg2(z14.string().describe("Concept, regex, literal text, filename, or capability to find. Examples: 'fuzzy match with whitespace tolerance', '^export', 'Cargo.lock'.")),
+      topK: arg2(optionalInt(1, 100).describe("Number of results (default: 10, max: 100)")),
+      hint: arg2(z14.enum(["regex", "literal", "semantic", "auto"]).optional().describe("Optional routing hint. Defaults to 'auto'."))
     },
     execute: async (args, context) => {
-      const response = await callBridge(ctx, context, "semantic_search", {
-        query: args.query,
+      if (typeof args.query !== "string" || args.query.length === 0) {
+        throw new Error("semantic_search: invalid params: missing field `query`");
+      }
+      const query = args.query;
+      const hint = typeof args.hint === "string" ? args.hint : undefined;
+      if (hint !== "semantic") {
+        const denied = await askGrepPermission(context, query);
+        if (denied)
+          return permissionDeniedResponse(denied);
+      }
+      const bridgeParams = {
+        query,
         top_k: args.topK ?? 10
-      });
+      };
+      if (hint)
+        bridgeParams.hint = hint;
+      const response = await callBridge(ctx, context, "semantic_search", bridgeParams);
       if (response.success === false) {
         if (response.code === "semantic_search_unavailable" && typeof response.message === "string") {
           return response.message;
@@ -36122,8 +36177,12 @@ function buildWorkflowHints(opts) {
     sections.push(`**Web/URL access**: \`aft_outline({ target: url })\` first for structure, then \`aft_zoom({ url, symbols: "<heading>" })\` for the specific section.`);
   }
   if (hasOutline && hasZoom && (hasGrep || hasSearch)) {
-    const locator = hasGrep ? `\`${grepName}\`` : "`aft_search`";
-    sections.push(hasGrep && hasSearch ? `**Code exploration**: For exact identifiers (\`useState\`, function names, env vars), error messages, or path-shaped queries → \`${grepName}\` first. For broad concepts ('where is X handled', 'how does Y work') → \`aft_search\`. Then use \`aft_outline\` for structure → \`aft_zoom\` for symbol(s).` : `**Code exploration**: ${locator} to locate → \`aft_outline\` for structure → \`aft_zoom\` for symbol(s).`);
+    if (hasSearch) {
+      const grepFallback = hasGrep ? ` Use \`${grepName}\` directly only when you need exhaustive enumeration of literal text (every TODO, every import of X) without ranking.` : "";
+      sections.push(`**Code exploration**: \`aft_search\` is the primary code-search tool. It auto-routes by query shape — exact identifiers, regex, error messages, natural language all use the same call. Pass \`hint: "regex"\` / \`hint: "literal"\` / \`hint: "semantic"\` to override routing if needed. Then \`aft_outline\` for structure → \`aft_zoom\` for symbol(s).${grepFallback}`);
+    } else {
+      sections.push(`**Code exploration**: \`${grepName}\` to locate → \`aft_outline\` for structure → \`aft_zoom\` for symbol(s).`);
+    }
   }
   if (hasNavigate) {
     sections.push([
@@ -36244,13 +36303,13 @@ var PLUGIN_VERSION = (() => {
     return "0.0.0";
   }
 })();
-var ANNOUNCEMENT_VERSION = "0.31.0";
+var ANNOUNCEMENT_VERSION = "0.32.0";
 var ANNOUNCEMENT_FEATURES = [
-  "`aft_navigate` has a new `trace_to_symbol` op for path-between-symbols queries. One call returns the shortest call path from one function to another with file + line for every hop. Honest errors for ambiguous, missing, or unreachable targets — including a candidate list to disambiguate.",
-  '`aft_outline target: "<dir>", files: true` returns an indexed file tree with language, symbol count, and byte size per file. Lets agents pick which files to actually open without first reading symbol bodies. Honest truncation (`complete: false` + `walk_truncated`/`unchecked_files`) when the directory exceeds the walk cap.',
-  '`aft_zoom` adds `targets` for cross-file batches — pull bodies from different files in one call. Schema breaking change: `symbol` is removed; pass `symbols: "name"` (string) or `symbols: ["a", "b"]` (array). Same shape works for `url` mode so you can grab multiple sections from one URL fetch.',
-  "Bun/npm/pnpm test compressors now match on output shape, not just on the head token. Wrapper invocations like `bun run --cwd packages/foo test`, `npm test`, and `pnpm test` keep failing-test bodies on the first run instead of dropping them to a generic summary.",
-  "Tool descriptions trimmed: ~1.2K agent-facing tokens removed (-19% on OpenCode, -2% on Pi) by dropping redundant `Returns:` blocks and compressing `lsp_diagnostics` while preserving its load-bearing honesty guidance."
+  "`aft_search` is now the primary code-search tool — auto-routes regex / literal / semantic / hybrid by query shape, with a `hint` override.",
+  'Semantic search stays queryable through edits — no more "rebuilding" fallback after every save.',
+  "Workflow hints promote `aft_search` as primary; `grep` is positioned as the specialized fallback.",
+  "Bare `\\n`, `\\t`, `\\r` queries correctly route to regex mode.",
+  'Empty params (`targets: []`, `url: ""`) no longer trigger misleading mutual-exclusion errors.'
 ];
 var ANNOUNCEMENT_FOOTER = "Join us on Discord: https://discord.gg/F2uWxjGnU";
 var plugin = async (input) => initializePluginForDirectory(input);

package/dist/shared/status.d.ts

@@ -44,6 +44,7 @@ export interface AftStatusSnapshot {
         files?: number | null;
         entries_done?: number | null;
         entries_total?: number | null;
+        refreshing_count: number;
         entries: number | null;
         dimension: number | null;
         error?: string | null;
@@ -78,6 +79,8 @@ export interface AftStatusSnapshot {
      */
     message: string;
 }
+export declare function formatSemanticIndexStatus(status: string, stage?: string | null): string;
+export declare function formatSemanticRefreshing(refreshingCount: number): string | null;
 export declare function formatBytes(bytes: number): string;
 export declare function coerceAftStatus(response: Record<string, unknown>): AftStatusSnapshot;
 /**

package/dist/shared/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/shared/status.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,0BAA0B,CAAC;IACpC,OAAO,EAAE,0BAA0B,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,EAAE;QACR,cAAc,EAAE,OAAO,CAAC;QACxB,gBAAgB,EAAE,MAAM,CAAC;QACzB,wBAAwB,EAAE,OAAO,CAAC;QAClC,YAAY,EAAE,OAAO,CAAC;QACtB,eAAe,EAAE,OAAO,CAAC;KAC1B,CAAC;IACF,YAAY,EAAE;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;KACzB,CAAC;IACF,cAAc,EAAE;QACd,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,CAAC;IACF,IAAI,EAAE;QACJ,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,kBAAkB,EAAE,MAAM,CAAC;QAC3B,mBAAmB,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE;QACZ,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iEAAiE;IACjE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,wEAAwE;IACxE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAqDD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAajD;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,CAmEpF;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAuE3E;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CA0EtE"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/shared/status.ts"],"names":[],"mappings":"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"}

package/dist/tools/_shared.d.ts

@@ -56,6 +56,19 @@ export declare const optionalInt: (min: number, max: number) => any;
  * declared more permissively.
  */
 export declare function coerceOptionalInt(v: unknown, paramName: string, min: number, max: number): number | undefined;
+/**
+ * True when a value represents "agent did not provide this param".
+ *
+ * GPT-family models send empty strings / empty arrays / null instead of
+ * omitting optional params entirely. Use this BEFORE mutual-exclusion
+ * checks so an empty `targets: []` or `url: ""` doesn't get counted as
+ * present and trigger a misleading "X is mutually exclusive with Y" error.
+ *
+ * Treats undefined / null / "" / [] / {} as empty. Booleans and numbers
+ * (including 0 and false) are NOT empty by themselves — only string and
+ * collection sentinels qualify.
+ */
+export declare function isEmptyParam(value: unknown): boolean;
 /**
  * Per-command timeout overrides (milliseconds).
  *

package/dist/tools/_shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../src/tools/_shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAQhF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,GACR,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,CAAC,EAAE,OAAO,EACV,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,SAAS,CAWpB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CASlE,CAAC;AAEF,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAErE;AA2BD,8EAA8E;AAC9E,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,MAAM,CAsDR;AAsBD;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAW3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,WAAW,GAAG,YAAY,CAEhF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA0BlC;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAE9F"}
+{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../src/tools/_shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAQhF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,GACR,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,CAAC,EAAE,OAAO,EACV,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,SAAS,CAWpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMpD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CASlE,CAAC;AAEF,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAErE;AA2BD,8EAA8E;AAC9E,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,MAAM,CAsDR;AAsBD;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAW3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,WAAW,GAAG,YAAY,CAEhF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA0BlC;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAE9F"}

package/dist/tools/ast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/tools/ast.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAkDjD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CA0S3E"}
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/tools/ast.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAkDjD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CA8S3E"}

package/dist/tools/reading.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reading.d.ts","sourceRoot":"","sources":["../../src/tools/reading.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAsCjD,UAAU,qBAAqB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,eAAe;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAmS/E;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GACnC,eAAe,CAyBjB;AA+CD,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CA2ChF"}
+{"version":3,"file":"reading.d.ts","sourceRoot":"","sources":["../../src/tools/reading.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA0CjD,UAAU,qBAAqB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,eAAe;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CA2S/E;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GACnC,eAAe,CAyBjB;AA+CD,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CA2ChF"}

package/dist/tools/refactoring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refactoring.d.ts","sourceRoot":"","sources":["../../src/tools/refactoring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAcjD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAyInF"}
+{"version":3,"file":"refactoring.d.ts","sourceRoot":"","sources":["../../src/tools/refactoring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAcjD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CA4InF"}

package/dist/tools/semantic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../src/tools/semantic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAWjD,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAyDhF"}
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../src/tools/semantic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAYjD,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CA8EhF"}

package/dist/tui.js

@@ -1,7 +1,7 @@
 // src/tui/index.tsx
 import { createMemo as createMemo2, createSignal as createSignal2, onCleanup as onCleanup2 } from "solid-js";
 // package.json
-var version = "0.31.1";
+var version = "0.32.0";
 
 // src/shared/rpc-client.ts
 import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
@@ -343,6 +343,19 @@ function readCompression(value) {
     session: readCompressionAggregate(compression.session)
   };
 }
+function formatSemanticIndexStatus(status, stage) {
+  if ((status === "loading" || status === "building") && stage === "fingerprint_change") {
+    return "Rebuilding (model changed)";
+  }
+  return status;
+}
+function formatSemanticRefreshing(refreshingCount) {
+  if (!Number.isFinite(refreshingCount) || refreshingCount <= 0)
+    return null;
+  if (refreshingCount > 20)
+    return "Ready (many files refreshing)";
+  return `Ready (${refreshingCount} file(s) refreshing)`;
+}
 function formatBytes(bytes) {
   if (!Number.isFinite(bytes) || bytes <= 0)
     return "0 B";
@@ -394,6 +407,7 @@ function coerceAftStatus(response) {
       files: readOptionalNumber(semanticIndex.files),
       entries_done: readOptionalNumber(semanticIndex.entries_done),
       entries_total: readOptionalNumber(semanticIndex.entries_total),
+      refreshing_count: readNumber(semanticIndex.refreshing_count),
       entries: readOptionalNumber(semanticIndex.entries),
       dimension: readOptionalNumber(semanticIndex.dimension),
       error: readNullableString(semanticIndex.error)
@@ -690,7 +704,15 @@ var SidebarContent = (props) => {
   const s = () => scopedSidebarSnapshot(status(), currentDirectory(), props.sessionID());
   const notInitialized = () => s()?.cache_role === "not_initialized";
   const searchStatus = () => statusDisplay(s()?.search_index?.status ?? "disabled");
-  const semanticStatus = () => statusDisplay(s()?.semantic_index?.status ?? "disabled");
+  const semanticStatus = () => {
+    const rawStatus = s()?.semantic_index?.status ?? "disabled";
+    const display = statusDisplay(rawStatus);
+    return {
+      ...display,
+      label: formatSemanticIndexStatus(rawStatus, s()?.semantic_index?.stage)
+    };
+  };
+  const semanticRefreshing = () => formatSemanticRefreshing(s()?.semantic_index?.refreshing_count ?? 0);
   const trigramBytes = () => s()?.disk?.trigram_disk_bytes ?? 0;
   const semanticBytes = () => s()?.disk?.semantic_disk_bytes ?? 0;
   const compressionRows = () => formatCompressionSidebarRows(s()?.compression);
@@ -819,6 +841,13 @@ var SidebarContent = (props) => {
             value: semanticStatus().label,
             tone: semanticStatus().tone
           }, undefined, false, undefined, this),
+          semanticRefreshing() && /* @__PURE__ */ jsxDEV("box", {
+            width: "100%",
+            children: /* @__PURE__ */ jsxDEV("text", {
+              fg: props.theme.textMuted,
+              children: semanticRefreshing()
+            }, undefined, false, undefined, this)
+          }, undefined, false, undefined, this),
           s()?.semantic_index?.status === "loading" && s()?.semantic_index?.entries_total != null && s().semantic_index.entries_total > 0 && /* @__PURE__ */ jsxDEV(StatRow, {
             theme: props.theme,
             label: "Progress",
@@ -1189,9 +1218,16 @@ var StatusDialog = (props) => {
               /* @__PURE__ */ jsxDEV2(R, {
                 theme: t(),
                 label: "Status",
-                value: status().semantic_index.status,
+                value: formatSemanticIndexStatus(status().semantic_index.status, status().semantic_index.stage),
                 tone: statusTone(status().semantic_index.status)
               }, undefined, false, undefined, this),
+              formatSemanticRefreshing(status().semantic_index.refreshing_count) ? /* @__PURE__ */ jsxDEV2("box", {
+                width: "100%",
+                children: /* @__PURE__ */ jsxDEV2("text", {
+                  fg: t().textMuted,
+                  children: formatSemanticRefreshing(status().semantic_index.refreshing_count)
+                }, undefined, false, undefined, this)
+              }, undefined, false, undefined, this) : null,
               /* @__PURE__ */ jsxDEV2(R, {
                 theme: t(),
                 label: "Entries",

package/dist/workflow-hints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-hints.d.ts","sourceRoot":"","sources":["../src/workflow-hints.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,SAAS,EAAqB,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,WAAW,EAAE,SAAS,GAAG,aAAa,GAAG,KAAK,CAAC;IAC/C,4EAA4E;IAC5E,aAAa,EAAE,OAAO,CAAC;IACvB,mEAAmE;IACnE,eAAe,EAAE,OAAO,CAAC;IACzB,wEAAwE;IACxE,qBAAqB,EAAE,OAAO,CAAC;IAC/B,4DAA4D;IAC5D,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC5B;AAID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAwEzE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAQjG"}
+{"version":3,"file":"workflow-hints.d.ts","sourceRoot":"","sources":["../src/workflow-hints.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,SAAS,EAAqB,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,WAAW,EAAE,SAAS,GAAG,aAAa,GAAG,KAAK,CAAC;IAC/C,4EAA4E;IAC5E,aAAa,EAAE,OAAO,CAAC;IACvB,mEAAmE;IACnE,eAAe,EAAE,OAAO,CAAC;IACzB,wEAAwE;IACxE,qBAAqB,EAAE,OAAO,CAAC;IAC/B,4DAA4D;IAC5D,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC5B;AAID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CA8EzE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAQjG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/aft-opencode",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "type": "module",
   "description": "OpenCode plugin for Agent File Tools (AFT) — tree-sitter and lsp powered code analysis",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.2.0",
-    "@cortexkit/aft-bridge": "0.31.1",
+    "@cortexkit/aft-bridge": "0.32.0",
     "@opencode-ai/plugin": "^1.15.5",
     "@opencode-ai/sdk": "^1.15.5",
     "@xterm/headless": "^5.5.0",
@@ -38,12 +38,12 @@
     "zod": "^4.1.8"
   },
   "optionalDependencies": {
-    "@cortexkit/aft-darwin-arm64": "0.31.1",
-    "@cortexkit/aft-darwin-x64": "0.31.1",
-    "@cortexkit/aft-linux-arm64": "0.31.1",
-    "@cortexkit/aft-linux-x64": "0.31.1",
-    "@cortexkit/aft-win32-arm64": "0.31.1",
-    "@cortexkit/aft-win32-x64": "0.31.1"
+    "@cortexkit/aft-darwin-arm64": "0.32.0",
+    "@cortexkit/aft-darwin-x64": "0.32.0",
+    "@cortexkit/aft-linux-arm64": "0.32.0",
+    "@cortexkit/aft-linux-x64": "0.32.0",
+    "@cortexkit/aft-win32-arm64": "0.32.0",
+    "@cortexkit/aft-win32-x64": "0.32.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/shared/status.ts

@@ -46,6 +46,7 @@ export interface AftStatusSnapshot {
     files?: number | null;
     entries_done?: number | null;
     entries_total?: number | null;
+    refreshing_count: number;
     entries: number | null;
     dimension: number | null;
     error?: string | null;
@@ -132,6 +133,19 @@ function formatCount(value: number | null): string {
   return value == null ? "—" : value.toLocaleString("en-US");
 }
 
+export function formatSemanticIndexStatus(status: string, stage?: string | null): string {
+  if ((status === "loading" || status === "building") && stage === "fingerprint_change") {
+    return "Rebuilding (model changed)";
+  }
+  return status;
+}
+
+export function formatSemanticRefreshing(refreshingCount: number): string | null {
+  if (!Number.isFinite(refreshingCount) || refreshingCount <= 0) return null;
+  if (refreshingCount > 20) return "Ready (many files refreshing)";
+  return `Ready (${refreshingCount} file(s) refreshing)`;
+}
+
 export function formatBytes(bytes: number): string {
   if (!Number.isFinite(bytes) || bytes <= 0) return "0 B";
   const units = ["B", "KB", "MB", "GB", "TB"];
@@ -190,6 +204,7 @@ export function coerceAftStatus(response: Record<string, unknown>): AftStatusSna
       files: readOptionalNumber(semanticIndex.files),
       entries_done: readOptionalNumber(semanticIndex.entries_done),
       entries_total: readOptionalNumber(semanticIndex.entries_total),
+      refreshing_count: readNumber(semanticIndex.refreshing_count),
       entries: readOptionalNumber(semanticIndex.entries),
       dimension: readOptionalNumber(semanticIndex.dimension),
       error: readNullableString(semanticIndex.error),
@@ -241,9 +256,13 @@ export function formatStatusDialogMessage(status: AftStatusSnapshot): string {
     `- trigrams: ${formatCount(status.search_index.trigrams)}`,
     "",
     "Semantic index",
-    `- status: ${status.semantic_index.status}`,
-    `- entries: ${formatCount(status.semantic_index.entries)}`,
+    `- status: ${formatSemanticIndexStatus(status.semantic_index.status, status.semantic_index.stage)}`,
   ];
+  const refreshing = formatSemanticRefreshing(status.semantic_index.refreshing_count);
+  if (refreshing) {
+    lines.push(`- ${refreshing}`);
+  }
+  lines.push(`- entries: ${formatCount(status.semantic_index.entries)}`);
   if (status.semantic_index.backend) {
     lines.push(`- backend: ${status.semantic_index.backend}`);
   }
@@ -316,9 +335,13 @@ export function formatStatusMarkdown(status: AftStatusSnapshot): string {
     `- **Trigrams:** ${formatCount(status.search_index.trigrams)}`,
     "",
     "### Semantic index",
-    `- **Status:** \`${status.semantic_index.status}\``,
-    `- **Entries:** ${formatCount(status.semantic_index.entries)}`,
+    `- **Status:** \`${formatSemanticIndexStatus(status.semantic_index.status, status.semantic_index.stage)}\``,
   ];
+  const refreshing = formatSemanticRefreshing(status.semantic_index.refreshing_count);
+  if (refreshing) {
+    lines.push(`- **Refresh:** ${refreshing}`);
+  }
+  lines.push(`- **Entries:** ${formatCount(status.semantic_index.entries)}`);
   if (status.semantic_index.backend) {
     lines.push(`- **Backend:** ${status.semantic_index.backend}`);
   }

package/src/tui/index.tsx

@@ -6,7 +6,13 @@ import { createMemo, createSignal, onCleanup } from "solid-js";
 
 import { version as packageVersion } from "../../package.json";
 import { AftRpcClient } from "../shared/rpc-client";
-import { type AftStatusSnapshot, coerceAftStatus, formatBytes } from "../shared/status";
+import {
+  type AftStatusSnapshot,
+  coerceAftStatus,
+  formatBytes,
+  formatSemanticIndexStatus,
+  formatSemanticRefreshing,
+} from "../shared/status";
 import {
   createAftSidebarSlot,
   formatCompressionSidebarRows,
@@ -331,9 +337,19 @@ const StatusDialog = (props: StatusDialogProps) => {
             <R
               theme={t()}
               label="Status"
-              value={status()!.semantic_index.status}
+              value={formatSemanticIndexStatus(
+                status()!.semantic_index.status,
+                status()!.semantic_index.stage,
+              )}
               tone={statusTone(status()!.semantic_index.status)}
             />
+            {formatSemanticRefreshing(status()!.semantic_index.refreshing_count) ? (
+              <box width="100%">
+                <text fg={t().textMuted}>
+                  {formatSemanticRefreshing(status()!.semantic_index.refreshing_count)}
+                </text>
+              </box>
+            ) : null}
             <R
               theme={t()}
               label="Entries"

package/src/tui/sidebar.tsx

@@ -11,7 +11,13 @@ import type { TuiPluginApi, TuiSlotPlugin, TuiThemeCurrent } from "@opencode-ai/
 import { createEffect, createMemo, createSignal, on, onCleanup } from "solid-js";
 
 import { AftRpcClient } from "../shared/rpc-client";
-import { type AftStatusSnapshot, coerceAftStatus, type StatusCompression } from "../shared/status";
+import {
+  type AftStatusSnapshot,
+  coerceAftStatus,
+  formatSemanticIndexStatus,
+  formatSemanticRefreshing,
+  type StatusCompression,
+} from "../shared/status";
 import { resolveCortexKitStorageRoot } from "../shared/storage-paths";
 
 const SINGLE_BORDER = { type: "single" } as any;
@@ -341,7 +347,16 @@ const SidebarContent = (props: {
   // Pre-compute display values so the JSX stays readable. createMemo for
   // each derived field would be overkill — these are cheap derivations.
   const searchStatus = () => statusDisplay(s()?.search_index?.status ?? "disabled");
-  const semanticStatus = () => statusDisplay(s()?.semantic_index?.status ?? "disabled");
+  const semanticStatus = () => {
+    const rawStatus = s()?.semantic_index?.status ?? "disabled";
+    const display = statusDisplay(rawStatus);
+    return {
+      ...display,
+      label: formatSemanticIndexStatus(rawStatus, s()?.semantic_index?.stage),
+    };
+  };
+  const semanticRefreshing = () =>
+    formatSemanticRefreshing(s()?.semantic_index?.refreshing_count ?? 0);
   const trigramBytes = () => s()?.disk?.trigram_disk_bytes ?? 0;
   const semanticBytes = () => s()?.disk?.semantic_disk_bytes ?? 0;
   const compressionRows = () => formatCompressionSidebarRows(s()?.compression);
@@ -463,6 +478,11 @@ const SidebarContent = (props: {
             value={semanticStatus().label}
             tone={semanticStatus().tone}
           />
+          {semanticRefreshing() && (
+            <box width="100%">
+              <text fg={props.theme.textMuted}>{semanticRefreshing()}</text>
+            </box>
+          )}
           {/* When loading, magic-context-style progress hint helps users see
           background work is making progress instead of stuck. */}
           {s()?.semantic_index?.status === "loading" &&