facult 2.7.3 → 2.7.7

package/src/manage.ts

@@ -1,5 +1,6 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import {
+  appendFile,
   cp,
   lstat,
   mkdir,
@@ -83,6 +84,29 @@ export interface ManagedState {
   tools: Record<string, ManagedToolState>;
 }
 
+type SyncLedgerAction = "add" | "adopt" | "remove" | "skip" | "write";
+
+interface SyncLedgerEvent {
+  version: 1;
+  id: string;
+  correlationId: string;
+  ts: string;
+  command: "sync";
+  phase: "plan" | "apply";
+  dryRun: boolean;
+  tool: string;
+  rootDir: string;
+  scope: "global" | "project";
+  actor: string;
+  action: SyncLedgerAction;
+  targetPath?: string;
+  name?: string;
+  sourcePath?: string;
+  oldHash?: string;
+  newHash?: string;
+  reason: string;
+}
+
 export interface ToolPaths {
   tool: string;
   skillsDir?: string;
@@ -186,6 +210,51 @@ async function ensureDir(p: string) {
   await mkdir(p, { recursive: true });
 }
 
+async function hasCanonicalSource(rootDir: string): Promise<boolean> {
+  const fileCandidates = [
+    "config.toml",
+    "config.local.toml",
+    "AGENTS.global.md",
+    "AGENTS.override.global.md",
+  ];
+  for (const relPath of fileCandidates) {
+    if (await fileExists(join(rootDir, relPath))) {
+      return true;
+    }
+  }
+
+  const dirCandidates = [
+    "agents",
+    "automations",
+    "instructions",
+    "mcp",
+    "rules",
+    "skills",
+    "snippets",
+    "tools",
+  ];
+  for (const relPath of dirCandidates) {
+    const entries = await readdir(join(rootDir, relPath)).catch(
+      () => [] as string[]
+    );
+    if (entries.some((entry) => !entry.startsWith("."))) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+async function isGeneratedOnlyProjectRoot(args: {
+  homeDir: string;
+  rootDir: string;
+}): Promise<boolean> {
+  if (projectRootFromAiRoot(args.rootDir, args.homeDir) == null) {
+    return false;
+  }
+  return !(await hasCanonicalSource(args.rootDir));
+}
+
 function renderedSourceKindForPath(
   sourcePath: string
 ): ManagedRenderedTargetState["sourceKind"] {
@@ -414,13 +483,7 @@ async function resolveToolPaths(
     return base;
   }
 
-  const adapterPaths = getAdapter("codex")?.getDefaultPaths?.();
-  const adapterConfig = adapterPaths?.config
-    ? expandHomePath(adapterPaths.config, home)
-    : null;
-
   const candidates = [
-    adapterConfig,
     homePath(home, ".config", "openai", "codex.json"),
     homePath(home, ".codex", "config.json"),
     homePath(home, ".codex", "mcp.json"),
@@ -446,6 +509,30 @@ export function managedStatePathForRoot(
   return join(facultMachineStateDir(home, rootDir), "managed.json");
 }
 
+function syncLedgerPathForRoot(
+  home: string = homedir(),
+  rootDir?: string
+): string {
+  return join(facultMachineStateDir(home, rootDir), "ledger", "sync.jsonl");
+}
+
+async function appendSyncLedgerEvents(args: {
+  homeDir: string;
+  rootDir: string;
+  events: SyncLedgerEvent[];
+}) {
+  if (args.events.length === 0) {
+    return;
+  }
+  const pathValue = syncLedgerPathForRoot(args.homeDir, args.rootDir);
+  await ensureDir(dirname(pathValue));
+  await appendFile(
+    pathValue,
+    `${args.events.map((event) => JSON.stringify(event)).join("\n")}\n`,
+    "utf8"
+  );
+}
+
 function legacyManagedStatePathForRoot(
   home: string = homedir(),
   rootDir?: string
@@ -720,6 +807,23 @@ async function loadCanonicalAutomations(
   return await loadAutomationEntries(join(rootDir, "automations"));
 }
 
+async function loadRenderableCanonicalAutomations(args: {
+  homeDir: string;
+  rootDir: string;
+  tool: string;
+}): Promise<AutomationEntry[]> {
+  const policy = await loadProjectToolSyncPolicy(args);
+  const automations = await loadCanonicalAutomations(args.rootDir);
+  if (!policy) {
+    return automations;
+  }
+  return automations.filter(
+    (automation) =>
+      policy.automations.includes("*") ||
+      policy.automations.includes(automation.name)
+  );
+}
+
 function isAutomationRuntimeRelativePath(relPath: string): boolean {
   return relPath === "memory.md";
 }
@@ -839,7 +943,12 @@ async function loadCanonicalCodexMarketplaceText(
 }
 
 async function hashDirectoryTree(root: string): Promise<string | null> {
-  if (!(await fileExists(root))) {
+  try {
+    const st = await lstat(root);
+    if (!st.isDirectory()) {
+      return null;
+    }
+  } catch {
     return null;
   }
   const files = await listRelativeFilesWithDotfiles(root);
@@ -1082,7 +1191,9 @@ async function syncAgentFiles({
 
 async function planAutomationFileChanges(args: {
   automationDir: string;
+  homeDir: string;
   rootDir: string;
+  tool: string;
   previouslyManagedTargets?: string[];
 }): Promise<{
   add: string[];
@@ -1090,7 +1201,7 @@ async function planAutomationFileChanges(args: {
   contents: Map<string, string>;
   sources: Map<string, string>;
 }> {
-  const automations = await loadCanonicalAutomations(args.rootDir);
+  const automations = await loadRenderableCanonicalAutomations(args);
   const contents = new Map<string, string>();
   const sources = new Map<string, string>();
   const desiredPaths = new Set<string>();
@@ -1640,13 +1751,15 @@ async function adoptExistingToolAgents(args: {
 }
 
 async function planExistingAutomationAdoption(args: {
+  homeDir: string;
   rootDir: string;
+  tool: string;
   automationDir: string;
 }): Promise<ExistingManagedImportPlan> {
   const plan = emptyManagedImportPlan();
   const liveAutomations = await loadAutomationEntries(args.automationDir);
   const canonicalAutomations = new Map(
-    (await loadCanonicalAutomations(args.rootDir)).map((entry) => [
+    (await loadRenderableCanonicalAutomations(args)).map((entry) => [
       entry.name,
       entry,
     ])
@@ -1674,7 +1787,9 @@ async function planExistingAutomationAdoption(args: {
 }
 
 async function adoptExistingAutomations(args: {
+  homeDir: string;
   rootDir: string;
+  tool: string;
   automationDir: string;
   conflictMode: "keep-canonical" | "keep-existing";
 }): Promise<ExistingManagedItem[]> {
@@ -1685,7 +1800,7 @@ async function adoptExistingAutomations(args: {
   const adopted: ExistingManagedItem[] = [];
   const liveAutomations = await loadAutomationEntries(args.automationDir);
   const canonicalAutomations = new Map(
-    (await loadCanonicalAutomations(args.rootDir)).map((entry) => [
+    (await loadRenderableCanonicalAutomations(args)).map((entry) => [
       entry.name,
       entry,
     ])
@@ -2136,6 +2251,20 @@ function isPreservedToolSkillEntry(name: string): boolean {
   return name.startsWith(".");
 }
 
+interface SkillSymlinkConflict {
+  name: string;
+  livePath: string;
+  canonicalPath?: string;
+  reason: "modified" | "unmanaged" | "disabled";
+}
+
+interface SkillSymlinkPlan {
+  add: string[];
+  remove: string[];
+  conflicts: SkillSymlinkConflict[];
+  adopted: SkillSymlinkConflict[];
+}
+
 async function restorePreservedToolSkillEntries({
   backupDir,
   toolSkillsDir,
@@ -2170,7 +2299,7 @@ async function planSkillSymlinkChanges({
   toolSkillsDir: string;
   rootDir: string;
   tool: string;
-}): Promise<{ add: string[]; remove: string[] }> {
+}): Promise<SkillSymlinkPlan> {
   const desiredEntries = await loadEnabledSkillEntries({
     homeDir,
     rootDir,
@@ -2186,16 +2315,46 @@ async function planSkillSymlinkChanges({
 
   const remove: string[] = [];
   const add: string[] = [];
+  const conflicts: SkillSymlinkConflict[] = [];
 
   for (const entry of existing) {
     if (isPreservedToolSkillEntry(entry.name)) {
       continue;
     }
+    const linkPath = join(toolSkillsDir, entry.name);
     if (!desiredSet.has(entry.name)) {
+      if (
+        entry.isDirectory() &&
+        (await fileExists(join(linkPath, "SKILL.md")))
+      ) {
+        const disabledCanonicalPath = join(rootDir, "skills", entry.name);
+        const [liveHash, canonicalHash] = await Promise.all([
+          hashDirectoryTree(linkPath),
+          hashDirectoryTree(disabledCanonicalPath),
+        ]);
+        if (canonicalHash != null) {
+          if (liveHash === canonicalHash) {
+            remove.push(entry.name);
+            continue;
+          }
+          conflicts.push({
+            name: entry.name,
+            livePath: linkPath,
+            canonicalPath: disabledCanonicalPath,
+            reason: "disabled",
+          });
+          continue;
+        }
+        conflicts.push({
+          name: entry.name,
+          livePath: linkPath,
+          reason: "unmanaged",
+        });
+        continue;
+      }
       remove.push(entry.name);
       continue;
     }
-    const linkPath = join(toolSkillsDir, entry.name);
     const target = desiredTargets.get(entry.name);
     if (!target) {
       remove.push(entry.name);
@@ -2204,6 +2363,27 @@ async function planSkillSymlinkChanges({
     try {
       const st = await lstat(linkPath);
       if (!st.isSymbolicLink()) {
+        if (
+          st.isDirectory() &&
+          (await fileExists(join(linkPath, "SKILL.md")))
+        ) {
+          const [liveHash, canonicalHash] = await Promise.all([
+            hashDirectoryTree(linkPath),
+            hashDirectoryTree(target),
+          ]);
+          if (
+            liveHash != null &&
+            (canonicalHash == null || liveHash !== canonicalHash)
+          ) {
+            conflicts.push({
+              name: entry.name,
+              livePath: linkPath,
+              canonicalPath: target,
+              reason: canonicalHash == null ? "unmanaged" : "modified",
+            });
+            continue;
+          }
+        }
         remove.push(entry.name);
         add.push(entry.name);
         continue;
@@ -2230,6 +2410,8 @@ async function planSkillSymlinkChanges({
   return {
     add: Array.from(new Set(add)).sort(),
     remove: Array.from(new Set(remove)).sort(),
+    conflicts: conflicts.sort((a, b) => a.name.localeCompare(b.name)),
+    adopted: [],
   };
 }
 
@@ -2245,7 +2427,7 @@ async function syncSkillSymlinks({
   rootDir: string;
   tool: string;
   dryRun?: boolean;
-}): Promise<{ add: string[]; remove: string[] }> {
+}): Promise<SkillSymlinkPlan> {
   const plan = await planSkillSymlinkChanges({
     homeDir,
     toolSkillsDir,
@@ -2256,6 +2438,23 @@ async function syncSkillSymlinks({
     return plan;
   }
 
+  const adoptedConflicts = await adoptSkillSymlinkConflictsIntoCanonical({
+    rootDir,
+    conflicts: plan.conflicts,
+  });
+  const adoptedNames = new Set(
+    adoptedConflicts.map((conflict) => conflict.name)
+  );
+  const unresolvedConflicts = plan.conflicts.filter(
+    (conflict) => !adoptedNames.has(conflict.name)
+  );
+  if (adoptedConflicts.length > 0) {
+    await buildIndex({
+      homeDir,
+      rootDir,
+      force: false,
+    });
+  }
   const desiredSkills = new Map(
     (
       await loadEnabledSkillEntries({
@@ -2267,19 +2466,30 @@ async function syncSkillSymlinks({
   );
 
   await ensureDir(toolSkillsDir);
-  for (const name of plan.remove) {
+  const remove = Array.from(
+    new Set([...plan.remove, ...adoptedConflicts.map(({ name }) => name)])
+  ).sort();
+  const add = Array.from(
+    new Set([...plan.add, ...adoptedConflicts.map(({ name }) => name)])
+  ).sort();
+  for (const name of remove) {
     const linkPath = join(toolSkillsDir, name);
     await rm(linkPath, { recursive: true, force: true });
   }
-  for (const name of plan.add) {
-    const target = desiredSkills.get(name);
+  for (const name of add) {
+    const target = desiredSkills.get(name) ?? join(rootDir, "skills", name);
     if (!(target && (await fileExists(target)))) {
       continue;
     }
     const linkPath = join(toolSkillsDir, name);
     await symlink(target, linkPath, "dir");
   }
-  return plan;
+  return {
+    add,
+    remove,
+    conflicts: unresolvedConflicts,
+    adopted: adoptedConflicts,
+  };
 }
 
 async function planMcpWrite({
@@ -2292,10 +2502,14 @@ async function planMcpWrite({
   mcpConfigPath: string;
   rootDir: string;
   tool: string;
-}): Promise<{ needsWrite: boolean; contents: string }> {
-  const { servers } = await loadCanonicalMcpState(rootDir, {
-    includeLocal: true,
-  });
+}): Promise<{ needsWrite: boolean; contents: string; sourcePath: string }> {
+  const { localPath, servers, trackedPath } = await loadCanonicalMcpState(
+    rootDir,
+    {
+      includeLocal: true,
+    }
+  );
+  const sourcePath = (await fileExists(localPath)) ? localPath : trackedPath;
   const filtered = await filterServersForTool({
     homeDir,
     rootDir,
@@ -2305,38 +2519,40 @@ async function planMcpWrite({
   const contents = `${JSON.stringify({ mcpServers: filtered }, null, 2)}\n`;
 
   if (!(await fileExists(mcpConfigPath))) {
-    return { needsWrite: true, contents };
+    return {
+      needsWrite: true,
+      contents,
+      sourcePath,
+    };
   }
   try {
     const current = await Bun.file(mcpConfigPath).text();
-    return { needsWrite: current !== contents, contents };
+    return {
+      needsWrite: current !== contents,
+      contents,
+      sourcePath,
+    };
   } catch {
-    return { needsWrite: true, contents };
+    return {
+      needsWrite: true,
+      contents,
+      sourcePath,
+    };
   }
 }
 
-async function syncMcpConfig({
-  homeDir,
-  mcpConfigPath,
-  rootDir,
-  tool,
-  dryRun,
-}: {
-  homeDir: string;
-  mcpConfigPath: string;
-  rootDir: string;
-  tool: string;
-  dryRun?: boolean;
-}): Promise<{ needsWrite: boolean }> {
-  const plan = await planMcpWrite({ homeDir, mcpConfigPath, rootDir, tool });
-  if (dryRun) {
-    return { needsWrite: plan.needsWrite };
+async function isEmptyGeneratedMcpConfig(pathValue: string): Promise<boolean> {
+  const text = await readTextIfExists(pathValue);
+  if (text == null) {
+    return false;
   }
-  if (plan.needsWrite) {
-    await ensureDir(dirname(mcpConfigPath));
-    await Bun.write(mcpConfigPath, plan.contents);
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    const servers = extractServersObject(parsed);
+    return servers != null && Object.keys(servers).length === 0;
+  } catch {
+    return false;
   }
-  return { needsWrite: plan.needsWrite };
 }
 
 async function writeToolMcpConfig({
@@ -2417,7 +2633,9 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
       : emptyManagedImportPlan(),
     toolPaths.automationDir
       ? await planExistingAutomationAdoption({
+          homeDir: home,
           rootDir,
+          tool,
           automationDir: toolPaths.automationDir,
         })
       : emptyManagedImportPlan(),
@@ -2577,7 +2795,9 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
   }
   if (toolPaths.automationDir && opts.adoptExisting) {
     const result = await adoptExistingAutomations({
+      homeDir: home,
       rootDir,
+      tool,
       automationDir: toolPaths.automationDir,
       conflictMode: importConflictMode,
     });
@@ -2648,10 +2868,20 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
         tool,
       })
     : null;
+  const mcpPreview = toolPaths.mcpConfig
+    ? await planMcpWrite({
+        homeDir: home,
+        mcpConfigPath: toolPaths.mcpConfig,
+        rootDir,
+        tool,
+      })
+    : null;
   const automationPreview = toolPaths.automationDir
     ? await planAutomationFileChanges({
         automationDir: toolPaths.automationDir,
+        homeDir: home,
         rootDir,
+        tool,
       })
     : null;
   const globalDocsPreview = toolPaths.toolHome
@@ -2927,6 +3157,15 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
       ),
     });
   }
+  if (toolPaths.mcpConfig && mcpPreview) {
+    updateRenderedTargetState({
+      entry: managedEntry,
+      writtenTargets: [toolPaths.mcpConfig],
+      removedTargets: [],
+      contents: new Map([[toolPaths.mcpConfig, mcpPreview.contents]]),
+      sources: new Map([[toolPaths.mcpConfig, mcpPreview.sourcePath]]),
+    });
+  }
 
   if (pluginPreview) {
     updateRenderedTargetState({
@@ -3248,7 +3487,7 @@ interface RenderedConflict {
   targetPath: string;
   sourcePath: string;
   sourceKind: ManagedRenderedTargetState["sourceKind"];
-  reason: "modified" | "unknown_state";
+  reason: "modified" | "unknown_state" | "missing_source";
 }
 
 interface RenderedApplyPlan {
@@ -3265,16 +3504,9 @@ async function planRenderedTargetConflicts(args: {
   desiredSources: Map<string, string>;
   conflictMode?: "warn" | "overwrite";
   protectAllSources?: boolean;
+  protectMissingSources?: boolean;
   normalizeText?: boolean;
 }): Promise<RenderedApplyPlan> {
-  if (args.conflictMode === "overwrite") {
-    return {
-      write: args.desiredWrites,
-      remove: args.desiredRemoves,
-      conflicts: [],
-    };
-  }
-
   const previous = args.entry.renderedTargets ?? {};
   const write: string[] = [];
   const remove: string[] = [];
@@ -3293,7 +3525,15 @@ async function planRenderedTargetConflicts(args: {
       continue;
     }
     const sourceKind = renderedSourceKindForPath(sourcePath);
-    if (sourceKind !== "builtin" && !args.protectAllSources) {
+    if (args.conflictMode === "overwrite" && sourceKind === "builtin") {
+      if (args.desiredWrites.includes(targetPath)) {
+        write.push(targetPath);
+      } else {
+        remove.push(targetPath);
+      }
+      continue;
+    }
+    if (sourceKind !== "builtin" && args.protectAllSources === false) {
       if (args.desiredWrites.includes(targetPath)) {
         write.push(targetPath);
       } else {
@@ -3303,6 +3543,20 @@ async function planRenderedTargetConflicts(args: {
     }
 
     const prior = previous[targetPath];
+    if (
+      args.protectMissingSources &&
+      args.desiredRemoves.includes(targetPath) &&
+      prior?.sourcePath &&
+      !(await fileExists(prior.sourcePath))
+    ) {
+      conflicts.push({
+        targetPath,
+        sourcePath: prior.sourcePath,
+        sourceKind,
+        reason: "missing_source",
+      });
+      continue;
+    }
     const currentHash = await readTargetHash(targetPath, {
       normalizeText: args.normalizeText,
     });
@@ -3372,9 +3626,11 @@ function logRenderedConflicts(
   for (const conflict of conflicts) {
     const verb = dryRun ? "would skip" : "skipped";
     const state =
-      conflict.reason === "unknown_state"
-        ? "no prior managed hash is recorded"
-        : "local edits were detected";
+      conflict.reason === "missing_source"
+        ? `canonical source is missing at ${conflict.sourcePath}`
+        : conflict.reason === "unknown_state"
+          ? "no prior managed hash is recorded"
+          : "local edits were detected";
     const surface =
       conflict.sourceKind === "builtin"
         ? "builtin-backed target"
@@ -3387,6 +3643,57 @@ function logRenderedConflicts(
   }
 }
 
+function logSkillSymlinkConflicts(
+  tool: string,
+  conflicts: SkillSymlinkConflict[],
+  dryRun?: boolean
+) {
+  for (const conflict of conflicts) {
+    const verb =
+      conflict.reason === "disabled"
+        ? dryRun
+          ? "would preserve"
+          : "preserved"
+        : dryRun
+          ? "would adopt"
+          : "adopted";
+    const state =
+      conflict.reason === "unmanaged"
+        ? "it is not in canonical skill state"
+        : conflict.reason === "disabled"
+          ? "it maps to a disabled canonical skill"
+          : "local skill content differs from canonical state";
+    const canonical = conflict.canonicalPath
+      ? ` (canonical ${conflict.canonicalPath})`
+      : "";
+    console.warn(
+      `${tool}: ${verb} skill ${conflict.name} from ${conflict.livePath}${canonical} because ${state}.`
+    );
+  }
+}
+
+async function adoptSkillSymlinkConflictsIntoCanonical(args: {
+  rootDir: string;
+  conflicts: SkillSymlinkConflict[];
+}): Promise<SkillSymlinkConflict[]> {
+  const adopted: SkillSymlinkConflict[] = [];
+  for (const conflict of args.conflicts) {
+    if (conflict.reason === "disabled") {
+      continue;
+    }
+    const canonicalPath =
+      conflict.canonicalPath ?? join(args.rootDir, "skills", conflict.name);
+    if (!(await fileExists(join(conflict.livePath, "SKILL.md")))) {
+      continue;
+    }
+    await rm(canonicalPath, { recursive: true, force: true });
+    await ensureDir(dirname(canonicalPath));
+    await cp(conflict.livePath, canonicalPath, { recursive: true });
+    adopted.push({ ...conflict, canonicalPath });
+  }
+  return adopted.sort((a, b) => a.name.localeCompare(b.name));
+}
+
 async function applyRenderedWrites(args: {
   contents: Map<string, ManagedTargetContent>;
   targets: string[];
@@ -3485,9 +3792,9 @@ function pruneAutomationRuntimeRenderedTargets(args: {
 
 function logSyncDryRun({
   tool,
-  entry,
   skillPlan,
   mcpPlan,
+  mcpConflicts,
   agentPlan,
   agentConflicts,
   automationPlan,
@@ -3502,9 +3809,9 @@ function logSyncDryRun({
   pluginConflicts,
 }: {
   tool: string;
-  entry: ManagedToolState;
-  skillPlan: { add: string[]; remove: string[] };
-  mcpPlan: { needsWrite: boolean };
+  skillPlan: SkillSymlinkPlan;
+  mcpPlan: { write: boolean; targetPath: string };
+  mcpConflicts: RenderedConflict[];
   agentPlan: { add: string[]; remove: string[] };
   agentConflicts: RenderedConflict[];
   automationPlan: { write: string[]; remove: string[] };
@@ -3524,6 +3831,7 @@ function logSyncDryRun({
   for (const name of skillPlan.remove) {
     console.log(`${tool}: would remove skill ${name}`);
   }
+  logSkillSymlinkConflicts(tool, skillPlan.conflicts, true);
   for (const p of agentPlan.add) {
     console.log(`${tool}: would write agent ${p}`);
   }
@@ -3566,12 +3874,14 @@ function logSyncDryRun({
     console.log(`${tool}: would remove plugin asset ${p}`);
   }
   logRenderedConflicts(tool, pluginConflicts, true);
-  if (mcpPlan.needsWrite && entry.mcpConfig) {
-    console.log(`${tool}: would update mcp config ${entry.mcpConfig}`);
+  if (mcpPlan.write) {
+    console.log(`${tool}: would update mcp config ${mcpPlan.targetPath}`);
   }
+  logRenderedConflicts(tool, mcpConflicts, true);
   if (
     skillPlan.add.length === 0 &&
     skillPlan.remove.length === 0 &&
+    skillPlan.conflicts.length === 0 &&
     agentPlan.add.length === 0 &&
     agentPlan.remove.length === 0 &&
     automationPlan.write.length === 0 &&
@@ -3584,7 +3894,8 @@ function logSyncDryRun({
     !configPlan.remove &&
     pluginPlan.write.length === 0 &&
     pluginPlan.remove.length === 0 &&
-    !mcpPlan.needsWrite &&
+    !mcpPlan.write &&
+    mcpConflicts.length === 0 &&
     agentConflicts.length === 0 &&
     automationConflicts.length === 0 &&
     globalDocsConflicts.length === 0 &&
@@ -3596,6 +3907,171 @@ function logSyncDryRun({
   }
 }
 
+function syncLedgerBase(args: {
+  correlationId: string;
+  dryRun: boolean;
+  homeDir: string;
+  rootDir: string;
+  tool: string;
+}): Omit<
+  SyncLedgerEvent,
+  | "action"
+  | "id"
+  | "name"
+  | "newHash"
+  | "oldHash"
+  | "reason"
+  | "sourcePath"
+  | "targetPath"
+> {
+  return {
+    version: 1,
+    correlationId: args.correlationId,
+    ts: new Date().toISOString(),
+    command: "sync",
+    phase: args.dryRun ? "plan" : "apply",
+    dryRun: args.dryRun,
+    tool: args.tool,
+    rootDir: args.rootDir,
+    scope: projectRootFromAiRoot(args.rootDir, args.homeDir)
+      ? "project"
+      : "global",
+    actor: process.env.USER ?? "unknown",
+  };
+}
+
+function renderedDesiredHash(args: {
+  contents: Map<string, ManagedTargetContent>;
+  normalizeText?: boolean;
+  targetPath: string;
+}): string | undefined {
+  const contents = args.contents.get(args.targetPath);
+  return contents
+    ? targetContentHash(contents, { normalizeText: args.normalizeText })
+    : undefined;
+}
+
+function collectRenderedLedgerEvents(args: {
+  base: Omit<
+    SyncLedgerEvent,
+    | "action"
+    | "id"
+    | "name"
+    | "newHash"
+    | "oldHash"
+    | "reason"
+    | "sourcePath"
+    | "targetPath"
+  >;
+  conflicts: RenderedConflict[];
+  contents: Map<string, ManagedTargetContent>;
+  entry: ManagedToolState;
+  normalizeText?: boolean;
+  plan: RenderedApplyPlan;
+  reason: string;
+  sources: Map<string, string>;
+}): SyncLedgerEvent[] {
+  const previous = args.entry.renderedTargets ?? {};
+  const events: SyncLedgerEvent[] = [];
+  for (const targetPath of args.plan.write) {
+    events.push({
+      ...args.base,
+      id: randomUUID(),
+      action: "write",
+      targetPath,
+      sourcePath: args.sources.get(targetPath),
+      oldHash: previous[targetPath]?.hash,
+      newHash: renderedDesiredHash({
+        contents: args.contents,
+        normalizeText: args.normalizeText,
+        targetPath,
+      }),
+      reason: args.reason,
+    });
+  }
+  for (const targetPath of args.plan.remove) {
+    events.push({
+      ...args.base,
+      id: randomUUID(),
+      action: "remove",
+      targetPath,
+      sourcePath: previous[targetPath]?.sourcePath,
+      oldHash: previous[targetPath]?.hash,
+      reason: args.reason,
+    });
+  }
+  for (const conflict of args.conflicts) {
+    events.push({
+      ...args.base,
+      id: randomUUID(),
+      action: "skip",
+      targetPath: conflict.targetPath,
+      sourcePath: conflict.sourcePath,
+      oldHash: previous[conflict.targetPath]?.hash,
+      reason: conflict.reason,
+    });
+  }
+  return events;
+}
+
+function collectSkillLedgerEvents(args: {
+  base: Omit<
+    SyncLedgerEvent,
+    | "action"
+    | "id"
+    | "name"
+    | "newHash"
+    | "oldHash"
+    | "reason"
+    | "sourcePath"
+    | "targetPath"
+  >;
+  plan: SkillSymlinkPlan;
+}): SyncLedgerEvent[] {
+  const events: SyncLedgerEvent[] = [];
+  for (const name of args.plan.add) {
+    events.push({
+      ...args.base,
+      id: randomUUID(),
+      action: "add",
+      name,
+      reason: "skill_symlink",
+    });
+  }
+  for (const name of args.plan.remove) {
+    events.push({
+      ...args.base,
+      id: randomUUID(),
+      action: "remove",
+      name,
+      reason: "skill_symlink",
+    });
+  }
+  for (const conflict of args.plan.conflicts) {
+    events.push({
+      ...args.base,
+      id: randomUUID(),
+      action: "skip",
+      name: conflict.name,
+      targetPath: conflict.livePath,
+      sourcePath: conflict.canonicalPath,
+      reason: `skill_${conflict.reason}`,
+    });
+  }
+  for (const conflict of args.plan.adopted) {
+    events.push({
+      ...args.base,
+      id: randomUUID(),
+      action: "adopt",
+      name: conflict.name,
+      targetPath: conflict.livePath,
+      sourcePath: conflict.canonicalPath,
+      reason: `skill_${conflict.reason}`,
+    });
+  }
+  return events;
+}
+
 async function repairManagedCanonicalContent(args: {
   homeDir: string;
   rootDir: string;
@@ -4002,6 +4478,38 @@ async function syncManagedToolEntry({
   dryRun?: boolean;
   builtinConflictMode?: "warn" | "overwrite";
 }) {
+  const correlationId = randomUUID();
+  const baseLedger = syncLedgerBase({
+    correlationId,
+    dryRun: Boolean(dryRun),
+    homeDir,
+    rootDir,
+    tool,
+  });
+  if (await isGeneratedOnlyProjectRoot({ homeDir, rootDir })) {
+    const message = `${tool}: ${dryRun ? "would skip" : "skipped"} sync because project .ai contains generated state only and no canonical source. Initialize or restore project .ai source before syncing managed project output.`;
+    if (dryRun) {
+      console.log(message);
+    } else {
+      console.warn(message);
+    }
+    if (!dryRun) {
+      await appendSyncLedgerEvents({
+        homeDir,
+        rootDir,
+        events: [
+          {
+            ...baseLedger,
+            id: randomUUID(),
+            action: "skip",
+            reason: "generated_only_project_root",
+          },
+        ],
+      });
+    }
+    return;
+  }
+
   pruneAutomationRuntimeRenderedTargets({
     entry,
     automationDir: entry.automationDir,
@@ -4024,7 +4532,18 @@ async function syncManagedToolEntry({
         tool,
         dryRun,
       })
-    : { add: [], remove: [] };
+    : { add: [], remove: [], conflicts: [], adopted: [] };
+  const skillLedgerEvents = collectSkillLedgerEvents({
+    base: baseLedger,
+    plan: skillPlan,
+  });
+  if (!dryRun) {
+    await appendSyncLedgerEvents({
+      homeDir,
+      rootDir,
+      events: skillLedgerEvents,
+    });
+  }
 
   const agentPlan = entry.agentsDir
     ? await planAgentFileChanges({
@@ -4037,20 +4556,21 @@ async function syncManagedToolEntry({
   const automationPlan = entry.automationDir
     ? await planAutomationFileChanges({
         automationDir: entry.automationDir,
+        homeDir,
         rootDir,
+        tool,
         previouslyManagedTargets: Object.keys(entry.renderedTargets ?? {}),
       })
     : { add: [], remove: [], contents: new Map(), sources: new Map() };
 
   const mcpPlan = entry.mcpConfig
-    ? await syncMcpConfig({
+    ? await planMcpWrite({
         homeDir,
         mcpConfigPath: entry.mcpConfig,
         rootDir,
         tool,
-        dryRun,
       })
-    : { needsWrite: false };
+    : null;
 
   const globalDocsPlan = entry.toolHome
     ? await planToolGlobalDocsSync({
@@ -4113,6 +4633,7 @@ async function syncManagedToolEntry({
           previouslyManagedTargets: Object.keys(entry.renderedTargets ?? {}),
         })
       : { add: [], remove: [], contents: new Map(), sources: new Map() };
+  const protectMissingSources = projectRootFromAiRoot(rootDir, homeDir) != null;
 
   const agentRendered = await planRenderedTargetConflicts({
     entry,
@@ -4121,6 +4642,7 @@ async function syncManagedToolEntry({
     desiredContents: agentPlan.contents,
     desiredSources: agentPlan.sources,
     conflictMode: builtinConflictMode,
+    protectMissingSources,
   });
   const globalDocsRendered = await planRenderedTargetConflicts({
     entry,
@@ -4129,6 +4651,7 @@ async function syncManagedToolEntry({
     desiredContents: globalDocsPlan.contents,
     desiredSources: globalDocsPlan.sources,
     conflictMode: builtinConflictMode,
+    protectMissingSources,
   });
   const automationRendered = await planRenderedTargetConflicts({
     entry,
@@ -4138,6 +4661,7 @@ async function syncManagedToolEntry({
     desiredSources: automationPlan.sources,
     conflictMode: builtinConflictMode,
     protectAllSources: true,
+    protectMissingSources,
   });
   const rulesRendered = await planRenderedTargetConflicts({
     entry,
@@ -4146,6 +4670,7 @@ async function syncManagedToolEntry({
     desiredContents: rulesPlan.contents,
     desiredSources: rulesPlan.sources,
     conflictMode: builtinConflictMode,
+    protectMissingSources,
   });
   const configContents =
     configPlan.contents != null
@@ -4165,6 +4690,7 @@ async function syncManagedToolEntry({
     desiredContents: configContents,
     desiredSources: configSources,
     conflictMode: builtinConflictMode,
+    protectMissingSources,
   });
   const pluginRendered = await planRenderedTargetConflicts({
     entry,
@@ -4175,14 +4701,126 @@ async function syncManagedToolEntry({
     conflictMode: builtinConflictMode,
     protectAllSources: true,
     normalizeText: false,
+    protectMissingSources,
   });
+  const mcpContents =
+    entry.mcpConfig && mcpPlan
+      ? new Map<string, ManagedTargetContent>([
+          [entry.mcpConfig, mcpPlan.contents],
+        ])
+      : new Map<string, ManagedTargetContent>();
+  const mcpSources =
+    entry.mcpConfig && mcpPlan
+      ? new Map<string, string>([[entry.mcpConfig, mcpPlan.sourcePath]])
+      : new Map<string, string>();
+  const mcpRendered = await planRenderedTargetConflicts({
+    entry,
+    desiredWrites:
+      entry.mcpConfig && mcpPlan?.needsWrite ? [entry.mcpConfig] : [],
+    desiredRemoves: [],
+    desiredContents: mcpContents,
+    desiredSources: mcpSources,
+    conflictMode: builtinConflictMode,
+    protectMissingSources,
+  });
+  if (
+    entry.mcpConfig &&
+    mcpRendered.conflicts.some(
+      (conflict) =>
+        conflict.targetPath === entry.mcpConfig &&
+        conflict.reason === "unknown_state"
+    ) &&
+    (await isEmptyGeneratedMcpConfig(entry.mcpConfig))
+  ) {
+    mcpRendered.conflicts = mcpRendered.conflicts.filter(
+      (conflict) => conflict.targetPath !== entry.mcpConfig
+    );
+    mcpRendered.write.push(entry.mcpConfig);
+    mcpRendered.write.sort();
+  }
+
+  const ledgerEvents = [
+    ...collectRenderedLedgerEvents({
+      base: baseLedger,
+      conflicts: agentRendered.conflicts,
+      contents: agentPlan.contents,
+      entry,
+      normalizeText: true,
+      plan: agentRendered,
+      reason: "agent_render",
+      sources: agentPlan.sources,
+    }),
+    ...collectRenderedLedgerEvents({
+      base: baseLedger,
+      conflicts: automationRendered.conflicts,
+      contents: automationPlan.contents,
+      entry,
+      normalizeText: true,
+      plan: automationRendered,
+      reason: "automation_render",
+      sources: automationPlan.sources,
+    }),
+    ...collectRenderedLedgerEvents({
+      base: baseLedger,
+      conflicts: globalDocsRendered.conflicts,
+      contents: globalDocsPlan.contents,
+      entry,
+      normalizeText: true,
+      plan: globalDocsRendered,
+      reason: "global_doc_render",
+      sources: globalDocsPlan.sources,
+    }),
+    ...collectRenderedLedgerEvents({
+      base: baseLedger,
+      conflicts: rulesRendered.conflicts,
+      contents: rulesPlan.contents,
+      entry,
+      normalizeText: true,
+      plan: rulesRendered,
+      reason: "rule_render",
+      sources: rulesPlan.sources,
+    }),
+    ...collectRenderedLedgerEvents({
+      base: baseLedger,
+      conflicts: configRendered.conflicts,
+      contents: configContents,
+      entry,
+      normalizeText: true,
+      plan: configRendered,
+      reason: "tool_config_render",
+      sources: configSources,
+    }),
+    ...collectRenderedLedgerEvents({
+      base: baseLedger,
+      conflicts: mcpRendered.conflicts,
+      contents: mcpContents,
+      entry,
+      normalizeText: true,
+      plan: mcpRendered,
+      reason: "mcp_render",
+      sources: mcpSources,
+    }),
+    ...collectRenderedLedgerEvents({
+      base: baseLedger,
+      conflicts: pluginRendered.conflicts,
+      contents: pluginPlan.contents,
+      entry,
+      normalizeText: false,
+      plan: pluginRendered,
+      reason: "plugin_render",
+      sources: pluginPlan.sources,
+    }),
+  ];
 
   if (dryRun) {
     logSyncDryRun({
       tool,
-      entry,
       skillPlan,
-      mcpPlan,
+      mcpPlan: {
+        write: mcpRendered.write.length > 0,
+        targetPath: entry.mcpConfig ?? "",
+      },
+      mcpConflicts: mcpRendered.conflicts,
       agentPlan: { add: agentRendered.write, remove: agentRendered.remove },
       agentConflicts: agentRendered.conflicts,
       automationPlan: {
@@ -4238,6 +4876,10 @@ async function syncManagedToolEntry({
       contents: configContents,
       targets: configRendered.write,
     });
+    await applyRenderedWrites({
+      contents: mcpContents,
+      targets: mcpRendered.write,
+    });
     await applyRenderedRemoves(pluginRendered.remove);
     await applyRenderedWrites({
       contents: pluginPlan.contents,
@@ -4251,7 +4893,10 @@ async function syncManagedToolEntry({
     logRenderedConflicts(tool, globalDocsRendered.conflicts);
     logRenderedConflicts(tool, rulesRendered.conflicts);
     logRenderedConflicts(tool, configRendered.conflicts);
+    logRenderedConflicts(tool, mcpRendered.conflicts);
     logRenderedConflicts(tool, pluginRendered.conflicts);
+    logSkillSymlinkConflicts(tool, skillPlan.adopted);
+    logSkillSymlinkConflicts(tool, skillPlan.conflicts);
 
     updateRenderedTargetState({
       entry,
@@ -4288,6 +4933,13 @@ async function syncManagedToolEntry({
       contents: configContents,
       sources: configSources,
     });
+    updateRenderedTargetState({
+      entry,
+      writtenTargets: mcpRendered.write,
+      removedTargets: mcpRendered.remove,
+      contents: mcpContents,
+      sources: mcpSources,
+    });
     updateRenderedTargetState({
       entry,
       writtenTargets: pluginRendered.write,
@@ -4302,6 +4954,7 @@ async function syncManagedToolEntry({
         `${tool}: adopted existing content ${name} into canonical store`
       );
     }
+    await appendSyncLedgerEvents({ homeDir, rootDir, events: ledgerEvents });
     console.log(`${tool} synced`);
   }
 }