@khorsheed/dsh-local-agent-dsh 0.2.0-rc.1 → 0.2.0

package/lib/provision.js

@@ -1,7 +1,6 @@
 import { createRequire } from "node:module";
-import { dirname, isAbsolute, join } from "node:path";
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import yaml from "js-yaml";
 //#region lib/types/provision.js
 /**
@@ -11,29 +10,38 @@ import yaml from "js-yaml";
 * `<scoped home>/profiles/<name>` — a manifest listing the official
 * `@deepseek-ai/dsh-base` layer, the family headless composition as the
 * profile's own patch layer (copied verbatim from the headless bundle's
-* `cordis.patch.yml`), and a single symlink resolving
-* `@khorsheed/dsh-local-agent-dsh-headless` from the sub-profile's
-* node_modules (the loader resolves the patch's insert rows through it).
+* `cordis.patch.yml`), and `@khorsheed/dsh-local-agent-dsh-headless` in
+* the sub-profile's node_modules (the loader resolves the patch's insert
+* rows through it) — a copy of the bundle for the host profile, a symlink
+* for the `-unit` twin and for the pinned single-profile form (see
+* `HeadlessBundleMount`).
 * Everything else the boot needs (dsh-base and its whole dependency graph,
 * cordis, the healed `profiles/node_modules` fallback) is resolved from the
 * dsh installation anchor automatically, so provisioning costs no pnpm
 * install.
 *
-* A sub-profile may additionally carry a PRESET ROSTER: one appended patch
-* layer inserting `@deepseek-ai/dsh-agent-presets` with a `default` preset
-* id. Without it the sub-dsh's model-facing rows come from the host plane and
-* the agent reads them off the global layer — which is why "the same harness
-* under two presets" was not a thing a condition could ask for. With it, the
-* scope directory IS the capability face: two scopes whose rosters name two
-* presets are two subjects, and the difference is a file a person can read.
+* A sub-profile may additionally compose an AGENT PRESET (host 0.2.0's
+* declarative form): the bundle package that declares the preset — an
+* `@deepseek-ai/dsh-agent-preset` row in its own bundle patch — joins the
+* manifest's bundle list, and one appended patch layer inserts
+* `@deepseek-ai/dsh-agent-preset-registry` with that preset as its
+* `default`. Without it the sub-dsh's model-facing rows come from the host
+* plane and the agent reads them off the global layer — which is why "the
+* same harness under two presets" was not a thing a condition could ask for.
+* With it, the scope directory IS the capability face: two scopes naming two
+* presets are two subjects, and the difference is files a person can read.
 *
-* Where the preset DIRECTORY lives is the scope's business too. The roster
-* derives a user root of `<$DSH_HOME>/.agent-presets` and the sub-dsh runs
-* with `DSH_HOME` pointed at the scoped home, so a scope that keeps its own
-* copy there is resolved identically on the host and inside an evaluation
-* unit (which bind-mounts the scope, and nothing else). `provisionDshScope`
-* below is the entry that puts the copy there, records what the scope
-* composes in a file of its own, and rosters it with no `roots` at all.
+* Where the preset PACKAGE lives is the scope's business too. The scope keeps
+* its own copy at `<scoped home>/preset-packages/<id>` and the sub-profile
+* resolves it through a RELATIVE symlink in its own `node_modules`, so the
+* package is found identically on the host and inside an evaluation unit
+* (which bind-mounts the scope, and nothing else). The copy comes from the
+* evaluation instance's own installation of the same package, which is also
+* what the instance's capability catalog measures. `provisionDshScope` below
+* is the entry that makes the copy, records what the scope composes in a
+* file of its own, and composes it. (0.1.x wrote a roster row for
+* `@deepseek-ai/dsh-agent-presets` and a `<scoped home>/.agent-presets/<id>`
+* directory instead; 0.2.0 ships neither the roster nor the directory scan.)
 *
 * It may also carry a PERMISSION BOUNDARY: one appended patch layer pinning
 * `sandbox-policy`'s mode and `user-approval`'s policy to one of dsh's own
@@ -42,7 +50,7 @@ import yaml from "js-yaml";
 * sub-dsh on a developer's machine and the wrong one inside an evaluation
 * unit, where the container IS the boundary and nobody is there to answer an
 * approval prompt. The layer is a FILE in the scope directory for the same
-* reason the roster is: a scoped home bind-mounted into a unit carries its
+* reason the preset layer is: a scoped home bind-mounted into a unit carries its
 * own boundary with it, and the value never has to ride the spawn env (where
 * every name enters the unit's composite fingerprint) or be baked into an
 * image.
@@ -74,40 +82,44 @@ const APPROVAL_FOR = {
 	"workspace-write": "ask",
 	"danger-full-access": "never"
 };
-/** The roster row's id inside the sub-profile patch (and the marker this module rewrites). */
-const PRESET_ROSTER_ROW_ID = "agent-presets";
+/** The registry row's id inside the sub-profile patch. */
+const PRESET_REGISTRY_ROW_ID = "agent-preset-registry";
 /**
-* The roster package the roster row names.
+* The registry package the registry row names.
 *
 * Deliberately NOT symlinked into the sub-profile the way the headless bundle
 * is. The headless bundle is a `@khorsheed` package the dsh installation does
-* not carry, so it must be linked in from the plugin installation; the roster
-* is an OFFICIAL package, already in the installation anchor's closure beside
-* `@deepseek-ai/dsh-base`. Linking a second copy would give it a second
-* `@deepseek-ai/cordis` — and cordis does service lookup and type checks by
-* instance identity, so the symptom would be silently missing services rather
-* than an error (the same failure the dual-filesystem contract in the README
-* describes for the bundle). A deployment whose anchor genuinely lacks the
-* roster gets the loader's own "cannot resolve" message, which names the
+* not carry, so it must be linked in from the plugin installation; the
+* registry is an OFFICIAL package, already in the installation anchor's
+* closure beside `@deepseek-ai/dsh-base`. Linking a second copy would give it
+* a second `@deepseek-ai/cordis` — and cordis does service lookup and type
+* checks by instance identity, so the symptom would be silently missing
+* services rather than an error. A deployment whose anchor genuinely lacks the
+* registry gets the loader's own "cannot resolve" message, which names the
 * module better than provisioning could.
 */
-const PRESET_ROSTER_MODULE = "@deepseek-ai/dsh-agent-presets";
-/** A preset id doubles as a directory name — the roster's own rule. */
+const PRESET_REGISTRY_MODULE = "@deepseek-ai/dsh-agent-preset-registry";
+/** The declarative preset row a preset bundle package carries in its patch. */
+const PRESET_ROW_MODULE = "@deepseek-ai/dsh-agent-preset";
+/** A preset id doubles as a directory name inside the scope. */
 const SUB_PROFILE_PRESET_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
-/** Header line that opens the generated roster layer (the parse anchor). */
-const PRESET_BLOCK_HEADER = "# --- preset roster (written by local-agent-dsh provisioning) ---";
+/** An npm package name the sub-profile manifest may list as a bundle. */
+const PACKAGE_NAME_RE = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+/** Header line that opens the generated preset layer (the parse anchor). */
+const PRESET_BLOCK_HEADER = "# --- agent preset (written by local-agent-dsh provisioning) ---";
 /** Header line that opens the generated permission layer (the parse anchor). */
 const PERMISSION_BLOCK_HEADER = "# --- permission boundary (written by local-agent-dsh provisioning) ---";
 /** The sub-profile's bundle layer list: the official base layer. The headless
 * composition rides the profile's own patch layer (see the module doc). */
 const SUB_PROFILE_BUNDLES = ["@deepseek-ai/dsh-base"];
 /** The sub-profile manifest the boot reads. */
-function subProfileManifest(profileName) {
+function subProfileManifest(profileName, presetPackage) {
+	const bundles = presetPackage === void 0 ? [...SUB_PROFILE_BUNDLES] : [...SUB_PROFILE_BUNDLES, presetPackage];
 	return JSON.stringify({
 		name: `dsh-profile-${profileName}`,
 		private: true,
 		dependencies: {},
-		dsh: { profile: { bundles: [...SUB_PROFILE_BUNDLES] } }
+		dsh: { profile: { bundles } }
 	}, void 0, 2) + "\n";
 }
 /**
@@ -122,55 +134,51 @@ function resolveHeadlessBundleDir(config = {}) {
 	const manifestPath = createRequire(import.meta.url).resolve("@khorsheed/dsh-local-agent-dsh-headless/package.json");
 	return dirname(manifestPath);
 }
-/** YAML-quote a scalar the roster config carries (paths and ids are operator input). */
+/** YAML-quote a scalar the generated layers carry (ids are operator input). */
 function yamlString(value) {
 	return JSON.stringify(value);
 }
 /**
-* The roster layer appended to the sub-profile's patch, or `''` when the
+* The preset layer appended to the sub-profile's patch, or `''` when the
 * sub-profile composes no preset.
 *
+* One insert of the 0.2.0 preset registry with the preset as its `default`:
+* every sub-dsh session that names no preset joins this one (the headless
+* agent loader mounts it through the registry's `mount`). The preset's own
+* declaration rides the bundle layer — the package that declares it is in
+* the manifest's bundle list — so this layer never repeats the composition.
+*
 * It is a SEPARATE patch operation appended after the headless bundle's own
 * list, which is what keeps the two independent: an upgraded headless bundle
-* rewrites its half and the roster survives, and dropping the preset drops
+* rewrites its half and the preset survives, and dropping the preset drops
 * exactly these lines.
-* @param preset - the roster to compose, or undefined for none.
+* @param preset - the preset to compose, or undefined for none.
 * @returns the YAML text to append (already newline-terminated), or `''`.
 */
-function presetRosterLayer(preset) {
+function presetRegistryLayer(preset) {
 	if (preset === void 0) return "";
 	if (!SUB_PROFILE_PRESET_ID_RE.test(preset.id)) throw new Error(`provision-dsh: preset id ${JSON.stringify(preset.id)} must match ${String(SUB_PROFILE_PRESET_ID_RE)} (it is a directory name)`);
-	const lines = [
+	return `${[
 		"",
 		PRESET_BLOCK_HEADER,
 		"# The sub-dsh composes every session from this preset; the headless agent",
-		"# loader joins the roster in its agent setup. Remove this layer and the",
-		"# agent falls back to the global layer.",
+		"# loader mounts it through the registry. Remove this layer and the agent",
+		"# falls back to the global layer.",
 		"- insert:",
-		`    - id: ${PRESET_ROSTER_ROW_ID}`,
-		`      name: '${PRESET_ROSTER_MODULE}'`,
+		`    - id: ${PRESET_REGISTRY_ROW_ID}`,
+		`      name: '${PRESET_REGISTRY_MODULE}'`,
 		"      config:",
 		`        default: ${yamlString(preset.id)}`
-	];
-	if (preset.includeShippedRoot !== void 0) lines.push(`        includeShippedRoot: ${String(preset.includeShippedRoot)}`);
-	if (preset.includeUserRoot !== void 0) lines.push(`        includeUserRoot: ${String(preset.includeUserRoot)}`);
-	if (preset.roots !== void 0 && preset.roots.length > 0) {
-		lines.push("        roots:");
-		for (const root of preset.roots) {
-			lines.push(`          - path: ${yamlString(root.path)}`);
-			if (root.trust !== void 0) lines.push(`            trust: ${root.trust}`);
-		}
-	}
-	return `${lines.join("\n")}\n`;
+	].join("\n")}\n`;
 }
 /**
 * The preset id a provisioned sub-profile's patch composes, read back from
-* the file. The roster layer is generated, so it is also parseable: a lock
+* the file. The preset layer is generated, so it is also parseable: a lock
 * check or a status surface can answer "which preset does this scope run?"
 * without booting the sub-dsh.
 * @param homeDir - the harness scoped home.
 * @param profileName - the sub-profile name (default {@link DEFAULT_SUB_PROFILE_NAME}).
-* @returns the preset id, or undefined when the sub-profile composes no roster.
+* @returns the preset id, or undefined when the sub-profile composes no preset.
 */
 function readSubProfilePreset(homeDir, profileName = DEFAULT_SUB_PROFILE_NAME) {
 	const patchPath = join(homeDir, "profiles", profileName, PROFILE_PATCH_FILENAME);
@@ -267,57 +275,114 @@ function ensureSymlink(link, target) {
 	rmSync(link, { force: true });
 	symlinkSync(target, link);
 }
+/** Suffix of the evaluation-unit twin of a sub-profile (see `unitHeadlessBundleDir`). */
+const UNIT_PROFILE_SUFFIX = "-unit";
+/**
+* The profile name an evaluation UNIT launches for this config: the
+* `-unit` twin when one is configured, else the one sub-profile.
+* @param config - provisioning config.
+* @returns the profile name a container round passes to `--profile`.
+*/
+function unitSubProfileName(config = {}) {
+	const profileName = config.profileName ?? "headless-local-agent-dsh";
+	return config.unitHeadlessBundleDir === void 0 ? profileName : `${profileName}${UNIT_PROFILE_SUFFIX}`;
+}
+/** Write one file only when its content differs. */
+function writeIfChanged(path, content) {
+	if (!existsSync(path) || readFileSync(path, "utf8") !== content) writeFileSync(path, content);
+}
+/**
+* Make `target` a byte-for-byte copy of the headless bundle `source`. A
+* symlink left by an earlier scheme is replaced; an identical copy is left
+* untouched, so re-provisioning before every round costs one comparison.
+*/
+function ensureBundleCopy(target, source) {
+	let stat;
+	try {
+		stat = lstatSync(target);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	if (stat?.isSymbolicLink() === true) rmSync(target, { force: true });
+	else if (stat !== void 0 && presetTreesEqual(source, target)) return;
+	if (presetTreeFiles(source) === void 0) throw new Error(`provision-dsh: headless bundle ${source} is missing or not a plain tree of files`);
+	mirrorPresetTree(source, target);
+}
+/** Provision one sub-profile directory against one headless bundle directory. */
+function provisionOneSubProfile(homeDir, profileName, bundleDir, patchSourceDir, config, mount) {
+	const profileDir = join(homeDir, "profiles", profileName);
+	mkdirSync(profileDir, { recursive: true });
+	const presetPackage = config.preset?.package;
+	if (presetPackage !== void 0 && !PACKAGE_NAME_RE.test(presetPackage)) throw new Error(`provision-dsh: preset package name ${JSON.stringify(presetPackage)} is not an npm package name`);
+	writeIfChanged(join(profileDir, "package.json"), subProfileManifest(profileName, presetPackage));
+	writeIfChanged(join(profileDir, PROFILE_PATCH_FILENAME), readFileSync(join(patchSourceDir, HEADLESS_PATCH_FILENAME), "utf8") + presetRegistryLayer(config.preset) + permissionBoundaryLayer(config.permissions) + (config.inheritModelConfiguration ? "\n# Selected local model; values and credentials stay in the launch environment.\n- id: llm-pi-ai\n  config:\n    providers: !!js JSON.parse(process.env.DSH_LOCAL_AGENT_MODEL_CONFIG || \"{}\").piAi?.providers ?? {}\n- id: llm-deepseek\n  config: !!js JSON.parse(process.env.DSH_LOCAL_AGENT_MODEL_CONFIG || \"{}\").deepseek ?? {}\n" : ""));
+	const bundleLink = join(profileDir, "node_modules", "@khorsheed", "dsh-local-agent-dsh-headless");
+	mkdirSync(dirname(bundleLink), { recursive: true });
+	if (mount === "copy") ensureBundleCopy(bundleLink, bundleDir);
+	else ensureSymlink(bundleLink, bundleDir);
+	if (presetPackage !== void 0 && config.preset !== void 0) {
+		const presetLink = join(profileDir, "node_modules", ...presetPackage.split("/"));
+		mkdirSync(dirname(presetLink), { recursive: true });
+		ensureSymlink(presetLink, relative(dirname(presetLink), scopePresetPackageDir(homeDir, config.preset.id)));
+	}
+	return profileDir;
+}
 /**
 * Provision (idempotently) the sub-dsh headless profile in the harness
 * scoped home: manifest, the headless patch as the profile's own patch
-* layer, and the bundle symlink. A file whose content already matches is
-* left untouched, so re-running after a restart is a no-op; a drifted file
-* (an upgraded headless bundle, or a profile provisioned by the pre-T6
-* scheme whose manifest listed the headless bundle as a layer) is rewritten,
-* which heals it before the sub-dsh boots.
+* layer, and the headless bundle (a copy; a symlink in the `-unit` twin or under a lone `headlessBundleDir` pin) — plus, when a preset package is composed,
+* the relative link resolving it from the scope's own copy, and, when
+* `unitHeadlessBundleDir` is configured, the `-unit` twin a container round
+* launches. A file whose content already matches is left untouched, so
+* re-running after a restart is a no-op; a drifted file (an upgraded headless
+* bundle, or a profile provisioned by an earlier scheme) is rewritten, which
+* heals it before the sub-dsh boots.
 * @param homeDir - the `dsh` harness's scoped home (its `$DSH_HOME` root).
 * @param config - profile naming and bundle-dir overrides.
-* @returns the absolute sub-profile directory.
+* @returns the absolute (host) sub-profile directory.
 */
 function provisionDshSubProfile(homeDir, config = {}) {
 	const profileName = config.profileName ?? "headless-local-agent-dsh";
-	const bundleDir = resolveHeadlessBundleDir(config);
-	const profileDir = join(homeDir, "profiles", profileName);
-	mkdirSync(profileDir, { recursive: true });
-	const manifestPath = join(profileDir, "package.json");
-	const manifestContent = subProfileManifest(profileName);
-	if (!existsSync(manifestPath) || readFileSync(manifestPath, "utf8") !== manifestContent) writeFileSync(manifestPath, manifestContent);
-	const patchPath = join(profileDir, PROFILE_PATCH_FILENAME);
-	const patchContent = readFileSync(join(bundleDir, HEADLESS_PATCH_FILENAME), "utf8") + presetRosterLayer(config.preset) + permissionBoundaryLayer(config.permissions);
-	if (!existsSync(patchPath) || readFileSync(patchPath, "utf8") !== patchContent) writeFileSync(patchPath, patchContent);
-	const bundleLink = join(profileDir, "node_modules", "@khorsheed", "dsh-local-agent-dsh-headless");
-	mkdirSync(dirname(bundleLink), { recursive: true });
-	ensureSymlink(bundleLink, bundleDir);
+	const hostBundleDir = resolveHeadlessBundleDir(config);
+	const unitDir = config.unitHeadlessBundleDir;
+	const profileDir = provisionOneSubProfile(homeDir, profileName, hostBundleDir, hostBundleDir, config, config.headlessBundleDir !== void 0 && unitDir === void 0 ? "link" : "copy");
+	if (unitDir !== void 0) {
+		const patchSource = existsSync(join(unitDir, HEADLESS_PATCH_FILENAME)) ? unitDir : hostBundleDir;
+		provisionOneSubProfile(homeDir, unitSubProfileName(config), unitDir, patchSource, config, "link");
+	}
 	return profileDir;
 }
 /**
-* The preset root a harness home derives — the roster's own rule, spelled
-* here because this module has to write into it.
+* Where a scope keeps its own copy of each preset PACKAGE it composes:
+* `<scoped home>/preset-packages/<id>`. (0.1.x used `.agent-presets/<id>`,
+* the directory roster's derived user root; 0.2.0 has no directory scan.)
 */
-const USER_PRESET_DIR = ".agent-presets";
-/** The file that makes a preset directory a preset (the roster's rule). */
-const PRESET_COMPOSITION_FILE = "agent.cordis.yml";
+const SCOPE_PRESET_PACKAGES_DIR = "preset-packages";
+/**
+* The scope's copy of one preset package.
+* @param homeDir - the harness scoped home.
+* @param id - the preset id.
+* @returns the directory, whether or not it exists.
+*/
+function scopePresetPackageDir(homeDir, id) {
+	return join(homeDir, SCOPE_PRESET_PACKAGES_DIR, id);
+}
 /**
 * The scope's own declaration of what its sub-profile composes.
 *
 * A FILE in the scope directory, for the third time and the same reason as
-* the roster layer and the permission boundary: a scoped home bind-mounted
+* the preset layer and the permission boundary: a scoped home bind-mounted
 * into an evaluation unit carries its own composition with it, and nothing
 * has to ride the spawn env or be baked into an image.
 *
 * It exists because the plugin's own `config` is instance-global — one
 * deployment, one answer — while a preset is a property of the SUBJECT. Two
-* scopes rostering two presets was therefore unexpressible, and the only way
-* to build it was to hand-append the roster layer to each scope's patch. That
+* scopes composing two presets was therefore unexpressible, and the only way
+* to build it was to hand-append the preset layer to each scope's patch. That
 * hand edit does not survive: this module regenerates the patch WHOLE, and
 * the registry re-provisions a scope the first time anything names it in a
-* fresh host process — so the roster silently disappears on the next restart,
-* and the next read-back reports a scope that rosters nothing.
+* fresh host process — so the layer silently disappears on the next restart,
+* and the next read-back reports a scope that composes nothing.
 */
 const SCOPE_SUB_PROFILE_FILENAME = "sub-profile.json";
 /**
@@ -381,32 +446,30 @@ const EXPRESSION_SCHEMA = yaml.DEFAULT_SCHEMA.extend([
 /** A quoted absolute path inside an expression's source text. */
 const QUOTED_ABSOLUTE_RE = /(['"])(\/[^'"\n]*)\1/g;
 /**
-* Every absolute filesystem path a preset composition names.
+* Every absolute filesystem path a preset bundle patch names.
 *
 * An absolute path is the one thing in a composition that cannot be true in
 * two places at once, and a preset used as an evaluation factor is copied:
-* it is read on the host from the deployment's preset root, again from the
+* it is read on the host from the instance's installation, again from the
 * scope's own copy, and a third time inside a unit where the scope is bound
 * at a different mount point. `skill-filesystem` resolves each
 * `customSkillDirs` entry with `resolve()`, so an absolute entry is taken as
 * written and a bare relative one resolves against the process's cwd —
 * neither travels.
 *
-* What does travel is the loader's own expression form, which the shipped
-* `cordis` preset already uses:
+* What does travel is resolving the package's own directory through the
+* loader's `baseUrl` (the declaring profile's root), the form the official
+* web-app presets use:
 *
 * ```yaml
 * customSkillDirs:
-*   - !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('skills/', baseUrl))"
+*   - !!js "process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('<pkg>/package.json')), 'skills')"
 * ```
 *
-* `baseUrl` is the composition's own directory (the include rewrites it), so
-* the root resolves wherever the preset is installed.
-*
 * Unparsable YAML reports NO findings: the loader is the authority on whether
 * a composition loads, and refusing a preset because this reader could not
 * parse it would be this module overruling it.
-* @param text - the `agent.cordis.yml` content.
+* @param text - the bundle patch content.
 * @returns the offending literals, in document order, deduplicated.
 */
 function compositionAbsolutePaths(text) {
@@ -443,7 +506,7 @@ function compositionAbsolutePaths(text) {
 	walk(document);
 	return found;
 }
-/** Every regular file under `dir`, as posix-ish relative paths, sorted. */
+/** Every regular file under `dir`, as posix-ish relative paths, sorted (a top-level `node_modules` is not part of a preset). */
 function presetTreeFiles(dir) {
 	const files = [];
 	const walk = (absDir, rel) => {
@@ -454,6 +517,7 @@ function presetTreeFiles(dir) {
 			return false;
 		}
 		for (const entry of entries) {
+			if (rel === "" && entry.name === "node_modules") continue;
 			const relChild = rel === "" ? entry.name : `${rel}/${entry.name}`;
 			if (entry.isSymbolicLink()) return false;
 			if (entry.isDirectory()) {
@@ -469,12 +533,13 @@ function presetTreeFiles(dir) {
 	return files.sort();
 }
 /**
-* Whether two preset directories are the same directory, byte for byte.
+* Whether two preset package directories are the same directory, byte for
+* byte.
 *
 * This is the whole claim the evaluation rests on: a capability face carries
 * no filesystem path, so the fingerprint taken against the deployment's copy
 * describes the scope's copy exactly when the two hold the same bytes.
-* @param a - one preset directory.
+* @param a - one preset package directory.
 * @param b - the other.
 * @returns true when both hold the same files with the same contents.
 */
@@ -491,10 +556,10 @@ function presetTreesEqual(a, b) {
 		}
 	});
 }
-/** Copy one preset directory onto another, replacing whatever was there. */
+/** Copy one preset package directory onto another, replacing whatever was there. */
 function mirrorPresetTree(source, target) {
 	const files = presetTreeFiles(source);
-	if (files === void 0) throw new Error(`provision-dsh: preset directory ${source} is not a plain tree of files (a symlink or a device node cannot be copied into a scope — an evaluation unit resolves neither)`);
+	if (files === void 0) throw new Error(`provision-dsh: preset package ${source} is not a plain tree of files (a symlink or a device node cannot be copied into a scope — an evaluation unit resolves neither)`);
 	rmSync(target, {
 		recursive: true,
 		force: true
@@ -505,82 +570,189 @@ function mirrorPresetTree(source, target) {
 		copyFileSync(join(source, name), destination);
 	}
 }
+/** A JSON object read off disk, or undefined. */
+function readJsonObject(path) {
+	try {
+		const value = JSON.parse(readFileSync(path, "utf8"));
+		return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+	} catch {
+		return;
+	}
+}
+/** The bundle patch files a package manifest declares (`dsh.bundle.patch`, a string or a list). */
+function bundlePatchFiles(manifest) {
+	const dsh = manifest["dsh"];
+	if (typeof dsh !== "object" || dsh === null) return [];
+	const bundle = dsh["bundle"];
+	if (typeof bundle !== "object" || bundle === null) return [];
+	const patch = bundle["patch"];
+	if (typeof patch === "string") return [patch];
+	return Array.isArray(patch) ? patch.filter((item) => typeof item === "string") : [];
+}
+/** The preset ids a bundle patch document declares through `@deepseek-ai/dsh-agent-preset` rows. */
+function declaredPresetIds(text) {
+	let document;
+	try {
+		document = yaml.load(text, { schema: EXPRESSION_SCHEMA });
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(document)) return [];
+	const ids = [];
+	const visit = (row) => {
+		if (typeof row !== "object" || row === null || Array.isArray(row)) return;
+		const record = row;
+		if (record["name"] !== "@deepseek-ai/dsh-agent-preset") return;
+		const config = record["config"];
+		if (typeof config !== "object" || config === null) return;
+		const id = config["id"];
+		if (typeof id === "string") ids.push(id);
+	};
+	for (const operation of document) {
+		if (typeof operation !== "object" || operation === null) continue;
+		const insert = operation["insert"];
+		if (Array.isArray(insert)) insert.forEach(visit);
+		else visit(operation);
+	}
+	return ids;
+}
+/**
+* Find the bundle package, among a profile's direct dependencies, whose
+* bundle patch declares preset `id`.
+*
+* This is how the 0.2.0 host itself learns the preset: a profile's direct
+* `dsh.bundle`-declaring dependency mounts its patch, and the patch's
+* `@deepseek-ai/dsh-agent-preset` row registers the id. Reading the same files
+* is what lets a scope copy exactly the package the evaluation instance's
+* capability catalog measures.
+* @param profileDir - the instance profile directory (holding `package.json`).
+* @param id - the preset id.
+* @returns the declaring package, or undefined when none (or more than one) declares it.
+*/
+function findPresetPackage(profileDir, id) {
+	const manifest = readJsonObject(join(profileDir, "package.json"));
+	if (manifest === void 0) return void 0;
+	const names = /* @__PURE__ */ new Set();
+	for (const field of [
+		"dependencies",
+		"optionalDependencies",
+		"devDependencies"
+	]) {
+		const deps = manifest[field];
+		if (typeof deps === "object" && deps !== null) for (const name of Object.keys(deps)) names.add(name);
+	}
+	const found = [];
+	for (const name of [...names].sort()) {
+		if (!PACKAGE_NAME_RE.test(name)) continue;
+		let dir;
+		try {
+			dir = realpathSync(join(profileDir, "node_modules", ...name.split("/")));
+		} catch {
+			continue;
+		}
+		const packageManifest = readJsonObject(join(dir, "package.json"));
+		if (packageManifest === void 0) continue;
+		if (bundlePatchFiles(packageManifest).some((file) => {
+			try {
+				return declaredPresetIds(readFileSync(join(dir, file), "utf8")).includes(id);
+			} catch {
+				return false;
+			}
+		})) found.push({
+			name,
+			dir
+		});
+	}
+	return found.length === 1 ? found[0] : void 0;
+}
+/**
+* Why a preset package directory cannot be copied into a scope, or undefined
+* when it can: it must name itself, declare its bundle patch, and the patch
+* must declare the preset without naming an absolute path.
+*/
+function presetPackageProblem(dir, id) {
+	const manifest = readJsonObject(join(dir, "package.json"));
+	const name = manifest?.["name"];
+	if (manifest === void 0 || typeof name !== "string" || !PACKAGE_NAME_RE.test(name)) return `${dir} has no package.json naming the package`;
+	const files = bundlePatchFiles(manifest);
+	if (files.length === 0) return `${name} declares no dsh.bundle.patch`;
+	let declares = false;
+	for (const file of files) {
+		let text;
+		try {
+			text = readFileSync(join(dir, file), "utf8");
+		} catch {
+			return `${name} declares bundle patch ${file}, which is missing`;
+		}
+		const offenders = compositionAbsolutePaths(text);
+		if (offenders.length > 0) return `${name}'s ${file} names absolute path(s) ${offenders.map((path) => JSON.stringify(path)).join(", ")} — a preset that is copied into a scope and bind-mounted into a unit is read from three different directories, so an absolute path is wrong in at least two of them. Resolve the package's own directory through baseUrl instead: !!js "…dirname(createRequire(baseUrl).resolve('${name}/package.json'))…"`;
+		if (declaredPresetIds(text).includes(id)) declares = true;
+	}
+	return declares ? void 0 : `${name} declares no ${PRESET_ROW_MODULE} row with id ${JSON.stringify(id)}`;
+}
 /**
-* Give one scope its own copy of a preset, from the deployment's preset root.
+* Give one scope its own copy of a preset package, from the evaluation
+* instance's own installation of it.
 *
-* The copy is what makes a preset reachable on BOTH paths. The roster derives
-* a user root of `<$DSH_HOME>/.agent-presets`, and the sub-dsh runs with
-* `DSH_HOME` pointed at the scoped home — which is `<scope>/.agent-presets`
-* on the host and `/creds/dsh/.agent-presets` inside an evaluation unit,
-* one directory, because the unit binds the scope. A roster pointed at the
-* deployment's root instead resolves on the host and names a path the unit
-* does not have.
+* The copy is what makes a preset reachable on BOTH paths. The sub-profile
+* resolves the package through a relative link to
+* `<scope>/preset-packages/<id>`, which is one directory on the host and
+* inside an evaluation unit, because the unit binds the scope.
 *
 * `refresh` is the difference between provisioning a condition and healing a
-* scope. A deliberate provision re-syncs from the deployment's copy, because
+* scope. A deliberate provision re-syncs from the instance's copy, because
 * that is the moment a new lock is minted and an edited preset should be
 * picked up. Every other provisioning leaves an existing copy alone: nothing
-* may move the subject under a run.
+* may move the subject under a run — and a healing call whose instance no
+* longer carries the package keeps the copy, reporting `matchesSource: false`.
 * @param homeDir - the harness scoped home.
-* @param presetRoot - the deployment's preset root.
-* @param id - the preset id (a directory name in both roots).
+* @param instanceProfileDir - the instance profile directory, or undefined when unknown.
+* @param id - the preset id.
 * @param options - `refresh` re-syncs an existing copy.
 * @returns where the copy is and whether it matches the source.
-* @throws when the source is missing, is not a preset, or names an absolute path.
+* @throws when no copy can be made: no installed package declares the id, or it is not a usable preset package.
 */
-function snapshotScopePreset(homeDir, presetRoot, id, options = {}) {
+function snapshotScopePreset(homeDir, instanceProfileDir, id, options = {}) {
 	if (!SUB_PROFILE_PRESET_ID_RE.test(id)) throw new Error(`provision-dsh: preset id ${JSON.stringify(id)} must match ${String(SUB_PROFILE_PRESET_ID_RE)} (it is a directory name)`);
-	const source = join(presetRoot, id);
-	const composition = join(source, PRESET_COMPOSITION_FILE);
-	if (!existsSync(composition)) throw new Error(`provision-dsh: no preset ${JSON.stringify(id)} in ${presetRoot} (expected ${join(id, PRESET_COMPOSITION_FILE)}) — install it into this deployment's preset root before a scope can compose it`);
-	const offenders = compositionAbsolutePaths(readFileSync(composition, "utf8"));
-	if (offenders.length > 0) throw new Error(`provision-dsh: preset ${JSON.stringify(id)} names absolute path(s) ${offenders.map((path) => JSON.stringify(path)).join(", ")} — a preset that is copied into a scope and bind-mounted into a unit is read from three different directories, so an absolute path is wrong in at least two of them. Use the loader expression the shipped \`cordis\` preset uses: !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('skills/', baseUrl))"`);
-	const dir = join(homeDir, USER_PRESET_DIR, id);
-	if (existsSync(dir) && options.refresh !== true) return {
+	const dir = scopePresetPackageDir(homeDir, id);
+	const copyName = () => {
+		const name = readJsonObject(join(dir, "package.json"))?.["name"];
+		return typeof name === "string" && PACKAGE_NAME_RE.test(name) ? name : void 0;
+	};
+	const source = instanceProfileDir === void 0 ? void 0 : findPresetPackage(instanceProfileDir, id);
+	const existing = existsSync(dir) ? copyName() : void 0;
+	if (existing !== void 0 && options.refresh !== true) return {
 		dir,
-		matchesSource: presetTreesEqual(source, dir),
+		packageName: existing,
+		matchesSource: source !== void 0 && presetTreesEqual(source.dir, dir),
 		copied: false
 	};
-	if (existsSync(dir) && presetTreesEqual(source, dir)) return {
+	if (source === void 0) throw new Error(`provision-dsh: no package installed in ${instanceProfileDir ?? "this instance's profile"} declares preset ${JSON.stringify(id)} (an ${PRESET_ROW_MODULE} row in its dsh.bundle.patch) — add the preset package to the instance profile before a scope can compose it`);
+	const problem = presetPackageProblem(source.dir, id);
+	if (problem !== void 0) throw new Error(`provision-dsh: preset ${JSON.stringify(id)}: ${problem}`);
+	if (existing !== void 0 && presetTreesEqual(source.dir, dir)) return {
 		dir,
+		packageName: existing,
 		matchesSource: true,
 		copied: false
 	};
-	mirrorPresetTree(source, dir);
+	mirrorPresetTree(source.dir, dir);
 	return {
 		dir,
+		packageName: source.name,
 		matchesSource: true,
 		copied: true
 	};
 }
 /**
-* The deployment's own preset root, when the caller names no other.
-*
-* The roster's own derivation, repeated here because the provisioning paths
-* that heal a scope (a host round, a live runtime) have no settings service
-* in reach: a non-blank `$DSH_HOME`, else the `~/.dsh` installation default
-* (the precedence of `resolveDshHome` in `@deepseek-ai/dsh-home-paths` —
-* the default was once hardcoded to `.dsh-official`, pointing a desktop
-* instance at another instance's home; 2026-09-30).
-*/
-function defaultPresetRoot() {
-	const fromEnv = process.env["DSH_HOME"];
-	const home = fromEnv !== void 0 && fromEnv.trim().length > 0 ? fromEnv : join(homedir(), ".dsh");
-	return join(home, USER_PRESET_DIR);
-}
-/**
-* Provision one scope: its own preset copy, its declaration, and the
-* sub-profile that rosters it.
+* Provision one scope: its own preset package copy, its declaration, and the
+* sub-profile that composes it.
 *
 * The preset resolves in one order, and the order is the decision: the
 * CALLER's explicit request, then the SCOPE's own declaration, then the
 * deployment's plugin config. The first is how a condition says which subject
 * this scope is; the second is how that survives a restart; the third is the
 * deployment-wide answer every scope had before either existed.
-*
-* A scope-owned preset rosters with NO `roots`. The roster's derived user
-* root is exactly the scope's copy on both paths, so leaving the roots alone
-* is what gives the host and the unit one resolution rule instead of two.
 * @param homeDir - the harness scoped home.
 * @param config - the deployment's sub-profile config.
 * @param options - per-scope inputs.
@@ -589,10 +761,13 @@ function defaultPresetRoot() {
 function provisionDshScope(homeDir, config = {}, options = {}) {
 	const requested = options.preset;
 	const declared = requested ?? readScopeSubProfile(homeDir)?.preset;
-	if (requested !== void 0) writeScopeSubProfile(homeDir, { preset: requested });
 	let snapshot;
-	if (declared !== void 0) snapshot = snapshotScopePreset(homeDir, options.presetRoot ?? defaultPresetRoot(), declared, { refresh: requested !== void 0 });
-	const preset = declared === void 0 ? config.preset : { id: declared };
+	if (declared !== void 0) snapshot = snapshotScopePreset(homeDir, options.instanceProfileDir, declared, { refresh: requested !== void 0 });
+	if (requested !== void 0) writeScopeSubProfile(homeDir, { preset: requested });
+	const preset = declared === void 0 || snapshot === void 0 ? config.preset : {
+		id: declared,
+		package: snapshot.packageName
+	};
 	return {
 		profileDir: provisionDshSubProfile(homeDir, {
 			...config,
@@ -603,4 +778,4 @@ function provisionDshScope(homeDir, config = {}, options = {}) {
 	};
 }
 //#endregion
-export { DEFAULT_SUB_PROFILE_NAME, PRESET_ROSTER_MODULE, SCOPE_SUB_PROFILE_FILENAME, SUB_PROFILE_PRESET_ID_RE, USER_PRESET_DIR, compositionAbsolutePaths, defaultPresetRoot, permissionBoundaryLayer, presetRosterLayer, presetTreesEqual, provisionDshScope, provisionDshSubProfile, readScopeSubProfile, readSubProfilePermissions, readSubProfilePreset, resolveHeadlessBundleDir, snapshotScopePreset, writeScopeSubProfile };
+export { DEFAULT_SUB_PROFILE_NAME, PRESET_REGISTRY_MODULE, PRESET_ROW_MODULE, SCOPE_PRESET_PACKAGES_DIR, SCOPE_SUB_PROFILE_FILENAME, SUB_PROFILE_PRESET_ID_RE, UNIT_PROFILE_SUFFIX, compositionAbsolutePaths, findPresetPackage, permissionBoundaryLayer, presetRegistryLayer, presetTreesEqual, provisionDshScope, provisionDshSubProfile, readScopeSubProfile, readSubProfilePermissions, readSubProfilePreset, resolveHeadlessBundleDir, scopePresetPackageDir, snapshotScopePreset, unitSubProfileName, writeScopeSubProfile };