opencode-swarm 7.177.0 → 7.178.0

package/dist/cli/{server-kdjc5aw8.js → server-58s1wwap.js}

@@ -10,106 +10,142 @@ import {
 import {
   MAX_PARALLEL_VERDICT_TASKS,
   buildSynonymIndex,
+  classifyCommand,
   computeParallelVerdict,
   computeQualityBudget,
   computeSastScan,
   createMemoryGateway,
   createSwarmTool,
+  detectPosixWrites,
+  detectWindowsWrites,
   expandTokens,
   getAgentSession,
   getCoChangePairs,
   readSynonymMap,
   redactSecrets,
+  resolveWriteTargets,
   symbols
-} from "./index-ebmep9me.js";
+} from "./index-heg4em8j.js";
 import {
   getProfileForFile
 } from "./index-hnvmj9wx.js";
 import {
   pLimit
-} from "./index-vfp9hjgv.js";
-import"./index-by7xpk8f.js";
-import"./index-eefz8ghz.js";
-import"./index-rgapg88w.js";
+} from "./index-q9vb5e7n.js";
+import {
+  checkFileAuthority,
+  checkWriteTargetForSymlink
+} from "./index-qs8eth8h.js";
+import"./index-bfz1jvcn.js";
+import"./index-vfc7d22n.js";
 import {
   _internals,
+  loadPlan,
   loadPlanJsonOnly,
   saveEvidence
-} from "./index-zbq9091c.js";
-import"./index-k6bjkqw8.js";
+} from "./index-jzxeymr0.js";
+import"./index-mpcp6rmj.js";
 import"./index-txdagbh7.js";
 import"./index-n1tcj1q7.js";
 import {
   containsControlChars,
+  createTargetWithinRootValidator,
   isCanonicalPathWithinRoot,
-  validateTargetWithinRoot
-} from "./index-fpbcxykc.js";
-import"./index-mcq6xs4k.js";
-import"./index-8dy3qf4q.js";
-import"./index-nzz58tbs.js";
+  validateSymlinkBoundary,
+  validateTargetWithinRoot,
+  validateWorkspaceRoot
+} from "./index-6b295cas.js";
+import"./index-zsm8h8y1.js";
+import"./index-at0ygwwp.js";
+import {
+  resolveCohortId
+} from "./index-zex7644g.js";
 import"./index-fyfbpz4f.js";
-import"./index-eya03h5m.js";
+import"./index-y74n1sy8.js";
 import"./index-549wxbe1.js";
 import"./index-zsrtt42s.js";
-import"./index-4chr4gbq.js";
-import"./index-5d2avnj9.js";
-import"./index-7nsvszwn.js";
+import"./index-wkde35ej.js";
+import"./index-pm7c6f66.js";
+import"./index-2b1whj28.js";
 import {
   getLanguageForExtension,
   getParserForFile
 } from "./index-pt7h91zc.js";
 import"./index-q7sjgr1y.js";
-import"./index-r18n5f17.js";
-import"./index-fnmt1ema.js";
-import"./index-ef2fa774.js";
+import"./index-kfk403mc.js";
+import"./index-p27az2hc.js";
+import"./index-rp0jk48x.js";
 import {
   effectiveRetrievalOutcomes,
   newTraceId,
   readAuthoritativeKnowledgeCounterRollups,
   recordKnowledgeEvent
-} from "./index-w7aedfce.js";
-import"./index-exhm2ztr.js";
+} from "./index-29begjkp.js";
+import"./index-zmb8fjp5.js";
 import"./index-2s7dvzff.js";
-import"./index-gwnbprzk.js";
-import"./index-wemtrnch.js";
+import {
+  appendUnactionable,
+  validateActionability,
+  validateActionableFields,
+  validateLesson
+} from "./index-d5dexrv1.js";
+import {
+  resolveWorktreeId
+} from "./index-ffqy30e5.js";
 import"./index-rtry5xyf.js";
-import"./index-rz4gpt3n.js";
+import"./index-2vhkwy6v.js";
 import"./index-frcemc0b.js";
 import"./index-wrt875kh.js";
-import"./index-5w51tawb.js";
-import"./index-zwam9stk.js";
-import"./index-z8j7jqxt.js";
-import"./index-v2he8xfj.js";
-import"./index-1bq6hkw5.js";
-import"./index-xnednxvm.js";
+import {
+  normalizeScopeFiles
+} from "./index-gg44hytk.js";
+import"./index-ke3m026z.js";
+import"./index-j1v54ahd.js";
+import"./index-y6a2bkp1.js";
+import"./index-w4yjy3vp.js";
+import"./index-tnjmn0dn.js";
 import"./index-rdm3px0g.js";
 import"./index-ry16d01s.js";
-import"./index-tbswvz8s.js";
+import"./index-yeh78c1g.js";
 import {
+  computeContentHash,
   computeOutcomeSignal,
+  dedupeCapped,
+  findActiveSwarmNearDuplicate,
+  findNearDuplicate,
+  inferTags,
   jaccardBigram,
   normalize,
   readKnowledge,
   readRetractionRecords,
+  reinforceSwarmKnowledgeEntry,
   resolveHiveKnowledgePath,
   resolveSwarmKnowledgePath,
+  transactKnowledge,
   wordBigrams
-} from "./index-hxdswvtv.js";
+} from "./index-2mdk6nt9.js";
 import"./index-vzm6zre7.js";
 import"./index-ae75rja9.js";
-import"./index-en0p0hqp.js";
-import"./index-tj0sdxg9.js";
+import"./index-yj1kr0ft.js";
+import {
+  tryAcquireLock
+} from "./index-j3rkh9mp.js";
 import"./index-7g4c7s5r.js";
-import"./index-2jtmevrr.js";
-import"./index-yhaxn5r7.js";
-import"./index-1xnse449.js";
+import"./index-wfbh1bx8.js";
+import {
+  assertSwarmContainedTarget,
+  atomicWriteSwarmFile
+} from "./index-zsp9de3k.js";
+import {
+  canonicalRootKeyFresh
+} from "./index-1xnse449.js";
 import {
   escapeRegex
 } from "./index-c1ggtmpm.js";
 import {
   loadGateOverrides,
   loadPluginConfigWithMeta
-} from "./index-zzr7f594.js";
+} from "./index-18hjycr1.js";
 import {
   init_git_executable,
   resolveGitExecutableAsync
@@ -119,12 +155,13 @@ import {
   KnowledgeConfigSchema,
   init_schema,
   stripKnownSwarmPrefix
-} from "./index-73arkdgf.js";
+} from "./index-wbkxbgk8.js";
 import {
   TOOL_METADATA,
   init_tool_metadata
-} from "./index-5frh43fj.js";
+} from "./index-m2n1rhgv.js";
 import {
+  KNOWLEDGE_SCHEMA_VERSION,
   init_knowledge_types,
   isActiveStatus
 } from "./index-bk5tah7q.js";
@@ -167,8 +204,13 @@ import {
   unknown
 } from "./index-gknz3bv1.js";
 import"./index-zpsr8rpc.js";
-import"./index-76qm2c2y.js";
-import"./index-yzjaj53h.js";
+import"./index-wvghb3x6.js";
+import {
+  getPathFlavor,
+  init_path_identity,
+  normalizePathIdentity,
+  unsafePathTextReason
+} from "./index-9rwhas09.js";
 import {
   init_logger,
   warn
@@ -7066,7 +7108,7 @@ var require_dist = __commonJS((exports, module) => {
 });
 
 // src/mcp/server.ts
-import path7 from "path";
+import path9 from "path";
 
 // node_modules/zod/v3/helpers/util.js
 var util;
@@ -15532,615 +15574,1070 @@ function applyResponsePipeline(payload) {
 // src/mcp/registry.ts
 init_tool_metadata();
 
-// src/mcp/adapters/knowledge-memory.ts
+// src/tools/knowledge-add.ts
 init_zod();
-import { existsSync as existsSync4 } from "fs";
-import path5 from "path";
-init_schema();
-
-// src/hooks/search-knowledge.ts
-init_schema();
-import { existsSync, statSync } from "fs";
-import path from "path";
-init_logger();
-
-// src/hooks/knowledge-reader.ts
-init_logger();
+import { randomUUID } from "crypto";
 init_knowledge_types();
-var JACCARD_THRESHOLD = 0.6;
-var HIVE_TIER_BOOST = 0.05;
-var DEFAULT_SAME_PROJECT_PENALTY = -0.05;
-function inferCategoriesFromPhase(phaseDescription) {
-  const lower = phaseDescription.toLowerCase();
-  const patterns = [
-    {
-      pattern: /\b(?:test|qa|quality|verification|validation)\b/,
-      categories: ["testing", "debugging"]
-    },
-    {
-      pattern: /\b(?:implement|build|develop|coding|code)\b/,
-      categories: ["tooling", "architecture", "debugging"]
-    },
-    {
-      pattern: /\b(?:integrat|deploy|ci|cd|release|publish)\b/,
-      categories: ["integration", "tooling", "performance"]
-    },
-    {
-      pattern: /\b(?:plan|design|architect|spec|requirement)\b/,
-      categories: ["architecture", "process"]
-    },
-    {
-      pattern: /\b(?:review|refactor|cleanup|polish|optimi)\b/,
-      categories: ["performance", "architecture", "process"]
-    },
-    {
-      pattern: /\b(?:secur|audit|harden|compliance)\b/,
-      categories: ["security", "testing"]
-    },
-    {
-      pattern: /\b(?:setup|config|scaffold|init|bootstrap)\b/,
-      categories: ["tooling", "other"]
-    },
-    {
-      pattern: /\b(?:doc|readme|changelog)\b/,
-      categories: ["process", "tooling"]
+var VALID_CATEGORIES = [
+  "process",
+  "architecture",
+  "tooling",
+  "security",
+  "testing",
+  "debugging",
+  "performance",
+  "integration",
+  "todo",
+  "other"
+];
+var KNOWLEDGE_ADD_FIELD_CAP = 20;
+function mergeLessonTags(tagsInput, lesson) {
+  return dedupeCapped([...Array.isArray(tagsInput) ? tagsInput : [], ...inferTags(lesson)], { cap: KNOWLEDGE_ADD_FIELD_CAP });
+}
+function strArray(v) {
+  return Array.isArray(v) ? dedupeCapped(v, { cap: KNOWLEDGE_ADD_FIELD_CAP }) : undefined;
+}
+var knowledge_add = createSwarmTool({
+  allowWorkingDirectoryOverride: true,
+  description: "Store a new lesson in the knowledge base for future reference. The lesson will be available for retrieval via knowledge_recall.",
+  args: {
+    lesson: exports_external.string().min(15).max(280).describe("The lesson to store (15-280 characters)"),
+    category: exports_external.enum(VALID_CATEGORIES).describe("Knowledge category for the lesson"),
+    tags: exports_external.array(exports_external.string()).optional().describe("Optional tags for better searchability"),
+    scope: exports_external.string().optional().describe("Scope of the lesson (global or stack:<name>)"),
+    applies_to_agents: exports_external.array(exports_external.string()).optional().describe('Agent roles this lesson applies to (e.g. ["coder"]). REQUIRED (or applies_to_tools) for the lesson to become active.'),
+    applies_to_tools: exports_external.array(exports_external.string()).optional().describe('Tool names this lesson applies to (e.g. ["edit","bash"]). REQUIRED (or applies_to_agents) for the lesson to become active.'),
+    required_actions: exports_external.array(exports_external.string()).optional().describe("Concrete actions to always take. At least one predicate field (required_actions / forbidden_actions / verification_checks) is REQUIRED for the lesson to become active."),
+    forbidden_actions: exports_external.array(exports_external.string()).optional().describe("Concrete actions to never take."),
+    verification_checks: exports_external.array(exports_external.string()).optional().describe("Checks a reviewer can run to verify compliance.")
+  },
+  execute: async (args, directory) => {
+    let lessonInput;
+    let categoryInput;
+    let tagsInput;
+    let scopeInput;
+    try {
+      if (args && typeof args === "object") {
+        const obj2 = args;
+        lessonInput = obj2.lesson;
+        categoryInput = obj2.category;
+        tagsInput = obj2.tags;
+        scopeInput = obj2.scope;
+      }
+    } catch {}
+    if (typeof lessonInput !== "string") {
+      return JSON.stringify({
+        success: false,
+        error: "lesson must be a string"
+      });
     }
-  ];
-  for (const { pattern, categories } of patterns) {
-    if (pattern.test(lower)) {
-      return categories;
+    const lesson = lessonInput;
+    if (lesson.length < 15 || lesson.length > 280) {
+      return JSON.stringify({
+        success: false,
+        error: "lesson must be between 15 and 280 characters"
+      });
+    }
+    if (typeof categoryInput !== "string") {
+      return JSON.stringify({
+        success: false,
+        error: "category must be a string"
+      });
+    }
+    const category = categoryInput;
+    if (!VALID_CATEGORIES.includes(category)) {
+      return JSON.stringify({
+        success: false,
+        error: `category must be one of: ${VALID_CATEGORIES.join(", ")}`
+      });
+    }
+    const tags = mergeLessonTags(tagsInput, lesson);
+    const scope = typeof scopeInput === "string" && scopeInput.length > 0 ? scopeInput : "global";
+    const obj = args && typeof args === "object" ? args : {};
+    const actionable = {
+      applies_to_agents: strArray(obj.applies_to_agents),
+      applies_to_tools: strArray(obj.applies_to_tools),
+      required_actions: strArray(obj.required_actions),
+      forbidden_actions: strArray(obj.forbidden_actions),
+      verification_checks: strArray(obj.verification_checks)
+    };
+    const shape = validateActionableFields(actionable);
+    if (!shape.valid) {
+      return JSON.stringify({
+        success: false,
+        error: `invalid actionability fields: ${shape.errors.join("; ")}`
+      });
+    }
+    let project_name = "";
+    let phase_number = 1;
+    try {
+      const plan = await loadPlan(directory);
+      project_name = plan?.title ?? "";
+      if (typeof plan?.current_phase === "number") {
+        phase_number = plan.current_phase;
+      }
+    } catch {}
+    let producer = null;
+    try {
+      const [worktreeId, cohort] = await Promise.all([
+        resolveWorktreeId(directory),
+        resolveCohortId(directory)
+      ]);
+      producer = {
+        cohort_id: cohort.cohortId,
+        worktree_id: worktreeId
+      };
+    } catch {}
+    const nowIso = new Date().toISOString();
+    const entry = {
+      id: randomUUID(),
+      tier: "swarm",
+      lesson,
+      category,
+      tags,
+      scope,
+      confidence: 0.5,
+      status: "candidate",
+      confirmed_by: [],
+      project_name,
+      retrieval_outcomes: {
+        applied_count: 0,
+        succeeded_after_count: 0,
+        failed_after_count: 0
+      },
+      schema_version: KNOWLEDGE_SCHEMA_VERSION,
+      producer,
+      revision: 1,
+      content_hash: computeContentHash(lesson),
+      created_at: nowIso,
+      updated_at: nowIso,
+      auto_generated: false,
+      hive_eligible: false,
+      ...actionable
+    };
+    let config;
+    let dedupThreshold = 0.6;
+    try {
+      const loaded = loadPluginConfigWithMeta(directory);
+      config = loaded.config;
+      dedupThreshold = config.knowledge?.dedup_threshold ?? 0.6;
+      if (config.knowledge?.validation_enabled !== false) {
+        const validation = validateLesson(lesson, [], {
+          category,
+          scope,
+          confidence: 0.5
+        });
+        if (!validation.valid) {
+          return JSON.stringify({
+            success: false,
+            error: `Validation failed: ${validation.reason}`
+          });
+        }
+      }
+    } catch {}
+    const actionability = validateActionability(entry);
+    if (!actionability.actionable) {
+      try {
+        await appendUnactionable(directory, entry, actionability.reason ?? "unactionable");
+      } catch {}
+      return JSON.stringify({
+        success: false,
+        quarantined: true,
+        id: entry.id,
+        reason: actionability.reason,
+        hint: "Provide at least one of required_actions/forbidden_actions/verification_checks AND at least one of applies_to_agents/applies_to_tools, then retry."
+      });
+    }
+    try {
+      const maxEntries = config?.knowledge?.swarm_max_entries ?? 100;
+      let duplicateResponse;
+      await transactKnowledge(resolveSwarmKnowledgePath(directory), (existingEntries) => {
+        const activeDuplicate = findActiveSwarmNearDuplicate(lesson, existingEntries, dedupThreshold);
+        if (activeDuplicate) {
+          const result = reinforceSwarmKnowledgeEntry(activeDuplicate, {
+            phase_number,
+            confirmed_at: new Date().toISOString(),
+            project_name
+          });
+          duplicateResponse = {
+            id: activeDuplicate.id,
+            reinforced: result.reinforced,
+            idempotent: result.reason === "already_confirmed_phase",
+            inactive: false
+          };
+          return result.reinforced ? existingEntries : null;
+        }
+        const inactiveDuplicate = findNearDuplicate(lesson, existingEntries, dedupThreshold);
+        if (inactiveDuplicate) {
+          duplicateResponse = {
+            id: inactiveDuplicate.id,
+            reinforced: false,
+            idempotent: false,
+            inactive: true
+          };
+          return null;
+        }
+        const updated = [...existingEntries, entry];
+        if (updated.length > maxEntries) {
+          return updated.slice(updated.length - maxEntries);
+        }
+        return updated;
+      });
+      if (duplicateResponse) {
+        if (duplicateResponse.inactive) {
+          return JSON.stringify({
+            success: false,
+            id: duplicateResponse.id,
+            message: "near-duplicate of inactive existing entry"
+          });
+        }
+        return JSON.stringify({
+          success: true,
+          id: duplicateResponse.id,
+          reinforced: duplicateResponse.reinforced,
+          idempotent: duplicateResponse.idempotent,
+          message: duplicateResponse.reinforced ? "near-duplicate reinforced existing entry" : "near-duplicate already confirmed for this phase"
+        });
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return JSON.stringify({
+        success: false,
+        error: message
+      });
     }
+    return JSON.stringify({
+      success: true,
+      id: entry.id,
+      category
+    });
+  }
+});
+
+// src/mcp/write-receipts.ts
+init_zod();
+import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { lstat, open } from "fs/promises";
+import * as path from "path";
+var MCP_WRITE_RECEIPTS_RELATIVE_PATH = path.join(".swarm", "mcp-write-receipts.jsonl");
+var MCP_WRITE_RECEIPTS_ARCHIVE_RELATIVE_PATH = path.join(".swarm", "mcp-write-receipts-archive.jsonl");
+var PREPARED_LEASE_MS = 30000;
+var MAX_RECEIPT_RECORDS = 500;
+var MAX_RECEIPT_ARCHIVE_RECORDS = 1e4;
+var MAX_RECEIPT_LINE_BYTES = 16384;
+var MAX_RECEIPT_JOURNAL_BYTES = 512 * 1024;
+var MAX_RECEIPT_ARCHIVE_BYTES = 16 * 1024 * 1024;
+var MAX_RECEIPT_RESPONSE_BYTES = 8 * 1024;
+var KNOWLEDGE_ADD_POLICY_VERSION = "knowledge_add:v1";
+var MAX_IDEMPOTENCY_KEY_LENGTH = 128;
+var MAX_ARGUMENT_BYTES = 128 * 1024;
+var MAX_CANONICAL_NODES = 2048;
+var MAX_CANONICAL_ARRAY_ITEMS = 64;
+var MAX_CANONICAL_OBJECT_KEYS = 64;
+var MAX_KNOWLEDGE_ARRAY_ITEMS = 20;
+var MAX_KNOWLEDGE_TEXT_LENGTH = 280;
+var MAX_KNOWLEDGE_OPTIONAL_TEXT_LENGTH = 256;
+var KNOWLEDGE_CATEGORIES = [
+  "process",
+  "architecture",
+  "tooling",
+  "security",
+  "testing",
+  "debugging",
+  "performance",
+  "integration",
+  "todo",
+  "other"
+];
+var writeReceiptStatusInput = exports_external.object({
+  idempotency_key: exports_external.string().min(1).max(MAX_IDEMPOTENCY_KEY_LENGTH).refine((value) => ![...value].some((character) => {
+    const code = character.codePointAt(0) ?? 0;
+    return code <= 31 || code === 127;
+  }), { message: "idempotency_key must not contain control characters" })
+});
+var WRITE_RECEIPT_STATES = [
+  "PREPARED",
+  "COMMITTED",
+  "FAILED_NO_EFFECT",
+  "IN_DOUBT"
+];
+
+class WriteReceiptError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "WriteReceiptError";
+    this.code = code;
   }
-  return ["process", "tooling"];
 }
-async function readMergedKnowledge(directory, config, context, opts) {
-  const swarmPath = resolveSwarmKnowledgePath(directory);
-  const swarmEntries = await readKnowledge(swarmPath);
-  let hiveEntries = [];
-  if (config.hive_enabled !== false) {
-    const hivePath = resolveHiveKnowledgePath();
-    hiveEntries = await readKnowledge(hivePath);
+var receiptRecordSchema = exports_external.object({
+  version: exports_external.literal(1),
+  receipt_id: exports_external.string().regex(/^[0-9a-f-]{36}$/i),
+  attempt_id: exports_external.string().regex(/^[0-9a-f-]{36}$/i),
+  tool: exports_external.string().min(1).max(80),
+  root_hash: exports_external.string().regex(/^[0-9a-f]{64}$/),
+  idempotency_hash: exports_external.string().regex(/^[0-9a-f]{64}$/),
+  arguments_digest: exports_external.string().regex(/^[0-9a-f]{64}$/),
+  policy_digest: exports_external.string().regex(/^[0-9a-f]{64}$/),
+  state: exports_external.enum(WRITE_RECEIPT_STATES),
+  prepared_at: exports_external.number().finite().nonnegative(),
+  updated_at: exports_external.number().finite().nonnegative(),
+  lease_expires_at: exports_external.number().finite().nonnegative(),
+  response: exports_external.string().max(MAX_RECEIPT_RESPONSE_BYTES).optional(),
+  error: exports_external.string().max(MAX_RECEIPT_RESPONSE_BYTES).optional()
+}).strict();
+function journalPath(root) {
+  return path.join(root, MCP_WRITE_RECEIPTS_RELATIVE_PATH);
+}
+function assertReceiptPaths(root) {
+  const journal = journalPath(root);
+  const lockDirectory = path.join(root, ".swarm", "locks");
+  try {
+    assertSwarmContainedTarget(journal);
+    assertSwarmContainedTarget(path.join(lockDirectory, "mcp-write-receipts.lock"));
+    assertSwarmContainedTarget(path.join(root, MCP_WRITE_RECEIPTS_ARCHIVE_RELATIVE_PATH));
+    validateSymlinkBoundary(journal, root);
+    validateSymlinkBoundary(lockDirectory, root);
+  } catch {
+    throw new WriteReceiptError("JOURNAL_UNAVAILABLE", "Write receipt journal path is outside the project boundary");
   }
-  const seenLessons = new Set;
-  const merged = [];
-  for (const entry of hiveEntries) {
-    const normalized = normalize(entry.lesson);
-    seenLessons.add(normalized);
-    merged.push({
-      ...entry,
-      relevanceScore: { category: 0, confidence: 0, keywords: 0 },
-      finalScore: 0
-    });
+}
+function getWriteReceiptArchivePath(root) {
+  return path.join(root, MCP_WRITE_RECEIPTS_ARCHIVE_RELATIVE_PATH);
+}
+function hash(value) {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function canonicalRoot(root) {
+  return canonicalRootKeyFresh(root);
+}
+function hasControlCharacters(value) {
+  for (const character of value) {
+    const code = character.codePointAt(0);
+    if (code !== undefined && (code <= 31 || code === 127))
+      return true;
   }
-  for (const entry of swarmEntries) {
-    const normalized = normalize(entry.lesson);
-    if (seenLessons.has(normalized)) {
-      continue;
+  return false;
+}
+function assertSafeRequest(request) {
+  if (!request.root || !path.isAbsolute(request.root)) {
+    throw new WriteReceiptError("INVALID_REQUEST", "Write receipt requires an absolute project root");
+  }
+  if (!request.tool || request.tool.length > 80 || hasControlCharacters(request.tool)) {
+    throw new WriteReceiptError("INVALID_REQUEST", "Write receipt tool identity is invalid");
+  }
+  if (!request.idempotencyKey || request.idempotencyKey.length > MAX_IDEMPOTENCY_KEY_LENGTH || hasControlCharacters(request.idempotencyKey)) {
+    throw new WriteReceiptError("INVALID_REQUEST", "Idempotency key is empty, too long, or contains control characters");
+  }
+}
+function stableValue(value, depth = 0, budget) {
+  const state = budget ?? { nodes: 0, bytes: 0 };
+  state.nodes += 1;
+  if (state.nodes > MAX_CANONICAL_NODES) {
+    throw new WriteReceiptError("INVALID_REQUEST", "Write arguments exceed the bounded receipt digest input");
+  }
+  if (depth > 16)
+    return "[depth-limited]";
+  if (value === null || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "string") {
+    state.bytes += Buffer.byteLength(value, "utf8");
+    if (state.bytes > MAX_ARGUMENT_BYTES) {
+      throw new WriteReceiptError("INVALID_REQUEST", "Write arguments exceed the bounded receipt digest input");
     }
-    const swarmBigrams = wordBigrams(normalized);
-    const isHiveNearDup = hiveEntries.some((hiveEntry) => jaccardBigram(swarmBigrams, wordBigrams(normalize(hiveEntry.lesson))) >= JACCARD_THRESHOLD);
-    if (isHiveNearDup)
-      continue;
-    const isSwarmNearDup = merged.some((m) => m.tier === "swarm" && jaccardBigram(swarmBigrams, wordBigrams(normalize(m.lesson))) >= JACCARD_THRESHOLD);
-    if (isSwarmNearDup)
-      continue;
-    seenLessons.add(normalized);
-    merged.push({
-      ...entry,
-      relevanceScore: { category: 0, confidence: 0, keywords: 0 },
-      finalScore: 0
-    });
+    return value;
   }
-  const retractionRecords = await readRetractionRecords(directory);
-  const suppressedLessons = new Set(retractionRecords.map((record3) => record3.normalized_lesson).filter((value) => typeof value === "string" && value.length > 0));
-  const scopeFilter = config.scope_filter ?? ["global"];
-  const filtered = merged.filter((entry) => (opts?.skipScopeFilter || scopeFilter.some((pattern) => (entry.scope ?? "global") === pattern)) && isActiveStatus(entry.status) && !suppressedLessons.has(normalize(entry.lesson)));
-  const ranked = filtered.map((entry) => {
-    let categoryScore = 0;
-    if (context?.currentPhase) {
-      const phaseCategories = inferCategoriesFromPhase(context.currentPhase);
-      if (phaseCategories.includes(entry.category)) {
-        categoryScore = 1;
-      } else if (entry.category === "process") {
-        categoryScore = 0.5;
-      }
-    } else {
-      categoryScore = 0.5;
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : "[non-finite]";
+  }
+  if (typeof value === "bigint")
+    return "[bigint]";
+  if (typeof value === "undefined")
+    return "[undefined]";
+  if (Array.isArray(value)) {
+    if (value.length > MAX_CANONICAL_ARRAY_ITEMS) {
+      throw new WriteReceiptError("INVALID_REQUEST", "Write arguments exceed the bounded receipt digest input");
     }
-    const confidenceScore = entry.confidence;
-    let keywordsScore = 0;
-    if (context?.techStack && entry.tags.length > 0) {
-      const matchingTags = entry.tags.filter((t) => context.techStack.some((s) => t.toLowerCase().includes(s.toLowerCase()) || s.toLowerCase().includes(t.toLowerCase()))).length;
-      keywordsScore = Math.min(matchingTags / Math.max(entry.tags.length, 1), 1);
-    } else if (entry.tags.length === 0) {
-      keywordsScore = 0.5;
+    return value.map((item) => stableValue(item, depth + 1, state));
+  }
+  if (typeof value === "object") {
+    const record3 = value;
+    const keys = Object.keys(record3).sort();
+    if (keys.length > MAX_CANONICAL_OBJECT_KEYS) {
+      throw new WriteReceiptError("INVALID_REQUEST", "Write arguments exceed the bounded receipt digest input");
     }
-    let tierBoost = 0;
-    let isSameProject = false;
-    if (entry.tier === "hive" && "source_project" in entry) {
-      const sourceProject = entry.source_project;
-      isSameProject = !!(context?.projectName && sourceProject === context.projectName);
-      tierBoost = HIVE_TIER_BOOST;
+    const result = Object.create(null);
+    for (const key of keys) {
+      state.bytes += Buffer.byteLength(key, "utf8");
+      if (state.bytes > MAX_ARGUMENT_BYTES) {
+        throw new WriteReceiptError("INVALID_REQUEST", "Write arguments exceed the bounded receipt digest input");
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(record3, key);
+      result[key] = stableValue(descriptor && "value" in descriptor ? descriptor.value : "[accessor]", depth + 1, state);
     }
-    const sameProjectPenalty = isSameProject ? DEFAULT_SAME_PROJECT_PENALTY : 0;
-    const finalScore = categoryScore * 0.4 + confidenceScore * 0.35 + keywordsScore * 0.25 + tierBoost + sameProjectPenalty;
-    const relevanceScore = {
-      category: categoryScore,
-      confidence: confidenceScore,
-      keywords: keywordsScore
-    };
-    return {
-      ...entry,
-      relevanceScore,
-      finalScore: Math.min(Math.max(finalScore, 0), 1)
-    };
-  });
-  ranked.sort((a, b) => {
-    const scoreDiff = b.finalScore - a.finalScore;
-    if (Math.abs(scoreDiff) > 0.001)
-      return scoreDiff;
-    const dateA = new Date(a.created_at).getTime();
-    const dateB = new Date(b.created_at).getTime();
-    return dateB - dateA;
-  });
-  const maxInject = config.max_inject_count ?? 5;
-  const topN = ranked.slice(0, maxInject);
-  return topN;
+    return result;
+  }
+  return `[${typeof value}]`;
 }
-function lc(s) {
-  return (s ?? "").toLowerCase();
+function canonicalArguments(value) {
+  const normalized = stableValue(value, 0, { nodes: 0, bytes: 0 });
+  const encoded = JSON.stringify(normalized);
+  if (encoded === undefined || Buffer.byteLength(encoded, "utf8") > MAX_ARGUMENT_BYTES) {
+    throw new WriteReceiptError("INVALID_REQUEST", "Write arguments exceed the bounded receipt digest input");
+  }
+  return encoded;
 }
-function anyMatch(haystack, needles) {
-  if (needles.length === 0)
-    return false;
-  const hay = haystack.map(lc);
-  return needles.some((n) => hay.some((h) => h.includes(lc(n))));
+function computeWriteReceiptIdentity(request) {
+  assertSafeRequest(request);
+  return {
+    root_hash: hash(canonicalRoot(request.root)),
+    idempotency_hash: hash(request.idempotencyKey),
+    arguments_digest: hash(canonicalArguments(request.arguments)),
+    policy_digest: hash(request.policy ?? KNOWLEDGE_ADD_POLICY_VERSION)
+  };
 }
-function tokenizeContext(ctx) {
-  const parts = [];
-  if (ctx.taskTitle)
-    parts.push(ctx.taskTitle);
-  if (ctx.taskDescription)
-    parts.push(ctx.taskDescription);
-  if (ctx.lastUserMessage)
-    parts.push(ctx.lastUserMessage);
-  if (ctx.currentAction)
-    parts.push(ctx.currentAction);
-  if (ctx.currentTool)
-    parts.push(ctx.currentTool);
-  if (ctx.targetAgent)
-    parts.push(ctx.targetAgent);
-  if (ctx.declaredScope)
-    parts.push(ctx.declaredScope);
-  if (ctx.recentReviewerFailures)
-    parts.push(...ctx.recentReviewerFailures);
-  if (ctx.recentTestFailures)
-    parts.push(...ctx.recentTestFailures);
-  if (ctx.recentToolErrors)
-    parts.push(...ctx.recentToolErrors);
-  if (ctx.planConstraints)
-    parts.push(...ctx.planConstraints);
-  if (ctx.filePaths)
-    parts.push(...ctx.filePaths);
-  return parts.map(lc);
-}
-function scoreDirectiveAgainstContext(entry, ctx) {
-  const haystack = tokenizeContext(ctx);
-  const triggerHit = entry.triggers && entry.triggers.length > 0 ? anyMatch(haystack, entry.triggers) : false;
-  const actionHit = entry.applies_to_tools && entry.applies_to_tools.length > 0 ? entry.applies_to_tools.map(lc).some((t) => t === lc(ctx.currentTool) || t === lc(ctx.currentAction)) : false;
-  const agentHit = entry.applies_to_agents && entry.applies_to_agents.length > 0 ? entry.applies_to_agents.map(lc).some((a) => a === lc(ctx.targetAgent)) : false;
-  let score = 0;
-  if (triggerHit)
-    score += 0.5;
-  if (actionHit)
-    score += 0.35;
-  if (agentHit)
-    score += 0.25;
-  if (entry.directive_priority === "critical")
-    score += 0.4;
-  else if (entry.directive_priority === "high")
-    score += 0.2;
-  else if (entry.directive_priority === "medium")
-    score += 0.1;
-  return { triggerHit, actionHit, agentHit, score: Math.min(1, score) };
+function sanitizeString(value, forbidden) {
+  let result = redactSecrets(value);
+  for (const secret of forbidden) {
+    if (secret.length > 0)
+      result = result.split(secret).join("[redacted]");
+  }
+  if (Buffer.byteLength(result, "utf8") <= MAX_RECEIPT_RESPONSE_BYTES)
+    return result;
+  const suffix = "...[bounded]";
+  const bytes = Buffer.from(result, "utf8");
+  const suffixBytes = Buffer.byteLength(suffix, "utf8");
+  if (MAX_RECEIPT_RESPONSE_BYTES <= suffixBytes) {
+    return bytes.subarray(0, MAX_RECEIPT_RESPONSE_BYTES).toString("utf8");
+  }
+  let low = 0;
+  let high = Math.min(bytes.length, MAX_RECEIPT_RESPONSE_BYTES - suffixBytes);
+  let best = "";
+  while (low <= high) {
+    const middle = Math.floor((low + high) / 2);
+    const candidate = bytes.subarray(0, middle).toString("utf8");
+    if (Buffer.byteLength(candidate, "utf8") <= MAX_RECEIPT_RESPONSE_BYTES - suffixBytes) {
+      best = candidate;
+      low = middle + 1;
+    } else {
+      high = middle - 1;
+    }
+  }
+  const bounded = best + suffix;
+  return Buffer.byteLength(bounded, "utf8") <= MAX_RECEIPT_RESPONSE_BYTES ? bounded : suffix;
 }
-
-// src/hooks/search-knowledge.ts
-init_knowledge_types();
-var TEXT_WEIGHT = 0.6;
-var META_WEIGHT = 0.4;
-var DIRECTIVE_BOOST_MIN_CONFIDENCE = 0.75;
-var SYNONYM_TEXT_BOOST = 0.15;
-var TRIGGER_RECALL_BOOST = 0.3;
-var TRIGGER_RECALL_MIN_LEN = 3;
-var DEFAULT_COLD_START_BONUS = 0.08;
-var DEFAULT_COLD_START_MAX_AGE_PHASES = 3;
-var OUTCOME_RANK_WEIGHT = 0.1;
-function entryText(e) {
-  return `${e.lesson} ${e.tags.join(" ")} ${e.category}`;
+var RECEIPT_RESULT_KEYS = new Set([
+  "success",
+  "error",
+  "quarantined",
+  "id",
+  "reason",
+  "hint",
+  "message",
+  "reinforced",
+  "idempotent",
+  "inactive",
+  "category",
+  "receipt_status",
+  "replayed",
+  "duplicate",
+  "committed",
+  "result"
+]);
+var RECEIPT_RESULT_UNREDACTED_VALUES = new Map([
+  ["category", new Set(KNOWLEDGE_CATEGORIES)]
+]);
+function sanitizeResultValue(value, forbidden, depth = 0, fieldName) {
+  if (depth > 8)
+    return "[depth-limited]";
+  if (typeof value === "string") {
+    const unredactedValues = fieldName ? RECEIPT_RESULT_UNREDACTED_VALUES.get(fieldName) : undefined;
+    if (unredactedValues?.has(value))
+      return value;
+    return sanitizeString(value, forbidden);
+  }
+  if (value === null || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.slice(0, 32).map((item) => sanitizeResultValue(item, forbidden, depth + 1));
+  }
+  if (typeof value === "object" && value !== null) {
+    const record3 = value;
+    const result = Object.create(null);
+    for (const key of Object.keys(record3).slice(0, 64)) {
+      if (!RECEIPT_RESULT_KEYS.has(key))
+        continue;
+      const descriptor = Object.getOwnPropertyDescriptor(record3, key);
+      result[key] = sanitizeResultValue(descriptor && "value" in descriptor ? descriptor.value : undefined, forbidden, depth + 1, key);
+    }
+    return result;
+  }
+  return `[${typeof value}]`;
 }
-function entryAgePhases(e) {
-  const cb = e.confirmed_by;
-  if (!Array.isArray(cb) || cb.length === 0)
-    return 0;
-  const phases = new Set;
-  for (const c of cb) {
-    if (typeof c?.phase_number === "number")
-      phases.add(c.phase_number);
+function collectForbiddenStrings(value, forbidden, depth = 0, nodes = { count: 0 }) {
+  if (nodes.count >= MAX_CANONICAL_NODES || depth > 16)
+    return;
+  nodes.count += 1;
+  if (typeof value === "string") {
+    if (value.length > 0)
+      forbidden.add(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value.slice(0, MAX_CANONICAL_ARRAY_ITEMS)) {
+      collectForbiddenStrings(item, forbidden, depth + 1, nodes);
+    }
+    return;
+  }
+  if (typeof value !== "object" || value === null)
+    return;
+  for (const key of Object.keys(value).slice(0, MAX_CANONICAL_OBJECT_KEYS)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor && "value" in descriptor) {
+      collectForbiddenStrings(descriptor.value, forbidden, depth + 1, nodes);
+    }
   }
-  return phases.size > 0 ? phases.size : cb.length;
 }
-function clampLambda(v) {
-  if (typeof v !== "number" || Number.isNaN(v))
-    return 0.5;
-  return Math.min(1, Math.max(0, v));
+function requestForbiddenStrings(request) {
+  const forbidden = new Set([request.root, request.idempotencyKey]);
+  collectForbiddenStrings(request.arguments, forbidden);
+  return [...forbidden];
 }
-function mmrRerank(pool, pinned, max, lambda) {
-  if (pool.length === 0)
-    return [];
-  const bigrams = new Map;
-  const bg = (e) => {
-    let s = bigrams.get(e.id);
-    if (!s) {
-      s = wordBigrams(normalize(e.lesson ?? ""));
-      bigrams.set(e.id, s);
+function sanitizeReceiptResponse(value, request) {
+  const forbidden = request ? requestForbiddenStrings(request) : [];
+  let parsed = value;
+  if (typeof value === "string") {
+    try {
+      parsed = JSON.parse(value);
+    } catch {
+      return sanitizeString(value, forbidden);
     }
-    return s;
+  }
+  const sanitized = sanitizeResultValue(parsed, forbidden);
+  let encoded;
+  try {
+    encoded = JSON.stringify(sanitized) || "null";
+  } catch {
+    encoded = '{"success":false,"error":"response unavailable"}';
+  }
+  if (Buffer.byteLength(encoded, "utf8") <= MAX_RECEIPT_RESPONSE_BYTES)
+    return encoded;
+  return '{"success":false,"error":"response exceeded receipt bound"}';
+}
+function parseReceiptResponse(response) {
+  try {
+    return JSON.parse(response);
+  } catch {
+    return response;
+  }
+}
+async function readWriteReceiptStatus(root, idempotencyKey) {
+  const request = {
+    root,
+    tool: "knowledge_add",
+    idempotencyKey,
+    arguments: {}
   };
-  const selected = [...pinned];
-  const candidates = [...pool];
-  const out = [];
-  while (selected.length < max && candidates.length > 0) {
-    let bestIdx = -1;
-    let bestScore = Number.NEGATIVE_INFINITY;
-    let best = null;
-    for (let i = 0;i < candidates.length; i++) {
-      const c = candidates[i];
-      let maxSim = 0;
-      for (const s of selected) {
-        const sim = jaccardBigram(bg(c), bg(s));
-        if (sim > maxSim)
-          maxSim = sim;
-      }
-      const score = lambda * c.finalScore - (1 - lambda) * maxSim;
-      if (score > bestScore + 0.000000001 || Math.abs(score - bestScore) <= 0.000000001 && best !== null && tieBreak(c, best) < 0) {
-        bestScore = score;
-        bestIdx = i;
-        best = c;
-      }
+  const identity = computeWriteReceiptIdentity(request);
+  assertReceiptPaths(root);
+  const storage = await readReceiptStorage(root);
+  const records = [...storage.archive, ...storage.active];
+  const record3 = [...records].reverse().find((candidate) => candidate.tool === request.tool && candidate.root_hash === identity.root_hash && candidate.idempotency_hash === identity.idempotency_hash);
+  if (!record3) {
+    return { found: false, status: "NOT_FOUND", retryable: true };
+  }
+  return {
+    found: true,
+    status: record3.state,
+    tool: record3.tool,
+    receipt_id: record3.receipt_id,
+    attempt_id: record3.attempt_id,
+    updated_at: record3.updated_at,
+    lease_expires_at: record3.lease_expires_at,
+    archived: storage.archive.includes(record3),
+    retryable: false
+  };
+}
+async function readJournal(filePath, limits) {
+  let content;
+  let info;
+  try {
+    info = await lstat(filePath);
+  } catch (error) {
+    if (error?.code === "ENOENT")
+      return [];
+    throw new WriteReceiptError("JOURNAL_UNAVAILABLE", "Write receipt journal could not be read");
+  }
+  if (!info.isFile() || info.isSymbolicLink()) {
+    throw new WriteReceiptError("JOURNAL_UNAVAILABLE", "Write receipt journal could not be read");
+  }
+  if (info.size > limits.maxBytes) {
+    throw new WriteReceiptError("JOURNAL_CAPACITY", "Write receipt journal exceeds its bounded capacity");
+  }
+  let handle;
+  try {
+    handle = await open(filePath, "r");
+    const buffer = Buffer.alloc(limits.maxBytes + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const read = await handle.read(buffer, offset, buffer.length - offset, null);
+      if (read.bytesRead === 0)
+        break;
+      offset += read.bytesRead;
     }
-    if (bestIdx < 0 || best === null)
-      break;
-    out.push(best);
-    selected.push(best);
-    candidates.splice(bestIdx, 1);
+    if (offset > limits.maxBytes) {
+      throw new WriteReceiptError("JOURNAL_CAPACITY", "Write receipt journal exceeds its bounded capacity");
+    }
+    content = buffer.subarray(0, offset).toString("utf8");
+  } catch (error) {
+    if (error instanceof WriteReceiptError)
+      throw error;
+    throw new WriteReceiptError("JOURNAL_UNAVAILABLE", "Write receipt journal could not be read");
+  } finally {
+    try {
+      await handle?.close();
+    } catch {}
   }
-  return out;
+  if (content.length > 0 && !content.endsWith(`
+`)) {
+    throw new WriteReceiptError("JOURNAL_CORRUPT", "Write receipt journal has a truncated final record");
+  }
+  const lines = content.split(`
+`);
+  if (lines.length > limits.maxRecords + 1) {
+    throw new WriteReceiptError("JOURNAL_CAPACITY", "Write receipt journal exceeds its bounded record capacity");
+  }
+  const records = [];
+  for (const line of lines) {
+    if (!line)
+      continue;
+    if (Buffer.byteLength(line, "utf8") > MAX_RECEIPT_LINE_BYTES) {
+      throw new WriteReceiptError("JOURNAL_CAPACITY", "Write receipt record exceeds its bounded line size");
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      throw new WriteReceiptError("JOURNAL_CORRUPT", "Write receipt journal contains invalid JSON");
+    }
+    const result = receiptRecordSchema.safeParse(parsed);
+    if (!result.success) {
+      throw new WriteReceiptError("JOURNAL_CORRUPT", "Write receipt journal contains an invalid record");
+    }
+    records.push(result.data);
+  }
+  return records;
 }
-function tieBreak(a, b) {
-  if (Math.abs(a.finalScore - b.finalScore) > 0.000000001)
-    return b.finalScore - a.finalScore;
-  const at = new Date(a.created_at).getTime();
-  const bt = new Date(b.created_at).getTime();
-  if (at !== bt)
-    return bt - at;
-  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+async function readReceiptStorage(root) {
+  const [archive, active] = await Promise.all([
+    readJournal(getWriteReceiptArchivePath(root), {
+      maxBytes: MAX_RECEIPT_ARCHIVE_BYTES,
+      maxRecords: MAX_RECEIPT_ARCHIVE_RECORDS
+    }),
+    readJournal(journalPath(root), {
+      maxBytes: MAX_RECEIPT_JOURNAL_BYTES,
+      maxRecords: MAX_RECEIPT_RECORDS
+    })
+  ]);
+  return { archive, active };
 }
-function statusBoost(status) {
-  if (status === "promoted")
-    return 0.15;
-  if (status === "established")
-    return 0.1;
-  return 0;
+function isUnresolved(record3) {
+  return record3.state === "PREPARED" || record3.state === "IN_DOUBT";
 }
-async function searchKnowledge(params) {
-  const {
-    directory,
-    config,
-    query,
-    context,
-    mode,
-    agent = "unknown",
-    sessionId = "unknown",
-    tier = "all",
-    emitEvent = false,
-    applyScopeFilter = true,
-    forceReadHive = false,
-    applyRoleScope = true,
-    skipLedgerGenesis = false
-  } = params;
-  const traceId = newTraceId();
-  const max = params.maxResults ?? config.max_inject_count ?? 5;
-  let results = [];
-  let synonymTokens = [];
-  const synonymTrace = {};
-  try {
-    const mergeConfig = {
-      ...config,
-      hive_enabled: tier === "swarm" ? false : forceReadHive ? true : config.hive_enabled,
-      max_inject_count: Math.max(20, max)
-    };
-    const projected = {
-      projectName: context?.projectName ?? "unknown",
-      currentPhase: context?.currentPhase ?? "",
-      techStack: context?.techStack,
-      recentErrors: [
-        ...context?.recentReviewerFailures ?? [],
-        ...context?.recentTestFailures ?? [],
-        ...context?.recentToolErrors ?? []
-      ]
-    };
-    let candidates = await readMergedKnowledge(directory, mergeConfig, projected, {
-      skipScopeFilter: !applyScopeFilter
+function serializeReceiptRecords(records, limits) {
+  if (records.length > limits.maxRecords) {
+    throw new WriteReceiptError("JOURNAL_CAPACITY", "Write receipt journal exceeds its bounded record capacity");
+  }
+  const lines = records.map((item) => JSON.stringify(item));
+  for (const line of lines) {
+    if (Buffer.byteLength(line, "utf8") > MAX_RECEIPT_LINE_BYTES) {
+      throw new WriteReceiptError("JOURNAL_CAPACITY", "Write receipt record exceeds its bounded line size");
+    }
+  }
+  const content = lines.join(`
+`) + (lines.length > 0 ? `
+` : "");
+  if (Buffer.byteLength(content, "utf8") > limits.maxBytes) {
+    throw new WriteReceiptError("JOURNAL_CAPACITY", "Write receipt journal exceeds its bounded byte capacity");
+  }
+  return content;
+}
+async function writeReceiptStorage(root, records, hooks) {
+  const latestByAttempt = new Map;
+  for (const record3 of records)
+    latestByAttempt.set(record3.attempt_id, record3);
+  const unresolved = records.filter((record3) => isUnresolved(record3) && latestByAttempt.get(record3.attempt_id) === record3);
+  const terminal = records.filter((record3) => !unresolved.includes(record3));
+  const activeTerminalCount = Math.max(0, MAX_RECEIPT_RECORDS - unresolved.length);
+  const activeRecords = new Set([
+    ...unresolved,
+    ...terminal.slice(-activeTerminalCount)
+  ]);
+  const active = records.filter((record3) => activeRecords.has(record3));
+  const archive = records.filter((record3) => !activeRecords.has(record3));
+  const activeContent = serializeReceiptRecords(active, {
+    maxBytes: MAX_RECEIPT_JOURNAL_BYTES,
+    maxRecords: MAX_RECEIPT_RECORDS
+  });
+  const archiveContent = serializeReceiptRecords(archive, {
+    maxBytes: MAX_RECEIPT_ARCHIVE_BYTES,
+    maxRecords: MAX_RECEIPT_ARCHIVE_RECORDS
+  });
+  if (archive.length > 0 || archiveContent.length > 0) {
+    await hooks?.persistStorage?.("archive", archive);
+    await atomicWriteSwarmFile(getWriteReceiptArchivePath(root), archiveContent, {
+      maxBytes: MAX_RECEIPT_ARCHIVE_BYTES
     });
-    const journalPath = path.join(directory, ".swarm", "knowledge-receipts-v2.jsonl");
-    const journalReadable = existsSync(journalPath) && statSync(journalPath).size > 0;
-    const counterRollups = skipLedgerGenesis && !journalReadable ? new Map : await readAuthoritativeKnowledgeCounterRollups(directory);
-    candidates = candidates.filter((e) => {
-      if (!isActiveStatus(e.status))
-        return false;
-      if (tier === "hive" && e.tier !== "hive")
-        return false;
-      return true;
+  }
+  try {
+    await hooks?.persistStorage?.("active", active);
+    await atomicWriteSwarmFile(journalPath(root), activeContent, {
+      maxBytes: MAX_RECEIPT_JOURNAL_BYTES
     });
-    const role = stripKnownSwarmPrefix(agent).toLowerCase();
-    if (applyRoleScope && role && role !== "unknown") {
-      candidates = candidates.filter((e) => {
-        if (!e.applies_to_agents || e.applies_to_agents.length === 0)
-          return true;
-        if (role === "architect")
-          return true;
-        return e.applies_to_agents.map((a) => stripKnownSwarmPrefix(a).toLowerCase()).includes(role);
-      });
-    }
-    const queryText = (query ?? "").trim();
-    const queryBigrams = queryText ? wordBigrams(normalize(queryText)) : null;
-    const hasQuery = queryBigrams !== null;
-    const textWeight = hasQuery ? TEXT_WEIGHT : 0;
-    const metaWeight = hasQuery ? META_WEIGHT : 1;
-    const compositeRaw = [
-      queryText,
-      context?.taskTitle,
-      context?.taskDescription,
-      context?.lastUserMessage,
-      context?.currentAction,
-      ...context?.recentReviewerFailures ?? [],
-      ...context?.recentTestFailures ?? [],
-      ...context?.recentToolErrors ?? []
-    ].filter((s) => typeof s === "string" && s.length > 0).join(" ");
-    const compositeNorm = normalize(compositeRaw);
-    const hasComposite = compositeNorm.length > 0;
-    try {
-      if (hasComposite) {
-        const synMap = await readSynonymMap(directory, config.retrieval?.synonym_map_max_pairs);
-        const synIndex = buildSynonymIndex(synMap, config.retrieval?.synonym_min_cooccurrence);
-        const baseTokens = compositeNorm.split(" ").filter(Boolean);
-        synonymTokens = expandTokens(synIndex, baseTokens);
+  } catch (error) {
+    if (unresolved.length > 0) {
+      const recoveryByReceipt = new Map(archive.map((record3) => [record3.receipt_id, record3]));
+      for (const record3 of unresolved) {
+        recoveryByReceipt.set(record3.receipt_id, record3);
       }
-    } catch {
-      synonymTokens = [];
+      try {
+        const recoveryArchiveContent = serializeReceiptRecords([...recoveryByReceipt.values()], {
+          maxBytes: MAX_RECEIPT_ARCHIVE_BYTES,
+          maxRecords: MAX_RECEIPT_ARCHIVE_RECORDS
+        });
+        await atomicWriteSwarmFile(getWriteReceiptArchivePath(root), recoveryArchiveContent, { maxBytes: MAX_RECEIPT_ARCHIVE_BYTES });
+      } catch {}
     }
-    const minConf = typeof config.directive_min_confidence === "number" ? config.directive_min_confidence : DIRECTIVE_BOOST_MIN_CONFIDENCE;
-    const scored = candidates.map((entry) => {
-      const retrievalOutcomes = effectiveRetrievalOutcomes(entry.retrieval_outcomes, counterRollups.get(entry.id));
-      const textScore = queryBigrams ? jaccardBigram(queryBigrams, wordBigrams(normalize(entryText(entry)))) : 0;
-      const metaScore = entry.finalScore;
-      const ds = context ? scoreDirectiveAgainstContext(entry, context) : { triggerHit: false, actionHit: false, agentHit: false, score: 0 };
-      const confBoost = context && entry.confidence >= minConf && (ds.actionHit || ds.agentHit) ? 0.25 : 0;
-      const generatedSkillBoost = entry.generated_skill_path && entry.status !== "archived" ? 0.05 : 0;
-      const outcomeBoost = computeOutcomeSignal(retrievalOutcomes) * OUTCOME_RANK_WEIGHT;
-      const coldStartBonus = (retrievalOutcomes.applied_explicit_count ?? 0) === 0 && entryAgePhases(entry) < (config.retrieval?.cold_start_max_age_phases ?? DEFAULT_COLD_START_MAX_AGE_PHASES) ? config.retrieval?.cold_start_bonus ?? DEFAULT_COLD_START_BONUS : 0;
-      let synonymBoost = 0;
-      if (synonymTokens.length > 0) {
-        const entryHay = normalize(entryText(entry));
-        const matched = [];
-        for (const t of synonymTokens) {
-          if (t.length > 0 && entryHay.includes(t))
-            matched.push(t);
-        }
-        if (matched.length > 0) {
-          synonymBoost = SYNONYM_TEXT_BOOST;
-          synonymTrace[entry.id] = matched;
-        }
+    throw error;
+  }
+}
+function nowFrom(hooks) {
+  const value = hooks?.now ? hooks.now() : Date.now();
+  return Number.isFinite(value) && value >= 0 ? value : Date.now();
+}
+function responseForRecord(record3) {
+  return record3.response === undefined ? {
+    success: false,
+    error: record3.error || "write receipt is unresolved"
+  } : parseReceiptResponse(record3.response);
+}
+function addReplayMarker(value) {
+  const marker = {
+    receipt_status: "replayed",
+    replayed: true,
+    duplicate: true,
+    committed: true
+  };
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return {
+      ...value,
+      ...marker
+    };
+  }
+  return {
+    result: value,
+    ...marker
+  };
+}
+function copyRecord(record3) {
+  return { ...record3 };
+}
+async function withReceiptLock(root, fn, hooks) {
+  assertReceiptPaths(root);
+  const lockResult = await tryAcquireLock(root, "mcp-write-receipts.jsonl", "mcp-write-receipts", "mcp-write-receipts");
+  if (!lockResult.acquired) {
+    throw new WriteReceiptError("JOURNAL_UNAVAILABLE", "Write receipt journal is busy; no write was attempted");
+  }
+  try {
+    assertReceiptPaths(root);
+    const storage = await readReceiptStorage(root);
+    const records = [...storage.archive, ...storage.active];
+    const result = await fn(records);
+    if (result.changed) {
+      await writeReceiptStorage(root, result.records, hooks);
+    }
+    return result.value;
+  } finally {
+    try {
+      await lockResult.lock._release?.();
+    } catch {}
+  }
+}
+async function prepareReceipt(request, hooks) {
+  const identity = computeWriteReceiptIdentity(request);
+  const timestamp = nowFrom(hooks);
+  const attempt = {
+    version: 1,
+    receipt_id: randomUUID2(),
+    attempt_id: randomUUID2(),
+    tool: request.tool,
+    ...identity,
+    state: "PREPARED",
+    prepared_at: timestamp,
+    updated_at: timestamp,
+    lease_expires_at: timestamp + PREPARED_LEASE_MS
+  };
+  try {
+    return await withReceiptLock(request.root, async (records) => {
+      const decision = {
+        current: undefined
+      };
+      const nextRecords = (() => {
+        const sameKey = records.filter((record3) => record3.root_hash === identity.root_hash && record3.idempotency_hash === identity.idempotency_hash);
+        const sameRequest = sameKey.filter((record3) => record3.tool === request.tool && record3.arguments_digest === identity.arguments_digest && record3.policy_digest === identity.policy_digest);
+        const latest = sameRequest.at(-1);
+        const unresolved = latest && isUnresolved(latest) ? latest : undefined;
+        if (unresolved) {
+          if (unresolved.state === "PREPARED" && timestamp >= unresolved.lease_expires_at) {
+            const inDoubt = {
+              ...unresolved,
+              state: "IN_DOUBT",
+              updated_at: timestamp,
+              error: "previous attempt expired before settlement"
+            };
+            decision.current = {
+              kind: "in_doubt",
+              receipt: copyRecord(inDoubt)
+            };
+            return [...records, inDoubt];
+          }
+          decision.current = unresolved.state === "PREPARED" ? { kind: "in_progress", receipt: copyRecord(unresolved) } : { kind: "in_doubt", receipt: copyRecord(unresolved) };
+          return records;
+        }
+        const exact = [...sameRequest].reverse().find((record3) => !isUnresolved(record3));
+        if (exact) {
+          decision.current = {
+            kind: "replay",
+            receipt: copyRecord(exact),
+            response: responseForRecord(exact)
+          };
+          return records;
+        }
+        if (sameKey.length > 0) {
+          const conflict = {
+            ...attempt,
+            state: "FAILED_NO_EFFECT",
+            updated_at: timestamp,
+            lease_expires_at: timestamp,
+            response: sanitizeReceiptResponse({ success: false, error: "idempotency key conflict" }, request),
+            error: "idempotency key conflict"
+          };
+          decision.current = {
+            kind: "conflict",
+            receipt: copyRecord(conflict),
+            response: responseForRecord(conflict)
+          };
+          return [...records, conflict];
+        }
+        decision.current = { kind: "prepared", receipt: copyRecord(attempt) };
+        return [...records, attempt];
+      })();
+      if (!decision.current) {
+        throw new WriteReceiptError("TRANSITION_REJECTED", "Write receipt preparation produced no decision");
+      }
+      const changed = nextRecords !== records;
+      if (changed && hooks && hooks.persistReceipt && (decision.current.kind === "prepared" || decision.current.kind === "in_doubt" || decision.current.kind === "conflict")) {
+        await hooks.persistReceipt(decision.current.receipt);
+      }
+      return { value: decision.current, records: nextRecords, changed };
+    }, hooks);
+  } catch (error) {
+    if (error instanceof WriteReceiptError)
+      throw error;
+    throw new WriteReceiptError("JOURNAL_UNAVAILABLE", "Write receipt journal could not be prepared");
+  }
+}
+function sameAttempt(record3, attempt) {
+  return record3.attempt_id === attempt.attempt_id && record3.tool === attempt.tool && record3.root_hash === attempt.root_hash && record3.idempotency_hash === attempt.idempotency_hash && record3.arguments_digest === attempt.arguments_digest && record3.policy_digest === attempt.policy_digest;
+}
+async function transitionReceipt(request, attempt, state, options) {
+  const timestamp = nowFrom(options.hooks);
+  const nextRecord = {
+    ...attempt,
+    state,
+    updated_at: timestamp,
+    lease_expires_at: state === "PREPARED" ? timestamp + PREPARED_LEASE_MS : attempt.lease_expires_at,
+    ...options.response === undefined ? state === "COMMITTED" ? { response: sanitizeReceiptResponse(undefined, request) } : {} : {
+      response: sanitizeReceiptResponse(options.response, request)
+    },
+    ...options.error === undefined ? {} : {
+      error: sanitizeString(options.error, requestForbiddenStrings(request))
+    }
+  };
+  const value = await withReceiptLock(request.root, async (records) => {
+    const current = [...records].reverse().find((record3) => sameAttempt(record3, attempt));
+    if (!current) {
+      throw new WriteReceiptError("TRANSITION_REJECTED", "Write receipt attempt no longer exists");
+    }
+    if (current.state === "COMMITTED") {
+      return { value: current, records, changed: false };
+    }
+    if (current.state === "IN_DOUBT" && state !== "COMMITTED" && state !== "IN_DOUBT") {
+      return { value: current, records, changed: false };
+    }
+    if (current.state === "IN_DOUBT" && state === "COMMITTED") {
+      if (options.hooks?.persistReceipt) {
+        await options.hooks.persistReceipt(nextRecord);
       }
-      const triggerRecallHit = !ds.triggerHit && hasComposite && Array.isArray(entry.triggers) && entry.triggers.some((tr) => {
-        const n = normalize(tr);
-        return n.length >= TRIGGER_RECALL_MIN_LEN && compositeNorm.includes(n);
-      });
-      const triggerRecallBoost = triggerRecallHit ? TRIGGER_RECALL_BOOST : 0;
-      const finalScore = Math.min(1, Math.max(0, textWeight * textScore + metaWeight * metaScore + ds.score + confBoost + generatedSkillBoost + outcomeBoost + coldStartBonus + synonymBoost + triggerRecallBoost + (hasQuery && !entry.confidence_floor_demoted ? statusBoost(entry.status) : 0)));
-      const statusScoreBoost = hasQuery && !entry.confidence_floor_demoted ? statusBoost(entry.status) : 0;
-      const isCritical = entry.directive_priority === "critical" && (ds.triggerHit || ds.actionHit || ds.agentHit);
-      const isForceHive = forceReadHive && entry.tier === "hive";
       return {
-        ...entry,
-        retrieval_outcomes: retrievalOutcomes,
-        finalScore,
-        coldStartBoost: coldStartBonus,
-        score_breakdown: {
-          text_score: textScore,
-          metadata_score: metaScore,
-          directive_score: ds.score,
-          confidence_boost: confBoost,
-          generated_skill_boost: generatedSkillBoost,
-          outcome_boost: outcomeBoost,
-          cold_start_boost: coldStartBonus,
-          synonym_boost: synonymBoost,
-          trigger_recall_boost: triggerRecallBoost,
-          status_boost: statusScoreBoost,
-          final_score: finalScore,
-          ...synonymTrace[entry.id] ? { synonym_matches: synonymTrace[entry.id] } : {}
-        },
-        __critical: isCritical,
-        __forceHive: isForceHive
+        value: nextRecord,
+        records: [...records, nextRecord],
+        changed: true
       };
-    });
-    scored.sort((a, b) => {
-      const diff = b.finalScore - a.finalScore;
-      if (Math.abs(diff) > 0.001)
-        return diff;
-      return new Date(b.created_at).getTime() - new Date(a.created_at).getTime();
-    });
-    const top = [];
-    const seen = new Set;
-    for (const e of scored) {
-      if (top.length >= max)
-        break;
-      if (e.__critical && !seen.has(e.id)) {
-        top.push(e);
-        seen.add(e.id);
-      }
     }
-    for (const e of scored) {
-      if (top.length >= max)
-        break;
-      if (e.__forceHive && !seen.has(e.id)) {
-        top.push(e);
-        seen.add(e.id);
-      }
+    if (current.state !== "PREPARED") {
+      return { value: current, records, changed: false };
     }
-    const lambda = clampLambda(config.retrieval?.mmr_lambda);
-    const remaining = scored.filter((e) => !seen.has(e.id));
-    const selected = mmrRerank(remaining, top, max, lambda);
-    for (const e of selected) {
-      if (top.length >= max)
-        break;
-      if (!seen.has(e.id)) {
-        top.push(e);
-        seen.add(e.id);
+    if (options.hooks?.persistReceipt) {
+      await options.hooks.persistReceipt(nextRecord);
+    }
+    return {
+      value: nextRecord,
+      records: [...records, nextRecord],
+      changed: true
+    };
+  }, options.hooks);
+  return value;
+}
+async function commitReceipt(request, attempt, response, hooks) {
+  return transitionReceipt(request, attempt, "COMMITTED", {
+    response,
+    hooks
+  });
+}
+async function markInDoubt(request, attempt, error, hooks) {
+  return transitionReceipt(request, attempt, "IN_DOUBT", { error, hooks });
+}
+async function executeWithReceipt(request, operation, hooks) {
+  const prepared = await prepareReceipt(request, hooks);
+  if (prepared.kind === "conflict") {
+    throw new WriteReceiptError("TRANSITION_REJECTED", "idempotency key conflict; no write was attempted");
+  }
+  if (prepared.kind === "replay") {
+    if (prepared.receipt.state === "FAILED_NO_EFFECT") {
+      throw new WriteReceiptError("TRANSITION_REJECTED", "idempotency key conflict; no write was attempted");
+    }
+    return addReplayMarker(prepared.response);
+  }
+  if (prepared.kind === "in_progress") {
+    throw new WriteReceiptError("TRANSITION_REJECTED", "write already in progress; retry after the original attempt settles");
+  }
+  if (prepared.kind === "in_doubt") {
+    throw new WriteReceiptError("TRANSITION_REJECTED", "write is IN_DOUBT and will not be retried automatically");
+  }
+  const attempt = prepared.receipt;
+  try {
+    if (hooks?.afterPrepare) {
+      await hooks.afterPrepare(copyRecord(attempt));
+    }
+  } catch {
+    throw new WriteReceiptError("TRANSITION_REJECTED", "write interrupted after durable preparation");
+  }
+  let result;
+  try {
+    result = await operation();
+  } catch (error) {
+    try {
+      await markInDoubt(request, attempt, error instanceof Error ? error.message : "production write failed");
+    } catch {}
+    throw new WriteReceiptError("TRANSITION_REJECTED", "write outcome is IN_DOUBT and must not be retried automatically");
+  }
+  try {
+    if (hooks?.afterMutation) {
+      await hooks.afterMutation(copyRecord(attempt));
+    }
+  } catch {
+    try {
+      await markInDoubt(request, attempt, "write completed but settlement was interrupted", hooks);
+    } catch {}
+    throw new WriteReceiptError("TRANSITION_REJECTED", "write outcome is IN_DOUBT and must not be retried automatically");
+  }
+  try {
+    await commitReceipt(request, attempt, result, hooks);
+  } catch {
+    try {
+      await markInDoubt(request, attempt, "write completed but final receipt persistence failed");
+    } catch {}
+    throw new WriteReceiptError("TRANSITION_REJECTED", "write outcome is IN_DOUBT and must not be retried automatically");
+  }
+  return result;
+}
+var KNOWLEDGE_ARRAY_FIELDS = [
+  "tags",
+  "applies_to_agents",
+  "applies_to_tools",
+  "required_actions",
+  "forbidden_actions",
+  "verification_checks"
+];
+function assertBoundedKnowledgeAddInput(rawArgs) {
+  if (!rawArgs || typeof rawArgs !== "object" || Array.isArray(rawArgs))
+    return;
+  const record3 = rawArgs;
+  for (const field of KNOWLEDGE_ARRAY_FIELDS) {
+    const descriptor = Object.getOwnPropertyDescriptor(record3, field);
+    const value = descriptor && "value" in descriptor ? descriptor.value : undefined;
+    if (value === undefined)
+      continue;
+    if (!Array.isArray(value) || value.length > MAX_KNOWLEDGE_ARRAY_ITEMS) {
+      throw new WriteReceiptError("INVALID_REQUEST", "knowledge_add array fields exceed their bounded capacity");
+    }
+    for (const item of value) {
+      if (typeof item !== "string" || item.length > MAX_KNOWLEDGE_OPTIONAL_TEXT_LENGTH) {
+        throw new WriteReceiptError("INVALID_REQUEST", "knowledge_add array values are invalid or too long");
       }
     }
-    results = top.map(({ __critical: _c, __forceHive: _f, ...rest }) => rest);
-  } catch (err) {
-    warn(`[search-knowledge] retrieval failed: ${err instanceof Error ? err.message : String(err)}`);
-    results = [];
   }
-  if (emitEvent) {
-    const ranks = {};
-    const scores = {};
-    results.forEach((e, idx) => {
-      ranks[e.id] = idx + 1;
-      scores[e.id] = e.finalScore;
-    });
-    const synonymBreakdown = {};
-    for (const e of results) {
-      if (synonymTrace[e.id])
-        synonymBreakdown[e.id] = synonymTrace[e.id];
+  for (const field of ["idempotency_key", "lesson", "scope"]) {
+    const descriptor = Object.getOwnPropertyDescriptor(record3, field);
+    const value = descriptor && "value" in descriptor ? descriptor.value : undefined;
+    if (value === undefined)
+      continue;
+    const max = field === "idempotency_key" ? MAX_IDEMPOTENCY_KEY_LENGTH : field === "lesson" ? MAX_KNOWLEDGE_TEXT_LENGTH : MAX_KNOWLEDGE_OPTIONAL_TEXT_LENGTH;
+    if (typeof value !== "string" || value.length > max) {
+      throw new WriteReceiptError("INVALID_REQUEST", "knowledge_add string fields are invalid or too long");
     }
-    const scoreBreakdown = synonymTokens.length > 0 ? {
-      synonyms_expanded: synonymTokens,
-      synonym_matches: synonymBreakdown
-    } : undefined;
-    await recordKnowledgeEvent(directory, {
-      type: "retrieved",
-      trace_id: traceId,
-      session_id: sessionId,
-      phase: context?.currentPhase,
-      task_id: context?.taskId,
-      agent,
-      query: query ?? context?.lastUserMessage ?? context?.currentPhase ?? "",
-      retrieval_mode: mode,
-      result_ids: results.map((e) => e.id),
-      ranks,
-      scores,
-      ...scoreBreakdown ? { score_breakdown: scoreBreakdown } : {}
-    });
   }
-  return { trace_id: traceId, results };
+}
+var boundedKnowledgeText = exports_external.string().max(MAX_KNOWLEDGE_OPTIONAL_TEXT_LENGTH);
+var knowledgeAddInput = exports_external.object({
+  idempotency_key: exports_external.string().min(1).max(MAX_IDEMPOTENCY_KEY_LENGTH).refine((value) => !hasControlCharacters(value), {
+    message: "idempotency_key must not contain ASCII control characters"
+  }),
+  lesson: exports_external.string().min(15).max(MAX_KNOWLEDGE_TEXT_LENGTH),
+  category: exports_external.enum(KNOWLEDGE_CATEGORIES),
+  tags: exports_external.array(boundedKnowledgeText).max(MAX_KNOWLEDGE_ARRAY_ITEMS).optional(),
+  scope: boundedKnowledgeText.optional(),
+  applies_to_agents: exports_external.array(boundedKnowledgeText).max(MAX_KNOWLEDGE_ARRAY_ITEMS).optional(),
+  applies_to_tools: exports_external.array(boundedKnowledgeText).max(MAX_KNOWLEDGE_ARRAY_ITEMS).optional(),
+  required_actions: exports_external.array(boundedKnowledgeText).max(MAX_KNOWLEDGE_ARRAY_ITEMS).optional(),
+  forbidden_actions: exports_external.array(boundedKnowledgeText).max(MAX_KNOWLEDGE_ARRAY_ITEMS).optional(),
+  verification_checks: exports_external.array(boundedKnowledgeText).max(MAX_KNOWLEDGE_ARRAY_ITEMS).optional()
+}).strict();
+function buildKnowledgeAddRequest(root, rawArgs, runtime) {
+  assertBoundedKnowledgeAddInput(rawArgs);
+  const args = knowledgeAddInput.parse(rawArgs);
+  const idempotencyKey = args.idempotency_key;
+  const productionArgs = {
+    ...args,
+    scope: args.scope ?? "global"
+  };
+  delete productionArgs.idempotency_key;
+  return {
+    request: {
+      root,
+      tool: "knowledge_add",
+      idempotencyKey,
+      arguments: productionArgs,
+      policy: runtime?.policy ?? KNOWLEDGE_ADD_POLICY_VERSION
+    },
+    productionArgs
+  };
 }
 
-// src/tools/swarm-memory-recall.ts
-init_zod();
-var MEMORY_KINDS = [
-  "user_preference",
-  "project_fact",
-  "architecture_decision",
-  "repo_convention",
-  "api_finding",
-  "code_pattern",
-  "test_pattern",
-  "failure_pattern",
-  "security_note",
-  "evidence",
-  "todo",
-  "scratch"
-];
-var swarm_memory_recall = createSwarmTool({
-  description: "Recall scoped Swarm memory for the current repository. Read-only; retrieved memory is untrusted background.",
-  args: {
-    query: exports_external.string().min(3).describe("Natural language recall query"),
-    kinds: exports_external.array(exports_external.enum(MEMORY_KINDS)).optional().describe("Optional memory kinds to include"),
-    maxItems: exports_external.number().int().min(1).max(20).optional().describe("Maximum memories to return")
-  },
-  execute: async (args, directory, ctx) => computeSwarmMemoryRecall(args, directory, ctx)
-});
-async function computeSwarmMemoryRecall(args, directory, ctx, options) {
-  const { config } = _internals2.loadPluginConfigWithMeta(directory);
-  if (config.memory?.enabled !== true) {
-    return JSON.stringify({
-      success: false,
-      disabled: true,
-      message: "Swarm memory is disabled. Set swarm.memory.enabled=true."
-    });
-  }
-  const parsed = RecallArgsSchema.safeParse(args);
-  if (!parsed.success) {
-    return JSON.stringify({
-      success: false,
-      error: parsed.error.issues.map((issue) => issue.message).join("; ")
-    });
-  }
-  const agent = getContextAgent(ctx);
-  const unitId = ctx?.sessionID ? _internals2.getAgentSession(ctx.sessionID)?.currentTaskId ?? undefined : undefined;
-  const gateway = _internals2.createMemoryGateway({
-    directory,
-    sessionID: ctx?.sessionID,
-    agentRole: agent,
-    agentId: agent,
-    runId: ctx?.sessionID,
-    unitId
-  }, {
-    config: config.memory
-  });
-  try {
-    const bundle = await gateway.recall(parsed.data, {
-      recordUsage: options?.recordUsage !== false
-    });
-    return JSON.stringify({
-      success: true,
-      bundle_id: bundle.id,
-      memory_ids: bundle.items.map((item) => item.record.id),
-      total: bundle.items.length,
-      token_estimate: bundle.tokenEstimate,
-      signals: bundle.items.map((item) => ({
-        memory_id: item.record.id,
-        relation: item.relation,
-        ...item.signals
-      })),
-      prompt_block: bundle.promptBlock
-    }, null, 2);
-  } finally {
-    await gateway.dispose();
-  }
-}
-var RecallArgsSchema = exports_external.object({
-  query: exports_external.string().min(3),
-  kinds: exports_external.array(exports_external.enum(MEMORY_KINDS)).optional(),
-  maxItems: exports_external.number().int().min(1).max(20).optional()
-});
-var _internals2 = {
-  loadPluginConfigWithMeta,
-  createMemoryGateway,
-  getAgentSession
-};
-function getContextAgent(ctx) {
-  if (!ctx || typeof ctx !== "object")
-    return;
-  const value = ctx.agent;
-  return typeof value === "string" ? value : undefined;
-}
-
-// src/mcp/adapters/verification.ts
+// src/mcp/adapters/verification.ts
 init_zod();
 
 // src/tools/evidence-check.ts
@@ -17035,7 +17532,7 @@ async function computePlaceholderScan(input, directory, gateOverrides, options)
   const addedLinesFiles = addedLinesValues.filter((lines) => (lines instanceof Set ? lines.size : lines.length) > 0).length;
   const addedLinesTotal = addedLinesValues.reduce((sum, lines) => sum + (lines instanceof Set ? lines.size : lines.length), 0);
   if (options?.persistEvidence === true) {
-    await _internals3.saveEvidence(directory, "placeholder_scan", {
+    await _internals2.saveEvidence(directory, "placeholder_scan", {
       task_id: "placeholder_scan",
       type: "placeholder",
       timestamp: new Date().toISOString(),
@@ -17075,11 +17572,11 @@ var placeholder_scan = createSwarmTool({
     allow_sentinels: exports_external.array(exports_external.string()).optional().describe("Deprecated alias for sentinel_allowlist")
   },
   async execute(args, directory) {
-    const result = await placeholderScan(args, directory, _internals3.loadGateOverrides(directory)?.placeholder_scan);
+    const result = await placeholderScan(args, directory, _internals2.loadGateOverrides(directory)?.placeholder_scan);
     return JSON.stringify(result);
   }
 });
-var _internals3 = {
+var _internals2 = {
   collectNonStubBodyLines,
   isStubSkeletonFunction,
   isConstantLiteralNode,
@@ -17091,7 +17588,7 @@ var _internals3 = {
 import * as fs3 from "fs";
 import * as path4 from "path";
 init_zod();
-var _internals4 = {
+var _internals3 = {
   loadGateOverrides
 };
 var MAX_FILE_SIZE2 = 2 * 1024 * 1024;
@@ -17282,113 +17779,732 @@ async function computeSyntaxCheck(input, directory, gates, options) {
       files: results
     });
   }
-  return {
-    verdict,
-    files: results,
-    summary
-  };
+  return {
+    verdict,
+    files: results,
+    summary
+  };
+}
+var syntax_check = createSwarmTool({
+  allowWorkingDirectoryOverride: true,
+  description: "Check syntax of source files using tree-sitter parsers. Supports JS/TS, Python, Go, Rust, Java, C/C++, C#, PHP, Ruby. Returns JSON with syntax errors found per file.",
+  args: {
+    changed_files: exports_external.array(exports_external.object({
+      path: exports_external.string(),
+      additions: exports_external.number()
+    })).describe("Files to check (from diff gate)"),
+    mode: exports_external.enum(["changed", "all"]).optional().describe("Check mode over the supplied changed_files. 'changed' (default) checks only entries with additions > 0, so deletion-only and pure-rename entries are excluded; 'all' checks every supplied entry. Neither mode enumerates the repository \u2014 this tool only ever inspects the files you pass in changed_files. If the filters leave nothing to check the verdict is 'skip', never 'pass'."),
+    languages: exports_external.array(exports_external.string()).optional().describe("Optional: restrict to specific languages")
+  },
+  async execute(args, directory) {
+    const gates = _internals3.loadGateOverrides(directory);
+    const result = await syntaxCheck(args, directory, gates);
+    return JSON.stringify(result);
+  }
+});
+
+// src/mcp/adapters/verification.ts
+function mcpToolContext(root) {
+  return { directory: root };
+}
+function safeParseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+var syntaxCheckSchema = exports_external.object({
+  changed_files: exports_external.array(exports_external.object({
+    path: exports_external.string().describe("Repository-relative file path"),
+    additions: exports_external.number().describe("Added line count from the diff")
+  })).describe("Files to check (from diff gate)"),
+  mode: exports_external.enum(["changed", "all"]).optional().describe("Check mode: 'changed' checks only additions > 0 entries; 'all' checks every entry"),
+  languages: exports_external.array(exports_external.string()).optional().describe("Restrict to specific languages")
+});
+var placeholderScanSchema = exports_external.object({
+  changed_files: exports_external.array(exports_external.string()).describe("Repository-relative file paths to scan")
+});
+var sastScanSchema = exports_external.object({
+  changed_files: exports_external.array(exports_external.string()).describe("Repository-relative file paths to scan"),
+  severity_threshold: exports_external.enum(["low", "medium", "high", "critical"]).optional().describe("Minimum severity to report (default: medium)")
+});
+var qualityBudgetSchema = exports_external.object({
+  changed_files: exports_external.array(exports_external.string()).describe("Repository-relative file paths to analyze")
+});
+var evidenceCheckSchema = exports_external.object({
+  required_types: exports_external.string().optional().describe('Comma-separated evidence types required per task (default: "reviewer,test_engineer")')
+});
+var syntaxCheckAdapter = {
+  name: "syntax_check",
+  kind: "read",
+  pathFields: ["changed_files"],
+  inputSchema: syntaxCheckSchema,
+  execute: (rawArgs, root) => computeSyntaxCheck(syntaxCheckSchema.parse(rawArgs), root)
+};
+var placeholderScanAdapter = {
+  name: "placeholder_scan",
+  kind: "read",
+  pathFields: ["changed_files"],
+  inputSchema: placeholderScanSchema,
+  execute: (rawArgs, root) => computePlaceholderScan({ changed_files: placeholderScanSchema.parse(rawArgs).changed_files }, root)
+};
+var sastScanAdapter = {
+  name: "sast_scan",
+  kind: "read",
+  pathFields: ["changed_files"],
+  inputSchema: sastScanSchema,
+  execute: (rawArgs, root) => {
+    const args = sastScanSchema.parse(rawArgs);
+    return computeSastScan({
+      changed_files: args.changed_files,
+      severity_threshold: args.severity_threshold,
+      offline_only: true
+    }, root);
+  }
+};
+var qualityBudgetAdapter = {
+  name: "quality_budget",
+  kind: "read",
+  pathFields: ["changed_files"],
+  inputSchema: qualityBudgetSchema,
+  execute: (rawArgs, root) => computeQualityBudget({ changed_files: qualityBudgetSchema.parse(rawArgs).changed_files }, root)
+};
+var evidenceCheckAdapter = {
+  name: "evidence_check",
+  kind: "read",
+  pathFields: [],
+  inputSchema: evidenceCheckSchema,
+  execute: async (rawArgs, root) => {
+    const args = evidenceCheckSchema.parse(rawArgs);
+    const result = await evidence_check.execute(args, mcpToolContext(root));
+    return typeof result === "string" ? safeParseJson(result) : result;
+  }
+};
+
+// src/mcp/adapters/knowledge-add.ts
+async function executeKnowledgeAdd(rawArgs, root, runtime) {
+  const { request, productionArgs } = buildKnowledgeAddRequest(root, rawArgs, runtime);
+  return executeWithReceipt(request, async () => {
+    const result = await knowledge_add.execute(productionArgs, mcpToolContext(root));
+    return typeof result === "string" ? safeParseJson(result) : result;
+  }, runtime?.hooks);
+}
+var knowledgeAddAdapter = {
+  name: "knowledge_add",
+  kind: "write",
+  pathFields: [],
+  inputSchema: knowledgeAddInput,
+  execute: executeKnowledgeAdd
+};
+
+// src/mcp/adapters/knowledge-memory.ts
+init_zod();
+import { existsSync as existsSync4 } from "fs";
+import path6 from "path";
+init_schema();
+
+// src/hooks/search-knowledge.ts
+init_schema();
+import { existsSync as existsSync3, statSync as statSync4 } from "fs";
+import path5 from "path";
+init_logger();
+
+// src/hooks/knowledge-reader.ts
+init_logger();
+init_knowledge_types();
+var JACCARD_THRESHOLD = 0.6;
+var HIVE_TIER_BOOST = 0.05;
+var DEFAULT_SAME_PROJECT_PENALTY = -0.05;
+function inferCategoriesFromPhase(phaseDescription) {
+  const lower = phaseDescription.toLowerCase();
+  const patterns = [
+    {
+      pattern: /\b(?:test|qa|quality|verification|validation)\b/,
+      categories: ["testing", "debugging"]
+    },
+    {
+      pattern: /\b(?:implement|build|develop|coding|code)\b/,
+      categories: ["tooling", "architecture", "debugging"]
+    },
+    {
+      pattern: /\b(?:integrat|deploy|ci|cd|release|publish)\b/,
+      categories: ["integration", "tooling", "performance"]
+    },
+    {
+      pattern: /\b(?:plan|design|architect|spec|requirement)\b/,
+      categories: ["architecture", "process"]
+    },
+    {
+      pattern: /\b(?:review|refactor|cleanup|polish|optimi)\b/,
+      categories: ["performance", "architecture", "process"]
+    },
+    {
+      pattern: /\b(?:secur|audit|harden|compliance)\b/,
+      categories: ["security", "testing"]
+    },
+    {
+      pattern: /\b(?:setup|config|scaffold|init|bootstrap)\b/,
+      categories: ["tooling", "other"]
+    },
+    {
+      pattern: /\b(?:doc|readme|changelog)\b/,
+      categories: ["process", "tooling"]
+    }
+  ];
+  for (const { pattern, categories } of patterns) {
+    if (pattern.test(lower)) {
+      return categories;
+    }
+  }
+  return ["process", "tooling"];
+}
+async function readMergedKnowledge(directory, config, context, opts) {
+  const swarmPath = resolveSwarmKnowledgePath(directory);
+  const swarmEntries = await readKnowledge(swarmPath);
+  let hiveEntries = [];
+  if (config.hive_enabled !== false) {
+    const hivePath = resolveHiveKnowledgePath();
+    hiveEntries = await readKnowledge(hivePath);
+  }
+  const seenLessons = new Set;
+  const merged = [];
+  for (const entry of hiveEntries) {
+    const normalized = normalize(entry.lesson);
+    seenLessons.add(normalized);
+    merged.push({
+      ...entry,
+      relevanceScore: { category: 0, confidence: 0, keywords: 0 },
+      finalScore: 0
+    });
+  }
+  for (const entry of swarmEntries) {
+    const normalized = normalize(entry.lesson);
+    if (seenLessons.has(normalized)) {
+      continue;
+    }
+    const swarmBigrams = wordBigrams(normalized);
+    const isHiveNearDup = hiveEntries.some((hiveEntry) => jaccardBigram(swarmBigrams, wordBigrams(normalize(hiveEntry.lesson))) >= JACCARD_THRESHOLD);
+    if (isHiveNearDup)
+      continue;
+    const isSwarmNearDup = merged.some((m) => m.tier === "swarm" && jaccardBigram(swarmBigrams, wordBigrams(normalize(m.lesson))) >= JACCARD_THRESHOLD);
+    if (isSwarmNearDup)
+      continue;
+    seenLessons.add(normalized);
+    merged.push({
+      ...entry,
+      relevanceScore: { category: 0, confidence: 0, keywords: 0 },
+      finalScore: 0
+    });
+  }
+  const retractionRecords = await readRetractionRecords(directory);
+  const suppressedLessons = new Set(retractionRecords.map((record3) => record3.normalized_lesson).filter((value) => typeof value === "string" && value.length > 0));
+  const scopeFilter = config.scope_filter ?? ["global"];
+  const filtered = merged.filter((entry) => (opts?.skipScopeFilter || scopeFilter.some((pattern) => (entry.scope ?? "global") === pattern)) && isActiveStatus(entry.status) && !suppressedLessons.has(normalize(entry.lesson)));
+  const ranked = filtered.map((entry) => {
+    let categoryScore = 0;
+    if (context?.currentPhase) {
+      const phaseCategories = inferCategoriesFromPhase(context.currentPhase);
+      if (phaseCategories.includes(entry.category)) {
+        categoryScore = 1;
+      } else if (entry.category === "process") {
+        categoryScore = 0.5;
+      }
+    } else {
+      categoryScore = 0.5;
+    }
+    const confidenceScore = entry.confidence;
+    let keywordsScore = 0;
+    if (context?.techStack && entry.tags.length > 0) {
+      const matchingTags = entry.tags.filter((t) => context.techStack.some((s) => t.toLowerCase().includes(s.toLowerCase()) || s.toLowerCase().includes(t.toLowerCase()))).length;
+      keywordsScore = Math.min(matchingTags / Math.max(entry.tags.length, 1), 1);
+    } else if (entry.tags.length === 0) {
+      keywordsScore = 0.5;
+    }
+    let tierBoost = 0;
+    let isSameProject = false;
+    if (entry.tier === "hive" && "source_project" in entry) {
+      const sourceProject = entry.source_project;
+      isSameProject = !!(context?.projectName && sourceProject === context.projectName);
+      tierBoost = HIVE_TIER_BOOST;
+    }
+    const sameProjectPenalty = isSameProject ? DEFAULT_SAME_PROJECT_PENALTY : 0;
+    const finalScore = categoryScore * 0.4 + confidenceScore * 0.35 + keywordsScore * 0.25 + tierBoost + sameProjectPenalty;
+    const relevanceScore = {
+      category: categoryScore,
+      confidence: confidenceScore,
+      keywords: keywordsScore
+    };
+    return {
+      ...entry,
+      relevanceScore,
+      finalScore: Math.min(Math.max(finalScore, 0), 1)
+    };
+  });
+  ranked.sort((a, b) => {
+    const scoreDiff = b.finalScore - a.finalScore;
+    if (Math.abs(scoreDiff) > 0.001)
+      return scoreDiff;
+    const dateA = new Date(a.created_at).getTime();
+    const dateB = new Date(b.created_at).getTime();
+    return dateB - dateA;
+  });
+  const maxInject = config.max_inject_count ?? 5;
+  const topN = ranked.slice(0, maxInject);
+  return topN;
+}
+function lc(s) {
+  return (s ?? "").toLowerCase();
+}
+function anyMatch(haystack, needles) {
+  if (needles.length === 0)
+    return false;
+  const hay = haystack.map(lc);
+  return needles.some((n) => hay.some((h) => h.includes(lc(n))));
+}
+function tokenizeContext(ctx) {
+  const parts = [];
+  if (ctx.taskTitle)
+    parts.push(ctx.taskTitle);
+  if (ctx.taskDescription)
+    parts.push(ctx.taskDescription);
+  if (ctx.lastUserMessage)
+    parts.push(ctx.lastUserMessage);
+  if (ctx.currentAction)
+    parts.push(ctx.currentAction);
+  if (ctx.currentTool)
+    parts.push(ctx.currentTool);
+  if (ctx.targetAgent)
+    parts.push(ctx.targetAgent);
+  if (ctx.declaredScope)
+    parts.push(ctx.declaredScope);
+  if (ctx.recentReviewerFailures)
+    parts.push(...ctx.recentReviewerFailures);
+  if (ctx.recentTestFailures)
+    parts.push(...ctx.recentTestFailures);
+  if (ctx.recentToolErrors)
+    parts.push(...ctx.recentToolErrors);
+  if (ctx.planConstraints)
+    parts.push(...ctx.planConstraints);
+  if (ctx.filePaths)
+    parts.push(...ctx.filePaths);
+  return parts.map(lc);
+}
+function scoreDirectiveAgainstContext(entry, ctx) {
+  const haystack = tokenizeContext(ctx);
+  const triggerHit = entry.triggers && entry.triggers.length > 0 ? anyMatch(haystack, entry.triggers) : false;
+  const actionHit = entry.applies_to_tools && entry.applies_to_tools.length > 0 ? entry.applies_to_tools.map(lc).some((t) => t === lc(ctx.currentTool) || t === lc(ctx.currentAction)) : false;
+  const agentHit = entry.applies_to_agents && entry.applies_to_agents.length > 0 ? entry.applies_to_agents.map(lc).some((a) => a === lc(ctx.targetAgent)) : false;
+  let score = 0;
+  if (triggerHit)
+    score += 0.5;
+  if (actionHit)
+    score += 0.35;
+  if (agentHit)
+    score += 0.25;
+  if (entry.directive_priority === "critical")
+    score += 0.4;
+  else if (entry.directive_priority === "high")
+    score += 0.2;
+  else if (entry.directive_priority === "medium")
+    score += 0.1;
+  return { triggerHit, actionHit, agentHit, score: Math.min(1, score) };
+}
+
+// src/hooks/search-knowledge.ts
+init_knowledge_types();
+var TEXT_WEIGHT = 0.6;
+var META_WEIGHT = 0.4;
+var DIRECTIVE_BOOST_MIN_CONFIDENCE = 0.75;
+var SYNONYM_TEXT_BOOST = 0.15;
+var TRIGGER_RECALL_BOOST = 0.3;
+var TRIGGER_RECALL_MIN_LEN = 3;
+var DEFAULT_COLD_START_BONUS = 0.08;
+var DEFAULT_COLD_START_MAX_AGE_PHASES = 3;
+var OUTCOME_RANK_WEIGHT = 0.1;
+function entryText(e) {
+  return `${e.lesson} ${e.tags.join(" ")} ${e.category}`;
+}
+function entryAgePhases(e) {
+  const cb = e.confirmed_by;
+  if (!Array.isArray(cb) || cb.length === 0)
+    return 0;
+  const phases = new Set;
+  for (const c of cb) {
+    if (typeof c?.phase_number === "number")
+      phases.add(c.phase_number);
+  }
+  return phases.size > 0 ? phases.size : cb.length;
+}
+function clampLambda(v) {
+  if (typeof v !== "number" || Number.isNaN(v))
+    return 0.5;
+  return Math.min(1, Math.max(0, v));
+}
+function mmrRerank(pool, pinned, max, lambda) {
+  if (pool.length === 0)
+    return [];
+  const bigrams = new Map;
+  const bg = (e) => {
+    let s = bigrams.get(e.id);
+    if (!s) {
+      s = wordBigrams(normalize(e.lesson ?? ""));
+      bigrams.set(e.id, s);
+    }
+    return s;
+  };
+  const selected = [...pinned];
+  const candidates = [...pool];
+  const out = [];
+  while (selected.length < max && candidates.length > 0) {
+    let bestIdx = -1;
+    let bestScore = Number.NEGATIVE_INFINITY;
+    let best = null;
+    for (let i = 0;i < candidates.length; i++) {
+      const c = candidates[i];
+      let maxSim = 0;
+      for (const s of selected) {
+        const sim = jaccardBigram(bg(c), bg(s));
+        if (sim > maxSim)
+          maxSim = sim;
+      }
+      const score = lambda * c.finalScore - (1 - lambda) * maxSim;
+      if (score > bestScore + 0.000000001 || Math.abs(score - bestScore) <= 0.000000001 && best !== null && tieBreak(c, best) < 0) {
+        bestScore = score;
+        bestIdx = i;
+        best = c;
+      }
+    }
+    if (bestIdx < 0 || best === null)
+      break;
+    out.push(best);
+    selected.push(best);
+    candidates.splice(bestIdx, 1);
+  }
+  return out;
+}
+function tieBreak(a, b) {
+  if (Math.abs(a.finalScore - b.finalScore) > 0.000000001)
+    return b.finalScore - a.finalScore;
+  const at = new Date(a.created_at).getTime();
+  const bt = new Date(b.created_at).getTime();
+  if (at !== bt)
+    return bt - at;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function statusBoost(status) {
+  if (status === "promoted")
+    return 0.15;
+  if (status === "established")
+    return 0.1;
+  return 0;
+}
+async function searchKnowledge(params) {
+  const {
+    directory,
+    config,
+    query,
+    context,
+    mode,
+    agent = "unknown",
+    sessionId = "unknown",
+    tier = "all",
+    emitEvent = false,
+    applyScopeFilter = true,
+    forceReadHive = false,
+    applyRoleScope = true,
+    skipLedgerGenesis = false
+  } = params;
+  const traceId = newTraceId();
+  const max = params.maxResults ?? config.max_inject_count ?? 5;
+  let results = [];
+  let synonymTokens = [];
+  const synonymTrace = {};
+  try {
+    const mergeConfig = {
+      ...config,
+      hive_enabled: tier === "swarm" ? false : forceReadHive ? true : config.hive_enabled,
+      max_inject_count: Math.max(20, max)
+    };
+    const projected = {
+      projectName: context?.projectName ?? "unknown",
+      currentPhase: context?.currentPhase ?? "",
+      techStack: context?.techStack,
+      recentErrors: [
+        ...context?.recentReviewerFailures ?? [],
+        ...context?.recentTestFailures ?? [],
+        ...context?.recentToolErrors ?? []
+      ]
+    };
+    let candidates = await readMergedKnowledge(directory, mergeConfig, projected, {
+      skipScopeFilter: !applyScopeFilter
+    });
+    const journalPath2 = path5.join(directory, ".swarm", "knowledge-receipts-v2.jsonl");
+    const journalReadable = existsSync3(journalPath2) && statSync4(journalPath2).size > 0;
+    const counterRollups = skipLedgerGenesis && !journalReadable ? new Map : await readAuthoritativeKnowledgeCounterRollups(directory);
+    candidates = candidates.filter((e) => {
+      if (!isActiveStatus(e.status))
+        return false;
+      if (tier === "hive" && e.tier !== "hive")
+        return false;
+      return true;
+    });
+    const role = stripKnownSwarmPrefix(agent).toLowerCase();
+    if (applyRoleScope && role && role !== "unknown") {
+      candidates = candidates.filter((e) => {
+        if (!e.applies_to_agents || e.applies_to_agents.length === 0)
+          return true;
+        if (role === "architect")
+          return true;
+        return e.applies_to_agents.map((a) => stripKnownSwarmPrefix(a).toLowerCase()).includes(role);
+      });
+    }
+    const queryText = (query ?? "").trim();
+    const queryBigrams = queryText ? wordBigrams(normalize(queryText)) : null;
+    const hasQuery = queryBigrams !== null;
+    const textWeight = hasQuery ? TEXT_WEIGHT : 0;
+    const metaWeight = hasQuery ? META_WEIGHT : 1;
+    const compositeRaw = [
+      queryText,
+      context?.taskTitle,
+      context?.taskDescription,
+      context?.lastUserMessage,
+      context?.currentAction,
+      ...context?.recentReviewerFailures ?? [],
+      ...context?.recentTestFailures ?? [],
+      ...context?.recentToolErrors ?? []
+    ].filter((s) => typeof s === "string" && s.length > 0).join(" ");
+    const compositeNorm = normalize(compositeRaw);
+    const hasComposite = compositeNorm.length > 0;
+    try {
+      if (hasComposite) {
+        const synMap = await readSynonymMap(directory, config.retrieval?.synonym_map_max_pairs);
+        const synIndex = buildSynonymIndex(synMap, config.retrieval?.synonym_min_cooccurrence);
+        const baseTokens = compositeNorm.split(" ").filter(Boolean);
+        synonymTokens = expandTokens(synIndex, baseTokens);
+      }
+    } catch {
+      synonymTokens = [];
+    }
+    const minConf = typeof config.directive_min_confidence === "number" ? config.directive_min_confidence : DIRECTIVE_BOOST_MIN_CONFIDENCE;
+    const scored = candidates.map((entry) => {
+      const retrievalOutcomes = effectiveRetrievalOutcomes(entry.retrieval_outcomes, counterRollups.get(entry.id));
+      const textScore = queryBigrams ? jaccardBigram(queryBigrams, wordBigrams(normalize(entryText(entry)))) : 0;
+      const metaScore = entry.finalScore;
+      const ds = context ? scoreDirectiveAgainstContext(entry, context) : { triggerHit: false, actionHit: false, agentHit: false, score: 0 };
+      const confBoost = context && entry.confidence >= minConf && (ds.actionHit || ds.agentHit) ? 0.25 : 0;
+      const generatedSkillBoost = entry.generated_skill_path && entry.status !== "archived" ? 0.05 : 0;
+      const outcomeBoost = computeOutcomeSignal(retrievalOutcomes) * OUTCOME_RANK_WEIGHT;
+      const coldStartBonus = (retrievalOutcomes.applied_explicit_count ?? 0) === 0 && entryAgePhases(entry) < (config.retrieval?.cold_start_max_age_phases ?? DEFAULT_COLD_START_MAX_AGE_PHASES) ? config.retrieval?.cold_start_bonus ?? DEFAULT_COLD_START_BONUS : 0;
+      let synonymBoost = 0;
+      if (synonymTokens.length > 0) {
+        const entryHay = normalize(entryText(entry));
+        const matched = [];
+        for (const t of synonymTokens) {
+          if (t.length > 0 && entryHay.includes(t))
+            matched.push(t);
+        }
+        if (matched.length > 0) {
+          synonymBoost = SYNONYM_TEXT_BOOST;
+          synonymTrace[entry.id] = matched;
+        }
+      }
+      const triggerRecallHit = !ds.triggerHit && hasComposite && Array.isArray(entry.triggers) && entry.triggers.some((tr) => {
+        const n = normalize(tr);
+        return n.length >= TRIGGER_RECALL_MIN_LEN && compositeNorm.includes(n);
+      });
+      const triggerRecallBoost = triggerRecallHit ? TRIGGER_RECALL_BOOST : 0;
+      const finalScore = Math.min(1, Math.max(0, textWeight * textScore + metaWeight * metaScore + ds.score + confBoost + generatedSkillBoost + outcomeBoost + coldStartBonus + synonymBoost + triggerRecallBoost + (hasQuery && !entry.confidence_floor_demoted ? statusBoost(entry.status) : 0)));
+      const statusScoreBoost = hasQuery && !entry.confidence_floor_demoted ? statusBoost(entry.status) : 0;
+      const isCritical = entry.directive_priority === "critical" && (ds.triggerHit || ds.actionHit || ds.agentHit);
+      const isForceHive = forceReadHive && entry.tier === "hive";
+      return {
+        ...entry,
+        retrieval_outcomes: retrievalOutcomes,
+        finalScore,
+        coldStartBoost: coldStartBonus,
+        score_breakdown: {
+          text_score: textScore,
+          metadata_score: metaScore,
+          directive_score: ds.score,
+          confidence_boost: confBoost,
+          generated_skill_boost: generatedSkillBoost,
+          outcome_boost: outcomeBoost,
+          cold_start_boost: coldStartBonus,
+          synonym_boost: synonymBoost,
+          trigger_recall_boost: triggerRecallBoost,
+          status_boost: statusScoreBoost,
+          final_score: finalScore,
+          ...synonymTrace[entry.id] ? { synonym_matches: synonymTrace[entry.id] } : {}
+        },
+        __critical: isCritical,
+        __forceHive: isForceHive
+      };
+    });
+    scored.sort((a, b) => {
+      const diff = b.finalScore - a.finalScore;
+      if (Math.abs(diff) > 0.001)
+        return diff;
+      return new Date(b.created_at).getTime() - new Date(a.created_at).getTime();
+    });
+    const top = [];
+    const seen = new Set;
+    for (const e of scored) {
+      if (top.length >= max)
+        break;
+      if (e.__critical && !seen.has(e.id)) {
+        top.push(e);
+        seen.add(e.id);
+      }
+    }
+    for (const e of scored) {
+      if (top.length >= max)
+        break;
+      if (e.__forceHive && !seen.has(e.id)) {
+        top.push(e);
+        seen.add(e.id);
+      }
+    }
+    const lambda = clampLambda(config.retrieval?.mmr_lambda);
+    const remaining = scored.filter((e) => !seen.has(e.id));
+    const selected = mmrRerank(remaining, top, max, lambda);
+    for (const e of selected) {
+      if (top.length >= max)
+        break;
+      if (!seen.has(e.id)) {
+        top.push(e);
+        seen.add(e.id);
+      }
+    }
+    results = top.map(({ __critical: _c, __forceHive: _f, ...rest }) => rest);
+  } catch (err) {
+    warn(`[search-knowledge] retrieval failed: ${err instanceof Error ? err.message : String(err)}`);
+    results = [];
+  }
+  if (emitEvent) {
+    const ranks = {};
+    const scores = {};
+    results.forEach((e, idx) => {
+      ranks[e.id] = idx + 1;
+      scores[e.id] = e.finalScore;
+    });
+    const synonymBreakdown = {};
+    for (const e of results) {
+      if (synonymTrace[e.id])
+        synonymBreakdown[e.id] = synonymTrace[e.id];
+    }
+    const scoreBreakdown = synonymTokens.length > 0 ? {
+      synonyms_expanded: synonymTokens,
+      synonym_matches: synonymBreakdown
+    } : undefined;
+    await recordKnowledgeEvent(directory, {
+      type: "retrieved",
+      trace_id: traceId,
+      session_id: sessionId,
+      phase: context?.currentPhase,
+      task_id: context?.taskId,
+      agent,
+      query: query ?? context?.lastUserMessage ?? context?.currentPhase ?? "",
+      retrieval_mode: mode,
+      result_ids: results.map((e) => e.id),
+      ranks,
+      scores,
+      ...scoreBreakdown ? { score_breakdown: scoreBreakdown } : {}
+    });
+  }
+  return { trace_id: traceId, results };
 }
-var syntax_check = createSwarmTool({
-  allowWorkingDirectoryOverride: true,
-  description: "Check syntax of source files using tree-sitter parsers. Supports JS/TS, Python, Go, Rust, Java, C/C++, C#, PHP, Ruby. Returns JSON with syntax errors found per file.",
+
+// src/tools/swarm-memory-recall.ts
+init_zod();
+var MEMORY_KINDS = [
+  "user_preference",
+  "project_fact",
+  "architecture_decision",
+  "repo_convention",
+  "api_finding",
+  "code_pattern",
+  "test_pattern",
+  "failure_pattern",
+  "security_note",
+  "evidence",
+  "todo",
+  "scratch"
+];
+var swarm_memory_recall = createSwarmTool({
+  description: "Recall scoped Swarm memory for the current repository. Read-only; retrieved memory is untrusted background.",
   args: {
-    changed_files: exports_external.array(exports_external.object({
-      path: exports_external.string(),
-      additions: exports_external.number()
-    })).describe("Files to check (from diff gate)"),
-    mode: exports_external.enum(["changed", "all"]).optional().describe("Check mode over the supplied changed_files. 'changed' (default) checks only entries with additions > 0, so deletion-only and pure-rename entries are excluded; 'all' checks every supplied entry. Neither mode enumerates the repository \u2014 this tool only ever inspects the files you pass in changed_files. If the filters leave nothing to check the verdict is 'skip', never 'pass'."),
-    languages: exports_external.array(exports_external.string()).optional().describe("Optional: restrict to specific languages")
+    query: exports_external.string().min(3).describe("Natural language recall query"),
+    kinds: exports_external.array(exports_external.enum(MEMORY_KINDS)).optional().describe("Optional memory kinds to include"),
+    maxItems: exports_external.number().int().min(1).max(20).optional().describe("Maximum memories to return")
   },
-  async execute(args, directory) {
-    const gates = _internals4.loadGateOverrides(directory);
-    const result = await syntaxCheck(args, directory, gates);
-    return JSON.stringify(result);
-  }
+  execute: async (args, directory, ctx) => computeSwarmMemoryRecall(args, directory, ctx)
 });
-
-// src/mcp/adapters/verification.ts
-function mcpToolContext(root) {
-  return { directory: root };
-}
-function safeParseJson(text) {
+async function computeSwarmMemoryRecall(args, directory, ctx, options) {
+  const { config } = _internals4.loadPluginConfigWithMeta(directory);
+  if (config.memory?.enabled !== true) {
+    return JSON.stringify({
+      success: false,
+      disabled: true,
+      message: "Swarm memory is disabled. Set swarm.memory.enabled=true."
+    });
+  }
+  const parsed = RecallArgsSchema.safeParse(args);
+  if (!parsed.success) {
+    return JSON.stringify({
+      success: false,
+      error: parsed.error.issues.map((issue) => issue.message).join("; ")
+    });
+  }
+  const agent = getContextAgent(ctx);
+  const unitId = ctx?.sessionID ? _internals4.getAgentSession(ctx.sessionID)?.currentTaskId ?? undefined : undefined;
+  const gateway = _internals4.createMemoryGateway({
+    directory,
+    sessionID: ctx?.sessionID,
+    agentRole: agent,
+    agentId: agent,
+    runId: ctx?.sessionID,
+    unitId
+  }, {
+    config: config.memory
+  });
   try {
-    return JSON.parse(text);
-  } catch {
-    return { raw: text };
+    const bundle = await gateway.recall(parsed.data, {
+      recordUsage: options?.recordUsage !== false
+    });
+    return JSON.stringify({
+      success: true,
+      bundle_id: bundle.id,
+      memory_ids: bundle.items.map((item) => item.record.id),
+      total: bundle.items.length,
+      token_estimate: bundle.tokenEstimate,
+      signals: bundle.items.map((item) => ({
+        memory_id: item.record.id,
+        relation: item.relation,
+        ...item.signals
+      })),
+      prompt_block: bundle.promptBlock
+    }, null, 2);
+  } finally {
+    await gateway.dispose();
   }
 }
-var syntaxCheckSchema = exports_external.object({
-  changed_files: exports_external.array(exports_external.object({
-    path: exports_external.string().describe("Repository-relative file path"),
-    additions: exports_external.number().describe("Added line count from the diff")
-  })).describe("Files to check (from diff gate)"),
-  mode: exports_external.enum(["changed", "all"]).optional().describe("Check mode: 'changed' checks only additions > 0 entries; 'all' checks every entry"),
-  languages: exports_external.array(exports_external.string()).optional().describe("Restrict to specific languages")
-});
-var placeholderScanSchema = exports_external.object({
-  changed_files: exports_external.array(exports_external.string()).describe("Repository-relative file paths to scan")
-});
-var sastScanSchema = exports_external.object({
-  changed_files: exports_external.array(exports_external.string()).describe("Repository-relative file paths to scan"),
-  severity_threshold: exports_external.enum(["low", "medium", "high", "critical"]).optional().describe("Minimum severity to report (default: medium)")
-});
-var qualityBudgetSchema = exports_external.object({
-  changed_files: exports_external.array(exports_external.string()).describe("Repository-relative file paths to analyze")
-});
-var evidenceCheckSchema = exports_external.object({
-  required_types: exports_external.string().optional().describe('Comma-separated evidence types required per task (default: "reviewer,test_engineer")')
+var RecallArgsSchema = exports_external.object({
+  query: exports_external.string().min(3),
+  kinds: exports_external.array(exports_external.enum(MEMORY_KINDS)).optional(),
+  maxItems: exports_external.number().int().min(1).max(20).optional()
 });
-var syntaxCheckAdapter = {
-  name: "syntax_check",
-  description: "Check syntax of source files using tree-sitter parsers. Supports JS/TS, Python, Go, Rust, Java, C/C++, C#, PHP, Ruby. Returns JSON with syntax errors found per file.",
-  kind: "read",
-  pathFields: ["changed_files"],
-  inputSchema: syntaxCheckSchema,
-  execute: (rawArgs, root) => computeSyntaxCheck(syntaxCheckSchema.parse(rawArgs), root)
-};
-var placeholderScanAdapter = {
-  name: "placeholder_scan",
-  description: "Scan changed files for placeholder content: TODO/FIXME comments, stub implementations, and placeholder markers that indicate unfinished work.",
-  kind: "read",
-  pathFields: ["changed_files"],
-  inputSchema: placeholderScanSchema,
-  execute: (rawArgs, root) => computePlaceholderScan({ changed_files: placeholderScanSchema.parse(rawArgs).changed_files }, root)
-};
-var sastScanAdapter = {
-  name: "sast_scan",
-  description: "static analysis security scan",
-  kind: "read",
-  pathFields: ["changed_files"],
-  inputSchema: sastScanSchema,
-  execute: (rawArgs, root) => {
-    const args = sastScanSchema.parse(rawArgs);
-    return computeSastScan({
-      changed_files: args.changed_files,
-      severity_threshold: args.severity_threshold,
-      offline_only: true
-    }, root);
-  }
-};
-var qualityBudgetAdapter = {
-  name: "quality_budget",
-  description: "check quality budgets (complexity, API surface, duplication, test ratio) for changed files",
-  kind: "read",
-  pathFields: ["changed_files"],
-  inputSchema: qualityBudgetSchema,
-  execute: (rawArgs, root) => computeQualityBudget({ changed_files: qualityBudgetSchema.parse(rawArgs).changed_files }, root)
-};
-var evidenceCheckAdapter = {
-  name: "evidence_check",
-  description: "Verify completed tasks in the plan have required evidence. Reads .swarm/plan.md for completed tasks and .swarm/evidence/ for evidence files. Returns JSON with completeness ratio and gaps for tasks missing required evidence types.",
-  kind: "read",
-  pathFields: [],
-  inputSchema: evidenceCheckSchema,
-  execute: async (rawArgs, root) => {
-    const args = evidenceCheckSchema.parse(rawArgs);
-    const result = await evidence_check.execute(args, mcpToolContext(root));
-    return typeof result === "string" ? safeParseJson(result) : result;
-  }
+var _internals4 = {
+  loadPluginConfigWithMeta,
+  createMemoryGateway,
+  getAgentSession
 };
+function getContextAgent(ctx) {
+  if (!ctx || typeof ctx !== "object")
+    return;
+  const value = ctx.agent;
+  return typeof value === "string" ? value : undefined;
+}
 
 // src/mcp/adapters/knowledge-memory.ts
 var knowledgeRecallSchema = exports_external.object({
@@ -17401,13 +18517,12 @@ var memoryRecallSchema = exports_external.object({
 });
 var knowledgeRecallAdapter = {
   name: "knowledge_recall",
-  description: "Performs semantic natural-language search across the knowledge base for relevant past decisions, patterns, and lessons learned.",
   kind: "read",
   pathFields: [],
   inputSchema: knowledgeRecallSchema,
   execute: async (rawArgs, root) => {
     const args = knowledgeRecallSchema.parse(rawArgs);
-    const knowledgePath = path5.join(root, ".swarm", "knowledge");
+    const knowledgePath = path6.join(root, ".swarm", "knowledge");
     if (!existsSync4(knowledgePath)) {
       return {
         results: [],
@@ -17441,7 +18556,6 @@ var knowledgeRecallAdapter = {
 };
 var swarmMemoryRecallAdapter = {
   name: "swarm_memory_recall",
-  description: "recall scoped Swarm memory for the current repository as untrusted background",
   kind: "read",
   pathFields: [],
   inputSchema: memoryRecallSchema,
@@ -17455,7 +18569,7 @@ var swarmMemoryRecallAdapter = {
         message: "Swarm memory is disabled. Set swarm.memory.enabled=true."
       };
     }
-    const storeArtifact = (config.memory.provider ?? "sqlite") === "sqlite" ? path5.join(root, ".swarm", "memory", "memory.db") : path5.join(root, ".swarm", "memory", "memories.jsonl");
+    const storeArtifact = (config.memory.provider ?? "sqlite") === "sqlite" ? path6.join(root, ".swarm", "memory", "memory.db") : path6.join(root, ".swarm", "memory", "memories.jsonl");
     if (!existsSync4(storeArtifact)) {
       return {
         available: false,
@@ -17468,6 +18582,18 @@ var swarmMemoryRecallAdapter = {
   }
 };
 
+// src/mcp/adapters/receipt-status.ts
+var receiptStatusAdapter = {
+  name: "knowledge_receipt_status",
+  kind: "read",
+  pathFields: [],
+  inputSchema: writeReceiptStatusInput,
+  execute: async (rawArgs, root) => {
+    const args = writeReceiptStatusInput.parse(rawArgs);
+    return readWriteReceiptStatus(root, args.idempotency_key);
+  }
+};
+
 // src/mcp/adapters/scope-repo.ts
 init_zod();
 
@@ -17475,7 +18601,7 @@ init_zod();
 init_zod();
 import * as child_process from "child_process";
 import * as fs4 from "fs";
-import * as path6 from "path";
+import * as path7 from "path";
 
 // src/diff/summary-generator.ts
 var RISK_LEVELS = ["Critical", "High", "Medium", "Low"];
@@ -17572,20 +18698,20 @@ function validateBase(base) {
 function validatePaths(paths) {
   if (!paths)
     return null;
-  for (const path7 of paths) {
-    if (!path7 || path7.length === 0) {
+  for (const path8 of paths) {
+    if (!path8 || path8.length === 0) {
       return "empty path not allowed";
     }
-    if (path7.length > MAX_PATH_LENGTH) {
+    if (path8.length > MAX_PATH_LENGTH) {
       return `path exceeds maximum length of ${MAX_PATH_LENGTH}`;
     }
-    if (SHELL_METACHARACTERS.test(path7)) {
+    if (SHELL_METACHARACTERS.test(path8)) {
       return "path contains shell metacharacters";
     }
-    if (path7.startsWith("-")) {
+    if (path8.startsWith("-")) {
       return 'path cannot start with "-" (option-like arguments not allowed)';
     }
-    if (CONTROL_CHAR_PATTERN.test(path7)) {
+    if (CONTROL_CHAR_PATTERN.test(path8)) {
       return "path contains control characters";
     }
   }
@@ -17689,8 +18815,8 @@ var diff = createSwarmTool({
         if (parts.length >= 3) {
           const additions = parseInt(parts[0], 10) || 0;
           const deletions = parseInt(parts[1], 10) || 0;
-          const path7 = parts[2];
-          files.push({ path: path7, additions, deletions });
+          const path8 = parts[2];
+          files.push({ path: path8, additions, deletions });
         }
       }
       if (summaryOnly) {
@@ -17773,7 +18899,7 @@ var diff = createSwarmTool({
           } else if (base === "unstaged") {
             const oldRef = `:${file.path}`;
             oldContent = fileExistsInRef(oldRef) ? getContentFromRef(oldRef) : "";
-            newContent = fs4.readFileSync(path6.join(directory, file.path), "utf-8");
+            newContent = fs4.readFileSync(path7.join(directory, file.path), "utf-8");
           } else {
             const oldRef = `${base}:${file.path}`;
             oldContent = fileExistsInRef(oldRef) ? getContentFromRef(oldRef) : "";
@@ -17925,7 +19051,6 @@ var symbolsSchema = exports_external.object({
 });
 var planConflictCheckAdapter = {
   name: "plan_conflict_check",
-  description: "read-only advisory check (#1656): compute a pairwise file-conflict matrix for N proposed parallel task groups using declared scopes and optional git co-change; returns a verdict (all_disjoint / conflicts_present / unknown_scopes), per-pair evidence, and a suggested serialization order. Writes nothing \u2014 the execution gate independently recomputes the verdict inline at dispatch time via the same helper. Call BEFORE attempting parallel dispatch to confirm disjointness.",
   kind: "read",
   pathFields: [],
   inputSchema: planConflictCheckSchema,
@@ -17933,7 +19058,6 @@ var planConflictCheckAdapter = {
 };
 var diffAdapter = {
   name: "diff",
-  description: "Analyze git diff for changed files, exports, interfaces, and function signatures. Returns structured output with contract change detection.",
   kind: "read",
   pathFields: ["paths"],
   inputSchema: diffSchema,
@@ -17958,7 +19082,6 @@ var diffAdapter = {
 };
 var symbolsAdapter = {
   name: "symbols",
-  description: "Extract and search code symbols (functions, classes, methods, interfaces) across the repository using tree-sitter. Use for understanding code structure and finding definitions.",
   kind: "read",
   pathFields: ["file", "workspace"],
   inputSchema: symbolsSchema,
@@ -17969,8 +19092,169 @@ var symbolsAdapter = {
   }
 };
 
+// src/tools/scope-validate.ts
+init_zod();
+import path8 from "path";
+init_path_identity();
+var scopeValidateArgs = {
+  command: exports_external.string().min(1).max(64 * 1024).describe("Shell command to inspect; it is never executed"),
+  shell: exports_external.enum(["posix", "powershell", "cmd"]).describe("Shell grammar used to inspect the command"),
+  scope_files: exports_external.array(exports_external.string().min(1).max(4096)).min(1).max(1e4).describe("Workspace-relative paths the command is allowed to write")
+};
+var scopeValidateSchema = exports_external.object(scopeValidateArgs);
+
+class ScopeValidationError extends Error {
+  code;
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.name = "ScopeValidationError";
+    this.code = code;
+  }
+}
+function fail(code, message) {
+  throw new ScopeValidationError(code, message);
+}
+function detectWrites(args) {
+  if (args.shell === "posix")
+    return detectPosixWrites(args.command);
+  return detectWindowsWrites(args.command, args.shell);
+}
+function createScopeMatcher(scopeEntries, directory) {
+  const flavor = getPathFlavor();
+  const pathImpl = flavor === "win32" ? path8.win32 : path8.posix;
+  const scopeIdentities = new Set(scopeEntries.map((scope) => normalizePathIdentity(pathImpl.resolve(directory, scope), flavor)));
+  return (filePath) => {
+    let candidate = pathImpl.resolve(directory, filePath);
+    while (true) {
+      if (scopeIdentities.has(normalizePathIdentity(candidate, flavor))) {
+        return true;
+      }
+      const parent = pathImpl.dirname(candidate);
+      if (parent === candidate)
+        return false;
+      candidate = parent;
+    }
+  };
+}
+function evaluateScopeValidate(args, directory) {
+  validateWorkspaceRoot(directory);
+  if (!args || typeof args.command !== "string") {
+    fail("INVALID_INPUT", "command must be a string");
+  }
+  if (!["posix", "powershell", "cmd"].includes(args.shell)) {
+    fail("INVALID_INPUT", "shell must be posix, powershell, or cmd");
+  }
+  if (!Array.isArray(args.scope_files)) {
+    fail("INVALID_SCOPE", "scope_files must be a non-empty array");
+  }
+  const normalizedScope = normalizeScopeFiles(args.scope_files);
+  if (!normalizedScope) {
+    fail("INVALID_SCOPE", "scope_files must contain safe workspace-relative paths");
+  }
+  const validateScopeTarget = createTargetWithinRootValidator(directory);
+  for (const scopeFile of normalizedScope) {
+    const unsafeReason = unsafePathTextReason(scopeFile);
+    if (unsafeReason)
+      fail("INVALID_SCOPE", unsafeReason);
+    const reason = validateScopeTarget(scopeFile);
+    if (reason)
+      fail("INVALID_SCOPE", reason);
+  }
+  const isInScope = createScopeMatcher(normalizedScope, directory);
+  const classification = classifyCommand(args.command);
+  if (classification.ambiguous) {
+    fail("AMBIGUOUS_COMMAND", "command syntax could not be verified safely");
+  }
+  if (classification.aggregate === "catastrophic" || classification.aggregate === "destructive") {
+    fail("DESTRUCTIVE_COMMAND", "destructive command intent is not permitted");
+  }
+  const analysis = detectWrites(args);
+  if (analysis.parseError) {
+    fail("UNPARSEABLE_COMMAND", "command could not be parsed safely");
+  }
+  if (!analysis.hasWrites) {
+    return {
+      allowed: true,
+      shell: args.shell,
+      command_digest: classification.originalDigest,
+      targets: []
+    };
+  }
+  const resolved = resolveWriteTargets(args.command, analysis.writes, directory);
+  const targets = [];
+  for (const target of resolved) {
+    if (!target.resolved || !target.resolvedPath) {
+      fail("UNRESOLVED_TARGET", "a write target could not be resolved statically");
+    }
+    const resolvedPath = path8.resolve(target.resolvedPath);
+    if (!isCanonicalPathWithinRoot(resolvedPath, directory)) {
+      fail("ROOT_ESCAPE", "a write target resolves outside the configured root");
+    }
+    const symlinkReason = checkWriteTargetForSymlink(resolvedPath, directory);
+    if (symlinkReason) {
+      fail("SYMLINK_ESCAPE", "a write target uses an unverifiable symlink or junction");
+    }
+    const relativeTarget = path8.relative(directory, resolvedPath);
+    if (!isInScope(relativeTarget)) {
+      fail("SCOPE_VIOLATION", "a write target is outside the inline declared scope");
+    }
+    const authority = checkFileAuthority("coder", relativeTarget, directory, undefined, { declaredScope: normalizedScope });
+    if (!authority.allowed) {
+      fail("AUTHORITY_DENIED", "a write target is protected by file authority policy");
+    }
+    targets.push({
+      category: target.original.category,
+      operator: target.original.operator,
+      path: relativeTarget.replace(/\\/g, "/")
+    });
+  }
+  return {
+    allowed: true,
+    shell: args.shell,
+    command_digest: classification.originalDigest,
+    targets
+  };
+}
+var scope_validate = createSwarmTool({
+  description: "Validate a shell command against an inline workspace scope without executing it. Rejects destructive, ambiguous, unresolved, escaping, symlinked, protected, and out-of-scope writes.",
+  args: scopeValidateArgs,
+  execute: async (args, directory) => JSON.stringify(evaluateScopeValidate(scopeValidateSchema.parse(args), directory))
+});
+
+// src/mcp/adapters/scope-validation.ts
+var scopeValidationAdapter = {
+  name: "scope_validate",
+  kind: "read",
+  pathFields: ["scope_files"],
+  inputSchema: scopeValidateSchema,
+  execute: async (rawArgs, root) => evaluateScopeValidate(scopeValidateSchema.parse(rawArgs), root)
+};
+
 // src/mcp/registry.ts
 var WRITE_TOOL_NAME_PATTERN = /write_|record_|submit_|repair_|prepare_|rebind_|invalidate_|authorize_|external_skill_(promote|reject|delete|revoke)|swarm_apply_patch|save_plan|update_task_status|declare_scope|set_qa_gates|knowledge_add|knowledge_remove|knowledge_archive|checkpoint|phase_complete|complete_pr_workflow|abort_pr_workflow|approve_plan_critic|swarm_memory_propose|swarm_memory_outcome|spec_write|lint_spec|skill_generate|skill_regenerate|skill_retire|skill_improve|skill_apply|run_stale_reconciliation|epic_record_divergence|lean_turbo_acquire_locks|lean_turbo_plan_lanes|lean_turbo_critic|lean_turbo_review|lean_turbo_run_phase|convene_general_council|swarm_command/;
+var REVIEWED_MCP_WRITE_TOOLS = ["knowledge_add"];
+var REVIEWED_MCP_WRITE_TOOL_SET = new Set(REVIEWED_MCP_WRITE_TOOLS);
+function validateWritePolicy(allowWrite, writeTools) {
+  if (writeTools === undefined)
+    return [];
+  if (!Array.isArray(writeTools)) {
+    throw new Error("MCP write policy must be an array");
+  }
+  if (!allowWrite && writeTools.length > 0) {
+    throw new Error("MCP write tools require the explicit allowWrite startup capability");
+  }
+  const seen = new Set;
+  for (const name of writeTools) {
+    if (typeof name !== "string" || name.length === 0 || !REVIEWED_MCP_WRITE_TOOL_SET.has(name)) {
+      throw new Error(`unknown or unauthorized MCP write tool: ${String(name)}`);
+    }
+    if (seen.has(name)) {
+      throw new Error(`duplicate MCP write tool: ${name}`);
+    }
+    seen.add(name);
+  }
+  return writeTools;
+}
 var READ_ADAPTERS = [
   knowledgeRecallAdapter,
   swarmMemoryRecallAdapter,
@@ -17981,13 +19265,16 @@ var READ_ADAPTERS = [
   qualityBudgetAdapter,
   planConflictCheckAdapter,
   diffAdapter,
-  symbolsAdapter
+  symbolsAdapter,
+  scopeValidationAdapter,
+  receiptStatusAdapter
 ];
 function buildMcpToolRegistry(options) {
   const root = options.root || options.directory || "";
   if (!root) {
     throw new Error("buildMcpToolRegistry: a project root is required");
   }
+  const requestedWrites = validateWritePolicy(options.allowWrite, options.writeTools);
   const tools = [];
   for (const adapter of READ_ADAPTERS) {
     const metadata = TOOL_METADATA[adapter.name];
@@ -18009,6 +19296,26 @@ function buildMcpToolRegistry(options) {
       execute: adapter.execute
     });
   }
+  if (requestedWrites.includes("knowledge_add")) {
+    const metadata = TOOL_METADATA.knowledge_add;
+    if (!metadata) {
+      throw new Error("buildMcpToolRegistry: knowledge_add is not a registered tool (TOOL_METADATA parity violated)");
+    }
+    if (WRITE_TOOL_NAME_PATTERN.test(knowledgeAddAdapter.name) === false) {
+      throw new Error("buildMcpToolRegistry: reviewed knowledge_add adapter is not classified as write-capable");
+    }
+    if (knowledgeAddAdapter.kind !== "write") {
+      throw new Error("buildMcpToolRegistry: knowledge_add adapter must be write-capable");
+    }
+    tools.push({
+      name: knowledgeAddAdapter.name,
+      description: metadata.description,
+      kind: "write",
+      pathFields: knowledgeAddAdapter.pathFields,
+      inputSchema: knowledgeAddAdapter.inputSchema,
+      execute: knowledgeAddAdapter.execute
+    });
+  }
   return { tools };
 }
 
@@ -18030,10 +19337,10 @@ class McpContainmentError extends Error {
 function validatePathValue(field, value, root) {
   if (typeof value !== "string" || value === "")
     return;
-  if (path7.isAbsolute(value) || /^[A-Za-z]:[/\\]/.test(value)) {
-    const resolved2 = path7.resolve(value);
-    const relative2 = path7.relative(root, resolved2);
-    if (relative2.startsWith("..") || path7.isAbsolute(relative2)) {
+  if (path9.isAbsolute(value) || /^[A-Za-z]:[/\\]/.test(value)) {
+    const resolved2 = path9.resolve(value);
+    const relative2 = path9.relative(root, resolved2);
+    if (relative2.startsWith("..") || path9.isAbsolute(relative2)) {
       throw new McpContainmentError(field, value, root);
     }
     if (!isCanonicalPathWithinRoot(resolved2, root)) {
@@ -18045,7 +19352,7 @@ function validatePathValue(field, value, root) {
   if (reason !== null) {
     throw new McpContainmentError(field, value, root);
   }
-  const resolved = path7.resolve(root, value);
+  const resolved = path9.resolve(root, value);
   if (!isCanonicalPathWithinRoot(resolved, root)) {
     throw new McpContainmentError(field, value, root);
   }
@@ -18080,7 +19387,8 @@ function createMcpServer(options) {
   const root = options.root;
   const registry = buildMcpToolRegistry({
     root,
-    allowWrite: options.allowWrite
+    allowWrite: options.allowWrite,
+    writeTools: options.writeTools
   });
   const server = new McpServer({
     name: SERVER_NAME,
@@ -18095,10 +19403,11 @@ function createMcpServer(options) {
         for (const field of tool.pathFields) {
           validatePathField(field, args[field], root);
         }
-        const raw = await tool.execute(args, root);
+        const raw = tool.kind === "write" ? await tool.execute(args, root, { hooks: options.writeHooks }) : await tool.execute(args, root);
         const { text } = applyResponsePipeline(raw);
         return {
-          content: [{ type: "text", text }]
+          content: [{ type: "text", text }],
+          ...tool.kind === "write" && isStructuredWriteFailure(raw) ? { isError: true } : {}
         };
       } catch (error) {
         const raw = error instanceof Error ? error.message : String(error);
@@ -18112,6 +19421,16 @@ function createMcpServer(options) {
   }
   return server;
 }
+function isStructuredWriteFailure(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const record3 = value;
+  if (record3.success === false)
+    return true;
+  if (record3.success !== true && typeof record3.error === "string")
+    return true;
+  return false;
+}
 async function runMcpServer(options) {
   const server = createMcpServer(options);
   const transport = options.transport !== undefined ? options.transport : new StdioServerTransport;