iterate-plugin 3.4.0 → 3.5.0

package/README.md

@@ -123,7 +123,7 @@ Beyond the 17 registered tools (full reference further down), the plugin closes
 - **Structured fix system** — each fix backs up first, writes a registry entry, records the diff; a failed validation can be reverted with `iterate_rollback`
 - **Breakpoint resume** — checkpoints saved at the start of each round; interrupted long iterations can resume
 - **History audit** — `iterate_history` reads the decision log (filtered by type / time / count) and the fix-registry summary to audit run process and fix details
-- **Runtime cleanup** — `iterate_prune` removes stale decision-log entries, stale checkpoints, orphaned fix backups and empty rounds; dry-run by default (report-only), real cleanup requires `dryRun:false`, and every cleanup is logged
+- **Runtime cleanup** — `iterate_prune` removes stale decision-log entries, stale checkpoints, orphaned fix backups, empty rounds and stray temp files left by crashed atomic writes; dry-run by default (report-only), real cleanup requires `dryRun:false`, and every cleanup is logged
 - **Config read / write** — `iterate_config` supports validated, backed-up, rollback-capable partial writes
 - **v3.2 Experience Bank** — `iterate_experience` queries historical fixes and patterns with search / filter / adopt, and can persist new verified fixes (`add`) — re-adding the same pattern+dimension bumps its hit count instead of duplicating it
 - **v3.2 Quality Gate** — `iterate_quality_gate` reads quality gate status with per-dimension convergence rates and PASS/FAIL, and can recompute + persist a fresh certificate (`compute`) from this round's findings / validation results (real convergence from `findingsByRound`)
@@ -258,7 +258,7 @@ validation:
 - `iterate_checkpoint` — iteration breakpoint: `save` persists progress to `.iterate/checkpoint.json`, `load` reads it back, `resume` loads + bumps the resume counter (interruption recovery), `clear` removes it. Resumable interrupted long iterations
 - `iterate_status` — summarize current iteration state: mode, current/last round, fixes applied, remaining architectural, decision-log entry count, whether a checkpoint exists; **v3.4: also surfaces the persisted quality-gate snapshot, experience-bank summary, and defense-events summary** (`qualityGate` / `experienceBank` / `defenseEvents`)
 - `iterate_history` — read iteration history (read-only): decision-log entries (filter by `type` / `since` / `limit`, default latest 50, cap 200) + fix-registry summary (per-round fixed/failed counts). For auditing the run, tracing logs, and inventorying fixes
-- `iterate_prune` — clean runtime artifacts: stale decision-log entries (by `retainDays`, default 30), stale checkpoints, orphaned fix backups, empty rounds. Dry-run by default (report-only); real cleanup with `dryRun:false`, each cleanup logged
+- `iterate_prune` — clean runtime artifacts: stale decision-log entries (by `retainDays`, default 30), stale checkpoints, orphaned fix backups, empty rounds, stray temp files (crashed atomic writes). Dry-run by default (report-only); real cleanup with `dryRun:false`, each cleanup logged
 - `iterate_transcript` — runtime observatory: persist review transcripts, threads, fixes, and nudge directions to `.iterate/transcript.json` for the client observatory
 - `iterate_experience` — **v3.2** query the experience bank (list / search / get), or `add` a new verified fix: re-adding the same pattern+dimension bumps its hit count instead of duplicating it. Persists to `.iterate/experience.json`
 - `iterate_quality_gate` — **v3.2** read the quality certificate (`read`), or recompute + persist a fresh one (`compute`) from findings, validation results, `findingsByRound`, and `fixedByDimension`. Real per-dimension convergence rates
@@ -292,9 +292,20 @@ All runtime state lives under `.iterate/` at the project root (can be excluded v
 
 - **Node.js**: `>=20` (`package.json` `engines.node`).
 - **DSH**: declares `dsh.compatibility.dshReleases` — `compatible` for the official
-  `0.1.2-alpha.4`, `0.1.2-alpha.5`, and `0.1.2-rc.1` releases. The plugin is built
-  against `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.1.2-rc.1`
-  and uses only public contracts (tool registration, client slots + theme, bundle patch).
+  `0.1.1-rc.1`, `0.1.2-alpha.4`, `0.1.2-alpha.5`, `0.1.2-rc.1`, and `0.1.3-alpha.1`
+  releases. The plugin is built against `@deepseek-ai/dsh-tools` /
+  `@deepseek-ai/dsh-util-values` `0.1.2-rc.1` and uses only public contracts
+  (tool registration, client slots + theme, bundle patch). `0.1.3-alpha.1` is a
+  source declaration matching the current DSH release window; it does not use any
+  API changed by that release.
+- **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
+  patch into the profile; `dsh plugin --profile <p> remove iterate-plugin`
+  uninstalled in ~602 ms and left zero references in the composed config. A full
+  runtime boot was **not** exercised here (no model provider in the disposable
+  profile), so `dshOperations` start/rollback stay `unknown`/`partial` — see
+  `CHANGELOG.md` for the exact commands and timings.
 
 ### Runtime permissions (conservative disclosure)
 
@@ -308,10 +319,14 @@ following capabilities; elevated capability means a DSH Profile install stays
   in-place edits to the user's source files (path-traversal protected to the
   resolved project root, backups taken before every fix, rollback on failure).
   The client half persists triage verdicts to `localStorage`.
-- **Commands** — the plugin registers model-facing tools; any shell execution that
-  the model performs (build / test / `git`) is run by the **host**, not by this
-  plugin. The client "command buttons" only copy paste-able instruction text; they
-  do not spawn processes.
+- **Commands** — the plugin's own tools execute a small, strictly bounded command
+  surface inside the dsh host process, only when the model calls them: `iterate_validate`
+  runs one of the **exact-match whitelisted** commands configured in
+  `iterate.config.yaml` `validation.commands` (yes, it shells out via
+  `node:child_process`, timeout-capped to ≤600 s); `iterate_review` (changed-only
+  scope) runs `git diff --name-only -z <branch>` in the project root. Nothing else
+  spawns a process. The client "command buttons" only copy paste-able instruction
+  text; they do not spawn processes.
 - **Credentials** — this plugin does **not** read or transmit credentials at
   runtime. The sibling **iterate-skill / iterate-harness** components may read git
   credentials / GitHub tokens when the user runs their own Git/API operations; those

package/README.zh-CN.md

@@ -122,7 +122,7 @@ UI 层为**防御式设计**：`slots` / `theme` / `React` 任一不可用时自
 - **结构化修复系统** — 每次修复先备份、写注册表、记录 diff，验证失败可 `iterate_rollback` 还原
 - **断点续跑** — 长迭代在每轮开头保存 checkpoint，中断后可恢复进度
 - **历史审计** — `iterate_history` 读取决策日志（按类型/时间/数量过滤）与修复注册表汇总，审查运行过程与修复明细
-- **运行时清理** — `iterate_prune` 清理过期的决策日志条目、陈旧断点、孤儿修复备份与空轮次；默认 dry-run 只报告不删除，显式 `dryRun:false` 才真正清理，每次清理写入决策日志
+- **运行时清理** — `iterate_prune` 清理过期的决策日志条目、陈旧断点、孤儿修复备份、空轮次与原子写入崩溃残留的临时文件；默认 dry-run 只报告不删除，显式 `dryRun:false` 才真正清理，每次清理写入决策日志
 - **配置读写** — `iterate_config` 支持带校验、备份、回滚的局部写入
 - **v3.2 经验银行** — `iterate_experience` 以检索 / 过滤 / 采纳查阅历史修复与模式，并可 `add` 持久化新的已验证修复——重复添加同一 pattern + dimension 时累加命中次数而非重复写入
 - **v3.2 质量门禁** — `iterate_quality_gate` 读取质量门禁状态（各维度收敛率 + PASS/FAIL），并可基于本轮 findings / 验证结果 `compute` 重新计算并持久化一份新的质量凭证（收敛率来自 `findingsByRound` 的真实收敛序列）
@@ -257,7 +257,7 @@ validation:
 - `iterate_checkpoint` — 迭代断点：`save` 保存当前进度到 `.iterate/checkpoint.json`，`load` 读回，`resume` 加载并累加恢复计数（中断恢复），`clear` 清除。长迭代可中断续跑
 - `iterate_status` — 汇总当前迭代状态：模式、当前轮/总轮、已修复数、剩余 architectural、决策日志条数、是否存在 checkpoint；**v3.4：同时返回持久化的质量门禁快照、经验银行摘要与防御事件摘要**（`qualityGate` / `experienceBank` / `defenseEvents`）
 - `iterate_history` — 读取迭代历史（只读）：决策日志条目（可按 `type` / `since` / `limit` 过滤，默认取最新 50 条，上限 200 条）+ 修复注册表汇总（各轮 fixed/failed 计数）。用于审查运行过程、审计日志、盘点修复
-- `iterate_prune` — 清理运行时产物：过期决策日志条目（按 `retainDays`，默认 30 天）、陈旧断点、孤儿修复备份、空轮次。默认 dry-run 只报告不删除；`dryRun:false` 才真正清理，每次清理写入决策日志
+- `iterate_prune` — 清理运行时产物：过期决策日志条目（按 `retainDays`，默认 30 天）、陈旧断点、孤儿修复备份、空轮次、崩溃原子写入残留的临时文件。默认 dry-run 只报告不删除；`dryRun:false` 才真正清理，每次清理写入决策日志
 - `iterate_transcript` — 运行时观测台：把审查转录、线程、修复与 nudge 指令持久化到 `.iterate/transcript.json`，供客户端观测台读取
 - `iterate_experience` — **v3.2** 查询经验银行（list / search / get），或 `add` 一条新的已验证修复：重复添加同一 pattern + dimension 累加命中次数而非重复写入。持久化到 `.iterate/experience.json`
 - `iterate_quality_gate` — **v3.2** 读取质量凭证（`read`），或基于 findings、验证结果、`findingsByRound` 与 `fixedByDimension` 重新计算并持久化一份新凭证（`compute`）。真实的逐维度收敛率
@@ -290,10 +290,17 @@ validation:
 ### Node.js / DSH 兼容范围
 
 - **Node.js**：`>=20`（`package.json` 的 `engines.node`）。
-- **DSH**：在 `dsh.compatibility.dshReleases` 中声明官方 `0.1.2-alpha.4`、
-  `0.1.2-alpha.5`、`0.1.2-rc.1` 三个版本为 `compatible`。插件基于
-  `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.1.2-rc.1` 构建，
-  只使用公开契约（工具注册、客户端 slots + theme、bundle patch）。
+- **DSH**：在 `dsh.compatibility.dshReleases` 中声明官方 `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` 五个版本为
+  `compatible`。插件基于 `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values`
+  `0.1.2-rc.1` 构建，只使用公开契约（工具注册、客户端 slots + theme、bundle patch）；
+  `0.1.3-alpha.1` 为匹配当前 DSH 发布窗口的源码声明，插件不使用该发布变更的任何 API。
+- **一次性 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>
+  remove iterate-plugin` 约 602ms 卸载完成、合成配置中不存在残留引用。完整运行时
+  启动未在此环境演练（一次性 Profile 无模型提供方），故 `dshOperations` 的
+  start/rollback 证据为 `unknown`/`partial`——确切命令与耗时见 `CHANGELOG.md`。
 
 ### 运行时权限（保守披露）
 
@@ -304,9 +311,12 @@ validation:
   检查点、transcript、修复备份/注册表、质量门禁、经验银行、防御事件）。
   `iterate_fix` / `iterate_triage` 还会就地修改用户源码（路径遍历防护限定在解析后
   的项目根目录内，每次修复前备份、失败回滚）。客户端侧把分诊判定持久化到 `localStorage`。
-- **命令（commands）** — 插件只注册模型可调用工具；模型要执行的任何 shell 操作
-  （build / test / `git`）都由**宿主**执行，不是本插件。客户端"指挥按钮"只复制可粘贴
-  的指令文本，不启动任何进程。
+- **命令（commands）** — 插件的工具本身只执行一个严格受限的命令面、且仅在模型调用时
+  于 dsh 宿主进程内运行：`iterate_validate` 运行 `iterate.config.yaml`
+  `validation.commands` 中**逐条精确匹配白名单**的命令（是的，经由
+  `node:child_process` 执行，超时上限 600 秒）；`iterate_review`（changed-only 范围）
+  在项目根目录运行 `git diff --name-only -z <branch>`。除此之外不启动任何进程。
+  客户端"指挥按钮"只复制可粘贴的指令文本，不启动任何进程。
 - **凭据（credentials）** — 本插件运行时**不**读取或传输凭据。同生态的
   **iterate-skill / iterate-harness** 组件在用户自行执行 Git/API 操作时可能读取
   git 凭据 / GitHub token；它们是独立包，本插件从不加载它们。

package/dist/atomic-fs.js

@@ -0,0 +1,77 @@
+/**
+ * src/atomic-fs.ts — crash-safe file writes for all plugin state.
+ *
+ * Every JSON/YAML artifact the plugin persists (.iterate/*.json,
+ * iterate.config.yaml) is written through here: content goes to a
+ * uniquely-named temp file in the SAME directory as the target (rename is
+ * only atomic within one filesystem), then is `renameSync`ed over the
+ * destination. A crash mid-write can therefore leave a stale temp file
+ * behind, but never a truncated / half-written state file — readers
+ * (which all tolerate missing/corrupt files) see either the previous or
+ * the new content, never a mixture.
+ */
+import { dirname, join } from 'node:path';
+import { renameSync, rmSync, writeFileSync } from 'node:fs';
+import { rename, rm, writeFile } from 'node:fs/promises';
+/** Best-effort unlink of a leftover temp file (never throws). */
+function cleanupTemp(tmp) {
+    try {
+        rmSync(tmp, { force: true });
+    }
+    catch {
+        /* ignore — temp files follow the prunable `.tmp-<pid>-<rand>` convention */
+    }
+}
+/** Best-effort async unlink of a leftover temp file (never throws). */
+async function cleanupTempAsync(tmp) {
+    try {
+        await rm(tmp, { force: true });
+    }
+    catch {
+        /* ignore — temp files follow the prunable `.tmp-<pid>-<rand>` convention */
+    }
+}
+/**
+ * Unique temp file path for `filePath`, in the same directory, following the
+ * prunable `.<basename>.tmp-<pid>-<random>` convention (see prune.ts
+ * `isPrunableTemp`). The pid+random suffix makes concurrent writers safe.
+ */
+function tempPathFor(filePath) {
+    return join(dirname(filePath), `.${filePath.split('/').pop() ?? 'file'}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
+}
+/**
+ * Write `data` to `filePath` atomically (temp file + rename, same dir).
+ * Temp files follow the `<name>.tmp-<pid>-<random>` convention also used by
+ * prune.ts / checkpoint.ts so they are recognizable and prunable.
+ * Throws on failure (callers own error reporting — they map failures to
+ * structured tool results).
+ */
+export function writeTextAtomic(filePath, data) {
+    const tmp = tempPathFor(filePath);
+    writeFileSync(tmp, data, 'utf-8');
+    try {
+        renameSync(tmp, filePath);
+    }
+    catch (err) {
+        // Best-effort temp cleanup so a failed write never litters the directory.
+        cleanupTemp(tmp);
+        throw err;
+    }
+}
+/** Async variant of {@link writeTextAtomic} (same temp naming convention). */
+export async function writeTextAtomicAsync(filePath, data) {
+    const tmp = tempPathFor(filePath);
+    await writeFile(tmp, data, 'utf-8');
+    try {
+        await rename(tmp, filePath);
+    }
+    catch (err) {
+        // Best-effort temp cleanup so a failed write never litters the directory.
+        await cleanupTempAsync(tmp);
+        throw err;
+    }
+}
+/** JSON.stringify (2-space indent) + atomic write in one call. */
+export function writeJsonAtomic(filePath, value) {
+    writeTextAtomic(filePath, JSON.stringify(value, null, 2));
+}

package/dist/config-write.js

@@ -9,9 +9,10 @@
  * The security posture mirrors the triage tool: never overwrite a malformed
  * config, always back up before writing, roll back on failure.
  */
-import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import yaml from 'js-yaml';
+import { writeTextAtomic } from "./atomic-fs.js";
 /** Config file name (must match config-loader). */
 export const CONFIG_FILE = 'iterate.config.yaml';
 /** Backup suffix helper (filesystem-safe timestamp). */
@@ -185,7 +186,7 @@ export function writeConfigFile(projectRoot, config) {
         }
     }
     try {
-        writeFileSync(configPath, yaml.dump(config, { noRefs: true }), 'utf-8');
+        writeTextAtomic(configPath, yaml.dump(config, { noRefs: true }));
     }
     catch (err) {
         let rollbackError = '';

package/dist/git-scope.js

@@ -22,7 +22,7 @@
  */
 import { execFile } from 'node:child_process';
 import { existsSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, sep } from 'node:path';
 /**
  * Parse `git diff --name-only -z` stdout into a list of relative paths.
  * Pure. NUL-delimited mode is machine-safe (handles any filename); when no
@@ -112,11 +112,12 @@ export function parseChangedFiles(stdout) {
  */
 export function filterExistingFiles(root, files) {
     const out = [];
+    const rootPrefix = root.endsWith(sep) ? root : root + sep;
     for (const rel of files) {
         if (rel.startsWith('/') || rel.includes('\0'))
             continue;
         const candidate = join(root, rel);
-        if (!candidate.startsWith(root + '/') && candidate !== root)
+        if (!candidate.startsWith(rootPrefix) && candidate !== root)
             continue;
         try {
             if (existsSync(candidate) && statSync(candidate).isFile())

package/dist/live.js

@@ -23,8 +23,9 @@
  *   - Any capture failure is swallowed (fire-and-forget) so it can never block
  *     or crash a tool call.
  */
-import { mkdir, readFile, writeFile, stat, appendFile, rename } from 'node:fs/promises';
+import { mkdir, readFile, stat, appendFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { writeTextAtomicAsync } from "./atomic-fs.js";
 import { join } from 'node:path';
 import { resolveProjectRoot } from "./config-loader.js";
 /** Keep at most this many live activity entries. */
@@ -101,9 +102,9 @@ export async function appendLive(projectRoot, entry) {
             const raw = await readFile(file, 'utf-8');
             const lines = raw.split('\n').filter(Boolean);
             const tail = lines.slice(-LIVE_MAX_ENTRIES);
-            const tmp = `${file}.trim.tmp`;
-            await writeFile(tmp, tail.join('\n') + '\n', 'utf-8');
-            await rename(tmp, file);
+            // Atomic rewrite (unique temp + rename) so a crash mid-trim never
+            // truncates the live feed; the temp file is prunable by iterate_prune.
+            await writeTextAtomicAsync(file, tail.join('\n') + '\n');
         }
         await appendFile(file, line, 'utf-8');
     }

package/dist/skill-prompt.js

@@ -142,9 +142,20 @@ for (let r = 1; r <= maxRounds; r++) {
   // Feed the DEDUPED + already-filtered set back (not raw findings) so the known
   // list stays bounded and reviewers never see the same issue twice.
   if (agg && agg.report && Array.isArray(agg.report.findings)) known = agg.report.findings
-  if (agg && agg.report && agg.report.convergence && agg.report.convergence.findingsByRound[r-1] === 0) {
-    log('round ' + r + ' found 0 new findings — converged')
-    break
+  // A round counts as "converged" ONLY when the aggregate accepted it
+  // (schema-valid) AND it genuinely found zero NEW findings. If reviewers all
+  // failed or their output stayed schema-invalid after retries, the round is
+  // INCONCLUSIVE — never report an empty-but-broken round as converged (an
+  // invalid/failed round must fail the run, not masquerade as a clean pass).
+  if (!schemaInvalid) {
+    const newCount =
+      agg && agg.report && agg.report.convergence
+        ? agg.report.convergence.findingsByRound[r - 1]
+        : thisRound.findings.length
+    if (newCount === 0) {
+      log('round ' + r + ' found 0 new findings — converged')
+      break
+    }
   }
 }
 
@@ -237,7 +248,7 @@ if (checkpoint) {
 
 phase('plan')
 const configRes = await agent(
-  'Call iterate_config({ validate: true }) and return the config JSON.',
+  'Call iterate_config({}) and return the config JSON.',
   Object.assign({ label: 'config:read' }, backend)
 )
 const cfg = (configRes && configRes.config) ? configRes.config : null
@@ -420,7 +431,7 @@ for (let r = startRound; r <= maxRounds; r++) {
     Object.assign({ label: 'checkpoint:save:r' + r }, backend)
   )
 
-  if (atomic.length === 0 && remaining.length === 0) {
+  if (atomic.length === 0 && remaining.length === 0 && !schemaInvalid) {
     log('round ' + r + ' found nothing to fix — converged')
     converged = true
     break

package/dist/tools/checkpoint.js

@@ -8,9 +8,10 @@
  *
  * Checkpoint layout: `.iterate/checkpoint.json`.
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+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 { checkpointPath, iterateDir, transcriptPath } from "../paths.js";
 import { readRegistry } from "./fix.js";
 import { readDecisionEntries } from "./decision-log.js";
@@ -192,10 +193,7 @@ export function registerCheckpointTool(ctx) {
                 };
                 try {
                     mkdirSync(iterateDir(projectRoot), { recursive: true });
-                    const cpPath = checkpointPath(projectRoot);
-                    const tmpPath = `${cpPath}.tmp-${Date.now()}`;
-                    writeFileSync(tmpPath, JSON.stringify(resumed, null, 2), 'utf-8');
-                    renameSync(tmpPath, cpPath);
+                    writeJsonAtomic(checkpointPath(projectRoot), resumed);
                 }
                 catch (err) {
                     return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` };
@@ -238,12 +236,10 @@ export function registerCheckpointTool(ctx) {
                 };
                 try {
                     mkdirSync(iterateDir(projectRoot), { recursive: true });
-                    // Atomic write (temp + rename): a crash mid-write must not corrupt
-                    // the checkpoint and silently lose the interruption state.
-                    const cpPath = checkpointPath(projectRoot);
-                    const tmpPath = `${cpPath}.tmp-${Date.now()}`;
-                    writeFileSync(tmpPath, JSON.stringify(checkpoint, null, 2), 'utf-8');
-                    renameSync(tmpPath, cpPath);
+                    // Atomic write (temp + rename, via writeJsonAtomic): a crash
+                    // mid-write must not corrupt the checkpoint and silently lose the
+                    // interruption state.
+                    writeJsonAtomic(checkpointPath(projectRoot), checkpoint);
                 }
                 catch (err) {
                     return { operation: 'save', ok: false, error: `failed to write checkpoint: ${String(err)}` };
@@ -262,6 +258,9 @@ export function registerCheckpointTool(ctx) {
 export function registerStatusTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_status',
+        // Read-only aggregation of on-disk state → safe to join a parallel
+        // dispatch group alongside other read-only sibling calls.
+        isConcurrencySafe: () => true,
         description: 'Summarize the current iterate run: mode, current round vs total, fixes applied, architectural ' +
             'findings remaining, decision-log size, and whether a resume checkpoint exists.',
         parameters: {

package/dist/tools/config.js

@@ -11,6 +11,20 @@ import { applyConfigUpdates, readRawConfig, validateConfigUpdates, writeConfigFi
 export function registerConfigTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_config',
+        // `read` never writes; `write` persists a config update → only read
+        // joins a parallel dispatch group.
+        isConcurrencySafe: (args) => args.operation !== 'write',
+        // Pending-call card: a config read vs a validated write.
+        presentCall: (args) => {
+            const a = args;
+            const isWrite = a.operation === 'write';
+            return {
+                card: 'generic',
+                title: isWrite ? 'Update iterate.config.yaml' : 'Read iterate.config.yaml',
+                kind: isWrite ? 'edit' : 'read',
+                ...(typeof a.section === 'string' && a.section ? { rawInput: { section: a.section } } : {}),
+            };
+        },
         description: 'Read or update the iterate.config.yaml configuration from the project root. ' +
             'Returns the full parsed config, a specific section, or validation errors. ' +
             'Use this to discover available dimensions, validation commands, git settings, and personalization rules, ' +

package/dist/tools/context.js

@@ -161,6 +161,9 @@ export { findSkillMd };
 export function registerContextTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_context',
+        // Read-only (reads SKILL.md / ITERATE.md) → safe to join a parallel
+        // dispatch group alongside other read-only sibling calls.
+        isConcurrencySafe: () => true,
         description: 'Read project context files (SKILL.md and/or ITERATE.md). ' +
             'SKILL.md contains the original iterate skill instructions; it is searched in ' +
             'the skill directory (auto-detected), the project root, or an explicit `skillDir`. ' +

package/dist/tools/decision-log.js

@@ -71,34 +71,44 @@ export function appendDecisionEntry(projectRoot, entry) {
     return { count, path: filePath };
 }
 /**
- * Read all entries from the decision log.
+ * Read all entries from the decision log, plus the count of corrupt lines.
  * A single corrupt line (partial write, hand-edit) is SKIPPED, not fatal —
- * one bad line must never empty the whole history for every reader.
+ * one bad line must never empty the whole history for every reader — but it
+ * is counted in `invalidLines` so it never disappears silently.
  */
-export function readDecisionEntries(projectRoot) {
+export function readDecisionLogDetailed(projectRoot) {
     const filePath = join(projectRoot, LOG_DIR, LOG_FILE);
     if (!existsSync(filePath))
-        return [];
+        return { entries: [], invalidLines: 0 };
     let content;
     try {
         content = readFileSync(filePath, 'utf-8');
     }
     catch {
-        return [];
+        return { entries: [], invalidLines: 0 };
     }
-    const out = [];
+    const entries = [];
+    let invalidLines = 0;
     for (const line of content.split('\n')) {
         const trimmed = line.trim();
         if (trimmed.length === 0)
             continue;
         try {
-            out.push(JSON.parse(trimmed));
+            entries.push(JSON.parse(trimmed));
         }
         catch {
-            // skip the corrupt line, keep the rest
+            invalidLines += 1;
         }
     }
-    return out;
+    return { entries, invalidLines };
+}
+/**
+ * Read all entries from the decision log.
+ * A single corrupt line (partial write, hand-edit) is SKIPPED, not fatal —
+ * one bad line must never empty the whole history for every reader.
+ */
+export function readDecisionEntries(projectRoot) {
+    return readDecisionLogDetailed(projectRoot).entries;
 }
 /**
  * Register the `iterate_decision_log` tool.
@@ -108,6 +118,9 @@ export function readDecisionEntries(projectRoot) {
 export function registerDecisionLogTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_decision_log',
+        // `read` never writes; `append` extends the audit log → only read joins
+        // a parallel dispatch group.
+        isConcurrencySafe: (args) => args.operation === 'read',
         description: 'Append-only decision log for the iterate loop. ' +
             'Use `append` to record a round start, review finding, fix, validation result, or decision. ' +
             'Use `read` to retrieve all entries for review. ' +
@@ -156,6 +169,7 @@ export function registerDecisionLogTool(ctx) {
                 properties: {
                     operation: { type: 'string', required: true },
                     entryCount: { type: 'integer' },
+                    invalidLines: { type: 'integer' },
                     logPath: { type: 'string' },
                     entries: { type: 'json' },
                     success: { type: 'boolean' },
@@ -174,10 +188,11 @@ export function registerDecisionLogTool(ctx) {
             }
             const projectRoot = resolved.root;
             if (args.operation === 'read') {
-                const entries = readDecisionEntries(projectRoot);
+                const { entries, invalidLines } = readDecisionLogDetailed(projectRoot);
                 return {
                     operation: 'read',
                     entryCount: entries.length,
+                    invalidLines,
                     logPath: join(projectRoot, LOG_DIR, LOG_FILE),
                     entries: entries,
                 };

package/dist/tools/defense-events.js

@@ -72,6 +72,9 @@ function validateRecordInput(args) {
 export function registerDefenseEventsTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_defense_events',
+        // List/counts never write; only `record` persists an event → read shapes
+        // join a parallel dispatch group.
+        isConcurrencySafe: (args) => args.operation !== 'record',
         description: 'Query or record defense events: precondition failures, rollbacks, invariant violations, ' +
             'and assumption falsifications. ' +
             'List/counts return events with descriptions, outcomes, and summary counts; ' +

package/dist/tools/defense-store.js

@@ -6,6 +6,8 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { iterateDir } from "../paths.js";
+import { writeJsonAtomic } from "../atomic-fs.js";
 const DEFENSE_EVENTS_FILE = 'defense-events.json';
 /** Valid defense event types (must stay in sync with DefenseEventType). */
 const VALID_EVENT_TYPES = new Set([
@@ -70,13 +72,15 @@ export function readDefenseEvents(projectRoot) {
  * an event that was never persisted.
  */
 export function writeDefenseEvents(projectRoot, stream) {
-    const dirPath = path.join(projectRoot, '.iterate');
+    const dirPath = iterateDir(projectRoot);
     const filePath = path.join(dirPath, DEFENSE_EVENTS_FILE);
     try {
         if (!fs.existsSync(dirPath)) {
             fs.mkdirSync(dirPath, { recursive: true });
         }
-        fs.writeFileSync(filePath, JSON.stringify(stream, null, 2), 'utf-8');
+        // Atomic (temp + rename): a crash mid-write can never leave a truncated
+        // defense event stream behind.
+        writeJsonAtomic(filePath, stream);
     }
     catch (err) {
         return { ok: false, error: `unable to write ${filePath}: ${String(err)}` };

package/dist/tools/experience-bank.js

@@ -67,6 +67,9 @@ function normalizeExperienceInput(raw) {
 export function registerExperienceBankTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_experience',
+        // List/search/get never write; only `add` upserts the bank → read shapes
+        // join a parallel dispatch group.
+        isConcurrencySafe: (args) => args.operation !== 'add',
         description: 'Query or extend the experience bank: browse/search historical fixes and patterns, ' +
             'or record a new verified fix (operation:"add"). ' +
             'List/search/get return matching entries with hit counts, verified fixes, and related context. ' +

package/dist/tools/experience-store.js

@@ -6,6 +6,8 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { iterateDir } from "../paths.js";
+import { writeJsonAtomic } from "../atomic-fs.js";
 const EXPERIENCE_FILE = 'experience.json';
 /** Default empty experience bank. */
 function emptyBank() {
@@ -37,13 +39,15 @@ export function readExperienceBank(projectRoot) {
  * an entry that was never persisted.
  */
 export function writeExperienceBank(projectRoot, bank) {
-    const dirPath = path.join(projectRoot, '.iterate');
+    const dirPath = iterateDir(projectRoot);
     const filePath = path.join(dirPath, EXPERIENCE_FILE);
     try {
         if (!fs.existsSync(dirPath)) {
             fs.mkdirSync(dirPath, { recursive: true });
         }
-        fs.writeFileSync(filePath, JSON.stringify(bank, null, 2), 'utf-8');
+        // Atomic (temp + rename): a crash mid-write can never leave a truncated
+        // experience bank behind.
+        writeJsonAtomic(filePath, bank);
     }
     catch (err) {
         return { ok: false, error: `unable to write ${filePath}: ${String(err)}` };