@deepseek-ai/dsh-plugin-manager 0.1.7-alpha.2 → 0.1.7-rc.2

package/lib/types/operations.js

@@ -1,11 +1,16 @@
 /** Shared profile package operations used by dsh plugin and the running manager. */
-import { existsSync } from 'node:fs';
-import { mkdir, mkdtemp, open } from 'node:fs/promises';
+import { once } from 'node:events';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, mkdtemp, open, rm } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { execa } from 'execa';
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
-import { DEFAULT_PROFILE_BUNDLES, bundlePatchPaths, initProfile, PROFILE_TEMPLATES, readProfileManifest, resolveBundleDir, resolveProfileDir, loadOverlayPatches, } from '@deepseek-ai/dsh-app-boot';
+import { DEFAULT_PROFILE_BUNDLES, bundlePatchPaths, initProfile, PROFILE_TEMPLATES, readProfileManifest, resolveBundleDir, resolveProfileDir, loadOverlayPatches, composeEntries, readProfileVersionExemptions, evaluatePluginCompatibility, pluginCompatibilityWarning, } from '@deepseek-ai/dsh-app-boot';
 import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess';
+import { parseInstallSpec } from "./install-spec.js";
+import { awaitTreeGone, leadsOwnGroup, treeAlive } from "./run-tree.js";
+import { incompatiblePlugin } from "./failure.js";
+export { setProfileVersionExemption, readProfileVersionExemptions } from '@deepseek-ai/dsh-app-boot';
 /** Resolve relative package specs against the caller's directory.
  * @param argument One pnpm argument.
  * @param cwd Invocation directory, never the profile directory.
@@ -65,76 +70,452 @@ async function reconcile(before, dir, anchor, options) {
     after.dsh = { ...after.dsh, profile: { ...after.dsh?.profile, bundles } };
     await saveManifest(dir, after);
 }
+/**
+ * How long the pipes keep draining after their process exited, as a fixed part of
+ * finishing a run rather than a deployment knob: a descendant that inherited them
+ * holds them open, and the tail a failure classification reads is written by then.
+ */
+const DRAIN_AFTER_EXIT_MS = 2_000;
+/** Whether every collector finished within `ms`.
+ * @param collectors The pipe readers racing the bound.
+ * @param ms The longest wait, in milliseconds.
+ * @returns True when all collectors settled in time.
+ */
+async function drainWithin(collectors, ms) {
+    if (collectors.length === 0)
+        return true;
+    let timer;
+    try {
+        return await Promise.race([
+            Promise.allSettled(collectors).then(() => true),
+            new Promise((resolve) => {
+                timer = setTimeout(() => { resolve(false); }, ms);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Install commands that take the packages to install as positionals. */
+const INSTALL_COMMANDS = new Set(['add', 'install', 'i']);
+/** Bound on a pre-install registry lookup when the caller names none. */
+const LOOKUP_TIMEOUT_MS = 20_000;
+/** Package specs an install command names explicitly, in order. */
+function namedSpecs(args) {
+    const index = args.findIndex(argument => !argument.startsWith('-'));
+    const command = index < 0 ? undefined : args[index];
+    if (command === undefined || !INSTALL_COMMANDS.has(command))
+        return [];
+    return args.slice(index + 1).filter(argument => !argument.startsWith('-'));
+}
+/** The manifest a named spec would install, read without installing it.
+ * A path spec is read from disk. A registry spec asks pnpm's own configuration for the version the
+ * range selects and its peer requirements. A git or tarball spec needs the fetch itself, so the
+ * check after installation is what judges it.
+ * @param dir Profile directory the lookup runs in.
+ * @param spec Anchored install spec.
+ * @param options Pnpm executable, prefix arguments, the caller's bound and signal.
+ * @param environment Environment of the caller's pnpm invocations.
+ * @param flags Flags of the run itself, so the lookup asks the registry that run will use.
+ * @returns The package manifest, or undefined when reading it would need the installation itself.
+ */
+async function namedSpecManifest(dir, spec, options, environment, flags) {
+    const parsed = parseInstallSpec(spec);
+    if (parsed.kind === 'path') {
+        const filename = join(parsed.path, 'package.json');
+        return existsSync(filename) ? JSON.parse(readFileSync(filename, 'utf8')) : undefined;
+    }
+    if (parsed.kind !== 'registry')
+        return undefined;
+    const viewed = await execa(options.command ?? 'pnpm', [
+        ...options.args ?? [], 'view', parsed.spec, 'name', 'version', 'peerDependencies', '--json',
+        ...flags, '--config.fetch-retries=0',
+    ], {
+        cwd: dir, env: environment, extendEnv: false, reject: false, stdin: 'ignore',
+        ...options.signal === undefined ? {} : { cancelSignal: options.signal },
+        timeout: options.lookupTimeoutMs ?? LOOKUP_TIMEOUT_MS,
+    });
+    if (viewed.exitCode !== 0)
+        return undefined;
+    const value = JSON.parse(viewed.stdout);
+    return (Array.isArray(value) ? value.at(-1) : value);
+}
+/** Missing installed packages are repairable; their absence is part of the before/after comparison. */
+function optionalFile(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/** Where an operation records the pnpm run it started, for a successor when the operation's own process ends first. */
+function runRecordPath(dir) {
+    return join(dir, '.plugin-manager', 'run.json');
+}
+/** Record a started run; a successor that takes over the profile lock from an exited process waits for it. */
+async function recordRun(dir, tree) {
+    if (tree.pid === undefined)
+        return;
+    await writeFileAtomic(runRecordPath(dir), `${JSON.stringify(tree)}\n`, { mode: 0o600, dirMode: 0o700 });
+}
+/**
+ * Why this operation must not run: a record left by an operation whose process
+ * ended mid-run names a run that is still writing the profile. The profile
+ * lock is taken over once its holder exits, but its pnpm tree can outlive it.
+ * A recorded run that stopped, within a bounded wait, has its record removed.
+ * @param dir Profile directory.
+ * @returns The diagnostic, or undefined when no recorded run is active.
+ */
+async function activeRecordedRun(dir) {
+    const path = runRecordPath(dir);
+    const text = optionalFile(path);
+    if (text === undefined)
+        return undefined;
+    let tree;
+    try {
+        const value = JSON.parse(text);
+        const { pid, grouped } = (typeof value === 'object' && value !== null ? value : {});
+        if (Number.isSafeInteger(pid) && pid > 0 && typeof grouped === 'boolean')
+            tree = { pid: pid, grouped };
+    }
+    catch (error) {
+        // Records are replaced atomically, so an unparsable one was written by something else and is reported below.
+        void error;
+    }
+    if (tree === undefined) {
+        return `dsh: ${path} does not name a package run; delete it once no earlier package operation is still running in this profile\n`;
+    }
+    await awaitTreeGone(tree);
+    if (treeAlive(tree)) {
+        return `dsh: process ${String(tree.pid)}, started by an earlier package operation whose own process ended, is still running in this profile; `
+            + `wait for it or stop it, then retry. If process ${String(tree.pid)} is not that package run, delete ${path}.\n`;
+    }
+    await rm(path, { force: true });
+    return undefined;
+}
+/** pnpm can install plugins through any direct-dependency field. */
+function directDependencies(manifest) {
+    const extra = manifest;
+    return { ...extra.devDependencies, ...manifest.dependencies, ...extra.optionalDependencies };
+}
+/** Inspect only plugin rows contributed by the changed bundle, not its dependency closure. */
+function bundleComponentManifests(manifest, dir, anchor) {
+    const bundle = manifest.dsh?.bundle;
+    if (bundle === undefined)
+        return [];
+    const patches = bundlePatchPaths(dir, bundle).flatMap(file => loadOverlayPatches('dsh', file));
+    const names = new Set();
+    const visit = (rows) => {
+        for (const row of rows) {
+            if (row.group && Array.isArray(row.config))
+                visit(row.config);
+            if (typeof row.name !== 'string' || row.name.startsWith('.') || row.name.startsWith('/') || row.name.includes(':'))
+                continue;
+            const parts = row.name.split('/');
+            names.add(parts.slice(0, row.name.startsWith('@') ? 2 : 1).join('/'));
+        }
+    };
+    visit(composeEntries([patches.filter(patch => patch.insert !== undefined)]));
+    return [...names].flatMap((name) => {
+        let packageDir;
+        try {
+            packageDir = resolveBundleDir('dsh', name, anchor, dir);
+        }
+        catch (error) {
+            // Resolution errors for uninstalled or dynamic rows remain subject to the startup loader's checks.
+            void error;
+            return [];
+        }
+        return [readProfileManifest('dsh', packageDir)];
+    });
+}
 /** Execute pnpm inside a profile whose caller already holds the profile write lock.
+ * Newly installed or updated direct dependencies are checked even when activation is disabled;
+ * an untouched dependency never blocks an unrelated operation and stays denied at startup.
+ * Compatibility denial restores the profile manifest and lockfile, but leaves downloaded modules on disk.
  * @param context Launcher-owned profile and resolution locations.
  * @param args Pnpm arguments, before relative path anchoring.
  * @param options Output, activation and cancellation policy.
- * @returns Exit status and diagnostic path; service output is bounded, CLI output uses inherited descriptors.
+ * @returns Exit status, whether the silence bound stopped the run, and the diagnostic path.
+ * A compatibility denial returns exit code 1. Service output is bounded; CLI output uses inherited descriptors.
  */
 export async function runProfilePnpm(context, args, options) {
     const dir = context.dir ?? resolveProfileDir(context.profile, context.home);
-    const before = readProfileManifest('dsh', dir);
+    // Before any profile file is read: a recorded run that is still active may be rewriting them.
+    const active = await activeRecordedRun(dir);
     const logRoot = join(dir, '.plugin-manager', 'logs');
     await mkdir(logRoot, { recursive: true, mode: 0o700 });
     const logDir = await mkdtemp(join(logRoot, 'operation-'));
     const logPath = join(logDir, 'pnpm.log');
     const log = await open(logPath, 'wx', 0o600);
+    if (active !== undefined) {
+        await log.write(active);
+        await log.close();
+        options.onOutput?.(active, 'stderr');
+        const bytes = Buffer.from(active);
+        return { exitCode: 1, output: bytes.subarray(Math.max(0, bytes.length - options.outputBytes)).toString('utf8'), truncated: bytes.length > options.outputBytes, logPath };
+    }
+    const before = readProfileManifest('dsh', dir);
+    const savedFiles = ['package.json', 'pnpm-lock.yaml'].map(name => ({ path: join(dir, name), text: optionalFile(join(dir, name)) }));
+    const beforeDependencies = directDependencies(before);
+    const installedBefore = new Map(Object.keys(beforeDependencies).map(name => [name, optionalFile(join(dir, 'node_modules', name, 'package.json'))]));
     let output = Buffer.alloc(0);
     let truncated = false;
+    const append = (bytes) => {
+        output = Buffer.concat([output, bytes]);
+        if (output.length > options.outputBytes) {
+            truncated = true;
+            output = output.subarray(output.length - options.outputBytes);
+        }
+    };
+    const environment = { ...(options.execution === 'cli' ? process.env : scrubbedParentEnv()), ...options.env };
+    const restore = async () => {
+        for (const file of savedFiles) {
+            if (file.text === undefined)
+                await rm(file.path, { force: true });
+            else
+                await writeFileAtomic(file.path, file.text, { mode: 0o600 });
+        }
+    };
+    /** Packages a compatibility check refused; callers render them for their own surface. */
+    const incompatible = [];
+    const rejected = async (warnings, restoration) => {
+        const diagnostic = `\ndsh: installation rejected: ${warnings.join('\n')}\ndsh: ${restoration}.\n`;
+        await log.write(diagnostic);
+        options.onOutput?.(diagnostic, 'stderr');
+        append(Buffer.from(diagnostic));
+        await log.close();
+        return { exitCode: 1, output: output.toString('utf8'), truncated, logPath, incompatible };
+    };
+    // An install command names the packages it adds, so their manifests are read and checked before
+    // pnpm runs: an incompatible version is never installed, and the one already in use keeps working.
+    const preflight = [];
+    const exemptions = readProfileVersionExemptions(dir);
+    // The run's own registry flags, so the lookup asks the registry the installation will use.
+    const registryFlags = args.filter(argument => argument.startsWith('--registry='));
+    for (const raw of namedSpecs(args)) {
+        // A spec whose manifest cannot be read or validated is left to the run itself and to the check
+        // after installation, which reports what it could not validate.
+        try {
+            const manifest = await namedSpecManifest(dir, anchorPathSpec(raw, context.cwd), options, environment, registryFlags);
+            if (manifest === undefined)
+                continue;
+            const issue = evaluatePluginCompatibility(manifest, exemptions);
+            if (issue !== undefined && !issue.exempted) {
+                preflight.push(pluginCompatibilityWarning(issue));
+                incompatible.push(incompatiblePlugin(issue));
+            }
+        }
+        catch (error) {
+            void error;
+            continue;
+        }
+    }
+    if (preflight.length > 0)
+        return rejected(preflight, 'nothing was installed');
     const cancellation = new AbortController();
+    // A service run captures output, so execa terminates the tree it leads when the
+    // run is killed: a lifecycle script outlives the pnpm process that started it.
+    // The CLI keeps the caller's process group, so an interrupt still reaches it.
+    const grouped = leadsOwnGroup(options.execution);
     const child = execa(options.command ?? 'pnpm', [...options.args ?? [], ...args.map(arg => anchorPathSpec(arg, context.cwd))], {
-        cwd: dir, env: { ...(options.execution === 'cli' ? process.env : scrubbedParentEnv()), ...options.env }, extendEnv: false, reject: false,
+        cwd: dir, env: environment, extendEnv: false, reject: false,
         stdout: options.execution === 'cli' ? 'inherit' : 'pipe',
         stderr: options.execution === 'cli' ? 'inherit' : 'pipe',
+        killDescendants: options.execution === 'service',
         buffer: false, stdin: options.execution === 'cli' ? 'inherit' : 'ignore', cancelSignal: options.signal === undefined
             ? cancellation.signal : AbortSignal.any([cancellation.signal, options.signal]),
     });
+    // Listened for before the record is written, so an exit during that write is not missed.
+    const exited = once(child.nodeChildProcess, 'exit').catch(() => undefined);
     let writes = Promise.resolve();
+    /** `settled` records that the process outcome is known; `stalled` that the silence bound stopped the run. */
+    const control = { settled: false, stalled: false };
+    /** Set once this call cuts the reading short itself, so the close it causes is not read as a run failure. */
+    let cut = false;
+    /** The first failure a reading hit before that cut, which the run still reports. */
+    let failure;
+    let idleTimer;
+    /** The silence bound: a captured run that stops printing without exiting is terminated, never awaited. */
+    const armIdle = () => {
+        if (control.settled || options.idleTimeoutMs === undefined)
+            return;
+        clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+            control.stalled = true;
+            // execa's kill reaches the whole tree of a service run, and escalates on its own.
+            child.kill();
+        }, options.idleTimeoutMs);
+    };
     const collect = async (stream, kind) => {
         try {
             for await (const chunk of stream) {
+                armIdle();
                 const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
                 writes = writes.then(async () => { await log.write(bytes); });
                 await writes;
                 options.onOutput?.(bytes.toString('utf8'), kind);
-                output = Buffer.concat([output, bytes]);
-                if (output.length > options.outputBytes) {
-                    truncated = true;
-                    output = output.subarray(output.length - options.outputBytes);
-                }
+                append(bytes);
             }
         }
         catch (error) {
-            cancellation.abort();
+            // A reading this call cut short is not a failure the run hit, and the run has
+            // already exited, so there is nothing left for the cancellation to stop.
+            if (!cut) {
+                failure ??= error instanceof Error ? error : new Error(String(error));
+                cancellation.abort();
+            }
             throw error;
         }
     };
+    const collectors = [
+        ...child.stdout === null ? [] : [collect(child.stdout, 'stdout')],
+        ...child.stderr === null ? [] : [collect(child.stderr, 'stderr')],
+    ];
+    // The drain decides whether a failure surfaces, so each reading is claimed now:
+    // an unclaimed rejection would be reported as unhandled while the pipes drain.
+    for (const collector of collectors)
+        void collector.catch(() => { });
+    // Inherited descriptors hand pnpm the terminal, so there is no captured output
+    // for a silence bound to observe: it would fire on a healthy run.
+    if (collectors.length > 0)
+        armIdle();
     let exitCode;
     try {
-        const [completion, ...streams] = await Promise.allSettled([child,
-            ...child.stdout === null ? [] : [collect(child.stdout, 'stdout')],
-            ...child.stderr === null ? [] : [collect(child.stderr, 'stderr')],
-        ]);
-        for (const stream of streams)
-            if (stream.status === 'rejected')
-                throw stream.reason;
+        await recordRun(dir, { pid: child.pid, grouped });
+        // execa resolves its promise only once the piped stdio has ended, so the
+        // process's own exit — the run's completion — is read from the raw child. A
+        // spawn failure settles without one.
+        const settled = Promise.allSettled([child]);
+        await Promise.race([exited, settled]);
+        control.settled = true;
+        clearTimeout(idleTimer);
+        // A stalled run stops its whole tree first, so the caller's rollback and lock
+        // release happen only after the scripts it started stopped writing.
+        if (control.stalled)
+            await awaitTreeGone({ pid: child.pid, grouped });
+        // A descendant that inherited the pipes can hold them open past the process;
+        // the tail drains under a bound instead of being awaited forever.
+        const drained = await drainWithin(collectors, DRAIN_AFTER_EXIT_MS);
+        if (drained) {
+            for (const stream of await Promise.allSettled(collectors))
+                if (stream.status === 'rejected')
+                    throw stream.reason;
+        }
+        else {
+            // Cutting the tail short is this call's own end, not a failure the run hit;
+            // a failure from before the cut still surfaces, and the cut leaves a notice
+            // in the log because a classification may read an incomplete tail.
+            cut = true;
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            const notice = 'dsh: pnpm output was cut short after its process exited\n';
+            await log.write(notice);
+            // A failure from before the cut is the run's own and replaces the notice a
+            // caller would otherwise read; a rejection the cut itself causes is its end.
+            if (failure !== undefined)
+                throw failure;
+            options.onOutput?.(notice, 'stderr');
+            append(Buffer.from(notice));
+        }
+        const [completion] = await settled;
         if (completion.status === 'rejected')
             throw completion.reason;
         const result = completion.value;
         exitCode = result.exitCode ?? (result.code === 'ENOENT' ? 127 : 1);
+        if (control.stalled) {
+            const notice = `dsh: pnpm printed nothing for ${String(options.idleTimeoutMs)}ms and was terminated\n`;
+            await log.write(notice);
+            options.onOutput?.(notice, 'stderr');
+            append(Buffer.from(notice));
+        }
         if (result.failed && output.length === 0) {
             const diagnostic = result.shortMessage ?? 'pnpm failed';
             await log.write(diagnostic);
             truncated = Buffer.byteLength(diagnostic) > options.outputBytes;
             output = Buffer.from(diagnostic).subarray(0, options.outputBytes);
         }
-        if (exitCode === 0 && options.activateNewBundles !== false)
-            await reconcile(before, dir, context.installAnchor, options);
+        // A terminated run's exit status says nothing about what it wrote, so it never reconciles the selection.
+        if (exitCode === 0 && !control.stalled) {
+            const after = readProfileManifest('dsh', dir);
+            const warnings = [];
+            for (const [name, spec] of Object.entries(directDependencies(after))) {
+                const packageDir = join(dir, 'node_modules', name);
+                const installed = optionalFile(join(packageDir, 'package.json'));
+                if (installed === undefined)
+                    continue;
+                // A dependency this run did not touch never blocks an unrelated operation; profile startup denies it.
+                const untouched = beforeDependencies[name] === spec && installedBefore.get(name) === installed;
+                const found = [];
+                const issues = [];
+                try {
+                    const manifest = readProfileManifest('dsh', packageDir);
+                    for (const candidate of [manifest, ...bundleComponentManifests(manifest, packageDir, context.installAnchor)]) {
+                        const issue = evaluatePluginCompatibility(candidate, readProfileVersionExemptions(dir));
+                        if (issue !== undefined && !issue.exempted) {
+                            found.push(pluginCompatibilityWarning(issue));
+                            issues.push(incompatiblePlugin(issue));
+                        }
+                    }
+                }
+                catch (error) {
+                    found.push(`Cannot validate installed package ${name}: ${String(error)}`);
+                }
+                if (found.length === 0)
+                    continue;
+                if (!untouched) {
+                    warnings.push(...found);
+                    incompatible.push(...issues);
+                }
+                else {
+                    const notice = `\ndsh: warning: ${found.join('\n')}\ndsh: it stays installed but profile startup denies it until you grant an exemption for those exact versions.\n`;
+                    await log.write(notice);
+                    options.onOutput?.(notice, 'stderr');
+                }
+            }
+            if (warnings.length > 0) {
+                // A bundle component's peers need installed contents, so this rejection lands after pnpm
+                // replaced the tree: restore the files, then reinstall the restored lockfile so the version
+                // that worked before this run keeps loading. A profile that had no lockfile is reinstalled
+                // from its restored manifest without creating one, which removes what this run added.
+                await restore();
+                const hadLockfile = savedFiles.some(file => file.path.endsWith('pnpm-lock.yaml') && file.text !== undefined);
+                const repair = ['install', hadLockfile ? '--frozen-lockfile' : '--config.lockfile=false'];
+                const repairing = execa(options.command ?? 'pnpm', [...options.args ?? [], ...repair], {
+                    cwd: dir, env: environment, extendEnv: false, reject: false, stdin: 'ignore',
+                    ...options.idleTimeoutMs === undefined ? {} : { timeout: options.idleTimeoutMs },
+                });
+                await recordRun(dir, { pid: repairing.pid, grouped: false });
+                const repaired = await repairing;
+                exitCode = 1;
+                const restoration = repaired.exitCode === 0
+                    ? 'restored package.json, pnpm-lock.yaml, and node_modules'
+                    : "restored package.json and pnpm-lock.yaml, but node_modules could not be reinstalled; run 'dsh plugin install'";
+                const diagnostic = `\ndsh: installation rejected: ${warnings.join('\n')}\ndsh: ${restoration}.\n`;
+                await log.write(diagnostic);
+                options.onOutput?.(diagnostic, 'stderr');
+                append(Buffer.from(diagnostic));
+            }
+            else if (options.activateNewBundles !== false) {
+                await reconcile(before, dir, context.installAnchor, options);
+            }
+        }
     }
     finally {
+        control.settled = true;
+        clearTimeout(idleTimer);
+        // This process saw the run end, so no successor has to wait for it.
+        await rm(runRecordPath(dir), { force: true });
         await log.close();
     }
-    return { exitCode, output: output.toString('utf8'), truncated, logPath };
+    return {
+        exitCode, output: output.toString('utf8'), truncated, logPath,
+        ...control.stalled ? { timedOut: true } : {}, ...incompatible.length > 0 ? { incompatible } : {},
+    };
 }
 /** Initialize and run the dsh plugin command with the same write lock as the service.
  * @param context Launcher-owned locations.

package/lib/types/run-tree.d.ts

@@ -0,0 +1,44 @@
+/** Waiting for one package run's process tree to disappear before its caller touches the profile. */
+/** The process (or process group) one run occupies. */
+export interface RunTree {
+    /** The run's process id, when its spawn published one. */
+    pid: number | undefined;
+    /** Whether the run leads its own process group, which is what a POSIX group probe addresses. */
+    grouped: boolean;
+}
+/** Injectable process operations, so every platform's probing is testable on any host. */
+export interface RunTreeInternals {
+    /** Host platform override for target decisions. */
+    platform?: NodeJS.Platform;
+    /** Liveness probe override, defaulting to `process.kill(target, 0)`. */
+    alive?: (target: number) => boolean;
+    /** Wait bound override, defaulting to the tree wait constant. */
+    waitMs?: number;
+}
+/**
+ * Whether one run leads its own process group, which is the target a POSIX
+ * liveness probe addresses for the whole tree. A run that captures output is
+ * spawned as its own group leader, because its tree is terminated as a unit; a
+ * run that inherits the caller's descriptors keeps the caller's group, so an
+ * interrupt still reaches it.
+ * @param execution Whether the run captures output or inherits the caller's descriptors.
+ * @param platform Host platform deciding how a tree is addressed.
+ * @returns True when the run leads its own process group.
+ */
+export declare function leadsOwnGroup(execution: 'cli' | 'service', platform?: NodeJS.Platform): boolean;
+/**
+ * Whether any member of a run's tree is still alive.
+ * @param tree The run's process id and whether it leads its own group.
+ * @param internals Injectable process operations.
+ * @returns True while the probe finds the process or a group member.
+ */
+export declare function treeAlive(tree: RunTree, internals?: RunTreeInternals): boolean;
+/**
+ * Wait until a terminated run's tree is gone, so the caller restores and
+ * unlocks the profile only after the scripts it started stopped writing.
+ * @param tree The run's process id and whether it leads its own group.
+ * @param internals Injectable process operations.
+ * @returns Fulfillment once no member remains, or the wait bound elapsed.
+ */
+export declare function awaitTreeGone(tree: RunTree, internals?: RunTreeInternals): Promise<void>;
+//# sourceMappingURL=run-tree.d.ts.map

package/lib/types/run-tree.js

@@ -0,0 +1,57 @@
+/** Waiting for one package run's process tree to disappear before its caller touches the profile. */
+/** How long a terminated tree may take to disappear before the caller stops waiting. */
+const TREE_WAIT_MS = 5_000;
+/** Poll cadence while waiting for a terminated tree to disappear. */
+const TREE_POLL_MS = 15;
+/**
+ * Whether one run leads its own process group, which is the target a POSIX
+ * liveness probe addresses for the whole tree. A run that captures output is
+ * spawned as its own group leader, because its tree is terminated as a unit; a
+ * run that inherits the caller's descriptors keeps the caller's group, so an
+ * interrupt still reaches it.
+ * @param execution Whether the run captures output or inherits the caller's descriptors.
+ * @param platform Host platform deciding how a tree is addressed.
+ * @returns True when the run leads its own process group.
+ */
+export function leadsOwnGroup(execution, platform = process.platform) {
+    return execution === 'service' && platform !== 'win32';
+}
+/** The target a tree probe addresses: a POSIX group when the run leads one, else the process itself. */
+function targetOf(pid, grouped, platform) {
+    return platform !== 'win32' && grouped ? -pid : pid;
+}
+/**
+ * Whether any member of a run's tree is still alive.
+ * @param tree The run's process id and whether it leads its own group.
+ * @param internals Injectable process operations.
+ * @returns True while the probe finds the process or a group member.
+ */
+export function treeAlive(tree, internals = {}) {
+    const pid = tree.pid;
+    if (pid === undefined)
+        return false;
+    const platform = internals.platform ?? process.platform;
+    const alive = internals.alive ?? ((target) => { process.kill(target, 0); return true; });
+    try {
+        return alive(targetOf(pid, tree.grouped, platform));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Wait until a terminated run's tree is gone, so the caller restores and
+ * unlocks the profile only after the scripts it started stopped writing.
+ * @param tree The run's process id and whether it leads its own group.
+ * @param internals Injectable process operations.
+ * @returns Fulfillment once no member remains, or the wait bound elapsed.
+ */
+export async function awaitTreeGone(tree, internals = {}) {
+    const deadline = Date.now() + (internals.waitMs ?? TREE_WAIT_MS);
+    while (treeAlive(tree, internals)) {
+        if (Date.now() >= deadline)
+            return;
+        await new Promise(resolve => setTimeout(resolve, TREE_POLL_MS));
+    }
+}
+//# sourceMappingURL=run-tree.js.map

package/lib/types/tools.js

@@ -2,6 +2,7 @@
 import { assertNever } from '@deepseek-ai/dsh-util-values';
 import { approveEscalation } from '@deepseek-ai/dsh-sandbox';
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import { getDshRuntimeVersion } from '@deepseek-ai/dsh-app-boot';
 /** Required services for the management tool. */
 export const inject = ['tools', 'pluginManager', 'sandboxPolicy'];
 /** Register one management tool for discovery and the four persistent actions.
@@ -10,11 +11,13 @@ export const inject = ['tools', 'pluginManager', 'sandboxPolicy'];
 export function apply(ctx) {
     ctx.tools.register(defineTool({
         name: 'plugin_manager',
-        description: 'List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately; startup profiles require restart.',
+        description: 'List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately; startup profiles require restart. Incompatible DSH peer dependencies block installation and activation. Version exemptions risk crashes and data loss: warn the user and obtain explicit permission for the exact plugin and runtime versions before granting one.',
         parameters: {
-            action: { type: 'string', required: true, enum: ['list_plugins', 'list_bundles', 'set_plugin', 'set_bundle', 'install_bundle', 'remove_bundle'], description: 'Management operation.' },
+            action: { type: 'string', required: true, enum: ['list_plugins', 'list_bundles', 'set_plugin', 'set_bundle', 'install_bundle', 'remove_bundle', 'list_version_exemptions', 'set_version_exemption'], description: 'Management operation.' },
             target: { type: 'string', description: 'Plugin entry id, bundle package name, or installation spec, according to action.' },
-            enabled: { type: 'boolean', description: 'Required for set operations; defaults to true for installation.' },
+            enabled: { type: 'boolean', description: 'Required for set operations; defaults to true for installation. For set_version_exemption, true grants and false revokes.' },
+            runtimeVersion: { type: 'string', description: 'For set_version_exemption: exact DSH version from list_version_exemptions. Target must be the manifest package-name@version, not an alias or version range.' },
+            acceptRisk: { type: 'boolean', description: 'For granting an exemption: true only after warning the user about possible crashes and data loss and receiving explicit permission for this exact plugin/runtime pair. General installation permission is not enough.' },
             approvedBuilds: { type: 'array', items: { type: 'string' }, description: 'For install_bundle: pass names from pendingBuilds only after the user explicitly approves running their install scripts in the conversation. This grants persistent permission for this profile.' },
             registry: { type: 'string', description: 'For install_bundle: the npm registry URL asked first, when the user names one; otherwise the configured registry is asked, and its configured fallbacks while a registry is unreachable.' },
             offset: { type: 'number', description: 'Zero-based list offset; defaults to 0.' },
@@ -34,6 +37,13 @@ export function apply(ctx) {
             exec.signal.throwIfAborted();
             const manager = ctx.pluginManager;
             switch (args.action) {
+                case 'list_version_exemptions':
+                    return JSON.stringify({ runtimeVersion: getDshRuntimeVersion(), ...manager.listVersionExemptions() });
+                case 'set_version_exemption':
+                    if (args.target === undefined || args.runtimeVersion === undefined || args.enabled === undefined) {
+                        throw new Error('target package-name@version, runtimeVersion, and enabled are required');
+                    }
+                    return JSON.stringify(await manager.setVersionExemption(args.target, args.runtimeVersion, args.enabled, args.acceptRisk));
                 case 'list_plugins':
                 case 'list_bundles': {
                     const offset = args.offset ?? 0;