@maudecode/talaria-web 1.21.0 → 1.23.2

package/dist/tools/updates.js

@@ -12,9 +12,10 @@
  */
 import { backupPersistedStores } from '../sessions/storage/json-installation.js';
 export { backupPersistedStores, CHANNEL_SWITCH_BACKUPS } from '../sessions/storage/json-installation.js';
-import { UpdatesSummarySchema } from '@maudecode/talaria-web-contracts';
+import { UpdatesSummarySchema, WebUpdateChannelSchema } from '@maudecode/talaria-web-contracts';
 import { z } from 'zod';
 import { readCapped } from '../http/capped.js';
+import { SidecarError } from '../sidecar/client.js';
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
@@ -41,6 +42,13 @@ const WEB_NPM_PACKAGE = '@maudecode/talaria-web';
 const GIT_LOCK_SIGNATURES = ["index.lock': file exists", ".lock': file exists", 'another git process seems to be running', 'unable to create .git/index.lock'];
 const NETWORK_FAILURES = ['could not resolve host', 'failed to connect', 'network is unreachable', 'no route to host', 'connection timed out', 'timed out after', 'connection reset by peer', 'remote end hung up unexpectedly', 'tls connection was non-properly terminated', 'ssl certificate problem'];
 export const normalizeChannel = (channel) => (channel === 'experimental' ? 'experimental' : 'stable');
+export const WEB_UPDATE_CHANNELS = WebUpdateChannelSchema.options;
+export const isWebChannel = (channel) => WebUpdateChannelSchema.safeParse(channel).success;
+export const normalizeWebChannel = (channel) => (isWebChannel(channel) ? channel : 'stable');
+/** TAL-1569: Nightly installs the same GHCR artifacts as Experimental, one daily `nightly` tag behind it. */
+const webFamily = (channel) => (channel === 'stable' ? 'stable' : 'experimental');
+/** A packaged `web-v` or `web-exp-v` version label of the channel's artifact family. */
+const familyVersion = (channel, label) => new RegExp(`^${webFamily(channel) === 'experimental' ? 'web-exp-v' : 'web-v'}${VERSION}$`).exec(label);
 export const ONLY_STABLE_VERSIONS = 'Choosing a version is available only on the Stable channel.';
 /** TAL-946: the release an update installs: the listed `version` (a `ref`), else the newest listed release (none when nothing is listed). */
 function selectVersion(versions, version, name) {
@@ -130,7 +138,12 @@ export function sanitizeGitDiagnostic(output, limit = 300) {
     s = s.replace(/([?&](?:access_token|oauth_token|private_token|client_secret|app_secret|api[_-]?key|token|password|secret|auth|key)=)[^&\s'"]+/gi, '$1<redacted>').trim();
     return s.length > limit ? `${s.slice(0, limit).trimEnd()}…` : s;
 }
+/** `runGit`'s marker when its own deadline killed git; libcurl's "Operation timed out after N milliseconds" stays a network failure. */
+const GIT_DEADLINE = /^git .+ timed out after (\d+(?:\.\d+)?)s$/;
 function fetchFailureMessage(out, network) {
+    const deadline = GIT_DEADLINE.exec(out.trim());
+    if (deadline)
+        return `The update check timed out after ${deadline[1] ?? ''}s. Try again.`;
     const detail = sanitizeGitDiagnostic(out);
     if (!detail)
         return network;
@@ -405,9 +418,9 @@ export function ghcrExperimental(fetchImpl) {
         return body.token;
     };
     return {
-        release: async () => {
+        release: async (channel) => {
             const auth = { Authorization: `Bearer ${await token()}` };
-            const m = await json(await send(`${GHCR}/v2/${EXPERIMENTAL_REPOSITORY}/manifests/experimental`, { headers: { ...auth, Accept: 'application/vnd.oci.image.manifest.v1+json' }, signal: AbortSignal.timeout(5000) }), 'manifest');
+            const m = await json(await send(`${GHCR}/v2/${EXPERIMENTAL_REPOSITORY}/manifests/${channel}`, { headers: { ...auth, Accept: 'application/vnd.oci.image.manifest.v1+json' }, signal: AbortSignal.timeout(5000) }), 'manifest');
             const layers = Array.isArray(m.layers) ? m.layers.map(dict) : [];
             const layer = layers[0];
             if (m.artifactType !== EXPERIMENTAL_ARTIFACT_TYPE || layers.length !== 1 || layer?.mediaType !== EXPERIMENTAL_LAYER_TYPE)
@@ -552,23 +565,51 @@ async function experimentalBuildsBehind(installed, latest, registry, getJson) {
     // ponytail: 500 commits back; an older install reports the builds within that window.
     return Math.max(1, count);
 }
-/** An npm install on Experimental: behind by its missed builds when its source differs from the `experimental` tag, or when switching channels. */
-async function checkNpmExperimental(result, installed, id, registry, getJson) {
+const CHANNEL_NAMES = { stable: 'Stable', nightly: 'Nightly', experimental: 'Experimental' };
+const AHEAD_OF_NIGHTLY = 'This npm installation is ahead of the Nightly build; it updates once Nightly passes it.';
+/**
+ * TAL-1569: whether a Nightly install (not a switch) holds a source newer than the `nightly` build. Nightly trails
+ * Experimental, so an install taken from Experimental is ahead of it and must not move back. Unorderable sources fail closed.
+ */
+async function aheadOfNightly(channel, switching, installed, nightly, getJson) {
+    if (channel !== 'nightly' || switching || !installed || installed === nightly)
+        return false;
+    let status;
+    try {
+        status = dict(await getJson(`/compare/${nightly}...${installed}`, { asset: false })).status;
+    }
+    catch {
+        status = null;
+    }
+    if (status === 'ahead')
+        return true;
+    if (status === 'behind' || status === 'diverged')
+        return false;
+    throw new ReleaseUnavailable('Cannot order this installation against the Nightly build', true);
+}
+/** An npm install on Experimental or Nightly: behind by its missed builds when its source differs from the channel's tag, or when switching from Stable. */
+async function checkNpmExperimental(result, installed, id, registry, getJson, channel) {
+    const name = CHANNEL_NAMES[channel];
     let release;
+    const disk = diskRelease(installed.packageRoot);
+    const current = str(disk?.sourceRevision ?? id.release().sourceRevision) || null;
+    const switching = npmInstallChannel(installed, id) === 'stable';
+    let ahead = false;
     try {
-        release = await registry.release();
+        release = await registry.release(channel);
+        ahead = await aheadOfNightly(channel, switching, current, release.sourceRevision, getJson);
     }
     catch (error) {
-        const unavailable = error instanceof ReleaseUnavailable ? error : new ReleaseUnavailable('The Experimental artifact is unavailable');
+        const unavailable = error instanceof ReleaseUnavailable ? error : new ReleaseUnavailable(`The ${name} artifact is unavailable`);
         return { ...result, install_kind: 'npm', manual_update: true, error: unavailable.message, ...(unavailable.transient ? { stale_check: true } : {}) };
     }
-    Object.assign(result, { latest_version: release.tag, latest_sha: release.sourceRevision, branch: 'experimental', release_based: true, no_git: true, install_kind: 'npm', manual_update: false });
-    const disk = diskRelease(installed.packageRoot);
-    const current = str(disk?.sourceRevision ?? id.release().sourceRevision) || null;
-    if (npmInstallChannel(installed, id) !== 'experimental')
-        return { ...result, current_sha: current, behind: await experimentalBuildsBehind(current, release.sourceRevision, registry, getJson), channel_switch: true, message: `Switching to Experimental installs ${release.version}.` };
+    Object.assign(result, { latest_version: release.tag, latest_sha: release.sourceRevision, branch: channel, release_based: true, no_git: true, install_kind: 'npm', manual_update: false });
+    if (switching)
+        return { ...result, current_sha: current, behind: await experimentalBuildsBehind(current, release.sourceRevision, registry, getJson), channel_switch: true, message: `Switching to ${name} installs ${release.version}.` };
+    if (ahead)
+        return { ...result, current_sha: current, behind: 0, manual_update: true, message: AHEAD_OF_NIGHTLY };
     if (disk?.sourceRevision !== release.sourceRevision)
-        return { ...result, current_sha: current, behind: await experimentalBuildsBehind(current, release.sourceRevision, registry, getJson), message: `Experimental update ${release.version} is available.` };
+        return { ...result, current_sha: current, behind: await experimentalBuildsBehind(current, release.sourceRevision, registry, getJson), message: `${name} update ${release.version} is available.` };
     const metadataRepair = !same(id.release(), disk);
     return { ...result, current_sha: release.sourceRevision, behind: 0, metadata_repair: metadataRepair, ...(metadataRepair ? { message: 'The npm package is current; finish the update to restart with that version.' } : {}) };
 }
@@ -579,13 +620,13 @@ export async function checkWebUpdate(webRoot, currentVersion, channel, git, getJ
     const result = { name: 'webui', channel, repo_url: REPOSITORY_URL, current_version: currentVersion, behind: null, no_git: root === null };
     if (root !== null)
         return { ...result, manual_update: true, message: CONTRIBUTOR_CHECKOUT_MESSAGE };
-    if (channel === 'experimental' && npmInstall && registry)
-        return checkNpmExperimental(result, npmInstall, id, registry, getJson);
-    const packaged = new RegExp(`^${channel === 'experimental' ? 'web-exp-v' : 'web-v'}${VERSION}$`).exec(currentVersion)?.slice(1, 4).join('.');
+    if (channel !== 'stable' && npmInstall && registry)
+        return checkNpmExperimental(result, npmInstall, id, registry, getJson, channel);
+    const packaged = familyVersion(channel, currentVersion)?.slice(1, 4).join('.');
     const installed = npmInstall?.version ?? packaged;
     let release;
     try {
-        release = await publishedWebRelease(channel, getJson, undefined, installed && new RegExp(`^${VERSION}$`).test(installed) ? installed : undefined);
+        release = await publishedWebRelease(webFamily(channel), getJson, undefined, installed && new RegExp(`^${VERSION}$`).test(installed) ? installed : undefined);
     }
     catch (error) {
         if (error instanceof ReleaseUnavailable)
@@ -611,7 +652,7 @@ export async function checkWebUpdate(webRoot, currentVersion, channel, git, getJ
             return { ...result, current_sha: release.sourceRevision, behind: 0, no_git: true, install_kind: 'npm', npm: release.npm, manual_update: false, metadata_repair: metadataRepair, ...(metadataRepair ? { message: 'The npm package is current; finish the update to restart with that version.' } : {}) };
         }
         const current = id.release().sourceRevision ?? null;
-        const version = new RegExp(`^${channel === 'experimental' ? 'web-exp-v' : 'web-v'}${VERSION}$`).exec(currentVersion);
+        const version = familyVersion(channel, currentVersion);
         let behind = version && current === release.sourceRevision ? 0 : null;
         if (behind === null && version) {
             const installed = version.slice(1).map(Number);
@@ -628,7 +669,7 @@ async function applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply
     if (!installed)
         return { ok: false, manual_update: true, message: 'Automatic npm updates require a direct global @maudecode/talaria-web installation.' };
     // Switching channels installs the selected channel's newest artifact regardless of version order (TAL-343).
-    const switching = npmInstallChannel(installed, id) !== channel;
+    const switching = npmInstallChannel(installed, id) !== webFamily(channel);
     if (version !== undefined && (channel !== 'stable' || switching))
         return { ok: false, target: 'webui', channel, message: ONLY_STABLE_VERSIONS };
     const onDisk = diskRelease(installed.packageRoot);
@@ -663,18 +704,21 @@ async function applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply
         }
     }
     else {
+        const name = CHANNEL_NAMES[channel];
         if (!packaged.registry)
-            return { ok: false, manual_update: true, message: 'Packaged Experimental updates are unavailable in this installation.' };
+            return { ok: false, manual_update: true, message: `Packaged ${name} updates are unavailable in this installation.` };
         let release;
         try {
-            release = await packaged.registry.release();
+            release = await packaged.registry.release(channel);
+            if (await aheadOfNightly(channel, switching, str(onDisk?.sourceRevision ?? id.release().sourceRevision) || null, release.sourceRevision, getJson))
+                return { ok: false, manual_update: true, target: 'webui', channel, message: AHEAD_OF_NIGHTLY };
         }
         catch (error) {
-            return { ok: false, message: error instanceof ReleaseUnavailable ? error.message : 'The Experimental artifact is unavailable.' };
+            return { ok: false, message: error instanceof ReleaseUnavailable ? error.message : `The ${name} artifact is unavailable.` };
         }
         const identity = { tag: release.tag, version: release.version, sourceRevision: release.sourceRevision, releaseSet: release.sourceRevision };
         // validateReleaseInfo (in diskRelease) already applies Stable's contract and Agent-pin checks to the packaged files.
-        target = { tag: release.tag, version: release.version, sourceRevision: release.sourceRevision, label: `Experimental ${release.version}`, matches: (r) => r !== null && same({ tag: r.tag, version: r.version, sourceRevision: r.sourceRevision, releaseSet: r.releaseSet }, identity), experimental: release };
+        target = { tag: release.tag, version: release.version, sourceRevision: release.sourceRevision, label: `${name} ${release.version}`, matches: (r) => r !== null && same({ tag: r.tag, version: r.version, sourceRevision: r.sourceRevision, releaseSet: r.releaseSet }, identity), experimental: release };
     }
     const priorRollback = readUpdateRollback(packaged.stateDir);
     if (packaged.skipFailedVersion && priorRollback?.failedVersion === target.version)
@@ -717,7 +761,7 @@ async function applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply
         const bins = dict(metadata.bin);
         if (metadata.name !== WEB_NPM_PACKAGE || metadata.version !== target.version || !target.matches(diskRelease(candidate))
             || !['talaria-web', 'talaria-web-mcp'].every((name) => str(bins[name]).replace(/^\.\//, '') === `dist/bin/${name}.js` && existsSync(join(candidate, `dist/bin/${name}.js`)))) {
-            return { ok: false, verification_failed: true, target: 'webui', channel, message: `The downloaded npm package does not match ${channel === 'stable' ? 'the completed release' : 'the Experimental artifact'}. The installed package was preserved.` };
+            return { ok: false, verification_failed: true, target: 'webui', channel, message: `The downloaded npm package does not match ${channel === 'stable' ? 'the completed release' : `the ${CHANNEL_NAMES[channel]} artifact`}. The installed package was preserved.` };
         }
         // npm can leave a dependency as an empty directory; swapping that in crash-loops the server (TAL-1010).
         const missing = Object.keys(dict(metadata.dependencies)).filter((name) => !existsSync(join(candidate, 'node_modules', name, 'package.json')));
@@ -1347,21 +1391,25 @@ function splitCategory(line) {
     return [['worth knowing', 'worth', 'note'].includes(label) ? 'worth' : 'notice', m[2] ?? ''];
 }
 const tagList = (notes) => notes.map((n) => n.tag).join(', ');
-function fallbackBullets(details) {
+const updateCount = (n) => `${String(n)} update${n === 1 ? '' : 's'}`;
+/** `resolved` is false when the update range could not be read, so empty notes and commits mean unknown, not none. */
+function fallbackBullets(details, resolved = true) {
     const out = details.map((item) => {
         const label = str(item.label || item.name) || 'Hermes';
+        if (!resolved)
+            return `${label} has ${updateCount(item.behind)} available. The summary could not be generated; try again later.`;
         const notes = item.notes;
         if (notes.length)
             return `${label} ${tagList(notes)} ${notes.length === 1 ? 'is' : 'are'} available.`;
         const commits = item.commits;
         if (commits.length)
-            return `${label} has ${String(item.behind)} update(s), including updates: ${commits.slice(0, 3).join('; ')}.`;
-        return `${label} has ${String(item.behind)} update(s) available.`;
+            return `${label} has ${updateCount(item.behind)}, including: ${commits.slice(0, 3).join('; ')}.`;
+        return `This build has no ${label} changes.`;
     });
     return out.length ? out : ['Updates are available.'];
 }
 function worthKnowingBullets(details) {
-    const targets = details.filter((d) => d.behind).map((d) => `${str(d.label || d.name) || 'Hermes'} (${String(d.behind)} update${d.behind === 1 ? '' : 's'})`);
+    const targets = details.filter((d) => d.behind).map((d) => `${str(d.label || d.name) || 'Hermes'} (${updateCount(d.behind)})`);
     return targets.length > 1 ? [`This summary combines updates from ${targets.join(' and ')}.`] : [];
 }
 const sectionsText = (sections) => sections.map((section) => [section.title, ...section.items.map((item) => `- ${item}`), ''].join('\n')).join('\n').trim();
@@ -1399,6 +1447,11 @@ function formatSections(text, details) {
         sections.push({ title: 'Worth knowing', items: worth });
     return [sections, sectionsText(sections)];
 }
+/** Deterministic copy when the model has nothing to summarize or cannot answer; never titled as model output. */
+function fallbackSections(details, resolved, deferred = false) {
+    const sections = [{ title: 'About this update', items: deferred ? ['The summary will be ready when the Agent update finishes.'] : uniqueBullets(fallbackBullets(details, resolved)) }];
+    return [sections, sectionsText(sections)];
+}
 const SUMMARY_SYSTEM = 'You write human-readable release summaries for Hermes users. Focus on what the user will notice in the product. Keep it simple, specific, and short. avoid technical jargon, implementation details, SHA names, branch names, and file paths unless necessary. Return only bullets. Do not include headings, markdown tables, intro paragraphs, or closing notes.';
 const SUMMARY_FORMAT = ['Prefix each bullet with `Notice:` for user-visible behavior changes or `Worth knowing:` for useful context.', 'Use Worth knowing only for helpful context that is not a duplicate of a Notice bullet.', 'Use everyday language and explain visible behavior changes, not code mechanics.', 'Return only prefixed bullets; the WebUI will add the fixed section headings separately.'];
 function summaryPrompt(details) {
@@ -1523,6 +1576,8 @@ export class UpdateService {
     applying = false;
     /** TAL-1525: a forced check owed once the current apply releases its lock. */
     refreshOwed = false;
+    /** TAL-1632: the latest owed refresh check, which runs after the apply that owed it returns. */
+    refreshing = Promise.resolve();
     /** TAL-1525: the Web package installed for the pending restart; this process still runs the old one. */
     installedWeb = null;
     autoTimer = null;
@@ -1535,6 +1590,10 @@ export class UpdateService {
     summaryQueues = new Map();
     summarizing = new Map();
     summaryFailures = new Set();
+    /** TAL-1591: targets whose model call the sidecar refused while the Agent runtime was mid-update; non-empty means the runtime is known stale. */
+    summaryDeferred = new Set();
+    /** Counts runtime-current signals, so a refusal that was in flight across one is retried rather than deferred. */
+    runtimeCurrentEpoch = 0;
     publishedTags = new Map();
     git;
     now;
@@ -1593,16 +1652,25 @@ export class UpdateService {
             this.summaryQueues.delete(target); }).catch(() => undefined);
         return next;
     }
-    preGenerateSummaries(status) {
-        for (const target of ['webui', 'agent']) {
+    preGenerateSummaries(status, targets = ['webui', 'agent']) {
+        for (const target of targets) {
             const info = dict(status[target]);
             if (updateTargetView(target, info, false).summary_available !== true)
                 continue;
             const automatic = this.deps.llm && this.deps.checkEnabled?.() !== false && this.deps.summarizeAutomatically?.() !== false;
-            const work = automatic ? this.summarizeTarget(target, info) : this.queueSummary(target, () => this.refreshSummaryItems(target, info));
+            const work = automatic ? this.summarizeTarget(target, info, false, true) : this.queueSummary(target, () => this.refreshSummaryItems(target, info));
             void work.catch(() => { this.logSummaryFailure(this.summaryKey(target, info), target); });
         }
     }
+    /** TAL-1591: the Agent runtime is current again, so deferred summaries are generated once. */
+    resumeDeferredSummaries() {
+        this.runtimeCurrentEpoch += 1;
+        if (!this.summaryDeferred.size)
+            return;
+        const targets = [...this.summaryDeferred];
+        this.summaryDeferred.clear();
+        this.preGenerateSummaries(this.cache, targets);
+    }
     agentChannel() { return this.deps.agentChannel?.() ?? DEFAULT_CHANNEL; }
     /** TAL-930: the Agent's published Stable tag, one anonymous GitHub read per remote per cache TTL; an unreadable answer keeps the last verified tag. */
     publishedTag = async (repoUrl) => {
@@ -1762,7 +1830,15 @@ export class UpdateService {
         if (!this.refreshOwed)
             return;
         this.refreshOwed = false;
-        void this.check(true).catch((error) => { this.deps.log(`[updates] refresh after update failed: ${error.message}`); });
+        this.refreshing = this.check(true).catch((error) => { this.deps.log(`[updates] refresh after update failed: ${error.message}`); });
+    }
+    /** Resolves once every owed refresh check has finished, so a caller can safely remove the checkouts it reads. */
+    async settled() {
+        let refreshing;
+        do {
+            refreshing = this.refreshing;
+            await refreshing;
+        } while (refreshing !== this.refreshing);
     }
     startAutoApply(intervalMs = AUTO_UPDATE_INTERVAL_MS) {
         if (this.autoStarted || this.autoRestartScheduled)
@@ -1772,6 +1848,8 @@ export class UpdateService {
         this.recoveryUnsubscribe = this.deps.onAgentReconnect?.((runtime) => {
             if (!this.autoStarted || lifecycle !== this.lifecycle)
                 return;
+            if (runtime.compatible && !runtime.stale)
+                this.resumeDeferredSummaries();
             if (runtime.compatible && !runtime.stale && this.recovery.phase === 'blocked') {
                 this.recoveryAttempt = 0;
                 this.recovery = { ...this.recovery, phase: 'waiting', attempt: 0, retry_at: null };
@@ -1911,6 +1989,7 @@ export class UpdateService {
                 throw new Error(result.detail || 'Agent recovery remains unverified.');
             await this.invalidate('agent');
             this.recovery = { phase: 'complete', attempt: this.recoveryAttempt, detail: 'Agent service and runtime recovery is verified.', retry_at: null, ...(result.operation ? { operation: result.operation } : {}), ...(result.revision ? { verified_revision: result.revision } : {}), ...(result.runtime_revision ? { runtime_revision: result.runtime_revision } : {}), ...(result.verified_version ? { verified_version: result.verified_version } : {}) };
+            this.resumeDeferredSummaries();
         }
         catch (error) {
             if (!current())
@@ -2295,7 +2374,7 @@ export class UpdateService {
         const latest = str(info.latest_sha);
         if (!SHA.test(current) || !SHA.test(latest))
             throw new Error('Update range is unavailable');
-        const releaseNotes = info.release_based === true && (target === 'webui' ? info.channel !== 'experimental' && Array.isArray(info.release_notes) && info.release_notes.length > 0 : Boolean(this.deps.getPublicJson && githubRepo(str(info.repo_url))));
+        const releaseNotes = info.release_based === true && (target === 'webui' ? info.channel === 'stable' && Array.isArray(info.release_notes) && info.release_notes.length > 0 : Boolean(this.deps.getPublicJson && githubRepo(str(info.repo_url))));
         const rangeKey = this.summaryKey(target, info);
         const identity = canon({ channel: info.channel, current_version: info.current_version, release_based: releaseNotes, repo: info.repo_url, path: target === 'agent' ? this.deps.agentDir() : this.deps.webRoot });
         const stored = this.pendingSummaries.get(target);
@@ -2334,7 +2413,7 @@ export class UpdateService {
     async summarize(target, checksOff = false) {
         return this.summarizeTarget(target, dict(this.cachedStatus()[target]), checksOff);
     }
-    async summarizeTarget(target, info, checksOff = false) {
+    async summarizeTarget(target, info, checksOff = false, automatic = false) {
         const view = updateTargetView(target, info, checksOff);
         const range = { current_version: typeof info.current_version === 'string' ? info.current_version : null, target_version: view.target_version ?? null };
         if (view.summary_available !== true)
@@ -2343,7 +2422,7 @@ export class UpdateService {
         const pending = this.summarizing.get(key);
         if (pending)
             return pending;
-        const generating = this.queueSummary(target, () => this.generateSummary(target, info, range, key)).finally(() => { this.summarizing.delete(key); });
+        const generating = this.queueSummary(target, () => this.generateSummary(target, info, range, key, automatic)).finally(() => { this.summarizing.delete(key); });
         this.summarizing.set(key, generating);
         return generating;
     }
@@ -2384,7 +2463,7 @@ export class UpdateService {
         }
         return sections;
     }
-    async generateSummary(target, info, range, key) {
+    async generateSummary(target, info, range, key, automatic) {
         let entry;
         let complete = false;
         try {
@@ -2398,21 +2477,39 @@ export class UpdateService {
         const last = entry?.items.at(-1)?.id ?? null;
         const cached = Boolean(complete && entry?.summary_sections && entry.summarized_through === last);
         let sections = cached ? entry.summary_sections : null;
+        // Pre-generation skips a known-stale runtime; an on-demand request asks again, and its answer proves the runtime current.
+        let deferred = false;
         if (!sections && entry && this.deps.llm && entry.items.length) {
             const at = entry.summarized_through === null ? 0 : entry.items.findIndex((item) => item.id === entry.summarized_through) + 1;
-            try {
-                sections = await this.foldSummary(entry.summary_sections, entry.items.slice(at), detail, source);
-                if (complete && sections) {
-                    entry.summary_sections = sections;
-                    entry.summarized_through = last;
-                    this.persistSummaries();
+            if (automatic && this.summaryDeferred.size)
+                deferred = true;
+            else
+                for (;;) {
+                    const epoch = this.runtimeCurrentEpoch;
+                    try {
+                        sections = await this.foldSummary(entry.summary_sections, entry.items.slice(at), detail, source);
+                        if (complete && sections) {
+                            entry.summary_sections = sections;
+                            entry.summarized_through = last;
+                            this.persistSummaries();
+                        }
+                        this.summaryDeferred.delete(target);
+                        this.resumeDeferredSummaries();
+                    }
+                    catch (error) {
+                        if (!(error instanceof SidecarError && error.condition === 'agent_runtime_stale'))
+                            this.logSummaryFailure(key, target);
+                        else if (epoch !== this.runtimeCurrentEpoch)
+                            continue;
+                        else
+                            deferred = true;
+                    }
+                    break;
                 }
-            }
-            catch {
-                this.logSummaryFailure(key, target);
-            }
+            if (deferred)
+                this.summaryDeferred.add(target);
         }
-        const fallback = formatSections('', [detail]);
+        const fallback = fallbackSections([detail], Boolean(entry), deferred);
         const summary = sections ? sectionsText(sections) : fallback[1];
         return { ok: true, target, ...range, summary, summary_sections: sections ?? fallback[0], generated_by: sections ? 'llm' : 'fallback', source, cached };
     }