@maudecode/talaria-web 1.11.0 → 1.13.0

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, 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';
@@ -22,9 +23,6 @@ export const REPOSITORY_URL = `https://github.com/${REPOSITORY}`;
 export const API_ROOT = `https://api.github.com/repos/${REPOSITORY}`;
 /** Anchored paths work from both the git root and Web's nested working directory. */
 export const WEB_UPDATE_PATHS = [':(top)web/', ':(top)contracts/'];
-/** Relative to the git root: the release stamp and the blobs it is verified against. */
-export const RELEASE_STAMP = 'web/_release.json';
-const RELEASE_BLOBS = ['sidecar/agent_dependency.json', 'contract_versions.json'];
 export const CACHE_TTL_S = 1800;
 export const AUTO_UPDATE_INTERVAL_MS = 5 * 60_000;
 export const RESTART_MAX_WAIT_S = 300;
@@ -57,15 +55,9 @@ export const runGit = (args, cwd, timeoutMs = 10_000) => new Promise((done) => {
         done({ out: err || out || `git exited with status ${String(e.code)}`, ok: false });
     });
 });
-/** The steps a source checkout needs after its files change (README "From a source checkout"), run from `<root>/web`. */
-export const WEB_BUILD_STEPS = [
-    ['ci', '--workspace', 'packages/contracts', '--workspace', 'packages/server', '--include=dev'],
-    ['run', 'build', '--workspace', 'packages/contracts'],
-    ['run', 'build', '--workspace', 'packages/server'],
-];
 export const WEB_BUILD_TIMEOUT_MS = 10 * 60_000;
-/** The artifact the supervisor re-executes; a build that does not leave it behind did not succeed. */
-export const WEB_SERVER_ENTRY = 'packages/server/dist/bin/talaria-web.js';
+/** Source checkouts are contributor-only: they update with git, and the updater never mutates them (TAL-379). */
+export const CONTRIBUTOR_CHECKOUT_MESSAGE = 'This is a contributor source checkout. Update it with git and rebuild Web (see web/README.md); only npm installs update automatically.';
 const runNpmCommand = (args, cwd, timeoutMs, env) => new Promise((done) => {
     // Prefer the npm beside the running node so a supervisor started with an absolute node path still finds it.
     const beside = join(dirname(process.execPath), 'npm');
@@ -87,20 +79,7 @@ const runNpmCommand = (args, cwd, timeoutMs, env) => new Promise((done) => {
         done({ out: (stderr.trim() || stdout.trim() || `npm exited with status ${String(e.code)}`).slice(-4000), ok: false });
     });
 });
-export const runNpm = (args, cwd, timeoutMs) => runNpmCommand(args, cwd, timeoutMs, { ...process.env, NODE_ENV: 'development' });
 export const runPackageNpm = (args, cwd, timeoutMs) => runNpmCommand(args, cwd, timeoutMs, process.env);
-/** Install and build the checkout's Web packages; null on success, else the message for the caller. */
-async function buildWeb(root, build) {
-    const cwd = join(root, 'web');
-    for (const step of WEB_BUILD_STEPS) {
-        const result = await build(step, cwd, WEB_BUILD_TIMEOUT_MS);
-        if (!result.ok)
-            return `\`npm ${step.join(' ')}\` failed: ${result.out || 'unknown error'}`;
-    }
-    if (!existsSync(join(cwd, WEB_SERVER_ENTRY)))
-        return `build finished without producing ${WEB_SERVER_ENTRY}`;
-    return null;
-}
 export const isGitLockError = (output) => { const l = output.toLowerCase(); return GIT_LOCK_SIGNATURES.some((s) => l.includes(s)); };
 /** Python `_sanitize_git_diagnostic`: strip URL userinfo, GitHub token shapes, and secret query values. */
 export function sanitizeGitDiagnostic(output, limit = 300) {
@@ -116,10 +95,14 @@ function fetchFailureMessage(out, network) {
     const lower = detail.toLowerCase();
     return NETWORK_FAILURES.some((s) => lower.includes(s)) ? network : `fetch failed: ${detail}`;
 }
-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.' };
-    return { ok: false, message };
+/** 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 normalizeRemoteUrl(remote) {
     let url = remote.trim();
@@ -155,7 +138,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 +153,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 +184,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 +260,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 +377,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,141 +408,54 @@ function diskRelease(webRoot) {
         return null;
     }
 }
-/** 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 = {};
-    for (const name of RELEASE_BLOBS) {
-        const shown = await git(['show', `${release.sourceRevision}:web/${name}`], root);
-        if (!shown.ok)
-            throw new Error('missing release metadata');
-        files[name] = JSON.parse(shown.out);
-    }
-    const pin = dict(files['sidecar/agent_dependency.json']);
-    const versions = dict(files['contract_versions.json']);
-    const expected = {
-        tag: release.tag,
-        version: release.version,
-        sourceRevision: release.sourceRevision,
-        releaseSet: release.sourceRevision,
-        contracts: { appWeb: [dict(versions.appWeb).fixtureVersion], webRelay: [dict(versions.webRelay).protocolVersion] },
-        compatibleAgent: { ...dict(pin['x-talaria']), image: dict(dict(pin.services)['hermes-agent']).image },
-    };
-    if (!same(expected, release.runtime))
-        throw new Error('release metadata differs from source');
-    return expected;
-}
-const stampPath = (root) => join(root, RELEASE_STAMP);
-const readStamp = (path) => {
-    if (!existsSync(path) && !isSymlink(path))
-        return null;
-    if (isSymlink(path))
-        throw new Error('local release stamp is a symbolic link');
-    return readFileSync(path, 'utf8');
-};
-const isSymlink = (path) => { try {
-    return lstatSync(path).isSymbolicLink();
-}
-catch {
-    return false;
-} };
-/** Python `_verified_release_stamp`: `[expected, installed]`; throws on a modified stamp. */
-async function verifiedReleaseStamp(root, release, git, id) {
-    const expected = await verifyReleaseSource(root, release, git);
-    const raw = readStamp(stampPath(root));
-    const installed = raw === null ? null : JSON.parse(raw);
-    if (installed !== null && ![id.release(), id.stamped(), expected].some((c) => same(c, installed)))
-        throw new Error('local release stamp was modified');
-    return [expected, installed];
-}
-/** Python `_main_stamp`: the unchanged generated stamp bytes (to discard when leaving a release), else null. */
-function mainStamp(root, id) {
-    const data = readStamp(stampPath(root));
-    if (data !== null && (!id.stamped().tag || !same(JSON.parse(data), id.stamped())))
-        throw new Error('local release stamp was modified');
-    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);
-    if (!fetched.ok)
-        return [null, fetched.out];
-    const source = await git(['rev-parse', 'refs/remotes/origin/main^{commit}'], root);
-    return source.ok && SHA.test(source.out) ? [source.out, ''] : [null, ''];
-}
-async function mainPathsDiffer(root, before, after, git) {
-    const files = await git(['diff', '--no-renames', '--name-only', before, after, '--', ...WEB_UPDATE_PATHS], root);
-    return files.ok ? Boolean(files.out) : null;
-}
-async function mainChangeCount(root, before, after, git) {
-    const changed = await mainPathsDiffer(root, before, after, git);
-    if (changed === null)
-        return null;
-    if (!changed)
-        return 0;
-    const count = await git(['rev-list', '--count', '--full-history', `${before}..${after}`, '--', ...WEB_UPDATE_PATHS], root);
-    const n = Number.parseInt(count.out, 10);
-    return count.ok && /^\d+$/.test(count.out) && n > 0 ? n : null;
-}
-async function mainRestartPending(root, head, git, id) {
-    const running = id.runningSourceRevision();
-    if (running === head)
-        return false;
-    if (!running)
-        return true;
-    return (await mainPathsDiffer(root, running, head, git)) !== false;
+/** 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';
 }
-async function checkMainUpdate(root, result, git, id) {
-    Object.assign(result, { branch: 'origin/main', release_based: false });
-    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 };
-    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);
-    if (!head.ok || !SHA.test(head.out) || !status.ok)
-        return { ...result, manual_update: true, error: 'Could not verify the source checkout' };
-    Object.assign(result, { installed_sha: head.out, dirty: Boolean(status.out) });
-    const base = await git(['merge-base', head.out, source], root);
-    result.current_sha = base.ok && SHA.test(base.out) ? base.out : null;
-    if (result.current_sha)
-        result.compare_url = `${REPOSITORY_URL}/compare/${base.out}...${source}`;
-    if (!base.ok || base.out !== head.out)
-        return { ...result, manual_update: true, message: 'This checkout is ahead of or diverged from origin/main; reconcile it manually.' };
-    const count = await mainChangeCount(root, head.out, source, git);
-    if (count === null)
-        return { ...result, error: 'Could not compare the source checkout with origin/main' };
+/** 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 {
-        mainStamp(root, id);
+        release = await registry.release();
     }
-    catch {
-        return { ...result, manual_update: true, error: 'Inspect the modified release stamp before updating.' };
-    }
-    Object.assign(result, { behind: count, metadata_repair: count === 0 && (await mainRestartPending(root, head.out, git, id)) });
-    if (status.out)
-        Object.assign(result, { manual_update: true, message: 'Commit or remove local changes before updating; Web updates never discard them.' });
-    else if (result.metadata_repair)
-        result.message = 'Source is current; finish the update to restart with that revision.';
-    return result;
+    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 `check_web_update`. */
-export async function checkWebUpdate(webRoot, currentVersion, channel, git, getJson, id, npmRun = runPackageNpm) {
+/** Python `check_web_update`: npm and packaged installs; a source checkout is contributor-only (TAL-379). */
+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 (root !== null)
+        return { ...result, manual_update: true, message: CONTRIBUTOR_CHECKOUT_MESSAGE };
+    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)
@@ -495,75 +480,83 @@ export async function checkWebUpdate(webRoot, currentVersion, channel, git, getJ
         }
         return { ...result, current_sha: current, behind, no_git: true, manual_update: true, message: 'Use the published Talaria Web image or authenticated monorepo installation; legacy checkouts require migration.' };
     }
-    const head = await git(['rev-parse', 'HEAD'], root);
-    const status = await git(['status', '--porcelain', '--untracked-files=all'], root);
-    if (!head.ok || !SHA.test(head.out) || !status.ok)
-        return { ...result, manual_update: true, error: 'Could not verify the source checkout' };
-    const current = head.out;
-    Object.assign(result, { installed_sha: current, dirty: Boolean(status.out) });
-    let base;
-    let knownBase;
-    if (current === release.sourceRevision) {
-        try {
-            const [expected, installed] = await verifiedReleaseStamp(root, release, git, id);
-            result.behind = 0;
-            result.metadata_repair = !same(installed, expected) || !same(id.release(), expected);
-            if (result.metadata_repair)
-                result.message = 'Apply the selected release again to repair its metadata or restart with its recorded identity.';
-        }
-        catch {
-            Object.assign(result, { behind: null, manual_update: true, error: 'Could not verify local release provenance; inspect the release stamp before updating.' });
-        }
-        base = current;
-        knownBase = true;
+}
+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);
     }
-    else {
-        const contains = await git(['merge-base', '--is-ancestor', release.sourceRevision, current], root);
-        if (contains.ok)
-            return { ...result, behind: null, manual_update: true, current_sha: null, message: 'This checkout is ahead of the selected release. Manage it manually or check out the published release and restart Web.' };
-        result.behind = 1;
-        const mb = await git(['merge-base', current, release.sourceRevision], root);
-        base = mb.out;
-        knownBase = mb.ok;
-        if (knownBase && base !== current)
-            Object.assign(result, { manual_update: true, message: 'Reconcile divergent source history before updating Web.' });
-    }
-    // Local-only commits cannot appear in a GitHub comparison; omit unresolvable links.
-    result.current_sha = knownBase && SHA.test(base) ? base : null;
-    if (result.current_sha)
-        result.compare_url = `${REPOSITORY_URL}/compare/${base}...${release.sourceRevision}`;
-    if (status.out)
-        Object.assign(result, { manual_update: true, message: 'Commit or remove local changes before updating; Web updates never discard them.' });
-    return result;
+    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) {
-    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.' };
+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 +566,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,128 +625,15 @@ 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) {
-    const root = await checkoutRoot(webRoot, git);
-    if (root === null)
-        return applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply);
-    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.' };
-    for (const marker of ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'rebase-merge', 'rebase-apply', 'BISECT_LOG']) {
-        const path = await git(['rev-parse', '--git-path', marker], root);
-        if (!path.ok || existsSync(resolve(root, path.out)))
-            return { ok: false, message: 'Finish or abort the repository operation before updating Web.' };
-    }
-    const headRes = await git(['rev-parse', 'HEAD'], root);
-    if (!headRes.ok || !SHA.test(headRes.out))
-        return { ok: false, message: 'Could not verify the current source revision' };
-    const head = headRes.out;
-    const main = channel === 'experimental';
-    let source;
-    let tag;
-    let release = null;
-    if (main) {
-        const [revision, error] = await mainRevision(root, git);
-        if (revision === null)
-            return gitFailure(error, 'Could not fetch origin/main; check Git read access.');
-        source = revision;
-        tag = 'main';
-    }
-    else {
-        try {
-            release = await publishedWebRelease(channel, getJson);
-        }
-        catch {
-            return { ok: false, message: 'Cannot resolve a completed Talaria release. Check private-repository read access.' };
-        }
-        source = release.sourceRevision;
-        tag = release.tag;
-    }
-    if (head !== source && !main) {
-        // Fetch only this immutable tag; never force-replace a local tag or pull an unrecorded tip.
-        const fetched = await git(['fetch', '--no-tags', 'origin', `refs/tags/${tag}:refs/tags/${tag}`], root, 30_000);
-        if (!fetched.ok)
-            return gitFailure(fetched.out, 'Could not fetch the published Web tag. Check Git credentials or a conflicting local tag.');
-        const resolved = await git(['rev-parse', `refs/tags/${tag}^{commit}`], root);
-        if (!resolved.ok || resolved.out !== source)
-            return { ok: false, message: 'Published Web tag does not match the immutable release manifest' };
-    }
-    if (head !== source) {
-        const forward = await git(['merge-base', '--is-ancestor', head, source], root);
-        if (!forward.ok) {
-            const contains = await git(['merge-base', '--is-ancestor', source, head], root);
-            if (contains.ok)
-                return { ok: false, manual_update: true, target: 'webui', channel, message: 'This checkout is ahead of the selected source. Manage it manually; updates never rewind local work.' };
-            return { ok: false, message: 'Web update refused: source histories diverge; reconcile the checkout manually.' };
-        }
-    }
-    if (main) {
-        const count = await mainChangeCount(root, head, source, git);
-        if (count === null)
-            return { ok: false, message: 'Could not compare Web and contract changes against origin/main.' };
-        if (count === 0)
-            source = head; // No checkout mutation for App/Relay-only changes.
-    }
-    // Compare provenance with the immutable incoming files before modifying the checkout.
-    let expected = null;
-    let installed;
-    try {
-        if (main)
-            installed = mainStamp(root, id);
-        else
-            [expected, installed] = await verifiedReleaseStamp(root, release, git, id);
-    }
-    catch {
-        return { ok: false, message: 'Web update refused: source or local provenance does not match the release manifest.' };
-    }
-    const runtimeCurrent = main ? !(await mainRestartPending(root, head, git, id)) : same(installed, expected) && same(id.release(), expected);
-    if (head === source && runtimeCurrent)
-        return { ok: true, up_to_date: true, target: 'webui', channel, message: main ? 'Web and shared contracts are current on main.' : 'Talaria Web already contains the selected release.' };
-    const again = await git(['rev-parse', 'HEAD'], root);
-    const clean = await git(['status', '--porcelain', '--untracked-files=all'], root);
-    if (!again.ok || again.out !== head || !clean.ok || clean.out)
-        return { ok: false, message: 'The checkout changed during the update; retry after it is clean.' };
-    if (!canApply())
-        return { ok: false, message: 'Web update deferred because its settings or lifecycle changed.' };
-    if (head !== source) {
-        const merged = await git(['merge', '--ff-only', '--no-stat', '--no-overwrite-ignore', source], root, 30_000);
-        const actual = await git(['rev-parse', 'HEAD'], root);
-        if (!merged.ok || !actual.ok || actual.out !== source)
-            return gitFailure(merged.out, 'Web fast-forward failed; no local changes were discarded.');
-    }
-    // The supervisor re-executes the built artifact, so the checkout is installed and rebuilt before the stamp claims
-    // the new release; a failed build leaves the old stamp (and the running server) truthful.
-    const buildError = await buildWeb(root, build);
-    if (buildError !== null)
-        return { ok: false, build_failed: true, target: 'webui', channel, sourceRevision: source, message: `Source advanced to ${tag}, but the Web build failed: ${buildError}. Run \`npm ci\` and \`npm run build\` in web/ (see README), then restart Web.` };
-    const stamp = stampPath(root);
-    if (main && installed !== null) {
-        try {
-            if (isSymlink(stamp) || readFileSync(stamp, 'utf8') !== installed)
-                throw new Error('release stamp changed during update');
-            unlinkSync(stamp);
-        }
-        catch {
-            return { ok: false, message: 'Source advanced but its release stamp could not be cleared; inspect it before restarting Web.' };
-        }
-    }
-    else if (!main && !same(installed, expected)) {
-        const temporary = join(dirname(stamp), `.release-${String(process.pid)}-${String(Date.now())}`);
-        try {
-            writeFileSync(temporary, `${JSON.stringify(expected, null, 2)}\n`);
-            renameSync(temporary, stamp);
-        }
-        catch {
-            rmSync(temporary, { force: true });
-            return { ok: false, message: 'Source advanced, but release metadata could not be written. Repair file permissions before restarting Web.' };
-        }
-    }
-    return { ok: true, target: 'webui', channel, sourceRevision: source, message: `Updated Talaria Web to ${tag}.` };
+/** Python `apply_web_update`: installs npm releases; a source checkout is never mutated (TAL-379). */
+export async function applyWebUpdate(webRoot, channel, git, getJson, id, npmRun = runPackageNpm, canApply = () => true, packaged = {}) {
+    if (await checkoutRoot(webRoot, git) !== null)
+        return { ok: false, manual_update: true, target: 'webui', channel, message: CONTRIBUTOR_CHECKOUT_MESSAGE };
+    return applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply, packaged);
 }
-// ── Agent checkout: independent Stable releases or Experimental default branch ──
 async function releaseTags(path, git) {
     const out = await git(['tag', '--list', AGENT_TAG_GLOB, '--sort=-v:refname'], path);
     return out.ok ? out.out.split('\n').map((l) => l.trim()).filter((tag) => /^v\d+\.\d+\.\d+$/.test(tag)) : [];
@@ -739,6 +642,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 +704,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 +733,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 +777,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 +819,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 +977,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 +1037,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 +1054,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 +1090,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 +1116,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', null, undefined, result.message);
+                else if (result.ok !== true)
+                    this.deps.autoNotification?.transition(notificationId, 'failed', null, undefined, result.message || result.error);
+                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', null, undefined, error.message);
             this.deps.log(`[updates] automatic Web update failed: ${error.message}`);
             return { ok: false, error: error.message };
         }
@@ -1217,8 +1173,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 +1187,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.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 +1243,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 +1260,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);