evolcore 0.0.27 → 0.0.28

package/dist/utils/cross-platform.js

@@ -6,6 +6,7 @@ import { promisify } from 'util';
 import fs from 'fs';
 import { getProcessStartTime, parseCimDate } from './process-introspect.js';
 import { decodeWindowsOutput } from './windows-output.js';
+import { resolveTrustedWindowsCmdPath } from './windows-shell-trust.js';
 const execFileAsync = promisify(execFile);
 const CLI_PROBE_FAILURE_BACKOFF_MS = 5_000;
 const CLI_PROBE_PACKAGES = {
@@ -17,9 +18,70 @@ const cliPathCache = new Map();
 const cliInstallationCache = new Map();
 const cliProbeCache = new Map();
 export const isWindows = process.platform === 'win32';
+// Keep this in sync with the Windows command-line metacharacters. The whole
+// `/c` expression is passed as one verbatim argument so paths with spaces and
+// shim-forwarded values such as `%`, `!`, `&`, and quotes stay data.
+const WINDOWS_CMD_META_RE = /([()[\]%!^"`<>&|;, *?])/g;
+function escapeWindowsCmdCommand(value) {
+    return value.replace(WINDOWS_CMD_META_RE, '^$1');
+}
+function escapeWindowsCmdArgument(value) {
+    let escaped = String(value);
+    escaped = escaped.replace(/(?=(\\+?)?)\1"/g, '$1$1\\"');
+    escaped = escaped.replace(/(?=(\\+?)?)\1$/g, '$1$1');
+    escaped = `"${escaped}"`;
+    return escaped.replace(WINDOWS_CMD_META_RE, '^$1');
+}
+/** Build one argv-based CLI launch without consulting the parent terminal. */
+export function buildCliLaunchCommand(executable, args, options = {}) {
+    const windows = options.isWindows ?? isWindows;
+    const extension = windows ? path.win32.extname(executable).toLowerCase() : '';
+    const shim = extension === '.cmd' || extension === '.bat';
+    if (!shim) {
+        return {
+            command: executable,
+            args,
+            resolvedPath: executable,
+            launcherKind: 'native-exe',
+            launcherPath: executable,
+        };
+    }
+    const resolveWindowsCmd = options.resolveWindowsCmd ?? resolveTrustedWindowsCmdPath;
+    const launcherPath = resolveWindowsCmd(options.comSpec);
+    if (!launcherPath) {
+        throw Object.assign(new Error('未找到受信任的系统 cmd.exe，已拒绝启动 Windows CLI shim'), {
+            code: 'EACCES',
+            path: executable,
+        });
+    }
+    const shellCommand = [
+        escapeWindowsCmdCommand(executable),
+        ...args.map(escapeWindowsCmdArgument),
+    ].join(' ');
+    return {
+        command: launcherPath,
+        args: ['/d', '/s', '/v:off', '/c', `"${shellCommand}"`],
+        resolvedPath: executable,
+        launcherKind: extension === '.cmd' ? 'cmd-shim' : 'bat-shim',
+        launcherPath,
+        windowsVerbatimArguments: true,
+    };
+}
 /** Resolve a CLI executable without spawning where/which. */
 export function resolveProbePath(command) {
-    const pathKey = `${command}\0${process.cwd()}\0${process.env.PATH ?? ''}\0${process.env.PATHEXT ?? ''}`;
+    const extensions = isWindows
+        ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(ext => /\.(com|exe|bat|cmd)$/i.test(ext))
+        : [''];
+    return resolveProbePathWithExtensions(command, extensions, 'executable');
+}
+/** Diagnose an incomplete npm installation without ever executing its PS1 shim. */
+export function resolvePowerShellShimPath(command) {
+    if (!isWindows)
+        return null;
+    return resolveProbePathWithExtensions(command, ['.ps1'], 'powershell-shim');
+}
+function resolveProbePathWithExtensions(command, extensions, cacheKind) {
+    const pathKey = `${cacheKind}\0${command}\0${process.cwd()}\0${process.env.PATH ?? ''}\0${extensions.join(';')}`;
     const cachedPath = cliPathCache.get(pathKey);
     if (cachedPath && fs.existsSync(cachedPath))
         return cachedPath;
@@ -27,9 +89,6 @@ export function resolveProbePath(command) {
     const directories = (process.env.PATH ?? '').split(path.delimiter);
     if (isWindows)
         directories.unshift(process.cwd());
-    const extensions = isWindows
-        ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(ext => /\.(com|exe|bat|cmd)$/i.test(ext))
-        : [''];
     for (const directory of directories) {
         for (const extension of extensions) {
             const candidate = path.resolve(directory.replace(/^"|"$/g, ''), command + extension);
@@ -98,20 +157,25 @@ export function invalidateCliProbes() {
 function cliProbeTimeouts(command, options) {
     return options.timeouts?.length ? options.timeouts : command === 'codex' ? [3_000, 15_000] : [3_000];
 }
-function prepareCliProbe(command, args) {
-    const executable = resolveProbePath(command);
+function prepareCliProbe(command, args, options = {}) {
+    const executable = options.executable ?? resolveProbePath(command);
     if (!executable)
         throw Object.assign(new Error(`${command} CLI not found`), { code: 'ENOENT' });
-    const identity = `${probeInstallationIdentity(command, executable)}|${process.env.ComSpec ?? ''}`;
+    const launchCommand = buildCliLaunchCommand(executable, args);
+    const launch = launchCommand;
+    const identity = `${probeInstallationIdentity(command, executable)}|${cliFileIdentity(launch.launcherPath)}`;
     const key = JSON.stringify([command, args]);
     let entry = cliProbeCache.get(key);
     if (!entry || entry.identity !== identity || (entry.retryAt !== undefined && Date.now() >= entry.retryAt)) {
         entry = { identity };
         cliProbeCache.set(key, entry);
     }
-    const shim = isWindows && /\.(cmd|bat)$/i.test(executable);
-    return { entry, command: shim ? process.env.ComSpec ?? 'cmd.exe' : executable,
-        args: shim ? ['/d', '/s', '/c', executable, ...args] : args };
+    return {
+        entry,
+        command: launchCommand.command,
+        args: launchCommand.args,
+        launch,
+    };
 }
 function failCliProbe(entry, error) {
     entry.error = error;
@@ -119,7 +183,7 @@ function failCliProbe(entry, error) {
     throw error;
 }
 export function probeCliSync(command, args, options = {}) {
-    const request = prepareCliProbe(command, args);
+    const request = prepareCliProbe(command, args, options);
     if (request.entry.output !== undefined)
         return request.entry.output;
     if (request.entry.error !== undefined)
@@ -127,10 +191,14 @@ export function probeCliSync(command, args, options = {}) {
     for (const [index, timeout] of cliProbeTimeouts(command, options).entries()) {
         const startedAt = Date.now();
         try {
-            return request.entry.output = execFileSync(request.command, request.args, { encoding: 'utf8', timeout, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+            return request.entry.output = execFileSync(request.command, request.args, {
+                encoding: 'utf8', timeout, windowsHide: true,
+                windowsVerbatimArguments: request.launch.windowsVerbatimArguments,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
         }
         catch (error) {
-            options.onFailure?.(args, startedAt, error, timeout);
+            options.onFailure?.(args, startedAt, error, timeout, request.launch);
             if (error.code !== 'ETIMEDOUT' || index === cliProbeTimeouts(command, options).length - 1)
                 return failCliProbe(request.entry, error);
         }
@@ -138,7 +206,7 @@ export function probeCliSync(command, args, options = {}) {
     throw new Error('CLI probe exhausted');
 }
 export async function probeCli(command, args, options = {}) {
-    const request = prepareCliProbe(command, args);
+    const request = prepareCliProbe(command, args, options);
     if (request.entry.output !== undefined)
         return request.entry.output;
     if (request.entry.error !== undefined)
@@ -151,7 +219,10 @@ export async function probeCli(command, args, options = {}) {
             const startedAt = Date.now();
             try {
                 const output = await new Promise((resolve, reject) => {
-                    const child = execFile(request.command, request.args, { encoding: 'utf8', timeout, windowsHide: true }, (error, stdout, stderr) => {
+                    const child = execFile(request.command, request.args, {
+                        encoding: 'utf8', timeout, windowsHide: true,
+                        windowsVerbatimArguments: request.launch.windowsVerbatimArguments,
+                    }, (error, stdout, stderr) => {
                         if (error) {
                             if (error.killed && error.signal === 'SIGTERM' && error.code == null)
                                 error.code = 'ETIMEDOUT';
@@ -166,7 +237,7 @@ export async function probeCli(command, args, options = {}) {
                 return request.entry.output = output;
             }
             catch (error) {
-                options.onFailure?.(args, startedAt, error, timeout);
+                options.onFailure?.(args, startedAt, error, timeout, request.launch);
                 if (error.code !== 'ETIMEDOUT' || index === timeouts.length - 1)
                     return failCliProbe(request.entry, error);
             }

package/dist/utils/npm-ops.js

@@ -8,11 +8,26 @@
  */
 import fs from 'fs';
 import path from 'path';
+import os from 'os';
 import { execFile, execFileSync } from 'child_process';
 import { promisify } from 'util';
 import { getPackageRoot } from '../paths.js';
+import { DEFAULT_RUNTIME_HOME_DIRNAME, MAIN_PACKAGE_NAME, RUNTIME_HOME_ENV, TARGET_PACKAGE_ROOT_ENV, WEB_PACKAGE_NAME, } from '../product.js';
 import { isWindows } from './cross-platform.js';
+import { withFileLock } from './atomic-write.js';
 const execFileAsync = promisify(execFile);
+function globalInstallLockPath() {
+    const home = process.env[RUNTIME_HOME_ENV] || path.join(os.homedir(), DEFAULT_RUNTIME_HOME_DIRNAME);
+    return path.join(home, 'data', 'npm-global-install.lock');
+}
+/**
+ * The restart monitor may execute from a staged copy of the package while
+ * upgrading the real installation. Keep code loading rooted at getPackageRoot
+ * but resolve install layout and local versions from the package being served.
+ */
+function targetPackageRoot() {
+    return process.env[TARGET_PACKAGE_ROOT_ENV] || getPackageRoot();
+}
 /** The preferred public registry for update checks. */
 export const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org';
 function normalizeRegistry(registry = DEFAULT_NPM_REGISTRY) {
@@ -55,7 +70,7 @@ function resolveNpmInvocation() {
  * default. A command failure is handled separately by using the public source
  * directly, so a broken npm config cannot leave the upgrade without a retry.
  */
-async function resolveUpgradeRegistry(signal) {
+export async function resolveUpgradeRegistry(signal) {
     const npm = resolveNpmInvocation();
     try {
         const result = await execFileAsync(npm.command, [...npm.argsPrefix, 'config', 'get', 'registry'], {
@@ -115,7 +130,7 @@ async function withGlobalInstallLock(action) {
     globalInstallTail = new Promise(resolve => { release = resolve; });
     await previous;
     try {
-        await action();
+        await withFileLock(globalInstallLockPath(), action, 5 * 60_000);
     }
     finally {
         release();
@@ -191,6 +206,59 @@ export async function requireOptional(pkg, autoInstall = true) {
         return await import(pkg);
     }
 }
+const PACKAGE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+export function isPackageVersion(value) {
+    if (typeof value !== 'string' || value.length > 256)
+        return false;
+    const match = PACKAGE_VERSION.exec(value);
+    return !!match && (!match[4] || match[4].split('.').every(id => !/^\d+$/.test(id) || id === '0' || !id.startsWith('0')));
+}
+export function normalizeVersionRegistry(value) {
+    if (typeof value !== 'string')
+        return null;
+    try {
+        const url = new URL(value);
+        if (!['https:', 'http:'].includes(url.protocol) || !url.hostname
+            || url.username || url.password || url.search || url.hash)
+            return null;
+        return url.href.replace(/\/+$/, '');
+    }
+    catch {
+        return null;
+    }
+}
+export function comparePackageVersions(a, b) {
+    if (!isPackageVersion(a) || !isPackageVersion(b))
+        throw new Error('Invalid package version');
+    const left = PACKAGE_VERSION.exec(a);
+    const right = PACKAGE_VERSION.exec(b);
+    for (let i = 1; i <= 3; i++) {
+        if (BigInt(left[i]) < BigInt(right[i]))
+            return -1;
+        if (BigInt(left[i]) > BigInt(right[i]))
+            return 1;
+    }
+    if (!left[4] || !right[4])
+        return left[4] === right[4] ? 0 : left[4] ? -1 : 1;
+    const la = left[4].split('.');
+    const ra = right[4].split('.');
+    for (let i = 0; i < Math.max(la.length, ra.length); i++) {
+        if (la[i] === ra[i])
+            continue;
+        if (la[i] === undefined)
+            return -1;
+        if (ra[i] === undefined)
+            return 1;
+        const ln = /^\d+$/.test(la[i]);
+        const rn = /^\d+$/.test(ra[i]);
+        if (ln && rn)
+            return BigInt(la[i]) < BigInt(ra[i]) ? -1 : 1;
+        if (ln !== rn)
+            return ln ? -1 : 1;
+        return la[i] < ra[i] ? -1 : 1;
+    }
+    return 0;
+}
 /**
  * 比较两个 semver 版本号 (a.b.c 格式)
  * 返回 -1 (a < b), 0 (a == b), 1 (a > b)
@@ -216,12 +284,12 @@ export function compareVersions(a, b) {
  * 而 npm link 指向项目源码目录，其父目录不是 node_modules。
  */
 export function isLinkedInstall() {
-    const pkgRoot = getPackageRoot();
+    const pkgRoot = targetPackageRoot();
     return path.basename(path.dirname(pkgRoot)) !== 'node_modules';
 }
 /** 获取本地 package.json 中的版本号 */
 export function getLocalVersion() {
-    const pkgPath = path.join(getPackageRoot(), 'package.json');
+    const pkgPath = path.join(targetPackageRoot(), 'package.json');
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
     return pkg.version;
 }
@@ -276,6 +344,53 @@ async function fetchLatestVersion(pkg = 'evolcore', timeoutMs = 10000, signal, r
         signal?.removeEventListener('abort', abort);
     }
 }
+/** Query an already selected source, retaining npm proxy/CA/auth behavior. */
+export async function queryPackageVersion(pkg, selection, signal) {
+    const registry = normalizeVersionRegistry(selection.registry);
+    if (!registry)
+        return null;
+    const version = selection.useNpmCli
+        ? await checkLatestVersionViaNpm(pkg, 10000, signal, registry)
+        : await fetchLatestVersion(pkg, 10000, signal, registry);
+    return isPackageVersion(version) ? { version, registry } : null;
+}
+/** No registry lookup: callers must validate cache freshness before each install. */
+export async function installExactPackageVersion(pkg, target, registry, resolveInstalled) {
+    if (![MAIN_PACKAGE_NAME, WEB_PACKAGE_NAME].includes(pkg)
+        || !isPackageVersion(target) || normalizeVersionRegistry(registry) !== registry) {
+        return { status: 'failed', error: 'Invalid cached install target' };
+    }
+    if (isLinkedInstall())
+        return { status: 'skipped' };
+    let result = { status: 'skipped' };
+    await withGlobalInstallLock(async () => {
+        const installed = resolveInstalled();
+        if (!installed || !isPackageVersion(installed.version))
+            return;
+        const from = installed.version;
+        if (comparePackageVersions(from, target) >= 0) {
+            result = { status: 'no-update', from };
+            return;
+        }
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                await npmInstallGlobal(`${pkg}@${target}`, { registry });
+                const actual = resolveInstalled()?.version;
+                if (!actual || !isPackageVersion(actual) || comparePackageVersions(actual, target) < 0) {
+                    throw new Error('Installed version did not reach the cached target');
+                }
+                result = { status: 'upgraded', from, to: actual };
+                return;
+            }
+            catch {
+                // npm stderr can contain private registry credentials. Persist a safe
+                // diagnostic; npm's existing permission/transport behavior is retained.
+                result = { status: 'failed', from, to: target, error: 'Exact package installation or version verification failed' };
+            }
+        }
+    });
+    return result;
+}
 /**
  * Read the current npm registry first. If that read succeeds, npm itself is
  * used for the version query so proxy/CA/auth settings are preserved. If the

package/dist/utils/package-version-info.js

@@ -0,0 +1,244 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getPackageRoot, resolvePaths } from '../paths.js';
+import { MAIN_PACKAGE_NAME, WEB_PACKAGE_NAME, TARGET_PACKAGE_ROOT_ENV } from '../product.js';
+import { getLocalVersion, isLinkedInstall, resolveGlobalPkg, resolveUpgradeRegistry, queryPackageVersion, installExactPackageVersion, } from './npm-ops.js';
+import { comparePackageVersions, isPackageVersion, normalizeVersionRegistry } from './npm-ops.js';
+import { atomicReplaceJson, withFileLock } from './atomic-write.js';
+export const VERSION_INFO_TTL_MS = 24 * 60 * 60 * 1000;
+export const VERSION_INFO_PACKAGES = [MAIN_PACKAGE_NAME, WEB_PACKAGE_NAME, '@agentunion/fastaun'];
+export const AUTO_UPGRADE_PACKAGES = [MAIN_PACKAGE_NAME, WEB_PACKAGE_NAME];
+const empty = () => ({ $schema_version: 1, packages: {} });
+const timestamp = (value) => typeof value === 'string' ? Date.parse(value) : NaN;
+const allowed = (name) => VERSION_INFO_PACKAGES.includes(name);
+const filePath = () => path.join(resolvePaths().dataDir, 'package-version-info.json');
+const writeLockPath = () => `${filePath()}.lock`;
+/** Read-only: corrupt/unknown formats never recover fields from partial data. */
+export function readPackageVersionInfo() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(filePath(), 'utf8'));
+        if (raw?.$schema_version !== 1 || !raw.packages || Array.isArray(raw.packages)
+            || typeof raw.packages !== 'object' || Object.keys(raw.packages).some(name => !allowed(name)))
+            return empty();
+        const result = empty();
+        for (const [name, value] of Object.entries(raw.packages)) {
+            const entry = value;
+            if (!entry || entry.packageName !== name || !['ok', 'unavailable', 'skipped', 'not-installed'].includes(entry.lastAttemptStatus)
+                || (entry.currentVersion !== null && !isPackageVersion(entry.currentVersion))
+                || (entry.latestVersion != null && !isPackageVersion(entry.latestVersion))
+                || (entry.registry !== undefined && normalizeVersionRegistry(entry.registry) !== entry.registry))
+                continue;
+            result.packages[name] = entry;
+        }
+        return result;
+    }
+    catch {
+        return empty();
+    }
+}
+/** Cooperating readers pause while a writer owns the Windows replace gate. */
+export async function readPackageVersionInfoConsistent(timeoutMs = 30000) {
+    const deadline = Date.now() + timeoutMs;
+    while (fs.existsSync(writeLockPath())) {
+        if (Date.now() >= deadline)
+            return readPackageVersionInfo();
+        await new Promise(resolve => setTimeout(resolve, 15));
+    }
+    return readPackageVersionInfo();
+}
+export function isPackageVersionInfoFresh(entry, now = Date.now(), ttlMs = VERSION_INFO_TTL_MS, registry) {
+    if (!entry || !allowed(entry.packageName) || !isPackageVersion(entry.currentVersion)
+        || !isPackageVersion(entry.latestVersion) || !entry.registry
+        || normalizeVersionRegistry(entry.registry) !== entry.registry
+        || (registry !== undefined && entry.registry !== registry))
+        return false;
+    const checked = timestamp(entry.checkedAt);
+    const observed = timestamp(entry.currentVersionObservedAt);
+    return Number.isFinite(checked) && checked <= now && now - checked <= ttlMs
+        && Number.isFinite(observed) && observed <= now;
+}
+/** Snapshot groups have separate clocks so a stale query cannot undo an install. */
+export async function mergePackageVersionInfo(patch) {
+    if (!allowed(patch.packageName))
+        throw new Error('Unmanaged package');
+    if (patch.currentVersion !== null && !isPackageVersion(patch.currentVersion))
+        throw new Error('Invalid installed version');
+    if (patch.checkedAt && (!isPackageVersion(patch.latestVersion)
+        || !patch.registry || normalizeVersionRegistry(patch.registry) !== patch.registry))
+        throw new Error('Invalid successful snapshot');
+    const file = filePath();
+    return withFileLock(writeLockPath(), async () => {
+        const data = readPackageVersionInfo();
+        const previous = data.packages[patch.packageName];
+        const entry = previous ? { ...previous } : {
+            packageName: patch.packageName, currentVersion: null, lastAttemptStatus: patch.lastAttemptStatus,
+        };
+        const newer = (next, old) => Number.isFinite(timestamp(next))
+            && (!Number.isFinite(timestamp(old)) || timestamp(old) > Date.now() || timestamp(next) >= timestamp(old));
+        if (newer(patch.currentVersionObservedAt, entry.currentVersionObservedAt)) {
+            entry.currentVersion = patch.currentVersion;
+            entry.currentVersionObservedAt = patch.currentVersionObservedAt;
+        }
+        if (newer(patch.checkedAt, entry.checkedAt)) {
+            entry.latestVersion = patch.latestVersion;
+            entry.checkedAt = patch.checkedAt;
+            entry.registry = patch.registry;
+        }
+        if (newer(patch.lastAttemptAt, entry.lastAttemptAt)) {
+            entry.lastAttemptStatus = patch.lastAttemptStatus;
+            entry.lastAttemptAt = patch.lastAttemptAt;
+            if (patch.lastError)
+                entry.lastError = patch.lastError;
+            else
+                delete entry.lastError;
+        }
+        if (patch.lastUpgrade && newer(patch.lastUpgrade.at, entry.lastUpgrade?.at))
+            entry.lastUpgrade = patch.lastUpgrade;
+        data.packages[patch.packageName] = entry;
+        await atomicReplaceJson(file, data);
+        return entry;
+    });
+}
+export function resolveVersionInfoPackage(name) {
+    if (!allowed(name))
+        throw new Error('Unmanaged package');
+    const root = process.env[TARGET_PACKAGE_ROOT_ENV] || getPackageRoot();
+    if (name === MAIN_PACKAGE_NAME)
+        return { version: getLocalVersion(), path: path.join(root, 'package.json') };
+    if (name === WEB_PACKAGE_NAME)
+        return resolveGlobalPkg(name);
+    const file = path.join(root, 'node_modules', '@agentunion', 'fastaun', 'package.json');
+    try {
+        return { version: JSON.parse(fs.readFileSync(file, 'utf8')).version, path: file };
+    }
+    catch {
+        return null;
+    }
+}
+function hasUpdate(entry, registry, now = Date.now()) {
+    return isPackageVersionInfoFresh(entry, now, VERSION_INFO_TTL_MS, registry)
+        && comparePackageVersions(entry.currentVersion, entry.latestVersion) < 0;
+}
+async function checkPackage(name, force, options) {
+    if (!allowed(name))
+        throw new Error('Unmanaged package');
+    const now = options.now ?? Date.now();
+    const at = new Date(now).toISOString();
+    const old = (await readPackageVersionInfoConsistent()).packages[name];
+    const observed = {
+        packageName: name, currentVersion: null, currentVersionObservedAt: at,
+        lastAttemptStatus: 'unavailable',
+    };
+    const log = (message) => options.log?.(`[${options.source ?? 'version-check'}] ${name}: ${message}`);
+    let source = 'refresh';
+    try {
+        const linked = isLinkedInstall();
+        const local = linked && name !== MAIN_PACKAGE_NAME ? null : resolveVersionInfoPackage(name);
+        if (local && !isPackageVersion(local.version))
+            throw new Error('Invalid installed package version');
+        observed.currentVersion = local?.version ?? null;
+        if (linked)
+            observed.lastAttemptStatus = 'skipped';
+        else if (!local)
+            observed.lastAttemptStatus = 'not-installed';
+        else {
+            const selection = options.selection ?? await resolveUpgradeRegistry(options.signal);
+            const registry = normalizeVersionRegistry(selection.registry);
+            if (!registry)
+                throw new Error('Registry configuration is not safe for version caching');
+            if (!force && isPackageVersionInfoFresh(old, now, VERSION_INFO_TTL_MS, registry)) {
+                source = 'cache';
+                observed.lastAttemptStatus = 'ok';
+                const entry = await mergePackageVersionInfo(observed);
+                log(`Using cached version information (age ${Math.floor((now - timestamp(old.checkedAt)) / 60000)}m)`);
+                return { packageName: name, status: 'ok', source, entry, hasUpdate: hasUpdate(entry, registry, now) };
+            }
+            log(force ? 'Refreshing version information' : 'Version information missing/invalid/expired; refreshing');
+            const checked = await queryPackageVersion(name, selection, options.signal);
+            if (!checked)
+                throw new Error('Version registry unavailable or returned an invalid version');
+            observed.latestVersion = checked.version;
+            observed.registry = checked.registry;
+            // Use request start, not completion: an older slow request cannot replace
+            // a later successful request, and query time consumes the TTL.
+            observed.checkedAt = at;
+            observed.lastAttemptStatus = 'ok';
+        }
+    }
+    catch {
+        observed.lastAttemptStatus = 'unavailable';
+        observed.lastError = 'Version refresh failed; continuing with current version';
+        log(observed.lastError);
+    }
+    observed.lastAttemptAt = at;
+    let entry = { ...old, ...observed };
+    try {
+        entry = await mergePackageVersionInfo(observed);
+    }
+    catch {
+        log('Version information could not be saved; continuing with current version');
+        return { packageName: name, source, entry, status: 'unavailable', hasUpdate: false, error: 'Version information could not be saved' };
+    }
+    return {
+        packageName: name, source, entry, status: observed.lastAttemptStatus,
+        hasUpdate: observed.lastAttemptStatus === 'ok' && hasUpdate(entry, observed.registry, now),
+        ...(observed.lastError ? { error: observed.lastError } : {}),
+    };
+}
+export async function refreshPackageVersionInfo(name, options = {}) {
+    return checkPackage(name, true, options);
+}
+export async function ensureFreshPackageVersionInfo(names = AUTO_UPGRADE_PACKAGES, options = {}) {
+    const selection = options.selection ?? (isLinkedInstall() ? undefined : await resolveUpgradeRegistry(options.signal));
+    return Promise.all(names.map(name => checkPackage(name, false, { ...options, selection })));
+}
+export async function refreshManagedPackageVersions(names = AUTO_UPGRADE_PACKAGES, options = {}) {
+    const selection = options.selection ?? (isLinkedInstall() ? undefined : await resolveUpgradeRegistry(options.signal));
+    return Promise.all(names.map(name => checkPackage(name, true, { ...options, selection })));
+}
+export async function recordPackageUpgrade(name, upgrade, log) {
+    try {
+        await mergePackageVersionInfo({
+            packageName: name, currentVersion: resolveVersionInfoPackage(name)?.version ?? null,
+            currentVersionObservedAt: new Date().toISOString(), lastAttemptStatus: 'unavailable', lastUpgrade: upgrade,
+        });
+    }
+    catch {
+        log?.(`${name}: Failed to record install outcome`);
+    }
+}
+/** Called only by the lifecycle coordinator, after shutdown. Never queries registry. */
+export async function applyCachedPackageUpgrades(names = AUTO_UPGRADE_PACKAGES, options = {}) {
+    if (names.some(name => !AUTO_UPGRADE_PACKAGES.includes(name)))
+        throw new Error('Package is not automatically managed');
+    if (isLinkedInstall())
+        return names.map(() => ({ status: 'skipped' }));
+    const results = [];
+    for (const name of names) {
+        let result = { status: 'skipped' };
+        if (!AUTO_UPGRADE_PACKAGES.includes(name))
+            throw new Error('Package is not automatically managed');
+        try {
+            const entry = (await readPackageVersionInfoConsistent(0)).packages[name];
+            const registry = entry?.registry ? normalizeVersionRegistry(entry.registry) : null;
+            if (!registry || !isPackageVersionInfoFresh(entry, Date.now(), VERSION_INFO_TTL_MS, registry)) {
+                result = { status: 'skipped', error: 'No valid cached version information' };
+            }
+            else {
+                options.log?.(`Applying cached version information: ${name}@${entry.latestVersion}`);
+                result = await installExactPackageVersion(name, entry.latestVersion, registry, () => resolveVersionInfoPackage(name));
+            }
+        }
+        catch {
+            result = { status: 'failed', error: 'Cached upgrade could not acquire installation lock or read installed version' };
+        }
+        if (result.status === 'upgraded' || result.status === 'failed') {
+            await recordPackageUpgrade(name, {
+                from: result.from, to: result.to, at: new Date().toISOString(),
+                status: result.status === 'upgraded' ? 'installed' : 'failed', error: result.error,
+            }, options.log);
+        }
+        results.push(result);
+    }
+    return results;
+}

package/dist/utils/windows-shell-trust.js

@@ -36,6 +36,10 @@ export function isTrustedShellSignature(kind, evidence) {
 function windowsSystemRoot() {
     return process.env.SystemRoot || process.env.WINDIR || 'C:\\Windows';
 }
+/** Return the only cmd.exe that EvolCore is willing to use as a shell carrier. */
+export function windowsSystemCmdPath() {
+    return path.win32.join(windowsSystemRoot(), 'System32', 'cmd.exe');
+}
 function systemPowerShellPath() {
     return path.win32.join(windowsSystemRoot(), 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
 }
@@ -195,6 +199,39 @@ export function isTrustedWindowsShellExecutable(executable, kind) {
     }
     return trusted;
 }
+/**
+ * Resolve an inherited ComSpec to the system cmd.exe and authenticate it.
+ * npm shims are not signed Microsoft binaries, so this helper intentionally
+ * validates only the interpreter and never the `.cmd`/`.bat` target.
+ */
+export function resolveTrustedWindowsCmdPath(comSpec) {
+    if (process.platform !== 'win32')
+        return comSpec || 'cmd.exe';
+    const systemCmd = windowsSystemCmdPath();
+    const candidate = (comSpec || process.env.ComSpec || process.env.COMSPEC || systemCmd).trim();
+    if (!candidate)
+        return undefined;
+    let candidatePath = candidate;
+    if (!isAbsoluteWindowsPath(candidatePath)) {
+        if (/^cmd(?:\.exe)?$/i.test(candidatePath))
+            candidatePath = systemCmd;
+        else
+            return undefined;
+    }
+    let candidateReal;
+    let systemReal;
+    try {
+        candidateReal = fs.realpathSync.native(candidatePath);
+        systemReal = fs.realpathSync.native(systemCmd);
+    }
+    catch {
+        return undefined;
+    }
+    if (path.win32.normalize(candidateReal).toLowerCase() !== path.win32.normalize(systemReal).toLowerCase()) {
+        return undefined;
+    }
+    return isTrustedWindowsShellExecutable(systemReal, 'cmd') ? systemReal : undefined;
+}
 /** Test hook: clear cached signature decisions after a fixture is replaced. */
 export function clearWindowsShellTrustCache() {
     signatureCache.clear();

package/kits/docs/channels/aun.md

@@ -55,6 +55,14 @@ AUN keystore seed 由 EvolCore 使用固定应用值管理，不再提供配置
 - **群 @ 处理策略**：`mention_mode=disabled|mention-only` 是群级配置，只决定哪些群消息进入 Agent LLM 上下文，不影响 AUN 协议层投递；被过滤消息仍应本地存档。
 - **身份体系**：对端以 AID 标识，关系层 peerKey 形如 `aun#alice.aid.pub`。
 
+### 私聊最终回复标题
+
+AUN 私聊中，`result.text` 的 `isFinal=true` 会在 `payload.text` 正文前添加 `✅ 最终回复:`。AUN 文本客户端按正文展示，标题随 outbox 上下文持久化，断线恢复发送时仍保留。群聊、中间文本、命令回执及错误消息不自动添加该标题。
+
+Interactive 私聊的最终正文保留到本轮结束后统一发送，避免定时 flush 提前当作中间文本发出。Codex 明确标记的 commentary 可按原定时窗口发送；没有阶段标记的正文等到下一文本块、工具调用或本轮结束后确定发送方式。标题和正文之间留一个空行，正文已经以同一标题开头时不重复添加，也不额外发送 `payload.title`。
+
+标题仅表示最终回复的展示信息，任务完成或失败仍由 `task.status` 表达。
+
 ### 出站关注状态
 
 AUN runner 状态和 action card 可携带顶层 `attention`，值只能是以下四种之一：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolcore",
-  "version": "0.0.27",
+  "version": "0.0.28",
   "description": "AI Agent gateway connecting Claude, Codex, Gemini, and the bundled ecagent runner to messaging channels with multi-project session management",
   "type": "module",
   "main": "dist/index.js",