@skrr-ai/cli 0.1.47 → 0.1.48

package/dist/lib/dedicated-service.js

@@ -0,0 +1,741 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GUEST_SERVICE_SOCKET_PATH = exports.DedicatedServiceChannel = exports.DedicatedServiceError = exports.SERVICE_ACTIONS = exports.SERVICE_RESTART_POLICIES = exports.SERVICE_RESERVED_NAMES = exports.SERVICE_SECRET_NAME_PATTERN = exports.SERVICE_NAME_PATTERN = exports.SERVICE_CALL_TIMEOUT_MS = exports.DEDICATED_SERVICE_EVENTS = void 0;
+exports.isServiceUnsupportedCode = isServiceUnsupportedCode;
+exports.describeServiceRefusal = describeServiceRefusal;
+exports.validateServiceSpec = validateServiceSpec;
+exports.parseServiceSpecDocument = parseServiceSpecDocument;
+exports.specPayload = specPayload;
+exports.specExportDocument = specExportDocument;
+exports.parseEnvEntries = parseEnvEntries;
+exports.parseParamEntries = parseParamEntries;
+exports.specFromFlags = specFromFlags;
+exports.streamServiceLogs = streamServiceLogs;
+exports.serviceTemplatesDir = serviceTemplatesDir;
+exports.loadLocalServiceTemplate = loadLocalServiceTemplate;
+exports.mergeServiceTemplate = mergeServiceTemplate;
+exports.serviceDetailText = serviceDetailText;
+exports.runningOnDedicatedRuntimeGuest = runningOnDedicatedRuntimeGuest;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const socket_io_client_1 = require("socket.io-client");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const agentic_stream_1 = require("./agentic-stream");
+const first_party_harness_1 = require("./first-party-harness");
+const format_1 = require("./format");
+/**
+ * Declared services on a Dedicated Runtime — the CLI half of
+ * docs/architecture/dedicated-runtime-always-on-workloads-2026-09-21.md (§5.3
+ * spec, §5.4 wire surface, §5.6 agent proposals).
+ *
+ * A service is a spec the daemon keeps reconciling: command, restart policy,
+ * env, per-service cgroup limits. The CLI never talks to the machine's
+ * registry — every verb rides the same admitted channel the terminal and SSH
+ * lanes use, as a `dedicated:service:*` socket event relayed by the API to the
+ * lease's daemon. What crosses the wire is exactly what the design doc names;
+ * anything not in the spec is refused by the daemon, not by us.
+ *
+ * Wire vocabulary (client side, mirrored from daemon:service:*):
+ *
+ *   client → API    dedicated:service:list|get|create|update|action|logs|
+ *                   logs:stop|approve|secret   {…payload, requestId}
+ *   API → client    dedicated:service:ack      {requestId, ok, error?, code?, result?}
+ *                   dedicated:service:state    {name, status, detail?, ts}
+ *                   dedicated:service:log      {name, streamId, data(b64), ts}
+ *                   dedicated:service:log:closed {name, streamId, reason}
+ *                   dedicated:service:proposed {name, spec, createdBy}
+ *                   dedicated:templates:ack    {requestId, ok, error?, code?, result?}
+ */
+exports.DEDICATED_SERVICE_EVENTS = {
+    list: 'dedicated:service:list',
+    get: 'dedicated:service:get',
+    create: 'dedicated:service:create',
+    update: 'dedicated:service:update',
+    action: 'dedicated:service:action',
+    logs: 'dedicated:service:logs',
+    logsStop: 'dedicated:service:logs:stop',
+    approve: 'dedicated:service:approve',
+    secret: 'dedicated:service:secret',
+    /** Phase-2 verbs — wired now; an old daemon refuses them cleanly. */
+    exec: 'dedicated:service:exec',
+    templatesList: 'dedicated:templates:list',
+    templatesGet: 'dedicated:templates:get',
+    ack: 'dedicated:service:ack',
+    templatesAck: 'dedicated:templates:ack',
+    state: 'dedicated:service:state',
+    log: 'dedicated:service:log',
+    logClosed: 'dedicated:service:log:closed',
+    proposed: 'dedicated:service:proposed',
+};
+/** How long a verb has to answer before the machine is declared unreachable. */
+exports.SERVICE_CALL_TIMEOUT_MS = 30_000;
+/** §5.3 — the scope name `skrr-svc-<name>` derives from it. */
+exports.SERVICE_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
+/** Secret names — the daemon's grammar; checked client-side so a bad name
+ *  is a usage error here, not a refusal that names the wrong object. */
+exports.SERVICE_SECRET_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/;
+/** Leaf names a service may never claim (the wrapper routes them itself). */
+exports.SERVICE_RESERVED_NAMES = new Set(['default', 'ssh', 'system']);
+exports.SERVICE_RESTART_POLICIES = new Set(['always', 'on-failure', 'never']);
+exports.SERVICE_ACTIONS = new Set(['start', 'stop', 'restart', 'remove']);
+const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENV_MAX_KEYS = 64;
+const ENV_VALUE_MAX_BYTES = 8 * 1024;
+/**
+ * Fields the daemon owns, never the client. `export` strips them so a repo
+ * `service.json` round-trips through `apply` cleanly; create/apply payloads
+ * drop them silently rather than fail — a checked-in spec can still carry
+ * them from a previous export or an older daemon's write.
+ */
+const DAEMON_OWNED_FIELDS = new Set(['createdBy', 'revision', 'createdAt', 'updatedAt']);
+class DedicatedServiceError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'DedicatedServiceError';
+        this.code = code;
+    }
+}
+exports.DedicatedServiceError = DedicatedServiceError;
+/** True for every refusal that says "this machine has no services support". */
+function isServiceUnsupportedCode(code) {
+    const c = (code || '').toLowerCase();
+    return (c === 'dedicated_runtime_services_unsupported' ||
+        c === 'services_unsupported' ||
+        c === 'unsupported' ||
+        c === 'not_implemented' ||
+        c === 'unknown_verb' ||
+        c === 'capability_missing' ||
+        c === 'dedicated_runtime_capability_missing');
+}
+/**
+ * A service refusal in words that say what to do — the same register
+ * `describeSshStartRefusal` uses for the SSH lane. The capability-missing
+ * branch mirrors the sshBridge fallback: an old image or an old daemon is a
+ * named condition with a next step, not a crash.
+ */
+function describeServiceRefusal(ack, context = {}) {
+    const code = ack.code || '';
+    if (isServiceUnsupportedCode(code)) {
+        return (ack.error ||
+            `This machine's daemon does not support the services_v1 extension${context.verb ? ` (${context.verb})` : ''}. ` +
+                `Its image may predate declared services — update it with \`skrr machines dedicated update-image ${context.leaseId || '<lease-id>'} --wait\`; \`skrr machines dedicated terminal\` and \`exec\` work in the meantime.`);
+    }
+    if (code === 'DEDICATED_RUNTIME_NOT_ASSIGNABLE') {
+        return ('The machine is not ready to take service commands (it must be running with a healthy workspace). ' +
+            `Check it with \`skrr machines dedicated show ${context.leaseId || '<lease-id>'}\`.`);
+    }
+    if (code === 'DEDICATED_RUNTIME_GENERATION_STALE') {
+        return 'The machine was replaced since its daemon registered. Wait a minute and try again.';
+    }
+    if (code === 'dedicated_runtime_quiesced') {
+        return 'The machine is checkpointing its workspace right now; try again in a moment.';
+    }
+    if (code === 'offline' || code === 'daemon_offline') {
+        return 'The machine’s daemon is not connected. Wait for it to come online and try again.';
+    }
+    if (code === 'conflict') {
+        return 'The service spec changed since you read it; fetch it again and re-apply your change.';
+    }
+    if (code === 'not_found') {
+        return context.name
+            ? `No service named ${context.name} on this machine.`
+            : 'The machine or the named service was not found.';
+    }
+    if (code === 'invalid' || code === 'validation') {
+        return `The daemon refused the spec: ${ack.error || 'invalid service spec'}`;
+    }
+    return ack.error ? `The service request failed: ${ack.error}` : 'The service request failed.';
+}
+/* ---------------------------------------------------------------- spec --- */
+/** Validation that costs the daemon nothing to re-check — §5.3's table, enforced client-side first. */
+function validateServiceSpec(doc, options = {}) {
+    const errors = [];
+    const { requireName = true, requireCommand = true } = options;
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+        return ['the spec must be a JSON object'];
+    }
+    const spec = doc;
+    if (spec.name !== undefined) {
+        if (typeof spec.name !== 'string' || !exports.SERVICE_NAME_PATTERN.test(spec.name)) {
+            errors.push('name must match ^[a-z0-9][a-z0-9-]{0,62}$');
+        }
+        else if (exports.SERVICE_RESERVED_NAMES.has(spec.name)) {
+            errors.push(`name "${spec.name}" is reserved (default, ssh, system are not services)`);
+        }
+    }
+    else if (requireName) {
+        errors.push('name is required');
+    }
+    const hasCommand = spec.command !== undefined;
+    const hasShell = spec.shell !== undefined;
+    if (hasCommand) {
+        if (!Array.isArray(spec.command) ||
+            spec.command.length === 0 ||
+            spec.command.some((w) => typeof w !== 'string' || w.length === 0)) {
+            errors.push('command must be a non-empty argv array of strings');
+        }
+        else if (spec.command.some((w) => w.includes('\0'))) {
+            errors.push('command arguments cannot contain null bytes');
+        }
+    }
+    if (hasShell && (typeof spec.shell !== 'string' || !spec.shell.trim())) {
+        errors.push('shell must be a non-empty string (run via sh -c)');
+    }
+    if (requireCommand && !hasCommand && !hasShell) {
+        errors.push('a command is required — argv after --, a "command" array, or a "shell" string');
+    }
+    if (spec.cwd !== undefined) {
+        if (typeof spec.cwd !== 'string' || !spec.cwd.startsWith('/')) {
+            errors.push('cwd must be an absolute path under the workspace (for example /workspace/repos/app)');
+        }
+    }
+    if (spec.env !== undefined) {
+        if (!spec.env || typeof spec.env !== 'object' || Array.isArray(spec.env)) {
+            errors.push('env must be an object of NAME=value pairs');
+        }
+        else {
+            const keys = Object.keys(spec.env);
+            if (keys.length > ENV_MAX_KEYS) {
+                errors.push(`env has ${keys.length} keys; at most ${ENV_MAX_KEYS} are allowed`);
+            }
+            for (const key of keys) {
+                if (!ENV_NAME_PATTERN.test(key)) {
+                    errors.push(`env key "${key}" is not a POSIX variable name`);
+                }
+                const value = spec.env[key];
+                if (typeof value !== 'string') {
+                    errors.push(`env.${key} must be a string`);
+                }
+                else if (Buffer.byteLength(value) > ENV_VALUE_MAX_BYTES) {
+                    errors.push(`env.${key} is over 8 KiB`);
+                }
+            }
+        }
+    }
+    if (spec.restart !== undefined && !exports.SERVICE_RESTART_POLICIES.has(String(spec.restart))) {
+        errors.push('restart must be always, on-failure or never');
+    }
+    if (spec.stopTimeoutSeconds !== undefined) {
+        const t = spec.stopTimeoutSeconds;
+        if (typeof t !== 'number' || !Number.isFinite(t) || t < 1 || t > 120) {
+            errors.push('stopTimeoutSeconds must be between 1 and 120');
+        }
+    }
+    if (spec.backoff !== undefined) {
+        if (!spec.backoff || typeof spec.backoff !== 'object' || Array.isArray(spec.backoff)) {
+            errors.push('backoff must be an object {initialMs, maxMs, budget, windowMs}');
+        }
+        else {
+            for (const key of ['initialMs', 'maxMs', 'windowMs']) {
+                const v = spec.backoff[key];
+                if (v !== undefined && (typeof v !== 'number' || !Number.isFinite(v) || v < 0)) {
+                    errors.push(`backoff.${key} must be a non-negative number`);
+                }
+            }
+            const budget = spec.backoff.budget;
+            if (budget !== undefined &&
+                (typeof budget !== 'number' || !Number.isInteger(budget) || budget < 0)) {
+                errors.push('backoff.budget must be a non-negative integer');
+            }
+        }
+    }
+    if (spec.limits !== undefined) {
+        if (!spec.limits || typeof spec.limits !== 'object' || Array.isArray(spec.limits)) {
+            errors.push('limits must be an object {memoryMax, cpuQuotaPercent, pidsMax}');
+        }
+        else {
+            const { memoryMax, cpuQuotaPercent, pidsMax } = spec.limits;
+            if (memoryMax !== undefined && (typeof memoryMax !== 'string' || !memoryMax.trim())) {
+                errors.push('limits.memoryMax must be a size string such as "512M" or "2G"');
+            }
+            if (cpuQuotaPercent !== undefined &&
+                (typeof cpuQuotaPercent !== 'number' ||
+                    !Number.isFinite(cpuQuotaPercent) ||
+                    cpuQuotaPercent <= 0)) {
+                errors.push('limits.cpuQuotaPercent must be a positive number');
+            }
+            if (pidsMax !== undefined &&
+                (typeof pidsMax !== 'number' || !Number.isInteger(pidsMax) || pidsMax <= 0)) {
+                errors.push('limits.pidsMax must be a positive integer');
+            }
+        }
+    }
+    if (spec.version !== undefined && spec.version !== 1) {
+        errors.push('version must be 1');
+    }
+    return errors;
+}
+/**
+ * Parse a `service.json` document, refusing with every problem named at once
+ * rather than the first — a file you are editing deserves the whole list.
+ */
+function parseServiceSpecDocument(raw, source, options = {}) {
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new DedicatedServiceError(`${source} is not valid JSON: ${err instanceof Error ? err.message : err}`, 'SPEC_JSON');
+    }
+    const errors = validateServiceSpec(doc, options);
+    if (errors.length > 0) {
+        throw new DedicatedServiceError(`${source} is not a valid service spec:\n${errors.map((e) => `  - ${e}`).join('\n')}`, 'SPEC_INVALID');
+    }
+    return doc;
+}
+/** The spec a mutation carries: the document minus the fields the daemon owns. */
+function specPayload(spec) {
+    const out = {};
+    for (const [key, value] of Object.entries(spec)) {
+        if (DAEMON_OWNED_FIELDS.has(key))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * The repo `service.json` form of a stored spec — `export`'s output. The
+ * document the daemon returned minus its bookkeeping, unknown fields kept
+ * verbatim so forward fields survive the round-trip.
+ */
+function specExportDocument(spec) {
+    return specPayload(spec);
+}
+/** `--env KEY=VALUE` entries, one flag instance each. */
+function parseEnvEntries(entries) {
+    const env = {};
+    for (const entry of entries ?? []) {
+        const eq = entry.indexOf('=');
+        if (eq <= 0) {
+            throw new DedicatedServiceError(`--env expects NAME=VALUE, got "${entry}"`, 'SPEC_INVALID');
+        }
+        env[entry.slice(0, eq)] = entry.slice(eq + 1);
+    }
+    return env;
+}
+/** `name=value` pairs for --param; the value stays a string — templates interpolate text. */
+function parseParamEntries(entries) {
+    return parseEnvEntries(entries);
+}
+/** A spec assembled from create/propose flags rather than a file. */
+function specFromFlags(input) {
+    const spec = { version: 1 };
+    if (input.name)
+        spec.name = input.name;
+    if (input.argv && input.argv.length > 0)
+        spec.command = input.argv;
+    if (input.cwd)
+        spec.cwd = input.cwd;
+    if (input.env && Object.keys(input.env).length > 0)
+        spec.env = input.env;
+    if (input.restart)
+        spec.restart = input.restart;
+    if (input.notify !== undefined)
+        spec.notify = input.notify;
+    if (input.stopTimeoutSeconds !== undefined)
+        spec.stopTimeoutSeconds = input.stopTimeoutSeconds;
+    if (input.limits) {
+        const limits = {};
+        if (input.limits.memoryMax)
+            limits.memoryMax = input.limits.memoryMax;
+        if (input.limits.cpuQuotaPercent !== undefined)
+            limits.cpuQuotaPercent = input.limits.cpuQuotaPercent;
+        if (input.limits.pidsMax !== undefined)
+            limits.pidsMax = input.limits.pidsMax;
+        if (Object.keys(limits).length > 0)
+            spec.limits = limits;
+    }
+    return spec;
+}
+function socketOptions(token) {
+    return {
+        path: '/ws/agentic',
+        auth: {
+            token,
+            ...(0, data_provider_1.getClientIdentityAuth)(),
+            clientPlatform: 'cli',
+            clientOs: process.platform === 'darwin' ? 'macos' : process.platform,
+        },
+        transports: ['websocket'],
+        reconnection: false,
+    };
+}
+/**
+ * One admitted socket for a run of service verbs. `call` emits
+ * `dedicated:service:<verb>` with a fresh requestId and resolves on the
+ * matching `dedicated:service:ack`; push events (`state`, `log`,
+ * `log:closed`, `proposed`) are exposed via `on` for the follow loop.
+ */
+class DedicatedServiceChannel {
+    options;
+    socket;
+    connected = false;
+    dead = false;
+    pending = new Map();
+    onDead = null;
+    constructor(options) {
+        this.options = options;
+        const connect = options.connect ?? socket_io_client_1.io;
+        this.socket = connect((0, agentic_stream_1.toWebSocketOrigin)(options.baseURL), socketOptions(options.token));
+        const onAck = (ack) => {
+            if (!ack?.requestId)
+                return;
+            const waiter = this.pending.get(ack.requestId);
+            if (!waiter)
+                return;
+            this.pending.delete(ack.requestId);
+            clearTimeout(waiter.timer);
+            waiter.resolve(ack);
+        };
+        this.socket.on(exports.DEDICATED_SERVICE_EVENTS.ack, onAck);
+        this.socket.on(exports.DEDICATED_SERVICE_EVENTS.templatesAck, onAck);
+    }
+    /** Resolves once the transport is up; rejects on connect failure. */
+    open() {
+        return new Promise((resolve, reject) => {
+            if (this.connected)
+                return resolve();
+            this.socket.on('connect', () => {
+                this.connected = true;
+                resolve();
+            });
+            this.socket.on('connect_error', (err) => {
+                if (this.connected)
+                    return;
+                this.close();
+                reject(new DedicatedServiceError(`Could not connect to skrr: ${err.message}`, err.data?.code || 'SERVICE_CONNECT_FAILED'));
+            });
+            this.socket.on('disconnect', () => {
+                this.dead = true;
+                for (const [, waiter] of this.pending) {
+                    clearTimeout(waiter.timer);
+                    waiter.resolve({
+                        ok: false,
+                        error: 'The connection to skrr closed before the machine answered.',
+                        code: 'disconnected',
+                    });
+                }
+                this.pending.clear();
+                this.onDead?.();
+            });
+        });
+    }
+    /** A socket dying mid-follow ends the follow cleanly rather than hanging. */
+    setOnDead(handler) {
+        this.onDead = handler;
+    }
+    get isConnected() {
+        return this.connected && !this.dead;
+    }
+    /**
+     * Emit a verb and await its ack. A refusal ack is a DedicatedServiceError
+     * whose message is the actionable sentence; the raw code rides along so a
+     * caller can branch on `conflict` or a missing capability.
+     */
+    call(verb, payload, timeoutMs = exports.SERVICE_CALL_TIMEOUT_MS) {
+        return this.callEvent(`dedicated:service:${verb}`, exports.DEDICATED_SERVICE_EVENTS.ack, payload, {
+            leaseId: typeof payload.leaseId === 'string' ? payload.leaseId : undefined,
+            verb,
+            name: typeof payload.name === 'string' ? payload.name : undefined,
+        }, timeoutMs);
+    }
+    /**
+     * A read against the template gallery — `dedicated:templates:list|get`,
+     * answered on `dedicated:templates:ack`. Same requestId/ack discipline as
+     * the service verbs; the event family is the only difference.
+     */
+    callTemplates(verb, payload, timeoutMs = exports.SERVICE_CALL_TIMEOUT_MS) {
+        return this.callEvent(`dedicated:templates:${verb}`, exports.DEDICATED_SERVICE_EVENTS.templatesAck, payload, {
+            verb: `templates:${verb}`,
+        }, timeoutMs);
+    }
+    /** The shared request/ack round-trip. */
+    callEvent(event, ackEvent, payload, context, timeoutMs) {
+        const requestId = `svc-${(0, node_crypto_1.randomUUID)()}`;
+        return new Promise((resolve, reject) => {
+            if (this.dead) {
+                reject(new DedicatedServiceError('The connection to skrr is closed.', 'disconnected'));
+                return;
+            }
+            const timer = setTimeout(() => {
+                this.pending.delete(requestId);
+                reject(new DedicatedServiceError('The machine did not answer in time. Its daemon may be busy, offline, or older than the services_v1 extension.', 'SERVICE_CALL_TIMEOUT'));
+            }, timeoutMs);
+            this.pending.set(requestId, {
+                timer,
+                resolve: (ack) => {
+                    if (!ack.ok) {
+                        reject(new DedicatedServiceError(describeServiceRefusal(ack, context), ack.code || 'SERVICE_REFUSED'));
+                        return;
+                    }
+                    resolve({ result: ack.result, ack });
+                },
+            });
+            this.socket.emit(event, { ...payload, requestId });
+        });
+    }
+    /** Subscribe to a server-pushed frame (`state`, `log`, `log:closed`, `proposed`). */
+    on(event, handler) {
+        this.socket.on(event, handler);
+    }
+    off(event, handler) {
+        this.socket.off(event, handler);
+    }
+    /** Emit without waiting for an ack (logs:stop — the stream may already be gone). */
+    send(event, payload) {
+        if (this.dead)
+            return;
+        this.socket.emit(event, payload);
+    }
+    close() {
+        for (const [, waiter] of this.pending)
+            clearTimeout(waiter.timer);
+        this.pending.clear();
+        this.dead = true;
+        try {
+            this.socket.disconnect();
+        }
+        catch {
+            /* a half-open socket refusing to close is not a failure */
+        }
+    }
+}
+exports.DedicatedServiceChannel = DedicatedServiceChannel;
+/**
+ * `service logs` — tail the stored log, then follow live
+ * `dedicated:service:log` frames until `log:closed`, a SIGINT, or the socket
+ * dies. Resolves with the exit code the command should use (0 unless the
+ * stream failed). The follow is closed with `dedicated:service:logs:stop` so
+ * the daemon does not keep piping to a dead reader.
+ */
+async function streamServiceLogs(options) {
+    const channel = new DedicatedServiceChannel(options);
+    const write = options.write ?? ((bytes) => options.output.write(bytes));
+    return new Promise((resolve, reject) => {
+        let streamId = null;
+        let finished = false;
+        const cleanupSignals = () => {
+            process.off('SIGINT', onSigint);
+            process.off('SIGTERM', onSigterm);
+        };
+        const finish = (code) => {
+            if (finished)
+                return;
+            finished = true;
+            cleanupSignals();
+            if (streamId && options.follow && !closedByServer) {
+                channel.send(exports.DEDICATED_SERVICE_EVENTS.logsStop, {
+                    leaseId: options.leaseId,
+                    name: options.name,
+                    streamId,
+                });
+            }
+            channel.close();
+            resolve(code);
+        };
+        const onSigint = () => finish(0);
+        const onSigterm = () => finish(0);
+        const onLog = (frame) => {
+            if (finished || !frame)
+                return;
+            if (streamId && frame.streamId && frame.streamId !== streamId)
+                return;
+            if (frame.name && frame.name !== options.name)
+                return;
+            if (typeof frame.data === 'string' && frame.data.length > 0) {
+                write(Buffer.from(frame.data, 'base64'));
+            }
+        };
+        // Set when the SERVER ended the stream — logs:stop answers a follow the
+        // client ended; a stream the daemon already closed has nothing to stop.
+        let closedByServer = false;
+        const onClosed = (frame) => {
+            if (finished || !frame)
+                return;
+            if (streamId && frame.streamId && frame.streamId !== streamId)
+                return;
+            if (frame.name && frame.name !== options.name)
+                return;
+            closedByServer = true;
+            if (frame.reason) {
+                options.errorOutput.write(`[log stream closed: ${frame.reason}]\n`);
+            }
+            finish(0);
+        };
+        // An agent proposal arriving while the owner watches logs surfaces where
+        // the owner is looking — stderr, so it never mingles with log bytes.
+        const onProposed = (frame) => {
+            if (finished || !frame)
+                return;
+            const proposalName = frame.name ?? frame.spec?.name ?? '(unnamed)';
+            const by = frame.createdBy ? ` by ${frame.createdBy}` : '';
+            options.errorOutput.write(`[an agent proposed service ${proposalName}${by} — approve with ` +
+                `\`skrr machines dedicated service approve ${options.leaseId} ${proposalName}\`]\n`);
+        };
+        channel.setOnDead(() => {
+            if (finished)
+                return;
+            options.errorOutput.write('[lost the connection to skrr; the log stream has ended]\n');
+            finish(1);
+        });
+        channel
+            .open()
+            .then(async () => {
+            process.on('SIGINT', onSigint);
+            process.on('SIGTERM', onSigterm);
+            channel.on(exports.DEDICATED_SERVICE_EVENTS.log, onLog);
+            channel.on(exports.DEDICATED_SERVICE_EVENTS.logClosed, onClosed);
+            channel.on(exports.DEDICATED_SERVICE_EVENTS.proposed, onProposed);
+            const { result } = await channel.call('logs', {
+                leaseId: options.leaseId,
+                name: options.name,
+                follow: options.follow,
+                ...(options.tailBytes !== undefined ? { tailBytes: options.tailBytes } : {}),
+            }, exports.SERVICE_CALL_TIMEOUT_MS);
+            streamId = typeof result?.streamId === 'string' ? result.streamId : null;
+            // A non-follow call can return the whole tail in the ack itself.
+            if (typeof result?.data === 'string' && result.data.length > 0) {
+                write(Buffer.from(result.data, 'base64'));
+            }
+            if (!options.follow)
+                finish(0);
+        })
+            .catch((err) => {
+            // Reject BEFORE closing — disconnect() fires onDead → finish(1),
+            // which would otherwise win the settlement race and mask the refusal.
+            finished = true;
+            cleanupSignals();
+            reject(err);
+            channel.close();
+        });
+    });
+}
+function serviceTemplatesDir(home = (0, node_os_1.homedir)()) {
+    return node_path_1.default.join(home, '.skrr', 'templates');
+}
+/**
+ * `~/.skrr/templates/<name>.json`, or null when absent. A template file that
+ * will not parse is an error, not a miss — silent fall-through to the gallery
+ * would hide a broken local file.
+ */
+function loadLocalServiceTemplate(name, home = (0, node_os_1.homedir)()) {
+    if (!exports.SERVICE_NAME_PATTERN.test(name)) {
+        throw new DedicatedServiceError(`Template name "${name}" is not valid (${exports.SERVICE_NAME_PATTERN}).`, 'TEMPLATE_NAME_INVALID');
+    }
+    const file = node_path_1.default.join(serviceTemplatesDir(home), `${name}.json`);
+    if (!(0, node_fs_1.existsSync)(file))
+        return null;
+    let doc;
+    try {
+        doc = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+    }
+    catch (err) {
+        throw new DedicatedServiceError(`${file} is not valid JSON: ${err instanceof Error ? err.message : err}`, 'TEMPLATE_JSON');
+    }
+    const template = doc;
+    if (!template ||
+        typeof template !== 'object' ||
+        typeof template.spec !== 'object' ||
+        !template.spec) {
+        throw new DedicatedServiceError(`${file} is not a service template — it needs a "spec" object.`, 'TEMPLATE_INVALID');
+    }
+    return template;
+}
+const PARAM_SLOT = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+function substitute(value, params, file) {
+    if (typeof value === 'string') {
+        return value.replace(PARAM_SLOT, (whole, key) => {
+            if (!(key in params)) {
+                throw new DedicatedServiceError(`Template ${file} uses \${${key}} but no value was given and the param has no default.`, 'TEMPLATE_PARAM_MISSING');
+            }
+            return params[key];
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((v) => substitute(v, params, file));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [
+            k,
+            substitute(v, params, file),
+        ]));
+    }
+    return value;
+}
+/**
+ * Merge a template with its params into a concrete spec. Required params
+ * without a value or a default refuse before any substitution runs — a
+ * half-merged spec is a worse failure than a named missing param.
+ */
+function mergeServiceTemplate(template, given, source = 'template') {
+    const declared = template.params ?? [];
+    const values = {};
+    for (const param of declared) {
+        if (!param || typeof param.name !== 'string')
+            continue;
+        if (param.name in given) {
+            values[param.name] = given[param.name];
+        }
+        else if (param.default !== undefined) {
+            values[param.name] = String(param.default);
+        }
+        else if (param.required) {
+            throw new DedicatedServiceError(`Template ${source} requires --param ${param.name}=<value>${param.description ? ` (${param.description})` : ''}`, 'TEMPLATE_PARAM_MISSING');
+        }
+    }
+    const undeclared = Object.keys(given).filter((k) => !declared.some((p) => p && p.name === k));
+    if (undeclared.length > 0) {
+        throw new DedicatedServiceError(`Template ${source} declares no param named ${undeclared.map((k) => `"${k}"`).join(', ')}.`, 'TEMPLATE_PARAM_UNKNOWN');
+    }
+    const merged = substitute(template.spec ?? {}, values, source);
+    return { version: 1, ...merged };
+}
+/* -------------------------------------------------------------- guest --- */
+/**
+ * The wire's `detail` is a string or the daemon's structured object
+ * ({reason, exitCode, signal, restarts, detail}) — render the fields for a
+ * status line, never "[object Object]". Shared by the owner-lane and
+ * guest-local status commands so both read the same shape.
+ */
+function serviceDetailText(detail) {
+    if (typeof detail === 'string')
+        return detail || undefined;
+    if (!detail || typeof detail !== 'object' || Array.isArray(detail))
+        return undefined;
+    const d = detail;
+    const parts = [];
+    if (typeof d.reason === 'string' && d.reason)
+        parts.push(d.reason);
+    if (typeof d.exitCode === 'number')
+        parts.push(`exit ${d.exitCode}`);
+    if (typeof d.signal === 'string' && d.signal)
+        parts.push(`signal ${d.signal}`);
+    if (typeof d.restarts === 'number')
+        parts.push(`${d.restarts} restarts`);
+    if (typeof d.backoffUntil === 'number')
+        parts.push(`backoff until ${(0, format_1.localStamp)(d.backoffUntil)}`);
+    if (typeof d.detail === 'string' && d.detail)
+        parts.push(d.detail);
+    return parts.join(', ') || undefined;
+}
+/** The daemon's workload-facing service socket on a Dedicated Runtime guest. */
+exports.GUEST_SERVICE_SOCKET_PATH = '/run/skrr-dedicated-runtime/service-propose/service-propose.sock';
+/**
+ * True when this process is running on a Dedicated Runtime guest — the
+ * workload-uid test, or the guest markers the image/daemon own. An SSH
+ * session may not carry the wrapper's env stamp, so the filesystem markers
+ * count too; the socket itself remains the authority.
+ */
+function runningOnDedicatedRuntimeGuest(env = process.env, getuid = process.getuid?.bind(process), paths = {}) {
+    if ((0, first_party_harness_1.isDedicatedRuntimeWorkload)(env, getuid))
+        return true;
+    const socketPath = paths.socketPath ?? exports.GUEST_SERVICE_SOCKET_PATH;
+    const attestation = paths.attestationPath ?? '/etc/skrr-dedicated-runtime/attestation.json';
+    const runtimeDir = paths.runtimeDir ?? '/run/skrr-dedicated-runtime';
+    return (0, node_fs_1.existsSync)(socketPath) || (0, node_fs_1.existsSync)(attestation) || (0, node_fs_1.existsSync)(runtimeDir);
+}