iterate-plugin 3.5.6 → 3.6.0

package/package.json

@@ -1,17 +1,16 @@
 {
   "name": "iterate-plugin",
-  "version": "3.5.6",
+  "version": "3.6.0",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness with quality command center and experience bank (v3.3). Features: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus dry-run pure-review mode, quality gate compute/persist, writable experience bank, defense events stream (record + bilingual labels), and native command buttons — with a live quality command center (F8/F9/F10 render real session data), §8 assign-fix instruction, and task_mode indicator wired end to end.",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jingzhao-l/iterate-skill.git",
-    "directory": "harness/iterate-plugin"
+    "url": "https://github.com/jingzhao-l/iterate-plugin.git"
   },
-  "homepage": "https://github.com/jingzhao-l/iterate-skill/tree/main/harness/iterate-plugin",
+  "homepage": "https://github.com/jingzhao-l/iterate-plugin",
   "bugs": {
-    "url": "https://github.com/jingzhao-l/iterate-skill/issues"
+    "url": "https://github.com/jingzhao-l/iterate-plugin/issues"
   },
   "keywords": [
     "dsh-plugin",
@@ -42,7 +41,11 @@
         "0.1.6-alpha.2": "compatible",
         "0.1.7-alpha.1": "compatible",
         "0.1.7-alpha.2": "compatible",
-        "0.1.7-rc.1": "compatible"
+        "0.1.7-rc.1": "compatible",
+        "0.1.7-rc.2": "compatible",
+        "0.2.0-rc.1": "compatible",
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-alpha.1": "compatible"
       }
     },
     "client": {
@@ -79,15 +82,15 @@
     "test:validate": "tsx --test test/validate.test.ts"
   },
   "dependencies": {
-    "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-tools": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-util-values": "0.1.7-rc.1",
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-util-values": "0.2.1-alpha.1",
     "js-yaml": "4.3.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-jobs": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-jobs": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.1",
     "@types/js-yaml": "4.0.9",
     "@types/node": "22.15.0",
     "@types/react": "19.2.2",

package/src/approval-gate.ts

@@ -6,9 +6,19 @@
  * any I/O, so it is fully unit-testable:
  *
  *   - `{ kind: 'allow' }`        → run the call.
- *   - `{ kind: 'ask', reason }`  → prompt the human via the dsh approval service.
+ *   - `{ kind: 'ask', reason, displayReason }` → prompt the human via the dsh
+ *     approval service (`displayReason` carries the localized prompt text;
+ *     dsh 0.2.x renders it when present).
  *   - `{ kind: 'deny', reason }` → refuse; the caller surfaces the reason.
  *
+ * LANGUAGE RULE (project `config.language`, zh|en):
+ *   - Human-facing text (the `ask` prompt / `displayReason`) FOLLOWS the
+ *     configured language.
+ *   - Structured/durable text (the `deny` reason, `deny.info.reason`,
+ *     decision-log and console output) STAYS ENGLISH so logs, audits, and
+ *     machine matchers never depend on a locale. `ask.reason` is the audited
+ *     English summary; `displayReason` is the localized prompt.
+ *
  * Policy (config `observatory.approval`, default 'ask'):
  *   - `allow` → destructive iterate calls always run (debug/trusted).
  *   - `deny`  → destructive iterate calls are always refused (fail-closed).
@@ -16,14 +26,33 @@
  *
  * Destructive calls are exactly the ones that mutate the workspace:
  * `iterate_fix` (writes files), `iterate_rollback` (restores from backups),
- * and `iterate_prune` with `dryRun !== true` (deletes `.iterate/` artifacts).
+ * `iterate_prune` with `dryRun === false` (deletes `.iterate/` artifacts —
+ * prune is read-only by default, so only an explicit `dryRun: false` gates),
+ * and `iterate_config` with `operation === 'write'` (rewrites
+ * `iterate.config.yaml`). `iterate_config` writes matter because the config
+ * is policy: a silent `reviewer: {evidence_validation: false}` or a
+ * `validation.commands` addition changes what later rounds are allowed to do,
+ * so a write is consented to exactly like a file write — the read operation
+ * stays free.
  * Read-only calls are always allowed. Non-iterate calls are untouched — the
  * gate only ever inspects iterate tools so it cannot alter unrelated behavior.
  */
 
+/** The languages the consent prompt can render (mirrors config.language). */
+export type ApprovalLanguage = 'zh' | 'en'
+
+/** Locale map accepted by dsh's `PreToolDecision.displayReason` (en is required). */
+export type ApprovalDisplayReason = { readonly en: string; readonly [locale: string]: string }
+
 export type ApprovalDecision =
   | { kind: 'allow' }
-  | { kind: 'ask'; reason: string }
+  | {
+      kind: 'ask'
+      /** Audited, English, machine-readable summary of what is being asked. */
+      reason: string
+      /** Localized prompt text (en, plus zh when configured). */
+      displayReason: ApprovalDisplayReason
+    }
   | { kind: 'deny'; reason: string }
 
 /** The subset of a tool execution the gate inspects. */
@@ -32,38 +61,134 @@ export interface ToolExecutionLike {
   arguments?: unknown
 }
 
-/** Destructive iterate tools subject to the gate. */
-const DESTRUCTIVE_TOOLS = new Set(['iterate_fix', 'iterate_rollback', 'iterate_prune'])
+/** Iterate tools subject to the gate (some only in specific operations). */
+const DESTRUCTIVE_TOOLS = new Set([
+  'iterate_fix',
+  'iterate_rollback',
+  'iterate_prune',
+  'iterate_config',
+])
 
-/** Human-readable reason rendered in the approval prompt. */
-function describe(toolName: string, arguments0?: Record<string, unknown>): string {
+/**
+ * True when this specific call MUTATES the workspace and therefore needs
+ * consent. Two of the four gated tools are operation-conditional:
+ *   - `iterate_prune` is read-only unless `dryRun === false`;
+ *   - `iterate_config` reads freely, but `operation === 'write'` rewrites
+ *     `iterate.config.yaml` — the file that carries the approval policy,
+ *     the reviewer gates, and the command allow-list.
+ */
+function mutatesWorkspace(toolName: string, args: Record<string, unknown>): boolean {
+  if (toolName === 'iterate_prune') return args.dryRun === false
+  if (toolName === 'iterate_config') return args.operation === 'write'
+  return DESTRUCTIVE_TOOLS.has(toolName)
+}
+
+/** Config updates the model supplied (empty when absent/malformed). */
+function readUpdates(args: Record<string, unknown>): Record<string, unknown> {
+  const u = args.updates
+  return u && typeof u === 'object' && !Array.isArray(u) ? (u as Record<string, unknown>) : {}
+}
+
+/**
+ * Config switches that DISABLE a safety gate, for the consent text. Writing
+ * `reviewer.evidence_validation: false` is legal config — but the human being
+ * asked must see that the call is about to turn a review gate off, not just
+ * "update a file".
+ */
+function disabledReviewGates(updates: Record<string, unknown>): string[] {
+  const rv = updates.reviewer
+  if (!rv || typeof rv !== 'object' || Array.isArray(rv)) return []
+  const off: string[] = []
+  for (const key of ['output_schema_validation', 'evidence_validation', 'coverage_validation'] as const) {
+    if ((rv as Record<string, unknown>)[key] === false) off.push(`reviewer.${key}`)
+  }
+  return off
+}
+
+/**
+ * Human-readable reason rendered in the approval prompt.
+ *
+ * `language` selects the wording of the HUMAN-FACING text; call it with
+ * `'en'` for the structured, machine-readable string (deny reasons, audited
+ * ask summaries) and with the project's configured language for the prompt
+ * text (`displayReason`). The structured deny reason therefore never
+ * localizes, while the consent prompt follows `config.language`.
+ */
+export function describe(
+  toolName: string,
+  arguments0?: Record<string, unknown>,
+  language: ApprovalLanguage = 'en',
+): string {
+  const zh = language === 'zh'
   const file =
     arguments0 && typeof arguments0.file === 'string'
       ? `\`${arguments0.file}\``
-      : 'the workspace'
+      : zh
+        ? '工作区'
+        : 'the workspace'
   switch (toolName) {
     case 'iterate_fix':
-      return `Apply an atomic fix to ${file}`
+      return zh
+        ? `对 ${file} 应用一次原子修复`
+        : `Apply an atomic fix to ${file}`
     case 'iterate_rollback': {
+      // Rollback's parameters are `id` (required) + `path` (project root) —
+      // it has NO `file` param, so naming `arguments.file` could never
+      // identify the target ("restore the workspace from backup" every time).
+      // Name the fix id and, when present, the project scope instead.
       const id =
-        arguments0 && typeof arguments0.id === 'string' ? ` \`${arguments0.id}\`` : ''
-      return `Revert fix${id} (restore ${file} from backup)`
+        arguments0 && typeof arguments0.id === 'string' && arguments0.id
+          ? `\`${arguments0.id}\``
+          : null
+      const scope =
+        arguments0 && typeof arguments0.path === 'string' && arguments0.path
+          ? `\`${arguments0.path}\``
+          : null
+      const target = id ?? scope ?? (zh ? '一次修复' : 'a fix')
+      const inScope = id && scope ? (zh ? `（位于 ${scope}）` : ` in ${scope}`) : ''
+      return zh
+        ? `回滚修复 ${target}${inScope}（从备份恢复其文件）`
+        : `Revert fix ${target}${inScope} (restore its file from backup)`
     }
     case 'iterate_prune':
-      return 'Delete stale `.iterate/` runtime artifacts'
+      return zh
+        ? '删除过期的 `.iterate/` 运行时产物'
+        : 'Delete stale `.iterate/` runtime artifacts'
+    case 'iterate_config': {
+      // Name WHAT is being written and shout when the write disables a review
+      // gate — the consent prompt is the last human look before the model
+      // rewrites the policy file. The WARNING marker stays literal in both
+      // languages so the UI's highlight rule matches on it.
+      const updates = readUpdates(arguments0 ?? {})
+      const keys = Object.keys(updates)
+      const scope = keys.length > 0 ? keys.map((k) => `\`${k}\``).join(', ') : (zh ? '配置' : 'the configuration')
+      const base = zh
+        ? `更新 \`iterate.config.yaml\`（${scope}）`
+        : `Update \`iterate.config.yaml\` (${scope})`
+      const off = disabledReviewGates(updates)
+      if (off.length === 0) return base
+      return zh
+        ? `${base} — WARNING：将关闭 ${off.join(', ')}`
+        : `${base} — WARNING: turns OFF ${off.join(', ')}`
+    }
     default:
-      return `Run ${toolName}`
+      return zh ? `运行 ${toolName}` : `Run ${toolName}`
   }
 }
 
 /**
  * Decide whether a tool execution may proceed under the given policy.
- * Returns `allow` for read-only prune (`dryRun: true`), for `allow`-policy
+ * Returns `allow` for read-only prune (`dryRun: true`), for config READS
+ * (`iterate_config` without `operation: 'write'`), for `allow`-policy
  * deployments, and for any non-iterate tool.
+ *
+ * `language` only affects the HUMAN-FACING `ask.displayReason` text; the
+ * audited `ask.reason` and the `deny.reason` stay English (see header).
  */
 export function decideApproval(
   execution: ToolExecutionLike,
   policy: 'ask' | 'deny' | 'allow',
+  language: ApprovalLanguage = 'en',
 ): ApprovalDecision {
   // Defensive reads: a hostile/proxied execution object must degrade to "not
   // our tool" (allow) rather than throw inside the gate.
@@ -86,20 +211,32 @@ export function decideApproval(
     rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs)
       ? (rawArgs as Record<string, unknown>)
       : {}
-  // `iterate_prune` is read-only in its default dry-run mode — no gate needed.
-  if (name === 'iterate_prune' && args.dryRun === false) {
-    // falls through to the destructive path below
-  } else if (name === 'iterate_prune') {
-    return { kind: 'allow' }
-  }
+  // Operation-conditional tools are read-only in their default operation —
+  // `iterate_prune` dry-runs and `iterate_config` reads need no consent.
+  if (!mutatesWorkspace(name, args)) return { kind: 'allow' }
 
   if (policy === 'allow') return { kind: 'allow' }
-  const reason = describe(name, args)
+  // Structured text (deny reason / audited ask summary) is always English;
+  // only the human prompt (`displayReason`) follows the project language.
+  const reason = describe(name, args, 'en')
   if (policy === 'deny') return { kind: 'deny', reason }
-  return { kind: 'ask', reason }
+  const localized = describe(name, args, language)
+  return {
+    kind: 'ask',
+    reason,
+    displayReason:
+      language === 'zh' ? { en: reason, zh: localized } : { en: reason },
+  }
 }
 
-/** True when any destructive iterate tool is listed in a name set. */
+/**
+ * True when a tool name is ROUTED through the approval gate.
+ *
+ * Name-level only (the caller has not parsed arguments yet), so the two
+ * operation-conditional tools are included for their whole name and
+ * {@link decideApproval} narrows per call: prune with a dry run and
+ * `iterate_config` reads both come back `allow`.
+ */
 export function isDestructiveIterateTool(name: unknown): boolean {
   return typeof name === 'string' && DESTRUCTIVE_TOOLS.has(name)
 }

package/src/atomic-fs.ts

@@ -4,16 +4,37 @@
  * Every JSON/YAML artifact the plugin persists (.iterate/*.json,
  * iterate.config.yaml) is written through here: content goes to a
  * uniquely-named temp file in the SAME directory as the target (rename is
- * only atomic within one filesystem), then is `renameSync`ed over the
- * destination. A crash mid-write can therefore leave a stale temp file
- * behind, but never a truncated / half-written state file — readers
- * (which all tolerate missing/corrupt files) see either the previous or
- * the new content, never a mixture.
+ * only atomic within one filesystem), is fsynced to plating, then is
+ * `renameSync`ed over the destination, followed by a best-effort directory
+ * fsync so the rename itself is durable. A crash mid-write can therefore
+ * leave a stale temp file behind, but never a truncated / half-written state
+ * file — readers (which all tolerate missing/corrupt files) see either the
+ * previous or the new content, never a mixture.
+ *
+ * Two properties travel with the rename (which REPLACES the target inode):
+ *   - permissions: the temp is given the existing target's mode before the
+ *     swap, so rewriting a 0755 script stays 0755 and a 0600 secret never
+ *     widens to the umask default (0644).
+ *   - symlinks: when the target is a symlink, the atomic replace runs on the
+ *     link's REAL target instead — a fix written through a linked source file
+ *     must reach the real file, and the link must survive as a link.
  */
 
-import { dirname, join } from 'node:path'
-import { renameSync, rmSync, writeFileSync } from 'node:fs'
-import { rename, rm, writeFile } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import {
+  closeSync,
+  fchmodSync,
+  fsyncSync,
+  lstatSync,
+  openSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeSync,
+} from 'node:fs'
+import { lstat, open, realpath, rename, rm, stat } from 'node:fs/promises'
+import type { FileHandle } from 'node:fs/promises'
 
 /** Best-effort unlink of a leftover temp file (never throws). */
 function cleanupTemp(tmp: string): void {
@@ -37,25 +58,126 @@ async function cleanupTempAsync(tmp: string): Promise<void> {
  * Unique temp file path for `filePath`, in the same directory, following the
  * prunable `.<basename>.tmp-<pid>-<random>` convention (see prune.ts
  * `isPrunableTemp`). The pid+random suffix makes concurrent writers safe.
+ * `basename` from node:path handles the platform separator (a hand-rolled
+ * `split('/')` breaks on Windows paths).
  */
 function tempPathFor(filePath: string): string {
   return join(
     dirname(filePath),
-    `.${filePath.split('/').pop() ?? 'file'}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`,
+    `.${basename(filePath)}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`,
   )
 }
 
 /**
- * Write `data` to `filePath` atomically (temp file + rename, same dir).
+ * Resolve the path the atomic replace must actually run on. A symlinked
+ * target is resolved to its real path: `renameSync(tmp, link)` would swap the
+ * LINK for a regular file and the linked-to file would silently keep its old
+ * content (a fix that never reaches the real source). When lstat/realpath
+ * cannot resolve (missing target, dangling or unreadable link), fall back to
+ * writing `filePath` itself — the pre-symlink-aware behavior.
+ */
+function resolveAtomicTarget(filePath: string): string {
+  try {
+    if (lstatSync(filePath).isSymbolicLink()) return realpathSync(filePath)
+  } catch {
+    // Missing target or unresolvable link — write `filePath` itself.
+  }
+  return filePath
+}
+
+/** Async variant of {@link resolveAtomicTarget}. */
+async function resolveAtomicTargetAsync(filePath: string): Promise<string> {
+  try {
+    if ((await lstat(filePath)).isSymbolicLink()) return await realpath(filePath)
+  } catch {
+    // Missing target or unresolvable link — write `filePath` itself.
+  }
+  return filePath
+}
+
+/**
+ * The permission bits to give the temp file: the existing target's mode (so
+ * the rename-over swap preserves it), or `null` for a brand-new file — then
+ * the default open mode (0o666 & ~umask) applies, exactly like a plain
+ * `writeFileSync` of a new file.
+ */
+function existingMode(target: string): number | null {
+  try {
+    return statSync(target).mode & 0o777
+  } catch {
+    return null
+  }
+}
+
+/** Async variant of {@link existingMode}. */
+async function existingModeAsync(target: string): Promise<number | null> {
+  try {
+    return (await stat(target)).mode & 0o777
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Best-effort fsync of the directory holding the final file, so the rename
+ * itself survives a crash. Unsupported on some platforms/filesystems — the
+ * data is already durable (fsynced on the temp), this only covers the
+ * directory entry, so failure is ignored by design.
+ */
+function fsyncDirBestEffort(dir: string): void {
+  try {
+    const fd = openSync(dir, 'r')
+    try {
+      fsyncSync(fd)
+    } finally {
+      closeSync(fd)
+    }
+  } catch {
+    // Directory fsync is unavailable (Windows, some FUSE mounts) — durability
+    // of the content does not depend on it.
+  }
+}
+
+/** Async variant of {@link fsyncDirBestEffort}. */
+async function fsyncDirBestEffortAsync(dir: string): Promise<void> {
+  let dh: FileHandle | undefined
+  try {
+    dh = await open(dir, 'r')
+    await dh.sync()
+  } catch {
+    // Directory fsync is unavailable — see fsyncDirBestEffort.
+  } finally {
+    if (dh) {
+      await dh.close().catch(() => {})
+    }
+  }
+}
+
+/**
+ * Write `data` to `filePath` atomically (temp file + fsync + rename, same dir).
  * Temp files follow the `<name>.tmp-<pid>-<random>` convention also used by
- * prune.ts / checkpoint.ts so they are recognizable and prunable.
+ * prune.ts / checkpoint.ts so they are recognizable and prunable. The existing
+ * target's mode is preserved across the swap and symlinked targets are
+ * resolved first (see the header).
  * Throws on failure (callers own error reporting — they map failures to
  * structured tool results).
  */
 export function writeTextAtomic(filePath: string, data: string): void {
-  const tmp = tempPathFor(filePath)
+  const target = resolveAtomicTarget(filePath)
+  const tmp = tempPathFor(target)
+  const mode = existingMode(target)
   try {
-    writeFileSync(tmp, data, 'utf-8')
+    // fd-based write so the mode can be pinned and the CONTENT fsynced before
+    // the rename — a crash after rename but before the data hit the disk would
+    // otherwise leave a zero-length / torn state file.
+    const fd = openSync(tmp, 'w')
+    try {
+      writeSync(fd, data, null, 'utf-8')
+      if (mode !== null) fchmodSync(fd, mode)
+      fsyncSync(fd)
+    } finally {
+      closeSync(fd)
+    }
   } catch (err) {
     // The write itself failed (disk full, permission, …): the temp file may
     // already be partially written, so remove it before propagating — a
@@ -64,19 +186,31 @@ export function writeTextAtomic(filePath: string, data: string): void {
     throw err
   }
   try {
-    renameSync(tmp, filePath)
+    renameSync(tmp, target)
   } catch (err) {
     // Best-effort temp cleanup so a failed rename never litters the directory.
     cleanupTemp(tmp)
     throw err
   }
+  fsyncDirBestEffort(dirname(target))
 }
 
 /** Async variant of {@link writeTextAtomic} (same temp naming convention). */
 export async function writeTextAtomicAsync(filePath: string, data: string): Promise<void> {
-  const tmp = tempPathFor(filePath)
+  const target = await resolveAtomicTargetAsync(filePath)
+  const tmp = tempPathFor(target)
+  const mode = await existingModeAsync(target)
   try {
-    await writeFile(tmp, data, 'utf-8')
+    // fd-based write: pin the target's mode and fsync the content before the
+    // rename (mirrors the sync variant — see writeTextAtomic).
+    const fh = await open(tmp, 'w')
+    try {
+      await fh.writeFile(data, 'utf-8')
+      if (mode !== null) await fh.chmod(mode)
+      await fh.sync()
+    } finally {
+      await fh.close()
+    }
   } catch (err) {
     // The write itself failed (disk full, permission, …): the temp file may
     // already be partially written, so remove it before propagating — a
@@ -85,12 +219,13 @@ export async function writeTextAtomicAsync(filePath: string, data: string): Prom
     throw err
   }
   try {
-    await rename(tmp, filePath)
+    await rename(tmp, target)
   } catch (err) {
     // Best-effort temp cleanup so a failed rename never litters the directory.
     await cleanupTempAsync(tmp)
     throw err
   }
+  await fsyncDirBestEffortAsync(dirname(target))
 }
 
 /** JSON.stringify (2-space indent) + atomic write in one call. */