@skrr-ai/cli 0.1.26 → 0.1.27

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

@@ -0,0 +1,80 @@
+import { execDedicatedRuntime, observeDedicatedRuntimeExecution, startDedicatedRuntimeExecution, type DedicatedRuntimeExecInput, type DedicatedRuntimeExecResult, type DedicatedRuntimeScope } from './dedicated-machines';
+/**
+ * `skrr machines dedicated exec`, as a start and a series of short observations
+ * (OSK-8705).
+ *
+ * The command used to be one request held open for as long as it ran. Behind
+ * CloudFront that request died at 60 s with an HTML 504 while the command kept
+ * running, and the page's advice — try again — ran it twice. Now no request
+ * lasts longer than one bounded observation, so no proxy timeout in front of
+ * the API decides whether the caller learns the exit code:
+ *
+ *   1. START under one idempotency key. A start whose answer never arrived (a
+ *      dropped connection, a gateway page) is sent again with the SAME key, and
+ *      the server returns the execution it already started — never a second run.
+ *   2. OBSERVE, letting the server hold each answer up to 20 s, until the
+ *      command ends. A failed observation is only a failed read; it is retried.
+ *   3. PRINT exactly what the synchronous route printed: the same result, the
+ *      same refusal body, the same exit code.
+ *
+ * Against a server that predates `executions`, it falls back to the synchronous
+ * route and says what that costs — but only on the FIRST start of a request id
+ * this invocation minted. A 404 without a product code proves the task that
+ * answered has no such route, not that no other task started the command; in a
+ * mixed fleet (a rolling deploy, a rollback) only the first attempt can rely on
+ * it. Every other case retries the same id or stops with the id to repeat.
+ */
+/** How long each observation lets the server hold the answer. */
+export declare const EXEC_OBSERVE_WAIT_MS = 20000;
+/** A request id is the idempotency key; the server accepts exactly this shape. */
+export declare const EXEC_REQUEST_ID_PATTERN: RegExp;
+export declare function newExecRequestId(): string;
+/** The CLI stopped hearing about a command it started. The command may still run. */
+export declare class DedicatedExecContactLostError extends Error {
+    readonly requestId: string;
+    readonly executionId: string;
+    readonly code = "DEDICATED_RUNTIME_EXECUTION_CONTACT_LOST";
+    constructor(requestId: string, executionId: string, cause: unknown);
+}
+/** No start request got an answer from the API, so whether the command started is unknown. */
+export declare class DedicatedExecStartUnconfirmedError extends Error {
+    readonly requestId: string;
+    readonly code = "DEDICATED_RUNTIME_EXECUTION_START_UNCONFIRMED";
+    constructor(requestId: string, cause: unknown);
+}
+/**
+ * The server has no `executions` route, but this invocation carries a request id
+ * it chose: falling back to the single-request route would ignore that id, and a
+ * run it already started elsewhere would happen twice.
+ */
+export declare class DedicatedExecIdempotencyUnsupportedError extends Error {
+    readonly requestId: string;
+    readonly code = "DEDICATED_RUNTIME_EXECUTION_REQUEST_ID_UNSUPPORTED";
+    constructor(requestId: string);
+}
+export interface DedicatedExecIo {
+    start: typeof startDedicatedRuntimeExecution;
+    observe: typeof observeDedicatedRuntimeExecution;
+    legacyExec: typeof execDedicatedRuntime;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    /** A line about the invocation (not the command's output), for stderr. */
+    notice: (message: string) => void;
+    signal: (ms: number) => AbortSignal | undefined;
+}
+/** The server answered, but has no `executions` route: nothing was started. */
+export declare function isMissingExecutionsEndpoint(err: unknown): boolean;
+export interface RunDedicatedExecOptions extends DedicatedRuntimeScope {
+    /** Idempotency key. Pass one to be able to repeat the invocation safely. */
+    requestId?: string;
+}
+export declare function runDedicatedExec(leaseId: string, input: DedicatedRuntimeExecInput, options?: RunDedicatedExecOptions, io?: Partial<DedicatedExecIo>): Promise<DedicatedRuntimeExecResult>;
+/**
+ * What was cut. A started command's stored outcome keeps at most the last
+ * 256 KiB of what the machine returned (`outputBytes` is the whole); the
+ * single-request route caps at 1 MB from the start.
+ */
+export declare function describeTruncation(result: {
+    stdout: string;
+    outputBytes?: number;
+}): string;

package/dist/lib/dedicated-exec.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DedicatedExecIdempotencyUnsupportedError = exports.DedicatedExecStartUnconfirmedError = exports.DedicatedExecContactLostError = exports.EXEC_REQUEST_ID_PATTERN = exports.EXEC_OBSERVE_WAIT_MS = void 0;
+exports.newExecRequestId = newExecRequestId;
+exports.isMissingExecutionsEndpoint = isMissingExecutionsEndpoint;
+exports.runDedicatedExec = runDedicatedExec;
+exports.describeTruncation = describeTruncation;
+const node_crypto_1 = require("node:crypto");
+const api_fetch_1 = require("./api-fetch");
+const dedicated_machines_1 = require("./dedicated-machines");
+/**
+ * `skrr machines dedicated exec`, as a start and a series of short observations
+ * (OSK-8705).
+ *
+ * The command used to be one request held open for as long as it ran. Behind
+ * CloudFront that request died at 60 s with an HTML 504 while the command kept
+ * running, and the page's advice — try again — ran it twice. Now no request
+ * lasts longer than one bounded observation, so no proxy timeout in front of
+ * the API decides whether the caller learns the exit code:
+ *
+ *   1. START under one idempotency key. A start whose answer never arrived (a
+ *      dropped connection, a gateway page) is sent again with the SAME key, and
+ *      the server returns the execution it already started — never a second run.
+ *   2. OBSERVE, letting the server hold each answer up to 20 s, until the
+ *      command ends. A failed observation is only a failed read; it is retried.
+ *   3. PRINT exactly what the synchronous route printed: the same result, the
+ *      same refusal body, the same exit code.
+ *
+ * Against a server that predates `executions`, it falls back to the synchronous
+ * route and says what that costs — but only on the FIRST start of a request id
+ * this invocation minted. A 404 without a product code proves the task that
+ * answered has no such route, not that no other task started the command; in a
+ * mixed fleet (a rolling deploy, a rollback) only the first attempt can rely on
+ * it. Every other case retries the same id or stops with the id to repeat.
+ */
+/** How long each observation lets the server hold the answer. */
+exports.EXEC_OBSERVE_WAIT_MS = 20_000;
+/** A request that has not answered by then is treated as lost, and retried. */
+const REQUEST_DEADLINE_MS = exports.EXEC_OBSERVE_WAIT_MS + 25_000;
+const START_ATTEMPTS = 4;
+/**
+ * How long past the command's own timeout to keep observing. Longer than the
+ * server's own outcome deadline (timeout + 30 s response grace + 60 s dispatch
+ * allowance), so the server reports `unknown` before this gives up on it.
+ */
+const OBSERVE_SLACK_MS = 2 * 60 * 1000;
+const MAX_BACKOFF_MS = 10_000;
+/** A request id is the idempotency key; the server accepts exactly this shape. */
+exports.EXEC_REQUEST_ID_PATTERN = /^[A-Za-z0-9._:/-]{1,200}$/;
+function newExecRequestId() {
+    return `exec:${(0, node_crypto_1.randomUUID)()}`;
+}
+/** How long an observation keeps asking after the server says the execution is not there. */
+const NOT_FOUND_TOLERANCE_MS = 60_000;
+/** The CLI stopped hearing about a command it started. The command may still run. */
+class DedicatedExecContactLostError extends Error {
+    requestId;
+    executionId;
+    code = 'DEDICATED_RUNTIME_EXECUTION_CONTACT_LOST';
+    constructor(requestId, executionId, cause) {
+        super(`Lost track of the command while it was running (execution ${executionId}). ` +
+            'It may still be running on the machine, or may have finished. To see how it ended ' +
+            `without running it again, repeat the same command with --request-id ${requestId} ` +
+            '(an outcome is kept for 5 minutes after it ends, and a minute after it is first read).' +
+            (cause instanceof Error && cause.message ? ` Last error: ${cause.message}` : ''));
+        this.requestId = requestId;
+        this.executionId = executionId;
+        this.name = 'DedicatedExecContactLostError';
+    }
+}
+exports.DedicatedExecContactLostError = DedicatedExecContactLostError;
+/** No start request got an answer from the API, so whether the command started is unknown. */
+class DedicatedExecStartUnconfirmedError extends Error {
+    requestId;
+    code = 'DEDICATED_RUNTIME_EXECUTION_START_UNCONFIRMED';
+    constructor(requestId, cause) {
+        super('Could not confirm whether the command started: no attempt got an answer from the API. ' +
+            'It may be running. To find out without running it a second time, repeat the same ' +
+            `command with --request-id ${requestId}.` +
+            (cause instanceof Error && cause.message ? ` Last error: ${cause.message}` : ''));
+        this.requestId = requestId;
+        this.name = 'DedicatedExecStartUnconfirmedError';
+    }
+}
+exports.DedicatedExecStartUnconfirmedError = DedicatedExecStartUnconfirmedError;
+/**
+ * The server has no `executions` route, but this invocation carries a request id
+ * it chose: falling back to the single-request route would ignore that id, and a
+ * run it already started elsewhere would happen twice.
+ */
+class DedicatedExecIdempotencyUnsupportedError extends Error {
+    requestId;
+    code = 'DEDICATED_RUNTIME_EXECUTION_REQUEST_ID_UNSUPPORTED';
+    constructor(requestId) {
+        super('This server answered as if it predates long-running exec, which is the only way --request-id ' +
+            'is honoured. The command was not run in a single request instead, because that could run ' +
+            `it a second time. During a deploy, retry shortly with --request-id ${requestId}; against ` +
+            'an older server, run it without --request-id.');
+        this.requestId = requestId;
+        this.name = 'DedicatedExecIdempotencyUnsupportedError';
+    }
+}
+exports.DedicatedExecIdempotencyUnsupportedError = DedicatedExecIdempotencyUnsupportedError;
+const defaultIo = {
+    start: dedicated_machines_1.startDedicatedRuntimeExecution,
+    observe: dedicated_machines_1.observeDedicatedRuntimeExecution,
+    legacyExec: dedicated_machines_1.execDedicatedRuntime,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+    notice: (message) => process.stderr.write(`${message}\n`),
+    signal: (ms) => typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function'
+        ? AbortSignal.timeout(ms)
+        : undefined,
+};
+function productCode(err) {
+    try {
+        const parsed = JSON.parse(err.body || '');
+        return typeof parsed.code === 'string' && parsed.code ? parsed.code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The server answered, but has no `executions` route: nothing was started. */
+function isMissingExecutionsEndpoint(err) {
+    return err instanceof api_fetch_1.ApiFetchError && err.status === 404 && !productCode(err);
+}
+/**
+ * No answer from the API itself: the connection failed, the request timed out
+ * client-side, or something in front of the API answered instead (a gateway
+ * page carries no product code). Whether the request arrived is unknown.
+ */
+function isUnansweredRequest(err) {
+    if (err instanceof api_fetch_1.ApiFetchError) {
+        return [502, 503, 504].includes(err.status) && !productCode(err);
+    }
+    const e = err;
+    if (!e)
+        return false;
+    if (e.name === 'AbortError' || e.name === 'TimeoutError')
+        return true;
+    const code = e.code || e.cause?.code || '';
+    if (['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EPIPE', 'ENOTFOUND', 'EAI_AGAIN'].includes(code)) {
+        return true;
+    }
+    return /fetch failed|socket hang up|network|terminated|other side closed/i.test(e.message || '');
+}
+function backoff(attempt) {
+    return Math.min(1000 * 2 ** Math.max(0, attempt - 1), MAX_BACKOFF_MS);
+}
+/** The refusal the synchronous route would have answered with, as its error. */
+function executionFailure(execution) {
+    const { status, ...body } = execution.error || {};
+    const httpStatus = typeof status === 'number' ? status : 500;
+    const code = typeof body.code === 'string' ? body.code : undefined;
+    return new api_fetch_1.ApiFetchError(`HTTP ${httpStatus} — command ${execution.state} (execution ${execution.id})`, httpStatus, JSON.stringify(Object.keys(body).length ? body : { error: 'The command failed' }), code, 'POST');
+}
+async function runDedicatedExec(leaseId, input, options = {}, io = {}) {
+    const deps = { ...defaultIo, ...io };
+    const requestId = options.requestId || newExecRequestId();
+    const scope = options.workspaceId
+        ? { workspaceId: options.workspaceId }
+        : {};
+    let execution;
+    for (let attempt = 1; !execution; attempt += 1) {
+        try {
+            const started = await deps.start(leaseId, input, {
+                ...scope,
+                requestId,
+                signal: deps.signal(REQUEST_DEADLINE_MS),
+            });
+            execution = started.execution;
+        }
+        catch (err) {
+            const missing = isMissingExecutionsEndpoint(err);
+            // Fall back only when nothing could have started: this is the first start
+            // for a request id this invocation minted. On a later attempt a codeless
+            // 404 is an OLDER task answering during a rolling deploy or a rollback,
+            // after an earlier attempt may have reached a newer one and started the
+            // command; a person's own --request-id may name a run a previous
+            // invocation started the same way. Either way `/exec` would run it twice.
+            if (missing && attempt === 1 && !options.requestId) {
+                deps.notice('This server predates long-running exec, so the command runs in a single request: ' +
+                    'one that runs past about 60 seconds is cut off at the edge while it keeps running ' +
+                    'on the machine.');
+                return deps.legacyExec(leaseId, input, scope);
+            }
+            // Safe only because the key is the same: the server answers a repeated
+            // start with the execution it already has.
+            if (!missing && !isUnansweredRequest(err))
+                throw err;
+            if (attempt >= START_ATTEMPTS) {
+                if (missing && attempt === 1)
+                    throw new DedicatedExecIdempotencyUnsupportedError(requestId);
+                throw new DedicatedExecStartUnconfirmedError(requestId, err);
+            }
+            await deps.sleep(backoff(attempt));
+        }
+    }
+    const timeoutMs = execution.timeoutMs || input.timeoutMs || dedicated_machines_1.DEDICATED_EXEC_DEFAULT_TIMEOUT_MS;
+    const giveUpAt = deps.now() + timeoutMs + OBSERVE_SLACK_MS;
+    let failures = 0;
+    let notFoundSince = null;
+    while (execution.state === 'running') {
+        try {
+            const observed = await deps.observe(leaseId, execution.id, {
+                ...scope,
+                waitMs: exports.EXEC_OBSERVE_WAIT_MS,
+                signal: deps.signal(REQUEST_DEADLINE_MS),
+            });
+            execution = observed.execution;
+            failures = 0;
+            notFoundSince = null;
+        }
+        catch (err) {
+            const code = err instanceof api_fetch_1.ApiFetchError ? productCode(err) : undefined;
+            // A codeless 404 is an older task, during a deploy or a rollback, that has
+            // never heard of `executions`; the command this id started is unaffected.
+            const olderServer = isMissingExecutionsEndpoint(err);
+            // Not found can be a result read and released moments ago, or a store that
+            // lost it. Keep asking briefly, then stop: one that is really gone does not
+            // come back, and waiting out the whole timeout would only delay the hint.
+            const notFound = code === 'DEDICATED_RUNTIME_EXECUTION_NOT_FOUND';
+            const transient = olderServer ||
+                notFound ||
+                isUnansweredRequest(err) ||
+                (err instanceof api_fetch_1.ApiFetchError &&
+                    (err.status === 429 || code === 'DEDICATED_RUNTIME_UNAVAILABLE'));
+            if (!transient)
+                throw err;
+            failures += 1;
+            const now = deps.now();
+            if (notFound)
+                notFoundSince ??= now;
+            else
+                notFoundSince = null;
+            const gaveUp = now >= giveUpAt ||
+                (notFoundSince !== null && now - notFoundSince >= NOT_FOUND_TOLERANCE_MS);
+            if (gaveUp)
+                throw new DedicatedExecContactLostError(requestId, execution.id, err);
+            await deps.sleep(backoff(failures));
+            continue;
+        }
+        if (execution.state === 'running' && deps.now() >= giveUpAt) {
+            // The server should have declared the outcome unknown by now.
+            throw new DedicatedExecContactLostError(requestId, execution.id, undefined);
+        }
+    }
+    if (execution.state === 'completed' && execution.result) {
+        return execution.result;
+    }
+    throw executionFailure(execution);
+}
+function sizeOf(bytes) {
+    if (bytes >= 1024 * 1024)
+        return `${Math.round((bytes / (1024 * 1024)) * 10) / 10} MiB`;
+    if (bytes >= 1024)
+        return `${Math.round(bytes / 1024)} KiB`;
+    return `${bytes} B`;
+}
+/**
+ * What was cut. A started command's stored outcome keeps at most the last
+ * 256 KiB of what the machine returned (`outputBytes` is the whole); the
+ * single-request route caps at 1 MB from the start.
+ */
+function describeTruncation(result) {
+    if (typeof result.outputBytes === 'number') {
+        return `[output truncated: showing the last ${sizeOf(Buffer.byteLength(result.stdout))} of ${sizeOf(result.outputBytes)}]`;
+    }
+    return '[output truncated at 1 MB]';
+}

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

@@ -11,6 +11,9 @@ export declare const dedicatedWaitFlags: {
     timeout: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     interval: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
 };
+/** The lease argument that means "the machine this command is running on". */
+export declare const DEDICATED_SELF_LEASE = "self";
+export declare const DEDICATED_LEASE_ARG_DESCRIPTION = "Dedicated Runtime lease id, or `self` when running on the machine itself";
 export declare abstract class DedicatedLeaseCommand extends BaseCommand {
     /**
      * `--workspace` is a BaseCommand flag every command already accepts (it sets
@@ -21,6 +24,12 @@ export declare abstract class DedicatedLeaseCommand extends BaseCommand {
     protected scopeFrom(flags: {
         workspace?: string;
     }): DedicatedRuntimeScope;
+    /**
+     * A lease argument as typed, or — for `self` — the lease of the machine this
+     * process runs on, so an agent working on a Dedicated Runtime can snapshot,
+     * inspect or stop its own machine without being told its id.
+     */
+    protected resolveLeaseArg(lease: string): Promise<string>;
     /**
      * Open an interactive terminal on a lease's machine and run it to the end,
      * exiting with the shell's own code.

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

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DedicatedLeaseCommand = exports.dedicatedWaitFlags = void 0;
+exports.DedicatedLeaseCommand = exports.DEDICATED_LEASE_ARG_DESCRIPTION = exports.DEDICATED_SELF_LEASE = exports.dedicatedWaitFlags = void 0;
 const core_1 = require("@oclif/core");
 const base_command_1 = require("../base-command");
 const dedicated_machines_1 = require("./dedicated-machines");
 const dedicated_terminal_1 = require("./dedicated-terminal");
+const daemonBroker_1 = require("./daemonBroker");
 const harnesses_1 = require("./harnesses");
 const dedicated_wait_1 = require("./dedicated-wait");
 const hosted_machines_1 = require("./hosted-machines");
@@ -28,6 +29,9 @@ exports.dedicatedWaitFlags = {
     }),
 };
 const TERMINAL_READY_STATES = new Set(['ready', 'active', 'idle']);
+/** The lease argument that means "the machine this command is running on". */
+exports.DEDICATED_SELF_LEASE = 'self';
+exports.DEDICATED_LEASE_ARG_DESCRIPTION = 'Dedicated Runtime lease id, or `self` when running on the machine itself';
 class DedicatedLeaseCommand extends base_command_1.BaseCommand {
     /**
      * `--workspace` is a BaseCommand flag every command already accepts (it sets
@@ -38,6 +42,25 @@ class DedicatedLeaseCommand extends base_command_1.BaseCommand {
     scopeFrom(flags) {
         return flags.workspace ? { workspaceId: flags.workspace } : {};
     }
+    /**
+     * A lease argument as typed, or — for `self` — the lease of the machine this
+     * process runs on, so an agent working on a Dedicated Runtime can snapshot,
+     * inspect or stop its own machine without being told its id.
+     */
+    async resolveLeaseArg(lease) {
+        if (lease !== exports.DEDICATED_SELF_LEASE)
+            return lease;
+        const descriptor = (0, daemonBroker_1.readBootstrap)(daemonBroker_1.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR);
+        if (!descriptor?.daemonId) {
+            this.error('`self` means the Dedicated Runtime this command runs on, and this is not one (or its daemon is not running). Pass a lease id.', { exit: 2 });
+        }
+        const listed = await this.callDedicated(() => (0, harnesses_1.listHarnesses)());
+        const resolved = (0, dedicated_machines_1.dedicatedLeaseIdForDaemon)(descriptor.daemonId, listed?.harnesses ?? []);
+        if (!resolved) {
+            this.error("This machine's daemon has not registered a lease yet, so `self` cannot be resolved. Pass a lease id, or try again once `skrr machines dedicated list` shows the machine ready.", { exit: 1 });
+        }
+        return resolved;
+    }
     /**
      * Open an interactive terminal on a lease's machine and run it to the end,
      * exiting with the shell's own code.

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

@@ -43,6 +43,8 @@ export interface DedicatedLease extends Omit<HarnessLease, 'storage'> {
         unpaidSince?: string;
         deletionNoticeAt?: string;
         deleteAfter?: string;
+        /** A workspace deletion and its recovery window (D12). */
+        deletion?: DedicatedLeaseDeletion;
     } & Record<string, unknown>;
     recovery?: {
         incidentHold?: {
@@ -51,8 +53,22 @@ export interface DedicatedLease extends Omit<HarnessLease, 'storage'> {
             heldAt?: string;
             closedAt?: string;
         };
+        /** Set on a machine created by restoring a deleted one. */
+        restoredFromLeaseId?: string;
     };
 }
+/**
+ * A deleted workspace: restorable into a new machine until `recoverableUntil`,
+ * then every copy is deleted and `completedAt` records it.
+ */
+export interface DedicatedLeaseDeletion {
+    status?: 'recoverable' | 'purging' | 'completed';
+    requestedAt?: string | null;
+    recoverableUntil?: string | null;
+    restorable?: boolean;
+    restoredToLeaseId?: string | null;
+    completedAt?: string | null;
+}
 export interface CreateDedicatedRuntimeInput extends DedicatedRuntimeScope {
     requestId: string;
     displayName: string;
@@ -114,6 +130,17 @@ export declare function performDedicatedLeaseAction(leaseId: string, action: Ded
 export declare function growDedicatedRuntime(leaseId: string, storageGb: number, options?: {
     requestId?: string;
 } & DedicatedRuntimeScope): Promise<DedicatedRuntimeResponse>;
+/**
+ * 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.
+ */
+export declare function restoreDeletedDedicatedRuntime(leaseId: string, options?: {
+    displayName?: string;
+    monthlySpendingLimitCents?: number;
+    requestId?: string;
+} & DedicatedRuntimeScope): Promise<DedicatedRuntimeResponse>;
 /**
  * Change the monthly spending cap of one lease.
  *
@@ -142,17 +169,66 @@ export interface DedicatedRuntimeExecResult {
     timedOut: boolean;
     truncated: boolean;
     durationMs: number;
+    /**
+     * Present when a started command's stored outcome kept only the tail: the
+     * number of bytes the machine returned, of which `stdout` is the last part.
+     */
+    outputBytes?: number;
 }
 /** The server's ceiling for one exec; documented beside the route. */
 export declare const DEDICATED_EXEC_MAX_TIMEOUT_MS: number;
+/** The server's default when a command names no timeout. */
+export declare const DEDICATED_EXEC_DEFAULT_TIMEOUT_MS: number;
 /**
- * Run one command on the machine as the workload user.
+ * 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.
  */
 export declare function execDedicatedRuntime(leaseId: string, input: DedicatedRuntimeExecInput, scope?: DedicatedRuntimeScope): Promise<DedicatedRuntimeExecResult>;
+export type DedicatedRuntimeExecutionState = 'running' | 'completed' | 'failed' | 'unknown';
+/** A started command, as `GET .../executions/:id` reports it. */
+export interface DedicatedRuntimeExecution {
+    id: string;
+    state: DedicatedRuntimeExecutionState;
+    startedAt: string;
+    timeoutMs: number;
+    completedAt?: string;
+    /** `completed`: exactly what the synchronous exec route returns. */
+    result?: DedicatedRuntimeExecResult;
+    /** `failed` / `unknown`: the status and body the synchronous route would have answered with. */
+    error?: {
+        status?: number;
+        code?: string;
+        error?: string;
+        message?: string;
+    } & Record<string, unknown>;
+}
+export interface DedicatedRuntimeExecutionResponse {
+    execution: DedicatedRuntimeExecution;
+    replayed?: boolean;
+}
+/**
+ * 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.
+ */
+export declare function startDedicatedRuntimeExecution(leaseId: string, input: DedicatedRuntimeExecInput, options: {
+    requestId: string;
+    signal?: AbortSignal;
+} & DedicatedRuntimeScope): Promise<DedicatedRuntimeExecutionResponse>;
+/** Read a started command, letting the server hold the answer up to `waitMs` for it to end. */
+export declare function observeDedicatedRuntimeExecution(leaseId: string, executionId: string, options: {
+    waitMs: number;
+    signal?: AbortSignal;
+} & DedicatedRuntimeScope): Promise<DedicatedRuntimeExecutionResponse>;
 /** Mirrors the daemon's bounds (daemon/src/tools/file-transfer.ts). */
 export declare const DEDICATED_FILE_CHUNK_BYTES: number;
 export declare const DEDICATED_FILE_MAX_BYTES: number;
@@ -219,6 +295,8 @@ export declare function dedicatedSpendSummary(lease: DedicatedLease): string;
  * 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. */
+export declare function describeDedicatedDeletion(deletion: DedicatedLeaseDeletion, leaseId?: string): string;
 export declare function describeDedicatedLease(lease: DedicatedLease, harnesses?: readonly Harness[]): string[];
 /**
  * Every harness row a Dedicated Runtime lease's daemon registered, freshest
@@ -231,6 +309,17 @@ export declare function describeDedicatedLease(lease: DedicatedLease, harnesses?
  * when it announces none), all sharing the daemon id.
  */
 export declare function dedicatedLeaseHarnesses(lease: Pick<DedicatedLease, 'id'>, harnesses: readonly Harness[]): Harness[];
+/**
+ * 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.
+ */
+export declare function dedicatedLeaseIdForDaemon(daemonId: string | undefined | null, harnesses: readonly Harness[]): string | null;
 /**
  * The row an interactive terminal opens on: online, local, with a daemon.
  *