iterate-plugin 3.7.0 → 3.8.0

package/README.md

@@ -342,11 +342,15 @@ All runtime state lives under `.iterate/` at the project root (can be excluded v
   `0.1.2-rc.1`, `0.1.3-alpha.1`, `0.1.5-alpha.1`, `0.1.5-alpha.2`,
   `0.1.5-rc.1`, `0.1.5-rc.2`, `0.1.6-alpha.1`, `0.1.6-alpha.2`,
   `0.1.7-alpha.1`, `0.1.7-alpha.2`, `0.1.7-rc.1`, `0.1.7-rc.2`, `0.2.0-rc.1`,
-  `0.2.0-rc.2`, `0.2.1-alpha.1`, `0.2.1-alpha.2` (19 releases, `0.1.1-rc.1` …
-  `0.2.1-alpha.2`).
+  `0.2.0-rc.2`, `0.2.1-alpha.1`, `0.2.1-alpha.2`, `0.2.1-alpha.3`,
+  `0.2.1-alpha.4` (21 releases, `0.1.1-rc.1` …
+  `0.2.1-alpha.4`).
   The plugin is built against `@deepseek-ai/dsh-tools` /
-  `@deepseek-ai/dsh-util-values` `0.2.1-alpha.2` and uses only public contracts
+  `@deepseek-ai/dsh-util-values` `0.2.1-alpha.4` and uses only public contracts
   (tool registration, client slots + theme, bundle patch).
+  It also declares `engines.dsh` (`>=0.1.1-rc.1`) so the dsh ≥ 0.2.1-alpha.4
+  runtime evaluates compatibility from that single range (earlier runtimes fall
+  back to the `@deepseek-ai/dsh-*` peer versions listed in `package.json`).
 - **Disposable-Profile evidence (real, `dsh` CLI `0.1.1-rc.1`)**: on a temp
   `$DSH_HOME`, `dsh plugin --profile <p> add <this-repo>` installed the bundle in
   ~449 ms; `dsh --profile <p> --dump-config` composed the `iterate-plugin` bundle
@@ -384,8 +388,36 @@ following capabilities; elevated capability means a DSH Profile install stays
 
 ### Dependencies
 
-Runtime dependencies: `@deepseek-ai/cordis`, `@deepseek-ai/dsh-tools`,
-`@deepseek-ai/dsh-util-values`, `js-yaml` — all pinned exact versions.
+Runtime dependency: `js-yaml` (pinned exact version). The three DSH host
+modules the plugin is built against — `@deepseek-ai/cordis`,
+`@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-util-values` — are declared as
+**optional `peerDependencies`** so the host's own copies are used instead of a
+second one bundled with the plugin (no duplicate module instances; `dsh`
+supplies them). They stay pinned in `devDependencies` for local builds and
+tests, in lockstep with the newest `dsh.compatibility.dshReleases` entry.
+
+#### Upstream adoption (v3.8.0 → dsh `0.2.1-alpha.4`)
+
+- **Adopted — the `engines.dsh` compatibility contract.** As of `0.2.1-alpha.4`
+  the dsh runtime decides a third-party plugin's compatibility **from
+  `engines.dsh` when it is declared** (a semver range, prereleases included),
+  ignoring `peerDependencies`; when it is absent the runtime falls back to
+  checking the exact `@deepseek-ai/dsh-*` peer versions. The plugin now declares
+  `engines.dsh: ">=0.1.1-rc.1"` — the same lower bound as the oldest
+  `dshReleases` entry — so a current runtime loads it without flagging the
+  exact-pinned peer list, while every host-specific capability stays
+  feature-detected (a missing `WorkingDirectoryService`, `ask.displayReason`,
+  `ctx.jobs`, etc. still degrade to the safe fallback). Earlier runtimes keep
+  using the `@deepseek-ai/dsh-*` peer versions, which are extended through
+  `0.2.1-alpha.4`.
+- **`0.2.1-alpha.3` / `0.2.1-alpha.4` are otherwise host-level releases** — Web
+  sign-in, secret/token masking, minimal-mode image reading, `/compact`, plugin
+  hot-reload, custom plugin index sources, and per-model reasoning-level UI. None
+  expose a tool/agent/session API this plugin consumes (`defineTool`, `JsonValue`,
+  `exec.*`, `tools/pre-execute`, `presentCall`), so no further adoption is
+  required this cycle.
+- All five `@deepseek-ai/*` packages are pinned to the exact `0.2.1-alpha.4`
+  (`@deepseek-ai/cordis` stays `4.0.5-alpha.2`).
 
 #### Upstream adoption (v3.7.0 → dsh `0.2.1-alpha.2`)
 

package/README.zh-CN.md

@@ -334,7 +334,7 @@ validation:
 ### Node.js / DSH 兼容范围
 
 - **Node.js**：`>=20`（`package.json` 的 `engines.node`）。
-- **DSH**：`package.json` 的 `dsh.compatibility.dshReleases` 字段是发布兼容性的**唯一真源**（本 README 逐字镜像该字段；两者需同步更新）。以下官方版本声明为 `compatible`：`0.1.1-rc.1`、`0.1.2-alpha.4`、`0.1.2-alpha.5`、`0.1.2-rc.1`、`0.1.3-alpha.1`、`0.1.5-alpha.1`、`0.1.5-alpha.2`、`0.1.5-rc.1`、`0.1.5-rc.2`、`0.1.6-alpha.1`、`0.1.6-alpha.2`、`0.1.7-alpha.1`、`0.1.7-alpha.2`、`0.1.7-rc.1`、`0.1.7-rc.2`、`0.2.0-rc.1`、`0.2.0-rc.2`、`0.2.1-alpha.1`、`0.2.1-alpha.2`（共 19 个版本，`0.1.1-rc.1` … `0.2.1-alpha.2`）。插件基于 `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.2.1-alpha.2` 构建，只使用公开契约（工具注册、客户端 slots + theme、bundle patch）。
+- **DSH**：`package.json` 的 `dsh.compatibility.dshReleases` 字段是发布兼容性的**唯一真源**（本 README 逐字镜像该字段；两者需同步更新）。以下官方版本声明为 `compatible`：`0.1.1-rc.1`、`0.1.2-alpha.4`、`0.1.2-alpha.5`、`0.1.2-rc.1`、`0.1.3-alpha.1`、`0.1.5-alpha.1`、`0.1.5-alpha.2`、`0.1.5-rc.1`、`0.1.5-rc.2`、`0.1.6-alpha.1`、`0.1.6-alpha.2`、`0.1.7-alpha.1`、`0.1.7-alpha.2`、`0.1.7-rc.1`、`0.1.7-rc.2`、`0.2.0-rc.1`、`0.2.0-rc.2`、`0.2.1-alpha.1`、`0.2.1-alpha.2`、`0.2.1-alpha.3`、`0.2.1-alpha.4`（共 21 个版本，`0.1.1-rc.1` … `0.2.1-alpha.4`）。插件基于 `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.2.1-alpha.4` 构建，只使用公开契约（工具注册、客户端 slots + theme、bundle patch）。插件同时声明 `engines.dsh`（`>=0.1.1-rc.1`），使 dsh ≥ 0.2.1-alpha.4 运行时只依据该范围判断兼容性（更早的运行时仍回退校验 `package.json` 中列出的 `@deepseek-ai/dsh-*` peer 版本）。
 - **一次性 Profile 证据（真实，`dsh` CLI `0.1.1-rc.1`）**：在临时 `$DSH_HOME` 下
   `dsh plugin --profile <p> add <本仓库>` 约 449ms 完成安装；`dsh --profile <p>
   --dump-config` 正确合成 `iterate-plugin` bundle patch；`dsh plugin --profile <p>
@@ -364,8 +364,28 @@ validation:
 
 ### 依赖
 
-运行时依赖：`@deepseek-ai/cordis`、`@deepseek-ai/dsh-tools`、
-`@deepseek-ai/dsh-util-values`、`js-yaml`——全部精确锁版。
+运行时依赖：`js-yaml`（精确锁版）。本插件构建所依赖的三个 DSH 宿主模块——
+`@deepseek-ai/cordis`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-util-values`
+——已声明为**可选 `peerDependencies`**，直接复用宿主自带的那一份，避免插件内
+再打包一份造成双模块实例（由 `dsh` 提供）；同时在 `devDependencies` 中精确锁版，
+供本地构建与测试，并与 `dsh.compatibility.dshReleases` 的最新条目保持一致。
+
+#### 上游采纳记录（v3.8.0 → dsh `0.2.1-alpha.4`）
+
+- **已采纳——`engines.dsh` 兼容契约。** 自 `0.2.1-alpha.4` 起，dsh 运行时**在声明了
+  `engines.dsh` 时只依据该字段**（一个含预发布版本的 semver 范围）判断第三方插件兼容性，
+  忽略 `peerDependencies`；未声明时才回退逐个校验精确的 `@deepseek-ai/dsh-*` peer 版本。
+  插件现已声明 `engines.dsh: ">=0.1.1-rc.1"`（与最早的 `dshReleases` 条目同下界），
+  使当前运行时加载时不再因精确锁版的 peer 列表被判不兼容；而所有宿主相关能力依旧
+  特性探测（缺少 `WorkingDirectoryService`、`ask.displayReason`、`ctx.jobs` 等一律
+  降级到安全回退）。更早的运行时仍走 `@deepseek-ai/dsh-*` peer 版本，已扩展至
+  `0.2.1-alpha.4`。
+- **`0.2.1-alpha.3` / `0.2.1-alpha.4` 其余均为宿主级变更**——Web 登录、密钥/令牌脱敏、
+  极简模式读图、`/compact`、插件热重载、自定义插件索引源、按模型配置推理等级 UI。
+  都未暴露本插件消费的 tool/agent/session API（`defineTool`、`JsonValue`、`exec.*`、
+  `tools/pre-execute`、`presentCall`），本轮无需进一步采纳。
+- 五个 `@deepseek-ai/*` 包全部精确锁到 `0.2.1-alpha.4`
+  （`@deepseek-ai/cordis` 保持 `4.0.5-alpha.2`）。
 
 #### 上游采纳记录（v3.7.0 → dsh `0.2.1-alpha.2`）
 

package/dist/file-lock.js

@@ -26,10 +26,17 @@
  * `withProjectLock` is therefore NOT reentrant and must not be nested for the
  * same (projectRoot, name).
  */
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync, } from 'node:fs';
+import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync, } from 'node:fs';
 import { join } from 'node:path';
 const LOCK_DIR = '.iterate';
-const DEFAULT_WAIT_MS = 5000;
+// Bounded wait before degrading to "proceed unlocked". `acquireProjectLock`
+// spins on `Atomics.wait`, which BLOCKS the single plugin thread for the whole
+// budget — so a long default wedges unrelated tool calls and the UI heartbeat
+// whenever a sibling process holds the lock. Healthy holders release in
+// microseconds, so 1000ms is very generous; anything slower is treated as
+// contention and degrades to the historical unlocked behavior rather than
+// stalling the event loop for five seconds.
+const DEFAULT_WAIT_MS = 1000;
 const DEFAULT_STALE_MS = 10000;
 const POLL_MS = 25;
 /** True when a pid refers to a live process (or we lack permission to tell). */
@@ -60,14 +67,17 @@ function lockFileName(name) {
     return `.${name}.lock`;
 }
 /**
- * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`.
+ * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`,
+ * reporting whether it was actually taken.
  *
- * Returns a release function: always callable, idempotent, never throws.
- * A no-op (but callable) release is returned when the lock directory cannot be
- * created or the wait times out — callers then proceed unlocked, which is the
- * historical best-effort behavior, rather than failing the operation.
+ * The returned release function is always callable, idempotent, and never
+ * throws. `acquired:false` (with a no-op release) is returned when the lock
+ * directory cannot be created or the wait times out — callers then proceed
+ * unlocked, which is the historical best-effort behavior, rather than failing
+ * the operation. Callers that MUST hold the mutex (e.g. a log rewrite that
+ * renames the file) branch on `acquired` and refuse to run unlocked.
  */
-export function acquireProjectLock(projectRoot, name, options = {}) {
+export function acquireProjectLockChecked(projectRoot, name, options = {}) {
     const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
         ? options.waitMs
         : DEFAULT_WAIT_MS;
@@ -80,7 +90,7 @@ export function acquireProjectLock(projectRoot, name, options = {}) {
             mkdirSync(dir, { recursive: true });
         }
         catch {
-            return () => { };
+            return { acquired: false, release: () => { } };
         }
     }
     const lockPath = join(dir, lockFileName(name));
@@ -92,7 +102,7 @@ export function acquireProjectLock(projectRoot, name, options = {}) {
         }
         catch (err) {
             if (err.code !== 'EEXIST')
-                return () => { };
+                return { acquired: false, release: () => { } };
             // Lock exists — steal it when the owner is gone or the lock is ancient.
             let stale = false;
             try {
@@ -118,11 +128,21 @@ export function acquireProjectLock(projectRoot, name, options = {}) {
                 continue;
             }
             if (Date.now() - start > waitMs)
-                return () => { };
+                return { acquired: false, release: () => { } };
             sleepSync(POLL_MS);
             continue;
         }
-        // Owned the lock: stamp the holder pid, then release once on return.
+        // Owned the lock: capture the created inode (for the ownership-checked
+        // release), stamp the holder pid, then release once on return.
+        let ino = 0;
+        try {
+            ino = fstatSync(fd).ino;
+        }
+        catch {
+            // inode unavailable on this filesystem — the release falls back to the
+            // pid-stamp check only.
+            ino = 0;
+        }
         try {
             writeSync(fd, String(process.pid));
         }
@@ -135,9 +155,20 @@ export function acquireProjectLock(projectRoot, name, options = {}) {
         catch {
             // best-effort
         }
-        return makeLockRelease(lockPath);
+        return { acquired: true, release: makeLockRelease(lockPath, ino) };
     }
 }
+/**
+ * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`.
+ *
+ * Returns a release function: always callable, idempotent, never throws.
+ * A no-op (but callable) release is returned when the lock directory cannot be
+ * created or the wait times out — callers then proceed unlocked, which is the
+ * historical best-effort behavior, rather than failing the operation.
+ */
+export function acquireProjectLock(projectRoot, name, options = {}) {
+    return acquireProjectLockChecked(projectRoot, name, options).release;
+}
 /**
  * Build the release function for a lock file this process just acquired.
  *
@@ -151,7 +182,25 @@ export function acquireProjectLock(projectRoot, name, options = {}) {
  *
  * Always callable, idempotent, and never throws.
  */
-export function makeLockRelease(lockPath) {
+/**
+ * Build the release function for a lock file this process just acquired.
+ *
+ * Advisory locks here are STOLEN when the recorded owner dies or the mtime
+ * goes ancient: the steal unlinks our file and creates a new one stamped with
+ * the STEALER's pid. An unguarded release would then unlink the new holder's
+ * lock — turning our release into a double-release that admits a third process
+ * into a "held" critical section. So the release re-reads the stamp and only
+ * unlinks a file that is still ours: same pid (or unstamped) AND, when we know
+ * the inode we created, the SAME inode still at the path. The inode check closes
+ * the read-then-unlink window where the stamp check alone could race a steal
+ * (our pid is alive, but the file was already replaced between the two calls).
+ *
+ * Always callable, idempotent, and never throws.
+ *
+ * @param lockPath - the lock file path.
+ * @param ino - the inode captured at acquisition (0 = unknown; skip the check).
+ */
+export function makeLockRelease(lockPath, ino) {
     let released = false;
     return () => {
         if (released)
@@ -169,6 +218,18 @@ export function makeLockRelease(lockPath) {
         // it is no longer ours to delete.
         if (raw !== '' && Number(raw) !== process.pid)
             return;
+        // The path must still refer to the file WE created. A stealer unlinked our
+        // file and created a fresh one; that replacement carries a different inode,
+        // so unlinking by path would delete the NEW holder's lock.
+        if (typeof ino === 'number' && ino !== 0) {
+            try {
+                if (statSync(lockPath).ino !== ino)
+                    return;
+            }
+            catch {
+                return; // vanished mid-release — nothing of ours left
+            }
+        }
         try {
             unlinkSync(lockPath);
         }

package/dist/git-scope.js

@@ -21,7 +21,7 @@
  * git repo.
  */
 import { execFile } from 'node:child_process';
-import { existsSync, statSync } from 'node:fs';
+import { lstatSync, realpathSync } from 'node:fs';
 import { join, sep } from 'node:path';
 /**
  * Parse `git diff --name-only -z` stdout into a list of relative paths.
@@ -112,6 +112,15 @@ export function parseChangedFiles(stdout) {
  * Keep only entries that resolve to an existing regular file under `root`.
  * Traversal-safe: rejects absolute paths and any relative path that would
  * escape `root` via `..` (resolved against the root before stat).
+ *
+ * Symlink handling: `statSync` (and `existsSync`) FOLLOW symlinks, so a git
+ * entry that is a link to a file OUTSIDE the project would pass a path-only
+ * containment check and enter the changed-only scope. Such a file is then
+ * rejected by the evidence gate (realpath out of bounds → `file_not_found`),
+ * so every finding on it would fail closed as `EVIDENCE_VIOLATION` forever —
+ * a permanent false positive for repos with dotfile or shared-config links.
+ * `lstatSync` distinguishes the link itself; a link whose REAL target escapes
+ * `root` is dropped here instead.
  */
 export function filterExistingFiles(root, files) {
     const out = [];
@@ -123,7 +132,18 @@ export function filterExistingFiles(root, files) {
         if (!candidate.startsWith(rootPrefix) && candidate !== root)
             continue;
         try {
-            if (existsSync(candidate) && statSync(candidate).isFile())
+            const st = lstatSync(candidate);
+            if (st.isFile()) {
+                out.push(rel);
+                continue;
+            }
+            if (!st.isSymbolicLink())
+                continue;
+            // A link whose real target stays inside the project is a legitimate,
+            // reviewable file; one that escapes is excluded from scope (fail-closed
+            // at the source instead of as a permanent evidence violation).
+            const real = realpathSync(candidate);
+            if (real === root || real.startsWith(rootPrefix))
                 out.push(rel);
         }
         catch {

package/dist/skill-prompt.js

@@ -134,7 +134,7 @@ for (let r = 1; r <= maxRounds; r++) {
         (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
         '\\n Already-known findings (do NOT re-report): ' +
         JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.'
-      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta?.findingsSchema }, backend))
     }))
     // A per-dimension reviewer subagent resolves \`null\` on child failure; the
     // aggregate below would report an all-failed round as an empty round, and
@@ -463,7 +463,7 @@ for (let r = startRound; r <= maxRounds; r++) {
         (steering ? '\\n STEERING — read this first: ' + steering : '') +
         (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
         '\\n Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.'
-      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta?.findingsSchema }, backend))
     }))
     // ALL reviewers returning null (child failures) means this round produced
     // no usable output — an empty aggregate must not read like a clean

package/dist/tools/checkpoint.js

@@ -12,6 +12,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { writeJsonAtomic } from "../atomic-fs.js";
+import { withProjectLock } from "../file-lock.js";
 import { checkpointPath, iterateDir, transcriptPath } from "../paths.js";
 import { readRegistry } from "./fix.js";
 import { readDecisionEntries } from "./decision-log.js";
@@ -289,23 +290,29 @@ export function registerCheckpointTool(ctx) {
                 return { operation: 'load', ok: true, checkpoint: checkpoint };
             }
             if (args.operation === 'resume') {
-                const current = readCheckpoint(projectRoot);
-                if (!current) {
-                    return { operation: 'resume', ok: false, error: 'no checkpoint to resume — run `save` first' };
-                }
-                const resumed = {
-                    ...current,
-                    resumeCount: (current.resumeCount ?? 0) + 1,
-                    updatedAt: new Date().toISOString(),
-                };
-                try {
-                    mkdirSync(iterateDir(projectRoot), { recursive: true });
-                    writeJsonAtomic(checkpointPath(projectRoot), resumed);
-                }
-                catch (err) {
-                    return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` };
-                }
-                return { operation: 'resume', ok: true, checkpoint: resumed };
+                // Read-modify-write across processes: a concurrent resume in a
+                // sibling process would read the same resumeCount and write it back,
+                // losing one increment. Serialize on a checkpoint lock (the same
+                // advisory pattern the config/triage/transcript writers use).
+                return withProjectLock(projectRoot, 'checkpoint', () => {
+                    const current = readCheckpoint(projectRoot);
+                    if (!current) {
+                        return { operation: 'resume', ok: false, error: 'no checkpoint to resume — run `save` first' };
+                    }
+                    const resumed = {
+                        ...current,
+                        resumeCount: (current.resumeCount ?? 0) + 1,
+                        updatedAt: new Date().toISOString(),
+                    };
+                    try {
+                        mkdirSync(iterateDir(projectRoot), { recursive: true });
+                        writeJsonAtomic(checkpointPath(projectRoot), resumed);
+                    }
+                    catch (err) {
+                        return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` };
+                    }
+                    return { operation: 'resume', ok: true, checkpoint: resumed };
+                });
             }
             if (args.operation === 'clear') {
                 const existed = existsSync(checkpointPath(projectRoot));

package/dist/tools/config.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { defaultConfig, loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from "../config-loader.js";
 import { applyConfigUpdates, readRawConfig, validateConfigUpdates, writeConfigFile, } from "../config-write.js";
+import { withProjectLock } from "../file-lock.js";
 /**
  * Register the `iterate_config` tool.
  * Reads and returns the iterate.config.yaml configuration, or writes a
@@ -105,42 +106,50 @@ export function registerConfigTool(ctx) {
                 if (updateErrors.length > 0) {
                     return { operation: 'write', ok: false, found: false, errors: updateErrors };
                 }
-                let base;
-                try {
-                    // Partial updates must be mergeable on a FRESH project (no config
-                    // file yet): otherwise `{max_rounds: 5}` alone fails schema
-                    // validation with a misleading "missing goal". Merge against the
-                    // built-in defaults when there is no file to read, so the written
-                    // config captures the effective config (defaults + update) and the
-                    // documented "write a partial update" contract works out of the box.
-                    base = existsSync(join(projectRoot, 'iterate.config.yaml'))
-                        ? readRawConfig(join(projectRoot, 'iterate.config.yaml'))
-                        : defaultConfig();
-                }
-                catch (err) {
-                    return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` };
-                }
-                const merged = applyConfigUpdates(base, updates ?? {});
-                const schemaErrors = validateConfig(merged);
-                if (schemaErrors.length > 0) {
+                // Serialize the read→merge→validate→write cycle against any other
+                // config/triage writer in a sibling process: without the lock, two
+                // sessions on the same project each read a stale base and the second
+                // merge silently discards the first's update (lost update). The same
+                // lock name is shared with `iterate_triage apply` so the two writers
+                // are mutually exclusive.
+                return withProjectLock(projectRoot, 'config-write', () => {
+                    let base;
+                    try {
+                        // Partial updates must be mergeable on a FRESH project (no config
+                        // file yet): otherwise `{max_rounds: 5}` alone fails schema
+                        // validation with a misleading "missing goal". Merge against the
+                        // built-in defaults when there is no file to read, so the written
+                        // config captures the effective config (defaults + update) and the
+                        // documented "write a partial update" contract works out of the box.
+                        base = existsSync(join(projectRoot, 'iterate.config.yaml'))
+                            ? readRawConfig(join(projectRoot, 'iterate.config.yaml'))
+                            : defaultConfig();
+                    }
+                    catch (err) {
+                        return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` };
+                    }
+                    const merged = applyConfigUpdates(base, updates ?? {});
+                    const schemaErrors = validateConfig(merged);
+                    if (schemaErrors.length > 0) {
+                        return {
+                            operation: 'write',
+                            ok: false,
+                            found: false,
+                            errors: schemaErrors.map((e) => `missing/required field: ${e}`),
+                        };
+                    }
+                    const result = writeConfigFile(projectRoot, merged);
+                    if (!result.ok)
+                        return { operation: 'write', ok: false, found: false, error: result.error };
+                    const { config } = loadEffectiveConfig(projectRoot);
                     return {
                         operation: 'write',
-                        ok: false,
-                        found: false,
-                        errors: schemaErrors.map((e) => `missing/required field: ${e}`),
+                        ok: true,
+                        found: true,
+                        backupPath: result.backupPath ?? null,
+                        config: config,
                     };
-                }
-                const result = writeConfigFile(projectRoot, merged);
-                if (!result.ok)
-                    return { operation: 'write', ok: false, found: false, error: result.error };
-                const { config } = loadEffectiveConfig(projectRoot);
-                return {
-                    operation: 'write',
-                    ok: true,
-                    found: true,
-                    backupPath: result.backupPath ?? null,
-                    config: config,
-                };
+                });
             }
             // ── Read operations (original behavior) ────────────────────────────
             const { config, source } = loadEffectiveConfig(projectRoot);

package/dist/tools/decision-log.js

@@ -1,8 +1,8 @@
-import { appendFileSync, readFileSync, mkdirSync, existsSync, openSync, writeSync, closeSync, unlinkSync, statSync, } from 'node:fs';
+import { appendFileSync, readFileSync, mkdirSync, existsSync, statSync, } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
-import { makeLockRelease } from "../file-lock.js";
+import { acquireProjectLockChecked } from "../file-lock.js";
 const LOG_DIR = '.iterate';
 const LOG_FILE = 'decision-log.jsonl';
 // ─── Cross-process log mutex ────────────────────────────────────────────────
@@ -19,34 +19,15 @@ const LOG_FILE = 'decision-log.jsonl';
 // be lost to a wedged append), never to a crash. The prune REWRITE is the
 // opposite — it renames the log and therefore refuses to run when the lock
 // cannot be taken (see `rewriteDecisionLogKeepingRecent` in prune.ts).
-const LOCK_FILE = '.decision-log.lock';
-const LOCK_WAIT_MS = 5000;
-const LOCK_STALE_MS = 10000;
-const LOCK_POLL_MS = 25;
-/** True when a pid refers to a live process (or we lack permission to tell). */
-function processAlive(pid) {
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code === 'EPERM';
-    }
-}
-/** Synchronous busy-wait sleep (Atomics.wait is a reliable sleep in Node). */
-function sleepSync(ms) {
-    const sab = new Int32Array(new SharedArrayBuffer(4));
-    Atomics.wait(sab, 0, 0, ms);
-}
+/** Lock name shared with the prune rewrite (→ `.iterate/.decision-log.lock`). */
+const LOG_LOCK_NAME = 'decision-log';
 /**
  * Acquire the decision-log lock for `projectRoot`.
  * Returns a release function (always callable; a no-op when the lock could
  * not be taken — never wedge an append behind a vanished holder).
  *
- * `options.waitMs` / `options.staleMs` override the defaults (tests use short
- * waits so a live-holder timeout is exercised in milliseconds, not 5s).
+ * `options.waitMs` / `options.staleMs` override the shared defaults (tests use
+ * short waits so a live-holder timeout is exercised in milliseconds, not 5s).
  */
 export function acquireLogLock(projectRoot, options = {}) {
     return acquireLogLockChecked(projectRoot, options).release;
@@ -57,76 +38,15 @@ export function acquireLogLock(projectRoot, options = {}) {
  * audit line must not be lost to a wedged append), but the rewrite renames the
  * log under any unlocked concurrent appender — it must refuse to run without
  * the mutex rather than silently dropping an audit line.
+ *
+ * Delegates to the shared `acquireProjectLockChecked` with lock name
+ * `decision-log`: the decision-log mutex IS that generic project lock. This
+ * module used to hand-roll an identical copy of the acquire/steal/wait logic,
+ * and the two stale/wait parameter sets could drift apart — one implementation,
+ * one set of defaults, one ownership-checked release.
  */
 export function acquireLogLockChecked(projectRoot, options = {}) {
-    const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
-        ? options.waitMs
-        : LOCK_WAIT_MS;
-    const staleMs = Number.isFinite(options.staleMs) && (options.staleMs ?? 0) >= 0
-        ? options.staleMs
-        : LOCK_STALE_MS;
-    const dir = join(projectRoot, LOG_DIR);
-    if (!existsSync(dir)) {
-        try {
-            mkdirSync(dir, { recursive: true });
-        }
-        catch {
-            return { acquired: false, release: () => { } };
-        }
-    }
-    const lockPath = join(dir, LOCK_FILE);
-    const start = Date.now();
-    for (;;) {
-        let fd = null;
-        try {
-            fd = openSync(lockPath, 'wx');
-        }
-        catch (err) {
-            if (err.code !== 'EEXIST')
-                return { acquired: false, release: () => { } };
-            // Lock exists — steal it when the owner is gone or the lock is ancient.
-            let stale = false;
-            try {
-                const st = statSync(lockPath);
-                if (Date.now() - st.mtimeMs > staleMs)
-                    stale = true;
-                else {
-                    const pid = Number(readFileSync(lockPath, 'utf-8'));
-                    if (!processAlive(pid))
-                        stale = true;
-                }
-            }
-            catch {
-                stale = true; // unreadable/vanishing lock → retry as stale
-            }
-            if (stale) {
-                try {
-                    unlinkSync(lockPath);
-                }
-                catch { /* another holder stole it */ }
-                continue;
-            }
-            if (Date.now() - start > waitMs)
-                return { acquired: false, release: () => { } };
-            sleepSync(LOCK_POLL_MS);
-            continue;
-        }
-        // Owned the lock: stamp the holder pid, then release once on return.
-        // The release is ownership-checked (see `makeLockRelease`): a lock stolen
-        // from this process after its owner went stale must not be unlinked by us.
-        try {
-            writeSync(fd, String(process.pid));
-        }
-        catch { /* pid stamp is advisory */ }
-        try {
-            closeSync(fd);
-        }
-        catch { /* best-effort */ }
-        return {
-            acquired: true,
-            release: makeLockRelease(lockPath),
-        };
-    }
+    return acquireProjectLockChecked(projectRoot, LOG_LOCK_NAME, options);
 }
 // ─── Entry-count cache (avoid an O(n) full re-read per append) ─────────────
 /**