@skrr-ai/cli 0.1.87 → 0.1.88

package/dist/lib/computer-files.js

@@ -0,0 +1,707 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DedicatedFileGenerationUnavailableError = void 0;
+exports.resolveDedicatedFileGeneration = resolveDedicatedFileGeneration;
+exports.listComputerFiles = listComputerFiles;
+exports.statComputerFile = statComputerFile;
+exports.searchComputerFiles = searchComputerFiles;
+exports.gitStatusComputerFiles = gitStatusComputerFiles;
+exports.mkdirComputerFile = mkdirComputerFile;
+exports.moveComputerFile = moveComputerFile;
+exports.deleteComputerFile = deleteComputerFile;
+exports.prepareComputerFileArchive = prepareComputerFileArchive;
+exports.readComputerFileArchiveChunk = readComputerFileArchiveChunk;
+exports.releaseComputerFileArchive = releaseComputerFileArchive;
+exports.computerFileArchiveDestination = computerFileArchiveDestination;
+exports.downloadComputerFileArchive = downloadComputerFileArchive;
+exports.computerFileTagString = computerFileTagString;
+exports.parseComputerFileTag = parseComputerFileTag;
+exports.computerFileModeString = computerFileModeString;
+exports.formatComputerFileSize = formatComputerFileSize;
+exports.computerFileEntryName = computerFileEntryName;
+exports.computerFileSearchHitLine = computerFileSearchHitLine;
+exports.computerFileSearchLines = computerFileSearchLines;
+exports.computerFileGitStatusLines = computerFileGitStatusLines;
+exports.computerFileRefusalBody = computerFileRefusalBody;
+exports.computerFileRefusalInfo = computerFileRefusalInfo;
+exports.describeComputerFileRefusal = describeComputerFileRefusal;
+exports.describeComputerFileFailure = describeComputerFileFailure;
+/**
+ * computer-files.ts — the computer's file surface from the CLI:
+ * `skrr machines dedicated ls|stat|search|git-status|mkdir|mv|rm|archive`, each a POST to
+ * `/api/machines/:machineId/files/<op>` (design §6.3; routes OSK-13455; CLI
+ * parity OSK-13463). `read` and the chunked `write` stay in
+ * dedicated-machines.ts behind `cp`.
+ *
+ * Every call is an `apiFetch` against a LITERAL path: the parity reader
+ * (cli/src/__tests__/helpers/api-surface.ts) resolves which routes a lib
+ * reaches by reading the literal at the call site, and a path composed inside
+ * a helper reads as an unreachable route — the reading that trains people to
+ * allowlist things that are fine.
+ *
+ * Refusals come back in the COMPUTER vocabulary, not DEDICATED_RUNTIME_*: the
+ * body is `{error, code, message, ...}` with `code` from
+ * `COMPUTER_REFUSAL_CODES` — `file_changed` (409, carrying `currentTag`),
+ * `too_large` (413, `details.maxBytes`), `path_withheld` (403, `details.rule`
+ * when a rule withheld it), `capability_missing`, `stale_generation`,
+ * `machine_unavailable`, `daemon_unreachable`, `timeout`, `consent_missing`,
+ * `unauthorized`, `rate_limited`, and `invalid_request` whose `details.reason`
+ * names the daemon-side cause (`exists`, `not_empty`, `is_directory`,
+ * `not_directory`, `into_itself`, `bad_cursor`, `is_root`, `too_many`,
+ * `bad_name`, `contents_tag_required`).
+ *
+ * Every call carries `generation` — the lease generation the COMMAND's view of
+ * the machine was made on (review C-01). A command resolves it once, with
+ * `resolveDedicatedFileGeneration`, before its first file call and presents
+ * that same number on every call it makes, so a machine replaced while the
+ * command runs refuses the rest (`stale_generation`) instead of the remaining
+ * calls landing on the replacement. A call without one is refused too
+ * (`details.reason: 'generation_required'`).
+ */
+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 data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../base-command");
+const api_fetch_1 = require("./api-fetch");
+const dedicated_machines_1 = require("./dedicated-machines");
+const dedicated_file_retry_1 = require("./dedicated-file-retry");
+/**
+ * The lease could not say which generation is running — a server that does not
+ * publish it yet, or a lease with none. File calls cannot be fenced without
+ * one, and the server refuses them unfenced, so the command stops here.
+ */
+class DedicatedFileGenerationUnavailableError extends Error {
+    code = 'DEDICATED_RUNTIME_GENERATION_UNAVAILABLE';
+    constructor(leaseId) {
+        super(`The server did not say which generation of ${leaseId} is running, so its files cannot be reached safely. ` +
+            'Try again; if it persists, the API is older than this CLI.');
+        this.name = 'DedicatedFileGenerationUnavailableError';
+    }
+}
+exports.DedicatedFileGenerationUnavailableError = DedicatedFileGenerationUnavailableError;
+/**
+ * Read the lease once and return the generation every file call of this
+ * command presents. Resolved at the START of a command and never again: a
+ * second read mid-command would follow a replacement, which is exactly what
+ * the fence exists to refuse.
+ */
+async function resolveDedicatedFileGeneration(leaseId, scope = {}) {
+    const response = await (0, dedicated_machines_1.getDedicatedRuntime)(leaseId, scope);
+    const generation = response?.lease?.generation;
+    if (typeof generation !== 'number' || !Number.isSafeInteger(generation) || generation < 1) {
+        throw new DedicatedFileGenerationUnavailableError(leaseId);
+    }
+    return generation;
+}
+// ---------------------------------------------------------------------------
+// Operations
+// ---------------------------------------------------------------------------
+/**
+ * List one directory on the machine, one page. `cursor` continues an earlier
+ * page's `nextCursor`; a withheld entry comes back with `withheld.reason`
+ * rather than silently absent (§18).
+ */
+async function listComputerFiles(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)((0, dedicated_machines_1.withDedicatedScope)(`/api/machines/${encodeURIComponent((0, dedicated_machines_1.computerMachineId)(leaseId))}/files/list`, scope), {
+        method: 'POST',
+        body: {
+            path: input.path,
+            generation: input.generation,
+            ...(input.cursor ? { cursor: input.cursor } : {}),
+            ...(input.limit !== undefined ? { limit: input.limit } : {}),
+        },
+    });
+}
+/**
+ * Stat one path — the entry, and its optimistic-concurrency `tag`. With
+ * `contents` a folder's tag also carries `contents` (a digest of everything
+ * inside it, at any depth) and the answer its total `entries`: the tag a
+ * fenced recursive delete presents. Needs `computer_files_fenced_v1`.
+ */
+async function statComputerFile(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)((0, dedicated_machines_1.withDedicatedScope)(`/api/machines/${encodeURIComponent((0, dedicated_machines_1.computerMachineId)(leaseId))}/files/stat`, scope), {
+        method: 'POST',
+        body: {
+            path: input.path,
+            generation: input.generation,
+            ...(input.contents === true ? { contents: true } : {}),
+        },
+    });
+}
+/**
+ * Search under a folder by file name or (`content`) by text. The answer carries
+ * its own `state` and the bounds that applied — see `computerFileSearchLines`
+ * for saying them. Defaults (ignore rules honoured, the machine's limit and
+ * time bound) are the machine's, so only what the caller set is sent.
+ */
+async function searchComputerFiles(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)((0, dedicated_machines_1.withDedicatedScope)(`/api/machines/${encodeURIComponent((0, dedicated_machines_1.computerMachineId)(leaseId))}/files/search`, scope), {
+        method: 'POST',
+        body: {
+            path: input.path,
+            query: input.query,
+            generation: input.generation,
+            mode: input.content === true ? 'content' : 'name',
+            ...(input.respectIgnore !== undefined ? { respectIgnore: input.respectIgnore } : {}),
+            ...(input.caseSensitive === true ? { caseSensitive: true } : {}),
+            ...(input.limit !== undefined ? { limit: input.limit } : {}),
+            ...(input.budgetMs !== undefined ? { budgetMs: input.budgetMs } : {}),
+        },
+    });
+}
+/** The git marks of one folder's entries (`modified`, `untracked`, …). */
+async function gitStatusComputerFiles(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)((0, dedicated_machines_1.withDedicatedScope)(`/api/machines/${encodeURIComponent((0, dedicated_machines_1.computerMachineId)(leaseId))}/files/gitstatus`, scope), { method: 'POST', body: { path: input.path, generation: input.generation } });
+}
+/** Create a directory, including missing parents. */
+async function mkdirComputerFile(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)((0, dedicated_machines_1.withDedicatedScope)(`/api/machines/${encodeURIComponent((0, dedicated_machines_1.computerMachineId)(leaseId))}/files/mkdir`, scope), { method: 'POST', body: { path: input.path, generation: input.generation } });
+}
+/**
+ * Rename or move one path. `tag` fences it: the move is refused `file_changed`
+ * when the source no longer matches the tag it was read with.
+ */
+async function moveComputerFile(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)((0, dedicated_machines_1.withDedicatedScope)(`/api/machines/${encodeURIComponent((0, dedicated_machines_1.computerMachineId)(leaseId))}/files/move`, scope), {
+        method: 'POST',
+        body: {
+            from: input.from,
+            to: input.to,
+            generation: input.generation,
+            ...(input.tag ? { tag: input.tag } : {}),
+        },
+    });
+}
+/**
+ * Delete one path. A folder is refused `not_empty` unless `recursive` is asked
+ * for; `tag` fences the delete against a file that changed since it was read.
+ * A RECURSIVE delete with a tag must present the folder's contents tag
+ * (`statComputerFile({contents: true})`): anything changed inside it since is
+ * refused `file_changed`, and a tag without `contents` is refused
+ * `contents_tag_required`. A recursive delete without a tag is unfenced.
+ */
+async function deleteComputerFile(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)((0, dedicated_machines_1.withDedicatedScope)(`/api/machines/${encodeURIComponent((0, dedicated_machines_1.computerMachineId)(leaseId))}/files/delete`, scope), {
+        method: 'POST',
+        body: {
+            path: input.path,
+            generation: input.generation,
+            ...(input.tag ? { tag: input.tag } : {}),
+            ...(input.recursive === true ? { recursive: true } : {}),
+        },
+    });
+}
+/**
+ * Stage a folder's archive on the machine (`archive` prepare). The machine
+ * holds the staged bytes until `releaseComputerFileArchive` — or until its own
+ * stale-staging sweep — so callers always release.
+ */
+async function prepareComputerFileArchive(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)((0, dedicated_machines_1.withDedicatedScope)(`/api/machines/${encodeURIComponent((0, dedicated_machines_1.computerMachineId)(leaseId))}/files/archive`, scope), { method: 'POST', body: { path: input.path, generation: input.generation } });
+}
+/** One chunk of a staged archive; `eof` ends the read. */
+async function readComputerFileArchiveChunk(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)((0, dedicated_machines_1.withDedicatedScope)(`/api/machines/${encodeURIComponent((0, dedicated_machines_1.computerMachineId)(leaseId))}/files/archive`, scope), {
+        method: 'POST',
+        body: {
+            archiveId: input.archiveId,
+            generation: input.generation,
+            ...(input.offset !== undefined ? { offset: input.offset } : {}),
+            ...(input.length !== undefined ? { length: input.length } : {}),
+        },
+    });
+}
+/** Release a staged archive. Best-effort callers still call it. */
+async function releaseComputerFileArchive(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)((0, dedicated_machines_1.withDedicatedScope)(`/api/machines/${encodeURIComponent((0, dedicated_machines_1.computerMachineId)(leaseId))}/files/archive`, scope), {
+        method: 'POST',
+        body: { archiveId: input.archiveId, generation: input.generation, release: true },
+    });
+}
+const defaultArchiveIo = {
+    prepare: prepareComputerFileArchive,
+    readChunk: readComputerFileArchiveChunk,
+    release: releaseComputerFileArchive,
+    onProcessExit: (fn) => {
+        process.on('exit', fn);
+        return () => process.removeListener('exit', fn);
+    },
+};
+function throwIfCancelled(signal) {
+    if (signal?.aborted) {
+        throw signal.reason instanceof Error ? signal.reason : new Error('Download cancelled');
+    }
+}
+/**
+ * Where a folder download lands. A destination that names a directory — spelled
+ * with a trailing separator, or an existing one — receives `<name>.<format>`
+ * inside it, as `cp` already treats directories.
+ */
+function computerFileArchiveDestination(localPath, name, format, 
+/** Whether `localPath` names an existing directory (caller's stat). */
+isDirectory) {
+    const fileName = `${name}.${format || 'tar'}`;
+    if (!localPath)
+        return fileName;
+    if (localPath.endsWith('/') || localPath.endsWith(node_path_1.sep))
+        return (0, node_path_1.join)(localPath, fileName);
+    return isDirectory ? (0, node_path_1.join)(localPath, fileName) : localPath;
+}
+/**
+ * Download one folder as its staged archive, prepare → chunks → release. Every
+ * call — prepare, each chunk, the release — presents the one `generation` the
+ * command resolved, so a machine replaced mid-download refuses the rest.
+ *
+ * The local write is never half-visible: chunks land in a temporary file beside
+ * the destination and are renamed into place at the end; a failed or cancelled
+ * download removes the temporary and still releases the staged archive. The
+ * archive itself is one immutable staged file, so chunks always belong to the
+ * same tree snapshot — there is no mid-copy change to fence here.
+ */
+async function downloadComputerFileArchive(leaseId, remotePath, localPath, generation, scope = {}, io = {}) {
+    const { prepare, readChunk, release, onProcessExit, signal, onProgress } = {
+        ...defaultArchiveIo,
+        ...io,
+    };
+    throwIfCancelled(signal);
+    const prepared = await (0, dedicated_file_retry_1.withFileAdmissionRetry)(() => prepare(leaseId, { path: remotePath, generation }, scope), signal);
+    let releaseAttempted = false;
+    try {
+        const existingDir = localPath
+            ? await (0, promises_1.stat)(localPath)
+                .then((info) => info.isDirectory())
+                .catch(() => false)
+            : false;
+        const target = computerFileArchiveDestination(localPath, prepared.name, prepared.format, existingDir);
+        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-archive-${(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, a killed process): the
+        // temporary must not sit beside the destination. Synchronous because an
+        // exit handler cannot await; harmless after the rename, when it is gone.
+        const forgetExitCleanup = onProcessExit(() => (0, node_fs_1.rmSync)(temporary, { force: true }));
+        let closed = false;
+        try {
+            let offset = 0;
+            for (;;) {
+                throwIfCancelled(signal);
+                const chunk = await (0, dedicated_file_retry_1.withFileAdmissionRetry)(() => readChunk(leaseId, { archiveId: prepared.archiveId, offset, length: prepared.chunkBytes, generation }, scope), signal);
+                const bytes = Buffer.from(chunk.data, 'base64');
+                if (chunk.offset !== offset) {
+                    throw new Error('An archive chunk arrived out of order; nothing was written to the destination.');
+                }
+                await handle.write(bytes, 0, bytes.byteLength, offset);
+                offset += bytes.byteLength;
+                onProgress?.(offset, prepared.size);
+                if (chunk.eof)
+                    break;
+                if (bytes.byteLength === 0) {
+                    throw new Error('The archive stream ended without completing.');
+                }
+            }
+            await handle.close();
+            closed = true;
+            await (0, promises_1.rename)(temporary, target);
+            releaseAttempted = true;
+            const released = await release(leaseId, { archiveId: prepared.archiveId, generation }, scope)
+                .then(() => true)
+                .catch(() => false);
+            return {
+                path: prepared.path,
+                name: prepared.name,
+                format: prepared.format,
+                entries: prepared.entries,
+                size: prepared.size,
+                bytes: offset,
+                destination: target,
+                archiveReleased: released,
+            };
+        }
+        catch (err) {
+            if (!closed)
+                await handle.close().catch(() => undefined);
+            await (0, promises_1.unlink)(temporary).catch(() => undefined);
+            throw err;
+        }
+        finally {
+            forgetExitCleanup();
+        }
+    }
+    finally {
+        if (!releaseAttempted) {
+            await release(leaseId, { archiveId: prepared.archiveId, generation }, scope).catch(() => undefined);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Entity tags
+// ---------------------------------------------------------------------------
+/** A folder contents tag: SHA-256, lowercase hex (`COMPUTER_FILE_CONTENTS_TAG_PATTERN`). */
+const CONTENTS_TAG = /^[0-9a-f]{64}$/;
+/**
+ * The tag exactly as `--tag` takes it back: `inode:size:mtimeNs`, the triple
+ * `stat` prints and a `file_changed` refusal carries — and, for a folder read
+ * with `stat --contents`, a fourth part, `inode:size:mtimeNs:contents`, the
+ * digest a fenced recursive delete presents.
+ */
+function computerFileTagString(tag) {
+    const base = `${tag.inode}:${tag.size}:${tag.mtimeNs}`;
+    return typeof tag.contents === 'string' ? `${base}:${tag.contents}` : base;
+}
+/**
+ * Parse a `--tag` value: the compact `inode:size:mtimeNs[:contents]` form, or
+ * the JSON object `--json` output prints. Throws a usage-shaped Error, never a
+ * half-tag.
+ */
+function parseComputerFileTag(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith('{')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            throw new Error('--tag is not readable JSON.');
+        }
+        if (isEntityTag(parsed))
+            return entityTagOf(parsed);
+        throw new Error('--tag JSON must carry inode, size and mtimeNs (and a valid contents, if any).');
+    }
+    const parts = trimmed.split(':');
+    if ((parts.length === 3 || parts.length === 4) &&
+        /^\d+$/.test(parts[0]) &&
+        /^\d+$/.test(parts[1]) &&
+        Number.isSafeInteger(Number(parts[1])) &&
+        /^\d+$/.test(parts[2]) &&
+        (parts.length === 3 || CONTENTS_TAG.test(parts[3]))) {
+        return {
+            inode: parts[0],
+            size: Number(parts[1]),
+            mtimeNs: parts[2],
+            ...(parts.length === 4 ? { contents: parts[3] } : {}),
+        };
+    }
+    throw new Error('--tag wants the <inode>:<size>:<mtimeNs> string `stat` prints (with :<contents> for a folder read with `stat --contents`).');
+}
+/** Only the tag's own fields, so a JSON tag never smuggles anything else onto the wire. */
+function entityTagOf(tag) {
+    return {
+        inode: tag.inode,
+        size: tag.size,
+        mtimeNs: tag.mtimeNs,
+        ...(typeof tag.contents === 'string' ? { contents: tag.contents } : {}),
+    };
+}
+function isEntityTag(value) {
+    const tag = value;
+    return (typeof tag?.inode === 'string' &&
+        /^\d+$/.test(tag.inode) &&
+        typeof tag?.size === 'number' &&
+        Number.isSafeInteger(tag.size) &&
+        tag.size >= 0 &&
+        typeof tag?.mtimeNs === 'string' &&
+        /^\d+$/.test(tag.mtimeNs) &&
+        (tag.contents === undefined ||
+            (typeof tag.contents === 'string' && CONTENTS_TAG.test(tag.contents))));
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+const MODE_KINDS = {
+    file: '-',
+    directory: 'd',
+    symlink: 'l',
+    other: '?',
+};
+/** `drwxr-x---` — the entry's type char plus its permission bits. */
+function computerFileModeString(type, mode) {
+    const kind = MODE_KINDS[type] ?? '?';
+    let out = '';
+    for (const shift of [6, 3, 0]) {
+        const bits = (mode >> shift) & 0o7;
+        out += bits & 0o4 ? 'r' : '-';
+        out += bits & 0o2 ? 'w' : '-';
+        out += bits & 0o1 ? 'x' : '-';
+    }
+    return `${kind}${out}`;
+}
+/** `1.2 MiB`, `3182 B` — sizes a person scans. */
+function formatComputerFileSize(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return '-';
+    if (bytes >= 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GiB`;
+    if (bytes >= 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+    if (bytes >= 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    return `${bytes} B`;
+}
+/**
+ * How one `ls` row names its entry: `name` (dirs marked `/`), a symlink's
+ * stored target (`a -> b`, never followed), and a withheld entry said as
+ * withheld with the reason — never rendered as an ordinary readable file.
+ */
+function computerFileEntryName(entry) {
+    let name = entry.type === 'directory' ? `${entry.name}/` : entry.name;
+    if (entry.type === 'symlink' && entry.linkTarget !== undefined) {
+        name += ` -> ${entry.linkTarget}`;
+    }
+    if (entry.withheld) {
+        name += `  [withheld: ${entry.withheld.reason}${entry.withheld.rule ? `, ${entry.withheld.rule}` : ''}]`;
+    }
+    return name;
+}
+/** One search hit as a line: `path`, or `path:line: text` for a content match. */
+function computerFileSearchHitLine(hit) {
+    const where = hit.line !== undefined
+        ? `${hit.relativePath}:${hit.line}: ${hit.text ?? ''}`
+        : hit.relativePath;
+    return hit.pathLossy ? `${where}  [name is not valid UTF-8; shown lossy]` : where;
+}
+/**
+ * The search read-out. The closing line says how it ended: a list cut at the
+ * limit or the time bound is never printed as if it were the whole answer, and
+ * "nothing found" is said only for a search that finished.
+ */
+function computerFileSearchLines(result) {
+    const content = result.mode === 'content';
+    const count = result.hits.length;
+    const lines = result.hits.map(computerFileSearchHitLine);
+    const ignore = result.respectIgnore ? '' : ', ignore rules off';
+    const found = (n) => content ? `${n} match${n === 1 ? '' : 'es'}` : `${n} file${n === 1 ? '' : 's'}`;
+    switch (result.state) {
+        case 'truncated':
+            lines.push(`Truncated at ${result.limit} results — there are more. Narrow the query or raise --limit${ignore}.`);
+            break;
+        case 'timed_out':
+            lines.push(`Still searching: stopped at the ${result.budgetMs} ms time bound; ${count === 0 ? 'nothing found so far' : `${found(count)} found so far — the results are at least these`}. Narrow the folder or raise --budget-ms.`);
+            break;
+        default:
+            lines.push(count === 0
+                ? `No ${content ? 'matches' : 'files'} found${ignore}.`
+                : `${found(count)}${ignore}.`);
+    }
+    return lines;
+}
+/** The git-status read-out; `timed_out` offers no marks and says so. */
+function computerFileGitStatusLines(result) {
+    if (!result.repository)
+        return [`${result.path} is not inside a git repository.`];
+    if (result.state === 'timed_out') {
+        return [
+            `${result.path}: git status did not finish in time; no marks are available. Try again.`,
+        ];
+    }
+    const names = Object.keys(result.marks).sort();
+    if (names.length === 0)
+        return [`${result.path}: clean — no marked entries.`];
+    return [
+        `${result.path} — ${names.length} marked entr${names.length === 1 ? 'y' : 'ies'}`,
+        ...names.map((name) => `  ${result.marks[name].padEnd(11)} ${name}`),
+    ];
+}
+// ---------------------------------------------------------------------------
+// Refusals — the computer vocabulary, read once for every command
+// ---------------------------------------------------------------------------
+/** The parsed refusal body of a thrown call, when the wire sent one. */
+function computerFileRefusalBody(err) {
+    if (!(err instanceof api_fetch_1.ApiFetchError) || !err.body)
+        return null;
+    try {
+        const parsed = JSON.parse(err.body);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The refusal, or null when the failure is not a computer refusal at all (an
+ * edge page, a lease that does not resolve — `formatDedicatedRuntimeApiError`'s
+ * cases, which the caller then handles).
+ *
+ * Codes the route returns that are not in COMPUTER_REFUSAL_CODES — `internal`,
+ * `not_supported`, a middleware's own — are still the refusal: they carry the
+ * same `{error, code, message}` envelope and there is no second reader to hand
+ * them to.
+ */
+function computerFileRefusalInfo(err) {
+    const body = computerFileRefusalBody(err);
+    if (!body)
+        return null;
+    const rawCode = typeof body.code === 'string' ? body.code : '';
+    if (!rawCode)
+        return null;
+    const normalized = (0, data_provider_1.normalizeComputerRefusalCode)(rawCode);
+    if (normalized === null && rawCode !== 'internal' && rawCode !== 'not_supported')
+        return null;
+    const details = body.details && typeof body.details === 'object' && !Array.isArray(body.details)
+        ? body.details
+        : undefined;
+    return {
+        code: normalized ?? rawCode,
+        message: (typeof body.message === 'string' && body.message) ||
+            (typeof body.error === 'string' && body.error) ||
+            'The machine refused this request.',
+        status: err instanceof api_fetch_1.ApiFetchError ? err.status : undefined,
+        ...(isEntityTag(body.currentTag) ? { currentTag: body.currentTag } : {}),
+        ...(details ? { details } : {}),
+        ...(typeof body.missingCapability === 'string'
+            ? { missingCapability: body.missingCapability }
+            : {}),
+        ...(typeof body.operation === 'string' ? { operation: body.operation } : {}),
+        body,
+    };
+}
+const RETRYABLE_REFUSAL_CODES = new Set(['daemon_unreachable', 'timeout', 'rate_limited']);
+/**
+ * The daemon-side reason an `invalid_request` carries, in the words that tell
+ * the caller what to change. `exists`/`not_empty`/… arrive under 409;
+ * `bad_cursor`/`bad_name`/`is_root`/`too_many` under 400 — the distinction is
+ * the server's, not something the wording should lean on.
+ */
+const INVALID_REQUEST_REASONS = {
+    exists: 'a file or folder by that name already exists',
+    not_empty: 'the folder is not empty; pass --recursive to remove it anyway',
+    is_directory: 'the path is a directory; pass --recursive to remove it',
+    not_directory: 'the path is not a directory',
+    into_itself: 'a folder cannot be moved into itself',
+    bad_cursor: 'the --cursor is stale or not from this listing; start the listing again',
+    bad_name: 'the name is not usable',
+    is_root: 'the workspace roots (repos/ and user-data/) cannot be renamed or removed',
+    too_many: 'the folder holds more entries than a listing can return',
+    contents_tag_required: "a recursive delete fenced by --tag needs the folder's contents tag; read it with `stat --contents` and pass that tag",
+};
+/**
+ * One refusal → the sentence the command prints: the server's own message, then
+ * what to do about it. A refusal that names its fix in the message already
+ * (`too_large` ends "Push it through Git or object storage instead.") is not
+ * given a second one.
+ */
+function describeComputerFileRefusal(refusal, ctx) {
+    const { bin } = ctx;
+    const lease = ctx.leaseId || '<lease-id>';
+    const reason = typeof refusal.details?.reason === 'string'
+        ? (INVALID_REQUEST_REASONS[refusal.details.reason] ?? refusal.details.reason)
+        : '';
+    switch (refusal.code) {
+        case 'file_changed': {
+            if (refusal.currentTag === undefined &&
+                'currentTag' in refusal.body &&
+                refusal.body.currentTag === null) {
+                return `${refusal.message} It is no longer there.`;
+            }
+            const tag = refusal.currentTag
+                ? ` Its current tag is ${computerFileTagString(refusal.currentTag)}.`
+                : '';
+            let fix = ctx.takesTag
+                ? ' If you mean to act on this version, stat it again and pass --tag.'
+                : ' Re-read it and try again.';
+            if (ctx.takesTag && typeof refusal.currentTag?.contents === 'string') {
+                // A folder's contents changed: only a fresh contents walk shows what is there now.
+                fix =
+                    ' If you mean to delete what is there now, look again with `stat --contents` and pass that tag.';
+            }
+            return `${refusal.message}${tag}${fix}`;
+        }
+        case 'path_withheld': {
+            const detail = (key) => typeof refusal.details?.[key] === 'string' ? refusal.details[key] : '';
+            const rule = detail('rule') || detail('reason');
+            return `${refusal.message}${rule ? ` Withheld by: ${rule}.` : ''} On a Dedicated Runtime only repos/ and user-data/ are reachable; the rest of the workspace belongs to the runtime.`;
+        }
+        case 'not_found': {
+            // `details.path` marks a path refusal; without it the machine itself was
+            // not found — "No computer exists by that machine id."
+            if (refusal.details?.path || /path|file|folder|directory/i.test(refusal.message)) {
+                return `${refusal.message} Look with \`${bin} machines dedicated ls ${lease} <dir>\`.`;
+            }
+            return `${refusal.message} List your machines with \`${bin} machines dedicated list\`.`;
+        }
+        case 'capability_missing':
+            if (refusal.missingCapability === 'computer_files_fenced_v1') {
+                return `${refusal.message} This machine's image predates fenced file changes (copy only onto a version you chose, \`stat --contents\`, a fenced \`rm -r --tag\`), so the machine's image must be updated: \`${bin} machines dedicated update-image ${lease}\` moves it onto the current image. Nothing was changed.`;
+            }
+            if (refusal.missingCapability === 'computer_files_search_v1') {
+                return `${refusal.message} Search and git marks are guest-only today: a Dedicated Runtime whose image carries them, not a personal machine. \`${bin} machines dedicated update-image ${lease}\` moves a dedicated machine onto the current image.`;
+            }
+            return `${refusal.message} \`${bin} machines dedicated update-image ${lease}\` moves the machine onto the current image, which carries it.`;
+        case 'consent_missing':
+            return `${refusal.message} On a personal machine the consent is set on that machine: \`${bin} computer allow\`.`;
+        case 'unauthorized':
+            return `${refusal.message} File access needs the operate tier — see \`${bin} machines shares ${lease}\`.`;
+        case 'stale_generation':
+            // `generation_required`: the request named no generation at all (an older
+            // CLI path); otherwise the machine was replaced after this command read
+            // it. Either way nothing reached the replacement.
+            return `${refusal.message} The machine was replaced while this command ran (or the request did not say which machine it meant); nothing was changed on the replacement. Run it again.`;
+        case 'too_large': {
+            // A contents walk (`stat --contents`, a fenced `rm -r --tag`) names only
+            // `maxEntries`; an archive names both and its message already says why.
+            const maxEntries = refusal.details?.maxEntries;
+            if (typeof maxEntries === 'number' && refusal.details?.maxBytes === undefined) {
+                return `${refusal.message} A contents tag covers at most ${maxEntries.toLocaleString('en-US')} entries, so a folder this large cannot be fenced by its contents: work on smaller folders inside it, or delete it without --tag (unfenced).`;
+            }
+            return refusal.message;
+        }
+        case 'machine_unavailable':
+            return `${refusal.message} See \`${bin} machines dedicated show ${lease}\`; a stopped machine serves no files until \`${bin} machines dedicated start ${lease} --wait\`.`;
+        case 'daemon_unreachable':
+            return `${refusal.message} \`${bin} machines dedicated health-check ${lease}\` asks the control plane to re-observe it; retry once the daemon is back.`;
+        case 'timeout':
+            return `${refusal.message} Retry; the machine did not answer in time.`;
+        case 'rate_limited':
+            return `${refusal.message} The limit is per minute — retry shortly.`;
+        case 'invalid_request':
+            return `${refusal.message}${reason ? ` (${reason})` : ''}`;
+        default:
+            return refusal.message;
+    }
+}
+/**
+ * Everything a command needs to print a failure — the computer refusal
+ * sentence when the wire sent one, or the dedicated-runtime reading otherwise
+ * (edge page, lease not found). Null means neither had anything to say, and
+ * the caller falls back to `handleApiError`.
+ */
+function describeComputerFileFailure(err, ctx) {
+    if (err instanceof DedicatedFileGenerationUnavailableError) {
+        return { message: err.message, code: err.code, retryable: true };
+    }
+    const refusal = computerFileRefusalInfo(err);
+    if (refusal) {
+        // Schema-issue strings (`details.issues`, already "path: message" text) go
+        // into the message; nothing else here renders them.
+        const issues = Array.isArray(refusal.details?.issues)
+            ? refusal.details.issues.filter((i) => typeof i === 'string').slice(0, 10)
+            : [];
+        return {
+            message: describeComputerFileRefusal(refusal, ctx) +
+                (issues.length ? `\n${issues.map((i) => `  ${i}`).join('\n')}` : ''),
+            code: refusal.code,
+            status: refusal.status,
+            retryable: RETRYABLE_REFUSAL_CODES.has(refusal.code) ||
+                (0, base_command_1.isRetryableFailure)(refusal.status, refusal.body),
+            details: refusal.body,
+            requestId: err instanceof api_fetch_1.ApiFetchError ? err.requestId : undefined,
+        };
+    }
+    const message = (0, dedicated_machines_1.formatDedicatedRuntimeApiError)(err, { bin: ctx.bin, leaseId: ctx.leaseId });
+    if (message) {
+        return {
+            message,
+            code: (0, dedicated_machines_1.dedicatedRuntimeApiErrorCode)(err) ?? 'CLI_ERROR',
+            status: err instanceof api_fetch_1.ApiFetchError ? err.status : undefined,
+            retryable: err instanceof api_fetch_1.ApiFetchError
+                ? (0, base_command_1.isRetryableFailure)(err.status, computerFileRefusalBody(err))
+                : false,
+            details: computerFileRefusalBody(err) ?? undefined,
+            requestId: err instanceof api_fetch_1.ApiFetchError ? err.requestId : undefined,
+        };
+    }
+    return null;
+}