evolcore 0.0.21 → 0.0.23

package/dist/trigger/parser.js

@@ -1,7 +1,11 @@
 import { CronExpressionParser } from 'cron-parser';
 const TRIGGER_UPDATE_FLAGS = new Set([
     'once', 'delay', 'at', 'cron', 'every', 'event', 'tz',
-    'prompt', 'name',
+    'prompt', 'name', 'description',
+    'script-file', 'script-runtime', 'script-args', 'script-timeout',
+    'feedback', 'target-channel', 'target-channel-id', 'target-chat-type', 'target-session', 'target-thread-id',
+    'trigger-thread', 'baseagent',
+    'on-error', 'noop-sentinel', 'retry-attempts', 'retry-backoff',
     'model', 'effort', 'permission',
     'max-runs', 'max-duration', 'concurrency', 'missed-policy',
 ]);
@@ -395,18 +399,22 @@ function commonParsed(flags, opts = {}) {
     if (!opts.update && !execution.value) {
         return { ok: false, error: '创建 trigger 必须显式指定 --exec script|trigger-session|target-session' };
     }
+    // update 场景下执行类型未知（不重命名 --exec），execution-type 相关校验
+    // 全部交给 patch/validation 按现有定义执行。
     const inferredExecution = execution.value;
-    if (baseagent.value && inferredExecution !== 'trigger_session') {
-        return { ok: false, error: '--baseagent 仅适用于 --exec trigger-session' };
-    }
-    if (inferredExecution === 'script') {
-        if (!scriptPath && !opts.update)
-            return { ok: false, error: '--exec script 需要 --script-path' };
-        if (scriptPath && !scriptRuntime && !opts.update)
-            return { ok: false, error: '--script-path 必须配合 --script-runtime 使用（node|python|bash）' };
-    }
-    else if (!prompt && !opts.update) {
-        return { ok: false, error: '--prompt 为必填项' };
+    if (!opts.update) {
+        if (baseagent.value && inferredExecution !== 'trigger_session') {
+            return { ok: false, error: '--baseagent 仅适用于 --exec trigger-session' };
+        }
+        if (inferredExecution === 'script') {
+            if (!scriptPath)
+                return { ok: false, error: '--exec script 需要 --script-path' };
+            if (scriptPath && !scriptRuntime)
+                return { ok: false, error: '--script-path 必须配合 --script-runtime 使用（node|python|bash）' };
+        }
+        else if (!prompt) {
+            return { ok: false, error: '--prompt 为必填项' };
+        }
     }
     const targetSessionValue = targetSession.value ?? (targetThreadId ? 'thread' : 'main');
     const feedbackStrategy = feedback.value ?? (hasTargetField ? 'target' : 'origin');
@@ -552,7 +560,7 @@ export function parseTriggerUpdateArgv(nameOrId, args, opts = {}) {
     const parsedFlags = flagsFromArgv(args, 'update');
     if (!parsedFlags.ok)
         return { ok: false, error: withPromptFileHint(parsedFlags.error, args, opts) };
-    const parsed = parseTriggerUpdateFlags(nameOrId, parsedFlags.flags, opts);
+    const parsed = parseTriggerUpdateFlags(nameOrId, parsedFlags.flags, { ...opts, allowScriptFile: true });
     return parsed.ok ? parsed : { ok: false, error: withPromptFileHint(parsed.error, args, opts) };
 }
 function flagsFromArgv(args, command) {
@@ -585,6 +593,9 @@ function parseTriggerUpdateFlags(nameOrId, flags, opts = {}) {
         if (!TRIGGER_UPDATE_FLAGS.has(flag))
             return { ok: false, error: `update 不支持参数 --${flag}` };
     }
+    if (flags.has('script-file') && !opts.allowScriptFile) {
+        return { ok: false, error: '--script-file 仅支持 ec trigger update CLI；请通过受控 CLI 上传脚本文件' };
+    }
     const parsed = commonParsed(flags, { update: true, ...opts });
     if (!parsed.ok)
         return parsed;
@@ -607,6 +618,11 @@ function parseTriggerUpdateFlags(nameOrId, flags, opts = {}) {
         update.name = value.name;
     if (value.prompt !== undefined)
         update.prompt = value.prompt;
+    const scriptFile = optionalFlagString(flags, 'script-file');
+    if ('error' in scriptFile)
+        return { ok: false, error: scriptFile.error };
+    if (scriptFile.value !== undefined)
+        update.scriptFile = scriptFile.value;
     if (value.model !== undefined)
         update.model = value.model;
     if (value.effort !== undefined)
@@ -636,6 +652,63 @@ function parseTriggerUpdateFlags(nameOrId, flags, opts = {}) {
         }
         update.missedPolicy = normalized;
     }
+    const description = optionalFlagString(flags, 'description');
+    if ('error' in description)
+        return { ok: false, error: description.error };
+    if (description.value !== undefined)
+        update.description = description.value || null;
+    if (flags.has('feedback') && value.feedbackStrategy !== undefined)
+        update.feedback = value.feedbackStrategy;
+    if (value.targetChannel !== undefined)
+        update.targetChannel = value.targetChannel;
+    if (value.targetChannelId !== undefined)
+        update.targetChannelId = value.targetChannelId;
+    if (value.targetChatType !== undefined)
+        update.targetChatType = value.targetChatType;
+    if (value.targetSession !== undefined && flags.has('target-session'))
+        update.targetSession = value.targetSession;
+    if (value.targetThreadId !== undefined)
+        update.targetThreadId = value.targetThreadId;
+    if (value.triggerThread !== undefined)
+        update.triggerThread = value.triggerThread;
+    if (value.baseagent !== undefined)
+        update.baseagent = value.baseagent;
+    const onError = optionalFlagString(flags, 'on-error');
+    if ('error' in onError)
+        return { ok: false, error: onError.error };
+    if (onError.value !== undefined) {
+        if (onError.value !== 'fail' && onError.value !== 'retry') {
+            return { ok: false, error: '--on-error 只接受 fail 或 retry' };
+        }
+        update.onError = onError.value;
+    }
+    const noopSentinel = optionalFlagString(flags, 'noop-sentinel');
+    if ('error' in noopSentinel)
+        return { ok: false, error: noopSentinel.error };
+    if (noopSentinel.value !== undefined)
+        update.noopSentinel = noopSentinel.value || null;
+    const retryAttempts = optionalFlagString(flags, 'retry-attempts');
+    if ('error' in retryAttempts)
+        return { ok: false, error: retryAttempts.error };
+    if (retryAttempts.value !== undefined) {
+        if (!/^\d+$/.test(retryAttempts.value))
+            return { ok: false, error: '--retry-attempts 必须是非负整数' };
+        update.retryAttempts = Number(retryAttempts.value);
+    }
+    const retryBackoff = optionalFlagString(flags, 'retry-backoff');
+    if ('error' in retryBackoff)
+        return { ok: false, error: retryBackoff.error };
+    if (retryBackoff.value !== undefined) {
+        if (!/^\d+$/.test(retryBackoff.value))
+            return { ok: false, error: '--retry-backoff 必须是毫秒正整数' };
+        update.retryBackoff = Number(retryBackoff.value);
+    }
+    if (value.scriptRuntime !== undefined)
+        update.scriptRuntime = value.scriptRuntime;
+    if (value.scriptArgs !== undefined)
+        update.scriptArgs = value.scriptArgs;
+    if (value.scriptTimeoutMs !== undefined)
+        update.scriptTimeout = value.scriptTimeoutMs;
     if (Object.keys(update).length === 0)
         return { ok: false, error: '没有可更新的 trigger 参数' };
     return { ok: true, nameOrId, value: update };

package/dist/trigger/patch.js

@@ -1,6 +1,7 @@
 import { normalizeTriggerDefinition, parseDurationMs, TRIGGER_SCHEMA_VERSION } from './validation.js';
 const PATCH_KEYS = new Set([
     'name',
+    'description',
     'scheduleType',
     'scheduleValue',
     'timezone',
@@ -12,6 +13,21 @@ const PATCH_KEYS = new Set([
     'maxDuration',
     'concurrency',
     'missedPolicy',
+    'feedback',
+    'targetChannel',
+    'targetChannelId',
+    'targetChatType',
+    'targetSession',
+    'targetThreadId',
+    'baseagent',
+    'triggerThread',
+    'onError',
+    'noopSentinel',
+    'retryAttempts',
+    'retryBackoff',
+    'scriptRuntime',
+    'scriptArgs',
+    'scriptTimeout',
 ]);
 export function applyTriggerPatch(definition, input, opts = {}) {
     if (!input || typeof input !== 'object' || Array.isArray(input)) {
@@ -48,6 +64,12 @@ export function applyTriggerPatch(definition, input, opts = {}) {
         updated.reliability.concurrency = patch.concurrency;
     if (patch.missedPolicy !== undefined)
         updated.reliability.missedPolicy = patch.missedPolicy;
+    if (patch.description !== undefined) {
+        if (patch.description === null || patch.description === '')
+            delete updated.description;
+        else
+            updated.description = String(patch.description);
+    }
     if (patch.maxRuns !== undefined || patch.maxDuration !== undefined) {
         const limits = updated.limits ? { ...updated.limits } : {};
         if (patch.maxRuns !== undefined) {
@@ -64,6 +86,85 @@ export function applyTriggerPatch(definition, input, opts = {}) {
         }
         updated.limits = Object.keys(limits).length > 0 ? limits : undefined;
     }
+    // feedback strategy
+    if (patch.feedback !== undefined) {
+        updated.feedback.strategy = patch.feedback;
+        if (patch.feedback !== 'target')
+            delete updated.feedback.target;
+    }
+    // feedback target fields
+    const hasTargetPatch = patch.targetChannel !== undefined
+        || patch.targetChannelId !== undefined
+        || patch.targetChatType !== undefined
+        || patch.targetSession !== undefined
+        || patch.targetThreadId !== undefined;
+    if (hasTargetPatch) {
+        if ((patch.targetChannel === undefined) !== (patch.targetChannelId === undefined)) {
+            throw new Error('targetChannel 与 targetChannelId 必须同时指定');
+        }
+        const prev = updated.feedback.target;
+        const next = {
+            channelKey: patch.targetChannel ?? prev?.channelKey ?? '',
+            channelId: patch.targetChannelId ?? prev?.channelId ?? '',
+            session: patch.targetSession ?? prev?.session ?? 'main',
+            threadId: patch.targetThreadId === null || patch.targetThreadId === ''
+                ? undefined
+                : (patch.targetThreadId ?? prev?.threadId),
+            chatType: patch.targetChatType === null
+                ? undefined
+                : (patch.targetChatType ?? prev?.chatType),
+        };
+        if (!next.channelKey || !next.channelId) {
+            throw new Error('target 修改需要提供有效的 channelKey 和 channelId');
+        }
+        updated.feedback.target = next;
+        if (updated.feedback.strategy !== 'target')
+            updated.feedback.strategy = 'target';
+    }
+    // execution fields
+    if (patch.baseagent !== undefined) {
+        if (updated.execution.type !== 'trigger_session') {
+            throw new Error('baseagent 仅适用于 trigger_session 类型');
+        }
+        setOptional(updated.execution, 'baseagent', patch.baseagent);
+    }
+    if (patch.triggerThread !== undefined)
+        setOptional(updated.execution, 'thread', patch.triggerThread);
+    if (patch.onError !== undefined)
+        updated.execution.onError = patch.onError;
+    if (patch.noopSentinel !== undefined) {
+        if (patch.noopSentinel === null || patch.noopSentinel === '')
+            updated.execution.noopSentinel = '[[NOOP]]';
+        else
+            updated.execution.noopSentinel = patch.noopSentinel;
+    }
+    // reliability retry
+    if (patch.retryAttempts !== undefined || patch.retryBackoff !== undefined) {
+        const retry = { ...updated.reliability.retry };
+        if (patch.retryAttempts !== undefined)
+            retry.maxAttempts = patch.retryAttempts ?? 0;
+        if (patch.retryBackoff !== undefined)
+            retry.backoffMs = patch.retryBackoff ?? 30_000;
+        updated.reliability = { ...updated.reliability, retry };
+    }
+    // script fields
+    if (patch.scriptRuntime !== undefined || patch.scriptArgs !== undefined || patch.scriptTimeout !== undefined) {
+        if (updated.execution.type !== 'script' || !updated.execution.script) {
+            throw new Error('scriptRuntime/scriptArgs/scriptTimeout 仅适用于 script 类型 trigger');
+        }
+        const script = { ...updated.execution.script };
+        if (patch.scriptRuntime !== undefined)
+            script.runtime = patch.scriptRuntime;
+        if (patch.scriptArgs !== undefined) {
+            if (patch.scriptArgs === null)
+                delete script.args;
+            else
+                script.args = patch.scriptArgs;
+        }
+        if (patch.scriptTimeout !== undefined)
+            script.timeoutMs = patch.scriptTimeout ?? 30_000;
+        updated.execution.script = script;
+    }
     return normalizeTriggerDefinition({
         ...updated,
         id: definition.id,
@@ -98,7 +199,9 @@ export function replaceEditableTriggerDefinition(existing, input) {
 }
 function assertBaseagentImmutable(existing, updated) {
     if (existing.execution.baseagent !== updated.execution.baseagent) {
-        throw new Error('execution.baseagent is immutable; create a new Trigger to use another baseagent');
+        if (existing.execution.type !== 'trigger_session' || updated.execution.type !== 'trigger_session') {
+            throw new Error('execution.baseagent is only mutable between trigger_session Triggers');
+        }
     }
 }
 function applySourcePatch(updated, patch) {

package/dist/trigger/scheduler.js

@@ -120,12 +120,12 @@ export class TriggerRuntimeScheduler {
     }
     listItems(definitions) {
         const latestRuns = this.audit.latest(definitions.map(definition => definition.id));
-        return definitions.map(definition => this.buildListItem(definition, latestRuns.get(definition.id)));
+        return definitions.map(definition => this.buildListItem(definition, latestRuns.get(definition.id), this.stats(definition.id)));
     }
     listItem(definition) {
-        return this.buildListItem(definition, this.audit.recent(definition.id, 1)[0]);
+        return this.buildListItem(definition, this.audit.recent(definition.id, 1)[0], this.stats(definition.id));
     }
-    buildListItem(definition, lastRun) {
+    buildListItem(definition, lastRun, stats = this.stats(definition.id)) {
         const schedule = this.state.readSchedule(definition.id);
         return {
             id: definition.id,
@@ -139,6 +139,10 @@ export class TriggerRuntimeScheduler {
                 ...(definition.feedback.target ? { target: definition.feedback.target } : {}),
             },
             ...(schedule ? { nextFireAt: schedule.nextFireAt } : {}),
+            fireCount: stats.fireCount,
+            failCount: stats.failCount,
+            ...(stats.lastFiredAt !== undefined ? { lastFiredAt: stats.lastFiredAt } : {}),
+            ...(stats.lastResult ? { lastResult: stats.lastResult } : {}),
             ...(lastRun ? { lastStatus: lastRun.status, lastFinishedAt: lastRun.finishedAt } : {}),
             updatedAt: definition.updatedAt,
         };
@@ -627,6 +631,7 @@ export class TriggerRuntimeScheduler {
                 effects: feedbackResult.effects,
                 error: feedbackResult.error,
                 conflictRunId: feedbackResult.conflictRunId,
+                interruption: feedbackResult.interruption,
                 causation,
             });
             if (!payload.dryRun) {
@@ -1147,6 +1152,7 @@ export class TriggerRuntimeScheduler {
                 anomalies,
                 effects: feedbackResult.effects,
                 error: feedbackResult.error,
+                interruption: feedbackResult.interruption,
                 causation,
             });
             this.audit.write(audit);
@@ -1469,6 +1475,7 @@ export class TriggerRuntimeScheduler {
             status: input.status,
             reason: input.reason,
             conflictRunId: input.conflictRunId,
+            ...(input.interruption ? { interruption: input.interruption } : {}),
             ...(activeRun?.executionSessionId ? { executionSessionId: activeRun.executionSessionId } : {}),
             ...(attempts?.length ? { attempts } : {}),
             ...(finalAttempt ? { finalAttempt: finalAttempt.attempt } : {}),
@@ -1783,6 +1790,7 @@ export class TriggerRuntimeScheduler {
                 type: 'trigger:skipped',
                 ...base,
                 reason: audit.reason ?? 'skipped',
+                ...(audit.interruption ?? {}),
             });
         }
     }
@@ -1900,6 +1908,15 @@ function errorReply(runId, durationMs, reason, text) {
 }
 function attemptSummaryFromExecution(attempt, attemptId, execution) {
     if (execution.feedbackResult) {
+        if (execution.feedbackResult.interruption) {
+            return {
+                status: 'interrupted',
+                error: {
+                    code: execution.feedbackResult.interruption.reasonCode,
+                    message: execution.feedbackResult.reason ?? execution.feedbackResult.interruption.reasonCode,
+                },
+            };
+        }
         const failed = execution.feedbackResult.status !== 'completed';
         return {
             status: failed ? 'failed' : 'completed',

package/dist/utils/ecweb-supervisor.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { spawn } from 'child_process';
-import { resolvePaths } from '../paths.js';
+import { getPackageRoot, resolvePaths } from '../paths.js';
 import { WEB_PACKAGE_NAME } from '../product.js';
 import { resolveGlobalPkg } from './npm-ops.js';
 import { ecwebVersionRequirementError, resolveEcwebLaunchCommand } from './ecweb-utils.js';
@@ -218,7 +218,16 @@ export function createEcwebSupervisor(options) {
                 detached: true,
                 stdio: ['ignore', childLogFd, childLogFd],
                 windowsHide: platform.isWindows,
-                env: { ...process.env, EVOLCORE_HOME: root },
+                // ECWeb dynamically imports EvolCore's dist modules for config,
+                // roles, authorization and session compatibility.  Pin that lookup
+                // to the same package root as this daemon; otherwise a separately
+                // installed ECWeb can resolve its peer dependency and silently load
+                // a different (possibly stale) EvolCore copy from node_modules.
+                env: {
+                    ...process.env,
+                    EVOLCORE_HOME: root,
+                    EVOLCORE_PACKAGE_ROOT: getPackageRoot(),
+                },
             });
         }
         catch (error) {

package/dist/utils/ecweb-utils.js

@@ -4,6 +4,7 @@ import { compareVersions, resolveGlobalPkg } from './npm-ops.js';
 import { isWindows as platformIsWindows, resolveCommandPath } from './cross-platform.js';
 import { MIN_ECWEB_VERSION, WEB_CLI_BIN, WEB_PACKAGE_NAME } from '../product.js';
 import { resolvePaths } from '../paths.js';
+import { ipcQuery } from '../ipc.js';
 /** EC Web owns the session-log reader, so older builds cannot safely serve a newer daemon. */
 export function isEcwebVersionSupported(version) {
     const normalized = version?.trim();
@@ -65,34 +66,15 @@ export function resolveEcwebLaunchCommand(ecwebArgs, opts = {}) {
     }
     return { command: commandPath, args: ecwebArgs, source: 'command' };
 }
-/**
- * ECWeb 配对码取码 helper（共享给 daemon 和 CLI）。
- *
- * 配对码是 ecweb 进程自己生成并持有的内部状态。daemon/CLI 通过 ecweb 的
- * localhost-only HTTP 接口 GET /api/pair-code 取当前码（远程访问被 ecweb 403 拒绝）。
- */
-/** 经 localhost 拉取 ecweb 当前配对码（仅本机可取）。失败返回 null。
- * authorizedBy 仅由 daemon 的 AUN 控制通道传入，用于把配对码换出的 token
- * 绑定到实际批准的 daemon-owner；普通 CLI 取码不携带该字段。 */
-export async function fetchEcwebPairCode(port, authorizedBy) {
+export async function fetchRemotePairingCode(authorizedBy) {
     try {
-        const headers = {};
-        const owner = authorizedBy?.trim();
-        if (owner)
-            headers['x-evolcore-pair-authorized-by'] = owner;
-        try {
-            const controlToken = fs.readFileSync(resolvePaths().controlToken, 'utf8').trim();
-            if (controlToken)
-                headers['x-evolcore-control-token'] = controlToken;
-        }
-        catch { }
-        const resp = await fetch(`http://127.0.0.1:${port}/api/pair-code`, {
-            headers,
-            signal: AbortSignal.timeout(2000),
-        });
-        if (!resp.ok)
+        const response = await ipcQuery(resolvePaths().socket, {
+            type: 'remote-auth.pair-code',
+            ...(authorizedBy?.trim() ? { authorizedBy: authorizedBy.trim() } : {}),
+        }, 2_000);
+        if (!response?.ok || typeof response.code !== 'string' || typeof response.expiresAt !== 'number')
             return null;
-        return await resp.json();
+        return { code: response.code, expiresAt: response.expiresAt };
     }
     catch {
         return null;

package/dist/utils/error-utils.js

@@ -380,6 +380,13 @@ export function getErrorMessage(error, terminalReason, includeEmoji = true) {
     }
     // 回退到原有的错误消息匹配逻辑
     const msg = error?.message || String(error);
+    // Codex app-server reports this when another app-server still owns the
+    // thread writer. Surface the handoff condition instead of hiding it behind
+    // the generic "processing failed" message.
+    if (error?.code === 'THREAD_ACTIVE_WRITER' || /already has an active writer/i.test(msg)) {
+        const prefix = includeEmoji ? '⚠️ ' : '';
+        return `${prefix}Codex 会话正在由另一个执行通道占用，请稍后重试（THREAD_ACTIVE_WRITER）`;
+    }
     // 字典优先 — 命中且有自定义消息则直接返回
     const rule = matchErrorRule(msg.toLowerCase());
     if (rule?.message)

package/dist/utils/logger.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import { resolvePaths } from '../paths.js';
 import { LogWriter } from './log-writer.js';
-import { classifyToolErrorCode } from '../core/permission/tool-error-code.js';
+import { classifyToolErrorCode, normalizeToolErrorCode } from '../core/permission/tool-error-code.js';
 import { normalizePermissionMode } from '../core/permission/mode.js';
 import { buildToolLifecycleEventKey } from '../core/audit/event-key.js';
 let currentLevel = process.env.LOG_LEVEL || 'INFO';
@@ -95,8 +95,8 @@ export function normalizeStructuredLog(data) {
     const isToolUse = eventType === 'tool:use' || eventType === 'tool_use';
     const isError = data.isError ?? data.is_error ?? (data.ok === false ? true : undefined)
         ?? nested?.isError ?? nested?.is_error ?? (nested?.ok === false ? true : undefined);
-    const error = data.error ?? data.errorMessage ?? nested?.error ?? nested?.errorMessage;
-    const result = data.result ?? data.content ?? nested?.result ?? nested?.content;
+    const decisionSource = data.decisionSource ?? data.decision_source
+        ?? nested?.decisionSource ?? nested?.decision_source;
     const decision = data.decision
         ?? data.status
         ?? (isToolResult && isError === true ? 'error' : undefined)
@@ -113,8 +113,11 @@ export function normalizeStructuredLog(data) {
         ?? nested?.errorCode
         ?? nested?.error_code;
     const errorCode = isToolResult && isError === true
-        ? classifyToolErrorCode({ errorCode: explicitErrorCode, error, result })
+        ? classifyToolErrorCode({ errorCode: explicitErrorCode, decisionSource })
         : explicitErrorCode;
+    const classificationMissing = isToolResult && isError === true
+        && !normalizeToolErrorCode(explicitErrorCode)
+        && decisionSource !== 'policy' && decisionSource !== 'approval';
     const lifecycleRecord = isToolUse || isToolResult;
     const lifecycleEventKey = lifecycleRecord
         ? (eventKey ?? buildToolLifecycleEventKey({
@@ -137,10 +140,12 @@ export function normalizeStructuredLog(data) {
         ...(agentName ? { agentName } : lifecycleRecord ? { agentName: 'unknown' } : {}),
         ...(permissionMode ? { permissionMode } : lifecycleRecord ? { permissionMode: 'unknown' } : {}),
         ...(toolName ? { toolName } : {}),
+        ...(decisionSource ? { decisionSource } : {}),
         ...(decision ? { decision } : {}),
         ...(executed !== undefined ? { executed } : {}),
         ...(executionState ? { executionState } : {}),
         ...(errorCode ? { errorCode } : {}),
+        ...(classificationMissing ? { classificationMissing: true } : {}),
         ...(missingContextFields.length > 0 ? { contextMissing: missingContextFields } : {}),
     };
 }

package/dist/utils/npm-ops.js

@@ -14,7 +14,7 @@ import { getPackageRoot } from '../paths.js';
 import { isWindows } from './cross-platform.js';
 const execFileAsync = promisify(execFile);
 // ── npm install -g (shared) ────────────────────────────────────────────────
-export async function npmInstallGlobal(pkg) {
+export async function npmInstallGlobal(pkg, options = {}) {
     let cmd;
     let args;
     // Windows: run via cmd /c to avoid shell:true deprecation warning on Node 22.
@@ -28,14 +28,24 @@ export async function npmInstallGlobal(pkg) {
         args = ['install', '-g', pkg];
     }
     try {
-        await execFileAsync(cmd, args, { timeout: 180000, windowsHide: isWindows });
+        await execFileAsync(cmd, args, {
+            timeout: options.timeoutMs ?? 180000,
+            windowsHide: isWindows,
+            signal: options.signal,
+        });
     }
     catch (e) {
+        if (options.signal?.aborted)
+            throw e;
         if (e.stderr?.includes('EACCES') || e.message?.includes('EACCES')) {
             if (isWindows) {
                 throw new Error('权限不足。请以管理员身份运行 PowerShell 或 CMD，然后重试');
             }
-            await execFileAsync('sudo', ['npm', 'install', '-g', pkg], { timeout: 180000, windowsHide: false });
+            await execFileAsync('sudo', ['npm', 'install', '-g', pkg], {
+                timeout: options.timeoutMs ?? 180000,
+                windowsHide: false,
+                signal: options.signal,
+            });
         }
         else {
             throw e;
@@ -119,15 +129,19 @@ export function resolveGlobalPkg(pkgName) {
  * 使用 HTTP fetch 直接查 registry API，不依赖 npm CLI。
  * 超时 10 秒，失败返回 null。
  */
-export async function checkLatestVersion(pkg = 'evolcore') {
+export async function checkLatestVersion(pkg = 'evolcore', timeoutMs = 10000, signal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    if (signal?.aborted)
+        abort();
+    else
+        signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(abort, timeoutMs);
     try {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), 10000);
         const res = await fetch(`https://registry.npmjs.org/${pkg}/latest`, {
             signal: controller.signal,
             headers: { 'Accept': 'application/json' },
         });
-        clearTimeout(timer);
         if (!res.ok)
             return null;
         const data = await res.json();
@@ -136,20 +150,26 @@ export async function checkLatestVersion(pkg = 'evolcore') {
     catch {
         return null;
     }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', abort);
+    }
 }
 /**
  * 完整升级流程：检查 → 比较 → 安装（失败重试一次）
  */
-export async function tryUpgrade() {
+export async function tryUpgrade(options = {}) {
     // 开发模式跳过
     if (isLinkedInstall()) {
         return { status: 'skipped' };
     }
     const localVer = getLocalVersion();
     // 查询 registry
-    const remoteVer = await checkLatestVersion();
+    const remoteVer = await checkLatestVersion('evolcore', options.checkTimeoutMs, options.signal);
     if (!remoteVer) {
-        return { status: 'skipped', error: 'Failed to check remote version' };
+        return options.signal?.aborted
+            ? { status: 'failed', from: localVer, error: 'Upgrade cancelled or timed out' }
+            : { status: 'skipped', error: 'Failed to check remote version' };
     }
     // 版本比较
     if (compareVersions(localVer, remoteVer) >= 0) {
@@ -159,11 +179,16 @@ export async function tryUpgrade() {
     let lastError;
     for (let attempt = 0; attempt < 2; attempt++) {
         try {
-            await npmInstallGlobal('evolcore@latest');
+            await npmInstallGlobal('evolcore@latest', {
+                timeoutMs: options.installTimeoutMs,
+                signal: options.signal,
+            });
             return { status: 'upgraded', from: localVer, to: remoteVer };
         }
         catch (e) {
             lastError = e.stderr || e.message || String(e);
+            if (options.signal?.aborted)
+                break;
         }
     }
     return { status: 'failed', from: localVer, to: remoteVer, error: lastError };
@@ -173,7 +198,7 @@ export async function tryUpgrade() {
  * 仅在包已安装时检查升级，未安装则跳过（resolveFn 返回 null）。
  * 用于 EC Web 等真正独立于 EvolCore 的全局包。
  */
-export async function tryUpgradeGlobalPkg(resolveInstalled, pkgName) {
+export async function tryUpgradeGlobalPkg(resolveInstalled, pkgName, options = {}) {
     if (isLinkedInstall()) {
         return { status: 'skipped' };
     }
@@ -182,9 +207,11 @@ export async function tryUpgradeGlobalPkg(resolveInstalled, pkgName) {
         return { status: 'skipped' }; // not installed, skip
     }
     const localVer = installed.version;
-    const remoteVer = await checkLatestVersion(pkgName);
+    const remoteVer = await checkLatestVersion(pkgName, options.checkTimeoutMs, options.signal);
     if (!remoteVer) {
-        return { status: 'skipped', error: 'Failed to check remote version' };
+        return options.signal?.aborted
+            ? { status: 'failed', from: localVer, error: 'Upgrade cancelled or timed out' }
+            : { status: 'skipped', error: 'Failed to check remote version' };
     }
     if (compareVersions(localVer, remoteVer) >= 0) {
         return { status: 'no-update', from: localVer };
@@ -192,11 +219,16 @@ export async function tryUpgradeGlobalPkg(resolveInstalled, pkgName) {
     let lastError;
     for (let attempt = 0; attempt < 2; attempt++) {
         try {
-            await npmInstallGlobal(`${pkgName}@latest`);
+            await npmInstallGlobal(`${pkgName}@latest`, {
+                timeoutMs: options.installTimeoutMs,
+                signal: options.signal,
+            });
             return { status: 'upgraded', from: localVer, to: remoteVer };
         }
         catch (e) {
             lastError = e.stderr || e.message || String(e);
+            if (options.signal?.aborted)
+                break;
         }
     }
     return { status: 'failed', from: localVer, to: remoteVer, error: lastError };