@rigour-labs/mcp 5.5.4 → 6.1.0-beta.1

package/dist/index.js

@@ -16,6 +16,7 @@ import { GateRunner } from "@rigour-labs/core";
 import { loadConfig, loadMcpSettings, logStudioEvent } from './utils/config.js';
 import { bindServer } from './utils/notifications.js';
 import { getMcpVersion } from './utils/package-version.js';
+import { buildMcpResultMeta, buildStudioImpact } from './utils/impact-receipt.js';
 // Dashboard (MCP App)
 import { DASHBOARD_URI, getDashboardHtml, pushTimelineEntry, updateScore } from './dashboard/index.js';
 // Tool definitions & advertised registry
@@ -32,9 +33,25 @@ import { handleCheckDeep, handleDeepStats } from './tools/deep-handlers.js';
 import { handleMcpGetSettings, handleMcpSetSettings } from './tools/mcp-settings-handler.js';
 import { handleContextStats, handleTaskCost, handleCacheStats, handleContextExplain, handleContextScope } from './tools/context-handlers.js';
 import { handleIndex } from './tools/index-handlers.js';
-import { recordContextEvent, estimateTokenCount } from '@rigour-labs/core';
+import { recordContextEvent, recordInteractionEvidence, recordInteractionLesson, syncTeamOutbox, estimateTokenCount } from '@rigour-labs/core';
 // ─── Server Setup ─────────────────────────────────────────────────
 const server = new Server({ name: "rigour-mcp", version: getMcpVersion('5.5.0') }, { capabilities: { tools: {}, prompts: {}, logging: {}, resources: {} } });
+function interactionMetadata(args) {
+    const input = (args && typeof args === 'object' ? args : {});
+    const rawFiles = Array.isArray(input.files)
+        ? input.files
+        : Array.isArray(input.filesChanged)
+            ? input.filesChanged
+            : Array.isArray(input.filesInScope)
+                ? input.filesInScope
+                : input.file ? [input.file] : [];
+    return {
+        taskId: String(input.taskId || input.task_id || '') || undefined,
+        agentId: String(input.agentId || input.agent_id || input.agent || '') || undefined,
+        sessionId: String(input.sessionId || input.session_id || '') || undefined,
+        files: rawFiles.filter((file) => typeof file === 'string').slice(0, 100),
+    };
+}
 // Bind server for logging notifications from handlers
 bindServer(server);
 // ─── Tool Listing ─────────────────────────────────────────────────
@@ -69,6 +86,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const requestId = randomUUID();
     try {
         await logStudioEvent(cwd, { type: "tool_call", requestId, tool: name, arguments: args });
+        try {
+            await recordInteractionEvidence(cwd, {
+                tool: name,
+                outcome: 'success',
+                phase: 'request',
+                requestId,
+                ...interactionMetadata(args),
+            });
+        }
+        catch {
+            // Evidence capture must never block the requested governance operation.
+        }
         // ── Image DLP warning ──────────────────────────────
         // MCP args may contain base64 image data. Text DLP cannot scan images.
         const argsStr = JSON.stringify(args ?? {});
@@ -136,7 +165,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 break;
             case "rigour_run_supervised": {
                 const { command, maxRetries = 3, dryRun = false } = args;
-                result = await handleRunSupervised(runner, cwd, command, maxRetries, dryRun, requestId, config);
+                result = await handleRunSupervised({
+                    runner,
+                    cwd,
+                    command,
+                    maxRetries,
+                    dryRun,
+                    requestId,
+                    config,
+                });
                 break;
             }
             // Multi-agent governance
@@ -225,12 +262,41 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     candidateTokens: telemetry?.candidateTokens ?? returnedTokens,
                     returnedTokens,
                     deduplicatedTokens: telemetry?.deduplicatedTokens ?? 0,
+                    candidateFiles: telemetry?.candidateFiles,
+                    returnedFiles: telemetry?.returnedFiles,
                 }, cwd);
             }
         }
         catch {
             // non-blocking context telemetry logging
         }
+        try {
+            const reportStatus = result?._rigour_report?.status;
+            const deterministic = Boolean(reportStatus === 'PASS');
+            const outcome = result?.isError ? 'error' : 'success';
+            await recordInteractionEvidence(cwd, {
+                tool: name,
+                outcome,
+                phase: 'response',
+                requestId,
+                deterministic,
+                summary: result?._guidance?.recommendation,
+                ...interactionMetadata(args),
+            });
+            await recordInteractionLesson(cwd, {
+                tool: name,
+                outcome,
+                requestId,
+                deterministic,
+                verifiedOutcome: deterministic,
+                summary: result?._guidance?.recommendation,
+                ...interactionMetadata(args),
+            });
+            void syncTeamOutbox().catch(() => undefined);
+        }
+        catch {
+            // Learning is evidence collection and must not block governance tools.
+        }
         // ── Prepend image DLP warning if image content was detected ──
         if (hasImageContent && Array.isArray(result.content)) {
             result.content.unshift({
@@ -238,9 +304,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 text: "⚠ DLP Notice: Image content detected in this request. Text-based credential scanning cannot analyze images. Avoid sharing screenshots containing API keys, tokens, or passwords.",
             });
         }
+        const studioImpact = buildStudioImpact(result._guidance, result._telemetry);
         await logStudioEvent(cwd, {
-            type: "tool_response", requestId, tool: name, status: "success",
-            content: result.content, _rigour_report: result._rigour_report,
+            type: "tool_response", requestId, tool: name, status: result.isError ? "error" : "success",
+            content: result.content,
+            _rigour_report: result._rigour_report,
+            ...studioImpact,
         });
         // ─── Dashboard State + MCP App UI Hint ──────────────
         const report = result._rigour_report;
@@ -253,7 +322,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         // Attach UI hint for MCP-App-capable clients (Claude Desktop, VS Code, ChatGPT, Goose)
         if (!result.isError) {
-            result._meta = { ui: { resourceUri: DASHBOARD_URI } };
+            result._meta = buildMcpResultMeta(result._meta, requestId, DASHBOARD_URI, result._guidance, result._telemetry);
         }
         // Notify clients that the dashboard resource has updated
         try {
@@ -272,6 +341,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             content: [{ type: "text", text: `RIGOUR ERROR: ${error.message}` }],
             isError: true,
         };
+        try {
+            await recordInteractionEvidence(cwd, {
+                tool: name,
+                outcome: 'error',
+                phase: 'response',
+                requestId,
+                summary: String(error?.message || 'Unknown error').slice(0, 500),
+                ...interactionMetadata(args),
+            });
+        }
+        catch {
+            // Failure evidence capture is intentionally non-blocking.
+        }
         await logStudioEvent(cwd, {
             type: "tool_response", requestId, tool: name,
             status: "error", error: error.message, content: errorResponse.content,

package/dist/tools/agent-handlers.js

@@ -9,8 +9,8 @@
 import fs from "fs-extra";
 import path from "path";
 import { logStudioEvent } from '../utils/config.js';
-import { setTaskCheckpointCache, getTaskCheckpointCache, estimateTokenCount, } from '@rigour-labs/core';
-import { PatternIndexer, savePatternIndex, loadPatternIndex, getDefaultIndexPath, } from '@rigour-labs/core/pattern-index';
+import { setTaskCheckpointCache, getTaskCheckpointCache, estimateTokenCount, updateAutomaticIndexForFiles, } from '@rigour-labs/core';
+import { loadPatternIndex, getDefaultIndexPath, } from '@rigour-labs/core/pattern-index';
 import { buildTelemetryMeta, getWorkspaceCommitSha } from '../utils/context-telemetry.js';
 import { appendContextFooter } from '../utils/context-footer.js';
 const HANDOFF_CONTEXT_TOKEN_LIMIT = 2000;
@@ -38,16 +38,9 @@ function globMatchesFile(filePath, glob) {
 async function refreshIndexForFiles(cwd, filesChanged) {
     if (filesChanged.length === 0)
         return null;
-    const indexPath = getDefaultIndexPath(cwd);
-    const existingIndex = await loadPatternIndex(indexPath);
-    if (!existingIndex) {
-        return 'Index not found — run rigour_index to enable incremental updates.';
-    }
     try {
-        const indexer = new PatternIndexer(cwd, { useEmbeddings: existingIndex.patterns.some(p => p.embedding?.length) });
-        const updated = await indexer.updateIndex(existingIndex);
-        await savePatternIndex(updated, indexPath);
-        return `Index refreshed for ${filesChanged.length} changed file(s) — ${updated.stats.totalPatterns} patterns total.`;
+        const { index, affectedFiles } = await updateAutomaticIndexForFiles(cwd, filesChanged);
+        return `Index refreshed ${filesChanged.length} changed and ${affectedFiles.length} affected file(s) — ${index.stats.totalPatterns} patterns total.`;
     }
     catch (error) {
         return `Index refresh failed: ${error.message}`;
@@ -82,6 +75,46 @@ async function validateTaskScopeAgainstIndex(cwd, taskScope) {
 }
 // ─── Agent Register ───────────────────────────────────────────────
 export async function handleAgentRegister(cwd, agentId, taskScope, requestId) {
+    const { validateAgentClaimedScope, loadOperatorScopes, isScopeSubset, } = await import('@rigour-labs/core');
+    const authority = process.env.RIGOUR_ALLOW_AGENT_SCOPE_AUTHORITY === '1';
+    if (!authority) {
+        const claimCheck = validateAgentClaimedScope(taskScope);
+        if (!claimCheck.ok) {
+            await logStudioEvent(cwd, {
+                type: 'firewall_deny',
+                requestId,
+                tool: 'rigour_agent_register',
+                decision: 'deny',
+                reason: claimCheck.reason,
+                ruleId: 'scope.register-denied',
+            });
+            return {
+                content: [{ type: 'text', text: `❌ SCOPE REGISTER DENIED: ${claimCheck.reason}` }],
+                isError: true,
+            };
+        }
+    }
+    const operatorScopes = await loadOperatorScopes(cwd);
+    if (operatorScopes) {
+        const allowed = operatorScopes[agentId];
+        if (!allowed || !isScopeSubset(taskScope, allowed)) {
+            const msg = allowed
+                ? `Claimed scope is not a subset of operator scopes for "${agentId}": ${allowed.join(', ')}`
+                : `No operator scopes defined for agent "${agentId}" in .rigour/operator-scopes.json`;
+            await logStudioEvent(cwd, {
+                type: 'firewall_deny',
+                requestId,
+                tool: 'rigour_agent_register',
+                decision: 'deny',
+                reason: msg,
+                ruleId: 'scope.operator-required',
+            });
+            return {
+                content: [{ type: 'text', text: `❌ SCOPE REGISTER DENIED: ${msg}` }],
+                isError: true,
+            };
+        }
+    }
     const sessionPath = path.join(cwd, '.rigour', 'agent-session.json');
     let session = { agents: [], startedAt: new Date().toISOString() };
     if (await fs.pathExists(sessionPath)) {

package/dist/tools/context-handlers.js

@@ -11,7 +11,7 @@
 import fs from 'fs-extra';
 import path from 'path';
 import { createHash } from 'crypto';
-import { getTaskContextStats, getTaskCostStats, getCacheStats, explainContext, getSemanticQueryCache, setSemanticQueryCache, findRelatedSemanticQueryCache, filterExistingEditScope, estimateTokenCount, } from '@rigour-labs/core';
+import { getTaskContextStats, getTaskCostStats, getCacheStats, explainContext, getSemanticQueryCache, setSemanticQueryCache, findRelatedSemanticQueryCache, filterExistingEditScope, estimateTokenCount, ensureAutomaticIndex, getApplicableLessons, searchTeamKnowledge, } from '@rigour-labs/core';
 import { loadPatternIndex, getDefaultIndexPath, generateEmbedding, semanticSearch, } from '@rigour-labs/core/pattern-index';
 import { buildTelemetryMeta, getWorkspaceCommitSha } from '../utils/context-telemetry.js';
 import { appendContextFooter } from '../utils/context-footer.js';
@@ -107,6 +107,10 @@ function scopeTelemetryMeta(opts) {
         taskId: opts.taskId,
         agentId: opts.agentId,
         queryHash: hashScopeQuery(opts.query),
+        candidateTokens: opts.candidateTokens,
+        returnedTokens: opts.returnedTokens,
+        candidateFiles: opts.candidateFiles,
+        returnedFiles: opts.returnedFiles,
     });
 }
 function textMatchPatterns(query, patterns, limit) {
@@ -155,6 +159,7 @@ async function serveCachedScope(cached, opts) {
         cacheNote: opts.note,
     };
     const cachedText = JSON.stringify(payload, null, 2);
+    const returnedTokens = estimateTokenCount(cachedText);
     const telemetry = scopeTelemetryMeta({
         candidateText: opts.fullIndexCandidate,
         returnedText: cachedText,
@@ -162,6 +167,11 @@ async function serveCachedScope(cached, opts) {
         query: opts.query,
         taskId: opts.taskId,
         agentId: opts.agentId,
+        candidateTokens: cached.sourceTokens,
+        returnedTokens,
+        candidateFiles: cached.candidateFiles,
+        returnedFiles: valid.length,
+        deduplicatedTokens: Math.max(0, (cached.sourceTokens ?? returnedTokens) - returnedTokens),
     });
     const label = opts.cacheStatus === 'partial-hit'
         ? 'CONTEXT SCOPE (partial cache)'
@@ -170,6 +180,15 @@ async function serveCachedScope(cached, opts) {
     return {
         content: [{ type: 'text', text: appendContextFooter(text, telemetry, 'rigour_check_pattern before creating code') }],
         _telemetry: telemetry,
+        _guidance: {
+            ...(cached.guidance ?? {
+                kind: 'context-scope',
+                recommendation: `Reuse the cached scope of ${valid.length} file(s).`,
+            }),
+            query: opts.query,
+            selectedFiles: valid,
+            excludedFileCount: Math.max(0, (cached.candidateFiles ?? valid.length) - valid.length),
+        },
     };
 }
 export async function handleContextScope(cwd, query, limit = 10, taskId, agentId) {
@@ -205,22 +224,9 @@ export async function handleContextScope(cwd, query, limit = 10, taskId, agentId
         if (served)
             return served;
     }
-    const index = await loadPatternIndex(indexPath);
-    if (!index) {
-        const text = '⚠️ Pattern index not found. Call rigour_index first to enable scoped context retrieval.\n\n'
-            + 'Without an index, agents tend to read entire directories — wasting tokens.';
-        return {
-            content: [{ type: 'text', text }],
-            _telemetry: scopeTelemetryMeta({
-                candidateText: fullIndexCandidate,
-                returnedText: text,
-                cacheStatus: 'miss',
-                query,
-                taskId,
-                agentId,
-            }),
-        };
-    }
+    const index = await loadPatternIndex(indexPath) ?? await ensureAutomaticIndex(cwd, {
+        backgroundSemantic: process.env.NODE_ENV !== 'test',
+    });
     let matched = [];
     const hasEmbeddings = index.patterns.some(p => p.embedding && p.embedding.length > 0);
     if (hasEmbeddings) {
@@ -252,6 +258,10 @@ export async function handleContextScope(cwd, query, limit = 10, taskId, agentId
         .slice(0, Math.max(0, 20 - editScope.length))
         .map(f => ({ file: f, reason: 'Outside semantic match for query' }));
     const signatures = matched.map(p => `- ${p.file}:${p.line} ${p.type} ${p.name} — ${p.signature || p.description || '(no signature)'}`);
+    const [applicableLearning, semanticKnowledge] = await Promise.all([
+        getApplicableLessons(cwd, agentId, process.env.RIGOUR_TEAM_ID),
+        searchTeamKnowledge(query, Math.min(limit, 8)),
+    ]);
     let fullFileTokens = 0;
     for (const file of editScope) {
         try {
@@ -262,22 +272,51 @@ export async function handleContextScope(cwd, query, limit = 10, taskId, agentId
             fullFileTokens += 500;
         }
     }
+    const guidance = {
+        kind: 'context-scope',
+        query,
+        recommendation: editScope.length > 0
+            ? `Read only the ${editScope.length} evidence-backed file(s) in this scope.`
+            : 'Refine the task query before reading broadly.',
+        patternRefs: matched.map(pattern => ({ id: pattern.id, label: pattern.name, file: pattern.file })),
+        lessonRefs: applicableLearning.lessons.map(lesson => ({ id: lesson.id, label: lesson.subject, visibility: lesson.visibility })),
+        selectedFiles: editScope,
+        excludedFileCount: Math.max(0, index.stats.totalFiles - editScope.length),
+        conflicts: applicableLearning.conflicts.length,
+    };
     const scopePayload = {
         query,
         editScope,
         skipScope,
         signatures,
+        learningGuidance: applicableLearning.lessons.map(lesson => ({
+            subject: lesson.subject,
+            scope: lesson.repositoryId,
+            visibility: lesson.visibility,
+            confidence: lesson.confidence,
+            provenance: lesson.provenance,
+        })),
+        learningConflicts: applicableLearning.conflicts,
+        semanticKnowledge: {
+            ...semanticKnowledge,
+            purpose: 'Advisory cross-repository recall only; similarity never promotes or enforces a lesson.',
+        },
         indexHealth: {
             totalPatterns: index.stats.totalPatterns,
             totalFiles: index.stats.totalFiles,
             lastUpdated: index.lastUpdated,
             semanticEnabled: hasEmbeddings,
         },
-        estimatedTokensSaved: Math.max(0, fullFileTokens - estimateTokenCount(signatures.join('\n'))),
+        estimatedTokensSaved: 0,
         recommendation: editScope.length > 0
             ? `Read ONLY these ${editScope.length} file(s). Do NOT scan the whole repo.`
             : 'No strong matches — refine query or run rigour_index --semantic',
     };
+    // Compare compact guidance with the raw contents of the selected files only.
+    // Repository-wide files excluded by structural matching are reported separately.
+    let resultText = JSON.stringify(scopePayload, null, 2);
+    scopePayload.estimatedTokensSaved = Math.max(0, fullFileTokens - estimateTokenCount(resultText));
+    resultText = JSON.stringify(scopePayload, null, 2);
     await setSemanticQueryCache(query, commitSha, {
         query,
         resolvedOwner: editScope[0] ? path.dirname(editScope[0]) : 'unknown',
@@ -286,8 +325,11 @@ export async function handleContextScope(cwd, query, limit = 10, taskId, agentId
         evidence: signatures.slice(0, 5),
         commitSha,
         confidence: matched.length > 0 ? 0.85 : 0.3,
+        sourceTokens: fullFileTokens,
+        candidateFiles: index.stats.totalFiles,
+        returnedFiles: editScope.length,
+        guidance,
     }, cwd);
-    const resultText = JSON.stringify(scopePayload, null, 2);
     const telemetry = scopeTelemetryMeta({
         candidateText: fullIndexCandidate,
         returnedText: resultText,
@@ -296,6 +338,10 @@ export async function handleContextScope(cwd, query, limit = 10, taskId, agentId
         query,
         taskId,
         agentId,
+        candidateTokens: fullFileTokens,
+        returnedTokens: estimateTokenCount(resultText),
+        candidateFiles: index.stats.totalFiles,
+        returnedFiles: editScope.length,
     });
     return {
         content: [{
@@ -303,5 +349,6 @@ export async function handleContextScope(cwd, query, limit = 10, taskId, agentId
                 text: appendContextFooter(`CONTEXT SCOPE\n\n${resultText}`, telemetry, 'rigour_check_pattern before creating code'),
             }],
         _telemetry: telemetry,
+        _guidance: guidance,
     };
 }

package/dist/tools/execution-handlers.d.ts

@@ -8,5 +8,17 @@ type ToolResult = {
     isError?: boolean;
 };
 export declare function handleRun(cwd: string, command: string, requestId: string): Promise<ToolResult>;
-export declare function handleRunSupervised(runner: GateRunner, cwd: string, command: string, maxRetries: number, dryRun: boolean, requestId: string, config?: Config): Promise<ToolResult>;
+export declare function handleRunSupervised(opts: {
+    runner: GateRunner;
+    cwd: string;
+    command: string;
+    maxRetries: number;
+    dryRun: boolean;
+    requestId: string;
+    config?: Config;
+}): Promise<ToolResult>;
+/**
+ * Fail-closed: timeout with no human decision → timeout-deny (not approve).
+ */
+export declare function pollArbitration(cwd: string, rid: string, timeout: number): Promise<string | null>;
 export {};

package/dist/tools/execution-handlers.js

@@ -2,35 +2,76 @@
  * Execution & Supervision Tool Handlers
  *
  * Handlers for: rigour_run, rigour_run_supervised
- *
- * @since v2.17.0 — extracted from monolithic index.ts
+ * Agent Transaction Firewall: fail-closed arbitration + typed commands.
  */
 import fs from "fs-extra";
 import path from "path";
-import { FixPacketService } from "@rigour-labs/core";
+import { FixPacketService, runTypedCommand, evaluateTypedCommand, issueArbitrationToken, } from "@rigour-labs/core";
 import { logStudioEvent } from '../utils/config.js';
 import { notifyProgress } from '../utils/notifications.js';
-export async function handleRun(cwd, command, requestId) {
-    // 1. Log Interceptable Event
+async function requireHumanApproval(cwd, command, requestId, tool) {
+    const arbitrationToken = await issueArbitrationToken(cwd, requestId, 60_000);
     await logStudioEvent(cwd, {
         type: "interception_requested",
         requestId,
-        tool: "rigour_run",
+        tool,
         command,
+        arbitrationToken,
     });
-    // 2. Poll for Human Arbitration (Max 60s wait)
     console.error(`[RIGOUR] Waiting for human arbitration for command: ${command}`);
     const decision = await pollArbitration(cwd, requestId, 60000);
-    if (decision === 'reject') {
+    if (decision === 'approve')
+        return null;
+    await logStudioEvent(cwd, {
+        type: "firewall_deny",
+        requestId,
+        tool: "human_arbitration",
+        decision: decision ?? 'timeout-deny',
+        reason: decision === 'reject' ? 'Human rejected' : 'Arbitration timed out (fail-closed)',
+    });
+    return {
+        content: [{
+                type: "text",
+                text: decision === 'reject'
+                    ? `❌ COMMAND REJECTED BY GOVERNOR: The execution of "${command}" was blocked by a human operator in the Governance Studio.`
+                    : `❌ COMMAND DENIED (fail-closed): No human arbitration within 60s for "${command}".`,
+            }],
+        isError: true,
+    };
+}
+export async function handleRun(cwd, command, requestId) {
+    const typed = evaluateTypedCommand(command);
+    await logStudioEvent(cwd, {
+        type: "firewall_precheck",
+        requestId,
+        tool: "rigour_run",
+        command,
+        firewallDecision: typed.decision,
+        firewallReason: typed.reason,
+        ruleId: typed.ruleId,
+    });
+    if (typed.decision !== 'allow') {
+        await logStudioEvent(cwd, {
+            type: "firewall_deny",
+            requestId,
+            tool: "rigour_run",
+            decision: typed.decision,
+            reason: typed.reason,
+            ruleId: typed.ruleId,
+        });
         return {
-            content: [{ type: "text", text: `❌ COMMAND REJECTED BY GOVERNOR: The execution of "${command}" was blocked by a human operator in the Governance Studio.` }],
+            content: [{
+                    type: "text",
+                    text: `❌ FIREWALL DENY (${typed.ruleId}): ${typed.reason}\nCommand: ${command}`,
+                }],
             isError: true,
         };
     }
-    // Execute
-    const { execa } = await import("execa");
+    const denied = await requireHumanApproval(cwd, command, requestId, "rigour_run");
+    if (denied)
+        return denied;
     try {
-        const { stdout, stderr } = await execa(command, { shell: true, cwd });
+        const { stdout, stderr } = await runTypedCommand(command, cwd);
         return {
             content: [{ type: "text", text: `✅ COMMAND EXECUTED (Approved by Governor):\n\nSTDOUT:\n${stdout}\n\nSTDERR:\n${stderr}` }],
         };
@@ -42,8 +83,29 @@ export async function handleRun(cwd, command, requestId) {
         };
     }
 }
-export async function handleRunSupervised(runner, cwd, command, maxRetries, dryRun, requestId, config) {
-    const { execa } = await import("execa");
+export async function handleRunSupervised(opts) {
+    const { runner, cwd, command, maxRetries, dryRun, requestId, config } = opts;
+    const typed = evaluateTypedCommand(command);
+    if (typed.decision !== 'allow') {
+        await logStudioEvent(cwd, {
+            type: "firewall_deny",
+            requestId,
+            tool: "rigour_run_supervised",
+            decision: typed.decision,
+            reason: typed.reason,
+            ruleId: typed.ruleId,
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: `❌ FIREWALL DENY (${typed.ruleId}): ${typed.reason}\nCommand: ${command}`,
+                }],
+            isError: true,
+        };
+    }
+    const denied = await requireHumanApproval(cwd, command, requestId, "rigour_run_supervised");
+    if (denied)
+        return denied;
     let iteration = 0;
     let lastReport = null;
     let result = null;
@@ -61,7 +123,7 @@ export async function handleRunSupervised(runner, cwd, command, maxRetries, dryR
         notifyProgress("info", `Supervisor iteration ${iteration}/${maxRetries}...`);
         if (!dryRun) {
             try {
-                await execa(command, { shell: true, cwd });
+                await runTypedCommand(command, cwd);
             }
             catch (e) {
                 console.error(`[RIGOUR] Iteration ${iteration} command error: ${e.message}`);
@@ -99,7 +161,6 @@ export async function handleRunSupervised(runner, cwd, command, maxRetries, dryR
         }
         if (iteration >= maxRetries) {
             notifyProgress("error", `Supervisor FAILED after ${iteration} iterations \u2014 ${lastReport.failures.length} violations remain`);
-            // Use FixPacketService for structured output instead of ad-hoc formatting
             let fixPacketText;
             if (config) {
                 const fixPacketService = new FixPacketService();
@@ -107,7 +168,6 @@ export async function handleRunSupervised(runner, cwd, command, maxRetries, dryR
                 fixPacketText = formatFixPacketForSupervisor(fixPacket);
             }
             else {
-                // Fallback if config not available
                 fixPacketText = lastReport.failures.map((f, i) => {
                     const sevTag = `[${(f.severity || 'medium').toUpperCase()}]`;
                     return `${i + 1}. ${sevTag} [${f.id}] ${f.title}: ${f.details}${f.files?.length ? ` (${f.files.join(', ')})` : ''}`;
@@ -168,28 +228,44 @@ function formatFixPacketForSupervisor(fixPacket) {
     }
     return lines.join('\n');
 }
-// ─── Private Helpers ──────────────────────────────────────────────
-async function pollArbitration(cwd, rid, timeout) {
-    const start = Date.now();
+/**
+ * Fail-closed: timeout with no human decision → timeout-deny (not approve).
+ */
+export async function pollArbitration(cwd, rid, timeout) {
     const eventsPath = path.join(cwd, '.rigour/events.jsonl');
-    while (Date.now() - start < timeout) {
-        if (await fs.pathExists(eventsPath)) {
-            const content = await fs.readFile(eventsPath, 'utf-8');
-            const lines = content.split('\n').filter(l => l.trim());
-            for (const line of lines.reverse()) {
-                let event;
-                try {
-                    event = JSON.parse(line);
-                }
-                catch {
-                    continue;
-                }
-                if (event.tool === 'human_arbitration' && event.requestId === rid) {
-                    return event.decision;
-                }
-            }
+    const maxIterations = Math.max(1, Math.ceil(timeout / 1000));
+    for (let i = 0; i < maxIterations; i++) {
+        const found = await readArbitrationDecision(eventsPath, rid);
+        if (found)
+            return found;
+        await sleepMs(1000);
+    }
+    return "timeout-deny";
+}
+async function readArbitrationDecision(eventsPath, rid) {
+    if (!(await fs.pathExists(eventsPath)))
+        return null;
+    const content = await fs.readFile(eventsPath, 'utf-8');
+    const lines = content.split('\n').filter(l => l.trim());
+    for (const line of lines.reverse()) {
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (event.tool === 'human_arbitration' && event.requestId === rid) {
+            return event.decision;
         }
-        await new Promise(r => setTimeout(r, 1000));
     }
-    return "approve"; // Default auto-approve if no human response
+    return null;
+}
+function sleepMs(ms) {
+    return new Promise(resolve => {
+        const timerId = setTimeout(() => {
+            clearTimeout(timerId);
+            resolve();
+        }, ms);
+    });
 }

package/dist/tools/hooks-handler.js

@@ -7,7 +7,7 @@
  * @since v3.0.0 — real-time hooks for AI coding tools
  * @since v4.2.0 — AI Agent DLP warning layer
  */
-import { runHookChecker, generateHookFiles } from "@rigour-labs/core";
+import { runHookChecker, generateHookFiles, updateAutomaticIndexForFiles } from "@rigour-labs/core";
 import { scanInputForCredentials, formatDLPAlert, createDLPAuditEntry, generateDLPHookFiles } from "@rigour-labs/core";
 import fs from "fs-extra";
 import path from "path";
@@ -73,7 +73,12 @@ export async function handleHooksCheck(cwd, files, timeout, text, agent) {
     const input = { cwd, files };
     if (timeout)
         input.timeout_ms = timeout;
+    if (agent)
+        input.agentId = agent;
     const result = await runHookChecker(input);
+    if (files.length > 0) {
+        await updateAutomaticIndexForFiles(cwd, files).catch(() => undefined);
+    }
     if (result.status === 'pass') {
         return {
             content: [{

package/dist/tools/index-handlers.js

@@ -52,7 +52,7 @@ export async function handleIndex(cwd, options = {}) {
     const candidateEstimate = 'Full codebase AST scan for pattern extraction';
     try {
         notifyProgress('info', 'Building pattern index...');
-        const indexer = new PatternIndexer(cwd, { useEmbeddings: options.semantic ?? false });
+        const indexer = new PatternIndexer(cwd, { useEmbeddings: options.semantic ?? true });
         const existingIndex = await loadPatternIndex(indexPath);
         let index;
         if (existingIndex && !options.force) {

package/dist/tools/memory-handlers.js

@@ -60,7 +60,7 @@ async function getIndexHealthBlock(cwd) {
     }
     return `\n\n📊 Pattern Index: ${index.stats.totalPatterns} patterns across ${index.stats.totalFiles} files (updated ${index.lastUpdated}).`;
 }
-function wrapRecallResult(text, candidateText, cacheStatus, deduplicatedTokens = 0) {
+function wrapRecallResult(text, candidateText, cacheStatus, deduplicatedTokens = 0, guidance) {
     const telemetry = buildTelemetryMeta({
         candidateText,
         returnedText: text,
@@ -73,6 +73,7 @@ function wrapRecallResult(text, candidateText, cacheStatus, deduplicatedTokens =
                 text: appendContextFooter(text, telemetry, 'rigour_context_scope("your task")'),
             }],
         _telemetry: telemetry,
+        _guidance: guidance,
     };
 }
 export async function handleRemember(cwd, key, value) {
@@ -137,7 +138,12 @@ export async function handleRecall(cwd, key) {
     if (cached?.evidence?.length) {
         const cachedBody = cached.evidence.join('\n');
         const indexHealth = await getIndexHealthBlock(cwd);
-        return wrapRecallResult(`${cachedBody}${indexHealth}`, candidateText, 'semantic-hit', Math.max(0, estimateTokenCount(candidateText) - estimateTokenCount(cachedBody)));
+        return wrapRecallResult(`${cachedBody}${indexHealth}`, candidateText, 'semantic-hit', Math.max(0, estimateTokenCount(candidateText) - estimateTokenCount(cachedBody)), cached.guidance ?? {
+            kind: 'memory',
+            query: key ?? 'all memories',
+            recommendation: key ? `Apply recalled memory "${key}" where relevant.` : 'Apply the recalled project memories where relevant.',
+            memoryRefs: key ? [{ id: key, label: key }] : [],
+        });
     }
     if (key) {
         const memory = store.memories[key];
@@ -164,6 +170,12 @@ export async function handleRecall(cwd, key) {
         const body = `RECALLED MEMORY [${key}]:\n${memory.value}\n\n(Stored: ${memory.timestamp})`;
         const indexHealth = await getIndexHealthBlock(cwd);
         const fullText = `${body}${indexHealth}`;
+        const guidance = {
+            kind: 'memory',
+            query: key,
+            recommendation: `Apply recalled memory "${key}" where relevant.`,
+            memoryRefs: [{ id: key, label: key }],
+        };
         await setSemanticQueryCache(cacheQuery, commitSha, {
             query: cacheQuery,
             resolvedOwner: 'memory',
@@ -172,8 +184,9 @@ export async function handleRecall(cwd, key) {
             evidence: [body],
             commitSha,
             confidence: 1,
+            guidance,
         }, cwd);
-        return wrapRecallResult(fullText, candidateText, 'miss');
+        return wrapRecallResult(fullText, candidateText, 'miss', 0, guidance);
     }
     const keys = Object.keys(store.memories);
     if (keys.length === 0) {
@@ -207,6 +220,12 @@ export async function handleRecall(cwd, key) {
         text = "NO MEMORIES STORED. Use rigour_remember to persist important instructions.";
     }
     text += await getIndexHealthBlock(cwd);
+    const guidance = {
+        kind: 'memory',
+        query: 'all memories',
+        recommendation: `Apply ${cleanMemories.length} recalled project memory item(s) where relevant.`,
+        memoryRefs: keys.filter(k => !taintedKeys.includes(k)).map(k => ({ id: k, label: k })),
+    };
     await setSemanticQueryCache(cacheQuery, commitSha, {
         query: cacheQuery,
         resolvedOwner: 'memory',
@@ -215,8 +234,9 @@ export async function handleRecall(cwd, key) {
         evidence: [text],
         commitSha,
         confidence: 1,
+        guidance,
     }, cwd);
-    return wrapRecallResult(text, candidateText, 'miss', Math.max(0, estimateTokenCount(candidateText) - estimateTokenCount(text)));
+    return wrapRecallResult(text, candidateText, 'miss', Math.max(0, estimateTokenCount(candidateText) - estimateTokenCount(text)), guidance);
 }
 export async function handleForget(cwd, key) {
     const store = await loadMemory(cwd);

package/dist/tools/pattern-handlers.js

@@ -68,9 +68,15 @@ export async function handleCheckPattern(cwd, patternName, type, intent, file) {
                     text: appendContextFooter(cachedText, telemetry, 'proceed with implementation or rigour_check when done'),
                 }],
             _telemetry: telemetry,
+            _guidance: cached.guidance ?? {
+                kind: 'pattern',
+                query: patternName,
+                recommendation: `Apply the cached pattern guidance for "${patternName}".`,
+            },
         };
     }
     let resultText = "";
+    let matchedPattern;
     // 0. File Guard — BLOCK writes to protected paths
     if (file) {
         const matched = await checkFileGuard(cwd, file);
@@ -88,6 +94,12 @@ export async function handleCheckPattern(cwd, patternName, type, intent, file) {
             return {
                 content: [{ type: "text", text: appendContextFooter(resultText, telemetry) }],
                 _telemetry: telemetry,
+                _guidance: {
+                    kind: 'pattern',
+                    query: patternName,
+                    recommendation: `STOP. Do not modify protected path "${file}" without human review.`,
+                    selectedFiles: [file],
+                },
             };
         }
     }
@@ -96,6 +108,7 @@ export async function handleCheckPattern(cwd, patternName, type, intent, file) {
         const matcher = new PatternMatcher(index);
         const matchResult = await matcher.match({ name: patternName, type, intent });
         if (matchResult.status === "FOUND_SIMILAR") {
+            matchedPattern = matchResult.matches[0].pattern;
             resultText += `🚨 PATTERN REINVENTION DETECTED\n`;
             resultText += `Similar pattern already exists: "${matchResult.matches[0].pattern.name}" in ${matchResult.matches[0].pattern.file}\n`;
             resultText += `SUGGESTION: ${matchResult.suggestion}\n\n`;
@@ -128,11 +141,12 @@ export async function handleCheckPattern(cwd, patternName, type, intent, file) {
             resultText += `\n`;
         }
     }
+    let recommendation = 'Proceed with implementation; no conflicting codebase pattern was found.';
     if (!resultText) {
         resultText = `✅ Pattern "${patternName}" is fresh, secure, and unique to the codebase.\n\nRECOMMENDED ACTION: Proceed with implementation.`;
     }
     else {
-        let recommendation = "Proceed with caution, addressing the warnings above.";
+        recommendation = "Proceed with caution, addressing the warnings above.";
         if (resultText.includes("🚨 PATTERN REINVENTION")) {
             recommendation = "STOP and REUSE the existing pattern mentioned above. Do not create a duplicate.";
         }
@@ -144,6 +158,13 @@ export async function handleCheckPattern(cwd, patternName, type, intent, file) {
         }
         resultText += `\nRECOMMENDED ACTION: ${recommendation}`;
     }
+    const guidance = {
+        kind: 'pattern',
+        query: patternName,
+        recommendation,
+        patternRefs: matchedPattern ? [{ id: matchedPattern.id, label: matchedPattern.name, file: matchedPattern.file }] : [],
+        selectedFiles: file ? [file] : matchedPattern?.file ? [matchedPattern.file] : [],
+    };
     await setSemanticQueryCache(cacheQuery, commitSha, {
         query: cacheQuery,
         resolvedOwner: file ? path.dirname(file) : 'patterns',
@@ -152,6 +173,7 @@ export async function handleCheckPattern(cwd, patternName, type, intent, file) {
         evidence: [resultText],
         commitSha,
         confidence: resultText.includes('✅') ? 0.9 : 0.7,
+        guidance,
     }, cwd);
     const telemetry = buildTelemetryMeta({
         candidateText: indexScanEstimate,
@@ -167,6 +189,7 @@ export async function handleCheckPattern(cwd, patternName, type, intent, file) {
                 text: appendContextFooter(resultText, telemetry, 'rigour_check before declaring done'),
             }],
         _telemetry: telemetry,
+        _guidance: guidance,
     };
 }
 export async function handleSecurityAudit(cwd) {

package/dist/utils/context-telemetry.d.ts

@@ -8,8 +8,32 @@ export type TelemetryMeta = {
     taskId?: string;
     agentId?: string;
     queryHash?: string;
+    candidateFiles?: number;
+    returnedFiles?: number;
     skipRecording?: boolean;
 };
+export type GuidanceMeta = {
+    kind: 'context-scope' | 'pattern' | 'memory';
+    query?: string;
+    recommendation: string;
+    patternRefs?: Array<{
+        id: string;
+        label: string;
+        file?: string;
+    }>;
+    lessonRefs?: Array<{
+        id: string;
+        label: string;
+        visibility?: string;
+    }>;
+    memoryRefs?: Array<{
+        id: string;
+        label: string;
+    }>;
+    selectedFiles?: string[];
+    excludedFileCount?: number;
+    conflicts?: number;
+};
 export type ToolResult = {
     content: {
         type: string;
@@ -20,6 +44,7 @@ export type ToolResult = {
     _rigour_report?: unknown;
     _meta?: unknown;
     _telemetry?: TelemetryMeta;
+    _guidance?: GuidanceMeta;
 };
 export declare function buildTelemetryMeta(opts: {
     candidateText: string;
@@ -29,6 +54,10 @@ export declare function buildTelemetryMeta(opts: {
     taskId?: string;
     agentId?: string;
     queryHash?: string;
+    candidateTokens?: number;
+    returnedTokens?: number;
+    candidateFiles?: number;
+    returnedFiles?: number;
     skipRecording?: boolean;
 }): TelemetryMeta;
 /** Resolve a short commit/ref fingerprint for cache keys. */

package/dist/utils/context-telemetry.js

@@ -6,14 +6,16 @@ import path from 'path';
 import { estimateTokenCount } from '@rigour-labs/core';
 export function buildTelemetryMeta(opts) {
     return {
-        candidateTokens: estimateTokenCount(opts.candidateText),
-        returnedTokens: estimateTokenCount(opts.returnedText),
+        candidateTokens: opts.candidateTokens ?? estimateTokenCount(opts.candidateText),
+        returnedTokens: opts.returnedTokens ?? estimateTokenCount(opts.returnedText),
         cacheStatus: opts.cacheStatus,
         deduplicatedTokens: opts.deduplicatedTokens ?? 0,
         isEstimated: true,
         taskId: opts.taskId,
         agentId: opts.agentId,
         queryHash: opts.queryHash,
+        candidateFiles: opts.candidateFiles,
+        returnedFiles: opts.returnedFiles,
         skipRecording: opts.skipRecording,
     };
 }

package/dist/utils/impact-receipt.d.ts

@@ -0,0 +1,13 @@
+import type { GuidanceMeta, TelemetryMeta } from './context-telemetry.js';
+export declare function buildStudioImpact(guidance?: GuidanceMeta, telemetry?: TelemetryMeta): {
+    guidance: GuidanceMeta | undefined;
+    telemetry: {
+        candidateTokens: number;
+        returnedTokens: number;
+        candidateFiles: number | undefined;
+        returnedFiles: number | undefined;
+        cacheStatus: import("./context-telemetry.js").CacheStatus;
+        classification: "observed" | "measured estimate";
+    } | undefined;
+};
+export declare function buildMcpResultMeta(existingMeta: unknown, requestId: string, resourceUri: string, guidance?: GuidanceMeta, telemetry?: TelemetryMeta): Record<string, unknown>;

package/dist/utils/impact-receipt.js

@@ -0,0 +1,43 @@
+function classification(telemetry) {
+    return telemetry?.isEstimated ? 'measured estimate' : 'observed';
+}
+export function buildStudioImpact(guidance, telemetry) {
+    return {
+        guidance,
+        telemetry: telemetry ? {
+            candidateTokens: telemetry.candidateTokens,
+            returnedTokens: telemetry.returnedTokens,
+            candidateFiles: telemetry.candidateFiles,
+            returnedFiles: telemetry.returnedFiles,
+            cacheStatus: telemetry.cacheStatus,
+            classification: classification(telemetry),
+        } : undefined,
+    };
+}
+export function buildMcpResultMeta(existingMeta, requestId, resourceUri, guidance, telemetry) {
+    const base = existingMeta && typeof existingMeta === 'object' && !Array.isArray(existingMeta)
+        ? existingMeta
+        : {};
+    if (!guidance)
+        return { ...base, ui: { resourceUri } };
+    return {
+        ...base,
+        ui: { resourceUri },
+        rigourImpact: {
+            requestId,
+            classification: classification(telemetry),
+            guidance,
+            context: telemetry ? {
+                candidateTokens: telemetry.candidateTokens,
+                returnedTokens: telemetry.returnedTokens,
+                avoidedTokens: Math.max(0, telemetry.candidateTokens - telemetry.returnedTokens),
+                candidateFiles: telemetry.candidateFiles,
+                returnedFiles: telemetry.returnedFiles,
+                excludedFiles: typeof telemetry.candidateFiles === 'number' && typeof telemetry.returnedFiles === 'number'
+                    ? Math.max(0, telemetry.candidateFiles - telemetry.returnedFiles)
+                    : undefined,
+                cacheStatus: telemetry.cacheStatus,
+            } : undefined,
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/mcp",
-  "version": "5.5.4",
+  "version": "6.1.0-beta.1",
   "description": "MCP server + live dashboard for AI code governance — OWASP LLM Top 10 (10/10), real-time MCP App UI, 25+ security patterns, Bayesian learning Brain, hallucinated import detection, multi-agent governance. Works with Claude, Cursor, VS Code, ChatGPT, Goose, Windsurf. Industry presets for HIPAA, SOC2, FedRAMP.",
   "license": "MIT",
   "homepage": "https://rigour.run",
@@ -62,7 +62,7 @@
     "execa": "^8.0.1",
     "fs-extra": "^11.4.0",
     "yaml": "^2.8.2",
-    "@rigour-labs/core": "5.5.4"
+    "@rigour-labs/core": "6.1.0-beta.1"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",