iterate-plugin 2.12.1 → 2.12.3

package/README.md

@@ -95,7 +95,8 @@ Besides 13 pure-function tools, it ships a **build-free Web UI layer** (triage p
 
 | UI component | Mounted slot | Function |
 | --- | --- | --- |
-| ConvergenceDashboard | `conversation.input.dock` | Live round progress bar, severity stats, dimension badges, trend mini-chart above the input; normal mode also shows fix-count badges |
+| ConvergenceDashboard | `conversation.input.dock` | Live round progress bar, severity stats, dimension badges, trend mini-chart above the input; normal mode also shows fix-count badges; plus a live workflow-phase chip (current phase + running/stopped) |
+| ObservatoryPanel | `conversation.input.dock` | Seven-tab runtime observatory below the input: live activity stream (type filter), review threads (expand/collapse all), convergence trend, finding locations (severity/dimension/search filter), fixes + rollback, checkpoint resume, decision timeline (type/round filter + search); one-click export of all observatory data to JSON (download, copy fallback) |
 | TriagePanel | `conversation.chat.turnTail` | Per-finding y/n/a triage, filtering, batch (incl. select-all), keyboard shortcuts, localStorage persistence, copy-YAML / apply-instruction |
 | StatsCard | `conversation.chat.turnTail` | When no findings remain: convergence stats, round history table, trend chart, completion summary |
 | iterate theme skin | `theme.overrideTokens` | Warm-amber 13-dsw-token override, light/dark modes, togglable in settings |

package/README.zh-CN.md

@@ -95,7 +95,8 @@ dsh plugin --profile web add iterate-plugin
 
 | UI 组件 | 挂载槽位 | 功能 |
 |---------|---------|------|
-| 收敛看板 `ConvergenceDashboard` | `conversation.input.dock` | 输入框上方实时显示轮次进度条、严重度统计、维度徽章、趋势迷你图，normal 模式另显示修复计数徽章 |
+| 收敛看板 `ConvergenceDashboard` | `conversation.input.dock` | 输入框上方实时显示轮次进度条、严重度统计、维度徽章、趋势迷你图，normal 模式另显示修复计数徽章；并显示运行阶段芯片（当前工作流阶段 + 运行中/已结束） |
+| 运行时观测台 `ObservatoryPanel` | `conversation.input.dock` | 输入框下方七个标签页：实时活动流（支持按活动类型筛选）、审查线程（支持全部展开/全部收起）、收敛趋势、发现定位（支持按严重度/维度/关键词筛选）、修复与回滚、断点恢复、决策时间线（支持按类型/轮次筛选与关键词搜索）；支持一键导出全部观测数据为 JSON（优先下载，失败回退复制） |
 | Findings 分诊面板 `TriagePanel` | `conversation.chat.turnTail` | 逐条 y/n/a 判定，支持筛选、批量（含一键全选所有 findings）、键盘快捷键、localStorage 持久化、复制 YAML/应用指令 |
 | 收敛统计卡片 `StatsCard` | `conversation.chat.turnTail` | 无 findings 时显示收敛统计、历史轮次表、趋势图、完成摘要 |
 | iterate 主题皮肤 | `theme.overrideTokens` | 暖琥珀配色的 13 个 dsw token 覆盖，明暗双模式，可在设置页开关 |

package/dist/git-scope.js

@@ -29,6 +29,64 @@ import { join } from 'node:path';
  * NUL is present (callers that did not pass -z) fall back to newline-split
  * with C-style quote/escape unescaping for core.quotePath output.
  */
+/**
+ * Decode the quoted body of a git core.quotePath output line into the real
+ * filename bytes, then interpret them as UTF-8.
+ *
+ * Single-pass and escape-atomic: each `\` consumes exactly one escape (\" \\
+ * \t \n or a 3-digit octal for a raw byte), so a literal `\\303` in a filename
+ * (escaped backslash + literal "303") is decoded as the byte `\` followed by
+ * ASCII "303" rather than as the single byte 0xC3. Ordinary characters in the
+ * quoted body are ASCII (git always octal-escapes non-ASCII bytes), so they map
+ * 1:1 to bytes.
+ */
+function decodeQuotedPath(content) {
+    const bytes = [];
+    let i = 0;
+    while (i < content.length) {
+        const ch = content[i];
+        if (ch !== '\\') {
+            bytes.push(ch.charCodeAt(0));
+            i++;
+            continue;
+        }
+        const next = content[i + 1];
+        if (next === '"') {
+            bytes.push(0x22);
+            i += 2;
+        }
+        else if (next === '\\') {
+            bytes.push(0x5c);
+            i += 2;
+        }
+        else if (next === 't') {
+            bytes.push(0x09);
+            i += 2;
+        }
+        else if (next === 'n') {
+            bytes.push(0x0a);
+            i += 2;
+        }
+        else if (next !== undefined && next >= '0' && next <= '7') {
+            const oct = content.slice(i + 1, i + 4);
+            if (oct.length === 3 && /^[0-7]{3}$/.test(oct)) {
+                bytes.push(parseInt(oct, 8));
+                i += 4;
+            }
+            else {
+                // Malformed octal — keep the backslash literally.
+                bytes.push(0x5c);
+                i++;
+            }
+        }
+        else {
+            // Unknown escape — keep the backslash literally.
+            bytes.push(0x5c);
+            i++;
+        }
+    }
+    return Buffer.from(bytes).toString('utf-8');
+}
 export function parseChangedFiles(stdout) {
     if (stdout.includes('\0')) {
         return stdout.split('\0').map((s) => s.trim()).filter((s) => s.length > 0);
@@ -38,16 +96,12 @@ export function parseChangedFiles(stdout) {
         .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).
+        // content uses C-style escapes (\" \\ \t \n) and \ooo octal escapes for
+        // non-ASCII bytes (which are raw UTF-8 BYTES, not Latin-1 code points).
         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)));
+        return decodeQuotedPath(quoted[1]);
     })
         .filter((line) => line.length > 0);
 }

package/dist/jobs.js

@@ -0,0 +1,68 @@
+/**
+ * src/jobs.ts — dsh Job Panel integration for iterate tool executions.
+ *
+ * dsh's background-job registry (`ctx.jobs`, @deepseek-ai/dsh-jobs) lets
+ * plugins surface long-running work in the client's Job Panel
+ * (`conversation.session.header.actions` list). We register custom kinds via
+ * declaration merging and wrap tool executions so each `iterate_review` /
+ * `iterate_fix` call shows up as a tracked job (running -> completed/failed).
+ *
+ * Defensive by design (matches the plugin's overall philosophy):
+ * - `ctx.jobs` only exists when the dsh host loaded a job registry + a
+ *   controller serves the calling owner (`@deepseek-ai/dsh-tool-jobs` or an
+ *   equivalent). When it is missing, `start()` throws or is absent — we
+ *   detect both and fall through to plain execution, so the Job Panel is a
+ *   pure enhancement and never breaks a tool call.
+ * - The registry is memory-only and panel rows are read-only (no progress
+ *   updates), so these jobs are completion records, not control channels.
+ */
+/**
+ * Run `fn` wrapped in a dsh background job, settling it completed/failed
+ * with the execution's outcome. When the host exposes no job registry (or
+ * refuses the start), `fn` runs untouched and `null` is returned — the Job
+ * Panel is an enhancement, never a dependency.
+ *
+ * @param ctx      the dsh plugin context (may or may not expose `jobs`).
+ * @param kind     iterate job kind registered via {@link IterateJobKind}.
+ * @param label    one-line job label shown in the panel.
+ * @param fn       the tool execution to track.
+ * @returns the registry-issued job id, or `null` when unavailable.
+ */
+export async function runWithJob(ctx, kind, label, fn) {
+    const jobs = ctx?.jobs;
+    if (!jobs || typeof jobs.start !== 'function') {
+        return { result: await fn(), jobId: null };
+    }
+    let settle;
+    const done = new Promise((resolve) => {
+        settle = resolve;
+    });
+    let jobId = null;
+    try {
+        jobId = jobs.start({
+            kind,
+            label,
+            run: () => ({
+                done,
+                cancel: () => settle({ status: 'killed', detail: 'cancelled' }),
+            }),
+        });
+    }
+    catch {
+        // Registry present but refuses work (e.g. no controller serves this
+        // owner) — run without panel tracking.
+        return { result: await fn(), jobId: null };
+    }
+    try {
+        const result = await fn();
+        settle({ status: 'completed', detail: 'done' });
+        return { result, jobId };
+    }
+    catch (error) {
+        settle({
+            status: 'failed',
+            detail: error instanceof Error ? error.message : 'execution failed',
+        });
+        throw error;
+    }
+}

package/dist/review.js

@@ -464,6 +464,40 @@ export function sanitizeRounds(rounds, schemaValidation) {
         };
     });
 }
+/**
+ * Build the "attached visual context" instruction block for a reviewer prompt.
+ *
+ * ``path``/``data`` attachments (screenshots, mockups, failure repros) are
+ * evidence a reviewer must weigh alongside the code — this clause names each
+ * one and mandates that the reviewer inspect/consider it (e.g. by opening the
+ * file with a vision-capable tool or the ``image_to_text`` bridge) before
+ * judging. Pure string construction; returns ``""`` when there are none.
+ */
+export function attachmentClause(attachments) {
+    if (!attachments || attachments.length === 0)
+        return '';
+    const lines = [];
+    for (const a of attachments) {
+        if (!a || typeof a !== 'object')
+            continue;
+        if (typeof a.path === 'string' && a.path) {
+            lines.push(`- ${a.path}${typeof a.caption === 'string' && a.caption ? ` (${a.caption})` : ''}`);
+        }
+        else if (typeof a.data === 'string' && a.data) {
+            const kind = typeof a.media_type === 'string' && a.media_type ? a.media_type : 'image';
+            lines.push(`- inline ${kind} image${typeof a.caption === 'string' && a.caption ? ` (${a.caption})` : ''}`);
+        }
+    }
+    if (lines.length === 0)
+        return '';
+    return ('ATTACHED VISUAL CONTEXT (mandatory): the following image attachment(s) were provided ' +
+        'with this review — each one is part of the evidence you must weigh:\n' +
+        lines.join('\n') +
+        '\nYou MUST inspect/consider EVERY attachment before judging your dimension (open it ' +
+        'with a vision-capable tool, or use image_to_text if your model cannot see images). ' +
+        'If an attachment is inaccessible, state that and judge solely on the code. Do not ' +
+        'ignore an attachment just because it is not code.');
+}
 /**
  * Build the task prompt for one dimension's reviewer subagent.
  * In dry-run mode, pass `alreadyKnown` (the findings from earlier rounds) so the
@@ -475,6 +509,10 @@ export function reviewerTaskPrompt(input) {
     if (input.focus) {
         parts.push(`FOCUS: ${input.focus}`);
     }
+    const attached = attachmentClause(input.attachments);
+    if (attached) {
+        parts.push(attached);
+    }
     if (input.scopeFiles && input.scopeFiles.length > 0) {
         parts.push('COVERAGE RULE (mandatory): below is the exact file inventory you are ' +
             'assigned to review. You MUST open EVERY file in this inventory with ' +
@@ -528,6 +566,13 @@ export function buildReviewPlan(input) {
     const dimensions = Array.isArray(input.config.dimensions) ? input.config.dimensions : [];
     const maxLines = input.config.atomic?.max_lines ?? 20;
     const changedFiles = Array.isArray(input.changedFiles) ? input.changedFiles : [];
+    // Defensive parse: keep only well-formed attachment entries (path or data).
+    const attachments = Array.isArray(input.attachments)
+        ? input.attachments.filter((a) => Boolean(a) &&
+            typeof a === 'object' &&
+            ((typeof a.path === 'string' && a.path.length > 0) ||
+                (typeof a.data === 'string' && a.data.length > 0)))
+        : [];
     // changed-only with zero detected changes → auto-fallback to full scope.
     const effectiveChangedOnly = configuredScope === 'changed-only' && changedFiles.length > 0;
     const scope = effectiveChangedOnly ? 'changed-only' : 'full';
@@ -575,6 +620,7 @@ export function buildReviewPlan(input) {
                     changedFiles: effectiveChangedOnly ? changedFiles : undefined,
                     scopeFiles: batch,
                     focus: focusMap.get(d),
+                    attachments,
                 }),
                 findingsSchema: findingsSchema(),
             });
@@ -589,5 +635,6 @@ export function buildReviewPlan(input) {
         knownIntentional: input.knownIntentional ?? [],
         changedFiles: effectiveChangedOnly ? changedFiles : [],
         fallbackToFull,
+        attachments,
     };
 }

package/dist/tools/fix.js

@@ -20,6 +20,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeF
 import { join, sep } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { loadEffectiveConfig, resolveProjectRootForExec } from "../config-loader.js";
+import { runWithJob } from "../jobs.js";
 import { countTouchedMethods } from "../method-scope.js";
 import { fixBackupPath, fixRegistryPath, fixesDir } from "../paths.js";
 import { appendDecisionEntry } from "./decision-log.js";
@@ -331,170 +332,173 @@ export function registerFixTool(ctx) {
             ],
         },
         async execute(args, exec) {
-            const resolved = resolveProjectRootForExec(exec, args.path);
-            if (!resolved.ok)
-                return { ok: false, error: resolved.reason };
-            const projectRoot = resolved.root;
-            const { config } = loadEffectiveConfig(projectRoot);
-            const maxLines = config.atomic?.max_lines ?? 20;
-            const maxAdjacentMethods = config.atomic?.max_adjacent_methods ?? 3;
-            const file = typeof args.file === 'string' ? args.file : '';
-            if (!file)
-                return { ok: false, error: 'file is required' };
-            if (typeof args.content !== 'string')
-                return { ok: false, error: 'content must be a string' };
-            if (args.content.length > MAX_FIX_CONTENT_CHARS) {
-                return {
-                    ok: false,
-                    error: `content exceeds the ${MAX_FIX_CONTENT_CHARS}-character limit (got ${args.content.length})`,
-                };
-            }
-            if (typeof args.round !== 'number' || !Number.isInteger(args.round) || args.round < 1) {
-                return { ok: false, error: 'round must be a positive integer' };
-            }
-            const finding = args.finding;
-            if (!finding || typeof finding !== 'object') {
-                return { ok: false, error: 'finding must be an object' };
-            }
-            if (typeof finding.file !== 'string' || finding.file.trim().length === 0) {
-                return { ok: false, error: 'finding.file must be a non-empty string' };
-            }
-            if (typeof finding.dimension !== 'string' || finding.dimension.trim().length === 0) {
-                return { ok: false, error: 'finding.dimension must be a non-empty string' };
-            }
-            // The finding must reference the file being fixed — the fix id and the
-            // rollback/diff target are derived from finding.file, so a mismatch
-            // would back up/restore the WRONG file.
-            if (finding.file !== file) {
-                return { ok: false, error: `finding.file ("${finding.file}") must match the file being fixed ("${file}")` };
-            }
-            // Full finding validation, mirroring the review schema: malformed
-            // findings would produce lossy registry/log entries and a degraded id.
-            const SEVERITY_SET = new Set(['critical', 'high', 'medium', 'low']);
-            if (!SEVERITY_SET.has(finding.severity)) {
-                return { ok: false, error: 'finding.severity must be one of critical/high/medium/low' };
-            }
-            if (typeof finding.summary !== 'string' || finding.summary.trim().length === 0) {
-                return { ok: false, error: 'finding.summary must be a non-empty string' };
-            }
-            if (typeof finding.is_atomic !== 'boolean') {
-                return { ok: false, error: 'finding.is_atomic must be a boolean' };
-            }
-            if (finding.line !== undefined && finding.line !== null &&
-                (typeof finding.line !== 'number' || !Number.isInteger(finding.line) || finding.line < 0)) {
-                return { ok: false, error: 'finding.line must be a non-negative integer (0 = whole-file)' };
-            }
-            const current = readProjectFile(projectRoot, file);
-            if (!current.ok)
-                return { ok: false, error: current.reason };
-            const hunks = diffLines(current.content, args.content);
-            const { added, removed } = countChangedLines(current.content, args.content);
-            if (!args.force && (added > maxLines || removed > maxLines)) {
-                return {
-                    ok: false,
-                    error: `Change to ${file} exceeds the atomic threshold (max_lines=${maxLines}, change is +${added}/-${removed}). ` +
-                        'Either split it into smaller atomic fixes or pass force:true if this is a deliberate architectural change.',
-                };
-            }
-            const touchedMethods = countTouchedMethods(current.content, args.content, hunks);
-            if (!args.force && touchedMethods > maxAdjacentMethods) {
-                return {
-                    ok: false,
-                    error: `Change to ${file} touches ${touchedMethods} adjacent method(s), exceeds atomic.max_adjacent_methods (${maxAdjacentMethods}). ` +
-                        'Split it into smaller atomic fixes or pass force:true if this is a deliberate multi-method change.',
-                };
-            }
-            const id = fixId(finding);
-            const registry = readRegistry(projectRoot);
-            if (findFixRecord(registry, id)) {
-                return { ok: false, error: `finding already fixed this run (id: ${id})`, id };
-            }
-            const target = resolveProjectFile(projectRoot, file);
-            if (!target.ok)
-                return { ok: false, error: target.reason };
-            // Personalization guards (SKILL.md Phase 2): protected_paths veto the
-            // fix outright; forbidden_fixes veto fix approaches appearing in the
-            // new content. Both are security-relevant, so they are enforced here
-            // in the tool, not left to the model.
-            const pers = config.personalization;
-            const protectedPaths = Array.isArray(pers?.protected_paths)
-                ? pers.protected_paths.filter((p) => typeof p === 'string' && p.length > 0)
-                : [];
-            for (const pattern of protectedPaths) {
-                if (globMatch(file, pattern)) {
-                    return { ok: false, error: `skipped: ${file} matches protected path "${pattern}" (personalization.protected_paths forbids modifying it)` };
+            const { result } = await runWithJob(ctx, 'iterate-fix', `iterate_fix ${typeof args.file === 'string' && args.file ? args.file : '(?)'}`, async () => {
+                const resolved = resolveProjectRootForExec(exec, args.path);
+                if (!resolved.ok)
+                    return { ok: false, error: resolved.reason };
+                const projectRoot = resolved.root;
+                const { config } = loadEffectiveConfig(projectRoot);
+                const maxLines = config.atomic?.max_lines ?? 20;
+                const maxAdjacentMethods = config.atomic?.max_adjacent_methods ?? 3;
+                const file = typeof args.file === 'string' ? args.file : '';
+                if (!file)
+                    return { ok: false, error: 'file is required' };
+                if (typeof args.content !== 'string')
+                    return { ok: false, error: 'content must be a string' };
+                if (args.content.length > MAX_FIX_CONTENT_CHARS) {
+                    return {
+                        ok: false,
+                        error: `content exceeds the ${MAX_FIX_CONTENT_CHARS}-character limit (got ${args.content.length})`,
+                    };
                 }
-            }
-            const forbiddenFixes = Array.isArray(pers?.forbidden_fixes)
-                ? pers.forbidden_fixes.filter((f) => typeof f === 'string' && f.length > 0)
-                : [];
-            for (const forbidden of forbiddenFixes) {
-                if (args.content.includes(forbidden)) {
-                    return { ok: false, error: `fix uses a forbidden approach: "${forbidden}" appears in the new content (personalization.forbidden_fixes)` };
+                if (typeof args.round !== 'number' || !Number.isInteger(args.round) || args.round < 1) {
+                    return { ok: false, error: 'round must be a positive integer' };
                 }
-            }
-            const timestamp = new Date().toISOString();
-            const backupPath = fixBackupPath(projectRoot, id, timestamp);
-            try {
-                mkdirSync(fixesDir(projectRoot), { recursive: true });
-                copyFileSync(target.resolved, backupPath);
-            }
-            catch (err) {
-                return { ok: false, error: `failed to create backup: ${String(err)}` };
-            }
-            try {
-                writeFileSync(target.resolved, args.content, 'utf-8');
-            }
-            catch (err) {
-                return { ok: false, error: `failed to write file: ${String(err)}` };
-            }
-            const record = {
-                id,
-                timestamp,
-                round: args.round,
-                finding,
-                backupPath,
-                diffSummary: buildDiffSummary(hunks),
-                linesAdded: added,
-                linesRemoved: removed,
-                success: true,
-            };
-            const nextRegistry = upsertRecord(registry, record);
-            try {
-                writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(nextRegistry, null, 2), 'utf-8');
-            }
-            catch (err) {
-                // Registry write failed → the file was already modified but no record
-                // exists, so a later rollback/diff could never see it and a retry would
-                // back up the already-fixed content as "original". Restore the file
-                // from the backup to leave the tree exactly as it was.
-                try {
-                    copyFileSync(backupPath, target.resolved);
+                const finding = args.finding;
+                if (!finding || typeof finding !== 'object') {
+                    return { ok: false, error: 'finding must be an object' };
+                }
+                if (typeof finding.file !== 'string' || finding.file.trim().length === 0) {
+                    return { ok: false, error: 'finding.file must be a non-empty string' };
+                }
+                if (typeof finding.dimension !== 'string' || finding.dimension.trim().length === 0) {
+                    return { ok: false, error: 'finding.dimension must be a non-empty string' };
+                }
+                // The finding must reference the file being fixed — the fix id and the
+                // rollback/diff target are derived from finding.file, so a mismatch
+                // would back up/restore the WRONG file.
+                if (finding.file !== file) {
+                    return { ok: false, error: `finding.file ("${finding.file}") must match the file being fixed ("${file}")` };
                 }
-                catch (restoreErr) {
+                // Full finding validation, mirroring the review schema: malformed
+                // findings would produce lossy registry/log entries and a degraded id.
+                const SEVERITY_SET = new Set(['critical', 'high', 'medium', 'low']);
+                if (!SEVERITY_SET.has(finding.severity)) {
+                    return { ok: false, error: 'finding.severity must be one of critical/high/medium/low' };
+                }
+                if (typeof finding.summary !== 'string' || finding.summary.trim().length === 0) {
+                    return { ok: false, error: 'finding.summary must be a non-empty string' };
+                }
+                if (typeof finding.is_atomic !== 'boolean') {
+                    return { ok: false, error: 'finding.is_atomic must be a boolean' };
+                }
+                if (finding.line !== undefined && finding.line !== null &&
+                    (typeof finding.line !== 'number' || !Number.isInteger(finding.line) || finding.line < 0)) {
+                    return { ok: false, error: 'finding.line must be a non-negative integer (0 = whole-file)' };
+                }
+                const current = readProjectFile(projectRoot, file);
+                if (!current.ok)
+                    return { ok: false, error: current.reason };
+                const hunks = diffLines(current.content, args.content);
+                const { added, removed } = countChangedLines(current.content, args.content);
+                if (!args.force && (added > maxLines || removed > maxLines)) {
                     return {
                         ok: false,
-                        error: `failed to write fix registry: ${String(err)}; additionally failed to restore ${file} from backup: ${String(restoreErr)}`,
+                        error: `Change to ${file} exceeds the atomic threshold (max_lines=${maxLines}, change is +${added}/-${removed}). ` +
+                            'Either split it into smaller atomic fixes or pass force:true if this is a deliberate architectural change.',
                     };
                 }
-                return { ok: false, error: `failed to write fix registry: ${String(err)} (file restored from backup)` };
-            }
-            appendDecisionEntry(projectRoot, {
-                timestamp,
-                round: args.round,
-                type: 'atomic_fix',
-                data: { id, file, finding: finding.summary, linesAdded: added, linesRemoved: removed },
+                const touchedMethods = countTouchedMethods(current.content, args.content, hunks);
+                if (!args.force && touchedMethods > maxAdjacentMethods) {
+                    return {
+                        ok: false,
+                        error: `Change to ${file} touches ${touchedMethods} adjacent method(s), exceeds atomic.max_adjacent_methods (${maxAdjacentMethods}). ` +
+                            'Split it into smaller atomic fixes or pass force:true if this is a deliberate multi-method change.',
+                    };
+                }
+                const id = fixId(finding);
+                const registry = readRegistry(projectRoot);
+                if (findFixRecord(registry, id)) {
+                    return { ok: false, error: `finding already fixed this run (id: ${id})`, id };
+                }
+                const target = resolveProjectFile(projectRoot, file);
+                if (!target.ok)
+                    return { ok: false, error: target.reason };
+                // Personalization guards (SKILL.md Phase 2): protected_paths veto the
+                // fix outright; forbidden_fixes veto fix approaches appearing in the
+                // new content. Both are security-relevant, so they are enforced here
+                // in the tool, not left to the model.
+                const pers = config.personalization;
+                const protectedPaths = Array.isArray(pers?.protected_paths)
+                    ? pers.protected_paths.filter((p) => typeof p === 'string' && p.length > 0)
+                    : [];
+                for (const pattern of protectedPaths) {
+                    if (globMatch(file, pattern)) {
+                        return { ok: false, error: `skipped: ${file} matches protected path "${pattern}" (personalization.protected_paths forbids modifying it)` };
+                    }
+                }
+                const forbiddenFixes = Array.isArray(pers?.forbidden_fixes)
+                    ? pers.forbidden_fixes.filter((f) => typeof f === 'string' && f.length > 0)
+                    : [];
+                for (const forbidden of forbiddenFixes) {
+                    if (args.content.includes(forbidden)) {
+                        return { ok: false, error: `fix uses a forbidden approach: "${forbidden}" appears in the new content (personalization.forbidden_fixes)` };
+                    }
+                }
+                const timestamp = new Date().toISOString();
+                const backupPath = fixBackupPath(projectRoot, id, timestamp);
+                try {
+                    mkdirSync(fixesDir(projectRoot), { recursive: true });
+                    copyFileSync(target.resolved, backupPath);
+                }
+                catch (err) {
+                    return { ok: false, error: `failed to create backup: ${String(err)}` };
+                }
+                try {
+                    writeFileSync(target.resolved, args.content, 'utf-8');
+                }
+                catch (err) {
+                    return { ok: false, error: `failed to write file: ${String(err)}` };
+                }
+                const record = {
+                    id,
+                    timestamp,
+                    round: args.round,
+                    finding,
+                    backupPath,
+                    diffSummary: buildDiffSummary(hunks),
+                    linesAdded: added,
+                    linesRemoved: removed,
+                    success: true,
+                };
+                const nextRegistry = upsertRecord(registry, record);
+                try {
+                    writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(nextRegistry, null, 2), 'utf-8');
+                }
+                catch (err) {
+                    // Registry write failed → the file was already modified but no record
+                    // exists, so a later rollback/diff could never see it and a retry would
+                    // back up the already-fixed content as "original". Restore the file
+                    // from the backup to leave the tree exactly as it was.
+                    try {
+                        copyFileSync(backupPath, target.resolved);
+                    }
+                    catch (restoreErr) {
+                        return {
+                            ok: false,
+                            error: `failed to write fix registry: ${String(err)}; additionally failed to restore ${file} from backup: ${String(restoreErr)}`,
+                        };
+                    }
+                    return { ok: false, error: `failed to write fix registry: ${String(err)} (file restored from backup)` };
+                }
+                appendDecisionEntry(projectRoot, {
+                    timestamp,
+                    round: args.round,
+                    type: 'atomic_fix',
+                    data: { id, file, finding: finding.summary, linesAdded: added, linesRemoved: removed },
+                });
+                return {
+                    ok: true,
+                    id,
+                    file,
+                    round: args.round,
+                    linesAdded: added,
+                    linesRemoved: removed,
+                    diffSummary: record.diffSummary,
+                    backupPath,
+                };
             });
-            return {
-                ok: true,
-                id,
-                file,
-                round: args.round,
-                linesAdded: added,
-                linesRemoved: removed,
-                diffSummary: record.diffSummary,
-                backupPath,
-            };
+            return result;
         },
     }));
 }