运维：运行并恢复无人值守的 AI 运行器

​

Timers

1. 先同步 engine source（ExecStartPre，在 Runner 进程外）。两个 步骤，都包在一个短生命周期的 flock（共享状态目录下的 base-sync.lock，Python 侧同步取同一把锁）里；两个实例可能在同一 tick 运行 ExecStartPre，并且自 Issue #171 起，所有更新共享 remote-tracking ref 的 fetch 都走同一把锁：Runner 侧的 freeze_base / verify_pr / merge_gate / confirm_merged fetch 统一经 fetch_base_ref（先取锁 → fetch → 释放，锁或 fetch 出错即 fail fast），implement/review 两个 prompt 指示 Pi 用 flock <BASE_SYNC_LOCK> git fetch origin <base_branch> 执行 base 新鲜度 fetch（锁路径从配置的 repo_dir 渲染进两个 prompt）。两个 并发 Runner（或 Runner 与 Pi 会话）因此不再争抢共享 ref（不会出现 cannot lock ref ... is at <X> but expected <Y> 失败）。两个步骤 作用的 checkout 都是部署 home——{{ORBI_REPO_DIR}} 占位符在 安装时渲染的是 deploy_home 路径（缺省 repo_dir），所以外部单仓 库模式（Issue #330）下同步、锁和 CLI 自愈全部作用于 orbi 源码 checkout，绝不作用于交付 checkout（用户仓库 X）。
   • 步骤 1 —— CLI 自愈（Issue #248）：探测已安装的 console script（orbi --version 当且仅当包可导入时成功），探测失败时在 同一把 base-sync.lock flock 下执行精确的 editable 强制重装 （uv tool install --force --reinstall --editable --python <interpreter> <repo_dir>——<interpreter> 遵循兼容选取规则： 系统 Python 满足 >= 3.14 下限时为 python3，否则为 uv 自动 供应的 3.14，与 orbi setup 同一规则，Issue #861）。这是 console script 连 import orbi 都失败时唯一能动手的地方——#248 现场：#168 的 src 布局迁移让已安装的 editable finder 过期，而 #158 的 Runner 内刷新（在 Runner 内部运行）根本不可达。它排在同步之前， 因为同步子命令需要可用的 CLI。健康的 CLI 退出 0，其余什么都不做 （不逐 tick 重装）；重装失败则 preflight 失败、service 不启动 （fail fast，无回退）。
   • 步骤 2 —— engine source 同步（Issue #535）：orbi sync-engine-source 把部署 home 带到配置的 engine source 更新 通道。通道是 deploy home orbi.toml 里的 host/deploy-only 配置 键 engine_source_track（仓库的 .github/orbi.toml 永远 不允许携带它；模式与失败行见下文 engine source 更新通道）。缺省 main 通道保持 #535 之前的精确行为：git fetch --no-auto-maintenance origin main && git merge --ff-only origin/main——fast-forward 到 origin/main。每次 fetch 都带 --no-auto-maintenance，避免 Git 子进程脱离 preflight 和共享锁的生命周期。checkout 不干净、fetch 失败、tag/SHA/branch 缺失、无法 fast-forward、或任何无法对照解析 结果验证的状态都会让 preflight 失败：service 不启动，原因写入 systemd journal（fail closed）。每种失败各写一条结构化、可操作的 行（deploy_home_dirty files=... fix=...、 engine_source_unresolved reason=...、 engine_source_not_fast_forwardable ...）；成功时同步写一条结构化 engine_source_synced engine_source_track=... resolved=... head=... 行。通道不是缺省的 main（branch:/release/tag:/sha:）时， Runner 也会跳过 merge 之后对部署 checkout 的 fast-forward：通道 拥有该 checkout，下一个 tick 的步骤 2 会重新施加它。
   正在运行的长任务从不被热更新或杀掉——一个 service 实例 active 时 systemd 忽略对该实例的后续 start 请求，下一次真正启动取到通道 跟踪的代码。
2. 运行一个 tick：恢复一个已打开的 PR（review/fix/merge 步骤），或 领取一个 ai-ready Issue，然后退出。一个 tick 至多执行一步交付，绝不 sleep 等待 GitHub（Issue #788）：implement tick 在 PR 打开后结束并释放 槽位；review tick 是唯一在 Pi 运行期间持有槽位的阶段；CI pending 或 mergeable UNKNOWN 记一行 journal 即返回——下一 tick 重读（waiting 原语）。在任何 slot 或领取之前，tick 还 运行启动前 git transport 检查（Issue #114、#580）：部署 checkout 的 origin remote 必须匹配配置的传输方式（orbi.toml git_transport：ssh——默认，[email protected]:owner/repo.git；或 https——https://github.com/<repo>.git，凭据走 gh credential helper），且对第一个配置 source repo 的 git ls-remote <expected-url> 退出 0（传输可达且已认证）。 传输损坏记录结构化 transport_check_failed ... reason=... 行并让 启动失败——不取 slot、不领取、不改标签，没有回退（GitHub API 操作永远留在 gh token 上）。同样在任何 slot 或领取之前，tick 运行 runner 执行代码新鲜度门禁（Issue #525）：证明本进程执行 的代码与配置的 engine source 通道一致（Issue #535： engine_source_track，缺省 origin/main——绝不是交付目标的 base_branch）——见下文 Runner 执行代码新鲜度与防线分层。

systemctl --user list-timers 'orbi@*.timer'
systemctl --user status 'orbi@*.service'

​

engine source 更新通道

• release 与 tag:——跟随与锁定：release（别名 stable）跟随 最新已发布版本，新 tag 发布后自动跟进——只在发版时变化（main 每次 提交都变）。tag:<name> 锁死一个精确版本，不改值就永不移动——版本 变更永远是一次有意操作；要求部署保持可复现时用它锁定，回滚就是把 上一个 tag 改回去。
• 安装与更新：install.sh 新安装复制 src/orbi/example_config.toml，其中 携带 engine_source_track = "release"——新部署跟随最新 release，而 不是 main 的中间态。Orbi 自有 dogfood 部署显式固定 main 通道。 通道值在下一次 service 启动时生效（ExecStartPre 同步施加它）；没有 守护进程，也不会重启正在运行的 Runner。
• 回滚就是把 track 改回旧的 tag:/sha: 值（或 release/main）——git 状态是唯一的存储，没有别的状态要清理。
• fail closed（service 不启动，每行都带 fix=）：
  • deploy_home_dirty files=... fix=...——tracked 本地编辑会阻塞 同步；用 git -C <deploy_home> stash && systemctl --user start [email protected] 保存后重试（之后 stash pop），或用 git -C <deploy_home> checkout -- . 丢弃。
  • engine_source_unresolved reason=tag_not_found|tag_conflict|sha_not_found|branch_ref_missing|no_official_release_tag—— 通道无法解析（先 fetch、核对名字，或发布 release tag）。
  • engine_source_not_fast_forwardable——分支在本地已分叉（部署 home 永远不应携带本地 commit）。
  • engine_source_unverified——HEAD 无法证明等于解析出的 commit。
• 成功证据：每次启动一条结构化 engine_source_synced engine_source_track=... resolved=... head=... journal 行。
• doctor 只读上报通道：engine_source: track=... resolved=... head=...（通道本地无法解析时输出带同样 reason 的 FAILED 行）。
• GitHub 拒绝按未广播的 SHA fetch（not our ref），所以 sha: 通道 一次性 fetch 全部已广播 ref，再在本地验证 commit；只能从未合并的 PR 分支可达的 SHA 因此 fail closed——请锁定 tag/release。
• 交付目标不受影响：base_branch 继续管辖任务 worktree 与交付 PR （engine/delivery 的语义隔离是 Issue #543 的主题）。

​

Runner 执行代码新鲜度与防线分层

• editable 安装（官方部署形态）：门禁解析运行中进程的 import 源（orbi.__file__ → src/orbi 包目录，绝不是 WorkingDirectory）， 用 git rev-parse --show-toplevel 定位其所在 checkout，并要求该 checkout 的 HEAD 等于配置的 engine source 通道的期望 commit： main/branch: 通道取已 fetch 的 refs/remotes/origin/<branch> 头，release/tag: 通道取解析出的 release/tag commit，sha: 通道 取精确 SHA。worktree 与部署 home 共享 refs，所以事故场景（install 绑到旧 worktree）在这里被拒绝。
• 非 editable 安装（uv tool / PyPI 拷贝）：安装的发行版本 （importlib.metadata）不得旧于通道对应的 release tag——跟踪分支 ref 上可达的最新 tag，或锁定的 release/tag: 版本本身。sha: 锁无法映射到版本，按不可验证 fail closed。相等或更新即通过。
• 全部是本地 git 读（rev-parse / describe / tag --list）： 已 fetch refs/tags 的新鲜度由 ExecStartPre 同步供给，checkout 一 致时零网络请求。任何无法证明新鲜的状态（origin ref 缺失、无 release tag、import 源无法定位）都以同样方式失败并带 reason= 字段——绝不静默放行。
• 落后或无法证明时输出结构化 runner_source_stale install=... source=... engine_source_track=... head=... origin_main=... allowed=false fix=... 行并 fail fast：不取 slot、不领取、不改标签。fix 是对 deploy home 的精确 editable 强制 重装命令。allow_stale_runner: true（getting-started）把同一行降级 为告警，供离线/受限网络机器使用——绝不跳过检查。

1. ExecStartPre preflight（CLI probe 自愈 + engine source 同步， Issue #535）是最外层防线：由 systemd 在 Runner 进程存在之前 执行——probe 步骤是包裹已安装 console script 的纯 shell，探测失败 就从 checkout 重装它，因此连 import orbi 都失败的 CLI 也会先在 这里被修复。保持已安装 unit 跟上模板（install-units 与启动前检查 的 unit_drift 自愈），这道 preflight 就永远存在。
2. runner 执行代码新鲜度门禁（本节，Issue #525）是 in-runner 不变量：从它发布的版本起，代码陈旧的 runner 拒绝领取任务，而不是 无声地失败。

​

暂停、迁移或移除部署

​

暂停部署

systemctl --user disable --now [email protected]
# 对每个启用的实例 @2..@N（N = max_concurrency）重复执行：
systemctl --user disable --now [email protected]

systemctl --user status 'orbi@*.service'

​

迁移到新的 deploy home

1. 在旧部署上执行上面的暂停命令。必须先做这一步，再删除或改名旧目录； 否则启用中的 timer 会继续唤醒并持续记录失败日志。
2. 确认新的 deploy_home 是持久目录，在那里 clone 或移动 Orbi checkout， 并更新其中的 orbi.toml。保留 repo_dir 指向交付 checkout；改变 deploy_home 不应移动或删除该 checkout、它的 worktree 或 .orbi/ 状态。
3. 在新的 deploy home 安装 unit 并启用所需数量的 timer：
   cd <new-deploy-home>
   orbi setup --config orbi.toml
   
   max_concurrency = 1 会启用 [email protected]；max_concurrency = 2 还会 启用 [email protected]。用下面的命令确认结果： systemctl --user list-timers 'orbi@*.timer'。
4. 如果新部署使用与旧部署相同的 unit_name，setup 已经替换了 unit 文件；不要再删除它们，否则也会删除新部署的 unit。如果明确改用了 新的 unit_name，只有在新部署验证正常后才能删除旧 unit。先按上面的 步骤停用旧 timer，再执行 systemctl --user daemon-reload。除非已经 单独确认数据可以丢弃，否则不要把 repo、worktree 或 .orbi/ 目录作为 unit 清理的一部分删除。

​

完全移除本机上的 Orbi

systemctl --user disable --now [email protected]
# 对每个启用的实例 @2..@N 重复执行：
systemctl --user disable --now [email protected]
rm ~/.config/systemd/user/[email protected] ~/.config/systemd/user/[email protected]
systemctl --user daemon-reload

uv tool uninstall orbi-cli

​

Unit 模板变更后（Issue #131、#142）

​

日志（journal）

journalctl --user -u [email protected] -u [email protected] -f
journalctl --user -u [email protected] -u [email protected] | grep e07383c2

• run_start / run_end — 开始时的完整现场（branch、worktree、 session 文件），结束时的结果（PR URL、commit）；
• activity / heartbeat / model_wait / resumed — session 运行 期间的实时 Pi 活动（phase、最近动作、elapsed、idle）。首个响应到达 前 phase 是启动子阶段：session_pending（Pi 已启动但还没创建 session 文件）和 request_pending（session 已存在、首个响应还没 到）；首个响应到达后按原规则用工具 phase（pr、bash…）；
• process_spawned / provider_config_loaded / session_created / first_request_started / first_response_received — 启动阶段行 （Issue #176）：每个阶段一行、按顺序，每行带 issue、role、Pi 实际 选择的 provider/model（session 的 model_change 记录出现前为 -）、距 spawn 的 elapsed（process_spawned 另带 pid）。 provider_config_loaded 由 Runner 在 spawn 前记录（provider 文件已 加载并物化；未配置时用 Pi 自己的 agent dir）；其余四行由 streamer 在 session JSONL 跨过每个里程碑时记录（session 记录、第一条 user 消息——首个请求发出——第一条 assistant 消息——首个响应到达）。卡在 starting 的 run 只靠这些行加 progress 评论的 phase 就能定位到 启动阶段；只记录标识符——从不记录 key、prompt 或模型输出；
• startup_failed — run 在首个响应之前失败时的一行（Issue #176）： 说明启动卡在哪（session_created=true|false、 first_request=true|false）加可区分的 reason=—— session_not_created（Pi 退出前没创建 session 文件）、 no_first_request（session 存在但没有首个请求）、 provider_rate_limited（provider 429——Issue #321）、 auth_failure / network_timeout（从 Pi 的 stderr 分类——只记类别、 从不记文本）、pi_exit_<N>（提前退出码）、timeout（run deadline）、 first_response_timeout（冻结的 model_wait 在响应前被杀——挂死的 首个请求）、model_wait_swallowed 和 idle_recovery_stale （既有 kill 路径）。既有的 run_failed 现场行和抛出的失败不变—— startup_failed 是额外的可观测性，不是新的失败路径；
• resume_continue — 恢复的 run 继续中断的工作（Issue #219）时的一次 INFO：worktree 的 run state 文件（.orbi/run-state.json） 验证了同一个 run（issue 编号 + 仓库名——仓库改名后 slug 变了也能 找到旧 worktree），且 worktree 带有未提交改动或之前的 session； 行带 worktree、changed_files（未提交路径）、reused_runs （之前的 session 文件数）和 previous_session（session id 或 -）； 新 session 在 prompt 里收到 resume context（继续既有工作——从不 重做、从不丢弃）。同一个 run 无法验证（state 文件缺失或损坏）时 行是 resume_continue_failed：fail fast，Issue 进入 ai-blocked 并带原因——从不静默 fresh 重做；
• pi_idle — 超过 300 秒（PI_IDLE_WARN_SECONDS=300）没有 model/session 活动且模型不期望回复时的一次 WARNING；活跃的慢模型 （model_wait）从不告警；
• model_wait_swallowed — 冻结的 model_wait 被 /slots 探针确认 吞请求（Issue #233）时的一次 WARNING + 杀掉 Pi 会话： model_wait_probe_url 端点报告所有 slot 持续 model_wait_probe_seconds 宽限（默认 60 秒）都空闲 （is_processing=false）——请求被上游接受但从未被调度进 slot， 模型进程活着、连接 ESTABLISHED，但没有东西在生成（#231 现场）； 行带 issue、role、idle 秒数、探针宽限、action=kill_pi、session、 run id、upstream_alive=true|false 和 reason=swallowed_model_request。它快速触发（远早于 model_wait_dead_seconds），吞请求约 1 分钟就能恢复而不是约 30 分钟。探针是纯旁路（Issue #79）：探测失败视为无证据（无此行， model_wait_dead 兜底仍生效），有 slot 在处理会重置空闲窗口（慢 模型不是吞请求）；未设置 model_wait_probe_url 时禁用；
• model_wait_dead — 冻结的 model_wait（最近一条事件是 tool result，无新事件）超过配置的 model_wait_dead_seconds（默认 1800 秒，PI_MODEL_WAIT_DEAD_SECONDS，Issue #228）时的一次 WARNING
  • 杀掉 Pi 会话：模型请求挂死——连接还活着、模型服务进程还活着都 只是行上的证据（upstream_alive=true|false），不是豁免（进程活着 ≠ 在回话，Issue #218）；行带 issue、role、idle 秒数、实际配置的 阈值、action=kill_pi、session、run id 和 reason=hung_model_request。 阈值度量的是完整 session 事件之间的静默（Pi 不向 JSONL 写 token 级进度），不是 token 级模型进度——持续追加事件的慢生成永不 触发（慢本地模型，如 27B Q4 GGUF 配 llama-server、请求超时 1200 秒：RX 7900 XTX 全层上 GPU 时 12K 上下文约 57 tokens/s，部分上 GPU 或纯 CPU 时远低于 20 tokens/s；默认配置下慢端也能存活超过 10 分钟的完整消息）；
• pi_idle_wait — idle-stall 恢复的宽限行（Issue #181）：仍在 deadline 内的 coreutils timeout <seconds> ... 包裹是合法的长命令， 不是 hang。Runner 每次 stall 记一条 pi_idle_wait 行（run id、 pid、cmdline、deadline），并在 progress 评论里报告 recovery=wait； 先过一个完整 idle 窗口的宽限再升级，之后每个窗口重新评估。等待期间 session-kill 耗尽计数同样暂停（Issue #1089）：kill 的边界是包裹自身 的 deadline——自等待开始起以 PI_IDLE_WAIT_MAX_SECONDS（默认 3600 秒）封顶，超过上限的声明 deadline 照常升级——而不是 PI_IDLE_RECOVERY_CYCLES 个 idle 窗口；
• pi_retry_429 — provider 限流重试每次一次 WARNING（Issue #321）： Pi 非零退出且 stderr 带 429 标记（429 / quota / RESOURCE_EXHAUSTED / retry in）——这是瞬时限流，不是任务失败。 同一个 Pi 会话在同一个 run 里退避后重新拉起：优先用 429 响应自带的 重试提示（retry in Ns / retryDelay: Ns），没有就默认递增 （30 秒翻倍），两者都封顶 5 分钟。行带 run id、issue、role、 attempt、next_retry_in、重试上限 limit（5）和 session； 等待期间持有 slot（本 run 等待时不认领新 Issue）。attempt 计数是 RUN 的，不是进程的（Issue #698）：它持久化在工作树的 .orbi/ 运行目录里，跨 runner 重启持续累加，上限才能真正触达终态。5 次退避 重试仍以 429 退出（连续 6 次 429 退出）之后，交付在每个阶段都是 终态——ai-blocked，绝不走可恢复续跑——失败评论带累计次数与修复 动作（配额窗口恢复后把 Issue 重新标为 ai-ready；终态会清掉持久化 计数，重排的尝试从全新预算开始），run_failed 现场标记 reason=provider_rate_limited。长期额度耗尽不在这里处理 （#313 的轮换语义接管）；
• run_failed — 完整现场加原因（pi_exit_N、timeout_...s，或 model_wait_swallowed_idle_...s——/slots 探针确认所有 slot 持续 空闲（Issue #233）Runner 快速杀掉 Pi，model_wait_dead_stale_...s ——冻结的 model_wait 超过配置的 model_wait_dead_seconds（默认 1800 秒，Issue #228）判定模型请求挂死，Runner 杀掉 Pi， idle_recovery_stale_...s——session 连续 PI_IDLE_RECOVERY_CYCLES （默认 3）个 idle 窗口保持空闲、Runner 杀掉 Pi，或 provider_rate_limited——provider 429 在本轮全部退避重试后仍失败 （Issue #321））。

​

事件参考

​

CLI（orbi）

# 在配置的 source repo 创建 Issue 并加 ai-ready 标签
orbi add "task title" --body "task body" --config orbi.toml
orbi add "task title" --repo OWNER/BACKLOG-REPO --config orbi.toml

# 读取仓库并最多提出三个待交付 Issue：交互流程对每个建议问一次，
# 把你确认的创建或打标签；--json 把 Suggestions 文档（repo、base_sha、
# session_dir、suggestions）打印到 stdout 且不写任何东西
orbi suggest --config orbi.toml
orbi suggest --repo OWNER/REPO --json --config orbi.toml

# 只读队列视图：当前（ai-in-progress）任务带实时 Pi 活动、下一个 ready
# Issue、每个 source repo 的最近结果（ai-pr-opened / ai-fix-needed /
# ai-merged / ai-blocked）
orbi status --config orbi.toml

# 只读部署/健康报告：repo commit、unit drift、CLI 源码（cli_source:
# clean / DRIFT + 结构化 cli_source_drift 行）、git transport（配置的
# origin URL、protocol、配置的 git_transport 的期望 URL、可达性探测——传输失败报告为
# `transport: FAILED ...`，不抛出）、timer/service 实例状态、slots、
# Pi session、当前 Issue、最近 journal，以及跨已安装部署的
# task-pool 重叠诊断（source_pool: healthy / FAILED / INCOMPLETE）
orbi doctor --config orbi.toml

# 只读前置条件门禁（Issue #163）：Python 版本、必需命令
# （git/gh/uv/orbi）、systemd user bus、gh auth、pi CLI、配置文件
# （存在、解析、校验）、每个 source repo 的访问 + 写权限、git
# transport（只读，从不迁移）、模型 provider（无密钥值的状态）。
# 第一个缺失的前提即快速失败，输出一行结构化结果：
# check_failed check=<步骤> reason=... fix=... docs=<官方链接>
# （`orbi check` 从不创建配置，也从不做任何变更）
orbi check --config orbi.toml

# 一次性、幂等初始化（新机器/新仓库）：gh auth + 仓库权限、平台 labels、
# systemd user units、checkout 检查（含 git transport：处于相反传输的
# `origin` 迁移为配置的 `git_transport` 的 URL（HTTPS->SSH 或
# SSH->HTTPS；人工授权的迁移路径；Runner 本身从不改写 remote），并探测
# 传输连通性（fail fast，没有回退））
orbi setup --config orbi.toml

# 把 active milestone 推进到一个 exact 的 GitHub Milestone 标题
# （仓库策略声明 active_milestone 时写策略，否则写主机配置；
# auto_next_milestone=false 的确认 Issue 自带票内 `/milestone <标题>` 命令）
orbi milestone set v0.6.0 --config orbi.toml

# 打印当前 run 的 Pi session JSONL 路径（没有 session 时 fail fast）
orbi session --config orbi.toml
orbi session --follow --config orbi.toml   # tail -f
orbi session --pretty --config orbi.toml   # 一行摘要

​

跨部署的 task pool 重叠（Issue #1519）

• source_pool: healthy deployments=N —— 没有别的部署共享该 pool。
• source_pool: FAILED repo=<owner/name> this_config=... other_config=... fix=... —— 两个部署服务同一个 task pool；为该 pool 只选一个部署，并用它的 max_concurrency 控制并发。
• source_pool: INCOMPLETE config=... reason=... fix=... —— 发现的配置 缺失、不可读或格式错误。修复或移除该单元的 ORBI_CONFIG 引用； pool 不可读时 doctor 绝不报告 all-clear。

​

人工推进 active milestone

orbi milestone set v0.6.0 --config orbi.toml
# active_milestone: v0.5.6 -> v0.6.0
# repo: orbi-build/orbi
# wrote: repo policy .github/orbi.toml
# next: the Runner's next tick claims Issues from Milestone "v0.6.0" and
# syncs the ORBI_ACTIVE_MILESTONE variable (verify: gh api
# repos/orbi-build/orbi/actions/variables/ORBI_ACTIVE_MILESTONE --jq .value)

orbi milestone set v0.9.9 --config orbi.toml
# milestone_set_failed reason=milestone_not_found title='v0.9.9'
#   repo=orbi-build/orbi open milestones: v0.6.0(3); fix=use one exact
#   title from `gh api repos/orbi-build/orbi/milestones?state=open --jq '.[].title'`

orbi milestone set v0.5.7 --config orbi.toml
# milestone_set_failed reason=milestone_closed title='v0.5.7'
#   repo=orbi-build/orbi state=closed; auto_next_milestone is true, so the
#   next idle tick would advance active_milestone away from it;
#   fix=reopen the milestone or set auto_next_milestone = false

​

从确认 Issue 推进 active milestone

• 命令锚定在行首：长评论的任意一行都生效，> 引用回复永远不触发； 匹配前先剥离 ```/~~~ 围栏代码块，因此「怎么用这条命令」的说明不会真的 触发。
• 只接受该 Issue 候选列表里的标题，且版本号一律取自评论字面量——命令 从不推断下一个版本。
• 评论者需对该仓有 write 权限（OWNER/MEMBER/MAINTAINER/COLLABORATOR）；其他人、 候选外的标题、格式错误的命令行，都会在 Issue 上留下一条可读原因； Runner 自己的评论永不触发。
• 三步各自幂等：创建缺失的 Milestone（open）；该 Milestone 下没有 release 票时按 .github/release-ticket-template.md 开一张 （version_file 取 version_file 配置项，否则按仓内文件探测；两者都 取不到时该步失败并在回执中给出修复方式，不再猜测 pyproject.toml； 仓库没有该模板时退回内置最小字段集并在票中注明）； 最后落地 active_milestone——当前值来自仓库 .github/orbi.toml 时写 该文件，否则写部署配置。
• 某一步失败时，Issue 上说明失败在哪一步及原因，已成功的步骤不回滚； 下一个 tick 会幂等地重跑整条命令。

​

票内命令

1. 在命令自己的模块里定义 CommandSpec（/milestone 是第一个注册者）并 调用 register_command(spec)。注册即校验：名称重复、verb 已被其他命令 占用、权限级别不在 PERMISSION_LEVELS 中，都会在 import 时快速失败。
2. 在 JOURNAL_EVENTS（src/orbi/journal.py）中登记事件类型 <name>_command_applied 与 <name>_command_failed，并在上面的”事件参考” 中补上对应行；event() 会拒绝未登记的 kind。
3. 在本表（及中文页）补上该命令行：绑定测试 tests/test_ticket_command.py 会读取两张表，出现偏差即失败。
4. 确保命令模块在处理票据前被 import（调用点所在模块是 orbi/milestone.py）：register_command 在 import 时执行。唯一的 process_commands(...) 调用传入整张 TICKET_COMMANDS 注册表，已登记的 命令无需改动调用点就会被调度。

​

已完成但没有 release 票的 Milestone

• 幂等：每个已完成的 Milestone 只存在一条 open 通知，绝不每 tick 一条。
• release 票缺失时通知保持打开；等待结束后自动关闭——该 Milestone 的 release 票已出现，或该 Milestone 不再处于等待状态（又有新的 open Issue，或 release 后已关闭）。关闭评论会说明是哪种情况。
• 等待状态记录 active_milestone_release_pending old=<active> repo=<repo>， 与推进等待记录的是同一个 old= 字段。通知写入失败属于纯旁路（pending_milestone_issue_failed），绝不让 tick 失败。
• 这个等待是有意为之，不是故障：待做的决定是「为已完成的 Milestone 打开 release 票」。未开启该键（默认 false）时行为与 #856 之前完全 一致。
• /milestone 的 release-ticket 步骤无法解析 version_file 时，通知会 收到 version_file_unresolved 回执并给出修复方式；设置 version_file （或 "none"）后重新回复即可。

​

公开表面

• **CLI：**裸 orbi tick，以及 add、suggest、status、doctor、 setup、install-units、session、milestone set、check、 sync-engine-source 子命令，包括 --config 和 ORBI_CONFIG 环境变量。
• Suggestions：orbi suggest --json 打印的文档（repo、base_sha、 session_dir 与最多三条建议）、保留的运行目录 <deploy_home>/.orbi/suggest/<run_id>/，以及产出它的 skill integrations/claude-plugin/skills/suggest-ai-ready-issues/（Issue #1576）；orbi setup 的提议只在终端上运行，否则只打印一行提示。
• 配置：配置参考中的每个 key 都是公开表面， 另加由 systemd EnvironmentFile 加载的 gitignored .orbi/env 文件。
• 部署：systemd/[email protected] 和 systemd/[email protected] 模板，及其 [email protected] 实例（N = max_concurrency，上限为 MAX_RUNNER_INSTANCES = 5）。
• **票内命令：**milestone 确认 Issue 上的 /milestone <标题> 评论 （Issue #1290）。
• 标签和生命周期：labels.toml 与 src/orbi/delivery_labels.py， 以及 ai-ready、ai-in-progress、ai-pr-opened、ai-fix-needed、 ai-merged、ai-blocked 状态机。
• **可观测性：**journal 每行以 [run_id] 开头，并使用 run_start、run_end、activity、heartbeat、resumed、run_failed 等稳定事件名，以及日志（journal）中记录的启动/恢复事件。 Pi 实时记录位于 <worktree>/.pi-session/*.jsonl。
• **交付命名和标记：**稳定的任务分支是 orbi/<owner>-<repo>-issue-<N>；带 run 的 worktree 目录是 .worktrees/orbi-<owner>-<repo>-issue-<N>-<run_id>。Issue/PR 评论和 PR body 使用 <!-- orbi:run=<run_id> --> 及可见的 run_id=<run_id>；PR body 还必须包含 Fixes #<N>。

​

Worktree 与 base 新鲜度

​

任务 worktree 回收（Issue #760）

​

远端交付分支回收（Issue #1479）

​

故障恢复

​

Run 卡在 session_pending：首个模型请求发出前挂死（Issue #311）

PID=<journal `process_spawned` 行里的 pid，或 `pgrep -f pi`>

# 1. 活着但空闲：state S、~0% CPU、epoll 空转
ps -o pid,stat,%cpu,wchan:32 -p "$PID"

# 2. 没有任何到模型 API 的 TCP 连接——请求从未发出
ss -tnp | grep "$PID"                    # 空

# 3. 唯一的 socket 是 D-Bus
ls -l /proc/"$PID"/fd | grep socket      # unix socket -> /run/user/1000/bus

# 4. session 文件从未创建
ls -la <任务 worktree>/.pi-session/      # 空

• first_response）。永久修复是 Issue #249——orbi 自声明 extensions （[[pi_extensions]]）并以 --no-extensions 启动 Pi，用户级插件从此 无法泄漏进无人值守会话。上游：向 pi-mcp-adapter 报 bug（无 MCP server 配置时不应硬初始化 keyring，或改惰性初始化）。

​

并发