@empirical-gauzza/cli 1.0.30 → 1.0.32

package/lib/deviceConfig.js

@@ -41,6 +41,31 @@ function writeIntegrationMode(integrationMode) {
   writeDeviceConfig(config);
 }
 
+// Hosts (codex / copilot / claude) that Empirical has actually been installed for on this
+// machine, recorded by `empirical install` and `empirical plugin install`. `doctor` reads this
+// so a host that merely exists on the machine (a ~/.claude folder left by another tool, or a CLI
+// the user deliberately skipped in the installer) is reported as skipped, not as broken.
+// Returns null when nothing was ever recorded (installs that predate this field), so callers
+// can tell "unknown" apart from "none".
+const KNOWN_HOST_IDS = ['codex', 'copilot', 'claude'];
+
+function readInstalledHosts() {
+  const config = readDeviceConfig();
+  if (!Array.isArray(config.installedHosts)) return null;
+  return config.installedHosts.filter((id) => KNOWN_HOST_IDS.includes(id));
+}
+
+function addInstalledHosts(hostIds) {
+  const config = readDeviceConfig();
+  const existing = Array.isArray(config.installedHosts) ? config.installedHosts : [];
+  const merged = new Set(existing.filter((id) => KNOWN_HOST_IDS.includes(id)));
+  for (const id of hostIds || []) {
+    if (KNOWN_HOST_IDS.includes(id)) merged.add(id);
+  }
+  config.installedHosts = KNOWN_HOST_IDS.filter((id) => merged.has(id));
+  writeDeviceConfig(config);
+}
+
 function readPolicyCache() {
   const config = readDeviceConfig();
   return config.empiricalPolicy || null;
@@ -101,6 +126,8 @@ module.exports = {
   writeDeviceConfig,
   readIntegrationMode,
   writeIntegrationMode,
+  readInstalledHosts,
+  addInstalledHosts,
   readPolicyCache,
   writePolicyCache,
   ensureDeviceId,

package/lib/doctor.js

@@ -13,6 +13,39 @@ const { detectInstallTargets } = require('./installers/detect');
 const { readInstalledVersions } = require('./pluginUpdateCheck');
 const { CORE_PLUGIN_NAME, OPTIONAL_PLUGIN_NAMES } = require('./installers/nativePlugin');
 const { getEmpiricalHooksDir, getCodexHooksScriptsDir, getCodexHomeDir } = require('./installers/hooks');
+const { readIntegrationMode, readInstalledHosts } = require('./deviceConfig');
+
+// ─── Which detected hosts doctor should grade ──────────────────────────────────
+// Doctor output is read by agents, and a FAIL line with a "Run: ..." remedy is, to an agent, an
+// instruction. So a host the user never set Empirical up for must not be graded as broken:
+//   - If the installer recorded which hosts it installed for, grade exactly those.
+//   - Otherwise (installs that predate the record), grade only hosts whose binary is on PATH; a
+//     bare dotfolder (e.g. ~/.claude left behind with no `claude` command) is nothing to check.
+// Skipped hosts still get one informational line so the user can see why they were left out.
+function partitionHostsToCheck(detectedTargets, installedHosts) {
+  const checked = [];
+  const skipped = [];
+  for (const target of detectedTargets) {
+    if (installedHosts !== null) {
+      if (installedHosts.includes(target.id)) {
+        checked.push(target);
+      } else {
+        const evidence = target.onPath
+          ? `${target.id} is on PATH`
+          : `only its ${target.configDir} folder exists; ${target.id} is not on PATH`;
+        skipped.push({ target, reason: `not set up for Empirical (${evidence}). To add it: empirical install.` });
+      }
+    } else if (target.onPath) {
+      checked.push(target);
+    } else {
+      skipped.push({
+        target,
+        reason: `only its ${target.configDir} folder exists; ${target.id} is not on PATH, so there is nothing to check. To set it up later: empirical install.`
+      });
+    }
+  }
+  return { checked, skipped };
+}
 
 // ─── Host MCP config registration ─────────────────────────────────────────────
 // Each host stores "is the Empirical MCP server registered" in a different shape and location.
@@ -377,11 +410,28 @@ async function runDoctor(args) {
     }
 
     // ─── MCP wiring diagnostics (C-007) ─────────────────────────────────────
-    const detectedTargets = detectInstallTargets();
-    if (detectedTargets.length === 0) {
+    const allDetected = detectInstallTargets();
+    let installedHosts = null;
+    let integrationMode = 1;
+    try {
+      installedHosts = readInstalledHosts();
+      integrationMode = readIntegrationMode();
+    } catch (_error) {
+      installedHosts = null;
+      integrationMode = 1;
+    }
+    const { checked: detectedTargets, skipped: skippedTargets } = partitionHostsToCheck(allDetected, installedHosts);
+
+    if (allDetected.length === 0) {
       addCheck('mcp_hosts_detected', 'warn', 'No supported host CLI detected (codex/claude/copilot). Nothing to check for MCP wiring.');
+    } else if (detectedTargets.length === 0) {
+      addCheck('mcp_hosts_detected', 'warn', `Detected: ${allDetected.map((t) => t.label).join(', ')}, but none is set up for Empirical. Run: empirical install.`);
     } else {
-      addCheck('mcp_hosts_detected', 'ok', `Detected: ${detectedTargets.map((t) => t.label).join(', ')}.`);
+      const modeLabel = integrationMode === 2 ? 'CLI-direct' : integrationMode === 3 ? 'MCP + CLI' : 'MCP';
+      addCheck('mcp_hosts_detected', 'ok', `Checking: ${detectedTargets.map((t) => t.label).join(', ')} (${modeLabel} mode).`);
+    }
+    for (const { target, reason } of skippedTargets) {
+      addCheck(`host_${target.id}`, 'skip', `${target.label}: ${reason}`);
     }
 
     for (const target of detectedTargets) {
@@ -393,7 +443,16 @@ async function runDoctor(args) {
       } catch (error) {
         result = { ok: false, message: `Could not inspect ${target.label} MCP config: ${error.message}` };
       }
-      addCheck(`mcp_config_${target.id}`, result.ok ? 'ok' : 'fail', `${target.label}: ${result.message}`);
+      if (integrationMode === 2) {
+        // CLI-direct mode: agents call the `empirical` CLI, so an unregistered MCP server is the
+        // expected state, not a defect. Report whatever is there without failing on absence.
+        const message = result.ok
+          ? `${result.message} (CLI-direct mode; MCP registration is optional.)`
+          : 'CLI-direct mode: MCP server not registered, and none is expected. Agents use the empirical CLI.';
+        addCheck(`mcp_config_${target.id}`, 'ok', `${target.label}: ${message}`);
+      } else {
+        addCheck(`mcp_config_${target.id}`, result.ok ? 'ok' : 'fail', `${target.label}: ${result.message}`);
+      }
     }
 
     const mcpReachability = await checkMcpReachability(token);
@@ -464,6 +523,7 @@ async function runDoctor(args) {
       const statusLabel = (status) => {
         if (status === 'ok') return colorize(ANSI.green, '[OK]  ');
         if (status === 'warn') return colorize(ANSI.yellow, '[WARN]');
+        if (status === 'skip') return colorize(ANSI.dim, '[SKIP]');
         return colorize(ANSI.red, '[FAIL]');
       };
       for (const check of checks) {

package/lib/installWizard.js

@@ -23,8 +23,9 @@ const { detectInstallTargets } = require('./installers/detect');
 const { installClaudeHooks, installCodexHooks, installCopilotHooks } = require('./installers/hooks');
 const { runCodex } = require('./installers/codex');
 const { installNativePlugin, OPTIONAL_PLUGIN_NAMES } = require('./installers/nativePlugin');
+const { writeCoreMemoryGuidance } = require('./installers/coreMemoryBlock');
 const { policyFromInstallerOptions, savePolicy: persistPolicy } = require('./policyCommands');
-const { writeIntegrationMode } = require('./deviceConfig');
+const { writeIntegrationMode, addInstalledHosts } = require('./deviceConfig');
 
 function pluginNamesForInstallerOptions(options = {}) {
   const names = ['empirical-memory'];
@@ -234,10 +235,13 @@ async function runInstallFlow() {
     log(uiHeader(`Step 2/2: Installing for ${target.label}...`));
     try {
       if (integrationMode === 2) {
-        // CLI-direct: skip MCP registration; the native plugin owns guidance.
+        // CLI-direct: skip MCP registration only. The skill, the hooks AND the global
+        // instructions block are all still required -- a real Copilot install that skipped the
+        // instructions file here left the agent ignoring Empirical for a whole session.
         const pluginNames = pluginNamesForInstallerOptions(promptOptions);
         installNativePlugin(target.id, pluginNames, integrationMode);
         log(`  - ${target.label} native plugins installed: ${pluginNames.join(', ')}.`);
+        writeCoreMemoryGuidance(target.id, pluginNames);
         if (target.id === 'claude') {
           try {
             installClaudeHooks(pluginNames);
@@ -260,6 +264,7 @@ async function runInstallFlow() {
           }
         }
         log(uiSuccess(`Done: ${target.label} (CLI-direct mode)`));
+        addInstalledHosts([target.id]);
       } else {
         // Mode 1 or 3: run MCP install normally
         const pluginNames = pluginNamesForInstallerOptions(promptOptions);
@@ -269,6 +274,7 @@ async function runInstallFlow() {
           integrationMode
         });
         log(uiSuccess(`Done: ${target.label}`));
+        addInstalledHosts([target.id]);
         if (target.id === 'codex') {
           codexInstalled = true;
           codexNeedsPostLogin = Boolean(installResult?.needsPostLogin);

package/lib/installers/claude.js

@@ -11,7 +11,7 @@ const {
 const { INSTALL_PROMPT_OPTIONS_DEFAULTS } = require('./promptBlocks');
 const { installClaudeHooks } = require('./hooks');
 const { installNativePlugin, CORE_PLUGIN_NAME } = require('./nativePlugin');
-const { buildCoreMemoryBlock, upsertCoreMemoryBlock } = require('./coreMemoryBlock');
+const { writeCoreMemoryGuidance } = require('./coreMemoryBlock');
 
 function runClaude(args, options = {}) {
   return runResolvedCommand('claude', args, options);
@@ -30,14 +30,7 @@ function installClaude(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEF
   // writes the same kind of identity-framed statement into the one file Claude reads every
   // session unconditionally, inside a clearly delimited block so any of the user's own content
   // in CLAUDE.md is left untouched.
-  try {
-    const claudeMdPath = path.join(os.homedir(), '.claude', 'CLAUDE.md');
-    const block = buildCoreMemoryBlock({ pluginNames: installOptions.pluginNames || [CORE_PLUGIN_NAME] });
-    upsertCoreMemoryBlock(claudeMdPath, block);
-    log(`  - Wrote Empirical core memory guidance to ${claudeMdPath}.`);
-  } catch (error) {
-    warn(`  - Could not write Empirical core memory guidance to CLAUDE.md: ${error.message}`);
-  }
+  writeCoreMemoryGuidance('claude', installOptions.pluginNames || [CORE_PLUGIN_NAME]);
 
   // installNativePlugin throws if the plugin install/update genuinely fails (see
   // assertPluginInstallSucceeded in nativePlugin.js) - hooks are only installed AFTER this

package/lib/installers/codex.js

@@ -11,7 +11,7 @@ const {
 const { INSTALL_PROMPT_OPTIONS_DEFAULTS } = require('./promptBlocks');
 const { installCodexHooks } = require('./hooks');
 const { installNativePlugin, CORE_PLUGIN_NAME } = require('./nativePlugin');
-const { buildCoreMemoryBlock, upsertCoreMemoryBlock } = require('./coreMemoryBlock');
+const { writeCoreMemoryGuidance } = require('./coreMemoryBlock');
 
 function runCodex(args, options = {}) {
   return runResolvedCommand('codex', args, options);
@@ -26,14 +26,7 @@ function installCodex(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEFA
   // 2026-08-24: see claude.js's identical block for why this now writes AGENTS.md instead of
   // leaving it untouched -- hooks + an installable skill alone were not enough against a
   // competing identity-framed built-in memory feature in a real session.
-  try {
-    const agentsMdPath = path.join(os.homedir(), '.codex', 'AGENTS.md');
-    const block = buildCoreMemoryBlock({ pluginNames: installOptions.pluginNames || [CORE_PLUGIN_NAME] });
-    upsertCoreMemoryBlock(agentsMdPath, block);
-    log(`  - Wrote Empirical core memory guidance to ${agentsMdPath}.`);
-  } catch (error) {
-    warn(`  - Could not write Empirical core memory guidance to AGENTS.md: ${error.message}`);
-  }
+  writeCoreMemoryGuidance('codex', installOptions.pluginNames || [CORE_PLUGIN_NAME]);
 
   // installNativePlugin throws on genuine failure (see assertPluginInstallSucceeded in
   // nativePlugin.js) - hooks install only AFTER this succeeds, never before, so a failed/skipped

package/lib/installers/copilot.js

@@ -12,7 +12,7 @@ const {
 const { INSTALL_PROMPT_OPTIONS_DEFAULTS } = require('./promptBlocks');
 const { installCopilotHooks } = require('./hooks');
 const { installNativePlugin, CORE_PLUGIN_NAME } = require('./nativePlugin');
-const { buildCoreMemoryBlock, upsertCoreMemoryBlock } = require('./coreMemoryBlock');
+const { writeCoreMemoryGuidance } = require('./coreMemoryBlock');
 
 function installCopilot(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEFAULTS, installOptions = {}) {
   const home = os.homedir();
@@ -65,13 +65,7 @@ function installCopilot(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DE
   // 2026-08-24: see claude.js's identical block for why this now writes copilot-instructions.md
   // instead of leaving it untouched -- hooks + an installable skill alone were not enough
   // against a competing identity-framed built-in memory feature in a real session.
-  try {
-    const block = buildCoreMemoryBlock({ pluginNames: installOptions.pluginNames || [CORE_PLUGIN_NAME] });
-    upsertCoreMemoryBlock(instructionsPath, block);
-    log(`  - Wrote Empirical core memory guidance to ${instructionsPath}.`);
-  } catch (error) {
-    warn(`  - Could not write Empirical core memory guidance to copilot-instructions.md: ${error.message}`);
-  }
+  writeCoreMemoryGuidance('copilot', installOptions.pluginNames || [CORE_PLUGIN_NAME]);
 
   // installNativePlugin throws on genuine failure (see assertPluginInstallSucceeded in
   // nativePlugin.js) - hooks install only AFTER this succeeds, never before, so a failed/skipped

package/lib/installers/coreMemoryBlock.js

@@ -1,6 +1,8 @@
 'use strict';
 
 const { readUtf8IfExists, writeFile, ensureDir } = require('../fsUtils');
+const { log, warn } = require('../ui');
+const os = require('os');
 const path = require('path');
 const { CORE_PLUGIN_NAME, OPTIONAL_PLUGIN_NAMES } = require('./nativePlugin');
 
@@ -88,9 +90,48 @@ function upsertCoreMemoryBlock(filePath, block) {
   writeFile(filePath, next);
 }
 
+// The one instructions file each host reads unconditionally every session. Kept here, next to
+// the block it receives, so every install path (full installer in any mode, `plugin install`)
+// writes to the same place instead of each path re-deriving it.
+const INSTRUCTIONS_FILE_BY_HOST = {
+  claude: ['.claude', 'CLAUDE.md'],
+  codex: ['.codex', 'AGENTS.md'],
+  copilot: ['.copilot', 'copilot-instructions.md']
+};
+
+function instructionsFilePathForHost(hostId) {
+  const segments = INSTRUCTIONS_FILE_BY_HOST[hostId];
+  if (!segments) throw new Error(`No global instructions file is known for host "${hostId}".`);
+  return path.join(os.homedir(), ...segments);
+}
+
+/**
+ * Writes (or refreshes) the core memory block in the host's global instructions file. Every
+ * install path must call this, whatever integration mode the user picked: a real CLI-direct
+ * Copilot install (2026-09-17) installed the skill and hooks but skipped this file, and the
+ * agent ignored Empirical for the whole session exactly as the 2026-08-24 incident predicted.
+ * Never throws; a failure here is logged and must not fail the install that already succeeded.
+ * Returns the path written, or null on failure.
+ */
+function writeCoreMemoryGuidance(hostId, pluginNames = [CORE_PLUGIN_NAME]) {
+  let filePath = null;
+  try {
+    filePath = instructionsFilePathForHost(hostId);
+    const block = buildCoreMemoryBlock({ pluginNames: pluginNames && pluginNames.length ? pluginNames : [CORE_PLUGIN_NAME] });
+    upsertCoreMemoryBlock(filePath, block);
+    log(`  - Wrote Empirical core memory guidance to ${filePath}.`);
+    return filePath;
+  } catch (error) {
+    warn(`  - Could not write Empirical core memory guidance for ${hostId}${filePath ? ` (${filePath})` : ''}: ${error.message}`);
+    return null;
+  }
+}
+
 module.exports = {
   BEGIN_MARKER,
   END_MARKER,
   buildCoreMemoryBlock,
-  upsertCoreMemoryBlock
+  upsertCoreMemoryBlock,
+  instructionsFilePathForHost,
+  writeCoreMemoryGuidance
 };

package/lib/installers/detect.js

@@ -8,33 +8,49 @@ const { installCodex } = require('./codex');
 const { installCopilot } = require('./copilot');
 const { installClaude } = require('./claude');
 
+// A host counts as detected when its binary is on PATH OR its home dotfolder exists. The
+// dotfolder alone is a weak signal (another tool, an uninstalled CLI, or a desktop app can leave
+// one behind), so each target also carries `onPath` and `configDirExists` separately; doctor uses
+// them to say "found only a folder, nothing to check" instead of failing the host.
 function detectInstallTargets() {
   const home = os.homedir();
   const targets = [];
 
-  const codexDetected = commandExists('codex') || fs.existsSync(path.join(home, '.codex'));
-  if (codexDetected) {
+  const codexOnPath = commandExists('codex');
+  const codexDirExists = fs.existsSync(path.join(home, '.codex'));
+  if (codexOnPath || codexDirExists) {
     targets.push({
       id: 'codex',
       label: 'Codex CLI',
+      onPath: codexOnPath,
+      configDirExists: codexDirExists,
+      configDir: path.join(home, '.codex'),
       install: installCodex
     });
   }
 
-  const copilotDetected = commandExists('copilot') || fs.existsSync(path.join(home, '.copilot'));
-  if (copilotDetected) {
+  const copilotOnPath = commandExists('copilot');
+  const copilotDirExists = fs.existsSync(path.join(home, '.copilot'));
+  if (copilotOnPath || copilotDirExists) {
     targets.push({
       id: 'copilot',
       label: 'GitHub Copilot CLI',
+      onPath: copilotOnPath,
+      configDirExists: copilotDirExists,
+      configDir: path.join(home, '.copilot'),
       install: installCopilot
     });
   }
 
-  const claudeDetected = commandExists('claude') || fs.existsSync(path.join(home, '.claude'));
-  if (claudeDetected) {
+  const claudeOnPath = commandExists('claude');
+  const claudeDirExists = fs.existsSync(path.join(home, '.claude'));
+  if (claudeOnPath || claudeDirExists) {
     targets.push({
       id: 'claude',
       label: 'Claude CLI',
+      onPath: claudeOnPath,
+      configDirExists: claudeDirExists,
+      configDir: path.join(home, '.claude'),
       install: installClaude
     });
   }

package/lib/installers/hooks.js

@@ -85,7 +85,9 @@ function runMemoryQuery(args) {
     appendLog('resolved direct entry point: ' + entryPoint);
     return spawnSync(process.execPath, [entryPoint].concat(args), {
       encoding: 'utf8',
-      timeout: 10000,
+      // Must stay under the host manifest cap for this event (25s). Recall is chronically 2-7s
+      // and the old 10s here killed the query silently while the host still had 15s to spare.
+      timeout: 20000,
       shell: false
     });
   }
@@ -97,7 +99,7 @@ function runMemoryQuery(args) {
   appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
   return spawnSync('empirical', args, {
     encoding: 'utf8',
-    timeout: 10000,
+    timeout: 20000,
     shell: process.platform === 'win32'
   });
 }
@@ -310,7 +312,9 @@ function runMemoryQuery(args) {
     appendLog('resolved direct entry point: ' + entryPoint);
     return spawnSync(process.execPath, [entryPoint].concat(args), {
       encoding: 'utf8',
-      timeout: 10000,
+      // Must stay under the host manifest cap for this event (25s). Recall is chronically 2-7s
+      // and the old 10s here killed the query silently while the host still had 15s to spare.
+      timeout: 20000,
       shell: false
     });
   }
@@ -318,7 +322,7 @@ function runMemoryQuery(args) {
   appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
   return spawnSync('empirical', args, {
     encoding: 'utf8',
-    timeout: 10000,
+    timeout: 20000,
     shell: process.platform === 'win32'
   });
 }
@@ -552,7 +556,9 @@ function runMemoryQuery(args) {
     appendLog('resolved direct entry point: ' + entryPoint);
     return spawnSync(process.execPath, [entryPoint].concat(args), {
       encoding: 'utf8',
-      timeout: 10000,
+      // Must stay under the host manifest cap for this event (25s). Recall is chronically 2-7s
+      // and the old 10s here killed the query silently while the host still had 15s to spare.
+      timeout: 20000,
       shell: false
     });
   }
@@ -560,7 +566,7 @@ function runMemoryQuery(args) {
   appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
   return spawnSync('empirical', args, {
     encoding: 'utf8',
-    timeout: 10000,
+    timeout: 20000,
     shell: process.platform === 'win32'
   });
 }

package/lib/installers/nativePlugin.js

@@ -23,19 +23,119 @@ function runPluginCommand(command, args, options = {}) {
   return runResolvedCommand(command, args, { stdio: 'inherit', ...options });
 }
 
+// Install/update commands are run with their output captured (and echoed back so the user still
+// sees the host CLI's own progress) because the failure text is what tells a locked plugin folder
+// apart from a real install failure -- see installOneOrKeepExisting below.
+function runPluginInstallCommand(command, args) {
+  const result = runResolvedCommand(command, args, { stdio: 'pipe' });
+  if (result && result.stdout) process.stdout.write(result.stdout);
+  if (result && result.stderr) process.stderr.write(result.stderr);
+  return result;
+}
+
 function assertPluginInstallSucceeded(agentId, result) {
   if (result && result.status === 0) return;
   const detail = result ? summarizeProcessOutput(result) : 'no process result';
   throw new Error(`${agentId} plugin installation failed.${detail ? ` Details: ${detail}` : ''}`);
 }
 
+// ─── Locked plugin folder (Windows) ───────────────────────────────────────────
+// Reproduced 2026-09-17: on Windows, a host CLI replaces an installed plugin by renaming its
+// folder, and Windows refuses to rename a folder any process has open. One open handle -- a
+// running Copilot CLI session, or the Copilot extension in VS Code watching that folder -- is
+// enough, and the host reports it as "Access is denied. (os error 5)". Users read that as a
+// permissions problem and reach for admin rights, which does nothing. Upstream: copilot-cli
+// #4151 / #4095. So when an install fails that way:
+//   - if the plugin is already installed, keep it and carry on (the rest of the install -- the
+//     instructions block, the hooks -- must not be held hostage to a refresh), and say so;
+//   - if it is not installed, fail with the one instruction that fixes it, naming the programs
+//     we can see running, instead of the host CLI's bare "Access is denied".
+const LOCKED_FOLDER_PATTERN = /access is denied|os error 5\b|EBUSY|EPERM|being used by another process/i;
+
+// Process names (as Windows reports them) that are known to hold plugin folders open per host.
+const LOCK_HOLDER_PROCESS_NAMES = {
+  copilot: ['copilot', 'Code'],
+  claude: ['claude', 'Code'],
+  codex: ['codex', 'Code']
+};
+
+const LOCK_HOLDER_LABELS = {
+  copilot: 'GitHub Copilot CLI',
+  claude: 'Claude Code',
+  codex: 'Codex CLI',
+  Code: 'VS Code'
+};
+
+function looksLikeLockedPluginFolder(result) {
+  if (!result) return false;
+  const text = `${result.stdout || ''}\n${result.stderr || ''}\n${result.error ? result.error.message || result.error : ''}`;
+  return LOCKED_FOLDER_PATTERN.test(text);
+}
+
+function detectLockHolders(agentId) {
+  if (process.platform !== 'win32') return [];
+  const names = LOCK_HOLDER_PROCESS_NAMES[agentId] || [];
+  if (!names.length) return [];
+  try {
+    const { spawnSync } = require('child_process');
+    const script = `Get-Process -Name ${names.join(',')} -ErrorAction SilentlyContinue | Select-Object -ExpandProperty ProcessName -Unique`;
+    const probe = spawnSync('pwsh', ['-NoProfile', '-Command', script], { encoding: 'utf8', timeout: 5000 });
+    return String(probe.stdout || '').split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+  } catch (_error) {
+    return [];
+  }
+}
+
+function describeLockHolders(agentId, holders) {
+  const seen = holders.map((name) => LOCK_HOLDER_LABELS[name] || name);
+  const hostLabel = LOCK_HOLDER_LABELS[agentId] || agentId;
+  if (seen.length) {
+    return `Running now: ${seen.join(', ')}. Close ${seen.length === 1 ? 'it' : 'them'} (every window and terminal session)`;
+  }
+  return `Close every ${hostLabel} session and every VS Code window`;
+}
+
+function currentlyInstalledVersion(agentId, name) {
+  try {
+    // Lazy: pluginUpdateCheck requires this module, so a top-level require would be a cycle.
+    const { readInstalledVersions } = require('../pluginUpdateCheck');
+    const versions = readInstalledVersions(agentId, [name]);
+    return versions && versions[name] ? versions[name] : null;
+  } catch (_error) {
+    return null;
+  }
+}
+
+/**
+ * Runs one plugin install and interprets the result. Returns { name, refreshed, keptVersion? }.
+ * Throws only for a genuine failure, or for a locked folder when the plugin is not installed at
+ * all (there is nothing to keep, and the user must act).
+ */
+function installOneOrKeepExisting(agentId, name, runInstall) {
+  const result = runInstall();
+  if (result && result.status === 0) return { name, refreshed: true };
+  if (!looksLikeLockedPluginFolder(result)) assertPluginInstallSucceeded(agentId, result);
+
+  const holders = detectLockHolders(agentId);
+  const action = describeLockHolders(agentId, holders);
+  const keptVersion = currentlyInstalledVersion(agentId, name);
+  if (keptVersion) {
+    warn(`  - ${LOCK_HOLDER_LABELS[agentId] || agentId} could not replace the ${name} plugin folder because another program has it open (Windows reported "Access is denied"; this is not a permissions problem). Kept the installed ${name}@${keptVersion} and continued. ${action}, then run: empirical plugin install ${agentId} to update it.`);
+    return { name, refreshed: false, keptVersion, lockedBy: holders };
+  }
+
+  throw new Error(
+    `${agentId} plugin installation failed: ${LOCK_HOLDER_LABELS[agentId] || agentId} could not write the ${name} plugin folder because another program has it open `
+    + `(Windows reported "Access is denied"; running as administrator will not help). ${action}, then run: empirical install`
+  );
+}
+
 function updateOrInstall(agentId, command, updateArgs, installArgs) {
-  const updateResult = runPluginCommand(command, updateArgs);
-  if (updateResult && updateResult.status === 0) return updateResult;
+  const updateResult = runPluginInstallCommand(command, updateArgs);
+  if (updateResult && updateResult.status === 0) return { refreshed: true };
 
-  const installResult = runPluginCommand(command, installArgs);
-  assertPluginInstallSucceeded(agentId, installResult);
-  return installResult;
+  const name = String(installArgs[2] || '').split('@')[0];
+  return installOneOrKeepExisting(agentId, name, () => runPluginInstallCommand(command, installArgs));
 }
 
 function normalizePluginNames(pluginNames = [CORE_PLUGIN_NAME]) {
@@ -92,21 +192,23 @@ function installNativePlugin(agentId, pluginNames = [CORE_PLUGIN_NAME], integrat
     applySkillModeVariant(agentId, resolvedIntegrationMode);
   };
 
+  const outcomes = [];
+
   if (agentId === 'claude') {
     // Marketplace registration is intentionally best-effort: native Claude returns non-zero
     // when the same Git marketplace is already registered, but the install command is still
     // authoritative and idempotent.
     runPluginCommand('claude', ['plugin', 'marketplace', 'add', EMPIRICAL_PLUGIN_SOURCE], { stdio: 'pipe' });
     for (const name of names) {
-      updateOrInstall(
+      outcomes.push(updateOrInstall(
         agentId,
         'claude',
         ['plugin', 'update', `${name}@empirical-memory`, '--scope', 'user'],
         ['plugin', 'install', name, '--scope', 'user']
-      );
+      ));
     }
     applyVariantIfCore();
-    return;
+    return { outcomes };
   }
 
   if (agentId === 'codex') {
@@ -114,11 +216,10 @@ function installNativePlugin(agentId, pluginNames = [CORE_PLUGIN_NAME], integrat
     // Refresh the Git marketplace snapshot before reinstalling an existing plugin.
     runPluginCommand('codex', ['plugin', 'marketplace', 'upgrade', 'empirical-memory'], { stdio: 'pipe' });
     for (const name of names) {
-      const result = runPluginCommand('codex', ['plugin', 'add', `${name}@empirical-memory`]);
-      assertPluginInstallSucceeded(agentId, result);
+      outcomes.push(installOneOrKeepExisting(agentId, name, () => runPluginInstallCommand('codex', ['plugin', 'add', `${name}@empirical-memory`])));
     }
     applyVariantIfCore();
-    return;
+    return { outcomes };
   }
 
   if (agentId === 'copilot') {
@@ -127,11 +228,10 @@ function installNativePlugin(agentId, pluginNames = [CORE_PLUGIN_NAME], integrat
     runPluginCommand('copilot', ['plugin', 'marketplace', 'add', EMPIRICAL_PLUGIN_SOURCE], { stdio: 'pipe' });
     runPluginCommand('copilot', ['plugin', 'marketplace', 'update', 'empirical-memory'], { stdio: 'pipe' });
     for (const name of names) {
-      const result = runPluginCommand('copilot', ['plugin', 'install', `${name}@empirical-memory`]);
-      assertPluginInstallSucceeded(agentId, result);
+      outcomes.push(installOneOrKeepExisting(agentId, name, () => runPluginInstallCommand('copilot', ['plugin', 'install', `${name}@empirical-memory`])));
     }
     applyVariantIfCore();
-    return;
+    return { outcomes };
   }
 
   throw new Error(`Unsupported plugin target: ${agentId}`);
@@ -143,5 +243,6 @@ module.exports = {
   OPTIONAL_PLUGIN_NAMES,
   normalizePluginNames,
   installNativePlugin,
-  applySkillModeVariant
+  applySkillModeVariant,
+  looksLikeLockedPluginFolder
 };

package/lib/pluginCommands.js

@@ -7,6 +7,8 @@ const {
   OPTIONAL_PLUGIN_NAMES = ['empirical-work-history', 'empirical-scar-tissue', 'empirical-todo']
 } = require('./installers/nativePlugin');
 const { checkNativePluginUpdates } = require('./pluginUpdateCheck');
+const { addInstalledHosts } = require('./deviceConfig');
+const { writeCoreMemoryGuidance } = require('./installers/coreMemoryBlock');
 
 const SUPPORTED_TARGETS = ['codex', 'copilot', 'claude'];
 
@@ -68,6 +70,15 @@ async function runPluginCommand(args = []) {
     if (pluginNames.length === 1) installNativePlugin(target);
     else installNativePlugin(target, pluginNames);
     log(uiSuccess(`${target} plugins installed through its marketplace: ${pluginNames.join(', ')}.`));
+    // The skill alone does not make an agent use Empirical; the identity-framed block in the
+    // host's global instructions file does. Write it on this path too, not only in `install`.
+    writeCoreMemoryGuidance(target, pluginNames);
+    // Record the host so `empirical doctor` checks it, and only it, from now on.
+    try {
+      addInstalledHosts([target]);
+    } catch (_error) {
+      // Device-config bookkeeping must never fail a plugin install that already succeeded.
+    }
   }
   log('');
   log('Native plugin installation does not configure MCP or credentials.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@empirical-gauzza/cli",
-  "version": "1.0.30",
+  "version": "1.0.32",
   "description": "Persistent cross-tool memory for AI agents. Give Claude Code, Codex, Copilot, Cursor, and ChatGPT one shared memory: save project context once, recall it everywhere via CLI or MCP.",
   "keywords": [
     "memory",