knit-mcp 0.11.2 → 0.11.4

package/README.md

@@ -3,7 +3,7 @@
   <a href="https://github.com/PDgit12/knit/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/PDgit12/knit/ci.yml?style=for-the-badge&label=CI&color=10b981" alt="CI" /></a>
   <img src="https://img.shields.io/badge/license-MIT-3b82f6?style=for-the-badge" alt="license" />
   <img src="https://img.shields.io/badge/node-%E2%89%A518-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="node" />
-  <img src="https://img.shields.io/badge/tests-664%20passing-22c55e?style=for-the-badge" alt="tests" />
+  <img src="https://img.shields.io/badge/tests-665%20passing-22c55e?style=for-the-badge" alt="tests" />
   <img src="https://img.shields.io/badge/MCP%20tools-53-7c3aed?style=for-the-badge" alt="tools" />
 </p>
 
@@ -452,6 +452,8 @@ LongMemEval-S R@5/R@10 + LOCOMO LLM-as-Judge runs are on the roadmap (v0.13+). U
 
 | Version | Headline |
 |---|---|
+| **v0.11.4** | Dogfood audit · ran a full audit of Knit's own codebase using its own `knit_spawn_team_worktree` primitive (4 parallel teams: Core Logic, Infrastructure, UI, Quality Assurance). Fixes: HIGH `engram refresh` no longer clobbers user-curated CLAUDE.md (now uses `spliceKnitBlock` like `cache.ts`); `saveSource`/`loadSource` validate `sourceId`; `appendGlobalLearning` propagates write failures; `redactSecrets` applied to `label`/`tags`/`domains` across all persistence boundaries; 100KB response ceiling on `knit_generate_test_cases`; full v0.11 tool surface now documented in `workflow-protocol.ts` generator (was frozen at the v0.4 surface). Plus: 16 key tools reclassified with `[PROTOCOL]`/`[REVIEW]`/`[MEMORY]`/`[GRAPH]` prefixes so the LLM picks the right tool reliably. 53 tools, 687 tests. |
+| **v0.11.3** | Propagation patch · `update_available` flag now surfaces in `knit_load_session` response (≈100% session reach vs. brain_status' low reach) + startup stderr nag on stale versions. Helps FUTURE upgrades land faster; doesn't retroactively reach v0.10.x users. 53 tools, 665 tests. |
 | **v0.11.2** | Pre-publish polish · chunk cap (2000) + `errorResponse` envelope across handlers + CLAUDE.md generator surfaces v0.11 tools · new `engram doctor` install health-check CLI · upgrade-path smoke test caught + fixed a data-loss bug in cache.ts (Case B was wiping user permissions on upgrade) · 11 real exploit-payload integration tests prove C1/C2/H1 fixes hold · `npm run bench` ships a synthetic retrieval harness (50 Q&A) measuring 86% top-1 / 96% R@5. 53 tools, 664 tests. |
 | **v0.11.1** | Audit-driven hardening · 3 CRITICAL (source_id path traversal, post-edit tsc shell injection, live calibration bug) + 10 HIGH fixes from a 5-agent audit, implemented in 3 parallel `knit_spawn_team_worktree` teams. HOOKS_VERSION 11 (auto-upgrades existing users). New `knit_delete_requirements` tool. Honest comparison vs mem0/Letta added. 53 tools, 636 tests. |
 | **v0.11.0** | Verify Layer + auto-config foundation · mandatory `knit_verify_claim` REVIEW gate · post-edit diff verify + universal `tsc` check · drift detector · self-healing classifier (per-project calibration) · `knit_index_requirements` + `knit_generate_test_cases` (BM25 over long specs) · `knit_get_fingerprint` + `knit_infer_domains` + `knit_compose_template` (zero-config CLAUDE.md). 52 tools, 625 tests. |

package/dist/{cache-3LPETDUT.js → cache-7HSMIYDJ.js}

@@ -2,15 +2,16 @@ import {
   detectProjectRoot,
   getBrain,
   refreshBrain
-} from "./chunk-TWHNYJAJ.js";
+} from "./chunk-I63UMEBF.js";
 import "./chunk-HROSQ5MS.js";
-import "./chunk-RZOVZYTF.js";
+import "./chunk-GATMQQK5.js";
+import "./chunk-WKQHCLLO.js";
 import "./chunk-MOOVNMIN.js";
 import "./chunk-ST4X7LZT.js";
 import "./chunk-M3YZOJNW.js";
+import "./chunk-POXT5OYN.js";
 import "./chunk-VB2TIR6L.js";
 import "./chunk-7UFS67HP.js";
-import "./chunk-WKQHCLLO.js";
 import "./chunk-27TA2ZQZ.js";
 export {
   detectProjectRoot,

package/dist/{chunk-RZOVZYTF.js → chunk-GATMQQK5.js}

@@ -62,7 +62,7 @@ async function fetchAgent(name, opts = {}) {
     throw new AgentFetchError(`Unknown agent: "${name}". Not in engram's registry.`);
   }
   const cachePath = agentsCacheFile(ref, cat, bare);
-  if (existsSync(cachePath)) {
+  if (!opts.refresh && existsSync(cachePath)) {
     return readFileSync(cachePath, "utf-8");
   }
   if (process.env.KNIT_OFFLINE === "1" || process.env.ENGRAM_OFFLINE === "1") {
@@ -250,7 +250,7 @@ async function installAgentsForProject(rootPath, config, knowledge, knowledgeBas
       }
     }
     try {
-      const baseMd = await fetchAgent(name, opts.refresh ? { ref: void 0 } : {});
+      const baseMd = await fetchAgent(name, opts.refresh ? { ref: void 0, refresh: true } : {});
       const relevant = knowledgeBase ? selectRelevantLearnings(knowledgeBase.entries, name) : [];
       const personalized = personalizeAgent(baseMd, {
         config,
@@ -285,55 +285,6 @@ function agentsNeededByProject(config) {
   return Array.from(names);
 }
 
-// src/mcp/update-check.ts
-var REGISTRY_DIST_TAGS_URL = "https://registry.npmjs.org/-/package/knit-mcp/dist-tags";
-var FETCH_TIMEOUT_MS = 2e3;
-var CACHE_TTL_MS = 60 * 60 * 1e3;
-var cachedLatest = null;
-var lastCheckedAt = 0;
-var inFlight = null;
-function getCachedLatestVersion() {
-  if (Date.now() - lastCheckedAt > CACHE_TTL_MS) {
-    prewarmLatestVersion();
-  }
-  return cachedLatest;
-}
-function prewarmLatestVersion() {
-  if (inFlight) return;
-  if (Date.now() - lastCheckedAt < CACHE_TTL_MS && cachedLatest !== null) return;
-  inFlight = doFetch().finally(() => {
-    inFlight = null;
-  });
-}
-async function doFetch() {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-  try {
-    const res = await fetch(REGISTRY_DIST_TAGS_URL, { signal: controller.signal });
-    if (!res.ok) return;
-    const data = await res.json();
-    if (typeof data.latest === "string" && data.latest.length > 0) {
-      cachedLatest = data.latest;
-      lastCheckedAt = Date.now();
-    }
-  } catch {
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-function isNewerVersion(latest, current) {
-  const parse = (v) => {
-    const stripped = v.replace(/[-+].*$/, "");
-    const parts = stripped.split(".").map((n) => parseInt(n, 10) || 0);
-    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
-  };
-  const [a1, a2, a3] = parse(latest);
-  const [b1, b2, b3] = parse(current);
-  if (a1 !== b1) return a1 > b1;
-  if (a2 !== b2) return a2 > b2;
-  return a3 > b3;
-}
-
 // src/engine/sessions.ts
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, appendFileSync, readFileSync as readFileSync3, statSync, writeFileSync as writeFileSync3, renameSync } from "fs";
 import { dirname as dirname2 } from "path";
@@ -466,9 +417,6 @@ function parseLine(line) {
 
 export {
   installAgentsForProject,
-  getCachedLatestVersion,
-  prewarmLatestVersion,
-  isNewerVersion,
   appendSession,
   searchSessions,
   getRecentSessions,

package/dist/{chunk-TWHNYJAJ.js → chunk-I63UMEBF.js}

@@ -4,9 +4,13 @@ import {
 } from "./chunk-HROSQ5MS.js";
 import {
   installAgentsForProject,
-  prewarmLatestVersion,
   pruneSessionsByAge
-} from "./chunk-RZOVZYTF.js";
+} from "./chunk-GATMQQK5.js";
+import {
+  importFromMarkdown,
+  loadKnowledgeBaseSafe,
+  saveKnowledgeBase
+} from "./chunk-WKQHCLLO.js";
 import {
   buildKnowledge,
   buildReverseDependencies
@@ -17,6 +21,9 @@ import {
 import {
   readLearnings
 } from "./chunk-M3YZOJNW.js";
+import {
+  prewarmLatestVersion
+} from "./chunk-POXT5OYN.js";
 import {
   persistScanResult,
   scanIntegrations
@@ -26,11 +33,6 @@ import {
   generateClaudeMd,
   spliceKnitBlock
 } from "./chunk-7UFS67HP.js";
-import {
-  importFromMarkdown,
-  loadKnowledgeBaseSafe,
-  saveKnowledgeBase
-} from "./chunk-WKQHCLLO.js";
 import {
   knowledgePath,
   knowledgebasePath,

package/dist/{chunk-ORKWLA33.js → chunk-OINYMLOV.js}

@@ -9,8 +9,16 @@ import { existsSync, mkdirSync, appendFileSync, readFileSync, statSync } from "f
 import { dirname, basename } from "path";
 function appendGlobalLearning(entry) {
   const path = globalLearningsPath();
-  mkdirSync(dirname(path), { recursive: true });
-  appendFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
+  } catch (err) {
+    process.stderr.write(
+      `[knit] global learning append failed at ${path}: ${err.message}
+`
+    );
+    throw err;
+  }
 }
 function searchGlobalLearnings(query, limit = 10) {
   const lines = readAllLines();

package/dist/chunk-POXT5OYN.js

@@ -0,0 +1,66 @@
+// src/mcp/update-check.ts
+var REGISTRY_DIST_TAGS_URL = "https://registry.npmjs.org/-/package/knit-mcp/dist-tags";
+var FETCH_TIMEOUT_MS = 2e3;
+var CACHE_TTL_MS = 60 * 60 * 1e3;
+var cachedLatest = null;
+var lastCheckedAt = 0;
+var inFlight = null;
+function getCachedLatestVersion() {
+  if (Date.now() - lastCheckedAt > CACHE_TTL_MS) {
+    prewarmLatestVersion();
+  }
+  return cachedLatest;
+}
+function prewarmLatestVersion() {
+  if (inFlight) return;
+  if (Date.now() - lastCheckedAt < CACHE_TTL_MS && cachedLatest !== null) return;
+  inFlight = doFetch().finally(() => {
+    inFlight = null;
+  });
+}
+async function doFetch() {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(REGISTRY_DIST_TAGS_URL, { signal: controller.signal });
+    if (!res.ok) return;
+    const data = await res.json();
+    if (typeof data.latest === "string" && data.latest.length > 0) {
+      cachedLatest = data.latest;
+      lastCheckedAt = Date.now();
+    }
+  } catch {
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function isNewerVersion(latest, current) {
+  const parse = (v) => {
+    const stripped = v.replace(/[-+].*$/, "");
+    const parts = stripped.split(".").map((n) => parseInt(n, 10) || 0);
+    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+  };
+  const [a1, a2, a3] = parse(latest);
+  const [b1, b2, b3] = parse(current);
+  if (a1 !== b1) return a1 > b1;
+  if (a2 !== b2) return a2 > b2;
+  return a3 > b3;
+}
+function __setCachedLatestForTests(version, checkedAtMs = Date.now()) {
+  cachedLatest = version;
+  lastCheckedAt = checkedAtMs;
+  inFlight = null;
+}
+function __resetUpdateCheckForTests() {
+  cachedLatest = null;
+  lastCheckedAt = 0;
+  inFlight = null;
+}
+
+export {
+  getCachedLatestVersion,
+  prewarmLatestVersion,
+  isNewerVersion,
+  __setCachedLatestForTests,
+  __resetUpdateCheckForTests
+};

package/dist/cli.js

@@ -20,10 +20,10 @@ async function runCLI() {
   const gradient = (await import("gradient-string")).default;
   const chalk = (await import("chalk")).default;
   const { setupCommand } = await import("./setup-5TUUWLIJ.js");
-  const { statusCommand } = await import("./status-VJDB75X2.js");
-  const { refreshCommand } = await import("./refresh-SMJ2NGIW.js");
-  const { installAgentsCommand } = await import("./install-agents-OBDCWCPB.js");
-  const { exportCommand } = await import("./export-CGSEUYZA.js");
+  const { statusCommand } = await import("./status-2SEITNIE.js");
+  const { refreshCommand } = await import("./refresh-S62AZ3QA.js");
+  const { installAgentsCommand } = await import("./install-agents-WDBQBWMN.js");
+  const { exportCommand } = await import("./export-4BO6HCXP.js");
   const { doctorCommand } = await import("./doctor-4DN2P2JR.js");
   const ENGRAM_GRADIENT = gradient(["#7c3aed", "#2563eb", "#06b6d4"]);
   const banner = `
@@ -98,13 +98,24 @@ async function runMCP() {
   const { Server } = await import("@modelcontextprotocol/sdk/server/index.js");
   const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
   const { ListToolsRequestSchema, CallToolRequestSchema } = await import("@modelcontextprotocol/sdk/types.js");
-  const { getBrain, detectProjectRoot, refreshBrain } = await import("./cache-3LPETDUT.js");
-  const { getActiveToolDefinitionsForBrain, handleToolCall } = await import("./tools-MIROTK2A.js");
+  const { getBrain, detectProjectRoot, refreshBrain } = await import("./cache-7HSMIYDJ.js");
+  const { getActiveToolDefinitionsForBrain, handleToolCall } = await import("./tools-ECHCPLCB.js");
   const { buildInstructions } = await import("./instructions-JARSXQPO.js");
   const { registerToolsListChangedNotifier } = await import("./notifier-4L27HKHI.js");
   const { loadScanResult } = await import("./integration-scanner-LBD2PIZ3.js");
+  const { prewarmLatestVersion, getCachedLatestVersion, isNewerVersion } = await import("./update-check-GQVDVT2N.js");
   const ROOT_PATH = detectProjectRoot();
   const PER_PROJECT_INSTRUCTIONS = buildInstructions(loadScanResult(ROOT_PATH));
+  prewarmLatestVersion();
+  setTimeout(() => {
+    const latest = getCachedLatestVersion();
+    if (latest && isNewerVersion(latest, VERSION)) {
+      process.stderr.write(
+        `[knit] update available: v${VERSION} installed, v${latest} on npm \u2014 restart Claude Code to upgrade (clear npx cache if needed: \`rm -rf ~/.npm/_npx/\`). Changelog: https://github.com/PDgit12/knit/blob/main/CHANGELOG.md
+`
+      );
+    }
+  }, 250);
   const server = new Server(
     { name: "knit-brain", version: VERSION },
     {

package/dist/{export-CGSEUYZA.js → export-4BO6HCXP.js}

@@ -1,6 +1,6 @@
 import {
   getRecentGlobalLearnings
-} from "./chunk-ORKWLA33.js";
+} from "./chunk-OINYMLOV.js";
 import {
   loadKnowledgeBase
 } from "./chunk-WKQHCLLO.js";

package/dist/{install-agents-OBDCWCPB.js → install-agents-WDBQBWMN.js}

@@ -1,16 +1,17 @@
 import {
   getBrain
-} from "./chunk-TWHNYJAJ.js";
+} from "./chunk-I63UMEBF.js";
 import "./chunk-HROSQ5MS.js";
 import {
   installAgentsForProject
-} from "./chunk-RZOVZYTF.js";
+} from "./chunk-GATMQQK5.js";
+import "./chunk-WKQHCLLO.js";
 import "./chunk-MOOVNMIN.js";
 import "./chunk-ST4X7LZT.js";
 import "./chunk-M3YZOJNW.js";
+import "./chunk-POXT5OYN.js";
 import "./chunk-VB2TIR6L.js";
 import "./chunk-7UFS67HP.js";
-import "./chunk-WKQHCLLO.js";
 import "./chunk-27TA2ZQZ.js";
 
 // src/commands/install-agents.ts

package/dist/{refresh-SMJ2NGIW.js → refresh-S62AZ3QA.js}

@@ -8,7 +8,9 @@ import {
   findFalsePositives
 } from "./chunk-M3YZOJNW.js";
 import {
-  generateClaudeMd
+  KNIT_MARKER_START,
+  generateClaudeMd,
+  spliceKnitBlock
 } from "./chunk-7UFS67HP.js";
 import {
   knowledgePath,
@@ -57,9 +59,19 @@ async function refreshCommand(targetDir) {
     tokenOptimization: "standard"
   };
   const genSpinner = ora({ text: chalk.dim("Regenerating CLAUDE.md..."), spinner: "dots" }).start();
-  writeFileSync(join(rootPath, "CLAUDE.md"), generateClaudeMd(config, knowledge, falsePositives), "utf-8");
+  const claudeMdPath = join(rootPath, "CLAUDE.md");
+  const newBlock = generateClaudeMd(config, knowledge, falsePositives);
+  const existing = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, "utf-8") : "";
+  if (existing && existing.includes(KNIT_MARKER_START)) {
+    const { content } = spliceKnitBlock(existing, newBlock);
+    writeFileSync(claudeMdPath, content, "utf-8");
+  } else if (!existing) {
+    writeFileSync(claudeMdPath, newBlock, "utf-8");
+  } else {
+    genSpinner.warn(chalk.yellow("CLAUDE.md is user-curated (no Knit markers). Skipping write to avoid clobber."));
+  }
   writeFileSync(knowledgePath(rootPath), JSON.stringify(knowledge, null, 2), "utf-8");
-  genSpinner.succeed(chalk.dim("CLAUDE.md + knowledge.json updated"));
+  if (genSpinner.isSpinning) genSpinner.succeed(chalk.dim("CLAUDE.md + knowledge.json updated"));
   console.log();
   console.log(chalk.bold("  Refresh complete"));
   if (falsePositives.length > 0) {

package/dist/{tools-MIROTK2A.js → tools-ECHCPLCB.js}

@@ -1,3 +1,10 @@
+import {
+  appendGlobalLearning,
+  buildGlobalLearning,
+  getRecentGlobalLearnings,
+  loadAllGlobalLearnings,
+  searchGlobalLearnings
+} from "./chunk-OINYMLOV.js";
 import {
   notifyToolsListChanged
 } from "./chunk-WMESQUZU.js";
@@ -9,32 +16,13 @@ import {
 } from "./chunk-UTVFELXS.js";
 import {
   appendSession,
-  getCachedLatestVersion,
   getRecentSessions,
   installAgentsForProject,
-  isNewerVersion,
   loadAllSessions,
   pruneSessionsByAge,
   searchSessions,
   sessionCount
-} from "./chunk-RZOVZYTF.js";
-import {
-  scanProject,
-  scanProjectFingerprint
-} from "./chunk-ST4X7LZT.js";
-import {
-  loadScanResult,
-  persistScanResult,
-  scanIntegrations
-} from "./chunk-VB2TIR6L.js";
-import "./chunk-7UFS67HP.js";
-import {
-  appendGlobalLearning,
-  buildGlobalLearning,
-  getRecentGlobalLearnings,
-  loadAllGlobalLearnings,
-  searchGlobalLearnings
-} from "./chunk-ORKWLA33.js";
+} from "./chunk-GATMQQK5.js";
 import {
   addEntry,
   bumpClassificationTier,
@@ -45,6 +33,20 @@ import {
   recordCacheHit,
   saveKnowledgeBase
 } from "./chunk-WKQHCLLO.js";
+import {
+  scanProject,
+  scanProjectFingerprint
+} from "./chunk-ST4X7LZT.js";
+import {
+  getCachedLatestVersion,
+  isNewerVersion
+} from "./chunk-POXT5OYN.js";
+import {
+  loadScanResult,
+  persistScanResult,
+  scanIntegrations
+} from "./chunk-VB2TIR6L.js";
+import "./chunk-7UFS67HP.js";
 import {
   calibrationPath,
   canonicalRepoRoot,
@@ -395,7 +397,48 @@ function tools(_) {
 | \`knit_define_team\` | Create a custom team. |
 | \`knit_start_team_review\` | Start a parallel review board. |
 | \`knit_post_team_findings\` | Each team posts to the shared board. |
-| \`knit_get_board_summary\` | Cross-team findings, severity-gated. |`;
+| \`knit_get_board_summary\` | Cross-team findings, severity-gated. |
+| \`knit_spawn_team_worktree\` | Spawn a git worktree for a team to do isolated parallel writes. |
+| \`knit_list_team_worktrees\` | List active team worktrees. |
+| \`knit_finalize_team_worktree\` | Merge or discard a team worktree branch. |
+
+**Cross-project memory** (v0.4+):
+| Tool | Use when |
+|------|----------|
+| \`knit_record_global_learning\` | Cross-project insight (applies beyond current repo). |
+| \`knit_search_global_learnings\` | Search learnings across all your projects. |
+| \`knit_reflect\` | Surface candidate patterns from session history. |
+| \`knit_get_suggestions\` | Adaptive warnings derived from past patterns for given domains. |
+| \`knit_install_agent\` | Fetch a specialized VoltAgent on demand. |
+| \`knit_prune_sessions\` | Garbage-collect old session log entries. |
+| \`knit_consolidate_learnings\` | Promote stable patterns to consolidated tier. |
+| \`knit_get_learning\` | Fetch a single learning by id. |
+
+**Feature gating + protocol guard** (v0.5+):
+| Tool | Use when |
+|------|----------|
+| \`knit_list_features\` | See which tools are hidden behind tier gates and how to enable them. |
+| \`knit_enable_feature\` / \`knit_disable_feature\` | Toggle a feature on/off for this project. |
+| \`knit_set_protocol_strictness\` / \`knit_get_protocol_strictness\` | off / warn / block \u2014 controls Protocol Guard hook. |
+| \`knit_scan_integrations\` | Detect external integrations the project uses. |
+| \`knit_compounding_metrics\` | Per-session token + hit-rate metrics. |
+| \`knit_get_metrics_history\` | History of compounding metrics for trend lines. |
+| \`knit_verify_claim\` | Cheap fact-check against the knowledge graph before quoting code. |
+
+**Self-healing classifier** (v0.11):
+| Tool | Use when |
+|------|----------|
+| \`knit_get_calibration\` / \`knit_reset_calibration\` | Inspect or reset per-project classifier tuning. |
+| \`knit_get_fingerprint\` | Project fingerprint used for shape-aware tier gating. |
+| \`knit_infer_domains\` | Auto-derive domain tags from files. |
+| \`knit_compose_template\` | Compose a generated artifact from a template. |
+
+**Requirements ingestion** (v0.11):
+| Tool | Use when |
+|------|----------|
+| \`knit_index_requirements\` | Chunk + BM25-index a long spec for retrieval. |
+| \`knit_generate_test_cases\` | Retrieve relevant chunks for a feature query (token-bounded). |
+| \`knit_list_requirements\` / \`knit_delete_requirements\` | Manage indexed sources. |`;
 }
 
 // src/engine/worktrees.ts
@@ -639,7 +682,6 @@ function classifyOrigin(supporting) {
     else global = true;
     if (local && global) return "mixed";
   }
-  if (local && global) return "mixed";
   return local ? "local" : "global";
 }
 function getAdaptiveSuggestions(kb, taskDomains) {
@@ -1487,6 +1529,9 @@ function chunkRequirements(content, minChars = 50) {
   return chunks;
 }
 function saveSource(rootPath, source) {
+  if (typeof source.sourceId !== "string" || !/^[A-Za-z0-9._-]{1,80}$/.test(source.sourceId)) {
+    throw new Error(`[knit] saveSource: invalid sourceId "${source.sourceId}"`);
+  }
   const path = requirementSourcePath(rootPath, source.sourceId);
   mkdirSync5(dirname5(path), { recursive: true });
   const tmp = `${path}.tmp`;
@@ -1494,6 +1539,7 @@ function saveSource(rootPath, source) {
   renameSync3(tmp, path);
 }
 function loadSource(rootPath, sourceId) {
+  if (typeof sourceId !== "string" || !/^[A-Za-z0-9._-]{1,80}$/.test(sourceId)) return null;
   const path = requirementSourcePath(rootPath, sourceId);
   if (!existsSync5(path)) return null;
   try {
@@ -1883,8 +1929,8 @@ function handleSearchLearnings(params, brain) {
   const limit = Math.max(1, Math.min(50, parseInt(params.limit || "10", 10) || 10));
   if (!query && domains.length === 0) {
     return JSON.stringify({
+      status: "error",
       error: "Provide either query (BM25 free-text) or domains (tag filter), or both. query=auth domains=#api filters BM25 results to entries tagged #api.",
-      query: [],
       results: [],
       count: 0
     });
@@ -2889,9 +2935,7 @@ function handleGetLearning(params, brain) {
   if (!id) return errorResponse("id parameter is required");
   const entry = brain.knowledgeBase.entries.find((e) => e.id === id);
   if (!entry) {
-    return JSON.stringify({
-      error: `No learning with id="${id}". List active ones via knit_search_learnings (default returns id + summary).`
-    });
+    return errorResponse(`No learning with id="${id}". List active ones via knit_search_learnings (default returns id + summary).`);
   }
   recordCacheHit(brain.knowledgeBase);
   return JSON.stringify({
@@ -2914,11 +2958,11 @@ function handleRecordLearning(params, brain) {
   const entry = {
     date,
     summary: redactSecrets(params.summary || "Untitled learning"),
-    domains: (params.domains || "general").split(",").map((d) => d.trim()),
+    domains: (params.domains || "general").split(",").map((d) => redactSecrets(d.trim())),
     approach: redactSecrets(params.approach || ""),
     outcome: ["success", "partial", "failure"].includes(params.outcome) ? params.outcome : "success",
     lesson: redactSecrets(params.lesson || ""),
-    tags: (params.tags || "").split(/\s+/).filter((t) => t.startsWith("#"))
+    tags: (params.tags || "").split(/\s+/).filter((t) => t.startsWith("#")).map((t) => redactSecrets(t))
   };
   addEntry(brain.knowledgeBase, entry);
   saveKnowledgeBase(knowledgebasePath(brain.rootPath), brain.knowledgeBase);
@@ -2946,7 +2990,7 @@ function handleRecordLearning(params, brain) {
 }
 function handleRecordFalsePositive(params, brain) {
   const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-  const tags = [...(params.tags || "").split(/\s+/).filter((t) => t.startsWith("#")), "#false-positive"];
+  const tags = [...(params.tags || "").split(/\s+/).filter((t) => t.startsWith("#")).map((t) => redactSecrets(t)), "#false-positive"];
   const entry = {
     date,
     summary: redactSecrets(params.summary || "Untitled FP"),
@@ -3085,7 +3129,8 @@ function handleIndexRequirements(params, brain) {
     return JSON.stringify({ status: "error", error: "Invalid source_id \u2014 must be 1-80 chars, alphanumeric + . _ - only" });
   }
   const sourceId = userSourceId || slugifySourceId(filePath);
-  const label = (params.label || "").trim() || void 0;
+  const rawLabel = (params.label || "").trim();
+  const label = rawLabel ? redactSecrets(rawLabel) : void 0;
   const source = {
     sourceId,
     sourcePath: filePath,
@@ -3142,8 +3187,13 @@ function handleGenerateTestCases(params, brain) {
       if (s) sourcesToSearch.push(s);
     }
   }
+  const MAX_RESPONSE_BYTES = 100 * 1024;
   const hits = retrieveTopChunks(sourcesToSearch, feature, topN);
-  const contextBytes = hits.reduce((s, h) => s + Buffer.byteLength(h.chunk.text, "utf-8"), 0);
+  let contextBytes = hits.reduce((s, h) => s + Buffer.byteLength(h.chunk.text, "utf-8"), 0);
+  while (contextBytes > MAX_RESPONSE_BYTES && hits.length > 1) {
+    const dropped = hits.pop();
+    contextBytes -= Buffer.byteLength(dropped.chunk.text, "utf-8");
+  }
   const totalBytes = sourcesToSearch.reduce((s, src) => s + src.sourceBytes, 0);
   const reductionPct = totalBytes > 0 ? Math.round(100 - contextBytes / totalBytes * 100) : 0;
   return JSON.stringify({
@@ -3581,6 +3631,16 @@ function handleLoadSession(params, brain) {
   if (wantAll || include.has("patterns")) {
     patterns = reflect(brain.knowledgeBase).slice(0, 3).map((p) => ({ type: p.type, description: p.description, confidence: p.confidence }));
   }
+  let updateAvailable;
+  const cachedLatest = getCachedLatestVersion();
+  if (cachedLatest && isNewerVersion(cachedLatest, VERSION)) {
+    updateAvailable = {
+      current: VERSION,
+      latest: cachedLatest,
+      upgrade: "Restart Claude Code (quit fully + reopen) to spawn a fresh MCP. If npx serves cache, run: rm -rf ~/.npm/_npx/$(ls ~/.npm/_npx | head -1) then reopen.",
+      changelog: "https://github.com/PDgit12/knit/blob/main/CHANGELOG.md"
+    };
+  }
   const response = {
     session_context: {
       last_session: lastSession,
@@ -3598,6 +3658,7 @@ function handleLoadSession(params, brain) {
       ...metrics !== void 0 ? { metrics } : {},
       ...recentSessions !== void 0 ? { recent_sessions: recentSessions } : {}
     },
+    ...updateAvailable ? { update_available: updateAvailable } : {},
     instruction: handoff2 ? "UNFINISHED WORK DETECTED. Read the handoff above \u2014 pick up where the last session left off. Do NOT start fresh." : topLearnings.length > 0 ? `Session loaded. ${topLearnings.length} key learnings, ${fps.length} false positives. Call knit_classify_task to begin. Use include=patterns,teams,metrics,recent_sessions,full_learnings,full_knowledge for more.` : "Fresh brain \u2014 no past learnings yet. Call knit_classify_task to begin."
   };
   return JSON.stringify(response);
@@ -3611,7 +3672,7 @@ function handleSaveSessionSummary(params, brain) {
     date: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     summary: redactSecrets((params.summary || "").slice(0, 500)),
-    tags: (params.tags || "").split(/\s+/).filter((t) => t.startsWith("#")),
+    tags: (params.tags || "").split(/\s+/).filter((t) => t.startsWith("#")).map((t) => redactSecrets(t)),
     outcome,
     filesTouched: params.files_touched ? params.files_touched.split(",").map((f) => f.trim()).filter(Boolean) : void 0,
     domainsTouched: params.domains ? params.domains.split(",").map((d) => d.trim()).filter(Boolean) : void 0
@@ -3813,32 +3874,32 @@ function getToolDefinitions() {
     // ── Query (read the brain) ───────────────────────────────────
     {
       name: "knit_query_imports",
-      description: "Reverse deps for a file \u2014 who imports it.",
+      description: "[GRAPH] Reverse deps \u2014 WHO IMPORTS this file. Use to find blast radius before editing.",
       inputSchema: { type: "object", properties: { file_path: { type: "string", description: "Relative file path." } }, required: ["file_path"] }
     },
     {
       name: "knit_query_dependents",
-      description: "Forward deps for a file \u2014 what it imports.",
+      description: "[GRAPH] Forward deps \u2014 WHAT THIS FILE IMPORTS. Opposite of knit_query_imports (who imports it).",
       inputSchema: { type: "object", properties: { file_path: { type: "string", description: "Relative file path." } }, required: ["file_path"] }
     },
     {
       name: "knit_query_exports",
-      description: "Exports from a file: functions, classes, types, constants.",
+      description: "[GRAPH] Exports from a file: functions, classes, types, constants. Use when verifying a claim or finding the canonical definition.",
       inputSchema: { type: "object", properties: { file_path: { type: "string", description: "Relative file path." } }, required: ["file_path"] }
     },
     {
       name: "knit_query_tests",
-      description: 'Tests for a file, or list all untested files with filter="untested".',
+      description: '[GRAPH] Tests covering a file, OR list all untested files with filter="untested". Use before declaring "tested" on changed code.',
       inputSchema: { type: "object", properties: { file_path: { type: "string", description: "Relative file path (optional)." }, filter: { type: "string", description: '"untested" to list all untested files.' } } }
     },
     {
       name: "knit_find_fanout",
-      description: "High-fanout files \u2014 imported by many others.",
+      description: "[GRAPH] High-fanout files \u2014 imported by many others. Editing these is high-risk; surfaces in classify_task risk_tier.",
       inputSchema: { type: "object", properties: { min_importers: { type: "string", description: "Minimum importers to qualify (default: 3)." } } }
     },
     {
       name: "knit_search_learnings",
-      description: 'BM25 + import-graph hybrid. Pass query="text" for BM25, domains="#tag" filter, files="src/a.ts,src/b.ts" for graph boost on learnings about neighbors. All combinable.',
+      description: "[MEMORY] Search THIS PROJECT's learnings. Use BEFORE re-investigating. Companions: knit_search_global_learnings (cross-project), knit_search_sessions (past tasks). BM25 + graph boost via files=.",
       inputSchema: {
         type: "object",
         properties: {
@@ -3862,7 +3923,7 @@ function getToolDefinitions() {
     // ── Update (write to the brain) ──────────────────────────────
     {
       name: "knit_classify_task",
-      description: "Call first. Returns risk_tier (drives plan mode), scope_tier (drives phases), change_kind, phases, auto_plan_mode, tier. Optional context_budget_remaining (0-100) downgrades gracefully.",
+      description: "[PROTOCOL] BEFORE any Edit/Write. Returns risk_tier (drives plan mode), scope_tier (drives phases), change_kind, auto_plan_mode. Optional context_budget_remaining (0-100) downgrades gracefully.",
       inputSchema: { type: "object", properties: { files_to_touch: { type: "string", description: 'Comma-separated files, or "unknown" for new projects.' }, description: { type: "string", description: "Brief task description." }, verbose: { type: "string", description: '"true" to include reasoning + cross_domain_ripple + files_count (debug fields).' }, context_budget_remaining: { type: "string", description: "Integer 0\u2013100 \u2014 percent of host agent context window remaining. <30 triggers scope downgrade + skips OPTIMIZE phase. Defaults to 100." } }, required: ["files_to_touch"] }
     },
     {
@@ -3872,7 +3933,7 @@ function getToolDefinitions() {
     },
     {
       name: "knit_record_learning",
-      description: "Record a non-obvious, reusable insight. Skip if a future search wouldn't be glad it exists.",
+      description: "[MEMORY-WRITE] Record a non-obvious THIS-PROJECT insight. Skip substring repeats. For cross-project: knit_record_global_learning. For FPs: knit_record_false_positive.",
       inputSchema: { type: "object", properties: { summary: { type: "string", description: "One-line summary." }, domains: { type: "string", description: "Comma-separated domains." }, approach: { type: "string", description: "What approach was taken." }, outcome: { type: "string", description: "success | partial | failure." }, lesson: { type: "string", description: "What to repeat or avoid." }, tags: { type: "string", description: 'Space-separated tags (e.g. "#api #auth").' } }, required: ["summary", "lesson", "tags"] }
     },
     {
@@ -3927,7 +3988,7 @@ function getToolDefinitions() {
     },
     {
       name: "knit_save_handoff",
-      description: "Save state for the next session. failed_attempts is the load-bearing field.",
+      description: "[END OF SESSION \u2014 UNFINISHED] Save state when work is incomplete or context degraded. failed_attempts is the load-bearing field. For finished work use knit_save_session_summary.",
       inputSchema: { type: "object", properties: { goal: { type: "string", description: "What we're trying to accomplish." }, current_state: { type: "string", description: "Where we are now." }, files_in_flight: { type: "string", description: "Files being modified." }, what_changed: { type: "string", description: "Commits and edits." }, failed_attempts: { type: "string", description: "What was tried and why it failed." }, decisions_made: { type: "string", description: "Important choices." }, next_step: { type: "string", description: "ONE most important next thing." } }, required: ["goal", "current_state", "failed_attempts", "next_step"] }
     },
     {
@@ -3978,12 +4039,12 @@ function getToolDefinitions() {
     // ── Session memory ───────────────────────────────────────────
     {
       name: "knit_load_session",
-      description: "Call at session start. Returns handoff, top learnings, false positives by default. Opt in to more via include=patterns,teams,metrics,recent_sessions,full_learnings,full_knowledge,all.",
+      description: "[PROTOCOL FIRST] Call once at session start. Returns handoff, top learnings, FPs, update_available. Opt in via include=patterns,teams,metrics,recent_sessions,full_learnings,all.",
       inputSchema: { type: "object", properties: { include: { type: "string", description: "Comma-separated optional sections." } } }
     },
     {
       name: "knit_save_session_summary",
-      description: "Opt-in. Record a session summary a future search would want to find.",
+      description: "[END OF SESSION] Record a session summary so future knit_search_sessions can find this work. Pair with knit_save_handoff when work is unfinished.",
       inputSchema: {
         type: "object",
         properties: {
@@ -4008,7 +4069,7 @@ function getToolDefinitions() {
     },
     {
       name: "knit_search_sessions",
-      description: 'Search past sessions by free text. "Have I done this before?"',
+      description: '[MEMORY] "Have I done this task before?" \u2014 search past SESSION summaries. Different from knit_search_learnings (lessons) and knit_search_global_learnings (cross-project).',
       inputSchema: {
         type: "object",
         properties: {
@@ -4055,7 +4116,7 @@ function getToolDefinitions() {
     // ── Cross-project learnings (Model C — global pool) ─────────
     {
       name: "knit_record_global_learning",
-      description: "Opt-in. Record a learning to the cross-project pool when it generalizes beyond this project.",
+      description: "[MEMORY-WRITE] Record a learning that generalizes across MULTIPLE projects. Sparingly \u2014 most learnings are project-specific. Companion: knit_record_learning (this project only).",
       inputSchema: {
         type: "object",
         properties: {
@@ -4069,7 +4130,7 @@ function getToolDefinitions() {
     },
     {
       name: "knit_search_global_learnings",
-      description: "Search the cross-project learnings pool across all projects on this machine.",
+      description: "[MEMORY] Search learnings ACROSS ALL projects on this machine. Use when starting a new domain. Companion: knit_search_learnings (this project only).",
       inputSchema: {
         type: "object",
         properties: {
@@ -4166,12 +4227,12 @@ function getToolDefinitions() {
     },
     {
       name: "knit_verify_claim",
-      description: 'Fact-check one claim against the knowledge graph. Patterns: "A imports B", "X exports Y", "A is tested by B", "X exists". Verdict: verified | contradicted | unparseable.',
+      description: '[REVIEW] Fact-check one claim before LEARN on standard/complex scope. Patterns: "A imports B", "X exports Y", "A is tested by B", "X exists". Verdict: verified | contradicted | unparseable.',
       inputSchema: { type: "object", properties: { claim: { type: "string", description: "One claim about the codebase to verify." } }, required: ["claim"] }
     },
     {
       name: "knit_get_learning",
-      description: "Fetch one full learning by id. Pair with knit_search_learnings (default returns headlines) for hierarchical retrieval \u2014 expand only what you need.",
+      description: "[MEMORY] Expand ONE learning by id (from a prior knit_search_learnings hit). Hierarchical retrieval \u2014 search returns headlines, this fetches details. Saves tokens vs. dumping full bodies.",
       inputSchema: { type: "object", properties: { id: { type: "string", description: "Learning id from a prior knit_search_learnings result." } }, required: ["id"] }
     },
     {
@@ -4260,7 +4321,7 @@ function handleToolCall(toolName, params, brain) {
     const allowAbsolute = toolName === "knit_index_requirements";
     const bad = decoded.includes("..") || decoded.includes("\0") || !allowAbsolute && (decoded.startsWith("/") || /^[A-Za-z]:\//.test(decoded));
     if (bad) {
-      return JSON.stringify({ error: "Invalid file path \u2014 no traversal or absolute paths allowed" });
+      return JSON.stringify({ status: "error", error: "Invalid file path \u2014 no traversal or absolute paths allowed" });
     }
     params.file_path = decoded;
   }
@@ -4271,7 +4332,7 @@ function handleToolCall(toolName, params, brain) {
   }
   const handler = handlers[toolName];
   if (!handler) {
-    return JSON.stringify({ error: `Unknown tool: ${toolName}` });
+    return JSON.stringify({ status: "error", error: `Unknown tool: ${toolName}` });
   }
   return handler(params, brain);
 }

package/dist/update-check-GQVDVT2N.js

@@ -0,0 +1,14 @@
+import {
+  __resetUpdateCheckForTests,
+  __setCachedLatestForTests,
+  getCachedLatestVersion,
+  isNewerVersion,
+  prewarmLatestVersion
+} from "./chunk-POXT5OYN.js";
+export {
+  __resetUpdateCheckForTests,
+  __setCachedLatestForTests,
+  getCachedLatestVersion,
+  isNewerVersion,
+  prewarmLatestVersion
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knit-mcp",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Knit — second brain for Claude Code. MCP server giving any AI agent project-scoped memory, tiered workflow protocol, and parallel team worktrees.",
   "type": "module",
   "bin": {

package/dist/{status-VJDB75X2.js → status-2SEITNIE.js}

@@ -1,12 +1,12 @@
-import {
-  readLearnings
-} from "./chunk-M3YZOJNW.js";
 import {
   getKBSummary,
   getStaleEntries,
   getTopEntries,
   loadKnowledgeBase
 } from "./chunk-WKQHCLLO.js";
+import {
+  readLearnings
+} from "./chunk-M3YZOJNW.js";
 import {
   knowledgePath,
   knowledgebasePath,