iterate-plugin 3.7.0 → 3.8.0

package/src/file-lock.ts

@@ -30,6 +30,7 @@
 import {
   closeSync,
   existsSync,
+  fstatSync,
   mkdirSync,
   openSync,
   readFileSync,
@@ -40,7 +41,14 @@ import {
 import { join } from 'node:path'
 
 const LOCK_DIR = '.iterate'
-const DEFAULT_WAIT_MS = 5000
+// Bounded wait before degrading to "proceed unlocked". `acquireProjectLock`
+// spins on `Atomics.wait`, which BLOCKS the single plugin thread for the whole
+// budget — so a long default wedges unrelated tool calls and the UI heartbeat
+// whenever a sibling process holds the lock. Healthy holders release in
+// microseconds, so 1000ms is very generous; anything slower is treated as
+// contention and degrades to the historical unlocked behavior rather than
+// stalling the event loop for five seconds.
+const DEFAULT_WAIT_MS = 1000
 const DEFAULT_STALE_MS = 10000
 const POLL_MS = 25
 
@@ -80,19 +88,28 @@ function lockFileName(name: string): string {
   return `.${name}.lock`
 }
 
+/** Outcome of a checked acquisition: whether the lock was actually TAKEN. */
+export interface AcquireLockResult {
+  acquired: boolean
+  release: () => void
+}
+
 /**
- * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`.
+ * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`,
+ * reporting whether it was actually taken.
  *
- * Returns a release function: always callable, idempotent, never throws.
- * A no-op (but callable) release is returned when the lock directory cannot be
- * created or the wait times out — callers then proceed unlocked, which is the
- * historical best-effort behavior, rather than failing the operation.
+ * The returned release function is always callable, idempotent, and never
+ * throws. `acquired:false` (with a no-op release) is returned when the lock
+ * directory cannot be created or the wait times out — callers then proceed
+ * unlocked, which is the historical best-effort behavior, rather than failing
+ * the operation. Callers that MUST hold the mutex (e.g. a log rewrite that
+ * renames the file) branch on `acquired` and refuse to run unlocked.
  */
-export function acquireProjectLock(
+export function acquireProjectLockChecked(
   projectRoot: string,
   name: string,
   options: LockOptions = {},
-): () => void {
+): AcquireLockResult {
   const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
     ? (options.waitMs as number)
     : DEFAULT_WAIT_MS
@@ -105,7 +122,7 @@ export function acquireProjectLock(
     try {
       mkdirSync(dir, { recursive: true })
     } catch {
-      return () => {}
+      return { acquired: false, release: () => {} }
     }
   }
   const lockPath = join(dir, lockFileName(name))
@@ -115,7 +132,7 @@ export function acquireProjectLock(
     try {
       fd = openSync(lockPath, 'wx')
     } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return () => {}
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return { acquired: false, release: () => {} }
       // Lock exists — steal it when the owner is gone or the lock is ancient.
       let stale = false
       try {
@@ -136,11 +153,20 @@ export function acquireProjectLock(
         }
         continue
       }
-      if (Date.now() - start > waitMs) return () => {}
+      if (Date.now() - start > waitMs) return { acquired: false, release: () => {} }
       sleepSync(POLL_MS)
       continue
     }
-    // Owned the lock: stamp the holder pid, then release once on return.
+    // Owned the lock: capture the created inode (for the ownership-checked
+    // release), stamp the holder pid, then release once on return.
+    let ino = 0
+    try {
+      ino = fstatSync(fd).ino
+    } catch {
+      // inode unavailable on this filesystem — the release falls back to the
+      // pid-stamp check only.
+      ino = 0
+    }
     try {
       writeSync(fd, String(process.pid))
     } catch {
@@ -151,10 +177,26 @@ export function acquireProjectLock(
     } catch {
       // best-effort
     }
-    return makeLockRelease(lockPath)
+    return { acquired: true, release: makeLockRelease(lockPath, ino) }
   }
 }
 
+/**
+ * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`.
+ *
+ * Returns a release function: always callable, idempotent, never throws.
+ * A no-op (but callable) release is returned when the lock directory cannot be
+ * created or the wait times out — callers then proceed unlocked, which is the
+ * historical best-effort behavior, rather than failing the operation.
+ */
+export function acquireProjectLock(
+  projectRoot: string,
+  name: string,
+  options: LockOptions = {},
+): () => void {
+  return acquireProjectLockChecked(projectRoot, name, options).release
+}
+
 /**
  * Build the release function for a lock file this process just acquired.
  *
@@ -168,7 +210,25 @@ export function acquireProjectLock(
  *
  * Always callable, idempotent, and never throws.
  */
-export function makeLockRelease(lockPath: string): () => void {
+/**
+ * Build the release function for a lock file this process just acquired.
+ *
+ * Advisory locks here are STOLEN when the recorded owner dies or the mtime
+ * goes ancient: the steal unlinks our file and creates a new one stamped with
+ * the STEALER's pid. An unguarded release would then unlink the new holder's
+ * lock — turning our release into a double-release that admits a third process
+ * into a "held" critical section. So the release re-reads the stamp and only
+ * unlinks a file that is still ours: same pid (or unstamped) AND, when we know
+ * the inode we created, the SAME inode still at the path. The inode check closes
+ * the read-then-unlink window where the stamp check alone could race a steal
+ * (our pid is alive, but the file was already replaced between the two calls).
+ *
+ * Always callable, idempotent, and never throws.
+ *
+ * @param lockPath - the lock file path.
+ * @param ino - the inode captured at acquisition (0 = unknown; skip the check).
+ */
+export function makeLockRelease(lockPath: string, ino?: number): () => void {
   let released = false
   return () => {
     if (released) return
@@ -183,6 +243,16 @@ export function makeLockRelease(lockPath: string): () => void {
     // A stamp naming another pid means the lock was stolen and reassigned:
     // it is no longer ours to delete.
     if (raw !== '' && Number(raw) !== process.pid) return
+    // The path must still refer to the file WE created. A stealer unlinked our
+    // file and created a fresh one; that replacement carries a different inode,
+    // so unlinking by path would delete the NEW holder's lock.
+    if (typeof ino === 'number' && ino !== 0) {
+      try {
+        if (statSync(lockPath).ino !== ino) return
+      } catch {
+        return // vanished mid-release — nothing of ours left
+      }
+    }
     try {
       unlinkSync(lockPath)
     } catch {

package/src/git-scope.ts

@@ -22,7 +22,7 @@
  */
 
 import { execFile } from 'node:child_process'
-import { existsSync, statSync } from 'node:fs'
+import { lstatSync, realpathSync } from 'node:fs'
 import { join, sep } from 'node:path'
 
 /** A resolved changed-only scope result. */
@@ -113,6 +113,15 @@ export function parseChangedFiles(stdout: string): string[] {
  * Keep only entries that resolve to an existing regular file under `root`.
  * Traversal-safe: rejects absolute paths and any relative path that would
  * escape `root` via `..` (resolved against the root before stat).
+ *
+ * Symlink handling: `statSync` (and `existsSync`) FOLLOW symlinks, so a git
+ * entry that is a link to a file OUTSIDE the project would pass a path-only
+ * containment check and enter the changed-only scope. Such a file is then
+ * rejected by the evidence gate (realpath out of bounds → `file_not_found`),
+ * so every finding on it would fail closed as `EVIDENCE_VIOLATION` forever —
+ * a permanent false positive for repos with dotfile or shared-config links.
+ * `lstatSync` distinguishes the link itself; a link whose REAL target escapes
+ * `root` is dropped here instead.
  */
 export function filterExistingFiles(root: string, files: string[]): string[] {
   const out: string[] = []
@@ -122,7 +131,17 @@ export function filterExistingFiles(root: string, files: string[]): string[] {
     const candidate = join(root, rel)
     if (!candidate.startsWith(rootPrefix) && candidate !== root) continue
     try {
-      if (existsSync(candidate) && statSync(candidate).isFile()) out.push(rel)
+      const st = lstatSync(candidate)
+      if (st.isFile()) {
+        out.push(rel)
+        continue
+      }
+      if (!st.isSymbolicLink()) continue
+      // A link whose real target stays inside the project is a legitimate,
+      // reviewable file; one that escapes is excluded from scope (fail-closed
+      // at the source instead of as a permanent evidence violation).
+      const real = realpathSync(candidate)
+      if (real === root || real.startsWith(rootPrefix)) out.push(rel)
     } catch {
       // Unreadable entry (e.g. a broken symlink) is not a valid review target.
       continue

package/src/skill-prompt.ts

@@ -135,7 +135,7 @@ for (let r = 1; r <= maxRounds; r++) {
         (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
         '\\n Already-known findings (do NOT re-report): ' +
         JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.'
-      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta?.findingsSchema }, backend))
     }))
     // A per-dimension reviewer subagent resolves \`null\` on child failure; the
     // aggregate below would report an all-failed round as an empty round, and
@@ -464,7 +464,7 @@ for (let r = startRound; r <= maxRounds; r++) {
         (steering ? '\\n STEERING — read this first: ' + steering : '') +
         (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
         '\\n Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.'
-      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta?.findingsSchema }, backend))
     }))
     // ALL reviewers returning null (child failures) means this round produced
     // no usable output — an empty aggregate must not read like a clean

package/src/tools/checkpoint.ts

@@ -14,6 +14,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import { writeJsonAtomic } from '../atomic-fs.ts'
+import { withProjectLock } from '../file-lock.ts'
 import { checkpointPath, iterateDir, transcriptPath } from '../paths.ts'
 import { readRegistry } from './fix.ts'
 import { readDecisionEntries } from './decision-log.ts'
@@ -322,22 +323,28 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
         }
 
         if (args.operation === 'resume') {
-          const current = readCheckpoint(projectRoot)
-          if (!current) {
-            return { operation: 'resume', ok: false, error: 'no checkpoint to resume — run `save` first' }
-          }
-          const resumed: IterationCheckpoint = {
-            ...current,
-            resumeCount: (current.resumeCount ?? 0) + 1,
-            updatedAt: new Date().toISOString(),
-          }
-          try {
-            mkdirSync(iterateDir(projectRoot), { recursive: true })
-            writeJsonAtomic(checkpointPath(projectRoot), resumed)
-          } catch (err) {
-            return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` }
-          }
-          return { operation: 'resume', ok: true, checkpoint: resumed as unknown as JsonValue }
+          // Read-modify-write across processes: a concurrent resume in a
+          // sibling process would read the same resumeCount and write it back,
+          // losing one increment. Serialize on a checkpoint lock (the same
+          // advisory pattern the config/triage/transcript writers use).
+          return withProjectLock(projectRoot, 'checkpoint', () => {
+            const current = readCheckpoint(projectRoot)
+            if (!current) {
+              return { operation: 'resume', ok: false, error: 'no checkpoint to resume — run `save` first' }
+            }
+            const resumed: IterationCheckpoint = {
+              ...current,
+              resumeCount: (current.resumeCount ?? 0) + 1,
+              updatedAt: new Date().toISOString(),
+            }
+            try {
+              mkdirSync(iterateDir(projectRoot), { recursive: true })
+              writeJsonAtomic(checkpointPath(projectRoot), resumed)
+            } catch (err) {
+              return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` }
+            }
+            return { operation: 'resume', ok: true, checkpoint: resumed as unknown as JsonValue }
+          })
         }
 
         if (args.operation === 'clear') {

package/src/tools/config.ts

@@ -9,6 +9,7 @@ import {
   validateConfigUpdates,
   writeConfigFile,
 } from '../config-write.ts'
+import { withProjectLock } from '../file-lock.ts'
 
 /**
  * Register the `iterate_config` tool.
@@ -121,40 +122,48 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
           if (updateErrors.length > 0) {
             return { operation: 'write', ok: false, found: false, errors: updateErrors }
           }
-          let base: Record<string, unknown>
-          try {
-            // Partial updates must be mergeable on a FRESH project (no config
-            // file yet): otherwise `{max_rounds: 5}` alone fails schema
-            // validation with a misleading "missing goal". Merge against the
-            // built-in defaults when there is no file to read, so the written
-            // config captures the effective config (defaults + update) and the
-            // documented "write a partial update" contract works out of the box.
-            base = existsSync(join(projectRoot, 'iterate.config.yaml'))
-              ? readRawConfig(join(projectRoot, 'iterate.config.yaml'))
-              : (defaultConfig() as unknown as Record<string, unknown>)
-          } catch (err) {
-            return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` }
-          }
-          const merged = applyConfigUpdates(base, updates ?? {})
-          const schemaErrors = validateConfig(merged)
-          if (schemaErrors.length > 0) {
+          // Serialize the read→merge→validate→write cycle against any other
+          // config/triage writer in a sibling process: without the lock, two
+          // sessions on the same project each read a stale base and the second
+          // merge silently discards the first's update (lost update). The same
+          // lock name is shared with `iterate_triage apply` so the two writers
+          // are mutually exclusive.
+          return withProjectLock(projectRoot, 'config-write', () => {
+            let base: Record<string, unknown>
+            try {
+              // Partial updates must be mergeable on a FRESH project (no config
+              // file yet): otherwise `{max_rounds: 5}` alone fails schema
+              // validation with a misleading "missing goal". Merge against the
+              // built-in defaults when there is no file to read, so the written
+              // config captures the effective config (defaults + update) and the
+              // documented "write a partial update" contract works out of the box.
+              base = existsSync(join(projectRoot, 'iterate.config.yaml'))
+                ? readRawConfig(join(projectRoot, 'iterate.config.yaml'))
+                : (defaultConfig() as unknown as Record<string, unknown>)
+            } catch (err) {
+              return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` }
+            }
+            const merged = applyConfigUpdates(base, updates ?? {})
+            const schemaErrors = validateConfig(merged)
+            if (schemaErrors.length > 0) {
+              return {
+                operation: 'write',
+                ok: false,
+                found: false,
+                errors: schemaErrors.map((e) => `missing/required field: ${e}`),
+              }
+            }
+            const result = writeConfigFile(projectRoot, merged)
+            if (!result.ok) return { operation: 'write', ok: false, found: false, error: result.error }
+            const { config } = loadEffectiveConfig(projectRoot)
             return {
               operation: 'write',
-              ok: false,
-              found: false,
-              errors: schemaErrors.map((e) => `missing/required field: ${e}`),
+              ok: true,
+              found: true,
+              backupPath: result.backupPath ?? null,
+              config: config as unknown as JsonValue,
             }
-          }
-          const result = writeConfigFile(projectRoot, merged)
-          if (!result.ok) return { operation: 'write', ok: false, found: false, error: result.error }
-          const { config } = loadEffectiveConfig(projectRoot)
-          return {
-            operation: 'write',
-            ok: true,
-            found: true,
-            backupPath: result.backupPath ?? null,
-            config: config as unknown as JsonValue,
-          }
+          })
         }
 
         // ── Read operations (original behavior) ────────────────────────────

package/src/tools/decision-log.ts

@@ -3,17 +3,13 @@ import {
   readFileSync,
   mkdirSync,
   existsSync,
-  openSync,
-  writeSync,
-  closeSync,
-  unlinkSync,
   statSync,
 } 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 { makeLockRelease } from '../file-lock.ts'
+import { acquireProjectLockChecked } from '../file-lock.ts'
 import type { DecisionLogEntry } from '../types.ts'
 
 const LOG_DIR = '.iterate'
@@ -34,35 +30,16 @@ const LOG_FILE = 'decision-log.jsonl'
 // opposite — it renames the log and therefore refuses to run when the lock
 // cannot be taken (see `rewriteDecisionLogKeepingRecent` in prune.ts).
 
-const LOCK_FILE = '.decision-log.lock'
-const LOCK_WAIT_MS = 5000
-const LOCK_STALE_MS = 10000
-const LOCK_POLL_MS = 25
-
-/** True when a pid refers to a live process (or we lack permission to tell). */
-function processAlive(pid: number): boolean {
-  if (!Number.isInteger(pid) || pid <= 0) return false
-  try {
-    process.kill(pid, 0)
-    return true
-  } catch (err) {
-    return (err as NodeJS.ErrnoException).code === 'EPERM'
-  }
-}
-
-/** Synchronous busy-wait sleep (Atomics.wait is a reliable sleep in Node). */
-function sleepSync(ms: number): void {
-  const sab = new Int32Array(new SharedArrayBuffer(4))
-  Atomics.wait(sab, 0, 0, ms)
-}
+/** Lock name shared with the prune rewrite (→ `.iterate/.decision-log.lock`). */
+const LOG_LOCK_NAME = 'decision-log'
 
 /**
  * Acquire the decision-log lock for `projectRoot`.
  * Returns a release function (always callable; a no-op when the lock could
  * not be taken — never wedge an append behind a vanished holder).
  *
- * `options.waitMs` / `options.staleMs` override the defaults (tests use short
- * waits so a live-holder timeout is exercised in milliseconds, not 5s).
+ * `options.waitMs` / `options.staleMs` override the shared defaults (tests use
+ * short waits so a live-holder timeout is exercised in milliseconds, not 5s).
  */
 export function acquireLogLock(
   projectRoot: string,
@@ -77,63 +54,18 @@ export function acquireLogLock(
  * audit line must not be lost to a wedged append), but the rewrite renames the
  * log under any unlocked concurrent appender — it must refuse to run without
  * the mutex rather than silently dropping an audit line.
+ *
+ * Delegates to the shared `acquireProjectLockChecked` with lock name
+ * `decision-log`: the decision-log mutex IS that generic project lock. This
+ * module used to hand-roll an identical copy of the acquire/steal/wait logic,
+ * and the two stale/wait parameter sets could drift apart — one implementation,
+ * one set of defaults, one ownership-checked release.
  */
 export function acquireLogLockChecked(
   projectRoot: string,
   options: { waitMs?: number; staleMs?: number } = {},
 ): { acquired: boolean; release: () => void } {
-  const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
-    ? (options.waitMs as number)
-    : LOCK_WAIT_MS
-  const staleMs = Number.isFinite(options.staleMs) && (options.staleMs ?? 0) >= 0
-    ? (options.staleMs as number)
-    : LOCK_STALE_MS
-  const dir = join(projectRoot, LOG_DIR)
-  if (!existsSync(dir)) {
-    try {
-      mkdirSync(dir, { recursive: true })
-    } catch {
-      return { acquired: false, release: () => {} }
-    }
-  }
-  const lockPath = join(dir, LOCK_FILE)
-  const start = Date.now()
-  for (;;) {
-    let fd: number | null = null
-    try {
-      fd = openSync(lockPath, 'wx')
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return { acquired: false, release: () => {} }
-      // Lock exists — steal it when the owner is gone or the lock is ancient.
-      let stale = false
-      try {
-        const st = statSync(lockPath)
-        if (Date.now() - st.mtimeMs > staleMs) stale = true
-        else {
-          const pid = Number(readFileSync(lockPath, 'utf-8'))
-          if (!processAlive(pid)) stale = true
-        }
-      } catch {
-        stale = true // unreadable/vanishing lock → retry as stale
-      }
-      if (stale) {
-        try { unlinkSync(lockPath) } catch { /* another holder stole it */ }
-        continue
-      }
-      if (Date.now() - start > waitMs) return { acquired: false, release: () => {} }
-      sleepSync(LOCK_POLL_MS)
-      continue
-    }
-    // Owned the lock: stamp the holder pid, then release once on return.
-    // The release is ownership-checked (see `makeLockRelease`): a lock stolen
-    // from this process after its owner went stale must not be unlinked by us.
-    try { writeSync(fd, String(process.pid)) } catch { /* pid stamp is advisory */ }
-    try { closeSync(fd) } catch { /* best-effort */ }
-    return {
-      acquired: true,
-      release: makeLockRelease(lockPath),
-    }
-  }
+  return acquireProjectLockChecked(projectRoot, LOG_LOCK_NAME, options)
 }
 
 // ─── Entry-count cache (avoid an O(n) full re-read per append) ─────────────