@yorz/cli 0.4.2 → 0.5.0

package/dist/cli/index.js

@@ -2,7 +2,7 @@
 import { homedir, platform, networkInterfaces } from "node:os";
 import { Command, Option } from "commander";
 import { stat, readFile, writeFile, rm, mkdir, access, rename, readdir, appendFile, copyFile } from "node:fs/promises";
-import { join, dirname, extname, resolve, sep, isAbsolute, basename as basename$1, relative, normalize } from "node:path";
+import { join, dirname, extname, isAbsolute, resolve, basename as basename$1, sep, relative, normalize } from "node:path";
 import { createHash, randomUUID, randomBytes } from "node:crypto";
 import { spawn, execFile } from "node:child_process";
 import { existsSync, openSync, closeSync, statSync, readSync, mkdirSync, watch, createReadStream } from "node:fs";
@@ -21,9 +21,37 @@ import { Codex } from "@openai/codex-sdk";
 import { createOpencode } from "@opencode-ai/sdk";
 import { createInterface as createInterface$1 } from "node:readline/promises";
 import MarkdownIt from "markdown-it";
-const version = "0.4.2";
+const name = "@yorz/cli";
+const version = "0.5.0";
+const type = "module";
+const description = "";
+const bin = { "yorz": "./dist/cli/index.js" };
+const engines = { "node": ">=20" };
+const files = ["dist", "README.md"];
+const keywords = ["ai", "agent", "spec-driven", "decision-os", "claude-code", "opencode", "workflow", "cli"];
+const license = "LGPL-3.0-or-later";
+const repository = { "type": "git", "url": "git+https://github.com/hughfenghen/YorZ.git" };
+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": "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 devDependencies = { "@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 = {
-  version
+  name,
+  version,
+  type,
+  description,
+  bin,
+  engines,
+  files,
+  keywords,
+  license,
+  repository,
+  homepage,
+  publishConfig,
+  scripts,
+  dependencies,
+  devDependencies
 };
 const claudeAdapter = {
   name: "claude",
@@ -51,11 +79,11 @@ const ADAPTERS = {
   opencode: opencodeAdapter,
   codex: codexAdapter
 };
-function getAdapter(name) {
-  if (name in ADAPTERS) return ADAPTERS[name];
-  throw new Error(`Unknown agent: ${name}. Supported: ${Object.keys(ADAPTERS).join(", ")}`);
+function getAdapter(name2) {
+  if (name2 in ADAPTERS) return ADAPTERS[name2];
+  throw new Error(`Unknown agent: ${name2}. Supported: ${Object.keys(ADAPTERS).join(", ")}`);
 }
-const __vite_glob_0_0 = '---\nname: yorz-debug\ndescription: 以资深工程师的调试纪律定位并修复疑难 bug——假设→取证→验证的证据闭环，靠 debug.md 活文档与 git 快照兜住污染。\n---\n\n# YorZ Debug 深度调试 Skill\n\n指导 Agent 以**资深工程师的调试纪律**逐步逼近疑难 bug 的根因：不凭猜测改代码，坚持「假设 → 取证 → 验证 → 缩小范围 → 再假设」的证据闭环。调试过程赋予更大的自由度（临时改代码、Mock 数据、加日志、建临时验证入口），同时用 `debug.md` 活文档 + `git stash create` 快照兜住"污染性改动不进入最终提交"。\n\n> 本 skill **不复用** yorz-spec 的 plan/tasks/execute 状态机。真相以 `debug.md` 为单一载体；Agent 持续推进直至需要用户回传证据（人在环路），或根因确认并收尾。\n\n## 何时进入本 skill\n\n- **独立触发（无需 spec / UI）**：用户在 Agent 对话中直接点名「用 yorz-debug 调这个 bug」。此时可能没有任何 spec 上下文——按下方「无 spec 场景」处理 `debug.md` 落点。\n- **追加任务勾选 Debug**：用户在 SpecDetail 追加 `fix` 任务时勾选「Debug 模式」，后端 prompt 指向本 skill。\n- **重入**：spec 目录已存在 `status: debugging` 的 `debug.md`（有未收尾记录块），run/append 路由自动切到本 skill。此时**不新建记录块**，定位活跃记录块（frontmatter `active: NNN`）续跑。\n\n## 输入约定\n\n- `spec_dir`（**可选**）：spec 目录路径（含 `spec.md`）。给出时 `debug.md` 建在此目录，与 `spec.md` 同级。\n- 待调试 bug 的描述：来自追加任务行 / 用户 prompt。\n- 运行服务上下文（**可选**）：由 YorZ Service 注入的当前项目运行中命令服务列表，包含 `runId`、`name`、`cli`、`pid`、`startedAt`、`logFile` 等字段。\n\n### debug.md 落点\n\n- **有 spec 上下文**：`debug.md` 落 `spec_dir`（与 `spec.md` 同级）。\n- **无 spec 场景（独立触发）**：没有 `spec_dir` 时，`debug.md` 落**当前工作目录**；若用户在 prompt 中显式指定了路径，则以用户指定为准。其余多记录模型、快照、脚手架、收尾流程与有 spec 时**完全一致**。\n\n## debug.md：多记录活文档\n\n**一个 `debug.md` 承载同一 spec 生命周期内的多次调试**（某次收尾后又发现新 bug，就追加下一条记录，不覆盖历史）。它同时是：调试活文档、**Debug 模式的持久化标记**（存在未收尾记录 = 处于 Debug 模式）、脚手架是否清理干净的守卫。\n\n### 文件级 frontmatter\n\n```yaml\n---\nstatus: debugging # debugging（存在未收尾记录）| resolved（全部记录已收尾）\nactive: 2 # 当前活跃记录编号；resolved 时留空\nupdated_at: \'2026-07-19 15:54:37\' # 本地秒级字符串\n---\n```\n\n### 正文按「记录块」组织\n\n每次进入 Debug **在文末追加**一个记录块，编号 `NNN` 从 1 递增、**不复用**、不覆盖既有块：\n\n```markdown\n## Debug 1 · <bug 一句话简述>\n\n- 状态：debugging # debugging | resolved\n- 快照：<git stash create 得到的 SHA>\n- 进入时间：\'2026-07-19 15:54:37\'\n\n### 1.1 Bug 现象与复现\n\n...\n\n### 1.2 关联链路分析\n\n...\n\n### 1.3 Debug 基线\n\n快照 SHA + 进入时间；`git diff <SHA>` 为退出闸门基准。\n\n### 1.4 假设看板\n\n...\n\n### 1.5 证据\n\n...\n\n### 1.6 脚手架清单\n\n...\n\n### 1.7 收尾核对\n\n...\n```\n\n### 生命周期\n\n- **创建 / 进入**：`debug.md` 不存在则创建（写文件 frontmatter + 第 1 个记录块）；已存在则追加 `## Debug <max+1>`，置文件 `status: debugging`、`active: <新编号>`。进入后**立刻**打快照（见「污染防线」）。\n- **单块收尾**：把该记录块块头 `状态` 置 `resolved`，脚手架逐条核销，`git diff <SNAP>` 校验只剩合法修复。\n- **文件 status 收敛**：单块收尾后，若**所有**记录块均 `resolved`，置文件 `status: resolved`、清空 `active`；否则保持 `debugging` 且 `active` 指向仍在调试的块。\n- **归档**：收尾**保留** `debug.md` 供复盘，绝不删除。\n\n## 核心调试循环\n\n**分析 → 规划 → 假设 → 实施 → 验证 → 缩小范围 → 再假设**，直至根因被硬证据锁定。\n\n```mermaid\nflowchart TD\n    Start["接手 bug"] --> Repro{"能稳定复现?"}\n    Repro -->|否| GetRepro["补齐复现步骤<br/>（问用户 / 自行构造）"]\n    GetRepro --> Repro\n    Repro -->|是| Analyze["分析关联链路<br/>写入 debug.md"]\n    Analyze --> Hypo["提出可证伪假设<br/>成立看到 X / 不成立看到 Y"]\n    Hypo --> Probe["写验证性代码 / 加日志<br/>登记脚手架清单"]\n    Probe --> Eval{"证据指向?"}\n    Eval -->|证伪| Exclude["记入已排除假设 + 依据"]\n    Exclude --> Narrow["缩小范围（二分/控制变量）"]\n    Narrow --> Hypo\n    Eval -->|坐实根因| Fix["写最终修复"]\n    Fix --> Verify{"重跑复现步骤<br/>问题消失?"}\n    Verify -->|否| Hypo\n    Verify -->|是| Close["进入收尾"]\n```\n\n### 方法层\n\n- **二分法**：在可疑区间（提交历史 / 代码路径 / 数据范围）二分定位，每次砍掉一半。\n- **控制变量法**：一次只改一个变量，隔离单一因素的影响。\n- **遍历可能分支**：对有限的分支/枚举/状态逐一验证，排除法收敛。\n\n## 硬约束（资深工程师容易做、Agent 容易漏）\n\n1. **先复现，再调试**：无法稳定复现，**不得进入修改阶段**——否则无从验证修没修好。复现不了就先构造复现路径或请用户提供。\n2. **假设必须可证伪**：提出假设时，同时写出"若成立会看到 X，若不成立会看到 Y"，再去取证。写进「假设看板」。\n3. **记录已排除假设 + 依据**：每否定一个假设，连同证据写入看板，**避免兜圈子反复验证同一已否定项**。\n4. **禁止无证据修复**：拿到指向根因的**硬证据**（日志 / 截图 / 可复现的最小用例）前，**只许写验证性代码，不许写最终修复**。\n5. **人机协作**：优先主动复现 Bug、获取日志进行分析判断，如果无途径复现 Bug、获取日志，也可暂停执行，让用户配合复现 Bug、回传日志。\n6. **退出双条件**：根因有硬证据 **且** 修复后重跑复现步骤、证据显示问题消失——**缺一不可**。\n\n### 日志纪律\n\n- **可读可复制**：打印结构化字符串而非整个 object（如 拼接关键字段 k1=v1&k2=v2 或 `JSON.stringify(x)`），避免直接打印对象或复杂结构变量的引用。\n- **避免刷屏**：不要在循环/高频路径里打印大量日志；聚焦怀疑环节，必要时带唯一标记便于检索。\n- **可定位**：日志带上下文（哪个函数 / 哪个分支 / 关键变量值），便于判定假设成立与否。\n\n## 更大的自由度（Debug 模式内允许）\n\n- 编写临时代码（条件短路）或注释有意义代码，控制程序进入 / 屏蔽特定分支；\n- 临时篡改变量值、Mock API 返回，让程序走到特定分支；\n- 编写临时独立测试页面 / 入口，简化复现路径、直接验证怀疑环节；\n- 联网查询第三方 SDK 文档、向用户询问必要信息；\n- 允许 lint / typecheck / build / 单测出现错误，允许**临时**跳过这些检查。\n\n> 每一处临时改动都**必须**在「脚手架清单」登记一行（文件 + 位置 + 类型：短路 / Mock / 注释 / 临时页面 / 临时日志），收尾逐条核销。**未登记 = 会漏还原**。\n\n## 污染防线（强制流程）\n\n在**当前项目与分支就地调试**，不开 worktree；靠快照 + 脚手架清单 + diff 兜住污染。\n\n```mermaid\nflowchart TD\n    Enter["进入 Debug（新记录块）"] --> Snap["SNAP = git stash create<br/>零副作用快照当前脏工作区"]\n    Snap --> Record["把 SNAP 写入记录块 · Debug 基线"]\n    Record --> Loop["调试循环<br/>照常改代码 + 登记脚手架清单"]\n    Loop --> Fixed{"根因确认 + 硬证据?"}\n    Fixed -->|否| Loop\n    Fixed -->|是| Revert["按脚手架清单逐条还原"]\n    Revert --> Diff["git diff SNAP"]\n    Diff --> Gate{"仅剩合法修复?"}\n    Gate -->|否| Revert\n    Gate -->|是| Done["置本块 status: resolved<br/>跑变更文件单测/build/typecheck"]\n```\n\n- **进入即打快照**：`git stash create`（**不是** `git stash` / 临时 commit）生成一个记录当前脏工作区的 commit 对象，但**不动工作区 / index / HEAD**。它天然区分"进入前的既有未提交改动"与"调试引入的改动"，避免临时 commit 的还原风险。把返回的 SHA 写入记录块「Debug 基线」。\n  - 若 `git stash create` 无输出（工作区干净），以当前 `HEAD`（`git rev-parse HEAD`）作为快照基准并注明。\n- **git diff 是退出闸门**：宣告完成前，`git diff <SNAP>` 必须**只剩合法修复**——所有短路 / Mock / 注释 / 临时页面 / 临时日志都已还原。diff 里还有脚手架残留 = 不许收尾。\n\n## 收尾（退出 Debug 模式）\n\n根因确认且修复通过复现验证后：\n\n1. **还原脚手架**：按「脚手架清单」逐条还原临时代码与被注释代码，确保原有逻辑正确；清理不需要的 debug 日志。\n2. **退出闸门**：`git diff <SNAP>` 只剩合法修复（脚手架清单全部核销）。\n3. **常规完整性检查**：跑变更文件关联单测、构建、类型检查。\n4. **落状态**：把该记录块块头 `状态` 置 `resolved`；按「文件 status 收敛」更新文件 frontmatter（全部 resolved → 文件 `status: resolved`、清空 `active`）。\n5. **保留归档**：`debug.md` 保留，供复盘。\n\n> 收尾后如又发现**新** bug，回到本 skill 追加下一条 `## Debug NNN` 记录块（不覆盖历史），重新走一遍循环。\n\n## 写回纪律\n\n- 每次写回 `debug.md` 都更新文件 frontmatter 的 `updated_at`。\n- `updated_at` 用本地秒级 `YYYY-MM-DD HH:mm:ss` 字符串。\n- 记录块编号连续递增、不复用、不重排既有块。\n';
+const __vite_glob_0_0 = '---\nname: yorz-debug\ndescription: 以资深工程师的调试纪律定位并修复疑难 bug——假设→取证→验证的证据闭环，靠 debug.md 活文档与 git 快照兜住污染。\n---\n\n# YorZ Debug 深度调试 Skill\n\n指导 Agent 以**资深工程师的调试纪律**逐步逼近疑难 bug 的根因：不凭猜测改代码，坚持「假设 → 取证 → 验证 → 缩小范围 → 再假设」的证据闭环。调试过程赋予更大的自由度（临时改代码、Mock 数据、加日志、建临时验证入口），同时用 `debug.md` 活文档 + `git stash create` 快照兜住"污染性改动不进入最终提交"。\n\n> 本 skill **不复用** yorz-spec 的 plan/tasks/execute 状态机。真相以 `debug.md` 为单一载体；Agent 持续推进直至需要用户回传证据（人在环路），或根因确认并收尾。\n\n## 何时进入本 skill\n\n- **独立触发（无需 spec / UI）**：用户在 Agent 对话中直接点名「用 yorz-debug 调这个 bug」。此时可能没有任何 spec 上下文——按下方「无 spec 场景」处理 `debug.md` 落点。\n- **追加任务勾选 Debug**：用户在 SpecDetail 追加 `fix` 任务时勾选「Debug 模式」，后端 prompt 指向本 skill。\n- **重入**：spec 目录已存在 `status: debugging` 的 `debug.md`（有未收尾记录块），run/append 路由自动切到本 skill。此时**不新建记录块**，定位活跃记录块（frontmatter `active: NNN`）续跑。\n\n## 输入约定\n\n- `spec_dir`（**可选**）：spec 目录路径（含 `spec.md`）。给出时 `debug.md` 建在此目录，与 `spec.md` 同级。\n- 待调试 bug 的描述：来自追加任务行 / 用户 prompt。\n- 运行服务上下文（**可选**）：由 YorZ Service 注入的当前项目运行中命令服务列表，包含 `runId`、`name`、`cli`、`pid`、`startedAt`、`logFile` 等字段。\n\n### debug.md 落点\n\n- **有 spec 上下文**：`debug.md` 落 `spec_dir`（与 `spec.md` 同级）。\n- **无 spec 场景（独立触发）**：没有 `spec_dir` 时，Debug 活文档必须落在项目临时目录 `.yorz/tmp/debug/`，文件名必须携带本地秒级时间信息，格式为 `debug-YYYYMMDD-HHmmss.md`；若 YorZ Service prompt 已给出具体文件路径，则以该路径为准。其余多记录模型、快照、脚手架、收尾流程与有 spec 时**完全一致**。\n\n## debug.md：多记录活文档\n\n**一个 `debug.md` 承载同一 spec 生命周期内的多次调试**（某次收尾后又发现新 bug，就追加下一条记录，不覆盖历史）。它同时是：调试活文档、**Debug 模式的持久化标记**（存在未收尾记录 = 处于 Debug 模式）、脚手架是否清理干净的守卫。\n\n### 文件级 frontmatter\n\n```yaml\n---\nstatus: debugging # debugging（存在未收尾记录）| resolved（全部记录已收尾）\nactive: 2 # 当前活跃记录编号；resolved 时留空\nupdated_at: \'2026-07-19 15:54:37\' # 本地秒级字符串\n---\n```\n\n### 正文按「记录块」组织\n\n每次进入 Debug **在文末追加**一个记录块，编号 `NNN` 从 1 递增、**不复用**、不覆盖既有块：\n\n```markdown\n## Debug 1 · <bug 一句话简述>\n\n- 状态：debugging # debugging | resolved\n- 快照：<git stash create 得到的 SHA>\n- 进入时间：\'2026-07-19 15:54:37\'\n\n### 1.1 Bug 现象与复现\n\n...\n\n### 1.2 关联链路分析\n\n...\n\n### 1.3 Debug 基线\n\n快照 SHA + 进入时间；`git diff <SHA>` 为退出闸门基准。\n\n### 1.4 假设看板\n\n...\n\n### 1.5 证据\n\n...\n\n### 1.6 脚手架清单\n\n...\n\n### 1.7 收尾核对\n\n...\n```\n\n### 生命周期\n\n- **创建 / 进入**：`debug.md` 不存在则创建（写文件 frontmatter + 第 1 个记录块）；已存在则追加 `## Debug <max+1>`，置文件 `status: debugging`、`active: <新编号>`。进入后**立刻**打快照（见「污染防线」）。\n- **单块收尾**：把该记录块块头 `状态` 置 `resolved`，脚手架逐条核销，`git diff <SNAP>` 校验只剩合法修复。\n- **文件 status 收敛**：单块收尾后，若**所有**记录块均 `resolved`，置文件 `status: resolved`、清空 `active`；否则保持 `debugging` 且 `active` 指向仍在调试的块。\n- **归档**：收尾**保留** `debug.md` 供复盘，绝不删除。\n\n## 核心调试循环\n\n**分析 → 规划 → 假设 → 实施 → 验证 → 缩小范围 → 再假设**，直至根因被硬证据锁定。\n\n```mermaid\nflowchart TD\n    Start["接手 bug"] --> Repro{"能稳定复现?"}\n    Repro -->|否| GetRepro["补齐复现步骤<br/>（问用户 / 自行构造）"]\n    GetRepro --> Repro\n    Repro -->|是| Analyze["分析关联链路<br/>写入 debug.md"]\n    Analyze --> Hypo["提出可证伪假设<br/>成立看到 X / 不成立看到 Y"]\n    Hypo --> Probe["写验证性代码 / 加日志<br/>登记脚手架清单"]\n    Probe --> Eval{"证据指向?"}\n    Eval -->|证伪| Exclude["记入已排除假设 + 依据"]\n    Exclude --> Narrow["缩小范围（二分/控制变量）"]\n    Narrow --> Hypo\n    Eval -->|坐实根因| Fix["写最终修复"]\n    Fix --> Verify{"重跑复现步骤<br/>问题消失?"}\n    Verify -->|否| Hypo\n    Verify -->|是| Close["进入收尾"]\n```\n\n### 方法层\n\n- **二分法**：在可疑区间（提交历史 / 代码路径 / 数据范围）二分定位，每次砍掉一半。\n- **控制变量法**：一次只改一个变量，隔离单一因素的影响。\n- **遍历可能分支**：对有限的分支/枚举/状态逐一验证，排除法收敛。\n\n## 硬约束（资深工程师容易做、Agent 容易漏）\n\n1. **先复现，再调试**：无法稳定复现，**不得进入修改阶段**——否则无从验证修没修好。复现不了就先构造复现路径或请用户提供。\n2. **假设必须可证伪**：提出假设时，同时写出"若成立会看到 X，若不成立会看到 Y"，再去取证。写进「假设看板」。\n3. **记录已排除假设 + 依据**：每否定一个假设，连同证据写入看板，**避免兜圈子反复验证同一已否定项**。\n4. **禁止无证据修复**：拿到指向根因的**硬证据**（日志 / 截图 / 可复现的最小用例）前，**只许写验证性代码，不许写最终修复**。\n5. **人机协作**：优先主动复现 Bug、获取日志进行分析判断，如果无途径复现 Bug、获取日志，也可暂停执行，让用户配合复现 Bug、回传日志。\n6. **退出双条件**：根因有硬证据 **且** 修复后重跑复现步骤、证据显示问题消失——**缺一不可**。\n\n### 日志纪律\n\n- **可读可复制**：打印结构化字符串而非整个 object（如 拼接关键字段 k1=v1&k2=v2 或 `JSON.stringify(x)`），避免直接打印对象或复杂结构变量的引用。\n- **避免刷屏**：不要在循环/高频路径里打印大量日志；聚焦怀疑环节，必要时带唯一标记便于检索。\n- **可定位**：日志带上下文（哪个函数 / 哪个分支 / 关键变量值），便于判定假设成立与否。\n\n## 更大的自由度（Debug 模式内允许）\n\n- 编写临时代码（条件短路）或注释有意义代码，控制程序进入 / 屏蔽特定分支；\n- 临时篡改变量值、Mock API 返回，让程序走到特定分支；\n- 编写临时独立测试页面 / 入口，简化复现路径、直接验证怀疑环节；\n- 联网查询第三方 SDK 文档、向用户询问必要信息；\n- 允许 lint / typecheck / build / 单测出现错误，允许**临时**跳过这些检查。\n\n> 每一处临时改动都**必须**在「脚手架清单」登记一行（文件 + 位置 + 类型：短路 / Mock / 注释 / 临时页面 / 临时日志），收尾逐条核销。**未登记 = 会漏还原**。\n\n## 污染防线（强制流程）\n\n在**当前项目与分支就地调试**，不开 worktree；靠快照 + 脚手架清单 + diff 兜住污染。\n\n```mermaid\nflowchart TD\n    Enter["进入 Debug（新记录块）"] --> Snap["SNAP = git stash create<br/>零副作用快照当前脏工作区"]\n    Snap --> Record["把 SNAP 写入记录块 · Debug 基线"]\n    Record --> Loop["调试循环<br/>照常改代码 + 登记脚手架清单"]\n    Loop --> Fixed{"根因确认 + 硬证据?"}\n    Fixed -->|否| Loop\n    Fixed -->|是| Revert["按脚手架清单逐条还原"]\n    Revert --> Diff["git diff SNAP"]\n    Diff --> Gate{"仅剩合法修复?"}\n    Gate -->|否| Revert\n    Gate -->|是| Done["置本块 status: resolved<br/>跑变更文件单测/build/typecheck"]\n```\n\n- **进入即打快照**：`git stash create`（**不是** `git stash` / 临时 commit）生成一个记录当前脏工作区的 commit 对象，但**不动工作区 / index / HEAD**。它天然区分"进入前的既有未提交改动"与"调试引入的改动"，避免临时 commit 的还原风险。把返回的 SHA 写入记录块「Debug 基线」。\n  - 若 `git stash create` 无输出（工作区干净），以当前 `HEAD`（`git rev-parse HEAD`）作为快照基准并注明。\n- **git diff 是退出闸门**：宣告完成前，`git diff <SNAP>` 必须**只剩合法修复**——所有短路 / Mock / 注释 / 临时页面 / 临时日志都已还原。diff 里还有脚手架残留 = 不许收尾。\n\n## 收尾（退出 Debug 模式）\n\n根因确认且修复通过复现验证后：\n\n1. **还原脚手架**：按「脚手架清单」逐条还原临时代码与被注释代码，确保原有逻辑正确；清理不需要的 debug 日志。\n2. **退出闸门**：`git diff <SNAP>` 只剩合法修复（脚手架清单全部核销）。\n3. **常规完整性检查**：跑变更文件关联单测、构建、类型检查。\n4. **落状态**：把该记录块块头 `状态` 置 `resolved`；按「文件 status 收敛」更新文件 frontmatter（全部 resolved → 文件 `status: resolved`、清空 `active`）。\n5. **保留归档**：`debug.md` 保留，供复盘。\n\n> 收尾后如又发现**新** bug，回到本 skill 追加下一条 `## Debug NNN` 记录块（不覆盖历史），重新走一遍循环。\n\n## 写回纪律\n\n- 每次写回 `debug.md` 都更新文件 frontmatter 的 `updated_at`。\n- `updated_at` 用本地秒级 `YYYY-MM-DD HH:mm:ss` 字符串。\n- 记录块编号连续递增、不复用、不重排既有块。\n';
 const __vite_glob_0_1 = '{\n  "$schema": "https://json-schema.org/draft-07/schema#",\n  "version": 2,\n  "modules": [\n    {\n      "module": "SKILL",\n      "file": "SKILL.md",\n      "relatedCases": []\n    }\n  ]\n}\n';
 const __vite_glob_0_2 = '---\nname: yorz-spec\ndescription: Drive YorZ spec docs through plan / tasks / execute stages with deterministic state updates.\n---\n\n# YorZ Spec Drive Skill\n\n将单个 YorZ spec 文档作为状态机执行，围绕 `plan` / `tasks` / `execute` 三阶段推进，全部任务完成后进入终止态 `done`，把状态持续写回文档。md 是单一真相；Agent 持续推进直至阻塞（待确认项、决策、Review）或收尾为 `done` 才退出。\n\n## 如何使用本 skill\n\n本 skill 文档结构精简为 3 个文件；每次接到 spec 任务时，**按以下顺序**按需 Read：\n\n1. **本文档（SKILL.md）**：输入约定、frontmatter 规范、格式约定、自动模式判定、全局硬约束、lint 硬约束、持续推进约束。\n2. **[stages.md](./stages.md)**：plan / tasks / execute / new-spec 四阶段流程与正面示例。\n3. **[review.md](./review.md)**：Review / Git Ops 阶段（独立路径，低频使用）。\n\n[mermaid.md](./mermaid.md) 与 `references/` 目录**仅按需 Read**：只有在判断当前阶段需要输出 mermaid 图表「升维」时才加载，纯状态推进任务不必读取，以节省 context。**plan 阶段的「图形化补充」收尾子步骤**（见 stages.md）会针对 `现状分析`/`技术方案` 两节强制加载 mermaid.md 补图；补图须遵循其核心原则**「图优先、精确信息折叠」**——表层给图，精确细节折叠进 `<details>` 精确层。\n\n> 当 Agent 以 `mode=review` / `mode=git-ops` 启动时，按 [review.md](./review.md) 执行；该路径不进入 plan/tasks/execute 状态机，也不修改 spec.md 的 frontmatter。\n\n## 输入约定\n\n- `spec_path`：**可选**，目标 spec 文档路径。\n  - 显式给出时：典型位置 `docs/specs/*.md` 或 `.yorz/specs/<id>/spec.md`，直接更新该 spec。\n  - 缺省时按以下顺序解析：\n    1. **从 session 上下文恢复**：扫描当前会话历史中已出现/已读写过的 spec 文档路径；存在多个时优先选取最近一次被读写的；若仍有歧义，向用户确认。\n    2. **从当前 prompt 创建**：若上下文中没有任何 spec 文档，按 [新建 spec 流程](./stages.md#new-spec) 生成路径与骨架。\n- spec 目录默认为 `.yorz/specs`，可由 `<ProjectRoot>/.yorz/config.json` 的 `specsDir` 字段覆盖。\n- `mode`：可选，`plan|tasks|execute|auto`，默认 `auto`。\n- 批注前缀：`！！！`\n\n## frontmatter 规范\n\n每个 spec md 顶部必须有 YAML frontmatter：\n\n```yaml\n---\nstage: plan # plan | tasks | execute | done\nlast_action: 简述上一次动作\nupdated_at: \'2026-06-14 15:42:07\' # 本地秒级字符串\nsummary: 一句话概要，≤ 200 字符\n---\n```\n\n- 字段顺序固定为 `stage` → `last_action` → `updated_at` → `summary`，每个字段独占一行，禁止嵌套与额外字段。\n- `updated_at` 使用本地秒级 `YYYY-MM-DD HH:mm:ss` 字符串。\n- 缺失任意字段时，先补齐再继续。\n\n## Markdown 格式化约定\n\n- 每次写回 spec md 后，**应在仓库支持的条件下运行 Markdown formatter**（优先 `npx prettier --write <spec_path>`）；未配置则跳过。\n- formatter 必须保留 YAML frontmatter 不变。\n- 任务清单仅使用单层 `- [ ]` / `- [x]`，避免缩进与嵌套。\n- 二、三级标题必须带层级编号，便于外部按章节号定位：\n  - 每次写回前按 body 中 `## ` / `### ` 出现顺序重新编号。\n  - 二级标题 `## N. 标题`（N 从 1 起）；三级标题 `### N.M 标题`（M 在所属二级下从 1 起）。\n  - 该规则不影响 frontmatter 与一级标题（`# `）。\n\n## 自动模式判定顺序（严格按顺序）\n\n`mode=auto` 时，**严格按顺序**判定，命中即停：\n\n1. 若 `spec_path` 缺省：从 session 上下文恢复 spec 路径；恢复失败进入 [新建 spec 流程](./stages.md#new-spec) 并以 `plan` 起步。\n2. **优先扫描 `## 追加任务` 中是否存在 `[open]` 条目**：存在即视为"新输入"信号，进入 `plan`（重开流程）。\n3. 若识别到新增/扩展需求或新增 bug，进入 `plan`（重开流程）。\n4. 若文档存在任意 `！！！` 批注，进入 [tasks](./stages.md#tasks)。\n5. 若 `## 待确认项` 下存在有效条目（非空态 `_暂无_`），停止推进并等待人工批注。\n6. 若 `stage` 已是 `done` 且上述 1–5 均未命中（无新输入/批注/待确认项），直接停止：终止态不再自动推进。\n7. 若存在未完成的**非 `[manual]`** 任务（`- [ ]` 且非 `- [ ] [manual]`），进入 [execute](./stages.md#execute)。\n8. 若任务清单已就绪且不存在未完成的非 manual 任务（走到此处已排除 `[open]`/新需求/批注/待确认项）：将 `stage` 置为 `done` 并停止推进（终止态）。\n9. 若 `## 技术实现方案` 为空或明显不完整，进入 [plan](./stages.md#plan)。\n10. 进入 [tasks](./stages.md#tasks) 生成或刷新详细任务清单。\n\n> 章节名 `## 待确认项` 为新名，parser/lint 兼容旧名 `## 待确认问题`；存量 spec 保留旧名仍可识别，新建/重写一律用 `待确认项`。\n>\n> 待确认项判定：章节内存在任一 `### ` 三级标题即视为未决；仅有 `_暂无_` 或整章为空即视为无未决条目；存在未决条目时禁止进入 execute。\n>\n> `done` 判定忽略 `- [ ] [manual]` 人工确认项：即使 manual 项仍未勾选，只要其余任务全部完成、且无待确认项/批注/`[open]`，即可收尾为 `done`。\n\n## 全局硬约束\n\n### 通用\n\n- 仅更新目标 spec 文档，不修改无关文档。\n- 每次写回文档都必须更新 frontmatter 元信息。\n- 执行任务时若涉及代码改动，只改动与任务相关的最小范围。\n\n### 章节建议\n\n初始化 spec 时**建议**创建以下章节（`## 追加任务` `## 用户批注` 为可选，由用户触发追加时懒插入）：\n\n- `## 现状分析` / `## 技术实现方案` / `## 待确认项` / `## 任务清单` / `## 执行记录`\n\n> lint 不再强制校验章节齐全；但 routing 按章节名查找时，章节不存在视为空态。\n\n### 变更重开流程\n\n**触发条件：**\n\n- 在已有 spec 中识别到"新增/扩展需求"或"新增 bug"，将 `stage` 切回 `plan`，`last_action` 记录"变更重开流程"。\n- `## 追加任务` 存在 `- [open] [feat|refct|fix] ...` 条目时，将 `stage` 切回 `plan`。\n\n**重开后必须做的事：**\n\n- 仅针对新增内容重新走完 `plan → tasks → execute`。\n- 未受影响的既有结论/任务可保留，受影响任务必须重新评估。\n- plan 阶段消费追加任务条目时，**不修改** `[open]` 状态标记。\n\n## 输出优先级\n\n1. 先保证状态正确（frontmatter 元信息更新）。\n2. 再保证结构正确（列表格式、任务格式、候选项）。\n3. 最后保证内容质量（可执行、可验收、可追踪）。\n\n## 写回后的 lint 硬约束\n\n任何阶段完成对 `spec.md` / `review.md` 的写入后，Agent **必须**通过 Bash 运行 `yorz lint <path> --format json`，并 parse stdout。\n\n- `errorCount === 0` 时视为通过。\n- 存在 `severity: error` 时按 `ruleId` + `message` + `line` 定位并修改，然后重新运行 lint。\n- 同一文件 lint 连续失败达到 **3 次**，将偏差作为 `## 待确认项` 条目写入 spec.md 后退出，等待人工干预。\n- `warn` 级 finding 不阻断推进，但应尽力消除。\n\n## 持续推进硬约束\n\nAgent 在 plan / tasks / execute 任意阶段，**只允许**因以下"合法阻塞"退出当轮：\n\n1. `## 待确认项` 章节存在非 `暂无` 条目；\n2. spec md 内存在任何 `！！！` 批注；\n3. 识别到新增/扩展需求或新增 bug，按变更重开流程切回 `plan`；\n4. 执行外部命令 / 工具调用失败，需要用户做不可推断的决断。\n\n**显式禁止**以下"元确认"行为：\n\n- 以"任务很多 / 改动较大 / 范围广 / 时间长 / 风险高"为由询问"是否继续 / 是否执行 / 是否同意此方案"。\n- 在 execute 阶段中段汇报进度并要求用户确认下一步。\n- 反问类如"要不要我开始 / 是否继续下一项"等问句。\n\n替代约定：tasks/execute 阶段若产生新疑问，**必须**作为新条目写回 `## 待确认项` 并按变更重开流程退出。\n\n兜底：对外部世界有副作用、不可逆的命令（如 `git push`、`git reset --hard`、`rm -rf`、修改 CI 配置等破坏性操作）仍按系统默认安全准则处理。\n\n## 与 YorZ 工作流的关联\n\n- 本 skill 不依赖 YorZ Service / GUI 也能独立工作：Agent 直接读写 `spec_path` 即可。\n- 当 YorZ Service 在线时，Agent 写回 md 会被 Service 的 FS Watcher 感知并推送给 GUI。\n- 如需用户介入，Agent 把信息写回文档对应章节后立即退出，由用户人工补齐 `！！！` 批注，再由 CLI / Service 重新拉起 Agent 继续执行。\n';
 const __vite_glob_0_3 = "---\nstage: execute\nlast_action: 主任务完成，追加 1 项 [open] 待处理\nupdated_at: 2026-06-20\nsummary: HELLO.txt 已经创建；追加任务：在 HELLO.txt 末尾追加一行 `goodbye world\\n`。\n---\n\n# HELLO 占位\n\n## 1. 背景\n\n希望仓库根有占位文件，便于演示。\n\n## 2. 需求\n\n- 在仓库根创建 `HELLO.txt`，内容 `hello world\\n`\n\n## 3. 现状分析\n\n`HELLO.txt` 已经存在，内容 `hello world\\n`。\n\n## 4. 技术实现方案\n\n- 直接写入 `HELLO.txt`，内容 `hello world\\n`。\n\n## 5. 待确认问题\n\n- 暂无\n\n## 6. 任务清单\n\n- [x] 在仓库根新建 `HELLO.txt`，内容 `hello world\\n`，验收点：文件存在且字节数 = 12。\n\n## 7. 追加任务\n\n- [open] 在 `HELLO.txt` 末尾追加一行 `goodbye world\\n`，验收点：最终文件含 2 行、共 26 字节。\n\n## 8. 执行记录\n\n- 2026-06-20 创建 `HELLO.txt`，内容 `hello world\\n`。\n";
@@ -167,15 +195,15 @@ const SKILL_FILES = /* @__PURE__ */ Object.assign({
 const SKILL_ROOT = "../skill/";
 function resolveSkillFiles(skillDir = SKILL_DIR_NAME) {
   const prefix = `${SKILL_ROOT}${skillDir}/`;
-  const files = [];
+  const files2 = [];
   for (const [key, content] of Object.entries(SKILL_FILES)) {
     const idx = key.indexOf(prefix);
     if (idx < 0) continue;
     const relPath = key.slice(idx + prefix.length);
     if (!relPath || relPath.startsWith("__tests__/") || relPath.includes("/__tests__/")) continue;
-    files.push({ relPath, content });
+    files2.push({ relPath, content });
   }
-  return files.sort((a, b) => a.relPath.localeCompare(b.relPath));
+  return files2.sort((a, b) => a.relPath.localeCompare(b.relPath));
 }
 async function install(opts, skillName = SKILL_DIR_NAME) {
   const adapter = getAdapter(opts.agent);
@@ -185,11 +213,11 @@ async function install(opts, skillName = SKILL_DIR_NAME) {
   const overwritten = await dirExists(skillDir);
   await rm(skillDir, { recursive: true, force: true });
   await mkdir(skillDir, { recursive: true });
-  const files = resolveSkillFiles(skillName);
-  if (!files.some((f) => f.relPath === "SKILL.md")) {
+  const files2 = resolveSkillFiles(skillName);
+  if (!files2.some((f) => f.relPath === "SKILL.md")) {
     throw new Error(`install: bundled skill "${skillName}" missing SKILL.md entry`);
   }
-  for (const f of files) {
+  for (const f of files2) {
     const target = join(skillDir, f.relPath);
     await mkdir(dirname(target), { recursive: true });
     await writeFile(target, f.content, "utf8");
@@ -198,7 +226,7 @@ async function install(opts, skillName = SKILL_DIR_NAME) {
   return {
     path: entry,
     overwritten,
-    files: files.map((f) => f.relPath),
+    files: files2.map((f) => f.relPath),
     gitignore
   };
 }
@@ -208,7 +236,7 @@ function computeBundledFingerprint(skillName = SKILL_DIR_NAME) {
 async function readInstalledFingerprint(skillDir, skillName = SKILL_DIR_NAME) {
   const relPaths = resolveSkillFiles(skillName).map((f) => f.relPath);
   if (!relPaths.includes("SKILL.md")) return null;
-  const files = [];
+  const files2 = [];
   for (const relPath of relPaths) {
     let content;
     try {
@@ -217,13 +245,13 @@ async function readInstalledFingerprint(skillDir, skillName = SKILL_DIR_NAME) {
       if (relPath === "SKILL.md") return null;
       content = "";
     }
-    files.push({ relPath, content });
+    files2.push({ relPath, content });
   }
-  return fingerprintFiles(files);
+  return fingerprintFiles(files2);
 }
-function fingerprintFiles(files) {
+function fingerprintFiles(files2) {
   const hash = createHash("sha256");
-  for (const f of [...files].sort((a, b) => a.relPath.localeCompare(b.relPath))) {
+  for (const f of [...files2].sort((a, b) => a.relPath.localeCompare(b.relPath))) {
     hash.update(f.relPath);
     hash.update("\0");
     hash.update(f.content);
@@ -482,13 +510,13 @@ class AttachmentStore {
     if (!existsSync(dir)) return [];
     const names = await this.listAttachmentNames(draftId);
     const out = [];
-    for (const name of names) {
-      const stats = await stat(join(dir, name));
-      const ext = extname(name).toLowerCase();
+    for (const name2 of names) {
+      const stats = await stat(join(dir, name2));
+      const ext = extname(name2).toLowerCase();
       const mime = mimeForExt(ext);
       const kind = classifyMime(mime);
       if (!kind) continue;
-      out.push({ storedName: name, name, size: stats.size, mime, kind });
+      out.push({ storedName: name2, name: name2, size: stats.size, mime, kind });
     }
     return out.sort((a, b) => a.storedName < b.storedName ? -1 : 1);
   }
@@ -555,8 +583,8 @@ class AttachmentStore {
     return uniquify(`${sanitized}${ext}`, existing);
   }
 }
-function isPlaceholderImageName(name) {
-  const lower = name.toLowerCase().trim();
+function isPlaceholderImageName(name2) {
+  const lower = name2.toLowerCase().trim();
   if (!lower) return true;
   return lower === "image.png" || lower === "image.jpg" || lower === "image.jpeg" || lower === "image.webp" || lower === "image.gif" || /^(image|screenshot|clipboard)([._ -]?\d+)?\.[a-z0-9]+$/.test(lower) || /^untitled\.[a-z0-9]+$/.test(lower);
 }
@@ -565,481 +593,391 @@ function pickExt(rawName, mime) {
   if (fromName) return fromName;
   return MIME_TO_EXT[mime] ?? "";
 }
-function stripExt(name) {
-  const ext = extname(name);
-  return ext ? name.slice(0, name.length - ext.length) : name;
+function stripExt(name2) {
+  const ext = extname(name2);
+  return ext ? name2.slice(0, name2.length - ext.length) : name2;
 }
 function sanitize(text) {
   let cleaned = text.replace(/[\s\\/:*?"<>|\x00-\x1f]+/g, "-");
   cleaned = cleaned.replace(/\.+/g, "-");
   return cleaned.replace(/^-+|-+$/g, "").slice(0, 64);
 }
-function uniquify(name, existing) {
-  if (!existing.includes(name)) return name;
-  const ext = extname(name);
-  const base = stripExt(name);
+function uniquify(name2, existing) {
+  if (!existing.includes(name2)) return name2;
+  const ext = extname(name2);
+  const base = stripExt(name2);
   for (let i = 1; i < 1e3; i++) {
     const candidate = `${base}-${i}${ext}`;
     if (!existing.includes(candidate)) return candidate;
   }
   return `${base}-${randomUUID().slice(0, 4)}${ext}`;
 }
-function isSafeName(name) {
-  if (!name) return false;
-  if (name.includes("/") || name.includes("\\")) return false;
-  if (name === "." || name === "..") return false;
-  if (name.startsWith(".")) return false;
+function isSafeName(name2) {
+  if (!name2) return false;
+  if (name2.includes("/") || name2.includes("\\")) return false;
+  if (name2 === "." || name2 === "..") return false;
+  if (name2.startsWith(".")) return false;
   return true;
 }
-function createSpecsRoutes(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;
-  };
-  app.get("/projects/:projectId/specs", async (c) => {
-    const p = await need(c);
-    if (p instanceof Response) return p;
-    const items = await p.store.list();
-    return c.json(items);
-  });
-  app.post("/projects/:projectId/specs", async (c) => {
-    const p = await need(c);
-    if (p instanceof Response) return p;
-    let body;
-    try {
-      body = await c.req.json();
-    } catch {
-      return c.json({ error: "invalid JSON body" }, 400);
-    }
-    const input = parseCreateBody(body);
-    if ("error" in input) return c.json({ error: input.error }, 400);
-    if (!input.title && input.requirement) {
-      const prompt = buildDraftPrompt(input.type, input.requirement, input.draftId);
-      const { sessionId } = await p.sessions.createSession();
-      const handle = await p.sessions.send(sessionId, prompt);
-      return c.json({ runId: handle.runId, sessionId, draft: true }, 202);
-    }
-    try {
-      const { id, path } = await p.store.create(input);
-      return c.json({ id, path }, 201);
-    } catch (err) {
-      return c.json({ error: err.message }, 400);
-    }
-  });
-  app.get("/projects/:projectId/specs/:id", async (c) => {
-    const p = await need(c);
-    if (p instanceof Response) return p;
-    const detail = await p.store.read(c.req.param("id"));
-    if (!detail) return c.json({ error: "spec not found" }, 404);
-    return c.json(detail);
-  });
-  app.patch("/projects/:projectId/specs/:id/stage", async (c) => {
-    const p = await need(c);
-    if (p instanceof Response) return p;
-    const specId = c.req.param("id");
-    let body;
-    try {
-      body = await c.req.json();
-    } catch {
-      return c.json({ error: "invalid JSON body" }, 400);
-    }
-    const stage = body && typeof body === "object" ? body.stage : void 0;
-    if (stage !== "plan" && stage !== "tasks" && stage !== "execute" && stage !== "done") {
-      return c.json({ error: "stage must be plan | tasks | execute | done" }, 400);
-    }
-    try {
-      await p.store.setStage(specId, stage);
-      return c.json({ ok: true });
-    } catch (err) {
-      return c.json({ error: err.message }, 404);
-    }
-  });
-  app.get("/projects/:projectId/specs/:id/attachments/:name", async (c) => {
-    const p = await need(c);
-    if (p instanceof Response) return p;
-    const id = c.req.param("id");
-    const name = c.req.param("name");
-    if (!isSafeAttachmentName(name)) {
-      return c.json({ error: "invalid attachment name" }, 400);
-    }
-    const detail = await p.store.read(id);
-    if (!detail) return c.json({ error: "spec not found" }, 404);
-    const file = join(p.specsDir, id, "attachments", name);
-    if (!existsSync(file)) return c.json({ error: "attachment not found" }, 404);
-    const ext = extname(name).toLowerCase();
-    const mime = mimeForExt(ext);
-    const kind = classifyMime(mime);
-    const data = await readFile(file);
-    c.header("Content-Type", mime);
-    c.header(
-      "Content-Disposition",
-      kind === "image" || kind === "pdf" || kind === "text" ? "inline" : "attachment"
-    );
-    c.header("Cache-Control", "max-age=300");
-    return c.body(new Uint8Array(data));
-  });
-  app.post("/projects/:projectId/specs/:id/inputs", async (c) => {
-    const p = await need(c);
-    if (p instanceof Response) return p;
-    let body;
-    try {
-      body = await c.req.json();
-    } catch {
-      return c.json({ error: "invalid JSON body" }, 400);
-    }
-    const parsed = parseAnnotateBody(body);
-    if ("error" in parsed) return c.json({ error: parsed.error }, 400);
-    try {
-      await p.store.appendAnnotation(c.req.param("id"), parsed);
-      return c.json({ ok: true });
-    } catch (err) {
-      return c.json({ error: err.message }, 404);
-    }
-  });
-  app.post("/projects/:projectId/specs/:id/questions/answers", async (c) => {
-    const p = await need(c);
-    if (p instanceof Response) return p;
-    let body;
-    try {
-      body = await c.req.json();
-    } catch {
-      return c.json({ error: "invalid JSON body" }, 400);
-    }
-    const parsed = parseQuestionAnswersBody(body);
-    if ("error" in parsed) return c.json({ error: parsed.error }, 400);
-    try {
-      await p.store.applyQuestionAnswers(c.req.param("id"), parsed);
-      return c.json({ ok: true });
-    } catch (err) {
-      const msg = err.message;
-      const status = /spec not found/.test(msg) ? 404 : 400;
-      return c.json({ error: msg }, status);
-    }
-  });
-  app.post("/projects/:projectId/specs/:id/appends", async (c) => {
-    const p = await need(c);
-    if (p instanceof Response) return p;
-    const specId = c.req.param("id");
-    let body;
-    try {
-      body = await c.req.json();
-    } catch {
-      return c.json({ error: "invalid JSON body" }, 400);
-    }
-    const parsed = parseAppendBody(body);
-    if ("error" in parsed) return c.json({ error: parsed.error }, 400);
-    const detail = await p.store.read(specId);
-    if (!detail) return c.json({ error: "spec not found" }, 404);
-    try {
-      await p.store.appendItem(specId, {
-        kind: parsed.kind,
-        description: parsed.description,
-        sectionPath: parsed.sectionPath,
-        quote: parsed.quote
-      });
-    } catch (err) {
-      return c.json({ error: err.message }, 400);
-    }
-    if (parsed.autoRun) {
-      const { sessionId } = await p.sessions.ensureSessionForSpec(specId);
-      const debugActive = await readDebugMdStatus(join(p.specsDir, specId)) === "debugging";
-      const prompt = parsed.debug ? buildDebugPrompt(p.specsDirRelative, specId, "new", await buildDebugRuntimeContext(p)) : debugActive ? buildDebugPrompt(
-        p.specsDirRelative,
-        specId,
-        "resume",
-        await buildDebugRuntimeContext(p)
-      ) : `请使用 yorz-spec skill 处理 spec：${p.specsDirRelative}/${specId}/spec.md`;
-      const handle = await p.sessions.send(sessionId, prompt);
-      return c.json({ ok: true, runId: handle.runId, sessionId });
-    }
-    return c.json({ ok: true });
-  });
-  app.post("/projects/:projectId/specs/:id/run", 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);
-    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)) : `请使用 yorz-spec skill 处理 spec：${p.specsDirRelative}/${specId}/spec.md`;
-    const handle = await p.sessions.send(sessionId, prompt);
-    return c.json({ runId: handle.runId, sessionId });
-  });
-  app.post("/projects/:projectId/specs/:id/explain", async (c) => {
-    const p = await need(c);
-    if (p instanceof Response) return p;
-    const specId = c.req.param("id");
-    let body;
-    try {
-      body = await c.req.json();
-    } catch {
-      return c.json({ error: "invalid JSON body" }, 400);
-    }
-    const text = body && typeof body === "object" ? body.text : void 0;
-    if (typeof text !== "string" || !text.trim()) {
-      return c.json({ error: "text required" }, 400);
-    }
-    if (text.length > 4e3) {
-      return c.json({ error: "text too long (max 4000)" }, 400);
-    }
-    const detail = await p.store.read(specId);
-    if (!detail) return c.json({ error: "spec not found" }, 404);
-    const prompt = `以下为 spec 文档 ${p.specsDirRelative}/${specId}/spec.md 中的一段内容。
-请用中文简洁解释其含义、背景与可能的实施影响。**不要**修改任何文件，只在终端输出解释文本。
-
-引用：
-"""
-${text}
-"""
-`;
-    const { sessionId } = await p.sessions.ensureSessionForSpec(specId);
-    const handle = await p.sessions.send(sessionId, prompt);
-    return c.json({ runId: handle.runId, sessionId });
-  });
-  app.delete("/projects/:projectId/specs/:id", 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);
-    await p.store.delete(specId);
-    return c.json({ ok: true });
-  });
-  return app;
+const CURRENT_VERSION$1 = 1;
+const DEFAULT_GLOBAL_AGENT = { defaultKind: "claude" };
+const DEFAULT_NOTIFICATIONS = {
+  sessionEnd: { banner: false, sound: false }
+};
+function resolveGlobalConfigDir(env = process.env) {
+  if (env.YORZ_HOME && env.YORZ_HOME.trim()) return env.YORZ_HOME.trim();
+  const xdg = env.XDG_CONFIG_HOME?.trim();
+  const base = xdg && xdg.length > 0 ? xdg : join(homedir(), ".config");
+  return join(base, "yorz");
 }
-function buildDraftPrompt(type, requirement, draftId) {
-  const lines = [
-    "请按 yorz-spec skill 的「新建 spec」流程，根据下方信息创建新的 spec 文档，并立即按 plan 阶段继续推进直至阻塞。",
-    "",
-    `类型：${type}（已由调用方指定，不要再询问）`,
-    "需求：",
-    '"""',
-    requirement.trim(),
-    '"""',
-    "",
-    "硬性要求：",
-    `- 生成 kebab-case summary-name 时只使用对需求有语义代表性的英文/数字字符；如难以从中文中提炼出可读 slug，请直接使用 \`untitled-\` + 3 位日期内自增编号占位，禁止把中文挤压为零散英文片段（例如禁止出现 \`spec-agent-spec-agent\` 之类的拼接）。`,
-    "- frontmatter.summary 必须是对需求的真实概述（≤200 字符），不要原样照搬整段需求。",
-    "- 完成 spec 文件初始化后立即进入 plan 阶段，按 SKILL 规则补齐 `现状分析` / `技术实现方案` / `待确认项`，再视需要进入 tasks/execute。"
-  ];
-  if (draftId) {
-    lines.push(
-      "",
-      `附件迁移：本次新建 spec 关联了草稿附件目录 \`.yorz/tmp/drafts/${draftId}/attachments/\`。`,
-      "- 在创建 `.yorz/specs/<id>/` 目录并写入 `spec.md` 骨架**之后**，立即把该 draft 目录下的所有文件迁移到 `.yorz/specs/<id>/attachments/`，文件名保持不变。",
-      "- 迁移完成后，在 `## 背景` 章节末尾追加一段附件列表，每个附件占一行（按文件扩展名判定 `kind`）：",
-      "  - 图片（`.png` / `.jpg` / `.jpeg` / `.gif` / `.webp` / `.bmp` / `.svg` / `.avif` / `.heic`）：使用 `![<文件名>](attachments/<文件名>)`",
-      "  - PDF（`.pdf`） / 文本（`.txt` / `.md` / `.markdown`）：使用 `[<文件名>](attachments/<文件名>)`",
-      "- 迁移失败（如 draft 目录已被清理、权限不足）时，**不要静默丢弃**：在 `## 待确认项` 章节追加一条记录说明问题，并退出本轮等待用户介入。"
-    );
-  }
-  return lines.join("\n");
+function resolveGlobalConfigPath(env = process.env) {
+  return join(resolveGlobalConfigDir(env), "projects.json");
 }
-async function readDebugMdStatus(specDir) {
-  const file = join(specDir, "debug.md");
-  let text;
+async function loadGlobalConfig(filePath) {
+  const fp = filePath ?? resolveGlobalConfigPath();
+  if (!existsSync(fp)) return defaultGlobalConfig();
+  let raw;
   try {
-    text = await readFile(file, "utf8");
+    raw = await readFile(fp, "utf8");
   } catch {
-    return null;
+    return defaultGlobalConfig();
   }
-  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
-  if (!m) return null;
-  const statusLine = m[1].split(/\r?\n/).find((l) => /^status\s*:/.test(l.trim()));
-  if (!statusLine) return null;
-  const val = statusLine.slice(statusLine.indexOf(":") + 1).trim().replace(/^['"]|['"]$/g, "");
-  return val === "debugging" ? "debugging" : val === "resolved" ? "resolved" : null;
+  if (!raw.trim()) return defaultGlobalConfig();
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return defaultGlobalConfig();
+  }
+  return normalizeConfig$1(parsed);
 }
-function buildDebugPrompt(specsDirRelative, specId, mode, runtimeContext = "") {
-  const specPath = `${specsDirRelative}/${specId}/spec.md`;
-  const debugPath = `${specsDirRelative}/${specId}/debug.md`;
-  if (mode === "resume") {
-    return `请使用 yorz-debug skill 继续调试：spec 目录 ${specsDirRelative}/${specId}（含 ${specPath}）。该目录下已存在处于 debugging 状态的 ${debugPath}，请定位其活跃记录块（frontmatter active 指向的 ## Debug NNN）继续「假设 → 取证 → 验证」循环，勿新建记录块。` + runtimeContext;
+async function saveGlobalConfig(config, filePath) {
+  const fp = filePath ?? resolveGlobalConfigPath();
+  await mkdir(dirname(fp), { recursive: true });
+  const normalized = normalizeConfig$1(config);
+  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 normalizeConfig$1(value) {
+  if (!value || typeof value !== "object") return defaultGlobalConfig();
+  const obj = value;
+  const projectsRaw = Array.isArray(obj.projects) ? obj.projects : [];
+  const projects = [];
+  for (const item of projectsRaw) {
+    if (!item || typeof item !== "object") continue;
+    const it = item;
+    const id = typeof it.id === "string" ? it.id : "";
+    const path = typeof it.path === "string" ? it.path : "";
+    if (!id || !path) continue;
+    const addedAt = typeof it.addedAt === "string" ? it.addedAt : "";
+    const lastActivityAt = typeof it.lastActivityAt === "string" ? it.lastActivityAt : null;
+    const worktree = normalizeWorktree(it.worktree);
+    const entry = { id, path, addedAt, lastActivityAt };
+    if (worktree) entry.worktree = worktree;
+    projects.push(entry);
   }
-  return `请使用 yorz-debug skill 进入 Debug 模式：spec 目录 ${specsDirRelative}/${specId}（含 ${specPath}）。若 ${debugPath} 不存在则创建，否则在文末追加新的 ## Debug 记录块；进入后立即 git stash create 打快照写入 Debug 基线，再开始「假设 → 取证 → 验证」循环。` + runtimeContext;
+  return {
+    version: CURRENT_VERSION$1,
+    projects,
+    agent: normalizeAgent$1(obj.agent),
+    notifications: normalizeNotifications(obj.notifications)
+  };
 }
-async function buildDebugRuntimeContext(project) {
-  return formatDebugRuntimeContext(await project.commands.listRuns());
+function defaultGlobalConfig() {
+  return {
+    version: CURRENT_VERSION$1,
+    projects: [],
+    agent: { defaultKind: DEFAULT_GLOBAL_AGENT.defaultKind },
+    notifications: {
+      sessionEnd: {
+        banner: DEFAULT_NOTIFICATIONS.sessionEnd.banner,
+        sound: DEFAULT_NOTIFICATIONS.sessionEnd.sound
+      }
+    }
+  };
 }
-function formatDebugRuntimeContext(runs) {
-  const running = runs.filter((r) => r.status === "running");
-  if (running.length === 0) {
-    return "\n\n当前项目运行服务上下文：暂无运行中的命令服务。若复现需要服务，请根据项目脚本自行启动，或请用户在 GUI 命令菜单启动后重试。";
+function normalizeAgent$1(value) {
+  if (!value || typeof value !== "object") return { defaultKind: DEFAULT_GLOBAL_AGENT.defaultKind };
+  const obj = value;
+  const defaultKind = obj.defaultKind;
+  if (defaultKind === "opencode" || defaultKind === "codex") return { defaultKind };
+  return { defaultKind: "claude" };
+}
+function normalizeNotifications(value) {
+  if (!value || typeof value !== "object") return defaultGlobalConfig().notifications;
+  const obj = value;
+  const sessionEndRaw = obj.sessionEnd;
+  if (!sessionEndRaw || typeof sessionEndRaw !== "object")
+    return defaultGlobalConfig().notifications;
+  const sessionEndObj = sessionEndRaw;
+  return {
+    sessionEnd: {
+      banner: typeof sessionEndObj.banner === "boolean" ? sessionEndObj.banner : DEFAULT_NOTIFICATIONS.sessionEnd.banner,
+      sound: typeof sessionEndObj.sound === "boolean" ? sessionEndObj.sound : DEFAULT_NOTIFICATIONS.sessionEnd.sound
+    }
+  };
+}
+function normalizeWorktree(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const it = value;
+  const mainProjectId = typeof it.mainProjectId === "string" ? it.mainProjectId : "";
+  const mainPath = typeof it.mainPath === "string" ? it.mainPath : "";
+  const branch = typeof it.branch === "string" ? it.branch : "";
+  const specId = typeof it.specId === "string" ? it.specId : "";
+  const createdAt = typeof it.createdAt === "string" ? it.createdAt : "";
+  if (!mainProjectId || !mainPath || !branch) return void 0;
+  const cleanSlug = typeof it.cleanSlug === "string" ? it.cleanSlug : void 0;
+  const meta = { mainProjectId, mainPath, branch, specId, createdAt };
+  if (cleanSlug) meta.cleanSlug = cleanSlug;
+  return meta;
+}
+function generateProjectId(absPath) {
+  const base = basename$1(absPath);
+  const slug = slugify(base) || "proj";
+  const hash = createHash("sha256").update(absPath).digest("hex").slice(0, 6);
+  return `${slug}-${hash}`;
+}
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/, "");
+}
+async function addProject(absPath, filePath, now = () => /* @__PURE__ */ new Date()) {
+  const config = await loadGlobalConfig(filePath);
+  const existing = config.projects.find((p) => p.path === absPath);
+  if (existing) return { entry: existing, created: false };
+  const entry = {
+    id: generateProjectId(absPath),
+    path: absPath,
+    addedAt: now().toISOString(),
+    lastActivityAt: null
+  };
+  config.projects.push(entry);
+  await saveGlobalConfig(config, filePath);
+  return { entry, created: true };
+}
+async function setProjectWorktree(id, worktree, filePath) {
+  const config = await loadGlobalConfig(filePath);
+  const target = config.projects.find((p) => p.id === id);
+  if (!target) return false;
+  if (worktree) target.worktree = worktree;
+  else delete target.worktree;
+  await saveGlobalConfig(config, filePath);
+  return true;
+}
+async function removeProject(id, filePath) {
+  const config = await loadGlobalConfig(filePath);
+  const before = config.projects.length;
+  config.projects = config.projects.filter((p) => p.id !== id);
+  if (config.projects.length === before) return false;
+  await saveGlobalConfig(config, filePath);
+  return true;
+}
+async function prepareProjectDir(input, cwd) {
+  if (typeof input !== "string" || !input.trim()) {
+    throw new Error("path required");
+  }
+  const trimmed = input.trim();
+  const abs = isAbsolute(trimmed) ? resolve(trimmed) : resolve(cwd ?? process.cwd(), trimmed);
+  if (!existsSync(abs)) {
+    throw new Error(`path does not exist: ${abs}`);
+  }
+  const stats = await stat(abs);
+  if (!stats.isDirectory()) {
+    throw new Error(`path is not a directory: ${abs}`);
+  }
+  await mkdir(join(abs, ".yorz", "specs"), { recursive: true });
+  return abs;
+}
+const LEVEL_WEIGHT = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+};
+const LOG_LEVELS = Object.keys(LEVEL_WEIGHT);
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+const DEFAULT_MAX_ARCHIVES = 1;
+const DEFAULT_LOG_FILE = "serve.log";
+const STDIO_LOG_FILE = "serve-stdio.log";
+function resolveLogDir(env = process.env) {
+  return join(resolveGlobalConfigDir(env), "logs");
+}
+function resolveLogLevel(env = process.env) {
+  const raw = env.YORZ_LOG_LEVEL?.trim().toLowerCase();
+  if (raw && LOG_LEVELS.includes(raw)) return raw;
+  return "info";
+}
+function defaultOptions(env = process.env) {
+  return {
+    dir: resolveLogDir(env),
+    fileName: DEFAULT_LOG_FILE,
+    maxBytes: DEFAULT_MAX_BYTES,
+    maxArchives: DEFAULT_MAX_ARCHIVES,
+    level: resolveLogLevel(env),
+    mirrorConsole: true
+  };
+}
+class RotatingFileSink {
+  constructor(dir, fileName, maxBytes, maxArchives) {
+    this.dir = dir;
+    this.fileName = fileName;
+    this.maxBytes = maxBytes;
+    this.maxArchives = maxArchives;
+  }
+  currentSize = 0;
+  initialized = false;
+  queue = Promise.resolve();
+  get filePath() {
+    return join(this.dir, this.fileName);
+  }
+  archivePath(index) {
+    return `${this.filePath}.${index}`;
+  }
+  /** Enqueue a line; returns immediately, never throws. */
+  write(line) {
+    this.queue = this.queue.then(() => this.writeNow(line)).catch(() => {
+    });
   }
-  const lines = ["\n\n当前项目运行服务上下文："];
-  for (const run of running) {
-    lines.push(
-      `- runId: ${promptScalar(run.runId)}`,
-      `  name: ${promptScalar(run.name)}`,
-      `  cli: ${promptScalar(run.cli)}`,
-      `  status: ${run.status}`,
-      `  pid: ${run.pid}`,
-      `  startedAt: ${new Date(run.startedAt).toISOString()}`,
-      `  logFile: ${promptScalar(run.logFile)}`
-    );
+  /** Resolve once every queued line has been flushed to disk. */
+  async flush() {
+    await this.queue.catch(() => {
+    });
   }
-  return lines.join("\n");
-}
-function promptScalar(value) {
-  return value.replace(/\r?\n/g, "\\n");
-}
-function parseCreateBody(body) {
-  if (!body || typeof body !== "object") return { error: "body must be an object" };
-  const obj = body;
-  const rawType = obj.type ?? "feat";
-  if (rawType !== "feat" && rawType !== "refct" && rawType !== "fix") {
-    return { error: "type must be feat | refct | fix" };
+  async writeNow(line) {
+    try {
+      await this.ensureInit();
+      const bytes = Buffer.byteLength(line, "utf8");
+      if (this.currentSize > 0 && this.currentSize + bytes > this.maxBytes) {
+        await this.rotate();
+      }
+      await appendFile(this.filePath, line, "utf8");
+      this.currentSize += bytes;
+    } catch {
+    }
   }
-  const out = { type: rawType };
-  if (typeof obj.title === "string" && obj.title.trim()) out.title = obj.title;
-  if (typeof obj.summary === "string" && obj.summary.trim()) out.summary = obj.summary;
-  if (typeof obj.requirement === "string" && obj.requirement.trim()) {
-    out.requirement = obj.requirement;
+  /** Lazily create the dir and recover `currentSize` from an existing file. */
+  async ensureInit() {
+    if (this.initialized) return;
+    await mkdir(this.dir, { recursive: true });
+    try {
+      const st = await stat(this.filePath);
+      this.currentSize = st.size;
+    } catch {
+      this.currentSize = 0;
+    }
+    this.initialized = true;
   }
-  if (obj.draftId !== void 0) {
-    if (typeof obj.draftId !== "string" || !obj.draftId.trim()) {
-      return { error: "draftId must be a non-empty string" };
+  async rotate() {
+    if (this.maxArchives <= 0) {
+      await writeFile(this.filePath, "", "utf8");
+      this.currentSize = 0;
+      return;
     }
-    if (!/^[a-zA-Z0-9-]{1,64}$/.test(obj.draftId)) {
-      return { error: "draftId has invalid format" };
+    for (let i = this.maxArchives - 1; i >= 1; i--) {
+      try {
+        await rename(this.archivePath(i), this.archivePath(i + 1));
+      } catch {
+      }
     }
-    out.draftId = obj.draftId;
+    await rename(this.filePath, this.archivePath(1));
+    this.currentSize = 0;
   }
-  return out;
 }
-function isSafeAttachmentName(name) {
-  if (!name) return false;
-  if (name.includes("/") || name.includes("\\")) return false;
-  if (name === "." || name === "..") return false;
-  if (name.startsWith(".")) return false;
-  return true;
+function createSink(options) {
+  return new RotatingFileSink(options.dir, options.fileName, options.maxBytes, options.maxArchives);
 }
-function parseQuestionAnswersBody(body) {
-  if (!body || typeof body !== "object") return { error: "body must be an object" };
-  const obj = body;
-  const rawAnswers = obj.answers;
-  const rawFreeforms = obj.freeformAnnotations;
-  if (rawAnswers !== void 0 && !Array.isArray(rawAnswers)) {
-    return { error: "answers must be an array" };
+function formatMeta(meta) {
+  if (!meta) return "";
+  const keys = Object.keys(meta);
+  if (keys.length === 0) return "";
+  try {
+    return ` ${JSON.stringify(meta, jsonReplacer)}`;
+  } catch {
+    return "";
   }
-  if (rawFreeforms !== void 0 && !Array.isArray(rawFreeforms)) {
-    return { error: "freeformAnnotations must be an array" };
+}
+function jsonReplacer(_key, value) {
+  if (value instanceof Error) return { message: value.message, stack: value.stack };
+  if (typeof value === "bigint") return value.toString();
+  return value;
+}
+class Logger {
+  constructor(core, scope) {
+    this.core = core;
+    this.scope = scope;
   }
-  const answers = [];
-  for (const a of rawAnswers ?? []) {
-    if (!a || typeof a !== "object") return { error: "answer must be an object" };
-    const ao = a;
-    if (typeof ao.questionText !== "string" || !ao.questionText.trim()) {
-      return { error: "answer.questionText required" };
-    }
-    const item = { questionText: ao.questionText };
-    if (typeof ao.questionId === "string") item.questionId = ao.questionId;
-    if (typeof ao.selectedOptionLabel === "string" && ao.selectedOptionLabel.trim()) {
-      item.selectedOptionLabel = ao.selectedOptionLabel;
-    }
-    if (typeof ao.note === "string" && ao.note.trim()) item.note = ao.note;
-    if (!item.selectedOptionLabel && !item.note) {
-      return { error: "answer requires selectedOptionLabel or note" };
-    }
-    answers.push(item);
+  get level() {
+    return this.core.options.level;
   }
-  const freeformAnnotations = [];
-  for (const f of rawFreeforms ?? []) {
-    if (!f || typeof f !== "object") return { error: "freeformAnnotation must be an object" };
-    const fo = f;
-    if (typeof fo.sectionPath !== "string" || !fo.sectionPath.trim()) {
-      return { error: "freeformAnnotation.sectionPath required" };
-    }
-    if (typeof fo.quote !== "string" || !fo.quote.trim()) {
-      return { error: "freeformAnnotation.quote required" };
-    }
-    if (typeof fo.note !== "string" || !fo.note.trim()) {
-      return { error: "freeformAnnotation.note required" };
-    }
-    freeformAnnotations.push({
-      sectionPath: fo.sectionPath,
-      quote: fo.quote,
-      note: fo.note
-    });
+  get filePath() {
+    return this.core.sink.filePath;
   }
-  if (answers.length === 0 && freeformAnnotations.length === 0) {
-    return { error: "answers or freeformAnnotations required" };
+  get dir() {
+    return this.core.options.dir;
   }
-  return { answers, freeformAnnotations };
-}
-function parseAppendBody(body) {
-  if (!body || typeof body !== "object") return { error: "body must be an object" };
-  const obj = body;
-  const kind = obj.kind;
-  if (kind !== "feat" && kind !== "refct" && kind !== "fix") {
-    return { error: "kind must be feat | refct | fix" };
+  /** Derive a logger that prefixes every line with `[scope]`. */
+  child(scope) {
+    const next = this.scope && this.scope !== "yorz" ? `${this.scope}:${scope}` : scope;
+    return new Logger(this.core, next);
   }
-  if (typeof obj.description !== "string" || !obj.description.trim()) {
-    return { error: "description required" };
+  debug(msg, meta) {
+    this.emit("debug", msg, meta);
   }
-  const out = { kind, description: obj.description, autoRun: true, debug: false };
-  if (obj.sectionPath !== void 0) {
-    if (typeof obj.sectionPath !== "string") return { error: "sectionPath must be a string" };
-    if (obj.sectionPath.length > 200) return { error: "sectionPath too long (max 200)" };
-    if (obj.sectionPath.trim()) out.sectionPath = obj.sectionPath;
+  info(msg, meta) {
+    this.emit("info", msg, meta);
   }
-  if (obj.quote !== void 0) {
-    if (typeof obj.quote !== "string") return { error: "quote must be a string" };
-    if (obj.quote.length > 500) return { error: "quote too long (max 500)" };
-    if (obj.quote.trim()) out.quote = obj.quote;
+  warn(msg, meta) {
+    this.emit("warn", msg, meta);
   }
-  if (obj.autoRun !== void 0) {
-    if (typeof obj.autoRun !== "boolean") return { error: "autoRun must be a boolean" };
-    out.autoRun = obj.autoRun;
+  error(msg, meta) {
+    this.emit("error", msg, meta);
   }
-  if (obj.debug !== void 0) {
-    if (typeof obj.debug !== "boolean") return { error: "debug must be a boolean" };
-    out.debug = obj.debug && kind === "fix";
+  /** Replace options in place; every existing child logger picks the change up. */
+  configure(patch) {
+    const prev = this.core.options;
+    const next = { ...prev, ...patch };
+    this.core.options = next;
+    const sinkChanged = next.dir !== prev.dir || next.fileName !== prev.fileName || next.maxBytes !== prev.maxBytes || next.maxArchives !== prev.maxArchives;
+    if (sinkChanged) this.core.sink = createSink(next);
   }
-  return out;
-}
-function parseAnnotateBody(body) {
-  if (!body || typeof body !== "object") return { error: "body must be an object" };
-  const obj = body;
-  if (obj.kind !== "annotate") {
-    return { error: 'kind must be "annotate"' };
+  async flush() {
+    await this.core.sink.flush();
   }
-  const sectionPath = obj.sectionPath;
-  const quote = obj.quote;
-  const note = obj.note;
-  if (typeof sectionPath !== "string" || !sectionPath.trim()) {
-    return { error: "sectionPath required" };
+  emit(level, msg, meta) {
+    const { options } = this.core;
+    if (LEVEL_WEIGHT[level] < LEVEL_WEIGHT[options.level]) return;
+    const line = `[${(/* @__PURE__ */ new Date()).toISOString()}] [${level}] [${this.scope}] ${msg}${formatMeta(meta)}
+`;
+    if (options.mirrorConsole) mirror(level, line);
+    this.core.sink.write(line);
   }
-  if (typeof quote !== "string" || !quote.trim()) return { error: "quote required" };
-  if (typeof note !== "string" || !note.trim()) return { error: "note required" };
-  if (sectionPath.length > 200) return { error: "sectionPath too long (max 200)" };
-  if (quote.length > 2e3) return { error: "quote too long (max 2000)" };
-  if (note.length > 2e3) return { error: "note too long (max 2000)" };
-  return { sectionPath, quote, note };
 }
-const KINDS = ["claude", "codex", "opencode"];
-const DRAFT_ID_RE = /^[a-zA-Z0-9-]{1,64}$/;
-function buildChatPrompt(prompt, draftId, attachments) {
-  if (attachments.length === 0) return prompt;
-  const dir = `.yorz/tmp/drafts/${draftId}/attachments`;
-  const lines = attachments.map((a) => {
-    const rel = `${dir}/${a.storedName}`;
-    return a.kind === "image" ? `- ![${a.name}](${rel})` : `- [${a.name}](${rel})`;
-  });
-  return [
-    prompt,
-    "",
-    "---",
-    `本次消息附带 ${attachments.length} 个附件，已保存在临时目录 \`${dir}/\`（请按需用文件工具直接读取，无需迁移）：`,
-    ...lines
-  ].join("\n");
+function mirror(level, line) {
+  const text = line.endsWith("\n") ? line.slice(0, -1) : line;
+  try {
+    if (level === "error") console.error(text);
+    else if (level === "warn") console.warn(text);
+    else console.log(text);
+  } catch {
+  }
 }
-function createSessionsRoutes(resolveProject) {
+function createLogger(patch = {}) {
+  const options = { ...defaultOptions(), ...patch };
+  return new Logger({ options, sink: createSink(options) }, "yorz");
+}
+let singleton = null;
+function getLogger() {
+  if (!singleton) singleton = createLogger();
+  return singleton;
+}
+function configureLogger(patch) {
+  const logger = getLogger();
+  logger.configure(patch);
+  return logger;
+}
+function createSpecsRoutes(resolveProject) {
   const app = new Hono();
   const need = async (c) => {
     const id = c.req.param("projectId") ?? "";
@@ -1048,266 +986,550 @@ function createSessionsRoutes(resolveProject) {
     if (!project) return c.json({ error: "project not found" }, 404);
     return project;
   };
-  app.get("/projects/:projectId/sessions", async (c) => {
+  app.get("/projects/:projectId/specs", async (c) => {
     const p = await need(c);
     if (p instanceof Response) return p;
-    return c.json(await p.sessions.listSessions());
+    const items = await p.store.list();
+    return c.json(items);
   });
-  app.post("/projects/:projectId/sessions", async (c) => {
+  app.post("/projects/:projectId/specs", async (c) => {
     const p = await need(c);
     if (p instanceof Response) return p;
-    let body = {};
+    let body;
     try {
       body = await c.req.json();
     } catch {
+      return c.json({ error: "invalid JSON body" }, 400);
+    }
+    const input = parseCreateBody(body);
+    if ("error" in input) return c.json({ error: input.error }, 400);
+    if (!input.title && input.requirement) {
+      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);
+      handle.onDone((finalSessionId) => {
+        void bindDraftSessionToCreatedSpec(p, beforeIds, finalSessionId);
+      });
+      return c.json({ runId: handle.runId, sessionId, draft: true }, 202);
     }
-    const kind = KINDS.includes(body.agentKind) ? body.agentKind : void 0;
-    const title = typeof body.title === "string" ? body.title : void 0;
     try {
-      const created = await p.sessions.createSession(kind, title);
-      return c.json(created, 201);
+      const { id, path } = await p.store.create(input);
+      return c.json({ id, path }, 201);
     } catch (err) {
-      return c.json({ error: err.message }, 500);
+      return c.json({ error: err.message }, 400);
     }
   });
-  app.get("/projects/:projectId/specs/:id/session", async (c) => {
+  app.get("/projects/:projectId/specs/:id", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const detail = await p.store.read(c.req.param("id"));
+    if (!detail) return c.json({ error: "spec not found" }, 404);
+    return c.json(detail);
+  });
+  app.patch("/projects/:projectId/specs/:id/stage", 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);
+    let body;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: "invalid JSON body" }, 400);
+    }
+    const stage = body && typeof body === "object" ? body.stage : void 0;
+    if (stage !== "plan" && stage !== "tasks" && stage !== "execute" && stage !== "done") {
+      return c.json({ error: "stage must be plan | tasks | execute | done" }, 400);
+    }
+    try {
+      await p.store.setStage(specId, stage);
+      return c.json({ ok: true });
+    } catch (err) {
+      return c.json({ error: err.message }, 404);
+    }
+  });
+  app.get("/projects/:projectId/specs/:id/attachments/:name", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const id = c.req.param("id");
+    const name2 = c.req.param("name");
+    if (!isSafeAttachmentName(name2)) {
+      return c.json({ error: "invalid attachment name" }, 400);
+    }
+    const detail = await p.store.read(id);
     if (!detail) return c.json({ error: "spec not found" }, 404);
+    const file = join(p.specsDir, id, "attachments", name2);
+    if (!existsSync(file)) return c.json({ error: "attachment not found" }, 404);
+    const ext = extname(name2).toLowerCase();
+    const mime = mimeForExt(ext);
+    const kind = classifyMime(mime);
+    const data = await readFile(file);
+    c.header("Content-Type", mime);
+    c.header(
+      "Content-Disposition",
+      kind === "image" || kind === "pdf" || kind === "text" ? "inline" : "attachment"
+    );
+    c.header("Cache-Control", "max-age=300");
+    return c.body(new Uint8Array(data));
+  });
+  app.post("/projects/:projectId/specs/:id/inputs", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    let body;
     try {
-      const found = await p.sessions.findSessionForSpec(specId);
-      if (!found) return c.json({ sessionId: null, kind: null, running: false });
-      return c.json({ ...found, running: p.sessions.isRunning(found.sessionId) });
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: "invalid JSON body" }, 400);
+    }
+    const parsed = parseAnnotateBody(body);
+    if ("error" in parsed) return c.json({ error: parsed.error }, 400);
+    try {
+      await p.store.appendAnnotation(c.req.param("id"), parsed);
+      return c.json({ ok: true });
     } catch (err) {
-      return c.json({ error: err.message }, 500);
+      return c.json({ error: err.message }, 404);
     }
   });
-  app.get("/projects/:projectId/sessions/:sid/messages", async (c) => {
+  app.post("/projects/:projectId/specs/:id/questions/answers", async (c) => {
     const p = await need(c);
     if (p instanceof Response) return p;
+    let body;
     try {
-      return c.json(await p.sessions.getMessages(c.req.param("sid")));
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: "invalid JSON body" }, 400);
+    }
+    const parsed = parseQuestionAnswersBody(body);
+    if ("error" in parsed) return c.json({ error: parsed.error }, 400);
+    try {
+      await p.store.applyQuestionAnswers(c.req.param("id"), parsed);
+      return c.json({ ok: true });
     } catch (err) {
-      return c.json({ error: err.message }, 500);
+      const msg = err.message;
+      const status = /spec not found/.test(msg) ? 404 : 400;
+      return c.json({ error: msg }, status);
     }
   });
-  app.post("/projects/:projectId/sessions/:sid/messages", async (c) => {
+  app.post("/projects/:projectId/specs/:id/appends", async (c) => {
     const p = await need(c);
     if (p instanceof Response) return p;
-    let body = {};
+    const specId = c.req.param("id");
+    let body;
     try {
       body = await c.req.json();
     } catch {
       return c.json({ error: "invalid JSON body" }, 400);
     }
-    const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
-    if (!prompt) return c.json({ error: "prompt required" }, 400);
-    let finalPrompt = prompt;
-    if (body.draftId !== void 0) {
-      if (typeof body.draftId !== "string" || !DRAFT_ID_RE.test(body.draftId)) {
-        return c.json({ error: "draftId has invalid format" }, 400);
-      }
-      const draftId = body.draftId;
-      if (await p.attachments.draftExists(draftId)) {
-        const metas = await p.attachments.listAttachments(draftId);
-        finalPrompt = buildChatPrompt(prompt, draftId, metas);
-      }
+    const parsed = parseAppendBody(body);
+    if ("error" in parsed) return c.json({ error: parsed.error }, 400);
+    const detail = await p.store.read(specId);
+    if (!detail) return c.json({ error: "spec not found" }, 404);
+    try {
+      await p.store.appendItem(specId, {
+        kind: parsed.kind,
+        description: parsed.description,
+        sectionPath: parsed.sectionPath,
+        quote: parsed.quote
+      });
+    } catch (err) {
+      return c.json({ error: err.message }, 400);
     }
-    const handle = await p.sessions.send(c.req.param("sid"), finalPrompt);
-    return c.json({ runId: handle.runId, sessionId: handle.sessionId }, 202);
+    if (parsed.autoRun) {
+      const { sessionId } = await p.sessions.ensureSessionForSpec(specId);
+      const debugActive = await readDebugMdStatus(join(p.specsDir, specId)) === "debugging";
+      const prompt = parsed.debug ? buildDebugPrompt(p.specsDirRelative, specId, "new", await buildDebugRuntimeContext(p)) : debugActive ? buildDebugPrompt(
+        p.specsDirRelative,
+        specId,
+        "resume",
+        await buildDebugRuntimeContext(p)
+      ) : `请使用 yorz-spec skill 处理 spec：${p.specsDirRelative}/${specId}/spec.md`;
+      const handle = await p.sessions.send(sessionId, prompt);
+      return c.json({ ok: true, runId: handle.runId, sessionId });
+    }
+    return c.json({ ok: true });
   });
-  app.post("/projects/:projectId/sessions/:sid/abort", async (c) => {
+  app.post("/projects/:projectId/specs/:id/run", async (c) => {
     const p = await need(c);
     if (p instanceof Response) return p;
-    const ok = await p.sessions.abort(c.req.param("sid"));
-    return c.json({ aborted: ok });
+    const specId = c.req.param("id");
+    const detail = await p.store.read(specId);
+    if (!detail) return c.json({ error: "spec not found" }, 404);
+    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)) : `请使用 yorz-spec skill 处理 spec：${p.specsDirRelative}/${specId}/spec.md`;
+    const handle = await p.sessions.send(sessionId, prompt);
+    return c.json({ runId: handle.runId, sessionId });
   });
-  return app;
-}
-const execFileP$1 = promisify(execFile);
-class GitError extends Error {
-  code;
-  stderr;
-  constructor(code, message, stderr = "") {
-    super(message);
-    this.name = "GitError";
-    this.code = code;
-    this.stderr = stderr;
-  }
-}
-const STATUS_FROM_CODE = {
-  " M": "M",
-  "M ": "M",
-  MM: "M",
-  " A": "A",
-  "A ": "A",
-  AM: "A",
-  " D": "D",
-  "D ": "D",
-  " R": "R",
-  "R ": "R",
-  "??": "??"
-};
-function classifyStatus(index, worktree) {
-  const key = `${index}${worktree}`;
-  if (STATUS_FROM_CODE[key]) return STATUS_FROM_CODE[key];
-  if (index === "?" && worktree === "?") return "??";
-  if (worktree === "M") return "M";
-  if (worktree === "D") return "D";
-  if (index === "A") return "A";
-  if (index === "M") return "M";
-  if (index === "D") return "D";
-  if (index === "R") return "R";
-  return index === " " ? worktree : index;
-}
-function assertSafeRelativePath(cwd, p) {
-  if (typeof p !== "string" || p.length === 0) {
-    throw new GitError("invalid_path", "path must be a non-empty string");
-  }
-  if (p.startsWith("/")) {
-    throw new GitError("invalid_path", `absolute path not allowed: ${p}`);
-  }
-  if (p.split(/[\\/]/).some((seg) => seg === "..")) {
-    throw new GitError("invalid_path", `parent traversal not allowed: ${p}`);
-  }
-  const absolute = resolve(cwd, p);
-  const cwdWithSep = cwd.endsWith(sep) ? cwd : `${cwd}${sep}`;
-  if (absolute !== cwd && !absolute.startsWith(cwdWithSep)) {
-    throw new GitError("invalid_path", `path escapes cwd: ${p}`);
+  app.post("/projects/:projectId/specs/:id/explain", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const specId = c.req.param("id");
+    let body;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: "invalid JSON body" }, 400);
+    }
+    const text = body && typeof body === "object" ? body.text : void 0;
+    if (typeof text !== "string" || !text.trim()) {
+      return c.json({ error: "text required" }, 400);
+    }
+    if (text.length > 4e3) {
+      return c.json({ error: "text too long (max 4000)" }, 400);
+    }
+    const detail = await p.store.read(specId);
+    if (!detail) return c.json({ error: "spec not found" }, 404);
+    const prompt = `以下为 spec 文档 ${p.specsDirRelative}/${specId}/spec.md 中的一段内容。
+请用中文简洁解释其含义、背景与可能的实施影响。**不要**修改任何文件，只在终端输出解释文本。
+
+引用：
+"""
+${text}
+"""
+`;
+    const { sessionId } = await p.sessions.ensureSessionForSpec(specId);
+    const handle = await p.sessions.send(sessionId, prompt);
+    return c.json({ runId: handle.runId, sessionId });
+  });
+  app.delete("/projects/:projectId/specs/:id", 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);
+    await p.store.delete(specId);
+    return c.json({ ok: true });
+  });
+  return app;
+}
+function buildDraftPrompt(type2, requirement, draftId) {
+  const lines = [
+    "请按 yorz-spec skill 的「新建 spec」流程，根据下方信息创建新的 spec 文档，并立即按 plan 阶段继续推进直至阻塞。",
+    "",
+    `类型：${type2}（已由调用方指定，不要再询问）`,
+    "需求：",
+    '"""',
+    requirement.trim(),
+    '"""',
+    "",
+    "硬性要求：",
+    `- 生成 kebab-case summary-name 时只使用对需求有语义代表性的英文/数字字符；如难以从中文中提炼出可读 slug，请直接使用 \`untitled-\` + 3 位日期内自增编号占位，禁止把中文挤压为零散英文片段（例如禁止出现 \`spec-agent-spec-agent\` 之类的拼接）。`,
+    "- frontmatter.summary 必须是对需求的真实概述（≤200 字符），不要原样照搬整段需求。",
+    "- 完成 spec 文件初始化后立即进入 plan 阶段，按 SKILL 规则补齐 `现状分析` / `技术实现方案` / `待确认项`，再视需要进入 tasks/execute。"
+  ];
+  if (draftId) {
+    lines.push(
+      "",
+      `附件迁移：本次新建 spec 关联了草稿附件目录 \`.yorz/tmp/drafts/${draftId}/attachments/\`。`,
+      "- 在创建 `.yorz/specs/<id>/` 目录并写入 `spec.md` 骨架**之后**，立即把该 draft 目录下的所有文件迁移到 `.yorz/specs/<id>/attachments/`，文件名保持不变。",
+      "- 迁移完成后，在 `## 背景` 章节末尾追加一段附件列表，每个附件占一行（按文件扩展名判定 `kind`）：",
+      "  - 图片（`.png` / `.jpg` / `.jpeg` / `.gif` / `.webp` / `.bmp` / `.svg` / `.avif` / `.heic`）：使用 `![<文件名>](attachments/<文件名>)`",
+      "  - PDF（`.pdf`） / 文本（`.txt` / `.md` / `.markdown`）：使用 `[<文件名>](attachments/<文件名>)`",
+      "- 迁移失败（如 draft 目录已被清理、权限不足）时，**不要静默丢弃**：在 `## 待确认项` 章节追加一条记录说明问题，并退出本轮等待用户介入。"
+    );
   }
-  return p;
+  return lines.join("\n");
 }
-async function runGit(cwd, args) {
+async function bindDraftSessionToCreatedSpec(project, beforeIds, sessionId) {
   try {
-    const result = await execFileP$1("git", args, {
-      cwd,
-      encoding: "utf8",
-      maxBuffer: 16 * 1024 * 1024
-    });
-    return { stdout: result.stdout, stderr: result.stderr };
-  } catch (err) {
-    const e = err;
-    if (e.code === "ENOENT") {
-      throw new GitError("git_missing", "git not found on PATH");
+    const created = (await project.store.list()).filter((s) => !beforeIds.has(s.id));
+    if (created.length !== 1) {
+      getLogger().child("agent").warn("skip draft session binding", {
+        sessionId,
+        createdCount: created.length
+      });
+      return;
     }
-    throw new GitError("git_failed", `git ${args[0]} failed`, e.stderr ?? e.message);
+    const [spec] = created;
+    const ok = await project.sessions.bindSessionToSpec(
+      sessionId,
+      spec.id,
+      formatSpecSessionTitle(spec.id, spec.summary)
+    );
+    if (!ok) {
+      getLogger().child("agent").warn("draft session binding target missing", {
+        sessionId,
+        specId: spec.id
+      });
+    }
+  } catch (err) {
+    getLogger().child("agent").warn("draft session binding failed", {
+      sessionId,
+      message: err instanceof Error ? err.message : String(err)
+    });
   }
 }
-async function runGitChecked(cwd, args) {
-  return runGit(cwd, args);
+function formatSpecSessionTitle(specId, summary) {
+  const s = summary.trim();
+  return s ? `${specId} · ${s}` : specId;
 }
-async function runGitRaw(cwd, args) {
+async function readDebugMdStatus(specDir) {
+  const file = join(specDir, "debug.md");
+  let text;
   try {
-    const result = await execFileP$1("git", args, {
-      cwd,
-      encoding: "utf8",
-      maxBuffer: 16 * 1024 * 1024
-    });
-    return { stdout: result.stdout, stderr: result.stderr, code: 0 };
-  } catch (err) {
-    const e = err;
-    if (e.code === "ENOENT") {
-      throw new GitError("git_missing", "git not found on PATH");
-    }
-    const code = typeof e.code === "number" ? e.code : 1;
-    return { stdout: e.stdout ?? "", stderr: e.stderr ?? e.message ?? "", code };
+    text = await readFile(file, "utf8");
+  } catch {
+    return null;
   }
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return null;
+  const statusLine = m[1].split(/\r?\n/).find((l) => /^status\s*:/.test(l.trim()));
+  if (!statusLine) return null;
+  const val = statusLine.slice(statusLine.indexOf(":") + 1).trim().replace(/^['"]|['"]$/g, "");
+  return val === "debugging" ? "debugging" : val === "resolved" ? "resolved" : null;
 }
-async function listChanges(cwd) {
-  const { stdout } = await runGit(cwd, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
-  return parsePorcelain(stdout);
+function buildDebugPrompt(specsDirRelative, specId, mode, runtimeContext = "") {
+  const specPath = `${specsDirRelative}/${specId}/spec.md`;
+  const debugPath = `${specsDirRelative}/${specId}/debug.md`;
+  if (mode === "resume") {
+    return `请使用 yorz-debug skill 继续调试：spec 目录 ${specsDirRelative}/${specId}（含 ${specPath}）。该目录下已存在处于 debugging 状态的 ${debugPath}，请定位其活跃记录块（frontmatter active 指向的 ## Debug NNN）继续「假设 → 取证 → 验证」循环，勿新建记录块。` + runtimeContext;
+  }
+  return `请使用 yorz-debug skill 进入 Debug 模式：spec 目录 ${specsDirRelative}/${specId}（含 ${specPath}）。若 ${debugPath} 不存在则创建，否则在文末追加新的 ## Debug 记录块；进入后立即 git stash create 打快照写入 Debug 基线，再开始「假设 → 取证 → 验证」循环。` + runtimeContext;
 }
-function parsePorcelain(raw) {
-  const out = [];
-  if (!raw) return out;
-  const records = raw.split("\0");
-  for (let i = 0; i < records.length; i++) {
-    const rec = records[i];
-    if (!rec) continue;
-    if (rec.length < 3) continue;
-    const index = rec[0];
-    const worktree = rec[1];
-    const path = rec.slice(3);
-    const change = {
-      path,
-      index,
-      worktree,
-      status: classifyStatus(index, worktree)
-    };
-    if (index === "R" || worktree === "R") {
-      const from = records[i + 1] ?? "";
-      change.renamedFrom = from;
-      i += 1;
+async function buildDebugRuntimeContext(project) {
+  return formatDebugRuntimeContext(await project.commands.listRuns());
+}
+function formatDebugRuntimeContext(runs) {
+  const running = runs.filter((r) => r.status === "running");
+  if (running.length === 0) {
+    return "\n\n当前项目运行服务上下文：暂无运行中的命令服务。若复现需要服务，请根据项目脚本自行启动，或请用户在 GUI 命令菜单启动后重试。";
+  }
+  const lines = ["\n\n当前项目运行服务上下文："];
+  for (const run of running) {
+    lines.push(
+      `- runId: ${promptScalar(run.runId)}`,
+      `  name: ${promptScalar(run.name)}`,
+      `  cli: ${promptScalar(run.cli)}`,
+      `  status: ${run.status}`,
+      `  pid: ${run.pid}`,
+      `  startedAt: ${new Date(run.startedAt).toISOString()}`,
+      `  logFile: ${promptScalar(run.logFile)}`
+    );
+  }
+  return lines.join("\n");
+}
+function promptScalar(value) {
+  return value.replace(/\r?\n/g, "\\n");
+}
+function parseCreateBody(body) {
+  if (!body || typeof body !== "object") return { error: "body must be an object" };
+  const obj = body;
+  const rawType = obj.type ?? "feat";
+  if (rawType !== "feat" && rawType !== "refct" && rawType !== "fix") {
+    return { error: "type must be feat | refct | fix" };
+  }
+  const out = { type: rawType };
+  if (typeof obj.title === "string" && obj.title.trim()) out.title = obj.title;
+  if (typeof obj.summary === "string" && obj.summary.trim()) out.summary = obj.summary;
+  if (typeof obj.requirement === "string" && obj.requirement.trim()) {
+    out.requirement = obj.requirement;
+  }
+  if (obj.draftId !== void 0) {
+    if (typeof obj.draftId !== "string" || !obj.draftId.trim()) {
+      return { error: "draftId must be a non-empty string" };
     }
-    out.push(change);
+    if (!/^[a-zA-Z0-9-]{1,64}$/.test(obj.draftId)) {
+      return { error: "draftId has invalid format" };
+    }
+    out.draftId = obj.draftId;
   }
   return out;
 }
-async function partitionPathsByStatus(cwd, paths) {
-  const all = await listChanges(cwd);
-  const byPath = new Map(all.map((c) => [c.path, c]));
-  const result = { tracked: [], untracked: [], renamed: [] };
-  for (const p of paths) {
-    const change = byPath.get(p);
-    if (!change) continue;
-    if (change.status === "??") {
-      result.untracked.push(p);
-    } else if (change.renamedFrom) {
-      result.renamed.push({ path: p, renamedFrom: change.renamedFrom });
-    } else {
-      result.tracked.push(p);
+function isSafeAttachmentName(name2) {
+  if (!name2) return false;
+  if (name2.includes("/") || name2.includes("\\")) return false;
+  if (name2 === "." || name2 === "..") return false;
+  if (name2.startsWith(".")) return false;
+  return true;
+}
+function parseQuestionAnswersBody(body) {
+  if (!body || typeof body !== "object") return { error: "body must be an object" };
+  const obj = body;
+  const rawAnswers = obj.answers;
+  const rawFreeforms = obj.freeformAnnotations;
+  if (rawAnswers !== void 0 && !Array.isArray(rawAnswers)) {
+    return { error: "answers must be an array" };
+  }
+  if (rawFreeforms !== void 0 && !Array.isArray(rawFreeforms)) {
+    return { error: "freeformAnnotations must be an array" };
+  }
+  const answers = [];
+  for (const a of rawAnswers ?? []) {
+    if (!a || typeof a !== "object") return { error: "answer must be an object" };
+    const ao = a;
+    if (typeof ao.questionText !== "string" || !ao.questionText.trim()) {
+      return { error: "answer.questionText required" };
+    }
+    const item = { questionText: ao.questionText };
+    if (typeof ao.questionId === "string") item.questionId = ao.questionId;
+    if (typeof ao.selectedOptionLabel === "string" && ao.selectedOptionLabel.trim()) {
+      item.selectedOptionLabel = ao.selectedOptionLabel;
+    }
+    if (typeof ao.note === "string" && ao.note.trim()) item.note = ao.note;
+    if (!item.selectedOptionLabel && !item.note) {
+      return { error: "answer requires selectedOptionLabel or note" };
     }
+    answers.push(item);
   }
-  return result;
-}
-async function commit(cwd, opts) {
-  const message = opts.message?.trim() ?? "";
-  if (!message) throw new GitError("invalid_message", "commit message must not be empty");
-  if (!Array.isArray(opts.paths) || opts.paths.length === 0) {
-    throw new GitError("no_paths", "commit requires at least one path");
+  const freeformAnnotations = [];
+  for (const f of rawFreeforms ?? []) {
+    if (!f || typeof f !== "object") return { error: "freeformAnnotation must be an object" };
+    const fo = f;
+    if (typeof fo.sectionPath !== "string" || !fo.sectionPath.trim()) {
+      return { error: "freeformAnnotation.sectionPath required" };
+    }
+    if (typeof fo.quote !== "string" || !fo.quote.trim()) {
+      return { error: "freeformAnnotation.quote required" };
+    }
+    if (typeof fo.note !== "string" || !fo.note.trim()) {
+      return { error: "freeformAnnotation.note required" };
+    }
+    freeformAnnotations.push({
+      sectionPath: fo.sectionPath,
+      quote: fo.quote,
+      note: fo.note
+    });
   }
-  for (const p of opts.paths) assertSafeRelativePath(cwd, p);
-  const { renamed } = await partitionPathsByStatus(cwd, opts.paths);
-  const extraPaths = renamed.map((r) => r.renamedFrom);
-  const allPaths = [...opts.paths, ...extraPaths];
-  await runGit(cwd, ["add", "--", ...allPaths]);
-  await runGit(cwd, ["commit", "-m", message, "--", ...allPaths]);
-  const { stdout } = await runGit(cwd, ["rev-parse", "HEAD"]);
-  return { commit: stdout.trim() };
+  if (answers.length === 0 && freeformAnnotations.length === 0) {
+    return { error: "answers or freeformAnnotations required" };
+  }
+  return { answers, freeformAnnotations };
 }
-async function discard(cwd, opts) {
-  if (!Array.isArray(opts.paths) || opts.paths.length === 0) {
-    throw new GitError("no_paths", "discard requires at least one path");
+function parseAppendBody(body) {
+  if (!body || typeof body !== "object") return { error: "body must be an object" };
+  const obj = body;
+  const kind = obj.kind;
+  if (kind !== "feat" && kind !== "refct" && kind !== "fix") {
+    return { error: "kind must be feat | refct | fix" };
+  }
+  if (typeof obj.description !== "string" || !obj.description.trim()) {
+    return { error: "description required" };
+  }
+  const out = { kind, description: obj.description, autoRun: true, debug: false };
+  if (obj.sectionPath !== void 0) {
+    if (typeof obj.sectionPath !== "string") return { error: "sectionPath must be a string" };
+    if (obj.sectionPath.length > 200) return { error: "sectionPath too long (max 200)" };
+    if (obj.sectionPath.trim()) out.sectionPath = obj.sectionPath;
+  }
+  if (obj.quote !== void 0) {
+    if (typeof obj.quote !== "string") return { error: "quote must be a string" };
+    if (obj.quote.length > 500) return { error: "quote too long (max 500)" };
+    if (obj.quote.trim()) out.quote = obj.quote;
+  }
+  if (obj.autoRun !== void 0) {
+    if (typeof obj.autoRun !== "boolean") return { error: "autoRun must be a boolean" };
+    out.autoRun = obj.autoRun;
   }
-  for (const p of opts.paths) assertSafeRelativePath(cwd, p);
-  const { tracked, untracked, renamed } = await partitionPathsByStatus(cwd, opts.paths);
-  if (tracked.length) {
-    await runGit(cwd, ["restore", "--staged", "--worktree", "--", ...tracked]);
+  if (obj.debug !== void 0) {
+    if (typeof obj.debug !== "boolean") return { error: "debug must be a boolean" };
+    out.debug = obj.debug && kind === "fix";
   }
-  if (untracked.length) {
-    await runGit(cwd, ["clean", "-fd", "--", ...untracked]);
+  return out;
+}
+function parseAnnotateBody(body) {
+  if (!body || typeof body !== "object") return { error: "body must be an object" };
+  const obj = body;
+  if (obj.kind !== "annotate") {
+    return { error: 'kind must be "annotate"' };
   }
-  for (const r of renamed) {
-    await runGitRaw(cwd, ["reset", "-q", "HEAD", "--", r.renamedFrom, r.path]);
-    await runGit(cwd, ["restore", "--worktree", "--", r.renamedFrom]);
-    await runGit(cwd, ["clean", "-fd", "--", r.path]);
+  const sectionPath = obj.sectionPath;
+  const quote = obj.quote;
+  const note = obj.note;
+  if (typeof sectionPath !== "string" || !sectionPath.trim()) {
+    return { error: "sectionPath required" };
   }
+  if (typeof quote !== "string" || !quote.trim()) return { error: "quote required" };
+  if (typeof note !== "string" || !note.trim()) return { error: "note required" };
+  if (sectionPath.length > 200) return { error: "sectionPath too long (max 200)" };
+  if (quote.length > 2e3) return { error: "quote too long (max 2000)" };
+  if (note.length > 2e3) return { error: "note too long (max 2000)" };
+  return { sectionPath, quote, note };
 }
-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");
+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;
+function isYorzDebugCommand(prompt) {
+  return /^\/yorz-debug(?:\s|$)/.test(prompt.trim());
+}
+function buildChatDebugPrompt(prompt, now = /* @__PURE__ */ new Date()) {
+  const body = prompt.trim().replace(/^\/yorz-debug(?:\s+|$)/, "").trim();
+  const debugPath = `${CHAT_DEBUG_DIR_REL}/debug-${formatDebugTimestamp(now)}.md`;
+  const bug = body || "请先根据对话上下文确认待调试问题；若上下文不足，请向用户补齐复现信息。";
+  return [
+    `请使用 yorz-debug skill 进入 Debug 模式。`,
+    `本次是普通 chat 独立触发，没有 spec_dir。Debug 活文档必须写入临时文件 \`${debugPath}\`。`,
+    `写入前请确保目录 \`${CHAT_DEBUG_DIR_REL}/\` 存在；该目录属于临时目录，会由 YorZ 定时清理。`,
+    `如果该文件不存在则创建；本文件只承载本次 chat debug 记录，不需要追加复用其他文件。`,
+    "",
+    "待调试问题：",
+    bug
+  ].join("\n");
+}
+async function cleanupExpiredChatDebugFiles(projectPath, opts = {}) {
+  const root = join(projectPath, CHAT_DEBUG_DIR_REL);
+  if (!existsSync(root)) return { removed: [] };
+  const removed = [];
+  const cutoff = (opts.now ?? Date.now()) - (opts.ttlMs ?? CHAT_DEBUG_RETENTION_MS);
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return { removed };
   }
-  for (const p of opts.paths) assertSafeRelativePath(cwd, p);
-  const { renamed } = await partitionPathsByStatus(cwd, opts.paths);
-  const extraPaths = renamed.map((r) => r.renamedFrom);
-  const allPaths = [...opts.paths, ...extraPaths];
-  const message = opts.message?.trim() || "yorz:stash";
-  await runGit(cwd, ["stash", "push", "--include-untracked", "-m", message, "--", ...allPaths]);
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const file = join(root, entry.name);
+    try {
+      const s = await stat(file);
+      if (s.mtimeMs <= cutoff) {
+        await rm(file, { force: true });
+        removed.push(entry.name);
+      }
+    } catch {
+    }
+  }
+  return { removed };
 }
-const VALID_ACTIONS = /* @__PURE__ */ new Set(["commit", "discard", "stash"]);
-function createSpecReviewRoutes(resolveProject) {
+function scheduleChatDebugCleanup(projectPath) {
+  void mkdir(join(projectPath, CHAT_DEBUG_DIR_REL), { recursive: true }).then(() => cleanupExpiredChatDebugFiles(projectPath)).catch(() => {
+  });
+  const timer = setInterval(() => {
+    void cleanupExpiredChatDebugFiles(projectPath).catch(() => {
+    });
+  }, CHAT_DEBUG_CLEANUP_INTERVAL_MS);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}
+function formatDebugTimestamp(date) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate()),
+    "-",
+    pad(date.getHours()),
+    pad(date.getMinutes()),
+    pad(date.getSeconds())
+  ].join("");
+}
+const KINDS = ["claude", "codex", "opencode"];
+const DRAFT_ID_RE = /^[a-zA-Z0-9-]{1,64}$/;
+function buildChatPrompt(prompt, draftId, attachments) {
+  if (attachments.length === 0) return prompt;
+  const dir = `.yorz/tmp/drafts/${draftId}/attachments`;
+  const lines = attachments.map((a) => {
+    const rel = `${dir}/${a.storedName}`;
+    return a.kind === "image" ? `- ![${a.name}](${rel})` : `- [${a.name}](${rel})`;
+  });
+  return [
+    prompt,
+    "",
+    "---",
+    `本次消息附带 ${attachments.length} 个附件，已保存在临时目录 \`${dir}/\`（请按需用文件工具直接读取，无需迁移）：`,
+    ...lines
+  ].join("\n");
+}
+function createSessionsRoutes(resolveProject) {
   const app = new Hono();
   const need = async (c) => {
     const id = c.req.param("projectId") ?? "";
@@ -1316,541 +1538,453 @@ function createSpecReviewRoutes(resolveProject) {
     if (!project) return c.json({ error: "project not found" }, 404);
     return project;
   };
-  app.post("/projects/:projectId/specs/:id/review", async (c) => {
+  app.get("/projects/:projectId/sessions", 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);
-    const specRel = `${p.specsDirRelative}/${specId}/spec.md`;
-    const reviewRel = `${p.specsDirRelative}/${specId}/review.md`;
-    const prompt = `请使用 yorz-spec skill 的 "Review / Git Ops 阶段" 流程处理本次 review：
-- spec 文档：${specRel}
-- 输出文件：${reviewRel}（追加新二级标题条目，禁止覆盖历史）
-- 必含 4 节：变更总结 / 影响范围 / 风险提醒 / 变更文件清单
-- 触发时间使用本机当前时间，格式 \`YYYY-MM-DD HH:mm:ss\`
-`;
-    const { sessionId } = await p.sessions.ensureSessionForSpec(specId);
-    const handle = await p.sessions.send(sessionId, prompt);
-    return c.json({ runId: handle.runId, sessionId });
+    return c.json(await p.sessions.listSessions());
   });
-  app.post("/projects/:projectId/specs/:id/git", async (c) => {
+  app.post("/projects/:projectId/sessions", 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;
+    let body = {};
     try {
       body = await c.req.json();
     } catch {
-      return c.json({ error: "invalid JSON body" }, 400);
-    }
-    const action = body && typeof body === "object" ? body.action : null;
-    if (!action || typeof action !== "string" || !VALID_ACTIONS.has(action)) {
-      return c.json({ error: "action must be one of commit | discard | stash" }, 400);
-    }
-    const specRel = `${p.specsDirRelative}/${specId}/spec.md`;
-    const reviewRel = `${p.specsDirRelative}/${specId}/review.md`;
-    const prompt = buildGitOpsPrompt(action, specId, specRel, reviewRel);
-    const { sessionId } = await p.sessions.ensureSessionForSpec(specId);
-    const handle = await p.sessions.send(sessionId, prompt);
-    return c.json({ runId: handle.runId, sessionId });
-  });
-  app.get("/projects/:projectId/specs/:id/review", 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);
-    const file = join(p.specsDir, specId, "review.md");
-    if (!existsSync(file)) return c.json({ text: "" });
-    try {
-      const text = await readFile(file, "utf8");
-      return c.json({ text });
-    } catch {
-      return c.json({ text: "" });
     }
-  });
-  app.get("/projects/:projectId/specs/:id/debug", 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);
-    const file = join(p.specsDir, specId, "debug.md");
-    if (!existsSync(file)) return c.json({ exists: false, text: "" });
+    const kind = KINDS.includes(body.agentKind) ? body.agentKind : void 0;
+    const title = typeof body.title === "string" ? body.title : void 0;
     try {
-      const text = await readFile(file, "utf8");
-      return c.json({ exists: true, text });
-    } catch {
-      return c.json({ exists: false, text: "" });
+      const created = await p.sessions.createSession(kind, title);
+      return c.json(created, 201);
+    } catch (err) {
+      return c.json({ error: err.message }, 500);
     }
   });
-  app.get("/projects/:projectId/specs/:id/changes", async (c) => {
+  app.get("/projects/:projectId/specs/:id/session", 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 });
+      const found = await p.sessions.findSessionForSpec(specId);
+      if (!found) return c.json({ sessionId: null, kind: null, running: false });
+      return c.json({ ...found, running: p.sessions.isRunning(found.sessionId) });
     } catch (err) {
-      if (err instanceof GitError) return c.json({ error: err.message }, 400);
-      throw err;
+      return c.json({ error: err.message }, 500);
     }
   });
-  app.post("/projects/:projectId/specs/:id/commit", async (c) => {
+  app.get("/projects/:projectId/sessions/:sid/messages", 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);
+      return c.json(await p.sessions.getMessages(c.req.param("sid")));
     } catch (err) {
-      if (err instanceof GitError) return c.json({ error: err.message }, 400);
-      throw err;
+      return c.json({ error: err.message }, 500);
     }
   });
-  app.post("/projects/:projectId/specs/:id/discard", async (c) => {
+  app.post("/projects/:projectId/sessions/:sid/messages", 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;
+    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;
+    const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
+    if (!prompt) return c.json({ error: "prompt required" }, 400);
+    let finalPrompt = isYorzDebugCommand(prompt) ? buildChatDebugPrompt(prompt) : prompt;
+    if (body.draftId !== void 0) {
+      if (typeof body.draftId !== "string" || !DRAFT_ID_RE.test(body.draftId)) {
+        return c.json({ error: "draftId has invalid format" }, 400);
+      }
+      const draftId = body.draftId;
+      if (await p.attachments.draftExists(draftId)) {
+        const metas = await p.attachments.listAttachments(draftId);
+        finalPrompt = buildChatPrompt(finalPrompt, draftId, metas);
+      }
     }
+    if (isYorzDebugCommand(prompt)) void cleanupExpiredChatDebugFiles(p.path).catch(() => {
+    });
+    const handle = await p.sessions.send(c.req.param("sid"), finalPrompt);
+    return c.json({ runId: handle.runId, sessionId: handle.sessionId }, 202);
   });
-  app.post("/projects/:projectId/specs/:id/stash", async (c) => {
+  app.post("/projects/:projectId/sessions/:sid/abort", 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 (paths.length === 0) return c.json({ error: "paths must not be empty" }, 400);
-    try {
-      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;
-    }
+    const ok = await p.sessions.abort(c.req.param("sid"));
+    return c.json({ aborted: ok });
   });
   return app;
 }
-function buildGitOpsPrompt(action, specId, specRel, reviewRel) {
-  const base = `请使用 yorz-spec skill 的 "Review / Git Ops 阶段" 流程执行 git 操作：
-- spec 文档：${specRel}
-- 最近一次 review：${reviewRel}（如不存在，请先依据 git status/diff 自行判断本次 spec 关联的变更）
-- spec-id：${specId}
-`;
-  switch (action) {
-    case "commit":
-      return base + `- 动作：git-commit。请基于 review 报告与 git status，由你自主判断本次 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 execFileP$1 = promisify(execFile);
+class GitError extends Error {
+  code;
+  stderr;
+  constructor(code, message, stderr = "") {
+    super(message);
+    this.name = "GitError";
+    this.code = code;
+    this.stderr = stderr;
   }
 }
-const CURRENT_VERSION$1 = 1;
-const DEFAULT_GLOBAL_AGENT = { defaultKind: "claude" };
-const DEFAULT_NOTIFICATIONS = {
-  sessionEnd: { banner: false, sound: false }
+const STATUS_FROM_CODE = {
+  " M": "M",
+  "M ": "M",
+  MM: "M",
+  " A": "A",
+  "A ": "A",
+  AM: "A",
+  " D": "D",
+  "D ": "D",
+  " R": "R",
+  "R ": "R",
+  "??": "??"
 };
-function resolveGlobalConfigDir(env = process.env) {
-  if (env.YORZ_HOME && env.YORZ_HOME.trim()) return env.YORZ_HOME.trim();
-  const xdg = env.XDG_CONFIG_HOME?.trim();
-  const base = xdg && xdg.length > 0 ? xdg : join(homedir(), ".config");
-  return join(base, "yorz");
-}
-function resolveGlobalConfigPath(env = process.env) {
-  return join(resolveGlobalConfigDir(env), "projects.json");
+function classifyStatus(index, worktree) {
+  const key = `${index}${worktree}`;
+  if (STATUS_FROM_CODE[key]) return STATUS_FROM_CODE[key];
+  if (index === "?" && worktree === "?") return "??";
+  if (worktree === "M") return "M";
+  if (worktree === "D") return "D";
+  if (index === "A") return "A";
+  if (index === "M") return "M";
+  if (index === "D") return "D";
+  if (index === "R") return "R";
+  return index === " " ? worktree : index;
 }
-async function loadGlobalConfig(filePath) {
-  const fp = filePath ?? resolveGlobalConfigPath();
-  if (!existsSync(fp)) return defaultGlobalConfig();
-  let raw;
-  try {
-    raw = await readFile(fp, "utf8");
-  } catch {
-    return defaultGlobalConfig();
+function assertSafeRelativePath(cwd, p) {
+  if (typeof p !== "string" || p.length === 0) {
+    throw new GitError("invalid_path", "path must be a non-empty string");
   }
-  if (!raw.trim()) return defaultGlobalConfig();
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return defaultGlobalConfig();
+  if (p.startsWith("/")) {
+    throw new GitError("invalid_path", `absolute path not allowed: ${p}`);
   }
-  return normalizeConfig$1(parsed);
-}
-async function saveGlobalConfig(config, filePath) {
-  const fp = filePath ?? resolveGlobalConfigPath();
-  await mkdir(dirname(fp), { recursive: true });
-  const normalized = normalizeConfig$1(config);
-  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 normalizeConfig$1(value) {
-  if (!value || typeof value !== "object") return defaultGlobalConfig();
-  const obj = value;
-  const projectsRaw = Array.isArray(obj.projects) ? obj.projects : [];
-  const projects = [];
-  for (const item of projectsRaw) {
-    if (!item || typeof item !== "object") continue;
-    const it = item;
-    const id = typeof it.id === "string" ? it.id : "";
-    const path = typeof it.path === "string" ? it.path : "";
-    if (!id || !path) continue;
-    const addedAt = typeof it.addedAt === "string" ? it.addedAt : "";
-    const lastActivityAt = typeof it.lastActivityAt === "string" ? it.lastActivityAt : null;
-    const worktree = normalizeWorktree(it.worktree);
-    const entry = { id, path, addedAt, lastActivityAt };
-    if (worktree) entry.worktree = worktree;
-    projects.push(entry);
+  if (p.split(/[\\/]/).some((seg) => seg === "..")) {
+    throw new GitError("invalid_path", `parent traversal not allowed: ${p}`);
   }
-  return {
-    version: CURRENT_VERSION$1,
-    projects,
-    agent: normalizeAgent$1(obj.agent),
-    notifications: normalizeNotifications(obj.notifications)
-  };
+  const absolute = resolve(cwd, p);
+  const cwdWithSep = cwd.endsWith(sep) ? cwd : `${cwd}${sep}`;
+  if (absolute !== cwd && !absolute.startsWith(cwdWithSep)) {
+    throw new GitError("invalid_path", `path escapes cwd: ${p}`);
+  }
+  return p;
 }
-function defaultGlobalConfig() {
-  return {
-    version: CURRENT_VERSION$1,
-    projects: [],
-    agent: { defaultKind: DEFAULT_GLOBAL_AGENT.defaultKind },
-    notifications: {
-      sessionEnd: {
-        banner: DEFAULT_NOTIFICATIONS.sessionEnd.banner,
-        sound: DEFAULT_NOTIFICATIONS.sessionEnd.sound
-      }
+async function runGit(cwd, args) {
+  try {
+    const result = await execFileP$1("git", args, {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: 16 * 1024 * 1024
+    });
+    return { stdout: result.stdout, stderr: result.stderr };
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") {
+      throw new GitError("git_missing", "git not found on PATH");
     }
-  };
+    throw new GitError("git_failed", `git ${args[0]} failed`, e.stderr ?? e.message);
+  }
 }
-function normalizeAgent$1(value) {
-  if (!value || typeof value !== "object") return { defaultKind: DEFAULT_GLOBAL_AGENT.defaultKind };
-  const obj = value;
-  const defaultKind = obj.defaultKind;
-  if (defaultKind === "opencode" || defaultKind === "codex") return { defaultKind };
-  return { defaultKind: "claude" };
+async function runGitChecked(cwd, args) {
+  return runGit(cwd, args);
 }
-function normalizeNotifications(value) {
-  if (!value || typeof value !== "object") return defaultGlobalConfig().notifications;
-  const obj = value;
-  const sessionEndRaw = obj.sessionEnd;
-  if (!sessionEndRaw || typeof sessionEndRaw !== "object")
-    return defaultGlobalConfig().notifications;
-  const sessionEndObj = sessionEndRaw;
-  return {
-    sessionEnd: {
-      banner: typeof sessionEndObj.banner === "boolean" ? sessionEndObj.banner : DEFAULT_NOTIFICATIONS.sessionEnd.banner,
-      sound: typeof sessionEndObj.sound === "boolean" ? sessionEndObj.sound : DEFAULT_NOTIFICATIONS.sessionEnd.sound
+async function runGitRaw(cwd, args) {
+  try {
+    const result = await execFileP$1("git", args, {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: 16 * 1024 * 1024
+    });
+    return { stdout: result.stdout, stderr: result.stderr, code: 0 };
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") {
+      throw new GitError("git_missing", "git not found on PATH");
     }
-  };
-}
-function normalizeWorktree(value) {
-  if (!value || typeof value !== "object") return void 0;
-  const it = value;
-  const mainProjectId = typeof it.mainProjectId === "string" ? it.mainProjectId : "";
-  const mainPath = typeof it.mainPath === "string" ? it.mainPath : "";
-  const branch = typeof it.branch === "string" ? it.branch : "";
-  const specId = typeof it.specId === "string" ? it.specId : "";
-  const createdAt = typeof it.createdAt === "string" ? it.createdAt : "";
-  if (!mainProjectId || !mainPath || !branch) return void 0;
-  const cleanSlug = typeof it.cleanSlug === "string" ? it.cleanSlug : void 0;
-  const meta = { mainProjectId, mainPath, branch, specId, createdAt };
-  if (cleanSlug) meta.cleanSlug = cleanSlug;
-  return meta;
-}
-function generateProjectId(absPath) {
-  const base = basename$1(absPath);
-  const slug = slugify(base) || "proj";
-  const hash = createHash("sha256").update(absPath).digest("hex").slice(0, 6);
-  return `${slug}-${hash}`;
-}
-function slugify(text) {
-  return text.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/, "");
-}
-async function addProject(absPath, filePath, now = () => /* @__PURE__ */ new Date()) {
-  const config = await loadGlobalConfig(filePath);
-  const existing = config.projects.find((p) => p.path === absPath);
-  if (existing) return { entry: existing, created: false };
-  const entry = {
-    id: generateProjectId(absPath),
-    path: absPath,
-    addedAt: now().toISOString(),
-    lastActivityAt: null
-  };
-  config.projects.push(entry);
-  await saveGlobalConfig(config, filePath);
-  return { entry, created: true };
-}
-async function setProjectWorktree(id, worktree, filePath) {
-  const config = await loadGlobalConfig(filePath);
-  const target = config.projects.find((p) => p.id === id);
-  if (!target) return false;
-  if (worktree) target.worktree = worktree;
-  else delete target.worktree;
-  await saveGlobalConfig(config, filePath);
-  return true;
+    const code = typeof e.code === "number" ? e.code : 1;
+    return { stdout: e.stdout ?? "", stderr: e.stderr ?? e.message ?? "", code };
+  }
 }
-async function removeProject(id, filePath) {
-  const config = await loadGlobalConfig(filePath);
-  const before = config.projects.length;
-  config.projects = config.projects.filter((p) => p.id !== id);
-  if (config.projects.length === before) return false;
-  await saveGlobalConfig(config, filePath);
-  return true;
+async function listChanges(cwd) {
+  const { stdout } = await runGit(cwd, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
+  return parsePorcelain(stdout);
 }
-async function prepareProjectDir(input, cwd) {
-  if (typeof input !== "string" || !input.trim()) {
-    throw new Error("path required");
-  }
-  const trimmed = input.trim();
-  const abs = isAbsolute(trimmed) ? resolve(trimmed) : resolve(cwd ?? process.cwd(), trimmed);
-  if (!existsSync(abs)) {
-    throw new Error(`path does not exist: ${abs}`);
-  }
-  const stats = await stat(abs);
-  if (!stats.isDirectory()) {
-    throw new Error(`path is not a directory: ${abs}`);
+function parsePorcelain(raw) {
+  const out = [];
+  if (!raw) return out;
+  const records = raw.split("\0");
+  for (let i = 0; i < records.length; i++) {
+    const rec = records[i];
+    if (!rec) continue;
+    if (rec.length < 3) continue;
+    const index = rec[0];
+    const worktree = rec[1];
+    const path = rec.slice(3);
+    const change = {
+      path,
+      index,
+      worktree,
+      status: classifyStatus(index, worktree)
+    };
+    if (index === "R" || worktree === "R") {
+      const from = records[i + 1] ?? "";
+      change.renamedFrom = from;
+      i += 1;
+    }
+    out.push(change);
   }
-  await mkdir(join(abs, ".yorz", "specs"), { recursive: true });
-  return abs;
-}
-const LEVEL_WEIGHT = {
-  debug: 10,
-  info: 20,
-  warn: 30,
-  error: 40
-};
-const LOG_LEVELS = Object.keys(LEVEL_WEIGHT);
-const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
-const DEFAULT_MAX_ARCHIVES = 1;
-const DEFAULT_LOG_FILE = "serve.log";
-const STDIO_LOG_FILE = "serve-stdio.log";
-function resolveLogDir(env = process.env) {
-  return join(resolveGlobalConfigDir(env), "logs");
+  return out;
 }
-function resolveLogLevel(env = process.env) {
-  const raw = env.YORZ_LOG_LEVEL?.trim().toLowerCase();
-  if (raw && LOG_LEVELS.includes(raw)) return raw;
-  return "info";
+async function partitionPathsByStatus(cwd, paths) {
+  const all = await listChanges(cwd);
+  const byPath = new Map(all.map((c) => [c.path, c]));
+  const result = { tracked: [], untracked: [], renamed: [] };
+  for (const p of paths) {
+    const change = byPath.get(p);
+    if (!change) continue;
+    if (change.status === "??") {
+      result.untracked.push(p);
+    } else if (change.renamedFrom) {
+      result.renamed.push({ path: p, renamedFrom: change.renamedFrom });
+    } else {
+      result.tracked.push(p);
+    }
+  }
+  return result;
 }
-function defaultOptions(env = process.env) {
-  return {
-    dir: resolveLogDir(env),
-    fileName: DEFAULT_LOG_FILE,
-    maxBytes: DEFAULT_MAX_BYTES,
-    maxArchives: DEFAULT_MAX_ARCHIVES,
-    level: resolveLogLevel(env),
-    mirrorConsole: true
-  };
+async function commit(cwd, opts) {
+  const message = opts.message?.trim() ?? "";
+  if (!message) throw new GitError("invalid_message", "commit message must not be empty");
+  if (!Array.isArray(opts.paths) || opts.paths.length === 0) {
+    throw new GitError("no_paths", "commit requires at least one path");
+  }
+  for (const p of opts.paths) assertSafeRelativePath(cwd, p);
+  const { renamed } = await partitionPathsByStatus(cwd, opts.paths);
+  const extraPaths = renamed.map((r) => r.renamedFrom);
+  const allPaths = [...opts.paths, ...extraPaths];
+  await runGit(cwd, ["add", "--", ...allPaths]);
+  await runGit(cwd, ["commit", "-m", message, "--", ...allPaths]);
+  const { stdout } = await runGit(cwd, ["rev-parse", "HEAD"]);
+  return { commit: stdout.trim() };
 }
-class RotatingFileSink {
-  constructor(dir, fileName, maxBytes, maxArchives) {
-    this.dir = dir;
-    this.fileName = fileName;
-    this.maxBytes = maxBytes;
-    this.maxArchives = maxArchives;
+async function discard(cwd, opts) {
+  if (!Array.isArray(opts.paths) || opts.paths.length === 0) {
+    throw new GitError("no_paths", "discard requires at least one path");
   }
-  currentSize = 0;
-  initialized = false;
-  queue = Promise.resolve();
-  get filePath() {
-    return join(this.dir, this.fileName);
+  for (const p of opts.paths) assertSafeRelativePath(cwd, p);
+  const { tracked, untracked, renamed } = await partitionPathsByStatus(cwd, opts.paths);
+  if (tracked.length) {
+    await runGit(cwd, ["restore", "--staged", "--worktree", "--", ...tracked]);
   }
-  archivePath(index) {
-    return `${this.filePath}.${index}`;
+  if (untracked.length) {
+    await runGit(cwd, ["clean", "-fd", "--", ...untracked]);
   }
-  /** Enqueue a line; returns immediately, never throws. */
-  write(line) {
-    this.queue = this.queue.then(() => this.writeNow(line)).catch(() => {
-    });
+  for (const r of renamed) {
+    await runGitRaw(cwd, ["reset", "-q", "HEAD", "--", r.renamedFrom, r.path]);
+    await runGit(cwd, ["restore", "--worktree", "--", r.renamedFrom]);
+    await runGit(cwd, ["clean", "-fd", "--", r.path]);
   }
-  /** Resolve once every queued line has been flushed to disk. */
-  async flush() {
-    await this.queue.catch(() => {
-    });
+}
+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");
   }
-  async writeNow(line) {
+  for (const p of opts.paths) assertSafeRelativePath(cwd, p);
+  const { renamed } = await partitionPathsByStatus(cwd, opts.paths);
+  const extraPaths = renamed.map((r) => r.renamedFrom);
+  const allPaths = [...opts.paths, ...extraPaths];
+  const message = opts.message?.trim() || "yorz:stash";
+  await runGit(cwd, ["stash", "push", "--include-untracked", "-m", message, "--", ...allPaths]);
+}
+const VALID_ACTIONS = /* @__PURE__ */ new Set(["commit", "discard", "stash"]);
+function createSpecReviewRoutes(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;
+  };
+  app.post("/projects/:projectId/specs/:id/review", 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);
+    const specRel = `${p.specsDirRelative}/${specId}/spec.md`;
+    const reviewRel = `${p.specsDirRelative}/${specId}/review.md`;
+    const prompt = `请使用 yorz-spec skill 的 "Review / Git Ops 阶段" 流程处理本次 review：
+- spec 文档：${specRel}
+- 输出文件：${reviewRel}（追加新二级标题条目，禁止覆盖历史）
+- 必含 4 节：变更总结 / 影响范围 / 风险提醒 / 变更文件清单
+- 触发时间使用本机当前时间，格式 \`YYYY-MM-DD HH:mm:ss\`
+`;
+    const { sessionId } = await p.sessions.ensureSessionForSpec(specId);
+    const handle = await p.sessions.send(sessionId, prompt);
+    return c.json({ runId: handle.runId, sessionId });
+  });
+  app.post("/projects/:projectId/specs/:id/git", 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 {
-      await this.ensureInit();
-      const bytes = Buffer.byteLength(line, "utf8");
-      if (this.currentSize > 0 && this.currentSize + bytes > this.maxBytes) {
-        await this.rotate();
-      }
-      await appendFile(this.filePath, line, "utf8");
-      this.currentSize += bytes;
+      body = await c.req.json();
     } catch {
+      return c.json({ error: "invalid JSON body" }, 400);
     }
-  }
-  /** Lazily create the dir and recover `currentSize` from an existing file. */
-  async ensureInit() {
-    if (this.initialized) return;
-    await mkdir(this.dir, { recursive: true });
+    const action = body && typeof body === "object" ? body.action : null;
+    if (!action || typeof action !== "string" || !VALID_ACTIONS.has(action)) {
+      return c.json({ error: "action must be one of commit | discard | stash" }, 400);
+    }
+    const specRel = `${p.specsDirRelative}/${specId}/spec.md`;
+    const reviewRel = `${p.specsDirRelative}/${specId}/review.md`;
+    const prompt = buildGitOpsPrompt(action, specId, specRel, reviewRel);
+    const { sessionId } = await p.sessions.ensureSessionForSpec(specId);
+    const handle = await p.sessions.send(sessionId, prompt);
+    return c.json({ runId: handle.runId, sessionId });
+  });
+  app.get("/projects/:projectId/specs/:id/review", 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);
+    const file = join(p.specsDir, specId, "review.md");
+    if (!existsSync(file)) return c.json({ text: "" });
+    try {
+      const text = await readFile(file, "utf8");
+      return c.json({ text });
+    } catch {
+      return c.json({ text: "" });
+    }
+  });
+  app.get("/projects/:projectId/specs/:id/debug", 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);
+    const file = join(p.specsDir, specId, "debug.md");
+    if (!existsSync(file)) return c.json({ exists: false, text: "" });
+    try {
+      const text = await readFile(file, "utf8");
+      return c.json({ exists: true, text });
+    } catch {
+      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;
+    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 {
-      const st = await stat(this.filePath);
-      this.currentSize = st.size;
+      body = await c.req.json();
     } catch {
-      this.currentSize = 0;
-    }
-    this.initialized = true;
-  }
-  async rotate() {
-    if (this.maxArchives <= 0) {
-      await writeFile(this.filePath, "", "utf8");
-      this.currentSize = 0;
-      return;
+      return c.json({ error: "invalid JSON body" }, 400);
     }
-    for (let i = this.maxArchives - 1; i >= 1; i--) {
-      try {
-        await rename(this.archivePath(i), this.archivePath(i + 1));
-      } catch {
-      }
+    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);
+    try {
+      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;
     }
-    await rename(this.filePath, this.archivePath(1));
-    this.currentSize = 0;
-  }
-}
-function createSink(options) {
-  return new RotatingFileSink(options.dir, options.fileName, options.maxBytes, options.maxArchives);
-}
-function formatMeta(meta) {
-  if (!meta) return "";
-  const keys = Object.keys(meta);
-  if (keys.length === 0) return "";
-  try {
-    return ` ${JSON.stringify(meta, jsonReplacer)}`;
-  } catch {
-    return "";
-  }
-}
-function jsonReplacer(_key, value) {
-  if (value instanceof Error) return { message: value.message, stack: value.stack };
-  if (typeof value === "bigint") return value.toString();
-  return value;
+  });
+  return app;
 }
-class Logger {
-  constructor(core, scope) {
-    this.core = core;
-    this.scope = scope;
-  }
-  get level() {
-    return this.core.options.level;
-  }
-  get filePath() {
-    return this.core.sink.filePath;
-  }
-  get dir() {
-    return this.core.options.dir;
-  }
-  /** Derive a logger that prefixes every line with `[scope]`. */
-  child(scope) {
-    const next = this.scope && this.scope !== "yorz" ? `${this.scope}:${scope}` : scope;
-    return new Logger(this.core, next);
-  }
-  debug(msg, meta) {
-    this.emit("debug", msg, meta);
-  }
-  info(msg, meta) {
-    this.emit("info", msg, meta);
-  }
-  warn(msg, meta) {
-    this.emit("warn", msg, meta);
-  }
-  error(msg, meta) {
-    this.emit("error", msg, meta);
-  }
-  /** Replace options in place; every existing child logger picks the change up. */
-  configure(patch) {
-    const prev = this.core.options;
-    const next = { ...prev, ...patch };
-    this.core.options = next;
-    const sinkChanged = next.dir !== prev.dir || next.fileName !== prev.fileName || next.maxBytes !== prev.maxBytes || next.maxArchives !== prev.maxArchives;
-    if (sinkChanged) this.core.sink = createSink(next);
-  }
-  async flush() {
-    await this.core.sink.flush();
-  }
-  emit(level, msg, meta) {
-    const { options } = this.core;
-    if (LEVEL_WEIGHT[level] < LEVEL_WEIGHT[options.level]) return;
-    const line = `[${(/* @__PURE__ */ new Date()).toISOString()}] [${level}] [${this.scope}] ${msg}${formatMeta(meta)}
+function buildGitOpsPrompt(action, specId, specRel, reviewRel) {
+  const base = `请使用 yorz-spec skill 的 "Review / Git Ops 阶段" 流程执行 git 操作：
+- spec 文档：${specRel}
+- 最近一次 review：${reviewRel}（如不存在，请先依据 git status/diff 自行判断本次 spec 关联的变更）
+- spec-id：${specId}
+`;
+  switch (action) {
+    case "commit":
+      return base + `- 动作：git-commit。请基于 review 报告与 git status，由你自主判断本次 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\`。
 `;
-    if (options.mirrorConsole) mirror(level, line);
-    this.core.sink.write(line);
-  }
-}
-function mirror(level, line) {
-  const text = line.endsWith("\n") ? line.slice(0, -1) : line;
-  try {
-    if (level === "error") console.error(text);
-    else if (level === "warn") console.warn(text);
-    else console.log(text);
-  } catch {
   }
 }
-function createLogger(patch = {}) {
-  const options = { ...defaultOptions(), ...patch };
-  return new Logger({ options, sink: createSink(options) }, "yorz");
-}
-let singleton = null;
-function getLogger() {
-  if (!singleton) singleton = createLogger();
-  return singleton;
-}
-function configureLogger(patch) {
-  const logger = getLogger();
-  logger.configure(patch);
-  return logger;
-}
 const sseLog = () => getLogger().child("sse");
 const HEARTBEAT_INTERVAL_MS = 5e3;
 function attachHeartbeat(stream, intervalMs = HEARTBEAT_INTERVAL_MS) {
@@ -2030,6 +2164,7 @@ class EventsHub {
   }
   async attachTopic(s, topic) {
     if (topic === "projects") return this.attachProjects(s);
+    if (topic === "system-notifications") return this.attachSystemNotifications(s);
     const m = /^project:([^:]+):(.+)$/.exec(topic);
     if (!m) throw new Error(`invalid topic: ${topic}`);
     const pid = m[1];
@@ -2058,6 +2193,15 @@ class EventsHub {
       this.emit(s, "projects", "projects-changed", {});
     });
   }
+  attachSystemNotifications(s) {
+    this.emit(s, "system-notifications", "ready", {});
+    const center = this.deps.systemNotifications;
+    if (!center) return () => {
+    };
+    return center.subscribe(() => {
+      this.emit(s, "system-notifications", "updated", {});
+    });
+  }
   attachSpecsList(s, topic, project) {
     this.emit(s, topic, "ready", {});
     return project.watcher.subscribeList(() => {
@@ -2125,9 +2269,9 @@ class EventsHub {
     });
   }
 }
-function createEventsRoutes(resolveProject, registry, projectsBus) {
+function createEventsRoutes(resolveProject, registry, projectsBus, systemNotifications) {
   const app = new Hono();
-  const hub = new EventsHub({ resolveProject, registry, projectsBus });
+  const hub = new EventsHub({ resolveProject, registry, projectsBus, systemNotifications });
   app.get("/events/stream", (c) => {
     const clientId = c.req.query("clientId")?.trim();
     if (!clientId) {
@@ -2300,12 +2444,12 @@ function normalizeCommands(value) {
     if (!item || typeof item !== "object") continue;
     const obj = item;
     const id = typeof obj.id === "string" ? obj.id.trim() : "";
-    const name = typeof obj.name === "string" ? obj.name.trim() : "";
+    const name2 = typeof obj.name === "string" ? obj.name.trim() : "";
     const cli = typeof obj.cli === "string" ? obj.cli.trim() : "";
-    if (!id || !name || !cli || seen.has(id)) continue;
+    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, cli, createdAt });
+    out.push({ id, name: name2, cli, createdAt });
   }
   return out;
 }
@@ -2530,12 +2674,12 @@ function createSpecDraftsRoutes(resolveProject) {
     const blob = file;
     const buf = new Uint8Array(await blob.arrayBuffer());
     const mime = blob.type || "";
-    const name = blob.name || "attachment";
+    const name2 = blob.name || "attachment";
     if (!classifyMime(mime)) {
       return c.json({ error: `unsupported MIME: ${mime || "(empty)"}` }, 415);
     }
     try {
-      const meta = await p.attachments.addAttachment(draftId, { name, mime, data: buf });
+      const meta = await p.attachments.addAttachment(draftId, { name: name2, mime, data: buf });
       return c.json(meta, 201);
     } catch (err) {
       return errorResponse(c, err);
@@ -2570,12 +2714,12 @@ function createSpecDraftsRoutes(resolveProject) {
     } catch {
       return c.json({ error: "invalid JSON body" }, 400);
     }
-    const name = body?.name;
-    if (typeof name !== "string" || !name.trim()) {
+    const name2 = body?.name;
+    if (typeof name2 !== "string" || !name2.trim()) {
       return c.json({ error: "name required" }, 400);
     }
     try {
-      const meta = await p.attachments.renameAttachment(draftId, storedName, name);
+      const meta = await p.attachments.renameAttachment(draftId, storedName, name2);
       return c.json(meta);
     } catch (err) {
       return errorResponse(c, err);
@@ -2917,7 +3061,7 @@ const RUN_RETENTION_MS = 7 * 24 * 60 * 60 * 1e3;
 function runLogRelPath(runId) {
   return `.yorz/tmp/commands/${runId}.log`;
 }
-const log$2 = () => getLogger().child("commands");
+const log$3 = () => getLogger().child("commands");
 const TAIL_POLL_MS = 200;
 const STOP_GRACE_MS = 2e3;
 class CommandNotFoundError extends Error {
@@ -2997,7 +3141,7 @@ class LogTailer {
         }
       }
     } catch (err) {
-      log$2().warn("tail read failed", { file: this.file, err });
+      log$3().warn("tail read failed", { file: this.file, err });
     } finally {
       if (fd !== null) closeSync(fd);
     }
@@ -3032,8 +3176,8 @@ class CommandManager {
     const cfg = await loadProjectConfig(this.projectPath);
     return cfg.commands;
   }
-  async addDef(name, cli) {
-    const trimmedName = name.trim();
+  async addDef(name2, cli) {
+    const trimmedName = name2.trim();
     const trimmedCli = cli.trim();
     if (!trimmedName) throw new Error("name is required");
     if (!trimmedCli) throw new Error("cli is required");
@@ -3101,7 +3245,7 @@ class CommandManager {
         signal: null,
         logFile: logRel
       };
-      log$2().error("failed to open command log", { runId, logAbs, err });
+      log$3().error("failed to open command log", { runId, logAbs, err });
       await this.store.upsert(failed);
       this.notifyRuns();
       return failed;
@@ -3140,7 +3284,7 @@ class CommandManager {
           void this.handleExit(runId, signal ? "killed" : "exited", code, signal ?? null);
         });
         child.on("error", (err) => {
-          log$2().warn("command child error", { runId, err });
+          log$3().warn("command child error", { runId, err });
           this.children.delete(runId);
           void this.handleExit(runId, "failed", null, null);
         });
@@ -3155,7 +3299,7 @@ class CommandManager {
         if (settled) return settled;
       }
       this.notifyRuns();
-      log$2().info("command started", { runId, commandId, pid: run.pid, cli: def.cli });
+      log$3().info("command started", { runId, commandId, pid: run.pid, cli: def.cli });
       return run;
     } finally {
       try {
@@ -3272,7 +3416,7 @@ class CommandManager {
       if (run.status === "running") {
         if (run.pid > 0 && isAlive(run.pid)) {
           killGroup(run.pid, "SIGKILL");
-          log$2().warn("reaped orphan command process", { runId: run.runId, pid: run.pid });
+          log$3().warn("reaped orphan command process", { runId: run.runId, pid: run.pid });
         }
         kept.push({ ...run, status: "killed", endedAt: run.endedAt ?? now, exitCode: null });
         continue;
@@ -3292,7 +3436,7 @@ class CommandManager {
       killGroup(run.pid, "SIGTERM");
       const exited = await waitForExit(run.pid, STOP_GRACE_MS);
       if (!exited) {
-        log$2().warn("command did not exit on SIGTERM, escalating", {
+        log$3().warn("command did not exit on SIGTERM, escalating", {
           runId: run.runId,
           pid: run.pid
         });
@@ -3323,7 +3467,7 @@ class CommandManager {
     await this.store.upsert(next);
     this.notifyRuns();
     this.notifyRun(next);
-    log$2().info("command ended", { runId, status, exitCode, signal });
+    log$3().info("command ended", { runId, status, exitCode, signal });
   }
   notifyRuns() {
     if (this.runsSubscribers.size === 0) return;
@@ -3545,13 +3689,43 @@ function createCommandsRoutes(resolveProject) {
 function parseDefBody(value) {
   if (!value || typeof value !== "object") return { error: "body must be an object" };
   const obj = value;
-  const name = typeof obj.name === "string" ? obj.name.trim() : "";
+  const name2 = typeof obj.name === "string" ? obj.name.trim() : "";
   const cli = typeof obj.cli === "string" ? obj.cli.trim() : "";
-  if (!name) return { error: "name required" };
-  if (name.length > MAX_NAME_LEN) return { error: `name too long (max ${MAX_NAME_LEN})` };
+  if (!name2) return { error: "name required" };
+  if (name2.length > MAX_NAME_LEN) return { error: `name too long (max ${MAX_NAME_LEN})` };
   if (!cli) return { error: "cli required" };
   if (cli.length > MAX_CLI_LEN) return { error: `cli too long (max ${MAX_CLI_LEN})` };
-  return { name, cli };
+  return { name: name2, cli };
+}
+function createSystemNotificationsRoutes(center) {
+  const app = new Hono();
+  app.get("/system-notifications", (c) => c.json(center.list()));
+  app.delete("/system-notifications/:id", (c) => {
+    const ok = center.delete(c.req.param("id"));
+    if (!ok) return c.json({ error: "notification not found" }, 404);
+    return c.json({ ok: true });
+  });
+  app.post("/system-notifications/:id/update", async (c) => {
+    try {
+      const notification = await center.update(c.req.param("id"));
+      return c.json(notification);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const status = message === "notification not found" ? 404 : 400;
+      return c.json({ error: message }, status);
+    }
+  });
+  app.post("/system-notifications/:id/restart", async (c) => {
+    try {
+      const notification = await center.restart(c.req.param("id"));
+      return c.json(notification);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const status = message === "notification not found" ? 404 : 400;
+      return c.json({ error: message }, status);
+    }
+  });
+  return app;
 }
 const MIME = {
   ".html": "text/html; charset=utf-8",
@@ -3716,6 +3890,7 @@ class WorktreeManager {
       path: wtPath,
       baseRef
     });
+    this.onProjectsChanged?.();
     return { entry: updated, branch, path: wtPath, baseRef };
   }
   /** Update the `specId` on a worktree entry once the spec has been created. */
@@ -3817,9 +3992,9 @@ class WorktreeManager {
   }
   async collectConflictReport(mainPath) {
     const unmerged = await runGitChecked(mainPath, ["diff", "--name-only", "--diff-filter=U"]);
-    const files = unmerged.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+    const files2 = unmerged.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
     const commitsByFile = {};
-    for (const file of files) {
+    for (const file of files2) {
       const log2 = await runGitRaw(mainPath, [
         "log",
         "--since=30 days ago",
@@ -3838,7 +4013,7 @@ class WorktreeManager {
       "--date=short"
     ]);
     return {
-      files,
+      files: files2,
       commitsByFile,
       recentMerges: parseCommitLines(merges.stdout)
     };
@@ -3892,10 +4067,10 @@ class WorktreeManager {
 }
 async function detectDefaultBranch(mainPath) {
   const res = await runGitChecked(mainPath, ["rev-parse", "--abbrev-ref", "HEAD"]);
-  const name = res.stdout.trim();
-  if (!name || name === "HEAD")
+  const name2 = res.stdout.trim();
+  if (!name2 || name2 === "HEAD")
     throw new GitError("detached_head", "main project is in detached HEAD; cannot base worktree");
-  return name;
+  return name2;
 }
 async function uniqueBranch(mainPath, base) {
   let candidate = base;
@@ -4069,6 +4244,9 @@ function createApp(opts) {
     }
   });
   api.route("/", createProjectRoutes(opts.registry, worktreeManager));
+  if (opts.systemNotifications) {
+    api.route("/", createSystemNotificationsRoutes(opts.systemNotifications));
+  }
   api.route("/", createGlobalConfigRoutes(opts.registry.configPath()));
   api.route("/", createProjectConfigRoutes(opts.registry));
   api.route("/", createSpecsRoutes(resolveProject));
@@ -4078,7 +4256,10 @@ function createApp(opts) {
   api.route("/", createWorktreeRoutes(opts.registry, worktreeManager));
   api.route("/", createProjectFilesRoutes(resolveProject));
   api.route("/", createCommandsRoutes(resolveProject));
-  api.route("/", createEventsRoutes(resolveProject, opts.registry, projectsBus));
+  api.route(
+    "/",
+    createEventsRoutes(resolveProject, opts.registry, projectsBus, opts.systemNotifications)
+  );
   app.route("/api", api);
   app.route("/", createStaticRoutes(opts.guiRoot));
   app.onError((err, c) => {
@@ -4225,8 +4406,8 @@ class SpecStore {
     if (kind !== "feat" && kind !== "refct" && kind !== "fix") {
       throw new Error("kind must be feat | refct | fix");
     }
-    const description = (input.description ?? "").trim();
-    if (!description) throw new Error("description required");
+    const description2 = (input.description ?? "").trim();
+    if (!description2) throw new Error("description required");
     const sectionPath = input.sectionPath?.trim() ?? "";
     const quote = input.quote?.trim() ?? "";
     if (quote.length > 500) throw new Error("quote too long (max 500)");
@@ -4239,10 +4420,10 @@ class SpecStore {
       updated_at: this.nowDateTime(),
       summary: existing.summary
     };
-    const firstLine = description.split(/\r?\n/)[0].slice(0, 80);
+    const firstLine = description2.split(/\r?\n/)[0].slice(0, 80);
     const stamp = this.timestamp();
     const lines = [`- [open] [${kind}] ${stamp} | ${firstLine}`];
-    lines.push(`  - 描述：${description}`);
+    lines.push(`  - 描述：${description2}`);
     if (sectionPath) lines.push(`  - 引用：${sectionPath}`);
     if (quote) lines.push(`  - 引用原文：> ${quote}`);
     const entry = lines.join("\n");
@@ -4315,9 +4496,9 @@ class SpecStore {
     if (!existsSync(dir)) return;
     await rm(dir, { recursive: true, force: true });
   }
-  async allocateId(type, summary) {
+  async allocateId(type2, summary) {
     const slug = kebab(summary);
-    const base = `${this.todayCompact()}.${type}.${slug}`;
+    const base = `${this.todayCompact()}.${type2}.${slug}`;
     let id = base;
     let n = 2;
     while (existsSync(join(this.root, id))) {
@@ -4920,10 +5101,10 @@ class CodexAdapter {
   }
   /** Walk ~/.codex/sessions, keep rollouts whose session_meta.cwd matches this project. */
   async listSessions() {
-    const files = await this.walkRollouts();
+    const files2 = await this.walkRollouts();
     const titleIndex = await this.readSessionIndex();
     const out = [];
-    for (const file of files) {
+    for (const file of files2) {
       const meta = await this.readMeta(file, titleIndex);
       if (!meta || meta.cwd !== this.cwd) continue;
       out.push({
@@ -5047,11 +5228,11 @@ class CodexAdapter {
     });
   }
   async findFileById(id) {
-    const files = await this.walkRollouts();
-    const match = files.find((f) => f.includes(id));
+    const files2 = await this.walkRollouts();
+    const match = files2.find((f) => f.includes(id));
     if (match) return match;
     const titleIndex = await this.readSessionIndex();
-    for (const f of files) {
+    for (const f of files2) {
       const meta = await this.readMeta(f, titleIndex);
       if (meta?.id === id) return f;
     }
@@ -5227,6 +5408,9 @@ function summarizePromptForTitle(prompt) {
   if (!cleaned) return "";
   return cleaned.length > TITLE_MAX_LENGTH ? `${cleaned.slice(0, TITLE_MAX_LENGTH - 1)}…` : cleaned;
 }
+function truncateTitle(title) {
+  return title.length > TITLE_MAX_LENGTH ? `${title.slice(0, TITLE_MAX_LENGTH - 1)}…` : title;
+}
 class SessionManager {
   constructor(cwd, defaultKind, store, opts = {}) {
     this.cwd = cwd;
@@ -5284,6 +5468,13 @@ class SessionManager {
     if (existing) return existing;
     return this.createSession(void 0, specId, specId);
   }
+  async bindSessionToSpec(sessionId, specId, title) {
+    const ok = await this.store.bindSpec(sessionId, specId);
+    if (!ok) return false;
+    const trimmed = title?.trim();
+    if (trimmed) await this.store.updateTitle(sessionId, truncateTitle(trimmed));
+    return true;
+  }
   async listSessions() {
     const indexed = await this.store.list();
     const byId = new Map(indexed.map((s) => [s.id, s]));
@@ -5407,7 +5598,7 @@ class SessionManager {
         this.setRunning(currentSid, false);
         void Promise.resolve(this.opts.onSessionEnd?.(currentSid)).catch(() => {
         });
-        emitter.emit("done");
+        emitter.emit("done", currentSid);
       }
     })();
     return {
@@ -5527,6 +5718,15 @@ class SessionStore {
     entry.updatedAt = Date.now();
     await this.persist();
   }
+  async bindSpec(id, specId) {
+    const items = await this.load();
+    const entry = items.find((s) => s.id === id);
+    if (!entry) return false;
+    entry.specId = specId;
+    entry.updatedAt = Date.now();
+    await this.persist();
+    return true;
+  }
   async touch(id) {
     const items = await this.load();
     const entry = items.find((s) => s.id === id);
@@ -5559,8 +5759,8 @@ async function defaultRunCommand(cmd, args) {
   });
 }
 function formatBannerTitle(projectName) {
-  const name = projectName?.trim();
-  return name ? `YorZ · ${name}` : "YorZ";
+  const name2 = projectName?.trim();
+  return name2 ? `YorZ · ${name2}` : "YorZ";
 }
 function appleScriptString(value) {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
@@ -5632,12 +5832,12 @@ class ProjectRegistry {
     const config = await loadGlobalConfig(this.globalConfigPath);
     const items = [];
     for (const p of config.projects) {
-      const name = basename(p.path);
+      const name2 = basename(p.path);
       const fallback = await maxSpecUpdatedAt(p.path);
       const sortKey = p.lastActivityAt ?? fallback ?? "";
       const item = {
         id: p.id,
-        name,
+        name: name2,
         path: p.path,
         lastActivityAt: p.lastActivityAt,
         sortKey
@@ -5646,8 +5846,8 @@ class ProjectRegistry {
       items.push(item);
     }
     items.sort((a, b) => a.sortKey < b.sortKey ? 1 : a.sortKey > b.sortKey ? -1 : 0);
-    return items.map(({ id, name, path, lastActivityAt, worktree }) => {
-      const out = { id, name, path, lastActivityAt };
+    return items.map(({ id, name: name2, path, lastActivityAt, worktree }) => {
+      const out = { id, name: name2, path, lastActivityAt };
       if (worktree) out.worktree = worktree;
       return out;
     });
@@ -5738,6 +5938,7 @@ class ProjectRegistry {
       onSessionEnd: notifySessionEnded
     });
     const commands = getCommandManager(input.path);
+    const stopChatDebugCleanup = scheduleChatDebugCleanup(input.path);
     let closed = false;
     const instance = {
       id: input.id,
@@ -5752,6 +5953,7 @@ class ProjectRegistry {
       async close() {
         if (closed) return;
         closed = true;
+        stopChatDebugCleanup();
         await watcher.close();
         await sessions.dispose().catch(() => {
         });
@@ -5800,6 +6002,182 @@ async function maxSpecUpdatedAt(projectPath) {
     return null;
   }
 }
+const VERSION_NOTIFICATION_ID = "version-update";
+const VERSION_CHECK_INTERVAL_MS = 12 * 60 * 60 * 1e3;
+const log$2 = () => getLogger().child("system-notifications");
+class SystemNotificationCenter {
+  constructor(opts = {}) {
+    this.opts = opts;
+  }
+  items = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  timer = null;
+  checking = false;
+  list() {
+    return [...this.items.values()].sort((a, b) => b.updatedAt - a.updatedAt);
+  }
+  delete(id) {
+    const deleted = this.items.delete(id);
+    if (deleted) this.emit();
+    return deleted;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  upsertVersionUpdate(info) {
+    const now = Date.now();
+    const current = this.items.get(VERSION_NOTIFICATION_ID);
+    const next = {
+      id: VERSION_NOTIFICATION_ID,
+      kind: "version-update",
+      title: "YorZ update available",
+      message: `YorZ ${info.latest} is available. Current version: ${info.current}.`,
+      createdAt: current?.createdAt ?? now,
+      updatedAt: now,
+      action: current?.action === "restart-ready" ? "restart-ready" : "update-available",
+      metadata: { currentVersion: info.current, latestVersion: info.latest }
+    };
+    this.items.set(next.id, next);
+    this.emit();
+    return next;
+  }
+  async update(id) {
+    const item = this.requireVersionNotification(id);
+    this.setAction(item.id, "updating");
+    try {
+      await (this.opts.runUpdate ?? defaultRunUpdate)();
+      return this.setAction(item.id, "restart-ready");
+    } catch (err) {
+      const current = this.requireVersionNotification(id);
+      const next = {
+        ...current,
+        action: "update-available",
+        updatedAt: Date.now(),
+        metadata: {
+          ...current.metadata ?? {},
+          error: err instanceof Error ? err.message : String(err)
+        }
+      };
+      this.items.set(id, next);
+      this.emit();
+      throw err;
+    }
+  }
+  async restart(id) {
+    const item = this.requireVersionNotification(id);
+    if (item.action !== "restart-ready") throw new Error("restart is not ready");
+    await (this.opts.runRestart ?? defaultRunRestart)();
+    return item;
+  }
+  startVersionChecks(intervalMs = VERSION_CHECK_INTERVAL_MS) {
+    if (this.timer) return;
+    void this.checkVersion();
+    this.timer = setInterval(() => void this.checkVersion(), intervalMs);
+    this.timer.unref?.();
+  }
+  stopVersionChecks() {
+    if (!this.timer) return;
+    clearInterval(this.timer);
+    this.timer = null;
+  }
+  async checkVersion() {
+    if (this.checking) return;
+    this.checking = true;
+    try {
+      const latest = await (this.opts.fetchLatestVersion ?? fetchLatestVersion)();
+      if (!latest) return;
+      const current = pkg.version;
+      if (compareVersions(latest, current) > 0) {
+        this.upsertVersionUpdate({ current, latest });
+      }
+    } catch (err) {
+      log$2().warn("version check failed", { err });
+    } finally {
+      this.checking = false;
+    }
+  }
+  requireVersionNotification(id) {
+    const item = this.items.get(id);
+    if (!item) throw new Error("notification not found");
+    if (item.kind !== "version-update") throw new Error("notification has no update action");
+    return item;
+  }
+  setAction(id, action) {
+    const item = this.requireVersionNotification(id);
+    const next = { ...item, action, updatedAt: Date.now() };
+    this.items.set(id, next);
+    this.emit();
+    return next;
+  }
+  emit() {
+    for (const listener of this.listeners) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  }
+}
+function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa || !pb) return 0;
+  for (let i = 0; i < 3; i++) {
+    const diff = pa[i] - pb[i];
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+}
+function resolveGlobalInstallCommand(env = process.env) {
+  const source = `${env.npm_config_user_agent ?? ""} ${env.npm_execpath ?? ""}`.toLowerCase();
+  const manager = source.includes("pnpm") ? "pnpm" : source.includes("bun") ? "bun" : source.includes("yarn") ? "yarn" : "npm";
+  switch (manager) {
+    case "pnpm":
+      return { cmd: "pnpm", args: ["add", "-g", "@yorz/cli@latest"] };
+    case "bun":
+      return { cmd: "bun", args: ["add", "-g", "@yorz/cli@latest"] };
+    case "yarn":
+      return { cmd: "yarn", args: ["global", "add", "@yorz/cli@latest"] };
+    default:
+      return { cmd: "npm", args: ["install", "-g", "@yorz/cli@latest"] };
+  }
+}
+function parseVersion(value) {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(value.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+async function fetchLatestVersion() {
+  const res = await fetch("https://registry.npmjs.org/@yorz/cli/latest");
+  if (!res.ok) throw new Error(`npm registry returned ${res.status}`);
+  const body = await res.json();
+  return typeof body.version === "string" ? body.version : null;
+}
+function defaultRunUpdate() {
+  const install2 = resolveGlobalInstallCommand();
+  return runProcess(install2.cmd, install2.args);
+}
+function defaultRunRestart() {
+  const entry = process.argv[1];
+  if (!entry) throw new Error("Cannot resolve CLI entrypoint for restart");
+  const child = spawn(process.execPath, [entry, "serve", "restart"], {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.unref();
+  return Promise.resolve();
+}
+function runProcess(cmd, args) {
+  return new Promise((resolve2, reject) => {
+    const child = spawn(cmd, args, { stdio: "ignore" });
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (code === 0) resolve2();
+      else reject(new Error(`${cmd} exited with ${code ?? signal ?? "unknown"}`));
+    });
+  });
+}
 const DEFAULT_PORT = 7423;
 const MAX_PORT_TRIES = 10;
 const DEFAULT_HOST = "127.0.0.1";
@@ -5817,7 +6195,9 @@ async function start(opts = {}) {
     }
   }
   const projects = await registry.list();
-  const app = createApp({ registry, guiRoot: opts.guiRoot });
+  const systemNotifications = new SystemNotificationCenter();
+  systemNotifications.startVersionChecks();
+  const app = createApp({ registry, guiRoot: opts.guiRoot, systemNotifications });
   const host = opts.host?.trim() || DEFAULT_HOST;
   const port = await listen(app.fetch, opts.port ?? DEFAULT_PORT, host);
   const url = `http://localhost:${port.port}/`;
@@ -5849,7 +6229,9 @@ async function start(opts = {}) {
     url,
     port: port.port,
     registry,
+    systemNotifications,
     async close() {
+      systemNotifications.stopVersionChecks();
       await stopAllCommandManagers();
       await registry.closeAll();
       await new Promise((resolve2, reject) => {
@@ -5901,8 +6283,8 @@ async function listen(fetchHandler, preferredPort, hostname) {
 function listLanUrls(port) {
   const urls = [];
   const ifaces = networkInterfaces();
-  for (const name of Object.keys(ifaces)) {
-    for (const info of ifaces[name] ?? []) {
+  for (const name2 of Object.keys(ifaces)) {
+    for (const info of ifaces[name2] ?? []) {
       if (info.family === "IPv4" && !info.internal) {
         urls.push(`http://${info.address}:${port}/`);
       }
@@ -5947,6 +6329,7 @@ const DEFAULT_SERVE_PORT = 7423;
 const RUNTIME_FILE = "runtime.json";
 const START_LOCK_DIR = "serve.lock";
 const START_WAIT_MS = 5e3;
+const RESTART_DELAY_MS = 500;
 function backgroundStdio() {
   try {
     const dir = resolveLogDir();
@@ -6057,6 +6440,33 @@ function backgroundArgs(opts) {
   args.push("--record-runtime");
   return args;
 }
+function restartWorkerArgs(opts) {
+  const args = ["serve", "restart", "--worker"];
+  if (opts.port !== void 0) args.push("--port", String(opts.port));
+  if (opts.host !== void 0) args.push("--host", opts.host);
+  if (opts.open) args.push("--open");
+  if (opts.cwd) args.push("--cwd", opts.cwd);
+  if (opts.noRegisterCwd) args.push("--no-register-cwd");
+  args.push("--skip-skill-check");
+  return args;
+}
+async function runRestartServe(opts = {}) {
+  silenceConsoleMirror();
+  if (opts.worker) {
+    await sleep(RESTART_DELAY_MS);
+    await runStopServe();
+    await runServe({ ...opts, foreground: false, skipSkillCheck: opts.skipSkillCheck ?? true });
+    return;
+  }
+  const entry = process.argv[1];
+  if (!entry) throw new Error("Cannot resolve CLI entrypoint for restart");
+  const child = spawn(process.execPath, [entry, ...restartWorkerArgs(opts)], {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.unref();
+  console.log(`YorZ Service restart scheduled (pid=${child.pid ?? "unknown"}).`);
+}
 async function ensureSkillsInstalledWithLog(cwd) {
   const results = await ensureSkillsInstalled({ home: homedir(), cwd });
   for (const r of results) {
@@ -6582,13 +6992,13 @@ const headingNumbering = {
   }
 };
 const headingRules = [headingH1Single, headingSectionLevel, headingNumbering];
-function findSection(ctx, name) {
+function findSection(ctx, name2) {
   const headings = collectHeadings(ctx);
   for (let i = 0; i < headings.length; i += 1) {
     const h = headings[i];
     if (h.level !== 2) continue;
     const bare = stripHeadingNumber(h.text);
-    if (bare !== name) continue;
+    if (bare !== name2) continue;
     const next = headings.slice(i + 1).find((x) => x.level === 2);
     return { start: h.line, end: next ? next.line - 1 : ctx.rawLines.length };
   }
@@ -6849,9 +7259,9 @@ async function initMermaid() {
         pretendToBeVisual: true
       });
       const win = dom.window;
-      const define = (name, value) => {
-        if (name in globalThis) return;
-        Object.defineProperty(globalThis, name, { value, writable: true, configurable: true });
+      const define = (name2, value) => {
+        if (name2 in globalThis) return;
+        Object.defineProperty(globalThis, name2, { value, writable: true, configurable: true });
       };
       define("window", win);
       define("document", win.document);
@@ -7286,8 +7696,8 @@ async function lintReviewMd(raw, opts = {}) {
 }
 async function lintFile(path, opts = {}) {
   const raw = await readFile(path, "utf8");
-  const name = basename$1(path).toLowerCase();
-  if (name === "review.md") return lintReviewMd(raw, { filePath: path, ...opts });
+  const name2 = basename$1(path).toLowerCase();
+  if (name2 === "review.md") return lintReviewMd(raw, { filePath: path, ...opts });
   return lintSpecMd(raw, { filePath: path, ...opts });
 }
 [...new Set([...SPEC_RULES, ...REVIEW_RULES].map((r) => r.id))];
@@ -7457,6 +7867,29 @@ serveCmd.command("stop").description("Stop the background YorZ Service.").action
   const result = await runStopServe();
   console.log(result.message);
 });
+serveCmd.command("restart").description("Restart the background YorZ Service.").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)"
+).option("--open", "open the GUI in the default browser", false).option(
+  "--cwd <path>",
+  "directory to auto-register when it contains .yorz/ (default: process.cwd())"
+).option("--no-register-cwd", "do not auto-register the current directory").addOption(new Option("--worker", "internal: run detached restart worker").hideHelp()).addOption(
+  new Option("--skip-skill-check", "internal: skip the skill install/update check").hideHelp()
+).action(async (opts) => {
+  const port = opts.port === void 0 ? void 0 : Number.parseInt(opts.port, 10);
+  if (port !== void 0 && (!Number.isFinite(port) || port < 0)) {
+    throw new Error(`Invalid --port: ${opts.port}`);
+  }
+  await runRestartServe({
+    port,
+    host: opts.host,
+    open: opts.open,
+    cwd: opts.cwd,
+    noRegisterCwd: opts.registerCwd === false,
+    skipSkillCheck: opts.skipSkillCheck === true,
+    worker: opts.worker === true
+  });
+});
 program.parseAsync(process.argv).catch((err) => {
   console.error(`error: ${err.message}`);
   process.exit(1);