Agent-System/.doc/ops/short-term/2026-09-22-agentctl-macos.md

title, task_id, status, created, updated, owner, task_type, task_tier, policy_revision, branch, worktree, base_dev_sha, write_scope, allowed_environments, head_sha, mutex, review_state, integration_state, deployment, cleanup, cleanup_owner, cleanup_trigger, remote_sync

title	task_id	status	created	updated	owner	task_type	task_tier	policy_revision	branch	worktree	base_dev_sha	write_scope	allowed_environments	head_sha	mutex	review_state	integration_state	deployment	cleanup	cleanup_owner	cleanup_trigger	remote_sync
agentctl macOS 进程平台层（W1-B）	agentctl-macos-2026-09-22	done	2026-09-22	2026-09-22	Cursor	implementation	small	AGENTS+worktree-ops @ 364ed7f1	feature/agentctl-macos-2026-09-22	.worktrees/agentctl-macos-2026-09-22	364ed7f1a3	scripts/agentctl.py scripts/agent_worktree.py scripts/tests/ .doc/ops/short-term/			agent-workflow-governance	pending	pending	not_required	pending	独立集成/维护执行者	tip 为 origin/dev 祖先且无进程使用后 remove	not_requested

agentctl macOS 进程平台层（W1-B）

用户目标与授权

• 用户目标：去掉 scripts/agentctl.py 对 Linux /proc 的硬依赖，使本机 macOS 可跑 with / docs apply / validate / integrate。
• 交付终点：平台层落地、三值语义 fail-closed、单测通过、本机 with 不再 TypeError、提交落盘。
• 禁止项：不编辑计划文件；不 push；不操作共享环境；不碰其他 worktree。

范围与非目标

• 允许写入：agentctl 进程/boot 探测与调用点、相关测试、本 short-term 记录；顺带为 agent_worktree 清理路径提供 macOS lsof cwd 枚举（非租约阻塞项）。
• 非目标：治理例外撤销、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；test_herdr_agents 的 MOCK_CWD 使用 resolve 路径以对齐 macOS /var→/private/var。

验证与证据

范围 / 被测 SHA	命令与环境	预期	实际 / 判定	证据 / 脱敏说明
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 不可用而登记的治理例外。

相关链接

• Plan：推进未完成条目全量计划（W1-B，勿改计划文件）
• 验证契约：.doc/ops/2026-09-21-validation-contract.md