iterate-plugin 3.7.0 → 3.9.0

package/dist/tools/transcript.js

@@ -23,12 +23,83 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { mkdir, readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { writeTextAtomicAsync } from "../atomic-fs.js";
+import { withProjectLock } from "../file-lock.js";
 import { dirname } from 'node:path';
 import { loadEffectiveConfig, resolveProjectRootForExec, } from "../config-loader.js";
 import { transcriptPath } from "../paths.js";
 import { ReviewTranscriptBuilder, MAX_TIMELINE, MAX_ROUNDS, normalizeManifestBounds } from "../transcript.js";
 import { readDecisionLogDetailed } from "./decision-log.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')
@@ -73,7 +144,7 @@ function normalizeCheckpoint(input) {
     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,
@@ -142,26 +213,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',
@@ -198,7 +279,23 @@ 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}`.
@@ -227,6 +324,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' },
                 },
             },
@@ -256,13 +366,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)}`,
@@ -272,6 +428,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.',
@@ -287,53 +455,81 @@ 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') {
-                let manifest = null;
-                if (existsSync(file)) {
-                    try {
-                        const parsed = JSON.parse(await readFile(file, 'utf-8'));
-                        manifest = parsed;
+                // 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 = null;
+                    if (existsSync(file)) {
+                        try {
+                            const parsed = JSON.parse(await readFile(file, 'utf-8'));
+                            manifest = parsed;
+                        }
+                        catch {
+                            manifest = null;
+                        }
                     }
-                    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),
+                        taskMode: (manifest?.taskMode === 'code' || manifest?.taskMode === 'iterate' ? manifest.taskMode : null),
+                        approval,
+                        goal: typeof manifest?.goal === 'string' ? manifest.goal : '',
+                        maxRounds: typeof manifest?.maxRounds === 'number' ? manifest.maxRounds : 0,
+                    };
+                    let builder;
+                    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),
-                    taskMode: (manifest?.taskMode === 'code' || manifest?.taskMode === 'iterate' ? manifest.taskMode : null),
-                    approval,
-                    goal: typeof manifest?.goal === 'string' ? manifest.goal : '',
-                    maxRounds: typeof manifest?.maxRounds === 'number' ? manifest.maxRounds : 0,
-                };
-                let builder;
-                if (manifest) {
-                    try {
-                        builder = rehydrateBuilder(manifest, approval);
+                    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 });
                     }
-                    catch {
-                        builder = new ReviewTranscriptBuilder(fallbackOpts);
+                    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 };
                     }
-                }
-                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(),
-                };
+                    return {
+                        operation: 'nudge',
+                        updated: true,
+                        transcript: builder.serialize(),
+                    };
+                });
             }
             // capture
             // `observatory.capture: false` opts the project out of transcript
@@ -450,17 +646,28 @@ 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;
+            const linkSession = await appendRunRecord(sessionOf(exec), runRecordFromManifest(manifest));
+            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,
             };
         },
     }));

package/dist/tools/triage.js

@@ -5,6 +5,7 @@ import yaml from 'js-yaml';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { writeTextAtomic } from "../atomic-fs.js";
 import { configBackupSuffix } from "../config-write.js";
+import { withProjectLock } from "../file-lock.js";
 import { WHOLE_FILE_LINE } from "../evidence.js";
 const CONFIG_FILE = 'iterate.config.yaml';
 /** Personalization key that holds the known-intentional list. */
@@ -227,58 +228,64 @@ function readConfigFile(configPath) {
 /** Apply the triage entries: backup, merge, write, rollback on failure. */
 function applyEntries(projectRoot, incoming) {
     const configPath = join(projectRoot, CONFIG_FILE);
-    let config;
-    try {
-        config = readConfigFile(configPath);
-    }
-    catch (err) {
-        // The file exists but is malformed — refuse to overwrite user data.
-        return { ok: false, error: `Failed to read config: ${String(err)}` };
-    }
-    const existing = readKnownIntentional(config);
-    const { merged, added, skipped, dropped } = mergeKnownIntentional(existing, incoming);
-    const nextConfig = buildConfigWithKnownIntentional(config, merged);
-    const hadFile = existsSync(configPath);
-    const backupPath = hadFile ? `${configPath}.bak-${backupSuffix()}` : null;
-    if (backupPath) {
+    // Serialize against `iterate_config write` (SAME lock name) so a triage apply
+    // and a config write on one project cannot interleave their read-modify-write
+    // and silently drop each other's updates. The lock spans read → merge →
+    // backup → write → backup-prune so the whole cycle is atomic.
+    return withProjectLock(projectRoot, 'config-write', () => {
+        let config;
         try {
-            copyFileSync(configPath, backupPath);
+            config = readConfigFile(configPath);
         }
         catch (err) {
-            return {
-                ok: false,
-                error: `Failed to create backup: ${String(err)}`,
-            };
+            // The file exists but is malformed — refuse to overwrite user data.
+            return { ok: false, error: `Failed to read config: ${String(err)}` };
         }
-    }
-    const yamlText = yaml.dump(nextConfig, { noRefs: true });
-    try {
-        writeTextAtomic(configPath, yamlText);
-    }
-    catch (err) {
-        // Rollback: restore the backup, or REMOVE the file we just created when
-        // there was no prior config — an empty file left behind would poison all
-        // future config reads (empty YAML is not a valid mapping).
-        let rollbackError = '';
+        const existing = readKnownIntentional(config);
+        const { merged, added, skipped, dropped } = mergeKnownIntentional(existing, incoming);
+        const nextConfig = buildConfigWithKnownIntentional(config, merged);
+        const hadFile = existsSync(configPath);
+        const backupPath = hadFile ? `${configPath}.bak-${backupSuffix()}` : null;
+        if (backupPath) {
+            try {
+                copyFileSync(configPath, backupPath);
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    error: `Failed to create backup: ${String(err)}`,
+                };
+            }
+        }
+        const yamlText = yaml.dump(nextConfig, { noRefs: true });
         try {
-            if (backupPath)
-                copyFileSync(backupPath, configPath);
-            else if (existsSync(configPath))
-                rmSync(configPath, { force: true });
+            writeTextAtomic(configPath, yamlText);
         }
-        catch (rbErr) {
-            rollbackError = `; rollback also failed: ${String(rbErr)}`;
+        catch (err) {
+            // Rollback: restore the backup, or REMOVE the file we just created when
+            // there was no prior config — an empty file left behind would poison all
+            // future config reads (empty YAML is not a valid mapping).
+            let rollbackError = '';
+            try {
+                if (backupPath)
+                    copyFileSync(backupPath, configPath);
+                else if (existsSync(configPath))
+                    rmSync(configPath, { force: true });
+            }
+            catch (rbErr) {
+                rollbackError = `; rollback also failed: ${String(rbErr)}`;
+            }
+            return {
+                ok: false,
+                error: `Failed to write config: ${String(err)}${rollbackError}`,
+            };
         }
-        return {
-            ok: false,
-            error: `Failed to write config: ${String(err)}${rollbackError}`,
-        };
-    }
-    // Success: bound the accumulation of timestamped backups so a long-lived
-    // project never collects an unbounded pile of config snapshots.
-    if (backupPath)
-        pruneOldConfigBackups(configPath);
-    return { ok: true, added, skipped, dropped, count: merged.length, configPath, backupPath };
+        // Success: bound the accumulation of timestamped backups so a long-lived
+        // project never collects an unbounded pile of config snapshots.
+        if (backupPath)
+            pruneOldConfigBackups(configPath);
+        return { ok: true, added, skipped, dropped, count: merged.length, configPath, backupPath };
+    });
 }
 /**
  * Register the `iterate_triage` tool.

package/dist/transcript.js

@@ -501,7 +501,7 @@ export class ReviewTranscriptBuilder {
             return;
         }
         this.checkpoint = {
-            mode: state.mode === 'dry-run' || state.mode === 'normal' ? state.mode : 'normal',
+            mode: state.mode === 'dry-run' || state.mode === 'normal' ? state.mode : null,
             round: typeof state.round === 'number' ? state.round : 0,
             maxRounds: typeof state.maxRounds === 'number' ? state.maxRounds : 0,
             fixedCount: typeof state.fixedCount === 'number' ? state.fixedCount : 0,
@@ -725,7 +725,7 @@ function normalizeCheckpointRow(input) {
     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: clampRoundValue(c.round),
         maxRounds: clampCountValue(c.maxRounds),
         fixedCount: clampCountValue(c.fixedCount),