@opengsd/gsd-core 1.13.0 → 1.15.0

package/gsd-core/bin/lib/runtime-hooks-surface.cjs

@@ -38,7 +38,7 @@ const commonjs_marker_cjs_1 = require("./commonjs-marker.cjs");
 const imperative_hook_bus_cjs_1 = require("./host-integration-adapters/imperative-hook-bus.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const shellCmdProjection = require("./shell-command-projection.cjs");
-const { isManagedHookBasename, isManagedHookCommand, projectLegacySettingsHookCommand, projectManagedHookCommand, projectPortableHookBaseDir, projectCodexHookTomlCommand, shellHookOmitsBashRunner, escapeTomlDoubleQuotedString, escapePosixDoubleQuoted, } = shellCmdProjection;
+const { isManagedHookBasename, isManagedHookCommand, projectLegacySettingsHookCommand, projectManagedHookCommand, projectPortableHookBaseDir, projectCodexHookTomlCommand, shellHookOmitsBashRunner, escapeTomlDoubleQuotedString, escapePosixDoubleQuoted, resolveExecutableBinary, } = shellCmdProjection;
 // ---------------------------------------------------------------------------
 // Terminal color constants (mirrors install.js for console output parity)
 // ---------------------------------------------------------------------------
@@ -459,9 +459,18 @@ function normalizeNodePath(execPath, opts) {
     // survives the upgrade. Derive <prefix> from the path itself (more reliable
     // than HOMEBREW_PREFIX env — the path IS the install location) so every layout
     // is covered by one branch instead of one per known prefix (#2185).
+    //
+    // #4137: rewrite only when the symlink exists; otherwise fall through to the
+    // raw execPath, exactly like the mise and volta branches. A keg-only/versioned
+    // formula (node@24 installed but never `brew link`ed) has no <prefix>/bin/node
+    // at all, so the unconditional rewrite handed every managed hook a path that
+    // fails at invocation — a rewrite must never turn a working keg path into an
+    // immediately broken one.
     const homebrewMatch = normalizedForMatch.match(/^(.+)\/Cellar\/node(@\d+)?\/[^/]+\/bin\/node(\.exe)?$/i);
     if (homebrewMatch) {
-        return `${homebrewMatch[1]}/bin/node${homebrewMatch[3] || ''}`;
+        const homebrewStable = `${homebrewMatch[1]}/bin/node${homebrewMatch[3] || ''}`;
+        if (existsSync(homebrewStable))
+            return homebrewStable;
     }
     // mise pins a concrete node version at <data>/installs/node/<ver>/bin/node
     // (Windows: <data>/installs/node/<ver>/node.exe). Node realpaths
@@ -567,7 +576,7 @@ function buildBakedNodeToken(opts) {
  * guarantee), ahead of `command -v node` and the well-known fallback list.
  */
 const NODE_RUNNER_RESOLVER_HOOK = 'gsd-node-runner.sh';
-function resolveBashRunner(opts) {
+function resolveBashExecutable(opts) {
     const platform = (opts && opts.platform) || process.platform;
     if (platform !== 'win32')
         return 'bash';
@@ -585,12 +594,19 @@ function resolveBashRunner(opts) {
         candidates.push(node_path_1.default.win32.join(env.SystemDrive, 'Program Files (x86)', 'Git', 'bin', 'bash.exe'));
     }
     for (const candidate of candidates) {
-        if (candidate && exists(candidate)) {
-            return JSON.stringify(shellCmdProjection.posixNormalize(candidate));
-        }
+        if (candidate && exists(candidate))
+            return shellCmdProjection.posixNormalize(candidate);
     }
     return null;
 }
+function resolveBashRunner(opts) {
+    const executable = resolveBashExecutable(opts);
+    if (executable === null)
+        return null;
+    return ((opts && opts.platform) || process.platform) === 'win32'
+        ? JSON.stringify(executable)
+        : executable;
+}
 // #3662 — recognize the two runtime-resolving command shapes the installer
 // emits, so the rewriter never churns (or un-does) an entry that already
 // works in every environment sharing the config root.
@@ -802,16 +818,52 @@ function rewriteLegacyCodexHookBlock(content, absoluteRunner, opts) {
     });
     return { content: updated, changed };
 }
+function _installEngineSymlinkGuard() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const mod = require('./install-engine.cjs');
+    return mod;
+}
 function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
     const hooksJsonPath = node_path_1.default.join(targetDir, 'hooks.json');
     const managedCommand = typeof opts.managedCommand === 'string' ? opts.managedCommand : null;
     const commandWindows = typeof opts.commandWindows === 'string' ? opts.commandWindows : null;
     const matcher = typeof opts.matcher === 'string' ? opts.matcher : undefined;
     const timeout = typeof opts.timeout === 'number' ? opts.timeout : undefined;
+    // #2586 Major 2: every Codex hooks.json writer funnels through this one
+    // function, and atomicWriteFileSync's final step is a rename(2) onto
+    // `hooksJsonPath` — which, when that path is a symlink, REPLACES the
+    // symlink with a plain file rather than writing through it. Refuse (with
+    // the same GSD_ALLOW_SYMLINKED_DEST opt-in every other install call site
+    // honors) before reading or writing, so a symlinked hooks.json is neither
+    // silently destroyed nor left the caller no escape hatch.
+    const symlinkGuard = _installEngineSymlinkGuard();
+    // The path this function actually reads/writes. Defaults to the nominal
+    // hooks.json path; reassigned below to the symlink's real target when the
+    // opt-in is active, so the write lands on the file the user's symlink
+    // points at instead of clobbering the symlink itself (see note below).
+    let effectiveHooksJsonPath = hooksJsonPath;
+    if (node_fs_1.default.existsSync(hooksJsonPath) && node_fs_1.default.lstatSync(hooksJsonPath).isSymbolicLink()) {
+        if (symlinkGuard.hasExistingSymlinkBetween(targetDir, hooksJsonPath, {
+            allowOptInFollow: symlinkGuard.isSymlinkedDestOptIn(),
+        })) {
+            throw new Error(`hooks.json at "${hooksJsonPath}" contains a symlink the install root "${targetDir}" does not trust — ` +
+                'refusing to read or write it. If this is an intentional user-owned symlink layout, re-run with ' +
+                'GSD_ALLOW_SYMLINKED_DEST=1.');
+        }
+        // hasExistingSymlinkBetween returned false only because the opt-in is
+        // active (a symlinked leaf always trips it otherwise) — so this IS a
+        // symlink and we are cleared to follow it. atomicWriteFileSync's final
+        // step is a rename(2) onto its target, which REPLACES an existing
+        // symlink at that path rather than writing through it; resolving to the
+        // real path here makes the read AND the write operate on the symlink's
+        // target, leaving the symlink itself untouched, matching what "follow"
+        // is supposed to mean.
+        effectiveHooksJsonPath = node_fs_1.default.realpathSync(hooksJsonPath);
+    }
     let parsed = {};
     let currentContent = null;
-    if (node_fs_1.default.existsSync(hooksJsonPath)) {
-        const raw = node_fs_1.default.readFileSync(hooksJsonPath, 'utf8');
+    if (node_fs_1.default.existsSync(effectiveHooksJsonPath)) {
+        const raw = node_fs_1.default.readFileSync(effectiveHooksJsonPath, 'utf8');
         currentContent = raw;
         if (raw.trim()) {
             try {
@@ -845,6 +897,12 @@ function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
     }
     parsed['hooks'] = hookTable;
     const eventEntries = Array.isArray(hookTable[eventName]) ? hookTable[eventName] : [];
+    // Minor 5 (#2586 review): an event key the user already had, already
+    // holding an empty array, must survive removal as an empty array — not be
+    // deleted outright. Deleting is only correct when OUR removal is what
+    // emptied a previously non-empty array. Tracked before the loop below can
+    // mutate anything.
+    const wasArrayEmpty = Array.isArray(hookTable[eventName]) && eventEntries.length === 0;
     let removedLegacy = false;
     const sanitizedEntries = [];
     for (const entry of eventEntries) {
@@ -886,6 +944,11 @@ function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
     if (sanitizedEntries.length > 0) {
         hookTable[eventName] = sanitizedEntries;
     }
+    else if (wasArrayEmpty) {
+        // Nothing of ours was ever here to remove — preserve the user's own
+        // empty array exactly as found (Minor 5).
+        hookTable[eventName] = [];
+    }
     else {
         delete hookTable[eventName];
     }
@@ -898,23 +961,25 @@ function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
     const changed = currentContent !== nextContent;
     const shouldWrite = changed && (currentContent !== null || Object.keys(parsed).length > 0);
     if (shouldWrite) {
-        atomicWriteFileSync(hooksJsonPath, nextContent, 'utf8');
+        atomicWriteFileSync(effectiveHooksJsonPath, nextContent, 'utf8');
     }
     return { changed: changed || removedLegacy, wrote: shouldWrite, path: hooksJsonPath };
 }
 function reconcileCodexHooksJsonSessionStart(targetDir, opts = {}) {
     return reconcileCodexHooksJsonEvent(targetDir, 'SessionStart', opts);
 }
-function buildCodexHookWindowsShimIR(scriptAbsPath, absoluteRunnerToken) {
-    if (!absoluteRunnerToken)
-        return null;
-    let interpreter;
+function parseAbsoluteRunnerToken(absoluteRunnerToken) {
     try {
-        interpreter = JSON.parse(absoluteRunnerToken);
+        return JSON.parse(absoluteRunnerToken);
     }
     catch {
-        interpreter = absoluteRunnerToken;
+        return absoluteRunnerToken;
     }
+}
+function buildCodexHookWindowsShimIR(scriptAbsPath, absoluteRunnerToken) {
+    if (!absoluteRunnerToken)
+        return null;
+    const interpreter = parseAbsoluteRunnerToken(absoluteRunnerToken);
     const targetAbs = shellCmdProjection.posixNormalize(scriptAbsPath);
     const scriptQuoted = JSON.stringify(targetAbs);
     const cmdPath = scriptAbsPath.replace(/\.js$/, '.cmd');
@@ -939,6 +1004,7 @@ function ensureCodexHooksJsonSessionStart(targetDir, opts = {}) {
         return { changed: false, wrote: false, path: hooksJsonPath };
     const scriptPath = shellCmdProjection.posixNormalize(node_path_1.default.resolve(targetDir, 'hooks', 'gsd-check-update.js'));
     const cmdShimPath = scriptPath.replace(/\.js$/, '.cmd');
+    const configuredEntrypoints = [];
     let managedCommand;
     if (platform === 'win32') {
         const shimIR = buildCodexHookWindowsShimIR(scriptPath, absoluteRunner);
@@ -955,6 +1021,7 @@ function ensureCodexHooksJsonSessionStart(targetDir, opts = {}) {
             return { changed: false, wrote: false, path: hooksJsonPath };
         }
         managedCommand = shimIR.hookCommand;
+        configuredEntrypoints.push({ runtime: 'codex', configPath: hooksJsonPath, scriptPath: shimIR.cmdPath, platform, selfExecutable: true }, { runtime: 'codex', configPath: hooksJsonPath, scriptPath, interpreterCandidates: [parseAbsoluteRunnerToken(absoluteRunner)], platform });
     }
     else {
         managedCommand = projectManagedHookCommand({
@@ -963,13 +1030,23 @@ function ensureCodexHooksJsonSessionStart(targetDir, opts = {}) {
             runtime: 'codex',
             platform,
         }) ?? undefined;
+        if (managedCommand) {
+            configuredEntrypoints.push({
+                runtime: 'codex',
+                configPath: hooksJsonPath,
+                scriptPath,
+                interpreterCandidates: [parseAbsoluteRunnerToken(absoluteRunner)],
+                platform,
+            });
+        }
     }
     if (!managedCommand)
         return { changed: false, wrote: false, path: hooksJsonPath };
     const commandWindows = platform === 'win32'
         ? JSON.stringify(shellCmdProjection.posixNormalize(cmdShimPath))
         : undefined;
-    return reconcileCodexHooksJsonSessionStart(targetDir, { managedCommand, commandWindows });
+    const result = reconcileCodexHooksJsonSessionStart(targetDir, { managedCommand, commandWindows });
+    return { ...result, configuredEntrypoints };
 }
 function ensureCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
     const platform = opts.platform || process.platform;
@@ -1015,6 +1092,186 @@ function removeCodexHooksJsonEvent(targetDir, eventName) {
 function removeCodexHooksJsonSessionStart(targetDir) {
     return reconcileCodexHooksJsonSessionStart(targetDir, { managedCommand: null });
 }
+// Literal, version-stable markers every shipped gsd-context-monitor.js
+// carries. Stable across the {{GSD_VERSION}} and runtime-path substitutions
+// the Codex copy step applies (#2586 design doc "Ownership check" — a raw
+// content hash would differ per runtime/version by construction, so a marker
+// check is used instead of manifest-membership, which has a bootstrap gap on
+// the exact case that matters most: a pre-#2586 install's manifest never
+// recorded this file at all).
+const CODEX_CONTEXT_MONITOR_OWNERSHIP_MARKERS = [
+    '#!/usr/bin/env node',
+    '// gsd-hook-version:',
+    '// Context Monitor - PostToolUse/AfterTool hook',
+];
+function isGsdOwnedCodexContextMonitorScript(filePath) {
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    // The .cmd shim (buildCodexHookWindowsShimIR) is a tiny generated batch
+    // wrapper, not the JS file itself — it never carries the JS markers above,
+    // so it gets its own narrower, still-specific signature: the exact
+    // "@ECHO OFF" / "@SETLOCAL" preamble the shim generator emits, invoking a
+    // script path that ends in gsd-context-monitor.js.
+    if (filePath.endsWith('.cmd')) {
+        return content.startsWith('@ECHO OFF') && content.includes('@SETLOCAL')
+            && /gsd-context-monitor\.js/.test(content);
+    }
+    return CODEX_CONTEXT_MONITOR_OWNERSHIP_MARKERS.every((marker) => content.includes(marker));
+}
+/**
+ * Scan every event in hooks.json for a surviving reference to the
+ * context-monitor script or its Windows .cmd shim, by basename — not scoped
+ * to CODEX_EXTENDED_HOOK_EVENTS, so a user who hand-registered it under an
+ * unrelated event key is still detected as "referenced" and the script is
+ * preserved.
+ */
+function hooksJsonReferencesCodexContextMonitor(targetDir) {
+    const hooksJsonPath = node_path_1.default.join(targetDir, 'hooks.json');
+    if (!node_fs_1.default.existsSync(hooksJsonPath))
+        return false;
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(hooksJsonPath, 'utf8');
+    }
+    catch {
+        return true; // unreadable — conservatively assume referenced, never delete
+    }
+    if (!raw.trim())
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return true; // unparseable — conservatively assume referenced
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return false;
+    const hooks = parsed['hooks'];
+    const table = hooks && typeof hooks === 'object' && !Array.isArray(hooks)
+        ? hooks
+        : parsed;
+    for (const key of Object.keys(table)) {
+        const entries = table[key];
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            const entryHooks = entry['hooks'];
+            const hookList = Array.isArray(entryHooks) ? entryHooks : [entry];
+            for (const hook of hookList) {
+                if (!hook || typeof hook !== 'object')
+                    continue;
+                const values = [
+                    hook['command'],
+                    hook['commandWindows'],
+                ];
+                for (const value of values) {
+                    if (typeof value === 'string' && /gsd-context-monitor(\.js|\.cmd)?/.test(value)) {
+                        return true;
+                    }
+                }
+            }
+        }
+    }
+    return false;
+}
+/**
+ * #2586 must-have #4/#8: after hooks.json registrations for
+ * CODEX_EXTENDED_HOOK_EVENTS have been reconciled away (by the caller, via
+ * removeCodexHooksJsonEvent), delete `hooks/gsd-context-monitor.js` and its
+ * `.cmd` shim ONLY when (a) no surviving hooks.json registration under ANY
+ * event still references either basename, and (b) the on-disk file carries
+ * GSD's own ownership markers (a user's hand-edited or unrelated file at that
+ * path is left alone). Each file is deleted independently — a failure
+ * deleting one is reported as a warning and never rolls back the (already
+ * safe, already-written) hooks.json deregistration the caller performed
+ * first.
+ */
+function cleanupOrphanedCodexContextMonitorScript(targetDir) {
+    const result = { deleted: [], warnings: [], stillReferenced: false };
+    if (hooksJsonReferencesCodexContextMonitor(targetDir)) {
+        result.stillReferenced = true;
+        return result;
+    }
+    const candidates = [
+        node_path_1.default.join(targetDir, 'hooks', 'gsd-context-monitor.js'),
+        node_path_1.default.join(targetDir, 'hooks', 'gsd-context-monitor.cmd'),
+    ];
+    for (const candidate of candidates) {
+        if (!node_fs_1.default.existsSync(candidate))
+            continue;
+        if (!isGsdOwnedCodexContextMonitorScript(candidate))
+            continue;
+        try {
+            node_fs_1.default.unlinkSync(candidate);
+            result.deleted.push(candidate);
+        }
+        catch (err) {
+            result.warnings.push({
+                path: candidate,
+                reason: err && err.message ? err.message : String(err),
+            });
+        }
+    }
+    return result;
+}
+function configuredEntrypointsForHook(configDir, hookName, opts) {
+    const platform = opts.platform || process.platform;
+    const runtime = opts.runtime || 'generic';
+    const configPath = opts.configPath || configDir;
+    const target = {
+        runtime,
+        configPath,
+        scriptPath: node_path_1.default.join(configDir, 'hooks', hookName),
+        platform,
+    };
+    const isShellHook = hookName.endsWith('.sh');
+    if (shellHookOmitsBashRunner({ platform, runtime, isShellHook }))
+        return [{ ...target, selfExecutable: true }];
+    const bash = resolveBashExecutable(opts);
+    if (isShellHook) {
+        // An unresolved bash must still surface as an interpreterCandidates entry
+        // (the literal token, same as the portableHooks runner below) so
+        // validateConfiguredEntrypoints reports 'unresolved-interpreter' instead
+        // of silently skipping the check because the field is absent.
+        return [{ ...target, interpreterCandidates: [bash === null ? 'bash' : bash] }];
+    }
+    // #4249: check the SAME stable alias buildNodeRunnerChainToken bakes as its
+    // first candidate (normalizeNodePath rewrites a version-manager shim like
+    // fnm/nvm/mise/volta into its persistent path), not the raw, currently-
+    // running process.execPath — which always trivially resolves regardless of
+    // whether the alias actually baked into the persisted command still does.
+    const nodeCandidates = [
+        normalizeNodePath(opts.execPath || process.execPath, opts),
+        'node',
+        '/usr/local/bin/node',
+        '/usr/bin/node',
+    ].filter((candidate) => Boolean(candidate));
+    if (!opts.portableHooks) {
+        return [{ ...target, interpreterCandidates: nodeCandidates }];
+    }
+    const runner = {
+        runtime,
+        configPath,
+        scriptPath: node_path_1.default.join(configDir, 'hooks', NODE_RUNNER_RESOLVER_HOOK),
+        interpreterCandidates: bash === null ? ['bash'] : [bash],
+        platform,
+    };
+    return [runner, { ...target, interpreterCandidates: nodeCandidates }];
+}
+function recordConfiguredHookCommand(command, configDir, hookName, opts) {
+    if (command && opts.configuredEntrypoints) {
+        opts.configuredEntrypoints.push(...configuredEntrypointsForHook(configDir, hookName, opts).map(entry => ({ ...entry, command })));
+    }
+    return command;
+}
 function buildHookCommand(configDir, hookName, opts) {
     if (!opts)
         opts = {};
@@ -1022,44 +1279,56 @@ function buildHookCommand(configDir, hookName, opts) {
     const runtime = opts.runtime || 'generic';
     const hookShell = opts.hookShell;
     const isShellHook = hookName.endsWith('.sh');
+    const track = (command) => recordConfiguredHookCommand(command, configDir, hookName, opts);
     if (shellHookOmitsBashRunner({ platform, runtime, isShellHook })) {
         if (opts.portableHooks) {
             const portableBaseDir = projectPortableHookBaseDir({
                 configDir,
                 homeDir: node_os_1.default.homedir(),
             });
-            return JSON.stringify(`${portableBaseDir}/hooks/${hookName}`);
+            return track(JSON.stringify(`${portableBaseDir}/hooks/${hookName}`));
         }
-        return JSON.stringify(shellCmdProjection.posixNormalize(configDir) + '/hooks/' + hookName);
+        return track(JSON.stringify(shellCmdProjection.posixNormalize(configDir) + '/hooks/' + hookName));
     }
     // .sh hooks keep the pre-#3662 shape everywhere: the bash runner resolves
     // at install time like today, and `bash` itself is a PATH-stable binary
     // (the absolute Git-Bash discovery covers win32 — #580/#3393).
     if (isShellHook) {
         const runner = resolveBashRunner(opts);
-        if (runner === null)
+        if (runner === null) {
+            // #4249 (antigravity review): this early return skips `track()` below,
+            // so an unresolved bash on win32 (no Git Bash found) previously left
+            // this hook silently unregistered with nothing for
+            // validateConfiguredEntrypoints to reject — configuredEntrypointsForHook's
+            // own 'unresolved bash must still surface' comment describes intent this
+            // return never reached. Push the entry directly (no `command`, since
+            // none was ever built) so the gate actually sees it.
+            if (opts.configuredEntrypoints) {
+                opts.configuredEntrypoints.push(...configuredEntrypointsForHook(configDir, hookName, opts));
+            }
             return null;
+        }
         if (opts.portableHooks) {
             const portableBaseDir = projectPortableHookBaseDir({
                 configDir,
                 homeDir: node_os_1.default.homedir(),
             });
-            return projectManagedHookCommand({
+            return track(projectManagedHookCommand({
                 absoluteRunner: runner,
                 scriptPath: `${portableBaseDir}/hooks/${hookName}`,
                 runtime: opts.runtime || 'generic',
                 platform,
                 hookShell,
-            });
+            }));
         }
         const hooksPath = shellCmdProjection.posixNormalize(configDir) + '/hooks/' + hookName;
-        return projectManagedHookCommand({
+        return track(projectManagedHookCommand({
             absoluteRunner: runner,
             scriptPath: hooksPath,
             runtime,
             platform,
             hookShell,
-        });
+        }));
     }
     // JS hooks (#3662): the node runner is resolved at hook-fire time, never
     // baked as a bare absolute path — an install-environment absolute path is
@@ -1082,7 +1351,7 @@ function buildHookCommand(configDir, hookName, opts) {
         // Absolute Git-Bash discovery on win32 when available (#580); `bash` on
         // PATH otherwise — the same assumption .sh hooks already make.
         const resolverRunner = resolveBashRunner(opts) || 'bash';
-        return shellCmdProjection.projectShellCommandText({
+        return track(shellCmdProjection.projectShellCommandText({
             runnerToken: resolverRunner,
             argTokens: [
                 JSON.stringify(`${portableBaseDir}/hooks/${NODE_RUNNER_RESOLVER_HOOK}`),
@@ -1092,19 +1361,19 @@ function buildHookCommand(configDir, hookName, opts) {
             runtime,
             platform,
             hookShell,
-        });
+        }));
     }
     const chainRunner = buildNodeRunnerChainToken(opts);
     if (chainRunner === null)
         return null;
     const hooksPath = shellCmdProjection.posixNormalize(configDir) + '/hooks/' + hookName;
-    return shellCmdProjection.projectShellCommandText({
+    return track(shellCmdProjection.projectShellCommandText({
         runnerToken: chainRunner,
         argTokens: [JSON.stringify(hooksPath)],
         runtime,
         platform,
         hookShell,
-    });
+    }));
 }
 // ---------------------------------------------------------------------------
 // Cline helpers
@@ -1205,6 +1474,7 @@ function mergeGsdAgentsMd(filePath, gsdContent) {
 // ---------------------------------------------------------------------------
 function writeClineArtifacts(targetDir, isGlobalInstall) {
     const written = [];
+    const configuredEntrypoints = [];
     const clinerulesDir = node_path_1.default.join(targetDir, '.clinerules');
     try {
         if (node_fs_1.default.existsSync(clinerulesDir)) {
@@ -1230,6 +1500,20 @@ function writeClineArtifacts(targetDir, isGlobalInstall) {
     catch { /* Windows: hooks unsupported anyway */ }
     written.push('.clinerules/hooks/PreToolUse');
     console.log(`  ${green}✓${reset} Wrote .clinerules/hooks/PreToolUse`);
+    // #4249 (CodeRabbit): Cline invokes this file directly via its own
+    // `#!/usr/bin/env node` shebang — a hybrid case. The script itself still
+    // needs the execute bit (selfExecutable), but unlike GSD's other JS hooks
+    // (which bake an absolute, install-time-resolved node path specifically to
+    // avoid this) its interpreter is looked up on PATH by `env` at hook-fire
+    // time, so `node` must also resolve or the hook can never run.
+    configuredEntrypoints.push({
+        runtime: 'cline',
+        configPath: hookPath,
+        scriptPath: hookPath,
+        interpreterCandidates: ['node'],
+        selfExecutable: true,
+        platform: process.platform,
+    });
     if (isGlobalInstall) {
         try {
             const agentsPath = node_path_1.default.join(node_os_1.default.homedir(), '.agents', 'AGENTS.md');
@@ -1240,7 +1524,7 @@ function writeClineArtifacts(targetDir, isGlobalInstall) {
             console.warn(`  ${yellow}⚠${reset} Could not write ~/.agents/AGENTS.md: ${err.message}`);
         }
     }
-    return written;
+    return { written, configuredEntrypoints };
 }
 // ---------------------------------------------------------------------------
 // Cursor hook functions
@@ -1491,7 +1775,13 @@ function writeCursorHooksJson(targetDir, src, opts) {
     if (installedScripts.size > 0) {
         ensureCommonJsMarker(hooksDir);
     }
-    const hookOpts = { runtime: 'cursor', platform: opts.platform || process.platform };
+    const configuredEntrypoints = [];
+    const hookOpts = {
+        runtime: 'cursor',
+        platform: opts.platform || process.platform,
+        configPath: node_path_1.default.join(targetDir, 'hooks.json'),
+        configuredEntrypoints,
+    };
     const commands = {};
     for (const ev of events) {
         const script = imperative_hook_bus_cjs_1.CURSOR_EVENT_SCRIPT_MAP[ev];
@@ -1505,7 +1795,7 @@ function writeCursorHooksJson(targetDir, src, opts) {
     const managedEntries = (0, imperative_hook_bus_cjs_1.buildHookBusEntries)(events, commands);
     const hooksJsonPath = node_path_1.default.join(targetDir, 'hooks.json');
     const result = reconcileCursorHooksJson(hooksJsonPath, managedEntries);
-    return { hooksJsonPath, changed: result.changed };
+    return { hooksJsonPath, changed: result.changed, configuredEntrypoints };
 }
 function removeCursorHooksJson(targetDir) {
     const hooksJsonPath = node_path_1.default.join(targetDir, 'hooks.json');
@@ -1710,7 +2000,13 @@ function writeWindsurfHooksJson(targetDir, src, opts) {
     if (installedScripts.size > 0) {
         ensureCommonJsMarker(hooksDir);
     }
-    const hookOpts = { runtime: 'windsurf', platform: opts.platform || process.platform };
+    const configuredEntrypoints = [];
+    const hookOpts = {
+        runtime: 'windsurf',
+        platform: opts.platform || process.platform,
+        configPath: node_path_1.default.join(targetDir, 'hooks.json'),
+        configuredEntrypoints,
+    };
     const commands = {};
     for (const ev of WINDSURF_HOOK_EVENTS) {
         const script = WINDSURF_EVENT_SCRIPT_MAP[ev];
@@ -1724,7 +2020,7 @@ function writeWindsurfHooksJson(targetDir, src, opts) {
     }
     const hooksJsonPath = node_path_1.default.join(targetDir, 'hooks.json');
     const result = reconcileWindsurfHooksJson(hooksJsonPath, managedEntries);
-    return { hooksJsonPath, changed: result.changed };
+    return { hooksJsonPath, changed: result.changed, configuredEntrypoints };
 }
 /**
  * Remove all GSD-managed Cascade hook entries from hooks.json. User-owned
@@ -2575,13 +2871,21 @@ function stripKimiHooksTomlBlock(content) {
  * touch the file's mtime for no reason.
  */
 function writeKimiHooksToml(configPath, targetDir, opts) {
+    const configuredEntrypoints = [];
+    const trackedOpts = {
+        hookOpts: {
+            ...opts.hookOpts,
+            configPath,
+            configuredEntrypoints,
+        },
+    };
     const existing = node_fs_1.default.existsSync(configPath) ? node_fs_1.default.readFileSync(configPath, 'utf8') : '';
     const stripped = stripKimiHooksTomlBlock(existing) ?? '';
-    const block = buildKimiHooksTomlBlock(targetDir, opts);
+    const block = buildKimiHooksTomlBlock(targetDir, trackedOpts);
     const entryCount = block ? (block.match(/\[\[hooks\]\]/g) || []).length : 0;
     if (!block) {
         if (stripped === existing)
-            return { changed: false, path: configPath, entryCount: 0 };
+            return { changed: false, path: configPath, entryCount: 0, configuredEntrypoints };
         if (stripped.trim() === '') {
             if (node_fs_1.default.existsSync(configPath))
                 node_fs_1.default.unlinkSync(configPath);
@@ -2590,15 +2894,15 @@ function writeKimiHooksToml(configPath, targetDir, opts) {
             node_fs_1.default.mkdirSync(node_path_1.default.dirname(configPath), { recursive: true });
             atomicWriteFileSync(configPath, stripped, 'utf8');
         }
-        return { changed: true, path: configPath, entryCount: 0 };
+        return { changed: true, path: configPath, entryCount: 0, configuredEntrypoints };
     }
     const separator = stripped.trim() === '' ? '' : (stripped.endsWith('\n') ? '\n' : '\n\n');
     const next = stripped.trim() === '' ? `${block}\n` : `${stripped}${separator}${block}\n`;
     if (next === existing)
-        return { changed: false, path: configPath, entryCount };
+        return { changed: false, path: configPath, entryCount, configuredEntrypoints };
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(configPath), { recursive: true });
     atomicWriteFileSync(configPath, next, 'utf8');
-    return { changed: true, path: configPath, entryCount };
+    return { changed: true, path: configPath, entryCount, configuredEntrypoints };
 }
 /**
  * Uninstall-time counterpart to writeKimiHooksToml: strips the GSD block and
@@ -2644,6 +2948,68 @@ function referencesHook(h, hookName) {
         (Array.isArray(args) && args.some(a => typeof a === 'string' && a.includes(hookName))) ||
         (typeof url === 'string' && url.includes(hookName));
 }
+function validateConfiguredEntrypoints(entries, deps = {}) {
+    const statSync = deps.statSync ?? node_fs_1.default.statSync;
+    const accessSync = deps.accessSync ?? node_fs_1.default.accessSync;
+    const resolve = deps.resolveExecutableBinary ?? resolveExecutableBinary;
+    const invalid = [];
+    for (const entry of entries) {
+        let scriptOk = false;
+        try {
+            scriptOk = statSync(entry.scriptPath).isFile();
+            if (!scriptOk) {
+                invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'script', path: entry.scriptPath, reason: 'wrong-file-type' });
+            }
+            else {
+                // #4249: statSync only needs search permission on the parent dirs, so
+                // it succeeds even for a chmod-000 file — the EACCES catch below
+                // never fires for that case. Read permission on the file itself must
+                // be checked explicitly: an interpreter opens the script directly,
+                // and even a self-executable shebang script is opened and read by
+                // its kernel-invoked interpreter, not just exec'd — X_OK alone does
+                // not prove it's readable.
+                try {
+                    accessSync(entry.scriptPath, node_fs_1.default.constants.R_OK);
+                }
+                catch {
+                    scriptOk = false;
+                    invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'script', path: entry.scriptPath, reason: 'unreadable' });
+                }
+            }
+        }
+        catch (statErr) {
+            // #4249 Nit: EACCES means a parent directory couldn't be searched —
+            // a real (if rare) permission problem, distinct from ENOENT's "missing".
+            // EPERM: Windows' equivalent permission-denied code for a directory a
+            // parent path couldn't be traversed into.
+            const code = statErr?.code;
+            const reason = code === 'EACCES' || code === 'EPERM' ? 'unreadable' : 'missing';
+            invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'script', path: entry.scriptPath, reason });
+        }
+        // #4249: selfExecutable is the sole source of truth for whether the OS
+        // execs scriptPath directly via its own shebang (set explicitly by every
+        // producer that needs it — a Windows-Claude .sh hook, Codex's Windows
+        // .cmd shim, Cline's hybrid `env node` hook — rather than inferred from
+        // the absence of interpreterCandidates, which Cline's hybrid case also
+        // carries). Skip on win32 like resolveExecutableBinary's own X_OK
+        // carve-out does: POSIX mode bits don't mean executable on Windows, and a
+        // real accessSync(X_OK) there would fail a .cmd shim under a test that
+        // simulates win32 on a POSIX runner (Node's own no-op only protects an
+        // actual Windows machine). Cline is the only producer where this runs.
+        if (scriptOk && entry.selfExecutable && (entry.platform ?? process.platform) !== 'win32') {
+            try {
+                accessSync(entry.scriptPath, node_fs_1.default.constants.X_OK);
+            }
+            catch {
+                invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'script', path: entry.scriptPath, reason: 'not-executable' });
+            }
+        }
+        if (entry.interpreterCandidates && !entry.interpreterCandidates.some(candidate => resolve(candidate, { platform: entry.platform, requireExecutable: true }) !== null)) {
+            invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'interpreter', path: entry.interpreterCandidates.join(' | '), reason: 'unresolved-interpreter' });
+        }
+    }
+    return invalid.length === 0 ? { ok: true } : { ok: false, invalid };
+}
 module.exports = {
     // Cline
     buildClineRulesBody,
@@ -2692,6 +3058,9 @@ module.exports = {
     removeCodexHooksJsonEvent,
     removeCodexHooksJsonSessionStart,
     buildCodexHookWindowsShimIR,
+    cleanupOrphanedCodexContextMonitorScript,
+    isGsdOwnedCodexContextMonitorScript,
+    hooksJsonReferencesCodexContextMonitor,
     // Codex TOML
     buildCodexHookBlock,
     rewriteLegacyCodexHookBlock,
@@ -2705,7 +3074,9 @@ module.exports = {
     // Shared
     stageTransitiveHookLibs,
     buildHookCommand,
+    recordConfiguredHookCommand,
     applySettingsJsonHooks,
+    validateConfiguredEntrypoints,
     referencesHook,
     rewriteLegacyManagedNodeHookCommands,
     reconcileManagedShellHookCommands,