iterate-plugin 3.4.0 → 3.5.0

package/src/tools/experience-store.ts

@@ -7,6 +7,8 @@
 
 import * as fs from 'node:fs'
 import * as path from 'node:path'
+import { iterateDir } from '../paths.ts'
+import { writeJsonAtomic } from '../atomic-fs.ts'
 import type { ExperienceBank, ExperienceEntry } from '../types.ts'
 
 const EXPERIENCE_FILE = 'experience.json'
@@ -45,14 +47,16 @@ export function writeExperienceBank(
   projectRoot: string,
   bank: ExperienceBank,
 ): { ok: true } | { ok: false; error: string } {
-  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/src/tools/fix.ts

@@ -17,7 +17,8 @@
  *   - 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.ts'
 import { join, sep } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
@@ -277,6 +278,19 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
   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 as { file?: unknown; content?: unknown }
+        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`. ' +
@@ -454,7 +468,7 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         }
 
         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)}` }
         }
@@ -472,7 +486,7 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         }
         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
           // exists, so a later rollback/diff could never see it and a retry would
@@ -524,6 +538,9 @@ export function registerDiffTool(ctx: { tools: { register: (def: ReturnType<type
   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.',
@@ -627,6 +644,17 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
   ctx.tools.register(
     defineTool({
       name: 'iterate_rollback',
+      // Pending-call card: which fix is about to be reverted.
+      presentCall: (args) => {
+        const a = args as { id?: unknown }
+        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, ' +
@@ -683,7 +711,7 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
 
         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/src/tools/history.ts

@@ -80,6 +80,9 @@ export function registerHistoryTool(ctx: { tools: { register: (def: ReturnType<t
   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). ' +

package/src/tools/prune.ts

@@ -11,6 +11,8 @@
  *   - 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.
@@ -18,11 +20,12 @@
  *   - 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 type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
+import { writeTextAtomic, writeJsonAtomic } from '../atomic-fs.ts'
 import { readDecisionEntries, appendDecisionEntry } from './decision-log.ts'
 import { readRegistry, removeRecord, recomputeRoundCounts } from './fix.ts'
 import { iterateDir, fixesDir, checkpointPath, fixRegistryPath } from '../paths.ts'
@@ -48,6 +51,26 @@ export function cutoffTimestamp(retainDays: number): string {
   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: string): boolean {
+  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.
@@ -59,6 +82,7 @@ export function inspectPrune(
   oldLogEntries: number
   hasCheckpoint: boolean
   staleBackups: string[]
+  staleTemps: string[]
   emptyRounds: number[]
   totalLogEntries: number
   registryRounds: number
@@ -100,10 +124,18 @@ export function inspectPrune(
     .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,
@@ -122,6 +154,7 @@ export function executePrune(
   deletedLogEntries: number
   deletedCheckpoint: boolean
   deletedBackups: string[]
+  deletedTemps: string[]
   trimmedEmptyRounds: number
   errors: string[]
 } {
@@ -130,6 +163,7 @@ export function executePrune(
     deletedLogEntries: 0,
     deletedCheckpoint: false,
     deletedBackups: [] as string[],
+    deletedTemps: [] as string[],
     trimmedEmptyRounds: 0,
     errors: [] as string[],
   }
@@ -142,9 +176,7 @@ export function executePrune(
     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) {
     result.errors.push(`failed to rewrite decision log: ${String(err)}`)
@@ -184,13 +216,23 @@ export function executePrune(
         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
 }
 
@@ -206,7 +248,8 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
       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: {
@@ -246,6 +289,7 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
               `  Decision-log entries to remove: ${report?.oldLogEntries ?? '?'} (of ${report?.totalLogEntries ?? '?'})`,
               `  Checkpoint to delete: ${report?.hasCheckpoint ? 'yes' : 'none'}`,
               `  Stale backups to delete: ${(report?.staleBackups as string[] | undefined)?.length ?? 0}`,
+              `  Stray temp files to delete: ${(report?.staleTemps as string[] | undefined)?.length ?? 0}`,
               `  Empty rounds to trim: ${(report?.emptyRounds as number[] | undefined)?.length ?? 0}`,
               '',
               'Pass dryRun:false to execute the prune.',
@@ -257,6 +301,7 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
             `  Deleted ${result?.deletedLogEntries ?? 0} old log entries.`,
             `  Checkpoint deleted: ${result?.deletedCheckpoint ? 'yes' : 'no'}`,
             `  Deleted ${(result?.deletedBackups as string[] | undefined)?.length ?? 0} stale backups.`,
+            `  Deleted ${(result?.deletedTemps as string[] | undefined)?.length ?? 0} stray temp files.`,
             `  Trimmed ${result?.trimmedEmptyRounds ?? 0} empty rounds.`,
           ]
           const errs = (result?.errors as string[] | undefined) ?? []

package/src/tools/quality-gate.ts

@@ -64,6 +64,9 @@ export function registerQualityGateTool(ctx: { tools: { register: (def: ReturnTy
   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 as { operation?: unknown }).operation === 'read',
       description:
         'Query or write the quality gate status: dimension convergence rates, verification pass rates, ' +
         'and overall PASS/FAIL status. ' +

package/src/tools/quality-store.ts

@@ -8,6 +8,7 @@
 
 import * as fs from 'node:fs'
 import * as path from 'node:path'
+import { writeJsonAtomic } from '../atomic-fs.ts'
 import type { QualityGateSnapshot, QualityGateDimension } from '../types.ts'
 
 const QUALITY_GATE_FILE = 'quality-gate.json'
@@ -108,7 +109,7 @@ export function writeQualityGate(
     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)}` }
   }

package/src/tools/transcript.ts

@@ -19,8 +19,9 @@
  */
 
 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.ts'
 import { dirname } from 'node:path'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import {
@@ -107,6 +108,9 @@ 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 as { operation?: unknown }).operation === 'read',
       description:
         'Runtime-observatory transcript for the iterate workflow. ' +
         '`read` returns the current persisted transcript manifest (per-reviewer threads, ' +
@@ -332,10 +336,8 @@ function rehydrateBuilder(manifest: TranscriptManifest, approval: 'ask' | 'deny'
   return builder
 }
 
-/** Atomically persist a manifest (tmp + rename) under `.iterate/`. */
+/** Atomically persist a manifest (unique temp + rename) under `.iterate/`. */
 async function persist(file: string, manifest: TranscriptManifest): Promise<void> {
   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))
 }

package/src/tools/triage.ts

@@ -1,9 +1,10 @@
-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 type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import yaml from 'js-yaml'
 import { resolveProjectRootForExec } from '../config-loader.ts'
+import { writeTextAtomic } from '../atomic-fs.ts'
 import type { KnownIntentional } from '../types.ts'
 
 const CONFIG_FILE = 'iterate.config.yaml'
@@ -229,7 +230,7 @@ function applyEntries(
 
   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
     // there was no prior config — an empty file left behind would poison all
@@ -268,6 +269,9 @@ export function registerTriageTool(ctx: { tools: { register: (def: ReturnType<ty
   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 as { operation?: unknown }).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 ' +

package/src/tools/validate.ts

@@ -28,11 +28,18 @@ export function clampTimeout(ms: number | undefined): number {
 /**
  * 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(
+export async function runCommand(
   command: string,
   cwd: string,
   timeoutMs: number,
+  signal?: AbortSignal,
 ): Promise<ValidationResult> {
   const start = performance.now()
   return new Promise<ValidationResult>((resolve) => {
@@ -43,6 +50,7 @@ async function runCommand(
         timeout: timeoutMs,
         maxBuffer: 10 * 1024 * 1024, // 10 MB
         env: { ...process.env, PAGER: 'cat' },
+        signal,
       },
       (error, stdout, stderr) => {
         const durationMs = Math.round(performance.now() - start)
@@ -50,12 +58,16 @@ async function runCommand(
         // 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,
         })
       },
@@ -72,6 +84,18 @@ export function registerValidateTool(ctx: { tools: { register: (def: ReturnType<
   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 as { command?: unknown }
+        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). ' +
@@ -105,6 +129,7 @@ export function registerValidateTool(ctx: { tools: { register: (def: ReturnType<
             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' },
           },
@@ -118,6 +143,7 @@ export function registerValidateTool(ctx: { tools: { register: (def: ReturnType<
                   `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}` : '',
@@ -139,6 +165,7 @@ export function registerValidateTool(ctx: { tools: { register: (def: ReturnType<
             stdout: '',
             stderr: '',
             timedOut: false,
+            canceled: false,
             durationMs: 0,
             rejectReason: resolved.reason,
           }
@@ -161,6 +188,7 @@ export function registerValidateTool(ctx: { tools: { register: (def: ReturnType<
             stdout: '',
             stderr: '',
             timedOut: false,
+            canceled: false,
             durationMs: 0,
             rejectReason:
               (source === 'defaults'
@@ -177,6 +205,7 @@ export function registerValidateTool(ctx: { tools: { register: (def: ReturnType<
             stdout: '',
             stderr: '',
             timedOut: false,
+            canceled: false,
             durationMs: 0,
             rejectReason:
               `Command must exactly match a command predefined in iterate.config.yaml validation.commands. ` +
@@ -184,7 +213,7 @@ export function registerValidateTool(ctx: { tools: { register: (def: ReturnType<
           }
         }
 
-        const result = await runCommand(args.command, projectRoot, timeout)
+        const result = await runCommand(args.command, projectRoot, timeout, exec.signal)
         return {
           allowed: true,
           ...result,

package/src/types.ts

@@ -74,6 +74,8 @@ export interface ValidationResult {
   stdout: string
   stderr: string
   timedOut: boolean
+  /** True when the caller's AbortSignal fired before the command finished. */
+  canceled: boolean
   durationMs: number
 }