iterate-plugin 3.5.7 → 3.7.0

package/dist/tools/history.js

@@ -24,16 +24,29 @@ export function clampHistoryLimit(limit) {
  * Filter + cap decision-log entries. Pure, unit-tested.
  * Returns the newest `limit` matching entries plus the total match count
  * (before the cap), so callers can tell when the result was truncated.
+ *
+ * `round` keeps only entries logged for that round; `file` keeps only entries
+ * whose `data.file` names that fixed file. Invalid `round`/`file` inputs are
+ * ignored (same convention as `type`/`since`), never treated as a match-nothing
+ * filter by accident.
  */
 export function filterDecisionEntries(entries, opts) {
     const type = typeof opts.type === 'string' && opts.type ? opts.type : undefined;
     const since = typeof opts.since === 'string' && opts.since ? opts.since : undefined;
+    const round = typeof opts.round === 'number' && Number.isInteger(opts.round) && opts.round >= 0
+        ? opts.round
+        : undefined;
+    const file = typeof opts.file === 'string' && opts.file ? opts.file : undefined;
     const limit = clampHistoryLimit(opts.limit);
     const matching = (Array.isArray(entries) ? entries : []).filter((e) => {
         if (type && e.type !== type)
             return false;
         if (since && e.timestamp <= since)
             return false;
+        if (round !== undefined && e.round !== round)
+            return false;
+        if (file && (!e.data || e.data.file !== file))
+            return false;
         return true;
     });
     return {
@@ -42,15 +55,44 @@ export function filterDecisionEntries(entries, opts) {
         limit,
     };
 }
-/** Per-round fix counts + totals from a fix registry. Pure, unit-tested. */
-export function summarizeFixRegistry(registry) {
-    const rounds = (registry.rounds ?? []).map((r) => ({
-        round: r.round,
-        // Coerce defensively so a hand-edited registry round missing either count
-        // can never propagate NaN into the integer output fields.
-        fixedCount: Number(r.fixedCount) || 0,
-        failedCount: Number(r.failedCount) || 0,
-    }));
+/**
+ * Per-round fix counts + totals from a fix registry. Pure, unit-tested.
+ *
+ * `opts.round` narrows the view to one round. `opts.file` narrows each round to
+ * the records that fixed that file: the stored per-round counts cover every
+ * file and cannot be subsetted, so a file-scoped summary RECOMPUTES the counts
+ * from the kept records (mirroring `recomputeRoundCounts`), and rounds left
+ * without any matching record are dropped entirely — an all-zero placeholder
+ * round would falsely suggest the file was touched that round.
+ */
+export function summarizeFixRegistry(registry, opts = {}) {
+    const roundFilter = typeof opts.round === 'number' && Number.isInteger(opts.round) && opts.round >= 0
+        ? opts.round
+        : undefined;
+    const fileFilter = typeof opts.file === 'string' && opts.file ? opts.file : undefined;
+    const rounds = (registry.rounds ?? [])
+        .filter((r) => roundFilter === undefined || r.round === roundFilter)
+        .flatMap((r) => {
+        if (fileFilter === undefined) {
+            // Coerce defensively so a hand-edited registry round missing either count
+            // can never propagate NaN into the integer output fields.
+            return [{
+                    round: r.round,
+                    fixedCount: Number(r.fixedCount) || 0,
+                    failedCount: Number(r.failedCount) || 0,
+                }];
+        }
+        const kept = (r.records ?? []).filter((rec) => rec && rec.finding && rec.finding.file === fileFilter);
+        if (kept.length === 0)
+            return [];
+        // Recompute from the kept records: a rolled-back (success:false) record
+        // counts as failed, matching the registry's own recomputeRoundCounts.
+        return [{
+                round: r.round,
+                fixedCount: kept.filter((rec) => rec.success).length,
+                failedCount: kept.filter((rec) => !rec.success).length,
+            }];
+    });
     return {
         totalFixed: rounds.reduce((s, r) => s + r.fixedCount, 0),
         totalFailed: rounds.reduce((s, r) => s + r.failedCount, 0),
@@ -60,8 +102,9 @@ export function summarizeFixRegistry(registry) {
 }
 /**
  * Register the `iterate_history` tool.
- * Reads the decision log (optionally filtered by type / since / limit) and a
- * fix-registry summary. Read-only; never modifies the filesystem.
+ * Reads the decision log (optionally filtered by type / since / round / file /
+ * limit) and a fix-registry summary (scoped by the same round / file filters).
+ * Read-only; never modifies the filesystem.
  */
 export function registerHistoryTool(ctx) {
     ctx.tools.register(defineTool({
@@ -70,7 +113,8 @@ export function registerHistoryTool(ctx) {
         // dispatch group alongside other read-only sibling calls.
         isConcurrencySafe: () => true,
         description: 'Read the iteration history: decision-log entries (optionally filtered by entry `type`, `since` ' +
-            'timestamp, and a `limit`) plus a summary of the fix registry (per-round fixed/failed counts). ' +
+            'timestamp, `round`, fixed `file`, and a `limit`) plus a summary of the fix registry (per-round ' +
+            'fixed/failed counts, scoped by the same round/file filters). ' +
             'Read-only — use it to review what the run did, audit a log, or inspect fixes.',
         parameters: {
             type: {
@@ -82,6 +126,16 @@ export function registerHistoryTool(ctx) {
                 type: 'string',
                 description: 'Optional ISO timestamp; only entries AFTER this timestamp are returned.',
             },
+            round: {
+                type: 'integer',
+                description: 'Optional round number; only decision-log entries logged for this round are returned, ' +
+                    'and the fix summary is scoped to this round.',
+            },
+            file: {
+                type: 'string',
+                description: 'Optional fixed-file path; only decision-log entries whose `data.file` matches are returned, ' +
+                    'and the fix summary counts only fixes applied to that file.',
+            },
             limit: {
                 type: 'integer',
                 description: `Max entries to return (default: ${DEFAULT_LIMIT}, cap: ${MAX_LIMIT}). Returns the newest window in chronological order.`,
@@ -127,8 +181,8 @@ export function registerHistoryTool(ctx) {
             if (!resolved.ok)
                 return { ok: false, kind: 'history', error: resolved.reason };
             const projectRoot = resolved.root;
-            const { entries, filteredCount, limit } = filterDecisionEntries(readDecisionEntries(projectRoot), { type: args.type, since: args.since, limit: args.limit });
-            const fixes = summarizeFixRegistry(readRegistry(projectRoot));
+            const { entries, filteredCount, limit } = filterDecisionEntries(readDecisionEntries(projectRoot), { type: args.type, since: args.since, limit: args.limit, round: args.round, file: args.file });
+            const fixes = summarizeFixRegistry(readRegistry(projectRoot), { round: args.round, file: args.file });
             return {
                 ok: true,
                 kind: 'history',

package/dist/tools/present.js

@@ -0,0 +1,80 @@
+/**
+ * src/tools/present.ts — shared `presentResult` helpers for the iterate tools (#12).
+ *
+ * dsh presents a completed call through `ToolDefinition.presentResult(args,
+ * result)` when the tool supplies one; the return value is a `ToolResultView`
+ * (a `card`-tagged render intent from `@deepseek-ai/dsh-tools`). These helpers
+ * read ONLY the durable result projection handed to the presenter
+ * (`result.content` / `result.isError`) — they never re-execute anything, so a
+ * live call and a session-log replay produce the identical card.
+ *
+ * House rules for every presenter built on this module:
+ *   - Pure / replay-safe: depend on `args` + `result` only.
+ *   - Defensive: any shape it cannot read returns `undefined`, which makes the
+ *     UI fall back to the default presentation (pending title + raw result)
+ *     instead of a wrong or half-guessed card.
+ *   - No invented copy: card text is derived from the render output the tool
+ *     itself produced.
+ */
+/**
+ * Concatenated text of a completed call's rendered content, or `undefined`
+ * when there is none. Failure results are never summarized — the presenter
+ * declines the card and the UI shows the raw error.
+ */
+export function renderedText(result) {
+    if (!result || result.isError === true || !Array.isArray(result.content))
+        return undefined;
+    const parts = [];
+    for (const block of result.content) {
+        if (block && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string') {
+            parts.push(block.text);
+        }
+    }
+    return parts.length > 0 ? parts.join('\n') : undefined;
+}
+/**
+ * First non-empty line of the rendered content — the card headline for a
+ * `presentResult` (#12). Long lines are clamped so a card header stays a
+ * header. `undefined` (failure / no text) means "decline the card".
+ */
+export function resultHeadline(result, maxLength = 160) {
+    const text = renderedText(result);
+    if (!text)
+        return undefined;
+    const line = text.split('\n').find((l) => l.trim().length > 0);
+    if (!line)
+        return undefined;
+    const trimmed = line.trim();
+    return trimmed.length > maxLength ? `${trimmed.slice(0, maxLength - 1)}…` : trimmed;
+}
+/**
+ * Parse a tool's rendered content as JSON — for tools whose `render` emits
+ * `JSON.stringify(value, null, 2)` verbatim (review, checkpoint). Returns a
+ * plain record, or `undefined` when the content is not an object-shaped JSON
+ * document (the presenter then declines the card rather than guess).
+ */
+export function parseRenderedJson(result) {
+    const text = renderedText(result);
+    if (!text)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? parsed
+        : undefined;
+}
+/** Narrow an unknown value to a plain record (arrays/null/primitives → undefined). */
+export function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Finite-number narrow for defensively reading fields off a parsed result. */
+export function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}

package/dist/tools/prune.js

@@ -21,14 +21,16 @@
  * Security model:
  *   - Only operates under the resolved project `.iterate/` directory.
  *   - dryRun=true by default — the caller must explicitly opt into deletion.
- *   - Each deletion is logged to the decision log (when not dry-run).
+ *   - Each non-dry-run appends ONE aggregate summary entry to the decision
+ *     log (counts per artifact class) — not one log line per deleted file.
  */
-import { existsSync, readdirSync, rmSync, unlinkSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, rmSync, unlinkSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { writeTextAtomic, writeJsonAtomic } from "../atomic-fs.js";
-import { readDecisionEntries, appendDecisionEntry, acquireLogLock, invalidateLogCountCache } from "./decision-log.js";
+import { withProjectLock } from "../file-lock.js";
+import { readDecisionEntries, appendDecisionEntry, acquireLogLockChecked, invalidateLogCountCache } from "./decision-log.js";
 import { readRegistry, recomputeRoundCounts } from "./fix.js";
 import { readExperienceBank, writeExperienceBank } from "./experience-store.js";
 import { readDefenseEvents, writeDefenseEvents } from "./defense-store.js";
@@ -91,12 +93,20 @@ export function sweepExperienceBank(bank, cap) {
     const total = bank.entries.length;
     if (total <= size)
         return { bank, removed: 0 };
-    const kept = [...bank.entries]
-        .sort((a, b) => (b.timestamp ?? '').localeCompare(a.timestamp ?? ''))
-        .slice(0, size);
-    // Preserve the original (insertion) order of the surviving entries.
-    const keptIds = new Set(kept.map((e) => e.id));
-    const ordered = bank.entries.filter((e) => keptIds.has(e.id));
+    // Keep by POSITION, not by id: a Set of kept ids lets duplicate ids (a
+    // hand-edited or double-written bank) defeat the cap — every original entry
+    // sharing a kept id would survive, so `removed` stayed 0 and the cap never
+    // applied. Rank positions newest-first (ties fall back to the original index
+    // so equal timestamps keep insertion order, as before), keep the first `size`
+    // positions, then re-emit the survivors in insertion order.
+    const ranked = bank.entries.map((_, i) => i);
+    ranked.sort((a, b) => {
+        const ta = bank.entries[a]?.timestamp ?? '';
+        const tb = bank.entries[b]?.timestamp ?? '';
+        return tb.localeCompare(ta) || a - b;
+    });
+    const keep = new Set(ranked.slice(0, size));
+    const ordered = bank.entries.filter((_, i) => keep.has(i));
     return {
         bank: { ...bank, entries: ordered, lastUpdated: new Date().toISOString() },
         removed: total - ordered.length,
@@ -160,6 +170,27 @@ export function inspectPrune(projectRoot, retainDays) {
         }
     }
     // 3. Stale fix backups: .bak files whose fix-id prefix is not in the registry.
+    //
+    // `readRegistry` returns an EMPTY registry for BOTH "file absent" and "file
+    // present but corrupt" — and for the corrupt case an empty active-id set
+    // would classify EVERY backup stale, so a single dryRun:false prune would
+    // delete the entire rollback safety net. Read the registry file directly to
+    // distinguish the two: absent ⇒ backups are orphaned (stale, delete as
+    // before); present-but-unreadable ⇒ set `registryError`, classify nothing,
+    // and let `executePrune`/the render surface the refusal.
+    const registryFile = fixRegistryPath(projectRoot);
+    let registryError = null;
+    if (existsSync(registryFile)) {
+        try {
+            const parsed = JSON.parse(readFileSync(registryFile, 'utf-8'));
+            if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.rounds)) {
+                registryError = `refusing to delete fix backups: fix registry is present but unreadable (invalid shape): ${registryFile}`;
+            }
+        }
+        catch (err) {
+            registryError = `refusing to delete fix backups: fix registry is present but unreadable: ${String(err)} (${registryFile})`;
+        }
+    }
     const registry = readRegistry(projectRoot);
     const activeIds = new Set();
     for (const r of registry.rounds) {
@@ -179,15 +210,17 @@ export function inspectPrune(projectRoot, retainDays) {
     catch {
         fixEntries = [];
     }
-    for (const entry of fixEntries) {
-        if (!entry.endsWith('.bak'))
-            continue;
-        // Extract the fix-id prefix (up to the first underscore after the id).
-        // e.g. "fix-abc123_2026-08-17T00-00-00-000Z.bak" → "fix-abc123"
-        const match = entry.match(/^(fix-[a-z0-9]+)_/);
-        const id = match?.[1];
-        if (id && !activeIds.has(id)) {
-            staleBackups.push(entry);
+    if (registryError === null) {
+        for (const entry of fixEntries) {
+            if (!entry.endsWith('.bak'))
+                continue;
+            // Extract the fix-id prefix (up to the first underscore after the id).
+            // e.g. "fix-abc123_2026-08-17T00-00-00-000Z.bak" → "fix-abc123"
+            const match = entry.match(/^(fix-[a-z0-9]+)_/);
+            const id = match?.[1];
+            if (id && !activeIds.has(id)) {
+                staleBackups.push(entry);
+            }
         }
     }
     // 4. Empty rounds (rounds with 0 records).
@@ -224,6 +257,7 @@ export function inspectPrune(projectRoot, retainDays) {
         emptyRounds,
         totalLogEntries: entries.length,
         registryRounds: registry.rounds.length,
+        registryError,
         totalExperiences: bank.entries.length,
         experienceOversize: sweptBank.removed,
         totalDefenseEvents: defenseStream.events.length,
@@ -239,29 +273,56 @@ export function inspectPrune(projectRoot, retainDays) {
  *
  * The read-before-rewrite is a TOCTOU hot spot: a concurrent worker can append
  * a fresh audit line between our read and our atomic rewrite, and an atomic
- * rename would silently discard it. So instead of a single read+write we use a
- * bounded compare-and-append loop — after each rewrite we re-read the log and
+ * rename would silently discard it. So instead of a single read+write we take
+ * the cross-process log mutex for the whole loop AND keep a bounded
+ * compare-and-append loop behind it — after each rewrite we re-read the log and
  * retry whenever the file grew (a concurrent append slipped in). The loop
  * terminates when the file is stable or after `MAX_LOG_REWRITE_RETRIES`, and a
  * failure here is surfaced as a structured error instead of truncating the log.
  *
- * @returns the number of entries removed (best-effort) or 0 on error.
+ * Lock required: when the mutex cannot be taken (another process is appending
+ * and does not release within the wait budget) the rewrite is REFUSED with a
+ * structured error rather than proceeding unlocked — an unlocked rename can
+ * drop a concurrent appender's audit line (its fd points at the pre-rename
+ * inode) with no way to detect the loss afterwards.
+ *
+ * `deleted` is the TOTAL across every attempt: attempt 1 may already have
+ * removed entries before a retry is needed, and reporting only the final
+ * attempt's slice would under-count the audit entry (the pre-fix code returned
+ * `deleted: 0` on the exhaustion path even after real deletions).
+ *
+ * @param options.afterRewrite test hook run after each successful rewrite —
+ * simulates a concurrent appender landing lines mid-loop (production passes
+ * no hook).
+ * @param options.lock lock wait/stale budgets (tests pass short waits so the
+ * lock-unavailable refusal is exercised in milliseconds, not 5s).
+ * @returns the number of entries removed across all attempts, or 0 with an
+ *  `error` when nothing needed removing or the rewrite was refused/failed.
  */
-function rewriteDecisionLogKeepingRecent(projectRoot, cutoff) {
+export function rewriteDecisionLogKeepingRecent(projectRoot, cutoff, options = {}) {
     const logPath = join(iterateDir(projectRoot), 'decision-log.jsonl');
     // Take the cross-process log lock for the ENTIRE loop: with the mutex held,
     // no concurrent appender can slip a fresh line into the read-before-rewrite
     // window, so the first attempt is nearly always the only one. (The retry
-    // loop stays as defense-in-depth for the lock-unavailable path.)
-    const release = acquireLogLock(projectRoot);
+    // loop stays as defense-in-depth for a line landing via the afterRewrite
+    // hook or an already-running appender's buffered write.)
+    const { acquired, release } = acquireLogLockChecked(projectRoot, options.lock);
+    if (!acquired) {
+        return {
+            deleted: 0,
+            error: 'failed to acquire the decision-log lock — refusing to rewrite the log unlocked ' +
+                '(a concurrent appender could lose an audit line). Retry after the other operation finishes.',
+        };
+    }
     try {
+        let deletedTotal = 0;
         for (let attempt = 0; attempt < MAX_LOG_REWRITE_RETRIES; attempt++) {
             try {
                 const entries = readDecisionEntries(projectRoot);
                 const kept = entries.filter((e) => e.timestamp >= cutoff);
                 const deleted = entries.length - kept.length;
                 if (deleted === 0)
-                    return { deleted: 0 };
+                    return { deleted: deletedTotal };
                 writeTextAtomic(logPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n');
                 // The append-side entry-count cache is keyed by path and assumes "same
                 // byte size ⇒ same count"; the rename above replaced the file with a
@@ -269,18 +330,23 @@ function rewriteDecisionLogKeepingRecent(projectRoot, cutoff) {
                 // append can report a wrong entryCount when the sizes coincidentally
                 // match.
                 invalidateLogCountCache(logPath);
+                // Accumulate THIS attempt's deletions before the re-read: whatever the
+                // later attempts (or the exhaustion path) report, these entries are
+                // already gone from disk and must count toward the audit total.
+                deletedTotal += deleted;
+                options.afterRewrite?.();
                 // A concurrent appender (cross-process, lock-unavailable path) may have
                 // landed new lines after our read. If the log grew during the write
                 // window, re-read and prune again instead of accepting a lost audit trail.
                 const after = readDecisionEntries(projectRoot);
                 if (after.length <= kept.length)
-                    return { deleted };
+                    return { deleted: deletedTotal };
             }
             catch (err) {
-                return { deleted: 0, error: `failed to rewrite decision log: ${String(err)}` };
+                return { deleted: deletedTotal, error: `failed to rewrite decision log: ${String(err)}` };
             }
         }
-        return { deleted: 0, error: `failed to rewrite decision log after ${MAX_LOG_REWRITE_RETRIES} attempts` };
+        return { deleted: deletedTotal, error: `failed to rewrite decision log after ${MAX_LOG_REWRITE_RETRIES} attempts` };
     }
     finally {
         release();
@@ -304,9 +370,10 @@ export function executePrune(projectRoot, retainDays, report) {
         errors: [],
     };
     // 1. Rewrite the decision log, keeping only recent entries. Atomic
-    // (temp + rename) so a crash mid-write can never truncate the log; the
-    // bounded compare-and-append loop guards against a concurrent appender
-    // slipping a fresh audit line into the read-before-rewrite window.
+    // (temp + rename) under the cross-process log mutex — REFUSED with a
+    // structured error when the lock cannot be taken (an unlocked rename could
+    // drop a concurrent appender's audit line); the bounded compare-and-append
+    // loop behind it guards the remaining read-before-rewrite window.
     {
         const { deleted, error } = rewriteDecisionLogKeepingRecent(projectRoot, cutoff);
         result.deletedLogEntries = deleted;
@@ -325,30 +392,42 @@ export function executePrune(projectRoot, retainDays, report) {
             result.errors.push(`failed to remove checkpoint: ${String(err)}`);
         }
     }
-    // 3. Delete stale backups.
-    for (const bak of report.staleBackups) {
-        try {
-            unlinkSync(join(fixesDir(projectRoot), bak));
-            result.deletedBackups.push(bak);
-        }
-        catch (err) {
-            result.errors.push(`failed to delete backup ${bak}: ${String(err)}`);
+    // 3. Delete stale backups — REFUSED outright when the registry is present
+    // but unreadable: without a readable active-id set every backup would have
+    // classified stale, and one dryRun:false prune would wipe the whole rollback
+    // safety net. Surface the refusal as a structured error instead.
+    if (report.registryError) {
+        result.errors.push(report.registryError);
+    }
+    else {
+        for (const bak of report.staleBackups) {
+            try {
+                unlinkSync(join(fixesDir(projectRoot), bak));
+                result.deletedBackups.push(bak);
+            }
+            catch (err) {
+                result.errors.push(`failed to delete backup ${bak}: ${String(err)}`);
+            }
         }
     }
-    // 4. Trim empty rounds from the registry.
+    // 4. Trim empty rounds from the registry (locked read-modify-write: the
+    // registry read and rewrite must not interleave with another process's
+    // fix/rollback or the update is lost — see src/file-lock.ts).
     if (report.emptyRounds.length > 0) {
         try {
-            let registry = readRegistry(projectRoot);
-            const emptyRoundNos = new Set(report.emptyRounds);
-            // Drop whole empty rounds (records.length === 0) instead of only
-            // removing their records — an empty round has no records to remove, so
-            // the old loop was a no-op that still reported trimmedEmptyRounds.
-            registry = {
-                ...registry,
-                rounds: registry.rounds.filter((r) => !emptyRoundNos.has(r.round) || (r.records?.length ?? 0) > 0),
-            };
-            registry = recomputeRoundCounts(registry);
-            writeJsonAtomic(fixRegistryPath(projectRoot), registry);
+            withProjectLock(projectRoot, 'fix-registry', () => {
+                let registry = readRegistry(projectRoot);
+                const emptyRoundNos = new Set(report.emptyRounds);
+                // Drop whole empty rounds (records.length === 0) instead of only
+                // removing their records — an empty round has no records to remove, so
+                // the old loop was a no-op that still reported trimmedEmptyRounds.
+                registry = {
+                    ...registry,
+                    rounds: registry.rounds.filter((r) => !emptyRoundNos.has(r.round) || (r.records?.length ?? 0) > 0),
+                };
+                registry = recomputeRoundCounts(registry);
+                writeJsonAtomic(fixRegistryPath(projectRoot), registry);
+            });
             result.trimmedEmptyRounds = report.emptyRounds.length;
         }
         catch (err) {
@@ -403,12 +482,27 @@ export function executePrune(projectRoot, retainDays, report) {
 export function registerPruneTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_prune',
+        // Pending-call card (#12): say up front whether this sweep is the default
+        // report-only preview or a REAL deletion — that distinction is prune's
+        // entire safety model, so it must be visible before the call runs. Pure:
+        // derived from args only.
+        presentCall: (args) => {
+            const a = args;
+            const deleting = a.dryRun === false;
+            return {
+                card: 'generic',
+                title: deleting
+                    ? 'Prune stale .iterate/ artifacts (delete)'
+                    : 'Prune preview (dry run — nothing deleted)',
+                kind: deleting ? 'delete' : 'read',
+            };
+        },
         description: 'Inspect or clean up old iterate runtime artifacts (.iterate/). ' +
             'Defaults to dry-run (report-only, no deletion). Pass `dryRun: false` to actually prune. ' +
             'Manages: old decision-log entries, stale checkpoints, orphaned fix backups, empty fix rounds, ' +
             'stray temp files left by crashed atomic writes, experience-bank entries beyond the entry cap, ' +
             'and stale defense events. ' +
-            'Each deletion is logged to the decision log.',
+            'A non-dry-run appends ONE aggregate summary entry (counts per artifact class) to the decision log.',
         parameters: {
             dryRun: {
                 type: 'boolean',
@@ -442,11 +536,14 @@ export function registerPruneTool(ctx) {
                 const report = value.report;
                 const result = value.result;
                 if (value.dryRun) {
+                    const registryError = report?.registryError;
                     const lines = [
                         `[dry-run] prune report (retainDays=${value.retainDays}):`,
                         `  Decision-log entries to remove: ${report?.oldLogEntries ?? '?'} (of ${report?.totalLogEntries ?? '?'})`,
                         `  Checkpoint to delete: ${report?.checkpointStale ? 'yes (stale)' : report?.hasCheckpoint ? 'no (fresh — resume point, kept)' : 'none'}`,
-                        `  Stale backups to delete: ${report?.staleBackups?.length ?? 0}`,
+                        registryError
+                            ? `  Stale backups to delete: none — ${registryError}`
+                            : `  Stale backups to delete: ${report?.staleBackups?.length ?? 0}`,
                         `  Stray temp files to delete: ${report?.staleTemps?.length ?? 0}`,
                         `  Empty rounds to trim: ${report?.emptyRounds?.length ?? 0}`,
                         `  Experience entries to drop (over ${report?.totalExperiences ?? '?'} cap): ${report?.experienceOversize ?? 0} of ${report?.totalExperiences ?? '?'}`,

package/dist/tools/quality-gate.js

@@ -9,6 +9,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { readQualityGate, writeQualityGate, computeQualityGate, clearQualityGate } from "./quality-store.js";
+import { resultHeadline } from "./present.js";
 /** Valid severity values (kept in sync with QualityGateSnapshot counting). */
 const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
 /** Validate a single finding object; returns true when well-formed. */
@@ -62,6 +63,14 @@ function sanitizeRoundSeries(raw) {
 export function registerQualityGateTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_quality_gate',
+        // Result card (#12): the certificate render already opens with its
+        // headline ("✓ Quality Gate: PASS (score: 92)") — surface that as the
+        // card title so a completed gate query isn't a bare blob. Pure: reads
+        // only the rendered result (replay-safe); failures decline the card.
+        presentResult: (_args, result) => {
+            const title = resultHeadline(result);
+            return title ? { card: 'generic', title } : undefined;
+        },
         // `read` never writes; `compute` persists the snapshot → only read
         // joins a parallel dispatch group.
         isConcurrencySafe: (args) => args.operation === 'read',
@@ -81,11 +90,13 @@ export function registerQualityGateTool(ctx) {
             dimensions: {
                 type: 'array',
                 items: { type: 'string' },
-                description: 'Dimensions to gate (required for compute).',
+                description: 'Dimensions to gate (required and must be non-empty for compute).',
             },
             findings: {
                 type: 'json',
-                description: 'Findings array (required for compute). Each item: { dimension, severity (critical|high|medium|low), file, line? }.',
+                description: 'Findings array for compute (optional — defaults to []). Each item: ' +
+                    '{ dimension, severity (critical|high|medium|low), file, line? }. Findings whose dimension ' +
+                    'is not listed in `dimensions` are excluded from scoring and reported as warnings.',
             },
             validationResults: {
                 type: 'json',
@@ -114,6 +125,11 @@ export function registerQualityGateTool(ctx) {
                     kind: { type: 'string' },
                     operation: { type: 'string' },
                     snapshot: { type: 'json' },
+                    warnings: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'compute only: findings excluded from scoring because their dimension is not gated.',
+                    },
                     error: { type: 'string' },
                 },
             },
@@ -139,6 +155,9 @@ export function registerQualityGateTool(ctx) {
                 if (snapshot.failReason) {
                     lines.push('', `Fail Reason: ${snapshot.failReason}`);
                 }
+                if (Array.isArray(value.warnings) && value.warnings.length > 0) {
+                    lines.push('', 'Warnings:', ...value.warnings.map((w) => `  ! ${String(w)}`));
+                }
                 if (operation === 'compute') {
                     lines.push('', 'Quality gate snapshot computed and persisted.');
                 }
@@ -170,12 +189,40 @@ export function registerQualityGateTool(ctx) {
                 const dimensions = Array.isArray(args.dimensions)
                     ? args.dimensions.filter((d) => typeof d === 'string' && d.length > 0)
                     : [];
+                // A compute without any gateable dimension would score an empty
+                // dimension list at overallScore 0 and PERSIST a fabricated FAIL
+                // certificate for a review that was simply never scoped. Refuse
+                // instead: no snapshot is written, and the caller gets a structured
+                // error naming the missing argument.
+                if (dimensions.length === 0) {
+                    return {
+                        ok: false,
+                        kind: 'quality_gate',
+                        operation: 'compute',
+                        error: 'dimensions is required (and must be a non-empty array of dimension names) for operation "compute" — ' +
+                            'without dimensions there is nothing to gate and no certificate can be computed.',
+                    };
+                }
                 const findings = Array.isArray(args.findings) ? args.findings.filter(isValidFinding) : [];
                 const validationResults = Array.isArray(args.validationResults)
                     ? args.validationResults.filter(isValidValidationResult)
                     : undefined;
                 const findingsByRound = sanitizeRoundSeries(args.findingsByRound);
                 const fixedByDimension = sanitizeNumberMap(args.fixedByDimension);
+                // Findings in dimensions outside the gated list are silently skipped
+                // by computeQualityGate (they never touch any dimension score) — a
+                // critical one still fails the gate globally, everything else just
+                // vanishes from the numbers. Surface those dimensions as warnings so
+                // the caller knows the score does NOT cover them; scoring is
+                // deliberately left unchanged.
+                const gated = new Set(dimensions);
+                const ungatedCounts = new Map();
+                for (const finding of findings) {
+                    if (!gated.has(finding.dimension)) {
+                        ungatedCounts.set(finding.dimension, (ungatedCounts.get(finding.dimension) ?? 0) + 1);
+                    }
+                }
+                const warnings = [...ungatedCounts].map(([dimension, count]) => `finding dimension "${dimension}" is not in the gated dimensions and was excluded from scoring (${count} finding${count === 1 ? '' : 's'})`);
                 const snapshot = computeQualityGate({
                     dimensions,
                     findings,
@@ -192,6 +239,9 @@ export function registerQualityGateTool(ctx) {
                     kind: 'quality_gate',
                     operation: 'compute',
                     snapshot: snapshot,
+                    // Typed by the output schema as string[] — do not widen this to
+                    // JsonValue or the execute return type stops matching the schema.
+                    warnings,
                 };
             }
             const snapshot = readQualityGate(projectRoot);