iterate-plugin 3.6.0 → 3.8.0

package/src/tools/decision-log.ts

@@ -3,16 +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 { acquireProjectLockChecked } from '../file-lock.ts'
 import type { DecisionLogEntry } from '../types.ts'
 
 const LOG_DIR = '.iterate'
@@ -33,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,
@@ -76,66 +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.
-    try { writeSync(fd, String(process.pid)) } catch { /* pid stamp is advisory */ }
-    try { closeSync(fd) } catch { /* best-effort */ }
-    let released = false
-    return {
-      acquired: true,
-      release: () => {
-        if (released) return
-        released = true
-        try { unlinkSync(lockPath) } catch { /* already gone */ }
-      },
-    }
-  }
+  return acquireProjectLockChecked(projectRoot, LOG_LOCK_NAME, options)
 }
 
 // ─── Entry-count cache (avoid an O(n) full re-read per append) ─────────────

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

package/src/working-directory.ts

@@ -0,0 +1,126 @@
+/**
+ * src/working-directory.ts — follow dsh's mutable session working directory.
+ *
+ * Upstream history:
+ *   - through dsh 0.2.1-alpha.1 the session's working directory WAS the
+ *     immutable `Session.header.cwd`, so reading `exec.agent.session.header.cwd`
+ *     was authoritative;
+ *   - dsh 0.2.1-alpha.2 added the `working_directory` tool and the
+ *     `WorkingDirectoryService` (`@deepseek-ai/dsh-working-directory`), whose
+ *     contract explicitly states "the immutable Session header retains the
+ *     ORIGINAL project" while `working-directory/change` events record the
+ *     current one. After a model/user switches directories mid-session,
+ *     `header.cwd` is therefore stale BY DESIGN.
+ *
+ * The iterate plugin resolves the project root (where `.iterate/` lives, where
+ * fixes are written, and — critically — which workspace the F8 approval policy
+ * is read from) from the session cwd. Sticking to `header.cwd` on a host that
+ * supports directory switches would silently operate on the wrong project:
+ * reviews would anchor to the original checkout while the model edits files
+ * elsewhere, and a `deny` policy in the active workspace would be read from
+ * the original one.
+ *
+ * So the effective directory is resolved through the host's service when it
+ * exists, and degrades to `header.cwd` otherwise:
+ *   - feature-detected (`ctx.get('workingDirectory')`) — hosts older than
+ *     0.2.1-alpha.2 simply have no such service and keep the old behavior;
+ *   - `service.get(session)` is the service's synchronous, I/O-free read of
+ *     the committed directory, so this stays safe on the approval path;
+ *   - every failure mode (no service, service throws, hostile getters, a
+ *     non-string result) falls back to `header.cwd`, never to `undefined`
+ *     where a header cwd exists.
+ *
+ * The service object is fetched lazily on every call, not once at plugin
+ * apply: dsh may register the service after this plugin loads, and a disposed
+ * context must degrade rather than cache a dead handle.
+ */
+
+/** Minimal structural view of dsh's `WorkingDirectoryService` (0.2.1-alpha.2+). */
+interface WorkingDirectoryServiceLike {
+  get(session: unknown): string
+}
+
+/** Minimal structural view of the cordis context surface this module uses. */
+interface ContextLike {
+  get?(name: string, strict?: boolean): unknown
+}
+
+/** The plugin context, installed once by `apply()`; null on hosts without it. */
+let installedContext: ContextLike | null = null
+
+/** True when `value` looks like a cordis context carrying `ctx.get`. */
+function isContextLike(value: unknown): value is ContextLike {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as ContextLike).get === 'function'
+  )
+}
+
+/**
+ * Install the plugin context used to look up the `workingDirectory` service.
+ * Passing anything without a callable `get` clears the installation (tests and
+ * hosts that load the plugin into a degraded context).
+ */
+export function installWorkingDirectoryContext(ctx: unknown): void {
+  installedContext = isContextLike(ctx) ? ctx : null
+}
+
+/** Forget the installed context (test isolation / unload). */
+export function resetWorkingDirectoryContext(): void {
+  installedContext = null
+}
+
+/**
+ * Read the host's committed working directory for `session`, if the host
+ * provides the service and it answers with a usable absolute path.
+ *
+ * Returns `undefined` for every degradation path so callers keep their
+ * previous `header.cwd` behavior.
+ */
+function serviceWorkingDirectory(session: unknown): string | undefined {
+  if (session === undefined || session === null) return undefined
+  const ctx = installedContext
+  if (!ctx) return undefined
+  try {
+    const service = ctx.get?.('workingDirectory')
+    if (!service || typeof (service as WorkingDirectoryServiceLike).get !== 'function') return undefined
+    const dir = (service as WorkingDirectoryServiceLike).get(session)
+    // A relative or empty directory would move the project root somewhere
+    // unspecified — refuse it and keep the header value instead.
+    if (typeof dir !== 'string' || dir.length === 0) return undefined
+    return dir
+  } catch {
+    // Missing/disposed service, unpublished session, or a throwing getter —
+    // degrade to the historical source rather than failing the tool call.
+    return undefined
+  }
+}
+
+/**
+ * The effective working directory of a session: the host's committed
+ * directory when available, else the immutable session header cwd.
+ *
+ * Returns `undefined` only when neither source yields a usable path.
+ */
+export function effectiveSessionCwd(session: unknown, headerCwd?: string): string | undefined {
+  const fromService = serviceWorkingDirectory(session)
+  if (fromService !== undefined) return fromService
+  return typeof headerCwd === 'string' && headerCwd.length > 0 ? headerCwd : undefined
+}
+
+/**
+ * Extract the effective cwd from a tool execution (`exec.agent.session`),
+ * reading every property defensively: a hostile/proxied exec must degrade to
+ * the fallback path, never throw out of an approval or capture hook.
+ */
+export function sessionCwdOf(exec: unknown): string | undefined {
+  try {
+    const agent = (exec as { agent?: { session?: { header?: { cwd?: unknown } } } } | null | undefined)?.agent
+    const session = agent?.session
+    const headerCwd = typeof agent?.session?.header?.cwd === 'string' ? agent.session.header.cwd : undefined
+    return effectiveSessionCwd(session, headerCwd)
+  } catch {
+    return undefined
+  }
+}