iterate-plugin 3.5.7 → 3.7.0

package/src/tools/review.ts

@@ -7,9 +7,12 @@ import {
   buildReviewReport,
   sanitizeRounds,
   validateRoundsSchema,
+  MAX_REVIEW_ROUNDS_CAP,
 } from '../review.ts'
 import { buildFinalReviewReport, metaReviewReport } from '../meta-review.ts'
-import { evidenceToPlain, verifyFindings } from '../evidence.ts'
+import { evidenceToPlain, resolveWithin, verifyFindings } from '../evidence.ts'
+import { readKnownIntentional } from './triage.ts'
+import { asNumber, asRecord, parseRenderedJson } from './present.ts'
 import {
   collectScopeFiles,
   computeCoverage,
@@ -22,6 +25,63 @@ import type { CoverageResult } from '../review-scope.ts'
 /** 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: unknown, configMax: unknown): number {
+  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: string, report: ReviewReport): Set<string> | undefined {
+  const raw: unknown[] = []
+  if (Array.isArray(report.readFiles)) {
+    raw.push(...report.readFiles)
+  } else if (Array.isArray(report.rounds)) {
+    for (const r of report.rounds) {
+      const files = (r as { readFiles?: unknown } | null | undefined)?.readFiles
+      if (Array.isArray(files)) raw.push(...files)
+    }
+  }
+  const set = new Set<string>()
+  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.
  *
@@ -35,10 +95,72 @@ 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: Record<string, unknown>): string | undefined {
+  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'] as const)
+    .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: Record<string, unknown>): string | undefined {
+  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: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
   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 as { operation?: unknown }
+        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) ' +
@@ -155,7 +277,7 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
         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 as { known_intentional?: KnownIntentional[] } | undefined)
             ?.known_intentional
           // changed-only scope: resolve the changed-file set against
@@ -200,7 +322,12 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
                 : []
               return { round: typeof rr?.round === 'number' ? rr.round : 0, findings, readFiles }
             })
-            .filter((r: ReviewRound) => 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: ReviewRound) => Number.isInteger(r.round) && r.round >= 1)
 
           if (rounds.length === 0) {
             return {
@@ -210,7 +337,7 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
             }
           }
 
-          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 ?? []
 
@@ -232,7 +359,18 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
             dimensions,
             maxReviewRounds,
             rounds: cleanRounds,
-            knownIntentional: args.knownIntentional as KnownIntentional[] | undefined,
+            // `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 {
@@ -258,7 +396,18 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
           // verdict. Disable via config `reviewer.evidence_validation: false`.
           const evidenceEnabled = config.reviewer?.evidence_validation !== false
           const findings: ReviewFinding[] = 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/src/tools/transcript.ts

@@ -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.
@@ -29,7 +31,8 @@ import {
   resolveProjectRootForExec,
 } from '../config-loader.ts'
 import { transcriptPath } from '../paths.ts'
-import { ReviewTranscriptBuilder } from '../transcript.ts'
+import { ReviewTranscriptBuilder, MAX_TIMELINE, MAX_ROUNDS, normalizeManifestBounds } from '../transcript.ts'
+import { readDecisionLogDetailed } from './decision-log.ts'
 import { readLive } from '../live.ts'
 import type {
   TranscriptManifest,
@@ -106,6 +109,47 @@ function normalizeFix(input: unknown): TranscriptFix | null {
   }
 }
 
+/**
+ * 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: unknown): value is TranscriptManifest {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+  const m = value as Record<string, unknown>
+  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 as { round?: unknown }).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: {
   tools: { register: (def: ReturnType<typeof defineTool>) => void }
@@ -120,10 +164,13 @@ export function registerTranscriptTool(ctx: {
         '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: {
@@ -159,9 +206,27 @@ 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).' },
       },
 
@@ -175,6 +240,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' },
           },
         },
@@ -191,33 +261,53 @@ export function registerTranscriptTool(ctx: {
 
         if (args.operation === 'read') {
           const live = await readLive(projectRoot)
-          if (!existsSync(file)) {
-            return {
-              operation: 'read',
-              found: false,
-              live: live as unknown as JsonValue,
-              transcript: new ReviewTranscriptBuilder({
-                project: projectRoot,
-                approval,
-              }).serialize() as unknown as JsonValue,
-            }
-          }
+          // 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: JsonValue
+            transcript: JsonValue
+          } => ({
+            operation: 'read',
+            found: false,
+            live: live as unknown as JsonValue,
+            transcript: new ReviewTranscriptBuilder({
+              project: projectRoot,
+              approval,
+            }).serialize() as unknown as JsonValue,
+          })
+          if (!existsSync(file)) return emptyView()
+          let parsed: unknown
           try {
-            const raw = await readFile(file, 'utf-8')
-            const parsed = JSON.parse(raw) as unknown as TranscriptManifest
-            return {
-              operation: 'read',
-              found: true,
-              live: live as unknown as JsonValue,
-              transcript: parsed as unknown as JsonValue,
-            }
+            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 as unknown as JsonValue,
+            // 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) as unknown as JsonValue,
+          }
         }
 
         if (args.operation === 'nudge') {
@@ -267,6 +357,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 : ''
@@ -301,14 +403,43 @@ 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') builder.snapshotConvergence(i + 1, n)
+          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
-        if (roundsExecuted > 0) builder.roundStart(roundsExecuted, maxRounds)
+        // 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.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)) {
@@ -317,6 +448,14 @@ export function registerTranscriptTool(ctx: {
             if (record) 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";
@@ -377,12 +516,15 @@ function rehydrateBuilder(manifest: TranscriptManifest, approval: 'ask' | 'deny'
       })
     }
   }
-  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)
   }
   if (manifest.checkpoint) builder.recordCheckpoint(manifest.checkpoint)
   if (Array.isArray(manifest.fixes)) for (const fx of manifest.fixes) builder.fix(fx as TranscriptFix)
+  // 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)
   builder.setNudge(manifest.nudge?.text ?? null)
   if (!manifest.active) builder.finish(manifest.stoppedReason ?? undefined)