mindgraph-mcp 0.13.5 → 0.14.1

package/dist/index.js

@@ -1,22 +1,1439 @@
 "use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 
 // src/index.ts
 var import_server = require("@modelcontextprotocol/sdk/server/index.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 var import_types = require("@modelcontextprotocol/sdk/types.js");
+var import_mindgraph2 = require("mindgraph");
+
+// src/error-detail.ts
 var import_mindgraph = require("mindgraph");
+function errorDetail(e) {
+  if (e instanceof import_mindgraph.MindGraphError && e.body !== void 0) {
+    const detail = typeof e.body === "string" ? e.body : JSON.stringify(e.body);
+    return `${e.message} \u2014 ${detail}`;
+  }
+  return e instanceof Error ? e.message : String(e);
+}
+
+// src/codegraph.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_promises = require("fs/promises");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var import_node_crypto = require("crypto");
+var DEFAULT_TIMEOUT_MS = 5e3;
+var DEFAULT_STATUS_TTL_MS = 6e4;
+var MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
+function normalizePath(path2) {
+  return path2.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+function normalizeSignature(signature) {
+  return signature.replace(/\s+/g, " ").trim();
+}
+function languageFromPath(path2) {
+  const extension = (0, import_node_path.extname)(path2).toLowerCase();
+  return {
+    ".c": "c",
+    ".cc": "cpp",
+    ".cpp": "cpp",
+    ".go": "go",
+    ".java": "java",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".kt": "kotlin",
+    ".py": "python",
+    ".rb": "ruby",
+    ".rs": "rust",
+    ".swift": "swift",
+    ".ts": "typescript",
+    ".tsx": "typescript"
+  }[extension] ?? "unknown";
+}
+function asNode(hit) {
+  return hit.node ?? hit;
+}
+function toCandidate(node) {
+  if (!node.filePath || !node.kind || !(node.qualifiedName || node.name)) return null;
+  return {
+    path: normalizePath(node.filePath),
+    language: node.language ?? languageFromPath(node.filePath),
+    kind: node.kind,
+    qualifiedName: node.qualifiedName ?? node.name ?? "",
+    signature: node.signature ?? null,
+    startLine: node.startLine ?? 1,
+    endLine: node.endLine ?? node.startLine ?? 1
+  };
+}
+function normalizeRemote(remote) {
+  const trimmed = remote.trim();
+  if (!trimmed) return null;
+  const scp = /^(?:[^@]+@)?([^:]+):(.+)$/.exec(trimmed);
+  if (scp && !trimmed.includes("://")) {
+    return `${scp[1].toLowerCase()}/${scp[2].replace(/\.git$/, "")}`;
+  }
+  try {
+    const url = new URL(trimmed);
+    const pathname = url.pathname.replace(/\/$/, "").replace(/\.git$/, "");
+    return `${url.host.toLowerCase()}${pathname}`;
+  } catch {
+    return null;
+  }
+}
+function pathContains(root, candidate) {
+  const child = (0, import_node_path.relative)(root, candidate);
+  return child === "" || child !== ".." && !child.startsWith(`..${import_node_path.sep}`) && !(0, import_node_path.isAbsolute)(child);
+}
+function nearestExistingDirectory(candidate) {
+  let current = (0, import_node_path.resolve)(candidate);
+  for (; ; ) {
+    if ((0, import_node_fs.existsSync)(current)) {
+      try {
+        return (0, import_node_fs.statSync)(current).isDirectory() ? current : (0, import_node_path.dirname)(current);
+      } catch {
+      }
+    }
+    const parent = (0, import_node_path.dirname)(current);
+    if (parent === current) return current;
+    current = parent;
+  }
+}
+function findWorkspaceFile(start, explicit) {
+  if (explicit) return (0, import_node_path.resolve)(start, explicit);
+  let current = (0, import_node_path.resolve)(start);
+  for (; ; ) {
+    const candidate = (0, import_node_path.join)(current, ".mindgraph", "workspace.json");
+    if ((0, import_node_fs.existsSync)(candidate)) return candidate;
+    const parent = (0, import_node_path.dirname)(current);
+    if (parent === current) return void 0;
+    current = parent;
+  }
+}
+async function runProcess(executable, args, timeoutMs, env, cwd) {
+  return await new Promise((resolvePromise, rejectPromise) => {
+    const child = (0, import_node_child_process.spawn)(executable, args, {
+      cwd,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true
+    });
+    const stdout = [];
+    const stderr = [];
+    let outputBytes = 0;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      setTimeout(() => child.kill("SIGKILL"), 250).unref();
+    }, timeoutMs);
+    timer.unref();
+    const collect = (target) => (chunk) => {
+      outputBytes += chunk.length;
+      if (outputBytes > MAX_OUTPUT_BYTES) {
+        child.kill("SIGTERM");
+        return;
+      }
+      target.push(chunk);
+    };
+    child.stdout.on("data", collect(stdout));
+    child.stderr.on("data", collect(stderr));
+    child.on("error", (cause) => {
+      clearTimeout(timer);
+      const error = new Error(cause.message);
+      error.kind = cause.code === "ENOENT" ? "absent" : "command_failed";
+      rejectPromise(error);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        const error = new Error(`command timed out after ${timeoutMs}ms`);
+        error.kind = "timeout";
+        rejectPromise(error);
+        return;
+      }
+      if (outputBytes > MAX_OUTPUT_BYTES) {
+        const error = new Error("codegraph output exceeded 5 MiB");
+        error.kind = "command_failed";
+        rejectPromise(error);
+        return;
+      }
+      if (code !== 0) {
+        const error = new Error(Buffer.concat(stderr).toString("utf8").trim());
+        error.kind = "command_failed";
+        error.exitCode = code;
+        rejectPromise(error);
+        return;
+      }
+      resolvePromise(Buffer.concat(stdout).toString("utf8"));
+    });
+  });
+}
+var CodegraphAdapter = class {
+  timeoutMs;
+  statusTtlMs;
+  env;
+  cwd;
+  workspaceFile;
+  now;
+  identityCache = /* @__PURE__ */ new Map();
+  statusCache = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.statusTtlMs = options.statusTtlMs ?? DEFAULT_STATUS_TTL_MS;
+    this.env = options.env ?? process.env;
+    this.cwd = options.cwd ?? process.cwd();
+    this.workspaceFile = findWorkspaceFile(
+      this.cwd,
+      options.workspaceFile ?? this.env.MINDGRAPH_WORKSPACE_FILE
+    );
+    this.now = options.now ?? Date.now;
+  }
+  async resolveRepository(repo, fallbackSpaceUid) {
+    const configured = await this.resolveRepositories(fallbackSpaceUid);
+    const selected = repo && configured.find((candidate) => candidate.repoId === repo) || repo && configured.find(
+      (candidate) => candidate.repoRoot === repo || (0, import_node_path.basename)(candidate.repoRoot) === repo
+    ) || (!repo ? [...configured].sort((a, b) => b.repoRoot.length - a.repoRoot.length).find((candidate) => pathContains(candidate.repoRoot, this.cwd)) : void 0) || (!repo && configured.length === 1 ? configured[0] : void 0);
+    if (selected) {
+      return !repo && this.env.MINDGRAPH_REPO_ID ? this.resolveRepositoryIdentity(
+        selected.repoRoot,
+        this.env.MINDGRAPH_REPO_ID,
+        selected.spaceUid
+      ) : selected;
+    }
+    const requestedRoot = repo || this.env.MINDGRAPH_REPO_ROOT || this.cwd;
+    const requestedPath = await (0, import_promises.realpath)((0, import_node_path.resolve)(this.cwd, requestedRoot)).catch(
+      () => (0, import_node_path.resolve)(this.cwd, requestedRoot)
+    );
+    const repoRoot = await this.gitRoot(requestedPath) ?? requestedPath;
+    return this.resolveRepositoryIdentity(
+      repoRoot,
+      this.env.MINDGRAPH_REPO_ID,
+      this.env.MINDGRAPH_CODE_SPACE_UID || fallbackSpaceUid
+    );
+  }
+  async resolveRepositories(fallbackSpaceUid) {
+    return Promise.all(
+      this.configuredRepositories().map(
+        (repository) => this.resolveRepositoryIdentity(
+          repository.repoRoot,
+          repository.repoId,
+          repository.spaceUid || this.env.MINDGRAPH_CODE_SPACE_UID || fallbackSpaceUid
+        )
+      )
+    );
+  }
+  async resolveRepositoryIdentity(root, explicitRepoId, spaceUid) {
+    const repoRoot = await (0, import_promises.realpath)(root).catch(() => (0, import_node_path.resolve)(root));
+    const cacheKey = `${repoRoot}\0${explicitRepoId ?? ""}\0${spaceUid ?? ""}`;
+    const cached = this.identityCache.get(cacheKey);
+    if (cached) return cached;
+    const pending = this.loadRepositoryIdentity(repoRoot, explicitRepoId, spaceUid);
+    this.identityCache.set(cacheKey, pending);
+    return pending;
+  }
+  async loadRepositoryIdentity(repoRoot, explicitRepoId, spaceUid) {
+    const remote = await runProcess(
+      "git",
+      ["-C", repoRoot, "config", "--get", "remote.origin.url"],
+      Math.min(this.timeoutMs, 2e3),
+      this.env
+    ).catch(() => "");
+    const repoId = explicitRepoId || normalizeRemote(remote) || await this.persistedRepositoryId(repoRoot);
+    return {
+      repoId,
+      repoRoot,
+      spaceUid
+    };
+  }
+  async persistedRepositoryId(repoRoot) {
+    const rawCommonDir = await runProcess(
+      "git",
+      ["-C", repoRoot, "rev-parse", "--git-common-dir"],
+      Math.min(this.timeoutMs, 2e3),
+      this.env
+    ).catch(() => "");
+    if (!rawCommonDir.trim()) {
+      return `local:${(0, import_node_path.basename)(repoRoot)}`;
+    }
+    const commonDir = (0, import_node_path.resolve)(repoRoot, rawCommonDir.trim());
+    const identityDir = (0, import_node_path.join)(commonDir, "mindgraph");
+    const identityFile = (0, import_node_path.join)(identityDir, "repository-id");
+    try {
+      const existing = (0, import_node_fs.readFileSync)(identityFile, "utf8").trim();
+      if (existing) return existing;
+    } catch {
+    }
+    (0, import_node_fs.mkdirSync)(identityDir, { recursive: true, mode: 448 });
+    const generated = (0, import_node_crypto.randomUUID)();
+    try {
+      (0, import_node_fs.writeFileSync)(identityFile, `${generated}
+`, {
+        encoding: "utf8",
+        flag: "wx",
+        mode: 384
+      });
+      return generated;
+    } catch (cause) {
+      if (cause.code !== "EEXIST") throw cause;
+      const winner = (0, import_node_fs.readFileSync)(identityFile, "utf8").trim();
+      if (!winner) throw new Error(`empty repository identity file: ${identityFile}`);
+      return winner;
+    }
+  }
+  async gitRoot(candidate) {
+    const start = nearestExistingDirectory(candidate);
+    const raw = await runProcess(
+      "git",
+      ["-C", start, "rev-parse", "--show-toplevel"],
+      Math.min(this.timeoutMs, 2e3),
+      this.env
+    ).catch(() => "");
+    return raw.trim() ? (0, import_node_path.resolve)(start, raw.trim()) : void 0;
+  }
+  async availability(repository) {
+    const cached = this.statusCache.get(repository.repoRoot);
+    if (cached && cached.expiresAt > this.now()) return cached.availability;
+    try {
+      const status = await this.runJson([
+        "status",
+        repository.repoRoot,
+        "-j"
+      ]);
+      const caveats = [];
+      let availability;
+      if (status.worktreeMismatch != null) {
+        availability = {
+          available: false,
+          reason: "wrong_index",
+          stale: false,
+          caveats: ["the index belongs to a different worktree"],
+          lastIndexed: status.lastIndexed
+        };
+      } else if (!status.initialized || status.index?.state !== "complete") {
+        availability = {
+          available: false,
+          reason: "index_incomplete",
+          stale: false,
+          caveats: [
+            !status.initialized ? "codegraph is not initialized for this repository" : `codegraph index state is ${status.index?.state ?? "unknown"}`
+          ],
+          lastIndexed: status.lastIndexed
+        };
+      } else {
+        const pending = (status.pendingChanges?.added ?? 0) + (status.pendingChanges?.modified ?? 0) + (status.pendingChanges?.removed ?? 0);
+        if (pending > 0) caveats.push(`${pending} worktree changes are not indexed`);
+        if ((status.index?.pendingRefs ?? 0) > 0) {
+          caveats.push(`${status.index?.pendingRefs} references remain pending`);
+        }
+        if (status.index?.reindexRecommended) caveats.push("codegraph recommends reindexing");
+        availability = {
+          available: true,
+          stale: caveats.length > 0,
+          caveats,
+          lastIndexed: status.lastIndexed
+        };
+      }
+      this.statusCache.set(repository.repoRoot, {
+        status,
+        availability,
+        expiresAt: this.now() + this.statusTtlMs
+      });
+      return availability;
+    } catch (cause) {
+      const failure = cause;
+      return {
+        available: false,
+        reason: failure.kind ?? "command_failed",
+        stale: false,
+        caveats: [failure.message || "codegraph status failed"]
+      };
+    }
+  }
+  async resolveRefs(refs, options = {}) {
+    const normalized = refs.map(
+      (ref) => typeof ref === "string" ? { symbol: ref } : ref
+    );
+    const results = await Promise.all(
+      normalized.map(async (ref) => {
+        const repository2 = await this.repositoryForRef(
+          ref,
+          options.repo,
+          options.fallbackSpaceUid
+        );
+        const availability2 = await this.availability(repository2);
+        if (!availability2.available) {
+          return {
+            ref,
+            repository: repository2,
+            availability: availability2,
+            candidates: [],
+            error: availability2.reason
+          };
+        }
+        return {
+          ...await this.resolveOne(ref, repository2),
+          repository: repository2,
+          availability: availability2
+        };
+      })
+    );
+    const repositories = [
+      ...new Map(
+        results.flatMap(
+          (result) => result.repository ? [[result.repository.repoRoot, result.repository]] : []
+        )
+      ).values()
+    ];
+    const repository = repositories[0] ?? await this.resolveRepository(options.repo, options.fallbackSpaceUid);
+    if (repositories.length === 0) repositories.push(repository);
+    const availabilities = results.flatMap(
+      (result) => result.availability ? [result.availability] : []
+    );
+    const availability = availabilities.length === 0 ? await this.availability(repository) : {
+      available: availabilities.every((item) => item.available),
+      reason: availabilities.find((item) => !item.available)?.reason,
+      stale: availabilities.some((item) => item.stale),
+      caveats: [
+        ...new Set(availabilities.flatMap((item) => item.caveats))
+      ]
+    };
+    return { repository, repositories, availability, results };
+  }
+  async repositoryForRef(ref, defaultRepo, fallbackSpaceUid) {
+    if (ref.repo || defaultRepo) {
+      return this.resolveRepository(ref.repo || defaultRepo, fallbackSpaceUid);
+    }
+    if (ref.path) {
+      const requested = (0, import_node_path.isAbsolute)(ref.path) ? (0, import_node_path.resolve)(ref.path) : (0, import_node_path.resolve)(this.cwd, ref.path);
+      const absolute = await (0, import_promises.realpath)(requested).catch(() => requested);
+      const configured = await this.resolveRepositories(fallbackSpaceUid);
+      const defining = [...configured].sort((a, b) => b.repoRoot.length - a.repoRoot.length).find((candidate) => pathContains(candidate.repoRoot, absolute));
+      if (defining) {
+        return this.env.MINDGRAPH_REPO_ID && pathContains(defining.repoRoot, this.cwd) ? this.resolveRepositoryIdentity(
+          defining.repoRoot,
+          this.env.MINDGRAPH_REPO_ID,
+          defining.spaceUid
+        ) : defining;
+      }
+      const gitRoot = await this.gitRoot(absolute);
+      if (gitRoot) {
+        return this.resolveRepositoryIdentity(
+          gitRoot,
+          this.env.MINDGRAPH_REPO_ID,
+          this.env.MINDGRAPH_CODE_SPACE_UID || fallbackSpaceUid
+        );
+      }
+    }
+    return this.resolveRepository(void 0, fallbackSpaceUid);
+  }
+  async expand(resolved, limit = 20) {
+    const repository = {
+      repoId: resolved.repoId,
+      repoRoot: resolved.repoRoot
+    };
+    const availability = await this.availability(repository);
+    if (!availability.available) {
+      return { availability, callers: [], callees: [], truncated: false };
+    }
+    const cap = Math.min(Math.max(limit, 1), 20);
+    const [callers, callees] = await Promise.all([
+      this.related("callers", resolved, cap + 1),
+      this.related("callees", resolved, cap + 1)
+    ]);
+    return {
+      availability,
+      callers: callers.slice(0, cap),
+      callees: callees.slice(0, cap),
+      truncated: callers.length > cap || callees.length > cap
+    };
+  }
+  async affected(resolved, limit = 50) {
+    const repository = {
+      repoId: resolved.repoId,
+      repoRoot: resolved.repoRoot
+    };
+    const availability = await this.availability(repository);
+    if (!availability.available) {
+      return { availability, affected: [], truncated: false };
+    }
+    const cap = Math.min(Math.max(limit, 1), 50);
+    const raw = await this.runJson([
+      "impact",
+      "-p",
+      resolved.repoRoot,
+      "-j",
+      "-d",
+      "2",
+      resolved.qualifiedName
+    ]);
+    const refs = (raw.affected ?? []).map((node) => ({
+      path: node.filePath,
+      line: node.startLine,
+      symbol: node.qualifiedName ?? node.name,
+      kind: node.kind
+    }));
+    const resolvedRefs = await this.resolveRelatedRefs(refs.slice(0, cap + 1), repository);
+    return {
+      availability,
+      affected: resolvedRefs.slice(0, cap),
+      truncated: refs.length > cap
+    };
+  }
+  configuredRepositories() {
+    const configured = [];
+    if (this.workspaceFile && (0, import_node_fs.existsSync)(this.workspaceFile)) {
+      try {
+        const parsed = JSON.parse(
+          (0, import_node_fs.readFileSync)(this.workspaceFile, "utf8")
+        );
+        if (parsed.v === 1 && Array.isArray(parsed.repositories)) {
+          const configDirectory = (0, import_node_path.dirname)(this.workspaceFile);
+          const base = (0, import_node_path.basename)(configDirectory) === ".mindgraph" ? (0, import_node_path.dirname)(configDirectory) : configDirectory;
+          for (const repository of parsed.repositories) {
+            if (!repository || typeof repository.root !== "string") continue;
+            configured.push({
+              repoId: typeof repository.repo_id === "string" ? repository.repo_id : void 0,
+              repoRoot: (0, import_node_path.resolve)(base, repository.root),
+              spaceUid: typeof repository.space_uid === "string" ? repository.space_uid : void 0
+            });
+          }
+        }
+      } catch {
+      }
+    }
+    const raw = this.env.MINDGRAPH_CODE_REPOS;
+    if (raw) {
+      try {
+        const parsed = JSON.parse(raw);
+        for (const [repoId, config] of Object.entries(parsed)) {
+          configured.push({
+            repoId,
+            repoRoot: (0, import_node_path.resolve)(
+              this.cwd,
+              typeof config === "string" ? config : config.root
+            ),
+            spaceUid: typeof config === "string" ? void 0 : config.space_uid
+          });
+        }
+      } catch {
+      }
+    }
+    return [
+      ...new Map(
+        configured.map((repository) => [repository.repoRoot, repository])
+      ).values()
+    ];
+  }
+  async resolveOne(ref, repository) {
+    const search = ref.symbol || ref.path;
+    if (!search || ref.line !== void 0 && (!Number.isInteger(ref.line) || ref.line < 1)) {
+      return { ref, candidates: [], error: "invalid_ref" };
+    }
+    try {
+      const args = ["query", "-p", repository.repoRoot, "-j", "-l", "50"];
+      if (ref.kind) args.push("-k", ref.kind);
+      args.push(search);
+      const hits = await this.runJson(args);
+      let candidates = hits.map(asNode).map(toCandidate).filter((item) => item !== null);
+      if (ref.path) {
+        const absolutePath = (0, import_node_path.isAbsolute)(ref.path) ? await (0, import_promises.realpath)(ref.path).catch(() => ref.path) : void 0;
+        const wanted = normalizePath(
+          absolutePath ? (0, import_node_path.relative)(repository.repoRoot, absolutePath) : ref.path
+        );
+        candidates = candidates.filter((candidate) => candidate.path === wanted);
+      }
+      if (ref.language) {
+        candidates = candidates.filter(
+          (candidate) => candidate.language.toLowerCase() === ref.language?.toLowerCase()
+        );
+      }
+      if (ref.kind) {
+        candidates = candidates.filter(
+          (candidate) => candidate.kind.toLowerCase() === ref.kind?.toLowerCase()
+        );
+      }
+      if (ref.symbol) {
+        const exact = candidates.filter((candidate) => {
+          const tail = candidate.qualifiedName.split(/::|\.|#/).at(-1);
+          return candidate.qualifiedName === ref.symbol || tail === ref.symbol;
+        });
+        if (exact.length > 0) candidates = exact;
+      }
+      if (ref.signature) {
+        const signature = normalizeSignature(ref.signature);
+        candidates = candidates.filter(
+          (candidate) => candidate.signature !== null && normalizeSignature(candidate.signature) === signature
+        );
+      }
+      if (ref.line !== void 0) {
+        candidates = candidates.filter(
+          (candidate) => candidate.startLine <= ref.line && candidate.endLine >= ref.line
+        );
+        if (candidates.length > 1) {
+          const narrowest = Math.min(
+            ...candidates.map((candidate) => candidate.endLine - candidate.startLine)
+          );
+          const narrowed = candidates.filter(
+            (candidate) => candidate.endLine - candidate.startLine === narrowest
+          );
+          if (narrowed.length === 1) candidates = narrowed;
+        }
+      }
+      if (candidates.length !== 1) {
+        return {
+          ref,
+          candidates,
+          error: candidates.length === 0 ? "not_found" : "ambiguous"
+        };
+      }
+      return {
+        ref,
+        candidates,
+        resolved: {
+          repoId: repository.repoId,
+          repoRoot: repository.repoRoot,
+          ...candidates[0]
+        }
+      };
+    } catch (cause) {
+      const failure = cause;
+      return {
+        ref,
+        candidates: [],
+        error: failure.kind ?? "command_failed"
+      };
+    }
+  }
+  async related(action, resolved, limit) {
+    const raw = await this.runJson([
+      action,
+      "-p",
+      resolved.repoRoot,
+      "-j",
+      "-l",
+      String(limit),
+      resolved.qualifiedName
+    ]);
+    const refs = (raw[action] ?? []).map((node) => ({
+      path: node.filePath,
+      line: node.startLine,
+      symbol: node.qualifiedName ?? node.name,
+      kind: node.kind
+    }));
+    return this.resolveRelatedRefs(refs, {
+      repoId: resolved.repoId,
+      repoRoot: resolved.repoRoot
+    });
+  }
+  async resolveRelatedRefs(refs, repository) {
+    const results = await Promise.all(refs.map((ref) => this.resolveOne(ref, repository)));
+    const seen = /* @__PURE__ */ new Set();
+    return results.flatMap((result) => result.resolved ? [result.resolved] : []).filter((result) => {
+      const key = `${result.path}:${result.qualifiedName}:${result.startLine}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+  async runJson(args) {
+    const candidates = [
+      this.env.MINDGRAPH_CODEGRAPH_BIN,
+      "codegraph",
+      (0, import_node_path.resolve)((0, import_node_os.homedir)(), ".local", "bin", "codegraph")
+    ].filter((candidate, index, all) => {
+      return Boolean(candidate) && all.indexOf(candidate) === index;
+    });
+    let lastFailure;
+    for (const executable of candidates) {
+      try {
+        const stdout = await runProcess(
+          executable,
+          args,
+          this.timeoutMs,
+          this.env,
+          this.cwd
+        );
+        return JSON.parse(stdout);
+      } catch (cause) {
+        const failure = cause;
+        lastFailure = failure;
+        if (failure.kind !== "absent") throw failure;
+      }
+    }
+    throw lastFailure ?? Object.assign(new Error("codegraph executable not found"), {
+      kind: "absent"
+    });
+  }
+};
+function repositoryIdentityKey(repository) {
+  return { v: 1, kind: "repository", repo_id: repository.repoId };
+}
+function codeRefIdentityKey(ref) {
+  if (ref.kind === "file") {
+    return {
+      v: 1,
+      kind: "file",
+      repo_id: ref.repoId,
+      path: ref.path
+    };
+  }
+  return {
+    v: 1,
+    kind: "symbol",
+    repo_id: ref.repoId,
+    language: ref.language,
+    symbol_kind: ref.kind,
+    qualified_name: ref.qualifiedName,
+    disambiguator: {
+      signature: ref.signature ?? "",
+      path: ref.path,
+      start_line: ref.startLine,
+      end_line: ref.endLine
+    }
+  };
+}
+
+// src/code-tool.ts
+var ok = (data) => ({
+  content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+});
+var err = (code, message, details) => ({
+  content: [
+    {
+      type: "text",
+      text: JSON.stringify({ error: message, code, details }, null, 2)
+    }
+  ],
+  isError: true
+});
+var CODE_TOOL = {
+  name: "mindgraph_code",
+  description: "Resolve typed code references through the local codegraph index and join them to persistent MindGraph memory/work. anchor creates exact repository/code anchors; recall reads attached graph context; expand reads callers/callees; affected reads impact for a code ref or Task/Execution. Ambiguous refs return candidates without writing.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["anchor", "recall", "expand", "affected"]
+      },
+      code_refs: {
+        type: "array",
+        maxItems: 50,
+        items: {
+          oneOf: [
+            { type: "string" },
+            {
+              type: "object",
+              properties: {
+                repo: { type: "string" },
+                path: { type: "string" },
+                line: { type: "integer", minimum: 1 },
+                symbol: { type: "string" },
+                kind: { type: "string" },
+                language: { type: "string" },
+                signature: { type: "string" }
+              },
+              additionalProperties: false
+            }
+          ]
+        }
+      },
+      anchor_uids: {
+        type: "array",
+        maxItems: 50,
+        items: { type: "string" },
+        description: "Already-materialized code anchor UIDs (codegraph is not required for recall)"
+      },
+      repo: {
+        type: "string",
+        description: "Configured repository id or repository root"
+      },
+      repo_space_uid: {
+        type: "string",
+        description: "Writable shared Project/repository Space for new anchors"
+      },
+      task_uid: { type: "string" },
+      execution_uid: { type: "string" },
+      limit: { type: "integer", minimum: 1, maximum: 50 },
+      agent_id: { type: "string" }
+    },
+    required: ["action"]
+  },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  }
+};
+async function handleCodeTool(client2, args, adapter = new CodegraphAdapter()) {
+  const codeClient = client2;
+  const action = args.action;
+  const refs = Array.isArray(args.code_refs) ? args.code_refs : [];
+  const anchorUids = Array.isArray(args.anchor_uids) ? args.anchor_uids : [];
+  const agentId = typeof args.agent_id === "string" ? args.agent_id : "mcp";
+  const fallbackSpaceUid = typeof args.repo_space_uid === "string" ? args.repo_space_uid : `space:agent:${agentId}`;
+  const options = {
+    repo: typeof args.repo === "string" ? args.repo : void 0,
+    fallbackSpaceUid
+  };
+  const limit = typeof args.limit === "number" ? args.limit : void 0;
+  try {
+    switch (action) {
+      case "anchor": {
+        if (refs.length === 0) return err("missing_code_refs", "code_refs is required for anchor");
+        const resolution = await adapter.resolveRefs(refs, options);
+        const resolved = resolution.results.flatMap(
+          (result) => result.resolved && result.repository ? [{ ref: result.resolved, repository: result.repository }] : []
+        );
+        const unresolved = resolution.results.filter((result) => !result.resolved);
+        if (resolved.length === 0) {
+          return ok({ ...resolution, anchors: [], wrote: false });
+        }
+        const missingSpace = resolved.find(
+          ({ repository }) => typeof args.repo_space_uid !== "string" && !repository.spaceUid
+        );
+        if (missingSpace) {
+          return err(
+            "missing_repository_space",
+            `repo_space_uid, a workspace space_uid, or MINDGRAPH_CODE_SPACE_UID is required for ${missingSpace.repository.repoId}`
+          );
+        }
+        const repositoryAnchors = /* @__PURE__ */ new Map();
+        for (const { repository } of resolved) {
+          if (repositoryAnchors.has(repository.repoRoot)) continue;
+          const spaceUid = typeof args.repo_space_uid === "string" ? args.repo_space_uid : repository.spaceUid;
+          const anchored = await anchorRepository(
+            codeClient,
+            repository,
+            spaceUid,
+            agentId
+          );
+          repositoryAnchors.set(repository.repoRoot, {
+            ...anchored,
+            repository
+          });
+        }
+        const anchors = [];
+        for (const { ref, repository } of resolved) {
+          const repositoryAnchor = repositoryAnchors.get(repository.repoRoot);
+          if (!repositoryAnchor.uid) continue;
+          const spaceUid = typeof args.repo_space_uid === "string" ? args.repo_space_uid : repository.spaceUid;
+          const anchor = await anchorCodeRef(
+            codeClient,
+            ref,
+            repositoryAnchor.uid,
+            spaceUid,
+            agentId
+          );
+          anchors.push(anchor);
+        }
+        return ok({
+          availability: resolution.availability,
+          repository: repositoryAnchors.values().next().value,
+          repositories: [...repositoryAnchors.values()],
+          anchors,
+          unresolved,
+          wrote: anchors.some((anchor) => anchor.created)
+        });
+      }
+      case "recall": {
+        const materialized = new Set(anchorUids);
+        let resolution;
+        if (refs.length > 0) {
+          resolution = await adapter.resolveRefs(refs, options);
+          for (const result of resolution.results) {
+            if (!result.resolved) continue;
+            const uid = await resolveMaterializedUid(codeClient, result.resolved, agentId);
+            if (uid) materialized.add(uid);
+          }
+        }
+        if (materialized.size === 0) {
+          return ok({
+            availability: resolution?.availability,
+            anchors: [],
+            context: [],
+            unresolved: resolution?.results.filter((result) => !result.resolved) ?? []
+          });
+        }
+        const context = await Promise.all(
+          [...materialized].map(async (uid) => ({
+            anchor_uid: uid,
+            graph: await codeClient.traverse({
+              action: "neighborhood",
+              start_uid: uid,
+              depth: 2,
+              max_nodes: Math.min(limit ?? 20, 20)
+            })
+          }))
+        );
+        return ok({
+          availability: resolution?.availability,
+          anchors: [...materialized],
+          context,
+          unresolved: resolution?.results.filter((result) => !result.resolved) ?? []
+        });
+      }
+      case "expand": {
+        const target = await resolveSingleTarget(
+          codeClient,
+          adapter,
+          refs,
+          anchorUids,
+          options
+        );
+        if ("error" in target) return target.error;
+        const expanded = await adapter.expand(target.ref, limit);
+        const joined = await joinMaterialized(
+          codeClient,
+          [...expanded.callers, ...expanded.callees],
+          agentId,
+          Math.min(limit ?? 20, 20)
+        );
+        return ok({ anchor: target.ref, ...expanded, materialized: joined });
+      }
+      case "affected": {
+        const targetUid = typeof args.task_uid === "string" ? args.task_uid : typeof args.execution_uid === "string" ? args.execution_uid : void 0;
+        let graphContext;
+        const graphRefs = [];
+        if (targetUid) {
+          graphContext = await codeClient.traverse({
+            action: "neighborhood",
+            start_uid: targetUid,
+            depth: 2,
+            max_nodes: 50
+          });
+          graphRefs.push(
+            ...await codeRefsFromGraphContext(codeClient, adapter, graphContext)
+          );
+        }
+        if (refs.length > 0 || anchorUids.length > 0) {
+          const target = await resolveSingleTarget(
+            codeClient,
+            adapter,
+            refs,
+            anchorUids,
+            options
+          );
+          if ("error" in target) return target.error;
+          graphRefs.unshift(target.ref);
+        }
+        const unique = uniqueRefs(graphRefs);
+        if (unique.length === 0) {
+          return ok({
+            target_uid: targetUid,
+            graph_context: graphContext,
+            affected: [],
+            degradation: "no materialized code anchors were attached"
+          });
+        }
+        const impacts = await Promise.all(
+          unique.map(async (ref) => ({ anchor: ref, ...await adapter.affected(ref, limit) }))
+        );
+        const structural = uniqueRefs(impacts.flatMap((impact) => impact.affected));
+        const joined = await joinMaterialized(
+          codeClient,
+          structural,
+          agentId,
+          Math.min(limit ?? 50, 50)
+        );
+        return ok({
+          target_uid: targetUid,
+          graph_context: graphContext,
+          impacts,
+          materialized: joined
+        });
+      }
+      default:
+        return err("unknown_action", `unknown mindgraph_code action: ${action}`);
+    }
+  } catch (cause) {
+    return err("code_tool_failed", errorDetail(cause));
+  }
+}
+async function attachCodeRefsToToolResult(client2, result, args, adapter) {
+  if (result.isError || !Array.isArray(args.code_refs) || args.code_refs.length === 0) {
+    return result;
+  }
+  const original = JSON.parse(result.content[0]?.text ?? "null");
+  const targetUids = primaryUids(original);
+  if (targetUids.length === 0) {
+    return ok({
+      result: original,
+      code_anchors: {
+        wrote: false,
+        caveat: "the write response exposed no primary UID to attach"
+      }
+    });
+  }
+  const anchorResult = await handleCodeTool(
+    client2,
+    {
+      action: "anchor",
+      code_refs: args.code_refs,
+      repo: args.repo,
+      repo_space_uid: args.repo_space_uid,
+      agent_id: args.agent_id
+    },
+    adapter
+  );
+  const anchors = JSON.parse(anchorResult.content[0]?.text ?? "null");
+  if (!anchorResult.isError) {
+    const codeClient = client2;
+    const anchorUids = (anchors.anchors ?? []).flatMap(
+      (anchor) => anchor.uid ? [anchor.uid] : []
+    );
+    for (const targetUid of targetUids) {
+      for (const anchorUid of anchorUids) {
+        await codeClient.entity({
+          action: "relate",
+          source_uid: targetUid,
+          target_uid: anchorUid,
+          edge_type: args.action === "lesson" ? "ABOUT" : "RELEVANT_TO",
+          agent_id: args.agent_id
+        });
+      }
+    }
+  }
+  return ok({ result: original, code_anchors: anchors });
+}
+async function anchorRepository(client2, repository, spaceUid, agentId) {
+  return client2.entity({
+    action: "create",
+    label: repository.repoId,
+    props: {
+      entity_type: "repository",
+      canonical_name: repository.repoId,
+      identifiers: { repo_id: repository.repoId }
+    },
+    identity: {
+      namespace: "external.code",
+      key_version: 1,
+      key: repositoryIdentityKey(repository)
+    },
+    identity_space_uid: spaceUid,
+    agent_id: agentId
+  });
+}
+async function anchorCodeRef(client2, ref, repositoryUid, spaceUid, agentId) {
+  const response = await client2.entity({
+    action: "create",
+    label: ref.qualifiedName,
+    props: {
+      entity_type: ref.kind === "file" ? "code_file" : "code_symbol",
+      canonical_name: ref.qualifiedName,
+      identifiers: {
+        repo_id: ref.repoId,
+        path: ref.path,
+        qualified_name: ref.qualifiedName
+      },
+      attributes: { code_ref: storedCodeRef(ref) }
+    },
+    identity: {
+      namespace: "external.code",
+      key_version: 1,
+      key: codeRefIdentityKey(ref)
+    },
+    identity_space_uid: spaceUid,
+    agent_id: agentId
+  });
+  if (response.uid) {
+    await client2.entity({
+      action: "relate",
+      source_uid: response.uid,
+      target_uid: repositoryUid,
+      edge_type: "PART_OF",
+      agent_id: agentId
+    });
+  }
+  return { ...response, ref };
+}
+async function resolveMaterializedUid(client2, ref, agentId) {
+  const response = await client2.entity({
+    action: "resolve_identity",
+    identity: {
+      namespace: "external.code",
+      key_version: 1,
+      key: codeRefIdentityKey(ref)
+    },
+    agent_id: agentId
+  });
+  return response.status === "existing" ? response.uid : void 0;
+}
+async function codeRefFromAnchor(client2, adapter, uid) {
+  const node = await client2.getNode(uid);
+  const attributes = node.props?.attributes;
+  if (!attributes || typeof attributes !== "object") return void 0;
+  const codeRef = attributes.code_ref;
+  if (!isStoredCodeRef(codeRef)) return void 0;
+  const repository = await adapter.resolveRepository(codeRef.repoId);
+  return { ...codeRef, repoRoot: repository.repoRoot };
+}
+async function resolveSingleTarget(client2, adapter, refs, anchorUids, options) {
+  if (refs.length > 1 || anchorUids.length > 1) {
+    return { error: err("ambiguous_target", "expand/affected accepts exactly one code target") };
+  }
+  if (anchorUids.length === 1) {
+    const ref = await codeRefFromAnchor(client2, adapter, anchorUids[0]);
+    return ref ? { ref } : { error: err("invalid_anchor", "anchor UID does not contain a typed code_ref") };
+  }
+  if (refs.length !== 1) {
+    return { error: err("missing_code_ref", "one code_ref or anchor_uid is required") };
+  }
+  const resolution = await adapter.resolveRefs(refs, options);
+  const result = resolution.results[0];
+  if (!result.resolved) {
+    return {
+      error: ok({
+        availability: resolution.availability,
+        result,
+        wrote: false
+      })
+    };
+  }
+  return { ref: result.resolved };
+}
+async function joinMaterialized(client2, refs, agentId, limit) {
+  const joined = [];
+  for (const ref of uniqueRefs(refs).slice(0, limit)) {
+    const uid = await resolveMaterializedUid(client2, ref, agentId);
+    if (!uid) continue;
+    joined.push({
+      ref,
+      anchor_uid: uid,
+      graph: await client2.traverse({
+        action: "neighborhood",
+        start_uid: uid,
+        depth: 2,
+        max_nodes: 20
+      })
+    });
+  }
+  return joined;
+}
+async function codeRefsFromGraphContext(client2, adapter, context) {
+  const uids = /* @__PURE__ */ new Set();
+  collectUids(context, uids);
+  if (uids.size === 0) return [];
+  const nodes = client2.getNodesBatch ? await client2.getNodesBatch([...uids]) : await Promise.all([...uids].map((uid) => client2.getNode(uid).catch(() => void 0)));
+  const stored = nodes.flatMap((node) => {
+    if (!node) return [];
+    const attributes = node.props?.attributes;
+    if (!attributes || typeof attributes !== "object") return [];
+    const codeRef = attributes.code_ref;
+    return isStoredCodeRef(codeRef) ? [codeRef] : [];
+  });
+  return Promise.all(
+    stored.map(async (ref) => {
+      const repository = await adapter.resolveRepository(ref.repoId);
+      return { ...ref, repoRoot: repository.repoRoot };
+    })
+  );
+}
+function collectUids(value, uids) {
+  if (Array.isArray(value)) {
+    value.forEach((item) => collectUids(item, uids));
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    if (typeof child === "string" && ["uid", "node_uid", "neighbor_uid", "from_uid", "to_uid"].includes(key)) {
+      uids.add(child);
+    } else {
+      collectUids(child, uids);
+    }
+  }
+}
+function isStoredCodeRef(value) {
+  if (!value || typeof value !== "object") return false;
+  const ref = value;
+  return typeof ref.repoId === "string" && typeof ref.path === "string" && typeof ref.language === "string" && typeof ref.kind === "string" && typeof ref.qualifiedName === "string" && (typeof ref.signature === "string" || ref.signature === null) && typeof ref.startLine === "number" && typeof ref.endLine === "number";
+}
+function storedCodeRef(ref) {
+  const { repoRoot: _localOnly, ...stored } = ref;
+  return stored;
+}
+function uniqueRefs(refs) {
+  const seen = /* @__PURE__ */ new Set();
+  return refs.filter((ref) => {
+    const key = `${ref.repoId}:${ref.path}:${ref.qualifiedName}:${ref.signature ?? ""}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+function primaryUids(value) {
+  if (!value || typeof value !== "object") return [];
+  const object = value;
+  const keys = [
+    "uid",
+    "claim_uid",
+    "goal_uid",
+    "project_uid",
+    "milestone_uid",
+    "decision_uid",
+    "task_uid",
+    "plan_uid",
+    "step_uid",
+    "execution_uid",
+    "lesson_uid"
+  ];
+  return [
+    ...new Set(
+      keys.flatMap((key) => typeof object[key] === "string" ? [object[key]] : [])
+    )
+  ];
+}
+
+// src/sync-tool.ts
+var import_node_crypto2 = __toESM(require("crypto"));
+var import_node_fs2 = __toESM(require("fs"));
+var import_node_path2 = __toESM(require("path"));
+var ok2 = (data) => ({
+  content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+});
+var err2 = (code, message) => ({
+  content: [{ type: "text", text: JSON.stringify({ code, error: message }) }],
+  isError: true
+});
+var SYNC_TOOL = {
+  name: "mindgraph_sync",
+  description: "Transactional one-way project memory-file sync. scan/status are reads; begin/record/finalize/abandon are writes. Discovery and hashing are automatic; semantic assertions are deliberately supplied through record. This never writes graph state back to files.",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["scan", "begin", "record", "finalize", "status", "abandon"]
+      },
+      paths: { type: "array", items: { type: "string" } },
+      workspace: {
+        type: "boolean",
+        description: "For scan only: fan out across repositories explicitly listed in .mindgraph/workspace.json"
+      },
+      repo: {
+        type: "string",
+        description: "Configured repository id, name, or root"
+      },
+      logical_path: { type: "string" },
+      content: { type: "string" },
+      content_hash: { type: "string" },
+      source_uid: { type: "string" },
+      execution_uid: { type: "string" },
+      assertion_fingerprint: { type: "string" },
+      planned_fingerprints: { type: "array", items: { type: "string" } },
+      current_fingerprints: { type: "array", items: { type: "string" } },
+      source_selector: { type: "object" },
+      capture_type: {
+        type: "string",
+        enum: ["lesson", "journal", "claim", "decision", "risk"]
+      },
+      label: { type: "string" },
+      summary: { type: "string" },
+      props: { type: "object" },
+      expected_execution_version: { type: "integer", minimum: 1 },
+      baseline_version: { type: "integer", minimum: 1 },
+      repo_space_uid: { type: "string" },
+      repo_id: { type: "string" },
+      provider: { type: "string", enum: ["claude_project", "explicit"] },
+      file_present: { type: "boolean" },
+      agent_id: { type: "string" },
+      invocation_context: {
+        type: "object",
+        description: "Adapter-owned; hooks replace forged or absent values.",
+        properties: {
+          harness: { type: "string" },
+          harnessSessionId: { type: "string" },
+          harnessTurnId: { type: "string" },
+          cwd: { type: "string" },
+          repoId: { type: "string" },
+          branch: { type: "string" },
+          commit: { type: "string" },
+          worktreeState: { type: "string" },
+          model: { type: "string" },
+          injectedBy: { type: "string" }
+        }
+      }
+    },
+    required: ["action"]
+  }
+};
+function safePath(root, candidate) {
+  const absolute = import_node_path2.default.resolve(root, candidate);
+  const relative2 = import_node_path2.default.relative(root, absolute);
+  if (relative2.startsWith("..") || import_node_path2.default.isAbsolute(relative2)) {
+    throw new Error(`path escapes repository root: ${candidate}`);
+  }
+  return absolute;
+}
+function markdownFiles(target) {
+  if (!import_node_fs2.default.existsSync(target)) return [];
+  const stat = import_node_fs2.default.statSync(target);
+  if (stat.isFile()) return target.endsWith(".md") ? [target] : [];
+  if (!stat.isDirectory()) return [];
+  return import_node_fs2.default.readdirSync(target, { withFileTypes: true }).flatMap((entry) => markdownFiles(import_node_path2.default.join(target, entry.name)));
+}
+function fileDescriptor(root, absolute) {
+  const content = import_node_fs2.default.readFileSync(absolute, "utf8");
+  return {
+    logical_path: import_node_path2.default.relative(root, absolute).split(import_node_path2.default.sep).join("/"),
+    content_hash: import_node_crypto2.default.createHash("sha256").update(content).digest("hex"),
+    bytes: Buffer.byteLength(content),
+    content
+  };
+}
+async function handleSyncTool(client2, args) {
+  try {
+    const action = String(args.action || "");
+    const context = args.invocation_context || {};
+    const adapter = new CodegraphAdapter({
+      cwd: context.cwd || process.cwd()
+    });
+    const requestedRepo = typeof args.repo === "string" ? args.repo : typeof args.repo_id === "string" ? args.repo_id : context.repoId;
+    const repository = await adapter.resolveRepository(requestedRepo);
+    const root = repository.repoRoot;
+    const repoId = repository.repoId;
+    const provider = String(args.provider || "claude_project");
+    const remote = client2;
+    if (action === "scan") {
+      const repositories = args.workspace === true ? await adapter.resolveRepositories() : [repository];
+      const requested = Array.isArray(args.paths) && args.paths.length > 0 ? args.paths.map(String) : [".claude/agent-memory", "memory"];
+      const scans = [];
+      for (const selected of repositories) {
+        scans.push(
+          await scanRepository(
+            remote,
+            selected,
+            requested,
+            provider,
+            args.agent_id
+          )
+        );
+      }
+      if (args.workspace === true) {
+        return ok2({
+          provider,
+          workspace: true,
+          repositories: scans,
+          one_way: "files_to_graph"
+        });
+      }
+      return ok2(scans[0]);
+    }
+    const request = {
+      ...args,
+      provider,
+      repo_id: repoId
+    };
+    delete request.invocation_context;
+    delete request.paths;
+    delete request.repo;
+    delete request.workspace;
+    if (action === "begin" && !request.content) {
+      if (!request.logical_path) {
+        return err2("missing_field", "logical_path is required for begin");
+      }
+      const file = fileDescriptor(
+        root,
+        safePath(root, String(request.logical_path))
+      );
+      request.content = file.content;
+      request.content_hash ||= file.content_hash;
+    }
+    if (action === "status" && request.logical_path && request.file_present !== false) {
+      const absolute = safePath(root, String(request.logical_path));
+      request.file_present = import_node_fs2.default.existsSync(absolute);
+      if (request.file_present && !request.content_hash) {
+        request.content_hash = fileDescriptor(root, absolute).content_hash;
+      }
+    }
+    return ok2(await remote.memorySync(request));
+  } catch (error) {
+    return err2("sync_failed", errorDetail(error));
+  }
+}
+async function scanRepository(remote, repository, requested, provider, agentId) {
+  const files = [
+    ...new Set(
+      requested.flatMap(
+        (candidate) => markdownFiles(safePath(repository.repoRoot, candidate))
+      )
+    )
+  ].sort();
+  const results = [];
+  for (const absolute of files) {
+    const file = fileDescriptor(repository.repoRoot, absolute);
+    const status = await remote.memorySync({
+      action: "scan",
+      provider,
+      repo_id: repository.repoId,
+      logical_path: file.logical_path,
+      content_hash: file.content_hash,
+      file_present: true,
+      agent_id: agentId
+    });
+    results.push({
+      logical_path: file.logical_path,
+      content_hash: file.content_hash,
+      bytes: file.bytes,
+      status
+    });
+  }
+  return {
+    repo_id: repository.repoId,
+    root: ".",
+    files: results
+  };
+}
 
 // src/tools.ts
 var TOOLS = [
   {
     name: "mindgraph_capture",
-    description: "Capture knowledge into the graph. Use 'entity' for people/orgs/places/events/nations/concepts (auto-deduplicates \u2014 safe to call even if already exists), 'observation' for factual statements, 'source' for documents/URLs, 'snippet' for quotes from a source, 'concept' for abstract ideas. Use 'journal' for quick personal notes, preferences, reflections, moods \u2014 anything subjective or informal. Prefer 'entity'/'observation' for objective facts, 'journal' for personal notes.",
+    description: "Capture knowledge into the graph. Use 'entity' for people/orgs/places/events/nations/concepts (auto-deduplicates \u2014 safe to call even if already exists), 'observation' for factual statements, 'source' for documents/URLs, 'snippet' for quotes from a source, and 'concept' for abstract ideas. Use 'journal' for quick personal notes and 'lesson' for a durable learning attributable to a session or source nodes. Prefer 'entity'/'observation' for objective facts, 'journal' for informal notes, and 'lesson' only for reusable knowledge.",
     inputSchema: {
       type: "object",
       properties: {
         action: {
           type: "string",
-          enum: ["entity", "observation", "source", "snippet", "concept", "journal"],
+          enum: [
+            "entity",
+            "observation",
+            "source",
+            "snippet",
+            "concept",
+            "journal",
+            "lesson"
+          ],
           description: "Type of knowledge to capture"
         },
         label: {
@@ -31,6 +1448,31 @@ var TOOLS = [
           type: "string",
           description: "Journal content/body text (for action=journal)"
         },
+        session_uid: {
+          type: "string",
+          description: "Session UID that produced a lesson (for action=lesson)"
+        },
+        work_uid: {
+          type: "string",
+          description: "Durable Task/work UID this capture is relevant to"
+        },
+        execution_uid: {
+          type: "string",
+          description: "Material Execution that produced the lesson"
+        },
+        idempotency_key: {
+          type: "string",
+          description: "Stable retry key for an intentional capture"
+        },
+        supersedes_uid: {
+          type: "string",
+          description: "Earlier capture corrected or superseded by this one"
+        },
+        summarizes_uids: {
+          type: "array",
+          items: { type: "string" },
+          description: "Source node UIDs the lesson was learned from (for action=lesson)"
+        },
         entity_type: {
           type: "string",
           enum: ["person", "organization", "place", "event", "nation", "concept"],
@@ -65,6 +1507,32 @@ var TOOLS = [
           type: "object",
           description: "Type-specific properties (e.g. birth_date for person, coordinates for place)"
         },
+        code_refs: {
+          type: "array",
+          items: {
+            oneOf: [
+              { type: "string" },
+              {
+                type: "object",
+                properties: {
+                  repo: { type: "string" },
+                  path: { type: "string" },
+                  line: { type: "integer", minimum: 1 },
+                  symbol: { type: "string" },
+                  kind: { type: "string" },
+                  language: { type: "string" },
+                  signature: { type: "string" }
+                }
+              }
+            ]
+          },
+          description: "Typed code targets to anchor and attach to the captured node"
+        },
+        repo: { type: "string", description: "Configured repository id or root" },
+        repo_space_uid: {
+          type: "string",
+          description: "Writable shared repository/Project Space for new code anchors"
+        },
         agent_id: {
           type: "string",
           description: "Agent identity"
@@ -238,6 +1706,16 @@ var TOOLS = [
           type: "object",
           description: "Type-specific properties (e.g. status, priority, deadline, horizon for goals)"
         },
+        code_refs: {
+          type: "array",
+          items: { oneOf: [{ type: "string" }, { type: "object" }] },
+          description: "Typed code targets to anchor and attach to the created commitment"
+        },
+        repo: { type: "string", description: "Configured repository id or root" },
+        repo_space_uid: {
+          type: "string",
+          description: "Writable shared repository/Project Space for new code anchors"
+        },
         agent_id: {
           type: "string",
           description: "Agent identity"
@@ -248,7 +1726,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_plan",
-    description: "Agent-level task management, governance, and procedural knowledge. Use 'create_plan'/'create_task'/'add_step' for task breakdowns, 'update_status' for progress, 'get_plan' to review. Use 'create_flow'/'add_procedure_step'/'add_affordance'/'add_control' for workflows and procedures. Use 'assess_risk'/'get_assessments' for risk analysis. Use 'get_pending' to read the governance approval queue \u2014 approvals are granted by a person in the MindGraph dashboard, never from here, so wait for one rather than trying to clear it. Prefer mindgraph_commit for user goals/projects; use this for agent-managed execution.",
+    description: "Authoritative durable engineering work and execution evidence. Use create_task/create_plan/add_step for work that must survive sessions; resume_work for the deterministic bounded brief; claim_task + heartbeat for the fenced lease; and start_iteration/checkpoint_iteration/block_task/complete_task/abandon_iteration for idempotent material attempts. Every composite write needs task version, Session, lease epoch, and an idempotency key. Use the harness-native todo list only for local coordination; never maintain the same authoritative Task in both systems.",
     inputSchema: {
       type: "object",
       properties: {
@@ -260,9 +1738,19 @@ var TOOLS = [
             "add_step",
             "update_status",
             "get_plan",
+            "resume_work",
+            "claim_task",
+            "heartbeat",
+            "start_iteration",
+            "checkpoint_iteration",
+            "block_task",
+            "complete_task",
+            "abandon_iteration",
             "start_execution",
             "complete_execution",
             "fail_execution",
+            "register_agent",
+            "get_executions",
             // C33: governance WRITES are deliberately not exposed here.
             // `create_policy` let a model author the rules it is judged by;
             // `request_approval` + `resolve_approval` let it raise and then
@@ -290,30 +1778,189 @@ var TOOLS = [
         },
         plan_uid: {
           type: "string",
-          description: "Plan UID (for add_step, get_plan)"
+          description: "Plan UID (for create_plan execution link, add_step, get_plan)"
         },
         task_uid: {
           type: "string",
-          description: "Task/step UID (for update_status, execution actions)"
+          description: "Task UID (for create_plan and graph-managed work actions)"
+        },
+        step_uid: {
+          type: "string",
+          description: "PlanStep UID for an iteration/checkpoint"
+        },
+        session_uid: {
+          type: "string",
+          description: "Durable Session UID that owns the task lease"
+        },
+        goal_uid: {
+          type: "string",
+          description: "Goal UID targeted by a task or plan"
         },
         target_uid: {
           type: "string",
-          description: "Parent flow/step UID or target node (for procedure/risk actions)"
+          description: "Task/plan/step UID for update_status, or parent/target node for procedure and risk actions"
+        },
+        execution_uid: {
+          type: "string",
+          description: "Execution UID (required for complete_execution/fail_execution)"
+        },
+        executor_uid: {
+          type: "string",
+          description: "Agent node UID that executed the work"
+        },
+        affordance_uid: {
+          type: "string",
+          description: "Affordance invoked by start_execution"
+        },
+        produces_node_uid: {
+          type: "string",
+          description: "Node produced by a completed execution"
+        },
+        filter_plan_uid: {
+          type: "string",
+          description: "Restrict get_executions to one plan"
+        },
+        depends_on_uids: {
+          type: "array",
+          items: { type: "string" },
+          description: "Plan-step UIDs that an added step depends on"
+        },
+        related_uids: {
+          type: "array",
+          items: { type: "string" },
+          description: "Target node UIDs to link to created work or an execution"
         },
         status: {
           type: "string",
           description: "New status value (for update_status)"
         },
+        task_status: {
+          type: "string",
+          description: "Task status requested by a checkpoint or abandon action"
+        },
+        step_status: {
+          type: "string",
+          description: "PlanStep status requested by a checkpoint"
+        },
+        execution_status: {
+          type: "string",
+          enum: ["completed", "failed", "abandoned"],
+          description: "Terminal Execution status for checkpoint_iteration"
+        },
+        expected_version: {
+          type: "number",
+          description: "Current Task node version used as the optimistic fence"
+        },
+        lease_epoch: {
+          type: "number",
+          description: "Current monotonic task-lease epoch"
+        },
+        lease_ttl_secs: {
+          type: "number",
+          minimum: 1,
+          description: "Requested server-time lease lifetime (default 300s)"
+        },
+        idempotency_key: {
+          type: "string",
+          description: "Caller-stable key required for every composite work mutation"
+        },
+        allow_takeover: {
+          type: "boolean",
+          description: "Governed claim override for a live lease owned by another agent"
+        },
+        release_lease: {
+          type: "boolean",
+          description: "Explicitly release or retain the lease after block/abandon/checkpoint"
+        },
+        override_reason: {
+          type: "string",
+          description: "Explicit completion reason when no terminal Execution evidence exists"
+        },
+        scope_uids: {
+          type: "array",
+          items: { type: "string" },
+          description: "Ordinary target UIDs that bound deterministic resume selection"
+        },
+        limit: {
+          type: "number",
+          minimum: 1,
+          maximum: 1,
+          description: "Resume returns one authoritative Task"
+        },
+        input_snapshot: {
+          type: "object",
+          description: "Structured inputs captured when an execution starts"
+        },
+        output_snapshot: {
+          type: "object",
+          description: "Structured outputs captured when an execution completes or fails"
+        },
+        outcome: {
+          type: "string",
+          description: "Execution outcome"
+        },
+        error: {
+          type: "string",
+          description: "Execution error detail (for fail_execution)"
+        },
+        side_effects: {
+          type: "array",
+          items: { type: "string" },
+          description: "Observable side effects of the execution"
+        },
+        next_action: {
+          type: "string",
+          description: "Recommended next action retained on terminal Execution evidence"
+        },
+        checkpoint_summary: {
+          type: "string",
+          description: "Bounded material-attempt checkpoint summary"
+        },
+        test_summary: {
+          type: "string",
+          description: "Test commands/results retained on the Execution"
+        },
+        produces_node_uids: {
+          type: "array",
+          items: { type: "string" },
+          description: "Nodes produced by checkpoint_iteration"
+        },
+        confidence: {
+          type: "number",
+          minimum: 0,
+          maximum: 1
+        },
+        salience: {
+          type: "number",
+          minimum: 0,
+          maximum: 1
+        },
         props: {
           type: "object",
           description: "Additional properties (e.g. likelihood, impact, mitigation for risks)"
         },
+        code_refs: {
+          type: "array",
+          items: { oneOf: [{ type: "string" }, { type: "object" }] },
+          description: "Typed code targets to anchor and attach to created work or execution"
+        },
+        repo: { type: "string", description: "Configured repository id or root" },
+        repo_space_uid: {
+          type: "string",
+          description: "Writable shared repository/Project Space for new code anchors"
+        },
         agent_id: {
           type: "string",
           description: "Agent identity"
         }
       },
       required: ["action"]
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
     }
   },
   {
@@ -688,14 +2335,45 @@ var TOOLS = [
       },
       required: ["action"]
     }
-  }
+  },
+  SYNC_TOOL,
+  CODE_TOOL
 ];
-function ok(data) {
+var INVOCATION_CONTEXT_SCHEMA = {
+  type: "object",
+  description: "Adapter-owned invocation context. Models should omit it; compatible hooks replace forged or absent values. cwd is consumed locally and never sent to the API.",
+  properties: {
+    harness: { type: "string", enum: ["claude-code", "codex", "generic"] },
+    harnessSessionId: { type: "string" },
+    harnessTurnId: { type: "string" },
+    cwd: { type: "string" },
+    repoId: { type: "string" },
+    branch: { type: "string" },
+    commit: { type: "string" },
+    worktreeState: { type: "string", enum: ["clean", "dirty"] },
+    model: { type: "string" },
+    injectedBy: { type: "string", enum: ["hook", "mcp-process", "caller"] }
+  }
+};
+for (const tool of TOOLS) {
+  if (tool.name === "mindgraph_retrieve") continue;
+  const schema = tool.inputSchema;
+  if (schema.properties && !schema.properties.invocation_context) {
+    schema.properties.invocation_context = INVOCATION_CONTEXT_SCHEMA;
+  }
+}
+function toolsForProfile(profile = process.env.MINDGRAPH_PROFILE || "general") {
+  if (profile === "coding") return TOOLS;
+  return TOOLS.filter(
+    (tool) => tool.name !== "mindgraph_code" && tool.name !== "mindgraph_sync"
+  );
+}
+function ok3(data) {
   return {
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
   };
 }
-function err(message) {
+function err3(message) {
   return {
     content: [{ type: "text", text: JSON.stringify({ error: message }) }],
     isError: true
@@ -703,29 +2381,53 @@ function err(message) {
 }
 async function handleTool(client2, name, args) {
   try {
+    let result;
     switch (name) {
       case "mindgraph_capture":
-        return await handleCapture(client2, args);
+        result = await handleCapture(client2, args);
+        break;
       case "mindgraph_reason":
-        return await handleReason(client2, args);
+        result = await handleReason(client2, args);
+        break;
       case "mindgraph_commit":
-        return await handleCommit(client2, args);
+        result = await handleCommit(client2, args);
+        break;
       case "mindgraph_plan":
-        return await handlePlan(client2, args);
+        result = await handlePlan(client2, args);
+        break;
       case "mindgraph_retrieve":
-        return await handleRetrieve(client2, args);
+        result = await handleRetrieve(client2, args);
+        break;
       case "mindgraph_ingest":
-        return await handleIngest(client2, args);
+        result = await handleIngest(client2, args);
+        break;
       case "mindgraph_synthesize":
-        return await handleSynthesize(client2, args);
+        result = await handleSynthesize(client2, args);
+        break;
       case "mindgraph_ontology":
-        return await handleOntology(client2, args);
+        result = await handleOntology(client2, args);
+        break;
+      case "mindgraph_code":
+        result = await handleCodeTool(client2, args);
+        break;
+      case "mindgraph_sync":
+        result = await handleSyncTool(client2, args);
+        break;
       default:
-        return err(`Unknown tool: ${name}`);
+        result = err3(`Unknown tool: ${name}`);
     }
+    const action = typeof args.action === "string" ? args.action : "";
+    const attach = name === "mindgraph_capture" || name === "mindgraph_commit" && action !== "get_open_decisions" || name === "mindgraph_plan" && ![
+      "get_plan",
+      "get_executions",
+      "get_pending",
+      "get_assessments",
+      "resume_work",
+      "heartbeat"
+    ].includes(action);
+    return attach ? await attachCodeRefsToToolResult(client2, result, args) : result;
   } catch (e) {
-    const message = e instanceof Error ? e.message : String(e);
-    return err(message);
+    return err3(errorDetail(e));
   }
 }
 async function handleCapture(client2, args) {
@@ -734,6 +2436,12 @@ async function handleCapture(client2, args) {
     label,
     summary,
     content,
+    session_uid,
+    work_uid,
+    execution_uid,
+    idempotency_key,
+    supersedes_uid,
+    summarizes_uids,
     entity_type,
     source_uid,
     mood,
@@ -744,12 +2452,30 @@ async function handleCapture(client2, args) {
     agent_id
   } = args;
   switch (action) {
+    case "lesson":
+      return ok3(
+        await client2.distill({
+          label,
+          output_type: "lesson",
+          summary,
+          confidence,
+          salience,
+          session_uid,
+          work_uid,
+          execution_uid,
+          idempotency_key,
+          supersedes_uid,
+          summarizes_uids,
+          props,
+          agent_id
+        })
+      );
     case "journal": {
-      if (!content) return err("content is required for action=journal");
+      if (!content) return err3("content is required for action=journal");
       const journalProps = { content };
       if (mood) journalProps.mood = mood;
       if (tags) journalProps.tags = tags;
-      return ok(await client2.journal(label, journalProps, { agent_id }));
+      return ok3(await client2.journal(label, journalProps, { agent_id }));
     }
     case "entity": {
       const type = entity_type || "concept";
@@ -757,22 +2483,22 @@ async function handleCapture(client2, args) {
       if (summary) entityProps.description = summary;
       switch (type) {
         case "person":
-          return ok(await client2.findOrCreatePerson(label, entityProps, agent_id));
+          return ok3(await client2.findOrCreatePerson(label, entityProps, agent_id));
         case "organization":
-          return ok(await client2.findOrCreateOrganization(label, entityProps, agent_id));
+          return ok3(await client2.findOrCreateOrganization(label, entityProps, agent_id));
         case "nation":
-          return ok(await client2.findOrCreateNation(label, entityProps, agent_id));
+          return ok3(await client2.findOrCreateNation(label, entityProps, agent_id));
         case "event":
-          return ok(await client2.findOrCreateEvent(label, entityProps, agent_id));
+          return ok3(await client2.findOrCreateEvent(label, entityProps, agent_id));
         case "place":
-          return ok(await client2.findOrCreatePlace(label, entityProps, agent_id));
+          return ok3(await client2.findOrCreatePlace(label, entityProps, agent_id));
         case "concept":
         default:
-          return ok(await client2.findOrCreateConcept(label, entityProps, agent_id));
+          return ok3(await client2.findOrCreateConcept(label, entityProps, agent_id));
       }
     }
     case "observation":
-      return ok(
+      return ok3(
         await client2.capture({
           action: "observation",
           label,
@@ -784,7 +2510,7 @@ async function handleCapture(client2, args) {
         })
       );
     case "source":
-      return ok(
+      return ok3(
         await client2.capture({
           action: "source",
           label,
@@ -796,7 +2522,7 @@ async function handleCapture(client2, args) {
         })
       );
     case "snippet":
-      return ok(
+      return ok3(
         await client2.capture({
           action: "snippet",
           label,
@@ -809,7 +2535,7 @@ async function handleCapture(client2, args) {
         })
       );
     case "concept":
-      return ok(
+      return ok3(
         await client2.structure({
           action: "concept",
           label,
@@ -821,7 +2547,7 @@ async function handleCapture(client2, args) {
         })
       );
     default:
-      return err(`Unknown capture action: ${action}`);
+      return err3(`Unknown capture action: ${action}`);
   }
 }
 async function handleReason(client2, args) {
@@ -839,20 +2565,30 @@ async function handleReason(client2, args) {
     agent_id
   } = args;
   if (action === "claim") {
-    const claimObj = claim || (label ? { label, confidence } : null);
-    if (!claimObj) return err("claim object or label is required for action=claim");
-    return ok(
+    const claimObj = claim ? {
+      label: claim.label,
+      confidence: claim.confidence,
+      ...claim.content ? { props: { content: claim.content } } : {}
+    } : label ? { label, confidence } : null;
+    if (!claimObj) return err3("claim object or label is required for action=claim");
+    return ok3(
       await client2.argue({
         claim: claimObj,
-        evidence,
-        warrant,
+        evidence: evidence?.map((e) => ({
+          label: e.label,
+          ...e.description ? { props: { description: e.description } } : {}
+        })),
+        warrant: warrant ? {
+          label: warrant.label,
+          ...warrant.content ? { props: { content: warrant.content } } : {}
+        } : void 0,
         argument,
         agent_id
       })
     );
   }
-  if (!label) return err(`label is required for action=${action}`);
-  return ok(
+  if (!label) return err3(`label is required for action=${action}`);
+  return ok3(
     await client2.inquire({
       action,
       label,
@@ -885,8 +2621,8 @@ async function handleCommit(client2, args) {
     case "goal":
     case "project":
     case "milestone":
-      if (!label) return err(`label is required for action=${action}`);
-      return ok(
+      if (!label) return err3(`label is required for action=${action}`);
+      return ok3(
         await client2.commit({
           action,
           label,
@@ -899,15 +2635,15 @@ async function handleCommit(client2, args) {
         })
       );
     case "open_decision":
-      if (!label) return err("label is required for open_decision");
-      return ok(await client2.openDecision(label, { summary, props, agent_id }));
+      if (!label) return err3("label is required for open_decision");
+      return ok3(await client2.openDecision(label, { summary, props, agent_id }));
     case "add_option":
-      if (!decision_uid) return err("decision_uid is required for add_option");
-      if (!label) return err("label is required for add_option");
-      return ok(await client2.addOption(decision_uid, label, { summary, props, agent_id }));
+      if (!decision_uid) return err3("decision_uid is required for add_option");
+      if (!label) return err3("label is required for add_option");
+      return ok3(await client2.addOption(decision_uid, label, { summary, props, agent_id }));
     case "add_constraint":
-      if (!decision_uid) return err("decision_uid is required for add_constraint");
-      return ok(
+      if (!decision_uid) return err3("decision_uid is required for add_constraint");
+      return ok3(
         await client2.deliberate({
           action: "add_constraint",
           label,
@@ -918,9 +2654,9 @@ async function handleCommit(client2, args) {
         })
       );
     case "resolve_decision":
-      if (!decision_uid) return err("decision_uid is required for resolve_decision");
-      if (!chosen_option_uid) return err("chosen_option_uid is required for resolve_decision");
-      return ok(
+      if (!decision_uid) return err3("decision_uid is required for resolve_decision");
+      if (!chosen_option_uid) return err3("chosen_option_uid is required for resolve_decision");
+      return ok3(
         await client2.resolveDecision(decision_uid, chosen_option_uid, {
           summary,
           props,
@@ -932,9 +2668,9 @@ async function handleCommit(client2, args) {
         })
       );
     case "get_open_decisions":
-      return ok(await client2.getOpenDecisions());
+      return ok3(await client2.getOpenDecisions());
     default:
-      return err(`Unknown commit action: ${action}`);
+      return err3(`Unknown commit action: ${action}`);
   }
 }
 async function handlePlan(client2, args) {
@@ -944,8 +2680,41 @@ async function handlePlan(client2, args) {
     summary,
     plan_uid,
     task_uid,
+    step_uid,
+    session_uid,
+    goal_uid,
     target_uid,
+    execution_uid,
+    executor_uid,
+    affordance_uid,
+    produces_node_uid,
+    filter_plan_uid,
+    depends_on_uids,
+    related_uids,
     status,
+    task_status,
+    step_status,
+    execution_status,
+    expected_version,
+    lease_epoch,
+    lease_ttl_secs,
+    idempotency_key,
+    allow_takeover,
+    release_lease,
+    override_reason,
+    scope_uids,
+    limit,
+    confidence,
+    salience,
+    input_snapshot,
+    output_snapshot,
+    side_effects,
+    outcome,
+    error,
+    next_action,
+    checkpoint_summary,
+    test_summary,
+    produces_node_uids,
     props,
     agent_id
   } = args;
@@ -956,25 +2725,120 @@ async function handlePlan(client2, args) {
     case "add_step":
     case "update_status":
     case "get_plan":
-      return ok(
+    case "resume_work":
+    case "claim_task":
+    case "heartbeat":
+    case "start_iteration":
+    case "checkpoint_iteration":
+    case "block_task":
+    case "complete_task":
+    case "abandon_iteration":
+      return ok3(
         await client2.plan({
           action,
           label,
           summary,
+          confidence,
+          salience,
+          goal_uid,
           plan_uid,
           task_uid,
+          step_uid,
+          session_uid,
+          target_uid,
+          depends_on_uids,
+          related_uids,
           status,
+          task_status,
+          step_status,
+          execution_status,
+          execution_uid,
+          expected_version,
+          lease_epoch,
+          lease_ttl_secs,
+          idempotency_key,
+          allow_takeover,
+          release_lease,
+          override_reason,
+          scope_uids,
+          limit,
+          input_snapshot,
+          output_snapshot,
+          side_effects,
+          outcome,
+          error,
+          next_action,
+          checkpoint_summary,
+          test_summary,
+          produces_node_uids,
           props,
           agent_id
         })
       );
     // Execution tracking
     case "start_execution":
-      return ok(await client2.execution({ action: "start", task_uid, agent_id }));
+      return ok3(
+        await client2.execution({
+          action: "start",
+          label,
+          summary,
+          confidence,
+          salience,
+          plan_uid,
+          executor_uid,
+          affordance_uid,
+          related_uids,
+          input_snapshot,
+          props,
+          agent_id
+        })
+      );
     case "complete_execution":
-      return ok(await client2.execution({ action: "complete", task_uid, agent_id }));
+      return ok3(
+        await client2.execution({
+          action: "complete",
+          execution_uid,
+          produces_node_uid,
+          output_snapshot,
+          side_effects,
+          outcome,
+          props,
+          agent_id
+        })
+      );
     case "fail_execution":
-      return ok(await client2.execution({ action: "fail", task_uid, agent_id }));
+      return ok3(
+        await client2.execution({
+          action: "fail",
+          execution_uid,
+          output_snapshot,
+          side_effects,
+          outcome,
+          error,
+          props,
+          agent_id
+        })
+      );
+    case "register_agent":
+      return ok3(
+        await client2.execution({
+          action: "register_agent",
+          label,
+          summary,
+          confidence,
+          salience,
+          props,
+          agent_id
+        })
+      );
+    case "get_executions":
+      return ok3(
+        await client2.execution({
+          action: "get_executions",
+          filter_plan_uid,
+          agent_id
+        })
+      );
     // Governance — read-only from MCP by design (C33). The write actions were
     // removed rather than repaired: `resolve_approval` here also sent
     // `task_uid` where the server requires `approval_uid`, and never sent
@@ -982,12 +2846,12 @@ async function handlePlan(client2, args) {
     // DENIED every approval an agent tried to resolve. Wiring that correctly
     // would have meant building a working self-approval path — the hole itself.
     case "get_pending":
-      return ok(await client2.governance({ action: "get_pending", agent_id }));
+      return ok3(await client2.governance({ action: "get_pending", agent_id }));
     // Procedures (merged from mindgraph_action)
     case "create_flow":
     case "add_affordance":
     case "add_control":
-      return ok(
+      return ok3(
         await client2.procedure({
           action,
           label,
@@ -998,7 +2862,7 @@ async function handlePlan(client2, args) {
         })
       );
     case "add_procedure_step":
-      return ok(
+      return ok3(
         await client2.procedure({
           action: "add_step",
           label,
@@ -1010,7 +2874,7 @@ async function handlePlan(client2, args) {
       );
     // Risk assessment (merged from mindgraph_action)
     case "assess_risk":
-      return ok(
+      return ok3(
         await client2.risk({
           action: "assess",
           label,
@@ -1021,7 +2885,7 @@ async function handlePlan(client2, args) {
         })
       );
     case "get_assessments":
-      return ok(
+      return ok3(
         await client2.risk({
           action: "get_assessments",
           target_uid,
@@ -1029,7 +2893,7 @@ async function handlePlan(client2, args) {
         })
       );
     default:
-      return err(`Unknown plan action: ${action}`);
+      return err3(`Unknown plan action: ${action}`);
   }
 }
 async function handleRetrieve(client2, args) {
@@ -1058,8 +2922,8 @@ async function handleRetrieve(client2, args) {
   } = args;
   switch (action) {
     case "context":
-      if (!query) return err("query is required for context retrieval");
-      return ok(
+      if (!query) return err3("query is required for context retrieval");
+      return ok3(
         await client2.retrieveContext({
           query,
           node_limit: limit,
@@ -1072,8 +2936,8 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "text":
-      if (!query) return err("query is required for text search");
-      return ok(
+      if (!query) return err3("query is required for text search");
+      return ok3(
         await client2.retrieve({
           action: "text",
           query,
@@ -1084,8 +2948,8 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "semantic":
-      if (!query) return err("query is required for semantic search");
-      return ok(
+      if (!query) return err3("query is required for semantic search");
+      return ok3(
         await client2.retrieve({
           action: "semantic",
           query,
@@ -1096,8 +2960,8 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "hybrid":
-      if (!query) return err("query is required for hybrid search");
-      return ok(
+      if (!query) return err3("query is required for hybrid search");
+      return ok3(
         await client2.retrieve({
           action: "hybrid",
           query,
@@ -1109,17 +2973,17 @@ async function handleRetrieve(client2, args) {
       );
     // Structured queries
     case "active_goals":
-      return ok(await client2.getGoals());
+      return ok3(await client2.getGoals());
     case "open_questions":
-      return ok(await client2.getOpenQuestions());
+      return ok3(await client2.getOpenQuestions());
     case "weak_claims":
-      return ok(await client2.getWeakClaims());
+      return ok3(await client2.getWeakClaims());
     case "pending_approvals":
-      return ok(await client2.getPendingApprovals());
+      return ok3(await client2.getPendingApprovals());
     case "unresolved_contradictions":
-      return ok(await client2.getContradictions());
+      return ok3(await client2.getContradictions());
     case "stale_derivations":
-      return ok(
+      return ok3(
         await client2.retrieve({
           action: "stale_derivations",
           limit,
@@ -1127,7 +2991,7 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "preferences":
-      return ok(
+      return ok3(
         await client2.retrieve({
           action: "preferences",
           ...query ? { query, k: limit } : {},
@@ -1136,8 +3000,8 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "layer":
-      if (!layer) return err("layer is required for layer retrieval");
-      return ok(
+      if (!layer) return err3("layer is required for layer retrieval");
+      return ok3(
         await client2.retrieve({
           action: "layer",
           layer,
@@ -1146,7 +3010,7 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "recent":
-      return ok(
+      return ok3(
         await client2.retrieve({
           action: "recent",
           limit,
@@ -1158,7 +3022,7 @@ async function handleRetrieve(client2, args) {
       );
     // Document inventory
     case "document_index":
-      return ok(
+      return ok3(
         await client2.getNodes({
           node_type: "Document",
           limit: limit ?? 100
@@ -1166,8 +3030,8 @@ async function handleRetrieve(client2, args) {
       );
     // Graph traversal
     case "chain":
-      if (!start_uid) return err("start_uid is required for chain traversal");
-      return ok(
+      if (!start_uid) return err3("start_uid is required for chain traversal");
+      return ok3(
         await client2.traverse({
           action: "chain",
           start_uid,
@@ -1178,8 +3042,8 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "neighborhood":
-      if (!start_uid) return err("start_uid is required for neighborhood traversal");
-      return ok(
+      if (!start_uid) return err3("start_uid is required for neighborhood traversal");
+      return ok3(
         await client2.traverse({
           action: "neighborhood",
           start_uid,
@@ -1192,9 +3056,9 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "path":
-      if (!start_uid) return err("start_uid is required for path traversal");
-      if (!end_uid) return err("end_uid is required for path traversal");
-      return ok(
+      if (!start_uid) return err3("start_uid is required for path traversal");
+      if (!end_uid) return err3("end_uid is required for path traversal");
+      return ok3(
         await client2.traverse({
           action: "path",
           start_uid,
@@ -1208,8 +3072,8 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "subgraph":
-      if (!start_uid) return err("start_uid is required for subgraph traversal");
-      return ok(
+      if (!start_uid) return err3("start_uid is required for subgraph traversal");
+      return ok3(
         await client2.traverse({
           action: "subgraph",
           start_uid,
@@ -1222,7 +3086,7 @@ async function handleRetrieve(client2, args) {
         })
       );
     default:
-      return err(`Unknown retrieve action: ${action}`);
+      return err3(`Unknown retrieve action: ${action}`);
   }
 }
 async function handleIngest(client2, args) {
@@ -1251,7 +3115,7 @@ async function handleIngest(client2, args) {
   const targetsOntology = Array.isArray(layers) && layers.includes("ontology");
   const cognitiveLayers = targetsOntology ? layers.filter((layer) => layer !== "ontology") : layers;
   if (targetsOntology && !ontology_schema_id) {
-    return err(
+    return err3(
       "layers included 'ontology' but no ontology_schema_id was supplied. Typed Layer-7 extraction is driven by ontology_schema_id, not by the layers list \u2014 pass the schema id, or drop 'ontology' from layers."
     );
   }
@@ -1259,8 +3123,8 @@ async function handleIngest(client2, args) {
   const ontologyOnly = targetsOntology && forwardedLayers === void 0;
   switch (action) {
     case "chunk":
-      if (!content) return err("content is required for chunk ingestion");
-      return ok(
+      if (!content) return err3("content is required for chunk ingestion");
+      return ok3(
         await client2.ingestChunk({
           content,
           label: title,
@@ -1274,8 +3138,8 @@ async function handleIngest(client2, args) {
         })
       );
     case "document":
-      if (!content) return err("content is required for document ingestion");
-      return ok(
+      if (!content) return err3("content is required for document ingestion");
+      return ok3(
         await client2.ingestDocument({
           content,
           title,
@@ -1294,8 +3158,8 @@ async function handleIngest(client2, args) {
         })
       );
     case "session":
-      if (!content) return err("content is required for session ingestion");
-      return ok(
+      if (!content) return err3("content is required for session ingestion");
+      return ok3(
         await client2.ingestSession({
           content,
           title,
@@ -1312,11 +3176,11 @@ async function handleIngest(client2, args) {
       );
     case "job_status":
       if (job_id) {
-        return ok(await client2.getJob(job_id));
+        return ok3(await client2.getJob(job_id));
       }
-      return ok(await client2.listJobs());
+      return ok3(await client2.listJobs());
     default:
-      return err(`Unknown ingest action: ${action}`);
+      return err3(`Unknown ingest action: ${action}`);
   }
 }
 async function handleSynthesize(client2, args) {
@@ -1324,19 +3188,19 @@ async function handleSynthesize(client2, args) {
   switch (action) {
     case "signals":
       if (!project_uid)
-        return err("project_uid is required for action='signals'");
-      return ok(
+        return err3("project_uid is required for action='signals'");
+      return ok3(
         await client2.signals(project_uid, { signals, target_types })
       );
     case "run":
       if (!project_uid)
-        return err("project_uid is required for action='run'");
-      return ok(await client2.runSynthesis(project_uid));
+        return err3("project_uid is required for action='run'");
+      return ok3(await client2.runSynthesis(project_uid));
     case "job_status":
-      if (!job_id) return err("job_id is required for action='job_status'");
-      return ok(await client2.getJob(job_id));
+      if (!job_id) return err3("job_id is required for action='job_status'");
+      return ok3(await client2.getJob(job_id));
     default:
-      return err(`Unknown synthesize action: ${action}`);
+      return err3(`Unknown synthesize action: ${action}`);
   }
 }
 async function handleOntology(client2, args) {
@@ -1364,18 +3228,18 @@ async function handleOntology(client2, args) {
   } = args;
   switch (action) {
     case "schemas":
-      return ok(await client2.listOntologySchemas());
+      return ok3(await client2.listOntologySchemas());
     case "schema":
-      if (!schema_id) return err("schema_id is required for action='schema'");
-      return ok(await client2.getOntologySchema(schema_id));
+      if (!schema_id) return err3("schema_id is required for action='schema'");
+      return ok3(await client2.getOntologySchema(schema_id));
     case "query": {
-      if (!query) return err("query is required for action='query'");
+      if (!query) return err3("query is required for action='query'");
       if (!schema_id) {
-        return err(
+        return err3(
           "schema_id is required for action='query' (use action='schemas' to find the active schema)"
         );
       }
-      return ok(
+      return ok3(
         await client2.queryOntology({
           query,
           schema_id,
@@ -1388,8 +3252,8 @@ async function handleOntology(client2, args) {
       );
     }
     case "search":
-      if (!query) return err("query is required for action='search'");
-      return ok(
+      if (!query) return err3("query is required for action='search'");
+      return ok3(
         await client2.searchDomainObjects(query, {
           schema_id,
           object_types,
@@ -1397,18 +3261,18 @@ async function handleOntology(client2, args) {
         })
       );
     case "objects":
-      if (!schema_id) return err("schema_id is required for action='objects'");
-      return ok(
+      if (!schema_id) return err3("schema_id is required for action='objects'");
+      return ok3(
         await client2.listDomainObjects({ schema_id, object_type, limit })
       );
     case "object":
-      if (!uid) return err("uid is required for action='object'");
-      return ok(await client2.getDomainObject(uid));
+      if (!uid) return err3("uid is required for action='object'");
+      return ok3(await client2.getDomainObject(uid));
     case "object_context":
-      if (!uid) return err("uid is required for action='object_context'");
-      return ok(await client2.getDomainObjectContext(uid, depth));
+      if (!uid) return err3("uid is required for action='object_context'");
+      return ok3(await client2.getDomainObjectContext(uid, depth));
     case "proposals":
-      return ok(
+      return ok3(
         await client2.listOntologyProposals({
           status: status ?? "pending",
           schema_id,
@@ -1417,21 +3281,21 @@ async function handleOntology(client2, args) {
         })
       );
     case "proposal":
-      if (!proposal_id) return err("proposal_id is required for action='proposal'");
-      return ok(await client2.getOntologyProposal(proposal_id));
+      if (!proposal_id) return err3("proposal_id is required for action='proposal'");
+      return ok3(await client2.getOntologyProposal(proposal_id));
     case "approve":
-      if (!proposal_id) return err("proposal_id is required for action='approve'");
-      return ok(await client2.approveOntologyProposal(proposal_id, { feedback }));
+      if (!proposal_id) return err3("proposal_id is required for action='approve'");
+      return ok3(await client2.approveOntologyProposal(proposal_id, { feedback }));
     case "reject":
-      if (!proposal_id) return err("proposal_id is required for action='reject'");
-      return ok(await client2.rejectOntologyProposal(proposal_id, reason));
+      if (!proposal_id) return err3("proposal_id is required for action='reject'");
+      return ok3(await client2.rejectOntologyProposal(proposal_id, reason));
     case "link": {
       if (!from_uid || !to_uid || !relation_type) {
-        return err(
+        return err3(
           "from_uid, to_uid, and relation_type are required for action='link'"
         );
       }
-      return ok(
+      return ok3(
         await client2.linkDomainObjects({
           from_uid,
           to_uid,
@@ -1442,11 +3306,11 @@ async function handleOntology(client2, args) {
       );
     }
     case "extract": {
-      if (!schema_id) return err("schema_id is required for action='extract'");
+      if (!schema_id) return err3("schema_id is required for action='extract'");
       if (!source_uids?.length) {
-        return err("source_uids is required for action='extract'");
+        return err3("source_uids is required for action='extract'");
       }
-      return ok(
+      return ok3(
         await client2.extractOntology({
           ontology_schema_id: schema_id,
           source_uids
@@ -1454,15 +3318,15 @@ async function handleOntology(client2, args) {
       );
     }
     default:
-      return err(`Unknown ontology action: ${action}`);
+      return err3(`Unknown ontology action: ${action}`);
   }
 }
 
 // src/generated-tools.ts
-var ok2 = (data) => ({
+var ok4 = (data) => ({
   content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
 });
-var err2 = (message) => ({
+var err4 = (message) => ({
   content: [{ type: "text", text: JSON.stringify({ error: message }) }],
   isError: true
 });
@@ -1529,10 +3393,10 @@ async function handleGeneratedTool(client2, desc, args) {
     switch (desc.maps_to) {
       case "search": {
         const query = args.query;
-        if (!query) return err2(`query is required for ${desc.name}`);
+        if (!query) return err4(`query is required for ${desc.name}`);
         const limit = typeof args.limit === "number" ? args.limit : void 0;
         const filters = Array.isArray(args.filters) ? args.filters : void 0;
-        return ok2(
+        return ok4(
           await ontologyClient.searchDomainObjects(query, {
             schema_id: desc.schema_id,
             object_types: [desc.object_type],
@@ -1543,33 +3407,33 @@ async function handleGeneratedTool(client2, desc, args) {
       }
       case "object": {
         const uid = args.uid;
-        if (!uid) return err2(`uid is required for ${desc.name}`);
-        return ok2(await ontologyClient.getDomainObject(uid, {
+        if (!uid) return err4(`uid is required for ${desc.name}`);
+        return ok4(await ontologyClient.getDomainObject(uid, {
           schema_id: desc.schema_id,
           object_type: desc.object_type
         }));
       }
       case "object_context": {
         const uid = args.uid;
-        if (!uid) return err2(`uid is required for ${desc.name}`);
+        if (!uid) return err4(`uid is required for ${desc.name}`);
         const depth = typeof args.depth === "number" ? args.depth : void 0;
-        return ok2(await ontologyClient.getDomainObjectContext(uid, depth, {
+        return ok4(await ontologyClient.getDomainObjectContext(uid, depth, {
           schema_id: desc.schema_id,
           object_type: desc.object_type
         }));
       }
       case "related": {
         const uid = args.uid;
-        if (!uid) return err2(`uid is required for ${desc.name}`);
+        if (!uid) return err4(`uid is required for ${desc.name}`);
         if (!desc.relation || !desc.entry_role || !desc.far_type) {
-          return err2(`invalid related descriptor: ${desc.name}`);
+          return err4(`invalid related descriptor: ${desc.name}`);
         }
         if (!ontologyClient.queryRelatedDomainObjects) {
-          return err2(
+          return err4(
             "related ontology tools require a graph-aware version of the mindgraph SDK"
           );
         }
-        return ok2(await ontologyClient.queryRelatedDomainObjects({
+        return ok4(await ontologyClient.queryRelatedDomainObjects({
           schema_id: desc.schema_id,
           entry_type: desc.object_type,
           uid,
@@ -1584,9 +3448,9 @@ async function handleGeneratedTool(client2, desc, args) {
       }
       case "structured_query": {
         const select = args.select;
-        if (!select) return err2(`select is required for ${desc.name}`);
+        if (!select) return err4(`select is required for ${desc.name}`);
         if (!ontologyClient.queryDomainStructured) {
-          return err2(
+          return err4(
             "structured ontology tools require a graph-aware version of the mindgraph SDK"
           );
         }
@@ -1597,13 +3461,13 @@ async function handleGeneratedTool(client2, desc, args) {
         for (const field of STRUCTURED_QUERY_PASSTHROUGH) {
           if (args[field] !== void 0) request[field] = args[field];
         }
-        return ok2(await ontologyClient.queryDomainStructured(request));
+        return ok4(await ontologyClient.queryDomainStructured(request));
       }
       default:
-        return err2(`unknown generated tool mapping: ${desc.maps_to}`);
+        return err4(`unknown generated tool mapping: ${desc.maps_to}`);
     }
   } catch (e) {
-    return err2(e instanceof Error ? e.message : String(e));
+    return err4(e instanceof Error ? e.message : String(e));
   }
 }
 
@@ -1617,7 +3481,7 @@ function isTransientStatus(status) {
   return status === 408 || status === 425 || status === 429 || status >= 500;
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 var KNOWN_DUTIES = /* @__PURE__ */ new Set(["log", "require_approval"]);
 function headers(apiKey, orgId) {
@@ -1634,6 +3498,105 @@ function unsupportedResponse(status, body) {
   const lower = body.toLowerCase();
   return lower.includes("unknown governance action") || lower.includes("unknown action") || lower.includes("invalid_governance_action");
 }
+var PLAN_READ_ACTIONS = /* @__PURE__ */ new Set([
+  "get_plan",
+  "get_executions",
+  "get_pending",
+  "get_assessments",
+  "resume_work"
+]);
+var ONTOLOGY_READ_ACTIONS = /* @__PURE__ */ new Set([
+  "list_schemas",
+  "get_schema",
+  "query",
+  "search_objects",
+  "list_objects",
+  "get_object",
+  "get_context",
+  "list_proposals",
+  "get_proposal"
+]);
+function toolMutability(toolName, action) {
+  if (toolName === "mindgraph_retrieve") return "read";
+  if (toolName === "mindgraph_plan") {
+    return action && PLAN_READ_ACTIONS.has(action) ? "read" : "write";
+  }
+  if (toolName === "mindgraph_ingest") {
+    return action === "job_status" ? "read" : "write";
+  }
+  if (toolName === "mindgraph_synthesize") {
+    return action === "signals" ? "read" : "write";
+  }
+  if (toolName === "mindgraph_code") {
+    return action === "anchor" ? "write" : "read";
+  }
+  if (toolName === "mindgraph_sync") {
+    return action === "scan" || action === "status" ? "read" : "write";
+  }
+  if (toolName === "mindgraph_ontology") {
+    return action && ONTOLOGY_READ_ACTIONS.has(action) ? "read" : "write";
+  }
+  if (/_(search|get|context|related|query)$/.test(toolName) && toolName !== "mindgraph_capture") {
+    return "read";
+  }
+  return "write";
+}
+var UID_FIELDS = [
+  "uid",
+  "source_uid",
+  "session_uid",
+  "work_uid",
+  "goal_uid",
+  "project_uid",
+  "task_uid",
+  "plan_uid",
+  "step_uid",
+  "target_uid",
+  "execution_uid",
+  "executor_uid",
+  "affordance_uid",
+  "produces_node_uid",
+  "filter_plan_uid",
+  "parent_uid",
+  "decision_uid",
+  "chosen_option_uid",
+  "governed_uid",
+  "approval_uid",
+  "requires_plan_uid",
+  "start_uid",
+  "end_uid"
+];
+var UID_ARRAY_FIELDS = [
+  "related_uids",
+  "depends_on_uids",
+  "summarizes_uids",
+  "informs_uid",
+  "target_uids",
+  "anchor_uids",
+  "scope_uids",
+  "produces_node_uids"
+];
+function governanceTarget(toolName, args) {
+  const action = typeof args.action === "string" ? args.action : void 0;
+  const targetUids = /* @__PURE__ */ new Set();
+  for (const field of UID_FIELDS) {
+    const value = args[field];
+    if (typeof value === "string" && value.length > 0) targetUids.add(value);
+  }
+  for (const field of UID_ARRAY_FIELDS) {
+    const value = args[field];
+    if (!Array.isArray(value)) continue;
+    for (const uid of value) {
+      if (typeof uid === "string" && uid.length > 0) targetUids.add(uid);
+    }
+  }
+  return {
+    tool_name: toolName,
+    ...action ? { action } : {},
+    mutability: toolMutability(toolName, action),
+    target_uids: [...targetUids]
+  };
+}
 async function checkMcpGovernance(toolName, args, config) {
   if (config.disabled) return { allowed: true };
   if (capability === "unsupported") {
@@ -1656,7 +3619,7 @@ async function checkMcpGovernance(toolName, args, config) {
             action: "check",
             act: "tool_invoke",
             agent_id: String(args.agent_id || config.agentId),
-            target: { tool_name: toolName },
+            target: governanceTarget(toolName, args),
             context: { adapter: "mindgraph-mcp", ...config.context },
             tier: "checkpoint"
           })
@@ -1853,13 +3816,15 @@ var API_KEY = process.env.MINDGRAPH_API_KEY;
 var BASE_URL = process.env.MINDGRAPH_BASE_URL || "https://api.mindgraph.cloud";
 var AGENT_ID = process.env.MINDGRAPH_AGENT_ID || "mcp";
 var ORG_ID = process.env.MINDGRAPH_ORG_ID;
+var PROFILE = process.env.MINDGRAPH_PROFILE || "general";
+var HARNESS = process.env.MINDGRAPH_HARNESS || "generic";
 if (!API_KEY) {
   console.error(
     "Error: MINDGRAPH_API_KEY environment variable is required.\nGet your API key at https://mindgraph.cloud/dashboard/keys\nOr run: npx mindgraph-mcp init"
   );
   process.exit(1);
 }
-var client = new import_mindgraph.MindGraph({
+var client = new import_mindgraph2.MindGraph({
   baseUrl: BASE_URL,
   apiKey: API_KEY,
   orgId: ORG_ID,
@@ -1868,7 +3833,7 @@ var client = new import_mindgraph.MindGraph({
   // window where npm may still resolve the preceding SDK declaration file.
   telemetrySurface: "mcp"
 });
-var INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph (7 tools).
+var INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph, plus any ontology tools generated by the active schema.
 
 ## #1 RULE: Go straight to the user's topic
 
@@ -1931,22 +3896,42 @@ Capture knowledge when the user shares something worth remembering:
 - Questions to track \u2192 \`mindgraph_reason\` action "open_question"
 - Goals or projects \u2192 \`mindgraph_commit\` action "goal"/"project"
 - Decisions \u2192 \`mindgraph_commit\` action "open_decision"
+- Durable engineering work that must survive sessions/harnesses \u2192 \`mindgraph_plan\`
+- Typed code anchors, attached memory/work, callers/callees, or impact \u2192 \`mindgraph_code\`
+- Reusable learning from a material attempt \u2192 \`mindgraph_capture\` action "lesson"
 - Long-form content \u2192 \`mindgraph_ingest\`
 - Cross-document synthesis over a project corpus \u2192 \`mindgraph_synthesize\` (action "signals" for structural signals; action "run" to spawn a synthesis job that writes Article nodes)
 
 ## Tool tips
 
+- Use the harness todo list to organize only the current harness's local execution. Use \`mindgraph_plan\` when work is authoritative across sessions/harnesses, needs graph relationships or evidence, or must be visible to other agents. Do not maintain the same item in both.
+- If a local harness task remains unfinished and should become authoritative outside that local list, promote it once with a stable idempotency key when the graph-managed composite actions are available; otherwise do not copy it.
 - \`capture\`: "entity"/"observation" for facts, "journal" for personal/informal
 - \`reason\`: "claim" when evidence exists, "open_question"/"hypothesis" otherwise
 - \`retrieve\`: "context" returns graph nodes only by default \u2014 set include_chunks=true for source text
 - \`retrieve\`: "context" (FTS default) \u2192 "semantic" (conceptual fallback) \u2192 "hybrid" (both)
 - \`retrieve\`: "neighborhood"/"chain"/"path"/"subgraph" for graph exploration
+- \`code\`: pass path + symbol + signature when names are overloaded; ambiguity never writes
 - Confidence: 0.9+ for facts, 0.5-0.8 for uncertain, <0.5 for speculation
 - Don't narrate tool usage \u2014 capture naturally as part of conversation`;
+if (PROFILE === "coding") {
+  INSTRUCTIONS += `
+
+## Coding profile
+
+- Use mindgraph_sync for explicit, one-way project memory-file imports. It discovers and hashes files, but you deliberately map durable assertions with record; it never writes graph state back to files.
+- Capture corrections, decisions with rationale, fixes that survived meaningful failed attempts, durable invariants/preferences, and blockers with evidence.
+- Do not capture routine mechanics, transient command output, facts cheaply derivable from code, unsupported speculation as high-confidence lessons, or completion without evidence.
+- Adapter context is owned by ${HARNESS}; omit invocation_context because hooks replace it.`;
+} else {
+  INSTRUCTIONS = INSTRUCTIONS.split("\n").filter(
+    (line) => !line.includes("mindgraph_code") && !line.includes("`code`") && !line.includes("Typed code anchors")
+  ).join("\n");
+}
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.13.5"
+    version: "0.14.1"
   },
   {
     capabilities: {
@@ -1959,7 +3944,7 @@ var server = new import_server.Server(
 );
 server.setRequestHandler(import_types.ListToolsRequestSchema, async () => {
   const generated = await getGeneratedTools(client);
-  return { tools: [...TOOLS, ...generated.tools] };
+  return { tools: [...toolsForProfile(PROFILE), ...generated.tools] };
 });
 var GOVERNANCE_CONFIG = {
   baseUrl: BASE_URL,