claude-dev-env 8.88.1 → 8.88.3

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

package/bin/install-pstack-plugin.mjs

@@ -1,6 +1,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
+import { findFolderLockers, lockedFolderAdvice, namesALockedFolder } from './folder-lockers.mjs';
 
 export const PSTACK_MARKETPLACE_REPOSITORY = 'jl-cmd/pstack-claude';
 export const PSTACK_MARKETPLACE_NAME = 'pstack-claude';
@@ -248,7 +249,17 @@ function absentHostOutcome(allSpecs, host, executable) {
     };
 }
 
-function installForHost(allSpecs, host, homeDirectory, environment, runCommand) {
+function lockedFolderDetail(allSpecs, host, homeDirectory, errorText, findLockers) {
+    const hostDefinition = HOST_DEFINITIONS[host];
+    if (!namesALockedFolder(errorText) || !hostDefinition.orphanedVersionsDirectory || !homeDirectory) return '';
+    return allSpecs.map(eachSpec => {
+        const pluginCacheDirectory = hostDefinition.orphanedVersionsDirectory(homeDirectory, eachSpec);
+        const allLockers = findLockers(pluginCacheDirectory);
+        return allLockers === null ? '' : ` ${lockedFolderAdvice(pluginCacheDirectory, allLockers)}`;
+    }).join('');
+}
+
+function installForHost(allSpecs, host, homeDirectory, environment, runCommand, findLockers) {
     const plan = marketplacePluginsPlan(allSpecs, host);
     const executable = environment[plan.executableVariable] || plan.executable;
     const commandEnvironment = { [plan.homeVariable]: homeDirectory };
@@ -265,11 +276,12 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand)
         if (namesAnAbsentCommand(outcome)) return absentHostOutcome(allSpecs, host, executable);
         if (outcome.status !== 0 || outcome.error) {
             const detail = singleLineDetail(outcome.stderr) || outcome.error?.message || `exit ${outcome.status}`;
+            const lockAdvice = lockedFolderDetail(allSpecs, host, homeDirectory, detail, findLockers);
             return {
                 host,
                 executable,
                 status: 'failed',
-                warning: `${executable} ${commandArguments.join(' ')} failed: ${detail}`,
+                warning: `${executable} ${commandArguments.join(' ')} failed: ${detail}${lockAdvice}`,
             };
         }
     }
@@ -294,7 +306,9 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand)
  * and skills this run already wrote still reach their durable places. An
  * absent tool arrives as a spawn `ENOENT` on other platforms and as
  * `cmd.exe`'s command-not-found exit code on Windows, and both read as
- * skipped.
+ * skipped. When a host cannot replace a plugin folder because something holds
+ * it, the warning names each process that holds it, so the user knows what to
+ * close before running the install again.
  *
  * @param {ReadonlyArray<typeof PSTACK_PLUGIN_SPEC>} allSpecs The plugins to install, from one marketplace.
  * @param {object} [options] Install targets.
@@ -302,12 +316,13 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand)
  * @param {string} [options.codexHome] The Codex home to install into.
  * @param {string[]} [options.hosts] The hosts to install. Defaults to the hosts every spec names.
  * @param {Record<string, string|undefined>} [options.environment] The process environment.
- * @param {object} [dependencies] Seams for the command runner.
+ * @param {object} [dependencies] Seams for the command runner and the folder locker search.
  * @returns {{status: string, hosts: object[], warning: string|null}} The outcome per host.
  */
 export function installMarketplacePlugins(allSpecs, options = {}, dependencies = {}) {
     const environment = options.environment ?? process.env;
     const runCommand = dependencies.runCommand ?? runHostCommand;
+    const findLockers = dependencies.findLockers ?? findFolderLockers;
     const homeDirectories = { claude: options.claudeRoot, codex: options.codexHome };
     const hosts = options.hosts ?? allSpecs[0].hosts.filter(
         eachHost => allSpecs.every(eachSpec => eachSpec.hosts.includes(eachHost)),
@@ -318,6 +333,7 @@ export function installMarketplacePlugins(allSpecs, options = {}, dependencies =
         homeDirectories[host],
         environment,
         runCommand,
+        findLockers,
     ));
     const failedCount = hostOutcomes.filter(outcome => outcome.status === 'failed').length;
     const installedCount = hostOutcomes.filter(outcome => outcome.status === 'installed').length;

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

@@ -392,3 +392,56 @@ test('a clean install deletes the orphaned pstack versions and keeps the install
     assert.equal(existsSync(join(versionsDirectory, '0.9.64')), true);
     assert.deepEqual(removeOrphanedPluginVersions(versionsDirectory), []);
 });
+
+test('a plugin folder held by another program names the process to close', () => {
+    const lockedError = 'Failed to install plugin "pstack@pstack-claude": The installed copy of this plugin version'
+        + ' could not be replaced: it is in use by another program (EPERM).';
+    const searchedFolders = [];
+    const runner = recordingRunner((executable, commandArguments) => (
+        executable === 'claude' && commandArguments[1] === 'install'
+            ? { status: 1, stderr: lockedError }
+            : { status: 0, stderr: '' }));
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, {
+        runCommand: runner.runCommand,
+        findLockers: folderPath => {
+            searchedFolders.push(folderPath);
+            return [{ pid: 19056, name: 'Cursor.exe', reason: 'command-line' }];
+        },
+    });
+    const claude = outcome.hosts.find(host => host.host === 'claude');
+    assert.equal(claude.status, 'failed');
+    assert.deepEqual(searchedFolders, [join('/managed/.claude', 'plugins', 'cache', 'pstack-claude', 'pstack')]);
+    assert.match(claude.warning, /Close Cursor\.exe \(PID 19056, was started on a path inside it\)/);
+});
+
+test('a failure that is not a held folder runs no locker search', () => {
+    const runner = recordingRunner((executable, commandArguments) => (
+        executable === 'claude' && commandArguments[2] === 'add'
+            ? { status: 1, stderr: 'owner: Invalid input: expected object, received undefined' }
+            : { status: 0, stderr: '' }));
+    let searched = false;
+    installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, {
+        runCommand: runner.runCommand,
+        findLockers: () => {
+            searched = true;
+            return [];
+        },
+    });
+    assert.equal(searched, false);
+});
+
+test('a held folder that was not searched adds no claim about what holds it', () => {
+    const lockedError = 'Failed to install plugin "pstack@pstack-claude": EPERM: operation not permitted';
+    const runner = recordingRunner((executable, commandArguments) => (
+        executable === 'claude' && commandArguments[1] === 'install'
+            ? { status: 1, stderr: lockedError }
+            : { status: 0, stderr: '' }));
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, {
+        runCommand: runner.runCommand,
+        findLockers: () => null,
+    });
+    const claude = outcome.hosts.find(host => host.host === 'claude');
+    assert.equal(claude.status, 'failed');
+    assert.match(claude.warning, /EPERM: operation not permitted$/);
+    assert.doesNotMatch(claude.warning, /likely holder|Close /);
+});

package/bin/install.mjs

@@ -72,7 +72,9 @@ import {
     writeCursorAgentsGuidanceHooks,
 } from './cursor-agents-guidance.mjs';
 import {
+    codexSolPromptPath,
     codexSolSettingSnapshotPaths,
+    installCodexSolPrompt,
     removeCodexSolSetting,
     SOL_PROMPT_DIRECTORY_NAME,
     SOL_PROMPT_FILE_NAME,
@@ -126,6 +128,12 @@ import {
     resolveFaultPhaseFromEnvironment,
     runWithInstallTransaction,
 } from './install-transaction.mjs';
+import { findShadowingGlobalInstall, shadowingGlobalAdvice } from './global-install-shadow.mjs';
+import {
+    addOpenTasksGateToProfiles,
+    otherProfileSettingsPaths,
+    removeOpenTasksGateFromProfiles,
+} from './profile-stop-gate.mjs';
 import { pythonExecutableProbeCommand } from './python-probe.mjs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -443,16 +451,28 @@ export function installPstackPluginForHosts() {
     });
 }
 
+/** Side steps that need the user, repeated at the end of the run so none scrolls past unseen. */
+const allActionNeededLines = [];
+
 function printPluginHostOutcomes(allSpecs, pluginOutcome) {
     for (const eachSpec of allSpecs) {
         for (const eachHost of pluginOutcome.hosts) {
-            console.log(eachHost.warning
-                ? `  ${eachSpec.label} (${eachHost.host}): ${eachHost.status} — ${eachHost.warning}`
-                : `  ${eachSpec.label} (${eachHost.host}): ${eachHost.status}`);
+            const outcomeLine = eachHost.warning
+                ? `${eachSpec.label} (${eachHost.host}): ${eachHost.status} — ${eachHost.warning}`
+                : `${eachSpec.label} (${eachHost.host}): ${eachHost.status}`;
+            console.log(`  ${outcomeLine}`);
+            if (eachHost.status === 'failed') allActionNeededLines.push(outcomeLine);
         }
     }
 }
 
+function printActionNeeded() {
+    if (allActionNeededLines.length === 0) return;
+    console.warn(`Action needed (${allActionNeededLines.length}):`);
+    for (const eachLine of allActionNeededLines) console.warn(`  - ${eachLine}`);
+    console.warn('');
+}
+
 function seedSubagentModelPolicy() {
     const policyDirectory = join(AGENTS_HOME, CURSOR_RULES_DIRECTORY_NAME);
     const policyPath = join(policyDirectory, SUBAGENT_MODEL_POLICY_FILE_NAME);
@@ -2680,17 +2700,33 @@ function install(selectedGroups, options = {}) {
     executeInstallPlan(plan);
 }
 
+/**
+ * List the profile settings paths that get the open-tasks Stop gate.
+ *
+ * Only an install into the main ~/.claude does this, because the gate entry
+ * names the main home's hook script.
+ *
+ * @param {string} mainSettingsPath
+ * @returns {string[]}
+ */
+function profileSettingsPathsForStopGate(mainSettingsPath) {
+    if (!pathsAreEquivalent(CLAUDE_HOME, join(homedir(), '.claude'))) return [];
+    return otherProfileSettingsPaths({ homeDirectory: homedir(), environment: process.env, mainSettingsPath });
+}
+
 function executeInstallPlan(plan) {
     const faultPhase = resolveFaultPhaseFromEnvironment(process.env);
     const snapshot = capturePriorInstallSnapshot({
         managedRoot: CLAUDE_HOME,
         manifestFilePath: MANIFEST_FILE,
         settingsPath: plan.settingsPath,
-        additionalSettingsPaths: [CODEX_HOOKS_CONFIGURATION_PATH],
+        additionalSettingsPaths: [CODEX_HOOKS_CONFIGURATION_PATH, ...profileSettingsPathsForStopGate(plan.settingsPath)],
         priorManifestFiles: [
             ...(plan.priorManifest.files || []),
             join(INSTALL_ROOT_RESOLUTION.codexHomeDirectory, 'AGENTS.md'),
             ...codexSolSettingSnapshotPaths(INSTALL_ROOT_RESOLUTION.codexHomeDirectory),
+            codexSolPromptPath(INSTALL_ROOT_RESOLUTION.codexHomeDirectory),
+            join(INSTALL_ROOT_RESOLUTION.codexHomeDirectory, SOL_PROMPT_FILE_NAME),
         ],
         journalParentDirectory: join(CLAUDE_HOME, TRANSACTION_JOURNAL_DIRECTORY_NAME),
     });
@@ -2737,6 +2773,16 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     const groupLabel = selectedGroups ? `groups: ${selectedGroups.join(', ')}` : 'all';
     console.log(`\nInstalling ${PACKAGE_NAME} (${groupLabel})...\n`);
     console.log(`  Python: ${pythonCommand}`);
+    const shadowingGlobal = findShadowingGlobalInstall({
+        packageName: PACKAGE_NAME,
+        packageRoot: PACKAGE_ROOT,
+        packageVersion: PACKAGE_VERSION,
+    });
+    if (shadowingGlobal) {
+        const shadowAdvice = shadowingGlobalAdvice(PACKAGE_NAME, shadowingGlobal, PACKAGE_VERSION);
+        console.warn(`  Warning: ${shadowAdvice}`);
+        allActionNeededLines.push(shadowAdvice);
+    }
     mkdirSync(CLAUDE_HOME, { recursive: true });
     const publishedPointerPaths = publishManagedLookupPointers();
 
@@ -2996,6 +3042,9 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         console.log(cursorOutcome.warning
             ? `  DeepStack (cursor): ${cursorOutcome.status} — ${cursorOutcome.warning}`
             : `  DeepStack (cursor): ${cursorOutcome.status}`);
+        if (cursorOutcome.status === 'failed') {
+            allActionNeededLines.push(`DeepStack (cursor): failed — ${cursorOutcome.warning}`);
+        }
     }
     const allRepositoryPluginSpecs = [
         USAGE_WRAPUP_PLUGIN_SPEC,
@@ -3028,9 +3077,14 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
         );
         if (deepenGuidancePath) allCodexGuidancePaths.push(deepenGuidancePath);
+        const solPromptPath = installCodexSolPrompt(
+            INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
+            join(PACKAGE_ROOT, SOL_PROMPT_DIRECTORY_NAME, SOL_PROMPT_FILE_NAME),
+        );
+        if (solPromptPath) allCodexGuidancePaths.push(solPromptPath);
         const solSettingPath = writeCodexSolSetting(
             INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
-            join(CLAUDE_HOME, SOL_PROMPT_DIRECTORY_NAME, SOL_PROMPT_FILE_NAME),
+            codexSolPromptPath(INSTALL_ROOT_RESOLUTION.codexHomeDirectory),
         );
         if (solSettingPath) {
             allCodexGuidancePaths.push(solSettingPath);
@@ -3151,6 +3205,16 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     for (const eachLine of describeProfileSettingsOutcome(mergeOutcome, false)) {
         console.log(`  Profile settings: ${eachLine}`);
     }
+    for (const eachOutcome of addOpenTasksGateToProfiles({
+        mainSettingsPath: join(CLAUDE_HOME, SETTINGS_FILE_NAME),
+        claudeHome: CLAUDE_HOME,
+        allProfileSettingsPaths: profileSettingsPathsForStopGate(join(CLAUDE_HOME, SETTINGS_FILE_NAME)),
+        homeDirectory: homedir(),
+    })) {
+        if (eachOutcome.additions.length > 0) {
+            console.log(`  Profile settings: open-tasks Stop gate added to ${eachOutcome.settingsPath}`);
+        }
+    }
 
     const agentsHubSource = join(PACKAGE_ROOT, 'AGENTS.md');
     if (existsSync(agentsHubSource)) {
@@ -3248,6 +3312,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         console.log(`  hooks: ${summary.hookFiles.created + summary.hookFiles.updated} files, ${summary.hookGroups} groups in settings.json`);
     }
     console.log(`  python: ${pythonCommand}\n`);
+    printActionNeeded();
 }
 
 function normalizePathForComparison(rawPath) {
@@ -3431,6 +3496,12 @@ function executeUninstallPlan(plan, helpers = {}) {
             writeFileSync(plan.settingsPath, JSON.stringify(settings, null, 4) + '\n');
         }
     }
+    for (const eachChangedPath of removeOpenTasksGateFromProfiles({
+        claudeHome: CLAUDE_HOME,
+        allProfileSettingsPaths: profileSettingsPathsForStopGate(plan.settingsPath),
+    })) {
+        console.log(`  Profile settings: open-tasks Stop gate removed from ${eachChangedPath}`);
+    }
     if (!codexRoutingHookExists()) {
         pruneManagedHooksFromHostConfiguration(CODEX_HOOKS_CONFIGURATION_PATH, 2);
     }
@@ -3489,11 +3560,13 @@ function uninstall() {
         managedRoot: CLAUDE_HOME,
         manifestFilePath: MANIFEST_FILE,
         settingsPath: plan.settingsPath,
-        additionalSettingsPaths: [CODEX_HOOKS_CONFIGURATION_PATH],
+        additionalSettingsPaths: [CODEX_HOOKS_CONFIGURATION_PATH, ...profileSettingsPathsForStopGate(plan.settingsPath)],
         priorManifestFiles: [
             ...plan.removableFiles,
             join(INSTALL_ROOT_RESOLUTION.codexHomeDirectory, 'AGENTS.md'),
             ...codexSolSettingSnapshotPaths(INSTALL_ROOT_RESOLUTION.codexHomeDirectory),
+            codexSolPromptPath(INSTALL_ROOT_RESOLUTION.codexHomeDirectory),
+            join(INSTALL_ROOT_RESOLUTION.codexHomeDirectory, SOL_PROMPT_FILE_NAME),
         ],
         journalParentDirectory: join(CLAUDE_HOME, TRANSACTION_JOURNAL_DIRECTORY_NAME),
     });

package/bin/install.test.mjs

@@ -3633,3 +3633,96 @@ test('a full install clears a retired session-continuity registration from every
         );
     }
 });
+
+function installWithGlobalPrefix(context, globalPrefix) {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cde-action-needed-'));
+    context.after(() => rmSync(homeDirectory, { recursive: true, force: true }));
+    return spawnSync(process.execPath, [join(dirname(fileURLToPath(import.meta.url)), 'install.mjs')], {
+        cwd: dirname(dirname(fileURLToPath(import.meta.url))),
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            CLAUDE_CONFIG_DIR: undefined,
+            LLM_SETTINGS_PROFILES_ROOT: undefined,
+            CLAUDE_DEV_ENV_INSTALL_FAULT: undefined,
+            CDE_INSTALL_PSTACK: '0',
+            CDE_INSTALL_DEEPSTACK: '0',
+            CDE_INSTALL_USAGE_WRAPUP: '0',
+            CDE_INSTALL_SUBAGENT_MODELS: '0',
+            CDE_INSTALL_DEEPEN_FIRST_PROMPT: '0',
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            APPDATA: join(homeDirectory, 'AppData', 'Roaming'),
+            CODEX_HOME: join(homeDirectory, '.codex'),
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+            TEMP: homeDirectory,
+            TMP: homeDirectory,
+            npm_config_prefix: undefined,
+            npm_config_global_prefix: globalPrefix ?? join(homeDirectory, 'no-global-prefix'),
+        },
+    });
+}
+
+test('install ends with an Action needed block naming an older global copy that shadows npx', (context) => {
+    const globalPrefix = mkdtempSync(join(tmpdir(), 'cde-global-prefix-'));
+    context.after(() => rmSync(globalPrefix, { recursive: true, force: true }));
+    const globalPackage = process.platform === 'win32'
+        ? join(globalPrefix, 'node_modules', 'claude-dev-env')
+        : join(globalPrefix, 'lib', 'node_modules', 'claude-dev-env');
+    mkdirSync(globalPackage, { recursive: true });
+    writeFileSync(join(globalPackage, 'package.json'), JSON.stringify({ name: 'claude-dev-env', version: '0.0.1' }));
+
+    const result = installWithGlobalPrefix(context, globalPrefix);
+
+    assert.equal(result.status, 0, result.stderr);
+    const actionIndex = result.stderr.lastIndexOf('Action needed (1):');
+    assert.ok(actionIndex >= 0, result.stderr);
+    assert.match(result.stderr.slice(actionIndex), /claude-dev-env 0\.0\.1/);
+    assert.match(result.stderr.slice(actionIndex), /npm uninstall -g claude-dev-env/);
+});
+
+test('install prints no Action needed block when every side step finished', (context) => {
+    const result = installWithGlobalPrefix(context, null);
+
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stderr.includes('Action needed'), false, result.stderr);
+});
+
+test('install adds the open-tasks Stop gate to every profile with its own settings.json, and uninstall removes it', (context) => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cde-profile-gate-install-'));
+    context.after(() => rmSync(homeDirectory, { recursive: true, force: true }));
+    const profileSettingsPath = join(homeDirectory, '.claude-profiles', 'prefs-only', 'settings.json');
+    mkdirSync(dirname(profileSettingsPath), { recursive: true });
+    writeFileSync(profileSettingsPath, JSON.stringify({ outputStyle: 'plain' }, null, 4));
+    const runInstaller = (argumentsList) => spawnSync(process.execPath, [join(dirname(fileURLToPath(import.meta.url)), 'install.mjs'), ...argumentsList], {
+        cwd: dirname(dirname(fileURLToPath(import.meta.url))),
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            CLAUDE_CONFIG_DIR: undefined,
+            LLM_SETTINGS_PROFILES_ROOT: undefined,
+            CLAUDE_DEV_ENV_INSTALL_FAULT: undefined,
+            CDE_INSTALL_PSTACK: '0',
+            CDE_INSTALL_DEEPSTACK: '0',
+            CDE_INSTALL_USAGE_WRAPUP: '0',
+            CDE_INSTALL_SUBAGENT_MODELS: '0',
+            CDE_INSTALL_DEEPEN_FIRST_PROMPT: '0',
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            CODEX_HOME: join(homeDirectory, '.codex'),
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+            TEMP: homeDirectory,
+            TMP: homeDirectory,
+        },
+    });
+    const profileStopCommands = () => (JSON.parse(readFileSync(profileSettingsPath, 'utf8')).hooks?.Stop ?? [])
+        .flatMap((eachGroup) => eachGroup.hooks.map((eachHook) => eachHook.command));
+
+    const installation = runInstaller([]);
+    assert.equal(installation.status, 0, installation.stderr);
+    assert.equal(profileStopCommands().filter((eachCommand) => eachCommand.includes('open_tasks_stop_gate.py')).length, 1);
+
+    const uninstallation = runInstaller(['--uninstall']);
+    assert.equal(uninstallation.status, 0, uninstallation.stderr);
+    assert.deepEqual(JSON.parse(readFileSync(profileSettingsPath, 'utf8')), { outputStyle: 'plain' });
+});