oh-langfuse 0.1.19 → 0.1.20

package/README.md

@@ -1,175 +1,126 @@
 # oh-langfuse
 
-`oh-langfuse` 是用于配置 Langfuse 链路追踪的交互式命令行工具，支持
-Claude Code、OpenCode 和 Codex。它提供终端安装向导、直接 setup/check
-命令，以及不同工具所需的安装脚本和校验脚本。
+`oh-langfuse` 是用于给 Claude Code、OpenCode 和 Codex 配置 Langfuse 追踪的命令行工具。它提供交互式安装向导，也支持 `setup` / `check` 直接命令，方便在用户机器上安装、修复和校验配置。
 
-## 项目定位
+当前 npm 版本：`0.1.20`
 
-本仓是 AI Coding 工具链中的 Langfuse 能力包，负责：
+## 能做什么
 
-- 检查 Node.js、npm、Python、pip、OpenCode CLI 等本地依赖；
-- 收集 Langfuse 用户标识，必须匹配 `^[a-z](?:\d{8}|wx\d{7})$`，例如 `h00613222` 或 `hwx1234567`；
-- 安装或更新 hook 脚本、插件文件、Python 虚拟环境和用户级配置；
-- 校验 Claude Code、OpenCode、Codex 的 Langfuse 配置是否生效。
+- 给 Claude Code 安装 `Stop` hook，把会话事件写入 Langfuse。
+- 给 OpenCode 安装并 patch `opencode-plugin-langfuse`，开启 OpenTelemetry。
+- 给 Codex 安装 `notify` hook，增量读取 session JSONL 并写入 Langfuse。
+- 安装完成后自动执行对应 `check`，尽早发现配置缺失。
+- 校验员工号格式，必须匹配 `^[a-z](?:\d{8}|wx\d{7})$`，例如 `h00613222` 或 `hwx1234567`。
 
-本包发布到 npm 后暴露 `oh-langfuse` 命令，并被聚合安装器
-`oh-aicoding-tool` 调用。
+## 快速使用
 
-迁移期内，npm 包仍保留旧命令别名 `code-tool-langfuse`。
+建议始终带 `@latest`，避免 npx 使用本地旧缓存：
 
-## 环境要求
+```bash
+npx oh-langfuse@latest
+npx oh-langfuse@latest setup
+npx oh-langfuse@latest check
+```
 
-| 目标工具 | 依赖 |
-| --- | --- |
-| Claude Code | Node.js、npm、Python、pip |
-| OpenCode | Node.js、npm、OpenCode CLI |
-| Codex | Node.js、npm、Python、pip |
+也可以指定目标：
 
-Linux 环境如果创建 Python venv 失败，请先安装 `python3-venv`。
+```bash
+npx oh-langfuse@latest setup claude
+npx oh-langfuse@latest setup opencode
+npx oh-langfuse@latest setup codex
 
-## 使用方式
+npx oh-langfuse@latest check claude
+npx oh-langfuse@latest check opencode
+npx oh-langfuse@latest check codex
+```
 
-从当前仓库运行：
+本地开发运行：
 
 ```bash
 npm install
 npm start
 ```
 
-npm 发布后运行：
+## 交互式菜单
 
-```bash
-npx oh-langfuse@latest
-```
-
-建议始终带 `@latest` 运行，避免 npx 使用本地缓存里的旧版本。
+运行 `npx oh-langfuse@latest` 会打开交互式菜单：
 
-交互界面支持：
+- `Up` / `Down` 移动选项。
+- 数字键快速定位。
+- `Space` 勾选或取消。
+- `Enter` 确认。
+- `q` 或 `Esc` 退出。
 
-- `Up` / `Down`：移动选项；
-- 数字键：快速选择；
-- `Space`：多选切换；
-- `Enter`：确认；
-- `q` 或 `Esc`：退出。
+多选菜单默认不勾选任何目标，避免误装。终端不支持原始按键输入时，会自动降级为数字输入模式。
 
-在不支持 raw input 的终端中，会自动退回到数字输入模式。
+## OpenCode 说明
 
-## 命令
+OpenCode 安装会写入：
 
-```bash
-oh-langfuse
-oh-langfuse setup
-oh-langfuse setup claude
-oh-langfuse setup opencode
-oh-langfuse setup codex
-oh-langfuse check
-oh-langfuse check environment
-oh-langfuse check claude
-oh-langfuse check opencode
-oh-langfuse check codex
-```
+- `~/.config/opencode/opencode.json`
+- `~/.config/opencode/plugins/opencode-plugin-langfuse`
+- `~/.config/opencode-plugin-langfuse/config.json`
+- Windows 下的 `~/.config/opencode/launch-opencode-langfuse.cmd`
+- Linux/macOS 下的 `~/.config/opencode/launch-opencode-langfuse.sh`
 
-预览安装动作，不写文件、不安装依赖：
+Windows 下安装器会尝试写入用户级 `LANGFUSE_PUBLIC_KEY`、`LANGFUSE_SECRET_KEY`、`LANGFUSE_BASEURL`。这些变量对当前已经打开的终端不会立即生效，需要新开终端，或者使用生成的 launcher 启动 OpenCode。
 
-```bash
-oh-langfuse setup --dry-run
-```
+`check opencode` 已按实际情况处理 Windows：如果当前终端还看不到 `LANGFUSE_*`，但用户级环境变量已写入，或 launcher 已生成，会显示 OpenCode 仍有可用的 Langfuse 环境变量来源，不再把这种情况误判为安装失败。
 
-本仓内也可以直接运行脚本。面向用户排查时，推荐使用 `npx oh-langfuse@latest check ...`，这样不依赖源码目录：
+WSL 用户请直接在 WSL shell 中安装和检查：
 
 ```bash
-npm run claude:setup
-npm run opencode:setup
-npm run codex:setup
-npx oh-langfuse@latest check claude
+npx oh-langfuse@latest setup opencode --userId=h00613222 --yes
 npx oh-langfuse@latest check opencode
-npx oh-langfuse@latest check codex
 ```
 
-## 各目标工具写入的配置
-
-### Claude Code
+不会做 Windows 到 WSL 的转发；在 WSL 中运行时，配置写入 WSL 用户自己的 `$HOME/.config/opencode`。
 
-安装 `langfuse_hook.py`，创建 `~/.claude/langfuse-venv`，安装 Python 包
-`langfuse`，并把 Langfuse 环境变量和 `Stop` hook 合并写入
-`~/.claude/settings.json`。
+## Claude Code 说明
 
-### OpenCode
-
-安装并 patch `opencode-plugin-langfuse`，在
-`~/.config/opencode/opencode.json` 中启用 OpenTelemetry，写入插件用户配置，
-并可写入用户级 `LANGFUSE_*` 环境变量。Windows 下会生成
-`launch-opencode-langfuse.cmd`，Linux/macOS 下会生成
-`launch-opencode-langfuse.sh`，用于在 shell 环境变量未生效时显式带
-Langfuse 配置启动 OpenCode。安装器可以读取带注释或尾随逗号的
-`opencode.json`，合并配置后会写回标准 JSON。
-
-如果你在 WSL 里运行 OpenCode，就在 WSL shell 里直接执行安装和检查命令。
-此时配置会写入 WSL 用户自己的 `$HOME/.config/opencode`：
-
-```bash
-npx oh-langfuse@latest setup opencode --userId=h00613222 --yes
-npx oh-langfuse@latest check opencode
-```
+Claude Code 安装会：
 
-安装完成后会自动执行一次 `check opencode`。如果检查提示当前终端缺少
-`LANGFUSE_*`，请新开一个 WSL 终端，或执行安装器提示的 `source ~/.bashrc`
-/ `source ~/.zshrc`，也可以直接使用生成的
-`~/.config/opencode/launch-opencode-langfuse.sh` 启动 OpenCode。
+- 安装 `langfuse_hook.py`
+- 创建 `~/.claude/langfuse-venv`
+- 安装 Python 包 `langfuse`
+- 合并更新 `~/.claude/settings.json`
+- 配置 `Stop` hook
 
-如果 `opencode.json` 原本是 JSONC 风格（例如带注释或尾随逗号），安装器会先兼容读取，
-再写回标准 JSON。
+Linux 如果缺少 venv 支持，请根据提示安装 `python3-venv` 或对应 Python 版本的 venv 包。
 
-### Codex
+## Codex 说明
 
-安装 `codex_langfuse_notify.py`，创建 `~/.codex/langfuse-venv`，安装 Python
-包 `langfuse`，把 Langfuse 凭据写入 `~/.codex/langfuse/config.json`，并更新
-`~/.codex/config.toml` 顶层 `notify` 命令。安装后需要重启 Codex。
+Codex 安装会：
 
-Codex 集成通过 notify hook 实现：每次通知事件会增量读取对应的
-`~/.codex/sessions/**/*.jsonl`，把新增的 user、assistant、tool、token 事件转换成
-Langfuse observation，并把读取偏移记录到 `~/.codex/langfuse/state.json`。
+- 安装 `codex_langfuse_notify.py`
+- 创建 `~/.codex/langfuse-venv`
+- 写入 `~/.codex/langfuse/config.json`
+- 更新 `~/.codex/config.toml` 顶层 `notify`
 
-## 环境变量覆盖
+配置后需要重启 Codex。notify hook 会增量读取 `~/.codex/sessions/**/*.jsonl`，把新的 user、assistant、tool、token 事件转换为 Langfuse observation，并把读取偏移记录到 `~/.codex/langfuse/state.json`。
 
-工具内置了内部 Langfuse 服务的默认值，可通过以下变量覆盖：
+## 环境变量
 
 | 变量 | 作用 |
 | --- | --- |
 | `LANGFUSE_BASEURL` / `LANGFUSE_HOST` | Langfuse 服务地址 |
 | `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
 | `LANGFUSE_SECRET_KEY` | Langfuse secret key |
-| `LANGFUSE_USER_ID` / `CC_USER_ID` | 用户标识或员工号 |
+| `LANGFUSE_USER_ID` / `CC_USER_ID` | 用户标识，必须匹配员工号规则 |
 | `CODEX_HOME` | 自定义 Codex home 目录 |
-| `OPENCODE_SKIP_PLUGIN_INSTALL` | OpenCode 插件已准备好时跳过 npm 安装 |
-| `OPENCODE_NPM_REGISTRY` | OpenCode 插件 npm 安装源，例如 `https://registry.npmmirror.com` |
-
-交互界面不会明文打印 secret key。
+| `OPENCODE_SKIP_PLUGIN_INSTALL` | 跳过 OpenCode npm 插件安装 |
+| `OPENCODE_NPM_REGISTRY` | OpenCode 插件 npm 安装源 |
 
-## 目录结构
+Secret key 不会在交互式界面中明文展示。
 
-| 路径 | 说明 |
-| --- | --- |
-| `bin/cli.js` | 交互式和直接命令入口 |
-| `scripts/langfuse-setup.mjs` | Claude Code Langfuse 安装 |
-| `scripts/opencode-langfuse-setup.mjs` | OpenCode Langfuse 安装 |
-| `scripts/codex-langfuse-setup.mjs` | Codex Langfuse 安装 |
-| `scripts/*-check.mjs` | 配置校验脚本 |
-| `langfuse_hook.py` | Claude Code hook exporter |
-| `codex_langfuse_notify.py` | Codex notify exporter |
-
-## 发布与维护
-
-- npm 包名：`oh-langfuse`
-- 主命令：`oh-langfuse`
-- 兼容命令：`code-tool-langfuse`
-- 发布前建议运行：
+## 常用维护命令
 
 ```bash
 npm run check
 npm pack --dry-run
 ```
 
-维护时请保持 README 命令列表、`bin/cli.js` 和 `package.json` 的 `bin/files`
-字段一致。
+发布包暴露两个命令：
+
+- `oh-langfuse`
+- `code-tool-langfuse`，兼容旧入口

package/langfuse_hook.py

@@ -15,10 +15,18 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
 # --- Langfuse import (fail-open) ---
-try:
-    from langfuse import Langfuse, propagate_attributes
-except Exception:
-    sys.exit(0)
+try:
+    from langfuse import Langfuse, propagate_attributes
+except Exception as e:
+    try:
+        state_dir = Path.home() / ".claude" / "state"
+        state_dir.mkdir(parents=True, exist_ok=True)
+        with open(state_dir / "langfuse_hook.log", "a", encoding="utf-8") as f:
+            ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            f.write(f"{ts} [ERROR] Failed to import langfuse package: {e}\n")
+    except Exception:
+        pass
+    sys.exit(0)
 
 # --- Paths ---
 STATE_DIR = Path.home() / ".claude" / "state"
@@ -325,22 +333,32 @@ def read_new_jsonl(transcript_path: Path, ss: SessionState) -> Tuple[List[Dict[s
         text = chunk.decode(errors="replace")
 
     combined = ss.buffer + text
-    lines = combined.split("\n")
-    # last element may be incomplete
-    ss.buffer = lines[-1]
-    ss.offset = new_offset
-
-    msgs: List[Dict[str, Any]] = []
-    for line in lines[:-1]:
-        line = line.strip()
+    lines = combined.split("\n")
+    tail = lines[-1]
+    ss.offset = new_offset
+
+    msgs: List[Dict[str, Any]] = []
+    for line in lines[:-1]:
+        line = line.strip()
         if not line:
             continue
         try:
             msgs.append(json.loads(line))
-        except Exception:
-            continue
-
-    return msgs, ss
+        except Exception:
+            continue
+
+    tail = tail.strip()
+    if tail:
+        try:
+            msgs.append(json.loads(tail))
+            ss.buffer = ""
+        except Exception:
+            # Keep a genuinely partial final line for the next hook run.
+            ss.buffer = tail
+    else:
+        ss.buffer = ""
+
+    return msgs, ss
 
 # ----------------- Turn assembly -----------------
 @dataclass
@@ -520,32 +538,34 @@ def main() -> int:
     start = time.time()
     debug("Hook started")
 
-    if os.environ.get("TRACE_TO_LANGFUSE", "").lower() != "true":
-        return 0
-
-    public_key = os.environ.get("CC_LANGFUSE_PUBLIC_KEY") or os.environ.get("LANGFUSE_PUBLIC_KEY")
-    secret_key = os.environ.get("CC_LANGFUSE_SECRET_KEY") or os.environ.get("LANGFUSE_SECRET_KEY")
-    host = os.environ.get("CC_LANGFUSE_BASE_URL") or os.environ.get("LANGFUSE_BASEURL") or "https://cloud.langfuse.com"
-
-    if not public_key or not secret_key:
-        return 0
-
-    payload = read_hook_payload()
-    session_id, transcript_path, user_id = extract_session_transcript_and_user(payload)
-
-    if not session_id or not transcript_path:
-        # No structured payload; fail open (do not guess)
-        debug("Missing session_id or transcript_path from hook payload; exiting.")
-        return 0
-
-    if not transcript_path.exists():
-        debug(f"Transcript path does not exist: {transcript_path}")
-        return 0
-
-    try:
-        langfuse = Langfuse(public_key=public_key, secret_key=secret_key, host=host)
-    except Exception:
-        return 0
+    if os.environ.get("TRACE_TO_LANGFUSE", "").lower() != "true":
+        return 0
+
+    public_key = os.environ.get("CC_LANGFUSE_PUBLIC_KEY") or os.environ.get("LANGFUSE_PUBLIC_KEY")
+    secret_key = os.environ.get("CC_LANGFUSE_SECRET_KEY") or os.environ.get("LANGFUSE_SECRET_KEY")
+    host = os.environ.get("CC_LANGFUSE_BASE_URL") or os.environ.get("LANGFUSE_BASEURL") or "https://cloud.langfuse.com"
+
+    if not public_key or not secret_key:
+        warn("Missing Langfuse public/secret key in hook environment; exiting.")
+        return 0
+
+    payload = read_hook_payload()
+    session_id, transcript_path, user_id = extract_session_transcript_and_user(payload)
+
+    if not session_id or not transcript_path:
+        # No structured payload; fail open (do not guess)
+        warn("Missing session_id or transcript_path from hook payload; exiting.")
+        return 0
+
+    if not transcript_path.exists():
+        warn(f"Transcript path does not exist: {transcript_path}")
+        return 0
+
+    try:
+        langfuse = Langfuse(public_key=public_key, secret_key=secret_key, host=host)
+    except Exception as e:
+        warn(f"Langfuse init failed: {e}")
+        return 0
 
     try:
         with FileLock(LOCK_FILE):
@@ -570,20 +590,21 @@ def main() -> int:
             for t in turns:
                 emitted += 1
                 turn_num = ss.turn_count + emitted
-                try:
-                    emit_turn(langfuse, session_id, user_id, turn_num, t, transcript_path)
-                except Exception as e:
-                    debug(f"emit_turn failed: {e}")
-                    # continue emitting other turns
+                try:
+                    emit_turn(langfuse, session_id, user_id, turn_num, t, transcript_path)
+                except Exception as e:
+                    warn(f"emit_turn failed: {e}")
+                    # continue emitting other turns
 
             ss.turn_count += emitted
             write_session_state(state, key, ss)
             save_state(state)
 
-        try:
-            langfuse.flush()
-        except Exception:
-            pass
+        try:
+            langfuse.flush()
+        except Exception as e:
+            warn(f"Langfuse flush failed: {e}")
+            pass
 
         dur = time.time() - start
         info(f"Processed {emitted} turns in {dur:.2f}s (session={session_id})")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-langfuse",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "private": false,
   "type": "module",
   "description": "Use npm scripts to configure Claude Code / OpenCode / Codex with Langfuse tracing.",

package/scripts/langfuse-check.mjs

@@ -1,90 +1,161 @@
-import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
-
-function readJsonIfExists(p) {
-  if (!fs.existsSync(p)) return null;
-  const txt = fs.readFileSync(p, "utf8");
-  if (!txt.trim()) return null;
-  return JSON.parse(txt);
-}
-
-function main() {
-  const userHome = os.homedir();
-  const claudeDir = path.join(userHome, ".claude");
-  const hooksDir = path.join(claudeDir, "hooks");
-  const settingsPath = path.join(claudeDir, "settings.json");
-
-  const results = [];
-
-  results.push({
-    item: "hooks 目录",
-    ok: fs.existsSync(hooksDir),
-    detail: hooksDir
-  });
-
-  const pyPath = path.join(hooksDir, "langfuse_hook.py");
-  results.push({
-    item: "hook 脚本",
-    ok: fs.existsSync(pyPath),
-    detail: pyPath
-  });
-
-  const settings = readJsonIfExists(settingsPath);
-  results.push({
-    item: "settings.json",
-    ok: !!settings,
-    detail: settingsPath
-  });
-
-  const env = settings?.env;
-  const neededEnv = [
-    "TRACE_TO_LANGFUSE",
-    "LANGFUSE_PUBLIC_KEY",
-    "LANGFUSE_SECRET_KEY",
-    "LANGFUSE_HOST",
-    "CC_LANGFUSE_BASE_URL",
-    "LANGFUSE_BASEURL"
-  ];
-
-  const missingEnv = neededEnv.filter((k) => !env || typeof env[k] === "undefined");
-  results.push({
-    item: "env 必要字段",
-    ok: missingEnv.length === 0,
-    detail: missingEnv.length ? `缺少：${missingEnv.join(", ")}` : "OK"
-  });
-
-  const stopHooks = settings?.hooks?.Stop;
-  let hasStop = false;
-  if (Array.isArray(stopHooks)) {
-    for (const entry of stopHooks) {
-      const hooks = entry?.hooks;
-      if (!Array.isArray(hooks)) continue;
-      for (const h of hooks) {
-        if (h?.type === "command" && typeof h?.command === "string" && h.command.includes("langfuse_hook.py")) {
-          hasStop = true;
-          break;
-        }
-      }
-      if (hasStop) break;
-    }
-  }
-  results.push({
-    item: "hooks.Stop 配置",
-    ok: hasStop,
-    detail: hasStop ? "OK" : "未找到指向 langfuse_hook.py 的 Stop hook"
-  });
-
-  const pad = (s, n) => (s.length >= n ? s : s + " ".repeat(n - s.length));
-  const w = Math.max(...results.map((r) => r.item.length)) + 2;
-  for (const r of results) {
-    const status = r.ok ? "OK " : "BAD";
-    console.log(`${status}  ${pad(r.item, w)} ${r.detail}`);
-  }
-
-  const failed = results.filter((r) => !r.ok);
-  process.exit(failed.length ? 2 : 0);
-}
-
-main();
-
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+
+function readJsonIfExists(p) {
+  if (!fs.existsSync(p)) return null;
+  const txt = fs.readFileSync(p, "utf8");
+  if (!txt.trim()) return null;
+  return JSON.parse(txt);
+}
+
+function addResult(results, item, ok, detail, fix = "") {
+  results.push({ item, ok, detail, fix });
+}
+
+function findLangfuseHook(settings) {
+  const stopHooks = settings?.hooks?.Stop;
+  if (!Array.isArray(stopHooks)) return null;
+  for (const entry of stopHooks) {
+    const hooks = entry?.hooks;
+    if (!Array.isArray(hooks)) continue;
+    for (const h of hooks) {
+      if (h?.type !== "command") continue;
+      const command = typeof h.command === "string" ? h.command : "";
+      const args = Array.isArray(h.args) ? h.args : [];
+      const joined = [command, ...args].join(" ");
+      if (joined.includes("langfuse_hook.py")) return { command, args };
+    }
+  }
+  return null;
+}
+
+function hookUsesExecForm(hook) {
+  return !!(hook?.command && Array.isArray(hook.args) && hook.args.some((arg) => String(arg).includes("langfuse_hook.py")));
+}
+
+function pathExists(p) {
+  return typeof p === "string" && p.length > 0 && fs.existsSync(p);
+}
+
+function checkPythonLangfuseImport(pythonPath) {
+  if (!pathExists(pythonPath)) return { ok: false, detail: "python executable missing" };
+  const result = spawnSync(pythonPath, ["-c", "import langfuse; print('OK')"], {
+    encoding: "utf8",
+    timeout: 15000,
+    windowsHide: true
+  });
+  if (result.status === 0) return { ok: true, detail: "OK" };
+  const err = `${result.stderr || result.stdout || result.error?.message || "unknown error"}`.trim();
+  return { ok: false, detail: err || "import failed" };
+}
+
+function main() {
+  const userHome = os.homedir();
+  const claudeDir = path.join(userHome, ".claude");
+  const hooksDir = path.join(claudeDir, "hooks");
+  const settingsPath = path.join(claudeDir, "settings.json");
+  const logPath = path.join(claudeDir, "state", "langfuse_hook.log");
+
+  const results = [];
+
+  addResult(results, "Claude config dir", fs.existsSync(claudeDir), claudeDir, "Run: npx oh-langfuse@latest setup claude");
+  addResult(results, "hooks dir", fs.existsSync(hooksDir), hooksDir, "Run setup again to install the hook script.");
+
+  const pyPath = path.join(hooksDir, "langfuse_hook.py");
+  addResult(results, "hook script", fs.existsSync(pyPath), pyPath, "Run setup again to copy langfuse_hook.py.");
+
+  const settings = readJsonIfExists(settingsPath);
+  addResult(results, "settings.json", !!settings, settingsPath, "Run setup again to write Claude settings.");
+
+  const env = settings?.env;
+  const neededEnv = [
+    "TRACE_TO_LANGFUSE",
+    "LANGFUSE_PUBLIC_KEY",
+    "LANGFUSE_SECRET_KEY",
+    "LANGFUSE_HOST",
+    "CC_LANGFUSE_BASE_URL",
+    "LANGFUSE_BASEURL"
+  ];
+
+  const missingEnv = neededEnv.filter((k) => !env || typeof env[k] === "undefined" || env[k] === "");
+  addResult(
+    results,
+    "Langfuse env fields",
+    missingEnv.length === 0,
+    missingEnv.length ? `missing: ${missingEnv.join(", ")}` : "OK",
+    "Run setup again so settings.json contains the Langfuse environment fields."
+  );
+
+  const userEnvOk = !!(
+    env?.CC_LANGFUSE_USER_ID ||
+    env?.CLAUDE_USER_ID ||
+    env?.CC_USER_ID ||
+    env?.LANGFUSE_USER_ID
+  );
+  addResult(results, "user id env field", userEnvOk, userEnvOk ? "OK" : "missing", "Run setup again and enter a valid employee id.");
+
+  const hook = findLangfuseHook(settings);
+  addResult(results, "hooks.Stop contains Langfuse", !!hook, hook ? "OK" : "missing", "Run setup again to register the Stop hook.");
+
+  const execFormOk = hookUsesExecForm(hook);
+  addResult(
+    results,
+    "hook command form",
+    process.platform === "win32" ? execFormOk : !!hook,
+    execFormOk ? "exec form command + args" : hook ? "legacy shell-form command" : "missing",
+    process.platform === "win32"
+      ? "Run setup again. Windows should use command plus args so paths are not parsed by Git Bash/PowerShell."
+      : "Run setup again to refresh the hook command."
+  );
+
+  if (hook) {
+    addResult(
+      results,
+      "hook python executable",
+      pathExists(hook.command),
+      hook.command || "missing",
+      "Run setup again to recreate the Python venv and write an absolute python path."
+    );
+    const hookScriptPath = execFormOk ? String(hook.args.find((arg) => String(arg).includes("langfuse_hook.py")) || "") : pyPath;
+    addResult(
+      results,
+      "hook args script",
+      pathExists(hookScriptPath),
+      hookScriptPath || "missing",
+      "Run setup again so the hook args point at langfuse_hook.py."
+    );
+    const importCheck = checkPythonLangfuseImport(hook.command);
+    addResult(
+      results,
+      "python package langfuse",
+      importCheck.ok,
+      importCheck.detail,
+      `Run: ${hook.command} -m pip install -U langfuse`
+    );
+  }
+
+  addResult(results, "hook log path", true, logPath);
+
+  const pad = (s, n) => (s.length >= n ? s : s + " ".repeat(n - s.length));
+  const w = Math.max(...results.map((r) => r.item.length)) + 2;
+  const failed = [];
+  for (const r of results) {
+    const status = r.ok ? "OK " : "BAD";
+    console.log(`${status}  ${pad(r.item, w)} ${r.detail}`);
+    if (!r.ok) failed.push(r);
+  }
+
+  if (failed.length) {
+    console.log("");
+    console.log("Fix suggestions:");
+    for (const r of failed) {
+      if (r.fix) console.log(`- ${r.item}: ${r.fix}`);
+    }
+  }
+
+  process.exit(failed.length ? 2 : 0);
+}
+
+main();

package/scripts/langfuse-setup.mjs

@@ -177,11 +177,13 @@ async function main() {
   }
   assertValidUserId(userId);
 
-  const langfuseHost =
-    args.langfuseHost ||
-    args.host ||
-    process.env.LANGFUSE_HOST ||
-    "http://120.46.221.227:3000";
+  const langfuseHost =
+    args.langfuseBaseUrl ||
+    args.langfuseHost ||
+    args.host ||
+    process.env.LANGFUSE_BASEURL ||
+    process.env.LANGFUSE_HOST ||
+    "http://120.46.221.227:3000";
 
   const publicKey =
     args.publicKey || process.env.LANGFUSE_PUBLIC_KEY || "pk-lf-da0c90a7-6e93-4eb7-bb86-c1047c8d187d";
@@ -246,10 +248,8 @@ async function main() {
   const settingsPath = path.join(claudeDir, "settings.json");
   const existing = readJsonIfExists(settingsPath) ?? {};
 
-  const pyCmdPath = normalizeWinPathForClaude(pyPath);
-  const pyExePath = normalizeWinPathForClaude(hookPython);
-  const desired = {
-    env: {
+  const desired = {
+    env: {
       TRACE_TO_LANGFUSE: "true",
       LANGFUSE_PUBLIC_KEY: publicKey,
       LANGFUSE_SECRET_KEY: secretKey,
@@ -265,12 +265,13 @@ async function main() {
       Stop: [
         {
           hooks: [
-            {
-              type: "command",
-              command: `${quoteCommandArg(pyExePath)} ${quoteCommandArg(pyCmdPath)}`
-            }
-          ]
-        }
+            {
+              type: "command",
+              command: hookPython,
+              args: [pyPath]
+            }
+          ]
+        }
       ]
     }
   };

package/scripts/real-self-verify.mjs

@@ -0,0 +1,414 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { resolveOpencodeCli } from "./resolve-opencode-cli.mjs";
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf8"));
+
+const DEFAULT_LANGFUSE_BASE_URL = "http://120.46.221.227:3000";
+const DEFAULT_LANGFUSE_PUBLIC_KEY = "pk-lf-da0c90a7-6e93-4eb7-bb86-c1047c8d187d";
+const DEFAULT_LANGFUSE_SECRET_KEY = "sk-lf-0269b85d-bfdc-442c-bfa3-e737954e3315";
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const raw = argv[i];
+    if (!raw.startsWith("--")) {
+      args._.push(raw);
+      continue;
+    }
+    const eq = raw.indexOf("=");
+    if (eq !== -1) {
+      args[raw.slice(2, eq)] = raw.slice(eq + 1);
+      continue;
+    }
+    const key = raw.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith("--")) {
+      args[key] = next;
+      i += 1;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`${packageJson.name} real self verification`);
+  console.log("");
+  console.log("Usage:");
+  console.log("  npm run self:verify -- --targets=opencode --userId=h00613222");
+  console.log("  node scripts/real-self-verify.mjs --targets=claude,opencode,codex --userId=h00613222");
+  console.log("");
+  console.log("What it does:");
+  console.log("  1. Runs the real setup command for each target unless --skip-install is set.");
+  console.log("  2. Starts the actual Claude/OpenCode/Codex CLI with a unique validation marker.");
+  console.log("  3. Polls Langfuse Public API until that marker appears in traces/observations.");
+  console.log("");
+  console.log("Options:");
+  console.log("  --targets=opencode,claude,codex");
+  console.log("  --userId=<id>                    Required unless LANGFUSE_USER_ID is set.");
+  console.log("  --langfuseBaseUrl=<url>           Defaults to package default or LANGFUSE_BASEURL.");
+  console.log("  --publicKey=<key>                 Defaults to package default or LANGFUSE_PUBLIC_KEY.");
+  console.log("  --secretKey=<key>                 Defaults to package default or LANGFUSE_SECRET_KEY.");
+  console.log("  --marker=<text>                   Override generated validation marker.");
+  console.log("  --timeoutMs=180000                Langfuse polling timeout.");
+  console.log("  --triggerTimeoutMs=300000         Per CLI invocation timeout.");
+  console.log("  --skip-install                    Do not run setup first.");
+  console.log("  --skip-trigger                    Only install and poll for a pre-existing marker.");
+  console.log("  --allow-trigger-failure           Poll Langfuse even if the CLI command exits non-zero.");
+  console.log("  --opencodeCmd=<path>              Override OpenCode CLI path.");
+  console.log("  --claudeCmd=<path>                Override Claude CLI path.");
+  console.log("  --codexCmd=<path>                 Override Codex CLI path.");
+  console.log("  --prompt=<text>                   Override the validation prompt.");
+}
+
+function splitTargets(raw) {
+  const value = String(raw || "opencode").trim();
+  const out = value
+    .split(/[, ]+/)
+    .map((x) => x.trim().toLowerCase())
+    .filter(Boolean);
+  const allowed = new Set(["claude", "opencode", "codex"]);
+  for (const target of out) {
+    if (!allowed.has(target)) throw new Error(`Unsupported target: ${target}`);
+  }
+  return out.length ? [...new Set(out)] : ["opencode"];
+}
+
+function makeMarker() {
+  return `real-self-verify-${packageJson.name}-${Date.now()}-${crypto.randomBytes(4).toString("hex")}`;
+}
+
+function shellNeeded(command) {
+  return process.platform === "win32" && /\.(cmd|bat)$/i.test(command);
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd || rootDir,
+    env: { ...process.env, ...(options.env || {}) },
+    encoding: "utf8",
+    stdio: options.stdio || "pipe",
+    timeout: options.timeoutMs,
+    windowsHide: true,
+    shell: shellNeeded(command),
+  });
+  return {
+    command,
+    args,
+    status: result.status ?? (result.error ? 1 : 0),
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+    error: result.error,
+    signal: result.signal,
+  };
+}
+
+function printRunResult(label, result) {
+  const status = result.status === 0 ? "OK" : "FAIL";
+  console.log(`[${status}] ${label}: ${result.command} ${result.args.join(" ")}`);
+  const text = `${result.stdout}\n${result.stderr}`.trim();
+  if (text) {
+    const clipped = text.length > 5000 ? `${text.slice(0, 5000)}\n...<clipped>` : text;
+    console.log(clipped);
+  }
+}
+
+function findOnPath(names) {
+  for (const name of names) {
+    const probe = run(name, ["--version"], { timeoutMs: 15000 });
+    if (probe.status === 0) return name;
+  }
+  return "";
+}
+
+function configFromArgs(args) {
+  return {
+    baseUrl:
+      String(args.langfuseBaseUrl || args.langfuseHost || args.host || process.env.LANGFUSE_BASEURL || process.env.LANGFUSE_HOST || DEFAULT_LANGFUSE_BASE_URL),
+    publicKey: String(args.publicKey || process.env.LANGFUSE_PUBLIC_KEY || DEFAULT_LANGFUSE_PUBLIC_KEY),
+    secretKey: String(args.secretKey || process.env.LANGFUSE_SECRET_KEY || DEFAULT_LANGFUSE_SECRET_KEY),
+    userId: String(args.userId || args.userid || process.env.LANGFUSE_USER_ID || process.env.CC_USER_ID || "").trim(),
+  };
+}
+
+function setupTarget(target, config, args) {
+  const cli = path.join(rootDir, "bin", "cli.js");
+  const setupArgs = [
+    cli,
+    "setup",
+    target,
+    "--yes",
+    `--userId=${config.userId}`,
+    `--langfuseBaseUrl=${config.baseUrl}`,
+    `--publicKey=${config.publicKey}`,
+    `--secretKey=${config.secretKey}`,
+  ];
+  if (args.npmRegistry) setupArgs.push(`--npmRegistry=${args.npmRegistry}`);
+  if (args.pipIndexUrl) setupArgs.push(`--pipIndexUrl=${args.pipIndexUrl}`);
+  if (args["skip-plugin-install"]) setupArgs.push("--skip-plugin-install");
+  if (args["no-set-env"]) setupArgs.push("--no-set-env");
+  if (args.cmd) setupArgs.push(`--cmd=${args.cmd}`);
+  const result = run(process.execPath, setupArgs, { stdio: "inherit", timeoutMs: Number(args.setupTimeoutMs || 600000) });
+  return result.status;
+}
+
+function validationPrompt(marker, target, customPrompt) {
+  if (customPrompt) return String(customPrompt).replaceAll("{marker}", marker).replaceAll("{target}", target);
+  return [
+    `This is an automated real self-verification run for ${packageJson.name}.`,
+    `Validation marker: ${marker}`,
+    "Reply with the validation marker exactly once and do not run tools.",
+  ].join("\n");
+}
+
+function triggerClaude(prompt, args, env) {
+  const cmd = String(args.claudeCmd || findOnPath(process.platform === "win32" ? ["claude.cmd", "claude"] : ["claude"]));
+  if (!cmd) return { status: 127, stdout: "", stderr: "Claude CLI not found. Set --claudeCmd=<path>.", command: "claude", args: [] };
+  const candidates = [
+    ["-p", prompt],
+    ["--print", prompt],
+  ];
+  let last = null;
+  for (const candidate of candidates) {
+    last = run(cmd, candidate, { env, timeoutMs: Number(args.triggerTimeoutMs || 300000) });
+    if (last.status === 0) return last;
+  }
+  return last;
+}
+
+function triggerOpenCode(prompt, args, env) {
+  const cmd = resolveOpencodeCli(args.opencodeCmd || args.cmd);
+  if (!cmd) return { status: 127, stdout: "", stderr: "OpenCode CLI not found. Set --opencodeCmd=<path>.", command: "opencode", args: [] };
+  const candidates = [
+    ["run", prompt],
+    ["run", "--print", prompt],
+    [prompt],
+  ];
+  let last = null;
+  for (const candidate of candidates) {
+    last = run(cmd, candidate, { env, timeoutMs: Number(args.triggerTimeoutMs || 300000) });
+    if (last.status === 0) return last;
+  }
+  return last;
+}
+
+function triggerCodex(prompt, args, env) {
+  const cmd = String(args.codexCmd || findOnPath(process.platform === "win32" ? ["codex.cmd", "codex"] : ["codex"]));
+  if (!cmd) return { status: 127, stdout: "", stderr: "Codex CLI not found. Set --codexCmd=<path>.", command: "codex", args: [] };
+  const candidates = [
+    ["exec", prompt],
+    ["exec", "--skip-git-repo-check", prompt],
+  ];
+  let last = null;
+  for (const candidate of candidates) {
+    last = run(cmd, candidate, { env, timeoutMs: Number(args.triggerTimeoutMs || 300000) });
+    if (last.status === 0) return last;
+  }
+  return last;
+}
+
+function apiBase(baseUrl) {
+  const trimmed = String(baseUrl || "").replace(/\/+$/, "");
+  return trimmed.endsWith("/api/public") ? trimmed : `${trimmed}/api/public`;
+}
+
+function basicAuth(publicKey, secretKey) {
+  return `Basic ${Buffer.from(`${publicKey}:${secretKey}`, "utf8").toString("base64")}`;
+}
+
+async function langfuseGet(config, pathname, params = {}) {
+  const url = new URL(`${apiBase(config.baseUrl)}${pathname}`);
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && String(value) !== "") url.searchParams.set(key, String(value));
+  }
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/json",
+      authorization: basicAuth(config.publicKey, config.secretKey),
+    },
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    const error = new Error(`Langfuse API ${response.status} ${response.statusText}: ${body.slice(0, 500)}`);
+    error.status = response.status;
+    throw error;
+  }
+  return await response.json();
+}
+
+function dataArray(value) {
+  if (Array.isArray(value)) return value;
+  if (Array.isArray(value?.data)) return value.data;
+  if (Array.isArray(value?.items)) return value.items;
+  return [];
+}
+
+function containsMarker(value, marker) {
+  try {
+    return JSON.stringify(value).includes(marker);
+  } catch {
+    return false;
+  }
+}
+
+function idOf(value) {
+  return value?.id || value?.traceId || value?.trace_id || "";
+}
+
+async function findLangfuseMarker(config, marker, { since, target }) {
+  const baseParams = {
+    limit: 100,
+    fromTimestamp: since.toISOString(),
+  };
+  const traceQueries = [
+    { ...baseParams, userId: config.userId },
+    baseParams,
+  ];
+
+  for (const params of traceQueries) {
+    let traces;
+    try {
+      traces = await langfuseGet(config, "/traces", params);
+    } catch (error) {
+      if (error.status === 404) continue;
+      throw error;
+    }
+    for (const trace of dataArray(traces)) {
+      if (containsMarker(trace, marker)) return { kind: "trace-list", target, id: idOf(trace), item: trace };
+    }
+    for (const trace of dataArray(traces).slice(0, 25)) {
+      const id = idOf(trace);
+      if (!id) continue;
+      try {
+        const detail = await langfuseGet(config, `/traces/${encodeURIComponent(id)}`);
+        if (containsMarker(detail, marker)) return { kind: "trace-detail", target, id, item: detail };
+      } catch (error) {
+        if (error.status !== 404) throw error;
+      }
+    }
+  }
+
+  const observationQueries = [
+    ["/observations", { ...baseParams, userId: config.userId }],
+    ["/observations", baseParams],
+    ["/v2/observations", { ...baseParams, fields: "core,basic,usage", userId: config.userId }],
+    ["/v2/observations", { ...baseParams, fields: "core,basic,usage" }],
+  ];
+  for (const [pathname, params] of observationQueries) {
+    try {
+      const observations = await langfuseGet(config, pathname, params);
+      for (const observation of dataArray(observations)) {
+        if (containsMarker(observation, marker)) return { kind: pathname, target, id: idOf(observation), item: observation };
+      }
+    } catch (error) {
+      if (error.status === 404 || error.status === 400) continue;
+      throw error;
+    }
+  }
+
+  return null;
+}
+
+async function pollLangfuse(config, marker, options) {
+  const timeoutMs = Number(options.timeoutMs || 180000);
+  const pollMs = Number(options.pollMs || 5000);
+  const deadline = Date.now() + timeoutMs;
+  const since = options.since || new Date(Date.now() - 10 * 60 * 1000);
+  let lastError = null;
+
+  while (Date.now() <= deadline) {
+    try {
+      const found = await findLangfuseMarker(config, marker, { since, target: options.target });
+      if (found) return found;
+      console.log(`[WAIT] Langfuse has not returned marker yet (${marker}).`);
+    } catch (error) {
+      lastError = error;
+      console.log(`[WAIT] Langfuse query failed: ${error.message}`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+
+  if (lastError) throw new Error(`Timed out waiting for marker. Last Langfuse error: ${lastError.message}`);
+  throw new Error(`Timed out waiting for marker in Langfuse: ${marker}`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || args.h) {
+    printHelp();
+    return 0;
+  }
+
+  const config = configFromArgs(args);
+  if (!config.userId) throw new Error("Missing --userId or LANGFUSE_USER_ID. Real verification needs a user id to install and filter traces.");
+  const targets = splitTargets(args.targets || args.target || args._[0]);
+  const marker = String(args.marker || makeMarker());
+  const since = new Date();
+  const results = [];
+
+  console.log(`[INFO] Package: ${packageJson.name}@${packageJson.version}`);
+  console.log(`[INFO] Targets: ${targets.join(", ")}`);
+  console.log(`[INFO] Langfuse: ${config.baseUrl}`);
+  console.log(`[INFO] User ID: ${config.userId}`);
+  console.log(`[INFO] Marker: ${marker}`);
+  console.log("");
+
+  for (const target of targets) {
+    if (!args["skip-install"]) {
+      const code = setupTarget(target, config, args);
+      if (code !== 0) throw new Error(`Setup failed for ${target} with exit code ${code}.`);
+    }
+
+    const prompt = validationPrompt(marker, target, args.prompt);
+    const env = {
+      TRACE_TO_LANGFUSE: "true",
+      LANGFUSE_PUBLIC_KEY: config.publicKey,
+      LANGFUSE_SECRET_KEY: config.secretKey,
+      LANGFUSE_BASEURL: config.baseUrl,
+      LANGFUSE_HOST: config.baseUrl,
+      LANGFUSE_USER_ID: config.userId,
+      CC_USER_ID: config.userId,
+      CC_LANGFUSE_USER_ID: config.userId,
+      CODEX_LANGFUSE_USER_ID: config.userId,
+      OHAI_REAL_SELF_VERIFY_MARKER: marker,
+      OHAI_REAL_SELF_VERIFY_TARGET: target,
+    };
+
+    if (!args["skip-trigger"]) {
+      const trigger =
+        target === "claude"
+          ? triggerClaude(prompt, args, env)
+          : target === "opencode"
+            ? triggerOpenCode(prompt, args, env)
+            : triggerCodex(prompt, args, env);
+      printRunResult(`${target} trigger`, trigger);
+      if (trigger.status !== 0 && !args["allow-trigger-failure"]) {
+        throw new Error(`${target} trigger failed before Langfuse polling. Use --allow-trigger-failure to poll anyway.`);
+      }
+    }
+
+    const found = await pollLangfuse(config, marker, { ...args, since, target });
+    console.log(`[OK] Langfuse marker found for ${target}: ${found.kind} ${found.id || ""}`.trim());
+    results.push({ target, marker, langfuse: { kind: found.kind, id: found.id || "" } });
+  }
+
+  console.log("");
+  console.log(JSON.stringify({ ok: true, package: packageJson.name, marker, results }, null, 2));
+  return 0;
+}
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error) => {
+    console.error(`[FAIL] ${error?.message || String(error)}`);
+    process.exitCode = 1;
+  });