dev-memory-cli 0.22.2 → 0.23.0

package/README.md

@@ -9,7 +9,7 @@ Dev Memory Skill Suite 为 Codex、Claude 等 coding agent 提供跨会话开发
 ## 核心能力
 
 - **会话恢复**：`SessionStart` 自动注入当前 repo + branch 的浓缩记忆和权威文件路径。
-- **语义化写入**：按 decision、risk、glossary、source、overview 等 kind 写入对应文件。
+- **后台语义沉淀**：定期读取完整会话，对照已有记忆后执行 append、rewrite、delete 或明确 skip。
 - **纠错优先**：修正旧记忆时定位并改写原 entry，避免同时保留互相冲突的新旧结论。
 - **分支隔离**：同一仓库的不同分支拥有独立工作记忆，可 fork、rename、reset 或归档。
 - **跨分支共享**：稳定规则进入 repo 层；候选知识可在分支完成时提炼上提。
@@ -17,17 +17,13 @@ Dev Memory Skill Suite 为 Codex、Claude 等 coding agent 提供跨会话开发
 - **多仓库工作区**：一个 workspace 下可同时加载多个 repo，并为主仓库保留更完整的上下文。
 - **本地管理面板**：浏览、编辑已存储记忆，预览 SessionStart 注入文本，并查看会话扫描与 token 用量。
 
-## 五个 Skill
+## 一个常驻 Skill
 
 | Skill | 职责 | 适用场景 |
 | --- | --- | --- |
 | `dev-memory-read` | 定位并搜索当前 repo/branch 的权威记忆，只读不写 | 主动恢复既有记忆、查询历史 TODO |
-| `dev-memory-capture` | 写入、改写或删除记忆；同步 Git 派生索引 | 稳定结论沉淀、纠错、阶段 checkpoint |
-| `dev-memory-setup` | 把 `unsorted.md` 中的内容分类合并到结构化文件 | 未分类内容整理、记忆结构初始化 |
-| `dev-memory-tidy` | 批量审查陈旧、重复、错误或模板残留条目，备份后应用 | 结构化记忆校准与清理 |
-| `dev-memory-graduate` | 提炼跨分支知识并归档已完成分支 | 分支收尾与归档 |
 
-Skill 定义触发语义与协作流程，文件操作统一由 `dev-memory-cli` 执行。
+普通开发会话不再常驻 capture/setup/tidy/graduate Skill。会话写入由 session-scan 后台处理；整理和归档由 CLI 临时启动专用维护 Agent，并只把对应维护 prompt 放进那个独立会话。
 
 ## 安装
 
@@ -44,13 +40,13 @@ npx skills add xluos/dev-memory-skill-suite --list
 安装到 Codex 全局：
 
 ```bash
-npx skills add xluos/dev-memory-skill-suite --skill '*' -a codex -g -y
+npx skills add xluos/dev-memory-skill-suite --skill dev-memory-read -a codex -g -y
 ```
 
 安装到检测到的所有 agent：
 
 ```bash
-npx skills add xluos/dev-memory-skill-suite --all -g -y
+npx skills add xluos/dev-memory-skill-suite --skill dev-memory-read --all -g -y
 ```
 
 ### 安装 CLI 与 Hook
@@ -81,31 +77,27 @@ dev-memory-cli session-scan install
 dev-memory-cli session-scan status
 ```
 
-扫描任务默认在本地时间 03:00 运行。`install-hooks codex` 只安装 CLI hook，不会隐式安装定时任务。
+扫描任务默认在本地时间 03:00 和 13:00 运行，时间列表可配置。LaunchAgent 触发时会读取 macOS HID 空闲时长；最近 10 分钟有键鼠输入则记录 `skipped_active` 并退出，不扫描文件或调用模型。活跃检测失败时默认保守跳过。手工执行 `session-scan run` 不受该检测影响。`install-hooks codex` 只安装 CLI hook，不会隐式安装定时任务。
 
 ## 基本使用
 
-写入操作具备 lazy initialization。存储骨架缺失时自动创建，setup 不作为写入前置条件。
+记忆是显式 opt-in。首次使用先初始化，然后由生命周期 hook 恢复、由定期 session-scan 沉淀新会话语义。
 
 ```bash
+# 为当前 repo + branch 初始化记忆骨架
+dev-memory-cli init
+
 # 查看当前仓库和分支对应的记忆路径
 dev-memory-cli read show
 
 # 只在当前 repo 的记忆范围内搜索
 dev-memory-cli read search --query "发布流程" --query "回滚"
 
-# 写入一条分支决策
-dev-memory-cli capture record \
-  --kind decision \
-  --content "发布前必须先跑完整打包检查"
-
-# 写入一条跨分支规则
-dev-memory-cli capture record \
-  --kind shared-decision \
-  --content "Python 测试优先使用项目虚拟环境"
+# 启动独立整理 Agent（不会把整理 prompt 放进普通开发会话）
+dev-memory-cli maintain tidy
 
-# 刷新 Git working tree 派生的文件索引
-dev-memory-cli capture sync-working-tree
+# 启动独立归档 Agent
+dev-memory-cli maintain archive --branch feature/example
 ```
 
 `read search` 默认搜索当前 branch + repo 共享层。跨分支和归档范围通过 `--scope` 显式指定：
@@ -115,11 +107,11 @@ dev-memory-cli read search --scope all-branches --query "关键词"
 dev-memory-cli read search --scope archived --query "关键词"
 ```
 
-### 写入路由
+### 底层写入路由
 
 ![Capture 写入路由](docs/diagrams/capture.png)
 
-`capture record` 支持三种输入方式：
+`capture` 是 session-scan 和维护 Agent 使用的底层写入引擎，同时保留为高级管理 CLI；它不再对应常驻 Skill。`capture record` 支持三种输入方式：
 
 - **显式 kind**：调用方明确指定内容语义，直接写目标 section。
 - **自动分类**：`--auto` 根据文本信号判断 decision、risk、glossary；无法明确分类时进入 `unsorted.md`。
@@ -150,19 +142,18 @@ dev-memory-cli capture rewrite-entry --id <entry-id> --content "修正后的完
 dev-memory-cli capture delete-entry --id <entry-id>
 ```
 
-符合跨分支复用判定的内容会同时进入 `pending-promotion.md`，由 graduate 在分支收尾阶段审核；候选内容不会直接写入 repo 共享层。
+符合跨分支复用判定的内容会同时进入 `pending-promotion.md`，由归档维护 Agent 在分支收尾阶段审核；候选内容不会直接写入 repo 共享层。
 
 ### 整理与归档
 
-三个维护动作边界不同：
+普通入口只有两个，都会启动独立交互式 Agent：
 
-| 动作 | 处理对象 | 结果 |
+| 命令 | 处理对象 | 结果 |
 | --- | --- | --- |
-| `setup` | `unsorted.md` 中尚未分类的内容 | 合并到 decisions、risks、glossary 或 repo 共享层 |
-| `tidy` | 已结构化但陈旧、重复或错误的内容 | proposal 审核，备份后 edit/delete/reset |
-| `graduate` | 已完成分支的有效记忆 | 上提跨分支知识，并把分支目录移入 `_archived` |
+| `dev-memory-cli maintain tidy` | `unsorted.md` 与已结构化但漂移的内容 | 分类、proposal HTML 审核、备份后 edit/delete/reset |
+| `dev-memory-cli maintain archive` | 已完成分支的有效记忆 | dry-run、上提跨分支知识、确认后移入 `_archived` |
 
-`tidy apply` 和 `graduate apply` 会改变或移动已有记忆，仅在显式调用后执行。
+维护 Agent 内部使用 `setup`、`tidy`、`graduate` 等低层子命令。`tidy apply` 和 `graduate apply` 会改变或移动已有记忆，仍然受人工审核和显式确认门禁保护。用 `--print-prompt` 可以只查看将传给独立 Agent 的完整维护指令。
 
 ### 分支记忆操作
 
@@ -223,11 +214,19 @@ dev-memory-cli session-scan run --dry-run --json
 dev-memory-cli session-scan run
 dev-memory-cli session-scan stats --json
 dev-memory-cli session-scan history --limit 20
+dev-memory-cli session-scan replay --run-id <run-id> --session-id <session-id> [--session-id <session-id> ...] [--executor codex]
 dev-memory-cli session-scan config show
 dev-memory-cli session-scan config set-executor codex
 dev-memory-cli session-scan config set-model codex <model>
+dev-memory-cli session-scan config set-schedule 03:00 13:00
+dev-memory-cli session-scan config set-active-minutes 10
+dev-memory-cli session-scan config set-timeout 360
 ```
 
+已安装定时任务时，`set-schedule` 会自动重载 LaunchAgent，使新的时间列表立即生效。
+
+`replay` 会按历史 run 记录的 `cursor_before` / `cursor_after` 精确重放指定会话，不回退当前会话游标；`--executor` 只覆盖本次运行，不修改持久配置。单分块会话只调用一次模型；最终结果必须包含至少一个记忆变更，或提供非空 `skip_reason`。空对象、只有 `title`、以及没有产生语义 action 且未说明原因的结果都会标记失败并保留重试空间。单次模型调用默认 360 秒超时，超时不会立即重试。run 账本会记录输出字段计数、`skip_reason`、payload 哈希、有效/观测字节数和语义 action 数，不保存原始总结正文。
+
 ## 运行模式
 
 | 模式 | 检测条件 | 行为 |
@@ -243,7 +242,7 @@ dev-memory-cli workspace show
 dev-memory-cli workspace primary <repo-basename>
 ```
 
-`DEV_MEMORY_PRIMARY_REPO` 可作为临时 override。Skill 在 workspace 中写入时应使用 `--repo <repo-path-or-basename>` 明确目标仓库。
+`DEV_MEMORY_PRIMARY_REPO` 可作为临时 override。维护命令在 workspace 中应使用 `--repo <repo-path-or-basename>` 明确目标仓库。
 
 ## 存储结构
 
@@ -319,6 +318,9 @@ dev-memory-cli context injection-preview \
 
 ```text
 dev-memory-cli read <show|search>
+dev-memory-cli init [--repo PATH] [--branch NAME]
+dev-memory-cli maintain <tidy|archive> [--repo PATH] [--branch NAME] [--executor auto|codex|coco]
+# low-level mutation/admin commands:
 dev-memory-cli capture <show|suggest-kind|classify|record|list-entries|find-candidates|rewrite-entry|delete-entry|apply-summary-output|sync-working-tree|record-head>
 dev-memory-cli setup <init|merge-unsorted|mark-completed>
 dev-memory-cli tidy <prepare|apply>
@@ -327,7 +329,7 @@ dev-memory-cli branch [list|inspect|rename|fork|delete|init|inherit-worktree-bas
 dev-memory-cli context <show|sync|injection-preview>
 dev-memory-cli workspace <show|primary>
 dev-memory-cli summary <extract-core>
-dev-memory-cli session-scan <run|install|status|stats|history|show|uninstall|config>
+dev-memory-cli session-scan <run|replay|install|status|stats|history|show|uninstall|config>
 dev-memory-cli hook <session-start|pre-compact|stop|session-end>
 dev-memory-cli ui
 dev-memory-cli install-hooks <codex|claude|--all>
@@ -352,11 +354,12 @@ dev-memory 的能力边界不包括：
 ```text
 bin/dev-memory.js              # CLI 入口与 Node 侧命令
 lib/dev_memory_*.py            # 记忆、分支、会话扫描、整理与归档实现
+lib/maintenance/               # 按需注入独立维护 Agent 的 prompt
 lib/ui-server.js               # 本地管理面板服务
 lib/ui-app.html                # 管理面板前端
 scripts/hooks/                 # 生命周期 hook 实现
 hooks/                         # Codex / Claude hook 模板
-skills/                        # 五个 skill 的声明与工作流
+skills/dev-memory-read/        # 唯一常驻 Skill
 tests/                         # Python 测试
 docs/diagrams/                 # README 图表及源文件
 ```

package/bin/dev-memory.js

@@ -376,6 +376,112 @@ function commandPySubcommand(name, rawArgs) {
   runPython(scriptPath, rawArgs);
 }
 
+const MAINTENANCE_MODES = new Set(["tidy", "archive"]);
+const MAINTENANCE_MARKER = "DEV_MEMORY_INTERNAL_MAINTENANCE_AGENT_V1";
+
+function maintenanceHelp() {
+  process.stdout.write(`Usage:
+  dev-memory-cli maintain tidy [--repo PATH] [--branch NAME] [--scope branch|branch+repo]
+                                  [--executor auto|codex|coco] [--model MODEL]
+  dev-memory-cli maintain archive [--repo PATH] [--branch NAME]
+                                     [--executor auto|codex|coco] [--model MODEL]
+  dev-memory-cli maintain <tidy|archive> --print-prompt [other options]
+
+The command starts a dedicated interactive maintenance-agent session. Tidy
+must not apply destructive changes before HTML review; archive must not apply
+before dry-run review and explicit confirmation.
+`);
+}
+
+function resolveMaintenanceExecutor(requested) {
+  const name = requested || process.env.DEV_MEMORY_MAINTENANCE_EXECUTOR || "auto";
+  if (!new Set(["auto", "codex", "coco"]).has(name)) {
+    fail(`unsupported maintenance executor: ${name}`);
+  }
+  if (name !== "auto") return name;
+  for (const candidate of ["codex", "coco"]) {
+    if (commandExists(candidate)) return candidate;
+  }
+  fail("no maintenance executor found; install codex/coco or use --print-prompt");
+}
+
+function buildMaintenancePrompt(mode, options, repoRoot) {
+  const promptPath = packageScript("lib", "maintenance", `${mode}.md`);
+  if (!fs.existsSync(promptPath)) fail(`missing maintenance prompt: ${promptPath}`);
+  const workflow = fs.readFileSync(promptPath, "utf8").trim();
+  const cliPath = path.resolve(process.argv[1]);
+  const branch = options.branch || "<current-git-branch>";
+  const scope = mode === "tidy" ? (options.scope || "branch") : "branch";
+  return `${MAINTENANCE_MARKER}
+
+你是 dev-memory 的专用维护 Agent。本会话只处理下面指定仓库的记忆维护，不承担普通开发任务。
+
+目标仓库：${repoRoot}
+目标分支：${branch}
+维护模式：${mode}
+整理范围：${scope}
+本次必须使用的 CLI：node ${JSON.stringify(cliPath)}
+
+不要依赖全局 dev-memory capture/setup/tidy/graduate Skill；完整维护流程已经随本提示提供。
+涉及删除、改写或归档时，必须遵守下面流程中的人工审核和确认门禁。
+
+${workflow}
+`;
+}
+
+function commandMaintain(rawArgs) {
+  const mode = rawArgs[0];
+  if (!mode || mode === "--help" || mode === "-h") {
+    maintenanceHelp();
+    return;
+  }
+  if (!MAINTENANCE_MODES.has(mode)) {
+    fail(`unknown maintenance mode: ${mode}`);
+  }
+  const { positional, options } = parseArgs(rawArgs.slice(1));
+  if (positional.length) fail(`unexpected maintenance argument: ${positional[0]}`);
+  const repoRoot = path.resolve(options.repo || process.cwd());
+  if (!fs.existsSync(repoRoot) || !fs.statSync(repoRoot).isDirectory()) {
+    fail(`maintenance repo does not exist: ${repoRoot}`);
+  }
+  if (mode === "tidy" && options.scope && !new Set(["branch", "branch+repo"]).has(options.scope)) {
+    fail(`unsupported tidy scope: ${options.scope}`);
+  }
+  const prompt = buildMaintenancePrompt(mode, options, repoRoot);
+  if (options["print-prompt"] || options["dry-run"]) {
+    process.stdout.write(prompt);
+    return;
+  }
+
+  const executor = resolveMaintenanceExecutor(options.executor);
+  let args;
+  if (executor === "codex") {
+    const modelArgs = options.model ? ["--model", String(options.model)] : [];
+    args = [
+      "-C", repoRoot,
+      "--sandbox", "danger-full-access",
+      "--ask-for-approval", "on-request",
+      "--dangerously-bypass-hook-trust",
+      ...modelArgs,
+      prompt,
+    ];
+  } else {
+    const modelArgs = options.model ? ["--config", `model=${String(options.model)}`] : [];
+    args = ["--permission-mode", "default", ...modelArgs, prompt];
+  }
+  const result = spawnSync(executor, args, {
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      DEV_MEMORY_MAINTENANCE_AGENT: "1",
+      DEV_MEMORY_MAINTENANCE_MODE: mode,
+    },
+    stdio: "inherit",
+  });
+  if (result.error) fail(`unable to start ${executor}: ${result.error.message}`);
+  if (result.status !== 0) process.exit(result.status || 1);
+}
+
 function branchScript() {
   return packageScript("lib", "dev_memory_branch.py");
 }
@@ -692,8 +798,11 @@ function printHelp() {
   dev-memory-cli install-hooks --all [--repo PATH] [--global]
   dev-memory-cli ui [--port N] [--host HOST] [--no-open] [--read-only]
   dev-memory-cli workspace <show|primary> [...]
+  dev-memory-cli init [--repo PATH] [--branch NAME]
   dev-memory-cli read <show|search> [...]
+  dev-memory-cli maintain <tidy|archive> [...]   # starts a dedicated interactive agent
   dev-memory-cli context <show|...> [...]
+  # Low-level mutation/admin commands used by session-scan and maintenance agents:
   dev-memory-cli capture <record|show|sync-working-tree|record-head|suggest-kind|classify> [...]
   dev-memory-cli setup <init|merge-unsorted|mark-completed> [...]
   dev-memory-cli graduate <dry-run|apply|index> [...]
@@ -719,6 +828,14 @@ function main() {
     commandPySubcommand(command, argv.slice(1));
     return;
   }
+  if (command === "init") {
+    commandPySubcommand("setup", ["init", ...argv.slice(1)]);
+    return;
+  }
+  if (command === "maintain") {
+    commandMaintain(argv.slice(1));
+    return;
+  }
   if (command === "branch") {
     commandBranch(argv.slice(1));
     return;

package/hooks/README.md

@@ -130,7 +130,9 @@ dev-memory-cli session-scan install
 dev-memory-cli session-scan status
 ```
 
-任务默认每天本地时间 03:00 运行。首次扫描只回看最近 3 天；后续使用持久化字节游标补扫上次成功处理后产生的全部数据。`install-hooks codex` 与 `session-scan install` 相互独立。
+任务默认每天本地时间 03:00 和 13:00 运行。LaunchAgent 使用 `session-scan run --scheduled`，运行前检查 macOS HID 空闲时长；最近 10 分钟有键鼠输入时写入 `skipped_active` 记录并退出，不读取会话正文、不调用模型。检测不可用时默认保守跳过。手工执行 `session-scan run` 不启用活跃检测。
+
+首次扫描只回看最近 3 天；后续使用持久化字节游标补扫上次成功处理后产生的全部数据。`install-hooks codex` 与 `session-scan install` 相互独立。
 
 扫描器只提取尚未处理的 user/assistant 语义消息，不限制消息数量，也不截断单条消息。材料超过单次模型上下文时按顺序分块，每个分块都进入中间摘要，再结合现有 memory 生成最终结构化结果。游标只在最终结果成功应用后推进。
 
@@ -143,6 +145,10 @@ dev-memory-cli session-scan status
   "session_scan": {
     "executor": "auto",
     "order": ["coco", "codex", "claude"],
+    "schedule_times": ["03:00", "13:00"],
+    "skip_when_computer_active": true,
+    "active_within_minutes": 10,
+    "activity_check_fail_closed": true,
     "chunk_chars": 60000,
     "idle_minutes": 60,
     "first_lookback_days": 3,
@@ -162,9 +168,14 @@ dev-memory-cli session-scan config show
 dev-memory-cli session-scan config set-executor codex
 dev-memory-cli session-scan config set-model codex <model>
 dev-memory-cli session-scan config set-profile codex <profile>
+dev-memory-cli session-scan config set-schedule 03:00 13:00
+dev-memory-cli session-scan config set-active-minutes 10
+dev-memory-cli session-scan config set-active-check on
 dev-memory-cli session-scan config validate
 ```
 
+已安装定时任务时，`set-schedule` 会自动重载 LaunchAgent；活跃阈值和开关由每次运行动态读取，无需重装。
+
 `auto` 只在命令不存在或 preset 被禁用时选择下一个执行器。模型调用失败不会自动换供应商，以免重复产生不可控费用。
 
 ### 递归防护

package/lib/dev_memory_capture.py

@@ -16,9 +16,11 @@ Subcommands:
 
 import argparse
 import difflib
+import fcntl
 import json
 import os
 import sys
+from contextlib import contextmanager
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
@@ -27,6 +29,7 @@ from dev_memory_common import (
     AUTO_END,
     AUTO_START,
     PLACEHOLDER_MARKERS,
+    atomic_write_text,
     append_log_event,
     append_to_section,
     asset_paths,
@@ -34,6 +37,7 @@ from dev_memory_common import (
     collect_git_facts,
     ensure_branch_paths_exist,
     get_head_commit,
+    get_branch_paths,
     get_setup_completed,
     is_cross_branch_candidate,
     join_sections,
@@ -140,7 +144,7 @@ def _append_with_separator(path, title, body, *, enforce_limit=True, max_entries
             else (body_stripped, 0)
         )
         updated.append((title, bounded))
-    path.write_text(join_sections(prefix, updated), encoding="utf-8")
+    atomic_write_text(path, join_sections(prefix, updated))
     return pruned
 
 
@@ -770,7 +774,7 @@ def _entry_mutation(paths, eid, *, new_text=None, delete=False):
 
     new_sections = list(sections)
     new_sections[section_idx] = (section_title, new_body)
-    target_path.write_text(join_sections(prefix, new_sections), encoding="utf-8")
+    atomic_write_text(target_path, join_sections(prefix, new_sections))
     return {
         "id": eid,
         "file_key": file_key,
@@ -1100,7 +1104,7 @@ def _prune_repo_shared_section(path, section_title, *, max_entries, max_entry_ch
         updated.append((existing_title, new_body))
     if not changed:
         return None
-    path.write_text(join_sections(prefix, updated), encoding="utf-8")
+    atomic_write_text(path, join_sections(prefix, updated))
     return result
 
 
@@ -1168,7 +1172,7 @@ def prune_bounded_memory(paths, *, max_entries=None):
                     "max_entries": max_entries,
                 })
         if changed:
-            path.write_text(join_sections(prefix, updated), encoding="utf-8")
+            atomic_write_text(path, join_sections(prefix, updated))
     return touched
 
 
@@ -1278,6 +1282,8 @@ def _decision_content(item):
     if isinstance(item, str):
         return item.strip()
     if isinstance(item, dict):
+        if not _decision_summary(item):
+            return ""
         return decision_body(item)
     return ""
 
@@ -1962,6 +1968,45 @@ def command_apply_summary_output(args):
             "reason": item.get("reason"),
         })
 
+    # Repair schema placeholder prose left by malformed historical summary
+    # output. Valid entries are top-level bullets; these exact unbulleted
+    # words are generator scaffolding and should never survive in memory.
+    placeholder_words = {
+        "decision", "summary", "reason", "impact", "risk", "mitigation",
+        "term", "definition", "name", "url", "note", "label", "path", "content",
+    }
+    for file_key in ("decisions", "risks", "glossary", "repo_glossary"):
+        path = paths[file_key]
+        if not path.exists():
+            continue
+        content = path.read_text(encoding="utf-8")
+        prefix, sections = split_sections(content)
+        updated = []
+        removed = 0
+        for section_title, section_body in sections:
+            kept_lines = []
+            section_removed = 0
+            for line in section_body.splitlines():
+                stripped = line.strip().strip(":：").lower()
+                is_bullet = line.lstrip().startswith(("- ", "* ", "+ "))
+                if stripped in placeholder_words and not is_bullet:
+                    section_removed += 1
+                    continue
+                kept_lines.append(line)
+            if section_removed:
+                rec = {
+                    "file": _label(file_key),
+                    "section": section_title,
+                    "mode": "remove-placeholder-orphans",
+                    "removed": section_removed,
+                }
+                touched.append(rec)
+                actions.append({"op": "remove-placeholder-orphans", **rec})
+                removed += section_removed
+            updated.append((section_title, "\n".join(kept_lines).strip()))
+        if removed:
+            atomic_write_text(path, join_sections(prefix, updated))
+
     bounded = prune_bounded_memory(paths)
     if bounded:
         touched.extend(bounded)
@@ -2177,6 +2222,20 @@ def _add_common_args(parser):
     parser.add_argument("--branch", help="Branch name. Defaults to the current checked-out branch")
 
 
+@contextmanager
+def _repo_command_lock(args):
+    """Serialize capture commands per repo so read-modify-write stays coherent."""
+    _, _, _, _, _, repo_dir, _ = get_branch_paths(args.repo, args.context_dir, args.branch)
+    lock_path = repo_dir / "jobs" / "capture.lock"
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with lock_path.open("a+", encoding="utf-8") as lock_stream:
+        fcntl.flock(lock_stream.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(lock_stream.fileno(), fcntl.LOCK_UN)
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="Unified write entrypoint for dev-memory repo+branch memory (merges old sync + update).",
@@ -2297,7 +2356,11 @@ def main():
             "sync-working-tree": command_sync_working_tree,
             "record-head": command_record_head,
         }
-        return handlers[args.command](args)
+        handler = handlers[args.command]
+        if args.command == "suggest-kind":
+            return handler(args)
+        with _repo_command_lock(args):
+            return handler(args)
     except Exception as exc:
         print(json.dumps({"error": str(exc)}, ensure_ascii=False), file=sys.stderr)
         return 1

package/lib/dev_memory_common.py

@@ -6,6 +6,7 @@ import os
 import re
 import shutil
 import subprocess
+import tempfile
 import time
 import uuid
 from collections import Counter
@@ -511,11 +512,29 @@ def asset_paths(repo_dir, branch_dir):
 
 def ensure_file(path, content):
     if not path.exists():
-        path.write_text(content, encoding="utf-8")
+        atomic_write_text(path, content)
+
+
+def atomic_write_text(path, content):
+    """Atomically replace a UTF-8 text file without exposing partial bytes."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    mode = (path.stat().st_mode & 0o777) if path.exists() else 0o644
+    fd, tmp_name = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
+    tmp_path = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.chmod(tmp_path, mode)
+        os.replace(tmp_path, path)
+    finally:
+        tmp_path.unlink(missing_ok=True)
 
 
 def write_json(path, payload):
-    path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    atomic_write_text(path, json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
 
 
 def read_json(path):
@@ -1705,7 +1724,7 @@ def ensure_progress_auto_block(path):
     else:
         updated = content.rstrip() + auto_section
 
-    path.write_text(updated + ("" if updated.endswith("\n") else "\n"), encoding="utf-8")
+    atomic_write_text(path, updated + ("" if updated.endswith("\n") else "\n"))
     return path.read_text(encoding="utf-8")
 
 
@@ -1762,7 +1781,7 @@ def upsert_markdown_section(path, title, body):
             updated.append((existing_title, existing_body))
     if not replaced:
         updated.append((title, body))
-    path.write_text(join_sections(prefix, updated), encoding="utf-8")
+    atomic_write_text(path, join_sections(prefix, updated))
 
 
 def _section_is_placeholder_only(text):
@@ -1822,7 +1841,7 @@ def append_to_section(path, title, body, *, max_entries=None):
     if not matched:
         bounded, _pruned = limit_markdown_entries(body.strip(), max_entries=max_entries)
         updated.append((title, bounded))
-    path.write_text(join_sections(prefix, updated), encoding="utf-8")
+    atomic_write_text(path, join_sections(prefix, updated))
 
 
 def upsert_progress_section(path, title, body):
@@ -1849,7 +1868,7 @@ def upsert_progress_section(path, title, body):
     if not replaced:
         updated.append((title, body))
     rewritten = join_sections(prefix, updated).rstrip() + "\n\n" + marker + after
-    path.write_text(rewritten, encoding="utf-8")
+    atomic_write_text(path, rewritten)
 
 
 def sync_progress(paths, facts):
@@ -1864,7 +1883,7 @@ def sync_progress(paths, facts):
     )
     current = ensure_progress_auto_block(paths["progress"])
     updated = replace_auto_block(current, build_auto_block(facts))
-    paths["progress"].write_text(updated, encoding="utf-8")
+    atomic_write_text(paths["progress"], updated)
 
 
 # ---------------------------------------------------------------------------
@@ -1918,7 +1937,7 @@ def append_log_event(log_path, action, *, kind=None, summary=None, details=None)
         return
     if not log_path.exists():
         log_path.parent.mkdir(parents=True, exist_ok=True)
-        log_path.write_text(template_log("unknown"), encoding="utf-8")
+        atomic_write_text(log_path, template_log("unknown"))
 
     header_parts = [f"## [{now_iso()}] {action}"]
     if kind:
@@ -1938,7 +1957,7 @@ def append_log_event(log_path, action, *, kind=None, summary=None, details=None)
     existing = log_path.read_text(encoding="utf-8")
     if not existing.endswith("\n"):
         existing += "\n"
-    log_path.write_text(existing + "\n" + block, encoding="utf-8")
+    atomic_write_text(log_path, existing + "\n" + block)
 
 
 # ---------------------------------------------------------------------------