@maudecode/talaria-web 1.20.0 → 1.22.0

package/dist/tools/updates.js

@@ -12,7 +12,7 @@
  */
 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 { execFile } from 'node:child_process';
@@ -41,6 +41,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) {
@@ -405,9 +412,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 +559,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 +614,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 +646,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 +663,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);
@@ -651,7 +686,7 @@ async function applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply
         }
         if (!chosen.npm)
             return { ok: false, manual_update: true, message: 'The completed Stable release does not include an npm package identity.' };
-        target = { version: chosen.version, sourceRevision: chosen.sourceRevision, label: `npm release ${chosen.version}`, matches: (r) => same(r, chosen.runtime), npm: chosen.npm };
+        target = { tag: chosen.tag, version: chosen.version, sourceRevision: chosen.sourceRevision, label: `npm release ${chosen.version}`, matches: (r) => same(r, chosen.runtime), npm: chosen.npm };
         if (!switching) {
             if (!canApply())
                 return { ok: false, message: 'Web update deferred because its settings or lifecycle changed.' };
@@ -663,18 +698,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 = { 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)
@@ -683,7 +721,7 @@ async function applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply
     if (current) {
         if (same(id.release(), onDisk))
             return { ok: true, up_to_date: true, target: 'webui', channel, message: channel === 'stable' ? 'Talaria Web already contains the selected npm release.' : `Talaria Web already contains ${target.label}.` };
-        return { ok: true, target: 'webui', channel, sourceRevision: target.sourceRevision, ...(target.npm ? { npm: target.npm } : {}), message: `Restarting Talaria Web with ${target.label}.` };
+        return { ok: true, target: 'webui', channel, tag: target.tag, sourceRevision: target.sourceRevision, ...(target.npm ? { npm: target.npm } : {}), message: `Restarting Talaria Web with ${target.label}.` };
     }
     if (!canApply())
         return { ok: false, message: 'Web update deferred because its settings or lifecycle changed.' };
@@ -717,7 +755,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')));
@@ -771,7 +809,7 @@ async function applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply
             catch { /* a leftover staging directory must not prevent restart after a verified switch */ }
         }
     }
-    return { ok: true, target: 'webui', channel, sourceRevision: target.sourceRevision, ...(target.npm ? { npm: target.npm } : {}),
+    return { ok: true, target: 'webui', channel, tag: target.tag, sourceRevision: target.sourceRevision, ...(target.npm ? { npm: target.npm } : {}),
         ...(switching ? { channel_switch: true, backup_dir: stores } : {}), message: `Updated Talaria Web to ${target.label}.${stores ? ` Settings were backed up to ${stores}.` : ''}` };
 }
 /** Python `apply_web_update`: installs npm releases; a source checkout is never mutated (TAL-379). */
@@ -796,6 +834,47 @@ async function currentReleaseTag(path, git) {
     const out = await git(['describe', '--tags', '--exact-match', '--match', AGENT_TAG_GLOB, 'HEAD'], path);
     return out.ok && out.out ? out.out : null;
 }
+/** TAL-1525: the checkout's installed identity, retained local-edit recovery, and distance to an already-known target, from local Git only. */
+async function installedAgentIdentity(path, latest, git) {
+    if (!path)
+        return null;
+    const head = await git(['rev-parse', 'HEAD'], path);
+    if (!head.ok || !SHA.test(head.out))
+        return null;
+    let pending;
+    try {
+        pending = await pendingAutostashes(path, git);
+    }
+    catch {
+        return null;
+    } // Uninspectable recovery keeps the cached answer.
+    const installed = { current_sha: head.out, current_version: await currentReleaseTag(path, git) ?? head.out.slice(0, 12), ...(pending.length ? RETAINED_LOCAL_EDITS : {}) };
+    if (typeof latest !== 'string' || !SHA.test(latest) || latest === head.out)
+        return installed;
+    const count = await git(['rev-list', '--count', `${head.out}..${latest}`], path);
+    return { ...installed, behind: count.ok && /^\d+$/.test(count.out) ? Number.parseInt(count.out, 10) : null };
+}
+/** TAL-1525: a cached target re-anchored on its installed identity; only cached releases newer than it stay offered. */
+function reanchored(info, installed) {
+    const next = { ...info };
+    // The installed identity re-asserts whatever recovery it still owes.
+    delete next.message;
+    delete next.metadata_repair;
+    delete next.channel_switch;
+    Object.assign(next, installed);
+    const versions = Array.isArray(info.versions) ? info.versions.map(dict) : [];
+    const at = versions.findIndex((v) => v.version === installed.current_version || (typeof v.sha === 'string' && v.sha === installed.current_sha));
+    if (at >= 0)
+        next.versions = versions.slice(0, at);
+    if (installed.current_sha === info.latest_sha) {
+        next.behind = 0;
+        next.versions = [];
+        delete next.manual_update;
+    }
+    else if (installed.behind === undefined)
+        next.behind = at >= 0 ? at : null;
+    return next;
+}
 async function verifiedAgentIdentity(path, expectedRevision, git) {
     const head = await git(['rev-parse', 'HEAD'], path);
     if (!head.ok || head.out !== expectedRevision || !SHA.test(head.out))
@@ -907,6 +986,7 @@ async function isDirty(path, git) {
     return !out.ok && (out.out === 'git exited with status 1' || !out.out || out.out.startsWith('git exited with status '));
 }
 /** Fetch and compare the independently selected Agent channel. */
+const RETAINED_LOCAL_EDITS = { metadata_repair: true, message: 'Local Agent changes need recovery. Their saved recovery records are retained.' };
 export async function checkAgentUpdate(path, git, channel = DEFAULT_CHANNEL, published) {
     if (!path || !existsSync(join(path, '.git')))
         return { name: 'agent', behind: null, no_git: true };
@@ -918,7 +998,7 @@ export async function checkAgentUpdate(path, git, channel = DEFAULT_CHANNEL, pub
     try {
         const pending = await pendingAutostashes(path, git);
         return { ...await agentTarget(path, git, channel, undefined, published), dirty: await isDirty(path, git),
-            ...(pending.length ? { metadata_repair: true, message: 'Local Agent changes need recovery. Their saved recovery records are retained.' } : {}) };
+            ...(pending.length ? RETAINED_LOCAL_EDITS : {}) };
     }
     catch (error) {
         return { name: 'agent', channel, behind: null, error: error.message };
@@ -1028,7 +1108,7 @@ async function withAgentMutation(path, info, git, policy, mutate, mode = 'source
     if (preflight)
         return preflight;
     try {
-        const result = await policy.withMutation(path, str(info.latest_sha), guarded);
+        const result = await policy.withMutation(path, str(info.latest_sha), guarded, str(info.current_sha));
         return result.refresh_confirmation ? { ...result, target: 'agent', confirmation_required: true, candidate_revision: info.latest_sha, agent_channel: info.channel } : result;
     }
     catch (error) {
@@ -1479,6 +1559,10 @@ export class UpdateService {
     checkingKey = null;
     lastGood = new Map();
     applying = false;
+    /** TAL-1525: a forced check owed once the current apply releases its lock. */
+    refreshOwed = false;
+    /** TAL-1525: the Web package installed for the pending restart; this process still runs the old one. */
+    installedWeb = null;
     autoTimer = null;
     autoStarted = false;
     lifecycle = 0;
@@ -1578,11 +1662,12 @@ export class UpdateService {
             supportedRevision: str(supported.sourceRevision), supportedVersion: str(supported.version), ...(options.confirmedRevision ? { confirmedRevision: options.confirmedRevision } : {}),
             ...(this.deps.agentHomes ? { retainedStateHomes: this.deps.agentHomes } : {}),
             repairPending: Boolean(marker && existsSync(marker)),
-            ...(this.deps.agentMutation ? { withMutation: async (path, revision, mutate) => {
+            ...(this.deps.agentMutation ? { withMutation: async (path, revision, mutate, baseline) => {
+                    await options.onTransaction?.(baseline, revision);
                     const result = await this.deps.agentMutation(path, revision, async (git, sync) => {
                         const applied = await mutate(git);
                         return applied.ok ? this.finishAgent(applied, path, sync, false) : applied;
-                    }, { refreshToken: options.refreshToken, onProgress: options.onProgress, mutationIntent: options.mutationIntent ? JSON.stringify([options.mutationIntent, force, options.agentChannel ?? this.agentChannel(), options.version ?? '', options.confirmedRevision ?? '']) : undefined });
+                    }, { operationId: options.operationId, baseline, refreshToken: options.refreshToken, onProgress: options.onProgress, mutationIntent: options.mutationIntent ? JSON.stringify([options.mutationIntent, force, options.agentChannel ?? this.agentChannel(), options.version ?? '', options.confirmedRevision ?? '']) : undefined });
                     if (result.ok && !retainRuntimeIntent) {
                         const intent = agentSyncMarker(path, this.deps.stateDir);
                         try {
@@ -1653,7 +1738,13 @@ export class UpdateService {
                 if (this.deps.refreshWebuiVersion)
                     webui.current_version = this.deps.refreshWebuiVersion();
                 const agentDir = this.deps.agentDir();
-                const agent = includeAgent ? this.keepLastGood('agent', agentChannel, await checkAgentUpdate(agentDir, this.git, agentChannel, this.publishedTag)) : ignoredAgent();
+                let agent = includeAgent ? this.keepLastGood('agent', agentChannel, await checkAgentUpdate(agentDir, this.git, agentChannel, this.publishedTag)) : ignoredAgent();
+                // A fetch failure keeps the last good remote answer, never its outdated installed identity.
+                if (agent.stale_check && agent.latest_sha) {
+                    const installed = await installedAgentIdentity(agentDir, agent.latest_sha, this.git);
+                    if (installed)
+                        agent = reanchored(agent, installed);
+                }
                 const marker = agentSyncMarker(agentDir, this.deps.stateDir);
                 if (includeAgent && marker && existsSync(marker)) {
                     Object.assign(agent, { metadata_repair: true, message: this.recovery.phase === 'blocked' ? this.recovery.detail || 'Agent update recovery needs attention.' : 'Agent update recovery is incomplete. Recovery will retry automatically when it is safe.' });
@@ -1663,7 +1754,7 @@ export class UpdateService {
                     Object.assign(agent, agentWarning(agent, policy));
                 if (Array.isArray(agent.versions))
                     agent.versions = agent.versions.map((v) => ({ ...dict(v), ...supportOf(dict(v).sha, policy) }));
-                Object.assign(this.cache, { webui, agent, checked_at: this.now(), include_agent: includeAgent, channel, agent_channel: agentChannel });
+                Object.assign(this.cache, { webui: this.installedWeb ? reanchored(webui, this.installedWeb) : webui, agent, checked_at: this.now(), include_agent: includeAgent, channel, agent_channel: agentChannel });
                 this.preGenerateSummaries(this.cache);
                 return this.statusSnapshot();
             }
@@ -1686,6 +1777,31 @@ export class UpdateService {
         const prior = this.lastGood.get(key);
         return prior && this.now() - prior.at < CACHE_TTL_S ? { ...prior.result, stale_check: true } : result;
     }
+    /**
+     * TAL-1525: an apply or recovery settled, so the cached target is re-anchored on its installed identity
+     * at once (local reads only) and one forced check follows in the background once no apply holds the lock.
+     */
+    async invalidate(target, applied) {
+        this.cache.checked_at = 0;
+        if (target === 'webui' && applied)
+            this.installedWeb = { current_sha: applied.sourceRevision ?? null, current_version: applied.tag };
+        const installed = target === 'webui' ? this.installedWeb : await installedAgentIdentity(this.deps.agentDir(), dict(this.cache.agent).latest_sha, this.git);
+        const cached = this.cache[target];
+        if (installed && cached && cached.ignored !== true)
+            this.cache[target] = reanchored(cached, installed);
+        if (this.deps.checkEnabled?.() === false)
+            return;
+        this.refreshOwed = true;
+        if (!this.applying)
+            this.refreshOwedCheck();
+    }
+    /** Starts the owed check; a check already in flight for the same key answers it. */
+    refreshOwedCheck() {
+        if (!this.refreshOwed)
+            return;
+        this.refreshOwed = false;
+        void this.check(true).catch((error) => { this.deps.log(`[updates] refresh after update failed: ${error.message}`); });
+    }
     startAutoApply(intervalMs = AUTO_UPDATE_INTERVAL_MS) {
         if (this.autoStarted || this.autoRestartScheduled)
             return;
@@ -1729,7 +1845,7 @@ export class UpdateService {
     }
     /** One sequence owns its timer and RPC; unchanged permanent debt cannot restart it. */
     armRecovery() {
-        if (!this.deps.recoverAgent || !this.deps.agentDir() || this.recoveryAbort || !this.autoStarted)
+        if (!this.deps.recoverAgent || (!this.deps.agentDir() && !this.deps.hasPendingRecovery?.()) || this.recoveryAbort || !this.autoStarted)
             return;
         if (this.recoveryTimer) {
             if (!this.recoveryProbe)
@@ -1745,6 +1861,9 @@ export class UpdateService {
         this.recoveryTimer.unref();
     }
     async publishRecovery() {
+        const operation = this.recovery.operation;
+        if (operation?.attempt_error)
+            this.recovery = { ...this.recovery, operation: { ...operation, attempt_error: sanitizeGitDiagnostic(operation.attempt_error, 2000) } };
         try {
             await this.deps.recoveryChanged?.(this.recovery);
         }
@@ -1760,6 +1879,9 @@ export class UpdateService {
         let retryDelay = 1000;
         let probeOnly = false;
         let ran = false;
+        let publish = true;
+        let operationId = this.deps.pendingRecoveryOperation?.();
+        let operation;
         const waitWithoutSpending = (detail, delay = 1000) => {
             retry = true;
             retryDelay = delay;
@@ -1768,11 +1890,14 @@ export class UpdateService {
         try {
             if (this.applying || this.deps.gatewayRestarting?.()) {
                 retry = true;
+                publish = false;
                 return;
             }
             const probe = await this.deps.recoverAgent(true, abort.signal);
             if (!current())
                 return;
+            operation = !operationId || probe.operation?.operation_id === operationId ? probe.operation : undefined;
+            operationId ??= operation?.operation_id;
             if (probe.waiting_for_idle) {
                 waitWithoutSpending(probe.detail);
                 return;
@@ -1792,7 +1917,7 @@ export class UpdateService {
             ran = true;
             // A re-check of a still-draining gateway keeps its waiting notice rather than flapping to running.
             if (!this.recoveryDraining) {
-                this.recovery = { phase: 'running', attempt: this.recoveryAttempt, detail: '', retry_at: null };
+                this.recovery = { phase: 'running', attempt: this.recoveryAttempt, detail: '', retry_at: null, ...(operationId ? { operation_id: operationId } : {}), ...(operation ? { operation } : {}) };
                 await this.publishRecovery();
                 if (!current())
                     return;
@@ -1822,8 +1947,8 @@ export class UpdateService {
             }
             if (!result.ok || result.owed)
                 throw new Error(result.detail || 'Agent recovery remains unverified.');
-            this.cache.checked_at = 0;
-            this.recovery = { phase: 'complete', attempt: this.recoveryAttempt, detail: 'Agent service and runtime recovery is verified. The original update outcome is unchanged.', retry_at: null };
+            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 } : {}) };
         }
         catch (error) {
             if (!current())
@@ -1841,7 +1966,8 @@ export class UpdateService {
                 this.recovery.retry_at = new Date(this.now() * 1000 + retryDelay).toISOString();
         }
         finally {
-            if (current()) {
+            if (current() && publish) {
+                this.recovery = { ...this.recovery, ...(operationId ? { operation_id: operationId } : {}), ...(operation && !this.recovery.operation ? { operation } : {}) };
                 await this.publishRecovery();
             }
             if (this.recoveryAbort === abort)
@@ -1938,6 +2064,7 @@ export class UpdateService {
         }
         finally {
             this.applying = false;
+            this.refreshOwedCheck();
             this.armRecovery();
         }
     }
@@ -1962,7 +2089,7 @@ export class UpdateService {
             const result = await applyWebUpdate(this.deps.webRoot, channel, this.git, this.deps.getJson, this.deps.identity, this.deps.npm ?? runPackageNpm, canApply, { registry: this.deps.experimental, stateDir: this.deps.stateDir, skipFailedVersion: options.skipFailedVersion }, options.version);
             // Settings can cancel before mutation, but a committed replacement must finish restarting unless shutting down.
             if (result.ok && !result.up_to_date && lifecycle === this.lifecycle) {
-                this.cache.checked_at = 0;
+                await this.invalidate('webui', result);
                 this.autoRestartScheduled = true;
                 this.stopAutoApply();
                 this.deps.scheduleRestart();
@@ -2002,24 +2129,34 @@ export class UpdateService {
                 return verified ? { ok: true, target: 'agent', up_to_date: false, message: 'Agent update recovery completed.', ...verified }
                     : { ok: false, message: 'Agent recovery could not verify the current source.' };
             }, 'repair');
+            // Repairing an older transaction cannot prove this request installed its selected release.
+            if (options.operationId)
+                result = { ...result, recovery_only: true };
         }
         else {
             result = force
                 ? await forceAgentUpdate(path, this.git, this.deps.log, options.agentChannel ?? this.agentChannel(), this.agentPolicy(options, force), options.version, this.publishedTag)
                 : await applyAgentUpdate(path, this.git, options.agentChannel ?? this.agentChannel(), this.agentPolicy(options, force), options.version, this.publishedTag);
         }
+        if (result.ok !== true && result.recovery_required !== false && !result.confirmation_required && await options.onFailure?.(result.message || result.error, typeof result.verified_revision === 'string' ? { revision: result.verified_revision, version: typeof result.verified_version === 'string' ? result.verified_version : null } : undefined))
+            result.recovery_pending = true;
         if (this.deps.agentMutation) {
             if (result.ok && result.restart_scheduled) {
                 this.autoRestartScheduled = true;
                 this.stopAutoApply();
                 this.deps.scheduleRestart();
             }
-            return result;
         }
-        return result.ok ? this.finishAgent(result, path) : result;
+        else if (result.ok)
+            result = await this.finishAgent(result, path);
+        // A failure can still leave Git advanced (a failed dependency sync), so the next check refetches.
+        if (result.ok)
+            await this.invalidate('agent');
+        else
+            this.cache.checked_at = 0;
+        return result;
     }
     async finishAgent(result, path, sync = this.deps.agentSync, restart = true) {
-        this.cache.checked_at = 0;
         const marker = agentSyncMarker(path, this.deps.stateDir);
         if (result.up_to_date === true && (!marker || !existsSync(marker)))
             return result;
@@ -2071,7 +2208,6 @@ export class UpdateService {
             const inv = inventoryLocks(path);
             const manual = `rm -f ${str(inv.well_known_lock_path)}`;
             if (!inv.well_known_lock_present) {
-                this.cache.checked_at = 0;
                 const retry = await this.applyInner(target, this.deps.channel(), () => true, options);
                 return { ...retry, lock_recovery: { action: 'no-lock-found', manual_command: manual, other_locks: inv.other_locks } };
             }
@@ -2197,7 +2333,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);