docs(ops): record agentctl-macos verification and head_sha
This commit is contained in:
WeiCHEN
@@ -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/<pid>/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。
|
||||
|
||||
## 相关链接
|
||||
|
||||
|
||||
Reference in New Issue
Block a user