@skrr-ai/cli 0.1.47 → 0.1.49

package/dist/lib/dedicated-machines.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEDICATED_FILE_MAX_BYTES = exports.DEDICATED_FILE_CHUNK_BYTES = exports.DEDICATED_EXEC_DEFAULT_TIMEOUT_MS = exports.DEDICATED_EXEC_MAX_TIMEOUT_MS = exports.DEDICATED_MACHINE_PRODUCT = exports.DEDICATED_LEASE_ACTIONS = void 0;
+exports.describeDedicatedCheckpoint = describeDedicatedCheckpoint;
 exports.describeDedicatedImageStanding = describeDedicatedImageStanding;
 exports.dedicatedRuntimeCreateInput = dedicatedRuntimeCreateInput;
 exports.isDedicatedRepositoryRef = isDedicatedRepositoryRef;
@@ -16,6 +17,7 @@ exports.setDedicatedRuntimeSpendingLimit = setDedicatedRuntimeSpendingLimit;
 exports.closeDedicatedRuntimeIncidentHold = closeDedicatedRuntimeIncidentHold;
 exports.destroyDedicatedRuntime = destroyDedicatedRuntime;
 exports.execDedicatedRuntime = execDedicatedRuntime;
+exports.getDedicatedRuntimeSignInStatus = getDedicatedRuntimeSignInStatus;
 exports.startDedicatedRuntimeExecution = startDedicatedRuntimeExecution;
 exports.observeDedicatedRuntimeExecution = observeDedicatedRuntimeExecution;
 exports.readDedicatedRuntimeFileChunk = readDedicatedRuntimeFileChunk;
@@ -46,6 +48,7 @@ exports.dedicatedRuntimeApiErrorCode = dedicatedRuntimeApiErrorCode;
 exports.dedicatedRuntimeApiErrorDetails = dedicatedRuntimeApiErrorDetails;
 exports.formatDedicatedRuntimeApiError = formatDedicatedRuntimeApiError;
 const auth_core_1 = require("@skrr-ai/auth-core");
+const data_provider_1 = require("@skrr-ai/data-provider");
 const api_fetch_1 = require("./api-fetch");
 const edge_error_page_1 = require("./edge-error-page");
 const harnesses_1 = require("./harnesses");
@@ -58,6 +61,17 @@ exports.DEDICATED_LEASE_ACTIONS = [
     'health-check',
 ];
 exports.DEDICATED_MACHINE_PRODUCT = 'dedicated-machine';
+/**
+ * What an operation's guest checkpoint says, or null when the lease records
+ * none. One line, because the copy — and the judgement that this is a plain
+ * fact and not a warning — lives once in `@skrr-ai/data-provider`.
+ */
+function describeDedicatedCheckpoint(lease) {
+    const operation = lease?.operation;
+    if (!operation)
+        return null;
+    return (0, data_provider_1.describeMachineCheckpointOutcome)(operation.checkpoint, { action: operation.action });
+}
 /** One line saying where a machine's image stands and what the owner can do. */
 function describeDedicatedImageStanding(image, leaseId) {
     const last = image.lastUpdate;
@@ -304,6 +318,22 @@ async function execDedicatedRuntime(leaseId, input, scope = {}) {
         },
     });
 }
+/**
+ * `GET /api/machines/dedicated/:leaseId/sign-in-status` — is this machine
+ * signed in to gh, Claude Code and Codex?
+ *
+ * Its own endpoint rather than a caller of `exec`, for the reason recorded
+ * beside the route: before it, the only way to find out was to START a sign-in
+ * against a credential that was already fine (OSK-10795). Read-only on the
+ * guest — three `… status` subcommands, no writes, no tokens read back.
+ *
+ * The vocabulary (`DedicatedRuntimeSignInStatus`, its states, the probe and its
+ * parser) is OWNED by `@skrr-ai/data-provider` and re-exported here. A second
+ * declaration is how a surface drifts from the server that answers it.
+ */
+async function getDedicatedRuntimeSignInStatus(leaseId, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/sign-in-status`, scope));
+}
 /**
  * Start one command. `requestId` is the idempotency key: the same id, for the
  * same command on the same lease, returns the execution it already started —
@@ -586,6 +616,23 @@ function describeDedicatedLease(lease, harnesses = []) {
     if (hold?.status === 'open') {
         row('incident', `hold open since ${hold.heldAt || '?'} — the failed source volume is billed until \`incident-close\``);
     }
+    // The lease's last (or current) operation, and — the reason this row exists —
+    // whether the machine saved its workspace for it. A stop that paused the work
+    // first and a stop that gave up waiting are different facts about whether the
+    // owner's last writes landed, and until OSK-11023 the server recorded the
+    // difference and no surface printed it. Dated, because on a machine that has
+    // since started again the sentence is about a past operation.
+    const operation = lease.operation;
+    if (operation?.action || operation?.status) {
+        const settledAt = operation.completedAt || operation.startedAt;
+        // The payload's own spelling, minus the underscore: this row is read by a
+        // person, and `in_progress` beside a plain English sentence reads as a code.
+        const status = operation.status === 'in_progress' ? 'in progress' : operation.status;
+        row('operation', [operation.action, status, settledAt].filter(Boolean).join(' '));
+        const checkpoint = describeDedicatedCheckpoint(lease);
+        if (checkpoint)
+            lines.push(`  ${''.padEnd(13)}${checkpoint.sentence}`);
+    }
     const engines = dedicatedLeaseHarnesses(lease, harnesses);
     if (engines.length > 0) {
         row('engines', engines.map((harness) => `${harness.provider} (${harness.status || 'unknown'})`).join(', '));

package/dist/lib/dedicated-service-command.d.ts

@@ -0,0 +1,60 @@
+import { DedicatedLeaseCommand } from './dedicated-lease-command';
+import { DedicatedServiceChannel, type ServiceVerb } from './dedicated-service';
+/**
+ * The flag set `service create`/`apply` and guest `service propose` share —
+ * one definition so the three surfaces cannot drift apart on what a spec
+ * accepts. `--file` and the argv tail remain per-command because their
+ * mutual-exclusion rules differ.
+ */
+export declare const serviceSpecFlags: {
+    name: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    cwd: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    env: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    restart: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    notify: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    'stop-timeout': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    'limit-memory': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    'limit-cpu': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    'limit-pids': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+};
+/** The lease arg every service command takes, with `self` support. */
+export declare const SERVICE_LEASE_ARG_DESCRIPTION = "Dedicated Runtime lease id, or `self` when running on the machine itself";
+/**
+ * `stop|restart|remove` wait for the guest's full graceful-stop sequence —
+ * up to stopTimeoutSeconds (120s max) plus the kill/confirm tail.
+ */
+export declare const SERVICE_ACTION_TIMEOUT_MS = 150000;
+/**
+ * `skrr machines dedicated service …` — commands that act on one lease's
+ * declared services through the admitted `dedicated:service:*` socket lane.
+ *
+ * Unlike the lease REST calls these commands' verbs are socket events with a
+ * requestId/ack round-trip, so they open a channel per invocation rather than
+ * going through apiFetch. Every refusal — a refused ack, a missing
+ * capability, a dropped socket — lands on `this.error` with an actionable
+ * sentence, the same convention `callDedicated` gives the REST lane.
+ */
+export declare abstract class DedicatedServiceCommand extends DedicatedLeaseCommand {
+    private svcChannel;
+    /** The shared channel for this invocation, opened on first use. */
+    protected serviceChannel(): Promise<DedicatedServiceChannel>;
+    /** Emit one verb and return the daemon's `result`, or throw as a CLI error. */
+    protected callService<T = unknown>(verb: ServiceVerb, payload: Record<string, unknown>, timeoutMs?: number): Promise<T | undefined>;
+    /**
+     * `start|stop|restart|rm` — the shared `dedicated:service:action` round
+     * trip and its printout. `rm` maps to the `remove` action on the wire (the
+     * doc's verb name); the CLI spells it `rm` because that is what a person
+     * deleting a declaration types.
+     */
+    protected runServiceAction(leaseId: string, name: string, action: 'start' | 'stop' | 'restart' | 'remove', flags: {
+        json?: boolean;
+        workspace?: string;
+    }): Promise<void>;
+    protected closeServiceChannel(): void;
+    /**
+     * Turn a service-lane failure into the command's exit — the refusal
+     * sentence the relay sent, or the clean capability-missing path the SSH
+     * lane established for a missing `sshBridge`.
+     */
+    protected reportServiceError(err: unknown): never;
+}

package/dist/lib/dedicated-service-command.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DedicatedServiceCommand = exports.SERVICE_ACTION_TIMEOUT_MS = exports.SERVICE_LEASE_ARG_DESCRIPTION = exports.serviceSpecFlags = void 0;
+const core_1 = require("@oclif/core");
+const dedicated_lease_command_1 = require("./dedicated-lease-command");
+const dedicated_service_1 = require("./dedicated-service");
+/**
+ * The flag set `service create`/`apply` and guest `service propose` share —
+ * one definition so the three surfaces cannot drift apart on what a spec
+ * accepts. `--file` and the argv tail remain per-command because their
+ * mutual-exclusion rules differ.
+ */
+exports.serviceSpecFlags = {
+    name: core_1.Flags.string({
+        description: 'Service name — ^[a-z0-9][a-z0-9-]{0,62}$, unique per machine',
+    }),
+    cwd: core_1.Flags.string({
+        description: 'Absolute working directory under the workspace, e.g. /workspace/repos/app',
+    }),
+    env: core_1.Flags.string({
+        description: 'Environment variable as NAME=VALUE; repeat for several',
+        multiple: true,
+    }),
+    restart: core_1.Flags.string({
+        description: 'Restart policy: always | on-failure | never (default always)',
+        options: ['always', 'on-failure', 'never'],
+    }),
+    notify: core_1.Flags.boolean({
+        description: 'Notify the owner when the service reaches failed (default on)',
+        allowNo: true,
+    }),
+    'stop-timeout': core_1.Flags.integer({
+        description: 'Seconds SIGTERM gets before the service’s cgroup is killed (1-120, default 10)',
+        min: 1,
+        max: 120,
+    }),
+    'limit-memory': core_1.Flags.string({
+        description: 'Per-service memory ceiling, e.g. 512M or 2G (clamped to the workload slice)',
+    }),
+    'limit-cpu': core_1.Flags.integer({
+        description: 'Per-service CPU quota as a percent of one core, e.g. 100 for one core',
+        min: 1,
+    }),
+    'limit-pids': core_1.Flags.integer({
+        description: 'Per-service max process count',
+        min: 1,
+    }),
+};
+/** The lease arg every service command takes, with `self` support. */
+exports.SERVICE_LEASE_ARG_DESCRIPTION = 'Dedicated Runtime lease id, or `self` when running on the machine itself';
+/**
+ * `stop|restart|remove` wait for the guest's full graceful-stop sequence —
+ * up to stopTimeoutSeconds (120s max) plus the kill/confirm tail.
+ */
+exports.SERVICE_ACTION_TIMEOUT_MS = 150_000;
+/**
+ * `skrr machines dedicated service …` — commands that act on one lease's
+ * declared services through the admitted `dedicated:service:*` socket lane.
+ *
+ * Unlike the lease REST calls these commands' verbs are socket events with a
+ * requestId/ack round-trip, so they open a channel per invocation rather than
+ * going through apiFetch. Every refusal — a refused ack, a missing
+ * capability, a dropped socket — lands on `this.error` with an actionable
+ * sentence, the same convention `callDedicated` gives the REST lane.
+ */
+class DedicatedServiceCommand extends dedicated_lease_command_1.DedicatedLeaseCommand {
+    svcChannel = null;
+    /** The shared channel for this invocation, opened on first use. */
+    async serviceChannel() {
+        if (this.svcChannel?.isConnected)
+            return this.svcChannel;
+        this.svcChannel?.close();
+        const channel = new dedicated_service_1.DedicatedServiceChannel({
+            baseURL: this.cliConfig.baseURL,
+            token: this.resolvedCredential.token,
+        });
+        try {
+            await channel.open();
+        }
+        catch (err) {
+            this.reportServiceError(err);
+        }
+        this.svcChannel = channel;
+        return channel;
+    }
+    /** Emit one verb and return the daemon's `result`, or throw as a CLI error. */
+    async callService(verb, payload, timeoutMs) {
+        try {
+            const channel = await this.serviceChannel();
+            const { result } = await channel.call(verb, payload, timeoutMs);
+            return result;
+        }
+        catch (err) {
+            this.reportServiceError(err);
+        }
+    }
+    /**
+     * `start|stop|restart|rm` — the shared `dedicated:service:action` round
+     * trip and its printout. `rm` maps to the `remove` action on the wire (the
+     * doc's verb name); the CLI spells it `rm` because that is what a person
+     * deleting a declaration types.
+     */
+    async runServiceAction(leaseId, name, action, flags) {
+        // A graceful stop can take up to stopTimeoutSeconds (max 120s) plus the
+        // kill/confirm tail — the action ack waits for all of it, so the call
+        // window must outlive the longest legitimate stop or it reports a false
+        // connectivity failure while the machine is still working.
+        const result = await this.callService('action', {
+            leaseId,
+            name,
+            action,
+            ...this.scopeFrom(flags),
+        }, action === 'start' ? undefined : exports.SERVICE_ACTION_TIMEOUT_MS);
+        this.closeServiceChannel();
+        if (flags.json) {
+            this.log(JSON.stringify(result ?? { name, action }, null, 2));
+            return;
+        }
+        const sentences = {
+            start: {
+                done: 'is starting',
+                hint: 'The machine will keep it running per its restart policy.',
+            },
+            stop: {
+                done: 'is stopping',
+                hint: 'Desired state is stopped — it stays stopped across machine restarts until you `service start` it.',
+            },
+            restart: { done: 'is restarting' },
+            remove: {
+                done: 'was removed',
+                hint: 'The declaration is gone; the machine will not bring it back.',
+            },
+        };
+        const sentence = sentences[action];
+        this.log(`Service ${name} ${sentence.done}.`);
+        if (sentence.hint)
+            this.log(sentence.hint);
+    }
+    closeServiceChannel() {
+        this.svcChannel?.close();
+        this.svcChannel = null;
+    }
+    /**
+     * Turn a service-lane failure into the command's exit — the refusal
+     * sentence the relay sent, or the clean capability-missing path the SSH
+     * lane established for a missing `sshBridge`.
+     */
+    reportServiceError(err) {
+        if (err instanceof dedicated_service_1.DedicatedServiceError) {
+            if ((0, dedicated_service_1.isServiceUnsupportedCode)(err.code)) {
+                this.failWithCliError({
+                    message: err.message,
+                    code: 'DEDICATED_RUNTIME_SERVICES_UNSUPPORTED',
+                    exit: 1,
+                    retryable: false,
+                });
+            }
+            if (err.code === 'SERVICE_CONNECT_FAILED') {
+                this.failWithCliError({
+                    message: err.message,
+                    code: err.code,
+                    exit: 1,
+                    retryable: true,
+                });
+            }
+            // Usage-shape failures (bad spec, bad flags) are the caller's to fix.
+            const usage = [
+                'SPEC_JSON',
+                'SPEC_INVALID',
+                'SPEC_FILE',
+                'TEMPLATE_JSON',
+                'TEMPLATE_INVALID',
+                'TEMPLATE_NAME_INVALID',
+                'TEMPLATE_PARAM_MISSING',
+                'TEMPLATE_PARAM_UNKNOWN',
+            ].includes(err.code);
+            this.error(err.message, { exit: usage ? 2 : 1, code: err.code });
+        }
+        this.handleApiError(err);
+    }
+}
+exports.DedicatedServiceCommand = DedicatedServiceCommand;

package/dist/lib/dedicated-service.d.ts

@@ -0,0 +1,342 @@
+import { io, type Socket } from 'socket.io-client';
+/**
+ * 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?}
+ */
+export declare const DEDICATED_SERVICE_EVENTS: {
+    readonly list: "dedicated:service:list";
+    readonly get: "dedicated:service:get";
+    readonly create: "dedicated:service:create";
+    readonly update: "dedicated:service:update";
+    readonly action: "dedicated:service:action";
+    readonly logs: "dedicated:service:logs";
+    readonly logsStop: "dedicated:service:logs:stop";
+    readonly approve: "dedicated:service:approve";
+    readonly secret: "dedicated:service:secret";
+    /** Phase-2 verbs — wired now; an old daemon refuses them cleanly. */
+    readonly exec: "dedicated:service:exec";
+    readonly templatesList: "dedicated:templates:list";
+    readonly templatesGet: "dedicated:templates:get";
+    readonly ack: "dedicated:service:ack";
+    readonly templatesAck: "dedicated:templates:ack";
+    readonly state: "dedicated:service:state";
+    readonly log: "dedicated:service:log";
+    readonly logClosed: "dedicated:service:log:closed";
+    readonly proposed: "dedicated:service:proposed";
+};
+/** How long a verb has to answer before the machine is declared unreachable. */
+export declare const SERVICE_CALL_TIMEOUT_MS = 30000;
+/** §5.3 — the scope name `skrr-svc-<name>` derives from it. */
+export declare const SERVICE_NAME_PATTERN: RegExp;
+/** 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. */
+export declare const SERVICE_SECRET_NAME_PATTERN: RegExp;
+/** Leaf names a service may never claim (the wrapper routes them itself). */
+export declare const SERVICE_RESERVED_NAMES: Set<string>;
+export declare const SERVICE_RESTART_POLICIES: Set<string>;
+export declare const SERVICE_ACTIONS: Set<string>;
+/**
+ * The declared-service spec — §5.3's record shape. Unknown fields are kept:
+ * the forward-compat rule is a read/write rule (a spec written by a newer
+ * daemon must round-trip through an older client unmangled), so `apply` and
+ * `export` carry whatever the daemon returned rather than a known-fields
+ * projection. The phase-2/horizon names (`schedule`, `timezone`,
+ * `missedFire`, `probe`, `hooks`, `replicas`, `dependsOn`) are listed only so
+ * the type reads them; the index signature is what preserves them.
+ */
+export interface DedicatedServiceSpec {
+    version?: number;
+    name?: string;
+    command?: string[];
+    shell?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    restart?: 'always' | 'on-failure' | 'never' | string;
+    backoff?: {
+        initialMs?: number;
+        maxMs?: number;
+        budget?: number;
+        windowMs?: number;
+    };
+    stopTimeoutSeconds?: number;
+    notify?: boolean;
+    limits?: {
+        memoryMax?: string;
+        cpuQuotaPercent?: number;
+        pidsMax?: number;
+    };
+    disabled?: boolean;
+    createdBy?: string;
+    revision?: number;
+    createdAt?: string;
+    updatedAt?: string;
+    schedule?: string;
+    timezone?: string;
+    missedFire?: string;
+    probe?: unknown;
+    hooks?: unknown;
+    replicas?: number;
+    dependsOn?: string[];
+    [key: string]: unknown;
+}
+/** One computed-state row, as `list`/`get` return it. Status is derived, never stored. */
+export interface DedicatedServiceRow {
+    /** Present on state pushes and some relay shapes; list/get rows name the service only under `spec.name`. */
+    name?: string;
+    status?: string;
+    /** A plain string or the daemon's structured detail ({reason, exitCode, …}). */
+    detail?: string | Record<string, unknown>;
+    restart?: string;
+    createdBy?: string;
+    disabled?: boolean;
+    spec?: DedicatedServiceSpec;
+    /** Phase-2: per-scope metrics the daemon may attach (`cpu.stat` et al). */
+    stats?: DedicatedServiceStats;
+    [key: string]: unknown;
+}
+export interface DedicatedServiceStats {
+    cpuPercent?: number;
+    memoryBytes?: number;
+    memoryMaxBytes?: number;
+    pidsCurrent?: number;
+    pidsMax?: number;
+    [key: string]: unknown;
+}
+/** An agent proposal awaiting the owner — `status: proposed`, per §5.6. */
+export interface DedicatedServiceProposal {
+    name?: string;
+    proposalId?: string;
+    spec?: DedicatedServiceSpec;
+    createdBy?: string;
+    proposedAt?: string;
+    [key: string]: unknown;
+}
+export interface DedicatedServiceGetResult {
+    spec?: DedicatedServiceSpec;
+    status?: string;
+    detail?: string | Record<string, unknown>;
+    stats?: DedicatedServiceStats;
+    /** Bounded ring of recent exits: {exitCode, signal, at}. */
+    exits?: Array<{
+        exitCode?: number | null;
+        signal?: string | null;
+        at?: string;
+    }>;
+    [key: string]: unknown;
+}
+export interface DedicatedServiceAck {
+    requestId?: string;
+    ok?: boolean;
+    error?: string;
+    code?: string;
+    result?: unknown;
+}
+export declare class DedicatedServiceError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** True for every refusal that says "this machine has no services support". */
+export declare function isServiceUnsupportedCode(code: string | undefined): boolean;
+/**
+ * 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.
+ */
+export declare function describeServiceRefusal(ack: Pick<DedicatedServiceAck, 'code' | 'error'>, context?: {
+    leaseId?: string;
+    verb?: string;
+    name?: string;
+}): string;
+/** Validation that costs the daemon nothing to re-check — §5.3's table, enforced client-side first. */
+export declare function validateServiceSpec(doc: unknown, options?: {
+    requireName?: boolean;
+    requireCommand?: boolean;
+}): string[];
+/**
+ * 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.
+ */
+export declare function parseServiceSpecDocument(raw: string, source: string, options?: {
+    requireName?: boolean;
+    requireCommand?: boolean;
+}): DedicatedServiceSpec;
+/** The spec a mutation carries: the document minus the fields the daemon owns. */
+export declare function specPayload(spec: DedicatedServiceSpec): Record<string, unknown>;
+/**
+ * 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.
+ */
+export declare function specExportDocument(spec: DedicatedServiceSpec): Record<string, unknown>;
+/** `--env KEY=VALUE` entries, one flag instance each. */
+export declare function parseEnvEntries(entries: readonly string[] | undefined): Record<string, string>;
+/** `name=value` pairs for --param; the value stays a string — templates interpolate text. */
+export declare function parseParamEntries(entries: readonly string[] | undefined): Record<string, string>;
+/** A spec assembled from create/propose flags rather than a file. */
+export declare function specFromFlags(input: {
+    name?: string;
+    argv?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    restart?: string;
+    notify?: boolean;
+    stopTimeoutSeconds?: number;
+    limits?: {
+        memoryMax?: string;
+        cpuQuotaPercent?: number;
+        pidsMax?: number;
+    };
+}): DedicatedServiceSpec;
+export interface DedicatedServiceSocketOptions {
+    baseURL: string;
+    token: string;
+    /** Injected for tests. */
+    connect?: (url: string, opts: Parameters<typeof io>[1]) => Socket;
+}
+export type ServiceVerb = 'list' | 'get' | 'create' | 'update' | 'action' | 'logs' | 'logs:stop' | 'approve' | 'secret' | 'exec';
+/**
+ * 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.
+ */
+export declare class DedicatedServiceChannel {
+    private options;
+    private socket;
+    private connected;
+    private dead;
+    private pending;
+    private onDead;
+    constructor(options: DedicatedServiceSocketOptions);
+    /** Resolves once the transport is up; rejects on connect failure. */
+    open(): Promise<void>;
+    /** A socket dying mid-follow ends the follow cleanly rather than hanging. */
+    setOnDead(handler: (() => void) | null): void;
+    get isConnected(): boolean;
+    /**
+     * 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<T = unknown>(verb: ServiceVerb, payload: Record<string, unknown>, timeoutMs?: number): Promise<{
+        result: T | undefined;
+        ack: DedicatedServiceAck;
+    }>;
+    /**
+     * 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<T = unknown>(verb: 'list' | 'get', payload: Record<string, unknown>, timeoutMs?: number): Promise<{
+        result: T | undefined;
+        ack: DedicatedServiceAck;
+    }>;
+    /** The shared request/ack round-trip. */
+    private callEvent;
+    /** Subscribe to a server-pushed frame (`state`, `log`, `log:closed`, `proposed`). */
+    on(event: string, handler: (frame: Record<string, unknown>) => void): void;
+    off(event: string, handler: (frame: Record<string, unknown>) => void): void;
+    /** Emit without waiting for an ack (logs:stop — the stream may already be gone). */
+    send(event: string, payload: Record<string, unknown>): void;
+    close(): void;
+}
+export interface ServiceLogFrame {
+    name?: string;
+    streamId?: string;
+    data?: string;
+    ts?: number | string;
+}
+export interface ServiceLogClosedFrame {
+    name?: string;
+    streamId?: string;
+    reason?: string;
+}
+export interface StreamServiceLogsOptions extends DedicatedServiceSocketOptions {
+    leaseId: string;
+    name: string;
+    follow: boolean;
+    /** Bytes from the end of the log to replay first. */
+    tailBytes?: number;
+    output: NodeJS.WritableStream;
+    errorOutput: NodeJS.WritableStream;
+    /** Frame sink for tests; defaults to output.write. */
+    write?: (bytes: Buffer) => void;
+}
+/**
+ * `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.
+ */
+export declare function streamServiceLogs(options: StreamServiceLogsOptions): Promise<number>;
+/**
+ * A service template — §10.2's spec-with-holes. `${param}` slots inside
+ * `spec` are substituted with --param values or the param's default.
+ */
+export interface DedicatedServiceTemplate {
+    version?: number;
+    name?: string;
+    description?: string;
+    params?: Array<{
+        name: string;
+        required?: boolean;
+        default?: string;
+        description?: string;
+    }>;
+    spec?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export declare function serviceTemplatesDir(home?: string): string;
+/**
+ * `~/.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.
+ */
+export declare function loadLocalServiceTemplate(name: string, home?: string): DedicatedServiceTemplate | null;
+/**
+ * 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.
+ */
+export declare function mergeServiceTemplate(template: DedicatedServiceTemplate, given: Record<string, string>, source?: string): DedicatedServiceSpec;
+/**
+ * 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.
+ */
+export declare function serviceDetailText(detail: unknown): string | undefined;
+/** The daemon's workload-facing service socket on a Dedicated Runtime guest. */
+export declare const 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.
+ */
+export declare function runningOnDedicatedRuntimeGuest(env?: NodeJS.ProcessEnv, getuid?: (() => number) | undefined, paths?: {
+    socketPath?: string;
+    attestationPath?: string;
+    runtimeDir?: string;
+}): boolean;