iterate-plugin 2.10.0 → 2.12.0

package/README.md

@@ -1,5 +1,8 @@
 # iterate-plugin for DeepSeek Harness (dsh)
 
+> dsh 桌面端的 iterate 收敛面板、UI 分诊与审查闭环插件。把 iterate 生态的同一套 review/fix loop 直接搬进 dsh 界面。
+> The iterate ecosystem's convergence dashboard, triage UI, and review/fix loop, natively embedded inside the DeepSeek Harness (dsh) desktop client.
+
 <p align="center">
   <a href="README.md"><strong>English</strong></a> ·
   <a href="README.zh-CN.md"><strong>简体中文</strong></a>
@@ -11,9 +14,44 @@
   <a href="https://github.com/jingzhao-l/iterate-plugin"><img src="https://img.shields.io/github/stars/jingzhao-l/iterate-plugin?style=social&label=Star" alt="Stars"></a>
   <a href="https://github.com/jingzhao-l/iterate-skill"><img src="https://img.shields.io/github/stars/jingzhao-l/iterate-skill?style=social&label=Main%20Repo%20Star" alt="Main Repo Stars"></a>
   <a href="https://www.npmjs.com/package/iterate-plugin"><img src="https://img.shields.io/npm/dt/iterate-plugin?label=Downloads&logo=npm&logoColor=white" alt="npm downloads"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow" alt="License"></a>
+  <a href="https://github.com/jingzhao-l/iterate-plugin/releases"><img src="https://img.shields.io/github/v/release/jingzhao-l/iterate-plugin" alt="GitHub release"></a>
 </p>
 
-> ⭐ If this helps your dsh workflow, give the main repo a star — it means a lot!
+> ⭐ If this helps your dsh workflow, give the main repo a star — it means a lot to open-source maintenance!
+
+---
+
+## The iterate Ecosystem / iterate 生态一览
+
+**iterate** is not one single binary — it is a **skill ecosystem** that layers a strict multi-round code gate on top of your existing AI assistants, IDEs, and scripts. It never replaces your tools; it adds an audit-and-close-the-loop layer on them. The whole ecosystem ships as **three interchangeable components sharing one `iterate.config.yaml` + one review-dimension system**:
+
+| Component | Form & Source | Target Scenario |
+|---|---|---|
+| **[Core Skill + CLI](https://github.com/jingzhao-l/iterate-skill)** | Portable AI skill `/iterate` + `iterate` CLI (source: iterate-skill monorepo root) | Conversation-driven multi-round iteration inside Trae / Claude Code / Cursor / Copilot / Codex and 25+ other assistants |
+| **[iterate-harness](https://github.com/jingzhao-l/iterate-harness)** | Standalone headless engine, command `ih` (npm: `iterate-harness`) | Run the EXACT same loop in terminal / CI / git hooks, without any conversational assistant required |
+| **iterate-plugin (this repo)** | dsh desktop-client plugin (npm: `iterate-plugin`) | Plug the harness runtime **into the dsh UI**: convergence dashboard, triage panel, round progress — all surfaced as native dsh widgets |
+
+How they fit together: **Core Skill** is the canonical, assistant-agnostic review/fix engine (the "brains"). **iterate-harness** is the same engine wrapped as a headless CLI + WebUI for unattended runs. **iterate-plugin** (this repository) wraps that harness runtime as a dsh plugin, rendering the triage UI and convergence dashboard directly inside the dsh desktop client. Configuration (`iterate.config.yaml`) and the 9-dimension review system are **identical across all three** — learn one, use them all.
+
+Quick install / entry points for the rest of the ecosystem:
+
+```bash
+# Core Skill + CLI (install into 25+ AI assistants)
+npx iterate-skill-installer
+
+# iterate-harness: headless engine (npm wrapper, simplest)
+npm install -g iterate-harness
+curl -fsSL https://raw.githubusercontent.com/jingzhao-l/iterate-harness/main/scripts/install.sh | bash
+ih iterate init && ih iterate review
+
+# iterate-plugin: dsh desktop plugin (this repo — commands repeated under Installation below)
+dsh plugin --profile web add iterate-plugin
+```
+
+> This document focuses on **iterate-plugin (this repo)**. For Core Skill docs see the [iterate-skill monorepo](https://github.com/jingzhao-l/iterate-skill); for headless engine docs see [iterate-harness](https://github.com/jingzhao-l/iterate-harness).
+
+---
 
 ## About This Plugin
 
@@ -23,7 +61,7 @@
 
 `iterate-plugin` is the [iterate](https://github.com/jingzhao-l/iterate-skill) integration for the [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) desktop client. It brings iterate's review loop (review → triage → fix → validate → converge) directly into the dsh UI, offering **autonomous closed-loop code iteration** (normal mode) and **dry-run read-only multi-round review**.
 
-Besides 13 pure-function tools, it ships a **build-free Web UI layer** (triage panel, convergence dashboard, stats card, theme skin, etc.) that plugs straight into dsh's existing UI slots. Configuration (`iterate.config.yaml` and the review dimensions) is identical across the other two components of the iterate ecosystem (skill / headless engine) — zero migration cost.
+Besides 13 pure-function tools, it ships a **build-free Web UI layer** (triage panel, convergence dashboard, stats card, theme skin, etc.) that plugs straight into dsh's existing UI slots. Configuration (`iterate.config.yaml` and the review dimensions) is identical across the other two components of the iterate ecosystem ([skill](https://github.com/jingzhao-l/iterate-skill) / [headless engine](https://github.com/jingzhao-l/iterate-harness)) — zero migration cost.
 
 ## Features
 
@@ -199,6 +237,8 @@ All runtime state lives under `.iterate/` at the project root (can be excluded v
 .iterate/
   decision-log.jsonl      # append-only decision log (plan/review/fix/revert…)
   checkpoint.json         # iteration breakpoint (resume)
+  transcript.json         # runtime-observatory manifest (per-reviewer threads, trend, fixes, timeline, nudge)
+  transcript-live.ndjson  # append-only near-real-time reviewer-activity feed (read/fix/rollback/validate…), byte-capped
   fixes/
     registry.json         # fix registry (list of FixRecords, grouped by round)
     <fix-id>_<ts>.bak     # original file backup before each fix

package/README.zh-CN.md

@@ -1,5 +1,8 @@
 # iterate-plugin for DeepSeek Harness (dsh)
 
+> dsh 桌面端的 iterate 收敛面板、UI 分诊与审查闭环插件。把 iterate 生态的同一套 review/fix loop 直接搬进 dsh 界面。
+> The iterate ecosystem's convergence dashboard, triage UI, and review/fix loop, natively embedded inside the DeepSeek Harness (dsh) desktop client.
+
 <p align="center">
   <a href="README.md"><strong>English</strong></a> ·
   <a href="README.zh-CN.md"><strong>简体中文</strong></a>
@@ -11,9 +14,44 @@
   <a href="https://github.com/jingzhao-l/iterate-plugin"><img src="https://img.shields.io/github/stars/jingzhao-l/iterate-plugin?style=social&label=Star" alt="Stars"></a>
   <a href="https://github.com/jingzhao-l/iterate-skill"><img src="https://img.shields.io/github/stars/jingzhao-l/iterate-skill?style=social&label=主仓库%20Star" alt="主仓库 Stars"></a>
   <a href="https://www.npmjs.com/package/iterate-plugin"><img src="https://img.shields.io/npm/dt/iterate-plugin?label=Downloads&logo=npm&logoColor=white" alt="npm downloads"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow" alt="License"></a>
+  <a href="https://github.com/jingzhao-l/iterate-plugin/releases"><img src="https://img.shields.io/github/v/release/jingzhao-l/iterate-plugin" alt="GitHub release"></a>
 </p>
 
-> ⭐ 如果这个插件对你的 dsh 工作流有帮助，欢迎为主仓库点亮 Star，这是对开源维护最大的支持！
+> ⭐ 如果这个插件对你的 dsh 工作流有帮助，欢迎为主仓库点亮 Star，这是对开源维护最大的支持！你的 Star 能让 iterate 被更多开发者看见。
+
+---
+
+## iterate 生态一览 / The iterate Ecosystem
+
+**iterate 不是一个独立的工具，而是一套附着在现有 AI 助手之上的技能生态。** 它不会替换你的 IDE 或 AI 工具，而是在你已有的工作流里，叠加一层"严格的代码收尾与把关"。整个生态由**三个可互换组件构成，共用同一套 `iterate.config.yaml` 与同一套 9 维度审查体系**：
+
+| 组件 | 形态与位置 | 面向场景 |
+|---|---|---|
+| **[Core Skill + CLI / 核心技能与命令行](https://github.com/jingzhao-l/iterate-skill)** | 可移植 AI 技能 `/iterate` + `iterate` CLI（源码：iterate-skill 主仓库根目录） | 在 Trae / Claude Code / Cursor / Copilot / Codex 等 25+ 助手中以对话方式进行多轮迭代 |
+| **[iterate-harness / 无头引擎](https://github.com/jingzhao-l/iterate-harness)** | 独立无头引擎，命令 `ih`（npm: `iterate-harness`） | 在终端 / CI / Git 钩子里**脱离对话式助手**，运行同一套闭环 |
+| **iterate-plugin / dsh 桌面插件（本仓库）** | dsh 桌面客户端插件（npm: `iterate-plugin`） | 把 harness 运行时**直接接入 dsh 界面**：收敛看板、分诊面板、轮次进度，均以原生 dsh 控件形式展示 |
+
+三者关系：**Core Skill** 是最通用的跨助手审查/修复引擎（"大脑"）；**iterate-harness** 是同一引擎封装为无头 CLI + WebUI，适合跑在无需交互的场景；**iterate-plugin**（本仓库）把 harness 运行时进一步封装为 dsh 插件，直接在 dsh 桌面客户端内渲染分诊 UI 与收敛看板。配置（`iterate.config.yaml`）与 9 维度审查体系**三者完全一致**——理解其一，即可举一反三。
+
+生态其余组件的快速安装/入口：
+
+```bash
+# Core Skill + CLI（一键安装到 25+ AI 编程助手）
+npx iterate-skill-installer
+
+# iterate-harness：无头引擎（npm 包装器，最简）
+npm install -g iterate-harness
+curl -fsSL https://raw.githubusercontent.com/jingzhao-l/iterate-harness/main/scripts/install.sh | bash
+ih iterate init && ih iterate review
+
+# iterate-plugin：dsh 桌面插件（本仓库，安装命令在下文「安装」一节重复列出）
+dsh plugin --profile web add iterate-plugin
+```
+
+> 本文档从下一节开始聚焦 **iterate-plugin（本仓库）**。核心技能文档见 [iterate-skill 主仓库](https://github.com/jingzhao-l/iterate-skill)，无头引擎文档见 [iterate-harness 独立仓库](https://github.com/jingzhao-l/iterate-harness)。
+
+---
 
 ## 这是什么 / About This Plugin
 
@@ -23,7 +61,7 @@
 
 `iterate-plugin` 是 [iterate](https://github.com/jingzhao-l/iterate-skill) 项目在 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 桌面客户端中的落地插件。它把 iterate 的开环审查闭环（review → triage → fix → validate → 收敛）直接带进 dsh 的界面：提供**自治闭环代码迭代**（normal 模式）与 **dry-run 纯多轮审查**（只读）两种能力。
 
-除 13 个纯函数工具外，还内置一套**免构建的 Web UI 层**（分诊面板、收敛看板、统计卡片、主题皮肤等），直接挂在 dsh 客户端的既有 UI 槽位上。配置方式（`iterate.config.yaml` 与审查维度）与迭代生态的另外两个组件（技能 / 无头引擎）完全一致，迁移零成本。
+除 13 个纯函数工具外，还内置一套**免构建的 Web UI 层**（分诊面板、收敛看板、统计卡片、主题皮肤等），直接挂在 dsh 客户端的既有 UI 槽位上。配置方式（`iterate.config.yaml` 与审查维度）与迭代生态的另外两个组件（[技能](https://github.com/jingzhao-l/iterate-skill) / [无头引擎](https://github.com/jingzhao-l/iterate-harness)）完全一致，迁移零成本。
 
 ## 特性
 

package/dist/approval-gate.js

@@ -0,0 +1,92 @@
+/**
+ * src/approval-gate.ts — pure policy gate for destructive iterate tool calls.
+ *
+ * Feeds dsh's `tools/pre-execute` waterfall (registered in `session-hooks.ts`).
+ * The gate classifies a tool execution and returns a typed decision without
+ * 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: 'deny', reason }` → refuse; the caller surfaces the reason.
+ *
+ * Policy (config `observatory.approval`, default 'ask'):
+ *   - `allow` → destructive iterate calls always run (debug/trusted).
+ *   - `deny`  → destructive iterate calls are always refused (fail-closed).
+ *   - `ask`   → destructive iterate calls prompt the human first.
+ *
+ * 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).
+ * Read-only calls are always allowed. Non-iterate calls are untouched — the
+ * gate only ever inspects iterate tools so it cannot alter unrelated behavior.
+ */
+/** Destructive iterate tools subject to the gate. */
+const DESTRUCTIVE_TOOLS = new Set(['iterate_fix', 'iterate_rollback', 'iterate_prune']);
+/** Human-readable reason rendered in the approval prompt. */
+function describe(toolName, arguments0) {
+    const file = arguments0 && typeof arguments0.file === 'string'
+        ? `\`${arguments0.file}\``
+        : 'the workspace';
+    switch (toolName) {
+        case 'iterate_fix':
+            return `Apply an atomic fix to ${file}`;
+        case 'iterate_rollback': {
+            const id = arguments0 && typeof arguments0.id === 'string' ? ` \`${arguments0.id}\`` : '';
+            return `Revert fix${id} (restore ${file} from backup)`;
+        }
+        case 'iterate_prune':
+            return 'Delete stale `.iterate/` runtime artifacts';
+        default:
+            return `Run ${toolName}`;
+    }
+}
+/**
+ * Decide whether a tool execution may proceed under the given policy.
+ * Returns `allow` for read-only prune (`dryRun: true`), for `allow`-policy
+ * deployments, and for any non-iterate tool.
+ */
+export function decideApproval(execution, policy) {
+    const name = typeof execution?.name === 'string' ? execution.name : '';
+    if (!name)
+        return { kind: 'allow' };
+    if (!DESTRUCTIVE_TOOLS.has(name))
+        return { kind: 'allow' };
+    const rawArgs = execution.arguments;
+    const args = rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs)
+        ? rawArgs
+        : {};
+    // `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' };
+    }
+    if (policy === 'allow')
+        return { kind: 'allow' };
+    const reason = describe(name, args);
+    if (policy === 'deny')
+        return { kind: 'deny', reason };
+    return { kind: 'ask', reason };
+}
+/** True when any destructive iterate tool is listed in a name set. */
+export function isDestructiveIterateTool(name) {
+    return typeof name === 'string' && DESTRUCTIVE_TOOLS.has(name);
+}
+/**
+ * Evaluate an iterate tool's own boundary gate for a destructive call.
+ * `approvedArg` is the caller-supplied `approved: true` flag (human consent
+ * already obtained). Returns a run / refuse result without any I/O.
+ */
+export function toolGate(policy, execution, approvedArg) {
+    const decision = decideApproval(execution, policy);
+    if (decision.kind === 'allow')
+        return { ok: true };
+    if (decision.kind === 'deny') {
+        return { ok: false, error: `Blocked by observatory approval policy: ${decision.reason}` };
+    }
+    // ask
+    if (approvedArg === true)
+        return { ok: true };
+    return { ok: false, requiresApproval: true, reason: decision.reason };
+}

package/dist/config-loader.js

@@ -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';
@@ -55,6 +55,10 @@ export function defaultConfig() {
             coverage_validation: true,
             scope_chunk_size: 25,
         },
+        observatory: {
+            capture: true,
+            approval: 'ask',
+        },
     };
 }
 /**
@@ -72,6 +76,11 @@ export function mergeConfig(base, override) {
     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 &&
             typeof baseValue === 'object' &&
@@ -223,8 +232,14 @@ function effectiveCwd(sessionCwd) {
         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/dist/config-write.js

@@ -9,7 +9,7 @@
  * The security posture mirrors the triage tool: never overwrite a malformed
  * 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';
 /** Config file name (must match config-loader). */
@@ -161,14 +161,17 @@ export function writeConfigFile(projectRoot, config) {
         writeFileSync(configPath, yaml.dump(config, { noRefs: true }), 'utf-8');
     }
     catch (err) {
+        let rollbackError = '';
         try {
             if (backupPath)
                 copyFileSync(backupPath, configPath);
+            else if (existsSync(configPath))
+                rmSync(configPath, { force: true });
         }
-        catch {
-            // Rollback failure is reported, never swallowed silently.
+        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/dist/evidence.js

@@ -22,10 +22,17 @@
  * The pure math (`countLines`, `verifyLineBounds`) is separated from the
  * 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';
 /** 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;
 /** Number of physical lines in `text`. A trailing newline does not add a line. */
 export function countLines(text) {
     if (text === '')
@@ -51,6 +58,22 @@ export function resolveWithin(root, rel) {
         return null;
     return resolved;
 }
+/** True when `candidate` is `root` itself or lexically inside `root`. */
+function isWithin(root, candidate) {
+    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) {
+    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.
@@ -79,6 +102,49 @@ export function verifyFinding(root, input, opts = {}) {
             error: 'file_not_found',
         };
     }
+    // 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;
     try {
         raw = readFileSync(resolved);

package/dist/git-scope.js

@@ -24,14 +24,31 @@ import { execFile } from 'node:child_process';
 import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 /**
- * 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) {
+    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.fromCharCode(parseInt(oct, 8)));
+    })
         .filter((line) => line.length > 0);
 }
 /**
@@ -90,9 +107,21 @@ export function runGit(args, cwd) {
  * plan because git is unavailable.
  */
 export async function resolveChangedFiles(root, targetBranch) {
-    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/dist/index.js

@@ -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)
@@ -32,11 +34,14 @@ import { registerFixTool, registerDiffTool, registerRollbackTool } from "./tools
 import { registerCheckpointTool, registerStatusTool } from "./tools/checkpoint.js";
 import { registerHistoryTool } from "./tools/history.js";
 import { registerPruneTool } from "./tools/prune.js";
+import { registerTranscriptTool } from "./tools/transcript.js";
+import { registerSessionHooks } from "./session-hooks.js";
+import { registerLiveCapture } from "./live.js";
 import { ITERATE_SKILL_PROMPT } from "./skill-prompt.js";
 export const name = 'iterate-plugin';
 export const inject = ['tools', 'systemPrompt'];
 export function apply(ctx) {
-    // 1. Register the 13 tools
+    // 1. Register the 14 tools
     registerConfigTool(ctx);
     registerValidateTool(ctx);
     registerDecisionLogTool(ctx);
@@ -50,6 +55,11 @@ export function apply(ctx) {
     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.
     ctx.systemPrompt.section({