@spilno/herald-mcp 1.28.2 → 1.30.0

package/dist/index.js

@@ -8,44 +8,144 @@
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "fs";
-import { homedir } from "os";
+import { homedir, userInfo } from "os";
 import { join } from "path";
 import * as readline from "readline";
 import { runInit } from "./cli/init.js";
+import { sanitize, previewSanitization } from "./sanitization.js";
 // Configuration - all sensitive values from environment only
 // CEDA_URL is primary, HERALD_API_URL for backwards compat, default to cloud
 const CEDA_API_URL = process.env.CEDA_URL || process.env.HERALD_API_URL || "https://getceda.com";
 const CEDA_API_TOKEN = process.env.HERALD_API_TOKEN;
 const CEDA_API_USER = process.env.HERALD_API_USER;
 const CEDA_API_PASS = process.env.HERALD_API_PASS;
-// CEDA-67: AI-native context - derived from environment, not configured
-// User identity (optional override, defaults to system user)
-const HERALD_USER = process.env.HERALD_USER || process.env.USER || "default";
-/**
- * CEDA-67: Derive context tags from current working directory
- * Example: /Users/john/Documents/aegis_ceda/herald-mcp → ["aegis_ceda", "herald-mcp"]
- */
-function deriveContextTags() {
-    const cwd = process.cwd();
-    const parts = cwd.split("/").filter(p => p &&
-        !p.startsWith(".") &&
-        !["Users", "Documents", "home", "~", "var", "tmp"].includes(p));
-    // Take last 3 meaningful path segments as tags
-    return parts.slice(-3).map(p => p.toLowerCase().replace(/[^a-z0-9-]/g, "-"));
+// CEDA-70: Zero-config context - everything auto-derived, nothing required
+// User is ALWAYS known (whoami). Company/project inferred from path as tags.
+function deriveUser() {
+    try {
+        return userInfo().username;
+    }
+    catch {
+        return "unknown";
+    }
+}
+function deriveTags() {
+    // Derive tags from cwd path - last 2 meaningful segments
+    // /Users/john/projects/acme/backend → ["acme", "backend"]
+    try {
+        const cwd = process.cwd();
+        const parts = cwd.split("/").filter(p => p && !["Users", "home", "Documents", "projects", "repos", "GitHub"].includes(p));
+        return parts.slice(-2); // Last 2 segments as tags
+    }
+    catch {
+        return [];
+    }
+}
+function getMcpJsonPath() {
+    return join(process.cwd(), '.mcp.json');
 }
-// Derived context (computed once at startup)
-const CONTEXT_TAGS = deriveContextTags();
+function readMcpJson() {
+    const mcpPath = getMcpJsonPath();
+    if (!existsSync(mcpPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(mcpPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function persistContext(context) {
+    const mcpPath = getMcpJsonPath();
+    let mcpJson = {};
+    if (existsSync(mcpPath)) {
+        try {
+            mcpJson = JSON.parse(readFileSync(mcpPath, 'utf-8'));
+        }
+        catch {
+            // Corrupted file, preserve structure
+            mcpJson = {};
+        }
+    }
+    // Add herald context section (preserve existing mcpServers)
+    mcpJson.herald = {
+        ...mcpJson.herald,
+        context: {
+            tags: context.tags,
+            user: context.user,
+            derived: true,
+            derivedFrom: 'path',
+            storedAt: new Date().toISOString()
+        }
+    };
+    writeFileSync(mcpPath, JSON.stringify(mcpJson, null, 2));
+    console.error(`[Herald] Context stored in .mcp.json: tags=[${context.tags.join(', ')}]`);
+}
+function loadOrDeriveContext() {
+    // 1. Check env vars (explicit override - highest priority)
+    if (process.env.HERALD_COMPANY) {
+        return {
+            tags: [process.env.HERALD_COMPANY, process.env.HERALD_PROJECT].filter(Boolean),
+            user: process.env.HERALD_USER || deriveUser(),
+            source: 'env'
+        };
+    }
+    // 2. Check .mcp.json for stored context
+    const mcpJson = readMcpJson();
+    if (mcpJson?.herald?.context?.tags?.length) {
+        return {
+            tags: mcpJson.herald.context.tags,
+            user: mcpJson.herald.context.user || deriveUser(),
+            source: 'stored'
+        };
+    }
+    // 3. Derive from path
+    const tags = deriveTags();
+    const user = deriveUser();
+    // Store for next time (if we have tags and .mcp.json exists or we can create it)
+    if (tags.length > 0) {
+        try {
+            persistContext({ tags, user });
+        }
+        catch {
+            // Silent fail - don't break startup if we can't write
+        }
+    }
+    return { tags, user, source: 'derived' };
+}
+// Load context once at startup
+const LOADED_CONTEXT = loadOrDeriveContext();
+// User is always known
+const HERALD_USER = LOADED_CONTEXT.user;
+// Tags from context (env > stored > derived)
+const HERALD_TAGS = LOADED_CONTEXT.tags;
+const HERALD_COMPANY = HERALD_TAGS[0] || "";
+const HERALD_PROJECT = HERALD_TAGS[1] || HERALD_TAGS[0] || "";
+// Track context source for telemetry
+const CONTEXT_SOURCE = LOADED_CONTEXT.source;
+const CONTEXT_AUTO_DERIVED = CONTEXT_SOURCE === 'derived';
 // Offspring vault context (for Avatar mode)
 const HERALD_VAULT = process.env.HERALD_VAULT || "";
 const AEGIS_OFFSPRING_PATH = process.env.AEGIS_OFFSPRING_PATH || join(homedir(), "Documents", "aegis_ceda", "_offspring");
 // Cloud mode: Use CEDA API for offspring communication instead of local files
 const OFFSPRING_CLOUD_MODE = process.env.HERALD_OFFSPRING_CLOUD === "true";
-const VERSION = "1.28.2";
+const VERSION = "1.30.0";
 // Self-routing description - teaches Claude when to call Herald
 const HERALD_DESCRIPTION = `AI-native pattern learning for CEDA.
 
+AUTHORIZATION GATES (CRITICAL):
+Before multi-file operations (>3 files), module scaffolding, or bulk changes:
+1. Present synthesis/plan to user
+2. Ask: "Proceed? [Y/continue/adjust]"
+3. WAIT for explicit approval before writing
+
+Autonomous (no gate): reading, searching, planning, single-file edits, commits.
+Gated: multi-file creation, module scaffolding, bulk operations.
+
+Why: User steering > execution speed. Long uninterrupted runs block collaboration.
+
 WHEN TO OFFER REFLECTION:
 When you notice FRICTION (multiple iterations, debugging spirals, corrections, confusion)
 or FLOW (clean first-pass execution, good instincts, smooth outcomes),
@@ -60,9 +160,9 @@ const AUTO_SYNC_ON_STARTUP = process.env.HERALD_AUTO_SYNC !== "false";
 // SECURITY: Never bundle API keys in npm packages
 const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY || "";
 const OPENAI_API_KEY = process.env.OPENAI_API_KEY || "";
-// Session persistence - user-based paths (tags handle context, not folders)
+// Session persistence - context-isolated paths
 function getHeraldDir() {
-    return join(homedir(), ".herald", HERALD_USER);
+    return join(homedir(), ".herald", HERALD_COMPANY, HERALD_PROJECT, HERALD_USER);
 }
 function getSessionFile() {
     return join(getHeraldDir(), "session");
@@ -179,7 +279,7 @@ function clearSession() {
     }
 }
 function getContextString() {
-    return `${HERALD_USER}→${CONTEXT_TAGS.join("→")}`;
+    return `${HERALD_COMPANY}:${HERALD_PROJECT}:${HERALD_USER}`;
 }
 const HERALD_SYSTEM_PROMPT = `You are Herald, the voice of CEDA (Cognitive Event-Driven Architecture).
 You help humans design module structures through natural conversation.
@@ -420,13 +520,14 @@ async function callCedaAPI(endpoint, method = "GET", body) {
         };
     }
     let url = `${CEDA_API_URL}${endpoint}`;
-    // CEDA-67: Add tags for context-aware endpoints
-    const needsContextParams = endpoint.startsWith("/api/patterns") ||
+    // Only add tenant params to endpoints that need them (patterns, session queries)
+    // Don't add to simple endpoints like /api/stats, /health
+    const needsTenantParams = endpoint.startsWith("/api/patterns") ||
         endpoint.startsWith("/api/session/") ||
         endpoint.startsWith("/api/observations");
-    if (method === "GET" && needsContextParams) {
+    if (method === "GET" && needsTenantParams) {
         const separator = endpoint.includes("?") ? "&" : "?";
-        url += `${separator}tags=${encodeURIComponent(CONTEXT_TAGS.join(","))}&user=${HERALD_USER}`;
+        url += `${separator}company=${HERALD_COMPANY}&project=${HERALD_PROJECT}&user=${HERALD_USER}`;
     }
     const headers = {
         "Content-Type": "application/json",
@@ -437,10 +538,10 @@ async function callCedaAPI(endpoint, method = "GET", body) {
     }
     let enrichedBody = body;
     if (method === "POST" && body && typeof body === "object") {
-        // CEDA-67: Use tags instead of company/project hierarchy
         enrichedBody = {
             ...body,
-            tags: CONTEXT_TAGS,
+            company: HERALD_COMPANY,
+            project: HERALD_PROJECT,
             user: HERALD_USER,
         };
     }
@@ -495,13 +596,13 @@ Examples:
   herald-mcp observe yes
 
 Environment:
-  CEDA_URL            CEDA server URL (default: https://getceda.com)
-  HERALD_USER         User identity (default: system username)
+  HERALD_API_URL      CEDA server URL (required for API calls)
+  HERALD_COMPANY      Company context (default: default)
+  HERALD_PROJECT      Project context (default: default)
+  HERALD_USER         User context (default: default)
   ANTHROPIC_API_KEY   Claude API key (required for chat mode)
   HERALD_API_TOKEN    Bearer token (optional)
 
-Context tags are derived automatically from your working directory.
-
 MCP Mode:
   When piped, Herald speaks JSON-RPC for AI agents.
 `);
@@ -626,7 +727,7 @@ async function runCLI(args) {
 // ============================================
 // MCP MODE - JSON-RPC for AI agents
 // ============================================
-const server = new Server({ name: "herald", version: VERSION, description: HERALD_DESCRIPTION }, { capabilities: { tools: {} } });
+const server = new Server({ name: "herald", version: VERSION, description: HERALD_DESCRIPTION }, { capabilities: { tools: {}, resources: {} } });
 const tools = [
     {
         name: "herald_help",
@@ -643,6 +744,50 @@ const tools = [
         description: "Get CEDA server statistics and loaded patterns info",
         inputSchema: { type: "object", properties: {} },
     },
+    {
+        name: "herald_gate",
+        description: `Request authorization before large operations.
+
+WHEN TO USE:
+Call this BEFORE multi-file operations (>3 files), module scaffolding, or bulk changes.
+
+This tool:
+1. Formats a clear authorization request for the user
+2. Returns a gate_id for tracking
+3. Records the operation scope for audit
+
+After calling this tool, WAIT for explicit user approval before proceeding.
+User may respond: Y/yes/proceed (approved), adjust (modify scope), or N/no (denied).
+
+Example flow:
+1. You complete synthesis/planning
+2. Call herald_gate with operation summary
+3. Tool returns formatted request
+4. STOP and wait for user response
+5. Only proceed if user approves`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                operation: {
+                    type: "string",
+                    description: "What operation needs authorization (e.g., 'Create bh-incidents module')"
+                },
+                scope: {
+                    type: "string",
+                    description: "Scope summary (e.g., '31 files, 6 dictionaries, 4 forms')"
+                },
+                template: {
+                    type: "string",
+                    description: "Template/pattern being followed (e.g., 'bh-inspections')"
+                },
+                rationale: {
+                    type: "string",
+                    description: "Brief rationale for the operation"
+                },
+            },
+            required: ["operation", "scope"],
+        },
+    },
     {
         name: "herald_predict",
         description: "Generate non-deterministic structure prediction from signal. Returns sessionId for multi-turn conversations.",
@@ -747,7 +892,7 @@ const tools = [
         inputSchema: {
             type: "object",
             properties: {
-                company: { type: "string", description: "Filter by company (optional, for backwards compatibility)" },
+                company: { type: "string", description: "Filter by company (optional, defaults to HERALD_COMPANY)" },
                 project: { type: "string", description: "Filter by project (optional)" },
                 user: { type: "string", description: "Filter by user (optional)" },
                 status: { type: "string", description: "Filter by status: active, archived, or expired (optional)" },
@@ -814,15 +959,28 @@ User's answer goes in the 'insight' parameter.
 
 DO NOT GUESS. The user knows what they valued. Ask them.
 
+ABSTRACTION GUIDANCE:
+Capture the PATTERN, not the SPECIFICS. Good patterns are reusable.
+- BAD: "Fixed bug in /Users/john/project/auth.ts line 47"
+- GOOD: "Early return pattern for auth validation reduces nesting"
+- BAD: "API key sk-proj-xxx was in wrong env file"
+- GOOD: "Secrets in .env.local not .env prevents accidental commits"
+
 Example flow:
 1. User: "That was smooth, capture it"
-2. You: "What specifically worked here?"
+2. You: "What specifically worked here? (Describe the pattern, not specific files/values)"
 3. User: "The ASCII visualization approach"
 4. You call herald_reflect with insight: "ASCII visualization approach"
 
-DRY RUN MODE (CEDA-65):
-Set dry_run=true to preview what would be captured without storing.
-Shows sanitization results and data classification.`,
+PRIVACY (CEDA-65):
+- Client-side sanitization runs BEFORE any data leaves your machine
+- API keys, tokens, passwords, file paths with usernames are auto-redacted
+- Private keys and AWS credentials are BLOCKED entirely
+- Use dry_run=true to preview exactly what would be transmitted
+
+DRY RUN MODE:
+Set dry_run=true to preview sanitization without storing.
+Shows what would be redacted and final transmitted text.`,
         inputSchema: {
             type: "object",
             properties: {
@@ -1060,6 +1218,124 @@ Returns all patterns for the current context (company/project/user) in the speci
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return { tools };
 });
+// ============================================
+// MCP RESOURCES - Auto-readable by Claude Code
+// ============================================
+// Helper to fetch patterns with cascade (reused from herald_patterns tool)
+async function fetchPatternsWithCascade() {
+    const seenInsights = new Set();
+    const patterns = [];
+    const antipatterns = [];
+    const queries = [
+        { scope: "user", url: `/api/herald/reflections?company=${HERALD_COMPANY}&project=${HERALD_PROJECT}&user=${HERALD_USER}&limit=10` },
+        { scope: "project", url: `/api/herald/reflections?company=${HERALD_COMPANY}&project=${HERALD_PROJECT}&limit=10` },
+        { scope: "company", url: `/api/herald/reflections?company=${HERALD_COMPANY}&limit=10` },
+    ];
+    for (const { scope, url } of queries) {
+        try {
+            const result = await callCedaAPI(url);
+            const scopePatterns = result.patterns || [];
+            const scopeAntipatterns = result.antipatterns || [];
+            for (const p of scopePatterns) {
+                const key = p.insight.toLowerCase().trim();
+                if (!seenInsights.has(key)) {
+                    seenInsights.add(key);
+                    patterns.push(`${p.insight} [${scope}]`);
+                }
+            }
+            for (const ap of scopeAntipatterns) {
+                const key = ap.insight.toLowerCase().trim();
+                if (!seenInsights.has(key)) {
+                    seenInsights.add(key);
+                    antipatterns.push(`${ap.insight} [${scope}]`);
+                }
+            }
+        }
+        catch {
+            // Continue if a level fails
+        }
+    }
+    return { patterns, antipatterns, context: `${HERALD_USER}→${HERALD_PROJECT}→${HERALD_COMPANY}` };
+}
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    const resources = [
+        {
+            uri: "herald://patterns",
+            name: "Herald Learned Patterns",
+            description: `Patterns and antipatterns learned from past sessions for ${HERALD_USER}→${HERALD_PROJECT}→${HERALD_COMPANY}. READ THIS AT SESSION START.`,
+            mimeType: "text/plain",
+        },
+        {
+            uri: "herald://context",
+            name: "Herald Context",
+            description: "Current Herald context configuration (company/project/user)",
+            mimeType: "application/json",
+        },
+    ];
+    return { resources };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    if (uri === "herald://patterns") {
+        try {
+            const { patterns, antipatterns, context } = await fetchPatternsWithCascade();
+            let content = `# Herald Patterns for ${context}\n\n`;
+            content += `**READ THIS FIRST** - These are learned patterns from past sessions.\n\n`;
+            if (antipatterns.length > 0) {
+                content += `## ⚠️ ANTIPATTERNS - AVOID THESE\n`;
+                antipatterns.forEach((ap, i) => {
+                    content += `${i + 1}. ${ap}\n`;
+                });
+                content += `\n`;
+            }
+            if (patterns.length > 0) {
+                content += `## ✓ PATTERNS - DO THESE\n`;
+                patterns.forEach((p, i) => {
+                    content += `${i + 1}. ${p}\n`;
+                });
+                content += `\n`;
+            }
+            if (patterns.length === 0 && antipatterns.length === 0) {
+                content += `No patterns learned yet. Capture patterns with "herald reflect" when you notice friction or flow.\n`;
+            }
+            content += `\n---\n*Auto-loaded from CEDA. Call herald_pattern_feedback() when a pattern helps.*\n`;
+            return {
+                contents: [{
+                        uri,
+                        mimeType: "text/plain",
+                        text: content,
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                contents: [{
+                        uri,
+                        mimeType: "text/plain",
+                        text: `Failed to load patterns: ${error}\n\nCEDA may be unavailable.`,
+                    }],
+            };
+        }
+    }
+    if (uri === "herald://context") {
+        const context = {
+            company: HERALD_COMPANY,
+            project: HERALD_PROJECT,
+            user: HERALD_USER,
+            vault: HERALD_VAULT || null,
+            autoDerived: CONTEXT_AUTO_DERIVED,
+            cedaUrl: CEDA_API_URL,
+        };
+        return {
+            contents: [{
+                    uri,
+                    mimeType: "application/json",
+                    text: JSON.stringify(context, null, 2),
+                }],
+        };
+    }
+    throw new Error(`Unknown resource: ${uri}`);
+});
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
@@ -1071,7 +1347,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 Welcome to Herald - your AI-native interface to CEDA (Cognitive Event-Driven Architecture).
 
 ## Current Context
-- Tags: ${CONTEXT_TAGS.join(", ")}
+- Company: ${HERALD_COMPANY}
+- Project: ${HERALD_PROJECT}
 - User: ${HERALD_USER}
 
 ## Available Tools
@@ -1129,17 +1406,19 @@ Herald will:
                 const cedaHealth = await callCedaAPI("/health");
                 const buffer = getBufferedInsights();
                 const cloudAvailable = !cedaHealth.error;
-                // CEDA-67: AI-native context - tags derived from cwd
                 const config = {
                     cedaUrl: CEDA_API_URL,
-                    tags: CONTEXT_TAGS,
+                    company: HERALD_COMPANY,
+                    project: HERALD_PROJECT,
                     user: HERALD_USER,
-                    cwd: process.cwd(),
                     vault: HERALD_VAULT || "(not set)",
+                    autoDerived: CONTEXT_AUTO_DERIVED,
                 };
                 const warnings = [];
-                if (CONTEXT_TAGS.length === 0)
-                    warnings.push("No context tags derived - check working directory");
+                if (CONTEXT_AUTO_DERIVED) {
+                    warnings.push(`Context auto-derived from folder: ${HERALD_COMPANY}/${HERALD_PROJECT}`);
+                    warnings.push("Run 'npx @spilno/herald-mcp init' for persistent config");
+                }
                 if (!process.env.CEDA_URL && !process.env.HERALD_API_URL) {
                     warnings.push("Using default CEDA_URL (getceda.com) - set CEDA_URL for custom endpoint");
                 }
@@ -1168,6 +1447,42 @@ Herald will:
                     content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
                 };
             }
+            case "herald_gate": {
+                const operation = args?.operation;
+                const scope = args?.scope;
+                const template = args?.template;
+                const rationale = args?.rationale;
+                // Generate gate ID for tracking
+                const gateId = `gate-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+                // Format the authorization request
+                let gateRequest = `\n## Authorization Required\n\n`;
+                gateRequest += `**Operation:** ${operation}\n`;
+                gateRequest += `**Scope:** ${scope}\n`;
+                if (template) {
+                    gateRequest += `**Template:** Following \`${template}\` patterns\n`;
+                }
+                if (rationale) {
+                    gateRequest += `**Rationale:** ${rationale}\n`;
+                }
+                gateRequest += `\n---\n`;
+                gateRequest += `**Proceed?** [Y/yes/proceed] [adjust] [N/no]\n`;
+                gateRequest += `\n_Gate ID: ${gateId}_\n`;
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                gate_id: gateId,
+                                status: "awaiting_authorization",
+                                message: gateRequest,
+                                operation,
+                                scope,
+                                template: template || null,
+                                instruction: "STOP HERE. Wait for user response before proceeding with any file operations.",
+                            }, null, 2)
+                        }],
+                };
+            }
             case "herald_predict": {
                 const signal = args?.signal;
                 const contextStr = args?.context;
@@ -1253,23 +1568,24 @@ Herald will:
                 const insight = args?.insight;
                 const targetVault = args?.target_vault;
                 const topic = args?.topic;
-                // CEDA-67: Use tags instead of company/project
                 const payload = {
                     insight,
                     topic,
                     targetVault,
                     sourceVault: HERALD_VAULT || undefined,
-                    tags: CONTEXT_TAGS,
+                    company: HERALD_COMPANY,
+                    project: HERALD_PROJECT,
                     user: HERALD_USER,
                 };
                 // Cloud-first: try to POST to CEDA, buffer locally on failure
                 // Map Herald's vault terminology to CEDA's context terminology
+                // Default toContext to "all" for guest mode / when no target specified
                 try {
                     const result = await callCedaAPI("/api/herald/insight", "POST", {
                         insight,
-                        toContext: targetVault,
+                        toContext: targetVault || "all", // Required by CEDA, default to broadcast
                         topic,
-                        fromContext: HERALD_VAULT,
+                        fromContext: HERALD_VAULT || `${HERALD_COMPANY}/${HERALD_PROJECT}`,
                     });
                     // Check if API returned an error
                     if (result.error) {
@@ -1353,8 +1669,8 @@ Herald will:
                         const result = await callCedaAPI("/api/herald/insight", "POST", {
                             insight: item.insight,
                             topic: item.topic,
-                            targetVault: item.targetVault,
-                            sourceVault: item.sourceVault,
+                            toContext: item.targetVault || "all", // CEDA expects toContext, default to "all"
+                            fromContext: item.sourceVault, // CEDA expects fromContext
                         });
                         if (result.error) {
                             failed.push(item);
@@ -1400,23 +1716,15 @@ Herald will:
             }
             // CEDA-49: Session Management Tools
             case "herald_session_list": {
-                // CEDA-67: Use tags for filtering, company/project for backwards compat
                 const company = args?.company;
                 const project = args?.project;
                 const user = args?.user;
                 const status = args?.status;
                 const limit = args?.limit;
                 const params = new URLSearchParams();
-                // Use tags by default, fall back to company/project if explicitly provided
-                if (company || project) {
-                    if (company)
-                        params.set("company", company);
-                    if (project)
-                        params.set("project", project);
-                }
-                else {
-                    params.set("tags", CONTEXT_TAGS.join(","));
-                }
+                params.set("company", company || HERALD_COMPANY);
+                if (project)
+                    params.set("project", project);
                 if (user)
                     params.set("user", user);
                 if (status)
@@ -1469,44 +1777,62 @@ Herald will:
                 const feeling = args?.feeling;
                 const insight = args?.insight;
                 const dryRun = args?.dry_run;
-                // CEDA-65: Dry-run mode - preview what would be captured without storing
+                // CEDA-65: Client-side sanitization preview (no network required)
+                const sessionPreview = previewSanitization(session);
+                const insightPreview = previewSanitization(insight);
+                // Check if content would be blocked
+                if (sessionPreview.wouldBlock || insightPreview.wouldBlock) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: false,
+                                    mode: "blocked",
+                                    error: "Content contains restricted data that cannot be transmitted",
+                                    blockReason: sessionPreview.blockReason || insightPreview.blockReason,
+                                    detectedTypes: [...sessionPreview.detectedTypes, ...insightPreview.detectedTypes],
+                                    hint: "Remove private keys, AWS credentials, or other restricted data before capturing.",
+                                }, null, 2)
+                            }],
+                        isError: true,
+                    };
+                }
+                // Dry-run mode - show sanitization preview without storing
                 if (dryRun) {
-                    try {
-                        const result = await callCedaAPI("/api/herald/reflect/dry-run", "POST", {
-                            session,
-                            feeling,
-                            insight,
-                            tags: CONTEXT_TAGS,
-                            user: HERALD_USER,
-                        });
-                        return {
-                            content: [{
-                                    type: "text",
-                                    text: JSON.stringify({
-                                        success: true,
-                                        mode: "dry-run",
-                                        message: "Preview of what would be captured (no data stored)",
-                                        feeling,
-                                        insight,
-                                        ...result,
-                                    }, null, 2)
-                                }],
-                        };
-                    }
-                    catch (error) {
-                        return {
-                            content: [{
-                                    type: "text",
-                                    text: JSON.stringify({
-                                        success: false,
-                                        mode: "dry-run",
-                                        error: `Dry-run failed: ${error}`,
-                                        hint: "CEDA may be unavailable. Try again later.",
-                                    }, null, 2)
-                                }],
-                        };
-                    }
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    mode: "dry-run",
+                                    message: "Preview of what would be captured (no data stored or transmitted)",
+                                    feeling,
+                                    sanitization: {
+                                        session: {
+                                            original: session,
+                                            sanitized: sessionPreview.sanitized,
+                                            wouldSanitize: sessionPreview.wouldSanitize,
+                                            detectedTypes: sessionPreview.detectedTypes,
+                                            classification: sessionPreview.classification,
+                                        },
+                                        insight: {
+                                            original: insight,
+                                            sanitized: insightPreview.sanitized,
+                                            wouldSanitize: insightPreview.wouldSanitize,
+                                            detectedTypes: insightPreview.detectedTypes,
+                                            classification: insightPreview.classification,
+                                        },
+                                    },
+                                    hint: insightPreview.wouldSanitize || sessionPreview.wouldSanitize
+                                        ? "Some content will be redacted. Consider using more abstract descriptions."
+                                        : "Content looks clean. Safe to capture.",
+                                }, null, 2)
+                            }],
+                    };
                 }
+                // Sanitize before transmission
+                const sanitizedSession = sessionPreview.sanitized;
+                const sanitizedInsight = insightPreview.sanitized;
                 // CEDA-64: Track reflection locally for session summary
                 addSessionReflection({
                     session,
@@ -1514,31 +1840,25 @@ Herald will:
                     insight,
                     method: "direct",
                 });
-                // Call CEDA's reflect endpoint with user's insight
+                // Call CEDA's reflect endpoint with SANITIZED insight
                 try {
                     const result = await callCedaAPI("/api/herald/reflect", "POST", {
-                        session,
+                        session: sanitizedSession,
                         feeling,
-                        insight, // User-provided insight - the actual pattern
+                        insight: sanitizedInsight, // Sanitized - no PII/secrets transmitted
                         method: "direct", // Track capture method for meta-learning
-                        tags: CONTEXT_TAGS,
+                        company: HERALD_COMPANY,
+                        project: HERALD_PROJECT,
                         user: HERALD_USER,
                         vault: HERALD_VAULT || undefined,
                     });
                     if (result.error) {
-                        // If cloud fails, store locally for later processing
-                        const localRecord = {
-                            session,
-                            feeling,
-                            tags: CONTEXT_TAGS,
-                            user: HERALD_USER,
-                            timestamp: new Date().toISOString(),
-                        };
-                        // Buffer as insight for later sync
+                        // If cloud fails, store locally for later processing (also sanitized)
                         bufferInsight({
-                            insight: `[REFLECT:${feeling}] ${insight} | Context: ${session}`,
+                            insight: `[REFLECT:${feeling}] ${sanitizedInsight} | Context: ${sanitizedSession}`,
                             topic: feeling === "stuck" ? "antipattern" : "pattern",
-                            tags: CONTEXT_TAGS,
+                            company: HERALD_COMPANY,
+                            project: HERALD_PROJECT,
                             user: HERALD_USER,
                         });
                         return {
@@ -1568,17 +1888,23 @@ Herald will:
                                     message: feeling === "stuck"
                                         ? `Antipattern captured: "${insight}"`
                                         : `Pattern captured: "${insight}"`,
+                                    context: {
+                                        company: HERALD_COMPANY,
+                                        project: HERALD_PROJECT,
+                                        autoDerived: CONTEXT_AUTO_DERIVED,
+                                    },
                                     ...result,
                                 }, null, 2)
                             }],
                     };
                 }
                 catch (error) {
-                    // Network error - buffer locally
+                    // Network error - buffer locally (sanitized)
                     bufferInsight({
-                        insight: `[REFLECT:${feeling}] ${insight} | Context: ${session}`,
+                        insight: `[REFLECT:${feeling}] ${sanitizedInsight} | Context: ${sanitizedSession}`,
                         topic: feeling === "stuck" ? "antipattern" : "pattern",
-                        tags: CONTEXT_TAGS,
+                        company: HERALD_COMPANY,
+                        project: HERALD_PROJECT,
                         user: HERALD_USER,
                     });
                     return {
@@ -1589,29 +1915,60 @@ Herald will:
                                     mode: "local",
                                     message: "Reflection buffered locally (cloud unreachable)",
                                     feeling,
-                                    insight,
+                                    insight: sanitizedInsight,
                                     hint: "Use herald_sync when cloud recovers.",
                                     buffered: true,
+                                    sanitized: sessionPreview.wouldSanitize || insightPreview.wouldSanitize,
                                 }, null, 2)
                             }],
                     };
                 }
             }
             case "herald_patterns": {
-                // Query learned patterns for current context
+                // Query learned patterns with inheritance: user → project → company
+                // More specific patterns take precedence over broader ones
                 try {
-                    const reflectionsResult = await callCedaAPI(`/api/herald/reflections?tags=${encodeURIComponent(CONTEXT_TAGS.join(","))}&user=${HERALD_USER}&limit=20`);
+                    // Helper to dedupe patterns by insight text (first occurrence wins)
+                    const seenInsights = new Set();
+                    const dedupePatterns = (items, scope) => {
+                        return items.filter(item => {
+                            const key = item.insight.toLowerCase().trim();
+                            if (seenInsights.has(key))
+                                return false;
+                            seenInsights.add(key);
+                            return true;
+                        }).map(item => ({ ...item, scope }));
+                    };
+                    // Cascade queries: user (most specific) → project → company (broadest)
+                    const queries = [
+                        { scope: "user", url: `/api/herald/reflections?company=${HERALD_COMPANY}&project=${HERALD_PROJECT}&user=${HERALD_USER}&limit=10` },
+                        { scope: "project", url: `/api/herald/reflections?company=${HERALD_COMPANY}&project=${HERALD_PROJECT}&limit=10` },
+                        { scope: "company", url: `/api/herald/reflections?company=${HERALD_COMPANY}&limit=10` },
+                    ];
+                    const patterns = [];
+                    const antipatterns = [];
+                    // Query each level, dedupe as we go (user patterns win over project, project over company)
+                    for (const { scope, url } of queries) {
+                        try {
+                            const result = await callCedaAPI(url);
+                            const scopePatterns = result.patterns || [];
+                            const scopeAntipatterns = result.antipatterns || [];
+                            patterns.push(...dedupePatterns(scopePatterns, scope));
+                            antipatterns.push(...dedupePatterns(scopeAntipatterns, scope));
+                        }
+                        catch {
+                            // Continue if a level fails (e.g., user not set)
+                        }
+                    }
                     const metaResult = await callCedaAPI("/api/herald/meta-patterns");
-                    // Format for Claude consumption
-                    const patterns = reflectionsResult.patterns || [];
-                    const antipatterns = reflectionsResult.antipatterns || [];
                     const metaPatterns = metaResult.metaPatterns || [];
-                    // Build readable summary
-                    let summary = `## Learned Patterns for ${HERALD_USER}→${CONTEXT_TAGS.join("→")}\n\n`;
+                    // Build readable summary with scope indicators
+                    let summary = `## Learned Patterns for ${HERALD_USER}→${HERALD_PROJECT}→${HERALD_COMPANY}\n\n`;
                     if (antipatterns.length > 0) {
                         summary += `### ⚠️ Antipatterns (avoid these)\n`;
                         antipatterns.slice(0, 5).forEach((ap, i) => {
-                            summary += `${i + 1}. ${ap.insight}`;
+                            const scopeTag = ap.scope ? ` [${ap.scope}]` : "";
+                            summary += `${i + 1}. ${ap.insight}${scopeTag}`;
                             if (ap.warning)
                                 summary += `\n   → ${ap.warning}`;
                             summary += `\n`;
@@ -1621,7 +1978,8 @@ Herald will:
                     if (patterns.length > 0) {
                         summary += `### ✓ Patterns (do these)\n`;
                         patterns.slice(0, 5).forEach((p, i) => {
-                            summary += `${i + 1}. ${p.insight}`;
+                            const scopeTag = p.scope ? ` [${p.scope}]` : "";
+                            summary += `${i + 1}. ${p.insight}${scopeTag}`;
                             if (p.reinforcement)
                                 summary += `\n   → ${p.reinforcement}`;
                             summary += `\n`;
@@ -1634,7 +1992,7 @@ Herald will:
                         summary += `Recommended capture method: ${meta.recommendedMethod} (${(meta.confidence * 100).toFixed(0)}% confidence)\n`;
                     }
                     if (patterns.length === 0 && antipatterns.length === 0) {
-                        summary = `No patterns learned yet for ${HERALD_USER}→${CONTEXT_TAGS.join("→")}.\n\nCapture patterns with "herald reflect" or "herald simulate" when you notice friction or flow.`;
+                        summary = `No patterns learned yet for ${HERALD_USER}→${HERALD_PROJECT}→${HERALD_COMPANY}.\n\nCapture patterns with "herald reflect" or "herald simulate" when you notice friction or flow.`;
                     }
                     return {
                         content: [{
@@ -1656,6 +2014,27 @@ Herald will:
                 const session = args?.session;
                 const feeling = args?.feeling;
                 const insight = args?.insight;
+                // CEDA-65: Client-side sanitization
+                const simSessionPreview = previewSanitization(session);
+                const simInsightPreview = previewSanitization(insight);
+                // Block restricted content
+                if (simSessionPreview.wouldBlock || simInsightPreview.wouldBlock) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: false,
+                                    mode: "blocked",
+                                    error: "Content contains restricted data that cannot be transmitted",
+                                    blockReason: simSessionPreview.blockReason || simInsightPreview.blockReason,
+                                    hint: "Remove private keys, AWS credentials, or other restricted data before capturing.",
+                                }, null, 2)
+                            }],
+                        isError: true,
+                    };
+                }
+                const simSanitizedSession = simSessionPreview.sanitized;
+                const simSanitizedInsight = simInsightPreview.sanitized;
                 // CEDA-64: Track reflection locally for session summary
                 addSessionReflection({
                     session,
@@ -1679,30 +2058,36 @@ Herald will:
                     };
                 }
                 try {
-                    // Build prompt and call AI for reflection
-                    const prompt = buildReflectionPrompt(session, feeling, insight);
+                    // Build prompt and call AI for reflection (use sanitized input)
+                    const prompt = buildReflectionPrompt(simSanitizedSession, feeling, simSanitizedInsight);
                     const extracted = await callAIForReflection(aiClient, prompt);
-                    // Send enriched data to CEDA
+                    // Sanitize AI-extracted fields too
+                    const sanitizedSignal = sanitize(extracted.signal || "").sanitizedText;
+                    const sanitizedReinforcement = extracted.reinforcement ? sanitize(extracted.reinforcement).sanitizedText : undefined;
+                    const sanitizedWarning = extracted.warning ? sanitize(extracted.warning).sanitizedText : undefined;
+                    // Send enriched data to CEDA (all sanitized)
                     const result = await callCedaAPI("/api/herald/reflect", "POST", {
-                        session,
+                        session: simSanitizedSession,
                         feeling,
-                        insight,
+                        insight: simSanitizedInsight,
                         method: "simulation", // Track capture method
-                        // AI-extracted fields
-                        signal: extracted.signal,
+                        // AI-extracted fields (sanitized)
+                        signal: sanitizedSignal,
                         outcome: extracted.outcome,
-                        reinforcement: extracted.reinforcement,
-                        warning: extracted.warning,
-                        tags: CONTEXT_TAGS,
+                        reinforcement: sanitizedReinforcement,
+                        warning: sanitizedWarning,
+                        company: HERALD_COMPANY,
+                        project: HERALD_PROJECT,
                         user: HERALD_USER,
                         vault: HERALD_VAULT || undefined,
                     });
                     if (result.error) {
-                        // Cloud failed but we have AI extraction - buffer with enriched data
+                        // Cloud failed but we have AI extraction - buffer with enriched data (sanitized)
                         bufferInsight({
-                            insight: `[SIMULATE:${feeling}] Signal: ${extracted.signal} | Insight: ${insight} | ${extracted.outcome === "pattern" ? `Reinforce: ${extracted.reinforcement}` : `Warn: ${extracted.warning}`}`,
+                            insight: `[SIMULATE:${feeling}] Signal: ${sanitizedSignal} | Insight: ${simSanitizedInsight} | ${extracted.outcome === "pattern" ? `Reinforce: ${sanitizedReinforcement}` : `Warn: ${sanitizedWarning}`}`,
                             topic: extracted.outcome,
-                            tags: CONTEXT_TAGS,
+                            company: HERALD_COMPANY,
+                            project: HERALD_PROJECT,
                             user: HERALD_USER,
                         });
                         return {
@@ -1809,7 +2194,8 @@ Herald will:
                         patternText,
                         outcome,
                         helped: outcome === "helped",
-                        tags: CONTEXT_TAGS,
+                        company: HERALD_COMPANY,
+                        project: HERALD_PROJECT,
                         user: HERALD_USER,
                     });
                     if (result.error) {
@@ -1859,7 +2245,8 @@ Herald will:
                         insight,
                         scope,
                         topic,
-                        sourceTags: CONTEXT_TAGS,
+                        sourceCompany: HERALD_COMPANY,
+                        sourceProject: HERALD_PROJECT,
                         sourceUser: HERALD_USER,
                         sourceVault: HERALD_VAULT || undefined,
                     });
@@ -1929,7 +2316,8 @@ Herald will:
                         patternId,
                         sessionId,
                         all: deleteAll,
-                        tags: CONTEXT_TAGS,
+                        company: HERALD_COMPANY,
+                        project: HERALD_PROJECT,
                         user: HERALD_USER,
                     });
                     if (result.error) {
@@ -1952,7 +2340,7 @@ Herald will:
                         message = `All patterns from session ${sessionId} deleted`;
                     }
                     else if (deleteAll) {
-                        message = `All patterns for ${HERALD_USER}→${CONTEXT_TAGS.join("→")} deleted`;
+                        message = `All patterns for ${HERALD_COMPANY}/${HERALD_PROJECT}/${HERALD_USER} deleted`;
                     }
                     return {
                         content: [{
@@ -1982,7 +2370,7 @@ Herald will:
             case "herald_export": {
                 const format = args?.format || "json";
                 try {
-                    const result = await callCedaAPI(`/api/herald/export?tags=${encodeURIComponent(CONTEXT_TAGS.join(","))}&user=${HERALD_USER}&format=${format}`);
+                    const result = await callCedaAPI(`/api/herald/export?company=${HERALD_COMPANY}&project=${HERALD_PROJECT}&user=${HERALD_USER}&format=${format}`);
                     if (result.error) {
                         return {
                             content: [{
@@ -2003,7 +2391,7 @@ Herald will:
                                     message: `Data exported in ${format.toUpperCase()} format (GDPR Art. 20)`,
                                     gdprArticle: "Article 20 - Right to Data Portability",
                                     format,
-                                    context: `${HERALD_USER}→${CONTEXT_TAGS.join("→")}`,
+                                    context: `${HERALD_COMPANY}/${HERALD_PROJECT}/${HERALD_USER}`,
                                     ...result,
                                 }, null, 2)
                             }],
@@ -2050,8 +2438,8 @@ async function autoSyncBuffer() {
             const result = await callCedaAPI("/api/herald/insight", "POST", {
                 insight: item.insight,
                 topic: item.topic,
-                targetVault: item.targetVault,
-                sourceVault: item.sourceVault,
+                toContext: item.targetVault || "all", // CEDA expects toContext
+                fromContext: item.sourceVault, // CEDA expects fromContext
             });
             if (result.error) {
                 failed.push(item);
@@ -2072,12 +2460,30 @@ async function autoSyncBuffer() {
         console.error(`[Herald] ${failed.length} insight(s) failed - will retry on next startup`);
     }
 }
+async function sendStartupHeartbeat() {
+    // Fire-and-forget heartbeat - don't block startup
+    try {
+        await callCedaAPI("/api/herald/heartbeat", "POST", {
+            event: "startup",
+            version: VERSION,
+            user: HERALD_USER,
+            tags: HERALD_TAGS,
+            contextSource: CONTEXT_SOURCE,
+            platform: process.platform,
+            nodeVersion: process.version,
+        });
+    }
+    catch {
+        // Silent fail - don't block MCP startup
+    }
+}
 async function runMCP() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("Herald MCP server running on stdio");
-    console.error(`Context: ${HERALD_USER}→${CONTEXT_TAGS.join("→")}`);
-    console.error("Tip: Call herald_patterns() to load learned patterns from past sessions");
+    console.error(`Herald MCP v${VERSION} running`);
+    console.error(`User: ${HERALD_USER} | Tags: [${HERALD_TAGS.join(", ")}] (${CONTEXT_SOURCE})`);
+    // Send startup heartbeat for visibility (non-blocking)
+    sendStartupHeartbeat();
     // Auto-sync buffered insights on startup
     await autoSyncBuffer();
 }