iterate-plugin 3.9.0 → 3.9.1

package/dist/file-lock.js

@@ -103,17 +103,23 @@ export function acquireProjectLockChecked(projectRoot, name, options = {}) {
         catch (err) {
             if (err.code !== 'EEXIST')
                 return { acquired: false, release: () => { } };
-            // Lock exists — steal it when the owner is gone or the lock is ancient.
+            // Lock exists — steal it when the owner is VERIFIABLY gone, or when the
+            // lock file is ancient. The stamp is read defensively: a lock is created
+            // empty (`openSync(..., 'wx')`) and the holder's pid lands a moment later,
+            // so an empty/garbled stamp means "just created, holder still writing" —
+            // treating `Number('') === 0` as a dead owner would let a contender steal
+            // a live lock and enter the same critical section. Only a parseable
+            // positive pid that is dead (or an ancient mtime) is stolen.
             let stale = false;
             try {
                 const st = statSync(lockPath);
-                if (Date.now() - st.mtimeMs > staleMs)
-                    stale = true;
-                else {
-                    const pid = Number(readFileSync(lockPath, 'utf-8'));
-                    if (!processAlive(pid))
-                        stale = true;
-                }
+                const ancient = Date.now() - st.mtimeMs > staleMs;
+                const raw = readFileSync(lockPath, 'utf-8').trim();
+                const pid = /^\d+$/.test(raw) ? Number(raw) : 0;
+                if (pid > 0)
+                    stale = !processAlive(pid) || ancient;
+                else
+                    stale = ancient;
             }
             catch {
                 stale = true; // unreadable/vanishing lock → retry as stale
@@ -238,17 +244,25 @@ export function makeLockRelease(lockPath, ino) {
         }
     };
 }
-/**
- * Run `fn` while holding the advisory lock named `name`.
- * The release is guaranteed via `finally`; `fn`'s value or error propagates
- * unchanged. Not reentrant for the same (projectRoot, name) — see header.
- */
 export function withProjectLock(projectRoot, name, fn, options = {}) {
     const release = acquireProjectLock(projectRoot, name, options);
+    let out;
     try {
-        return fn();
+        out = fn();
     }
-    finally {
+    catch (err) {
         release();
+        throw err;
+    }
+    if (out && typeof out.then === 'function') {
+        return out.then((value) => {
+            release();
+            return value;
+        }, (err) => {
+            release();
+            throw err;
+        });
     }
+    release();
+    return out;
 }

package/dist/git-scope.js

@@ -172,16 +172,31 @@ export function decideScope(changedFiles) {
  */
 export function runGit(args, cwd, opts = {}) {
     return new Promise((resolve) => {
-        execFile('git', args, {
-            cwd,
-            timeout: 30_000,
-            maxBuffer: 10 * 1024 * 1024,
-            env: { ...process.env, PAGER: 'cat' },
-            signal: opts.signal,
-        }, (error, stdout, stderr) => {
-            const exitCode = error ? (typeof error.code === 'number' ? error.code : 1) : 0;
-            resolve({ ok: exitCode === 0, stdout: stdout ?? '', stderr: stderr ?? '', exitCode });
-        });
+        // execFile can THROW SYNCHRONOUSLY (rather than call back with an error)
+        // when an argument cannot be encoded — e.g. a NUL or lone surrogate in the
+        // config-supplied target branch. Without this guard that throw escapes the
+        // promise executor, rejecting `runGit` and propagating out of the tool call
+        // instead of degrading to the documented full-scope fallback.
+        try {
+            execFile('git', args, {
+                cwd,
+                timeout: 30_000,
+                maxBuffer: 10 * 1024 * 1024,
+                env: { ...process.env, PAGER: 'cat' },
+                signal: opts.signal,
+            }, (error, stdout, stderr) => {
+                const exitCode = error ? (typeof error.code === 'number' ? error.code : 1) : 0;
+                resolve({ ok: exitCode === 0, stdout: stdout ?? '', stderr: stderr ?? '', exitCode });
+            });
+        }
+        catch (err) {
+            resolve({
+                ok: false,
+                stdout: '',
+                stderr: err instanceof Error ? err.message : String(err),
+                exitCode: 1,
+            });
+        }
     });
 }
 /**

package/dist/report-render.js

@@ -138,6 +138,10 @@ function asString(value) {
 function asNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 }
+/** Non-negative integer (floors fractions); 0 for anything else. */
+function asInt(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
 function asArray(value) {
     return Array.isArray(value) ? value : [];
 }
@@ -184,7 +188,7 @@ export function buildRunReportData(manifest, extra) {
     const findings = asArray(get(src, 'findings')).map((f) => ({
         dimension: asString(get(f, 'dimension')),
         file: asString(get(f, 'file')),
-        line: asNumber(get(f, 'line')),
+        line: asInt(get(f, 'line')),
         severity: findingSeverity(f),
         summary: asString(get(f, 'summary')),
         failureScenario: asString(get(f, 'failure_scenario')),
@@ -205,7 +209,7 @@ export function buildRunReportData(manifest, extra) {
     const validations = asArray(get(src, 'validations')).map((v) => ({
         round: asNumber(get(v, 'round')),
         command: asString(get(v, 'command')),
-        exitCode: typeof get(v, 'exitCode') === 'number' ? asNumber(get(v, 'exitCode')) : null,
+        exitCode: typeof get(v, 'exitCode') === 'number' ? asInt(get(v, 'exitCode')) : null,
         allowed: get(v, 'allowed') === true,
         rejectReason: asString(get(v, 'rejectReason')),
     }));
@@ -225,7 +229,11 @@ export function buildRunReportData(manifest, extra) {
         taskMode: taskMode === 'code' || taskMode === 'iterate' ? taskMode : null,
         round: asNumber(get(src, 'round')),
         maxRounds: asNumber(get(src, 'maxRounds')),
-        active: get(src, 'active') !== false,
+        // An ABSENT `active` means "no run / unknown", not "running": a missing or
+        // empty transcript used to render a live, pulsing run at round 0. The
+        // transcript builder always writes an explicit boolean, so a strict `true`
+        // only ever loses the phantom run, never a real one.
+        active: get(src, 'active') === true,
         stoppedReason: typeof stoppedReason === 'string' && stoppedReason ? stoppedReason : null,
         updatedAt: asString(get(src, 'updatedAt')),
         convergence: asArray(get(src, 'convergence')).filter((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0),
@@ -296,7 +304,7 @@ export function renderRunReportMarkdown(manifest, extra, opts) {
         lines.push(`| ${labels.severity} | ${labels.dimension} | ${labels.location} | ${labels.summary} |`);
         lines.push('| --- | --- | --- | --- |');
         for (const f of data.findings) {
-            const loc = f.file ? `${f.file}${f.line > 1 ? `:${f.line}` : ''}` : '';
+            const loc = f.file ? `${f.file}${f.line > 0 ? `:${f.line}` : ''}` : '';
             lines.push(`| ${mdCell(f.severity)} | ${mdCell(f.dimension)} | ${mdCell(loc)} | ${mdCell(f.summary)} |`);
         }
     }
@@ -395,7 +403,9 @@ export function renderRunReportSarif(manifest, extra, opts) {
             result.fixes = [{ description: { text: f.suggestedFix } }];
         return result;
     });
-    const failedValidations = data.validations.filter((v) => v.exitCode !== 0).length;
+    // `exitCode: null` is the documented "unknown / no exit code" value, not a
+    // failure: only a concrete non-zero code makes the run unsuccessful.
+    const failedValidations = data.validations.filter((v) => v.exitCode !== null && v.exitCode !== 0).length;
     return {
         $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
         version: '2.1.0',

package/dist/session-record.js

@@ -100,7 +100,9 @@ export function normalizeRunRecord(data) {
     const d = data;
     // A record written by a future/incompatible build is skipped rather than
     // coerced: the version gate is the contract that lets the payload evolve.
-    if (nonNegInt(d.version) !== ITERATE_RUN_RECORD_VERSION)
+    // The check is exact (an integer compare, not a floor) so a payload stamped
+    // `1.9` by a future build is rejected instead of rounded down to `1`.
+    if (!Number.isInteger(d.version) || d.version !== ITERATE_RUN_RECORD_VERSION)
         return null;
     const findings = (d.findings && typeof d.findings === 'object' && !Array.isArray(d.findings)
         ? d.findings
@@ -132,12 +134,17 @@ export function normalizeRunRecord(data) {
 let cachedApi;
 /** Test override; when set (including `null`) the dynamic import is bypassed. */
 let testApiOverride;
+/** Module loader; replaceable for tests to exercise import failure/late availability. */
+let moduleImporter = () => import('@deepseek-ai/dsh-session');
 /** Resolve the `@deepseek-ai/dsh-session` record API, or `null` when absent. */
 export function loadSessionRecordApi() {
     if (testApiOverride !== undefined)
         return Promise.resolve(testApiOverride);
     if (cachedApi === undefined) {
-        cachedApi = import('@deepseek-ai/dsh-session')
+        // `Promise.resolve().then(...)` (not a bare call) so a loader that throws
+        // SYNCHRONOUSLY still lands in the `.catch` instead of escaping.
+        cachedApi = Promise.resolve()
+            .then(() => moduleImporter())
             .then((mod) => {
             const m = mod;
             if (typeof m.appendPluginRecord !== 'function' || typeof m.pluginRecordOf !== 'function') {
@@ -149,9 +156,24 @@ export function loadSessionRecordApi() {
             };
         })
             .catch(() => null);
+        // A `null` resolution (module/API absent, or a transient import failure) is
+        // NOT memoized: it is cleared so the next call retries. Otherwise one
+        // unlucky first import would disable session linking for the whole process.
+        void cachedApi.then((api) => {
+            if (!api)
+                cachedApi = undefined;
+        });
     }
     return cachedApi;
 }
+/**
+ * Replace the module loader for tests (to exercise the import-failure and
+ * late-availability paths). Pass `undefined` to restore the real dynamic import.
+ */
+export function setSessionRecordImporterForTests(loader) {
+    moduleImporter = loader ?? (() => import('@deepseek-ai/dsh-session'));
+    cachedApi = undefined;
+}
 /**
  * Override the session-record API for tests. Pass `undefined` to restore the
  * real dynamic import, or an object / `null` to force a deterministic result.

package/dist/tools/report.js

@@ -4,8 +4,8 @@
  *   iterate_report — render the current iterate run into a portable report.
  *
  * Two formats, one normalized data model (shared with the client export
- * buttons via `lib/parse.js`, so the on-screen export and this tool can never
- * drift):
+ * buttons via `src/report-render.ts`, so the on-screen export and this tool
+ * can never drift):
  *
  *   - `markdown` — a PR-pasteable run report: header (mode/round/status), the
  *                  quality-gate table, the findings table, the fixes table,

package/dist/tools/transcript.js

@@ -29,6 +29,7 @@ import { loadEffectiveConfig, resolveProjectRootForExec, } from "../config-loade
 import { transcriptPath } from "../paths.js";
 import { ReviewTranscriptBuilder, MAX_TIMELINE, MAX_ROUNDS, normalizeManifestBounds } from "../transcript.js";
 import { readDecisionLogDetailed } from "./decision-log.js";
+import { readQualityGate } from "./quality-store.js";
 import { readLive } from "../live.js";
 import { buildRunRecord, appendRunRecord, readRunRecords, sessionOf, } from "../session-record.js";
 /** Severity tally over a manifest's (globally deduped) findings. */
@@ -656,7 +657,18 @@ export function registerTranscriptTool(ctx) {
             // session. Best-effort — a link failure is reported, never fatal (the
             // on-disk capture above already succeeded).
             let sessionRecord;
-            const linkSession = await appendRunRecord(sessionOf(exec), runRecordFromManifest(manifest));
+            // Snapshot the CURRENT quality-gate verdict into the record so a
+            // recovered run keeps its PASS/FAIL badge. An absent gate reads as the
+            // store's default (`pending`); a corrupt/throwing read degrades to
+            // `null` and never fails the capture.
+            let qualityStatus = null;
+            try {
+                qualityStatus = readQualityGate(projectRoot).overallStatus ?? null;
+            }
+            catch {
+                qualityStatus = null;
+            }
+            const linkSession = await appendRunRecord(sessionOf(exec), runRecordFromManifest(manifest, qualityStatus));
             sessionRecord = (linkSession.ok
                 ? { linked: true, seq: linkSession.seq }
                 : { linked: false, supported: linkSession.supported, reason: linkSession.error });
@@ -682,6 +694,12 @@ function rehydrateBuilder(manifest, approval) {
         goal: manifest.goal,
         maxRounds: manifest.maxRounds,
     });
+    // Phase breadcrumbs are part of the run narrative the F1 stage tracker shows;
+    // replay them before the rounds so an edit round-trip keeps the stage order.
+    for (const p of Array.isArray(manifest.phases) ? manifest.phases : []) {
+        if (typeof p === 'string')
+            builder.phase(p);
+    }
     for (const r of Array.isArray(manifest.rounds) ? manifest.rounds : []) {
         // A malformed/null round row must be skipped, never a throw (the caller
         // wraps rehydrate in a fallback, but preserving sibling rows is better).
@@ -689,6 +707,10 @@ function rehydrateBuilder(manifest, approval) {
             continue;
         builder.roundStart(r.round, manifest.maxRounds);
         for (const t of Array.isArray(r.threads) ? r.threads : []) {
+            // A null/garbled thread row must be skipped too: reading `t.dimension`
+            // off it would throw and cost the WHOLE manifest its history.
+            if (!t || typeof t !== 'object')
+                continue;
             // restoreThread (not reviewerStart + reviewerMessage(join)) preserves the
             // message ARRAY boundaries and the thread's own dimension: rehydration
             // previously collapsed each thread's messages into one string and, once a
@@ -708,6 +730,15 @@ function rehydrateBuilder(manifest, approval) {
         if (typeof n === 'number' && n >= 0)
             builder.snapshotConvergence(idx + 1, n);
     }
+    // Top-level findings live in the global newest-wins list (the F3 panel reads
+    // `manifest.findings`); restoreThread only rebuilds the per-round threads, so
+    // without this a nudge/rollback re-persist blanked the findings panel.
+    if (Array.isArray(manifest.findings))
+        builder.restoreFindings(manifest.findings);
+    // Move the round marker forward past the captured rows: `roundStart` reopens
+    // rows, but a manifest whose `round` outruns its rows (advanceRound semantics)
+    // would otherwise rewind the reported round.
+    builder.advanceRound(manifest.round, manifest.maxRounds);
     if (manifest.checkpoint)
         builder.recordCheckpoint(manifest.checkpoint);
     if (Array.isArray(manifest.fixes))

package/dist/transcript.js

@@ -428,6 +428,24 @@ export class ReviewTranscriptBuilder {
         }
         this.touch();
     }
+    /**
+     * Re-insert top-level findings when rehydrating a persisted manifest (the
+     * nudge / rollback edit round-trip). `restoreThread` already rebuilds the
+     * per-round thread copy of each finding but never the global list, so an edit
+     * that only rewrites steering text used to blank `manifest.findings` and the
+     * F3 findings panel. This refills the global newest-wins list (and its dedupe
+     * set), mirroring `reviewerFindings` without needing a live thread.
+     */
+    restoreFindings(findings) {
+        if (Array.isArray(findings)) {
+            for (const raw of findings) {
+                const f = normalizeFinding(raw);
+                if (f)
+                    this.addGlobal(f);
+            }
+        }
+        this.touch();
+    }
     // ─── Convergence (F2) ───────────────────────────────────────────────────
     /** Record a round's new-finding count for the convergence series. */
     snapshotConvergence(round, newCount) {

package/lib/client.js

@@ -1,4 +1,4 @@
-/* iterate-plugin client source-digest: 50774433818a03e70b4ac5341a6683c1ccb3d3a5ff93561a29007232a03b3e01 */
+/* iterate-plugin client source-digest: 2819f2e6f5f182bb31b9e47c356f60e0b8d97fcdbd232c31b89438619623cf93 */
 window.__ModuleLoader__.load({ id: "iterate-plugin", factory: (require) => {
 var module = { exports: {} };
 var exports = module.exports;
@@ -2023,6 +2023,9 @@ function asString(value) {
 function asNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
+function asInt(value) {
+  return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
 function asArray(value) {
   return Array.isArray(value) ? value : [];
 }
@@ -2056,7 +2059,7 @@ function buildRunReportData(manifest, extra) {
   const findings = asArray(get(src, "findings")).map((f) => ({
     dimension: asString(get(f, "dimension")),
     file: asString(get(f, "file")),
-    line: asNumber(get(f, "line")),
+    line: asInt(get(f, "line")),
     severity: findingSeverity(f),
     summary: asString(get(f, "summary")),
     failureScenario: asString(get(f, "failure_scenario")),
@@ -2078,7 +2081,7 @@ function buildRunReportData(manifest, extra) {
   const validations = asArray(get(src, "validations")).map((v) => ({
     round: asNumber(get(v, "round")),
     command: asString(get(v, "command")),
-    exitCode: typeof get(v, "exitCode") === "number" ? asNumber(get(v, "exitCode")) : null,
+    exitCode: typeof get(v, "exitCode") === "number" ? asInt(get(v, "exitCode")) : null,
     allowed: get(v, "allowed") === true,
     rejectReason: asString(get(v, "rejectReason"))
   }));
@@ -2097,7 +2100,11 @@ function buildRunReportData(manifest, extra) {
     taskMode: taskMode === "code" || taskMode === "iterate" ? taskMode : null,
     round: asNumber(get(src, "round")),
     maxRounds: asNumber(get(src, "maxRounds")),
-    active: get(src, "active") !== false,
+    // An ABSENT `active` means "no run / unknown", not "running": a missing or
+    // empty transcript used to render a live, pulsing run at round 0. The
+    // transcript builder always writes an explicit boolean, so a strict `true`
+    // only ever loses the phantom run, never a real one.
+    active: get(src, "active") === true,
     stoppedReason: typeof stoppedReason === "string" && stoppedReason ? stoppedReason : null,
     updatedAt: asString(get(src, "updatedAt")),
     convergence: asArray(get(src, "convergence")).filter(
@@ -2170,7 +2177,7 @@ function renderRunReportMarkdown(manifest, extra, opts) {
     lines.push(`| ${labels.severity} | ${labels.dimension} | ${labels.location} | ${labels.summary} |`);
     lines.push("| --- | --- | --- | --- |");
     for (const f of data.findings) {
-      const loc = f.file ? `${f.file}${f.line > 1 ? `:${f.line}` : ""}` : "";
+      const loc = f.file ? `${f.file}${f.line > 0 ? `:${f.line}` : ""}` : "";
       lines.push(`| ${mdCell(f.severity)} | ${mdCell(f.dimension)} | ${mdCell(loc)} | ${mdCell(f.summary)} |`);
     }
   }
@@ -2269,7 +2276,7 @@ function renderRunReportSarif(manifest, extra, opts) {
     if (f.suggestedFix) result.fixes = [{ description: { text: f.suggestedFix } }];
     return result;
   });
-  const failedValidations = data.validations.filter((v) => v.exitCode !== 0).length;
+  const failedValidations = data.validations.filter((v) => v.exitCode !== null && v.exitCode !== 0).length;
   return {
     $schema: "https://json.schemastore.org/sarif-2.1.0.json",
     version: "2.1.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "3.9.0",
+  "version": "3.9.1",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness with quality command center and experience bank (v3.3). Features: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus dry-run pure-review mode, quality gate compute/persist, writable experience bank, defense events stream (record + bilingual labels), and native command buttons — with a live quality command center (F8/F9/F10 render real session data), §8 assign-fix instruction, and task_mode indicator wired end to end.",
   "type": "module",
   "license": "MIT",

package/src/file-lock.ts

@@ -133,15 +133,21 @@ export function acquireProjectLockChecked(
       fd = openSync(lockPath, 'wx')
     } catch (err) {
       if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return { acquired: false, release: () => {} }
-      // Lock exists — steal it when the owner is gone or the lock is ancient.
+      // Lock exists — steal it when the owner is VERIFIABLY gone, or when the
+      // lock file is ancient. The stamp is read defensively: a lock is created
+      // empty (`openSync(..., 'wx')`) and the holder's pid lands a moment later,
+      // so an empty/garbled stamp means "just created, holder still writing" —
+      // treating `Number('') === 0` as a dead owner would let a contender steal
+      // a live lock and enter the same critical section. Only a parseable
+      // positive pid that is dead (or an ancient mtime) is stolen.
       let stale = false
       try {
         const st = statSync(lockPath)
-        if (Date.now() - st.mtimeMs > staleMs) stale = true
-        else {
-          const pid = Number(readFileSync(lockPath, 'utf-8'))
-          if (!processAlive(pid)) stale = true
-        }
+        const ancient = Date.now() - st.mtimeMs > staleMs
+        const raw = readFileSync(lockPath, 'utf-8').trim()
+        const pid = /^\d+$/.test(raw) ? Number(raw) : 0
+        if (pid > 0) stale = !processAlive(pid) || ancient
+        else stale = ancient
       } catch {
         stale = true // unreadable/vanishing lock → retry as stale
       }
@@ -265,17 +271,49 @@ export function makeLockRelease(lockPath: string, ino?: number): () => void {
  * Run `fn` while holding the advisory lock named `name`.
  * The release is guaranteed via `finally`; `fn`'s value or error propagates
  * unchanged. Not reentrant for the same (projectRoot, name) — see header.
+ *
+ * `fn` may return a promise: in that case the lock is held until it settles, so
+ * a read-modify-write that spans `await`ed fs calls is actually serialized
+ * (releasing when `fn()` *returns its promise* would defeat the lock entirely).
  */
 export function withProjectLock<T>(
   projectRoot: string,
   name: string,
   fn: () => T,
+  options?: LockOptions,
+): T
+export function withProjectLock<T>(
+  projectRoot: string,
+  name: string,
+  fn: () => Promise<T>,
+  options?: LockOptions,
+): Promise<T>
+export function withProjectLock<T>(
+  projectRoot: string,
+  name: string,
+  fn: () => T | Promise<T>,
   options: LockOptions = {},
-): T {
+): T | Promise<T> {
   const release = acquireProjectLock(projectRoot, name, options)
+  let out: T | Promise<T>
   try {
-    return fn()
-  } finally {
+    out = fn()
+  } catch (err) {
     release()
+    throw err
+  }
+  if (out && typeof (out as Promise<T>).then === 'function') {
+    return (out as Promise<T>).then(
+      (value) => {
+        release()
+        return value
+      },
+      (err) => {
+        release()
+        throw err
+      },
+    )
   }
+  release()
+  return out
 }

package/src/git-scope.ts

@@ -177,21 +177,35 @@ export function runGit(
   opts: { signal?: AbortSignal } = {},
 ): Promise<{ ok: boolean; stdout: string; stderr: string; exitCode: number }> {
   return new Promise((resolve) => {
-    execFile(
-      'git',
-      args,
-      {
-        cwd,
-        timeout: 30_000,
-        maxBuffer: 10 * 1024 * 1024,
-        env: { ...process.env, PAGER: 'cat' },
-        signal: opts.signal,
-      },
-      (error, stdout, stderr) => {
-        const exitCode = error ? (typeof error.code === 'number' ? error.code : 1) : 0
-        resolve({ ok: exitCode === 0, stdout: stdout ?? '', stderr: stderr ?? '', exitCode })
-      },
-    )
+    // execFile can THROW SYNCHRONOUSLY (rather than call back with an error)
+    // when an argument cannot be encoded — e.g. a NUL or lone surrogate in the
+    // config-supplied target branch. Without this guard that throw escapes the
+    // promise executor, rejecting `runGit` and propagating out of the tool call
+    // instead of degrading to the documented full-scope fallback.
+    try {
+      execFile(
+        'git',
+        args,
+        {
+          cwd,
+          timeout: 30_000,
+          maxBuffer: 10 * 1024 * 1024,
+          env: { ...process.env, PAGER: 'cat' },
+          signal: opts.signal,
+        },
+        (error, stdout, stderr) => {
+          const exitCode = error ? (typeof error.code === 'number' ? error.code : 1) : 0
+          resolve({ ok: exitCode === 0, stdout: stdout ?? '', stderr: stderr ?? '', exitCode })
+        },
+      )
+    } catch (err) {
+      resolve({
+        ok: false,
+        stdout: '',
+        stderr: err instanceof Error ? err.message : String(err),
+        exitCode: 1,
+      })
+    }
   })
 }
 

package/src/report-render.ts

@@ -205,6 +205,11 @@ function asNumber(value: unknown): number {
   return typeof value === 'number' && Number.isFinite(value) ? value : 0
 }
 
+/** Non-negative integer (floors fractions); 0 for anything else. */
+function asInt(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0
+}
+
 function asArray(value: unknown): unknown[] {
   return Array.isArray(value) ? value : []
 }
@@ -258,7 +263,7 @@ export function buildRunReportData(
   const findings: ReportFinding[] = asArray(get(src, 'findings')).map((f) => ({
     dimension: asString(get(f, 'dimension')),
     file: asString(get(f, 'file')),
-    line: asNumber(get(f, 'line')),
+    line: asInt(get(f, 'line')),
     severity: findingSeverity(f),
     summary: asString(get(f, 'summary')),
     failureScenario: asString(get(f, 'failure_scenario')),
@@ -284,7 +289,7 @@ export function buildRunReportData(
   const validations: ReportValidation[] = asArray(get(src, 'validations')).map((v) => ({
     round: asNumber(get(v, 'round')),
     command: asString(get(v, 'command')),
-    exitCode: typeof get(v, 'exitCode') === 'number' ? asNumber(get(v, 'exitCode')) : null,
+    exitCode: typeof get(v, 'exitCode') === 'number' ? asInt(get(v, 'exitCode')) : null,
     allowed: get(v, 'allowed') === true,
     rejectReason: asString(get(v, 'rejectReason')),
   }))
@@ -306,7 +311,11 @@ export function buildRunReportData(
     taskMode: taskMode === 'code' || taskMode === 'iterate' ? taskMode : null,
     round: asNumber(get(src, 'round')),
     maxRounds: asNumber(get(src, 'maxRounds')),
-    active: get(src, 'active') !== false,
+    // An ABSENT `active` means "no run / unknown", not "running": a missing or
+    // empty transcript used to render a live, pulsing run at round 0. The
+    // transcript builder always writes an explicit boolean, so a strict `true`
+    // only ever loses the phantom run, never a real one.
+    active: get(src, 'active') === true,
     stoppedReason: typeof stoppedReason === 'string' && stoppedReason ? stoppedReason : null,
     updatedAt: asString(get(src, 'updatedAt')),
     convergence: asArray(get(src, 'convergence')).filter(
@@ -392,7 +401,7 @@ export function renderRunReportMarkdown(
     lines.push(`| ${labels.severity} | ${labels.dimension} | ${labels.location} | ${labels.summary} |`)
     lines.push('| --- | --- | --- | --- |')
     for (const f of data.findings) {
-      const loc = f.file ? `${f.file}${f.line > 1 ? `:${f.line}` : ''}` : ''
+      const loc = f.file ? `${f.file}${f.line > 0 ? `:${f.line}` : ''}` : ''
       lines.push(`| ${mdCell(f.severity)} | ${mdCell(f.dimension)} | ${mdCell(loc)} | ${mdCell(f.summary)} |`)
     }
   }
@@ -513,7 +522,9 @@ export function renderRunReportSarif(
     if (f.suggestedFix) result.fixes = [{ description: { text: f.suggestedFix } }]
     return result
   })
-  const failedValidations = data.validations.filter((v) => v.exitCode !== 0).length
+  // `exitCode: null` is the documented "unknown / no exit code" value, not a
+  // failure: only a concrete non-zero code makes the run unsuccessful.
+  const failedValidations = data.validations.filter((v) => v.exitCode !== null && v.exitCode !== 0).length
   return {
     $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
     version: '2.1.0',

package/src/session-record.ts

@@ -63,7 +63,7 @@ export interface IterateRunRecord {
   }
   /** Applied (successful) fixes recorded so far. */
   fixedCount: number
-  /** Snapshot of the quality-gate verdict at write time, when known. */
+  /** Quality-gate verdict snapshotted at write time (`pending` when undecided). */
   qualityStatus: 'pass' | 'fail' | 'pending' | null
   /** ISO timestamp the record was written. */
   updatedAt: string
@@ -193,7 +193,9 @@ export function normalizeRunRecord(data: unknown): IterateRunRecord | null {
   const d = data as Record<string, unknown>
   // A record written by a future/incompatible build is skipped rather than
   // coerced: the version gate is the contract that lets the payload evolve.
-  if (nonNegInt(d.version) !== ITERATE_RUN_RECORD_VERSION) return null
+  // The check is exact (an integer compare, not a floor) so a payload stamped
+  // `1.9` by a future build is rejected instead of rounded down to `1`.
+  if (!Number.isInteger(d.version) || d.version !== ITERATE_RUN_RECORD_VERSION) return null
   const findings = (d.findings && typeof d.findings === 'object' && !Array.isArray(d.findings)
     ? (d.findings as Record<string, unknown>)
     : {}) as Record<string, unknown>
@@ -226,12 +228,17 @@ export function normalizeRunRecord(data: unknown): IterateRunRecord | null {
 let cachedApi: Promise<SessionRecordApi | null> | undefined
 /** Test override; when set (including `null`) the dynamic import is bypassed. */
 let testApiOverride: SessionRecordApi | null | undefined
+/** Module loader; replaceable for tests to exercise import failure/late availability. */
+let moduleImporter: () => Promise<unknown> = () => import('@deepseek-ai/dsh-session')
 
 /** Resolve the `@deepseek-ai/dsh-session` record API, or `null` when absent. */
 export function loadSessionRecordApi(): Promise<SessionRecordApi | null> {
   if (testApiOverride !== undefined) return Promise.resolve(testApiOverride)
   if (cachedApi === undefined) {
-    cachedApi = import('@deepseek-ai/dsh-session')
+    // `Promise.resolve().then(...)` (not a bare call) so a loader that throws
+    // SYNCHRONOUSLY still lands in the `.catch` instead of escaping.
+    cachedApi = Promise.resolve()
+      .then(() => moduleImporter())
       .then((mod) => {
         const m = mod as unknown as Partial<SessionRecordApi>
         if (typeof m.appendPluginRecord !== 'function' || typeof m.pluginRecordOf !== 'function') {
@@ -243,10 +250,25 @@ export function loadSessionRecordApi(): Promise<SessionRecordApi | null> {
         }
       })
       .catch(() => null)
+    // A `null` resolution (module/API absent, or a transient import failure) is
+    // NOT memoized: it is cleared so the next call retries. Otherwise one
+    // unlucky first import would disable session linking for the whole process.
+    void cachedApi.then((api) => {
+      if (!api) cachedApi = undefined
+    })
   }
   return cachedApi
 }
 
+/**
+ * Replace the module loader for tests (to exercise the import-failure and
+ * late-availability paths). Pass `undefined` to restore the real dynamic import.
+ */
+export function setSessionRecordImporterForTests(loader: (() => Promise<unknown>) | undefined): void {
+  moduleImporter = loader ?? (() => import('@deepseek-ai/dsh-session'))
+  cachedApi = undefined
+}
+
 /**
  * Override the session-record API for tests. Pass `undefined` to restore the
  * real dynamic import, or an object / `null` to force a deterministic result.

package/src/tools/report.ts

@@ -4,8 +4,8 @@
  *   iterate_report — render the current iterate run into a portable report.
  *
  * Two formats, one normalized data model (shared with the client export
- * buttons via `lib/parse.js`, so the on-screen export and this tool can never
- * drift):
+ * buttons via `src/report-render.ts`, so the on-screen export and this tool
+ * can never drift):
  *
  *   - `markdown` — a PR-pasteable run report: header (mode/round/status), the
  *                  quality-gate table, the findings table, the fixes table,

package/src/tools/transcript.ts

@@ -34,6 +34,7 @@ import {
 import { transcriptPath } from '../paths.ts'
 import { ReviewTranscriptBuilder, MAX_TIMELINE, MAX_ROUNDS, normalizeManifestBounds } from '../transcript.ts'
 import { readDecisionLogDetailed } from './decision-log.ts'
+import { readQualityGate } from './quality-store.ts'
 import { readLive } from '../live.ts'
 import {
   buildRunRecord,
@@ -685,7 +686,17 @@ export function registerTranscriptTool(ctx: {
         // session. Best-effort — a link failure is reported, never fatal (the
         // on-disk capture above already succeeded).
         let sessionRecord: JsonValue
-        const linkSession = await appendRunRecord(sessionOf(exec), runRecordFromManifest(manifest))
+        // Snapshot the CURRENT quality-gate verdict into the record so a
+        // recovered run keeps its PASS/FAIL badge. An absent gate reads as the
+        // store's default (`pending`); a corrupt/throwing read degrades to
+        // `null` and never fails the capture.
+        let qualityStatus: 'pass' | 'fail' | 'pending' | null = null
+        try {
+          qualityStatus = readQualityGate(projectRoot).overallStatus ?? null
+        } catch {
+          qualityStatus = null
+        }
+        const linkSession = await appendRunRecord(sessionOf(exec), runRecordFromManifest(manifest, qualityStatus))
         sessionRecord = (
           linkSession.ok
             ? { linked: true, seq: linkSession.seq }
@@ -715,12 +726,20 @@ function rehydrateBuilder(manifest: TranscriptManifest, approval: 'ask' | 'deny'
     goal: manifest.goal,
     maxRounds: manifest.maxRounds,
   })
+  // Phase breadcrumbs are part of the run narrative the F1 stage tracker shows;
+  // replay them before the rounds so an edit round-trip keeps the stage order.
+  for (const p of Array.isArray(manifest.phases) ? manifest.phases : []) {
+    if (typeof p === 'string') builder.phase(p)
+  }
   for (const r of Array.isArray(manifest.rounds) ? manifest.rounds : []) {
     // A malformed/null round row must be skipped, never a throw (the caller
     // wraps rehydrate in a fallback, but preserving sibling rows is better).
     if (!r || typeof r !== 'object') continue
     builder.roundStart(r.round, manifest.maxRounds)
     for (const t of Array.isArray(r.threads) ? r.threads : []) {
+      // A null/garbled thread row must be skipped too: reading `t.dimension`
+      // off it would throw and cost the WHOLE manifest its history.
+      if (!t || typeof t !== 'object') continue
       // restoreThread (not reviewerStart + reviewerMessage(join)) preserves the
       // message ARRAY boundaries and the thread's own dimension: rehydration
       // previously collapsed each thread's messages into one string and, once a
@@ -739,6 +758,14 @@ function rehydrateBuilder(manifest: TranscriptManifest, approval: 'ask' | 'deny'
     const n = manifest.convergence[idx]
     if (typeof n === 'number' && n >= 0) builder.snapshotConvergence(idx + 1, n)
   }
+  // Top-level findings live in the global newest-wins list (the F3 panel reads
+  // `manifest.findings`); restoreThread only rebuilds the per-round threads, so
+  // without this a nudge/rollback re-persist blanked the findings panel.
+  if (Array.isArray(manifest.findings)) builder.restoreFindings(manifest.findings)
+  // Move the round marker forward past the captured rows: `roundStart` reopens
+  // rows, but a manifest whose `round` outruns its rows (advanceRound semantics)
+  // would otherwise rewind the reported round.
+  builder.advanceRound(manifest.round, manifest.maxRounds)
   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

package/src/transcript.ts

@@ -486,6 +486,24 @@ export class ReviewTranscriptBuilder {
     this.touch()
   }
 
+  /**
+   * Re-insert top-level findings when rehydrating a persisted manifest (the
+   * nudge / rollback edit round-trip). `restoreThread` already rebuilds the
+   * per-round thread copy of each finding but never the global list, so an edit
+   * that only rewrites steering text used to blank `manifest.findings` and the
+   * F3 findings panel. This refills the global newest-wins list (and its dedupe
+   * set), mirroring `reviewerFindings` without needing a live thread.
+   */
+  restoreFindings(findings: readonly unknown[]): void {
+    if (Array.isArray(findings)) {
+      for (const raw of findings) {
+        const f = normalizeFinding(raw)
+        if (f) this.addGlobal(f)
+      }
+    }
+    this.touch()
+  }
+
   // ─── Convergence (F2) ───────────────────────────────────────────────────
 
   /** Record a round's new-finding count for the convergence series. */