odai-dsh-agent 0.0.1

package/preset/odai/skills/odai/scripts/verify-routing.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const args = parseArgs(process.argv.slice(2));
+const mappings = new Map([["odai_planner", "planner"], ["odai_executor", "executor"], ["odai_reviewer", "reviewer"]]);
+
+if (args.help) {
+  console.log(`Usage:
+  node odai-verify-routing.mjs --host codex --project <directory> \\
+    --role <odai_planner|odai_executor|odai_reviewer> --after <ISO timestamp> \\
+    [--agent-path </root/task>] [--sessions <directory>]
+
+只读取近期 Codex rollout metadata，把实际角色、模型与推理档和 odai 托管清单对账。`);
+  process.exit(0);
+}
+if (args.host !== "codex") fail(`不支持的 host：${args.host || "(missing)"}`);
+if (!mappings.has(args.role)) fail("--role 必须是 odai_planner、odai_executor 或 odai_reviewer");
+if (!args.project || !args.after) fail("缺少 --project 或 --after");
+const after = Date.parse(args.after);
+if (!Number.isFinite(after)) fail(`无效的 --after：${args.after}`);
+
+const project = path.resolve(args.project);
+const manifestFile = path.join(scriptDir, "odai-routing.json");
+if (!existsSync(manifestFile)) fail(`缺少路由清单：${manifestFile}`);
+const manifest = JSON.parse(readFileSync(manifestFile, "utf8"));
+if (manifest.id !== "odai-routing-installation" || manifest.host !== "codex") fail("路由清单无效");
+for (const [relative, expected] of Object.entries(manifest.files || {})) {
+  const target = path.join(scriptDir, relative);
+  if (!existsSync(target) || sha256(readFileSync(target)) !== expected) fail(`路由托管文件缺失或已变化：${relative}`);
+}
+const expected = manifest.mapping?.[mappings.get(args.role)];
+if (!expected?.model) fail("路由清单缺少角色模型映射");
+
+const sessions = path.resolve(args.sessions || path.join(process.env.CODEX_HOME || path.join(homedir(), ".codex"), "sessions"));
+if (!existsSync(sessions)) fail(`Codex sessions 不存在：${sessions}`);
+const candidates = [];
+for (const file of recentJsonl(sessions, after - 5000)) {
+  const metadata = readMetadata(file);
+  const session = metadata.session;
+  const source = session?.source?.subagent?.thread_spawn;
+  if (!source || session.agent_role !== args.role || path.resolve(session.cwd || "") !== project) continue;
+  const started = Date.parse(session.timestamp || "");
+  if (!Number.isFinite(started) || started < after) continue;
+  if (args.agentPath && source.agent_path !== args.agentPath) continue;
+  if (metadata.context) candidates.push({ session, context: metadata.context, source });
+}
+if (candidates.length !== 1) fail(candidates.length ? `找到 ${candidates.length} 个候选子会话；请用 --agent-path 消除歧义` : "未找到满足边界的子会话运行时记录");
+const match = candidates[0];
+const actualModel = match.context.model;
+const actualEffort = match.context.effort || match.context.collaboration_mode?.settings?.reasoning_effort || null;
+if (actualModel !== expected.model) fail(`模型不匹配：期望 ${expected.model}，实际 ${actualModel || "(missing)"}`);
+if (expected.reasoning_effort && actualEffort !== expected.reasoning_effort) fail(`推理档不匹配：期望 ${expected.reasoning_effort}，实际 ${actualEffort || "(missing)"}`);
+
+process.stdout.write(`${JSON.stringify({
+  verified: true, role: match.session.agent_role, model: actualModel, reasoning_effort: actualEffort,
+  agent_path: match.source.agent_path || null, child_thread_id: match.session.id,
+  parent_thread_id: match.session.parent_thread_id || null, project,
+}, null, 2)}\n`);
+
+function recentJsonl(root, threshold) {
+  const files = [];
+  const pending = [root];
+  while (pending.length) {
+    const directory = pending.pop();
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const full = path.join(directory, entry.name);
+      if (entry.isDirectory()) pending.push(full);
+      else if (entry.isFile() && entry.name.endsWith(".jsonl") && statSync(full).mtimeMs >= threshold) files.push(full);
+    }
+  }
+  return files;
+}
+function readMetadata(file) {
+  let session = null; let context = null;
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line) continue;
+    let event; try { event = JSON.parse(line); } catch { continue; }
+    if (event.type === "session_meta") session = event.payload;
+    if (event.type === "turn_context") context = event.payload;
+    if (session && context) break;
+  }
+  return { session, context };
+}
+function parseArgs(values) {
+  const result = { host: "", project: "", role: "", after: "", agentPath: "", sessions: "", help: false };
+  const fields = new Map([["--host", "host"], ["--project", "project"], ["--role", "role"], ["--after", "after"], ["--agent-path", "agentPath"], ["--sessions", "sessions"]]);
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (value === "--help" || value === "-h") result.help = true;
+    else if (fields.has(value)) { const next = values[++index] || ""; if (!next || next.startsWith("--")) fail(`${value} 需要一个值`); result[fields.get(value)] = next; }
+    else fail(`未知参数：${value}`);
+  }
+  return result;
+}
+function sha256(value) { return createHash("sha256").update(value).digest("hex"); }
+function fail(message) { console.error(message); process.exit(1); }

package/scripts/verify-agent-load.mjs

@@ -0,0 +1,217 @@
+import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { execFileSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+
+import { installAgentPreset, SUPPORTED_DSH_VERSION } from "../src/installer.mjs";
+
+const agentRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const repoRoot = resolve(agentRoot, "../..");
+const dsh = process.env.DSH_BIN ?? "dsh";
+const dshRoot = process.env.DSH_PACKAGE_ROOT
+  ? resolve(process.env.DSH_PACKAGE_ROOT)
+  : findDshPackageRoot(dsh);
+const scopeModule = resolve(dshRoot, "node_modules/@deepseek-ai/dsh-scope/lib/index.js");
+await verifyPinnedComposition();
+const scratch = await mkdtemp(resolve(tmpdir(), "odai-agent-scope-"));
+const home = resolve(scratch, "home");
+const workspace = resolve(scratch, "workspace");
+const sourceRoot = resolve(scratch, "source-preset");
+const markerPath = resolve(scratch, "scope-results.json");
+const probePluginPath = resolve(scratch, "scope-probe-plugin.mjs");
+const patchPath = resolve(scratch, "scope-probe.patch.yml");
+
+const yaml = (value) => JSON.stringify(value);
+
+function findDshPackageRoot(command) {
+  const locator = process.platform === "win32" ? "where" : "which";
+  const located = execFileSync(locator, [command], { encoding: "utf8" }).trim().split(/\r?\n/u)[0];
+  let current = dirname(realpathSync(located));
+  while (dirname(current) !== current) {
+    try {
+      const metadata = JSON.parse(readFileSync(resolve(current, "package.json"), "utf8"));
+      if (metadata.name === "@deepseek-ai/dsh") return current;
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    current = dirname(current);
+  }
+  throw new Error(`cannot locate the @deepseek-ai/dsh package behind ${command}`);
+}
+
+async function verifyPinnedComposition() {
+  const dshMetadata = JSON.parse(await readFile(resolve(dshRoot, "package.json"), "utf8"));
+  if (dshMetadata.version !== SUPPORTED_DSH_VERSION) {
+    throw new Error(`agent preset expects DSH ${SUPPORTED_DSH_VERSION}, found ${dshMetadata.version}`);
+  }
+
+  const standard = await readFile(resolve(dshRoot, "config/agent-presets/standard/agent.cordis.yml"), "utf8");
+  const odaiSuffix = [
+    "# Odai contributes scoped prompt, guard, routing, user-owned responsibility",
+    "# mappings, and evidence listeners. Base controller selection stays host-owned.",
+    "- id: odai-governance",
+    "  name: ./runtime/index.mjs",
+    "  config:",
+    "    routing:",
+    "      mode: auto",
+    "      provider: spawn",
+  ].join("\n");
+  const expected = `${standard
+    .replace(
+      "# The preset's own persona, shadowing the deployment default for this agent.\n# `{{model}}` and `{{cwd}}` resolve from the agent's own route and workspace.",
+      "# The preset's own model-neutral persona shadows the deployment default. Auto\n# routing can upgrade after prompt assembly; `{{cwd}}` remains workspace-local.",
+    )
+    .replace(
+      "You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.",
+      "You are Odai, a coding agent. Your working directory is {{cwd}}.",
+    )
+    .trimEnd()}\n\n${odaiSuffix}`;
+  const actual = (await readFile(resolve(agentRoot, "preset/odai/agent.cordis.yml"), "utf8")).trimEnd();
+  if (actual !== expected) {
+    throw new Error("Odai Agent composition drifted from the pinned DSH standard preset");
+  }
+}
+
+async function freePort() {
+  return await new Promise((accept, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : undefined;
+      server.close((error) => error ? reject(error) : accept(port));
+    });
+  });
+}
+
+async function rpc(baseUrl, method, payload) {
+  const rpcId = randomUUID();
+  const response = await fetch(`${baseUrl}/api/${method}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ type: "client-request", rpcId, method, payload }),
+  });
+  const text = await response.text();
+  if (!response.ok) throw new Error(`${method} HTTP ${response.status}: ${text}`);
+  const body = JSON.parse(text);
+  if (body.result?.ok !== true) throw new Error(`${method} failed: ${text}`);
+  return body.result.value;
+}
+
+async function waitForServer(baseUrl, child, output) {
+  const deadline = Date.now() + 20_000;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) throw new Error(`dsh web exited early (${child.exitCode})\n${output()}`);
+    try {
+      await rpc(baseUrl, "agentPreset.list", {});
+      return;
+    } catch {
+      await new Promise((accept) => setTimeout(accept, 75));
+    }
+  }
+  throw new Error(`timed out waiting for dsh web\n${output()}`);
+}
+
+async function waitForMarker(child, output) {
+  const deadline = Date.now() + 15_000;
+  while (Date.now() < deadline) {
+    if (existsSync(markerPath)) return JSON.parse(await readFile(markerPath, "utf8"));
+    if (child.exitCode !== null) throw new Error(`dsh web exited before probe completed (${child.exitCode})\n${output()}`);
+    await new Promise((accept) => setTimeout(accept, 50));
+  }
+  throw new Error(`timed out waiting for scope marker\n${output()}`);
+}
+
+await mkdir(workspace, { recursive: true });
+await cp(resolve(agentRoot, "preset/odai"), sourceRoot, { recursive: true });
+const developmentRuntime = resolve(repoRoot, "dsh/runtime/src");
+const developmentSkill = resolve(repoRoot, "skills/odai");
+if (existsSync(developmentRuntime) && existsSync(developmentSkill)) {
+  await Promise.all([
+    cp(developmentRuntime, resolve(sourceRoot, "runtime"), { recursive: true }),
+    cp(developmentSkill, resolve(sourceRoot, "skills/odai"), { recursive: true }),
+  ]);
+} else if (!existsSync(resolve(sourceRoot, "runtime/index.mjs"))
+  || !existsSync(resolve(sourceRoot, "skills/odai/SKILL.md"))) {
+  throw new Error("Odai Agent verification requires either repository sources or packaged runtime and skill files");
+}
+await installAgentPreset({ dshHome: home, sourceRoot });
+
+const probePlugin = `import { existsSync, readFileSync, writeFileSync } from "node:fs";\nimport { bindScopeParent } from ${JSON.stringify(pathToFileURL(scopeModule).href)};\n\nexport const name = "odai-agent-scope-probe";\nexport const inject = ["systemPrompt", "tools"];\n\nexport function apply(ctx, config) {\n  const results = {};\n  let writing = Promise.resolve();\n\n  ctx.on("agent/created", ({ agent }) => {\n    writing = writing.then(async () => {\n      const preset = agent.session?.header?.agentPreset;\n      if (preset !== "standard" && preset !== "odai") return;\n\n      const assembly = await ctx.systemPrompt.assemble({ scope: agent });\n      const canonicalSections = assembly.sections.filter((section) => section.name === "odai:canonical-governance");\n      const writePath = preset === "odai" ? config.odaiWritePath : config.standardWritePath;\n      const childSession = new Proxy(agent.session, {\n        get(target, property) {\n          if (property === "header") {\n            return { ...target.header, origin: "subagent", delegationDepth: 1 };\n          }\n          return Reflect.get(target, property, target);\n        },\n      });\n      const child = { id: agent.id, session: childSession };\n      bindScopeParent(child, agent);\n      const toolResult = await ctx.tools.execute({\n        callId: \`scope-probe-\${preset}\`,\n        name: "write",\n        arguments: { file_path: writePath, content: \`\${preset} child write reached body\\n\` },\n        agent: child,\n        signal: new AbortController().signal,\n      });\n\n      let routingConfigured;\n      if (preset === "odai") {\n        const routingResult = await ctx.tools.execute({\n          callId: "scope-probe-odai-routing-config",\n          name: "odai_routing_config",\n          arguments: { action: "set", responsibility: "executor", provider: "probe-provider", model: "probe-executor", reasoningEffort: "high" },\n          agent,\n          signal: new AbortController().signal,\n        });\n        if (routingResult.isError) throw new Error(\`odai routing config tool failed: \${routingResult.error?.message}\`);\n        const stored = JSON.parse(readFileSync(config.routingConfigPath, "utf8"));\n        routingConfigured = stored.roles?.executor?.provider === "probe-provider"\n          && stored.roles?.executor?.model === "probe-executor";\n      }\n\n      results[preset] = {\n        canonicalSectionCount: canonicalSections.length,\n        toolIsError: toolResult.isError === true,\n        toolError: toolResult.isError === true ? toolResult.error?.message : undefined,\n        writeReachedBody: existsSync(writePath),\n        ...(routingConfigured === undefined ? {} : { routingConfigured }),\n      };\n      if (results.standard && results.odai) {\n        writeFileSync(config.markerPath, JSON.stringify(results, null, 2) + "\\n", "utf8");\n      }\n    }).catch((error) => {\n      writeFileSync(config.markerPath, JSON.stringify({ probeError: error?.stack ?? String(error) }, null, 2) + "\\n", "utf8");\n    });\n  }, { global: true });\n}\n`;
+await writeFile(probePluginPath, probePlugin, "utf8");
+await writeFile(patchPath, [
+  "- insert:",
+  "    - id: odai-agent-scope-probe",
+  `      name: ${yaml(probePluginPath)}`,
+  "      config:",
+  `        markerPath: ${yaml(markerPath)}`,
+  `        standardWritePath: ${yaml(resolve(workspace, "standard-child-write.txt"))}`,
+  `        odaiWritePath: ${yaml(resolve(workspace, "odai-child-write.txt"))}`,
+  `        routingConfigPath: ${yaml(resolve(home, "odai/routing.json"))}`,
+  "",
+].join("\n"), "utf8");
+
+const port = await freePort();
+const baseUrl = `http://127.0.0.1:${port}`;
+const child = spawn(dsh, [
+  "--profile", "web",
+  "--patch", patchPath,
+  "--host", "127.0.0.1",
+  "--port", String(port),
+], {
+  cwd: workspace,
+  env: {
+    ...process.env,
+    DSH_HOME: home,
+    DSH_TELEMETRY_MODE: "DISABLED",
+  },
+  stdio: ["ignore", "pipe", "pipe"],
+});
+let output = "";
+child.stdout.on("data", (chunk) => { output += chunk.toString(); });
+child.stderr.on("data", (chunk) => { output += chunk.toString(); });
+const capturedOutput = () => output;
+
+try {
+  await waitForServer(baseUrl, child, capturedOutput);
+  const roster = await rpc(baseUrl, "agentPreset.list", {});
+  const ids = roster.presets.map((preset) => preset.id);
+  if (!ids.includes("standard") || !ids.includes("odai")) {
+    throw new Error(`expected standard and odai presets, got ${JSON.stringify(ids)}`);
+  }
+  await rpc(baseUrl, "session.create", { cwd: workspace, agentPreset: "standard" });
+  await rpc(baseUrl, "session.create", { cwd: workspace, agentPreset: "odai" });
+  const results = await waitForMarker(child, capturedOutput);
+  if (results.probeError) throw new Error(results.probeError);
+  if (results.standard?.canonicalSectionCount !== 0) {
+    throw new Error(`standard saw odai canonical prompt: ${JSON.stringify(results)}`);
+  }
+  if (results.standard?.toolError?.startsWith("ODAI_SUBAGENT_BOUNDARY:")) {
+    throw new Error(`standard child call reached the odai guard: ${JSON.stringify(results)}`);
+  }
+  if (results.odai?.canonicalSectionCount !== 1) {
+    throw new Error(`odai canonical prompt count was not exactly one: ${JSON.stringify(results)}`);
+  }
+  if (results.odai?.writeReachedBody !== false || results.odai?.toolIsError !== true
+    || !results.odai?.toolError?.startsWith("ODAI_SUBAGENT_BOUNDARY:")) {
+    throw new Error(`odai child write was not denied by odai guard: ${JSON.stringify(results)}`);
+  }
+  if (results.odai?.routingConfigured !== true) {
+    throw new Error(`odai natural routing tool did not persist through DSH: ${JSON.stringify(results)}`);
+  }
+  process.stdout.write(`${JSON.stringify({ scratch, roster: ids, results }, null, 2)}\n`);
+} finally {
+  child.kill("SIGTERM");
+  await new Promise((accept) => {
+    if (child.exitCode !== null) return accept();
+    const timeout = setTimeout(() => { child.kill("SIGKILL"); accept(); }, 3_000);
+    child.once("exit", () => { clearTimeout(timeout); accept(); });
+  });
+  if (process.env.KEEP_ODAI_SCOPE_PROBE !== "1") {
+    await rm(scratch, { recursive: true, force: true });
+  }
+}

package/src/installer.mjs

@@ -0,0 +1,270 @@
+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 } 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"));
+export const SUPPORTED_DSH_VERSION = packageMetadata.peerDependencies["@deepseek-ai/dsh"];
+const requiredFiles = Object.freeze([
+  "agent.cordis.yml",
+  "preset.yml",
+  "runtime/index.mjs",
+  "skills/odai/SKILL.md",
+]);
+
+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 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);
+  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 = await readFile(compositionPath, "utf8");
+    let stampedComposition = `${composition.trimEnd()}\n# odai-dsh-agent generation ${packageMetadata.version}:${randomUUID()}\n`;
+    // DSH rc.6 keys 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,
+      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,
+      trust: "user",
+      security: "DSH user presets have the same privileges as shell access; install only reviewed preset code.",
+    });
+  } 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);
+  await rm(inspected.target, { recursive: true, force: true });
+  return Object.freeze({ operation: "uninstalled", target: inspected.target, presetId: inspected.presetId });
+}
+
+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,
+  };
+}
+
+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 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;
+}