claude-dev-env 8.88.1 → 8.88.2

package/bin/codex-trimmed-sol.mjs

@@ -1,4 +1,4 @@
-import { lstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { lstatSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 export const SOL_PROMPT_DIRECTORY_NAME = 'system-prompts';
@@ -53,6 +53,38 @@ function readCodexConfig(configPath) {
     return { isReadable: true, currentText: readFileSync(configPath, 'utf8') };
 }
 
+/**
+ * Return where the installer keeps the Codex copy of the trimmed Sol prompt.
+ *
+ * The copy lives in CODEX_HOME beside 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. A missing file makes
+ * every Codex command fail before it starts.
+ *
+ * @param {string} codexHome
+ * @returns {string}
+ */
+export function codexSolPromptPath(codexHome) {
+    return join(codexHome, SOL_PROMPT_FILE_NAME);
+}
+
+/**
+ * Copy the trimmed Sol prompt into CODEX_HOME.
+ *
+ * @param {string} codexHome
+ * @param {string} sourcePromptPath The prompt file the package ships.
+ * @returns {string|null} The Codex copy's path when this call wrote it, and null when it was already current.
+ */
+export function installCodexSolPrompt(codexHome, sourcePromptPath) {
+    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(codexHome, { 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 +120,15 @@ 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 Codex copy of the prompt is removed in every
+ * case, because install writes it even when the user's own setting kept the
+ * package line out.
  *
  * @param {string} codexHome
  * @returns {string|null} The config path when it changed, or null when nothing was removed.
  */
 export function removeCodexSolSetting(codexHome) {
+    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

@@ -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,41 @@ 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);
+});

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);
+});

package/bin/install-deepstack-plugin.mjs

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
@@ -23,6 +23,9 @@ export const DEEPSTACK_PLUGIN_OPT_OUT_FLAG = '--no-deepstack';
 export const DEEPSTACK_PLUGIN_OPT_OUT_VARIABLE = 'CDE_INSTALL_DEEPSTACK';
 export const DEEPSTACK_SOURCE_VARIABLE = 'CDE_DEEPSTACK_SOURCE';
 export const DEEPSTACK_CURSOR_DIRECTORY_NAME = 'plugins/deepstack';
+/** Name prefix of the temporary DeepStack clone a full install makes when no local tree exists. */
+export const DEEPSTACK_CLONE_PREFIX = 'deepstack-';
+const CLONE_REMOVAL_RETRIES = 3;
 export const DEEPSTACK_SKILL_RELATIVE_PATH = 'skills/deepstack-mode/SKILL.md';
 export const DEEPSTACK_SESSION_SCRIPT_RELATIVE_PATH = 'hooks/session-start.sh';
 export const DEEPSTACK_SESSION_POWERSHELL_RELATIVE_PATH = 'hooks/session-start.ps1';
@@ -266,7 +269,9 @@ export function seedCodexDeepStackModels(codexHome) {
  * @param {string} [options.sourceDirectory] A local plugin tree for the Cursor copy.
  * @param {string[]} [options.argumentList] Command-line arguments, for the opt-out flag.
  * @param {Record<string, string|undefined>} [options.environment] The process environment.
- * @param {object} [dependencies] Seams for the marketplace command runner.
+ * @param {boolean} [options.allowClone] False stops the clone fallback.
+ * @param {string} [options.cloneParentDirectory] Where the temporary clone goes. Defaults to the system temp folder.
+ * @param {object} [dependencies] Seams for the marketplace command runner and the clone.
  * @returns {{status: string, hosts: object[], cursor: object, warning: string|null}} The outcome.
  */
 export function installDeepStackForHosts(options = {}, dependencies = {}) {
@@ -290,16 +295,25 @@ export function installDeepStackForHosts(options = {}, dependencies = {}) {
         environment,
         sourceDirectory: options.sourceDirectory,
     });
-    if (!sourceDirectory && options.allowClone !== false) {
-        sourceDirectory = cloneDeepStackRepository(mkdtempSync(join(tmpdir(), 'deepstack-')));
+    const cloneDirectory = !sourceDirectory && options.allowClone !== false
+        ? mkdtempSync(join(options.cloneParentDirectory ?? tmpdir(), DEEPSTACK_CLONE_PREFIX))
+        : null;
+    let cursor;
+    try {
+        if (cloneDirectory) {
+            const cloneRepository = dependencies.cloneRepository ?? cloneDeepStackRepository;
+            sourceDirectory = cloneRepository(cloneDirectory);
+        }
+        cursor = installDeepStackCursor({
+            cursorDirectory: options.cursorDirectory,
+            pluginSourceDirectory: sourceDirectory,
+            firstTaskHookPath: options.firstTaskHookPath,
+            pythonCommand: options.pythonCommand,
+            formatPathArgument: options.formatPathArgument,
+        });
+    } finally {
+        if (cloneDirectory) removeDeepStackClone(cloneDirectory);
     }
-    const cursor = installDeepStackCursor({
-        cursorDirectory: options.cursorDirectory,
-        pluginSourceDirectory: sourceDirectory,
-        firstTaskHookPath: options.firstTaskHookPath,
-        pythonCommand: options.pythonCommand,
-        formatPathArgument: options.formatPathArgument,
-    });
     if (marketplace.hosts.some(host => host.host === 'codex' && host.status === 'installed') && options.codexHome) {
         seedCodexDeepStackModels(options.codexHome);
     }
@@ -314,14 +328,20 @@ export function installDeepStackForHosts(options = {}, dependencies = {}) {
 }
 
 /**
- * Clone jl-cmd-projects/DeepStack when no local tree is available.
+ * Remove the temporary DeepStack clone once the Cursor copy is written.
  *
- * The installer calls this only from a full install that has no source
- * directory and no marketplace cache. Tests pass a source directory instead.
+ * Nothing reads the clone after the install: the Cursor hooks point at the
+ * copy under the Cursor home, and Claude and Codex read their own marketplace
+ * caches. Git writes its pack files read-only, which the forced removal
+ * handles on Windows too.
  *
- * @param {string} destination An empty directory for the clone.
- * @returns {string|null} The plugin directory inside the clone.
+ * @param {string} cloneDirectory The directory the clone was made in.
+ * @returns {void}
  */
+export function removeDeepStackClone(cloneDirectory) {
+    rmSync(cloneDirectory, { recursive: true, force: true, maxRetries: CLONE_REMOVAL_RETRIES });
+}
+
 /**
  * Return the git clone URL for the DeepStack marketplace repository.
  *
@@ -331,6 +351,15 @@ export function deepStackCloneUrl() {
     return ['https:', '', 'github.com', `${DEEPSTACK_MARKETPLACE_REPOSITORY}.git`].join('/');
 }
 
+/**
+ * Clone jl-cmd-projects/DeepStack when no local tree is available.
+ *
+ * The installer calls this only from a full install that has no source
+ * directory and no marketplace cache. Tests pass a source directory instead.
+ *
+ * @param {string} destination An empty directory for the clone.
+ * @returns {string|null} The plugin directory inside the clone.
+ */
 export function cloneDeepStackRepository(destination) {
     const outcome = spawnSync('git', [
         'clone',

package/bin/install-deepstack-plugin.test.mjs

@@ -1,10 +1,11 @@
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
     DEEPSTACK_MARKETPLACE_REPOSITORY,
+    DEEPSTACK_SKILL_RELATIVE_PATH,
     DEEPSTACK_PLUGIN_IDENTIFIER,
     DEEPSTACK_PLUGIN_SPEC,
     deepStackCloneUrl,
@@ -136,3 +137,66 @@ test('--no-deepstack and CDE_INSTALL_DEEPSTACK=0 skip the install', () => {
     assert.equal(skipped.status, 'skipped');
     assert.equal(skipped.cursor.status, 'skipped');
 });
+
+const absentHostRunner = () => ({ status: null, stderr: '', error: { code: 'ENOENT' } });
+
+function writeClonedPlugin(cloneDirectory) {
+    const pluginDirectory = join(cloneDirectory, 'plugins', 'deepstack');
+    mkdirSync(join(pluginDirectory, 'skills', 'deepstack-mode'), { recursive: true });
+    writeFileSync(join(pluginDirectory, DEEPSTACK_SKILL_RELATIVE_PATH), '# DeepStack\n');
+    mkdirSync(join(cloneDirectory, '.git', 'objects', 'pack'), { recursive: true });
+    const packPath = join(cloneDirectory, '.git', 'objects', 'pack', 'pack-1.pack');
+    writeFileSync(packPath, 'pack');
+    chmodSync(packPath, 0o444);
+    return pluginDirectory;
+}
+
+test('the temporary clone is removed once the Cursor copy is written', () => {
+    const root = mkdtempSync(join(tmpdir(), 'deepstack-clone-'));
+    try {
+        const cloneParentDirectory = join(root, 'temp');
+        mkdirSync(cloneParentDirectory);
+        const cursorDirectory = join(root, 'cursor');
+        let clonedInto = null;
+        const outcome = installDeepStackForHosts({
+            claudeRoot: join(root, 'claude'),
+            codexHome: join(root, 'codex'),
+            cursorDirectory,
+            firstTaskHookPath: join(root, 'hooks', 'deepen_first_prompt.py'),
+            environment: {},
+            cloneParentDirectory,
+        }, {
+            runCommand: absentHostRunner,
+            cloneRepository: cloneDirectory => {
+                clonedInto = cloneDirectory;
+                return writeClonedPlugin(cloneDirectory);
+            },
+        });
+        assert.equal(outcome.cursor.status, 'installed');
+        assert.ok(clonedInto.startsWith(cloneParentDirectory));
+        assert.ok(existsSync(join(cursorDirectory, 'plugins', 'deepstack', DEEPSTACK_SKILL_RELATIVE_PATH)));
+        assert.deepEqual(readdirSync(cloneParentDirectory), []);
+    } finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+
+test('a failed clone leaves no temporary folder behind', () => {
+    const root = mkdtempSync(join(tmpdir(), 'deepstack-clone-'));
+    try {
+        const cloneParentDirectory = join(root, 'temp');
+        mkdirSync(cloneParentDirectory);
+        const outcome = installDeepStackForHosts({
+            claudeRoot: join(root, 'claude'),
+            codexHome: join(root, 'codex'),
+            cursorDirectory: join(root, 'cursor'),
+            firstTaskHookPath: join(root, 'hooks', 'deepen_first_prompt.py'),
+            environment: {},
+            cloneParentDirectory,
+        }, { runCommand: absentHostRunner, cloneRepository: () => null });
+        assert.equal(outcome.cursor.status, 'failed');
+        assert.deepEqual(readdirSync(cloneParentDirectory), []);
+    } finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});