@yorz/cli 0.3.7 → 0.4.2

package/dist/cli/index.js

@@ -3,9 +3,9 @@ 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 { createHash, randomUUID } from "node:crypto";
+import { createHash, randomUUID, randomBytes } from "node:crypto";
 import { spawn, execFile } from "node:child_process";
-import { existsSync, statSync, mkdirSync, watch, createReadStream, openSync } from "node:fs";
+import { existsSync, openSync, closeSync, statSync, readSync, mkdirSync, watch, createReadStream } from "node:fs";
 import { serve } from "@hono/node-server";
 import { Hono } from "hono";
 import { promisify } from "node:util";
@@ -21,7 +21,7 @@ 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.3.7";
+const version = "0.4.2";
 const pkg = {
   version
 };
@@ -55,7 +55,7 @@ function getAdapter(name) {
   if (name in ADAPTERS) return ADAPTERS[name];
   throw new Error(`Unknown agent: ${name}. 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\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. Bug 现象与复现\n\n...\n\n### 2. 关联链路分析\n\n...\n\n### 3. Debug 基线\n\n快照 SHA + 进入时间；`git diff <SHA>` 为退出闸门基准。\n\n### 4. 假设看板\n\n...\n\n### 5. 证据\n\n...\n\n### 6. 脚手架清单\n\n...\n\n### 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. **人在环路**：加日志后**停下**，请用户复现并回传日志 / 截图（MVP 复用现有 Chat 会话承接回传，无需新 UI）。回传前不臆断。\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.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_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";
@@ -747,7 +747,12 @@ function createSpecsRoutes(resolveProject) {
     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") : debugActive ? buildDebugPrompt(p.specsDirRelative, specId, "resume") : `请使用 yorz-spec skill 处理 spec：${p.specsDirRelative}/${specId}/spec.md`;
+      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 });
     }
@@ -761,7 +766,7 @@ function createSpecsRoutes(resolveProject) {
     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") : `请使用 yorz-spec skill 处理 spec：${p.specsDirRelative}/${specId}/spec.md`;
+    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 });
   });
@@ -850,13 +855,38 @@ async function readDebugMdStatus(specDir) {
   const val = statusLine.slice(statusLine.indexOf(":") + 1).trim().replace(/^['"]|['"]$/g, "");
   return val === "debugging" ? "debugging" : val === "resolved" ? "resolved" : null;
 }
-function buildDebugPrompt(specsDirRelative, specId, mode) {
+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）继续「假设 → 取证 → 验证」循环，勿新建记录块。`;
+    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;
+}
+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 `请使用 yorz-debug skill 进入 Debug 模式：spec 目录 ${specsDirRelative}/${specId}（含 ${specPath}）。若 ${debugPath} 不存在则创建，否则在文末追加新的 ## Debug 记录块；进入后立即 git stash create 打快照写入 Debug 基线，再开始「假设 → 取证 → 验证」循环。`;
+  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" };
@@ -2008,6 +2038,9 @@ class EventsHub {
     if (!project) throw new Error("project not found");
     if (rest === "specs") return this.attachSpecsList(s, topic, project);
     if (rest === "sessions") return this.attachSessionsStatus(s, topic, project);
+    if (rest === "commands") return this.attachCommandRuns(s, topic, project);
+    const cm = /^command:(.+)$/.exec(rest);
+    if (cm) return this.attachCommandRun(s, topic, project, cm[1]);
     let sm = /^spec:([^:]+):changes$/.exec(rest);
     if (sm) return this.attachSpecChanges(s, topic, project, sm[1]);
     sm = /^spec:([^:]+)$/.exec(rest);
@@ -2057,6 +2090,32 @@ class EventsHub {
       this.emit(s, topic, "session-msg", ev);
     });
   }
+  // Project-level topic: the running-commands container. Emits the full run
+  // list on every change — the list is short and the GUI renders it wholesale.
+  async attachCommandRuns(s, topic, project) {
+    this.emit(s, topic, "ready", {});
+    const runs = await project.commands.listRuns().catch(() => []);
+    this.emit(s, topic, "runs-updated", { runs });
+    return project.commands.subscribeRuns((next) => {
+      this.emit(s, topic, "runs-updated", { runs: next });
+    });
+  }
+  // Per-run topic: incremental stdout plus terminal status transitions.
+  async attachCommandRun(s, topic, project, runId) {
+    const run = await project.commands.getRun(runId);
+    if (!run) throw new Error("command run not found");
+    this.emit(s, topic, "ready", { run });
+    const unsubOutput = project.commands.subscribeOutput(runId, (chunk) => {
+      this.emit(s, topic, "output-appended", chunk);
+    });
+    const unsubRun = project.commands.subscribeRun(runId, (next) => {
+      this.emit(s, topic, "run-updated", { run: next });
+    });
+    return () => {
+      unsubOutput();
+      unsubRun();
+    };
+  }
   // Project-level topic: broadcasts which sessions have an in-flight turn, so
   // the Chat list can render a spinner on sessions other than the active one.
   attachSessionsStatus(s, topic, project) {
@@ -2174,7 +2233,12 @@ function createProjectRoutes(registry, worktreeManager) {
 const CURRENT_VERSION = 1;
 const DEFAULT_SPECS_DIR = ".yorz/specs";
 function defaultProjectConfig() {
-  return { version: CURRENT_VERSION, agent: { kind: "inherit" }, specsDir: DEFAULT_SPECS_DIR };
+  return {
+    version: CURRENT_VERSION,
+    agent: { kind: "inherit" },
+    specsDir: DEFAULT_SPECS_DIR,
+    commands: []
+  };
 }
 function configPath(cwd) {
   return join(cwd, ".yorz", "config.json");
@@ -2225,7 +2289,25 @@ function normalizeConfig(value) {
   const obj = value;
   const agent = normalizeAgent(obj.agent);
   const specsDir = normalizeSpecsDir(obj.specsDir);
-  return { version: CURRENT_VERSION, agent, specsDir };
+  const commands = normalizeCommands(obj.commands);
+  return { version: CURRENT_VERSION, agent, specsDir, commands };
+}
+function normalizeCommands(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of value) {
+    if (!item || typeof item !== "object") continue;
+    const obj = item;
+    const id = typeof obj.id === "string" ? obj.id.trim() : "";
+    const name = typeof obj.name === "string" ? obj.name.trim() : "";
+    const cli = typeof obj.cli === "string" ? obj.cli.trim() : "";
+    if (!id || !name || !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 });
+  }
+  return out;
 }
 function normalizeAgent(value) {
   if (typeof value === "string") {
@@ -2274,10 +2356,12 @@ function createProjectConfigRoutes(registry) {
     }
     const parsed = parseBody$1(raw);
     if ("error" in parsed) return c.json({ error: parsed.error }, 400);
+    const current = await loadProjectConfig(entry.path);
     const cfg = {
       version: 1,
       agent: parsed.agent,
-      specsDir: parsed.specsDir
+      specsDir: parsed.specsDir,
+      commands: current.commands
     };
     let absSpecsDir;
     try {
@@ -2755,6 +2839,720 @@ function createProjectFilesRoutes(resolveProject) {
   });
   return app;
 }
+class CommandRunStore {
+  file;
+  cache = null;
+  loadPromise = null;
+  writeChain = Promise.resolve();
+  constructor(projectPath) {
+    this.file = join(projectPath, ".yorz", "tmp", "commands", "index.json");
+  }
+  /**
+   * The in-flight read is memoized, not just its result: concurrent callers
+   * must end up mutating the *same* array. Racing reads that each install a
+   * fresh cache would silently drop every upsert but the last.
+   */
+  load() {
+    if (this.cache) return Promise.resolve(this.cache);
+    if (!this.loadPromise) {
+      this.loadPromise = (async () => {
+        let items = [];
+        try {
+          const raw = await readFile(this.file, "utf8");
+          const parsed = JSON.parse(raw);
+          if (Array.isArray(parsed)) items = parsed;
+        } catch {
+          items = [];
+        }
+        this.cache ??= items;
+        return this.cache;
+      })();
+    }
+    return this.loadPromise;
+  }
+  async persist() {
+    this.writeChain = this.writeChain.then(async () => {
+      const body = JSON.stringify(this.cache ?? [], null, 2);
+      await mkdir(dirname(this.file), { recursive: true });
+      const tmp = `${this.file}.tmp-${process.pid}-${Date.now().toString(36)}`;
+      await writeFile(tmp, body, "utf8");
+      await rename(tmp, this.file);
+    });
+    await this.writeChain;
+  }
+  /** Newest run first. */
+  async list() {
+    const items = await this.load();
+    return [...items].sort((a, b) => b.startedAt - a.startedAt);
+  }
+  async get(runId) {
+    const items = await this.load();
+    return items.find((r) => r.runId === runId);
+  }
+  async upsert(run) {
+    const items = await this.load();
+    const idx = items.findIndex((r) => r.runId === run.runId);
+    if (idx >= 0) items[idx] = { ...items[idx], ...run };
+    else items.push(run);
+    await this.persist();
+  }
+  async remove(runId) {
+    const items = await this.load();
+    const idx = items.findIndex((r) => r.runId === runId);
+    if (idx < 0) return false;
+    items.splice(idx, 1);
+    await this.persist();
+    return true;
+  }
+  /** Bulk replace, used by the startup reap pass. */
+  async replaceAll(runs) {
+    await this.load();
+    this.cache = [...runs];
+    this.loadPromise = Promise.resolve(this.cache);
+    await this.persist();
+  }
+}
+const OUTPUT_TAIL_LIMIT = 256 * 1024;
+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 TAIL_POLL_MS = 200;
+const STOP_GRACE_MS = 2e3;
+class CommandNotFoundError extends Error {
+  constructor(id) {
+    super(`command not found: ${id}`);
+    this.name = "CommandNotFoundError";
+  }
+}
+class RunNotFoundError extends Error {
+  constructor(id) {
+    super(`command run not found: ${id}`);
+    this.name = "RunNotFoundError";
+  }
+}
+class LogTailer {
+  constructor(file) {
+    this.file = file;
+  }
+  subscribers = /* @__PURE__ */ new Set();
+  timer = null;
+  offset = 0;
+  get subscriberCount() {
+    return this.subscribers.size;
+  }
+  get running() {
+    return this.timer !== null;
+  }
+  /**
+   * The first subscriber positions the tail at the current end of file: the GUI
+   * has already fetched everything up to there over REST. Any gap caused by
+   * writes landing between that fetch and this subscribe shows up as a
+   * non-contiguous offset, which the GUI heals with a refetch.
+   */
+  subscribe(cb, fromOffset) {
+    if (this.subscribers.size === 0) this.offset = fromOffset ?? currentSize(this.file);
+    this.subscribers.add(cb);
+    if (!this.timer) {
+      this.timer = setInterval(() => this.poll(), TAIL_POLL_MS);
+      this.timer.unref?.();
+    }
+    return () => {
+      this.subscribers.delete(cb);
+      if (this.subscribers.size === 0) this.stop();
+    };
+  }
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+  }
+  poll() {
+    let size;
+    try {
+      size = statSync(this.file).size;
+    } catch {
+      return;
+    }
+    if (size <= this.offset) {
+      if (size < this.offset) this.offset = size;
+      return;
+    }
+    let fd = null;
+    try {
+      fd = openSync(this.file, "r");
+      const length = size - this.offset;
+      const buf = Buffer.alloc(length);
+      const read = readSync(fd, buf, 0, length, this.offset);
+      if (read <= 0) return;
+      const chunk = {
+        offset: this.offset,
+        chunk: buf.subarray(0, read).toString("utf8")
+      };
+      this.offset += read;
+      for (const cb of this.subscribers) {
+        try {
+          cb(chunk);
+        } catch {
+        }
+      }
+    } catch (err) {
+      log$2().warn("tail read failed", { file: this.file, err });
+    } finally {
+      if (fd !== null) closeSync(fd);
+    }
+  }
+}
+class CommandManager {
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+    this.store = new CommandRunStore(projectPath);
+  }
+  store;
+  children = /* @__PURE__ */ new Map();
+  tailers = /* @__PURE__ */ new Map();
+  runsSubscribers = /* @__PURE__ */ new Set();
+  runSubscribers = /* @__PURE__ */ new Map();
+  /**
+   * Exits observed before `run()` finished persisting the record. A command
+   * that dies immediately (bad shell syntax, missing binary) emits `exit`
+   * before the first `upsert` lands; without this the terminal state would be
+   * dropped and the record would stay `running` forever.
+   */
+  pendingEnds = /* @__PURE__ */ new Map();
+  persisted = /* @__PURE__ */ new Set();
+  initPromise = null;
+  /** Idempotent startup pass: reap leftovers, drop expired records. */
+  init() {
+    if (!this.initPromise) this.initPromise = this.reap();
+    return this.initPromise;
+  }
+  // ---- definitions (persisted in .yorz/config.json) ----
+  async listDefs() {
+    const cfg = await loadProjectConfig(this.projectPath);
+    return cfg.commands;
+  }
+  async addDef(name, cli) {
+    const trimmedName = name.trim();
+    const trimmedCli = cli.trim();
+    if (!trimmedName) throw new Error("name is required");
+    if (!trimmedCli) throw new Error("cli is required");
+    const cfg = await loadProjectConfig(this.projectPath);
+    const def = {
+      id: shortId(),
+      name: trimmedName,
+      cli: trimmedCli,
+      createdAt: Date.now()
+    };
+    cfg.commands = [...cfg.commands, def];
+    await saveProjectConfig(this.projectPath, cfg);
+    return def;
+  }
+  async removeDef(commandId) {
+    const cfg = await loadProjectConfig(this.projectPath);
+    const next = cfg.commands.filter((c) => c.id !== commandId);
+    if (next.length === cfg.commands.length) return false;
+    cfg.commands = next;
+    await saveProjectConfig(this.projectPath, cfg);
+    return true;
+  }
+  // ---- runs ----
+  async listRuns() {
+    await this.init();
+    return this.store.list();
+  }
+  async getRun(runId) {
+    await this.init();
+    return this.store.get(runId);
+  }
+  /**
+   * Spawn a command. Idempotent per definition: if that command already has a
+   * live run, the existing record is returned instead of starting a second
+   * process (two dev servers would just fight over the same port).
+   */
+  async run(commandId) {
+    await this.init();
+    const defs = await this.listDefs();
+    const def = defs.find((d) => d.id === commandId);
+    if (!def) throw new CommandNotFoundError(commandId);
+    const existing = (await this.store.list()).find(
+      (r) => r.commandId === commandId && r.status === "running"
+    );
+    if (existing) return existing;
+    const runId = shortId();
+    const logRel = runLogRelPath(runId);
+    const logAbs = join(this.projectPath, ".yorz", "tmp", "commands", `${runId}.log`);
+    await mkdir(join(this.projectPath, ".yorz", "tmp", "commands"), { recursive: true });
+    const now = Date.now();
+    let fd;
+    try {
+      fd = openSync(logAbs, "a");
+    } catch (err) {
+      const failed = {
+        runId,
+        commandId,
+        name: def.name,
+        cli: def.cli,
+        pid: -1,
+        status: "failed",
+        startedAt: now,
+        endedAt: now,
+        exitCode: null,
+        signal: null,
+        logFile: logRel
+      };
+      log$2().error("failed to open command log", { runId, logAbs, err });
+      await this.store.upsert(failed);
+      this.notifyRuns();
+      return failed;
+    }
+    try {
+      const child = spawn(def.cli, {
+        shell: true,
+        cwd: this.projectPath,
+        env: process.env,
+        detached: true,
+        // No pipes: the child writes straight into the log fd. Keeps a chatty
+        // dev server from buffering through this process, and lets the REST
+        // first paint and the SSE tail read from one single source.
+        stdio: ["ignore", fd, fd]
+      });
+      child.unref();
+      const run = {
+        runId,
+        commandId,
+        name: def.name,
+        cli: def.cli,
+        pid: child.pid ?? -1,
+        status: "running",
+        startedAt: now,
+        logFile: logRel
+      };
+      if (!child.pid) {
+        run.status = "failed";
+        run.endedAt = Date.now();
+        run.exitCode = null;
+        run.signal = null;
+      } else {
+        this.children.set(runId, child);
+        child.on("exit", (code, signal) => {
+          this.children.delete(runId);
+          void this.handleExit(runId, signal ? "killed" : "exited", code, signal ?? null);
+        });
+        child.on("error", (err) => {
+          log$2().warn("command child error", { runId, err });
+          this.children.delete(runId);
+          void this.handleExit(runId, "failed", null, null);
+        });
+      }
+      await this.store.upsert(run);
+      this.persisted.add(runId);
+      const raced = this.pendingEnds.get(runId);
+      if (raced) {
+        this.pendingEnds.delete(runId);
+        await this.markRunEnded(runId, raced.status, raced.exitCode, raced.signal);
+        const settled = await this.store.get(runId);
+        if (settled) return settled;
+      }
+      this.notifyRuns();
+      log$2().info("command started", { runId, commandId, pid: run.pid, cli: def.cli });
+      return run;
+    } finally {
+      try {
+        closeSync(fd);
+      } catch {
+      }
+    }
+  }
+  /** Terminate the process but keep the run record and its log. */
+  async stop(runId) {
+    await this.init();
+    const run = await this.store.get(runId);
+    if (!run) throw new RunNotFoundError(runId);
+    if (run.status !== "running") return run;
+    await this.terminate(run);
+    return await this.store.get(runId) ?? run;
+  }
+  /** Terminate if needed, then drop the record and delete the log file. */
+  async clear(runId) {
+    await this.init();
+    const run = await this.store.get(runId);
+    if (!run) return false;
+    if (run.status === "running") await this.terminate(run);
+    this.tailers.get(runId)?.stop();
+    this.tailers.delete(runId);
+    await this.store.remove(runId);
+    await rm(join(this.projectPath, run.logFile), { force: true }).catch(() => {
+    });
+    this.runSubscribers.delete(runId);
+    this.persisted.delete(runId);
+    this.pendingEnds.delete(runId);
+    this.notifyRuns();
+    return true;
+  }
+  async readOutput(runId, offset) {
+    await this.init();
+    const run = await this.store.get(runId);
+    if (!run) throw new RunNotFoundError(runId);
+    return readLogSlice(join(this.projectPath, run.logFile), offset);
+  }
+  // ---- subscriptions (SSE) ----
+  subscribeRuns(cb) {
+    this.runsSubscribers.add(cb);
+    return () => this.runsSubscribers.delete(cb);
+  }
+  subscribeRun(runId, cb) {
+    let set = this.runSubscribers.get(runId);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.runSubscribers.set(runId, set);
+    }
+    set.add(cb);
+    return () => {
+      set.delete(cb);
+      if (set.size === 0) this.runSubscribers.delete(runId);
+    };
+  }
+  subscribeOutput(runId, cb, fromOffset) {
+    const file = join(this.projectPath, runLogRelPath(runId));
+    let tailer = this.tailers.get(runId);
+    if (!tailer) {
+      tailer = new LogTailer(file);
+      this.tailers.set(runId, tailer);
+    }
+    const unsub = tailer.subscribe(cb, fromOffset);
+    return () => {
+      unsub();
+      const t = this.tailers.get(runId);
+      if (t && t.subscriberCount === 0) this.tailers.delete(runId);
+    };
+  }
+  // ---- lifecycle ----
+  /**
+   * Stop every live child. Called on service shutdown: commands are tied to the
+   * service lifetime, so nothing outlives it.
+   */
+  async stopAll() {
+    const runs = await this.store.list().catch(() => []);
+    const live = runs.filter((r) => r.status === "running");
+    await Promise.all(live.map((r) => this.terminate(r).catch(() => {
+    })));
+    for (const t of this.tailers.values()) t.stop();
+    this.tailers.clear();
+  }
+  /** Last-resort synchronous kill for `process.on('exit')`, which cannot await. */
+  stopAllSync() {
+    for (const [runId, child] of this.children) {
+      const pid = child.pid;
+      if (!pid) continue;
+      try {
+        process.kill(-pid, "SIGKILL");
+      } catch {
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {
+        }
+      }
+      this.children.delete(runId);
+    }
+    for (const t of this.tailers.values()) t.stop();
+  }
+  /**
+   * Startup pass. Any record still marked `running` belongs to a previous
+   * service process: kill it if it somehow survived (service SIGKILLed), then
+   * mark it `killed`. Also drops records that finished long ago.
+   */
+  async reap() {
+    const runs = await this.store.list().catch(() => []);
+    if (runs.length === 0) return;
+    const now = Date.now();
+    const kept = [];
+    const dropped = [];
+    for (const run of runs) {
+      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 });
+        }
+        kept.push({ ...run, status: "killed", endedAt: run.endedAt ?? now, exitCode: null });
+        continue;
+      }
+      const endedAt = run.endedAt ?? run.startedAt;
+      if (now - endedAt > RUN_RETENTION_MS) dropped.push(run);
+      else kept.push(run);
+    }
+    await this.store.replaceAll(kept);
+    for (const run of dropped) {
+      await rm(join(this.projectPath, run.logFile), { force: true }).catch(() => {
+      });
+    }
+  }
+  async terminate(run) {
+    if (run.pid > 0) {
+      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", {
+          runId: run.runId,
+          pid: run.pid
+        });
+        killGroup(run.pid, "SIGKILL");
+        await waitForExit(run.pid, STOP_GRACE_MS);
+      }
+    }
+    this.children.delete(run.runId);
+    await this.markRunEnded(run.runId, "killed", null, "SIGTERM");
+  }
+  async handleExit(runId, status, exitCode, signal) {
+    if (!this.persisted.has(runId)) {
+      this.pendingEnds.set(runId, { status, exitCode, signal: signal ?? null });
+      return;
+    }
+    await this.markRunEnded(runId, status, exitCode, signal);
+  }
+  async markRunEnded(runId, status, exitCode, signal) {
+    const run = await this.store.get(runId);
+    if (!run || run.status !== "running") return;
+    const next = {
+      ...run,
+      status,
+      endedAt: Date.now(),
+      exitCode,
+      signal: signal ?? null
+    };
+    await this.store.upsert(next);
+    this.notifyRuns();
+    this.notifyRun(next);
+    log$2().info("command ended", { runId, status, exitCode, signal });
+  }
+  notifyRuns() {
+    if (this.runsSubscribers.size === 0) return;
+    void this.store.list().then((runs) => {
+      for (const cb of this.runsSubscribers) {
+        try {
+          cb(runs);
+        } catch {
+        }
+      }
+    });
+  }
+  notifyRun(run) {
+    const set = this.runSubscribers.get(run.runId);
+    if (!set) return;
+    for (const cb of set) {
+      try {
+        cb(run);
+      } catch {
+      }
+    }
+  }
+}
+const managers = /* @__PURE__ */ new Map();
+function getCommandManager(projectPath) {
+  let m = managers.get(projectPath);
+  if (!m) {
+    m = new CommandManager(projectPath);
+    managers.set(projectPath, m);
+  }
+  return m;
+}
+async function stopAllCommandManagers() {
+  const all = [...managers.values()];
+  managers.clear();
+  await Promise.all(all.map((m) => m.stopAll().catch(() => {
+  })));
+}
+function stopAllCommandManagersSync() {
+  for (const m of managers.values()) m.stopAllSync();
+  managers.clear();
+}
+function readLogSlice(file, offset) {
+  let size = 0;
+  try {
+    size = statSync(file).size;
+  } catch {
+    return { offset: 0, text: "", size: 0, truncated: false };
+  }
+  let start2 = offset ?? Math.max(0, size - OUTPUT_TAIL_LIMIT);
+  let truncated = offset === void 0 && start2 > 0;
+  if (start2 > size) start2 = size;
+  if (start2 < 0) start2 = 0;
+  if (size - start2 > OUTPUT_TAIL_LIMIT) {
+    start2 = size - OUTPUT_TAIL_LIMIT;
+    truncated = true;
+  }
+  const length = size - start2;
+  if (length <= 0) return { offset: start2, text: "", size, truncated };
+  let fd = null;
+  try {
+    fd = openSync(file, "r");
+    const buf = Buffer.alloc(length);
+    const read = readSync(fd, buf, 0, length, start2);
+    return { offset: start2, text: buf.subarray(0, read).toString("utf8"), size, truncated };
+  } catch {
+    return { offset: start2, text: "", size, truncated };
+  } finally {
+    if (fd !== null) closeSync(fd);
+  }
+}
+function currentSize(file) {
+  try {
+    return statSync(file).size;
+  } catch {
+    return 0;
+  }
+}
+function shortId() {
+  return randomBytes(8).toString("hex");
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function killGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch {
+    }
+  }
+}
+async function waitForExit(pid, timeoutMs) {
+  const until = Date.now() + timeoutMs;
+  while (Date.now() < until) {
+    if (!isAlive(pid)) return true;
+    await sleep$1(50);
+  }
+  return !isAlive(pid);
+}
+function sleep$1(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+const MAX_NAME_LEN = 120;
+const MAX_CLI_LEN = 2e3;
+function createCommandsRoutes(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/commands", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    return c.json(await p.commands.listDefs());
+  });
+  app.post("/projects/:projectId/commands", 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 = parseDefBody(body);
+    if ("error" in parsed) return c.json({ error: parsed.error }, 400);
+    const def = await p.commands.addDef(parsed.name, parsed.cli);
+    return c.json(def, 201);
+  });
+  app.delete("/projects/:projectId/commands/:commandId", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const ok = await p.commands.removeDef(c.req.param("commandId"));
+    if (!ok) return c.json({ error: "command not found" }, 404);
+    return c.json({ ok: true });
+  });
+  app.get("/projects/:projectId/command-runs", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    return c.json(await p.commands.listRuns());
+  });
+  app.post("/projects/:projectId/command-runs", 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 commandId = body && typeof body === "object" ? body.commandId : void 0;
+    if (typeof commandId !== "string" || !commandId.trim()) {
+      return c.json({ error: "commandId required" }, 400);
+    }
+    try {
+      const run = await p.commands.run(commandId.trim());
+      return c.json(run, 201);
+    } catch (err) {
+      if (err instanceof CommandNotFoundError) return c.json({ error: "command not found" }, 404);
+      return c.json({ error: err.message }, 400);
+    }
+  });
+  app.get("/projects/:projectId/command-runs/:runId", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const run = await p.commands.getRun(c.req.param("runId"));
+    if (!run) return c.json({ error: "command run not found" }, 404);
+    return c.json(run);
+  });
+  app.get("/projects/:projectId/command-runs/:runId/output", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const raw = c.req.query("offset");
+    let offset;
+    if (raw !== void 0 && raw !== "") {
+      const n = Number(raw);
+      if (!Number.isInteger(n) || n < 0)
+        return c.json({ error: "offset must be a non-negative integer" }, 400);
+      offset = n;
+    }
+    try {
+      return c.json(await p.commands.readOutput(c.req.param("runId"), offset));
+    } catch (err) {
+      if (err instanceof RunNotFoundError) return c.json({ error: "command run not found" }, 404);
+      throw err;
+    }
+  });
+  app.post("/projects/:projectId/command-runs/:runId/stop", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    try {
+      const run = await p.commands.stop(c.req.param("runId"));
+      return c.json({ ok: true, run });
+    } catch (err) {
+      if (err instanceof RunNotFoundError) return c.json({ error: "command run not found" }, 404);
+      throw err;
+    }
+  });
+  app.delete("/projects/:projectId/command-runs/:runId", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const ok = await p.commands.clear(c.req.param("runId"));
+    if (!ok) return c.json({ error: "command run not found" }, 404);
+    return c.json({ ok: true });
+  });
+  return app;
+}
+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 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 (!cli) return { error: "cli required" };
+  if (cli.length > MAX_CLI_LEN) return { error: `cli too long (max ${MAX_CLI_LEN})` };
+  return { name, cli };
+}
 const MIME = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
@@ -3279,6 +4077,7 @@ function createApp(opts) {
   api.route("/", createSpecDraftsRoutes(resolveProject));
   api.route("/", createWorktreeRoutes(opts.registry, worktreeManager));
   api.route("/", createProjectFilesRoutes(resolveProject));
+  api.route("/", createCommandsRoutes(resolveProject));
   api.route("/", createEventsRoutes(resolveProject, opts.registry, projectsBus));
   app.route("/api", api);
   app.route("/", createStaticRoutes(opts.guiRoot));
@@ -3862,6 +4661,7 @@ class SpecWatcher {
 function blocksFrom(message) {
   if (!message || typeof message !== "object") return [];
   const content = message.content;
+  if (typeof content === "string") return content ? [{ type: "text", text: content }] : [];
   return Array.isArray(content) ? content : [];
 }
 function toolResultText(content) {
@@ -4441,6 +5241,8 @@ class SessionManager {
   emitters = /* @__PURE__ */ new Map();
   /** Session ids with an in-flight turn. Drives the list spinner. */
   running = /* @__PURE__ */ new Set();
+  /** Kind of sessions discovered via `listSessions()` but absent from the store. */
+  discoveredKinds = /* @__PURE__ */ new Map();
   statusEmitter = new EventEmitter();
   emitterFor(sid) {
     let e = this.emitters.get(sid);
@@ -4491,6 +5293,7 @@ class SessionManager {
       if (!adapter.capabilities().listSessions) continue;
       try {
         for (const info of await adapter.listSessions()) {
+          if (!nativeIds.has(info.id)) this.discoveredKinds.set(info.id, kind);
           nativeIds.add(info.id);
           const indexed2 = byId.get(info.id);
           if (!indexed2) {
@@ -4538,8 +5341,15 @@ class SessionManager {
     if (!title || isOpaqueTitle(title, sid)) return;
     await this.store.updateTitle(sid, title);
   }
+  async resolveKind(sid) {
+    const known = (await this.store.get(sid))?.kind ?? this.live.get(sid)?.kind ?? this.discoveredKinds.get(sid);
+    if (known) return known;
+    await this.listSessions().catch(() => {
+    });
+    return this.discoveredKinds.get(sid) ?? this.defaultKind;
+  }
   async getMessages(sid) {
-    const kind = (await this.store.get(sid))?.kind ?? this.live.get(sid)?.kind ?? this.defaultKind;
+    const kind = await this.resolveKind(sid);
     const adapter = this.adapters.get(kind);
     if (!adapter.capabilities().getMessages) return [];
     return adapter.getMessages(sid);
@@ -4927,6 +5737,7 @@ class ProjectRegistry {
     const sessions = new SessionManager(input.path, defaultKind, sessionStore, {
       onSessionEnd: notifySessionEnded
     });
+    const commands = getCommandManager(input.path);
     let closed = false;
     const instance = {
       id: input.id,
@@ -4937,6 +5748,7 @@ class ProjectRegistry {
       watcher,
       sessions,
       attachments,
+      commands,
       async close() {
         if (closed) return;
         closed = true;
@@ -4950,6 +5762,8 @@ class ProjectRegistry {
       await attachments.ensureRoot();
       void attachments.cleanupExpired().catch(() => {
       });
+      void commands.init().catch(() => {
+      });
       await watcher.start();
     })();
     this.cache.set(input.id, { instance, startPromise });
@@ -4988,6 +5802,10 @@ async function maxSpecUpdatedAt(projectPath) {
 }
 const DEFAULT_PORT = 7423;
 const MAX_PORT_TRIES = 10;
+const DEFAULT_HOST = "127.0.0.1";
+function isLoopbackHost(host) {
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
 const log$1 = () => getLogger().child("serve");
 async function start(opts = {}) {
   const registry = new ProjectRegistry({ globalConfigPath: opts.globalConfigPath });
@@ -5000,11 +5818,16 @@ async function start(opts = {}) {
   }
   const projects = await registry.list();
   const app = createApp({ registry, guiRoot: opts.guiRoot });
-  const port = await listen(app.fetch, opts.port ?? DEFAULT_PORT);
+  const host = opts.host?.trim() || DEFAULT_HOST;
+  const port = await listen(app.fetch, opts.port ?? DEFAULT_PORT, host);
   const url = `http://localhost:${port.port}/`;
   console.log(`YorZ Service ready at ${url} (${projects.length} project${projects.length === 1 ? "" : "s"})`);
-  for (const lanUrl of listLanUrls(port.port)) {
-    console.log(`  LAN: ${lanUrl}`);
+  if (!isLoopbackHost(host)) {
+    console.log(`  WARNING: bound to ${host} — reachable from the network.`);
+    for (const lanUrl of listLanUrls(port.port)) {
+      console.log(`  LAN: ${lanUrl}`);
+    }
+    log$1().warn("service bound to a non-loopback address", { host, port: port.port });
   }
   for (const p of projects) {
     console.log(`  - ${p.name} -> ${p.path}`);
@@ -5020,12 +5843,14 @@ async function start(opts = {}) {
     logFile: getLogger().filePath
   });
   installGlobalErrorHandlers();
+  installCommandExitGuard();
   if (opts.open) await tryOpenBrowser(url);
   return {
     url,
     port: port.port,
     registry,
     async close() {
+      await stopAllCommandManagers();
       await registry.closeAll();
       await new Promise((resolve2, reject) => {
         port.server.close((err) => err ? reject(err) : resolve2());
@@ -5034,7 +5859,7 @@ async function start(opts = {}) {
     }
   };
 }
-async function listen(fetchHandler, preferredPort) {
+async function listen(fetchHandler, preferredPort, hostname) {
   let lastErr = null;
   for (let i = 0; i < MAX_PORT_TRIES; i++) {
     const tryPort = preferredPort + i;
@@ -5042,7 +5867,7 @@ async function listen(fetchHandler, preferredPort) {
       return await new Promise(
         (resolve2, reject) => {
           const server = serve(
-            { fetch: fetchHandler, port: tryPort, hostname: "0.0.0.0" },
+            { fetch: fetchHandler, port: tryPort, hostname },
             (info) => {
               resolve2({ port: info.port, server });
             }
@@ -5097,6 +5922,14 @@ function logCrash(kind, payload) {
   const body = payload instanceof Error ? payload.stack ?? payload.message : String(payload);
   log$1().error(kind, { detail: body });
 }
+let commandExitGuardInstalled = false;
+function installCommandExitGuard() {
+  if (commandExitGuardInstalled) return;
+  commandExitGuardInstalled = true;
+  process.on("exit", () => {
+    stopAllCommandManagersSync();
+  });
+}
 function installGlobalErrorHandlers() {
   if (process.listenerCount("uncaughtException") > 0) return;
   process.on("uncaughtException", (err) => {
@@ -5134,23 +5967,28 @@ async function runServe(opts) {
   }
   const handle = await start({
     port: opts.port,
+    host: opts.host,
     open: opts.open,
     cwd: opts.cwd ?? process.cwd(),
     noRegisterCwd: opts.noRegisterCwd
   });
-  await upsertProcess({
-    pid: process.pid,
-    port: handle.port,
-    url: handle.url,
-    startedAt: (/* @__PURE__ */ new Date()).toISOString()
-  });
-  console.log(`Stop with: yorz serve stop`);
+  if (opts.recordRuntime) {
+    await upsertProcess({
+      pid: process.pid,
+      port: handle.port,
+      url: handle.url,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    console.log(`Stop with: yorz serve stop`);
+  } else {
+    console.log(`Stop with: Ctrl-C`);
+  }
   const shutdown = async () => {
     console.log("\nShutting down YorZ Service…");
     try {
       await handle.close();
     } finally {
-      await removeRuntimeForPid(process.pid);
+      if (opts.recordRuntime) await removeRuntimeForPid(process.pid);
       process.exit(0);
     }
   };
@@ -5211,10 +6049,12 @@ function startBackgroundServe(opts) {
 function backgroundArgs(opts) {
   const args = ["--foreground"];
   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");
+  args.push("--record-runtime");
   return args;
 }
 async function ensureSkillsInstalledWithLog(cwd) {
@@ -6586,12 +7426,15 @@ program.command("lint [paths...]").description("Lint spec.md / review.md files f
     if (result.exitCode !== 0) process.exit(result.exitCode);
   }
 );
-const serveCmd = program.command("serve").description("Start the YorZ Service (HTTP + SSE + static GUI; multi-project).").option("-p, --port <port>", "port to listen on", "7423").option("--open", "open the GUI in the default browser", false).option("--foreground", "run the service in the foreground", false).option("--background", "run the service in the background (default)", false).option(
+const serveCmd = program.command("serve").description("Start the YorZ Service (HTTP + SSE + static GUI; multi-project).").option("-p, --port <port>", "port to listen on", "7423").option(
+  "--host <address>",
+  "bind address (default: 127.0.0.1; the service runs shell commands, so exposing it to the network is opt-in)"
+).option("--open", "open the GUI in the default browser", false).option("--foreground", "run the service in the foreground", false).option("--background", "run the service in the background (default)", 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("--skip-skill-check", "internal: skip the skill install/update check").hideHelp()
-).action(async (opts) => {
+).addOption(new Option("--record-runtime", "internal: record foreground process").hideHelp()).action(async (opts) => {
   if (opts.foreground && opts.background) {
     throw new Error("Use either --foreground or --background, not both");
   }
@@ -6601,11 +7444,13 @@ const serveCmd = program.command("serve").description("Start the YorZ Service (H
   }
   await runServe({
     port,
+    host: opts.host,
     open: opts.open,
     cwd: opts.cwd,
     noRegisterCwd: opts.registerCwd === false,
     foreground: opts.foreground === true,
-    skipSkillCheck: opts.skipSkillCheck === true
+    skipSkillCheck: opts.skipSkillCheck === true,
+    recordRuntime: opts.recordRuntime === true
   });
 });
 serveCmd.command("stop").description("Stop the background YorZ Service.").action(async () => {