iranti 0.2.51 → 0.3.2

package/dist/scripts/iranti-cli.js

@@ -13,6 +13,7 @@ const https_1 = __importDefault(require("https"));
 const promises_2 = __importDefault(require("readline/promises"));
 const stream_1 = require("stream");
 const net_1 = __importDefault(require("net"));
+const crypto_1 = require("crypto");
 const client_1 = require("../src/library/client");
 const apiKeys_1 = require("../src/security/apiKeys");
 const cliHelpRenderer_1 = require("../src/lib/cliHelpRenderer");
@@ -30,7 +31,10 @@ const backends_1 = require("../src/library/backends");
 const runtimeLifecycle_1 = require("../src/lib/runtimeLifecycle");
 const queries_1 = require("../src/library/queries");
 const autoRemember_1 = require("../src/lib/autoRemember");
+const semanticFactTags_1 = require("../src/lib/semanticFactTags");
 const staffEventRegistry_1 = require("../src/lib/staffEventRegistry");
+const scaffoldCloseout_1 = require("../src/lib/scaffoldCloseout");
+const projectLearning_1 = require("../src/lib/projectLearning");
 class CliError extends Error {
     constructor(code, message, hints = [], details) {
         super(message);
@@ -64,6 +68,7 @@ const ANSI = {
 };
 let CLI_DEBUG = process.argv.includes('--debug') || process.env.IRANTI_DEBUG === '1';
 let CLI_VERBOSE = CLI_DEBUG || process.argv.includes('--verbose') || process.env.IRANTI_VERBOSE === '1';
+let ACTIVE_PARSED_ARGS = null;
 // H-7: Cleanup/rollback stack — LIFO handlers run on SIGINT/SIGTERM to undo partial multi-step operations
 const _cleanupStack = [];
 function pushCleanup(fn) {
@@ -146,6 +151,15 @@ function verboseLog(message, details) {
 function cliError(code, message, hints = [], details) {
     return new CliError(code, message, hints, details);
 }
+function wantsJsonErrorEnvelope(args) {
+    return Boolean(args && hasFlag(args, 'json'));
+}
+function normalizeCliFailure(err) {
+    if (err instanceof CliError) {
+        return err;
+    }
+    return (0, commandErrors_1.rewriteCommandError)('iranti', err);
+}
 function parseArgs(argv) {
     const flags = new Map();
     const positionals = [];
@@ -282,6 +296,25 @@ function findClosestAncestorRuntimeRoot(startDir) {
     }
     return null;
 }
+function findClosestDoctorEnvTarget(startDir) {
+    for (const dir of walkAncestorPaths(startDir)) {
+        const repoEnv = path_1.default.join(dir, '.env');
+        if (fs_1.default.existsSync(repoEnv) && fs_1.default.statSync(repoEnv).isFile()) {
+            return {
+                envFile: repoEnv,
+                envSource: 'repo',
+            };
+        }
+        const projectEnv = path_1.default.join(dir, '.env.iranti');
+        if (fs_1.default.existsSync(projectEnv) && fs_1.default.statSync(projectEnv).isFile()) {
+            return {
+                envFile: projectEnv,
+                envSource: 'project-binding',
+            };
+        }
+    }
+    return { envFile: null, envSource: 'repo' };
+}
 function resolveInstallRootDetails(args, scope) {
     const explicitFlag = getFlag(args, 'root');
     const explicit = explicitFlag ? stripWrappingQuotes(explicitFlag) : (process.env.IRANTI_HOME ? stripWrappingQuotes(process.env.IRANTI_HOME) : undefined);
@@ -621,6 +654,16 @@ async function readEnvFile(filePath) {
     }
     return out;
 }
+async function readEnvFileIfExists(filePath) {
+    if (!filePath || !fs_1.default.existsSync(filePath))
+        return null;
+    try {
+        return await readEnvFile(filePath);
+    }
+    catch {
+        return null;
+    }
+}
 async function readInstanceMetaFile(metaFile) {
     if (!fs_1.default.existsSync(metaFile))
         return null;
@@ -632,7 +675,11 @@ async function readInstanceMetaFile(metaFile) {
         return null;
     }
 }
-function makeInstanceEnv(name, port, dbUrl, apiKey, instanceDir) {
+function resolveInstanceApiKeyPepper(existingPepper) {
+    const trimmed = existingPepper?.trim() ?? '';
+    return trimmed || (0, crypto_1.randomBytes)(32).toString('hex');
+}
+function makeInstanceEnv(name, port, dbUrl, apiKey, instanceDir, apiKeyPepper) {
     const lines = [
         '# Iranti instance env',
         `IRANTI_INSTANCE_NAME=${name}`,
@@ -645,6 +692,7 @@ function makeInstanceEnv(name, port, dbUrl, apiKey, instanceDir) {
         'IRANTI_ARCHIVIST_DEBOUNCE_MS=60000',
         'IRANTI_ARCHIVIST_INTERVAL_MS=0',
         `IRANTI_API_KEY=${apiKey ?? 'replace_me_with_api_key'}`,
+        `IRANTI_API_KEY_PEPPER=${apiKeyPepper}`,
         '',
     ];
     return lines.join('\n');
@@ -1054,13 +1102,28 @@ async function ensureProjectGitignore(projectPath) {
 async function writeProjectBinding(projectPath, updates) {
     await ensureDir(projectPath);
     const outFile = path_1.default.join(projectPath, '.env.iranti');
+    const previousBinding = fs_1.default.existsSync(outFile)
+        ? await readEnvFile(outFile).catch(() => ({}))
+        : {};
+    const normalizedUpdates = {
+        ...updates,
+        IRANTI_CODEBASE_ENTITY: updates.IRANTI_CODEBASE_ENTITY ?? previousBinding.IRANTI_CODEBASE_ENTITY ?? (0, projectLearning_1.deriveProjectCodebaseEntity)(projectPath),
+    };
     if (!fs_1.default.existsSync(outFile)) {
         await writeText(outFile, '# Iranti project binding\n');
     }
-    await upsertEnvFile(outFile, updates);
+    await upsertEnvFile(outFile, normalizedUpdates);
     await ensureProjectGitignore(projectPath);
+    const writtenBinding = await readEnvFile(outFile).catch(() => ({}));
+    await syncProjectBindingRegistry(projectPath, writtenBinding, previousBinding);
     return outFile;
 }
+function normalizeProjectRegistryPath(projectPath) {
+    const normalized = path_1.default.resolve(projectPath);
+    return process.platform === 'win32'
+        ? normalized.toLowerCase()
+        : normalized;
+}
 async function removeProjectPathFromRegistry(runtimeRoot, instanceName, projectPath) {
     const registryPath = path_1.default.join(runtimeRoot, 'instances', instanceName, 'projects.json');
     if (!fs_1.default.existsSync(registryPath))
@@ -1068,16 +1131,54 @@ async function removeProjectPathFromRegistry(runtimeRoot, instanceName, projectP
     const parsed = readJsonFile(registryPath);
     if (!parsed || !Array.isArray(parsed.projects))
         return false;
+    const expectedProjectPath = normalizeProjectRegistryPath(projectPath);
     const nextProjects = parsed.projects.filter((entry) => {
         if (!entry || typeof entry !== 'object')
             return false;
-        return String(entry.projectPath ?? '') !== projectPath;
+        return normalizeProjectRegistryPath(String(entry.projectPath ?? '')) !== expectedProjectPath;
     });
     if (nextProjects.length === parsed.projects.length)
         return false;
     await writeText(registryPath, `${JSON.stringify({ projects: nextProjects }, null, 2)}\n`);
     return true;
 }
+async function syncProjectBindingRegistry(projectPath, binding, previousBinding = {}) {
+    const nextRuntimeRoot = runtimeRootFromInstanceEnv(binding.IRANTI_INSTANCE_ENV ?? '');
+    const nextInstanceName = binding.IRANTI_INSTANCE?.trim() || null;
+    const previousRuntimeRoot = runtimeRootFromInstanceEnv(previousBinding.IRANTI_INSTANCE_ENV ?? '');
+    const previousInstanceName = previousBinding.IRANTI_INSTANCE?.trim() || null;
+    if (previousRuntimeRoot && previousInstanceName && (previousRuntimeRoot !== nextRuntimeRoot
+        || previousInstanceName !== nextInstanceName)) {
+        await removeProjectPathFromRegistry(previousRuntimeRoot, previousInstanceName, projectPath);
+    }
+    if (!nextRuntimeRoot || !nextInstanceName)
+        return;
+    const registryPath = path_1.default.join(nextRuntimeRoot, 'instances', nextInstanceName, 'projects.json');
+    const existingRegistry = fs_1.default.existsSync(registryPath)
+        ? readJsonFile(registryPath)
+        : null;
+    const existingProjects = Array.isArray(existingRegistry?.projects) ? existingRegistry.projects : [];
+    const normalizedProjectPath = normalizeProjectRegistryPath(projectPath);
+    const previousEntry = existingProjects.find((entry) => entry
+        && typeof entry === 'object'
+        && normalizeProjectRegistryPath(String(entry.projectPath ?? '')) === normalizedProjectPath);
+    const boundAt = typeof previousEntry?.boundAt === 'string' && previousEntry.boundAt.trim().length > 0
+        ? previousEntry.boundAt
+        : new Date().toISOString();
+    const nextProjects = existingProjects
+        .filter((entry) => !entry
+        || typeof entry !== 'object'
+        || normalizeProjectRegistryPath(String(entry.projectPath ?? '')) !== normalizedProjectPath)
+        .concat({
+        projectPath,
+        agentId: binding.IRANTI_AGENT_ID?.trim() || 'project_main',
+        memoryEntity: binding.IRANTI_MEMORY_ENTITY?.trim() || 'user/main',
+        mode: binding.IRANTI_PROJECT_MODE?.trim() || 'isolated',
+        boundAt,
+    })
+        .sort((a, b) => String(a.projectPath ?? '').localeCompare(String(b.projectPath ?? '')));
+    await writeText(registryPath, `${JSON.stringify({ projects: nextProjects }, null, 2)}\n`);
+}
 async function cleanupProjectBindingRegistry(projectPath, binding) {
     const removedFrom = [];
     const runtimeRoot = runtimeRootFromInstanceEnv(binding.IRANTI_INSTANCE_ENV ?? '');
@@ -1089,6 +1190,24 @@ async function cleanupProjectBindingRegistry(projectPath, binding) {
     }
     return removedFrom;
 }
+function readInstanceProjectRegistry(root, instanceName) {
+    const registryPath = path_1.default.join(root, 'instances', instanceName, 'projects.json');
+    if (!fs_1.default.existsSync(registryPath))
+        return [];
+    const parsed = readJsonFile(registryPath);
+    if (!parsed || !Array.isArray(parsed.projects))
+        return [];
+    return parsed.projects
+        .filter((entry) => entry && typeof entry === 'object' && typeof entry.projectPath === 'string' && entry.projectPath.trim().length > 0)
+        .map((entry) => ({
+        projectPath: String(entry.projectPath),
+        agentId: typeof entry.agentId === 'string' && entry.agentId.trim().length > 0 ? entry.agentId : 'project_main',
+        memoryEntity: typeof entry.memoryEntity === 'string' && entry.memoryEntity.trim().length > 0 ? entry.memoryEntity : 'user/main',
+        mode: typeof entry.mode === 'string' && entry.mode.trim().length > 0 ? entry.mode : 'isolated',
+        boundAt: typeof entry.boundAt === 'string' && entry.boundAt.trim().length > 0 ? entry.boundAt : null,
+    }))
+        .sort((a, b) => a.projectPath.localeCompare(b.projectPath));
+}
 async function withPromptSession(run) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         throw new Error('--interactive requires a real terminal session.');
@@ -1202,6 +1321,59 @@ function postgresDatabaseName(databaseUrl) {
     }
     return database;
 }
+function summarizeDatabaseTarget(databaseUrl) {
+    const trimmed = databaseUrl?.trim() ?? '';
+    if (!trimmed || detectPlaceholder(trimmed))
+        return null;
+    try {
+        const parsed = parsePostgresConnectionString(trimmed);
+        const database = decodeURIComponent(parsed.pathname.replace(/^\/+/, ''));
+        if (!database)
+            return parsed.host || trimmed;
+        return `${parsed.host}/${database}`;
+    }
+    catch {
+        return trimmed;
+    }
+}
+function summarizeActiveAuthority(envSource, bindingFile, boundInstanceEnvFile) {
+    if (bindingFile && boundInstanceEnvFile)
+        return 'project binding -> bound instance env';
+    if (bindingFile)
+        return 'project binding';
+    if (envSource.startsWith('instance:'))
+        return 'named instance env';
+    if (envSource === 'explicit-env')
+        return 'explicit env';
+    if (envSource === 'repo')
+        return 'repo env';
+    if (envSource === 'environment')
+        return 'environment';
+    return envSource;
+}
+async function buildOperatorAuthoritySummary(options) {
+    const repoEnv = await readEnvFileIfExists(options.repoEnvFile ?? null);
+    const boundDatabaseUrl = options.boundInstanceEnv?.DATABASE_URL?.trim() || null;
+    const nearbyBoundDatabaseUrl = options.nearbyBoundInstanceEnv?.DATABASE_URL?.trim() || null;
+    const selectedDatabaseUrl = options.env?.DATABASE_URL?.trim() || null;
+    const activeDatabaseUrl = boundDatabaseUrl || selectedDatabaseUrl;
+    const repoDatabaseUrl = repoEnv?.DATABASE_URL?.trim() || null;
+    return {
+        activeAuthority: summarizeActiveAuthority(options.envSource, options.bindingFile ?? null, options.boundInstanceEnvFile ?? null),
+        activeBindingSource: options.bindingFile ?? null,
+        activeBoundInstanceEnv: options.boundInstanceEnvFile ?? null,
+        activeDatabaseUrl,
+        activeDatabaseTarget: summarizeDatabaseTarget(activeDatabaseUrl),
+        repoDatabaseUrl,
+        repoDatabaseTarget: summarizeDatabaseTarget(repoDatabaseUrl),
+        repoDatabaseDiffers: Boolean(repoDatabaseUrl && activeDatabaseUrl && repoDatabaseUrl !== activeDatabaseUrl),
+        nearbyBindingSource: options.nearbyBindingFile ?? null,
+        nearbyBoundInstanceEnv: options.nearbyBoundInstanceEnvFile ?? null,
+        nearbyBindingDatabaseUrl: nearbyBoundDatabaseUrl,
+        nearbyBindingDatabaseTarget: summarizeDatabaseTarget(nearbyBoundDatabaseUrl),
+        nearbyBindingDiffers: Boolean(nearbyBoundDatabaseUrl && activeDatabaseUrl && nearbyBoundDatabaseUrl !== activeDatabaseUrl),
+    };
+}
 function isLocalPostgresHost(hostname) {
     const normalized = hostname.trim().toLowerCase();
     return normalized === 'localhost' || normalized === '127.0.0.1' || normalized === '::1';
@@ -1513,13 +1685,17 @@ async function ensureRuntimeInstalled(root, scope) {
 async function ensureInstanceConfigured(root, name, config) {
     const { instanceDir, envFile, metaFile } = instancePaths(root, name);
     const created = !fs_1.default.existsSync(envFile);
+    const existingEnv = fs_1.default.existsSync(envFile)
+        ? await readEnvFile(envFile).catch(() => ({}))
+        : {};
+    const apiKeyPepper = resolveInstanceApiKeyPepper(existingEnv.IRANTI_API_KEY_PEPPER);
     if (created) {
         await ensureDir(instanceDir);
         await ensureDir(path_1.default.join(instanceDir, 'logs'));
         await ensureDir(path_1.default.join(instanceDir, 'escalation', 'active'));
         await ensureDir(path_1.default.join(instanceDir, 'escalation', 'resolved'));
         await ensureDir(path_1.default.join(instanceDir, 'escalation', 'archived'));
-        await writeText(envFile, makeInstanceEnv(name, config.port, config.dbUrl, config.apiKey, instanceDir));
+        await writeText(envFile, makeInstanceEnv(name, config.port, config.dbUrl, config.apiKey, instanceDir, apiKeyPepper));
         const meta = {
             name,
             createdAt: new Date().toISOString(),
@@ -1535,6 +1711,7 @@ async function ensureInstanceConfigured(root, name, config) {
         IRANTI_PORT: String(config.port),
         DATABASE_URL: config.dbUrl,
         IRANTI_API_KEY: config.apiKey,
+        IRANTI_API_KEY_PEPPER: apiKeyPepper,
         LLM_PROVIDER: config.provider,
         ...config.providerKeys,
     });
@@ -1545,22 +1722,37 @@ async function ensureInstanceConfigured(root, name, config) {
     return { envFile, instanceDir, created };
 }
 function makeIrantiMcpServerConfig(projectEnvPath) {
+    const env = {
+        IRANTI_MCP_HOST: 'codex_cli',
+    };
+    if (projectEnvPath) {
+        env.IRANTI_PROJECT_ENV = projectEnvPath;
+    }
     return {
         command: 'iranti',
         args: ['mcp'],
-        ...(projectEnvPath
-            ? {
-                env: {
-                    IRANTI_PROJECT_ENV: projectEnvPath,
-                },
-            }
-            : {}),
+        env,
+    };
+}
+function makeClaudeLocalMcpServerConfig(projectEnvPath) {
+    const env = {
+        IRANTI_MCP_HOST: 'claude_code',
+    };
+    if (projectEnvPath) {
+        env.IRANTI_PROJECT_ENV = projectEnvPath;
+    }
+    return {
+        command: 'iranti',
+        args: ['mcp'],
+        env,
     };
 }
 function makeVsCodeIrantiMcpServerConfig(projectPath, projectEnvPath) {
     const resolvedProjectEnvPath = projectEnvPath ? path_1.default.resolve(projectEnvPath) : undefined;
     const localProjectEnvPath = path_1.default.join(projectPath, '.env.iranti');
-    const env = {};
+    const env = {
+        IRANTI_MCP_HOST: 'codex_vscode',
+    };
     if (resolvedProjectEnvPath && path_1.default.resolve(localProjectEnvPath) !== resolvedProjectEnvPath) {
         env.IRANTI_PROJECT_ENV = resolvedProjectEnvPath;
     }
@@ -1619,6 +1811,13 @@ async function resolveAttendantCliTarget(args) {
             cwd,
             projectEnvFile: explicitProjectEnv ? path_1.default.resolve(explicitProjectEnv) : undefined,
         });
+        debugLog('Attendant CLI runtime env resolved.', {
+            cwd,
+            authorityMode: loaded.authorityMode,
+            projectEnvFile: loaded.projectEnvFile ?? null,
+            instanceEnvFile: loaded.instanceEnvFile ?? null,
+            loadedFiles: loaded.loadedFiles.join(' | ') || '(none)',
+        });
         envSource = loaded.projectEnvFile ? 'project-binding' : 'environment';
         envFile = loaded.projectEnvFile ?? loaded.instanceEnvFile ?? null;
         projectEnvFile = loaded.projectEnvFile;
@@ -1638,7 +1837,11 @@ async function resolveAttendantCliTarget(args) {
         projectEnvFile,
         instanceEnvFile,
         agentId,
-        iranti: (0, createFirstPartyIranti_1.createFirstPartyIranti)({ connectionString }),
+        iranti: (0, createFirstPartyIranti_1.createFirstPartyIranti)({
+            connectionString,
+            sessionLedgerSource: 'cli',
+            sessionLedgerHost: 'plain_cli',
+        }),
     };
 }
 function truncateText(value, limit) {
@@ -1713,6 +1916,135 @@ function resolveTaskEntity(args) {
     }
     return entity;
 }
+function resolveIssueEntity(args) {
+    const explicit = getFlag(args, 'entity')?.trim();
+    if (explicit) {
+        if (!explicit.includes('/')) {
+            throw new Error('issue entity must use entityType/entityId format.');
+        }
+        return explicit;
+    }
+    const fromEnv = process.env.IRANTI_MEMORY_ENTITY?.trim();
+    if (fromEnv?.includes('/')) {
+        return fromEnv;
+    }
+    throw new Error('Missing issue entity. Pass --entity <entityType/entityId> or run from a bound project with IRANTI_MEMORY_ENTITY.');
+}
+function resolveIssueStatusFilter(args) {
+    const raw = getFlag(args, 'status')?.trim().toLowerCase();
+    if (!raw)
+        return null;
+    if (raw === 'open' || raw === 'resolved') {
+        return raw;
+    }
+    throw new Error(`Invalid --status '${raw}'. Use open or resolved.`);
+}
+function parseIssueListFact(entry) {
+    if (!entry.key.startsWith('issue_')) {
+        return { item: null, invalid: null };
+    }
+    const value = typeof entry.value === 'object' && entry.value ? entry.value : null;
+    if (!value) {
+        return {
+            item: null,
+            invalid: {
+                key: entry.key,
+                summary: entry.summary,
+                confidence: entry.confidence,
+                source: entry.source,
+                reason: 'issue_* fact value is not an object',
+            },
+        };
+    }
+    const rawStatus = typeof value?.status === 'string' ? value.status.toLowerCase() : '';
+    if (rawStatus !== 'open' && rawStatus !== 'resolved') {
+        return {
+            item: null,
+            invalid: {
+                key: entry.key,
+                summary: entry.summary,
+                confidence: entry.confidence,
+                source: entry.source,
+                reason: 'issue_* fact is missing canonical open/resolved status',
+            },
+        };
+    }
+    return {
+        item: {
+            key: entry.key,
+            issueId: typeof value?.issueId === 'string' && value.issueId.trim() ? value.issueId.trim() : entry.key.replace(/^issue_/, ''),
+            title: typeof value?.title === 'string' && value.title.trim() ? value.title.trim() : entry.summary,
+            status: rawStatus,
+            severity: typeof value?.severity === 'string' && value.severity.trim() ? value.severity.trim() : 'medium',
+            summary: entry.summary,
+            confidence: entry.confidence,
+            source: entry.source,
+            discoveredAt: typeof value?.discoveredAt === 'string' && value.discoveredAt.trim() ? value.discoveredAt.trim() : null,
+            resolvedAt: typeof value?.resolvedAt === 'string' && value.resolvedAt.trim() ? value.resolvedAt.trim() : null,
+            resolution: typeof value?.resolution === 'string' && value.resolution.trim() ? value.resolution.trim() : null,
+            tags: Array.isArray(value?.tags)
+                ? value.tags.map((tag) => String(tag).trim()).filter(Boolean)
+                : [],
+        },
+        invalid: null,
+    };
+}
+function compareIssueListItems(a, b) {
+    if (a.status !== b.status) {
+        return a.status === 'open' ? -1 : 1;
+    }
+    const severityRank = new Map([
+        ['critical', 0],
+        ['high', 1],
+        ['medium', 2],
+        ['low', 3],
+    ]);
+    const severityDelta = (severityRank.get(a.severity) ?? 99) - (severityRank.get(b.severity) ?? 99);
+    if (severityDelta !== 0)
+        return severityDelta;
+    return a.issueId.localeCompare(b.issueId);
+}
+function printIssuesResult(entity, items, statusFilter, inventoryCounts, invalidFacts) {
+    console.log(sectionTitle('Issues Command'));
+    console.log(`Entity: ${entity}`);
+    console.log(`Filter: ${statusFilter ?? 'all'}`);
+    console.log(`Total: ${items.length}`);
+    console.log(`Canonical inventory: ${inventoryCounts.canonicalTotal} (${inventoryCounts.open} open, ${inventoryCounts.resolved} resolved)`);
+    console.log(`Invalid issue_* facts: ${inventoryCounts.invalid}`);
+    console.log('');
+    if (invalidFacts.length > 0) {
+        console.log('Warnings:');
+        for (const invalid of invalidFacts) {
+            console.log(`  - ${invalid.key}: ${invalid.reason} [source=${invalid.source}, confidence=${invalid.confidence}]`);
+        }
+        console.log('');
+    }
+    if (items.length === 0) {
+        console.log('No issue facts found.');
+        return;
+    }
+    for (const item of items) {
+        const header = `[${item.status.toUpperCase()}] ${item.issueId} (${item.severity})`;
+        console.log(header);
+        console.log(`  Title: ${item.title}`);
+        console.log(`  Summary: ${item.summary}`);
+        console.log(`  Source: ${item.source}`);
+        console.log(`  Confidence: ${item.confidence}`);
+        if (item.discoveredAt) {
+            console.log(`  Discovered: ${item.discoveredAt}`);
+        }
+        if (item.resolvedAt) {
+            console.log(`  Resolved: ${item.resolvedAt}`);
+        }
+        if (item.resolution) {
+            console.log(`  Resolution: ${item.resolution}`);
+        }
+        if (item.tags.length > 0) {
+            console.log(`  Tags: ${item.tags.join(', ')}`);
+        }
+        console.log('');
+    }
+}
 function buildHandoffSummary(key, value) {
     switch (key) {
         case 'status': {
@@ -1805,6 +2137,11 @@ function printAttendResult(target, latestMessage, result) {
     console.log(`  confidence    ${result.decision.confidence}`);
     console.log(`  explanation   ${result.decision.explanation}`);
     console.log(`  facts         ${result.facts.length}`);
+    if ((result.memoryAttributions?.length ?? 0) > 0) {
+        const firstAttribution = result.memoryAttributions[0];
+        console.log(`  injection id  ${firstAttribution.injectionId}`);
+        console.log(`  attribution   ${firstAttribution.status} surfaced=${firstAttribution.surfaced} used=${firstAttribution.used} helpful=${firstAttribution.helpful}`);
+    }
     if (result.facts.length === 0) {
         console.log('');
         console.log('No facts selected for injection.');
@@ -1839,6 +2176,21 @@ function makeClaudeHookEntry(event, projectEnvPath) {
         ],
     };
 }
+const IRANTI_CLAUDE_ALLOWED_TOOLS = [
+    'mcp__iranti__iranti_handshake',
+    'mcp__iranti__iranti_attend',
+    'mcp__iranti__iranti_observe',
+    'mcp__iranti__iranti_checkpoint',
+    'mcp__iranti__iranti_query',
+    'mcp__iranti__iranti_search',
+    'mcp__iranti__iranti_write',
+    'mcp__iranti__iranti_remember_response',
+    'mcp__iranti__iranti_ingest',
+    'mcp__iranti__iranti_relate',
+    'mcp__iranti__iranti_related',
+    'mcp__iranti__iranti_related_deep',
+    'mcp__iranti__iranti_who_knows',
+];
 function isClaudeHooksObject(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
@@ -1871,12 +2223,46 @@ function needsClaudeHookSettingsUpgrade(value) {
     }
     return false;
 }
+function mergeClaudePermissionAllowList(existing) {
+    const currentPermissions = existing && typeof existing.permissions === 'object' && existing.permissions !== null && !Array.isArray(existing.permissions)
+        ? { ...existing.permissions }
+        : {};
+    const allow = Array.isArray(currentPermissions.allow)
+        ? [...currentPermissions.allow.map((value) => String(value))]
+        : [];
+    for (const toolName of IRANTI_CLAUDE_ALLOWED_TOOLS) {
+        if (!allow.includes(toolName)) {
+            allow.push(toolName);
+        }
+    }
+    return {
+        ...currentPermissions,
+        allow,
+    };
+}
 function makeClaudeHookSettings(projectEnvPath, existing) {
     const existingHooks = existing && isClaudeHooksObject(existing.hooks)
         ? existing.hooks
         : {};
+    const existingMcpServers = existing && existing.mcpServers && typeof existing.mcpServers === 'object' && !Array.isArray(existing.mcpServers)
+        ? existing.mcpServers
+        : {};
+    const existingEnabledMcpjsonServers = Array.isArray(existing?.enabledMcpjsonServers)
+        ? existing.enabledMcpjsonServers
+            .map((value) => String(value))
+            .filter((value) => value !== 'iranti')
+        : undefined;
     return {
         ...(existing ?? {}),
+        enableAllProjectMcpServers: false,
+        permissions: mergeClaudePermissionAllowList(existing),
+        mcpServers: {
+            ...existingMcpServers,
+            iranti: makeClaudeLocalMcpServerConfig(projectEnvPath),
+        },
+        ...(existingEnabledMcpjsonServers
+            ? { enabledMcpjsonServers: existingEnabledMcpjsonServers }
+            : {}),
         hooks: {
             ...existingHooks,
             SessionStart: [makeClaudeHookEntry('SessionStart', projectEnvPath)],
@@ -1994,12 +2380,87 @@ async function writeClaudeCodeProjectFiles(projectPath, projectEnvPath, force =
             settingsStatus = 'updated';
         }
     }
+    const claudeMdFile = path_1.default.join(projectPath, 'CLAUDE.md');
+    let claudeMdStatus = 'unchanged';
+    const irantiMdBlock = buildIrantiClaudeMdBlock();
+    if (!fs_1.default.existsSync(claudeMdFile)) {
+        await writeText(claudeMdFile, irantiMdBlock);
+        claudeMdStatus = 'created';
+    }
+    else {
+        const existing = fs_1.default.readFileSync(claudeMdFile, 'utf8');
+        if (!existing.includes('<!-- iranti-rules -->')) {
+            await writeText(claudeMdFile, `${existing.trimEnd()}\n\n${irantiMdBlock}`);
+            claudeMdStatus = 'updated';
+        }
+        else {
+            const replaced = existing.replace(/<!-- iranti-rules -->[\s\S]*?<!-- \/iranti-rules -->/, irantiMdBlock.trim());
+            if (replaced !== existing) {
+                await writeText(claudeMdFile, replaced);
+                claudeMdStatus = 'updated';
+            }
+        }
+    }
+    const closeout = await (0, scaffoldCloseout_1.writeProjectScaffoldCloseout)({
+        tool: 'claude',
+        projectPath,
+        projectEnvFile: resolvedProjectEnvPath ?? projectEnvPath ?? null,
+        files: [
+            { path: mcpFile, status: mcpStatus },
+            { path: vscodeMcpFile, status: vscodeMcpStatus },
+            { path: settingsFile, status: settingsStatus },
+            { path: claudeMdFile, status: claudeMdStatus },
+        ],
+        agentId: 'iranti_cli_scaffold',
+    });
     return {
         mcp: mcpStatus,
         vscodeMcp: vscodeMcpStatus,
         settings: settingsStatus,
+        claudeMd: claudeMdStatus,
+        closeout,
     };
 }
+function buildIrantiClaudeMdBlock() {
+    return [
+        '<!-- iranti-rules -->',
+        '# Iranti Memory Protocol',
+        '',
+        'IMPORTANT: These rules OVERRIDE any default behavior and MUST be followed exactly. No work should begin until the session-start acknowledgment is stated.',
+        '',
+        '## Every turn',
+        '1. Call `mcp__iranti__iranti_attend` before responding to the user message.',
+        '2. Call `mcp__iranti__iranti_attend` before using any knowledge discovery tool — Read, Grep, Glob, WebSearch, WebFetch, and Bash commands used as factual basis for a decision.',
+        '3. Call `mcp__iranti__iranti_attend` after knowledge discovery to check new findings against stored memory and decide what to inject, write, or checkpoint.',
+        '4. Call `mcp__iranti__iranti_attend` after delivering any substantive response — plans, decisions, analysis, or structured recommendations are durable findings that must be assessed before the next turn.',
+        '5. Call `mcp__iranti__iranti_write` after confirmed durable findings — decisions, blockers, next steps, validated environment details, what worked, what failed, what changed, and what happens next.',
+        '6. Call `mcp__iranti__iranti_write` after every Edit or Write tool call — file changes are always durable. Record what changed, why, and what the file now does.',
+        '7. Call `mcp__iranti__iranti_write` after any Bash command that reveals system state — build results, test outcomes, container state, environment facts, errors.',
+        '8. Call `mcp__iranti__iranti_write` after any WebSearch or WebFetch that surfaces confirmed external facts.',
+        '9. Call `mcp__iranti__iranti_write` after any Agent (subagent) tool completes — subagent findings are invisible to the hive mind otherwise.',
+        '10. If a recall-style lookup returns no facts, try at least one alternative retrieval angle before concluding the fact is not stored.',
+        '11. Call `mcp__iranti__iranti_attend` again when new knowledge should change what is loaded for the next step.',
+        '',
+        '## Session start',
+        '- Call `mcp__iranti__iranti_handshake` with the current task before responding to the first user message.',
+        '- After the handshake completes, you MUST explicitly state: "I acknowledge that Iranti is a hive mind. I have read the Iranti operating rules and the protocols for iranti_handshake, iranti_attend, iranti_write, iranti_checkpoint, and iranti_remember_response, and I pledge to use them to persist what I find, what works, what fails, what changes, and what happens next so later sessions do not have to rediscover it."',
+        '- This acknowledgment is strictly mandatory. No work should begin until it is stated.',
+        '',
+        '## After context compaction',
+        '- Call `mcp__iranti__iranti_handshake` before responding to the next user message.',
+        '',
+        '## Checkpointing',
+        '- Call `mcp__iranti__iranti_checkpoint` when completing a task, when shifting to a new task mid-session, at any natural pause point, and before stepping away from long or interrupted work.',
+        '- Record key actions in the checkpoint `actions` field so later sessions can see important commands, tests, searches, validations, and decisions without rerunning them blindly.',
+        '- Do not rely on `mcp__iranti__iranti_write` alone — facts and checkpoints are separate stores. A checkpoint not written means the next handshake recovers from stale data.',
+        '- Under-logged runs are non-compliant. Leave structured breadcrumbs for what you found, what worked, what failed, what changed, and what happens next instead of only a broad summary.',
+        '',
+        '## Host setup check',
+        '- If this file was not present at session start, run `iranti claude-setup .` to complete integration.',
+        '<!-- /iranti-rules -->',
+        '',
+    ].join('\n');
+}
 function hasCodexInstalled() {
     try {
         const proc = (0, commandInvocation_1.spawnSyncResolved)('codex', ['--version'], { stdio: 'ignore' });
@@ -2055,6 +2516,10 @@ async function isPortAvailable(port, host = '0.0.0.0') {
     });
 }
 function listPublishedDockerHostPorts() {
+    const injected = process.env.IRANTI_FAKE_DOCKER_PORTS?.trim();
+    if (injected) {
+        return (0, dockerCliParsing_1.parsePublishedDockerHostPorts)(injected);
+    }
     const docker = inspectDockerAvailability();
     if (!docker.daemonReachable)
         return new Set();
@@ -2305,12 +2770,21 @@ async function executeSetupPlan(plan) {
             IRANTI_INSTANCE: plan.instanceName,
             IRANTI_INSTANCE_ENV: configured.envFile,
         });
+        const bindingEnv = await readEnvFile(written);
+        const learningStatus = await (0, projectLearning_1.writeProjectLearningSnapshot)({
+            projectPath,
+            projectEnvFile: written,
+            binding: bindingEnv,
+            agentId: project.agentId,
+        });
         bindings.push({
             projectPath,
             envFile: written,
             agentId: project.agentId,
             projectMode: project.projectMode,
             autoRemember: project.autoRemember,
+            codebaseEntity: bindingEnv.IRANTI_CODEBASE_ENTITY ?? (0, projectLearning_1.deriveProjectCodebaseEntity)(projectPath),
+            learningStatus,
         });
         if (project.claudeCode) {
             await writeClaudeCodeProjectFiles(projectPath);
@@ -2339,7 +2813,7 @@ async function executeSetupPlan(plan) {
         bindings,
     };
 }
-function parseSetupConfig(filePath) {
+async function parseSetupConfig(filePath) {
     const resolved = path_1.default.resolve(filePath);
     if (!fs_1.default.existsSync(resolved)) {
         throw new Error(`Setup config file not found: ${resolved}`);
@@ -2361,7 +2835,7 @@ function parseSetupConfig(filePath) {
             : databaseModeRaw === 'existing' || databaseModeRaw === 'local' || databaseModeRaw.length === 0
                 ? 'local'
                 : (() => { throw new Error(`Unsupported databaseMode in setup config: ${databaseModeRaw}`); })();
-    const databaseUrl = deriveDatabaseUrlForMode(databaseMode, instanceName, String(raw?.databaseUrl ?? raw?.dbUrl ?? '').trim());
+    const databaseUrl = await resolveSetupDatabaseUrl(databaseMode, instanceName, String(raw?.databaseUrl ?? raw?.dbUrl ?? '').trim());
     const databaseIntentStrategy = parseDatabaseIntentStrategyFlag(String(raw?.databaseIntent ?? raw?.dbIntent ?? '').trim(), 'databaseIntent');
     const provider = normalizeProvider(String(raw?.provider ?? 'mock')) ?? 'mock';
     if (!isSupportedProvider(provider)) {
@@ -2423,7 +2897,7 @@ function parseSetupConfig(filePath) {
         }),
     };
 }
-function defaultsSetupPlan(args) {
+async function defaultsSetupPlan(args) {
     const scope = normalizeScope(getFlag(args, 'scope'));
     const root = path_1.default.resolve(getFlag(args, 'root') ?? resolveInstallRoot(args, scope));
     const mode = getFlag(args, 'mode') === 'shared' ? 'shared' : 'isolated';
@@ -2450,7 +2924,7 @@ function defaultsSetupPlan(args) {
     const explicitDatabaseUrl = (getFlag(args, 'db-url')
         ?? (databaseMode === 'managed' ? process.env.DATABASE_URL : '')
         ?? '').trim();
-    const databaseUrl = deriveDatabaseUrlForMode(databaseMode, instanceName, explicitDatabaseUrl);
+    const databaseUrl = await resolveSetupDatabaseUrl(databaseMode, instanceName, explicitDatabaseUrl);
     const databaseIntentStrategy = parseDatabaseIntentStrategyFlag(getFlag(args, 'db-intent'), '--db-intent');
     const provider = normalizeProvider(getFlag(args, 'provider') ?? process.env.LLM_PROVIDER ?? 'mock') ?? 'mock';
     if (!isSupportedProvider(provider)) {
@@ -2609,6 +3083,22 @@ function summarizeStatus(checks) {
         return 'warn';
     return 'pass';
 }
+async function resolveDatabaseAuthorityInfo(repoEnvFile, boundInstanceEnvFile) {
+    const normalizedRepoEnvFile = repoEnvFile && fs_1.default.existsSync(repoEnvFile) ? repoEnvFile : null;
+    const normalizedBoundEnvFile = boundInstanceEnvFile && fs_1.default.existsSync(boundInstanceEnvFile) ? boundInstanceEnvFile : null;
+    const repoEnv = normalizedRepoEnvFile ? await readEnvFile(normalizedRepoEnvFile) : null;
+    const boundEnv = normalizedBoundEnvFile ? await readEnvFile(normalizedBoundEnvFile) : null;
+    const repoEnvDatabaseUrl = repoEnv?.DATABASE_URL?.trim() || null;
+    const boundInstanceDatabaseUrl = boundEnv?.DATABASE_URL?.trim() || null;
+    return {
+        repoEnvFile: normalizedRepoEnvFile,
+        repoEnvDatabaseUrl,
+        boundInstanceDatabaseUrl,
+        mismatch: Boolean(repoEnvDatabaseUrl
+            && boundInstanceDatabaseUrl
+            && repoEnvDatabaseUrl !== boundInstanceDatabaseUrl),
+    };
+}
 function detectVsCodeMcpWorkspaceCheck(projectEnvPath) {
     const vscodeMcpPath = path_1.default.join(path_1.default.dirname(projectEnvPath), '.vscode', 'mcp.json');
     if (!fs_1.default.existsSync(vscodeMcpPath)) {
@@ -2680,6 +3170,9 @@ function collectDoctorRemediations(checks, envSource, envFile) {
         if (check.name === 'bound instance env' && check.status !== 'pass') {
             add('Run `iranti configure project` to refresh the project binding, or set IRANTI_INSTANCE_ENV in `.env.iranti` so doctor can inspect the bound local instance.');
         }
+        if (check.name === 'runtime root selection' && check.status !== 'pass') {
+            add('Rerun `iranti doctor` with `--root <runtime-root>` that matches the bound project instance, or refresh `.env.iranti` with `iranti configure project` if the binding is stale.');
+        }
         if (check.name === 'vscode mcp workspace' && check.status !== 'pass') {
             add('Run `iranti codex-setup` from the project root to scaffold `.vscode/mcp.json`, or add an `iranti` server entry there manually for VS Code MCP clients.');
         }
@@ -2723,15 +3216,14 @@ function resolveDoctorEnvTarget(args) {
             envSource: `instance:${instanceName}`,
         };
     }
-    const repoEnv = path_1.default.join(cwd, '.env');
-    const projectEnv = path_1.default.join(cwd, '.env.iranti');
-    if (fs_1.default.existsSync(repoEnv)) {
-        debugLog('Doctor target resolved from repo env.', { envFile: repoEnv });
-        return { envFile: repoEnv, envSource: 'repo' };
+    const discovered = findClosestDoctorEnvTarget(cwd);
+    if (discovered.envFile && discovered.envSource === 'repo') {
+        debugLog('Doctor target resolved from repo env.', { envFile: discovered.envFile });
+        return discovered;
     }
-    if (fs_1.default.existsSync(projectEnv)) {
-        debugLog('Doctor target resolved from project binding.', { envFile: projectEnv });
-        return { envFile: projectEnv, envSource: 'project-binding' };
+    if (discovered.envFile && discovered.envSource === 'project-binding') {
+        debugLog('Doctor target resolved from project binding.', { envFile: discovered.envFile });
+        return discovered;
     }
     debugLog('Doctor target resolution found no env file.', { cwd });
     return { envFile: null, envSource: 'repo' };
@@ -3022,6 +3514,23 @@ function deriveDatabaseUrlForMode(mode, instanceName, explicitDatabaseUrl) {
     }
     return `postgresql://${user}:${password}@${localDatabaseHost}:5432/iranti_${instanceName}`;
 }
+async function resolveSetupDatabaseUrl(mode, instanceName, explicitDatabaseUrl) {
+    if (mode !== 'docker') {
+        return deriveDatabaseUrlForMode(mode, instanceName, explicitDatabaseUrl);
+    }
+    const explicit = explicitDatabaseUrl?.trim() ?? '';
+    if (explicit && !detectPlaceholder(explicit)) {
+        return explicit;
+    }
+    const preferredPort = 5432;
+    const dockerPublishedPorts = listPublishedDockerHostPorts();
+    const selectedPort = await isPortUsable(preferredPort, '0.0.0.0', dockerPublishedPorts)
+        ? preferredPort
+        : await findNextAvailablePort(preferredPort + 1, '0.0.0.0', 50, dockerPublishedPorts);
+    const user = encodeURIComponent((process.env.POSTGRES_USER ?? 'postgres').trim() || 'postgres');
+    const password = encodeURIComponent((process.env.POSTGRES_PASSWORD ?? 'postgres').trim() || 'postgres');
+    return `postgresql://${user}:${password}@${preferredLocalDatabaseHost()}:${selectedPort}/iranti_${instanceName}`;
+}
 function preferredLocalDatabaseHost() {
     return process.platform === 'win32' ? '127.0.0.1' : 'localhost';
 }
@@ -3906,6 +4415,15 @@ function removeIrantiClaudeHooksFromValue(value) {
     }
     return Object.keys(next).length === 0 ? null : next;
 }
+function removeIrantiAgentsBlockFromText(value) {
+    if (!value.includes('<!-- iranti-rules -->'))
+        return value;
+    const next = value
+        .replace(/<!-- iranti-rules -->[\s\S]*?<!-- \/iranti-rules -->/g, '')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    return next.length === 0 ? null : `${next}\n`;
+}
 async function cleanupProjectBindingIntegrations(projectPath) {
     const result = { removed: [], updated: [], warnings: [] };
     const candidates = [
@@ -3952,6 +4470,26 @@ async function cleanupProjectBindingIntegrations(projectPath) {
             }
         }
     }
+    const agentsFile = path_1.default.join(projectPath, 'AGENTS.md');
+    if (fs_1.default.existsSync(agentsFile)) {
+        try {
+            const existing = await promises_1.default.readFile(agentsFile, 'utf8');
+            const next = removeIrantiAgentsBlockFromText(existing);
+            if (next !== existing) {
+                if (!next) {
+                    await promises_1.default.rm(agentsFile, { force: true });
+                    result.removed.push(agentsFile);
+                }
+                else {
+                    await writeText(agentsFile, next);
+                    result.updated.push(agentsFile);
+                }
+            }
+        }
+        catch {
+            result.warnings.push(`Skipped unreadable Codex agents file ${agentsFile}`);
+        }
+    }
     return result;
 }
 async function cleanupProjectArtifacts(artifacts) {
@@ -4023,6 +4561,37 @@ async function cleanupProjectArtifacts(artifacts) {
                 });
             }
         }
+        if (artifact.agentsFile && fs_1.default.existsSync(artifact.agentsFile)) {
+            try {
+                const existing = await promises_1.default.readFile(artifact.agentsFile, 'utf8');
+                const next = removeIrantiAgentsBlockFromText(existing);
+                if (next !== existing) {
+                    if (!next) {
+                        await promises_1.default.rm(artifact.agentsFile, { force: true });
+                        results.push({
+                            label: 'project-agents',
+                            status: 'pass',
+                            detail: `Removed ${artifact.agentsFile}`,
+                        });
+                    }
+                    else {
+                        await writeText(artifact.agentsFile, next);
+                        results.push({
+                            label: 'project-agents',
+                            status: 'pass',
+                            detail: `Removed Iranti Codex block from ${artifact.agentsFile}`,
+                        });
+                    }
+                }
+            }
+            catch {
+                results.push({
+                    label: 'project-agents',
+                    status: 'warn',
+                    detail: `Skipped unreadable text file ${artifact.agentsFile}`,
+                });
+            }
+        }
     }
     return results;
 }
@@ -4161,7 +4730,7 @@ async function uninstallCommand(args) {
         && !dryRun;
     if (execute && !dryRun) {
         if (requiresDetachedWindowsSelfUninstall) {
-            const artifactFiles = projectArtifacts.flatMap((artifact) => [artifact.bindingFile, artifact.mcpFile, artifact.claudeSettingsFile]
+            const artifactFiles = projectArtifacts.flatMap((artifact) => [artifact.bindingFile, artifact.mcpFile, artifact.claudeSettingsFile, artifact.agentsFile]
                 .filter((value) => Boolean(value)));
             const script = buildDetachedWindowsUninstallScript({
                 parentPid: process.pid,
@@ -4473,7 +5042,7 @@ async function setupCommand(args) {
         const dependencyChecks = await collectDependencyChecks();
         printDependencyChecks(dependencyChecks);
         console.log('');
-        const plan = configPath ? parseSetupConfig(configPath) : defaultsSetupPlan(args);
+        const plan = configPath ? await parseSetupConfig(configPath) : await defaultsSetupPlan(args);
         const result = await executeSetupPlan(plan);
         console.log(sectionTitle('Setup Complete'));
         console.log(`  runtime root   ${result.root}`);
@@ -4490,7 +5059,10 @@ async function setupCommand(args) {
         else {
             console.log('  projects');
             for (const binding of result.bindings) {
-                console.log(`    - ${binding.projectPath} (${binding.agentId}, ${binding.projectMode})`);
+                const learningSuffix = binding.learningStatus.status === 'written'
+                    ? `, learned=${binding.codebaseEntity}`
+                    : `, project-learning=${binding.learningStatus.status}`;
+                console.log(`    - ${binding.projectPath} (${binding.agentId}, ${binding.projectMode}${learningSuffix})`);
             }
         }
         printNextSteps([
@@ -4853,7 +5425,10 @@ async function setupCommand(args) {
     else {
         console.log('  projects');
         for (const binding of finalResult.bindings) {
-            console.log(`    - ${binding.projectPath} (${binding.agentId}, ${binding.projectMode}, auto-remember=${binding.autoRemember ? 'true' : 'false'})`);
+            const learningSuffix = binding.learningStatus.status === 'written'
+                ? `, codebase=${binding.codebaseEntity}`
+                : `, project-learning=${binding.learningStatus.status}`;
+            console.log(`    - ${binding.projectPath} (${binding.agentId}, ${binding.projectMode}, auto-remember=${binding.autoRemember ? 'true' : 'false'}${learningSuffix})`);
         }
     }
     const nextSteps = [
@@ -4868,8 +5443,37 @@ async function setupCommand(args) {
 }
 async function doctorCommand(args) {
     const json = hasFlag(args, 'json');
+    const scope = normalizeScope(getFlag(args, 'scope'));
     const { envFile, envSource } = resolveDoctorEnvTarget(args);
+    const repoEnvFile = findClosestAncestorFile(process.cwd(), '.env');
+    const resolution = resolveInstallRootDetails(args, scope);
+    const discovery = {
+        selectedRuntimeRoot: resolution.root,
+        selectionSource: resolution.source,
+        selectionReason: describeRuntimeRootSource(resolution.source),
+        boundRuntimeRoot: null,
+        boundInstanceEnv: null,
+        projectBindingFile: null,
+        projectBindingSource: null,
+        rootMismatch: false,
+        otherRuntimeRoots: [],
+    };
     const checks = [];
+    let authority = {
+        activeAuthority: summarizeActiveAuthority(envSource, null, null),
+        activeBindingSource: null,
+        activeBoundInstanceEnv: null,
+        activeDatabaseUrl: null,
+        activeDatabaseTarget: null,
+        repoDatabaseUrl: null,
+        repoDatabaseTarget: null,
+        repoDatabaseDiffers: false,
+        nearbyBindingSource: null,
+        nearbyBoundInstanceEnv: null,
+        nearbyBindingDatabaseUrl: null,
+        nearbyBindingDatabaseTarget: null,
+        nearbyBindingDiffers: false,
+    };
     const version = getPackageVersion();
     const pushEnvironmentChecks = async (env, prefix = '') => {
         const databaseUrl = env.DATABASE_URL;
@@ -4902,7 +5506,7 @@ async function doctorCommand(args) {
         });
         try {
             if (!detectPlaceholder(databaseUrl)) {
-                (0, client_1.initDb)(databaseUrl);
+                (0, client_1.initDb)(databaseUrl, { applicationName: 'iranti:cli:doctor' });
                 databaseInitializedForDoctor = true;
             }
             const backendName = (0, backends_1.resolveVectorBackendName)({
@@ -4992,12 +5596,33 @@ async function doctorCommand(args) {
         const treatAsProjectBinding = envSource === 'project-binding'
             || path_1.default.basename(envFile).toLowerCase() === '.env.iranti'
             || (Boolean(env.IRANTI_URL?.trim()) && detectPlaceholder(env.DATABASE_URL));
+        let linkedInstanceEnvFile = null;
+        let linkedEnv = null;
         checks.push({
             name: 'environment file',
             status: 'pass',
             detail: `${envSource} env loaded from ${envFile}`,
         });
         if (treatAsProjectBinding) {
+            const binding = await inspectProjectBinding(envFile);
+            const boundRuntimeRoot = binding.runtimeRoot ? path_1.default.resolve(binding.runtimeRoot) : null;
+            const selectedRuntimeRoot = path_1.default.resolve(resolution.root);
+            const otherRuntimeRoots = Array.from(new Set([boundRuntimeRoot]
+                .filter((candidate) => Boolean(candidate))
+                .filter((candidate) => candidate !== selectedRuntimeRoot && fs_1.default.existsSync(candidate))));
+            discovery.boundRuntimeRoot = boundRuntimeRoot;
+            discovery.boundInstanceEnv = binding.instanceEnvFile;
+            discovery.projectBindingFile = binding.bindingFile;
+            discovery.projectBindingSource = 'doctor-target';
+            discovery.rootMismatch = Boolean(boundRuntimeRoot && boundRuntimeRoot !== selectedRuntimeRoot);
+            discovery.otherRuntimeRoots = otherRuntimeRoots;
+            checks.push({
+                name: 'runtime root selection',
+                status: discovery.rootMismatch ? 'warn' : 'pass',
+                detail: discovery.rootMismatch
+                    ? `Doctor selected runtime root ${selectedRuntimeRoot} (${describeRuntimeRootSource(resolution.source)}), but the project binding points at ${boundRuntimeRoot}.`
+                    : `Doctor selected runtime root ${selectedRuntimeRoot} (${describeRuntimeRootSource(resolution.source)}).`,
+            });
             checks.push(detectPlaceholder(env.IRANTI_URL)
                 ? {
                     name: 'project binding url',
@@ -5023,28 +5648,28 @@ async function doctorCommand(args) {
                     status: 'pass',
                     detail: 'IRANTI_API_KEY is present in .env.iranti.',
                 });
-            const linkedInstanceEnv = env.IRANTI_INSTANCE_ENV?.trim();
-            if (!linkedInstanceEnv) {
+            linkedInstanceEnvFile = env.IRANTI_INSTANCE_ENV?.trim() || null;
+            if (!linkedInstanceEnvFile) {
                 checks.push({
                     name: 'bound instance env',
                     status: 'warn',
                     detail: 'IRANTI_INSTANCE_ENV is not set in .env.iranti. Skipping database and provider checks for the bound instance.',
                 });
             }
-            else if (!fs_1.default.existsSync(linkedInstanceEnv)) {
+            else if (!fs_1.default.existsSync(linkedInstanceEnvFile)) {
                 checks.push({
                     name: 'bound instance env',
                     status: 'warn',
-                    detail: `Linked instance env not found: ${linkedInstanceEnv}. Skipping database and provider checks for the bound instance.`,
+                    detail: `Linked instance env not found: ${linkedInstanceEnvFile}. Skipping database and provider checks for the bound instance.`,
                 });
             }
             else {
                 checks.push({
                     name: 'bound instance env',
                     status: 'pass',
-                    detail: `Using ${linkedInstanceEnv} for bound instance diagnostics.`,
+                    detail: `Using ${linkedInstanceEnvFile} for bound instance diagnostics.`,
                 });
-                const linkedEnv = await readEnvFile(linkedInstanceEnv);
+                linkedEnv = await readEnvFile(linkedInstanceEnvFile);
                 await pushEnvironmentChecks(linkedEnv, 'bound instance ');
             }
         }
@@ -5062,11 +5687,55 @@ async function doctorCommand(args) {
                     detail: 'IRANTI_API_KEY is present.',
                 });
         }
+        const nearbyProjectBindingFile = treatAsProjectBinding
+            ? null
+            : findClosestAncestorFile(path_1.default.dirname(envFile), '.env.iranti');
+        const nearbyBindingEnv = await readEnvFileIfExists(nearbyProjectBindingFile);
+        const nearbyBoundInstanceEnvFile = nearbyBindingEnv?.IRANTI_INSTANCE_ENV?.trim() || null;
+        const nearbyBoundInstanceEnv = await readEnvFileIfExists(nearbyBoundInstanceEnvFile);
+        authority = await buildOperatorAuthoritySummary({
+            envSource,
+            envFile,
+            env,
+            bindingFile: treatAsProjectBinding ? envFile : null,
+            boundInstanceEnvFile: linkedInstanceEnvFile,
+            boundInstanceEnv: linkedEnv,
+            repoEnvFile,
+            nearbyBindingFile: nearbyProjectBindingFile,
+            nearbyBoundInstanceEnvFile,
+            nearbyBoundInstanceEnv,
+        });
+        if (!treatAsProjectBinding && authority.nearbyBindingSource && authority.nearbyBindingDiffers) {
+            checks.push({
+                name: 'nearby project binding authority',
+                status: 'warn',
+                detail: `Repo env is the active doctor target, but nearby project binding ${authority.nearbyBindingSource} points at ${authority.nearbyBindingDatabaseTarget ?? 'an unknown database target'} via ${authority.nearbyBoundInstanceEnv ?? 'an unknown bound env'}. Direct DB checks against repo .env may miss facts stored in the bound instance DB.`,
+            });
+        }
     }
+    debugLog('Doctor authority summary resolved.', {
+        activeAuthority: authority.activeAuthority,
+        activeBindingSource: authority.activeBindingSource ?? null,
+        activeBoundInstanceEnv: authority.activeBoundInstanceEnv ?? null,
+        activeDatabaseTarget: authority.activeDatabaseTarget ?? null,
+        repoDatabaseTarget: authority.repoDatabaseTarget ?? null,
+        repoDatabaseDiffers: authority.repoDatabaseDiffers,
+        nearbyBindingSource: authority.nearbyBindingSource ?? null,
+        nearbyBindingDatabaseTarget: authority.nearbyBindingDatabaseTarget ?? null,
+        nearbyBindingDiffers: authority.nearbyBindingDiffers,
+    });
     const result = {
         version,
         envSource,
         envFile,
+        authority,
+        selectedRuntimeRoot: discovery.selectedRuntimeRoot,
+        selectedRuntimeRootSource: discovery.selectionSource,
+        boundRuntimeRoot: discovery.boundRuntimeRoot,
+        boundInstanceEnv: discovery.boundInstanceEnv,
+        rootMismatch: discovery.rootMismatch,
+        otherRuntimeRoots: discovery.otherRuntimeRoots,
+        discovery,
         status: summarizeStatus(checks),
         checks,
         remediations: collectDoctorRemediations(checks, envSource, envFile),
@@ -5087,6 +5756,26 @@ async function doctorCommand(args) {
             : paint(result.status.toUpperCase(), 'red')}`);
     if (envFile)
         console.log(`  env     : ${envFile}`);
+    console.log(`  authority : ${authority.activeAuthority}`);
+    if (authority.activeBindingSource)
+        console.log(`  binding   : ${authority.activeBindingSource}`);
+    if (authority.activeBoundInstanceEnv)
+        console.log(`  bound env : ${authority.activeBoundInstanceEnv}`);
+    if (authority.activeDatabaseTarget)
+        console.log(`  active db : ${authority.activeDatabaseTarget}`);
+    if (authority.activeDatabaseUrl)
+        console.log(`  active url: ${authority.activeDatabaseUrl}`);
+    if (authority.repoDatabaseDiffers && authority.repoDatabaseTarget) {
+        console.log(`  repo db   : ${authority.repoDatabaseTarget} (repo .env differs)`);
+    }
+    if (authority.nearbyBindingDiffers) {
+        if (authority.nearbyBindingSource)
+            console.log(`  nearby binding : ${authority.nearbyBindingSource}`);
+        if (authority.nearbyBoundInstanceEnv)
+            console.log(`  nearby bound env: ${authority.nearbyBoundInstanceEnv}`);
+        if (authority.nearbyBindingDatabaseTarget)
+            console.log(`  nearby db : ${authority.nearbyBindingDatabaseTarget} (binding differs)`);
+    }
     console.log('');
     for (const check of checks) {
         const marker = check.status === 'pass'
@@ -5120,6 +5809,24 @@ async function statusCommand(args) {
     const binding = projectEnv && fs_1.default.existsSync(projectEnv) ? await inspectProjectBinding(projectEnv) : null;
     const boundRuntimeRoot = binding?.runtimeRoot ?? null;
     const boundInstanceEnv = binding?.instanceEnvFile ?? null;
+    const projectBindingEnv = await readEnvFileIfExists(projectEnv);
+    const boundInstanceEnvMap = await readEnvFileIfExists(boundInstanceEnv);
+    const activeStatusEnv = projectEnv && fs_1.default.existsSync(projectEnv)
+        ? projectBindingEnv
+        : await readEnvFileIfExists(repoEnv);
+    const authority = await buildOperatorAuthoritySummary({
+        envSource: projectEnv && fs_1.default.existsSync(projectEnv) ? 'project-binding' : repoEnv && fs_1.default.existsSync(repoEnv) ? 'repo' : 'environment',
+        envFile: projectEnv && fs_1.default.existsSync(projectEnv)
+            ? projectEnv
+            : repoEnv && fs_1.default.existsSync(repoEnv)
+                ? repoEnv
+                : null,
+        env: activeStatusEnv,
+        bindingFile: projectEnv && fs_1.default.existsSync(projectEnv) ? projectEnv : null,
+        boundInstanceEnvFile: boundInstanceEnv,
+        boundInstanceEnv: boundInstanceEnvMap,
+        repoEnvFile: repoEnv,
+    });
     const rootMismatch = Boolean(boundRuntimeRoot && path_1.default.resolve(boundRuntimeRoot) !== path_1.default.resolve(root));
     const userInstallRuntimeRoot = fs_1.default.existsSync(path_1.default.join(resolution.userRoot, 'install.json')) ? resolution.userRoot : null;
     const systemInstallRuntimeRoot = fs_1.default.existsSync(path_1.default.join(resolution.systemRoot, 'install.json')) ? resolution.systemRoot : null;
@@ -5132,6 +5839,18 @@ async function statusCommand(args) {
     rows.push({ label: 'scope', value: scope });
     rows.push({ label: 'runtime_root', value: root });
     rows.push({ label: 'root_source', value: describeRuntimeRootSource(resolution.source) });
+    rows.push({ label: 'authority', value: authority.activeAuthority });
+    if (authority.activeBindingSource)
+        rows.push({ label: 'binding_source', value: authority.activeBindingSource });
+    if (authority.activeBoundInstanceEnv)
+        rows.push({ label: 'bound_instance_env', value: authority.activeBoundInstanceEnv });
+    if (authority.activeDatabaseTarget)
+        rows.push({ label: 'active_db_target', value: authority.activeDatabaseTarget });
+    if (authority.activeDatabaseUrl)
+        rows.push({ label: 'active_db_url', value: authority.activeDatabaseUrl });
+    if (authority.repoDatabaseDiffers && authority.repoDatabaseTarget) {
+        rows.push({ label: 'repo_db_target', value: `${authority.repoDatabaseTarget} (repo .env differs)` });
+    }
     if (boundRuntimeRoot)
         rows.push({ label: 'bound_root', value: boundRuntimeRoot });
     rows.push({ label: 'repo_env', value: repoEnv && fs_1.default.existsSync(repoEnv) ? repoEnv : '(missing)' });
@@ -5141,12 +5860,21 @@ async function statusCommand(args) {
         rows.push({ label: 'root_mismatch', value: 'project binding points at a different runtime root' });
     const instances = await collectRuntimeInstanceSummaries(root);
     const recommendedActions = Array.from(new Set(instances.flatMap((instance) => instance.repairHints)));
+    debugLog('Status authority summary resolved.', {
+        activeAuthority: authority.activeAuthority,
+        activeBindingSource: authority.activeBindingSource ?? null,
+        activeBoundInstanceEnv: authority.activeBoundInstanceEnv ?? null,
+        activeDatabaseTarget: authority.activeDatabaseTarget ?? null,
+        repoDatabaseTarget: authority.repoDatabaseTarget ?? null,
+        repoDatabaseDiffers: authority.repoDatabaseDiffers,
+    });
     if (json) {
         console.log(JSON.stringify({
             version: getPackageVersion(),
             scope,
             runtimeRoot: root,
             runtimeRootSource: resolution.source,
+            authority,
             discovery: {
                 selectedRuntimeRoot: root,
                 selectionSource: resolution.source,
@@ -5196,6 +5924,15 @@ async function statusCommand(args) {
             console.log(`    meta: ${instance.metaFile}`);
             console.log(`    config: ${describeInstanceConfig(instance.config)}`);
             console.log(`    runtime: ${describeInstanceRuntime(instance.runtime)}`);
+            if (instance.projectCount === 0) {
+                console.log('    projects: none bound');
+            }
+            else {
+                console.log(`    projects: ${instance.projectCount}`);
+                for (const project of instance.boundProjects) {
+                    console.log(`      - ${project.projectPath} (${project.agentId}, ${project.mode})`);
+                }
+            }
             if (instance.repairHints.length > 0) {
                 console.log('    hints:');
                 for (const hint of instance.repairHints) {
@@ -5215,6 +5952,108 @@ async function statusCommand(args) {
         }
     }
 }
+function handoffWriteProperties(key) {
+    switch (key) {
+        case 'status':
+            return {
+                memoryScope: 'project',
+                capturePhase: 'manual',
+                durableClass: 'handoff_status',
+                canonicalKey: 'status',
+                mergeStrategy: 'replace',
+                ...(0, semanticFactTags_1.buildSemanticFactTags)({
+                    memoryScope: 'project',
+                    durableClass: 'handoff_status',
+                    mergeStrategy: 'replace',
+                    extraTags: ['handoff', 'task_memory'],
+                }),
+            };
+        case 'next_step':
+            return {
+                memoryScope: 'project',
+                capturePhase: 'manual',
+                durableClass: 'next_step',
+                canonicalKey: 'next_step',
+                mergeStrategy: 'replace',
+                ...(0, semanticFactTags_1.buildSemanticFactTags)({
+                    memoryScope: 'project',
+                    durableClass: 'next_step',
+                    mergeStrategy: 'replace',
+                    extraTags: ['handoff', 'task_memory'],
+                }),
+            };
+        case 'current_owner':
+            return {
+                memoryScope: 'project',
+                capturePhase: 'manual',
+                durableClass: 'owner',
+                canonicalKey: 'current_owner',
+                mergeStrategy: 'replace',
+                ...(0, semanticFactTags_1.buildSemanticFactTags)({
+                    memoryScope: 'project',
+                    durableClass: 'owner',
+                    mergeStrategy: 'replace',
+                    extraTags: ['handoff', 'task_memory'],
+                }),
+            };
+        case 'blockers':
+            return {
+                memoryScope: 'project',
+                capturePhase: 'manual',
+                durableClass: 'open_risks',
+                canonicalKey: 'blockers',
+                mergeStrategy: 'replace',
+                ...(0, semanticFactTags_1.buildSemanticFactTags)({
+                    memoryScope: 'project',
+                    durableClass: 'open_risks',
+                    mergeStrategy: 'replace',
+                    extraTags: ['handoff', 'task_memory', 'blockers'],
+                }),
+            };
+        case 'artifacts':
+            return {
+                memoryScope: 'project',
+                capturePhase: 'manual',
+                durableClass: 'artifact',
+                canonicalKey: 'artifacts',
+                mergeStrategy: 'replace',
+                ...(0, semanticFactTags_1.buildSemanticFactTags)({
+                    memoryScope: 'project',
+                    durableClass: 'artifact',
+                    mergeStrategy: 'replace',
+                    extraTags: ['handoff', 'task_memory'],
+                }),
+            };
+        case 'active_handoff_task':
+            return {
+                memoryScope: 'project',
+                capturePhase: 'manual',
+                durableClass: 'handoff_task',
+                canonicalKey: 'active_handoff_task',
+                mergeStrategy: 'replace',
+                ...(0, semanticFactTags_1.buildSemanticFactTags)({
+                    memoryScope: 'project',
+                    durableClass: 'handoff_task',
+                    mergeStrategy: 'replace',
+                    extraTags: ['handoff', 'project_memory'],
+                }),
+            };
+        default:
+            return {
+                memoryScope: 'project',
+                capturePhase: 'manual',
+                durableClass: 'decision',
+                canonicalKey: key,
+                mergeStrategy: 'replace',
+                ...(0, semanticFactTags_1.buildSemanticFactTags)({
+                    memoryScope: 'project',
+                    durableClass: 'decision',
+                    mergeStrategy: 'replace',
+                    extraTags: ['handoff', 'task_memory'],
+                }),
+            };
+    }
+}
 async function collectRuntimeInstanceSummaries(root) {
     const instancesDir = path_1.default.join(root, 'instances');
     const instances = [];
@@ -5225,6 +6064,7 @@ async function collectRuntimeInstanceSummaries(root) {
     for (const entry of entries.filter((value) => value.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
         const { envFile, metaFile } = instancePaths(root, entry.name);
         const config = await inspectInstanceConfig(root, entry.name);
+        const boundProjects = readInstanceProjectRegistry(root, entry.name);
         let port = '(unknown)';
         if (config.state.envPresent && config.state.envReadable) {
             try {
@@ -5241,6 +6081,8 @@ async function collectRuntimeInstanceSummaries(root) {
             port,
             envFile: config.state.envPresent ? envFile : '(missing)',
             metaFile: config.state.metaPresent ? metaFile : '(missing)',
+            boundProjects,
+            projectCount: boundProjects.length,
             config,
             runtime,
             repairHints: buildInstanceRepairHints(entry.name, config, runtime),
@@ -5514,6 +6356,10 @@ async function createInstanceCommand(args) {
     }
     const { instanceDir, envFile, metaFile } = instancePaths(root, name);
     const instanceAlreadyExisted = fs_1.default.existsSync(instanceDir);
+    const existingEnv = fs_1.default.existsSync(envFile)
+        ? await readEnvFile(envFile).catch(() => ({}))
+        : {};
+    const apiKeyPepper = resolveInstanceApiKeyPepper(existingEnv.IRANTI_API_KEY_PEPPER);
     if (instanceAlreadyExisted && !hasFlag(args, 'force')) {
         throw new Error(`Instance '${name}' already exists at ${instanceDir}. Use --force to overwrite.`);
     }
@@ -5538,17 +6384,25 @@ async function createInstanceCommand(args) {
     await ensureDir(path_1.default.join(instanceDir, 'escalation', 'active'));
     await ensureDir(path_1.default.join(instanceDir, 'escalation', 'resolved'));
     await ensureDir(path_1.default.join(instanceDir, 'escalation', 'archived'));
-    await writeText(envFile, makeInstanceEnv(name, port, dbUrl, apiKey, instanceDir));
+    await writeText(envFile, makeInstanceEnv(name, port, dbUrl, apiKey, instanceDir, apiKeyPepper));
     await upsertEnvFile(envFile, {
+        IRANTI_API_KEY_PEPPER: apiKeyPepper,
         LLM_PROVIDER: provider,
         ...(providerKey && providerKeyName ? { [providerKeyName]: providerKey } : {}),
     });
+    const resolvedDatabaseIntent = resolveInstanceDatabaseIntent({
+        instanceName: name,
+        env: { DATABASE_URL: dbUrl },
+        meta: null,
+        dependencies: [],
+    }).intent;
     const meta = {
         name,
         createdAt: new Date().toISOString(),
         port,
         envFile,
         instanceDir,
+        ...(resolvedDatabaseIntent ? { databaseIntent: resolvedDatabaseIntent } : {}),
     };
     await writeJson(metaFile, meta);
     // Instance fully created — pop the rollback so it doesn't run on normal exit
@@ -5617,6 +6471,7 @@ async function showInstanceCommand(args) {
         : {};
     const meta = await readInstanceMetaFile(instancePaths(root, name).metaFile);
     const dependencies = (0, runtimeDependencies_1.parseInstanceDependencies)(meta?.dependencies).dependencies;
+    const boundProjects = readInstanceProjectRegistry(root, name);
     const databaseIntent = resolveInstanceDatabaseIntent({
         instanceName: name,
         env,
@@ -5637,6 +6492,12 @@ async function showInstanceCommand(args) {
     if (dependencies.length > 0) {
         console.log(`  deps: ${dependencies.map((dependency) => (0, runtimeDependencies_1.describeInstanceDependency)(dependency)).join(', ')}`);
     }
+    if (boundProjects.length > 0) {
+        console.log('  projects:');
+        for (const project of boundProjects) {
+            console.log(`    - ${project.projectPath} (${project.agentId}, ${project.mode})`);
+        }
+    }
     console.log(`  runtime: ${describeInstanceRuntime(runtime)}`);
     if (runtime.state?.healthUrl) {
         console.log(`  health: ${runtime.state.healthUrl}`);
@@ -5742,10 +6603,21 @@ async function projectInitCommand(args) {
         IRANTI_INSTANCE: instanceName,
         IRANTI_INSTANCE_ENV: envFile,
     });
+    const writtenBinding = await readEnvFile(outFile);
+    const learningStatus = await (0, projectLearning_1.writeProjectLearningSnapshot)({
+        projectPath,
+        projectEnvFile: outFile,
+        binding: writtenBinding,
+        agentId,
+    });
     console.log(sectionTitle('Project Initialized'));
     console.log(`  status ${okLabel()}`);
     console.log(`  wrote ${outFile}`);
     console.log(`  mode  ${projectMode}`);
+    console.log(`  codebase ${writtenBinding.IRANTI_CODEBASE_ENTITY ?? (0, projectLearning_1.deriveProjectCodebaseEntity)(projectPath)}`);
+    if (learningStatus.status !== 'written') {
+        console.log(`  learn ${paint(learningStatus.status, learningStatus.status === 'failed' ? 'red' : 'yellow')} (${learningStatus.detail})`);
+    }
     printNextSteps([
         `iranti doctor --instance ${instanceName}`,
         'iranti chat',
@@ -5879,6 +6751,9 @@ async function configureInstanceCommand(args) {
         }
         updates[envKey] = undefined;
     }
+    if (!env.IRANTI_API_KEY_PEPPER?.trim()) {
+        updates.IRANTI_API_KEY_PEPPER = resolveInstanceApiKeyPepper();
+    }
     let nextDependencies = currentDependencies;
     if (clearDockerContainer) {
         nextDependencies = currentDependencies.filter((dependency) => dependency.kind !== 'docker-container');
@@ -6031,7 +6906,7 @@ async function configureProjectCommand(args) {
         IRANTI_PERSONAL_MEMORY_ENTITY: explicitPersonalMemoryEntity ?? existing.IRANTI_PERSONAL_MEMORY_ENTITY ?? 'user/main',
         IRANTI_AUTO_REMEMBER: String(explicitAutoRemember ?? envFlagEnabled(existing.IRANTI_AUTO_REMEMBER)),
         IRANTI_PROJECT_MODE: normalizeProjectMode(explicitProjectMode, normalizeProjectMode(existing.IRANTI_PROJECT_MODE, inferProjectMode(projectPath, instanceEnvFile))),
-        IRANTI_INSTANCE: instanceName,
+        IRANTI_INSTANCE: instanceName ?? existing.IRANTI_INSTANCE,
         IRANTI_INSTANCE_ENV: instanceEnvFile,
     };
     if (!updates.IRANTI_URL) {
@@ -6041,6 +6916,13 @@ async function configureProjectCommand(args) {
         throw new Error('Unable to determine IRANTI_API_KEY. Provide --api-key <token> or configure the instance first.');
     }
     const written = await writeProjectBinding(projectPath, updates);
+    const writtenBinding = await readEnvFile(written);
+    const learningStatus = await (0, projectLearning_1.writeProjectLearningSnapshot)({
+        projectPath,
+        projectEnvFile: written,
+        binding: writtenBinding,
+        agentId: updates.IRANTI_AGENT_ID,
+    });
     const json = hasFlag(args, 'json');
     const result = {
         projectPath,
@@ -6050,6 +6932,8 @@ async function configureProjectCommand(args) {
         autoRemember: updates.IRANTI_AUTO_REMEMBER === 'true',
         projectMode: updates.IRANTI_PROJECT_MODE,
         instance: updates.IRANTI_INSTANCE ?? null,
+        codebaseEntity: writtenBinding.IRANTI_CODEBASE_ENTITY ?? (0, projectLearning_1.deriveProjectCodebaseEntity)(projectPath),
+        projectLearning: learningStatus,
     };
     if (json) {
         console.log(JSON.stringify(result, null, 2));
@@ -6063,9 +6947,13 @@ async function configureProjectCommand(args) {
     console.log(`  agent    ${updates.IRANTI_AGENT_ID}`);
     console.log(`  remember ${updates.IRANTI_AUTO_REMEMBER}`);
     console.log(`  mode     ${updates.IRANTI_PROJECT_MODE}`);
+    console.log(`  codebase ${writtenBinding.IRANTI_CODEBASE_ENTITY ?? (0, projectLearning_1.deriveProjectCodebaseEntity)(projectPath)}`);
     if (updates.IRANTI_INSTANCE) {
         console.log(`  instance ${updates.IRANTI_INSTANCE}`);
     }
+    if (learningStatus.status !== 'written') {
+        console.log(`  learn    ${paint(learningStatus.status, learningStatus.status === 'failed' ? 'red' : 'yellow')} (${learningStatus.detail})`);
+    }
     printNextSteps([
         `iranti doctor${updates.IRANTI_INSTANCE ? ` --instance ${updates.IRANTI_INSTANCE}` : ''}`,
     ]);
@@ -6090,7 +6978,7 @@ async function authCreateKeyCommand(args) {
         throw new Error(`Instance '${instanceName}' still has a placeholder DATABASE_URL. Update ${envFile} first.`);
     }
     const scopes = scopesRaw.split(',').map((value) => value.trim()).filter(Boolean);
-    (0, client_1.initDb)(env.DATABASE_URL);
+    (0, client_1.initDb)(env.DATABASE_URL, { applicationName: 'iranti:cli:auth_create' });
     const created = await (0, apiKeys_1.createOrRotateApiKey)({
         keyId,
         owner,
@@ -6104,7 +6992,7 @@ async function authCreateKeyCommand(args) {
         const resolvedProjectPath = path_1.default.resolve(projectPath);
         const existingBindingFile = path_1.default.join(resolvedProjectPath, '.env.iranti');
         const existingBinding = fs_1.default.existsSync(existingBindingFile) ? await readEnvFile(existingBindingFile) : {};
-        await writeProjectBinding(resolvedProjectPath, {
+        const written = await writeProjectBinding(resolvedProjectPath, {
             IRANTI_URL: `http://localhost:${env.IRANTI_PORT ?? '3001'}`,
             IRANTI_API_KEY: created.token,
             IRANTI_AGENT_ID: agentId ?? existingBinding.IRANTI_AGENT_ID ?? 'my_agent',
@@ -6114,6 +7002,13 @@ async function authCreateKeyCommand(args) {
             IRANTI_INSTANCE: instanceName,
             IRANTI_INSTANCE_ENV: envFile,
         });
+        const binding = await readEnvFile(written);
+        await (0, projectLearning_1.writeProjectLearningSnapshot)({
+            projectPath: resolvedProjectPath,
+            projectEnvFile: written,
+            binding,
+            agentId: agentId ?? binding.IRANTI_AGENT_ID ?? 'my_agent',
+        });
     }
     if (hasFlag(args, 'json')) {
         console.log(JSON.stringify({
@@ -6154,7 +7049,7 @@ async function authListKeysCommand(args) {
     if (detectPlaceholder(env.DATABASE_URL)) {
         throw new Error(`Instance '${instanceName}' still has a placeholder DATABASE_URL. Update ${envFile} first.`);
     }
-    (0, client_1.initDb)(env.DATABASE_URL);
+    (0, client_1.initDb)(env.DATABASE_URL, { applicationName: 'iranti:cli:auth_list' });
     const keys = await (0, apiKeys_1.listApiKeys)();
     if (hasFlag(args, 'json')) {
         console.log(JSON.stringify({ instance: instanceName, keys }, null, 2));
@@ -6182,7 +7077,7 @@ async function authRevokeKeyCommand(args) {
     if (detectPlaceholder(env.DATABASE_URL)) {
         throw new Error(`Instance '${instanceName}' still has a placeholder DATABASE_URL. Update ${envFile} first.`);
     }
-    (0, client_1.initDb)(env.DATABASE_URL);
+    (0, client_1.initDb)(env.DATABASE_URL, { applicationName: 'iranti:cli:auth_revoke' });
     const revoked = await (0, apiKeys_1.revokeApiKey)(keyId);
     if (!revoked) {
         throw new Error(`API key not found: ${keyId}`);
@@ -6315,6 +7210,52 @@ async function attendCommand(args) {
         await (0, client_1.disconnectDb)().catch(() => undefined);
     }
 }
+async function issuesCommand(args) {
+    try {
+        const json = hasFlag(args, 'json');
+        const target = await resolveAttendantCliTarget(args);
+        const entity = resolveIssueEntity(args);
+        const statusFilter = resolveIssueStatusFilter(args);
+        const allFacts = await target.iranti.queryAll(entity);
+        const parsedIssueFacts = allFacts
+            .map(parseIssueListFact)
+            .filter((result) => result.item || result.invalid);
+        const canonicalItems = parsedIssueFacts
+            .map((result) => result.item)
+            .filter((item) => Boolean(item));
+        const invalidIssueLikeFacts = parsedIssueFacts
+            .map((result) => result.invalid)
+            .filter((item) => Boolean(item))
+            .sort((a, b) => a.key.localeCompare(b.key));
+        const inventoryCounts = {
+            open: canonicalItems.filter((item) => item.status === 'open').length,
+            resolved: canonicalItems.filter((item) => item.status === 'resolved').length,
+            invalid: invalidIssueLikeFacts.length,
+            canonicalTotal: canonicalItems.length,
+            issueLikeTotal: canonicalItems.length + invalidIssueLikeFacts.length,
+        };
+        const items = canonicalItems
+            .filter((item) => !statusFilter || item.status === statusFilter)
+            .sort(compareIssueListItems);
+        await (0, staffEventRegistry_1.flushStaffEventEmitter)().catch(() => undefined);
+        if (json) {
+            console.log(JSON.stringify({
+                entity,
+                status: statusFilter,
+                total: items.length,
+                counts: inventoryCounts,
+                invalidIssueLikeFacts,
+                items,
+            }, null, 2));
+            return;
+        }
+        printIssuesResult(entity, items, statusFilter, inventoryCounts, invalidIssueLikeFacts);
+    }
+    finally {
+        await (0, staffEventRegistry_1.flushStaffEventEmitter)().catch(() => undefined);
+        await (0, client_1.disconnectDb)().catch(() => undefined);
+    }
+}
 async function handoffCommand(args) {
     try {
         const json = hasFlag(args, 'json');
@@ -6405,6 +7346,7 @@ async function handoffCommand(args) {
                 confidence,
                 source,
                 agent: target.agentId,
+                properties: handoffWriteProperties(write.key),
             });
         }
         await (0, staffEventRegistry_1.flushStaffEventEmitter)().catch(() => undefined);
@@ -6431,7 +7373,7 @@ async function handoffCommand(args) {
 function printClaudeSetupHelp() {
     console.log([
         'Scaffold Claude Code MCP and hook files for the current project.',
-        'Use this when a bound repo should be ready for Claude Code without hand-editing `.mcp.json`, `.vscode/mcp.json`, or `.claude/settings.local.json`.',
+        'Use this when a bound repo should be ready for Claude Code without hand-editing `.mcp.json`, `.vscode/mcp.json`, `.claude/settings.local.json`, or `CLAUDE.md`.',
         '',
         'Usage:',
         '  iranti claude-setup [path] [--project-env <path>] [--force]',
@@ -6445,9 +7387,10 @@ function printClaudeSetupHelp() {
         '',
         'Notes:',
         '  - Expects a project binding at .env.iranti unless --project-env is supplied.',
-        '  - Writes .mcp.json, .vscode/mcp.json, and .claude/settings.local.json.',
+        '  - Writes .mcp.json, .vscode/mcp.json, .claude/settings.local.json, and a local `CLAUDE.md` Iranti protocol block.',
         '  - Adds the Iranti MCP server to existing .mcp.json / .vscode/mcp.json files without removing other servers.',
         '  - Leaves existing Claude hook files untouched unless --force is supplied.',
+        '  - The generated protocol block explicitly requires handshake at session start, attend before reply and before/after discovery, checkpointing at natural pauses/interrupted work, and durable writes after confirmed findings.',
         '',
         'Scan mode (--scan):',
         '  - Scans immediate subdirectories of the given dir by default.',
@@ -6570,6 +7513,7 @@ async function discoverProjectArtifacts(scanRoots) {
             const bindingFile = path_1.default.join(current, '.env.iranti');
             const mcpFile = path_1.default.join(current, '.mcp.json');
             const claudeSettingsFile = path_1.default.join(current, '.claude', 'settings.local.json');
+            const agentsFile = path_1.default.join(current, 'AGENTS.md');
             const artifact = { projectPath: current };
             if (fs_1.default.existsSync(bindingFile))
                 artifact.bindingFile = bindingFile;
@@ -6579,7 +7523,18 @@ async function discoverProjectArtifacts(scanRoots) {
             if (fs_1.default.existsSync(claudeSettingsFile) && hasIrantiClaudeHookSettings(readJsonFile(claudeSettingsFile))) {
                 artifact.claudeSettingsFile = claudeSettingsFile;
             }
-            if (artifact.bindingFile || artifact.mcpFile || artifact.claudeSettingsFile) {
+            if (fs_1.default.existsSync(agentsFile)) {
+                try {
+                    const agentsText = await promises_1.default.readFile(agentsFile, 'utf8');
+                    if (agentsText.includes('<!-- iranti-rules -->')) {
+                        artifact.agentsFile = agentsFile;
+                    }
+                }
+                catch {
+                    // Ignore unreadable AGENTS files during discovery; cleanup will warn if selected.
+                }
+            }
+            if (artifact.bindingFile || artifact.mcpFile || artifact.claudeSettingsFile || artifact.agentsFile) {
                 projects.set(current, artifact);
             }
             for (const entry of entries) {
@@ -6674,9 +7629,12 @@ async function claudeSetupCommand(args) {
     console.log(`  mcp       ${path_1.default.join(projectPath, '.mcp.json')}`);
     console.log(`  vscode    ${path_1.default.join(projectPath, '.vscode', 'mcp.json')}`);
     console.log(`  settings  ${path_1.default.join(projectPath, '.claude', 'settings.local.json')}`);
-    console.log(`  mcp status      ${result.mcp}`);
-    console.log(`  vscode status   ${result.vscodeMcp}`);
-    console.log(`  settings status ${result.settings}`);
+    console.log(`  claude.md ${path_1.default.join(projectPath, 'CLAUDE.md')}`);
+    console.log(`  mcp status        ${result.mcp}`);
+    console.log(`  vscode status     ${result.vscodeMcp}`);
+    console.log(`  settings status   ${result.settings}`);
+    console.log(`  claude.md status  ${result.claudeMd}`);
+    console.log(`  memory closeout   ${result.closeout.status} (${result.closeout.detail})`);
     console.log(`${infoLabel()} Next: open Claude Code in this project and verify Iranti tools are available.`);
 }
 async function chatCommand(args) {
@@ -6760,6 +7718,9 @@ function printHandshakeHelp() {
 function printAttendHelp() {
     (0, cliHelpRenderer_1.printAttendHelp)({ sectionTitle, commandText });
 }
+function printIssuesHelp() {
+    (0, cliHelpRenderer_1.printIssuesHelp)({ sectionTitle, commandText });
+}
 function printHandoffHelp() {
     (0, cliHelpRenderer_1.printHandoffHelp)({ sectionTitle, commandText });
 }
@@ -6772,8 +7733,305 @@ function printResolveHelp() {
 function printProviderKeyHelp() {
     (0, cliHelpRenderer_1.printProviderKeyHelp)({ sectionTitle, commandText });
 }
+function printMcpHelp() {
+    console.log([
+        'MCP server and maintenance commands.',
+        'Use this when the stdio MCP server should be started directly, or when you need to inspect and clean stale MCP wrapper/server pairs.',
+        '',
+        'Usage:',
+        '  iranti mcp',
+        '  iranti mcp cleanup [--dry-run] [--json]',
+        '',
+        'Notes:',
+        '  - `iranti mcp` starts the stdio MCP server for Claude, Codex, or another MCP client.',
+        '  - `iranti mcp cleanup` only removes stale launcher/server pairs that no longer have a live host ancestor.',
+        '  - Active chains still rooted in `claude.exe` or `codex.exe` are reported but not killed.',
+        '  - Current implementation is tuned for Windows process trees.',
+    ].join('\n'));
+}
+function isMcpLauncherCommand(commandLine) {
+    if (!commandLine)
+        return false;
+    const lower = commandLine.toLowerCase();
+    return lower.includes('\\node_modules\\iranti\\bin\\iranti.js')
+        && /\bmcp\b/.test(lower);
+}
+function isMcpChildCommand(commandLine) {
+    if (!commandLine)
+        return false;
+    return commandLine.toLowerCase().includes('\\dist\\scripts\\iranti-mcp.js');
+}
+function collectWindowsProcessSnapshot() {
+    const probe = runCommandCapture('powershell', [
+        '-NoProfile',
+        '-Command',
+        'Get-CimInstance Win32_Process | Select-Object ProcessId, ParentProcessId, Name, CommandLine | ConvertTo-Json -Compress',
+    ]);
+    if (probe.status !== 0) {
+        throw cliError('IRANTI_MCP_CLEANUP_PROBE_FAILED', 'Failed to inspect Windows process state for MCP cleanup.', ['Retry with `--debug` to inspect the PowerShell probe output.'], { stderr: probe.stderr.trim() || null });
+    }
+    const payload = JSON.parse(probe.stdout);
+    const rows = Array.isArray(payload) ? payload : [payload];
+    return rows.map((row) => ({
+        pid: Number(row.ProcessId ?? 0),
+        parentPid: row.ParentProcessId === null || row.ParentProcessId === undefined
+            ? null
+            : Number(row.ParentProcessId),
+        name: String(row.Name ?? ''),
+        commandLine: String(row.CommandLine ?? ''),
+    })).filter((row) => Number.isFinite(row.pid) && row.pid > 0);
+}
+function summarizeMcpCleanupCounts(candidates) {
+    return {
+        stale_no_host_ancestor: candidates.filter((candidate) => candidate.status === 'stale_no_host_ancestor').length,
+        stale_shell_no_host: candidates.filter((candidate) => candidate.status === 'stale_shell_no_host').length,
+        stale_child_parent_missing: candidates.filter((candidate) => candidate.status === 'stale_child_parent_missing').length,
+        stale_launcher_only: candidates.filter((candidate) => candidate.status === 'stale_launcher_only').length,
+        attached_claude: candidates.filter((candidate) => candidate.status === 'attached_claude').length,
+        attached_codex: candidates.filter((candidate) => candidate.status === 'attached_codex').length,
+        attached_or_uncertain: candidates.filter((candidate) => candidate.status === 'attached_or_uncertain').length,
+    };
+}
+function buildMcpCleanupReport(rows) {
+    const protectedPids = currentProcessFamilyPids();
+    const index = new Map();
+    for (const row of rows) {
+        index.set(row.pid, row);
+    }
+    const warnings = [];
+    const candidates = [];
+    const matchedLaunchers = new Set();
+    const childByLauncher = new Map();
+    for (const row of rows) {
+        if (row.name.toLowerCase() !== 'node.exe')
+            continue;
+        if (!isMcpChildCommand(row.commandLine))
+            continue;
+        if (protectedPids.has(row.pid))
+            continue;
+        const parent = row.parentPid ? index.get(row.parentPid) : undefined;
+        if (!parent) {
+            candidates.push({
+                status: 'stale_child_parent_missing',
+                childPid: row.pid,
+                reason: 'MCP child process has no live launcher parent.',
+            });
+            continue;
+        }
+        if (!isMcpLauncherCommand(parent.commandLine)) {
+            candidates.push({
+                status: 'attached_or_uncertain',
+                childPid: row.pid,
+                reason: 'MCP child process is attached to a parent that is not a recognized Iranti MCP launcher.',
+            });
+            continue;
+        }
+        matchedLaunchers.add(parent.pid);
+        childByLauncher.set(parent.pid, row);
+        if (protectedPids.has(parent.pid)) {
+            candidates.push({
+                status: 'attached_or_uncertain',
+                launcherPid: parent.pid,
+                childPid: row.pid,
+                reason: 'Skipping the current CLI process family.',
+            });
+            continue;
+        }
+        const grand = parent.parentPid ? index.get(parent.parentPid) : undefined;
+        const great = grand?.parentPid ? index.get(grand.parentPid) : undefined;
+        const grandName = grand?.name.toLowerCase() ?? '';
+        const greatName = great?.name.toLowerCase() ?? '';
+        if (!grand) {
+            candidates.push({
+                status: 'stale_no_host_ancestor',
+                launcherPid: parent.pid,
+                childPid: row.pid,
+                reason: 'Launcher parent exists, but no live host ancestor remains.',
+            });
+            continue;
+        }
+        if (grandName === 'cmd.exe' && !great) {
+            candidates.push({
+                status: 'stale_shell_no_host',
+                launcherPid: parent.pid,
+                childPid: row.pid,
+                reason: 'Launcher is still wrapped by cmd.exe, but the host process above cmd.exe is gone.',
+            });
+            continue;
+        }
+        if (grandName === 'cmd.exe' && greatName === 'claude.exe') {
+            candidates.push({
+                status: 'attached_claude',
+                launcherPid: parent.pid,
+                childPid: row.pid,
+                host: 'claude',
+                reason: 'Chain is still rooted in claude.exe.',
+            });
+            continue;
+        }
+        if (grandName === 'cmd.exe' && greatName === 'codex.exe') {
+            candidates.push({
+                status: 'attached_codex',
+                launcherPid: parent.pid,
+                childPid: row.pid,
+                host: 'codex',
+                reason: 'Chain is still rooted in codex.exe.',
+            });
+            continue;
+        }
+        candidates.push({
+            status: 'attached_or_uncertain',
+            launcherPid: parent.pid,
+            childPid: row.pid,
+            reason: 'Launcher/server pair still has a live ancestor that is not a known stale shape.',
+        });
+    }
+    for (const row of rows) {
+        if (row.name.toLowerCase() !== 'node.exe')
+            continue;
+        if (!isMcpLauncherCommand(row.commandLine))
+            continue;
+        if (matchedLaunchers.has(row.pid) || protectedPids.has(row.pid))
+            continue;
+        const grand = row.parentPid ? index.get(row.parentPid) : undefined;
+        const great = grand?.parentPid ? index.get(grand.parentPid) : undefined;
+        const grandName = grand?.name.toLowerCase() ?? '';
+        const greatName = great?.name.toLowerCase() ?? '';
+        if (!grand) {
+            candidates.push({
+                status: 'stale_launcher_only',
+                launcherPid: row.pid,
+                reason: 'Launcher remains alive without a child or live host ancestor.',
+            });
+        }
+        else if (grandName === 'cmd.exe' && !great) {
+            candidates.push({
+                status: 'stale_launcher_only',
+                launcherPid: row.pid,
+                reason: 'Launcher is still wrapped by cmd.exe, but the host process above cmd.exe is gone.',
+            });
+        }
+    }
+    const safeStatuses = new Set([
+        'stale_no_host_ancestor',
+        'stale_shell_no_host',
+        'stale_child_parent_missing',
+        'stale_launcher_only',
+    ]);
+    const safeCandidates = candidates.filter((candidate) => safeStatuses.has(candidate.status));
+    const skippedCandidates = candidates.filter((candidate) => !safeStatuses.has(candidate.status));
+    if (safeCandidates.length === 0) {
+        warnings.push('No stale MCP launcher/server pairs were found with the current safe cleanup rule.');
+    }
+    return {
+        platform: process.platform,
+        supported: process.platform === 'win32',
+        dryRun: true,
+        counts: summarizeMcpCleanupCounts(candidates),
+        safeCandidates,
+        skippedCandidates,
+        cleaned: [],
+        warnings,
+    };
+}
+function printMcpCleanupReport(report) {
+    console.log(sectionTitle('MCP Cleanup'));
+    if (!report.supported) {
+        console.log(`${warnLabel()} MCP cleanup is currently supported on Windows only.`);
+        return;
+    }
+    console.log(`  safe stale candidates   ${report.safeCandidates.length}`);
+    console.log(`  attached claude         ${report.counts.attached_claude}`);
+    console.log(`  attached codex          ${report.counts.attached_codex}`);
+    console.log(`  other live / uncertain  ${report.counts.attached_or_uncertain}`);
+    console.log(`  cleaned entries         ${report.cleaned.length}`);
+    console.log(`  mode                    ${report.dryRun ? 'dry-run' : 'execute'}`);
+    console.log('');
+    if (report.safeCandidates.length > 0) {
+        console.log(sectionTitle('Safe Targets'));
+        for (const candidate of report.safeCandidates) {
+            const ids = [
+                candidate.launcherPid ? `launcher=${candidate.launcherPid}` : null,
+                candidate.childPid ? `child=${candidate.childPid}` : null,
+            ].filter((value) => Boolean(value));
+            console.log(`  ${commandText(candidate.status)} ${ids.join(' ')} - ${candidate.reason}`);
+        }
+        console.log('');
+    }
+    if (report.skippedCandidates.length > 0) {
+        console.log(sectionTitle('Skipped Targets'));
+        for (const candidate of report.skippedCandidates) {
+            const ids = [
+                candidate.launcherPid ? `launcher=${candidate.launcherPid}` : null,
+                candidate.childPid ? `child=${candidate.childPid}` : null,
+            ].filter((value) => Boolean(value));
+            console.log(`  ${commandText(candidate.status)} ${ids.join(' ')} - ${candidate.reason}`);
+        }
+        console.log('');
+    }
+    for (const warning of report.warnings) {
+        console.log(`${warnLabel()} ${warning}`);
+    }
+}
+async function mcpCleanupCommand(args) {
+    const json = hasFlag(args, 'json');
+    const dryRun = hasFlag(args, 'dry-run');
+    if (process.platform !== 'win32') {
+        const report = {
+            platform: process.platform,
+            supported: false,
+            dryRun,
+            counts: {
+                stale_no_host_ancestor: 0,
+                stale_shell_no_host: 0,
+                stale_child_parent_missing: 0,
+                stale_launcher_only: 0,
+                attached_claude: 0,
+                attached_codex: 0,
+                attached_or_uncertain: 0,
+            },
+            safeCandidates: [],
+            skippedCandidates: [],
+            cleaned: [],
+            warnings: ['MCP cleanup is currently implemented for Windows process trees only.'],
+        };
+        if (json) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        printMcpCleanupReport(report);
+        return;
+    }
+    const report = buildMcpCleanupReport(collectWindowsProcessSnapshot());
+    report.dryRun = dryRun;
+    if (!dryRun) {
+        const cleaned = new Set();
+        for (const candidate of report.safeCandidates) {
+            if (candidate.childPid && !cleaned.has(`child:${candidate.childPid}`)) {
+                const proc = runCommandCapture('powershell', ['-NoProfile', '-Command', `Stop-Process -Id ${candidate.childPid} -Force -ErrorAction SilentlyContinue`]);
+                if (proc.status === 0) {
+                    report.cleaned.push({ pid: candidate.childPid, role: 'child' });
+                    cleaned.add(`child:${candidate.childPid}`);
+                }
+            }
+            if (candidate.launcherPid && !cleaned.has(`launcher:${candidate.launcherPid}`)) {
+                const proc = runCommandCapture('powershell', ['-NoProfile', '-Command', `Stop-Process -Id ${candidate.launcherPid} -Force -ErrorAction SilentlyContinue`]);
+                if (proc.status === 0) {
+                    report.cleaned.push({ pid: candidate.launcherPid, role: 'launcher' });
+                    cleaned.add(`launcher:${candidate.launcherPid}`);
+                }
+            }
+        }
+    }
+    if (json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    printMcpCleanupReport(report);
+}
 async function main() {
     const args = parseArgs(process.argv.slice(2));
+    ACTIVE_PARSED_ARGS = args;
     setCliDebugFlags(args);
     debugLog('CLI invocation started.', {
         command: args.command,
@@ -7001,6 +8259,14 @@ async function main() {
         await attendCommand(args);
         return;
     }
+    if (args.command === 'issues') {
+        if (hasFlag(args, 'help')) {
+            printIssuesHelp();
+            return;
+        }
+        await issuesCommand(args);
+        return;
+    }
     if (args.command === 'handoff') {
         if (hasFlag(args, 'help')) {
             printHandoffHelp();
@@ -7026,6 +8292,26 @@ async function main() {
         return;
     }
     if (args.command === 'mcp') {
+        if (!args.subcommand || args.subcommand === 'server') {
+            if (hasFlag(args, 'help')) {
+                printMcpHelp();
+                return;
+            }
+            await handoffToScript('iranti-mcp', args.subcommand === 'server' ? process.argv.slice(4) : process.argv.slice(3));
+            return;
+        }
+        if (args.subcommand === 'cleanup') {
+            if (hasFlag(args, 'help')) {
+                printMcpHelp();
+                return;
+            }
+            await mcpCleanupCommand(args);
+            return;
+        }
+        if (args.subcommand === 'help' || args.subcommand === '--help') {
+            printMcpHelp();
+            return;
+        }
         await handoffToScript('iranti-mcp', process.argv.slice(3));
         return;
     }
@@ -7065,24 +8351,40 @@ main().then(async () => {
         await (0, staffEventRegistry_1.flushStaffEventEmitter)();
     }
     catch { }
-    const formattedError = (0, commandErrors_1.rewriteCommandError)('iranti', err);
-    const message = formattedError.message;
-    const code = err instanceof CliError ? err.code : null;
+    const failure = normalizeCliFailure(err);
+    const code = failure.code ?? 'IRANTI_COMMAND_FAILED';
+    const message = failure.message;
+    const hints = failure instanceof CliError ? failure.hints : (failure.hints ?? []);
+    const details = failure instanceof CliError ? failure.details : undefined;
+    if (wantsJsonErrorEnvelope(ACTIVE_PARSED_ARGS)) {
+        const payload = {
+            ok: false,
+            error: {
+                code,
+                message,
+                hints,
+                ...(details && Object.keys(details).length > 0 ? { details } : {}),
+                ...(CLI_DEBUG && failure.stack ? { stack: failure.stack } : {}),
+            },
+        };
+        process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
+        process.exit(1);
+    }
     console.error(`${failLabel('ERROR')}${code ? ` [${code}]` : ''} ${message}`);
-    if (err instanceof CliError && err.hints.length > 0) {
+    if (hints.length > 0) {
         console.error('');
         console.error('Possible fixes:');
-        for (const hint of err.hints) {
+        for (const hint of hints) {
             console.error(`  - ${hint}`);
         }
     }
-    if (CLI_DEBUG && err instanceof CliError && err.details && Object.keys(err.details).length > 0) {
+    if (CLI_DEBUG && details && Object.keys(details).length > 0) {
         console.error('');
-        console.error(`${paint('[DEBUG]', 'gray')} ${JSON.stringify(err.details, null, 2)}`);
+        console.error(`${paint('[DEBUG]', 'gray')} ${JSON.stringify(details, null, 2)}`);
     }
-    if (CLI_DEBUG && formattedError.stack) {
+    if (CLI_DEBUG && failure.stack) {
         console.error('');
-        console.error(formattedError.stack);
+        console.error(failure.stack);
     }
     process.exit(1);
 });