deskbuddy 0.0.1 → 0.2.0-beta.0

package/dist/hook.cjs

@@ -0,0 +1,922 @@
+#!/usr/bin/env node
+'use strict'
+// 🔴 这个文件在用户【每次工具调用】时都会被执行一次。三条铁律：
+//    ① 只 require Node 内置模块 —— 它不进 bundler，构建时原样 cp 成 dist/hook.cjs，
+//       再由 deskbuddy enable 复制到 ~/.deskbuddy/hook.cjs。
+//       扩展名必须是 .cjs：本包是 "type": "module"，叫 .js 会被当成 ESM 直接崩。
+//       require 任何 npm 包都会拖慢用户的 agent。
+//    ② 永不阻塞 —— 上报 2 秒超时、fire-and-forget，失败就丢，下次跃迁自然补上。
+//    ③ 任何异常都吞掉并 exit(0) —— hook 报错会直接打断用户的 AI 会话。
+//
+// ⚠️ 本文件与 src/core/{config,state,process,snapshot,registry,title}.ts 是【同一套逻辑的两份实现】：
+//    那边给 CLI 用（可以有依赖），这边给 hook 用（必须零依赖）。改一边记得改另一边，
+//    src/hook/hook.test.ts 里有对齐用例会挡住漂移。
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const http = require('node:http')
+const https = require('node:https')
+const crypto = require('node:crypto')
+const { execFileSync } = require('node:child_process')
+
+const DEFAULT_API_BASE = process.env.DESKBUDDY_API_BASE || 'https://api.shifengintelli.com'
+const KEEPALIVE_MS = 2 * 60 * 1000
+const MAX_SESSIONS = 20
+/** 状态文件里保留的最近事件条数，与 src/core/state.ts 的 RECENT_MAX 一致 */
+const RECENT_MAX = 8
+const REPORT_TIMEOUT_MS = 2000
+/** ServiceApi 版本，不是包路径里的 v2 */
+const GATEWAY_VERSION = '1.0'
+const APP_ID = process.env.DESKBUDDY_APPID || 'deskbuddy-cli'
+/**
+ * ⚠️ 【公开常量，不是密钥】。客户端是 npm 公开发布的，任何人解包就能看到它。
+ * jumpSign=false 下签名的全部作用只是换取 180 秒防重放窗口，外加让这个 appid 不跳过
+ * 框架的 userAuth 闸门。它保护不了任何东西 —— 真正的防线是服务端的 clientId ↔ userId
+ * 绑定关系，而那个绑定建立在 App 的已登录态上，不在 CLI 里。
+ */
+const APP_SECRET = process.env.DESKBUDDY_APPSECRET || '3aeb6e0afc144e188dd3ede5c7865643'
+/**
+ * 🔴 服务名 = 服务端 handler 的全限定类名小写（@ServiceApi.value() 为空时回落到类名小写）。
+ * 服务端类改名 / 挪包，这里会静默失效，表现是 NOT_SUPPORT。与 src/core/api.ts 里那份必须一致。
+ */
+const SERVICES = {
+  authCode: 'com.shifeng.api.service.api.v2.deskbuddy.deskbuddyauthcodeapi',
+  authToken: 'com.shifeng.api.service.api.v2.deskbuddy.deskbuddyauthtokenapi',
+  sessionReport: 'com.shifeng.api.service.api.v2.deskbuddy.deskbuddysessionreportapi',
+  toolRegistry: 'com.shifeng.api.service.api.v2.deskbuddy.deskbuddytoolregistryapi',
+  confirmAuth: 'com.shifeng.api.service.api.v2.deskbuddy.deskbuddyconfirmauthapi',
+}
+/**
+ * 🔴 只读 transcript 尾部这么多字节，绝不遍历整个文件。
+ * 实测最大的 transcript 有 1.47 GB，全文件遍历会把用户的 agent 卡死；
+ * 而最后一条 ai-title 实测距文件尾只有 1–31 KB。
+ */
+const TRANSCRIPT_TAIL_BYTES = 64 * 1024
+/** 没配 titleSources 的工具按这条链处理 */
+const DEFAULT_TITLE_SOURCES = ['git-branch', 'project']
+/** cwd 不是仓库根时向上找 .git 的层数上限 */
+const GIT_LOOKUP_MAX_UP = 5
+
+/** 服务端拉不到、本地缓存也没有时的最小兜底：至少还能认出"在跑 / 结束"，不至于整个瞎掉。 */
+const FALLBACK_REGISTRY = {
+  version: 'builtin',
+  tools: {
+    claude_code: {
+      format: 'cc-hook',
+      processNames: ['claude'],
+      titleSources: ['cc-ai-title', 'git-branch', 'project'],
+      events: {
+        UserPromptSubmit: 'watch',
+        PreToolUse: 'watch',
+        PostToolUse: 'watch',
+        // 工具跑失败时 Claude Code 发这个而不是 PostToolUse；窗口待批准撤卡也要认它
+        PostToolUseFailure: 'watch',
+        Stop: 'done',
+        // 窗口里弹授权框的那一刻就是待确认（S10），不等之后那条权限通知
+        PermissionRequest: 'ask_approval',
+      },
+      lifecycle: { SessionStart: 'ignore', SessionEnd: 'remove' },
+    },
+    codex: {
+      format: 'codex-toml',
+      processNames: ['codex'],
+      // codex-thread-name 是机会主义的一级：session_index.jsonl 里的 thread_name
+      // 原生只有 /rename 手动设，多数用户是空的，取不到就往下回落
+      titleSources: ['codex-thread-name', 'git-branch', 'project'],
+      events: {
+        UserPromptSubmit: 'watch',
+        PreToolUse: 'watch',
+        PostToolUse: 'watch',
+        Stop: 'done',
+        PermissionRequest: 'ask_approval',
+      },
+      lifecycle: { SessionStart: 'ignore', SessionEnd: 'remove' },
+    },
+    workbuddy: {
+      format: 'cc-hook',
+      processNames: ['WorkBuddy'],
+      titleSources: ['git-branch', 'project'],
+      events: {
+        UserPromptSubmit: 'watch',
+        PreToolUse: 'watch',
+        PostToolUse: 'watch',
+        Stop: 'done',
+        PermissionRequest: 'ask_approval',
+      },
+      lifecycle: { SessionStart: 'ignore', SessionEnd: 'remove' },
+    },
+    qoder: {
+      format: 'cc-hook',
+      processNames: ['Qoder CN'],
+      titleSources: ['git-branch', 'project'],
+      events: {
+        UserPromptSubmit: 'watch',
+        PreToolUse: 'watch',
+        PostToolUse: 'watch',
+        Stop: 'done',
+        PermissionRequest: 'ask_approval',
+      },
+      lifecycle: { SessionStart: 'ignore', SessionEnd: 'remove' },
+    },
+    opencode: {
+      format: 'oc-plugin',
+      processNames: ['opencode'],
+      // opencode 自带的会话标题是模型对提问的摘要，违反隐私约束（spec §6.4），不用
+      titleSources: ['git-branch', 'project'],
+      events: {
+        UserPromptSubmit: 'watch',
+        PreToolUse: 'watch',
+        PostToolUse: 'watch',
+        Stop: 'done',
+        PermissionRequest: 'ask_approval',
+      },
+      lifecycle: { SessionEnd: 'remove' },
+    },
+  },
+}
+
+// ---------- 配置 ----------
+
+function deskbuddyHome() {
+  return process.env.DESKBUDDY_HOME || path.join(os.homedir(), '.deskbuddy')
+}
+
+function loadConfig() {
+  const fallback = { clientId: '', hostName: os.hostname(), enabledTools: [], apiBase: DEFAULT_API_BASE }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(deskbuddyHome(), 'config.json'), 'utf8'))
+    return {
+      clientId: parsed.clientId || fallback.clientId,
+      hostName: parsed.hostName || fallback.hostName,
+      enabledTools: Array.isArray(parsed.enabledTools) ? parsed.enabledTools : [],
+      apiBase: process.env.DESKBUDDY_API_BASE || parsed.apiBase || DEFAULT_API_BASE,
+    }
+  } catch (e) {
+    return fallback
+  }
+}
+
+// ---------- 映射表 ----------
+
+/** hook 每次执行都会调用，只读本地缓存 —— 绝不能在 hook 里发网络请求拉配置。 */
+function loadRegistry() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(deskbuddyHome(), 'tool-registry.json'), 'utf8'))
+  } catch (e) {
+    return FALLBACK_REGISTRY
+  }
+}
+
+function mapEvent(registry, tool, event, payload) {
+  const t = registry && registry.tools ? registry.tools[tool] : null
+  if (!t) return 'ignore'
+  const lifecycle = t.lifecycle ? t.lifecycle[event] : undefined
+  if (lifecycle) return lifecycle // ignore / remove
+  const conds = t.conditionalEvents ? t.conditionalEvents[event] : undefined
+  if (Array.isArray(conds)) {
+    // 🔴 Claude Code 的 Notification 有两类：权限确认 → ask_approval；
+    //    闲置等待输入 → done。把闲置也报成待确认，屏上会全是"待确认"，提醒直接失效。
+    const text = String((payload && (payload.message ?? payload.notification_type)) ?? '')
+    for (const c of conds) {
+      try {
+        if (new RegExp(c.match, 'i').test(text)) return c.state
+      } catch (e) {
+        /* 映射表里写坏的正则不能连累整个 hook */
+      }
+    }
+  }
+  return (t.events && t.events[event]) || 'ignore'
+}
+
+function agentNames(registry, tool) {
+  const t = registry && registry.tools ? registry.tools[tool] : null
+  if (t && Array.isArray(t.processNames) && t.processNames.length > 0) return t.processNames
+  const f = FALLBACK_REGISTRY.tools[tool]
+  return f ? f.processNames : []
+}
+
+/** 会话标题回落链。顺序由服务端映射表决定，客户端不写死。 */
+function titleSources(registry, tool) {
+  const t = registry && registry.tools ? registry.tools[tool] : null
+  if (t && Array.isArray(t.titleSources) && t.titleSources.length > 0) return t.titleSources
+  const f = FALLBACK_REGISTRY.tools[tool]
+  return f && f.titleSources && f.titleSources.length > 0 ? f.titleSources : DEFAULT_TITLE_SOURCES
+}
+
+// ---------- 会话标题 ----------
+
+function codexHome() {
+  return process.env.CODEX_HOME || path.join(os.homedir(), '.codex')
+}
+
+/** 读文件尾部 N 字节并按行切开。读不了就返回空数组，绝不抛。 */
+function readTailLines(file, bytes) {
+  let fd
+  try {
+    const size = fs.statSync(file).size
+    if (size <= 0) return []
+    const len = Math.min(size, bytes)
+    const buf = Buffer.alloc(len)
+    fd = fs.openSync(file, 'r')
+    fs.readSync(fd, buf, 0, len, size - len)
+    return buf.toString('utf8').split('\n')
+  } catch (e) {
+    return []
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd)
+      } catch (e) {
+        /* ignore */
+      }
+    }
+  }
+}
+
+/** Claude Code 自己写进 transcript 的会话标题（{"type":"ai-title","aiTitle":"…"}）。 */
+function readAiTitle(transcriptPath) {
+  if (!transcriptPath) return null
+  const lines = readTailLines(transcriptPath, TRANSCRIPT_TAIL_BYTES)
+  // 从后往前找第一条 ai-title
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]
+    if (line.indexOf('"ai-title"') === -1) continue
+    try {
+      const obj = JSON.parse(line)
+      if (obj && obj.type === 'ai-title') {
+        const title = String(obj.aiTitle == null ? '' : obj.aiTitle).trim()
+        if (title !== '') return title
+      }
+    } catch (e) {
+      /* 尾部窗口切出来的半行，跳过 */
+    }
+  }
+  return null
+}
+
+/**
+ * Codex 的会话名：~/.codex/session_index.jsonl 里 {"id":…,"thread_name":…}。
+ * ⚠️ 机会主义的一级——原生只有 /rename 手动设，普通用户这里多半是空的。
+ */
+function readCodexThreadName(sessionId, home) {
+  if (!sessionId) return null
+  const indexPath = path.join(home || codexHome(), 'session_index.jsonl')
+  const lines = readTailLines(indexPath, TRANSCRIPT_TAIL_BYTES)
+  // 从后往前找：同一个会话可能被改过多次名，最后一条才是最新的
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]
+    if (line.indexOf(sessionId) === -1) continue
+    try {
+      const obj = JSON.parse(line)
+      if (obj && obj.id === sessionId) {
+        const name = String(obj.thread_name == null ? '' : obj.thread_name).trim()
+        if (name !== '') return name
+      }
+    } catch (e) {
+      /* 尾部窗口切出来的半行，跳过 */
+    }
+  }
+  return null
+}
+
+/** 读一个目录下的 .git/HEAD 内容。不是仓库返回 null（worktree 时跟一跳）。 */
+function readGitHead(dir) {
+  try {
+    const dotGit = path.join(dir, '.git')
+    let headPath = path.join(dotGit, 'HEAD')
+    if (!fs.statSync(dotGit).isDirectory()) {
+      // worktree / submodule：.git 是个文件，内容是 "gitdir: <路径>"
+      const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dotGit, 'utf8'))
+      if (!m) return null
+      const gitdir = m[1].trim()
+      headPath = path.join(path.isAbsolute(gitdir) ? gitdir : path.join(dir, gitdir), 'HEAD')
+    }
+    return fs.readFileSync(headPath, 'utf8').trim()
+  } catch (e) {
+    return null
+  }
+}
+
+/** 当前分支名。cwd 可能是仓库子目录，向上找最多 GIT_LOOKUP_MAX_UP 层；detached HEAD 返回 null。 */
+function readGitBranch(cwd, maxUp) {
+  if (!cwd) return null
+  const limit = maxUp === undefined ? GIT_LOOKUP_MAX_UP : maxUp
+  let dir = cwd
+  for (let up = 0; up <= limit; up++) {
+    const head = readGitHead(dir)
+    if (head !== null) {
+      const ref = /^ref:\s*refs\/heads\/(.+)$/.exec(head)
+      if (!ref) return null // detached HEAD 是一串裸 sha，没必要上屏
+      return ref[1].trim() || null
+    }
+    const parent = path.dirname(dir)
+    if (parent === dir) break // 到根了
+    dir = parent
+  }
+  return null
+}
+
+/** 按 registry 给的顺序逐级回落。所有来源都不碰 prompt 原文。 */
+function resolveTitle(sources, ctx) {
+  const list = sources || []
+  for (const source of list) {
+    let value = null
+    if (source === 'cc-ai-title') value = readAiTitle(ctx.transcriptPath)
+    else if (source === 'codex-thread-name') value = readCodexThreadName(ctx.sessionId, ctx.codexHome)
+    else if (source === 'git-branch') value = readGitBranch(ctx.cwd)
+    else if (source === 'project') value = path.basename(ctx.cwd || '') || null
+    // 不认识的来源直接跳过：新来源应该先发版再进 registry
+    if (value) return value
+  }
+  return ''
+}
+
+// ---------- 进程探测 ----------
+
+function processName(pid) {
+  try {
+    // macOS / Linux 通用。Windows 需要 tasklist，首期不支持
+    const out = execFileSync('ps', ['-p', String(pid), '-o', 'comm='], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    const name = out.trim()
+    return name === '' ? null : name
+  } catch (e) {
+    return null
+  }
+}
+
+function parentPid(pid) {
+  try {
+    const out = execFileSync('ps', ['-p', String(pid), '-o', 'ppid='], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    const ppid = Number(out.trim())
+    return Number.isFinite(ppid) && ppid > 1 ? ppid : null
+  } catch (e) {
+    return null
+  }
+}
+
+/** 🔴 expectName 防 pid 复用：只看 pid 存在，会把已关闭的窗口误判成还活着。 */
+function isAlive(pid, expectName) {
+  if (!Number.isFinite(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+  } catch (e) {
+    return false
+  }
+  if (!expectName) return true
+  const name = processName(pid)
+  return name != null && name.toLowerCase().includes(String(expectName).toLowerCase())
+}
+
+/** hook 的直接父进程可能是 shell，agent 在更上层，所以要逐级往上找。 */
+function resolveAgentPid(startPid, names, maxDepth) {
+  const wanted = (names || []).map((n) => String(n).toLowerCase()).filter((n) => n !== '')
+  if (wanted.length === 0) return null
+  const depthLimit = maxDepth || 8
+  let pid = startPid
+  for (let depth = 0; depth < depthLimit && pid != null; depth++) {
+    const name = processName(pid)
+    if (name && wanted.some((w) => name.toLowerCase().includes(w))) return pid
+    pid = parentPid(pid)
+  }
+  return null
+}
+
+// ---------- 会话状态 ----------
+
+function stateDir() {
+  return path.join(deskbuddyHome(), 'state')
+}
+
+function statePath(sessionId) {
+  // sessionId 来自 agent，是不可信输入，清洗掉路径穿越字符
+  const safe = String(sessionId).replace(/[^A-Za-z0-9_-]/g, '')
+  return path.join(stateDir(), (safe || 'unknown') + '.json')
+}
+
+function readState(sessionId) {
+  try {
+    return JSON.parse(fs.readFileSync(statePath(sessionId), 'utf8'))
+  } catch (e) {
+    return null
+  }
+}
+
+/** 原子写：先写 .tmp 再 rename，避免并发的多个 hook 读到写了一半的 JSON。 */
+function writeState(s) {
+  fs.mkdirSync(stateDir(), { recursive: true })
+  const tmp = statePath(s.sessionId) + '.tmp'
+  fs.writeFileSync(tmp, JSON.stringify(s), 'utf8')
+  fs.renameSync(tmp, statePath(s.sessionId))
+}
+
+function removeState(sessionId) {
+  try {
+    fs.rmSync(statePath(sessionId), { force: true })
+  } catch (e) {
+    /* 删不掉就算了，下次还会尝试 */
+  }
+}
+
+/**
+ * 读取某工具下所有【进程还活着】的会话，顺手清理已死的。
+ * SessionEnd 极不可靠（用户叉掉窗口时根本不触发），进程存活才是唯一硬信号。
+ */
+function readAliveStates(tool) {
+  let files
+  try {
+    files = fs.readdirSync(stateDir())
+  } catch (e) {
+    return []
+  }
+  const alive = []
+  for (const file of files) {
+    if (!file.endsWith('.json')) continue
+    let s
+    try {
+      s = JSON.parse(fs.readFileSync(path.join(stateDir(), file), 'utf8'))
+    } catch (e) {
+      try {
+        fs.rmSync(path.join(stateDir(), file), { force: true }) // 脏文件直接清掉
+      } catch (e2) {
+        /* ignore */
+      }
+      continue
+    }
+    if (!s || s.tool !== tool) continue
+    if (s.pid && !isAlive(s.pid, s.pidName)) {
+      removeState(s.sessionId) // 窗口已关：剔除并自我清理，state 目录不再无限增长
+      continue
+    }
+    alive.push(s)
+  }
+  return alive
+}
+
+// ---------- 节流与快照 ----------
+
+function shouldReport(prev, next, nowMs) {
+  if (!prev) return true
+  if (prev.state !== next.state) return true
+  // 保活：状态没跃迁也要定期报一次，否则服务端会把这台机器判成失联
+  return nowMs - (prev.lastReportAt || 0) > KEEPALIVE_MS
+}
+
+function buildSnapshot(states, tool, cfg, nowMs) {
+  const sessions = states
+    .filter((s) => s.tool === tool) // 替换粒度是 (clientId, tool)，混进别的工具会冲掉对方
+    .sort((a, b) => b.updatedAt - a.updatedAt)
+    .slice(0, MAX_SESSIONS)
+    .map((s) => ({
+      sessionId: s.sessionId,
+      title: s.title,
+      // 隐私：只带目录名，不带全路径——全路径会暴露公司目录结构与用户名
+      project: path.basename(s.project || ''),
+      state: s.state,
+      startedAt: s.startedAt,
+      updatedAt: s.updatedAt,
+      interactive: s.interactive === true,
+    }))
+  return { clientId: cfg.clientId, hostName: cfg.hostName, tool: tool, snapshotAt: nowMs, sessions: sessions }
+}
+
+// ---------- 上报 ----------
+
+/**
+ * 服务端 HelloApi.java:152：
+ *   source    = `${appid}_${appSecret}_${timestamp}_${deviceId}_${deviceName}_${nonce}_${body}`
+ *   signature = md5Hex(source)
+ * 七段用 `_` 连接，顺序不能变。
+ */
+function sign(p) {
+  const source = [p.appId, p.appSecret, p.timestamp, p.deviceId, p.deviceName, p.nonce, p.body].join('_')
+  return crypto.createHash('md5').update(source, 'utf8').digest('hex')
+}
+
+/**
+ * 网关 body。返回的就是要发出去的那个字符串 —— 拿它算签名，再原样发。
+ * 🔴 没有 group 字段；data 是【字符串】不是对象；base.encode 必须显式 "false"，
+ *    否则服务端会拿 data 去 AES 解密，直接 DATA_DECODE_FAIL。
+ */
+function buildGatewayBody(service, data, requestId) {
+  return JSON.stringify({
+    service: service,
+    version: GATEWAY_VERSION,
+    requestId: requestId || crypto.randomUUID(),
+    base: { encode: 'false' },
+    data: JSON.stringify(data == null ? {} : data),
+  })
+}
+
+/**
+ * 六个必填头（/gateway 用 @RequestHeader 声明且 required 默认 true，【缺一个就是 400】）。
+ * 🔴 签名用的必须是传进来的这个 body 字符串本身，绝不能再 stringify 一次 —— 键序可能不同。
+ * 没有 ShiFeng-Token：鉴权靠 clientId ↔ userId 绑定关系。
+ */
+function buildHeaders(cfg, body, opts) {
+  const o = opts || {}
+  const timestamp = o.timestamp || String(Date.now())
+  const nonce = o.nonce || crypto.randomBytes(8).toString('hex')
+  return {
+    'Content-Type': 'application/json;charset=UTF-8',
+    'Content-Length': String(Buffer.byteLength(body)),
+    'ShiFeng-AppId': APP_ID,
+    'ShiFeng-Timestamp': timestamp,
+    'ShiFeng-Device-ID': cfg.clientId,
+    'ShiFeng-Device-Name': cfg.hostName,
+    'ShiFeng-Nonce': nonce,
+    'ShiFeng-Signature': sign({
+      appId: APP_ID,
+      appSecret: APP_SECRET,
+      timestamp: timestamp,
+      deviceId: cfg.clientId,
+      deviceName: cfg.hostName,
+      nonce: nonce,
+      body: body,
+    }),
+  }
+}
+
+/** fire-and-forget：2 秒超时，失败静默。绝不能因为网络问题卡住用户的 agent。 */
+function postReport(cfg, payload) {
+  return new Promise((resolve) => {
+    let settled = false
+    const done = () => {
+      if (!settled) {
+        settled = true
+        resolve()
+      }
+    }
+    try {
+      const url = new URL('/gateway', cfg.apiBase)
+      const body = buildGatewayBody(SERVICES.sessionReport, payload)
+      const mod = url.protocol === 'http:' ? http : https
+      const req = mod.request(
+        {
+          protocol: url.protocol,
+          hostname: url.hostname,
+          port: url.port || undefined,
+          path: url.pathname,
+          method: 'POST',
+          headers: buildHeaders(cfg, body),
+        },
+        (res) => {
+          res.resume()
+          res.on('end', done)
+          res.on('error', done)
+        }
+      )
+      req.setTimeout(REPORT_TIMEOUT_MS, () => {
+        req.destroy()
+        done()
+      })
+      req.on('error', done)
+      req.write(body)
+      req.end()
+    } catch (e) {
+      done()
+    }
+  })
+}
+
+// ---------- 主流程 ----------
+
+function readStdin() {
+  try {
+    return JSON.parse(fs.readFileSync(0, 'utf8') || '{}')
+  } catch (e) {
+    return {}
+  }
+}
+
+/**
+ * 组装并上报该工具当前的全量快照。没授权 / 没 enable 就什么都不做。
+ * readAliveStates 会顺手做进程探测并清掉已死的会话。
+ */
+async function reportIfAuthorized(tool, nowMs) {
+  const cfg = loadConfig()
+  // clientId 为空说明还没 setup 过（服务端靠 clientId ↔ userId 绑定关系认人）：
+  // 绝不能在这里现编一个，那等于凭空造出一台没人认领的机器
+  if (!cfg.clientId || cfg.enabledTools.indexOf(tool) === -1) return
+  await postReport(cfg, buildSnapshot(readAliveStates(tool), tool, cfg, nowMs))
+}
+
+/**
+ * 工具调用指纹前 16 位，与 src/daemon/gate/approvals.ts 的 fingerprint 同算法。
+ * daemon 靠它认出"跑完的正是设备上等着的那一步"，并行的同名工具不会误撤卡（S10 评审 #2）
+ */
+function toolFingerprint(toolName, toolInput) {
+  let input = ''
+  try {
+    input = JSON.stringify(toolInput === undefined ? null : toolInput)
+  } catch (e) {
+    input = String(toolInput)
+  }
+  return crypto.createHash('sha256').update(toolName).update('\0').update(input).digest('hex').slice(0, 16)
+}
+
+/**
+ * 这个智能体进程是不是【交互窗口】（二期 P1）。参数里有 -p / --print / stream-json / exec 的是
+ * 脚本、SDK 或 daemon 起的远程任务；桌面 App 与终端里的 TUI 是窗口。与 gate.cjs 的 isInteractiveClaude 同一判据。
+ * 🔴 判不出来按 false：false 只意味着"不挡远程指令"，与改动前的行为一致
+ */
+function isInteractiveArgs(args) {
+  const all = String(args || '').trim().split(/\s+/)
+  const tokens = all.slice(1)
+  if (tokens.length === 0) return true
+  // exec 只认 Codex 的子命令位置：`claude "exec the tests"` 这种带提示词启动的窗口不能误判（评审）
+  if (tokens[0] === 'exec' && /codex/i.test(path.basename(all[0]))) return false
+  // opencode 的非交互是 `opencode run …`（二期 P9）；TUI 是 `opencode [目录]`
+  if (tokens[0] === 'run' && /opencode/i.test(path.basename(all[0]))) return false
+  return !tokens.some(
+    (t) =>
+      t === '--print' ||
+      t === 'stream-json' ||
+      t.startsWith('--output-format=stream') ||
+      /^-[a-zA-Z]*p[a-zA-Z]*$/.test(t)
+  )
+}
+
+/** 只看进程在不在（kill 0），不查进程名：每次事件都要调，ps 太贵 */
+function pidExists(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return false
+  }
+}
+
+function detectInteractive(pid) {
+  if (!pid) return false
+  try {
+    const args = execFileSync('ps', ['-ww', '-o', 'args=', '-p', String(pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return args.trim() !== '' && isInteractiveArgs(args)
+  } catch (e) {
+    return false
+  }
+}
+
+// ---------- /clear 改绑（二期 P2） ----------
+
+/** 与 src/core/state.ts 的 ALIAS_TTL_MS 一致 */
+const ALIAS_TTL_MS = 7 * 24 * 60 * 60 * 1000
+/** SessionEnd(clear) 到 SessionStart(clear) 之间允许的间隔 */
+const CLEAR_PAIR_MS = 60 * 1000
+
+function clearMarkPath(pid) {
+  return path.join(deskbuddyHome(), 'clear', String(pid) + '.json')
+}
+
+/** SessionEnd(reason=clear)：按智能体进程号记下旧会话，等同一进程的 SessionStart(source=clear) 来配对 */
+function markClear(pid, oldSessionId) {
+  try {
+    fs.mkdirSync(path.join(deskbuddyHome(), 'clear'), { recursive: true })
+    fs.writeFileSync(clearMarkPath(pid), JSON.stringify({ old: oldSessionId, at: Date.now() }), 'utf8')
+  } catch (e) {
+    /* 改绑是锦上添花，失败就退回"旧会话失效" */
+  }
+}
+
+/** SessionStart(source=clear)：配对成功就写别名 旧 → 新 */
+function pairClear(pid, newSessionId) {
+  let mark
+  try {
+    mark = JSON.parse(fs.readFileSync(clearMarkPath(pid), 'utf8'))
+    fs.unlinkSync(clearMarkPath(pid))
+  } catch (e) {
+    return
+  }
+  if (!mark || typeof mark.old !== 'string' || !mark.old || mark.old === newSessionId) return
+  if (!(Date.now() - mark.at < CLEAR_PAIR_MS)) return
+  const file = path.join(deskbuddyHome(), 'alias.json')
+  let map = {}
+  try {
+    map = JSON.parse(fs.readFileSync(file, 'utf8')) || {}
+  } catch (e) {
+    map = {}
+  }
+  const now = Date.now()
+  for (const k of Object.keys(map)) {
+    if (!(map[k] && now - map[k].at < ALIAS_TTL_MS)) delete map[k]
+  }
+  map[mark.old] = { to: newSessionId, at: now }
+  try {
+    fs.writeFileSync(file + '.tmp', JSON.stringify(map), 'utf8')
+    fs.renameSync(file + '.tmp', file)
+  } catch (e) {
+    /* 同上 */
+  }
+}
+
+/** 最近目录最多记多少条（二期 P6，与 src/core/dirs.ts 同构；上报只取前 10） */
+const DIRS_KEEP = 30
+
+/** UserPromptSubmit 时记下工作目录：{全路径: 最近使用毫秒}。🔴 全路径只留本机 */
+function recordDir(cwd, now) {
+  if (!cwd) return
+  const file = path.join(deskbuddyHome(), 'dirs.json')
+  let map = {}
+  try {
+    map = JSON.parse(fs.readFileSync(file, 'utf8')) || {}
+  } catch (e) {
+    map = {}
+  }
+  map[cwd] = now
+  const kept = Object.entries(map)
+    .filter((e) => typeof e[1] === 'number')
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, DIRS_KEEP)
+  try {
+    fs.mkdirSync(deskbuddyHome(), { recursive: true })
+    fs.writeFileSync(file + '.tmp', JSON.stringify(Object.fromEntries(kept)), 'utf8')
+    fs.renameSync(file + '.tmp', file)
+  } catch (e) {
+    /* 记不下只影响设备上的目录列表 */
+  }
+}
+
+/** 与 src/core/state.ts 的 NOTICE_TTL_MS 一致 */
+const NOTICE_TTL_MS = 60 * 60 * 1000
+const NOTICE_EVENTS = { PostToolUse: 1, PostToolUseFailure: 1, Stop: 1 }
+
+/**
+ * 窗口回显（S10，见 src/core/state.ts 的 writeNotice）：有就取出并删掉，返回要显示的文字。
+ * 先删再用：并发的两个 hook 最多一个拿到，不会重复显示
+ */
+function takeNotice(sessionId) {
+  const safe = String(sessionId).replace(/[^A-Za-z0-9_-]/g, '')
+  if (!safe) return ''
+  const file = path.join(deskbuddyHome(), 'notice', safe + '.json')
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf8')
+    fs.unlinkSync(file)
+  } catch (e) {
+    return ''
+  }
+  try {
+    const n = JSON.parse(raw)
+    if (typeof n.text !== 'string' || !n.text || !(Date.now() - n.at < NOTICE_TTL_MS)) return ''
+    return n.text.slice(0, 300)
+  } catch (e) {
+    return ''
+  }
+}
+
+async function main(argv) {
+  // 同一份 hook 被 Claude Code 与 Codex 复用，靠命令行参数区分是哪个工具
+  const tool = (argv && argv[2]) || 'claude_code'
+  const payload = readStdin()
+  const event = payload.hook_event_name || ''
+  const sessionId = payload.session_id || ''
+  if (!sessionId) return
+
+  if (NOTICE_EVENTS[event]) {
+    const notice = takeNotice(sessionId)
+    // 🔴 writeSync：macOS 上 stdout 是管道时 process.stdout.write 是异步的，进程先退就丢了
+    if (notice) {
+      try {
+        fs.writeSync(1, JSON.stringify({ systemMessage: notice }))
+      } catch (e) {
+        /* 显示不了就算了 */
+      }
+    }
+  }
+
+  const registry = loadRegistry()
+
+  // /clear 改绑（二期 P2）：SessionStart 在映射表里是 ignore，要在那之前处理
+  if (event === 'SessionStart' && payload.source === 'clear') {
+    const pid = resolveAgentPid(process.pid, agentNames(registry, tool))
+    if (pid) pairClear(pid, sessionId)
+  }
+
+  const action = mapEvent(registry, tool, event, payload)
+  if (action === 'ignore') return
+  if (action === 'remove') {
+    if (event === 'SessionEnd' && payload.reason === 'clear') {
+      const old = readState(sessionId)
+      if (old && old.pid) markClear(old.pid, sessionId)
+    }
+    removeState(sessionId)
+    // 删完补发一次剩余会话，否则这条会一直挂在屏上等服务端失联 TTL。
+    // 关掉最后一个窗口时发的是空列表——服务端放行空快照，该机器该工具随即从屏上消失
+    await reportIfAuthorized(tool, Date.now())
+    return
+  }
+
+  const prev = readState(sessionId)
+  const now = Date.now()
+  if (event === 'UserPromptSubmit') recordDir(payload.cwd, now)
+  // 状态里记的进程还活着才沿用（评审）：先远程 -p 跑过、后又在窗口 resume 同一会话时，
+  // 不能拿死掉的 -p 进程的 interactive=false 挡不住窗口
+  const prevAlive = !!(prev && prev.pid && pidExists(prev.pid))
+  const pid = (prevAlive && prev.pid) || resolveAgentPid(process.pid, agentNames(registry, tool)) || undefined
+  const next = {
+    sessionId: sessionId,
+    tool: tool,
+    // 标题要读文件，只在真正上报时才取（见下面）；这里先沿用上一次的
+    title: (prev && prev.title) || '',
+    project: payload.cwd || (prev && prev.project) || '',
+    // 🔴 和 project 装的是同一个值，不是冗余：project 这个名字读起来就像「只该存目录名」
+    //    （上报侧确实只发 basename，见 snapshot.ts），早晚有人去「修」它。而远程指令靠
+    //    工作目录定位在哪执行 —— 实测 claude --resume 从任何目录都找得到会话，但 agent 的
+    //    工作目录跟着【启动目录】走：目录错了不报任何错，它会拿着对的对话去改错目录里的文件。
+    //    所以单独立一个名字说得清的字段，把这条契约钉死。
+    //    ⚠️ 只落本机，绝不上报：快照里发出去的仍然只有 basename。
+    cwd: payload.cwd || (prev && prev.cwd) || '',
+    state: action,
+    startedAt: (prev && prev.startedAt) || now,
+    updatedAt: now,
+    pid: pid,
+    pidName: pid ? (prevAlive && prev.pidName) || processName(pid) || undefined : undefined,
+    // 二期 P1：窗口开着的会话，设备不能再往里下指令（两个进程会互相吞掉对话）。每个会话只判一次
+    interactive: prevAlive && typeof prev.interactive === 'boolean' ? prev.interactive : detectInteractive(pid),
+    lastReportAt: prev ? prev.lastReportAt : undefined,
+    // daemon 靠它给窗口待批准撤卡（S10），与 src/core/state.ts 的 recent 同构
+    recent: ((prev && Array.isArray(prev.recent) ? prev.recent : []).concat([
+      {
+        e: event,
+        tool: typeof payload.tool_name === 'string' ? payload.tool_name : undefined,
+        fp: typeof payload.tool_name === 'string' ? toolFingerprint(payload.tool_name, payload.tool_input) : undefined,
+        at: now,
+      },
+    ])).slice(-RECENT_MAX),
+  }
+
+  if (!shouldReport(prev, next, now)) {
+    writeState(next)
+    return
+  }
+
+  // 🔴 标题只在真要上报时取（跃迁 / 2 分钟保活），不在每次 hook 事件都去读文件：
+  //    cc-ai-title 要读 transcript，长任务期间 PreToolUse/PostToolUse 触发极频繁
+  next.title =
+    resolveTitle(titleSources(registry, tool), {
+      transcriptPath: payload.transcript_path,
+      cwd: next.project,
+      sessionId: sessionId,
+    }) ||
+    next.title ||
+    ''
+  next.lastReportAt = now
+  writeState(next)
+
+  await reportIfAuthorized(tool, now)
+}
+
+if (require.main === module) {
+  main(process.argv)
+    .catch(() => {
+      /* 🔴 hook 报错会直接打断用户的 AI 会话，一律吞掉 */
+    })
+    .finally(() => process.exit(0))
+}
+
+// 仅供单测使用（被 require 时才会用到，作为 hook 跑时没有任何开销）
+module.exports = {
+  DEFAULT_TITLE_SOURCES,
+  APP_ID,
+  APP_SECRET,
+  FALLBACK_REGISTRY,
+  GATEWAY_VERSION,
+  GIT_LOOKUP_MAX_UP,
+  SERVICES,
+  TRANSCRIPT_TAIL_BYTES,
+  agentNames,
+  buildGatewayBody,
+  buildHeaders,
+  buildSnapshot,
+  isAlive,
+  loadConfig,
+  loadRegistry,
+  main,
+  mapEvent,
+  processName,
+  readAiTitle,
+  readAliveStates,
+  readCodexThreadName,
+  readGitBranch,
+  readState,
+  removeState,
+  resolveAgentPid,
+  resolveTitle,
+  takeNotice,
+  isInteractiveArgs,
+  recordDir,
+  markClear,
+  pairClear,
+  shouldReport,
+  sign,
+  titleSources,
+  writeState,
+}