claude-dev-env 8.88.1 → 8.88.3

package/bin/codex-trimmed-sol.mjs

@@ -1,5 +1,8 @@
-import { lstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { lstatSync, mkdirSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { DEFAULT_CODEX_DIRECTORY_NAME } from './install-constants.mjs';
 
 export const SOL_PROMPT_DIRECTORY_NAME = 'system-prompts';
 export const SOL_PROMPT_FILE_NAME = 'codex-sol.md';
@@ -53,6 +56,91 @@ function readCodexConfig(configPath) {
     return { isReadable: true, currentText: readFileSync(configPath, 'utf8') };
 }
 
+/**
+ * Return the Codex home whose folder holds the prompt the config.toml setting names.
+ *
+ * Account sync links each account home's config.toml to the main Codex
+ * home's file: a symbolic link, or a hard link when the account cannot
+ * create one. Every home that shares that file shares one setting, so the
+ * prompt it names belongs in the main home. Any other home uses its own
+ * folder, including a home whose config.toml links into a dotfiles folder.
+ *
+ * @param {string} codexHome
+ * @returns {string}
+ */
+export function codexConfigDirectory(codexHome) {
+    const mainCodexHome = join(homedir(), DEFAULT_CODEX_DIRECTORY_NAME);
+    return sharesMainConfig(codexHome, mainCodexHome) ? mainCodexHome : codexHome;
+}
+
+function sharesMainConfig(codexHome, mainCodexHome) {
+    return isSameFile(join(codexHome, CODEX_CONFIG_FILE_NAME), join(mainCodexHome, CODEX_CONFIG_FILE_NAME));
+}
+
+function isSameFile(firstPath, secondPath) {
+    try {
+        const firstEntry = statSync(firstPath, { bigint: true, throwIfNoEntry: false });
+        const secondEntry = statSync(secondPath, { bigint: true, throwIfNoEntry: false });
+        return Boolean(firstEntry && secondEntry && firstEntry.dev === secondEntry.dev && firstEntry.ino === secondEntry.ino);
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * True when CODEX_HOME is an account home whose config.toml is the main Codex home's file.
+ *
+ * Such a home borrows the setting and the prompt from the main home, so
+ * uninstalling from it leaves both alone. The homes are compared as folders
+ * on disk, so a CODEX_HOME spelled with other letter case or through a link
+ * still counts as the main home.
+ *
+ * @param {string} codexHome
+ * @returns {boolean}
+ */
+export function codexConfigIsBorrowed(codexHome) {
+    const mainCodexHome = join(homedir(), DEFAULT_CODEX_DIRECTORY_NAME);
+    return sharesMainConfig(codexHome, mainCodexHome) && !isSameFile(codexHome, mainCodexHome);
+}
+
+/**
+ * Return where the installer keeps the Codex copy of the trimmed Sol prompt.
+ *
+ * The copy sits in CODEX_HOME, or in the main Codex home when CODEX_HOME is
+ * an account home that shares its config.toml, so the file the setting names
+ * stays put when any claude-dev-env version, older ones included, prunes or
+ * rewrites the managed files under ~/.claude, and every home that shares that
+ * config.toml names the same copy. A missing file makes every Codex command
+ * fail before it starts.
+ *
+ * @param {string} codexHome
+ * @returns {string}
+ */
+export function codexSolPromptPath(codexHome) {
+    return join(codexConfigDirectory(codexHome), SOL_PROMPT_FILE_NAME);
+}
+
+/**
+ * Copy the trimmed Sol prompt to the folder `codexSolPromptPath` names.
+ *
+ * An account home that shares the main config.toml also loses the copy an earlier
+ * install left in its own folder, since no setting names that copy any more.
+ *
+ * @param {string} codexHome
+ * @param {string} sourcePromptPath The prompt file the package ships.
+ * @returns {string|null} The prompt copy's path when this call wrote it, and null when it was already current.
+ */
+export function installCodexSolPrompt(codexHome, sourcePromptPath) {
+    if (codexConfigIsBorrowed(codexHome)) rmSync(join(codexHome, SOL_PROMPT_FILE_NAME), { force: true });
+    const promptPath = codexSolPromptPath(codexHome);
+    const promptText = readFileSync(sourcePromptPath, 'utf8');
+    const promptEntry = lstatSync(promptPath, { throwIfNoEntry: false });
+    if (promptEntry?.isFile() && readFileSync(promptPath, 'utf8') === promptText) return null;
+    mkdirSync(dirname(promptPath), { recursive: true });
+    writeFileSync(promptPath, promptText, 'utf8');
+    return promptPath;
+}
+
 export function codexSolSettingSnapshotPaths(codexHome) {
     const configPath = join(codexHome, CODEX_CONFIG_FILE_NAME);
     const { isReadable, currentText } = readCodexConfig(configPath);
@@ -88,12 +176,21 @@ export function writeCodexSolSetting(codexHome, instructionsPath) {
  * Remove the package's `model_instructions_file` line from CODEX_HOME/config.toml.
  *
  * The rest of the file stays as the user wrote it. A file that held only the
- * package line is removed.
+ * package line is removed. The prompt copy is removed in every case, because
+ * install writes it even when the user's own setting kept the package line
+ * out. An account home that shares the main config.toml only drops its own
+ * leftover copy: the shared setting and prompt belong to the main home, and
+ * other homes still read them.
  *
  * @param {string} codexHome
  * @returns {string|null} The config path when it changed, or null when nothing was removed.
  */
 export function removeCodexSolSetting(codexHome) {
+    if (codexConfigIsBorrowed(codexHome)) {
+        rmSync(join(codexHome, SOL_PROMPT_FILE_NAME), { force: true });
+        return null;
+    }
+    rmSync(codexSolPromptPath(codexHome), { force: true });
     const configPath = join(codexHome, CODEX_CONFIG_FILE_NAME);
     const { isReadable, currentText } = readCodexConfig(configPath);
     if (!isReadable || currentText === null) return null;

package/bin/codex-trimmed-sol.test.mjs

@@ -1,7 +1,7 @@
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -129,7 +129,7 @@ test('a missing config needs no prior snapshot', (context) => {
 test('full install points config.toml model_instructions_file at the installed trimmed prompt', (context) => {
     const homeDirectory = makeScratchHome(context);
     const configPath = join(homeDirectory, '.codex', CODEX_CONFIG_FILE_NAME);
-    const installedPromptPath = join(homeDirectory, '.claude', 'system-prompts', 'codex-sol.md');
+    const installedPromptPath = join(homeDirectory, '.codex', 'codex-sol.md');
 
     const firstInstallation = installInScratchHome(homeDirectory);
     assert.equal(firstInstallation.status, 0, firstInstallation.stdout + firstInstallation.stderr);
@@ -226,3 +226,156 @@ test('failed install leaves a directory at the config path unchanged', (context)
     assert.match(installation.stderr, /prior installation restored/);
     assert.equal(readFileSync(sentinelPath, 'utf8'), 'keep\n');
 });
+
+test('the prompt the setting names survives a prune of the managed Claude files', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const configPath = join(homeDirectory, '.codex', CODEX_CONFIG_FILE_NAME);
+    const installation = installInScratchHome(homeDirectory);
+    assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+    rmSync(join(homeDirectory, '.claude', 'system-prompts'), { recursive: true, force: true });
+    const namedPath = JSON.parse(readFileSync(configPath, 'utf8').split('\n')[1].split(' = ')[1]);
+    assert.equal(existsSync(namedPath), true);
+});
+
+test('uninstall removes the Codex copy of the prompt', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const promptPath = join(homeDirectory, '.codex', 'codex-sol.md');
+    const installation = installInScratchHome(homeDirectory);
+    assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+    assert.equal(existsSync(promptPath), true);
+    const uninstallation = installInScratchHome(homeDirectory, ['--uninstall']);
+    assert.equal(uninstallation.status, 0, uninstallation.stdout + uninstallation.stderr);
+    assert.equal(existsSync(promptPath), false);
+});
+
+test('uninstall removes the Codex copy of the prompt when the user wrote their own setting', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const codexHome = join(homeDirectory, '.codex');
+    const configPath = join(codexHome, CODEX_CONFIG_FILE_NAME);
+    const promptPath = join(codexHome, 'codex-sol.md');
+    const userText = 'model_instructions_file = "/mine.md"\n';
+    mkdirSync(codexHome, { recursive: true });
+    writeFileSync(configPath, userText);
+    const installation = installInScratchHome(homeDirectory);
+    assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+    assert.equal(existsSync(promptPath), true);
+    const uninstallation = installInScratchHome(homeDirectory, ['--uninstall']);
+    assert.equal(uninstallation.status, 0, uninstallation.stdout + uninstallation.stderr);
+    assert.equal(existsSync(promptPath), false);
+    assert.equal(readFileSync(configPath, 'utf8'), userText);
+});
+
+
+function makeLinkedCodexHomes(context) {
+    const homeDirectory = makeScratchHome(context);
+    const ownerHome = join(homeDirectory, '.codex');
+    const linkedHome = join(homeDirectory, '.codex-editor');
+    mkdirSync(ownerHome, { recursive: true });
+    mkdirSync(linkedHome, { recursive: true });
+    writeFileSync(join(ownerHome, CODEX_CONFIG_FILE_NAME), 'approval_policy = "never"\n');
+    try {
+        symlinkSync(join(ownerHome, CODEX_CONFIG_FILE_NAME), join(linkedHome, CODEX_CONFIG_FILE_NAME), 'file');
+    } catch (error) {
+        if (error.code === 'EPERM') return null;
+        throw error;
+    }
+    return { homeDirectory, ownerHome, linkedHome };
+}
+
+test('a home whose config.toml links to another home names the prompt beside the real file', (context) => {
+    const homes = makeLinkedCodexHomes(context);
+    if (!homes) return context.skip('this account cannot create symlinks');
+    const { homeDirectory, ownerHome, linkedHome } = homes;
+    writeFileSync(join(linkedHome, 'codex-sol.md'), 'left by an earlier install\n');
+
+    assert.equal(installInScratchHome(homeDirectory, [], { CODEX_HOME: ownerHome }).status, 0);
+    const linkedInstallation = installInScratchHome(homeDirectory, [], { CODEX_HOME: linkedHome });
+
+    assert.equal(linkedInstallation.status, 0, linkedInstallation.stderr);
+    const configText = readFileSync(join(ownerHome, CODEX_CONFIG_FILE_NAME), 'utf8');
+    assert.ok(configText.includes(`model_instructions_file = ${JSON.stringify(join(ownerHome, 'codex-sol.md'))}`), configText);
+    assert.equal(readFileSync(join(ownerHome, 'codex-sol.md'), 'utf8'), readFileSync(shippedPromptPath, 'utf8'));
+    assert.equal(existsSync(join(linkedHome, 'codex-sol.md')), false);
+});
+
+test('uninstall from a home whose config.toml is linked keeps the shared setting and prompt', (context) => {
+    const homes = makeLinkedCodexHomes(context);
+    if (!homes) return context.skip('this account cannot create symlinks');
+    const { homeDirectory, ownerHome, linkedHome } = homes;
+    assert.equal(installInScratchHome(homeDirectory, [], { CODEX_HOME: ownerHome }).status, 0);
+    assert.equal(installInScratchHome(homeDirectory, [], { CODEX_HOME: linkedHome }).status, 0);
+
+    const uninstallation = installInScratchHome(homeDirectory, ['--uninstall'], { CODEX_HOME: linkedHome });
+
+    assert.equal(uninstallation.status, 0, uninstallation.stderr);
+    const configText = readFileSync(join(ownerHome, CODEX_CONFIG_FILE_NAME), 'utf8');
+    assert.ok(configText.includes(`model_instructions_file = ${JSON.stringify(join(ownerHome, 'codex-sol.md'))}`), configText);
+    assert.equal(existsSync(join(ownerHome, 'codex-sol.md')), true);
+});
+
+test('a home whose config.toml is a hard link to the main home\'s file names the prompt in the main home', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const mainHome = join(homeDirectory, '.codex');
+    const linkedHome = join(homeDirectory, '.codex-editor');
+    mkdirSync(mainHome, { recursive: true });
+    mkdirSync(linkedHome, { recursive: true });
+    writeFileSync(join(mainHome, CODEX_CONFIG_FILE_NAME), 'approval_policy = "never"\n');
+    linkSync(join(mainHome, CODEX_CONFIG_FILE_NAME), join(linkedHome, CODEX_CONFIG_FILE_NAME));
+    assert.equal(installInScratchHome(homeDirectory, [], { CODEX_HOME: mainHome }).status, 0);
+
+    const linkedInstallation = installInScratchHome(homeDirectory, [], { CODEX_HOME: linkedHome });
+    assert.equal(linkedInstallation.status, 0, linkedInstallation.stderr);
+    const sharedLine = `model_instructions_file = ${JSON.stringify(join(mainHome, 'codex-sol.md'))}`;
+    assert.ok(readFileSync(join(mainHome, CODEX_CONFIG_FILE_NAME), 'utf8').includes(sharedLine));
+    assert.equal(existsSync(join(linkedHome, 'codex-sol.md')), false);
+
+    const uninstallation = installInScratchHome(homeDirectory, ['--uninstall'], { CODEX_HOME: linkedHome });
+    assert.equal(uninstallation.status, 0, uninstallation.stderr);
+    assert.ok(readFileSync(join(mainHome, CODEX_CONFIG_FILE_NAME), 'utf8').includes(sharedLine));
+    assert.equal(existsSync(join(mainHome, 'codex-sol.md')), true);
+});
+
+test('a main home whose config.toml links into a dotfiles folder keeps the prompt in CODEX_HOME, and uninstall removes the line', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const mainHome = join(homeDirectory, '.codex');
+    const dotfilesDirectory = join(homeDirectory, 'dotfiles', 'codex');
+    mkdirSync(mainHome, { recursive: true });
+    mkdirSync(dotfilesDirectory, { recursive: true });
+    writeFileSync(join(dotfilesDirectory, CODEX_CONFIG_FILE_NAME), 'approval_policy = "never"\n');
+    try {
+        symlinkSync(join(dotfilesDirectory, CODEX_CONFIG_FILE_NAME), join(mainHome, CODEX_CONFIG_FILE_NAME), 'file');
+    } catch (error) {
+        if (error.code === 'EPERM') return context.skip('this account cannot create symlinks');
+        throw error;
+    }
+
+    assert.equal(installInScratchHome(homeDirectory, [], { CODEX_HOME: mainHome }).status, 0);
+    assert.ok(readFileSync(join(dotfilesDirectory, CODEX_CONFIG_FILE_NAME), 'utf8')
+        .includes(`model_instructions_file = ${JSON.stringify(join(mainHome, 'codex-sol.md'))}`));
+    assert.equal(existsSync(join(dotfilesDirectory, 'codex-sol.md')), false);
+
+    assert.equal(installInScratchHome(homeDirectory, ['--uninstall'], { CODEX_HOME: mainHome }).status, 0);
+    assert.equal(readFileSync(join(dotfilesDirectory, CODEX_CONFIG_FILE_NAME), 'utf8'), 'approval_policy = "never"\n');
+    assert.equal(existsSync(join(mainHome, 'codex-sol.md')), false);
+});
+
+test('CODEX_HOME that reaches the main home through a folder link still uninstalls the line', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const mainHome = join(homeDirectory, '.codex');
+    const folderLink = join(homeDirectory, 'codex-home-link');
+    mkdirSync(mainHome, { recursive: true });
+    writeFileSync(join(mainHome, CODEX_CONFIG_FILE_NAME), 'approval_policy = "never"\n');
+    try {
+        symlinkSync(mainHome, folderLink, 'junction');
+    } catch (error) {
+        if (error.code === 'EPERM') return context.skip('this account cannot create links');
+        throw error;
+    }
+
+    assert.equal(installInScratchHome(homeDirectory, [], { CODEX_HOME: folderLink }).status, 0);
+    assert.equal(existsSync(join(mainHome, 'codex-sol.md')), true);
+
+    assert.equal(installInScratchHome(homeDirectory, ['--uninstall'], { CODEX_HOME: folderLink }).status, 0);
+    assert.equal(readFileSync(join(mainHome, CODEX_CONFIG_FILE_NAME), 'utf8'), 'approval_policy = "never"\n');
+    assert.equal(existsSync(join(mainHome, 'codex-sol.md')), false);
+});

package/bin/folder-lockers.mjs

@@ -0,0 +1,142 @@
+import { spawnSync } from 'node:child_process';
+
+/** Env var that carries the folder path into the PowerShell probe, so no quoting reaches the command line. */
+export const LOCKED_FOLDER_VARIABLE = 'CDE_LOCKED_FOLDER';
+const LOCKER_PROBE_TIMEOUT_MILLISECONDS = 20000;
+const LOCKED_FOLDER_PATTERN = /\b(EPERM|EBUSY|in use by another program|being used by another process)\b/i;
+export const LOCKER_REASON_COMMAND_LINE = 'command-line';
+export const LOCKER_REASON_OPEN_FILE = 'open-file';
+
+/**
+ * PowerShell that lists the processes holding a folder.
+ *
+ * Two checks run: a process whose command line or executable path names a
+ * path inside the folder (an editor or shell opened on a file there), and a
+ * process that holds a file in the folder open, from the Windows Restart
+ * Manager. Each match prints one JSON line.
+ */
+export const LOCKER_PROBE_SCRIPT = String.raw`
+$ErrorActionPreference = 'SilentlyContinue'
+$folder = [IO.Path]::GetFullPath($env:${LOCKED_FOLDER_VARIABLE}).TrimEnd('\')
+$forms = @($folder, $folder.Replace('\', '/'))
+foreach ($process in Get-CimInstance Win32_Process) {
+    $text = "$($process.CommandLine) $($process.ExecutablePath)"
+    foreach ($form in $forms) {
+        if ($text.IndexOf($form, [StringComparison]::OrdinalIgnoreCase) -ge 0) {
+            [pscustomobject]@{ pid = [int]$process.ProcessId; name = $process.Name; reason = '${LOCKER_REASON_COMMAND_LINE}' } | ConvertTo-Json -Compress
+            break
+        }
+    }
+}
+Add-Type -Namespace Cde -Name RestartManager -MemberDefinition @'
+[StructLayout(LayoutKind.Sequential)] public struct UniqueProcess { public int ProcessId; public System.Runtime.InteropServices.ComTypes.FILETIME StartTime; }
+[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)] public struct ProcessInfo { public UniqueProcess Process; [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)] public string AppName; [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 64)] public string ServiceName; public int ApplicationType; public uint AppStatus; public uint TSSessionId; [MarshalAs(UnmanagedType.Bool)] public bool Restartable; }
+[DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)] public static extern int RmStartSession(out uint handle, int flags, System.Text.StringBuilder key);
+[DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)] public static extern int RmRegisterResources(uint handle, uint fileCount, string[] files, uint appCount, IntPtr apps, uint serviceCount, string[] services);
+[DllImport("rstrtmgr.dll")] public static extern int RmGetList(uint handle, out uint needed, ref uint count, [In, Out] ProcessInfo[] infos, ref uint reasons);
+[DllImport("rstrtmgr.dll")] public static extern int RmEndSession(uint handle);
+'@
+$files = @(Get-ChildItem -LiteralPath $folder -Recurse -File -Force | Select-Object -First 2000 -ExpandProperty FullName)
+if ($files.Count -gt 0) {
+    $handle = [uint32]0
+    if ([Cde.RestartManager]::RmStartSession([ref]$handle, 0, (New-Object Text.StringBuilder 64)) -eq 0) {
+        try {
+            if ([Cde.RestartManager]::RmRegisterResources($handle, [uint32]$files.Count, [string[]]$files, 0, [IntPtr]::Zero, 0, $null) -eq 0) {
+                $needed = [uint32]0; $count = [uint32]64; $reasons = [uint32]0
+                $infos = New-Object Cde.RestartManager+ProcessInfo[] 64
+                if ([Cde.RestartManager]::RmGetList($handle, [ref]$needed, [ref]$count, $infos, [ref]$reasons) -eq 0) {
+                    for ($index = 0; $index -lt $count; $index++) {
+                        [pscustomobject]@{ pid = $infos[$index].Process.ProcessId; name = $infos[$index].AppName; reason = '${LOCKER_REASON_OPEN_FILE}' } | ConvertTo-Json -Compress
+                    }
+                }
+            }
+        } finally { [void][Cde.RestartManager]::RmEndSession($handle) }
+    }
+}
+`;
+
+/**
+ * True when a host command's error text says a folder could not be replaced because it is in use.
+ *
+ * @param {string} errorText The command's error output.
+ * @returns {boolean}
+ */
+export function namesALockedFolder(errorText) {
+    return LOCKED_FOLDER_PATTERN.test(errorText ?? '');
+}
+
+/**
+ * Parse the probe's JSON lines into one entry per process.
+ *
+ * @param {string} probeOutput Standard output of the PowerShell probe.
+ * @param {number} ownProcessId This installer's process id, which never counts as a locker.
+ * @returns {{pid: number, name: string, reason: string}[]}
+ */
+export function parseLockerLines(probeOutput, ownProcessId = process.pid) {
+    const lockersByProcessId = new Map();
+    for (const eachLine of (probeOutput ?? '').split(/\r?\n/)) {
+        const trimmedLine = eachLine.trim();
+        if (!trimmedLine.startsWith('{')) continue;
+        let locker;
+        try {
+            locker = JSON.parse(trimmedLine);
+        } catch {
+            continue;
+        }
+        if (!Number.isInteger(locker.pid) || locker.pid === ownProcessId) continue;
+        if (!lockersByProcessId.has(locker.pid)) lockersByProcessId.set(locker.pid, locker);
+    }
+    return [...lockersByProcessId.values()];
+}
+
+/**
+ * List the running processes that hold a folder, on Windows.
+ *
+ * @param {string} folderPath The folder a host could not replace.
+ * @param {object} [dependencies] Seams for tests.
+ * @param {string} [dependencies.platform] The Node platform name.
+ * @param {(folderPath: string) => string|null} [dependencies.runProbe] Returns the probe's standard output, or null when the probe could not start or timed out.
+ * @returns {{pid: number, name: string, reason: string}[]|null} The holders, an empty list when the probe ran and found none, and null when nothing was searched: another platform, or a probe that could not start or timed out.
+ */
+export function findFolderLockers(folderPath, dependencies = {}) {
+    const platform = dependencies.platform ?? process.platform;
+    if (platform !== 'win32' || !folderPath) return null;
+    const runProbe = dependencies.runProbe ?? runLockerProbe;
+    const probeOutput = runProbe(folderPath);
+    return probeOutput === null ? null : parseLockerLines(probeOutput);
+}
+
+function runLockerProbe(folderPath) {
+    const encodedScript = Buffer.from(LOCKER_PROBE_SCRIPT, 'utf16le').toString('base64');
+    const probe = spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-EncodedCommand', encodedScript], {
+        encoding: 'utf8',
+        env: { ...process.env, [LOCKED_FOLDER_VARIABLE]: folderPath },
+        timeout: LOCKER_PROBE_TIMEOUT_MILLISECONDS,
+        windowsHide: true,
+    });
+    if (probe.error) return null;
+    return probe.stdout ?? '';
+}
+
+function describeLocker(locker) {
+    const how = locker.reason === LOCKER_REASON_OPEN_FILE
+        ? 'has a file in it open'
+        : 'was started on a path inside it';
+    return `${locker.name} (PID ${locker.pid}, ${how})`;
+}
+
+/**
+ * Tell the user exactly what to close so a locked plugin folder can be replaced.
+ *
+ * @param {string} folderPath The folder the host could not replace.
+ * @param {{pid: number, name: string, reason: string}[]} allLockers What holds it.
+ * @returns {string}
+ */
+export function lockedFolderAdvice(folderPath, allLockers) {
+    if (allLockers.length === 0) {
+        return `No running process names ${folderPath} or holds a file in it open, so a window or terminal`
+            + ' whose working folder is inside it is the likely holder. Close it and run the install again.';
+    }
+    const verb = allLockers.length === 1 ? 'holds' : 'hold';
+    return `Close ${allLockers.map(describeLocker).join(', ')}, which ${verb} ${folderPath}, and run the install again.`;
+}

package/bin/folder-lockers.test.mjs

@@ -0,0 +1,55 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import {
+    findFolderLockers,
+    LOCKER_REASON_COMMAND_LINE,
+    LOCKER_REASON_OPEN_FILE,
+    lockedFolderAdvice,
+    namesALockedFolder,
+    parseLockerLines,
+} from './folder-lockers.mjs';
+
+test('a host error about a folder in use names a locked folder', () => {
+    assert.equal(namesALockedFolder('could not be replaced: it is in use by another program (EPERM)'), true);
+    assert.equal(namesALockedFolder('EBUSY: resource busy or locked'), true);
+    assert.equal(namesALockedFolder('Failed to parse marketplace file'), false);
+});
+
+test('probe lines become one entry per process, and this process never counts', () => {
+    const probeOutput = [
+        '{"pid":19056,"name":"Cursor.exe","reason":"command-line"}',
+        '{"pid":19056,"name":"Cursor.exe","reason":"open-file"}',
+        'WARNING: noise',
+        '{"pid":4242,"name":"pwsh.exe","reason":"open-file"}',
+        '{"pid":7,"name":"node.exe","reason":"command-line"}',
+    ].join('\r\n');
+    assert.deepEqual(parseLockerLines(probeOutput, 7), [
+        { pid: 19056, name: 'Cursor.exe', reason: LOCKER_REASON_COMMAND_LINE },
+        { pid: 4242, name: 'pwsh.exe', reason: LOCKER_REASON_OPEN_FILE },
+    ]);
+});
+
+test('only Windows runs the probe', () => {
+    let probedFolder = null;
+    const runProbe = folderPath => {
+        probedFolder = folderPath;
+        return '{"pid":5,"name":"Cursor.exe","reason":"command-line"}';
+    };
+    assert.equal(findFolderLockers('/cache/pstack', { platform: 'linux', runProbe }), null);
+    assert.equal(probedFolder, null);
+    assert.equal(findFolderLockers('C:/cache/pstack', { platform: 'win32', runProbe }).length, 1);
+    assert.equal(probedFolder, 'C:/cache/pstack');
+});
+
+test('the advice names each process to close, or says what else holds a folder', () => {
+    assert.equal(
+        lockedFolderAdvice('C:/cache/pstack', [{ pid: 19056, name: 'Cursor.exe', reason: LOCKER_REASON_COMMAND_LINE }]),
+        'Close Cursor.exe (PID 19056, was started on a path inside it), which holds C:/cache/pstack, and run the install again.',
+    );
+    assert.match(lockedFolderAdvice('C:/cache/pstack', []), /working folder is inside it/);
+});
+
+test('a probe that did not finish searched nothing, and a probe that found no holder is an empty list', () => {
+    assert.equal(findFolderLockers('C:/cache/pstack', { platform: 'win32', runProbe: () => null }), null);
+    assert.deepEqual(findFolderLockers('C:/cache/pstack', { platform: 'win32', runProbe: () => '' }), []);
+});

package/bin/global-install-shadow.mjs

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Return the folder a global `npm install -g` of the package lives in, or null when the prefix is unknown.
+ *
+ * npm passes its global prefix to the programs it starts as
+ * `npm_config_global_prefix`. On Windows the default prefix is `%APPDATA%\npm`.
+ *
+ * @param {string} packageName
+ * @param {Record<string, string|undefined>} environment
+ * @param {string} platform The Node platform name.
+ * @returns {string|null}
+ */
+export function globalPackageDirectory(packageName, environment, platform) {
+    const windowsDefaultPrefix = platform === 'win32' && environment.APPDATA ? join(environment.APPDATA, 'npm') : null;
+    const prefix = environment.npm_config_global_prefix || environment.npm_config_prefix || windowsDefaultPrefix;
+    if (!prefix) return null;
+    return platform === 'win32'
+        ? join(prefix, 'node_modules', packageName)
+        : join(prefix, 'lib', 'node_modules', packageName);
+}
+
+function samePath(firstPath, secondPath) {
+    try {
+        return realpathSync(firstPath).toLowerCase() === realpathSync(secondPath).toLowerCase();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Find a global install of the package at another version than the one running.
+ *
+ * `npx <package>` with no version runs a global copy when one is on PATH, so
+ * an old global copy runs instead of the newest release, and its update pass
+ * prunes files that newer installs left for Codex and Cursor.
+ *
+ * @param {object} options
+ * @param {string} options.packageName
+ * @param {string} options.packageRoot The folder of the copy that is running.
+ * @param {string} options.packageVersion The running version.
+ * @param {Record<string, string|undefined>} [options.environment]
+ * @param {string} [options.platform]
+ * @returns {{directory: string, version: string}|null}
+ */
+export function findShadowingGlobalInstall(options) {
+    const environment = options.environment ?? process.env;
+    const directory = globalPackageDirectory(options.packageName, environment, options.platform ?? process.platform);
+    if (!directory) return null;
+    const manifestPath = join(directory, 'package.json');
+    if (!existsSync(manifestPath) || samePath(directory, options.packageRoot)) return null;
+    let version;
+    try {
+        version = JSON.parse(readFileSync(manifestPath, 'utf8')).version;
+    } catch {
+        return null;
+    }
+    if (!version || version === options.packageVersion) return null;
+    return { directory, version };
+}
+
+/**
+ * Say what the global copy does and the exact commands that fix it.
+ *
+ * @param {string} packageName
+ * @param {{directory: string, version: string}} shadow
+ * @param {string} packageVersion The running version.
+ * @returns {string}
+ */
+export function shadowingGlobalAdvice(packageName, shadow, packageVersion) {
+    return `A global ${packageName} ${shadow.version} is installed at ${shadow.directory}. `
+        + `\`npx ${packageName}\` without a version runs that copy instead of ${packageVersion}. `
+        + `Remove it with \`npm uninstall -g ${packageName}\`, or update it with \`npm install -g ${packageName}@latest\`.`;
+}

package/bin/global-install-shadow.test.mjs

@@ -0,0 +1,56 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { findShadowingGlobalInstall, globalPackageDirectory, shadowingGlobalAdvice } from './global-install-shadow.mjs';
+
+function makeScratch(context) {
+    const scratch = mkdtempSync(join(tmpdir(), 'cde-shadow-'));
+    context.after(() => rmSync(scratch, { recursive: true, force: true }));
+    return scratch;
+}
+
+function writeGlobalCopy(prefix, version) {
+    const directory = join(prefix, 'node_modules', 'claude-dev-env');
+    mkdirSync(directory, { recursive: true });
+    writeFileSync(join(directory, 'package.json'), JSON.stringify({ name: 'claude-dev-env', version }));
+    return directory;
+}
+
+test('the global folder comes from npm, or the Windows default prefix', () => {
+    assert.equal(
+        globalPackageDirectory('claude-dev-env', { npm_config_global_prefix: '/usr/local' }, 'linux'),
+        join('/usr/local', 'lib', 'node_modules', 'claude-dev-env'),
+    );
+    assert.equal(
+        globalPackageDirectory('claude-dev-env', { APPDATA: 'C:/Roaming' }, 'win32'),
+        join('C:/Roaming', 'npm', 'node_modules', 'claude-dev-env'),
+    );
+    assert.equal(globalPackageDirectory('claude-dev-env', {}, 'linux'), null);
+});
+
+test('an older global copy is found and named with the commands that fix it', (context) => {
+    const scratch = makeScratch(context);
+    const directory = writeGlobalCopy(join(scratch, 'npm'), '8.35.1');
+    const shadow = findShadowingGlobalInstall({
+        packageName: 'claude-dev-env',
+        packageRoot: join(scratch, 'npx-copy'),
+        packageVersion: '8.89.0',
+        environment: { APPDATA: scratch },
+        platform: 'win32',
+    });
+    assert.deepEqual(shadow, { directory, version: '8.35.1' });
+    const advice = shadowingGlobalAdvice('claude-dev-env', shadow, '8.89.0');
+    assert.match(advice, /global claude-dev-env 8\.35\.1/);
+    assert.match(advice, /npm uninstall -g claude-dev-env/);
+});
+
+test('a global copy at the running version, or the running copy itself, is not reported', (context) => {
+    const scratch = makeScratch(context);
+    const directory = writeGlobalCopy(join(scratch, 'npm'), '8.89.0');
+    const options = { packageName: 'claude-dev-env', environment: { APPDATA: scratch }, platform: 'win32' };
+    assert.equal(findShadowingGlobalInstall({ ...options, packageRoot: join(scratch, 'x'), packageVersion: '8.89.0' }), null);
+    assert.equal(findShadowingGlobalInstall({ ...options, packageRoot: directory, packageVersion: '9.0.0' }), null);
+    assert.equal(findShadowingGlobalInstall({ ...options, environment: {}, packageRoot: directory, packageVersion: '1' }), null);
+});