iterate-plugin 2.12.1 → 2.12.2

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;
         },
     }));
 }

package/dist/tools/review.js

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { loadEffectiveConfig, resolveProjectRootForExec } from "../config-loader.js";
+import { runWithJob } from "../jobs.js";
 import { buildReviewPlan, buildReviewReport, sanitizeRounds, validateRoundsSchema, } from "../review.js";
 import { buildFinalReviewReport, metaReviewReport } from "../meta-review.js";
 import { evidenceToPlain, verifyFindings } from "../evidence.js";
@@ -65,6 +66,15 @@ export function registerReviewTool(ctx) {
                 description: 'For `meta-review`: the ReviewReport JSON (as returned by `aggregate`) to audit for ' +
                     'internal consistency and produce the final review report.',
             },
+            attachments: {
+                type: 'json',
+                description: 'Optional (plan only): image/visual attachments to thread into the review, e.g. ' +
+                    '[{"path":"screens/hits.png","caption":"reproduced layout bug"}]. Each entry: ' +
+                    '{path?, data?, media_type?, caption?} — path resolves relative to the project root, ' +
+                    'data is a base64 payload (media_type e.g. image/png), caption gives human context. ' +
+                    'Injected as a mandatory clause into every dimension reviewer prompt so screenshots/' +
+                    'mockups/failure repros are weighed alongside the code.',
+            },
             fixedCount: {
                 type: 'integer',
                 description: 'For `aggregate` (normal mode only): number of atomic fixes applied so far. ' +
@@ -107,134 +117,145 @@ export function registerReviewTool(ctx) {
             ],
         },
         async execute(args, exec) {
-            const resolved = resolveProjectRootForExec(exec, args.path);
-            if (!resolved.ok) {
-                return { operation: args.operation, error: resolved.reason };
-            }
-            const projectRoot = resolved.root;
-            // Effective config = defaults merged with project overrides. Never
-            // null, so `plan`/`aggregate` work even without a config file.
-            const { config } = loadEffectiveConfig(projectRoot);
-            const mode = args.mode ?? 'dry-run';
-            if (args.operation === 'plan') {
-                const maxReviewRounds = args.maxReviewRounds ?? config.max_rounds ?? DEFAULT_MAX_REVIEW_ROUNDS;
-                const knownIntentional = config.personalization
-                    ?.known_intentional;
-                // changed-only scope: resolve the changed-file set against
-                // git.target_branch before building the plan so reviewers get the
-                // concrete file list (and the plan auto-falls back to full when there
-                // are no changes). git failures degrade to a full-scope plan.
-                let changedFiles;
-                if (config.review?.scope === 'changed-only') {
-                    const gitScope = await resolveChangedFiles(projectRoot, config.git?.target_branch ?? 'main');
-                    changedFiles = gitScope.changedFiles;
+            const { result } = await runWithJob(ctx, 'iterate-review', `iterate_review ${String(args.operation ?? '')} (${String(args.mode ?? 'dry-run')})`, async () => {
+                const resolved = resolveProjectRootForExec(exec, args.path);
+                if (!resolved.ok) {
+                    return { operation: args.operation, error: resolved.reason };
                 }
-                // Full-codebase review: pre-collect the source inventory so
-                // buildReviewPlan can batch it into per-chunk reviewer tasks
-                // (coverage enforcement).
-                let scopeFiles;
-                if (config.review?.scope === 'full') {
-                    scopeFiles = collectScopeFiles(projectRoot, { scope: 'full' });
-                }
-                const plan = buildReviewPlan({ config, mode, maxReviewRounds, knownIntentional, changedFiles, scopeFiles });
-                return { operation: 'plan', mode, found: true, plan: plan };
-            }
-            if (args.operation === 'aggregate') {
-                const rawRounds = Array.isArray(args.rounds) ? args.rounds : [];
-                const rounds = rawRounds
-                    .map((r) => {
-                    const rr = r;
-                    const findings = Array.isArray(rr?.findings) ? rr.findings : [];
-                    const readFiles = Array.isArray(rr?.readFiles)
-                        ? rr.readFiles.filter((f) => typeof f === 'string')
+                const projectRoot = resolved.root;
+                // Effective config = defaults merged with project overrides. Never
+                // null, so `plan`/`aggregate` work even without a config file.
+                const { config } = loadEffectiveConfig(projectRoot);
+                const mode = args.mode ?? 'dry-run';
+                if (args.operation === 'plan') {
+                    const maxReviewRounds = args.maxReviewRounds ?? config.max_rounds ?? DEFAULT_MAX_REVIEW_ROUNDS;
+                    const knownIntentional = config.personalization
+                        ?.known_intentional;
+                    // changed-only scope: resolve the changed-file set against
+                    // git.target_branch before building the plan so reviewers get the
+                    // concrete file list (and the plan auto-falls back to full when there
+                    // are no changes). git failures degrade to a full-scope plan.
+                    let changedFiles;
+                    if (config.review?.scope === 'changed-only') {
+                        const gitScope = await resolveChangedFiles(projectRoot, config.git?.target_branch ?? 'main');
+                        changedFiles = gitScope.changedFiles;
+                    }
+                    // Full-codebase review: pre-collect the source inventory so
+                    // buildReviewPlan can batch it into per-chunk reviewer tasks
+                    // (coverage enforcement).
+                    let scopeFiles;
+                    if (config.review?.scope === 'full') {
+                        scopeFiles = collectScopeFiles(projectRoot, { scope: 'full' });
+                    }
+                    // Thread image/visual attachments (screenshots/mockups/failure repros)
+                    // into the plan so every reviewer prompt weighs them alongside code.
+                    const attachments = Array.isArray(args.attachments)
+                        ? args.attachments.filter((a) => Boolean(a) &&
+                            typeof a === 'object' &&
+                            ((typeof a.path === 'string' && a.path.length > 0) ||
+                                (typeof a.data === 'string' && a.data.length > 0)))
                         : [];
-                    return { round: typeof rr?.round === 'number' ? rr.round : 0, findings, readFiles };
-                })
-                    .filter((r) => r.round > 0);
-                if (rounds.length === 0) {
+                    const plan = buildReviewPlan({ config, mode, maxReviewRounds, knownIntentional, changedFiles, scopeFiles, attachments });
+                    return { operation: 'plan', mode, found: true, plan: plan };
+                }
+                if (args.operation === 'aggregate') {
+                    const rawRounds = Array.isArray(args.rounds) ? args.rounds : [];
+                    const rounds = rawRounds
+                        .map((r) => {
+                        const rr = r;
+                        const findings = Array.isArray(rr?.findings) ? rr.findings : [];
+                        const readFiles = Array.isArray(rr?.readFiles)
+                            ? rr.readFiles.filter((f) => typeof f === 'string')
+                            : [];
+                        return { round: typeof rr?.round === 'number' ? rr.round : 0, findings, readFiles };
+                    })
+                        .filter((r) => r.round > 0);
+                    if (rounds.length === 0) {
+                        return {
+                            operation: 'aggregate',
+                            mode,
+                            error: 'rounds must be a non-empty array of {round, findings}.',
+                        };
+                    }
+                    const maxReviewRounds = args.maxReviewRounds ?? config.max_rounds ?? DEFAULT_MAX_REVIEW_ROUNDS;
+                    const goal = args.goal ?? config.goal ?? '';
+                    const dimensions = config.dimensions ?? [];
+                    // Output schema validation gate (reviewer.output_schema_validation,
+                    // default true): validate every round's findings against the findings
+                    // schema, then drop schema-invalid entries before the deterministic
+                    // core so malformed reviewer output can never crash dedupe/sort or
+                    // leak into fixes. The `schemaValidation` array is surfaced so the
+                    // workflow can retry failing rounds (≤2 times) with a strict-JSON
+                    // nudge. When disabled, non-object entries are still dropped for
+                    // crash-safety.
+                    const schemaEnabled = config.reviewer?.output_schema_validation !== false;
+                    const schemaValidation = schemaEnabled ? validateRoundsSchema(rounds) : null;
+                    const cleanRounds = sanitizeRounds(rounds, schemaValidation);
+                    const report = buildReviewReport({
+                        mode,
+                        goal,
+                        dimensions,
+                        maxReviewRounds,
+                        rounds: cleanRounds,
+                        knownIntentional: args.knownIntentional,
+                        fixedCount: typeof args.fixedCount === 'number' ? args.fixedCount : undefined,
+                    });
                     return {
                         operation: 'aggregate',
                         mode,
-                        error: 'rounds must be a non-empty array of {round, findings}.',
+                        report: report,
+                        schemaValidation: (schemaValidation ?? null),
                     };
                 }
-                const maxReviewRounds = args.maxReviewRounds ?? config.max_rounds ?? DEFAULT_MAX_REVIEW_ROUNDS;
-                const goal = args.goal ?? config.goal ?? '';
-                const dimensions = config.dimensions ?? [];
-                // Output schema validation gate (reviewer.output_schema_validation,
-                // default true): validate every round's findings against the findings
-                // schema, then drop schema-invalid entries before the deterministic
-                // core so malformed reviewer output can never crash dedupe/sort or
-                // leak into fixes. The `schemaValidation` array is surfaced so the
-                // workflow can retry failing rounds (≤2 times) with a strict-JSON
-                // nudge. When disabled, non-object entries are still dropped for
-                // crash-safety.
-                const schemaEnabled = config.reviewer?.output_schema_validation !== false;
-                const schemaValidation = schemaEnabled ? validateRoundsSchema(rounds) : null;
-                const cleanRounds = sanitizeRounds(rounds, schemaValidation);
-                const report = buildReviewReport({
-                    mode,
-                    goal,
-                    dimensions,
-                    maxReviewRounds,
-                    rounds: cleanRounds,
-                    knownIntentional: args.knownIntentional,
-                    fixedCount: typeof args.fixedCount === 'number' ? args.fixedCount : undefined,
-                });
-                return {
-                    operation: 'aggregate',
-                    mode,
-                    report: report,
-                    schemaValidation: (schemaValidation ?? null),
-                };
-            }
-            if (args.operation === 'meta-review') {
-                const source = args.report;
-                if (!source || typeof source !== 'object') {
+                if (args.operation === 'meta-review') {
+                    const source = args.report;
+                    if (!source || typeof source !== 'object') {
+                        return {
+                            operation: 'meta-review',
+                            mode,
+                            error: 'report must be a ReviewReport JSON object (as returned by `aggregate`).',
+                        };
+                    }
+                    const audit = metaReviewReport(source);
+                    // Hard code-evidence gate (default on): every finding's file/line is
+                    // validated against real files on disk before folding into the final
+                    // verdict. Disable via config `reviewer.evidence_validation: false`.
+                    const evidenceEnabled = config.reviewer?.evidence_validation !== false;
+                    const findings = Array.isArray(source.findings) ? source.findings : [];
+                    const evidence = evidenceEnabled ? verifyFindings(projectRoot, findings) : null;
+                    // Prompt-informative coverage: compare the reviewer's self-reported
+                    // reads against the assigned scope inventory (never flips the
+                    // verdict). Disable via config `reviewer.coverage_validation: false`.
+                    const coverageEnabled = config.reviewer?.coverage_validation !== false;
+                    let coverage = null;
+                    if (coverageEnabled) {
+                        const assigned = collectScopeFiles(projectRoot, {
+                            scope: config.review?.scope === 'changed-only' ? 'changed-only' : 'full',
+                        });
+                        const readFiles = Array.isArray(source.readFiles)
+                            ? source.readFiles
+                            : null;
+                        if (readFiles && readFiles.length > 0) {
+                            coverage = computeCoverage(assigned, readFiles);
+                        }
+                    }
+                    const finalReport = buildFinalReviewReport(source, { evidence, coverage });
                     return {
                         operation: 'meta-review',
                         mode,
-                        error: 'report must be a ReviewReport JSON object (as returned by `aggregate`).',
+                        found: true,
+                        report: audit,
+                        evidence: evidence ? evidenceToPlain(evidence) : null,
+                        coverage: coverage ? coverageToDict(coverage) : null,
+                        finalReport: finalReport,
                     };
                 }
-                const audit = metaReviewReport(source);
-                // Hard code-evidence gate (default on): every finding's file/line is
-                // validated against real files on disk before folding into the final
-                // verdict. Disable via config `reviewer.evidence_validation: false`.
-                const evidenceEnabled = config.reviewer?.evidence_validation !== false;
-                const findings = Array.isArray(source.findings) ? source.findings : [];
-                const evidence = evidenceEnabled ? verifyFindings(projectRoot, findings) : null;
-                // Prompt-informative coverage: compare the reviewer's self-reported
-                // reads against the assigned scope inventory (never flips the
-                // verdict). Disable via config `reviewer.coverage_validation: false`.
-                const coverageEnabled = config.reviewer?.coverage_validation !== false;
-                let coverage = null;
-                if (coverageEnabled) {
-                    const assigned = collectScopeFiles(projectRoot, {
-                        scope: config.review?.scope === 'changed-only' ? 'changed-only' : 'full',
-                    });
-                    const readFiles = Array.isArray(source.readFiles)
-                        ? source.readFiles
-                        : null;
-                    if (readFiles && readFiles.length > 0) {
-                        coverage = computeCoverage(assigned, readFiles);
-                    }
-                }
-                const finalReport = buildFinalReviewReport(source, { evidence, coverage });
                 return {
-                    operation: 'meta-review',
-                    mode,
-                    found: true,
-                    report: audit,
-                    evidence: evidence ? evidenceToPlain(evidence) : null,
-                    coverage: coverage ? coverageToDict(coverage) : null,
-                    finalReport: finalReport,
+                    operation: args.operation,
+                    error: `Unknown operation "${args.operation}". Use "plan", "aggregate", or "meta-review".`,
                 };
-            }
-            return {
-                operation: args.operation,
-                error: `Unknown operation "${args.operation}". Use "plan", "aggregate", or "meta-review".`,
-            };
+            });
+            return result;
         },
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "2.12.1",
+  "version": "2.12.2",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus a dry-run pure-review mode with multi-round convergence and a meta-review that audits the report and emits a final review report.",
   "type": "module",
   "license": "MIT",
@@ -61,11 +61,12 @@
   },
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.1",
-    "@deepseek-ai/dsh-tools": "0.1.1-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.1-rc.2",
     "js-yaml": "4.3.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-session": "0.1.1-rc.1",
+    "@deepseek-ai/dsh-jobs": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.1-rc.2",
     "@types/js-yaml": "4.0.9",
     "@types/node": "22.15.0",
     "@types/react": "19.2.2",

package/src/jobs.ts

@@ -0,0 +1,97 @@
+/**
+ * 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.
+ */
+
+import type { JobOutcome, JobRegistry } from '@deepseek-ai/dsh-jobs'
+
+/** Extend dsh's producer-kind registry with iterate's custom kinds. */
+declare module '@deepseek-ai/dsh-jobs' {
+  interface JobKindMap {
+    'iterate-review': 'iterate-review'
+    'iterate-fix': 'iterate-fix'
+  }
+}
+
+/** Custom job kinds this plugin registers. */
+export type IterateJobKind = 'iterate-review' | 'iterate-fix'
+
+/** Shape of the `ctx.jobs` surface we rely on (duck-typed for safety). */
+interface JobsLike {
+  start(spec: {
+    kind: IterateJobKind
+    label: string
+    run(): { done: Promise<JobOutcome>; cancel?: () => void }
+  }): string
+}
+
+/**
+ * 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<T>(
+  ctx: unknown,
+  kind: IterateJobKind,
+  label: string,
+  fn: () => Promise<T> | T,
+): Promise<{ result: T; jobId: string | null }> {
+  const jobs = (ctx as { jobs?: JobsLike } | undefined)?.jobs
+  if (!jobs || typeof jobs.start !== 'function') {
+    return { result: await fn(), jobId: null }
+  }
+
+  let settle!: (outcome: JobOutcome) => void
+  const done = new Promise<JobOutcome>((resolve) => {
+    settle = resolve
+  })
+
+  let jobId: string | null = 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/src/review.ts

@@ -20,6 +20,7 @@
 import type {
   IterateConfig,
   KnownIntentional,
+  ReviewAttachment,
   ReviewFinding,
   ReviewReport,
   ReviewRound,
@@ -546,6 +547,39 @@ export function sanitizeRounds(
   })
 }
 
+/**
+ * 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: ReviewAttachment[] | undefined): string {
+  if (!attachments || attachments.length === 0) return ''
+  const lines: string[] = []
+  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
@@ -581,6 +615,12 @@ export function reviewerTaskPrompt(input: {
    * review concentrates on the areas the user cares about.
    */
   focus?: string
+  /**
+   * Image/visual attachments to weigh alongside the code (screenshots,
+   * mockups, failure repros). Injected as a mandatory review-aware clause so
+   * every dimension reviewer inspects/considers them before judging.
+   */
+  attachments?: ReviewAttachment[]
 }): string {
   const parts: string[] = []
   parts.push(
@@ -591,6 +631,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 ' +
@@ -672,6 +716,12 @@ export function buildReviewPlan(input: {
    * complete inventory it must open file-by-file.
    */
   scopeFiles?: string[]
+  /**
+   * Image/visual attachments to thread into the review. Injected as a
+   * mandatory clause into every dimension's reviewer prompt and surfaced on
+   * the returned plan so the orchestrator/report can reference them.
+   */
+  attachments?: ReviewAttachment[]
 }): {
   mode: 'normal' | 'dry-run'
   goal: string
@@ -683,6 +733,8 @@ export function buildReviewPlan(input: {
   changedFiles: string[]
   /** True when scope was `changed-only` but no changes were found. */
   fallbackToFull: boolean
+  /** The attachments threaded into every reviewer prompt (empty when none). */
+  attachments: ReviewAttachment[]
 } {
   // Defensive reads: a malformed config (e.g. `dimensions` as a non-array, or
   // `review`/`atomic` missing) must degrade to sane defaults instead of
@@ -693,6 +745,16 @@ 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): a is ReviewAttachment =>
+          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: 'full' | 'changed-only' = effectiveChangedOnly ? 'changed-only' : 'full'
@@ -744,6 +806,7 @@ export function buildReviewPlan(input: {
           changedFiles: effectiveChangedOnly ? changedFiles : undefined,
           scopeFiles: batch,
           focus: focusMap.get(d),
+          attachments,
         }),
         findingsSchema: findingsSchema(),
       })
@@ -759,5 +822,6 @@ export function buildReviewPlan(input: {
     knownIntentional: input.knownIntentional ?? [],
     changedFiles: effectiveChangedOnly ? changedFiles : [],
     fallbackToFull,
+    attachments,
   }
 }

package/src/tools/fix.ts

@@ -22,6 +22,7 @@ import { join, sep } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { loadEffectiveConfig, resolveProjectRootForExec } from '../config-loader.ts'
+import { runWithJob } from '../jobs.ts'
 import { countTouchedMethods } from '../method-scope.ts'
 import { fixBackupPath, fixRegistryPath, fixesDir } from '../paths.ts'
 import { appendDecisionEntry } from './decision-log.ts'
@@ -335,6 +336,7 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
       },
 
       async execute(args, exec) {
+        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
@@ -504,6 +506,8 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
           diffSummary: record.diffSummary,
           backupPath,
         }
+        })
+        return result
       },
     }),
   )

package/src/tools/review.ts

@@ -1,6 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { loadEffectiveConfig, resolveProjectRootForExec } from '../config-loader.ts'
+import { runWithJob } from '../jobs.ts'
 import {
   buildReviewPlan,
   buildReviewReport,
@@ -15,7 +16,7 @@ import {
   coverageToDict,
 } from '../review-scope.ts'
 import { resolveChangedFiles } from '../git-scope.ts'
-import type { KnownIntentional, ReviewFinding, ReviewReport, ReviewRound } from '../types.ts'
+import type { KnownIntentional, ReviewAttachment, ReviewFinding, ReviewReport, ReviewRound } from '../types.ts'
 import type { CoverageResult } from '../review-scope.ts'
 
 /** Default round cap when neither the arg nor config provides one. */
@@ -85,6 +86,16 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
             'For `meta-review`: the ReviewReport JSON (as returned by `aggregate`) to audit for ' +
             'internal consistency and produce the final review report.',
         },
+        attachments: {
+          type: 'json',
+          description:
+            'Optional (plan only): image/visual attachments to thread into the review, e.g. ' +
+            '[{"path":"screens/hits.png","caption":"reproduced layout bug"}]. Each entry: ' +
+            '{path?, data?, media_type?, caption?} — path resolves relative to the project root, ' +
+            'data is a base64 payload (media_type e.g. image/png), caption gives human context. ' +
+            'Injected as a mandatory clause into every dimension reviewer prompt so screenshots/' +
+            'mockups/failure repros are weighed alongside the code.',
+        },
         fixedCount: {
           type: 'integer',
           description:
@@ -132,6 +143,7 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
       },
 
       async execute(args, exec) {
+        const { result } = await runWithJob(ctx, 'iterate-review', `iterate_review ${String(args.operation ?? '')} (${String(args.mode ?? 'dry-run')})`, async () => {
         const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) {
           return { operation: args.operation, error: resolved.reason }
@@ -162,7 +174,18 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
           if (config.review?.scope === 'full') {
             scopeFiles = collectScopeFiles(projectRoot, { scope: 'full' })
           }
-          const plan = buildReviewPlan({ config, mode, maxReviewRounds, knownIntentional, changedFiles, scopeFiles })
+          // Thread image/visual attachments (screenshots/mockups/failure repros)
+          // into the plan so every reviewer prompt weighs them alongside code.
+          const attachments = Array.isArray(args.attachments)
+            ? (args.attachments as ReviewAttachment[]).filter(
+                (a): a is ReviewAttachment =>
+                  Boolean(a) &&
+                  typeof a === 'object' &&
+                  ((typeof a.path === 'string' && a.path.length > 0) ||
+                    (typeof a.data === 'string' && a.data.length > 0)),
+              )
+            : []
+          const plan = buildReviewPlan({ config, mode, maxReviewRounds, knownIntentional, changedFiles, scopeFiles, attachments })
           return { operation: 'plan', mode, found: true, plan: plan as unknown as JsonValue }
         }
 
@@ -268,6 +291,8 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
           operation: args.operation,
           error: `Unknown operation "${args.operation}". Use "plan", "aggregate", or "meta-review".`,
         }
+        })
+        return result
       },
     }),
   )

package/src/types.ts

@@ -16,6 +16,13 @@ export interface IterateConfig {
     command_whitelist: string[]
     commands: Record<string, string[]>
   }
+  /**
+   * LLM reasoning effort for review passes ('low' | 'medium' | 'high').
+   * Absent → follow the provider default. The harness forwards it into the
+   * OpenAI-compatible request body; the plugin surfaces it in the settings
+   * panel and review plan (dsh 0.1.1-rc.7+ exposes the same 'low' effort).
+   */
+  reasoning_effort?: 'low' | 'medium' | 'high'
   reviewer: {
     output_schema_validation: boolean
     evidence_validation: boolean
@@ -70,6 +77,25 @@ export interface ValidationResult {
   durationMs: number
 }
 
+/**
+ * An image (or other visual) attachment threaded into a review.
+ *
+ * The user/context can attach screenshots, UI mockups, or reproduced-failure
+ * images that reviewers should weigh alongside the code. Only ``path`` or
+ * ``data`` need be present; ``media_type`` describes ``data`` (base64);
+ * ``caption`` supplies human context for the reviewer prompt.
+ */
+export interface ReviewAttachment {
+  /** Local path to the image (resolved relative to the project root). */
+  path?: string
+  /** Base64-encoded image content (alternative to ``path``). */
+  data?: string
+  /** MIME type of ``data`` (e.g. image/png, image/jpeg, image/webp). */
+  media_type?: string
+  /** Short human caption explaining what the attachment shows and why it matters. */
+  caption?: string
+}
+
 /** A single finding from a dimension review */
 export interface ReviewFinding {
   dimension: string