@rallycry/conveyor-k3 0.1.11 → 0.1.13

package/dist/index.d.ts

@@ -5,10 +5,17 @@ interface ClusterConnectionConfig {
     clusterToken: string;
     /** Test-only override; production always reads the root-owned guest key. */
     deviceKeyPath?: string;
+    /** Test-only overrides; production reads the host-written control aliases. */
+    readControlFile?: (path: string) => string | null;
+    controlFileExists?: (path: string) => boolean;
+    /** Dial again after the server closes the socket. The daemon's connection only. */
+    reconnectWhenReplaced?: boolean;
 }
 declare class ClusterConnection {
     private socket;
     private readonly config;
+    private redialDelayMs;
+    private redialTimer;
     /** Called when Conveyor says the desired state changed. */
     onSyncRequested: (() => void) | null;
     /** Called when Conveyor asks the machine to remove itself. */
@@ -26,6 +33,8 @@ declare class ClusterConnection {
      * instead of waiting out the stale window.
      */
     sayGoodbye(timeoutMs?: number): Promise<void>;
+    /** Dial again after the server closed the socket, waiting longer each time. */
+    private redial;
     disconnect(): void;
 }
 
@@ -68,7 +77,8 @@ interface FileSystemPort$1 {
     readFile(path: string): Promise<string | null>;
     writeFile(path: string, content: string, mode?: number): Promise<void>;
     removeFile(path: string): Promise<void>;
-    ensureDir(path: string): Promise<void>;
+    /** With a mode, an existing directory is set to it as well. */
+    ensureDir(path: string, mode?: number): Promise<void>;
 }
 declare const nodeFileSystem: FileSystemPort$1;
 /** In-memory filesystem for tests. Exported so suites share one shape. */
@@ -78,6 +88,23 @@ declare function createMemoryFileSystem(seed?: Record<string, string>): FileSyst
     removed: string[];
 };
 
+/**
+ * The long-lived daemon: connect, converge, report, repeat.
+ *
+ * Three clocks, deliberately independent:
+ *
+ * - **Heartbeat, 30s.** Placement reads what this writes, so it is the one
+ *   thing that must never stall behind slower work.
+ * - **Warm, hourly.** Re-pull the wanted refs so a bake never costs the next
+ *   card a cold multi-gigabyte pull.
+ * - **Reconcile + prune, daily** — plus on connect and whenever Conveyor says
+ *   the desired state changed.
+ *
+ * The daily reconcile is what makes this a reconciler rather than a command
+ * listener: a machine that was powered off, or whose sync nudge landed on
+ * another API replica, still converges on its own.
+ */
+
 interface DaemonPorts {
     exec: Executor;
     fs: FileSystemPort$1;
@@ -85,6 +112,8 @@ interface DaemonPorts {
     cliVersion: string;
     writeWorkloads?: (data: PersonalClusterWorkloads | undefined) => Promise<void>;
     log: (line: string) => void;
+    /** The in-cluster registry's HTTP API; the global `fetch` when absent. */
+    fetch?: (url: string, init?: RequestInit) => Promise<Response>;
 }
 declare class ClusterDaemon {
     private readonly ports;
@@ -105,15 +134,33 @@ declare class ClusterDaemon {
      * the next reconcile silently clear them.
      */
     private warmWarnings;
+    /** Content hash labels by image id, so each image is inspected once. */
+    private readonly localImageHashes;
+    /** How long the in-cluster registry has been not ready, across beats. */
+    private readonly registryWatch;
+    /**
+     * Whether pod isolation is in force, from the last reconcile; undefined
+     * while desired state does not ask for it. Every heartbeat checks it again
+     * against k3s's own settings before reporting it.
+     */
+    private isolation;
     private timers;
+    /** When the last store walk started, so one that failed is not retried on every reconcile. */
+    private storeWalkStartedAt;
     /** Serializes reconcile against itself — a sync nudge during a reconcile
      *  must queue, not interleave two kubectl applies of the same manifests. */
     private reconciling;
+    /** The run queued behind the running one, until it starts. At most one waits. */
+    private queuedRun;
+    /** The next reconcile while pod isolation is not applied; `dueAt` 0 = none. */
+    private isolationRetry;
     constructor(ports: DaemonPorts);
     start(): Promise<void>;
     stop(): Promise<void>;
     /** Fetch the desired state and converge to it. Queued, never concurrent. */
     syncAndReconcile(): Promise<void>;
+    /** Reconcile again later while pod isolation is not applied; stop once it is. */
+    private scheduleIsolationRetry;
     private runReconcile;
     /**
      * The hourly clock: warm, re-pin, and reclaim if the pile justifies it.
@@ -124,6 +171,14 @@ declare class ClusterDaemon {
      * generations in between.
      */
     private warmAndPruneIfDue;
+    /**
+     * Measure k3s's containerd store when the last measurement is old enough,
+     * and keep the result for the heartbeat. After a prune, so the number it
+     * reports is what the prune left. A failed measurement keeps the last one.
+     */
+    private measureStoreIfDue;
+    /** The store size the heartbeat reports: the last measurement, null before one. */
+    private get measuredStoreBytes();
     /** Pre-pull the wanted refs. Silent on success; that is the normal case. */
     warm(): Promise<void>;
     /**
@@ -158,63 +213,8 @@ declare class ClusterDaemon {
     private runBeat;
 }
 
-/**
- * Converge the machine onto Conveyor's desired state.
- *
- * This is what "manages itself" means in code. Conveyor publishes what the
- * cluster SHOULD look like; this function makes it so, and it runs on connect,
- * on request, and daily. Nothing here is a command from the server — a machine
- * that was powered off for a week catches up on its next run, and a practice
- * Conveyor changes reaches every enrolled box without anyone touching one.
- *
- * Three properties every step keeps:
- *
- * 1. **Idempotent.** Running twice changes nothing the first run already did.
- * 2. **Independently fallible.** A step that fails records a warning and the
- *    rest still run. A cluster with one bad namespace is not a reason to skip
- *    image hygiene.
- * 3. **Additive.** Nothing here deletes a namespace, a workload, or an image
- *    that is in use. The machine belongs to its owner.
- * 4. **Bounded.** The server does not get to say what runs here. The one field
- *    it sends as raw YAML is checked against a local kind allowlist before it
- *    reaches `kubectl` — see `../lib/manifest-guard.js`.
- */
-
-/** The filesystem operations reconcile needs, injectable for tests. */
-interface FileSystemPort {
-    readFile(path: string): Promise<string | null>;
-    writeFile(path: string, content: string, mode?: number): Promise<void>;
-    removeFile(path: string): Promise<void>;
-    ensureDir(path: string): Promise<void>;
-}
-interface ReconcileContext {
-    exec: Executor;
-    fs: FileSystemPort;
-    /**
-     * Conveyor pods currently running here, or null when that could not be
-     * determined. A disruptive step is unsafe above zero AND unsafe on null —
-     * "I could not ask" is not "nothing is running".
-     */
-    runningConveyorPods: number | null;
-}
-interface ReconcileResult {
-    appliedVersion: number;
-    warnings: string[];
-    /** True when the kubelet drop-in changed and k3s was restarted. */
-    restartedK3s: boolean;
-    /** Kubelet flags left to the owner because their own config sets them. */
-    skippedKubeletFlags: string[];
-    /**
-     * The image-GC high threshold the kubelet is actually enforcing — ours, or
-     * the owner's when their own config.yaml set it and the drop-in stood down.
-     * Null when neither side named one. Reported so the heartbeat can warn about
-     * GC pressure against the number in force rather than the one we sent.
-     */
-    effectiveImageGcHighThreshold: number | null;
-    /** True when a wrong-valued PriorityClass was deleted AND put back. */
-    recreatedPriorityClass: boolean;
-}
-declare function reconcile(ctx: ReconcileContext, desired: PersonalClusterDesiredState): Promise<ReconcileResult>;
+/** The `fetch` the registry API calls go through, injectable for tests. */
+type RegistryFetch = (url: string, init?: RequestInit) => Promise<Response>;
 
 /** One entry of `crictl images -o json`. */
 interface CrictlImage {
@@ -277,6 +277,22 @@ interface WarmResult {
  */
 declare function warmImages(exec: Executor, wantedImages: string[], unauthenticatedHosts: string[]): Promise<WarmResult>;
 
+/**
+ * Which locally baked images this machine holds, for placement.
+ *
+ * A Bake Locally project's image exists only where a bake imported it: the
+ * runner's own machine, or the managed VM on it. When one account has several
+ * instances, placement has to send a card to an instance that holds the image,
+ * and should prefer one holding the latest bake. So the heartbeat lists every
+ * `localhost/` ref, with the content hash the bake stamped on the image.
+ *
+ * The hash takes one `crictl inspecti` per image, cached by image id: an id
+ * names exactly one image config, so its label never changes.
+ */
+
+/** Image id to the content hash label on that image, null when it has none. */
+type LocalImageHashCache = Map<string, string | null>;
+
 interface TelemetryState {
     cliVersion: string;
     appliedDesiredStateVersion: number;
@@ -291,10 +307,36 @@ interface TelemetryState {
      * no reconcile has read one yet. Drives the GC-pressure warning below.
      */
     imageGcHighThreshold?: number | null;
+    /** The daemon's own cache of content hash labels, kept across beats. */
+    localImageHashes?: LocalImageHashCache;
+    /** Present while desired state turns the in-cluster registry on. */
+    localRegistry?: LocalRegistryWatch;
+    /** Present while desired state asks for pod isolation (a host-runtime machine). */
+    isolation?: {
+        applied: boolean;
+    };
+    /**
+     * The last measured size of k3s's containerd store. Null (or absent) until
+     * the first measurement, and the heartbeat says null then: a 0 would read
+     * as an empty store.
+     */
+    k3sStoreBytes?: number | null;
 }
 interface TelemetryPorts {
     exec: Executor;
     readFile(path: string): Promise<string | null>;
+    /** Injectable for tests; the registry probe uses the global otherwise. */
+    fetch?: RegistryFetch;
+}
+/** The daemon's memory of the registry's readiness, kept across beats. */
+interface LocalRegistryWatch {
+    /** When a beat first found the registry not ready; null while it is. */
+    notReadySince: number | null;
+    /**
+     * Until when a cleanup stops the registry on purpose. The clock does not
+     * run until then, so the panel never calls that stop an outage.
+     */
+    pausedUntil?: number | null;
 }
 /**
  * Conveyor pods running here, across every namespace it manages — or null when
@@ -313,6 +355,78 @@ interface TelemetryPorts {
 declare function countRunningConveyorPods(exec: Executor): Promise<number | null>;
 declare function collectHeartbeat(ports: TelemetryPorts, state: TelemetryState, inventory: ImageInventory | null): Promise<PersonalClusterHeartbeat>;
 
+/**
+ * Converge the machine onto Conveyor's desired state.
+ *
+ * This is what "manages itself" means in code. Conveyor publishes what the
+ * cluster SHOULD look like; this function makes it so, and it runs on connect,
+ * on request, and daily. Nothing here is a command from the server — a machine
+ * that was powered off for a week catches up on its next run, and a practice
+ * Conveyor changes reaches every enrolled box without anyone touching one.
+ *
+ * Three properties every step keeps:
+ *
+ * 1. **Idempotent.** Running twice changes nothing the first run already did.
+ * 2. **Independently fallible.** A step that fails records a warning and the
+ *    rest still run. A cluster with one bad namespace is not a reason to skip
+ *    image hygiene.
+ * 3. **Additive.** Nothing here deletes a namespace, a workload, or an image
+ *    that is in use. The machine belongs to its owner. The one delete is an
+ *    EMPTY pool namespace of a project the machine no longer serves, under
+ *    local bounds the server cannot widen — see `./prune-namespaces.js`.
+ * 4. **Bounded.** The server does not get to say what runs here. The one field
+ *    it sends as raw YAML is checked against a local kind allowlist before it
+ *    reaches `kubectl` — see `../lib/manifest-guard.js`.
+ */
+
+/** The filesystem operations reconcile needs, injectable for tests. */
+interface FileSystemPort {
+    readFile(path: string): Promise<string | null>;
+    writeFile(path: string, content: string, mode?: number): Promise<void>;
+    removeFile(path: string): Promise<void>;
+    ensureDir(path: string, mode?: number): Promise<void>;
+}
+interface ReconcileContext {
+    exec: Executor;
+    fs: FileSystemPort;
+    /**
+     * Conveyor pods currently running here, or null when that could not be
+     * determined. A disruptive step is unsafe above zero AND unsafe on null —
+     * "I could not ask" is not "nothing is running".
+     */
+    runningConveyorPods: number | null;
+}
+interface ReconcileResult {
+    appliedVersion: number;
+    warnings: string[];
+    /**
+     * True when this pass restarted k3s: for new kubelet settings, or to load
+     * the local image registry's mirror. At most one restart per pass.
+     */
+    restartedK3s: boolean;
+    /** Kubelet flags left to the owner because their own config sets them. */
+    skippedKubeletFlags: string[];
+    /**
+     * The image-GC high threshold the kubelet is actually enforcing — ours, or
+     * the owner's when their own config.yaml set it and the drop-in stood down.
+     * Null when neither side named one. Reported so the heartbeat can warn about
+     * GC pressure against the number in force rather than the one we sent.
+     */
+    effectiveImageGcHighThreshold: number | null;
+    /** True when a wrong-valued PriorityClass was deleted AND put back. */
+    recreatedPriorityClass: boolean;
+    /** Empty pool namespaces of projects this machine no longer serves, removed. */
+    prunedNamespaces: string[];
+    /**
+     * Whether pod isolation is in force, while desired state asks for it (a
+     * host-runtime machine). Undefined otherwise. Reported on every heartbeat.
+     */
+    isolation?: {
+        applied: boolean;
+    };
+}
+declare function reconcile(ctx: ReconcileContext, desired: PersonalClusterDesiredState): Promise<ReconcileResult>;
+
 interface RegistryAuth {
     username?: string;
     password?: string;
@@ -434,7 +548,11 @@ declare function ownerConfiguredKeys(ownerConfig: string | null): Set<string>;
  * they chose, and last-writer-wins on their own file is exactly what this
  * module exists not to do.
  */
-declare function renderK3sDropIn(kubelet: PersonalClusterKubeletState, ownerConfig: string | null): DropInRenderResult;
+declare function renderK3sDropIn(kubelet: PersonalClusterKubeletState, ownerConfig: string | null, 
+/** False on an adopted k3s: its components stay as its owner set them. */
+options?: {
+    disableComponents?: boolean;
+}): DropInRenderResult;
 /**
  * @deprecated Use {@link renderK3sDropIn}. Kept as a named alias because the
  * package exports it and a published CLI may still import it by this name.
@@ -491,6 +609,27 @@ interface MachineState {
      * wanted" is not a safe rule to unpin on. Only what we pinned, we unpin.
      */
     pinnedImages?: string[];
+    /** When the in-cluster registry's garbage was last collected. */
+    lastRegistryGcAt?: string | null;
+    /**
+     * The size of k3s's containerd store at the last measurement, and when that
+     * was. Kept so the heartbeat reports it between the hourly measurements,
+     * and a daemon restart does not walk the store again straight away.
+     */
+    k3sStoreBytes?: number;
+    k3sStoreMeasuredAt?: string;
+    /**
+     * "host" once `conveyor-k3 host setup` or `host link` enrolled this machine
+     * as a host-runtime instance. Absent on a VM guest, including every state
+     * file written before the host runtime existed.
+     */
+    runtime?: "host";
+    /**
+     * True once setup installed this machine's k3s. Absent on a k3s setup found
+     * already installed, and in every state file written before the field
+     * existed. See {@link managesK3s}.
+     */
+    k3sInstalledByConveyor?: boolean;
 }
 declare function readState(fs: FileSystemPort$1): Promise<MachineState>;
 declare function writeState(fs: FileSystemPort$1, state: MachineState): Promise<void>;
@@ -503,7 +642,7 @@ declare function writeState(fs: FileSystemPort$1, state: MachineState): Promise<
  * help output below is part of the product: every verb states what it does to
  * their machine, and `uninstall` states what it does not.
  */
-declare const VERBS: readonly ["vm", "setup", "start", "stop", "status", "sync", "update", "registry", "runners", "uninstall", "daemon"];
+declare const VERBS: readonly ["vm", "host", "setup", "start", "stop", "status", "sync", "update", "registry", "runners", "uninstall", "daemon"];
 type Verb = (typeof VERBS)[number];
 declare function isVerb(value: string): value is Verb;
 interface ParsedArgs {
@@ -519,15 +658,17 @@ interface ParsedArgs {
  * this surface is nine verbs and six flags, not a general CLI framework.
  */
 declare function parseArgs(argv: readonly string[]): ParsedArgs;
-declare const HELP = "conveyor-k3 \u2014 managed personal compute for Conveyor\n\nUsage: conveyor-k3 <command> [options]\n\nCommands:\n  vm                    Manage isolated compute on macOS or Linux.\n                        Run conveyor-k3 vm for host lifecycle commands.\n  setup                 Install and enrol this machine. Safe to re-run.\n  start                 Start the tunnel and the daemon.\n  stop                  Stop both, and tell Conveyor at once so your next\n                        build goes straight to project compute.\n  status [--json]       What is running, what Conveyor knows, and what is\n                        missing.\n  sync                  Re-read your settings from Conveyor and apply them.\n  update                Update conveyor-k3, cloudflared, and (when you have\n                        allowed it and nothing is running) k3s.\n  registry list         Which registry credentials are configured, and which\n                        ones your projects still need.\n  registry add <host>   Add one registry credential.\n                          --username <user>\n                          --password-stdin      read the password from stdin\n                          --no-restart          skip the required k3s restart\n  runners list          Which GitHub Actions runners this machine hosts, and\n                        whether each may import a locally baked image.\n  runners grant <user>\u2026 Let those runner users import a locally baked image\n                        into this node and pin it. Writes one file under\n                        /etc/sudoers.d, checked with visudo first. Needed only\n                        when a project has Bake Locally turned on.\n  uninstall             Remove Conveyor's units, environment, and state. Your\n                        k3s config, registries.yaml, and workloads are left\n                        alone.\n                          --purge-k3s --yes     also remove k3s itself\n  daemon                Run in the foreground (what the systemd unit calls).\n\nOptions:\n  --version             Print the version.\n  --help                Print this message.\n\nDocs: https://conveyor.rallycryapp.com/docs/guides/managed-personal-compute\n";
+declare const HELP = "conveyor-k3 \u2014 Personal Compute for Conveyor\n\nUsage: conveyor-k3 <command> [options]\n\nOne product, two runtimes. Pick the one that fits the machine:\n\nOn your computer or server:\n  vm                    Personal computer runtime: an isolated VM on macOS or\n                        Linux. Run conveyor-k3 vm for its commands.\n  host                  Dedicated server runtime: k3s and the daemon on this\n                        Linux machine, with no VM. Root only. Run\n                        conveyor-k3 host for its commands.\n\nInside a linked machine (the VM guest, or the server itself):\n  setup                 VM guest only: install and enrol this machine. Safe\n                        to re-run. On a server, use conveyor-k3 host setup.\n  start                 Start the tunnel and the daemon.\n  stop                  Stop both, and tell Conveyor at once so your next\n                        build goes straight to project compute.\n  status [--json]       What is running, what Conveyor knows, and what is\n                        missing.\n  sync                  Re-read your settings from Conveyor and apply them.\n  update                Update conveyor-k3, cloudflared, and (when you have\n                        allowed it and nothing is running) k3s.\n  registry list         Which registry credentials are configured, and which\n                        ones your projects still need.\n  registry add <host>   Add one registry credential.\n                          --username <user>\n                          --password-stdin      read the password from stdin\n                          --no-restart          skip the required k3s restart\n  registry gc           Delete superseded shadow-bake images from the image\n                        registry inside this cluster. Runs daily on its own,\n                        and only while no Conveyor pod or bake is running.\n                          --dry-run             list what it would delete\n  runners list          Which GitHub Actions runners this machine hosts, and\n                        whether each may import a locally baked image.\n  runners grant <user>\u2026 Let those runner users import a locally baked image\n                        into this node and pin it. Writes one file under\n                        /etc/sudoers.d, checked with visudo first. Needed only\n                        when a project has Bake Locally turned on.\n  uninstall             VM guest only: remove Conveyor's units, environment,\n                        state, and image registry. Your k3s config, your own\n                        registries.yaml entries, your workloads, and the\n                        registry's data are left alone. On a server, use\n                        conveyor-k3 host uninstall: it also removes the\n                        device key.\n                          --purge-k3s --yes     also remove k3s itself and the\n                                                registry's data\n  daemon                Run in the foreground (what the systemd unit calls).\n\nOptions:\n  --version             Print the version.\n  --help                Print this message.\n\nDocs: https://conveyor.rallycryapp.com/docs/guides/managed-personal-compute\n";
 
 /**
- * `conveyor-k3 registry add|list` — the one place this CLI writes
- * `registries.yaml`.
- *
- * The reconcile loop never touches that file. Only an explicit command does,
- * it takes a timestamped backup first, and it merges rather than templates —
- * so a machine pulling through its own LAN mirror keeps that mirror, its TLS
+ * `conveyor-k3 registry add|list|gc` — where an owner adds registry
+ * credentials, and cleans up the registry inside the cluster.
+ *
+ * `add` is the one command that writes a credential into `registries.yaml`.
+ * The reconcile loop writes that file for one reason only: the mirror for the
+ * in-cluster registry's host (`lib/registries.ts` lists both writers). Both
+ * take a timestamped backup first, and both merge rather than template — so a
+ * machine pulling through its own LAN mirror keeps that mirror, its TLS
  * settings, and every other host it had configured.
  *
  * A restart is required and is not optional: k3s reads `registries.yaml` at
@@ -568,23 +709,12 @@ declare function registryList(ports: RegistryPorts, requiredHosts: string[]): Pr
  */
 declare function renderRegistryAuthSummary(missing: string[]): string[];
 
-/**
- * `conveyor-k3 uninstall` — remove exactly what Conveyor put on this machine.
- *
- * Everything this CLI created carries a `conveyor-k3` name and lives under
- * `/etc/conveyor` or `/var/lib/conveyor-k3`, which is what makes a precise
- * removal possible. Nothing else is touched: not the owner's `config.yaml`,
- * not `registries.yaml`, not their workloads.
- *
- * k3s itself is NOT removed by default. On most machines it predates us, or
- * the owner wants to keep it — so removing it is `--purge-k3s`, and even then
- * only after an explicit confirmation.
- */
-
 interface UninstallPorts {
     exec: Executor;
     fs: FileSystemPort$1;
     log: (line: string) => void;
+    /** Injected so the `registries.yaml` backup's name is deterministic in tests. */
+    now?: () => Date;
 }
 interface UninstallOptions {
     /** Also run k3s-uninstall.sh. Requires `confirmed`. */
@@ -644,6 +774,12 @@ interface UpdateBinaries {
 }
 interface UpdateDecisionInput {
     autoUpgradeK3s: boolean;
+    /**
+     * False on a server whose k3s setup did not install (`managesK3s`): the
+     * installer would turn off the owner's traefik and servicelb. Absent reads
+     * as true, which is every VM guest.
+     */
+    managesK3s?: boolean;
     /** Null when the count could not be read — treated exactly like "busy". */
     runningConveyorPods: number | null;
     installedK3s: [number, number] | null;
@@ -694,6 +830,27 @@ declare function runUpdate(ports: UpdatePorts, decision: K3sUpgradeDecision, cha
 declare function parseK3sVersion(output: string): [number, number] | null;
 declare function meetsK3sMinimum(version: [number, number] | null): boolean;
 
+/**
+ * Capacity profiles: how many guest connections a VM's host relays at once, how
+ * much one connection may carry, and how fast the boot disk may go.
+ *
+ * Pure and import-free on purpose: the QEMU wrapper bundle (dist/vm-qemu.js)
+ * includes it, and that bundle starts once for every guest connection.
+ */
+/** `custom` is any set of values that no longer matches a preset. */
+type CapacityProfile = "default" | "server" | "custom";
+/** What the host enforces, in bytes, rendered into network.json as `limits`. */
+interface CapacityLimits {
+    schema: 1;
+    profile: CapacityProfile;
+    relaySlots: number;
+    /** Slots that only control-plane relays (the tunnel and the daemon) may take. */
+    reservedRelaySlots: number;
+    relayMaxBytes: number;
+    diskBytesPerSecond: number;
+    diskIops: number;
+}
+
 interface NetworkEndpoint {
     host: string;
     ports: number[];
@@ -706,6 +863,8 @@ interface ResolvedNetworkHost {
     /** Host-resolved, pinned, globally-routable IPv4 address. */
     address: string;
     ports: number[];
+    /** A control-plane destination, whose relays may use the reserved slots. */
+    reserve?: "control";
 }
 interface GuestSrvRecord {
     name: string;
@@ -719,6 +878,13 @@ interface ResolvedNetwork {
     hosts: ResolvedNetworkHost[];
     /** Static SRV answers needed by cloudflared's documented edge discovery. */
     srv: GuestSrvRecord[];
+    /**
+     * Daemon-only aliases of the Conveyor API. Guest DNS never serves them, so
+     * only the daemon, which dials them by address, can use the reserved slots.
+     */
+    control?: ResolvedNetworkHost[];
+    /** What the host enforces. Absent in a document an older CLI wrote. */
+    limits?: CapacityLimits;
 }
 /** Alias used by the VM host manager. */
 type NetworkPolicy = ResolvedNetwork;
@@ -776,11 +942,72 @@ interface QemuNetworkPolicy extends ResolvedNetwork {
 /** Host-only information used to tie QEMU file endpoints to one Lima instance. */
 interface QemuPolicyContext {
     instanceDir?: string;
+    /** The Lima instance name, which Lima passes as `-name lima-<name>`. */
+    vmName?: string;
+    /** The boot-disk throttle, from the network policy's capacity limits. */
+    disk?: {
+        bps: number;
+        iops: number;
+    };
 }
-/** Rewrites only a complete, known Lima QEMU profile; every unknown input fails closed. */
-declare function rewriteQemuArgs(args: string[], network: QemuNetworkPolicy, ncPath?: string, context?: QemuPolicyContext): string[];
+/**
+ * Rewrites only a complete, known Lima QEMU profile; every unknown input fails
+ * closed. The network's capacity limits set the boot-disk throttle.
+ */
+declare function rewriteQemuArgs(args: string[], network: QemuNetworkPolicy, ncPath?: string, hostContext?: QemuPolicyContext): string[];
 
+/** The largest whole-GiB guest whose host cost (see vmHostMemoryGiB) fits in the budget. */
+declare function maximumGuestMemoryGiBWithin(budgetGiB: number, relaySlots?: number): number;
 /** Reserve 25% of physical host RAM after accounting for VM overhead. */
-declare function maximumGuestMemoryGiB(hostBytes: number): number;
+declare function maximumGuestMemoryGiB(hostBytes: number, relaySlots?: number): number;
+
+/** `--instance` omitted or `default`: the original VM, whose paths never move. */
+declare const DEFAULT_INSTANCE = "default";
+/** The `--instance` flag's value. Omitted or `default` selects the default VM. */
+declare function parseInstanceName(value: unknown): string;
+
+/** One VM's host paths. The default VM keeps its original root. */
+declare function hostPaths(instance?: string): {
+    root: string;
+    limaHome: string;
+    state: string;
+    network: string;
+    template: string;
+    wrapper: string;
+    wrapperJs: string;
+    applied: string;
+    guard: string;
+    startRequest: string;
+    policyTransaction: string;
+    lock: string;
+    /** Written by an owner stop, so a supervising service does not restart the VM. */
+    stopIntent: string;
+    instance: string;
+    vmName: string;
+    instanceDir: string;
+    limaConfig: string;
+};
+/** Every host path of one VM under `root`. Pure, so tests inject a temporary root. */
+declare function pathsForRoot(root: string, instance?: string): {
+    root: string;
+    limaHome: string;
+    state: string;
+    network: string;
+    template: string;
+    wrapper: string;
+    wrapperJs: string;
+    applied: string;
+    guard: string;
+    startRequest: string;
+    policyTransaction: string;
+    lock: string;
+    /** Written by an owner stop, so a supervising service does not restart the VM. */
+    stopIntent: string;
+    instance: string;
+    vmName: string;
+    instanceDir: string;
+    limaConfig: string;
+};
+type HostPaths = ReturnType<typeof pathsForRoot>;
 
-export { ClusterConnection, type ClusterConnectionConfig, ClusterDaemon, CommandError, type CrictlImage, type DaemonPorts, type Executor, type FileSystemPort$1 as FileSystemPort, type GuestDnsProvision, type GuestSrvRecord, HELP, type ImageInventory, K3S_DISABLED_COMPONENTS, K3S_INSTALL_EXEC, type K3sUpgradeDecision, type MachineState, type NetworkEndpoint, type NetworkPolicy, type QemuNetworkPolicy, type ReconcileContext, type ReconcileResult, type RegistriesFile, type ResolvedNetwork, type ResolvedNetworkHost, type SRVLookup, type UninstallResult, type UnitRenderOptions, VERBS, type Verb, cloudflaredSrvRecords, collectHeartbeat, configuredAuthHosts, countRunningConveyorPods, createMemoryFileSystem, decideK3sUpgrade, isGloballyRoutableIPv4, isVerb, maximumGuestMemoryGiB, meetsK3sMinimum, missingAuthHosts, nodeFileSystem, ownerConfiguredKeys, ownerConfiguredKubeletFlags, parseArgs, parseK3sVersion, parseRegistries, pruneStrandedImages, readImageInventory, readState, reconcile, registryAdd, registryList, renderAllUnits, renderGuestDnsProvision, renderK3sDropIn, renderKubeletDropIn, renderRegistryAuthSummary, resolveCloudflaredSrvRecords, resolveNetwork, rewriteQemuArgs, runOrThrow, runUpdate, selectStrandedImages, serializeRegistries, spawnExecutor, uninstall, upsertRegistryAuth, warmImages, writeState };
+export { ClusterConnection, type ClusterConnectionConfig, ClusterDaemon, CommandError, type CrictlImage, DEFAULT_INSTANCE, type DaemonPorts, type Executor, type FileSystemPort$1 as FileSystemPort, type GuestDnsProvision, type GuestSrvRecord, HELP, type HostPaths, type ImageInventory, K3S_DISABLED_COMPONENTS, K3S_INSTALL_EXEC, type K3sUpgradeDecision, type MachineState, type NetworkEndpoint, type NetworkPolicy, type QemuNetworkPolicy, type ReconcileContext, type ReconcileResult, type RegistriesFile, type ResolvedNetwork, type ResolvedNetworkHost, type SRVLookup, type UninstallResult, type UnitRenderOptions, VERBS, type Verb, cloudflaredSrvRecords, collectHeartbeat, configuredAuthHosts, countRunningConveyorPods, createMemoryFileSystem, decideK3sUpgrade, hostPaths, isGloballyRoutableIPv4, isVerb, maximumGuestMemoryGiB, maximumGuestMemoryGiBWithin, meetsK3sMinimum, missingAuthHosts, nodeFileSystem, ownerConfiguredKeys, ownerConfiguredKubeletFlags, parseArgs, parseInstanceName, parseK3sVersion, parseRegistries, pruneStrandedImages, readImageInventory, readState, reconcile, registryAdd, registryList, renderAllUnits, renderGuestDnsProvision, renderK3sDropIn, renderKubeletDropIn, renderRegistryAuthSummary, resolveCloudflaredSrvRecords, resolveNetwork, rewriteQemuArgs, runOrThrow, runUpdate, selectStrandedImages, serializeRegistries, spawnExecutor, uninstall, upsertRegistryAuth, warmImages, writeState };