@skrr-ai/cli 0.1.25 → 0.1.27

package/dist/lib/dedicated-machines.js

@@ -1,20 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEDICATED_LEASE_ACTIONS = void 0;
+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.dedicatedRuntimeCreateInput = dedicatedRuntimeCreateInput;
+exports.isDedicatedRepositoryRef = isDedicatedRepositoryRef;
 exports.createDedicatedRuntime = createDedicatedRuntime;
 exports.listDedicatedRuntimes = listDedicatedRuntimes;
 exports.getDedicatedRuntime = getDedicatedRuntime;
 exports.performDedicatedLeaseAction = performDedicatedLeaseAction;
 exports.growDedicatedRuntime = growDedicatedRuntime;
+exports.restoreDeletedDedicatedRuntime = restoreDeletedDedicatedRuntime;
+exports.setDedicatedRuntimeSpendingLimit = setDedicatedRuntimeSpendingLimit;
 exports.closeDedicatedRuntimeIncidentHold = closeDedicatedRuntimeIncidentHold;
 exports.destroyDedicatedRuntime = destroyDedicatedRuntime;
+exports.execDedicatedRuntime = execDedicatedRuntime;
+exports.startDedicatedRuntimeExecution = startDedicatedRuntimeExecution;
+exports.observeDedicatedRuntimeExecution = observeDedicatedRuntimeExecution;
+exports.readDedicatedRuntimeFileChunk = readDedicatedRuntimeFileChunk;
+exports.writeDedicatedRuntimeFileChunk = writeDedicatedRuntimeFileChunk;
+exports.parseDedicatedCopyEndpoints = parseDedicatedCopyEndpoints;
 exports.dedicatedLeaseId = dedicatedLeaseId;
 exports.dedicatedLeaseState = dedicatedLeaseState;
 exports.dedicatedLeaseDisplayName = dedicatedLeaseDisplayName;
+exports.formatUsdCents = formatUsdCents;
+exports.dedicatedSpendSummary = dedicatedSpendSummary;
+exports.describeDedicatedDeletion = describeDedicatedDeletion;
+exports.describeDedicatedLease = describeDedicatedLease;
+exports.dedicatedLeaseHarnesses = dedicatedLeaseHarnesses;
+exports.dedicatedLeaseIdForDaemon = dedicatedLeaseIdForDaemon;
+exports.dedicatedTerminalHarness = dedicatedTerminalHarness;
+exports.selectDedicatedAttachHarness = selectDedicatedAttachHarness;
+exports.dedicatedCatalogFromProducts = dedicatedCatalogFromProducts;
+exports.dedicatedRuntimeApiErrorCode = dedicatedRuntimeApiErrorCode;
 exports.formatDedicatedRuntimeApiError = formatDedicatedRuntimeApiError;
 const api_fetch_1 = require("./api-fetch");
-const harnesses_1 = require("./harnesses");
+const edge_error_page_1 = require("./edge-error-page");
 exports.DEDICATED_LEASE_ACTIONS = [
     'start',
     'stop',
@@ -22,6 +41,7 @@ exports.DEDICATED_LEASE_ACTIONS = [
     'snapshot',
     'health-check',
 ];
+exports.DEDICATED_MACHINE_PRODUCT = 'dedicated-machine';
 /**
  * Flags in, request body out — and the point of it being a function is the
  * OMISSION.
@@ -36,6 +56,7 @@ exports.DEDICATED_LEASE_ACTIONS = [
  * means the same bug was invisible in them.
  */
 function dedicatedRuntimeCreateInput(input) {
+    const repositoryRef = input.repositoryRef?.trim();
     return {
         requestId: input.requestId,
         displayName: input.displayName,
@@ -47,45 +68,102 @@ function dedicatedRuntimeCreateInput(input) {
         ...(input.backupProfile
             ? { backupProfile: input.backupProfile }
             : {}),
+        ...(repositoryRef ? { repositoryRef } : {}),
         ...(input.workspaceId ? { workspaceId: input.workspaceId } : {}),
     };
 }
+/**
+ * The shapes the server's repository parser accepts: `owner/repo`,
+ * `github.com/owner/repo`, or an https URL to it, optionally ending in `.git`.
+ *
+ * This is a typo catcher, not the authority. The server re-parses the value and
+ * decides whether the owner's GitHub App installation covers it; checking the
+ * shape here only turns "create failed" into "that is not a repository" before a
+ * billable request is sent.
+ */
+function isDedicatedRepositoryRef(value) {
+    return /^(?:https?:\/\/)?(?:github\.com\/)?[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?(?:\.git)?$/i.test(value.trim());
+}
+// Takes the finished path rather than composing one from a suffix, so the route
+// each call reaches is a literal at the call site. `cli/src/__tests__/helpers/
+// api-surface.ts` reads coverage out of the source, and a path assembled inside a
+// builder is invisible to it: exec, files/read and files/write were all reported
+// unreachable by domain-api-parity while being perfectly reachable, which is the
+// reading that trains people to allowlist things that are fine. Same shape as
+// `withQuery` on the `request.*` side.
+//
+// Query parameters therefore go in `query`, never into the literal: the coverage
+// reader matches the literal against the route table, and a `?name=` inside it
+// makes the endpoint read as unreachable.
+function withDedicatedScope(path, scope, query = {}) {
+    const params = Object.entries(query);
+    if (scope.workspaceId)
+        params.push(['workspaceId', scope.workspaceId]);
+    if (params.length === 0)
+        return path;
+    const separator = path.includes('?') ? '&' : '?';
+    return `${path}${separator}${params
+        .map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`)
+        .join('&')}`;
+}
 async function createDedicatedRuntime(input) {
     const { requestId, workspaceId, ...body } = input;
-    if (workspaceId) {
-        return (0, api_fetch_1.apiFetch)(`/api/machines/dedicated?workspaceId=${encodeURIComponent(workspaceId)}`, {
-            method: 'POST',
-            body,
-            headers: { 'Idempotency-Key': requestId },
-        });
-    }
-    return (0, api_fetch_1.apiFetch)('/api/machines/dedicated', {
-        method: 'POST',
-        body,
-        headers: { 'Idempotency-Key': requestId },
-    });
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope('/api/machines/dedicated', { workspaceId }), { method: 'POST', body, headers: { 'Idempotency-Key': requestId } });
 }
 async function listDedicatedRuntimes(options = {}) {
-    return (0, harnesses_1.listHarnessLeases)({
-        ...options,
-        machineProduct: 'dedicated-machine',
-    });
+    const query = new URLSearchParams();
+    if (options.limit)
+        query.set('limit', String(options.limit));
+    if (options.state)
+        query.set('state', options.state);
+    query.set('machineProduct', exports.DEDICATED_MACHINE_PRODUCT);
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/leases?${query.toString()}`, options));
 }
-async function getDedicatedRuntime(leaseId) {
-    return (0, harnesses_1.getHarnessLease)(leaseId);
+async function getDedicatedRuntime(leaseId, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/leases/${encodeURIComponent(leaseId)}`, scope));
 }
-async function performDedicatedLeaseAction(leaseId, action) {
-    return (0, harnesses_1.performHarnessLeaseAction)(leaseId, action);
+async function performDedicatedLeaseAction(leaseId, action, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/leases/${encodeURIComponent(leaseId)}/actions/${encodeURIComponent(action)}`, scope), { method: 'POST' });
 }
 async function growDedicatedRuntime(leaseId, storageGb, options = {}) {
-    return (0, api_fetch_1.apiFetch)(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/storage`, {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/storage`, options), {
         method: 'POST',
         body: { storageGb },
         ...(options.requestId ? { headers: { 'Idempotency-Key': options.requestId } } : {}),
     });
 }
+/**
+ * Restore a deleted Dedicated Runtime into a NEW machine, from the final recovery
+ * point its deletion kept. Only inside the deletion's recovery window, and once
+ * per deletion; the response's `lease` is the new machine. The cap defaults to
+ * the deleted machine's.
+ */
+async function restoreDeletedDedicatedRuntime(leaseId, options = {}) {
+    const body = {};
+    if (options.displayName)
+        body.displayName = options.displayName;
+    if (options.monthlySpendingLimitCents !== undefined) {
+        body.monthlySpendingLimitCents = options.monthlySpendingLimitCents;
+    }
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/restore`, options), {
+        method: 'POST',
+        body,
+        ...(options.requestId ? { headers: { 'Idempotency-Key': options.requestId } } : {}),
+    });
+}
+/**
+ * Change the monthly spending cap of one lease.
+ *
+ * The route accepts `spendingLimitCents` and nothing else: who pays is decided
+ * at create and there is no API that moves it. A cap below what the month has
+ * already spent (or is projected to) is refused rather than stopping the machine
+ * on the next reconciler pass.
+ */
+async function setDedicatedRuntimeSpendingLimit(leaseId, spendingLimitCents, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/leases/${encodeURIComponent(leaseId)}/billing`, scope), { method: 'PATCH', body: { spendingLimitCents } });
+}
 async function closeDedicatedRuntimeIncidentHold(leaseId, options = {}) {
-    return (0, api_fetch_1.apiFetch)(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/incident-hold/close`, {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/incident-hold/close`, options), {
         method: 'POST',
         body: {},
         ...(options.requestId ? { headers: { 'Idempotency-Key': options.requestId } } : {}),
@@ -95,7 +173,86 @@ async function destroyDedicatedRuntime(leaseId, options = {}) {
     const query = options.retentionIntent
         ? `?retentionIntent=${encodeURIComponent(options.retentionIntent)}`
         : '';
-    return (0, api_fetch_1.apiFetch)(`/api/machines/leases/${encodeURIComponent(leaseId)}${query}`, { method: 'DELETE' });
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/leases/${encodeURIComponent(leaseId)}${query}`, options), { method: 'DELETE' });
+}
+/** The server's ceiling for one exec; documented beside the route. */
+exports.DEDICATED_EXEC_MAX_TIMEOUT_MS = 10 * 60 * 1000;
+/** The server's default when a command names no timeout. */
+exports.DEDICATED_EXEC_DEFAULT_TIMEOUT_MS = 2 * 60 * 1000;
+/**
+ * Run one command on the machine as the workload user, in ONE request.
+ *
+ * The synchronous route, kept for servers that predate `executions`. It holds
+ * the request open while the command runs, so behind CloudFront a command that
+ * runs past ~60 s is cut off at the edge while it keeps running (OSK-8705).
+ * `runDedicatedExec` (dedicated-exec.ts) starts and observes instead, and falls
+ * back to this only when the server has no `executions` route.
+ *
+ * Not idempotent and not retried: `apiFetch` gives each call a fresh
+ * idempotency key, which is the rule for an unfenced write — running the same
+ * command twice is two intents even when the text is identical.
+ */
+async function execDedicatedRuntime(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/exec`, scope), {
+        method: 'POST',
+        body: {
+            command: input.command,
+            ...(input.cwd ? { cwd: input.cwd } : {}),
+            ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+        },
+    });
+}
+/**
+ * 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 —
+ * so a retry after a lost response never runs the command twice.
+ */
+async function startDedicatedRuntimeExecution(leaseId, input, options) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/executions`, options), {
+        method: 'POST',
+        body: {
+            command: input.command,
+            ...(input.cwd ? { cwd: input.cwd } : {}),
+            ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+        },
+        headers: { 'X-Idempotency-Key': options.requestId },
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+}
+/** Read a started command, letting the server hold the answer up to `waitMs` for it to end. */
+async function observeDedicatedRuntimeExecution(leaseId, executionId, options) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/executions/${encodeURIComponent(executionId)}`, options, { waitMs: String(Math.max(0, Math.floor(options.waitMs))) }), options.signal ? { signal: options.signal } : {});
+}
+/** Mirrors the daemon's bounds (daemon/src/tools/file-transfer.ts). */
+exports.DEDICATED_FILE_CHUNK_BYTES = 512 * 1024;
+exports.DEDICATED_FILE_MAX_BYTES = 64 * 1024 * 1024;
+async function readDedicatedRuntimeFileChunk(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/files/read`, scope), { method: 'POST', body: input });
+}
+async function writeDedicatedRuntimeFileChunk(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/files/write`, scope), { method: 'POST', body: input });
+}
+const REMOTE_ENDPOINT = /^(rtl_[A-Za-z0-9_-]{1,80}):(.+)$/;
+/**
+ * `cp <src> <dst>` where exactly one side is `<lease-id>:<path>`.
+ *
+ * The remote side is recognised by the lease id prefix rather than by "has a
+ * colon", so a Windows path (`C:\\build\\out.zip`) or a local file whose name
+ * contains a colon is never mistaken for a machine.
+ */
+function parseDedicatedCopyEndpoints(source, destination) {
+    const src = REMOTE_ENDPOINT.exec(source);
+    const dst = REMOTE_ENDPOINT.exec(destination);
+    if (src && dst) {
+        throw new Error('Copy between two machines is not supported; one side must be a local path.');
+    }
+    if (!src && !dst) {
+        throw new Error('One side must name the machine, as <lease-id>:<path>.');
+    }
+    if (src) {
+        return { direction: 'download', leaseId: src[1], remotePath: src[2], localPath: destination };
+    }
+    return { direction: 'upload', localPath: source, leaseId: dst[1], remotePath: dst[2] };
 }
 function dedicatedLeaseId(lease) {
     return String(lease?.id ?? '');
@@ -106,6 +263,268 @@ function dedicatedLeaseState(lease) {
 function dedicatedLeaseDisplayName(lease) {
     return lease?.displayName ? String(lease.displayName) : '-';
 }
+/** `$12.34` — cents are what the API speaks; dollars are what a person reads. */
+function formatUsdCents(cents) {
+    if (typeof cents !== 'number' || !Number.isFinite(cents))
+        return '-';
+    const sign = cents < 0 ? '-' : '';
+    return `${sign}$${(Math.abs(cents) / 100).toFixed(2)}`;
+}
+/** `this month $1.23 of $500.00 cap`, or why that sentence cannot be written. */
+function dedicatedSpendSummary(lease) {
+    const billing = lease.billing;
+    if (!billing)
+        return '-';
+    const cap = billing.monthlySpendLimitCents ?? billing.spendingLimitCents;
+    if (billing.spendStatusUnavailable) {
+        return `spend unavailable right now · cap ${formatUsdCents(cap)}`;
+    }
+    const spent = billing.currentMonthSpendCents;
+    const projected = billing.projectedCurrentMonthSpendCents;
+    const parts = [`${formatUsdCents(spent)} this month of ${formatUsdCents(cap)} cap`];
+    if (typeof projected === 'number' && projected !== spent) {
+        parts.push(`projected ${formatUsdCents(projected)}`);
+    }
+    if (billing.spendingLimitExceeded) {
+        parts.push('OVER CAP — compute is stopped, files are kept');
+    }
+    return parts.join(' · ');
+}
+/**
+ * The human rendering of `machines dedicated show`, as lines.
+ *
+ * Pure so it can be pinned without a server. Every field is optional because a
+ * lease that is still `requested` has no resources, daemon or spend yet, and a
+ * missing value is omitted rather than printed as a column of dashes.
+ */
+/** One line saying what a deletion still allows. */
+function describeDedicatedDeletion(deletion, leaseId) {
+    if (deletion.restoredToLeaseId) {
+        return `restored into ${deletion.restoredToLeaseId}`;
+    }
+    if (deletion.status === 'completed') {
+        return `permanently deleted${deletion.completedAt ? ` ${deletion.completedAt}` : ''}; no copy remains`;
+    }
+    if (deletion.status === 'purging') {
+        return 'recovery window closed; every copy is being deleted';
+    }
+    if (deletion.restorable) {
+        return `restorable until ${deletion.recoverableUntil} — \`skrr machines dedicated restore ${leaseId || '<lease-id>'}\``;
+    }
+    return 'nothing to restore; every copy is deleted when the window closes';
+}
+function describeDedicatedLease(lease, harnesses = []) {
+    const lines = [dedicatedLeaseDisplayName(lease)];
+    const row = (label, value) => {
+        if (value === undefined || value === null || value === '')
+            return;
+        lines.push(`  ${label.padEnd(13)}${value}`);
+    };
+    row('id', dedicatedLeaseId(lease));
+    row('state', lease.stateReason
+        ? `${dedicatedLeaseState(lease)} (${lease.stateReason})`
+        : dedicatedLeaseState(lease));
+    const resources = lease.resources || {};
+    const size = [
+        resources.sizePreset,
+        resources.cpu ? `${resources.cpu} vCPU` : '',
+        resources.memoryGb ? `${resources.memoryGb} GiB RAM` : '',
+        resources.regionClass,
+    ]
+        .filter(Boolean)
+        .join(' · ');
+    row('size', size);
+    const storage = lease.storage || {};
+    const disk = [
+        resources.storageGb ? `${resources.storageGb} GiB` : '',
+        storage.retentionClass ? `retention ${storage.retentionClass}` : '',
+        storage.backupProfile ? `backup ${storage.backupProfile}` : '',
+    ]
+        .filter(Boolean)
+        .join(' · ');
+    row('workspace', disk);
+    row('last backup', storage.lastBackupAt);
+    const image = [resources.imageVersion || lease.daemon?.imageVersion].filter(Boolean).join('');
+    row('image', image);
+    if (lease.daemon?.version || lease.daemon?.lastHeartbeatAt) {
+        row('daemon', [
+            lease.daemon.version ? `skrrd ${lease.daemon.version}` : '',
+            lease.daemon.lastHeartbeatAt ? `heartbeat ${lease.daemon.lastHeartbeatAt}` : '',
+        ]
+            .filter(Boolean)
+            .join(' · '));
+    }
+    const health = lease.health;
+    if (health && typeof health.assignable === 'boolean') {
+        row('health', health.assignable
+            ? 'can take work'
+            : `not assignable${health.reasons?.length ? `: ${[...new Set(health.reasons)].join(', ')}` : ''}`);
+    }
+    row('spend', lease.billing ? dedicatedSpendSummary(lease) : undefined);
+    if (storage.deleteAfter || storage.unpaidSince) {
+        row('deletion', [
+            storage.unpaidSince ? `unpaid since ${storage.unpaidSince}` : '',
+            storage.deletionNoticeAt ? `notice ${storage.deletionNoticeAt}` : '',
+            storage.deleteAfter ? `workspace deleted after ${storage.deleteAfter}` : '',
+        ]
+            .filter(Boolean)
+            .join(' · '));
+    }
+    const deletion = storage.deletion;
+    if (deletion?.status) {
+        row('deleted', describeDedicatedDeletion(deletion, dedicatedLeaseId(lease)));
+    }
+    row('restored from', lease.recovery?.restoredFromLeaseId);
+    const hold = lease.recovery?.incidentHold;
+    if (hold?.status === 'open') {
+        row('incident', `hold open since ${hold.heldAt || '?'} — the failed source volume is billed until \`incident-close\``);
+    }
+    const engines = dedicatedLeaseHarnesses(lease, harnesses);
+    if (engines.length > 0) {
+        row('engines', engines.map((harness) => `${harness.provider} (${harness.status || 'unknown'})`).join(', '));
+    }
+    // What the PRODUCT supports, not what this state allows: an archived lease
+    // still lists `start`. Labelled so nobody scripts against it as the latter.
+    const capabilities = Object.entries(lease.lifecycleCapabilities || {})
+        .filter(([, allowed]) => allowed)
+        .map(([name]) => name);
+    row('supports', capabilities.join(', '));
+    row('support ref', lease.supportReference);
+    return lines;
+}
+/**
+ * Every harness row a Dedicated Runtime lease's daemon registered, freshest
+ * first.
+ *
+ * A lease payload names no daemon (provider and daemon ids are deliberately
+ * absent), so the join goes the other way: each row a guest daemon registers
+ * carries `metadata.machineLeaseId` and `metadata.machineProduct`. One daemon
+ * writes one row PER ENGINE it announces (claude, codex, sky-code, or `oversky`
+ * when it announces none), all sharing the daemon id.
+ */
+function dedicatedLeaseHarnesses(lease, harnesses) {
+    const seenAt = (harness) => Date.parse(harness.lastSeenAt || '') || 0;
+    return harnesses
+        .filter((harness) => {
+        const metadata = harness.metadata || {};
+        return (metadata.machineProduct === exports.DEDICATED_MACHINE_PRODUCT &&
+            metadata.machineLeaseId === lease.id);
+    })
+        .sort((a, b) => seenAt(b) - seenAt(a));
+}
+/**
+ * The lease of the machine this process is running on, from the harness rows.
+ *
+ * Nothing in a workload process's environment names its lease — the daemon's
+ * environment (lease, generation, credentials) sits on the other side of the uid
+ * split by design. The CLI hand-off descriptor the daemon publishes to the
+ * workload group does carry the daemon's id, and every harness row that daemon
+ * registered carries `metadata.machineLeaseId`. Joining the two answers "which
+ * machine am I" with no new daemon surface.
+ */
+function dedicatedLeaseIdForDaemon(daemonId, harnesses) {
+    if (!daemonId)
+        return null;
+    const leaseIds = new Set(harnesses
+        .filter((harness) => harness.daemonId === daemonId &&
+        harness.metadata?.machineProduct === exports.DEDICATED_MACHINE_PRODUCT &&
+        typeof harness.metadata?.machineLeaseId === 'string')
+        .map((harness) => String(harness.metadata?.machineLeaseId)));
+    // One daemon serves one lease. Two would mean rows from a replaced
+    // generation disagree, and guessing between them is how `self` would act on
+    // the wrong machine.
+    return leaseIds.size === 1 ? [...leaseIds][0] : null;
+}
+/**
+ * The row an interactive terminal opens on: online, local, with a daemon.
+ *
+ * Any engine row reaches the same shell — they share the daemon — so the
+ * freshest one wins. The terminal relay's own access check refuses a row that
+ * is not local or has no daemon, so offering one here would only move the
+ * refusal later.
+ */
+function dedicatedTerminalHarness(lease, harnesses) {
+    return (dedicatedLeaseHarnesses(lease, harnesses).find((harness) => harness.status === 'online' &&
+        Boolean(harness.daemonId) &&
+        (harness.harnessLocation === undefined || harness.harnessLocation === 'local')) || null);
+}
+/**
+ * The harness row an agent should be attached to, for `attach`.
+ *
+ * Choosing a row also chooses the ENGINE the agent's turns run under, so an
+ * ambiguous choice is refused with the options named rather than guessed. A
+ * row need not be online to be attached — a stopped machine keeps its rows —
+ * but the error says so when it is not.
+ */
+function selectDedicatedAttachHarness(lease, harnesses, engine) {
+    const rows = dedicatedLeaseHarnesses(lease, harnesses);
+    if (rows.length === 0) {
+        return {
+            error: `No harness is registered for ${lease.id} yet. A machine's daemon registers one when it ` +
+                'first connects; start the machine, wait for it to be ready, and try again.',
+        };
+    }
+    const providers = [...new Set(rows.map((row) => row.provider))];
+    if (engine) {
+        const match = rows.find((row) => row.provider === engine);
+        if (!match) {
+            return {
+                error: `${lease.id} has no "${engine}" engine. Registered: ${providers.join(', ')}.`,
+            };
+        }
+        return { harness: match };
+    }
+    if (providers.length > 1) {
+        return {
+            error: `${lease.id} runs more than one engine (${providers.join(', ')}); the one you attach is ` +
+                'the one the agent works under. Pass --engine <name>.',
+        };
+    }
+    return { harness: rows[0] };
+}
+/**
+ * The Dedicated Runtime row of `GET /api/machines/products`, reduced to what a
+ * caller needs to choose `create` flags.
+ *
+ * `--size-preset` has no client-side list of values on purpose — presets are
+ * gated by server flags — so this is where a caller learns which ones exist.
+ */
+function dedicatedCatalogFromProducts(payload) {
+    const products = Array.isArray(payload)
+        ? payload
+        : (payload?.products ?? []);
+    const product = products.find((row) => row?.machineProduct === exports.DEDICATED_MACHINE_PRODUCT || row?.id === exports.DEDICATED_MACHINE_PRODUCT);
+    if (!product)
+        return null;
+    const configuration = (product.configuration || {});
+    const billing = (product.billing || {});
+    const presentation = (billing.presentation || {});
+    const sizeCatalog = Array.isArray(configuration.sizePresetCatalog)
+        ? configuration.sizePresetCatalog
+        : (Array.isArray(configuration.sizePresets) ? configuration.sizePresets : []).map((id) => ({ id }));
+    const availability = typeof product.availability === 'string'
+        ? product.availability
+        : String(product.availability?.status || 'unknown');
+    return {
+        availability,
+        ...(typeof product.disabledReason === 'string' && product.disabledReason
+            ? { disabledReason: product.disabledReason }
+            : {}),
+        sizes: sizeCatalog,
+        regionClasses: configuration.regionClasses || [],
+        ...(configuration.storage
+            ? { storage: configuration.storage }
+            : {}),
+        retentionClasses: configuration.retentionClasses || [],
+        backupProfiles: configuration.backupProfiles || [],
+        defaultMonthlySpendingLimitCents: billing.defaultMonthlySpendingLimitCents,
+        maxUserMonthlySpendingLimitCents: billing.maxUserMonthlySpendingLimitCents,
+        priceLines: Array.isArray(presentation.priceLines)
+            ? presentation.priceLines
+            : [],
+        ...(typeof presentation.headline === 'string' ? { headline: presentation.headline } : {}),
+    };
+}
 /**
  * Dedicated Runtime commands are unusually likely to meet a server that has
  * never heard of them.
@@ -140,6 +559,54 @@ function describeMissingEndpoint(err) {
         'the deployment — `skrr context` names the server it is talking to, and `skrr machines ' +
         'dedicated list` will still work if the feature is deployed at all.');
 }
+/**
+ * A lease that is not found is usually a SCOPE question, not a typo.
+ *
+ * Every lease lookup is `(owner, workspace)`: with a workspace selected the
+ * server searches only that workspace's leases, and without one only personal
+ * leases. So `not found` for an id the caller just created most often means the
+ * active workspace differs from the one the machine was created in.
+ */
+function describeLeaseNotFound(err) {
+    if (err.status !== 404)
+        return null;
+    try {
+        const parsed = JSON.parse(err.body || '');
+        if (parsed.code || parsed.error !== 'Machine lease not found')
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return ('Machine lease not found. Leases are looked up within one scope: your personal machines, or ' +
+        'the workspace you name. If you created it with --workspace, pass the same --workspace here; ' +
+        '`skrr machines dedicated list` shows what this scope can see.');
+}
+/**
+ * The product refusal code the server sent (`DEDICATED_RUNTIME_NOT_ASSIGNABLE`,
+ * …), for `this.error(message, { code })`. Without it a `--json` caller got the
+ * generic `CLI_ERROR` and could only branch on prose (OSK-8685). Falls back to
+ * `HTTP_<status>`, the same code `handleApiError` uses for a body with none.
+ */
+function dedicatedRuntimeApiErrorCode(err) {
+    if (!(err instanceof api_fetch_1.ApiFetchError)) {
+        return undefined;
+    }
+    const edge = (0, edge_error_page_1.describeEdgeErrorPage)({ status: err.status, body: err.body, method: err.method });
+    if (edge) {
+        return edge.code;
+    }
+    try {
+        const parsed = JSON.parse(err.body || '');
+        if (typeof parsed.code === 'string' && parsed.code) {
+            return parsed.code;
+        }
+    }
+    catch {
+        // Unparseable body: no product code.
+    }
+    return err.status ? `HTTP_${err.status}` : undefined;
+}
 function formatDedicatedRuntimeApiError(err) {
     if (!(err instanceof api_fetch_1.ApiFetchError) || !err.body) {
         return null;
@@ -147,6 +614,16 @@ function formatDedicatedRuntimeApiError(err) {
     if (err.status === 401) {
         return null;
     }
+    // An HTML page is the edge answering in the API's place — a WAF block or a
+    // gateway timeout. Printing its markup told nobody anything (OSK-8700).
+    const edge = (0, edge_error_page_1.describeEdgeErrorPage)({ status: err.status, body: err.body, method: err.method });
+    if (edge) {
+        return edge.message;
+    }
+    const notFound = describeLeaseNotFound(err);
+    if (notFound) {
+        return notFound;
+    }
     const missingEndpoint = describeMissingEndpoint(err);
     if (missingEndpoint) {
         return missingEndpoint;