@skrr-ai/cli 0.1.86 → 0.1.88

package/dist/commands/machines/dedicated/archive.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../../base-command");
+const dedicated_lease_command_1 = require("../../../lib/dedicated-lease-command");
+const dedicated_machines_1 = require("../../../lib/dedicated-machines");
+const dedicated_copy_1 = require("../../../lib/dedicated-copy");
+const computer_files_1 = require("../../../lib/computer-files");
+const LIMIT_MIB = dedicated_machines_1.DEDICATED_FILE_MAX_BYTES / (1024 * 1024);
+/**
+ * `skrr machines dedicated archive` — download a folder from the machine as a
+ * tar file.
+ *
+ * The machine builds one staged archive of the folder (prepare), the CLI reads
+ * it in chunks (read) and frees it (release — always, including on a failed or
+ * cancelled download). The local file is written beside its destination and
+ * renamed into place, the same discipline `cp` keeps, so a cancelled download
+ * never leaves a partial `<name>.tar` — only the machine's staged copy, which
+ * release then removes.
+ */
+class DedicatedMachinesArchive extends dedicated_lease_command_1.DedicatedLeaseCommand {
+    static summary = 'Download a folder from a Dedicated Runtime machine as a tar file';
+    static description = [
+        `Downloads one folder as a single tar archive of at most ${LIMIT_MIB} MiB and 10,000 entries. ` +
+            'A destination left off, or one that names a directory, receives <name>.tar.',
+        'The staged archive is the folder as it stood when the command ran — the tree may keep ' +
+            'changing, the archive does not. Symlinks are stored as links and never followed out of ' +
+            'the folder.',
+        'A Ctrl-C removes the local partial and releases the staged copy on the machine (exit 130; ' +
+            '143 for SIGTERM, 129 when the terminal closes). Progress is shown on a terminal, but not ' +
+            'with --json or under CI.',
+    ].join('\n\n');
+    static examples = [
+        '<%= config.bin %> machines dedicated archive rtl_abc123 repos/app',
+        '<%= config.bin %> machines dedicated archive rtl_abc123 repos/app ./backups/',
+        '<%= config.bin %> machines dedicated archive rtl_abc123 repos/app ./app-snapshot.tar --json',
+    ];
+    static args = {
+        lease: core_1.Args.string({
+            description: dedicated_lease_command_1.DEDICATED_LEASE_ARG_DESCRIPTION,
+            required: true,
+            ignoreStdin: true,
+        }),
+        path: core_1.Args.string({
+            description: 'Folder on the machine, relative to /workspace (inside repos/ or user-data/)',
+            required: true,
+            ignoreStdin: true,
+        }),
+        destination: core_1.Args.string({
+            description: 'Local file, or a directory to receive <name>.tar (default: ./<name>.tar)',
+            required: false,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output the result as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(DedicatedMachinesArchive);
+        const leaseId = await this.resolveLeaseArg(args.lease);
+        const scope = this.scopeFrom(flags);
+        const progress = !flags.json && process.stderr.isTTY && !(0, dedicated_copy_1.isContinuousIntegration)()
+            ? (0, dedicated_copy_1.createCopyProgress)({
+                label: 'Downloading',
+                write: (text) => process.stderr.write(text),
+            })
+            : null;
+        // Same interrupt contract as `cp`: the first signal asks the download to
+        // stop; the partial is removed and the staged archive released.
+        const interrupt = (0, dedicated_copy_1.listenForCopyInterrupt)();
+        let result;
+        try {
+            // Once: prepare, every chunk and the release present this generation.
+            const generation = await (0, computer_files_1.resolveDedicatedFileGeneration)(leaseId, scope);
+            result = await (0, computer_files_1.downloadComputerFileArchive)(leaseId, args.path, args.destination, generation, scope, {
+                signal: interrupt.signal,
+                onProgress: progress?.update,
+            });
+        }
+        catch (thrown) {
+            progress?.clear();
+            const interruptedBy = interrupt.interruptedBy();
+            const err = interruptedBy ? new dedicated_copy_1.DedicatedCopyCancelledError(interruptedBy) : thrown;
+            if (err instanceof dedicated_copy_1.DedicatedCopyCancelledError) {
+                this.error(`${err.message} Nothing was written for ${args.path}; the staged archive on the machine is released.`, { exit: err.exitCode, code: err.code });
+            }
+            const refusal = (0, base_command_1.apiRefusal)(err);
+            if (refusal.body?.retryable === true)
+                this.handleApiError(err);
+            const failure = (0, computer_files_1.describeComputerFileFailure)(err, { bin: this.config.bin, leaseId });
+            if (failure)
+                this.failWithCliError({ ...failure, exit: 1 });
+            if (err instanceof Error && typeof err.status !== 'number') {
+                this.error(err.message, { exit: 1, code: 'DEDICATED_RUNTIME_FILE_TRANSFER_FAILED' });
+            }
+            this.handleApiError(err);
+        }
+        finally {
+            interrupt.dispose();
+        }
+        progress?.clear();
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        this.log(`Downloaded ${result.name}.${result.format} (${result.entries} entries, ${result.size} bytes) → ${result.destination}`);
+        if (!result.archiveReleased) {
+            this.warn('The staged archive could not be released; the machine removes it within the hour.');
+        }
+    }
+}
+exports.default = DedicatedMachinesArchive;

package/dist/commands/machines/dedicated/audit.d.ts

@@ -0,0 +1,25 @@
+import { DedicatedLeaseCommand } from '../../../lib/dedicated-lease-command';
+import { type ComputerAuditPage } from '../../../lib/machine-audit';
+type AuditEvent = ComputerAuditPage['events'][number];
+/** The actor as ids: the audit record stores no display name. */
+export declare function describeAuditActor(actor: AuditEvent['actor']): string;
+/** What the event touched, as the record says it — a surface, a path, a reason. */
+export declare function describeAuditEvent(event: AuditEvent): string;
+export default class DedicatedMachinesAudit extends DedicatedLeaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        lease: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        kind: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        actor: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        since: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        until: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        limit: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        cursor: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+export {};

package/dist/commands/machines/dedicated/audit.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeAuditActor = describeAuditActor;
+exports.describeAuditEvent = describeAuditEvent;
+const core_1 = require("@oclif/core");
+const dedicated_lease_command_1 = require("../../../lib/dedicated-lease-command");
+const format_1 = require("../../../lib/format");
+const machine_audit_1 = require("../../../lib/machine-audit");
+/** The actor as ids: the audit record stores no display name. */
+function describeAuditActor(actor) {
+    return actor.kind === 'human' ? `person ${actor.userId}` : `agent ${actor.agentId}`;
+}
+/** What the event touched, as the record says it — a surface, a path, a reason. */
+function describeAuditEvent(event) {
+    const parts = [];
+    if (event.summary)
+        parts.push(event.summary);
+    else {
+        const detail = event.detail ?? {};
+        const path = typeof detail.path === 'string' ? detail.path : undefined;
+        const reason = typeof detail.reason === 'string' ? detail.reason : undefined;
+        if (path)
+            parts.push(typeof detail.toPath === 'string' ? `${path} -> ${detail.toPath}` : path);
+        if (reason)
+            parts.push(reason);
+    }
+    if (event.surfaceId)
+        parts.push(`[${event.surfaceKind ?? 'surface'} ${event.surfaceId}]`);
+    return parts.join(' ') || '-';
+}
+class DedicatedMachinesAudit extends dedicated_lease_command_1.DedicatedLeaseCommand {
+    static description = "Read a machine's audit record — who changed control, wrote files, opened, closed or shared a surface, changed a grant or used power — long after the live Activity window has rolled off";
+    static examples = [
+        '<%= config.bin %> machines dedicated audit <lease-id>',
+        '<%= config.bin %> machines dedicated audit <lease-id> --kind control_changed --since 14d --until 7d',
+        '<%= config.bin %> machines dedicated audit <lease-id> --actor <user-id> --json',
+        '<%= config.bin %> machines dedicated audit <lease-id> --cursor <next-cursor>',
+    ];
+    static args = {
+        lease: core_1.Args.string({
+            ignoreStdin: true,
+            description: dedicated_lease_command_1.DEDICATED_LEASE_ARG_DESCRIPTION,
+            required: true,
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        kind: core_1.Flags.string({
+            description: `Only this kind; repeat for several (${machine_audit_1.COMPUTER_AUDIT_KINDS.join(', ')})`,
+            multiple: true,
+            options: [...machine_audit_1.COMPUTER_AUDIT_KINDS],
+        }),
+        actor: core_1.Flags.string({ description: 'Only events this person (user id) did' }),
+        since: core_1.Flags.string({
+            description: 'Only events at or after this time: 2026-09-24, an ISO time, or an age like 7d',
+        }),
+        until: core_1.Flags.string({
+            description: 'Only events before this time: 2026-09-24, an ISO time, or an age like 7d',
+        }),
+        limit: core_1.Flags.integer({ description: 'Events per page (1-200)', default: 50, min: 1, max: 200 }),
+        cursor: core_1.Flags.string({ description: 'Continue from the `next` cursor of a previous page' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(DedicatedMachinesAudit);
+        const leaseId = await this.resolveLeaseArg(args.lease);
+        let since;
+        let until;
+        try {
+            since = flags.since ? (0, machine_audit_1.parseAuditTime)(flags.since, '--since') : undefined;
+            until = flags.until ? (0, machine_audit_1.parseAuditTime)(flags.until, '--until') : undefined;
+        }
+        catch (err) {
+            this.error(err instanceof Error ? err.message : String(err), { exit: 2 });
+        }
+        const page = await this.callDedicated(() => (0, machine_audit_1.listMachineAudit)(`lease:${leaseId}`, {
+            kinds: flags.kind,
+            actorUserId: flags.actor,
+            since,
+            until,
+            cursor: flags.cursor,
+            limit: flags.limit,
+        }));
+        if (flags.json) {
+            this.log(JSON.stringify(page, null, 2));
+            return;
+        }
+        const events = page?.events ?? [];
+        if (events.length === 0) {
+            // An empty page is "nothing matched", never "nothing happened": the
+            // record is kept 400 days and a grantee is not shown grant changes.
+            this.log(flags.kind || flags.actor || flags.since || flags.until
+                ? 'No audit events match those filters.'
+                : 'No audit events recorded for this machine.');
+            return;
+        }
+        (0, format_1.renderTable)(events.map((event) => ({
+            when: (0, format_1.localStamp)(event.occurredAt),
+            actor: (0, format_1.formatCell)(describeAuditActor(event.actor)),
+            kind: (0, format_1.formatCell)(event.kind),
+            what: (0, format_1.formatCell)(describeAuditEvent(event)),
+        })), [
+            { key: 'when', header: `WHEN (${(0, format_1.localZone)()})` },
+            { key: 'actor', header: 'ACTOR', verbatim: true },
+            { key: 'kind', header: 'KIND' },
+            { key: 'what', header: 'WHAT', verbatim: true },
+        ], (line) => this.log(line));
+        if (page?.nextCursor) {
+            this.log(`More (older) events: re-run with --cursor ${page.nextCursor}`);
+        }
+    }
+}
+exports.default = DedicatedMachinesAudit;

package/dist/commands/machines/dedicated/computer.d.ts

@@ -0,0 +1,23 @@
+import { DedicatedLeaseCommand } from '../../../lib/dedicated-lease-command';
+/**
+ * `skrr machines dedicated computer` — open the machine's computer: its
+ * terminals, browser and files as one desktop of windows (design §11, §17).
+ *
+ * The page is `/machines/<machineId>/computer`, where the machine id is the
+ * inventory's `lease:<leaseId>`. The command prints that URL (always, on
+ * stdout) and opens it unless stdout is not a terminal or --json was passed —
+ * the same open contract `projects open` and the other entity opens keep.
+ */
+export default class DedicatedMachinesComputer extends DedicatedLeaseCommand {
+    static summary: string;
+    static examples: string[];
+    static args: {
+        lease: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        web: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        app: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/machines/dedicated/computer.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const dedicated_lease_command_1 = require("../../../lib/dedicated-lease-command");
+const entity_open_1 = require("../../../lib/entity-open");
+const dedicated_machines_1 = require("../../../lib/dedicated-machines");
+/**
+ * `skrr machines dedicated computer` — open the machine's computer: its
+ * terminals, browser and files as one desktop of windows (design §11, §17).
+ *
+ * The page is `/machines/<machineId>/computer`, where the machine id is the
+ * inventory's `lease:<leaseId>`. The command prints that URL (always, on
+ * stdout) and opens it unless stdout is not a terminal or --json was passed —
+ * the same open contract `projects open` and the other entity opens keep.
+ */
+class DedicatedMachinesComputer extends dedicated_lease_command_1.DedicatedLeaseCommand {
+    static summary = 'Open a Dedicated Runtime machine’s computer in the browser or skrr Desktop';
+    static examples = [
+        '<%= config.bin %> machines dedicated computer rtl_abc123',
+        '<%= config.bin %> machines dedicated computer rtl_abc123 --app',
+        '<%= config.bin %> machines dedicated computer rtl_abc123 --json',
+    ];
+    static args = {
+        lease: core_1.Args.string({
+            description: dedicated_lease_command_1.DEDICATED_LEASE_ARG_DESCRIPTION,
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        web: core_1.Flags.boolean({ char: 'w', description: 'Open in the browser (default)' }),
+        app: core_1.Flags.boolean({ char: 'a', description: 'Open in skrr Desktop (macOS)' }),
+        json: core_1.Flags.boolean({ description: 'Print the canonical URL as JSON without opening it' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(DedicatedMachinesComputer);
+        const leaseId = await this.resolveLeaseArg(args.lease);
+        // The lease read doubles as the existence check: an id that resolves to
+        // nothing is refused before a browser opens on a dead page.
+        const response = await this.callDedicated(() => (0, dedicated_machines_1.getDedicatedRuntime)(leaseId, this.scopeFrom(flags)));
+        if (!response?.lease) {
+            this.error('Dedicated Runtime lease not found.', { exit: 1 });
+        }
+        const url = (0, dedicated_machines_1.dedicatedComputerUrl)(this.cliConfig.baseURL, leaseId);
+        if (!url) {
+            this.error(`No computer page exists for ${leaseId}.`, { exit: 1 });
+        }
+        const result = await (0, entity_open_1.openEntity)({
+            baseURL: this.cliConfig.baseURL,
+            entity: { url },
+            urlFor: () => null,
+            target: flags.app ? 'app' : 'web',
+            json: Boolean(flags.json),
+        });
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const where = result.target === 'app' ? 'skrr Desktop' : 'browser';
+        this.log(result.opened ? `Opened ${where}: ${result.url}` : result.url);
+    }
+}
+exports.default = DedicatedMachinesComputer;

package/dist/commands/machines/dedicated/cp.d.ts

@@ -17,6 +17,8 @@ export default class DedicatedMachinesCp extends BaseCommand {
     };
     static flags: {
         workspace: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        overwrite: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'if-tag': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;

package/dist/commands/machines/dedicated/cp.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const base_command_1 = require("../../../base-command");
+const computer_files_1 = require("../../../lib/computer-files");
 const dedicated_machines_1 = require("../../../lib/dedicated-machines");
 const dedicated_copy_1 = require("../../../lib/dedicated-copy");
 const LIMIT_MIB = dedicated_machines_1.DEDICATED_FILE_MAX_BYTES / (1024 * 1024);
@@ -26,6 +27,12 @@ class DedicatedMachinesCp extends base_command_1.BaseCommand {
             'machine is created.',
         'As with cp and scp, a destination that ends in / or is an existing directory receives the file ' +
             'under its source name.',
+        'Copying to the machine never replaces a file unasked. A destination that does not exist is created, ' +
+            'and the copy commits only if the name is still free. A destination that exists is refused before ' +
+            'anything is sent, unless --overwrite is given (it replaces the version found when the copy starts, ' +
+            'and says which) or --if-tag <tag> (it replaces exactly the version `stat` showed you). Either way, a ' +
+            'destination that changes during the copy is not replaced. Every request of one copy is bound to the ' +
+            'machine as it was when the copy started: a machine replaced meanwhile refuses the rest.',
         'Files marked executable keep owner execute permission on the copy. Other permissions use ' +
             'destination defaults; source special permission bits are not copied.',
         'Neither side is left half-written: the file is staged beside its destination and renamed into ' +
@@ -36,6 +43,8 @@ class DedicatedMachinesCp extends base_command_1.BaseCommand {
     static examples = [
         '<%= config.bin %> machines dedicated cp ./dist/app.tar.gz rtl_abc123:repos/app/app.tar.gz',
         '<%= config.bin %> machines dedicated cp ./notes.md rtl_abc123:user-data/',
+        '<%= config.bin %> machines dedicated cp ./build.zip rtl_abc123:repos/app/build.zip --overwrite',
+        '<%= config.bin %> machines dedicated cp ./build.zip rtl_abc123:repos/app/build.zip --if-tag 12345:3182:1761234567890000000',
         '<%= config.bin %> machines dedicated cp rtl_abc123:repos/app/coverage/report.html ./report.html',
     ];
     // `ignoreStdin: true` on both, per the CLI's own hygiene rule: without it oclif
@@ -55,6 +64,12 @@ class DedicatedMachinesCp extends base_command_1.BaseCommand {
     };
     static flags = {
         workspace: core_1.Flags.string({ description: 'Workspace scope' }),
+        overwrite: core_1.Flags.boolean({
+            description: 'Copying to the machine: replace an existing destination (the version found when the copy starts)',
+        }),
+        'if-tag': core_1.Flags.string({
+            description: 'Copying to the machine: replace the destination only if it still has this tag — the <inode>:<size>:<mtimeNs> `stat` prints',
+        }),
         json: core_1.Flags.boolean({ description: 'Output the result as JSON' }),
     };
     async run() {
@@ -68,6 +83,23 @@ class DedicatedMachinesCp extends base_command_1.BaseCommand {
             this.error(err.message, { exit: 2 });
         }
         const scope = { workspaceId: flags.workspace };
+        if (plan.direction === 'download' && (flags.overwrite || flags['if-tag'] !== undefined)) {
+            this.error('--overwrite and --if-tag apply when copying to the machine.', { exit: 2 });
+        }
+        let ifTag;
+        if (flags['if-tag'] !== undefined) {
+            try {
+                ifTag = (0, computer_files_1.parseComputerFileTag)(flags['if-tag']);
+            }
+            catch (err) {
+                this.error(err.message.replace(/--tag/g, '--if-tag'), { exit: 2 });
+            }
+            if (ifTag.contents !== undefined) {
+                this.error('--if-tag names a file version; a folder contents tag cannot be replaced.', {
+                    exit: 2,
+                });
+            }
+        }
         // Progress is drawn on stderr, for a person at a terminal: never into a
         // --json document, and never into a CI log as a stream of carriage returns.
         const progress = !flags.json && process.stderr.isTTY && !(0, dedicated_copy_1.isContinuousIntegration)()
@@ -84,13 +116,24 @@ class DedicatedMachinesCp extends base_command_1.BaseCommand {
         let result;
         try {
             const { signal } = interrupt;
+            // Once, before the first file call: every request of this copy presents
+            // this generation, so a machine replaced mid-copy refuses the rest.
+            const generation = await (0, computer_files_1.resolveDedicatedFileGeneration)(plan.leaseId, scope);
             result =
                 plan.direction === 'upload'
                     ? await (0, dedicated_copy_1.uploadToDedicatedRuntime)(plan.localPath, plan.leaseId, plan.remotePath, scope, {
+                        generation,
                         signal,
                         onProgress,
+                        overwrite: flags.overwrite === true,
+                        ...(ifTag ? { ifTag } : {}),
+                        // Said before a byte is sent, so the person knows what is being replaced.
+                        onReplace: (destination, tag) => {
+                            progress?.clear();
+                            process.stderr.write(`Replacing ${destination} (tag ${(0, computer_files_1.computerFileTagString)(tag)})\n`);
+                        },
                     })
-                    : await (0, dedicated_copy_1.downloadFromDedicatedRuntime)(plan.leaseId, plan.remotePath, plan.localPath, scope, { signal, onProgress });
+                    : await (0, dedicated_copy_1.downloadFromDedicatedRuntime)(plan.leaseId, plan.remotePath, plan.localPath, scope, { generation, signal, onProgress });
         }
         catch (thrown) {
             progress?.clear();
@@ -107,6 +150,28 @@ class DedicatedMachinesCp extends base_command_1.BaseCommand {
             if (err instanceof dedicated_copy_1.DedicatedCopyError) {
                 this.error(err.message, { exit: 1, code: err.code });
             }
+            if (err instanceof computer_files_1.DedicatedFileGenerationUnavailableError) {
+                this.error(err.message, { exit: 1, code: err.code });
+            }
+            // The machine was replaced mid-copy, or its image cannot fence the copy:
+            // the computer vocabulary says what to do about either.
+            const computerCode = (0, computer_files_1.computerFileRefusalInfo)(err)?.code;
+            if (computerCode === 'stale_generation' || computerCode === 'capability_missing') {
+                const failure = (0, computer_files_1.describeComputerFileFailure)(err, {
+                    bin: this.config.bin,
+                    leaseId: plan.leaseId,
+                });
+                if (failure) {
+                    const notReplaced = plan.direction === 'upload'
+                        ? ` ${plan.leaseId}:${plan.remotePath} was not changed.`
+                        : ` Nothing was written to ${plan.localPath}.`;
+                    this.failWithCliError({
+                        ...failure,
+                        message: `${failure.message}${notReplaced}`,
+                        exit: 1,
+                    });
+                }
+            }
             // Keep the API status, request id and explicit retry decision together.
             if ((0, base_command_1.apiRefusal)(err).body?.retryable === true)
                 this.handleApiError(err);
@@ -129,7 +194,14 @@ class DedicatedMachinesCp extends base_command_1.BaseCommand {
             this.log(JSON.stringify({ direction: plan.direction, ...result }, null, 2));
             return;
         }
-        this.log(`${plan.direction === 'upload' ? 'Uploaded' : 'Downloaded'} ${result.bytes} bytes → ${result.destination}`);
+        if (plan.direction === 'upload' && result.alreadyCommitted) {
+            this.log(`Already copied: ${result.destination} (an earlier attempt committed it)`);
+            return;
+        }
+        const replaced = result.replacedTag
+            ? ` (replaced the version tagged ${result.replacedTag})`
+            : '';
+        this.log(`${plan.direction === 'upload' ? 'Uploaded' : 'Downloaded'} ${result.bytes} bytes → ${result.destination}${replaced}`);
     }
 }
 exports.default = DedicatedMachinesCp;

package/dist/commands/machines/dedicated/git-status.d.ts

@@ -0,0 +1,15 @@
+import { DedicatedLeaseCommand } from '../../../lib/dedicated-lease-command';
+/** `skrr machines dedicated git-status` — git marks of one folder's entries. */
+export default class DedicatedMachinesGitStatus extends DedicatedLeaseCommand {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static args: {
+        lease: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        path: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/machines/dedicated/git-status.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const dedicated_lease_command_1 = require("../../../lib/dedicated-lease-command");
+const computer_files_1 = require("../../../lib/computer-files");
+/** `skrr machines dedicated git-status` — git marks of one folder's entries. */
+class DedicatedMachinesGitStatus extends dedicated_lease_command_1.DedicatedLeaseCommand {
+    static summary = 'Show git marks for a folder on a Dedicated Runtime machine';
+    static description = 'Prints the git mark (modified, added, untracked, ignored, conflicted) of each entry of one ' +
+        'folder, as the computer’s Files window decorates them. A folder outside a repository is ' +
+        'said so; a status that does not finish in time offers no marks rather than a partial set. ' +
+        'Available on dedicated machines, not on a personal machine.';
+    static examples = [
+        '<%= config.bin %> machines dedicated git-status rtl_abc123 repos/app',
+        '<%= config.bin %> machines dedicated git-status rtl_abc123 repos/app --json',
+    ];
+    static args = {
+        lease: core_1.Args.string({
+            description: dedicated_lease_command_1.DEDICATED_LEASE_ARG_DESCRIPTION,
+            required: true,
+            ignoreStdin: true,
+        }),
+        path: core_1.Args.string({
+            description: 'Folder on the machine, relative to /workspace',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output the result as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(DedicatedMachinesGitStatus);
+        const leaseId = await this.resolveLeaseArg(args.lease);
+        let result;
+        try {
+            const scope = this.scopeFrom(flags);
+            const generation = await (0, computer_files_1.resolveDedicatedFileGeneration)(leaseId, scope);
+            result = await (0, computer_files_1.gitStatusComputerFiles)(leaseId, { path: args.path, generation }, scope);
+        }
+        catch (err) {
+            const failure = (0, computer_files_1.describeComputerFileFailure)(err, { bin: this.config.bin, leaseId });
+            if (failure)
+                this.failWithCliError({ ...failure, exit: 1 });
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        for (const line of (0, computer_files_1.computerFileGitStatusLines)(result))
+            this.log(line);
+    }
+}
+exports.default = DedicatedMachinesGitStatus;

package/dist/commands/machines/dedicated/index.js

@@ -19,6 +19,13 @@ class DedicatedMachines extends core_1.Command {
         '<%= config.bin %> machines dedicated sign-in <lease-id> github',
         '<%= config.bin %> machines dedicated exec <lease-id> -- git -C repos/app status',
         '<%= config.bin %> machines dedicated cp ./notes.md <lease-id>:user-data/notes.md',
+        '<%= config.bin %> machines dedicated ls <lease-id> repos/app',
+        '<%= config.bin %> machines dedicated stat <lease-id> repos/app/package.json',
+        '<%= config.bin %> machines dedicated mkdir <lease-id> repos/app/dist',
+        '<%= config.bin %> machines dedicated mv <lease-id> repos/a repos/b',
+        '<%= config.bin %> machines dedicated rm <lease-id> repos/app/dist --recursive',
+        '<%= config.bin %> machines dedicated archive <lease-id> repos/app',
+        '<%= config.bin %> machines dedicated computer <lease-id>',
         '<%= config.bin %> machines dedicated stop <lease-id> --wait',
         '<%= config.bin %> machines dedicated start <lease-id> --wait',
         '<%= config.bin %> machines dedicated restart <lease-id>',
@@ -44,6 +51,13 @@ class DedicatedMachines extends core_1.Command {
             ['sign-in', 'sign in to GitHub CLI, Claude Code or Codex there'],
             ['exec', 'run one command; output and exit code'],
             ['cp', 'copy a file to or from the machine'],
+            ['ls', 'list a directory on the machine'],
+            ['stat', 'one path: type, size, mtime, mode and its tag'],
+            ['mkdir', 'create a directory, parents included'],
+            ['mv', 'rename or move a path'],
+            ['rm', 'delete a file or folder (--recursive)'],
+            ['archive', 'download a folder as a tar file'],
+            ['computer', 'open the machine’s computer in the browser or skrr Desktop'],
             ['start', 'start a stopped runtime'],
             ['stop', 'stop compute and keep the disk'],
             ['restart', 'restart the instance; files stay'],
@@ -56,7 +70,7 @@ class DedicatedMachines extends core_1.Command {
             ['service', 'declare workloads the machine keeps running'],
             ['destroy', 'stop compute; keep or purge the workspace disk'],
         ];
-        this.log('skrr Dedicated Runtime commands:');
+        this.log('Skrr Dedicated Runtime commands:');
         for (const [name, summary] of rows) {
             this.log(`  skrr machines dedicated ${name.padEnd(15)} ${summary}`);
         }

package/dist/commands/machines/dedicated/ls.d.ts

@@ -0,0 +1,27 @@
+import { DedicatedLeaseCommand } from '../../../lib/dedicated-lease-command';
+/**
+ * `skrr machines dedicated ls` — list one directory on the machine.
+ *
+ * Paths are relative to /workspace and, on a guest, confined to `repos/` and
+ * `user-data/` — the tenant roots; the workspace root itself is the runtime's
+ * and a listing of it is refused `path_withheld`. Entries are sorted by the
+ * machine by name bytes; a symlink shows its stored target and is never
+ * followed; an entry the machine withholds (deny set, blockedPaths, a
+ * sensitive pattern, an OS permission) is shown as withheld, not hidden.
+ */
+export default class DedicatedMachinesLs extends DedicatedLeaseCommand {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static args: {
+        lease: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        path: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        limit: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        cursor: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        all: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}