iterate-plugin 3.7.0 → 3.8.0

package/src/tools/transcript.ts

@@ -24,6 +24,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { mkdir, readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { writeTextAtomicAsync } from '../atomic-fs.ts'
+import { withProjectLock } from '../file-lock.ts'
 import { dirname } from 'node:path'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import {
@@ -81,7 +82,7 @@ function normalizeCheckpoint(input: unknown): TranscriptManifest['checkpoint'] {
   const round = typeof c.round === 'number' && Number.isFinite(c.round) ? c.round : 0
   if (round <= 0) return null
   return {
-    mode: c.mode === 'dry-run' || c.mode === 'normal' ? c.mode : 'normal',
+    mode: c.mode === 'dry-run' || c.mode === 'normal' ? c.mode : null,
     round,
     maxRounds: typeof c.maxRounds === 'number' && Number.isFinite(c.maxRounds) ? c.maxRounds : 0,
     fixedCount: typeof c.fixedCount === 'number' && Number.isFinite(c.fixedCount) ? c.fixedCount : 0,
@@ -215,7 +216,22 @@ export function registerTranscriptTool(ctx: {
             'the run console can show which commands ran and whether they passed.',
         },
         refReadFiles: { type: 'json', description: 'For `capture`: flat array of all read files across rounds (optional).' },
-        stoppedReason: { type: 'string', description: 'For `capture`: why the run ended — "converged" | "max_rounds_reached" | "aborted_by_validation" | "aborted_by_config" | "schema_invalid" | "no_usable_reviewer_output" | "inconclusive". When omitted, derived from the convergence trend (trailing 0 = converged, otherwise = max_rounds_reached once a round ran).' },
+        stoppedReason: {
+          type: 'string',
+          // Enum guard: the label renderer keys off this value, so a stray or
+          // prototype-chain string (e.g. "__proto__") must not enter the tool.
+          // The render path additionally uses Object.hasOwn (defense for
+          // hand-edited manifests that bypass this schema).
+          enum: [
+            'converged',
+            'max_rounds_reached',
+            'aborted_by_validation',
+            'aborted_by_config',
+            'schema_invalid',
+            'no_usable_reviewer_output',
+            'inconclusive',
+          ],
+          description: 'For `capture`: why the run ended — "converged" | "max_rounds_reached" | "aborted_by_validation" | "aborted_by_config" | "schema_invalid" | "no_usable_reviewer_output" | "inconclusive". When omitted, derived from the convergence trend (trailing 0 = converged, otherwise = max_rounds_reached once a round ran).' },
         // `string | null` (NOT plain `type: 'string'`): dsh validates arguments
         // against the compiled schema BEFORE execute, and the docs — plus the
         // client's clear button — advertise `{"operation":"nudge","text":null}`.
@@ -311,49 +327,62 @@ export function registerTranscriptTool(ctx: {
         }
 
         if (args.operation === 'nudge') {
-          let manifest: TranscriptManifest | null = null
-          if (existsSync(file)) {
-            try {
-              const parsed = JSON.parse(await readFile(file, 'utf-8')) as unknown as TranscriptManifest
-              manifest = parsed
-            } catch {
-              manifest = null
+          // Read-modify-write across processes: a concurrent nudge in a sibling
+          // process would otherwise read the same manifest and write back over
+          // each other's steering text. Serialize on the shared transcript lock
+          // (same pattern as the config/triage writers). The body still awaits,
+          // so the lock is held across the read and write; a same-process
+          // re-entry degrades to unlocked (the advisory lock is per-pid), which
+          // is the documented best-effort fallback for a low-value projection.
+          return withProjectLock(projectRoot, 'transcript', async () => {
+            let manifest: TranscriptManifest | null = null
+            if (existsSync(file)) {
+              try {
+                const parsed = JSON.parse(await readFile(file, 'utf-8')) as unknown as TranscriptManifest
+                manifest = parsed
+              } catch {
+                manifest = null
+              }
             }
-          }
-          // Rehydrating a parsed-but-malformed manifest (e.g. `rounds: [null]`
-          // or a non-object) must never crash the nudge — degrade to a fresh
-          // builder so the steering text still lands. The fallback must keep
-          // the ORIGINAL run identity (mode/taskMode/goal/maxRounds) so a
-          // stray malformed field can never silently rewrite a dry-run run
-          // into a `normal` one.
-          const fallbackOpts = {
-            project: projectRoot,
-            mode: (manifest?.mode === 'dry-run' || manifest?.mode === 'normal' ? manifest.mode : null) as 'dry-run' | 'normal' | null,
-            taskMode: (manifest?.taskMode === 'code' || manifest?.taskMode === 'iterate' ? manifest.taskMode : null) as 'code' | 'iterate' | null,
-            approval,
-            goal: typeof manifest?.goal === 'string' ? manifest.goal : '',
-            maxRounds: typeof manifest?.maxRounds === 'number' ? manifest.maxRounds : 0,
-          }
-          let builder: ReviewTranscriptBuilder
-          if (manifest) {
-            try {
-              builder = rehydrateBuilder(manifest, approval)
-            } catch {
-              builder = new ReviewTranscriptBuilder(fallbackOpts)
+            // Rehydrating a parsed-but-malformed manifest (e.g. `rounds: [null]`
+            // or a non-object) must never crash the nudge — degrade to a fresh
+            // builder so the steering text still lands. The fallback must keep
+            // the ORIGINAL run identity (mode/taskMode/goal/maxRounds) so a
+            // stray malformed field can never silently rewrite a dry-run run
+            // into a `normal` one.
+            const fallbackOpts = {
+              project: projectRoot,
+              mode: (manifest?.mode === 'dry-run' || manifest?.mode === 'normal' ? manifest.mode : null) as 'dry-run' | 'normal' | null,
+              taskMode: (manifest?.taskMode === 'code' || manifest?.taskMode === 'iterate' ? manifest.taskMode : null) as 'code' | 'iterate' | null,
+              approval,
+              goal: typeof manifest?.goal === 'string' ? manifest.goal : '',
+              maxRounds: typeof manifest?.maxRounds === 'number' ? manifest.maxRounds : 0,
             }
-          } else {
-            builder = new ReviewTranscriptBuilder({ project: projectRoot, mode: 'normal', approval })
-          }
-          builder.setNudge(typeof args.text === 'string' && args.text.trim() ? args.text : null)
-          const persisted = await persistChecked(file, builder.serialize())
-          if (!persisted.ok) {
-            return { operation: 'nudge', updated: false, error: persisted.error }
-          }
-          return {
-            operation: 'nudge',
-            updated: true,
-            transcript: builder.serialize() as unknown as JsonValue,
-          }
+            let builder: ReviewTranscriptBuilder
+            if (manifest) {
+              try {
+                builder = rehydrateBuilder(manifest, approval)
+              } catch {
+                builder = new ReviewTranscriptBuilder(fallbackOpts)
+              }
+            } else {
+              // No manifest yet: the run's mode is genuinely unknown at nudge
+              // time (capture sets it). Recording `mode: 'normal'` here would
+              // rewrite a dry-run run into a `normal` one in the status/badge
+              // until capture lands — `null` honestly says "not captured yet".
+              builder = new ReviewTranscriptBuilder({ project: projectRoot, mode: null, approval })
+            }
+            builder.setNudge(typeof args.text === 'string' && args.text.trim() ? args.text : null)
+            const persisted = await persistChecked(file, builder.serialize())
+            if (!persisted.ok) {
+              return { operation: 'nudge', updated: false, error: persisted.error }
+            }
+            return {
+              operation: 'nudge',
+              updated: true,
+              transcript: builder.serialize() as unknown as JsonValue,
+            }
+          })
         }
 
         // capture

package/src/tools/triage.ts

@@ -6,6 +6,7 @@ import yaml from 'js-yaml'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import { writeTextAtomic } from '../atomic-fs.ts'
 import { configBackupSuffix } from '../config-write.ts'
+import { withProjectLock } from '../file-lock.ts'
 import { WHOLE_FILE_LINE } from '../evidence.ts'
 import type { KnownIntentional } from '../types.ts'
 
@@ -268,56 +269,62 @@ function applyEntries(
   error: string
 } {
   const configPath = join(projectRoot, CONFIG_FILE)
-  let config: Record<string, unknown>
-  try {
-    config = readConfigFile(configPath)
-  } catch (err) {
-    // The file exists but is malformed — refuse to overwrite user data.
-    return { ok: false, error: `Failed to read config: ${String(err)}` }
-  }
-  const existing = readKnownIntentional(config)
-  const { merged, added, skipped, dropped } = mergeKnownIntentional(existing, incoming)
-  const nextConfig = buildConfigWithKnownIntentional(config, merged)
+  // Serialize against `iterate_config write` (SAME lock name) so a triage apply
+  // and a config write on one project cannot interleave their read-modify-write
+  // and silently drop each other's updates. The lock spans read → merge →
+  // backup → write → backup-prune so the whole cycle is atomic.
+  return withProjectLock(projectRoot, 'config-write', () => {
+    let config: Record<string, unknown>
+    try {
+      config = readConfigFile(configPath)
+    } catch (err) {
+      // The file exists but is malformed — refuse to overwrite user data.
+      return { ok: false, error: `Failed to read config: ${String(err)}` }
+    }
+    const existing = readKnownIntentional(config)
+    const { merged, added, skipped, dropped } = mergeKnownIntentional(existing, incoming)
+    const nextConfig = buildConfigWithKnownIntentional(config, merged)
 
-  const hadFile = existsSync(configPath)
-  const backupPath = hadFile ? `${configPath}.bak-${backupSuffix()}` : null
+    const hadFile = existsSync(configPath)
+    const backupPath = hadFile ? `${configPath}.bak-${backupSuffix()}` : null
+
+    if (backupPath) {
+      try {
+        copyFileSync(configPath, backupPath)
+      } catch (err) {
+        return {
+          ok: false,
+          error: `Failed to create backup: ${String(err)}`,
+        }
+      }
+    }
 
-  if (backupPath) {
+    const yamlText = yaml.dump(nextConfig, { noRefs: true })
     try {
-      copyFileSync(configPath, backupPath)
+      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
+      // future config reads (empty YAML is not a valid mapping).
+      let rollbackError = ''
+      try {
+        if (backupPath) copyFileSync(backupPath, configPath)
+        else if (existsSync(configPath)) rmSync(configPath, { force: true })
+      } catch (rbErr) {
+        rollbackError = `; rollback also failed: ${String(rbErr)}`
+      }
       return {
         ok: false,
-        error: `Failed to create backup: ${String(err)}`,
+        error: `Failed to write config: ${String(err)}${rollbackError}`,
       }
     }
-  }
-
-  const yamlText = yaml.dump(nextConfig, { noRefs: true })
-  try {
-    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
-    // future config reads (empty YAML is not a valid mapping).
-    let rollbackError = ''
-    try {
-      if (backupPath) copyFileSync(backupPath, configPath)
-      else if (existsSync(configPath)) rmSync(configPath, { force: true })
-    } catch (rbErr) {
-      rollbackError = `; rollback also failed: ${String(rbErr)}`
-    }
-    return {
-      ok: false,
-      error: `Failed to write config: ${String(err)}${rollbackError}`,
-    }
-  }
 
-  // Success: bound the accumulation of timestamped backups so a long-lived
-  // project never collects an unbounded pile of config snapshots.
-  if (backupPath) pruneOldConfigBackups(configPath)
+    // Success: bound the accumulation of timestamped backups so a long-lived
+    // project never collects an unbounded pile of config snapshots.
+    if (backupPath) pruneOldConfigBackups(configPath)
 
-  return { ok: true, added, skipped, dropped, count: merged.length, configPath, backupPath }
+    return { ok: true, added, skipped, dropped, count: merged.length, configPath, backupPath }
+  })
 }
 
 /**

package/src/transcript.ts

@@ -565,7 +565,7 @@ export class ReviewTranscriptBuilder {
       return
     }
     this.checkpoint = {
-      mode: state.mode === 'dry-run' || state.mode === 'normal' ? state.mode : 'normal',
+      mode: state.mode === 'dry-run' || state.mode === 'normal' ? state.mode : null,
       round: typeof state.round === 'number' ? state.round : 0,
       maxRounds: typeof state.maxRounds === 'number' ? state.maxRounds : 0,
       fixedCount: typeof state.fixedCount === 'number' ? state.fixedCount : 0,
@@ -804,7 +804,7 @@ function normalizeCheckpointRow(input: unknown): TranscriptCheckpoint | null {
   const round = typeof c.round === 'number' && Number.isFinite(c.round) ? c.round : 0
   if (round <= 0) return null
   return {
-    mode: c.mode === 'dry-run' || c.mode === 'normal' ? c.mode : 'normal',
+    mode: c.mode === 'dry-run' || c.mode === 'normal' ? c.mode : null,
     round: clampRoundValue(c.round),
     maxRounds: clampCountValue(c.maxRounds),
     fixedCount: clampCountValue(c.fixedCount),

package/src/types.ts

@@ -320,7 +320,7 @@ export interface TranscriptEntry {
 
 /** Checkpoint summary surfaced for resume actions (F5). */
 export interface TranscriptCheckpoint {
-  mode: 'dry-run' | 'normal'
+  mode: 'dry-run' | 'normal' | null
   round: number
   maxRounds: number
   fixedCount: number