@javierkaiser/opencode-indexing 0.2.0 → 0.2.1

package/install.mjs

@@ -1,17 +1,32 @@
 #!/usr/bin/env node
 /**
- * Cross-platform installer for opencode-indexing.
+ * Installer for opencode-indexing.
  *
  * Works on Windows, Linux and macOS (Node >= 22.6; Node 26 recommended).
  *
- *   node install.mjs [--skip-deps] [--no-restart]
+ *   node install.mjs [--local|--package] [spec] [--skip-deps] [--no-restart]
+ *   npx @javierkaiser/opencode-indexing
  *
- * What it does:
- *  1. Copies the plugin into <config>/opencode/plugins/opencode-indexing
- *     (config dir honors $XDG_CONFIG_HOME, defaulting to ~/.config).
- *  2. Installs runtime dependencies (ignore + optional lancedb/tree-sitter).
- *  3. Merges tool permissions into <config>/opencode/opencode.json.
- *  4. Restarts the OpenCode service so the plugin loads.
+ * There are two ways to install, because there are two audiences.
+ *
+ *  --local    Copies the plugin into <config>/opencode/plugins/opencode-indexing
+ *             and installs its runtime dependencies there. This is the
+ *             development path: edits to the source take effect on restart,
+ *             with no publish in between.
+ *
+ *  --package  Hands the job to `opencode plugin add`, which installs the
+ *             published package into OpenCode's own cache and records it in the
+ *             global `plugins` array. This is the user-facing path: OpenCode
+ *             owns the install, so `opencode plugin check` and `plugin update`
+ *             work on it.
+ *
+ * The mode is picked from where this file runs. A checkout has `.git` or `test/`
+ * beside it and gets `--local`; anything else — the npx cache, a global install,
+ * an unpacked tarball — gets `--package`. Pass either flag to override, and the
+ * installer says which one it chose and why.
+ *
+ * Both modes write the tool permission rules and restart the service, so either
+ * one leaves a working install.
  */
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
@@ -25,110 +40,44 @@ const skipDeps = has("--skip-deps")
 const noRestart = has("--no-restart")
 
 const source = dirname(fileURLToPath(import.meta.url))
+const sourcePkg = JSON.parse(readFileSync(join(source, "package.json"), "utf8"))
 const configRoot = process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config")
 const configDir = join(configRoot, "opencode")
 const dest = join(configDir, "plugins", "opencode-indexing")
 const configFile = join(configDir, "opencode.json")
 
 const isWindows = process.platform === "win32"
+const opencodeBin = isWindows ? "opencode.cmd" : "opencode"
 const log = (message) => console.log(message)
 const warn = (message) => console.warn(message)
 
-log("Installing opencode-indexing")
-log(`  from: ${source}`)
-log(`  to:   ${dest}`)
-
-// ---------------------------------------------------------------------------
-// 1. Copy plugin files (keep a previously installed node_modules in place)
-// ---------------------------------------------------------------------------
 /**
- * Entries copied into the plugin directory.
+ * Whether this looks like the repository rather than an installed copy.
  *
- * An allowlist rather than a blocklist: a blocklist copied whatever local debris
- * happened to be in the working tree — a stray `test-run.log` was shipped into
- * every install. This mirrors the `files` field in package.json, minus the
- * installers, which are not needed inside an installed plugin.
+ * `.git` and `test/` are both absent from the published tarball, so their
+ * presence means someone is running the installer out of a working tree and
+ * almost certainly wants the source they are editing to be what gets loaded.
  */
-const COPY_ENTRIES = [
-  "index.ts",
-  "tui.ts",
-  "tui",
-  "src",
-  "package.json",
-  "tsconfig.json",
-  "README.md",
-  "LICENSE",
-  "THIRD_PARTY_NOTICES.md",
-]
-
-mkdirSync(dest, { recursive: true })
-for (const entry of readdirSync(dest)) {
-  if (entry === "node_modules") continue
-  rmSync(join(dest, entry), { recursive: true, force: true })
+function looksLikeCheckout() {
+  return existsSync(join(source, ".git")) || existsSync(join(source, "test"))
 }
-for (const entry of COPY_ENTRIES) {
-  const from = join(source, entry)
-  if (!existsSync(from)) {
-    warn(`  skipping missing entry: ${entry}`)
-    continue
-  }
-  cpSync(from, join(dest, entry), { recursive: true })
-}
-log("  files copied")
 
-// ---------------------------------------------------------------------------
-// 2. Minimal runtime package.json + dependency install
-// ---------------------------------------------------------------------------
-const sourcePkg = JSON.parse(readFileSync(join(source, "package.json"), "utf8"))
-const installedPkg = {
-  name: sourcePkg.name,
-  version: sourcePkg.version,
-  type: "module",
-  exports: {
-    ".": "./index.ts",
-    "./rpc": "./src/rpc.ts",
-    "./tui": "./tui.ts",
-  },
-  dependencies: {
-    ignore: ">=7.0.0",
-  },
-  optionalDependencies: {
-    "@lancedb/lancedb": "0.26.2",
-    "web-tree-sitter": "0.25.10",
-    "tree-sitter-wasms": "0.1.13",
-  },
-  // The host (OpenCode TUI) provides the renderer stack; declaring optional
-  // peers documents the contract without forcing a duplicate install.
-  peerDependencies: {
-    "@opencode/theme": ">=2.0.23",
-    "@opentui/core": ">=0.5.14",
-    "@opentui/solid": ">=0.5.14",
-    "solid-js": ">=1.9.12",
-  },
-  peerDependenciesMeta: {
-    "@opencode/theme": { optional: true },
-    "@opentui/core": { optional: true },
-    "@opentui/solid": { optional: true },
-    "solid-js": { optional: true },
-  },
-}
-writeFileSync(join(dest, "package.json"), JSON.stringify(installedPkg, null, 2) + "\n", "utf8")
+const mode = has("--local") ? "local" : has("--package") ? "package" : looksLikeCheckout() ? "local" : "package"
+const reason = has("--local") || has("--package") ? "requested" : looksLikeCheckout() ? "a checkout" : "an installed copy"
 
-if (!skipDeps) {
-  log("  installing runtime deps (ignore + optional lancedb/tree-sitter)...")
-  const npm = isWindows ? "npm.cmd" : "npm"
-  const result = spawnSync(
-    npm,
-    ["install", "--omit=dev", "--omit=peer", "--no-audit", "--no-fund", "--loglevel=error"],
-    { cwd: dest, stdio: "inherit", shell: isWindows },
-  )
-  if (result.error || result.status !== 0) {
-    warn(`  dependency install failed (${result.error?.message ?? `exit ${result.status}`}); the plugin still runs with reduced features`)
-  }
-}
+// A positional argument is the package spec for --package. `@latest` rather than
+// the version this file was published as, because an exact version is skipped by
+// `opencode plugin check` and `plugin update`: pinning would silently opt the
+// install out of the update path OpenCode provides.
+const positional = argv.filter((arg) => !arg.startsWith("-"))
+const spec = positional[0] ?? `${sourcePkg.name}@latest`
+
+log(`Installing ${sourcePkg.name} ${sourcePkg.version}`)
+log(`  from: ${source}`)
+log(`  mode: ${mode} (${reason})`)
 
 // ---------------------------------------------------------------------------
-// 3. Merge tool permissions into opencode.json (JSONC tolerant)
+// Tool permissions (both modes)
 // ---------------------------------------------------------------------------
 function stripJsonc(input) {
   // Strip a UTF-8 BOM: editors on Windows may add one and JSON.parse rejects it.
@@ -189,51 +138,203 @@ const TOOLS = ["indexing_search", "indexing_status", "indexing_config", "indexin
 // Everything else only reads. This one writes the settings file, so the host
 // asks the user before it runs instead of taking it on trust.
 const ASK_BEFORE_RUN = new Set(["indexing_config_set"])
-try {
-  let cfg = {}
-  if (existsSync(configFile)) {
-    cfg = JSON.parse(stripJsonc(readFileSync(configFile, "utf8")))
-    if (typeof cfg !== "object" || cfg === null || Array.isArray(cfg)) cfg = {}
-  }
 
-  // Drop the V1 entries this installer used to write. Anything else the user
-  // put there is left untouched.
-  if (cfg.permission && typeof cfg.permission === "object" && !Array.isArray(cfg.permission)) {
-    for (const tool of TOOLS) delete cfg.permission[tool]
-    if (Object.keys(cfg.permission).length === 0) delete cfg.permission
-  }
+/**
+ * Add one permission rule per tool to the global config.
+ *
+ * `opencode plugin add` installs the plugin but knows nothing about its tools,
+ * so a package-mode install has to write these itself or the `ask` gate on
+ * `indexing_config_set` is lost. The read tools would be allowed by the base
+ * `{ "*": "allow" }` policy anyway; they are written out so the set is visible
+ * and can be tightened in one place.
+ */
+function writePermissions() {
+  try {
+    let cfg = {}
+    if (existsSync(configFile)) {
+      cfg = JSON.parse(stripJsonc(readFileSync(configFile, "utf8")))
+      if (typeof cfg !== "object" || cfg === null || Array.isArray(cfg)) cfg = {}
+    }
 
-  if (!Array.isArray(cfg.permissions)) cfg.permissions = []
-  for (const tool of TOOLS) {
-    const effect = ASK_BEFORE_RUN.has(tool) ? "ask" : "allow"
-    const rule = cfg.permissions.find((entry) => entry && entry.action === tool)
-    if (rule) {
-      rule.resource = "*"
-      rule.effect = effect
-    } else {
-      cfg.permissions.push({ action: tool, resource: "*", effect })
+    // Drop the V1 entries this installer used to write. Anything else the user
+    // put there is left untouched.
+    if (cfg.permission && typeof cfg.permission === "object" && !Array.isArray(cfg.permission)) {
+      for (const tool of TOOLS) delete cfg.permission[tool]
+      if (Object.keys(cfg.permission).length === 0) delete cfg.permission
     }
-  }
 
-  mkdirSync(configDir, { recursive: true })
-  writeFileSync(configFile, JSON.stringify(cfg, null, 2) + "\n", "utf8")
-  log(`  permissions added to ${configFile}`)
-} catch (error) {
-  warn(`  could not update ${configFile}: ${error instanceof Error ? error.message : String(error)}`)
+    if (!Array.isArray(cfg.permissions)) cfg.permissions = []
+    for (const tool of TOOLS) {
+      const effect = ASK_BEFORE_RUN.has(tool) ? "ask" : "allow"
+      const rule = cfg.permissions.find((entry) => entry && entry.action === tool)
+      if (rule) {
+        rule.resource = "*"
+        rule.effect = effect
+      } else {
+        cfg.permissions.push({ action: tool, resource: "*", effect })
+      }
+    }
+
+    mkdirSync(configDir, { recursive: true })
+    writeFileSync(configFile, JSON.stringify(cfg, null, 2) + "\n", "utf8")
+    log(`  permissions added to ${configFile}`)
+  } catch (error) {
+    warn(`  could not update ${configFile}: ${error instanceof Error ? error.message : String(error)}`)
+  }
 }
 
 // ---------------------------------------------------------------------------
-// 4. Restart the OpenCode service so the plugin loads
+// Service restart (both modes)
 // ---------------------------------------------------------------------------
-if (!noRestart) {
+function restartService() {
+  if (noRestart) return
   log("  restarting OpenCode service...")
-  const opencode = isWindows ? "opencode.cmd" : "opencode"
-  const result = spawnSync(opencode, ["service", "restart"], { stdio: "inherit", shell: isWindows })
+  const result = spawnSync(opencodeBin, ["service", "restart"], { stdio: "inherit", shell: isWindows })
   if (result.error || result.status !== 0) {
     warn("  could not restart automatically. Run: opencode service restart")
   }
 }
 
+// ---------------------------------------------------------------------------
+// Local mode: copy the working tree into the config directory
+// ---------------------------------------------------------------------------
+/**
+ * Entries copied into the plugin directory.
+ *
+ * An allowlist rather than a blocklist: a blocklist copied whatever local debris
+ * happened to be in the working tree — a stray `test-run.log` was shipped into
+ * every install. This mirrors the `files` field in package.json, minus the
+ * installers, which are not needed inside an installed plugin.
+ */
+const COPY_ENTRIES = [
+  "index.ts",
+  "tui.ts",
+  "tui",
+  "src",
+  "package.json",
+  "tsconfig.json",
+  "README.md",
+  "LICENSE",
+  "THIRD_PARTY_NOTICES.md",
+]
+
+function installLocal() {
+  log(`  to:   ${dest}`)
+  mkdirSync(dest, { recursive: true })
+  for (const entry of readdirSync(dest)) {
+    if (entry === "node_modules") continue
+    rmSync(join(dest, entry), { recursive: true, force: true })
+  }
+  for (const entry of COPY_ENTRIES) {
+    const from = join(source, entry)
+    if (!existsSync(from)) {
+      warn(`  skipping missing entry: ${entry}`)
+      continue
+    }
+    cpSync(from, join(dest, entry), { recursive: true })
+  }
+  log("  files copied")
+
+  // The installed package.json is derived, never hand-written: the list this
+  // used to keep in parallel is how `apache-arrow` came to be declared for the
+  // installer and missing from the published package, which broke every Kilo
+  // LanceDB import for one of the two install paths and not the other.
+  const installedPkg = {
+    name: sourcePkg.name,
+    version: sourcePkg.version,
+    type: "module",
+    exports: sourcePkg.exports,
+    dependencies: sourcePkg.dependencies,
+    optionalDependencies: sourcePkg.optionalDependencies,
+    peerDependencies: sourcePkg.peerDependencies,
+    peerDependenciesMeta: sourcePkg.peerDependenciesMeta,
+  }
+  writeFileSync(join(dest, "package.json"), JSON.stringify(installedPkg, null, 2) + "\n", "utf8")
+
+  if (skipDeps) {
+    log("  skipping dependency install (--skip-deps)")
+    return
+  }
+
+  log("  installing runtime deps (ignore + optional lancedb/tree-sitter)...")
+  const npm = isWindows ? "npm.cmd" : "npm"
+  // --omit=peer is why apache-arrow has to be a real dependency above: the
+  // native LanceDB binary loads without it and throws on first use.
+  const result = spawnSync(
+    npm,
+    ["install", "--omit=dev", "--omit=peer", "--no-audit", "--no-fund", "--loglevel=error"],
+    { cwd: dest, stdio: "inherit", shell: isWindows },
+  )
+  if (result.error || result.status !== 0) {
+    warn(`  dependency install failed (${result.error?.message ?? `exit ${result.status}`}); the plugin still runs with reduced features`)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Package mode: let OpenCode own the install
+// ---------------------------------------------------------------------------
+/** How many entries `opencode plugin list` reports for this plugin. */
+function registeredCount() {
+  const result = spawnSync(opencodeBin, ["plugin", "list"], { encoding: "utf8", shell: isWindows })
+  if (result.error || result.status !== 0 || typeof result.stdout !== "string") return undefined
+  // `plugin list` prints a table: `ID  VERSION  SOURCE`. Compare the first
+  // column exactly rather than by prefix, so a longer id that happens to start
+  // the same way is not counted as this plugin.
+  return result.stdout
+    .split("\n")
+    .map((line) => line.trim().split(/\s+/)[0])
+    .filter((id) => id === "opencode.indexing").length
+}
+
+function installPackage() {
+  log(`  spec: ${spec}`)
+
+  const added = spawnSync(opencodeBin, ["plugin", "add", spec], { stdio: "inherit", shell: isWindows })
+  if (added.error || added.status !== 0) {
+    // Nothing has been removed at this point, so a failure here leaves the
+    // previous install exactly as it was.
+    warn(`  \`opencode plugin add\` failed (${added.error?.message ?? `exit ${added.status}`}); the previous install was left untouched`)
+    return false
+  }
+
+  // Remove the copied plugin *after* the package is in place. Both sources
+  // define `id: "opencode.indexing"`, and the config directory is scanned
+  // automatically, so leaving the copy behind would load the plugin twice.
+  if (existsSync(dest)) {
+    rmSync(dest, { recursive: true, force: true })
+    log(`  removed the copied plugin at ${dest} (it would load twice)`)
+  }
+
+  return true
+}
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+if (mode === "local") {
+  installLocal()
+} else if (!installPackage()) {
+  warn("  not writing permissions or restarting: the install did not complete")
+  process.exit(1)
+}
+
+writePermissions()
+// Before the count below, not after: `plugin list` asks the running service,
+// which still holds the configuration from before this install.
+restartService()
+
+if (mode === "package") {
+  const count = registeredCount()
+  if (count !== undefined && count > 1) {
+    warn(`  ${count} entries report id opencode.indexing; only one should. Check \`opencode plugin list\`.`)
+  }
+}
+
 log("Done.")
-log("Verify with: opencode api get /api/info")
-log("Then run in a session: indexing_status  (or /indexing-config in any client)")
+if (mode === "package") {
+  log("Update with: opencode plugin update")
+  log("Remove with: opencode plugin remove " + spec)
+} else {
+  log("Verify with: opencode api get /api/info")
+  log("Then run in a session: indexing_status  (or /indexing-config in any client)")
+}

package/install.ps1

@@ -3,8 +3,11 @@
 # and macOS all run the same code instead of drifting copies.
 #
 # Usage:
-#   powershell -ExecutionPolicy Bypass -File install.ps1 [-SkipDeps] [-NoRestart]
+#   powershell -ExecutionPolicy Bypass -File install.ps1 [-Local|-Package] [-Spec <spec>] [-SkipDeps] [-NoRestart]
 param(
+  [switch]$Local,
+  [switch]$Package,
+  [string]$Spec,
   [switch]$SkipDeps,
   [switch]$NoRestart
 )
@@ -12,6 +15,9 @@ param(
 $ErrorActionPreference = "Stop"
 $script = Join-Path $PSScriptRoot "install.mjs"
 $forward = @()
+if ($Local) { $forward += "--local" }
+if ($Package) { $forward += "--package" }
+if ($Spec) { $forward += $Spec }
 if ($SkipDeps) { $forward += "--skip-deps" }
 if ($NoRestart) { $forward += "--no-restart" }
 

package/install.sh

@@ -3,7 +3,7 @@
 # Thin wrapper: the cross-platform logic lives in install.mjs.
 #
 # Usage:
-#   sh install.sh [--skip-deps] [--no-restart]
+#   sh install.sh [--local|--package] [spec] [--skip-deps] [--no-restart]
 set -eu
 
 dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@javierkaiser/opencode-indexing",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "OpenCode plugin: semantic code search that reuses Kilo Code indexes (Qdrant/LanceDB) and maintains its own independent index",
   "license": "MIT",
   "author": "Carlos Javier Lust <javierkaiser@gmail.com>",
@@ -29,6 +29,9 @@
     "./rpc": "./src/rpc.ts",
     "./tui": "./tui.ts"
   },
+  "bin": {
+    "opencode-indexing": "./install.mjs"
+  },
   "files": [
     "index.ts",
     "tui.ts",
@@ -61,7 +64,8 @@
   "optionalDependencies": {
     "@lancedb/lancedb": "0.26.2",
     "tree-sitter-wasms": "0.1.13",
-    "web-tree-sitter": "0.25.10"
+    "web-tree-sitter": "0.25.10",
+    "apache-arrow": "18.1.0"
   },
   "devDependencies": {
     "@opencode/plugin": "2.0.23",

package/src/import.ts

@@ -6,6 +6,7 @@ import { getKiloStoreInfo, resolveKiloCollection } from "./kilo-store.ts"
 import { readLanceDbInfoAt, readLanceDbBatch, lanceDbName } from "./lancedb-store.ts"
 import { kiloLanceDbDirectory } from "./settings.ts"
 import { recordWorkspace } from "./workspaces.ts"
+import { describeError } from "./errors.ts"
 import type { EmbeddingProfile, QdrantPoint, IndexReport } from "./types.ts"
 import type { VectorStoreAdapter } from "./vector-store.ts"
 import { profileKey } from "./registry.ts"
@@ -47,9 +48,25 @@ export interface ImportReport {
 /** Read-only description of Kilo sources available for a workspace. */
 export async function discoverKiloSources(
   root: string,
-  options: { qdrant?: Qdrant; lancedbDirectory?: string; homeDir?: string; targetProfile?: EmbeddingProfile },
+  options: {
+    qdrant?: Qdrant
+    lancedbDirectory?: string
+    homeDir?: string
+    targetProfile?: EmbeddingProfile
+    /**
+     * Called when a source exists but could not be read.
+     *
+     * A backend that is down and a source that does not exist look identical
+     * once the error is swallowed, and both are reported to the user as "no Kilo
+     * index found". That is a wrong answer in the first case: the index is
+     * sitting on disk, and what is missing is a native module or a running
+     * server. The caller decides where the message surfaces.
+     */
+    onProblem?: (message: string) => void
+  },
 ): Promise<KiloSourceInfo[]> {
   const sources: KiloSourceInfo[] = []
+  const problem = options.onProblem ?? ((): void => {})
   const isCompatible = (profile?: EmbeddingProfile): boolean => {
     if (!options.targetProfile || !profile) return true
     return profileKey(profile) === profileKey(options.targetProfile)
@@ -71,15 +88,17 @@ export async function discoverKiloSources(
         compatible: isCompatible(info.profile),
       })
     }
-  } catch {
-    // Qdrant unreachable: skip silently; lancedb may still be available.
+  } catch (error) {
+    // A backend that answers with no matching collection is not a failure; a
+    // backend that never answered is.
+    problem(`Could not reach the Qdrant server to look for a Kilo index: ${describeError(error)}`)
   }
 
   // LanceDB source
-  try {
-    const directory = options.lancedbDirectory ?? kiloLanceDbDirectory(options.homeDir)
-    const dbPath = path.join(directory, lanceDbName(root))
-    if (fs.existsSync(dbPath)) {
+  const directory = options.lancedbDirectory ?? kiloLanceDbDirectory(options.homeDir)
+  const dbPath = path.join(directory, lanceDbName(root))
+  if (fs.existsSync(dbPath)) {
+    try {
       const info = await readLanceDbInfoAt(dbPath)
       if (info.vectorExists) {
         sources.push({
@@ -92,9 +111,11 @@ export async function discoverKiloSources(
           compatible: isCompatible(info.profile),
         })
       }
+    } catch (error) {
+      // The directory is there, so this is "found but unreadable", never
+      // "not indexed". Say so, with the reason.
+      problem(`A Kilo LanceDB index exists at ${dbPath} but could not be read: ${describeError(error)}`)
     }
-  } catch {
-    // LanceDB unavailable: skip.
   }
 
   return sources

package/src/indexer.ts

@@ -157,10 +157,15 @@ export async function runIndex(deps: IndexerDeps, options: IndexOptions): Promis
   if (shouldImport) {
     await deps.onProgress?.({ phase: "importing", processed: 0, total: 0 })
     try {
+      // Collected rather than thrown: discovery no longer fails on an
+      // unreadable source, and the caller has to be told why the scan below is
+      // about to re-embed the whole workspace at their expense.
+      const problems: string[] = []
       const sources = await discoverKiloSources(root, {
         qdrant,
         homeDir: undefined,
         targetProfile: profile,
+        onProblem: (message) => problems.push(message),
       })
       const source = sources.find((item) => item.compatible) ?? sources[0]
       if (source && source.compatible) {
@@ -190,6 +195,12 @@ export async function runIndex(deps: IndexerDeps, options: IndexOptions): Promis
         report.errors.push(
           `Kilo index found (${source.name}) but its embedding profile does not match ${profile.provider}:${profile.modelId}:${profile.dimension}; indexing from scratch`,
         )
+      } else if (problems.length > 0) {
+        // No usable source and a reason why. Without this the build reads as a
+        // workspace that has no Kilo index at all, and the full re-embedding
+        // that follows looks like the normal path rather than the expensive
+        // fallback it is.
+        report.errors.push(`${problems.join(" · ")} Indexing from scratch instead.`)
       }
     } catch (error) {
       report.errors.push(`import failed: ${describeError(error)}`)

package/src/rpc.ts

@@ -19,6 +19,20 @@ const empty = { type: "object", properties: {}, additionalProperties: false } as
  */
 const directoryShape = { directory: { type: "string" } } as const
 
+/**
+ * Input schema for a method whose only argument is the caller's workspace.
+ *
+ * Exists so `kilo.discover` and `settings.test` cannot be written as a bare
+ * `directoryShape`: that is a fragment of `properties`, not a schema, and a
+ * validator reading it as one sees no `directory` at all — silently answering
+ * about the service's own workspace again.
+ */
+const workspaceInputShape = {
+  type: "object",
+  properties: { ...directoryShape },
+  additionalProperties: false,
+} as const
+
 const settingsShape = {
   type: "object",
   properties: {
@@ -62,6 +76,9 @@ export const IndexingRpc = {
         type: "object",
         properties: {
           target: { type: "string", enum: ["qdrant", "lancedb", "provider", "kilo"] },
+          // Only `kilo` is workspace-scoped; the other targets describe global
+          // backends. Sending it costs nothing and keeps one shape for the client.
+          ...directoryShape,
         },
         required: ["target"],
         additionalProperties: false,
@@ -74,7 +91,7 @@ export const IndexingRpc = {
       },
     },
     "kilo.discover": {
-      input: empty,
+      input: workspaceInputShape,
       output: {
         type: "object",
         properties: {
@@ -94,6 +111,14 @@ export const IndexingRpc = {
               additionalProperties: true,
             },
           },
+          /**
+           * Sources that exist but could not be read, in plain language.
+           *
+           * Without this the only thing a caller can say when the list is empty
+           * is "not found", which is a different statement from "found, and the
+           * read failed" — and the second one is the one that needs acting on.
+           */
+          problems: { type: "array", items: { type: "string" } },
         },
         required: ["sources"],
         additionalProperties: false,

package/src/status.ts

@@ -93,11 +93,19 @@ export async function getStatus(deps: StatusDeps, options?: { checkFreshness?: b
     settings.dimension > 0
       ? { provider: settings.provider, modelId: settings.modelId, dimension: settings.dimension }
       : undefined
+  // Discovery problems are collected here rather than thrown away, so `indexing_status`
+  // can say "found but unreadable" instead of the much less useful "nothing there".
+  const kiloProblems: string[] = []
   const [kiloInfo, ownInfo, manifest, kiloSources] = await Promise.all([
     kiloCollection ? getKiloStoreInfo(qdrant, kiloCollection).catch(() => null) : null,
     ownStore.info().catch(() => null),
     loadManifest(kv, root),
-    discoverKiloSources(root, { qdrant, homeDir: undefined, targetProfile }).catch(() => [] as KiloSourceInfo[]),
+    discoverKiloSources(root, {
+      qdrant,
+      homeDir: undefined,
+      targetProfile,
+      onProblem: (message) => kiloProblems.push(message),
+    }).catch(() => [] as KiloSourceInfo[]),
   ])
 
   const freshness = { checked: false, total: 0, added: 0, maybeStale: 0, deleted: 0 }
@@ -204,6 +212,10 @@ export async function getStatus(deps: StatusDeps, options?: { checkFreshness?: b
     },
     freshness,
     recommendation,
-    warnings,
+    // Discovery problems ride along as warnings because that is the list
+    // `indexing_status` already renders, so they surface without a field of
+    // their own. It is the only consumer: the footer reads point counts and
+    // `ownStoreReachable`, and never looks at warnings.
+    warnings: [...warnings, ...kiloProblems],
   }
 }