iterate-plugin 2.11.0 → 2.12.0

package/src/config-loader.ts

@@ -56,6 +56,10 @@ export function defaultConfig(): IterateConfig {
       coverage_validation: true,
       scope_chunk_size: 25,
     },
+    observatory: {
+      capture: true,
+      approval: 'ask',
+    },
   }
 }
 

package/src/index.ts

@@ -2,13 +2,15 @@
  * iterate-plugin — dsh plugin for the iterate autonomous closed-loop workflow
  *
  * Architecture:
- * - The plugin registers 13 tools (config, validate, decision-log, context, review,
- *   triage, fix, diff, rollback, checkpoint, status, history, prune)
+ * - The plugin registers 14 tools (config, validate, decision-log, context, review,
+ *   triage, fix, diff, rollback, checkpoint, status, history, prune, transcript)
  * - The plugin injects a system prompt section teaching the iterate workflow pattern
  * - The model (prompted by the skill) writes a workflow script using dsh's `workflow` tool
  * - The workflow script uses `agent()` / `parallel()` / `phase()` / `log()` to orchestrate
- * - Subagents use the 13 tools to do real work (read config, run validation, log decisions,
- *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune)
+ * - Subagents use the 14 tools to do real work (read config, run validation, log decisions,
+ *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune, transcript)
+ * - A `tools/pre-execute` hook gates destructive iterate calls behind human approval
+ *   (F8 observatory approval policy: ask / deny / allow).
  *
  * Tool invocation model:
  * - Workflow script CANNOT call tools directly (sandboxed vm, no Node API)
@@ -34,13 +36,16 @@ import { registerFixTool, registerDiffTool, registerRollbackTool } from './tools
 import { registerCheckpointTool, registerStatusTool } from './tools/checkpoint.ts'
 import { registerHistoryTool } from './tools/history.ts'
 import { registerPruneTool } from './tools/prune.ts'
+import { registerTranscriptTool } from './tools/transcript.ts'
+import { registerSessionHooks } from './session-hooks.ts'
+import { registerLiveCapture } from './live.ts'
 import { ITERATE_SKILL_PROMPT } from './skill-prompt.ts'
 
 export const name = 'iterate-plugin'
-export const inject = ['tools', 'systemPrompt']
+export const inject = ['tools', 'systemPrompt'] as const
 
 export function apply(ctx: Context): void {
-  // 1. Register the 13 tools
+  // 1. Register the 14 tools
   registerConfigTool(ctx)
   registerValidateTool(ctx)
   registerDecisionLogTool(ctx)
@@ -54,6 +59,12 @@ export function apply(ctx: Context): void {
   registerStatusTool(ctx)
   registerHistoryTool(ctx)
   registerPruneTool(ctx)
+  registerTranscriptTool(ctx)
+
+  // 2. Wire the observatory approval gate onto dsh's tools/pre-execute waterfall,
+  //    and the live reviewer-activity feed onto tools/result.
+  registerSessionHooks(ctx)
+  registerLiveCapture(ctx)
 
   // 2. Inject the iterate skill prompt as a system prompt section
   // This teaches the model how to write iterate workflow scripts using the tools.

package/src/live.ts

@@ -0,0 +1,185 @@
+/**
+ * src/live.ts — live reviewer-activity feed for the iterate observatory (F1 live).
+ *
+ * Watches `tools/result` and, for tool calls we can attribute to a project root
+ * (the caller agent's session cwd), appends one line to an append-only NDJSON
+ * file `.iterate/transcript-live.ndjson`. The `iterate_transcript` tool then
+ * mixes the most recent entries into its `read` / `capture` results so the
+ * client observatory shows what reviewers are doing in near-real-time (which
+ * files they read, which fixes/rollbacks/diffs land, where the run is).
+ *
+ * Why project-scoped (not per-thread):
+ *   Tool executions carry the calling agent's session cwd but NOT the workflow
+ *   sub-agent's `dimension` / `round` label, so we cannot reliably attribute a
+ *   read to a specific reviewer thread without inventing data. We therefore
+ *   record honest project-level activity and never fabricate an attribution.
+ *   Per-thread narration stays the job of the final `iterate_transcript capture`.
+ *
+ * Safety:
+ *   - Read-only observer: never mutates source files; writes only the NDJSON
+ *     live file under `.iterate/`.
+ *   - The live file is byte-capped (rewrite to last N lines when it grows too
+ *     large) so it can never grow unbounded.
+ *   - Any capture failure is swallowed (fire-and-forget) so it can never block
+ *     or crash a tool call.
+ */
+
+import { mkdir, readFile, writeFile, stat, appendFile, rename } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import type { ToolExecution } from '@deepseek-ai/dsh-tools'
+import { resolveProjectRoot } from './config-loader.ts'
+
+/** Keep at most this many live activity entries. */
+export const LIVE_MAX_ENTRIES = 300
+/** Rewrite the live file when its byte size exceeds this threshold. */
+export const LIVE_MAX_BYTES = 64 * 1024
+
+/** One live activity record. */
+export interface LiveActivityEntry {
+  /** ISO 8601 timestamp of the tool result. */
+  ts: string
+  /** Coarse category used by the client for coloring/grouping. */
+  type:
+    | 'read'
+    | 'fix'
+    | 'rollback'
+    | 'diff'
+    | 'review'
+    | 'triage'
+    | 'checkpoint'
+    | 'validate'
+    | 'log'
+    | 'prune'
+    | 'info'
+  /** The tool that produced the activity. */
+  tool: string
+  /**
+   * The affected target: a source file path (relative to project root) for
+   * read/fix/rollback/diff, else a summary string (e.g. the review operation).
+   */
+  target: string
+}
+
+/** File path of the live NDJSON feed for a project root. */
+export function liveFilePath(projectRoot: string): string {
+  return join(projectRoot, '.iterate', 'transcript-live.ndjson')
+}
+
+/** Resolve the project root a tool execution belongs to, if any. */
+function projectRootOf(exec: ToolExecution): string | null {
+  const cwd = exec.agent?.session?.header?.cwd
+  if (!cwd) return null
+  const resolved = resolveProjectRoot(undefined, cwd)
+  return resolved.ok ? resolved.root : null
+}
+
+/** Classify a settled tool call into a live activity entry, or null to skip. */
+export function classifyTool(
+  name: string,
+  args: unknown,
+  projectRoot: string,
+): LiveActivityEntry | null {
+  // `read_file` is the dsh-native file reader reviewers use to inspect code.
+  if (name === 'read_file') {
+    const file =
+      args && typeof args === 'object' && typeof (args as Record<string, unknown>).path === 'string'
+        ? (args as Record<string, unknown>).path as string
+        : ''
+    return file ? { ts: new Date().toISOString(), type: 'read', tool: name, target: file } : null
+  }
+
+  // The iterate plugin's own tools — surface what the workflow is doing live.
+  const records: Record<string, LiveActivityEntry['type']> = {
+    iterate_fix: 'fix',
+    iterate_rollback: 'rollback',
+    iterate_diff: 'diff',
+    iterate_review: 'review',
+    iterate_triage: 'triage',
+    iterate_checkpoint: 'checkpoint',
+    iterate_validate: 'validate',
+    iterate_decision_log: 'log',
+    iterate_history: 'info',
+    iterate_prune: 'prune',
+    iterate_transcript: 'log',
+    iterate_status: 'info',
+    iterate_config: 'info',
+    iterate_context: 'info',
+  }
+  const type = records[name]
+  if (!type) return null
+
+  let target = ''
+  if (args && typeof args === 'object') {
+    const a = args as Record<string, unknown>
+    if (typeof a.file === 'string' && a.file) target = a.file
+    else if (typeof a.path === 'string' && a.path) target = a.path
+    else if (typeof a.operation === 'string' && a.operation) target = a.operation
+    else if (name === 'iterate_rollback' && typeof a.id === 'string' && a.id) {
+      target = `fix ${a.id}`
+    }
+  }
+  if (!target) target = name
+  return { ts: new Date().toISOString(), type, tool: name, target }
+}
+
+/** Append one activity record to the project's live feed (byte-capped). */
+export async function appendLive(projectRoot: string, entry: LiveActivityEntry): Promise<void> {
+  const file = liveFilePath(projectRoot)
+  const line = JSON.stringify(entry) + '\n'
+  await mkdir(join(projectRoot, '.iterate'), { recursive: true })
+  // Amortized O(1): only read+rewrite when the file has grown past the cap.
+  try {
+    const st = await stat(file).catch(() => null)
+    if (st && st.size > LIVE_MAX_BYTES) {
+      const raw = await readFile(file, 'utf-8')
+      const lines = raw.split('\n').filter(Boolean)
+      const tail = lines.slice(-LIVE_MAX_ENTRIES)
+      const tmp = `${file}.trim.tmp`
+      await writeFile(tmp, tail.join('\n') + '\n', 'utf-8')
+      await rename(tmp, file)
+    }
+    await appendFile(file, line, 'utf-8')
+  } catch {
+    // Fire-and-forget: never let live capture break a tool call.
+  }
+}
+
+/** Read the live feed (newest first), capped at the last LIVE_MAX_ENTRIES. */
+export async function readLive(projectRoot: string): Promise<LiveActivityEntry[]> {
+  const file = liveFilePath(projectRoot)
+  if (!existsSync(file)) return []
+  try {
+    const raw = await readFile(file, 'utf-8')
+    const entries: LiveActivityEntry[] = []
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue
+      try {
+        const parsed = JSON.parse(line) as LiveActivityEntry
+        if (parsed && typeof parsed.ts === 'string' && typeof parsed.type === 'string') {
+          entries.push(parsed)
+        }
+      } catch {
+        // skip malformed lines
+      }
+    }
+    return entries.slice(-LIVE_MAX_ENTRIES).reverse()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Register a `tools/result` observer that captures reviewer activity into the
+ * project's live feed. Fire-and-forget; failures are swallowed.
+ */
+export function registerLiveCapture(ctx: Context): void {
+  ctx.on('tools/result', (exec: ToolExecution) => {
+    const root = projectRootOf(exec)
+    if (!root) return
+    const entry = classifyTool(exec.name, exec.arguments, root)
+    if (!entry) return
+    void appendLive(root, entry)
+  })
+}

package/src/paths.ts

@@ -36,3 +36,8 @@ export function fixBackupPath(projectRoot: string, id: string, timestamp: string
 export function checkpointPath(projectRoot: string): string {
   return join(iterateDir(projectRoot), 'checkpoint.json')
 }
+
+/** Runtime-observatory transcript file (JSON). */
+export function transcriptPath(projectRoot: string): string {
+  return join(iterateDir(projectRoot), 'transcript.json')
+}

package/src/session-hooks.ts

@@ -0,0 +1,90 @@
+/**
+ * src/session-hooks.ts — dsh pipeline hooks for the iterate observatory (F8).
+ *
+ * Wires the {@link decideApproval} policy gate to dsh's `tools/pre-execute`
+ * waterfall. This is the AUTHORITATIVE approval seam for destructive iterate
+ * tools (`iterate_fix` / `iterate_rollback` / `iterate_prune` with dryRun:false):
+ *
+ *   - `allow` policy      → the call runs.
+ *   - `deny`  policy      → the call is refused (fail-closed), surfaced as an
+ *                           error to the model.
+ *   - `ask`   policy      → return `{ kind: 'ask', reason }`; dsh's own
+ *                           scheduler routes it through the `approval` service
+ *                           (see `@deepseek-ai/dsh-user-approval`), which
+ *                           prompts the human and audits an approve/deny pair
+ *                           on the session.
+ *
+ * We deliberately do NOT also add `approved` flags inside the tool bodies:
+ * the pre-execute waterfall consumes the human decision before the tool runs,
+ * so a second tool-internal gate would double-ask. This one gate is enough and
+ * stays dsh-native.
+ *
+ * Safety properties:
+ *   - Read-only tools and non-iterate tools are always allowed (the gate only
+ *     inspects the three destructive iterate toolnames).
+ *   - If the project root / observatory config cannot be resolved, the policy
+ *     degrades to `ask` (fail-safe: destructive writes always require consent).
+ */
+
+import { loadEffectiveConfig, resolveProjectRoot } from './config-loader.ts'
+import { decideApproval, isDestructiveIterateTool } from './approval-gate.ts'
+import type { Context } from '@deepseek-ai/cordis'
+import type { ToolExecution, PreToolDecision } from '@deepseek-ai/dsh-tools'
+
+/**
+ * Build the per-call approval decision for a tool execution.
+ * Returns a dsh `PreToolDecision` so the caller can short-circuit the caller.
+ */
+export function gateDecision(exec: ToolExecution): PreToolDecision {
+  // Importing the decision, and only inspecting our own tools, keeps unrelated
+  // tooling untouched. Anything we cannot classify is allowed by default.
+  if (!isDestructiveIterateTool(exec.name)) return { kind: 'allow' }
+
+  // Resolve the project root (use the call's own `path` arg, else the agent's
+  // session cwd) to read the effective observatory policy.
+  const argPath = typeof exec.arguments === 'object' && exec.arguments && !Array.isArray(exec.arguments)
+    && typeof (exec.arguments as Record<string, unknown>).path === 'string'
+    ? (exec.arguments as Record<string, unknown>).path as string
+    : undefined
+  const sessionCwd = exec.agent?.session?.header?.cwd
+  const resolved = resolveProjectRoot(argPath, sessionCwd)
+  let policy: 'ask' | 'deny' | 'allow' = 'ask'
+  if (resolved.ok) {
+    const { config } = loadEffectiveConfig(resolved.root)
+    const p = config.observatory?.approval
+    if (p === 'deny') policy = 'deny'
+    else if (p === 'allow') policy = 'allow'
+    // anything else (including a corrupt/missing `ask`) → 'ask'
+  }
+
+  const decision = decideApproval(exec, policy)
+  if (decision.kind === 'deny') return { kind: 'deny', reason: decision.reason }
+  if (decision.kind === 'ask') return { kind: 'ask', reason: decision.reason }
+  return { kind: 'allow' }
+}
+
+/**
+ * Register the `tools/pre-execute` waterfall listener that applies the
+ * observatory approval gate to every destructive iterate tool call.
+ */
+export function registerSessionHooks(ctx: Context): void {
+  ctx.on('tools/pre-execute', (exec: ToolExecution, next: () => Promise<PreToolDecision>) => {
+    // Never let a throwing gate break the pipeline — degrade to allow.
+    let decision: PreToolDecision
+    try {
+      decision = gateDecision(exec)
+    } catch {
+      return next()
+    }
+    if (decision.kind === 'ask') {
+      // Delegate the actual human-consent prompt + audit to dsh's approval
+      // service via the scheduler's `ask` path. `next()` here would short-circuit
+      // to allow, which would bypass consent — so return our ask decision.
+      return Promise.resolve(decision)
+    }
+    if (decision.kind === 'deny') {
+      return Promise.resolve(decision)
+    }
+    return next()
+  })
+}

package/src/skill-prompt.ts

@@ -23,6 +23,7 @@ You have the iterate plugin installed, which registers these tools:
 - \`iterate_status\` — summarize the current run: mode, round, fixes applied, architectural remaining, decision-log size, checkpoint presence, and whether the run was interrupted (a checkpoint left on disk means the previous run was interrupted and can be resumed)
 - \`iterate_history\` — inspect the runtime state in detail: decision-log entries and applied fixes (optionally scoped to a round or a fixed file)
 - \`iterate_prune\` — remove stale runtime artifacts (\`.iterate/\` entries). Defaults to a read-only dry-run that reports what WOULD be removed; pass \`dryRun:false\` to actually prune.
+- \`iterate_transcript\` — runtime observatory file (\`.iterate/transcript.json\`). \`read\` fetches the persisted manifest including any steering \`nudge\` for this run's reviewers; \`capture\` (call once after the final report) persists the per-reviewer threads, convergence trend, findings, fixes, checkpoint, and timeline so the client observatory panel reflects the run; \`nudge\` sets/clears steering text the next round's reviewers read. Purely local, never touches source files.
 
 ### When to use
 When the user asks to review or iterate on the project (e.g. "review this project", "iterate on error handling", "check the codebase for issues", "dry-run review", "反复审查"), run an iterate **workflow** by calling the \`workflow\` tool.
@@ -78,6 +79,14 @@ const knownIntentional = (plan.knownIntentional || [])   // config personalizati
 let known = []              // cumulative DEDUPED findings fed back to reviewers
 const rounds = []           // raw per-round findings
 
+phase('transcript')
+// Read any steering nudge written (via iterate_transcript nudge) for this run's reviewers.
+const transRead = await agent(
+  'Call iterate_transcript({operation:"read"}) and return {nudge:<transcript.nudge ? transcript.nudge.text : null>}.',
+  Object.assign({ label: 'transcript:read' }, backend)
+)
+const steering = transRead && typeof transRead.nudge === 'string' && transRead.nudge ? transRead.nudge : null
+
 phase('review')
 for (let r = 1; r <= maxRounds; r++) {
   log('round ' + r + ' of ' + maxRounds + ' — finding NEW issues only')
@@ -99,6 +108,7 @@ for (let r = 1; r <= maxRounds; r++) {
         ? meta.reviewerPrompt
         : 'Review dimension "' + dim + '".'
       const extra =
+        (steering ? '\\n STEERING — read this first: ' + steering : '') +
         (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
         '\\n Already-known findings (do NOT re-report): ' +
         JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.'
@@ -157,6 +167,13 @@ const metaRes = await agent(
 const finalReport = metaRes && metaRes.finalReport ? metaRes.finalReport : null
 const metaAudit = finalReport && finalReport.metaReview ? finalReport.metaReview : null
 
+// Persist the run's observatory transcript (reviewer threads, trend, findings)
+// so the client observatory panel reflects this review. Writes ONLY .iterate/transcript.json.
+await agent(
+  'Call iterate_transcript({operation:"capture", mode:"dry-run", goal:' + JSON.stringify(report.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + report.convergence.totalRounds + ', findingsByRound:' + JSON.stringify(report.convergence.findingsByRound || []) + ', rounds:' + JSON.stringify(rounds.map(rr => ({ round: rr.round, findings: rr.findings, readFiles: rr.readFiles }))) + '}). Return {operation:"ok"}.',
+  Object.assign({ label: 'transcript:capture' }, backend)
+)
+
 return {
   mode: 'dry-run',
   goal: report.goal,
@@ -181,7 +198,7 @@ Key rules for dry-run:
 - Stop when a round reports 0 new findings (converged) or maxReviewRounds is reached.
 - The report (with per-round convergence stats + suggested fix priorities) is the deliverable.
 - **Meta-review**: after building the report, audit it with \`iterate_review({operation:"meta-review"})\` for internal consistency (counts, severity buckets, dimension sums, sort order, convergence math). The meta-review ALSO runs the hard code-evidence gate (default on): every finding's file/line is validated against real files on disk, so any fabricated location surfaces as a critical \`EVIDENCE_VIOLATION\` and flips the verdict to \`needs_revision\`. The \`finalReport.verdict\` is \`approved\` only when the report passes every check AND every finding anchors to real, read code; otherwise \`needs_revision\`. Surface the final report and its verdict as the closing deliverable.
-- Only a single \`report\` entry may be appended to the decision log; nothing else is written.
+- Only a single \`report\` entry may be appended to the decision log; nothing else is written to source files. The final \`iterate_transcript capture\` writes ONLY the observatory file (\`.iterate/transcript.json\`) so the client panel reflects the run — it is not a source-code write.
 
 ### Normal-mode workflow (autonomous closed loop)
 Set \`args.mode = "normal"\`. Loop: resume → plan → parallel review ×N → atomic fixes via \`iterate_fix\` → validate → rollback on failure → checkpoint → loop → auto-stop when zero findings remain.
@@ -239,6 +256,14 @@ let fixedCount = (checkpoint && typeof checkpoint.fixedCount === 'number') ? che
 let converged = false
 let abortedByValidation = false
 let failedCommands = []
+const fixRecords = []        // observatory fix records collected round by round
+
+// Read any steering nudge intended for this run's reviewers.
+const transRead = await agent(
+  'Call iterate_transcript({operation:"read"}) and return {nudge:<transcript.nudge ? transcript.nudge.text : null>}.',
+  Object.assign({ label: 'transcript:read' }, backend)
+)
+const steering = transRead && typeof transRead.nudge === 'string' && transRead.nudge ? transRead.nudge : null
 
 phase('loop')
 for (let r = startRound; r <= maxRounds; r++) {
@@ -265,6 +290,7 @@ for (let r = startRound; r <= maxRounds; r++) {
         ? meta.reviewerPrompt
         : 'Review dimension "' + dim + '" on the CURRENT code state (previous atomic findings are fixed).'
       const extra =
+        (steering ? '\\n STEERING — read this first: ' + steering : '') +
         (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
         '\\n Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.'
       return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
@@ -309,12 +335,14 @@ for (let r = startRound; r <= maxRounds; r++) {
       'Apply the fixes for ' + file + ' using iterate_fix. For EACH finding in this list, ' +
       'read the current file, compute the edited full content (change <= ' + atomicMaxLines + ' lines), and call ' +
       'iterate_fix({ file: "' + file + '", content: <full new file content>, finding: <that finding>, round: ' + r + ' }). ' +
-      'Apply the findings IN ORDER. After all fixes, call iterate_diff({ file: "' + file + '" }) to verify the accumulated diff. ' +
-      'Findings: ' + JSON.stringify(byFile[file]) + '. Return the array of {id, ok, error} per iterate_fix call.',
+      'Apply the findings IN ORDER. After all fixes, call iterate_diff({ file: "' + file + '" }) to verify the accumulated diff and ' +
+      'read its line statistics (lines added/removed). ' +
+      'Findings: ' + JSON.stringify(byFile[file]) + '. Return the array of {id, ok, error, file, linesAdded, linesRemoved} per iterate_fix call ' +
+      '(id/ok required; put the file-wide line stats from iterate_diff on each record, or on the last record and 0 elsewhere).',
       Object.assign({ label: 'fix:' + file, phase: 'fix', schema: {
         type: 'object', additionalProperties: false,
         properties: {
-          fixes: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { id: { type: 'string' }, ok: { type: 'boolean' }, error: { type: 'string' } }, required: ['id', 'ok'] } }
+          fixes: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { id: { type: 'string' }, ok: { type: 'boolean' }, error: { type: 'string' }, file: { type: 'string' }, linesAdded: { type: 'integer' }, linesRemoved: { type: 'integer' } }, required: ['id', 'ok'] } }
         },
         required: ['fixes'] } }, backend)
     )))
@@ -322,6 +350,17 @@ for (let r = startRound; r <= maxRounds; r++) {
       if (res && Array.isArray(res.fixes)) {
         for (const fx of res.fixes) {
           if (fx && fx.ok === true) { fixedCount += 1; roundFixIds.push(fx.id) }
+          // Collect fix records for the observatory transcript (defensive defaults).
+          const fixFileKeys = Object.keys(byFile)
+          fixRecords.push({
+            id: fx && typeof fx.id === 'string' ? fx.id : '',
+            file: fx && typeof fx.file === 'string' ? fx.file : (fixFileKeys.length === 1 ? fixFileKeys[0] : ''),
+            round: r,
+            summary: '',
+            linesAdded: fx && typeof fx.linesAdded === 'number' ? fx.linesAdded : 0,
+            linesRemoved: fx && typeof fx.linesRemoved === 'number' ? fx.linesRemoved : 0,
+            success: !!(fx && fx.ok === true),
+          })
         }
       }
     }
@@ -404,6 +443,19 @@ if (!abortedByValidation) {
     { label: 'checkpoint:clear' }
   )
 }
+// Persist the run's observatory transcript (threads, trend, fixes, checkpoint)
+// so the client observatory panel reflects the run. Writes ONLY .iterate/transcript.json.
+const obsCheckpoint = abortedByValidation ? null : {
+  mode: 'normal',
+  round: rounds.length,
+  maxRounds: maxRounds,
+  fixedCount: fixedCount,
+  resumeCount: effectiveResumeCount,
+}
+await agent(
+  'Call iterate_transcript({operation:"capture", mode:"normal", goal:' + JSON.stringify(plan.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + rounds.length + ', findingsByRound:' + JSON.stringify(rounds.map(rr => (rr.findings && rr.findings.length) ? rr.findings.length : 0)) + ', fixes:' + JSON.stringify(fixRecords) + ', checkpoint:' + JSON.stringify(obsCheckpoint) + ', rounds:' + JSON.stringify(rounds.map(rr => ({ round: rr.round, findings: rr.findings, readFiles: rr.readFiles }))) + '}). Return {operation:"ok"}.',
+  { label: 'transcript:capture' }
+)
 return {
   mode: 'normal',
   goal: plan.goal,