iterate-plugin 3.8.0 → 3.9.1

package/dist/tools/transcript.js

@@ -29,7 +29,78 @@ 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. */
+function severityCounts(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.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, qualityStatus = null) {
+    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, fallbackProject, approval) {
+    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, round) {
     if (!round || typeof round !== 'object')
@@ -143,26 +214,36 @@ function isManifestShaped(value) {
 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.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.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',
@@ -244,6 +325,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' },
                 },
             },
@@ -273,13 +367,59 @@ export function registerTranscriptTool(ctx) {
                         approval,
                     }).serialize(),
                 });
-                if (!existsSync(file))
+                // 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 () => {
+                    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];
+                    return {
+                        transcript: normalizeManifestBounds(recoverManifestFromRecord(latest, projectRoot, approval)),
+                        sessionRecord: {
+                            seq: latest.seq,
+                            time: latest.time,
+                            updatedAt: latest.updatedAt,
+                        },
+                    };
+                };
+                if (!existsSync(file)) {
+                    const recovered = await recover();
+                    if (recovered) {
+                        return {
+                            operation: 'read',
+                            found: true,
+                            recovered: true,
+                            live: live,
+                            transcript: recovered.transcript,
+                            sessionRecord: recovered.sessionRecord,
+                        };
+                    }
                     return emptyView();
+                }
                 let parsed;
                 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,
+                            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)}`,
@@ -289,6 +429,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,
+                            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.',
@@ -304,6 +456,21 @@ export function registerTranscriptTool(ctx) {
                     transcript: normalizeManifestBounds(parsed),
                 };
             }
+            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,
+                    ...(error ? { error } : {}),
+                };
+            }
             if (args.operation === 'nudge') {
                 // Read-modify-write across processes: a concurrent nudge in a sibling
                 // process would otherwise read the same manifest and write back over
@@ -480,17 +647,39 @@ export function registerTranscriptTool(ctx) {
                 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;
+            // 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 });
             const live = await readLive(projectRoot);
             return {
                 operation: 'capture',
                 found: true,
                 updated: true,
                 live: live,
-                transcript: builder.serialize(),
+                transcript: manifest,
+                sessionRecord,
             };
         },
     }));
@@ -505,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).
@@ -512,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
@@ -531,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) {