@dotdotgod/claude-code 0.3.2 → 0.3.3

package/README.md

@@ -34,6 +34,8 @@ Then use the bundled `/dd:*` commands in your repository:
 /dd:impact
 ```
 
+After an update, restart Claude Code and confirm the active plugin points to the new installed cache entry. Source changes do not rewrite an existing `~/.claude/plugins/cache/.../<hash>/`; reinstall the plugin through the supported flow if Claude continues using an older cache hash.
+
 For local development from a source checkout, load the plugin directory directly instead of installing:
 
 ```bash
@@ -45,7 +47,7 @@ claude --plugin-dir /path/to/dotdotgod/packages/claude-code
 | Command or skill | Use it for | Result |
 | --- | --- | --- |
 | `/dd:init` | Start a repository with dotdotgod conventions. | Creates or normalizes shared agent files, docs indexes, local-memory areas, and the complete default project config. |
-| `/dd:load` | Load project memory without changing maintained project files. | Renders the shared Markdown tree and uses `dotdotgod query` when focus text is provided; query may refresh ignored caches. |
+| `/dd:load` | Load project memory without changing maintained project files. | Renders the shared Markdown tree and uses `dotdotgod query` when focus text is provided; unavailable optional semantic routing falls back to the map with bounded evidence. |
 | `/dd:plan` | Plan before implementation. | Writes or updates durable task intent in `docs/plan/<task-slug>/README.md`. |
 | `/dd:impact` | Review changed files before verification or handoff. | Uses `dotdotgod graph impact` to identify likely related docs, tests, commands, and source files. |
 | `document-clarify` | Improve docs wording without changing behavior contracts. | Clarifies README/spec/test/arch/plan/archive docs using memory-area roles. |

package/hooks/runtime.mjs

@@ -4,7 +4,7 @@
 // packages/context/src/hooks.mjs
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, parse, resolve } from "node:path";
 function inputText() {
   return readFileSync(0, "utf8");
 }
@@ -12,24 +12,45 @@ function parseInput() {
   const text = inputText().trim();
   return text ? JSON.parse(text) : {};
 }
-function projectRoot(input) {
-  return resolve(input.cwd || input.project_dir || process.env.CLAUDE_PROJECT_DIR || process.cwd());
-}
 function sessionId(input) {
   return String(input.session_id || input.sessionId || "default").replace(/[^a-zA-Z0-9._-]/g, "_");
 }
-function statePath(input) {
-  return join(projectRoot(input), ".dotdotgod", "context", "runtime", `${sessionId(input)}.json`);
+function runtimeStatePath(root, id) {
+  return join(root, ".dotdotgod", "context", "runtime", `${id}.json`);
+}
+function declaredProjectRoot(input) {
+  const value = input.project_dir || process.env.CLAUDE_PROJECT_DIR;
+  return typeof value === "string" && value.trim() ? resolve(value) : null;
+}
+function findExistingStateRoot(cwd, id) {
+  let current = resolve(cwd);
+  const filesystemRoot = parse(current).root;
+  while (true) {
+    if (existsSync(runtimeStatePath(current, id))) return current;
+    if (current === filesystemRoot) return null;
+    current = dirname(current);
+  }
 }
-function readState(input) {
+function resolveHookContext(input, event) {
+  const id = sessionId(input);
+  const declared = declaredProjectRoot(input);
+  if (declared) return { root: declared, path: runtimeStatePath(declared, id) };
+  if (typeof input.cwd !== "string" || !input.cwd.trim()) return null;
+  const existing = findExistingStateRoot(input.cwd, id);
+  if (existing) return { root: existing, path: runtimeStatePath(existing, id) };
+  if (event !== "sessionstart") return null;
+  const root = resolve(input.cwd);
+  return { root, path: runtimeStatePath(root, id) };
+}
+function readState(path) {
   try {
-    return JSON.parse(readFileSync(statePath(input), "utf8"));
+    return JSON.parse(readFileSync(path, "utf8"));
   } catch {
     return { loadRequired: false, pending: {} };
   }
 }
-function writeState(input, state) {
-  const path = statePath(input);
+function writeState(path, state) {
+  if (!path) return;
   mkdirSync(dirname(path), { recursive: true });
   const temp = `${path}.${process.pid}.tmp`;
   writeFileSync(temp, `${JSON.stringify(state, null, 2)}
@@ -66,19 +87,21 @@ function isImpactGate(name, input) {
   if (!/^(Bash|Shell|local_shell|shell|shell_command|exec_command)$/i.test(name)) return false;
   return /(^|\s)(test|build|lint|verify|commit|push|publish|deploy)(\s|:|$)|\b(git\s+(commit|push)|npm\s+(test|publish)|pnpm\s+[^\n]*(test|build|lint|verify|publish))\b/i.test(commandFrom(input));
 }
-function changedPath(input) {
+function changedPath(input, root) {
   const value = toolInput(input);
   const path = value.file_path || value.path;
-  return typeof path === "string" ? resolve(projectRoot(input), path) : null;
+  return root && typeof path === "string" ? resolve(root, path) : null;
 }
 function runHook(event) {
   const input = parseInput();
   const name = toolName(input);
-  const state = readState(input);
+  const context = resolveHookContext(input, event);
+  const state = readState(context?.path);
   state.pending ||= {};
   if (event === "sessionstart") {
+    if (!context) return {};
     state.loadRequired = true;
-    writeState(input, state);
+    writeState(context.path, state);
     return { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: "Dotdotgod project memory has not been loaded for this session. Before substantive shell or write work, call dotdotgod_project_load once with a concise task-specific focus." } };
   }
   if (event === "pretooluse") {
@@ -89,18 +112,19 @@ function runHook(event) {
     return {};
   }
   if (event === "posttooluse") {
+    if (!context) return {};
     if (mcpTool(name, "dotdotgod_project_load")) state.loadRequired = false;
     else if (mcpTool(name, "dotdotgod_project_impact")) {
       const checked = toolInput(input).paths;
       if (Array.isArray(checked)) for (const path of checked) {
-        const absolute = resolve(projectRoot(input), path);
+        const absolute = resolve(context.root, path);
         if (state.pending[absolute] === fileHash(absolute)) delete state.pending[absolute];
       }
     } else if (/^(Edit|Write|apply_patch)$/i.test(name)) {
-      const path = changedPath(input);
+      const path = changedPath(input, context.root);
       if (path) state.pending[path] = fileHash(path);
     }
-    writeState(input, state);
+    writeState(context.path, state);
     return {};
   }
   return {};

package/mcp/cli.mjs

@@ -1309,6 +1309,20 @@ Create dotdotgod.config.json from a bundled or user template. Without --template
   dotdotgod query <root> <query> [--limit n] [--json]
 
 Search shared project documentation with the resolved local or remote embedding provider.`;
+    case "embedding":
+      return `Usage:
+  dotdotgod embedding status [<root>] [--json]
+  dotdotgod embedding install [<root>] --confirm [--json]`;
+    case "embedding status":
+      return `Usage:
+  dotdotgod embedding status [<root>] [--json]
+
+Inspect the optional persistent local embedding runtime without network access.`;
+    case "embedding install":
+      return `Usage:
+  dotdotgod embedding install [<root>] --confirm [--json]
+
+After user approval, install the fixed optional runtime persistently. Uses network access and dependency install scripts; the model may download on first query.`;
     case "map":
       return `Usage:
   dotdotgod map <root> [--depth <positive-integer>] [--json]
@@ -1351,6 +1365,7 @@ Commands:
   init                  Initialize project memory files.
   config                Inspect or initialize project configuration.
   query                 Search project documentation.
+  embedding             Inspect or install the optional local embedding runtime.
   map                   Render the project documentation map.
   resolve               Resolve a project reference.
   expand                Expand references in a prompt.
@@ -1403,6 +1418,7 @@ function helpCommandFromArgs(args) {
   if (nonHelp[0] === "graph" && nonHelp[1]) return `graph ${nonHelp[1]}`;
   if (nonHelp[0] === "traceability" && nonHelp[1]) return `traceability ${nonHelp[1]}`;
   if (nonHelp[0] === "config" && nonHelp[1] === "init") return "config init";
+  if (nonHelp[0] === "embedding" && nonHelp[1]) return `embedding ${nonHelp[1]}`;
   return nonHelp[0] ?? "root";
 }
 function parseCommon(argv) {
@@ -2709,6 +2725,74 @@ function collectDocumentationChunks(root, exclude, documentationRoot = "docs") {
   });
 }
 
+// packages/cli/src/query/embedding-runtime.mjs
+import { existsSync as existsSync12, mkdirSync as mkdirSync3, readFileSync as readFileSync11, rmSync, writeFileSync as writeFileSync4 } from "node:fs";
+import { spawnSync as spawnSync2 } from "node:child_process";
+import { createRequire } from "node:module";
+import { homedir as homedir3 } from "node:os";
+import { join as join11 } from "node:path";
+import { pathToFileURL } from "node:url";
+var EMBEDDING_RUNTIME_PACKAGE = "@huggingface/transformers";
+var EMBEDDING_RUNTIME_VERSION = "4.2.0";
+var EmbeddingRuntimeMissingError = class extends Error {
+  constructor() {
+    super("Optional local embedding runtime is not installed.");
+    this.name = "EmbeddingRuntimeMissingError";
+    this.code = "EMBEDDING_RUNTIME_MISSING";
+  }
+};
+function embeddingRuntimeRoot(options = {}) {
+  return join11(options.home ?? homedir3(), ".dotdotgod", "runtime", "embedding");
+}
+function resolvePersistentTransformers(options = {}) {
+  const root = embeddingRuntimeRoot(options);
+  try {
+    const require2 = createRequire(join11(root, "package.json"));
+    return require2.resolve(EMBEDDING_RUNTIME_PACKAGE);
+  } catch {
+    throw new EmbeddingRuntimeMissingError();
+  }
+}
+function embeddingRuntimeStatus(options = {}) {
+  const root = embeddingRuntimeRoot(options);
+  try {
+    const require2 = createRequire(join11(root, "package.json"));
+    const packagePath = require2.resolve(`${EMBEDDING_RUNTIME_PACKAGE}/package.json`);
+    const version = JSON.parse(readFileSync11(packagePath, "utf8")).version;
+    return { ok: true, installed: true, installAvailable: true, package: EMBEDDING_RUNTIME_PACKAGE, requiredVersion: EMBEDDING_RUNTIME_VERSION, packageVersion: version, location: root };
+  } catch {
+    return { ok: true, installed: false, installAvailable: true, package: EMBEDDING_RUNTIME_PACKAGE, requiredVersion: EMBEDDING_RUNTIME_VERSION, packageVersion: null, location: root };
+  }
+}
+function installEmbeddingRuntime(options = {}) {
+  if (options.confirm !== true) throw new Error("Embedding runtime installation requires explicit confirmation.");
+  const root = embeddingRuntimeRoot(options);
+  const lock = join11(root, ".installing");
+  if (existsSync12(lock)) throw new Error("Embedding runtime installation is already in progress.");
+  mkdirSync3(root, { recursive: true });
+  writeFileSync4(lock, `${process.pid}
+`, { flag: "wx" });
+  try {
+    const spawn = options.spawnImpl ?? spawnSync2;
+    const result = spawn(options.npmCommand ?? "npm", ["install", "--prefix", root, "--save-exact", "--omit=dev", "--no-audit", "--no-fund", `${EMBEDDING_RUNTIME_PACKAGE}@${EMBEDDING_RUNTIME_VERSION}`], { encoding: "utf8", timeout: options.timeoutMs ?? 3e5, shell: false, stdio: ["ignore", "pipe", "pipe"] });
+    if (result.error || result.status !== 0) throw new Error(result.error?.code === "ENOENT" ? "npm is unavailable." : "Embedding runtime installation failed.");
+    const status = embeddingRuntimeStatus({ home: options.home });
+    if (!status.installed) throw new Error("Embedding runtime installation could not be verified.");
+    return { ...status, command: "embedding install", modelDownloadPending: true };
+  } finally {
+    rmSync(lock, { force: true });
+  }
+}
+async function importTransformers(options = {}) {
+  try {
+    return await import(EMBEDDING_RUNTIME_PACKAGE);
+  } catch (error) {
+    if (error?.code !== "ERR_MODULE_NOT_FOUND") throw error;
+    const path = resolvePersistentTransformers(options);
+    return import(pathToFileURL(path).href);
+  }
+}
+
 // packages/cli/src/query/embedder.mjs
 var localPipelines = /* @__PURE__ */ new Map();
 function normalize(row) {
@@ -2719,7 +2803,7 @@ function normalize(row) {
 }
 async function localEmbedder(profile) {
   if (!localPipelines.has(profile.model)) {
-    localPipelines.set(profile.model, import("@huggingface/transformers").then(async ({ env, pipeline }) => {
+    localPipelines.set(profile.model, importTransformers().then(async ({ env, pipeline }) => {
       env.allowLocalModels = true;
       return pipeline("feature-extraction", profile.model);
     }));
@@ -2787,8 +2871,8 @@ async function resolveEmbedder(root, options = {}) {
 
 // packages/cli/src/query/store.mjs
 import { createHash as createHash4 } from "node:crypto";
-import { existsSync as existsSync12, mkdirSync as mkdirSync3, readFileSync as readFileSync11, renameSync, rmSync, writeFileSync as writeFileSync4 } from "node:fs";
-import { join as join11 } from "node:path";
+import { existsSync as existsSync13, mkdirSync as mkdirSync4, readFileSync as readFileSync12, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join12 } from "node:path";
 var VECTOR_SCHEMA_VERSION = 2;
 var VECTOR_DIMENSIONS = 384;
 function profileFingerprint(identity) {
@@ -2808,18 +2892,18 @@ function isValidNormalizedVectorValues(values, dimensions = VECTOR_DIMENSIONS) {
   return true;
 }
 function vectorCachePaths(root) {
-  const directory = join11(root, ".dotdotgod", "vectors");
-  return { directory, manifest: join11(directory, "manifest.json"), chunks: join11(directory, "chunks.jsonl"), embeddings: join11(directory, "embeddings.f32") };
+  const directory = join12(root, ".dotdotgod", "vectors");
+  return { directory, manifest: join12(directory, "manifest.json"), chunks: join12(directory, "chunks.jsonl"), embeddings: join12(directory, "embeddings.f32") };
 }
 function readVectorCache(root, identity = null) {
   const paths = vectorCachePaths(root);
-  if (!existsSync12(paths.manifest) || !existsSync12(paths.chunks) || !existsSync12(paths.embeddings)) return null;
+  if (!existsSync13(paths.manifest) || !existsSync13(paths.chunks) || !existsSync13(paths.embeddings)) return null;
   try {
-    const manifest = JSON.parse(readFileSync11(paths.manifest, "utf8"));
+    const manifest = JSON.parse(readFileSync12(paths.manifest, "utf8"));
     if (manifest.schemaVersion !== VECTOR_SCHEMA_VERSION || !Number.isInteger(manifest.dimensions) || manifest.dimensions < 1) return null;
     if (identity && manifest.profileFingerprint !== profileFingerprint(identity)) return null;
-    const chunks = readFileSync11(paths.chunks, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
-    const buffer = readFileSync11(paths.embeddings);
+    const chunks = readFileSync12(paths.chunks, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+    const buffer = readFileSync12(paths.embeddings);
     if (buffer.byteLength !== chunks.length * manifest.dimensions * 4) return null;
     const vectors = new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4);
     if (!isValidNormalizedVectorValues(vectors, manifest.dimensions)) return null;
@@ -2830,14 +2914,14 @@ function readVectorCache(root, identity = null) {
 }
 function atomicWrite(path, data) {
   const temporary = `${path}.tmp-${process.pid}`;
-  writeFileSync4(temporary, data);
+  writeFileSync5(temporary, data);
   renameSync(temporary, path);
 }
 function writeVectorCache(root, chunks, vectors, metadata = {}) {
   const paths = vectorCachePaths(root);
   const dimensions = metadata.dimensions;
   if (!Number.isInteger(dimensions) || dimensions < 1) throw new Error("Vector dimensions must be a positive integer.");
-  mkdirSync3(paths.directory, { recursive: true });
+  mkdirSync4(paths.directory, { recursive: true });
   if (vectors.length !== chunks.length * dimensions) throw new Error("Vector count does not match chunk metadata.");
   if (!isValidNormalizedVectorValues(vectors, dimensions)) throw new Error("Vectors must contain finite normalized values.");
   const manifest = { schemaVersion: VECTOR_SCHEMA_VERSION, chunks: chunks.length, generatedAt: (/* @__PURE__ */ new Date()).toISOString(), ...metadata };
@@ -2976,12 +3060,44 @@ async function runQuery(argv) {
   }
 }
 
+// packages/cli/src/commands/embedding.mjs
+import { resolve as resolve10 } from "node:path";
+function parse(argv) {
+  const [action2 = "status", ...rest] = argv;
+  let root = ".";
+  let json = false;
+  let confirm = false;
+  for (const arg of rest) {
+    if (arg === "--json") json = true;
+    else if (arg === "--confirm") confirm = true;
+    else if (!arg.startsWith("-") && root === ".") root = arg;
+    else usage(`Unknown embedding option: ${arg}`, `embedding ${action2}`);
+  }
+  return { action: action2, root: resolve10(root), json, confirm };
+}
+function runEmbedding(argv, options = {}) {
+  const parsed = parse(argv);
+  if (!["status", "install"].includes(parsed.action)) usage(`Unknown embedding command: ${parsed.action}`, "embedding");
+  const resolved = resolveEmbeddingProfile(parsed.root, options);
+  if (resolved.profile.provider !== "local") {
+    const result2 = { ok: true, command: `embedding ${parsed.action}`, provider: resolved.profile.provider, required: false, installed: false, installAvailable: false };
+    console.log(parsed.json ? JSON.stringify(result2, null, 2) : "Local embedding runtime is not required for the configured remote provider.");
+    return result2;
+  }
+  if (parsed.action === "install" && !parsed.confirm) usage("embedding install requires --confirm after user approval.", "embedding install");
+  const runtimeOptions = { home: options.home };
+  const result = parsed.action === "status" ? embeddingRuntimeStatus(runtimeOptions) : installEmbeddingRuntime({ ...runtimeOptions, confirm: true, spawnImpl: options.spawnImpl, npmCommand: options.npmCommand });
+  const payload = { ...result, command: `embedding ${parsed.action}`, provider: "local", required: true, ...parsed.action === "install" ? { disclosure: "Installation uses network access and dependency install scripts; the configured model may download on first query." } : {} };
+  console.log(parsed.json ? JSON.stringify(payload, null, 2) : payload.installed ? `Embedding runtime installed (${payload.packageVersion}).` : "Embedding runtime is not installed.");
+  return payload;
+}
+
 // packages/cli/src/commands/map.mjs
-import { resolve as resolve11 } from "node:path";
+import { resolve as resolve12 } from "node:path";
 
 // packages/cli/src/memory/documentation-map.mjs
-import { existsSync as existsSync13, readdirSync as readdirSync4, statSync as statSync6 } from "node:fs";
-import { join as join12, resolve as resolve10 } from "node:path";
+import { existsSync as existsSync14, readdirSync as readdirSync4, statSync as statSync6 } from "node:fs";
+import { join as join13, resolve as resolve11 } from "node:path";
 var SKIPPED_DIRECTORIES2 = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "coverage", ".git", ".dotdotgod"]);
 function node() {
   return { directories: /* @__PURE__ */ new Map(), files: [] };
@@ -3044,7 +3160,7 @@ function discoverMarkdown(root, documentationRoot, exclude) {
   const walk = (relativeDirectory) => {
     let entries;
     try {
-      entries = readdirSync4(join12(root, relativeDirectory), { withFileTypes: true, encoding: "utf8" });
+      entries = readdirSync4(join13(root, relativeDirectory), { withFileTypes: true, encoding: "utf8" });
     } catch {
       return;
     }
@@ -3061,8 +3177,8 @@ function discoverMarkdown(root, documentationRoot, exclude) {
   return paths.sort();
 }
 function buildDocumentationMap(projectRoot = ".", { depth = 5 } = {}) {
-  const root = resolve10(projectRoot);
-  if (!existsSync13(root)) return { ok: false, error: { code: "ROOT_NOT_FOUND", message: `Project root not found: ${root}` } };
+  const root = resolve11(projectRoot);
+  if (!existsSync14(root)) return { ok: false, error: { code: "ROOT_NOT_FOUND", message: `Project root not found: ${root}` } };
   try {
     if (!statSync6(root).isDirectory()) return { ok: false, error: { code: "ROOT_NOT_FOUND", message: `Project root not found: ${root}` } };
   } catch {
@@ -3110,7 +3226,7 @@ function parseMapOptions(argv) {
     } else if (!arg.startsWith("-")) fail(options.json, "UNEXPECTED_ARGUMENT", `Unexpected argument: ${arg}`);
     else fail(options.json, "UNKNOWN_OPTION", `Unknown option: ${arg}`);
   }
-  options.root = resolve11(options.root);
+  options.root = resolve12(options.root);
   return options;
 }
 function runMap(argv) {
@@ -3122,7 +3238,7 @@ function runMap(argv) {
 }
 
 // packages/cli/src/reference/resolve.mjs
-import { resolve as resolve13 } from "node:path";
+import { resolve as resolve14 } from "node:path";
 
 // node_modules/.pnpm/leiden-ts@0.1.0/node_modules/leiden-ts/dist/index.js
 var GraphValidationError = class extends Error {
@@ -4493,15 +4609,15 @@ function compareImpactItems(seeds) {
 }
 
 // packages/cli/src/impact/vector-profile.mjs
-import { lstatSync, readFileSync as readFileSync12, realpathSync } from "node:fs";
-import { extname as extname5, relative as relative4, resolve as resolve12, sep } from "node:path";
+import { lstatSync, readFileSync as readFileSync13, realpathSync } from "node:fs";
+import { extname as extname5, relative as relative4, resolve as resolve13, sep } from "node:path";
 var MAX_VECTOR_PROFILE_FILE_BYTES = 64 * 1024;
 var MAX_VECTOR_PROFILE_CHARS = 4e3;
 var MAX_VECTOR_PROFILE_METADATA_ITEMS = 20;
 var TEXT_EXTENSIONS = /* @__PURE__ */ new Set([".c", ".cc", ".cpp", ".css", ".go", ".h", ".hpp", ".html", ".java", ".js", ".json", ".jsx", ".md", ".mjs", ".py", ".rb", ".rs", ".sh", ".ts", ".tsx", ".txt", ".yaml", ".yml"]);
 var GENERATED_SEGMENTS = /* @__PURE__ */ new Set([".dotdotgod", "build", "coverage", "dist", "node_modules"]);
 function insideRoot(root, absolute) {
-  const normalizedRoot = resolve12(root);
+  const normalizedRoot = resolve13(root);
   return absolute === normalizedRoot || absolute.startsWith(`${normalizedRoot}${sep}`);
 }
 function normalizeChangedPath(path) {
@@ -4512,8 +4628,8 @@ function normalizeChangedPath(path) {
 function canonicalizeChangedPath(root, path) {
   const normalized = normalizeChangedPath(path);
   if (!normalized) return null;
-  const rootAbsolute = resolve12(root);
-  const absolute = resolve12(rootAbsolute, normalized);
+  const rootAbsolute = resolve13(root);
+  const absolute = resolve13(rootAbsolute, normalized);
   if (!insideRoot(rootAbsolute, absolute)) return normalized;
   try {
     const canonicalRoot = realpathSync(rootAbsolute);
@@ -4544,7 +4660,7 @@ function graphMetadata(graph, seedId) {
 function safeTextPrefix(root, path) {
   if (unsafeProfilePath(path) || !TEXT_EXTENSIONS.has(extname5(path).toLowerCase())) return "";
   try {
-    const absolute = resolve12(root, path);
+    const absolute = resolve13(root, path);
     if (!insideRoot(root, absolute)) return "";
     const canonicalAbsolute = realpathSync(absolute);
     if (!insideRoot(realpathSync(root), canonicalAbsolute)) return "";
@@ -4552,7 +4668,7 @@ function safeTextPrefix(root, path) {
     if (canonicalPath !== path || unsafeProfilePath(canonicalPath) || !TEXT_EXTENSIONS.has(extname5(canonicalPath).toLowerCase())) return "";
     const stats = lstatSync(canonicalAbsolute);
     if (!stats.isFile() || stats.isSymbolicLink() || stats.size > MAX_VECTOR_PROFILE_FILE_BYTES) return "";
-    const buffer = readFileSync12(canonicalAbsolute);
+    const buffer = readFileSync13(canonicalAbsolute);
     if (buffer.includes(0)) return "";
     const text = new TextDecoder("utf-8", { fatal: true }).decode(buffer);
     return text.slice(0, MAX_VECTOR_PROFILE_CHARS);
@@ -4945,7 +5061,7 @@ function parseReferenceOptions(argv, command) {
     else filtered.push(arg);
   }
   const operands = filtered.filter((arg) => !arg.startsWith("-"));
-  return { ...options, root: resolve13(operands[0] ?? "."), json: filtered.includes("--json"), rootArgv: operands.slice(1) };
+  return { ...options, root: resolve14(operands[0] ?? "."), json: filtered.includes("--json"), rootArgv: operands.slice(1) };
 }
 function formatReferenceOutput(payload) {
   const refreshNote = payload.metadata.cacheRefreshed ? ", refreshed" : "";
@@ -4994,15 +5110,15 @@ function runExpand(argv) {
 }
 
 // packages/cli/src/commands/traceability.mjs
-import { existsSync as existsSync14, readFileSync as readFileSync13, readdirSync as readdirSync5, writeFileSync as writeFileSync5 } from "node:fs";
-import { join as join13, resolve as resolve14 } from "node:path";
+import { existsSync as existsSync15, readFileSync as readFileSync14, readdirSync as readdirSync5, writeFileSync as writeFileSync6 } from "node:fs";
+import { join as join14, resolve as resolve15 } from "node:path";
 function collectDocsMarkdownFiles(root) {
-  const docs = join13(root, "docs");
+  const docs = join14(root, "docs");
   const files = [];
   const walk = (dir) => {
-    if (!existsSync14(dir)) return;
+    if (!existsSync15(dir)) return;
     for (const entry of readdirSync5(dir, { withFileTypes: true })) {
-      const path = join13(dir, entry.name);
+      const path = join14(dir, entry.name);
       if (entry.isDirectory()) walk(path);
       else if (entry.isFile() && entry.name.endsWith(".md")) files.push(path);
     }
@@ -5027,7 +5143,7 @@ function parseTraceabilityOptions(argv) {
   }
   if (options.check && options.write) usage("Choose only one traceability links mode: --check or --write.", "traceability links");
   options.check = options.check || !options.write;
-  options.root = resolve14(options.root);
+  options.root = resolve15(options.root);
   return options;
 }
 function runTraceability(argv) {
@@ -5038,7 +5154,7 @@ function runTraceability(argv) {
   const errors = [...config.errors ?? []];
   for (const file of files) {
     if (options.write && errors.length > 0) break;
-    const content = readFileSync13(file, "utf8");
+    const content = readFileSync14(file, "utf8");
     for (const error of validateTraceabilityLinksRegion(content, options.root, file)) errors.push(error);
     const blocks = extractDotdotgodTraceabilityBlocks(content).filter((block) => !block.error);
     if (blocks.length === 0) continue;
@@ -5047,7 +5163,7 @@ function runTraceability(argv) {
       for (const error of result.errors ?? []) errors.push(error);
       continue;
     }
-    if (options.write && result.changed) writeFileSync5(file, result.content);
+    if (options.write && result.changed) writeFileSync6(file, result.content);
     if (result.changed) results.push({ file: rel(options.root, file), changed: true });
   }
   const ok = errors.length === 0 && (!options.check || results.length === 0);
@@ -5253,6 +5369,7 @@ async function runCli(argv = process.argv.slice(2)) {
   else if (command === "config") runConfig(args);
   else if (command === "status") runStatus(args);
   else if (command === "query") await runQuery(args);
+  else if (command === "embedding") runEmbedding(args);
   else if (command === "map") runMap(args);
   else if (command === "resolve") runResolve(args);
   else if (command === "expand") runExpand(args);

package/mcp/server.mjs

@@ -23179,10 +23179,37 @@ async function cliJson(args, cwd) {
 }
 async function projectLoad(input) {
   const root2 = resolve5(input.root || process.cwd());
-  const tree = markdownTree(root2, input.maxDepth ?? (input.focus ? 3 : 5));
+  const focus = input.focus?.trim() ?? "";
+  const tree = markdownTree(root2, input.maxDepth ?? (focus ? 3 : 5));
   let query = null;
-  if (input.focus?.trim()) query = await cliJson(["query", root2, input.focus.trim(), "--limit", String(Math.min(input.limit ?? 30, 30)), "--json"], root2);
-  return { ok: true, root: root2, focus: input.focus?.trim() ?? "", documentationTree: tree, query };
+  let queryUnavailable;
+  if (focus) {
+    try {
+      query = await cliJson(["query", root2, focus, "--limit", String(Math.min(input.limit ?? 30, 30)), "--json"], root2);
+    } catch (error2) {
+      const missingRuntime = String(error2?.message ?? error2).includes("Optional local embedding runtime is not installed");
+      queryUnavailable = missingRuntime ? {
+        code: "EMBEDDING_RUNTIME_MISSING",
+        message: "Local semantic search requires an optional embedding runtime; continue with the documentation map or ask the user before installation.",
+        recovery: { kind: "embedding-runtime-install", requiresConfirmation: true, statusTool: "dotdotgod_embedding_status", installTool: "dotdotgod_embedding_install", cliCommand: "dotdotgod embedding install --confirm" }
+      } : {
+        code: "QUERY_UNAVAILABLE",
+        message: "Semantic project query is unavailable; continue with the documentation map and targeted reads."
+      };
+    }
+  }
+  return { ok: true, root: root2, focus, documentationTree: tree, query, ...queryUnavailable ? { queryUnavailable } : {} };
+}
+async function projectEmbeddingStatus(input = {}) {
+  const root2 = resolve5(input.root || process.cwd());
+  const result = await cliJson(["embedding", "status", root2, "--json"], root2);
+  return { ...result, ...result.location ? { location: "~/.dotdotgod/runtime/embedding" } : {} };
+}
+async function projectEmbeddingInstall(input = {}) {
+  if (input.confirm !== true) throw new Error("confirm: true is required after explicit user approval.");
+  const root2 = resolve5(input.root || process.cwd());
+  const result = await cliJson(["embedding", "install", root2, "--confirm", "--json"], root2);
+  return { ...result, ...result.location ? { location: "~/.dotdotgod/runtime/embedding" } : {} };
 }
 async function projectImpact(input) {
   const root2 = resolve5(input.root || process.cwd());
@@ -23216,10 +23243,13 @@ var IngestionJobRunner = class {
     this.renderer = renderer;
     this.running = false;
     this.scheduled = false;
+    this.closed = false;
+    this.pumpPromise = void 0;
     this.controllers = /* @__PURE__ */ new Map();
     this.schedule();
   }
   enqueue(kind, input) {
+    if (this.closed) throw new Error("Ingestion job runner is closed.");
     if (!["index", "fetch"].includes(kind)) throw new Error("Unsupported ingestion job kind.");
     const job = this.store.createJob({ kind, input, sessionId: this.sessionId ?? null });
     this.schedule();
@@ -23233,18 +23263,31 @@ var IngestionJobRunner = class {
     return this.store.cancelJob(id);
   }
   schedule() {
-    if (this.scheduled || this.running) return;
+    if (this.closed || this.scheduled || this.running) return;
     this.scheduled = true;
     queueMicrotask(() => {
       this.scheduled = false;
-      void this.pump();
+      if (this.closed) return;
+      const pending = this.pump();
+      this.pumpPromise = pending;
+      const clearPending = () => {
+        if (this.pumpPromise === pending) this.pumpPromise = void 0;
+      };
+      void pending.then(clearPending, clearPending);
     });
   }
+  async close() {
+    this.closed = true;
+    for (const controller of this.controllers.values()) controller.abort();
+    if (this.scheduled) await Promise.resolve();
+    await this.pumpPromise;
+  }
   async pump() {
-    if (this.running) return;
+    if (this.closed || this.running) return;
     this.running = true;
     try {
       for (; ; ) {
+        if (this.closed) break;
         const job = this.store.claimNextJob();
         if (!job) break;
         const controller = new AbortController();
@@ -23259,7 +23302,7 @@ var IngestionJobRunner = class {
         } finally {
           this.controllers.delete(job.id);
         }
-        await new Promise((resolve6) => setImmediate(resolve6));
+        if (!this.closed) await new Promise((resolve6) => setImmediate(resolve6));
       }
     } finally {
       this.running = false;
@@ -23427,10 +23470,11 @@ register("session_resume", "Use an explicit opaque session ID for subsequent con
 register("ingestion_job_start", "Queue one durable bounded background index or strict-fetch ingestion job.", phase3Shape("ingestion_job_start"), (input) => ({ ok: true, job: getJobs().enqueue(input.kind, input.input) }));
 register("ingestion_job_status", "Return bounded status for one background ingestion job.", phase3Shape("ingestion_job_status"), (input) => ({ ok: true, job: getJobs().status(input.id) }), { readOnlyHint: true });
 register("ingestion_job_cancel", "Cancel one queued or running background ingestion job.", phase3Shape("ingestion_job_cancel"), (input) => ({ ok: true, ...getJobs().cancel(input.id) }), { destructiveHint: true });
-register("context_heal", "Explicitly back up and migrate only a recognized recoverable context database.", phase3Shape("context_heal"), () => {
+register("context_heal", "Explicitly back up and migrate only a recognized recoverable context database.", phase3Shape("context_heal"), async () => {
+  await jobRunner?.close();
+  jobRunner = void 0;
   contextStore?.close();
   contextStore = void 0;
-  jobRunner = void 0;
   return healContextDatabase(root);
 }, { destructiveHint: true });
 register("stats", "Report local context store counts and location.", {}, () => ({ ok: true, sessionId, ...getStore().stats() }), { readOnlyHint: true });
@@ -23447,6 +23491,8 @@ register("dotdotgod_project_load", "Load a bounded documentation map and optiona
   limit: external_exports.number().int().min(1).max(30).optional(),
   maxDepth: external_exports.number().int().min(1).max(5).optional()
 }, (input) => projectLoad(projectInput(input)), { readOnlyHint: true });
+register("dotdotgod_embedding_status", "Inspect the optional persistent embedding runtime without installing or contacting a registry.", { root: external_exports.string().optional() }, (input) => projectEmbeddingStatus(projectInput(input)), { readOnlyHint: true });
+register("dotdotgod_embedding_install", "After explicit user approval, install the fixed optional embedding runtime persistently. Uses network and dependency install scripts.", { root: external_exports.string().optional(), confirm: external_exports.literal(true) }, (input) => projectEmbeddingInstall(projectInput(input)), { destructiveHint: true, openWorldHint: true });
 register("dotdotgod_project_impact", "Run bounded graph impact for up to 20 changed paths.", {
   root: external_exports.string().optional(),
   paths: external_exports.array(external_exports.string()).min(1).max(20)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/claude-code",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Claude Code adapter for dotdotgod project memory workflows.",
   "type": "module",
   "license": "Elastic-2.0",
@@ -23,12 +23,9 @@
   "engines": {
     "node": ">=22.5.0"
   },
-  "dependencies": {
-    "@huggingface/transformers": "^4.2.0"
-  },
   "devDependencies": {
     "esbuild": "0.27.3",
-    "@dotdotgod/context": "0.3.2"
+    "@dotdotgod/context": "0.3.3"
   },
   "files": [
     ".claude-plugin",