@skrr-ai/cli 0.1.28 → 0.1.30

package/dist/lib/dedicated-copy.js

@@ -1,39 +1,216 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DedicatedCopyCancelledError = exports.DedicatedCopyError = void 0;
+exports.listenForCopyInterrupt = listenForCopyInterrupt;
+exports.createCopyProgress = createCopyProgress;
+exports.isContinuousIntegration = isContinuousIntegration;
+exports.namesRemoteDirectory = namesRemoteDirectory;
+exports.intoRemoteDirectory = intoRemoteDirectory;
 exports.uploadToDedicatedRuntime = uploadToDedicatedRuntime;
 exports.downloadFromDedicatedRuntime = downloadFromDedicatedRuntime;
 const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
 const node_path_1 = require("node:path");
 const dedicated_machines_1 = require("./dedicated-machines");
+/**
+ * A refusal the CLI makes itself, with the code the server uses for the same
+ * cause. A file over the limit, a file that changed and a file that is missing
+ * each read one way and carry one code whichever side found it; the server's
+ * sentences are in `DedicatedRuntimeMachineAccess.mapFileTransferError`
+ * (OSK-8714). Before, these local refusals had no code at all.
+ */
+class DedicatedCopyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DedicatedCopyError';
+    }
+}
+exports.DedicatedCopyError = DedicatedCopyError;
+const changedWhileCopying = (path, where) => new DedicatedCopyError('DEDICATED_RUNTIME_FILE_CHANGED', `${path} changed ${where} while it was being copied, so nothing was written. Copy it again once it has stopped changing.`);
 const defaultIo = {
     readChunk: dedicated_machines_1.readDedicatedRuntimeFileChunk,
     writeChunk: dedicated_machines_1.writeDedicatedRuntimeFileChunk,
     chunkBytes: dedicated_machines_1.DEDICATED_FILE_CHUNK_BYTES,
     maxBytes: dedicated_machines_1.DEDICATED_FILE_MAX_BYTES,
+    onProcessExit: (fn) => {
+        process.on('exit', fn);
+        return () => process.removeListener('exit', fn);
+    },
 };
+// SIGHUP too: a closed terminal cancels a copy like Ctrl-C. With no listener of
+// the command's own for it, auth-core's handler lets the process die by the
+// signal, and a download's exit handler never runs to remove its temporary file.
+const SIGNAL_NUMBERS = { SIGHUP: 1, SIGINT: 2, SIGTERM: 15 };
+/** A copy stopped by SIGINT, SIGTERM or SIGHUP. Exits 128 + the signal's number, as a shell would. */
+class DedicatedCopyCancelledError extends Error {
+    signalName;
+    code = 'DEDICATED_RUNTIME_COPY_CANCELLED';
+    exitCode;
+    constructor(signalName) {
+        super(`Copy cancelled by ${signalName}.`);
+        this.signalName = signalName;
+        this.name = 'DedicatedCopyCancelledError';
+        this.exitCode = 128 + SIGNAL_NUMBERS[signalName];
+    }
+}
+exports.DedicatedCopyCancelledError = DedicatedCopyCancelledError;
+function throwIfCancelled(signal) {
+    if (signal?.aborted) {
+        throw signal.reason instanceof Error ? signal.reason : new Error('Copy cancelled');
+    }
+}
+/**
+ * Listen for SIGINT, SIGTERM and SIGHUP for the length of one copy.
+ *
+ * An ordinary command-level listener, nothing more. The lock-release handler
+ * every command inherits defers to it (`installLockExitHandlers`,
+ * packages/auth-core/src/refresh.ts): the first signal reaches this listener,
+ * which aborts the copy so the loop removes its partial and rejects; a second
+ * signal, or a cleanup that hangs past auth-core's fallback, exits the process,
+ * and a download's exit handler still removes its temporary file then.
+ */
+function listenForCopyInterrupt({ proc = process, notice = (message) => process.stderr.write(`${message}\n`), } = {}) {
+    const controller = new AbortController();
+    let interruptedBy = null;
+    const listeners = Object.keys(SIGNAL_NUMBERS).map((name) => {
+        const listener = () => {
+            if (interruptedBy)
+                return;
+            interruptedBy = name;
+            // After SIGHUP the terminal that would show the notice is gone.
+            if (name !== 'SIGHUP') {
+                notice(`\nCancelling the copy and removing its partial file… (${name === 'SIGINT' ? 'Ctrl-C' : name} again to stop now)`);
+            }
+            controller.abort(new DedicatedCopyCancelledError(name));
+        };
+        proc.on(name, listener);
+        return [name, listener];
+    });
+    return {
+        signal: controller.signal,
+        interruptedBy: () => interruptedBy,
+        dispose: () => {
+            for (const [name, listener] of listeners)
+                proc.removeListener(name, listener);
+        },
+    };
+}
 function mib(bytes) {
     return `${Math.round((bytes / (1024 * 1024)) * 10) / 10} MiB`;
 }
+/**
+ * One line of progress for a terminal, redrawn in place: a 60 MiB copy takes
+ * about forty seconds, and printed nothing until it ended (OSK-8714). The
+ * caller decides whether there is a terminal to draw on.
+ */
+function createCopyProgress({ label, write, now = Date.now, }) {
+    const startedAt = now();
+    let drawn = false;
+    return {
+        update(copied, total) {
+            const seconds = Math.max(now() - startedAt, 1) / 1000;
+            const percent = total > 0 ? Math.floor((copied / total) * 100) : 100;
+            write(`\r\x1b[2K${label} ${mib(copied)} of ${mib(total)} (${percent}%), ${mib(copied / seconds)}/s`);
+            drawn = true;
+        },
+        clear() {
+            if (drawn)
+                write('\r\x1b[2K');
+            drawn = false;
+        },
+    };
+}
+/** Whether a CI system is running this. Progress is for a person watching. */
+function isContinuousIntegration(env = process.env) {
+    const ci = env.CI?.trim().toLowerCase();
+    return Boolean(ci) && ci !== '0' && ci !== 'false';
+}
+/** `dir/`, `dir/.` or `.`: a machine path that names a directory to copy into. */
+function namesRemoteDirectory(remotePath) {
+    return /(^|\/)\.?$/.test(remotePath);
+}
+/** `name` inside the machine directory `directory`, however it was spelled. */
+function intoRemoteDirectory(directory, name) {
+    const parent = directory.replace(/\/\.?$/, '').replace(/^\.$/, '');
+    return parent ? `${parent}/${name}` : name;
+}
+const PATH_IS_DIRECTORY = 'DEDICATED_RUNTIME_PATH_IS_DIRECTORY';
+/** The machine refused the destination as a directory before anything was staged. */
+class DestinationIsDirectory extends Error {
+    refusal;
+    constructor(refusal) {
+        super('The destination on the machine is a directory');
+        this.refusal = refusal;
+    }
+}
+/**
+ * Upload one file. A destination that is a directory — spelled `dir/`, or an
+ * existing directory named without the slash — receives the file under its own
+ * name, as `cp` and `scp` do and as a download into a local directory already
+ * did. Before, `cp tiny.txt <lease>:repos/scout-a/` sent the whole file and then
+ * failed the machine's final rename with EISDIR (OSK-8713).
+ *
+ * `dir/` is resolved here, without asking. A directory named without the slash
+ * is found out by the machine, which refuses it on the first chunk before
+ * anything is staged; the copy then goes into it, once.
+ */
 async function uploadToDedicatedRuntime(localPath, leaseId, remotePath, scope = {}, io = {}) {
-    const { writeChunk, chunkBytes, maxBytes } = { ...defaultIo, ...io };
-    const info = await (0, promises_1.stat)(localPath);
+    const intoDirectory = (directory) => intoRemoteDirectory(directory, (0, node_path_1.basename)(localPath));
+    const attempt = async (target) => {
+        try {
+            return await uploadFile(localPath, leaseId, target, scope, io);
+        }
+        catch (err) {
+            throw err instanceof DestinationIsDirectory ? err.refusal : err;
+        }
+    };
+    if (namesRemoteDirectory(remotePath)) {
+        return attempt(intoDirectory(remotePath));
+    }
+    try {
+        return await uploadFile(localPath, leaseId, remotePath, scope, io);
+    }
+    catch (err) {
+        if (err instanceof DestinationIsDirectory)
+            return attempt(intoDirectory(remotePath));
+        throw err;
+    }
+}
+async function uploadFile(localPath, leaseId, remotePath, scope, io) {
+    const { writeChunk, chunkBytes, maxBytes, signal, onProgress } = { ...defaultIo, ...io };
+    throwIfCancelled(signal);
+    const info = await (0, promises_1.stat)(localPath).catch((err) => {
+        // The raw `ENOENT: no such file or directory, stat './x'` said the same
+        // thing in the platform's words rather than ours.
+        if (err?.code === 'ENOENT' || err?.code === 'ENOTDIR') {
+            throw new DedicatedCopyError('DEDICATED_RUNTIME_FILE_NOT_FOUND', `${localPath} does not exist here.`);
+        }
+        throw err;
+    });
     if (!info.isFile()) {
-        throw new Error(`${localPath} is not a regular file`);
+        throw new DedicatedCopyError('DEDICATED_RUNTIME_PATH_NOT_A_FILE', `${localPath} is not a regular file; cp copies one file.`);
     }
     if (info.size > maxBytes) {
-        throw new Error(`${localPath} is ${mib(info.size)}; copy is limited to ${mib(maxBytes)}. Push it through Git or object storage instead.`);
+        throw new DedicatedCopyError('DEDICATED_RUNTIME_FILE_TOO_LARGE', `${localPath} is ${mib(info.size)}; copy is limited to ${mib(maxBytes)}. Push it through Git or object storage instead.`);
     }
     const transferId = `cp-${Date.now().toString(36)}-${(0, node_crypto_1.randomBytes)(6).toString('hex')}`;
     const handle = await (0, promises_1.open)(localPath, 'r');
+    let offset = 0;
     try {
         const buffer = Buffer.alloc(chunkBytes);
-        let offset = 0;
         for (;;) {
+            // Checked between chunks, never by abandoning one in flight: the machine
+            // still applies a chunk whose request was abandoned, and while it does,
+            // the abort below is refused as a write to a file another request holds.
+            // Waiting out one chunk is what lets the abort remove the staged file.
+            throwIfCancelled(signal);
             const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, offset);
             const final = offset + bytesRead >= info.size;
             if (!final && bytesRead === 0) {
-                throw new Error(`${localPath} shrank while it was being copied`);
+                throw changedWhileCopying(localPath, 'here');
             }
             const result = await writeChunk(leaseId, {
                 path: remotePath,
@@ -45,14 +222,22 @@ async function uploadToDedicatedRuntime(localPath, leaseId, remotePath, scope =
                 ...(final ? { final: true, totalSize: info.size } : {}),
             }, scope);
             offset += bytesRead;
+            onProgress?.(offset, info.size);
             if (final) {
                 return { bytes: offset, destination: `${leaseId}:${result.path || remotePath}` };
             }
         }
     }
     catch (err) {
+        if (offset === 0 && err?.code === PATH_IS_DIRECTORY) {
+            // Refused before the first chunk was staged: there is nothing to abort.
+            throw new DestinationIsDirectory(err);
+        }
         // Best effort: remove the staged partial so it does not sit beside the
-        // destination. The destination itself was never touched.
+        // destination. The destination itself was never touched. An abort that
+        // never arrives — the process killed, the network gone — is covered by the
+        // machine, which removes a stale staging file on the next upload into the
+        // same directory (daemon/src/tools/file-transfer.ts).
         await writeChunk(leaseId, { path: remotePath, transferId, offset: 0, abort: true }, scope).catch(() => undefined);
         throw err;
     }
@@ -61,44 +246,61 @@ async function uploadToDedicatedRuntime(localPath, leaseId, remotePath, scope =
     }
 }
 async function downloadFromDedicatedRuntime(leaseId, remotePath, localPath, scope = {}, io = {}) {
-    const { readChunk, chunkBytes } = { ...defaultIo, ...io };
+    const { readChunk, chunkBytes, onProcessExit, signal, onProgress } = { ...defaultIo, ...io };
+    throwIfCancelled(signal);
     let target = localPath;
-    try {
-        if ((await (0, promises_1.stat)(localPath)).isDirectory()) {
-            target = (0, node_path_1.join)(localPath, (0, node_path_1.basename)(remotePath));
-        }
+    if (localPath.endsWith('/') || localPath.endsWith(node_path_1.sep)) {
+        // Spelled as a directory: into it, made if missing. It used to become a
+        // FILE named after the directory when the directory did not exist yet.
+        target = (0, node_path_1.join)(localPath, (0, node_path_1.basename)(remotePath));
     }
-    catch {
-        // Does not exist yet: it names the file.
+    else {
+        try {
+            if ((await (0, promises_1.stat)(localPath)).isDirectory()) {
+                target = (0, node_path_1.join)(localPath, (0, node_path_1.basename)(remotePath));
+            }
+        }
+        catch {
+            // Does not exist yet: it names the file.
+        }
     }
     await (0, promises_1.mkdir)((0, node_path_1.dirname)(target), { recursive: true });
     const temporary = (0, node_path_1.join)((0, node_path_1.dirname)(target), `.${(0, node_path_1.basename)(target)}.skrr-download-${(0, node_crypto_1.randomBytes)(6).toString('hex')}`);
     const handle = await (0, promises_1.open)(temporary, 'wx');
+    // For an exit nothing waits for — a second Ctrl-C, auth-core's fallback, a
+    // caller that passed no signal. Synchronous, because an exit handler cannot
+    // await; harmless after the rename, when the path is gone.
+    const forgetExitCleanup = onProcessExit(() => (0, node_fs_1.rmSync)(temporary, { force: true }));
     let closed = false;
     let offset = 0;
     let size = -1;
     let mtimeMs = -1;
     try {
         for (;;) {
-            const chunk = await readChunk(leaseId, { path: remotePath, offset, length: chunkBytes }, scope);
+            throwIfCancelled(signal);
+            // Nothing on the machine needs undoing, so an in-flight read is abandoned
+            // at once rather than waited out.
+            const chunk = await readChunk(leaseId, { path: remotePath, offset, length: chunkBytes }, scope, signal);
             if (size === -1) {
                 size = chunk.size;
                 mtimeMs = chunk.mtimeMs;
             }
             else if (chunk.size !== size || chunk.mtimeMs !== mtimeMs) {
                 // Chunks from two versions of a file splice into one that never existed.
-                throw new Error(`${remotePath} changed on the machine while it was being copied`);
+                throw changedWhileCopying(remotePath, 'on the machine');
             }
             const bytes = Buffer.from(chunk.dataBase64, 'base64');
             if (bytes.byteLength !== chunk.bytesRead) {
-                throw new Error('A chunk arrived damaged; nothing was written to the destination');
+                throw new DedicatedCopyError('DEDICATED_RUNTIME_FILE_TRANSFER_FAILED', 'A chunk arrived damaged; nothing was written to the destination.');
             }
             await handle.write(bytes, 0, bytes.byteLength, offset);
             offset += bytes.byteLength;
+            onProgress?.(offset, size);
             if (chunk.eof)
                 break;
             if (bytes.byteLength === 0) {
-                throw new Error(`${remotePath} ended before its reported size`);
+                // It was shorter than it said when the first chunk was read.
+                throw changedWhileCopying(remotePath, 'on the machine');
             }
         }
         await handle.close();
@@ -112,4 +314,7 @@ async function downloadFromDedicatedRuntime(leaseId, remotePath, localPath, scop
         await (0, promises_1.unlink)(temporary).catch(() => undefined);
         throw err;
     }
+    finally {
+        forgetExitCleanup();
+    }
 }

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

@@ -43,7 +43,13 @@ export declare abstract class DedicatedLeaseCommand extends BaseCommand {
         workspace?: string;
         cwd?: string;
     }, initialCommand?: string): Promise<void>;
-    /** Run an API call, turning a refusal into the server's own sentence. */
+    /**
+     * Run an API call, turning a refusal into the server's own sentence.
+     *
+     * The refusal's public `details` ride along in the `--json` envelope: a script
+     * that meets a failed health check can branch on `details.reasons` rather than
+     * parse the sentence, which `this.error` alone had no way to carry (OSK-8687).
+     */
     protected callDedicated<T>(fn: () => Promise<T>): Promise<T>;
     /**
      * Print the lease an action returned, or wait for its operation to finish

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

@@ -112,15 +112,28 @@ class DedicatedLeaseCommand extends base_command_1.BaseCommand {
         if (code !== 0)
             this.exit(code);
     }
-    /** Run an API call, turning a refusal into the server's own sentence. */
+    /**
+     * Run an API call, turning a refusal into the server's own sentence.
+     *
+     * The refusal's public `details` ride along in the `--json` envelope: a script
+     * that meets a failed health check can branch on `details.reasons` rather than
+     * parse the sentence, which `this.error` alone had no way to carry (OSK-8687).
+     */
     async callDedicated(fn) {
         try {
             return await fn();
         }
         catch (err) {
             const message = (0, dedicated_machines_1.formatDedicatedRuntimeApiError)(err);
-            if (message)
-                this.error(message, { exit: 1, code: (0, dedicated_machines_1.dedicatedRuntimeApiErrorCode)(err) });
+            if (message) {
+                this.failWithCliError({
+                    message,
+                    code: (0, dedicated_machines_1.dedicatedRuntimeApiErrorCode)(err) ?? 'CLI_ERROR',
+                    exit: 1,
+                    retryable: false,
+                    details: (0, dedicated_machines_1.dedicatedRuntimeApiErrorDetails)(err),
+                });
+            }
             this.handleApiError(err);
         }
     }

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

@@ -1,5 +1,5 @@
 import type { Harness, HarnessLease } from './harnesses';
-export type DedicatedLeaseAction = 'start' | 'stop' | 'restart' | 'snapshot' | 'health-check';
+export type DedicatedLeaseAction = 'start' | 'stop' | 'restart' | 'update-image' | 'snapshot' | 'health-check';
 export declare const DEDICATED_LEASE_ACTIONS: DedicatedLeaseAction[];
 export declare const DEDICATED_MACHINE_PRODUCT = "dedicated-machine";
 export interface DedicatedRuntimeScope {
@@ -13,7 +13,16 @@ export interface DedicatedRuntimeScope {
  * compile while the columns stayed empty. Provider ids (instance, volume, AMI)
  * are deliberately absent from the payload and therefore from this type.
  */
-export interface DedicatedLease extends Omit<HarnessLease, 'storage'> {
+export interface DedicatedLease extends Omit<HarnessLease, 'storage' | 'health'> {
+    /** Canonical public scope; the persisted MachineLease field is `teamId`. */
+    workspaceId?: string | null;
+    health?: {
+        assignable?: boolean;
+        reasons?: string[];
+        advisories?: string[];
+        /** Where the machine's root image stands (D11). Absent when it cannot be judged. */
+        image?: DedicatedImageStanding;
+    } & Record<string, unknown>;
     supportReference?: string;
     lifecycleCapabilities?: Record<string, boolean>;
     executionCapabilities?: Record<string, boolean>;
@@ -41,10 +50,14 @@ export interface DedicatedLease extends Omit<HarnessLease, 'storage'> {
         lastRestoreTestAt?: string;
         lastRestoreTestStatus?: string;
         unpaidSince?: string;
+        /** When the deletion notice REACHED the owner (the clock's start), not when one was recorded. */
         deletionNoticeAt?: string;
+        /** The deletion deadline in force: an archive deadline, or an unpaid one a delivered notice started. */
         deleteAfter?: string;
         /** A workspace deletion and its recovery window (D12). */
         deletion?: DedicatedLeaseDeletion;
+        /** Why and when this workspace may be deleted, before it is (D7). */
+        deletionPlan?: DedicatedDeletionPlan;
     } & Record<string, unknown>;
     recovery?: {
         incidentHold?: {
@@ -56,19 +69,108 @@ export interface DedicatedLease extends Omit<HarnessLease, 'storage'> {
         /** Set on a machine created by restoring a deleted one. */
         restoredFromLeaseId?: string;
     };
+    /**
+     * The lease's current (or last) operation, and whether it has finished. A
+     * state can be reached before the operation that reached it is done: a create
+     * is `ready` the moment its guest registers. Absent from servers that predate
+     * it, and for a lease that never had an operation.
+     */
+    operation?: DedicatedLeaseOperation;
+}
+export interface DedicatedLeaseOperation {
+    /** `provision` (create), `start`, `stop`, `restart`, `update-image`, `snapshot`, `grow`, `destroy`; null when the server does not name it. */
+    action?: string | null;
+    /** `cancelled`: an unpaid purge undone before its destroy was issued. Every status but `in_progress` is settled. */
+    status?: 'in_progress' | 'succeeded' | 'failed' | 'cancelled';
+    startedAt?: string | null;
+    completedAt?: string | null;
+}
+/**
+ * A Dedicated Runtime's root image, as the server judges it (D11). The platform
+ * owns the image: a machine on an older one moves onto the current image at its
+ * next start from stopped, its next restart, or when its owner asks, and must
+ * have moved by `updateBy`. A move that does not come back healthy returns the
+ * machine to the previous image. Files under the workspace survive both.
+ */
+export interface DedicatedImageStanding {
+    /** A newer image exists that has not already failed on this machine. */
+    updateAvailable?: boolean;
+    /** When the older image stops being supported; null when there is no deadline. */
+    updateBy?: string | null;
+    lastUpdate?: {
+        status?: 'applying' | 'succeeded' | 'rolling_back' | 'rolled_back' | 'failed';
+        startedAt?: string | null;
+        settledAt?: string | null;
+    } | null;
 }
+/** One line saying where a machine's image stands and what the owner can do. */
+export declare function describeDedicatedImageStanding(image: DedicatedImageStanding, leaseId?: string): string;
 /**
  * A deleted workspace: restorable into a new machine until `recoverableUntil`,
- * then every copy is deleted and `completedAt` records it.
+ * then every copy is deleted and `completedAt` records it. `withheld`: an unpaid
+ * deletion stopped after its machine was shut down and before its files were
+ * deleted — kept in the archived lease, with no window, restorable.
  */
 export interface DedicatedLeaseDeletion {
-    status?: 'recoverable' | 'purging' | 'completed';
+    status?: 'recoverable' | 'purging' | 'completed' | 'withheld';
     requestedAt?: string | null;
     recoverableUntil?: string | null;
     restorable?: boolean;
     restoredToLeaseId?: string | null;
+    /** This lease is the previous copy of a workspace restored into that machine. */
+    supersededByLeaseId?: string | null;
     completedAt?: string | null;
 }
+/**
+ * `storage.deletionPlan`: why and when this workspace may be deleted, which
+ * notices reached the owner on which channels, and what is holding a deletion
+ * back. Brand-free and provider-free, like the rest of the payload.
+ */
+/**
+ * What clears an unpaid deletion's cause, and so cancels it: paying the runtime's
+ * unpaid invoices (their pages only for an owner who pays them), or subscribing
+ * again to the plan the machine needs.
+ */
+export type DedicatedDeletionRemedy = {
+    kind: 'subscribe';
+} | {
+    kind: 'pay_invoice';
+    paidByOwner: boolean;
+    invoices: Array<{
+        hostedInvoiceUrl: string;
+        amountDue: number | null;
+        currency: string | null;
+    }>;
+};
+export interface DedicatedDeletionPlan {
+    kind: 'unpaid' | 'retention_period';
+    status: 'notice_pending' | 'scheduled' | 'deleting' | 'cancelled';
+    /** Chosen by the remedy: `payment_failed` an invoice to pay, `plan_inactive` a plan to subscribe to. */
+    reason?: 'subscription_canceled' | 'payment_failed' | 'plan_inactive' | 'unknown';
+    remedy?: DedicatedDeletionRemedy;
+    entitlementEndedAt?: string | null;
+    retentionEndsAt?: string | null;
+    unpaidSince?: string | null;
+    deletionNoticeDeliveredAt?: string | null;
+    deleteAfter?: string | null;
+    retentionDays?: number | null;
+    noticeFloorDays?: number | null;
+    notices?: Array<{
+        notice: string;
+        round?: number;
+        deliveredAt?: string | null;
+        channels?: string[];
+    }>;
+    blockedBy?: string;
+    blockedSince?: string | null;
+    /** While `deleting`: whether restoring billing still cancels it, and from when it may start. */
+    cancellable?: boolean;
+    deletionStartsAt?: string | null;
+    cancelledAt?: string | null;
+    cancelReason?: string;
+    /** Cancelled after the machine was shut down: the files are kept in the archived lease. */
+    workspaceWithheld?: boolean;
+}
 export interface CreateDedicatedRuntimeInput extends DedicatedRuntimeScope {
     requestId: string;
     displayName: string;
@@ -77,7 +179,7 @@ export interface CreateDedicatedRuntimeInput extends DedicatedRuntimeScope {
     storageGb?: number;
     retentionClass?: string;
     backupProfile?: 'crash-consistent' | 'application-consistent';
-    monthlySpendingLimitCents: number;
+    monthlySpendingLimitCents?: number;
     repositoryRef?: string;
 }
 export interface DedicatedRuntimeResponse {
@@ -100,7 +202,7 @@ export declare function dedicatedRuntimeCreateInput(input: {
     requestId: string;
     displayName: string;
     sizePreset: string;
-    monthlySpendingLimitCents: number;
+    monthlySpendingLimitCents?: number;
     regionClass?: string;
     storageGb?: number;
     retentionClass?: string;
@@ -162,7 +264,11 @@ export interface DedicatedRuntimeExecInput {
     timeoutMs?: number;
 }
 export interface DedicatedRuntimeExecResult {
-    /** stdout and stderr, merged in the order the machine produced them, capped at 1 MB. */
+    /**
+     * stdout and stderr together, capped at 1 MB. Each stream keeps its order, but
+     * they are read as two pipes, so their lines can interleave differently from
+     * the order the command wrote them.
+     */
     stdout: string;
     /** null when the command was killed at its deadline. */
     exitCode: number | null;
@@ -252,7 +358,7 @@ export declare function readDedicatedRuntimeFileChunk(leaseId: string, input: {
     path: string;
     offset: number;
     length: number;
-}, scope?: DedicatedRuntimeScope): Promise<DedicatedFileChunk>;
+}, scope?: DedicatedRuntimeScope, signal?: AbortSignal): Promise<DedicatedFileChunk>;
 export declare function writeDedicatedRuntimeFileChunk(leaseId: string, input: {
     path: string;
     transferId: string;
@@ -298,6 +404,13 @@ export declare function dedicatedSpendSummary(lease: DedicatedLease): string;
 /** 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[];
+/** "2026-09-30 14:00 UTC (in 17 days)" — a deadline readable without converting it. */
+export declare function formatDedicatedDeadline(value: string | null | undefined, now?: Date): string;
+/**
+ * The deletion plan as lines for `show`: what will happen and when first, then
+ * why, which notices reached the owner, and what is holding it back.
+ */
+export declare function dedicatedDeletionLines(lease: DedicatedLease, now?: Date): string[];
 /**
  * Every harness row a Dedicated Runtime lease's daemon registered, freshest
  * first.
@@ -387,5 +500,14 @@ export declare function dedicatedCatalogFromProducts(payload: unknown): Dedicate
  * `HTTP_<status>`, the same code `handleApiError` uses for a body with none.
  */
 export declare function dedicatedRuntimeApiErrorCode(err: unknown): string | undefined;
+/**
+ * The public `details` object a refusal carried — `state`, `action` and the
+ * health `reasons` of a failed health check — for the `--json` envelope.
+ *
+ * The server builds it from an allow-list of safe values (reason codes, lease
+ * states), so it is passed through whole rather than re-filtered here, where a
+ * second list would only drift from the first.
+ */
+export declare function dedicatedRuntimeApiErrorDetails(err: unknown): Record<string, unknown> | undefined;
 export declare function formatDedicatedRuntimeApiError(err: unknown): string | null;
 export {};