@yorz/cli 0.7.1 → 0.8.0

package/dist/cli/index.js

@@ -23,7 +23,7 @@ import { createOpencode } from "@opencode-ai/sdk";
 import { createInterface as createInterface$1 } from "node:readline/promises";
 import MarkdownIt from "markdown-it";
 const name = "@yorz/cli";
-const version = "0.7.1";
+const version = "0.8.0";
 const type = "module";
 const description = "";
 const bin = { "yorz": "./dist/cli/index.js" };
@@ -35,7 +35,7 @@ const repository = { "type": "git", "url": "git+https://github.com/hughfenghen/Y
 const homepage = "https://github.com/hughfenghen/YorZ#readme";
 const publishConfig = { "access": "public" };
 const scripts = { "build": "pnpm run build:cli && pnpm run build:gui", "build:cli": "vite build", "build:gui": "vite build --config vite.gui.config.ts", "dev:cli": "pnpm run build:cli && node dist/cli/index.js serve --port 7424 --foreground", "dev:gui": "vite --config vite.gui.config.ts", "typecheck": "tsc -b", "test": "vitest run", "test:agent": "node scripts/test-agent.mjs", "test:e2e": "pnpm run build && playwright test", "format": 'prettier --write "src/**/*.{ts,tsx,md,css}"', "prepublishOnly": "pnpm run build" };
-const dependencies = { "@anthropic-ai/claude-agent-sdk": "^0.3.207", "@hono/node-server": "^2.0.4", "@openai/codex-sdk": "^0.144.1", "@opencode-ai/sdk": "^1.17.18", "chokidar": "^5.0.0", "commander": "^12.1.0", "gray-matter": "^4.0.3", "hono": "^4.12.25", "jsdom": "^25.0.1", "markdown-it": "^14.2.0", "mermaid": "^11.0.0", "morphdom": "^2.7.8", "timeago.js": "^4.0.2", "trash": "^10.1.1" };
+const dependencies = { "@anthropic-ai/claude-agent-sdk": "^0.3.207", "@hono/node-server": "^2.0.4", "@openai/codex-sdk": "^0.144.1", "@opencode-ai/sdk": "^1.17.18", "chokidar": "^5.0.0", "commander": "^12.1.0", "gray-matter": "^4.0.3", "hono": "^4.12.25", "jsdom": "^25.0.1", "markdown-it": "^14.2.0", "mermaid": "^11.0.0", "morphdom": "^2.7.8", "parse-diff": "^0.12.0", "timeago.js": "^4.0.2", "trash": "^10.1.1" };
 const devDependencies = { "@fontsource/jetbrains-mono": "^5.3.0", "@kobalte/core": "^0.13.12", "@playwright/test": "^1.61.0", "@solidjs/router": "^0.16.1", "@types/jsdom": "^21.1.7", "@types/markdown-it": "^14.1.2", "@types/node": "^22.10.0", "autoprefixer": "^10.5.2", "class-variance-authority": "^0.7.1", "clsx": "^2.1.1", "concurrently": "^9.1.0", "highlight.js": "^11.11.1", "i18next": "^26.3.6", "i18next-browser-languagedetector": "^8.2.1", "lucide-solid": "^1.24.0", "markdown-it-task-lists": "^2.1.1", "postcss": "^8.5.16", "prettier": "^3.4.0", "solid-js": "^1.9.13", "tailwind-merge": "^3.6.0", "tailwindcss": "^3.4.19", "tailwindcss-animate": "^1.0.7", "typescript": "^5.7.0", "vite": "^6.0.0", "vite-plugin-solid": "^2.11.12", "vitest": "^2.1.0" };
 const pkg = {
   name,
@@ -1199,6 +1199,202 @@ function skillEntryPath(skillName, env = process.env) {
 function skillRef(skillName, env = process.env) {
   return `请先完整阅读并严格遵循 ${skillEntryPath(skillName, env)}（YorZ 内置 ${skillName} skill 规则）`;
 }
+const METRICS_DIR_NAME = "metrics";
+const TELEMETRY_FILE_NAME = "telemetry.jsonl";
+const PROJECT_META_FILE_NAME = "project.json";
+const DEFAULT_TELEMETRY_MAX_BYTES = 5 * 1024 * 1024;
+const DEFAULT_TELEMETRY_MAX_ARCHIVES = 2;
+function resolveMetricsDir(env = process.env) {
+  return join(resolveGlobalConfigDir(env), METRICS_DIR_NAME);
+}
+function resolveProjectMetricsDir(projectRoot, env = process.env) {
+  return join(resolveMetricsDir(env), generateProjectId(resolve(projectRoot)));
+}
+function findProjectRoot(startDir) {
+  let dir = resolve(startDir);
+  for (; ; ) {
+    if (existsSync(join(dir, ".yorz"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function normalizeUsage(kind, raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const obj = raw;
+  const snapshot = kind === "codex" ? fromCodex(obj) : kind === "opencode" ? fromOpenCode(obj) : fromClaude(obj);
+  return isEmpty(snapshot) ? void 0 : snapshot;
+}
+function fromClaude(u) {
+  return compact({
+    inputTokens: num$2(u.input_tokens),
+    outputTokens: num$2(u.output_tokens),
+    cacheReadTokens: num$2(u.cache_read_input_tokens),
+    cacheCreateTokens: num$2(u.cache_creation_input_tokens)
+  });
+}
+function fromCodex(u) {
+  const total = num$2(u.input_tokens);
+  const cached = num$2(u.cached_input_tokens);
+  const uncached = total !== void 0 && cached !== void 0 ? Math.max(total - cached, 0) : total;
+  return compact({
+    inputTokens: uncached,
+    cacheReadTokens: cached,
+    outputTokens: num$2(u.output_tokens),
+    reasoningTokens: num$2(u.reasoning_output_tokens)
+  });
+}
+function fromOpenCode(u) {
+  const cache = u.cache && typeof u.cache === "object" ? u.cache : {};
+  return compact({
+    inputTokens: num$2(u.input),
+    outputTokens: num$2(u.output),
+    reasoningTokens: num$2(u.reasoning),
+    cacheReadTokens: num$2(cache.read),
+    cacheCreateTokens: num$2(cache.write)
+  });
+}
+function num$2(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function compact(snapshot) {
+  const out = {};
+  for (const [key, value] of Object.entries(snapshot)) {
+    if (value !== void 0) out[key] = value;
+  }
+  return out;
+}
+function isEmpty(snapshot) {
+  return Object.keys(snapshot).length === 0;
+}
+const TELEMETRY_SCHEMA_VERSION = 1;
+function isTelemetryEnabled(env = process.env) {
+  const raw = env.YORZ_TELEMETRY?.trim().toLowerCase();
+  if (!raw) return true;
+  return !["off", "0", "false", "no", "disabled"].includes(raw);
+}
+class TelemetryRecorder {
+  constructor(projectRoot, projectId, dir, enabled) {
+    this.projectRoot = projectRoot;
+    this.projectId = projectId;
+    this.dir = dir;
+    this.enabled = enabled;
+    this.sink = enabled ? new RotatingFileSink(
+      dir,
+      TELEMETRY_FILE_NAME,
+      DEFAULT_TELEMETRY_MAX_BYTES,
+      DEFAULT_TELEMETRY_MAX_ARCHIVES
+    ) : null;
+  }
+  sink;
+  metaWritten = false;
+  get filePath() {
+    return join(this.dir, TELEMETRY_FILE_NAME);
+  }
+  /** Queue one event. Returns immediately; never throws. */
+  record(event, payload = {}) {
+    if (!this.sink) return;
+    let line;
+    try {
+      const envelope = {
+        v: TELEMETRY_SCHEMA_VERSION,
+        ts: nowStamp(),
+        event,
+        projectId: this.projectId,
+        ...payload
+      };
+      line = `${JSON.stringify(envelope)}
+`;
+    } catch {
+      return;
+    }
+    this.sink.write(line);
+    this.ensureMeta();
+  }
+  /** Resolve once every queued line has hit the disk (tests / shutdown). */
+  async flush() {
+    await this.sink?.flush();
+  }
+  /** Write the id → absolute path sidecar once per process. Best-effort. */
+  ensureMeta() {
+    if (this.metaWritten || !this.sink) return;
+    this.metaWritten = true;
+    const meta = {
+      id: this.projectId,
+      path: this.projectRoot,
+      firstSeenAt: nowStamp()
+    };
+    void (async () => {
+      try {
+        await mkdir(this.dir, { recursive: true });
+        await writeFile(join(this.dir, PROJECT_META_FILE_NAME), `${JSON.stringify(meta, null, 2)}
+`);
+      } catch {
+      }
+    })();
+  }
+}
+const recorders = /* @__PURE__ */ new Map();
+function getTelemetry(projectRoot, env = process.env) {
+  const root = resolve(projectRoot);
+  const cached = recorders.get(root);
+  if (cached) return cached;
+  const recorder = new TelemetryRecorder(
+    root,
+    generateProjectId(root),
+    resolveProjectMetricsDir(root, env),
+    isTelemetryEnabled(env)
+  );
+  recorders.set(root, recorder);
+  return recorder;
+}
+function nowStamp(date = /* @__PURE__ */ new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  const ymd = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+  return `${ymd} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+const TASK_LINE = /^- \[( |x|X)\]/gm;
+function snapshotSpec(detail) {
+  if (!detail) return null;
+  let tasksTotal = 0;
+  let tasksDone = 0;
+  for (const match of detail.body.matchAll(TASK_LINE)) {
+    tasksTotal += 1;
+    if (match[1] !== " ") tasksDone += 1;
+  }
+  return {
+    stage: detail.frontmatter.stage,
+    tasksTotal,
+    tasksDone,
+    specBytes: Buffer.byteLength(detail.body, "utf8")
+  };
+}
+function trackSpecStage(opts) {
+  const { projectRoot, store, specId, handle, before, trigger } = opts;
+  const beforeSnapshot = snapshotSpec(before);
+  handle.onDone(() => {
+    void (async () => {
+      let afterSnapshot = null;
+      try {
+        afterSnapshot = snapshotSpec(await store.read(specId));
+      } catch {
+      }
+      const payload = {
+        specId,
+        trigger,
+        traceId: handle.runId,
+        sessionId: handle.sessionId,
+        stageBefore: beforeSnapshot?.stage,
+        stageAfter: afterSnapshot?.stage,
+        tasksTotal: afterSnapshot?.tasksTotal,
+        tasksDone: afterSnapshot?.tasksDone,
+        tasksDoneBefore: beforeSnapshot?.tasksDone,
+        specBytes: afterSnapshot?.specBytes
+      };
+      getTelemetry(projectRoot).record("spec.stage", payload);
+    })();
+  });
+}
 function createSpecsRoutes(resolveProject) {
   const app = new Hono();
   const need = async (c) => {
@@ -1229,7 +1425,7 @@ function createSpecsRoutes(resolveProject) {
       const beforeIds = new Set((await p.store.list()).map((s) => s.id));
       const prompt = buildDraftPrompt(input.type, input.requirement, input.draftId);
       const { sessionId } = await p.sessions.createSession();
-      const handle = await p.sessions.send(sessionId, prompt);
+      const handle = await p.sessions.send(sessionId, prompt, void 0, { trigger: "new-spec" });
       handle.onDone((finalSessionId) => {
         void bindDraftSessionToCreatedSpec(p, beforeIds, finalSessionId);
       });
@@ -1365,7 +1561,18 @@ function createSpecsRoutes(resolveProject) {
         "resume",
         await buildDebugRuntimeContext(p)
       ) : `${skillRef("yorz-spec")}，然后处理 spec：${p.specsDirRelative}/${specId}/spec.md`;
-      const handle = await p.sessions.send(sessionId, prompt);
+      const handle = await p.sessions.send(sessionId, prompt, void 0, {
+        trigger: "append",
+        specId
+      });
+      trackSpecStage({
+        projectRoot: p.path,
+        store: p.store,
+        specId,
+        handle,
+        before: detail,
+        trigger: "append"
+      });
       return c.json({ ok: true, runId: handle.runId, sessionId });
     }
     return c.json({ ok: true });
@@ -1379,7 +1586,18 @@ function createSpecsRoutes(resolveProject) {
     const { sessionId } = await p.sessions.ensureSessionForSpec(specId);
     const debugActive = await readDebugMdStatus(join(p.specsDir, specId)) === "debugging";
     const prompt = debugActive ? buildDebugPrompt(p.specsDirRelative, specId, "resume", await buildDebugRuntimeContext(p)) : `${skillRef("yorz-spec")}，然后处理 spec：${p.specsDirRelative}/${specId}/spec.md`;
-    const handle = await p.sessions.send(sessionId, prompt);
+    const handle = await p.sessions.send(sessionId, prompt, void 0, {
+      trigger: "run",
+      specId
+    });
+    trackSpecStage({
+      projectRoot: p.path,
+      store: p.store,
+      specId,
+      handle,
+      before: detail,
+      trigger: "run"
+    });
     return c.json({ runId: handle.runId, sessionId });
   });
   app.post("/projects/:projectId/specs/:id/explain", async (c) => {
@@ -1410,7 +1628,10 @@ ${text}
 """
 `;
     const { sessionId } = await p.sessions.ensureSessionForSpec(specId);
-    const handle = await p.sessions.send(sessionId, prompt);
+    const handle = await p.sessions.send(sessionId, prompt, void 0, {
+      trigger: "explain",
+      specId
+    });
     return c.json({ runId: handle.runId, sessionId });
   });
   app.delete("/projects/:projectId/specs/:id", async (c) => {
@@ -2002,7 +2223,9 @@ function createSessionsRoutes(resolveProject) {
     }
     if (resolved.builtin === "yorz-debug") void cleanupExpiredChatDebugFiles(p.path).catch(() => {
     });
-    const handle = await p.sessions.send(c.req.param("sid"), finalPrompt, prompt);
+    const handle = await p.sessions.send(c.req.param("sid"), finalPrompt, prompt, {
+      trigger: "chat"
+    });
     return c.json({ runId: handle.runId, sessionId: handle.sessionId }, 202);
   });
   app.post("/projects/:projectId/sessions/:sid/abort", async (c) => {
@@ -2082,16 +2305,27 @@ function assertSafeRelativePath(cwd, p) {
   }
   return p;
 }
+function recordGitOp(cwd, args, startedAt, ok, code) {
+  getTelemetry(cwd).record("git.op", {
+    op: args[0] ?? "unknown",
+    ok,
+    exitCode: code,
+    durMs: Date.now() - startedAt
+  });
+}
 async function runGit(cwd, args) {
+  const startedAt = Date.now();
   try {
     const result = await execFileWithoutWindow("git", args, {
       cwd,
       encoding: "utf8",
       maxBuffer: 16 * 1024 * 1024
     });
+    recordGitOp(cwd, args, startedAt, true, 0);
     return { stdout: result.stdout, stderr: result.stderr };
   } catch (err) {
     const e = err;
+    recordGitOp(cwd, args, startedAt, false, typeof e.code === "number" ? e.code : void 0);
     if (e.code === "ENOENT") {
       throw new GitError("git_missing", "git not found on PATH");
     }
@@ -2102,19 +2336,23 @@ async function runGitChecked(cwd, args) {
   return runGit(cwd, args);
 }
 async function runGitRaw(cwd, args) {
+  const startedAt = Date.now();
   try {
     const result = await execFileWithoutWindow("git", args, {
       cwd,
       encoding: "utf8",
       maxBuffer: 16 * 1024 * 1024
     });
+    recordGitOp(cwd, args, startedAt, true, 0);
     return { stdout: result.stdout, stderr: result.stderr, code: 0 };
   } catch (err) {
     const e = err;
     if (e.code === "ENOENT") {
+      recordGitOp(cwd, args, startedAt, false);
       throw new GitError("git_missing", "git not found on PATH");
     }
     const code = typeof e.code === "number" ? e.code : 1;
+    recordGitOp(cwd, args, startedAt, false, code);
     return { stdout: e.stdout ?? "", stderr: e.stderr ?? e.message ?? "", code };
   }
 }
@@ -2198,6 +2436,114 @@ async function discard(cwd, opts) {
     await runGit(cwd, ["clean", "-fd", "--", r.path]);
   }
 }
+const MAX_PATCH_BYTES = 512 * 1024;
+const MAX_PATCH_LINES = 3e3;
+function truncatePatch(patch) {
+  let text = patch;
+  let truncated = false;
+  if (Buffer.byteLength(text, "utf8") > MAX_PATCH_BYTES) {
+    text = text.slice(0, MAX_PATCH_BYTES);
+    truncated = true;
+  }
+  const lines = text.split("\n");
+  if (lines.length > MAX_PATCH_LINES) {
+    text = lines.slice(0, MAX_PATCH_LINES).join("\n");
+    truncated = true;
+  }
+  return { patch: text, truncated };
+}
+async function untrackedDiff(cwd, path) {
+  let buf;
+  try {
+    buf = await readFile(resolve(cwd, path));
+  } catch {
+    return { path, patch: "", binary: false, truncated: false };
+  }
+  if (buf.subarray(0, 8e3).includes(0)) {
+    return { path, patch: "", binary: true, truncated: false };
+  }
+  const text = buf.toString("utf8");
+  const lines = text.length === 0 ? [] : text.replace(/\n$/, "").split("\n");
+  const body = lines.map((l) => `+${l}`).join("\n");
+  const header = `--- /dev/null
++++ b/${path}
+@@ -0,0 +1,${lines.length} @@
+`;
+  const { patch, truncated } = truncatePatch(lines.length ? `${header}${body}` : header);
+  return { path, patch, binary: false, truncated };
+}
+async function fileDiff(cwd, path) {
+  assertSafeRelativePath(cwd, path);
+  const change = (await listChanges(cwd)).find((c) => c.path === path);
+  if (change?.status === "??") return untrackedDiff(cwd, path);
+  const pathArgs = change?.renamedFrom ? [change.renamedFrom, path] : [path];
+  const res = await runGitRaw(cwd, ["diff", "HEAD", "--", ...pathArgs]);
+  if (res.code !== 0 && !res.stdout) {
+    throw new GitError("git_failed", res.stderr.trim() || "git diff failed", res.stderr);
+  }
+  const raw = res.stdout;
+  if (!raw.includes("@@") && /^Binary files .* differ$/m.test(raw)) {
+    return { path, patch: "", binary: true, truncated: false };
+  }
+  const { patch, truncated } = truncatePatch(raw);
+  return { path, patch, binary: false, truncated };
+}
+async function currentBranch(cwd) {
+  const { stdout } = await runGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const branch = stdout.trim();
+  if (!branch || branch === "HEAD") {
+    throw new GitError("detached_head", "cannot operate from a detached HEAD");
+  }
+  return branch;
+}
+async function listBranches(cwd) {
+  const [current, branchesResult] = await Promise.all([
+    currentBranch(cwd),
+    runGit(cwd, ["branch", "--format=%(refname:short)"])
+  ]);
+  const branches = branchesResult.stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+  return { current, branches };
+}
+async function checkoutBranch(cwd, branch) {
+  const target = branch?.trim() ?? "";
+  if (!target) throw new GitError("invalid_branch", "branch must not be empty");
+  const state = await listBranches(cwd);
+  if (!state.branches.includes(target)) {
+    throw new GitError("invalid_branch", `unknown local branch: ${target}`);
+  }
+  if (state.current === target) return { current: state.current };
+  const res = await runGitRaw(cwd, ["checkout", target]);
+  if (res.code !== 0) {
+    throw new GitError("checkout_failed", res.stderr.trim() || "git checkout failed", res.stderr);
+  }
+  return { current: await currentBranch(cwd) };
+}
+async function push(cwd) {
+  const branch = await currentBranch(cwd);
+  const upstream = await runGitRaw(cwd, [
+    "rev-parse",
+    "--abbrev-ref",
+    "--symbolic-full-name",
+    "@{u}"
+  ]);
+  const hasUpstream = upstream.code === 0 && upstream.stdout.trim().length > 0;
+  const args = hasUpstream ? ["push"] : ["push", "--set-upstream", "origin", branch];
+  const res = await runGitRaw(cwd, args);
+  if (res.code !== 0) {
+    throw new GitError("push_failed", res.stderr.trim() || "git push failed", res.stderr);
+  }
+  return { branch, createdUpstream: !hasUpstream };
+}
+async function pull(cwd) {
+  const branch = await currentBranch(cwd);
+  const before = (await runGit(cwd, ["rev-parse", "HEAD"])).stdout.trim();
+  const res = await runGitRaw(cwd, ["pull", "--ff-only"]);
+  if (res.code !== 0) {
+    throw new GitError("pull_failed", res.stderr.trim() || "git pull failed", res.stderr);
+  }
+  const after = (await runGit(cwd, ["rev-parse", "HEAD"])).stdout.trim();
+  return { branch, updated: before !== after };
+}
 async function stash(cwd, opts) {
   if (!Array.isArray(opts.paths) || opts.paths.length === 0) {
     throw new GitError("no_paths", "stash requires at least one path");
@@ -2238,7 +2584,18 @@ function createSpecReviewRoutes(resolveProject) {
     const specRel = `${p.specsDirRelative}/${specId}/spec.md`;
     const prompt = buildGitOpsPrompt(action, specId, specRel);
     const { sessionId } = await p.sessions.ensureSessionForSpec(specId);
-    const handle = await p.sessions.send(sessionId, prompt);
+    const handle = await p.sessions.send(sessionId, prompt, void 0, {
+      trigger: "git-ops",
+      specId
+    });
+    trackSpecStage({
+      projectRoot: p.path,
+      store: p.store,
+      specId,
+      handle,
+      before: detail,
+      trigger: "git-ops"
+    });
     return c.json({ runId: handle.runId, sessionId });
   });
   app.get("/projects/:projectId/specs/:id/debug", async (c) => {
@@ -2256,21 +2613,7 @@ function createSpecReviewRoutes(resolveProject) {
       return c.json({ exists: false, text: "" });
     }
   });
-  app.get("/projects/:projectId/specs/:id/changes", async (c) => {
-    const p = await need(c);
-    if (p instanceof Response) return p;
-    const specId = c.req.param("id");
-    const detail = await p.store.read(specId);
-    if (!detail) return c.json({ error: "spec not found" }, 404);
-    try {
-      const changes = await listChanges(p.path);
-      return c.json({ changes });
-    } catch (err) {
-      if (err instanceof GitError) return c.json({ error: err.message }, 400);
-      throw err;
-    }
-  });
-  app.post("/projects/:projectId/specs/:id/commit", async (c) => {
+  app.post("/projects/:projectId/specs/:id/stash", async (c) => {
     const p = await need(c);
     if (p instanceof Response) return p;
     const specId = c.req.param("id");
@@ -2285,30 +2628,122 @@ function createSpecReviewRoutes(resolveProject) {
     const obj = body && typeof body === "object" ? body : {};
     const message = typeof obj.message === "string" ? obj.message.trim() : "";
     const paths = Array.isArray(obj.paths) ? obj.paths.filter((v) => typeof v === "string") : [];
-    if (!message) return c.json({ error: "message must not be empty" }, 400);
     if (paths.length === 0) return c.json({ error: "paths must not be empty" }, 400);
     try {
-      const result = await commit(p.path, { message, paths });
-      return c.json(result);
+      await stash(p.path, { message: message || `yorz:${specId}`, paths });
+      return c.json({ ok: true });
     } catch (err) {
       if (err instanceof GitError) return c.json({ error: err.message }, 400);
       throw err;
     }
   });
-  app.post("/projects/:projectId/specs/:id/discard", async (c) => {
+  return app;
+}
+function buildGitOpsPrompt(action, specId, specRel) {
+  const base = `${skillRef("yorz-git-ops")}，然后执行 git 操作：
+- spec 文档：${specRel}
+- 请依据 spec 文档与 git status/diff 自行判断本次 spec 关联的变更文件
+- spec-id：${specId}
+`;
+  switch (action) {
+    case "commit":
+      return base + `- 动作：git-commit。请基于 spec 文档与 git status/diff，由你自主判断本次 spec 相关的变更文件，执行 \`git add\` + \`git commit\`；commit message 由你生成，不带 scope；禁止 \`git push\` 与 \`git reset --hard\`。
+`;
+    case "discard":
+      return base + `- 动作：git-discard。请使用 \`git restore --staged --worktree -- <paths>\` 与 \`git clean -fd -- <paths>\` 丢弃 spec 相关的未提交变更；对 untracked 新文件应先在终端输出列表再处理；不要预先 stash 备份；禁止 \`git reset --hard\` 与 \`git push\`。
+`;
+    case "stash":
+      return base + `- 动作：git-stash。请使用 \`git stash push -m "yorz:${specId}" -- <paths>\` 暂存 spec 相关变更文件；禁止 \`git push\`。
+`;
+  }
+}
+function createGitRoutes(resolveProject) {
+  const app = new Hono();
+  const need = async (c) => {
+    const id = c.req.param("projectId") ?? "";
+    if (!id) return c.json({ error: "projectId required" }, 400);
+    const project = await resolveProject(id);
+    if (!project) return c.json({ error: "project not found" }, 404);
+    return project;
+  };
+  const readBody = async (c) => {
+    try {
+      const body = await c.req.json();
+      return body && typeof body === "object" ? body : {};
+    } catch {
+      return null;
+    }
+  };
+  const toPaths = (value) => Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+  app.get("/projects/:projectId/git/changes", async (c) => {
     const p = await need(c);
     if (p instanceof Response) return p;
-    const specId = c.req.param("id");
-    const detail = await p.store.read(specId);
-    if (!detail) return c.json({ error: "spec not found" }, 404);
-    let body;
     try {
-      body = await c.req.json();
-    } catch {
-      return c.json({ error: "invalid JSON body" }, 400);
+      return c.json({ changes: await listChanges(p.path) });
+    } catch (err) {
+      if (err instanceof GitError) return c.json({ error: err.message }, 400);
+      throw err;
     }
-    const obj = body && typeof body === "object" ? body : {};
-    const paths = Array.isArray(obj.paths) ? obj.paths.filter((v) => typeof v === "string") : [];
+  });
+  app.get("/projects/:projectId/git/diff", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const path = c.req.query("path") ?? "";
+    if (!path) return c.json({ error: "path required" }, 400);
+    try {
+      return c.json(await fileDiff(p.path, path));
+    } catch (err) {
+      if (err instanceof GitError) return c.json({ error: err.message }, 400);
+      throw err;
+    }
+  });
+  app.get("/projects/:projectId/git/branches", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    try {
+      return c.json(await listBranches(p.path));
+    } catch (err) {
+      if (err instanceof GitError) return c.json({ error: err.message }, 400);
+      throw err;
+    }
+  });
+  app.post("/projects/:projectId/git/checkout", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const body = await readBody(c);
+    if (!body) return c.json({ error: "invalid JSON body" }, 400);
+    const branch = typeof body.branch === "string" ? body.branch.trim() : "";
+    if (!branch) return c.json({ error: "branch must not be empty" }, 400);
+    try {
+      const result = await checkoutBranch(p.path, branch);
+      return c.json({ ok: true, ...result });
+    } catch (err) {
+      if (err instanceof GitError) return c.json({ error: err.message }, 400);
+      throw err;
+    }
+  });
+  app.post("/projects/:projectId/git/commit", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const body = await readBody(c);
+    if (!body) return c.json({ error: "invalid JSON body" }, 400);
+    const message = typeof body.message === "string" ? body.message.trim() : "";
+    const paths = toPaths(body.paths);
+    if (!message) return c.json({ error: "message must not be empty" }, 400);
+    if (paths.length === 0) return c.json({ error: "paths must not be empty" }, 400);
+    try {
+      return c.json(await commit(p.path, { message, paths }));
+    } catch (err) {
+      if (err instanceof GitError) return c.json({ error: err.message }, 400);
+      throw err;
+    }
+  });
+  app.post("/projects/:projectId/git/discard", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const body = await readBody(c);
+    if (!body) return c.json({ error: "invalid JSON body" }, 400);
+    const paths = toPaths(body.paths);
     if (paths.length === 0) return c.json({ error: "paths must not be empty" }, 400);
     try {
       await discard(p.path, { paths });
@@ -2318,25 +2753,23 @@ function createSpecReviewRoutes(resolveProject) {
       throw err;
     }
   });
-  app.post("/projects/:projectId/specs/:id/stash", async (c) => {
+  app.post("/projects/:projectId/git/push", async (c) => {
     const p = await need(c);
     if (p instanceof Response) return p;
-    const specId = c.req.param("id");
-    const detail = await p.store.read(specId);
-    if (!detail) return c.json({ error: "spec not found" }, 404);
-    let body;
     try {
-      body = await c.req.json();
-    } catch {
-      return c.json({ error: "invalid JSON body" }, 400);
+      const result = await push(p.path);
+      return c.json({ ok: true, ...result });
+    } catch (err) {
+      if (err instanceof GitError) return c.json({ error: err.message }, 400);
+      throw err;
     }
-    const obj = body && typeof body === "object" ? body : {};
-    const message = typeof obj.message === "string" ? obj.message.trim() : "";
-    const paths = Array.isArray(obj.paths) ? obj.paths.filter((v) => typeof v === "string") : [];
-    if (paths.length === 0) return c.json({ error: "paths must not be empty" }, 400);
+  });
+  app.post("/projects/:projectId/git/pull", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
     try {
-      await stash(p.path, { message: message || `yorz:${specId}`, paths });
-      return c.json({ ok: true });
+      const result = await pull(p.path);
+      return c.json({ ok: true, ...result });
     } catch (err) {
       if (err instanceof GitError) return c.json({ error: err.message }, 400);
       throw err;
@@ -2344,24 +2777,6 @@ function createSpecReviewRoutes(resolveProject) {
   });
   return app;
 }
-function buildGitOpsPrompt(action, specId, specRel) {
-  const base = `${skillRef("yorz-git-ops")}，然后执行 git 操作：
-- spec 文档：${specRel}
-- 请依据 spec 文档与 git status/diff 自行判断本次 spec 关联的变更文件
-- spec-id：${specId}
-`;
-  switch (action) {
-    case "commit":
-      return base + `- 动作：git-commit。请基于 spec 文档与 git status/diff，由你自主判断本次 spec 相关的变更文件，执行 \`git add\` + \`git commit\`；commit message 由你生成，不带 scope；禁止 \`git push\` 与 \`git reset --hard\`。
-`;
-    case "discard":
-      return base + `- 动作：git-discard。请使用 \`git restore --staged --worktree -- <paths>\` 与 \`git clean -fd -- <paths>\` 丢弃 spec 相关的未提交变更；对 untracked 新文件应先在终端输出列表再处理；不要预先 stash 备份；禁止 \`git reset --hard\` 与 \`git push\`。
-`;
-    case "stash":
-      return base + `- 动作：git-stash。请使用 \`git stash push -m "yorz:${specId}" -- <paths>\` 暂存 spec 相关变更文件；禁止 \`git push\`。
-`;
-  }
-}
 const sseLog = () => getLogger().child("sse");
 const HEARTBEAT_INTERVAL_MS = 5e3;
 function attachHeartbeat(stream, intervalMs = HEARTBEAT_INTERVAL_MS) {
@@ -2553,9 +2968,8 @@ class EventsHub {
     if (rest === "commands") return this.attachCommandRuns(s, topic, project);
     const cm = /^command:(.+)$/.exec(rest);
     if (cm) return this.attachCommandRun(s, topic, project, cm[1]);
-    let sm = /^spec:([^:]+):changes$/.exec(rest);
-    if (sm) return this.attachSpecChanges(s, topic, project, sm[1]);
-    sm = /^spec:([^:]+)$/.exec(rest);
+    if (rest === "changes") return this.attachProjectChanges(s, topic, project);
+    let sm = /^spec:([^:]+)$/.exec(rest);
     if (sm) return this.attachSpec(s, topic, project, sm[1]);
     sm = /^session:(.+)$/.exec(rest);
     if (sm) return this.attachSession(s, topic, project, sm[1]);
@@ -2593,9 +3007,12 @@ class EventsHub {
       this.emit(s, topic, "updated", { type: kind, mtime });
     });
   }
-  async attachSpecChanges(s, topic, project, specId) {
-    const exists = await project.store.read(specId);
-    if (!exists) throw new Error("spec not found");
+  /**
+   * Git changes are repository-wide: the watcher is keyed on the project path,
+   * so this topic carries no spec id and both the standalone Git page and the
+   * spec Review page share one subscription.
+   */
+  attachProjectChanges(s, topic, project) {
     this.emit(s, topic, "ready", {});
     const { current, unsubscribe } = subscribeGitChanges(project.path, (changes) => {
       this.emit(s, topic, "changes-updated", { changes });
@@ -3986,6 +4403,15 @@ class CommandManager {
     this.notifyRuns();
     this.notifyRun(next);
     log$3().info("command ended", { runId, status, exitCode, signal });
+    getTelemetry(this.projectPath).record("cmd.exec", {
+      commandId: next.commandId,
+      name: next.name,
+      runId,
+      status,
+      exitCode: exitCode ?? void 0,
+      signal: signal ?? void 0,
+      durMs: (next.endedAt ?? Date.now()) - next.startedAt
+    });
   }
   notifyRuns() {
     if (this.runsSubscribers.size === 0) return;
@@ -4808,7 +5234,7 @@ function parseCommitLines(stdout) {
 function renderConflictSpec(args) {
   const { branch, report, now } = args;
   const today = `${now.getFullYear()}-${pad2(now.getMonth() + 1)}-${pad2(now.getDate())}`;
-  const nowStamp = `${today} ${pad2(now.getHours())}:${pad2(now.getMinutes())}:${pad2(now.getSeconds())}`;
+  const nowStamp2 = `${today} ${pad2(now.getHours())}:${pad2(now.getMinutes())}:${pad2(now.getSeconds())}`;
   const fileLines = report.files.length ? report.files.map((f) => `- \`${f}\``).join("\n") : "- （无 — 合并失败但未列出冲突文件，请人工核查）";
   const commitBlocks = report.files.length ? report.files.map((f) => {
     const commits = report.commitsByFile[f] ?? [];
@@ -4878,7 +5304,7 @@ _暂无_
     "---",
     "stage: plan",
     "last_action: 由 worktree 合并冲突自动生成",
-    `updated_at: '${nowStamp}'`,
+    `updated_at: '${nowStamp2}'`,
     `summary: 解决 ${branch} 合并到主项目时产生的 ${report.files.length} 个冲突文件`,
     "---",
     ""
@@ -4934,7 +5360,9 @@ function createApp(opts) {
       const { sessionId } = await main.sessions.ensureSessionForSpec(specId);
       void main.sessions.send(
         sessionId,
-        `${skillRef("yorz-spec")}，然后处理 spec：${main.specsDirRelative}/${specId}/spec.md`
+        `${skillRef("yorz-spec")}，然后处理 spec：${main.specsDirRelative}/${specId}/spec.md`,
+        void 0,
+        { trigger: "conflict", specId }
       );
     }
   });
@@ -4947,6 +5375,7 @@ function createApp(opts) {
   api.route("/", createSpecsRoutes(resolveProject));
   api.route("/", createSessionsRoutes(resolveProject));
   api.route("/", createSpecReviewRoutes(resolveProject));
+  api.route("/", createGitRoutes(resolveProject));
   api.route("/", createSpecDraftsRoutes(resolveProject));
   api.route("/", createWorktreeRoutes(opts.registry, worktreeManager));
   api.route("/", createProjectFilesRoutes(resolveProject));
@@ -5420,6 +5849,7 @@ const watcherLog = () => getLogger().child("watcher");
 const UNLINK_SETTLE_MS = 80;
 class SpecWatcher {
   root;
+  cwd;
   unlinkSettleMs;
   detailListeners = /* @__PURE__ */ new Map();
   listListeners = /* @__PURE__ */ new Set();
@@ -5430,6 +5860,7 @@ class SpecWatcher {
   watcher = null;
   constructor(opts) {
     this.root = opts.specsDir ?? join(opts.cwd, ".yorz", "specs");
+    this.cwd = opts.cwd;
     this.unlinkSettleMs = opts.unlinkSettleMs ?? UNLINK_SETTLE_MS;
   }
   async start() {
@@ -5523,6 +5954,7 @@ class SpecWatcher {
     this.pendingUnlinks.set(id, timer);
   }
   emit(id, evt, mtimeMs) {
+    getTelemetry(this.cwd).record("spec.change", { specId: id, kind: evt, mtimeMs });
     for (const cb of this.detailListeners.get(id) ?? []) cb(evt, mtimeMs);
     for (const cb of this.listListeners) cb();
   }
@@ -5586,6 +6018,29 @@ function usageWindows(usage) {
   }
   return out;
 }
+function num$1(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function withCost(usage, costUsd) {
+  if (costUsd === void 0) return usage;
+  return { ...usage ?? {}, costUsd };
+}
+function primaryModel(modelUsage) {
+  if (!isRecord(modelUsage)) return void 0;
+  let best;
+  let bestOutput = -1;
+  for (const [model, raw] of Object.entries(modelUsage)) {
+    const output = isRecord(raw) ? num$1(raw.outputTokens) ?? 0 : 0;
+    if (output > bestOutput) {
+      bestOutput = output;
+      best = model;
+    }
+  }
+  return best;
+}
 class ClaudeSession {
   constructor(id, cwd, isNew) {
     this.id = id;
@@ -5612,6 +6067,7 @@ class ClaudeSession {
     try {
       const q = query({ prompt, options });
       let usage;
+      let metrics;
       let completed = false;
       for await (const msg of q) {
         const m = msg;
@@ -5636,12 +6092,32 @@ class ClaudeSession {
           }
         } else if (m.type === "result") {
           usage = m.usage;
+          metrics = {
+            usage: withCost(normalizeUsage("claude", m.usage), num$1(m.total_cost_usd)),
+            modelUsage: isRecord(m.modelUsage) ? m.modelUsage : void 0,
+            numTurns: num$1(m.num_turns),
+            stopReason: typeof m.stop_reason === "string" ? m.stop_reason : void 0,
+            model: primaryModel(m.modelUsage),
+            durationMs: num$1(m.duration_ms),
+            apiDurationMs: num$1(m.duration_api_ms)
+          };
+        } else if (m.type === "system" && m.subtype === "compact_boundary") {
+          const meta = m.compact_metadata ?? {};
+          yield {
+            type: "compact",
+            metrics: {
+              trigger: meta.trigger === "manual" || meta.trigger === "auto" ? meta.trigger : void 0,
+              preTokens: num$1(meta.pre_tokens),
+              postTokens: num$1(meta.post_tokens),
+              durationMs: num$1(meta.duration_ms)
+            }
+          };
         } else if (m.type === "system" && m.subtype === "session_state_changed" && m.state === "idle") {
           completed = true;
-          yield { type: "turn-completed", usage };
+          yield { type: "turn-completed", usage, metrics };
         }
       }
-      if (!completed) yield { type: "turn-completed", usage };
+      if (!completed) yield { type: "turn-completed", usage, metrics };
     } catch (err) {
       if (ctrl.signal.aborted) return;
       yield { type: "error", message: err instanceof Error ? err.message : String(err) };
@@ -5924,7 +6400,11 @@ class CodexSession {
             yield { type: "error", message: item.message };
           }
         } else if (ev.type === "turn.completed") {
-          yield { type: "turn-completed", usage: ev.usage };
+          yield {
+            type: "turn-completed",
+            usage: ev.usage,
+            metrics: { usage: normalizeUsage("codex", ev.usage) }
+          };
         } else if (ev.type === "turn.failed") {
           yield { type: "error", message: ev.error.message };
         } else if (ev.type === "error") {
@@ -6310,7 +6790,14 @@ class OpenCodeSession {
       for (const part of textParts(data.parts)) {
         if (part.type === "text") yield { type: "text", delta: part.text };
       }
-      yield { type: "turn-completed", usage: data.info.tokens };
+      yield {
+        type: "turn-completed",
+        usage: data.info.tokens,
+        metrics: {
+          usage: normalizeUsage("opencode", data.info.tokens),
+          model: typeof data.info.modelID === "string" ? data.info.modelID : void 0
+        }
+      };
     } catch (err) {
       if (this.aborted) return;
       yield { type: "error", message: err instanceof Error ? err.message : String(err) };
@@ -6678,9 +7165,11 @@ class SessionManager {
    * text while sending an expanded prompt to the Agent. Without it, an injected
    * hidden prompt would become the title.
    */
-  async send(sid, prompt, titleSource) {
+  async send(sid, prompt, titleSource, meta = {}) {
     const runId = randomUUID();
     const emitter = this.emitterFor(sid);
+    const telemetry = getTelemetry(this.cwd);
+    const attribution = { specId: meta.specId, trigger: meta.trigger };
     let currentSid = sid;
     const startedAt = Date.now();
     await this.maybeUpdateTitleFromPrompt(currentSid, titleSource ?? prompt).catch(() => {
@@ -6689,18 +7178,57 @@ class SessionManager {
     });
     this.setRunning(sid, true);
     agentLog().info("dispatch start", { sessionId: sid, runId, promptLength: prompt.length });
+    telemetry.record("agent.dispatch", {
+      ...attribution,
+      phase: "start",
+      sessionId: sid,
+      traceId: runId,
+      promptLength: prompt.length
+    });
+    let agentKind;
+    let dispatchError;
     const task = (async () => {
       try {
         const ls = await this.ensureLive(sid);
+        agentKind = ls.kind;
         for await (const ev of ls.session.send(prompt)) {
           if (ev.type === "session-started" && ev.sessionId !== currentSid) {
             const oldSid = currentSid;
             currentSid = ev.sessionId;
             await this.reconcile(oldSid, ev.sessionId);
+          } else if (ev.type === "turn-completed") {
+            const m = ev.metrics ?? {};
+            telemetry.record("agent.turn", {
+              ...attribution,
+              sessionId: currentSid,
+              traceId: runId,
+              agentKind,
+              usage: m.usage,
+              modelUsage: m.modelUsage,
+              numTurns: m.numTurns,
+              stopReason: m.stopReason,
+              model: m.model,
+              durMs: m.durationMs,
+              apiDurMs: m.apiDurationMs
+            });
+          } else if (ev.type === "compact") {
+            telemetry.record("agent.compact", {
+              ...attribution,
+              sessionId: currentSid,
+              traceId: runId,
+              agentKind,
+              // Named apart from the dispatch `trigger` so both survive on the
+              // same line: which action started the run, and what compacted it.
+              compactTrigger: ev.metrics.trigger,
+              preTokens: ev.metrics.preTokens,
+              postTokens: ev.metrics.postTokens,
+              durMs: ev.metrics.durationMs
+            });
           }
           emitter.emit("event", ev);
         }
       } catch (err) {
+        dispatchError = err instanceof Error ? err.message : String(err);
         agentLog().error("dispatch failed", {
           sessionId: currentSid,
           runId,
@@ -6718,6 +7246,17 @@ class SessionManager {
           runId,
           durationMs: Date.now() - startedAt
         });
+        telemetry.record("agent.dispatch", {
+          ...attribution,
+          phase: "end",
+          sessionId: currentSid,
+          traceId: runId,
+          agentKind,
+          promptLength: prompt.length,
+          durMs: Date.now() - startedAt,
+          ok: dispatchError === void 0,
+          errorMessage: dispatchError
+        });
         await this.store.touch(currentSid).catch(() => {
         });
         this.setRunning(currentSid, false);
@@ -8909,6 +9448,7 @@ async function lintFile(path, opts = {}) {
 }
 [...new Set([...SPEC_RULES, ...REVIEW_RULES].map((r) => r.id))];
 async function runLint(opts) {
+  const startedAt = Date.now();
   const cwd = resolve(opts.cwd);
   let targets = [];
   if (opts.all) {
@@ -8978,8 +9518,220 @@ async function runLint(opts) {
 Total: ${errorCount} error(s), ${warnCount} warn(s) across ${reports.length} file(s).
 `);
   }
+  await recordLintRun(cwd, {
+    fileCount: targets.length,
+    errorCount,
+    warnCount,
+    exitCode,
+    durMs: Date.now() - startedAt
+  });
   return { reports, errorCount, warnCount, exitCode };
 }
+async function recordLintRun(cwd, payload) {
+  const root = findProjectRoot(cwd);
+  if (!root) return;
+  const telemetry = getTelemetry(root);
+  telemetry.record("lint.run", payload);
+  await telemetry.flush();
+}
+const UNATTRIBUTED = "(no spec)";
+async function runMetrics(opts) {
+  const dirs = await resolveTargetDirs(opts);
+  if (dirs.length === 0) {
+    process.stderr.write(
+      "no telemetry found — run a dispatch first, or pass --project <id|path> / --all\n"
+    );
+    return { exitCode: 1, summary: emptySummary() };
+  }
+  const summary = emptySummary();
+  for (const dir of dirs) {
+    summary.projects.push(await projectLabel(dir));
+    for (const file of await telemetryFiles(dir)) {
+      summary.files.push(file);
+      await consumeFile(file, opts.since, summary);
+    }
+  }
+  summary.specs.sort((a, b) => b.costUsd - a.costUsd || b.turns - a.turns);
+  if (opts.format === "json") {
+    process.stdout.write(`${JSON.stringify(summary, null, 2)}
+`);
+  } else {
+    process.stdout.write(renderText(summary));
+  }
+  return { exitCode: 0, summary };
+}
+async function resolveTargetDirs(opts) {
+  const metricsDir = resolveMetricsDir();
+  if (opts.all) {
+    if (!existsSync(metricsDir)) return [];
+    const entries = await readdir(metricsDir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => join(metricsDir, e.name));
+  }
+  if (opts.project) {
+    const dir2 = isAbsolute(opts.project) ? resolveProjectMetricsDir(opts.project) : join(metricsDir, opts.project);
+    return existsSync(dir2) ? [dir2] : [];
+  }
+  const root = findProjectRoot(opts.cwd);
+  if (!root) return [];
+  const dir = resolveProjectMetricsDir(root);
+  return existsSync(dir) ? [dir] : [];
+}
+async function telemetryFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const entries = await readdir(dir);
+  const archives = entries.filter((name2) => name2.startsWith(`${TELEMETRY_FILE_NAME}.`)).sort((a, b) => Number(b.split(".").pop()) - Number(a.split(".").pop())).map((name2) => join(dir, name2));
+  const current = join(dir, TELEMETRY_FILE_NAME);
+  return existsSync(current) ? [...archives, current] : archives;
+}
+async function projectLabel(dir) {
+  try {
+    const raw = await readFile(join(dir, PROJECT_META_FILE_NAME), "utf8");
+    const meta = JSON.parse(raw);
+    return meta.path ? `${meta.id ?? "?"} (${meta.path})` : meta.id ?? dir;
+  } catch {
+    return dir;
+  }
+}
+async function consumeFile(file, since, out) {
+  let raw;
+  try {
+    raw = await readFile(file, "utf8");
+  } catch {
+    return;
+  }
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    let ev;
+    try {
+      ev = JSON.parse(line);
+    } catch {
+      out.skipped += 1;
+      continue;
+    }
+    const ts = typeof ev.ts === "string" ? ev.ts : "";
+    if (since && ts.slice(0, 10) < since) continue;
+    out.lines += 1;
+    const event = typeof ev.event === "string" ? ev.event : "unknown";
+    out.eventCounts[event] = (out.eventCounts[event] ?? 0) + 1;
+    applyEvent(ev, event, out);
+  }
+}
+function applyEvent(ev, event, out) {
+  if (!event.startsWith("agent.")) return;
+  const bucket = bucketFor(out, typeof ev.specId === "string" ? ev.specId : UNATTRIBUTED);
+  if (event === "agent.dispatch") {
+    if (ev.phase !== "end") return;
+    bucket.dispatches += 1;
+    out.totals.dispatches += 1;
+    if (ev.ok === false) {
+      bucket.failures += 1;
+      out.totals.failures += 1;
+    }
+    return;
+  }
+  if (event === "agent.compact") {
+    bucket.compactions += 1;
+    out.totals.compactions += 1;
+    return;
+  }
+  if (event !== "agent.turn") return;
+  bucket.turns += 1;
+  out.totals.turns += 1;
+  const durMs = num(ev.durMs);
+  bucket.agentDurMs += durMs;
+  out.totals.agentDurMs += durMs;
+  const usage = ev.usage ?? {};
+  for (const key of [
+    "inputTokens",
+    "cacheReadTokens",
+    "cacheCreateTokens",
+    "outputTokens"
+  ]) {
+    bucket[key] += num(usage[key]);
+    out.totals[key] += num(usage[key]);
+  }
+  bucket.costUsd += num(usage.costUsd);
+  out.totals.costUsd += num(usage.costUsd);
+}
+function bucketFor(out, specId) {
+  let bucket = out.specs.find((s) => s.specId === specId);
+  if (!bucket) {
+    bucket = {
+      specId,
+      dispatches: 0,
+      turns: 0,
+      compactions: 0,
+      inputTokens: 0,
+      cacheReadTokens: 0,
+      cacheCreateTokens: 0,
+      outputTokens: 0,
+      costUsd: 0,
+      agentDurMs: 0,
+      failures: 0,
+      stages: []
+    };
+    out.specs.push(bucket);
+  }
+  return bucket;
+}
+function num(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function emptySummary() {
+  return {
+    projects: [],
+    files: [],
+    lines: 0,
+    skipped: 0,
+    eventCounts: {},
+    totals: {
+      dispatches: 0,
+      turns: 0,
+      compactions: 0,
+      inputTokens: 0,
+      cacheReadTokens: 0,
+      cacheCreateTokens: 0,
+      outputTokens: 0,
+      costUsd: 0,
+      agentDurMs: 0,
+      failures: 0
+    },
+    specs: []
+  };
+}
+const SPEC_ROW_LIMIT = 20;
+function renderText(s) {
+  const lines = [];
+  lines.push(`projects: ${s.projects.join(", ") || "(none)"}`);
+  lines.push(`events:   ${s.lines}${s.skipped ? ` (${s.skipped} unparseable line(s))` : ""}`);
+  const kinds = Object.entries(s.eventCounts).sort((a, b) => b[1] - a[1]);
+  if (kinds.length) {
+    lines.push(`by kind:  ${kinds.map(([k, n]) => `${k}=${n}`).join("  ")}`);
+  }
+  const t = s.totals;
+  lines.push("");
+  lines.push(
+    `total: ${t.dispatches} dispatch(es), ${t.turns} turn(s), ${t.failures} failure(s), ${t.compactions} compaction(s)`
+  );
+  lines.push(
+    `tokens: in=${t.inputTokens} cacheRead=${t.cacheReadTokens} cacheWrite=${t.cacheCreateTokens} out=${t.outputTokens}`
+  );
+  lines.push(`cost: $${t.costUsd.toFixed(4)}   agent time: ${(t.agentDurMs / 1e3).toFixed(1)}s`);
+  if (s.specs.length) {
+    lines.push("");
+    lines.push("per spec (by cost):");
+    for (const spec of s.specs.slice(0, SPEC_ROW_LIMIT)) {
+      lines.push(
+        `  ${spec.specId.padEnd(40)} $${spec.costUsd.toFixed(4).padStart(9)}  ${String(spec.dispatches).padStart(3)} disp  ${String(spec.turns).padStart(3)} turn  in=${spec.inputTokens} cacheRead=${spec.cacheReadTokens} out=${spec.outputTokens}`
+      );
+    }
+    if (s.specs.length > SPEC_ROW_LIMIT) {
+      lines.push(`  … ${s.specs.length - SPEC_ROW_LIMIT} more spec(s) not shown (use --format json)`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
 const program = new Command();
 program.name("yorz").description("YorZ CLI — manage the yorz-spec skill.").version(pkg.version);
 const uninstallCmd = program.command("uninstall").description("Remove YorZ artifacts (skills, ...).");
@@ -9043,6 +9795,18 @@ program.command("lint [paths...]").description("Lint spec.md / review.md files f
     if (result.exitCode !== 0) process.exit(result.exitCode);
   }
 );
+program.command("metrics").description("Summarize collected telemetry (token / cost / duration per spec).").option("--format <format>", "output format: text | json", "text").option("--project <idOrPath>", "project id or absolute path (default: project of --cwd)").option("--all", "aggregate across every project that has telemetry", false).option("--since <date>", "only events on or after this local date (YYYY-MM-DD)").option("--cwd <path>", "working directory (default: process.cwd())").action(
+  async (opts) => {
+    const result = await runMetrics({
+      cwd: opts.cwd ?? process.cwd(),
+      format: opts.format === "json" ? "json" : "text",
+      project: opts.project,
+      all: opts.all === true,
+      since: opts.since
+    });
+    if (result.exitCode !== 0) process.exit(result.exitCode);
+  }
+);
 const serveCmd = program.command("serve").description("Start the YorZ Service (HTTP + SSE + static GUI; multi-project).").option("-p, --port <port>", "port to listen on", "7423").option(
   "--host <address>",
   "bind address (default: 127.0.0.1; the service runs shell commands, so exposing it to the network is opt-in)"