abelworkflow 1.1.3 → 1.2.0

package/lib/installer/links.mjs

@@ -3,7 +3,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
 import { backupIfNeeded, pathExists, pathTargetExists } from "../config/store.mjs";
 import { containsPath, isWindows } from "../paths.mjs";
 import { hashBytes } from "../utils.mjs";
-import { ensureManagedContainerDirectory } from "./assets.mjs";
+import { ensureManagedContainerDirectories } from "./assets.mjs";
 
 async function createManagedTargetState(targetPath, sourcePath, kind, mode, status) {
   let targetHash;
@@ -17,6 +17,11 @@ async function createSymlink(targetPath, sourcePath, linkType) {
   await fs.symlink(sourcePath, targetPath, linkType);
 }
 
+function recordLinkResult(results, options, result) {
+  results.push(result);
+  options.onResult?.(result);
+}
+
 async function symlinkPointsTo(targetPath, sourcePath) {
   try {
     if (!(await fs.lstat(targetPath)).isSymbolicLink()) return false;
@@ -34,14 +39,6 @@ function previousStateOwnsSource(previousState, sourcePath, kind) {
     && previousState.kind === kind;
 }
 
-function isUnverifiedWindowsCopy(previousState, kind) {
-  return isWindows()
-    && kind === "file"
-    && previousState?.kind === "file"
-    && previousState.mode === "copy"
-    && !previousState.targetHash;
-}
-
 async function targetMatchesPreviousState(targetPath, previousState) {
   if (!previousState || !(await pathExists(targetPath))) return false;
   const targetStat = await fs.lstat(targetPath);
@@ -84,24 +81,40 @@ async function ordinaryFileMatchesSource(targetPath, sourcePath, kind) {
   }
 }
 
-async function moveReplaceableTarget(targetPath) {
+async function moveReplaceableTarget(targetPath, options) {
   const targetStat = await fs.lstat(targetPath);
   if (targetStat.isDirectory() && !targetStat.isSymbolicLink()) return false;
+  await options.beforeMutation?.();
   await backupIfNeeded(targetPath);
   return true;
 }
 
+async function removeRecordedTarget(targetPath, previousState, options = {}) {
+  if (!(await pathExists(targetPath))) return { targetPath, status: "removed" };
+  const matchesPrevious = await targetMatchesPreviousState(targetPath, previousState);
+  if (matchesPrevious) {
+    await options.beforeMutation?.();
+    await fs.rm(targetPath, { recursive: true, force: true });
+    return { targetPath, status: "removed" };
+  }
+  if (options.force && await moveReplaceableTarget(targetPath, options)) {
+    return { targetPath, status: "removed" };
+  }
+  return { targetPath, status: "conflict" };
+}
+
 async function ensureManagedLink(targetPath, sourcePath, kind, previousLinkedTargets = {}, options = {}) {
   const force = options.force ?? false;
+  if (!(await pathExists(dirname(targetPath)))) await options.beforeMutation?.();
   await fs.mkdir(dirname(targetPath), { recursive: true });
   const sourceExists = await pathTargetExists(sourcePath);
   const targetExists = await pathExists(targetPath);
   const previousState = previousLinkedTargets[targetPath];
   const wasPreviouslyManaged = previousStateOwnsSource(previousState, sourcePath, kind);
-  const isUnverifiedCopy = wasPreviouslyManaged && isUnverifiedWindowsCopy(previousState, kind);
 
   if (targetExists && await symlinkPointsTo(targetPath, sourcePath)) {
     if (!sourceExists) {
+      await options.beforeMutation?.();
       await fs.rm(targetPath, { recursive: true, force: true });
       return { targetPath, status: "removed" };
     }
@@ -111,12 +124,12 @@ async function ensureManagedLink(targetPath, sourcePath, kind, previousLinkedTar
   if (!sourceExists) {
     if (!targetExists) return { targetPath, status: "removed" };
     if (!wasPreviouslyManaged) return { targetPath, status: "skipped" };
-    if (isUnverifiedCopy) return { targetPath, status: "conflict" };
     if (await targetMatchesPreviousState(targetPath, previousState)) {
+      await options.beforeMutation?.();
       await fs.rm(targetPath, { recursive: true, force: true });
       return { targetPath, status: "removed" };
     }
-    if (force && await moveReplaceableTarget(targetPath)) return { targetPath, status: "removed" };
+    if (force && await moveReplaceableTarget(targetPath, options)) return { targetPath, status: "removed" };
     return { targetPath, status: "conflict" };
   }
 
@@ -125,23 +138,18 @@ async function ensureManagedLink(targetPath, sourcePath, kind, previousLinkedTar
   }
 
   if (targetExists) {
-    if (isUnverifiedCopy) {
-      if (await ordinaryFileMatchesSource(targetPath, sourcePath, kind)) {
-        return createManagedTargetState(targetPath, sourcePath, kind, "copy", "unchanged");
-      }
-      return { targetPath, status: "conflict" };
-    }
     const matchesPrevious = wasPreviouslyManaged && await targetMatchesPreviousState(targetPath, previousState);
     if (matchesPrevious && await ordinaryFileMatchesSource(targetPath, sourcePath, kind)) {
       return createManagedTargetState(targetPath, sourcePath, kind, previousState.mode, "unchanged");
     }
-    if ((!matchesPrevious && !force) || !(await moveReplaceableTarget(targetPath))) {
+    if ((!matchesPrevious && !force) || !(await moveReplaceableTarget(targetPath, options))) {
       return { targetPath, status: "conflict" };
     }
   }
 
   const linkType = isWindows() ? (kind === "dir" ? "junction" : "file") : kind;
   try {
+    await options.beforeMutation?.();
     await createSymlink(targetPath, sourcePath, linkType);
     return createManagedTargetState(targetPath, sourcePath, kind, "symlink", "linked");
   } catch (error) {
@@ -185,7 +193,8 @@ async function pathIsFile(path) {
   }
 }
 
-async function ensureProviderRootDirectory(homeDir, ...segments) {
+async function ensureProviderRootDirectory(homeDir, segments, options = {}) {
+  if (!(await pathExists(homeDir))) await options.beforeMutation?.();
   await fs.mkdir(homeDir, { recursive: true });
   let directory = homeDir;
   for (const segment of segments) {
@@ -196,13 +205,20 @@ async function ensureProviderRootDirectory(homeDir, ...segments) {
     } catch (error) {
       if (error?.code !== "ENOENT") throw error;
       try {
+        await options.beforeMutation?.();
         await fs.mkdir(directory);
       } catch (mkdirError) {
         if (mkdirError?.code === "EEXIST") {
+          const concurrentTarget = await fs.lstat(directory);
+          if (!concurrentTarget.isSymbolicLink() && concurrentTarget.isDirectory()) continue;
           throw new Error(`Provider root conflict at ${directory}`, { cause: mkdirError });
         }
         throw mkdirError;
       }
+      const createdTarget = await fs.lstat(directory);
+      if (createdTarget.isSymbolicLink() || !createdTarget.isDirectory()) {
+        throw new Error(`Provider root conflict at ${directory}`);
+      }
       continue;
     }
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
@@ -257,37 +273,18 @@ function isWithinManagedRoot(targetPath, managedSourceRoot, pathOps = { isAbsolu
 async function pruneManagedTargets(targetDir, managedSourceRoot, expectedNames, previousLinkedTargets, options = {}) {
   const resolvedTargetDir = resolve(targetDir);
   const expectedNameSet = new Set(expectedNames);
-  const results = [];
+  const candidates = [];
   for (const [targetPath, previousState] of Object.entries(previousLinkedTargets)) {
     const resolvedTargetPath = resolve(targetPath);
     if (targetPath !== resolvedTargetPath || dirname(resolvedTargetPath) !== resolvedTargetDir) continue;
     if (!isWithinManagedRoot(resolve(previousState.sourcePath), resolve(managedSourceRoot))) continue;
     if (expectedNameSet.has(basename(resolvedTargetPath)) && await pathTargetExists(previousState.sourcePath)) continue;
-    if (!(await pathExists(resolvedTargetPath))) {
-      results.push({ targetPath, status: "removed" });
-      continue;
-    }
-    const isUnverifiedCopy = isUnverifiedWindowsCopy(previousState, previousState.kind);
-    const matchesPrevious = await targetMatchesPreviousState(resolvedTargetPath, previousState)
-      || (isUnverifiedCopy && await ordinaryFileMatchesSource(
-        resolvedTargetPath,
-        previousState.sourcePath,
-        previousState.kind
-      ));
-    if (matchesPrevious) {
-      await fs.rm(resolvedTargetPath, { recursive: true, force: true });
-      results.push({ targetPath, status: "removed" });
-      continue;
-    }
-    if (isUnverifiedCopy) {
-      results.push({ targetPath, status: "conflict" });
-      continue;
-    }
-    if (options.force && await moveReplaceableTarget(resolvedTargetPath)) {
-      results.push({ targetPath, status: "removed" });
-      continue;
-    }
-    results.push({ targetPath, status: "conflict" });
+    candidates.push([resolvedTargetPath, previousState]);
+  }
+  if (candidates.length > 0) await options.validateTargetDir?.(targetDir);
+  const results = [];
+  for (const [targetPath, previousState] of candidates) {
+    recordLinkResult(results, options, await removeRecordedTarget(targetPath, previousState, options));
   }
   return results;
 }
@@ -304,7 +301,7 @@ async function linkSkillDirectories(baseDir, paths, previousLinkedTargets, optio
     options
   ));
   for (const skillName of skillNames) {
-    results.push(await ensureManagedLink(
+    recordLinkResult(results, options, await ensureManagedLink(
       join(baseDir, "skills", skillName),
       join(skillsRoot, skillName),
       "dir",
@@ -320,7 +317,7 @@ async function linkCommands(targetDir, paths, previousLinkedTargets, options) {
   const commandFiles = await getCommandNames(commandsRoot);
   const results = await pruneManagedTargets(targetDir, commandsRoot, commandFiles, previousLinkedTargets, options);
   for (const fileName of commandFiles) {
-    results.push(await ensureManagedLink(
+    recordLinkResult(results, options, await ensureManagedLink(
       join(targetDir, fileName),
       join(commandsRoot, fileName),
       "file",
@@ -332,68 +329,56 @@ async function linkCommands(targetDir, paths, previousLinkedTargets, options) {
 }
 
 async function linkClaude(paths, previousLinkedTargets = {}, options = {}) {
-  const claudeDir = await ensureProviderRootDirectory(paths.homeDir, ".claude");
-  await ensureManagedContainerDirectory(join(claudeDir, "commands"), join(paths.agentsDir, "commands"));
-  await ensureManagedContainerDirectory(join(claudeDir, "skills"), join(paths.agentsDir, "skills"));
-  return [
-    await ensureManagedLink(
-      join(claudeDir, "CLAUDE.md"),
-      join(paths.agentsDir, "AGENTS.md"),
-      "file",
-      previousLinkedTargets,
-      options
-    ),
-    ...await linkCommands(join(claudeDir, "commands"), paths, previousLinkedTargets, options),
-    ...await linkSkillDirectories(claudeDir, paths, previousLinkedTargets, options)
-  ];
+  const claudeDir = await ensureProviderRootDirectory(paths.homeDir, [".claude"], options);
+  await ensureManagedContainerDirectories([
+    join(claudeDir, "commands"),
+    join(claudeDir, "skills")
+  ], options);
+  const results = [];
+  recordLinkResult(results, options, await ensureManagedLink(
+    join(claudeDir, "CLAUDE.md"),
+    join(paths.agentsDir, "AGENTS.md"),
+    "file",
+    previousLinkedTargets,
+    options
+  ));
+  results.push(...await linkCommands(join(claudeDir, "commands"), paths, previousLinkedTargets, options));
+  results.push(...await linkSkillDirectories(claudeDir, paths, previousLinkedTargets, options));
+  return results;
 }
 
 async function linkCodex(paths, previousLinkedTargets = {}, options = {}) {
-  const codexDir = await ensureProviderRootDirectory(paths.homeDir, ".codex");
-  await ensureManagedContainerDirectory(join(codexDir, "skills"), join(paths.agentsDir, "skills"));
-  await ensureManagedContainerDirectory(join(codexDir, "prompts"), join(paths.agentsDir, "commands"));
-  return [
-    await ensureManagedLink(
-      join(codexDir, "AGENTS.md"),
-      join(paths.agentsDir, "AGENTS.md"),
-      "file",
-      previousLinkedTargets,
-      options
-    ),
-    ...await linkSkillDirectories(codexDir, paths, previousLinkedTargets, options),
-    ...await linkCommands(join(codexDir, "prompts"), paths, previousLinkedTargets, options)
-  ];
+  const codexDir = await ensureProviderRootDirectory(paths.homeDir, [".codex"], options);
+  await ensureManagedContainerDirectories([
+    join(codexDir, "skills"),
+    join(codexDir, "prompts")
+  ], options);
+  const results = [];
+  recordLinkResult(results, options, await ensureManagedLink(
+    join(codexDir, "AGENTS.md"),
+    join(paths.agentsDir, "AGENTS.md"),
+    "file",
+    previousLinkedTargets,
+    options
+  ));
+  results.push(...await linkSkillDirectories(codexDir, paths, previousLinkedTargets, options));
+  results.push(...await linkCommands(join(codexDir, "prompts"), paths, previousLinkedTargets, options));
+  return results;
 }
 
-async function linkPi(paths, previousLinkedTargets = {}, options = {}) {
-  const piAgentDir = await ensureProviderRootDirectory(paths.homeDir, ".pi", "agent");
-  await ensureManagedContainerDirectory(join(piAgentDir, "skills"), join(paths.agentsDir, "skills"));
-  await ensureManagedContainerDirectory(join(piAgentDir, "prompts"), join(paths.agentsDir, "commands"));
-  await ensureManagedContainerDirectory(join(piAgentDir, "extensions"), join(paths.agentsDir, "extensions"));
-  const results = [
-    await ensureManagedLink(
-      join(piAgentDir, "AGENTS.md"),
-      join(paths.agentsDir, "AGENTS.md"),
-      "file",
-      previousLinkedTargets,
-      options
-    ),
-    ...await linkSkillDirectories(piAgentDir, paths, previousLinkedTargets, options),
-    ...await linkCommands(join(piAgentDir, "prompts"), paths, previousLinkedTargets, options)
-  ];
-  const extensionsRoot = join(paths.agentsDir, "extensions");
+async function linkPiExtensionsInDirectory(targetDir, extensionsRoot, previousLinkedTargets, options) {
   const extensionNames = await getPiExtensionNames(extensionsRoot);
-  results.push(...await pruneManagedTargets(
-    join(piAgentDir, "extensions"),
+  const results = await pruneManagedTargets(
+    targetDir,
     extensionsRoot,
     extensionNames,
     previousLinkedTargets,
     options
-  ));
+  );
   for (const entryName of extensionNames) {
     const sourcePath = join(extensionsRoot, entryName);
-    results.push(await ensureManagedLink(
-      join(piAgentDir, "extensions", entryName),
+    recordLinkResult(results, options, await ensureManagedLink(
+      join(targetDir, entryName),
       sourcePath,
       await pathIsDirectory(sourcePath) ? "dir" : "file",
       previousLinkedTargets,
@@ -403,14 +388,52 @@ async function linkPi(paths, previousLinkedTargets = {}, options = {}) {
   return results;
 }
 
+async function linkPiExtensions(paths, previousLinkedTargets = {}, options = {}) {
+  const piAgentDir = await ensureProviderRootDirectory(paths.homeDir, [".pi", "agent"], options);
+  const targetDir = join(piAgentDir, "extensions");
+  await ensureManagedContainerDirectories([targetDir], options);
+  return linkPiExtensionsInDirectory(
+    targetDir,
+    join(paths.agentsDir, "extensions"),
+    previousLinkedTargets,
+    options
+  );
+}
+
+async function linkPi(paths, previousLinkedTargets = {}, options = {}) {
+  const piAgentDir = await ensureProviderRootDirectory(paths.homeDir, [".pi", "agent"], options);
+  await ensureManagedContainerDirectories([
+    join(piAgentDir, "extensions"),
+    join(piAgentDir, "skills"),
+    join(piAgentDir, "prompts")
+  ], options);
+  const results = [];
+  recordLinkResult(results, options, await ensureManagedLink(
+    join(piAgentDir, "AGENTS.md"),
+    join(paths.agentsDir, "AGENTS.md"),
+    "file",
+    previousLinkedTargets,
+    options
+  ));
+  results.push(...await linkSkillDirectories(piAgentDir, paths, previousLinkedTargets, options));
+  results.push(...await linkCommands(join(piAgentDir, "prompts"), paths, previousLinkedTargets, options));
+  results.push(...await linkPiExtensionsInDirectory(
+    join(piAgentDir, "extensions"),
+    join(paths.agentsDir, "extensions"),
+    previousLinkedTargets,
+    options
+  ));
+  return results;
+}
+
 export {
   ensureManagedLink,
+  ensureProviderRootDirectory,
   getCommandNames,
   isWithinManagedRoot,
   linkClaude,
   linkCodex,
   linkPi,
-  pathIsDirectory,
-  pathIsFile,
+  linkPiExtensions,
   pruneManagedTargets
 };

package/lib/installer/lock.mjs

@@ -0,0 +1,82 @@
+import * as fs from "node:fs/promises";
+import { dirname } from "node:path";
+import lockfile from "proper-lockfile";
+
+async function readDeploymentRootIdentity(agentsDir) {
+  try {
+    const target = await fs.lstat(agentsDir);
+    if (target.isSymbolicLink() || !target.isDirectory()) {
+      throw new Error(`Deployment root conflict at ${agentsDir}`);
+    }
+    return {
+      canonicalPath: await fs.realpath(agentsDir),
+      dev: target.dev,
+      ino: target.ino
+    };
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function sameIdentity(left, right) {
+  return Boolean(left && right)
+    && left.canonicalPath === right.canonicalPath
+    && left.dev === right.dev
+    && left.ino === right.ino;
+}
+
+async function assertDeploymentRootIdentity(agentsDir, expected) {
+  let current;
+  try {
+    current = await readDeploymentRootIdentity(agentsDir);
+  } catch (error) {
+    throw new Error(`Deployment root changed at ${agentsDir}`, { cause: error });
+  }
+  if (!sameIdentity(current, expected)) {
+    throw new Error(`Deployment root changed at ${agentsDir}`);
+  }
+}
+
+async function withDeploymentLock(paths, operation, options = {}) {
+  await fs.mkdir(dirname(paths.agentsDir), { recursive: true });
+  const beforeWait = await readDeploymentRootIdentity(paths.agentsDir);
+  const release = await lockfile.lock(paths.agentsDir, {
+    realpath: false,
+    lockfilePath: `${paths.agentsDir}.abelworkflow-operation.lock`,
+    retries: options.retries ?? {
+      retries: 100,
+      factor: 1,
+      minTimeout: 50,
+      maxTimeout: 50,
+      randomize: false
+    }
+  });
+  try {
+    let identity;
+    try {
+      identity = await readDeploymentRootIdentity(paths.agentsDir);
+    } catch (error) {
+      throw new Error(`Deployment root changed at ${paths.agentsDir}`, { cause: error });
+    }
+    if (beforeWait && !sameIdentity(identity, beforeWait)) {
+      throw new Error(`Deployment root changed at ${paths.agentsDir}`);
+    }
+    if (!identity) {
+      try {
+        await fs.mkdir(paths.agentsDir);
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+      }
+      identity = await readDeploymentRootIdentity(paths.agentsDir);
+    }
+    if (!identity) throw new Error(`Deployment root changed at ${paths.agentsDir}`);
+    const guard = () => assertDeploymentRootIdentity(paths.agentsDir, identity);
+    await guard();
+    return await operation(guard);
+  } finally {
+    await release();
+  }
+}
+
+export { withDeploymentLock };

package/lib/installer/state.mjs

@@ -18,16 +18,6 @@ function objectField(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
 
-function stringArray(value) {
-  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
-}
-
-function getPreviousManagedCodexAuthKeys(previousMetadata = {}) {
-  return isMetadataV2(previousMetadata)
-    ? stringArray(previousMetadata.managedCodexAuthKeys)
-    : [];
-}
-
 function normalizeManagedCodexAgentFiles(value = {}) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return {};
   return sortObject(Object.fromEntries(Object.entries(value).filter(([name, hash]) => (
@@ -41,30 +31,38 @@ function getPreviousManagedCodexAgentFiles(previousMetadata = {}) {
 }
 
 async function readInstallMetadata(paths) {
-  const metadata = await readJsonFileSafe(metadataPathFor(paths), {});
+  const metadata = await readJsonFileSafe(metadataPathFor(paths), {}, { safeRoot: paths.agentsDir });
   if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
     throw new TypeError(`Install metadata in ${metadataPathFor(paths)} must contain a JSON object`);
   }
+  if (Object.keys(metadata).length > 0 && !isMetadataV2(metadata)) {
+    throw new Error(`Unsupported install metadata schema in ${metadataPathFor(paths)}`);
+  }
   return metadata;
 }
 
-async function writeInstallMetadata(paths, metadata) {
-  return writeJson(metadataPathFor(paths), metadata, { backupLimit: 0 });
+async function writeInstallMetadata(paths, metadata, options = {}) {
+  await options.guard?.();
+  return writeJson(metadataPathFor(paths), metadata, {
+    backupLimit: 0,
+    safeRoot: paths.agentsDir
+  });
 }
 
 function buildInstallMetadata({
   previousMetadata = {},
   packageVersion,
+  workflowInstalled = isMetadataV2(previousMetadata)
+    && previousMetadata.workflowInstalled === true,
   managedFiles = {},
-  managedCodexAuthKeys = getPreviousManagedCodexAuthKeys(previousMetadata),
   managedCodexAgentFiles = getPreviousManagedCodexAgentFiles(previousMetadata),
   linkedTargets = {}
 }) {
   return {
     schemaVersion: 2,
     packageVersion,
+    ...(workflowInstalled ? { workflowInstalled: true } : {}),
     managedFiles: sortObject(managedFiles),
-    managedCodexAuthKeys: [...new Set(managedCodexAuthKeys)].sort(),
     managedCodexAgentFiles: normalizeManagedCodexAgentFiles(managedCodexAgentFiles),
     linkedTargets: sortObject(linkedTargets)
   };
@@ -84,12 +82,9 @@ function finalizeProviderInstallMetadata({
       ? previousMetadata.packageVersion
       : packageVersion,
     managedFiles: isV2 ? objectField(previousMetadata.managedFiles) : {},
-    managedCodexAuthKeys: stringArray(
-      overrides.managedCodexAuthKeys ?? getPreviousManagedCodexAuthKeys(previousMetadata)
-    ),
     managedCodexAgentFiles: overrides.managedCodexAgentFiles
       ?? getPreviousManagedCodexAgentFiles(previousMetadata),
-    linkedTargets: objectField(previousMetadata.linkedTargets)
+    linkedTargets: isV2 ? objectField(previousMetadata.linkedTargets) : {}
   });
 }
 
@@ -135,10 +130,8 @@ export {
   createInstallReport,
   finalizeProviderInstallMetadata,
   getPreviousManagedCodexAgentFiles,
-  getPreviousManagedCodexAuthKeys,
   mergeInstallReports,
   mergeLinkedTargets,
-  metadataPathFor,
   readInstallMetadata,
   writeInstallMetadata
 };

package/lib/paths.mjs

@@ -25,10 +25,8 @@ function createPaths({
     workflowTemplateRoot,
     installMetadataName: ".abelworkflow-install.json",
     claudeSettingsPath: join(absoluteHomeDir, ".claude", "settings.json"),
-    claudeMetaConfigPath: join(absoluteHomeDir, ".claude.json"),
     codexConfigPath: join(absoluteHomeDir, ".codex", "config.toml"),
     codexAuthPath: join(absoluteHomeDir, ".codex", "auth.json"),
-    codexTemplateConfigPath: join(codexTemplateRoot, "config-base.toml"),
     codexTemplateAgentsPath: join(codexTemplateRoot, "agents"),
     piAgentDir,
     piAuthPath: join(piAgentDir, "auth.json"),
@@ -48,7 +46,7 @@ function assertSeparateSourceAndDeployment(packageRoot, agentsDir) {
   throw new Error(
     `源码目录 packageRoot (${packageRoot}) 与部署目录 agentsDir (${agentsDir}) 不能相同或互相嵌套。`
     + "请将源码克隆到独立目录（例如 ~/src/AbelWorkflow），再用 --agents-dir 指向 ~/.agents；"
-    + "请手动迁移已有源码克隆，安装器不会自动移动或删除数据，--force 也不能绕过此限制。"
+    + "请手动移动已有源码目录，安装器不会自动移动或删除数据，--force 也不能绕过此限制。"
   );
 }
 
@@ -78,16 +76,18 @@ function containsPath(parent, child, pathOps = { isAbsolute, relative, sep }) {
 
 const defaultPaths = createPaths();
 
-function getPlatform() {
-  return process.env.ABELWORKFLOW_TEST_PLATFORM || process.platform;
+function getPlatform(platform = process.platform) {
+  return platform;
 }
 
-function isWindows() {
-  return getPlatform() === "win32";
+function isWindows(platform = getPlatform()) {
+  return platform === "win32";
 }
 
-function pathToLabel(path, homeDir = defaultPaths.homeDir) {
-  return path.replace(homeDir, "~");
+function pathToLabel(path, homeDir = defaultPaths.homeDir, pathOps = { isAbsolute, relative, sep }) {
+  if (!containsPath(homeDir, path, pathOps)) return path;
+  const homeRelativePath = pathOps.relative(homeDir, path);
+  return homeRelativePath ? `~${pathOps.sep}${homeRelativePath}` : "~";
 }
 
 function maskSecret(value) {