iterate-plugin 2.10.0 → 2.12.0

package/src/config-loader.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, resolve, sep } from 'node:path'
 import yaml from 'js-yaml'
@@ -56,6 +56,10 @@ export function defaultConfig(): IterateConfig {
       coverage_validation: true,
       scope_chunk_size: 25,
     },
+    observatory: {
+      capture: true,
+      approval: 'ask',
+    },
   }
 }
 
@@ -75,6 +79,10 @@ export function mergeConfig(
   const out: Record<string, unknown> = { ...base }
   for (const [key, value] of Object.entries(override)) {
     if (value === undefined) continue
+    // Prototype-pollution guard: a YAML `__proto__`/`constructor`/`prototype`
+    // key must never be plain-assigned — js-yaml stores __proto__ as an own
+    // data property, and `out[key] = value` would invoke the __proto__ setter.
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue
     const baseValue = out[key]
     if (
       baseValue &&
@@ -242,7 +250,13 @@ function effectiveCwd(sessionCwd?: string): string {
     if (encoded && encoded.startsWith('--') && encoded.endsWith('--')) {
       try {
         const decoded = decodeURIComponent(encoded.slice(2, -2).replace(/~/g, '%'))
-        if (decoded && decoded.startsWith(sep)) return decoded
+        // The workspace encoding drops the leading root separator (`/Volumes/…`
+        // → `Volumes-…`), so re-attach it when absent. `~<hex>` → `%<hex>` is
+        // the documented percent spelling; '-' doubles as the '/' separator, so
+        // literal dashes in a path cannot round-trip — verify the result exists
+        // and fall through otherwise.
+        const candidate = decoded && !decoded.startsWith(sep) ? sep + decoded : decoded
+        if (candidate && candidate.startsWith(sep) && existsSync(candidate)) return candidate
       } catch {
         // malformed encoding — fall through to cwd
       }

package/src/config-write.ts

@@ -10,7 +10,7 @@
  * config, always back up before writing, roll back on failure.
  */
 
-import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import yaml from 'js-yaml'
 
@@ -169,12 +169,14 @@ export function writeConfigFile(
   try {
     writeFileSync(configPath, yaml.dump(config, { noRefs: true }), 'utf-8')
   } catch (err) {
+    let rollbackError = ''
     try {
       if (backupPath) copyFileSync(backupPath, configPath)
-    } catch {
-      // Rollback failure is reported, never swallowed silently.
+      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)}` }
+    return { ok: false, error: `failed to write config: ${String(err)}${rollbackError}` }
   }
 
   return { ok: true, backupPath }

package/src/evidence.ts

@@ -23,13 +23,21 @@
  * filesystem half (`verifyFinding`) to stay unit-testable without touching disk.
  */
 
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
 import { resolve, sep } from 'node:path'
 import type { ReviewFinding } from './types.ts'
 
 /** Sentinel for whole-file findings (line 0 or omitted means the whole file). */
 export const WHOLE_FILE_LINE = 0
 
+/**
+ * Hard cap on a single evidence file read. `verifyFinding` only needs the
+ * line count + a NUL check; reading an unbounded file (or a device file
+ * reached through a symlink) is a memory/hang hazard, so anything larger is
+ * treated as not line-addressable.
+ */
+const MAX_EVIDENCE_BYTES = 10 * 1024 * 1024
+
 export type EvidenceError = 'file_not_found' | 'line_out_of_range'
 
 /** Per-finding attestation result. */
@@ -79,6 +87,22 @@ export function resolveWithin(root: string, rel: string): string | null {
   return resolved
 }
 
+/** True when `candidate` is `root` itself or lexically inside `root`. */
+function isWithin(root: string, candidate: string): boolean {
+  if (candidate === root) return true
+  const prefix = root.endsWith(sep) ? root : root + sep
+  return candidate.startsWith(prefix)
+}
+
+/** best-effort realpath; falls back to the lexical path on any failure. */
+function safeRealpath(p: string): string {
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
 /**
  * Pure check that `line` (if anchored) exists in `text`.
  * Whole-file findings (undefined/0) are always bounds-valid.
@@ -116,6 +140,50 @@ export function verifyFinding(
     }
   }
 
+  // Symlink containment: resolveWithin is lexical only, but existsSync /
+  // readFileSync follow symlinks. Verify the REAL path stays inside the REAL
+  // project root so a finding path can never read (or line-count) a file
+  // outside the project via a symlinked directory or file.
+  const rootReal = safeRealpath(root)
+  const real = safeRealpath(resolved)
+  if (!isWithin(rootReal, real)) {
+    return {
+      file: relFile,
+      line,
+      lineTotal: null,
+      resolvedPath: resolved,
+      verified: false,
+      error: 'file_not_found',
+    }
+  }
+
+  // Regular-file + size guard: a directory, device file (/dev/zero), FIFO or
+  // multi-GB file is not a line-addressable text target. statSync follows
+  // symlinks, so a link to a device still lands here and is rejected.
+  let st
+  try {
+    st = statSync(resolved)
+  } catch {
+    return {
+      file: relFile,
+      line,
+      lineTotal: null,
+      resolvedPath: resolved,
+      verified: false,
+      error: 'file_not_found',
+    }
+  }
+  if (!st.isFile() || st.size > MAX_EVIDENCE_BYTES) {
+    return {
+      file: relFile,
+      line,
+      lineTotal: null,
+      resolvedPath: resolved,
+      verified: false,
+      error: 'line_out_of_range',
+    }
+  }
+
   let raw: Buffer
   try {
     raw = readFileSync(resolved)

package/src/git-scope.ts

@@ -38,14 +38,30 @@ export interface GitScopeResult {
 }
 
 /**
- * Parse `git diff --name-only` stdout into a list of relative paths.
- * Pure: strips blank lines, trims whitespace, drops quotes (git can quote
- * paths with special characters).
+ * Parse `git diff --name-only -z` stdout into a list of relative paths.
+ * Pure. NUL-delimited mode is machine-safe (handles any filename); when no
+ * NUL is present (callers that did not pass -z) fall back to newline-split
+ * with C-style quote/escape unescaping for core.quotePath output.
  */
 export function parseChangedFiles(stdout: string): string[] {
+  if (stdout.includes('\0')) {
+    return stdout.split('\0').map((s) => s.trim()).filter((s) => s.length > 0)
+  }
   return stdout
     .split('\n')
-    .map((line) => line.trim().replace(/^"|"$/g, ''))
+    .map((line) => {
+      const trimmed = line.trim()
+      // git core.quotePath wraps paths with special characters in "..."; the
+      // content uses C-style escapes (\" \\ \t \n and \ooo octal for non-ASCII).
+      const quoted = trimmed.match(/^"(.*)"$/)
+      if (!quoted) return trimmed
+      return quoted[1]!
+        .replace(/\\"/g, '"')
+        .replace(/\\\\/g, '\\')
+        .replace(/\\t/g, '\t')
+        .replace(/\\n/g, '\n')
+        .replace(/\\([0-7]{3})/g, (_m, oct: string) => String.fromCharCode(parseInt(oct, 8)))
+    })
     .filter((line) => line.length > 0)
 }
 
@@ -118,9 +134,21 @@ export async function resolveChangedFiles(
   root: string,
   targetBranch: string,
 ): Promise<GitScopeResult> {
-  const { ok, stdout, stderr } = await runGit(['diff', '--name-only', targetBranch, '--'], root)
+  // Option-injection guard: a branch name starting with '-' would be parsed by
+  // git as an option (e.g. --output=...), not a ref. Reject it outright.
+  if (typeof targetBranch !== 'string' || targetBranch.trim() === '' || targetBranch.startsWith('-')) {
+    return {
+      scope: 'full',
+      changedFiles: [],
+      fallbackToFull: true,
+      error: `invalid target branch "${String(targetBranch)}"`,
+    }
+  }
+  // -z: NUL-delimited names — machine-safe for any filename (spaces, quotes,
+  // non-ASCII), and never confused with option-like content.
+  const { ok, stdout, stderr } = await runGit(['diff', '--name-only', '-z', targetBranch, '--'], root)
   if (!ok) {
-    const reason = stderr.trim() || `git diff --name-only ${targetBranch} failed`
+    const reason = stderr.trim() || `git diff --name-only -z ${targetBranch} failed`
     return { scope: 'full', changedFiles: [], fallbackToFull: true, error: reason }
   }
   const existing = filterExistingFiles(root, parseChangedFiles(stdout))

package/src/index.ts

@@ -2,13 +2,15 @@
  * iterate-plugin — dsh plugin for the iterate autonomous closed-loop workflow
  *
  * Architecture:
- * - The plugin registers 13 tools (config, validate, decision-log, context, review,
- *   triage, fix, diff, rollback, checkpoint, status, history, prune)
+ * - The plugin registers 14 tools (config, validate, decision-log, context, review,
+ *   triage, fix, diff, rollback, checkpoint, status, history, prune, transcript)
  * - The plugin injects a system prompt section teaching the iterate workflow pattern
  * - The model (prompted by the skill) writes a workflow script using dsh's `workflow` tool
  * - The workflow script uses `agent()` / `parallel()` / `phase()` / `log()` to orchestrate
- * - Subagents use the 13 tools to do real work (read config, run validation, log decisions,
- *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune)
+ * - Subagents use the 14 tools to do real work (read config, run validation, log decisions,
+ *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune, transcript)
+ * - A `tools/pre-execute` hook gates destructive iterate calls behind human approval
+ *   (F8 observatory approval policy: ask / deny / allow).
  *
  * Tool invocation model:
  * - Workflow script CANNOT call tools directly (sandboxed vm, no Node API)
@@ -34,13 +36,16 @@ import { registerFixTool, registerDiffTool, registerRollbackTool } from './tools
 import { registerCheckpointTool, registerStatusTool } from './tools/checkpoint.ts'
 import { registerHistoryTool } from './tools/history.ts'
 import { registerPruneTool } from './tools/prune.ts'
+import { registerTranscriptTool } from './tools/transcript.ts'
+import { registerSessionHooks } from './session-hooks.ts'
+import { registerLiveCapture } from './live.ts'
 import { ITERATE_SKILL_PROMPT } from './skill-prompt.ts'
 
 export const name = 'iterate-plugin'
-export const inject = ['tools', 'systemPrompt']
+export const inject = ['tools', 'systemPrompt'] as const
 
 export function apply(ctx: Context): void {
-  // 1. Register the 13 tools
+  // 1. Register the 14 tools
   registerConfigTool(ctx)
   registerValidateTool(ctx)
   registerDecisionLogTool(ctx)
@@ -54,6 +59,12 @@ export function apply(ctx: Context): void {
   registerStatusTool(ctx)
   registerHistoryTool(ctx)
   registerPruneTool(ctx)
+  registerTranscriptTool(ctx)
+
+  // 2. Wire the observatory approval gate onto dsh's tools/pre-execute waterfall,
+  //    and the live reviewer-activity feed onto tools/result.
+  registerSessionHooks(ctx)
+  registerLiveCapture(ctx)
 
   // 2. Inject the iterate skill prompt as a system prompt section
   // This teaches the model how to write iterate workflow scripts using the tools.

package/src/live.ts

@@ -0,0 +1,185 @@
+/**
+ * src/live.ts — live reviewer-activity feed for the iterate observatory (F1 live).
+ *
+ * Watches `tools/result` and, for tool calls we can attribute to a project root
+ * (the caller agent's session cwd), appends one line to an append-only NDJSON
+ * file `.iterate/transcript-live.ndjson`. The `iterate_transcript` tool then
+ * mixes the most recent entries into its `read` / `capture` results so the
+ * client observatory shows what reviewers are doing in near-real-time (which
+ * files they read, which fixes/rollbacks/diffs land, where the run is).
+ *
+ * Why project-scoped (not per-thread):
+ *   Tool executions carry the calling agent's session cwd but NOT the workflow
+ *   sub-agent's `dimension` / `round` label, so we cannot reliably attribute a
+ *   read to a specific reviewer thread without inventing data. We therefore
+ *   record honest project-level activity and never fabricate an attribution.
+ *   Per-thread narration stays the job of the final `iterate_transcript capture`.
+ *
+ * Safety:
+ *   - Read-only observer: never mutates source files; writes only the NDJSON
+ *     live file under `.iterate/`.
+ *   - The live file is byte-capped (rewrite to last N lines when it grows too
+ *     large) so it can never grow unbounded.
+ *   - Any capture failure is swallowed (fire-and-forget) so it can never block
+ *     or crash a tool call.
+ */
+
+import { mkdir, readFile, writeFile, stat, appendFile, rename } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import type { ToolExecution } from '@deepseek-ai/dsh-tools'
+import { resolveProjectRoot } from './config-loader.ts'
+
+/** Keep at most this many live activity entries. */
+export const LIVE_MAX_ENTRIES = 300
+/** Rewrite the live file when its byte size exceeds this threshold. */
+export const LIVE_MAX_BYTES = 64 * 1024
+
+/** One live activity record. */
+export interface LiveActivityEntry {
+  /** ISO 8601 timestamp of the tool result. */
+  ts: string
+  /** Coarse category used by the client for coloring/grouping. */
+  type:
+    | 'read'
+    | 'fix'
+    | 'rollback'
+    | 'diff'
+    | 'review'
+    | 'triage'
+    | 'checkpoint'
+    | 'validate'
+    | 'log'
+    | 'prune'
+    | 'info'
+  /** The tool that produced the activity. */
+  tool: string
+  /**
+   * The affected target: a source file path (relative to project root) for
+   * read/fix/rollback/diff, else a summary string (e.g. the review operation).
+   */
+  target: string
+}
+
+/** File path of the live NDJSON feed for a project root. */
+export function liveFilePath(projectRoot: string): string {
+  return join(projectRoot, '.iterate', 'transcript-live.ndjson')
+}
+
+/** Resolve the project root a tool execution belongs to, if any. */
+function projectRootOf(exec: ToolExecution): string | null {
+  const cwd = exec.agent?.session?.header?.cwd
+  if (!cwd) return null
+  const resolved = resolveProjectRoot(undefined, cwd)
+  return resolved.ok ? resolved.root : null
+}
+
+/** Classify a settled tool call into a live activity entry, or null to skip. */
+export function classifyTool(
+  name: string,
+  args: unknown,
+  projectRoot: string,
+): LiveActivityEntry | null {
+  // `read_file` is the dsh-native file reader reviewers use to inspect code.
+  if (name === 'read_file') {
+    const file =
+      args && typeof args === 'object' && typeof (args as Record<string, unknown>).path === 'string'
+        ? (args as Record<string, unknown>).path as string
+        : ''
+    return file ? { ts: new Date().toISOString(), type: 'read', tool: name, target: file } : null
+  }
+
+  // The iterate plugin's own tools — surface what the workflow is doing live.
+  const records: Record<string, LiveActivityEntry['type']> = {
+    iterate_fix: 'fix',
+    iterate_rollback: 'rollback',
+    iterate_diff: 'diff',
+    iterate_review: 'review',
+    iterate_triage: 'triage',
+    iterate_checkpoint: 'checkpoint',
+    iterate_validate: 'validate',
+    iterate_decision_log: 'log',
+    iterate_history: 'info',
+    iterate_prune: 'prune',
+    iterate_transcript: 'log',
+    iterate_status: 'info',
+    iterate_config: 'info',
+    iterate_context: 'info',
+  }
+  const type = records[name]
+  if (!type) return null
+
+  let target = ''
+  if (args && typeof args === 'object') {
+    const a = args as Record<string, unknown>
+    if (typeof a.file === 'string' && a.file) target = a.file
+    else if (typeof a.path === 'string' && a.path) target = a.path
+    else if (typeof a.operation === 'string' && a.operation) target = a.operation
+    else if (name === 'iterate_rollback' && typeof a.id === 'string' && a.id) {
+      target = `fix ${a.id}`
+    }
+  }
+  if (!target) target = name
+  return { ts: new Date().toISOString(), type, tool: name, target }
+}
+
+/** Append one activity record to the project's live feed (byte-capped). */
+export async function appendLive(projectRoot: string, entry: LiveActivityEntry): Promise<void> {
+  const file = liveFilePath(projectRoot)
+  const line = JSON.stringify(entry) + '\n'
+  await mkdir(join(projectRoot, '.iterate'), { recursive: true })
+  // Amortized O(1): only read+rewrite when the file has grown past the cap.
+  try {
+    const st = await stat(file).catch(() => null)
+    if (st && st.size > LIVE_MAX_BYTES) {
+      const raw = await readFile(file, 'utf-8')
+      const lines = raw.split('\n').filter(Boolean)
+      const tail = lines.slice(-LIVE_MAX_ENTRIES)
+      const tmp = `${file}.trim.tmp`
+      await writeFile(tmp, tail.join('\n') + '\n', 'utf-8')
+      await rename(tmp, file)
+    }
+    await appendFile(file, line, 'utf-8')
+  } catch {
+    // Fire-and-forget: never let live capture break a tool call.
+  }
+}
+
+/** Read the live feed (newest first), capped at the last LIVE_MAX_ENTRIES. */
+export async function readLive(projectRoot: string): Promise<LiveActivityEntry[]> {
+  const file = liveFilePath(projectRoot)
+  if (!existsSync(file)) return []
+  try {
+    const raw = await readFile(file, 'utf-8')
+    const entries: LiveActivityEntry[] = []
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue
+      try {
+        const parsed = JSON.parse(line) as LiveActivityEntry
+        if (parsed && typeof parsed.ts === 'string' && typeof parsed.type === 'string') {
+          entries.push(parsed)
+        }
+      } catch {
+        // skip malformed lines
+      }
+    }
+    return entries.slice(-LIVE_MAX_ENTRIES).reverse()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Register a `tools/result` observer that captures reviewer activity into the
+ * project's live feed. Fire-and-forget; failures are swallowed.
+ */
+export function registerLiveCapture(ctx: Context): void {
+  ctx.on('tools/result', (exec: ToolExecution) => {
+    const root = projectRootOf(exec)
+    if (!root) return
+    const entry = classifyTool(exec.name, exec.arguments, root)
+    if (!entry) return
+    void appendLive(root, entry)
+  })
+}

package/src/meta-review.ts

@@ -70,8 +70,13 @@ export interface FinalReviewReport {
   }
 }
 
-/** Number of distinct consistency checks performed by `metaReviewReport`. */
-export const META_REVIEW_CHECKS = 6
+/**
+ * Number of distinct consistency checks performed by `metaReviewReport`.
+ * The check set is: COUNT_MATCH, SEVERITY_SUM, DIMENSION_SUM, DIMENSION_UNKNOWN,
+ * SORT_ORDER, CONVERGENCE_SUM, CONVERGENCE_FLAG, ROUND_NUMBER, ROUND_EMPTY,
+ * ROUND_GAP.
+ */
+export const META_REVIEW_CHECKS = 10
 
 /**
  * How many uncovered scope files are listed in a COVERAGE_GAP hint before the
@@ -266,14 +271,23 @@ export function metaReviewReport(report: ReviewReport): MetaReviewResult {
       )
     }
   }
-  for (let i = 1; i <= rounds.length; i++) {
-    if (!seenRounds.has(i)) {
-      add(
-        'ROUND_GAP',
-        'medium',
-        `Round ${i} is missing from the round sequence`,
-        `rounds present: ${[...seenRounds].sort((a, b) => a - b).join(', ') || 'none'}.`,
-      )
+  // ROUND_GAP: only flag gaps WITHIN the range of actually-present round
+  // numbers. Non-contiguous starts (e.g. a resumed run beginning at round 5)
+  // and arbitrary round numbering are supported by the aggregate engine, so
+  // missing 1..N prefixes are NOT defects. Checks min..max of present rounds.
+  const present = [...seenRounds].sort((a, b) => a - b)
+  if (present.length > 0) {
+    const min = present[0]!
+    const max = present[present.length - 1]!
+    for (let i = min; i <= max; i++) {
+      if (!seenRounds.has(i)) {
+        add(
+          'ROUND_GAP',
+          'medium',
+          `Round ${i} is missing from the round sequence`,
+          `rounds present: ${present.join(', ')}.`,
+        )
+      }
     }
   }
 

package/src/method-scope.ts

@@ -96,6 +96,8 @@ const SIGNATURE_PATTERNS: Array<{ kind: string; re: RegExp; nameIndex: number }>
 export function collectMethodSignatures(text: string): MethodSignature[] {
   const lines = text.split('\n')
   const out: MethodSignature[] = []
+  // Set lookup instead of scanning the growing array (O(S²) → O(S)).
+  const seen = new Set<string>()
   for (let i = 0; i < lines.length; i++) {
     const raw = lines[i]!
     const line = i + 1
@@ -105,7 +107,9 @@ export function collectMethodSignatures(text: string): MethodSignature[] {
       const name = m[p.nameIndex]
       if (!name || RESERVED_WORDS.has(name) || CALLABLE_NOISE.has(name)) continue
       // Avoid two patterns claiming the same line (e.g. TS method + arrow).
-      if (out.some((s) => s.line === line && s.name === name)) break
+      const key = `${line}|${name}`
+      if (seen.has(key)) break
+      seen.add(key)
       out.push({ name, line })
       break
     }

package/src/paths.ts

@@ -36,3 +36,8 @@ export function fixBackupPath(projectRoot: string, id: string, timestamp: string
 export function checkpointPath(projectRoot: string): string {
   return join(iterateDir(projectRoot), 'checkpoint.json')
 }
+
+/** Runtime-observatory transcript file (JSON). */
+export function transcriptPath(projectRoot: string): string {
+  return join(iterateDir(projectRoot), 'transcript.json')
+}

package/src/review-scope.ts

@@ -114,20 +114,23 @@ function collectChanged(changedFiles: string[]): string[] {
 }
 
 function collectFull(root: string): string[] {
-  // Deterministic recursive walk built on Node's fs; a code reviewer never
-  // anchors findings to lock files, images, or vendored builds.
+  // Deterministic iterative walk (explicit stack — unbounded recursion could
+  // overflow on pathologically deep trees); a code reviewer never anchors
+  // findings to lock files, images, or vendored builds.
   const out: string[] = []
-  const walk = (dir: string): void => {
+  const stack: string[] = [root]
+  while (stack.length > 0) {
+    const dir = stack.pop()!
     let entries: import('node:fs').Dirent[]
     try {
       entries = readdirSync(dir, { withFileTypes: true })
     } catch {
-      return
+      continue
     }
     for (const entry of entries) {
       const abs = join(dir, entry.name)
       if (entry.isDirectory()) {
-        if (!isIgnoredDir(entry.name)) walk(abs)
+        if (!isIgnoredDir(entry.name)) stack.push(abs)
         continue
       }
       if (!entry.isFile()) continue
@@ -136,13 +139,14 @@ function collectFull(root: string): string[] {
       out.push(rel.split(SEP).join(SEP))
     }
   }
-  walk(root)
   return out.sort()
 }
 
 /** Split `files` into stable batches, keeping directory runs together. */
 export function chunkFiles(files: string[], perChunk?: number): string[][] {
-  const size = perChunk === undefined || perChunk < 1 ? DEFAULT_SCOPE_CHUNK_SIZE : perChunk
+  // Number.isFinite: NaN fails `perChunk < 1` and would yield one unbounded
+  // chunk (current.length >= NaN is never true).
+  const size = Number.isFinite(perChunk) && (perChunk as number) >= 1 ? (perChunk as number) : DEFAULT_SCOPE_CHUNK_SIZE
   const ordered = [...files].sort()
   const chunks: string[][] = []
   let current: string[] = []