@skrr-ai/cli 0.1.87 → 0.1.89

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 {
@@ -357,6 +358,34 @@ export declare function restoreDeletedDedicatedRuntime(leaseId: string, options?
  * on the next reconciler pass.
  */
 export declare function setDedicatedRuntimeSpendingLimit(leaseId: string, spendingLimitCents: number | null, scope?: DedicatedRuntimeScope): Promise<DedicatedRuntimeResponse>;
+/**
+ * Whether the agents working on a Dedicated Runtime get a browser (OSK-13809).
+ *
+ * `state` is the machine's setting; `offered` is whether its CONNECTED daemon
+ * offers the browser right now (null: nothing connected, or unreadable). The
+ * two differ after a change until the daemon reconnects, and on an image
+ * without Chrome, which never offers it.
+ */
+export type DedicatedAgentBrowserState = {
+    leaseId: string;
+    state: 'on' | 'off' | 'pending_first_start';
+    enabled: boolean;
+    offered: boolean | null;
+    capability: string;
+    changed?: boolean;
+    effectiveOnNextReconnect?: boolean;
+};
+export declare function getDedicatedRuntimeAgentBrowser(leaseId: string, scope?: DedicatedRuntimeScope): Promise<DedicatedAgentBrowserState>;
+/** Turn the agents' browser on or off. An actual change is in the machine's audit record. */
+export declare function setDedicatedRuntimeAgentBrowser(leaseId: string, enabled: boolean, scope?: DedicatedRuntimeScope): Promise<DedicatedAgentBrowserState>;
+/**
+ * One line for a person. Says the bad cases out loud: a setting that is on
+ * while the connected daemon does not offer it yet, and a setting we could
+ * not read at all.
+ */
+export declare function describeDedicatedAgentBrowser(value: DedicatedAgentBrowserState | {
+    error: string;
+} | null | undefined, leaseId: string): string;
 export declare function closeDedicatedRuntimeIncidentHold(leaseId: string, options?: {
     requestId?: string;
 } & DedicatedRuntimeScope): Promise<DedicatedRuntimeResponse>;
@@ -478,21 +507,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';
@@ -578,6 +655,9 @@ export declare function dedicatedSpendSummary(lease: DedicatedLease): string;
 export declare function describeDedicatedDeletion(deletion: DedicatedLeaseDeletion, leaseId?: string): string;
 export declare function describeDedicatedLease(lease: DedicatedLease, harnesses?: readonly Harness[], opts?: {
     latestDaemonRelease?: LatestDaemonRelease | null;
+    agentBrowser?: DedicatedAgentBrowserState | {
+        error: string;
+    } | null;
 }): 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;