@maudecode/talaria-web 1.11.0 → 1.12.1

package/dist/tools/updates.js

@@ -4,7 +4,8 @@
  * Web: a recognized clean Talaria checkout fast-forwards to the newest completed
  * release set (stable) or `origin/main` (experimental) and stamps `web/_release.json`
  * from immutable git blobs. Direct global npm installs can replace themselves
- * with an exact completed Stable package; other packaged installs stay manual.
+ * with an exact completed Stable package or the verified GHCR Experimental artifact, switching
+ * channels in either direction; other packaged installs stay manual.
  * Agent: the external checkout follows its own `v*` tags with a
  * stash/pull or force reset, then the gateway restarts through the sidecar.
  * Nothing here deletes git locks; `clearLock` only inventories them.
@@ -12,7 +13,7 @@
 import { readCapped } from '../http/capped.js';
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, lstatSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
 import { dict } from '../config/agent-config.js';
 import { validateReleaseInfo } from '../release.js';
@@ -116,6 +117,15 @@ function fetchFailureMessage(out, network) {
     const lower = detail.toLowerCase();
     return NETWORK_FAILURES.some((s) => lower.includes(s)) ? network : `fetch failed: ${detail}`;
 }
+/** One delayed retry absorbs a transient network blip; a lock conflict is not transient. */
+export const FETCH_RETRY_MS = 1000;
+async function fetchWithRetry(git, args, cwd, timeoutMs) {
+    const first = await git(args, cwd, timeoutMs);
+    if (first.ok || isGitLockError(first.out))
+        return first;
+    await new Promise((r) => setTimeout(r, FETCH_RETRY_MS));
+    return git(args, cwd, timeoutMs);
+}
 function gitFailure(out, message) {
     if (isGitLockError(out))
         return { ok: false, lock_conflict: true, message: 'Web update is blocked by a repository lock. Wait for the other Git operation or inspect the checkout manually.' };
@@ -155,7 +165,13 @@ function sortKeys(value) {
 }
 const same = (a, b) => canon(a) === canon(b);
 // ── published release sets ───────────────────────────────────────────────────
+/** `transient`: GitHub was unreachable, slow, or overloaded, so a retry can succeed; the rest describe published state. */
 export class ReleaseUnavailable extends Error {
+    transient;
+    constructor(message, transient = false) {
+        super(message);
+        this.transient = transient;
+    }
 }
 /** GitHub API client: opt-in `TALARIA_RELEASE_TOKEN`, 2 MB cap, and asset redirects only to GitHub's release host with the token stripped. */
 export function githubJson(fetchImpl, env) {
@@ -164,17 +180,25 @@ export function githubJson(fetchImpl, env) {
         const token = (env.TALARIA_RELEASE_TOKEN ?? '').trim();
         if (token)
             headers.Authorization = `Bearer ${token}`;
-        let res = await fetchImpl(API_ROOT + path, { headers, redirect: 'manual', signal: AbortSignal.timeout(5000) });
+        const send = async (url, init) => {
+            try {
+                return await fetchImpl(url, init);
+            }
+            catch (error) {
+                throw new ReleaseUnavailable(`GitHub is unreachable: ${error.message}`, true);
+            }
+        };
+        let res = await send(API_ROOT + path, { headers, redirect: 'manual', signal: AbortSignal.timeout(5000) });
         if (res.status >= 300 && res.status < 400) {
             const target = new URL(res.headers.get('location') ?? '', API_ROOT + path);
             if (target.protocol !== 'https:' || target.hostname !== 'release-assets.githubusercontent.com')
                 throw new ReleaseUnavailable('Unexpected release download redirect');
             const anonymous = { ...headers };
             delete anonymous.Authorization;
-            res = await fetchImpl(target.toString(), { headers: anonymous, signal: AbortSignal.timeout(5000) });
+            res = await send(target.toString(), { headers: anonymous, signal: AbortSignal.timeout(5000) });
         }
         if (!res.ok)
-            throw new ReleaseUnavailable(`GitHub answered ${String(res.status)}`);
+            throw new ReleaseUnavailable(`GitHub answered ${String(res.status)}`, res.status >= 500 || res.status === 429);
         const body = await readCapped(res, 2_000_000);
         if (!body)
             throw new ReleaseUnavailable('Release metadata exceeds the download limit');
@@ -187,7 +211,7 @@ export async function publishedWebRelease(channel, getJson, now = () => performa
     const deadline = now() + 15_000;
     const fetchJson = (path, asset = false) => {
         if (now() >= deadline)
-            throw new ReleaseUnavailable('Release lookup exceeded its deadline; retry or update manually');
+            throw new ReleaseUnavailable('Release lookup exceeded its deadline; retry or update manually', true);
         return getJson(path, { asset });
     };
     const published = [];
@@ -263,6 +287,81 @@ export async function publishedWebRelease(channel, getJson, now = () => performa
     }
     throw new ReleaseUnavailable('No completed Talaria Web release is available on this channel');
 }
+// ── Experimental artifacts (TAL-343) ─────────────────────────────────────────
+const GHCR = 'https://ghcr.io';
+const EXPERIMENTAL_REPOSITORY = 'maudecode/talaria-web-experimental';
+const EXPERIMENTAL_ARTIFACT_TYPE = 'application/vnd.maudecode.talaria-web.experimental.v1';
+const EXPERIMENTAL_LAYER_TYPE = 'application/vnd.maudecode.talaria-web.npm.tgz';
+/** GHCR serves blobs by redirecting here; the pull token never follows. */
+const EXPERIMENTAL_BLOB_HOST = 'pkg-containers.githubusercontent.com';
+export const EXPERIMENTAL_TARBALL_CAP = 200_000_000;
+const EXPERIMENTAL_VERSION = new RegExp(`^${VERSION}-exp\\.([a-f0-9]{12})$`);
+/** Anonymous GHCR client with `githubJson`'s timeouts, caps, and transient classification. */
+export function ghcrExperimental(fetchImpl) {
+    const send = async (url, init) => {
+        try {
+            return await fetchImpl(url, { redirect: 'manual', ...init });
+        }
+        catch (error) {
+            throw new ReleaseUnavailable(`GHCR is unreachable: ${error.message}`, true);
+        }
+    };
+    const check = (res, what) => {
+        if (!res.ok)
+            throw new ReleaseUnavailable(`GHCR answered ${String(res.status)} for the Experimental ${what}`, res.status >= 500 || res.status === 429);
+    };
+    const json = async (res, what) => {
+        check(res, what);
+        const body = await readCapped(res, 2_000_000);
+        if (!body)
+            throw new ReleaseUnavailable(`Experimental ${what} exceeds the download limit`);
+        try {
+            return dict(JSON.parse(body.toString('utf8')));
+        }
+        catch {
+            throw new ReleaseUnavailable(`Invalid Experimental ${what}`);
+        }
+    };
+    const token = async () => {
+        const body = await json(await send(`${GHCR}/token?scope=repository:${EXPERIMENTAL_REPOSITORY}:pull`, { signal: AbortSignal.timeout(5000) }), 'pull token');
+        if (typeof body.token !== 'string' || !body.token)
+            throw new ReleaseUnavailable('GHCR did not issue an anonymous pull token');
+        return body.token;
+    };
+    return {
+        release: async () => {
+            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 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)
+                throw new ReleaseUnavailable('The Experimental artifact has an unexpected format');
+            const annotations = dict(m.annotations);
+            const sourceRevision = annotations['org.opencontainers.image.revision'];
+            const version = annotations['org.opencontainers.image.version'];
+            const size = layer.size;
+            if (typeof sourceRevision !== 'string' || !SHA.test(sourceRevision) || typeof version !== 'string' || EXPERIMENTAL_VERSION.exec(version)?.[4] !== sourceRevision.slice(0, 12)
+                || typeof layer.digest !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(layer.digest) || typeof size !== 'number' || !Number.isInteger(size) || size < 1 || size > EXPERIMENTAL_TARBALL_CAP) {
+                throw new ReleaseUnavailable('The Experimental artifact has malformed provenance');
+            }
+            return { tag: `web-exp-v${version}`, version, sourceRevision, digest: layer.digest, size };
+        },
+        download: async (release) => {
+            let res = await send(`${GHCR}/v2/${EXPERIMENTAL_REPOSITORY}/blobs/${release.digest}`, { headers: { Authorization: `Bearer ${await token()}` }, signal: AbortSignal.timeout(120_000) });
+            if (res.status >= 300 && res.status < 400) {
+                const target = new URL(res.headers.get('location') ?? '', GHCR);
+                if (target.protocol !== 'https:' || target.hostname !== EXPERIMENTAL_BLOB_HOST)
+                    throw new ReleaseUnavailable('Unexpected Experimental download redirect');
+                res = await send(target.toString(), { redirect: 'error', signal: AbortSignal.timeout(120_000) });
+            }
+            check(res, 'download');
+            const body = await readCapped(res, release.size);
+            if (body?.length !== release.size || `sha256:${createHash('sha256').update(body).digest('hex')}` !== release.digest)
+                throw new ReleaseUnavailable('The Experimental download does not match its digest');
+            return body;
+        },
+    };
+}
 // ── Web checkout ─────────────────────────────────────────────────────────────
 /** The git root when `webRoot` is `<root>/web` of a Talaria checkout with a GitHub `maudecode/talaria` origin; else null. */
 export async function checkoutRoot(webRoot, git) {
@@ -305,7 +404,7 @@ export async function npmInstallInfo(webRoot, npm = runPackageNpm, container = e
     catch {
         return null;
     }
-    if (metadata.name !== WEB_NPM_PACKAGE || typeof metadata.version !== 'string' || !new RegExp(`^${VERSION}$`).test(metadata.version))
+    if (metadata.name !== WEB_NPM_PACKAGE || typeof metadata.version !== 'string' || !(new RegExp(`^${VERSION}$`).test(metadata.version) || EXPERIMENTAL_VERSION.test(metadata.version)))
         return null;
     const global = await npm(['root', '--global'], webRoot, 10_000);
     if (!global.ok || !isAbsolute(global.out))
@@ -336,6 +435,30 @@ function diskRelease(webRoot) {
         return null;
     }
 }
+/** The channel an npm install came from: its release tag prefix (`web-exp-v` or `web-v`). */
+function npmInstallChannel(installed, id) {
+    return str(diskRelease(installed.packageRoot)?.tag ?? id.release().tag).startsWith('web-exp-v') ? 'experimental' : 'stable';
+}
+/** An npm install on Experimental: behind when its source differs from the `experimental` tag, or when switching channels. */
+async function checkNpmExperimental(result, installed, id, registry) {
+    let release;
+    try {
+        release = await registry.release();
+    }
+    catch (error) {
+        const unavailable = error instanceof ReleaseUnavailable ? error : new ReleaseUnavailable('The Experimental 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: 1, channel_switch: true, message: `Switching to Experimental installs ${release.version}.` };
+    if (disk?.sourceRevision !== release.sourceRevision)
+        return { ...result, current_sha: current, behind: 1, message: `Experimental 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.' } : {}) };
+}
 /** Python `verify_release_source`: the stamp Web expects for `release`, computed from immutable blobs at its source revision. */
 export async function verifyReleaseSource(root, release, git) {
     const files = {};
@@ -390,9 +513,12 @@ function mainStamp(root, id) {
     return data;
 }
 async function mainRevision(root, git) {
-    const fetched = await git(['fetch', '--no-tags', 'origin', 'refs/heads/main:refs/remotes/origin/main'], root, 30_000);
+    const fetched = await fetchWithRetry(git, ['fetch', '--no-tags', 'origin', 'refs/heads/main:refs/remotes/origin/main'], root, 30_000);
     if (!fetched.ok)
         return [null, fetched.out];
+    // Single-branch clones never receive tags, so `git describe` would name a stale Web release.
+    // Best effort and unforced: a conflicting local tag is kept and never fails the main fetch.
+    await git(['fetch', '--no-tags', 'origin', 'refs/tags/web-v*:refs/tags/web-v*', 'refs/tags/web-exp-v*:refs/tags/web-exp-v*'], root, 30_000);
     const source = await git(['rev-parse', 'refs/remotes/origin/main^{commit}'], root);
     return source.ok && SHA.test(source.out) ? [source.out, ''] : [null, ''];
 }
@@ -423,8 +549,10 @@ async function checkMainUpdate(root, result, git, id) {
     if (root === null)
         return { ...result, manual_update: true, message: 'Main updates require an authenticated Talaria source checkout with Web under web/.' };
     const [source, error] = await mainRevision(root, git);
-    if (source === null)
-        return { ...result, error: gitFailure(error, 'Could not fetch origin/main; check Git read access.').message };
+    if (source === null) {
+        const detail = sanitizeGitDiagnostic(error);
+        return { ...result, stale_check: true, error: gitFailure(error, detail ? `Could not fetch origin/main: ${detail}` : 'Could not fetch origin/main; check Git read access.').message };
+    }
     Object.assign(result, { latest_sha: source, latest_version: `main@${source.slice(0, 12)}` });
     const head = await git(['rev-parse', 'HEAD'], root);
     const status = await git(['status', '--porcelain', '--untracked-files=all'], root);
@@ -454,23 +582,29 @@ async function checkMainUpdate(root, result, git, id) {
     return result;
 }
 /** Python `check_web_update`. */
-export async function checkWebUpdate(webRoot, currentVersion, channel, git, getJson, id, npmRun = runPackageNpm) {
+export async function checkWebUpdate(webRoot, currentVersion, channel, git, getJson, id, npmRun = runPackageNpm, registry) {
     const root = await checkoutRoot(webRoot, git);
     const npmInstall = root === null ? await npmInstallInfo(webRoot, npmRun) : null;
     const result = { name: 'webui', channel, repo_url: REPOSITORY_URL, current_version: currentVersion, behind: null, no_git: root === null };
     if (channel === 'experimental' && root !== null)
         return checkMainUpdate(root, result, git, id);
+    if (channel === 'experimental' && npmInstall && registry)
+        return checkNpmExperimental(result, npmInstall, id, registry);
     let release;
     try {
         release = await publishedWebRelease(channel, getJson);
     }
     catch (error) {
         if (error instanceof ReleaseUnavailable)
-            return { ...result, manual_update: true, error: error.message };
+            return { ...result, manual_update: true, error: error.message, ...(error.transient ? { stale_check: true } : {}) };
         return { ...result, manual_update: true, error: 'Talaria release metadata is unavailable. Private repositories require TALARIA_RELEASE_TOKEN with Contents read access.' };
     }
     Object.assign(result, { latest_version: release.tag, latest_sha: release.sourceRevision, branch: release.tag, release_based: true, release_url: release.release_url, image: release.image });
     if (root === null) {
+        if (npmInstall && channel === 'stable' && release.npm && npmInstallChannel(npmInstall, id) === 'experimental') {
+            // A channel switch installs the newest Stable package regardless of version order (TAL-343).
+            return { ...result, current_sha: id.release().sourceRevision ?? null, behind: 1, no_git: true, install_kind: 'npm', npm: release.npm, manual_update: false, channel_switch: true, message: `Switching to Stable installs npm release ${release.version}.` };
+        }
         if (npmInstall && channel === 'stable' && release.npm && !str(id.release().tag).startsWith('web-exp-v')) {
             const comparison = compareVersions(npmInstall.version, release.version);
             if (comparison > 0)
@@ -536,34 +670,82 @@ export async function checkWebUpdate(webRoot, currentVersion, channel, git, getJ
         Object.assign(result, { manual_update: true, message: 'Commit or remove local changes before updating; Web updates never discard them.' });
     return result;
 }
-async function applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply) {
-    if (channel !== 'stable')
-        return { ok: false, manual_update: true, message: 'Packaged Experimental updates require manual artifact replacement.' };
-    if (str(id.release().tag).startsWith('web-exp-v'))
-        return { ok: false, manual_update: true, message: 'Switch packaged update channels manually before enabling Stable updates.' };
+export const CHANNEL_SWITCH_BACKUPS = 5;
+/** Web's persisted stores (`settings.json`, the project store, the workspace store) as seen from the state dir. */
+const PERSISTED_STORES = ['settings.json', 'projects.json', 'workspaces.json', 'last_workspace.txt'];
+/** Copy the persisted stores to `<stateDir>/backups/channel-switch-<UTC timestamp>/`, keeping the newest few; throws on failure. */
+export function backupPersistedStores(stateDir, now = new Date(), keep = CHANNEL_SWITCH_BACKUPS) {
+    const root = join(stateDir, 'backups');
+    mkdirSync(root, { recursive: true });
+    const name = `channel-switch-${now.toISOString().replace(/[:.]/g, '-')}`;
+    const target = join(root, name);
+    if (existsSync(target))
+        throw new Error(`${name} already exists`);
+    // Only a complete copy is published under the name that counts toward the retained backups.
+    const partial = mkdtempSync(join(root, `.${name}-`));
+    try {
+        for (const store of PERSISTED_STORES)
+            if (existsSync(join(stateDir, store)))
+                copyFileSync(join(stateDir, store), join(partial, store));
+        renameSync(partial, target);
+    }
+    catch (error) {
+        rmSync(partial, { recursive: true, force: true });
+        throw error;
+    }
+    const backups = readdirSync(root).filter((name) => name.startsWith('channel-switch-')).sort();
+    for (const old of backups.slice(0, Math.max(0, backups.length - keep)))
+        rmSync(join(root, old), { recursive: true, force: true });
+    return target;
+}
+async function applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply, packaged) {
     const installed = await npmInstallInfo(webRoot, npmRun);
     if (!installed)
         return { ok: false, manual_update: true, message: 'Automatic npm updates require a direct global @maudecode/talaria-web installation.' };
-    let release;
-    try {
-        release = await publishedWebRelease('stable', getJson);
+    // Switching channels installs the selected channel's newest artifact regardless of version order (TAL-343).
+    const switching = npmInstallChannel(installed, id) !== channel;
+    const onDisk = diskRelease(installed.packageRoot);
+    let target;
+    if (channel === 'stable') {
+        let release;
+        try {
+            release = await publishedWebRelease('stable', getJson);
+        }
+        catch {
+            return { ok: false, message: 'Cannot resolve a completed Talaria release. Check private-repository read access.' };
+        }
+        if (!release.npm)
+            return { ok: false, manual_update: true, message: 'The completed Stable release does not include an npm package identity.' };
+        target = { version: release.version, sourceRevision: release.sourceRevision, label: `npm release ${release.version}`, matches: (r) => same(r, release.runtime), npm: release.npm };
+        if (!switching) {
+            if (!canApply())
+                return { ok: false, message: 'Web update deferred because its settings or lifecycle changed.' };
+            const comparison = compareVersions(installed.version, release.version);
+            if (comparison > 0)
+                return { ok: false, manual_update: true, message: 'This npm installation is ahead of the selected Stable release.' };
+            if (comparison === 0 && !target.matches(onDisk))
+                return { ok: false, manual_update: true, message: 'Installed npm release metadata does not match the completed release.' };
+        }
     }
-    catch {
-        return { ok: false, message: 'Cannot resolve a completed Talaria release. Check private-repository read access.' };
+    else {
+        if (!packaged.registry)
+            return { ok: false, manual_update: true, message: 'Packaged Experimental updates are unavailable in this installation.' };
+        let release;
+        try {
+            release = await packaged.registry.release();
+        }
+        catch (error) {
+            return { ok: false, message: error instanceof ReleaseUnavailable ? error.message : 'The Experimental 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 };
     }
-    if (!release.npm)
-        return { ok: false, manual_update: true, message: 'The completed Stable release does not include an npm package identity.' };
-    if (!canApply())
-        return { ok: false, message: 'Web update deferred because its settings or lifecycle changed.' };
-    const comparison = compareVersions(installed.version, release.version);
-    if (comparison > 0)
-        return { ok: false, manual_update: true, message: 'This npm installation is ahead of the selected Stable release.' };
-    if (comparison === 0) {
-        if (!same(diskRelease(installed.packageRoot), release.runtime))
-            return { ok: false, manual_update: true, message: 'Installed npm release metadata does not match the completed release.' };
-        if (same(id.release(), release.runtime))
-            return { ok: true, up_to_date: true, target: 'webui', channel, message: 'Talaria Web already contains the selected npm release.' };
-        return { ok: true, target: 'webui', channel, sourceRevision: release.sourceRevision, npm: release.npm, message: `Restarting Talaria Web with npm release ${release.version}.` };
+    const current = !switching && target.matches(onDisk);
+    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}.` };
     }
     if (!canApply())
         return { ok: false, message: 'Web update deferred because its settings or lifecycle changed.' };
@@ -573,19 +755,42 @@ async function applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply
     const candidate = join(staging, 'lib/node_modules/@maudecode/talaria-web');
     const backup = join(staging, 'previous');
     let keepBackup = false;
+    let stores = null;
     try {
-        const update = await npmRun(['install', '--global', '--prefix', staging, '--no-audit', '--no-fund', release.npm], staging, WEB_BUILD_TIMEOUT_MS);
+        let spec = target.npm ?? '';
+        if (target.experimental) {
+            let tarball;
+            try {
+                tarball = await packaged.registry.download(target.experimental);
+            }
+            catch (error) {
+                return { ok: false, verification_failed: true, target: 'webui', channel, message: `${error instanceof ReleaseUnavailable ? error.message : 'The Experimental download failed'}. The installed package was preserved.` };
+            }
+            spec = join(staging, 'talaria-web-experimental.tgz');
+            writeFileSync(spec, tarball);
+        }
+        const update = await npmRun(['install', '--global', '--prefix', staging, '--no-audit', '--no-fund', spec], staging, WEB_BUILD_TIMEOUT_MS);
         if (!update.ok)
             return { ok: false, install_failed: true, target: 'webui', channel, message: `npm update failed: ${sanitizeGitDiagnostic(update.out, 1000) || 'unknown error'}` };
         const metadata = dict(JSON.parse(readFileSync(join(candidate, 'package.json'), 'utf8')));
         const bins = dict(metadata.bin);
-        if (metadata.name !== WEB_NPM_PACKAGE || metadata.version !== release.version || !same(diskRelease(candidate), release.runtime)
+        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 the completed release. 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 Experimental artifact'}. The installed package was preserved.` };
         }
-        const current = await npmInstallInfo(webRoot, npmRun);
-        if (!canApply() || current?.packageRoot !== installed.packageRoot || current.version !== installed.version)
+        const recheck = await npmInstallInfo(webRoot, npmRun);
+        if (!canApply() || recheck?.packageRoot !== installed.packageRoot || recheck.version !== installed.version)
             return { ok: false, message: 'The npm installation or update settings changed; retry the update.' };
+        if (switching) {
+            try {
+                if (!packaged.stateDir)
+                    throw new Error('the Web state directory is unknown');
+                stores = backupPersistedStores(packaged.stateDir);
+            }
+            catch (error) {
+                return { ok: false, backup_failed: true, target: 'webui', channel, message: `Channel switch aborted: Web settings could not be backed up (${sanitizeGitDiagnostic(error.message, 300)}). The installed package was preserved.` };
+            }
+        }
         renameSync(installed.packageRoot, backup);
         try {
             renameSync(candidate, installed.packageRoot);
@@ -609,13 +814,14 @@ 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: release.sourceRevision, npm: release.npm, message: `Updated Talaria Web to npm release ${release.version}.` };
+    return { ok: true, target: 'webui', channel, 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`: fast-forward a recognized clean checkout to main or a published Stable tag. */
-export async function applyWebUpdate(webRoot, channel, git, getJson, id, build = runNpm, npmRun = runPackageNpm, canApply = () => true) {
+export async function applyWebUpdate(webRoot, channel, git, getJson, id, build = runNpm, npmRun = runPackageNpm, canApply = () => true, packaged = {}) {
     const root = await checkoutRoot(webRoot, git);
     if (root === null)
-        return applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply);
+        return applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply, packaged);
     const status = await git(['status', '--porcelain', '--untracked-files=all'], root);
     if (!status.ok || status.out)
         return { ok: false, dirty: true, message: 'Web update refused: the checkout must be clean, including untracked files.' };
@@ -739,6 +945,12 @@ 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;
 }
+async function verifiedAgentIdentity(path, expectedRevision, git) {
+    const head = await git(['rev-parse', 'HEAD'], path);
+    if (!head.ok || head.out !== expectedRevision || !SHA.test(head.out))
+        return null;
+    return { verified_revision: head.out, verified_version: await currentReleaseTag(path, git) };
+}
 const headContainsRef = async (path, ref, git) => (await git(['merge-base', '--is-ancestor', ref, 'HEAD'], path)).ok;
 const canFastForwardTo = async (path, ref, git) => (await git(['merge-base', '--is-ancestor', 'HEAD', ref], path)).ok;
 async function detectDefaultBranch(path, git) {
@@ -795,7 +1007,7 @@ async function isDirty(path, git) {
 export async function checkAgentUpdate(path, git, channel = DEFAULT_CHANNEL) {
     if (!path || !existsSync(join(path, '.git')))
         return { name: 'agent', behind: null, no_git: true };
-    const fetched = await git(['fetch', 'origin', '--tags', '--force'], path, 15_000);
+    const fetched = await fetchWithRetry(git, ['fetch', 'origin', '--tags', '--force'], path, 15_000);
     if (!fetched.ok) {
         const message = fetched.out ? `fetch failed: ${sanitizeGitDiagnostic(fetched.out)}` : 'fetch failed';
         return { name: 'agent', channel, behind: null, error: message, stale_check: true, dirty: await isDirty(path, git) };
@@ -824,8 +1036,12 @@ export async function applyAgentUpdate(path, git, channel = DEFAULT_CHANNEL, pol
     catch (error) {
         return { ok: false, message: error.message };
     }
-    if (info.current_sha === info.latest_sha)
-        return { ok: true, up_to_date: true, target: 'agent', message: 'Agent is up to date.' };
+    if (info.current_sha === info.latest_sha) {
+        const verified = await verifiedAgentIdentity(path, str(info.latest_sha), git);
+        if (!verified)
+            return { ok: false, message: 'The installed Agent revision could not be verified.' };
+        return { ok: true, up_to_date: true, target: 'agent', message: 'Agent is up to date.', ...verified };
+    }
     if (info.manual_update || info.error)
         return { ...info, ok: false, message: info.message ?? info.error };
     const warning = confirmAgent(info, policy);
@@ -864,7 +1080,10 @@ export async function applyAgentUpdate(path, git, channel = DEFAULT_CHANNEL, pol
         if (!popped.ok)
             message += '. Local changes remain in `git stash list`; resolve them manually.';
     }
-    return { ok: true, message, target: 'agent', ref };
+    const verified = await verifiedAgentIdentity(path, revision, git);
+    if (!verified)
+        return { ok: false, message: 'The Agent update completed, but the installed revision could not be verified.', target: 'agent' };
+    return { ok: true, message, target: 'agent', ref, ...verified };
 }
 async function restoreStash(path, git, pullOut) {
     if ((await git(['stash', 'pop'], path)).ok)
@@ -903,7 +1122,10 @@ export async function forceAgentUpdate(path, git, log, channel = DEFAULT_CHANNEL
         log(`[updates] force update: git clean -fd failed (continuing to reset --hard): ${cleaned.out}`);
     if (!(await git(['reset', '--hard', revision], path)).ok)
         return { ok: false, message: `Force reset to ${ref} failed` };
-    return { ok: true, message: `agent force-updated to ${ref}`, target: 'agent', ref };
+    const verified = await verifiedAgentIdentity(path, revision, git);
+    if (!verified)
+        return { ok: false, message: 'The Agent force update completed, but the installed revision could not be verified.', target: 'agent' };
+    return { ok: true, message: `agent force-updated to ${ref}`, target: 'agent', ref, ...verified };
 }
 /** Python `_inventory_locks`: report `.git/**\/*.lock` without touching any of them. */
 export function inventoryLocks(path) {
@@ -1058,6 +1280,7 @@ export class UpdateService {
     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;
     autoTimer = null;
     autoStarted = false;
@@ -1117,8 +1340,11 @@ export class UpdateService {
         this.checkingKey = key;
         this.checking = (async () => {
             try {
-                const webui = await checkWebUpdate(this.deps.webRoot, this.deps.webuiVersion, channel, this.git, this.deps.getJson, this.deps.identity, this.deps.npm ?? runPackageNpm);
-                const agent = includeAgent ? await checkAgentUpdate(this.deps.agentDir(), this.git, agentChannel) : ignoredAgent();
+                const webui = this.keepLastGood('webui', channel, await checkWebUpdate(this.deps.webRoot, this.deps.webuiVersion, channel, this.git, this.deps.getJson, this.deps.identity, this.deps.npm ?? runPackageNpm, this.deps.experimental));
+                // The check may have fetched release tags the startup `git describe` never saw.
+                if (this.deps.refreshWebuiVersion)
+                    webui.current_version = this.deps.refreshWebuiVersion();
+                const agent = includeAgent ? this.keepLastGood('agent', agentChannel, await checkAgentUpdate(this.deps.agentDir(), this.git, agentChannel)) : ignoredAgent();
                 if (agent.latest_sha)
                     Object.assign(agent, agentWarning(agent, this.agentPolicy()));
                 Object.assign(this.cache, { webui, agent, checked_at: this.now(), include_agent: includeAgent, channel, agent_channel: agentChannel });
@@ -1131,6 +1357,18 @@ export class UpdateService {
         })();
         return this.checking;
     }
+    /** A failed fetch (`stale_check`) keeps the channel's last good result until the cache TTL, so a network blip never flips the status; persistent failures surface. */
+    keepLastGood(target, channel, result) {
+        const key = `${target}:${channel}`;
+        if (!result.stale_check) {
+            if (!result.error)
+                this.lastGood.set(key, { at: this.now(), result });
+            return result;
+        }
+        this.deps.log(`[updates] ${target} fetch failed: ${str(result.error)}`);
+        const prior = this.lastGood.get(key);
+        return prior && this.now() - prior.at < CACHE_TTL_S ? { ...prior.result, stale_check: true } : result;
+    }
     startAutoApply(intervalMs = AUTO_UPDATE_INTERVAL_MS) {
         if (this.autoStarted || this.autoRestartScheduled)
             return;
@@ -1155,11 +1393,19 @@ export class UpdateService {
     }
     /** Shared turn admission stays closed from update start through the supervisor restart. */
     blocksNewWork() { return this.applying || this.autoRestartScheduled; }
+    pendingRestartResponse(target) {
+        if (!this.autoRestartScheduled)
+            return null;
+        if (target === 'webui')
+            return { ok: true, target, restart_scheduled: true, message: 'A Web restart is already scheduled.' };
+        return { ok: false, status: 'already_in_progress', target, message: 'A Talaria Web restart is already scheduled. Wait for the server to restart before updating Hermes Agent.' };
+    }
     async autoApplyOnce() {
         if (this.autoRunning || this.applying || this.autoRestartScheduled || !(this.deps.checkEnabled?.() ?? this.deps.autoApply?.()))
             return null;
         this.autoRunning = true;
         const lifecycle = this.lifecycle;
+        let notificationId = null;
         try {
             const channel = this.deps.channel();
             const stillEnabled = () => lifecycle === this.lifecycle && Boolean(this.deps.autoApply?.()) && (this.deps.checkEnabled?.() ?? true) && channel === this.deps.channel();
@@ -1173,13 +1419,26 @@ export class UpdateService {
             }
             if (!(Number(web.behind) > 0 || web.metadata_repair === true))
                 return web;
+            notificationId = this.deps.autoNotification?.begin() ?? null;
             const result = await this.apply('webui', channel, stillEnabled);
+            if (notificationId) {
+                if (result.restart_blocked === true)
+                    this.deps.autoNotification?.transition(notificationId, 'blocked');
+                else if (result.ok !== true)
+                    this.deps.autoNotification?.transition(notificationId, 'failed');
+                else if (result.restart_scheduled === true)
+                    this.deps.autoNotification?.transition(notificationId, 'restarting', str(result.sourceRevision || result.candidate_revision));
+                else
+                    this.deps.autoNotification?.transition(notificationId, 'succeeded');
+            }
             this.deps.log(`[updates] automatic Web update: ${str(result.message || (result.ok ? 'applied' : 'failed'))}`);
             if (!result.ok)
                 this.cache.webui = { ...web, message: result.message, error: result.restart_blocked ? undefined : result.message };
             return result;
         }
         catch (error) {
+            if (notificationId)
+                this.deps.autoNotification?.transition(notificationId, 'failed');
             this.deps.log(`[updates] automatic Web update failed: ${error.message}`);
             return { ok: false, error: error.message };
         }
@@ -1217,8 +1476,9 @@ export class UpdateService {
     async apply(target, channel, canApply = () => true, agentOptions = {}) {
         if (this.checking)
             await this.checking;
-        if (this.autoRestartScheduled)
-            return { ok: true, restart_scheduled: true, message: 'A Web restart is already scheduled.' };
+        const pendingRestart = this.pendingRestartResponse(target);
+        if (pendingRestart)
+            return pendingRestart;
         if (!canApply())
             return { ok: false, message: 'Web update settings changed; update deferred.' };
         const blocked = this.blockedResponse(target);
@@ -1230,7 +1490,7 @@ export class UpdateService {
     async applyInner(target, channel, canApply = () => true, agentOptions = {}) {
         if (target === 'webui') {
             const lifecycle = this.lifecycle;
-            const result = await applyWebUpdate(this.deps.webRoot, channel, this.git, this.deps.getJson, this.deps.identity, this.deps.build ?? runNpm, this.deps.npm ?? runPackageNpm, canApply);
+            const result = await applyWebUpdate(this.deps.webRoot, channel, this.git, this.deps.getJson, this.deps.identity, this.deps.build ?? runNpm, this.deps.npm ?? runPackageNpm, canApply, { registry: this.deps.experimental, stateDir: this.deps.stateDir });
             // 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;
@@ -1286,6 +1546,9 @@ export class UpdateService {
             await this.checking;
         if (target === 'webui')
             return this.apply(target, channel);
+        const pendingRestart = this.pendingRestartResponse(target);
+        if (pendingRestart)
+            return pendingRestart;
         const blocked = this.blockedResponse(target);
         if (blocked)
             return Promise.resolve(blocked);
@@ -1300,6 +1563,9 @@ export class UpdateService {
     clearLock(target, agentOptions = {}) {
         if (target === 'webui')
             return this.apply(target).then((r) => ({ ...r, lock_recovery: { action: 'retry-only' } }));
+        const pendingRestart = this.pendingRestartResponse(target);
+        if (pendingRestart)
+            return Promise.resolve(pendingRestart);
         const blocked = this.blockedResponse(target);
         if (blocked)
             return Promise.resolve(blocked);