mindgraph-mcp 0.14.9 → 0.16.0

package/dist/cli.js

@@ -915,6 +915,61 @@ var init_dist = __esm({
   }
 });
 
+// src/hook-env.ts
+function stableAgentId() {
+  let user = "user";
+  try {
+    user = import_node_os.default.userInfo().username || "user";
+  } catch {
+  }
+  const digest = import_node_crypto.default.createHash("sha256").update(`${user}@${import_node_os.default.hostname()}`).digest("hex").slice(0, 12);
+  return `u-${digest}`;
+}
+function hookEnvPath(dir) {
+  return import_node_path.default.join(dir || import_node_path.default.join(import_node_os.default.homedir(), ".mindgraph"), "hooks.json");
+}
+function loadHookEnv(dir) {
+  try {
+    const raw = import_node_fs.default.readFileSync(hookEnvPath(dir), "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+      baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : void 0,
+      apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : void 0,
+      agentId: typeof parsed.agentId === "string" ? parsed.agentId : void 0,
+      orgId: typeof parsed.orgId === "string" ? parsed.orgId : void 0
+    };
+  } catch {
+    return {};
+  }
+}
+function saveHookEnv(env, dir) {
+  const file = hookEnvPath(dir);
+  import_node_fs.default.mkdirSync(import_node_path.default.dirname(file), { recursive: true });
+  const existing = loadHookEnv(dir);
+  const merged = {
+    baseUrl: env.baseUrl ?? existing.baseUrl,
+    apiKey: env.apiKey ?? existing.apiKey,
+    agentId: env.agentId ?? existing.agentId,
+    orgId: env.orgId === null ? void 0 : env.orgId ?? existing.orgId
+  };
+  import_node_fs.default.writeFileSync(file, `${JSON.stringify(merged, null, 2)}
+`, {
+    mode: 384
+  });
+  import_node_fs.default.chmodSync(file, 384);
+  return file;
+}
+var import_node_crypto, import_node_fs, import_node_os, import_node_path;
+var init_hook_env = __esm({
+  "src/hook-env.ts"() {
+    "use strict";
+    import_node_crypto = __toESM(require("crypto"));
+    import_node_fs = __toESM(require("fs"));
+    import_node_os = __toESM(require("os"));
+    import_node_path = __toESM(require("path"));
+  }
+});
+
 // src/codegraph.ts
 function unavailabilityCaveats(reason, message) {
   const caveats = [message || "codegraph status failed"];
@@ -1095,7 +1150,7 @@ function codeRefIdentityKey(ref) {
     }
   };
 }
-var import_node_child_process, import_node_fs2, import_promises, import_node_os2, import_node_path2, import_node_crypto, DEFAULT_TIMEOUT_MS, DEFAULT_STATUS_TTL_MS, MAX_OUTPUT_BYTES, CodegraphAdapter;
+var import_node_child_process, import_node_fs2, import_promises, import_node_os2, import_node_path2, import_node_crypto2, DEFAULT_TIMEOUT_MS, DEFAULT_STATUS_TTL_MS, MAX_OUTPUT_BYTES, CodegraphAdapter;
 var init_codegraph = __esm({
   "src/codegraph.ts"() {
     "use strict";
@@ -1104,7 +1159,7 @@ var init_codegraph = __esm({
     import_promises = require("fs/promises");
     import_node_os2 = require("os");
     import_node_path2 = require("path");
-    import_node_crypto = require("crypto");
+    import_node_crypto2 = require("crypto");
     DEFAULT_TIMEOUT_MS = 5e3;
     DEFAULT_STATUS_TTL_MS = 6e4;
     MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
@@ -1204,7 +1259,7 @@ var init_codegraph = __esm({
         } catch {
         }
         (0, import_node_fs2.mkdirSync)(identityDir, { recursive: true, mode: 448 });
-        const generated = (0, import_node_crypto.randomUUID)();
+        const generated = (0, import_node_crypto2.randomUUID)();
         try {
           (0, import_node_fs2.writeFileSync)(identityFile, `${generated}
 `, {
@@ -1617,10 +1672,28 @@ function errorDetail(e) {
   }
   return e instanceof Error ? e.message : String(e);
 }
+function conflictState(e) {
+  if (!(e instanceof MindGraphError) || !e.body || typeof e.body !== "object") {
+    return {};
+  }
+  const body = e.body;
+  const lifted = {};
+  for (const key of CONFLICT_STATE_KEYS) {
+    if (body[key] !== void 0) lifted[key] = body[key];
+  }
+  return lifted;
+}
+var CONFLICT_STATE_KEYS;
 var init_error_detail = __esm({
   "src/error-detail.ts"() {
     "use strict";
     init_dist();
+    CONFLICT_STATE_KEYS = [
+      "current_version",
+      "current_epoch",
+      "lease_expires_at",
+      "lease_owner_agent_id"
+    ];
   }
 });
 
@@ -2144,7 +2217,7 @@ function fileDescriptor(root, absolute) {
   const content = import_node_fs5.default.readFileSync(absolute, "utf8");
   return {
     logical_path: import_node_path5.default.relative(root, absolute).split(import_node_path5.default.sep).join("/"),
-    content_hash: import_node_crypto4.default.createHash("sha256").update(content).digest("hex"),
+    content_hash: import_node_crypto5.default.createHash("sha256").update(content).digest("hex"),
     bytes: Buffer.byteLength(content),
     content
   };
@@ -2252,11 +2325,11 @@ async function scanRepository(remote, repository, requested, provider, agentId)
     files: results
   };
 }
-var import_node_crypto4, import_node_fs5, import_node_path5, ok2, err2, SYNC_TOOL;
+var import_node_crypto5, import_node_fs5, import_node_path5, ok2, err2, SYNC_TOOL;
 var init_sync_tool = __esm({
   "src/sync-tool.ts"() {
     "use strict";
-    import_node_crypto4 = __toESM(require("crypto"));
+    import_node_crypto5 = __toESM(require("crypto"));
     import_node_fs5 = __toESM(require("fs"));
     import_node_path5 = __toESM(require("path"));
     init_codegraph();
@@ -2339,6 +2412,361 @@ var init_sync_tool = __esm({
   }
 });
 
+// src/render.ts
+function obj(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function str(value) {
+  return typeof value === "string" && value ? value : void 0;
+}
+function num(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function clip(value, max, state) {
+  const text = str(value);
+  if (!text) return void 0;
+  if (text.length <= max) return text;
+  state.bounded = true;
+  return `${text.slice(0, max - 1)}\u2026`;
+}
+function isNodeShaped(value) {
+  const node = obj(value);
+  return Boolean(node && str(node.uid) && (str(node.label) || str(node.node_type)));
+}
+function unwrapSearchResult(value) {
+  if (isNodeShaped(value)) return value;
+  const wrapper = obj(value);
+  const inner = obj(wrapper?.node);
+  if (inner && isNodeShaped(inner)) {
+    const score = num(wrapper.score);
+    return score !== void 0 ? { ...inner, retrieval_score: score } : inner;
+  }
+  return void 0;
+}
+function statusTag(node) {
+  const tags = [];
+  if (node.superseded === true) {
+    tags.push(
+      node.superseded_by ? `SUPERSEDED by ${str(node.superseded_by)}` : "SUPERSEDED"
+    );
+  }
+  const truth = str(node.truth_status) ?? str(obj(node.props)?.truth_status);
+  if (truth && truth !== "accepted") tags.push(`truth: ${truth}`);
+  if (node.currently_valid === false) tags.push("OUTSIDE ITS VALIDITY WINDOW");
+  if (node.valid_at_time === false) tags.push("NOT VALID AT THE REQUESTED TIME");
+  return tags.length > 0 ? ` [${tags.join("; ")}]` : "";
+}
+function firstQuote(node, state) {
+  const chunks = Array.isArray(node.source_chunks) ? node.source_chunks : [];
+  for (const raw of chunks) {
+    const chunk = obj(raw);
+    const quote = str(chunk?.quote) ?? str(obj(chunk?.anchor)?.exact);
+    if (quote) return clip(quote, QUOTE_MAX, state);
+  }
+  return void 0;
+}
+function sourceTag(node) {
+  const docs = Array.isArray(node.source_documents) ? node.source_documents : [];
+  const first = obj(docs[0]);
+  const title = str(first?.title);
+  if (!title) return void 0;
+  const extra = docs.length > 1 ? ` (+${docs.length - 1} more)` : "";
+  return `from: ${title}${extra}`;
+}
+function layer7Fields(node, state) {
+  const fields = obj(obj(node.props)?.fields);
+  if (!fields) return void 0;
+  const pairs = Object.entries(fields).filter(([, value]) => value !== null && value !== void 0 && value !== "").map(([key, value]) => `${key}: ${Array.isArray(value) ? value.join(", ") : String(value)}`);
+  if (pairs.length === 0) return void 0;
+  return clip(pairs.join("; "), SUMMARY_MAX, state);
+}
+function nodeSummaryText(node, state) {
+  const props = obj(node.props);
+  return clip(node.summary, SUMMARY_MAX, state) ?? clip(props?.content, SUMMARY_MAX, state) ?? clip(props?.description, SUMMARY_MAX, state) ?? clip(props?.definition, SUMMARY_MAX, state);
+}
+function nodeLines(node, state) {
+  const label = clip(node.label, LABEL_MAX, state) || "(unlabeled)";
+  const type = str(node.node_type) || "Node";
+  const confidence = num(node.confidence);
+  const score = num(node.retrieval_score);
+  const parenthetical = [
+    type,
+    confidence !== void 0 ? `confidence ${confidence}` : void 0,
+    score !== void 0 ? `score ${Math.round(score * 100) / 100}` : void 0
+  ].filter(Boolean).join(", ");
+  const head = `- **${label}** [${str(node.uid) || "?"}] (${parenthetical})${statusTag(node)}`;
+  const summary = nodeSummaryText(node, state);
+  const lines = [summary && summary !== label ? `${head}: ${summary}` : head];
+  const fields = layer7Fields(node, state);
+  if (fields) lines.push(`  - fields: ${fields}`);
+  const quote = firstQuote(node, state);
+  if (quote) lines.push(`  - source quote: "${quote}"`);
+  const source = sourceTag(node);
+  if (source) lines.push(`  - ${source}`);
+  const believers = Array.isArray(node.believed_by) ? node.believed_by : [];
+  if (believers.length > 0) {
+    const rendered = believers.slice(0, 3).map((raw) => {
+      const believer = obj(raw);
+      const conf = num(believer?.confidence);
+      return `${str(believer?.agent_label) || "?"}${conf !== void 0 ? ` (${conf})` : ""}`;
+    }).join(", ");
+    lines.push(`  - believed by: ${rendered}`);
+  }
+  return lines.join("\n");
+}
+function groupedNodeSections(nodes, state, headingPrefix = "") {
+  const groups = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    const type = str(node.node_type) || "Node";
+    const group = groups.get(type) ?? [];
+    group.push(node);
+    groups.set(type, group);
+  }
+  const sections = [];
+  let first = true;
+  for (const [type, group] of groups) {
+    sections.push({
+      heading: `${first ? headingPrefix : ""}### ${type}`,
+      items: group.map((node) => nodeLines(node, state))
+    });
+    first = false;
+  }
+  return sections;
+}
+function relationshipItems(edges, labelByUid, state) {
+  const lines = [];
+  for (const raw of edges) {
+    const edge = obj(raw);
+    if (!edge) continue;
+    const type = str(edge.edge_type) || "?";
+    const from = str(edge.from_uid);
+    const to = str(edge.to_uid);
+    if (CURATION_EDGE_TYPES.has(type)) continue;
+    if (!from || !to || from === to) continue;
+    const fromLabel = labelByUid.get(from);
+    const toLabel = labelByUid.get(to);
+    if (!fromLabel || !toLabel) continue;
+    lines.push(`- ${fromLabel} \u2014${type}\u2192 ${toLabel}`);
+  }
+  if (lines.length > RELATIONSHIP_MAX) {
+    state.bounded = true;
+    const extra = lines.length - RELATIONSHIP_MAX;
+    return [...lines.slice(0, RELATIONSHIP_MAX), `- (+${extra} more relationships)`];
+  }
+  return lines;
+}
+function assemble(header, sections, state) {
+  const lines = [header];
+  let used = header.length;
+  for (const section of sections) {
+    if (section.items.length === 0 && !section.heading) continue;
+    const headingCost = section.heading.length + 2;
+    if (used + headingCost > RENDER_CHAR_BUDGET) {
+      state.bounded = true;
+      continue;
+    }
+    let sectionUsed = 0;
+    const kept = [];
+    let dropped = 0;
+    for (const item of section.items) {
+      if (used + headingCost + sectionUsed + item.length + 1 > RENDER_CHAR_BUDGET) {
+        dropped += 1;
+        continue;
+      }
+      kept.push(item);
+      sectionUsed += item.length + 1;
+    }
+    if (kept.length === 0 && section.items.length > 0) {
+      state.bounded = true;
+      continue;
+    }
+    if (dropped > 0) {
+      state.bounded = true;
+      const marker = `(+${dropped} more not shown)`;
+      kept.push(marker);
+      sectionUsed += marker.length + 1;
+    }
+    lines.push(
+      section.items.length === 0 ? section.heading : `${section.heading}
+${kept.join("\n")}`
+    );
+    used += headingCost + sectionUsed;
+  }
+  if (state.bounded) {
+    lines.push(
+      '\u2026[rendered context bounded \u2014 fetch full node content by uid, or pass format: "json" for the raw response]'
+    );
+  }
+  return lines.join("\n\n");
+}
+function policySections(payload, state) {
+  const policies = Array.isArray(payload.applicable_policies) ? payload.applicable_policies : [];
+  if (policies.length === 0) return [];
+  const items = policies.map((raw) => obj(raw)).filter((policy) => Boolean(policy)).map((policy) => {
+    const rules = Array.isArray(policy.prose_rules) ? policy.prose_rules.map(String).join("; ") : policy.prose_rules;
+    return `- ${str(policy.name) || "(unnamed policy)"}: ${clip(rules, SUMMARY_MAX, state) || "(structured rules apply)"}`;
+  });
+  return [{ heading: "## Applicable policies", items }];
+}
+function hiddenSections(payload) {
+  const hidden = payload.hidden_item_count;
+  if (hidden === void 0 || hidden === null) return [];
+  return [
+    {
+      heading: `Note: ${hidden} item(s) were hidden by access scoping.`,
+      items: []
+    }
+  ];
+}
+function renderContext(response) {
+  const payload = obj(response);
+  if (!payload) return void 0;
+  const graph = obj(payload.graph);
+  const rawNodes = Array.isArray(graph?.nodes) ? graph.nodes : [];
+  const shaped = rawNodes.filter(isNodeShaped);
+  const nodes = shaped.filter((node) => !INFRA_NODE_TYPES.has(str(node.node_type) || ""));
+  const infraOnly = shaped.length - nodes.length;
+  const articles = Array.isArray(payload.articles) ? payload.articles : [];
+  const chunks = Array.isArray(payload.chunks) ? payload.chunks : [];
+  const state = { bounded: false };
+  const sections = [];
+  if (articles.length > 0) {
+    sections.push({
+      heading: "## Knowledge articles",
+      items: articles.map((raw) => obj(raw)).filter((article) => Boolean(article)).map(
+        (article) => `### ${str(article.label) || "(untitled)"} [${str(article.uid) || "?"}]
+${clip(article.content, ARTICLE_MAX, state) || ""}`
+      )
+    });
+  }
+  if (nodes.length > 0) {
+    sections.push(...groupedNodeSections(nodes, state, "## Knowledge graph\n\n"));
+    const labelByUid = /* @__PURE__ */ new Map();
+    for (const node of nodes) labelByUid.set(str(node.uid), str(node.label) || "?");
+    const relationships = relationshipItems(
+      Array.isArray(graph?.edges) ? graph.edges : [],
+      labelByUid,
+      state
+    );
+    if (relationships.length > 0) {
+      sections.push({ heading: "## Relationships", items: relationships });
+    }
+  } else if (infraOnly > 0) {
+    sections.push({
+      heading: `Note: ${infraOnly} document/chunk node(s) matched \u2014 use action "document_index" or include_chunks for their content.`,
+      items: []
+    });
+  }
+  if (chunks.length > 0) {
+    sections.push({
+      heading: "## Source excerpts",
+      items: chunks.map((raw) => obj(raw)).filter((chunk) => Boolean(chunk)).map(
+        (chunk) => `- [${str(chunk.chunk_uid) || "?"}] from "${str(chunk.document_title) || "unknown document"}": "${clip(chunk.content, CHUNK_MAX, state) || ""}"`
+      )
+    });
+  }
+  sections.push(...policySections(payload, state));
+  sections.push(...hiddenSections(payload));
+  if (sections.length === 0) {
+    return "No results found for this search.";
+  }
+  if (nodes.length === 0 && articles.length === 0 && chunks.length === 0) {
+    return assemble("# Retrieved context\n\nNo graph results matched this search.", sections, state);
+  }
+  return assemble("# Retrieved context", sections, state);
+}
+function renderNodeList(response, title, limit) {
+  let candidates = [];
+  if (Array.isArray(response)) {
+    candidates = response;
+  } else {
+    const payload = obj(response);
+    if (!payload) return void 0;
+    for (const key of ["nodes", "results", "items", "goals", "questions", "claims", "preferences", "documents"]) {
+      const candidate = payload[key];
+      if (Array.isArray(candidate) && candidate.some((entry) => unwrapSearchResult(entry))) {
+        candidates = candidate;
+        break;
+      }
+    }
+  }
+  let nodes = candidates.map(unwrapSearchResult).filter((node) => Boolean(node));
+  if (nodes.length === 0) return void 0;
+  const total = nodes.length;
+  const state = { bounded: false };
+  if (limit !== void 0 && limit > 0 && nodes.length > limit) {
+    nodes = nodes.slice(0, limit);
+    state.bounded = true;
+  }
+  const sections = groupedNodeSections(nodes, state);
+  const shown = nodes.length;
+  return assemble(
+    `# ${title} (${shown === total ? total : `${shown} of ${total}`})`,
+    sections,
+    state
+  );
+}
+function renderTraversal(response) {
+  const payload = obj(response);
+  if (!payload) return void 0;
+  const container = obj(payload.graph) ?? payload;
+  const rawNodes = Array.isArray(container.nodes) ? container.nodes : [];
+  const nodes = rawNodes.filter(isNodeShaped);
+  const paths = Array.isArray(payload.paths) ? payload.paths : [];
+  if (nodes.length === 0 && paths.length === 0) return void 0;
+  const state = { bounded: false };
+  const sections = [];
+  const labelByUid = /* @__PURE__ */ new Map();
+  for (const node of nodes) labelByUid.set(str(node.uid), str(node.label) || "?");
+  if (paths.length > 0) {
+    const items = paths.map((raw) => obj(raw)).filter((path6) => Boolean(path6)).map((path6, index) => {
+      const uids = Array.isArray(path6.node_uids) ? path6.node_uids.map(String) : [];
+      const labels = Array.isArray(path6.labels) ? path6.labels.map(String) : Array.isArray(path6.nodes) ? path6.nodes.map((hop) => {
+        const hopNode = obj(hop);
+        return str(hopNode?.label) || labelByUid.get(str(hopNode?.uid) || "") || str(hop) || "?";
+      }) : [];
+      const route = labels.length > 0 ? labels.join(" \u2192 ") : uids.join(" \u2192 ") || "(path)";
+      const cost = num(path6.cost) ?? num(path6.path_cost);
+      const confidence = num(path6.path_confidence);
+      const meta = [
+        cost !== void 0 ? `cost ${cost}` : void 0,
+        confidence !== void 0 ? `confidence ${confidence}` : void 0
+      ].filter(Boolean);
+      const head = `${index + 1}. ${route}${meta.length > 0 ? ` (${meta.join(", ")})` : ""}`;
+      return labels.length > 0 && uids.length > 0 ? `${head}
+   uids: ${uids.join(" \u2192 ")}` : head;
+    });
+    sections.push({ heading: "## Paths", items });
+  }
+  if (nodes.length > 0) {
+    sections.push(...groupedNodeSections(nodes, state, "## Nodes\n\n"));
+    const relationships = relationshipItems(
+      Array.isArray(container.edges) ? container.edges : [],
+      labelByUid,
+      state
+    );
+    if (relationships.length > 0) {
+      sections.push({ heading: "## Relationships", items: relationships });
+    }
+  }
+  return assemble("# Graph traversal", sections, state);
+}
+var LABEL_MAX, SUMMARY_MAX, QUOTE_MAX, ARTICLE_MAX, CHUNK_MAX, RELATIONSHIP_MAX, RENDER_CHAR_BUDGET, CURATION_EDGE_TYPES, INFRA_NODE_TYPES;
+var init_render = __esm({
+  "src/render.ts"() {
+    "use strict";
+    LABEL_MAX = 200;
+    SUMMARY_MAX = 400;
+    QUOTE_MAX = 180;
+    ARTICLE_MAX = 6e3;
+    CHUNK_MAX = 6e3;
+    RELATIONSHIP_MAX = 40;
+    RENDER_CHAR_BUDGET = 24e3;
+    CURATION_EDGE_TYPES = /* @__PURE__ */ new Set(["POSSIBLE_DUPLICATE", "PossibleDuplicate"]);
+    INFRA_NODE_TYPES = /* @__PURE__ */ new Set(["Chunk", "Document", "Article"]);
+  }
+});
+
 // src/tools.ts
 function toolsForProfile(profile = process.env.MINDGRAPH_PROFILE || "general") {
   if (profile === "coding") return TOOLS;
@@ -2405,6 +2833,18 @@ async function handleTool(client2, name, args) {
     ].includes(action);
     return attach ? await attachCodeRefsToToolResult(client2, result, args) : result;
   } catch (e) {
+    const lifted = conflictState(e);
+    if (Object.keys(lifted).length > 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ error: errorDetail(e), ...lifted })
+          }
+        ],
+        isError: true
+      };
+    }
     return err3(errorDetail(e));
   }
 }
@@ -2920,6 +3360,7 @@ async function handlePlan(client2, args) {
 async function handleRetrieve(client2, args) {
   const {
     action,
+    format,
     query,
     start_uid,
     end_uid,
@@ -2940,12 +3381,24 @@ async function handleRetrieve(client2, args) {
     graph_max_depth,
     confidence_min,
     salience_min,
+    article_limit,
+    valid_at,
+    created_after,
+    created_before,
+    explain,
+    k,
+    max_cost,
     agent_id
   } = args;
+  const rendered = (raw, render) => {
+    if (format === "json") return ok3(raw);
+    const text = render(raw);
+    return text !== void 0 ? { content: [{ type: "text", text }] } : ok3(raw);
+  };
   switch (action) {
     case "context":
       if (!query) return err3("query is required for context retrieval");
-      return ok3(
+      return rendered(
         await client2.retrieveContext({
           query,
           node_limit: limit,
@@ -2954,110 +3407,139 @@ async function handleRetrieve(client2, args) {
           chunk_limit: include_chunks ? limit ?? 5 : 0,
           // Scoped by default, never walled: the coding profile drops the
           // document/article leg (the "Bob Work" class of noise) unless the
-          // model opts in for a genuinely document-shaped question.
-          ...process.env.MINDGRAPH_PROFILE === "coding" && !include_documents ? { article_limit: 0 } : {},
+          // model opts in for a genuinely document-shaped question. Any
+          // profile can drop it with include_documents: false (previously a
+          // silent no-op outside coding). An EXPLICIT article_limit is at
+          // least as clear an opt-in as include_documents:true — it always
+          // wins over profile defaults (a coding-profile model reaching for
+          // the advertised knob must not get a silent no-op).
+          ...article_limit !== void 0 ? { article_limit } : include_documents === false || process.env.MINDGRAPH_PROFILE === "coding" && !include_documents ? { article_limit: 0 } : {},
+          valid_at,
           include_graph,
           graph_expansion_limit: graph_expansion_limit ?? 3,
           graph_max_depth: graph_max_depth ?? 2
-        })
+        }),
+        renderContext
       );
     case "text":
       if (!query) return err3("query is required for text search");
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "text",
           query,
           limit,
           node_types,
           layer,
+          explain,
           agent_id
-        })
+        }),
+        (raw) => renderNodeList(raw, `Text search: ${query}`)
       );
     case "semantic":
       if (!query) return err3("query is required for semantic search");
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "semantic",
           query,
           k: limit,
           node_types,
           layer,
+          explain,
           agent_id
-        })
+        }),
+        (raw) => renderNodeList(raw, `Semantic search: ${query}`)
       );
     case "hybrid":
       if (!query) return err3("query is required for hybrid search");
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "hybrid",
           query,
           k: limit,
           node_types,
           layer,
+          explain,
           agent_id
-        })
+        }),
+        // With explain, per-leg scoring must survive — raw JSON only.
+        explain ? () => void 0 : (raw) => renderNodeList(raw, `Hybrid search: ${query}`)
       );
-    // Structured queries
+    // Structured queries. These go through the generic /retrieve action
+    // dispatch rather than the SDK's no-argument convenience methods — the
+    // conveniences silently dropped `limit`/`offset` (the tool advertised
+    // them; five actions ignored them).
     case "active_goals":
-      return ok3(await client2.getGoals());
     case "open_questions":
-      return ok3(await client2.getOpenQuestions());
     case "weak_claims":
-      return ok3(await client2.getWeakClaims());
     case "pending_approvals":
-      return ok3(await client2.getPendingApprovals());
     case "unresolved_contradictions":
-      return ok3(await client2.getContradictions());
+      return rendered(
+        await client2.retrieve({
+          action,
+          limit,
+          offset,
+          agent_id
+        }),
+        (raw) => renderNodeList(raw, action.replace(/_/g, " "), limit)
+      );
     case "stale_derivations":
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "stale_derivations",
           limit,
           offset
-        })
+        }),
+        (raw) => renderNodeList(raw, "stale derivations", limit)
       );
     case "preferences":
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "preferences",
           ...query ? { query, k: limit } : {},
           limit,
           agent_id
-        })
+        }),
+        (raw) => renderNodeList(raw, "Preferences", limit)
       );
     case "layer":
       if (!layer) return err3("layer is required for layer retrieval");
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "layer",
           layer,
           limit,
+          node_types,
           agent_id
-        })
+        }),
+        (raw) => renderNodeList(raw, `Layer: ${layer}`, limit)
       );
     case "recent":
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "recent",
           limit,
           node_types,
           confidence_min,
           salience_min,
+          created_after,
+          created_before,
           agent_id
-        })
+        }),
+        (raw) => renderNodeList(raw, "Recently ingested", limit)
       );
     // Document inventory
     case "document_index":
-      return ok3(
+      return rendered(
         await client2.getNodes({
           node_type: "Document",
           limit: limit ?? 100
-        })
+        }),
+        (raw) => renderNodeList(raw, "Ingested documents")
       );
     // Graph traversal
     case "chain":
       if (!start_uid) return err3("start_uid is required for chain traversal");
-      return ok3(
+      return rendered(
         await client2.traverse({
           action: "chain",
           start_uid,
@@ -3065,11 +3547,12 @@ async function handleRetrieve(client2, args) {
           exclude_edge_types,
           include_provenance,
           max_nodes
-        })
+        }),
+        renderTraversal
       );
     case "neighborhood":
       if (!start_uid) return err3("start_uid is required for neighborhood traversal");
-      return ok3(
+      return rendered(
         await client2.traverse({
           action: "neighborhood",
           start_uid,
@@ -3079,12 +3562,13 @@ async function handleRetrieve(client2, args) {
           exclude_edge_types,
           include_provenance,
           max_nodes
-        })
+        }),
+        renderTraversal
       );
     case "path":
       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(
+      return rendered(
         await client2.traverse({
           action: "path",
           start_uid,
@@ -3095,11 +3579,12 @@ async function handleRetrieve(client2, args) {
           exclude_edge_types,
           include_provenance,
           max_nodes
-        })
+        }),
+        renderTraversal
       );
     case "subgraph":
       if (!start_uid) return err3("start_uid is required for subgraph traversal");
-      return ok3(
+      return rendered(
         await client2.traverse({
           action: "subgraph",
           start_uid,
@@ -3109,7 +3594,24 @@ async function handleRetrieve(client2, args) {
           exclude_edge_types,
           include_provenance,
           max_nodes
-        })
+        }),
+        renderTraversal
+      );
+    case "top_k_paths":
+      if (!start_uid) return err3("start_uid is required for top_k_paths");
+      if (!end_uid) return err3("end_uid is required for top_k_paths");
+      return rendered(
+        await client2.traverse({
+          action: "top_k_paths",
+          start_uid,
+          end_uid,
+          k,
+          max_hops: max_depth,
+          max_cost,
+          edge_types,
+          exclude_edge_types
+        }),
+        renderTraversal
       );
     default:
       return err3(`Unknown retrieve action: ${action}`);
@@ -3355,6 +3857,7 @@ var init_tools = __esm({
     init_code_tool();
     init_codegraph();
     init_sync_tool();
+    init_render();
     TOOLS = [
       {
         name: "mindgraph_capture",
@@ -3928,10 +4431,16 @@ var init_tools = __esm({
                 "neighborhood",
                 "path",
                 "subgraph",
+                "top_k_paths",
                 "document_index"
               ],
               description: "Retrieval or traversal strategy"
             },
+            format: {
+              type: "string",
+              enum: ["text", "json"],
+              description: "Output format (default 'text'): a compact rendered context block \u2014 labels, uids, summaries, status tags, relationships. Pass 'json' for the raw server response (full props, source-chunk offsets, retrieval metadata)."
+            },
             query: {
               type: "string",
               description: "Search query \u2014 for 'text'/'context': 1-3 BM25 keywords, drop filler words. For 'semantic'/'hybrid': natural language is OK since it uses vector similarity."
@@ -3991,7 +4500,35 @@ var init_tools = __esm({
             },
             include_documents: {
               type: "boolean",
-              description: "Include ingested documents and wiki articles in context results. The coding profile defaults these OFF so engineering questions aren't answered from unrelated ingested content; pass true when the question is about a document, spec, or article."
+              description: "Include ingested documents and wiki articles in context results. The coding profile defaults these OFF so engineering questions aren't answered from unrelated ingested content; pass true when the question is about a document, spec, or article \u2014 or false in any profile to drop the article leg."
+            },
+            article_limit: {
+              type: "number",
+              description: "Max wiki articles in context results (default 3; 0 disables the article leg). An explicit value overrides profile defaults, including the coding profile's articles-off default."
+            },
+            valid_at: {
+              type: "string",
+              description: "ISO-8601 date (e.g. '2021-06') for context: nodes with validity windows are annotated as of this date instead of today"
+            },
+            created_after: {
+              type: "number",
+              description: "Unix seconds \u2014 'recent' action: only nodes ingested after this time"
+            },
+            created_before: {
+              type: "number",
+              description: "Unix seconds \u2014 'recent' action: only nodes ingested before this time"
+            },
+            explain: {
+              type: "boolean",
+              description: "hybrid action: include per-leg retrieval scoring (legs) in the response"
+            },
+            k: {
+              type: "number",
+              description: "top_k_paths action: number of cheapest paths (default 3, cap 25)"
+            },
+            max_cost: {
+              type: "number",
+              description: "top_k_paths action: optional cost ceiling for returned paths"
             },
             include_chunks: {
               type: "boolean",
@@ -4822,7 +5359,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.7.1 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v${"0.16.0"} running on stdio (${BASE_URL})`
   );
 }
 var import_server, import_stdio, import_types, API_KEY, BASE_URL, AGENT_ID, ORG_ID, PROFILE, HARNESS, client, INSTRUCTIONS, server, GOVERNANCE_CONFIG, PROMPTS;
@@ -4833,13 +5370,14 @@ var init_src = __esm({
     import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
     import_types = require("@modelcontextprotocol/sdk/types.js");
     init_dist();
+    init_hook_env();
     init_tools();
     init_generated_tools();
     init_governance();
     init_resources();
     API_KEY = process.env.MINDGRAPH_API_KEY;
     BASE_URL = process.env.MINDGRAPH_BASE_URL || "https://api.mindgraph.cloud";
-    AGENT_ID = process.env.MINDGRAPH_AGENT_ID || "mcp";
+    AGENT_ID = process.env.MINDGRAPH_AGENT_ID || loadHookEnv().agentId || stableAgentId();
     ORG_ID = process.env.MINDGRAPH_ORG_ID;
     PROFILE = process.env.MINDGRAPH_PROFILE || "general";
     HARNESS = process.env.MINDGRAPH_HARNESS || "generic";
@@ -4961,7 +5499,7 @@ Capture knowledge when the user shares something worth remembering:
     server = new import_server.Server(
       {
         name: "mindgraph",
-        version: "0.14.9"
+        version: "0.16.0"
       },
       {
         capabilities: {
@@ -5182,46 +5720,10 @@ ${conversation}`
 var fs5 = __toESM(require("fs"));
 var path5 = __toESM(require("path"));
 var os4 = __toESM(require("os"));
-var crypto4 = __toESM(require("crypto"));
+var crypto5 = __toESM(require("crypto"));
 var import_child_process = require("child_process");
 init_dist();
-
-// src/hook-env.ts
-var import_node_fs = __toESM(require("fs"));
-var import_node_os = __toESM(require("os"));
-var import_node_path = __toESM(require("path"));
-function hookEnvPath(dir) {
-  return import_node_path.default.join(dir || import_node_path.default.join(import_node_os.default.homedir(), ".mindgraph"), "hooks.json");
-}
-function loadHookEnv(dir) {
-  try {
-    const raw = import_node_fs.default.readFileSync(hookEnvPath(dir), "utf8");
-    const parsed = JSON.parse(raw);
-    return {
-      baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : void 0,
-      apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : void 0,
-      agentId: typeof parsed.agentId === "string" ? parsed.agentId : void 0
-    };
-  } catch {
-    return {};
-  }
-}
-function saveHookEnv(env, dir) {
-  const file = hookEnvPath(dir);
-  import_node_fs.default.mkdirSync(import_node_path.default.dirname(file), { recursive: true });
-  const existing = loadHookEnv(dir);
-  const merged = {
-    baseUrl: env.baseUrl ?? existing.baseUrl,
-    apiKey: env.apiKey ?? existing.apiKey,
-    agentId: env.agentId ?? existing.agentId
-  };
-  import_node_fs.default.writeFileSync(file, `${JSON.stringify(merged, null, 2)}
-`, {
-    mode: 384
-  });
-  import_node_fs.default.chmodSync(file, 384);
-  return file;
-}
+init_hook_env();
 
 // src/cli-args.ts
 function parseArgs(argv) {
@@ -5292,12 +5794,14 @@ function classifyMcpAddFailure(e) {
 }
 
 // src/hook-core.ts
-var import_node_crypto2 = __toESM(require("crypto"));
+var import_node_crypto3 = __toESM(require("crypto"));
 var import_node_fs3 = __toESM(require("fs"));
 var import_node_os3 = __toESM(require("os"));
 var import_node_path3 = __toESM(require("path"));
 var import_node_child_process2 = require("child_process");
 init_codegraph();
+init_code_tool();
+init_hook_env();
 var NOOP = { kind: "noop" };
 function defaultLedger(sessionId, options) {
   return {
@@ -5319,7 +5823,7 @@ function runtimeDir(options) {
 }
 function ledgerPath(sessionId, options) {
   const harness = "harness" in options ? options.harness : "claude-code";
-  const key = import_node_crypto2.default.createHash("sha256").update(`${harness}\0${sessionId}`).digest("hex");
+  const key = import_node_crypto3.default.createHash("sha256").update(`${harness}\0${sessionId}`).digest("hex");
   return import_node_path3.default.join(runtimeDir(options), `${key}.json`);
 }
 function waitBriefly(ms) {
@@ -5334,14 +5838,14 @@ function withLedger(sessionId, options, update) {
   }
   const lock = `${file}.lock`;
   let lockFd;
-  for (let attempt = 0; attempt < 50; attempt++) {
+  for (let attempt = 0; attempt < 400; attempt++) {
     try {
       lockFd = import_node_fs3.default.openSync(lock, "wx", 384);
       break;
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
       try {
-        if (Date.now() - import_node_fs3.default.statSync(lock).mtimeMs > 1e4) import_node_fs3.default.unlinkSync(lock);
+        if (Date.now() - import_node_fs3.default.statSync(lock).mtimeMs > 3e3) import_node_fs3.default.unlinkSync(lock);
       } catch {
       }
       waitBriefly(10);
@@ -5361,7 +5865,7 @@ function withLedger(sessionId, options, update) {
     }
     const result = update(ledger);
     ledger.updatedAt = Date.now();
-    const temporary = `${file}.${process.pid}.${import_node_crypto2.default.randomUUID()}.tmp`;
+    const temporary = `${file}.${process.pid}.${import_node_crypto3.default.randomUUID()}.tmp`;
     import_node_fs3.default.writeFileSync(temporary, `${JSON.stringify(ledger)}
 `, { mode: 384 });
     import_node_fs3.default.renameSync(temporary, file);
@@ -5396,17 +5900,13 @@ function worktreeState(cwd) {
   const status = gitValue(cwd, ["status", "--porcelain"]);
   return status === void 0 ? "unknown" : status ? "dirty" : "clean";
 }
-async function invocationContext(input, options) {
-  const repository = await new CodegraphAdapter({
-    cwd: input.cwd,
-    workspaceFile: options.workspaceFile
-  }).resolveRepository();
+function invocationContext(input, options, repoId) {
   return {
     harness: options.harness,
     harnessSessionId: input.session_id,
     harnessTurnId: input.turn_id,
     cwd: input.cwd,
-    repoId: repository.repoId,
+    repoId,
     branch: gitValue(input.cwd, ["branch", "--show-current"]),
     commit: gitValue(input.cwd, ["rev-parse", "HEAD"]),
     worktreeState: worktreeState(input.cwd),
@@ -5414,6 +5914,9 @@ async function invocationContext(input, options) {
     injectedBy: "hook"
   };
 }
+function resolveAgentId(options) {
+  return options.agentId || process.env.MINDGRAPH_AGENT_ID || stableAgentId();
+}
 function object(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
 }
@@ -5441,56 +5944,198 @@ function number(value) {
 function string(value) {
   return typeof value === "string" && value ? value : void 0;
 }
-function boundedBrief(brief) {
-  const encoded = JSON.stringify(brief, null, 2);
-  const capped = encoded.length <= 9e3 ? encoded : `${encoded.slice(0, 8900)}
+var BRIEF_CHAR_BUDGET = 9e3;
+function renderBrief(brief, meta) {
+  let bounded = false;
+  const clipTracked = (value, max) => {
+    const text = string(value);
+    if (!text) return void 0;
+    if (text.length <= max) return text;
+    bounded = true;
+    return `${text.slice(0, max - 1)}\u2026`;
+  };
+  const nodeLine = (value, summaryMax) => {
+    const node = object(value);
+    if (!node) return void 0;
+    const label = clipTracked(node.label, 160) || "(unlabeled)";
+    const summary = clipTracked(node.summary, summaryMax);
+    const uid = string(node.uid);
+    return `- ${label}${uid ? ` [${uid}]` : ""}${summary && summary !== label ? ` \u2014 ${summary}` : ""}`;
+  };
+  const lines = [
+    "MindGraph durable work brief (authoritative across sessions/harnesses):"
+  ];
+  if (meta.scopeNote) lines.push(meta.scopeNote);
+  const task = object(brief?.task);
+  const scopedOut = number(brief?.scoped_out_tasks);
+  if (!task) {
+    lines.push("No durable task is eligible for this session's scope.");
+    if (scopedOut) {
+      lines.push(
+        `${scopedOut} durable task(s) exist outside this repository scope \u2014 resume one explicitly by task_uid if that is intended.`
+      );
+    }
+  } else {
+    const props = object(task.props);
+    const details = [
+      `status ${string(props?.status) || "unknown"}`,
+      string(props?.priority) ? `priority ${string(props?.priority)}` : void 0,
+      number(task.version) !== void 0 ? `v${number(task.version)}` : void 0
+    ].filter(Boolean);
+    lines.push(
+      `Task: ${clipTracked(task.label, 200) || "(unlabeled)"} [${string(task.uid) || "?"}] \u2014 ${details.join(", ")}`
+    );
+    const description = clipTracked(props?.description, 400);
+    if (description) lines.push(`  ${description}`);
+    const reason = string(brief?.selection_reason);
+    if (reason) lines.push(`Selection: ${reason}`);
+    const lease = object(brief?.claim) || object(brief?.lease);
+    if (meta.claimed) {
+      const epoch = number(lease?.lease_epoch);
+      lines.push(
+        `Claimed: yes${epoch !== void 0 ? ` (lease epoch ${epoch})` : ""} \u2014 this session holds the lease.`
+      );
+    } else if (meta.claimFailed) {
+      lines.push(
+        "Claimed: no \u2014 the claim attempt failed (another session may hold the lease). Treat as context; claim_task explicitly before mutating it."
+      );
+    } else {
+      lines.push(
+        "Claimed: no \u2014 backlog context, not owned. claim_task deliberately before starting this work."
+      );
+    }
+    const goal = nodeLine(brief?.goal, 200);
+    if (goal) lines.push(`Goal:
+${goal}`);
+    const steps = Array.isArray(brief?.next_steps) ? brief.next_steps : [];
+    if (steps.length > 5) bounded = true;
+    const stepLines = steps.slice(0, 5).map((step) => nodeLine(step, 160)).filter(Boolean);
+    if (stepLines.length) lines.push(`Next steps:
+${stepLines.join("\n")}`);
+    const blockers = Array.isArray(brief?.blockers) ? brief.blockers : [];
+    if (blockers.length > 5) bounded = true;
+    const blockerLines = blockers.slice(0, 5).map((blocker) => nodeLine(blocker, 200)).filter(Boolean);
+    if (blockerLines.length) lines.push(`Blockers:
+${blockerLines.join("\n")}`);
+    const active = object(brief?.active_execution);
+    if (active) {
+      const iteration = number(active.iteration) ?? number(object(active.props)?.iteration);
+      lines.push(
+        `Active execution: [${string(active.uid) || "?"}] iteration ${iteration ?? "?"} still running from a prior session \u2014 checkpoint or abandon it.`
+      );
+    }
+    const poison = object(brief?.poison_task) || string(brief?.warning);
+    if (poison) {
+      lines.push(
+        `Warning: ${typeof poison === "string" ? clipTracked(poison, 300) : "recent executions of this task repeatedly failed \u2014 investigate before retrying."}`
+      );
+    }
+  }
+  const optional = [];
+  const knowledge = Array.isArray(brief?.knowledge) ? brief.knowledge : [];
+  if (knowledge.length > 5) bounded = true;
+  const knowledgeLines = knowledge.slice(0, 5).map((item) => nodeLine(item, 350)).filter(Boolean);
+  if (knowledgeLines.length) {
+    optional.push(`Relevant knowledge:
+${knowledgeLines.join("\n")}`);
+  }
+  const targets = Array.isArray(brief?.code_targets) ? brief.code_targets : [];
+  const targetLabels = targets.slice(0, 10).map((target) => clipTracked(object(target)?.label, 120)).filter(Boolean);
+  if (targetLabels.length) {
+    const extra = targets.length - targetLabels.length;
+    if (extra > 0) bounded = true;
+    optional.push(
+      `Code targets: ${targetLabels.join(", ")}${extra > 0 ? ` (+${extra} more)` : ""}`
+    );
+  }
+  const footer = task ? "Use the harness todo list only for local execution details; do not duplicate this durable Task there." : void 0;
+  let used = lines.join("\n").length + (footer ? footer.length + 1 : 0);
+  for (const section of optional) {
+    if (used + section.length + 1 > BRIEF_CHAR_BUDGET) {
+      bounded = true;
+      break;
+    }
+    lines.push(section);
+    used += section.length + 1;
+  }
+  if (bounded) {
+    lines.push(
+      "\u2026[bounded work brief truncated \u2014 fetch full node content by uid if needed]"
+    );
+  }
+  if (footer) lines.push(footer);
+  const rendered = lines.join("\n");
+  return rendered.length <= BRIEF_CHAR_BUDGET ? rendered : `${rendered.slice(0, BRIEF_CHAR_BUDGET - 40)}
 \u2026[bounded work brief truncated]`;
-  return [
-    "MindGraph durable work brief (authoritative across sessions/harnesses):",
-    capped,
-    "Use the harness todo list only for local execution details; do not duplicate this durable Task there."
-  ].join("\n");
 }
 async function repositoryScopeUids(input, client2, options, agentId) {
-  if (!client2.entity) return [];
+  if (!client2.entity) return { uids: [], failures: [] };
   const adapter = new CodegraphAdapter({
     cwd: input.cwd,
     workspaceFile: options.workspaceFile
   });
   const configured = await adapter.resolveRepositories();
   const repositories = configured.length > 0 ? configured : [await adapter.resolveRepository()];
+  const failures = [];
   const resolved = await Promise.all(
-    repositories.map(
-      (repository) => client2.entity({
-        action: "resolve_identity",
-        identity: {
-          namespace: "external.code",
-          key_version: 1,
-          key: repositoryIdentityKey(repository)
-        },
-        agent_id: agentId
-      }).catch(() => void 0)
-    )
+    repositories.map(async (repository) => {
+      try {
+        const payload = object(
+          await client2.entity({
+            action: "resolve_identity",
+            identity: {
+              namespace: "external.code",
+              key_version: 1,
+              key: repositoryIdentityKey(repository)
+            },
+            agent_id: agentId
+          })
+        );
+        if (payload?.status === "existing" && string(payload.uid)) {
+          return string(payload.uid);
+        }
+        if (payload?.status === "absent") {
+          const anchored = await anchorRepository(
+            client2,
+            repository,
+            repository.spaceUid ?? `space:agent:${agentId}`,
+            agentId
+          );
+          if (anchored?.uid) return anchored.uid;
+          failures.push(
+            `${repository.repoId}: anchor ${anchored?.status ?? "failed"}`
+          );
+          return void 0;
+        }
+        failures.push(
+          `${repository.repoId}: ${string(payload?.status) || "unresolved"}`
+        );
+        return void 0;
+      } catch (error) {
+        failures.push(
+          `${repository.repoId}: ${error?.message || "resolve failed"}`
+        );
+        return void 0;
+      }
+    })
   );
-  return [
-    ...new Set(
-      resolved.flatMap((response) => {
-        const payload = object(response);
-        return payload?.status === "existing" && string(payload.uid) ? [string(payload.uid)] : [];
-      })
-    )
-  ];
+  return {
+    uids: [...new Set(resolved.filter((uid) => Boolean(uid)))],
+    failures
+  };
 }
-function isOwnPriorWork(brief, agentId) {
+function isOwnPriorWork(brief, agentId, harness) {
   const reason = string(brief?.selection_reason);
   if (reason === "owned_live_lease" || reason === "same_agent_session_rebind") {
     return true;
   }
-  return string(object(brief?.lease)?.lease_owner_agent_id) === agentId;
+  const owner = string(object(brief?.lease)?.lease_owner_agent_id);
+  return owner === agentId || owner === harness;
 }
 async function sessionStart(input, client2, options) {
-  const agentId = options.agentId || process.env.MINDGRAPH_AGENT_ID || options.harness;
+  const agentId = resolveAgentId(options);
   const harnessLabel = options.harness === "claude-code" ? "Claude Code" : "Codex";
+  const nowSeconds = (options.now || (() => Date.now() / 1e3))();
   const opened = object(
     await client2.session({
       action: "open",
@@ -5502,7 +6147,21 @@ async function sessionStart(input, client2, options) {
     })
   );
   const sessionUid = string(opened?.uid);
-  const scopeUids = await repositoryScopeUids(input, client2, options, agentId);
+  const baselineWorktree = worktreeState(input.cwd);
+  if (sessionUid) {
+    withLedger(input.session_id, options, (ledger) => {
+      ledger.sessionUid = sessionUid;
+      ledger.baselineWorktree = baselineWorktree;
+      return void 0;
+    });
+  }
+  const scope = await repositoryScopeUids(input, client2, options, agentId);
+  if (scope.failures.length > 0) {
+    console.error(
+      `mindgraph-hook: ${scope.failures.length} repository scope(s) failed to resolve (${scope.failures.join("; ")}); resume runs ${scope.uids.length > 0 ? "narrowed" : "UNSCOPED"}`
+    );
+  }
+  const scopeUids = scope.uids;
   let brief = object(
     await client2.plan({
       action: "resume_work",
@@ -5513,9 +6172,19 @@ async function sessionStart(input, client2, options) {
   );
   const task = object(brief?.task);
   const lease = object(brief?.lease);
-  if (sessionUid && string(task?.uid) && number(task?.version) && isOwnPriorWork(brief, agentId)) {
+  const prior = readLedger(input.session_id, options);
+  const leaseExpiry = number(lease?.lease_expires_at);
+  const leaseLive = leaseExpiry !== void 0 && leaseExpiry > nowSeconds;
+  const heldByThisSession = leaseLive && prior.taskUid !== void 0 && prior.taskUid === string(task?.uid) && prior.leaseEpoch === number(lease?.lease_epoch);
+  let claimed;
+  let claimFailed = false;
+  if (sessionUid && string(task?.uid) && number(task?.version) && isOwnPriorWork(brief, agentId, options.harness) && // A LIVE lease belongs to whichever session claimed it — claiming from
+  // here would fence that session out mid-work (the released server
+  // rebinds same-owner live leases without allow_takeover). Re-claim live
+  // leases only when this very session already holds them (re-entry).
+  (!leaseLive || heldByThisSession)) {
     try {
-      const claimed = object(
+      claimed = object(
         await client2.plan({
           action: "claim_task",
           task_uid: task.uid,
@@ -5525,35 +6194,63 @@ async function sessionStart(input, client2, options) {
           agent_id: agentId
         })
       );
-      brief = object(
-        await client2.plan({
-          action: "resume_work",
-          task_uid: task.uid,
-          session_uid: sessionUid,
-          ...scopeUids.length > 0 ? { scope_uids: scopeUids } : {},
-          agent_id: agentId
-        })
-      );
-      if (brief && claimed) brief.claim = claimed;
     } catch {
+      claimFailed = true;
+    }
+    if (claimed) {
+      try {
+        const reResumed = object(
+          await client2.plan({
+            action: "resume_work",
+            task_uid: task.uid,
+            session_uid: sessionUid,
+            ...scopeUids.length > 0 ? { scope_uids: scopeUids } : {},
+            agent_id: agentId
+          })
+        );
+        if (reResumed) brief = reResumed;
+      } catch {
+      }
+      if (brief) brief.claim = claimed;
     }
   }
-  const briefText = boundedBrief(brief || { status: "no_eligible_work" });
-  const briefHash = import_node_crypto2.default.createHash("sha256").update(briefText).digest("hex");
+  const stillHeld = !claimed && claimFailed && heldByThisSession;
+  const scopeNote = scope.failures.length > 0 ? `Scope: ${scopeUids.length} repositories resolved, ${scope.failures.length} FAILED \u2014 durable-work selection ran ${scopeUids.length > 0 ? "narrowed" : "unscoped"}; tasks in the failed repositories may be missing.` : void 0;
+  const briefText = renderBrief(brief || { status: "no_eligible_work" }, {
+    claimed: Boolean(claimed) || stillHeld,
+    claimFailed: claimFailed && !stillHeld,
+    scopeNote
+  });
+  const briefHash = import_node_crypto3.default.createHash("sha256").update(briefText).digest("hex");
   const shouldInject = withLedger(input.session_id, options, (ledger) => {
     const changed = ledger.lastBriefHash !== briefHash;
     const reinjectCompact = options.reinjectUnchangedCompact && input.source === "compact";
     ledger.sessionUid = sessionUid;
-    ledger.baselineWorktree = worktreeState(input.cwd);
-    const selectedTask = object(brief?.task);
-    const selectedLease = object(brief?.lease) || object(brief?.claim);
-    const executions = Array.isArray(brief?.recent_executions) ? brief?.recent_executions : [];
-    const latest = object(executions[0]);
-    ledger.taskUid = string(selectedTask?.uid);
-    ledger.taskVersion = number(selectedTask?.version);
-    ledger.leaseEpoch = number(selectedLease?.lease_epoch);
-    ledger.leaseExpiresAt = number(selectedLease?.lease_expires_at);
-    ledger.executionUid = string(object(brief?.active_execution)?.uid) || string(latest?.uid);
+    ledger.baselineWorktree = baselineWorktree;
+    if (claimed) {
+      const claimLease = object(brief?.claim) || object(brief?.lease);
+      const selectedTask = object(brief?.task);
+      ledger.taskUid = string(selectedTask?.uid);
+      ledger.taskVersion = number(claimed.task_version) ?? number(selectedTask?.version) ?? void 0;
+      ledger.leaseEpoch = number(claimLease?.lease_epoch);
+      ledger.leaseExpiresAt = number(claimLease?.lease_expires_at);
+      ledger.lastLeaseRenewalAt = nowSeconds;
+      const running = [
+        object(brief?.active_execution),
+        ...Array.isArray(brief?.recent_executions) ? brief.recent_executions.map(object) : []
+      ].find(
+        (execution) => execution && (string(object(execution.props)?.status) ?? string(execution.status)) === "running"
+      );
+      ledger.executionUid = running ? string(running.uid) : void 0;
+    } else if (claimFailed && ledger.taskUid !== void 0 && ledger.taskUid === string(object(brief?.task)?.uid) && ledger.lastLeaseRenewalAt !== void 0) {
+    } else {
+      ledger.taskUid = void 0;
+      ledger.taskVersion = void 0;
+      ledger.leaseEpoch = void 0;
+      ledger.leaseExpiresAt = void 0;
+      ledger.executionUid = void 0;
+      ledger.lastLeaseRenewalAt = void 0;
+    }
     ledger.lastBriefHash = briefHash;
     return changed || reinjectCompact;
   });
@@ -5562,82 +6259,173 @@ async function sessionStart(input, client2, options) {
 async function preTool(input, options) {
   const original = { ...input.tool_input || {} };
   const ledger = readLedger(input.session_id, options);
+  let repoId = ledger.repoContextCwd === input.cwd && ledger.repoContextAt !== void 0 && Date.now() - ledger.repoContextAt < 3e5 ? ledger.repoContextRepoId : void 0;
+  if (!repoId) {
+    repoId = (await new CodegraphAdapter({
+      cwd: input.cwd,
+      workspaceFile: options.workspaceFile
+    }).resolveRepository()).repoId;
+    withLedger(input.session_id, options, (fresh) => {
+      fresh.repoContextCwd = input.cwd;
+      fresh.repoContextRepoId = repoId;
+      fresh.repoContextAt = Date.now();
+      return void 0;
+    });
+  }
   const updatedInput = {
     ...original,
-    invocation_context: await invocationContext(input, options)
+    invocation_context: invocationContext(input, options, repoId)
   };
   if (ledger.sessionUid) updatedInput.session_uid = ledger.sessionUid;
   if (ledger.taskUid && updatedInput.task_uid === void 0) {
     updatedInput.task_uid = ledger.taskUid;
   }
-  if (ledger.taskUid && input.tool_name?.includes("mindgraph_capture") && updatedInput.work_uid === void 0) {
+  const modelTask = string(original.task_uid);
+  const targetsLedgerTask = ledger.taskUid !== void 0 && (modelTask === void 0 || modelTask === ledger.taskUid);
+  const isCapture = Boolean(input.tool_name?.includes("mindgraph_capture"));
+  const fencedAction = Boolean(input.tool_name?.includes("mindgraph_plan")) && FENCED_PLAN_ACTIONS.has(string(original.action) || "");
+  if (ledger.taskUid && isCapture && updatedInput.work_uid === void 0) {
     updatedInput.work_uid = ledger.taskUid;
   }
-  if (ledger.executionUid && updatedInput.execution_uid === void 0) {
+  if (targetsLedgerTask && (fencedAction || isCapture) && ledger.executionUid && updatedInput.execution_uid === void 0) {
     updatedInput.execution_uid = ledger.executionUid;
   }
-  if (ledger.leaseEpoch !== void 0 && updatedInput.lease_epoch === void 0) {
+  if (targetsLedgerTask && fencedAction && ledger.leaseEpoch !== void 0 && updatedInput.lease_epoch === void 0) {
     updatedInput.lease_epoch = ledger.leaseEpoch;
   }
-  if (ledger.taskVersion !== void 0 && updatedInput.expected_version === void 0) {
+  if (targetsLedgerTask && fencedAction && ledger.taskVersion !== void 0 && updatedInput.expected_version === void 0) {
     updatedInput.expected_version = ledger.taskVersion;
   }
   return { kind: "rewrite", updatedInput };
 }
+var FENCED_PLAN_ACTIONS = /* @__PURE__ */ new Set([
+  "claim_task",
+  "heartbeat",
+  "start_iteration",
+  "checkpoint_iteration",
+  "block_task",
+  "complete_task",
+  "abandon_iteration"
+]);
 async function postTool(input, client2, options) {
   const name = input.tool_name || "";
   const args = input.tool_input || {};
   const action = string(args.action);
   const payload = responsePayload(input.tool_response);
   const nowSeconds = (options.now || (() => Date.now() / 1e3))();
-  let heartbeat;
+  let renewal;
   withLedger(input.session_id, options, (ledger) => {
     ledger.materialToolCalls += 1;
-    if (["Edit", "Write", "NotebookEdit", "apply_patch"].includes(name) || name === "Bash" && action !== "read") {
+    if (["Edit", "Write", "NotebookEdit", "apply_patch"].includes(name)) {
       ledger.mutatingOperations += 1;
     }
-    if (name.includes("mindgraph_capture") && !payload?.error) {
-      ledger.memoryWritten = true;
+    if (!payload?.error) {
+      if (name.includes("mindgraph_capture") && ["lesson", "journal"].includes(action || "") || name.includes("mindgraph_commit") && action === "resolve_decision" || name.includes("mindgraph_plan") && action === "assess_risk") {
+        ledger.memoryWritten = true;
+      }
     }
     if (name.includes("mindgraph_plan")) {
-      if (action === "start_iteration" && !payload?.error) {
-        ledger.executionUid = string(payload?.execution_uid) || ledger.executionUid;
-      }
-      if (["checkpoint_iteration", "block_task", "complete_task", "abandon_iteration"].includes(
-        action || ""
-      ) && !payload?.error) {
-        ledger.iterationCheckpointed = true;
-        if (action !== "block_task") ledger.executionUid = void 0;
-      }
-      ledger.taskVersion = number(payload?.task_version) || number(payload?.version) || ledger.taskVersion;
-      ledger.leaseEpoch = number(payload?.lease_epoch) || ledger.leaseEpoch;
-      ledger.leaseExpiresAt = number(payload?.lease_expires_at) || ledger.leaseExpiresAt;
+      const targetTask = string(args.task_uid) || ledger.taskUid;
+      const aboutLedgerTask = targetTask !== void 0 && targetTask === ledger.taskUid;
+      if (!payload?.error) {
+        if (action === "claim_task" && targetTask) {
+          const rebindToOther = targetTask !== ledger.taskUid;
+          ledger.taskUid = targetTask;
+          ledger.taskVersion = number(payload?.task_version) ?? number(payload?.version) ?? (rebindToOther ? void 0 : ledger.taskVersion);
+          ledger.leaseEpoch = number(payload?.lease_epoch) ?? (rebindToOther ? void 0 : ledger.leaseEpoch);
+          ledger.leaseExpiresAt = number(payload?.lease_expires_at) ?? (rebindToOther ? void 0 : ledger.leaseExpiresAt);
+          if (rebindToOther) ledger.executionUid = void 0;
+          ledger.lastLeaseRenewalAt = nowSeconds;
+        }
+        if (action === "start_iteration") {
+          ledger.executionUid = string(payload?.execution_uid) || ledger.executionUid;
+        }
+        if (["checkpoint_iteration", "block_task", "complete_task", "abandon_iteration"].includes(
+          action || ""
+        )) {
+          ledger.iterationCheckpointed = true;
+          if (action !== "block_task") ledger.executionUid = void 0;
+        }
+        if (action === "complete_task" && aboutLedgerTask) {
+          ledger.taskUid = void 0;
+          ledger.taskVersion = void 0;
+          ledger.leaseEpoch = void 0;
+          ledger.leaseExpiresAt = void 0;
+          ledger.lastLeaseRenewalAt = void 0;
+        } else if (aboutLedgerTask && action !== "claim_task") {
+          ledger.taskVersion = number(payload?.task_version) ?? (string(payload?.uid) === ledger.taskUid ? number(payload?.version) : void 0) ?? ledger.taskVersion;
+          ledger.leaseEpoch = number(payload?.lease_epoch) ?? ledger.leaseEpoch;
+          if (number(payload?.lease_expires_at) !== void 0) {
+            ledger.leaseExpiresAt = number(payload?.lease_expires_at);
+            ledger.lastLeaseRenewalAt = nowSeconds;
+          }
+        }
+      } else if (aboutLedgerTask) {
+        ledger.taskVersion = number(payload?.current_version) ?? ledger.taskVersion;
+        ledger.leaseEpoch = number(payload?.current_epoch) ?? ledger.leaseEpoch;
+        ledger.leaseExpiresAt = number(payload?.lease_expires_at) ?? ledger.leaseExpiresAt;
+      }
     }
-    if (ledger.taskUid && ledger.sessionUid && ledger.taskVersion !== void 0 && ledger.leaseEpoch !== void 0 && ledger.leaseExpiresAt !== void 0 && ledger.leaseExpiresAt - nowSeconds <= 60) {
-      heartbeat = {
-        taskUid: ledger.taskUid,
-        sessionUid: ledger.sessionUid,
-        taskVersion: ledger.taskVersion,
-        leaseEpoch: ledger.leaseEpoch
-      };
+    if (ledger.taskUid && ledger.sessionUid && ledger.taskVersion !== void 0 && ledger.leaseEpoch !== void 0 && ledger.leaseExpiresAt !== void 0 && // Only ledgers whose lease state was written by a claim THIS code made
+    // may renew: 0.14.9 ledgers carry adopted-but-never-claimed fence
+    // state, and a lapse-reclaim from one would auto-seize a task this
+    // session never owned — the incident class all of this exists to kill.
+    ledger.lastLeaseRenewalAt !== void 0) {
+      const expiresIn = ledger.leaseExpiresAt - nowSeconds;
+      const sinceRenewal = nowSeconds - ledger.lastLeaseRenewalAt;
+      if (expiresIn <= 0) {
+        renewal = {
+          kind: "reclaim",
+          taskUid: ledger.taskUid,
+          sessionUid: ledger.sessionUid,
+          taskVersion: ledger.taskVersion,
+          leaseEpoch: ledger.leaseEpoch
+        };
+      } else if (expiresIn <= 60 || sinceRenewal >= 180) {
+        renewal = {
+          kind: "heartbeat",
+          taskUid: ledger.taskUid,
+          sessionUid: ledger.sessionUid,
+          taskVersion: ledger.taskVersion,
+          leaseEpoch: ledger.leaseEpoch
+        };
+      }
     }
     return void 0;
   });
-  if (heartbeat) {
+  if (renewal) {
+    const active = renewal;
     try {
       const response = object(
-        await client2.plan({
+        active.kind === "reclaim" ? (
+          // The lease already lapsed: a heartbeat can only 409. Re-claim
+          // rebinds the same owner's expired lease (bumping the epoch) so
+          // durable tracking survives a >TTL quiet stretch mid-session.
+          await client2.plan({
+            action: "claim_task",
+            task_uid: active.taskUid,
+            session_uid: active.sessionUid,
+            expected_version: active.taskVersion,
+            idempotency_key: `hook-reclaim:${input.session_id}:${active.taskUid}:${active.leaseEpoch}:${Math.floor(nowSeconds / 60)}`,
+            agent_id: resolveAgentId(options)
+          })
+        ) : await client2.plan({
           action: "heartbeat",
-          task_uid: heartbeat.taskUid,
-          session_uid: heartbeat.sessionUid,
-          expected_version: heartbeat.taskVersion,
-          lease_epoch: heartbeat.leaseEpoch,
-          idempotency_key: `hook-heartbeat:${input.session_id}:${heartbeat.taskUid}:${Math.floor(nowSeconds / 60)}`,
-          agent_id: options.agentId || options.harness
+          task_uid: active.taskUid,
+          session_uid: active.sessionUid,
+          expected_version: active.taskVersion,
+          lease_epoch: active.leaseEpoch,
+          idempotency_key: `hook-heartbeat:${input.session_id}:${active.taskUid}:${active.leaseEpoch}:${active.taskVersion}:${Math.floor(nowSeconds / 60)}`,
+          agent_id: resolveAgentId(options)
         })
       );
       withLedger(input.session_id, options, (ledger) => {
-        ledger.leaseExpiresAt = number(response?.lease_expires_at) || ledger.leaseExpiresAt;
+        if (payloadIsError(response)) return void 0;
+        if (ledger.taskUid !== active.taskUid) return void 0;
+        ledger.taskVersion = number(response?.task_version) ?? ledger.taskVersion;
+        ledger.leaseEpoch = number(response?.lease_epoch) ?? ledger.leaseEpoch;
+        ledger.leaseExpiresAt = number(response?.lease_expires_at) ?? ledger.leaseExpiresAt;
+        ledger.lastLeaseRenewalAt = nowSeconds;
         return void 0;
       });
     } catch {
@@ -5645,6 +6433,9 @@ async function postTool(input, client2, options) {
   }
   return NOOP;
 }
+function payloadIsError(payload) {
+  return Boolean(payload && payload.error);
+}
 function stop(input, options) {
   if (input.stop_hook_active) return NOOP;
   return withLedger(input.session_id, options, (ledger) => {
@@ -5675,17 +6466,20 @@ async function sessionEnd(input, client2, options) {
         release_lease: true,
         summary: `${harnessLabel} SessionEnd: ${input.reason || "interrupted"}`,
         idempotency_key: `session-end:${input.session_id}:${ledger.executionUid}`,
-        agent_id: options.agentId || options.harness
+        agent_id: resolveAgentId(options)
       });
     } catch {
     }
   }
-  if (ledger.sessionUid) {
+  const abandonRan = Boolean(
+    ledger.executionUid && ledger.taskUid && ledger.sessionUid && ledger.taskVersion !== void 0 && ledger.leaseEpoch !== void 0
+  );
+  if (ledger.sessionUid && (options.harness !== "codex" || !abandonRan)) {
     try {
       await client2.session({
         action: "close",
         session_uid: ledger.sessionUid,
-        agent_id: options.agentId || options.harness
+        agent_id: resolveAgentId(options)
       });
     } catch {
     }
@@ -5795,7 +6589,7 @@ async function runCodexHook(input, client2, options = {}) {
 var import_node_fs4 = __toESM(require("fs"));
 var import_node_os4 = __toESM(require("os"));
 var import_node_path4 = __toESM(require("path"));
-var import_node_crypto3 = __toESM(require("crypto"));
+var import_node_crypto4 = __toESM(require("crypto"));
 var OWNER_MARKER = "--owner mindgraph";
 var RUNNER_RELATIVE = ".mindgraph/bin/mindgraph-hook.cjs";
 function command(harness) {
@@ -5839,11 +6633,14 @@ function desiredEntries(harness) {
         // inherited 20s edge in both harnesses: the hooks correctly failed
         // open, but no brief reached the model. The same installed runner
         // completed in 16.84s once warm. Keep a 30s cold-tenant margin.
+        // The declared Codex context limit must not undercut the brief's own
+        // 9,000-char budget: at 3,000 the harness applied a SECOND, tighter
+        // truncation the renderer knew nothing about.
         hooks: [
           ownedHook(
             harness,
             30,
-            harness === "codex" ? 3e3 : void 0
+            harness === "codex" ? 1e4 : void 0
           )
         ]
       }
@@ -5851,13 +6648,23 @@ function desiredEntries(harness) {
     PreToolUse: [
       {
         matcher: "mcp__mindgraph__.*",
-        hooks: [ownedHook(harness, 3)]
+        // Repository resolution over a large multi-repo workspace plus three
+        // git probes can exceed 3s on the first (uncached) call; a killed
+        // PreToolUse means the call goes through untagged.
+        hooks: [ownedHook(harness, 5)]
       }
     ],
-    PostToolUse: [{ matcher: ".*", hooks: [ownedHook(harness, 5)] }],
+    // PostToolUse awaits the lease renewal round-trip, which fires exactly
+    // when the tenant is cold (post-idle reclaim) — 5s killed it mid-claim.
+    PostToolUse: [{ matcher: ".*", hooks: [ownedHook(harness, 10)] }],
     Stop: [{ hooks: [ownedHook(harness, 5)] }],
+    // SessionEnd makes up to two sequential cloud calls (abandon_iteration +
+    // session close) — the SAME cold-tenant latency SessionStart needs 30s
+    // for. Claude honors the configured budget; Codex clamps SessionEnd to a
+    // 3s platform cap regardless of this value (see codex-hooks.ts wire
+    // map), so the codex adapter instead makes at most ONE call there.
     SessionEnd: [
-      { hooks: [ownedHook(harness, harness === "codex" ? 3 : 8)] }
+      { hooks: [ownedHook(harness, harness === "codex" ? 3 : 30)] }
     ]
   };
   return harness === "claude-code" ? {
@@ -5878,7 +6685,7 @@ function entryHasOwnedHook(value) {
 }
 function writeSettings(file, settings) {
   import_node_fs4.default.mkdirSync(import_node_path4.default.dirname(file), { recursive: true });
-  const temporary = `${file}.${process.pid}.${import_node_crypto3.default.randomUUID()}.tmp`;
+  const temporary = `${file}.${process.pid}.${import_node_crypto4.default.randomUUID()}.tmp`;
   import_node_fs4.default.writeFileSync(temporary, `${JSON.stringify(settings, null, 2)}
 `, {
     mode: 384
@@ -5956,6 +6763,52 @@ function uninstallCodexHooks(scope, projectDir = process.cwd(), codexHomeDir) {
 }
 
 // src/cli.ts
+function recordHookHealth(harness, error) {
+  try {
+    const dir = process.env.MINDGRAPH_RUNTIME_DIR || path5.join(os4.homedir(), ".mindgraph", "runtime");
+    fs5.mkdirSync(dir, { recursive: true, mode: 448 });
+    const file = path5.join(dir, "hook-health.json");
+    let failures = 0;
+    try {
+      failures = Number(JSON.parse(fs5.readFileSync(file, "utf8")).consecutiveFailures) || 0;
+    } catch {
+    }
+    fs5.writeFileSync(
+      file,
+      `${JSON.stringify({
+        harness,
+        lastError: error.slice(0, 500),
+        lastFailureAt: (/* @__PURE__ */ new Date()).toISOString(),
+        consecutiveFailures: failures + 1
+      })}
+`,
+      { mode: 384 }
+    );
+  } catch {
+  }
+}
+function clearHookHealth(harness) {
+  try {
+    const file = path5.join(
+      process.env.MINDGRAPH_RUNTIME_DIR || path5.join(os4.homedir(), ".mindgraph", "runtime"),
+      "hook-health.json"
+    );
+    if (!fs5.existsSync(file)) return;
+    const current = JSON.parse(fs5.readFileSync(file, "utf8"));
+    if (!Number(current.consecutiveFailures)) return;
+    fs5.writeFileSync(
+      file,
+      `${JSON.stringify({
+        harness,
+        lastOkAt: (/* @__PURE__ */ new Date()).toISOString(),
+        consecutiveFailures: 0
+      })}
+`,
+      { mode: 384 }
+    );
+  } catch {
+  }
+}
 function getClaudeDesktopConfigPath() {
   switch (process.platform) {
     case "darwin":
@@ -6031,7 +6884,10 @@ function installClaudeCode(apiKey, baseUrl, agentId) {
     "--env",
     "MINDGRAPH_HARNESS=claude-code",
     "--env",
-    `MINDGRAPH_AGENT_ID=${agentId || "claude-code"}`
+    // The registration, the hooks, and the serve path must all resolve the
+    // SAME identity — a differing default here made the model's fenced tool
+    // calls and the hook's lease two different agents on the server.
+    `MINDGRAPH_AGENT_ID=${agentId || process.env.MINDGRAPH_AGENT_ID || loadHookEnv().agentId || stableAgentId()}`
   ];
   if (baseUrl) {
     envArgs.push("--env", `MINDGRAPH_BASE_URL=${baseUrl}`);
@@ -6121,6 +6977,23 @@ function printStatus() {
   console.log(
     `MINDGRAPH_BASE_URL: ${process.env.MINDGRAPH_BASE_URL || "https://api.mindgraph.cloud (default)"}`
   );
+  try {
+    const healthFile = path5.join(
+      process.env.MINDGRAPH_RUNTIME_DIR || path5.join(os4.homedir(), ".mindgraph", "runtime"),
+      "hook-health.json"
+    );
+    if (fs5.existsSync(healthFile)) {
+      const health = JSON.parse(fs5.readFileSync(healthFile, "utf8"));
+      const failures = Number(health.consecutiveFailures) || 0;
+      console.log(
+        failures > 0 ? `Hooks: FAILING (${failures} consecutive; last: ${health.lastError} at ${health.lastFailureAt})` : `Hooks: healthy (last recovery ${health.lastOkAt || "unknown"})`
+      );
+    } else {
+      console.log("Hooks: no health marker (no hook failures recorded)");
+    }
+  } catch {
+    console.log("Hooks: health marker unreadable");
+  }
 }
 function withHooksFlag() {
   return process.argv.includes("--hooks");
@@ -6133,7 +7006,16 @@ function finishCodeInstall(apiKey, baseUrl, withHooks, agentId) {
     console.log(
       `Installed ${result.added} and refreshed ${result.updated} MindGraph Claude Code hook entries in ${result.path}`
     );
-    const envPath = saveHookEnv({ apiKey, baseUrl, agentId });
+    const envPath = saveHookEnv({
+      apiKey,
+      baseUrl,
+      // Default the stable per-user identity only when nothing is stored —
+      // an explicit or previously persisted agentId must survive reinstalls.
+      agentId: agentId || process.env.MINDGRAPH_AGENT_ID || loadHookEnv().agentId || stableAgentId(),
+      // The org pin follows the install environment exactly: installing
+      // without MINDGRAPH_ORG_ID clears any stale pin (null = clear).
+      orgId: process.env.MINDGRAPH_ORG_ID ?? null
+    });
     console.log(`Saved hook connection settings to ${envPath} (mode 600)`);
   } else {
     console.log(
@@ -6192,7 +7074,7 @@ var DASHBOARD_URL = process.env.MINDGRAPH_DASHBOARD_URL || "https://mindgraph.cl
 var POLL_INTERVAL = 2e3;
 var POLL_TIMEOUT = 10 * 60 * 1e3;
 function generateCode() {
-  return crypto4.randomBytes(32).toString("hex");
+  return crypto5.randomBytes(32).toString("hex");
 }
 function openBrowser(url) {
   try {
@@ -6355,10 +7237,19 @@ async function main2() {
         `Installed ${result.added} and refreshed ${result.updated} MindGraph ${hookHarness === "codex" ? "Codex" : "Claude Code"} hook entries in ${result.path}`
       );
       printCodegraphStatus();
-      if (apiKey || baseUrl || agentId) {
-        const envPath = saveHookEnv({ apiKey, baseUrl, agentId });
-        console.log(`Saved hook connection settings to ${envPath} (mode 600)`);
-      } else {
+      const envPath = saveHookEnv({
+        apiKey,
+        baseUrl,
+        // Default the stable per-user identity only when nothing is stored —
+        // an explicit or previously persisted agentId must survive
+        // reinstalls.
+        agentId: agentId || process.env.MINDGRAPH_AGENT_ID || loadHookEnv().agentId || stableAgentId(),
+        // The org pin follows the install environment exactly: installing
+        // without MINDGRAPH_ORG_ID clears any stale pin (null = clear).
+        orgId: process.env.MINDGRAPH_ORG_ID ?? null
+      });
+      console.log(`Saved hook connection settings to ${envPath} (mode 600)`);
+      if (!apiKey && !baseUrl) {
         console.log(
           "Note: hooks resolve MINDGRAPH_API_KEY/MINDGRAPH_BASE_URL from the environment or ~/.mindgraph/hooks.json \u2014 pass --api-key/--base-url to persist them now."
         );
@@ -6385,6 +7276,7 @@ async function main2() {
       const hookApiKey = apiKey ?? stored.apiKey;
       const hookBaseUrl = baseUrl ?? stored.baseUrl;
       if (!hookApiKey) {
+        recordHookHealth(hookHarness, "no-api-key");
         process.stdout.write("{}\n");
         break;
       }
@@ -6393,12 +7285,19 @@ async function main2() {
         const client2 = new MindGraph({
           baseUrl: hookBaseUrl || "https://api.mindgraph.cloud",
           apiKey: hookApiKey,
-          orgId: process.env.MINDGRAPH_ORG_ID,
+          // Hooks run with the harness's environment, which usually lacks
+          // MINDGRAPH_ORG_ID even when the MCP registration pins it — on a
+          // multi-org key the hooks would otherwise track work in the key's
+          // DEFAULT org while the MCP tools write to the pinned one.
+          orgId: process.env.MINDGRAPH_ORG_ID || stored.orgId,
           maxRetries: 0,
           telemetrySurface: "mcp"
         });
         const hookOptions = {
-          agentId: process.env.MINDGRAPH_AGENT_ID || stored.agentId || hookHarness
+          // No harness-name fallback here: hook-core derives a stable
+          // per-user default shared by both harnesses, which is what lets a
+          // task claimed under Codex rebind under Claude Code.
+          agentId: process.env.MINDGRAPH_AGENT_ID || stored.agentId
         };
         const output = hookHarness === "codex" ? await runCodexHook(
           input,
@@ -6411,7 +7310,15 @@ async function main2() {
         );
         process.stdout.write(`${JSON.stringify(output)}
 `);
-      } catch {
+        clearHookHealth(hookHarness);
+      } catch (error) {
+        recordHookHealth(
+          hookHarness,
+          error?.message || "hook failed"
+        );
+        console.error(
+          `mindgraph-hook: failing open (${error?.message || "unknown error"})`
+        );
         process.stdout.write("{}\n");
       }
       break;