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

package/lib/types/provision.js

@@ -5,29 +5,38 @@
  * `<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
@@ -36,7 +45,7 @@
  * 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.
@@ -51,9 +60,8 @@
  * @module @khorsheed/dsh-local-agent-dsh/provision
  */
 import { createRequire } from 'node:module';
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, isAbsolute, join } from 'node:path';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative } from 'node:path';
 import yaml from 'js-yaml';
 /** Default name of the sub-dsh profile under the scoped home. */
 export const DEFAULT_SUB_PROFILE_NAME = 'headless-local-agent-dsh';
@@ -73,28 +81,31 @@ 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.
  */
-export const PRESET_ROSTER_MODULE = '@deepseek-ai/dsh-agent-presets';
-/** A preset id doubles as a directory name — the roster's own rule. */
+export const PRESET_REGISTRY_MODULE = '@deepseek-ai/dsh-agent-preset-registry';
+/** The declarative preset row a preset bundle package carries in its patch. */
+export const PRESET_ROW_MODULE = '@deepseek-ai/dsh-agent-preset';
+/** A preset id doubles as a directory name inside the scope. */
 export 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
@@ -103,12 +114,13 @@ 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 === undefined ? [...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 } },
     }, undefined, 2) + '\n';
 }
 /**
@@ -125,22 +137,28 @@ export function resolveHeadlessBundleDir(config = {}) {
     const manifestPath = require.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 `''`.
  */
-export function presetRosterLayer(preset) {
+export function presetRegistryLayer(preset) {
     if (preset === undefined)
         return '';
     if (!SUB_PROFILE_PRESET_ID_RE.test(preset.id)) {
@@ -150,36 +168,24 @@ export function presetRosterLayer(preset) {
         '',
         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 !== undefined)
-        lines.push(`        includeShippedRoot: ${String(preset.includeShippedRoot)}`);
-    if (preset.includeUserRoot !== undefined)
-        lines.push(`        includeUserRoot: ${String(preset.includeUserRoot)}`);
-    if (preset.roots !== undefined && preset.roots.length > 0) {
-        lines.push('        roots:');
-        for (const root of preset.roots) {
-            lines.push(`          - path: ${yamlString(root.path)}`);
-            if (root.trust !== undefined)
-                lines.push(`            trust: ${root.trust}`);
-        }
-    }
     return `${lines.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.
  */
 export function readSubProfilePreset(homeDir, profileName = DEFAULT_SUB_PROFILE_NAME) {
     const patchPath = join(homeDir, 'profiles', profileName, PROFILE_PATCH_FILENAME);
@@ -294,64 +300,140 @@ function ensureSymlink(link, target) {
     rmSync(link, { force: true });
     symlinkSync(target, link);
 }
+/** Suffix of the evaluation-unit twin of a sub-profile (see `unitHeadlessBundleDir`). */
+export 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`.
+ */
+export function unitSubProfileName(config = {}) {
+    const profileName = config.profileName ?? DEFAULT_SUB_PROFILE_NAME;
+    return config.unitHeadlessBundleDir === undefined ? 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 !== undefined && presetTreesEqual(source, target))
+        return;
+    if (presetTreeFiles(source) === undefined) {
+        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 !== undefined && !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 !== undefined && config.preset !== undefined) {
+        // RELATIVE, so the link resolves the same on the host and inside a unit
+        // that bind-mounts the scope at a different absolute path.
+        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.
  */
 export function provisionDshSubProfile(homeDir, config = {}) {
     const profileName = config.profileName ?? DEFAULT_SUB_PROFILE_NAME;
-    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 hostBundleDir = resolveHeadlessBundleDir(config);
+    const unitDir = config.unitHeadlessBundleDir;
+    // The pinned single-profile form (a `headlessBundleDir` shared by host and
+    // unit, no twin) keeps its link: the pin's whole point is one path both
+    // filesystems resolve, and that form predates 0.2.0's linked-root routing.
+    const hostMount = config.headlessBundleDir !== undefined && unitDir === undefined ? 'link' : 'copy';
+    const profileDir = provisionOneSubProfile(homeDir, profileName, hostBundleDir, hostBundleDir, config, hostMount);
+    if (unitDir !== undefined) {
+        // The twin's patch comes from the unit's bundle when this machine can
+        // read it (a host-side mirror of the image's install, as `/opt` is on a
+        // dataset machine), else from the host bundle — the link is what moves.
+        const patchSource = existsSync(join(unitDir, HEADLESS_PATCH_FILENAME)) ? unitDir : hostBundleDir;
+        provisionOneSubProfile(homeDir, unitSubProfileName(config), unitDir, patchSource, config, 'link');
     }
-    const bundleLink = join(profileDir, 'node_modules', '@khorsheed', 'dsh-local-agent-dsh-headless');
-    mkdirSync(dirname(bundleLink), { recursive: true });
-    ensureSymlink(bundleLink, bundleDir);
     return profileDir;
 }
 // ── the scope's own preset ───────────────────────────────────────────────
 /**
- * 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.)
+ */
+export 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.
  */
-export 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';
+export 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.
  */
 export const SCOPE_SUB_PROFILE_FILENAME = 'sub-profile.json';
 /**
@@ -416,32 +498,30 @@ const EXPRESSION_SCHEMA = yaml.DEFAULT_SCHEMA.extend(['scalar', 'sequence', 'map
 /** 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.
  */
 export function compositionAbsolutePaths(text) {
@@ -485,7 +565,7 @@ export 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) => {
@@ -497,6 +577,8 @@ 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}`;
             // A symlink is refused rather than followed: it does not survive the
             // bind mount into a unit, and the scoped home's own hash counts one as
@@ -519,12 +601,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.
  */
@@ -544,11 +627,11 @@ export 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 === undefined) {
-        throw new Error(`provision-dsh: preset directory ${source} is not a plain tree of files`
+        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 });
@@ -558,84 +641,209 @@ 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 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 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'] !== PRESET_ROW_MODULE)
+            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.
+ */
+export function findPresetPackage(profileDir, id) {
+    const manifest = readJsonObject(join(profileDir, 'package.json'));
+    if (manifest === undefined)
+        return undefined;
+    const names = 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 === undefined)
+            continue;
+        const declares = bundlePatchFiles(packageManifest).some(file => {
+            try {
+                return declaredPresetIds(readFileSync(join(dir, file), 'utf8')).includes(id);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (declares)
+            found.push({ name, dir });
+    }
+    return found.length === 1 ? found[0] : undefined;
+}
+/**
+ * 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 === undefined || 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 ? undefined : `${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.
  */
-export function snapshotScopePreset(homeDir, presetRoot, id, options = {}) {
+export 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 = scopePresetPackageDir(homeDir, id);
+    const copyName = () => {
+        const name = readJsonObject(join(dir, 'package.json'))?.['name'];
+        return typeof name === 'string' && PACKAGE_NAME_RE.test(name) ? name : undefined;
+    };
+    const source = instanceProfileDir === undefined ? undefined : findPresetPackage(instanceProfileDir, id);
+    const existing = existsSync(dir) ? copyName() : undefined;
+    if (existing !== undefined && options.refresh !== true) {
+        return { dir, packageName: existing, matchesSource: source !== undefined && presetTreesEqual(source.dir, dir), copied: false };
     }
-    const dir = join(homeDir, USER_PRESET_DIR, id);
-    if (existsSync(dir) && options.refresh !== true) {
-        return { dir, matchesSource: presetTreesEqual(source, dir), copied: false };
+    if (source === undefined) {
+        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`);
     }
-    if (existsSync(dir) && presetTreesEqual(source, dir)) {
-        return { dir, matchesSource: true, copied: false };
+    const problem = presetPackageProblem(source.dir, id);
+    if (problem !== undefined)
+        throw new Error(`provision-dsh: preset ${JSON.stringify(id)}: ${problem}`);
+    if (existing !== undefined && presetTreesEqual(source.dir, dir)) {
+        return { dir, packageName: existing, matchesSource: true, copied: false };
     }
-    mirrorPresetTree(source, dir);
-    return { dir, 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).
- */
-export function defaultPresetRoot() {
-    const fromEnv = process.env['DSH_HOME'];
-    const home = fromEnv !== undefined && fromEnv.trim().length > 0 ? fromEnv : join(homedir(), '.dsh');
-    return join(home, USER_PRESET_DIR);
+    mirrorPresetTree(source.dir, dir);
+    return { dir, packageName: source.name, matchesSource: true, copied: true };
 }
 /**
- * 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.
@@ -644,13 +852,15 @@ export function defaultPresetRoot() {
 export function provisionDshScope(homeDir, config = {}, options = {}) {
     const requested = options.preset;
     const declared = requested ?? readScopeSubProfile(homeDir)?.preset;
-    if (requested !== undefined)
-        writeScopeSubProfile(homeDir, { preset: requested });
     let snapshot;
     if (declared !== undefined) {
-        snapshot = snapshotScopePreset(homeDir, options.presetRoot ?? defaultPresetRoot(), declared, { refresh: requested !== undefined });
+        snapshot = snapshotScopePreset(homeDir, options.instanceProfileDir, declared, { refresh: requested !== undefined });
     }
-    const preset = declared === undefined ? config.preset : { id: declared };
+    if (requested !== undefined)
+        writeScopeSubProfile(homeDir, { preset: requested });
+    const preset = declared === undefined || snapshot === undefined
+        ? config.preset
+        : { id: declared, package: snapshot.packageName };
     const profileDir = provisionDshSubProfile(homeDir, { ...config, ...(preset === undefined ? {} : { preset }) });
     return {
         profileDir,