opencode-sessions-explorer 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.4] - 2026-06-14
+
+### Fixed
+- `search-text` now preserves requested `sem`/`hybrid` modes when the `ck` semantic
+  index is missing, allowing `ck` to perform its normal lazy auto-indexing instead
+  of falling back to regex.
+
 ## [0.1.3] - 2026-06-14
 
 ### Fixed

package/README.md

@@ -71,7 +71,9 @@ bunx opencode-sessions-explorer-check-deps
 bunx opencode-sessions-explorer-bulk-export
 ```
 
-1. (Optional) Build the `ck` index from the export root, not the repo root:
+1. (Optional) Prewarm the `ck` index from the export root, not the repo root.
+   Normal `lex`, `sem`, and `hybrid` searches ask `ck` to build or refresh indexes
+   lazily, so this step is only for avoiding first-search latency or troubleshooting:
 
 ```bash
 cd ~/.local/share/opencode-sessions-explorer
@@ -125,9 +127,10 @@ full first-run walkthrough, see [docs/install.md](docs/install.md) and
 ### Export and Maintenance
 
 - **One-time export.** `bulk-export` materializes searchable session content for `ck`.
-- **Stay current.** The plugin auto-syncs new parts before each search call; rebuild
-  the optional semantic index explicitly (`ck --reindex .` / `ck --index .`) when
-  `sem` or `hybrid` warnings report stale or partial coverage.
+- **Stay current.** The plugin auto-syncs new parts before each search call, then
+  lets normal `lex`, `sem`, and `hybrid` `ck` searches lazily build or refresh their
+  indexes. Explicit `ck --index .` / `ck --reindex .` runs are optional prewarm or
+  troubleshooting steps for stale or partial coverage warnings.
 - **Health probe.** `check-deps` and the `db-stats` tool report dependency and schema
   health.
 - See [docs/guides/export-and-maintenance.md](docs/guides/export-and-maintenance.md).

package/dist/bin/check-deps.js

@@ -1581,7 +1581,7 @@ try {
       if (idx.present)
         pass("ck index", idx.embedded_chunks != null ? `present (${idx.embedded_chunks} embedded chunks)` : "present");
       else
-        warn("ck index", "not built", "For semantic search: `cd " + root + " && ck --index .` (slow, one-time, ~5h for ~150k parts)");
+        warn("ck index", "not built", "Semantic search will ask ck to lazily build the index; optionally prewarm with `cd " + root + " && ck --index .`.");
     }
   } else {
     warn("ck CLI", `${ckBin} returned ${r.status}: ${(r.stderr ?? "").slice(0, 120)}`, "Reinstall via `cargo install ck-search`.");

package/dist/plugin.js

@@ -14991,13 +14991,13 @@ function statusFromProbe(explicit, embeddedChunks, indexUpdatedMs, exportMarkerM
   return "fresh";
 }
 function ckIndexWarning(status, root, probeFailure) {
-  const rebuild = `Run 'cd "${root}" && ck --reindex .' (or 'ck --index .') externally; opencode-sessions-explorer will not rebuild embeddings inline.`;
+  const prewarm = `opencode-sessions-explorer will not call ck --index or ck --reindex inline; run 'cd "${root}" && ck --index .' or 'ck --reindex .' only to prewarm or troubleshoot.`;
   if (status === "missing")
-    return `ck semantic index is missing at ${root}/.ck. ${rebuild}`;
+    return `ck semantic index is missing at ${root}/.ck. ck will lazily create or update the index during sem/hybrid search; the first run may be slow. ${prewarm}`;
   if (status === "stale")
-    return `ck semantic index appears stale relative to the export tree; sem/hybrid results may omit recently exported files. ${rebuild}`;
+    return `ck semantic index appears stale relative to the export tree; ck will attempt a lazy refresh during sem/hybrid search. Results may be partial if refresh fails or times out. ${prewarm}`;
   const reason = probeFailure ? ` (${probeFailure})` : "";
-  return `ck semantic index freshness is partial/unverified${reason}; sem/hybrid results may cover only indexed files. ${rebuild}`;
+  return `ck semantic index freshness is partial/unverified${reason}; ck will attempt lazy index refresh during sem/hybrid search. Results may cover only indexed files if refresh fails or times out. ${prewarm}`;
 }
 function exportMarkerMtime(root) {
   const markers = [".last_sync", ".channels_v1_complete"];
@@ -15661,7 +15661,7 @@ var searchSessionsMeta = tool({
 import { existsSync as existsSync9 } from "fs";
 import { join as join9 } from "path";
 var searchText = tool({
-  description: "opencode-sessions-explorer: full-text search across the BODIES of all your prior OpenCode sessions (the actual conversation content \u2014 user prompts, assistant responses, tool inputs/outputs, reasoning, file references, patches, subtask prompts). " + 'Answers any of: "where in my OpenCode history did I mention X", "find sessions about Y", "have I ever discussed Z", "look up earlier conversations about W", "all references to V across my OpenCode sessions", "did this topic come up before", "when did I last talk about Q", "find the session where I worked on R", "search my prior chat content for S", "grep across all OpenCode sessions for T", "have I asked about this before". ' + "Default surface is `recall`: session-first, channel-aware, and evidence-limited. It searches high-signal conversation/session-summary views first and returns ranked sessions with raw part refs. " + "Use `surface:'forensics'` (or explicit channels including `raw`) for exhaustive raw replay over tool output, reasoning, patches, and all exported bodies. " + "ARG `group_by_session`: when true, rolls hits up to one row per session with hit_count, first/last seen timestamps, evidence snippets, and channel counts. If omitted, unscoped recall defaults to true; scoped one-session searches default to flat hits. " + `CRITICAL ARG \`role\` (default 'any'): which message roles to search inside. **Default to 'any'** for natural-language questions like "where did I mention X", "find sessions about Y", "did I discuss Z" \u2014 these are asking about appearances ANYWHERE in your conversations (user prompts AND assistant text AND tool I/O AND reasoning). ` + `Only set role='user' when the user EXPLICITLY narrows to authored messages: "what prompts have I typed containing X", "my user-authored messages mentioning Y", "questions I sent OpenCode with Z". Phrases like "did I mention" / "in my history" / "have I discussed" do NOT imply role='user' \u2014 those are asking about the corpus as a whole. ` + `Only set role='assistant' for questions explicitly about what the AI said ("what has the assistant said about X"). ` + "Modes: 'regex' (default \u2014 drop-in grep, no index needed), 'lex' (BM25 phrase search, auto-builds Tantivy index), 'sem' (semantic embeddings, requires `ck --index .` to be run once outside this tool), 'hybrid' (regex + sem). " + "Pre-filter cross-session searches via session_ids[], project_id, agent, since_ms/until_ms \u2014 unscoped full-corpus search can take 10-30 seconds. Scoped searches return in <1s. " + "For grep INSIDE a single known session use grep-session instead (faster, narrower).",
+  description: "opencode-sessions-explorer: full-text search across the BODIES of all your prior OpenCode sessions (the actual conversation content \u2014 user prompts, assistant responses, tool inputs/outputs, reasoning, file references, patches, subtask prompts). " + 'Answers any of: "where in my OpenCode history did I mention X", "find sessions about Y", "have I ever discussed Z", "look up earlier conversations about W", "all references to V across my OpenCode sessions", "did this topic come up before", "when did I last talk about Q", "find the session where I worked on R", "search my prior chat content for S", "grep across all OpenCode sessions for T", "have I asked about this before". ' + "Default surface is `recall`: session-first, channel-aware, and evidence-limited. It searches high-signal conversation/session-summary views first and returns ranked sessions with raw part refs. " + "Use `surface:'forensics'` (or explicit channels including `raw`) for exhaustive raw replay over tool output, reasoning, patches, and all exported bodies. " + "ARG `group_by_session`: when true, rolls hits up to one row per session with hit_count, first/last seen timestamps, evidence snippets, and channel counts. If omitted, unscoped recall defaults to true; scoped one-session searches default to flat hits. " + `CRITICAL ARG \`role\` (default 'any'): which message roles to search inside. **Default to 'any'** for natural-language questions like "where did I mention X", "find sessions about Y", "did I discuss Z" \u2014 these are asking about appearances ANYWHERE in your conversations (user prompts AND assistant text AND tool I/O AND reasoning). ` + `Only set role='user' when the user EXPLICITLY narrows to authored messages: "what prompts have I typed containing X", "my user-authored messages mentioning Y", "questions I sent OpenCode with Z". Phrases like "did I mention" / "in my history" / "have I discussed" do NOT imply role='user' \u2014 those are asking about the corpus as a whole. ` + `Only set role='assistant' for questions explicitly about what the AI said ("what has the assistant said about X"). ` + "Modes: 'regex' (default \u2014 drop-in grep, no index needed), 'lex' (BM25 phrase search, lets ck auto-build/update its Tantivy index), 'sem' (semantic embeddings, lets ck lazily build/refresh its index), 'hybrid' (regex + sem). " + "Pre-filter cross-session searches via session_ids[], project_id, agent, since_ms/until_ms \u2014 unscoped full-corpus search can take 10-30 seconds. Scoped searches return in <1s. " + "For grep INSIDE a single known session use grep-session instead (faster, narrower).",
   args: {
     q: tool.schema.string().describe("Search query (regex pattern, BM25 phrase, or natural-language depending on mode)"),
     mode: tool.schema.enum(["regex", "lex", "sem", "hybrid"]).default("regex"),
@@ -15709,24 +15709,18 @@ var searchText = tool({
         return groupBySession ? { sessions: table([]), hits_total: 0, mode: args.mode, surface, channels, scope_session_count: scopeIds.length, ck_duration_ms: 0, suppressed: emptySuppressed(channels) } : { hits: table([]), mode: args.mode, scope_session_count: scopeIds.length, ck_duration_ms: 0 };
       }
       let effectiveMode = args.mode;
+      let preSearchFreshness = null;
       if (args.mode === "sem" || args.mode === "hybrid") {
-        const freshness = await ckIndexFreshness(root);
-        ctx.indexStatus = combineExportAndCkStatus(exportStatus, freshness.status);
-        if (freshness.warning)
-          ctx.warnings.push(freshness.warning);
-        if (freshness.status === "missing") {
-          ctx.warnings.push("ck semantic index missing; falling back to regex for this request.");
-          effectiveMode = "regex";
-          ctx.mode = "fallback-regex";
-        } else if (freshness.status !== "fresh") {
-          const chunks = freshness.embedded_chunks != null ? ` (${freshness.embedded_chunks} embedded chunks)` : "";
-          ctx.warnings.push(`ck semantic index status is ${freshness.status}${chunks}; sem/hybrid results are partial until an explicit ck rebuild is run.`);
-        }
+        preSearchFreshness = await ckIndexFreshness(root);
+        ctx.indexStatus = combineExportAndCkStatus(exportStatus, preSearchFreshness.status);
       }
       if (!ctx.mode)
         ctx.mode = effectiveMode;
       const ckTopk = groupBySession ? Math.min(Math.max(args.limit * 20, 100), 500) : Math.min(args.limit * (effectiveMode === "regex" ? 2 : 3), 150);
-      return await runWithCk(args, scopes, effectiveMode, ctx, scopeIds === "all" ? null : scopeIds.length, ckTopk, channels, surface, groupBySession);
+      const result = await runWithCk(args, scopes, effectiveMode, ctx, scopeIds === "all" ? null : scopeIds.length, ckTopk, channels, surface, groupBySession);
+      if (preSearchFreshness)
+        await refreshCkStatusAfterSearch(ctx, root, exportStatus, preSearchFreshness);
+      return result;
     });
   }
 });
@@ -15982,6 +15976,18 @@ function combineExportAndCkStatus(exportStatus, ckStatus) {
     return "stale";
   return ckStatus;
 }
+async function refreshCkStatusAfterSearch(ctx, root, exportStatus, preSearchFreshness) {
+  try {
+    const postSearchFreshness = await ckIndexFreshness(root);
+    ctx.indexStatus = combineExportAndCkStatus(exportStatus, postSearchFreshness.status);
+    if (postSearchFreshness.status !== "fresh") {
+      ctx.warnings.push(postSearchFreshness.warning ?? preSearchFreshness.warning ?? "ck semantic index freshness is not verified after search; results may be partial.");
+    }
+  } catch (e) {
+    ctx.indexStatus = combineExportAndCkStatus(exportStatus, preSearchFreshness.status);
+    ctx.warnings.push(preSearchFreshness.warning ?? `ck semantic index freshness recheck failed after search: ${e.message}`);
+  }
+}
 function warnOnPartialScopeCoverage2(ctx, coverage, timeoutMs) {
   if (!coverage.truncated)
     return;

package/docs/getting-started.md

@@ -54,13 +54,14 @@ history, then branch into the right workflow guide.
    bunx opencode-sessions-explorer-bulk-export
    ```
 
-1. (Optional) Build the semantic index to enable `mode:'sem'` and `mode:'hybrid'`
-   search. This is a slow, one-time pass. Run it in the export root, not in the
-   repository checkout:
+1. (Optional) Prewarm the `ck` index. Normal `mode:'lex'`, `mode:'sem'`, and
+   `mode:'hybrid'` searches let `ck` lazily build or refresh indexes during the
+   search; prewarming only avoids first-search latency or helps troubleshooting.
+   Run it in the export root, not in the repository checkout:
 
    ```bash
    cd ~/.local/share/opencode-sessions-explorer
-   ck --index .  # run in the export root, not the repo root
+   ck --index .  # optional prewarm in the export root
    ```
 
 1. Run the install health probe again and confirm there are no hard failures:

package/docs/guides/export-and-maintenance.md

@@ -54,15 +54,16 @@ maintenance.
    bunx opencode-sessions-explorer-bulk-export --reset
    ```
 
-1. (Optional) Build the semantic index to unlock `sem` and `hybrid` search modes.
-   This is slow and runs outside the plugin. Run it from the export root, not from
-   the repository checkout; use `ck --reindex .` when search warnings report a stale
-   or partially verified index:
+1. (Optional) Prewarm the `ck` index. Normal `lex`, `sem`, and `hybrid` searches
+   invoke `ck` in the requested mode so `ck` can lazily build or refresh indexes
+   during the search. Run these commands only to avoid first-search latency or to
+   troubleshoot stale/partial coverage warnings, and run them from the export root,
+   not from the repository checkout:
 
    ```bash
    cd ~/.local/share/opencode-sessions-explorer
-   ck --index .  # run in the export root, not the repo root
-   ck --reindex .  # explicit rebuild when stale/partial warnings appear
+   ck --index .  # optional prewarm in the export root
+   ck --reindex .  # optional troubleshooting refresh
    ```
 
 1. Verify everything is wired up, and re-run after any OpenCode upgrade:

package/docs/guides/search-and-grep.md

@@ -25,11 +25,12 @@ known session, and audit individual tool invocations by name, status, or substri
 
 `search-text` and `grep-session` shell out to the optional [`ck`](https://github.com/BeaconBay/ck)
 CLI over the filesystem export tree. If `ck` is not installed, both return
-`CK_NOT_FOUND` cleanly; the other 16 tools keep working without it. Semantic modes
-require an embedding index built outside the tool (`ck --index .` or
-`ck --reindex .` from the export root). Missing indexes fall back to `regex`; stale
-or partially verified indexes keep using `sem`/`hybrid` but warn that results may be
-incomplete. The tools never rebuild embeddings inline. See
+`CK_NOT_FOUND` cleanly; the other 16 tools keep working without it. Normal `lex`,
+`sem`, and `hybrid` searches invoke `ck` in that mode so `ck` can lazily build or
+refresh its own indexes during the search. Explicit `ck --index .` or
+`ck --reindex .` runs from the export root are optional prewarm/troubleshooting
+steps, not required before first use. If an index is missing, stale, or partially
+verified, the tools warn that the first/lazy-refresh run may be slow or partial. See
 [search surfaces](../reference/search-surfaces.md) for the surface/channel model.
 
 ## Controls

package/docs/reference/architecture.md

@@ -61,6 +61,9 @@ CLI, which walks the export tree. `ck` supports plain regex with no index, a BM2
 full-text index, and semantic embeddings; the index lives under `.ck/` in the export
 root and is incremental. `ck` is optional: when it is absent these two tools return
 `CK_NOT_FOUND` cleanly and the other 16 tools are unaffected.
+The plugin invokes normal `lex`, `sem`, and `hybrid` `ck` searches and lets `ck`
+perform its lazy index build/refresh; explicit index commands are optional prewarm
+or troubleshooting steps, not a prerequisite for first use.
 
 ### L4 — Enriched Response
 
@@ -89,12 +92,12 @@ flag, so the direct database write is the only mechanism.
 
 ## Examples
 
-Materialize the export tree (L2), then build the optional `ck` index (L3):
+Materialize the export tree (L2), then optionally prewarm the `ck` index (L3):
 
 ```bash
 bunx opencode-sessions-explorer-bulk-export
 cd ~/.local/share/opencode-sessions-explorer
-ck --index .   # run in the export root, not the repository checkout
+ck --index .   # optional prewarm from the export root
 ```
 
 Verify all four layers are healthy:

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-sessions-explorer",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "OpenCode plugin for recall and analysis of past OpenCode sessions: search, grep, and cost/usage insights across your session history via 18 LLM tools (17 read-only plus one write, unarchive-session).",
   "keywords": [
     "opencode",