@pcircle/memesh 4.8.2 → 4.8.5

package/dist/core/doctor.js

@@ -12,7 +12,7 @@ import { probeProvider } from './llm-validator.js';
 import { openDatabase, closeDatabase, getPendingReindexInfo, isDatabaseOpen, readVectorGeneration, generationRowIds, } from '../db.js';
 import { getUpdateCheck } from './version-check.js';
 import { classifyBump } from './updater.js';
-import { getCurrentInstallChannel, getInstallChannelSupport, detectPluginHost } from './install-channel.js';
+import { getCurrentInstallChannel, getInstallChannelSupport, detectPluginHost, pluginHostConfigRoot, versionedPluginCacheRoots, PLUGIN_REFRESH_COMMANDS, } from './install-channel.js';
 import { getInstallRecord } from './install-id.js';
 import { citationRulePath, citationRuleState } from './citation-rule.js';
 import { getDbPath, getMemeshDirFromDbPath, homeDir, memeshDir, getProjectName } from './paths.js';
@@ -27,6 +27,8 @@ import { parseSqliteUtcMs } from './time-utils.js';
 import { autoCaptureDecision } from './capture-flag.js';
 import { guardFromMetadata } from './guards.js';
 import { getAgentMessageStorageReport } from './agent-message-storage.js';
+import { readHostConfigFile } from '../host-runtime/config.js';
+import { summariseTelemetry } from './llm-telemetry.js';
 const EMBEDDING_PROBE_TIMEOUT_MS = 15000;
 const EXPECTED_HOOK_TYPES = ['PreToolUse', 'SessionStart', 'PostToolUse', 'Stop', 'PreCompact'];
 const AGENT_MESSAGE_STORAGE_QUOTA_ENV = 'MEMESH_AGENT_MESSAGE_STORAGE_QUOTA_BYTES';
@@ -147,6 +149,15 @@ function inspectAgentMessageStorage(db, databasePath, policy) {
         return undefined;
     }
 }
+function inspectCodexSessionSetup(codexPluginCacheDetected, existsSyncImpl) {
+    if (!codexPluginCacheDetected)
+        return null;
+    const configPath = path.join(getMemeshDirFromDbPath(), 'hosts', 'codex-session.json');
+    if (existsSyncImpl(configPath)) {
+        return createCheck('codex-session-setup', 'Codex ordinary-session notification setup', 'pass', 'A Codex plugin cache copy was detected, but this proves only that cached source exists, not that the plugin is enabled or registered. The explicit opt-in ordinary-session notification setup is present; durable inbox remains available, and MeMesh will not auto-attach.');
+    }
+    return createCheck('codex-session-setup', 'Codex ordinary-session notification setup', 'warn', 'A Codex plugin cache copy was detected, but this proves only that cached source exists, not that the plugin is enabled or registered. Durable inbox remains available, but live ordinary-session wakeup is inactive. Setup is explicit opt-in; MeMesh will not auto-attach.', 'Run `memesh agent setup codex-session --project <project> --principal <principal> --workspace <exact-workspace>`, then restart Codex.', { code: 'codex-session.config-missing' });
+}
 function configuredAgentMessageStoragePolicy(explicit) {
     if (explicit !== undefined)
         return explicit;
@@ -206,28 +217,49 @@ function inspectConfigFile(existsSyncImpl, readFileSyncImpl, getConfigPathImpl,
         return createCheck('config', 'Config', 'fail', `${configPath} could not be read or parsed (${msg}). Every setting in it — LLM provider, fallbacks, embedder — is being silently ignored right now.`, `Fix the JSON or remove the file to fall back to defaults: mv ${configPath} ${configPath}.bak`, { code: 'config-parse.unreadable', params: { path: configPath, detail: msg } });
     }
 }
-function inspectMcpConfig(packageRoot, existsSyncImpl, readFileSyncImpl) {
-    const mcpPath = path.join(packageRoot, '.mcp.json');
+const MCP_PLACEHOLDER = '${CLAUDE_PLUGIN_ROOT}';
+function declaredMcpManifest(packageRoot, readFileSyncImpl) {
+    const parsed = parseJsonFile(path.join(packageRoot, '.claude-plugin', 'plugin.json'), readFileSyncImpl);
+    if (!parsed.ok)
+        return null;
+    const declared = parsed.value.mcpServers;
+    if (typeof declared !== 'string' || !declared.startsWith('./'))
+        return null;
+    return declared.slice(2);
+}
+function inspectMcpConfig(packageRoot, installChannel, existsSyncImpl, readFileSyncImpl, env) {
+    const relativeManifest = declaredMcpManifest(packageRoot, readFileSyncImpl);
+    if (relativeManifest === null) {
+        return createCheck('mcp-config', 'MCP config', 'fail', '.claude-plugin/plugin.json declares no `mcpServers` path, so Claude Code has no MeMesh MCP server to start.', 'Reinstall MeMesh so the plugin manifest and the MCP manifest it names are both restored.', { code: 'mcp-config.missing' });
+    }
+    const label = relativeManifest;
+    const mcpPath = path.join(packageRoot, relativeManifest);
     if (!existsSyncImpl(mcpPath)) {
-        return createCheck('mcp-config', 'MCP config', 'fail', '.mcp.json is missing.', 'Restore `.mcp.json` from the package or reinstall MeMesh.', { code: 'mcp-config.missing' });
+        return createCheck('mcp-config', 'MCP config', 'fail', `${label} is missing.`, 'Reinstall MeMesh so the plugin manifest and the MCP manifest it names are both restored.', { code: 'mcp-config.missing' });
     }
     const parsed = parseJsonFile(mcpPath, readFileSyncImpl);
     if (!parsed.ok) {
-        return createCheck('mcp-config', 'MCP config', 'fail', '.mcp.json is not valid JSON.', `Fix ${mcpPath} so Claude Code can read the MCP server definition.`, { code: 'mcp-config.invalid-json', params: { path: mcpPath } });
+        return createCheck('mcp-config', 'MCP config', 'fail', `${label} is not valid JSON.`, `Fix ${mcpPath} so Claude Code can read the MCP server definition.`, { code: 'mcp-config.invalid-json', params: { path: mcpPath } });
     }
     const server = parsed.value.mcpServers?.memesh;
     if (!server || typeof server.command !== 'string') {
-        return createCheck('mcp-config', 'MCP config', 'fail', '.mcp.json does not define a usable `memesh` MCP server entry.', 'Reinstall MeMesh or restore the `mcpServers.memesh` entry in `.mcp.json`.', { code: 'mcp-config.no-entry' });
+        return createCheck('mcp-config', 'MCP config', 'fail', `${label} does not define a usable \`memesh\` MCP server entry.`, `Reinstall MeMesh or restore the \`mcpServers.memesh\` entry in \`${label}\`.`, { code: 'mcp-config.no-entry' });
     }
     const args = Array.isArray(server.args) ? server.args : [];
     const entry = typeof args[0] === 'string' ? args[0] : null;
     if (entry) {
-        const resolved = path.resolve(entry.replaceAll('${CLAUDE_PLUGIN_ROOT}', packageRoot));
+        const pluginRoot = installChannel === 'plugin-marketplace' ? packageRoot : (env.CLAUDE_PLUGIN_ROOT || null);
+        if (entry.includes(MCP_PLACEHOLDER) && pluginRoot === null) {
+            return createCheck('mcp-config', 'MCP config', 'warn', `${label} starts \`${entry}\`. NOT VERIFIED: \`${MCP_PLACEHOLDER}\` is substituted by the Claude Code plugin runtime, and this is a ${installChannel} install with CLAUDE_PLUGIN_ROOT unset — so the file it names was not checked.`, `Verify it the way the plugin runtime would: CLAUDE_PLUGIN_ROOT=${packageRoot} memesh doctor`, { code: 'mcp-config.placeholder-unresolved', params: { entry, channel: installChannel } });
+        }
+        const resolved = pluginRoot === null
+            ? path.resolve(packageRoot, entry)
+            : path.resolve(entry.replaceAll(MCP_PLACEHOLDER, pluginRoot));
         if (!existsSyncImpl(resolved)) {
-            return createCheck('mcp-config', 'MCP config', 'fail', `.mcp.json starts \`${entry}\`, and that file is not in this install — so every memesh MCP tool fails to start.`, 'Reinstall MeMesh; if you edited `.mcp.json` by hand, point it back at `${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js`.', { code: 'mcp-config.entry-missing', params: { entry, resolved } });
+            return createCheck('mcp-config', 'MCP config', 'fail', `${label} starts \`${entry}\`, and that file is not in this install — so every memesh MCP tool fails to start.`, `Reinstall MeMesh; if you edited \`${label}\` by hand, point it back at \`${MCP_PLACEHOLDER}/dist/mcp/server.js\`.`, { code: 'mcp-config.entry-missing', params: { entry, resolved } });
         }
     }
-    return createCheck('mcp-config', 'MCP config', 'pass', '.mcp.json is present, defines the memesh MCP server, and the script it starts exists.');
+    return createCheck('mcp-config', 'MCP config', 'pass', `${label} is present, defines the memesh MCP server, and the script it starts exists.`);
 }
 function extractHookScriptPaths(hooksConfig, packageRoot) {
     const hooks = hooksConfig.hooks;
@@ -235,8 +267,12 @@ function extractHookScriptPaths(hooksConfig, packageRoot) {
         return [];
     const scripts = new Set();
     for (const entries of Object.values(hooks)) {
-        for (const entry of entries ?? []) {
-            for (const hook of entry.hooks ?? []) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            if (!Array.isArray(entry.hooks))
+                continue;
+            for (const hook of entry.hooks) {
                 if (typeof hook.command !== 'string')
                     continue;
                 const command = hook.command.replace('${CLAUDE_PLUGIN_ROOT}/', '');
@@ -259,7 +295,10 @@ function inspectHooksConfig(packageRoot, platform, existsSyncImpl, readFileSyncI
             createCheck('hooks-config', 'Hooks config', 'fail', 'hooks/hooks.json is not valid JSON.', `Fix ${hooksPath} so Claude Code can load the hook definitions.`, { code: 'hooks-config.invalid-json', params: { path: hooksPath } }),
         ];
     }
-    const hookTypes = Object.keys(parsed.value.hooks ?? {});
+    const parsedHooks = parsed.value.hooks;
+    const hookTypes = parsedHooks && typeof parsedHooks === 'object' && !Array.isArray(parsedHooks)
+        ? Object.keys(parsedHooks)
+        : [];
     const missingTypes = EXPECTED_HOOK_TYPES.filter((type) => !hookTypes.includes(type));
     const configCheck = missingTypes.length > 0
         ? createCheck('hooks-config', 'Hooks config', 'fail', `hooks/hooks.json is missing expected hook types: ${missingTypes.join(', ')}.`, 'Restore the shipped hook configuration or reinstall MeMesh.', { code: 'hooks-config.missing-types', params: { types: missingTypes.join(', ') } })
@@ -602,7 +641,32 @@ function inspectNativeBinding(packageRoot, _existsSyncImpl, probeImpl = defaultN
     }
     return createCheck('native-binding', 'SQLite and vector search', 'warn', `sqlite-vec could not be loaded: ${result.message}. Memories are still saved and found by keyword; only search by meaning is off.`, `Run: cd "${packageRoot}" && npm install --omit=dev`, { code: 'native-binding.load-failed', params: { detail: result.message, root: packageRoot } });
 }
-function inspectShellCli(installChannel, packageRoot, resolveShellMemeshImpl) {
+function readVersionFromInstalledBinary(binaryPath, existsSyncImpl, readFileSyncImpl, realpathSyncImpl = fs.realpathSync) {
+    let resolved;
+    try {
+        resolved = realpathSyncImpl(binaryPath);
+    }
+    catch {
+        resolved = binaryPath;
+    }
+    let dir = path.dirname(resolved);
+    for (let depth = 0; depth < 8; depth += 1) {
+        const pkgPath = path.join(dir, 'package.json');
+        if (existsSyncImpl(pkgPath)) {
+            const parsed = parseJsonFile(pkgPath, readFileSyncImpl);
+            if (!parsed.ok)
+                return null;
+            const { name, version } = parsed.value;
+            return name === '@pcircle/memesh' && typeof version === 'string' ? version : null;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+function inspectShellCli(installChannel, packageRoot, packageVersion, resolveShellMemeshImpl, existsSyncImpl, readFileSyncImpl) {
     const shellPath = resolveShellMemeshImpl();
     const isSameAsCurrent = shellPath ? path.resolve(shellPath).startsWith(path.resolve(packageRoot)) : false;
     const hasDistinctShellCli = !!shellPath && !isSameAsCurrent;
@@ -612,7 +676,25 @@ function inspectShellCli(installChannel, packageRoot, resolveShellMemeshImpl) {
             : 'Running from npm-global install — shell access available in this terminal.');
     }
     if (hasDistinctShellCli) {
-        return createCheck('shell-cli', 'Shell CLI on PATH', 'pass', `\`memesh\` resolves to ${shellPath} (separate from this install at ${packageRoot}). Both paths coexist and share the same DB.`);
+        const shellVersion = readVersionFromInstalledBinary(shellPath, existsSyncImpl, readFileSyncImpl);
+        const shellIsBehind = shellVersion ? classifyBump(shellVersion, packageVersion) : null;
+        const thisIsBehind = shellVersion ? classifyBump(packageVersion, shellVersion) : null;
+        if (shellIsBehind) {
+            return createCheck('shell-cli', 'Shell CLI on PATH', 'warn', `\`memesh\` resolves to ${shellPath} (separate from this install at ${packageRoot}), and it is running ${shellVersion} — behind this install's ${packageVersion}. Both share the same DB, but an agent using this install and a human typing \`memesh\` in a terminal are running different code.`, 'Run `npm install -g @pcircle/memesh@latest` to bring the shell CLI up to date — a separate global install is never updated automatically by the plugin marketplace.');
+        }
+        if (thisIsBehind) {
+            const pluginHost = installChannel === 'plugin-marketplace' ? detectPluginHost(packageRoot) : null;
+            const fix = installChannel !== 'plugin-marketplace'
+                ? `Update this install (a ${installChannel}) to ${shellVersion} or newer via its own channel — see \`memesh status\`.`
+                : pluginHost
+                    ? `Run \`${PLUGIN_REFRESH_COMMANDS[pluginHost]}\` to bring this plugin copy to ${shellVersion} (or newer).`
+                    : `Bring this plugin copy to ${shellVersion} (or newer) with your host's refresh command — `
+                        + `Claude Code: \`${PLUGIN_REFRESH_COMMANDS['claude-code']}\`; `
+                        + `Codex: \`${PLUGIN_REFRESH_COMMANDS.codex}\`.`;
+            return createCheck('shell-cli', 'Shell CLI on PATH', 'warn', `\`memesh\` resolves to ${shellPath} (separate from this install at ${packageRoot}), and it is running ${shellVersion} — ahead of this install's ${packageVersion}.`, fix);
+        }
+        return createCheck('shell-cli', 'Shell CLI on PATH', 'pass', `\`memesh\` resolves to ${shellPath} (separate from this install at ${packageRoot}). Both paths coexist and share the same DB`
+            + (shellVersion ? `, both on ${packageVersion}.` : ' — could not read the shell copy\'s own version to compare.'));
     }
     if (installChannel === 'plugin-marketplace') {
         const host = detectPluginHost(packageRoot) === 'codex' ? 'Codex CLI' : 'Claude Code';
@@ -623,6 +705,282 @@ function inspectShellCli(installChannel, packageRoot, resolveShellMemeshImpl) {
         ? `\`memesh\` resolves to ${shellPath}.`
         : `No shell-PATH \`memesh\` detected. If you want terminal access, run \`npm install -g @pcircle/memesh\` (this install is a ${installChannel}, so the check is informational only).`);
 }
+function defaultMarketplaceHeadSha(host) {
+    if (host === 'codex') {
+        const codexHome = pluginHostConfigRoot('codex');
+        return readCodexInstallRevision(path.join(codexHome, '.tmp', 'marketplaces', 'pcircle-memesh'), fs.readFileSync);
+    }
+    const dir = path.join(pluginHostConfigRoot('claude-code'), 'plugins', 'marketplaces', 'pcircle-memesh');
+    try {
+        const out = execFileSync('git', ['-C', dir, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        return /^[0-9a-f]{40}$/.test(out) ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readCodexInstallRevision(root, readFileSyncImpl) {
+    const parsed = parseJsonFile(path.join(root, '.codex-marketplace-install.json'), readFileSyncImpl);
+    if (!parsed.ok)
+        return null;
+    const rev = parsed.value.revision;
+    return typeof rev === 'string' && /^[0-9a-f]{40}$/.test(rev) ? rev : null;
+}
+function pluginCacheUnverifiable(host, missing) {
+    const hostLabel = host === 'codex' ? 'Codex' : 'Claude Code';
+    const command = PLUGIN_REFRESH_COMMANDS[host];
+    return createCheck('plugin-cache', `Plugin cache source record is current (${hostLabel})`, 'warn', `Could not tell whether the plugin cache matches the marketplace: ${missing}. The version alone cannot answer this — two builds can carry the same version.`, `Run \`${command}\` — it re-stages the cache from the marketplace and records the commit, after which this check can answer.`, { code: 'plugin-cache.unverifiable', params: { host: hostLabel, command } });
+}
+function readClaudePluginEntries(registryPath, readFileSyncImpl, existsSyncImpl) {
+    if (!existsSyncImpl(registryPath)) {
+        return { exists: false, readable: false, defined: false, malformed: false, entries: [] };
+    }
+    const parsed = parseJsonFile(registryPath, readFileSyncImpl);
+    if (!parsed.ok)
+        return { exists: true, readable: false, defined: false, malformed: false, entries: [] };
+    const raw = parsed.value?.plugins?.['memesh@pcircle-memesh'];
+    const entries = Array.isArray(raw)
+        ? raw.filter((entry) => !!entry && typeof entry === 'object')
+        : [];
+    return {
+        exists: true,
+        readable: true,
+        defined: raw !== undefined,
+        malformed: raw !== undefined && (!Array.isArray(raw) || entries.length !== raw.length),
+        entries,
+    };
+}
+function defaultPluginCacheDiscovery(readFileSyncImpl, existsSyncImpl) {
+    const discovered = [];
+    const claudeConfigRoot = pluginHostConfigRoot('claude-code');
+    const claudeRegistry = path.join(claudeConfigRoot, 'plugins', 'installed_plugins.json');
+    const claudeCacheRoot = path.join(claudeConfigRoot, 'plugins', 'cache', 'pcircle-memesh', 'memesh');
+    const registry = readClaudePluginEntries(claudeRegistry, readFileSyncImpl, existsSyncImpl);
+    const entries = registry.entries;
+    if (registry.malformed) {
+        discovered.push({
+            host: 'claude-code',
+            packageRoot: claudeCacheRoot,
+            installedPluginsPath: claudeRegistry,
+            unverifiableReason: 'installed_plugins.json has a malformed memesh entry',
+        });
+    }
+    else if (entries.length > 0) {
+        const cachesByRoot = new Map();
+        for (const entry of entries) {
+            const recordedInstallPath = typeof entry.installPath === 'string' && entry.installPath.length > 0
+                ? entry.installPath
+                : null;
+            const installPath = recordedInstallPath ?? claudeCacheRoot;
+            const cache = {
+                host: 'claude-code', packageRoot: installPath, installedPluginsPath: claudeRegistry,
+                ...(!recordedInstallPath ? { unverifiableReason: 'an installed_plugins.json entry has no usable installPath' }
+                    : !existsSyncImpl(installPath) ? { unverifiableReason: `the recorded plugin cache does not exist at ${installPath}` } : {}),
+            };
+            const rootKey = path.resolve(installPath);
+            const existing = cachesByRoot.get(rootKey);
+            if (!existing)
+                cachesByRoot.set(rootKey, cache);
+            else if (!existing.unverifiableReason && cache.unverifiableReason) {
+                existing.unverifiableReason = cache.unverifiableReason;
+            }
+        }
+        discovered.push(...cachesByRoot.values());
+    }
+    else if (registry.defined) {
+        const cachedRoots = versionedPluginCacheRoots(claudeCacheRoot);
+        if (cachedRoots.length > 0) {
+            discovered.push({
+                host: 'claude-code',
+                packageRoot: cachedRoots[cachedRoots.length - 1],
+                installedPluginsPath: claudeRegistry,
+                unverifiableReason: 'installed_plugins.json records no active memesh install while a versioned plugin cache still exists',
+            });
+        }
+    }
+    else if (!registry.readable) {
+        const cachedRoots = versionedPluginCacheRoots(claudeCacheRoot);
+        const cachedRoot = cachedRoots[cachedRoots.length - 1];
+        if (cachedRoot) {
+            discovered.push({
+                host: 'claude-code', packageRoot: cachedRoot, installedPluginsPath: claudeRegistry,
+                unverifiableReason: registry.exists
+                    ? 'installed_plugins.json could not be read or parsed'
+                    : 'installed_plugins.json does not exist while a versioned plugin cache still exists',
+            });
+        }
+    }
+    const codexHome = pluginHostConfigRoot('codex');
+    const codexCacheRoot = path.join(codexHome, 'plugins', 'cache', 'pcircle-memesh', 'memesh');
+    const codexRoots = versionedPluginCacheRoots(codexCacheRoot);
+    if (codexRoots.length === 1) {
+        discovered.push({ host: 'codex', packageRoot: codexRoots[0] });
+    }
+    else if (codexRoots.length > 1) {
+        discovered.push({
+            host: 'codex',
+            packageRoot: codexRoots[codexRoots.length - 1],
+            unverifiableReason: `several versioned Codex plugin cache directories exist under ${codexCacheRoot}`,
+        });
+    }
+    return discovered;
+}
+function inspectPluginCacheCurrency(installChannel, pluginHost, packageRoot, installedPluginsPath, readFileSyncImpl, existsSyncImpl, marketplaceHeadShaImpl) {
+    if (installChannel !== 'plugin-marketplace')
+        return null;
+    const host = pluginHost === 'codex' ? 'codex' : 'claude-code';
+    const hostLabel = host === 'codex' ? 'Codex' : 'Claude Code';
+    const command = PLUGIN_REFRESH_COMMANDS[host];
+    let installedSha;
+    let installedMissing;
+    if (host === 'codex') {
+        installedSha = readCodexInstallRevision(packageRoot, readFileSyncImpl);
+        installedMissing = 'the plugin cache carries no readable .codex-marketplace-install.json revision';
+    }
+    else {
+        const registryPath = installedPluginsPath ?? path.join(pluginHostConfigRoot('claude-code'), 'plugins', 'installed_plugins.json');
+        const registry = readClaudePluginEntries(registryPath, readFileSyncImpl, existsSyncImpl);
+        const entries = registry.entries;
+        const here = path.resolve(packageRoot);
+        const matching = entries.filter(e => typeof e?.installPath === 'string' && path.resolve(e.installPath) === here);
+        const soleEntry = entries.length === 1 ? entries[0] : undefined;
+        const soleEntryHasPath = typeof soleEntry?.installPath === 'string' && soleEntry.installPath.length > 0;
+        const entry = matching.length === 1 ? matching[0] : undefined;
+        installedSha = !registry.malformed
+            && typeof entry?.gitCommitSha === 'string'
+            && /^[0-9a-f]{40}$/.test(entry.gitCommitSha)
+            ? entry.gitCommitSha
+            : null;
+        if (!registry.exists) {
+            installedMissing = `installed_plugins.json does not exist at ${registryPath}`;
+        }
+        else if (!registry.readable) {
+            installedMissing = 'installed_plugins.json could not be read or parsed';
+        }
+        else if (registry.malformed) {
+            installedMissing = 'installed_plugins.json has a malformed memesh entry';
+        }
+        else if (!registry.defined) {
+            installedMissing = 'installed_plugins.json has no memesh@pcircle-memesh entry';
+        }
+        else if (entries.length === 0) {
+            installedMissing = 'installed_plugins.json records no active memesh install for this cache';
+        }
+        else if (matching.length > 1) {
+            installedMissing = `installed_plugins.json lists ${matching.length} memesh entries for this install (${packageRoot})`;
+        }
+        else if (matching.length === 0 && soleEntryHasPath) {
+            installedMissing = `the only memesh entry in installed_plugins.json names another install, not this one (${packageRoot})`;
+        }
+        else if (matching.length === 0 && soleEntry) {
+            installedMissing = 'the only memesh entry in installed_plugins.json has no usable installPath to identify this cache';
+        }
+        else if (entries.length > 1 && matching.length === 0) {
+            installedMissing = `installed_plugins.json lists ${entries.length} memesh entries and none of them is this install (${packageRoot})`;
+        }
+        else {
+            installedMissing = 'installed_plugins.json does not record the commit this plugin was installed from';
+        }
+    }
+    const marketplaceSha = marketplaceHeadShaImpl(host);
+    if (!installedSha || !marketplaceSha) {
+        const missing = !installedSha ? installedMissing : `the ${hostLabel} marketplace snapshot has no readable commit`;
+        return pluginCacheUnverifiable(host, missing);
+    }
+    if (installedSha === marketplaceSha) {
+        return createCheck('plugin-cache', `Plugin cache source record is current (${hostLabel})`, 'pass', `The plugin cache records marketplace commit ${marketplaceSha.slice(0, 8)}, which matches the current marketplace snapshot.`);
+    }
+    return createCheck('plugin-cache', `Plugin cache source record is current (${hostLabel})`, 'warn', `The plugin cache records commit ${installedSha.slice(0, 8)}, but the marketplace has moved to ${marketplaceSha.slice(0, 8)} under the same version — ${hostLabel} does not normally refresh a cache whose version did not change, so refresh the cache before relying on the newer marketplace code.`, `Run \`${command}\` to refresh the cache in place, then restart ${hostLabel}.`, { code: 'plugin-cache.stale', params: { installed: installedSha.slice(0, 8), marketplace: marketplaceSha.slice(0, 8), host: hostLabel, command } });
+}
+function annotateNpmGlobalPluginCacheVersion(check, discoveredPackageRoot, hostLabel, runningVersion) {
+    const cacheRoot = path.dirname(discoveredPackageRoot);
+    const discoveredVersion = path.basename(discoveredPackageRoot);
+    let amended = check;
+    if (discoveredVersion !== runningVersion && classifyBump(runningVersion, discoveredVersion)) {
+        const skewNote = `This npm-global install is on ${runningVersion}; the ${hostLabel} plugin cache is on ${discoveredVersion}. `
+            + 'The plugin marketplace\'s own auto-updater only ever refreshes its plugin copy — it cannot and will not update this separate npm-global install.';
+        const skewFix = `Run \`memesh update\` to bring this npm-global install to ${discoveredVersion} (or newer) — it does not update itself automatically.`;
+        amended = {
+            ...amended,
+            status: amended.status === 'pass' ? 'warn' : amended.status,
+            summary: `${amended.summary} ${skewNote}`,
+            fix: amended.fix ? `${amended.fix} Also: ${skewFix}` : skewFix,
+            code: undefined,
+            params: undefined,
+        };
+    }
+    const cachedVersions = versionedPluginCacheRoots(cacheRoot);
+    if (cachedVersions.length > 2) {
+        amended = {
+            ...amended,
+            summary: `${amended.summary} ${cachedVersions.length} versioned copies of the ${hostLabel} plugin are cached under ${cacheRoot}; old ones are never removed automatically. `
+                + `Delete ones you no longer need once no ${hostLabel} process is using them, e.g. \`rm -rf "${cachedVersions[0]}"\`.`,
+        };
+    }
+    return amended;
+}
+function inspectClaudeChannelRegistration(existsSyncImpl, readFileSyncImpl) {
+    const configPath = path.join(homeDir(), '.claude.json');
+    let parsed = null;
+    if (existsSyncImpl(configPath)) {
+        try {
+            const value = JSON.parse(readFileSyncImpl(configPath, 'utf8'));
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                throw new Error('not an object');
+            parsed = value;
+        }
+        catch {
+            return createCheck('claude-channel', 'Claude Channel registration', 'warn', 'The canonical Claude user config could not be read as JSON, so the memesh-channel registration is malformed or unverifiable.', 'Repair the owner-controlled Claude config with `claude mcp remove memesh-channel` and re-run `memesh agent setup claude` to obtain a fresh registration command.');
+        }
+    }
+    const servers = parsed?.mcpServers;
+    const server = servers && typeof servers === 'object' && !Array.isArray(servers)
+        ? servers['memesh-channel']
+        : undefined;
+    if (server === undefined) {
+        return createCheck('claude-channel', 'Claude Channel registration', 'warn', 'No user-scoped memesh-channel registration was found. Durable MCP/inbox messaging can still work, but live Claude Channel notification is inactive. The upstream research-preview channel remains opt-in.', 'If you want the opt-in channel, run `memesh agent setup claude` and then register the printed user-scoped MCP command.');
+    }
+    const record = server && typeof server === 'object' && !Array.isArray(server)
+        ? server
+        : null;
+    const command = record?.command;
+    const rawArgs = record?.args;
+    const args = Array.isArray(rawArgs) ? rawArgs : null;
+    const configIndex = args?.indexOf('--config') ?? -1;
+    const target = args && configIndex >= 0 && typeof args[configIndex + 1] === 'string'
+        ? args[configIndex + 1]
+        : null;
+    let targetConfigValid = false;
+    if (target) {
+        try {
+            const config = readHostConfigFile(target);
+            const required = ['router_socket', 'token_file', 'project', 'principal_id'];
+            targetConfigValid = config.server_name === 'memesh-channel'
+                && required.every((key) => {
+                    const value = config[key];
+                    return typeof value === 'string'
+                        && value.length > 0
+                        && Buffer.byteLength(value) <= 4096;
+                });
+        }
+        catch {
+            targetConfigValid = false;
+        }
+    }
+    const coherent = command === 'memesh-host-claude'
+        && args !== null
+        && args.length === 2
+        && configIndex === 0
+        && target !== null
+        && targetConfigValid;
+    if (!coherent) {
+        const reason = command !== 'memesh-host-claude' || args === null || configIndex !== 0 || target === null
+            ? 'the command or --config declaration is malformed'
+            : 'the declared owner config target is missing, insecure, malformed, or incomplete';
+        return createCheck('claude-channel', 'Claude Channel registration', 'warn', `The user-scoped memesh-channel registration is present but ${reason}. Live Claude Channel notification is not established.`, 'Remove and re-register the owner-controlled memesh-channel entry with `memesh agent setup claude`; keep its generated config file owner-private.');
+    }
+    return createInfo('claude-channel', 'Claude Channel registration', 'The user-scoped memesh-channel registration and owner-private config target are coherent (CONFIGURED). Development-channel admission and agent surfacing are not verified; durable MCP/inbox messaging remains a separate path.');
+}
 function inspectDashboardArtifact(packageRoot, existsSyncImpl) {
     const dashboardPath = path.join(packageRoot, 'dashboard', 'dist', 'index.html');
     if (!existsSyncImpl(dashboardPath)) {
@@ -711,7 +1069,13 @@ async function inspectUpdateStatus(packageVersion, getUpdateCheckImpl, installSu
             return createCheck('update-status', 'Update status', 'pass', `Running pre-release version (${packageVersion}), npm latest is ${update.latestVersion}`);
         }
     }
-    return createCheck('update-status', 'Update status', update.freshness === 'stale' ? 'warn' : 'pass', `Version ${packageVersion} is current${update.freshness === 'stale' ? ', but cached update data is stale.' : '.'}`, update.freshness === 'stale'
+    const checkedHoursAgo = update.lastSuccessfulCheckAt === null
+        ? null
+        : (Date.now() - Date.parse(update.lastSuccessfulCheckAt)) / 3600_000;
+    const checkedAgo = formatHoursAgo(checkedHoursAgo);
+    return createCheck('update-status', 'Update status', update.freshness === 'stale' ? 'warn' : 'pass', update.freshness === 'stale'
+        ? `As of the last check (${checkedAgo}), ${packageVersion} was the latest version — that check is more than 24h old, so a newer release may exist since. Doctor never makes a live registry call itself.`
+        : `As of the last check (${checkedAgo}), ${packageVersion} was the latest version.`, update.freshness === 'stale'
         ? 'Run `memesh status` while online to refresh cached update metadata.'
         : undefined, update.freshness === 'stale'
         ? { code: 'update-status.stale', params: { version: packageVersion } }
@@ -742,7 +1106,7 @@ function verifySkillsManifest(packageRoot, existsSyncImpl, readFileSyncImpl, ins
     catch (err) {
         return createCheck('skills-manifest', 'Skills + hooks integrity', 'fail', `skills-manifest.json is unreadable (${err instanceof Error ? err.message : 'parse error'}).`, `Reinstall the package: ${reinstall} If the problem persists open an issue.`, { code: 'skills-manifest.unreadable', params: { detail: err instanceof Error ? err.message : 'parse error' } });
     }
-    const entries = manifest.entries ?? [];
+    const entries = Array.isArray(manifest.entries) ? manifest.entries : [];
     if (entries.length === 0) {
         return createCheck('skills-manifest', 'Skills + hooks integrity', 'fail', 'skills-manifest.json contains zero entries.', `Reinstall the package: ${reinstall}`, { code: 'skills-manifest.empty' });
     }
@@ -806,7 +1170,7 @@ function probeInstalledMessageCapability(packageRoot) {
         const tool = (await client.listTools()).tools.find((candidate) => candidate.name === 'message');
         assert.ok(tool, 'installed MCP did not advertise message');
         const actions = tool.inputSchema?.properties?.action?.enum;
-        assert.deepEqual(actions, ['send', 'poll', 'fetch', 'intake', 'ack', 'disposition', 'activation', 'receipts']);
+        assert.deepEqual(actions, ['send', 'poll', 'discover', 'fetch', 'intake', 'ack', 'disposition', 'activation', 'receipts']);
       } finally { await client.close(); }
     `], {
             cwd: packageRoot,
@@ -825,11 +1189,11 @@ function probeInstalledMessageCapability(packageRoot) {
 }
 function inspectMessageCapability(packageRoot, enabled, probe) {
     if (!enabled) {
-        return createInfo('message-capability', 'Message adapter imports', 'Not verified (opt-in). Set MEMESH_DOCTOR_PROBE_MESSAGE_CAPABILITY=1 to start this installed MCP and verify its eight-action message schema plus bundled host-adapter imports. This does not check a live router socket or host registration.');
+        return createInfo('message-capability', 'Message adapter imports', 'Not verified (opt-in). Set MEMESH_DOCTOR_PROBE_MESSAGE_CAPABILITY=1 to start this installed MCP and verify its nine-action message schema plus bundled host-adapter imports. This does not check a live router socket or host registration.');
     }
     const result = probe(packageRoot);
     if (result.ok)
-        return createCheck('message-capability', 'Message adapter imports', 'pass', 'This installed MCP advertised the eight-action message schema and all bundled host adapters imported successfully. No live router socket, host registration, or host acceptance was verified.');
+        return createCheck('message-capability', 'Message adapter imports', 'pass', 'This installed MCP advertised the nine-action message schema and all bundled host adapters imported successfully. No live router socket, host registration, or host acceptance was verified.');
     return createCheck('message-capability', 'Message adapter imports', 'fail', `Installed message capability probe failed: ${result.message}.`, 'Reinstall or rebuild this package, then retry with MEMESH_DOCTOR_PROBE_MESSAGE_CAPABILITY=1.', { code: 'message-capability.probe-failed', params: { detail: result.message } });
 }
 async function defaultMessageRouterStatusProbe() {
@@ -909,6 +1273,33 @@ async function inspectEmbeddingProbe(capabilities, probeCapabilities, embedTextI
         clearTimeout(timer);
     }
 }
+const LLM_TELEMETRY_HEALTH_WINDOW_DAYS = 7;
+const LLM_TELEMETRY_HEALTH_MIN_CALLS = 3;
+function inspectLlmTelemetryHealth(db, windowDays = LLM_TELEMETRY_HEALTH_WINDOW_DAYS, minCalls = LLM_TELEMETRY_HEALTH_MIN_CALLS) {
+    let summaries;
+    try {
+        summaries = summariseTelemetry(windowDays, db);
+    }
+    catch {
+        return undefined;
+    }
+    if (summaries.length === 0)
+        return undefined;
+    const broken = summaries
+        .filter((s) => s.total_calls >= minCalls && s.successes === 0)
+        .sort((a, b) => b.total_calls - a.total_calls);
+    if (broken.length > 0) {
+        const detail = broken.map((s) => `${s.flow} (${s.total_calls} call${s.total_calls === 1 ? '' : 's'}, 0 succeeded)`).join(', ');
+        return createCheck('llm_telemetry_health', 'AI feature health', 'warn', `${broken.length} AI-backed feature${broken.length === 1 ? '' : 's'} failed every call in the last `
+            + `${windowDays} days: ${detail}. Those features are silently doing nothing.`, 'Run `memesh telemetry` for the full per-flow detail, then check the model/provider configured for '
+            + 'the failing flow. `memesh doctor --probe` confirms whether it answers a live call.', { code: 'llm-telemetry.silent-failure', params: { count: broken.length, detail, windowDays } });
+    }
+    const totalCalls = summaries.reduce((n, s) => n + s.total_calls, 0);
+    const totalSuccesses = summaries.reduce((n, s) => n + s.successes, 0);
+    const rate = totalCalls > 0 ? Math.round((totalSuccesses / totalCalls) * 100) : 100;
+    return createInfo('llm_telemetry_health', 'AI feature health', `${summaries.length} AI-backed flow${summaries.length === 1 ? '' : 's'} made ${totalCalls} call(s) in the `
+        + `last ${windowDays} days; ${rate}% succeeded.`);
+}
 async function inspectLlmProbe(capabilities, probeCapabilities, probeProviderImpl) {
     const llm = capabilities.llm;
     if (!llm) {
@@ -938,7 +1329,7 @@ function summarizeOverallStatus(checks) {
     return 'PASS';
 }
 export async function runDoctor(options) {
-    const { packageRoot, packageVersion, probeHttp = false, probeCapabilities = false, embedTextImpl = embedText, probeProviderImpl = probeProvider, httpBaseUrl = 'http://127.0.0.1:3737', platform = process.platform, openDatabaseImpl = openDatabase, closeDatabaseImpl = closeDatabase, isDatabaseOpenImpl = isDatabaseOpen, detectCapabilitiesImpl = detectCapabilities, getConfigPathImpl = getConfigPath, getUpdateCheckImpl = getUpdateCheck, getCurrentInstallChannelImpl = getCurrentInstallChannel, installedPluginsPathImpl, getInstallChannelSupportImpl = getInstallChannelSupport, existsSyncImpl = fs.existsSync, readFileSyncImpl = fs.readFileSync, statSyncImpl = fs.statSync, fetchImpl = fetch, agentMessageStoragePolicy, nativeBindingProbeImpl, resolveShellMemeshImpl = defaultResolveShellMemesh, probeMessageCapability = process.env.MEMESH_DOCTOR_PROBE_MESSAGE_CAPABILITY === '1', messageCapabilityProbeImpl = probeInstalledMessageCapability, probeMessageRouterStatus = process.env.MEMESH_DOCTOR_PROBE_MESSAGE_ROUTER === '1', messageRouterStatusProbeImpl = defaultMessageRouterStatusProbe, } = options;
+    const { packageRoot, packageVersion, probeHttp = false, probeCapabilities = false, embedTextImpl = embedText, probeProviderImpl = probeProvider, httpBaseUrl = 'http://127.0.0.1:3737', platform = process.platform, envImpl = process.env, openDatabaseImpl = openDatabase, closeDatabaseImpl = closeDatabase, isDatabaseOpenImpl = isDatabaseOpen, detectCapabilitiesImpl = detectCapabilities, getConfigPathImpl = getConfigPath, getUpdateCheckImpl = getUpdateCheck, getCurrentInstallChannelImpl = getCurrentInstallChannel, installedPluginsPathImpl, marketplaceHeadShaImpl = defaultMarketplaceHeadSha, pluginCacheDiscoveryImpl, getInstallChannelSupportImpl = getInstallChannelSupport, existsSyncImpl = fs.existsSync, readFileSyncImpl = fs.readFileSync, statSyncImpl = fs.statSync, fetchImpl = fetch, agentMessageStoragePolicy, nativeBindingProbeImpl, resolveShellMemeshImpl = defaultResolveShellMemesh, probeMessageCapability = process.env.MEMESH_DOCTOR_PROBE_MESSAGE_CAPABILITY === '1', messageCapabilityProbeImpl = probeInstalledMessageCapability, probeMessageRouterStatus = process.env.MEMESH_DOCTOR_PROBE_MESSAGE_ROUTER === '1', messageRouterStatusProbeImpl = defaultMessageRouterStatusProbe, } = options;
     const wasDbOpenBeforeUs = isDatabaseOpenImpl();
     const safeCloseDatabaseImpl = wasDbOpenBeforeUs
         ? () => undefined
@@ -993,7 +1384,14 @@ export async function runDoctor(options) {
                     ? 'The vector index could not be read, so how much of your memory semantic recall can see is unknown'
                     : `${missingVectors} memor${missingVectors === 1 ? 'y has' : 'ies have'} no search vector, `
                         + 'so semantic recall cannot find them (keyword search still works)';
-            dbChecks.push(createCheck('vector_index', 'Vector Index', 'warn', owed, `Run 'memesh reindex' to fix. This will restore full search functionality.`, { code: 'vector-index.stale', params: { missing: missingVectors ?? -1 } }));
+            const noEmbedderConfigured = detectCapabilitiesImpl().embeddings === 'tfidf';
+            const vectorIndexFix = noEmbedderConfigured
+                ? `No embedder is configured, so reindex has nothing to embed with — run 'memesh config set embedder.provider ollama' (or 'openai') first, then 'memesh reindex'.`
+                : `Run 'memesh reindex' to fix. This will restore full search functionality.`;
+            dbChecks.push(createCheck('vector_index', 'Vector Index', 'warn', owed, vectorIndexFix, {
+                code: noEmbedderConfigured ? 'vector-index.stale-no-embedder' : 'vector-index.stale',
+                params: { missing: missingVectors ?? -1 },
+            }));
         }
         const generation = readVectorGeneration();
         if (generation.state !== 'none') {
@@ -1074,6 +1472,9 @@ export async function runDoctor(options) {
                 dbChecks.push(createInfo('citation_compliance', 'Memory citation rate', `${cited} of ${citationTotal} session(s) with injected memories cited at least one (${rate}%).`));
             }
         }
+        const llmTelemetryHealth = inspectLlmTelemetryHealth(db);
+        if (llmTelemetryHealth)
+            dbChecks.push(llmTelemetryHealth);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : 'unknown database error';
@@ -1141,17 +1542,53 @@ export async function runDoctor(options) {
         }
     }
     checks.push(inspectConfigFile(existsSyncImpl, readFileSyncImpl, getConfigPathImpl, detectCapabilitiesImpl().llm));
-    checks.push(inspectMcpConfig(packageRoot, existsSyncImpl, readFileSyncImpl));
+    checks.push(inspectMcpConfig(packageRoot, install, existsSyncImpl, readFileSyncImpl, envImpl));
     checks.push(...inspectHooksConfig(packageRoot, platform, existsSyncImpl, readFileSyncImpl, statSyncImpl));
-    const wiring = inspectHookWiring(existsSyncImpl, readFileSyncImpl, memeshDir(), install, installedPluginsPathImpl, detectPluginHost(packageRoot));
+    const pluginHost = detectPluginHost(packageRoot);
+    let codexPluginCacheDetected = pluginHost === 'codex';
+    let claudePluginCacheDetected = pluginHost === 'claude-code';
+    const wiring = inspectHookWiring(existsSyncImpl, readFileSyncImpl, memeshDir(), install, installedPluginsPathImpl, pluginHost);
+    const pluginCache = inspectPluginCacheCurrency(install, pluginHost, packageRoot, installedPluginsPathImpl, readFileSyncImpl, existsSyncImpl, marketplaceHeadShaImpl);
+    if (pluginCache)
+        checks.push(pluginCache);
+    if (install === 'npm-global') {
+        const discoveredCounts = new Map();
+        const discoveredPluginCaches = pluginCacheDiscoveryImpl
+            ? pluginCacheDiscoveryImpl()
+            : defaultPluginCacheDiscovery(readFileSyncImpl, existsSyncImpl);
+        for (const discovered of discoveredPluginCaches) {
+            if (discovered.host === 'codex')
+                codexPluginCacheDetected = true;
+            if (discovered.host === 'claude-code')
+                claudePluginCacheDetected = true;
+            let check = discovered.unverifiableReason
+                ? pluginCacheUnverifiable(discovered.host, discovered.unverifiableReason)
+                : inspectPluginCacheCurrency('plugin-marketplace', discovered.host, discovered.packageRoot, discovered.installedPluginsPath, readFileSyncImpl, existsSyncImpl, marketplaceHeadShaImpl);
+            if (check && !discovered.unverifiableReason) {
+                check = annotateNpmGlobalPluginCacheVersion(check, discovered.packageRoot, discovered.host === 'codex' ? 'Codex' : 'Claude Code', packageVersion);
+            }
+            if (check) {
+                const hostName = discovered.host;
+                const index = (discoveredCounts.get(discovered.host) ?? 0) + 1;
+                discoveredCounts.set(discovered.host, index);
+                checks.push({ ...check, id: `plugin-cache-${hostName}${index === 1 ? '' : `-${index}`}` });
+            }
+        }
+    }
     checks.push(wiring);
+    if (claudePluginCacheDetected) {
+        checks.push(inspectClaudeChannelRegistration(existsSyncImpl, readFileSyncImpl));
+    }
+    const codexSessionSetup = inspectCodexSessionSetup(codexPluginCacheDetected, existsSyncImpl);
+    if (codexSessionSetup)
+        checks.push(codexSessionSetup);
     const captureWired = wiring.status === 'pass'
         && (wiring.params === undefined || wiring.params.captureWired === 1);
     checks.push(inspectHookActivity(openDatabaseImpl, safeCloseDatabaseImpl, existsSyncImpl, statSyncImpl, captureWired));
     checks.push(inspectDashboardArtifact(packageRoot, existsSyncImpl));
     checks.push(inspectNodeRuntime(packageRoot, existsSyncImpl, readFileSyncImpl));
     checks.push(inspectNativeBinding(packageRoot, existsSyncImpl, nativeBindingProbeImpl));
-    checks.push(inspectShellCli(install, packageRoot, resolveShellMemeshImpl));
+    checks.push(inspectShellCli(install, packageRoot, packageVersion, resolveShellMemeshImpl, existsSyncImpl, readFileSyncImpl));
     checks.push(verifySkillsManifest(packageRoot, existsSyncImpl, readFileSyncImpl, installSupport));
     checks.push(inspectMessageCapability(packageRoot, probeMessageCapability, messageCapabilityProbeImpl));
     checks.push(await inspectMessageRouterStatus(probeMessageRouterStatus, messageRouterStatusProbeImpl));