@yorz/cli 0.7.0 → 0.8.0

package/dist/cli/index.js

@@ -2,7 +2,7 @@
 import { homedir, platform } from "node:os";
 import { Command, Option } from "commander";
 import { stat, mkdir, writeFile, rename, readFile, rm, access, readdir, appendFile, copyFile } from "node:fs/promises";
-import { join, isAbsolute, resolve, basename as basename$1, dirname, extname, sep, relative, normalize } from "node:path";
+import { join, isAbsolute, resolve, basename as basename$1, dirname, extname, relative, sep, normalize } from "node:path";
 import { createHash, randomUUID, randomBytes } from "node:crypto";
 import { existsSync, openSync, closeSync, statSync, readSync, mkdirSync, watch, createReadStream } from "node:fs";
 import { spawn, execFile, execFileSync } from "node:child_process";
@@ -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.0";
+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,
@@ -54,6 +54,93 @@ const pkg = {
   dependencies,
   devDependencies
 };
+const HIDDEN_PROMPT_OPEN = "<!-- yorz:hidden -->";
+const HIDDEN_PROMPT_CLOSE = "<!-- /yorz:hidden -->";
+const SLASH_NAME_RE$1 = /^\/([\w-]+)(?:\s|$)/;
+function matchCustomInstruction(prompt, instructions) {
+  const matched = SLASH_NAME_RE$1.exec(prompt.trim());
+  if (!matched) return null;
+  const name2 = matched[1];
+  return instructions.find((item) => item.name === name2) ?? null;
+}
+function wrapHiddenPrompt(hidden, original) {
+  const body = hidden.trim();
+  if (!body) return original;
+  return [HIDDEN_PROMPT_OPEN, body, HIDDEN_PROMPT_CLOSE, original].join("\n");
+}
+function appendHiddenPrompt(original, hidden) {
+  const body = hidden.trim();
+  if (!body) return original;
+  return [original, "", HIDDEN_PROMPT_OPEN, body, HIDDEN_PROMPT_CLOSE].join("\n");
+}
+function normalizeCustomInstructions(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of value) {
+    if (!item || typeof item !== "object") continue;
+    const obj = item;
+    const id = typeof obj.id === "string" ? obj.id.trim() : "";
+    const name2 = typeof obj.name === "string" ? obj.name.trim().replace(/^\/+/, "") : "";
+    if (!id || !name2 || seen.has(id) || !/^[\w-]+$/.test(name2)) continue;
+    seen.add(id);
+    out.push({
+      id,
+      name: name2,
+      description: typeof obj.description === "string" ? obj.description : "",
+      // Fall back to the pre-rename `systemPrompt` so existing configs keep
+      // working; the next save rewrites them under the new key.
+      hiddenPrompt: typeof obj.hiddenPrompt === "string" ? obj.hiddenPrompt : typeof obj.systemPrompt === "string" ? obj.systemPrompt : "",
+      prefill: typeof obj.prefill === "string" ? obj.prefill : "",
+      createdAt: typeof obj.createdAt === "number" && obj.createdAt > 0 ? obj.createdAt : 0
+    });
+  }
+  return out;
+}
+function parseCustomInstructions(value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) return { error: "customInstructions must be an array" };
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, item] of value.entries()) {
+    if (!item || typeof item !== "object") {
+      return { error: `customInstructions.${index} must be an object` };
+    }
+    const obj = item;
+    const id = typeof obj.id === "string" ? obj.id.trim() : "";
+    const name2 = typeof obj.name === "string" ? obj.name.trim().replace(/^\/+/, "") : "";
+    if (!id) return { error: `customInstructions.${index}.id required` };
+    if (!name2 || !/^[\w-]+$/.test(name2)) {
+      return {
+        error: `customInstructions.${index}.name must use letters, numbers, underscores, or hyphens`
+      };
+    }
+    if (seen.has(id)) return { error: `duplicate custom instruction id: ${id}` };
+    seen.add(id);
+    const description2 = obj.description;
+    const hiddenPrompt = obj.hiddenPrompt ?? obj.systemPrompt;
+    const prefill = obj.prefill;
+    const createdAt = obj.createdAt;
+    if (typeof description2 !== "string") {
+      return { error: `customInstructions.${index}.description must be a string` };
+    }
+    if (typeof hiddenPrompt !== "string") {
+      return { error: `customInstructions.${index}.hiddenPrompt must be a string` };
+    }
+    if (typeof prefill !== "string") {
+      return { error: `customInstructions.${index}.prefill must be a string` };
+    }
+    if (typeof createdAt !== "number" || createdAt <= 0) {
+      return { error: `customInstructions.${index}.createdAt must be a positive number` };
+    }
+    out.push({ id, name: name2, description: description2, hiddenPrompt, prefill, createdAt });
+  }
+  return out;
+}
+function mergeCustomInstructions(project, global) {
+  const names = new Set(project.map((item) => item.name));
+  return [...project, ...global.filter((item) => !names.has(item.name))];
+}
 const CURRENT_VERSION$1 = 1;
 const DEFAULT_GLOBAL_AGENT = { defaultKind: "claude" };
 const DEFAULT_NOTIFICATIONS = {
@@ -233,30 +320,6 @@ function normalizeAppearance(value) {
     language: isLanguage(language) ? language : DEFAULT_APPEARANCE.language
   };
 }
-function normalizeCustomInstructions(value) {
-  if (!Array.isArray(value)) return [];
-  const out = [];
-  const seen = /* @__PURE__ */ new Set();
-  for (const item of value) {
-    if (!item || typeof item !== "object") continue;
-    const obj = item;
-    const id = typeof obj.id === "string" ? obj.id.trim() : "";
-    const name2 = typeof obj.name === "string" ? obj.name.trim().replace(/^\/+/, "") : "";
-    if (!id || !name2 || seen.has(id) || !/^[\w-]+$/.test(name2)) continue;
-    seen.add(id);
-    out.push({
-      id,
-      name: name2,
-      description: typeof obj.description === "string" ? obj.description : "",
-      // Fall back to the pre-rename `systemPrompt` so existing configs keep
-      // working; the next save rewrites them under the new key.
-      hiddenPrompt: typeof obj.hiddenPrompt === "string" ? obj.hiddenPrompt : typeof obj.systemPrompt === "string" ? obj.systemPrompt : "",
-      prefill: typeof obj.prefill === "string" ? obj.prefill : "",
-      createdAt: typeof obj.createdAt === "number" && obj.createdAt > 0 ? obj.createdAt : 0
-    });
-  }
-  return out;
-}
 function isThemeMode(value) {
   return value === "system" || value === "light" || value === "dark";
 }
@@ -1136,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) => {
@@ -1166,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);
       });
@@ -1302,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 });
@@ -1316,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) => {
@@ -1347,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) => {
@@ -1604,25 +1888,6 @@ function parseAnnotateBody(body) {
   if (note.length > 2e3) return { error: "note too long (max 2000)" };
   return { sectionPath, quote, note };
 }
-const HIDDEN_PROMPT_OPEN = "<!-- yorz:hidden -->";
-const HIDDEN_PROMPT_CLOSE = "<!-- /yorz:hidden -->";
-const SLASH_NAME_RE$1 = /^\/([\w-]+)(?:\s|$)/;
-function matchCustomInstruction(prompt, instructions) {
-  const matched = SLASH_NAME_RE$1.exec(prompt.trim());
-  if (!matched) return null;
-  const name2 = matched[1];
-  return instructions.find((item) => item.name === name2) ?? null;
-}
-function wrapHiddenPrompt(hidden, original) {
-  const body = hidden.trim();
-  if (!body) return original;
-  return [HIDDEN_PROMPT_OPEN, body, HIDDEN_PROMPT_CLOSE, original].join("\n");
-}
-function appendHiddenPrompt(original, hidden) {
-  const body = hidden.trim();
-  if (!body) return original;
-  return [original, "", HIDDEN_PROMPT_OPEN, body, HIDDEN_PROMPT_CLOSE].join("\n");
-}
 const CHAT_DEBUG_DIR_REL = ".yorz/tmp/debug";
 const CHAT_DEBUG_RETENTION_MS = 7 * 24 * 60 * 60 * 1e3;
 const CHAT_DEBUG_CLEANUP_INTERVAL_MS = 60 * 60 * 1e3;
@@ -1690,6 +1955,113 @@ function formatDebugTimestamp(date) {
     pad(date.getSeconds())
   ].join("");
 }
+const CURRENT_VERSION = 1;
+const DEFAULT_SPECS_DIR = ".yorz/specs";
+function defaultProjectConfig() {
+  return {
+    version: CURRENT_VERSION,
+    agent: { kind: "inherit" },
+    specsDir: DEFAULT_SPECS_DIR,
+    commands: [],
+    customInstructions: []
+  };
+}
+function configPath(cwd) {
+  return join(cwd, ".yorz", "config.json");
+}
+async function loadProjectConfig(cwd) {
+  const fp = configPath(cwd);
+  if (!existsSync(fp)) return defaultProjectConfig();
+  let raw;
+  try {
+    raw = await readFile(fp, "utf8");
+  } catch {
+    return defaultProjectConfig();
+  }
+  if (!raw.trim()) return defaultProjectConfig();
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return defaultProjectConfig();
+  }
+  return normalizeConfig(parsed);
+}
+async function saveProjectConfig(cwd, cfg) {
+  const fp = configPath(cwd);
+  await mkdir(dirname(fp), { recursive: true });
+  const normalized = normalizeConfig(cfg);
+  const body = `${JSON.stringify(normalized, null, 2)}
+`;
+  const tmp = `${fp}.tmp-${process.pid}-${Date.now().toString(36)}`;
+  await writeFile(tmp, body, "utf8");
+  await rename(tmp, fp);
+}
+function resolveSpecsDir(cwd, cfg) {
+  const root = resolve(cwd);
+  const raw = (cfg.specsDir || DEFAULT_SPECS_DIR).trim() || DEFAULT_SPECS_DIR;
+  const abs = isAbsolute(raw) ? resolve(raw) : resolve(root, raw);
+  const rel = relative(root, abs);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error(`specsDir must stay within the project root: ${raw}`);
+  }
+  return abs;
+}
+async function ensureSpecsDirExists(absSpecsDir) {
+  await mkdir(absSpecsDir, { recursive: true });
+}
+function normalizeConfig(value) {
+  if (!value || typeof value !== "object") return defaultProjectConfig();
+  const obj = value;
+  const agent = normalizeAgent(obj.agent);
+  const specsDir = normalizeSpecsDir(obj.specsDir);
+  const commands = normalizeCommands(obj.commands);
+  const customInstructions = normalizeCustomInstructions(obj.customInstructions);
+  return { version: CURRENT_VERSION, agent, specsDir, commands, customInstructions };
+}
+function normalizeCommands(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of value) {
+    if (!item || typeof item !== "object") continue;
+    const obj = item;
+    const id = typeof obj.id === "string" ? obj.id.trim() : "";
+    const name2 = typeof obj.name === "string" ? obj.name.trim() : "";
+    const cli = typeof obj.cli === "string" ? obj.cli.trim() : "";
+    if (!id || !name2 || !cli || seen.has(id)) continue;
+    seen.add(id);
+    const createdAt = typeof obj.createdAt === "number" && obj.createdAt > 0 ? obj.createdAt : 0;
+    out.push({ id, name: name2, cli, createdAt });
+  }
+  return out;
+}
+function normalizeAgent(value) {
+  if (typeof value === "string") {
+    if (value === "opencode") return { kind: "opencode" };
+    if (value === "codex") return { kind: "codex" };
+    return { kind: "claude" };
+  }
+  if (!value || typeof value !== "object") return { kind: "claude" };
+  const obj = value;
+  const kind = obj.kind;
+  if (kind === "inherit") return { kind: "inherit" };
+  if (kind === "opencode") return { kind: "opencode" };
+  if (kind === "codex") return { kind: "codex" };
+  if (kind === "custom") {
+    const cmd = typeof obj.cmd === "string" ? obj.cmd.trim() : "";
+    if (!cmd) return { kind: "claude" };
+    const args = Array.isArray(obj.args) ? obj.args.filter((a) => typeof a === "string") : [];
+    return { kind: "custom", cmd, args };
+  }
+  return { kind: "claude" };
+}
+function normalizeSpecsDir(value) {
+  if (typeof value !== "string") return DEFAULT_SPECS_DIR;
+  const trimmed = value.trim();
+  if (!trimmed) return DEFAULT_SPECS_DIR;
+  return trimmed;
+}
 const SLASH_NAME_RE = /^\/([\w-]+)(?:\s|$)/;
 const SPEC_COMMAND_RE = /^\/yorz-spec(?:\s|$)/;
 function isSlashCommand(prompt) {
@@ -1739,6 +2111,13 @@ function resolveChatPrompt(prompt, instructions, opts = {}) {
   }
   return { prompt: buildUnknownCommandPrompt(original, hit), builtin: null };
 }
+async function loadCustomInstructions(projectPath) {
+  const [project, global] = await Promise.all([
+    loadProjectConfig(projectPath).then((cfg) => cfg.customInstructions).catch(() => []),
+    loadGlobalConfig().then((cfg) => cfg.customInstructions).catch(() => [])
+  ]);
+  return mergeCustomInstructions(project, global);
+}
 const KINDS = ["claude", "codex", "opencode"];
 const DRAFT_ID_RE = /^[a-zA-Z0-9-]{1,64}$/;
 function buildChatPrompt(prompt, draftId, attachments) {
@@ -1827,7 +2206,7 @@ function createSessionsRoutes(resolveProject) {
     }
     const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
     if (!prompt) return c.json({ error: "prompt required" }, 400);
-    const instructions = isSlashCommand(prompt) ? await loadGlobalConfig().then((cfg) => cfg.customInstructions).catch(() => []) : [];
+    const instructions = isSlashCommand(prompt) ? await loadCustomInstructions(p.path) : [];
     const resolved = resolveChatPrompt(prompt, instructions, {
       specsDirRelative: p.specsDirRelative
     });
@@ -1844,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) => {
@@ -1924,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");
     }
@@ -1944,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 };
   }
 }
@@ -2018,7 +2414,7 @@ async function commit(cwd, opts) {
   const extraPaths = renamed.map((r) => r.renamedFrom);
   const allPaths = [...opts.paths, ...extraPaths];
   await runGit(cwd, ["add", "--", ...allPaths]);
-  await runGit(cwd, ["commit", "-m", message, "--", ...allPaths]);
+  await runGit(cwd, ["commit", "-m", message]);
   const { stdout } = await runGit(cwd, ["rev-parse", "HEAD"]);
   return { commit: stdout.trim() };
 }
@@ -2040,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");
@@ -2080,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) => {
@@ -2098,68 +2613,6 @@ 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) => {
-    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 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);
-    } catch (err) {
-      if (err instanceof GitError) return c.json({ error: err.message }, 400);
-      throw err;
-    }
-  });
-  app.post("/projects/:projectId/specs/:id/discard", 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 obj = body && typeof body === "object" ? body : {};
-    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);
-    try {
-      await discard(p.path, { 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/stash", async (c) => {
     const p = await need(c);
     if (p instanceof Response) return p;
@@ -2204,6 +2657,126 @@ function buildGitOpsPrompt(action, specId, specRel) {
 `;
   }
 }
+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;
+    try {
+      return c.json({ changes: await listChanges(p.path) });
+    } catch (err) {
+      if (err instanceof GitError) return c.json({ error: err.message }, 400);
+      throw err;
+    }
+  });
+  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 });
+      return c.json({ ok: true });
+    } catch (err) {
+      if (err instanceof GitError) return c.json({ error: err.message }, 400);
+      throw err;
+    }
+  });
+  app.post("/projects/:projectId/git/push", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    try {
+      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;
+    }
+  });
+  app.post("/projects/:projectId/git/pull", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    try {
+      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;
+    }
+  });
+  return app;
+}
 const sseLog = () => getLogger().child("sse");
 const HEARTBEAT_INTERVAL_MS = 5e3;
 function attachHeartbeat(stream, intervalMs = HEARTBEAT_INTERVAL_MS) {
@@ -2395,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]);
@@ -2435,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 });
@@ -2593,111 +3168,6 @@ function createProjectRoutes(registry, worktreeManager) {
   });
   return app;
 }
-const CURRENT_VERSION = 1;
-const DEFAULT_SPECS_DIR = ".yorz/specs";
-function defaultProjectConfig() {
-  return {
-    version: CURRENT_VERSION,
-    agent: { kind: "inherit" },
-    specsDir: DEFAULT_SPECS_DIR,
-    commands: []
-  };
-}
-function configPath(cwd) {
-  return join(cwd, ".yorz", "config.json");
-}
-async function loadProjectConfig(cwd) {
-  const fp = configPath(cwd);
-  if (!existsSync(fp)) return defaultProjectConfig();
-  let raw;
-  try {
-    raw = await readFile(fp, "utf8");
-  } catch {
-    return defaultProjectConfig();
-  }
-  if (!raw.trim()) return defaultProjectConfig();
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return defaultProjectConfig();
-  }
-  return normalizeConfig(parsed);
-}
-async function saveProjectConfig(cwd, cfg) {
-  const fp = configPath(cwd);
-  await mkdir(dirname(fp), { recursive: true });
-  const normalized = normalizeConfig(cfg);
-  const body = `${JSON.stringify(normalized, null, 2)}
-`;
-  const tmp = `${fp}.tmp-${process.pid}-${Date.now().toString(36)}`;
-  await writeFile(tmp, body, "utf8");
-  await rename(tmp, fp);
-}
-function resolveSpecsDir(cwd, cfg) {
-  const root = resolve(cwd);
-  const raw = (cfg.specsDir || DEFAULT_SPECS_DIR).trim() || DEFAULT_SPECS_DIR;
-  const abs = isAbsolute(raw) ? resolve(raw) : resolve(root, raw);
-  const rel = relative(root, abs);
-  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
-    throw new Error(`specsDir must stay within the project root: ${raw}`);
-  }
-  return abs;
-}
-async function ensureSpecsDirExists(absSpecsDir) {
-  await mkdir(absSpecsDir, { recursive: true });
-}
-function normalizeConfig(value) {
-  if (!value || typeof value !== "object") return defaultProjectConfig();
-  const obj = value;
-  const agent = normalizeAgent(obj.agent);
-  const specsDir = normalizeSpecsDir(obj.specsDir);
-  const commands = normalizeCommands(obj.commands);
-  return { version: CURRENT_VERSION, agent, specsDir, commands };
-}
-function normalizeCommands(value) {
-  if (!Array.isArray(value)) return [];
-  const out = [];
-  const seen = /* @__PURE__ */ new Set();
-  for (const item of value) {
-    if (!item || typeof item !== "object") continue;
-    const obj = item;
-    const id = typeof obj.id === "string" ? obj.id.trim() : "";
-    const name2 = typeof obj.name === "string" ? obj.name.trim() : "";
-    const cli = typeof obj.cli === "string" ? obj.cli.trim() : "";
-    if (!id || !name2 || !cli || seen.has(id)) continue;
-    seen.add(id);
-    const createdAt = typeof obj.createdAt === "number" && obj.createdAt > 0 ? obj.createdAt : 0;
-    out.push({ id, name: name2, cli, createdAt });
-  }
-  return out;
-}
-function normalizeAgent(value) {
-  if (typeof value === "string") {
-    if (value === "opencode") return { kind: "opencode" };
-    if (value === "codex") return { kind: "codex" };
-    return { kind: "claude" };
-  }
-  if (!value || typeof value !== "object") return { kind: "claude" };
-  const obj = value;
-  const kind = obj.kind;
-  if (kind === "inherit") return { kind: "inherit" };
-  if (kind === "opencode") return { kind: "opencode" };
-  if (kind === "codex") return { kind: "codex" };
-  if (kind === "custom") {
-    const cmd = typeof obj.cmd === "string" ? obj.cmd.trim() : "";
-    if (!cmd) return { kind: "claude" };
-    const args = Array.isArray(obj.args) ? obj.args.filter((a) => typeof a === "string") : [];
-    return { kind: "custom", cmd, args };
-  }
-  return { kind: "claude" };
-}
-function normalizeSpecsDir(value) {
-  if (typeof value !== "string") return DEFAULT_SPECS_DIR;
-  const trimmed = value.trim();
-  if (!trimmed) return DEFAULT_SPECS_DIR;
-  return trimmed;
-}
 function createProjectConfigRoutes(registry) {
   const app = new Hono();
   app.get("/projects/:projectId/config", async (c) => {
@@ -2724,7 +3194,8 @@ function createProjectConfigRoutes(registry) {
       version: 1,
       agent: parsed.agent,
       specsDir: parsed.specsDir,
-      commands: current.commands
+      commands: current.commands,
+      customInstructions: current.customInstructions
     };
     let absSpecsDir;
     try {
@@ -2745,6 +3216,34 @@ function createProjectConfigRoutes(registry) {
     await registry.reload(id);
     return c.json({ ok: true, config: cfg });
   });
+  app.get("/projects/:projectId/custom-instructions", async (c) => {
+    const id = c.req.param("projectId");
+    const entry = await registry.findEntry(id);
+    if (!entry) return c.json({ error: "project not found" }, 404);
+    const cfg = await loadProjectConfig(entry.path);
+    return c.json({ customInstructions: cfg.customInstructions });
+  });
+  app.put("/projects/:projectId/custom-instructions", async (c) => {
+    const id = c.req.param("projectId");
+    const entry = await registry.findEntry(id);
+    if (!entry) return c.json({ error: "project not found" }, 404);
+    let raw;
+    try {
+      raw = await c.req.json();
+    } catch {
+      return c.json({ error: "invalid JSON body" }, 400);
+    }
+    if (!raw || typeof raw !== "object") return c.json({ error: "body must be an object" }, 400);
+    const parsed = parseCustomInstructions(raw.customInstructions);
+    if ("error" in parsed) return c.json({ error: parsed.error }, 400);
+    const current = await loadProjectConfig(entry.path);
+    try {
+      await saveProjectConfig(entry.path, { ...current, customInstructions: parsed });
+    } catch (err) {
+      return c.json({ error: err.message }, 500);
+    }
+    return c.json({ ok: true, customInstructions: parsed });
+  });
   return app;
 }
 function parseBody$1(value) {
@@ -3062,46 +3561,6 @@ function parseAppearance(value) {
   if (!isLanguage(language)) return { error: "appearance.language must be zh-CN | en" };
   return { themeMode, themeName, language };
 }
-function parseCustomInstructions(value) {
-  if (value === void 0) return [];
-  if (!Array.isArray(value)) return { error: "customInstructions must be an array" };
-  const out = [];
-  const seen = /* @__PURE__ */ new Set();
-  for (const [index, item] of value.entries()) {
-    if (!item || typeof item !== "object") {
-      return { error: `customInstructions.${index} must be an object` };
-    }
-    const obj = item;
-    const id = typeof obj.id === "string" ? obj.id.trim() : "";
-    const name2 = typeof obj.name === "string" ? obj.name.trim().replace(/^\/+/, "") : "";
-    if (!id) return { error: `customInstructions.${index}.id required` };
-    if (!name2 || !/^[\w-]+$/.test(name2)) {
-      return {
-        error: `customInstructions.${index}.name must use letters, numbers, underscores, or hyphens`
-      };
-    }
-    if (seen.has(id)) return { error: `duplicate custom instruction id: ${id}` };
-    seen.add(id);
-    const description2 = obj.description;
-    const hiddenPrompt = obj.hiddenPrompt ?? obj.systemPrompt;
-    const prefill = obj.prefill;
-    const createdAt = obj.createdAt;
-    if (typeof description2 !== "string") {
-      return { error: `customInstructions.${index}.description must be a string` };
-    }
-    if (typeof hiddenPrompt !== "string") {
-      return { error: `customInstructions.${index}.hiddenPrompt must be a string` };
-    }
-    if (typeof prefill !== "string") {
-      return { error: `customInstructions.${index}.prefill must be a string` };
-    }
-    if (typeof createdAt !== "number" || createdAt <= 0) {
-      return { error: `customInstructions.${index}.createdAt must be a positive number` };
-    }
-    out.push({ id, name: name2, description: description2, hiddenPrompt, prefill, createdAt });
-  }
-  return out;
-}
 function createSpecDraftsRoutes(resolveProject) {
   const app = new Hono();
   const need = async (c) => {
@@ -3944,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;
@@ -4766,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] ?? [];
@@ -4836,7 +5304,7 @@ _暂无_
     "---",
     "stage: plan",
     "last_action: 由 worktree 合并冲突自动生成",
-    `updated_at: '${nowStamp}'`,
+    `updated_at: '${nowStamp2}'`,
     `summary: 解决 ${branch} 合并到主项目时产生的 ${report.files.length} 个冲突文件`,
     "---",
     ""
@@ -4892,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 }
       );
     }
   });
@@ -4905,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));
@@ -5378,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();
@@ -5388,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() {
@@ -5481,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();
   }
@@ -5544,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;
@@ -5570,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;
@@ -5594,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) };
@@ -5882,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") {
@@ -6268,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) };
@@ -6636,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(() => {
@@ -6647,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,
@@ -6676,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);
@@ -8867,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) {
@@ -8936,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, ...).");
@@ -9001,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)"