@maudecode/talaria-web 0.0.0 → 1.12.1

package/dist/tools/updates.js

@@ -3,17 +3,20 @@
  *
  * 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. npm builds and unrecognized checkouts report
- * `manual_update`. Agent: the external checkout follows its own `v*` tags with a
+ * from immutable git blobs. Direct global npm installs can replace themselves
+ * 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.
  */
 import { readCapped } from '../http/capped.js';
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+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';
 import { str } from '../util.js';
 export const REPOSITORY = 'MaudeCode/talaria';
 export const REPOSITORY_URL = `https://github.com/${REPOSITORY}`;
@@ -24,11 +27,13 @@ export const WEB_UPDATE_PATHS = [':(top)web/', ':(top)contracts/'];
 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;
 export const DEFAULT_CHANNEL = 'stable';
 const SHA = /^[a-f0-9]{40}$/;
 const VERSION = '(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)';
 const AGENT_TAG_GLOB = 'v*';
+const WEB_NPM_PACKAGE = '@maudecode/talaria-web';
 const GIT_LOCK_SIGNATURES = ["index.lock': file exists", ".lock': file exists", 'another git process seems to be running', 'unable to create .git/index.lock'];
 const NETWORK_FAILURES = ['could not resolve host', 'failed to connect', 'network is unreachable', 'no route to host', 'connection timed out', 'timed out after', 'connection reset by peer', 'remote end hung up unexpectedly', 'tls connection was non-properly terminated', 'ssl certificate problem'];
 export const normalizeChannel = (channel) => (channel === 'experimental' ? 'experimental' : 'stable');
@@ -62,10 +67,11 @@ export const WEB_BUILD_STEPS = [
 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';
-export const runNpm = (args, cwd, timeoutMs) => new Promise((done) => {
+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');
-    execFile(existsSync(beside) ? beside : 'npm', args, { cwd, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024, env: { ...process.env, NODE_ENV: 'development' } }, (error, stdout, stderr) => {
+    const cli = resolve(dirname(process.execPath), '../lib/node_modules/npm/bin/npm-cli.js');
+    execFile(existsSync(cli) ? process.execPath : existsSync(beside) ? beside : 'npm', existsSync(cli) ? [cli, ...args] : args, { cwd, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024, env: { ...env, PATH: `${dirname(process.execPath)}${delimiter}${env.PATH ?? ''}` } }, (error, stdout, stderr) => {
         if (!error) {
             done({ out: stdout.trim(), ok: true });
             return;
@@ -82,6 +88,8 @@ export const runNpm = (args, cwd, timeoutMs) => 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');
@@ -109,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.' };
@@ -148,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) {
@@ -157,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');
@@ -180,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 = [];
@@ -227,6 +258,9 @@ export async function publishedWebRelease(channel, getJson, now = () => performa
         if (typeof source !== 'string' || !SHA.test(source) || component.releaseSet !== source || component.version !== componentTag.split('-v').pop() || typeof component.image !== 'string' || !/^ghcr\.io\/maudecode\/talaria-web@sha256:[a-f0-9]{64}$/.test(component.image)) {
             throw new ReleaseUnavailable('Web release references are mutable or inconsistent');
         }
+        const npm = component.npm;
+        if (npm !== undefined && npm !== `${WEB_NPM_PACKAGE}@${String(component.version)}`)
+            throw new ReleaseUnavailable('Web npm release identity is inconsistent');
         const contracts = dict(m.contracts);
         const supported = {};
         for (const name of ['appWeb', 'webRelay']) {
@@ -245,6 +279,7 @@ export async function publishedWebRelease(channel, getJson, now = () => performa
             sourceRevision: source,
             releaseSet: source,
             image: component.image,
+            npm: typeof npm === 'string' ? npm : null,
             manifestReleaseSet: str(m.releaseSet),
             runtime: { tag: componentTag, version: component.version, sourceRevision: source, releaseSet: source, contracts: supported, compatibleAgent: agent },
             release_url: `${REPOSITORY_URL}/releases/tag/${tag}`,
@@ -252,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) {
@@ -283,6 +393,72 @@ export async function checkoutRoot(webRoot, git) {
         return null;
     }
 }
+/** A real global npm install of this package; local, npx, linked and container trees fail closed. */
+export async function npmInstallInfo(webRoot, npm = runPackageNpm, container = existsSync('/.within_container') || existsSync('/.dockerenv') || existsSync('/run/.containerenv')) {
+    if (container || !webRoot || !existsSync(webRoot))
+        return null;
+    let metadata;
+    try {
+        metadata = dict(JSON.parse(readFileSync(join(webRoot, 'package.json'), 'utf8')));
+    }
+    catch {
+        return null;
+    }
+    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))
+        return null;
+    const expected = join(resolve(global.out), '@maudecode', 'talaria-web');
+    try {
+        if (lstatSync(expected).isSymbolicLink() || realpathSync(expected) !== realpathSync(webRoot))
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { packageRoot: realpathSync(webRoot), version: metadata.version };
+}
+function compareVersions(installed, latest) {
+    const a = installed.split('.').map(Number);
+    const b = latest.split('.').map(Number);
+    for (let i = 0; i < 3; i += 1)
+        if (a[i] !== b[i])
+            return Math.sign((a[i] ?? 0) - (b[i] ?? 0));
+    return 0;
+}
+function diskRelease(webRoot) {
+    try {
+        return validateReleaseInfo(JSON.parse(readFileSync(join(webRoot, '_release.json'), 'utf8')), webRoot);
+    }
+    catch {
+        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 = {};
@@ -337,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, ''];
 }
@@ -370,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);
@@ -401,22 +582,41 @@ async function checkMainUpdate(root, result, git, id) {
     return result;
 }
 /** Python `check_web_update`. */
-export async function checkWebUpdate(webRoot, currentVersion, channel, git, getJson, id) {
+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)
+                return { ...result, current_sha: id.release().sourceRevision ?? null, behind: 0, no_git: true, install_kind: 'npm', manual_update: true, message: 'This npm installation is ahead of the selected Stable release.' };
+            if (comparison < 0)
+                return { ...result, current_sha: id.release().sourceRevision ?? null, behind: 1, no_git: true, install_kind: 'npm', npm: release.npm, manual_update: false, message: `Stable npm update ${release.version} is available.` };
+            const installed = diskRelease(npmInstall.packageRoot);
+            if (!same(installed, release.runtime))
+                return { ...result, current_sha: id.release().sourceRevision ?? null, behind: null, no_git: true, install_kind: 'npm', manual_update: true, error: 'Installed npm release metadata does not match the completed release.' };
+            const metadataRepair = !same(id.release(), release.runtime);
+            return { ...result, current_sha: release.sourceRevision, behind: 0, no_git: true, install_kind: 'npm', npm: release.npm, manual_update: false, metadata_repair: metadataRepair, ...(metadataRepair ? { message: 'The npm package is current; finish the update to restart with that version.' } : {}) };
+        }
         const current = id.release().sourceRevision ?? null;
         const version = new RegExp(`^${channel === 'experimental' ? 'web-exp-v' : 'web-v'}${VERSION}$`).exec(currentVersion);
         let behind = version && current === release.sourceRevision ? 0 : null;
@@ -470,11 +670,158 @@ 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;
 }
+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.' };
+    // 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.' };
+        }
+    }
+    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 };
+    }
+    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.' };
+    // Global npm installs keep dependencies inside the package. Build the replacement beside the old package so
+    // install/verification failures cannot damage the running installation and the final rename stays on one volume.
+    const staging = mkdtempSync(join(dirname(installed.packageRoot), '.talaria-update-'));
+    const candidate = join(staging, 'lib/node_modules/@maudecode/talaria-web');
+    const backup = join(staging, 'previous');
+    let keepBackup = false;
+    let stores = null;
+    try {
+        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 !== target.version || !target.matches(diskRelease(candidate))
+            || !['talaria-web', 'talaria-web-mcp'].every((name) => str(bins[name]).replace(/^\.\//, '') === `dist/bin/${name}.js` && existsSync(join(candidate, `dist/bin/${name}.js`)))) {
+            return { ok: false, verification_failed: true, target: 'webui', channel, message: `The downloaded npm package does not match ${channel === 'stable' ? 'the completed release' : 'the Experimental artifact'}. The installed package was preserved.` };
+        }
+        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);
+        }
+        catch (error) {
+            // Never delete the only surviving copy if a filesystem error also prevents restoration.
+            keepBackup = true;
+            renameSync(backup, installed.packageRoot);
+            keepBackup = false;
+            throw error;
+        }
+    }
+    catch (error) {
+        return { ok: false, install_failed: true, message: `npm update failed: ${sanitizeGitDiagnostic(error.message, 1000)}${keepBackup ? `; previous package retained at ${backup}` : ''}` };
+    }
+    finally {
+        if (!keepBackup) {
+            try {
+                rmSync(staging, { recursive: true, force: true });
+            }
+            catch { /* a leftover staging directory must not prevent restart after a verified switch */ }
+        }
+    }
+    return { ok: true, target: 'webui', channel, sourceRevision: target.sourceRevision, ...(target.npm ? { npm: target.npm } : {}),
+        ...(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) {
+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 { ok: false, manual_update: true, message: 'Automatic updates require a Talaria monorepo checkout with Web under web/. Migrate this installation manually.' };
+        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.' };
@@ -552,6 +899,8 @@ export async function applyWebUpdate(webRoot, channel, git, getJson, id, build =
     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);
@@ -587,105 +936,91 @@ export async function applyWebUpdate(webRoot, channel, git, getJson, id, build =
     }
     return { ok: true, target: 'webui', channel, sourceRevision: source, message: `Updated Talaria Web to ${tag}.` };
 }
-// ── Agent checkout (external project, `v*` tags, stable only) ────────────────
+// ── 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(Boolean) : [];
+    return out.ok ? out.out.split('\n').map((l) => l.trim()).filter((tag) => /^v\d+\.\d+\.\d+$/.test(tag)) : [];
 }
 async function currentReleaseTag(path, git) {
-    const out = await git(['describe', '--tags', '--abbrev=0', '--match', AGENT_TAG_GLOB], path);
+    const out = await git(['describe', '--tags', '--exact-match', '--match', AGENT_TAG_GLOB, 'HEAD'], path);
     return out.ok && out.out ? out.out : null;
 }
-const releaseGap = (tags, current, latest) => (current === latest ? 0 : current !== null && tags.includes(current) ? tags.indexOf(current) : 1);
-async function headIsPastLatestTag(path, current, git) {
-    if (!current)
-        return false;
-    const full = await git(['describe', '--tags', '--always', '--match', AGENT_TAG_GLOB], path);
-    return full.ok && Boolean(full.out) && full.out !== current;
+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) {
+    const refreshed = await git(['remote', 'set-head', 'origin', '--auto'], path, 15_000);
+    if (!refreshed.ok)
+        throw new Error('Agent default branch could not be refreshed from origin');
     const out = await git(['symbolic-ref', 'refs/remotes/origin/HEAD'], path);
-    if (out.ok && out.out)
-        return out.out.split('/').pop() ?? 'master';
-    for (const branch of ['master', 'main'])
-        if ((await git(['rev-parse', '--verify', `origin/${branch}`], path)).ok)
-            return branch;
-    return 'master';
+    const prefix = 'refs/remotes/origin/';
+    if (out.ok && out.out.startsWith(prefix) && (await git(['rev-parse', '--verify', `${out.out}^{commit}`], path)).ok)
+        return out.out.slice(prefix.length);
+    throw new Error('Agent default branch is unavailable');
 }
-async function upstreamRef(path, git) {
-    const upstream = await git(['rev-parse', '--abbrev-ref', '@{upstream}'], path);
-    return upstream.ok && upstream.out ? upstream.out : `origin/${await detectDefaultBranch(path, git)}`;
+async function agentTarget(path, git, channel) {
+    const ref = channel === 'experimental' ? `origin/${await detectDefaultBranch(path, git)}` : (await releaseTags(path, git))[0];
+    if (!ref)
+        throw new Error('No stable Agent release is available');
+    const current = await git(['rev-parse', 'HEAD'], path);
+    const latest = await git(['rev-parse', `${ref}^{commit}`], path);
+    if (!current.ok || !latest.ok || !SHA.test(current.out) || !SHA.test(latest.out))
+        throw new Error('Agent Git identity is unavailable');
+    const count = await git(['rev-list', '--count', `${current.out}..${latest.out}`], path);
+    const behind = count.ok && /^\d+$/.test(count.out) ? Number.parseInt(count.out, 10) : null;
+    const manual = current.out !== latest.out && !(await canFastForwardTo(path, latest.out, git));
+    const remote = normalizeRemoteUrl((await git(['remote', 'get-url', 'origin'], path)).out);
+    return {
+        name: 'agent', channel, branch: ref, current_sha: current.out, latest_sha: latest.out,
+        current_version: await currentReleaseTag(path, git) ?? current.out.slice(0, 12), latest_version: ref,
+        behind, release_based: channel === 'stable', repo_url: remote, compare_url: compareUrl(remote, current.out, latest.out),
+        ...(behind === null ? { error: 'Agent commit count is unavailable' } : {}),
+        ...(manual ? { manual_update: true, message: 'Agent checkout is ahead of or divergent from this channel; refusing to rewind it.' } : {}),
+    };
 }
-/** Python `_select_apply_compare_ref` for the Agent: the latest reachable `v*` tag, else the tracking branch. */
-async function selectAgentCompareRef(path, git) {
-    const tags = await releaseTags(path, git);
-    const latest = tags[0];
-    if (latest) {
-        const current = await currentReleaseTag(path, git);
-        const behind = releaseGap(tags, current, latest);
-        const fallthrough = (behind === 0 && (await headIsPastLatestTag(path, current, git))) || (behind > 0 && (await headContainsRef(path, latest, git))) || (behind > 0 && !(await canFastForwardTo(path, latest, git)));
-        if (!fallthrough)
-            return latest;
-    }
-    return upstreamRef(path, git);
+function agentWarning(info, policy) {
+    return { candidate_revision: info.latest_sha, supported_revision: policy.supportedRevision, supported_version: policy.supportedVersion,
+        unsupported: info.latest_sha !== policy.supportedRevision };
 }
-async function checkAgentRelease(path, git) {
-    const tags = await releaseTags(path, git);
-    const latest = tags[0];
-    if (!latest)
+function confirmAgent(info, policy) {
+    // Ordinary apply handles its non-mutating no-op; force still cleans files at the same revision.
+    if (!policy)
         return null;
-    const current = await currentReleaseTag(path, git);
-    let behind = releaseGap(tags, current, latest);
-    if (current === null) {
-        const ahead = await git(['tag', '--list', AGENT_TAG_GLOB, '--contains', 'HEAD'], path);
-        const count = ahead.ok ? ahead.out.split('\n').filter((l) => l.trim()).length : 0;
-        if (count > 0)
-            behind = count;
-    }
-    if (behind === 0 && (await headIsPastLatestTag(path, current, git)))
+    if (info.latest_sha === policy.supportedRevision)
+        return policy.confirmedRevision && policy.confirmedRevision !== info.latest_sha
+            ? { ok: false, message: 'The Agent update target changed. Check for updates and try again.' } : null;
+    if (policy.confirmedRevision === info.latest_sha)
         return null;
-    if (behind > 0 && (await headContainsRef(path, latest, git)))
-        return null;
-    if (behind > 0 && !(await canFastForwardTo(path, latest, git)))
-        return null;
-    const remote = normalizeRemoteUrl((await git(['remote', 'get-url', 'origin'], path)).out);
-    return { name: 'agent', behind, current_sha: current, latest_sha: latest, branch: latest, repo_url: remote, release_based: true, current_version: current, latest_version: latest, channel: DEFAULT_CHANNEL };
-}
-async function checkAgentBranch(path, git) {
-    const ref = await upstreamRef(path, git);
-    const count = await git(['rev-list', '--count', `HEAD..${ref}`], path);
-    const behind = count.ok && /^\d+$/.test(count.out) ? Number.parseInt(count.out, 10) : 0;
-    const mb = await git(['merge-base', 'HEAD', ref], path);
-    let current = null;
-    if (mb.ok && mb.out) {
-        const short = await git(['rev-parse', '--short', mb.out], path);
-        current = short.ok && short.out ? short.out : null;
-    }
-    const latest = (await git(['rev-parse', '--short', ref], path)).out;
-    const remote = normalizeRemoteUrl((await git(['remote', 'get-url', 'origin'], path)).out);
-    return { name: 'agent', behind, current_sha: current, latest_sha: latest, branch: ref, repo_url: remote, compare_url: compareUrl(remote, current, latest) };
+    return { ok: false, target: 'agent', agent_channel: info.channel, confirmation_required: true, ...agentWarning(info, policy),
+        message: 'This Agent version is not officially supported by Talaria and may cause issues.' };
 }
 async function isDirty(path, git) {
     const out = await git(['diff-index', '--quiet', 'HEAD', '--'], path, 1000);
     return !out.ok && (out.out === 'git exited with status 1' || !out.out || out.out.startsWith('git exited with status '));
 }
-/** Python `_check_repo` for the Agent checkout: fetch tags, prefer the release view, else the branch view. */
-export async function checkAgentUpdate(path, git) {
+/** Fetch and compare the independently selected Agent channel. */
+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';
-        const info = (await checkAgentRelease(path, git)) ?? { name: 'agent', behind: null };
-        return { ...info, error: message, stale_check: true, dirty: await isDirty(path, git) };
+        return { name: 'agent', channel, behind: null, error: message, stale_check: true, dirty: await isDirty(path, git) };
+    }
+    try {
+        return { ...await agentTarget(path, git, channel), dirty: await isDirty(path, git) };
+    }
+    catch (error) {
+        return { name: 'agent', channel, behind: null, error: error.message };
     }
-    const info = (await checkAgentRelease(path, git)) ?? { ...(await checkAgentBranch(path, git)), channel: DEFAULT_CHANNEL };
-    return { ...info, dirty: await isDirty(path, git) };
 }
-/** Python `_apply_update_inner` (agent branch): fetch, stash, `pull --ff-only`, pop. */
-export async function applyAgentUpdate(path, git) {
+/** Fetch, confirm the immutable Agent target, stash, fast-forward, and pop. */
+export async function applyAgentUpdate(path, git, channel = DEFAULT_CHANNEL, policy) {
     if (!path || !existsSync(join(path, '.git')))
         return { ok: false, message: 'Not a git repository' };
     const fetched = await git(['fetch', 'origin', '--quiet', '--tags', '--force'], path, 15_000);
@@ -694,7 +1029,26 @@ export async function applyAgentUpdate(path, git) {
             return { ok: false, message: `Fetch failed due to a repository lock: ${fetched.out.trim()}`, lock_conflict: true };
         return { ok: false, message: fetchFailureMessage(fetched.out, 'Could not reach the remote repository. Check your internet connection and try again.') };
     }
-    const ref = await selectAgentCompareRef(path, git);
+    let info;
+    try {
+        info = await agentTarget(path, git, channel);
+    }
+    catch (error) {
+        return { ok: false, message: error.message };
+    }
+    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);
+    if (warning)
+        return warning;
+    const ref = str(info.branch);
+    const revision = str(info.latest_sha);
     const status = await git(['status', '--porcelain', '--untracked-files=no'], path);
     if (!status.ok) {
         if (isGitLockError(status.out))
@@ -710,9 +1064,8 @@ export async function applyAgentUpdate(path, git) {
             return { ok: false, message: 'Failed to stash local changes' };
         stashed = true;
     }
-    const slash = ref.indexOf('/');
-    const pullArgs = slash > 0 ? ['pull', '--ff-only', ref.slice(0, slash), ref.slice(slash + 1)] : ['pull', '--ff-only', 'origin', ref];
-    const pulled = await git(pullArgs, path, 30_000);
+    // Merge the immutable commit that was checked/acknowledged, never re-fetch a moving ref here.
+    const pulled = await git(['merge', '--ff-only', revision], path, 30_000);
     if (!pulled.ok) {
         let note = '';
         if (stashed)
@@ -727,7 +1080,10 @@ export async function applyAgentUpdate(path, git) {
         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)
@@ -739,23 +1095,37 @@ async function restoreStash(path, git, pullOut) {
     return `Your local modifications could not be restored automatically (stash pop failed after pull error: ${pullOut.trim().slice(0, 200) || 'no detail'}). They remain safely in \`git stash list\`; run \`git -C ${path} stash pop\` once the lock is cleared.`;
 }
 /** Python `apply_force_update` (agent branch): fetch, refuse a pure-ancestor rewind, `checkout . && clean -fd && reset --hard`. */
-export async function forceAgentUpdate(path, git, log) {
+export async function forceAgentUpdate(path, git, log, channel = DEFAULT_CHANNEL, policy) {
     if (!path || !existsSync(join(path, '.git')))
         return { ok: false, message: 'Not a git repository' };
     const fetched = await git(['fetch', 'origin', '--quiet', '--tags', '--force'], path, 15_000);
     if (!fetched.ok)
         return { ok: false, message: fetchFailureMessage(fetched.out, 'Could not reach the remote repository. Check your connection.') };
-    const ref = await selectAgentCompareRef(path, git);
-    if ((await headContainsRef(path, ref, git)) && !(await canFastForwardTo(path, ref, git))) {
-        return { ok: false, message: `agent is already ahead of the stable channel (${ref}); refusing to rewind the checkout. Switching to a slower channel keeps your current version until that channel catches up.`, target: 'agent', channel: DEFAULT_CHANNEL, refused_rewind: true };
+    let info;
+    try {
+        info = await agentTarget(path, git, channel);
+    }
+    catch (error) {
+        return { ok: false, message: error.message };
+    }
+    const ref = str(info.branch);
+    const revision = str(info.latest_sha);
+    if ((await headContainsRef(path, revision, git)) && !(await canFastForwardTo(path, revision, git))) {
+        return { ok: false, message: `agent is already ahead of the ${channel} channel (${ref}); refusing to rewind the checkout. Switching to a slower channel keeps your current version until that channel catches up.`, target: 'agent', channel, refused_rewind: true };
     }
+    const warning = confirmAgent(info, policy);
+    if (warning)
+        return warning;
     await git(['checkout', '.'], path);
     const cleaned = await git(['clean', '-fd'], path);
     if (!cleaned.ok)
         log(`[updates] force update: git clean -fd failed (continuing to reset --hard): ${cleaned.out}`);
-    if (!(await git(['reset', '--hard', ref], path)).ok)
+    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) {
@@ -907,9 +1277,16 @@ function summaryPrompt(details) {
 }
 export class UpdateService {
     deps;
-    cache = { webui: null, agent: null, checked_at: 0, include_agent: true, channel: DEFAULT_CHANNEL };
+    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;
+    lifecycle = 0;
+    autoRunning = false;
+    autoRestartScheduled = false;
     summaries = new Map();
     git;
     now;
@@ -920,13 +1297,24 @@ export class UpdateService {
         this.now = deps.now ?? (() => Date.now() / 1000);
         this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     }
+    agentChannel() { return this.deps.agentChannel?.() ?? DEFAULT_CHANNEL; }
+    agentPolicy(confirmedRevision) {
+        const supported = dict(this.deps.identity.release().compatibleAgent);
+        return { supportedRevision: str(supported.sourceRevision), supportedVersion: str(supported.version), ...(confirmedRevision ? { confirmedRevision } : {}) };
+    }
     /** Python `cached_update_status`: no network, no git mutations. */
-    cachedStatus(includeAgent = this.deps.includeAgent(), channel = this.deps.channel()) {
+    cachedStatus(includeAgent = this.deps.includeAgent(), channel = this.deps.channel(), agentChannel = this.agentChannel()) {
         const cached = { ...this.cache };
         if (cached.channel !== channel) {
             cached.channel = channel;
+            cached.webui = null;
             cached.stale_channel = true;
         }
+        if (cached.agent_channel !== agentChannel) {
+            cached.agent_channel = agentChannel;
+            cached.agent = null;
+            cached.stale_agent_channel = true;
+        }
         if (cached.include_agent !== includeAgent) {
             cached.include_agent = includeAgent;
             if (!includeAgent)
@@ -935,27 +1323,129 @@ export class UpdateService {
         cached.cached = true;
         return cached;
     }
-    /** Python `check_for_updates`: 30 min cache keyed on channel + include_agent; one in-flight check per key. */
-    async check(force = false, includeAgent = this.deps.includeAgent(), channel = this.deps.channel()) {
-        const matches = this.cache.include_agent === includeAgent && this.cache.channel === channel;
+    /** 30 min cache keyed on both channels + include_agent; one in-flight check per key. */
+    async check(force = false, includeAgent = this.deps.includeAgent(), channel = this.deps.channel(), agentChannel = this.agentChannel()) {
+        const key = `${channel}:${agentChannel}:${String(includeAgent)}`;
+        if (this.checking) {
+            if (this.checkingKey === key)
+                return this.checking;
+            await this.checking;
+            return this.check(force, includeAgent, channel, agentChannel);
+        }
+        if (this.applying)
+            return this.cachedStatus(includeAgent, channel, agentChannel);
+        const matches = this.cache.include_agent === includeAgent && this.cache.channel === channel && this.cache.agent_channel === agentChannel;
         if (!force && matches && this.now() - Number(this.cache.checked_at) < CACHE_TTL_S)
             return { ...this.cache };
-        if (this.checking && matches)
-            return this.checking;
+        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);
-                // The channel is a Web concept; the Agent always follows its own stable tags.
-                const agent = includeAgent ? await checkAgentUpdate(this.deps.agentDir(), this.git) : ignoredAgent();
-                Object.assign(this.cache, { webui, agent, checked_at: this.now(), include_agent: includeAgent, channel });
+                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 });
                 return { ...this.cache };
             }
             finally {
                 this.checking = null;
+                this.checkingKey = null;
             }
         })();
         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;
+        this.autoStarted = true;
+        const lifecycle = this.lifecycle;
+        const schedule = (delay) => {
+            this.autoTimer = setTimeout(() => {
+                this.autoTimer = null;
+                void this.autoApplyOnce().finally(() => { if (this.autoStarted && lifecycle === this.lifecycle && !this.autoRestartScheduled)
+                    schedule(intervalMs); });
+            }, delay);
+            this.autoTimer.unref();
+        };
+        schedule(0);
+    }
+    stopAutoApply() {
+        this.autoStarted = false;
+        this.lifecycle += 1;
+        if (this.autoTimer)
+            clearTimeout(this.autoTimer);
+        this.autoTimer = null;
+    }
+    /** 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();
+            const checked = await this.check(true, this.deps.includeAgent(), channel);
+            const web = dict(checked.webui);
+            if (!stillEnabled())
+                return web;
+            if (web.error || web.manual_update) {
+                this.deps.log(`[updates] automatic Web update unavailable: ${str(web.error || web.message)}`);
+                return web;
+            }
+            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 };
+        }
+        finally {
+            this.autoRunning = false;
+        }
+    }
     blockedResponse(target) {
         const b = this.deps.blockers();
         if (!b.restart_blocked)
@@ -965,7 +1455,11 @@ export class UpdateService {
             parts.push(`${String(b.active_streams)} active chat stream${b.active_streams === 1 ? '' : 's'}`);
         if (b.active_runs)
             parts.push(`${String(b.active_runs)} active agent run${b.active_runs === 1 ? '' : 's'}`);
-        return { ok: false, message: `Cannot update ${target} while ${parts.join(' and ') || 'active chat work'} is running. Wait for the response to finish, then retry the update.`, target, restart_blocked: true, active_streams: b.active_streams, active_runs: b.active_runs, blocking_stream_ids: b.blocking_stream_ids, blocking_run_ids: b.blocking_run_ids };
+        if (b.active_terminals)
+            parts.push(`${String(b.active_terminals)} open terminal${b.active_terminals === 1 ? '' : 's'}`);
+        if (b.active_cron_jobs)
+            parts.push(`${String(b.active_cron_jobs)} active cron job${b.active_cron_jobs === 1 ? '' : 's'}`);
+        return { ok: false, message: `Cannot update ${target} while ${parts.join(' and ') || 'active work'} is running. Wait for work to finish and close open terminals, then retry the update.`, target, ...b };
     }
     async locked(fn) {
         if (this.applying)
@@ -979,17 +1473,29 @@ export class UpdateService {
         }
     }
     /** Python `apply_update`. */
-    apply(target, channel) {
+    async apply(target, channel, canApply = () => true, agentOptions = {}) {
+        if (this.checking)
+            await this.checking;
+        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);
         if (blocked)
-            return Promise.resolve(blocked);
-        return this.locked(() => this.applyInner(target, channel ?? this.deps.channel()));
+            return blocked;
+        const lifecycle = this.lifecycle;
+        return this.locked(() => this.applyInner(target, channel ?? this.deps.channel(), () => lifecycle === this.lifecycle && canApply(), agentOptions));
     }
-    async applyInner(target, channel) {
+    async applyInner(target, channel, canApply = () => true, agentOptions = {}) {
         if (target === 'webui') {
-            const result = await applyWebUpdate(this.deps.webRoot, channel, this.git, this.deps.getJson, this.deps.identity, this.deps.build ?? runNpm);
-            if (result.ok && !result.up_to_date) {
+            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, { 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;
+                this.autoRestartScheduled = true;
+                this.stopAutoApply();
                 this.deps.scheduleRestart();
                 result.restart_scheduled = true;
             }
@@ -997,8 +1503,8 @@ export class UpdateService {
         }
         if (target !== 'agent')
             return { ok: false, message: `Unknown target: ${target}` };
-        const result = await applyAgentUpdate(this.deps.agentDir(), this.git);
-        if (!result.ok)
+        const result = await applyAgentUpdate(this.deps.agentDir(), this.git, agentOptions.agentChannel ?? this.agentChannel(), this.agentPolicy(agentOptions.confirmedRevision));
+        if (!result.ok || result.up_to_date)
             return result;
         return this.finishAgent(result);
     }
@@ -1035,23 +1541,31 @@ export class UpdateService {
         return [false, { ...annotated, message: `${str(first.message) || 'Restart failed'}; recovery retry did not complete: ${str(retry.message) || 'retry did not complete'}` }];
     }
     /** Python `apply_force_update`: Web keeps its clean-only policy; the Agent resets hard. */
-    force(target, channel) {
+    async force(target, channel, agentOptions = {}) {
+        if (this.checking)
+            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);
         return this.locked(async () => {
             if (target !== 'agent')
                 return { ok: false, message: `Unknown target: ${target}` };
-            const result = await forceAgentUpdate(this.deps.agentDir(), this.git, this.deps.log);
+            const result = await forceAgentUpdate(this.deps.agentDir(), this.git, this.deps.log, agentOptions.agentChannel ?? this.agentChannel(), this.agentPolicy(agentOptions.confirmedRevision));
             return result.ok ? this.finishAgent(result) : result;
         });
     }
     /** Python `apply_clear_lock`: never removes a lock; Web retries the clean path, the Agent gets the manual command. */
-    clearLock(target) {
+    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);
@@ -1065,7 +1579,7 @@ export class UpdateService {
             const manual = `rm -f ${str(inv.well_known_lock_path)}`;
             if (!inv.well_known_lock_present) {
                 this.cache.checked_at = 0;
-                const retry = await this.applyInner(target, this.deps.channel());
+                const retry = await this.applyInner(target, this.deps.channel(), () => true, agentOptions);
                 return { ...retry, lock_recovery: { action: 'no-lock-found', manual_command: manual, other_locks: inv.other_locks } };
             }
             return { ok: false, message: `A git lock file (.git/index.lock) is present. The server does not delete locks automatically -- git uses O_CREAT|O_EXCL locking, which cannot be detected with advisory probes. To recover: confirm no other git process is running against this checkout, then run: ${manual}  Click "Retry update" once you have removed it.`, lock_held: true, target, manual_command: manual, well_known_lock_path: inv.well_known_lock_path, other_locks: inv.other_locks };