iranti 0.2.51 → 0.3.2

package/dist/scripts/iranti-mcp.js

@@ -32,15 +32,47 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const z = __importStar(require("zod/v4"));
+const sdk_1 = require("../src/sdk");
 const commandErrors_1 = require("../src/lib/commandErrors");
 const createFirstPartyIranti_1 = require("../src/lib/createFirstPartyIranti");
 const runtimeEnv_1 = require("../src/lib/runtimeEnv");
 const autoRemember_1 = require("../src/lib/autoRemember");
+const staffEventRegistry_1 = require("../src/lib/staffEventRegistry");
+const client_1 = require("../src/library/client");
+const attendant_1 = require("../src/attendant");
+const assistantCheckpoint_1 = require("../src/lib/assistantCheckpoint");
+const hostMemoryFormatting_1 = require("../src/lib/hostMemoryFormatting");
 (0, runtimeEnv_1.loadRuntimeEnv)();
+let runtimeHostOverride = null;
+let shutdownPromise = null;
+let processIranti = null;
+const HOST_SETUP_CHECKS = {
+    claude_code: { file: 'CLAUDE.md', command: 'iranti claude-setup .' },
+    codex: { file: 'AGENTS.md', command: 'iranti codex-setup' },
+    codex_cli: { file: 'AGENTS.md', command: 'iranti codex-setup' },
+    codex_vscode: { file: 'AGENTS.md', command: 'iranti codex-setup' },
+};
+function checkHostSetup(host, cwd) {
+    if (!host)
+        return [];
+    const check = HOST_SETUP_CHECKS[host];
+    if (!check)
+        return [];
+    const filePath = node_path_1.default.join(cwd, check.file);
+    if (!node_fs_1.default.existsSync(filePath)) {
+        return [`⚠ ${check.file} not found in ${cwd}. Run \`${check.command}\` to complete host setup for this project. Until then, operating rules will not be enforced across sessions.`];
+    }
+    return [];
+}
 function printHelp() {
     console.log([
         'Iranti MCP Server',
@@ -59,7 +91,8 @@ function printHelp() {
         '  IRANTI_MCP_AGENT_DESCRIPTION  Default agent description',
         '  IRANTI_MCP_AGENT_MODEL        Default agent model label',
         '  IRANTI_MCP_DEFAULT_SOURCE     Default write source (default: ClaudeCode)',
-        '  IRANTI_AUTO_REMEMBER         Opt-in explicit prompt auto-save before attend()',
+        '  IRANTI_MCP_HOST               Host label for session ledger events (default: generic_mcp)',
+        '  IRANTI_AUTO_REMEMBER         Opt-in prompt-side auto-save before pre-response attend()',
         '',
         'This server is intended for Claude Code and other MCP clients over stdio.',
         'If you run `iranti mcp` directly in a terminal, it will stay running and wait for an MCP client.',
@@ -72,13 +105,39 @@ function requireConnectionString() {
     }
     return connectionString;
 }
-function defaultAgentId() {
-    return process.env.IRANTI_MCP_DEFAULT_AGENT?.trim()
-        || process.env.IRANTI_AGENT_ID?.trim()
+function currentHost(host) {
+    return host?.trim()
+        || runtimeHostOverride?.trim()
+        || process.env.IRANTI_MCP_HOST?.trim();
+}
+function defaultAgentId(host) {
+    const resolvedHost = currentHost(host);
+    if (resolvedHost === 'claude_code') {
+        return process.env.IRANTI_CLAUDE_AGENT_ID?.trim()
+            || process.env.IRANTI_AGENT_ID?.trim()
+            || 'claude_code';
+    }
+    const explicit = process.env.IRANTI_MCP_DEFAULT_AGENT?.trim();
+    if (explicit)
+        return explicit;
+    if (resolvedHost === 'codex' || resolvedHost === 'codex_cli' || resolvedHost === 'codex_vscode') {
+        return 'codex_code';
+    }
+    return process.env.IRANTI_AGENT_ID?.trim()
         || 'claude_code';
 }
-function defaultWriteSource() {
-    return process.env.IRANTI_MCP_DEFAULT_SOURCE?.trim() || 'ClaudeCode';
+function defaultWriteSource(host) {
+    const resolvedHost = currentHost(host);
+    if (resolvedHost === 'claude_code') {
+        return 'ClaudeCode';
+    }
+    const explicit = process.env.IRANTI_MCP_DEFAULT_SOURCE?.trim();
+    if (explicit)
+        return explicit;
+    if (resolvedHost === 'codex' || resolvedHost === 'codex_cli' || resolvedHost === 'codex_vscode') {
+        return 'Codex';
+    }
+    return 'MCP';
 }
 function safeJsonParse(raw) {
     try {
@@ -115,18 +174,57 @@ function parseIsoDate(raw) {
     }
     return parsed;
 }
-async function ensureDefaultAgent(iranti) {
-    const agentId = defaultAgentId();
+async function ensureDefaultAgent(iranti, host) {
+    const agentId = defaultAgentId(host);
+    const resolvedHost = currentHost(host);
+    const isCodexHost = resolvedHost === 'codex' || resolvedHost === 'codex_cli' || resolvedHost === 'codex_vscode';
     await iranti.registerAgent({
         agentId,
-        name: process.env.IRANTI_MCP_AGENT_NAME?.trim() || 'Claude Code',
-        description: process.env.IRANTI_MCP_AGENT_DESCRIPTION?.trim() || 'Claude Code MCP client',
+        name: process.env.IRANTI_MCP_AGENT_NAME?.trim() || (isCodexHost ? 'Codex' : 'Claude Code'),
+        description: process.env.IRANTI_MCP_AGENT_DESCRIPTION?.trim() || (isCodexHost ? 'Codex MCP client' : 'Claude Code MCP client'),
         capabilities: ['memory_read', 'memory_write', 'hybrid_search', 'working_memory'],
-        model: process.env.IRANTI_MCP_AGENT_MODEL?.trim() || process.env.ANTHROPIC_MODEL || 'claude-code',
+        model: process.env.IRANTI_MCP_AGENT_MODEL?.trim()
+            || process.env.ANTHROPIC_MODEL
+            || (isCodexHost ? 'codex' : 'claude-code'),
+    });
+}
+function syncRuntimeLedgerContext(iranti, host, agent) {
+    iranti.setSessionLedgerContext({
+        source: 'mcp',
+        host: currentHost(host) ?? null,
+        agentId: agent?.trim() || defaultAgentId(host),
     });
 }
-function withDefaultAgent(agent) {
-    return agent?.trim() || defaultAgentId();
+function withDefaultAgent(agent, host) {
+    return agent?.trim() || defaultAgentId(host);
+}
+function resolveToolAgent(agent, agentId, host) {
+    return withDefaultAgent(agentId ?? agent, host);
+}
+function resolveToolHost(host) {
+    const trimmed = host?.trim();
+    if (trimmed) {
+        runtimeHostOverride = trimmed;
+        return trimmed;
+    }
+    return currentHost();
+}
+function protocolViolationResult(error) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${error.protocolViolation.message}\n\n${JSON.stringify({
+                    blocked: true,
+                    protocolViolation: error.protocolViolation,
+                }, null, 2)}`,
+            },
+        ],
+        structuredContent: {
+            blocked: true,
+            protocolViolation: error.protocolViolation,
+        },
+    };
 }
 function normalizeRecentMessages(messages) {
     if (!Array.isArray(messages))
@@ -139,6 +237,95 @@ function normalizeRecentMessages(messages) {
 function isInteractiveTerminalLaunch() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
+function clearProcessAttendants() {
+    for (const agentId of (0, attendant_1.activeAttendants)()) {
+        (0, attendant_1.clearAttendant)(agentId);
+    }
+}
+async function checkpointActiveAttendants(iranti, reason) {
+    const agents = (0, attendant_1.activeAttendants)();
+    for (const agentId of agents) {
+        const brief = (0, attendant_1.getAttendant)(agentId).getBrief();
+        const existing = brief?.sessionCheckpoint;
+        if (!existing?.task)
+            continue;
+        const existingCheckpoint = existing.checkpoint ?? {};
+        await iranti.checkpoint({
+            agentId,
+            task: existing.task,
+            recentMessages: [],
+            checkpoint: {
+                currentStep: existingCheckpoint.currentStep ?? 'in progress',
+                nextStep: existingCheckpoint.nextStep,
+                openRisks: existingCheckpoint.openRisks,
+                recentOutputs: existingCheckpoint.recentOutputs,
+                actions: existingCheckpoint.actions,
+                fileChanges: existingCheckpoint.fileChanges,
+                entityTargets: existingCheckpoint.entityTargets,
+                notes: `Host exited gracefully (${reason}). Resume from next step if applicable.`,
+            },
+            sessionId: existing.sessionId,
+        }).catch(() => undefined);
+    }
+}
+function resolveAttendLatestMessage(input) {
+    const latestMessage = input.latestMessage?.trim();
+    if (latestMessage)
+        return latestMessage;
+    const message = input.message?.trim();
+    if (message)
+        return message;
+    throw new Error('iranti_attend requires latestMessage or message.');
+}
+async function shutdownProcess(code, reason) {
+    if (shutdownPromise) {
+        return shutdownPromise;
+    }
+    shutdownPromise = (async () => {
+        try {
+            if (processIranti) {
+                await checkpointActiveAttendants(processIranti, reason).catch(() => undefined);
+            }
+            clearProcessAttendants();
+            await (0, staffEventRegistry_1.flushStaffEventEmitter)().catch(() => undefined);
+            await (0, client_1.disconnectDb)().catch(() => undefined);
+        }
+        finally {
+            if (isInteractiveTerminalLaunch()) {
+                console.error(`[iranti-mcp] shutting down (${reason}).`);
+            }
+            process.exitCode = code;
+        }
+    })();
+    return shutdownPromise;
+}
+function installShutdownHooks(transport) {
+    let shutdownRequested = false;
+    const requestShutdown = (code, reason) => {
+        if (shutdownRequested)
+            return;
+        shutdownRequested = true;
+        void shutdownProcess(code, reason);
+    };
+    transport.onclose = () => {
+        requestShutdown(0, 'transport_closed');
+    };
+    // When stdin is already ending or closing, asking the SDK transport to close
+    // can re-touch the same handle. On Windows that has been reproducing a
+    // UV_HANDLE_CLOSING assertion during shutdown, so we exit directly here.
+    process.stdin.once('end', () => requestShutdown(0, 'stdin_end'));
+    process.stdin.once('close', () => requestShutdown(0, 'stdin_close'));
+    process.stdin.once('error', () => requestShutdown(1, 'stdin_error'));
+    process.stdout.once('error', (error) => {
+        requestShutdown(error?.code === 'EPIPE' ? 0 : 1, error?.code === 'EPIPE' ? 'stdout_epipe' : 'stdout_error');
+    });
+    process.once('SIGINT', () => {
+        requestShutdown(130, 'sigint');
+    });
+    process.once('SIGTERM', () => {
+        requestShutdown(143, 'sigterm');
+    });
+}
 async function main() {
     if (process.argv.includes('--help') || process.argv.includes('-h')) {
         printHelp();
@@ -147,11 +334,16 @@ async function main() {
     const iranti = (0, createFirstPartyIranti_1.createFirstPartyIranti)({
         connectionString: requireConnectionString(),
         llmProvider: process.env.LLM_PROVIDER,
+        sessionLedgerSource: 'mcp',
+        sessionLedgerHost: currentHost() || 'generic_mcp',
+        sessionLedgerAgentId: defaultAgentId(),
+        dbPoolMax: 3,
     });
+    processIranti = iranti;
     await ensureDefaultAgent(iranti);
     const server = new mcp_js_1.McpServer({
         name: 'iranti-mcp',
-        version: '0.2.51',
+        version: '0.3.2',
     });
     server.registerTool('iranti_handshake', {
         description: `Initialize or refresh an agent's working-memory brief for the current task.
@@ -166,13 +358,23 @@ Do not use this as a per-turn retrieval tool; use iranti_attend.`,
             task: z.string().min(1).describe('The current task or objective.'),
             recentMessages: z.array(z.string()).optional().describe('Recent conversation messages.'),
             agent: z.string().optional().describe('Override the default agent id.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id.'),
+            host: z.string().optional().describe('Host identifier (e.g. claude_code, codex). Used to verify host setup has been run for this project.'),
         },
-    }, async ({ task, recentMessages, agent }) => {
+    }, async ({ task, recentMessages, agent, agentId, host }) => {
+        const resolvedHost = resolveToolHost(host);
+        const resolvedAgent = resolveToolAgent(agent, agentId, resolvedHost);
+        syncRuntimeLedgerContext(iranti, resolvedHost, resolvedAgent);
+        await ensureDefaultAgent(iranti, resolvedHost);
         const result = await iranti.handshake({
-            agent: withDefaultAgent(agent),
+            agent: resolvedAgent,
             task,
             recentMessages: normalizeRecentMessages(recentMessages),
         });
+        const setupWarnings = checkHostSetup(resolvedHost, process.cwd());
+        if (setupWarnings.length > 0) {
+            return textResult({ ...result, setupWarnings });
+        }
         return textResult(result);
     });
     server.registerTool('iranti_attend', {
@@ -186,33 +388,140 @@ be added to context if relevant memory is missing. If no handshake has been
 performed yet for this agent in the current process, attend will auto-bootstrap
 the session first and report that in the result metadata.
 This is the minimum safe pre-reply call even when the host skipped handshake.
-Omitting currentContext falls back to latestMessage only; pass the
-full visible context when available.`,
+Omitting currentContext falls back to the latest message only; pass the
+full visible context when available. For host compatibility, message is
+accepted as an alias for latestMessage. When phase='post-response', pass the
+assistant response so Iranti can persist strict continuity facts and shared
+checkpoint breadcrumbs before closing the turn.`,
         inputSchema: {
-            latestMessage: z.string().min(1).describe('The latest user or assistant message.'),
+            latestMessage: z.string().min(1).optional().describe('The latest user or assistant message.'),
+            message: z.string().min(1).optional().describe('Alias for latestMessage, accepted for host compatibility.'),
             currentContext: z.string().optional().describe('Current visible context window.'),
             entityHints: z.array(z.string()).optional().describe('Optional entity hints in entityType/entityId format.'),
             maxFacts: z.number().int().min(1).max(20).optional().describe('Maximum facts to inject.'),
             forceInject: z.boolean().optional().describe('Force a memory injection decision.'),
+            phase: z.enum(['pre-response', 'post-response', 'mid-turn']).optional().describe("Call phase: 'pre-response' before replying, 'post-response' after replying. Enables precise compliance tracking."),
             agent: z.string().optional().describe('Override the default agent id.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id.'),
         },
-    }, async ({ latestMessage, currentContext, entityHints, maxFacts, forceInject, agent }) => {
-        const resolvedAgent = withDefaultAgent(agent);
-        if ((0, autoRemember_1.isAutoRememberEnabled)()) {
-            await (0, autoRemember_1.autoRememberPromptFacts)({
-                iranti,
-                prompt: latestMessage,
+    }, async ({ latestMessage, message, currentContext, entityHints, maxFacts, forceInject, phase, agent, agentId }) => {
+        const resolvedAgent = resolveToolAgent(agent, agentId);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
+        const resolvedLatestMessage = resolveAttendLatestMessage({ latestMessage, message });
+        try {
+            if (phase === 'post-response') {
+                await (0, autoRemember_1.rememberAssistantResponseFacts)({
+                    iranti,
+                    response: resolvedLatestMessage,
+                    agent: resolvedAgent,
+                    source: defaultWriteSource(),
+                    ledgerContext: {
+                        source: 'mcp',
+                        host: currentHost() || 'generic_mcp',
+                    },
+                });
+                const checkpoint = (0, assistantCheckpoint_1.extractAssistantCheckpointPayload)(resolvedLatestMessage);
+                const projectEntity = process.env.IRANTI_MEMORY_ENTITY?.trim();
+                if (checkpoint && projectEntity) {
+                    await iranti.checkpoint({
+                        agent: resolvedAgent,
+                        task: `Post-response checkpoint for ${resolvedAgent}`,
+                        recentMessages: [],
+                        checkpoint: {
+                            ...checkpoint,
+                            entityTargets: [projectEntity],
+                        },
+                    });
+                }
+            }
+            else if ((0, autoRemember_1.isAutoRememberEnabled)()) {
+                await (0, autoRemember_1.autoRememberPromptFacts)({
+                    iranti,
+                    prompt: resolvedLatestMessage,
+                    agent: resolvedAgent,
+                    source: defaultWriteSource(),
+                });
+            }
+            const result = await iranti.attend({
                 agent: resolvedAgent,
-                source: defaultWriteSource(),
+                latestMessage: resolvedLatestMessage,
+                currentContext: currentContext ?? resolvedLatestMessage,
+                entityHints,
+                maxFacts,
+                forceInject,
+                phase,
             });
+            const injectionBlock = result.shouldInject
+                ? (0, hostMemoryFormatting_1.formatStructuredFactBlock)(result.facts, {
+                    title: 'Iranti Retrieved Memory',
+                    includeValues: true,
+                })
+                : '';
+            return textResult({
+                ...result,
+                injectionBlock,
+            });
+        }
+        catch (error) {
+            if (error instanceof sdk_1.ProtocolViolationError) {
+                return protocolViolationResult(error);
+            }
+            throw error;
         }
-        const result = await iranti.attend({
+    });
+    server.registerTool('iranti_checkpoint', {
+        description: `Persist a shared progress checkpoint while you work.
+Use this at meaningful milestones so current step, next step, open risks,
+recent outputs, structured actions, and shared entity breadcrumbs survive across turns,
+sessions, and agents. This is the strongest shared-RAM tool for active work:
+prefer it over ad-hoc prose when you need another session or another agent
+to pick up where you left off. If entityTargets are supplied, Iranti also
+writes canonical shared breadcrumbs such as current_step, next_step,
+open_risks, recent_actions, and recent_file_changes to those entities for handoff.`,
+        inputSchema: {
+            task: z.string().min(1).describe('Current task or objective for the active checkpoint.'),
+            recentMessages: z.array(z.string()).optional().describe('Recent messages that help fingerprint the active task.'),
+            currentStep: z.string().optional().describe('What is being worked on right now.'),
+            nextStep: z.string().optional().describe('The next step another session or agent should take.'),
+            openRisks: z.array(z.string()).optional().describe('Open risks or blockers that still matter.'),
+            recentOutputs: z.array(z.string()).optional().describe('Important outputs or artifacts produced so far.'),
+            actions: z.array(z.object({
+                kind: z.string().min(1).describe('Action kind such as command, test, edit, search, validation, or decision.'),
+                summary: z.string().min(1).describe('Compact description of what action happened.'),
+                status: z.string().optional().describe('Optional outcome such as passed, failed, succeeded, or skipped.'),
+                target: z.string().optional().describe('Optional command, file, test, or subsystem the action touched.'),
+                detail: z.string().optional().describe('Optional compact supporting detail for later recovery.'),
+            })).optional().describe('Structured actions completed so far, such as commands, tests, searches, or validations.'),
+            fileChanges: z.array(z.object({
+                action: z.string().min(1).describe('Change action such as created, updated, moved, renamed, or deleted.'),
+                path: z.string().min(1).describe('Primary file path affected by the action.'),
+                toPath: z.string().optional().describe('Destination path for move/rename actions.'),
+                purpose: z.string().optional().describe('Why the file changed or what role it now serves.'),
+            })).optional().describe('Structured file actions produced so far.'),
+            entityTargets: z.array(z.string()).optional().describe('Shared entities that should receive checkpoint breadcrumbs, in entityType/entityId format.'),
+            notes: z.string().optional().describe('Compact extra checkpoint notes that aid handoff.'),
+            sessionId: z.string().optional().describe('Optional existing session id to refresh.'),
+            agent: z.string().optional().describe('Override the default agent id.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id.'),
+        },
+    }, async ({ task, recentMessages, currentStep, nextStep, openRisks, recentOutputs, actions, fileChanges, entityTargets, notes, sessionId, agent, agentId }) => {
+        const resolvedAgent = resolveToolAgent(agent, agentId);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
+        const result = await iranti.checkpoint({
             agent: resolvedAgent,
-            latestMessage,
-            currentContext: currentContext ?? latestMessage,
-            entityHints,
-            maxFacts,
-            forceInject,
+            task,
+            recentMessages: normalizeRecentMessages(recentMessages),
+            sessionId,
+            checkpoint: {
+                currentStep,
+                nextStep,
+                openRisks,
+                recentOutputs,
+                actions,
+                fileChanges,
+                entityTargets,
+                notes,
+            },
         });
         return textResult(result);
     });
@@ -223,18 +532,31 @@ full visible context when available.`,
             entityHints: z.array(z.string()).optional().describe('Optional entity hints in entityType/entityId format.'),
             maxFacts: z.number().int().min(1).max(20).optional().describe('Maximum facts to recover.'),
             agent: z.string().optional().describe('Override the default agent id.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id.'),
         },
-    }, async ({ currentContext, entityHints, maxFacts, agent }) => {
-        const result = await iranti.observe({
-            agent: withDefaultAgent(agent),
-            currentContext,
-            entityHints,
-            maxFacts,
-        });
-        return textResult(result);
+    }, async ({ currentContext, entityHints, maxFacts, agent, agentId }) => {
+        const resolvedAgent = resolveToolAgent(agent, agentId);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
+        try {
+            const result = await iranti.observe({
+                agent: resolvedAgent,
+                currentContext,
+                entityHints,
+                maxFacts,
+            });
+            return textResult(result);
+        }
+        catch (error) {
+            if (error instanceof sdk_1.ProtocolViolationError) {
+                return protocolViolationResult(error);
+            }
+            throw error;
+        }
     });
     server.registerTool('iranti_query', {
         description: `Retrieve the current fact for an exact entity+key lookup.
+REQUIRED: call iranti_attend before this discovery tool so Iranti can decide
+whether memory should be injected before exact lookup.
 Use this when you already know both the entity and the key.
 Returns the current value, summary, confidence, source, and
 temporal metadata when available. Prefer this over iranti_search
@@ -243,15 +565,62 @@ memory alone before checking Iranti.`,
         inputSchema: {
             entity: z.string().min(1).describe('Entity in entityType/entityId format.'),
             key: z.string().min(1).describe('Fact key to retrieve.'),
+            agent: z.string().optional().describe('Override the default agent id for protocol tracking.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id for protocol tracking.'),
         },
-    }, async ({ entity, key }) => {
-        const result = await iranti.query(entity, key);
-        return textResult(result);
+    }, async ({ entity, key, agent, agentId }) => {
+        const resolvedAgent = resolveToolAgent(agent, agentId);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
+        try {
+            const result = await iranti.query(entity, key);
+            return textResult(result);
+        }
+        catch (error) {
+            if (error instanceof sdk_1.ProtocolViolationError) {
+                return protocolViolationResult(error);
+            }
+            throw error;
+        }
+    });
+    server.registerTool('iranti_history', {
+        description: `Retrieve the full version history of a fact for an exact entity+key pair.
+Returns all archived past values plus the current value, ordered oldest-first.
+Each entry includes value, summary, confidence, source, validFrom, validUntil,
+isCurrent, archivedReason, and resolutionState.
+REQUIRED: call iranti_attend before this discovery tool so Iranti can decide
+whether memory should be injected first.
+Use this to understand how a fact evolved over time — decisions that changed,
+blockers that were resolved, values that were contested or superseded.`,
+        inputSchema: {
+            entity: z.string().min(1).describe('Entity in entityType/entityId format.'),
+            key: z.string().min(1).describe('Fact key to retrieve history for.'),
+            limit: z.number().int().min(1).optional().describe('Maximum number of entries to return (applied after sorting oldest-first).'),
+            includeExpired: z.boolean().optional().describe('Include entries that expired without being superseded.'),
+            includeContested: z.boolean().optional().describe('Include entries that were contested or escalated.'),
+            agent: z.string().optional().describe('Override the default agent id for protocol tracking.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id for protocol tracking.'),
+        },
+    }, async ({ entity, key, limit, includeExpired, includeContested, agent, agentId }) => {
+        const resolvedAgent = resolveToolAgent(agent, agentId);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
+        try {
+            const history = await iranti.history(entity, key, { includeExpired, includeContested });
+            const result = limit != null ? history.slice(0, limit) : history;
+            return textResult(result);
+        }
+        catch (error) {
+            if (error instanceof sdk_1.ProtocolViolationError) {
+                return protocolViolationResult(error);
+            }
+            throw error;
+        }
     });
     server.registerTool('iranti_search', {
         description: `Search shared memory with natural language when the exact entity
 or key is unknown. Uses hybrid lexical and vector search across
 stored facts. Use this for discovery and recall, not exact lookup.
+REQUIRED: call iranti_attend before this discovery tool so Iranti can decide
+whether memory should be injected before search.
 If the user asks what they previously told you and you do not know
 the exact key, use this before saying you do not know.`,
         inputSchema: {
@@ -262,18 +631,30 @@ the exact key, use this before saying you do not know.`,
             lexicalWeight: z.number().min(0).max(1).optional().describe('Lexical ranking weight.'),
             vectorWeight: z.number().min(0).max(1).optional().describe('Vector similarity weight.'),
             minScore: z.number().min(0).max(1).optional().describe('Minimum final score threshold.'),
+            agent: z.string().optional().describe('Override the default agent id for protocol tracking.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id for protocol tracking.'),
         },
-    }, async ({ query, entityType, entityId, limit, lexicalWeight, vectorWeight, minScore }) => {
-        const result = await iranti.search({
-            query,
-            entityType,
-            entityId,
-            limit,
-            lexicalWeight,
-            vectorWeight,
-            minScore,
-        });
-        return textResult(result);
+    }, async ({ query, entityType, entityId, limit, lexicalWeight, vectorWeight, minScore, agent, agentId }) => {
+        const resolvedAgent = resolveToolAgent(agent, agentId);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
+        try {
+            const result = await iranti.search({
+                query,
+                entityType,
+                entityId,
+                limit,
+                lexicalWeight,
+                vectorWeight,
+                minScore,
+            });
+            return textResult(result);
+        }
+        catch (error) {
+            if (error instanceof sdk_1.ProtocolViolationError) {
+                return protocolViolationResult(error);
+            }
+            throw error;
+        }
     });
     server.registerTool('iranti_write', {
         description: `Write one durable fact to shared memory for a specific entity.
@@ -282,7 +663,9 @@ agents, or sessions should retain. Requires: entity ("type/id"),
 key, value JSON, and summary. Confidence is optional and defaults
 to 85. Conflicts on the same entity+key are detected automatically
 and may be resolved or escalated. Personal-memory keys honor the
-configured canonical personal entity for this project/session.`,
+configured canonical personal entity for this project/session.
+Use properties JSON when you need structured issue or workflow metadata
+such as issueStatus=open|resolved, severity, or resolution notes.`,
         inputSchema: {
             entity: z.string().min(1).describe('Entity in entityType/entityId format.'),
             key: z.string().min(1).describe('Fact key.'),
@@ -290,12 +673,16 @@ configured canonical personal entity for this project/session.`,
             summary: z.string().min(1).describe('Short retrieval-safe summary.'),
             confidence: z.number().int().min(0).max(100).optional().describe('Raw confidence score.'),
             source: z.string().optional().describe('Source label for provenance.'),
+            propertiesJson: z.string().optional().describe('Optional JSON-serialized fact properties for metadata such as issueStatus or severity.'),
             validFrom: z.string().optional().describe('Optional ISO timestamp for when the fact became true/current.'),
             requestId: z.string().optional().describe('Optional idempotency key.'),
             agent: z.string().optional().describe('Override the default agent id.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id.'),
         },
-    }, async ({ entity, key, valueJson, summary, confidence, source, validFrom, requestId, agent }) => {
+    }, async ({ entity, key, valueJson, summary, confidence, source, propertiesJson, validFrom, requestId, agent, agentId }) => {
         const target = (0, autoRemember_1.resolvePersonalWriteTarget)({ entity, key });
+        const resolvedAgent = resolveToolAgent(agent, agentId);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
         const result = await iranti.write({
             entity: target.entity,
             key,
@@ -303,7 +690,8 @@ configured canonical personal entity for this project/session.`,
             summary,
             confidence: confidence ?? 85,
             source: source?.trim() || defaultWriteSource(),
-            agent: withDefaultAgent(agent),
+            agent: resolvedAgent,
+            properties: propertiesJson ? safeJsonParse(propertiesJson) : undefined,
             validFrom: parseIsoDate(validFrom),
             requestId,
         });
@@ -313,6 +701,54 @@ configured canonical personal entity for this project/session.`,
             ...(target.rerouted ? { originalEntity: target.originalEntity, canonicalizedPersonalEntity: true } : {}),
         });
     });
+    server.registerTool('iranti_write_issue', {
+        description: `Write a canonical open or resolved issue fact on a stable key.
+Use this when you want defects, bugs, or chores to remain first-class shared
+memory instead of loose prose. The same issueId always maps to the same
+issue_<id> key, so changing status from open to resolved archives the prior
+state automatically while preserving history. Prefer this over hand-rolling
+issueStatus properties through iranti_write when the fact is specifically a
+trackable issue lifecycle entry.`,
+        inputSchema: {
+            entity: z.string().min(1).describe('Owner entity in entityType/entityId format, usually a project entity.'),
+            issueId: z.string().min(1).describe('Stable issue identifier that becomes issue_<normalized_id>.'),
+            title: z.string().min(1).describe('Short human-readable issue title.'),
+            status: z.enum(['open', 'resolved']).describe('Issue lifecycle status.'),
+            summary: z.string().min(1).describe('Short retrieval-safe summary of the issue state.'),
+            confidence: z.number().int().min(0).max(100).optional().describe('Raw confidence score.'),
+            source: z.string().optional().describe('Source label for provenance.'),
+            severity: z.enum(['low', 'medium', 'high', 'critical']).optional().describe('Optional issue severity.'),
+            detailsJson: z.string().optional().describe('Optional JSON-serialized structured issue details.'),
+            discoveredAt: z.string().optional().describe('Optional ISO timestamp for when the issue was first observed.'),
+            resolvedAt: z.string().optional().describe('Optional ISO timestamp for when the issue was resolved.'),
+            resolution: z.string().optional().describe('Optional resolution note for resolved issues.'),
+            tags: z.array(z.string()).optional().describe('Optional issue tags.'),
+            requestId: z.string().optional().describe('Optional idempotency key.'),
+            agent: z.string().optional().describe('Override the default agent id.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id.'),
+        },
+    }, async ({ entity, issueId, title, status, summary, confidence, source, severity, detailsJson, discoveredAt, resolvedAt, resolution, tags, requestId, agent, agentId }) => {
+        const resolvedAgent = resolveToolAgent(agent, agentId);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
+        const result = await iranti.writeIssue({
+            entity,
+            issueId,
+            title,
+            status,
+            summary,
+            confidence: confidence ?? 85,
+            source: source?.trim() || defaultWriteSource(),
+            agent: resolvedAgent,
+            severity,
+            details: detailsJson ? safeJsonParse(detailsJson) : undefined,
+            discoveredAt,
+            resolvedAt,
+            resolution,
+            tags,
+            requestId,
+        });
+        return textResult(result);
+    });
     server.registerTool('iranti_remember_response', {
         description: `Persist a strict durable summary from your own response.
 Use this after you decide to say something like "the next step is ...",
@@ -327,16 +763,23 @@ this for arbitrary prose or every turn.`,
             source: z.string().optional().describe('Optional provenance label override.'),
             confidence: z.number().int().min(0).max(100).optional().describe('Raw confidence score for remembered summaries.'),
             agent: z.string().optional().describe('Override the default agent id.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id.'),
         },
-    }, async ({ response, projectEntity, personalEntity, source, confidence, agent }) => {
+    }, async ({ response, projectEntity, personalEntity, source, confidence, agent, agentId }) => {
+        const resolvedAgent = resolveToolAgent(agent, agentId);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
         const result = await (0, autoRemember_1.rememberAssistantResponseFacts)({
             iranti,
             response,
-            agent: withDefaultAgent(agent),
+            agent: resolvedAgent,
             source: source?.trim() || defaultWriteSource(),
             projectEntity,
             personalEntity,
             confidence: confidence ?? 90,
+            ledgerContext: {
+                source: 'mcp',
+                host: currentHost() || 'generic_mcp',
+            },
         });
         return textResult(result);
     });
@@ -348,14 +791,17 @@ this for arbitrary prose or every turn.`,
             confidence: z.number().int().min(0).max(100).optional().describe('Raw confidence score.'),
             source: z.string().optional().describe('Source label for provenance.'),
             agent: z.string().optional().describe('Override the default agent id.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id.'),
         },
-    }, async ({ entity, content, confidence, source, agent }) => {
+    }, async ({ entity, content, confidence, source, agent, agentId }) => {
+        const resolvedAgent = resolveToolAgent(agent, agentId);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
         const result = await iranti.ingest({
             entity,
             content,
             confidence: confidence ?? 80,
             source: source?.trim() || defaultWriteSource(),
-            agent: withDefaultAgent(agent),
+            agent: resolvedAgent,
         });
         return textResult(result);
     });
@@ -370,49 +816,106 @@ this for arbitrary prose or every turn.`,
         },
     }, async ({ fromEntity, relationshipType, toEntity, propertiesJson, createdBy }) => {
         const properties = propertiesJson ? safeJsonParse(propertiesJson) : undefined;
+        const resolvedAgent = withDefaultAgent(createdBy);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
         const result = await iranti.relate(fromEntity, relationshipType, toEntity, {
-            createdBy: withDefaultAgent(createdBy),
+            createdBy: resolvedAgent,
             properties: (properties ?? {}),
         });
         return textResult({ ok: true, result });
     });
     server.registerTool('iranti_related', {
-        description: 'Read directly related entities (1 hop) for a given entity.',
+        description: `Read directly related entities (1 hop) for a given entity.
+REQUIRED: call iranti_attend before this discovery tool so Iranti can decide
+whether memory should be injected before graph traversal.`,
         inputSchema: {
             entity: z.string().min(1).describe('Entity in entityType/entityId format.'),
+            agent: z.string().optional().describe('Override the default agent id for protocol tracking.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id for protocol tracking.'),
         },
-    }, async ({ entity }) => {
-        const result = await iranti.getRelated(entity);
-        return textResult(result);
+    }, async ({ entity, agent, agentId }) => {
+        const resolvedAgent = resolveToolAgent(agent, agentId);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
+        try {
+            const result = await iranti.getRelated(entity);
+            return textResult(result);
+        }
+        catch (error) {
+            if (error instanceof sdk_1.ProtocolViolationError) {
+                return protocolViolationResult(error);
+            }
+            throw error;
+        }
     });
     server.registerTool('iranti_related_deep', {
-        description: 'Read related entities up to N hops deep for a given entity.',
+        description: `Read related entities up to N hops deep for a given entity.
+REQUIRED: call iranti_attend before this discovery tool so Iranti can decide
+whether memory should be injected before graph traversal.`,
         inputSchema: {
             entity: z.string().min(1).describe('Entity in entityType/entityId format.'),
             depth: z.number().int().min(1).max(5).optional().describe('Traversal depth.'),
+            agent: z.string().optional().describe('Override the default agent id for protocol tracking.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id for protocol tracking.'),
         },
-    }, async ({ entity, depth }) => {
-        const result = await iranti.getRelatedDeep(entity, depth ?? 2);
-        return textResult(result);
+    }, async ({ entity, depth, agent, agentId }) => {
+        const resolvedAgent = resolveToolAgent(agent, agentId);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
+        try {
+            const result = await iranti.getRelatedDeep(entity, depth ?? 2);
+            return textResult(result);
+        }
+        catch (error) {
+            if (error instanceof sdk_1.ProtocolViolationError) {
+                return protocolViolationResult(error);
+            }
+            throw error;
+        }
     });
     server.registerTool('iranti_who_knows', {
-        description: 'List which agents have written facts about an entity.',
+        description: `List which agents have written facts about an entity.
+REQUIRED: call iranti_attend before this discovery tool so Iranti can decide
+whether memory should be injected before provenance discovery.`,
         inputSchema: {
             entity: z.string().min(1).describe('Entity in entityType/entityId format.'),
+            agent: z.string().optional().describe('Override the default agent id for protocol tracking.'),
+            agentId: z.string().optional().describe('Alias for agent. Override the default agent id for protocol tracking.'),
         },
-    }, async ({ entity }) => {
-        const result = await iranti.whoKnows(entity);
-        return textResult(result);
+    }, async ({ entity, agent, agentId }) => {
+        const resolvedAgent = resolveToolAgent(agent, agentId);
+        syncRuntimeLedgerContext(iranti, undefined, resolvedAgent);
+        try {
+            const result = await iranti.whoKnows(entity);
+            return textResult(result);
+        }
+        catch (error) {
+            if (error instanceof sdk_1.ProtocolViolationError) {
+                return protocolViolationResult(error);
+            }
+            throw error;
+        }
     });
     if (isInteractiveTerminalLaunch()) {
         console.error('[iranti-mcp] stdio server running; waiting for an MCP client. Press Ctrl+C to exit.');
     }
     const transport = new stdio_js_1.StdioServerTransport();
+    installShutdownHooks(transport);
     await server.connect(transport);
 }
 main().catch((error) => {
     const formatted = (0, commandErrors_1.rewriteCommandError)('iranti mcp', error);
+    (0, staffEventRegistry_1.getStaffEventEmitter)().emit({
+        staffComponent: 'Attendant',
+        actionType: 'host_failure',
+        agentId: defaultAgentId(),
+        source: 'mcp',
+        level: 'audit',
+        reason: formatted.message,
+        metadata: {
+            host: currentHost() || 'generic_mcp',
+            operation: 'mcp_startup',
+        },
+    });
     console.error('[iranti-mcp] fatal:', formatted.message);
-    process.exit(1);
+    void shutdownProcess(1, 'fatal_error');
 });
 //# sourceMappingURL=iranti-mcp.js.map