@skrr-ai/cli 0.1.87 → 0.1.88

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

@@ -1,3 +1,5 @@
+import type { ComputerFileEntityTag } from '@skrr-ai/data-provider';
+import { statComputerFile } from './computer-files';
 import { readDedicatedRuntimeFileChunk, writeDedicatedRuntimeFileChunk, type DedicatedRuntimeScope } from './dedicated-machines';
 /**
  * The two copy loops behind `skrr machines dedicated cp`.
@@ -8,6 +10,14 @@ import { readDedicatedRuntimeFileChunk, writeDedicatedRuntimeFileChunk, type Ded
  * stages beside its destination on the machine and the final chunk renames it;
  * a download writes a temporary file beside its local destination and renames.
  *
+ * Every chunk presents the ONE lease generation the command resolved before it
+ * started (review C-01), so a machine replaced mid-copy refuses the remaining
+ * chunks instead of receiving them. And an upload never replaces a destination
+ * it was not told to (review CW-01): it stats the destination first, creates a
+ * new file only if the name is still free at commit (`createOnly`), and
+ * replaces an existing one only when asked to — and then only the exact version
+ * it saw (`replaceTag`).
+ *
  * And neither leaves its partial behind when it is cancelled (OSK-8708).
  * `listenForCopyInterrupt` turns SIGINT, SIGTERM and SIGHUP into an
  * AbortSignal the loops honour; a download also removes its temporary file from
@@ -16,12 +26,25 @@ import { readDedicatedRuntimeFileChunk, writeDedicatedRuntimeFileChunk, type Ded
 export interface DedicatedCopyIo {
     readChunk: typeof readDedicatedRuntimeFileChunk;
     writeChunk: typeof writeDedicatedRuntimeFileChunk;
+    /** How an upload learns what its destination is before it sends a byte. */
+    statPath: typeof statComputerFile;
     chunkBytes: number;
     maxBytes: number;
     /** Run `fn` if the process exits; returns the unregister. Injectable for tests. */
     onProcessExit: (fn: () => void) => () => void;
 }
 export interface DedicatedCopyOptions extends Partial<DedicatedCopyIo> {
+    /**
+     * The lease generation the command resolved at its start
+     * (`resolveDedicatedFileGeneration`), presented on every call of the copy.
+     */
+    generation: number;
+    /** Upload: replace an existing destination (the version the stat found). */
+    overwrite?: boolean;
+    /** Upload: replace exactly this version of the destination, and no other. */
+    ifTag?: ComputerFileEntityTag;
+    /** Upload: told which version is about to be replaced, before any byte is sent. */
+    onReplace?: (destination: string, tag: ComputerFileEntityTag) => void;
     /** Cancels the copy, which then removes its partial file before it rejects. */
     signal?: AbortSignal;
     /** Called after every chunk with the bytes copied so far and the file's size. */
@@ -35,8 +58,8 @@ export interface DedicatedCopyOptions extends Partial<DedicatedCopyIo> {
  * (OSK-8714). Before, these local refusals had no code at all.
  */
 export declare class DedicatedCopyError extends Error {
-    readonly code: 'DEDICATED_RUNTIME_FILE_TOO_LARGE' | 'DEDICATED_RUNTIME_FILE_CHANGED' | 'DEDICATED_RUNTIME_FILE_NOT_FOUND' | 'DEDICATED_RUNTIME_PATH_NOT_A_FILE' | 'DEDICATED_RUNTIME_FILE_TRANSFER_FAILED';
-    constructor(code: 'DEDICATED_RUNTIME_FILE_TOO_LARGE' | 'DEDICATED_RUNTIME_FILE_CHANGED' | 'DEDICATED_RUNTIME_FILE_NOT_FOUND' | 'DEDICATED_RUNTIME_PATH_NOT_A_FILE' | 'DEDICATED_RUNTIME_FILE_TRANSFER_FAILED', message: string);
+    readonly code: 'DEDICATED_RUNTIME_FILE_TOO_LARGE' | 'DEDICATED_RUNTIME_FILE_CHANGED' | 'DEDICATED_RUNTIME_FILE_NOT_FOUND' | 'DEDICATED_RUNTIME_PATH_NOT_A_FILE' | 'DEDICATED_RUNTIME_PATH_IS_DIRECTORY' | 'DEDICATED_RUNTIME_FILE_EXISTS' | 'DEDICATED_RUNTIME_FILE_TRANSFER_FAILED';
+    constructor(code: 'DEDICATED_RUNTIME_FILE_TOO_LARGE' | 'DEDICATED_RUNTIME_FILE_CHANGED' | 'DEDICATED_RUNTIME_FILE_NOT_FOUND' | 'DEDICATED_RUNTIME_PATH_NOT_A_FILE' | 'DEDICATED_RUNTIME_PATH_IS_DIRECTORY' | 'DEDICATED_RUNTIME_FILE_EXISTS' | 'DEDICATED_RUNTIME_FILE_TRANSFER_FAILED', message: string);
 }
 declare const SIGNAL_NUMBERS: {
     readonly SIGHUP: 1;
@@ -76,6 +99,14 @@ export declare function listenForCopyInterrupt({ proc, notice, }?: {
 export interface DedicatedCopyResult {
     bytes: number;
     destination: string;
+    /** Upload: true when the copy created the destination, false when it replaced one. */
+    created?: boolean;
+    /** Upload: the tag of the version that was replaced, as `stat` prints it. */
+    replacedTag?: string;
+    /** Upload: the committed file's tag, as `stat` prints it. */
+    tag?: string;
+    /** Upload: the machine answered from the receipt of an earlier, committed attempt. */
+    alreadyCommitted?: boolean;
 }
 /**
  * One line of progress for a terminal, redrawn in place: a 60 MiB copy takes
@@ -100,13 +131,18 @@ export declare function intoRemoteDirectory(directory: string, name: string): st
  * 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).
+ * did (OSK-8713).
+ *
+ * The destination is stat'ed before any byte is sent, and what the copy may do
+ * to it is decided then and enforced at commit by the machine (review CW-01):
  *
- * `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.
+ * - nothing there → the copy creates it, and commits only if the name is still
+ *   free (`createOnly`); something that appears meanwhile is never replaced;
+ * - a file there → refused before sending anything, unless `overwrite` (replace
+ *   the version the stat found) or `ifTag` (replace exactly that version) was
+ *   given; either way the commit replaces only that version (`replaceTag`), and
+ *   a file changed during the copy is refused `file_changed`, nothing replaced.
  */
-export declare function uploadToDedicatedRuntime(localPath: string, leaseId: string, remotePath: string, scope?: DedicatedRuntimeScope, io?: DedicatedCopyOptions): Promise<DedicatedCopyResult>;
-export declare function downloadFromDedicatedRuntime(leaseId: string, remotePath: string, localPath: string, scope?: DedicatedRuntimeScope, io?: DedicatedCopyOptions): Promise<DedicatedCopyResult>;
+export declare function uploadToDedicatedRuntime(localPath: string, leaseId: string, remotePath: string, scope: DedicatedRuntimeScope, io: DedicatedCopyOptions): Promise<DedicatedCopyResult>;
+export declare function downloadFromDedicatedRuntime(leaseId: string, remotePath: string, localPath: string, scope: DedicatedRuntimeScope, io: DedicatedCopyOptions): Promise<DedicatedCopyResult>;
 export {};

package/dist/lib/dedicated-copy.js

@@ -12,6 +12,7 @@ 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 computer_files_1 = require("./computer-files");
 const dedicated_file_retry_1 = require("./dedicated-file-retry");
 const dedicated_machines_1 = require("./dedicated-machines");
 /**
@@ -34,6 +35,7 @@ const changedWhileCopying = (path, where) => new DedicatedCopyError('DEDICATED_R
 const defaultIo = {
     readChunk: dedicated_machines_1.readDedicatedRuntimeFileChunk,
     writeChunk: dedicated_machines_1.writeDedicatedRuntimeFileChunk,
+    statPath: computer_files_1.statComputerFile,
     chunkBytes: dedicated_machines_1.DEDICATED_FILE_CHUNK_BYTES,
     maxBytes: dedicated_machines_1.DEDICATED_FILE_MAX_BYTES,
     onProcessExit: (fn) => {
@@ -138,51 +140,107 @@ 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;
+/**
+ * Stat one machine path for an upload. A path that does not exist is `absent`
+ * — the copy creates it, and any missing parent with it. Every other refusal
+ * (withheld, stale generation, the machine unreachable) is the copy's refusal.
+ */
+async function statDestination(statPath, leaseId, remotePath, generation, scope, signal) {
+    let result;
+    try {
+        result = await (0, dedicated_file_retry_1.withFileAdmissionRetry)(() => statPath(leaseId, { path: remotePath, generation }, scope), signal);
+    }
+    catch (err) {
+        const refusal = (0, computer_files_1.computerFileRefusalInfo)(err);
+        // `details.path` (or a path-shaped message) marks a missing PATH; without
+        // it the machine itself was not found, which is not a destination to create.
+        if (refusal?.code === 'not_found' &&
+            (refusal.details?.path !== undefined || /path|file|folder|directory/i.test(refusal.message))) {
+            return { kind: 'absent' };
+        }
+        throw err;
+    }
+    const type = result.entry.type;
+    if (type === 'directory')
+        return { kind: 'directory' };
+    if (type === 'file' && result.tag) {
+        return {
+            kind: 'file',
+            tag: { inode: result.tag.inode, size: result.tag.size, mtimeNs: result.tag.mtimeNs },
+        };
     }
+    return { kind: 'other', type };
 }
+const sameTag = (a, b) => a.inode === b.inode && a.size === b.size && a.mtimeNs === b.mtimeNs;
 /**
  * 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).
+ * did (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.
+ * The destination is stat'ed before any byte is sent, and what the copy may do
+ * to it is decided then and enforced at commit by the machine (review CW-01):
+ *
+ * - nothing there → the copy creates it, and commits only if the name is still
+ *   free (`createOnly`); something that appears meanwhile is never replaced;
+ * - a file there → refused before sending anything, unless `overwrite` (replace
+ *   the version the stat found) or `ifTag` (replace exactly that version) was
+ *   given; either way the commit replaces only that version (`replaceTag`), and
+ *   a file changed during the copy is refused `file_changed`, nothing replaced.
  */
-async function uploadToDedicatedRuntime(localPath, leaseId, remotePath, scope = {}, io = {}) {
-    const intoDirectory = (directory) => intoRemoteDirectory(directory, (0, node_path_1.basename)(localPath));
-    const attempt = async (target) => {
-        try {
-            return await uploadFile(localPath, leaseId, target, scope, io);
+async function uploadToDedicatedRuntime(localPath, leaseId, remotePath, scope, io) {
+    const { statPath, signal, generation } = { ...defaultIo, ...io };
+    throwIfCancelled(signal);
+    const info = await localSourceInfo(localPath, { ...defaultIo, ...io }.maxBytes);
+    const shown = (target) => `${leaseId}:${target}`;
+    let target = namesRemoteDirectory(remotePath)
+        ? intoRemoteDirectory(remotePath, (0, node_path_1.basename)(localPath))
+        : remotePath;
+    let destination = await statDestination(statPath, leaseId, target, generation, scope, signal);
+    if (destination.kind === 'directory' && target === remotePath) {
+        // An existing directory named without the slash: into it, once.
+        target = intoRemoteDirectory(remotePath, (0, node_path_1.basename)(localPath));
+        destination = await statDestination(statPath, leaseId, target, generation, scope, signal);
+    }
+    if (destination.kind === 'directory') {
+        throw new DedicatedCopyError('DEDICATED_RUNTIME_PATH_IS_DIRECTORY', `${shown(target)} is a directory on the machine; nothing was sent.`);
+    }
+    if (destination.kind === 'other') {
+        throw new DedicatedCopyError('DEDICATED_RUNTIME_PATH_NOT_A_FILE', `${shown(target)} is a ${destination.type} on the machine, not a regular file; cp does not replace it. Nothing was sent.`);
+    }
+    let condition;
+    let replacedTag;
+    if (destination.kind === 'absent') {
+        if (io.ifTag) {
+            throw new DedicatedCopyError('DEDICATED_RUNTIME_FILE_CHANGED', `${shown(target)} is no longer there, so the version --if-tag ${(0, computer_files_1.computerFileTagString)(io.ifTag)} names cannot be replaced. Nothing was sent; copy again without --if-tag to create it.`);
         }
-        catch (err) {
-            throw err instanceof DestinationIsDirectory ? err.refusal : err;
+        condition = { createOnly: true };
+    }
+    else if (io.ifTag) {
+        if (!sameTag(io.ifTag, destination.tag)) {
+            throw new DedicatedCopyError('DEDICATED_RUNTIME_FILE_CHANGED', `${shown(target)} changed since --if-tag ${(0, computer_files_1.computerFileTagString)(io.ifTag)} was read; its current tag is ${(0, computer_files_1.computerFileTagString)(destination.tag)}. Nothing was sent or replaced.`);
         }
-    };
-    if (namesRemoteDirectory(remotePath)) {
-        return attempt(intoDirectory(remotePath));
+        replacedTag = destination.tag;
+        condition = { replaceTag: destination.tag };
     }
-    try {
-        return await uploadFile(localPath, leaseId, remotePath, scope, io);
+    else if (io.overwrite) {
+        replacedTag = destination.tag;
+        condition = { replaceTag: destination.tag };
     }
-    catch (err) {
-        if (err instanceof DestinationIsDirectory)
-            return attempt(intoDirectory(remotePath));
-        throw err;
+    else {
+        throw new DedicatedCopyError('DEDICATED_RUNTIME_FILE_EXISTS', `${shown(target)} already exists (tag ${(0, computer_files_1.computerFileTagString)(destination.tag)}). Nothing was sent. Pass --overwrite to replace it, or --if-tag ${(0, computer_files_1.computerFileTagString)(destination.tag)} to replace exactly this version.`);
     }
+    if (replacedTag)
+        io.onReplace?.(shown(target), replacedTag);
+    const result = await uploadFile(localPath, info, leaseId, target, scope, io, condition);
+    return {
+        ...result,
+        created: replacedTag === undefined,
+        ...(replacedTag ? { replacedTag: (0, computer_files_1.computerFileTagString)(replacedTag) } : {}),
+    };
 }
-async function uploadFile(localPath, leaseId, remotePath, scope, io) {
-    const { writeChunk, chunkBytes, maxBytes, signal, onProgress } = { ...defaultIo, ...io };
-    throwIfCancelled(signal);
+/** The local source of an upload: a regular file within the size limit. */
+async function localSourceInfo(localPath, maxBytes) {
     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.
@@ -197,6 +255,34 @@ async function uploadFile(localPath, leaseId, remotePath, scope, io) {
     if (info.size > maxBytes) {
         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.`);
     }
+    return info;
+}
+/**
+ * The commit's own refusal of the condition the upload carried, in the copy's
+ * words: the destination changed (or appeared) DURING the copy and nothing was
+ * replaced. Anything else passes through unchanged.
+ */
+function commitConditionRefusal(err, shownTarget) {
+    const refusal = (0, computer_files_1.computerFileRefusalInfo)(err);
+    if (!refusal)
+        return err;
+    if (refusal.code === 'file_changed') {
+        let now = '';
+        if (refusal.currentTag !== undefined) {
+            now = ` Its current tag is ${(0, computer_files_1.computerFileTagString)(refusal.currentTag)}.`;
+        }
+        else if (refusal.body.currentTag === null) {
+            now = ' It is no longer there.';
+        }
+        return new DedicatedCopyError('DEDICATED_RUNTIME_FILE_CHANGED', `${shownTarget} changed on the machine during the copy, so nothing was replaced.${now} Look at it with \`stat\`, then copy again.`);
+    }
+    if (refusal.code === 'invalid_request' && refusal.details?.reason === 'exists') {
+        return new DedicatedCopyError('DEDICATED_RUNTIME_FILE_EXISTS', `${shownTarget} appeared on the machine during the copy, so nothing was replaced. Copy again with --overwrite if you mean to replace it.`);
+    }
+    return err;
+}
+async function uploadFile(localPath, info, leaseId, remotePath, scope, io, condition) {
+    const { writeChunk, chunkBytes, signal, onProgress, generation } = { ...defaultIo, ...io };
     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;
@@ -217,36 +303,45 @@ async function uploadFile(localPath, leaseId, remotePath, scope, io) {
                 path: remotePath,
                 transferId,
                 offset,
+                generation,
                 dataBase64: buffer.subarray(0, bytesRead).toString('base64'),
+                // On every chunk, so a machine whose image cannot honour the
+                // condition refuses the FIRST chunk, before anything is staged.
+                ...condition,
                 // A file that GREW is caught here: the machine refuses to commit
                 // when what it staged is not the size declared at the start.
-                ...(final ? { final: true, totalSize: info.size, executable: (info.mode & 0o111) !== 0 } : {}),
+                ...(final
+                    ? { final: true, totalSize: info.size, executable: (info.mode & 0o111) !== 0 }
+                    : {}),
             }, scope), signal);
             offset += bytesRead;
             onProgress?.(offset, info.size);
-            if (final) {
-                return { bytes: offset, destination: `${leaseId}:${result.path || remotePath}` };
+            // A receipt (`alreadyCommitted`) is the same success: this transfer
+            // committed earlier and only its acknowledgement was lost.
+            if (final || result.alreadyCommitted === true) {
+                return {
+                    bytes: info.size,
+                    destination: `${leaseId}:${result.path || remotePath}`,
+                    ...(result.tag ? { tag: (0, computer_files_1.computerFileTagString)(result.tag) } : {}),
+                    ...(result.alreadyCommitted === true ? { alreadyCommitted: true } : {}),
+                };
             }
         }
     }
     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. 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;
+        await writeChunk(leaseId, { path: remotePath, transferId, offset: 0, abort: true, generation }, scope).catch(() => undefined);
+        throw commitConditionRefusal(err, `${leaseId}:${remotePath}`);
     }
     finally {
         await handle.close();
     }
 }
-async function downloadFromDedicatedRuntime(leaseId, remotePath, localPath, scope = {}, io = {}) {
+async function downloadFromDedicatedRuntime(leaseId, remotePath, localPath, scope, io) {
     const { readChunk, chunkBytes, onProcessExit, signal, onProgress } = { ...defaultIo, ...io };
     throwIfCancelled(signal);
     let target = localPath;
@@ -282,14 +377,16 @@ async function downloadFromDedicatedRuntime(leaseId, remotePath, localPath, scop
             throwIfCancelled(signal);
             // Nothing on the machine needs undoing, so an in-flight read is abandoned
             // at once rather than waited out.
-            const chunk = await (0, dedicated_file_retry_1.withFileAdmissionRetry)(() => readChunk(leaseId, { path: remotePath, offset, length: chunkBytes }, scope, signal), signal);
+            const chunk = await (0, dedicated_file_retry_1.withFileAdmissionRetry)(() => readChunk(leaseId, { path: remotePath, offset, length: chunkBytes, generation: io.generation }, scope, signal), signal);
             if (size === -1) {
                 size = chunk.size;
                 mtimeMs = chunk.mtimeMs;
                 executable = chunk.executable;
             }
-            else if (chunk.size !== size || chunk.mtimeMs !== mtimeMs ||
-                (typeof chunk.executable === 'boolean' && typeof executable === 'boolean' &&
+            else if (chunk.size !== size ||
+                chunk.mtimeMs !== mtimeMs ||
+                (typeof chunk.executable === 'boolean' &&
+                    typeof executable === 'boolean' &&
                     chunk.executable !== executable)) {
                 // Chunks from two versions of a file splice into one that never existed.
                 throw changedWhileCopying(remotePath, 'on the machine');

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

@@ -285,6 +285,7 @@ export declare function dedicatedRuntimeCreateInput(input: {
  * billable request is sent.
  */
 export declare function isDedicatedRepositoryRef(value: string): boolean;
+export declare function withDedicatedScope(path: string, scope: DedicatedRuntimeScope, query?: Record<string, string>): string;
 export declare function createDedicatedRuntime(input: CreateDedicatedRuntimeInput): Promise<DedicatedRuntimeResponse>;
 /** One offered tier as the operator price book checks it. */
 export interface DedicatedPriceBookPresetCheck {
@@ -478,21 +479,69 @@ export interface DedicatedFileWriteResult {
     staged: number;
     committed: boolean;
     aborted?: boolean;
+    /** On commit: the committed file's entity tag. */
+    tag?: {
+        inode: string;
+        size: number;
+        mtimeNs: string;
+    };
+    /**
+     * This transfer had ALREADY committed (review CW-02): the answer is its
+     * receipt, and nothing was written again — a retried final chunk whose first
+     * acknowledgement was lost. A success, never a reason to upload again.
+     */
+    alreadyCommitted?: boolean;
 }
+/**
+ * `lease:<leaseId>` is the machine id the computer file routes address a
+ * Dedicated Runtime by (`/api/machines/:machineId/files/*`, authorised by
+ * ComputerAccess), the same id the machine inventory uses.
+ */
+export declare const computerMachineId: (leaseId: string) => string;
+/**
+ * The computer's page for a Dedicated Runtime — `/machines/<machineId>/computer`
+ * (the route `paneRouteConfig` serves the computer shell at, design §11).
+ * Composed on the `machine` web route rather than concatenated against baseURL,
+ * so the `api.`-subdomain → apex origin mapping stays the one in web-url.ts.
+ */
+export declare function dedicatedComputerUrl(baseURL: string, leaseId: string): string | null;
+/**
+ * One chunk of a download. `generation` is the lease generation the `cp`
+ * command resolved at its start, presented on every chunk (review C-01): a
+ * machine replaced mid-copy refuses the rest `stale_generation`.
+ */
 export declare function readDedicatedRuntimeFileChunk(leaseId: string, input: {
     path: string;
     offset: number;
     length: number;
+    generation: number;
 }, scope?: DedicatedRuntimeScope, signal?: AbortSignal): Promise<DedicatedFileChunk>;
+/**
+ * One call of a chunked upload. `generation` fences every chunk to the machine
+ * the command resolved (review C-01). How the commit treats a destination is
+ * the caller's explicit choice (review CW-01), never an unconditional replace:
+ * `createOnly` commits only if nothing has the name (else 409
+ * `invalid_request`/`exists`); `replaceTag` commits only over the file with
+ * exactly that tag (else 409 `file_changed` with `currentTag`, null when it is
+ * gone). Never both. Each needs `computer_files_fenced_v1` on the machine.
+ */
 export declare function writeDedicatedRuntimeFileChunk(leaseId: string, input: {
     path: string;
     transferId: string;
     offset: number;
+    generation: number;
     dataBase64?: string;
     final?: boolean;
     abort?: boolean;
+    query?: boolean;
     totalSize?: number;
     executable?: boolean;
+    createOnly?: boolean;
+    replaceTag?: {
+        inode: string;
+        size: number;
+        mtimeNs: string;
+    };
 }, scope?: DedicatedRuntimeScope): Promise<DedicatedFileWriteResult>;
 export type DedicatedCopyPlan = {
     direction: 'upload';

package/dist/lib/dedicated-machines.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEDICATED_FILE_MAX_BYTES = exports.DEDICATED_FILE_CHUNK_BYTES = exports.DEDICATED_EXEC_DEFAULT_TIMEOUT_MS = exports.DEDICATED_EXEC_MAX_TIMEOUT_MS = exports.DEDICATED_MACHINE_PRODUCT = exports.DEDICATED_LEASE_ACTIONS = void 0;
+exports.computerMachineId = exports.DEDICATED_FILE_MAX_BYTES = exports.DEDICATED_FILE_CHUNK_BYTES = exports.DEDICATED_EXEC_DEFAULT_TIMEOUT_MS = exports.DEDICATED_EXEC_MAX_TIMEOUT_MS = exports.DEDICATED_MACHINE_PRODUCT = exports.DEDICATED_LEASE_ACTIONS = void 0;
 exports.describeDedicatedCheckpoint = describeDedicatedCheckpoint;
 exports.compareDaemonVersions = compareDaemonVersions;
 exports.describeDedicatedDaemonRelease = describeDedicatedDaemonRelease;
 exports.describeDedicatedImageStanding = describeDedicatedImageStanding;
 exports.dedicatedRuntimeCreateInput = dedicatedRuntimeCreateInput;
 exports.isDedicatedRepositoryRef = isDedicatedRepositoryRef;
+exports.withDedicatedScope = withDedicatedScope;
 exports.createDedicatedRuntime = createDedicatedRuntime;
 exports.getDedicatedOperatorPriceBook = getDedicatedOperatorPriceBook;
 exports.dedicatedOperatorPriceBookLines = dedicatedOperatorPriceBookLines;
@@ -22,6 +23,7 @@ exports.execDedicatedRuntime = execDedicatedRuntime;
 exports.getDedicatedRuntimeSignInStatus = getDedicatedRuntimeSignInStatus;
 exports.startDedicatedRuntimeExecution = startDedicatedRuntimeExecution;
 exports.observeDedicatedRuntimeExecution = observeDedicatedRuntimeExecution;
+exports.dedicatedComputerUrl = dedicatedComputerUrl;
 exports.readDedicatedRuntimeFileChunk = readDedicatedRuntimeFileChunk;
 exports.writeDedicatedRuntimeFileChunk = writeDedicatedRuntimeFileChunk;
 exports.parseDedicatedCopyEndpoints = parseDedicatedCopyEndpoints;
@@ -53,6 +55,7 @@ const auth_core_1 = require("@skrr-ai/auth-core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const api_fetch_1 = require("./api-fetch");
 const machine_spend_cap_1 = require("./machine-spend-cap");
+const web_url_1 = require("./web-url");
 const edge_error_page_1 = require("./edge-error-page");
 const harnesses_1 = require("./harnesses");
 exports.DEDICATED_LEASE_ACTIONS = [
@@ -445,11 +448,89 @@ async function observeDedicatedRuntimeExecution(leaseId, executionId, options) {
 /** 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;
+/**
+ * `lease:<leaseId>` is the machine id the computer file routes address a
+ * Dedicated Runtime by (`/api/machines/:machineId/files/*`, authorised by
+ * ComputerAccess), the same id the machine inventory uses.
+ */
+const computerMachineId = (leaseId) => `lease:${leaseId}`;
+exports.computerMachineId = computerMachineId;
+/**
+ * The computer's page for a Dedicated Runtime — `/machines/<machineId>/computer`
+ * (the route `paneRouteConfig` serves the computer shell at, design §11).
+ * Composed on the `machine` web route rather than concatenated against baseURL,
+ * so the `api.`-subdomain → apex origin mapping stays the one in web-url.ts.
+ */
+function dedicatedComputerUrl(baseURL, leaseId) {
+    const page = (0, web_url_1.webUrl)(baseURL, { kind: 'machine', machineId: (0, exports.computerMachineId)(leaseId) });
+    return page ? `${page}/computer` : null;
+}
+const LEGACY_FILE_CODES = {
+    file_changed: 'DEDICATED_RUNTIME_FILE_CHANGED',
+    too_large: 'DEDICATED_RUNTIME_FILE_TOO_LARGE',
+    not_found: 'DEDICATED_RUNTIME_FILE_NOT_FOUND',
+};
+/**
+ * The copy loop branches on the `DEDICATED_RUNTIME_*` code a refused chunk
+ * carried (a destination that is a directory, a file that changed). The file
+ * routes answer in the computer's wire vocabulary and keep the specific cause in
+ * `details.reason`, so a refusal is re-coded here, at the one place that knows
+ * about the copy loop, rather than the loop learning two vocabularies.
+ */
+function withCopyLoopCode(err) {
+    if (!(err instanceof api_fetch_1.ApiFetchError))
+        return err;
+    let reason;
+    try {
+        reason = JSON.parse(err.body ?? '{}').details?.reason;
+    }
+    catch {
+        reason = undefined;
+    }
+    const code = typeof reason === 'string' && reason.startsWith('DEDICATED_RUNTIME_')
+        ? reason
+        : err.code
+            ? LEGACY_FILE_CODES[err.code]
+            : undefined;
+    if (code)
+        err.code = code;
+    return err;
+}
+/**
+ * One chunk of a download. `generation` is the lease generation the `cp`
+ * command resolved at its start, presented on every chunk (review C-01): a
+ * machine replaced mid-copy refuses the rest `stale_generation`.
+ */
 async function readDedicatedRuntimeFileChunk(leaseId, input, scope = {}, signal) {
-    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/files/read`, scope), { method: 'POST', body: input, ...(signal ? { signal } : {}) });
+    const wire = await (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/${encodeURIComponent((0, exports.computerMachineId)(leaseId))}/files/read`, scope), { method: 'POST', body: input, ...(signal ? { signal } : {}) }).catch((err) => {
+        throw withCopyLoopCode(err);
+    });
+    return {
+        path: wire.path,
+        size: wire.size,
+        // The tag's nanosecond mtime, as the whole-millisecond value the copy loop
+        // compares between chunks to notice a file that changed under it.
+        mtimeMs: Number(BigInt(wire.tag.mtimeNs) / 1000000n),
+        ...(typeof wire.executable === 'boolean' ? { executable: wire.executable } : {}),
+        offset: wire.offset,
+        bytesRead: Buffer.from(wire.data, 'base64').byteLength,
+        dataBase64: wire.data,
+        eof: wire.eof,
+    };
 }
+/**
+ * One call of a chunked upload. `generation` fences every chunk to the machine
+ * the command resolved (review C-01). How the commit treats a destination is
+ * the caller's explicit choice (review CW-01), never an unconditional replace:
+ * `createOnly` commits only if nothing has the name (else 409
+ * `invalid_request`/`exists`); `replaceTag` commits only over the file with
+ * exactly that tag (else 409 `file_changed` with `currentTag`, null when it is
+ * gone). Never both. Each needs `computer_files_fenced_v1` on the machine.
+ */
 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 });
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/${encodeURIComponent((0, exports.computerMachineId)(leaseId))}/files/write`, scope), { method: 'POST', body: input }).catch((err) => {
+        throw withCopyLoopCode(err);
+    });
 }
 const REMOTE_ENDPOINT = /^(rtl_[A-Za-z0-9_-]{1,80}):(.+)$/;
 /**
@@ -570,7 +651,8 @@ function dedicatedSpendSummary(lease) {
     if (!billing)
         return '-';
     const cap = billing.monthlySpendLimitCents !== undefined
-        ? billing.monthlySpendLimitCents : billing.spendingLimitCents;
+        ? billing.monthlySpendLimitCents
+        : billing.spendingLimitCents;
     if (billing.spendStatusUnavailable) {
         return `spend unavailable right now · ${cap === null ? 'no monthly cap' : `cap ${formatUsdCents(cap)}`}`;
     }
@@ -647,6 +729,12 @@ function describeDedicatedLease(lease, harnesses = [], opts = {}) {
     row('state', lease.stateReason
         ? `${dedicatedLeaseState(lease)} (${lease.stateReason})`
         : dedicatedLeaseState(lease));
+    // A reason the platform wrote for its own stop gets a sentence, not just a code: the
+    // code names an internal rule and leaves the owner asking where their machine went
+    // (OSK-13732). A reason with no copy keeps printing as the code above.
+    const stateReasonCopy = (0, data_provider_1.describeMachineStateReason)(lease.stateReason);
+    if (stateReasonCopy)
+        row('why', stateReasonCopy);
     const resources = lease.resources || {};
     const size = [
         resources.sizePreset,
@@ -1119,10 +1207,13 @@ function dedicatedCreateSummary(catalog, choices) {
         : 'server default';
     const retains = retentionClass !== undefined && retentionClass !== 'none';
     const capCents = choices.spendingLimitCents !== undefined
-        ? choices.spendingLimitCents : catalog?.defaultMonthlySpendingLimitCents;
+        ? choices.spendingLimitCents
+        : catalog?.defaultMonthlySpendingLimitCents;
     const cap = capCents !== undefined && capCents !== null
         ? `${formatUsdCents(capCents)} per month${choices.spendingLimitCents === undefined ? ' (catalog default)' : ''}`
-        : capCents === null ? 'no cap — compute and retained storage still bill' : 'server default';
+        : capCents === null
+            ? 'no cap — compute and retained storage still bill'
+            : 'server default';
     return [
         `Create Dedicated Runtime "${choices.name}" — it bills while it runs:`,
         `  size         ${choices.sizePreset} — ${spec}`,

package/dist/lib/label-scope.d.ts

@@ -39,6 +39,18 @@ export declare const labelScopeFlags: {
     scope: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
     'scope-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
 };
+/**
+ * `--allow-duplicate-name`, shared by every command that can put a live name
+ * into a scope (create, rename, restore).
+ *
+ * The SERVER owns the rule (`LabelService.assertNameFreeInOtherScope`): a name
+ * another label you can use already carries is refused with
+ * `409 duplicate_name_other_scope`, and the refusal names that label. The CLI
+ * only relays the override, so every surface — web, MCP, CLI — gets one answer.
+ */
+export declare const allowDuplicateNameFlags: {
+    'allow-duplicate-name': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+};
 export interface ResolvedLabelScope {
     scope: LabelScope;
     scopeId?: string;