@maudecode/talaria-web 0.0.0 → 1.11.0

package/dist/tools/updates.js

@@ -3,17 +3,19 @@
  *
  * 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; 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 { existsSync, lstatSync, 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 +26,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 +66,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 +87,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');
@@ -227,6 +234,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 +255,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}`,
@@ -283,6 +294,48 @@ 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))
+        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;
+    }
+}
 /** 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 = {};
@@ -401,8 +454,9 @@ 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) {
     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);
@@ -417,6 +471,18 @@ export async function checkWebUpdate(webRoot, currentVersion, channel, git, getJ
     }
     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 && !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 +536,86 @@ export async function checkWebUpdate(webRoot, currentVersion, channel, git, getJ
         Object.assign(result, { manual_update: true, message: 'Commit or remove local changes before updating; Web updates never discard them.' });
     return result;
 }
+async function applyNpmWebUpdate(webRoot, channel, getJson, id, npmRun, canApply) {
+    if (channel !== 'stable')
+        return { ok: false, manual_update: true, message: 'Packaged Experimental updates require manual artifact replacement.' };
+    if (str(id.release().tag).startsWith('web-exp-v'))
+        return { ok: false, manual_update: true, message: 'Switch packaged update channels manually before enabling Stable updates.' };
+    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);
+    }
+    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.' };
+    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}.` };
+    }
+    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;
+    try {
+        const update = await npmRun(['install', '--global', '--prefix', staging, '--no-audit', '--no-fund', release.npm], 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)
+            || !['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.' };
+        }
+        const current = await npmInstallInfo(webRoot, npmRun);
+        if (!canApply() || current?.packageRoot !== installed.packageRoot || current.version !== installed.version)
+            return { ok: false, message: 'The npm installation or update settings changed; retry the update.' };
+        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: release.sourceRevision, npm: release.npm, message: `Updated Talaria Web to npm release ${release.version}.` };
+}
 /** 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) {
     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);
     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 +693,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 +730,85 @@ 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;
-}
 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)
-        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)))
+function confirmAgent(info, policy) {
+    // Ordinary apply handles its non-mutating no-op; force still cleans files at the same revision.
+    if (!policy)
         return null;
-    if (behind > 0 && (await headContainsRef(path, latest, 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 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);
     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 +817,22 @@ 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)
+        return { ok: true, up_to_date: true, target: 'agent', message: 'Agent is up to date.' };
+    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 +848,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)
@@ -739,21 +876,32 @@ 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 };
 }
@@ -907,9 +1055,15 @@ 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;
     applying = false;
+    autoTimer = null;
+    autoStarted = false;
+    lifecycle = 0;
+    autoRunning = false;
+    autoRestartScheduled = false;
     summaries = new Map();
     git;
     now;
@@ -920,13 +1074,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 +1100,93 @@ 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 = 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();
+                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;
     }
+    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; }
+    async autoApplyOnce() {
+        if (this.autoRunning || this.applying || this.autoRestartScheduled || !(this.deps.checkEnabled?.() ?? this.deps.autoApply?.()))
+            return null;
+        this.autoRunning = true;
+        const lifecycle = this.lifecycle;
+        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;
+            const result = await this.apply('webui', channel, stillEnabled);
+            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) {
+            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 +1196,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 +1214,28 @@ export class UpdateService {
         }
     }
     /** Python `apply_update`. */
-    apply(target, channel) {
+    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.' };
+        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);
+            // 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 +1243,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,7 +1281,9 @@ 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 blocked = this.blockedResponse(target);
@@ -1044,12 +1292,12 @@ export class UpdateService {
         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 blocked = this.blockedResponse(target);
@@ -1065,7 +1313,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 };