iterate-plugin 3.5.6 → 3.6.0

package/dist/tools/triage.js

@@ -4,16 +4,29 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import yaml from 'js-yaml';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { writeTextAtomic } from "../atomic-fs.js";
+import { configBackupSuffix } from "../config-write.js";
+import { WHOLE_FILE_LINE } from "../evidence.js";
 const CONFIG_FILE = 'iterate.config.yaml';
 /** Personalization key that holds the known-intentional list. */
 const PERSONALIZATION_KEY = 'personalization';
 const KNOWN_INTENTIONAL_KEY = 'known_intentional';
 /** Max entries per single `apply` call. */
 const MAX_ENTRIES = 500;
+/**
+ * TOTAL cap on `personalization.known_intentional`.
+ *
+ * `MAX_ENTRIES` only bounds one `apply` payload, so the list itself grew
+ * without limit across sessions — every review round then ran
+ * `filterKnownIntentional` as O(findings × entries) over an ever-longer list,
+ * and the config file (backed up on every write) grew with it. Merges now
+ * evict the OLDEST entries (list order is write order — incoming entries are
+ * appended) beyond this bound and report how many were dropped.
+ */
+export const MAX_TOTAL_KNOWN_INTENTIONAL = 1000;
 /** How many timestamped config backups are retained (older ones are removed). */
 export const MAX_TRIAGE_BACKUPS = 5;
-/** Whole-file marker line (matches review.ts filterKnownIntentional semantics). */
-const WHOLE_FILE_LINE = 0;
+/** Whole-file marker line — the shared constant from evidence.ts (also used by
+ *  review-scope/filterKnownIntentional), so every consumer agrees on `0`. */
 // ─── Pure helpers (exported for unit tests) ─────────────────────────────────
 /**
  * Normalize a caller-supplied `line` value.
@@ -86,11 +99,15 @@ export function entryKey(entry) {
 /**
  * Merge incoming entries into the existing known-intentional list.
  * Existing entries are never mutated; incoming entries whose key already
- * exists are skipped. Returns the merged list plus add/skip counts.
+ * exists are skipped. The result is then bounded by
+ * {@link MAX_TOTAL_KNOWN_INTENTIONAL}: the list is append-ordered, so when a
+ * merge overflows, the entries at the FRONT (the oldest ones) are evicted and
+ * counted in `dropped` — the caller reports that number instead of silently
+ * losing verdicts.
  *
  * @param {KnownIntentional[]} existing
  * @param {KnownIntentional[]} incoming
- * @returns {{ merged: KnownIntentional[], added: number, skipped: number }}
+ * @returns {{ merged: KnownIntentional[], added: number, skipped: number, dropped: number }}
  */
 export function mergeKnownIntentional(existing, incoming) {
     const seen = new Set();
@@ -114,7 +131,16 @@ export function mergeKnownIntentional(existing, incoming) {
         merged.push(entry);
         added++;
     }
-    return { merged, added, skipped };
+    // Total bound: evict oldest-first. Incoming entries sit at the END of
+    // `merged`, so they survive — a session cannot evict its own fresh verdicts
+    // by overflowing the list, and one apply adds at most MAX_ENTRIES entries,
+    // which bounds how far a single merge can overshoot the cap.
+    let dropped = 0;
+    if (merged.length > MAX_TOTAL_KNOWN_INTENTIONAL) {
+        dropped = merged.length - MAX_TOTAL_KNOWN_INTENTIONAL;
+        merged.splice(0, dropped);
+    }
+    return { merged, added, skipped, dropped };
 }
 /**
  * Build a NEW config object with `personalization.known_intentional` set to
@@ -146,10 +172,15 @@ export function readKnownIntentional(config) {
         typeof e === 'object' &&
         typeof e.file === 'string');
 }
-/** Build a filesystem-safe backup suffix from the current time. */
-export function backupSuffix(now = new Date()) {
-    return now.toISOString().replace(/[:.]/g, '-');
-}
+/**
+ * Build a filesystem-safe backup suffix from the current time.
+ *
+ * Re-exported from config-write: BOTH writers back up `iterate.config.yaml`,
+ * and the shared implementation carries the same-millisecond collision guard
+ * (two backups created in the same ms used to produce the identical
+ * `config.bak-…` path, so the second silently overwrote the first).
+ */
+export const backupSuffix = configBackupSuffix;
 /**
  * Bound the timestamped config backups: after a fresh one is written, delete
  * every older `config.bak-*` file beyond the newest `keep`. Best-effort — a
@@ -205,7 +236,7 @@ function applyEntries(projectRoot, incoming) {
         return { ok: false, error: `Failed to read config: ${String(err)}` };
     }
     const existing = readKnownIntentional(config);
-    const { merged, added, skipped } = mergeKnownIntentional(existing, incoming);
+    const { merged, added, skipped, dropped } = mergeKnownIntentional(existing, incoming);
     const nextConfig = buildConfigWithKnownIntentional(config, merged);
     const hadFile = existsSync(configPath);
     const backupPath = hadFile ? `${configPath}.bak-${backupSuffix()}` : null;
@@ -247,7 +278,7 @@ function applyEntries(projectRoot, incoming) {
     // project never collects an unbounded pile of config snapshots.
     if (backupPath)
         pruneOldConfigBackups(configPath);
-    return { ok: true, added, skipped, count: merged.length, configPath, backupPath };
+    return { ok: true, added, skipped, dropped, count: merged.length, configPath, backupPath };
 }
 /**
  * Register the `iterate_triage` tool.
@@ -266,13 +297,31 @@ function applyEntries(projectRoot, incoming) {
 export function registerTriageTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_triage',
+        // Pending-call card (#12): `apply` rewrites iterate.config.yaml (with
+        // backup + rollback) — it must read as a config write, not a read, and
+        // name how many entries it will merge. `list` is a plain read and keeps
+        // the default presentation. Pure: derived from args only.
+        presentCall: (args) => {
+            const a = args;
+            if (a.operation !== 'apply')
+                return undefined;
+            const count = Array.isArray(a.entries) ? a.entries.length : 0;
+            return {
+                card: 'generic',
+                title: count > 0
+                    ? `Apply ${count} known_intentional ${count === 1 ? 'entry' : 'entries'} to iterate.config.yaml`
+                    : 'Apply known_intentional entries to iterate.config.yaml',
+                kind: 'edit',
+            };
+        },
         // `list` is a pure config read; `apply` rewrites iterate.config.yaml →
         // only list joins a parallel dispatch group.
         isConcurrencySafe: (args) => args.operation === 'list',
         description: 'Manage `personalization.known_intentional` entries in iterate.config.yaml. ' +
             'Use `apply` to write back triage verdicts (entries where the reviewer said "known intentional") so ' +
             'future review rounds filter them out. Entries are deduped by file|dimension|line and the config is ' +
-            'backed up before writing. Use `list` to read the current entries. ' +
+            'backed up before writing. The list is capped at 1000 entries — when a merge overflows it, the OLDEST ' +
+            'entries are evicted and the result reports `dropped`. Use `list` to read the current entries. ' +
             'The client browser cannot write files, so this tool is the write-back channel for the triage panel.',
         parameters: {
             operation: {
@@ -301,6 +350,8 @@ export function registerTriageTool(ctx) {
                     operation: { type: 'string', required: true },
                     added: { type: 'integer' },
                     skipped: { type: 'integer' },
+                    /** Entries evicted from the FRONT of the list (total cap hit). */
+                    dropped: { type: 'integer' },
                     count: { type: 'integer' },
                     path: { type: 'string' },
                     backupPath: { oneOf: [{ type: 'string' }, { type: 'null' }] },
@@ -360,6 +411,10 @@ export function registerTriageTool(ctx) {
                     operation: 'apply',
                     added: result.added,
                     skipped: result.skipped,
+                    // Surface the overflow count: a merge that hit the total cap
+                    // evicted the OLDEST entries, and the caller must be able to see
+                    // how many verdicts were dropped instead of silently losing them.
+                    dropped: result.dropped,
                     count: result.count,
                     path: result.configPath,
                     backupPath: result.backupPath ?? null,

package/dist/tools/validate.js

@@ -5,6 +5,8 @@ const DEFAULT_TIMEOUT_MS = 120_000;
 /** Hard ceiling on a single validation command's runtime, so a model cannot
  *  pin the tool open indefinitely via an unbounded `timeout` argument. */
 const MAX_TIMEOUT_MS = 600_000;
+/** Default cap on a validation command's captured stdout+stderr (10 MB). */
+const DEFAULT_MAX_BUFFER = 10 * 1024 * 1024;
 /**
  * Clamp a caller-supplied timeout (ms) to a sane range.
  * Non-finite / non-positive values fall back to the default; any value above
@@ -25,35 +27,70 @@ export function clampTimeout(ms) {
  * instead of pinning the dispatch open until the timeout elapses. The result
  * distinguishes "cancelled by the caller" (`canceled: true`) from "ran past
  * `timeoutMs`" (`timedOut: true`).
+ *
+ * `maxBuffer` is injectable for tests (defaults to the production 10 MB cap);
+ * hitting it sets `truncated: true` so callers can report the cut output
+ * instead of silently returning a partial stream.
+ *
+ * Never rejects: `exec()` validates its arguments synchronously and can THROW
+ * before registering its callback (a NUL byte in the command raises
+ * ERR_INVALID_ARG_VALUE). Inside a promise executor that throw would reject
+ * the promise and escape `execute` unguarded, so it is caught and resolved as
+ * a `startError` result instead.
  */
-export async function runCommand(command, cwd, timeoutMs, signal) {
+export async function runCommand(command, cwd, timeoutMs, signal, maxBuffer = DEFAULT_MAX_BUFFER) {
     const start = performance.now();
     return new Promise((resolve) => {
-        exec(command, {
-            cwd,
-            timeout: timeoutMs,
-            maxBuffer: 10 * 1024 * 1024, // 10 MB
-            env: { ...process.env, PAGER: 'cat' },
-            signal,
-        }, (error, stdout, stderr) => {
-            const durationMs = Math.round(performance.now() - start);
-            // error.code is the exit code when the command ran; when the binary
-            // cannot be spawned Node sets error.code to a STRING ('ENOENT' etc).
-            // Coerce to a number so the integer output schema is never violated.
-            const exitCode = typeof error?.code === 'number' ? error.code : (error ? 1 : 0);
-            const canceled = signal?.aborted === true;
+        try {
+            exec(command, {
+                cwd,
+                timeout: timeoutMs,
+                maxBuffer,
+                env: { ...process.env, PAGER: 'cat' },
+                signal,
+            }, (error, stdout, stderr) => {
+                const durationMs = Math.round(performance.now() - start);
+                // error.code is the exit code when the command ran; when the binary
+                // cannot be spawned Node sets error.code to a STRING ('ENOENT' etc).
+                // Coerce to a number so the integer output schema is never violated.
+                const exitCode = typeof error?.code === 'number' ? error.code : (error ? 1 : 0);
+                const canceled = signal?.aborted === true;
+                // maxBuffer overflow: error.code is the STRING
+                // 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' and stdout/stderr were cut
+                // short — flag it instead of reporting a plain exit-1 with silently
+                // truncated output. @types/node types ExecException.code as
+                // number|undefined, so widen to unknown for the runtime comparison.
+                const errorCode = error?.code;
+                const truncated = errorCode === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER';
+                resolve({
+                    command,
+                    exitCode,
+                    stdout: stdout ?? '',
+                    stderr: stderr ?? '',
+                    // A caller cancellation also kills the child (killed === true), but
+                    // that is not a timeout — only report timedOut for the deadline path.
+                    timedOut: error?.killed === true && !canceled,
+                    canceled,
+                    durationMs,
+                    truncated,
+                });
+            });
+        }
+        catch (err) {
+            // Synchronous exec() throw (invalid command string, e.g. a NUL byte):
+            // resolve a structured "never started" failure rather than rejecting.
             resolve({
                 command,
-                exitCode,
-                stdout: stdout ?? '',
-                stderr: stderr ?? '',
-                // A caller cancellation also kills the child (killed === true), but
-                // that is not a timeout — only report timedOut for the deadline path.
-                timedOut: error?.killed === true && !canceled,
-                canceled,
-                durationMs,
+                exitCode: 1,
+                stdout: '',
+                stderr: String(err),
+                timedOut: false,
+                canceled: false,
+                durationMs: Math.round(performance.now() - start),
+                truncated: false,
+                startError: String(err?.message ?? err),
             });
-        });
+        }
     });
 }
 /**
@@ -109,6 +146,10 @@ export function registerValidateTool(ctx) {
                     timedOut: { type: 'boolean', required: true },
                     canceled: { type: 'boolean', required: true },
                     durationMs: { type: 'integer', required: true },
+                    truncated: {
+                        type: 'boolean',
+                        description: 'true when command output exceeded the maxBuffer cap and was cut short.',
+                    },
                     rejectReason: { type: 'string' },
                 },
             },
@@ -122,6 +163,12 @@ export function registerValidateTool(ctx) {
                             `Duration: ${value.durationMs}ms`,
                             value.timedOut ? '⚠ Timed out' : '',
                             value.canceled ? '⚠ Cancelled before completion' : '',
+                            // A truncated run still reports its (partial) output — the
+                            // reader must be told the stream was cut, otherwise the
+                            // missing tail reads as "no output".
+                            value.truncated
+                                ? `⚠ ${value.rejectReason ?? 'Output truncated: maxBuffer limit exceeded.'}`
+                                : '',
                             '',
                             value.stdout ? `[stdout]\n${value.stdout}` : '',
                             value.stderr ? `[stderr]\n${value.stderr}` : '',
@@ -186,7 +233,51 @@ export function registerValidateTool(ctx) {
                         `Allowed commands: ${predefinedCommands.join(' | ')}`,
                 };
             }
-            const result = await runCommand(args.command, projectRoot, timeout, exec.signal);
+            const result = await (async () => {
+                try {
+                    return await runCommand(args.command, projectRoot, timeout, exec.signal);
+                }
+                catch (err) {
+                    // runCommand resolves its own start failures; this guard exists so
+                    // NO unexpected rejection can escape `execute` as an unhandled tool
+                    // crash (the tool contract is a structured result, always).
+                    return {
+                        command: args.command,
+                        exitCode: 1,
+                        stdout: '',
+                        stderr: String(err),
+                        timedOut: false,
+                        canceled: false,
+                        durationMs: 0,
+                        truncated: false,
+                        startError: String(err?.message ?? err),
+                    };
+                }
+            })();
+            // exec() refused the command before it ever ran (e.g. a NUL byte in a
+            // whitelisted command string): the command never started, so this is a
+            // structured failure — exit 1 + a rejectReason naming the cause — not a
+            // run that merely exited non-zero.
+            if (result.startError !== undefined) {
+                return {
+                    allowed: false,
+                    command: args.command,
+                    exitCode: 1,
+                    stdout: '',
+                    stderr: result.stderr,
+                    timedOut: false,
+                    canceled: false,
+                    durationMs: result.durationMs,
+                    rejectReason: `command failed to start: ${result.startError}`,
+                };
+            }
+            if (result.truncated === true) {
+                return {
+                    allowed: true,
+                    ...result,
+                    rejectReason: `command output exceeded the ${Math.round(DEFAULT_MAX_BUFFER / (1024 * 1024))} MB maxBuffer limit and was truncated`,
+                };
+            }
             return {
                 allowed: true,
                 ...result,

package/dist/transcript.js

@@ -11,6 +11,8 @@
  *   - F5  — checkpoint summary (resume).
  *   - F6  — nudge channel (steer the next round).
  *   - F7  — append-only decision timeline.
+ *   - validations — per-round validation outcomes (command / exitCode /
+ *     allowed) for the run console; see {@link TranscriptValidation}.
  *
  * It performs NO I/O and NEVER touches the filesystem — persistence lives in
  * the `iterate_transcript` tool. Inputs are defensively normalized so a
@@ -31,14 +33,22 @@ const MAX_FINDINGS_PER_THREAD = 100;
 /** Max global findings kept in the manifest. */
 const MAX_FINDINGS_TOTAL = 2000;
 /** Max timeline entries kept (newest wins). */
-const MAX_TIMELINE = 500;
+export const MAX_TIMELINE = 500;
 /** Max applied-fix records kept (newest wins; bounded so a long run cannot
  *  grow the manifest payload without limit). */
 const MAX_FIXES = 200;
+/** Max validation rows kept (newest wins; bounds a very long run's payload). */
+const MAX_VALIDATIONS = 500;
 /** Max round number accepted by the builder. A model-authored/manifest-backed
  *  round value is attacker-influenced JSON: `roundStart(1e9)` / `snapshotConvergence`
- *  would otherwise preallocate arrays of that size and OOM the host. */
-const MAX_ROUNDS = 1000;
+ *  would otherwise preallocate arrays of that size and OOM the host.
+ *  Exported so the capture/rehydrate FEED side can truncate before feeding
+ *  (a value above the cap would otherwise be folded into the last slot). */
+export const MAX_ROUNDS = 1000;
+/** Max threads restored per round from a persisted manifest (the live cap plus
+ *  headroom for the single overflow thread). Shared by {@link ReviewTranscriptBuilder.restoreThread}
+ *  and the read-side normalizer so both bound hostile manifests identically. */
+export const MAX_THREADS_RESTORED = MAX_THREADS_PER_ROUND * 2 + 1;
 /** Thresholds applied when reducing a string list under a cap. */
 function clampStringList(source, cap) {
     const out = [];
@@ -97,6 +107,40 @@ function normalizeFinding(input) {
         acknowledged: typeof f.acknowledged === 'boolean' ? f.acknowledged : undefined,
     };
 }
+/**
+ * Normalize one validation row (`capture` `validations` contract), dropping
+ * rows that cannot identify WHAT was run and clamping the rest — the same
+ * defensive style as the round/fix normalizers, because these values arrive
+ * from a `type:'json'` argument a model authored.
+ *
+ *   - a non-object row, a missing/non-finite round (≤ 0 after flooring), or
+ *     a missing/blank command → dropped (there is nothing to attribute);
+ *   - `round` above the builder cap → clamped (never dropped: the row is real);
+ *   - `exitCode` → integer, or `null` when absent/unknown/not a number;
+ *   - `allowed` → strict boolean; an ABSENT flag degrades to `false` (fail
+ *     closed: a row that cannot prove it was allow-listed reads as rejected);
+ *   - `rejectReason` → trimmed string, omitted when blank.
+ */
+function normalizeValidation(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return null;
+    const v = input;
+    const rawRound = typeof v.round === 'number' && Number.isFinite(v.round) ? Math.floor(v.round) : 0;
+    if (rawRound <= 0)
+        return null;
+    const command = typeof v.command === 'string' ? v.command.trim() : '';
+    if (!command)
+        return null;
+    const exitCode = typeof v.exitCode === 'number' && Number.isFinite(v.exitCode) ? Math.floor(v.exitCode) : null;
+    const rejectReason = typeof v.rejectReason === 'string' && v.rejectReason.trim() ? v.rejectReason.trim() : undefined;
+    return {
+        round: Math.min(rawRound, MAX_ROUNDS),
+        command,
+        exitCode,
+        allowed: v.allowed === true,
+        ...(rejectReason ? { rejectReason } : {}),
+    };
+}
 /**
  * Append one raw finding to a thread's list, bound to MAX_FINDINGS_PER_THREAD
  * with NEWEST-WINS eviction (drop the oldest findings once the cap is hit).
@@ -140,6 +184,7 @@ export class ReviewTranscriptBuilder {
     globalFindings = [];
     globalSeenKeys = new Set();
     fixes = [];
+    validations = [];
     checkpoint = null;
     timeline = [];
     nudge = null;
@@ -214,6 +259,29 @@ export class ReviewTranscriptBuilder {
         }
         this.touch();
     }
+    /**
+     * Advance the CURRENT-round marker to `round` WITHOUT creating round rows.
+     *
+     * `roundStart` pre-allocates empty rows up to `round` (legitimate while a
+     * round is opening — reviewers write into those rows). At capture time,
+     * though, `roundsExecuted` may legitimately exceed the rounds we actually
+     * captured data for: calling `roundStart(roundsExecuted)` there fabricated
+     * phantom EMPTY round rows the reviewers never produced. This setter only
+     * moves the marker — and only FORWARD (never rewinds past a row capture
+     * already recorded) — so `manifest.round` still reports how far the run got
+     * while `manifest.rounds` keeps only rounds with captured content.
+     */
+    advanceRound(round, maxRounds) {
+        const r = typeof round === 'number' && Number.isFinite(round) && round > 0
+            ? Math.min(Math.floor(round), MAX_ROUNDS)
+            : 0;
+        if (r > this.round)
+            this.round = r;
+        if (typeof maxRounds === 'number' && Number.isFinite(maxRounds) && maxRounds >= 0) {
+            this.maxRounds = Math.min(Math.floor(maxRounds), MAX_ROUNDS);
+        }
+        this.touch();
+    }
     // ─── Reviewer threads (F1) ──────────────────────────────────────────────
     /** Start a reviewer sub-agent's thread for the current round. */
     reviewerStart(dimension, attempt = 1) {
@@ -274,7 +342,7 @@ export class ReviewTranscriptBuilder {
             return;
         // Hostile-manifest guard: keep the live hard bound (with headroom for the
         // single overflow thread) and newest-first truncate beyond it.
-        if (live.threads.length >= MAX_THREADS_PER_ROUND * 2 + 1)
+        if (live.threads.length >= MAX_THREADS_RESTORED)
             return;
         const dim = typeof thread.dimension === 'string' && thread.dimension.trim()
             ? thread.dimension.trim()
@@ -407,6 +475,23 @@ export class ReviewTranscriptBuilder {
         }
         this.touch();
     }
+    // ─── Validations (F6/F8 console) ────────────────────────────────────────
+    /**
+     * Record one validation command outcome. Normalizes defensively (bad rows
+     * are dropped, out-of-cap rounds clamped) and keeps the NEWEST rows under
+     * MAX_VALIDATIONS, mirroring {@link fix}. A malformed row can never crash
+     * the capture nor leak non-JSON state into the manifest.
+     */
+    validation(input) {
+        const record = normalizeValidation(input);
+        if (!record)
+            return;
+        this.validations.push(record);
+        if (this.validations.length > MAX_VALIDATIONS) {
+            this.validations.splice(0, this.validations.length - MAX_VALIDATIONS);
+        }
+        this.touch();
+    }
     // ─── Checkpoint (F5) ────────────────────────────────────────────────────
     /** Record the current checkpoint summary (null clears it). */
     recordCheckpoint(state) {
@@ -493,6 +578,7 @@ export class ReviewTranscriptBuilder {
             // already ≤ MAX_FINDINGS_TOTAL — no post-hoc slice needed.
             findings: this.globalFindings,
             fixes: this.fixes,
+            validations: this.validations,
             checkpoint: this.checkpoint,
             timeline: this.timeline,
             nudge: this.nudge,
@@ -560,3 +646,180 @@ function dedupePaths(paths) {
 function isoNow() {
     return new Date().toISOString();
 }
+// ─── Read-side normalization ────────────────────────────────────────────────
+/** Clamp an unknown round marker into [0, MAX_ROUNDS] (0 = never recorded). */
+function clampRoundValue(v) {
+    return typeof v === 'number' && Number.isFinite(v)
+        ? Math.min(Math.max(Math.floor(v), 0), MAX_ROUNDS)
+        : 0;
+}
+/** Clamp an unknown non-negative counter (0 when absent/garbage). */
+function clampCountValue(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0;
+}
+/** Re-run one persisted thread row through the builder's per-row bounds. */
+function normalizeThreadRow(input) {
+    const t = (input && typeof input === 'object' ? input : {});
+    const dim = typeof t.dimension === 'string' && t.dimension.trim() ? t.dimension.trim() : 'review';
+    const att = typeof t.attempt === 'number' && Number.isFinite(t.attempt) ? Math.floor(t.attempt) : 1;
+    const messages = Array.isArray(t.messages) ? t.messages : [];
+    const readFiles = Array.isArray(t.readFiles) ? t.readFiles : [];
+    const rawFindings = Array.isArray(t.findings) ? t.findings : [];
+    const findings = rawFindings
+        .map((f) => normalizeFinding(f))
+        .filter((f) => f !== null);
+    return {
+        dimension: dim,
+        attempt: att > 0 ? att : 1,
+        // Same reductions serialize() applies: messages newest-capped + trimmed,
+        // readFiles deduped, per-thread findings newest-capped.
+        messages: clampStringList(messages, MAX_MESSAGES_PER_THREAD),
+        readFiles: dedupePaths(readFiles),
+        findings: findings.length > MAX_FINDINGS_PER_THREAD
+            ? findings.slice(-MAX_FINDINGS_PER_THREAD)
+            : findings,
+    };
+}
+/** Re-run one persisted fix row through the builder's fix() requirements. */
+function normalizeFixRow(input) {
+    if (!input || typeof input !== 'object')
+        return null;
+    const f = input;
+    const id = typeof f.id === 'string' ? f.id : '';
+    const file = typeof f.file === 'string' ? f.file : '';
+    if (!id || !file)
+        return null;
+    return {
+        id,
+        file,
+        // No fabricated "now" on read: a corrupt/absent timestamp stays blank
+        // instead of masquerading as a fix that just happened.
+        timestamp: typeof f.timestamp === 'string' ? f.timestamp : '',
+        round: clampRoundValue(f.round),
+        summary: typeof f.summary === 'string' ? f.summary : '',
+        linesAdded: clampCountValue(f.linesAdded),
+        linesRemoved: clampCountValue(f.linesRemoved),
+        success: f.success !== false,
+    };
+}
+/** Re-run one persisted timeline row through the builder's decision() shape. */
+function normalizeTimelineRow(input) {
+    if (!input || typeof input !== 'object')
+        return null;
+    const e = input;
+    return {
+        timestamp: typeof e.timestamp === 'string' ? e.timestamp : '',
+        round: clampRoundValue(e.round),
+        type: typeof e.type === 'string' && e.type ? e.type : 'decision',
+        data: e.data && typeof e.data === 'object' && !Array.isArray(e.data)
+            ? e.data
+            : {},
+    };
+}
+/** Re-run a persisted checkpoint through the builder's recordCheckpoint rules. */
+function normalizeCheckpointRow(input) {
+    if (!input || typeof input !== 'object')
+        return null;
+    const c = input;
+    const round = typeof c.round === 'number' && Number.isFinite(c.round) ? c.round : 0;
+    if (round <= 0)
+        return null;
+    return {
+        mode: c.mode === 'dry-run' || c.mode === 'normal' ? c.mode : 'normal',
+        round: clampRoundValue(c.round),
+        maxRounds: clampCountValue(c.maxRounds),
+        fixedCount: clampCountValue(c.fixedCount),
+        resumeCount: clampCountValue(c.resumeCount),
+        updatedAt: typeof c.updatedAt === 'string' ? c.updatedAt : '',
+    };
+}
+/** Re-run a persisted nudge through the builder's setNudge rules. */
+function normalizeNudgeRow(input) {
+    if (!input || typeof input !== 'object')
+        return null;
+    const n = input;
+    const text = typeof n.text === 'string' ? n.text.trim() : '';
+    if (!text)
+        return null;
+    return { timestamp: typeof n.timestamp === 'string' ? n.timestamp : '', text };
+}
+/**
+ * Defensive read-side normalization of a persisted manifest.
+ *
+ * `.iterate/transcript.json` is hand-editable JSON handed straight to the
+ * client/model by `iterate_transcript.read`: the tool gates the ROOT shape,
+ * but row-level bounds (threads, messages, findings, timeline, fixes …) used
+ * to pass through untouched, so a hostile or corrupted file could leak an
+ * unbounded payload or junk field values (fractional lines, non-string
+ * phases, negative counters) that a capture could never have written.
+ *
+ * Every field is re-run through the SAME normalizers and caps the builder
+ * uses at capture time. Deliberately NOT implemented as
+ * `rehydrateBuilder(...).serialize()`: that drops fields the builder cannot
+ * rebuild (phases, the run identity, the round marker), so a plain read would
+ * silently rewrite history. Unknown inputs degrade instead of throwing — this
+ * runs after the tool's structural gate but must stay safe on its own.
+ */
+export function normalizeManifestBounds(value) {
+    const m = (value && typeof value === 'object' ? value : {});
+    const rounds = (Array.isArray(m.rounds) ? m.rounds : [])
+        .slice(0, MAX_ROUNDS)
+        .map((r) => {
+        const row = (r && typeof r === 'object' ? r : {});
+        const threads = (Array.isArray(row.threads) ? row.threads : [])
+            .slice(0, MAX_THREADS_RESTORED)
+            .map((t) => normalizeThreadRow(t));
+        return { round: Math.max(clampRoundValue(row.round), 1), threads };
+    });
+    const fixes = (Array.isArray(m.fixes) ? m.fixes : [])
+        .map((f) => normalizeFixRow(f))
+        .filter((f) => f !== null);
+    const timeline = (Array.isArray(m.timeline) ? m.timeline : [])
+        .map((e) => normalizeTimelineRow(e))
+        .filter((e) => e !== null);
+    const globalFindings = (Array.isArray(m.findings) ? m.findings : [])
+        .map((f) => normalizeFinding(f))
+        .filter((f) => f !== null);
+    const convergence = (Array.isArray(m.convergence) ? m.convergence : [])
+        .slice(0, MAX_ROUNDS)
+        .map((n) => (typeof n === 'number' && Number.isFinite(n) ? n : -1));
+    const validations = Array.isArray(m.validations)
+        ? m.validations
+            .map((v) => normalizeValidation(v))
+            .filter((v) => v !== null)
+            .slice(-MAX_VALIDATIONS)
+        : undefined;
+    const policy = m.approval?.policy === 'deny' || m.approval?.policy === 'allow' ? m.approval.policy : 'ask';
+    const out = {
+        version: typeof m.version === 'number' && Number.isFinite(m.version) ? m.version : TRANSCRIPT_VERSION,
+        project: typeof m.project === 'string' ? m.project : '',
+        updatedAt: typeof m.updatedAt === 'string' ? m.updatedAt : '',
+        active: m.active === true,
+        mode: m.mode === 'dry-run' || m.mode === 'normal' ? m.mode : null,
+        goal: typeof m.goal === 'string' ? m.goal : '',
+        // A phase list is free-form narration names — strings only, bounded.
+        phases: clampStringList(Array.isArray(m.phases) ? m.phases : [], 100),
+        round: clampRoundValue(m.round),
+        maxRounds: clampCountValue(m.maxRounds),
+        rounds,
+        convergence,
+        findings: globalFindings.length > MAX_FINDINGS_TOTAL
+            ? globalFindings.slice(-MAX_FINDINGS_TOTAL)
+            : globalFindings,
+        fixes: fixes.slice(-MAX_FIXES),
+        checkpoint: normalizeCheckpointRow(m.checkpoint),
+        timeline: timeline.slice(-MAX_TIMELINE),
+        nudge: normalizeNudgeRow(m.nudge),
+        approval: {
+            active: typeof m.approval?.active === 'boolean' ? m.approval.active : policy !== 'allow',
+            policy,
+        },
+    };
+    if (validations !== undefined)
+        out.validations = validations;
+    if (m.taskMode === 'code' || m.taskMode === 'iterate' || m.taskMode === null)
+        out.taskMode = m.taskMode;
+    if (typeof m.stoppedReason === 'string' || m.stoppedReason === null)
+        out.stoppedReason = m.stoppedReason;
+    return out;
+}