evolcore 0.0.32 → 0.0.34

package/dist/cli/daemon-commands.js

@@ -4,7 +4,7 @@ import os from 'os';
 import { spawn, execFile } from 'child_process';
 import { promisify } from 'util';
 import readline from 'readline';
-import { resolveRoot, resolvePaths, ensureDataDirs, getPackageRoot, agentMdPath } from '../paths.js';
+import { resolveRoot, resolvePaths, ensureDataDirs, getPackageRoot, agentMdPath, asModeOverridePath } from '../paths.js';
 import { loadDefaults, loadAllAgents, loadDaemonConfig, saveDaemonConfig } from '../config-store.js';
 import { resolveEffective } from '../config/config-manager.js';
 import { resolveAnthropicConfig } from '../agents/baseagent.js';
@@ -25,7 +25,7 @@ import { isNonAgentSessionChannel } from '../core/system-channels.js';
 import { printCodeStats } from './code-stats.js';
 import { getProcessStartTime, startTimeMatches } from '../utils/process-introspect.js';
 import { AGENT_DELEGATION_TOKEN_ENV, readDelegationCredential } from '../core/auth/agent-delegation.js';
-import { RUNTIME_HOME_ENV, WEB_CLI_BIN, WEB_PACKAGE_LATEST, WEB_PACKAGE_NAME } from '../product.js';
+import { MAIN_CLI_BIN, RUNTIME_HOME_ENV, WEB_CLI_BIN, WEB_PACKAGE_LATEST, WEB_PACKAGE_NAME } from '../product.js';
 import { rotateStdoutLog } from '../utils/log-writer.js';
 import { inspectDataMigrationRequirement } from '../core/data-migration.js';
 import { isInitCancelledError, printInitCancelHint } from './init-cancel.js';
@@ -34,8 +34,34 @@ import { listCodexAppServerProcesses, unregisterCodexAppServerProcess } from '..
 import { DEFAULT_ECWEB_PORT, ecwebService, setEcwebEnabled } from '../config/daemon-services.js';
 import { checkCodexProjectPath, inspectCodexManagedHook, ensureCodexManagedHook, runCodexHookLaunchDiagnostic, } from '../agents/codex/diagnostics.js';
 const execFileAsync = promisify(execFile);
+export async function confirmCodexHookRebind(state, packageRoot) {
+    console.log('⚠️ Codex 受管 Hook 绑定的另一套 EvolCore/Node 路径仍存在，需确认是否切换：');
+    console.log(`  现有包: ${state.managedPackageRoot}`);
+    console.log(`  现有 Node: ${state.managedNodePath}`);
+    console.log(`  当前包: ${packageRoot}`);
+    console.log(`  当前 Node: ${process.execPath}`);
+    console.log('  切换会更新机器级 Hook，影响共享此策略的 Codex 会话；不会执行数据迁移。');
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.warn(`  非交互模式不自动选择。请在交互式终端运行 ${MAIN_CLI_BIN} start 确认；也可使用现有安装的 CLI。`);
+        return false;
+    }
+    const terminal = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => {
+        let settled = false;
+        const finish = (confirmed) => {
+            if (settled)
+                return;
+            settled = true;
+            terminal.close();
+            resolve(confirmed);
+        };
+        terminal.once('close', () => finish(false));
+        terminal.once('SIGINT', () => finish(false));
+        terminal.question('  [1] 切换到当前包/Node 并修复  [2] 保留原绑定并取消本次启动 [1/2，默认 2]: ', answer => finish(answer.trim() === '1'));
+    });
+}
 /** Run before launch, and before restart stops any existing daemon. */
-export function ensureCodexHookBeforeLifecycle(onRepaired) {
+export async function ensureCodexHookBeforeLifecycle(onRepaired) {
     if (!platform.isWindows)
         return true;
     try {
@@ -53,19 +79,31 @@ export function ensureCodexHookBeforeLifecycle(onRepaired) {
             });
         if (!usesCodex)
             return true;
-        const result = ensureCodexManagedHook({
-            packageRoot: getPackageRoot(),
-            onInstallRequired: () => console.log('🔧 Codex 运行组件缺失，正在自动安装；Windows 提示管理员授权时请选择“是”。'),
+        const packageRoot = getPackageRoot();
+        const result = await ensureCodexManagedHook({
+            packageRoot,
+            repairDecision: state => confirmCodexHookRebind(state, packageRoot),
+            onInstallRequired: state => console.log(state.status === 'stale'
+                ? '🔧 Codex 受管 Hook 路径已过期，正在修复；Windows 提示管理员授权时请选择“是”。'
+                : '🔧 Codex 运行组件缺失，正在自动安装；Windows 提示管理员授权时请选择“是”。'),
         });
         if (result.status === 'installed') {
             if (result.repaired) {
-                console.log('✅ Codex Windows managed hook 已自动安装并验证');
+                console.log('✅ Codex Windows managed hook 已修复并验证');
                 onRepaired?.();
             }
             return true;
         }
-        console.error(`❌ Codex Windows managed hook 未就绪：${result.error || result.reason || result.status}`);
-        if (result.status === 'missing') {
+        if (result.cancelled) {
+            console.warn('ℹ 未确认切换 Codex 受管 Hook，保留原绑定；本次启动/重启已取消，现有服务未停止。');
+            process.exitCode = 1;
+            return false;
+        }
+        console.error(`❌ Codex Windows managed hook 启动检查未通过：${result.error || result.reason || result.status}`);
+        if (result.status === 'stale') {
+            console.error(`  本次操作已停止，现有服务未停止。请在交互式终端运行 ${MAIN_CLI_BIN} start 确认修复，或使用原安装的 CLI。`);
+        }
+        else if (result.status === 'missing') {
             console.error('  本次操作已停止。下次启动或重启会再次自动尝试安装，需要允许 Windows 管理员授权。');
         }
         else {
@@ -192,6 +230,7 @@ function buildDaemonEnv(p, opts) {
         EVENT_LOG: process.env.EVENT_LOG || 'true',
         ...(opts.diagnose ? { EVOLCORE_DIAGNOSE: '1' } : {}),
         ...(opts.bindBootstrap ? { EVOLCORE_BIND_BOOTSTRAP: '1' } : {}),
+        ...(opts.debug ? { EVOLCORE_DEBUG_MODE: '1' } : {}),
     };
 }
 function latestSourceMtime(dir) {
@@ -419,7 +458,73 @@ function resolveRunningDuration(pid, uptime) {
     const instance = scanInstances().mains.find(entry => entry.alive && entry.record.pid === pid);
     return instance ? formatRunningDuration(Date.now() - instance.record.startedAt) : '未知';
 }
-function printStartupInfo(opts = {}) {
+/**
+ * 渲染"运行模式"那一行。
+ *
+ * `daemonMode` 有值时用 daemon 实例记录里的模式（`ec status` 看的是正在跑的进程）；
+ * 没有时按当前进程判断（`ec start` 时就是这一份 CLI 即将拉起的模式）。
+ */
+/**
+ * CLI 侧按包路径判断模式。**不能用 isDevMode()**：它首次求值会读走并删除
+ * `--as-mode` 覆盖文件，那份文件只该由 daemon 消费。
+ */
+function packageIsDevMode() {
+    return !getPackageRoot().includes('node_modules');
+}
+export function describeRunMode(daemonMode, cliIsDevMode = packageIsDevMode()) {
+    const effective = daemonMode ?? (cliIsDevMode ? 'dev' : 'install');
+    const label = effective === 'install' ? '安装模式' : '开发模式';
+    const note = effective === 'install'
+        ? '（校验随包文件，篡改自动恢复）'
+        : '（不校验随包文件，可随意改动）';
+    return `运行模式:   ${label}${note}`;
+}
+/**
+ * 把本次 `--as-mode` 写进一次性覆盖文件，daemon 启动时读走并删除。
+ *
+ * 不走环境变量：环境变量会被 `ec restart` 全量继承，模式会在操作者不知情的
+ * 情况下被带到新进程。文件是一次性的，daemon 读过即删；若 daemon 最终没起来，
+ * 文件还留着，会在下一次启动时被读到——所以启动真实失败时此处清理。
+ */
+function writeAsModeOverride(asMode) {
+    const file = asModeOverridePath();
+    if (!asMode) {
+        // 没带 --as-mode：清掉上次失败启动可能残留的文件，保证这次按包路径判断
+        clearAsModeOverride(file);
+        return null;
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${asMode}\n`, 'utf-8');
+    return file;
+}
+function clearAsModeOverride(file) {
+    if (!file)
+        return;
+    try {
+        fs.rmSync(file, { force: true });
+    }
+    catch { /* ignore */ }
+}
+/** daemon 已在运行时 `--as-mode` 不会生效，明说，别让人以为切过去了。 */
+function warnAsModeNotApplied(asMode) {
+    if (!asMode)
+        return;
+    console.log(`  ⚠ --as-mode ${asMode} 未生效：daemon 已在运行，模式只在启动时确定。`);
+    console.log(`    需要切换请先 ec stop，再 ec start --as-mode ${asMode}。`);
+}
+function printAsModeNotice(asMode) {
+    if (!asMode)
+        return;
+    console.log('');
+    console.log(`🧪 本次运行模式已设为${asMode === 'install' ? '安装模式' : '开发模式'}（ec start --as-mode ${asMode}）`);
+    if (asMode === 'install') {
+        console.log('   随包发布的 kits/技能文件将按台账校验，带外改动会被自动恢复。');
+        console.log('   开发仓里请勿长期使用：本机 kits 文件会被登记进真实台账，');
+        console.log('   之后再按开发模式修改它们，会在下次以安装模式启动时被回滚。');
+    }
+    console.log('   只影响这一次启动；ec restart 不带该参数，会恢复按包路径判断。');
+}
+function printStartupInfo(opts = {}, asMode) {
     const pkgRoot = getPackageRoot();
     const isNpmInstall = pkgRoot.includes('node_modules');
     const cliRunsSource = !import.meta.url.includes('/dist/');
@@ -463,25 +568,33 @@ function printStartupInfo(opts = {}) {
     console.log(`${prefix}${version}${pidPart}${aunPart}`);
     console.log(`  包路径:     ${pkgRoot}`);
     console.log(`  安装类型:   ${isNpmInstall ? 'npm全局安装' : '开发仓(link)'}`);
+    // asMode 只是"本次请求"，是否生效要看 daemon 是否真的由这次启动拉起，标清楚别和实际模式混淆
+    const modeLine = describeRunMode(opts.runMode ?? asMode, !isNpmInstall);
+    console.log(`  ${asMode && !opts.runMode ? `${modeLine}（--as-mode 请求）` : modeLine}`);
     console.log(`  CLI执行:    ${cliRunsSource ? '源码(tsx)' : '编译产物(dist)'}`);
     console.log(`  Daemon执行: ${daemonRunsDist ? '编译产物(dist)' : '未知'}`);
     console.log(`  代码时间:   ${latestMtime ? formatLocalTime(latestMtime) : '?'}`);
 }
 export async function cmdStart(opts = {}) {
-    const cmdStartedAt = Date.now();
-    printStartupInfo();
+    // Measure from process start so the reported time includes CLI bootstrap
+    // (tsx compilation in a dev checkout), which is what the operator waits for.
+    const cmdStartedAt = Math.min(Date.now(), Math.round(performance.timeOrigin));
+    printStartupInfo(undefined, opts.asMode);
     const p = resolvePaths();
     const existingDaemon = await probeDaemon(p.socket);
     if (existingDaemon) {
         let hookRepaired = false;
-        if (!ensureCodexHookBeforeLifecycle(() => { hookRepaired = true; }))
+        if (!await ensureCodexHookBeforeLifecycle(() => { hookRepaired = true; }))
             return;
         if (hookRepaired) {
-            console.log('🔄 Codex 运行组件已补齐，正在自动重启服务以加载策略...');
+            console.log('🔄 Codex 运行组件已修复，正在自动重启服务以加载策略...');
             await cmdRestart({ diagnose: opts.diagnose });
             return;
         }
         console.log(`  EvolCore is already running (PID: ${existingDaemon.pid}, IPC reachable)`);
+        const runningRecord = scanInstances().mains.find(m => m.alive && m.record.pid === existingDaemon.pid)?.record;
+        console.log(`  当前 daemon ${describeRunMode(runningRecord?.runMode)}`);
+        warnAsModeNotApplied(opts.asMode);
         console.log(`  已在运行；已运行时长: ${resolveRunningDuration(existingDaemon.pid, existingDaemon.uptime)}；部署/脚本可直接复用当前实例`);
         return;
     }
@@ -524,7 +637,7 @@ export async function cmdStart(opts = {}) {
     // The initialization path can create the first Codex agent, so perform the
     // machine-hook check after config migration/auto-init and before any daemon
     // process is launched.
-    if (!ensureCodexHookBeforeLifecycle())
+    if (!await ensureCodexHookBeforeLifecycle())
         return;
     // 控制 AID 门禁：缺 aid 且交互式 → 只补全控制 AID + owners（不重走 baseagent 向导）。
     // 非 TTY（restart-monitor/systemd/管道）不补全（无法交互），只提示后继续启动，daemon 侧 warn 兜底。
@@ -582,6 +695,8 @@ export async function cmdStart(opts = {}) {
         console.log(`  EvolCore is already running (PID: ${aliveMains.map(m => m.record.pid).join(', ')})`);
         console.log(`  启动于: ${new Date(first.record.startedAtIso).toLocaleString()}`);
         console.log(`  启动方式: ${first.record.launchedBy}`);
+        console.log(`  当前 daemon ${describeRunMode(first.record.runMode)}`);
+        warnAsModeNotApplied(opts.asMode);
         // 报告 AID 状态
         if (status.aidLastActivity.size > 0) {
             console.log('  AID 状态:');
@@ -608,7 +723,9 @@ export async function cmdStart(opts = {}) {
     // On Windows/macOS the process environment may be unavailable, so an
     // unregistered process from this package is conservatively treated as a
     // blocker when its HOME cannot be identified.
-    const orphans = findOrphanProcesses();
+    // No live main reached this point, so the registry snapshot above is still
+    // the authoritative "known PID" set; avoid a second scan.
+    const orphans = findOrphanProcesses(status);
     const blockingOrphans = orphans.filter(o => isRuntimeOrphan(o));
     if (blockingOrphans.length > 0) {
         console.error(`❌ 检测到未登记的 EvolCore 进程（PID: ${blockingOrphans.map(o => o.pid).join(', ')}），已停止启动以避免重复连接 AUN。`);
@@ -619,10 +736,13 @@ export async function cmdStart(opts = {}) {
     reportOrphans(orphans);
     if (versionInfo.some(result => result.hasUpdate)) {
         cleanEnv();
+        // 这条路由 restart-monitor 拉起 daemon，同样靠覆盖文件把 --as-mode 带过去
+        const overrideFile = writeAsModeOverride(opts.asMode);
         const launched = await launchPackageLifecycle('start', console.log, {
             prepared: true, foreground: opts.foreground, env: buildDaemonEnv(p, opts),
         });
         if (!launched.ok) {
+            clearAsModeOverride(overrideFile);
             console.error(`❌ 启动事务未能建立：${launched.reason}`);
             process.exitCode = 1;
         }
@@ -645,6 +765,7 @@ export async function cmdStart(opts = {}) {
     const appMain = path.join(getPackageRoot(), 'dist', 'index.js');
     const daemonEnv = buildDaemonEnv(p, opts);
     if (opts.foreground) {
+        const overrideFile = writeAsModeOverride(opts.asMode);
         const child = spawn('node', ['--no-warnings=ExperimentalWarning', appMain], {
             detached: false,
             stdio: 'inherit',
@@ -653,6 +774,7 @@ export async function cmdStart(opts = {}) {
         });
         const childPid = child.pid;
         if (!childPid) {
+            clearAsModeOverride(overrideFile);
             console.error('❌ Failed to start EvolCore (process creation failed)');
             process.exit(1);
             return;
@@ -666,6 +788,22 @@ export async function cmdStart(opts = {}) {
             console.log(`  EVOLCORE_HOME: ${resolveRoot()}`);
             console.log(`  Logs: ${p.logs}/`);
             console.log(`⏱ ready in ${((Date.now() - cmdStartedAt) / 1000).toFixed(1)}s`);
+            if (opts.debug) {
+                console.log('');
+                console.log('🔧 调试模式已启用（EVOLCORE_DEBUG_MODE=1）');
+                console.log('  在宿主终端以任意 session 身份执行命令：');
+                console.log('');
+                console.log(`    ec msg send '<消息内容>' --as-session <sessionId>`);
+                console.log('    ec trigger list --as-session <sessionId>');
+                console.log('    ec memory list --as-session <sessionId>');
+                console.log('');
+                console.log('  查看可用会话（运行后将在此处列出）：');
+                console.log(`    ec msg send 'test' --as-session   # 不带 sessionId 自动列出`);
+                console.log('');
+                console.log('  注意：重启 daemon（ec restart）会清除调试模式，');
+                console.log('        需重新执行 ec start --debug 才能恢复。');
+            }
+            printAsModeNotice(opts.asMode);
             void waitForExistingEcweb(p).then((ecweb) => {
                 if (shouldPrintNoSelfAgentHints) {
                     printNoSelfAgentHints({ daemonConfig: loadDaemonConfig(), ecwebStarted: ecweb !== null, skipped });
@@ -712,6 +850,7 @@ export async function cmdStart(opts = {}) {
     const stdoutLog = path.join(p.logs, 'stdout.log');
     const out = fs.openSync(stdoutLog, 'a');
     const err = fs.openSync(stdoutLog, 'a');
+    const overrideFile = writeAsModeOverride(opts.asMode);
     const child = spawn('node', ['--no-warnings=ExperimentalWarning', appMain], {
         detached: true,
         stdio: ['ignore', out, err],
@@ -719,6 +858,12 @@ export async function cmdStart(opts = {}) {
         env: daemonEnv,
     });
     const childPid = child.pid;
+    // daemon 已在启动时读走该文件；若未能起来（pid 丢失/提前退出），清掉避免影响下次启动
+    child.once('error', () => clearAsModeOverride(overrideFile));
+    // Track liveness from the spawn handle instead of launching tasklist on
+    // every poll; the poll interval below is short enough that it matters.
+    let childExited = false;
+    child.once('exit', () => { childExited = true; });
     child.unref();
     // 等待 ready signal（最多 30 秒，AUN sidecar 超时 15s + 其他通道连接）
     const startTime = Date.now();
@@ -769,10 +914,27 @@ export async function cmdStart(opts = {}) {
                 printCodeStats(getPackageRoot(), p.logs);
             }
             console.log(`⏱ done in ${((Date.now() - cmdStartedAt) / 1000).toFixed(1)}s`);
-            // ECWeb lifecycle belongs to the daemon; the CLI only reports whether
-            // the supervised instance became healthy.
-            const ecwebStarted = await waitForExistingEcweb(p) !== null;
+            printAsModeNotice(opts.asMode);
+            if (opts.debug) {
+                console.log('');
+                console.log('🔧 调试模式已启用（EVOLCORE_DEBUG_MODE=1）');
+                console.log('  在宿主终端以任意 session 身份执行命令：');
+                console.log('');
+                console.log(`    ec msg send '<消息内容>' --as-session <sessionId>`);
+                console.log('    ec trigger list --as-session <sessionId>');
+                console.log('    ec memory list --as-session <sessionId>');
+                console.log('');
+                console.log('  查看可用会话（运行后将在此处列出）：');
+                console.log(`    ec msg send 'test' --as-session   # 不带 sessionId 自动列出`);
+                console.log('');
+                console.log('  注意：重启 daemon（ec restart）会清除调试模式，');
+                console.log('        需重新执行 ec start --debug 才能恢复。');
+            }
+            // ECWeb lifecycle belongs to the daemon; the CLI only needs its health
+            // for the no-agent hints. Waiting otherwise just holds the prompt for
+            // up to the probe timeout after the daemon is already ready.
             if (shouldPrintNoSelfAgentHints) {
+                const ecwebStarted = await waitForExistingEcweb(p) !== null;
                 printNoSelfAgentHints({ daemonConfig: loadDaemonConfig(), ecwebStarted, skipped });
             }
             return;
@@ -791,7 +953,7 @@ export async function cmdStart(opts = {}) {
             return;
         }
         // 进程已退出且无 ready signal
-        if (!platform.isProcessRunning(childPid)) {
+        if (childExited) {
             // 给进程一点时间写 ready signal（可能刚好在写入中）
             if (Date.now() - startTime > 3000) {
                 console.log('❌ Failed to start EvolCore');
@@ -806,9 +968,9 @@ export async function cmdStart(opts = {}) {
                 return;
             }
         }
-        setTimeout(checkReady, 500);
+        setTimeout(checkReady, 200);
     };
-    setTimeout(checkReady, 1000);
+    setTimeout(checkReady, 200);
 }
 function isPidReused(pid, expectedStartedAt) {
     if (expectedStartedAt === undefined)
@@ -821,7 +983,10 @@ function reportPidReused(pid) {
 }
 async function stopPid(pid, gracefulRequested = false, expectedStartedAt) {
     console.log(`🛑 Stopping EvolCore (PID: ${pid})...`);
-    if (isPidReused(pid, expectedStartedAt)) {
+    // A graceful request was accepted by the daemon that answered for this exact
+    // PID over IPC, so its identity is already proven; the start-time probe (a
+    // PowerShell launch on Windows) only guards the kill path.
+    if (!gracefulRequested && isPidReused(pid, expectedStartedAt)) {
         reportPidReused(pid);
         return true;
     }
@@ -870,7 +1035,7 @@ function isRuntimeOrphan(orphan, currentHome = resolveRoot()) {
 export async function cmdStop() {
     const status = scanInstances();
     const p = resolvePaths();
-    const initialOrphans = findOrphanProcesses();
+    const initialOrphans = findOrphanProcesses(status);
     const runtimeOrphans = initialOrphans.filter(orphan => isRuntimeOrphan(orphan, p.root));
     const ping = await probeDaemon(p.socket);
     if (ping && !hasVisibleDaemonPid(status, ping) && runtimeOrphans.length === 0) {
@@ -895,7 +1060,8 @@ export async function cmdStop() {
         process.exitCode = 1;
         return;
     }
-    await sleep(500);
+    // stopPid already observed every process leave the process table, so the
+    // records can be cleaned immediately (same reasoning as restart-monitor).
     cleanupInstances();
     if (aliveMains.length > 1) {
         console.log(`⚠ 停止了 ${aliveMains.length} 个 main 实例: ${aliveMains.map(m => m.record.pid).join(', ')}`);
@@ -904,7 +1070,10 @@ export async function cmdStop() {
 export async function cmdRestart(opts = {}) {
     const cmdStartedAt = Date.now();
     console.log('🔄 Restarting EvolCore...');
-    if (!ensureCodexHookBeforeLifecycle())
+    // 重启不带 --as-mode，模式按包路径重新判定；清掉可能残留的覆盖文件，并显示出来
+    writeAsModeOverride(undefined);
+    console.log(`  ${describeRunMode()}`);
+    if (!await ensureCodexHookBeforeLifecycle())
         return;
     const initialStatus = scanInstances();
     const socketPath = resolvePaths().socket;
@@ -1117,7 +1286,8 @@ export async function cmdStatus() {
         console.log('');
     }
     if (pid) {
-        printStartupInfo({ pid, running: true });
+        const mainRecord = aliveMains.find(m => m.record.pid === pid)?.record;
+        printStartupInfo({ pid, running: true, runMode: mainRecord?.runMode });
         if (!ping) {
             console.log('⚠ 仅确认 daemon PID 存活，IPC 不可用，不能据此判断服务健康。');
             if (ipcFailure)

package/dist/cli/debug-mode.js

@@ -0,0 +1,154 @@
+/**
+ * debug-mode.ts — `--as-session <sessionId>` 调试路径
+ *
+ * 在外部终端（宿主 CC 终端）以任意 agent 身份执行托管命令。
+ * 调用方在检查 EVOLCORE_SESSION_ID 之前先调用 resolveDebugContext(args)；
+ * 注入完成后 process.env.EVOLCORE_SESSION_ID 已设好，后续走统一托管路径。
+ */
+import fs from 'fs';
+import path from 'path';
+import { resolvePaths, debugSessionsDir } from '../paths.js';
+import { ipcQuery } from '../ipc.js';
+import { AGENT_DELEGATION_TOKEN_ENV } from '../core/auth/agent-delegation.js';
+import { buildTaskRuntimeEnv } from './task-context.js';
+const AS_SESSION_FLAG = '--as-session';
+function formatTimeAgo(ms) {
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}秒前`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}分钟前`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}小时前`;
+    return `${Math.floor(h / 24)}天前`;
+}
+function listAvailableSessions() {
+    const dir = debugSessionsDir();
+    if (!fs.existsSync(dir))
+        return { sessions: [], dirExists: false };
+    try {
+        const sessions = fs.readdirSync(dir)
+            .filter(f => f.endsWith('.json'))
+            .map(f => {
+            try {
+                return JSON.parse(fs.readFileSync(path.join(dir, f), 'utf-8'));
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((s) => s !== null && !!s.sessionId)
+            .sort((a, b) => b.writtenAt - a.writtenAt)
+            .slice(0, 20);
+        return { sessions, dirExists: true };
+    }
+    catch {
+        return { sessions: [], dirExists: true };
+    }
+}
+function printSessionList(result) {
+    const { sessions, dirExists } = result;
+    if (!dirExists) {
+        console.error('❌ 调试模式未启用。请先执行：ec start --debug');
+        return;
+    }
+    if (sessions.length === 0) {
+        console.error('ℹ️  调试模式已启用，但暂无可用会话。');
+        console.error('   请等待 agent 收到至少一条消息后再试。');
+        return;
+    }
+    console.error('\n可用会话（最近 20 个）：');
+    for (const s of sessions) {
+        const age = formatTimeAgo(Date.now() - s.writtenAt);
+        console.error(`  ${s.sessionId}  ${s.selfAid} → ${s.channelId}  ${age}`);
+    }
+}
+/**
+ * 检测命令行参数中是否包含 --as-session，若有则执行调试路径：
+ * 1. 互斥检查（托管会话中拒绝）
+ * 2. 读临时文件
+ * 3. 调 debug-issue-token IPC 现取 token
+ * 4. 注入 process.env，后续命令走统一托管路径
+ *
+ * 不带 --as-session 时直接返回，不做任何事。
+ */
+export async function resolveDebugContext(args) {
+    const flagIdx = args.indexOf(AS_SESSION_FLAG);
+    if (flagIdx === -1)
+        return;
+    // 互斥检查：托管会话里不允许 --as-session
+    if (process.env.EVOLCORE_SESSION_ID) {
+        console.error('❌ --as-session 仅限外部终端使用，托管会话中不可用');
+        process.exit(1);
+    }
+    const sessionId = args[flagIdx + 1];
+    // 不带 sessionId 或 sessionId 以 - 开头（下一个 flag）
+    if (!sessionId || sessionId.startsWith('-')) {
+        console.error('❌ --as-session 需要指定 sessionId\n');
+        console.error(`使用：ec <命令> --as-session <sessionId>`);
+        printSessionList(listAvailableSessions());
+        process.exit(1);
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(sessionId)) {
+        console.error('❌ 无效 sessionId');
+        process.exit(1);
+    }
+    // 读临时文件（session bind 时已写入）
+    const snapshotPath = path.join(debugSessionsDir(), `${sessionId}.json`);
+    if (!fs.existsSync(snapshotPath)) {
+        const result = listAvailableSessions();
+        if (!result.dirExists) {
+            console.error('❌ 调试模式未启用。请先执行：ec start --debug');
+        }
+        else {
+            console.error(`❌ 调试会话不存在：${sessionId}\n`);
+            printSessionList(result);
+        }
+        process.exit(1);
+    }
+    // 调 debug-issue-token IPC 现取 token
+    let response;
+    try {
+        response = await ipcQuery(resolvePaths().socket, { type: 'debug-issue-token', sessionId }, 5000);
+    }
+    catch (err) {
+        console.error(`❌ 无法连接 daemon：${err instanceof Error ? err.message : String(err)}`);
+        console.error('请确认 daemon 正在以 debug 模式运行：ec start --debug');
+        process.exit(1);
+    }
+    if (!response) {
+        console.error('❌ daemon 无响应，请确认 daemon 正在以 debug 模式运行：ec start --debug');
+        process.exit(1);
+    }
+    if (!response.ok) {
+        console.error(`❌ 无法获取调试 token：${response.error}`);
+        process.exit(1);
+    }
+    const { token, runtimeContext } = response;
+    // 注入 process.env，后续代码走统一托管路径
+    // 注意：去掉 daemonRuntimeEpoch——debug session 不是真实任务，
+    // 不应该受 ipc.ts 里的 daemon epoch 检查约束，否则 msg send --thread 后续命令会报
+    // "The task delegation token belongs to a previous daemon runtime"
+    const ctxWithoutEpoch = { ...runtimeContext, daemonRuntimeEpoch: undefined };
+    Object.assign(process.env, buildTaskRuntimeEnv(ctxWithoutEpoch));
+    process.env[AGENT_DELEGATION_TOKEN_ENV] = token;
+    // thread 命令从 EVOLCORE_SELF_AID 读 selfAid（不走 taskRuntimeContext），单独注入
+    if (runtimeContext.selfAid)
+        process.env.EVOLCORE_SELF_AID = runtimeContext.selfAid;
+}
+/** 从 args 中去掉 --as-session <sessionId> 两个元素，返回净化后的参数列表 */
+export function stripAsSessionArgs(args) {
+    const result = [];
+    let i = 0;
+    while (i < args.length) {
+        if (args[i] === AS_SESSION_FLAG) {
+            i += 2; // 跳过 flag 和 sessionId
+        }
+        else {
+            result.push(args[i++]);
+        }
+    }
+    return result;
+}

package/dist/cli/fs-command.js

@@ -56,7 +56,8 @@ Options:
   --content-type <mime>           上传时指定内容类型
   --public                        上传后公开可读（personal storage）
   --visibility <public|private>   chmod 可见性
-  --allow-roles <roles>           chmod 角色约束，逗号分隔
+  --allow-roles <roles>           chmod 角色约束，写法固定为单引号包住、逗号分隔，
+                                  如 --allow-roles 'owner,admin'
   -m aid:<aid>:<perms>            setfacl 新增/更新 ACL
   -x aid:<aid>                    setfacl 移除 ACL
   --source <AID>:<path>           mount 虚拟卷来源

package/dist/cli/handoff-command.js

@@ -162,6 +162,9 @@ export async function cmdHandoff(args) {
     if (!sub || isHelpFlag(sub) || wantsHelp(args)) {
         console.log(`用法: ec handoff <command> [args]
 
+⚠  ec handoff 已废弃，请改用话题链（ec thread + ec msg send --thread）。
+   本命令保留以兼容现有脚本，将在 P2 后续版本中移除。
+
 Commands:
   return [handoff-id] [content]       提交一个回流结果；required 可用同一 ID 追加多个结果
   return [handoff-id] --text-from-file <path>