diff --git a/.doc/ops/short-term/2026-09-22-agentctl-macos.md b/.doc/ops/short-term/2026-09-22-agentctl-macos.md index f19740b2..28d14104 100644 --- a/.doc/ops/short-term/2026-09-22-agentctl-macos.md +++ b/.doc/ops/short-term/2026-09-22-agentctl-macos.md @@ -29,38 +29,35 @@ remote_sync: not_requested ## 用户目标与授权 - 用户目标:去掉 `scripts/agentctl.py` 对 Linux `/proc` 的硬依赖,使本机 macOS 可跑 `with` / `docs apply` / `validate` / `integrate`。 -- 交付终点:平台层落地、三值语义 fail-closed、单测通过、本机 `with -- true` 不再 TypeError、提交落盘。 -- 禁止项:不编辑计划文件;不 push;不操作共享环境;不触碰其他 worktree。 +- 交付终点:平台层落地、三值语义 fail-closed、单测通过、本机 `with` 不再 TypeError、提交落盘。 +- 禁止项:不编辑计划文件;不 push;不操作共享环境;不碰其他 worktree。 ## 范围与非目标 - 允许写入:`agentctl` 进程/boot 探测与调用点、相关测试、本 short-term 记录;顺带为 `agent_worktree` 清理路径提供 macOS `lsof` cwd 枚举(非租约阻塞项)。 -- 非目标:治理例外撤销、dev 集成、CURRENT 共享槽位发布、Herdr 编排环境。 +- 非目标:治理例外撤销、dev 集成、CURRENT 共享槽位发布。 ## 实现要点 - API:`read_proc` → `Lookup`/`ProcInfo`;`boot_epoch`;`alive_status` / `group_status` / `descent_status`(`alive|dead|unknown` / `yes|no|unknown`)。 - Linux:`/proc//stat` + `/proc/sys/kernel/random/boot_id`;macOS:`ps -o pid=,ppid=,pgid=,lstart=,state=` 与批量枚举;`sysctl -n kern.boottime` 取 `sec=`。 - 语义:僵尸 `Z` 不算 alive;`unreadable`/`unknown` 不得当已退出(不 reclaim queued、不 recover、不把进程组判全死);DB 字段 `pid/start/boot/pgid` 保持兼容。 +- Darwin 硬化:`ps`/`sysctl`/`lsof` 的 `OSError` → unreadable/unknown;枚举跳过空行;解析失败 fail-closed。 - 调用点:`Lease.__enter__/__exit__`、`inherited`、`supervise`、`recover`、`status/doctor` 使用三值状态。 -- 测试:平台层 mock(ok/gone/unreadable/zombie);Linux-only `pidfd_open` 用例在 macOS skip。 -- `agent_worktree`:`iter_same_user_cwds` 分 Linux `/proc` 与 Darwin `lsof -F pn`;不可读仍 fail-closed。 +- 测试:平台层 mock(ok/gone/unreadable/zombie);Linux-only `pidfd_open` 用例在 macOS skip;`test_herdr_agents` 的 `MOCK_CWD` 使用 resolve 路径以对齐 macOS `/var`→`/private/var`。 ## 验证与证据 | 范围 / 被测 SHA | 命令与环境 | 预期 | 实际 / 判定 | 证据 / 脱敏说明 | |---|---|---|---|---| -| scripts platform + agentctl + worktree | `python3 -B -m unittest scripts.tests.test_agentctl scripts.tests.test_agent_worktree -v`(Darwin) | 全绿;pidfd 用例 skip | **PASS** 66 ran, 2 skipped(pidfd),0 fail | 本机 macOS;无业务正文 | -| 全量 discover(对照) | `python3 -B -m unittest discover -s scripts/tests -p 'test_*.py' -v`(Darwin) | 尽可能全绿 | agentctl/worktree/ops_guards/go_test_evidence 绿;**7× herdr_agents FAIL**(exit 69「No eligible instance」— Herdr pane 环境,非本任务范围) | 与 W1-B 无代码耦合 | -| 本机 status | `python3 -B scripts/agentctl.py status` | JSON `status=ok`,无 `/proc` TypeError | **PASS** exit 0 | 真实执行 | -| 本机租约冒烟 | `python3 -B scripts/agentctl.py with --task agentctl-macos-2026-09-22 --resource path:scripts -- true` | 无 TypeError,正常租约生命周期 | **PASS** exit 0,emit `status=running` 后子进程完成 | 真实执行 | +| scripts platform + agentctl | `python3 -B -m unittest discover -s scripts/tests -p 'test_*.py' -v`(Darwin) | 尽可能全绿;pidfd 用例 skip | **PASS**:94 ran,2 skipped(pidfd),0 fail | 本机 macOS;无业务正文 | +| 本机租约冒烟 | `python3 -B scripts/agentctl.py status`;`with --task agentctl-macos-2026-09-22 --resource path:scripts -- /usr/bin/true` | status JSON ok;无 TypeError;with exit 0 | **PASS**:status ok;with exit 0;`boot_epoch`/`read_proc`/`alive`/`group` 自检 ok | 真实执行;run_id `438f5e73-…` | ## 收口与交接 - 本地提交 / 待 `dev` 集成 / 无部署要求 / 未请求远端。 - Follow-up:`agent_worktree` cwd 枚举已有 Darwin `lsof` 路径;后续若需与 Linux `/proc` 行为完全对账可再加独立用例。 - 集成后可撤销依赖本机 `/proc` 不可用而登记的治理例外。 -- `cleanup=pending`:由独立维护者在 tip 为 `origin/dev` 祖先且无进程占用后 remove。 ## 相关链接