metame-cli 1.5.0 → 1.5.1

package/scripts/daemon.js

@@ -35,13 +35,14 @@ process.on('uncaughtException', (err) => {
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { execSync, execFileSync, spawn } = require('child_process');
+const { execSync, execFileSync, execFile, spawn } = require('child_process');
 
 const HOME = os.homedir();
 const METAME_DIR = path.join(HOME, '.metame');
 const CONFIG_FILE = path.join(METAME_DIR, 'daemon.yaml');
 const STATE_FILE = path.join(METAME_DIR, 'daemon_state.json');
 const PID_FILE = path.join(METAME_DIR, 'daemon.pid');
+const LOCK_FILE = path.join(METAME_DIR, 'daemon.lock');
 const LOG_FILE = path.join(METAME_DIR, 'daemon.log');
 const BRAIN_FILE = path.join(HOME, '.claude_profile.yaml');
 const DISPATCH_DIR = path.join(METAME_DIR, 'dispatch');
@@ -59,7 +60,7 @@ const CLAUDE_BIN = (() => {
   ];
   try {
     const cmd = process.platform === 'win32' ? 'where claude' : 'which claude 2>/dev/null';
-    return execSync(cmd, { encoding: 'utf8' }).trim().split('\n')[0];
+    return execSync(cmd, { encoding: 'utf8', ...(process.platform === 'win32' ? { windowsHide: true } : {}) }).trim().split('\n')[0];
   } catch {}
   for (const p of candidates) { if (fs.existsSync(p)) return p; }
   return 'claude'; // fallback: hope it's in PATH
@@ -144,7 +145,7 @@ const { createFileBrowser } = require('./daemon-file-browser');
 const { createPidManager, setupRuntimeWatchers } = require('./daemon-runtime-lifecycle');
 const { createNotifier } = require('./daemon-notify');
 const { createClaudeEngine } = require('./daemon-claude-engine');
-const { createEngineRuntimeFactory, detectDefaultEngine, ENGINE_DISTILL_MAP } = require('./daemon-engine-runtime');
+const { createEngineRuntimeFactory, detectDefaultEngine, ENGINE_MODEL_CONFIG, ENGINE_DISTILL_MAP, ENGINE_DEFAULT_MODEL } = require('./daemon-engine-runtime');
 const { createCommandRouter } = require('./daemon-command-router');
 const { createTaskScheduler } = require('./daemon-task-scheduler');
 const { createAgentTools } = require('./daemon-agent-tools');
@@ -164,6 +165,11 @@ function getDaemonProviderEnv() {
   try { return providerMod.buildDaemonEnv(); } catch { return {}; }
 }
 
+function getDistillModel() {
+  if (!providerMod || typeof providerMod.getDistillModel !== 'function') return 'haiku';
+  try { return providerMod.getDistillModel(); } catch { return 'haiku'; }
+}
+
 function getActiveProviderEnv() {
   if (!providerMod) return {};
   try { return providerMod.buildActiveEnv(); } catch { return {}; }
@@ -206,9 +212,10 @@ const {
   cpExtractTimestamp,
   cpDisplayLabel,
   gitCheckpoint,
+  gitCheckpointAsync,
   listCheckpoints,
   cleanupCheckpoints,
-} = createCheckpointUtils({ execSync, path, log });
+} = createCheckpointUtils({ execSync, execFile, path, log });
 
 // ---------------------------------------------------------
 // CONFIG & STATE
@@ -894,6 +901,8 @@ function dispatchTask(targetProject, message, config, replyFn, streamOptions = n
  * Spawn session-summarize.js for sessions that have been idle 2-24 hours.
  * Called on sleep mode entry. Skips sessions that already have a fresh summary.
  */
+const MAX_CONCURRENT_SUMMARIES = 3;
+
 function spawnSessionSummaries() {
   const scriptPath = path.join(__dirname, 'session-summarize.js');
   if (!fs.existsSync(scriptPath)) return;
@@ -901,18 +910,43 @@ function spawnSessionSummaries() {
   const now = Date.now();
   const TWO_HOURS = 2 * 60 * 60 * 1000;
   const SEVEN_DAYS = 7 * 24 * 60 * 60 * 1000;
+  // Collect eligible sessions, sort by most recently active first
+  const eligible = [];
   for (const [cid, sess] of Object.entries(state.sessions || {})) {
-    if (!sess.id || !sess.started) continue;
+    // Support both old flat format and new per-engine format
+    let sessionId, started;
+    if (sess.engines) {
+      const active = Object.values(sess.engines).find(s => s.id && s.started);
+      if (!active) continue;
+      sessionId = active.id;
+      started = true;
+    } else {
+      sessionId = sess.id;
+      started = sess.started;
+    }
+    if (!sessionId || !started) continue;
     const lastActive = sess.last_active || 0;
     const idleMs = now - lastActive;
     if (idleMs < TWO_HOURS || idleMs > SEVEN_DAYS) continue;
-    // Skip if summary is already newer than last activity
     if ((sess.last_summary_at || 0) > lastActive) continue;
+    eligible.push({ cid, sess: { ...sess, id: sessionId, started }, lastActive });
+  }
+  eligible.sort((a, b) => b.lastActive - a.lastActive);
+
+  let spawned = 0;
+  for (const { cid, sess } of eligible) {
+    if (spawned >= MAX_CONCURRENT_SUMMARIES) {
+      log('INFO', `[DAEMON] Session summary concurrency limit (${MAX_CONCURRENT_SUMMARIES}) reached, deferring remaining`);
+      break;
+    }
+    const idleMs = now - (sess.last_active || 0);
     try {
       const child = spawn(process.execPath, [scriptPath, cid, sess.id], {
         detached: true, stdio: 'ignore',
+        ...(process.platform === 'win32' ? { windowsHide: true } : {}),
       });
       child.unref();
+      spawned++;
       log('INFO', `[DAEMON] Session summary spawned for ${cid} (idle ${Math.round(idleMs / 3600000)}h)`);
     } catch (e) {
       log('WARN', `[DAEMON] Failed to spawn session summary: ${e.message}`);
@@ -1253,11 +1287,13 @@ const {
   buildSessionCardElements,
   listProjectDirs,
   getSession,
+  getSessionForEngine,
   createSession,
   getSessionName,
   writeSessionName,
   markSessionStarted,
   watchSessionFiles,
+  isEngineSessionValid,
 } = createSessionStore({
   fs,
   path,
@@ -1361,6 +1397,16 @@ if (providerMod && typeof providerMod.setEngine === 'function') {
 }
 log('INFO', `Default engine: ${_defaultEngine} (detected: ${detectedEngine})`);
 
+// One-time migration: daemon.model (legacy) → daemon.models.<engine>
+try {
+  const _migCfg = yaml.load(fs.readFileSync(CONFIG_FILE, 'utf8')) || {};
+  if (_migCfg.daemon && _migCfg.daemon.model && !_migCfg.daemon.models) {
+    _migCfg.daemon.models = { [_defaultEngine]: _migCfg.daemon.model };
+    writeConfigSafe(_migCfg);
+    log('INFO', `Migrated daemon.model="${_migCfg.daemon.model}" → daemon.models.${_defaultEngine}`);
+  }
+} catch { /* ignore */ }
+
 function getDefaultEngine() {
   return _defaultEngine;
 }
@@ -1371,16 +1417,24 @@ function setDefaultEngine(engine) {
   st.default_engine = engine;
   saveState(st);
   if (providerMod) {
-    // Couple distill model
+    // Sync distill model to this engine's default
     if (typeof providerMod.setDistillModel === 'function') {
-      const paired = ENGINE_DISTILL_MAP[engine] || ENGINE_DISTILL_MAP.claude;
-      try { providerMod.setDistillModel(paired); } catch { /* ignore */ }
+      const distill = (ENGINE_MODEL_CONFIG[engine] || ENGINE_MODEL_CONFIG.claude).distill;
+      try { providerMod.setDistillModel(distill); } catch { /* ignore */ }
     }
-    // Couple distill binary
     if (typeof providerMod.setEngine === 'function') {
       try { providerMod.setEngine(engine); } catch { /* ignore */ }
     }
   }
+  // Migrate old daemon.model → daemon.models[engine] on first switch
+  try {
+    const cfg = yaml.load(fs.readFileSync(CONFIG_FILE, 'utf8')) || {};
+    if (!cfg.daemon) cfg.daemon = {};
+    if (cfg.daemon.model && !cfg.daemon.models) {
+      cfg.daemon.models = { [engine]: cfg.daemon.model };
+      writeConfigSafe(cfg);
+    }
+  } catch { /* ignore */ }
 }
 
 const getEngineRuntime = createEngineRuntimeFactory({
@@ -1413,6 +1467,7 @@ const {
   recordTokens,
   buildProfilePreamble,
   getDaemonProviderEnv,
+  getDistillModel,
   log,
   physiologicalHeartbeat,
   isUserIdle,
@@ -1460,6 +1515,7 @@ const { handleAdminCommand } = createAdminCommandHandler({
   saveState,
   getDefaultEngine,
   setDefaultEngine,
+  getDistillModel,
 });
 
 const { handleSessionCommand } = createSessionCommandHandler({
@@ -1519,12 +1575,15 @@ const { spawnClaudeAsync, askClaude } = createClaudeEngine({
   sendFileButtons,
   findSessionFile,
   listRecentSessions,
+  isEngineSessionValid,
   getSession,
+  getSessionForEngine,
   createSession,
   getSessionName,
   writeSessionName,
   markSessionStarted,
   gitCheckpoint,
+  gitCheckpointAsync,
   recordTokens,
   skillEvolution,
   touchInteraction,
@@ -1617,6 +1676,7 @@ const { handleExecCommand } = createExecCommandHandler({
   createSession,
   findSessionFile,
   loadConfig,
+  getDistillModel,
 });
 
 const { handleOpsCommand } = createOpsCommandHandler({
@@ -1705,6 +1765,72 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+let daemonLockFd = null;
+function isPidAlive(pid) {
+  if (!pid || Number.isNaN(pid)) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function acquireDaemonLock() {
+  const restartFromPid = parseInt(process.env.METAME_RESTART_FROM_PID || '', 10);
+  const maxAttempts = restartFromPid ? 6 : 2;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      daemonLockFd = fs.openSync(LOCK_FILE, 'wx');
+      fs.writeFileSync(daemonLockFd, JSON.stringify({
+        pid: process.pid,
+        started_at: new Date().toISOString(),
+      }), 'utf8');
+      return true;
+    } catch (e) {
+      if (e.code !== 'EEXIST') {
+        log('ERROR', `Failed to acquire daemon lock: ${e.message}`);
+        return false;
+      }
+      try {
+        const raw = fs.readFileSync(LOCK_FILE, 'utf8');
+        const meta = JSON.parse(raw || '{}');
+        const ownerPid = parseInt(meta.pid, 10);
+        if (isPidAlive(ownerPid)) {
+          // Restart handoff: allow child to wait for parent to exit and take over.
+          if (restartFromPid && ownerPid === restartFromPid) {
+            for (let i = 0; i < 30; i++) {
+              sleepSync(500);
+              if (!isPidAlive(ownerPid)) break;
+            }
+            if (isPidAlive(ownerPid)) {
+              log('WARN', `Restart handoff timed out, previous daemon still alive (PID: ${ownerPid})`);
+              if (attempt < maxAttempts - 1) continue;
+              return false;
+            }
+            try { fs.unlinkSync(LOCK_FILE); } catch { /* ignore */ }
+            continue;
+          }
+          log('WARN', `Another daemon instance owns lock (PID: ${meta.pid})`);
+          return false;
+        }
+      } catch {
+        // Ignore malformed lock metadata and treat as stale.
+      }
+      try { fs.unlinkSync(LOCK_FILE); } catch { /* ignore */ }
+    }
+  }
+  return false;
+}
+
+function releaseDaemonLock() {
+  try {
+    if (daemonLockFd !== null) fs.closeSync(daemonLockFd);
+  } catch { /* ignore */ }
+  daemonLockFd = null;
+  try { if (fs.existsSync(LOCK_FILE)) fs.unlinkSync(LOCK_FILE); } catch { /* ignore */ }
+}
+
 // ---------------------------------------------------------
 // MAIN
 // ---------------------------------------------------------
@@ -1724,7 +1850,9 @@ async function main() {
   // Config validation: warn on unknown/suspect fields
   const KNOWN_SECTIONS = ['daemon', 'telegram', 'feishu', 'heartbeat', 'budget', 'projects'];
   const KNOWN_DAEMON = [
-    'model',
+    'model',          // legacy (still valid as fallback)
+    'models',         // per-engine model map: { claude, codex }
+    'distill_models', // per-engine distill model map
     'log_max_size',
     'heartbeat_check_interval',
     'session_allowed_tools',
@@ -1736,7 +1864,8 @@ async function main() {
     'enable_nl_mac_control',
     'enable_nl_mac_fallback',
   ];
-  const VALID_MODELS = ['sonnet', 'opus', 'haiku'];
+  // All known models across all engines (for legacy daemon.model validation only)
+  const BUILTIN_CLAUDE_MODELS = ENGINE_MODEL_CONFIG.claude.options;
   for (const key of Object.keys(config)) {
     if (!KNOWN_SECTIONS.includes(key)) log('WARN', `Config: unknown section "${key}" (typo?)`);
   }
@@ -1744,17 +1873,22 @@ async function main() {
     for (const key of Object.keys(config.daemon)) {
       if (!KNOWN_DAEMON.includes(key)) log('WARN', `Config: unknown daemon.${key} (typo?)`);
     }
-    if (config.daemon.model && !VALID_MODELS.includes(config.daemon.model)) {
-      // Custom model names are valid when using non-anthropic providers
+    // Validate legacy daemon.model (only warn if anthropic provider + unknown Claude model)
+    if (config.daemon.model && !BUILTIN_CLAUDE_MODELS.includes(config.daemon.model)) {
       const activeProv = providerMod ? providerMod.getActiveName() : 'anthropic';
-      if (activeProv === 'anthropic') {
-        log('WARN', `Config: daemon.model="${config.daemon.model}" is not a known model`);
+      if (activeProv === 'anthropic' && _defaultEngine === 'claude') {
+        log('WARN', `Config: daemon.model="${config.daemon.model}" is not a known Claude model`);
       } else {
-        log('INFO', `Config: custom model "${config.daemon.model}" for provider "${activeProv}"`);
+        log('INFO', `Config: model "${config.daemon.model}" for engine "${_defaultEngine}" / provider "${activeProv}"`);
       }
     }
   }
 
+  if (!acquireDaemonLock()) {
+    process.exit(0);
+  }
+  process.on('exit', releaseDaemonLock);
+
   // Takeover: kill any existing daemon
   killExistingDaemon();
   writePid();
@@ -1819,6 +1953,32 @@ async function main() {
   // Start heartbeat scheduler
   let heartbeatTimer = startHeartbeat(config, notifyFn, notifyPersonalFn);
 
+  let shuttingDown = false;
+  function spawnReplacementDaemon(reason) {
+    try {
+      const replacementScript = path.join(METAME_DIR, 'daemon.js');
+      const bg = spawn(process.execPath, [replacementScript], {
+        detached: process.platform !== 'win32',
+        stdio: 'ignore',
+        windowsHide: true,
+        cwd: METAME_DIR,
+        env: {
+          ...process.env,
+          HOME,
+          USERPROFILE: HOME,
+          METAME_ROOT: process.env.METAME_ROOT || path.dirname(__filename),
+          METAME_RESTART_FROM_PID: String(process.pid),
+        },
+      });
+      bg.unref();
+      log('INFO', `[RESTART] Spawned replacement daemon (PID: ${bg.pid}) reason=${reason}`);
+      return true;
+    } catch (e) {
+      log('ERROR', `[RESTART] Failed to spawn replacement daemon: ${e.message}`);
+      return false;
+    }
+  }
+
   const runtimeWatchers = setupRuntimeWatchers({
     fs,
     path,
@@ -1839,8 +1999,8 @@ async function main() {
     getHeartbeatTimer: () => heartbeatTimer,
     setHeartbeatTimer: (next) => { heartbeatTimer = next; },
     onRestartRequested: () => {
-      // Reuse full shutdown logic (kill child processes, clean PID, stop bridges)
-      shutdown().catch(() => process.exit(0));
+      // Reuse full shutdown logic, then self-spawn replacement.
+      shutdown({ restartReason: 'daemon-script-changed' }).catch(() => process.exit(1));
     },
   });
   // Expose reloadConfig to handleCommand via closure
@@ -1872,7 +2032,17 @@ async function main() {
   }
 
   // Graceful shutdown
-  const shutdown = async () => {
+  const shutdown = async (opts = {}) => {
+    if (shuttingDown) return;
+    shuttingDown = true;  // set immediately to prevent double-spawn race condition
+    if (opts.restartReason) {
+      const spawned = spawnReplacementDaemon(opts.restartReason);
+      if (!spawned) {
+        log('ERROR', `[RESTART] Abort shutdown: failed to spawn replacement (${opts.restartReason})`);
+        shuttingDown = false;
+        return;
+      }
+    }
     log('INFO', 'Daemon shutting down...');
     await notifyActiveUsers('关闭').catch(() => {});
     runtimeWatchers.stop();
@@ -1891,6 +2061,7 @@ async function main() {
     activeProcesses.clear();
     try { if (fs.existsSync(ACTIVE_PIDS_FILE)) fs.unlinkSync(ACTIVE_PIDS_FILE); } catch { }
     cleanPid();
+    releaseDaemonLock();
     const s = loadState();
     s.pid = null;
     saveState(s);
@@ -1914,7 +2085,7 @@ async function main() {
         st.watchdog_restart = new Date().toISOString();
         st.watchdog_stall_seconds = Math.round(elapsed / 1000);
         saveState(st);
-        process.exit(1); // caffeinate or launchd will restart us
+        shutdown({ restartReason: 'watchdog-stall' }).catch(() => process.exit(1));
       }
     } catch (e) {
       log('WARN', `[WATCHDOG] Check failed: ${e.message}`);

package/scripts/distill.js

@@ -1409,5 +1409,9 @@ if (require.main === module) {
     } else {
       console.log(`💤 ${result.summary}`);
     }
+    // Report estimated token usage for daemon budget tracking
+    // Each callHaiku invocation ~2k-5k tokens; estimate from signal count + result size
+    const estTokens = Math.ceil(((result.signalCount || 1) * 500) + ((result.summary || '').length / 4));
+    console.log(`__TOKENS__:${estTokens}`);
   })();
 }

package/scripts/docs/maintenance-manual.md

@@ -72,13 +72,30 @@ feishu:
   - 仅在“当前默认引擎对应 CLI 不可用”时判为故障
   - 自定义 provider 下允许任意合法模型名（不再强制 sonnet/opus/haiku）
 
-## 5. 运行时文件与状态
+## 5. Agent Soul 身份层
+
+- 集中存储：`~/.metame/agents/<agent_id>/`（soul.md、memory-snapshot.md、agent.yaml）
+- 项目视图：`<cwd>/SOUL.md`、`<cwd>/MEMORY.md` 是指向集中存储的链接
+- Claude：`@SOUL.md` 写入 CLAUDE.md 头部，CLI 每次 session 自动加载（引用式，改源文件立即生效）
+- Codex：每次新 session 合并 CLAUDE.md + SOUL.md 写入 `<cwd>/AGENTS.md`（快照式，需新 session 生效）
+- 老项目迁移：`/agent soul repair` 幂等补建 soul 层
+- 注意：Windows 上 copy 模式的 SOUL.md 不会自动同步源文件变更，需 `/agent soul repair` 刷新
+
+## 6. 运行时文件与状态
 
 - 配置：`~/.metame/daemon.yaml`
 - daemon 状态：`~/.metame/daemon_state.json`
 - 活跃子进程：`~/.metame/active_agent_pids.json`
+- 热重载备份：`~/.metame/.last-good/`（daemon 稳定运行 60s 后自动备份）
+- 崩溃计数：`~/.metame/.crash-count`（连续 2 次快速崩溃触发自动恢复）
+
+## 7. 热重载安全机制（三层防护）
+
+1. **部署前预检**（`index.js`）：`node -c` 语法检查所有 `.js`，不通过则拒绝部署到 `~/.metame/`
+2. **重启前预检**（`daemon-runtime-lifecycle.js`）：daemon.js 变更触发重启前再次语法校验，不通过则阻止重启并通知 admin
+3. **崩溃循环自愈**：连续 2 次在 30s 内崩溃 → 自动从 `.last-good/` 恢复 → 通知 admin
 
-## 6. 常见故障排查
+## 8. 常见故障排查
 
 ### Codex 认证失败
 
@@ -109,7 +126,26 @@ feishu:
 2. 若仍失败，手动 `/new` 新开会话
 3. 检查 `~/.metame/active_agent_pids.json` 是否残留异常进程
 
-## 7. 变更后维护动作
+## 9. 双平台/双引擎维护矩阵
+
+### 统一维护（改一处即可）
+- agent-layer.js / daemon-agent-tools.js / daemon-agent-commands.js / daemon-user-acl.js
+- ENGINE_MODEL_CONFIG（daemon-engine-runtime.js 集中管理）
+- daemon-runtime-lifecycle.js 的语法检查和备份机制
+
+### 需分别维护（有平台/引擎特殊分支）
+
+| 模块 | 差异点 | 注意事项 |
+|------|--------|----------|
+| platform.js `killProcessTree` | POSIX: `kill(-pid)` / Windows: `taskkill /T /F` | 所有进程杀死调用点应统一使用此函数 |
+| daemon-engine-runtime.js `resolveBinary` | macOS: `which` + homebrew / Windows: `where` + `.cmd` | 新增引擎需两端测试 |
+| daemon-engine-runtime.js `buildArgs` | Claude: `--resume`/`--continue` / Codex: `exec resume`，Codex resume 不能传权限 flag | 改参数结构时两端验证 |
+| daemon-claude-engine.js Soul 注入 | Claude: `@SOUL.md` import（引用式）/ Codex: AGENTS.md 合并写入（快照式） | 改 soul 加载方式需两端测试 |
+| agent-layer.js `createLinkOrMirror` | macOS: symlink / Windows: hardlink → copy 降级 | copy 模式不会自动同步源文件变更 |
+| daemon.js `spawnReplacementDaemon` | POSIX: `detached: true` / Windows: `detached: false` | 改 spawn 参数时注意平台分支 |
+| NL Mac 控制（command-router） | macOS only，`process.platform === 'darwin'` 守卫 | Windows 天然跳过 |
+
+## 10. 变更后维护动作
 
 1. `npm test`
 2. `npm run sync:plugin`

package/scripts/docs/pointer-map.md

@@ -15,6 +15,8 @@
 - 会话存储：`scripts/daemon-session-store.js`
 - 默认配置：`scripts/daemon-default.yaml`
 - Provider/蒸馏模型配置：`scripts/providers.js`（`/provider`、`/distill-model`）
+- 跨平台基础设施：`scripts/platform.js`（`killProcessTree`、`socketPath`、`sleepSync`、`icon`）
+- 热重载安全机制：`scripts/daemon-runtime-lifecycle.js`（语法预检、last-good 备份、crash-loop 自愈）
 - 维护手册：`scripts/docs/maintenance-manual.md`
 
 ## 多引擎（Claude/Codex）定位
@@ -28,10 +30,24 @@
   - 关键点：`askClaude()` 按 `project.engine`/session 选择 runtime；`patchSessionSerialized()` 串行回写 session
   - Codex 规则：`exec`/`resume`、10 分钟窗口内一次自动重试、`thread_id` 迁移回写
 
+- Agent Soul 身份层（新）：
+  - `scripts/agent-layer.js`
+  - 关键点：`ensureAgentLayer()` 创建 `~/.metame/agents/<id>/`（soul.md、memory-snapshot.md、agent.yaml）；
+    `createLinkOrMirror()` Windows 兼容（symlink → hardlink → copy 降级）；
+    `ensureClaudeMdSoulImport()` 在 CLAUDE.md 头部注入 `@SOUL.md`（Claude CLI 自动加载）；
+    Codex 引擎在每次新 session 时将 CLAUDE.md + SOUL.md 合并写入 AGENTS.md（见 daemon-claude-engine.js:957）；
+    `repairAgentLayer()` 懒迁移：老项目补建 soul 层，幂等安全
+
+- Agent 命令处理（新）：
+  - `scripts/daemon-agent-commands.js`
+  - 关键点：`createAgentCommandHandler()` 处理 `/agent`、`/activate`、`/resume`；
+    `/agent soul [repair|edit]`；`pendingActivations` 无 TTL（消费即删）；防止创建群自激活
+
 - 路由与 Agent 创建：
   - `scripts/daemon-command-router.js`
   - `scripts/daemon-agent-tools.js`
-  - 关键点：自然语言提取 `codex` 关键词；默认 `claude` 不写 `engine` 字段，仅 `codex` 持久化 `engine: codex`
+  - 关键点：自然语言提取 `codex` 关键词；默认 `claude` 不写 `engine` 字段，仅 `codex` 持久化 `engine: codex`；
+    `bindAgentToChat()` 自动调用 `ensureAgentMetadata()` 建立 soul 层
 
 - 会话命令与兼容边界：
   - `scripts/daemon-exec-commands.js`
@@ -74,6 +90,12 @@
 - 夜间反思文档：`~/.metame/memory/decisions/`、`~/.metame/memory/lessons/`
 - 知识胶囊：`~/.metame/memory/capsules/`
 - 复盘文档：`~/.metame/memory/postmortems/`
+- **Agent Soul 层**：`~/.metame/agents/<agent_id>/`
+  - `agent.yaml` — id / name / engine / aliases
+  - `soul.md` — 身份定义（主文件，项目目录的 SOUL.md 是其链接）
+  - `memory-snapshot.md` — 近期记忆快照（注入 session prompt）
+  - 项目视图：`<cwd>/SOUL.md`（symlink/hardlink/copy）、`<cwd>/MEMORY.md`（同）
+  - `<cwd>/AGENTS.md` — Codex 专用，每次新 session 由 daemon 合并 CLAUDE.md + SOUL.md 写入
 
 ## 诊断顺序（推荐）
 

package/scripts/feishu-adapter.js

@@ -10,15 +10,40 @@ const fs = require('fs');
 const path = require('path');
 
 let Lark;
-try {
-  Lark = require('@larksuiteoapi/node-sdk');
-} catch {
+function _tryRequireLark() {
+  // 1. local node_modules (dev environment)
+  try { return require('@larksuiteoapi/node-sdk'); } catch {}
+  // 2. METAME_ROOT/node_modules (packaged metame-cli)
   const metameRoot = process.env.METAME_ROOT;
   if (metameRoot) {
-    Lark = require(require('path').join(metameRoot, 'node_modules', '@larksuiteoapi/node-sdk'));
+    try { return require(path.join(metameRoot, 'node_modules', '@larksuiteoapi/node-sdk')); } catch {}
   }
-  if (!Lark) {
-    console.error('Cannot find @larksuiteoapi/node-sdk. Run: npm install @larksuiteoapi/node-sdk');
+  // 3. ~/.metame/node_modules (auto-installed for new users)
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (home) {
+    try { return require(path.join(home, '.metame', 'node_modules', '@larksuiteoapi', 'node-sdk')); } catch {}
+  }
+  return null;
+}
+Lark = _tryRequireLark();
+if (!Lark) {
+  // Auto-install into ~/.metame so new users never see this error
+  const home = process.env.HOME || process.env.USERPROFILE;
+  const prefix = home ? path.join(home, '.metame') : null;
+  if (prefix) {
+    console.log('[feishu] @larksuiteoapi/node-sdk not found, auto-installing into ~/.metame ...');
+    const { execSync } = require('child_process');
+    try {
+      execSync(`npm install @larksuiteoapi/node-sdk --prefix "${prefix}" --silent`, { stdio: 'inherit' });
+      Lark = require(path.join(prefix, 'node_modules', '@larksuiteoapi', 'node-sdk'));
+      console.log('[feishu] SDK installed successfully.');
+    } catch (e) {
+      console.error('[feishu] Auto-install failed:', e.message);
+      console.error('Manual fix: npm install @larksuiteoapi/node-sdk --prefix ~/.metame');
+      process.exit(1);
+    }
+  } else {
+    console.error('[feishu] Cannot find @larksuiteoapi/node-sdk and HOME is not set.');
     process.exit(1);
   }
 }
@@ -26,12 +51,11 @@ try {
 // Timeout wrapper: prevents SDK calls from hanging indefinitely when
 // Feishu's token refresh HTTP request has no response (e.g. network down)
 function withTimeout(promise, ms = 10000) {
-  return Promise.race([
-    promise,
-    new Promise((_, reject) =>
-      setTimeout(() => reject(new Error(`Feishu API timeout after ${ms}ms`)), ms)
-    ),
-  ]);
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`Feishu API timeout after ${ms}ms`)), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 
 // Max chars per lark_md element (Feishu limit ~4000)

package/scripts/memory-extract.js

@@ -7,7 +7,7 @@
  * into memory.db. Runs independently of raw_signals.jsonl so that
  * pure technical sessions (no preference signals) are still captured.
  *
- * Designed to run as a standalone heartbeat task every 30 minutes.
+ * Designed to run as a standalone heartbeat task (default interval: 4h).
  */
 
 'use strict';
@@ -356,6 +356,10 @@ async function run() {
 if (require.main === module) {
   run().then(({ sessionsProcessed, factsSaved, factsSkipped }) => {
     console.log(`✅ memory-extract: ${sessionsProcessed} session(s), ${factsSaved} facts saved, ${factsSkipped} skipped`);
+    // Report estimated token usage for daemon budget tracking
+    // Each session processed ≈ 1 callHaiku invocation ≈ 3k tokens
+    const estTokens = sessionsProcessed * 3000;
+    if (estTokens > 0) console.log(`__TOKENS__:${estTokens}`);
   }).catch(e => {
     console.error(`[memory-extract] Fatal: ${e.message}`);
     process.exit(1);

package/scripts/memory-nightly-reflect.js

@@ -465,6 +465,9 @@ facts(json): ${JSON.stringify(groupFacts, null, 2).slice(0, 5000)}
 if (require.main === module) {
   run().then(() => {
     console.log('✅ nightly-reflect complete');
+    // Report estimated token usage for daemon budget tracking
+    // ~5k tokens per reflection + capsule generation
+    console.log('__TOKENS__:5000');
   }).catch(e => {
     console.error(`[NIGHTLY-REFLECT] Fatal: ${e.message}`);
     process.exit(1);

package/scripts/mentor-engine.js

@@ -365,14 +365,14 @@ function buildMentorPrompt(sessionState = {}, profile = {}, config = {}, nowMs =
   lines.push(`- mode=${mode}, zone=${zone}`);
 
   if (mode === 'gentle') {
-    lines.push('- Before solution, optionally ask one short guiding question.');
+    lines.push('- Give solution but include brief rationale so user can learn the "why".');
   } else if (mode === 'active') {
-    lines.push('- Ask user for their design idea first, then provide improvements.');
-    lines.push('- End with one-line "关键收获".');
+    lines.push('- Lead with the key concept/principle before the implementation.');
+    lines.push('- Add one-line "关键收获" at the end of your reply.');
   } else {
     lines.push('- Prefer scaffold/pseudocode first; avoid dumping full solution immediately.');
-    lines.push('- Use Socratic prompts to force active reasoning.');
     lines.push('- Apply knowledge firewall: do not fill user logic gaps with unstated assumptions.');
+    lines.push('- Guide via explanation structure, not by asking the user questions.');
   }
 
   if (zone === 'comfort') lines.push('- Increase challenge slightly (new method or stronger abstraction).');