@rudderhq/agent-runtime-utils 0.4.6-canary.8 → 0.5.0

package/dist/server-utils.test.js

@@ -2,13 +2,14 @@ import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { ensureLocalCliCredentialShimsInPath, ensureRudderCliInPath, loadAgentInstructionsPrefix, prepareAgentInstructionRuntimeContext, renderTemplate, resolveLocalOperatorHome, RUDDER_AGENT_HEARTBEAT_INSTRUCTION, RUDDER_AGENT_OPERATING_CONTRACT, runChildProcess, selectPromptTemplate, shouldIncludeRuntimeHeartbeatInstructions, syncLocalCliCredentialHomeEntries, } from "./server-utils.js";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanupLegacyRudderDocsManagedEntry, createOperatorInterruptAbortReason, ensureLocalCliCredentialShimsInPath, ensureRudderCliInPath, filterRudderDesiredSkillsForBrowserCapability, loadAgentInstructionsPrefix, prepareAgentInstructionRuntimeContext, renderTemplate, resolveDesktopCliSpawnTarget, resolveLocalOperatorHome, resolveRudderCliShimTarget, resolveRudderDesiredSkillNames, RUDDER_AGENT_HEARTBEAT_INSTRUCTION, RUDDER_AGENT_OPERATING_CONTRACT, runChildProcess, selectPromptTemplate, shouldIncludeRuntimeHeartbeatInstructions, syncLocalCliCredentialHomeEntries, } from "./server-utils.js";
 const ORIGINAL_HOME = process.env.HOME;
 const ORIGINAL_RUDDER_OPERATOR_HOME = process.env.RUDDER_OPERATOR_HOME;
 const ORIGINAL_ZDOTDIR = process.env.ZDOTDIR;
 const ORIGINAL_GIT_AUTHOR_EMAIL = process.env.GIT_AUTHOR_EMAIL;
 const ORIGINAL_GIT_COMMITTER_EMAIL = process.env.GIT_COMMITTER_EMAIL;
+const ORIGINAL_RUDDER_DESKTOP_CLI_ENTRY = process.env.RUDDER_DESKTOP_CLI_ENTRY;
 afterEach(() => {
     if (ORIGINAL_HOME === undefined)
         delete process.env.HOME;
@@ -30,6 +31,10 @@ afterEach(() => {
         delete process.env.GIT_COMMITTER_EMAIL;
     else
         process.env.GIT_COMMITTER_EMAIL = ORIGINAL_GIT_COMMITTER_EMAIL;
+    if (ORIGINAL_RUDDER_DESKTOP_CLI_ENTRY === undefined)
+        delete process.env.RUDDER_DESKTOP_CLI_ENTRY;
+    else
+        process.env.RUDDER_DESKTOP_CLI_ENTRY = ORIGINAL_RUDDER_DESKTOP_CLI_ENTRY;
 });
 function readPathValue(env) {
     return env.PATH ?? env.Path ?? "";
@@ -37,7 +42,393 @@ function readPathValue(env) {
 function shimName() {
     return process.platform === "win32" ? "rudder.cmd" : "rudder";
 }
+describe("cleanupLegacyRudderDocsManagedEntry", () => {
+    it("is exposed by the shared runtime utilities", () => {
+        expect(cleanupLegacyRudderDocsManagedEntry).toBeTypeOf("function");
+    });
+    it("removes the dangling legacy symlink derived from the selected canonical Rudder Docs source", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-docs-legacy-symlink-"));
+        const skillsHome = path.join(root, "managed-skills");
+        const canonicalSource = path.join(root, "bundled-skills", "rudder-docs");
+        const legacySource = path.join(root, "bundled-skills", "rudder");
+        const legacyTarget = path.join(skillsHome, "rudder");
+        try {
+            await fs.mkdir(skillsHome, { recursive: true });
+            await fs.mkdir(canonicalSource, { recursive: true });
+            await fs.symlink(legacySource, legacyTarget);
+            const result = await cleanupLegacyRudderDocsManagedEntry(skillsHome, [{
+                    key: "rudder/rudder-docs",
+                    runtimeName: "rudder-docs",
+                    source: canonicalSource,
+                }]);
+            expect(result).toEqual({
+                state: "removed",
+                targetPath: legacyTarget,
+                legacySourcePath: legacySource,
+                kind: "symlink",
+            });
+            await expect(fs.lstat(legacyTarget)).rejects.toMatchObject({ code: "ENOENT" });
+        }
+        finally {
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
+    it("recognizes the canonical bundled selection key for a dangling legacy symlink", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-docs-bundled-legacy-symlink-"));
+        const skillsHome = path.join(root, "managed-skills");
+        const canonicalSource = path.join(root, "bundled-skills", "rudder-docs");
+        const legacySource = path.join(root, "bundled-skills", "rudder");
+        const legacyTarget = path.join(skillsHome, "rudder");
+        try {
+            await fs.mkdir(skillsHome, { recursive: true });
+            await fs.mkdir(canonicalSource, { recursive: true });
+            await fs.symlink(legacySource, legacyTarget);
+            const result = await cleanupLegacyRudderDocsManagedEntry(skillsHome, [{
+                    key: "bundled:rudder/rudder-docs",
+                    runtimeName: "rudder-docs",
+                    source: canonicalSource,
+                }]);
+            expect(result.state).toBe("removed");
+            await expect(fs.lstat(legacyTarget)).rejects.toMatchObject({ code: "ENOENT" });
+        }
+        finally {
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
+    it("preserves an exact legacy-source symlink when its target still exists", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-docs-live-legacy-symlink-"));
+        const skillsHome = path.join(root, "managed-skills");
+        const canonicalSource = path.join(root, "bundled-skills", "rudder-docs");
+        const legacySource = path.join(root, "bundled-skills", "rudder");
+        const legacyTarget = path.join(skillsHome, "rudder");
+        try {
+            await fs.mkdir(skillsHome, { recursive: true });
+            await fs.mkdir(canonicalSource, { recursive: true });
+            await fs.mkdir(legacySource, { recursive: true });
+            await fs.symlink(legacySource, legacyTarget);
+            const result = await cleanupLegacyRudderDocsManagedEntry(skillsHome, [{
+                    key: "rudder/rudder-docs",
+                    runtimeName: "rudder-docs",
+                    source: canonicalSource,
+                }]);
+            expect(result.state).toBe("collision");
+            expect(result.kind).toBe("symlink");
+            expect(await fs.realpath(legacyTarget)).toBe(await fs.realpath(legacySource));
+        }
+        finally {
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
+    it("preserves a replacement swapped in after initial symlink validation", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-docs-symlink-swap-"));
+        const skillsHome = path.join(root, "managed-skills");
+        const canonicalSource = path.join(root, "bundled-skills", "rudder-docs");
+        const legacySource = path.join(root, "bundled-skills", "rudder");
+        const legacyTarget = path.join(skillsHome, "rudder");
+        let statSpy = null;
+        try {
+            await fs.mkdir(skillsHome, { recursive: true });
+            await fs.mkdir(canonicalSource, { recursive: true });
+            await fs.symlink(legacySource, legacyTarget);
+            statSpy = vi.spyOn(fs, "stat").mockImplementationOnce(async () => {
+                await fs.unlink(legacyTarget);
+                await fs.writeFile(legacyTarget, "replacement\n", "utf8");
+                throw Object.assign(new Error("legacy source missing"), { code: "ENOENT" });
+            });
+            const result = await cleanupLegacyRudderDocsManagedEntry(skillsHome, [{
+                    key: "rudder/rudder-docs",
+                    runtimeName: "rudder-docs",
+                    source: canonicalSource,
+                }]);
+            expect(result.state).toBe("collision");
+            await expect(fs.readFile(legacyTarget, "utf8")).resolves.toBe("replacement\n");
+        }
+        finally {
+            statSpy?.mockRestore();
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
+    it("removes a legacy materialized directory only when its Rudder provenance matches the derived source", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-docs-legacy-materialized-"));
+        const skillsHome = path.join(root, "managed-skills");
+        const canonicalSource = path.join(root, "bundled-skills", "rudder-docs");
+        const legacySource = path.join(root, "bundled-skills", "rudder");
+        const legacyTarget = path.join(skillsHome, "rudder");
+        try {
+            await fs.mkdir(canonicalSource, { recursive: true });
+            await fs.mkdir(path.join(legacyTarget, ".rudder"), { recursive: true });
+            await fs.writeFile(path.join(legacyTarget, ".rudder", "materialized-skill.json"), JSON.stringify({ sourcePath: legacySource }), "utf8");
+            const result = await cleanupLegacyRudderDocsManagedEntry(skillsHome, [{
+                    key: "rudder/rudder-docs",
+                    runtimeName: "rudder-docs",
+                    source: canonicalSource,
+                }]);
+            expect(result).toEqual({
+                state: "removed",
+                targetPath: legacyTarget,
+                legacySourcePath: legacySource,
+                kind: "directory",
+            });
+            await expect(fs.lstat(legacyTarget)).rejects.toMatchObject({ code: "ENOENT" });
+        }
+        finally {
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
+    it("preserves a materialized directory replacement with matching provenance but a different inode", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-docs-directory-swap-"));
+        const skillsHome = path.join(root, "managed-skills");
+        const canonicalSource = path.join(root, "bundled-skills", "rudder-docs");
+        const legacySource = path.join(root, "bundled-skills", "rudder");
+        const legacyTarget = path.join(skillsHome, "rudder");
+        const displacedTarget = path.join(skillsHome, "rudder-original");
+        const manifestPath = path.join(legacyTarget, ".rudder", "materialized-skill.json");
+        const replacementMarker = path.join(legacyTarget, "replacement.txt");
+        let lstatSpy = null;
+        try {
+            await fs.mkdir(canonicalSource, { recursive: true });
+            await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+            await fs.writeFile(manifestPath, JSON.stringify({ sourcePath: legacySource }), "utf8");
+            const originalLstat = fs.lstat.bind(fs);
+            lstatSpy = vi.spyOn(fs, "lstat").mockImplementationOnce(async () => {
+                const originalStats = await originalLstat(legacyTarget);
+                await fs.rename(legacyTarget, displacedTarget);
+                await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+                await fs.writeFile(manifestPath, JSON.stringify({ sourcePath: legacySource }), "utf8");
+                await fs.writeFile(replacementMarker, "replacement\n", "utf8");
+                return originalStats;
+            });
+            const result = await cleanupLegacyRudderDocsManagedEntry(skillsHome, [{
+                    key: "rudder/rudder-docs",
+                    runtimeName: "rudder-docs",
+                    source: canonicalSource,
+                }]);
+            expect(result.state).toBe("collision");
+            await expect(fs.readFile(replacementMarker, "utf8")).resolves.toBe("replacement\n");
+        }
+        finally {
+            lstatSpy?.mockRestore();
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
+    it("reports a failed state when unlinking the proven dangling symlink fails", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-docs-unlink-failure-"));
+        const skillsHome = path.join(root, "managed-skills");
+        const canonicalSource = path.join(root, "bundled-skills", "rudder-docs");
+        const legacySource = path.join(root, "bundled-skills", "rudder");
+        const legacyTarget = path.join(skillsHome, "rudder");
+        let unlinkSpy = null;
+        try {
+            await fs.mkdir(skillsHome, { recursive: true });
+            await fs.mkdir(canonicalSource, { recursive: true });
+            await fs.symlink(legacySource, legacyTarget);
+            unlinkSpy = vi.spyOn(fs, "unlink").mockRejectedValueOnce(new Error("simulated unlink failure"));
+            const result = await cleanupLegacyRudderDocsManagedEntry(skillsHome, [{
+                    key: "rudder/rudder-docs",
+                    runtimeName: "rudder-docs",
+                    source: canonicalSource,
+                }]);
+            expect(result).toMatchObject({
+                state: "failed",
+                targetPath: legacyTarget,
+                kind: "symlink",
+                detail: "unlink failed: simulated unlink failure",
+            });
+            expect((await fs.lstat(legacyTarget)).isSymbolicLink()).toBe(true);
+        }
+        finally {
+            unlinkSpy?.mockRestore();
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
+    it("reports a failed state when removing the proven materialized directory fails", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-docs-rm-failure-"));
+        const skillsHome = path.join(root, "managed-skills");
+        const canonicalSource = path.join(root, "bundled-skills", "rudder-docs");
+        const legacySource = path.join(root, "bundled-skills", "rudder");
+        const legacyTarget = path.join(skillsHome, "rudder");
+        const manifestPath = path.join(legacyTarget, ".rudder", "materialized-skill.json");
+        let rmSpy = null;
+        try {
+            await fs.mkdir(canonicalSource, { recursive: true });
+            await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+            await fs.writeFile(manifestPath, JSON.stringify({ sourcePath: legacySource }), "utf8");
+            rmSpy = vi.spyOn(fs, "rm").mockRejectedValueOnce(new Error("simulated rm failure"));
+            const result = await cleanupLegacyRudderDocsManagedEntry(skillsHome, [{
+                    key: "rudder/rudder-docs",
+                    runtimeName: "rudder-docs",
+                    source: canonicalSource,
+                }]);
+            expect(result).toMatchObject({
+                state: "failed",
+                targetPath: legacyTarget,
+                kind: "directory",
+                detail: "recursive removal failed: simulated rm failure",
+            });
+            expect((await fs.lstat(legacyTarget)).isDirectory()).toBe(true);
+        }
+        finally {
+            rmSpy?.mockRestore();
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
+    it("preserves an unrecognized symlink and reports an ownership collision", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-docs-legacy-symlink-collision-"));
+        const skillsHome = path.join(root, "managed-skills");
+        const canonicalSource = path.join(root, "bundled-skills", "rudder-docs");
+        const unrelatedSource = path.join(root, "user-skills", "rudder");
+        const legacyTarget = path.join(skillsHome, "rudder");
+        try {
+            await fs.mkdir(skillsHome, { recursive: true });
+            await fs.mkdir(canonicalSource, { recursive: true });
+            await fs.symlink(unrelatedSource, legacyTarget);
+            const result = await cleanupLegacyRudderDocsManagedEntry(skillsHome, [{
+                    key: "rudder/rudder-docs",
+                    runtimeName: "rudder-docs",
+                    source: canonicalSource,
+                }]);
+            expect(result.state).toBe("collision");
+            expect(result.kind).toBe("symlink");
+            expect((await fs.lstat(legacyTarget)).isSymbolicLink()).toBe(true);
+            expect(await fs.readlink(legacyTarget)).toBe(unrelatedSource);
+        }
+        finally {
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
+    it("preserves a regular directory without matching Rudder provenance", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-docs-legacy-dir-collision-"));
+        const skillsHome = path.join(root, "managed-skills");
+        const canonicalSource = path.join(root, "bundled-skills", "rudder-docs");
+        const legacyTarget = path.join(skillsHome, "rudder");
+        const marker = path.join(legacyTarget, "user-owned.txt");
+        try {
+            await fs.mkdir(canonicalSource, { recursive: true });
+            await fs.mkdir(legacyTarget, { recursive: true });
+            await fs.writeFile(marker, "keep me\n", "utf8");
+            const result = await cleanupLegacyRudderDocsManagedEntry(skillsHome, [{
+                    key: "rudder/rudder-docs",
+                    runtimeName: "rudder-docs",
+                    source: canonicalSource,
+                }]);
+            expect(result.state).toBe("collision");
+            expect(result.kind).toBe("directory");
+            await expect(fs.readFile(marker, "utf8")).resolves.toBe("keep me\n");
+        }
+        finally {
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
+    it("preserves a regular file at the legacy child path", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-docs-legacy-file-collision-"));
+        const skillsHome = path.join(root, "managed-skills");
+        const canonicalSource = path.join(root, "bundled-skills", "rudder-docs");
+        const legacyTarget = path.join(skillsHome, "rudder");
+        try {
+            await fs.mkdir(canonicalSource, { recursive: true });
+            await fs.mkdir(skillsHome, { recursive: true });
+            await fs.writeFile(legacyTarget, "user-owned\n", "utf8");
+            const result = await cleanupLegacyRudderDocsManagedEntry(skillsHome, [{
+                    key: "rudder/rudder-docs",
+                    runtimeName: "rudder-docs",
+                    source: canonicalSource,
+                }]);
+            expect(result.state).toBe("collision");
+            expect(result.kind).toBe("file");
+            await expect(fs.readFile(legacyTarget, "utf8")).resolves.toBe("user-owned\n");
+        }
+        finally {
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
+    it("does not trust a selected user skill merely because its runtime name is rudder-docs", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-docs-user-skill-"));
+        const skillsHome = path.join(root, "managed-skills");
+        const userSource = path.join(root, "user-skills", "rudder-docs");
+        const userSibling = path.join(root, "user-skills", "rudder");
+        const legacyTarget = path.join(skillsHome, "rudder");
+        try {
+            await fs.mkdir(skillsHome, { recursive: true });
+            await fs.mkdir(userSource, { recursive: true });
+            await fs.symlink(userSibling, legacyTarget);
+            const result = await cleanupLegacyRudderDocsManagedEntry(skillsHome, [{
+                    key: "user/rudder-docs",
+                    runtimeName: "rudder-docs",
+                    source: userSource,
+                }]);
+            expect(result).toEqual({
+                state: "not_applicable",
+                targetPath: legacyTarget,
+                legacySourcePath: null,
+                kind: null,
+            });
+            expect((await fs.lstat(legacyTarget)).isSymbolicLink()).toBe(true);
+        }
+        finally {
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
+});
+describe("filterRudderDesiredSkillsForBrowserCapability", () => {
+    const available = [
+        { key: "bundled:rudder/browser", runtimeName: "browser" },
+        { key: "org:keep-skill", runtimeName: "keep-skill" },
+    ];
+    const desired = available.map((entry) => entry.key);
+    it("removes only Browser from the effective desired set after preflight disables it", () => {
+        expect(filterRudderDesiredSkillsForBrowserCapability(available, desired, false)).toEqual(["org:keep-skill"]);
+    });
+    it("preserves the desired set when Browser remains available", () => {
+        expect(filterRudderDesiredSkillsForBrowserCapability(available, desired, true)).toEqual(desired);
+    });
+});
+describe("resolveRudderDesiredSkillNames", () => {
+    it("preserves an exact nested Rudder repository skill key", () => {
+        const nestedRepositorySkill = {
+            key: "rudder/rudder/community-helper",
+            runtimeName: "community-helper",
+        };
+        expect(resolveRudderDesiredSkillNames({
+            rudderSkillSync: {
+                desiredSkills: [nestedRepositorySkill.key],
+            },
+        }, [nestedRepositorySkill])).toEqual([nestedRepositorySkill.key]);
+    });
+    it("normalizes legacy Rudder Docs inputs and emits one canonical runtime key", () => {
+        const available = [
+            { key: "bundled:rudder/rudder-docs", runtimeName: "rudder-docs" },
+        ];
+        expect(resolveRudderDesiredSkillNames({
+            rudderSkillSync: {
+                desiredSkills: [
+                    "rudder",
+                    "rudder/rudder",
+                    "bundled:rudder/rudder",
+                    "bundled:rudder/rudder-docs",
+                ],
+            },
+        }, available)).toEqual(["bundled:rudder/rudder-docs"]);
+    });
+});
 describe("ensureRudderCliInPath", () => {
+    it("runs the packaged Windows CLI in Electron's Node mode so stdio remains available", () => {
+        const cliEntry = String.raw `C:\Program Files\Rudder\resources\server-package\desktop-cli.js`;
+        const cliRunner = String.raw `C:\Program Files\Rudder\resources\server-package\desktop-cli-runner.js`;
+        const executable = String.raw `C:\Program Files\Rudder\Rudder.exe`;
+        expect(resolveDesktopCliSpawnTarget(cliEntry, executable, "win32", cliRunner)).toEqual({
+            command: executable,
+            args: [cliRunner],
+            env: { ELECTRON_RUN_AS_NODE: "1" },
+        });
+        expect(resolveDesktopCliSpawnTarget(cliEntry, executable, "darwin")).toEqual({
+            command: executable,
+            args: ["--desktop-cli"],
+        });
+        expect(resolveDesktopCliSpawnTarget(cliEntry, executable, "win32")).toEqual({
+            command: executable,
+            args: ["--desktop-cli"],
+        });
+    });
     it("prefers the current source CLI shim over an existing rudder binary on PATH", async () => {
         const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-cli-source-shim-"));
         const moduleDir = path.join(root, "packages", "agent-runtime-utils", "src");
@@ -88,6 +479,61 @@ describe("ensureRudderCliInPath", () => {
             await fs.rm(root, { recursive: true, force: true });
         }
     });
+    it("uses the Desktop CLI entry when the server runs from an external runtime cache", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-cli-external-runtime-shim-"));
+        const runtimeModuleDir = path.join(root, "runtimes", "0.4.6", "node_modules", "@rudderhq", "agent-runtime-utils", "dist");
+        const desktopCli = path.join(root, "Desktop.app", "Contents", "Resources", "server-package", "desktop-cli.js");
+        const desktopExecutable = process.platform === "darwin"
+            ? path.join(root, "Desktop.app", "Contents", "MacOS", "Rudder")
+            : path.join(root, "Desktop.app", "Contents", process.platform === "win32" ? "Rudder.exe" : "Rudder");
+        const desktopManifest = path.join(path.dirname(desktopCli), "rudder-cli-package.json");
+        const staleBinDir = path.join(root, "stale-bin");
+        const staleRudder = path.join(staleBinDir, shimName());
+        try {
+            await fs.mkdir(runtimeModuleDir, { recursive: true });
+            await fs.mkdir(path.dirname(desktopCli), { recursive: true });
+            await fs.mkdir(path.dirname(desktopExecutable), { recursive: true });
+            await fs.mkdir(staleBinDir, { recursive: true });
+            await fs.writeFile(desktopCli, "console.log('fresh desktop cli');\n", "utf8");
+            await fs.writeFile(path.join(path.dirname(desktopCli), "desktop-cli-runner.js"), "console.log('desktop cli runner');\n", "utf8");
+            await fs.writeFile(desktopExecutable, "desktop executable\n", "utf8");
+            await fs.writeFile(desktopManifest, JSON.stringify({ name: "@rudderhq/cli", version: "0.4.6" }), "utf8");
+            await fs.writeFile(staleRudder, process.platform === "win32" ? "@echo off\r\necho stale\r\n" : "#!/bin/sh\necho stale\n", "utf8");
+            await fs.chmod(staleRudder, 0o755);
+            process.env.RUDDER_DESKTOP_CLI_ENTRY = desktopCli;
+            const target = await resolveRudderCliShimTarget(runtimeModuleDir);
+            const env = await ensureRudderCliInPath(runtimeModuleDir, { PATH: staleBinDir });
+            const firstPathEntry = readPathValue(env).split(path.delimiter)[0];
+            const shim = await fs.readFile(path.join(firstPathEntry, shimName()), "utf8");
+            expect(target).toMatchObject(process.platform === "win32"
+                ? {
+                    command: desktopExecutable,
+                    args: [path.join(path.dirname(desktopCli), "desktop-cli-runner.js")],
+                    env: { ELECTRON_RUN_AS_NODE: "1" },
+                    provenance: "desktop_bundle",
+                    version: "0.4.6",
+                }
+                : {
+                    command: desktopExecutable,
+                    args: ["--desktop-cli"],
+                    provenance: "desktop_bundle",
+                    version: "0.4.6",
+                });
+            expect(firstPathEntry).not.toBe(staleBinDir);
+            expect(shim).toContain(desktopExecutable);
+            if (process.platform === "win32") {
+                expect(shim).toContain("ELECTRON_RUN_AS_NODE=1");
+                expect(shim).toContain("desktop-cli-runner.js");
+            }
+            else {
+                expect(shim).toContain("--desktop-cli");
+                expect(shim).not.toContain(desktopCli);
+            }
+        }
+        finally {
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
 });
 describe("selectPromptTemplate", () => {
     it("keeps issue assignment prompts neutral for non-code work", () => {
@@ -711,6 +1157,56 @@ describe("loadAgentInstructionsPrefix", () => {
     });
 });
 describe("runChildProcess", () => {
+    function isPidAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            const code = error instanceof Error && "code" in error ? error.code : null;
+            return code === "EPERM";
+        }
+    }
+    async function waitForPidExit(pid, timeoutMs = 2_000) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (!isPidAlive(pid))
+                return;
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        }
+        throw new Error(`process ${pid} remained alive after ${timeoutMs}ms`);
+    }
+    function forceKillProcessGroup(pid) {
+        if (process.platform === "win32" || pid === null)
+            return;
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch {
+            // The group already exited.
+        }
+    }
+    it("does not expose the Desktop CLI entry to provider child processes", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-run-child-process-desktop-cli-env-"));
+        const capturePath = path.join(root, "env.json");
+        const scriptPath = path.join(root, "capture-env.mjs");
+        await fs.writeFile(scriptPath, "import fs from 'node:fs'; fs.writeFileSync(process.argv[2], JSON.stringify(process.env.RUDDER_DESKTOP_CLI_ENTRY ?? null));\n", "utf8");
+        process.env.RUDDER_DESKTOP_CLI_ENTRY = "/private/Desktop.app/desktop-cli.js";
+        try {
+            const result = await runChildProcess("run-child-process-desktop-cli-env", process.execPath, [scriptPath, capturePath], {
+                cwd: root,
+                env: {},
+                timeoutSec: 5,
+                graceSec: 1,
+                onLog: async () => { },
+            });
+            expect(result.exitCode).toBe(0);
+            expect(JSON.parse(await fs.readFile(capturePath, "utf8"))).toBeNull();
+        }
+        finally {
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    });
     it("preserves explicit blank Git identity env overrides", async () => {
         const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-run-child-process-git-env-"));
         const capturePath = path.join(root, "env.json");
@@ -809,12 +1305,14 @@ describe("runChildProcess", () => {
             await fs.rm(root, { recursive: true, force: true });
         }
     });
-    it("forces SIGKILL after the grace period when an aborted child ignores SIGTERM", async () => {
+    it.runIf(process.platform !== "win32")("keeps the configured grace for a generic abort without an operator reason", async () => {
         const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-run-child-process-abort-"));
         const scriptPath = path.join(root, "ignore-sigterm.mjs");
         let spawnedPid = null;
+        let abortedAt = 0;
         await fs.writeFile(scriptPath, [
             "process.on('SIGTERM', () => {});",
+            "console.log('ready');",
             "setInterval(() => {}, 1000);",
         ].join("\n"), "utf8");
         const controller = new AbortController();
@@ -828,18 +1326,97 @@ describe("runChildProcess", () => {
                 abortSignal: controller.signal,
                 onSpawn: async ({ pid }) => {
                     spawnedPid = pid;
-                    setTimeout(() => controller.abort(), 50);
                 },
-                onLog: async () => { },
+                onLog: async (_stream, chunk) => {
+                    if (chunk.includes("ready") && abortedAt === 0) {
+                        abortedAt = Date.now();
+                        controller.abort();
+                    }
+                },
             });
             expect(result.signal).toBe("SIGTERM");
             expect(Date.now() - startedAt).toBeLessThan(5_000);
+            expect(abortedAt).toBeGreaterThan(0);
+            expect(Date.now() - abortedAt).toBeGreaterThanOrEqual(800);
             expect(spawnedPid).not.toBeNull();
             await new Promise((resolve) => setTimeout(resolve, 50));
             expect(() => process.kill(spawnedPid, 0)).toThrow();
         }
         finally {
             controller.abort();
+            forceKillProcessGroup(spawnedPid);
+            await fs.rm(root, { recursive: true, force: true });
+        }
+    }, 10_000);
+    it.runIf(process.platform !== "win32")("kills a stubborn parent and grandchild by the operator hard deadline without forwarding post-abort output", async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), "rudder-run-child-process-group-abort-"));
+        const parentScriptPath = path.join(root, "stubborn-parent.mjs");
+        const grandchildScriptPath = path.join(root, "stubborn-grandchild.mjs");
+        const grandchildPidPath = path.join(root, "grandchild.pid");
+        const controller = new AbortController();
+        const liveLogs = [];
+        let parentPid = null;
+        let grandchildPid = null;
+        let abortedAt = 0;
+        await fs.writeFile(grandchildScriptPath, [
+            "process.on('SIGTERM', () => console.log('grandchild-after-abort'));",
+            "console.log('grandchild-ready');",
+            "setInterval(() => console.log('grandchild-tick'), 25);",
+        ].join("\n"), "utf8");
+        await fs.writeFile(parentScriptPath, [
+            "import { spawn } from 'node:child_process';",
+            "import fs from 'node:fs';",
+            "process.on('SIGTERM', () => console.log('parent-after-abort'));",
+            `const grandchild = spawn(process.execPath, [${JSON.stringify(grandchildScriptPath)}], { stdio: ['ignore', 'inherit', 'inherit'] });`,
+            "fs.writeFileSync(process.argv[2], String(grandchild.pid));",
+            "console.log('parent-ready');",
+            "setInterval(() => console.log('parent-tick'), 25);",
+        ].join("\n"), "utf8");
+        try {
+            const result = await runChildProcess("run-child-process-group-operator-abort", process.execPath, [parentScriptPath, grandchildPidPath], {
+                cwd: root,
+                env: {},
+                timeoutSec: 10,
+                graceSec: 5,
+                abortSignal: controller.signal,
+                onSpawn: async ({ pid }) => {
+                    parentPid = pid;
+                },
+                onLog: async (_stream, chunk) => {
+                    liveLogs.push(chunk);
+                    if (abortedAt === 0 && chunk.includes("grandchild-ready")) {
+                        grandchildPid = Number(await fs.readFile(grandchildPidPath, "utf8"));
+                        abortedAt = Date.now();
+                        controller.abort(createOperatorInterruptAbortReason(250));
+                    }
+                },
+            });
+            expect(result.signal).toBe("SIGTERM");
+            expect(abortedAt).toBeGreaterThan(0);
+            expect(Date.now() - abortedAt).toBeGreaterThanOrEqual(150);
+            expect(Date.now() - abortedAt).toBeLessThan(1_500);
+            expect(result.stdout).toContain("parent-after-abort");
+            expect(result.stdout).toContain("grandchild-after-abort");
+            expect(liveLogs.join("")).not.toContain("parent-after-abort");
+            expect(liveLogs.join("")).not.toContain("grandchild-after-abort");
+            expect(parentPid).not.toBeNull();
+            expect(grandchildPid).not.toBeNull();
+            await waitForPidExit(parentPid);
+            await waitForPidExit(grandchildPid);
+        }
+        finally {
+            if (!controller.signal.aborted) {
+                controller.abort(createOperatorInterruptAbortReason(1));
+            }
+            forceKillProcessGroup(parentPid);
+            if (grandchildPid !== null && isPidAlive(grandchildPid)) {
+                try {
+                    process.kill(grandchildPid, "SIGKILL");
+                }
+                catch {
+                    // The process already exited.
+                }
+            }
             await fs.rm(root, { recursive: true, force: true });
         }
     }, 10_000);