@netpilot/skills 0.3.2 → 0.6.0

package/scripts/sync.mjs

@@ -1,5 +1,17 @@
 import { createHash, randomUUID } from "node:crypto";
-import { copyFile, lstat, mkdir, open, readFile, readdir, realpath, rm, writeFile } from "node:fs/promises";
+import {
+  copyFile,
+  link,
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  realpath,
+  rename,
+  rm,
+  rmdir,
+  writeFile,
+} from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -12,10 +24,22 @@ const HOST_DESTINATIONS = {
 };
 
 const CODEX_AGENT_DESTINATION = [".codex", "agents"];
+const CURRENT_STATE_DESTINATION = [".agents", ".state", "skills-installer"];
+const LEGACY_STATE_DESTINATION = [".netpilot-skills"];
+const LAYOUT_LOCK_DIRECTORY = [".agents", ".state"];
+const LAYOUT_LOCK_NAME = "skills-installer.layout.lock";
 
 const ALL_HOSTS = Object.freeze(Object.keys(HOST_DESTINATIONS));
 const ALL_COMPONENTS = Object.freeze(["skills", "agents"]);
+const COMPONENT_ALIASES = Object.freeze({
+  "system-agents": "agents",
+});
 const SUPPORT_FILE_NAMES = Object.freeze(["LICENSE", "THIRD_PARTY_NOTICES.md"]);
+const MANAGED_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+function canonicalComponent(component) {
+  return COMPONENT_ALIASES[component] ?? component;
+}
 
 export class SyncConflictError extends Error {
   constructor(conflicts) {
@@ -27,16 +51,30 @@ export class SyncConflictError extends Error {
 
 export function parseArgs(argv) {
   let apply = false;
+  let requestedMode = null;
   let homeDir = os.homedir();
-  let hosts = [...ALL_HOSTS];
-  let components = ["skills"];
+  let hosts = ["codex"];
+  let components = [...ALL_COMPONENTS];
+  let componentSpecified = false;
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
     if (argument === "--apply") {
+      if (requestedMode === "dry-run") {
+        throw new Error("--apply 与 --dry-run 不能同时使用");
+      }
+      requestedMode = "apply";
       apply = true;
       continue;
     }
+    if (argument === "--dry-run") {
+      if (requestedMode === "apply") {
+        throw new Error("--apply 与 --dry-run 不能同时使用");
+      }
+      requestedMode = "dry-run";
+      apply = false;
+      continue;
+    }
     if (argument === "--host") {
       const host = argv[index + 1];
       if (!host) throw new Error("--host 需要 codex、claude 或 all");
@@ -52,12 +90,15 @@ export function parseArgs(argv) {
     }
     if (argument === "--component") {
       const component = argv[index + 1];
-      if (!component) throw new Error("--component 需要 skills、agents 或 all");
+      if (!component) {
+        throw new Error("--component 需要 skills、system-agents、agents 或 all");
+      }
       index += 1;
+      componentSpecified = true;
       if (component === "all") {
         components = [...ALL_COMPONENTS];
-      } else if (ALL_COMPONENTS.includes(component)) {
-        components = [component];
+      } else if (ALL_COMPONENTS.includes(canonicalComponent(component))) {
+        components = [canonicalComponent(component)];
       } else {
         throw new Error(`不支持的组件：${component}`);
       }
@@ -75,6 +116,10 @@ export function parseArgs(argv) {
     throw new Error(`未知参数：${argument}`);
   }
 
+  if (!componentSpecified && !hosts.includes("codex")) {
+    components = ["skills"];
+  }
+
   return { apply, homeDir, hosts, components };
 }
 
@@ -86,6 +131,35 @@ async function hashFile(filePath) {
   return sha256(await readFile(filePath));
 }
 
+function projectCodexSkill(skillContent) {
+  const frontmatter = skillContent.match(/^---\r?\n([\s\S]*?)\r?\n---(?=\r?\n|$)/u);
+  if (!frontmatter) return skillContent;
+
+  const newline = frontmatter[0].includes("\r\n") ? "\r\n" : "\n";
+  const omittedKeys = new Set(["argument-hint", "disable-model-invocation"]);
+  const projectedLines = [];
+  let omittingValue = false;
+
+  for (const line of frontmatter[1].split(/\r?\n/u)) {
+    const key = /^([a-z0-9-]+):(?:\s|$)/iu.exec(line)?.[1] ?? null;
+    if (key) {
+      omittingValue = omittedKeys.has(key);
+      if (!omittingValue) projectedLines.push(line);
+      continue;
+    }
+    if (omittingValue && (/^[ \t]/u.test(line) || line.trim() === "")) continue;
+    omittingValue = false;
+    projectedLines.push(line);
+  }
+
+  const projectedFrontmatter = [
+    "---",
+    ...projectedLines,
+    "---",
+  ].join(newline);
+  return projectedFrontmatter + skillContent.slice(frontmatter[0].length);
+}
+
 async function readManifest(manifestPath) {
   try {
     const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
@@ -228,12 +302,517 @@ async function inspectAncestorPath(basePath, targetDirectory) {
   return { safe: true };
 }
 
+async function inspectHomeRoot(homeDir) {
+  const resolvedHome = path.resolve(homeDir);
+  const parsed = path.parse(resolvedHome);
+  let currentPath = parsed.root;
+  const segments = path.relative(parsed.root, resolvedHome).split(path.sep).filter(Boolean);
+
+  for (const segment of segments) {
+    currentPath = path.join(currentPath, segment);
+    try {
+      const stats = await lstat(currentPath);
+      if (stats.isSymbolicLink()) {
+        const isHomeRoot = path.resolve(currentPath) === resolvedHome;
+        return {
+          safe: false,
+          path: currentPath,
+          reason: isHomeRoot
+            ? "home 根目录是 symlink 或 junction"
+            : "home 路径的父目录是 symlink 或 junction",
+        };
+      }
+      if (!stats.isDirectory()) {
+        return {
+          safe: false,
+          path: currentPath,
+          reason:
+            path.resolve(currentPath) === resolvedHome
+              ? "home 根路径不是目录"
+              : "home 路径的父路径不是目录",
+        };
+      }
+    } catch (error) {
+      if (error.code === "ENOENT") return { safe: true };
+      throw error;
+    }
+  }
+
+  return { safe: true };
+}
+
+async function assertSafeHomeRoot(homeDir) {
+  const homeSafety = await inspectHomeRoot(homeDir);
+  if (homeSafety.safe) return;
+  throw new SyncConflictError([
+    {
+      host: "state",
+      component: "home",
+      assetName: "home",
+      skillName: "home",
+      relativePath: ".",
+      targetPath: homeDir,
+      action: "conflict",
+      reason: `${homeSafety.reason}：${homeSafety.path}`,
+    },
+  ]);
+}
+
+function resolveStatePaths(homeDir) {
+  const currentStateDir = path.join(homeDir, ...CURRENT_STATE_DESTINATION);
+  const legacyStateDir = path.join(homeDir, ...LEGACY_STATE_DESTINATION);
+  return {
+    currentStateDir,
+    currentManifestPath: path.join(currentStateDir, "manifest.json"),
+    legacyStateDir,
+    legacyManifestPath: path.join(legacyStateDir, "manifest.json"),
+    layoutLockDir: path.join(homeDir, ...LAYOUT_LOCK_DIRECTORY),
+  };
+}
+
+function stateLayoutConflict(homeDir, reason, targetPath = homeDir) {
+  return new SyncConflictError([
+    {
+      host: "state",
+      component: "layout",
+      assetName: "state-layout",
+      skillName: "state-layout",
+      relativePath: ".",
+      targetPath,
+      action: "conflict",
+      reason,
+    },
+  ]);
+}
+
+async function inspectStateDirectory(homeDir, targetPath) {
+  const ancestor = await inspectAncestorPath(homeDir, targetPath);
+  if (!ancestor.safe) {
+    throw stateLayoutConflict(
+      homeDir,
+      `${ancestor.reason}：${ancestor.path}`,
+      targetPath,
+    );
+  }
+  try {
+    const stats = await lstat(targetPath);
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+      throw stateLayoutConflict(
+        homeDir,
+        "状态路径必须是非符号链接目录",
+        targetPath,
+      );
+    }
+    return {
+      exists: true,
+      path: targetPath,
+      identity: { dev: stats.dev, ino: stats.ino },
+    };
+  } catch (error) {
+    if (error.code === "ENOENT") return { exists: false, path: targetPath };
+    throw error;
+  }
+}
+
+function sameStateDirectoryIdentity(left, right) {
+  return left?.dev === right?.dev && left?.ino === right?.ino;
+}
+
+async function inspectStateLayout(homeDir, paths = resolveStatePaths(homeDir)) {
+  const [current, legacy] = await Promise.all([
+    inspectStateDirectory(homeDir, paths.currentStateDir),
+    inspectStateDirectory(homeDir, paths.legacyStateDir),
+  ]);
+  if (current.exists && legacy.exists) {
+    const legacyEntries = await readdir(legacy.path);
+    const latestLegacy = await inspectStateDirectory(homeDir, legacy.path);
+    if (
+      legacyEntries.length === 0 &&
+      latestLegacy.exists &&
+      sameStateDirectoryIdentity(legacy.identity, latestLegacy.identity)
+    ) {
+      return {
+        kind: "current-with-empty-legacy",
+        current,
+        legacy: latestLegacy,
+        paths,
+      };
+    }
+    throw stateLayoutConflict(
+      homeDir,
+      "新旧状态目录同时存在，拒绝自动合并 ownership",
+      paths.currentStateDir,
+    );
+  }
+  return {
+    kind: current.exists ? "current" : legacy.exists ? "legacy" : "fresh",
+    current,
+    legacy,
+    paths,
+  };
+}
+
+function parseLockRecord(content) {
+  const trimmed = content.trim();
+  if (/^[1-9][0-9]*$/u.test(trimmed)) {
+    return { schemaVersion: 0, pid: Number(trimmed), owner: `legacy-${trimmed}` };
+  }
+  try {
+    const record = JSON.parse(trimmed);
+    if (
+      record.schemaVersion !== 1 ||
+      !Number.isSafeInteger(record.pid) ||
+      record.pid <= 0 ||
+      typeof record.owner !== "string" ||
+      record.owner.length < 8 ||
+      typeof record.createdAt !== "string"
+    ) {
+      return null;
+    }
+    return record;
+  } catch {
+    return null;
+  }
+}
+
+function isProcessAlive(pid) {
+  if (pid === process.pid) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error.code === "ESRCH" || error.code === "EINVAL") return false;
+    return true;
+  }
+}
+
+async function moveLockForCompare({ lockPath, expectedContent, stateDir, purpose }) {
+  const movedPath = path.join(stateDir, `${purpose}-${randomUUID()}.lock`);
+  try {
+    await rename(lockPath, movedPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+
+  const movedContent = await readFile(movedPath, "utf8");
+  if (movedContent === expectedContent) return movedPath;
+
+  try {
+    await restoreQuarantinedRemoval(lockPath, movedPath);
+  } catch (restoreError) {
+    restoreError.preserveEvidence = true;
+    throw restoreError;
+  }
+  const error = new Error(`同步锁在回收期间发生变化：${lockPath}`);
+  error.preserveEvidence = true;
+  throw error;
+}
+
+async function acquireSyncLock({
+  homeDir,
+  stateDir,
+  lockName = "sync.lock",
+  beforeLockPublish,
+}) {
+  let stateSafety = await inspectAncestorPath(homeDir, stateDir);
+  if (!stateSafety.safe) {
+    throw new SyncConflictError([
+      {
+        host: "state",
+        component: "lock",
+        assetName: "sync",
+        skillName: "sync",
+        relativePath: lockName,
+        targetPath: path.join(stateDir, lockName),
+        action: "conflict",
+        reason: `${stateSafety.reason}：${stateSafety.path}`,
+      },
+    ]);
+  }
+  await mkdir(stateDir, { recursive: true });
+  stateSafety = await inspectAncestorPath(homeDir, stateDir);
+  if (!stateSafety.safe) {
+    throw stateLayoutConflict(
+      homeDir,
+      `${stateSafety.reason}：${stateSafety.path}`,
+      stateDir,
+    );
+  }
+
+  const lockPath = path.join(stateDir, lockName);
+  const owner = randomUUID();
+  const recordContent = `${JSON.stringify({
+    schemaVersion: 1,
+    pid: process.pid,
+    owner,
+    createdAt: new Date().toISOString(),
+  })}\n`;
+  const stagedLockPath = path.join(
+    stateDir,
+    `${lockName.replaceAll(".", "-")}-${owner}.tmp`,
+  );
+  await writeFile(stagedLockPath, recordContent, { encoding: "utf8", flag: "wx" });
+  if ((await readFile(stagedLockPath, "utf8")) !== recordContent) {
+    await rm(stagedLockPath, { force: true });
+    throw new Error(`同步锁记录暂存校验失败：${stagedLockPath}`);
+  }
+
+  try {
+    await beforeLockPublish?.();
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      try {
+        await link(stagedLockPath, lockPath);
+        await rm(stagedLockPath).catch(() => {});
+        return { lockPath, recordContent, stateDir };
+      } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+
+        let existingContent;
+        try {
+          existingContent = await readFile(lockPath, "utf8");
+        } catch (readError) {
+          if (readError.code === "ENOENT") continue;
+          throw readError;
+        }
+        const existingRecord = parseLockRecord(existingContent);
+        if (!existingRecord) {
+          throw new Error(
+            `同步锁格式无法验证：${lockPath}。确认没有安装进程后再手工删除该文件。`,
+          );
+        }
+        if (isProcessAlive(existingRecord.pid)) {
+          throw new Error(
+            `已有同步进程持有锁：${lockPath}（PID ${existingRecord.pid}）`,
+          );
+        }
+
+        const stalePath = await moveLockForCompare({
+          lockPath,
+          expectedContent: existingContent,
+          stateDir,
+          purpose: "stale-sync-lock",
+        });
+        if (!stalePath) continue;
+        await rm(stalePath);
+      }
+    }
+
+    throw new Error(`无法安全获取同步锁：${lockPath}`);
+  } catch (error) {
+    await rm(stagedLockPath, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function releaseSyncLock(lock) {
+  const ownedPath = await moveLockForCompare({
+    lockPath: lock.lockPath,
+    expectedContent: lock.recordContent,
+    stateDir: lock.stateDir,
+    purpose: "released-sync-lock",
+  });
+  if (!ownedPath) {
+    const error = new Error(`同步锁在释放前已消失：${lock.lockPath}`);
+    error.preserveEvidence = true;
+    throw error;
+  }
+  await rm(ownedPath);
+}
+
+function conflictForOperation(operation, reason) {
+  return new SyncConflictError([
+    {
+      ...operation,
+      action: "conflict",
+      reason,
+    },
+  ]);
+}
+
+async function assertSafeOperationTarget(operation, homeDir) {
+  const targetParent = path.dirname(operation.targetPath);
+  const ancestor = await inspectAncestorPath(homeDir, targetParent);
+  if (!ancestor.safe) {
+    throw conflictForOperation(operation, `${ancestor.reason}：${ancestor.path}`);
+  }
+
+  const realHome = await realpath(homeDir);
+  const realParent = await realpath(targetParent);
+  const relativeParent = path.relative(realHome, realParent);
+  if (relativeParent.startsWith("..") || path.isAbsolute(relativeParent)) {
+    throw conflictForOperation(operation, `目标父目录解析到 home 之外：${realParent}`);
+  }
+}
+
+async function prepareSafeTargetParent(operation, homeDir) {
+  const targetParent = path.dirname(operation.targetPath);
+  const ancestor = await inspectAncestorPath(homeDir, targetParent);
+  if (!ancestor.safe) {
+    throw conflictForOperation(operation, `${ancestor.reason}：${ancestor.path}`);
+  }
+  await mkdir(targetParent, { recursive: true });
+  await assertSafeOperationTarget(operation, homeDir);
+}
+
+async function assertSameTransactionDevice(operation, stageRoot) {
+  const [stageStats, targetParentStats] = await Promise.all([
+    lstat(stageRoot),
+    lstat(path.dirname(operation.targetPath)),
+  ]);
+  if (stageStats.dev !== targetParentStats.dev) {
+    throw conflictForOperation(
+      operation,
+      "目标与事务 staging 不在同一文件系统；无法保证原子提交与回滚",
+    );
+  }
+}
+
+async function linkStagedFileNoOverwrite({ operation, stagedPath }) {
+  try {
+    await link(stagedPath, operation.targetPath);
+  } catch (error) {
+    if (error.code === "EEXIST") {
+      throw conflictForOperation(operation, "目标在最终提交前被创建");
+    }
+    if (error.code === "EXDEV") {
+      throw conflictForOperation(
+        operation,
+        "目标与事务 staging 不在同一文件系统；无法原子发布",
+      );
+    }
+    throw error;
+  }
+}
+
 function manifestKey(host, component, assetName, relativePath) {
   if (component === "skills") return `${host}/${assetName}/${relativePath}`;
   if (component === "agents") return `${host}/agents/${assetName}/${relativePath}`;
   return `${host}/${assetName}/${relativePath}`;
 }
 
+function resolveManagedTarget(manifestKeyValue, homeDir, stateDir) {
+  const segments = manifestKeyValue.split("/");
+  if (
+    segments.some(
+      (segment) =>
+        segment.length === 0 ||
+        segment === "." ||
+        segment === ".." ||
+        segment.includes("\\") ||
+        /[\u0000-\u001f:*?"<>|]/u.test(segment) ||
+        /[. ]$/u.test(segment),
+    )
+  ) {
+    return null;
+  }
+
+  if (
+    segments[0] === "state" &&
+    segments[1] === "notices" &&
+    segments.length === 3 &&
+    SUPPORT_FILE_NAMES.includes(segments[2])
+  ) {
+    const relativeSegments = segments.slice(2);
+    return {
+      host: "state",
+      component: "support",
+      assetName: "notices",
+      skillName: "notices",
+      relativePath: relativeSegments.join("/"),
+      targetPath: path.join(stateDir, "notices", ...relativeSegments),
+      pruneRoot: path.join(stateDir, "notices"),
+    };
+  }
+
+  if (segments[0] === "codex" && segments[1] === "agents") {
+    if (
+      segments.length !== 4 ||
+      !MANAGED_NAME_PATTERN.test(segments[2]) ||
+      segments[3] !== `${segments[2]}.toml`
+    ) {
+      return null;
+    }
+    const relativeSegments = segments.slice(3);
+    return {
+      host: "codex",
+      component: "agents",
+      assetName: segments[2],
+      skillName: segments[2],
+      relativePath: relativeSegments.join("/"),
+      targetPath: path.join(homeDir, ...CODEX_AGENT_DESTINATION, ...relativeSegments),
+      pruneRoot: path.join(homeDir, ...CODEX_AGENT_DESTINATION),
+    };
+  }
+
+  if (
+    segments[0] in HOST_DESTINATIONS &&
+    segments.length >= 3 &&
+    MANAGED_NAME_PATTERN.test(segments[1])
+  ) {
+    const relativeSegments = segments.slice(2);
+    return {
+      host: segments[0],
+      component: "skills",
+      assetName: segments[1],
+      skillName: segments[1],
+      relativePath: relativeSegments.join("/"),
+      targetPath: path.join(
+        homeDir,
+        ...HOST_DESTINATIONS[segments[0]],
+        segments[1],
+        ...relativeSegments,
+      ),
+      pruneRoot: path.join(homeDir, ...HOST_DESTINATIONS[segments[0]]),
+    };
+  }
+
+  return null;
+}
+
+function targetIdentity(targetPath) {
+  const resolved = path.resolve(targetPath);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function collectManifestTargetConflicts(manifest, homeDir, stateDir) {
+  const conflicts = [];
+  const targetOwners = new Map();
+
+  for (const key of Object.keys(manifest.files)) {
+    const target = resolveManagedTarget(key, homeDir, stateDir);
+    if (!target) {
+      conflicts.push({
+        host: "state",
+        component: "manifest",
+        assetName: key,
+        skillName: key,
+        relativePath: key,
+        targetPath: path.join(stateDir, "manifest.json"),
+        action: "conflict",
+        reason: `manifest key 非规范或不受支持：${key}`,
+        manifestKey: key,
+      });
+      continue;
+    }
+
+    const identity = targetIdentity(target.targetPath);
+    const existingKey = targetOwners.get(identity);
+    if (existingKey && existingKey !== key) {
+      conflicts.push({
+        ...target,
+        action: "conflict",
+        reason: `manifest key 目标冲突：${existingKey} 与 ${key}`,
+        manifestKey: key,
+      });
+      continue;
+    }
+    targetOwners.set(identity, key);
+  }
+
+  return conflicts;
+}
+
 async function planFileOperation({
   host,
   component,
@@ -241,12 +820,15 @@ async function planFileOperation({
   skillName = assetName,
   relativePath,
   sourcePath,
+  sourceContent = null,
   targetPath,
   manifest,
   homeDir,
 }) {
   const key = manifestKey(host, component, assetName, relativePath);
-  const sourceHash = await hashFile(sourcePath);
+  const sourceHash = sourceContent === null
+    ? await hashFile(sourcePath)
+    : sha256(Buffer.from(sourceContent, "utf8"));
   const ancestor = await inspectAncestorPath(homeDir, path.dirname(targetPath));
   const target = ancestor.safe
     ? await inspectTarget(targetPath)
@@ -282,6 +864,7 @@ async function planFileOperation({
     skillName,
     relativePath,
     sourcePath,
+    sourceContent,
     targetPath,
     sourceHash,
     targetHash: target.hash,
@@ -292,6 +875,42 @@ async function planFileOperation({
   };
 }
 
+async function planRemovalOperation({
+  manifestKeyValue,
+  previousHash,
+  target,
+  homeDir,
+}) {
+  const ancestor = await inspectAncestorPath(homeDir, path.dirname(target.targetPath));
+  const installed = ancestor.safe
+    ? await inspectTarget(target.targetPath)
+    : { exists: false, regularFile: false, hash: null };
+  let action = "remove";
+  let reason = installed.exists ? "源中已移除" : "源中和安装目录中均已不存在，仅清理记录";
+
+  if (!ancestor.safe) {
+    action = "conflict";
+    reason = `${ancestor.reason}：${ancestor.path}`;
+  } else if (installed.exists && !installed.regularFile) {
+    action = "conflict";
+    reason = "源中已移除，但目标路径不是普通文件";
+  } else if (installed.exists && installed.hash !== previousHash) {
+    action = "conflict";
+    reason = "源中已移除，但文件在上次同步后被修改";
+  }
+
+  return {
+    ...target,
+    sourcePath: null,
+    sourceHash: null,
+    targetHash: installed.hash,
+    previousHash,
+    action,
+    reason,
+    manifestKey: manifestKeyValue,
+  };
+}
+
 async function collectChangedTargetConflicts(operations, homeDir) {
   const conflicts = [];
   for (const operation of operations) {
@@ -318,28 +937,227 @@ async function collectChangedTargetConflicts(operations, homeDir) {
       (!target.regularFile || target.hash !== operation.sourceHash)
     ) {
       conflicts.push({ ...operation, action: "conflict", reason: "目标在预检后发生变化" });
+    } else if (
+      operation.action === "remove" &&
+      ((operation.targetHash === null && target.exists) ||
+        (operation.targetHash !== null &&
+          (!target.regularFile || target.hash !== operation.targetHash)))
+    ) {
+      conflicts.push({ ...operation, action: "conflict", reason: "待移除目标在预检后发生变化" });
     }
   }
   return conflicts;
 }
 
-async function applyOperationsTransactional({ operations, homeDir, manifestPath }) {
-  const stateDir = path.dirname(manifestPath);
-  await mkdir(stateDir, { recursive: true });
-  const stateSafety = await inspectAncestorPath(homeDir, stateDir);
-  if (!stateSafety.safe) {
+async function collectFinalTargetConflicts(operations, homeDir) {
+  const conflicts = [];
+  for (const operation of operations) {
+    if (operation.action === "conflict") continue;
+    const ancestor = await inspectAncestorPath(homeDir, path.dirname(operation.targetPath));
+    if (!ancestor.safe) {
+      conflicts.push({
+        ...operation,
+        action: "conflict",
+        reason: `${ancestor.reason}：${ancestor.path}`,
+      });
+      continue;
+    }
+
+    const target = await inspectTarget(operation.targetPath);
+    if (operation.action === "remove") {
+      if (target.exists) {
+        conflicts.push({
+          ...operation,
+          action: "conflict",
+          reason: "已移除目标在 manifest 提交前重新出现",
+        });
+      }
+      continue;
+    }
+    if (!target.regularFile || target.hash !== operation.sourceHash) {
+      conflicts.push({
+        ...operation,
+        action: "conflict",
+        reason: "目标在发布后、manifest 提交前发生变化",
+      });
+    }
+  }
+  return conflicts;
+}
+
+async function removeEmptyParentDirectories(startDirectory, stopDirectory) {
+  const stop = path.resolve(stopDirectory);
+  let current = path.resolve(startDirectory);
+
+  while (current !== stop) {
+    const relative = path.relative(stop, current);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+      throw new Error(`拒绝清理受管理根目录之外的目录：${current}`);
+    }
+
+    try {
+      await rmdir(current);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        current = path.dirname(current);
+        continue;
+      }
+      if (error.code === "ENOTEMPTY" || error.code === "EEXIST") return;
+      throw error;
+    }
+    current = path.dirname(current);
+  }
+}
+
+export async function restoreQuarantinedRemoval(targetPath, backupPath) {
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  try {
+    await link(backupPath, targetPath);
+  } catch (error) {
+    const restoreError = new Error(
+      `无法无覆盖地恢复隔离文件；隔离副本保留在：${backupPath}`,
+      { cause: error },
+    );
+    restoreError.preserveEvidence = true;
+    throw restoreError;
+  }
+  try {
+    await rm(backupPath);
+  } catch (error) {
+    const cleanupError = new Error(
+      `目标已恢复，但隔离副本未能清理：${backupPath}`,
+      { cause: error },
+    );
+    cleanupError.preserveEvidence = true;
+    throw cleanupError;
+  }
+}
+
+export async function quarantineManagedRemoval({
+  targetPath,
+  backupPath,
+  expectedHash,
+}) {
+  await mkdir(path.dirname(backupPath), { recursive: true });
+  try {
+    await rename(targetPath, backupPath);
+  } catch (error) {
     throw new SyncConflictError([
       {
         host: "state",
-        skillName: "manifest",
-        relativePath: "manifest.json",
-        targetPath: manifestPath,
+        component: "removal",
+        assetName: path.basename(targetPath),
+        skillName: path.basename(targetPath),
+        relativePath: path.basename(targetPath),
+        targetPath,
         action: "conflict",
-        reason: `${stateSafety.reason}：${stateSafety.path}`,
+        reason: `无法原子隔离待移除文件：${error.message}`,
+      },
+    ]);
+  }
+
+  let actualHash;
+  try {
+    actualHash = await hashFile(backupPath);
+  } catch (error) {
+    try {
+      await restoreQuarantinedRemoval(targetPath, backupPath);
+    } catch (restoreError) {
+      restoreError.cause = error;
+      throw restoreError;
+    }
+    throw error;
+  }
+
+  if (actualHash !== expectedHash) {
+    try {
+      await restoreQuarantinedRemoval(targetPath, backupPath);
+    } catch (restoreError) {
+      const conflict = new SyncConflictError([
+        {
+          host: "state",
+          component: "removal",
+          assetName: path.basename(targetPath),
+          skillName: path.basename(targetPath),
+          relativePath: path.basename(targetPath),
+          targetPath,
+          action: "conflict",
+          reason: `待移除文件已变化且无法安全恢复；隔离副本保留在 ${backupPath}`,
+        },
+      ]);
+      conflict.cause = restoreError;
+      conflict.preserveEvidence = true;
+      throw conflict;
+    }
+    throw new SyncConflictError([
+      {
+        host: "state",
+        component: "removal",
+        assetName: path.basename(targetPath),
+        skillName: path.basename(targetPath),
+        relativePath: path.basename(targetPath),
+        targetPath,
+        action: "conflict",
+        reason: "待移除目标在最终原子隔离时发生变化",
       },
     ]);
   }
 
+  return { backupPath, actualHash };
+}
+
+async function rollbackAppliedOperation({ entry, stageRoot, homeDir }) {
+  const { operation, backupPath, published } = entry;
+  await prepareSafeTargetParent(operation, homeDir);
+  await assertSameTransactionDevice(operation, stageRoot);
+
+  let publishedBackupPath = null;
+  const target = await inspectTarget(operation.targetPath);
+  if (published && target.exists) {
+    if (!target.regularFile || target.hash !== operation.sourceHash) {
+      const error = new Error(
+        `回滚拒绝覆盖事务期间变化的目标：${operation.targetPath}`,
+      );
+      error.preserveEvidence = true;
+      throw error;
+    }
+    publishedBackupPath = path.join(
+      stageRoot,
+      "rollback-current",
+      ...operation.manifestKey.split("/"),
+    );
+    try {
+      await quarantineManagedRemoval({
+        targetPath: operation.targetPath,
+        backupPath: publishedBackupPath,
+        expectedHash: operation.sourceHash,
+      });
+    } catch (error) {
+      error.preserveEvidence = true;
+      throw error;
+    }
+  }
+
+  if (operation.action === "create") {
+    if (publishedBackupPath) await rm(publishedBackupPath);
+    return;
+  }
+
+  if (backupPath) {
+    await restoreQuarantinedRemoval(operation.targetPath, backupPath);
+  }
+  if (publishedBackupPath) await rm(publishedBackupPath);
+}
+
+async function applyOperationsTransactional({
+  operations,
+  homeDir,
+  manifestPath,
+  expectedManifestHash,
+  transactionHooks = {},
+}) {
+  await assertSafeHomeRoot(homeDir);
+  const stateDir = path.dirname(manifestPath);
   const stagingDir = path.join(stateDir, "staging");
   const stagingSafety = await inspectAncestorPath(homeDir, stagingDir);
   if (!stagingSafety.safe) {
@@ -355,29 +1173,10 @@ async function applyOperationsTransactional({ operations, homeDir, manifestPath
     ]);
   }
 
-  const lockPath = path.join(stateDir, "sync.lock");
-  let lockHandle;
-  try {
-    lockHandle = await open(lockPath, "wx");
-  } catch (error) {
-    if (error.code === "EEXIST") throw new Error(`已有同步进程持有锁：${lockPath}`);
-    throw error;
-  }
-  try {
-    await lockHandle.writeFile(`${process.pid}\n`, "utf8");
-  } catch (error) {
-    await lockHandle.close();
-    await rm(lockPath, { force: true });
-    throw error;
-  }
-
-  const stageRoot = path.join(stateDir, "staging", randomUUID());
+  const stageRoot = path.join(stagingDir, randomUUID());
   const stagedPaths = new Map();
   const applied = [];
   const rollbackErrors = [];
-  let manifestBackupPath = null;
-  let manifestExisted = false;
-  let manifestChanged = false;
   let preserveStage = false;
 
   try {
@@ -408,90 +1207,205 @@ async function applyOperationsTransactional({ operations, homeDir, manifestPath
       if (operation.action !== "create" && operation.action !== "update") continue;
       const stagedPath = path.join(stageRoot, "next", ...operation.manifestKey.split("/"));
       await mkdir(path.dirname(stagedPath), { recursive: true });
-      await copyFile(operation.sourcePath, stagedPath);
+      if (operation.sourceContent === null) {
+        await copyFile(operation.sourcePath, stagedPath);
+      } else {
+        await writeFile(stagedPath, operation.sourceContent, "utf8");
+      }
       if ((await hashFile(stagedPath)) !== operation.sourceHash) {
         throw new Error(`暂存文件校验失败：${operation.sourcePath}`);
       }
       stagedPaths.set(operation.manifestKey, stagedPath);
     }
 
-    const lockedManifest = await readManifest(manifestPath);
     const manifestTarget = await inspectTarget(manifestPath);
     if (manifestTarget.exists && !manifestTarget.regularFile) {
       throw new Error(`同步 manifest 不是普通文件：${manifestPath}`);
     }
-    if (manifestTarget.exists) {
-      manifestExisted = true;
-      manifestBackupPath = path.join(stageRoot, "backups", "manifest.json");
-      await mkdir(path.dirname(manifestBackupPath), { recursive: true });
-      await copyFile(manifestPath, manifestBackupPath);
+    if (manifestTarget.hash !== expectedManifestHash) {
+      throw conflictForOperation(
+        {
+          host: "state",
+          component: "manifest",
+          assetName: "manifest",
+          skillName: "manifest",
+          relativePath: "manifest.json",
+          targetPath: manifestPath,
+        },
+        "同步 manifest 在规划后发生变化",
+      );
+    }
+    const lockedManifest = await readManifest(manifestPath);
+    const lockedManifestConflicts = collectManifestTargetConflicts(
+      lockedManifest,
+      homeDir,
+      stateDir,
+    );
+    if (lockedManifestConflicts.length > 0) {
+      throw new SyncConflictError(lockedManifestConflicts);
     }
 
     const changedTargetConflicts = await collectChangedTargetConflicts(operations, homeDir);
     if (changedTargetConflicts.length > 0) throw new SyncConflictError(changedTargetConflicts);
 
     for (const operation of operations) {
-      if (operation.action !== "create" && operation.action !== "update") continue;
+      if (!["create", "update", "remove"].includes(operation.action)) continue;
+      if (operation.action === "remove" && operation.targetHash === null) continue;
+
+      await prepareSafeTargetParent(operation, homeDir);
+      await transactionHooks.beforeOperationCommit?.(operation);
+      await assertSafeOperationTarget(operation, homeDir);
+      await assertSameTransactionDevice(operation, stageRoot);
+
       let backupPath = null;
-      if (operation.action === "update") {
+      let entry = null;
+      if (operation.action === "update" || operation.action === "remove") {
         backupPath = path.join(stageRoot, "backups", ...operation.manifestKey.split("/"));
-        await mkdir(path.dirname(backupPath), { recursive: true });
-        await copyFile(operation.targetPath, backupPath);
-        if ((await hashFile(backupPath)) !== operation.targetHash) {
-          throw new Error(`目标备份校验失败：${operation.targetPath}`);
-        }
+        await quarantineManagedRemoval({
+          targetPath: operation.targetPath,
+          backupPath,
+          expectedHash: operation.targetHash,
+        });
+        entry = { operation, backupPath, published: false };
+        applied.push(entry);
+        await transactionHooks.afterOperationQuarantine?.(operation);
       }
+      if (operation.action === "remove") continue;
 
-      applied.push({ operation, backupPath });
-      await mkdir(path.dirname(operation.targetPath), { recursive: true });
-      await copyFile(stagedPaths.get(operation.manifestKey), operation.targetPath);
+      await assertSafeOperationTarget(operation, homeDir);
+      await assertSameTransactionDevice(operation, stageRoot);
+      await linkStagedFileNoOverwrite({
+        operation,
+        stagedPath: stagedPaths.get(operation.manifestKey),
+      });
+      if (!entry) {
+        entry = { operation, backupPath: null, published: true };
+        applied.push(entry);
+      } else {
+        entry.published = true;
+      }
       if ((await hashFile(operation.targetPath)) !== operation.sourceHash) {
         throw new Error(`同步后校验失败：${operation.targetPath}`);
       }
+      await transactionHooks.afterOperationPublish?.(operation);
     }
 
     const nextFiles = { ...lockedManifest.files };
-    for (const operation of operations) nextFiles[operation.manifestKey] = operation.sourceHash;
+    for (const operation of operations) {
+      if (operation.action === "remove") {
+        delete nextFiles[operation.manifestKey];
+      } else {
+        nextFiles[operation.manifestKey] = operation.sourceHash;
+      }
+    }
     const nextManifest = {
       schemaVersion: 1,
       managedBy: "netpilot-skills",
       updatedAt: new Date().toISOString(),
-      files: Object.fromEntries(Object.entries(nextFiles).sort(([left], [right]) => left.localeCompare(right))),
+      files: Object.fromEntries(
+        Object.entries(nextFiles).sort(([left], [right]) => left.localeCompare(right)),
+      ),
     };
     const stagedManifestPath = path.join(stageRoot, "next-manifest.json");
-    await mkdir(path.dirname(stagedManifestPath), { recursive: true });
     await writeFile(stagedManifestPath, `${JSON.stringify(nextManifest, null, 2)}\n`, "utf8");
     JSON.parse(await readFile(stagedManifestPath, "utf8"));
-    manifestChanged = true;
-    await copyFile(stagedManifestPath, manifestPath);
+    const manifestOperation = {
+      host: "state",
+      component: "manifest",
+      assetName: "manifest",
+      skillName: "manifest",
+      relativePath: "manifest.json",
+      targetPath: manifestPath,
+      manifestKey: "state/manifest.json",
+      targetHash: manifestTarget.hash,
+      sourceHash: await hashFile(stagedManifestPath),
+      action: manifestTarget.exists ? "update" : "create",
+    };
+    await prepareSafeTargetParent(manifestOperation, homeDir);
+    await transactionHooks.beforeOperationCommit?.(manifestOperation);
+    await assertSafeOperationTarget(manifestOperation, homeDir);
+    await assertSameTransactionDevice(manifestOperation, stageRoot);
+    const finalTargetConflicts = await collectFinalTargetConflicts(operations, homeDir);
+    if (finalTargetConflicts.length > 0) {
+      throw new SyncConflictError(finalTargetConflicts);
+    }
+
+    let manifestEntry;
+    if (manifestOperation.action === "update") {
+      const manifestBackupPath = path.join(stageRoot, "backups", "manifest.json");
+      await quarantineManagedRemoval({
+        targetPath: manifestPath,
+        backupPath: manifestBackupPath,
+        expectedHash: manifestOperation.targetHash,
+      });
+      manifestEntry = {
+        operation: manifestOperation,
+        backupPath: manifestBackupPath,
+        published: false,
+      };
+      applied.push(manifestEntry);
+      await transactionHooks.afterOperationQuarantine?.(manifestOperation);
+    }
+    await assertSafeOperationTarget(manifestOperation, homeDir);
+    await assertSameTransactionDevice(manifestOperation, stageRoot);
+    await linkStagedFileNoOverwrite({
+      operation: manifestOperation,
+      stagedPath: stagedManifestPath,
+    });
+    if (!manifestEntry) {
+      manifestEntry = {
+        operation: manifestOperation,
+        backupPath: null,
+        published: true,
+      };
+      applied.push(manifestEntry);
+    } else {
+      manifestEntry.published = true;
+    }
+    if ((await hashFile(manifestPath)) !== manifestOperation.sourceHash) {
+      throw new Error(`同步后校验失败：${manifestPath}`);
+    }
     JSON.parse(await readFile(manifestPath, "utf8"));
-  } catch (error) {
-    for (const { operation, backupPath } of [...applied].reverse()) {
-      try {
-        if (backupPath) {
-          await copyFile(backupPath, operation.targetPath);
-        } else {
-          await rm(operation.targetPath, { force: true });
-        }
-      } catch (rollbackError) {
-        rollbackErrors.push(`${operation.targetPath}: ${rollbackError.message}`);
-      }
+    await transactionHooks.afterOperationPublish?.(manifestOperation);
+    const postManifestTargetConflicts = await collectFinalTargetConflicts(operations, homeDir);
+    if (postManifestTargetConflicts.length > 0) {
+      throw new SyncConflictError(postManifestTargetConflicts);
+    }
+    const committedManifest = await inspectTarget(manifestPath);
+    if (
+      !committedManifest.regularFile ||
+      committedManifest.hash !== manifestOperation.sourceHash
+    ) {
+      throw conflictForOperation(
+        manifestOperation,
+        "manifest 在最终提交后发生变化",
+      );
     }
 
-    if (manifestChanged) {
+    for (const operation of operations) {
+      if (
+        operation.action === "remove" &&
+        operation.targetHash !== null &&
+        operation.pruneRoot
+      ) {
+        await removeEmptyParentDirectories(
+          path.dirname(operation.targetPath),
+          operation.pruneRoot,
+        );
+      }
+    }
+  } catch (error) {
+    if (error.preserveEvidence) preserveStage = true;
+    for (const entry of [...applied].reverse()) {
       try {
-        if (manifestExisted) {
-          await copyFile(manifestBackupPath, manifestPath);
-        } else {
-          await rm(manifestPath, { force: true });
-        }
+        await rollbackAppliedOperation({ entry, stageRoot, homeDir });
       } catch (rollbackError) {
-        rollbackErrors.push(`${manifestPath}: ${rollbackError.message}`);
+        preserveStage = true;
+        rollbackErrors.push(`${entry.operation.targetPath}: ${rollbackError.message}`);
       }
     }
 
     if (rollbackErrors.length > 0) {
-      preserveStage = true;
       throw new Error(
         `同步失败且回滚不完整；暂存保留在 ${stageRoot}\n${rollbackErrors.join("\n")}`,
         { cause: error },
@@ -499,24 +1413,125 @@ async function applyOperationsTransactional({ operations, homeDir, manifestPath
     }
     throw error;
   } finally {
+    if (!preserveStage) await rm(stageRoot, { recursive: true, force: true });
+  }
+}
+
+async function migrateLegacyState({
+  homeDir,
+  paths,
+  transactionHooks,
+}) {
+  let syncLock = await acquireSyncLock({
+    homeDir,
+    stateDir: paths.legacyStateDir,
+    beforeLockPublish: transactionHooks.beforeLockPublish,
+  });
+  let moved = false;
+  try {
+    const freshLayout = await inspectStateLayout(homeDir, paths);
+    if (freshLayout.kind !== "legacy") {
+      throw stateLayoutConflict(
+        homeDir,
+        "获取旧状态锁后布局发生变化，拒绝继续迁移",
+        paths.legacyStateDir,
+      );
+    }
+    const lockedSourceIdentity = freshLayout.legacy.identity;
+    const legacyManifest = await inspectTarget(paths.legacyManifestPath);
+    if (!legacyManifest.exists || !legacyManifest.regularFile) {
+      throw stateLayoutConflict(
+        homeDir,
+        "旧状态目录缺少可信的普通 manifest.json",
+        paths.legacyManifestPath,
+      );
+    }
+    await readManifest(paths.legacyManifestPath);
+    await transactionHooks.beforeStateMigrationRename?.();
+    const beforeRename = await inspectStateLayout(homeDir, paths);
+    if (
+      beforeRename.kind !== "legacy" ||
+      !sameStateDirectoryIdentity(
+        lockedSourceIdentity,
+        beforeRename.legacy.identity,
+      )
+    ) {
+      throw stateLayoutConflict(
+        homeDir,
+        "旧状态目录身份在迁移提交前发生变化",
+        paths.currentStateDir,
+      );
+    }
+    try {
+      await rename(paths.legacyStateDir, paths.currentStateDir);
+    } catch (error) {
+      if (error.code === "EXDEV") {
+        throw stateLayoutConflict(
+          homeDir,
+          "新旧状态目录不在同一文件系统，拒绝退化为非原子复制",
+          paths.currentStateDir,
+        );
+      }
+      if (["EEXIST", "ENOTEMPTY"].includes(error.code)) {
+        throw stateLayoutConflict(
+          homeDir,
+          "新状态目录在原子迁移前已出现",
+          paths.currentStateDir,
+        );
+      }
+      throw error;
+    }
+    moved = true;
+    syncLock = {
+      ...syncLock,
+      stateDir: paths.currentStateDir,
+      lockPath: path.join(paths.currentStateDir, "sync.lock"),
+    };
+    const migratedLayout = await inspectStateLayout(homeDir, paths);
+    if (
+      migratedLayout.kind !== "current" ||
+      !sameStateDirectoryIdentity(
+        lockedSourceIdentity,
+        migratedLayout.current.identity,
+      )
+    ) {
+      const error = new Error("状态目录迁移后的目标身份不一致");
+      error.preserveEvidence = true;
+      throw error;
+    }
+    const migratedManifest = await inspectTarget(paths.currentManifestPath);
+    if (
+      !migratedManifest.regularFile ||
+      migratedManifest.hash !== legacyManifest.hash
+    ) {
+      const error = new Error("状态目录迁移后 manifest digest 不一致");
+      error.preserveEvidence = true;
+      throw error;
+    }
+    await transactionHooks.afterStateMigrationRename?.();
+    return syncLock;
+  } catch (error) {
     try {
-      await lockHandle.close();
-    } finally {
-      await rm(lockPath, { force: true });
+      await releaseSyncLock(syncLock);
+    } catch (releaseError) {
+      error.releaseError = releaseError;
+      error.preserveEvidence = true;
     }
-    if (!preserveStage) await rm(stageRoot, { recursive: true, force: true });
+    if (moved) error.stateMigrationCommitted = true;
+    throw error;
   }
 }
 
 export async function syncSkills({
   rootDir,
   homeDir,
-  hosts = [...ALL_HOSTS],
-  components = ["skills"],
+  hosts = ["codex"],
+  components = [...ALL_COMPONENTS],
   apply = false,
+  transactionHooks = {},
 }) {
   const selectedHosts = [...new Set(hosts)];
-  const selectedComponents = [...new Set(components)];
+  const selectedComponents = [...new Set(components.map(canonicalComponent))];
   for (const host of selectedHosts) {
     if (!(host in HOST_DESTINATIONS)) throw new Error(`不支持的宿主：${host}`);
   }
@@ -525,15 +1540,123 @@ export async function syncSkills({
   }
   if (
     selectedComponents.includes("agents") &&
-    (selectedHosts.length !== 1 || selectedHosts[0] !== "codex")
+    !selectedHosts.includes("codex")
   ) {
-    throw new Error("Codex agents 组件只支持显式选择 --host codex");
+    throw new Error("Codex agents 组件要求 --host 包含 codex");
   }
 
   const resolvedRoot = path.resolve(rootDir);
   const resolvedHome = path.resolve(homeDir);
-  const manifestPath = path.join(resolvedHome, ".netpilot-skills", "manifest.json");
-  const stateDir = path.dirname(manifestPath);
+  await assertSafeHomeRoot(resolvedHome);
+  const statePaths = resolveStatePaths(resolvedHome);
+  let stateLayout = await inspectStateLayout(resolvedHome, statePaths);
+  let stateDir =
+    stateLayout.kind === "legacy"
+      ? statePaths.legacyStateDir
+      : statePaths.currentStateDir;
+  let manifestPath =
+    stateLayout.kind === "legacy"
+      ? statePaths.legacyManifestPath
+      : statePaths.currentManifestPath;
+  let stateMigration =
+    stateLayout.kind === "legacy"
+      ? {
+          action: "move",
+          from: statePaths.legacyStateDir,
+          to: statePaths.currentStateDir,
+        }
+      : null;
+  let stateRepair =
+    stateLayout.kind === "current-with-empty-legacy"
+      ? {
+          action: "remove-empty-legacy-state",
+          target: statePaths.legacyStateDir,
+        }
+      : null;
+  let layoutLock = null;
+  let syncLock = null;
+  let syncError = null;
+
+  try {
+    if (apply) {
+      layoutLock = await acquireSyncLock({
+        homeDir: resolvedHome,
+        stateDir: statePaths.layoutLockDir,
+        lockName: LAYOUT_LOCK_NAME,
+        beforeLockPublish: transactionHooks.beforeLayoutLockPublish,
+      });
+      stateLayout = await inspectStateLayout(resolvedHome, statePaths);
+      if (stateLayout.kind === "current-with-empty-legacy") {
+        stateRepair = {
+          action: "remove-empty-legacy-state",
+          target: statePaths.legacyStateDir,
+        };
+        const expectedCurrentIdentity = stateLayout.current.identity;
+        try {
+          await rmdir(statePaths.legacyStateDir);
+        } catch (error) {
+          if (["ENOTEMPTY", "EEXIST"].includes(error.code)) {
+            throw stateLayoutConflict(
+              resolvedHome,
+              "空旧状态目录在清理前出现内容，拒绝继续",
+              statePaths.legacyStateDir,
+            );
+          }
+          throw error;
+        }
+        const repairedLayout = await inspectStateLayout(
+          resolvedHome,
+          statePaths,
+        );
+        if (
+          repairedLayout.kind !== "current" ||
+          !sameStateDirectoryIdentity(
+            expectedCurrentIdentity,
+            repairedLayout.current.identity,
+          )
+        ) {
+          throw stateLayoutConflict(
+            resolvedHome,
+            "清理旧状态残留后当前状态目录身份发生变化",
+            statePaths.currentStateDir,
+          );
+        }
+        stateLayout = repairedLayout;
+      }
+      if (stateLayout.kind === "legacy") {
+        stateMigration = {
+          action: "move",
+          from: statePaths.legacyStateDir,
+          to: statePaths.currentStateDir,
+        };
+        syncLock = await migrateLegacyState({
+          homeDir: resolvedHome,
+          paths: statePaths,
+          transactionHooks,
+        });
+      } else {
+        syncLock = await acquireSyncLock({
+          homeDir: resolvedHome,
+          stateDir: statePaths.currentStateDir,
+          beforeLockPublish: transactionHooks.beforeLockPublish,
+        });
+      }
+      const lockedLayout = await inspectStateLayout(
+        resolvedHome,
+        statePaths,
+      );
+      if (lockedLayout.kind !== "current") {
+        throw stateLayoutConflict(
+          resolvedHome,
+          "获取同步锁后项目状态布局发生变化，拒绝继续",
+          statePaths.currentStateDir,
+        );
+      }
+      stateLayout = lockedLayout;
+      stateDir = statePaths.currentStateDir;
+      manifestPath = statePaths.currentManifestPath;
+    }
+    if (syncLock) await transactionHooks.afterLockAcquired?.();
   const stateSafety = await inspectAncestorPath(resolvedHome, stateDir);
   if (!stateSafety.safe) {
     throw new SyncConflictError([
@@ -561,6 +1684,12 @@ export async function syncSkills({
     ]);
   }
   const manifest = await readManifest(manifestPath);
+  const manifestConflicts = collectManifestTargetConflicts(
+    manifest,
+    resolvedHome,
+    stateDir,
+  );
+  if (manifestConflicts.length > 0) throw new SyncConflictError(manifestConflicts);
   const sourceFiles = selectedComponents.includes("skills")
     ? await discoverSourceFiles(resolvedRoot)
     : [];
@@ -581,6 +1710,10 @@ export async function syncSkills({
       const hostRoot = path.join(resolvedHome, ...HOST_DESTINATIONS[host]);
       for (const source of sourceFiles) {
         const targetPath = path.join(hostRoot, source.skillName, ...source.relativePath.split("/"));
+        const sourceContent =
+          host === "codex" && source.relativePath === "SKILL.md"
+            ? projectCodexSkill(await readFile(source.absolutePath, "utf8"))
+            : null;
         operations.push(await planFileOperation({
           host,
           component: "skills",
@@ -588,6 +1721,7 @@ export async function syncSkills({
           skillName: source.skillName,
           relativePath: source.relativePath,
           sourcePath: source.absolutePath,
+          sourceContent,
           targetPath,
           manifest,
           homeDir: resolvedHome,
@@ -627,46 +1761,114 @@ export async function syncSkills({
     }));
   }
 
+  const desiredManifestKeys = new Set(operations.map((operation) => operation.manifestKey));
+  for (const [key, previousHash] of Object.entries(manifest.files)) {
+    if (desiredManifestKeys.has(key)) continue;
+    const target = resolveManagedTarget(key, resolvedHome, stateDir);
+    if (!target) continue;
+    const selected =
+      target.component === "support" ||
+      (target.component === "skills" &&
+        selectedComponents.includes("skills") &&
+        selectedHosts.includes(target.host)) ||
+      (target.component === "agents" &&
+        selectedComponents.includes("agents") &&
+        selectedHosts.includes("codex"));
+    if (!selected) continue;
+    operations.push(await planRemovalOperation({
+      manifestKeyValue: key,
+      previousHash,
+      target,
+      homeDir: resolvedHome,
+    }));
+  }
+
   const conflicts = operations.filter((operation) => operation.action === "conflict");
   const result = {
     mode: apply ? "apply" : "dry-run",
     homeDir: resolvedHome,
-    manifestPath,
+    manifestPath: statePaths.currentManifestPath,
+    ...(manifestPath !== statePaths.currentManifestPath
+      ? { sourceManifestPath: manifestPath }
+      : {}),
+    ...(stateMigration ? { stateMigration } : {}),
+    ...(stateRepair ? { stateRepair } : {}),
     operations,
     conflicts,
   };
 
   if (!apply) return result;
   if (conflicts.length > 0) throw new SyncConflictError(conflicts);
-  await applyOperationsTransactional({ operations, homeDir: resolvedHome, manifestPath });
+  await applyOperationsTransactional({
+    operations,
+    homeDir: resolvedHome,
+    manifestPath,
+    expectedManifestHash: manifestTarget.hash,
+    transactionHooks,
+  });
 
   return result;
+  } catch (error) {
+    syncError = error;
+    throw error;
+  } finally {
+    let releaseFailure = null;
+    for (const lock of [syncLock, layoutLock]) {
+      if (!lock) continue;
+      try {
+        await releaseSyncLock(lock);
+      } catch (releaseError) {
+        if (syncError) {
+          syncError.releaseError = releaseError;
+          syncError.preserveEvidence = true;
+        } else {
+          releaseFailure ??= releaseError;
+        }
+      }
+    }
+    if (!syncError && releaseFailure) throw releaseFailure;
+  }
 }
 
 function printHelp() {
   console.log(`用法：
-  netpilot-skills install [--host codex|claude|all] [--component skills|agents|all] [--home PATH] [--apply]
-  npm run sync -- [--host codex|claude|all] [--component skills|agents|all] [--home PATH] [--apply]
+  netpilot-skills sync [--host codex|claude|all] [--component skills|system-agents|agents|all] [--home PATH] [--apply|--dry-run]
+  npm run sync -- [--host codex|claude|all] [--component skills|system-agents|agents|all] [--home PATH] [--apply|--dry-run]
 
-默认执行 dry-run，只展示计划。只有传入 --apply 才会写入用户级目录。
-Codex 目标：~/.agents/skills
-Claude Code 目标：~/.claude/skills
-Codex agents 目标：~/.codex/agents（必须显式选择 --component agents 或 all）`);
+底层 sync 默认执行 dry-run，只展示计划。只有传入 --apply 才会写入用户级目录。
+默认目标：Codex skills 与 agents。
+Codex Skills 目标：~/.agents/skills
+Codex 系统级（用户全局）Agents 目标：~/.codex/agents
+system-agents 是 agents 的语义化别名，二者安装内容与 manifest 所有权相同。
+Claude Code 目标：~/.claude/skills（选择 --host claude 时默认只安装 skills）。
+选择 --host all 时，Skills 同步到 Codex 与 Claude，Agents 只同步到 Codex。`);
 }
 
 function printPlan(result) {
+  if (result.stateRepair) {
+    console.log(
+      `[remove-empty] state ${result.stateRepair.target}`,
+    );
+  }
+  if (result.stateMigration) {
+    console.log(
+      `[move] state ${result.stateMigration.from} -> ${result.stateMigration.to}`,
+    );
+  }
   for (const operation of result.operations) {
     const reason = operation.reason ? `（${operation.reason}）` : "";
     const component = operation.component === "skills" ? "skills" : operation.component;
     console.log(`[${operation.action}] ${operation.host} ${component} ${operation.assetName}/${operation.relativePath}${reason}`);
   }
   const counts = Object.fromEntries(
-    ["create", "update", "unchanged", "conflict"].map((action) => [
+    ["create", "update", "remove", "unchanged", "conflict"].map((action) => [
       action,
       result.operations.filter((operation) => operation.action === action).length,
     ]),
   );
-  console.log(`汇总：新增 ${counts.create}，更新 ${counts.update}，不变 ${counts.unchanged}，冲突 ${counts.conflict}`);
+  console.log(
+    `汇总：新增 ${counts.create}，更新 ${counts.update}，移除 ${counts.remove}，不变 ${counts.unchanged}，冲突 ${counts.conflict}`,
+  );
   if (result.mode === "dry-run") console.log("当前为 dry-run；确认计划后追加 --apply。 ");
 }
 
@@ -675,9 +1877,9 @@ async function main() {
     printHelp();
     return;
   }
-  const options = parseArgs(process.argv.slice(2));
-  const rootDir = fileURLToPath(new URL("..", import.meta.url));
   try {
+    const options = parseArgs(process.argv.slice(2));
+    const rootDir = fileURLToPath(new URL("..", import.meta.url));
     const result = await syncSkills({ rootDir, ...options });
     printPlan(result);
     if (result.conflicts.length > 0) process.exitCode = 2;
@@ -690,7 +1892,8 @@ async function main() {
       process.exitCode = 2;
       return;
     }
-    throw error;
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
   }
 }