[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-jayminwest--overstory":3,"tool-jayminwest--overstory":64},[4,17,27,35,48,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",140436,2,"2026-04-05T23:32:43",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,43,44,45,15,46,26,13,47],"数据工具","视频","插件","其他","音频",{"id":49,"name":50,"github_repo":51,"description_zh":52,"stars":53,"difficulty_score":10,"last_commit_at":54,"category_tags":55,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,46],{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},2181,"OpenHands","OpenHands\u002FOpenHands","OpenHands 是一个专注于 AI 驱动开发的开源平台，旨在让智能体（Agent）像人类开发者一样理解、编写和调试代码。它解决了传统编程中重复性劳动多、环境配置复杂以及人机协作效率低等痛点，通过自动化流程显著提升开发速度。\n\n无论是希望提升编码效率的软件工程师、探索智能体技术的研究人员，还是需要快速原型验证的技术团队，都能从中受益。OpenHands 提供了灵活多样的使用方式：既可以通过命令行（CLI）或本地图形界面在个人电脑上轻松上手，体验类似 Devin 的流畅交互；也能利用其强大的 Python SDK 自定义智能体逻辑，甚至在云端大规模部署上千个智能体并行工作。\n\n其核心技术亮点在于模块化的软件智能体 SDK，这不仅构成了平台的引擎，还支持高度可组合的开发模式。此外，OpenHands 在 SWE-bench 基准测试中取得了 77.6% 的优异成绩，证明了其解决真实世界软件工程问题的能力。平台还具备完善的企业级功能，支持与 Slack、Jira 等工具集成，并提供细粒度的权限管理，适合从个人开发者到大型企业的各类用户场景。",70626,"2026-04-05T22:51:36",[26,15,13,45],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":69,"readme_en":70,"readme_zh":71,"quickstart_zh":72,"use_case_zh":73,"hero_image_url":74,"owner_login":75,"owner_name":76,"owner_avatar_url":77,"owner_bio":78,"owner_company":79,"owner_location":80,"owner_email":81,"owner_twitter":81,"owner_website":79,"owner_url":82,"languages":83,"stars":92,"forks":93,"last_commit_at":94,"license":95,"difficulty_score":96,"env_os":97,"env_gpu":98,"env_ram":98,"env_deps":99,"category_tags":108,"github_topics":109,"view_count":23,"oss_zip_url":81,"oss_zip_packed_at":81,"status":16,"created_at":113,"updated_at":114,"faqs":115,"releases":151},4029,"jayminwest\u002Foverstory","overstory","Multi-agent orchestration for AI coding agents — pluggable runtime adapters for Claude Code, Pi, and more","Overstory 是一款专为 AI 编程助手设计的多智能体协作编排工具。它旨在解决单个 AI 代理在处理复杂开发任务时能力有限、效率不足的问题，通过将一次编码会话转化为由多个“工人”智能体组成的团队协作模式，显著提升大型项目的开发与重构效率。\n\n该工具主要面向需要处理复杂代码库、进行大规模重构或希望探索多智能体工程模式的资深开发者与技术研究人员。需要注意的是，由于多智能体协作会带来成本增加、错误累积及合并冲突等挑战，Overstory 并不适合普通用户或简单任务场景，使用者需具备一定的风险管控意识。\n\n其核心技术亮点在于独特的架构设计：利用 Git Worktrees 和 tmux 为每个智能体创建隔离的工作空间，通过自定义的 SQLite 邮件系统进行去中心化协调，并内置了分层冲突解决机制以自动合并代码成果。此外，Overstory 拥有高度灵活的插件化运行时接口，支持无缝切换包括 Claude Code、Pi、Gemini CLI、Aider 在内的十余种主流 AI 编程工具，让开发者能根据需求自由组合最合适的智能体阵容，实现真正的定制化自动化开发流。","# Overstory\n\nMulti-agent orchestration for AI coding agents.\n\n[![npm](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@os-eco\u002Foverstory-cli)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@os-eco\u002Foverstory-cli)\n[![CI](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Foverstory\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Foverstory\u002Factions\u002Fworkflows\u002Fci.yml)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](LICENSE)\n\nOverstory turns a single coding session into a multi-agent team by spawning worker agents in git worktrees via tmux, coordinating them through a custom SQLite mail system, and merging their work back with tiered conflict resolution. A pluggable `AgentRuntime` interface lets you swap between 11 runtimes — Claude Code, [Pi](https:\u002F\u002Fgithub.com\u002Fbadlogic\u002Fpi-mono\u002Ftree\u002Fmain\u002Fpackages\u002Fcoding-agent), [Gemini CLI](https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli), [Aider](https:\u002F\u002Faider.chat), [Goose](https:\u002F\u002Fgithub.com\u002Fblock\u002Fgoose), [Amp](https:\u002F\u002Famp.dev), or your own adapter.\n\n> **Warning: Agent swarms are not a universal solution.** Do not deploy Overstory without understanding the risks of multi-agent orchestration — compounding error rates, cost amplification, debugging complexity, and merge conflicts are the normal case, not edge cases. Read [STEELMAN.md](STEELMAN.md) for a full risk analysis and the [Agentic Engineering Book](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Fagentic-engineering-book) ([web version](https:\u002F\u002Fjayminwest.com\u002Fagentic-engineering-book)) before using this tool in production.\n\n## Install\n\nRequires [Bun](https:\u002F\u002Fbun.sh) v1.0+, git, and tmux. At least one supported agent runtime must be installed:\n\n- [Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code) (`claude` CLI)\n- [Pi](https:\u002F\u002Fgithub.com\u002Fbadlogic\u002Fpi-mono\u002Ftree\u002Fmain\u002Fpackages\u002Fcoding-agent) (`pi` CLI)\n- [GitHub Copilot](https:\u002F\u002Fgithub.com\u002Ffeatures\u002Fcopilot) (`copilot` CLI)\n- [Codex](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex) (`codex` CLI)\n- [Gemini CLI](https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli) (`gemini` CLI)\n- [Cursor CLI](https:\u002F\u002Fcursor.com\u002Fdocs\u002Fcli\u002Foverview) (`agent` CLI)\n- [Sapling](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Fsapling) (`sp` CLI)\n- [OpenCode](https:\u002F\u002Fopencode.ai) (`opencode` CLI)\n- [Aider](https:\u002F\u002Faider.chat) (`aider` CLI)\n- [Goose](https:\u002F\u002Fgithub.com\u002Fblock\u002Fgoose) (`goose` CLI)\n- [Amp](https:\u002F\u002Famp.dev) (`amp` CLI)\n\n```bash\nbun install -g @os-eco\u002Foverstory-cli\n```\n\nOr try without installing:\n\n```bash\nnpx @os-eco\u002Foverstory-cli --help\n```\n\n### Development\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Foverstory.git\ncd overstory\nbun install\nbun link              # Makes 'ov' available globally\n\nbun test              # Run all tests\nbun run lint          # Biome check\nbun run typecheck     # tsc --noEmit\n```\n\n## Quick Start\n\n```bash\n# Initialize overstory in your project\ncd your-project\nov init\n\n# Install hooks into .claude\u002Fsettings.local.json\nov hooks install\n\n# Start a coordinator (persistent orchestrator)\nov coordinator start\n\n# Or spawn individual worker agents\nov sling \u003Ctask-id> --capability builder --name my-builder\n\n# Check agent status\nov status\n\n# Live dashboard for monitoring the fleet\nov dashboard\n\n# Nudge a stalled agent\nov nudge \u003Cagent-name>\n\n# Check mail from agents\nov mail check --inject\n```\n\n## Commands\n\nEvery command supports `--json` where noted. Global flags: `-q`\u002F`--quiet`, `--timing`, `--project \u003Cpath>`. ANSI colors respect `NO_COLOR`.\n\n### Core Workflow\n\n| Command | Description |\n|---------|-------------|\n| `ov init` | Initialize `.overstory\u002F` and bootstrap os-eco tools (`--yes`, `--name`, `--tools`, `--skip-mulch`, `--skip-seeds`, `--skip-canopy`, `--skip-onboard`, `--json`) |\n| `ov sling \u003Ctask-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--no-scout-check`, `--runtime`, `--base-branch`, `--profile`, `--json`) |\n| `ov stop \u003Cagent-name>` | Terminate a running agent (`--clean-worktree`, `--json`) |\n| `ov prime` | Load context for orchestrator\u002Fagent (`--agent`, `--compact`) |\n| `ov spec write \u003Ctask-id>` | Write a task specification (`--body`) |\n| `ov discover` | Discover a brownfield codebase via coordinator-driven scout swarm (`--skip`, `--name`, `--attach`, `--watchdog`, `--json`) |\n| `ov update` | Refresh `.overstory\u002F` managed files from installed package (`--agents`, `--manifest`, `--hooks`, `--dry-run`, `--json`) |\n\n### Coordination\n\n| Command | Description |\n|---------|-------------|\n| `ov coordinator start` | Start persistent coordinator agent (`--attach`\u002F`--no-attach`, `--watchdog`, `--monitor`, `--profile`) |\n| `ov coordinator stop` | Stop coordinator |\n| `ov coordinator status` | Show coordinator state |\n| `ov coordinator send` | Fire-and-forget message to coordinator (`--subject`) |\n| `ov coordinator ask` | Synchronous request\u002Fresponse to coordinator (`--subject`, `--timeout`) |\n| `ov coordinator output` | Show recent coordinator output (`--lines`) |\n| `ov coordinator check-complete` | Evaluate exit triggers, return completion status |\n| `ov orchestrator start` | Start multi-repo orchestrator agent (`--attach`\u002F`--no-attach`, `--watchdog`, `--profile`) |\n| `ov orchestrator stop` | Stop orchestrator |\n| `ov orchestrator status` | Show orchestrator state |\n| `ov orchestrator send` | Fire-and-forget message to orchestrator (`--subject`) |\n| `ov orchestrator ask` | Synchronous request\u002Fresponse to orchestrator (`--subject`, `--timeout`) |\n| `ov orchestrator output` | Show recent orchestrator output (`--lines`) |\n| `ov supervisor start` | **[DEPRECATED]** Start per-project supervisor agent |\n| `ov supervisor stop` | **[DEPRECATED]** Stop supervisor |\n| `ov supervisor status` | **[DEPRECATED]** Show supervisor state |\n\n### Messaging\n\n| Command | Description |\n|---------|-------------|\n| `ov mail send` | Send a message (`--to`, `--subject`, `--body`, `--type`, `--priority`) |\n| `ov mail check` | Check inbox — unread messages (`--agent`, `--inject`, `--debounce`, `--json`) |\n| `ov mail list` | List messages with filters (`--from`, `--to`, `--unread`) |\n| `ov mail read \u003Cid>` | Mark message as read |\n| `ov mail reply \u003Cid>` | Reply in same thread (`--body`) |\n| `ov nudge \u003Cagent> [message]` | Send a text nudge to an agent (`--from`, `--force`, `--json`) |\n\n### Task Groups\n\n| Command | Description |\n|---------|-------------|\n| `ov group create \u003Cname>` | Create a task group for batch tracking |\n| `ov group status \u003Cname>` | Show group progress |\n| `ov group add \u003Cname> \u003Cissue-id>` | Add issue to group |\n| `ov group list` | List all groups |\n\n### Merge\n\n| Command | Description |\n|---------|-------------|\n| `ov merge` | Merge agent branches into canonical (`--branch`, `--all`, `--into`, `--dry-run`, `--json`) |\n\n### Observability\n\n| Command | Description |\n|---------|-------------|\n| `ov status` | Show all active agents, worktrees, tracker state (`--json`, `--verbose`, `--all`) |\n| `ov dashboard` | Live TUI dashboard for agent monitoring (`--interval`, `--all`) |\n| `ov inspect \u003Cagent>` | Deep per-agent inspection (`--follow`, `--interval`, `--no-tmux`, `--limit`, `--json`) |\n| `ov trace` | View agent\u002Ftask timeline (`--agent`, `--run`, `--since`, `--until`, `--limit`, `--json`) |\n| `ov errors` | Aggregated error view across agents (`--agent`, `--run`, `--since`, `--until`, `--limit`, `--json`) |\n| `ov replay` | Interleaved chronological replay (`--run`, `--agent`, `--since`, `--until`, `--limit`, `--json`) |\n| `ov feed` | Unified real-time event stream (`--follow`, `--interval`, `--agent`, `--run`, `--json`) |\n| `ov logs` | Query NDJSON logs across agents (`--agent`, `--level`, `--since`, `--until`, `--follow`, `--json`) |\n| `ov costs` | Token\u002Fcost analysis and breakdown (`--live`, `--self`, `--agent`, `--run`, `--bead`, `--by-capability`, `--last`, `--json`) |\n| `ov metrics` | Show session metrics (`--last`, `--json`) |\n| `ov run list` | List orchestration runs (`--last`, `--json`) |\n| `ov run show \u003Cid>` | Show run details |\n| `ov run complete` | Mark current run as completed |\n\n### Infrastructure\n\n| Command | Description |\n|---------|-------------|\n| `ov hooks install` | Install orchestrator hooks to `.claude\u002Fsettings.local.json` (`--force`) |\n| `ov hooks uninstall` | Remove orchestrator hooks |\n| `ov hooks status` | Check if hooks are installed |\n| `ov worktree list` | List worktrees with status |\n| `ov worktree clean` | Remove completed worktrees (`--completed`, `--all`, `--force`) |\n| `ov watch` | Start watchdog daemon — Tier 0 (`--interval`, `--background`) |\n| `ov monitor start` | Start Tier 2 monitor agent |\n| `ov monitor stop` | Stop monitor agent |\n| `ov monitor status` | Show monitor state |\n| `ov log \u003Cevent>` | Log a hook event (`--agent`) |\n| `ov clean` | Clean up worktrees, sessions, artifacts (`--completed`, `--all`, `--run`) |\n| `ov doctor` | Run health checks on overstory setup — 12 categories (`--category`, `--fix`, `--json`) |\n| `ov ecosystem` | Show os-eco tool versions and health (`--json`) |\n| `ov upgrade` | Upgrade overstory to latest npm version (`--check`, `--all`, `--json`) |\n| `ov agents discover` | Discover agents by capability\u002Fstate\u002Fparent (`--capability`, `--state`, `--parent`, `--json`) |\n| `ov completions \u003Cshell>` | Generate shell completions (bash, zsh, fish) |\n\n## Architecture\n\nOverstory uses instruction overlays and tool-call guards to turn agent sessions into orchestrated workers. Each agent runs in an isolated git worktree via tmux. Inter-agent messaging is handled by a custom SQLite mail system (WAL mode, ~1-5ms per query) with typed protocol messages and broadcast support. A FIFO merge queue with 4-tier conflict resolution merges agent branches back to canonical. A tiered watchdog system (Tier 0 mechanical daemon, Tier 1 AI-assisted triage, Tier 2 monitor agent) ensures fleet health. See [CLAUDE.md](CLAUDE.md) for full technical details.\n\n### Runtime Adapters\n\nOverstory is runtime-agnostic. The `AgentRuntime` interface (`src\u002Fruntimes\u002Ftypes.ts`) defines the contract — each adapter handles spawning, config deployment, guard enforcement, readiness detection, and transcript parsing for its runtime. Set the default in `config.yaml` or override per-agent with `ov sling --runtime \u003Cname>`.\n\n| Runtime | CLI | Guard Mechanism | Stability |\n|---------|-----|-----------------|-----------|\n| Claude Code | `claude` | `settings.local.json` hooks | Stable |\n| Sapling | `sp` | `.sapling\u002Fguards.json` | Stable |\n| Pi | `pi` | `.pi\u002Fextensions\u002F` guard extension | Experimental |\n| Copilot | `copilot` | (none — `--allow-all-tools`) | Experimental |\n| Cursor | `agent` | (none — `--yolo`) | Experimental |\n| Codex | `codex` | OS-level sandbox (Seatbelt\u002FLandlock) | Experimental |\n| Gemini | `gemini` | `--sandbox` flag | Experimental |\n| Aider | `aider` | (none — `--yes-always`) | Experimental |\n| Goose | `goose` | Profile-based permissions | Experimental |\n| Amp | `amp` | Built-in approval system | Experimental |\n| OpenCode | `opencode` | (none) | Experimental |\n\n## How It Works\n\nInstruction overlays + tool-call guards + the `ov` CLI turn your coding session into a multi-agent orchestrator. A persistent coordinator agent manages task decomposition and dispatch, while a mechanical watchdog daemon monitors agent health in the background.\n\n```\nOrchestrator (multi-repo coordinator of coordinators)\n  --> Coordinator (persistent orchestrator at project root)\n        --> Supervisor \u002F Lead (team lead, depth 1)\n              --> Workers: Scout, Builder, Reviewer, Merger (depth 2)\n```\n\n### Agent Types\n\n| Agent | Role | Access |\n|-------|------|--------|\n| **Orchestrator** | Multi-repo coordinator of coordinators — dispatches coordinators per sub-repo | Read-only |\n| **Coordinator** | Persistent orchestrator — decomposes objectives, dispatches agents, tracks task groups | Read-only |\n| **Supervisor** | Per-project team lead — manages worker lifecycle, handles nudge\u002Fescalation | Read-only |\n| **Scout** | Read-only exploration and research | Read-only |\n| **Builder** | Implementation and code changes | Read-write |\n| **Reviewer** | Validation and code review | Read-only |\n| **Lead** | Team coordination, can spawn sub-workers | Read-write |\n| **Merger** | Branch merge specialist | Read-write |\n| **Monitor** | Tier 2 continuous fleet patrol — ongoing health monitoring | Read-only |\n\n### Key Architecture\n\n- **Agent Definitions**: Two-layer system — base `.md` files define the HOW (workflow), per-task overlays define the WHAT (task scope). Base definition content is injected into spawned agent overlays automatically.\n- **Messaging**: Custom SQLite mail system with typed protocol — 8 message types (`worker_done`, `merge_ready`, `dispatch`, `escalation`, etc.) for structured agent coordination, plus broadcast messaging with group addresses (`@all`, `@builders`, etc.)\n- **Worktrees**: Each agent gets an isolated git worktree — no file conflicts between agents\n- **Merge**: FIFO merge queue (SQLite-backed) with 4-tier conflict resolution\n- **Watchdog**: Tiered health monitoring — Tier 0 mechanical daemon (tmux\u002Fpid liveness), Tier 1 AI-assisted failure triage, Tier 2 monitor agent for continuous fleet patrol\n- **Tool Enforcement**: Runtime-specific guards (hooks for Claude Code, extensions for Pi) mechanically block file modifications for non-implementation agents and dangerous git operations for all agents\n- **Task Groups**: Batch coordination with auto-close when all member issues complete\n- **Session Lifecycle**: Checkpoint save\u002Frestore for compaction survivability, handoff orchestration for crash recovery\n- **Token Instrumentation**: Session metrics extracted from runtime transcript files (JSONL)\n\n## Project Structure\n\n```\noverstory\u002F\n  src\u002F\n    index.ts                      CLI entry point (Commander.js program)\n    types.ts                      Shared types and interfaces\n    config.ts                     Config loader + validation\n    errors.ts                     Custom error types\n    json.ts                       Standardized JSON envelope helpers\n    commands\u002F                     One file per CLI subcommand (37 commands)\n      agents.ts                   Agent discovery and querying\n      coordinator.ts              Persistent orchestrator lifecycle\n      supervisor.ts               Team lead management [DEPRECATED]\n      dashboard.ts                Live TUI dashboard (ANSI via Chalk)\n      hooks.ts                    Orchestrator hooks management\n      sling.ts                    Agent spawning\n      group.ts                    Task group batch tracking\n      nudge.ts                    Agent nudging\n      mail.ts                     Inter-agent messaging\n      monitor.ts                  Tier 2 monitor management\n      merge.ts                    Branch merging\n      status.ts                   Fleet status overview\n      prime.ts                    Context priming\n      init.ts                     Project initialization\n      worktree.ts                 Worktree management\n      watch.ts                    Watchdog daemon\n      log.ts                      Hook event logging\n      logs.ts                     NDJSON log query\n      feed.ts                     Unified real-time event stream\n      run.ts                      Orchestration run lifecycle\n      trace.ts                    Agent\u002Ftask timeline viewing\n      clean.ts                    Worktree\u002Fsession cleanup\n      doctor.ts                   Health check runner (12 check modules)\n      inspect.ts                  Deep per-agent inspection\n      spec.ts                     Task spec management\n      errors.ts                   Aggregated error view\n      replay.ts                   Interleaved event replay\n      stop.ts                     Agent termination\n      costs.ts                    Token\u002Fcost analysis\n      metrics.ts                  Session metrics\n      ecosystem.ts                os-eco tool dashboard\n      update.ts                   Refresh managed files\n      upgrade.ts                  npm version upgrades\n      discover.ts                 Brownfield codebase discovery via coordinator-driven scout swarm\n      orchestrator.ts             Multi-repo coordination (PersistentAgentSpec)\n      completions.ts              Shell completion generation (bash\u002Fzsh\u002Ffish)\n    canopy\u002F\n      client.ts                   Canopy client (prompt rendering, listing, emission)\n    agents\u002F                       Agent lifecycle management\n      manifest.ts                 Agent registry (load + query)\n      overlay.ts                  Dynamic CLAUDE.md overlay generator\n      identity.ts                 Persistent agent identity (CVs)\n      checkpoint.ts               Session checkpoint save\u002Frestore\n      lifecycle.ts                Handoff orchestration\n      hooks-deployer.ts           Deploy hooks + tool enforcement\n      copilot-hooks-deployer.ts   Deploy hooks config to Copilot worktrees\n      guard-rules.ts              Shared guard constants (tool lists, bash patterns)\n    worktree\u002F                     Git worktree + tmux management\n    mail\u002F                         SQLite mail system (typed protocol, broadcast)\n    merge\u002F                        FIFO queue + conflict resolution\n    watchdog\u002F                     Tiered health monitoring (daemon, triage, health)\n    logging\u002F                      Multi-format logger + sanitizer + reporter + color control + shared theme\u002Fformat\n    metrics\u002F                      SQLite metrics + pricing + transcript parsing\n    doctor\u002F                       Health check modules (12 checks)\n    utils\u002F                        Shared utilities (bin, fs, pid, time, version)\n    insights\u002F                     Session insight analyzer for auto-expertise\n    runtimes\u002F                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot, Codex, Gemini, Sapling, OpenCode, Cursor, Aider, Goose, Amp)\n    tracker\u002F                      Pluggable task tracker (beads + seeds backends)\n    mulch\u002F                        mulch client (programmatic API + CLI wrapper)\n    e2e\u002F                          End-to-end lifecycle tests\n  agents\u002F                         Base agent definitions (.md, 9 roles) + skill definitions\n  templates\u002F                      Templates for overlays and hooks\n```\n\n## Configuration\n\n### Gateway Providers\n\nRoute agent API calls through custom gateway endpoints (z.ai, OpenRouter, self-hosted proxies). Configure providers in `.overstory\u002Fconfig.yaml`:\n\n```yaml\nproviders:\n  anthropic:\n    type: native\n  zai:\n    type: gateway\n    baseUrl: https:\u002F\u002Fapi.z.ai\u002Fv1\n    authTokenEnv: ZAI_API_KEY\n  openrouter:\n    type: gateway\n    baseUrl: https:\u002F\u002Fopenrouter.ai\u002Fapi\u002Fv1\n    authTokenEnv: OPENROUTER_API_KEY\nmodels:\n  builder: zai\u002Fclaude-sonnet-4-6\n  scout: openrouter\u002Fopenai\u002Fgpt-4o\n```\n\n**How it works:** Model refs use `provider\u002Fmodel-id` format. Overstory sets `ANTHROPIC_BASE_URL` to the gateway `baseUrl`, `ANTHROPIC_AUTH_TOKEN` from the env var named in `authTokenEnv`, and `ANTHROPIC_API_KEY=\"\"` to prevent direct Anthropic calls. The agent receives `\"sonnet\"` as a model alias and Claude Code routes via env vars.\n\n**Environment variable notes:**\n- `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_API_KEY` are mutually exclusive per-agent\n- Gateway agents get `ANTHROPIC_API_KEY=\"\"` and `ANTHROPIC_AUTH_TOKEN` from provider config\n- Direct Anthropic API calls (merge resolver, watchdog triage) still need `ANTHROPIC_API_KEY` in the orchestrator env\n\n**Validation:** `ov doctor --category providers` checks reachability, auth tokens, model-provider refs, and tool-use compatibility.\n\n**`ProviderConfig` fields:**\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `type` | `native` or `gateway` | Yes | Provider type |\n| `baseUrl` | string | Gateway only | API endpoint URL |\n| `authTokenEnv` | string | Gateway only | Env var name holding auth token |\n\n## Troubleshooting\n\n### Coordinator died during startup\n\nThis error means the coordinator tmux session exited before the TUI became ready. The most common cause is slow shell initialization.\n\n**Step 1: Measure shell startup time**\n\n```bash\ntime zsh -i -c exit   # For zsh\ntime bash -i -c exit  # For bash\n```\n\nIf startup takes more than 1 second, slow shell init is likely the cause.\n\n**Step 2: Common slow-startup causes**\n\n| Cause | Typical delay | Fix |\n|-------|---------------|-----|\n| oh-my-zsh with many plugins | 1-5s | Reduce plugins, switch to lighter framework (zinit with lazy loading) |\n| nvm (Node Version Manager) | 1-3s | Use `--no-use` + lazy-load nvm, or switch to fnm\u002Fvolta |\n| pyenv init | 0.5-2s | Lazy-load pyenv |\n| rbenv init | 0.5-1s | Lazy-load rbenv |\n| starship prompt | 0.5-1s | Check starship timings |\n| conda auto-activate | 1-3s | `auto_activate_base: false` in `.condarc` |\n| Homebrew shellenv | 0.5-1s | Cache output instead of evaluating every shell start |\n\n**Step 3: Configure `shellInitDelayMs`** in `.overstory\u002Fconfig.yaml`:\n\n```yaml\nruntime:\n  shellInitDelayMs: 3000\n```\n\n- Default: `0` (no delay)\n- Typical values: `1000`–`5000` depending on shell startup time\n- Values above `30000` (30s) trigger a warning\n- Inserts a delay between tmux session creation and TUI readiness polling\n\n**Step 4: Optimization examples**\n\nLazy-load nvm (add to `~\u002F.zshrc` or `~\u002F.bashrc`):\n\n```bash\n# Lazy-load nvm — only activates when you first call nvm\u002Fnode\u002Fnpm\nexport NVM_DIR=\"$HOME\u002F.nvm\"\nnvm() { unset -f nvm node npm npx; [ -s \"$NVM_DIR\u002Fnvm.sh\" ] && . \"$NVM_DIR\u002Fnvm.sh\"; nvm \"$@\"; }\nnode() { unset -f nvm node npm npx; [ -s \"$NVM_DIR\u002Fnvm.sh\" ] && . \"$NVM_DIR\u002Fnvm.sh\"; node \"$@\"; }\nnpm()  { unset -f nvm node npm npx; [ -s \"$NVM_DIR\u002Fnvm.sh\" ] && . \"$NVM_DIR\u002Fnvm.sh\"; npm  \"$@\"; }\nnpx()  { unset -f nvm node npm npx; [ -s \"$NVM_DIR\u002Fnvm.sh\" ] && . \"$NVM_DIR\u002Fnvm.sh\"; npx  \"$@\"; }\n```\n\nReduce oh-my-zsh plugins (edit `~\u002F.zshrc`):\n\n```bash\n# Before: plugins=(git zsh-autosuggestions zsh-syntax-highlighting node npm python ruby rbenv pyenv ...)\n# After: keep only what you use regularly\nplugins=(git)\n```\n\n## Part of os-eco\n\nOverstory is part of the [os-eco](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Fos-eco) AI agent tooling ecosystem.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fjayminwest_overstory_readme_00510ee15b83.png\" alt=\"os-eco\" width=\"444\" \u002F>\n\u003C\u002Fp>\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT\n","# Overstory\n\n面向 AI 编码代理的多智能体编排工具。\n\n[![npm](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@os-eco\u002Foverstory-cli)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@os-eco\u002Foverstory-cli)\n[![CI](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Foverstory\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Foverstory\u002Factions\u002Fworkflows\u002Fci.yml)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](LICENSE)\n\nOverstory 通过在 Git 工作树中利用 tmux 派生工作代理、借助自定义 SQLite 邮件系统进行协调，并以分层冲突解决机制合并它们的工作成果，将单个编码会话转变为一个多智能体团队。一个可插拔的 `AgentRuntime` 接口允许你在 11 种运行时之间切换——Claude Code、[Pi](https:\u002F\u002Fgithub.com\u002Fbadlogic\u002Fpi-mono\u002Ftree\u002Fmain\u002Fpackages\u002Fcoding-agent)、[Gemini CLI](https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli)、[Aider](https:\u002F\u002Faider.chat)、[Goose](https:\u002F\u002Fgithub.com\u002Fblock\u002Fgoose)、[Amp](https:\u002F\u002Famp.dev)，或你自己的适配器。\n\n> **警告：智能体群并非万能解决方案。** 在不了解多智能体编排的风险之前，请勿部署 Overstory——错误率叠加、成本放大、调试复杂性以及合并冲突都是常态，而非边缘情况。请在将此工具用于生产环境前阅读 [STEELMAN.md](STEELMAN.md) 中的完整风险分析，以及 [Agentic Engineering Book](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Fagentic-engineering-book)（[网页版](https:\u002F\u002Fjayminwest.com\u002Fagentic-engineering-book)）。\n\n## 安装\n\n需要 [Bun](https:\u002F\u002Fbun.sh) v1.0+、git 和 tmux。至少需安装一种受支持的代理运行时：\n\n- [Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code) (`claude` CLI)\n- [Pi](https:\u002F\u002Fgithub.com\u002Fbadlogic\u002Fpi-mono\u002Ftree\u002Fmain\u002Fpackages\u002Fcoding-agent) (`pi` CLI)\n- [GitHub Copilot](https:\u002F\u002Fgithub.com\u002Ffeatures\u002Fcopilot) (`copilot` CLI)\n- [Codex](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex) (`codex` CLI)\n- [Gemini CLI](https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli) (`gemini` CLI)\n- [Cursor CLI](https:\u002F\u002Fcursor.com\u002Fdocs\u002Fcli\u002Foverview) (`agent` CLI)\n- [Sapling](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Fsapling) (`sp` CLI)\n- [OpenCode](https:\u002F\u002Fopencode.ai) (`opencode` CLI)\n- [Aider](https:\u002F\u002Faider.chat) (`aider` CLI)\n- [Goose](https:\u002F\u002Fgithub.com\u002Fblock\u002Fgoose) (`goose` CLI)\n- [Amp](https:\u002F\u002Famp.dev) (`amp` CLI)\n\n```bash\nbun install -g @os-eco\u002Foverstory-cli\n```\n\n或者无需安装直接试用：\n\n```bash\nnpx @os-eco\u002Foverstory-cli --help\n```\n\n### 开发\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Foverstory.git\ncd overstory\nbun install\nbun link              # 使 'ov' 全局可用\n\nbun test              # 运行所有测试\nbun run lint          # Biome 检查\nbun run typecheck     # tsc --noEmit\n```\n\n## 快速入门\n\n```bash\n# 在你的项目中初始化 Overstory\ncd your-project\nov init\n\n# 将钩子安装到 .claude\u002Fsettings.local.json\nov hooks install\n\n# 启动协调器（持久化编排器）\nov coordinator start\n\n# 或者派生独立的工作代理\nov sling \u003Ctask-id> --capability builder --name my-builder\n\n# 查看代理状态\nov status\n\n# 实时仪表板，用于监控整个代理集群\nov dashboard\n\n# 推动卡住的代理\nov nudge \u003Cagent-name>\n\n# 查看来自代理的邮件\nov mail check --inject\n```\n\n## 命令\n\n每个命令在标注处都支持 `--json`。全局标志：`-q`\u002F`--quiet`、`--timing`、`--project \u003Cpath>`。ANSI 颜色会尊重 `NO_COLOR` 设置。\n\n### 核心流程\n\n| 命令 | 描述 |\n|------|------|\n| `ov init` | 初始化 `.overstory\u002F` 并引导 os-eco 工具（`--yes`、`--name`、`--tools`、`--skip-mulch`、`--skip-seeds`、`--skip-canopy`、`--skip-onboard`、`--json`） |\n| `ov sling \u003Ctask-id>` | 派生一个工作代理（`--capability`、`--name`、`--spec`、`--files`、`--parent`、`--depth`、`--skip-scout`、`--skip-review`、`--max-agents`、`--dispatch-max-agents`、`--skip-task-check`、`--no-scout-check`、`--runtime`、`--base-branch`、`--profile`、`--json`） |\n| `ov stop \u003Cagent-name>` | 终止正在运行的代理（`--clean-worktree`、`--json`） |\n| `ov prime` | 为编排器\u002F代理加载上下文（`--agent`、`--compact`） |\n| `ov spec write \u003Ctask-id>` | 编写任务规范（`--body`） |\n| `ov discover` | 通过协调驱动的侦察蜂群发现现有代码库（`--skip`、`--name`、`--attach`、`--watchdog`、`--json`） |\n| `ov update` | 从已安装包中刷新 `.overstory\u002F` 管理的文件（`--agents`、`--manifest`、`--hooks`、`--dry-run`、`--json`） |\n\n### 协调\n\n| 命令 | 描述 |\n|------|------|\n| `ov coordinator start` | 启动持久化协调代理（`--attach`\u002F`--no-attach`、`--watchdog`、`--monitor`、`--profile`） |\n| `ov coordinator stop` | 停止协调器 |\n| `ov coordinator status` | 显示协调器状态 |\n| `ov coordinator send` | 向协调器发送即发即弃的消息（`--subject`） |\n| `ov coordinator ask` | 向协调器发起同步请求与响应（`--subject`、`--timeout`） |\n| `ov coordinator output` | 显示协调器近期输出（`--lines`） |\n| `ov coordinator check-complete` | 评估退出触发条件，返回完成状态 |\n| `ov orchestrator start` | 启动多仓库编排代理（`--attach`\u002F`--no-attach`、`--watchdog`、`--profile`） |\n| `ov orchestrator stop` | 停止编排器 |\n| `ov orchestrator status` | 显示编排器状态 |\n| `ov orchestrator send` | 向编排器发送即发即弃的消息（`--subject`） |\n| `ov orchestrator ask` | 向编排器发起同步请求与响应（`--subject`、`--timeout`） |\n| `ov orchestrator output` | 显示编排器近期输出（`--lines`） |\n| `ov supervisor start` | **[已弃用]** 启动项目级监督代理 |\n| `ov supervisor stop` | **[已弃用]** 停止监督代理 |\n| `ov supervisor status` | **[已弃用]** 显示监督代理状态 |\n\n### 消息传递\n\n| 命令 | 描述 |\n|------|------|\n| `ov mail send` | 发送消息（`--to`、`--subject`、`--body`、`--type`、`--priority`） |\n| `ov mail check` | 检查收件箱——未读消息（`--agent`、`--inject`、`--debounce`、`--json`） |\n| `ov mail list` | 列出带有筛选条件的消息（`--from`、`--to`、`--unread`） |\n| `ov mail read \u003Cid>` | 标记消息为已读 |\n| `ov mail reply \u003Cid>` | 在同一对话线程中回复（`--body`） |\n| `ov nudge \u003Cagent> [message]` | 向代理发送简短提醒（`--from`、`--force`、`--json`） |\n\n### 任务组\n\n| 命令 | 描述 |\n|------|------|\n| `ov group create \u003Cname>` | 创建用于批量跟踪的任务组 |\n| `ov group status \u003Cname>` | 显示组进度 |\n| `ov group add \u003Cname> \u003Cissue-id>` | 将问题添加到组 |\n| `ov group list` | 列出所有组 |\n\n### 合并\n\n| 命令 | 描述 |\n|------|------|\n| `ov merge` | 将代理分支合并到主干（`--branch`、`--all`、`--into`、`--dry-run`、`--json`） |\n\n### 可观测性\n\n| 命令 | 描述 |\n|---------|-------------|\n| `ov status` | 显示所有活跃代理、工作树和跟踪器状态（`--json`、`--verbose`、`--all`） |\n| `ov dashboard` | 用于代理监控的实时 TUI 仪表板（`--interval`、`--all`） |\n| `ov inspect \u003Cagent>` | 对单个代理进行深度检查（`--follow`、`--interval`、`--no-tmux`、`--limit`、`--json`） |\n| `ov trace` | 查看代理\u002F任务时间线（`--agent`、`--run`、`--since`、`--until`、`--limit`、`--json`） |\n| `ov errors` | 聚合显示跨代理的错误视图（`--agent`、`--run`、`--since`、`--until`、`--limit`、`--json`） |\n| `ov replay` | 按时间顺序交错回放（`--run`、`--agent`、`--since`、`--until`、`--limit`、`--json`） |\n| `ov feed` | 统一的实时事件流（`--follow`、`--interval`、`--agent`、`--run`、`--json`） |\n| `ov logs` | 查询跨代理的 NDJSON 日志（`--agent`、`--level`、`--since`、`--until`、`--follow`、`--json`） |\n| `ov costs` | 令牌\u002F成本分析与细分（`--live`、`--self`、`--agent`、`--run`、`--bead`、`--by-capability`、`--last`、`--json`） |\n| `ov metrics` | 显示会话指标（`--last`、`--json`） |\n| `ov run list` | 列出编排运行记录（`--last`、`--json`） |\n| `ov run show \u003Cid>` | 显示运行详情 |\n| `ov run complete` | 将当前运行标记为已完成 |\n\n### 基础设施\n\n| 命令 | 描述 |\n|---------|-------------|\n| `ov hooks install` | 将编排器钩子安装到 `.claude\u002Fsettings.local.json` 文件中（`--force`） |\n| `ov hooks uninstall` | 移除编排器钩子 |\n| `ov hooks status` | 检查是否已安装钩子 |\n| `ov worktree list` | 列出带有状态的工作树 |\n| `ov worktree clean` | 清理已完成的工作树（`--completed`、`--all`、`--force`） |\n| `ov watch` | 启动看门狗守护进程 — 第 0 层（`--interval`、`--background`） |\n| `ov monitor start` | 启动第 2 层监控代理 |\n| `ov monitor stop` | 停止监控代理 |\n| `ov monitor status` | 显示监控状态 |\n| `ov log \u003Cevent>` | 记录钩子事件（`--agent`） |\n| `ov clean` | 清理工作树、会话和工件（`--completed`、`--all`、`--run`） |\n| `ov doctor` | 对 Overstory 部署执行健康检查 — 共 12 个类别（`--category`、`--fix`、`--json`） |\n| `ov ecosystem` | 显示操作系统生态工具的版本及健康状况（`--json`） |\n| `ov upgrade` | 将 Overstory 升级到最新的 npm 版本（`--check`、`--all`、`--json`） |\n| `ov agents discover` | 根据能力\u002F状态\u002F父代理发现代理（`--capability`、`--state`、`--parent`、`--json`） |\n| `ov completions \u003Cshell>` | 生成 shell 补全脚本（bash、zsh、fish） |\n\n## 架构\n\nOverstory 使用指令叠加层和工具调用防护机制，将代理会话转化为编排式工作流。每个代理通过 tmux 在隔离的 Git 工作树中运行。代理间的消息传递由自定义的 SQLite 邮件系统（WAL 模式，每次查询约 1–5 毫秒）处理，支持类型化协议消息和广播功能。一个具有 4 层冲突解决机制的 FIFO 合并队列会将各代理分支合并回规范分支。分层看门狗系统（第 0 层机械守护进程、第 1 层 AI 辅助分流、第 2 层监控代理）确保整个集群的健康状态。完整技术细节请参阅 [CLAUDE.md](CLAUDE.md)。\n\n### 运行时适配器\n\nOverstory 是运行时无关的。`AgentRuntime` 接口（`src\u002Fruntimes\u002Ftypes.ts`）定义了契约——每个适配器负责为其运行时环境启动进程、部署配置、实施防护机制、检测就绪状态以及解析会话日志。可在 `config.yaml` 中设置默认值，或使用 `ov sling --runtime \u003Cname>` 命令为特定代理覆盖设置。\n\n| 运行时 | CLI | 防护机制 | 稳定性 |\n|---------|-----|-----------------|-----------|\n| Claude Code | `claude` | `settings.local.json` 钩子 | 稳定 |\n| Sapling | `sp` | `.sapling\u002Fguards.json` | 稳定 |\n| Pi | `pi` | `.pi\u002Fextensions\u002F` 防护扩展 | 实验性 |\n| Copilot | `copilot` | （无 — `--allow-all-tools`） | 实验性 |\n| Cursor | `agent` | （无 — `--yolo`） | 实验性 |\n| Codex | `codex` | 操作系统级别的沙箱（Seatbelt\u002FLandlock） | 实验性 |\n| Gemini | `gemini` | `--sandbox` 标志 | 实验性 |\n| Aider | `aider` | （无 — `--yes-always`） | 实验性 |\n| Goose | `goose` | 基于配置文件的权限 | 实验性 |\n| Amp | `amp` | 内置审批系统 | 实验性 |\n| OpenCode | `opencode` | （无） | 实验性 |\n\n## 工作原理\n\n指令叠加层 + 工具调用防护机制 + `ov` CLI 将您的编码会话转变为多代理编排系统。一个持久化的协调代理负责管理任务分解和调度，而机械看门狗守护进程则在后台监控代理的健康状况。\n\n```\n编排器（多仓库协调者的协调者）\n  --> 协调器（项目根目录下的持久化编排者）\n        --> 监督员 \u002F 团队负责人（团队领导，第 1 层）\n              --> 工人：侦察员、构建者、评审员、合并者（第 2 层）\n```\n\n### 代理类型\n\n| 代理 | 角色 | 权限 |\n|-------|------|--------|\n| **编排器** | 多仓库协调者的协调者——为每个子仓库派遣协调器 | 只读 |\n| **协调器** | 持久化编排者——分解目标、派遣代理、跟踪任务组 | 只读 |\n| **监督员** | 项目级团队负责人——管理工人生命周期、处理提醒\u002F升级 | 只读 |\n| **侦察员** | 只读探索与研究 | 只读 |\n| **构建者** | 实现与代码修改 | 读写 |\n| **评审员** | 验证与代码审查 | 只读 |\n| **领队** | 团队协调，可派生子工人 | 读写 |\n| **合并者** | 分支合并专家 | 读写 |\n| **监控员** | 第 2 层持续舰队巡逻——持续健康监测 | 只读 |\n\n### 关键架构\n\n- **代理定义**：两层系统——基础 `.md` 文件定义 HOW（工作流程），每项任务的叠加层定义 WHAT（任务范围）。基础定义内容会自动注入到派生的代理叠加层中。\n- **消息传递**：自定义的 SQLite 邮件系统，采用类型化协议——8 种消息类型（`worker_done`、`merge_ready`、`dispatch`、`escalation` 等），用于结构化的代理协调，并支持带组地址的广播消息（`@all`、`@builders` 等）。\n- **工作树**：每个代理都拥有独立的 Git 工作树——避免代理之间的文件冲突。\n- **合并**：基于 SQLite 的 FIFO 合并队列，配备 4 层冲突解决机制。\n- **看门狗**：分层健康监测——第 0 层机械守护进程（tmux\u002FPID 活性）、第 1 层 AI 辅助故障分流、第 2 层监控代理用于持续舰队巡逻。\n- **工具强制执行**：针对不同运行时的防护机制（Claude Code 的钩子、Pi 的扩展），可自动阻止非实现类代理的文件修改操作，以及所有代理的危险 Git 操作。\n- **任务组**：批量协调，当所有成员的任务完成后自动关闭。\n- **会话生命周期**：检查点保存\u002F恢复以提高容错能力，交接编排用于崩溃恢复。\n- **令牌监控**：从运行时会话日志文件（JSONL）中提取会话指标。\n\n## 项目结构\n\n```\noverstory\u002F\n  src\u002F\n    index.ts                      CLI 入口点（Commander.js 程序）\n    types.ts                      共享类型和接口\n    config.ts                     配置加载 + 验证\n    errors.ts                     自定义错误类型\n    json.ts                       标准化 JSON 封装辅助函数\n    commands\u002F                     每个 CLI 子命令一个文件（37 个命令）\n      agents.ts                   代理发现与查询\n      coordinator.ts              持久化编排器生命周期\n      supervisor.ts               团队负责人管理 [已弃用]\n      dashboard.ts                实时 TUI 仪表板（通过 Chalk 使用 ANSI）\n      hooks.ts                    编排器钩子管理\n      sling.ts                    代理启动\n      group.ts                    任务组批量跟踪\n      nudge.ts                    代理提醒\n      mail.ts                     代理间消息传递\n      monitor.ts                  第二层监控管理\n      merge.ts                    分支合并\n      status.ts                   舰队状态概览\n      prime.ts                    上下文预热\n      init.ts                     项目初始化\n      worktree.ts                 工作树管理\n      watch.ts                    看门狗守护进程\n      log.ts                      钩子事件日志记录\n      logs.ts                     NDJSON 日志查询\n      feed.ts                     统一实时事件流\n      run.ts                      编排运行生命周期\n      trace.ts                    查看代理\u002F任务时间线\n      clean.ts                    清理工作树\u002F会话\n      doctor.ts                   健康检查执行者（12 个检查模块）\n      inspect.ts                  深度代理检查\n      spec.ts                     任务规范管理\n      errors.ts                   聚合错误视图\n      replay.ts                   交错事件回放\n      stop.ts                     终止代理\n      costs.ts                    Token\u002F成本分析\n      metrics.ts                  会话指标\n      ecosystem.ts                os-eco 工具仪表板\n      update.ts                   刷新管理文件\n      upgrade.ts                  npm 版本升级\n      discover.ts                 通过协调器驱动的侦察蜂群发现旧代码库\n      orchestrator.ts             多仓库协调（PersistentAgentSpec）\n      completions.ts              Shell 补全生成（bash\u002Fzsh\u002Ffish）\n    canopy\u002F\n      client.ts                   Canopy 客户端（提示渲染、列表显示、事件发射）\n    agents\u002F                       代理生命周期管理\n      manifest.ts                 代理注册表（加载 + 查询）\n      overlay.ts                  动态 CLAUDE.md 叠加层生成器\n      identity.ts                 代理持久化身份（简历）\n      checkpoint.ts               会话检查点保存\u002F恢复\n      lifecycle.ts                交接编排\n      hooks-deployer.ts           部署钩子 + 工具强制执行\n      copilot-hooks-deployer.ts   将钩子配置部署到 Copilot 工作树\n      guard-rules.ts              共享守卫常量（工具列表、bash 模式）\n    worktree\u002F                     Git 工作树 + tmux 管理\n    mail\u002F                         SQLite 邮件系统（类型化协议、广播）\n    merge\u002F                        FIFO 队列 + 冲突解决\n    watchdog\u002F                     分层健康监测（守护进程、分诊、健康）\n    logging\u002F                      多格式日志记录器 + 净化器 + 报告器 + 颜色控制 + 共享主题\u002F格式\n    metrics\u002F                      SQLite 指标 + 定价 + 转录解析\n    doctor\u002F                       健康检查模块（12 个检查）\n    utils\u002F                        共享工具（二进制、文件系统、PID、时间、版本）\n    insights\u002F                     会话洞察分析器，用于自动专家化\n    runtimes\u002F                     代理运行时抽象（注册表 + 适配器：Claude、Pi、Copilot、Codex、Gemini、Sapling、OpenCode、Cursor、Aider、Goose、Amp）\n    tracker\u002F                      可插拔任务跟踪器（珠子 + 种子后端）\n    mulch\u002F                        mulch 客户端（程序化 API + CLI 包装）\n    e2e\u002F                          端到端生命周期测试\n  agents\u002F                         基础代理定义（.md，9 种角色）+ 技能定义\n  templates\u002F                      叠加层和钩子的模板\n```\n\n## 配置\n\n### 网关提供商\n\n将代理 API 调用路由到自定义网关端点（z.ai、OpenRouter、自托管代理）。在 `.overstory\u002Fconfig.yaml` 中配置提供商：\n\n```yaml\nproviders:\n  anthropic:\n    type: native\n  zai:\n    type: gateway\n    baseUrl: https:\u002F\u002Fapi.z.ai\u002Fv1\n    authTokenEnv: ZAI_API_KEY\n  openrouter:\n    type: gateway\n    baseUrl: https:\u002F\u002Fopenrouter.ai\u002Fapi\u002Fv1\n    authTokenEnv: OPENROUTER_API_KEY\nmodels:\n  builder: zai\u002Fclaude-sonnet-4-6\n  scout: openrouter\u002Fopenai\u002Fgpt-4o\n```\n\n**工作原理：** 模型引用使用 `provider\u002Fmodel-id` 格式。Overstory 将 `ANTHROPIC_BASE_URL` 设置为网关的 `baseUrl`，`ANTHROPIC_AUTH_TOKEN` 从 `authTokenEnv` 中指定的环境变量中获取，并将 `ANTHROPIC_API_KEY=\"\"` 以防止直接调用 Anthropic API。代理接收到 `\"sonnet\"` 作为模型别名，而 Claude Code 的路由则通过环境变量进行。\n\n**环境变量说明：**\n- `ANTHROPIC_AUTH_TOKEN` 和 `ANTHROPIC_API_KEY` 在每个代理中是互斥的。\n- 网关代理会获得 `ANTHROPIC_API_KEY=\"\"` 和来自提供商配置的 `ANTHROPIC_AUTH_TOKEN`。\n- 直接调用 Anthropic API（如合并解析器、看门狗分诊）仍需要在编排器环境中设置 `ANTHROPIC_API_KEY`。\n\n**验证：** 运行 `ov doctor --category providers` 可检查可达性、认证令牌、模型-提供商引用以及工具使用兼容性。\n\n**`ProviderConfig` 字段：**\n\n| 字段 | 类型 | 必需 | 描述 |\n|-------|------|----------|-------------|\n| `type` | `native` 或 `gateway` | 是 | 提供商类型 |\n| `baseUrl` | 字符串 | 仅网关 | API 端点 URL |\n| `authTokenEnv` | 字符串 | 仅网关 | 存储认证令牌的环境变量名称 |\n\n## 故障排除\n\n### 协调器在启动过程中退出\n\n此错误表示协调器 tmux 会话在 TUI 准备就绪之前就已退出。最常见的原因是 shell 初始化过慢。\n\n**步骤 1：测量 shell 启动时间**\n\n```bash\ntime zsh -i -c exit   # 对于 zsh\ntime bash -i -c exit  # 对于 bash\n```\n\n如果启动时间超过 1 秒，很可能是 shell 初始化过慢导致的。\n\n**步骤 2：常见的启动缓慢原因**\n\n| 原因 | 典型延迟 | 解决方法 |\n|-------|---------------|-----|\n| oh-my-zsh 搭配大量插件 | 1–5秒 | 减少插件数量，改用更轻量级的框架（如 zinit 并启用懒加载） |\n| nvm（Node 版本管理器） | 1–3秒 | 使用 `--no-use` 并懒加载 nvm，或切换到 fnm\u002Fvolta |\n| pyenv init | 0.5–2秒 | 懒加载 pyenv |\n| rbenv init | 0.5–1秒 | 懒加载 rbenv |\n| starship 提示符 | 0.5–1秒 | 检查 starship 的耗时情况 |\n| conda 自动激活 | 1–3秒 | 在 `.condarc` 中设置 `auto_activate_base: false` |\n| Homebrew shellenv | 0.5–1秒 | 缓存输出结果，而非每次启动 shell 时都重新计算 |\n\n**步骤 3：配置 `.overstory\u002Fconfig.yaml` 中的 `shellInitDelayMs`：**\n\n```yaml\nruntime:\n  shellInitDelayMs: 3000\n```\n\n- 默认值：`0`（无延迟）\n- 常用值：根据 shell 启动时间，通常为 `1000`–`5000`\n- 如果设置超过 `30000`（30秒），将触发警告\n- 该设置会在 tmux 会话创建与 TUI 准备就绪轮询之间插入一段延迟\n\n**步骤 4：优化示例**\n\n懒加载 nvm（添加到 `~\u002F.zshrc` 或 `~\u002F.bashrc`）：\n\n```bash\n# 懒加载 nvm — 只有首次调用 nvm\u002Fnode\u002Fnpm 时才会激活\nexport NVM_DIR=\"$HOME\u002F.nvm\"\nnvm() { unset -f nvm node npm npx; [ -s \"$NVM_DIR\u002Fnvm.sh\" ] && . \"$NVM_DIR\u002Fnvm.sh\"; nvm \"$@\"; }\nnode() { unset -f nvm node npm npx; [ -s \"$NVM_DIR\u002Fnvm.sh\" ] && . \"$NVM_DIR\u002Fnvm.sh\"; node \"$@\"; }\nnpm()  { unset -f nvm node npm npx; [ -s \"$NVM_DIR\u002Fnvm.sh\" ] && . \"$NVM_DIR\u002Fnvm.sh\"; npm  \"$@\"; }\nnpx()  { unset -f nvm node npm npx; [ -s \"$NVM_DIR\u002Fnvm.sh\" ] && . \"$NVM_DIR\u002Fnvm.sh\"; npx  \"$@\"; }\n```\n\n减少 oh-my-zsh 插件（编辑 `~\u002F.zshrc`）：\n\n```bash\n# 修改前：plugins=(git zsh-autosuggestions zsh-syntax-highlighting node npm python ruby rbenv pyenv ...)\n# 修改后：仅保留经常使用的插件\nplugins=(git)\n```\n\n## os-eco 的一部分\n\nOverstory 是 [os-eco](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Fos-eco) AI 代理工具生态系统的一部分。\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fjayminwest_overstory_readme_00510ee15b83.png\" alt=\"os-eco\" width=\"444\" \u002F>\n\u003C\u002Fp>\n\n## 贡献说明\n\n欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取相关指南。\n\n## 许可证\n\nMIT","# Overstory 快速上手指南\n\nOverstory 是一个用于 AI 编码代理的多智能体编排工具。它通过 `tmux` 在 Git worktree 中生成工作代理，利用自定义 SQLite 邮件系统进行协调，并将结果合并回主分支。\n\n## 环境准备\n\n在开始之前，请确保您的系统满足以下要求：\n\n*   **操作系统**：支持 Linux 或 macOS（依赖 `tmux` 和 `git`）。\n*   **核心依赖**：\n    *   [Bun](https:\u002F\u002Fbun.sh) v1.0+ (运行时环境)\n    *   `git` (版本控制)\n    *   `tmux` (终端复用，用于隔离代理会话)\n*   **AI 代理运行时**：必须至少安装并配置好以下任一支持的 AI CLI 工具：\n    *   Claude Code (`claude`)\n    *   GitHub Copilot (`copilot`)\n    *   Cursor (`agent`)\n    *   Aider (`aider`)\n    *   Gemini CLI (`gemini`)\n    *   或其他支持的工具 (Pi, Codex, Sapling, OpenCode, Goose, Amp)\n\n> **注意**：多智能体协作会带来成本增加、错误累积和合并冲突等风险。在生产环境使用前，请务必评估相关风险。\n\n## 安装步骤\n\n推荐使用 Bun 进行全局安装：\n\n```bash\nbun install -g @os-eco\u002Foverstory-cli\n```\n\n如果您不想全局安装，也可以直接使用 `npx` 运行：\n\n```bash\nnpx @os-eco\u002Foverstory-cli --help\n```\n\n### 开发模式安装（可选）\n\n如果您需要贡献代码或测试最新功能：\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Foverstory.git\ncd overstory\nbun install\nbun link              # 使 'ov' 命令全局可用\n```\n\n## 基本使用\n\n以下是启动 Overstory 并运行第一个多智能体任务的最简流程：\n\n### 1. 初始化项目\n进入您的代码项目目录并初始化 Overstory：\n\n```bash\ncd your-project\nov init\n```\n\n### 2. 安装钩子（推荐）\n将编排钩子安装到 `.claude\u002Fsettings.local.json` 中，以便更好地集成：\n\n```bash\nov hooks install\n```\n\n### 3. 启动协调器\n启动一个持久的协调器代理（Coordinator），它负责任务分解和调度：\n\n```bash\nov coordinator start\n```\n*提示：添加 `--attach` 参数可前台运行并查看实时日志。*\n\n### 4. 分发任务给工作代理\n使用 `sling` 命令生成具体的工作代理（如构建者、审查者等）来执行任务：\n\n```bash\n# 示例：创建一个名为 my-builder 的代理来处理特定任务\nov sling \u003Ctask-id> --capability builder --name my-builder\n```\n*注：`\u003Ctask-id>` 可以是具体的任务描述或 ID。*\n\n### 5. 监控与合并\n*   **查看状态**：实时监控所有代理的状态和工作树。\n    ```bash\n    ov status\n    # 或使用交互式仪表盘\n    ov dashboard\n    ```\n*   **合并代码**：当代理完成任务后，将它们的分支合并回主分支（包含冲突解决机制）。\n    ```bash\n    ov merge\n    ```\n\n### 常用辅助命令\n*   **检查消息**：查看代理间的通信邮件。\n    ```bash\n    ov mail check --inject\n    ```\n*   **提醒卡住的代理**：如果某个代理停滞不前，发送提醒。\n    ```bash\n    ov nudge \u003Cagent-name>\n    ```\n*   **清理环境**：清理已完成的工作树和会话。\n    ```bash\n    ov clean\n    ```","某中型电商团队需要在三天内将单体架构拆分为微服务，涉及订单、支付和库存三个模块的重构与并行开发。\n\n### 没有 overstory 时\n- **串行开发效率低**：资深工程师只能逐个处理模块，无法同时推进多个任务，导致整体交付周期被迫拉长。\n- **上下文切换成本高**：开发者在不同分支和代码库间频繁切换，容易混淆逻辑，且难以维持对每个模块的深度专注。\n- **合并冲突频发**：多人手动修改同一核心文件时缺乏协调，后期合并代码时产生大量复杂冲突，解决耗时甚至超过开发时间。\n- **调试与监控困难**：缺乏统一视图来追踪各子任务的进度，一旦某个环节卡住，管理者难以快速定位并干预。\n\n### 使用 overstory 后\n- **多智能体并行协作**：通过 `ov sling` 命令瞬间启动分别负责订单、支付和库存的三个 AI 代理（如 Claude Code 和 Aider），在独立的 git worktree 中同步编码。\n- **自动化冲突消解**：overstory 内置的分层冲突解决机制自动协调各代理的修改，将原本棘手的合并问题在后台平滑处理，大幅减少人工介入。\n- **统一调度与监控**：利用 `ov dashboard` 实时查看整个“代理舰队”的状态，通过 `ov nudge` 轻松唤醒停滞的任务，确保流水线顺畅运行。\n- **灵活运行时切换**：针对不同模块特性，为计算密集型任务配置高性能模型，为逻辑密集型任务配置高精度模型，实现成本与效果的最优平衡。\n\noverstory 将单兵作战的编码模式升级为高度协同的自动化工程团队，显著提升了复杂重构任务的交付速度与质量。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fjayminwest_overstory_848d3ac1.png","jayminwest","Jaymin West","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fjayminwest_2d6d7ece.jpg","I help companies accelerate their AI adoption through technical consulting and hands-on engineering.","jayminwest.com","Seattle, WA",null,"https:\u002F\u002Fgithub.com\u002Fjayminwest",[84,88],{"name":85,"color":86,"percentage":87},"TypeScript","#3178c6",99.7,{"name":89,"color":90,"percentage":91},"Go Template","#00ADD8",0.3,1187,204,"2026-04-05T18:20:33","MIT",4,"Linux, macOS","未说明",{"notes":100,"python":101,"dependencies":102},"该工具不依赖 Python 或 GPU，而是基于 Bun (JavaScript\u002FTypeScript 运行时)。必须安装 git 和 tmux 以支持多代理在隔离的 git worktree 中运行。用户需预先安装并配置至少一种支持的 AI 编码代理 CLI 工具（如 Claude Code、Aider 等）才能正常工作。","不需要 (基于 Bun 运行时)",[103,104,105,106,107],"Bun v1.0+","git","tmux","@os-eco\u002Foverstory-cli","至少一种支持的 AI Agent CLI (如 Claude Code, Aider, Gemini CLI 等)",[15],[110,111,112,105],"agent-swarms","ai-agents","claude-code","2026-03-27T02:49:30.150509","2026-04-06T08:52:39.344110",[116,121,126,131,135,139,143,147],{"id":117,"question_zh":118,"answer_zh":119,"source_url":120},18343,"Overstory 是否支持不同的工作流模式，例如快速执行和开放式协作？","是的，从 v0.9.3 版本开始，Overstory 原生支持两种工作流配置文件：\n1. **delivery（交付模式）**：适用于解决方案已知或明确指定的任务（如 Bug 修复、特定功能）。此模式下系统优化自主执行、严格的质量门禁和测试，仅在遇到歧义或风险时升级人工干预。\n2. **co-creation（共创模式）**：适用于大型、开放式的任务（如从零构建产品、架构设计）。此模式下系统优化探索、生成带权衡的选项，并在关键里程碑设置人工决策点。\n\n使用方法：通过新入口点 `ov workflow start \u003Cworkflow>` 启动，分别使用 `delivery` 或 `co-creation` 别名。共创模式的任务规范位于 `openspec\u002Fchanges\u002F\u003Ctask-id>\u002Ftasks.md`。","https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Foverstory\u002Fissues\u002F106",{"id":122,"question_zh":123,"answer_zh":124,"source_url":125},18344,"如何在多仓库（Monorepo）结构中使用 Overstory，使得主目录的 Dashboard 能显示子目录中生成的 Agent？","默认情况下，每个子目录仓库都有独立的 `.overstory\u002F` 状态和数据库，导致根目录的协调器无法看到子仓库中生成的 Agent。\n\n解决方案是引入一个由协调器管理的项目注册表（Project Registry）：\n1. 保持每个仓库的 `.overstory` 状态对其自身具有权威性。\n2. 在工作区根目录添加一个显式的项目注册表。\n3. 运行根目录的 `ov status` 或 `ov dashboard` 时，系统将聚合这些已注册项目的状态，而不是仅假设单个本地仓库根目录。\n\n这解决了跨仓库的可见性和发现性问题，无需重写邮件传输层。相关实现思路参考 PR #1 (RogerNavelsaker fork)。","https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Foverstory\u002Fissues\u002F102",{"id":127,"question_zh":128,"answer_zh":129,"source_url":130},18345,"在使用 Fish Shell 时遇到报错，提示生成了 bash 专用的 export 语法，如何解决？","这是一个已知问题（Issue #86），根源在于 `tmux.ts` 模块生成的环境变量导出语句仅兼容 Bash 语法（`export VAR=value`），而 Fish Shell 使用不同的语法（`set -x VAR value`）。\n\n该问题已被标记为严重（critical）Bug 并分解为独立跟踪项。建议暂时在 Bash 环境中运行 Overstory，或者等待后续版本修复以自动检测 Shell 类型并生成对应语法。","https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Foverstory\u002Fissues\u002F84",{"id":132,"question_zh":133,"answer_zh":134,"source_url":130},18346,"`ov sling` 命令在生成失败时留下了孤儿工作树（orphaned worktrees）或分支，该如何清理？","这是 Issue #88 中报告的一个高优先级问题。当 `ov sling` 生成 Agent 失败时，可能会遗留未清理的 Git 工作树和分支。\n\n目前的临时解决方法是手动检查并清理：\n1. 使用 `git worktree list` 查看残留的工作树。\n2. 使用 `git worktree remove \u003Cpath>` 手动删除孤儿工作树。\n3. 检查并删除相关的孤立分支。\n\n维护者已将其列为需修复的 Bug，未来版本将增加自动清理机制。",{"id":136,"question_zh":137,"answer_zh":138,"source_url":130},18347,"运行 `ov init` 初始化生态系统后，为什么第一次合并会被阻塞？","这是因为 `ov init` 生成的引导文件（bootstrap files）处于未提交（uncommitted）状态，导致合并流程阻塞（Issue #91）。\n\n解决步骤：\n1. 运行 `ov init` 后，检查生成的文件。\n2. 手动执行 `git add .` 和 `git commit -m \"chore: init overstory ecosystem\"` 提交这些文件。\n3. 然后再继续后续的合并或工作流操作。\n\n这是一个中等优先级的改进点，未来可能会在初始化命令中自动处理提交步骤。",{"id":140,"question_zh":141,"answer_zh":142,"source_url":130},18348,"如何区分 `ov doctor` 报告中的“尚未创建”和“缺失\u002F损坏”状态？","目前 `ov doctor` 可能无法清晰区分这两种状态（Issue #94）。\n\n建议的排查方法：\n1. 检查 `.overstory\u002F` 目录是否存在。如果不存在，属于“尚未创建”。\n2. 如果目录存在但命令报错，检查其中的数据库文件（如 `mail.db`）是否完整，这通常属于“缺失\u002F损坏”。\n\n维护者计划改进 `ov doctor` 命令，使其输出更明确的诊断信息，分别指示是需要初始化还是需要进行修复。",{"id":144,"question_zh":145,"answer_zh":146,"source_url":130},18349,"在多 Agent 并行工作时，如何处理合并冲突以避免内容静默丢失？","在 Issue #89 和 #84 的测试中发现，自动解析合并层级（auto-resolve merge tier）有时会静默丢弃先前合并的内容（特别是当多个 Agent 修改同一文件的同一区域时）。\n\n最佳实践建议：\n1. 对于关键文件，避免让多个 Builder Agent 同时修改同一区域。\n2. 在合并后务必进行人工审查（Review），不要完全依赖自动解析。\n3. 关注后续版本对合并策略的优化，目前该问题已被标记为严重（critical）Bug 进行跟踪。",{"id":148,"question_zh":149,"answer_zh":150,"source_url":130},18350,"如何优化多 Agent 并发执行时的稳定性和资源占用？","根据用户体验报告（Issue #95），默认的并发数（`maxConcurrent`）可能过高，而 Shell 初始化延迟（`shellInitDelayMs`）可能过低，导致竞争或不稳定。\n\n建议调整配置：\n1. **降低** `maxConcurrent` 的默认值，减少同时运行的 Agent 数量。\n2. **提高** `shellInitDelayMs` 的值，给 Shell 初始化留出更多时间，避免竞态条件。\n\n具体数值需根据机器性能调整，但在资源受限环境下，保守的配置能显著提高成功率。",[152,157,162,167,172,177,182,187,192,197,202,207,212,217,222,227,232,237,242,247],{"id":153,"version":154,"summary_zh":155,"released_at":156},108914,"v0.9.3","### 新增\n\n#### Tmux 套接字隔离\n- **`tmux -L overstory` 套接字** — 所有代理会话现在运行在专用的 tmux 服务器套接字上，与用户的个人 tmux 配置（主题、插件、快捷键绑定）相互隔离。这可以防止因 tmux 配置不兼容而导致的进程启动失败。详情请参阅 GitHub #93。\n- **`TMUX_SOCKET` 常量和 `tmuxCmd()` 辅助函数**，位于 `src\u002Fworktree\u002Ftmux.ts` 中 — 所有 tmux 操作（创建、列出、终止、捕获输出、发送按键）都通过共享的套接字构建器进行路由。\n\n#### Copilot 运行时增强\n- **模型别名扩展** — Copilot 运行时现在通过 `MODEL_MAP` 将简短别名（`sonnet`、`opus`、`haiku`）映射为完整限定的模型名称（`claude-sonnet-4-6` 等）；未知名称则原样传递 (#77)。\n- **钩子支持** — 新增了 `src\u002Fagents\u002Fcopilot-hooks-deployer.ts` 和 `templates\u002Fcopilot-hooks.json.tmpl`，用于将 `.github\u002Fhooks.json` 部署到 Copilot 工作树中，以实现事件日志记录。\n- **文件夹信任自动配置** — `ensureCopilotTrustedFolders()` 会预先将工作树路径注册到 `~\u002F.config\u002Fgithub-copilot\u002Fconfig.json` 中，从而抑制信任提示。\n- **`ov init` 中的自动检测** — 运行时检测现在会检查是否安装了 `copilot` CLI，如果未安装 Claude Code，则将其设置为默认值。\n\n#### 初始化运行时自动检测\n- **`detectDefaultRuntime()`**，位于 `src\u002Fcommands\u002Finit.ts` 中 — `ov init` 现在会探测已安装的编码代理 CLI（claude、copilot、gemini、opencode、sapling、pi），并将第一个匹配项设置为配置中的 `runtime.default`。\n\n### 修复\n\n- **使用 beads 后端时仪表板显示“无跟踪数据”问题** — `bd list --json` 现在能够同时处理扁平数组和树形格式（`{ mol: [...] }`）的输出，并回退至 `bd ready --json`。\n- **Codex 提供者前缀剥离** — `CodexRuntime` 现在会在将模型名称传递给 `codex` CLI 之前，先剥离 `provider\u002F` 前缀。\n- **Pi 就绪状态正则表达式** — 更新了模式，以匹配 M 标度上下文窗口（例如 `1M`）。\n- **协调器完成协议顺序** — 现在堆肥记录操作会在工作树清理之前执行，从而避免在工作树被提前移除时丢失相关知识。\n\n### 变更\n\n- 所有 tmux 操作均使用专用的 `overstory` 套接字，而非默认服务器套接字。\n- Copilot 运行时指令路径：`.github\u002Fcopilot-instructions.md`。\n\n### 测试\n\n- 共计 113 个文件中有 3689 个测试用例（包含 8627 次 `expect()` 调用）。\n- 新增测试文件：`src\u002Fagents\u002Fcopilot-hooks-deployer.test.ts`（162 行）。\n- 扩展了：`src\u002Fruntimes\u002Fcopilot.test.ts`（新增 220 行 — 包括模型别名、文件夹信任、钩子及自动检测功能）。\n- 扩展了：`src\u002Fworktree\u002Ftmux.test.ts`（新增 140 行 — 包括套接字隔离和 `tmuxCmd()` 构建器功能）。\n- 扩展了：`src\u002Fruntimes\u002Fcodex.test.ts`（新增 35 行 — 包括提供者前缀剥离功能）。\n- 扩展了：`src\u002Fruntimes\u002Fpi.test.ts`（新增 24 行 — 包括 M 标度上下文正则表达式功能）。\n- 扩展了：`src\u002Ftracker\u002Ffactory.test.ts`（新增 10 行）。","2026-03-23T20:51:26",{"id":158,"version":159,"summary_zh":160,"released_at":161},108915,"v0.9.2","### 新增\n\n#### Aider、Goose 和 Amp 运行时适配器\n- **`src\u002Fruntimes\u002Faider.ts`** — 为 Paul Gauthier 的 AI 配对编程工具 [Aider](https:\u002F\u002Faider.chat)（`aider` CLI）新增的实验性运行时适配器 — 带有 `--yes-always` 选项的交互式 REPL，会将覆盖写入 `CONVENTIONS.md`，无钩子系统 — 感谢 **@arosstale** (#80)\n- **`src\u002Fruntimes\u002Fgoose.ts`** — 为 Block 公司的 AI 开发者代理 [Goose](https:\u002F\u002Fgithub.com\u002Fblock\u002Fgoose)（`goose` CLI）新增的实验性运行时适配器 — 带基于配置文件权限的交互式 REPL，会将覆盖写入 `.goosehints` — 感谢 **@arosstale** (#80)\n- **`src\u002Fruntimes\u002Famp.ts`** — 为 Sourcegraph 的 AI 编码代理 [Amp](https:\u002F\u002Famp.dev)（`amp` CLI）新增的实验性运行时适配器 — 内置审批系统的交互式聊天，会将覆盖写入 `.amp\u002FAGENT.md` — 感谢 **@arosstale** (#80)\n- 运行时数量：8 → 11 个适配器\n\n#### 协调器命令界面\n- **`ov orchestrator`** — 新增用于生态系统级别多仓库编排的顶层命令；通过可复用的 `PersistentAgentSpec` 抽象，与 `ov coordinator` 共享相同的 start\u002Fstop\u002Fstatus\u002Fsend\u002Fask\u002Foutput 子命令 (#126)\n- **`src\u002Fcommands\u002Forchestrator.ts`** — 定义了 `ORCHESTRATOR_SPEC`，并通过共享的持久化代理机制进行路由\n- **重构 `coordinator.ts`** — 提取了 `PersistentAgentSpec` 接口以及 `startPersistentAgent()` \u002F `stopPersistentAgent()` \u002F `statusPersistentAgent()` 辅助函数，以实现协调器和编排器之间的代码复用\n\n#### 低预算代理的角色压缩\n- **`agents\u002Flead.md` 中的预算压缩规则** — 当 `MAX_AGENTS` 受限时，领头人现在会压缩角色：`=1` 表示同时充当领头人和工作者，`=2` 表示每次只带一名助手，随后自行完成任务 (#127)\n- **更新 `agents\u002Fcoordinator.md`** — 协调员现在可以直接在低预算或工作范围较窄的情况下生成侦察员和构建者，而不再总是通过领头人来完成\n- **增强 `src\u002Fagents\u002Foverlay.ts`** — `formatDispatchOverrides()` 现在会为 `MAX_AGENTS = 1` 和 `MAX_AGENTS = 2` 生成考虑压缩情况的消息内容\n\n#### 监控守护程序增强\n- **`src\u002Fwatchdog\u002Ftriage.ts` 中的 `TriageResult` 类型** — 用结构化的 `{ verdict, fallback, reason }` 替代简单的字符串，以提升故障排查的可观测性\n- **新的监控守护程序配置选项** — `rpcTimeoutMs`（默认 5000）、`triageTimeoutMs`（默认 30000）、`maxEscalationLevel`（默认 3），并增加了验证范围\n- **`ov doctor --category watchdog`** — 新增医生检查类别，用于验证 PID 文件完整性、进程存活状态及层级可用性\n\n#### 工具模块\n- **`src\u002Futils\u002Fbin.ts`** — `resolveOverstoryBin()` 用于重新启动场景\n- **`src\u002Futils\u002Ffs.ts`** — SQLite 清空、JSON 重置、目录清理、文件删除等辅助函数\n- **`src\u002Futils\u002Fpid.ts`** — PID 文件的读取、写入和删除\n- **`src\u002Futils\u002Ftime.ts`** — 解析相对时间格式（`1h`、`30m`、`2d`、`10s`）\n- **`src\u002Futils\u002Fversion.ts`** — 版本检测（当前版本、npm 注册表版本、CLI 工具版本）\n\n#### Pi 运行时\n- **AGENTS.md 覆盖支持** — Pi 运行时","2026-03-23T19:31:04",{"id":163,"version":164,"summary_zh":165,"released_at":166},108916,"v0.9.1","### 变更\n\n#### Discover 命令重写\n- **`ov discover` 现由协调器驱动** — 替换了直接生成侦察员的方式，改为使用协调器会话，该会话可按类别自主生成引导员和侦察员、汇总结果并写入 mulch 记录。\n- 从 `coordinator.ts` 中提取了 `startCoordinatorSession()` — 作为可复用的核心，供需要自定义名称或信标的协调器式会话的命令使用（`ov discover` 已采用）。\n- **新增标志位：** `ov discover` 命令增加了 `--attach` \u002F `--no-attach` 和 `--watchdog`；默认代理名称由 `discover` 更改为 `discover-coordinator`。\n- 为提高可测试性，将 `buildDiscoveryBeacon()` 和 `buildScoutArgs()` 辅助函数从 `discover.ts` 中导出。\n\n### 修复\n\n- **`ov discover` 中的任务锁冲突问题** — 每个侦察员现在拥有唯一的任务 ID（`taskId-categoryName`），不再共享同一任务 ID，从而避免了 `checkTaskLock()` 阻塞第 2 至第 6 个侦察员的情况。\n- **`ov discover` 中的 `maxAgentsPerLead` 拒绝问题** — 现在通过 `--max-agents` 参数传递侦察员数量，以避免在所有 6 个类别均启用时超过默认上限 5 个。\n\n### 测试\n\n- 共计 102 个文件中的 3398 项测试（包含 8038 次 `expect()` 调用）。\n- 新增了 6 个针对 `buildScoutArgs()` 的单元测试，覆盖所有验收条件。","2026-03-13T18:45:01",{"id":168,"version":169,"summary_zh":170,"released_at":171},108917,"v0.8.7","### 新增\n\n#### Cursor CLI 运行时适配器\n- **`src\u002Fruntimes\u002Fcursor.ts`** — 为 [Cursor CLI](https:\u002F\u002Fcursor.com\u002Fdocs\u002Fcli\u002Foverview)（`agent` 二进制文件）新增的运行时适配器，实现了 `AgentRuntime` 接口，支持通过 tmux 启动 TUI、从 `.cursor\u002Frules\u002Foverstory.md` 分发指令、`--yolo` 权限绕过以及无头一次性模式 — 感谢 **@XavierChevalier** (#104, #66)\n- **`src\u002Fruntimes\u002Fcursor.test.ts`** — 全面的测试套件（497 行），覆盖了启动命令构建、叠加层生成、就绪状态检测和会话记录解析等功能\n\n#### 运行时稳定性分类\n- **`AgentRuntime` 上的 `stability` 字段** — 在运行时接口中新增了 `\"stable\" | \"beta\" | \"experimental\"` 字段；Claude 和 Sapling 标记为 `stable`，Pi 和 Codex 标记为 `beta`，Copilot\u002FGemini\u002FOpenCode\u002FCursor 标记为 `experimental`\n- 稳定性信息已体现在 `ov agents` 命令和运行时文档中\n\n#### 按协调器隔离运行\n- **按协调器会话跟踪** — `SessionStore` 现在会为每个会话记录 `coordinator_name`，并对现有数据库进行自动迁移，从而在同一个项目中同时运行多个协调器时实现隔离化的运行跟踪\n- **`OVERSTORY_TASK_ID` 环境变量** — 现代理器会将任务 ID 作为环境变量传递给代理；追踪器的 `close` 命令已被保护，以防止代理关闭其分配范围之外的问题\n\n#### 仪表板运行时列\n- **仪表板代理面板中的运行时列** — 实时 TUI 仪表板现在会显示每个代理正在使用的运行时（例如 `claude`、`cursor`、`sapling`）——感谢 **@mustafamagdy** (#99)\n\n### 修复\n\n- **SQLite 锁竞争导致的仪表板崩溃** — 当并发代理导致 `SQLITE_BUSY` 错误时，`ov dashboard` 不再崩溃；数据库读取操作现已封装重试逻辑\n- **合并自动解决中的静默内容丢失问题** — 合并解决器第二层（块级）在解决冲突时不再静默丢弃非冲突内容，而是正确保留整个文件\n- **`ov init` 在调用 spawner 时出现 ENOENT 错误** — 现在对用于检测生态系统工具的 `spawner()` 调用进行了 try\u002Fcatch 包装，以防止在未安装 `mulch`、`sd` 或 `cn` CLI 时发生崩溃\n- **`detectReady` 中的 Shift+Tab 误判问题** — `hasStatusBar` 检查不再将 Shift+Tab 的转义序列误认为是状态栏标志，从而避免过早判定代理已就绪\n- **Claude 绕过对话框与 Codex 共享状态问题** — Claude 运行时的 `detectReady()` 现在能够识别“绕过”对话框阶段；Codex 运行时也正确处理了 `sharedWritableDirs` 启动选项——感谢 **@Ilanbux** (#101)\n- **WSL2 竞争条件下的 tmux 窗格重试机制** — `capturePaneContent()` 和 `sendKeys()` 现在会在因 WSL2 时序问题导致的临时 tmux 失败时进行重试——感谢 **@arosstale** (#78)\n- **Fish shell 下的 tmux 启动问题** — 现在将 tmux 会话命令包裹在 `\u002Fbin\u002Fbash -c` 中，以避免用户默认 Shell 为 Fish 时出现启动失败\n- **`coordinator_name` 列的数据库迁移** — `createSessionStore()` 现在会自动迁移现有的 `sessions` 表","2026-03-10T14:57:46",{"id":173,"version":174,"summary_zh":175,"released_at":176},108918,"v0.8.6","### 新增\n\n#### 协调器完成协议\n- **`ov coordinator check-complete`** — 新的子命令，用于评估已配置的退出触发条件（`allAgentsDone`、`taskTrackerEmpty`、`onShutdownSignal`），并返回每个触发条件的状态；仅当所有启用的触发条件均满足时，`complete` 才为 `true`\n- **`coordinator.exitTriggers` 配置项** — 在 `config.yaml` 中新增 `coordinator` 部分，包含三个布尔类型的触发条件，用于控制协调器的自动关闭（默认均为 `false`）\n- 退出触发条件的评估已集成到协调器完成协议中——当配置的条件满足时，协调器现在可以自行终止\n- `allAgentsDone` 触发条件还会检查合并队列，以防止在分支仍待合并时过早关闭\n\n#### 派生回滚\n- **`rollbackWorktree()`** — 在 `src\u002Fworktree\u002Fmanager.ts` 中新增的帮助函数，用于移除工作树并删除其分支（尽力而为，错误将被吞下）\n- **派生失败时的 `ov sling` 回滚** — 如果在创建工作树后代理派生失败，工作树和分支将自动回滚，以避免出现孤立资源\n\n#### 每个代理的清理\n- **`ov clean --agent \u003Cname>`** — 针对单个代理的定向清理：终止 tmux 会话或进程树，移除工作树，删除分支，清空代理和日志目录，记录合成的会话结束事件，并将会话标记为已完成\n- **已完成代理上的 `ov stop --clean-worktree`** — 此前会对已完成的代理抛出错误；现在则跳过终止步骤，直接进行工作树和分支的清理\n\n#### 合并可靠性\n- **合并前自动提交 os-eco 状态文件** — 运行时状态文件（`.seeds\u002F`、`.overstory\u002F`、`.mulch\u002F`、`.canopy\u002F`、`.greenhouse\u002F`、`.claude\u002F`、`CLAUDE.md`）会以 `chore: sync os-eco runtime state` 提交，以防止因工作区脏而导致的合并错误\n- **合并过程中暂存\u002F弹出脏文件** — 在合并前暂存未提交的更改，并在合并后将其弹出，同时在失败时进行适当的清理\n- **`onMergeSuccess` 回调** — `createMergeResolver()` 现在接受一个可选的 `onMergeSuccess` 钩子，在每次条目成功合并后调用\n- **合并解析器中未跟踪文件的处理** 已得到改进，以防止跟踪文件与未跟踪文件之间的冲突\n\n#### 初始化脚手架提交\n- **`ov init` 结束时自动提交脚手架文件** — 生态系统目录（`.overstory\u002F`、`.seeds\u002F`、`.mulch\u002F`、`.canopy\u002F`、`.gitattributes`、`CLAUDE.md`）会被提交，以避免代理分支在合并时引发未跟踪文件与跟踪文件之间的冲突\n\n### 修复\n\n- **无头代理终止的影响范围** — 使用 tmux 前缀匹配的 `killSession(\"\")` 可能会终止所有 tmux 会话；现在看门狗使用 `killAgent()` 辅助函数，通过基于 PID 的 `killProcessTree()` 处理无头代理，而通过命名的 tmux 会话处理 TUI 代理\n- **无头代理的 stale 检测** — 看门狗现在会对无头代理执行 `isProcessAlive(pid)` 检查，而不再仅检查 tmux 会话是否存活\n- **协调器状态文件提交** — 完成协议现在会提交 os-eco 状态文件","2026-03-06T14:59:24",{"id":178,"version":179,"summary_zh":180,"released_at":181},108919,"v0.8.5","### 新增\n\n#### OpenCode 运行时适配器\n- **`src\u002Fruntimes\u002Fopencode.ts`** — 为 [SST OpenCode](https:\u002F\u002Fopencode.ai) (`opencode` CLI) 新增的运行时适配器，实现了带有模型标志支持的 `AgentRuntime` 接口、`AGENTS.md` 指令文件以及无头子进程的启动功能。\n- **`src\u002Fruntimes\u002Fopencode.test.ts`** — 测试套件（325 行），覆盖了启动命令构建、覆盖层生成、防护规则及环境设置等场景。\n\n#### 无头代理的 NDJSON 事件尾部监听器\n- **`src\u002Fevents\u002Ftailer.ts`** — 后台 NDJSON 事件尾部监听器，轮询来自无头代理（如 Sapling、OpenCode）的 `stdout.log` 文件，解析新行并将其通过 EventStore 写入 `events.db`，从而支持 `ov status`、`ov dashboard` 和 `ov feed` 实时展示无头代理的执行进度。\n- **`src\u002Fevents\u002Ftailer.test.ts`** — 测试套件（461 行），覆盖了行解析、文件尾部监听、停止与清理操作以及各种边界情况。\n- **Watchdog 集成** — `runDaemonTick()` 现在会自动启动或停止活跃无头代理的事件尾部监听器，模块级别的监听器注册表可在每次 tick 中持续存在。\n\n#### 无头代理检查\n- **`ov inspect` 的 `stdout.log` 备用机制** — 当使用 `--no-tmux` 或 tmux 捕获失败时，`inspect` 命令将回退到读取代理的 `stdout.log` NDJSON 文件，解析最近的事件以显示无头代理的工具调用和执行进度。\n\n### 修复\n\n- **Sapling `buildDirectSpawn()` 崩溃问题** — 现在的模型解析逻辑会先检查模型参数是否为 `undefined`，而不再无条件调用 `.toUpperCase()`；只有在明确指定了模型时才会追加 `--model` 标志。\n- **Sapling API 密钥泄露问题** — 现在会在子进程中显式清除 `ANTHROPIC_API_KEY` 环境变量，防止父进程会话中的密钥泄漏到 Sapling 子进程中；网关提供商则会根据需要重新设置该密钥。\n\n### 测试\n\n- 共计 98 个文件中包含 3201 个测试用例（7551 次 `expect()` 调用）。","2026-03-05T15:22:44",{"id":183,"version":184,"summary_zh":185,"released_at":186},108920,"v0.8.4","### 新增\n\n#### 按能力运行时路由\n- **`runtime.capabilities` 配置字段** — 将能力名称（如 `builder`、`scout`、`coordinator`）映射到运行时适配器名称，从而支持异构集群：不同角色的代理可以使用不同的运行时。\n- `getRuntime()` 现在接受 `capability` 参数；查找顺序为：显式 `--runtime` 标志 > `capabilities[cap]` > `default` > `\"claude\"`。\n- 新增 4 个测试，分别覆盖能力路由、回退机制、显式覆盖以及未定义的能力场景。\n\n#### 运行时无关的会话记录发现\n- 在 `AgentRuntime` 接口中新增 **`getTranscriptDir()` 方法** — 现在每个运行时适配器都独立负责会话记录目录的解析，不再将 Claude Code 的路径硬编码在 `costs` 命令中。\n- 所有 6 个运行时适配器均已实现 `getTranscriptDir()` 方法（Claude 返回项目特定路径；其他返回 `null`）。\n\n#### 动态指令路径发现\n- `agents.ts` 中的 `getKnownInstructionPaths()` 现在通过 `getAllRuntimes()` 查询所有已注册的运行时，而非维护硬编码列表，因此新运行时能够自动被发现。\n\n### 修复\n\n- **工作树脏状态合并保护** — `ov merge` 现在会在尝试合并之前检测跟踪文件是否存在未提交的更改，并抛出明确的错误信息，从而避免因误导性的空冲突列表而导致的四层级连锁失败。\n- 在 `resolver.test.ts` 中新增 5 个测试，用于覆盖脏工作树检测逻辑。\n\n### 变更\n\n- 将 Claude Code 相关的具体实现从成本计算、会话记录和代理发现模块中解耦 — 移除了 `transcript.ts` 中对 `estimateCost` 的重新导出（改由直接从 `pricing.ts` 导入），并将会话记录目录的解析逻辑从 `costs` 命令中移至运行时适配器，同时指令路径列表也改为从运行时注册表中获取。\n\n### 测试\n\n- 共计 96 个文件中的 3137 个测试用例（包含 7420 次 `expect()` 断言）。","2026-03-04T21:49:57",{"id":188,"version":189,"summary_zh":190,"released_at":191},108921,"v0.8.3","### 新增\n\n#### 自动生成的代理名称\n- **`ov sling` 不再强制要求 `--name`** — 如果省略，则会根据 `{capability}-{taskId}` 生成一个唯一名称，并在必要时添加 `-2`、`-3` 等后缀以避免与现有活跃会话冲突。\n- 从 `src\u002Fcommands\u002Fsling.ts` 中导出 `generateAgentName()` 辅助函数，包含防冲突逻辑。\n\n#### 直接生成侦察员和建造者\n- **协调器现在可以直接生成侦察员和建造者** — 此前仅允许生成领导者而无需 `--parent`；如今，对于不需要领导者作为中介的轻量级任务，也可以直接生成侦察员和建造者。\n\n#### 运行时感知的指令路径\n- **代理定义中的 `{{INSTRUCTION_PATH}}` 占位符** — 所有代理 `.md` 文件现在使用运行时解析的占位符，而非硬编码的 `.claude\u002FCLAUDE.md`，从而使 Codex (`AGENTS.md`)、Sapling (`SAPLING.md`) 及其他运行时能够在各自的原生指令路径上放置覆盖层。\n- 在 `OverlayConfig` 类型和 `generateOverlay()` 函数中新增了 `instructionPath` 字段。\n\n### 修复\n\n- **Codex 运行时启动** — `buildSpawnCommand()` 现在使用交互式 `codex`（而非 `codex exec`），以确保会话在 tmux 中保持存活；同时，对于 Codex CLI 不支持的 Anthropic 别名，会省略 `--model` 参数（感谢 @vidhatanand）。\n- **僵尸代理清理** — `ov stop` 现在会清理僵尸代理（将其标记为已完成），而不是报错提示“已为僵尸”。\n- **无头模式下的 stdout 重定向** — `ov sling` 始终将无头代理的 stdout 重定向到文件，以防止因背压导致的僵尸进程。\n- **配置警告去重** — 在 `validateConfig` 中，非 Anthropic 模型的警告现在每个进程只发出一次，而不是每次调用 `loadConfig()` 时都发出。\n- **Codex 裸模型引用** — `validateConfig` 现在接受裸模型引用（如 `gpt-5.3-codex`），当默认运行时为 `codex` 时，不再要求必须使用带有提供商前缀的格式。\n\n### 变更\n\n- 更新代理定义 `.md` 文件，使用 `{{INSTRUCTION_PATH}}` 占位符（建造者、领导者、合并者、评审员、侦察员、主管、编排者）。\n\n### 测试\n\n- 共计 96 个文件中有 3130 个测试用例（7406 次 `expect()` 调用）。","2026-03-04T19:59:21",{"id":193,"version":194,"summary_zh":195,"released_at":196},108922,"v0.8.2","### 新增\n\n#### RuntimeConnection 注册表\n- **`src\u002Fruntimes\u002Fconnections.ts`** — 用于管理活动 `RuntimeConnection` 实例的模块级注册表，按代理名称键值跟踪与无头代理进程（例如 Sapling）之间的 RPC 连接。\n- 提供 `getConnection()`、`setConnection()` 和 `removeConnection()` 方法以进行生命周期管理，并在移除时自动调用 `close()`。\n- 在 `src\u002Fruntimes\u002Fconnections.test.ts` 中新增 6 个测试用例。\n\n#### Sapling RPC 功能增强\n- **SaplingRuntime 的 RuntimeConnection** — 提供完整的 RPC 支持，实现与 Sapling 代理进程之间的直接标准输入\u002F输出通信。\n- 在 `buildEnv()` 和 `buildDirectSpawn()` 中实现了模型别名解析功能，能够正确展开 `sonnet`、`opus` 和 `haiku` 等别名。\n\n### 修复\n\n- **无头背压僵尸进程问题** — 现在 `ov sling` 会将无头代理的标准输出和标准错误重定向到日志文件，从而防止因背压导致的僵尸进程问题。\n- **`deployConfig` 防护写入** — 即使覆盖配置未定义，也会始终写入 `guards.json` 文件，避免无头运行时缺少防护文件的情况。\n- **Sapling 模型别名解析** — 在 `buildEnv()` 和 `buildDirectSpawn()` 两条路径中均正确扩展了模型别名。\n\n### 测试\n\n- 共计 96 个文件中的 3116 个测试用例（包含 7373 次 `expect()` 调用）。","2026-03-04T18:42:49",{"id":198,"version":199,"summary_zh":200,"released_at":201},108923,"v0.8.0","### 新增\n\n#### 协调器交互子命令\n- **`ov coordinator send`** — 通过邮件发送即发即弃的消息给正在运行的协调器，并自动催促，取代了原先需要分两步执行的 `ov mail send` + `ov nudge` 操作模式。\n- **`ov coordinator ask`** — 向协调器发起同步请求\u002F响应；发送带有 `correlationId` 的调度邮件，自动催促，在同一线程中轮询回复，并在收到回复后退出，返回回复体（可配置 `--timeout`，默认 120 秒）。\n- **`ov coordinator output`** — 使用 tmux 的 `capture-pane` 显示协调器的近期输出（可配置 `--lines`，默认 100 行）。\n- 在 `src\u002Fcommands\u002Fcoordinator.test.ts` 中新增了 334 行测试覆盖率。\n\n#### 调度器代理定义\n- **`agents\u002Forchestrator.md`** — 新增用于协调多个仓库的底层代理定义，位于协调器之上。\n- 定义了调度器的角色：通过 `ov coordinator start --project` 为每个子仓库启动协调器，通过邮件进行监控，且从不直接修改代码。\n- 列出了可能的失败模式：`DIRECT_SLING`、`CODE_MODIFICATION`、`SPEC_WRITING`、`OVERLAPPING_REPO_SCOPE`、`OVERLAPPING_FILE_SCOPE`、`DIRECT_MERGE`、`PREMATURE_COMPLETION`、`SILENT_FAILURE`、`POLLING_LOOP`。\n- 该代理定义共 239 行。\n\n#### 协调器的运营者消息协议\n- 在 `agents\u002Fcoordinator.md` 中新增了 **`operator-messages`** 部分 — 定义了协调器如何处理来自 CLI 的同步人工请求。\n- 回复格式：始终使用 `ov mail reply` 并回显 `correlationId`。\n- 状态请求格式：结构化为 `Active leads` \u002F `Completed` \u002F `Blockers` \u002F `Next actions`。\n- 包括调度、停止、合并以及未知请求的处理规则。\n\n#### 全局标志 `--project`\n- **`ov --project \u003Cpath>`** — 为任意命令指定不同的项目根目录，覆盖自动检测功能。\n- 会验证目标路径是否包含 `.overstory\u002Fconfig.yaml`；若缺失则抛出 `ConfigError`。\n- 在 `src\u002Fconfig.ts` 中新增了 `setProjectRootOverride()`、`getProjectRootOverride()` 和 `clearProjectRootOverride()` 函数。\n- 在 `src\u002Fconfig.test.ts` 中新增了 66 行测试覆盖率。\n\n#### `ov update` 命令\n- **`ov update`** — 从已安装的 npm 包中刷新 `.overstory\u002F` 目录下的管理文件，无需执行完整的 `ov init`。\n- 刷新内容包括：代理定义文件（`agent-defs\u002F*.md`）、`agent-manifest.json`、`hooks.json`、`.gitignore`、`README.md`。\n- 不会触及的内容有：`config.yaml`、`config.local.yaml`、SQLite 数据库、代理状态、工作树、规范文件、日志以及 `.claude\u002Fsettings.local.json`。\n- 可选参数：`--agents`、`--manifest`、`--hooks`、`--dry-run`、`--json`。\n- 排除了已废弃的代理定义文件（`supervisor.md`）。\n- 在 `src\u002Fcommands\u002Fupdate.test.ts` 中新增了 464 行测试覆盖率。\n\n### 变更\n\n- 代理类型由 7 种增加到 8 种（新增调度器）。\n- CLI 命令数量由 32 条增加到 34 条（新增 `update`、`coordinator send`、`coordinator ask`、`coordinator output`）。\n\n### 测试\n\n- 共计 92 个文件中包含 2923 个测试用例（总计 6852 次 `expect()` 调用）。","2026-03-03T20:58:41",{"id":203,"version":204,"summary_zh":205,"released_at":206},108924,"v0.7.9","### Added\n\n#### Gemini CLI Runtime Adapter\n- **Gemini CLI** (`gemini`) runtime adapter — full `AgentRuntime` implementation for Google's Gemini coding agent\n- TUI-based interactive mode via tmux (Ink-based TUI, similar to Copilot adapter)\n- Instruction file: `GEMINI.md` written to worktree root (agent overlay content)\n- Sandbox support via `--sandbox` flag, `--approval-mode yolo` for auto-approval\n- Headless mode: `gemini -p \"prompt\"` for one-shot calls\n- Transcript parsing from `--output-format stream-json` NDJSON events\n- Registered in runtime registry as `\"gemini\"`, available via `ov sling --runtime gemini`\n- 537 lines of test coverage in `src\u002Fruntimes\u002Fgemini.test.ts`\n\n#### Model Alias Expansion via Environment Variables\n- **`ANTHROPIC_DEFAULT_{ALIAS}_MODEL`** env vars — expand model aliases (`sonnet`, `opus`, `haiku`) to specific model IDs at runtime\n- `expandAliasFromEnv()` in `src\u002Fagents\u002Fmanifest.ts` checks `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`\n- Applied during `resolveModel()` — env var values override default alias resolution\n- 169 lines of new test coverage in `src\u002Fagents\u002Fmanifest.test.ts`\n\n### Fixed\n\n- **`.overstory\u002F.gitignore`** — un-ignore `agent-defs\u002F` contents so custom agent definitions are tracked by git\n- **CI lint** — fix import sort order in `sling.test.ts`\n\n### Testing\n\n- 2888 tests across 91 files (6768 `expect()` calls)\n","2026-03-03T13:00:21",{"id":208,"version":209,"summary_zh":210,"released_at":211},108925,"v0.7.8","### Added\n\n#### Shell Init Delay\n- **`runtime.shellInitDelayMs`** config option — configurable delay between tmux session creation and TUI readiness polling, giving slow shells (oh-my-zsh, nvm, starship, etc.) time to initialize before the agent command starts\n- Applied to both `ov sling` and `ov coordinator start` spawn paths\n- Validation: must be non-negative number; values above 30s trigger a warning\n\n#### `--base-branch` Flag for `ov sling`\n- **`ov sling --base-branch \u003Cbranch>`** — override the base branch for worktree creation instead of using the canonical branch\n- Resolution order: `--base-branch` flag > current HEAD > `config.project.canonicalBranch`\n- New `getCurrentBranch()` helper in `src\u002Fcommands\u002Fsling.ts`\n\n#### Token Snapshot Run Tracking\n- **`run_id`** column added to `token_snapshots` table — snapshots are now tagged with the active run ID when recorded\n- `getLatestSnapshots()` accepts optional `runId` parameter to filter snapshots by run\n- `ov costs --live` now scopes to current run when `--run` is provided\n- Migration `migrateSnapshotRunIdColumn()` safely adds the column to existing databases\n\n#### Tmux Session State Detection\n- **`checkSessionState()`** in `src\u002Fworktree\u002Ftmux.ts` — detailed session state reporting that distinguishes `\"alive\"`, `\"dead\"`, and `\"no_server\"` states (vs the boolean `isSessionAlive()`)\n- Used by coordinator to provide targeted error messages and clean up stale sessions\n\n### Fixed\n\n#### Coordinator Zombie Detection\n- **`src\u002Fcommands\u002Fcoordinator.ts`** — `ov coordinator start` now detects zombie coordinator sessions (tmux pane exists but agent process has exited) and automatically reclaims them instead of blocking with \"already running\"\n- Stale sessions where tmux is dead or server is not running are now cleaned up before re-spawning\n- Handles pid-null edge case (sessions from older schema) conservatively\n\n#### Shell Init Delay Validation\n- **`src\u002Fconfig.ts`** — validates `shellInitDelayMs` is a non-negative finite number; warns on values above 30s; falls back to default (0) on invalid input\n\n### Testing\n- 2830 tests across 90 files (6689 `expect()` calls)\n- **`src\u002Fmetrics\u002Fpricing.test.ts`** — new test suite covering `getPricingForModel()` and `estimateCost()`\n- **`src\u002Fmetrics\u002Fstore.test.ts`** — snapshot run_id recording and filtering tests\n- **`src\u002Fcommands\u002Fcoordinator.test.ts`** — zombie detection, stale session cleanup, and pid-null edge case tests\n- **`src\u002Fcommands\u002Fsling.test.ts`** — `--base-branch` flag and `getCurrentBranch()` tests\n- **`src\u002Fconfig.test.ts`** — `shellInitDelayMs` validation tests\n- **`src\u002Fworktree\u002Ftmux.test.ts`** — `checkSessionState()` tests\n","2026-03-02T18:57:28",{"id":213,"version":214,"summary_zh":215,"released_at":216},108926,"v0.7.7","### Added\n\n#### Codex Runtime Adapter\n- **`src\u002Fruntimes\u002Fcodex.ts`** — new `CodexRuntime` adapter implementing the `AgentRuntime` interface for OpenAI's `codex` CLI, with headless `codex exec` mode, OS-level sandbox security (Seatbelt\u002FLandlock), `AGENTS.md` instruction path, and NDJSON event stream parsing for token usage\n- **`src\u002Fruntimes\u002Fcodex.test.ts`** — comprehensive test suite (741 lines) covering spawn command building, config deployment, readiness detection, and transcript parsing\n- **Runtime registry** now includes `codex` alongside `claude`, `pi`, and `copilot`\n\n#### Documentation\n- **`docs\u002Fruntime-adapters.md`** — contributor guide (991 lines) covering the `AgentRuntime` interface, all four built-in adapters, the registry pattern, and a step-by-step walkthrough for adding new runtimes\n\n### Changed\n\n#### Dashboard Redesign\n- **`src\u002Fcommands\u002Fdashboard.ts`** — rewritten with rolling event buffer, compact panels, and new multi-panel layout (Agents 60% + Tasks\u002FFeed 40%, Mail + Merge Queue row, Metrics row)\n\n### Fixed\n- **`src\u002Fcommands\u002Finit.test.ts`** — use no-op spawner in init tests to avoid CI failures from tmux\u002Fsubprocess side effects\n\n### Testing\n- 2779 tests across 89 files (6591 `expect()` calls)\n","2026-02-27T19:54:03",{"id":218,"version":219,"summary_zh":220,"released_at":221},108927,"v0.7.6","### Added\n\n#### Copilot Runtime Adapter\n- **`src\u002Fruntimes\u002Fcopilot.ts`** — new `CopilotRuntime` adapter implementing the `AgentRuntime` interface for GitHub Copilot's `copilot` CLI, with `--allow-all-tools` permission mode, `.github\u002Fcopilot-instructions.md` instruction path, and transcript parsing support\n- **`src\u002Fruntimes\u002Fcopilot.test.ts`** — comprehensive test suite (507 lines) covering spawn command building, config deployment, readiness detection, and transcript parsing\n- **Runtime registry** now includes `copilot` alongside `claude` and `pi`\n\n#### Ecosystem Bootstrap in `ov init`\n- **`ov init` now bootstraps sibling os-eco tools** — automatically runs `mulch init`, `sd init`, and `cn init` when the respective CLIs are available; adds CLAUDE.md onboarding sections for each tool\n- **New flags:** `--tools \u003Clist>` (comma-separated tool selection), `--skip-mulch`, `--skip-seeds`, `--skip-canopy`, `--skip-onboard`, `--json`\n- **`src\u002Fcommands\u002Finit.test.ts`** — expanded with ecosystem bootstrap tests (335 lines total)\n\n#### Doctor Provider Checks\n- **`src\u002Fdoctor\u002Fproviders.ts`** — new `providers` check category (11th category) validating gateway provider reachability, auth token environment variables, and tool-use compatibility for multi-runtime configurations\n- **`src\u002Fdoctor\u002Fproviders.test.ts`** — test suite (373 lines) covering provider validation scenarios\n\n#### Multi-Provider Model Pricing\n- **`src\u002Fmetrics\u002Fpricing.ts`** — extended with OpenAI (GPT-4o, GPT-4o-mini, GPT-5, o1, o3) and Google Gemini (Flash, Pro) pricing alongside existing Claude tiers\n\n#### Cost Analysis Enhancements\n- **`--bead \u003Cid>` flag for `ov costs`** — filter cost breakdown by task\u002Fbead ID via new `MetricsStore.getSessionsByTask()` method\n- **Runtime-aware transcript discovery** — `ov costs --self` now resolves transcript paths through the runtime adapter instead of hardcoding Claude Code paths\n\n#### Agent Discovery Improvements\n- **Runtime-aware instruction path** in `ov agents discover` — `extractFileScope()` now tries the configured runtime's `instructionPath` before falling back to `KNOWN_INSTRUCTION_PATHS`\n\n### Changed\n\n- **CI: CHANGELOG-based GitHub release notes** — publish workflow now extracts the version's CHANGELOG.md section for release notes instead of auto-generating from commits; falls back to `--generate-notes` if no entry found\n\n### Fixed\n\n- **Pi coding agent URL** updated in README to correct repository path\n\n#### Testing\n- 2714 tests across 88 files (6481 `expect()` calls)\n","2026-02-27T02:25:13",{"id":223,"version":224,"summary_zh":225,"released_at":226},108928,"v0.7.5","### Fixed\n\n- **tmux \"command too long\" error** — coordinator, monitor, and supervisor commands now pass agent definition file paths instead of inlining content via `--append-system-prompt`; the shell inside the tmux pane reads the file via `$(cat ...)` at runtime, keeping the tmux IPC message small regardless of agent definition size (fixes #45)\n- **Biome formatting** in seeds tracker test (`src\u002Ftracker\u002Fseeds.test.ts`)\n\n### Changed\n\n- **`SpawnOpts.appendSystemPromptFile`** — new option in `AgentRuntime` interface (`src\u002Fruntimes\u002Ftypes.ts`) for file-based system prompt injection; both Claude and Pi runtime adapters support it with fallback to inline `appendSystemPrompt`\n- **README and package description** updated to be runtime-agnostic, reflecting the `AgentRuntime` abstraction\n\n#### Testing\n- 2612 tests across 86 files (6277 `expect()` calls)\n","2026-02-26T22:32:22",{"id":228,"version":229,"summary_zh":230,"released_at":231},108929,"v0.7.4","### Added\n\n#### Runtime-Agnostic Pricing Module\n- **`src\u002Fmetrics\u002Fpricing.ts`** — extracted pricing logic from `transcript.ts` into a standalone module with `TokenUsage`, `ModelPricing`, `getPricingForModel()`, and `estimateCost()` exports, enabling any runtime (not just Claude Code) to use cost estimation without pulling in JSONL-specific parsing logic\n\n#### Multi-Runtime Instruction File Discovery\n- **`KNOWN_INSTRUCTION_PATHS`** in `agents.ts` — `extractFileScope()` now tries `.claude\u002FCLAUDE.md` then `AGENTS.md` (future Codex support) instead of hardcoding Claude Code's overlay path\n\n#### Mulch Classification Guidance\n- **`--classification` guidance in all 8 agent definitions** — builder, coordinator, lead, merger, monitor, reviewer, and scout definitions updated with `--classification \u003Cfoundational|tactical|observational>` guidance for `ml record` commands, with inline descriptions of when to use each classification level\n\n#### Pi Runtime Improvements\n- **`agent_end` handler in Pi guard extensions** — Pi agents now log `session-end` when the agentic loop completes (via `agent_end` event), preventing watchdog false-positive zombie escalation; `session_shutdown` handler kept as a safety net for crashes and force-kills\n- **`--tool-name` forwarding** in Pi guard extensions — `ov log tool-start` and `ov log tool-end` calls now correctly forward the tool name\n\n#### Testing\n- **Tracker adapter test suites** — comprehensive tests for beads (`src\u002Ftracker\u002Fbeads.test.ts`, 454 lines) and seeds (`src\u002Ftracker\u002Fseeds.test.ts`, 469 lines) backends covering CLI invocation, JSON parsing, error handling, and edge cases\n- Test suite grew from 2550 to 2607 tests across 86 files (6269 expect() calls)\n\n### Fixed\n- **`OVERSTORY_GITIGNORE` import in `prime.ts`** — removed duplicate constant definition, now imports from `init.ts` where the canonical constant lives\n- **Pi agent zombie-state bug** — without the `agent_end` handler, completed Pi agents were never marked \"completed\" in the SessionStore, causing the watchdog to escalate them through stalled → nudge → triage → terminate\n- **Shell completions for `sling`** — added missing `--runtime` flag to shell completion definitions (PR #39, thanks [@lucabarak](https:\u002F\u002Fgithub.com\u002Flucabarak))\n- **`cleanupTempDir` ENOENT\u002FEBUSY handling** — tightened catch block for ENOENT errors and added retry logic for EBUSY from SQLite WAL handles on Windows (#41)\n","2026-02-26T19:08:21",{"id":233,"version":234,"summary_zh":235,"released_at":236},108930,"v0.7.3","### Added\n\n#### Outcome Feedback Loop\n- **Mulch outcome tracking** — sling now captures applied mulch record IDs at spawn time (saved to `.overstory\u002Fagents\u002F{name}\u002Fapplied-records.json`) and `ov log session-end` appends \"success\" outcomes back to those records, closing the expertise feedback loop\n- `MulchClient.appendOutcome()` method for programmatic outcome recording with status, duration, agent, notes, and test results fields\n\n#### Mulch Search\u002FPrime Enrichment\n- `--classification` filter for mulch search (foundational, tactical, observational)\n- `--outcome-status` filter for mulch search (success, failure)\n- `--sort-by-score` support in mulch prime for relevance-ranked expertise injection\n\n#### Dashboard Redesign\n- **Tasks panel** — upper-right quadrant displays tracker issues with priority colors\n- **Feed panel** — lower-right quadrant shows recent events from the last 5 minutes\n- `dimBox` — dimmed box-drawing characters for less aggressive panel borders\n- `computeAgentPanelHeight()` — dynamic agent panel sizing (min 8, max 50% screen, scales with agent count)\n- Tracker caching with 10s TTL to reduce repeated CLI calls\n- Layout restructured to 60\u002F40 split (agents left, tasks+feed right) with 50\u002F50 mail\u002Fmerge at bottom\n\n#### Formatting\n- `formatEventLine()` — centralized compact event formatting with agent colors and event labels (used by both feed and dashboard)\n- `numericPriorityColor()` — maps numeric priorities (1–4) to semantic colors\n- `buildAgentColorMap()` and `extendAgentColorMap()` — stable color assignment for agents by appearance order\n\n#### Sling\n- `--no-scout-check` flag to suppress scout-before-build warning\n- `shouldShowScoutWarning()` — testable logic for when to warn about missing scouts\n\n#### Testing\n- 2550 tests across 84 files (6167 `expect()` calls), up from 2476\u002F83\u002F6044\n- New `src\u002Flogging\u002Fformat.test.ts` — coverage for event line formatting and color utilities\n\n### Fixed\n\n#### Pi Runtime\n- **EventStore visibility** — removed stdin-only gate on EventStore writes so Pi agents get full event tracking without stdin payload (`ov log tool-start`\u002F`tool-end`)\n- **Tool name forwarding** — Pi guard extensions now pass `--tool-name` to `ov log` calls, fixing missing tool names in event timelines\n\n#### Shell Completions\n- Added missing `--runtime` flag to sling completions\n- Synced all shell completion scripts (bash\u002Fzsh\u002Ffish) with current CLI commands and flags\n- Added `--no-scout-check` and `--all` (dashboard) to completions\n\n#### Feed\n- Restored `formatEventLine()` usage lost during dashboard-builder merge conflict\n\n#### Testing Infrastructure\n- Retry temp dir cleanup on EBUSY from SQLite WAL handles (exponential backoff, 5 retries) — fixes flaky cleanup on Windows\n- Tightened `cleanupTempDir()` ENOENT handling\n\n### Changed\n\n- Dashboard layout restructured from single-column to multi-panel grid with dynamic sizing\n- Feed and dashboard now share centralized event formatting via `formatEventLine()`\n- Brand color lightened for better terminal contrast\n","2026-02-26T17:40:36",{"id":238,"version":239,"summary_zh":240,"released_at":241},108931,"v0.7.2","### Added\n\n#### Pi Runtime Enhancements\n- **Configurable model alias expansion** — `PiRuntimeConfig` type with `provider` + `modelMap` fields so bare aliases like \"opus\" are correctly expanded to provider-qualified model IDs (e.g., \"anthropic\u002Fclaude-opus-4-6\"), configurable via `config.yaml` runtime.pi section\n- **`requiresBeaconVerification?()`** — optional method on `AgentRuntime` interface; Pi returns `false` to skip the beacon resend loop that spams duplicate startup messages (Pi's idle\u002Fprocessing states are indistinguishable via pane content)\n- Config validation for `runtime.pi.provider` and `runtime.pi.modelMap` entries\n\n### Fixed\n\n#### Pi Runtime\n- **Zombie-state bug** — Pi agents were stuck in zombie state because pi-guards.ts used the old `() => Extension` object-style API instead of the correct `(pi: ExtensionAPI) => void` factory style; guards were never firing. Rewritten to ExtensionAPI factory format with proper `event.toolName` and `{ block, reason }` returns\n- **Activity tracking** — Added `pi.on(tool_call\u002Ftool_execution_end\u002Fsession_shutdown)` handlers so `lastActivity` updates and the watchdog no longer misclassifies active Pi agents as zombies\n- **Beacon verification loop** — `sling.ts` now skips the beacon resend loop when `runtime.requiresBeaconVerification()` returns `false`, preventing duplicate startup messages for Pi agents\n- **`detectReady()`** — Fixed to check for Pi TUI header (`pi v`) + token-usage status bar regex instead of `model:` which Pi never emits\n- Pi guard extension tests updated for ExtensionAPI format (8 fixes + 7 new tests)\n\n#### Agent Definitions\n- Replaced 54 hardcoded \"bead\" references in agent base definitions with tracker-agnostic terminology (task\u002Fissue); `{{TRACKER_CLI}}` and `{{TRACKER_NAME}}` placeholders remain for CLI commands\n- Fixed overlay fallback default from \"bd\" to \"sd\" (seeds is the preferred tracker)\n\n### Changed\n\n- **Supervisor agent soft-deprecated** — `ov supervisor` commands marked `[DEPRECATED]` with stderr warning on `start`; supervisor removed from default agent manifest and `ov init` agent-defs copy; `supervisor.md` retains deprecation notice but code is preserved for backward compatibility\n- `biome.json` excludes `.pi\u002F` directory from linting (generated extension files)\n\n### Testing\n\n- 2476 tests across 83 files (6044 `expect()` calls)\n","2026-02-26T15:44:03",{"id":243,"version":244,"summary_zh":245,"released_at":246},108932,"v0.7.0","### Added\n\n#### AgentRuntime Abstraction Layer\n- **`src\u002Fruntimes\u002Ftypes.ts`** — `AgentRuntime` interface defining the contract for multi-provider agent support: `buildSpawnCommand()`, `buildPrintCommand()`, `deployConfig()`, `detectReady()`, `parseTranscript()`, `buildEnv()`, plus supporting types (`SpawnOpts`, `ReadyState`, `OverlayContent`, `HooksDef`, `TranscriptSummary`)\n- **`src\u002Fruntimes\u002Fclaude.ts`** — `ClaudeRuntime` adapter implementing `AgentRuntime` for Claude Code CLI — delegates to existing subsystems (hooks-deployer, transcript parser) without new behavior\n- **`src\u002Fruntimes\u002Fregistry.ts`** — Runtime registry with `getRuntime()` factory — lookup by name, config default, or hardcoded \"claude\" fallback\n- **`docs\u002Fruntime-abstraction.md`** — Design document covering coupling inventory, phased migration plan, and adapter contract rationale\n- **`--runtime \u003Cname>` flag** on `ov sling` — allows per-agent runtime override (defaults to config or \"claude\")\n- **`runtime.default` config field** — new optional `OverstoryConfig.runtime.default` property for setting the default runtime adapter\n\n#### Testing\n- **`src\u002Fruntimes\u002Fclaude.test.ts`** — 616-line test suite for ClaudeRuntime adapter covering all 7 interface methods\n- **`src\u002Fruntimes\u002Fregistry.test.ts`** — Registry tests for name lookup, config default fallback, and unknown runtime errors\n- **`src\u002Fcommands\u002Fsling.test.ts`** — Additional sling tests for runtime integration\n- **`src\u002Fagents\u002Foverlay.test.ts`** — Tests for parameterized `instructionPath` in `writeOverlay()`\n- 2357 tests across 81 files (5857 `expect()` calls)\n\n### Changed\n\n#### Runtime Rewiring (Phase 2)\n- **`src\u002Fcommands\u002Fsling.ts`** — Rewired to use `AgentRuntime.buildSpawnCommand()` and `detectReady()` instead of hardcoded `claude` CLI construction and TUI heuristics\n- **`src\u002Fcommands\u002Fcoordinator.ts`** — Rewired to use `AgentRuntime` for spawn command building, env construction, and TUI readiness detection\n- **`src\u002Fcommands\u002Fsupervisor.ts`** — Rewired to use `AgentRuntime` for spawn command building and TUI readiness detection\n- **`src\u002Fcommands\u002Fmonitor.ts`** — Rewired to use `AgentRuntime` for spawn command building and env construction\n- **`src\u002Fworktree\u002Ftmux.ts`** — `waitForTuiReady()` now accepts a `detectReady` callback instead of hardcoded Claude Code TUI heuristics, making it runtime-agnostic\n- **`src\u002Fagents\u002Foverlay.ts`** — `writeOverlay()` now accepts an optional `instructionPath` parameter (default: `.claude\u002FCLAUDE.md`), enabling runtime-specific instruction file paths\n\n#### Branding\n- README.md: replaced ASCII ecosystem diagram with os-eco logo image\n","2026-02-26T01:46:01",{"id":248,"version":249,"summary_zh":250,"released_at":251},108933,"v0.6.11","### Added\n\n#### Per-Lead Agent Budget Ceiling\n- **`agents.maxAgentsPerLead` config** (default: 5) — limits how many active children a single lead agent can spawn; set to 0 for unlimited\n- **`--max-agents \u003Cn>` flag on `ov sling`** — CLI override for the per-lead ceiling when spawning under a parent\n- **`checkParentAgentLimit()`** — pure-function guard that counts active children per parent and blocks spawns at the limit\n\n#### Dispatch-Level Overrides\n- **`--skip-review` flag on `ov sling`** — instructs a lead agent to skip Phase 3 review and self-verify instead (reads builder diff + runs quality gates)\n- **`--dispatch-max-agents \u003Cn>` flag on `ov sling`** — per-lead agent ceiling override injected into the overlay so the lead knows its budget\n- **`formatDispatchOverrides()`** in overlay system — generates a `## Dispatch Overrides` section in lead overlays when `skipReview` or `maxAgentsOverride` are set\n- **`dispatch-overrides` section in `agents\u002Flead.md`** — documents the override protocol so leads know to check their overlay before following the default three-phase workflow\n- **`DispatchPayload` extended** with `skipScouts`, `skipReview`, and `maxAgents` optional fields\n\n#### Duplicate Lead Prevention\n- **`checkDuplicateLead()`** — prevents two lead agents from concurrently working the same task ID, avoiding the duplicate work stream anti-pattern (overstory-gktc postmortem)\n\n#### Mail Refactoring\n- **`shouldAutoNudge()` and `isDispatchNudge()`** exported from mail.ts for testability — previously inlined logic now unit-testable\n- **`AUTO_NUDGE_TYPES`** exported as `ReadonlySet` for direct test assertions\n\n#### Testing\n- **`sling.test.ts`** — expanded (201 lines added) covering `checkDuplicateLead`, `checkParentAgentLimit`, per-lead budget ceiling enforcement, and dispatch override validation\n- **`overlay.test.ts`** — expanded (236 lines added) covering `formatDispatchOverrides`, skip-review overlay, max-agents overlay, and combined overrides\n- **`mail.test.ts`** — expanded (64 lines added) covering `shouldAutoNudge`, `isDispatchNudge`, and dispatch nudge behavior\n- **`hooks-deployer.test.ts`** — new test file (105 lines) covering hooks deployment and configurable safe prefix extraction\n- **`config.test.ts`** — expanded (22 lines added) covering `maxAgentsPerLead` validation\n\n### Changed\n\n- **Terminology normalization** — replaced \"beads\" with \"task\" throughout CLI copy and generic code: `checkBeadLock` → `checkTaskLock`, `{{BEAD_ID}}` → `{{TASK_ID}}` in overlay template, error messages updated (\"Bead is already being worked\" → \"Task is already being worked\")\n- **README unified** to canonical os-eco template — shortened, restructured with table-based CLI reference, consistent badge style\n- **`agents\u002Flead.md`** — added `dispatch-overrides` section documenting SKIP REVIEW and MAX AGENTS override protocol\n- **Default tracker name** changed from `\"beads\"` to `\"seeds\"` in overlay fallback\n\n### Fixed\n\n- **`ov trace` description** — changed from \"agent\u002Fbead\" to \"agent or task\" for consistency with terminology normalization\n\n### Testing\n- 2283 tests across 79 files (5749 `expect()` calls)\n","2026-02-25T22:53:06"]