iterate-plugin 2.12.0 → 2.12.2

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/lib/client.js

@@ -1629,6 +1629,11 @@ function TriagePanel(props) {
       const t = ev.target;
       if (t && (t.tagName === "INPUT" || t.tagName === "TEXTAREA" || t.tagName === "SELECT")) return;
       if (t && typeof t.isContentEditable === "boolean" && t.isContentEditable) return;
+      const rootEl = doc.querySelector('[data-iterate="triage"]');
+      if (!rootEl) return;
+      const activeEl = doc.activeElement;
+      if (!activeEl) return;
+      if (activeEl !== rootEl && !(typeof rootEl.contains === "function" && rootEl.contains(activeEl))) return;
       const verdict = keyToVerdict(ev.key);
       if (verdict && selected !== null && indices.includes(selected)) {
         ev.preventDefault();
@@ -2146,6 +2151,7 @@ function ObservatoryPanel(props) {
   const [tab, setTab] = React.useState("live");
   const [expandedThreads, setExpandedThreads] = React.useState(/* @__PURE__ */ new Set());
   const [copiedKey, setCopiedKey] = React.useState(null);
+  const [copyFailText, setCopyFailText] = React.useState(null);
   const [nudgeText, setNudgeText] = React.useState("");
   const [timelineType, setTimelineType] = React.useState("");
   const [timelineSearch, setTimelineSearch] = React.useState("");
@@ -2156,7 +2162,10 @@ function ObservatoryPanel(props) {
   const copyInstruction = (key, text) => {
     if (!text) return;
     copyText(text).then((ok) => {
-      if (!ok) return;
+      if (!ok) {
+        setCopyFailText(text);
+        return;
+      }
       setCopiedKey(key);
       if (copyTimer.current) clearTimeout(copyTimer.current);
       copyTimer.current = setTimeout(() => setCopiedKey((cur) => cur === key ? null : cur), 1600);
@@ -2446,6 +2455,11 @@ ${JSON.stringify({
 
 \`\`\`json
 ${JSON.stringify({ operation: "nudge", text: nudgeText }, null, 2)}
+\`\`\``;
+    const activeClearInstruction = `\u8BF7\u8C03\u7528 \`iterate_transcript\` \u6E05\u9664\u5F53\u524D nudge\uFF1A
+
+\`\`\`json
+${JSON.stringify({ operation: "nudge", text: null }, null, 2)}
 \`\`\``;
     return React.createElement(
       "div",
@@ -2465,7 +2479,12 @@ ${JSON.stringify({ operation: "nudge", text: nudgeText }, null, 2)}
           { className: "iterate-obs-bar", style: { marginBottom: 6 } },
           React.createElement("b", {}, "\u5F53\u524D nudge"),
           React.createElement("span", { className: "iterate-obs-msg" }, activeNudgeText),
-          React.createElement("button", { className: "iterate-btn", onClick: () => setNudgeText("") }, "\u6E05\u9664")
+          React.createElement("button", {
+            className: "iterate-btn",
+            "data-copied": copiedKey === "nudge-clear" ? "" : void 0,
+            onClick: () => copyInstruction("nudge-clear", activeClearInstruction),
+            title: "\u590D\u5236\u6E05\u9664 nudge \u6307\u4EE4\uFF08\u5199 text:null\uFF09\uFF0C\u5728\u8FD0\u884C\u63A7\u5236\u53F0\u63D0\u793A\u6E05\u9664\u5DF2\u6301\u4E45\u5316\u7684 nudge"
+          }, copiedKey === "nudge-clear" ? "\u5DF2\u590D\u5236\u6E05\u9664\u6307\u4EE4" : "\u590D\u5236\u6E05\u9664\u6307\u4EE4")
         ) : null,
         React.createElement("textarea", {
           className: "iterate-obs-input iterate-obs-mono",
@@ -2559,6 +2578,21 @@ ${JSON.stringify({ operation: "nudge", text: nudgeText }, null, 2)}
   const renderLive = () => {
     const liveEntries = manifest.live || [];
     if (liveEntries.length === 0) {
+      const hasThreads = (manifest.rounds || []).length > 0;
+      const hasFindings = (manifest.findings || []).length > 0;
+      if (hasThreads || hasFindings) {
+        return React.createElement(
+          "div",
+          { className: "iterate-obs-empty" },
+          React.createElement("div", {}, "\u5B9E\u65F6\u6D3B\u52A8\u6D41\u4EC5\u5728\u8FD0\u884C\u671F\u95F4\u8BB0\u5F55\uFF0C\u5F53\u524D\u5DF2\u5B8C\u6210\u3002"),
+          React.createElement(
+            "div",
+            { className: "iterate-obs-bar", style: { marginTop: 8 } },
+            React.createElement("button", { className: "iterate-btn", onClick: () => setTab("f1") }, "\u67E5\u770B\u5BA1\u67E5\u7EBF\u7A0B"),
+            React.createElement("button", { className: "iterate-btn", onClick: () => setTab("f3") }, "\u67E5\u770B\u53D1\u73B0")
+          )
+        );
+      }
       return React.createElement("div", { className: "iterate-obs-empty" }, "\u6682\u65E0\u5B9E\u65F6\u6D3B\u52A8");
     }
     const rows = liveEntries.map((e, i) => {
@@ -2631,6 +2665,23 @@ ${JSON.stringify({ operation: "nudge", text: nudgeText }, null, 2)}
     open ? React.createElement(
       "div",
       {},
+      copyFailText ? React.createElement(
+        "div",
+        { className: "iterate-obs-block" },
+        React.createElement(
+          "div",
+          { className: "iterate-obs-block-head" },
+          React.createElement("b", {}, "\u590D\u5236\u672A\u6210\u529F"),
+          React.createElement("span", { className: "iterate-obs-head-meta" }, "\u526A\u8D34\u677F\u5199\u5165\u88AB\u62D2\u7EDD\uFF0C\u8BF7\u624B\u52A8\u9009\u4E2D\u4E0B\u65B9\u6307\u4EE4\u590D\u5236"),
+          React.createElement("button", {
+            className: "iterate-btn",
+            "data-ghost": "",
+            "aria-label": "\u5173\u95ED\u590D\u5236\u5931\u8D25\u63D0\u793A",
+            onClick: () => setCopyFailText(null)
+          }, "\u5173\u95ED")
+        ),
+        React.createElement("div", { className: "iterate-obs-code" }, copyFailText)
+      ) : null,
       React.createElement(
         "div",
         { className: "iterate-obs-tabs" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "2.12.0",
+  "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/client/index.ts

@@ -967,6 +967,14 @@ function TriagePanel(props: SlotProps) {
       const t = ev.target as HTMLElement | null
       if (t && (t.tagName === 'INPUT' || t.tagName === 'TEXTAREA' || t.tagName === 'SELECT')) return
       if (t && typeof t.isContentEditable === 'boolean' && t.isContentEditable) return
+      // Only act when focus is INSIDE the triage panel. Everything else keeps
+      // standard behavior (↑/↓ page scroll, typing in the composer), so we do
+      // not hijack document-level keys just because a report is mounted.
+      const rootEl = doc.querySelector('[data-iterate="triage"]')
+      if (!rootEl) return
+      const activeEl = doc.activeElement as HTMLElement | null
+      if (!activeEl) return
+      if (activeEl !== rootEl && !(typeof rootEl.contains === 'function' && rootEl.contains(activeEl))) return
       const verdict = keyToVerdict(ev.key)
       if (verdict && selected !== null && indices.includes(selected)) {
         ev.preventDefault()
@@ -1466,6 +1474,10 @@ function ObservatoryPanel(props: SlotProps) {
   const [tab, setTab] = React.useState('live')
   const [expandedThreads, setExpandedThreads] = React.useState<Set<string>>(new Set())
   const [copiedKey, setCopiedKey] = React.useState<string | null>(null)
+  // When a clipboard write is blocked (permissions/unsupported), reveal the
+  // raw instruction text so the user can copy it manually instead of silently
+  // dropping the action (mirrors the triage/settings fallback).
+  const [copyFailText, setCopyFailText] = React.useState<string | null>(null)
   const [nudgeText, setNudgeText] = React.useState('')
   const [timelineType, setTimelineType] = React.useState('')
   const [timelineSearch, setTimelineSearch] = React.useState('')
@@ -1478,7 +1490,7 @@ function ObservatoryPanel(props: SlotProps) {
   const copyInstruction = (key: string, text: string) => {
     if (!text) return
     copyText(text).then((ok) => {
-      if (!ok) return
+      if (!ok) { setCopyFailText(text); return }
       setCopiedKey(key)
       if (copyTimer.current) clearTimeout(copyTimer.current)
       copyTimer.current = setTimeout(() => setCopiedKey((cur) => (cur === key ? null : cur)), 1600)
@@ -1732,6 +1744,10 @@ function ObservatoryPanel(props: SlotProps) {
     const present = Boolean(nudge && nudge.text)
     const activeNudgeText = nudge && nudge.text ? nudge.text : ''
     const nudgeInstruction = `请调用 \`iterate_transcript\` 写入 nudge 指令：\n\n\`\`\`json\n${JSON.stringify({ operation: 'nudge', text: nudgeText }, null, 2)}\n\`\`\``
+    // Clearing the PERSISTED nudge (as opposed to the draft) requires
+    // text:null. Copied as a paste-able instruction, mirroring the panel's
+    // copy-to-command pattern — it cannot be cleared from the client directly.
+    const activeClearInstruction = `请调用 \`iterate_transcript\` 清除当前 nudge：\n\n\`\`\`json\n${JSON.stringify({ operation: 'nudge', text: null }, null, 2)}\n\`\`\``
     return React.createElement('div', { className: 'iterate-obs-block' },
       React.createElement('div', { className: 'iterate-obs-block-head' },
         React.createElement('span', {}, '运行控制台'),
@@ -1743,7 +1759,11 @@ function ObservatoryPanel(props: SlotProps) {
           ? React.createElement('div', { className: 'iterate-obs-bar', style: { marginBottom: 6 } },
               React.createElement('b', {}, '当前 nudge'),
               React.createElement('span', { className: 'iterate-obs-msg' }, activeNudgeText),
-              React.createElement('button', { className: 'iterate-btn', onClick: () => setNudgeText('') }, '清除'),
+              React.createElement('button', {
+                className: 'iterate-btn', 'data-copied': copiedKey === 'nudge-clear' ? '' : undefined,
+                onClick: () => copyInstruction('nudge-clear', activeClearInstruction),
+                title: '复制清除 nudge 指令（写 text:null），在运行控制台提示清除已持久化的 nudge',
+              }, copiedKey === 'nudge-clear' ? '已复制清除指令' : '复制清除指令'),
             )
           : null,
         React.createElement('textarea', {
@@ -1828,6 +1848,20 @@ function ObservatoryPanel(props: SlotProps) {
   const renderLive = () => {
     const liveEntries = manifest.live || []
     if (liveEntries.length === 0) {
+      // Live entries only accumulate during an ACTIVE run. For a completed run
+      // (or before any capture) this tab is empty — guide the user to the
+      // populated summary tabs instead of leaving a dead-end "暂无实时活动" state.
+      const hasThreads = (manifest.rounds || []).length > 0
+      const hasFindings = (manifest.findings || []).length > 0
+      if (hasThreads || hasFindings) {
+        return React.createElement('div', { className: 'iterate-obs-empty' },
+          React.createElement('div', {}, '实时活动流仅在运行期间记录，当前已完成。'),
+          React.createElement('div', { className: 'iterate-obs-bar', style: { marginTop: 8 } },
+            React.createElement('button', { className: 'iterate-btn', onClick: () => setTab('f1') }, '查看审查线程'),
+            React.createElement('button', { className: 'iterate-btn', onClick: () => setTab('f3') }, '查看发现'),
+          ),
+        )
+      }
       return React.createElement('div', { className: 'iterate-obs-empty' }, '暂无实时活动')
     }
     const rows = liveEntries.map((e, i) => {
@@ -1880,6 +1914,19 @@ function ObservatoryPanel(props: SlotProps) {
     ),
     open
       ? React.createElement('div', {},
+          copyFailText
+            ? React.createElement('div', { className: 'iterate-obs-block' },
+                React.createElement('div', { className: 'iterate-obs-block-head' },
+                  React.createElement('b', {}, '复制未成功'),
+                  React.createElement('span', { className: 'iterate-obs-head-meta' }, '剪贴板写入被拒绝，请手动选中下方指令复制'),
+                  React.createElement('button', {
+                    className: 'iterate-btn', 'data-ghost': '', 'aria-label': '关闭复制失败提示',
+                    onClick: () => setCopyFailText(null),
+                  }, '关闭'),
+                ),
+                React.createElement('div', { className: 'iterate-obs-code' }, copyFailText),
+              )
+            : null,
           React.createElement('div', { className: 'iterate-obs-tabs' },
             ...OBS_TABS.map((t) =>
               React.createElement('button', {

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
+  }
+}