@wpelevator/tug 0.2.0 → 0.3.0

package/dist/agent.js

@@ -7,13 +7,18 @@ import { validateImageArchive, verifyDownload } from "./artifacts.js";
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import net from 'node:net';
-import { composeForNode, dumpYaml, isRolling, serviceSecretVersions } from "./compose.js";
-import { activeRollingStates, composeBase, hasLegacyContainers, reconcileRolling, retireAll } from "./rollout.js";
-import { ensureDir, errMessage, now, parseDuration } from "./util.js";
+import dns from 'node:dns/promises';
+import { WebSocket } from 'ws';
+import { createHash } from 'node:crypto';
+import { addressBoundServices, composeForNode, dumpYaml, isRolling, serviceSecretVersions, } from "./compose.js";
+import { LIVE_MAX_FRAME_BYTES, LIVE_START_TIMEOUT_MS } from "./protocol.js";
+import { LiveOperationEngine } from "./live.js";
+import { loadRolloutState, activeRollingStates, composeBase, hasLegacyContainers, reconcileRolling, retireAll, } from "./rollout.js";
+import { ensureDir, errMessage, isPublicAddress, now, parseDuration } from "./util.js";
 import { openAgentDb } from "./db.js";
 import { createDockerRunner, createHostRunner } from "./runners.js";
 import { CADDY_CONTAINER, reconcileIngress, removeIngress } from "./ingress.js";
-import { WG_INTERFACE, ensureWgKeys, readReportedKey, reconcileMesh, rotateWgKeys, writeReportedKey } from "./mesh.js";
+import { WG_INTERFACE, ensureWgKeys, readReportedKey, reconcileMesh, rotateWgKeys, writeReportedKey, } from "./mesh.js";
 const CONTROL_URL_FROM_ENV = Boolean(process.env.TUG_CONTROL_URL);
 let CONTROL_URL = process.env.TUG_CONTROL_URL || 'http://localhost:8080';
 let TOKEN = process.env.TUG_AGENT_TOKEN;
@@ -24,7 +29,19 @@ const INTERVAL = Number(process.env.TUG_POLL_INTERVAL_MS || 5000);
 // Opt-in WireGuard mesh: needs `wg`/`ip` in the agent image, host networking and NET_ADMIN.
 const MESH = process.env.TUG_MESH === 'true';
 export function defaultContext() {
-    return { docker: createDockerRunner(), http: fetch, nodeName: NODE_NAME, stateDir: STATE_DIR, apply: APPLY, controlUrl: CONTROL_URL, token: TOKEN, host: createHostRunner(), mesh: MESH, caddyImage: process.env.TUG_CADDY_IMAGE, rolloutPorts: process.env.TUG_ROLLOUT_PORTS };
+    return {
+        docker: createDockerRunner(),
+        http: fetch,
+        nodeName: NODE_NAME,
+        stateDir: STATE_DIR,
+        apply: APPLY,
+        controlUrl: CONTROL_URL,
+        token: TOKEN,
+        host: createHostRunner(),
+        mesh: MESH,
+        caddyImage: process.env.TUG_CADDY_IMAGE,
+        rolloutPorts: process.env.TUG_ROLLOUT_PORTS,
+    };
 }
 const dbsByStateDir = new Map();
 async function agentDb(stateDir) {
@@ -36,22 +53,417 @@ async function agentDb(stateDir) {
     }
     return db;
 }
-function authHeaders(ctx) { if (!ctx.token)
-    throw new Error('TUG_AGENT_TOKEN required'); return { Authorization: `Bearer ${ctx.token}` }; }
+function authHeaders(ctx) {
+    if (!ctx.token)
+        throw new Error('TUG_AGENT_TOKEN required');
+    return { Authorization: `Bearer ${ctx.token}` };
+}
 async function api(ctx, route, opts = {}) {
-    const res = await ctx.http(`${ctx.controlUrl}${route}`, { ...opts, headers: { ...authHeaders(ctx), ...(opts.headers || {}) } });
+    const res = await ctx.http(`${ctx.controlUrl}${route}`, {
+        ...opts,
+        headers: {
+            ...authHeaders(ctx),
+            ...(opts.headers || {}),
+        },
+    });
     if (!res.ok)
         throw new Error(`${opts.method || 'GET'} ${route}: ${res.status} ${await res.text()}`);
     return res.json();
 }
+/** Keeps one outbound stream open and falls back to a bounded HTTP wait when an intermediary rejects WebSockets. */
+export class AgentWakeChannel {
+    ctx;
+    createSocket;
+    socket;
+    cursor = 0;
+    pending = false;
+    waiter;
+    handlers;
+    constructor(ctx, createSocket = (url, token) => new WebSocket(url, {
+        headers: { Authorization: `Bearer ${token}` },
+        maxPayload: LIVE_MAX_FRAME_BYTES,
+    }), handlers = {}) {
+        this.ctx = ctx;
+        this.createSocket = createSocket;
+        this.handlers = handlers;
+    }
+    notify() {
+        this.pending = true;
+        this.waiter?.();
+    }
+    async connect() {
+        if (this.socket?.readyState === WebSocket.OPEN)
+            return true;
+        if (!this.ctx.token)
+            throw new Error('TUG_AGENT_TOKEN required');
+        const url = new URL('/agent/v1/stream', this.ctx.controlUrl);
+        url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+        return new Promise((resolve) => {
+            let settled = false;
+            const socket = this.createSocket(url.toString(), this.ctx.token);
+            this.socket = socket;
+            const finish = (connected) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(connected);
+            };
+            const timer = setTimeout(() => {
+                socket.terminate();
+                finish(false);
+            }, 1500);
+            socket.on('open', () => finish(true));
+            socket.on('message', (data) => {
+                if (this.socket !== socket)
+                    return;
+                let message;
+                const json = data.toString();
+                if (Buffer.byteLength(json) > LIVE_MAX_FRAME_BYTES) {
+                    this.close();
+                    return;
+                }
+                try {
+                    message = JSON.parse(json);
+                }
+                catch {
+                    return;
+                }
+                if (!message || typeof message !== 'object')
+                    return;
+                const frame = message;
+                if (typeof frame.type === 'string' && frame.type.startsWith('live.')) {
+                    if (frame.v === 1)
+                        void Promise.resolve(this.handlers.onLive?.(message)).catch((error) => console.error('agent live frame failed:', errMessage(error)));
+                    return;
+                }
+                if ((frame.type !== 'ready' && frame.type !== 'work-available') ||
+                    !Number.isSafeInteger(frame.cursor) ||
+                    Number(frame.cursor) < 0)
+                    return;
+                this.cursor = Math.max(this.cursor, Number(frame.cursor));
+                if (frame.type === 'work-available')
+                    this.notify();
+            });
+            socket.on('close', () => {
+                if (this.socket === socket) {
+                    this.socket = undefined;
+                    this.handlers.onDisconnect?.();
+                }
+                if (settled)
+                    this.waiter?.();
+                else
+                    finish(false);
+            });
+            socket.on('error', () => {
+                if (this.socket === socket) {
+                    this.socket = undefined;
+                    this.handlers.onDisconnect?.();
+                }
+                socket.terminate();
+                this.waiter?.();
+                finish(false);
+            });
+        });
+    }
+    async waitOnSocket(timeoutMs) {
+        if (this.pending) {
+            this.pending = false;
+            return;
+        }
+        await new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                if (this.waiter === done)
+                    this.waiter = undefined;
+                resolve();
+            };
+            this.waiter = done;
+            const timer = setTimeout(done, timeoutMs);
+        });
+        this.pending = false;
+    }
+    async longPoll(timeoutMs) {
+        const wake = await api(this.ctx, `/agent/v1/wake?after=${this.cursor}&timeout=${Math.min(timeoutMs, 30_000)}`);
+        this.cursor = Math.max(this.cursor, wake.cursor);
+    }
+    async wait(timeoutMs) {
+        if (await this.connect())
+            return this.waitOnSocket(timeoutMs);
+        await this.longPoll(timeoutMs);
+    }
+    send(frame) {
+        const socket = this.socket;
+        if (!socket || socket.readyState !== WebSocket.OPEN)
+            return false;
+        if (socket.bufferedAmount > 1048576) {
+            this.close();
+            socket.terminate();
+            return false;
+        }
+        try {
+            socket.send(JSON.stringify(frame));
+            return true;
+        }
+        catch {
+            this.close();
+            return false;
+        }
+    }
+    close() {
+        const socket = this.socket;
+        this.socket = undefined;
+        this.handlers.onDisconnect?.();
+        socket?.close();
+        this.waiter?.();
+    }
+}
+/** Resolves a service once before starting a process so rollouts cannot silently retarget an open session. */
+export async function resolveLiveContainer(ctx, request) {
+    const name = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/;
+    if (!name.test(request.project) ||
+        request.project === '..' ||
+        !request.service ||
+        !name.test(request.service))
+        throw new Error('A valid project and service are required');
+    const state = await loadRolloutState(path.join(ctx.stateDir, 'projects', request.project));
+    const rolling = state.services[request.service];
+    if (rolling && !rolling.active)
+        throw new Error('Rolling service has no active revision');
+    const project = rolling?.active?.project ?? request.project;
+    if (!name.test(project))
+        throw new Error('Invalid active rollout project');
+    const result = await ctx.docker([
+        'ps',
+        '--all',
+        '--no-trunc',
+        '--quiet',
+        '--filter',
+        'label=com.docker.compose.project=' + project,
+        '--filter',
+        'label=com.docker.compose.service=' + request.service,
+        '--filter',
+        'label=com.docker.compose.oneoff=False',
+    ]);
+    const ids = result.out.trim().split(/\s+/).filter(Boolean);
+    if (ids.length !== 1)
+        throw new Error(ids.length
+            ? 'Service has multiple containers; select an unambiguous service'
+            : 'Service has no container on this node');
+    if (!/^[a-f0-9]{12,64}$/.test(ids[0]))
+        throw new Error('Docker returned an invalid container ID');
+    return ids[0];
+}
+export class AgentLiveOperations {
+    ctx;
+    emit;
+    engine;
+    sessions = new Map();
+    constructor(ctx, emit, options = {}) {
+        this.ctx = ctx;
+        this.emit = emit;
+        this.engine = new LiveOperationEngine({
+            ...options,
+            emit: (event) => {
+                if (!this.sessions.has(event.sessionId))
+                    return;
+                if (event.type === 'exit')
+                    this.sessions.delete(event.sessionId);
+                if (event.type === 'output')
+                    this.emit({
+                        v: 1,
+                        type: 'live.output',
+                        sessionId: event.sessionId,
+                        stream: event.stream,
+                        data: event.data,
+                    });
+                else if (event.type === 'result')
+                    this.emit({
+                        v: 1,
+                        type: 'live.result',
+                        sessionId: event.sessionId,
+                        result: event.result,
+                    });
+                else
+                    this.emit({ ...event, v: 1, type: 'live.exit' });
+            },
+        });
+    }
+    async handle(frame) {
+        if (frame.v !== 1 ||
+            typeof frame.sessionId !== 'string' ||
+            !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,255}$/.test(frame.sessionId))
+            return;
+        if (frame.type === 'live.open') {
+            // An existing open belongs to its original request; replaying it must not start another process.
+            if (this.sessions.has(frame.sessionId))
+                return;
+            const entry = { ready: Promise.resolve(), queuedBytes: 0 };
+            this.sessions.set(frame.sessionId, entry);
+            entry.ready = this.open({ ...frame.request, sessionId: frame.sessionId }, entry);
+            await entry.ready;
+            return;
+        }
+        const entry = this.sessions.get(frame.sessionId);
+        if (!entry)
+            return;
+        if (frame.type === 'live.cancel') {
+            this.engine.cancel(frame.sessionId);
+            if (this.sessions.delete(frame.sessionId))
+                this.emit({
+                    v: 1,
+                    type: 'live.exit',
+                    sessionId: frame.sessionId,
+                    code: null,
+                    signal: null,
+                    cancelled: true,
+                });
+            return;
+        }
+        let queued = 0;
+        try {
+            let input;
+            if (frame.type === 'live.stdin') {
+                if (typeof frame.data !== 'string' || frame.data.length > 87384)
+                    throw new Error('Invalid stdin frame');
+                input = Buffer.from(frame.data, 'base64');
+                if (input.toString('base64') !== frame.data || input.length > 65536)
+                    throw new Error('Invalid base64 stdin');
+                queued = input.length;
+                entry.queuedBytes += queued;
+                if (entry.queuedBytes > 262144)
+                    throw new Error('Live stdin queue exceeds size limit');
+            }
+            await entry.ready;
+            if (this.sessions.get(frame.sessionId) !== entry)
+                return;
+            if (frame.type === 'live.stdin' && input)
+                this.engine.stdin(frame.sessionId, input);
+            else if (frame.type === 'live.stdin-end')
+                this.engine.endStdin(frame.sessionId);
+            else if (frame.type === 'live.resize')
+                this.engine.resize(frame.sessionId, frame.columns, frame.rows);
+        }
+        catch (error) {
+            this.fail(frame.sessionId, entry, error);
+        }
+        finally {
+            entry.queuedBytes -= queued;
+        }
+    }
+    dispose() {
+        const ids = [...this.sessions.keys()];
+        this.engine.dispose();
+        for (const id of ids)
+            if (this.sessions.delete(id))
+                this.emit({
+                    v: 1,
+                    type: 'live.exit',
+                    sessionId: id,
+                    code: null,
+                    signal: null,
+                    cancelled: true,
+                });
+    }
+    fail(id, entry, error) {
+        if (this.sessions.get(id) !== entry)
+            return;
+        this.sessions.delete(id);
+        this.emit({
+            v: 1,
+            type: 'live.exit',
+            sessionId: id,
+            code: null,
+            signal: null,
+            cancelled: false,
+            error: errMessage(error),
+        });
+        this.engine.cancel(id);
+    }
+    async open(request, entry) {
+        try {
+            if (this.sessions.size > 16)
+                throw new Error('Live session limit reached');
+            if (!this.ctx.apply)
+                throw new Error('Live operations require an applying agent');
+            if (request.node && request.node !== this.ctx.nodeName)
+                throw new Error('Live request selected a different node');
+            if (typeof request.project !== 'string' ||
+                !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.test(request.project))
+                throw new Error('Invalid project');
+            if (request.operation === 'ps') {
+                const rollout = await loadRolloutState(path.join(this.ctx.stateDir, 'projects', request.project));
+                if (this.sessions.get(request.sessionId) !== entry)
+                    return;
+                const projects = [
+                    ...new Set([
+                        request.project,
+                        ...Object.values(rollout.services).flatMap((service) => service.active ? [service.active.project] : []),
+                    ]),
+                ];
+                this.engine.start({ operation: 'ps', sessionId: request.sessionId, projects });
+            }
+            else {
+                if (!['exec', 'logs', 'inspect'].includes(request.operation))
+                    throw new Error('Invalid live operation');
+                let timer;
+                let container;
+                try {
+                    container = await Promise.race([
+                        resolveLiveContainer(this.ctx, request),
+                        new Promise((_resolve, reject) => {
+                            timer = setTimeout(() => reject(new Error('Live container resolution timed out')), LIVE_START_TIMEOUT_MS);
+                            timer.unref();
+                        }),
+                    ]);
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+                if (this.sessions.get(request.sessionId) !== entry)
+                    return;
+                if (request.operation === 'exec')
+                    this.engine.start({
+                        operation: 'exec',
+                        sessionId: request.sessionId,
+                        container,
+                        command: request.command,
+                        interactive: request.interactive,
+                        tty: request.tty,
+                        columns: request.columns,
+                        rows: request.rows,
+                    });
+                else if (request.operation === 'logs')
+                    this.engine.start({
+                        operation: 'logs',
+                        sessionId: request.sessionId,
+                        container,
+                        tail: request.tail,
+                    });
+                else
+                    this.engine.start({ operation: 'inspect', sessionId: request.sessionId, container });
+            }
+            if (this.sessions.get(request.sessionId) === entry)
+                this.emit({ v: 1, type: 'live.started', sessionId: request.sessionId });
+        }
+        catch (error) {
+            this.fail(request.sessionId, entry, error);
+        }
+    }
+}
 async function writeEnv(file, secrets) {
-    const body = Object.entries(secrets).map(([k, v]) => `${k}=${String(v).replace(/\n/g, '\\n')}`).join('\n') + '\n';
+    const body = Object.entries(secrets)
+        .map(([k, v]) => `${k}=${String(v).replace(/\n/g, '\\n')}`)
+        .join('\n') + '\n';
     await fs.writeFile(file, body, { mode: 0o600 });
 }
 /** `docker compose` prefix for a project; rolling revision projects pass their own Compose file. */
 const composeCmd = (project, cwd, composeFile) => composeFile ? composeBase(project, cwd, composeFile) : ['compose', '-p', project];
 export async function containerIp(ctx, project, service, cwd, composeFile) {
-    const ids = (await ctx.docker([...composeCmd(project, cwd, composeFile), 'ps', '-q', service], { cwd })).out.trim().split(/\s+/).filter(Boolean);
+    const ids = (await ctx.docker([...composeCmd(project, cwd, composeFile), 'ps', '-q', service], { cwd })).out
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
     if (!ids.length)
         throw new Error(`${service}: no container found`);
     const inspected = JSON.parse((await ctx.docker(['inspect', ids[0]], { cwd })).out)[0];
@@ -60,8 +472,14 @@ export async function containerIp(ctx, project, service, cwd, composeFile) {
 }
 function tcpCheck(host, port, timeoutMs = 2000) {
     return new Promise((resolve, reject) => {
-        const s = net.createConnection({ host, port: Number(port), timeout: timeoutMs }, () => { s.destroy(); resolve(true); });
-        s.on('timeout', () => { s.destroy(); reject(new Error(`tcp timeout ${host}:${port}`)); });
+        const s = net.createConnection({ host, port: Number(port), timeout: timeoutMs }, () => {
+            s.destroy();
+            resolve(true);
+        });
+        s.on('timeout', () => {
+            s.destroy();
+            reject(new Error(`tcp timeout ${host}:${port}`));
+        });
         s.on('error', reject);
     });
 }
@@ -74,7 +492,9 @@ export async function waitForHealth(ctx, project, service, health, cwd, composeF
     for (let i = 0; i < retries; i++) {
         try {
             if (health.type === 'docker') {
-                const id = (await ctx.docker([...composeCmd(project, cwd, composeFile), 'ps', '-q', service], { cwd })).out.trim().split(/\s+/)[0];
+                const id = (await ctx.docker([...composeCmd(project, cwd, composeFile), 'ps', '-q', service], { cwd })).out
+                    .trim()
+                    .split(/\s+/)[0];
                 const state = JSON.parse((await ctx.docker(['inspect', id], { cwd })).out)[0]?.State;
                 if (!state?.Running)
                     throw new Error(`${service}: not running`);
@@ -86,7 +506,9 @@ export async function waitForHealth(ctx, project, service, health, cwd, composeF
             }
             else if (health.type === 'http') {
                 const ip = await containerIp(ctx, project, service, cwd, composeFile);
-                const res = await ctx.http(`http://${ip}:${health.port || 80}${health.path || '/'}`, { signal: AbortSignal.timeout(parseDuration(health.timeout || '2s')) });
+                const res = await ctx.http(`http://${ip}:${health.port || 80}${health.path || '/'}`, {
+                    signal: AbortSignal.timeout(parseDuration(health.timeout || '2s')),
+                });
                 if (!res.ok)
                     throw new Error(`${service}: http ${res.status}`);
             }
@@ -94,7 +516,7 @@ export async function waitForHealth(ctx, project, service, health, cwd, composeF
         }
         catch (e) {
             last = e;
-            await new Promise(r => setTimeout(r, intervalMs));
+            await new Promise((r) => setTimeout(r, intervalMs));
         }
     }
     throw new Error(`${service}: ${describeHealthCheck(health)} failed after ${retries} attempt${retries === 1 ? '' : 's'}: ${describeError(last)}`);
@@ -113,18 +535,74 @@ function describeHealthCheck(health) {
     return 'docker health check';
 }
 export { parseDuration };
+/**
+ * Containers of Tug projects (`projects`, plus their rolling revision projects `<project>-…`) that
+ * listen on all interfaces or on a public IP, from `docker ps --format '{{.Label "com.docker.compose.project"}}\t{{.Names}}\t{{.Ports}}'`.
+ */
+export function publicListeners(psOutput, projects) {
+    const out = [];
+    for (const line of psOutput.split('\n')) {
+        const [project, container, ports = ''] = line.split('\t');
+        if (!project || !projects.some((p) => project === p || project.startsWith(`${p}-`)))
+            continue;
+        for (const m of ports.matchAll(/(\[[0-9a-fA-F:.]+\]|[0-9a-fA-F:.]+):(\d+(?:-\d+)?)->(\S+?)(?:,|$)/g)) {
+            if (isPublicAddress(m[1]))
+                out.push({ project, container, listen: `${m[1]}:${m[2]}->${m[3]}` });
+        }
+    }
+    return out;
+}
+/** `ports.public` diagnostic: a warning, not a failure, since an operator may publish on purpose with an explicit host IP. */
+async function publicPortsCheck(ctx) {
+    try {
+        const projects = await fs
+            .readdir(path.join(ctx.stateDir, 'projects'))
+            .catch(() => []);
+        const ps = await ctx.docker([
+            'ps',
+            '--filter',
+            'label=com.docker.compose.project',
+            '--format',
+            '{{.Label "com.docker.compose.project"}}\t{{.Names}}\t{{.Ports}}',
+        ]);
+        const listeners = publicListeners(ps.out, projects);
+        const stdout = listeners.map((l) => `${l.project}\t${l.container}\t${l.listen}`).join('\n');
+        return listeners.length
+            ? {
+                name: 'ports.public',
+                ok: true,
+                stdout: stdout.slice(-4000),
+                warning: `${listeners.length} published port${listeners.length === 1 ? ' of Tug projects listens' : 's of Tug projects listen'} on a public address; bind them to 127.0.0.1, the overlay IP or a private address unless that is intended`,
+            }
+            : {
+                name: 'ports.public',
+                ok: true,
+                stdout: 'no Tug project container listens on a public address',
+            };
+    }
+    catch (e) {
+        return { name: 'ports.public', ok: false, error: errMessage(e).slice(-4000) };
+    }
+}
 export async function executeCommand(command, ctx = defaultContext()) {
-    const payload = typeof command.payload_json === 'string' ? JSON.parse(command.payload_json || '{}') : command.payload || {};
+    const payload = typeof command.payload_json === 'string'
+        ? JSON.parse(command.payload_json || '{}')
+        : command.payload || {};
     if (command.type === 'diagnostics.run') {
         const checks = [];
         for (const [name, args] of [
             ['docker.info', ['info']],
             ['docker.version', ['version']],
-            ['docker.compose.version', ['compose', 'version']]
+            ['docker.compose.version', ['compose', 'version']],
         ]) {
             try {
                 const result = await ctx.docker([...args]);
-                checks.push({ name, ok: true, stdout: result.out.slice(-4000), stderr: result.err.slice(-4000) });
+                checks.push({
+                    name,
+                    ok: true,
+                    stdout: result.out.slice(-4000),
+                    stderr: result.err.slice(-4000),
+                });
             }
             catch (e) {
                 checks.push({ name, ok: false, error: errMessage(e).slice(-4000) });
@@ -136,25 +614,42 @@ export async function executeCommand(command, ctx = defaultContext()) {
             extra.push(['wireguard.version', () => host('wg', ['--version'])], ['wireguard.interface', () => host('wg', ['show', WG_INTERFACE])]);
         }
         if (await fs.stat(path.join(ctx.stateDir, 'ingress')).then(() => true, () => false)) {
-            extra.push(['ingress.caddy', () => ctx.docker(['container', 'inspect', '-f', '{{.State.Status}}', CADDY_CONTAINER])]);
+            extra.push([
+                'ingress.caddy',
+                () => ctx.docker(['container', 'inspect', '-f', '{{.State.Status}}', CADDY_CONTAINER]),
+            ]);
         }
         for (const [name, fn] of extra) {
             try {
                 const result = await fn();
-                checks.push({ name, ok: true, stdout: result.out.slice(-4000), stderr: result.err.slice(-4000) });
+                checks.push({
+                    name,
+                    ok: true,
+                    stdout: result.out.slice(-4000),
+                    stderr: result.err.slice(-4000),
+                });
             }
             catch (e) {
                 checks.push({ name, ok: false, error: errMessage(e).slice(-4000) });
             }
         }
-        return { commandId: command.id, state: checks.every(c => c.ok) ? 'succeeded' : 'failed', result: { checks, node: ctx.nodeName } };
+        checks.push(await publicPortsCheck(ctx));
+        return {
+            commandId: command.id,
+            state: checks.every((c) => c.ok) ? 'succeeded' : 'failed',
+            result: { checks, node: ctx.nodeName },
+        };
     }
     if (command.type === 'service.restart') {
         const project = payload.project;
         const service = payload.service;
         const dir = path.join(ctx.stateDir, 'projects', project);
         await ctx.docker(['compose', '-p', project, 'restart', service], { cwd: dir });
-        return { commandId: command.id, state: 'succeeded', result: { project, service, restarted: true } };
+        return {
+            commandId: command.id,
+            state: 'succeeded',
+            result: { project, service, restarted: true },
+        };
     }
     if (command.type === 'logs.fetch') {
         const project = payload.project;
@@ -162,7 +657,11 @@ export async function executeCommand(command, ctx = defaultContext()) {
         const tail = String(payload.tail || 200);
         const dir = path.join(ctx.stateDir, 'projects', project);
         const result = await ctx.docker(['compose', '-p', project, 'logs', '--no-color', '--tail', tail, service], { cwd: dir });
-        return { commandId: command.id, state: 'succeeded', result: { stdout: result.out, stderr: result.err } };
+        return {
+            commandId: command.id,
+            state: 'succeeded',
+            result: { stdout: result.out, stderr: result.err },
+        };
     }
     if (command.type === 'volume.delete') {
         const project = payload.project;
@@ -175,23 +674,40 @@ export async function executeCommand(command, ctx = defaultContext()) {
             if (!errMessage(e).includes('No such volume'))
                 throw e;
         }
-        return { commandId: command.id, state: 'succeeded', result: { project, volume, deleted: true } };
+        return {
+            commandId: command.id,
+            state: 'succeeded',
+            result: { project, volume, deleted: true },
+        };
     }
     if (command.type === 'wg.rotate-key') {
         if (!ctx.mesh)
             throw new Error('the WireGuard mesh is not enabled on this agent (TUG_MESH=true)');
         const { publicKey } = await rotateWgKeys(ctx.stateDir);
-        await api(ctx, '/agent/v1/wireguard/key', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ publicKey }) });
+        await api(ctx, '/agent/v1/wireguard/key', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ publicKey }),
+        });
         await writeReportedKey(ctx.stateDir, publicKey);
         return { commandId: command.id, state: 'succeeded', result: { publicKey } };
     }
-    return { commandId: command.id, state: 'failed', result: { error: `unsupported command ${command.type}` } };
+    return {
+        commandId: command.id,
+        state: 'failed',
+        result: { error: `unsupported command ${command.type}` },
+    };
+}
+async function managedImageFile(ctx) {
+    await ensureDir(ctx.stateDir);
+    return path.join(ctx.stateDir, 'managed-images.json');
 }
-async function managedImageFile(ctx) { await ensureDir(ctx.stateDir); return path.join(ctx.stateDir, 'managed-images.json'); }
 async function managedImages(ctx) {
     try {
         const refs = JSON.parse(await fs.readFile(await managedImageFile(ctx), 'utf8'));
-        return Array.isArray(refs) ? refs.filter((ref) => typeof ref === 'string' && ref.startsWith('tug-build/')) : [];
+        return Array.isArray(refs)
+            ? refs.filter((ref) => typeof ref === 'string' && ref.startsWith('tug-build/'))
+            : [];
     }
     catch {
         return [];
@@ -205,7 +721,11 @@ export async function ensureArtifact(ctx, artifact) {
     }
     catch { }
     const remember = async (daemonId) => {
-        identities[artifact.imageRef] = { daemonId, artifactId: artifact.imageId, sha256: artifact.sha256 };
+        identities[artifact.imageRef] = {
+            daemonId,
+            artifactId: artifact.imageId,
+            sha256: artifact.sha256,
+        };
         await fs.writeFile(identityFile, JSON.stringify(identities), { mode: 0o600 });
         const refs = await managedImages(ctx);
         if (!refs.includes(artifact.imageRef))
@@ -214,14 +734,19 @@ export async function ensureArtifact(ctx, artifact) {
     const inspect = async () => JSON.parse((await ctx.docker(['image', 'inspect', artifact.imageRef])).out)[0];
     try {
         const image = await inspect();
-        if ((image?.Id === artifact.imageId || (identities[artifact.imageRef]?.daemonId === image?.Id && identities[artifact.imageRef]?.artifactId === artifact.imageId && identities[artifact.imageRef]?.sha256 === artifact.sha256)) && `${image.Os}/${image.Architecture}` === artifact.platform) {
+        if ((image?.Id === artifact.imageId ||
+            (identities[artifact.imageRef]?.daemonId === image?.Id &&
+                identities[artifact.imageRef]?.artifactId === artifact.imageId &&
+                identities[artifact.imageRef]?.sha256 === artifact.sha256)) &&
+            `${image.Os}/${image.Architecture}` === artifact.platform) {
             await remember(image.Id);
             return;
         }
     }
     catch { }
     const host = JSON.parse((await ctx.docker(['info', '--format', '{{json .}}'])).out);
-    const arch = { x86_64: 'amd64', aarch64: 'arm64' }[host.Architecture] || host.Architecture;
+    const arch = { x86_64: 'amd64', aarch64: 'arm64' }[host.Architecture] ||
+        host.Architecture;
     if (host.OSType && host.Architecture && `${host.OSType}/${arch}` !== artifact.platform)
         throw new Error(`image platform ${artifact.platform} does not match node ${host.OSType}/${arch}; build for the target platform`);
     const downloadDir = await fs.mkdtemp(path.join(ctx.stateDir, 'image-download-'));
@@ -268,7 +793,26 @@ export async function pruneManagedImages(ctx, retained) {
     }
     await fs.writeFile(await managedImageFile(ctx), JSON.stringify(remaining), { mode: 0o600 });
 }
-export async function reconcile(desiredState, ctx = defaultContext(), endpoints = {}) {
+/**
+ * The IP that published ports without a host IP listen on: `127.0.0.1` when the node has no
+ * address, the address itself when it is an IP, otherwise what it resolves to on this node.
+ */
+export async function resolveBindAddress(address, lookup = (host) => dns.lookup(host)) {
+    if (!address)
+        return '127.0.0.1';
+    const bare = address.replace(/^\[|\]$/g, '');
+    if (net.isIP(bare))
+        return bare;
+    try {
+        return (await lookup(bare)).address;
+    }
+    catch (e) {
+        throw new Error(`cannot resolve node address ${address} to bind published ports: ${errMessage(e)}`, { cause: e });
+    }
+}
+// Last public-port warning per project, so the event is sent when it changes rather than on every poll.
+const publicPortWarnings = new Map();
+export async function reconcile(desiredState, ctx = defaultContext(), endpoints = {}, ports = { address: null, loopback: {} }) {
     const dir = path.join(ctx.stateDir, 'projects', desiredState.project);
     await ensureDir(dir);
     const plannedCompose = composeForNode(desiredState, ctx.nodeName, {});
@@ -276,63 +820,169 @@ export async function reconcile(desiredState, ctx = defaultContext(), endpoints
     if (!serviceNames.length) {
         if (ctx.apply)
             await retireAll(ctx, dir, desiredState).catch(() => { });
-        return { project: desiredState.project, observedVersion: desiredState.version, ...(desiredState.revision ? { observedRevision: desiredState.revision } : {}), health: 'skipped', services: [], serviceStates: {} };
+        return {
+            project: desiredState.project,
+            observedVersion: desiredState.version,
+            ...(desiredState.revision ? { observedRevision: desiredState.revision } : {}),
+            health: 'skipped',
+            services: [],
+            serviceStates: {},
+        };
     }
-    const serviceStates = Object.fromEntries(serviceNames.map(service => [service, { rolloutState: 'pending', image: desiredState.services[service]?.image }]));
-    const emit = (service, rolloutState, message = rolloutState) => api(ctx, '/agent/v1/events', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ projectId: desiredState.project, level: 'info', type: `service.${rolloutState}`, message, metadata: { service, version: desiredState.version, node: ctx.nodeName } }) }).catch(() => { });
+    const serviceStates = Object.fromEntries(serviceNames.map((service) => [
+        service,
+        { rolloutState: 'pending', image: desiredState.services[service]?.image },
+    ]));
+    const emit = (service, rolloutState, message = rolloutState, level = 'info') => api(ctx, '/agent/v1/events', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            projectId: desiredState.project,
+            level,
+            type: `service.${rolloutState}`,
+            message,
+            metadata: { service, version: desiredState.version, node: ctx.nodeName },
+        }),
+    }).catch(() => { });
     const sec = await api(ctx, `/agent/v1/secrets?project=${encodeURIComponent(desiredState.project)}&services=${encodeURIComponent(serviceNames.join(','))}`);
     const currentSecretVersions = serviceSecretVersions(desiredState.compose, serviceNames, sec.versions || {});
     const db = await agentDb(ctx.stateDir);
     const previousRow = await db.get('SELECT version, revision, secret_versions_json FROM applied_state WHERE project = ?', desiredState.project);
-    const previous = previousRow ? { version: previousRow.version, revision: previousRow.revision, secretVersions: JSON.parse(previousRow.secret_versions_json) } : {};
-    const rolling = serviceNames.filter(service => isRolling(desiredState.compose.services[service]));
+    const previous = previousRow
+        ? {
+            version: previousRow.version,
+            revision: previousRow.revision,
+            secretVersions: JSON.parse(previousRow.secret_versions_json),
+        }
+        : {};
+    const rolling = serviceNames.filter((service) => isRolling(desiredState.compose.services[service]));
     const rollingSet = new Set(rolling);
-    const mainServices = serviceNames.filter(service => !rollingSet.has(service));
-    const secretChangedServices = mainServices.filter(service => JSON.stringify(previous.secretVersions?.[service] || {}) !== JSON.stringify(currentSecretVersions[service] || {}));
-    const sameDesiredVersion = desiredState.revision ? previous.revision === desiredState.revision : previous.version === desiredState.version;
+    const mainServices = serviceNames.filter((service) => !rollingSet.has(service));
+    const secretChangedServices = mainServices.filter((service) => JSON.stringify(previous.secretVersions?.[service] || {}) !==
+        JSON.stringify(currentSecretVersions[service] || {}));
+    const sameDesiredVersion = desiredState.revision
+        ? previous.revision === desiredState.revision
+        : previous.version === desiredState.version;
     // Rolling services run in their own revision projects; the main project holds only the recreated ones.
-    const nodeCompose = composeForNode(desiredState, ctx.nodeName, sec.secrets || {}, endpoints, rollingSet);
+    const loopback = new Set(ports.loopback[desiredState.project] || []);
+    // Resolve only when some port actually binds to the node address; a hostname nobody needs must not fail the apply.
+    const needsAddress = addressBoundServices(desiredState.compose, serviceNames, loopback).length > 0;
+    const bind = {
+        address: needsAddress ? await resolveBindAddress(ports.address) : '127.0.0.1',
+        loopback,
+    };
+    const nodeCompose = composeForNode(desiredState, ctx.nodeName, {
+        secrets: sec.secrets || {},
+        endpoints,
+        exclude: rollingSet,
+        bind,
+    });
+    await warnPublicPorts(ctx, desiredState, serviceNames, bind);
     await fs.writeFile(path.join(dir, 'docker-compose.yml'), dumpYaml(nodeCompose));
     await writeEnv(path.join(dir, '.env'), sec.secrets || {});
-    const failedStatus = (error) => ({ project: desiredState.project, observedVersion: desiredState.version, ...(desiredState.revision ? { observedRevision: desiredState.revision } : {}), health: 'failed', services: serviceNames, serviceStates, error });
+    const failedStatus = (error) => ({
+        project: desiredState.project,
+        observedVersion: desiredState.version,
+        ...(desiredState.revision ? { observedRevision: desiredState.revision } : {}),
+        health: 'failed',
+        services: serviceNames,
+        serviceStates,
+        error,
+    });
+    // Lifecycle events say what changed, not that the agent is still polling. They are sent when the desired revision,
+    // this node's rendered configuration or the secrets change, when an apply fails (once) and when it recovers (once).
+    const eventFingerprint = createHash('sha256')
+        .update(JSON.stringify([
+        desiredState.revision || desiredState.version,
+        dumpYaml(nodeCompose),
+        mainServices.map((service) => currentSecretVersions[service] || {}),
+    ]))
+        .digest('hex')
+        .slice(0, 16);
+    const knownEvents = mainServices.length
+        ? await db.get('SELECT fingerprint, phase FROM event_state WHERE project = ?', desiredState.project)
+        : undefined;
+    const announce = knownEvents?.fingerprint !== eventFingerprint;
+    const wasFailed = !announce && knownEvents?.phase === 'failed';
+    const markEvents = (phase) => db.run('INSERT INTO event_state(project, fingerprint, phase) VALUES(?,?,?) ON CONFLICT(project) DO UPDATE SET fingerprint=excluded.fingerprint, phase=excluded.phase', desiredState.project, eventFingerprint, phase);
+    let failing;
     if (ctx.apply) {
         try {
             for (const service of mainServices) {
                 serviceStates[service].rolloutState = 'pulling';
-                await emit(service, 'pulling');
+                if (announce)
+                    await emit(service, 'pulling');
             }
             for (const service of mainServices) {
                 const artifact = desiredState.services[service].artifact;
                 if (artifact)
                     await ensureArtifact(ctx, artifact);
             }
-            const pullServices = mainServices.filter(service => !desiredState.services[service].artifact);
+            // Registry images are pulled only for a new desired revision. Pulling on every poll would let a tag that moved
+            // upstream (`mariadb:11`) recreate the container without a deploy; `up -d` still pulls images that are missing.
+            const pullServices = sameDesiredVersion
+                ? []
+                : mainServices.filter((service) => !desiredState.services[service].artifact);
             if (pullServices.length)
-                await ctx.docker(['compose', '-p', desiredState.project, 'pull', ...(pullServices.length === mainServices.length ? [] : pullServices)], { cwd: dir });
+                await ctx.docker([
+                    'compose',
+                    '-p',
+                    desiredState.project,
+                    'pull',
+                    ...(pullServices.length === mainServices.length ? [] : pullServices),
+                ], { cwd: dir });
             for (const service of mainServices) {
                 serviceStates[service].rolloutState = 'starting';
-                await emit(service, 'starting');
+                if (announce)
+                    await emit(service, 'starting');
             }
             if (mainServices.length) {
                 // Services that just became rolling still run here until their replacement takes over; keep them.
-                const keepLegacy = rolling.length > 0 && await hasLegacyContainers(ctx, desiredState.project, rolling);
-                await ctx.docker(['compose', '-p', desiredState.project, 'up', '-d', ...(keepLegacy ? [] : ['--remove-orphans'])], { cwd: dir });
+                const keepLegacy = rolling.length > 0 && (await hasLegacyContainers(ctx, desiredState.project, rolling));
+                await ctx.docker([
+                    'compose',
+                    '-p',
+                    desiredState.project,
+                    'up',
+                    '-d',
+                    ...(keepLegacy ? [] : ['--remove-orphans']),
+                ], { cwd: dir });
             }
             if (sameDesiredVersion && secretChangedServices.length) {
                 for (const service of secretChangedServices)
                     await emit(service, 'secret_recreate', 'secret version changed; recreating service');
-                await ctx.docker(['compose', '-p', desiredState.project, 'up', '-d', '--no-deps', '--force-recreate', ...secretChangedServices], { cwd: dir });
+                await ctx.docker([
+                    'compose',
+                    '-p',
+                    desiredState.project,
+                    'up',
+                    '-d',
+                    '--no-deps',
+                    '--force-recreate',
+                    ...secretChangedServices,
+                ], { cwd: dir });
             }
             for (const service of mainServices) {
                 serviceStates[service].rolloutState = 'health_checking';
-                await emit(service, 'health_checking');
+                if (announce)
+                    await emit(service, 'health_checking');
+                failing = service;
                 await waitForHealth(ctx, desiredState.project, service, desiredState.services[service]?.health, dir);
+                failing = undefined;
                 serviceStates[service].rolloutState = 'serving';
                 serviceStates[service].healthyAt = now();
-                await emit(service, 'serving');
+                if (announce || wasFailed)
+                    await emit(service, 'serving', wasFailed ? 'serving again after a failure' : 'serving');
             }
+            if (mainServices.length && (announce || wasFailed))
+                await markEvents('serving');
         }
         catch (e) {
+            if (mainServices.length && !wasFailed) {
+                // Announce a failure once; retries of the same failure stay quiet until it recovers or the inputs change.
+                await emit(failing ?? mainServices.join(', '), 'failed', errMessage(e), 'error');
+                await markEvents('failed');
+            }
             // Rolling services are untouched by a failure here, so keep reporting their current revision as serving.
             if (!rolling.length)
                 throw e;
@@ -341,14 +991,24 @@ export async function reconcile(desiredState, ctx = defaultContext(), endpoints
         }
         if (rolling.length) {
             const rolled = await reconcileRolling(ctx, {
-                desired: desiredState, dir, services: rolling, secretVersions: currentSecretVersions,
-                full: composeForNode(desiredState, ctx.nodeName, sec.secrets || {}, endpoints),
+                desired: desiredState,
+                dir,
+                services: rolling,
+                secretVersions: currentSecretVersions,
+                full: composeForNode(desiredState, ctx.nodeName, {
+                    secrets: sec.secrets || {},
+                    endpoints,
+                    bind,
+                }),
                 deps: {
                     waitForHealth: (project, service, composeFile) => waitForHealth(ctx, project, service, desiredState.services[service]?.health, dir, composeFile),
-                    ensureArtifact: async (service) => { const artifact = desiredState.services[service].artifact; if (artifact)
-                        await ensureArtifact(ctx, artifact); },
-                    emit
-                }
+                    ensureArtifact: async (service) => {
+                        const artifact = desiredState.services[service].artifact;
+                        if (artifact)
+                            await ensureArtifact(ctx, artifact);
+                    },
+                    emit,
+                },
             });
             Object.assign(serviceStates, rolled.serviceStates);
             const errors = Object.entries(rolled.errors);
@@ -366,14 +1026,51 @@ export async function reconcile(desiredState, ctx = defaultContext(), endpoints
      VALUES(?,?,?,?,?,?)
      ON CONFLICT(project) DO UPDATE SET version=excluded.version, revision=excluded.revision, applied_at=excluded.applied_at,
        service_states_json=excluded.service_states_json, secret_versions_json=excluded.secret_versions_json`, desiredState.project, desiredState.version, desiredState.revision || null, now(), JSON.stringify(serviceStates), JSON.stringify(currentSecretVersions));
-    return { project: desiredState.project, observedVersion: desiredState.version, ...(desiredState.revision ? { observedRevision: desiredState.revision } : {}), health: 'serving', services: serviceNames, serviceStates };
+    return {
+        project: desiredState.project,
+        observedVersion: desiredState.version,
+        ...(desiredState.revision ? { observedRevision: desiredState.revision } : {}),
+        health: 'serving',
+        services: serviceNames,
+        serviceStates,
+    };
+}
+/** Emits a `ports.public` warning when published ports of this project are bound to a public node address. */
+async function warnPublicPorts(ctx, desiredState, serviceNames, bind) {
+    const key = `${ctx.stateDir}\0${desiredState.project}`;
+    const exposed = isPublicAddress(bind.address)
+        ? addressBoundServices(desiredState.compose, serviceNames, bind.loopback)
+        : [];
+    const message = exposed.length
+        ? `published ports of ${exposed.join(', ')} listen on public address ${bind.address}; enable the mesh, give the node a private address, or write the host IP in ports to make the exposure explicit`
+        : '';
+    if ((publicPortWarnings.get(key) ?? '') === message)
+        return;
+    publicPortWarnings.set(key, message);
+    if (!message)
+        return;
+    await api(ctx, '/agent/v1/events', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            projectId: desiredState.project,
+            level: 'warn',
+            type: 'ports.public',
+            message,
+            metadata: { services: exposed, address: bind.address, node: ctx.nodeName },
+        }),
+    }).catch(() => { });
 }
 /** Reports this node's WireGuard public key when control has not seen the current one yet. */
 export async function reportWgKey(ctx) {
     const { publicKey } = await ensureWgKeys(ctx.stateDir);
-    if (await readReportedKey(ctx.stateDir) === publicKey)
+    if ((await readReportedKey(ctx.stateDir)) === publicKey)
         return;
-    await api(ctx, '/agent/v1/wireguard/key', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ publicKey }) });
+    await api(ctx, '/agent/v1/wireguard/key', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ publicKey }),
+    });
     await writeReportedKey(ctx.stateDir, publicKey);
 }
 let lastNetworkError = '';
@@ -401,10 +1098,16 @@ export async function pollOnce(ctx = defaultContext()) {
     const projects = [];
     for (const desired of work.desiredStates || (work.desiredState ? [work.desiredState] : [])) {
         try {
-            projects.push(await reconcile(desired, ctx, work.serviceEndpoints?.[desired.project]));
+            projects.push(await reconcile(desired, ctx, work.serviceEndpoints?.[desired.project], work.ports));
         }
         catch (e) {
-            projects.push({ project: desired.project, observedVersion: desired.version, ...(desired.revision ? { observedRevision: desired.revision } : {}), health: 'failed', error: errMessage(e) });
+            projects.push({
+                project: desired.project,
+                observedVersion: desired.version,
+                ...(desired.revision ? { observedRevision: desired.revision } : {}),
+                health: 'failed',
+                error: errMessage(e),
+            });
         }
     }
     let ingress;
@@ -421,15 +1124,23 @@ export async function pollOnce(ctx = defaultContext()) {
             commandResults.push(await executeCommand(command, ctx));
         }
         catch (e) {
-            commandResults.push({ commandId: command.id, state: 'failed', result: { error: errMessage(e) } });
+            commandResults.push({
+                commandId: command.id,
+                state: 'failed',
+                result: { error: errMessage(e) },
+            });
         }
     }
     const report = { node: ctx.nodeName, projects, commandResults };
     if (ingress)
         report.ingress = ingress;
-    if (work.retainedImages && projects.every(project => project.health !== 'failed'))
+    if (work.retainedImages && projects.every((project) => project.health !== 'failed'))
         await pruneManagedImages(ctx, work.retainedImages);
-    await api(ctx, '/agent/v1/status', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(report) });
+    await api(ctx, '/agent/v1/status', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(report),
+    });
     return projects;
 }
 const CREDS_FILE = () => path.join(STATE_DIR, 'agent.json');
@@ -461,11 +1172,13 @@ async function readJoinKey() {
 }
 function dockerLogin(registry, user, password) {
     return new Promise((resolve, reject) => {
-        const p = spawn('docker', ['login', registry, '-u', user, '--password-stdin'], { stdio: ['pipe', 'ignore', 'pipe'] });
+        const p = spawn('docker', ['login', registry, '-u', user, '--password-stdin'], {
+            stdio: ['pipe', 'ignore', 'pipe'],
+        });
         let err = '';
-        p.stderr.on('data', d => err += d);
+        p.stderr.on('data', (d) => (err += d));
         p.on('error', reject);
-        p.on('close', code => code === 0 ? resolve() : reject(new Error(err.trim() || `exit ${code}`)));
+        p.on('close', (code) => code === 0 ? resolve() : reject(new Error(err.trim() || `exit ${code}`)));
         p.stdin.write(password);
         p.stdin.end();
     });
@@ -480,26 +1193,48 @@ async function enroll(joinKey) {
     }
     if (!decoded.enrollToken)
         throw new Error('join key is missing enrollToken');
-    const controlUrl = (!CONTROL_URL_FROM_ENV && decoded.controlUrl) ? decoded.controlUrl : CONTROL_URL;
+    const controlUrl = !CONTROL_URL_FROM_ENV && decoded.controlUrl ? decoded.controlUrl : CONTROL_URL;
     // node's fetch reads NODE_EXTRA_CA_CERTS only at startup, so apply an embedded CA by
     // persisting it and re-execing ourselves once with the env var set.
     if (decoded.ca && !process.env.NODE_EXTRA_CA_CERTS) {
         await ensureDir(STATE_DIR);
         const caPath = path.join(STATE_DIR, 'control-ca.pem');
         await fs.writeFile(caPath, decoded.ca);
-        const r = spawnSync(process.execPath, process.argv.slice(1), { stdio: 'inherit', env: { ...process.env, NODE_EXTRA_CA_CERTS: caPath } });
+        const r = spawnSync(process.execPath, process.argv.slice(1), {
+            stdio: 'inherit',
+            env: { ...process.env, NODE_EXTRA_CA_CERTS: caPath },
+        });
         process.exit(r.status ?? 1);
     }
     console.log(`enrolling with ${controlUrl} as ${NODE_NAME}`);
     const wgPublicKey = MESH ? (await ensureWgKeys(STATE_DIR)).publicKey : undefined;
     const res = await fetch(`${controlUrl}/agent/v1/enroll`, {
-        method: 'POST', headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ enrollToken: decoded.enrollToken, name: NODE_NAME, address: process.env.TUG_NODE_ADDRESS, publicAddress: process.env.TUG_NODE_PUBLIC_ADDRESS, wgPublicKey })
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            enrollToken: decoded.enrollToken,
+            name: NODE_NAME,
+            address: process.env.TUG_NODE_ADDRESS,
+            publicAddress: process.env.TUG_NODE_PUBLIC_ADDRESS,
+            wgPublicKey,
+            labels: decoded.labels ||
+                (process.env.TUG_LABELS
+                    ? process.env.TUG_LABELS.split(',')
+                        .map((s) => s.trim())
+                        .filter(Boolean)
+                    : undefined),
+        }),
     });
     if (!res.ok)
         throw new Error(`enroll failed: ${res.status} ${await res.text()}`);
-    const out = await res.json();
-    const creds = { agentToken: out.agentToken, nodeName: out.node?.name || NODE_NAME, controlUrl, registry: out.registry || null, registryToken: out.registryToken || null };
+    const out = (await res.json());
+    const creds = {
+        agentToken: out.agentToken,
+        nodeName: out.node?.name || NODE_NAME,
+        controlUrl,
+        registry: out.registry || null,
+        registryToken: out.registryToken || null,
+    };
     await saveCreds(creds);
     if (wgPublicKey)
         await writeReportedKey(STATE_DIR, wgPublicKey);
@@ -509,7 +1244,9 @@ async function enroll(joinKey) {
 // Establish durable credentials before polling: explicit env token (SSH/push install) wins,
 // then credentials persisted on the state volume, then a one-time enroll via the join key.
 export async function loadOrEnroll() {
-    let creds = TOKEN ? { agentToken: TOKEN, nodeName: NODE_NAME, controlUrl: CONTROL_URL } : await loadCreds();
+    let creds = TOKEN
+        ? { agentToken: TOKEN, nodeName: NODE_NAME, controlUrl: CONTROL_URL }
+        : await loadCreds();
     if (!creds) {
         const joinKey = await readJoinKey();
         if (!joinKey)
@@ -533,14 +1270,28 @@ export async function loadOrEnroll() {
 export async function main() {
     await loadOrEnroll();
     console.log(`tug-agent node=${NODE_NAME} control=${CONTROL_URL} apply=${APPLY}`);
+    const ctx = defaultContext();
+    const wake = new AgentWakeChannel(ctx, undefined, {
+        onLive: (frame) => live.handle(frame),
+        onDisconnect: () => live.dispose(),
+    });
+    const live = new AgentLiveOperations(ctx, (frame) => {
+        wake.send(frame);
+    });
     for (;;) {
         try {
-            await pollOnce();
+            await pollOnce(ctx);
         }
         catch (e) {
             console.error(errMessage(e));
         }
-        await new Promise(r => setTimeout(r, INTERVAL));
+        try {
+            await wake.wait(INTERVAL);
+        }
+        catch (e) {
+            console.error(`agent wake wait failed: ${errMessage(e)}`);
+            await new Promise((r) => setTimeout(r, INTERVAL));
+        }
     }
 }
 if (import.meta.url === `file://${process.argv[1]}`)