iterate-plugin 3.7.0 → 3.9.0

package/src/tools/report.ts

@@ -0,0 +1,244 @@
+/**
+ * src/tools/report.ts — `iterate_report` tool.
+ *
+ *   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):
+ *
+ *   - `markdown` — a PR-pasteable run report: header (mode/round/status), the
+ *                  quality-gate table, the findings table, the fixes table,
+ *                  validations, defense events, and the experience bank.
+ *   - `sarif`    — a SARIF 2.1.0 log so CI / GitHub Code Scanning can consume
+ *                  iterate findings as code-scanning results (ruleId =
+ *                  dimension, severity → error/warning/note, file+line
+ *                  locations, suggested fix attached).
+ *
+ * Reads only local state (`.iterate/transcript.json` + the quality / experience
+ * / defense stores) and writes only `.iterate/report.<ext>` when `write:true`.
+ * Malformed or missing state is rendered as-is (empty tables) — an export must
+ * never fail because a run was partial.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import { resolveProjectRootForExec } from '../config-loader.ts'
+import { iterateDir, transcriptPath } from '../paths.ts'
+import { readQualityGate } from './quality-store.ts'
+import { readExperienceBank } from './experience-store.ts'
+import { readDefenseEvents } from './defense-store.ts'
+import { resultHeadline } from './present.ts'
+import { renderRunReportMarkdown, renderRunReportSarif, REPORT_FORMATS } from '../report-render.ts'
+
+/** Formats accepted by the tool (kept in sync with the shared renderer). */
+const FORMATS: ReadonlySet<string> = new Set(REPORT_FORMATS)
+
+/** Read the persisted transcript manifest, tolerating a missing/garbled file. */
+function readManifest(projectRoot: string): { manifest: unknown; source: 'disk' | 'empty' } {
+  const file = transcriptPath(projectRoot)
+  if (!existsSync(file)) return { manifest: {}, source: 'empty' }
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf-8')) as unknown
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return { manifest: parsed, source: 'disk' }
+    }
+    return { manifest: {}, source: 'empty' }
+  } catch {
+    return { manifest: {}, source: 'empty' }
+  }
+}
+
+/**
+ * Register the `iterate_report` tool.
+ * Renders the current run into a Markdown or SARIF report.
+ */
+export function registerReportTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_report',
+      // Result card: surface the report headline ("report: markdown · N findings")
+      // as the card title. Pure: reads only the rendered result (replay-safe).
+      presentResult: (_args, result) => {
+        const title = resultHeadline(result)
+        return title ? { card: 'generic', title } : undefined
+      },
+      // `write:true` persists a file; a pure render joins a parallel group.
+      isConcurrencySafe: (args) => (args as { write?: unknown }).write !== true,
+      description:
+        'Export the current iterate run as a portable report. ' +
+        '`format:"markdown"` (default) renders a PR-pasteable report: run header (mode / round / status), ' +
+        'quality-gate table, findings table, fixes table, per-round validations, defense events, and the ' +
+        'experience bank. `format:"sarif"` renders a SARIF 2.1.0 log for CI / GitHub Code Scanning ' +
+        '(one rule per review dimension; finding severity maps to error/warning/note; findings carry ' +
+        'file + line locations and the suggested fix). ' +
+        'Set `write:true` to also persist the report under `.iterate/report.md` / `.iterate/report.sarif` ' +
+        'and get the path back. `lang` selects the report language (zh | en). ' +
+        'Read-only apart from the optional report file; never touches source files.',
+      parameters: {
+        format: {
+          type: 'string',
+          description: 'Report format: "markdown" (default) or "sarif".',
+          enum: ['markdown', 'sarif'],
+        },
+        write: {
+          type: 'boolean',
+          description: 'When true, persist the report to `.iterate/report.md` / `.iterate/report.sarif` and return its path. Default: false.',
+        },
+        lang: {
+          type: 'string',
+          description: 'Report language: "zh" (default) or "en". Affects labels/headings only.',
+          enum: ['zh', 'en'],
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            kind: { type: 'string' },
+            format: { type: 'string' },
+            /** The rendered report text (Markdown, or pretty-printed SARIF JSON). */
+            content: { type: 'string' },
+            /** The SARIF log object, when format is "sarif". */
+            sarif: { type: 'json' },
+            /** Whether a source transcript manifest was found on disk. */
+            source: { type: 'string' },
+            written: { type: 'boolean' },
+            reportPath: { type: 'string' },
+            findings: { type: 'number' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (!value.ok) return [{ type: 'text', text: `report export failed: ${value.error}` }]
+          const content = typeof value.content === 'string' ? value.content : ''
+          const header = [
+            `report: ${String(value.format ?? 'markdown')} · ${String(value.findings ?? 0)} findings · source=${String(value.source ?? 'empty')}`,
+            value.written ? `written to ${String(value.reportPath ?? '')}` : '',
+          ].filter(Boolean).join(' · ')
+          return [{ type: 'text', text: `${header}\n\n${content}` }]
+        },
+      },
+
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
+        if (!resolved.ok) return { ok: false, kind: 'report', error: resolved.reason }
+        const projectRoot = resolved.root
+
+        const rawFormat = typeof args.format === 'string' ? args.format : 'markdown'
+        const format = FORMATS.has(rawFormat) ? rawFormat : 'markdown'
+        const lang = args.lang === 'en' ? 'en' : 'zh'
+
+        const { manifest, source } = readManifest(projectRoot)
+        let qualityGate: unknown = null
+        let experienceBank: unknown = null
+        let defenseEvents: unknown = null
+        try {
+          qualityGate = readQualityGate(projectRoot)
+        } catch {
+          qualityGate = null
+        }
+        try {
+          experienceBank = readExperienceBank(projectRoot)
+        } catch {
+          experienceBank = null
+        }
+        try {
+          defenseEvents = readDefenseEvents(projectRoot)
+        } catch {
+          defenseEvents = null
+        }
+
+        const extra = { qualityGate, experienceBank, defenseEvents }
+        let content: string
+        let sarif: JsonValue | undefined
+        let findings = 0
+        try {
+          if (format === 'sarif') {
+            const doc = renderRunReportSarif(manifest, extra, {
+              toolVersion: pluginVersion(),
+            }) as unknown as { runs?: Array<{ results?: unknown[] }> }
+            sarif = doc as unknown as JsonValue
+            content = JSON.stringify(doc, null, 2)
+            findings = Array.isArray(doc?.runs?.[0]?.results) ? (doc.runs[0].results as unknown[]).length : 0
+          } else {
+            content = renderRunReportMarkdown(manifest, extra, { lang }) as unknown as string
+            findings = countMarkdownFindings(content)
+          }
+        } catch (err) {
+          return {
+            ok: false,
+            kind: 'report',
+            format,
+            error: `failed to render report: ${err instanceof Error ? err.message : String(err)}`,
+          }
+        }
+
+        let written = false
+        let reportPath: string | undefined
+        if (args.write === true) {
+          try {
+            const dir = iterateDir(projectRoot)
+            mkdirSync(dir, { recursive: true })
+            reportPath = `${dir}/report.${format === 'sarif' ? 'sarif' : 'md'}`
+            writeFileSync(reportPath, content, 'utf-8')
+            written = true
+          } catch (err) {
+            return {
+              ok: false,
+              kind: 'report',
+              format,
+              error: `failed to write report: ${err instanceof Error ? err.message : String(err)}`,
+            }
+          }
+        }
+
+        return {
+          ok: true,
+          kind: 'report',
+          format,
+          content,
+          ...(sarif !== undefined ? { sarif } : {}),
+          source,
+          written,
+          ...(reportPath ? { reportPath } : {}),
+          findings,
+        }
+      },
+    }),
+  )
+}
+
+/**
+ * Best-effort plugin version for the SARIF driver. Resolved from the package
+ * manifest next to this module (`src/tools` and `dist/tools` are both two
+ * levels below the root); an unreadable/unparsable manifest yields ''.
+ */
+function pluginVersion(): string {
+  try {
+    const raw = readFileSync(new URL('../../package.json', import.meta.url), 'utf-8')
+    const pkg = JSON.parse(raw) as { version?: unknown }
+    return typeof pkg.version === 'string' ? pkg.version : ''
+  } catch {
+    return ''
+  }
+}
+
+/** Count the findings table rows in a rendered Markdown report (for the card). */
+function countMarkdownFindings(markdown: string): number {
+  const m = /##\s+.*?\((\d+)\)/.exec(markdown)
+  if (m && m[1]) {
+    const n = Number(m[1])
+    if (Number.isFinite(n)) return n
+  }
+  return 0
+}

package/src/tools/transcript.ts

@@ -24,6 +24,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { mkdir, readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { writeTextAtomicAsync } from '../atomic-fs.ts'
+import { withProjectLock } from '../file-lock.ts'
 import { dirname } from 'node:path'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import {
@@ -34,11 +35,89 @@ import { transcriptPath } from '../paths.ts'
 import { ReviewTranscriptBuilder, MAX_TIMELINE, MAX_ROUNDS, normalizeManifestBounds } from '../transcript.ts'
 import { readDecisionLogDetailed } from './decision-log.ts'
 import { readLive } from '../live.ts'
+import {
+  buildRunRecord,
+  appendRunRecord,
+  readRunRecords,
+  sessionOf,
+  type IterateRunRecord,
+  type StoredRunRecord,
+} from '../session-record.ts'
 import type {
   TranscriptManifest,
   TranscriptFix,
 } from '../types.ts'
 
+/** Severity tally over a manifest's (globally deduped) findings. */
+function severityCounts(findings: unknown): IterateRunRecord['findings'] {
+  const counts = { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
+  if (!Array.isArray(findings)) return counts
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue
+    const sev = (f as { severity?: unknown }).severity
+    counts.total++
+    if (sev === 'critical') counts.critical++
+    else if (sev === 'high') counts.high++
+    else if (sev === 'medium') counts.medium++
+    else counts.low++
+  }
+  return counts
+}
+
+/** Build the compact session-linked record from a finished manifest. */
+function runRecordFromManifest(
+  manifest: TranscriptManifest,
+  qualityStatus: 'pass' | 'fail' | 'pending' | null = null,
+): IterateRunRecord {
+  return buildRunRecord({
+    project: manifest.project,
+    goal: manifest.goal,
+    mode: manifest.mode,
+    taskMode: manifest.taskMode,
+    round: manifest.round,
+    maxRounds: manifest.maxRounds,
+    active: manifest.active,
+    stoppedReason: manifest.stoppedReason,
+    convergence: manifest.convergence,
+    counts: severityCounts(manifest.findings),
+    fixedCount: Array.isArray(manifest.fixes) ? manifest.fixes.filter((f) => f.success !== false).length : 0,
+    qualityStatus,
+  })
+}
+
+/**
+ * Rebuild a (summary-only) transcript manifest from a session-linked record.
+ *
+ * Degraded by design: the record carries the run SUMMARY (mode / goal / round /
+ * max-rounds / end state / convergence series), not the per-finding detail, so
+ * the recovered manifest has an empty `findings`/`fixes`/`timeline`. It exists
+ * so the observatory shows the real run header + trend after `.iterate/` is
+ * lost, instead of a blank panel. Round rows stay empty because the record has
+ * no per-thread narration.
+ */
+export function recoverManifestFromRecord(
+  record: IterateRunRecord,
+  fallbackProject: string,
+  approval: 'ask' | 'deny' | 'allow',
+): TranscriptManifest {
+  const builder = new ReviewTranscriptBuilder({
+    project: record.project || fallbackProject,
+    mode: record.mode,
+    taskMode: record.taskMode,
+    approval,
+    goal: record.goal,
+    maxRounds: record.maxRounds,
+  })
+  const series = Array.isArray(record.convergence) ? record.convergence : []
+  for (let i = 0; i < Math.min(series.length, MAX_ROUNDS); i += 1) {
+    const n = series[i]
+    if (typeof n === 'number' && Number.isFinite(n) && n >= 0) builder.snapshotConvergence(i + 1, n)
+  }
+  if (record.round > 0) builder.advanceRound(record.round, record.maxRounds)
+  if (!record.active) builder.finish(record.stoppedReason ?? undefined)
+  return builder.serialize()
+}
+
 /** Build per-dimension threads for one round from its (dimension-tagged) findings. */
 function captureRound(builder: ReviewTranscriptBuilder, round: unknown): void {
   if (!round || typeof round !== 'object') return
@@ -81,7 +160,7 @@ function normalizeCheckpoint(input: unknown): TranscriptManifest['checkpoint'] {
   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',
+    mode: c.mode === 'dry-run' || c.mode === 'normal' ? c.mode : null,
     round,
     maxRounds: typeof c.maxRounds === 'number' && Number.isFinite(c.maxRounds) ? c.maxRounds : 0,
     fixedCount: typeof c.fixedCount === 'number' && Number.isFinite(c.fixedCount) ? c.fixedCount : 0,
@@ -157,27 +236,37 @@ export function registerTranscriptTool(ctx: {
   ctx.tools.register(
     defineTool({
       name: 'iterate_transcript',
-      // `read` never writes; `capture`/`nudge` persist transcript state → only
-      // read joins a parallel dispatch group.
-      isConcurrencySafe: (args) => (args as { operation?: unknown }).operation === 'read',
+      // `read`/`recall` never write; `capture`/`nudge` persist transcript state
+      // → only the read shapes join a parallel dispatch group.
+      isConcurrencySafe: (args) => {
+        const op = (args as { operation?: unknown }).operation
+        return op === 'read' || op === 'recall'
+      },
       description:
         'Runtime-observatory transcript for the iterate workflow. ' +
         '`read` returns the current persisted transcript manifest (per-reviewer threads, ' +
         'convergence series, findings, fixes, checkpoint, timeline, and any steering nudge ' +
         'written for the next round) — or, when the file is missing/malformed, a structured ' +
-        'empty view (`found:false` plus a blank manifest). ' +
+        'empty view (`found:false` plus a blank manifest). When the on-disk file is gone but the ' +
+        'session carries a linked run record (dsh ≥ 0.2.1-rc.1), `read` RECOVERS a summary manifest ' +
+        'from that record and sets `recovered:true`. ' +
         '`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?}). ' +
+        'On a successful capture the tool ALSO appends a compact run record onto the dsh session log ' +
+        '(best-effort; reported as `sessionRecord`) so the run survives `.iterate/` loss and travels with ' +
+        'the session. ' +
+        '`recall` lists the session-linked run records (newest first) — useful to audit a run after ' +
+        'restart or to confirm the write took. ' +
         '`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: {
           type: 'string',
           required: true,
-          description: '"read" to fetch the manifest, "capture" to persist one, "nudge" to set steering text.',
-          enum: ['read', 'capture', 'nudge'],
+          description: '"read" to fetch the manifest, "capture" to persist one, "recall" to list session-linked run records, "nudge" to set steering text.',
+          enum: ['read', 'capture', 'recall', 'nudge'],
         },
         rounds: {
           type: 'json',
@@ -215,7 +304,22 @@ export function registerTranscriptTool(ctx: {
             '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).' },
+        stoppedReason: {
+          type: 'string',
+          // Enum guard: the label renderer keys off this value, so a stray or
+          // prototype-chain string (e.g. "__proto__") must not enter the tool.
+          // The render path additionally uses Object.hasOwn (defense for
+          // hand-edited manifests that bypass this schema).
+          enum: [
+            'converged',
+            'max_rounds_reached',
+            'aborted_by_validation',
+            'aborted_by_config',
+            'schema_invalid',
+            'no_usable_reviewer_output',
+            'inconclusive',
+          ],
+          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).' },
         // `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}`.
@@ -245,6 +349,19 @@ export function registerTranscriptTool(ctx: {
               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.' },
+            recovered: {
+              type: 'boolean',
+              description: 'For `read`: true when the manifest was rebuilt from a session-linked run record because the on-disk file was missing or unreadable.',
+            },
+            supported: {
+              type: 'boolean',
+              description: 'For `recall`: whether the host exposes the dsh session state-record API (dsh ≥ 0.2.1-rc.1).',
+            },
+            records: { type: 'json', description: 'For `recall`: session-linked run records, newest first.' },
+            sessionRecord: {
+              type: 'json',
+              description: 'For `capture`/`read`: the session-link outcome/position (`{linked, seq}` on capture, `{seq, updatedAt}` on a recovery).',
+            },
             error: { type: 'string' },
           },
         },
@@ -280,11 +397,59 @@ export function registerTranscriptTool(ctx: {
               approval,
             }).serialize() as unknown as JsonValue,
           })
-          if (!existsSync(file)) return emptyView()
+          // Recovery (dsh ≥ 0.2.1-rc.1): when the on-disk manifest is gone
+          // but the SESSION that produced the run carries a linked run record,
+          // rebuild a summary manifest so the observatory shows the real run
+          // header + trend instead of a blank panel. Best-effort: no session,
+          // no API, or no record all fall back to `emptyView()`.
+          const recover = async ():
+            | Promise<{ transcript: JsonValue; sessionRecord: JsonValue } | null> => {
+            const session = sessionOf(exec)
+            if (!session) return null
+            const { supported, records } = await readRunRecords(session)
+            if (!supported || records.length === 0) return null
+            const latest = records[records.length - 1] as StoredRunRecord
+            return {
+              transcript: normalizeManifestBounds(
+                recoverManifestFromRecord(latest, projectRoot, approval),
+              ) as unknown as JsonValue,
+              sessionRecord: {
+                seq: latest.seq,
+                time: latest.time,
+                updatedAt: latest.updatedAt,
+              } as unknown as JsonValue,
+            }
+          }
+          if (!existsSync(file)) {
+            const recovered = await recover()
+            if (recovered) {
+              return {
+                operation: 'read',
+                found: true,
+                recovered: true,
+                live: live as unknown as JsonValue,
+                transcript: recovered.transcript,
+                sessionRecord: recovered.sessionRecord,
+              }
+            }
+            return emptyView()
+          }
           let parsed: unknown
           try {
             parsed = JSON.parse(await readFile(file, 'utf-8'))
           } catch (err) {
+            const recovered = await recover()
+            if (recovered) {
+              return {
+                operation: 'read',
+                found: true,
+                recovered: true,
+                live: live as unknown as JsonValue,
+                transcript: recovered.transcript,
+                sessionRecord: recovered.sessionRecord,
+                error: `Recovered a summary from the session log; on-disk transcript was unreadable (${err instanceof Error ? err.message : String(err)}).`,
+              }
+            }
             return {
               ...emptyView(),
               error: `Failed to read transcript: ${err instanceof Error ? err.message : String(err)}`,
@@ -294,6 +459,18 @@ export function registerTranscriptTool(ctx: {
             // `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.
+            const recovered = await recover()
+            if (recovered) {
+              return {
+                operation: 'read',
+                found: true,
+                recovered: true,
+                live: live as unknown as JsonValue,
+                transcript: recovered.transcript,
+                sessionRecord: recovered.sessionRecord,
+                error: 'Recovered a summary from the session log; on-disk file is not a valid manifest.',
+              }
+            }
             return {
               ...emptyView(),
               error: 'Transcript file is not a valid manifest; returning an empty view.',
@@ -310,50 +487,79 @@ export function registerTranscriptTool(ctx: {
           }
         }
 
+        if (args.operation === 'recall') {
+          // New capability: list the run records this plugin appended onto the
+          // dsh session log (dsh ≥ 0.2.1-rc.1). Read-only; degrades to
+          // `supported:false` on a host without the API.
+          const session = sessionOf(exec)
+          const { supported, records, error } = await readRunRecords(session)
+          const newestFirst = [...records].reverse()
+          return {
+            operation: 'recall',
+            found: newestFirst.length > 0,
+            supported,
+            records: newestFirst as unknown as JsonValue,
+            ...(error ? { error } : {}),
+          }
+        }
+
         if (args.operation === 'nudge') {
-          let manifest: TranscriptManifest | null = null
-          if (existsSync(file)) {
-            try {
-              const parsed = JSON.parse(await readFile(file, 'utf-8')) as unknown as TranscriptManifest
-              manifest = parsed
-            } catch {
-              manifest = null
+          // Read-modify-write across processes: a concurrent nudge in a sibling
+          // process would otherwise read the same manifest and write back over
+          // each other's steering text. Serialize on the shared transcript lock
+          // (same pattern as the config/triage writers). The body still awaits,
+          // so the lock is held across the read and write; a same-process
+          // re-entry degrades to unlocked (the advisory lock is per-pid), which
+          // is the documented best-effort fallback for a low-value projection.
+          return withProjectLock(projectRoot, 'transcript', async () => {
+            let manifest: TranscriptManifest | null = null
+            if (existsSync(file)) {
+              try {
+                const parsed = JSON.parse(await readFile(file, 'utf-8')) as unknown as TranscriptManifest
+                manifest = parsed
+              } catch {
+                manifest = null
+              }
             }
-          }
-          // Rehydrating a parsed-but-malformed manifest (e.g. `rounds: [null]`
-          // or a non-object) must never crash the nudge — degrade to a fresh
-          // builder so the steering text still lands. The fallback must keep
-          // the ORIGINAL run identity (mode/taskMode/goal/maxRounds) so a
-          // stray malformed field can never silently rewrite a dry-run run
-          // into a `normal` one.
-          const fallbackOpts = {
-            project: projectRoot,
-            mode: (manifest?.mode === 'dry-run' || manifest?.mode === 'normal' ? manifest.mode : null) as 'dry-run' | 'normal' | null,
-            taskMode: (manifest?.taskMode === 'code' || manifest?.taskMode === 'iterate' ? manifest.taskMode : null) as 'code' | 'iterate' | null,
-            approval,
-            goal: typeof manifest?.goal === 'string' ? manifest.goal : '',
-            maxRounds: typeof manifest?.maxRounds === 'number' ? manifest.maxRounds : 0,
-          }
-          let builder: ReviewTranscriptBuilder
-          if (manifest) {
-            try {
-              builder = rehydrateBuilder(manifest, approval)
-            } catch {
-              builder = new ReviewTranscriptBuilder(fallbackOpts)
+            // Rehydrating a parsed-but-malformed manifest (e.g. `rounds: [null]`
+            // or a non-object) must never crash the nudge — degrade to a fresh
+            // builder so the steering text still lands. The fallback must keep
+            // the ORIGINAL run identity (mode/taskMode/goal/maxRounds) so a
+            // stray malformed field can never silently rewrite a dry-run run
+            // into a `normal` one.
+            const fallbackOpts = {
+              project: projectRoot,
+              mode: (manifest?.mode === 'dry-run' || manifest?.mode === 'normal' ? manifest.mode : null) as 'dry-run' | 'normal' | null,
+              taskMode: (manifest?.taskMode === 'code' || manifest?.taskMode === 'iterate' ? manifest.taskMode : null) as 'code' | 'iterate' | null,
+              approval,
+              goal: typeof manifest?.goal === 'string' ? manifest.goal : '',
+              maxRounds: typeof manifest?.maxRounds === 'number' ? manifest.maxRounds : 0,
             }
-          } else {
-            builder = new ReviewTranscriptBuilder({ project: projectRoot, mode: 'normal', approval })
-          }
-          builder.setNudge(typeof args.text === 'string' && args.text.trim() ? args.text : null)
-          const persisted = await persistChecked(file, builder.serialize())
-          if (!persisted.ok) {
-            return { operation: 'nudge', updated: false, error: persisted.error }
-          }
-          return {
-            operation: 'nudge',
-            updated: true,
-            transcript: builder.serialize() as unknown as JsonValue,
-          }
+            let builder: ReviewTranscriptBuilder
+            if (manifest) {
+              try {
+                builder = rehydrateBuilder(manifest, approval)
+              } catch {
+                builder = new ReviewTranscriptBuilder(fallbackOpts)
+              }
+            } else {
+              // No manifest yet: the run's mode is genuinely unknown at nudge
+              // time (capture sets it). Recording `mode: 'normal'` here would
+              // rewrite a dry-run run into a `normal` one in the status/badge
+              // until capture lands — `null` honestly says "not captured yet".
+              builder = new ReviewTranscriptBuilder({ project: projectRoot, mode: null, approval })
+            }
+            builder.setNudge(typeof args.text === 'string' && args.text.trim() ? args.text : null)
+            const persisted = await persistChecked(file, builder.serialize())
+            if (!persisted.ok) {
+              return { operation: 'nudge', updated: false, error: persisted.error }
+            }
+            return {
+              operation: 'nudge',
+              updated: true,
+              transcript: builder.serialize() as unknown as JsonValue,
+            }
+          })
         }
 
         // capture
@@ -469,17 +675,30 @@ export function registerTranscriptTool(ctx: {
         else if (convergence.length > 0 && last === 0) builder.finish('converged')
         else if (roundsExecuted > 0) builder.finish('max_rounds_reached')
 
-        const persisted = await persistChecked(file, builder.serialize())
+        const manifest = builder.serialize()
+        const persisted = await persistChecked(file, manifest)
         if (!persisted.ok) {
           return { operation: 'capture', found: true, updated: false, error: persisted.error }
         }
+        // Session link (dsh ≥ 0.2.1-rc.1): append a compact run record onto the
+        // session log so the run survives `.iterate/` loss and travels with the
+        // 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))
+        sessionRecord = (
+          linkSession.ok
+            ? { linked: true, seq: linkSession.seq }
+            : { linked: false, supported: linkSession.supported, reason: linkSession.error }
+        ) as unknown as JsonValue
         const live = await readLive(projectRoot)
         return {
           operation: 'capture',
           found: true,
           updated: true,
           live: live as unknown as JsonValue,
-          transcript: builder.serialize() as unknown as JsonValue,
+          transcript: manifest as unknown as JsonValue,
+          sessionRecord,
         }
       },
     }),