iterate-plugin 3.5.6 → 3.6.0

package/dist/tools/quality-store.js

@@ -59,6 +59,11 @@ export function readQualityGate(projectRoot) {
                 })
                 : [];
             return {
+                // Snapshot-level fallback timestamp: display-only metadata — the gate
+                // is a SINGLE snapshot file (overwritten wholesale), and nothing sorts
+                // or evicts by `timestamp`, so a missing/corrupt value degrading to
+                // "now" cannot affect retention or ordering. (Reaffirmed from the
+                // earlier review: comment only, behavior unchanged.)
                 timestamp: typeof parsed.timestamp === 'string' ? parsed.timestamp : emptySnapshot().timestamp,
                 overallStatus: status,
                 overallScore: num(parsed.overallScore),
@@ -160,6 +165,12 @@ export function computeQualityGate(opts) {
         dimensionStats[dim] = { count: 0, critical: 0, high: 0, medium: 0, low: 0 };
     }
     for (const finding of findings) {
+        // Findings in dimensions outside the gated list land here with no matching
+        // `dimensionStats` entry and are skipped — they never touch any dimension
+        // score (only a global critical still fails the gate). Scoring stays
+        // unchanged by contract; the tool layer surfaces the excluded dimensions
+        // as `warnings` so the numbers are never silently incomplete
+        // (see src/tools/quality-gate.ts).
         const stats = dimensionStats[finding.dimension];
         if (stats) {
             stats.count++;
@@ -179,7 +190,12 @@ export function computeQualityGate(opts) {
         // Score: 100 - (critical*30 + high*15 + medium*5 + low*1), capped at 0
         const penalty = stats.critical * 30 + stats.high * 15 + stats.medium * 5 + stats.low * 1;
         const score = Math.max(0, 100 - penalty);
-        const status = score >= 80 ? 'pass' : score >= 50 ? 'warn' : 'fail';
+        // Arithmetic alone would grade a single critical as 100-30=70 → 'warn',
+        // while the snapshot's overall status is 'fail' (hasCritical below) — a
+        // certificate that contradicts itself ("WARN" on the dimension that made
+        // the gate fail). Any critical finding is a hard FAIL for that dimension,
+        // regardless of its score; non-critical dimensions keep the score bands.
+        const status = stats.critical > 0 ? 'fail' : score >= 80 ? 'pass' : score >= 50 ? 'warn' : 'fail';
         const series = findingsByRound?.[dim];
         const convergenceRate = convergenceRateFor(Array.isArray(series) ? series : undefined, stats.count);
         return {

package/dist/tools/review.js

@@ -1,13 +1,73 @@
 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 { buildReviewPlan, buildReviewReport, sanitizeRounds, validateRoundsSchema, MAX_REVIEW_ROUNDS_CAP, } from "../review.js";
 import { buildFinalReviewReport, metaReviewReport } from "../meta-review.js";
-import { evidenceToPlain, verifyFindings } from "../evidence.js";
+import { evidenceToPlain, resolveWithin, verifyFindings } from "../evidence.js";
+import { readKnownIntentional } from "./triage.js";
+import { asNumber, asRecord, parseRenderedJson } from "./present.js";
 import { collectScopeFiles, computeCoverage, coverageToDict, } from "../review-scope.js";
 import { resolveChangedFiles } from "../git-scope.js";
 /** Default round cap when neither the arg nor config provides one. */
 const DEFAULT_MAX_REVIEW_ROUNDS = 3;
+/**
+ * Resolve the effective round cap at the TOOL boundary so `plan` and
+ * `aggregate` can never disagree on it (the plan advertises a cap the
+ * aggregate must then honor).
+ *
+ * Precedence: a FINITE caller value → a FINITE config value → the default (3).
+ * A non-finite / non-numeric caller value does NOT collapse to 1 — it falls
+ * through to the config value (the old doc comment claimed otherwise, which
+ * the implementation never did). Only a finite `≤ 0` value collapses to 1,
+ * the smallest sane cap.
+ *
+ * The resolved value is then clamped to `[1, MAX_REVIEW_ROUNDS_CAP]`, so an
+ * absurd caller value (1e15) can no longer leak an unbounded cap into the
+ * report's `maxReviewRounds` field (`buildReviewReport` echoes its input and
+ * `aggregateRounds` sizes `findingsByRound` from it). Upper clamp mirrors
+ * `clampMaxReviewRounds` in src/review.ts.
+ */
+export function resolveMaxReviewRounds(argsMax, configMax) {
+    const raw = typeof argsMax === 'number' && Number.isFinite(argsMax)
+        ? argsMax
+        : typeof configMax === 'number' && Number.isFinite(configMax)
+            ? configMax
+            : DEFAULT_MAX_REVIEW_ROUNDS;
+    return Math.min(MAX_REVIEW_ROUNDS_CAP, Math.max(1, Math.floor(raw)));
+}
+/**
+ * Build the READ set backing the meta-review evidence verdict from the
+ * report's self-reported `readFiles` (aggregated across rounds; falls back to
+ * the per-round lists for older reports that predate the flat field).
+ *
+ * Entries are resolved the SAME way `verifyFinding` resolves a finding's
+ * `file` (lexical, root-relative) so the Set membership check matches, and
+ * entries escaping the project root are dropped. Returns `undefined` when
+ * nothing was read — an absent read set keeps `readVerified` "not checkable"
+ * (null ratio) instead of a misleading `0.0`.
+ */
+function buildReadSet(projectRoot, report) {
+    const raw = [];
+    if (Array.isArray(report.readFiles)) {
+        raw.push(...report.readFiles);
+    }
+    else if (Array.isArray(report.rounds)) {
+        for (const r of report.rounds) {
+            const files = r?.readFiles;
+            if (Array.isArray(files))
+                raw.push(...files);
+        }
+    }
+    const set = new Set();
+    for (const p of raw) {
+        if (typeof p !== 'string' || p === '')
+            continue;
+        const abs = resolveWithin(projectRoot, p);
+        if (abs !== null)
+            set.add(abs);
+    }
+    return set.size > 0 ? set : undefined;
+}
 /**
  * Register the `iterate_review` tool.
  *
@@ -21,9 +81,73 @@ const DEFAULT_MAX_REVIEW_ROUNDS = 3;
  *                 severity sort, and convergence stats; returns a ReviewReport.
  *                 Purely computational — NEVER touches the filesystem.
  */
+/**
+ * Card headline for an `aggregate` result: what the report found and where
+ * convergence stands (#12). Defensive — returns `undefined` whenever the
+ * payload is not the shape this tool renders, so the card is declined rather
+ * than guessed at.
+ */
+function aggregateHeadline(value) {
+    const report = asRecord(value.report);
+    const summary = report ? asRecord(report.summary) : undefined;
+    const total = summary ? asNumber(summary.totalFindings) : undefined;
+    if (total === undefined || !summary)
+        return undefined;
+    const buckets = ['critical', 'high', 'medium', 'low']
+        .map((k) => ({ label: k, n: asNumber(summary[k]) ?? 0 }))
+        .filter((b) => b.n > 0)
+        .map((b) => `${b.n} ${b.label}`);
+    const convergence = report ? asRecord(report.convergence) : undefined;
+    // A mid-run aggregate legitimately has converged:false — say so instead of
+    // implying the run is over.
+    const status = convergence && convergence.converged === true ? 'converged' : 'not converged yet';
+    return (`Review report: ${total} finding${total === 1 ? '' : 's'}` +
+        (buckets.length > 0 ? ` (${buckets.join(', ')})` : '') +
+        ` — ${status}`);
+}
+/**
+ * Card headline for a `meta-review` result: the verdict plus what the audit
+ * checked (#12). Same defensive contract as {@link aggregateHeadline}.
+ */
+function metaReviewHeadline(value) {
+    const finalReport = asRecord(value.finalReport);
+    if (!finalReport)
+        return undefined;
+    const verdict = typeof finalReport.verdict === 'string' && finalReport.verdict
+        ? finalReport.verdict
+        : undefined;
+    if (!verdict)
+        return undefined;
+    const meta = asRecord(finalReport.metaReview);
+    const issues = meta && Array.isArray(meta.issues) ? meta.issues.length : undefined;
+    const checks = meta ? asNumber(meta.checksRun) : undefined;
+    const bits = [
+        issues !== undefined ? `${issues} issue${issues === 1 ? '' : 's'}` : '',
+        checks !== undefined ? `${checks} check${checks === 1 ? '' : 's'} run` : '',
+    ].filter(Boolean);
+    return `Meta-review: ${verdict}` + (bits.length > 0 ? ` (${bits.join(', ')})` : '');
+}
 export function registerReviewTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_review',
+        // Result card (#12): aggregate/meta-review results are large raw-JSON
+        // bodies — give them a readable headline (finding counts + convergence /
+        // verdict) instead of an unsummarized blob. Only these two operations
+        // get a card; `plan` keeps the default. Pure: parsed from the rendered
+        // result only (replay-safe); a shape miss declines the card.
+        presentResult: (args, result) => {
+            if (result.isError)
+                return undefined;
+            const a = args;
+            const op = a.operation;
+            if (op !== 'aggregate' && op !== 'meta-review')
+                return undefined;
+            const value = parseRenderedJson(result);
+            if (!value)
+                return undefined;
+            const title = op === 'aggregate' ? aggregateHeadline(value) : metaReviewHeadline(value);
+            return title ? { card: 'generic', title } : undefined;
+        },
         description: 'Deterministic review engine for the iterate workflow. ' +
             'Use `plan` to generate the review plan (dimensions, reviewer prompts, findings schema, round cap) ' +
             'for normal or dry-run mode. Use `aggregate` to merge raw per-round findings into a deduped, ' +
@@ -128,7 +252,7 @@ export function registerReviewTool(ctx) {
                 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 maxReviewRounds = resolveMaxReviewRounds(args.maxReviewRounds, config.max_rounds);
                     const knownIntentional = config.personalization
                         ?.known_intentional;
                     // changed-only scope: resolve the changed-file set against
@@ -169,7 +293,12 @@ export function registerReviewTool(ctx) {
                             : [];
                         return { round: typeof rr?.round === 'number' ? rr.round : 0, findings, readFiles };
                     })
-                        .filter((r) => r.round > 0);
+                        // Boundary guard: convergence is keyed on `round - 1`, so a
+                        // fractional/zero/NaN round (`1.5`, `NaN` — all passable through
+                        // the `json` argument) must never reach the deterministic core.
+                        // Mirrors the core's own `Number.isInteger(round) && round >= 1`
+                        // filter; a non-integer round is simply "not a round" here.
+                        .filter((r) => Number.isInteger(r.round) && r.round >= 1);
                     if (rounds.length === 0) {
                         return {
                             operation: 'aggregate',
@@ -177,7 +306,7 @@ export function registerReviewTool(ctx) {
                             error: 'rounds must be a non-empty array of {round, findings}.',
                         };
                     }
-                    const maxReviewRounds = args.maxReviewRounds ?? config.max_rounds ?? DEFAULT_MAX_REVIEW_ROUNDS;
+                    const maxReviewRounds = resolveMaxReviewRounds(args.maxReviewRounds, config.max_rounds);
                     const goal = args.goal ?? config.goal ?? '';
                     const dimensions = config.dimensions ?? [];
                     // Output schema validation gate (reviewer.output_schema_validation,
@@ -197,7 +326,18 @@ export function registerReviewTool(ctx) {
                         dimensions,
                         maxReviewRounds,
                         rounds: cleanRounds,
-                        knownIntentional: args.knownIntentional,
+                        // `type:'json'` passes schema validation for ANY JSON value, so a
+                        // bare string/object used to reach filterKnownIntentional →
+                        // `known.some` TypeError that escaped execute. Every sibling json
+                        // arg is guarded the same way: a non-array means "no known
+                        // entries" (identical to omitting it). The element shape reuses
+                        // triage's guard — the same one behind the config-sourced list —
+                        // so config-provided and arg-provided rows stay interchangeable.
+                        knownIntentional: Array.isArray(args.knownIntentional)
+                            ? readKnownIntentional({
+                                personalization: { known_intentional: args.knownIntentional },
+                            })
+                            : undefined,
                         fixedCount: typeof args.fixedCount === 'number' ? args.fixedCount : undefined,
                     });
                     return {
@@ -222,7 +362,18 @@ export function registerReviewTool(ctx) {
                     // 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;
+                    // READ set for the evidence verdict: `readVerified`/`readVerifiedRatio`
+                    // are only computable when the audit knows which files reviewers
+                    // actually opened, yet the tool never supplied one — so the skill
+                    // prompt's "every finding anchors to real, READ code" was
+                    // unverifiable (always null). The report already aggregates every
+                    // round's self-reported `readFiles`; wiring it through evidence.ts's
+                    // existing optional `readSet` needs no core change. An empty read
+                    // list keeps the "not checkable" (null) semantics instead of 0.0.
+                    const readSet = buildReadSet(projectRoot, source);
+                    const evidence = evidenceEnabled
+                        ? verifyFindings(projectRoot, findings, readSet ? { readSet } : {})
+                        : 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`.

package/dist/tools/transcript.js

@@ -9,10 +9,12 @@
  *                  "not found" empty view). Used each round by the workflow to
  *                  pick up steering nudges, and polled by tool-reading agents.
  *   - `capture`  — build a fresh transcript from the review `rounds` + `report`
- *                  and persist it. Called by the canonical scripts after the
- *                  final aggregate so the client always sees the latest run.
- *   - `nudge`    — set (`text`) or clear (`text: null`) steering text persisted
- *                  for the next round's reviewers to read.
+ *                  (plus the decision-log timeline) and persist it. Called by
+ *                  the canonical scripts after the final aggregate so the
+ *                  client always sees the latest run. Skipped entirely when
+ *                  `observatory.capture: false` is configured.
+ *   - `nudge`    — set (`text`) or clear (`text: null` / empty string) steering
+ *                  text persisted for the next round's reviewers to read.
  *
  * All writes are persisted to `.iterate/transcript.json` via an atomic
  * tmp+rename so a crashed writer never leaves a corrupt manifest.
@@ -24,7 +26,8 @@ import { writeTextAtomicAsync } from "../atomic-fs.js";
 import { dirname } from 'node:path';
 import { loadEffectiveConfig, resolveProjectRootForExec, } from "../config-loader.js";
 import { transcriptPath } from "../paths.js";
-import { ReviewTranscriptBuilder } from "../transcript.js";
+import { ReviewTranscriptBuilder, MAX_TIMELINE, MAX_ROUNDS, normalizeManifestBounds } from "../transcript.js";
+import { readDecisionLogDetailed } from "./decision-log.js";
 import { readLive } from "../live.js";
 /** Build per-dimension threads for one round from its (dimension-tagged) findings. */
 function captureRound(builder, round) {
@@ -98,6 +101,43 @@ function normalizeFix(input) {
         success: f.success !== false,
     };
 }
+/**
+ * Structural gate for a parsed `.iterate/transcript.json` payload.
+ *
+ * `JSON.parse` accepts `null`, `[]`, `{}` … — parseable values that are NOT
+ * manifests; the read path used to return them as `found: true`. Only a
+ * payload carrying the builder's field layout is accepted here (the ROOT
+ * gate); row-level bounds and values are then re-normalized on the way out by
+ * {@link normalizeManifestBounds}, so an older but still renderable manifest
+ * is shown instead of blanked — and a hostile one is bounded instead of
+ * passed through.
+ *
+ * Deliberately does NOT rehydrate through the builder for normalization:
+ * `rehydrateBuilder(...).serialize()` drops fields the builder cannot rebuild
+ * (notably `phases`), so a plain read would silently rewrite history.
+ */
+function isManifestShaped(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const m = value;
+    if (typeof m.version !== 'number' || typeof m.project !== 'string' || typeof m.active !== 'boolean') {
+        return false;
+    }
+    if (!Array.isArray(m.rounds) ||
+        !Array.isArray(m.convergence) ||
+        !Array.isArray(m.findings) ||
+        !Array.isArray(m.fixes) ||
+        !Array.isArray(m.timeline)) {
+        return false;
+    }
+    // Rows must be objects (round rows with a numeric index): a manifest whose
+    // rows are `null`/`"x"` is structurally broken, not merely old.
+    return (m.rounds.every((r) => !!r && typeof r === 'object' && typeof r.round === 'number') &&
+        m.convergence.every((n) => typeof n === 'number') &&
+        m.findings.every((f) => !!f && typeof f === 'object') &&
+        m.fixes.every((f) => !!f && typeof f === 'object') &&
+        m.timeline.every((e) => !!e && typeof e === 'object'));
+}
 /** Register the `iterate_transcript` tool. */
 export function registerTranscriptTool(ctx) {
     ctx.tools.register(defineTool({
@@ -108,10 +148,13 @@ export function registerTranscriptTool(ctx) {
         description: 'Runtime-observatory transcript for the iterate workflow. ' +
             '`read` returns the current persisted transcript manifest (per-reviewer threads, ' +
             'convergence series, findings, fixes, checkpoint, timeline, and any steering nudge ' +
-            'written for the next round). ' +
-            '`capture` builds a fresh transcript from the review `rounds` + `report` and persists it ' +
-            '(call once after the final aggregate so the UI reflects the run). ' +
-            '`nudge` sets (text) or clears (text:null) steering text the next round\'s reviewers read. ' +
+            'written for the next round) — or, when the file is missing/malformed, a structured ' +
+            'empty view (`found:false` plus a blank manifest). ' +
+            '`capture` builds a fresh transcript from the review `rounds` + `report`, folds in the ' +
+            'decision-log timeline, and persists it (call once after the final aggregate so the UI ' +
+            'reflects the run; skipped when `observatory.capture` is disabled). Round validation outcomes ' +
+            'can be carried on capture via `validations` ({round, command, exitCode, allowed, rejectReason?}). ' +
+            '`nudge` sets (text) or clears (text:null or an empty string) steering text the next round\'s reviewers read. ' +
             'Purely local and deterministic — never touches source files.',
         parameters: {
             operation: {
@@ -147,9 +190,26 @@ export function registerTranscriptTool(ctx) {
                 type: 'json',
                 description: 'For `capture`: array of applied fixes [{id, file, round, summary, linesAdded, linesRemoved, success}].',
             },
+            validations: {
+                type: 'json',
+                description: 'For `capture`: per-round validation outcomes [{round, command, exitCode:number|null, allowed:boolean, rejectReason?}] — ' +
+                    'the exact commands run by iterate_validate with their exit codes. Malformed rows are dropped, ' +
+                    'out-of-range rounds clamped, and the list capped (newest kept). Pass every round\'s validate results so ' +
+                    'the run console can show which commands ran and whether they passed.',
+            },
             refReadFiles: { type: 'json', description: 'For `capture`: flat array of all read files across rounds (optional).' },
             stoppedReason: { type: 'string', description: 'For `capture`: why the run ended — "converged" | "max_rounds_reached" | "aborted_by_validation" | "aborted_by_config" | "schema_invalid" | "no_usable_reviewer_output" | "inconclusive". When omitted, derived from the convergence trend (trailing 0 = converged, otherwise = max_rounds_reached once a round ran).' },
-            text: { type: 'string', description: 'For `nudge`: steering text to set (or null to clear).' },
+            // `string | null` (NOT plain `type: 'string'`): dsh validates arguments
+            // against the compiled schema BEFORE execute, and the docs — plus the
+            // client's clear button — advertise `{"operation":"nudge","text":null}`.
+            // Under `type: 'string'` that call always failed validation, so the
+            // advertised clear flow could never run. Probed against the installed
+            // dsh-tools validator: `oneOf[string,null]` accepts null + string and
+            // still rejects numbers (`type:'json'` would have accepted those too).
+            text: {
+                oneOf: [{ type: 'string' }, { type: 'null' }],
+                description: 'For `nudge`: steering text to set. `null` (or an empty/whitespace-only string) clears the stored nudge.',
+            },
             path: { type: 'string', description: 'Project root directory (default: current working directory).' },
         },
         output: {
@@ -162,6 +222,11 @@ export function registerTranscriptTool(ctx) {
                     transcript: { type: 'json' },
                     live: { type: 'json', description: 'Recent live reviewer-activity entries (newest first).' },
                     updated: { type: 'boolean' },
+                    skipped: {
+                        type: 'boolean',
+                        description: 'For `capture`: true when nothing was persisted because `observatory.capture` is disabled.',
+                    },
+                    reason: { type: 'string', description: 'For a skipped `capture`: why persistence was skipped.' },
                     error: { type: 'string' },
                 },
             },
@@ -177,34 +242,50 @@ export function registerTranscriptTool(ctx) {
             const approval = config.observatory?.approval ?? 'ask';
             if (args.operation === 'read') {
                 const live = await readLive(projectRoot);
-                if (!existsSync(file)) {
-                    return {
-                        operation: 'read',
-                        found: false,
-                        live: live,
-                        transcript: new ReviewTranscriptBuilder({
-                            project: projectRoot,
-                            approval,
-                        }).serialize(),
-                    };
-                }
+                // Every "no usable manifest" outcome (missing file, unparseable JSON,
+                // parseable-but-wrong-shape JSON) returns the SAME structured
+                // not-found view: `found:false` plus an empty manifest. The client's
+                // F1–F7 tabs read `transcript.<field>` unconditionally, so the old
+                // bare `{found:false, error}` parse-error branch blanked the panel.
+                const emptyView = () => ({
+                    operation: 'read',
+                    found: false,
+                    live: live,
+                    transcript: new ReviewTranscriptBuilder({
+                        project: projectRoot,
+                        approval,
+                    }).serialize(),
+                });
+                if (!existsSync(file))
+                    return emptyView();
+                let parsed;
                 try {
-                    const raw = await readFile(file, 'utf-8');
-                    const parsed = JSON.parse(raw);
-                    return {
-                        operation: 'read',
-                        found: true,
-                        live: live,
-                        transcript: parsed,
-                    };
+                    parsed = JSON.parse(await readFile(file, 'utf-8'));
                 }
                 catch (err) {
                     return {
-                        operation: 'read',
-                        found: false,
+                        ...emptyView(),
                         error: `Failed to read transcript: ${err instanceof Error ? err.message : String(err)}`,
                     };
                 }
+                if (!isManifestShaped(parsed)) {
+                    // `JSON.parse` happily accepts `null`, `[]` and `{}` — values that
+                    // are parseable but carry no manifest. Surfacing them as
+                    // `found:true` made the observatory render junk panels.
+                    return {
+                        ...emptyView(),
+                        error: 'Transcript file is not a valid manifest; returning an empty view.',
+                    };
+                }
+                return {
+                    operation: 'read',
+                    found: true,
+                    live: live,
+                    // Defensive normalization (bounded rows + sanitized field values)
+                    // so a hand-edited/hostile manifest is never handed to the client
+                    // raw — same normalizers/caps the builder applies at capture time.
+                    transcript: normalizeManifestBounds(parsed),
+                };
             }
             if (args.operation === 'nudge') {
                 let manifest = null;
@@ -255,6 +336,18 @@ export function registerTranscriptTool(ctx) {
                 };
             }
             // capture
+            // `observatory.capture: false` opts the project out of transcript
+            // persistence entirely. Only an EXPLICIT false skips: an unreadable or
+            // missing config falls back to the defaults (capture on), so a broken
+            // config can never silently blind the observatory.
+            if (config.observatory?.capture === false) {
+                return {
+                    operation: 'capture',
+                    updated: false,
+                    skipped: true,
+                    reason: 'observatory.capture is disabled',
+                };
+            }
             const mode = args.mode === 'normal' ? 'normal' : 'dry-run';
             const taskMode = args.taskMode === 'code' || args.taskMode === 'iterate' ? args.taskMode : undefined;
             const goal = typeof args.goal === 'string' ? args.goal : '';
@@ -287,15 +380,45 @@ export function registerTranscriptTool(ctx) {
                 for (const [dim, list] of byDim)
                     builder.reviewerSnapshot(dim, list, readFiles);
             }
-            // Convergence series from the report (position per round).
-            for (let i = 0; i < convergence.length; i += 1) {
+            // Convergence series from the report (position per round). The rehydrate
+            // path already refuses negative/non-finite counts; capture must not be
+            // the asymmetric back door that persists a hostile `-3` into the F2
+            // trend (a non-number entry was already skipped; `Number.isFinite`
+            // additionally rejects NaN, which `typeof NaN === 'number'` admits).
+            // Truncate at MAX_ROUNDS on the FEED side: `snapshotConvergence` clamps
+            // an over-cap round to the last slot, so feeding 1000+ entries would
+            // silently FOLD every extra round into slot 1000 (one value winning).
+            for (let i = 0; i < Math.min(convergence.length, MAX_ROUNDS); i += 1) {
                 const n = convergence[i];
-                if (typeof n === 'number')
+                if (typeof n === 'number' && Number.isFinite(n) && n >= 0)
                     builder.snapshotConvergence(i + 1, n);
             }
             const roundsExecuted = typeof args.roundsExecuted === 'number' ? Math.floor(args.roundsExecuted) : rounds.length;
+            // Advance the round MARKER only — never `roundStart`, which would
+            // pre-create phantom EMPTY round rows for rounds we captured no data
+            // for (a resumed run reports `roundsExecuted` above the rounds with
+            // captured findings). advanceRound also refuses to rewind below the
+            // last captured round.
             if (roundsExecuted > 0)
-                builder.roundStart(roundsExecuted, maxRounds);
+                builder.advanceRound(roundsExecuted, maxRounds);
+            // F7 timeline: the decision log is the source of truth for what the run
+            // decided, and the tool docs promise a captured `timeline`. Without
+            // folding it in, `manifest.timeline` was ALWAYS empty on capture (the
+            // builder's decision() ran only during nudge rehydration), so the
+            // client's F7 tab rendered nothing even for a run with a full audit
+            // trail. Feed only the builder's cap worth — the builder evicts oldest
+            // first anyway, and slicing first saves a clone per dropped entry.
+            // Fail-safe: an unreadable/corrupt log must never break the capture —
+            // the transcript is a UI projection, the log stays the primary record.
+            try {
+                const { entries } = readDecisionLogDetailed(projectRoot);
+                for (const e of entries.slice(-MAX_TIMELINE))
+                    builder.decision(e);
+            }
+            catch {
+                // readDecisionLogDetailed already skips corrupt lines; this catch
+                // covers an unexpected reader failure (unreadable dir, EACCES …).
+            }
             builder.recordCheckpoint(normalizeCheckpoint(args.checkpoint));
             if (Array.isArray(args.fixes)) {
                 for (const fx of args.fixes) {
@@ -304,6 +427,15 @@ export function registerTranscriptTool(ctx) {
                         builder.fix(record);
                 }
             }
+            // Validation outcomes (contract with the client run console):
+            // [{round, command, exitCode, allowed, rejectReason?}]. The builder
+            // normalizes every row defensively (bad rows dropped, rounds clamped,
+            // capped newest-wins), so a hostile/malformed payload can neither
+            // crash the capture nor persist junk.
+            if (Array.isArray(args.validations)) {
+                for (const v of args.validations)
+                    builder.validation(v);
+            }
             // End state: an explicit stoppedReason wins; otherwise derive it from
             // the trend. A run that settled closes as "converged"; a run that did
             // real work but never trended to 0 closes as "max_rounds_reached";
@@ -364,7 +496,7 @@ function rehydrateBuilder(manifest, approval) {
             });
         }
     }
-    for (let idx = 0; idx < (manifest.convergence ?? []).length; idx += 1) {
+    for (let idx = 0; idx < Math.min((manifest.convergence ?? []).length, MAX_ROUNDS); idx += 1) {
         const n = manifest.convergence[idx];
         if (typeof n === 'number' && n >= 0)
             builder.snapshotConvergence(idx + 1, n);
@@ -374,6 +506,11 @@ function rehydrateBuilder(manifest, approval) {
     if (Array.isArray(manifest.fixes))
         for (const fx of manifest.fixes)
             builder.fix(fx);
+    // Validation rows survive a nudge-edit re-persist (same defensive
+    // normalization as capture — a hand-edited manifest is re-clamped here).
+    if (Array.isArray(manifest.validations))
+        for (const v of manifest.validations)
+            builder.validation(v);
     if (Array.isArray(manifest.timeline))
         for (const e of manifest.timeline)
             builder.decision(e);