ai-project-manage-cli 8.0.2 → 8.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-project-manage-cli",
-  "version": "8.0.2",
+  "version": "8.0.4",
   "description": "命令行工具：后续用于调用平台后端 API 完成运维与自动化操作",
   "type": "module",
   "private": false,
@@ -22,10 +22,7 @@
     "@types/node": "^22.0.0",
     "typescript": "~5.6.0",
     "esbuild": "~0.28.0",
-    "vitest": "~4.1.5",
-    "@types/dockerode": "~4.0.1",
-    "@types/ssh2": "~1.15.0",
-    "@types/ssh2-sftp-client": "~9.0.6"
+    "vitest": "~4.1.5"
   },
   "engines": {
     "node": ">=22.13.0"
@@ -38,10 +35,6 @@
     "ws": "~8.18.0",
     "listpage-http": "~0.0.318",
     "commander": "~14.0.3",
-    "minio": "~8.0.7",
-    "dockerode": "~5.0.0",
-    "ssh2": "~1.16.0",
-    "ssh2-sftp-client": "~12.0.1",
-    "jszip": "~3.10.1"
+    "minio": "~8.0.7"
   }
 }

package/template/AGENTS.webide.md

@@ -14,14 +14,14 @@
 - `webide_reply.md`：输出通道（每轮必守）
 - `webide_git_commit.md`：开发 / 修码时的 Git 提交与 push
 - `webide_sql_change.md`：有表结构或 SQL 变更时，须在 `AppendMessage` 中醒目提示
-- `webide_terminal.md`：本地 dev 必须用 WebIDE 终端工具，禁止用 Shell 起长驻进程
+- `webide_terminal.md`：长驻进程禁止用 Shell；本地服务由顶栏「启动项目」触发，开发任务不要自行起服务
 - `webide_testcase.md`：生成测试用例并调用 `UpsertWebIdeTestCases`
 - `webide_merge.md`：验收通过后调用 `MergeWebIdePullRequests`
 
 ### 目录
 
-- 项目文档：`.apm/project/<项目ID>/`（索引 `manifest.json`；部署 / 本地 dev 命令以 `deploy.md` 为准，禁止猜测）
+- 项目文档：`.apm/project/<项目ID>/`（索引 `manifest.json`；部署 / 本地 dev 命令以该目录下文件名或路径包含 `deploy` 的文档为准，不必恰好叫 `deploy.md`，禁止猜测）
 - 任务附件：`.apm/webide/<taskId>/attachments/`（prompt 出现「任务附件」时按路径查看）
 - 仓库清单：`.apm/workspace-repos.json`（先确认单仓 / 多仓；多仓必须写清改动范围并点名仓库）
 
-计划、用例、终端、合并 PR 均走 WebIDE 专用工具（`AskQuestion`、`RecommendPlan`、`UpsertWebIdePlan`、`UpsertWebIdeTestCases`、`StartWebIdeTerminal`、`MergeWebIdePullRequests` 等）。
+计划、用例、合并 PR 走 WebIDE 专用工具（`AskQuestion`、`RecommendPlan`、`UpsertWebIdePlan`、`UpsertWebIdeTestCases`、`MergeWebIdePullRequests` 等）。本地服务由用户在顶栏「启动项目」启动，开发任务不要自行起长驻进程。

package/template/rules/webide_terminal.md

@@ -1,37 +1,44 @@
 # WebIDE 长驻终端
 
-长驻进程（如前后端 `dev`）必须用自定义工具管理，**禁止**用 Shell 启动会长期占用的 dev server。
+长驻进程（如前后端 `dev`）必须用 MCP `pty-session` 管理，**禁止**用 Shell 启动会长期占用的 dev server。
+
+会话与 WebIDE「终端」面板共用同一套 `pty-session-mcp serve`。工具名：`create` / `write` / `read` / `resize` / `kill` / `list`。
+
+本地服务由用户在顶栏「启动项目」触发（独立 Agent），**开发/修码任务不要自行起或重启长驻进程**。
 
 ## 工具
 
-- `StartWebIdeTerminal`：`{ key, name?, cwd, command, readyPattern?, portsHint? }`
-  - `key` 稳定标识，如 `frontend` / `backend`；同 key 已在跑（RUNNING/READY）则幂等返回
-  - 进程挂在 CLI 主进程，跨多轮消息存活
-- `StopWebIdeTerminal`：`{ key }` 或 `{ terminalId }`；杀进程树，状态改为 EXITED（不删记录）
-- `StopAllWebIdeTerminals`：停掉本 task 全部仍存活的终端（重跑本地环境前使用）
-- `ListWebIdeTerminals`：列出**存活**终端（STARTING / RUNNING / READY / STOPPING），**不含** EXITED / FAILED
+- `list`：列出当前仍存活的 PTY。用返回的 `name` 识别服务（如 `frontend` / `backend` / `mobile`）。
+- `create`：`{ cwd, name, command?, args? }`
+  - `name` 用稳定 key（`frontend` / `backend` / `mobile`）
+  - 需要跑 shell 命令时：先 `create({ cwd, name })` 打开默认 shell，再 `write({ id, data: "<命令>" })`（`submit` 默认 true，会补换行）
+  - `command` 只能是可执行文件，不能是整句 shell（如不要把 `pnpm dev` 塞进 `command`）
+- `write`：往会话写命令或输入
+- `read`：`{ id, waitMs }` 轮询输出，直到出现就绪日志 / 端口
+- `kill`：`{ id }` 结束该会话。只杀目标 `name`，不要误杀其它端
 
 ## 启动命令来源
 
-必须 Read `.apm/project/<项目ID>/deploy.md`（完整路径以本轮 prompt 中给出的为准，勿省略项目 ID），按文档中的 cwd / command / 服务划分调用 `StartWebIdeTerminal`。
+必须在 `.apm/project/<项目ID>/` 下找到 **文件名或路径包含 deploy** 的文档（不必恰好叫 `deploy.md`，例如 `deploy前端.md`、`deploy/医务系统.md`）。完整目录以本轮 prompt 给出的项目 ID 为准，勿省略。
 
-- 文档不存在或未写明启动方式 → 用 AppendMessage 说明无法启动本地环境，**禁止猜测命令**。
+1. 先 Read 该目录的 `manifest.json`，从 `documents[].path` 里挑包含 deploy 的条目，再 Read 该文件。
+2. 没有 manifest 时 Glob `**/*deploy*`。
+3. 按文档中的 cwd / command / 服务划分创建会话。
+4. 文档不存在或未写明启动方式 → 结束任务，**禁止猜测命令**。
 
-## 时机（打开本地 dev）
+## 时机（顶栏启动 / 重启）
 
 固定顺序：
 
-1. **`ListWebIdeTerminals`**
-2. 若无活终端 → Read prompt 中的 `.apm/project/<项目ID>/deploy.md` 完整路径 → 按前后端分别 `StartWebIdeTerminal`；已有活终端则复用
-3. 等待 READY / 端口即可
-4. AppendMessage：可在「终端」面板观察本地日志；「浏览器」面板由平台打开本客户机外网地址（勿粘贴整段 stdout；无需 Agent 打开浏览器）
-
-后续改码（热更新）：有活终端则**复用，不重起**。
+1. **`list`**
+2. 启动：无对应 `name` 的活会话 → 按部署文档 `create` + `write`；已有同名活会话则结束，不重起
+3. 重启：先 `kill` 目标 `name`，再按部署文档 `create` + `write`（不要杀掉其它端）
+4. `read` 等待就绪日志 / 端口即可
 
-显式重跑：`StopAllWebIdeTerminals` → 再 Read `.apm/project/<项目ID>/deploy.md` → 重新 Start。
+用户在「终端」面板看日志，在「浏览器」面板看客户机外网地址。
 
 ## 规范
 
 1. 禁止用 Shell / 后台进程方式起 `dev` / `serve` 等长驻命令。
 2. 观察日志请用户看 WebIDE「终端」面板；页面请用户看「浏览器」面板（客户机外网地址）。
-3. 任务结束或不再需要时可 Stop；不要留下孤儿进程。
+3. 不再需要时可 kill；不要留下孤儿进程。

package/template/skills/webide-run-retro/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: webide-run-retro
+description: >-
+  Resolve a Cursor WebIDE run-id or agent-id to the local conversation
+  transcript, then produce two documents: conversation replay and defect
+  retrospective attribution (unclear requirements vs AI vs environment). Use
+  when the user pastes a run-id (run-<uuid>), agent-id (agent-<uuid>), asks to
+  查找对话, 对话回放, 复盘, 缺陷归因, or reviews WebIDE report-defect rounds.
+---
+
+# WebIDE Run / Agent 复盘
+
+用户给出 `run-id` 或 `agent-id` 时：先还原对话，再只对 **report-defect**（及等价的用户缺陷反馈）做归因。回复用中文。
+
+产出必须是 **两份独立文档**（两份 Canvas），缺一不可：
+
+1. **对话回放** — 整段 agent 对话按轮次可浏览
+2. **复盘归因** — 对用户提出的缺陷做主因判定与改进建议
+
+## 1. 解析 ID
+
+执行（不要手写等价逻辑）：
+
+```bash
+node ~/.cursor/skills/webide-run-retro/scripts/inspect-run.mjs --id '<用户给的ID>'
+```
+
+脚本会：
+
+- 读 `AGENT_TRANSCRIPTS` 与 `~/.cursor/projects/*/agent-transcripts`
+- 查 SDK store `index.db`（活表 + 已删除页的字符串残留，因为 WebIDE 常 `purge` store）
+- 读 `.apm/webide/<taskId>/cursor-agent.json`
+- 打印 `agentId`、`matchedRunId`、`transcriptPath`、按轮次的 `conversation`
+
+`run-<uuid>` 是一次 `send()`；`agent-<uuid>` 是整段多轮会话。有 run-id 时仍要拉**整个 agent** 对话，否则看不到原需求。
+
+找不到 transcript 就停，说明缺了哪一层（store / transcripts / 已清理），不要编对话。
+
+## 2. 读对话
+
+用脚本输出的 `transcriptPath` 做补充阅读：
+
+- 第一轮 `action=start`（或首条用户需求）= **原需求原文**
+- `action=write-plan` / `start-develop` = AI 理解与实现范围
+- `action=report-defect` = 待归因缺陷（`【现状】` / `【预期】`）
+- 助手收尾句与 git 提交（`feat:` / `fix:`）用来核对手改了什么
+
+需要核对代码时，对比特性分支相对基线的首次实现提交 vs 后续 `fix:` 提交，避免把基线旧逻辑算成 AI 新引入。
+
+## 3. 归因（必做）
+
+细则见 [attribution.md](attribution.md)。对每条缺陷标**一个主因**：
+
+1. **需求没写清** — 原文没有该行为/边界/状态机
+2. **AI 理解或实现问题** — 原文或缺陷期望已写清，但理解偏了、修不彻底、工作流做半截
+3. **环境 / 工程** — 启动、构建、端口，与业务无关
+
+总判断先写：**原需求有没有被理解对**。后面的缺陷经常是测试挖出未写进需求的业务，不要误判成「字段理解反了」。
+
+给出两个动作建议：
+
+- 需求没写清 → 培训用户（过滤包含/排除、空值样例、暂存/提交状态机、字段可空、验收反例）
+- AI 理解/实现问题 → 补业务文档（组件默认过滤、审批暂存/startFlow、deploy 启动命令）
+
+## 4. 输出
+
+聊天里用 3–8 句中文给出：agent-id、任务名、回放轮次数、缺陷条数、总判断、两条动作建议。然后给出两份 Canvas 的 markdown 链接。不要用大 markdown 表代替 Canvas。
+
+先 Read `~/.cursor/skills-cursor/canvas/SKILL.md`。两份都写在 `~/.cursor/projects/<workspace>/canvases/`，文件名 kebab-case。
+
+### 文档 1：对话回放
+
+文件：`<agent-short-id>-conversation.canvas.tsx`
+
+必须包含：
+
+- ID 映射：run-id、agent-id、task-id
+- 任务标题与时间范围
+- 轮次一览表：序号、时间、动作、用户意图、工具次数
+- 对话正文：每轮可展开，用户请求摘要 + 助手收尾回复（不要堆工具调用细节）
+- 中断后重试的同一缺陷合并说明（若有）
+
+### 文档 2：复盘归因
+
+文件：`<agent-short-id>-retro.canvas.tsx`
+
+必须包含：
+
+- 总判断：原需求有没有被理解对
+- 主因分布（饼图或统计）：需求没写清 / AI 理解或实现 / 环境
+- 原需求实际覆盖了什么（对照评估与首轮实现）
+- 缺陷连锁关系（若有）
+- 逐条归因表：缺陷、主因、原需求是否覆盖、原因
+- 两块建议：培训用户写需求 vs 补 AI 业务文档
+
+无缺陷时：仍产出文档 2，写明「无 report-defect 轮次，不归因」，不要编缺陷。
+
+## 5. 禁止
+
+- 不要把对话回放和复盘归因合成一份 Canvas
+- 不要把缺陷单里新补的期望，回溯成「原需求 AI 理解错」
+- 不要只复述工具调用；归因要对照原文、评估结论、代码/提交
+- 不要输出密钥、API Key、MinIO 凭证

package/template/skills/webide-run-retro/attribution.md

@@ -0,0 +1,26 @@
+# 缺陷归因细则
+
+主因只标一个。对照物永远是**该 agent 第一轮用户需求原文**，不是后续缺陷单里补充的期望。
+
+## 三类主因
+
+| 主因 | 何时用 | 对应动作 |
+|------|--------|----------|
+| 需求没写清 | 缺陷所要的行为不在原文（含空值、过滤白名单、按钮/状态机、验收反例） | 培训用户把需求写完整 |
+| AI 理解或实现问题 | 原文已覆盖，或缺陷单已写清期望，但 AI 理解偏了、修不彻底、把工作流做半截 | 补业务/组件/工作流文档 |
+| 环境 / 工程 | 启动失败、端口、构建命令、与业务无关 | 补 deploy/启动文档 |
+
+不要把「测试中途新提出的暂存/提交」算成「AI 把原需求理解错」。原需求理解对、范围外行为在测试里才出现 → 需求缺口。
+
+## 连锁缺陷
+
+同一缺口连续爆出来时，在表里分开写，但复盘正文要标明因果链。例如：未写「无级别术式可申请」→ 选中后必填失败 → 库非空失败 → 改成暂存 → 列表/工作流半截。
+
+只把链尾的「做半截」标成 AI 实现问题；链头标需求缺口。
+
+## 评估阶段检查
+
+若第一轮评估写了「无开放问题」，但测试缺陷正好落在未提问的边界上，复盘里必须点出本该问的问题，并同时改进：
+
+- 用户需求模板（过滤包含/排除、空值样例、按钮状态机、字段可空、验收反例）
+- AI 评估检查单（空值、默认过滤、暂存 vs 提交、流程何时启动）

package/template/skills/webide-run-retro/scripts/inspect-run.mjs

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+/**
+ * Resolve a Cursor SDK run-id or agent-id to the local transcript and a
+ * structured conversation summary. Execute this script; do not reimplement.
+ *
+ * Usage:
+ *   node inspect-run.mjs --id run-<uuid>
+ *   node inspect-run.mjs --id agent-<uuid>
+ *   node inspect-run.mjs --id <uuid>
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+const UUID_RE =
+  "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const RUN_RE = new RegExp(`run-${UUID_RE}`, "gi");
+const AGENT_RE = new RegExp(`agent-${UUID_RE}`, "gi");
+
+function arg(name, fallback) {
+  const idx = process.argv.indexOf(name);
+  if (idx >= 0 && process.argv[idx + 1]) return process.argv[idx + 1];
+  return fallback;
+}
+
+function walkFiles(root, matcher, acc = [], depth = 0) {
+  if (!root || depth > 6 || acc.length > 80) return acc;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const ent of entries) {
+    const full = path.join(root, ent.name);
+    if (ent.isDirectory()) {
+      if (["node_modules", ".git", "target"].includes(ent.name)) continue;
+      walkFiles(full, matcher, acc, depth + 1);
+    } else if (matcher(full, ent.name)) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+function normalizeId(raw) {
+  const id = String(raw || "").trim();
+  if (!id) throw new Error("missing --id");
+  if (id.startsWith("run-") || id.startsWith("agent-")) return id;
+  if (new RegExp(`^${UUID_RE}$`, "i").test(id)) {
+    return { uuid: id, ambiguous: true };
+  }
+  return id;
+}
+
+function texts(rec) {
+  const content = rec?.message?.content;
+  if (!Array.isArray(content)) return [];
+  return content
+    .filter((c) => c?.type === "text" && c.text)
+    .map((c) => String(c.text).replace(/\[REDACTED\]/g, "").trim())
+    .filter(Boolean);
+}
+
+function tools(rec) {
+  const content = rec?.message?.content;
+  if (!Array.isArray(content)) return [];
+  return content.filter((c) => c?.type === "tool_use").map((c) => c.name);
+}
+
+function parseTranscript(filePath) {
+  const lines = fs.readFileSync(filePath, "utf8").trim().split("\n").filter(Boolean);
+  const records = lines.map((line, i) => {
+    try {
+      return { i, ...JSON.parse(line) };
+    } catch {
+      return { i, role: "unknown", parseError: true };
+    }
+  });
+
+  const rounds = [];
+  let cur = null;
+  for (const rec of records) {
+    if (rec.role === "user") {
+      const raw = texts(rec).join("\n");
+      if (raw.startsWith("<dynamic_tools>")) continue;
+      if (cur) rounds.push(cur);
+      const ts = (raw.match(/<timestamp>(.*?)<\/timestamp>/) || [])[1] || "";
+      const action = (raw.match(/\baction=([^\s]+)/) || [])[1] || "";
+      const taskId = (raw.match(/\btaskId=([^\s]+)/) || [])[1] || "";
+      const title = (raw.match(/标题：(.+)/) || [])[1]?.trim() || "";
+      const dm = raw.match(/【现状】\s*([\s\S]*?)\s*【预期】/);
+      const em = raw.match(/【预期】\s*([\s\S]*?)(?:\n\n##|\npayload=|$)/);
+      cur = {
+        ts,
+        action,
+        taskId,
+        title,
+        defect: dm ? dm[1].trim().replace(/\s+/g, " ") : "",
+        expected: em ? em[1].trim().replace(/\s+/g, " ") : "",
+        userPreview: raw.replace(/\s+/g, " ").slice(0, 280),
+        lastReply: "",
+        assistantNotes: [],
+        toolCount: 0,
+      };
+    } else if (cur && rec.role === "assistant") {
+      const t = texts(rec).join(" ").trim();
+      cur.toolCount += tools(rec).length;
+      if (t) {
+        cur.assistantNotes.push(t.slice(0, 240));
+        cur.lastReply = t.slice(0, 400);
+      }
+    }
+  }
+  if (cur) rounds.push(cur);
+
+  const first = rounds[0] || {};
+  return {
+    recordCount: records.length,
+    taskId: rounds.map((r) => r.taskId).find(Boolean) || "",
+    title: rounds.map((r) => r.title).find(Boolean) || "",
+    rounds,
+    defects: rounds
+      .filter((r) => r.action === "report-defect" || r.defect)
+      .map((r, idx) => ({
+        n: idx + 1,
+        ts: r.ts,
+        defect: r.defect,
+        expected: r.expected,
+        lastReply: r.lastReply,
+        toolCount: r.toolCount,
+      })),
+    actions: rounds.map((r) => r.action).filter(Boolean),
+    firstAction: first.action || "",
+  };
+}
+
+function readLiveSqlite(dbPath) {
+  const out = { agents: [], runs: [] };
+  try {
+    const db = new DatabaseSync(dbPath);
+    try {
+      out.agents = db.prepare("SELECT * FROM agents").all();
+      out.runs = db.prepare("SELECT * FROM runs").all();
+    } finally {
+      db.close();
+    }
+  } catch (err) {
+    out.error = err.message;
+  }
+  return out;
+}
+
+function scanSqliteBinary(dbPath) {
+  const buf = fs.readFileSync(dbPath);
+  const text = buf.toString("latin1");
+  return {
+    agentIds: [...new Set(text.match(AGENT_RE) || [])],
+    runIds: [...new Set(text.match(RUN_RE) || [])],
+  };
+}
+
+function discoverRoots() {
+  const cwd = process.cwd();
+  const home = os.homedir();
+  const transcriptsEnv = process.env.AGENT_TRANSCRIPTS;
+  const cursorHome = fs.existsSync(path.join(home, ".cursor"))
+    ? path.join(home, ".cursor")
+    : path.join("/data", "cursor-home");
+  const projectsDir = path.join(cursorHome, "projects");
+  return { cwd, home, transcriptsEnv, cursorHome, projectsDir };
+}
+
+function findTranscripts(roots) {
+  const dirs = [];
+  if (roots.transcriptsEnv && fs.existsSync(roots.transcriptsEnv)) {
+    dirs.push(roots.transcriptsEnv);
+  }
+  if (fs.existsSync(roots.projectsDir)) {
+    for (const name of fs.readdirSync(roots.projectsDir)) {
+      const p = path.join(roots.projectsDir, name, "agent-transcripts");
+      if (fs.existsSync(p)) dirs.push(p);
+    }
+  }
+  return [...new Set(dirs)];
+}
+
+function findStores(roots) {
+  const files = [];
+  if (fs.existsSync(roots.projectsDir)) {
+    for (const name of fs.readdirSync(roots.projectsDir)) {
+      const store = path.join(roots.projectsDir, name, "sdk-agent-store");
+      walkFiles(store, (full, base) => base === "index.db", files, 0);
+    }
+  }
+  walkFiles(
+    path.join(roots.cwd, ".apm"),
+    (full, base) => base === "cursor-agent.json",
+    files,
+    0,
+  );
+  return files;
+}
+
+function findTranscriptFile(transcriptDirs, agentId) {
+  const stems = [agentId, agentId.replace(/^agent-/, ""), `agent-${agentId.replace(/^agent-/, "")}`];
+  for (const dir of transcriptDirs) {
+    for (const stem of stems) {
+      const nested = path.join(dir, stem, `${stem}.jsonl`);
+      if (fs.existsSync(nested)) return nested;
+      const flat = path.join(dir, `${stem}.jsonl`);
+      if (fs.existsSync(flat)) return flat;
+    }
+    try {
+      for (const name of fs.readdirSync(dir)) {
+        if (name.includes(agentId.replace(/^agent-/, ""))) {
+          const candidate = path.join(dir, name, `${name}.jsonl`);
+          if (fs.existsSync(candidate)) return candidate;
+        }
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  return null;
+}
+
+function main() {
+  const rawId = arg("--id", process.argv[2]);
+  const normalized = normalizeId(rawId);
+  const roots = discoverRoots();
+  const transcriptDirs = findTranscripts(roots);
+  const storeFiles = findStores(roots);
+
+  const recovered = { agentIds: new Set(), runIds: new Set(), liveRuns: [] };
+  for (const file of storeFiles.filter((f) => f.endsWith("index.db"))) {
+    const live = readLiveSqlite(file);
+    for (const row of live.runs || []) {
+      recovered.liveRuns.push({
+        store: file,
+        runId: row.run_id || row.runId,
+        agentId: row.agent_id || row.agentId,
+        status: row.status,
+        turnNumber: row.turn_number || row.turnNumber,
+      });
+      if (row.run_id) recovered.runIds.add(row.run_id);
+      if (row.agent_id) recovered.agentIds.add(row.agent_id);
+    }
+    for (const row of live.agents || []) {
+      if (row.agent_id) recovered.agentIds.add(row.agent_id);
+    }
+    const scanned = scanSqliteBinary(file);
+    scanned.agentIds.forEach((id) => recovered.agentIds.add(id));
+    scanned.runIds.forEach((id) => recovered.runIds.add(id));
+  }
+
+  for (const file of storeFiles.filter((f) => f.endsWith("cursor-agent.json"))) {
+    try {
+      const j = JSON.parse(fs.readFileSync(file, "utf8"));
+      if (j.agentId) recovered.agentIds.add(j.agentId);
+    } catch {
+      /* ignore */
+    }
+  }
+
+  let input = typeof normalized === "string" ? normalized : `uuid:${normalized.uuid}`;
+  let kind = "unknown";
+  let agentId = null;
+  let matchedRunId = null;
+
+  const asString = typeof normalized === "string" ? normalized : normalized.uuid;
+  const wantRun = asString.startsWith("run-")
+    ? asString
+    : recovered.runIds.has(`run-${asString}`)
+      ? `run-${asString}`
+      : null;
+  const wantAgent = asString.startsWith("agent-")
+    ? asString
+    : recovered.agentIds.has(`agent-${asString}`)
+      ? `agent-${asString}`
+      : asString.startsWith("agent-")
+        ? asString
+        : `agent-${asString.replace(/^agent-/, "")}`;
+
+  if (asString.startsWith("run-") || recovered.runIds.has(wantRun)) {
+    kind = "run";
+    matchedRunId = wantRun || asString;
+    const live = recovered.liveRuns.find((r) => r.runId === matchedRunId);
+    if (live?.agentId) agentId = live.agentId;
+    if (!agentId && recovered.agentIds.size === 1) {
+      agentId = [...recovered.agentIds][0];
+    }
+  } else if (asString.startsWith("agent-") || recovered.agentIds.has(wantAgent)) {
+    kind = "agent";
+    agentId = wantAgent.startsWith("agent-") ? wantAgent : `agent-${wantAgent}`;
+  } else if (asString.startsWith("agent-") || asString.length === 36) {
+    kind = asString.startsWith("run-") ? "run" : "agent";
+    agentId = kind === "agent" ? (asString.startsWith("agent-") ? asString : `agent-${asString}`) : null;
+    matchedRunId = kind === "run" ? asString : null;
+  }
+
+  if (!agentId && kind === "agent") {
+    agentId = asString.startsWith("agent-") ? asString : `agent-${asString}`;
+  }
+
+  let transcriptPath = agentId ? findTranscriptFile(transcriptDirs, agentId) : null;
+  if (!transcriptPath && kind === "agent") {
+    transcriptPath = findTranscriptFile(transcriptDirs, asString);
+  }
+
+  const conversation = transcriptPath ? parseTranscript(transcriptPath) : null;
+
+  const result = {
+    input: rawId,
+    kind,
+    agentId,
+    matchedRunId,
+    recoveredAgentIds: [...recovered.agentIds],
+    recoveredRunIds: [...recovered.runIds],
+    liveRuns: recovered.liveRuns,
+    transcriptPath,
+    transcriptDirs,
+    storeFiles,
+    conversation,
+    note: !transcriptPath
+      ? "No transcript found. Check AGENT_TRANSCRIPTS or ~/.cursor/projects/*/agent-transcripts."
+      : recovered.liveRuns.length === 0 && matchedRunId
+        ? "Run tables were empty; mapping used leftover SQLite pages plus the only local agent-id."
+        : undefined,
+  };
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+main();