@wpelevator/tug 0.2.1 → 0.4.0

package/dist/agent.js

@@ -1,20 +1,26 @@
 #!/usr/bin/env node
 import fs from 'node:fs/promises';
-import { createWriteStream } from 'node:fs';
+import { createReadStream, createWriteStream } from 'node:fs';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { validateImageArchive, verifyDownload } from "./artifacts.js";
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import net from 'node:net';
+import dns from 'node:dns/promises';
+import { WebSocket } from 'ws';
 import { createHash } from 'node:crypto';
-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 { addressBoundServices, isRolling, serviceSecretVersions } from "./compose.js";
+import { containerSpecs, networkName, volumeName } from "./container-spec.js";
+import { API_VERSION, DockerEngine, isNotFound } from "./docker-api.js";
+import { LIVE_MAX_FRAME_BYTES, LIVE_START_TIMEOUT_MS } from "./protocol.js";
+import { LiveOperationEngine } from "./live.js";
+import { activeRollingStates, clearRolloutState, ensureProjectResources, loadRolloutState, projectContainers, reconcileRecreate, reconcileRolling, sweepOrphans, } from "./reconciler.js";
+import { ensureDir, errMessage, isPublicAddress, now, parseDuration } from "./util.js";
 import { openAgentDb } from "./db.js";
-import { createDockerRunner, createHostRunner } from "./runners.js";
+import { 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;
@@ -25,7 +31,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: new DockerEngine(),
+        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) {
@@ -37,36 +55,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();
 }
-async function writeEnv(file, secrets) {
-    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 });
+/** 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 containers = await projectContainers(ctx.docker, request.project, request.service);
+    // A rolling service has the draining revision beside the serving one; only the serving one is addressed.
+    const candidates = rolling?.active
+        ? containers.filter((c) => c.Names.includes(`/${rolling.active.container}`))
+        : containers;
+    if (candidates.length !== 1)
+        throw new Error(candidates.length
+            ? 'Service has multiple containers; select an unambiguous service'
+            : 'Service has no container on this node');
+    if (!/^[a-f0-9]{12,64}$/.test(candidates[0].Id))
+        throw new Error('Docker returned an invalid container ID');
+    return candidates[0].Id;
+}
+export class AgentLiveOperations {
+    ctx;
+    emit;
+    engine;
+    sessions = new Map();
+    constructor(ctx, emit, options = {}) {
+        this.ctx = ctx;
+        this.emit = emit;
+        this.engine = new LiveOperationEngine({
+            docker: ctx.docker,
+            ...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) {
+        const current = () => this.sessions.get(request.sessionId) === entry;
+        const started = () => this.emit({ v: 1, type: 'live.started', sessionId: request.sessionId });
+        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') {
+                // A query's result and exit follow `started` immediately, so announce it first.
+                started();
+                await this.engine.start({
+                    operation: 'ps',
+                    sessionId: request.sessionId,
+                    projects: [request.project],
+                });
+                return;
+            }
+            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 (!current())
+                return;
+            if (request.operation === 'inspect') {
+                started();
+                await this.engine.start({ operation: 'inspect', sessionId: request.sessionId, container });
+                return;
+            }
+            if (request.operation === 'exec')
+                await 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
+                await this.engine.start({
+                    operation: 'logs',
+                    sessionId: request.sessionId,
+                    container,
+                    tail: request.tail,
+                });
+            if (current())
+                started();
+            else
+                this.engine.cancel(request.sessionId);
+        }
+        catch (error) {
+            this.fail(request.sessionId, entry, error);
+        }
+    }
 }
-/** `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);
-    if (!ids.length)
-        throw new Error(`${service}: no container found`);
-    const inspected = JSON.parse((await ctx.docker(['inspect', ids[0]], { cwd })).out)[0];
-    const networks = inspected?.NetworkSettings?.Networks || {};
-    return Object.values(networks)[0]?.IPAddress || '127.0.0.1';
+/** The container's address on the project network, which health checks dial. */
+export async function containerIp(ctx, project, container) {
+    const networks = (await ctx.docker.inspectContainer(container)).NetworkSettings?.Networks || {};
+    const net = networks[networkName(project)] ?? Object.values(networks)[0];
+    return net?.IPAddress || net?.GlobalIPv6Address || '127.0.0.1';
 }
 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);
     });
 }
-export async function waitForHealth(ctx, project, service, health, cwd, composeFile) {
+export async function waitForHealth(ctx, project, container, service, health) {
     if (!ctx.apply || !health)
         return;
     const retries = Number(health.retries || 10);
@@ -75,19 +474,20 @@ 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 state = JSON.parse((await ctx.docker(['inspect', id], { cwd })).out)[0]?.State;
+                const state = (await ctx.docker.inspectContainer(container)).State;
                 if (!state?.Running)
                     throw new Error(`${service}: not running`);
                 if (state.Health && state.Health.Status !== 'healthy')
                     throw new Error(`${service}: docker health ${state.Health.Status}`);
             }
             else if (health.type === 'tcp') {
-                await tcpCheck(await containerIp(ctx, project, service, cwd, composeFile), health.port, parseDuration(health.timeout || '2s'));
+                await tcpCheck(await containerIp(ctx, project, container), health.port, parseDuration(health.timeout || '2s'));
             }
             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 ip = await containerIp(ctx, project, container);
+                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}`);
             }
@@ -95,7 +495,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)}`);
@@ -114,18 +514,76 @@ function describeHealthCheck(health) {
     return 'docker health check';
 }
 export { parseDuration };
+/** Containers of Tug projects (`projects`) that publish a port on all interfaces or on a public IP. */
+export function publicListeners(containers, projects) {
+    const out = [];
+    for (const c of containers) {
+        const project = c.Labels?.['tug.project'];
+        if (!project || !projects.includes(project))
+            continue;
+        for (const p of c.Ports || []) {
+            if (!p.PublicPort || !p.IP || !isPublicAddress(p.IP))
+                continue;
+            const host = p.IP.includes(':') ? `[${p.IP}]` : p.IP;
+            out.push({
+                project,
+                container: (c.Names?.[0] || c.Id).replace(/^\//, ''),
+                listen: `${host}:${p.PublicPort}->${p.PrivatePort}/${p.Type}`,
+            });
+        }
+    }
+    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 containers = await ctx.docker.listContainers({ label: ['tug.project'] }, false);
+        const listeners = publicListeners(containers, 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) };
+    }
+}
+const MIN_API_VERSION = API_VERSION.replace(/^v/, '');
+/** The minor number of an Engine API version such as `1.41`; 0 when unparseable. */
+const apiMinor = (version) => Number(version?.split('.')[1]) || 0;
 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']]
-        ]) {
+        const daemon = [
+            ['docker.info', async () => JSON.stringify(await ctx.docker.info(), null, 2)],
+            [
+                'docker.version',
+                async () => {
+                    const version = await ctx.docker.version();
+                    if (apiMinor(version.ApiVersion) < apiMinor(MIN_API_VERSION))
+                        throw new Error(`Docker Engine API ${version.ApiVersion} is older than the ${MIN_API_VERSION} the agent needs (Docker 20.10+)`);
+                    return JSON.stringify(version, null, 2);
+                },
+            ],
+        ];
+        for (const [name, fn] of daemon) {
             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: (await fn()).slice(-4000), stderr: '' });
             }
             catch (e) {
                 checks.push({ name, ok: false, error: errMessage(e).slice(-4000) });
@@ -137,62 +595,106 @@ 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',
+                async () => ({
+                    out: String((await ctx.docker.inspectContainer(CADDY_CONTAINER)).State?.Status),
+                    err: '',
+                }),
+            ]);
         }
         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 } };
+        const { project, service } = payload;
+        await ctx.docker.restartContainer(await resolveLiveContainer(ctx, { project, service }));
+        return {
+            commandId: command.id,
+            state: 'succeeded',
+            result: { project, service, restarted: true },
+        };
     }
     if (command.type === 'logs.fetch') {
-        const project = payload.project;
-        const service = payload.service;
-        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 } };
+        const { project, service } = payload;
+        const id = await resolveLiveContainer(ctx, { project, service });
+        const logs = await ctx.docker.logs(id, { follow: false, tail: Number(payload.tail || 200) });
+        const out = [];
+        const err = [];
+        logs.stdout.on('data', (d) => out.push(d));
+        logs.stderr.on('data', (d) => err.push(d));
+        await new Promise((resolve, reject) => {
+            logs.on('error', reject);
+            logs.on('close', () => resolve());
+        });
+        return {
+            commandId: command.id,
+            state: 'succeeded',
+            result: {
+                stdout: Buffer.concat(out).toString('utf8'),
+                stderr: Buffer.concat(err).toString('utf8'),
+            },
+        };
     }
     if (command.type === 'volume.delete') {
-        const project = payload.project;
-        const volume = payload.volume;
-        const composeVolume = `${project}_${volume}`;
-        try {
-            await ctx.docker(['volume', 'rm', composeVolume]);
-        }
-        catch (e) {
-            if (!errMessage(e).includes('No such volume'))
+        const { project, volume } = payload;
+        // Volumes are never removed by reconciliation; this explicit command is the only way one goes away.
+        await ctx.docker.removeVolume(volumeName(project, volume)).catch((e) => {
+            if (!isNotFound(e))
                 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 [];
@@ -206,24 +708,36 @@ 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))
             await fs.writeFile(await managedImageFile(ctx), JSON.stringify([...refs, artifact.imageRef]), { mode: 0o600 });
     };
-    const inspect = async () => JSON.parse((await ctx.docker(['image', 'inspect', artifact.imageRef])).out)[0];
+    const inspect = () => ctx.docker.inspectImage(artifact.imageRef);
     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 &&
+            (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;
-    if (host.OSType && host.Architecture && `${host.OSType}/${arch}` !== artifact.platform)
+    const host = await ctx.docker.info();
+    const arch = host.Architecture
+        ? { x86_64: 'amd64', aarch64: 'arm64' }[host.Architecture] ||
+            host.Architecture
+        : undefined;
+    if (host.OSType && arch && `${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-'));
     const file = path.join(downloadDir, 'image.tar.gz');
@@ -235,7 +749,7 @@ export async function ensureArtifact(ctx, artifact) {
         const archive = await validateImageArchive(file, artifact.imageRef);
         if (archive.imageId !== artifact.imageId || archive.platform !== artifact.platform)
             throw new Error('downloaded archive image metadata differs from desired artifact');
-        await ctx.docker(['load', '-i', file]);
+        await ctx.docker.loadImage(createReadStream(file));
         const image = await inspect();
         if (!image?.Id || `${image.Os}/${image.Architecture}` !== artifact.platform)
             throw new Error('loaded image identity or platform does not match desired artifact');
@@ -256,12 +770,11 @@ export async function pruneManagedImages(ctx, retained) {
             continue;
         }
         try {
-            const used = (await ctx.docker(['ps', '-aq', '--filter', `ancestor=${ref}`])).out.trim();
-            if (used) {
+            if ((await ctx.docker.listContainers({ ancestor: ref })).length) {
                 remaining.push(ref);
                 continue;
             }
-            await ctx.docker(['image', 'rm', ref]);
+            await ctx.docker.removeImage(ref);
         }
         catch {
             remaining.push(ref);
@@ -269,83 +782,161 @@ 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, {});
-    const serviceNames = Object.keys(plannedCompose.services || {});
+    const serviceNames = Object.keys(containerSpecs(desiredState, ctx.nodeName).specs);
     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: {} };
+        if (ctx.apply) {
+            await sweepOrphans(ctx.docker, desiredState.project, new Set()).catch(() => { });
+            await clearRolloutState(dir).catch(() => { });
+        }
+        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, 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 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 previousRow = await db.get('SELECT version, revision FROM applied_state WHERE project = ?', desiredState.project);
+    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;
-    // 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);
-    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 });
-    // 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 mainServices = serviceNames.filter((service) => !rollingSet.has(service));
+    // Published 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.
+    const sameDesiredVersion = previousRow
+        ? desiredState.revision
+            ? previousRow.revision === desiredState.revision
+            : previousRow.version === desiredState.version
+        : false;
+    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 plan = containerSpecs(desiredState, ctx.nodeName, {
+        secrets: sec.secrets || {},
+        secretVersions: sec.versions || {},
+        endpoints,
+        bind,
+    });
+    await warnPublicPorts(ctx, desiredState, serviceNames, bind);
+    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
+    // or any container definition (which includes the secret versions it uses) changes, when an apply fails (once)
+    // and when it recovers (once).
+    const eventFingerprint = createHash('sha256')
+        .update(JSON.stringify([
+        desiredState.revision || desiredState.version,
+        mainServices.map((service) => plan.specs[service].hash),
+    ]))
+        .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);
+    const deps = {
+        waitForHealth: (container, service, dependency) => waitForHealth(ctx, desiredState.project, container, service, desiredState.services[service]?.health ?? (dependency ? { type: 'docker' } : null)),
+        ensureArtifact: async (service) => {
+            const artifact = desiredState.services[service].artifact;
+            if (artifact)
+                await ensureArtifact(ctx, artifact);
+        },
+        pullImage: (service) => ctx.docker.pullImage(plan.specs[service].body.Image),
+        emit,
+    };
     let failing;
     if (ctx.apply) {
         try {
-            for (const service of mainServices) {
-                serviceStates[service].rolloutState = '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);
-            if (pullServices.length)
-                await ctx.docker(['compose', '-p', desiredState.project, 'pull', ...(pullServices.length === mainServices.length ? [] : pullServices)], { cwd: dir });
-            for (const service of mainServices) {
-                serviceStates[service].rolloutState = '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 });
-            }
-            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 });
-            }
-            for (const service of mainServices) {
-                serviceStates[service].rolloutState = '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();
-                if (announce || wasFailed)
-                    await emit(service, 'serving', wasFailed ? 'serving again after a failure' : 'serving');
-            }
+            await ensureProjectResources(ctx.docker, desiredState.project, plan);
+            await sweepOrphans(ctx.docker, desiredState.project, new Set(serviceNames));
+            if (mainServices.length)
+                await reconcileRecreate(ctx.docker, {
+                    desired: desiredState,
+                    dir,
+                    plan,
+                    nodeName: ctx.nodeName,
+                    deps,
+                    services: mainServices,
+                    pull: !sameDesiredVersion,
+                }, {
+                    pulling: async (service) => {
+                        serviceStates[service].rolloutState = 'pulling';
+                        if (announce)
+                            await emit(service, 'pulling');
+                    },
+                    starting: async (service) => {
+                        serviceStates[service].rolloutState = 'starting';
+                        if (announce)
+                            await emit(service, 'starting');
+                    },
+                    checking: async (service) => {
+                        serviceStates[service].rolloutState = 'health_checking';
+                        if (announce)
+                            await emit(service, 'health_checking');
+                    },
+                    serving: async (service) => {
+                        serviceStates[service].rolloutState = 'serving';
+                        serviceStates[service].healthyAt = now();
+                        if (announce || wasFailed)
+                            await emit(service, 'serving', wasFailed ? 'serving again after a failure' : 'serving');
+                    },
+                    failing: (service) => {
+                        failing = service;
+                    },
+                });
             if (mainServices.length && (announce || wasFailed))
                 await markEvents('serving');
         }
@@ -362,15 +953,14 @@ export async function reconcile(desiredState, ctx = defaultContext(), endpoints
             return failedStatus(errMessage(e));
         }
         if (rolling.length) {
-            const rolled = await reconcileRolling(ctx, {
-                desired: desiredState, dir, services: rolling, secretVersions: currentSecretVersions,
-                full: composeForNode(desiredState, ctx.nodeName, sec.secrets || {}, endpoints),
-                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
-                }
+            const rolled = await reconcileRolling(ctx.docker, {
+                desired: desiredState,
+                dir,
+                services: rolling,
+                plan,
+                nodeName: ctx.nodeName,
+                rolloutPorts: ctx.rolloutPorts,
+                deps,
             });
             Object.assign(serviceStates, rolled.serviceStates);
             const errors = Object.entries(rolled.errors);
@@ -378,7 +968,7 @@ export async function reconcile(desiredState, ctx = defaultContext(), endpoints
                 return failedStatus(errors.map(([service, error]) => `${service}: ${error}`).join('; '));
         }
         else
-            await retireAll(ctx, dir, desiredState);
+            await clearRolloutState(dir);
     }
     else {
         for (const service of serviceNames)
@@ -388,14 +978,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 = '';
@@ -423,10 +1050,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;
@@ -443,15 +1076,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');
@@ -483,11 +1124,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();
     });
@@ -502,26 +1145,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);
@@ -531,7 +1196,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)
@@ -555,14 +1222,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]}`)