iterate-plugin 3.6.0 → 3.8.0

package/src/client/session-cache.ts

@@ -0,0 +1,54 @@
+/**
+ * src/client/session-cache.ts — the newest session the session-scoped slots saw.
+ *
+ * Slot scopes in dsh are not uniform: `conversation.input.dock` (dashboard,
+ * observatory) renders inside a session and receives `props.session`, while
+ * `settings.section` renders at ROOT scope on the settings page and gets no
+ * session at all. The settings card nevertheless needs session-derived state —
+ * specifically the config the model echoed back through `iterate_config`, which
+ * is what closes the config write → read-back loop.
+ *
+ * Rather than fake a session for the root slot, the session-scoped slots
+ * publish what the host handed them and root-scoped panels subscribe:
+ *
+ *   session slot renders → noteSession(props.session)
+ *   settings panel       → useSessionSnapshot() (via subscribeSession)
+ *
+ * Design constraints (mirrors `i18n.ts`):
+ *   - **Pure**: no React, no DOM — the store is unit-testable on its own, and
+ *     the React binding lives next to `useLang()` in index.ts.
+ *   - **Identity-compared**: the same session object never notifies twice, so
+ *     a slot that re-renders every frame cannot spin its subscribers.
+ *   - **Never fabricated**: it only ever holds what the host really passed; an
+ *     empty cache reads as "nothing echoed yet", which is the honest state.
+ */
+
+/** Anything host-shaped; the plugins only ever pass it through opaque. */
+export type CachedSession = unknown
+
+let current: CachedSession = null
+
+const listeners = new Set<() => void>()
+
+/**
+ * Publish the session a session-scoped slot was rendered with.
+ * Notifies subscribers only when the identity actually changes.
+ */
+export function noteSession(session: CachedSession): void {
+  if (Object.is(session, current)) return
+  current = session
+  for (const listener of [...listeners]) listener()
+}
+
+/** Last published session (or `null` before any session slot has rendered). */
+export function readSession(): CachedSession {
+  return current
+}
+
+/** Subscribe to session changes; returns the unsubscribe function. */
+export function subscribeSession(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}

package/src/config-loader.ts

@@ -3,6 +3,7 @@ import { homedir } from 'node:os'
 import { basename, dirname, join, resolve, sep } from 'node:path'
 import yaml from 'js-yaml'
 import type { IterateConfig } from './types.ts'
+import { sessionCwdOf } from './working-directory.ts'
 
 /**
  * Load and parse iterate.config.yaml from the project root.
@@ -748,12 +749,17 @@ export function resolveProjectRoot(input?: string, sessionCwd?: string): Project
 /**
  * Thin adapter for tool `execute(args, exec)` bodies: pull the session cwd
  * from the DSH run context and hand it to {@link resolveProjectRoot}.
+ *
+ * The cwd source is the EFFECTIVE session directory (dsh 0.2.1-alpha.2's
+ * `workingDirectory` service when the host provides one, else the immutable
+ * `header.cwd` — see `./working-directory.ts`), so a session whose directory
+ * was switched mid-run still resolves the project it is actually editing.
  */
 export function resolveProjectRootForExec(
   exec: { agent?: { session?: { header?: { cwd?: string } } } } | undefined,
   input?: string,
 ): ProjectRootResult {
-  return resolveProjectRoot(input, exec?.agent?.session?.header?.cwd)
+  return resolveProjectRoot(input, sessionCwdOf(exec))
 }
 
 /**

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,16 +177,87 @@ export function acquireProjectLock(
     } catch {
       // best-effort
     }
-    let released = false
-    return () => {
-      if (released) return
-      released = true
+    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.
+ *
+ * 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 (the shape left
+ * when our own advisory pid write failed, or when the content is not a pid).
+ *
+ * Always callable, idempotent, and never throws.
+ */
+/**
+ * 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
+    released = true
+    let raw = ''
+    try {
+      raw = readFileSync(lockPath, 'utf-8').trim()
+    } catch {
+      // Already gone (or unreadable) — nothing of ours left to remove.
+      return
+    }
+    // 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 {
-        unlinkSync(lockPath)
+        if (statSync(lockPath).ino !== ino) return
       } catch {
-        // already gone
+        return // vanished mid-release — nothing of ours left
       }
     }
+    try {
+      unlinkSync(lockPath)
+    } catch {
+      // already gone
+    }
   }
 }
 

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/index.ts

@@ -45,6 +45,7 @@ import { registerQualityGateTool } from './tools/quality-gate.ts'
 import { registerDefenseEventsTool } from './tools/defense-events.ts'
 import { registerSessionHooks } from './session-hooks.ts'
 import { registerLiveCapture } from './live.ts'
+import { installWorkingDirectoryContext } from './working-directory.ts'
 import { ITERATE_SKILL_PROMPT } from './skill-prompt.ts'
 
 export const name = 'iterate-plugin'
@@ -58,6 +59,12 @@ export function apply(ctx: Context): void {
   //    running with NO `tools/pre-execute` approval gate — a fail-open hole
   //    created by load order. Registering the gate first means a partial load
   //    can only ever err on the side of MORE gating, never less.
+  //
+  //    The working-directory context is installed first for the same reason:
+  //    every cwd read below (gate policy, live capture, tool project roots)
+  //    must see dsh 0.2.1-alpha.2+ directory switches, and installing it last
+  //    would leave a partially-loaded plugin resolving the wrong workspace.
+  installWorkingDirectoryContext(ctx)
   registerSessionHooks(ctx)
   registerLiveCapture(ctx)
 

package/src/live.ts

@@ -34,6 +34,7 @@ import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type { ToolExecution } from '@deepseek-ai/dsh-tools'
 import { loadEffectiveConfig, resolveProjectRoot } from './config-loader.ts'
+import { sessionCwdOf } from './working-directory.ts'
 
 /** Keep at most this many live activity entries. */
 export const LIVE_MAX_ENTRIES = 300
@@ -140,7 +141,7 @@ export function appendLive(projectRoot: string, entry: LiveActivityEntry): Promi
 
 /** Resolve the project root a tool execution belongs to, if any. */
 function projectRootOf(exec: ToolExecution): string | null {
-  const cwd = exec.agent?.session?.header?.cwd
+  const cwd = sessionCwdOf(exec)
   if (!cwd) return null
   const resolved = resolveProjectRoot(undefined, cwd)
   return resolved.ok ? resolved.root : null

package/src/session-hooks.ts

@@ -55,6 +55,7 @@
 
 import { loadEffectiveConfig, resolveProjectRoot } from './config-loader.ts'
 import { decideApproval, isDestructiveIterateTool } from './approval-gate.ts'
+import { sessionCwdOf } from './working-directory.ts'
 import type { Context } from '@deepseek-ai/cordis'
 import type { ToolErrorInfo, ToolExecution, PreToolDecision } from '@deepseek-ai/dsh-tools'
 
@@ -114,7 +115,11 @@ export function gateDecision(exec: ToolExecution): PreToolDecision {
       const p = (args as Record<string, unknown>).path
       if (typeof p === 'string') argPath = p
     }
-    sessionCwd = exec?.agent?.session?.header?.cwd
+    // Effective session directory (see ./working-directory.ts): a session whose
+    // directory was switched via dsh 0.2.1-alpha.2's `working_directory` tool
+    // must have its POLICY read from the workspace it is now in — `header.cwd`
+    // alone would read the original project's approval policy.
+    sessionCwd = sessionCwdOf(exec)
   } catch {
     // hostile/proxied exec — fall through with both undefined (defaults to ask)
   }

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) ────────────────────────────