@evomap/evolver-mcp 2.0.0-beta.17 → 2.0.0-beta.19

package/dist/installerShared.js

@@ -0,0 +1,99 @@
+import { lstatSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+/** Default command used by runtimes that support a SessionStart hook. The flag enables session-id capture. */
+export const DEFAULT_HOOK_COMMAND = 'evolver inject session-start --hook-stdin';
+export const DEFAULT_PROMPT_RECALL_HOOK_COMMAND = 'evolver inject prompt-recall --hook-stdin';
+export const EVOLVER_HOOK_STATUS = 'evolver-managed-hook';
+const LEGACY_EVOLVER_HOOK_STATUS = 'Loading Evolver memory';
+function isObj(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const LEGACY_NODE_COMMAND = /^"?node(?:\.exe)?"?\s+/i;
+const LEGACY_EVOLVER_SCRIPT_BASENAME = /(?:^|[\\/'"\s])(?:evolver-session-start|evolver-session-end|evolver-signal-detect|evolver-task-recall|evolver-daemon-start)\.js(?=$|[\\/'"\s])/i;
+const LEGACY_V2_CLI_HOOK_COMMAND = /^"?evolver(?:\.cmd|\.exe)?"?\s+inject\s+(?:session-start|prompt-recall)(?:\s|$)/i;
+function isKnownEvolverHookCommand(command) {
+    const trimmed = command.trim();
+    return LEGACY_V2_CLI_HOOK_COMMAND.test(trimmed)
+        || (LEGACY_NODE_COMMAND.test(trimmed) && LEGACY_EVOLVER_SCRIPT_BASENAME.test(trimmed));
+}
+/** Bind custom-command ownership to that exact command without adding undocumented hook-schema fields. */
+export function evolverManagedHookStatus(command) {
+    if (isKnownEvolverHookCommand(command))
+        return EVOLVER_HOOK_STATUS;
+    const commandTag = createHash('sha256').update(command, 'utf8').digest('hex').slice(0, 16);
+    return `${EVOLVER_HOOK_STATUS} [evolver:${commandTag}]`;
+}
+function legacyEvolverManagedHookStatus(command) {
+    const currentStatus = evolverManagedHookStatus(command);
+    return `${LEGACY_EVOLVER_HOOK_STATUS}${currentStatus.slice(EVOLVER_HOOK_STATUS.length)}`;
+}
+const NO_MANAGED_HOOK_COMMANDS = new Set();
+const isEvolverHandler = (handler, trustManagedStatus, managedCommands) => {
+    if (!isObj(handler) || typeof handler['command'] !== 'string')
+        return false;
+    const command = handler['command'];
+    return isKnownEvolverHookCommand(command)
+        || (trustManagedStatus && (managedCommands.has(command)
+            || handler['statusMessage'] === evolverManagedHookStatus(command)
+            || handler['statusMessage'] === legacyEvolverManagedHookStatus(command)));
+};
+/** Remove only Evolver-owned handlers, retaining user handlers that share the same matcher group. */
+export function stripEvolverHookEntries(entries, trustManagedStatus = false, managedCommands = NO_MANAGED_HOOK_COMMANDS) {
+    let changed = false;
+    const keptEntries = [];
+    for (const entry of entries) {
+        if (!isObj(entry)) {
+            keptEntries.push(entry);
+            continue;
+        }
+        const handlers = entry['hooks'];
+        if (!Array.isArray(handlers)) {
+            if (isEvolverHandler(entry, trustManagedStatus, managedCommands))
+                changed = true;
+            else
+                keptEntries.push(entry);
+            continue;
+        }
+        const keptHandlers = handlers.filter((handler) => !isEvolverHandler(handler, trustManagedStatus, managedCommands));
+        if (keptHandlers.length === handlers.length) {
+            keptEntries.push(entry);
+            continue;
+        }
+        changed = true;
+        if (keptHandlers.length > 0)
+            keptEntries.push({ ...entry, hooks: keptHandlers });
+    }
+    return { changed, entries: keptEntries };
+}
+export class SymlinkRefusedError extends Error {
+    constructor(label, path) {
+        super(`[setup-hooks] refusing to operate: ${label} ${path} is a symbolic link — evolver will not follow symlinks for adapter-owned paths (a hostile workspace could redirect writes/unlinks outside the project). Replace it with a real directory/file and rerun.`);
+        this.name = 'SymlinkRefusedError';
+    }
+}
+export class UnparseableConfigError extends Error {
+    constructor(label, path, owner = 'Claude Code') {
+        super(`[setup-hooks] refusing to overwrite ${label} (${path}): the file exists and is non-empty but is not valid JSON. This is ${owner}'s own shared config; merging into it would replace the whole file and could wipe its contents. Fix or remove the corrupt file, then rerun.`);
+        this.name = 'UnparseableConfigError';
+    }
+}
+export class EmptySharedConfigError extends Error {
+    constructor(label, path, owner = 'Claude Code') {
+        super(`[setup-hooks] refusing to overwrite ${label} (${path}): the file exists but is empty or contains only whitespace. ${owner} may be in the middle of a truncating write, and treating it as fresh config could wipe shared config data. Fix the empty file or retry after ${owner} finishes writing it.`);
+        this.name = 'EmptySharedConfigError';
+    }
+}
+/** Refuse to read or write through a symlink at an adapter-owned path. */
+export function assertNotSymlink(path, label) {
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (stat.isSymbolicLink())
+        throw new SymlinkRefusedError(label, path);
+}

package/dist/jsonMcpInstaller.d.ts

@@ -1,9 +1,11 @@
 import type { InjectionPlan, McpServerCmd, RuntimeId } from './injection.js';
-import { type InstallOptions, type InstallResult, type UninstallOptions } from './installer.js';
+import { type InstallOptions, type InstallResult, type UninstallOptions } from './installerShared.js';
 type BeforeReplaceHook = (path: string) => void;
 export declare function _setJsonMcpBeforeReplaceHookForTest(hook?: BeforeReplaceHook): void;
 export declare function _setJsonMcpAfterReplaceHookForTest(hook?: BeforeReplaceHook): void;
+export declare function _setJsonMcpAfterSharedFileValidateHookForTest(hook?: BeforeReplaceHook): void;
 export declare function _setJsonMcpBeforeBackupRemoveHookForTest(hook?: BeforeReplaceHook): void;
+export declare function _setJsonMcpBeforeSharedFileCommitHookForTest(hook?: BeforeReplaceHook): void;
 export interface JsonMcpRuntimeSpec {
     runtime: 'opencode' | 'kiro';
     configPath(opts: JsonMcpPathOptions): string;
@@ -70,6 +72,8 @@ export declare class McpConfigChangedError extends Error {
 export declare class McpServerValidationError extends Error {
     constructor(message: string);
 }
+declare function retrySharedConfigTransaction<T>(operation: () => T): T;
+export declare const _retrySharedConfigTransactionForTest: typeof retrySharedConfigTransaction;
 export declare function installJsonMcpRuntime(spec: JsonMcpRuntimeSpec, plan: InjectionPlan, opts: InstallOptions): InstallResult;
 export declare function uninstallJsonMcpRuntime(spec: JsonMcpRuntimeSpec, runtime: RuntimeId, opts: UninstallOptions): InstallResult;
 export {};

package/dist/jsonMcpInstaller.js

@@ -1,24 +1,34 @@
-import { chmodSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { chmodSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { EmptySharedConfigError, SymlinkRefusedError, UnparseableConfigError, } from './installer.js';
+import { EmptySharedConfigError, SymlinkRefusedError, UnparseableConfigError, } from './installerShared.js';
+import { commitSharedFile, SharedFileConflictError } from './sharedFileCommit.js';
 const CONFIG_MODE = 0o600;
 const DIR_MODE = 0o700;
 const BACKUP_VERSION = 1;
 const ENV_FILE_KEY = 'EVOLVER_ENV_FILE';
+const SHARED_CONFIG_WRITE_RETRIES = 5;
 let beforeReplaceHookForTest;
 let afterReplaceHookForTest;
+let afterSharedFileValidateHookForTest;
 let beforeBackupRemoveHookForTest;
+let beforeSharedFileCommitHookForTest;
 export function _setJsonMcpBeforeReplaceHookForTest(hook) {
     beforeReplaceHookForTest = hook;
 }
 export function _setJsonMcpAfterReplaceHookForTest(hook) {
     afterReplaceHookForTest = hook;
 }
+export function _setJsonMcpAfterSharedFileValidateHookForTest(hook) {
+    afterSharedFileValidateHookForTest = hook;
+}
 export function _setJsonMcpBeforeBackupRemoveHookForTest(hook) {
     beforeBackupRemoveHookForTest = hook;
 }
+export function _setJsonMcpBeforeSharedFileCommitHookForTest(hook) {
+    beforeSharedFileCommitHookForTest = hook;
+}
 function removeBackup(path) {
     beforeBackupRemoveHookForTest?.(path);
     rmSync(path);
@@ -361,25 +371,20 @@ function assertConfigTopologyUnchanged(runtime, safeRoot, snapshot) {
             throw new McpConfigChangedError(runtime, candidate.path);
     }
 }
-function atomicWrite(path, raw, mode, beforeRename) {
-    mkdirSync(dirname(path), { recursive: true, mode: DIR_MODE });
-    const tempPath = join(dirname(path), `.${randomUUID()}.tmp`);
-    try {
-        writeFileSync(tempPath, raw, { encoding: 'utf8', mode, flag: 'wx' });
-        chmodSync(tempPath, mode);
-        beforeRename?.();
-        renameSync(tempPath, path);
-    }
-    finally {
-        rmSync(tempPath, { force: true });
-    }
-}
 function guardedAtomicWrite(runtime, safeRoot, path, raw, mode, expectedRaw, additionalGuard) {
-    atomicWrite(path, raw, mode, () => {
-        beforeReplaceHookForTest?.(path);
-        assertSafeParents(runtime, safeRoot, path);
-        assertUnchanged(runtime, path, expectedRaw);
-        additionalGuard?.();
+    beforeReplaceHookForTest?.(path);
+    assertSafeParents(runtime, safeRoot, path);
+    assertUnchanged(runtime, path, expectedRaw);
+    additionalGuard?.();
+    commitSharedFile({
+        path,
+        expectedRaw: expectedRaw ?? undefined,
+        nextRaw: raw,
+        mode,
+        ...(afterSharedFileValidateHookForTest ? { afterValidateForTest: () => afterSharedFileValidateHookForTest?.(path) } : {}),
+        ...(beforeSharedFileCommitHookForTest
+            ? { beforeCommitForTest: () => beforeSharedFileCommitHookForTest?.(path) }
+            : {}),
     });
 }
 function guardedRemove(runtime, safeRoot, path, expectedRaw, additionalGuard) {
@@ -387,7 +392,15 @@ function guardedRemove(runtime, safeRoot, path, expectedRaw, additionalGuard) {
     assertSafeParents(runtime, safeRoot, path);
     assertUnchanged(runtime, path, expectedRaw);
     additionalGuard?.();
-    rmSync(path);
+    commitSharedFile({
+        path,
+        expectedRaw: expectedRaw ?? undefined,
+        nextRaw: undefined,
+        ...(afterSharedFileValidateHookForTest ? { afterValidateForTest: () => afterSharedFileValidateHookForTest?.(path) } : {}),
+        ...(beforeSharedFileCommitHookForTest
+            ? { beforeCommitForTest: () => beforeSharedFileCommitHookForTest?.(path) }
+            : {}),
+    });
 }
 function backupPath(configPath) {
     return `${configPath}.evolver-backup.json`;
@@ -552,7 +565,24 @@ function looksLikeEnvFilePointer(value) {
         || /^[.~$%]/.test(value)
         || /\.(?:env|dotenv)(?:$|[._-])/i.test(value);
 }
+function retrySharedConfigTransaction(operation) {
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            return operation();
+        }
+        catch (error) {
+            if (!(error instanceof SharedFileConflictError)
+                || error.recoveryPath !== undefined
+                || attempt >= SHARED_CONFIG_WRITE_RETRIES)
+                throw error;
+        }
+    }
+}
+export const _retrySharedConfigTransactionForTest = retrySharedConfigTransaction;
 export function installJsonMcpRuntime(spec, plan, opts) {
+    return retrySharedConfigTransaction(() => installJsonMcpRuntimeOnce(spec, plan, opts));
+}
+function installJsonMcpRuntimeOnce(spec, plan, opts) {
     validateServer(opts.server);
     const resolution = resolveInstallRuntimeConfig(spec, opts);
     const { configPath, safeRoot } = resolution;
@@ -707,6 +737,9 @@ function withoutEvolver(data, containerKey) {
     return next;
 }
 export function uninstallJsonMcpRuntime(spec, runtime, opts) {
+    return retrySharedConfigTransaction(() => uninstallJsonMcpRuntimeOnce(spec, runtime, opts));
+}
+function uninstallJsonMcpRuntimeOnce(spec, runtime, opts) {
     const resolution = resolveUninstallRuntimeConfig(spec, opts);
     const { configPath, safeRoot } = resolution;
     assertSafeParents(spec.runtime, safeRoot, configPath);

package/dist/kiroInstaller.d.ts

@@ -1,10 +1,10 @@
-import type { InstallOptions } from './installer.js';
+import type { InstallOptions } from './installerShared.js';
 import { type JsonMcpRuntimeResolution, type JsonMcpRuntimeSpec } from './jsonMcpInstaller.js';
 type KiroPathOptions = Pick<InstallOptions, 'configRoot' | 'scope' | 'homeDir' | 'kiroHome'>;
 /** Resolve only Kiro's base mcp.json contract; custom agent JSON is intentionally out of scope. */
 export declare function resolveKiroConfig(opts: KiroPathOptions): JsonMcpRuntimeResolution;
 export declare const KIRO_SPEC: JsonMcpRuntimeSpec;
 export declare function kiroConfigRoot({ configRoot, scope, homeDir, kiroHome }: Pick<InstallOptions, 'configRoot' | 'scope' | 'homeDir' | 'kiroHome'>): string;
-export declare const installKiro: (plan: import("./injection.js").InjectionPlan, opts: InstallOptions) => import("./installer.js").InstallResult;
-export declare const uninstallKiro: (runtime: import("./injection.js").RuntimeId, opts: import("./installer.js").UninstallOptions) => import("./installer.js").InstallResult;
+export declare const installKiro: (plan: import("./injection.js").InjectionPlan, opts: InstallOptions) => import("./installerShared.js").InstallResult;
+export declare const uninstallKiro: (runtime: import("./injection.js").RuntimeId, opts: import("./installerShared.js").UninstallOptions) => import("./installerShared.js").InstallResult;
 export {};

package/dist/opencodeInstaller.d.ts

@@ -1,4 +1,4 @@
-import type { InstallOptions } from './installer.js';
+import type { InstallOptions } from './installerShared.js';
 import { type JsonMcpRuntimeResolution, type JsonMcpRuntimeSpec } from './jsonMcpInstaller.js';
 type OpenCodePathOptions = Pick<InstallOptions, 'configRoot' | 'scope' | 'homeDir' | 'xdgConfigHome' | 'opencodeConfig' | 'opencodeConfigDir'>;
 type OpenCodeManagedPathOptions = Pick<InstallOptions, 'opencodePlatform' | 'opencodeProgramData' | 'opencodeUsername'>;
@@ -13,6 +13,6 @@ export declare function resolveOpenCodeManagedPreferencePaths(opts?: OpenCodeMan
  */
 export declare function resolveOpenCodeConfig(opts: OpenCodePathOptions): JsonMcpRuntimeResolution;
 export declare const OPENCODE_SPEC: JsonMcpRuntimeSpec;
-export declare const installOpenCode: (plan: import("./injection.js").InjectionPlan, opts: InstallOptions) => import("./installer.js").InstallResult;
-export declare const uninstallOpenCode: (runtime: import("./injection.js").RuntimeId, opts: import("./installer.js").UninstallOptions) => import("./installer.js").InstallResult;
+export declare const installOpenCode: (plan: import("./injection.js").InjectionPlan, opts: InstallOptions) => import("./installerShared.js").InstallResult;
+export declare const uninstallOpenCode: (runtime: import("./injection.js").RuntimeId, opts: import("./installerShared.js").UninstallOptions) => import("./installerShared.js").InstallResult;
 export {};

package/dist/proxyClient.js

@@ -1,4 +1,5 @@
 import { lstatSync, readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 export class EvolverProxyClient {
@@ -51,7 +52,11 @@ export class EvolverProxyClient {
         });
     }
     submitAsset(asset) {
-        return this.submitAssetBundle({ assets: [asset] });
+        // MCP publishing remains durable and outage-tolerant; the bare route is reserved for V1 synchronous callers.
+        return this.call('POST', '/asset/submit?mode=async', this.modeBoundBody({
+            assets: [asset],
+            request_id: randomUUID(),
+        }));
     }
     submitAssetBundle(bundle) {
         return this.call('POST', '/asset/submit', this.modeBoundBody(bundle));
@@ -221,12 +226,7 @@ function expectedHubModeFromEnv(env) {
     return value === 'public' || value === 'private' ? value : undefined;
 }
 function readProxySettings(env, allowDefaultHome) {
-    const explicitPath = env['EVOLVER_PROXY_SETTINGS_FILE']?.trim();
-    const settingsDir = env['EVOLVER_SETTINGS_DIR']?.trim();
-    const homeDir = env['HOME']?.trim() || (allowDefaultHome ? homedir() : '');
-    const settingsPath = explicitPath
-        || (settingsDir ? join(settingsDir, 'settings.json') : undefined)
-        || (homeDir ? join(homeDir, '.evolver', 'settings.json') : undefined);
+    const settingsPath = resolveProxySettingsPath(env, allowDefaultHome);
     if (!settingsPath)
         return undefined;
     try {
@@ -244,6 +244,16 @@ function readProxySettings(env, allowDefaultHome) {
         return undefined;
     }
 }
+function resolveProxySettingsPath(env, allowDefaultHome) {
+    const explicit = env['EVOLVER_PROXY_SETTINGS_FILE']?.trim();
+    if (explicit)
+        return explicit;
+    const settingsDir = env['EVOLVER_SETTINGS_DIR']?.trim();
+    if (settingsDir)
+        return join(settingsDir, 'settings.json');
+    const homeDir = env['HOME']?.trim() || (allowDefaultHome ? homedir() : '');
+    return homeDir ? join(homeDir, '.evolver', 'settings.json') : undefined;
+}
 function isLoopbackHttpUrl(raw) {
     try {
         const url = new URL(raw);

package/dist/sharedFileCommit.d.ts

@@ -0,0 +1,20 @@
+import { linkSync } from 'node:fs';
+export interface SharedFileCommitOptions {
+    path: string;
+    expectedRaw: string | undefined;
+    nextRaw: string | undefined;
+    mode?: number;
+    beforeCommitForTest?: () => void;
+    afterValidateForTest?: () => void;
+    afterDisplaceForTest?: (displacedPath: string) => void;
+    beforePublishForTest?: () => void;
+    linkForTest?: typeof linkSync;
+}
+export declare class SharedFileConflictError extends Error {
+    readonly recoveryPath?: string | undefined;
+    constructor(path: string, recoveryPath?: string | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/** Commits only if the target bytes still match the caller's snapshot. */
+export declare function commitSharedFile(options: SharedFileCommitOptions): void;

package/dist/sharedFileCommit.js

@@ -0,0 +1,256 @@
+import { chmodSync, closeSync, constants as fsConstants, copyFileSync, existsSync, linkSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+export class SharedFileConflictError extends Error {
+    recoveryPath;
+    constructor(path, recoveryPath, options) {
+        super(recoveryPath
+            ? `Shared config changed during commit: ${path}; conflicting bytes preserved at ${recoveryPath}`
+            : `Shared config changed during commit: ${path}`, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.recoveryPath = recoveryPath;
+        this.name = 'SharedFileConflictError';
+    }
+}
+function tempPath(path, label) {
+    return join(dirname(path), `.${basename(path)}.evolver-${label}-${process.pid}-${randomUUID()}`);
+}
+function writePrepared(path, raw, mode) {
+    const fd = openSync(path, 'wx', mode);
+    try {
+        writeFileSync(fd, raw, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+    chmodSync(path, mode);
+}
+function removeIfPresent(path) {
+    if (!path)
+        return;
+    try {
+        unlinkSync(path);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}
+function publishNoClobber(source, target, linkFile = linkSync) {
+    try {
+        linkFile(source, target);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'EPERM' && code !== 'EACCES' && code !== 'ENOTSUP' && code !== 'EOPNOTSUPP' && code !== 'EXDEV') {
+            throw error;
+        }
+        copyFileSync(source, target, fsConstants.COPYFILE_EXCL);
+    }
+}
+function snapshotNoClobber(source, snapshot, linkFile = linkSync) {
+    try {
+        linkFile(source, snapshot);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'EPERM' && code !== 'EACCES' && code !== 'ENOTSUP' && code !== 'EOPNOTSUPP' && code !== 'EXDEV') {
+            throw error;
+        }
+        copyFileSync(source, snapshot, fsConstants.COPYFILE_EXCL);
+    }
+}
+function restoreNoClobber(displaced, target, linkFile = linkSync) {
+    try {
+        publishNoClobber(displaced, target, linkFile);
+        unlinkSync(displaced);
+        return undefined;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EEXIST')
+            return displaced;
+        if (code === 'EPERM' || code === 'EACCES' || code === 'ENOTSUP' || code === 'EOPNOTSUPP' || code === 'EXDEV') {
+            try {
+                copyFileSync(displaced, target, fsConstants.COPYFILE_EXCL);
+                unlinkSync(displaced);
+                return undefined;
+            }
+            catch (copyError) {
+                if (copyError.code === 'EEXIST')
+                    return displaced;
+                throw new AggregateError([err, copyError], `Unable to restore shared config at ${target}`);
+            }
+        }
+        throw err;
+    }
+}
+function fileVersion(path) {
+    const stat = statSync(path, { bigint: true });
+    return {
+        dev: stat.dev,
+        ino: stat.ino,
+        size: stat.size,
+        mtimeNs: stat.mtimeNs,
+        ctimeNs: stat.ctimeNs,
+    };
+}
+function sameFileVersion(left, right) {
+    return left.dev === right.dev
+        && left.ino === right.ino
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs;
+}
+/** Commits only if the target bytes still match the caller's snapshot. */
+export function commitSharedFile(options) {
+    const mode = options.mode ?? 0o600;
+    const prepared = options.nextRaw === undefined ? undefined : tempPath(options.path, 'next');
+    const displaced = options.expectedRaw === undefined ? undefined : tempPath(options.path, 'previous');
+    const movedLive = options.expectedRaw === undefined ? undefined : tempPath(options.path, 'live');
+    let preserveDisplaced = false;
+    let preserveMovedLive = false;
+    let liveWasMoved = false;
+    let published = false;
+    try {
+        if (prepared)
+            writePrepared(prepared, options.nextRaw, mode);
+        options.beforeCommitForTest?.();
+        if (options.expectedRaw === undefined) {
+            if (!prepared)
+                return;
+            try {
+                publishNoClobber(prepared, options.path, options.linkForTest);
+            }
+            catch (err) {
+                if (err.code === 'EEXIST') {
+                    throw new SharedFileConflictError(options.path);
+                }
+                throw err;
+            }
+            return;
+        }
+        // Validate while the live path is still present. The no-clobber publish below then limits the unavoidable
+        // crash-only missing-path interval to the two adjacent metadata operations.
+        let versionBeforeRead;
+        let actualRaw;
+        let validatedVersion;
+        try {
+            versionBeforeRead = fileVersion(options.path);
+            actualRaw = readFileSync(options.path, 'utf8');
+            validatedVersion = fileVersion(options.path);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                throw new SharedFileConflictError(options.path);
+            }
+            throw err;
+        }
+        if (actualRaw !== options.expectedRaw) {
+            throw new SharedFileConflictError(options.path);
+        }
+        if (!sameFileVersion(versionBeforeRead, validatedVersion)) {
+            throw new SharedFileConflictError(options.path);
+        }
+        options.afterValidateForTest?.();
+        snapshotNoClobber(options.path, displaced, options.linkForTest);
+        try {
+            const liveAfterSnapshot = fileVersion(options.path);
+            if (readFileSync(options.path, 'utf8') !== options.expectedRaw
+                || liveAfterSnapshot.dev !== validatedVersion.dev
+                || liveAfterSnapshot.ino !== validatedVersion.ino
+                || liveAfterSnapshot.size !== validatedVersion.size
+                || liveAfterSnapshot.mtimeNs !== validatedVersion.mtimeNs) {
+                throw new SharedFileConflictError(options.path);
+            }
+            options.afterDisplaceForTest?.(displaced);
+            const liveBeforePublish = fileVersion(options.path);
+            if (!sameFileVersion(liveAfterSnapshot, liveBeforePublish)
+                || readFileSync(options.path, 'utf8') !== options.expectedRaw
+                || readFileSync(displaced, 'utf8') !== options.expectedRaw) {
+                throw new SharedFileConflictError(options.path);
+            }
+            options.beforePublishForTest?.();
+            renameSync(options.path, movedLive);
+            liveWasMoved = true;
+            if (readFileSync(movedLive, 'utf8') !== options.expectedRaw) {
+                const recoveryPath = restoreNoClobber(movedLive, options.path, options.linkForTest);
+                liveWasMoved = recoveryPath !== undefined;
+                preserveMovedLive = recoveryPath !== undefined;
+                throw new SharedFileConflictError(options.path, recoveryPath);
+            }
+            if (prepared) {
+                publishNoClobber(prepared, options.path);
+                removeIfPresent(prepared);
+            }
+            else {
+                unlinkSync(movedLive);
+                liveWasMoved = false;
+            }
+            if (prepared) {
+                unlinkSync(movedLive);
+                liveWasMoved = false;
+            }
+            published = true;
+            removeIfPresent(displaced);
+        }
+        catch (error) {
+            if (!published) {
+                if (liveWasMoved && movedLive !== undefined) {
+                    const recoveryPath = restoreNoClobber(movedLive, options.path, options.linkForTest);
+                    liveWasMoved = recoveryPath !== undefined;
+                    preserveMovedLive = recoveryPath !== undefined;
+                    if (recoveryPath !== undefined) {
+                        removeIfPresent(displaced);
+                        throw new SharedFileConflictError(options.path, recoveryPath, { cause: error });
+                    }
+                }
+                removeIfPresent(displaced);
+                if (error instanceof SharedFileConflictError)
+                    throw error;
+                throw new SharedFileConflictError(options.path, undefined, { cause: error });
+            }
+            let recoveryPath;
+            try {
+                if (prepared && existsSync(options.path)) {
+                    try {
+                        if (readFileSync(options.path, 'utf8') === options.nextRaw)
+                            removeIfPresent(options.path);
+                    }
+                    catch {
+                        // Preserve a concurrent replacement and expose the snapshot as recoveryPath.
+                    }
+                }
+                recoveryPath = restoreNoClobber(displaced, options.path, options.linkForTest);
+                preserveDisplaced = recoveryPath !== undefined;
+            }
+            catch (restoreError) {
+                preserveDisplaced = true;
+                throw new Error(`Shared config commit failed for ${options.path}; original bytes preserved at ${displaced}`, { cause: new AggregateError([error, restoreError]) });
+            }
+            throw new SharedFileConflictError(options.path, recoveryPath, { cause: error });
+        }
+    }
+    finally {
+        if (!preserveDisplaced && displaced && existsSync(displaced)) {
+            if (!existsSync(options.path)) {
+                const recoveryPath = restoreNoClobber(displaced, options.path, options.linkForTest);
+                preserveDisplaced = recoveryPath !== undefined;
+            }
+            else {
+                // Keep a displaced file only when it is the sole recovery copy of concurrent bytes.
+                try {
+                    const displacedRaw = readFileSync(displaced, 'utf8');
+                    if (displacedRaw === options.expectedRaw)
+                        removeIfPresent(displaced);
+                }
+                catch {
+                    // Preserve an unreadable displaced file instead of masking the primary result.
+                }
+            }
+        }
+        removeIfPresent(prepared);
+        if (!preserveMovedLive && movedLive && existsSync(movedLive)) {
+            removeIfPresent(movedLive);
+        }
+    }
+}

package/dist/stdio.js

@@ -9,6 +9,7 @@ import { buildEvolverPrimer } from './primer.js';
 import { EvolverMcpServer, UnknownToolError } from './server.js';
 import { reachableProxyClientFromEnv } from './proxyClient.js';
 import { loadEnvFileFromEnvOrThrow } from './envFile.js';
+import { bootstrap } from '@evomap/evolver-core';
 try {
     loadEnvFileFromEnvOrThrow(process.env);
 }
@@ -16,6 +17,8 @@ catch {
     process.stderr.write('[evolver-mcp] fatal: failed to load EVOLVER_ENV_FILE\n');
     process.exit(1);
 }
+// Emit deprecation warnings for any V1 env vars still present in the environment.
+bootstrap.checkV1EnvCompat(process.env);
 const store = new assetstore.LocalJsonlProvider(events.assetsDir());
 const mailboxPath = process.env['EVOLVER_MCP_MAILBOX'] ?? join(events.evomapHome(), 'mailbox', 'mcp.db');
 mkdirSync(dirname(mailboxPath), { recursive: true });

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@evomap/evolver-mcp",
-  "version": "2.0.0-beta.17",
+  "version": "2.0.0-beta.19",
   "private": false,
   "type": "module",
+  "engines": {
+    "node": "^22.13.0 || >=23.4.0"
+  },
   "description": "Evolver MCP server (agent 工具发现入口)",
   "bin": {
     "evolver-mcp": "./dist/stdio.js"
@@ -20,7 +23,7 @@
     }
   },
   "dependencies": {
-    "@evomap/evolver-core": "2.0.0-beta.17",
+    "@evomap/evolver-core": "2.0.0-beta.19",
     "smol-toml": "^1.6.1"
   },
   "repository": {