@skrr-ai/cli 0.1.24 → 0.1.26

package/dist/commands/spaces/task-rollups.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr spaces task-rollups` — task-status counts for every Space you can view,
+ * in one request: the same rollup the Spaces sidebar row reads, counted by the
+ * project-rollup rules (`done` is done only; `open` excludes cancelled).
+ */
+export default class SpacesTaskRollups extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/spaces/task-rollups.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../base-command");
+/**
+ * `skrr spaces task-rollups` — task-status counts for every Space you can view,
+ * in one request: the same rollup the Spaces sidebar row reads, counted by the
+ * project-rollup rules (`done` is done only; `open` excludes cancelled).
+ */
+class SpacesTaskRollups extends base_command_1.BaseCommand {
+    static description = 'Show task-status counts for every space you can view';
+    static examples = [
+        '<%= config.bin %> spaces task-rollups',
+        '<%= config.bin %> spaces task-rollups --json',
+    ];
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(SpacesTaskRollups);
+        let response;
+        // Titles are best-effort: the rollup carries only ids, and a failed title
+        // lookup must not hide counts the rollup did return.
+        let titles = new Map();
+        try {
+            const [rollups, spaces] = await Promise.all([
+                data_provider_1.dataService.listSpaceTaskRollups(),
+                data_provider_1.dataService.listSpaces({ includeArchived: true, limit: 500 }).catch(() => null),
+            ]);
+            response = rollups;
+            const rows = (spaces?.data ||
+                []);
+            titles = new Map(rows.map((space) => [String(space.id), space.title || '']));
+        }
+        catch (err) {
+            this.handleApiError(err);
+            return;
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(response, null, 2));
+            return;
+        }
+        if (response.degraded) {
+            // A partial walk is not the whole picture; say so before the numbers.
+            this.log(`Degraded: ${(response.warnings || []).join('; ') || 'some spaces were not counted'}`);
+        }
+        const rows = [...(response.rollups || [])].sort((a, b) => b.tasks.open - a.tasks.open);
+        if (rows.length === 0) {
+            this.log('No spaces with tasks.');
+            return;
+        }
+        const label = (spaceId) => {
+            const title = titles.get(spaceId);
+            const text = title ? `${title} (${spaceId.slice(0, 8)})` : spaceId;
+            return text.length > 48 ? `${text.slice(0, 45)}...` : text;
+        };
+        this.log(`${'SPACE'.padEnd(48)} ${'OPEN'.padStart(5)} ${'DONE'.padStart(5)} ${'BLOCKED'.padStart(7)} ${'TOTAL'.padStart(5)}`);
+        for (const { spaceId, tasks } of rows) {
+            this.log(`${label(spaceId).padEnd(48)} ${String(tasks.open).padStart(5)} ${String(tasks.done).padStart(5)} ` +
+                `${String(tasks.blocked).padStart(7)} ${String(tasks.total).padStart(5)}`);
+        }
+    }
+}
+exports.default = SpacesTaskRollups;

package/dist/commands/spaces/work-sync/telemetry.js

@@ -52,6 +52,28 @@ class SpacesWorkSyncTelemetry extends base_command_1.BaseCommand {
         this.log(`Verdict:       ${summary.rollout.verdict}`);
         this.log(`Sampled rows:  ${summary.sampledEvents}`);
         this.log(`Repair backlog: ${summary.repairBacklog}`);
+        if (summary.coverage && summary.coverage.hits + summary.coverage.misses > 0) {
+            const { hits, misses, hitRate } = summary.coverage;
+            this.log(`Coverage:      ${hits} hits · ${misses} misses` +
+                (hitRate === null ? '' : ` (${Math.round(hitRate * 1000) / 10}% of cold opens)`));
+        }
+        // Before the zero-events early return: writes are measured from the command
+        // queue, not from board telemetry, so a Space can have one without the other.
+        const commandRows = Object.entries(summary.commands || {}).sort(([a], [b]) => a.localeCompare(b));
+        if (commandRows.length > 0) {
+            const percent = (value) => value === null ? 'n/a' : `${Math.round(value * 1000) / 10}%`;
+            this.log('');
+            this.log('Writes (durable command queue):');
+            for (const [kind, stats] of commandRows) {
+                this.log(`  ${kind.padEnd(20)} ${stats.commands} commands · ${stats.accepted} accepted · ` +
+                    `${stats.pending} pending · ${stats.deadLettered} refused`);
+                this.log(`  ${''.padEnd(20)} version conflicts ${stats.versionConflicts} ` +
+                    `(${percent(stats.rates.versionConflict)} of settled) · authorization changed ` +
+                    `${stats.authorizationChanged} (${percent(stats.rates.authorizationChanged)}) · ` +
+                    `duplicate deliveries ${stats.duplicateDeliveries} ` +
+                    `(${percent(stats.rates.duplicateDelivery)} of deliveries)`);
+            }
+        }
         // Zero sampled rows is a REAL answer and the most misread one: it means
         // nothing has been measured in this Space, not that everything is fine. The
         // server already distinguishes it (`insufficient_evidence`); say so here too

package/dist/commands/tasks/assign.js

@@ -74,7 +74,7 @@ class TasksAssign extends base_command_1.BaseCommand {
             options: ['agent', 'human'],
         }),
         list: core_1.Flags.boolean({
-            description: "List the task's space members (who can be assigned) and exit",
+            description: "List the task's space members and exit (your own unshared agents can also be assigned, by id)",
         }),
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
     };

package/dist/commands/tasks/create.js

@@ -460,8 +460,9 @@ class TasksCreate extends base_command_1.BaseCommand {
             defaultAgentResolution = {
                 applied: false,
                 source: 'none',
-                note: 'Created unassigned: the agent bound to this session is not a member of that space. ' +
-                    'Add it to the space, or pass an assignee explicitly.',
+                note: 'Created unassigned: the agent bound to this session is not a member of that space, ' +
+                    'and it is not your own agent shared with no one else, which is the only other way ' +
+                    'an agent can work there. Add it to the space, or pass an assignee explicitly.',
             };
             try {
                 const result = await this.createTaskOrRecover(payload);
@@ -572,9 +573,14 @@ class TasksCreate extends base_command_1.BaseCommand {
         const dropped = (0, tasks_1.droppedDefaultAssignees)(resolution, memberIds);
         const warnings = [];
         if (dropped.agentIds.length > 0) {
+            // Membership is one of TWO consents the server accepts (AgentTaskConsent);
+            // the other — your own agent, shared with no one else — needs the agent's
+            // sharing, which a dry run does not read. So this says what decides it
+            // rather than predicting a drop that owner delegation would not make.
             warnings.push(`The defaulted assignee agent ${dropped.agentIds.join(', ')} is not a member of ` +
-                `space ${spaceId}, so the real create will drop it and record the task ` +
-                'unassigned. Add the agent to the space, or pass an assignee explicitly.');
+                `space ${spaceId}. The real create keeps it only if it is your own agent shared ` +
+                'with no one else; otherwise it records the task unassigned. Add the agent to the ' +
+                'space, or pass an assignee explicitly.');
         }
         if (dropped.userIds.length > 0) {
             warnings.push(`The defaulted assignee ${dropped.userIds.join(', ')} is not a member of space ` +

package/dist/commands/tasks/list.js

@@ -86,6 +86,33 @@ function emptyTasksMessage(flags, bin = 'skrr') {
         lines.push('      no longer has that status. Try `--execution-state active` (running now) or');
         lines.push(`      \`--execution-state recovered\` (reaped, startable), or \`${bin} tasks active\`.`);
     }
+    else if (typeof flags.status === 'string' &&
+        flags.status.length > 0 &&
+        !flags['execution-state']) {
+        // A filter that matches nothing and a board that IS empty print the same
+        // thing, and the caller cannot tell which they are looking at. Observed:
+        // `--status todo` on a board whose open column is `backlog` said `No tasks.`
+        // while twelve were open, and it was believed.
+        //
+        // Not fixed by validating the value, for two reasons. A status is a
+        // Space-owned workflow-state id — TASK_STATUSES is a legacy default set, not
+        // a closed vocabulary — so a space may legitimately define one we have never
+        // heard of. And `todo` IS a built-in, so refusing unknown values would not
+        // have caught the case that prompted this. What distinguishes the two
+        // readings is naming the filter and how to drop it.
+        //
+        // Silent when `--execution-state` is also set, to leave the exact bare
+        // string the branch above deliberately produces for that combination. The
+        // same ambiguity exists there, but overturning a pinned decision is not
+        // this change's business.
+        lines.push('');
+        lines.push(`Note: nothing matched \`--status ${flags.status}\`. A status is a workflow-state id the`);
+        lines.push('      space owns, so a board need not use this one at all.');
+        lines.push('  → See what this scope actually holds: the same command without `--status`.');
+        if (!data_provider_1.TASK_STATUSES.includes(flags.status)) {
+            lines.push(`      (built-in ids: ${data_provider_1.TASK_STATUSES.join(', ')})`);
+        }
+    }
     return lines.join('\n');
 }
 /**

package/dist/lib/api-fetch.js

@@ -37,6 +37,8 @@ const config_1 = require("./config");
 // (b) tests that mock './auth-storage' get a single mock target.
 const auth_storage_1 = require("./auth-storage");
 const credential_resolver_1 = require("./credential-resolver");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const idempotency_scope_1 = require("./idempotency-scope");
 const node_adapter_1 = require("./node-adapter");
 const refresh_1 = require("./refresh");
 const delegated_cli_1 = require("./delegated-cli");
@@ -95,6 +97,12 @@ async function apiFetch(pathOrUrl, opts = {}) {
     if (opts.body !== undefined && method !== 'GET') {
         body = JSON.stringify(opts.body);
     }
+    // Same rule as every `dataService` write (`@skrr-ai/data-provider`
+    // idempotency), chosen once so the 401 retries below resend the same key.
+    (0, idempotency_scope_1.bindAutonomousIdempotencyScope)();
+    const callerHeaders = method === 'GET'
+        ? (opts.headers ?? {})
+        : (0, data_provider_1.withIdempotencyKey)(opts.headers, { method, url: pathOrUrl, body: opts.body });
     // A trusted Agent process cannot smuggle an explicit human credential into
     // this escape hatch. The daemon-issued session token is the sole principal.
     //
@@ -146,7 +154,7 @@ async function apiFetch(pathOrUrl, opts = {}) {
         // Caller headers are applied BEFORE the auth header below is read, and
         // deliberately cannot clobber Authorization / Content-Type: an idempotency
         // key is additive metadata, not a way to re-auth the request.
-        for (const [k, v] of Object.entries(opts.headers ?? {})) {
+        for (const [k, v] of Object.entries(callerHeaders)) {
             const lower = k.toLowerCase();
             if (lower === 'authorization' || lower === 'content-type')
                 continue;

package/dist/lib/assignee-resolver.d.ts

@@ -9,12 +9,13 @@
  * reference into exactly one member of the task's space, or an actionable
  * failure that names the candidates.
  *
- * Scoping to the space is not just ergonomics. The server rejects assignees
- * that are not space members (`SpacePermissionService.validateAssigneeSpaceMembership`
- * → `ASSIGNEE_NOT_IN_SPACE`), so resolving against the space membership list
- * means a name that resolves is a name that will be accepted — we never build
- * a request the server is guaranteed to refuse, and we cannot accidentally
- * leak a directory-wide user search into a space the caller can't see.
+ * Scoping to the space is not just ergonomics. The server accepts space members
+ * and, beyond them, only the caller's own agent when it is shared with no one
+ * else (`AgentTaskConsent` → otherwise `ASSIGNEE_NOT_IN_SPACE`), so a name that
+ * resolves against the membership list is a name that will be accepted, and we
+ * cannot accidentally leak a directory-wide user search into a space the caller
+ * can't see. An owner-delegated agent is not a member and so is not resolvable
+ * by name here; it is passed by raw id.
  */
 export type MemberKind = 'user' | 'agent';
 export type SpaceMember = {

package/dist/lib/daemonBroker.d.ts

@@ -36,6 +36,7 @@
  * liveness with `process.kill(pid, 0)` to filter stale files left behind
  * by a force-killed daemon.
  */
+import { type AuthBackend } from './auth-storage';
 import { type CliConfig } from './config';
 /**
  * Wire-shape of the bootstrap file. Mirrors
@@ -86,6 +87,13 @@ export interface DaemonBrokerResult {
      * the mint/confirm split, where the mint still revoked eagerly.
      */
     familyId?: string;
+    /**
+     * Where `attemptDaemonBrokerLoginAndPersist` actually stored the credential.
+     * Callers label the token's source from this, not from the platform: Keychain
+     * only exists on macOS, and even there a failed Keychain write falls back to
+     * the file.
+     */
+    storedIn?: Exclude<AuthBackend, 'none'>;
 }
 /**
  * Explicit reasons the broker path could fail. These exist to keep the
@@ -139,6 +147,8 @@ export interface DaemonBrokerOptions {
     profile?: string;
     /** Override the bootstrap file path entirely (tests / unusual layouts). */
     bootstrapPathOverride?: string;
+    /** Test seam: the ordered candidate list, when one path is not enough. */
+    candidatePathsOverride?: readonly string[];
     /** Override total request timeout. Tests use a short value. */
     timeoutMs?: number;
 }
@@ -159,6 +169,24 @@ export declare function resolveProfileBootstrapPaths(primary: string, entryNames
  * deterministic when more than one matching daemon is running.
  */
 export declare function resolveBootstrapCandidatePaths(profile?: string): string[];
+/**
+ * A Dedicated Runtime guest's workload hand-off descriptor.
+ *
+ * On that product the daemon runs as `skrr-runtime` and everything the user runs
+ * — terminals, Bash tool calls, engines — as `skrr-workload`, so the island
+ * bootstrap above sits in a home this process cannot read. The daemon publishes
+ * this second descriptor to the shared workload group instead
+ * (`daemon/src/dedicated-cli-handoff.ts`). Its secret is accepted by the
+ * cli-handoff route and nothing else, so it is a hand-off candidate ONLY: it is
+ * deliberately absent from `resolveBootstrapCandidatePaths`, which message-intent
+ * submission also reads and which needs the island secret.
+ *
+ * Fixed and root-controlled (the daemon unit's RuntimeDirectory), so nothing the
+ * user configures can point the broker somewhere else.
+ */
+export declare const DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR = "/run/skrr-dedicated-runtime/cli-handoff/descriptor.json";
+/** Where the cli-handoff broker looks, in order. */
+export declare function resolveCliHandoffCandidatePaths(profile?: string): string[];
 /**
  * Resolve the first live daemon bootstrap for a profile. Message-intent
  * submission reuses the same authenticated loopback discovery as the login

package/dist/lib/daemonBroker.js

@@ -71,10 +71,12 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR = void 0;
 exports.normalizeBaseUrl = normalizeBaseUrl;
 exports.resolveBootstrapPath = resolveBootstrapPath;
 exports.resolveProfileBootstrapPaths = resolveProfileBootstrapPaths;
 exports.resolveBootstrapCandidatePaths = resolveBootstrapCandidatePaths;
+exports.resolveCliHandoffCandidatePaths = resolveCliHandoffCandidatePaths;
 exports.findLiveDaemonBootstrap = findLiveDaemonBootstrap;
 exports.readBootstrap = readBootstrap;
 exports.attemptDaemonBrokerLogin = attemptDaemonBrokerLogin;
@@ -164,6 +166,33 @@ function resolveBootstrapCandidatePaths(profile = 'default') {
         return process.platform === 'darwin' ? [primary] : [primary, legacyBootstrapPath()];
     }
 }
+/**
+ * A Dedicated Runtime guest's workload hand-off descriptor.
+ *
+ * On that product the daemon runs as `skrr-runtime` and everything the user runs
+ * — terminals, Bash tool calls, engines — as `skrr-workload`, so the island
+ * bootstrap above sits in a home this process cannot read. The daemon publishes
+ * this second descriptor to the shared workload group instead
+ * (`daemon/src/dedicated-cli-handoff.ts`). Its secret is accepted by the
+ * cli-handoff route and nothing else, so it is a hand-off candidate ONLY: it is
+ * deliberately absent from `resolveBootstrapCandidatePaths`, which message-intent
+ * submission also reads and which needs the island secret.
+ *
+ * Fixed and root-controlled (the daemon unit's RuntimeDirectory), so nothing the
+ * user configures can point the broker somewhere else.
+ */
+exports.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR = '/run/skrr-dedicated-runtime/cli-handoff/descriptor.json';
+/** Where the cli-handoff broker looks, in order. */
+function resolveCliHandoffCandidatePaths(profile = 'default') {
+    const candidates = resolveBootstrapCandidatePaths(profile);
+    // Any profile: a guest runs one daemon, and the auto-broker resolves the
+    // default profile regardless of `--profile`, so a narrower condition here would
+    // only describe behaviour production never reaches.
+    if (process.platform === 'linux') {
+        candidates.push(exports.DEDICATED_RUNTIME_CLI_HANDOFF_DESCRIPTOR);
+    }
+    return candidates;
+}
 /**
  * Pre-Phase-K bootstrap path (non-darwin). Read-only fallback consulted
  * when the canonical path is absent — covers a freshly-upgraded daemon
@@ -247,13 +276,15 @@ function readBootstrap(filePath) {
  */
 async function attemptDaemonBrokerLogin(opts) {
     const profile = opts.profile ?? 'default';
-    const candidates = opts.bootstrapPathOverride
-        ? [opts.bootstrapPathOverride]
-        : resolveBootstrapCandidatePaths(profile);
-    let bootstrap = null;
-    let usedPath = null;
-    let unboundBootstrap = null;
-    let unboundPath = null;
+    const candidates = opts.candidatePathsOverride
+        ? [...opts.candidatePathsOverride]
+        : opts.bootstrapPathOverride
+            ? [opts.bootstrapPathOverride]
+            : resolveCliHandoffCandidatePaths(profile);
+    // Bound candidates (their serverUrl matches this CLI) in order, then unbound
+    // ones. Every usable candidate is kept, not just the first: see below.
+    const usable = [];
+    const unbound = [];
     let mismatchedBootstrap = null;
     for (const candidate of candidates) {
         const candidateBootstrap = readBootstrap(candidate);
@@ -269,19 +300,13 @@ async function attemptDaemonBrokerLogin(opts) {
         }
         if (typeof candidateBootstrap.serverUrl !== 'string' ||
             candidateBootstrap.serverUrl.length === 0) {
-            unboundBootstrap ??= candidateBootstrap;
-            unboundPath ??= candidate;
+            unbound.push(candidateBootstrap);
             continue;
         }
-        bootstrap = candidateBootstrap;
-        usedPath = candidate;
-        break;
-    }
-    if (!bootstrap && unboundBootstrap && unboundPath) {
-        bootstrap = unboundBootstrap;
-        usedPath = unboundPath;
+        usable.push(candidateBootstrap);
     }
-    if (!bootstrap || !usedPath) {
+    usable.push(...unbound);
+    if (usable.length === 0) {
         if (mismatchedBootstrap?.serverUrl) {
             return {
                 ok: false,
@@ -296,6 +321,22 @@ async function attemptDaemonBrokerLogin(opts) {
             detail: `No daemon bootstrap file found (looked in ${candidates.join(', ')})`,
         };
     }
+    // A candidate nothing is listening behind moves on to the next one. Liveness is
+    // only a pid check, and EPERM counts as alive — on a Dedicated Runtime guest
+    // nearly every pid belongs to another uid, so a stale island file in the
+    // workload's own home (restored dotfiles, say) passes it and used to shadow the
+    // daemon's live hand-off descriptor forever, with `skrr` reporting "Not signed
+    // in". Only a refused connection falls through: any answer, or a timeout, is a
+    // daemon that is really there, and its outcome stands.
+    let outcome = null;
+    for (const bootstrap of usable) {
+        outcome = await brokerThrough(bootstrap, opts);
+        if (outcome.ok || outcome.reason !== 'network')
+            return outcome;
+    }
+    return outcome;
+}
+async function brokerThrough(bootstrap, opts) {
     const url = `http://${bootstrap.host}:${bootstrap.port}/v1/auth/cli-handoff`;
     const timeoutMs = opts.timeoutMs ?? REQUEST_TIMEOUT_MS;
     const controller = new AbortController();
@@ -486,7 +527,7 @@ async function attemptDaemonBrokerLoginAndPersist(opts) {
     if (!serverOrigin) {
         throw new Error('Daemon-broker credential persistence requires a valid CLI baseURL.');
     }
-    (0, auth_storage_1.writeToBackend)({
+    const storedIn = (0, auth_storage_1.writeToBackend)({
         token: outcome.accessToken,
         refreshToken: outcome.refreshToken,
         ...(expiryToEpochMs(outcome.accessExpiresAt) !== undefined
@@ -507,7 +548,7 @@ async function attemptDaemonBrokerLoginAndPersist(opts) {
             familyId: outcome.familyId,
         });
     }
-    return outcome;
+    return storedIn === 'none' ? outcome : { ...outcome, storedIn };
 }
 // ---------------------------------------------------------------------
 // Auto-broker on first command (BaseCommand.init hook)

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

@@ -0,0 +1,22 @@
+import { readDedicatedRuntimeFileChunk, writeDedicatedRuntimeFileChunk, type DedicatedRuntimeScope } from './dedicated-machines';
+/**
+ * The two copy loops behind `skrr machines dedicated cp`.
+ *
+ * One API request per 512 KiB chunk, so every chunk passes the same owner
+ * check, generation fence and daemon file policy as any other access to the
+ * machine. Neither end is replaced until the whole file has arrived: an upload
+ * 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.
+ */
+export interface DedicatedCopyIo {
+    readChunk: typeof readDedicatedRuntimeFileChunk;
+    writeChunk: typeof writeDedicatedRuntimeFileChunk;
+    chunkBytes: number;
+    maxBytes: number;
+}
+export interface DedicatedCopyResult {
+    bytes: number;
+    destination: string;
+}
+export declare function uploadToDedicatedRuntime(localPath: string, leaseId: string, remotePath: string, scope?: DedicatedRuntimeScope, io?: Partial<DedicatedCopyIo>): Promise<DedicatedCopyResult>;
+export declare function downloadFromDedicatedRuntime(leaseId: string, remotePath: string, localPath: string, scope?: DedicatedRuntimeScope, io?: Partial<DedicatedCopyIo>): Promise<DedicatedCopyResult>;

package/dist/lib/dedicated-copy.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadToDedicatedRuntime = uploadToDedicatedRuntime;
+exports.downloadFromDedicatedRuntime = downloadFromDedicatedRuntime;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const dedicated_machines_1 = require("./dedicated-machines");
+const defaultIo = {
+    readChunk: dedicated_machines_1.readDedicatedRuntimeFileChunk,
+    writeChunk: dedicated_machines_1.writeDedicatedRuntimeFileChunk,
+    chunkBytes: dedicated_machines_1.DEDICATED_FILE_CHUNK_BYTES,
+    maxBytes: dedicated_machines_1.DEDICATED_FILE_MAX_BYTES,
+};
+function mib(bytes) {
+    return `${Math.round((bytes / (1024 * 1024)) * 10) / 10} MiB`;
+}
+async function uploadToDedicatedRuntime(localPath, leaseId, remotePath, scope = {}, io = {}) {
+    const { writeChunk, chunkBytes, maxBytes } = { ...defaultIo, ...io };
+    const info = await (0, promises_1.stat)(localPath);
+    if (!info.isFile()) {
+        throw new Error(`${localPath} is not a regular file`);
+    }
+    if (info.size > maxBytes) {
+        throw new Error(`${localPath} is ${mib(info.size)}; copy is limited to ${mib(maxBytes)}. Push it through Git or object storage instead.`);
+    }
+    const transferId = `cp-${Date.now().toString(36)}-${(0, node_crypto_1.randomBytes)(6).toString('hex')}`;
+    const handle = await (0, promises_1.open)(localPath, 'r');
+    try {
+        const buffer = Buffer.alloc(chunkBytes);
+        let offset = 0;
+        for (;;) {
+            const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, offset);
+            const final = offset + bytesRead >= info.size;
+            if (!final && bytesRead === 0) {
+                throw new Error(`${localPath} shrank while it was being copied`);
+            }
+            const result = await writeChunk(leaseId, {
+                path: remotePath,
+                transferId,
+                offset,
+                dataBase64: buffer.subarray(0, bytesRead).toString('base64'),
+                // 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 } : {}),
+            }, scope);
+            offset += bytesRead;
+            if (final) {
+                return { bytes: offset, destination: `${leaseId}:${result.path || remotePath}` };
+            }
+        }
+    }
+    catch (err) {
+        // Best effort: remove the staged partial so it does not sit beside the
+        // destination. The destination itself was never touched.
+        await writeChunk(leaseId, { path: remotePath, transferId, offset: 0, abort: true }, scope).catch(() => undefined);
+        throw err;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function downloadFromDedicatedRuntime(leaseId, remotePath, localPath, scope = {}, io = {}) {
+    const { readChunk, chunkBytes } = { ...defaultIo, ...io };
+    let target = localPath;
+    try {
+        if ((await (0, promises_1.stat)(localPath)).isDirectory()) {
+            target = (0, node_path_1.join)(localPath, (0, node_path_1.basename)(remotePath));
+        }
+    }
+    catch {
+        // Does not exist yet: it names the file.
+    }
+    await (0, promises_1.mkdir)((0, node_path_1.dirname)(target), { recursive: true });
+    const temporary = (0, node_path_1.join)((0, node_path_1.dirname)(target), `.${(0, node_path_1.basename)(target)}.skrr-download-${(0, node_crypto_1.randomBytes)(6).toString('hex')}`);
+    const handle = await (0, promises_1.open)(temporary, 'wx');
+    let closed = false;
+    let offset = 0;
+    let size = -1;
+    let mtimeMs = -1;
+    try {
+        for (;;) {
+            const chunk = await readChunk(leaseId, { path: remotePath, offset, length: chunkBytes }, scope);
+            if (size === -1) {
+                size = chunk.size;
+                mtimeMs = chunk.mtimeMs;
+            }
+            else if (chunk.size !== size || chunk.mtimeMs !== mtimeMs) {
+                // Chunks from two versions of a file splice into one that never existed.
+                throw new Error(`${remotePath} changed on the machine while it was being copied`);
+            }
+            const bytes = Buffer.from(chunk.dataBase64, 'base64');
+            if (bytes.byteLength !== chunk.bytesRead) {
+                throw new Error('A chunk arrived damaged; nothing was written to the destination');
+            }
+            await handle.write(bytes, 0, bytes.byteLength, offset);
+            offset += bytes.byteLength;
+            if (chunk.eof)
+                break;
+            if (bytes.byteLength === 0) {
+                throw new Error(`${remotePath} ended before its reported size`);
+            }
+        }
+        await handle.close();
+        closed = true;
+        await (0, promises_1.rename)(temporary, target);
+        return { bytes: offset, destination: target };
+    }
+    catch (err) {
+        if (!closed)
+            await handle.close().catch(() => undefined);
+        await (0, promises_1.unlink)(temporary).catch(() => undefined);
+        throw err;
+    }
+}

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

@@ -0,0 +1,50 @@
+import { BaseCommand } from '../base-command';
+import { type DedicatedRuntimeResponse, type DedicatedRuntimeScope } from './dedicated-machines';
+import { type DedicatedWaitGoal } from './dedicated-wait';
+/**
+ * Lifecycle calls answer 202 with the lease already in its transitional state.
+ * `--wait` watches it to the END of the operation, which for snapshot and grow
+ * is a field, not a state (see `dedicated-wait.ts`).
+ */
+export declare const dedicatedWaitFlags: {
+    wait: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    timeout: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    interval: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+};
+export declare abstract class DedicatedLeaseCommand extends BaseCommand {
+    /**
+     * `--workspace` is a BaseCommand flag every command already accepts (it sets
+     * `X-Workspace-Id` for the whole invocation). It is also passed as the scope
+     * query, the way `create`, `exec` and `cp` always have, so the scope a request
+     * was made in is visible in the request itself.
+     */
+    protected scopeFrom(flags: {
+        workspace?: string;
+    }): DedicatedRuntimeScope;
+    /**
+     * Open an interactive terminal on a lease's machine and run it to the end,
+     * exiting with the shell's own code.
+     *
+     * Every refusal is decided BEFORE the socket opens where it can be — a stopped
+     * machine, a daemon that is not connected, stdin that is not a terminal — so
+     * the caller gets a sentence that says what to do instead of a start that
+     * hangs and times out.
+     */
+    protected openDedicatedTerminal(leaseId: string, flags: {
+        workspace?: string;
+        cwd?: string;
+    }, initialCommand?: string): Promise<void>;
+    /** Run an API call, turning a refusal into the server's own sentence. */
+    protected callDedicated<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Print the lease an action returned, or wait for its operation to finish
+     * first when `--wait` was passed.
+     */
+    protected reportLeaseAction(response: DedicatedRuntimeResponse | undefined, flags: {
+        json?: boolean;
+        wait?: boolean;
+        timeout?: string;
+        interval?: number;
+        workspace?: string;
+    }, goal: DedicatedWaitGoal | null, verb: string): Promise<void>;
+}