iterate-plugin 3.4.1 → 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

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`）。真实的逐维度收敛率

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/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/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)}` };

package/dist/tools/fix.js

@@ -16,7 +16,8 @@
  *   - Backups are written before any write, so a failure never destroys data.
  *   - Atomicity is enforced against `config.atomic.max_lines` unless `force`.
  */
-import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
+import { writeJsonAtomic, writeTextAtomic } from "../atomic-fs.js";
 import { join, sep } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { loadEffectiveConfig, resolveProjectRootForExec } from "../config-loader.js";
@@ -276,6 +277,20 @@ function readProjectFile(projectRoot, file) {
 export function registerFixTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_fix',
+        // Pending-call card: surface the file about to change as an inline diff.
+        // oldText is null — a call-time presenter has no access to the file's
+        // prior content (an overwrite, per the presentation contract).
+        presentCall: (args) => {
+            const a = args;
+            if (typeof a.file !== 'string' || typeof a.content !== 'string')
+                return undefined;
+            return {
+                card: 'diff',
+                title: `Fix ${a.file}`,
+                diffs: [{ path: a.file, oldText: null, newText: a.content }],
+                locations: [{ path: a.file }],
+            };
+        },
         description: 'Apply ONE atomic fix to a file. Pass the target relative `file`, the finding that motivated ' +
             'the fix, the NEW full `content` of that file (after your edit), and the current `round`. ' +
             'The tool backs up the original, enforces the atomic `max_lines` and `max_adjacent_methods` thresholds (unless `force`), ' +
@@ -445,7 +460,7 @@ export function registerFixTool(ctx) {
                     return { ok: false, error: `failed to create backup: ${String(err)}` };
                 }
                 try {
-                    writeFileSync(target.resolved, args.content, 'utf-8');
+                    writeTextAtomic(target.resolved, args.content);
                 }
                 catch (err) {
                     return { ok: false, error: `failed to write file: ${String(err)}` };
@@ -463,7 +478,7 @@ export function registerFixTool(ctx) {
                 };
                 const nextRegistry = upsertRecord(registry, record);
                 try {
-                    writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(nextRegistry, null, 2), 'utf-8');
+                    writeJsonAtomic(fixRegistryPath(projectRoot), nextRegistry);
                 }
                 catch (err) {
                     // Registry write failed → the file was already modified but no record
@@ -511,6 +526,9 @@ export function registerFixTool(ctx) {
 export function registerDiffTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_diff',
+        // Read-only (never writes project files or plugin state) → safe to join
+        // a parallel dispatch group alongside other read-only sibling calls.
+        isConcurrencySafe: () => true,
         description: 'Show the changes made by iterate fixes. With `file`, returns the unified diff of the current ' +
             'file content vs its original (first backup). Without `file`, returns a summary of every fixed file.',
         parameters: {
@@ -612,6 +630,18 @@ export function registerDiffTool(ctx) {
 export function registerRollbackTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_rollback',
+        // Pending-call card: which fix is about to be reverted.
+        presentCall: (args) => {
+            const a = args;
+            if (typeof a.id !== 'string' || a.id.length === 0)
+                return undefined;
+            return {
+                card: 'generic',
+                title: `Rollback fix ${a.id}`,
+                kind: 'edit',
+                rawInput: { id: a.id },
+            };
+        },
         description: 'Revert a previously applied fix. Pass the fix `id` (returned by iterate_fix). ' +
             'The file is restored from the fix backup, the fix is removed from the registry, ' +
             'and a `revert` entry is appended to the decision log. Use when a round\'s validation fails.',
@@ -667,7 +697,7 @@ export function registerRollbackTool(ctx) {
             }
             const nextRegistry = removeRecord(registry, id);
             try {
-                writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(nextRegistry, null, 2), 'utf-8');
+                writeJsonAtomic(fixRegistryPath(projectRoot), nextRegistry);
             }
             catch (err) {
                 return { ok: false, error: `failed to update fix registry: ${String(err)}` };

package/dist/tools/history.js

@@ -64,6 +64,9 @@ export function summarizeFixRegistry(registry) {
 export function registerHistoryTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_history',
+        // Read-only audit view over on-disk state → safe to join a parallel
+        // dispatch group alongside other read-only sibling calls.
+        isConcurrencySafe: () => true,
         description: 'Read the iteration history: decision-log entries (optionally filtered by entry `type`, `since` ' +
             'timestamp, and a `limit`) plus a summary of the fix registry (per-round fixed/failed counts). ' +
             'Read-only — use it to review what the run did, audit a log, or inspect fixes.',

package/dist/tools/prune.js

@@ -11,16 +11,19 @@
  *   - Fix backups left over from old rounds (backups whose fix-id no longer
  *     appears in the registry).
  *   - Empty fix rounds (rounds with 0 records).
+ *   - Stray temp files left behind by a crashed atomic write (see
+ *     `isPrunableTemp` for the recognized naming conventions).
  *
  * Security model:
  *   - Only operates under the resolved project `.iterate/` directory.
  *   - dryRun=true by default — the caller must explicitly opt into deletion.
  *   - Each deletion is logged to the decision log (when not dry-run).
  */
-import { existsSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
+import { writeTextAtomic, writeJsonAtomic } from "../atomic-fs.js";
 import { readDecisionEntries, appendDecisionEntry } from "./decision-log.js";
 import { readRegistry, recomputeRoundCounts } from "./fix.js";
 import { iterateDir, fixesDir, checkpointPath, fixRegistryPath } from "../paths.js";
@@ -41,6 +44,28 @@ export function cutoffTimestamp(retainDays) {
     d.setDate(d.getDate() - retainDays);
     return d.toISOString();
 }
+/**
+ * Whether a file name inside `.iterate/` is a prunable leftover temp file.
+ *
+ * Recognized conventions (all written to the SAME directory as their target,
+ * so they can never be confused with real state files):
+ *   - `.<name>.tmp-<pid>-<rand>` — current atomic-fs.ts temp prefix;
+ *   - `.tmp-<pid>-<rand>`        — legacy temp prefix (older plugin builds);
+ *   - `<name>.tmp`               — legacy transcript.ts / live.ts temp suffix.
+ *
+ * Pure and exported for unit tests. A live writer's temp file is only visible
+ * to it (unique name), so deleting any match is always safe.
+ */
+export function isPrunableTemp(name) {
+    if (typeof name !== 'string' || name.length === 0 || name === '.' || name === '..')
+        return false;
+    if (name.startsWith('.tmp-'))
+        return true;
+    if (name.endsWith('.tmp'))
+        return true;
+    // .<basename>.tmp-<pid>-<rand>: starts with a dot and contains ".tmp-" after it.
+    return name.startsWith('.') && name.includes('.tmp-');
+}
 /**
  * Inspect the runtime state and report what would be pruned.
  * Pure (no deletions). Returns a structured report.
@@ -79,10 +104,17 @@ export function inspectPrune(projectRoot, retainDays) {
     const emptyRounds = registry.rounds
         .filter((r) => r.records.length === 0)
         .map((r) => r.round);
+    // 5. Stray atomic-write temp files left behind by a crashed writer. The
+    // unique prefix makes them recognizable and safe to delete — no live writer
+    // ever reads another writer's temp file.
+    const staleTemps = existsSync(iterateDir(projectRoot))
+        ? readdirSync(iterateDir(projectRoot)).filter((f) => isPrunableTemp(f)).sort()
+        : [];
     return {
         oldLogEntries,
         hasCheckpoint,
         staleBackups,
+        staleTemps,
         emptyRounds,
         totalLogEntries: entries.length,
         registryRounds: registry.rounds.length,
@@ -98,6 +130,7 @@ export function executePrune(projectRoot, retainDays, report) {
         deletedLogEntries: 0,
         deletedCheckpoint: false,
         deletedBackups: [],
+        deletedTemps: [],
         trimmedEmptyRounds: 0,
         errors: [],
     };
@@ -109,9 +142,7 @@ export function executePrune(projectRoot, retainDays, report) {
         result.deletedLogEntries = entries.length - kept.length;
         if (result.deletedLogEntries > 0) {
             const logPath = join(iterateDir(projectRoot), 'decision-log.jsonl');
-            const tmpPath = `${logPath}.tmp-${Date.now()}`;
-            writeFileSync(tmpPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n', 'utf-8');
-            renameSync(tmpPath, logPath);
+            writeTextAtomic(logPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n');
         }
     }
     catch (err) {
@@ -151,13 +182,23 @@ export function executePrune(projectRoot, retainDays, report) {
                 rounds: registry.rounds.filter((r) => !emptyRoundNos.has(r.round) || (r.records?.length ?? 0) > 0),
             };
             registry = recomputeRoundCounts(registry);
-            writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(registry, null, 2), 'utf-8');
+            writeJsonAtomic(fixRegistryPath(projectRoot), registry);
             result.trimmedEmptyRounds = report.emptyRounds.length;
         }
         catch (err) {
             result.errors.push(`failed to trim empty rounds: ${String(err)}`);
         }
     }
+    // 5. Remove stray atomic-write temp files.
+    for (const tmp of report.staleTemps) {
+        try {
+            rmSync(join(iterateDir(projectRoot), tmp), { force: true });
+            result.deletedTemps.push(tmp);
+        }
+        catch (err) {
+            result.errors.push(`failed to delete temp file ${tmp}: ${String(err)}`);
+        }
+    }
     return result;
 }
 /**
@@ -170,7 +211,8 @@ export function registerPruneTool(ctx) {
         name: 'iterate_prune',
         description: 'Inspect or clean up old iterate runtime artifacts (.iterate/). ' +
             'Defaults to dry-run (report-only, no deletion). Pass `dryRun: false` to actually prune. ' +
-            'Manages: old decision-log entries, stale checkpoints, orphaned fix backups, empty fix rounds. ' +
+            'Manages: old decision-log entries, stale checkpoints, orphaned fix backups, empty fix rounds, ' +
+            'and stray temp files left by crashed atomic writes. ' +
             'Each deletion is logged to the decision log.',
         parameters: {
             dryRun: {
@@ -210,6 +252,7 @@ export function registerPruneTool(ctx) {
                         `  Decision-log entries to remove: ${report?.oldLogEntries ?? '?'} (of ${report?.totalLogEntries ?? '?'})`,
                         `  Checkpoint to delete: ${report?.hasCheckpoint ? 'yes' : 'none'}`,
                         `  Stale backups to delete: ${report?.staleBackups?.length ?? 0}`,
+                        `  Stray temp files to delete: ${report?.staleTemps?.length ?? 0}`,
                         `  Empty rounds to trim: ${report?.emptyRounds?.length ?? 0}`,
                         '',
                         'Pass dryRun:false to execute the prune.',
@@ -221,6 +264,7 @@ export function registerPruneTool(ctx) {
                     `  Deleted ${result?.deletedLogEntries ?? 0} old log entries.`,
                     `  Checkpoint deleted: ${result?.deletedCheckpoint ? 'yes' : 'no'}`,
                     `  Deleted ${result?.deletedBackups?.length ?? 0} stale backups.`,
+                    `  Deleted ${result?.deletedTemps?.length ?? 0} stray temp files.`,
                     `  Trimmed ${result?.trimmedEmptyRounds ?? 0} empty rounds.`,
                 ];
                 const errs = result?.errors ?? [];