nexus/wiki/concepts/Sub-Agent-Race-Condition.md

title, type, tags, sources, last_updated

title	type	tags	sources	last_updated
Sub-Agent Race Condition	concept	multi-agent concurrency engineering-pitfall	overnight-mini-app-builder	2026-04-22

Definition

多子代理并发编辑共享文件时导致的竞态条件。当主会话和子代理同时尝试修改同一文件（如 AUTONOMOUS.md/Kanban 状态文件）时，由于 edit 工具要求精确的 oldText 匹配，子代理在主会话读取和编辑之间的窗口期内更新了文件内容，导致 oldText 失效，edit 操作静默失败。

Aliases

• Race Condition
• 并发编辑冲突
• Silent Edit Failure

Root Cause

OpenClaw 的 edit 工具依赖精确字符串匹配（exact oldText match）。在多 Agent 并发场景下：

1. 主会话读取文件 → 内存中为旧版本
2. 子代理修改同一文件 → 磁盘版本已更新
3. 主会话尝试 edit(oldText=旧版本) → 匹配失败 → 静默失败

Solution: Git-Style Append-Only Pattern

参考 Git 的"不重写历史"原则，将任务文件分为两类：

文件	角色	谁可写
AUTONOMOUS.md	状态文件（目标 + 开放待办）	仅主会话
memory/tasks-log.md	追加日志（已完成任务）	所有子代理（只追加）

# tasks-log.md — Completed Tasks (append-only)
# Sub-agents: always append to the END. Never edit existing lines.

### 2026-02-24
- ✅ TASK-001: Research competitors → research/competitors.md
- ✅ TASK-002: Draft blog post → drafts/post-1.md

子代理 spawn 指令中必须包含：

"When done, append a ✅ line to memory/tasks-log.md. Never edit AUTONOMOUS.md directly."

Key Relationships

• GitAsAuditLog — 本模式的概念来源，Git 的追加提交哲学
• SharedStateCoordination — 共享状态协调的通用概念
• overnight-mini-app-builder — 本模式的来源场景