coze_lab 0.1.37 → 0.1.40

package/README.md

@@ -8,7 +8,7 @@ Configure local AI agents (Claude Code, Codex, OpenClaw) to report traces to Coz
 # First-time setup — triggers browser OAuth authorization
 npx coze_lab --agent=<type>
 
-# Per-agent setup. Cloud/local is inferred from coze-bridge config.
+# Per-agent setup. Cloud/local is inferred from coze-bridge config or CLOUD_ENV=1.
 npx coze_lab --agent-id=<agentId>
 
 # Auth-only commands (no agent configuration)
@@ -23,8 +23,8 @@ npx coze_lab --logout     # Clear cached credentials
 | Parameter | Required | Values / Effect |
 |-----------|----------|-----------------|
 | `--agent` | ✓ (for setup) | `claude-code`, `codex`, `openclaw` |
-| `--agent-id` | — | Resolve `~/.coze/agents/<agentId>/config.json` and write per-agent config. `deployType=cloud` enables cloud mode automatically |
-| `--cloud` | — | Backward-compatible override for old callers. New callers should rely on `--agent-id` + config `deployType` |
+| `--agent-id` | — | Resolve `~/.coze/agents/<agentId>/config.json` and write per-agent config. Cloud mode is inferred from `deployType=cloud`, `CLOUD_ENV=1`, or bridge cloud-only fields |
+| `--cloud` | — | Backward-compatible override for old manual callers. New callers should rely on `--agent-id` auto-detection |
 | `--codex-home` | — | Override Codex config home for non-cloud/custom runs |
 | `--login` | — | Run the Device Code login flow only |
 | `--status` | — | Print local token status (valid / expiring / expired) |
@@ -56,7 +56,7 @@ npx coze_lab --logout     # Clear cached credentials
 | `codex` | `~/.codex/hooks/cozeloop_hook.py` | `~/.codex/hooks.json` | `~/.codex/hooks/cozeloop.env` |
 | `openclaw` | — (Node.js plugin) | `~/.openclaw/openclaw.json` | inline in config |
 
-For cloud Codex with `--agent-id=<agentId>` and config `deployType=cloud`, Codex hooks are written to
+For cloud Codex with `--agent-id=<agentId>`, Codex hooks are written to
 `~/.coze/agents/<agentId>/codex-home` by default. The directory is created if it
 does not already exist, so callers do not need to pass `--codex-home` for the
 standard coze-bridge layout.

package/index.js

@@ -53,6 +53,11 @@ function getCloudTokenInfo() {
   return { token: '', source: '', traceUsable: false };
 }
 
+function isCloudRuntimeEnv() {
+  const v = readEnv('CLOUD_ENV').toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes' || v === 'cloud';
+}
+
 // ─── 1. Color helpers ────────────────────────────────────────────────────────
 const C = {
   reset:  '\x1b[0m',
@@ -156,6 +161,30 @@ function parseArgs() {
 
 const VALID_AGENTS = ['claude-code', 'codex', 'openclaw'];
 
+function hasCloudSessionToken(cfg) {
+  const sessions = cfg?.sessions;
+  if (!sessions || typeof sessions !== 'object' || Array.isArray(sessions)) return false;
+  return Object.values(sessions).some((record) => (
+    record
+    && typeof record === 'object'
+    && typeof record.modelToken === 'string'
+    && record.modelToken.trim()
+  ));
+}
+
+function hasCloudModelInfo(cfg) {
+  return !!(cfg?.modelInfo && typeof cfg.modelInfo === 'object' && !Array.isArray(cfg.modelInfo));
+}
+
+function inferDeployTypeFromAgentConfig(cfg) {
+  if (cfg?.deployType === 'cloud') return { deployType: 'cloud', reason: 'config.deployType=cloud' };
+  if (isCloudRuntimeEnv()) return { deployType: 'cloud', reason: 'env CLOUD_ENV=1' };
+  if (cfg?.deployType === 'local') return { deployType: 'local', reason: 'config.deployType=local' };
+  if (hasCloudSessionToken(cfg)) return { deployType: 'cloud', reason: 'config.sessions[*].modelToken' };
+  if (hasCloudModelInfo(cfg)) return { deployType: 'cloud', reason: 'config.modelInfo' };
+  return { deployType: 'local', reason: 'no cloud signal' };
+}
+
 // resolveAgent 读 ~/.coze/agents/<agentId>/config.json，返回 { framework, workspace, deployType, agentId, root }。
 // soft=true 时，config 不存在 / 解析失败 / framework 非法均返回 null（不退出），供云端回退到显式 --agent。
 function resolveAgent(agentId, soft) {
@@ -186,8 +215,8 @@ function resolveAgent(agentId, soft) {
       `支持的类型: ${VALID_AGENTS.join(', ')}`,
     ]);
   }
-  const deployType = cfg.deployType === 'cloud' ? 'cloud' : 'local';
-  return { framework, workspace: cfg.workspace || '', deployType, agentId, root };
+  const inferred = inferDeployTypeFromAgentConfig(cfg);
+  return { framework, workspace: cfg.workspace || '', deployType: inferred.deployType, deployReason: inferred.reason, agentId, root };
 }
 
 function validateArgs(args) {
@@ -197,11 +226,12 @@ function validateArgs(args) {
   if (args['refresh']) return { refresh: true };
   if (args['verify'])  return { verify:  true, pairCode: args['pair-code'] };
 
-  // --agent-id：优先读 coze-bridge 的 ~/.coze/agents/<id>/config.json 拿 framework/workspace/deployType。
-  // deployType=cloud 时自动进入云端注入路径；显式 --cloud 仍保留，供 config 缺失时兜底。
+  // --agent-id：优先读 coze-bridge 的 ~/.coze/agents/<id>/config.json 拿 framework/workspace。
+  // 云端判定优先看 deployType / CLOUD_ENV；兼容老 config 时再看 cloud-only 落盘字段。
   if (args['agent-id']) {
     const explicitCloud = !!args['cloud'];
-    const resolved = resolveAgent(args['agent-id'], explicitCloud /* soft */);
+    const runtimeCloud = isCloudRuntimeEnv();
+    const resolved = resolveAgent(args['agent-id'], explicitCloud || runtimeCloud /* soft */);
     if (resolved) {
       const cloud = explicitCloud || resolved.deployType === 'cloud';
       return {
@@ -210,20 +240,22 @@ function validateArgs(args) {
         workspace: resolved.workspace,
         agentRoot: resolved.root,
         deployType: resolved.deployType,
+        deployReason: explicitCloud ? '--cloud' : resolved.deployReason,
         'codex-home': args['codex-home'],
         pairCode: args['pair-code'],
         cloud,
         force: !!args['force'],
       };
     }
-    // 显式 --cloud 且 config.json 缺失：回退到显式 --agent（workspace 在 main 推断）。
-    if (!args['agent'] || !VALID_AGENTS.includes(args['agent'])) {
+    // 显式 --cloud 或 CLOUD_ENV=1 且 config.json 缺失：回退到显式 --agent
+    // （workspace 在 main 推断）。没有云端信号时仍按本地 config 缺失报错。
+    if ((!explicitCloud && !runtimeCloud) || !args['agent'] || !VALID_AGENTS.includes(args['agent'])) {
       errorBox([
         `ERROR: 未找到 agent "${args['agent-id']}" 的 config.json，且未显式指定 --agent`,
         '',
         '新调用方应确认 coze-bridge 已在目标环境写入该 agent config。',
-        '如需兼容旧手工命令，可显式拼上 framework 和 --cloud：',
-        `  npx coze_lab --cloud --agent-id=${args['agent-id']} --agent=claude-code|codex|openclaw`,
+        '如需兼容旧手工命令，可显式拼上 framework：',
+        `  npx coze_lab --agent-id=${args['agent-id']} --agent=claude-code|codex|openclaw`,
       ]);
     }
     return {
@@ -231,6 +263,7 @@ function validateArgs(args) {
       agentId: args['agent-id'],
       workspace: args['workspace'] || '',
       deployType: 'cloud',
+      deployReason: explicitCloud ? '--cloud' : 'env CLOUD_ENV=1',
       'codex-home': args['codex-home'],
       pairCode: args['pair-code'],
       cloud: true,
@@ -462,14 +495,27 @@ function writeHookScript(dest, content) {
   }
 }
 
+// atomicWriteFileSync 原子写文件：先写到同目录下的临时文件（带 pid），fsync 后 rename
+// 覆盖目标。rename 在同一文件系统上是原子操作，避免读-改-写过程中崩溃留下半截/空文件。
+function atomicWriteFileSync(filepath, data, options) {
+  const dir = path.dirname(filepath);
+  const tmp = path.join(dir, `.tmp.${process.pid}.${Date.now()}.${path.basename(filepath)}`);
+  try {
+    fs.writeFileSync(tmp, data, options);
+    fs.renameSync(tmp, filepath);
+  } catch (e) {
+    // 失败时清掉残留临时文件，保持目标文件原样（要么旧内容，要么不存在）。
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw e;
+  }
+}
+
 function mergeJson(filepath, mergeFn) {
   let existing = {};
   if (fs.existsSync(filepath)) {
-    try {
-      existing = JSON.parse(fs.readFileSync(filepath, 'utf8'));
-    } catch {
-      warnBox([`Warning: Could not parse existing ${filepath}`, '', 'Starting with a fresh configuration.']);
-    }
+    // 解析失败时绝不退回空对象继续合并——那会丢掉文件里已有的 hook/凭证配置。
+    // 直接抛错，让调用方保留原文件内容、让用户感知到坏文件，而不是静默覆盖。
+    existing = JSON.parse(fs.readFileSync(filepath, 'utf8'));
   }
   return mergeFn(existing);
 }
@@ -499,32 +545,46 @@ function writeClaudeCodeHook(patToken, workspaceId, pythonCmd, configBaseDir, cl
   const refreshScript = path.join(hooksDir, 'cozeloop_refresh.py');
   writeHookScript(refreshScript, readScript('shared/cozeloop_refresh.py'));
 
-  // 2. Merge settings.json — Stop (trace) + UserPromptSubmit (refresh)。用绝对路径。
+  // 2. Merge settings.json — Stop (trace 收尾) + PostToolUse (trace 增量) + UserPromptSubmit (refresh)。用绝对路径。
   const hookCmd    = `${pythonCmd} ${hookScript}`;
   const refreshCmd = `${pythonCmd} ${refreshScript}`;
 
   ensureDir(claudeDir);
-  const settings = mergeJson(settingsPath, (existing) => {
-    if (!existing.hooks) existing.hooks = {};
-
-    // Stop hook — trace upload
-    if (!existing.hooks.Stop) existing.hooks.Stop = [];
-    existing.hooks.Stop = existing.hooks.Stop.filter(
-      entry => !entry.hooks?.some(h => h.command?.includes('cozeloop_hook.py'))
-    );
-    existing.hooks.Stop.push({ matcher: '', hooks: [{ type: 'command', command: hookCmd }] });
-
-    // UserPromptSubmit hook — token refresh before each user message
-    if (!existing.hooks.UserPromptSubmit) existing.hooks.UserPromptSubmit = [];
-    existing.hooks.UserPromptSubmit = existing.hooks.UserPromptSubmit.filter(
-      entry => !entry.hooks?.some(h => h.command?.includes('cozeloop_refresh.py'))
-    );
-    existing.hooks.UserPromptSubmit.push({ matcher: '', hooks: [{ type: 'command', command: refreshCmd }] });
-
-    return existing;
-  });
+  let settings;
+  try {
+    settings = mergeJson(settingsPath, (existing) => {
+      if (!existing.hooks) existing.hooks = {};
+
+      // Stop hook — trace upload（收尾，全量上报最后一批）
+      if (!existing.hooks.Stop) existing.hooks.Stop = [];
+      existing.hooks.Stop = existing.hooks.Stop.filter(
+        entry => !entry.hooks?.some(h => h.command?.includes('cozeloop_hook.py'))
+      );
+      existing.hooks.Stop.push({ matcher: '', hooks: [{ type: 'command', command: hookCmd }] });
+
+      // PostToolUse hook — trace 增量上报（任务进行中即上报已完成 turn，脚本内置节流+turn边界控制）。
+      // 没有它，长任务（单 turn 跑十几分钟）期间 Stop 不触发，trace 全程查不到。
+      if (!existing.hooks.PostToolUse) existing.hooks.PostToolUse = [];
+      existing.hooks.PostToolUse = existing.hooks.PostToolUse.filter(
+        entry => !entry.hooks?.some(h => h.command?.includes('cozeloop_hook.py'))
+      );
+      existing.hooks.PostToolUse.push({ matcher: '', hooks: [{ type: 'command', command: hookCmd }] });
+
+      // UserPromptSubmit hook — token refresh before each user message
+      if (!existing.hooks.UserPromptSubmit) existing.hooks.UserPromptSubmit = [];
+      existing.hooks.UserPromptSubmit = existing.hooks.UserPromptSubmit.filter(
+        entry => !entry.hooks?.some(h => h.command?.includes('cozeloop_refresh.py'))
+      );
+      existing.hooks.UserPromptSubmit.push({ matcher: '', hooks: [{ type: 'command', command: refreshCmd }] });
+
+      return existing;
+    });
+  } catch (e) {
+    // 现存 settings.json 解析失败：保留原文件，提示用户手动修复，绝不用空配置覆盖。
+    errorBox([`ERROR: Existing ${settingsPath} is not valid JSON`, '', e.message, '', '请修复或删除该文件后重试，避免覆盖丢失现有 hook 配置。']);
+  }
   try {
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2));
   } catch (e) {
     errorBox([`ERROR: Cannot write ${settingsPath}`, '', e.message]);
   }
@@ -533,42 +593,47 @@ function writeClaudeCodeHook(patToken, workspaceId, pythonCmd, configBaseDir, cl
   // 3. Write credentials into <baseDir>/.claude/settings.local.json
   ensureDir(path.join(baseDir, '.claude'));
   ensureDir(path.dirname(logFile));
-  const localSettings = mergeJson(localSettingsPath, (existing) => {
-    if (!existing.env) existing.env = {};
-    existing.env.COZELOOP_WORKSPACE_ID = workspaceId;
-    existing.env.COZELOOP_HOOK_LOG = logFile;
-    if (cloud) {
-      const loopToken = readEnv('COZELOOP_API_TOKEN');
-      const cozeToken = readEnv('COZE_API_TOKEN');
-      existing.env.COZELAB_ONBOARD_CLOUD = '1';
-      if (loopToken) {
-        existing.env.COZELOOP_API_TOKEN = loopToken;
-        delete existing.env.COZE_API_TOKEN;
-      } else if (cozeToken) {
-        existing.env.COZE_API_TOKEN = cozeToken;
+  let localSettings;
+  try {
+    localSettings = mergeJson(localSettingsPath, (existing) => {
+      if (!existing.env) existing.env = {};
+      existing.env.COZELOOP_WORKSPACE_ID = workspaceId;
+      existing.env.COZELOOP_HOOK_LOG = logFile;
+      if (cloud) {
+        const loopToken = readEnv('COZELOOP_API_TOKEN');
+        const cozeToken = readEnv('COZE_API_TOKEN');
+        existing.env.COZELAB_ONBOARD_CLOUD = '1';
+        if (loopToken) {
+          existing.env.COZELOOP_API_TOKEN = loopToken;
+          delete existing.env.COZE_API_TOKEN;
+        } else if (cozeToken) {
+          existing.env.COZE_API_TOKEN = cozeToken;
+          delete existing.env.COZELOOP_API_TOKEN;
+        }
+      } else {
         delete existing.env.COZELOOP_API_TOKEN;
+        delete existing.env.COZE_API_TOKEN;
+        delete existing.env.COZELAB_ONBOARD_CLOUD;
       }
-    } else {
-      delete existing.env.COZELOOP_API_TOKEN;
-      delete existing.env.COZE_API_TOKEN;
-      delete existing.env.COZELAB_ONBOARD_CLOUD;
-    }
-    const loopBaseUrl = readEnv('COZELOOP_API_BASE_URL');
-    const otelEndpoint = readEnv('OTEL_ENDPOINT');
-    if (loopBaseUrl) {
-      existing.env.COZELOOP_API_BASE_URL = loopBaseUrl;
-      delete existing.env.OTEL_ENDPOINT;
-    } else if (otelEndpoint) {
-      existing.env.OTEL_ENDPOINT = otelEndpoint;
-      delete existing.env.COZELOOP_API_BASE_URL;
-    }
-    // 切正式环境：移除历史注入的 PPE 泳道 env（旧版本曾写入 x_tt_env/x_use_ppe）
-    delete existing.env.x_tt_env;
-    delete existing.env.x_use_ppe;
-    return existing;
-  });
+      const loopBaseUrl = readEnv('COZELOOP_API_BASE_URL');
+      const otelEndpoint = readEnv('OTEL_ENDPOINT');
+      if (loopBaseUrl) {
+        existing.env.COZELOOP_API_BASE_URL = loopBaseUrl;
+        delete existing.env.OTEL_ENDPOINT;
+      } else if (otelEndpoint) {
+        existing.env.OTEL_ENDPOINT = otelEndpoint;
+        delete existing.env.COZELOOP_API_BASE_URL;
+      }
+      // 切正式环境：移除历史注入的 PPE 泳道 env（旧版本曾写入 x_tt_env/x_use_ppe）
+      delete existing.env.x_tt_env;
+      delete existing.env.x_use_ppe;
+      return existing;
+    });
+  } catch (e) {
+    errorBox([`ERROR: Existing ${localSettingsPath} is not valid JSON`, '', e.message, '', '请修复或删除该文件后重试，避免覆盖丢失现有凭证配置。']);
+  }
   try {
-    fs.writeFileSync(localSettingsPath, JSON.stringify(localSettings, null, 2));
+    atomicWriteFileSync(localSettingsPath, JSON.stringify(localSettings, null, 2));
   } catch (e) {
     errorBox([`ERROR: Cannot write credentials to ${localSettingsPath}`, '', e.message]);
   }
@@ -629,7 +694,7 @@ function writeCodexHook(token, workspaceId, pythonCmd, codexHome, cloud) {
   }
   ok(`Credentials written to ${envFile} (chmod 600)`);
 
-  // 3. Merge hooks.json — Stop (trace) + SessionStart (refresh)
+  // 3. Merge hooks.json — Stop (trace 收尾) + PostToolUse (trace 增量) + SessionStart (refresh)
   //    命令用绝对路径（CODEX_HOME 不一定是 ~/.codex）。
   const hookCmd    = `set -a && . ${envFile} && set +a && ${pythonCmd} ${hookScript}`;
   const refreshCmd = `${pythonCmd} ${refreshScript}`;
@@ -637,13 +702,21 @@ function writeCodexHook(token, workspaceId, pythonCmd, codexHome, cloud) {
   const hooks = mergeJson(hooksJson, (existing) => {
     if (!existing.hooks) existing.hooks = {};
 
-    // Stop hook — trace upload
+    // Stop hook — trace upload（turn 结束，收尾全量上报）
     if (!existing.hooks.Stop) existing.hooks.Stop = [];
     existing.hooks.Stop = existing.hooks.Stop.filter(
       entry => !entry.hooks?.some(h => h.command?.includes('cozeloop_hook.py'))
     );
     existing.hooks.Stop.push({ matcher: null, hooks: [{ type: 'command', command: hookCmd, timeout: 60 }] });
 
+    // PostToolUse hook — trace 增量上报（turn 进行中即上报已完成 turn，脚本内置节流+turn边界控制）。
+    // 没有它，单个长 turn 内（多轮工具调用持续数分钟）期间 Stop 不触发，trace 全程查不到。
+    if (!existing.hooks.PostToolUse) existing.hooks.PostToolUse = [];
+    existing.hooks.PostToolUse = existing.hooks.PostToolUse.filter(
+      entry => !entry.hooks?.some(h => h.command?.includes('cozeloop_hook.py'))
+    );
+    existing.hooks.PostToolUse.push({ matcher: null, hooks: [{ type: 'command', command: hookCmd, timeout: 60 }] });
+
     // SessionStart hook — token refresh
     if (!existing.hooks.SessionStart) existing.hooks.SessionStart = [];
     existing.hooks.SessionStart = existing.hooks.SessionStart.filter(
@@ -680,16 +753,31 @@ function resolveCodexHome(args) {
 function resolveHomeDir(cloud) {
   const h = os.homedir();
   if (!cloud) return h;
-  // 优先 $HOME，其次 os.homedir()，再回退云端常见 root home。
-  const candidates = [process.env.HOME, h, '/root'].filter(Boolean);
+  // 优先级：$HOME > os.homedir()（非空才用）> 显式候选目录。
+  // 不再无脑回退 /root —— 云端真实 home 可能是 /home/appuser，回退 /root 会把
+  // openclaw.json/凭证写错位置。仅在 HOME 与 os.homedir() 都拿不到时才探测候选。
+  const envHome = (process.env.HOME || '').trim();
+  if (envHome) {
+    info(`resolveHomeDir: using $HOME=${envHome}`);
+    return envHome;
+  }
+  if (h) {
+    info(`resolveHomeDir: using os.homedir()=${h}`);
+    return h;
+  }
+  // HOME 与 os.homedir() 都为空：探测云端常见 home 候选，挑第一个已有 coze/openclaw 配置的。
+  const candidates = ['/home/appuser', '/root'];
   for (const c of candidates) {
     try {
       if (fs.existsSync(path.join(c, '.coze')) || fs.existsSync(path.join(c, '.openclaw'))) {
+        info(`resolveHomeDir: HOME/os.homedir() empty, detected home=${c}`);
         return c;
       }
     } catch { /* ignore */ }
   }
-  return h || '/root';
+  const fallback = candidates[candidates.length - 1];
+  warn(`resolveHomeDir: cannot determine home (HOME/os.homedir() empty, no candidate has coze config), falling back to ${fallback}`);
+  return fallback;
 }
 
 function normalizeTraceAgentIds(ids) {
@@ -1446,8 +1534,9 @@ function loadCredentials() {
 }
 
 function saveCredentials(creds) {
-  fs.mkdirSync(path.dirname(CREDS_PATH), { recursive: true });
-  fs.writeFileSync(CREDS_PATH, JSON.stringify(creds, null, 2), { mode: 0o600 });
+  // 0o700：凭证目录仅 owner 可读/进入，其他用户无法枚举 ~/.cozeloop 内容。
+  fs.mkdirSync(path.dirname(CREDS_PATH), { recursive: true, mode: 0o700 });
+  atomicWriteFileSync(CREDS_PATH, JSON.stringify(creds, null, 2), { mode: 0o600 });
 }
 
 function deleteCredentials() {
@@ -1486,7 +1575,7 @@ async function refreshToken(creds) {
   const updated = {
     access_token:  data.access_token,
     refresh_token: data.refresh_token ?? creds.refresh_token,
-    expires_at:    (data.expires_in ?? 0) * 1000,  // expires_in is a unix timestamp in seconds
+    expires_at:    (data.expires_in ?? 0) * 1000,  // expires_at stored in milliseconds (Python 端按毫秒读)
     workspace_id:  creds.workspace_id ?? WORKSPACE_ID,  // preserve workspace_id
   };
   saveCredentials(updated);
@@ -1569,7 +1658,7 @@ async function deviceCodeAuth() {
       const creds = {
         access_token:  pollData.access_token,
         refresh_token: pollData.refresh_token,
-        expires_at:    (pollData.expires_in ?? 0) * 1000,  // unix timestamp in seconds
+        expires_at:    (pollData.expires_in ?? 0) * 1000,  // expires_at stored in milliseconds (Python 端按毫秒读)
         workspace_id:  WORKSPACE_ID,
       };
       saveCredentials(creds);
@@ -1784,14 +1873,13 @@ async function main() {
   // 云端模式：开启结构化输出 + errorBox 抛异常（而非 exit）。
   CLOUD_MODE = !!args.cloud;
   // per-agent 路由时 agent 的 workspace（claude-code 用它做配置根目录）。
-  // per-agent 路由时 agent 的 workspace（claude-code 用它做配置根目录）。
   // 云端 claude-code 未显式传 workspace 时，按约定路径 ~/.coze/agents/<id>/workspace 推断。
   let agentWorkspace = args.workspace || '';
   if (args.cloud && args.agentId && agent === 'claude-code' && !agentWorkspace) {
     agentWorkspace = path.join(os.homedir(), '.coze', 'agents', args.agentId, 'workspace');
   }
   if (args.agentId) {
-    info(`目标 agent: ${args.agentId} (framework=${agent}, workspace=${agentWorkspace || 'N/A'})`);
+    info(`目标 agent: ${args.agentId} (framework=${agent}, workspace=${agentWorkspace || 'N/A'}, deploy=${args.cloud ? 'cloud' : 'local'}, reason=${args.deployReason || 'n/a'})`);
     console.log('');
   }
 
@@ -1945,20 +2033,30 @@ async function main() {
   successBox(summaryLines);
 }
 
-main().catch(e => {
-  // 云端模式：失败时输出结构化结果（含 logid），exit 非 0 但带 COZE_LAB_RESULT 行。
-  if (CLOUD_MODE) {
-    if (cloudResult.inject !== 'ok') {
-      // 写 hook 配置前的任何失败 → 注入失败。
-      cloudResult.inject = 'fail';
-    } else if (cloudResult.verify === 'skip') {
-      // 注入已成功，但验证阶段异常崩溃（未走到正常的 ok/fail 判定）→ 记为验证失败。
-      cloudResult.verify = 'fail';
+// 仅在作为 CLI 直接运行时执行 main()；被 require（单元测试）时只导出内部函数。
+if (require.main === module) {
+  main().catch(e => {
+    // 云端模式：失败时输出结构化结果（含 logid），exit 非 0 但带 COZE_LAB_RESULT 行。
+    if (CLOUD_MODE) {
+      if (cloudResult.inject !== 'ok') {
+        // 写 hook 配置前的任何失败 → 注入失败。
+        cloudResult.inject = 'fail';
+      } else if (cloudResult.verify === 'skip') {
+        // 注入已成功，但验证阶段异常崩溃（未走到正常的 ok/fail 判定）→ 记为验证失败。
+        cloudResult.verify = 'fail';
+      }
+      if (!cloudResult.message) cloudResult.message = e && e.message ? e.message : 'unexpected failure';
+      if (!cloudResult.logid) cloudResult.logid = extractLogid(cloudResult.message);
+      emitCloudResult();
+      process.exit(1);
     }
-    if (!cloudResult.message) cloudResult.message = e && e.message ? e.message : 'unexpected failure';
-    if (!cloudResult.logid) cloudResult.logid = extractLogid(cloudResult.message);
-    emitCloudResult();
-    process.exit(1);
-  }
-  errorBox(['ERROR: Unexpected failure', '', e.message]);
-});
+    errorBox(['ERROR: Unexpected failure', '', e.message]);
+  });
+}
+
+module.exports = {
+  resolveHomeDir,
+  mergeJson,
+  atomicWriteFileSync,
+  isExpired,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coze_lab",
-  "version": "0.1.37",
+  "version": "0.1.40",
   "description": "Configure local AI agents (Claude Code, Codex, OpenClaw) to report traces to CozeLoop",
   "keywords": [
     "cozeloop",

package/scripts/claude-code/cozeloop_hook.py

@@ -127,6 +127,10 @@ _DEFAULT_WORKSPACE_ID = "7649231955045072915"  # hardcoded spaceID fallback
 _COZE_CTX_OPEN = "<coze-context>"
 _COZE_CTX_CLOSE = "</coze-context>"
 
+# 中途事件(PostToolUse)增量上报的最小间隔（秒）。密集工具调用下用它节流，避免每秒多次 flush。
+# 终态事件(Stop)不受此限制。
+INCREMENTAL_UPLOAD_MIN_INTERVAL = float(os.environ.get("COZELOOP_INCREMENTAL_MIN_INTERVAL", "10"))
+
 
 def _content_to_text(content: Any) -> str:
     """Flatten Claude message content (str | list[dict] | dict) to plain text."""
@@ -438,8 +442,8 @@ def _token_from_credentials() -> Optional[str]:
     creds = _load_credentials()
     if not creds:
         return None
-    expires_at_sec = creds.get("expires_at", 0) / 1000
-    remaining = expires_at_sec - time.time()
+    # expires_at 由 index.js 以毫秒存储；先减去当前毫秒时间再换算成秒，与 _REFRESH_THRESHOLD(秒) 比较。
+    remaining = (creds.get("expires_at", 0) - time.time() * 1000) / 1000
     if remaining > _REFRESH_THRESHOLD:
         debug_log(f"Cached token valid, expires in {int(remaining)}s.")
         return creds.get("access_token")
@@ -1091,7 +1095,13 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history
     else:
         print("[CozeLoop] 警告: 未找到有效 Token，上报可能失败", file=sys.stderr)
     creds = _load_credentials()
-    workspace_id = (creds or {}).get("workspace_id") or os.environ.get("COZELOOP_WORKSPACE_ID", "") or _DEFAULT_WORKSPACE_ID
+    # 云端模式：sandbox 注入的 COZELOOP_WORKSPACE_ID 必须优先于 credentials.json。
+    # 否则残留的本地 credentials.json workspace_id 会覆盖云端注入，导致 trace 上报错位。
+    is_cloud = os.environ.get("COZELAB_ONBOARD_CLOUD", "").lower() in ("1", "true", "yes")
+    if is_cloud:
+        workspace_id = os.environ.get("COZELOOP_WORKSPACE_ID", "") or (creds or {}).get("workspace_id") or _DEFAULT_WORKSPACE_ID
+    else:
+        workspace_id = (creds or {}).get("workspace_id") or os.environ.get("COZELOOP_WORKSPACE_ID", "") or _DEFAULT_WORKSPACE_ID
     os.environ["COZELOOP_WORKSPACE_ID"] = workspace_id
     upload_events: List[str] = []
     client_kwargs = {
@@ -1150,6 +1160,16 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history
                 t = coze_context_tags(um.get("content") if um else None)
                 if t:
                     coze_tags = t
+            # Drop empty-valued coze_* tags: the backend pairs traces by exact tag
+            # match (coze_message_id / coze_agent_id), where an empty string is
+            # indistinguishable from "absent" yet still bloats the span — never
+            # emit one. Log when a pairing key is missing so a silent pairing miss
+            # is debuggable.
+            coze_tags = {k: v for k, v in coze_tags.items() if isinstance(v, str) and v.strip()}
+            if not coze_tags.get("coze_message_id"):
+                hook_log(f"coze-context missing coze_message_id session={session_id}")
+            if not coze_tags.get("coze_session_id"):
+                hook_log(f"coze-context missing coze_session_id session={session_id}")
             if coze_tags:
                 root_tags.update(coze_tags)
                 root_baggage.update(coze_tags)
@@ -1561,7 +1581,19 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, history
         debug_log(f"An error occurred while sending traces to CozeLoop: {e}")
         return None
     finally:
-        # Crucial: close the client to ensure all buffered traces are sent.
+        # Flush buffered spans BEFORE closing so a slow/failed close() can't drop
+        # them. close() also flushes, but flushing first surfaces the upload
+        # failure (via trace_finish_event_processor -> upload_events) while the
+        # client is still usable.
+        # KNOWN RISK: when flush/close reports a 401, the block below re-sends the
+        # ENTIRE turn batch with a refreshed token. The SDK has no per-span ack, so
+        # any batch the first attempt already delivered before the auth failure is
+        # uploaded a second time -> duplicate trace. Acceptable for now (a missing
+        # trace is worse than a dup); revisit if the SDK gains partial-ack/resume.
+        try:
+            client.flush()
+        except Exception as _flush_err:
+            debug_log(f"client.flush() before close failed: {_flush_err}")
         client.close()
         debug_log("CozeLoop client closed.")
 
@@ -1614,6 +1646,11 @@ def main():
     # Read hook input from stdin (Claude Code provides transcript_path, session_id, etc.)
     hook_input = read_hook_stdin()
 
+    # 触发事件类型：Stop=会话结束（收尾，全量上报）；PostToolUse=任务进行中（增量上报）。
+    # 缺省按 Stop 处理，兼容旧注册与手动调用。
+    hook_event = (hook_input.get("hook_event_name") or "Stop").strip()
+    is_terminal_event = hook_event not in ("PostToolUse", "PreToolUse")
+
     # Determine conversation file: prefer stdin, fallback to file scan
     conversation_file = hook_input.get("transcript_path")
     if conversation_file:
@@ -1637,6 +1674,16 @@ def main():
     state = load_state(state_file)
     last_processed_line = state.get("last_processed_line", 0)
 
+    # 节流：PostToolUse 在密集工具调用下会高频触发。距上次上报不足 INCREMENTAL_UPLOAD_MIN_INTERVAL
+    # 秒则跳过本次增量上报，避免每秒多次 flush 抬高上报量/成本。终态事件(Stop)永不被节流，
+    # 保证任务结束时一定收尾上报最后一批。
+    if not is_terminal_event:
+        now_ts = time.time()
+        last_upload_ts = state.get("last_upload_ts", 0)
+        if now_ts - last_upload_ts < INCREMENTAL_UPLOAD_MIN_INTERVAL:
+            debug_log(f"throttled: event={hook_event} since_last={now_ts - last_upload_ts:.1f}s < {INCREMENTAL_UPLOAD_MIN_INTERVAL}s, skip")
+            return
+
     # Read new messages from the file
     new_messages = read_new_messages(conversation_file, last_processed_line)
 
@@ -1685,18 +1732,38 @@ def main():
         if not has_coze_ctx:
             debug_log("No coze-context found in any turn (incl. history), skipping upload.")
             return
-        print(f"[CozeLoop] 开始上报: session={session_id}, turns={len(turns)}", file=sys.stderr)
-        uploaded = send_turns_to_cozeloop(turns, session_id, history_turns)
+
+        # turn 边界控制：中途事件(PostToolUse)触发时，最后一个 turn 往往仍在进行中
+        # （后续还会追加 step）。若此刻就上报并推进其行号，同一逻辑 turn 会在下次触发时
+        # 因缺了起始 user 消息而被拆成新的 root span。故中途事件只上报“已完成”的 turn
+        # （= 除最后一个之外的所有 turn），把最后一个留到下次/收尾。终态事件(Stop)上报全部。
+        if is_terminal_event:
+            turns_to_send = turns
+        else:
+            turns_to_send = turns[:-1]
+        if not turns_to_send:
+            debug_log(f"event={hook_event}: no completed turn to send yet (turns={len(turns)}), defer")
+            return
+
+        print(f"[CozeLoop] 开始上报: session={session_id}, event={hook_event}, turns={len(turns_to_send)}/{len(turns)}", file=sys.stderr)
+        uploaded = send_turns_to_cozeloop(turns_to_send, session_id, history_turns)
         if uploaded is None:
             debug_log("Send failed, state not advanced.")
             return
 
-        # Update state with the new last processed line number
-        last_line_in_batch = max(msg.get("_line_number", 0) for msg in new_messages)
-        state["last_processed_line"] = last_line_in_batch + 1
+        # 推进 last_processed_line：只推进到已上报 turn 覆盖的最后一行。中途事件保留了最后一个
+        # 未完成 turn，故推进到“倒数第二个 turn 的末行”，让未完成 turn 的所有行下次重新读取。
+        if is_terminal_event:
+            last_line_in_batch = max(msg.get("_line_number", 0) for msg in new_messages)
+            state["last_processed_line"] = last_line_in_batch + 1
+        else:
+            # turns_to_send 是 turns[:-1]，下一个未发送 turn 的起始行即新的水位线。
+            next_turn_start = turns[-1].get("start_line", 0)
+            state["last_processed_line"] = next_turn_start
+        state["last_upload_ts"] = time.time()
         save_state(state_file, state)
-        print(f"[CozeLoop] 上报完成 ✓ session={session_id}, turns={len(turns)}", file=sys.stderr)
-        debug_log(f"State updated. Last processed line: {state['last_processed_line']}")
+        print(f"[CozeLoop] 上报完成 ✓ session={session_id}, turns={len(turns_to_send)}", file=sys.stderr)
+        debug_log(f"State updated. event={hook_event} last_processed_line={state['last_processed_line']}")
 
     debug_log("Hook finished.")
 

package/scripts/codex/cozeloop_hook.py

@@ -50,6 +50,10 @@ _REFRESH_LOCK_STALE = 30
 _DEFAULT_WORKSPACE_ID = "7649231955045072915"  # hardcoded spaceID fallback
 _OTEL_SUFFIX = "/v1/loop/opentelemetry"
 
+# 中途事件(PostToolUse)增量上报的最小间隔（秒）。密集工具调用下用它节流，避免每次工具调用都 flush。
+# 终态事件(Stop/SubagentStop)不受此限制。
+INCREMENTAL_UPLOAD_MIN_INTERVAL = float(os.environ.get("COZELOOP_INCREMENTAL_MIN_INTERVAL", "10"))
+
 
 # --- coze-context parsing -------------------------------------------------
 # User messages may embed a block like:
@@ -351,7 +355,8 @@ def _token_from_credentials():
     creds = _load_credentials()
     if not creds:
         return None
-    remaining = creds.get("expires_at", 0) / 1000 - time.time()
+    # expires_at 由 index.js 以毫秒存储；先减去当前毫秒时间再换算成秒，与 _REFRESH_THRESHOLD(秒) 比较。
+    remaining = (creds.get("expires_at", 0) - time.time() * 1000) / 1000
     if remaining > _REFRESH_THRESHOLD:
         return creds.get("access_token")
     if creds.get("refresh_token"):
@@ -1102,7 +1107,13 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
         )
         print("[CozeLoop] 警告: 未找到有效 Token，上报可能失败", file=sys.stderr)
     creds = _load_credentials()
-    workspace_id = (creds or {}).get("workspace_id") or os.environ.get("COZELOOP_WORKSPACE_ID", "") or _DEFAULT_WORKSPACE_ID
+    # 云端模式：sandbox 注入的 COZELOOP_WORKSPACE_ID 必须优先于 credentials.json。
+    # 否则残留的本地 credentials.json workspace_id 会覆盖云端注入，导致 trace 上报错位。
+    is_cloud = os.environ.get("COZELAB_ONBOARD_CLOUD", "").lower() in ("1", "true", "yes")
+    if is_cloud:
+        workspace_id = os.environ.get("COZELOOP_WORKSPACE_ID", "") or (creds or {}).get("workspace_id") or _DEFAULT_WORKSPACE_ID
+    else:
+        workspace_id = (creds or {}).get("workspace_id") or os.environ.get("COZELOOP_WORKSPACE_ID", "") or _DEFAULT_WORKSPACE_ID
     os.environ["COZELOOP_WORKSPACE_ID"] = workspace_id
     hook_log(f"workspace_id={workspace_id}")
     upload_events: List[str] = []
@@ -1151,6 +1162,16 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
                 t = {f"coze_{k}": v for k, v in turn_coze_context(turn).items()}
                 if t:
                     coze_tags = t
+            # Drop empty-valued coze_* tags: the backend pairs traces by exact tag
+            # match (coze_message_id / coze_agent_id), where an empty string is
+            # indistinguishable from "absent" yet still bloats the span — never
+            # emit one. Log when a pairing key is missing so a silent pairing miss
+            # is debuggable.
+            coze_tags = {k: v for k, v in coze_tags.items() if isinstance(v, str) and v.strip()}
+            if not coze_tags.get("coze_message_id"):
+                hook_log(f"coze-context missing coze_message_id session_id={session_id}")
+            if not coze_tags.get("coze_session_id"):
+                hook_log(f"coze-context missing coze_session_id session_id={session_id}")
             if coze_tags:
                 root_tags.update(coze_tags)
                 root_baggage.update(coze_tags)
@@ -1488,6 +1509,19 @@ def send_turns_to_cozeloop(turns: List[Dict[str, Any]], session_id: str, model_n
         debug_log(f"An error occurred while sending traces to CozeLoop: {e}")
         return None
     finally:
+        # Flush buffered spans BEFORE closing so a slow/failed close() can't drop
+        # them. close() also flushes, but flushing first surfaces the upload
+        # failure (via trace_finish_event_processor -> upload_events) while the
+        # client is still usable.
+        # KNOWN RISK: when flush/close reports a 401, the block below re-sends the
+        # ENTIRE turn batch with a refreshed token. The SDK has no per-span ack, so
+        # any batch the first attempt already delivered before the auth failure is
+        # uploaded a second time -> duplicate trace. Acceptable for now (a missing
+        # trace is worse than a dup); revisit if the SDK gains partial-ack/resume.
+        try:
+            client.flush()
+        except Exception as _flush_err:
+            debug_log(f"client.flush() before close failed: {_flush_err}")
         client.close()
         hook_log("client closed")
         debug_log("CozeLoop client closed.")
@@ -1545,6 +1579,11 @@ def main():
 
     debug_log(f"Hook input: {json.dumps(hook_input, ensure_ascii=False)}")
 
+    # 触发事件类型：Stop/SubagentStop=turn 结束（收尾，全量上报）；PostToolUse=turn 进行中
+    # （增量上报，仅上报已完成 turn + 节流）。缺省按终态处理，兼容旧注册与手动调用。
+    hook_event = (hook_input.get("hook_event_name") or "Stop").strip()
+    is_terminal_event = hook_event not in ("PostToolUse", "PreToolUse")
+
     # Get transcript path
     transcript_path = hook_input.get("transcript_path")
     if not transcript_path:
@@ -1633,7 +1672,12 @@ def main():
 
     # Send turns to CozeLoop — only if at least one turn carries coze-context.
     if turns:
-        has_coze_ctx = any(
+        # coze-context 只出现在首个 turn 的 user 消息里。增量上报推进后，后续批次的 turns
+        # 已不含首 turn，直接判断会误判为"无 coze-context"而跳过。故用 state 持久化"本会话
+        # 曾见过 coze-context"标记：一旦见过，后续增量批次都视为应上报（与 claude-code 用
+        # history_turns 判断等效）。
+        seen_ctx = bool(state.get("seen_coze_context"))
+        has_coze_ctx = seen_ctx or any(
             turn_coze_context(t)
             for t in turns
         )
@@ -1641,17 +1685,48 @@ def main():
             hook_log(f"skip no coze-context turns={len(turns)} session_id={session_id}")
             debug_log("No coze-context found in any turn, skipping upload.")
             return
+        if not seen_ctx:
+            state["seen_coze_context"] = True
+
+        # 节流：PostToolUse 在密集工具调用下高频触发。距上次上报不足间隔则跳过本次增量上报。
+        # 终态事件(Stop/SubagentStop)永不被节流，保证 turn 结束时一定收尾。
+        if not is_terminal_event:
+            now_ts = time.time()
+            last_upload_ts = state.get("last_upload_ts", 0)
+            if now_ts - last_upload_ts < INCREMENTAL_UPLOAD_MIN_INTERVAL:
+                hook_log(f"throttled event={hook_event} since_last={now_ts - last_upload_ts:.1f}s session_id={session_id}")
+                debug_log(f"throttled: event={hook_event}, skip incremental upload")
+                return
+
+        # turn 边界控制：中途事件(PostToolUse)触发时，最后一个 turn 往往仍在进行中
+        # （task_complete 尚未到达，后续还会追加内容）。只上报已完成 turn（turns[:-1]），
+        # 把最后一个留到下次/收尾，避免同一 turn 被拆成多个 trace。终态事件上报全部。
+        if is_terminal_event:
+            turns_to_send = turns
+        else:
+            turns_to_send = turns[:-1]
+        if not turns_to_send:
+            hook_log(f"defer no completed turn event={hook_event} turns={len(turns)} session_id={session_id}")
+            debug_log(f"event={hook_event}: no completed turn to send yet, defer")
+            return
+
         history_context = state.get("conversation_history", [])
         updated_history = send_turns_to_cozeloop(
-            turns, session_id, model_name,
+            turns_to_send, session_id, model_name,
             history_context=history_context,
         )
         if updated_history is not None:
-            last_line = max(e.get("_line_number", 0) for e in entries) + 1
+            # 推进 last_processed_line：终态推进到所有 entry 末行；中途保留最后一个未完成 turn，
+            # 推进到该 turn 的起始行，让它的所有 entry 下次重新读取。
+            if is_terminal_event:
+                last_line = max(e.get("_line_number", 0) for e in entries) + 1
+            else:
+                last_line = turns[-1].get("start_line", max(e.get("_line_number", 0) for e in entries) + 1)
             state["last_processed_line"] = last_line
             state["conversation_history"] = updated_history
+            state["last_upload_ts"] = time.time()
             save_state(state_file, state)
-            hook_log(f"state advanced last_line={last_line} session_id={session_id}")
+            hook_log(f"state advanced event={hook_event} last_line={last_line} sent={len(turns_to_send)}/{len(turns)} session_id={session_id}")
             debug_log(f"State updated, last processed line: {last_line}")
         else:
             hook_log(f"send failed state not advanced session_id={session_id}")

package/scripts/openclaw/dist/cozeloop-exporter.js

@@ -404,6 +404,11 @@ class CozeloopIngestExporter {
         this.serviceName = config.serviceName;
         this.onAuthFailure = config.onAuthFailure;
         this.shutdownRequested = false;
+        // In-flight postSpans() promises. export() returns void (OTel contract),
+        // so without tracking these the process can exit while an HTTP POST is
+        // still pending and silently drop the span batch. forceFlush() awaits
+        // this set so dispose()/shutdown() can guarantee delivery.
+        this.pendingPromises = new Set();
         fileLog(this.logFile, `[ingest] exporter ready url=${this.url} workspaceId=${this.workspaceId}`);
     }
     export(spans, resultCallback) {
@@ -411,13 +416,17 @@ class CozeloopIngestExporter {
             resultCallback({ code: EXPORT_SUCCESS });
             return;
         }
-        this.postSpans(spans)
+        const pending = this.postSpans(spans)
             .then(() => resultCallback({ code: EXPORT_SUCCESS }))
             .catch((err) => {
                 this.logger?.error?.(`[CozeloopTrace] CozeLoop ingest export failed: ${err?.message || err}`);
                 fileLog(this.logFile, `[ingest] export FAILED url=${this.url} spans=${spans.length} err=${err?.message || err}`);
                 resultCallback({ code: EXPORT_FAILED, error: err });
+            })
+            .finally(() => {
+                this.pendingPromises.delete(pending);
             });
+        this.pendingPromises.add(pending);
     }
     async postSpans(spans) {
         const body = {
@@ -486,10 +495,15 @@ class CozeloopIngestExporter {
         fileLog(this.logFile, `[ingest] OK HTTP ${res.status} spans=${body.spans.length}${retry ? " retry=1" : ""}`);
     }
     async forceFlush() {
-        return;
+        // Wait for every in-flight POST to settle. allSettled (not all) so one
+        // failed batch doesn't abort the wait on the others.
+        if (this.pendingPromises.size > 0) {
+            await Promise.allSettled([...this.pendingPromises]);
+        }
     }
     async shutdown() {
         this.shutdownRequested = true;
+        await this.forceFlush();
     }
 }
 
@@ -888,6 +902,9 @@ export class CozeloopExporter {
     async dispose() {
         if (this.provider) {
             try {
+                // Flush in-flight batches before tearing the provider down so a
+                // pending HTTP POST is never killed by process exit.
+                await this.flush();
                 await this.provider.shutdown();
             }
             catch (err) {

package/scripts/openclaw/dist/index.js

@@ -70,7 +70,11 @@ function parseCozeContext(input) {
             continue;
         const key = line.slice(0, sep).trim();
         const value = line.slice(sep + 1).trim();
-        if (key)
+        // Tag keys map directly onto backend trace-query field names, so only
+        // accept the same charset the keys are written in (letters/digits/_).
+        // Lines whose key carries any other char are malformed — skip them
+        // rather than emit a tag the backend Eq filter could never hit.
+        if (key && /^[A-Za-z0-9_]+$/.test(key))
             out["coze_" + key] = value;
     }
     return out;
@@ -1409,14 +1413,17 @@ const cozeloopTracePlugin = {
         };
         // OpenClaw runtime 周期性发送的心跳轮询消息，不是真实对话，整条 trace 丢弃。
         const HEARTBEAT_INPUT = "[OpenClaw heartbeat poll]";
+        // 宽松匹配：trim 后只要包含心跳标记即算心跳，避免 runtime 加前后缀/包裹时漏判。
+        const isHeartbeatText = (text) => typeof text === "string"
+            && text.trim().includes(HEARTBEAT_INPUT);
         const isHeartbeatInput = (input) => {
             if (typeof input === "string") {
-                return input.trim() === HEARTBEAT_INPUT;
+                return isHeartbeatText(input);
             }
             // content 可能是 [{type:'text', text:'...'}] 形式
             if (Array.isArray(input)) {
                 return input.some((p) => p && typeof p === "object"
-                    && typeof p.text === "string" && p.text.trim() === HEARTBEAT_INPUT);
+                    && isHeartbeatText(p.text));
             }
             return false;
         };
@@ -1428,6 +1435,7 @@ const cozeloopTracePlugin = {
             const lastUserFallback = lastUserFallbackFor(ctx, channelId);
             const heartbeatInput = ctx.userInput
                 || lastUserFallback?.userInput || (lastUserFallback ? lastUserInput : undefined);
+            const currentIsHeartbeat = isHeartbeatInput(ctx.userInput);
             if (isHeartbeatInput(heartbeatInput)) {
                 if (config.debug) {
                     api.logger.info(`[CozeloopTrace] skip heartbeat poll trace, traceId=${ctx.traceId}`);
@@ -1439,13 +1447,24 @@ const cozeloopTracePlugin = {
             // /loop follow-ups and later turns have none. Fall back to the per-
             // session cache (and global last-seen) instead of dropping the trace.
             // Only skip when NO context has ever been seen for this session.
+            //
+            // EXCEPTION: never apply the cache fallback to a heartbeat poll — the
+            // cache could resurrect a previous real turn's coze-context and make
+            // the heartbeat masquerade as that conversation (a phantom trace).
+            // Claude-code / codex hooks only look at the current turn; match that.
             const ocSessionId = ctx.openclawSessionId || lastOpenclawSessionId;
-            rememberCozeContext(ctx.userInput, ocSessionId);
-            let cozeCtx = resolveCozeContext(ctx.userInput, ocSessionId);
-            if (Object.keys(cozeCtx).length === 0) {
-                // Try the fallback user inputs too before giving up.
-                const fallbackInput = lastUserFallback?.userInput || (lastUserFallback ? lastUserInput : undefined);
-                cozeCtx = resolveCozeContext(fallbackInput, ocSessionId);
+            let cozeCtx;
+            if (currentIsHeartbeat) {
+                cozeCtx = parseCozeContext(ctx.userInput);
+            }
+            else {
+                rememberCozeContext(ctx.userInput, ocSessionId);
+                cozeCtx = resolveCozeContext(ctx.userInput, ocSessionId);
+                if (Object.keys(cozeCtx).length === 0) {
+                    // Try the fallback user inputs too before giving up.
+                    const fallbackInput = lastUserFallback?.userInput || (lastUserFallback ? lastUserInput : undefined);
+                    cozeCtx = resolveCozeContext(fallbackInput, ocSessionId);
+                }
             }
             if (Object.keys(cozeCtx).length === 0) {
                 return;
@@ -1477,6 +1496,20 @@ const cozeloopTracePlugin = {
             if (!ctx.userInput) {
                 ctx.userInput = lastUserFallback?.userInput || (lastUserFallback ? lastUserInput : undefined);
             }
+            // Drop empty-valued coze_* tags: the backend pairs traces by exact
+            // tag match (coze_message_id / coze_session_id), and an empty-string
+            // tag is indistinguishable from "absent" there while still bloating
+            // the span — so never emit one. Log when the pairing keys are missing
+            // so a silent pairing miss is debuggable.
+            const cozeTags = {};
+            for (const [k, v] of Object.entries(cozeCtx)) {
+                if (typeof v === "string" && v.trim() !== "") {
+                    cozeTags[k] = v;
+                }
+            }
+            if (config.debug && (!cozeTags.coze_message_id || !cozeTags.coze_session_id)) {
+                api.logger.info(`[CozeloopTrace] coze-context missing pairing key(s): message_id=${cozeTags.coze_message_id ? "ok" : "MISSING"} session_id=${cozeTags.coze_session_id ? "ok" : "MISSING"}, traceId=${ctx.traceId}`);
+            }
             const rootSpanData = {
                 name: "openclaw_request",
                 type: "entry",
@@ -1486,7 +1519,7 @@ const cozeloopTracePlugin = {
                     "run.id": ctx.runId,
                     "turn.id": ctx.turnId,
                     "openclaw.channel_id": channelId,
-                    ...cozeCtx,
+                    ...cozeTags,
                 },
                 input: ctx.userInput,
                 traceId: ctx.traceId,

package/scripts/shared/cozeloop_refresh.py

@@ -44,7 +44,8 @@ def refresh(rt):
 def main():
     creds = load()
     if not creds: return
-    remaining = (creds.get("expires_at",0)/1000) - time.time()
+    # expires_at 由 index.js 以毫秒存储；先减去当前毫秒时间再换算成秒，与 THRESHOLD(秒) 比较。
+    remaining = (creds.get("expires_at",0) - time.time()*1000)/1000
     if remaining > THRESHOLD: return  # still fresh
     print(f"[cozeloop_refresh] token expiring in {int(remaining)}s, refreshing...", file=sys.stderr)
     if creds.get("refresh_token"):