@jagilber-org/index-server 1.19.1

package/dist/services/handlers/instructions.shared.d.ts

@@ -0,0 +1,31 @@
+import { InstructionEntry } from '../../models/instruction';
+export declare function isMutationEnabled(): boolean;
+export declare function isCI(): boolean;
+export declare function limitResponseSize<T extends Record<string, unknown>>(response: T): T;
+export interface ImportEntry {
+    id: string;
+    title: string;
+    body: string;
+    rationale?: string;
+    priority: number;
+    audience: InstructionEntry['audience'];
+    requirement: InstructionEntry['requirement'];
+    categories?: unknown[];
+    deprecatedBy?: string;
+    riskScore?: number;
+    version?: string;
+    owner?: string;
+    status?: InstructionEntry['status'];
+    priorityTier?: InstructionEntry['priorityTier'];
+    classification?: InstructionEntry['classification'];
+    lastReviewedAt?: string;
+    nextReviewDue?: string;
+    changeLog?: InstructionEntry['changeLog'];
+    semanticSummary?: string;
+    contentType?: InstructionEntry['contentType'];
+}
+export declare function guard<TParams, TResult>(name: string, fn: (p: TParams) => TResult): (p: TParams) => TResult;
+export declare function traceVisibility(): boolean;
+export declare function traceInstructionVisibility(id: string, phase: string, extra?: Record<string, unknown>): void;
+export declare function traceEnvSnapshot(phase: string, extra?: Record<string, unknown>): void;
+export {};

package/dist/services/handlers/instructions.shared.js

@@ -0,0 +1,124 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMutationEnabled = isMutationEnabled;
+exports.isCI = isCI;
+exports.limitResponseSize = limitResponseSize;
+exports.guard = guard;
+exports.traceVisibility = traceVisibility;
+exports.traceInstructionVisibility = traceInstructionVisibility;
+exports.traceEnvSnapshot = traceEnvSnapshot;
+// Shared utilities used across instruction handler submodules.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const indexContext_1 = require("../indexContext");
+const runtimeConfig_1 = require("../../config/runtimeConfig");
+const tracing_1 = require("../tracing");
+function isMutationEnabled() {
+    return (0, runtimeConfig_1.getRuntimeConfig)().mutation.enabled;
+}
+function isCI() {
+    const ctx = (0, runtimeConfig_1.getRuntimeConfig)().instructions.ciContext;
+    return ctx.inCI || ctx.githubActions || ctx.tfBuild;
+}
+function limitResponseSize(response) {
+    if (!isCI())
+        return response;
+    const responseStr = JSON.stringify(response);
+    if (responseStr.length <= 60000)
+        return response;
+    if ('items' in response && Array.isArray(response.items) && response.items.length > 3) {
+        return {
+            ...response,
+            items: response.items.slice(0, 3),
+            ciLimited: true,
+            originalCount: response.items.length,
+            message: 'Response limited in CI environment to prevent truncation'
+        };
+    }
+    return response;
+}
+function guard(name, fn) {
+    return (p) => {
+        const viaDispatcher = !!(p && typeof p === 'object' && p._viaDispatcher);
+        if (!isMutationEnabled() && !viaDispatcher) {
+            throw { code: -32601, message: `Mutation disabled. Use index_dispatch with action parameter instead of direct ${name} calls. Set INDEX_SERVER_MUTATION=1 to enable direct calls.`, data: { method: name, alternative: 'index_dispatch', reason: 'mutation_disabled' } };
+        }
+        return fn(p);
+    };
+}
+function traceVisibility() { return (0, tracing_1.traceEnabled)(1); }
+function traceInstructionVisibility(id, phase, extra) {
+    if (!traceVisibility())
+        return;
+    try {
+        const dir = (0, indexContext_1.getInstructionsDir)();
+        const file = path_1.default.join(dir, `${id}.json`);
+        const st = (0, indexContext_1.ensureLoaded)();
+        const indexItem = st.byId.get(id);
+        let fileExists = false;
+        let fileSize;
+        let mtime;
+        let diskHash;
+        if (fs_1.default.existsSync(file)) {
+            fileExists = true;
+            const stat = fs_1.default.statSync(file);
+            fileSize = stat.size;
+            mtime = stat.mtime.toISOString();
+            try {
+                const rawTxt = fs_1.default.readFileSync(file, 'utf8');
+                try {
+                    const rawJson = JSON.parse(rawTxt);
+                    if (typeof rawJson.sourceHash === 'string')
+                        diskHash = rawJson.sourceHash;
+                }
+                catch { /* ignore parse */ }
+            }
+            catch { /* ignore read */ }
+        }
+        (0, tracing_1.emitTrace)('[trace:visibility]', {
+            phase,
+            id,
+            dir,
+            now: new Date().toISOString(),
+            fileExists,
+            fileSize,
+            mtime,
+            diskHash,
+            indexHas: !!indexItem,
+            indexSourceHash: indexItem?.sourceHash,
+            indexUpdatedAt: indexItem?.updatedAt,
+            serverHash: st.hash,
+            listCount: st.list.length,
+            sampleIds: st.list.slice(0, 3).map(e => e.id),
+            ...extra
+        });
+    }
+    catch { /* swallow tracing issues */ }
+}
+function traceEnvSnapshot(phase, extra) {
+    if (!traceVisibility())
+        return;
+    try {
+        const cfg = (0, runtimeConfig_1.getRuntimeConfig)();
+        const instructionsCfg = cfg.instructions;
+        const indexCfg = cfg.index;
+        (0, tracing_1.emitTrace)('[trace:env]', {
+            phase,
+            pid: process.pid,
+            flags: {
+                mutationEnabled: cfg.mutation.enabled,
+                strictCreate: instructionsCfg.strictCreate,
+                canonicalDisable: instructionsCfg.canonicalDisable,
+                readRetries: indexCfg.readRetries.attempts,
+                readBackoffMs: indexCfg.readRetries.backoffMs,
+                requireCategory: instructionsCfg.requireCategory,
+                instructionsDir: indexCfg.baseDir
+            },
+            ...extra
+        });
+    }
+    catch { /* ignore env tracing errors */ }
+}

package/dist/services/handlers.activation.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/handlers.activation.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * VS Code Activation Guide Handler
+ *
+ * Provides a stable read-only tool 'meta_activation_guide' that returns comprehensive
+ * guidance for activating Index Server tools in VSCode. Addresses the common pain
+ * point where tools show as "disabled by the user" despite correct settings.json configuration.
+ *
+ * Key insight: settings.json configuration is necessary but NOT sufficient - activation
+ * functions must be called to actually enable tools in VSCode.
+ *
+ * Created: 2026-02-01 (in response to repeated multi-session activation pain)
+ */
+const registry_1 = require("../server/registry");
+const ACTIVATION_GUIDE_VERSION = '1.0.0';
+(0, registry_1.registerHandler)('meta_activation_guide', () => {
+    return {
+        version: ACTIVATION_GUIDE_VERSION,
+        generatedAt: new Date().toISOString(),
+        problem: 'Index Server tools show as "disabled by the user" in VSCode even when properly configured in settings.json (chat.mcp.tools)',
+        rootCause: 'Settings.json configuration provides permission framework but does NOT trigger actual tool enablement. Activation functions must be called explicitly.',
+        solution: 'Call VSCode activation functions to enable tool categories. These functions are VSCode client-side features that must be invoked before using MCP tools.',
+        categories: {
+            instructionManagement: {
+                function: 'activate_instruction_management_and_operations_tools()',
+                description: 'Core instruction index operations: add, search, dispatch, remove, repair, import, normalize, reload',
+                tools: [
+                    'index_add',
+                    'index_dispatch',
+                    'index_search',
+                    'index_remove',
+                    'index_repair',
+                    'index_import',
+                    'index_health',
+                    'index_normalize',
+                    'index_reload',
+                    'usage_track',
+                    'usage_hotset',
+                    'manifest_refresh'
+                ],
+                toolCount: 12
+            },
+            graphAndSchema: {
+                function: 'activate_instruction_graph_and_schema_tools()',
+                description: 'Instruction graph export and JSON schema retrieval',
+                tools: ['graph_export', 'index_schema'],
+                toolCount: 2
+            },
+            governance: {
+                function: 'activate_governance_management_tools()',
+                description: 'Governance operations: enrich placeholder fields, compute/update governance hash',
+                tools: [
+                    'index_enrich',
+                    'index_governanceHash',
+                    'index_governanceUpdate'
+                ],
+                toolCount: 3
+            },
+            manifest: {
+                function: 'activate_manifest_management_tools()',
+                description: 'index manifest repair and status checks',
+                tools: ['manifest_repair', 'manifest_status'],
+                toolCount: 2
+            },
+            bootstrap: {
+                function: 'activate_bootstrap_management_tools()',
+                description: 'Bootstrap confirmation and finalization for guarded mutations',
+                tools: [
+                    'bootstrap_request',
+                    'bootstrap_confirmFinalize',
+                    'bootstrap_status'
+                ],
+                toolCount: 3
+            },
+            diagnostics: {
+                function: 'activate_diagnostic_stress_testing_tools()',
+                description: 'CPU/memory/microtask stress testing for performance analysis',
+                tools: [
+                    'diagnostics_block',
+                    'diagnostics_memoryPressure',
+                    'diagnostics_microtaskFlood'
+                ],
+                toolCount: 3
+            },
+            health: {
+                function: 'activate_feedback_and_health_monitoring_tools()',
+                description: 'Feedback submission and system health monitoring',
+                tools: [
+                    'feedback_submit',
+                    'feedback_list',
+                    'feedback_health',
+                    'feedback_stats',
+                    'health_check'
+                ],
+                toolCount: 5
+            }
+        },
+        quickStart: {
+            step1: 'Identify which tool you need (e.g., index_search)',
+            step2: 'Find matching category in activation categories above (e.g., instructionManagement)',
+            step3: 'Call the activation function with NO parameters: activate_instruction_management_and_operations_tools()',
+            step4: 'Retry your tool call - it should now work'
+        },
+        example: {
+            problem: 'Error: Tool "mcp_mcp-index-ser_index_search" is disabled by the user',
+            solution: 'Call: activate_instruction_management_and_operations_tools()',
+            verification: 'Retry index_search - should now execute successfully'
+        },
+        commonMistake: 'Assuming settings.json configuration (chat.mcp.tools) alone enables tools. Configuration provides permission framework but activation functions actually enable the tools.',
+        troubleshooting: [
+            {
+                symptom: 'All tools show as disabled despite settings.json configuration',
+                diagnosis: 'Activation functions not called',
+                fix: 'Call all activation functions listed in categories section above'
+            },
+            {
+                symptom: 'Some tool categories work, others disabled',
+                diagnosis: 'Only some activation functions called',
+                fix: 'Identify missing categories and call their activation functions'
+            },
+            {
+                symptom: 'Tools were working, now disabled after VSCode restart',
+                diagnosis: 'Activation state not persisted across sessions',
+                fix: 'Re-call activation functions after VSCode restart'
+            },
+            {
+                symptom: 'Cannot find activation function for a tool',
+                diagnosis: 'Tool may not require activation OR wrong MCP server',
+                fix: 'Verify tool belongs to index via meta_tools, check tool name mapping in categories above'
+            }
+        ],
+        relatedResources: {
+            instruction: 'mcp-tool-activation-critical-p0 (P0 instruction in Index Server index)',
+            documentation: 'See INDEX_SERVER_TOOL_ACTIVATION_IMPROVEMENT_PLAN.md in repository for detailed analysis'
+        }
+    };
+});
+(0, registry_1.registerHandler)('meta_check_activation', (params) => {
+    const toolName = params?.toolName;
+    if (!toolName) {
+        return {
+            found: false,
+            message: 'Parameter "toolName" is required (e.g., {"toolName": "index_search"})'
+        };
+    }
+    // Map tool names to activation categories
+    const toolMapping = {
+        'index_add': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
+        'index_dispatch': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
+        'index_search': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
+        'index_remove': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
+        'index_repair': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
+        'index_import': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
+        'index_health': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
+        'index_normalize': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
+        'index_reload': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
+        'usage_track': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
+        'usage_hotset': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
+        'manifest_refresh': { category: 'instructionManagement', function: 'activate_instruction_management_and_operations_tools' },
+        'graph_export': { category: 'graphAndSchema', function: 'activate_instruction_graph_and_schema_tools' },
+        'index_schema': { category: 'graphAndSchema', function: 'activate_instruction_graph_and_schema_tools' },
+        'index_enrich': { category: 'governance', function: 'activate_governance_management_tools' },
+        'index_governanceHash': { category: 'governance', function: 'activate_governance_management_tools' },
+        'index_governanceUpdate': { category: 'governance', function: 'activate_governance_management_tools' },
+        'manifest_repair': { category: 'manifest', function: 'activate_manifest_management_tools' },
+        'manifest_status': { category: 'manifest', function: 'activate_manifest_management_tools' },
+        'bootstrap_request': { category: 'bootstrap', function: 'activate_bootstrap_management_tools' },
+        'bootstrap_confirmFinalize': { category: 'bootstrap', function: 'activate_bootstrap_management_tools' },
+        'bootstrap_status': { category: 'bootstrap', function: 'activate_bootstrap_management_tools' },
+        'diagnostics_block': { category: 'diagnostics', function: 'activate_diagnostic_stress_testing_tools' },
+        'diagnostics_memoryPressure': { category: 'diagnostics', function: 'activate_diagnostic_stress_testing_tools' },
+        'diagnostics_microtaskFlood': { category: 'diagnostics', function: 'activate_diagnostic_stress_testing_tools' },
+        'feedback_submit': { category: 'health', function: 'activate_feedback_and_health_monitoring_tools' },
+        'feedback_list': { category: 'health', function: 'activate_feedback_and_health_monitoring_tools' },
+        'feedback_health': { category: 'health', function: 'activate_feedback_and_health_monitoring_tools' },
+        'feedback_stats': { category: 'health', function: 'activate_feedback_and_health_monitoring_tools' },
+        'health_check': { category: 'health', function: 'activate_feedback_and_health_monitoring_tools' }
+    };
+    const mapping = toolMapping[toolName];
+    if (!mapping) {
+        return {
+            found: true,
+            tool: toolName,
+            activationRequired: false,
+            message: `Tool '${toolName}' not found in activation mapping. May not require activation, or tool name is incorrect.`
+        };
+    }
+    return {
+        found: true,
+        tool: toolName,
+        activationRequired: true,
+        activationFunction: mapping.function,
+        activationCategory: mapping.category,
+        instructions: `To use '${toolName}' in VSCode:
+1. Call: ${mapping.function}()
+2. Retry tool call: ${toolName}
+3. Tool should now execute successfully
+
+Common issue: Settings.json configuration alone does NOT enable tools.`,
+        settingsJsonNote: 'Ensure tool is enabled in settings.json (chat.mcp.tools.index["' + toolName + '"]: true) but this configuration alone is insufficient for activation.'
+    };
+});

package/dist/services/handlers.bootstrap.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/handlers.bootstrap.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const registry_1 = require("../server/registry");
+const bootstrapGating_1 = require("./bootstrapGating");
+(0, registry_1.registerHandler)('bootstrap_request', (p) => {
+    const reason = (0, bootstrapGating_1.mutationGatedReason)();
+    return { status: (0, bootstrapGating_1.getBootstrapStatus)(), gatedReason: reason, ...(0, bootstrapGating_1.requestBootstrapToken)(p?.rationale) };
+});
+(0, registry_1.registerHandler)('bootstrap_confirmFinalize', (p) => {
+    if (!p || typeof p.token !== 'string' || !p.token.trim())
+        return { error: 'missing_token' };
+    const result = (0, bootstrapGating_1.finalizeBootstrapToken)(p.token.trim());
+    return { result, status: (0, bootstrapGating_1.getBootstrapStatus)() };
+});
+(0, registry_1.registerHandler)('bootstrap_status', () => {
+    return { status: (0, bootstrapGating_1.getBootstrapStatus)(), gatedReason: (0, bootstrapGating_1.mutationGatedReason)() };
+});
+// Unified bootstrap handler (002 Phase 2c)
+(0, registry_1.registerHandler)('bootstrap', (params) => {
+    const { action, ...rest } = params || {};
+    if (!action)
+        throw new Error('Missing required parameter: action');
+    if (action === 'status') {
+        return (0, bootstrapGating_1.getBootstrapStatus)();
+    }
+    if (action === 'request') {
+        const reason = (0, bootstrapGating_1.mutationGatedReason)();
+        return { status: (0, bootstrapGating_1.getBootstrapStatus)(), gatedReason: reason, ...(0, bootstrapGating_1.requestBootstrapToken)(rest.rationale) };
+    }
+    if (action === 'confirm') {
+        const token = rest.token;
+        if (!token || typeof token !== 'string' || !token.trim())
+            return { error: 'missing_token' };
+        const result = (0, bootstrapGating_1.finalizeBootstrapToken)(token.trim());
+        return { result, status: (0, bootstrapGating_1.getBootstrapStatus)() };
+    }
+    throw new Error(`Unknown bootstrap action: ${action}. Valid: request, confirm, status`);
+});

package/dist/services/handlers.dashboardConfig.d.ts

@@ -0,0 +1,34 @@
+/**
+ * dashboard_config
+ * Returns a deterministic snapshot of all recognized environment / feature flags regardless of current value.
+ * This consolidates scattered documentation, enabling the dashboard (and tests) to surface:
+ *  - Current value (raw)
+ *  - Parsed boolean (when applicable)
+ *  - Default semantics
+ *  - Category (core | dashboard | instructions | manifest | tracing | diagnostics | stress | usage | validation | auth | metrics | experimental)
+ *  - Description
+ *  - Stability (stable | diagnostic | experimental | deprecated | reserved)
+ *  - Since (version first introduced when known – best effort)
+ *
+ * The list is curated (not discovered dynamically) to ensure ordering stability and to include flags
+ * that might not appear in code paths when disabled. Additions should append (not reorder) to maintain
+ * predictable client diffing.
+ */
+export interface FlagMeta {
+    name: string;
+    category: string;
+    description: string;
+    stability: 'stable' | 'diagnostic' | 'experimental' | 'deprecated' | 'reserved';
+    since?: string;
+    default?: string;
+    type?: 'boolean' | 'string' | 'number';
+}
+export interface FlagRuntime extends FlagMeta {
+    value?: string;
+    enabled?: boolean;
+    parsed?: unknown;
+    docAnchor?: string;
+}
+export declare const FLAG_REGISTRY: FlagMeta[];
+export declare function getFlagRegistrySnapshot(): FlagRuntime[];
+export {};

package/dist/services/handlers.dashboardConfig.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLAG_REGISTRY = void 0;
+exports.getFlagRegistrySnapshot = getFlagRegistrySnapshot;
+const registry_1 = require("../server/registry");
+const envUtils_1 = require("../utils/envUtils");
+// Curated registry. Order is intentional for grouping high-value operational flags first.
+exports.FLAG_REGISTRY = [
+    // Core operation & dashboard
+    { name: 'INDEX_SERVER_MUTATION', category: 'core', description: 'Enable mutation tools (add/import/remove/enrich/governance updates).', stability: 'stable', default: 'off', type: 'boolean', since: '1.0.0' },
+    { name: 'INDEX_SERVER_VERBOSE_LOGGING', category: 'core', description: 'Verbose logging (handshake, dispatch timings).', stability: 'stable', default: 'off', type: 'boolean', since: '1.0.0' },
+    { name: 'INDEX_SERVER_LOG_DIAG', category: 'diagnostics', description: 'Diagnostic logging (lower-level/internal).', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.0.0' },
+    { name: 'INDEX_SERVER_DASHBOARD', category: 'dashboard', description: 'Enable admin dashboard HTTP server.', stability: 'stable', default: 'off', type: 'boolean', since: '1.0.0' },
+    { name: 'INDEX_SERVER_DASHBOARD_PORT', category: 'dashboard', description: 'Dashboard port.', stability: 'stable', default: '8787', type: 'number', since: '1.0.0' },
+    { name: 'INDEX_SERVER_DASHBOARD_HOST', category: 'dashboard', description: 'Dashboard bind host.', stability: 'stable', default: '127.0.0.1', type: 'string', since: '1.0.0' },
+    { name: 'INDEX_SERVER_DASHBOARD_TRIES', category: 'dashboard', description: 'Dashboard port retry attempts.', stability: 'stable', default: '10', type: 'number', since: '1.0.0' },
+    // Manifest & index
+    { name: 'INDEX_SERVER_MANIFEST_WRITE', category: 'manifest', description: 'Allow writing index manifest (set 0 to disable).', stability: 'stable', default: 'on', type: 'boolean', since: '1.1.0' },
+    { name: 'INDEX_SERVER_MANIFEST_FASTLOAD', category: 'manifest', description: 'Preview fastload path (currently reserved).', stability: 'reserved', default: 'off', type: 'boolean', since: '1.1.0' },
+    { name: 'INDEX_SERVER_ENABLE_INDEX_SERVER_POLLER', category: 'manifest', description: 'Enable background version marker poller (cross-process propagation).', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    { name: 'INDEX_SERVER_POLL_MS', category: 'manifest', description: 'Index poll interval ms when poller enabled.', stability: 'diagnostic', default: '10000', type: 'number', since: '1.1.1' },
+    { name: 'INDEX_SERVER_POLL_PROACTIVE', category: 'manifest', description: 'Proactive reload on poll interval even if version unchanged.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    // Instructions strictness / visibility / creation controls
+    { name: 'INDEX_SERVER_STRICT_CREATE', category: 'index', description: 'After add, perform strict visibility verification chain.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    { name: 'INDEX_SERVER_STRICT_REMOVE', category: 'index', description: 'After remove, enforce strict verification of absence.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    { name: 'INDEX_SERVER_TEST_STRICT_VISIBILITY', category: 'instructions', description: 'Test-only strict fallback path for immediate get/query discoverability.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    { name: 'INDEX_SERVER_REQUIRE_CATEGORY', category: 'instructions', description: 'Reject instructions missing category unless lax override set.', stability: 'stable', default: 'off', type: 'boolean', since: '1.0.0' },
+    { name: 'INDEX_SERVER_CANONICAL_DISABLE', category: 'instructions', description: 'Disable canonical sourceHash persistence (forces runtime recompute).', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    { name: 'INDEX_SERVER_READ_RETRIES', category: 'instructions', description: 'Retries for post-add disk visibility checks.', stability: 'diagnostic', default: '5', type: 'number', since: '1.1.1' },
+    { name: 'INDEX_SERVER_READ_BACKOFF_MS', category: 'instructions', description: 'Backoff ms between read retries.', stability: 'diagnostic', default: '10', type: 'number', since: '1.1.1' },
+    // Tracing & logging advanced
+    { name: 'INDEX_SERVER_TRACE_LEVEL', category: 'tracing', description: 'Explicit trace level (off|core|perf|files|verbose).', stability: 'stable', default: 'off', type: 'string', since: '1.1.2' },
+    { name: 'INDEX_SERVER_TRACE_ALL', category: 'tracing', description: 'Force maximum trace verbosity.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.2' },
+    { name: 'INDEX_SERVER_TRACE_PERSIST', category: 'tracing', description: 'Enable persistent JSONL trace output (auto file).', stability: 'stable', default: 'off', type: 'boolean', since: '1.1.2' },
+    { name: 'INDEX_SERVER_TRACE_FILE', category: 'tracing', description: 'Explicit trace output file path.', stability: 'stable', default: '(unset)', type: 'string', since: '1.1.2' },
+    { name: 'INDEX_SERVER_TRACE_DIR', category: 'tracing', description: 'Directory for auto trace files.', stability: 'stable', default: './logs/trace', type: 'string', since: '1.1.2' },
+    { name: 'INDEX_SERVER_TRACE_MAX_FILE_SIZE', category: 'tracing', description: 'Rotate trace file after exceeding N bytes (0=off).', stability: 'stable', default: '0', type: 'number', since: '1.1.2' },
+    { name: 'INDEX_SERVER_TRACE_CATEGORIES', category: 'tracing', description: 'Comma/space list of allowed trace categories (filter).', stability: 'stable', default: '(all)', type: 'string', since: '1.1.2' },
+    { name: 'INDEX_SERVER_TRACE_SESSION', category: 'tracing', description: 'Explicit trace session id.', stability: 'stable', default: '(random)', type: 'string', since: '1.1.2' },
+    { name: 'INDEX_SERVER_TRACE_CALLSITE', category: 'tracing', description: 'Include emitting function callsite (verbose or explicit).', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.2' },
+    { name: 'INDEX_SERVER_TRACE_FSYNC', category: 'tracing', description: 'fsync after each trace write (heavy, diagnostics only).', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.2' },
+    { name: 'INDEX_SERVER_TRACE_BUFFER_SIZE', category: 'tracing', description: 'Enable in-memory ring buffer of last N trace frames.', stability: 'experimental', default: '0', type: 'number', since: '1.1.2' },
+    { name: 'INDEX_SERVER_TRACE_BUFFER_FILE', category: 'tracing', description: 'Explicit file path for buffer dump.', stability: 'experimental', default: './logs/trace/trace-buffer.json', type: 'string', since: '1.1.2' },
+    { name: 'INDEX_SERVER_TRACE_BUFFER_DUMP_ON_EXIT', category: 'tracing', description: 'Dump ring buffer automatically on process exit.', stability: 'experimental', default: 'off', type: 'boolean', since: '1.1.2' },
+    { name: 'INDEX_SERVER_VISIBILITY_DIAG', category: 'tracing', description: 'Force core trace level for visibility diagnostics.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    { name: 'INDEX_SERVER_FILE_TRACE', category: 'tracing', description: 'Promote index file events to trace level (files).', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    // Usage & metrics
+    { name: 'INDEX_SERVER_DISABLE_USAGE_RATE_LIMIT', category: 'usage', description: 'Disable internal usage sampling rate limit.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    { name: 'INDEX_SERVER_DISABLE_USAGE_CLAMP', category: 'usage', description: 'Disable initial usage count clamp logic.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    { name: 'INDEX_SERVER_USAGE_FLUSH_MS', category: 'usage', description: 'Override usage flush debounce interval.', stability: 'diagnostic', default: '75', type: 'number', since: '1.1.1' },
+    // Validation / schema
+    { name: 'INDEX_SERVER_VALIDATION_MODE', category: 'validation', description: 'Schema validation engine selection (ajv|zod|auto).', stability: 'stable', default: 'zod', type: 'string', since: '1.1.2' },
+    // Handshake / transport / performance diagnostics
+    { name: 'INDEX_SERVER_DISABLE_EARLY_STDIN_BUFFER', category: 'diagnostics', description: 'Disable early stdin buffering (compare fragmentation behavior).', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    { name: 'INDEX_SERVER_FATAL_EXIT_DELAY_MS', category: 'diagnostics', description: 'Delay before forced fatal exit (ms).', stability: 'diagnostic', default: '15', type: 'number', since: '1.1.1' },
+    { name: 'INDEX_SERVER_IDLE_KEEPALIVE_MS', category: 'diagnostics', description: 'Keepalive interval for idle transports.', stability: 'stable', default: '30000', type: 'number', since: '1.0.0' },
+    { name: 'INDEX_SERVER_ADD_TIMING', category: 'diagnostics', description: 'Embed per-tool timing phase marks in response envelope.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    { name: 'INDEX_SERVER_TRACE_DISPATCH_DIAG', category: 'diagnostics', description: 'Extra dispatcher timing/phase logs (use INDEX_SERVER_TRACE=dispatchDiag).', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    // Stress / adversarial
+    { name: 'INDEX_SERVER_STRESS_DIAG', category: 'stress', description: 'Enable stress suite & escalated diagnostic loops.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.0' },
+    // Auth / security (placeholders for future expansion)
+    { name: 'INDEX_SERVER_REQUIRE_AUTH_ALL', category: 'auth', description: 'Require auth for all tool calls (future integration).', stability: 'experimental', default: 'off', type: 'boolean', since: '1.1.2' },
+    { name: 'INDEX_SERVER_AUTH_KEY', category: 'auth', description: 'Static auth key / token (development only).', stability: 'experimental', default: '(unset)', type: 'string', since: '1.1.2' },
+    // Metrics collection (file-based)
+    { name: 'INDEX_SERVER_METRICS_FILE_STORAGE', category: 'metrics', description: 'Persist metrics snapshots to files for dashboard aggregation.', stability: 'experimental', default: 'off', type: 'boolean', since: '1.1.2' },
+    { name: 'INDEX_SERVER_METRICS_DIR', category: 'metrics', description: 'Directory for metrics file storage.', stability: 'experimental', default: './metrics', type: 'string', since: '1.1.2' },
+    { name: 'INDEX_SERVER_METRICS_MAX_FILES', category: 'metrics', description: 'Max metrics files to retain (rotation).', stability: 'experimental', default: '720', type: 'number', since: '1.1.2' },
+    // Debug / developer ergonomics
+    { name: 'INDEX_SERVER_DEBUG', category: 'diagnostics', description: 'Enable developer diagnostics bundle (memory, internals).', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.0' },
+    { name: 'INDEX_SERVER_MEMORY_MONITOR', category: 'diagnostics', description: 'Enable periodic memory usage sampling/logging.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.0' },
+    { name: 'INDEX_SERVER_LOG_MUTATION', category: 'diagnostics', description: 'Emit mutation-specific verbose logs.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.0' },
+    // Legacy / removed (for awareness; not parsed at runtime)
+    { name: 'INDEX_SERVER_SHORTCIRCUIT', category: 'deprecated', description: 'Removed legacy short-circuit handshake path.', stability: 'deprecated', default: '(removed)', since: '<1.1.0' },
+    // Multi-instance / leader-follower
+    { name: 'INDEX_SERVER_MODE', category: 'multi-instance', description: 'Instance mode: standalone (default), leader, follower, auto.', stability: 'experimental', default: 'standalone', type: 'string', since: '1.8.5' },
+    { name: 'INDEX_SERVER_LEADER_PORT', category: 'multi-instance', description: 'HTTP port for leader MCP transport (thin clients connect here).', stability: 'experimental', default: '9090', type: 'number', since: '1.8.5' },
+    { name: 'INDEX_SERVER_HEARTBEAT_MS', category: 'multi-instance', description: 'Leader heartbeat interval (ms).', stability: 'experimental', default: '5000', type: 'number', since: '1.8.5' },
+    { name: 'INDEX_SERVER_STALE_THRESHOLD_MS', category: 'multi-instance', description: 'Stale leader threshold (ms) before follower promotes.', stability: 'experimental', default: '15000', type: 'number', since: '1.8.5' },
+];
+function parseValue(meta) {
+    const raw = process.env[meta.name];
+    if (raw === undefined)
+        return {};
+    if (meta.type === 'boolean') {
+        const enabled = (0, envUtils_1.getBooleanEnv)(meta.name);
+        return { value: raw, enabled, parsed: enabled };
+    }
+    if (meta.type === 'number') {
+        const n = parseInt(raw, 10);
+        return { value: raw, parsed: Number.isFinite(n) ? n : undefined };
+    }
+    return { value: raw, parsed: raw };
+}
+function getFlagRegistrySnapshot() {
+    return exports.FLAG_REGISTRY
+        .slice()
+        .sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name))
+        .map(m => ({ ...m, ...parseValue(m), docAnchor: m.name.toLowerCase().replace(/_/g, '-') }));
+}
+(0, registry_1.registerHandler)('dashboard_config', () => {
+    const flags = getFlagRegistrySnapshot();
+    return {
+        generatedAt: new Date().toISOString(),
+        lastRefreshed: Date.now(),
+        total: flags.length,
+        flags,
+    };
+});

package/dist/services/handlers.diagnostics.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/handlers.diagnostics.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const registry_1 = require("../server/registry");
+/**
+ * diagnostics_block: Intentionally CPU blocks the event loop for a specified number of milliseconds.
+ * Purpose: Reproduce / probe health_check hang or starvation behavior under synchronous handler saturation.
+ * NOTE: This is test/instrumentation oriented and not part of stable tool surface.
+ */
+(0, registry_1.registerHandler)('diagnostics_block', (p) => {
+    const ms = typeof p.ms === 'number' ? Math.min(Math.max(p.ms, 0), 10_000) : 250; // cap at 10s
+    const start = Date.now();
+    // Busy-loop (intentional) to simulate CPU starvation in a single-threaded event loop
+    // eslint-disable-next-line no-empty
+    while (Date.now() - start < ms) { /* block */ }
+    return { blockedMs: ms, startedAt: new Date(start).toISOString(), endedAt: new Date().toISOString() };
+});
+/**
+ * diagnostics_microtaskFlood: Schedules a large number of microtasks (Promise.resolve chains)
+ * to create event loop turn pressure without pure synchronous blocking.
+ * Useful to probe starvation scenarios distinct from a tight busy loop.
+ */
+(0, registry_1.registerHandler)('diagnostics_microtaskFlood', async (p) => {
+    const count = typeof p.count === 'number' ? Math.min(Math.max(p.count, 0), 200_000) : 25_000;
+    let ops = 0;
+    // Chain microtasks in batches to avoid blowing the call stack while still flooding.
+    function batch(n) {
+        if (n <= 0)
+            return Promise.resolve();
+        return Promise.resolve().then(() => { ops++; }).then(() => batch(n - 1));
+    }
+    const start = Date.now();
+    await batch(count);
+    return { scheduled: count, executed: ops, ms: Date.now() - start };
+});
+/**
+ * diagnostics_memoryPressure: Allocates transient buffers to induce GC / memory pressure.
+ * Allocation is bounded & immediately released (locally scoped) before returning.
+ */
+(0, registry_1.registerHandler)('diagnostics_memoryPressure', (p) => {
+    const mb = typeof p.mb === 'number' ? Math.min(Math.max(p.mb, 1), 512) : 64; // cap to 512MB
+    const start = Date.now();
+    const blocks = [];
+    const PER = 4 * 1024 * 1024; // 4MB per block
+    const needed = Math.ceil((mb * 1024 * 1024) / PER);
+    for (let i = 0; i < needed; i++) {
+        const b = Buffer.allocUnsafe(PER);
+        // touch a few bytes to ensure physical commit
+        b[0] = 1;
+        b[PER - 1] = 1;
+        blocks.push(b);
+    }
+    const allocMs = Date.now() - start;
+    // Release references so GC can reclaim
+    return { requestedMB: mb, blocks: blocks.length, perBlockBytes: PER, allocMs };
+});
+// Augment global type locally (non-invasive)
+// eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+const gRef = global;
+(0, registry_1.registerHandler)('diagnostics_handshake', () => {
+    const buf = gRef.HANDSHAKE_EVENTS_REF;
+    if (Array.isArray(buf))
+        return { events: buf.slice(-50) };
+    return { events: [], warning: 'handshake instrumentation unavailable in this build' };
+});

package/dist/services/handlers.feedback.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Feedback/Emit System for Index Server
+ *
+ * Provides MCP protocol-compliant tools for clients to submit structured feedback,
+ * status reports, security issues, feature requests, and other communications
+ * to server administrators or monitoring systems.
+ *
+ * This system follows MCP best practices:
+ * - Tools are discoverable via tools/list
+ * - Input validation via JSON schemas
+ * - Structured responses for programmatic consumption
+ * - Proper error handling and logging
+ * - Audit trail for security and compliance
+ */
+export {};