@kuznai/inception-engine 0.19.0 → 0.21.0

package/dist/{core → src/core}/deploy.js

@@ -4,14 +4,15 @@ import path from "node:path";
 import { AGENT_REGISTRY, AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { UserError } from "../errors.js";
 import { logger } from "../logger.js";
+import * as frontmatterAdapter from "./adapters/frontmatter.js";
 import { compileAdapterActions } from "./adapters/index.js";
+import { applyTomlMcpPatch } from "./adapters/toml.js";
+import { planCapabilityForDeploy } from "./capabilities.js";
+import { applyMergePatch, computeUndoPatch, isPlainObject, } from "./merge-patch.js";
 import { lookupDeployment, registerDeployment, verifyDeployment, } from "./ownership.js";
 import { getDeployMethod, resolveAgentSkillPath } from "./resolve.js";
 import { resolveTargetTemplate } from "./runtime-paths.js";
 import { sourceAccessError, validateSkillDefinitionFile, validateSourceFile, validateSourcePath, } from "./validation.js";
-function isPlainObject(v) {
-    return typeof v === "object" && v !== null && !Array.isArray(v);
-}
 async function readJsonConfigFile(filePath) {
     let rawContent;
     try {
@@ -35,34 +36,6 @@ async function readJsonConfigFile(filePath) {
     }
     return parsed;
 }
-function computeUndoPatch(original, patch) {
-    const undoPatch = {};
-    for (const key of Object.keys(patch)) {
-        const patchVal = patch[key];
-        if (isPlainObject(patchVal) && isPlainObject(original[key])) {
-            undoPatch[key] = computeUndoPatch(original[key], patchVal);
-        }
-        else {
-            undoPatch[key] = key in original ? original[key] : null;
-        }
-    }
-    return undoPatch;
-}
-function applyMergePatch(original, patch) {
-    const patched = { ...original };
-    for (const [key, value] of Object.entries(patch)) {
-        if (value === null) {
-            delete patched[key];
-        }
-        else if (isPlainObject(value) && isPlainObject(patched[key])) {
-            patched[key] = applyMergePatch(patched[key], value);
-        }
-        else {
-            patched[key] = value;
-        }
-    }
-    return patched;
-}
 function detectCollisions(actions) {
     const seen = new Map();
     const warnings = [];
@@ -134,7 +107,7 @@ function checkPairAgentRuleAmbiguities(manifest, primary, rider) {
             JSON.stringify(primarySupport.path) === JSON.stringify(riderSupport.path)) {
             warnings.push({
                 kind: "ambiguity",
-                message: `Both "${primary}" and "${rider}" are listed in agentRules entry "${entry.name}". Both target the same surface — listing both is redundant but harmless; deduplication ensures only one write action is emitted.`,
+                message: `Both "${primary}" and "${rider}" are listed in agentRules entry "${entry.name}". Both target the same surface - listing both is redundant but harmless; deduplication ensures only one write action is emitted.`,
             });
         }
     }
@@ -151,7 +124,7 @@ function checkPairMcpAmbiguities(manifest, primary, rider) {
             continue;
         warnings.push({
             kind: "ambiguity",
-            message: `Both "${primary}" and "${rider}" are listed in mcpServers entry "${entry.name}". "${primary}" writes to a shared MCP surface — verify that deploying to both does not produce conflicting MCP server behavior.`,
+            message: `Both "${primary}" and "${rider}" are listed in mcpServers entry "${entry.name}". "${primary}" writes to a shared MCP surface - verify that deploying to both does not produce conflicting MCP server behavior.`,
         });
     }
     return warnings;
@@ -163,7 +136,7 @@ function checkPairAgentDefinitionAmbiguities(manifest, primary, rider) {
             continue;
         warnings.push({
             kind: "ambiguity",
-            message: `Both "${primary}" and "${rider}" are listed in agentDefinitions entry "${entry.name}". They write to distinct surfaces — verify that this behavioral divergence is intended.`,
+            message: `Both "${primary}" and "${rider}" are listed in agentDefinitions entry "${entry.name}". They write to distinct surfaces - verify that this behavioral divergence is intended.`,
         });
     }
     return warnings;
@@ -191,28 +164,45 @@ function checkAntigravityPathCollisions(manifest) {
         if (defNames.has(entry.name)) {
             warnings.push({
                 kind: "collision",
-                message: `agentDefinitions entry "${entry.name}" and mcpServers entry "${entry.name}" for agent "antigravity" both resolve to {repo}/.agents/rules/${entry.name}.md — one will silently overwrite the other; use different names or remove one entry`,
+                message: `agentDefinitions entry "${entry.name}" and mcpServers entry "${entry.name}" for agent "antigravity" both resolve to {repo}/.agents/rules/${entry.name}.md - one will silently overwrite the other; use different names or remove one entry`,
             });
         }
     }
     return warnings;
 }
+function assertNoAntigravityPathCollisions(manifest) {
+    const collisions = checkAntigravityPathCollisions(manifest);
+    if (collisions.length === 0)
+        return;
+    throw new UserError("MANIFEST_INVALID", collisions.map((warning) => warning.message).join("; "));
+}
 async function planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home) {
     const method = getDeployMethod();
     const actions = [];
-    for (const skill of manifest.skills) {
+    const warnings = [];
+    async function planSkillEntry(skill) {
         const targetAgents = skill.agents.filter((agentId) => detectedAgents.includes(agentId));
         if (targetAgents.length === 0)
-            continue;
+            return;
         const source = path.resolve(sourceDir, skill.path);
         await validateSourcePath(source, skill.path, resolvedSourceDir, realRoot);
         await validateSkillContract(source, skill.path);
         for (const agentId of targetAgents) {
+            const plan = planCapabilityForDeploy({
+                agentId,
+                capability: "skills",
+                entryName: skill.name,
+                targetAgentIds: targetAgents,
+            });
+            if (plan.outcome === "warn") {
+                warnings.push(plan.warning);
+                continue;
+            }
+            if (plan.outcome === "native" || plan.outcome === "redundant")
+                continue;
             const agent = AGENT_REGISTRY_BY_ID[agentId];
             if (!agent)
                 continue;
-            if (!agent.skills)
-                continue;
             actions.push({
                 kind: "skill-dir",
                 skill: skill.name,
@@ -220,18 +210,19 @@ async function planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realR
                 source,
                 target: resolveAgentSkillPath(agent, skill.name, home),
                 method,
-                confidence: agent.provenance.skills ?? "provisional",
+                confidence: plan.confidence ?? "provisional",
             });
         }
     }
-    return actions;
+    await Promise.all(manifest.skills.map(planSkillEntry));
+    return { actions, warnings };
 }
 async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace) {
     const actions = [];
-    for (const fileEntry of manifest.files ?? []) {
+    await Promise.all((manifest.files ?? []).map(async (fileEntry) => {
         const targetAgents = fileEntry.agents.filter((agentId) => detectedAgents.includes(agentId));
         if (targetAgents.length === 0)
-            continue;
+            return;
         const source = path.resolve(sourceDir, fileEntry.path);
         await validateSourcePath(source, fileEntry.path, resolvedSourceDir, realRoot);
         await validateSourceFile(source, fileEntry.path);
@@ -245,10 +236,10 @@ async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, real
                 agent: agentId,
                 source,
                 target: resolveTargetTemplate(fileEntry.target, home, repo, workspace),
-                confidence: agent.provenance.skills,
+                confidence: "implementation-only",
             });
         }
-    }
+    }));
     return actions;
 }
 function planConfigPatchActions(manifest, detectedAgents, home, repo, workspace) {
@@ -273,6 +264,7 @@ function planConfigPatchActions(manifest, detectedAgents, home, repo, workspace)
     return actions;
 }
 export async function planDeploy(manifest, sourceDir, detectedAgents, home, repo, workspace) {
+    assertNoAntigravityPathCollisions(manifest);
     const resolvedSourceDir = path.resolve(sourceDir);
     let realRoot;
     try {
@@ -282,14 +274,16 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home, repo
         realRoot = resolvedSourceDir;
     }
     const repoDir = repo ?? realRoot;
+    const skillPlan = await planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home);
     const actions = [
-        ...(await planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home)),
+        ...skillPlan.actions,
         ...(await planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repoDir, workspace)),
         ...planConfigPatchActions(manifest, detectedAgents, home, repoDir, workspace),
     ];
     const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, manifest.permissions ?? [], sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repoDir, manifest.agentDefinitions ?? [], workspace);
     actions.push(...adapterResult.actions);
     const warnings = [
+        ...skillPlan.warnings,
         ...detectAmbiguities(detectedAgents, manifest),
         ...checkAntigravityPathCollisions(manifest),
         ...detectCollisions(actions),
@@ -376,7 +370,7 @@ async function backupManagedFileWriteTarget(action, home, deps) {
         agent: action.agent,
     }, deps.registry);
     if (!isOwned) {
-        throw new Error(`Target "${action.target}" exists but is not managed by inception-engine — refusing to overwrite`);
+        throw new Error(`Target "${action.target}" exists but is not managed by inception-engine - refusing to overwrite`);
     }
     const backupPath = `${action.target}.inception-backup`;
     await (deps.fileOps ?? defaultDeployFileOps).rm(backupPath, {
@@ -495,6 +489,7 @@ async function deployFileWrite(action, dryRun, verbose, home, planned, deps) {
             source: action.source,
             skill: action.skill,
             agent: action.agent,
+            migratedFrom: action.migratedFrom,
         }, deps.registry));
         logger.ok(label);
         if (verbose) {
@@ -533,7 +528,7 @@ async function deployConfigPatch(action, dryRun, verbose, home, planned, deps) {
         if (existingEntry &&
             (existingEntry.skill !== action.skill ||
                 existingEntry.agent !== action.agent)) {
-            throw new Error(`Config "${action.target}" is already patched by skill "${existingEntry.skill}" for agent "${existingEntry.agent}" — refusing to double-patch`);
+            throw new Error(`Config "${action.target}" is already patched by skill "${existingEntry.skill}" for agent "${existingEntry.agent}" - refusing to double-patch`);
         }
         const original = await readJsonConfigFile(action.target);
         const undoPatch = computeUndoPatch(original, patch);
@@ -581,7 +576,7 @@ async function deployTomlPatch(action, dryRun, verbose, home, planned, deps) {
     try {
         const { previousValue } = await (deps.registry
             ? Promise.resolve({ previousValue: null })
-            : (await import("./adapters/toml.js")).applyTomlMcpPatch(action.target, action.skill, action.config));
+            : applyTomlMcpPatch(action.target, action.skill, action.config));
         // Note: To truly support custom deps here we'd need to refactor toml adapter to accept deps.
         // For now we assume standard adapter for TOML.
         await registerDeployment(home, action.target, {
@@ -605,6 +600,11 @@ async function deployTomlPatch(action, dryRun, verbose, home, planned, deps) {
 }
 async function deployFrontmatterEmit(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
+    if (!isPlainObject(action.frontmatter)) {
+        const msg = `Frontmatter patch for skill "${action.skill}" must be a plain object`;
+        logger.fail(label, msg);
+        return { error: msg };
+    }
     if (dryRun) {
         planned.push({
             verb: "emit-frontmatter",
@@ -617,12 +617,40 @@ async function deployFrontmatterEmit(action, dryRun, verbose, home, planned, dep
         return { error: null };
     }
     try {
-        await (await import("./adapters/frontmatter.js")).writeFrontmatterFile(action.target, action.frontmatter, { preserveBody: true });
-        await registerDeployment(home, action.target, {
+        const existingEntry = await lookupDeployment(home, action.target, deps.registry);
+        if (existingEntry &&
+            (existingEntry.kind !== "frontmatter-emit" ||
+                existingEntry.skill !== action.skill ||
+                existingEntry.agent !== action.agent)) {
+            throw new Error(`Frontmatter target "${action.target}" is already patched by skill "${existingEntry.skill}" for agent "${existingEntry.agent}" - refusing to double-patch`);
+        }
+        const existing = await frontmatterAdapter.readFrontmatterDocumentFile(action.target);
+        const undoPatch = computeUndoPatch(existing.attributes, action.frontmatter);
+        const patchedFrontmatter = applyMergePatch(existing.attributes, action.frontmatter);
+        const content = frontmatterAdapter.buildMarkdownDocument(patchedFrontmatter, existing.body, { hasFrontmatter: true });
+        await replaceFileAtomically(action.target, deps, (tempPath, fileOps) => fileOps.writeFile(tempPath, content, "utf-8"), async () => {
+            try {
+                await lstat(action.target);
+            }
+            catch {
+                return null;
+            }
+            const backupPath = `${action.target}.inception-backup`;
+            await (deps.fileOps ?? defaultDeployFileOps).rm(backupPath, {
+                recursive: true,
+                force: true,
+            });
+            await (deps.fileOps ?? defaultDeployFileOps).rename(action.target, backupPath);
+            return backupPath;
+        }, () => registerDeployment(home, action.target, {
             kind: "frontmatter-emit",
+            patch: action.frontmatter,
+            undoPatch,
+            created: !existing.exists,
+            hadFrontmatter: existing.hasFrontmatter,
             skill: action.skill,
             agent: action.agent,
-        }, deps.registry);
+        }, deps.registry));
         logger.ok(label);
         if (verbose) {
             logger.detail(`emit-frontmatter: ${action.target}`);
@@ -683,7 +711,7 @@ async function assertTargetAbsent(targetPath) {
     catch (err) {
         if (err instanceof Error && err.message.startsWith("Target path appeared"))
             throw err;
-        // ENOENT is expected — target should not exist after backup
+        // ENOENT is expected - target should not exist after backup
     }
 }
 async function createDeployTarget(action, home, deps) {
@@ -746,7 +774,7 @@ async function backupExisting(targetPath, verbose, home, expected, deps) {
         skill: expected.skill,
         agent: expected.agent,
     }, deps.registry))) {
-        throw new Error(`Target "${targetPath}" exists but is not managed by inception-engine — refusing to overwrite`);
+        throw new Error(`Target "${targetPath}" exists but is not managed by inception-engine - refusing to overwrite`);
     }
     const backupPath = `${targetPath}.inception-backup`;
     if (verbose) {

package/dist/{core → src/core}/detect.js

@@ -8,13 +8,8 @@ const defaultExecFn = async (cmd, args) => {
     await execFileAsync(cmd, args);
 };
 export async function detectInstalledAgents(home) {
-    const detected = [];
-    for (const agent of AGENT_REGISTRY) {
-        if (await isAgentInstalled(agent, home)) {
-            detected.push(agent.id);
-        }
-    }
-    return detected;
+    const results = await Promise.all(AGENT_REGISTRY.map((agent) => isAgentInstalled(agent, home)));
+    return AGENT_REGISTRY.filter((_, i) => results[i]).map((a) => a.id);
 }
 async function isAgentInstalled(agent, home) {
     const detectPath = resolveAgentDetectPath(agent, home);

package/dist/{core → src/core}/init.js

@@ -1,9 +1,10 @@
 import { access, readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { AGENT_REGISTRY, AGENT_REGISTRY_BY_ID } from "../config/agents.js";
+import { AGENT_REGISTRY } from "../config/agents.js";
 import { dryRunPrefix, logger } from "../logger.js";
 import { AGENT_IDS, AgentDefinitionEntrySchema, ConfigEntrySchema, FileEntrySchema, McpServerEntrySchema, } from "../schemas/manifest.js";
 import { parseFrontmatterDocument } from "./adapters/frontmatter.js";
+import { shouldInitIncludeAgent } from "./capabilities.js";
 const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 // Ordered list: first match wins. Catch-all is applied at call site.
 // Derived from the registry: group agents by the filename of their global
@@ -14,13 +15,11 @@ const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 const AGENT_RULES_FILE_PATTERNS = (() => {
     const filenameToAgents = new Map();
     for (const agent of AGENT_REGISTRY) {
+        if (!shouldInitIncludeAgent(agent.id, "agentRules", "global"))
+            continue;
         const support = agent.agentRulesSupport;
         if (support?.status !== "supported")
             continue;
-        // Skip riders that require the primary — they cannot be listed independently
-        if (support.surfaceKind?.kind === "shared-via" &&
-            support.surfaceKind.requiresPrimary)
-            continue;
         const filename = support.path.posix[support.path.posix.length - 1]?.toLowerCase();
         if (!filename)
             continue;
@@ -47,10 +46,11 @@ const AGENT_RULES_SUBDIRS = ["rules", "instructions", ".github"];
 // Conventional subdirectories that contain agent definition files.
 // Derived from the registry: for each agent with a supported agentDefinitions
 // surface, extract the directory prefix from its posix path template.
+// Includes the legacy ".github/agents" path for backward compatibility.
 const AGENT_DEFINITION_SUBDIRS = (() => {
     const subdirs = new Set();
     for (const agent of AGENT_REGISTRY) {
-        const support = agent.agentDefinitionsSupport;
+        const support = agent.agentDefinitionsRepoSupport;
         if (support?.status !== "supported")
             continue;
         const tmpl = support.path.posix;
@@ -62,6 +62,7 @@ const AGENT_DEFINITION_SUBDIRS = (() => {
         if (dirSegs.length > 0)
             subdirs.add(dirSegs.join("/"));
     }
+    subdirs.add(".github/agents");
     return Array.from(subdirs);
 })();
 async function hasAntigravityMcpFrontmatter(absPath) {
@@ -114,6 +115,7 @@ function resolveSkillName(relPath, name, namesSeen) {
     return null;
 }
 function buildSkills(found, agents) {
+    const initAgents = agents.filter((agentId) => shouldInitIncludeAgent(agentId, "skills"));
     const namesSeen = new Set();
     const skills = [];
     for (const { relPath, name } of found) {
@@ -121,7 +123,7 @@ function buildSkills(found, agents) {
         if (skillName === null)
             continue;
         namesSeen.add(skillName);
-        skills.push({ name: skillName, path: relPath, agents });
+        skills.push({ name: skillName, path: relPath, agents: initAgents });
     }
     return skills;
 }
@@ -215,7 +217,7 @@ function buildAgentRules(candidates, activeAgents, skillNamesSeen) {
 }
 /**
  * Derives the name for an agent definition entry from its file name.
- * For GitHub Copilot's `{name}.agent.md` naming convention, strips the
+ * For GitHub Copilot's legacy `{name}.agent.md` naming convention, strips the
  * `.agent` infix in addition to the `.md` extension.
  */
 function deriveAgentDefinitionName(relPath, fileName) {
@@ -236,12 +238,15 @@ function deriveAgentDefinitionName(relPath, fileName) {
 /**
  * Maps a known agent-definition subdirectory to the agent IDs that own it.
  * Derived from the registry by matching each agent's agentDefinitionsSupport
- * path prefix. Returns null when the subdir is not recognized.
+ * path prefix. Includes legacy mapping for ".github/agents".
+ * Returns null when the subdir is not recognized.
  */
 function agentsForDefinitionSubdir(subdir) {
+    if (subdir === ".github/agents")
+        return ["github-copilot"];
     const matching = [];
     for (const agent of AGENT_REGISTRY) {
-        const support = agent.agentDefinitionsSupport;
+        const support = agent.agentDefinitionsRepoSupport;
         if (support?.status !== "supported")
             continue;
         const tmpl = support.path.posix;
@@ -325,8 +330,7 @@ async function findAgentDefinitionCandidates(baseDir, skillDirRelPaths, agentRul
 function buildAgentDefinitions(candidates, activeAgents, namesSeen) {
     const definitions = [];
     const localNamesSeen = new Set(namesSeen);
-    const definitionsCapableAgents = activeAgents.filter((id) => AGENT_REGISTRY_BY_ID[id].agentDefinitionsSupport?.status !==
-        "unsupported");
+    const definitionsCapableAgents = activeAgents.filter((id) => shouldInitIncludeAgent(id, "agentDefinitions", "repo"));
     for (const { relPath, name: rawName, suggestedAgents } of candidates) {
         // Use suggested agents (from the dir that was scanned), intersected with
         // active agents that support agentDefinitions. Fall back to all capable
@@ -351,7 +355,7 @@ function buildAgentDefinitions(candidates, activeAgents, namesSeen) {
             }
         }
         localNamesSeen.add(name);
-        definitions.push({ name, path: relPath, agents });
+        definitions.push({ name, path: relPath, agents, scope: "repo" });
     }
     return definitions;
 }
@@ -517,7 +521,8 @@ function logPathAgentEntries(label, entries) {
         return;
     logger.detail(`${label}:`);
     for (const e of entries) {
-        logger.detail(`  ${e.name}  →  ${e.path}  [${e.agents.join(", ")}]`);
+        const entryAgents = e.agents ?? [];
+        logger.detail(`  ${e.name}  →  ${e.path}  [${entryAgents.join(", ")}]`);
     }
 }
 function logVerboseManifest(skills, agentRules, mcpServers, files, configs, agentDefinitions) {
@@ -548,17 +553,7 @@ function logVerboseManifest(skills, agentRules, mcpServers, files, configs, agen
 export async function runInit(options) {
     const { directory, dryRun, force, verbose } = options;
     const agents = options.agents ?? [...AGENT_IDS];
-    const agentRulesCapableAgents = agents.filter((id) => {
-        const support = AGENT_REGISTRY_BY_ID[id].agentRulesSupport;
-        if (!support || support.status === "unsupported")
-            return false;
-        // Exclude riders that require the primary — they cannot operate independently
-        if (support.status === "supported" &&
-            support.surfaceKind?.kind === "shared-via" &&
-            support.surfaceKind.requiresPrimary)
-            return false;
-        return true;
-    });
+    const agentRulesCapableAgents = agents.filter((id) => shouldInitIncludeAgent(id, "agentRules", "global"));
     const manifestPath = path.join(directory, "inception.json");
     if (!dryRun && (await manifestExists(manifestPath)) && !force) {
         logger.error(`Error: ${manifestPath} already exists. Use --force to overwrite.`);

package/dist/src/core/merge-patch.d.ts

@@ -0,0 +1,4 @@
+export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+export declare function computeUndoPatch(original: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+export declare function applyMergePatch(original: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+export declare function applyUndoPatch(current: Record<string, unknown>, undoPatch: Record<string, unknown>): Record<string, unknown>;

package/dist/src/core/merge-patch.js

@@ -0,0 +1,46 @@
+export function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+export function computeUndoPatch(original, patch) {
+    const undoPatch = {};
+    for (const key of Object.keys(patch)) {
+        const patchVal = patch[key];
+        if (isPlainObject(patchVal) && isPlainObject(original[key])) {
+            undoPatch[key] = computeUndoPatch(original[key], patchVal);
+        }
+        else {
+            undoPatch[key] = key in original ? original[key] : null;
+        }
+    }
+    return undoPatch;
+}
+export function applyMergePatch(original, patch) {
+    const patched = { ...original };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null) {
+            delete patched[key];
+        }
+        else if (isPlainObject(value) && isPlainObject(patched[key])) {
+            patched[key] = applyMergePatch(patched[key], value);
+        }
+        else {
+            patched[key] = value;
+        }
+    }
+    return patched;
+}
+export function applyUndoPatch(current, undoPatch) {
+    const restored = { ...current };
+    for (const [key, originalValue] of Object.entries(undoPatch)) {
+        if (originalValue === null) {
+            delete restored[key];
+        }
+        else if (isPlainObject(originalValue) && isPlainObject(restored[key])) {
+            restored[key] = applyUndoPatch(restored[key], originalValue);
+        }
+        else {
+            restored[key] = originalValue;
+        }
+    }
+    return restored;
+}

package/dist/{core → src/core}/ownership.js

@@ -40,10 +40,23 @@ async function setFilePermissions(filePath) {
 function emptyRegistry() {
     return { version: 1, deployments: {} };
 }
+function surfaceIdForEntry(entry) {
+    return entry.surfaceId ?? `${entry.kind}:${entry.agent}:${entry.skill}`;
+}
 export async function registerDeployment(home, targetPath, entry, persistence = defaultRegistryPersistence) {
     const registry = await persistence.load(home);
+    const surfaceId = surfaceIdForEntry(entry);
+    for (const migratedTarget of entry.migratedFrom ?? []) {
+        if (migratedTarget === targetPath)
+            continue;
+        const existing = registry.deployments[migratedTarget];
+        if (existing?.surfaceId === surfaceId) {
+            delete registry.deployments[migratedTarget];
+        }
+    }
     registry.deployments[targetPath] = {
         ...entry,
+        surfaceId,
         deployed: new Date().toISOString(),
     };
     await persistence.save(home, registry);