odai-dsh-agent 0.2.1 → 0.2.3

package/src/installer.mjs

@@ -1,382 +1,398 @@
-import { createHash, randomUUID } from "node:crypto";
-import {
-  chmod,
-  cp,
-  lstat,
-  mkdir,
-  readFile,
-  readdir,
-  rename,
-  rm,
-  writeFile,
-} from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, relative, resolve, sep } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-import { parse as parseYaml } from "yaml";
-
-export const DEFAULT_PRESET_ID = "odai";
-export const MANIFEST_FILE = ".odai-agent.json";
-
-const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const defaultSourceRoot = resolve(packageRoot, "preset/odai");
-const packageMetadata = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
-const DSH_VERSION_PATTERN = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
-export const SUPPORTED_DSH_VERSIONS = Object.freeze(
-  packageMetadata.peerDependencies["@deepseek-ai/dsh"]
-    .split(/\s*\|\|\s*/u)
-    .filter(Boolean),
-);
-if (SUPPORTED_DSH_VERSIONS.length === 0 || SUPPORTED_DSH_VERSIONS.some((version) => !DSH_VERSION_PATTERN.test(version))) {
-  throw new Error("odai-dsh-agent peer dependency must list exact supported DSH versions");
-}
-export const SUPPORTED_DSH_VERSION = SUPPORTED_DSH_VERSIONS.at(-1);
-const requiredFiles = Object.freeze([
-  "agent.cordis.yml",
-  "preset.yml",
-  "runtime/index.mjs",
-  "runtime/session-compat.mjs",
-  "runtime/session-evidence.mjs",
-  "runtime/skill-bundle.mjs",
-  "runtime/skill-evolution.mjs",
-  "runtime/skill-selection-state.mjs",
-  "runtime/skill-selector.mjs",
-  "runtime/skill-source-config.mjs",
-  "skills/odai/SKILL.md",
-  "skills/odai/manifest.json",
-]);
-
-function replaceCompositionContract(composition, before, after, label) {
-  const first = composition.indexOf(before);
-  if (first < 0 || composition.indexOf(before, first + before.length) >= 0) {
-    throw new Error(`Odai Agent composition does not contain exactly one rc.7 ${label} contract`);
-  }
-  return `${composition.slice(0, first)}${after}${composition.slice(first + before.length)}`;
-}
-
-export function renderAgentCompositionForDsh(composition, dshVersion = SUPPORTED_DSH_VERSION) {
-  if (typeof composition !== "string" || composition.trim() === "") {
-    throw new TypeError("agent composition must be a non-empty string");
-  }
-  if (!SUPPORTED_DSH_VERSIONS.includes(dshVersion)) {
-    throw new Error(`unsupported DSH version ${dshVersion || "<empty>"}; expected one of ${SUPPORTED_DSH_VERSIONS.join(", ")}`);
-  }
-  let rendered = composition.replace(/\r\n/gu, "\n");
-  if (dshVersion === "0.1.0-rc.7") return rendered;
-  rendered = replaceCompositionContract(
-    rendered,
-    "    # Production dsh does not install these optional providers. An opting-in\n    # Profile mounts each provider once on the host plane; copy this preset,\n    # then remove `disabled` from the matching tool row.",
-    "    # Product providers are host-plane singletons. Copy this preset, then\n    # remove `disabled` from either ordinary tool row to expose that product\n    # only to agents composed from the copy.",
-    "optional-provider comment",
-  );
-  rendered = replaceCompositionContract(
-    rendered,
-    "        provider: codex\n        toolName: subagent_codex\n        backgroundMode: one-shot",
-    "        provider: codex\n        toolName: subagent_codex\n        enableRunInBackground: false",
-    "Codex provider",
-  );
-  return replaceCompositionContract(
-    rendered,
-    "        provider: claude-code\n        toolName: subagent_claude_code\n        backgroundMode: one-shot",
-    "        provider: claude-code\n        toolName: subagent_claude_code\n        enableRunInBackground: false",
-    "Claude Code provider",
-  );
-}
-
-export function resolveDshHome(configured, env = process.env) {
-  const value = configured ?? env.DSH_HOME ?? resolve(homedir(), ".dsh");
-  if (typeof value !== "string" || value.trim() === "") {
-    throw new TypeError("DSH home must be a non-empty path");
-  }
-  const trimmed = value.trim();
-  if (trimmed === "~") return homedir();
-  if (trimmed.startsWith(`~${sep}`)) return resolve(homedir(), trimmed.slice(2));
-  return resolve(trimmed);
-}
-
-export async function inspectAgentInstallation(options = {}) {
-  const presetId = assertPresetId(options.presetId ?? DEFAULT_PRESET_ID);
-  const dshHome = resolveDshHome(options.dshHome);
-  const target = resolve(dshHome, ".agent-presets", presetId);
-  const state = await inspectTarget(target, presetId);
-  return Object.freeze({ dshHome, presetId, target, ...state });
-}
-
-export async function installAgentPreset(options = {}) {
-  const presetId = assertPresetId(options.presetId ?? DEFAULT_PRESET_ID);
-  const dshHome = resolveDshHome(options.dshHome);
-  const sourceRoot = resolve(options.sourceRoot ?? defaultSourceRoot);
-  const dshVersion = options.dshVersion ?? SUPPORTED_DSH_VERSION;
-  if (!SUPPORTED_DSH_VERSIONS.includes(dshVersion)) {
-    throw new Error(`unsupported DSH version ${dshVersion || "<empty>"}; expected one of ${SUPPORTED_DSH_VERSIONS.join(", ")}`);
-  }
-  const targetRoot = resolve(dshHome, ".agent-presets");
-  const target = resolve(targetRoot, presetId);
-  const current = await inspectTarget(target, presetId);
-  const previousCompositionSize = current.status === "installed"
-    ? Buffer.byteLength(await readFile(resolve(target, "agent.cordis.yml")))
-    : undefined;
-
-  if (current.status === "drifted") {
-    throw new Error(`refusing to replace modified preset at ${target}: ${current.issues.join("; ")}`);
-  }
-
-  await assertSource(sourceRoot);
-  const sessionCompatibility = await repairSessionCompatibility(
-    dshHome,
-    [sourceRoot],
-    options.confirmDshStopped === true,
-    options.processScanner,
-  );
-  await mkdir(targetRoot, { recursive: true, mode: 0o700 });
-  const staging = resolve(targetRoot, `.${presetId}.tmp-${process.pid}-${randomUUID()}`);
-  const backup = resolve(targetRoot, `.${presetId}.backup-${process.pid}-${randomUUID()}`);
-  let backupCreated = false;
-
-  try {
-    await cp(sourceRoot, staging, { recursive: true, errorOnExist: true });
-    await tightenTree(staging);
-    const compositionPath = resolve(staging, "agent.cordis.yml");
-    const composition = renderAgentCompositionForDsh(await readFile(compositionPath, "utf8"), dshVersion);
-    let stampedComposition = `${composition.trimEnd()}\n# odai-dsh-agent generation ${packageMetadata.version}:${randomUUID()}\n`;
-    // Supported DSH releases key standing generations by mtime and size, so size must change even on same-tick updates.
-    if (previousCompositionSize === Buffer.byteLength(stampedComposition)) {
-      stampedComposition += "# odai-dsh-agent generation size bump\n";
-    }
-    await writeFile(compositionPath, stampedComposition, "utf8");
-    const files = await hashTree(staging);
-    const manifest = {
-      schemaVersion: 1,
-      package: packageMetadata.name,
-      version: packageMetadata.version,
-      dshVersion,
-      presetId,
-      files,
-    };
-    const manifestPath = resolve(staging, MANIFEST_FILE);
-    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-    await chmod(manifestPath, 0o600);
-
-    if (current.status === "installed") {
-      await rename(target, backup);
-      backupCreated = true;
-    }
-    await rename(staging, target);
-    if (backupCreated) {
-      await rm(backup, { recursive: true, force: true });
-      backupCreated = false;
-    }
-
-    return Object.freeze({
-      operation: current.status === "installed" ? "updated" : "installed",
-      dshHome,
-      presetId,
-      target,
-      version: packageMetadata.version,
-      dshVersion,
-      trust: "user",
-      security: "DSH user presets have the same privileges as shell access; install only reviewed preset code.",
-      sessionCompatibility,
-    });
-  } catch (error) {
-    await rm(staging, { recursive: true, force: true });
-    if (backupCreated) {
-      const targetState = await pathState(target);
-      if (targetState === "missing") await rename(backup, target);
-    }
-    throw error;
-  } finally {
-    await rm(backup, { recursive: true, force: true });
-  }
-}
-
-export async function uninstallAgentPreset(options = {}) {
-  const inspected = await inspectAgentInstallation(options);
-  if (inspected.status === "absent") {
-    return Object.freeze({ operation: "absent", target: inspected.target, presetId: inspected.presetId });
-  }
-  if (inspected.status === "drifted") {
-    throw new Error(`refusing to remove modified preset at ${inspected.target}: ${inspected.issues.join("; ")}`);
-  }
-  await assertPresetIsNotDefault(inspected.dshHome, inspected.presetId);
-  const sessionCompatibility = await repairSessionCompatibility(
-    inspected.dshHome,
-    [defaultSourceRoot, inspected.target],
-    options.confirmDshStopped === true,
-    options.processScanner,
-  );
-  if (sessionCompatibility.failures.length > 0) {
-    throw new Error(`refusing to uninstall before legacy Odai session evidence is made ignorable: ${sessionCompatibility.failures.map((failure) => `${failure.path}: ${failure.error}`).join("; ")}`);
-  }
-  await rm(inspected.target, { recursive: true, force: true });
-  return Object.freeze({
-    operation: "uninstalled",
-    target: inspected.target,
-    presetId: inspected.presetId,
-    sessionCompatibility,
-  });
-}
-
-async function assertPresetIsNotDefault(dshHome, presetId) {
-  const settingsPath = resolve(dshHome, "settings.yaml");
-  let text;
-  try {
-    text = await readFile(settingsPath, "utf8");
-  } catch (error) {
-    if (error?.code === "ENOENT") return;
-    throw error;
-  }
-  let settings;
-  try {
-    settings = parseYaml(text) ?? {};
-  } catch (error) {
-    throw new Error(`cannot verify the default agent preset in ${settingsPath}: ${error.message}`);
-  }
-  if (settings?.["agent-presets"]?.default === presetId) {
-    throw new Error(`refusing to uninstall the default preset ${presetId}; select another agent-presets.default first`);
-  }
-}
-
-async function inspectTarget(target, presetId) {
-  const state = await pathState(target);
-  if (state === "missing") return { status: "absent", issues: [] };
-  if (state !== "directory") return { status: "drifted", issues: ["target is not a regular directory"] };
-
-  let manifest;
-  try {
-    manifest = JSON.parse(await readFile(resolve(target, MANIFEST_FILE), "utf8"));
-  } catch (error) {
-    return { status: "drifted", issues: [`managed manifest is unavailable: ${error.message}`] };
-  }
-
-  const issues = validateManifest(manifest, presetId);
-  let actualFiles = {};
-  try {
-    actualFiles = await hashTree(target, { exclude: new Set([MANIFEST_FILE]) });
-  } catch (error) {
-    issues.push(error.message);
-  }
-
-  if (issues.length === 0) {
-    const expectedFiles = manifest.files;
-    for (const [path, hash] of Object.entries(expectedFiles)) {
-      if (!(path in actualFiles)) issues.push(`missing managed file ${path}`);
-      else if (actualFiles[path] !== hash) issues.push(`modified managed file ${path}`);
-    }
-    for (const path of Object.keys(actualFiles)) {
-      if (!(path in expectedFiles)) issues.push(`unmanaged file ${path}`);
-    }
-  }
-
-  return {
-    status: issues.length === 0 ? "installed" : "drifted",
-    issues,
-    version: typeof manifest?.version === "string" ? manifest.version : undefined,
-    dshVersion: typeof manifest?.dshVersion === "string" ? manifest.dshVersion : undefined,
-  };
-}
-
-function validateManifest(manifest, presetId) {
-  const issues = [];
-  if (manifest?.schemaVersion !== 1) issues.push("unsupported managed manifest schema");
-  if (manifest?.package !== packageMetadata.name) issues.push("managed manifest package mismatch");
-  if (manifest?.presetId !== presetId) issues.push("managed manifest preset id mismatch");
-  if (!manifest?.files || typeof manifest.files !== "object" || Array.isArray(manifest.files)) {
-    issues.push("managed manifest file map is invalid");
-  }
-  return issues;
-}
-
-async function repairSessionCompatibility(dshHome, sourceRoots, confirmDshStopped, processScanner) {
-  for (const sourceRoot of sourceRoots) {
-    const modulePath = resolve(sourceRoot, "runtime/session-compat.mjs");
-    if (await pathState(modulePath) !== "file") continue;
-    const compatibility = await import(pathToFileURL(modulePath).href);
-    if (typeof compatibility.inspectLegacySessionLogs !== "function"
-      || typeof compatibility.repairLegacySessionLogs !== "function") {
-      throw new Error(`agent package session compatibility module is invalid: ${modulePath}`);
-    }
-    const inspected = compatibility.inspectLegacySessionLogs({ dshHome });
-    if (inspected.failures.length > 0) {
-      throw new Error(`cannot inspect legacy Odai session evidence safely: ${inspected.failures.map((failure) => `${failure.path}: ${failure.error}`).join("; ")}`);
-    }
-    if (inspected.matchedEvents === 0) return inspected;
-    if (!confirmDshStopped) {
-      throw new Error(`found ${inspected.matchedEvents} legacy Odai session event(s); stop every DSH process and rerun with --yes before changing the Agent preset`);
-    }
-    const repaired = compatibility.repairLegacySessionLogs({
-      dshHome,
-      confirmDshStopped: true,
-      processScanner,
-    });
-    if (repaired.failures.length > 0) {
-      throw new Error(`cannot repair legacy Odai session evidence safely: ${repaired.failures.map((failure) => `${failure.path}: ${failure.error}`).join("; ")}`);
-    }
-    return repaired;
-  }
-  throw new Error("agent package is incomplete: missing runtime/session-compat.mjs");
-}
-
-async function assertSource(sourceRoot) {
-  for (const path of requiredFiles) {
-    const state = await pathState(resolve(sourceRoot, path));
-    if (state !== "file") throw new Error(`agent package is incomplete: missing ${path}`);
-  }
-}
-
-async function tightenTree(root) {
-  await chmod(root, 0o700);
-  const entries = await readdir(root, { withFileTypes: true });
-  for (const entry of entries) {
-    const path = resolve(root, entry.name);
-    if (entry.isSymbolicLink()) throw new Error(`symbolic link is not allowed in managed preset: ${entry.name}`);
-    if (entry.isDirectory()) await tightenTree(path);
-    else if (entry.isFile()) await chmod(path, 0o600);
-    else throw new Error(`unsupported filesystem entry in managed preset: ${entry.name}`);
-  }
-}
-
-async function hashTree(root, options = {}) {
-  const found = {};
-  await walk(root, "");
-  return Object.fromEntries(Object.entries(found).sort(([left], [right]) => left.localeCompare(right)));
-
-  async function walk(base, prefix) {
-    const entries = await readdir(base, { withFileTypes: true });
-    entries.sort((left, right) => left.name.localeCompare(right.name));
-    for (const entry of entries) {
-      const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
-      if (options.exclude?.has(relativePath)) continue;
-      const absolutePath = resolve(base, entry.name);
-      if (entry.isSymbolicLink()) throw new Error(`symbolic link is not allowed in managed preset: ${relativePath}`);
-      if (entry.isDirectory()) await walk(absolutePath, relativePath);
-      else if (entry.isFile()) found[relativePath] = await hashFile(absolutePath);
-      else throw new Error(`unsupported filesystem entry in managed preset: ${relativePath}`);
-    }
-  }
-}
-
-async function hashFile(path) {
-  return createHash("sha256").update(await readFile(path)).digest("hex");
-}
-
-async function pathState(path) {
-  try {
-    const stats = await lstat(path);
-    if (stats.isSymbolicLink()) return "symlink";
-    if (stats.isDirectory()) return "directory";
-    if (stats.isFile()) return "file";
-    return "other";
-  } catch (error) {
-    if (error?.code === "ENOENT") return "missing";
-    throw error;
-  }
-}
-
-function assertPresetId(value) {
-  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(value)) {
-    throw new TypeError("preset id must contain only letters, digits, dots, underscores, or hyphens");
-  }
-  return value;
-}
+import { createHash, randomUUID } from "node:crypto";
+import {
+  chmod,
+  cp,
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { parse as parseYaml } from "yaml";
+
+export const DEFAULT_PRESET_ID = "odai";
+export const MANIFEST_FILE = ".odai-agent.json";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const defaultSourceRoot = resolve(packageRoot, "preset/odai");
+const packageMetadata = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
+const DSH_VERSION_PATTERN = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
+export const SUPPORTED_DSH_VERSIONS = Object.freeze(
+  packageMetadata.peerDependencies["@deepseek-ai/dsh"]
+    .split(/\s*\|\|\s*/u)
+    .filter(Boolean),
+);
+if (SUPPORTED_DSH_VERSIONS.length === 0 || SUPPORTED_DSH_VERSIONS.some((version) => !DSH_VERSION_PATTERN.test(version))) {
+  throw new Error("odai-dsh-agent peer dependency must list exact supported DSH versions");
+}
+const SOURCE_DSH_VERSION = "0.1.0-rc.8";
+const OPTIONAL_PROVIDER_COMMENTS = Object.freeze({
+  "0.1.0-rc.6": "    # Product providers are host-plane singletons. Copy this preset, then\n    # remove `disabled` from either ordinary tool row to expose that product\n    # only to agents composed from the copy.",
+  "0.1.0-rc.7": "    # Production dsh does not install these optional providers. An opting-in\n    # Profile mounts each provider once on the host plane; copy this preset,\n    # then remove `disabled` from the matching tool row.",
+  "0.1.0-rc.8": "    # Production dsh does not install these optional providers. Install the\n    # matching Bundle in this Profile and restart the Host, then copy this\n    # preset and remove `disabled` from the matching tool row. Host availability\n    # alone grants no tool.",
+});
+const compositionVersions = Object.keys(OPTIONAL_PROVIDER_COMMENTS);
+if (JSON.stringify(SUPPORTED_DSH_VERSIONS) !== JSON.stringify(compositionVersions)) {
+  throw new Error(`Odai Agent peer versions ${SUPPORTED_DSH_VERSIONS.join(", ")} must exactly match composition contracts ${compositionVersions.join(", ")}`);
+}
+if (compositionVersions.at(-1) !== SOURCE_DSH_VERSION) {
+  throw new Error(`Odai Agent source composition targets ${SOURCE_DSH_VERSION}, not contract baseline ${compositionVersions.at(-1)}`);
+}
+export const SUPPORTED_DSH_VERSION = SOURCE_DSH_VERSION;
+const requiredFiles = Object.freeze([
+  "agent.cordis.yml",
+  "preset.yml",
+  "runtime/index.mjs",
+  "runtime/session-compat.mjs",
+  "runtime/session-evidence.mjs",
+  "runtime/skill-bundle.mjs",
+  "runtime/skill-evolution.mjs",
+  "runtime/skill-selection-state.mjs",
+  "runtime/skill-selector.mjs",
+  "runtime/skill-source-config.mjs",
+  "skills/odai/SKILL.md",
+  "skills/odai/manifest.json",
+]);
+
+function replaceCompositionContract(composition, before, after, label) {
+  const first = composition.indexOf(before);
+  if (first < 0 || composition.indexOf(before, first + before.length) >= 0) {
+    throw new Error(`Odai Agent source composition does not contain exactly one ${label} contract`);
+  }
+  return `${composition.slice(0, first)}${after}${composition.slice(first + before.length)}`;
+}
+
+export function renderAgentCompositionForDsh(composition, dshVersion = SUPPORTED_DSH_VERSION) {
+  if (typeof composition !== "string" || composition.trim() === "") {
+    throw new TypeError("agent composition must be a non-empty string");
+  }
+  if (!SUPPORTED_DSH_VERSIONS.includes(dshVersion)) {
+    throw new Error(`unsupported DSH version ${dshVersion || "<empty>"}; expected one of ${SUPPORTED_DSH_VERSIONS.join(", ")}`);
+  }
+  let rendered = composition.replace(/\r\n/gu, "\n");
+  if (dshVersion === SOURCE_DSH_VERSION) return rendered;
+  const targetComment = OPTIONAL_PROVIDER_COMMENTS[dshVersion];
+  if (!targetComment) throw new Error(`missing Agent composition contract for DSH ${dshVersion}`);
+  rendered = replaceCompositionContract(
+    rendered,
+    OPTIONAL_PROVIDER_COMMENTS[SOURCE_DSH_VERSION],
+    targetComment,
+    "optional-provider comment",
+  );
+  if (dshVersion === "0.1.0-rc.7") return rendered;
+  rendered = replaceCompositionContract(
+    rendered,
+    "        provider: codex\n        toolName: subagent_codex\n        backgroundMode: one-shot",
+    "        provider: codex\n        toolName: subagent_codex\n        enableRunInBackground: false",
+    "Codex provider",
+  );
+  return replaceCompositionContract(
+    rendered,
+    "        provider: claude-code\n        toolName: subagent_claude_code\n        backgroundMode: one-shot",
+    "        provider: claude-code\n        toolName: subagent_claude_code\n        enableRunInBackground: false",
+    "Claude Code provider",
+  );
+}
+
+export function resolveDshHome(configured, env = process.env) {
+  const value = configured ?? env.DSH_HOME ?? resolve(homedir(), ".dsh");
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError("DSH home must be a non-empty path");
+  }
+  const trimmed = value.trim();
+  if (trimmed === "~") return homedir();
+  if (trimmed.startsWith(`~${sep}`)) return resolve(homedir(), trimmed.slice(2));
+  return resolve(trimmed);
+}
+
+export async function inspectAgentInstallation(options = {}) {
+  const presetId = assertPresetId(options.presetId ?? DEFAULT_PRESET_ID);
+  const dshHome = resolveDshHome(options.dshHome);
+  const target = resolve(dshHome, ".agent-presets", presetId);
+  const state = await inspectTarget(target, presetId);
+  return Object.freeze({ dshHome, presetId, target, ...state });
+}
+
+export async function installAgentPreset(options = {}) {
+  const presetId = assertPresetId(options.presetId ?? DEFAULT_PRESET_ID);
+  const dshHome = resolveDshHome(options.dshHome);
+  const sourceRoot = resolve(options.sourceRoot ?? defaultSourceRoot);
+  const dshVersion = options.dshVersion ?? SUPPORTED_DSH_VERSION;
+  if (!SUPPORTED_DSH_VERSIONS.includes(dshVersion)) {
+    throw new Error(`unsupported DSH version ${dshVersion || "<empty>"}; expected one of ${SUPPORTED_DSH_VERSIONS.join(", ")}`);
+  }
+  const targetRoot = resolve(dshHome, ".agent-presets");
+  const target = resolve(targetRoot, presetId);
+  const current = await inspectTarget(target, presetId);
+  const previousCompositionSize = current.status === "installed"
+    ? Buffer.byteLength(await readFile(resolve(target, "agent.cordis.yml")))
+    : undefined;
+
+  if (current.status === "drifted") {
+    throw new Error(`refusing to replace modified preset at ${target}: ${current.issues.join("; ")}`);
+  }
+
+  await assertSource(sourceRoot);
+  const sessionCompatibility = await repairSessionCompatibility(
+    dshHome,
+    [sourceRoot],
+    options.confirmDshStopped === true,
+    options.processScanner,
+  );
+  await mkdir(targetRoot, { recursive: true, mode: 0o700 });
+  const staging = resolve(targetRoot, `.${presetId}.tmp-${process.pid}-${randomUUID()}`);
+  const backup = resolve(targetRoot, `.${presetId}.backup-${process.pid}-${randomUUID()}`);
+  let backupCreated = false;
+
+  try {
+    await cp(sourceRoot, staging, { recursive: true, errorOnExist: true });
+    await tightenTree(staging);
+    const compositionPath = resolve(staging, "agent.cordis.yml");
+    const composition = renderAgentCompositionForDsh(await readFile(compositionPath, "utf8"), dshVersion);
+    let stampedComposition = `${composition.trimEnd()}\n# odai-dsh-agent generation ${packageMetadata.version}:${randomUUID()}\n`;
+    // Supported DSH releases key standing generations by mtime and size, so size must change even on same-tick updates.
+    if (previousCompositionSize === Buffer.byteLength(stampedComposition)) {
+      stampedComposition += "# odai-dsh-agent generation size bump\n";
+    }
+    await writeFile(compositionPath, stampedComposition, "utf8");
+    const files = await hashTree(staging);
+    const manifest = {
+      schemaVersion: 1,
+      package: packageMetadata.name,
+      version: packageMetadata.version,
+      dshVersion,
+      presetId,
+      files,
+    };
+    const manifestPath = resolve(staging, MANIFEST_FILE);
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    await chmod(manifestPath, 0o600);
+
+    if (current.status === "installed") {
+      await rename(target, backup);
+      backupCreated = true;
+    }
+    await rename(staging, target);
+    if (backupCreated) {
+      await rm(backup, { recursive: true, force: true });
+      backupCreated = false;
+    }
+
+    return Object.freeze({
+      operation: current.status === "installed" ? "updated" : "installed",
+      dshHome,
+      presetId,
+      target,
+      version: packageMetadata.version,
+      dshVersion,
+      trust: "user",
+      security: "DSH user presets have the same privileges as shell access; install only reviewed preset code.",
+      sessionCompatibility,
+    });
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    if (backupCreated) {
+      const targetState = await pathState(target);
+      if (targetState === "missing") await rename(backup, target);
+    }
+    throw error;
+  } finally {
+    await rm(backup, { recursive: true, force: true });
+  }
+}
+
+export async function uninstallAgentPreset(options = {}) {
+  const inspected = await inspectAgentInstallation(options);
+  if (inspected.status === "absent") {
+    return Object.freeze({ operation: "absent", target: inspected.target, presetId: inspected.presetId });
+  }
+  if (inspected.status === "drifted") {
+    throw new Error(`refusing to remove modified preset at ${inspected.target}: ${inspected.issues.join("; ")}`);
+  }
+  await assertPresetIsNotDefault(inspected.dshHome, inspected.presetId);
+  const sessionCompatibility = await repairSessionCompatibility(
+    inspected.dshHome,
+    [defaultSourceRoot, inspected.target],
+    options.confirmDshStopped === true,
+    options.processScanner,
+  );
+  if (sessionCompatibility.failures.length > 0) {
+    throw new Error(`refusing to uninstall before legacy Odai session evidence is made ignorable: ${sessionCompatibility.failures.map((failure) => `${failure.path}: ${failure.error}`).join("; ")}`);
+  }
+  await rm(inspected.target, { recursive: true, force: true });
+  return Object.freeze({
+    operation: "uninstalled",
+    target: inspected.target,
+    presetId: inspected.presetId,
+    sessionCompatibility,
+  });
+}
+
+async function assertPresetIsNotDefault(dshHome, presetId) {
+  const settingsPath = resolve(dshHome, "settings.yaml");
+  let text;
+  try {
+    text = await readFile(settingsPath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+  let settings;
+  try {
+    settings = parseYaml(text) ?? {};
+  } catch (error) {
+    throw new Error(`cannot verify the default agent preset in ${settingsPath}: ${error.message}`);
+  }
+  if (settings?.["agent-presets"]?.default === presetId) {
+    throw new Error(`refusing to uninstall the default preset ${presetId}; select another agent-presets.default first`);
+  }
+}
+
+async function inspectTarget(target, presetId) {
+  const state = await pathState(target);
+  if (state === "missing") return { status: "absent", issues: [] };
+  if (state !== "directory") return { status: "drifted", issues: ["target is not a regular directory"] };
+
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(resolve(target, MANIFEST_FILE), "utf8"));
+  } catch (error) {
+    return { status: "drifted", issues: [`managed manifest is unavailable: ${error.message}`] };
+  }
+
+  const issues = validateManifest(manifest, presetId);
+  let actualFiles = {};
+  try {
+    actualFiles = await hashTree(target, { exclude: new Set([MANIFEST_FILE]) });
+  } catch (error) {
+    issues.push(error.message);
+  }
+
+  if (issues.length === 0) {
+    const expectedFiles = manifest.files;
+    for (const [path, hash] of Object.entries(expectedFiles)) {
+      if (!(path in actualFiles)) issues.push(`missing managed file ${path}`);
+      else if (actualFiles[path] !== hash) issues.push(`modified managed file ${path}`);
+    }
+    for (const path of Object.keys(actualFiles)) {
+      if (!(path in expectedFiles)) issues.push(`unmanaged file ${path}`);
+    }
+  }
+
+  return {
+    status: issues.length === 0 ? "installed" : "drifted",
+    issues,
+    version: typeof manifest?.version === "string" ? manifest.version : undefined,
+    dshVersion: typeof manifest?.dshVersion === "string" ? manifest.dshVersion : undefined,
+  };
+}
+
+function validateManifest(manifest, presetId) {
+  const issues = [];
+  if (manifest?.schemaVersion !== 1) issues.push("unsupported managed manifest schema");
+  if (manifest?.package !== packageMetadata.name) issues.push("managed manifest package mismatch");
+  if (manifest?.presetId !== presetId) issues.push("managed manifest preset id mismatch");
+  if (!manifest?.files || typeof manifest.files !== "object" || Array.isArray(manifest.files)) {
+    issues.push("managed manifest file map is invalid");
+  }
+  return issues;
+}
+
+async function repairSessionCompatibility(dshHome, sourceRoots, confirmDshStopped, processScanner) {
+  for (const sourceRoot of sourceRoots) {
+    const modulePath = resolve(sourceRoot, "runtime/session-compat.mjs");
+    if (await pathState(modulePath) !== "file") continue;
+    const compatibility = await import(pathToFileURL(modulePath).href);
+    if (typeof compatibility.inspectLegacySessionLogs !== "function"
+      || typeof compatibility.repairLegacySessionLogs !== "function") {
+      throw new Error(`agent package session compatibility module is invalid: ${modulePath}`);
+    }
+    const inspected = compatibility.inspectLegacySessionLogs({ dshHome });
+    if (inspected.failures.length > 0) {
+      throw new Error(`cannot inspect legacy Odai session evidence safely: ${inspected.failures.map((failure) => `${failure.path}: ${failure.error}`).join("; ")}`);
+    }
+    if (inspected.matchedEvents === 0) return inspected;
+    if (!confirmDshStopped) {
+      throw new Error(`found ${inspected.matchedEvents} legacy Odai session event(s); stop every DSH process and rerun with --yes before changing the Agent preset`);
+    }
+    const repaired = compatibility.repairLegacySessionLogs({
+      dshHome,
+      confirmDshStopped: true,
+      processScanner,
+    });
+    if (repaired.failures.length > 0) {
+      throw new Error(`cannot repair legacy Odai session evidence safely: ${repaired.failures.map((failure) => `${failure.path}: ${failure.error}`).join("; ")}`);
+    }
+    return repaired;
+  }
+  throw new Error("agent package is incomplete: missing runtime/session-compat.mjs");
+}
+
+async function assertSource(sourceRoot) {
+  for (const path of requiredFiles) {
+    const state = await pathState(resolve(sourceRoot, path));
+    if (state !== "file") throw new Error(`agent package is incomplete: missing ${path}`);
+  }
+}
+
+async function tightenTree(root) {
+  await chmod(root, 0o700);
+  const entries = await readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const path = resolve(root, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`symbolic link is not allowed in managed preset: ${entry.name}`);
+    if (entry.isDirectory()) await tightenTree(path);
+    else if (entry.isFile()) await chmod(path, 0o600);
+    else throw new Error(`unsupported filesystem entry in managed preset: ${entry.name}`);
+  }
+}
+
+async function hashTree(root, options = {}) {
+  const found = {};
+  await walk(root, "");
+  return Object.fromEntries(Object.entries(found).sort(([left], [right]) => left.localeCompare(right)));
+
+  async function walk(base, prefix) {
+    const entries = await readdir(base, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (options.exclude?.has(relativePath)) continue;
+      const absolutePath = resolve(base, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`symbolic link is not allowed in managed preset: ${relativePath}`);
+      if (entry.isDirectory()) await walk(absolutePath, relativePath);
+      else if (entry.isFile()) found[relativePath] = await hashFile(absolutePath);
+      else throw new Error(`unsupported filesystem entry in managed preset: ${relativePath}`);
+    }
+  }
+}
+
+async function hashFile(path) {
+  return createHash("sha256").update(await readFile(path)).digest("hex");
+}
+
+async function pathState(path) {
+  try {
+    const stats = await lstat(path);
+    if (stats.isSymbolicLink()) return "symlink";
+    if (stats.isDirectory()) return "directory";
+    if (stats.isFile()) return "file";
+    return "other";
+  } catch (error) {
+    if (error?.code === "ENOENT") return "missing";
+    throw error;
+  }
+}
+
+function assertPresetId(value) {
+  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(value)) {
+    throw new TypeError("preset id must contain only letters, digits, dots, underscores, or hyphens");
+  }
+  return value;
+}