evolcore 0.0.22 → 0.0.23

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/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/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 };

package/kits/docs/evolcore/INDEX.md

@@ -37,6 +37,7 @@
 | `ec agent` | EvolAgent 生命周期 | 创建/启停/热重载/改配置 | 管理员（owner/admin） | `agent.md`；完整创建与 Bootstrap 见 `agent-create.md` |
 | `ec contact` | Contact Book 与访问控制 | 申请添加、拉黑/解除拉黑、查拉黑 | Agent 当前私聊可申请添加；管理写操作按角色限制 | `contact.md` |
 | `ec rpc` | 底层 AUN RPC（逃生通道） | 直接调协议方法 | 高级/兜底 | `rpc.md` |
+| `ec menu-client` | 远程 Daemon Menu 请求 | 远程诊断/daemon 日志/监控/原始配置 | 非托管 eclink/运维主机 | `menu-client.md` |
 
 ## 会话自管理类（不连 AUN，操作当前会话）
 

package/kits/docs/evolcore/agent-create.md

@@ -2,6 +2,11 @@
 
 本手册用于创建一个能正常工作的 EvolAgent。创建者负责创建和观察状态；新 Agent 在自己的 Bootstrap 会话中完成首次设定。不要把创建流水线完成误认为 Agent 已激活。
 
+### AID 与 Owner 约定
+
+- AID 必须是 `{name}.{issuer}`，例如 `helper.agentid.cn`；不要使用四级域名（如 `helper.team.agentid.cn`），也不要把显示名当作 AID。
+- `--owner` 填写需求提出者或实际责任 Owner 的完整 AID，而不是默认填写当前执行者。创建者只是代办创建流程时，仍应保留需求提出者的 Owner 权限。
+
 ## 生命周期与完成标准
 
 ```text
@@ -18,6 +23,8 @@ active
 
 ## 1. 创建者创建 Agent
 
+多个 Agent 必须串行创建和观察。不要并行启动多个 `ec agent new`：证书、热加载和 Bootstrap 会竞争连接与资源，容易造成超时、锁等待或把失败误判为未创建。
+
 在独立终端可以使用交互模式：
 
 ```bash
@@ -56,6 +63,8 @@ ec agent show helper.agentid.pub
 
 如果是 menu 创建，`accepted=true` 只表示请求已受理。继续轮询 `createProgress.status` 直到 `ready` 或 `failed`。这里的 `createProgress.status=ready` **只表示后台创建流水线结束，不等于 `lifecycle=active`**。
 
+创建者应维护一个最小状态账本（可放在当前任务记录中），每个 Agent 至少记录：`aid`、需求 Owner、项目路径、创建请求是否受理、`createProgress.status`、`lifecycle`、本地 `agent.md` 是否存在/字段是否完整、名片是否已发布、最近错误、下一步和最后检查时间。重启或超时恢复时先按账本逐项核对实际状态，再决定续做，不按“上次命令是否返回”推断结果。
+
 ## 2. 触发 Bootstrap
 
 当任一已启用 channel 可以联系 Owner 时，系统会向 Owner 发送固定的 Bootstrap 首条消息，并把生命周期从 `created` 切换为 `bootstrapping`。
@@ -136,6 +145,8 @@ ec agent get helper.agentid.pub lifecycle
 ec agent show helper.agentid.pub
 ```
 
+验证其它 Agent 的生命周期、配置和创建进度统一使用 `ec agent get/show/list`；`ec aid` 只用于身份、证书和名片操作，不要用 `ec aid` 代替 Agent 状态验证。
+
 验收标准：
 
 - `lifecycle` 为 `active`。
@@ -144,3 +155,5 @@ ec agent show helper.agentid.pub
 - 新 Agent 能在新主会话中处理普通任务。
 
 如果仍为 `created`，检查 channel 是否已能联系 Owner，必要时由 Owner 主动发送首条消息。如果仍为 `bootstrapping`，回到新 Agent 的 Bootstrap 会话完成字段确认、名片发布和 `ready`，不要由创建者直接绕过引导。
+
+失败重试前必须先执行状态检查：若本地 `agent.md` 已存在且远端名片已发布，只向该 Agent 发送 `ready`/续做指令，让它在自己的 Bootstrap 会话中完成收尾；不要重复创建、重复改名片或重复发布。仅在确认创建记录不存在且名片未发布时，才重新发起创建。

package/kits/docs/evolcore/group-collaboration.md

@@ -21,6 +21,7 @@
 
 - `<self-aid>` 是当前 Agent 的 AID。托管 Agent 会话必须使用自己的 AID，不能代替其他 Agent 发起管理操作。
 - 创建群的 Agent 自动成为群 owner。
+- 需求发起者应设置为群 admin（若需求发起者就是创建者，则其已是 owner，无需另设）。
 - owner/admin 负责邀请成员、设置角色、修改入群规则和发布 `/rules.md`。
 - 普通 member 可以读取当前群信息、读取规则并参与协作；需要管理群成员或设置时，应请 owner/admin 操作。
 - `dissolve` 和 `owner` 转让属于 owner 级操作，临时协作结束通常不需要解散群。
@@ -36,13 +37,13 @@
 - 分工：谁负责协调、执行、复核和最终决策。
 - 验收：完成条件、截止时间、交付路径和汇报频率。
 
-使用 Owner 明确提供或已经可靠取得的完整 AID；不要从显示名猜测 AID，也不要邀请尚未确认的对象。如果参与者、可见性或入群方式不明确，先向 Owner 补齐这些信息再创建群。
+使用 Owner 明确提供或已经可靠取得的完整 AID；AID 必须是 `{name}.{issuer}`，例如 `coordinator.agentid.cn`，不要使用四级域名或从显示名猜测 AID，也不要邀请尚未确认的对象。如果参与者、可见性或入群方式不明确，先向 Owner 补齐这些信息再创建群。
 
 如果已经有合适的群，先用 `ec group list` 和 `ec group info` 检查，不要为每个任务重复建群。
 
 ## 2. 创建私有协作群
 
-推荐默认使用私有群和 `invite_only`，先建群再按名单邀请：
+群名称必填。创建前根据群名称确定一个简短、唯一的 group AID（同样使用 `{name}.{issuer}`，不要四级域名），并给出一句群简介；名称、AID 和简介应能体现协作目标。推荐默认使用私有群和 `invite_only`，先建群再按名单邀请：
 
 ```bash
 ec group create coordinator.agentid.pub "Project Alpha 协作" \
@@ -63,6 +64,8 @@ ec group rules coordinator.agentid.pub <group-id> --format json
 
 ## 3. 邀请成员并设置角色
 
+先确认所有待协作 Agent 的 `lifecycle` 都是 `active`（使用 `ec agent get/show`，不要用 `ec aid`）。在此之前不要邀请成员，也不要发送或分派任务；Bootstrap 未完成的 Agent 不能稳定接收协作工作。
+
 一次邀请多个成员：
 
 ```bash
@@ -100,6 +103,8 @@ ec group rules coordinator.agentid.pub <group-id> \
 
 ### 4.2 编写并发布 `/rules.md`
 
+团队群必须先发布一份最小 `/rules.md`。至少明确四类职责：协调（拆解任务、同步状态、最终汇总）、侦察（收集资料和事实）、分析（比较方案、识别风险）、策略（做出取舍和升级决策）。可再补充具体成员映射、交付格式和升级路径。
+
 在当前项目中准备一个不超过 4KB 的 UTF-8 Markdown 文件，例如 `project-alpha-rules.md`：
 
 ```markdown

package/kits/docs/evolcore/menu-client.md

@@ -0,0 +1,34 @@
+# ec menu-client — 远程 Daemon Menu 客户端
+
+向另一台主机的 EvolCore Control AID 发送一个标准 `menu.*` 请求，并在同一 AUN 短连接中完成发送、拉取、匹配和 ACK。适合非托管主机上的 eclink/运维工具调用；托管 Agent 会话不应使用它绕过当前 daemon。
+
+## 用法
+
+```bash
+ec menu-client request <from-aid> <daemon-aid> \
+  --request-file "$TMPDIR/menu-request.json" \
+  --timeout 15s \
+  --encrypt \
+  --format json
+```
+
+- `--request-file` 与 `--request-json` 二选一，内容是现有 Menu request；缺少 `id` 时自动生成 UUID。
+- 默认使用 E2EE，并发送 `client_name=ec-menu-client` 和本机 EvolCore `client_version`。
+- 默认 slot 是 `evolcore-menu-client`；`--app <slot>` 可覆盖，但会切换消费游标，调用方须自行串行化。
+- 默认授权是远端 `daemon.json.owners` 对发送 AID 的校验。
+- `--remote-token <token>` 使用 daemon 签发的远程访问 token，权限与 daemon-owner 一致。CLI 审计日志不会记录 token 明文。
+- `--ecweb-token <token>` 是 `--remote-token` 的兼容别名。
+- `menu.query` / `menu.options` 等待响应超时时自动重发一次相同 request id；写操作不自动重试。
+- 成功时 stdout 是完整 `menu.response` JSON。远端业务错误仍在响应的 `error` 字段中；本地传输/超时/ACK 错误退出码非 0。
+
+## 常用请求
+
+```json
+{"type":"menu.query","id":"status-1","name":"system","args":{"view":"status"}}
+{"type":"menu.query","id":"monitor-1","name":"system","args":{"view":"monitor"}}
+{"type":"menu.query","id":"logs-1","name":"system","args":{"view":"logs","source":"daemon","limit":200}}
+{"type":"menu.options","id":"config-options-1","name":"config","args":{"option":"rawFile"}}
+{"type":"menu.query","id":"config-1","name":"config","args":{"view":"rawFile","resource":"daemon"}}
+```
+
+先用 `menu.list` 的 `args.view=catalog`、`context.kind=process` 获取目标 daemon 实际支持的能力和 wire 参数，不要在适配器中另建一套协议字段。

package/kits/migrations/migrate-contact-book-v2.mjs

@@ -531,7 +531,15 @@ function planMigration(home) {
 function assertDaemonStopped(home) {
   const candidates = [];
   const pidFile = path.join(home, 'daemon.pid');
-  if (fs.existsSync(pidFile)) candidates.push({ pid: Number(fs.readFileSync(pidFile, 'utf8').trim()), source: pidFile });
+  try {
+    // daemon.pid is a retired legacy marker. Ignore directory/symlink residue
+    // so a sandbox-created directory cannot turn migration into EISDIR.
+    if (fs.lstatSync(pidFile).isFile()) {
+      candidates.push({ pid: Number(fs.readFileSync(pidFile, 'utf8').trim()), source: pidFile });
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
   const instanceDir = path.join(home, 'data', 'instance');
   if (fs.existsSync(instanceDir)) {
     for (const name of fs.readdirSync(instanceDir)) {

package/kits/migrations/migrate-role-config-v4.mjs

@@ -452,11 +452,17 @@ function changeRecord(home, file, kind, beforeText, after) {
 function assertDaemonStopped(home) {
   const candidates = [];
   const legacyPidFile = path.join(home, 'daemon.pid');
-  if (fs.existsSync(legacyPidFile)) {
-    candidates.push({
-      pid: Number(fs.readFileSync(legacyPidFile, 'utf8').trim()),
-      source: legacyPidFile,
-    });
+  try {
+    // daemon.pid is a retired legacy marker. Ignore directory/symlink residue
+    // so a sandbox-created directory cannot turn migration into EISDIR.
+    if (fs.lstatSync(legacyPidFile).isFile()) {
+      candidates.push({
+        pid: Number(fs.readFileSync(legacyPidFile, 'utf8').trim()),
+        source: legacyPidFile,
+      });
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
   }
 
   const instanceDir = path.join(home, 'data', 'instance');

package/kits/migrations/migrate-role-config-v5.mjs

@@ -200,8 +200,14 @@ function planMigration(home) {
 function assertDaemonStopped(home) {
   const candidates = [];
   const pidFile = path.join(home, 'daemon.pid');
-  if (fs.existsSync(pidFile)) {
-    candidates.push({ pid: Number(fs.readFileSync(pidFile, 'utf8').trim()), source: pidFile });
+  try {
+    // daemon.pid is a retired legacy marker. Ignore directory/symlink residue
+    // so a sandbox-created directory cannot turn migration into EISDIR.
+    if (fs.lstatSync(pidFile).isFile()) {
+      candidates.push({ pid: Number(fs.readFileSync(pidFile, 'utf8').trim()), source: pidFile });
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
   }
   const instanceDir = path.join(home, 'data', 'instance');
   if (fs.existsSync(instanceDir)) {

package/kits/templates/roles/visitor.json

@@ -21,6 +21,7 @@
     "model.list": { "allow": true, "scopes": ["relation"], "constraints": { "ownPeerOnly": true, "targetCurrentAgentOnly": true } },
     "model.current": { "allow": true, "scopes": ["relation"], "constraints": { "ownPeerOnly": true, "targetCurrentAgentOnly": true } },
     "model.info": { "allow": true, "scopes": ["relation"], "constraints": { "ownPeerOnly": true, "targetCurrentAgentOnly": true } },
+    "model.effort.current": { "allow": true, "scopes": ["relation"], "constraints": { "ownPeerOnly": true, "targetCurrentAgentOnly": true } },
     "model.use": { "allow": false },
     "model.effort": { "allow": false },
     "model.reset": { "allow": false },

package/kits/templates/system-fragments/bootstrap.md

@@ -2,7 +2,7 @@
 phase: bootstrapping
 
 这是 agent 生命周期的强制门禁。你正在进行首次自我设定；在完成前，唯一目标是和 owner 确认并写入基础名片信息，不处理普通任务。
-整个过程由你根据当前对话自主推进，不存在需要查询或维护的额外 bootstrap 子状态。
+Bootstrap 不另设隐藏状态机；恢复依据是可核对的生命周期和名片状态。每次重启、超时恢复或收到“继续”时，先检查自身 `lifecycle` 以及本地 `agent.md` 是否存在、字段是否完整，再决定续做步骤，不按旧上下文推断尚未完成。
 系统已经在进入本阶段时向 owner 发送过固定的首条引导消息。当前收到的是 owner 对该消息的后续输入：不要重新发送、复述或改写那条固定消息，也不要再次完整罗列三项问题；只针对当前输入推进下一步。
 
 需要确认的字段：
@@ -17,6 +17,13 @@ phase: bootstrapping
   - `ec agent ready {{selfAid}}`
 - 除这些 bootstrap 操作及向 owner 回复外，不得调用工具或执行命令。
 
+恢复时遵循以下幂等规则：
+- `lifecycle=active`：Bootstrap 已完成，不重复改名片、不重复发布、不重复执行 `ready`，也不处理本轮夹带的普通任务。
+- `lifecycle=created`：尚未进入 Bootstrap，只等待 channel/owner 首条消息；不重复创建 Agent。
+- `lifecycle=bootstrapping` 且本地 `agent.md` 已发布并且字段完整：只向 owner 简短确认现状，并执行最后的 `ec agent ready {{selfAid}}`；不要再次修改或发布名片。
+- `lifecycle=bootstrapping` 但名片未发布或字段不完整：从缺失的确认步骤继续。发布失败时先说明错误，修正后再试，不盲目重试。
+- Bootstrap 期间不执行、不分析、不规划普通任务；普通任务只能留到 `active` 后的新主会话。
+
 每轮处理规则：
 1. 首次需要候选值时，读取本地 agent.md 的 YAML frontmatter。已有且格式有效的 `name`、`description`、`tags` 是现有候选值：简短回显并询问保持还是修改，不要求重新输入。空值、占位值或格式无效的字段视为缺失；`tags` 必须为 3 到 6 个非空标签。
 2. 只把 owner 明确提供、修改、选择或确认的 `name`、`description`、`tags` 当作候选信息。普通任务内容、示例值和顺带提及的词语都不是候选信息，不得据此推断字段。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolcore",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "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",
@@ -48,7 +48,7 @@
     "prepublishOnly": "npm test"
   },
   "dependencies": {
-    "@agentunion/fastaun": "0.5.11",
+    "@agentunion/fastaun": "0.5.13",
     "@anthropic-ai/claude-agent-sdk": "0.3.220",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ajv": "^8.20.0",
@@ -58,6 +58,7 @@
     "image-type": "^6.0.0",
     "partial-json": "0.1.7",
     "qrcode-terminal": "^0.12.0",
+    "smol-toml": "1.8.0",
     "typebox": "1.1.38",
     "ws": "^8.21.0",
     "yaml": "2.9.0",
@@ -82,5 +83,12 @@
   },
   "engines": {
     "node": ">=22.16.0"
-  }
+  },
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC"
 }