@dikolab/kbdb 0.3.2 → 0.4.1

package/dist/cli.mjs

@@ -1,11 +1,20 @@
 import {
   computeSha256,
+  configureLog,
   detectRuntime,
   getArgs,
   getIpcPath,
+  log,
+  parseLogLevel,
+  parseWorkerToml,
   resolveBaseDir,
+  resolveLogLevel,
   resolveWorkerScript
-} from "./chunk-JG2UCKLI.mjs";
+} from "./chunk-BJXEVALU.mjs";
+
+// src/cli.ts
+import { readFileSync as readFileSync4 } from "node:fs";
+import { join as join9 } from "node:path";
 
 // src/shared/cli/constants/defaults.constant.ts
 var DEFAULT_LIMIT = 20;
@@ -41,19 +50,31 @@ function parseArgs(argv) {
         }
         return options;
       case "--version":
-      case "-v":
         options.command = "version";
         return options;
+      case "-v":
+      case "--verbose": {
+        const next = argv[i + 1];
+        if (next && !next.startsWith("-")) {
+          options.logLevel = parseLogLevel(next);
+          i++;
+        } else {
+          options.logLevel = 2 /* WARNING */;
+        }
+        break;
+      }
+      case "-vv":
+      case "--verbose-info":
+        options.logLevel = 1 /* INFO */;
+        break;
+      case "-vvv":
+      case "--verbose-debug":
+        options.logLevel = 0 /* DEBUG */;
+        break;
       case "--init":
-        console.error(
-          'warning: --init is deprecated, use "kbdb db init"'
-        );
         options.command = "init";
         break;
       case "--migrate":
-        console.error(
-          'warning: --migrate is deprecated, use "kbdb db migrate"'
-        );
         options.command = "migrate";
         break;
       case "--db":
@@ -62,6 +83,7 @@ function parseArgs(argv) {
       case "--format":
       case "-f":
         options.format = argv[++i] ?? DEFAULT_FORMAT;
+        options.formatExplicit = true;
         break;
       case "--mode":
       case "-m":
@@ -119,10 +141,31 @@ function parseArgs(argv) {
       case "-c":
         options.content = true;
         break;
+      case "--relaxed":
+        options.relaxed = true;
+        break;
+      case "--from":
+        options.from = argv[++i];
+        break;
+      case "--dry-run":
+        options.dryRun = true;
+        break;
+      case "--export-format":
+        options.exportFormat = argv[++i] ?? "git";
+        break;
+      case "--timeout-ms":
+        options.timeoutMs = parseInt(argv[++i] ?? "", 10) || void 0;
+        break;
+      case "--retry":
+        options.retry = parseInt(argv[++i] ?? "", 10) || void 0;
+        break;
+      case "--non-interactive":
+        options.nonInteractive = true;
+        break;
       default:
         if (!options.command) {
           options.command = arg;
-        } else if (!options.args.length && (options.command === "db" || options.command === "skill" || options.command === "agent")) {
+        } else if (!options.args.length && (options.command === "db" || options.command === "skill" || options.command === "agent" || options.command === "worker")) {
           options.command = `${options.command}-${arg}`;
         } else {
           options.args.push(arg);
@@ -195,6 +238,7 @@ function formatMcp(paged) {
 
 // src/shared/cli/functions/run-search.function.ts
 async function runSearch(client, options) {
+  log("searching: " + options.args.join(" "), 0 /* DEBUG */);
   const query = options.args.join(" ").trim();
   if (!query) {
     return {
@@ -211,8 +255,13 @@ async function runSearch(client, options) {
     mode: options.mode,
     limit: options.limit,
     offset: options.offset,
-    algo: options.algo
+    algo: options.algo,
+    relaxed: options.relaxed
   });
+  log(
+    "search returned " + results.total.toString() + " results",
+    0 /* DEBUG */
+  );
   return {
     items: results.items.map((r) => ({
       kbid: r.kbid,
@@ -231,13 +280,41 @@ async function runSearch(client, options) {
     offset: results.offset,
     limit: results.limit,
     has_more: results.has_more,
-    relaxed: results.relaxed ?? false
+    relaxed: results.relaxed ?? false,
+    elapsed_ms: results.elapsed_ms,
+    search_mode: results.search_mode,
+    retrieval_method: results.retrieval_method
   };
 }
 
+// src/shared/cli/functions/resolve-kbid-prefix.function.ts
+var SECTION_TYPES = ["text", "code", "image"];
+async function resolveKbidPrefix(prefix, client) {
+  if (prefix.length >= 26) return prefix;
+  const seen = /* @__PURE__ */ new Set();
+  for (const type of SECTION_TYPES) {
+    const records = await client.listByType(type);
+    for (const r of records) {
+      if (r.kbid.startsWith(prefix)) seen.add(r.kbid);
+    }
+  }
+  if (seen.size === 0) {
+    const msg = `no section matches prefix "${prefix}"`;
+    log(msg, 3 /* ERROR */);
+    throw new Error(msg);
+  }
+  if (seen.size > 1) {
+    const msg = `ambiguous prefix "${prefix}": ${seen.size.toString()} matches`;
+    log(msg, 3 /* ERROR */);
+    throw new Error(msg);
+  }
+  return [...seen][0];
+}
+
 // src/shared/cli/functions/run-recall.function.ts
 var MAX_RECALL_DEPTH = 3;
 async function runRecall(client, options) {
+  log("running recall", 0 /* DEBUG */);
   if (options.args.length === 0) {
     return { error: "no kbid provided" };
   }
@@ -245,14 +322,18 @@ async function runRecall(client, options) {
     MAX_RECALL_DEPTH,
     Math.max(0, options.depth ?? 0)
   );
-  if (options.args.length === 1) {
-    return client.recall({ kbid: options.args[0], depth });
+  const resolved = await Promise.all(
+    options.args.map((a) => resolveKbidPrefix(a, client))
+  );
+  if (resolved.length === 1) {
+    return client.recall({ kbid: resolved[0], depth });
   }
-  return client.recall({ kbids: options.args, depth });
+  return client.recall({ kbids: resolved, depth });
 }
 
 // src/shared/cli/functions/run-export.function.ts
 async function runExport(client, options) {
+  log("running export", 0 /* DEBUG */);
   const path = options.args[0];
   return client.export({ path });
 }
@@ -261,6 +342,10 @@ async function runExport(client, options) {
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, extname, join } from "node:path";
 async function runLearn(client, options, io) {
+  log(
+    "learning " + options.args.length.toString() + " targets",
+    0 /* DEBUG */
+  );
   const results = [];
   let stdinConsumed = false;
   const readStdin = io?.readStdin ?? readProcessStdin;
@@ -299,6 +384,10 @@ async function runLearn(client, options, io) {
       );
     }
   }
+  log(
+    "learned " + results.length.toString() + " sections",
+    0 /* DEBUG */
+  );
   return results;
 }
 function mapAddSectionResult(result, path, size) {
@@ -362,8 +451,10 @@ function isSupportedFile(path) {
 
 // src/shared/cli/functions/run-unlearn.function.ts
 async function runUnlearn(client, options) {
+  log("running unlearn", 0 /* DEBUG */);
   const results = [];
-  for (const kbid of options.args) {
+  for (const arg of options.args) {
+    const kbid = await resolveKbidPrefix(arg, client);
     const result = await client.removeSection(kbid);
     results.push({ kbid, removed: result.removed });
   }
@@ -372,7 +463,11 @@ async function runUnlearn(client, options) {
 
 // src/shared/cli/functions/run-content.function.ts
 async function runContent(client, options) {
-  return client.content(options.args);
+  log("running content", 0 /* DEBUG */);
+  const resolved = await Promise.all(
+    options.args.map((a) => resolveKbidPrefix(a, client))
+  );
+  return client.content(resolved);
 }
 
 // src/shared/cli/functions/run-check.function.ts
@@ -386,6 +481,7 @@ function parseDivergentContent(encoded) {
   }).filter((entry) => entry.kbids.length > 0);
 }
 async function runCheck(client, _options) {
+  log("running check", 0 /* DEBUG */);
   const raw = await client.integrityCheck();
   return {
     ok: raw.ok,
@@ -400,21 +496,34 @@ async function runCheck(client, _options) {
 
 // src/shared/cli/functions/run-gc.function.ts
 async function runGc(client, _options) {
+  log("running gc", 0 /* DEBUG */);
   return client.gc();
 }
 
 // src/shared/cli/functions/run-rebuild.function.ts
 async function runRebuild(client, _options) {
+  log("running rebuild", 0 /* DEBUG */);
   return client.rebuildIndexes();
 }
 
 // src/shared/cli/functions/find-db.function.ts
 import { existsSync } from "node:fs";
-import { join as join2, resolve } from "node:path";
+import { dirname, join as join2, resolve } from "node:path";
 function findDb(dbPath) {
-  const base = dbPath ? resolve(dbPath) : process.cwd();
-  const kbdbDir = join2(base, ".kbdb");
-  return existsSync(kbdbDir) ? kbdbDir : null;
+  if (dbPath) {
+    const target = join2(resolve(dbPath), ".kbdb");
+    return existsSync(target) ? target : null;
+  }
+  let current = process.cwd();
+  let parent = dirname(current);
+  while (parent !== current) {
+    const candidate2 = join2(current, ".kbdb");
+    if (existsSync(candidate2)) return candidate2;
+    current = parent;
+    parent = dirname(current);
+  }
+  const candidate = join2(current, ".kbdb");
+  return existsSync(candidate) ? candidate : null;
 }
 
 // src/shared/cli/functions/run-init.function.ts
@@ -549,6 +658,7 @@ function createScaffold(dbDir) {
   writeFileSync2(join4(dbDir, ".gitignore"), GITIGNORE);
 }
 function runInit(options) {
+  log("running init", 0 /* DEBUG */);
   const basePath = options.dbPath ? resolve2(options.dbPath) : process.cwd();
   const dbDir = join4(basePath, ".kbdb");
   try {
@@ -600,11 +710,13 @@ function askReadline(question) {
 
 // src/shared/cli/functions/run-status.function.ts
 async function runStatus(client, _options) {
+  log("running status", 0 /* DEBUG */);
   return client.dbStatus();
 }
 
 // src/shared/cli/functions/run-db-init.function.ts
 function runDbInit(options, runInitFn) {
+  log("running db-init", 0 /* DEBUG */);
   const result = runInitFn(options);
   if (result.ok) {
     return {
@@ -624,6 +736,7 @@ function runDbInit(options, runInitFn) {
 
 // src/shared/cli/functions/run-db-migrate.function.ts
 async function runDbMigrate(client, options) {
+  log("running db-migrate", 0 /* DEBUG */);
   const dbPath = options.dbPath ?? process.cwd();
   return client.migrateDatabase(dbPath);
 }
@@ -651,6 +764,7 @@ function serializeSkillContent(skill) {
 
 // src/shared/cli/functions/run-skill-learn.function.ts
 async function runSkillLearn(client, options) {
+  log("running skill-learn", 0 /* DEBUG */);
   const name = options.name;
   if (!name) {
     return { error: "--name is required", exitCode: 1 };
@@ -681,6 +795,7 @@ async function runSkillLearn(client, options) {
 
 // src/shared/cli/functions/run-skill-list.function.ts
 async function runSkillList(client, _options) {
+  log("running skill-list", 0 /* DEBUG */);
   const records = await client.listByType("skill");
   const items = records.map((r) => {
     let argumentCount = 0;
@@ -708,9 +823,11 @@ async function runSkillList(client, _options) {
 function parseSkillContent(json) {
   const raw = JSON.parse(json);
   if (typeof raw["name"] !== "string" || !raw["name"]) {
+    log("skill name is required", 3 /* ERROR */);
     throw new Error("skill name is required");
   }
   if (typeof raw["body"] !== "string") {
+    log("skill body is required", 3 /* ERROR */);
     throw new Error("skill body is required");
   }
   return {
@@ -723,6 +840,7 @@ function parseSkillContent(json) {
 
 // src/shared/cli/functions/run-skill-get.function.ts
 async function runSkillGet(client, options) {
+  log("running skill-get", 0 /* DEBUG */);
   const identifier = options.args[0] ?? options.name;
   if (!identifier) {
     return {
@@ -759,6 +877,7 @@ async function runSkillGet(client, options) {
 
 // src/shared/cli/functions/run-skill-delete.function.ts
 async function runSkillDelete(client, options) {
+  log("running skill-delete", 0 /* DEBUG */);
   const kbid = options.args[0];
   if (!kbid) {
     return { error: "kbid is required", exitCode: 1 };
@@ -776,6 +895,7 @@ async function runSkillDelete(client, options) {
 
 // src/shared/cli/functions/run-agent-create.function.ts
 async function runAgentCreate(client, options) {
+  log("running agent-create", 0 /* DEBUG */);
   const name = options.name;
   if (!name) {
     return { error: "--name is required", exitCode: 1 };
@@ -821,6 +941,7 @@ async function runAgentCreate(client, options) {
 
 // src/shared/cli/functions/run-agent-list.function.ts
 async function runAgentList(client, _options) {
+  log("running agent-list", 0 /* DEBUG */);
   const docs = await client.listDocumentsByType("agent");
   const items = docs.map((d) => ({
     docid: d.docid,
@@ -877,6 +998,7 @@ async function resolveSkills(client, skillRefs) {
   });
 }
 async function runAgentGet(client, options) {
+  log("running agent-get", 0 /* DEBUG */);
   const docid = options.args[0];
   if (!docid) {
     return { error: "docid is required", exitCode: 1 };
@@ -898,6 +1020,7 @@ async function runAgentGet(client, options) {
 
 // src/shared/cli/functions/run-agent-delete.function.ts
 async function runAgentDelete(client, options) {
+  log("running agent-delete", 0 /* DEBUG */);
   const docid = options.args[0];
   if (!docid) {
     return { error: "docid is required", exitCode: 1 };
@@ -909,8 +1032,23 @@ async function runAgentDelete(client, options) {
   };
 }
 
+// src/shared/cli/functions/run-import.function.ts
+async function runImport(client, options) {
+  const from = options.from;
+  if (!from) {
+    const msg = "import requires --from <path>";
+    log(msg, 3 /* ERROR */);
+    throw new Error(msg);
+  }
+  return client.import({
+    from,
+    dryRun: options.dryRun === true
+  });
+}
+
 // src/shared/cli/functions/dispatch-command.function.ts
 async function dispatchCommand(client, options, io) {
+  log("dispatching command: " + options.command, 0 /* DEBUG */);
   switch (options.command) {
     case "learn":
       return handleLearn(client, options, io);
@@ -932,6 +1070,8 @@ async function dispatchCommand(client, options, io) {
       return handleStatus(client, options);
     case "export":
       return handleExport(client, options);
+    case "import":
+      return handleImport(client, options);
     case "db-init":
       return handleDbInit(options);
     case "db-migrate":
@@ -969,6 +1109,7 @@ async function dispatchCommand(client, options, io) {
       return result;
     }
     default:
+      log("unknown command: " + options.command, 2 /* WARNING */);
       return {
         error: `unknown command: ${options.command}`,
         exitCode: 1
@@ -1054,6 +1195,20 @@ async function handleExport(client, options) {
     };
   }
 }
+async function handleImport(client, options) {
+  try {
+    const result = await runImport(client, options);
+    return {
+      output: JSON.stringify(result, null, 2),
+      exitCode: 0
+    };
+  } catch (err) {
+    return {
+      error: `import failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+}
 async function handleContent(client, options) {
   try {
     const result = await runContent(client, options);
@@ -1154,7 +1309,7 @@ async function hydrateSearchPreviews(client, paged) {
 }
 
 // src/shared/version/constants/version.constant.ts
-var VERSION = "0.2.2";
+var VERSION = "0.4.1";
 
 // src/shared/cli/functions/generate-help.function.ts
 var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
@@ -1171,7 +1326,8 @@ var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
   "mcp",
   "db",
   "skill",
-  "agent"
+  "agent",
+  "worker"
 ]);
 var GROUP_SUBCOMMANDS = {
   db: [
@@ -1189,6 +1345,10 @@ var GROUP_SUBCOMMANDS = {
     ["list", "List all agents"],
     ["get", "Retrieve an agent by docid"],
     ["delete", "Remove an agent"]
+  ],
+  worker: [
+    ["stop", "Stop the worker daemon"],
+    ["restart", "Restart the worker daemon"]
   ]
 };
 function isKnownCommand(cmd) {
@@ -1257,6 +1417,10 @@ Agents:
    agent get           Retrieve an agent by docid
    agent delete        Remove an agent
 
+Worker:
+   worker stop         Stop the worker daemon
+   worker restart      Restart the worker daemon
+
 Server:
    mcp                 Start MCP server mode (stdio)
 
@@ -1302,7 +1466,8 @@ Run "kbdb ${group} <subcommand> --help" for details.
 var GROUP_DESCRIPTIONS = {
   db: "Database management",
   skill: "Skill management",
-  agent: "Agent management"
+  agent: "Agent management",
+  worker: "Worker daemon management"
 };
 var LEAF_HELP = {
   learn: `kbdb learn - Import content from files or stdin
@@ -1488,11 +1653,11 @@ Options:
    --db <path>         Path to .kbdb directory
 
 Environment:
-   KBDB_DIR            Fallback database path
+   KBDB_DB_DIR            Fallback database path
 
 Examples:
    kbdb mcp --db /path/to/project
-   KBDB_DIR=/path/to/project kbdb mcp
+   KBDB_DB_DIR=/path/to/project kbdb mcp
 `
 };
 var SUBCOMMAND_HELP = {
@@ -1655,6 +1820,28 @@ Output:
 
 Examples:
    kbdb agent delete agent-code-reviewer
+`,
+  "worker-stop": `kbdb worker stop - Stop the worker daemon
+
+Usage: kbdb worker stop [options]
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Examples:
+   kbdb worker stop
+   kbdb worker stop --db /path/to/project
+`,
+  "worker-restart": `kbdb worker restart - Restart the worker daemon
+
+Usage: kbdb worker restart [options]
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Examples:
+   kbdb worker restart
+   kbdb worker restart --db /path/to/project
 `
 };
 function generateSubcommandHelp(command, subcommand) {
@@ -1666,211 +1853,72 @@ function generateSubcommandHelp(command, subcommand) {
   return generateCommandHelp(command);
 }
 
-// src/shared/cli/functions/run-cli.function.ts
-async function runCli(argv, deps2) {
-  const options = parseArgs(argv);
-  if (options.command === "help" || !options.command) {
-    const helpCommand = options.args[0];
-    const helpSubcommand = options.args[1];
-    const helpText = generateHelp(helpCommand, helpSubcommand);
-    if (helpCommand && !isKnownCommand(helpCommand)) {
-      return { output: helpText, exitCode: 1 };
-    }
-    return { output: helpText, exitCode: 0 };
-  }
-  if (options.command === "version") {
-    return { output: VERSION, exitCode: 0 };
-  }
-  if (options.command === "init" || options.command === "db-init") {
-    return handleInit(options, deps2);
-  }
-  if (options.command === "mcp") {
-    return handleMcp(options, deps2);
-  }
-  if (options.command === "migrate" || options.command === "db-migrate") {
-    return handleMigrate(options, deps2);
-  }
-  return handleDataCommand(options, deps2);
-}
-function handleInit(options, deps2) {
-  const result = deps2.runInit(options);
-  if (result.ok) {
-    return {
-      output: result.targetPath,
-      exitCode: 0
-    };
-  }
-  return {
-    error: `error: ${result.errorMessage ?? "init failed"}`,
-    exitCode: 1
-  };
-}
-async function handleMcp(options, deps2) {
-  const rawDbPath = options.dbPath ?? process.env["KBDB_DIR"];
-  if (!rawDbPath) {
-    return {
-      error: "error: --db or KBDB_DIR required in MCP mode",
-      exitCode: 1
-    };
-  }
-  const dbDir = deps2.findDb(rawDbPath);
-  if (!dbDir) {
-    return {
-      error: `error: no .kbdb database found at ${rawDbPath}`,
-      exitCode: 1
-    };
-  }
-  let client;
-  try {
-    client = await deps2.createWorkerClient({
-      contextPath: dbDir
-    });
-  } catch (err) {
-    return {
-      error: `error: ${errorToMessage(err)}`,
-      exitCode: 1
-    };
-  }
+// src/shared/worker-client/classes/worker-client.class.ts
+import { connect } from "node:net";
+
+// src/shared/worker-client/functions/discover-daemon.function.ts
+import { existsSync as existsSync4, readFileSync as readFileSync2, unlinkSync } from "node:fs";
+import { join as join5 } from "node:path";
+import { tmpdir } from "node:os";
+
+// src/shared/platform/functions/is-process-alive.function.ts
+function isProcessAlive(pid) {
   try {
-    const gateResult = await versionGate(client, dbDir);
-    if (gateResult) return gateResult;
-    if (deps2.startMcpServer) {
-      await deps2.startMcpServer(dbDir);
-    }
-    return { exitCode: 0 };
-  } catch (err) {
-    return {
-      error: `error: mcp failed: ${errorToMessage(err)}`,
-      exitCode: 1
-    };
-  } finally {
-    client.disconnect();
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
   }
 }
-async function handleMigrate(options, deps2) {
-  const dbDir = deps2.findDb(options.dbPath);
-  if (!dbDir) {
-    const basePath = options.dbPath ?? process.cwd();
-    return {
-      error: `error: no .kbdb database found at ${basePath}`,
-      exitCode: 1
-    };
-  }
-  let client;
-  try {
-    client = await deps2.createWorkerClient({
-      contextPath: dbDir
-    });
-  } catch (err) {
-    return {
-      error: `error: ${errorToMessage(err)}`,
-      exitCode: 1
-    };
-  }
-  try {
-    const versionStatus = await client.checkVersion(dbDir);
-    if (versionStatus.status === "too_new") {
-      return {
-        error: `error: database version ${versionStatus.currentVersion.toString()} is newer than kbdb version ${versionStatus.requiredVersion.toString()} -- upgrade kbdb`,
-        exitCode: 1
-      };
-    }
-    if (versionStatus.status === "needs_migration") {
-      const migrateResult = await client.migrateDatabase(dbDir);
-      return {
-        output: JSON.stringify(migrateResult, null, 2),
-        exitCode: 0
-      };
-    }
-    return { output: "already up to date", exitCode: 0 };
-  } catch (err) {
-    return {
-      error: `error: migrate failed: ${errorToMessage(err)}`,
-      exitCode: 1
-    };
-  } finally {
-    client.disconnect();
+
+// src/shared/worker-client/functions/discover-daemon.function.ts
+function discoverDaemon(contextId) {
+  log("discovering daemon for context: " + contextId, 0 /* DEBUG */);
+  const pidPath = join5(tmpdir(), `kbdb-${contextId}.pid`);
+  if (!existsSync4(pidPath)) {
+    log(
+      "no daemon PID file found for context: " + contextId,
+      0 /* DEBUG */
+    );
+    return null;
   }
-}
-async function handleDataCommand(options, deps2) {
-  let dbDir = deps2.findDb(options.dbPath);
-  if (!dbDir) {
-    const basePath = options.dbPath ?? process.cwd();
-    if (!deps2.isStdinTty()) {
-      return {
-        error: `error: no .kbdb database found at ${basePath} -- run \`kbdb --init\` to create one`,
-        exitCode: 1
-      };
-    }
-    const answer = await deps2.promptUser(
-      `No .kbdb database found. Create one in ${basePath}? [y/N] `
+  const pidStr = readFileSync2(pidPath, "utf-8").trim();
+  const pid = parseInt(pidStr, 10);
+  if (isNaN(pid) || !isProcessAlive(pid)) {
+    log(
+      "daemon process not alive for context: " + contextId,
+      0 /* DEBUG */
     );
-    if (answer.toLowerCase() !== "y") {
-      return {
-        error: "aborted: no database created",
-        exitCode: 1
-      };
-    }
-    const initResult = deps2.runInit(options);
-    if (!initResult.ok) {
-      return {
-        error: `error: ${initResult.errorMessage ?? "init failed"}`,
-        exitCode: 1
-      };
+    try {
+      unlinkSync(pidPath);
+    } catch {
     }
-    dbDir = initResult.targetPath;
-  }
-  let client;
-  try {
-    client = await deps2.createWorkerClient({
-      contextPath: dbDir
-    });
-  } catch (err) {
-    return {
-      error: `error: ${errorToMessage(err)}`,
-      exitCode: 1
-    };
+    return null;
   }
+  log("daemon found: pid=" + pid.toString(), 0 /* DEBUG */);
+  const socketPath = join5(tmpdir(), `kbdb-${contextId}.sock`);
+  const crashPath = join5(tmpdir(), `kbdb-${contextId}.crash`);
   try {
-    const gateResult = await versionGate(client, dbDir);
-    if (gateResult) return gateResult;
-    return await dispatchCommand(client, options);
-  } finally {
-    client.disconnect();
-  }
-}
-async function versionGate(client, dbDir) {
-  const versionStatus = await client.checkVersion(dbDir);
-  if (versionStatus.status === "needs_migration") {
-    return {
-      error: "error: database needs migration -- run `kbdb --migrate`",
-      exitCode: 1
-    };
-  }
-  if (versionStatus.status === "too_new") {
-    return {
-      error: `error: database version ${versionStatus.currentVersion.toString()} is newer than kbdb version ${versionStatus.requiredVersion.toString()} -- upgrade kbdb`,
-      exitCode: 1
-    };
+    unlinkSync(crashPath);
+  } catch {
   }
-  return null;
+  return { pid, socketPath };
 }
 
-// src/shared/cli/constants/help-text.constant.ts
-var HELP_TEXT = generateHelp();
-
 // src/shared/worker-client/classes/worker-client.class.ts
-import { connect } from "node:net";
 var WorkerClient = class {
   /**
    * @param socketPath - absolute path to the daemon's IPC socket
    *   (or Windows named pipe path)
    * @param contextId - 16-character context identifier sent as
    *   `ctx` in every JSON-RPC request
+   * @param requestTimeoutMs - per-request timeout in ms
+   *   (0 or undefined disables the timeout)
    */
-  constructor(socketPath, contextId) {
+  constructor(socketPath, contextId, requestTimeoutMs) {
     this.socketPath = socketPath;
     this.contextId = contextId;
+    this.requestTimeoutMs = requestTimeoutMs;
   }
   /** Underlying socket; `null` when not connected. */
   socket = null;
@@ -1880,30 +1928,121 @@ var WorkerClient = class {
   pending = /* @__PURE__ */ new Map();
   /** Partial line buffer for split TCP/IPC frames. */
   buffer = "";
+  /** Whether the underlying socket is connected. */
+  get isConnected() {
+    return this.socket !== null;
+  }
   /**
    * Establishes the IPC connection to the worker daemon.
    *
+   * Retries up to 5 times with exponential backoff on
+   * transient errors (`ENOENT`, `ECONNREFUSED`).
+   *
    * @throws {Error} if the connection cannot be established
    */
   async connect() {
+    log("connecting to " + this.socketPath, 0 /* DEBUG */);
+    const maxRetries = 5;
+    let delay = 50;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        await this.tryConnect();
+        log("connected", 0 /* DEBUG */);
+        return;
+      } catch (err) {
+        const code = err.code;
+        const retriable = code === "ENOENT" || code === "ECONNREFUSED";
+        if (!retriable || attempt === maxRetries) {
+          throw err;
+        }
+        log(
+          "connect retry: attempt=" + attempt.toString() + " code=" + code + " delay=" + delay.toString() + "ms",
+          0 /* DEBUG */
+        );
+        await new Promise((r) => setTimeout(r, delay));
+        delay = Math.min(delay * 2, 1e3);
+      }
+    }
+  }
+  /** Destroys the IPC socket and clears the connection state. */
+  disconnect() {
+    log("disconnecting client", 0 /* DEBUG */);
+    if (this.socket) {
+      this.socket.destroy();
+      this.socket = null;
+    }
+  }
+  /**
+   * Kills the daemon process and disconnects the client.
+   *
+   * Discovers the daemon via PID file and sends `SIGTERM`.
+   * Always disconnects the socket regardless of kill outcome.
+   */
+  killDaemon() {
+    const info = discoverDaemon(this.contextId);
+    log(
+      "killing daemon: pid=" + (info ? info.pid.toString() : "unknown"),
+      0 /* DEBUG */
+    );
+    if (info) {
+      try {
+        process.kill(info.pid, "SIGTERM");
+      } catch {
+      }
+    }
+    this.disconnect();
+  }
+  /**
+   * Single connection attempt with keepalive and
+   * post-connect failure handlers.
+   */
+  async tryConnect() {
     return new Promise((resolve4, reject) => {
-      this.socket = connect(this.socketPath, () => {
+      const sock = connect(this.socketPath, () => {
+        sock.removeListener("error", reject);
+        sock.setKeepAlive(true, 3e4);
+        sock.on("error", (err) => {
+          log(
+            "socket error: code=" + (err.code ?? err.message),
+            0 /* DEBUG */
+          );
+          this.handleSocketFailure(err);
+        });
+        sock.on("close", () => {
+          log("socket closed", 0 /* DEBUG */);
+          if (this.pending.size > 0) {
+            this.handleSocketFailure(
+              new Error("connection closed")
+            );
+          }
+          this.socket = null;
+        });
+        this.socket = sock;
         resolve4();
       });
-      this.socket.on("error", (err) => {
-        reject(err);
-      });
-      this.socket.on("data", (chunk) => {
+      sock.on("error", reject);
+      sock.on("data", (chunk) => {
         this.handleData(chunk.toString());
       });
     });
   }
-  /** Destroys the IPC socket and clears the connection state. */
-  disconnect() {
-    if (this.socket) {
-      this.socket.destroy();
-      this.socket = null;
+  /**
+   * Rejects all pending calls and marks the client as
+   * disconnected.
+   */
+  handleSocketFailure(err) {
+    log(
+      "socket failure: pending=" + this.pending.size.toString() + " err=" + err.message,
+      0 /* DEBUG */
+    );
+    const sock = this.socket;
+    this.socket = null;
+    for (const [id, call] of this.pending) {
+      this.pending.delete(id);
+      if (call.timer) clearTimeout(call.timer);
+      call.reject(err);
     }
+    if (sock) sock.destroy();
   }
   /**
    * Searches the knowledge base.
@@ -1912,7 +2051,10 @@ var WorkerClient = class {
    * @returns paginated search results with metadata
    */
   async search(params) {
-    return this.call("search", params);
+    return this.call("search", {
+      ...params,
+      algo: params.algo
+    });
   }
   /**
    * Retrieves full content and context for one or more sections by
@@ -2163,7 +2305,20 @@ var WorkerClient = class {
    */
   async export(params) {
     return this.call("export", {
-      targetPath: params?.path || void 0
+      targetPath: params?.path || void 0,
+      format: params?.format
+    });
+  }
+  /**
+   * Imports an exported database from the given path.
+   *
+   * @param params - source path and dry-run flag
+   * @returns import report with counts and timing
+   */
+  async import(params) {
+    return this.call("importDb", {
+      sourcePath: params.from,
+      dryRun: params.dryRun
     });
   }
   /**
@@ -2180,14 +2335,35 @@ var WorkerClient = class {
       throw new Error("not connected");
     }
     const id = this.nextId++;
+    log(
+      "call: method=" + method + " id=" + id.toString(),
+      0 /* DEBUG */
+    );
     const request = {
       jsonrpc: "2.0",
       id,
       method,
       params: { ctx: this.contextId, ...params }
     };
+    const timeoutMs = this.requestTimeoutMs;
     return new Promise((resolve4, reject) => {
-      this.pending.set(id, { resolve: resolve4, reject });
+      const call = { resolve: resolve4, reject };
+      if (timeoutMs) {
+        call.timer = setTimeout(() => {
+          if (!this.pending.has(id)) return;
+          this.pending.delete(id);
+          log(
+            "request timeout after " + String(timeoutMs) + "ms",
+            2 /* WARNING */
+          );
+          const err = new Error(
+            `request timeout after ${String(timeoutMs)}ms`
+          );
+          err.code = "REQUEST_TIMEOUT";
+          reject(err);
+        }, timeoutMs);
+      }
+      this.pending.set(id, call);
       socket.write(JSON.stringify(request) + "\n");
     });
   }
@@ -2208,15 +2384,33 @@ var WorkerClient = class {
         const pending = this.pending.get(response.id);
         if (pending) {
           this.pending.delete(response.id);
+          if (pending.timer) clearTimeout(pending.timer);
           if (response.error) {
+            log(
+              "response error: id=" + response.id.toString() + " code=" + response.error.code.toString(),
+              0 /* DEBUG */
+            );
             const err = new Error(response.error.message);
             err.code = response.error.code;
             pending.reject(err);
           } else {
+            log(
+              "response ok: id=" + response.id.toString(),
+              0 /* DEBUG */
+            );
             pending.resolve(response.result);
           }
+        } else {
+          log(
+            "unmatched response id=" + response.id.toString(),
+            0 /* DEBUG */
+          );
         }
-      } catch {
+      } catch (parseErr) {
+        log(
+          "json parse error: " + parseErr.message,
+          0 /* DEBUG */
+        );
       }
     }
   }
@@ -2228,129 +2422,501 @@ import { join as join8 } from "node:path";
 import { tmpdir as tmpdir3 } from "node:os";
 
 // src/shared/worker-client/functions/resolve-db-path.function.ts
-import { existsSync as existsSync4 } from "node:fs";
-import { join as join5, resolve as resolve3 } from "node:path";
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join6, resolve as resolve3 } from "node:path";
 function resolveDbPath(targetDir) {
   const base = targetDir ? resolve3(targetDir) : process.cwd();
-  const dbPath = join5(base, ".kbdb");
-  if (!existsSync4(dbPath)) {
-    throw new Error(`database not found: ${dbPath}`);
+  const dbPath = join6(base, ".kbdb");
+  if (!existsSync5(dbPath)) {
+    const msg = `database not found: ${dbPath}`;
+    log(msg, 3 /* ERROR */);
+    throw new Error(msg);
+  }
+  return dbPath;
+}
+
+// src/shared/worker-client/functions/compute-context-id.function.ts
+async function computeContextId(absolutePath) {
+  const hash = await computeSha256(absolutePath);
+  return hash.slice(0, 16);
+}
+
+// src/shared/worker-client/functions/spawn-daemon.function.ts
+import { spawn } from "node:child_process";
+function spawnDaemon(contextPath, runtime2, workerScript2) {
+  if (!workerScript2) {
+    const msg = "workerScript must be provided (resolve at entry point)";
+    log(msg, 3 /* ERROR */);
+    throw new Error(msg);
+  }
+  const execPath = runtime2 === "deno" ? "deno" : process.execPath;
+  const logLevelEnv = process.env["KBDB_LOG_LEVEL"];
+  const logArgs = logLevelEnv ? ["--log-level", logLevelEnv] : [];
+  const args = runtime2 === "deno" ? ["run", "--allow-all", workerScript2, contextPath, ...logArgs] : [workerScript2, contextPath, ...logArgs];
+  log(
+    "spawning daemon: " + execPath + " " + args.join(" "),
+    0 /* DEBUG */
+  );
+  const child = spawn(execPath, args, {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.unref();
+}
+
+// src/shared/worker-client/functions/wait-for-daemon.function.ts
+import { existsSync as existsSync6 } from "node:fs";
+import { join as join7 } from "node:path";
+import { tmpdir as tmpdir2 } from "node:os";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var POLL_INTERVAL_MS = 100;
+async function waitForDaemon(contextId, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  log("waiting for daemon: contextId=" + contextId, 0 /* DEBUG */);
+  const pidPath = join7(tmpdir2(), `kbdb-${contextId}.pid`);
+  const start = Date.now();
+  let iteration = 0;
+  while (Date.now() - start < timeoutMs) {
+    if (existsSync6(pidPath)) {
+      log("daemon PID file appeared", 0 /* DEBUG */);
+      return true;
+    }
+    iteration++;
+    if (iteration % 10 === 0) {
+      const elapsed2 = Date.now() - start;
+      log(
+        "still waiting for daemon: elapsed=" + elapsed2.toString() + "ms",
+        0 /* DEBUG */
+      );
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+  const elapsed = Date.now() - start;
+  log(
+    "timed out waiting for daemon: elapsed=" + elapsed.toString() + "ms",
+    0 /* DEBUG */
+  );
+  return false;
+}
+
+// src/shared/worker-client/functions/create-worker-client.function.ts
+async function createWorkerClient(options) {
+  const dbPath = options?.contextPath ?? resolveDbPath(options?.dbPath);
+  const contextId = await computeContextId(dbPath);
+  log("create-worker-client: contextId=" + contextId, 0 /* DEBUG */);
+  const socketPath = getIpcPath(contextId);
+  let daemon = discoverDaemon(contextId);
+  if (daemon) {
+    log("daemon found: pid=" + daemon.pid.toString(), 0 /* DEBUG */);
+  } else {
+    log("no daemon found", 0 /* DEBUG */);
+  }
+  if (!daemon && options?.autoSpawn !== false) {
+    const runtime2 = detectRuntime();
+    log("auto-spawning daemon", 0 /* DEBUG */);
+    spawnDaemon(dbPath, runtime2, options?.workerScript);
+    log("waiting for daemon after spawn", 0 /* DEBUG */);
+    await waitForDaemon(contextId, options?.connectTimeoutMs);
+    daemon = discoverDaemon(contextId);
+  }
+  if (!daemon) {
+    const msg = `kbdb worker daemon did not start: ${readCrashReason(contextId)}`;
+    log(msg, 3 /* ERROR */);
+    throw new Error(msg);
+  }
+  log("connecting to daemon", 0 /* DEBUG */);
+  const client = new WorkerClient(
+    socketPath,
+    contextId,
+    options?.requestTimeoutMs
+  );
+  await client.connect();
+  return client;
+}
+function readCrashReason(contextId) {
+  const crashPath = join8(tmpdir3(), `kbdb-${contextId}.crash`);
+  if (!existsSync7(crashPath)) {
+    return "daemon failed to start (no details available)";
+  }
+  try {
+    const raw = readFileSync3(crashPath, "utf-8");
+    const crash = JSON.parse(raw);
+    unlinkSync2(crashPath);
+    return crash.error ?? "unknown error (crash log empty)";
+  } catch {
+    return "daemon failed to start (crash log unreadable)";
+  }
+}
+
+// src/shared/cli/functions/run-worker-stop.function.ts
+async function runWorkerStop(dbDir) {
+  log("running worker-stop", 0 /* DEBUG */);
+  const contextId = await computeContextId(dbDir);
+  const info = discoverDaemon(contextId);
+  if (!info) {
+    return { output: "no daemon running", exitCode: 0 };
+  }
+  log("pid found: " + info.pid.toString(), 0 /* DEBUG */);
+  try {
+    process.kill(info.pid, "SIGTERM");
+    log("sigterm sent to pid=" + info.pid.toString(), 0 /* DEBUG */);
+  } catch {
+    return {
+      error: "error: failed to stop daemon",
+      exitCode: 1
+    };
+  }
+  const deadline = Date.now() + 5e3;
+  let pollIteration = 0;
+  while (Date.now() < deadline) {
+    try {
+      process.kill(info.pid, 0);
+    } catch {
+      log(
+        "process exited: pid=" + info.pid.toString(),
+        0 /* DEBUG */
+      );
+      break;
+    }
+    pollIteration++;
+    if (pollIteration % 5 === 0) {
+      log(
+        "waiting for exit: pid=" + info.pid.toString() + " poll=" + pollIteration.toString(),
+        0 /* DEBUG */
+      );
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  if (Date.now() >= deadline) {
+    log(
+      "timed out waiting for exit: pid=" + info.pid.toString(),
+      0 /* DEBUG */
+    );
+  }
+  return {
+    output: `stopped daemon (pid ${info.pid.toString()})`,
+    exitCode: 0
+  };
+}
+
+// src/shared/cli/functions/run-worker-restart.function.ts
+async function runWorkerRestart(dbDir) {
+  log("running worker-restart", 0 /* DEBUG */);
+  const stopResult = await runWorkerStop(dbDir);
+  if (stopResult.exitCode !== 0) return stopResult;
+  return {
+    output: "daemon will restart on next command",
+    exitCode: 0
+  };
+}
+
+// src/shared/cli/functions/resolve-raw-db-path.function.ts
+function resolveRawDbPath(options) {
+  return options.dbPath ?? process.env["KBDB_DB_DIR"];
+}
+
+// src/shared/worker-client/functions/retry-on-timeout.function.ts
+async function retryOnTimeout(createClient, operation, maxRetries) {
+  let lastError = new Error("retryOnTimeout exhausted");
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    log(
+      "retry-on-timeout: attempt=" + attempt.toString() + " max=" + maxRetries.toString(),
+      0 /* DEBUG */
+    );
+    const client = await createClient();
+    try {
+      const result = await operation(client);
+      log(
+        "retry-on-timeout: success on attempt=" + attempt.toString(),
+        0 /* DEBUG */
+      );
+      return { client, result };
+    } catch (err) {
+      const code = err.code;
+      if (code !== "REQUEST_TIMEOUT" || attempt >= maxRetries) {
+        log(
+          "retry-on-timeout: non-retriable error code=" + String(code),
+          0 /* DEBUG */
+        );
+        client.disconnect();
+        throw err;
+      }
+      lastError = err;
+      if (client.killDaemon) {
+        log(
+          "retry " + String(attempt + 1) + "/" + String(maxRetries) + ": killing daemon",
+          2 /* WARNING */
+        );
+        client.killDaemon();
+      } else {
+        client.disconnect();
+      }
+    }
+  }
+  log(
+    "retry-on-timeout: all retries exhausted max=" + maxRetries.toString(),
+    0 /* DEBUG */
+  );
+  throw lastError;
+}
+
+// src/shared/worker-client/constants/request-timeout.constant.ts
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+
+// src/shared/worker-client/constants/retry-defaults.constant.ts
+var DEFAULT_RETRY_COUNT = 5;
+
+// src/shared/cli/functions/run-cli.function.ts
+async function runCli(argv, deps2) {
+  const options = parseArgs(argv);
+  const logLevel = resolveLogLevel(options.logLevel);
+  configureLog({ level: logLevel });
+  log("command: " + options.command, 0 /* DEBUG */);
+  if (options.command === "init") {
+    log('--init is deprecated, use "kbdb db init"', 2 /* WARNING */);
+  }
+  if (options.command === "migrate") {
+    log(
+      '--migrate is deprecated, use "kbdb db migrate"',
+      2 /* WARNING */
+    );
+  }
+  const nonInteractive = options.nonInteractive || process.env["KBDB_NON_INTERACTIVE"] === "1" || process.env["KBDB_NON_INTERACTIVE"] === "true";
+  const effectiveDeps = nonInteractive ? { ...deps2, isStdinTty: () => false } : deps2;
+  if (!options.formatExplicit) {
+    options.format = effectiveDeps.isStdoutTty() ? "text" : "json";
+  }
+  if (options.command === "help" || !options.command) {
+    const helpCommand = options.args[0];
+    const helpSubcommand = options.args[1];
+    const helpText = generateHelp(helpCommand, helpSubcommand);
+    if (helpCommand && !isKnownCommand(helpCommand)) {
+      return { output: helpText, exitCode: 1 };
+    }
+    return { output: helpText, exitCode: 0 };
+  }
+  if (options.command === "version") {
+    return { output: VERSION, exitCode: 0 };
+  }
+  if (options.command === "init" || options.command === "db-init") {
+    return handleInit(options, effectiveDeps);
+  }
+  if (options.command === "mcp") {
+    return handleMcp(options, effectiveDeps);
+  }
+  if (options.command === "migrate" || options.command === "db-migrate") {
+    return handleMigrate(options, effectiveDeps);
+  }
+  if (options.command === "worker-stop") {
+    return handleWorkerLifecycle(
+      options,
+      effectiveDeps,
+      runWorkerStop
+    );
+  }
+  if (options.command === "worker-restart") {
+    return handleWorkerLifecycle(
+      options,
+      effectiveDeps,
+      runWorkerRestart
+    );
+  }
+  return handleDataCommand(options, effectiveDeps);
+}
+function handleInit(options, deps2) {
+  const result = deps2.runInit(options);
+  if (result.ok) {
+    return {
+      output: result.targetPath,
+      exitCode: 0
+    };
+  }
+  return {
+    error: `error: ${result.errorMessage ?? "init failed"}`,
+    exitCode: 1
+  };
+}
+function resolveTimeoutMs(options) {
+  return options.timeoutMs ?? (parseInt(process.env["KBDB_DAEMON_TIMEOUT"] ?? "", 10) || DEFAULT_REQUEST_TIMEOUT_MS);
+}
+function resolveRetryCount(options) {
+  return options.retry ?? (parseInt(process.env["KBDB_RETRY"] ?? "", 10) || DEFAULT_RETRY_COUNT);
+}
+async function handleMcp(options, deps2) {
+  const explicitPath = resolveRawDbPath(options);
+  const dbDir = deps2.findDb(explicitPath);
+  if (!dbDir) {
+    return {
+      error: "error: no .kbdb database found at " + (explicitPath ?? process.cwd()),
+      exitCode: 1
+    };
+  }
+  const timeoutMs = resolveTimeoutMs(options);
+  const maxRetries = resolveRetryCount(options);
+  let client;
+  try {
+    client = await deps2.createWorkerClient({
+      contextPath: dbDir,
+      requestTimeoutMs: timeoutMs
+    });
+  } catch (err) {
+    return {
+      error: `error: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
   }
-  return dbPath;
-}
-
-// src/shared/worker-client/functions/compute-context-id.function.ts
-async function computeContextId(absolutePath) {
-  const hash = await computeSha256(absolutePath);
-  return hash.slice(0, 16);
-}
-
-// src/shared/worker-client/functions/discover-daemon.function.ts
-import { existsSync as existsSync5, readFileSync as readFileSync2, unlinkSync } from "node:fs";
-import { join as join6 } from "node:path";
-import { tmpdir } from "node:os";
-
-// src/shared/platform/functions/is-process-alive.function.ts
-function isProcessAlive(pid) {
   try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
+    const gateResult = await versionGate(client, dbDir);
+    if (gateResult) return gateResult;
+    if (deps2.startMcpServer) {
+      await deps2.startMcpServer(
+        dbDir,
+        () => deps2.createWorkerClient({
+          contextPath: dbDir,
+          requestTimeoutMs: timeoutMs
+        }),
+        maxRetries
+      );
+    }
+    return { exitCode: 0 };
+  } catch (err) {
+    return {
+      error: `error: mcp failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  } finally {
+    client.disconnect();
   }
 }
-
-// src/shared/worker-client/functions/discover-daemon.function.ts
-function discoverDaemon(contextId) {
-  const pidPath = join6(tmpdir(), `kbdb-${contextId}.pid`);
-  if (!existsSync5(pidPath)) return null;
-  const pidStr = readFileSync2(pidPath, "utf-8").trim();
-  const pid = parseInt(pidStr, 10);
-  if (isNaN(pid) || !isProcessAlive(pid)) {
-    try {
-      unlinkSync(pidPath);
-    } catch {
-    }
-    return null;
+async function handleMigrate(options, deps2) {
+  const dbDir = deps2.findDb(options.dbPath);
+  if (!dbDir) {
+    const basePath = options.dbPath ?? process.cwd();
+    return {
+      error: `error: no .kbdb database found at ${basePath}`,
+      exitCode: 1
+    };
   }
-  const socketPath = join6(tmpdir(), `kbdb-${contextId}.sock`);
-  const crashPath = join6(tmpdir(), `kbdb-${contextId}.crash`);
+  let client;
   try {
-    unlinkSync(crashPath);
-  } catch {
+    client = await deps2.createWorkerClient({
+      contextPath: dbDir
+    });
+  } catch (err) {
+    return {
+      error: `error: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+  try {
+    const versionStatus = await client.checkVersion(dbDir);
+    if (versionStatus.status === "too_new") {
+      return {
+        error: `error: database version ${versionStatus.currentVersion.toString()} is newer than kbdb version ${versionStatus.requiredVersion.toString()} -- upgrade kbdb`,
+        exitCode: 1
+      };
+    }
+    if (versionStatus.status === "needs_migration") {
+      const migrateResult = await client.migrateDatabase(dbDir);
+      return {
+        output: JSON.stringify(migrateResult, null, 2),
+        exitCode: 0
+      };
+    }
+    return { output: "already up to date", exitCode: 0 };
+  } catch (err) {
+    return {
+      error: `error: migrate failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  } finally {
+    client.disconnect();
   }
-  return { pid, socketPath };
 }
-
-// src/shared/worker-client/functions/spawn-daemon.function.ts
-import { spawn } from "node:child_process";
-function spawnDaemon(contextPath, runtime2, workerScript2) {
-  if (!workerScript2) {
-    throw new Error(
-      "workerScript must be provided (resolve at entry point)"
+async function handleDataCommand(options, deps2) {
+  const explicitPath = resolveRawDbPath(options);
+  let dbDir = deps2.findDb(explicitPath);
+  if (!dbDir) {
+    const basePath = explicitPath ?? process.cwd();
+    if (!deps2.isStdinTty()) {
+      return {
+        error: `error: no .kbdb database found at ${basePath} -- run \`kbdb --init\` to create one`,
+        exitCode: 1
+      };
+    }
+    const answer = await deps2.promptUser(
+      `No .kbdb database found. Create one in ${basePath}? [y/N] `
     );
+    if (answer.toLowerCase() !== "y") {
+      return {
+        error: "aborted: no database created",
+        exitCode: 1
+      };
+    }
+    const initResult = deps2.runInit(options);
+    if (!initResult.ok) {
+      return {
+        error: `error: ${initResult.errorMessage ?? "init failed"}`,
+        exitCode: 1
+      };
+    }
+    dbDir = initResult.targetPath;
   }
-  const execPath = runtime2 === "deno" ? "deno" : process.execPath;
-  const args = runtime2 === "deno" ? ["run", "--allow-all", workerScript2, contextPath] : [workerScript2, contextPath];
-  const child = spawn(execPath, args, {
-    detached: true,
-    stdio: "ignore"
-  });
-  child.unref();
-}
-
-// src/shared/worker-client/functions/wait-for-daemon.function.ts
-import { existsSync as existsSync6 } from "node:fs";
-import { join as join7 } from "node:path";
-import { tmpdir as tmpdir2 } from "node:os";
-var DEFAULT_TIMEOUT_MS = 1e4;
-var POLL_INTERVAL_MS = 100;
-async function waitForDaemon(contextId, timeoutMs = DEFAULT_TIMEOUT_MS) {
-  const pidPath = join7(tmpdir2(), `kbdb-${contextId}.pid`);
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    if (existsSync6(pidPath)) return true;
-    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  log("db path: " + dbDir, 0 /* DEBUG */);
+  const timeoutMs = resolveTimeoutMs(options);
+  const maxRetries = resolveRetryCount(options);
+  try {
+    const { client, result } = await retryOnTimeout(
+      () => deps2.createWorkerClient({
+        contextPath: dbDir,
+        requestTimeoutMs: timeoutMs
+      }),
+      async (c) => {
+        const gateResult = await versionGate(c, dbDir);
+        if (gateResult) return gateResult;
+        return dispatchCommand(c, options);
+      },
+      maxRetries
+    );
+    client.disconnect();
+    return result;
+  } catch (err) {
+    return {
+      error: `error: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
   }
-  return false;
 }
-
-// src/shared/worker-client/functions/create-worker-client.function.ts
-async function createWorkerClient(options) {
-  const dbPath = options?.contextPath ?? resolveDbPath(options?.dbPath);
-  const contextId = await computeContextId(dbPath);
-  const socketPath = getIpcPath(contextId);
-  let daemon = discoverDaemon(contextId);
-  if (!daemon && options?.autoSpawn !== false) {
-    const runtime2 = detectRuntime();
-    spawnDaemon(dbPath, runtime2, options?.workerScript);
-    await waitForDaemon(contextId, options?.connectTimeoutMs);
-    daemon = discoverDaemon(contextId);
-  }
-  if (!daemon) {
-    throw new Error(
-      `kbdb worker daemon did not start: ${readCrashReason(contextId)}`
-    );
+async function handleWorkerLifecycle(options, deps2, action) {
+  const explicitPath = resolveRawDbPath(options);
+  const dbDir = deps2.findDb(explicitPath);
+  if (!dbDir) {
+    return {
+      error: "error: no .kbdb database found at " + (explicitPath ?? process.cwd()),
+      exitCode: 1
+    };
   }
-  const client = new WorkerClient(socketPath, contextId);
-  await client.connect();
-  return client;
+  return action(dbDir);
 }
-function readCrashReason(contextId) {
-  const crashPath = join8(tmpdir3(), `kbdb-${contextId}.crash`);
-  if (!existsSync7(crashPath)) {
-    return "daemon failed to start (no details available)";
+async function versionGate(client, dbDir) {
+  const versionStatus = await client.checkVersion(dbDir);
+  if (versionStatus.status === "needs_migration") {
+    return {
+      error: "error: database needs migration -- run `kbdb --migrate`",
+      exitCode: 1
+    };
   }
-  try {
-    const raw = readFileSync3(crashPath, "utf-8");
-    const crash = JSON.parse(raw);
-    unlinkSync2(crashPath);
-    return crash.error ?? "unknown error (crash log empty)";
-  } catch {
-    return "daemon failed to start (crash log unreadable)";
+  if (versionStatus.status === "too_new") {
+    return {
+      error: `error: database version ${versionStatus.currentVersion.toString()} is newer than kbdb version ${versionStatus.requiredVersion.toString()} -- upgrade kbdb`,
+      exitCode: 1
+    };
   }
+  return null;
 }
 
+// src/shared/cli/constants/help-text.constant.ts
+var HELP_TEXT = generateHelp();
+
 // src/shared/mcp/classes/mcp-server.class.ts
 import { createInterface as createInterface2 } from "node:readline";
 
@@ -2384,6 +2950,10 @@ function createToolDefinitions() {
             type: "string",
             enum: ["lexical", "vector", "hybrid"],
             description: "Search algorithm (default: lexical)"
+          },
+          relaxed: {
+            type: "boolean",
+            description: "Use relaxed (OR) matching when the strict query returns no results"
           }
         },
         required: ["query"]
@@ -3064,6 +3634,7 @@ function asStringArray2(value) {
   return [];
 }
 async function handleToolCall(client, name, args) {
+  log("tool call: " + name, 0 /* DEBUG */);
   try {
     switch (name) {
       case "search":
@@ -3107,6 +3678,7 @@ async function handleToolCall(client, name, args) {
       case "auto-capture-review":
         return handleAutoCaptureReview();
       default:
+        log("unknown tool: " + name, 2 /* WARNING */);
         return {
           content: [
             {
@@ -3118,6 +3690,10 @@ async function handleToolCall(client, name, args) {
         };
     }
   } catch (err) {
+    log(
+      "tool call failed: " + name + ": " + (err instanceof Error ? err.message : String(err)),
+      3 /* ERROR */
+    );
     return {
       content: [
         {
@@ -3135,7 +3711,8 @@ async function handleSearch2(client, args) {
     mode: args["mode"],
     limit: args["limit"],
     offset: args["offset"],
-    algo: args["algo"]
+    algo: args["algo"],
+    relaxed: args["relaxed"]
   });
   const stripped = {
     ...results,
@@ -3491,6 +4068,7 @@ async function handleResourceRead(client, uri) {
       ]
     };
   }
+  log(`Unknown resource URI: ${uri}`, 3 /* ERROR */);
   throw new Error(`Unknown resource URI: ${uri}`);
 }
 
@@ -3567,6 +4145,7 @@ async function handleAgentPrompt(name, client) {
   const agents = await client.listDocumentsByType("agent");
   const doc = agents.find((a) => a.title === agentName);
   if (!doc) {
+    log("agent not found: " + agentName, 3 /* ERROR */);
     throw new Error("agent not found: " + agentName);
   }
   const sections = doc.sections;
@@ -3611,6 +4190,7 @@ async function handleSkillPrompt(name, promptArgs, client) {
     }
   }
   if (matchContent === void 0) {
+    log(`Prompt not found: ${name}`, 3 /* ERROR */);
     throw new Error(`Prompt not found: ${name}`);
   }
   const parsed = JSON.parse(matchContent);
@@ -3702,6 +4282,131 @@ function shouldEmitLog(messageLevel, threshold) {
   return messageIndex >= thresholdIndex;
 }
 
+// src/shared/auto-capture/functions/build-capture-prompt.function.ts
+function buildCapturePrompt(recentContext) {
+  return "Review the following conversation context and identify factual knowledge worth storing in the knowledge base.\n\nRules:\n- Include durable facts, decisions, preferences, and corrections that would be useful in future sessions.\n- Exclude ephemeral, task-specific, or temporary information that has no lasting value.\n- Format each piece of extracted knowledge as a concise statement suitable for direct storage.\n- If no durable knowledge is found, respond with an empty list.\n\nConversation context:\n" + recentContext;
+}
+
+// src/shared/mcp/functions/has-sampling-capability.function.ts
+function hasSamplingCapability(hostCapabilities) {
+  if (hostCapabilities === null) return false;
+  return Boolean(hostCapabilities["sampling"]);
+}
+
+// src/shared/mcp/functions/run-auto-capture.function.ts
+function isSamplingResponse(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const obj = v;
+  const content = obj["content"];
+  if (typeof content !== "object" || content === null) return false;
+  return typeof content["text"] === "string";
+}
+async function runAutoCapture(controller, config, client, hostCapabilities, requestSampling) {
+  try {
+    const trigger = controller.evaluate();
+    log("auto-capture trigger evaluated", 0 /* DEBUG */);
+    if (!trigger.shouldCapture) return;
+    if (!hasSamplingCapability(hostCapabilities)) return;
+    const prompt = buildCapturePrompt("recent conversation context");
+    const messages = [
+      { role: "user", content: { type: "text", text: prompt } }
+    ];
+    const raw = await requestSampling(messages, 1024);
+    if (!isSamplingResponse(raw)) return;
+    const text = raw.content.text.trim();
+    if (!text) return;
+    if (config.dryRun) return;
+    log("auto-capture storing knowledge", 0 /* DEBUG */);
+    await client.addSection({
+      sectionType: "text/markdown",
+      content: text,
+      title: "Auto-captured knowledge"
+    });
+  } catch {
+    log("auto-capture error (non-fatal)", 0 /* DEBUG */);
+  }
+}
+
+// src/shared/auto-capture/functions/evaluate-trigger.function.ts
+function evaluateTrigger(config, state) {
+  log("evaluating auto-capture trigger conditions", 0 /* DEBUG */);
+  if (!config.enabled) {
+    return {
+      shouldCapture: false,
+      reason: "auto-capture is disabled"
+    };
+  }
+  if (state.totalCapturesThisSession >= config.maxCapturesPerSession) {
+    return {
+      shouldCapture: false,
+      reason: "session capture limit reached"
+    };
+  }
+  const elapsed = state.lastCaptureTimestamp ? Date.now() - state.lastCaptureTimestamp : Infinity;
+  if (elapsed < config.minIntervalMs) {
+    return {
+      shouldCapture: false,
+      reason: "within minimum interval"
+    };
+  }
+  if (state.toolCallsSinceLastCapture < config.triggerAfterToolCalls) {
+    return {
+      shouldCapture: false,
+      reason: "tool call threshold not yet reached"
+    };
+  }
+  return { shouldCapture: true, reason: "trigger threshold met" };
+}
+
+// src/shared/auto-capture/classes/auto-capture-controller.class.ts
+var AutoCaptureController = class {
+  toolCallsSinceLastCapture = 0;
+  lastCaptureTimestamp = 0;
+  totalCapturesThisSession = 0;
+  config;
+  /** @param config - the auto-capture configuration to use */
+  constructor(config) {
+    this.config = config;
+  }
+  /** Record one tool call for trigger counting. */
+  recordToolCall() {
+    this.toolCallsSinceLastCapture += 1;
+  }
+  /**
+   * Evaluates the current state against the trigger criteria.
+   *
+   * When the trigger fires, advances the session counters so the
+   * next evaluation respects rate limiting and the session cap.
+   *
+   * @returns the trigger decision with a human-readable reason
+   */
+  evaluate() {
+    log("evaluating auto-capture trigger", 0 /* DEBUG */);
+    const trigger = evaluateTrigger(this.config, this.state());
+    if (trigger.shouldCapture) {
+      this.totalCapturesThisSession += 1;
+      this.lastCaptureTimestamp = Date.now();
+      this.toolCallsSinceLastCapture = 0;
+    }
+    return trigger;
+  }
+  /** Reset all counters, e.g. on client disconnect. */
+  reset() {
+    log("resetting auto-capture controller", 0 /* DEBUG */);
+    this.toolCallsSinceLastCapture = 0;
+    this.lastCaptureTimestamp = 0;
+    this.totalCapturesThisSession = 0;
+  }
+  /** Returns a snapshot of the current controller state. */
+  state() {
+    return {
+      toolCallsSinceLastCapture: this.toolCallsSinceLastCapture,
+      lastCaptureTimestamp: this.lastCaptureTimestamp,
+      totalCapturesThisSession: this.totalCapturesThisSession
+    };
+  }
+};
+
 // src/shared/mcp/constants/mcp-error-codes.constant.ts
 var PARSE_ERROR = -32700;
 var METHOD_NOT_FOUND = -32601;
@@ -3711,21 +4416,63 @@ var RESOURCE_NOT_FOUND = -32002;
 var McpServer = class {
   client;
   contextPath;
+  autoCaptureConfig;
+  clientFactory;
+  maxRetries;
+  autoCaptureController = null;
   initialized = false;
   hostCapabilities = null;
   logLevel = null;
   subscriptions = /* @__PURE__ */ new Set();
   nextRequestId = 1;
   pendingRequests = /* @__PURE__ */ new Map();
-  constructor(client, contextPath) {
+  /**
+   * @param client - worker client providing knowledge-base operations
+   * @param contextPath - absolute path to the `.kbdb` directory
+   * @param autoCaptureConfig - optional auto-capture configuration;
+   *   when provided the server activates auto-capture on connection
+   * @param clientFactory - creates a fresh worker client (for retry)
+   * @param maxRetries - max retries on REQUEST_TIMEOUT
+   */
+  constructor(client, contextPath, autoCaptureConfig, clientFactory, maxRetries) {
     this.client = client;
     this.contextPath = contextPath ?? "";
+    this.autoCaptureConfig = autoCaptureConfig ?? null;
+    this.clientFactory = clientFactory ?? null;
+    this.maxRetries = maxRetries ?? DEFAULT_RETRY_COUNT;
+  }
+  async reconnectClient() {
+    if (!this.clientFactory) {
+      log("no client factory for reconnect", 3 /* ERROR */);
+      throw new Error("no client factory for reconnect");
+    }
+    this.client.disconnect();
+    this.client = await this.clientFactory();
+    log("MCP client reconnected", 0 /* DEBUG */);
+  }
+  async withRetry(fn) {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await fn();
+      } catch (err) {
+        const code = err.code;
+        if (code !== "REQUEST_TIMEOUT" || attempt >= this.maxRetries || !this.clientFactory) {
+          throw err;
+        }
+        log(
+          "request timeout, reconnecting (attempt " + (attempt + 1).toString() + "/" + this.maxRetries.toString() + ")",
+          2 /* WARNING */
+        );
+        await this.reconnectClient();
+      }
+    }
   }
   async listen() {
     const rl = createInterface2({
       input: process.stdin,
       terminal: false
     });
+    log("MCP server listening on stdin", 0 /* DEBUG */);
     let pending = Promise.resolve();
     await new Promise((resolve4) => {
       rl.on("line", (line) => {
@@ -3733,7 +4480,10 @@ var McpServer = class {
       });
       rl.on("close", () => {
         void pending.then(() => {
+          this.autoCaptureController?.reset();
+          this.autoCaptureController = null;
           this.client.disconnect();
+          log("MCP stdin closed", 0 /* DEBUG */);
           resolve4();
         });
       });
@@ -3797,6 +4547,7 @@ var McpServer = class {
    */
   async requestSampling(messages, maxTokens) {
     if (!this.hostCapabilities?.["sampling"]) {
+      log("Host does not support sampling", 3 /* ERROR */);
       throw new Error("Host does not support sampling");
     }
     return this.sendRequest("sampling/createMessage", {
@@ -3843,10 +4594,15 @@ var McpServer = class {
       return null;
     }
     const request = parsed;
+    log("MCP request: " + request.method, 0 /* DEBUG */);
     if (request.id === void 0) {
       if (request.method === "notifications/initialized" || request.method === "notifications/cancelled") {
         if (request.method === "notifications/initialized" && !this.initialized) {
           this.initialized = true;
+          log("MCP initialized", 1 /* INFO */);
+          if (this.autoCaptureConfig !== null) {
+            this.autoCaptureController = new AutoCaptureController(this.autoCaptureConfig);
+          }
           void this.runStartupHealthCheck();
         }
       }
@@ -3880,7 +4636,7 @@ var McpServer = class {
             protocolVersion: "2025-11-25",
             serverInfo: {
               name: "kbdb",
-              version: "0.1.0"
+              version: VERSION
             },
             capabilities: {
               tools: {},
@@ -3921,11 +4677,10 @@ var McpServer = class {
         const rawName = params["name"];
         const name = typeof rawName === "string" ? rawName : "";
         const args = params["arguments"] ?? {};
-        const result = await handleToolCall(
-          this.client,
-          name,
-          args
+        const result = await this.withRetry(
+          () => handleToolCall(this.client, name, args)
         );
+        this.afterToolCall();
         return { jsonrpc: "2.0", id, result };
       }
       case "resources/read": {
@@ -3933,9 +4688,8 @@ var McpServer = class {
         const rawUri = params["uri"];
         const uri = typeof rawUri === "string" ? rawUri : "";
         try {
-          const result = await handleResourceRead(
-            this.client,
-            uri
+          const result = await this.withRetry(
+            () => handleResourceRead(this.client, uri)
           );
           return { jsonrpc: "2.0", id, result };
         } catch (err) {
@@ -4040,6 +4794,23 @@ var McpServer = class {
     const json = JSON.stringify(response);
     process.stdout.write(json + "\n");
   }
+  /**
+   * Records a tool call in the auto-capture controller and fires
+   * a capture when the trigger condition is met.
+   */
+  afterToolCall() {
+    const ctrl = this.autoCaptureController;
+    const cfg = this.autoCaptureConfig;
+    if (ctrl === null || cfg === null) return;
+    ctrl.recordToolCall();
+    void runAutoCapture(
+      ctrl,
+      cfg,
+      this.client,
+      this.hostCapabilities,
+      (messages, maxTokens) => this.requestSampling(messages, maxTokens)
+    );
+  }
   /**
    * Runs an integrity check immediately after the MCP handshake
    * completes. Emits a `notifications/message` warning when the
@@ -4064,8 +4835,15 @@ var McpServer = class {
 };
 
 // src/shared/mcp/functions/create-mcp-server.function.ts
-function createMcpServer(client) {
-  return new McpServer(client);
+function createMcpServer(client, contextPath, autoCaptureConfig, clientFactory, maxRetries) {
+  log("creating MCP server", 0 /* DEBUG */);
+  return new McpServer(
+    client,
+    contextPath,
+    autoCaptureConfig,
+    clientFactory,
+    maxRetries
+  );
 }
 
 // src/cli.ts
@@ -4074,18 +4852,36 @@ var baseDir = resolveBaseDir(import.meta.url, import.meta.dirname);
 var workerScript = resolveWorkerScript(baseDir.scriptDir, runtime);
 var deps = {
   isStdinTty,
+  isStdoutTty: () => process.stdout.isTTY,
   promptUser,
   createWorkerClient: (opts) => createWorkerClient({ ...opts, workerScript }),
   findDb,
   runInit,
-  startMcpServer: async (contextPath) => {
+  startMcpServer: async (contextPath, clientFactory, maxRetries) => {
+    log("starting MCP server", 1 /* INFO */);
     const client = await createWorkerClient({
       contextPath,
       workerScript
     });
     try {
-      const server = createMcpServer(client);
+      const tomlPath = join9(contextPath, "worker.toml");
+      let autoCaptureConfig;
+      try {
+        const tomlText = readFileSync4(tomlPath, "utf-8");
+        const daemonConfig = parseWorkerToml(tomlText, contextPath);
+        autoCaptureConfig = daemonConfig.autoCapture;
+      } catch {
+      }
+      const server = createMcpServer(
+        client,
+        contextPath,
+        autoCaptureConfig,
+        clientFactory,
+        maxRetries
+      );
+      log("MCP server listening on stdio", 0 /* DEBUG */);
       await server.listen();
+      log("MCP server closed", 1 /* INFO */);
     } finally {
       client.disconnect();
     }
@@ -4097,7 +4893,7 @@ async function main() {
     console.log(result.output);
   }
   if (result.error) {
-    console.error(result.error);
+    log(result.error, 3 /* ERROR */);
   }
   if (result.exitCode !== 0) {
     process.exitCode = result.exitCode;
@@ -4105,7 +4901,7 @@ async function main() {
 }
 main().catch((err) => {
   const msg = err instanceof Error ? err.message : String(err);
-  console.error(`error: ${msg}`);
+  log("error: " + msg, 3 /* ERROR */);
   process.exitCode = 1;
 });
 //# sourceMappingURL=cli.mjs.map