@maudecode/talaria-web 1.19.0 → 1.21.0

package/dist/tools/updates.js

@@ -651,7 +651,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.' };
@@ -674,7 +674,7 @@ async function applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply
         }
         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: `Experimental ${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 +683,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.' };
@@ -771,7 +771,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 +796,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))
@@ -875,6 +916,8 @@ async function agentTarget(path, git, channel, version, published) {
         ...(manual ? { manual_update: true, message: 'Agent checkout is ahead of or divergent from this channel; refusing to rewind it.' } : {}),
     };
 }
+/** TAL-1429: the Agent update waits for the gateways' own native drain instead of interrupting their work. */
+export const gatewayDrainDetail = (services, seconds) => `Waiting for ${services.length ? services.join(', ') : 'the gateway'} to finish in-flight work before installing (up to ${String(Math.max(1, Math.ceil(seconds / 60)))} min).`;
 /** Only an exact verified revision is supported: a moved tag, a non-tag HEAD, Experimental `main` and a missing record are all unchecked. */
 const agentSupport = (sha, policy) => typeof sha === 'string' && SHA.test(sha) && policy.supportedRevisions.includes(sha) ? 'supported' : 'unchecked';
 const SUPPORT_LABELS = { supported: 'Supported', unchecked: 'Not tested with this Talaria' };
@@ -905,6 +948,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 };
@@ -916,7 +960,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 };
@@ -1026,7 +1070,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) {
@@ -1458,6 +1502,9 @@ async function syncAgentDependencies(path, revision, sync, stateDir, git, clearI
     return result;
 }
 const RECOVERY_DELAYS = [0, 1000, 4000, 15000, 60000, 120000];
+/** TAL-1430: re-check spacing for a native drain, and the lightweight lifecycle probe of exhausted debt. */
+const RECOVERY_DRAIN_RETRY_MS = 15000;
+const RECOVERY_PROBE_MS = 60000;
 export class UpdateService {
     deps;
     recoveryTimer = null;
@@ -1465,12 +1512,19 @@ export class UpdateService {
     recoveryUnsubscribe = null;
     recoveryAttempt = 0;
     recoveryFingerprint = '';
+    recoveryDraining = false;
+    /** The pending timer is an exhausted obligation's lightweight probe, which any immediate trigger may replace. */
+    recoveryProbe = false;
     recovery = { phase: 'idle', attempt: 0, detail: '', retry_at: null };
     cache = { webui: null, agent: null, checked_at: 0, include_agent: true, channel: DEFAULT_CHANNEL, agent_channel: DEFAULT_CHANNEL };
     checking = null;
     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;
@@ -1570,11 +1624,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, 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 {
@@ -1645,7 +1700,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.' });
@@ -1655,7 +1716,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();
             }
@@ -1678,6 +1739,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;
@@ -1713,14 +1799,22 @@ export class UpdateService {
         if (this.recoveryTimer)
             clearTimeout(this.recoveryTimer);
         this.recoveryTimer = null;
+        this.recoveryProbe = false;
+        this.recoveryDraining = false;
         this.recoveryAbort?.abort();
         this.recoveryUnsubscribe?.();
         this.recoveryUnsubscribe = null;
     }
     /** One sequence owns its timer and RPC; unchanged permanent debt cannot restart it. */
     armRecovery() {
-        if (!this.deps.recoverAgent || !this.deps.agentDir() || this.recoveryTimer || 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)
+                return;
+            clearTimeout(this.recoveryTimer);
+        }
+        this.recoveryProbe = false;
         const lifecycle = this.lifecycle;
         this.recoveryTimer = setTimeout(() => {
             this.recoveryTimer = null;
@@ -1729,6 +1823,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);
         }
@@ -1742,41 +1839,59 @@ export class UpdateService {
         const current = () => !abort.signal.aborted && lifecycle === this.lifecycle && this.autoStarted;
         let retry = false;
         let retryDelay = 1000;
-        const waitForIdle = (detail) => {
+        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;
             this.recovery = { phase: 'waiting', attempt: this.recoveryAttempt, detail, retry_at: new Date(this.now() * 1000 + retryDelay).toISOString() };
         };
         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) {
-                waitForIdle(probe.detail);
+                waitWithoutSpending(probe.detail);
                 return;
             }
             if (!probe.owed && ['idle', 'complete'].includes(this.recovery.phase) && !this.deps.hasPendingRecovery?.())
                 return;
             if (probe.fingerprint !== this.recoveryFingerprint && ['idle', 'complete', 'blocked'].includes(this.recovery.phase))
                 this.recoveryAttempt = 0;
-            if (probe.owed && this.recovery.phase === 'blocked' && this.recoveryAttempt >= RECOVERY_DELAYS.length && probe.fingerprint === this.recoveryFingerprint)
+            if (probe.owed && this.recovery.phase === 'blocked' && this.recoveryAttempt >= RECOVERY_DELAYS.length && probe.fingerprint === this.recoveryFingerprint) {
+                // Exhausted debt keeps a cheap probe; a changed receipt or attested gateway lifecycle rearms the sequence.
+                retry = probeOnly = true;
+                retryDelay = RECOVERY_PROBE_MS;
                 return;
+            }
             this.recoveryFingerprint = probe.fingerprint;
             this.recoveryAttempt += 1;
-            this.recovery = { phase: 'running', attempt: this.recoveryAttempt, detail: '', retry_at: null };
-            await this.publishRecovery();
-            if (!current())
-                return;
+            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, ...(operationId ? { operation_id: operationId } : {}), ...(operation ? { operation } : {}) };
+                await this.publishRecovery();
+                if (!current())
+                    return;
+            }
             const result = await this.deps.recoverAgent(false, abort.signal);
             if (!current())
                 return;
             this.recoveryFingerprint = result.fingerprint;
-            if (result.waiting_for_idle) {
+            this.recoveryDraining = result.draining === true;
+            if (result.waiting_for_idle || result.draining) {
                 this.recoveryAttempt -= 1;
-                waitForIdle(result.detail);
+                waitWithoutSpending(result.detail, result.draining ? RECOVERY_DRAIN_RETRY_MS : 1000);
                 return;
             }
             if (result.local_restore && result.revision) {
@@ -1794,21 +1909,27 @@ 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())
                 return;
-            // A failed discovery also consumes the bounded sequence.
-            if (this.recovery.phase !== 'running')
+            this.recoveryDraining = false;
+            // A failed discovery also consumes the bounded sequence; an exhausted probe's failure does not extend it.
+            if (!ran && this.recoveryAttempt < RECOVERY_DELAYS.length)
                 this.recoveryAttempt += 1;
-            retry = this.recoveryAttempt < RECOVERY_DELAYS.length;
-            retryDelay = RECOVERY_DELAYS[this.recoveryAttempt] ?? 1000;
-            this.recovery = { phase: retry ? 'waiting' : 'blocked', attempt: this.recoveryAttempt, detail: sanitizeGitDiagnostic(error.message), retry_at: retry ? new Date(this.now() * 1000 + retryDelay).toISOString() : null };
+            const exhausted = this.recoveryAttempt >= RECOVERY_DELAYS.length;
+            this.recovery = { phase: exhausted ? 'blocked' : 'waiting', attempt: this.recoveryAttempt, detail: sanitizeGitDiagnostic(error.message), retry_at: null };
+            retry = true;
+            probeOnly = exhausted;
+            retryDelay = exhausted ? RECOVERY_PROBE_MS : RECOVERY_DELAYS[this.recoveryAttempt] ?? 1000;
+            if (!exhausted)
+                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)
@@ -1816,7 +1937,8 @@ export class UpdateService {
             if (this.autoStarted && lifecycle !== this.lifecycle)
                 this.armRecovery();
             if (current() && retry) {
-                this.recoveryTimer = setTimeout(() => { this.recoveryTimer = null; void this.recoverOnce(lifecycle); }, retryDelay);
+                this.recoveryProbe = probeOnly;
+                this.recoveryTimer = setTimeout(() => { this.recoveryTimer = null; this.recoveryProbe = false; void this.recoverOnce(lifecycle); }, retryDelay);
                 this.recoveryTimer.unref();
             }
         }
@@ -1904,6 +2026,7 @@ export class UpdateService {
         }
         finally {
             this.applying = false;
+            this.refreshOwedCheck();
             this.armRecovery();
         }
     }
@@ -1928,7 +2051,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();
@@ -1968,24 +2091,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;
@@ -2037,7 +2170,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 } };
             }