Agent-System/.doc/remediation/2026-09-23-coordination-db-daemon-phased-plan.md

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

title	status	created	updated	owner	task_id	task_type	task_tier	policy_revision	branch	worktree	base_dev_sha	write_scope	allowed_environments	mutex	review_state	integration_state	deployment	cleanup	cleanup_owner	remote_sync
协调库与 daemon：分阶段设计与实施方案	planned	2026-09-23	2026-09-23	Cursor	coordination-db-daemon-2026-09-23	research	multi_stage	agent-governance-2026-09-21-r1 @ 63e66c6fb3	feature/coordination-db-daemon-2026-09-23	.worktrees/coordination-db-daemon-2026-09-23	63e66c6fb3	.doc		coordination-db-daemon	pending	pending	not_required	pending	独立维护者	not_requested

协调库与 daemon：分阶段设计与实施方案

本文件是方案文档（planned），不含 daemon/PostgreSQL 实施。配套 研究依据。上位约束：锁协调方案、操作规范、平台深化方案 §0。

0. 用户目标与授权

• 用户目标：统一认领、状态与执行入口；文档逐步变为状态输出；为多主机协作预留结构。
• 交付形态（已确认）：研究 + 方案；不实施数据库或 daemon。
• 边界（已确认）：分阶段——L1 单宿主机内（daemon + 现有 SQLite）；跨机 PostgreSQL 仅登记为 planned 的 L2，需二次授权与 ADR。
• 并行授权：修掉 agentctl queue 子解析器重复注册（已合入本地 63e66c6f）。

1. 现状基线（纠正摘要偏差）

摘要原说法	实测
SQLite 管理「部分」协调状态	.locks/state.sqlite 已是权威库（11 表；采样 tasks≈105 / runs≈653 / events≈1406）
非容器用 systemd	本机 Darwin；仓库内 systemd/launchd/协调 compose 0 个
任务注册无长期排他认领	属实：缺显式 claim；scope/lease 已有
文档 3f14d7fa 已合入	不存在；本轮重新落地

已成立能力（不推倒）：scripts/agentctl.py 的 scope、flock 租约、三值进程存活、docs CAS+收据、候选准入、--ff-only、hooks；.git/agent-control/dev-integration.lock 与 .locks/os/dev-integration.lock 同 inode。

关键缺口：长期 claim、常驻协调入口、configs/agent-governance.yaml、CURRENT/MATRIX 稳定 record id、queue/jobs 运维闭环（parser 已修，行仍为 0）、agentctl_automation.py 分叉。

2. 目标架构

flowchart TB
  subgraph L1 [L1 单宿主机 本方案设计线]
    AG1[Agent 与工具调用] --> AC[agentctl CLI 统一入口]
    AC --> DB[(.locks/state.sqlite 权威库)]
    AC --> OS[.locks/os flock 稳定锁]
    CO[常驻协调入口 launchd 本机] --> DB
    CO --> PUB[docs apply 收据化发布]
    AC --> GI[git:dev 候选验证与 ff-only]
  end
  subgraph L2 [L2 跨机 仅 planned 需 ADR]
    HA[主机 A 执行代理] --> CD[中央协调 daemon]
    HB[主机 B 执行代理] --> CD
    CD --> PG[(独立 PostgreSQL)]
    CD --> EXH[指定主机执行 Git 集成与部署]
  end
  L1 -.->|L1 验收后另立 ADR| L2

三种关系（协议核心）

机制	作用	今日状态
scope	智能体允许修改哪些路径/能力	tasks.scopes + check_resources，已 enforced
claim	某项工作当前由谁长期负责	缺失；CURRENT 手工行不是原子认领
lease	谁正在操作某资源	Lease + flock + 存活核验，已 enforced

认领在短事务中完成：检查权限、冲突、冻结、公平排队、登记归属、写审计——全成或全拒。冲突返回持有者、队列票据与 retry_after。

执行安全不能只靠数据库锁。 TTL/心跳过期只进入 suspect/quarantine，不立即把资源交给下一个智能体；须核验旧进程与外部操作结果后再交接（见 U7）。

3. L1 七个实施单元

每单元另建 short-term + mutex + 验收 + 回退；合入 local_dev 串行占 git:dev。

U1 缺陷收敛与实现归一

项	状态
queue 子解析器重复注册	已修复并合入 63e66c6fb35d6b4dd9f3ed92e15acc9933aeb344（删后注册块；保留 --head / cancel --task / schedule --drain；回归 3 例；unittest 103/2 skipped PASS）
scripts/agentctl_automation.py 零导入、schema 分叉	planned：收敛到 W4 或按记录删除
.locks/state.db 0 字节孤儿	planned：确认无引用后清理（运行态，不入 Git）

U2 治理策略外部化

新建 tracked configs/agent-governance.yaml（今日不存在），收敛 SHARED_DOCS、PROJECTABLE_DOCS、JOB_KINDS、protocol/policy 版本；fail-closed 加载；旧客户端低于最小协议版本拒写。

U3 显式长期认领 claim

在 SQLite 增加 claim 表/字段（或等价资源键），与 scope/lease 分离。BEGIN IMMEDIATE 短事务内：权限、父子路径重叠、冻结、公平排队、审计。不同资源可并行。不把 Markdown idle 当作原子锁。

U4 常驻协调入口（本机）

• macOS：launchd plist（本机默认）。
• Linux：systemd unit。
• 单实例：.locks/os/manager.lock（2026-09-21 方案已规划、今日不存在）。
• 职责：驱动 queue schedule、文档投影发布、心跳过期扫描；不新增权限。
• 不可用时：阻止受保护写入，不静默放行。

U5 CURRENT 状态输出化

• ## 并行认领 / 集成槽位：稳定 record id + docs project 生成；人工「焦点 / 受控约束」保留。
• 同批修正：CURRENT.md:5 与 :15 自相矛盾；操作规范 :3「Linux 本机」过时描述。
• 发布仍走 docs apply CAS + 收据 + hook。

U6 FEATURE-MATRIX 分阶段迁移

27 模块行加稳定 record id 与结构化状态字段；保留声明范围、审核与证据。done 仍需 docs:approve + 已提交证据路径；不因任务结束或锁释放自动升 done。production_ready 仍只由发布门禁判定。任务完成 ≠ 能力完成 ≠ 发布就绪。

U7 执行代理与安全交接

固化：suspect → quarantine → 核验（supervisor/子进程组消失、物理锁可得、外部结果核对）→ 交接。复用并加强 recover；补 fencing generation 与 env/git 收据。Git 集成与共享环境部署集中主目录执行入口（queue_schedule 已限主 dev）；保留 flock、候选准入、--ff-only。数据库管记录与授权，执行入口防实际双写。

4. L2 登记（planned，不开工）

前置条件：用户二次授权 + ADR 覆盖锁方案 §3.2 与平台深化 §0。

登记内容：中央独立 PostgreSQL（独立配置/数据目录/备份，不依赖产品容器）；中央协调 daemon；各主机执行代理；指定执行主机做 Git 集成与部署；systemd 开机启动与异常重启；单中央节点故障时暂停受保护写入。

待执行验收（不得冒充已测）：真实双主机并发、断网、旧进程存活、重复 request_id、备份恢复。systemd 能恢复进程，不能替代主机容灾与数据库备份。

5. 文档与状态模型

内容	归属
任务归属、进度、队列、执行状态	数据库（权威）
CURRENT 运行表格	逐步自动生成；人工焦点/约束保留
FEATURE-MATRIX	分阶段结构化；证据与审核保留
规范、方案、验收报告正文	继续 Git 管理

6. 全局验收门

1. 每单元：受影响 unittest + 负例（冲突认领、旧 generation、daemon 停写）。
2. U3/U5/U6：双任务并行写不丢行、同行 CAS 冲突可见。
3. U4/U7：杀 supervisor 留子进程不得误抢；断心跳后须核验再交接。
4. L2：未授权不得实施；不得把 planned 写成 enforced。
5. 红线：不把 L1 宣称为 OS 沙箱；不依赖产品容器启动协调；不接触业务数据库。

7. 风险与回退

风险	控制
两套锁各自放行	延续 2026-09-21 §10 硬链接/双锁兼容；禁止静默第二锁根
daemon 扩大权限	只调度已授权操作；能力仍来自 task register
CURRENT 自动覆盖人工焦点	仅受控区块机器写；整文需 docs:admin
L2 提前开工	无 ADR 拒合入跨机代码
文档与运行态漂移	CURRENT 标明快照时间；以 doctor/status 核验

每单元独立 revert；迁移 additive；部署清单与代码分提交。

8. 与既有文档关系

• 本方案 = 2026-09-21 锁方案 的演进版：L1 补 claim/常驻入口/文档状态化；不推翻 SQLite 权威与 advisory 边界。
• 不替代 平台深化方案（产品可靠性/HA）；协调跨机另立 ADR。
• gap-matrix / FEATURE-MATRIX 状态不因本方案自动变更。

9. 开工准入（第一批实施前）

1. 每批 short-term + CURRENT 认领 + mutex。
2. 从当时 dev tip 建 worktree；重读 policy_revision。
3. L2 / 共享环境须单独授权。
4. 本文件保持 planned；首批实施时回填映射，不代填验收。