iterate-plugin 3.4.1 → 3.5.1

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";
@@ -24,6 +25,7 @@ import { runWithJob } from "../jobs.js";
 import { countTouchedMethods } from "../method-scope.js";
 import { fixBackupPath, fixRegistryPath, fixesDir } from "../paths.js";
 import { appendDecisionEntry } from "./decision-log.js";
+import { markFixRolledBackInTranscript } from "./transcript.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 /** Upper bound for a single fix `content` payload (characters). */
 export const MAX_FIX_CONTENT_CHARS = 1_000_000;
@@ -276,6 +278,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 +461,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 +479,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 +527,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 +631,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 +698,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)}` };
@@ -678,6 +709,11 @@ export function registerRollbackTool(ctx) {
                 type: 'revert',
                 data: { id, file: record.finding.file, revertedDiff: record.diffSummary },
             });
+            // Mirror the reversal into the persisted observatory transcript (F4) so
+            // the client no longer shows a rolled-back fix as "成功". Best-effort:
+            // a missing/corrupt transcript is left untouched and never breaks the
+            // rollback flow.
+            await markFixRolledBackInTranscript(projectRoot, id);
             return { ok: true, id, file: record.finding.file };
         },
     }));

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 ?? [];

package/dist/tools/quality-gate.js

@@ -8,7 +8,7 @@
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
-import { readQualityGate, writeQualityGate, computeQualityGate } from "./quality-store.js";
+import { readQualityGate, writeQualityGate, computeQualityGate, clearQualityGate } from "./quality-store.js";
 /** Validate a single finding object; returns true when well-formed. */
 function isValidFinding(raw) {
     if (!raw || typeof raw !== 'object')
@@ -59,16 +59,21 @@ function sanitizeRoundSeries(raw) {
 export function registerQualityGateTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_quality_gate',
+        // `read` never writes; `compute` persists the snapshot → only read
+        // joins a parallel dispatch group.
+        isConcurrencySafe: (args) => args.operation === 'read',
         description: 'Query or write the quality gate status: dimension convergence rates, verification pass rates, ' +
             'and overall PASS/FAIL status. ' +
             'Operation "read" (default) returns the persisted machine-readable quality certificate. ' +
             'Operation "compute" computes a fresh snapshot from this round\'s findings/validation results, ' +
-            'persists it to .iterate/quality-gate.json, and returns it.',
+            'persists it to .iterate/quality-gate.json, and returns it. ' +
+            'Operation "clear" removes the persisted certificate (use it to reset a stale gate before ' +
+            'starting a fresh iteration).',
         parameters: {
             operation: {
                 type: 'string',
-                description: 'Operation: read (load persisted certificate) or compute (recompute + persist). Default: read.',
-                enum: ['read', 'compute'],
+                description: 'Operation: read (load persisted certificate), compute (recompute + persist), or clear (remove the persisted certificate). Default: read.',
+                enum: ['read', 'compute', 'clear'],
             },
             dimensions: {
                 type: 'array',
@@ -134,6 +139,9 @@ export function registerQualityGateTool(ctx) {
                 if (operation === 'compute') {
                     lines.push('', 'Quality gate snapshot computed and persisted.');
                 }
+                if (operation === 'clear') {
+                    lines.push('', 'Quality gate certificate cleared — the gate will be recomputed on the next iteration.');
+                }
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
@@ -143,6 +151,18 @@ export function registerQualityGateTool(ctx) {
                 return { ok: false, kind: 'quality_gate', error: resolved.reason };
             const projectRoot = resolved.root;
             const operation = typeof args.operation === 'string' ? args.operation : 'read';
+            if (operation === 'clear') {
+                const result = clearQualityGate(projectRoot);
+                if (!result.ok) {
+                    return { ok: false, kind: 'quality_gate', operation: 'clear', error: result.error };
+                }
+                return {
+                    ok: true,
+                    kind: 'quality_gate',
+                    operation: 'clear',
+                    snapshot: readQualityGate(projectRoot),
+                };
+            }
             if (operation === 'compute') {
                 const dimensions = Array.isArray(args.dimensions)
                     ? args.dimensions.filter((d) => typeof d === 'string' && d.length > 0)

package/dist/tools/quality-store.js

@@ -7,6 +7,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { writeJsonAtomic } from "../atomic-fs.js";
 const QUALITY_GATE_FILE = 'quality-gate.json';
 /** Default empty quality gate snapshot. */
 function emptySnapshot() {
@@ -96,13 +97,31 @@ export function writeQualityGate(projectRoot, snapshot) {
         if (!fs.existsSync(dirPath)) {
             fs.mkdirSync(dirPath, { recursive: true });
         }
-        fs.writeFileSync(filePath, JSON.stringify(snapshot, null, 2), 'utf-8');
+        writeJsonAtomic(filePath, snapshot);
     }
     catch (err) {
         return { ok: false, error: `unable to write ${filePath}: ${String(err)}` };
     }
     return { ok: true };
 }
+/**
+ * Clear the persisted quality gate certificate (`.iterate/quality-gate.json`).
+ * Returns whether a file existed and was removed, or a structured error when
+ * the removal fails — a stale FAIL certificate must never silently persist.
+ */
+export function clearQualityGate(projectRoot) {
+    const filePath = path.join(projectRoot, '.iterate', QUALITY_GATE_FILE);
+    const existed = fs.existsSync(filePath);
+    if (!existed)
+        return { ok: true, existed: false };
+    try {
+        fs.rmSync(filePath, { force: true });
+    }
+    catch (err) {
+        return { ok: false, error: `unable to remove ${filePath}: ${String(err)}` };
+    }
+    return { ok: true, existed: true };
+}
 /**
  * Compute the convergence rate for a dimension.
  *

package/dist/tools/transcript.js

@@ -18,8 +18,9 @@
  * tmp+rename so a crashed writer never leaves a corrupt manifest.
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { writeTextAtomicAsync } from "../atomic-fs.js";
 import { dirname } from 'node:path';
 import { loadEffectiveConfig, resolveProjectRootForExec, } from "../config-loader.js";
 import { transcriptPath } from "../paths.js";
@@ -96,6 +97,9 @@ function normalizeFix(input) {
 export function registerTranscriptTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_transcript',
+        // `read` never writes; `capture`/`nudge` persist transcript state → only
+        // read joins a parallel dispatch group.
+        isConcurrencySafe: (args) => args.operation === 'read',
         description: 'Runtime-observatory transcript for the iterate workflow. ' +
             '`read` returns the current persisted transcript manifest (per-reviewer threads, ' +
             'convergence series, findings, fixes, checkpoint, timeline, and any steering nudge ' +
@@ -322,10 +326,39 @@ function rehydrateBuilder(manifest, approval) {
         builder.finish();
     return builder;
 }
-/** Atomically persist a manifest (tmp + rename) under `.iterate/`. */
+/** Atomically persist a manifest (unique temp + rename) under `.iterate/`. */
 async function persist(file, manifest) {
     await mkdir(dirname(file), { recursive: true });
-    const tmp = `${file}.tmp`;
-    await writeFile(tmp, JSON.stringify(manifest, null, 2), 'utf-8');
-    await rename(tmp, file);
+    await writeTextAtomicAsync(file, JSON.stringify(manifest, null, 2));
+}
+/**
+ * Mark one applied fix as rolled back in the PERSISTED transcript, so the
+ * client observatory (F4 fix/rollback tab) reflects the reversal instead of
+ * showing the fix as still "成功" after a rollback.
+ *
+ * Best-effort and fail-safe: a missing/corrupt transcript is ignored, and a
+ * persistence failure never throws into the caller (rollback itself is the
+ * primary operation; the transcript is a secondary UI projection).
+ *
+ * @returns true when a transcript existed and was updated.
+ */
+export async function markFixRolledBackInTranscript(projectRoot, id) {
+    const file = transcriptPath(projectRoot);
+    if (!existsSync(file))
+        return false;
+    try {
+        const parsed = JSON.parse(await readFile(file, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.fixes))
+            return false;
+        const { config } = loadEffectiveConfig(projectRoot);
+        const approval = config.observatory?.approval ?? 'ask';
+        const builder = rehydrateBuilder(parsed, approval);
+        builder.markFixRolledBack(id);
+        await persist(file, builder.serialize());
+        return true;
+    }
+    catch {
+        // Never let the secondary transcript write break the rollback flow.
+        return false;
+    }
 }

package/dist/tools/triage.js

@@ -1,8 +1,9 @@
-import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import yaml from 'js-yaml';
 import { resolveProjectRootForExec } from "../config-loader.js";
+import { writeTextAtomic } from "../atomic-fs.js";
 const CONFIG_FILE = 'iterate.config.yaml';
 /** Personalization key that holds the known-intentional list. */
 const PERSONALIZATION_KEY = 'personalization';
@@ -191,7 +192,7 @@ function applyEntries(projectRoot, incoming) {
     }
     const yamlText = yaml.dump(nextConfig, { noRefs: true });
     try {
-        writeFileSync(configPath, yamlText, 'utf-8');
+        writeTextAtomic(configPath, yamlText);
     }
     catch (err) {
         // Rollback: restore the backup, or REMOVE the file we just created when
@@ -231,6 +232,9 @@ function applyEntries(projectRoot, incoming) {
 export function registerTriageTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_triage',
+        // `list` is a pure config read; `apply` rewrites iterate.config.yaml →
+        // only list joins a parallel dispatch group.
+        isConcurrencySafe: (args) => args.operation === 'list',
         description: 'Manage `personalization.known_intentional` entries in iterate.config.yaml. ' +
             'Use `apply` to write back triage verdicts (entries where the reviewer said "known intentional") so ' +
             'future review rounds filter them out. Entries are deduped by file|dimension|line and the config is ' +

package/dist/tools/validate.js

@@ -19,8 +19,14 @@ export function clampTimeout(ms) {
 /**
  * Run a single shell command with timeout and return structured results.
  * Pure function (no side effects beyond the exec call).
+ *
+ * `signal` (the caller's `exec.signal` per the dsh tools contract) is forwarded
+ * to the child process so a cancelled tool call kills the running command
+ * instead of pinning the dispatch open until the timeout elapses. The result
+ * distinguishes "cancelled by the caller" (`canceled: true`) from "ran past
+ * `timeoutMs`" (`timedOut: true`).
  */
-async function runCommand(command, cwd, timeoutMs) {
+export async function runCommand(command, cwd, timeoutMs, signal) {
     const start = performance.now();
     return new Promise((resolve) => {
         exec(command, {
@@ -28,18 +34,23 @@ async function runCommand(command, cwd, timeoutMs) {
             timeout: timeoutMs,
             maxBuffer: 10 * 1024 * 1024, // 10 MB
             env: { ...process.env, PAGER: 'cat' },
+            signal,
         }, (error, stdout, stderr) => {
             const durationMs = Math.round(performance.now() - start);
             // error.code is the exit code when the command ran; when the binary
             // cannot be spawned Node sets error.code to a STRING ('ENOENT' etc).
             // Coerce to a number so the integer output schema is never violated.
             const exitCode = typeof error?.code === 'number' ? error.code : (error ? 1 : 0);
+            const canceled = signal?.aborted === true;
             resolve({
                 command,
                 exitCode,
                 stdout: stdout ?? '',
                 stderr: stderr ?? '',
-                timedOut: error?.killed === true,
+                // A caller cancellation also kills the child (killed === true), but
+                // that is not a timeout — only report timedOut for the deadline path.
+                timedOut: error?.killed === true && !canceled,
+                canceled,
                 durationMs,
             });
         });
@@ -53,6 +64,19 @@ async function runCommand(command, cwd, timeoutMs) {
 export function registerValidateTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_validate',
+        // Pending-call card: render the pending validation as a terminal card.
+        // Pure — derived from args only; no `cwd` (the UI bridge resolves the
+        // relative command against the session workspace).
+        presentCall: (args) => {
+            const a = args;
+            if (typeof a.command !== 'string' || a.command.length === 0)
+                return undefined;
+            return {
+                card: 'terminal',
+                title: a.command,
+                description: 'Run a preconfigured iterate validation command (exact match on validation.commands).',
+            };
+        },
         description: 'Run a validation command that is PRECONFIGURED in iterate.config.yaml `validation.commands`. ' +
             'The command must exactly match one of the configured commands (they are the only ones the user trusts). ' +
             'Returns exit code, stdout, stderr, and duration. ' +
@@ -83,6 +107,7 @@ export function registerValidateTool(ctx) {
                     stdout: { type: 'string', required: true },
                     stderr: { type: 'string', required: true },
                     timedOut: { type: 'boolean', required: true },
+                    canceled: { type: 'boolean', required: true },
                     durationMs: { type: 'integer', required: true },
                     rejectReason: { type: 'string' },
                 },
@@ -96,6 +121,7 @@ export function registerValidateTool(ctx) {
                             `Exit code: ${value.exitCode}`,
                             `Duration: ${value.durationMs}ms`,
                             value.timedOut ? '⚠ Timed out' : '',
+                            value.canceled ? '⚠ Cancelled before completion' : '',
                             '',
                             value.stdout ? `[stdout]\n${value.stdout}` : '',
                             value.stderr ? `[stderr]\n${value.stderr}` : '',
@@ -116,6 +142,7 @@ export function registerValidateTool(ctx) {
                     stdout: '',
                     stderr: '',
                     timedOut: false,
+                    canceled: false,
                     durationMs: 0,
                     rejectReason: resolved.reason,
                 };
@@ -137,6 +164,7 @@ export function registerValidateTool(ctx) {
                     stdout: '',
                     stderr: '',
                     timedOut: false,
+                    canceled: false,
                     durationMs: 0,
                     rejectReason: (source === 'defaults'
                         ? 'No iterate.config.yaml at project root — running on built-in defaults, which configure NO trusted validation commands. '
@@ -152,12 +180,13 @@ export function registerValidateTool(ctx) {
                     stdout: '',
                     stderr: '',
                     timedOut: false,
+                    canceled: false,
                     durationMs: 0,
                     rejectReason: `Command must exactly match a command predefined in iterate.config.yaml validation.commands. ` +
                         `Allowed commands: ${predefinedCommands.join(' | ')}`,
                 };
             }
-            const result = await runCommand(args.command, projectRoot, timeout);
+            const result = await runCommand(args.command, projectRoot, timeout, exec.signal);
             return {
                 allowed: true,
                 ...result,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "3.4.1",
+  "version": "3.5.1",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness with quality command center and experience bank (v3.3). Features: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus dry-run pure-review mode, quality gate compute/persist, writable experience bank, defense events stream (record + bilingual labels), and native command buttons — with a live quality command center (F8/F9/F10 render real session data), §8 assign-fix instruction, and task_mode indicator wired end to end.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,10 @@
         "0.1.2-alpha.4": "compatible",
         "0.1.2-alpha.5": "compatible",
         "0.1.2-rc.1": "compatible",
-        "0.1.3-alpha.1": "compatible"
+        "0.1.3-alpha.1": "compatible",
+        "0.1.5-alpha.1": "compatible",
+        "0.1.5-alpha.2": "compatible",
+        "0.1.5-rc.1": "compatible"
       }
     },
     "client": {

package/src/atomic-fs.ts

@@ -0,0 +1,83 @@
+/**
+ * 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: string): void {
+  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: string): Promise<void> {
+  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: string): string {
+  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: string, data: string): void {
+  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: string, data: string): Promise<void> {
+  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: string, value: unknown): void {
+  writeTextAtomic(filePath, JSON.stringify(value, null, 2))
+}