@deepseek-ai/dsh-app-boot 0.1.6-alpha.1 → 0.1.6-alpha.2

package/lib/index.js

@@ -1,17 +1,16 @@
 import { createRequire, isBuiltin } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { parseEnv } from "node:util";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import * as yaml from "js-yaml";
 import { Context, Service } from "@deepseek-ai/cordis";
 import Loader, { EntryGroup, EntryTree, isJsExpr } from "@deepseek-ai/cordis-plugin-loader";
-import { access, constants, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
+import { access, constants, readFile, rename, writeFile } from "node:fs/promises";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import Group from "@deepseek-ai/cordis-plugin-group";
 import { dshHomePath, resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { createLaunchEnvironmentSnapshot } from "@deepseek-ai/dsh-launch-environment";
-import { watch } from "chokidar";
 import { withFileLock } from "@deepseek-ai/dsh-atomic-write";
 import { imports, resolve as resolve$1 } from "resolve.exports";
 import { getEnvironmentData, setEnvironmentData } from "node:worker_threads";
@@ -247,100 +246,6 @@ var Include = class extends EntryTree {
 	}
 };
 //#endregion
-//#region lib/types/watch-config.js
-/** Exact-path watching for live profile patch files outside Cordis module roots. */
-const registrations = /* @__PURE__ */ new WeakMap();
-async function findWatchRoot(filename) {
-	let root = dirname(filename);
-	let depth = 0;
-	while (true) try {
-		if (!(await stat(root)).isDirectory()) throw new Error(`config watch parent is not a directory: ${root}`);
-		const canonicalRoot = await realpath(root);
-		return {
-			filename: resolve(canonicalRoot, relative(root, filename)),
-			root: canonicalRoot,
-			depth
-		};
-	} catch (error) {
-		if (error.code !== "ENOENT") throw error;
-		const parent = dirname(root);
-		if (parent === root) throw error;
-		root = parent;
-		depth += 1;
-	}
-}
-/**
-* Watch one patch path, including missing parents, and serialize refresh callbacks.
-* @param ctx Context that owns watcher disposal and receives refresh failures.
-* @param filename Absolute patch-file path.
-* @param options Deployment watcher options inherited from the HMR configuration.
-* @param refresh Callback for additions, changes, and removals.
-* @returns A disposer that closes the watcher and drains its current refresh.
-* @throws When path resolution, watcher startup, or effect registration fails.
-*/
-async function watchConfig(ctx, filename, options, refresh) {
-	const target = await findWatchRoot(filename);
-	const paths = registrations.get(ctx) ?? /* @__PURE__ */ new Set();
-	registrations.set(ctx, paths);
-	if (paths.has(target.filename)) throw new Error(`config path already registered: ${filename}`);
-	const { cwd: _cwd, ignored: _ignored, ...watchOptions } = options;
-	const watcher = watch(target.root, {
-		...watchOptions,
-		depth: target.depth,
-		ignoreInitial: false
-	});
-	paths.add(target.filename);
-	const state = { dirty: false };
-	let running;
-	const onChange = (path) => {
-		const observed = resolve(path);
-		if (observed !== filename && observed !== target.filename) return;
-		state.dirty = true;
-		if (running) return;
-		running = (async () => {
-			while (state.dirty) {
-				state.dirty = false;
-				try {
-					await refresh();
-				} catch (reason) {
-					const error = reason instanceof Error ? reason : new Error(String(reason), { cause: reason });
-					ctx.logger.warn("config reload at %C failed", filename);
-					ctx.logger.warn(error);
-				}
-			}
-		})().finally(() => {
-			running = void 0;
-		});
-	};
-	watcher.on("add", onChange);
-	watcher.on("change", onChange);
-	watcher.on("unlink", onChange);
-	const ready = Promise.withResolvers();
-	let pending = true;
-	watcher.once("ready", () => {
-		pending = false;
-		ready.resolve();
-	});
-	watcher.on("error", (error) => {
-		if (pending) {
-			pending = false;
-			ready.reject(error);
-		} else ctx.logger.warn(error);
-	});
-	const dispose = async () => {
-		await watcher.close();
-		paths.delete(target.filename);
-		await running;
-	};
-	try {
-		await ready.promise;
-		return ctx.effect(() => dispose, "app-boot.watchConfig()");
-	} catch (error) {
-		await dispose();
-		throw error;
-	}
-}
-//#endregion
 //#region lib/types/profile-resolution/legacy-links.js
 /** Legacy profile-link inspection shared by the disk materializer and runtime resolver. */
 /** Profile-private package links projected into its pnpm-managed node_modules. */
@@ -446,26 +351,11 @@ function resolveProfileDir(name, home = resolveDshHome()) {
 }
 /** The shipped profile templates auto-initialized on first use, by name. */
 const PROFILE_TEMPLATES = {
-	acp: {
-		bundles: ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-acp-app"],
-		patchReload: "startup"
-	},
-	web: {
-		bundles: ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app"],
-		patchReload: "live"
-	},
-	headless: {
-		bundles: ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-headless"],
-		patchReload: "startup"
-	},
-	sdk: {
-		bundles: ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-sdk-app"],
-		patchReload: "startup"
-	},
-	"sdk-minimal": {
-		bundles: ["@deepseek-ai/dsh-sdk-minimal"],
-		patchReload: "startup"
-	}
+	acp: { bundles: ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-acp-app"] },
+	web: { bundles: ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app"] },
+	headless: { bundles: ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-headless"] },
+	sdk: { bundles: ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-sdk-app"] },
+	"sdk-minimal": { bundles: ["@deepseek-ai/dsh-sdk-minimal"] }
 };
 /** Installation-owned bundle tuples normalized to the shipped template. */
 const INSTALLATION_OWNED_PROFILE_TUPLES = { headless: [
@@ -475,8 +365,13 @@ const INSTALLATION_OWNED_PROFILE_TUPLES = { headless: [
 ] };
 /** The bundle list a `dsh plugin` init uses for a name with no shipped template. */
 const DEFAULT_PROFILE_BUNDLES = ["@deepseek-ai/dsh-base"];
-/** Custom profiles retain the historical live patch-file behavior. */
-const DEFAULT_PROFILE_PATCH_RELOAD = "live";
+/**
+* The bundles the dsh installation ships for a person to switch on: each a
+* runtime dependency of the installation that declares `dsh.bundle.patch`,
+* selected by no shipped template, and offered switched off by the plugin
+* manager ([rationale](../../../../.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.md)).
+*/
+const OPTIONAL_BUNDLES = ["@deepseek-ai/dsh-experimental-agent-team-profile", "@deepseek-ai/dsh-experimental-agent-team-web-profile"];
 const PROFILE_PATCH_TEMPLATE = `# Your patch layer for this dsh profile, applied after every bundle layer:
 # a top-level YAML array of loader patch entries (id-targeted config
 # overrides, disables, and insert lists; \`!!js\` expressions allowed).
@@ -494,9 +389,8 @@ autoInstallPeers: false
 * so re-running is a no-op on an initialized profile.
 * @param dir - the profile directory from {@link resolveProfileDir}.
 * @param bundles - the initial `dsh.profile.bundles` layer list.
-* @param patchReload - user patch-file lifecycle; custom profiles default to live reload.
 */
-function initProfile(dir, bundles, patchReload = DEFAULT_PROFILE_PATCH_RELOAD) {
+function initProfile(dir, bundles) {
 	mkdirSync(dir, { recursive: true });
 	const manifestPath = join(dir, "package.json");
 	if (!existsSync(manifestPath)) {
@@ -504,10 +398,7 @@ function initProfile(dir, bundles, patchReload = DEFAULT_PROFILE_PATCH_RELOAD) {
 			name: `dsh-profile-${basename(dir)}`,
 			private: true,
 			dependencies: {},
-			dsh: { profile: {
-				bundles: [...bundles],
-				patchReload
-			} }
+			dsh: { profile: { bundles: [...bundles] } }
 		};
 		writeFileSync(manifestPath, JSON.stringify(manifest, void 0, 2) + "\n");
 	}
@@ -823,6 +714,26 @@ function createProfileResolutionGeneration(options) {
 		materialize: false
 	});
 }
+/**
+* Supply an application-owned profile with filesystem packages from its installation and selected bundles.
+* All fallback links belong to the profile; no shared Harness-home directory is written.
+* Existing pnpm-managed packages remain authoritative. The caller serializes profile mutations.
+* @param options - owning installation package.json and the loaded application profile.
+*/
+function healIsolatedProfileModuleFallback(options) {
+	const installationLinks = resolveModuleFallbackEntries(options.installAnchor, false).packageDirs;
+	healProfileModuleFallback(options.profile, new Set(installationLinks.keys()), true, void 0, void 0, installationLinks);
+}
+/**
+* Detach this profile's fallback links before a package-manager mutation.
+* Installed packages and links replaced by pnpm remain untouched; the next profile launch restores fallbacks.
+* @param profileDir - profile directory whose package mutation is serialized by the caller.
+*/
+function unlinkProfileModuleFallback(profileDir) {
+	const ownedModulesDir = join(profileDir, PROFILE_MODULE_FALLBACK_DIR, "node_modules");
+	if (!existsSync(ownedModulesDir)) return;
+	for (const name of ownedPackageNames(ownedModulesDir)) removeProfileSymlink(join(profileDir, "node_modules"), ownedModulesDir, name);
+}
 /** Heal one module-fallback generation while the cross-process writer lock is held. */
 function healProfilesModuleFallbackLocked(entries, modulesDir) {
 	for (const entry of entries) {
@@ -872,7 +783,7 @@ function dependencyClosure(anchors, reserved, exclude, declarers, versions) {
 	return links;
 }
 /** Reconcile packages carried only by selected bundles into one profile. */
-function healProfileModuleFallback(profile, installationPackageNames, materialize = true, declarers, versions) {
+function healProfileModuleFallback(profile, installationPackageNames, materialize = true, declarers, versions, installationLinks = /* @__PURE__ */ new Map()) {
 	const profileModulesDir = join(profile.dir, "node_modules");
 	const ownedModulesDir = join(profile.dir, PROFILE_MODULE_FALLBACK_DIR, "node_modules");
 	if (materialize) {
@@ -892,9 +803,10 @@ function healProfileModuleFallback(profile, installationPackageNames, materializ
 		}
 	}, declarers, versions);
 	for (const layer of profile.layers) bundleLinks.delete(layer.packageName);
-	if (!materialize) return bundleLinks;
-	for (const packageName of ownedPackageNames(ownedModulesDir)) if (!bundleLinks.has(packageName)) removeProfileSymlink(profileModulesDir, ownedModulesDir, packageName);
-	for (const [packageName, target] of bundleLinks) {
+	const links = new Map([...installationLinks, ...bundleLinks]);
+	if (!materialize) return links;
+	for (const packageName of ownedPackageNames(ownedModulesDir)) if (!links.has(packageName)) removeProfileSymlink(profileModulesDir, ownedModulesDir, packageName);
+	for (const [packageName, target] of links) {
 		const ownedLink = join(ownedModulesDir, packageName);
 		mkdirSync(dirname(ownedLink), { recursive: true });
 		ensureSymlink(ownedLink, target);
@@ -902,7 +814,7 @@ function healProfileModuleFallback(profile, installationPackageNames, materializ
 		mkdirSync(dirname(profileLink), { recursive: true });
 		ensureProfileSymlink(profileLink, ownedLink);
 	}
-	return bundleLinks;
+	return links;
 }
 /**
 * Read a profile's manifest.
@@ -936,27 +848,21 @@ function sameBundles(left, right) {
 }
 /**
 * Normalize an exact installation-owned bundle tuple to its shipped template,
-* or add the shipped reload default to an exact current tuple. A changed value
-* is written back during profile loading while every other manifest field is
-* preserved; any other bundle list is user-owned and remains untouched.
+* preserving all other manifest fields. Other bundle lists remain untouched.
 */
 function normalizeShippedProfile(name, dir, manifest) {
 	const installationOwned = INSTALLATION_OWNED_PROFILE_TUPLES[name];
 	const template = PROFILE_TEMPLATES[name];
 	const bundles = manifest.dsh?.profile?.bundles;
 	if (template === void 0 || bundles === void 0) return manifest;
-	const isRetiredTuple = installationOwned !== void 0 && sameBundles(bundles, installationOwned);
-	const isCurrentTuple = sameBundles(bundles, template.bundles);
-	const needsReloadDefault = manifest.dsh?.profile?.patchReload === void 0 && isCurrentTuple;
-	if (!isRetiredTuple && !needsReloadDefault) return manifest;
+	if (!(installationOwned !== void 0 && sameBundles(bundles, installationOwned))) return manifest;
 	const normalized = {
 		...manifest,
 		dsh: {
 			...manifest.dsh,
 			profile: {
 				...manifest.dsh?.profile,
-				bundles: [...template.bundles],
-				patchReload: manifest.dsh?.profile?.patchReload ?? template.patchReload
+				bundles: [...template.bundles]
 			}
 		}
 	};
@@ -1008,12 +914,7 @@ function resolveBundleDir(binName, packageName, installAnchor, profileDir) {
 * @returns the resolved bundle layers and optional user patch layer.
 */
 function loadProfileDirectory(binName, dir, installAnchor, options = {}) {
-	const manifest = readProfileManifest(binName, dir);
-	const bundles = manifest.dsh?.profile?.bundles ?? [];
-	const rawPatchReload = manifest.dsh?.profile?.patchReload;
-	if (rawPatchReload !== void 0 && rawPatchReload !== "live" && rawPatchReload !== "startup") throw new Error(`${binName}: profile manifest ${join(dir, "package.json")} dsh.profile.patchReload must be "live" or "startup"`);
-	const patchReload = rawPatchReload ?? "live";
-	const layers = bundles.map((packageName) => {
+	const layers = (readProfileManifest(binName, dir).dsh?.profile?.bundles ?? []).map((packageName) => {
 		const packageDir = resolveBundleDir(binName, packageName, installAnchor, dir);
 		const declared = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8")).dsh?.bundle?.patch;
 		if (declared === void 0) throw new Error(`${binName}: profile bundle ${JSON.stringify(packageName)} declares no dsh.bundle in its package.json`);
@@ -1032,8 +933,7 @@ function loadProfileDirectory(binName, dir, installAnchor, options = {}) {
 		dir,
 		layers,
 		patchPath,
-		patches,
-		patchReload
+		patches
 	};
 }
 /**
@@ -1055,7 +955,7 @@ function loadProfile(binName, name, installAnchor, home = resolveDshHome(), opti
 	if (!existsSync(join(dir, "package.json"))) {
 		const template = PROFILE_TEMPLATES[name];
 		if (template === void 0) throw new Error(`${binName}: profile ${JSON.stringify(name)} does not exist; create it with 'dsh plugin --profile ${name} add <package>'`);
-		initProfile(dir, template.bundles, template.patchReload);
+		initProfile(dir, template.bundles);
 	}
 	normalizeShippedProfile(name, dir, readProfileManifest(binName, dir));
 	return loadProfileDirectory(binName, dir, installAnchor, options);
@@ -1075,6 +975,166 @@ function composeEntries(layers, warn = () => {}) {
 	});
 }
 //#endregion
+//#region lib/types/profile-context.js
+/** Launcher-owned profile locations and composition inputs. */
+const TELEMETRY_ROW_ID = "session-telemetry-otel";
+/**
+* Resolve the telemetry opt-out switch into its boot patch. ANY non-empty
+* value (including `'0'`/`'false'`) disables: a privacy switch prefers
+* off-by-mistake over on-by-mistake. A composition without the telemetry row
+* exports nothing, so the switch is then trivially satisfied and no patch is
+* generated — custom profiles need not mount telemetry to run with the
+* switch set.
+* @param disabledEnv - the raw `DSH_TELEMETRY_DISABLED` value (`undefined` when unset).
+* @param hasRow - whether the composition carries the telemetry row.
+* @returns the disable patch, or `undefined` when no hard-disable patch is required.
+*/
+function resolveTelemetryPatch(disabledEnv, hasRow) {
+	if ((disabledEnv ?? "") === "" || !hasRow) return void 0;
+	return {
+		id: TELEMETRY_ROW_ID,
+		disabled: true
+	};
+}
+/** Read current bundle and user layers with the launch-time overlays.
+* @param binName Diagnostic prefix for malformed or missing configuration.
+* @param context Data supplied by the profile launcher.
+* @param initialProfile Already loaded startup profile; omitted reads the current files.
+* @returns Detached ordered patches; this function does not update the Loader.
+*/
+function readProfilePatches(binName, context, initialProfile) {
+	const profile = initialProfile ?? loadProfileDirectory(binName, context.dir, context.installAnchor, { userLayer: false });
+	const patches = structuredClone([
+		...profile.layers.flatMap((layer) => layer.patches),
+		...initialProfile?.patches ?? loadOptionalPatches(binName, context.patchPath) ?? [],
+		...loadOptionalPatches(binName, join(context.home, "cordis.patch.yml")) ?? [],
+		...context.overlays
+	]);
+	const telemetryPatch = resolveTelemetryPatch(context.telemetryDisabledEnv, composeEntries([patches]).some((row) => row.id === TELEMETRY_ROW_ID));
+	if (telemetryPatch !== void 0) patches.push(telemetryPatch);
+	return patches;
+}
+//#endregion
+//#region lib/types/profile-plugins.js
+/** Installed profile dependencies and their bundle activation after package-manager operations. */
+/** Unavailable installed metadata must not prevent listing or removing dependencies. */
+function optionalManifest(binName, packageDir) {
+	try {
+		return readProfileManifest(binName, packageDir);
+	} catch {
+		return;
+	}
+}
+/** Resolve activation metadata with the same installation precedence as profile loading. */
+function bundleManifest(location, name) {
+	let packageDir;
+	try {
+		packageDir = resolveBundleDir(location.binName, name, location.installAnchor, location.profileDir);
+	} catch {
+		return;
+	}
+	return optionalManifest(location.binName, packageDir);
+}
+/**
+* Read installed versions and bundle declarations without requiring loadable plugin code.
+* Missing or unreadable installed metadata leaves the dependency visible for repair or removal.
+* @param location - profile and installation resolution inputs.
+* @returns dependency records in package.json order and the profile manifest.
+*/
+function readProfilePlugins(location) {
+	const manifest = readProfileManifest(location.binName, location.profileDir);
+	const bundles = manifest.dsh?.profile?.bundles ?? [];
+	return {
+		manifest,
+		dependencies: Object.entries(manifest.dependencies ?? {}).map(([name, spec]) => {
+			const installed = optionalManifest(location.binName, join(location.profileDir, "node_modules", name));
+			return {
+				name,
+				version: typeof installed?.version === "string" ? installed.version : spec,
+				bundle: bundleManifest(location, name)?.dsh?.bundle?.patch !== void 0,
+				enabled: bundles.includes(name)
+			};
+		})
+	};
+}
+/**
+* Write a bundle list while preserving the supplied profile's other metadata.
+* @param profileDir - directory whose package.json is updated.
+* @param manifest - current profile manifest, read after the package operation when applicable.
+* @param bundles - ordered active bundle names, including any template entries.
+* @returns the written manifest.
+*/
+function writeProfileBundles(profileDir, manifest, bundles) {
+	const updated = {
+		...manifest,
+		dsh: {
+			...manifest.dsh,
+			profile: {
+				...manifest.dsh?.profile,
+				bundles: [...bundles]
+			}
+		}
+	};
+	writeProfileManifest(profileDir, updated);
+	return updated;
+}
+/**
+* Reconcile installed bundle declarations after a successful package-manager operation.
+* Dependency-managed entries disappear when removed or when their package loses its declaration;
+* template entries retain their order and duplicates. New bundle dependencies activate automatically.
+* @param options - location, inventory captured before pnpm, and whether explicitly disabled bundles remain disabled.
+* @returns updated inventory and newly added ordinary dependencies for caller-owned warnings.
+*/
+function reconcileProfilePlugins(options) {
+	const after = readProfilePlugins(options);
+	const beforeNames = new Set(options.before.dependencies.map((dependency) => dependency.name));
+	const afterNames = new Set(after.dependencies.map((dependency) => dependency.name));
+	const bundleNames = new Set(after.dependencies.filter((dependency) => dependency.bundle).map((dependency) => dependency.name));
+	const disabled = new Set(options.preserveDisabled ? options.before.dependencies.filter((dependency) => dependency.bundle && !dependency.enabled).map((dependency) => dependency.name) : []);
+	const previous = after.manifest.dsh?.profile?.bundles ?? [];
+	const bundles = previous.filter((name) => !(beforeNames.has(name) || afterNames.has(name)) || bundleNames.has(name));
+	for (const dependency of after.dependencies) if (dependency.bundle && !disabled.has(dependency.name) && !bundles.includes(dependency.name)) bundles.push(dependency.name);
+	return {
+		plugins: {
+			manifest: bundles.length !== previous.length || bundles.some((name, index) => name !== previous[index]) ? writeProfileBundles(options.profileDir, after.manifest, bundles) : after.manifest,
+			dependencies: after.dependencies.map((dependency) => ({
+				...dependency,
+				enabled: bundles.includes(dependency.name)
+			}))
+		},
+		addedPlainDependencies: after.dependencies.filter((dependency) => !dependency.bundle && !beforeNames.has(dependency.name)).map((dependency) => dependency.name)
+	};
+}
+//#endregion
+//#region lib/types/profile-sanitize.js
+/** Filesystem recovery for callers that own profile shutdown and write exclusion. */
+/**
+* Back up the profile patch and retain only the caller's recovery bundles.
+* The caller must stop the profile and exclude concurrent profile writes.
+* Installed packages and other manifest fields are preserved; patches are never parsed.
+* Failures propagate and may leave completed changes in place for a retry.
+* @param binName - Diagnostic prefix for invalid profile manifests.
+* @param profileDir - Profile directory to recover without loading its plugins.
+* @param bundles - Ordered bundles to enable after recovery.
+* @returns Backup path with a Unix millisecond timestamp and optional collision ordinal, or undefined if absent.
+*/
+function sanitizeProfile(binName, profileDir, bundles) {
+	const manifest = existsSync(join(profileDir, "package.json")) ? readProfileManifest(binName, profileDir) : void 0;
+	const patchPath = join(profileDir, PROFILE_PATCH_FILENAME);
+	const backupBase = `${patchPath}.bak-${Date.now()}`;
+	let backupPath = backupBase;
+	let ordinal = 0;
+	while (existsSync(backupPath)) backupPath = `${backupBase}-${++ordinal}`;
+	try {
+		renameSync(patchPath, backupPath);
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+		backupPath = void 0;
+	}
+	if (manifest !== void 0) writeProfileBundles(profileDir, manifest, bundles);
+	return backupPath;
+}
+//#endregion
 //#region lib/types/profile-resolution/resolver.js
 /** In-memory profile package routing for Node's default ESM and CommonJS loaders. */
 const WORKER_RESOLUTION_KEY = "@deepseek-ai/dsh-app-boot/profile-resolution";
@@ -2061,37 +2121,38 @@ function loadLayeredEnv(binName, cwd = process.cwd(), warn = (line) => void proc
 }
 const bootstrapIncludes = /* @__PURE__ */ new WeakMap();
 const userPatchesSchema = entryListSchema;
-/**
-* Watch the user patch layer and reapply it to the boot Include without rollback.
-* @param ctx - settled app context containing the root Include and an active HMR service.
-* @param options - diagnostic, file, and patch-composition inputs.
-* @returns an asynchronous disposer after the exact-path watcher is ready.
-* @throws when HMR or the root Include is absent, watcher setup fails, or initial path resolution fails.
+/** Apply one complete patch generation and wait for Loader activation diagnostics.
+* @param ctx Booted root context.
+* @param patches Complete ordered patch list.
+* @param binName Diagnostic prefix.
+* @param requiredIds Explicit enablement targets whose existing failures also reject reconciliation.
+* @returns Diagnostics for unchanged pre-existing inactive entries; new or changed failures reject.
 */
-async function watchUserPatches(ctx, options) {
-	const { binName, filename, compose = (patches) => patches } = options;
-	const hmr = ctx.get("hmr");
-	if (hmr === void 0) throw new Error(`${binName}: user patch-layer watching requires the Cordis HMR service`);
+async function reconcileProfilePatches(ctx, patches, binName, requiredIds = []) {
 	const entry = bootstrapIncludes.get(ctx);
-	if (entry === void 0) throw new Error(`${binName}: user patch-layer watching requires the root Include entry`);
-	const register = watchConfig(ctx, filename, hmr.config, async () => {
-		const { patches: _previousPatches, ...includeConfig } = entry.options.config;
-		const patches = compose(loadOptionalPatches(binName, filename) ?? []);
-		await entry.update({ config: {
-			...includeConfig,
-			patches
-		} });
-		await ctx.loader.await();
-		await Promise.allSettled([...ctx.loader.entries()].map((entry) => Promise.resolve(entry.fiber?.await())));
-		const failures = await inactiveEntries(ctx);
-		if (failures.length > 0) throw new Error(activationDiagnostic(binName, "warning", failures).trimEnd());
-	});
-	try {
-		return await register;
-	} catch (error) {
-		if (error?.code === "INACTIVE_EFFECT") return async () => {};
-		throw error;
-	}
+	if (entry === void 0) throw new Error(`${binName}: profile reload requires the root Include entry`);
+	const previousFailures = (await inactiveEntries(ctx)).map((failure) => ({
+		...failure,
+		diagnostic: inactiveDiagnostic(failure),
+		fiber: failure.entry.fiber,
+		options: JSON.stringify(failure.entry.options)
+	}));
+	const previousFibers = [...ctx.loader.entries()].flatMap((row) => row.fiber === void 0 ? [] : [{
+		fiber: row.fiber,
+		failed: row.fiber.state === FIBER_FAILED || row.fiber.state === FIBER_DISPOSED
+	}]);
+	const { patches: _previous, ...includeConfig } = entry.options.config;
+	await entry.update({ config: {
+		...includeConfig,
+		patches
+	} });
+	const results = await Promise.allSettled(previousFibers.map(({ fiber }) => fiber.await()));
+	await ctx.loader.await();
+	const failures = await inactiveEntries(ctx);
+	const introduced = failures.filter((failure) => requiredIds.includes(failure.entry.options.id) || !previousFailures.some((previous) => previous.entry === failure.entry && previous.fiber === failure.entry.fiber && previous.options === JSON.stringify(failure.entry.options) && previous.diagnostic === inactiveDiagnostic(failure)));
+	if (introduced.length > 0) throw new Error(activationDiagnostic(binName, introduced).trimEnd());
+	for (const [index, result] of results.entries()) if (result.status === "rejected" && !previousFibers[index]?.failed) throw result.reason;
+	return failures.map(inactiveDiagnostic);
 }
 /**
 * Load an optional patch-list file: a top-level YAML array of loader patch
@@ -2392,12 +2453,12 @@ function installFailLoud(binName, proc = process, release) {
 }
 /**
 * Value mirrors used because Cordis's const enum has no runtime object to import.
-* Keep aligned with `packages/extensions/tool-cordis/src/fiber-state.ts` and
-* `packages/client/web/src/loader-status.ts`.
+* Keep aligned with `packages/client/web/src/loader-status.ts`.
 */
 const FIBER_PENDING = 0;
 const FIBER_ACTIVE = 2;
 const FIBER_FAILED = 3;
+const FIBER_DISPOSED = 4;
 /**
 * Entry ids whose presence defines a usable DSH application.
 *
@@ -2432,6 +2493,25 @@ function formatActivationError(error) {
 	visit(error);
 	return details.join("\n");
 }
+/** Startup audit failure with non-enumerable metadata and original failures as its cause. */
+var StartupError = class extends Error {
+	entries;
+	/** Root configuration and startup logs, attached by boot after disposal. */
+	startup;
+	/**
+	* @param message - concise terminal diagnostic.
+	* @param entries - inactive plugin metadata and original failure values.
+	*/
+	constructor(message, entries) {
+		const failures = entries.flatMap(({ outcome }) => outcome.kind === "failed" ? [outcome.error] : []);
+		super(message, failures.length > 0 ? { cause: new AggregateError(failures, "Plugin activation failures") } : void 0);
+		this.entries = entries;
+		Object.defineProperties(this, {
+			entries: { enumerable: false },
+			startup: { enumerable: false }
+		});
+	}
+};
 /**
 * Collect Loader activation failures and disabled-expression errors. Failed
 * fibers are awaited to recover their recorded rejection reason and coalesce
@@ -2441,13 +2521,16 @@ async function inactiveEntries(ctx) {
 	const failures = [];
 	const rejectionReasons = [];
 	for (const entry of ctx.loader.entries()) {
-		const subject = `${entry.options.id} (${entry.options.name})`;
 		try {
 			if (entry.disabled) continue;
 		} catch (error) {
 			failures.push({
 				entry,
-				diagnostic: `${subject}: disabled expression failed: ${formatActivationError(error)}`
+				outcome: {
+					kind: "failed",
+					error,
+					phase: "disabled expression failed"
+				}
 			});
 			continue;
 		}
@@ -2455,7 +2538,10 @@ async function inactiveEntries(ctx) {
 		if (fiber === void 0) {
 			failures.push({
 				entry,
-				diagnostic: `${subject}: failed to import`
+				outcome: {
+					kind: "failed",
+					error: "failed to import"
+				}
 			});
 			continue;
 		}
@@ -2468,7 +2554,10 @@ async function inactiveEntries(ctx) {
 				rejectionReasons.push(error);
 				failures.push({
 					entry,
-					diagnostic: `${subject}: ${formatActivationError(error)}`
+					outcome: {
+						kind: "failed",
+						error
+					}
 				});
 			}
 			continue;
@@ -2477,42 +2566,90 @@ async function inactiveEntries(ctx) {
 			const missing = Object.keys(fiber.inject).filter((service) => fiber.ctx.get(service) === void 0);
 			failures.push({
 				entry,
-				diagnostic: `${subject}: pending (waiting for ${missing.length === 1 ? "service" : "services"}: ${missing.join(", ") || "unknown"})`
+				outcome: {
+					kind: "pending",
+					missing
+				}
 			});
 		} else failures.push({
 			entry,
-			diagnostic: `${subject}: fiber state ${String(state)}`
+			outcome: {
+				kind: "failed",
+				error: `fiber state ${String(state)}`
+			}
 		});
 	}
 	if (rejectionReasons.length > 0) await observeLoaderRejectionCheckpoint(rejectionReasons);
 	return failures;
 }
-/** Render an inactive-entry diagnostic with a count and severity label. */
-function activationDiagnostic(binName, severity, failures) {
+/** Render one failed plugin's original error and activation phase. */
+function failureDetail(outcome) {
+	return `${outcome.phase === void 0 ? "" : `${outcome.phase}: `}${formatActivationError(outcome.error)}`;
+}
+/** Render optional-only warnings without changing startup policy. */
+function activationDiagnostic(binName, failures) {
 	const noun = failures.length === 1 ? "entry" : "entries";
-	return `${binName === "" ? "" : `${binName}: `}${severity}: ${String(failures.length)} ${noun} did not activate\n${failures.map((failure) => failure.diagnostic).join("\n")}\n`;
+	return `${binName}: warning: ${String(failures.length)} ${noun} did not activate\n${failures.map(inactiveDiagnostic).join("\n")}\n`;
+}
+/** Stable per-entry text for reload comparisons and optional warnings. */
+function inactiveDiagnostic({ entry, outcome }) {
+	const detail = outcome.kind === "failed" ? failureDetail(outcome) : `pending (waiting for ${outcome.missing.length === 1 ? "service" : "services"}: ${outcome.missing.join(", ") || "unknown"})`;
+	return `${entry.options.id} (${entry.options.name}): ${detail}`;
+}
+/** Group startup failures and pending services, marking every required entry. */
+function startupDiagnostic(binName, failures, required) {
+	const lines = [`${binName}: startup failed: ${String(required.size)} required ${required.size === 1 ? "plugin" : "plugins"} did not activate`];
+	const failed = failures.flatMap(({ entry, outcome }) => outcome.kind === "failed" ? [{
+		entry,
+		outcome
+	}] : []);
+	const pending = failures.flatMap(({ entry, outcome }) => outcome.kind === "pending" ? [{
+		entry,
+		outcome
+	}] : []);
+	pending.sort((left, right) => Number(required.has(right.entry)) - Number(required.has(left.entry)));
+	const label = (entry) => `${entry.options.id}${required.has(entry) ? " (required)" : ""}`;
+	if (failed.length > 0) {
+		lines.push("", `Failed plugins (${String(failed.length)}):`);
+		for (const { entry, outcome } of failed) {
+			lines.push(`  ${label(entry)}`, `    Package: ${entry.options.name}`);
+			lines.push(...failureDetail(outcome).split("\n").map((line) => `    ${line}`));
+		}
+	}
+	if (pending.length > 0) {
+		const width = Math.max(6, ...pending.map(({ entry }) => label(entry).length)) + 2;
+		lines.push("", `Plugins waiting for services (${String(pending.length)}):`, `  ${"Plugin".padEnd(width)}Missing services`);
+		for (const { entry, outcome } of pending) lines.push(`  ${label(entry).padEnd(width)}${outcome.missing.join(", ") || "unknown"}`);
+	}
+	return lines.join("\n");
 }
 /**
 * Apply DSH startup policy to a settled Loader tree.
 *
 * Inactive entries from the global required list reject startup. Other
-* inactive entries produce one warning and leave successful siblings running.
+* inactive entries join that failure diagnostic, or produce one warning when
+* no required entry failed and leave successful siblings running.
 * Required ids absent from the tree, and disabled required entries, are ignored.
 * A throwing disabled expression is an entry failure, not a disabled entry.
 * The bootstrap Include must activate so unreadable or invalid root config is fatal.
 * @param ctx - the settled context whose Loader entries to audit.
-* @param binName - the diagnostic prefix on optional-entry warnings.
+* @param binName - the prefix on startup diagnostics.
 * @param warn - sink for optional-entry warnings.
 * @returns after optional warnings if required startup checks pass.
-* @throws when the bootstrap Include or a required entry is inactive or its disabled expression throws.
+* @throws {@link StartupError} when the bootstrap Include or a required entry is inactive or its disabled expression throws;
+* its message includes optional failures too.
 */
 async function auditStartupEntries(ctx, binName, warn = (line) => void process.stderr.write(line)) {
 	const failures = await inactiveEntries(ctx);
-	const required = [];
-	const optional = [];
-	for (const failure of failures) (failure.entry === bootstrapIncludes.get(ctx) || requiredStartupEntryIds.has(failure.entry.options.id) ? required : optional).push(failure);
-	if (optional.length > 0) warn(activationDiagnostic(binName, "warning", optional));
-	if (required.length > 0) throw new Error(activationDiagnostic("", "required startup failure", required).trimEnd());
+	const required = new Set(failures.filter(({ entry }) => entry === bootstrapIncludes.get(ctx) || requiredStartupEntryIds.has(entry.options.id)).map(({ entry }) => entry));
+	if (required.size > 0) throw new StartupError(startupDiagnostic(binName, failures, required), failures.map(({ entry, outcome }) => ({
+		id: entry.options.id,
+		module: entry.options.name,
+		required: required.has(entry),
+		fiberState: entry.fiber?.state,
+		outcome
+	})));
+	if (failures.length > 0) warn(activationDiagnostic(binName, failures));
 }
 /**
 * Boot the Loader against `absoluteConfigPath` and return only after the whole
@@ -2539,13 +2676,28 @@ async function auditStartupEntries(ctx, binName, warn = (line) => void process.s
 * complete plugin set.
 * @returns the root context after the initial startup audit, or as soon as a
 * surface disposed the tree while startup was still in flight.
-* @throws a labelled error after disposing the partial context — `host
+* @throws {@link StartupError} for an inactive required entry, including all inactive plugins in its message;
+* otherwise a labelled error after disposing the partial context — `host
 * preparation failed` when `prepare` threw before any config-tree entry
 * mounted, `plugin tree failed to load` afterwards. Cyclic causes terminate
 * diagnostic traversal without replacing the original cause.
 */
 async function boot(binName, absoluteConfigPath, patches, prepare, bareModuleBaseUrl) {
 	const ctx = new Context();
+	const startupLogs = [];
+	const diagnostics = new Context();
+	diagnostics.logger = ctx.logger;
+	diagnostics.logger.exporter({
+		levels: { default: 2 },
+		export: ({ ts, name, type, args }) => {
+			if (type === "warn" || type === "error") startupLogs.push({
+				ts,
+				name,
+				type,
+				args
+			});
+		}
+	});
 	let stage = "host preparation failed";
 	try {
 		ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + "/";
@@ -2568,6 +2720,13 @@ async function boot(binName, absoluteConfigPath, patches, prepare, bareModuleBas
 		return ctx;
 	} catch (cause) {
 		await ctx.fiber.dispose();
+		if (cause instanceof StartupError) {
+			cause.startup = {
+				configurationPath: absoluteConfigPath,
+				messages: startupLogs
+			};
+			throw cause;
+		}
 		const detail = cause instanceof Error ? cause.message : String(cause);
 		let deepest = cause;
 		const seen = /* @__PURE__ */ new Set();
@@ -2577,6 +2736,8 @@ async function boot(binName, absoluteConfigPath, patches, prepare, bareModuleBas
 		}
 		const stack = deepest instanceof AggregateError ? `\n${deepest.stack ?? deepest.message}\n${deepest.errors.map(formatActivationError).join("\n")}` : deepest instanceof Error && deepest !== cause ? `\n${deepest.stack ?? deepest.message}` : "";
 		throw new Error(`${binName}: ${stage}: ${detail}${stack}`, { cause });
+	} finally {
+		await diagnostics.fiber.dispose();
 	}
 }
 /** Prompt-section name for the harness-source location line an app bin adds after boot. */
@@ -2606,4 +2767,4 @@ function addHarnessSourceSection(ctx, sourceRoot) {
 	});
 }
 //#endregion
-export { DEFAULT_PROFILE_BUNDLES, DEFAULT_PROFILE_PATCH_RELOAD, FAIL_LOUD_RELEASE_TIMEOUT_MS, HARNESS_SOURCE_SECTION, PROFILES_DIR, PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PluginPackages, addHarnessSourceSection, auditStartupEntries, boot, composeEntries, createProfileResolutionGeneration, healProfilesModuleFallback, initProfile, installFailLoud, loadEnv, loadLayeredEnv, loadOptionalPatches, loadOverlayPatches, loadProfile, loadProfileDirectory, mountRootInclude, readProfileManifest, renderConfigDump, resolveBundleDir, resolveConfigPath, resolveProfileDir, watchUserPatches, writeProfileManifest };
+export { DEFAULT_PROFILE_BUNDLES, FAIL_LOUD_RELEASE_TIMEOUT_MS, HARNESS_SOURCE_SECTION, OPTIONAL_BUNDLES, PROFILES_DIR, PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PluginPackages, StartupError, addHarnessSourceSection, auditStartupEntries, boot, composeEntries, createProfileResolutionGeneration, healIsolatedProfileModuleFallback, healProfilesModuleFallback, initProfile, installFailLoud, loadEnv, loadLayeredEnv, loadOptionalPatches, loadOverlayPatches, loadProfile, loadProfileDirectory, mountRootInclude, readProfileManifest, readProfilePatches, readProfilePlugins, reconcileProfilePatches, reconcileProfilePlugins, renderConfigDump, resolveBundleDir, resolveConfigPath, resolveProfileDir, resolveTelemetryPatch, sanitizeProfile, unlinkProfileModuleFallback, writeProfileBundles, writeProfileManifest };