@kuznai/inception-engine 0.24.0 → 0.25.1

package/dist/src/config/manifest.js

@@ -12,20 +12,22 @@ export async function loadManifest(directory) {
     catch (err) {
         const code = err.code;
         if (code === "ENOENT") {
-            throw new UserError("MANIFEST_INVALID", `No inception.json found in ${directory}. Are you pointing to the right repo?`);
+            throw new UserError("MANIFEST_INVALID", `No inception.json found in ${directory}. Are you pointing to the right repo?`, { cause: err });
         }
         if (code === "EACCES" || code === "EPERM") {
-            throw new UserError("MANIFEST_INVALID", `Permission denied reading ${manifestPath}. Check file permissions.`);
+            throw new UserError("MANIFEST_INVALID", `Permission denied reading ${manifestPath}. Check file permissions.`, { cause: err });
         }
         const detail = err instanceof Error ? err.message : String(err);
-        throw new UserError("MANIFEST_INVALID", `Failed to read ${manifestPath}: ${detail}`);
+        throw new UserError("MANIFEST_INVALID", `Failed to read ${manifestPath}: ${detail}`, { cause: err });
     }
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
-    catch {
-        throw new UserError("MANIFEST_INVALID", `Invalid JSON in ${manifestPath}`);
+    catch (err) {
+        throw new UserError("MANIFEST_INVALID", `Invalid JSON in ${manifestPath}`, {
+            cause: err,
+        });
     }
     return validateManifest(parsed, manifestPath);
 }

package/dist/src/core/adapters/frontmatter.js

@@ -1,6 +1,6 @@
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
+import { readFile } from "node:fs/promises";
 import YAML from "yaml";
+import { writeFileAtomic } from "../atomic-write.js";
 /**
  * Splits a Markdown string into YAML frontmatter and the remaining body.
  * Expects the file to start with --- delimiter.
@@ -54,11 +54,6 @@ export function buildMarkdownDocument(frontmatter, body = "", options = {}) {
     const separator = cleanBody ? "\n\n" : "\n";
     return `---\n${serialized}\n---\n${separator}${cleanBody}`;
 }
-function createAtomicTempPath(targetPath) {
-    return `${targetPath}.inception-tmp-${process.pid}-${Date.now()}-${Math.random()
-        .toString(36)
-        .slice(2)}`;
-}
 /**
  * Reads an existing `.md` file and parses its frontmatter.
  * Returns `{ attributes: {}, body: "" }` if the file does not exist.
@@ -98,19 +93,5 @@ export async function writeFrontmatterFile(filePath, frontmatter, options = {})
         body = existing.body;
     }
     const content = buildFrontmatterDocument(frontmatter, body);
-    const tempPath = createAtomicTempPath(filePath);
-    try {
-        await mkdir(path.dirname(filePath), { recursive: true });
-        await writeFile(tempPath, content, "utf-8");
-        await rename(tempPath, filePath);
-    }
-    catch (err) {
-        try {
-            await rm(tempPath, { force: true });
-        }
-        catch {
-            /* best-effort cleanup */
-        }
-        throw err;
-    }
+    await writeFileAtomic(filePath, content);
 }

package/dist/src/core/adapters/toml.js

@@ -1,6 +1,6 @@
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
+import { readFile } from "node:fs/promises";
 import { parse, stringify } from "smol-toml";
+import { writeFileAtomic } from "../atomic-write.js";
 /**
  * Reads and parses a TOML file. Returns an empty object if the file does not
  * exist (treat a missing config.toml as an empty config).
@@ -19,27 +19,8 @@ export async function readTomlConfig(filePath) {
     const parsed = parse(raw);
     return parsed;
 }
-function createAtomicTempPath(targetPath) {
-    return `${targetPath}.inception-tmp-${process.pid}-${Date.now()}-${Math.random()
-        .toString(36)
-        .slice(2)}`;
-}
 async function writeTomlConfigAtomic(filePath, obj) {
-    const tempPath = createAtomicTempPath(filePath);
-    try {
-        await mkdir(path.dirname(filePath), { recursive: true });
-        await writeFile(tempPath, stringify(obj), "utf-8");
-        await rename(tempPath, filePath);
-    }
-    catch (err) {
-        try {
-            await rm(tempPath, { force: true });
-        }
-        catch {
-            /* best-effort cleanup */
-        }
-        throw err;
-    }
+    await writeFileAtomic(filePath, stringify(obj));
 }
 /**
  * Merges a named MCP server entry into `config.toml`'s `[mcpServers]` table.

package/dist/src/core/atomic-write.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Writes `content` to `targetPath` atomically by staging through a temp file
+ * in the same directory and renaming into place. The temp file is cleaned up
+ * on error. Parent directory is created if absent.
+ *
+ * On Windows, `fs.rename` throws EPERM when the target file already exists.
+ * In that case we fall back to `cp` + `unlink` of the temp file, which is not
+ * atomic but is the best available option without third-party packages.
+ */
+export declare function writeFileAtomic(targetPath: string, content: string, options?: {
+    encoding?: BufferEncoding;
+}): Promise<void>;

package/dist/src/core/atomic-write.js

@@ -0,0 +1,42 @@
+import { cp, mkdir, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Writes `content` to `targetPath` atomically by staging through a temp file
+ * in the same directory and renaming into place. The temp file is cleaned up
+ * on error. Parent directory is created if absent.
+ *
+ * On Windows, `fs.rename` throws EPERM when the target file already exists.
+ * In that case we fall back to `cp` + `unlink` of the temp file, which is not
+ * atomic but is the best available option without third-party packages.
+ */
+export async function writeFileAtomic(targetPath, content, options) {
+    const dir = path.dirname(targetPath);
+    const tempPath = path.join(dir, `.inception-tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(dir, { recursive: true });
+    try {
+        await writeFile(tempPath, content, options?.encoding ?? "utf-8");
+        try {
+            await rename(tempPath, targetPath);
+        }
+        catch (err) {
+            // On Windows, rename fails with EPERM when the target already exists.
+            if (process.platform === "win32" &&
+                (err.code === "EPERM" ||
+                    err.code === "EBUSY")) {
+                await cp(tempPath, targetPath);
+                await unlink(tempPath);
+                return;
+            }
+            throw err;
+        }
+    }
+    catch (err) {
+        try {
+            await unlink(tempPath);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
+}

package/dist/src/core/deploy.d.ts

@@ -1,10 +1,10 @@
 import type { AgentId, DeployAction, Manifest, PlannedChange, PlanWarning, SkillDirDeployAction } from "../types.ts";
 import { type RegistryPersistence } from "./ownership.ts";
-export declare function planDeploy(manifest: Manifest, sourceDir: string, detectedAgents: AgentId[], home: string, repo?: string, workspace?: string): Promise<{
+export declare function planDeploy(manifest: Manifest, sourceDir: string, detectedAgents: AgentId[], home: string, repo?: string, workspace?: string, signal?: AbortSignal): Promise<{
     actions: DeployAction[];
     warnings: PlanWarning[];
 }>;
-export declare function executeDeploy(actions: DeployAction[], dryRun: boolean, verbose: boolean, home: string, deps?: DeployDependencies): Promise<{
+export declare function executeDeploy(actions: DeployAction[], dryRun: boolean, verbose: boolean, home: string, deps?: DeployDependencies, signal?: AbortSignal): Promise<{
     succeeded: number;
     failed: Array<{
         action: DeployAction;

package/dist/src/core/deploy.js

@@ -9,7 +9,7 @@ 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, registryDirPath, registerDeployment, verifyDeployment, } from "./ownership.js";
+import { defaultRegistryPersistence, lookupDeployment, RunRegistry, registerDeployment, registryDirPath, verifyDeployment, } from "./ownership.js";
 import { getDeployMethod, resolveAgentSkillPath } from "./resolve.js";
 import { resolveTargetTemplate } from "./runtime-paths.js";
 import { sourceAccessError, validateSkillDefinitionFile, validateSourceFile, validateSourcePath, } from "./validation.js";
@@ -21,18 +21,18 @@ async function readJsonConfigFile(filePath) {
     catch (err) {
         const code = err.code;
         if (code === "ENOENT")
-            throw new Error(`Config file not found: ${filePath}`);
+            throw new UserError("DEPLOY_FAILED", `Config file not found: ${filePath}`, { cause: err });
         throw err;
     }
     let parsed;
     try {
         parsed = JSON.parse(rawContent);
     }
-    catch {
-        throw new Error(`Config file is not valid JSON: ${filePath}`);
+    catch (err) {
+        throw new UserError("DEPLOY_FAILED", `Config file is not valid JSON: ${filePath}`, { cause: err });
     }
     if (!isPlainObject(parsed)) {
-        throw new Error(`Config file is not a JSON object: ${filePath}`);
+        throw new UserError("DEPLOY_FAILED", `Config file is not a JSON object: ${filePath}`);
     }
     return parsed;
 }
@@ -324,7 +324,7 @@ function planConfigPatchActions(manifest, detectedAgents, home, repo, workspace)
     }
     return actions;
 }
-export async function planDeploy(manifest, sourceDir, detectedAgents, home, repo, workspace) {
+export async function planDeploy(manifest, sourceDir, detectedAgents, home, repo, workspace, signal) {
     assertNoAntigravityPathCollisions(manifest);
     const resolvedSourceDir = path.resolve(sourceDir);
     let realRoot;
@@ -336,11 +336,15 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home, repo
     }
     const repoDir = repo ?? realRoot;
     const skillPlan = await planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home);
+    if (signal?.aborted)
+        return { actions: [], warnings: [] };
     const actions = [
         ...skillPlan.actions,
         ...(await planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repoDir, workspace)),
         ...planConfigPatchActions(manifest, detectedAgents, home, repoDir, workspace),
     ];
+    if (signal?.aborted)
+        return { actions: [], warnings: [] };
     const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, manifest.permissions ?? [], sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repoDir, manifest.agentDefinitions ?? [], workspace, manifest.hooks ?? [], manifest.executionConfigs ?? []);
     actions.push(...adapterResult.actions);
     const warnings = [
@@ -355,12 +359,32 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home, repo
     }
     return { actions, warnings };
 }
-export async function executeDeploy(actions, dryRun, verbose, home, deps = {}) {
+export async function executeDeploy(actions, dryRun, verbose, home, deps = {}, signal) {
     let succeeded = 0;
     const failed = [];
     const planned = [];
+    const runRegistry = new RunRegistry(deps.registry ?? defaultRegistryPersistence);
+    const depsWithRegistry = {
+        ...deps,
+        registry: runRegistry,
+    };
+    if (!dryRun) {
+        try {
+            await runRegistry.preflight(home);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                succeeded: 0,
+                failed: actions.map((action) => ({ action, error: message })),
+                planned,
+            };
+        }
+    }
     for (const action of actions) {
-        const result = await dispatchDeployAction(action, dryRun, verbose, home, planned, deps);
+        if (signal?.aborted)
+            break;
+        const result = await dispatchDeployAction(action, dryRun, verbose, home, planned, depsWithRegistry);
         if (result.error === null) {
             succeeded++;
         }
@@ -368,6 +392,9 @@ export async function executeDeploy(actions, dryRun, verbose, home, deps = {}) {
             failed.push({ action, error: result.error });
         }
     }
+    if (!dryRun) {
+        await runRegistry.flush(home);
+    }
     return { succeeded, failed, planned };
 }
 async function dispatchDeployAction(action, dryRun, verbose, home, planned, deps) {
@@ -434,7 +461,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 UserError("DEPLOY_FAILED", `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, {
@@ -592,7 +619,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 UserError("DEPLOY_FAILED", `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);
@@ -686,7 +713,7 @@ async function deployFrontmatterEmit(action, dryRun, verbose, home, planned, dep
             (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`);
+            throw new UserError("DEPLOY_FAILED", `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);
@@ -735,12 +762,12 @@ async function validateSkillContract(source, skillPath) {
     catch (err) {
         const code = err.code;
         if (code === "ENOENT") {
-            throw new UserError("DEPLOY_FAILED", `Skill "${skillPath}" source not found: ${source}`);
+            throw new UserError("DEPLOY_FAILED", `Skill "${skillPath}" source not found: ${source}`, { cause: err });
         }
         if (code === "EACCES" || code === "EPERM") {
-            throw new UserError("DEPLOY_FAILED", `Permission denied accessing skill "${skillPath}" source: ${source}`);
+            throw new UserError("DEPLOY_FAILED", `Permission denied accessing skill "${skillPath}" source: ${source}`, { cause: err });
         }
-        throw new UserError("DEPLOY_FAILED", `Cannot access skill "${skillPath}" source: ${source}`);
+        throw new UserError("DEPLOY_FAILED", `Cannot access skill "${skillPath}" source: ${source}`, { cause: err });
     }
     if (!stat.isDirectory()) {
         throw new UserError("DEPLOY_FAILED", `Skill "${skillPath}" source is not a directory: ${source}`);
@@ -751,9 +778,9 @@ async function validateSkillContract(source, skillPath) {
     catch (err) {
         const code = err.code;
         if (code === "EACCES" || code === "EPERM") {
-            throw new UserError("DEPLOY_FAILED", `Permission denied reading skill directory "${skillPath}": ${source}`);
+            throw new UserError("DEPLOY_FAILED", `Permission denied reading skill directory "${skillPath}": ${source}`, { cause: err });
         }
-        throw new UserError("DEPLOY_FAILED", `Cannot read skill directory "${skillPath}": ${source}`);
+        throw new UserError("DEPLOY_FAILED", `Cannot read skill directory "${skillPath}": ${source}`, { cause: err });
     }
     try {
         await access(path.join(source, "SKILL.md"), constants.R_OK);
@@ -761,9 +788,9 @@ async function validateSkillContract(source, skillPath) {
     catch (err) {
         const code = err.code;
         if (code === "EACCES" || code === "EPERM") {
-            throw new UserError("DEPLOY_FAILED", `Permission denied reading SKILL.md in skill "${skillPath}": ${source}`);
+            throw new UserError("DEPLOY_FAILED", `Permission denied reading SKILL.md in skill "${skillPath}": ${source}`, { cause: err });
         }
-        throw new UserError("DEPLOY_FAILED", `Skill "${skillPath}" source is missing SKILL.md: ${source}`);
+        throw new UserError("DEPLOY_FAILED", `Skill "${skillPath}" source is missing SKILL.md: ${source}`, { cause: err });
     }
     await validateSkillDefinitionFile(path.join(source, "SKILL.md"), skillPath);
 }
@@ -838,7 +865,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 UserError("DEPLOY_FAILED", `Target "${targetPath}" exists but is not managed by inception-engine - refusing to overwrite`);
     }
     const backupPath = `${targetPath}.inception-backup`;
     if (verbose) {

package/dist/src/core/init.d.ts

@@ -5,5 +5,6 @@ export interface InitOptions {
     dryRun: boolean;
     force: boolean;
     verbose: boolean;
+    signal?: AbortSignal;
 }
 export declare function runInit(options: InitOptions): Promise<number>;

package/dist/src/core/init.js

@@ -1,9 +1,10 @@
-import { access, readdir, readFile, writeFile } from "node:fs/promises";
+import { access, readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 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 { writeFileAtomic } from "./atomic-write.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.
@@ -78,7 +79,9 @@ async function hasAntigravityMcpFrontmatter(absPath) {
     return (Object.hasOwn(attributes, "mcp-servers") ||
         Object.hasOwn(attributes, "mcpServers"));
 }
-async function findSkillDirs(baseDir, dir, found) {
+async function findSkillDirs(baseDir, dir, found, signal) {
+    if (signal?.aborted)
+        return;
     let entries;
     try {
         entries = await readdir(dir, { withFileTypes: true, encoding: "utf-8" });
@@ -100,8 +103,10 @@ async function findSkillDirs(baseDir, dir, found) {
         return;
     }
     for (const entry of entries) {
+        if (signal?.aborted)
+            return;
         if (entry.isDirectory() && !entry.name.startsWith(".")) {
-            await findSkillDirs(baseDir, path.join(dir, entry.name), found);
+            await findSkillDirs(baseDir, path.join(dir, entry.name), found, signal);
         }
     }
 }
@@ -152,7 +157,9 @@ function deriveAgentRulesName(relPath, fileName) {
     }
     return rawName;
 }
-async function scanDirForMarkdown(dir, baseDir, skillDirRelPaths, seen, candidates) {
+async function scanDirForMarkdown(dir, baseDir, skillDirRelPaths, seen, candidates, signal) {
+    if (signal?.aborted)
+        return;
     let entries;
     try {
         entries = await readdir(dir, { withFileTypes: true, encoding: "utf-8" });
@@ -177,12 +184,12 @@ async function scanDirForMarkdown(dir, baseDir, skillDirRelPaths, seen, candidat
         candidates.push({ relPath, name, defaultAgents: [] });
     }
 }
-async function findAgentRulesCandidates(baseDir, skillDirRelPaths) {
+async function findAgentRulesCandidates(baseDir, skillDirRelPaths, signal) {
     const candidates = [];
     const seen = new Set();
-    await scanDirForMarkdown(baseDir, baseDir, skillDirRelPaths, seen, candidates);
+    await scanDirForMarkdown(baseDir, baseDir, skillDirRelPaths, seen, candidates, signal);
     for (const subdir of AGENT_RULES_SUBDIRS) {
-        await scanDirForMarkdown(path.join(baseDir, subdir), baseDir, skillDirRelPaths, seen, candidates);
+        await scanDirForMarkdown(path.join(baseDir, subdir), baseDir, skillDirRelPaths, seen, candidates, signal);
     }
     // Promote .github/copilot-instructions.md to the native copilot-repo scope.
     // The general scanDirForMarkdown pass above picks it up via AGENT_RULES_SUBDIRS
@@ -196,6 +203,8 @@ async function findAgentRulesCandidates(baseDir, skillDirRelPaths) {
     // Discover .github/instructions/*.instructions.md as copilot-scoped entries.
     // These are not covered by the general scan (it only looks for .md/.markdown
     // and the stem derivation would lose the .instructions suffix).
+    if (signal?.aborted)
+        return candidates;
     const instructionsDir = path.join(baseDir, ".github", "instructions");
     let instrEntries;
     try {
@@ -383,10 +392,12 @@ async function scanDefinitionSubdir(subdir, baseDir, seen, skillDirRelPaths, age
         candidates.push({ relPath, name, suggestedAgents });
     }
 }
-async function findAgentDefinitionCandidates(baseDir, skillDirRelPaths, agentRulesRelPaths) {
+async function findAgentDefinitionCandidates(baseDir, skillDirRelPaths, agentRulesRelPaths, signal) {
     const candidates = [];
     const seen = new Set();
     for (const subdir of AGENT_DEFINITION_SUBDIRS) {
+        if (signal?.aborted)
+            break;
         await scanDefinitionSubdir(subdir, baseDir, seen, skillDirRelPaths, agentRulesRelPaths, candidates);
     }
     return candidates;
@@ -615,7 +626,7 @@ function logVerboseManifest(skills, agentRules, mcpServers, files, configs, agen
     }
 }
 export async function runInit(options) {
-    const { directory, dryRun, force, verbose } = options;
+    const { directory, dryRun, force, verbose, signal } = options;
     const agents = options.agents ?? [...AGENT_IDS];
     const agentRulesCapableAgents = agents.filter((id) => shouldInitIncludeAgent(id, "agentRules", "global"));
     const manifestPath = path.join(directory, "inception.json");
@@ -624,21 +635,27 @@ export async function runInit(options) {
         return 2;
     }
     const found = [];
-    await findSkillDirs(directory, directory, found);
+    await findSkillDirs(directory, directory, found, signal);
+    if (signal?.aborted)
+        return 0;
     if (found.length === 0) {
         logger.info("No skill directories found (looking for directories containing SKILL.md).");
     }
     const skills = buildSkills(found, agents);
     const skillNamesSeen = new Set(skills.map((s) => s.name));
     const skillDirRelPaths = new Set(found.map((f) => f.relPath));
-    const agentRulesCandidates = await findAgentRulesCandidates(directory, skillDirRelPaths);
+    const agentRulesCandidates = await findAgentRulesCandidates(directory, skillDirRelPaths, signal);
+    if (signal?.aborted)
+        return 0;
     const agentRules = buildAgentRules(agentRulesCandidates, agentRulesCapableAgents, agents, skillNamesSeen);
     const allNamesSeen = new Set([
         ...skillNamesSeen,
         ...agentRules.map((r) => r.name),
     ]);
     const agentRulesRelPaths = new Set(agentRules.map((r) => r.path));
-    const agentDefinitionCandidates = await findAgentDefinitionCandidates(directory, skillDirRelPaths, agentRulesRelPaths);
+    const agentDefinitionCandidates = await findAgentDefinitionCandidates(directory, skillDirRelPaths, agentRulesRelPaths, signal);
+    if (signal?.aborted)
+        return 0;
     const discoveredDefinitions = buildAgentDefinitions(agentDefinitionCandidates, agents, allNamesSeen);
     // Sidecar file overrides take precedence over auto-discovery
     const sidecarDefinitions = await loadAgentDefinitionsManifest(directory);
@@ -673,7 +690,7 @@ export async function runInit(options) {
         await emitDirectoryHints(directory, files.length, configs.length);
         return 0;
     }
-    await writeFile(manifestPath, json, "utf-8");
+    await writeFileAtomic(manifestPath, json);
     logger.info(`Generated ${manifestPath} with ${summarize()}.`);
     if (verbose) {
         logVerboseManifest(skills, agentRules, mcpServers, files, configs, agentDefinitions);

package/dist/src/core/ownership.d.ts

@@ -23,6 +23,30 @@ export type VerifyExpected = {
 export declare function registryPath(home: string): string;
 export declare function registryDirPath(home: string): string;
 export declare const defaultRegistryPersistence: RegistryPersistence;
+/**
+ * Per-run in-memory registry cache. Loads the registry from disk once on
+ * first access, buffers all save calls in memory, and writes to disk only
+ * when flush() is called explicitly at the end of a deploy or revert run.
+ *
+ * Implements RegistryPersistence so it can be passed as deps.registry to
+ * executeDeploy and executeRevert without touching any action-level callers.
+ */
+export declare class RunRegistry implements RegistryPersistence {
+    private cache;
+    private dirty;
+    private readonly backing;
+    constructor(backing: RegistryPersistence);
+    load(home: string): Promise<Registry>;
+    save(_home: string, registry: Registry): Promise<void>;
+    /**
+     * Validate that the registry is writable before any actions run. Writes the
+     * current (possibly empty) registry state so that a backing store failure is
+     * detected upfront, before any filesystem changes are made by deploy or
+     * revert actions. Skipped in dry-run flows.
+     */
+    preflight(home: string): Promise<void>;
+    flush(home: string): Promise<void>;
+}
 export type RegisterEntry = Omit<SkillDirRegistryEntry, "deployed"> | Omit<FileWriteRegistryEntry, "deployed"> | Omit<ConfigPatchRegistryEntry, "deployed"> | Omit<FrontmatterEmitRegistryEntry, "deployed">;
 export declare function registerDeployment(home: string, targetPath: string, entry: RegisterEntry, persistence?: RegistryPersistence): Promise<void>;
 export declare function unregisterDeployment(home: string, targetPath: string, persistence?: RegistryPersistence): Promise<void>;

package/dist/src/core/ownership.js

@@ -1,6 +1,8 @@
-import { chmod, lstat, mkdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
+import { UserError } from "../errors.js";
 import { RegistrySchema, } from "../schemas/registry.js";
+import { writeFileAtomic } from "./atomic-write.js";
 const REGISTRY_DIR = ".inception-engine";
 const REGISTRY_FILE = "registry.json";
 export function registryPath(home) {
@@ -13,7 +15,7 @@ async function assertSafeRegistryStoragePath(targetPath, label) {
     try {
         const stat = await lstat(targetPath);
         if (stat.isSymbolicLink()) {
-            throw new Error(`Refusing to use ${label} symlink: ${targetPath}`);
+            throw new UserError("DEPLOY_FAILED", `Refusing to use ${label} symlink: ${targetPath}`);
         }
     }
     catch (err) {
@@ -42,13 +44,55 @@ async function saveRegistry(home, registry) {
     await setDirectoryPermissions(dir);
     const filePath = registryPath(home);
     await assertSafeRegistryStoragePath(filePath, "registry file");
-    await writeFile(filePath, `${JSON.stringify(registry, null, 2)}\n`);
+    await writeFileAtomic(filePath, `${JSON.stringify(registry, null, 2)}\n`);
     await setFilePermissions(filePath);
 }
 export const defaultRegistryPersistence = {
     load: loadRegistry,
     save: saveRegistry,
 };
+/**
+ * Per-run in-memory registry cache. Loads the registry from disk once on
+ * first access, buffers all save calls in memory, and writes to disk only
+ * when flush() is called explicitly at the end of a deploy or revert run.
+ *
+ * Implements RegistryPersistence so it can be passed as deps.registry to
+ * executeDeploy and executeRevert without touching any action-level callers.
+ */
+export class RunRegistry {
+    cache = null;
+    dirty = false;
+    backing;
+    constructor(backing) {
+        this.backing = backing;
+    }
+    async load(home) {
+        if (this.cache === null) {
+            this.cache = await this.backing.load(home);
+        }
+        return this.cache;
+    }
+    async save(_home, registry) {
+        this.cache = registry;
+        this.dirty = true;
+    }
+    /**
+     * Validate that the registry is writable before any actions run. Writes the
+     * current (possibly empty) registry state so that a backing store failure is
+     * detected upfront, before any filesystem changes are made by deploy or
+     * revert actions. Skipped in dry-run flows.
+     */
+    async preflight(home) {
+        const registry = await this.load(home);
+        await this.backing.save(home, registry);
+    }
+    async flush(home) {
+        if (this.dirty && this.cache !== null) {
+            await this.backing.save(home, this.cache);
+            this.dirty = false;
+        }
+    }
+}
 /**
  * Restrict access to the state directory regardless of umask.
  * On Windows, the OS inherits ACLs from the parent directory — no-op is correct.

package/dist/src/core/preflight.d.ts

@@ -3,4 +3,4 @@ export interface PreflightWarning {
     kind: "policy" | "config-authority" | "info" | "precedence" | "budget";
     message: string;
 }
-export declare function runPreflight(options: CliOptions, manifest: Manifest, home: string, detectedAgents: AgentId[]): Promise<PreflightWarning[]>;
+export declare function runPreflight(options: CliOptions, manifest: Manifest, home: string, detectedAgents: AgentId[], signal?: AbortSignal): Promise<PreflightWarning[]>;

package/dist/src/core/preflight.js

@@ -312,13 +312,21 @@ async function collectAgentWarnings(agentId, manifest, home) {
     }
     return warnings;
 }
-export async function runPreflight(options, manifest, home, detectedAgents) {
+export async function runPreflight(options, manifest, home, detectedAgents, signal) {
     const warnings = [];
     for (const agentId of detectedAgents) {
+        if (signal?.aborted)
+            return warnings;
         warnings.push(...(await collectAgentWarnings(agentId, manifest, home)));
     }
+    if (signal?.aborted)
+        return warnings;
     warnings.push(...detectCapabilityPlanningWarnings(manifest, detectedAgents));
+    if (signal?.aborted)
+        return warnings;
     warnings.push(...detectInstructionPrecedence(detectedAgents, manifest));
+    if (signal?.aborted)
+        return warnings;
     warnings.push(...(await detectInstructionBudgetRisk(detectedAgents, manifest, options.directory)));
     return warnings;
 }

package/dist/src/core/resolve.js

@@ -89,7 +89,7 @@ export function resolveAgentSkillPathFor(agent, skillName, home, platform) {
         const hint = agent.skillsSurfaceKind?.kind === "shared-via"
             ? ` Deploy skills via the "${agent.skillsSurfaceKind.via}" target, which covers this agent natively.`
             : "";
-        throw new Error(`Agent "${agent.id}" does not have a skills deployment path.${hint}`);
+        throw new UserError("RESOLVE_FAILED", `Agent "${agent.id}" does not have a skills deployment path.${hint}`);
     }
     return resolvePlaceholders(agent.skills[platform], skillName, home);
 }

package/dist/src/core/revert.d.ts

@@ -2,7 +2,7 @@ import type { AgentId, Manifest, PlannedChange, RevertAction } from "../types.ts
 import { type RegistryPersistence } from "./ownership.ts";
 export declare function planRevert(manifest: Manifest, detectedAgents: AgentId[], home: string, repo?: string): RevertAction[];
 export declare function planRevertAll(manifest: Manifest, home: string, repo?: string): RevertAction[];
-export declare function executeRevert(actions: RevertAction[], dryRun: boolean, verbose: boolean, home: string, deps?: RevertDependencies): Promise<{
+export declare function executeRevert(actions: RevertAction[], dryRun: boolean, verbose: boolean, home: string, deps?: RevertDependencies, signal?: AbortSignal): Promise<{
     succeeded: number;
     skipped: number;
     failed: Array<{