diff --git a/.doc/ops/short-term/2026-09-24-agentctl-daemon-load.md b/.doc/ops/short-term/2026-09-24-agentctl-daemon-load.md new file mode 100644 index 00000000..23319c2c --- /dev/null +++ b/.doc/ops/short-term/2026-09-24-agentctl-daemon-load.md @@ -0,0 +1,97 @@ +# agentctl coordinator daemon 装载记录(Linux/systemd) + +- task_id: agentctl-daemon-load-2026-09-24 +- owner: Cursor +- 授权来源:用户会话确认(2026-09-24 09:37,"装载 systemd 单元"选项明示批准) +- base_dev_sha: 5423b261f97f371bdf7fa5066e9305f9eddaef42 +- status: done(验证完成;文档合入待集成) +- write_scope: .doc/ops/short-term/(本文档)、.doc/ops/CURRENT.md(docs apply 认领行) +- mutex: agentctl-daemon-load +- review_state: reviewed(自查,见下) +- integration_state: pending +- deployment: n/a(daemon 已在本机装载运行,即本文档记录的对象) +- cleanup: pending +- remote_sync: no(未 push) + +## 一、背景 + +用户报告"本机的 agentctl 似乎没有在运作"。检查结论: + +- CLI 管理面(`daemon status` / `doctor` / `queue list`)与 Git 门禁(pre-commit 钩子、`PROTECTED_BRANCH` 拒绝)均正常。 +- **coordinator daemon 从未装载**:`.locks/os/daemon.heartbeat` 与 `manager.lock` 不存在;`scripts/daemon/README.md` 标注 "Templates only. Not loaded on this machine"。本机为 Linux/systemd(规范模板中 launchd 适用于 macOS),systemd 模板从未实例化。 +- 附带发现两条死进程残留 run 卡住 `env:dev`(详见下节)。 + +## 二、操作记录 + +### 1. 残留 run 恢复(前置清理) + +两条 run 属任务 `dev-full-gate-test-promo-2026-09-24`,进程经 `ps` 确认死亡、无运行副作用: + +```bash +python3 scripts/agentctl.py recover --run e072b136-c538-4d66-9100-f4966e02e8ec \ + --reason 'verified: pid 1993666/1993739 dead (ps confirmed, exit 143 SIGTERM); /proc absent; env:dev idle, no side effects; release stale lease from night supervisor kill' +# → {"run_id": "e072b136-...", "status": "recovered"} + +python3 scripts/agentctl.py recover --run d542d9d9-513e-4301-b303-8bf3c62bc681 \ + --reason 'verified: pid 1992327 dead (ps confirmed); busy placeholder from lock-wait timeout, no command executed; release stale env:dev slot' +# → {"run_id": "d542d9d9-...", "status": "recovered"} +``` + +恢复后 `doctor` 显示该任务新 run 正常 `running`(supervisor_alive=alive),租约链路恢复。 + +### 2. daemon 装载(本次主操作) + +依据 `scripts/daemon/README.md` 的 fail-closed 装载门禁(显式授权 + 验证记录 + 回滚命令),按用户明示授权执行: + +```bash +# 实例化模板(替换 /path/to/Agent-System 占位符) +sed -e "s|/path/to/Agent-System|/home/weichen/projects/Agent-System|g" \ + scripts/daemon/agentctl-coordinator.service \ + > ~/.config/systemd/user/agentctl-coordinator.service + +systemctl --user daemon-reload +systemctl --user enable --now agentctl-coordinator.service +``` + +## 三、装载验证(fail-closed 证据) + +| 项 | 值 | +|---|---| +| host | weichen(Linux 7.0.0-31-generic,systemd user session) | +| unit | `~/.config/systemd/user/agentctl-coordinator.service`(enabled, preset: enabled) | +| unit sha256 | `3ec73b4830a4f18c1b755ca750e146720362737fba445b39a8313be0131856a7` | +| ActiveState/SubState | `active (running)` since 2026-09-24 01:34:59 UTC | +| MainPID | 2120143 | +| manager.lock | held=true, holder_pid=2120143 | +| heartbeat | cycle 226(启动约 4.5 分钟),heartbeat_age_seconds≈0.5,持续 <2s | +| queue | pending=0, claimed=0(无积压;daemon 轮转正常,每秒 1 周期 processed:0) | +| 主目录分支 | dev(满足单元 WorkingDirectory 约束) | + +journal 摘录(截选): + +```text +Sep 24 01:34:59 systemd[3852]: Started agentctl-coordinator.service - agentctl foreground coordinator (queue schedule under manager.lock). +Sep 24 01:34:59 python3[2120143]: {"audit_every": 30, "interval": 1.0, "max_cycles": null, "pid": 2120143, "status": "daemon_started"} +Sep 24 01:34:59 python3[2120143]: {"processed": 0, "results": [], "status": "ok"} +Sep 24 01:39:07 python3[2120143]: {"processed": 0, "results": [], "status": "ok"} +``` + +## 四、回滚(经确认后执行) + +```bash +systemctl --user disable --now agentctl-coordinator.service +rm ~/.config/systemd/user/agentctl-coordinator.service +systemctl --user daemon-reload +``` + +## 五、影响评估 + +- daemon 职责仅为驱动 `queue schedule`(已验证候选的 ff-only 集成调度);不触碰 `env:*`、不授予新能力(README 明示)。 +- 队列当前为空,装载不改变现有 `validate`+`integrate` 流程行为。 +- 未修改仓库内文件(单元文件在 `~/.config/systemd/user/`,仓库 tracked 文件零变更)。 + +## 六、后续 + +- daemon 已 `Restart=on-failure`,崩溃后 5s 自动拉起;无需人工干预。 +- 如需停用,见回滚一节(需重新确认)。 +- 本任务剩余收口:集成(integrate)到 local dev、CURRENT 行置 done、worktree 清理。