@nomac/cli 0.2.5 → 0.3.0-beta.1

package/bin/nomac.mjs

@@ -2,6 +2,9 @@
 import { main } from "../src/cli.mjs";
 
 main(process.argv.slice(2)).catch((err) => {
-  console.error(err?.friendly ?? err?.message ?? String(err));
+  const args = process.argv.slice(2);
+  if (["start", "sync", "pull", "stop", "session", "transport"].includes(args[0]) && args.includes("--json")) {
+    console.error(JSON.stringify({ error: { code: err?.code ?? "session_error", message: err?.friendly ?? err?.message ?? String(err), ...(err?.details ? { details: err.details } : {}) } }));
+  } else console.error(err?.friendly ?? err?.message ?? String(err));
   process.exit(err?.exitCode ?? 1);
 });

package/bin/rsync-ssh.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Private rsync transport. stdout is the binary rsync protocol, never CLI logging.
+import { rsyncServerCommand, runProcess, sshArgs } from "../src/session-ssh.mjs";
+
+try {
+  const session = JSON.parse(process.env.NOMAC_TRANSFER_SESSION ?? "null");
+  if (!session) throw new Error("This helper is started by nomac sync/pull.");
+  const command = rsyncServerCommand(session, process.argv.slice(2), session.remoteDirectory);
+  await runProcess("ssh", [...sshArgs(session), session.target, command], { inherit: true });
+} catch (error) {
+  console.error(error.friendly ?? error.message);
+  process.exitCode = error.exitCode ?? 1;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nomac/cli",
-  "version": "0.2.5",
-  "description": "Ship iOS apps to TestFlight and the App Store without a Mac — built for agents.",
+  "version": "0.3.0-beta.1",
+  "description": "Cloud Mac sessions over SSH and HTTPS, plus iOS builds and publishing — built for agents.",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {
@@ -20,7 +20,10 @@
   },
   "dependencies": {
     "ignore": "^7.0.0",
-    "tar": "^7.4.0"
+    "tar": "^7.4.0",
+    "ws": "^8.21.3",
+    "https-proxy-agent": "^9.1.0",
+    "proxy-from-env": "^2.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",

package/src/api.mjs

@@ -1,12 +1,13 @@
 import { loadApiKey, loadApiUrl } from "./config.mjs";
 
 export class CliError extends Error {
-  constructor(message, friendly, status, code) {
+  constructor(message, friendly, status, code, details) {
     super(message);
     this.friendly = friendly ?? message;
     this.exitCode = 1;
     this.status = status;
     this.code = code;
+    this.details = details;
   }
 }
 
@@ -33,7 +34,7 @@ export async function api(method, path, { body, raw, idempotencyKey } = {}) {
   if (!key) {
     throw new CliError(
       "not logged in",
-      "Not logged in. Run `nomac login <api-key>` (create a key in the dashboard) or set NOMAC_API_KEY.",
+      "Not logged in. Run `nomac login` and approve access in your browser, or set NOMAC_API_KEY.",
     );
   }
   const url = `${loadApiUrl()}${path}`;
@@ -49,13 +50,17 @@ export async function api(method, path, { body, raw, idempotencyKey } = {}) {
       ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
     },
     body: raw ?? (body !== undefined ? JSON.stringify(body) : undefined),
+  }).catch(() => {
+    throw new CliError("Request outcome unknown", "The response was lost. Reconcile the previous operation before retrying; reuse its request_key.", undefined, "outcome_unknown", { code: "outcome_unknown", ...(idempotencyKey ? { request_key: idempotencyKey } : {}) });
+  });
+  const text = await res.text().catch(() => {
+    throw new CliError("Response body was lost", "Reconcile the previous operation before retrying; reuse its request_key.", res.status, "outcome_unknown", { code: "outcome_unknown", ...(idempotencyKey ? { request_key: idempotencyKey } : {}) });
   });
-  const text = await res.text();
   let json;
   try {
     json = text ? JSON.parse(text) : {};
   } catch {
-    throw new CliError(`API returned non-JSON (HTTP ${res.status}): ${text.slice(0, 200)}`, undefined, res.status);
+    throw new CliError(`API returned non-JSON (HTTP ${res.status})`, "The response could not be read. Reconcile the operation before retrying; reuse its request_key.", res.status, "bad_response", { code: "bad_response", ...(idempotencyKey ? { request_key: idempotencyKey } : {}) });
   }
   if (!res.ok) {
     const err = json?.error ?? {};
@@ -64,6 +69,7 @@ export async function api(method, path, { body, raw, idempotencyKey } = {}) {
       err.message ?? `API error (HTTP ${res.status})`,
       res.status,
       err.code,
+      { ...err, ...(idempotencyKey ? { request_key: idempotencyKey } : {}) },
     );
   }
   return json;

package/src/cli.mjs

@@ -4,9 +4,30 @@ import { loadProjectState, saveApiKey, saveProjectState } from "./config.mjs";
 import { packTarball } from "./pack.mjs";
 import { uploadSourceSnapshot } from "./upload.mjs";
 
-const HELP = `nomac — ship iOS apps without a Mac (agent-first)
+const HELP = `nomac — Mac workspaces for agents / iOS app publishing
 
-Usage:
+Nomac 2.0 cloud Macs:
+  nomac credits               weekly hours and plan checkout
+  nomac start                 allocate or reconnect to your Mac
+  nomac exec --request-key KEY -- command args
+  nomac job JOB_ID             inspect a submitted command
+  nomac output JOB_ID          read resumable command output
+  nomac start --help           session limits and usage
+
+Existing Mac workspaces:
+  nomac start --host user@mac connect a dedicated Mac you control
+  nomac sync .                upload changed project files
+  nomac ssh                   open the full Mac shell
+  nomac pull ./output         retrieve a remote directory
+  nomac session status --json show workspace and connection information
+  nomac stop                  detach locally (does not end a rental)
+  nomac start --help          setup, exclusions and preview limitations
+
+Nomac 2.0 transport probe:
+  nomac tunnel <session>       SSH through the configured port-443 gateway
+  nomac transport --help       HTTPS jobs, resumable output and binary probes
+
+Existing publishing commands:
   nomac login                  connect this device (approve in the browser)
   nomac login <api-key>        store an nmk_ key directly (CI / power users)
   nomac push                   pack this directory and upload a snapshot
@@ -22,6 +43,40 @@ Environment: NOMAC_API_KEY, NOMAC_API_URL`;
 export async function main(argv) {
   const [cmd, ...rest] = argv;
   switch (cmd) {
+    case "credits": {
+      const { creditsCommand } = await import("./mac-credits.mjs");
+      return creditsCommand(rest);
+    }
+    case "tunnel": {
+      if (rest.length !== 1) throw new CliError("Usage: nomac tunnel <session-id>");
+      const { tunnel } = await import("./mac-transport.mjs");
+      if (process.env.NOMAC_SESSION_TOKEN) return tunnel(rest[0]);
+      const { sessionAccess } = await import("./hosted-sessions.mjs");
+      const access = await sessionAccess(rest[0].replace(/^nomac-/, ""));
+      return tunnel(rest[0], { gateway: access.gateway, token: access.token });
+    }
+    case "transport": {
+      const { transportCommand } = await import("./transport-command.mjs");
+      return transportCommand(rest);
+    }
+    case "start":
+    case "exec":
+    case "job":
+    case "output":
+    case "sync":
+    case "ssh":
+    case "pull":
+    case "stop":
+    case "session": {
+      const { sessionStore } = await import("./session-store.mjs");
+      const store = sessionStore();
+      if (!rest.includes("--host") && !rest.some(value => value.startsWith("--host=")) && store.load()?.mode !== "external_ssh") {
+        const { hostedSessionCommand } = await import("./hosted-sessions.mjs");
+        return hostedSessionCommand(cmd, rest, { store });
+      }
+      const { sessionCommand } = await import("./sessions.mjs");
+      return sessionCommand(cmd, rest);
+    }
     case "login": {
       const key = rest[0];
       if (key) {

package/src/hosted-sessions.mjs

@@ -0,0 +1,171 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { api, CliError } from "./api.mjs";
+import { sessionStore } from "./session-store.mjs";
+import { forwardingArg, runProcess, sshArgs, workspaceCommand } from "./session-ssh.mjs";
+import { pullProject, syncProject } from "./session-transfer.mjs";
+import { macRequest, sessionId, transportOptions } from "./mac-transport.mjs";
+
+const HELP = `Nomac cloud Mac sessions
+  nomac start [--wait 300] [--max-duration 7200] [--idle-timeout 600] [--max-cost 5] [--json]
+  nomac sync . [--dry-run]           upload changed files
+  nomac ssh [--forward 8080:3000]    full Mac shell and port forwarding
+  nomac ssh -- command args         run any command over SSH
+  nomac exec --request-key KEY -- command args
+  nomac job JOB_ID                  reconcile a submitted command
+  nomac output JOB_ID [--cursor 0] [--stream stdout|stderr]
+  nomac pull ./output [--from PATH] retrieve files before stopping
+  nomac session status --json       live state, cost and cleanup status
+  nomac stop [--wait 60] --json      request shutdown and wait for confirmation
+
+Login once with nomac login. The CLI creates a local SSH key; it sends only the
+public key. Sessions use the port-443 gateway and verified guest host keys.
+Time continues while the VM is ready, including between commands. Inspect the
+returned offer and limits. Stop removes the VM and its files; pull first.
+A wait timeout leaves the session attached: inspect status or run stop.
+Use nomac start --host user@mac to connect an existing Mac instead.`;
+const options = {
+  help: { type: "boolean" }, json: { type: "boolean" }, wait: { type: "string" },
+  "max-duration": { type: "string" }, "idle-timeout": { type: "string" },
+  "max-cost": { type: "string" }, "request-key": { type: "string" }, timeout: { type: "string" },
+  overwrite: { type: "boolean" }, "dry-run": { type: "boolean" }, from: { type: "string" },
+  forward: { type: "string", multiple: true }, cursor: { type: "string" }, stream: { type: "string" },
+};
+function budget(value = "5") {
+  if (!/^(?:0|[1-9][0-9]{0,5})(?:\.[0-9]{1,6})?$/.test(value)) throw new CliError("--max-cost must be a positive USD amount, for example 5 or 2.50.");
+  const [whole, fraction = ""] = value.split(".");
+  const result = BigInt(whole) * 1000000n + BigInt(fraction.padEnd(6, "0"));
+  if (result <= 0n) throw new CliError("--max-cost must be positive.");
+  return result.toString();
+}
+function integer(value, fallback, min, max) {
+  if (value === undefined) return fallback;
+  if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < min || Number(value) > max) throw new CliError("Invalid numeric option.");
+  return Number(value);
+}
+export async function sessionAccess(id, request = api) {
+  sessionId(id);
+  const access = await request("POST", `/api/v1/mac/sessions/${id}/access`);
+  if (access.session_id !== id || !Number.isSafeInteger(access.generation) || access.generation < 1 || access.ssh?.username !== "agent" || !/^ssh-ed25519 [A-Za-z0-9+/]+={0,2}(?: [^\r\n\x00]*)?$/.test(access.ssh?.host_key ?? "")) throw new CliError("Invalid session access response.");
+  // Validates the gateway origin and token without saving bearer credentials to disk.
+  transportOptions({ gateway: access.gateway, token: access.token });
+  return access;
+}
+export async function hostedRequest(id, method, path, params = {}, { request = api, transport = macRequest } = {}) {
+  const access = await sessionAccess(id, request);
+  return transport(method, path, { ...params, gateway: access.gateway, token: access.token });
+}
+export async function hostedSessionCommand(command, argv, { store = sessionStore(), request = api, transport = macRequest, run = runProcess, print = console.log, sleep = ms => new Promise(r => setTimeout(r, ms)), now = Date.now } = {}) {
+  let parsed;
+  try { parsed = parseArgs({ args: argv, options, allowPositionals: true }); }
+  catch (error) { throw new CliError(error.message); }
+  const { values, positionals } = parsed;
+  if (values.help) return print(HELP);
+  const output = result => {
+    const billing = result.session?.billing;
+    const usage = billing?.mode === "weekly_included"
+      ? `Included time used: ${billing.used_seconds} seconds. No extra charge.`
+      : `Cost: ${JSON.stringify(result.session?.cost)}`;
+    print(values.json || !["start", "stop"].includes(command) ? JSON.stringify(result, null, 2) : `${result.session.id}: ${result.session.state}\n${result.session.state === "ready" ? "Next: nomac sync . → nomac ssh" : "Check: nomac session status --json"}\n${usage}`);
+    return result;
+  };
+  const saveView = (local, view) => {
+    if (view.id !== local.id && local.id) throw new CliError("Session response mismatch.");
+    sessionId(view.id);
+    Object.assign(local, { id: view.id, state: view.state, snapshot: view }); store.save(local);
+    return view;
+  };
+  const refresh = async local => saveView(local, (await request("GET", `/api/v1/mac/sessions/${sessionId(local.id)}`)).session);
+  async function ready(local) {
+    await refresh(local);
+    if (local.state !== "ready") throw new CliError("Mac is not ready.", `Session ${local.id} is ${local.state}. Run nomac session status --json.`, undefined, "session_not_ready");
+    const access = await sessionAccess(local.id, request);
+    if (local.generation && (local.generation !== access.generation || local.hostKey !== access.ssh.host_key)) throw new CliError("The guest identity changed. Stop this session and start a fresh one.", undefined, undefined, "host_key_changed");
+    Object.assign(local, { generation: access.generation, hostKey: access.ssh.host_key, target: `agent@nomac-${local.id}`, workspace: "/Users/agent/workspace", knownHosts: join(store.directory, "known_hosts") });
+    writeFileSync(local.knownHosts, `nomac-${local.id} ${access.ssh.host_key}\n`, { mode: 0o600 }); chmodSync(local.knownHosts, 0o600); store.save(local);
+    return local;
+  }
+  const localSession = () => {
+    const local = store.load();
+    if (local?.mode !== "hosted" || !local.id) throw new CliError("No attached cloud session.", "Run nomac start to allocate or reconcile your Mac.");
+    return local;
+  };
+  if (command === "session") {
+    if (positionals.length !== 1 || !["status", "info"].includes(positionals[0])) throw new CliError("Usage: nomac session status --json");
+    const local = localSession(); return output({ session: await refresh(local) });
+  }
+  if (["exec", "job", "output"].includes(command)) {
+    const local = localSession(), base = `/api/v1/mac/sessions/${sessionId(local.id)}`;
+    let path, method = "GET", params = {};
+    if (command === "exec") {
+      if (!positionals.length || !argv.includes("--") || !/^[A-Za-z0-9_.:-]{8,128}$/.test(values["request-key"] ?? "")) throw new CliError("Use nomac exec --request-key STABLE_KEY -- command args");
+      method = "POST"; path = `${base}/jobs`; params = { requestKey: values["request-key"], body: { argv: positionals, timeout_seconds: integer(values.timeout, 60, 1, 600) } };
+    } else {
+      if (positionals.length !== 1 || !/^job_[a-f0-9]{40}$/.test(positionals[0])) throw new CliError("Supply the existing job ID.");
+      path = `${base}/jobs/${positionals[0]}`;
+      if (command === "output") {
+        const cursor = integer(values.cursor, 0, 0, Number.MAX_SAFE_INTEGER), stream = values.stream ?? "stdout";
+        if (!["stdout", "stderr"].includes(stream)) throw new CliError("Use stdout or stderr.");
+        path += `/output?cursor=${cursor}&stream=${stream}`;
+      }
+    }
+    return output(await hostedRequest(local.id, method, path, params, { request, transport }));
+  }
+  if (command === "ssh") {
+    if (values.json) throw new CliError("SSH streams bytes. Use session status --json for metadata.");
+    const local = await ready(localSession());
+    return run("ssh", [...sshArgs(local, { batch: false }), ...(!positionals.length && process.stdin.isTTY ? ["-t"] : []), ...(values.forward ?? []).flatMap(v => ["-L", forwardingArg(v)]), "-o", "ExitOnForwardFailure=yes", local.target, workspaceCommand(local, positionals)], { inherit: true });
+  }
+  return store.locked(async () => {
+    if (command === "start") {
+      if (positionals.length) throw new CliError("Usage: nomac start [--wait SECONDS] [--json]");
+      let local = store.load();
+      if (local && local.mode !== "hosted") throw new CliError("An existing Mac workspace is attached.");
+      const limits = { max_duration_seconds: integer(values["max-duration"], 7200, 60, 86400), idle_timeout_seconds: integer(values["idle-timeout"], 600, 60, 3600), spend_cap_microunits: budget(values["max-cost"]) };
+      if (local && !["stopped", "failed"].includes(local.state)) {
+        for (const [flag, field] of [["max-duration", "max_duration_seconds"], ["idle-timeout", "idle_timeout_seconds"], ["max-cost", "spend_cap_microunits"]]) {
+          if (values[flag] !== undefined && limits[field] !== local.request.limits[field]) throw new CliError("This session already has different limits. Stop it and start a fresh session to change them.");
+        }
+        if (values["request-key"] !== undefined && values["request-key"] !== local.requestKey) throw new CliError("A session is already attached under a different request key. Inspect it or stop it before starting another.");
+      }
+      if (!local || ["stopped", "failed"].includes(local.state)) {
+        const identity = join(store.directory, `id_ed25519_${randomUUID()}`);
+        await run("ssh-keygen", ["-q", "-t", "ed25519", "-N", "", "-C", "nomac-session", "-f", identity]);
+        local = { mode: "hosted", state: "requesting", identity, requestKey: values["request-key"] ?? `cli-${randomUUID()}`, request: { profile: "standard", public_key: readFileSync(`${identity}.pub`, "utf8").trim(), limits } };
+        store.save(local); store.saveBaseline({});
+      }
+      if (!local.id) {
+        const result = await request("POST", "/api/v1/mac/sessions", { idempotencyKey: local.requestKey, body: local.request });
+        saveView(local, result.session);
+      }
+      const deadline = now() + integer(values.wait, 300, 0, 600) * 1000;
+      for (;;) {
+        await refresh(local);
+        if (!["queued", "provisioning"].includes(local.state) || now() >= deadline) break;
+        await sleep(2000);
+      }
+      if (local.state === "ready") await ready(local);
+      return output({ session: local.snapshot, request_key: local.requestKey });
+    }
+    const local = localSession();
+    if (command === "stop") {
+      if (positionals.length) throw new CliError("Usage: nomac stop [--wait SECONDS] [--json]");
+      saveView(local, (await request("DELETE", `/api/v1/mac/sessions/${sessionId(local.id)}`)).session);
+      const deadline = now() + integer(values.wait, 60, 0, 300) * 1000;
+      while (!["stopped", "failed"].includes(local.state) && now() < deadline) { await sleep(1000); await refresh(local); }
+      return output({ session: local.snapshot });
+    }
+    await ready(local);
+    if (command === "sync") {
+      if (positionals.length > 1 || (positionals[0] && resolve(positionals[0]) !== store.project)) throw new CliError("Run nomac sync . from the attached project.");
+      return output(await syncProject(local, store, { overwrite: values.overwrite, dryRun: values["dry-run"], run }));
+    }
+    if (command === "pull") {
+      if (positionals.length !== 1) throw new CliError("Usage: nomac pull LOCAL_PATH [--from REMOTE_PATH]");
+      return output(await pullProject(local, store, positionals[0], { from: values.from ?? positionals[0], overwrite: values.overwrite, dryRun: values["dry-run"], run }));
+    }
+    throw new CliError("Unknown cloud session command.");
+  });
+}

package/src/mac-credits.mjs

@@ -0,0 +1,10 @@
+import { parseArgs } from "node:util";
+import { api, CliError } from "./api.mjs";
+export async function creditsCommand(argv, { request = api, print = console.log } = {}) {
+  const { values, positionals } = parseArgs({ args: argv, options: { plan: { type: "string" }, "request-key": { type: "string" }, json: { type: "boolean" }, help: { type: "boolean" } }, allowPositionals: true });
+  if (values.help) return print("nomac credits [--json]\nnomac credits --plan five|twenty_five --request-key STABLE_KEY\n$5/week for 5 hours or $20/week for 25 hours. Unused hours expire weekly.\nReturns a subscription checkout link; the human reviews and pays. Reuse the key after a lost response.");
+  if (positionals.length) throw new CliError("Unexpected credits argument.");
+  if (!values.plan) return print(JSON.stringify(await request("GET", "/api/v1/mac/credits"), null, 2));
+  if (!["five", "twenty_five"].includes(values.plan) || !/^[A-Za-z0-9_.:-]{8,128}$/.test(values["request-key"] ?? "")) throw new CliError("Choose --plan five or twenty_five and supply a stable --request-key.");
+  return print(JSON.stringify(await request("POST", "/api/v1/mac/credits/checkout", { idempotencyKey: values["request-key"], body: { plan: values.plan } }), null, 2));
+}

package/src/mac-tools.mjs

@@ -0,0 +1,18 @@
+import { api } from "./api.mjs";
+const text = value => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
+const session = { type: "string", pattern: "^ses_[A-Za-z0-9_-]{1,80}$" };
+const job = { type: "string", pattern: "^job_[a-f0-9]{40}$" };
+const key = { type: "string", pattern: "^[A-Za-z0-9_.:-]{8,128}$" };
+const schema = (properties, required = []) => ({ type: "object", properties, required, additionalProperties: false });
+const base = args => `/api/v1/mac/sessions/${encodeURIComponent(args.session_id)}`;
+export const MAC_TOOLS = [
+  { name: "get_mac_checkout", description: "Return a weekly subscription checkout: five is $5/week for 5 hours; twenty_five is $20/week for 25 hours. Renews until canceled; no rollover or overage. The human reviews and subscribes. Reuse request_key after a lost response.", inputSchema: schema({ plan: { type: "string", enum: ["five", "twenty_five"] }, request_key: key }, ["plan", "request_key"]), handler: async ({ plan, request_key }) => text(await api("POST", "/api/v1/mac/credits/checkout", { body: { plan }, idempotencyKey: request_key })) },
+  { name: "get_mac_credits", description: "Read weekly Mac hours, expiry, reservations and concurrency, separate from legacy build subscriptions.", inputSchema: schema({}), handler: async () => text(await api("GET", "/api/v1/mac/credits")) },
+  { name: "start_mac", description: "Allocate a full cloud Mac VM. Supply a stable request_key; SSH public_key is optional for HTTPS-only agents; reuse both after a lost response. Inspect the returned offer and limits. Poll get_mac_session until ready. No project pipeline is imposed; stop_mac deletes the VM and files.", inputSchema: schema({ public_key: { type: "string" }, request_key: key, limits: { type: "object", properties: { max_duration_seconds: { type: "integer", minimum: 60, maximum: 86400 }, idle_timeout_seconds: { type: "integer", minimum: 60, maximum: 3600 }, spend_cap_microunits: { type: "string", pattern: "^[1-9][0-9]{0,17}$" } }, additionalProperties: false } }, ["request_key"]), handler: async ({ request_key, ...body }) => text(await api("POST", "/api/v1/mac/sessions", { body, idempotencyKey: request_key })) },
+  { name: "list_mac_sessions", description: "Find existing Mac sessions, including after losing a response. Shows state, cost, limits and cleanup.", inputSchema: schema({}), handler: async () => text(await api("GET", "/api/v1/mac/sessions")) },
+  { name: "get_mac_session", description: "Read live Mac allocation state, cost, funded time and cleanup confirmation. queued/provisioning means wait; stopping is not yet confirmed cleanup.", inputSchema: schema({ session_id: session }, ["session_id"]), handler: async args => text(await api("GET", base(args))) },
+  { name: "stop_mac", description: "Stop billing by shutting down the VM and deleting its files. Retrieve files first. Poll get_mac_session until cleanup_confirmed; stopping only acknowledges the request.", inputSchema: schema({ session_id: session }, ["session_id"]), handler: async args => text(await api("DELETE", base(args))) },
+  { name: "exec_mac", description: "Run any argv command in your cloud Mac workspace. Returns a durable job ID; poll get_mac_job and read_mac_output. Reuse request_key and identical arguments after lost responses; never submit a new key blindly. Use bash -lc explicitly for shell syntax.", inputSchema: schema({ session_id: session, request_key: key, argv: { type: "array", items: { type: "string" }, minItems: 1 }, timeout_seconds: { type: "integer", minimum: 1, maximum: 600 } }, ["session_id", "request_key", "argv"]), handler: async ({ session_id, request_key, ...body }) => text(await api("POST", `${base({ session_id })}/jobs`, { body, idempotencyKey: request_key })) },
+  { name: "get_mac_job", description: "Inspect the existing command without rerunning it. Retain its job ID until completion and retrieve output before stopping the VM.", inputSchema: schema({ session_id: session, job_id: job }, ["session_id", "job_id"]), handler: async args => text(await api("GET", `${base(args)}/jobs/${encodeURIComponent(args.job_id)}`)) },
+  { name: "read_mac_output", description: "Read a bounded stdout/stderr chunk by byte cursor. data_base64 preserves binary output. Resume from next_cursor; retrieve before stopping the VM.", inputSchema: schema({ session_id: session, job_id: job, cursor: { type: "integer", minimum: 0 }, stream: { type: "string", enum: ["stdout", "stderr"] } }, ["session_id", "job_id"]), handler: async args => text(await api("GET", `${base(args)}/jobs/${encodeURIComponent(args.job_id)}/output?${new URLSearchParams({ cursor: String(args.cursor ?? 0), stream: args.stream ?? "stdout" })}`)) },
+];

package/src/mac-transport.mjs

@@ -0,0 +1,118 @@
+import http from "node:http";
+import https from "node:https";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { getProxyForUrl } from "proxy-from-env";
+import WebSocket, { createWebSocketStream } from "ws";
+import { CliError } from "./api.mjs";
+
+export function sessionId(value) {
+  const id = String(value ?? "").replace(/^nomac-/, "");
+  if (!/^ses_[A-Za-z0-9_-]{1,80}$/.test(id)) throw new CliError("Invalid Mac session ID.", undefined, undefined, "invalid_session");
+  return id;
+}
+
+export function transportOptions(options = {}) {
+  let url;
+  try { url = new URL(options.gateway ?? process.env.NOMAC_GATEWAY_URL); }
+  catch { throw new CliError("Set NOMAC_GATEWAY_URL to the HTTPS gateway origin.", undefined, undefined, "gateway_required"); }
+  const loopback = ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname);
+  if ((url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) || url.username || url.password || url.search || url.hash || url.pathname !== "/") {
+    throw new CliError("The gateway must be an HTTPS origin; HTTP is allowed only for a loopback probe.", undefined, undefined, "invalid_gateway");
+  }
+  const token = options.token ?? process.env.NOMAC_SESSION_TOKEN;
+  if (typeof token !== "string" || !/^[A-Za-z0-9_-]{32,2048}$/.test(token)) throw new CliError("Set NOMAC_SESSION_TOKEN to a session-scoped access token.", undefined, undefined, "token_required");
+  const proxy = options.proxy ?? getProxyForUrl(url.href);
+  return { url, token, agent: proxy ? new HttpsProxyAgent(proxy) : undefined, ca: options.ca };
+}
+
+/** Bounded requests deliberately do not require streaming responses or retry mutations. */
+export function macRequest(method, path, { body, raw, requestKey, ...options } = {}) {
+  const { url, token, agent, ca } = transportOptions(options);
+  if (!path.startsWith("/api/v1/mac/") || path.includes("#")) throw new CliError("Invalid Mac API path.");
+  const target = new URL(path, url);
+  if (target.origin !== url.origin) throw new CliError("Invalid Mac API origin.");
+  const payload = raw ?? (body === undefined ? undefined : Buffer.from(JSON.stringify(body)));
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const fail = (code, message, status) => {
+      if (settled) return;
+      settled = true;
+      reject(new CliError(message, undefined, status, code, requestKey ? { request_key: requestKey } : undefined));
+    };
+    const request = (target.protocol === "https:" ? https : http).request(target, {
+      method, agent, ca, headers: {
+        authorization: `Bearer ${token}`,
+        ...(payload ? { "content-type": raw ? "application/octet-stream" : "application/json", "content-length": payload.length } : {}),
+        ...(requestKey ? { "idempotency-key": requestKey } : {}),
+      },
+    }, response => {
+      const chunks = []; let bytes = 0;
+      response.on("data", chunk => {
+        bytes += chunk.length;
+        if (bytes > 768 * 1024) {
+          fail("response_too_large", "The gateway response exceeded its limit.");
+          response.destroy();
+        } else chunks.push(chunk);
+      });
+      response.on("error", () => fail("outcome_unknown", "Response lost. Inspect the job or retry with the same request key."));
+      response.on("end", () => {
+        if (settled) return;
+        let data;
+        try { data = JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+        catch { return fail("bad_response", "The gateway returned an unreadable response. Reconcile before retrying.", response.statusCode); }
+        if (response.statusCode < 200 || response.statusCode >= 300) return fail(data.error?.code ?? "gateway_error", data.error?.message ?? "The Mac request failed.", response.statusCode);
+        settled = true;
+        resolve(data);
+      });
+    });
+    const deadline = setTimeout(() => request.destroy(new Error("deadline")), 15_000);
+    request.on("close", () => clearTimeout(deadline));
+    request.on("error", () => fail("outcome_unknown", "Connection lost. Inspect the job or retry with the same request key."));
+    request.end(payload);
+  });
+}
+
+/** A ProxyCommand: stdout contains only SSH bytes, never status or cost messages. */
+export function tunnel(value, { input = process.stdin, output = process.stdout, ...options } = {}) {
+  const id = sessionId(value);
+  const { url, token, agent, ca } = transportOptions(options);
+  url.pathname = `/api/v1/mac/sessions/${id}/ssh`;
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url, {
+      agent, ca, headers: { authorization: `Bearer ${token}` },
+      handshakeTimeout: 15_000, perMessageDeflate: false, maxPayload: 1024 * 1024,
+      followRedirects: false,
+    });
+    const stream = createWebSocketStream(ws, { highWaterMark: 64 * 1024 });
+    let failure, closedCode, settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      input.unpipe(stream); stream.unpipe(output); input.pause();
+      input.removeListener("error", fail); output.removeListener("error", fail);
+      if (failure || closedCode !== 1000) reject(failure ?? new CliError("SSH tunnel closed unexpectedly.", undefined, undefined, "tunnel_disconnected"));
+      else resolve();
+    };
+    const fail = () => { failure ??= new CliError("SSH tunnel disconnected. Reconnect explicitly; an existing SSH connection cannot be resumed.", undefined, undefined, "tunnel_disconnected"); stream.destroy(); finish(); };
+    stream.on("error", fail);
+    input.on("error", fail);
+    output.on("error", fail);
+    ws.on("unexpected-response", (_req, response) => {
+      failure = new CliError(`SSH tunnel refused (HTTP ${response.statusCode}).`, undefined, response.statusCode, "tunnel_refused");
+      response.resume();
+      ws.terminate();
+    });
+    ws.on("error", fail);
+    ws.on("close", code => {
+      closedCode = code;
+      input.unpipe(stream); input.pause();
+      if (code !== 1000 || failure) { stream.destroy(); finish(); }
+    });
+    // A close frame can arrive while the consumer is backpressured. Drain all
+    // buffered SSH bytes and the last output write before resolving.
+    stream.on("end", () => output.write(Buffer.alloc(0), error => { if (error) fail(); else finish(); }));
+    stream.pipe(output, { end: false });
+    input.pipe(stream);
+  });
+}

package/src/mcp.mjs

@@ -11,6 +11,7 @@ import { loadProjectState, saveProjectState } from "./config.mjs";
 import { packTarball } from "./pack.mjs";
 import { uploadSourceSnapshot } from "./upload.mjs";
 import { uploadStoreAsset } from "./store-upload.mjs";
+import { MAC_TOOLS } from "./mac-tools.mjs";
 
 const PROTOCOL_FALLBACK = "2025-06-18";
 
@@ -27,6 +28,32 @@ async function resolveProjectId(args) {
 }
 
 export const TOOLS = [
+  ...MAC_TOOLS,
+  {
+    name: "check_project", description: "Free source-readiness check of the latest uploaded snapshot. No Apple credentials or paid compute. Run push_project first or after code changes; this does not prove compilation or TestFlight delivery.",
+    inputSchema: { type: "object", properties: { project_id: { type: "string" } }, additionalProperties: false },
+    handler: async args => text(await api("POST", "/api/v1/check-project", { body: { project_id: await resolveProjectId(args) } })),
+  },
+  {
+    name: "get_billing_status", description: "Read confirmed payment, contracted prices, quota/reset, renewal and first-purchase refund eligibility. After payment, resume a blocked build once with a fresh request_key only if the earlier response said build_started:false. Reconcile unknown outcomes first.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    handler: async () => text(await api("GET", "/api/v1/billing/status")),
+  },
+  {
+    name: "get_checkout_link", description: "Return an org-bound checkout link; the human chooses a plan and pays explicitly. This tool does not charge them. Reuses pending checkout; existing subscribers get billing management instead.",
+    inputSchema: { type: "object", properties: { plan: { type: "string", enum: ["starter", "pro"] } }, additionalProperties: false },
+    handler: async args => text(await api("POST", "/api/v1/billing/checkout", { body: args })),
+  },
+  {
+    name: "request_refund", description: "Preview the first-purchase refund amount and subscription cancellation. Default confirm:false. Present the quote and effect to the customer; only after explicit authorization for both actions call with confirm:true and its request_id. A build failure alone does not authorize a refund. Reason is optional.",
+    inputSchema: { type: "object", properties: { confirm: { type: "boolean", default: false }, request_id: { type: "string" }, reason: { type: "string", maxLength: 1000 } }, additionalProperties: false },
+    handler: async args => text(await api("POST", "/api/v1/billing/refund", { body: args })),
+  },
+  {
+    name: "get_refund_status", description: "Read the saved refund and cancellation progress. Does not submit a refund or cancel anything.",
+    inputSchema: { type: "object", properties: { request_id: { type: "string" } }, required: ["request_id"], additionalProperties: false },
+    handler: async args => text(await api("GET", `/api/v1/billing/refund?request_id=${encodeURIComponent(args.request_id)}`)),
+  },
   {
     name: "upload_store_asset",
     description: "Upload a new Apple screenshot, preview, purchase image, supplemental reviewer attachment or encryption document from file_path (up to 500 MiB, subject to Apple limits) or data_base64 (2 MiB). Discover the createInstance operation/body and parent scope with get_store_capabilities/read_store. Preview by default; confirm:true reserves, uploads and commits. Preserve request_key and identical bytes/body to resume. ready:true requires Apple processing COMPLETE. Message attachments require App Store Connect.",
@@ -114,6 +141,7 @@ export const TOOLS = [
       properties: {
         project_id: { type: "string" },
         workflow: { type: "string", enum: ["release", "smoke"], default: "release" },
+        request_key: { type: "string", description: "Reuse this key to reconcile an unknown response. Use a fresh key after a confirmed build_started:false and payment/setup completion." },
       },
       additionalProperties: false,
     },
@@ -121,7 +149,7 @@ export const TOOLS = [
       const project_id = await resolveProjectId(args);
       const res = await api("POST", "/api/v1/builds", {
         body: { project_id, workflow: args?.workflow ?? "release" },
-        idempotencyKey: `mcp-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+        idempotencyKey: args?.request_key ?? `mcp-${randomUUID()}`,
       });
       let warning;
       try {
@@ -400,7 +428,7 @@ export async function runMcpServer() {
             reply(await tool.handler(params?.arguments ?? {}));
           } catch (err) {
             reply({
-              content: [{ type: "text", text: err?.friendly ?? err?.message ?? String(err) }],
+              content: [{ type: "text", text: err?.details ? JSON.stringify({ error: { ...err.details, message: err.friendly ?? err.message } }, null, 2) : err?.friendly ?? err?.message ?? String(err) }],
               isError: true,
             });
           }

package/src/session-ssh.mjs

@@ -0,0 +1,135 @@
+import { spawn } from "node:child_process";
+import { isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "./api.mjs";
+
+export const shellQuote = (value) => `'${String(value).replaceAll("'", "'\\''")}'`;
+
+export function validateTarget(target) {
+  // A hostname or user-owned SSH config alias, never command-line options or a shell expression.
+  if (typeof target !== "string" || !/^(?:[a-zA-Z0-9_][a-zA-Z0-9_.-]*@)?[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/.test(target)) {
+    throw new CliError("invalid SSH target", "Use --host user@hostname or an alias from your SSH config. For IPv6, configure an SSH alias first.", undefined, "invalid_ssh_target");
+  }
+  return target;
+}
+
+export function validateWorkspace(path) {
+  if (typeof path !== "string" || !path.startsWith("/") || path === "/" || /[\x00-\x1f\x7f]/.test(path) || path.split("/").some(part => part === ".." || part === ".")) {
+    throw new CliError("invalid workspace", "The Mac returned an invalid workspace path.");
+  }
+  return path;
+}
+
+export function sshArgs(session, { batch = true } = {}) {
+  validateTarget(session.target);
+  if (session.port !== undefined && (!Number.isInteger(session.port) || session.port < 1 || session.port > 65535)) throw new CliError("invalid SSH port");
+  if (session.identity && (!isAbsolute(session.identity) || /[\x00-\x1f\x7f]/.test(session.identity))) throw new CliError("invalid identity path");
+  if (session.mode === "hosted") {
+    if (!/^ses_[A-Za-z0-9_-]{1,80}$/.test(session.id) || !isAbsolute(session.knownHosts ?? "") || /[\x00-\x1f\x7f]/.test(session.knownHosts)) throw new CliError("invalid hosted SSH state");
+  }
+  return [
+    ...(session.mode === "hosted" ? ["-F", "/dev/null", "-o", `UserKnownHostsFile=${session.knownHosts}`, "-o", "GlobalKnownHostsFile=/dev/null",
+      "-o", `HostKeyAlias=nomac-${session.id}`, "-o", `ProxyCommand=${[process.execPath, fileURLToPath(new URL("../bin/nomac.mjs", import.meta.url)), "tunnel", session.id].map(shellQuote).join(" ")}`] : []),
+    "-o", "StrictHostKeyChecking=yes", "-o", "ForwardAgent=no",
+    "-o", "ConnectTimeout=15", "-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=3",
+    // Avoid reusing a separately owned master connection with different authentication/forwarding.
+    "-o", "ControlMaster=no", "-o", "ControlPath=none",
+    ...(batch ? ["-o", "BatchMode=yes", "-o", "ClearAllForwardings=yes"] : []),
+    ...(session.port ? ["-p", String(session.port)] : []),
+    ...(session.identity ? ["-i", session.identity, "-o", "IdentitiesOnly=yes"] : []),
+  ];
+}
+
+export function runProcess(program, args, { input, inherit = false, maxBytes = 8 * 1024 * 1024, timeoutMs, env } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(program, args, { shell: false, stdio: inherit ? "inherit" : ["pipe", "pipe", "pipe"], ...(env ? { env } : {}) });
+    const output = [], errors = [];
+    let bytes = 0, failure, timer;
+    const stop = (message) => { failure = new CliError(message); child.kill("SIGTERM"); };
+    if (timeoutMs) timer = setTimeout(() => stop("Remote operation timed out; inspect its outcome before retrying."), timeoutMs);
+    if (!inherit) {
+      for (const [stream, chunks] of [[child.stdout, output], [child.stderr, errors]]) {
+        stream.on("data", chunk => {
+          bytes += chunk.length;
+          if (bytes > maxBytes) stop("Command output exceeded the capture limit. Run the command through nomac ssh to stream its output.");
+          else chunks.push(chunk);
+        });
+      }
+      child.stdin.on("error", error => { if (error.code !== "EPIPE") failure = error; });
+      child.stdin.end(input);
+    }
+    child.on("error", error => {
+      clearTimeout(timer);
+      reject(new CliError(error.message, error.code === "ENOENT" ? `${program} is required but was not found in PATH.` : error.message, undefined, error.code === "ENOENT" ? "tool_missing" : "process_failed"));
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      if (failure) return reject(failure);
+      const result = { code: code ?? 1, signal, stdout: Buffer.concat(output).toString("utf8"), stderr: Buffer.concat(errors).toString("utf8") };
+      if (code !== 0) {
+        const error = new CliError(`${program} exited ${code ?? signal}`, result.stderr.trim() || `${program} exited ${code ?? signal}`, undefined, program === "ssh" ? "ssh_failed" : "transfer_failed");
+        error.exitCode = code && code > 0 ? code : 1;
+        error.result = result;
+        return reject(error);
+      }
+      resolve(result);
+    });
+  });
+}
+
+export function remote(session, script, { run = runProcess, ...options } = {}) {
+  return run("ssh", [...sshArgs(session), session.target, script], { timeoutMs: 60_000, ...options });
+}
+
+/** Does not install a project pipeline or run source code. Creates only this owned workspace. */
+export async function prepareWorkspace(session, options) {
+  if (!/^nms_[a-f0-9]{32}$/.test(session.id)) throw new CliError("invalid session id");
+  const location = session.workspace
+    ? shellQuote(validateWorkspace(session.workspace))
+    : `"$HOME/.nomac/workspaces/${session.id}"`;
+  const script = [
+    'test "$(uname -s)" = Darwin || { echo "Nomac needs a macOS host." >&2; exit 1; }',
+    "command -v rsync >/dev/null || { echo 'Install rsync on the Mac before using file transfer.' >&2; exit 1; }",
+    "perl -MJSON::PP -MDigest::SHA -MEncode -MFcntl -e 'exit 0' || { echo 'Perl checksum and JSON modules are required for file conflict checks.' >&2; exit 1; }",
+    `umask 077; mkdir -p ${location} && cd ${location} || exit 1`,
+    "pwd -P", "sw_vers -productVersion", "uname -m",
+    'if [ "$(id -u)" = 0 ]; then echo admin; else id -Gn; fi', "df -Pk . | tail -1 | awk '{print $4}'",
+  ].join("\n");
+  const { stdout } = await remote(session, script, options);
+  const lines = stdout.trimEnd().split("\n");
+  if (lines.length !== 5) throw new CliError("unexpected Mac response", "The SSH shell printed unexpected output. Ensure non-interactive startup files are quiet, then retry nomac start.");
+  const [workspace, osVersion, architecture, groups, availableKb] = lines;
+  validateWorkspace(workspace);
+  if (!/^[0-9]+(?:\.[0-9]+)*$/.test(osVersion) || !/^[a-zA-Z0-9_]+$/.test(architecture) || !/^\d+$/.test(availableKb)) throw new CliError("invalid Mac capabilities");
+  const admin = groups.split(/\s+/).includes("admin");
+  if (!admin) throw new CliError("administrator account required", "This account is not a macOS administrator. Use an administrator account for a full Nomac workspace.");
+  return { workspace, capabilities: { os: "macOS", version: osVersion, architecture, administrator: admin, available_disk_bytes: Number(availableKb) * 1024 } };
+}
+
+export function workspaceCommand(session, args = []) {
+  const command = args.length ? args.map(shellQuote).join(" ") : '"$SHELL" -l';
+  return `cd ${shellQuote(validateWorkspace(session.workspace))} && exec ${command}`;
+}
+
+export function forwardingArg(value) {
+  const match = /^(\d{1,5}):(\d{1,5})$/.exec(value);
+  if (!match || match.slice(1).some(port => Number(port) < 1 || Number(port) > 65535)) throw new CliError("invalid port mapping", "Use --forward LOCAL_PORT:REMOTE_PORT, for example --forward 8080:3000.");
+  return `127.0.0.1:${Number(match[1])}:127.0.0.1:${Number(match[2])}`;
+}
+
+/** rsync has its own argument parser, not a POSIX shell: quoted apostrophes double. */
+export const rsyncQuote = (value) => `'${String(value).replaceAll("'", "''")}'`;
+
+export function rsyncServerCommand(session, argv, from = ".") {
+  const index = argv.findIndex((arg, i) => arg === "rsync" && argv[i + 1] === "--server");
+  if (index === -1) throw new CliError("invalid rsync server command");
+  const source = String(from);
+  if (source.startsWith("/") || source.split("/").includes("..") || /[\x00-\x1f\x7f\\]/.test(source)) throw new CliError("invalid transfer source");
+  return [
+    `cd ${shellQuote(validateWorkspace(session.workspace))} || exit 1`,
+    `p=${shellQuote(source === "." ? "." : `./${source}`)}`,
+    'while [ "$p" != . ]; do test ! -L "$p" || exit 1; p=$(dirname "$p"); done',
+    `cd ${shellQuote(source)} || exit 1`,
+    `exec ${argv.slice(index).map(shellQuote).join(" ")}`,
+  ].join("\n");
+}

package/src/session-store.mjs

@@ -0,0 +1,45 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CliError } from "./api.mjs";
+
+/** Session metadata stays outside the project: a checkout cannot choose an SSH target. */
+export function sessionStore(projectDir = process.cwd(), stateDir = join(homedir(), ".nomac", "sessions")) {
+  const project = realpathSync(projectDir);
+  const name = createHash("sha256").update(project).digest("hex").slice(0, 24);
+  const directory = join(stateDir, name);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  chmodSync(directory, 0o700);
+  const stateFile = join(directory, "session.json");
+  const baselineFile = join(directory, "baseline.json");
+  const read = (file) => {
+    if (!existsSync(file)) return null;
+    try { return JSON.parse(readFileSync(file, "utf8")); }
+    catch { throw new CliError("invalid session state", `Cannot read ${file}. Restore it before continuing; no remote operation was started.`); }
+  };
+  const write = (file, data) => {
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(temporary, JSON.stringify(data, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+      renameSync(temporary, file);
+    } finally { rmSync(temporary, { force: true }); }
+  };
+  return {
+    project, directory,
+    load: () => read(stateFile),
+    save: (value) => write(stateFile, value),
+    baseline: () => read(baselineFile) ?? {},
+    saveBaseline: (value) => write(baselineFile, value),
+    async locked(operation) {
+      const lock = join(directory, "operation.lock");
+      try { mkdirSync(lock, { mode: 0o700 }); }
+      catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        throw new CliError("session busy", `Another session operation is running. If it was interrupted, verify it has ended before removing ${lock}.`);
+      }
+      try { return await operation(); }
+      finally { rmSync(lock, { recursive: true, force: true }); }
+    },
+  };
+}

package/src/session-transfer.mjs

@@ -0,0 +1,215 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants, copyFileSync, createReadStream, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, chmodSync, utimesSync } from "node:fs";
+import { dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import ignoreFactory from "ignore";
+import { CliError } from "./api.mjs";
+import { remote, rsyncQuote, runProcess, shellQuote, validateWorkspace } from "./session-ssh.mjs";
+
+const EXCLUDED = [
+  ".git/", ".nomac/", ".nomac.json", ".nomac-transfer/", "node_modules/", "Pods/", "build/", "dist/", "DerivedData/", ".build/", ".next/",
+  ".env", ".env.*", "*.p8", "*.p12", "*.pem", "*.key", "*.mobileprovision", ".ssh/", ".aws/", ".netrc", ".npmrc", "id_rsa*", "id_ed25519*", ".DS_Store",
+];
+
+export function projectFiles(root) {
+  const denied = ignoreFactory().add(EXCLUDED);
+  const files = [], skippedLinks = [];
+  const walk = (directory, inherited = []) => {
+    const scopes = [...inherited];
+    for (const name of [".gitignore", ".nomacignore"]) {
+      const path = join(directory, name);
+      // Ignore files themselves must not read through a symlink outside the project.
+      if (existsSync(path) && lstatSync(path).isFile()) scopes.push({ root: directory, rules: ignoreFactory().add(readFileSync(path, "utf8")) });
+    }
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name), rel = relative(root, path).split(sep).join("/");
+      const candidate = rel + (entry.isDirectory() ? "/" : "");
+      if (denied.ignores(candidate)) continue;
+      let ignored = false;
+      for (const scope of scopes) {
+        const result = scope.rules.test(relative(scope.root, path).split(sep).join("/") + (entry.isDirectory() ? "/" : ""));
+        if (result.ignored) ignored = true;
+        if (result.unignored) ignored = false;
+      }
+      if (ignored) continue;
+      if (entry.isSymbolicLink()) skippedLinks.push(rel);
+      else if (entry.isDirectory()) walk(path, scopes);
+      else if (entry.isFile()) files.push(rel);
+    }
+  };
+  walk(root);
+  return { files: files.sort(), skippedLinks: skippedLinks.sort() };
+}
+
+export async function fingerprint(path) {
+  const stat = lstatSync(path);
+  if (!stat.isFile()) return stat.isSymbolicLink() ? "symlink" : "other";
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path, { flags: constants.O_RDONLY | constants.O_NOFOLLOW })) hash.update(chunk);
+  return `file:${hash.digest("hex")}:${(stat.mode & 0o777).toString(8)}`;
+}
+
+export function safeRelative(path) {
+  if (typeof path !== "string" || isAbsolute(path) || path.split(/[\\/]/).includes("..") || /[\x00-\x1f\x7f]/.test(path) || path.includes("\\")) throw new CliError("invalid relative path", "Use a path within the workspace, without '..' or control characters.");
+  return posix.normalize(path || ".").replace(/\/$/, "") || ".";
+}
+
+// One process per batch, rather than launching shasum/stat for every source file.
+// These Perl modules ship with the Perl used by macOS's checksum tools.
+const REMOTE_FINGERPRINTS = `
+use strict; use warnings;
+use JSON::PP; use Digest::SHA; use Encode qw(encode_utf8);
+use Fcntl qw(O_RDONLY O_NOFOLLOW);
+my $json = JSON::PP->new->utf8;
+my $names = $json->decode(do { local $/; <STDIN> });
+die "Invalid file list" unless ref($names) eq 'ARRAY';
+my %result;
+for my $name (@$names) {
+  die "Invalid path" if ref($name) || $name =~ m{^/|(?:^|/)\\.\\.(?:/|$)|[\\x00-\\x1f\\x7f\\\\]};
+  my $file = './' . encode_utf8($name);
+  my @parts = split m{/}, $file;
+  my $unsafe = 0;
+  while (@parts > 1) {
+    if (-l join('/', @parts)) { $unsafe = 1; last; }
+    pop @parts;
+  }
+  if ($unsafe) { $result{$name} = 'symlink'; next; }
+  if (!-e $file) { $result{$name} = 'missing'; next; }
+  if (!-f $file) { $result{$name} = 'other'; next; }
+  sysopen(my $handle, $file, O_RDONLY | O_NOFOLLOW) or die "Cannot open source file";
+  binmode($handle);
+  my $mode = sprintf('%o', (stat($handle))[2] & 0777);
+  my $digest = Digest::SHA->new(256)->addfile($handle)->hexdigest;
+  close($handle);
+  $result{$name} = "file:$digest:$mode";
+}
+print $json->encode(\\%result);
+`;
+
+export async function remoteFingerprints(session, files, options) {
+  const result = Object.create(null);
+  for (let offset = 0; offset < files.length; offset += 1000) {
+    const batch = files.slice(offset, offset + 1000);
+    for (const path of batch) safeRelative(path);
+    const script = `cd ${shellQuote(validateWorkspace(session.workspace))} && perl -e ${shellQuote(REMOTE_FINGERPRINTS)}`;
+    const { stdout } = await remote(session, script, { ...options, input: JSON.stringify(batch) });
+    let values;
+    try { values = JSON.parse(stdout); } catch { throw new CliError("invalid remote file response"); }
+    if (!values || Array.isArray(values) || Object.keys(values).length !== batch.length) throw new CliError("invalid remote file response");
+    for (const path of batch) {
+      const value = Object.hasOwn(values, path) && values[path];
+      if (typeof value !== "string" || !/^(?:missing|symlink|other|file:[a-f0-9]{64}:[0-7]{1,4})$/.test(value)) throw new CliError("invalid remote fingerprint");
+      Object.defineProperty(result, path, { value, enumerable: true, configurable: true, writable: true });
+    }
+  }
+  return result;
+}
+
+function transferArgs() {
+  const bridge = fileURLToPath(new URL("../bin/rsync-ssh.mjs", import.meta.url));
+  return ["-rpt", "--checksum", "--itemize-changes", "--stats", "--timeout=60", "-e", [process.execPath, bridge].map(rsyncQuote).join(" ")];
+}
+
+const transferEnv = (session, remoteDirectory = ".") => ({ ...process.env, NOMAC_TRANSFER_SESSION: JSON.stringify({ ...session, remoteDirectory }) });
+
+function conflictError(paths, side) {
+  const error = new CliError("transfer conflict", `${side} changes would be overwritten: ${paths.slice(0, 10).join(", ")}. Retrieve/reconcile the changes first, or explicitly use --overwrite.`);
+  error.code = "transfer_conflict";
+  error.details = { paths, side };
+  return error;
+}
+
+export async function syncProject(session, store, { overwrite = false, dryRun = false, run = runProcess } = {}) {
+  const { files, skippedLinks } = projectFiles(store.project);
+  if (!files.length) throw new CliError("no project files", "No files remain after .gitignore, .nomacignore and default exclusions.");
+  const local = Object.create(null);
+  for (const path of files) local[path] = await fingerprint(join(store.project, path));
+  const baseline = Object.assign(Object.create(null), store.baseline());
+  const previous = await remoteFingerprints(session, files, { run });
+  const unsafe = files.filter(path => ["symlink", "other"].includes(previous[path]));
+  if (unsafe.length) throw new CliError("unsafe remote path", `Remote paths are symlinks or have incompatible types: ${unsafe.slice(0, 10).join(", ")}. Resolve them inside the workspace first.`);
+  const conflicts = files.filter(path => previous[path] !== "missing" && previous[path] !== local[path] && previous[path] !== baseline[path]);
+  if (conflicts.length && !overwrite) throw conflictError(conflicts, "Remote");
+  if (dryRun) return { dry_run: true, files: files.length, changed: files.filter(path => previous[path] !== local[path]), skipped_symlinks: skippedLinks };
+  const output = await run("rsync", [...transferArgs(), "--from0", "--files-from=-", `${store.project}/`, `${session.target}:./`], { input: Buffer.from(files.join("\0") + "\0"), env: transferEnv(session) });
+  const after = await remoteFingerprints(session, files, { run });
+  const changedDuringTransfer = files.filter(path => after[path] !== local[path]);
+  for (const path of files) if (after[path] === local[path]) baseline[path] = local[path];
+  store.saveBaseline(baseline);
+  if (changedDuringTransfer.length) throw new CliError("transfer changed during verification", "Some files changed during transfer. Stop concurrent edits and rerun sync; verified files were recorded.");
+  return { files: files.length, changed: files.filter(path => previous[path] !== local[path]), skipped_symlinks: skippedLinks, output: output.stdout };
+}
+
+/** Refuse symlink ancestors, including the destination itself, before local writes. */
+export function assertSafeDestination(root, target) {
+  const rel = relative(root, target);
+  if (rel.startsWith(`..${sep}`) || rel === ".." || isAbsolute(rel)) throw new CliError("destination escapes project");
+  let current = root;
+  for (const part of rel.split(sep).filter(Boolean)) {
+    current = join(current, part);
+    try { if (lstatSync(current).isSymbolicLink()) throw new CliError("unsafe local path", `Refusing to write through symlink: ${current}`); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+}
+
+export async function pullProject(session, store, destination, { from = destination, overwrite = false, dryRun = false, run = runProcess } = {}) {
+  destination = safeRelative(destination); from = safeRelative(from);
+  const localRoot = resolve(store.project, destination);
+  assertSafeDestination(store.project, localRoot);
+  const staging = mkdtempSync(join(store.directory, "pull-"));
+  const backup = join(store.directory, "backups", randomUUID());
+  try {
+    // Download into an empty private directory; rsync never receives the user's working tree as destination.
+    await run("rsync", [...transferArgs(), `${session.target}:./`, `${staging}/`], { env: transferEnv(session, from) });
+    const files = [];
+    const walk = (directory) => {
+      for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) walk(path);
+        else if (entry.isFile()) files.push(relative(staging, path));
+        else throw new CliError("unsupported download entry", "The download contains a symlink or special file. Retrieve it explicitly over SSH after reviewing it.");
+      }
+    };
+    walk(staging);
+    const baseline = Object.assign(Object.create(null), store.baseline()), plan = [], conflicts = [];
+    for (const path of files) {
+      const target = join(localRoot, path), incoming = await fingerprint(join(staging, path));
+      assertSafeDestination(store.project, target);
+      const current = existsSync(target) ? await fingerprint(target) : "missing";
+      if (current === "other") throw new CliError("incompatible local path", `A directory or special file occupies ${target}.`);
+      const remotePath = from === "." ? path : `${from.replace(/\/$/, "")}/${path}`;
+      // A baseline is meaningful only when downloading to the original project-relative path.
+      const samePath = relative(store.project, target).split(sep).join("/") === remotePath.split(sep).join("/");
+      if (current !== "missing" && current !== incoming && (!samePath || baseline[remotePath] !== current)) conflicts.push(path);
+      plan.push({ path, target, current, incoming, remotePath, samePath });
+    }
+    if (conflicts.length && !overwrite) throw conflictError(conflicts, "Local");
+    if (dryRun) return { dry_run: true, files: files.length, changed: plan.filter(file => file.current !== file.incoming).map(file => file.path) };
+    let backups = false;
+    for (const file of plan) {
+      assertSafeDestination(store.project, file.target);
+      const current = existsSync(file.target) ? await fingerprint(file.target) : "missing";
+      if (current !== file.current) throw new CliError("local file changed", "A local file changed during pull. Stop concurrent edits and retry. Earlier replacements have recovery copies.");
+      if (current !== file.incoming) {
+        mkdirSync(dirname(file.target), { recursive: true });
+        if (current !== "missing") {
+          const recovery = join(backup, file.path);
+          mkdirSync(dirname(recovery), { recursive: true, mode: 0o700 });
+          copyFileSync(file.target, recovery, constants.COPYFILE_EXCL);
+          backups = true;
+        }
+        const temporary = join(dirname(file.target), `.nomac-download-${randomUUID()}`);
+        try {
+          const sourcePath = join(staging, file.path), stat = lstatSync(sourcePath);
+          copyFileSync(sourcePath, temporary, constants.COPYFILE_EXCL);
+          chmodSync(temporary, stat.mode & 0o777);
+          utimesSync(temporary, stat.atime, stat.mtime);
+          renameSync(temporary, file.target);
+        } finally { rmSync(temporary, { force: true }); }
+      }
+      if (file.samePath) baseline[file.remotePath] = file.incoming;
+    }
+    store.saveBaseline(baseline);
+    return { files: files.length, changed: plan.filter(file => file.current !== file.incoming).map(file => file.path), ...(backups ? { recovery_directory: backup } : {}) };
+  } finally { rmSync(staging, { recursive: true, force: true }); }
+}

package/src/sessions.mjs

@@ -0,0 +1,144 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { CliError } from "./api.mjs";
+import { sessionStore } from "./session-store.mjs";
+import { forwardingArg, prepareWorkspace, runProcess, shellQuote, sshArgs, validateTarget, workspaceCommand } from "./session-ssh.mjs";
+import { pullProject, syncProject } from "./session-transfer.mjs";
+
+export const SESSION_HELP = `Nomac 2.0 — SSH workspace preview
+
+First connection (use a dedicated Mac you control):
+  nomac start --host dev@my-mac [--identity ~/.ssh/id_ed25519] [--port 22]
+
+Then, from the same local project:
+  nomac start                 reconnect to the same Mac workspace
+  nomac sync .                upload changed project files
+  nomac sync --dry-run        inspect changes before uploading
+  nomac ssh                   open a normal shell in the workspace
+  nomac ssh -- node --version run any command (quote shell scripts explicitly)
+  nomac ssh --forward 8080:3000
+  nomac pull ./output         download a remote directory into ./output
+  nomac pull .                bring remote source changes back, with conflict checks
+  nomac session status --json inspect connection, capabilities and ownership
+  nomac stop                  detach locally; the externally owned Mac stays running
+
+Options:
+  sync/pull --overwrite       explicitly replace conflicting files
+  pull --from PATH           choose a different remote directory
+  start/sync/pull/stop --json return machine-readable results
+
+Requires OpenSSH and rsync locally; macOS, rsync and Perl checksum/JSON modules remotely.
+SSH host keys must already be verified in your known_hosts. Your SSH config/agent
+can authenticate; private keys never leave this device. Passwordless sudo is not
+assumed. Use .nomacignore and .gitignore for project exclusions. Symlinks are
+omitted in this preview; use Git/SSH explicitly for projects that need them.
+
+This preview connects an existing Mac. It does not rent hardware, meter charges,
+revoke the owner's SSH access or shut down the Mac. Stop detaches this CLI only;
+existing connections and remote processes continue. Manage rentals with their owner.`;
+
+const commonOptions = { help: { type: "boolean" }, json: { type: "boolean" } };
+const commandOptions = {
+  start: { host: { type: "string" }, identity: { type: "string" }, port: { type: "string" } },
+  sync: { overwrite: { type: "boolean" }, "dry-run": { type: "boolean" } },
+  pull: { overwrite: { type: "boolean" }, "dry-run": { type: "boolean" }, from: { type: "string" } },
+  ssh: { forward: { type: "string", multiple: true } },
+  stop: {}, session: {},
+};
+
+export function describeSession(session) {
+  return {
+    id: session.id, mode: "external_ssh", state: session.state,
+    connection: { target: session.target, port: session.port ?? null, ...(session.identity ? { identity_file: session.identity } : {}) },
+    workspace: session.workspace ?? null, capabilities: session.capabilities ?? null,
+    ssh_command: session.workspace ? ["ssh", ...sshArgs(session, { batch: false }), session.target, workspaceCommand(session)].map(shellQuote).join(" ") : null,
+    checked_at: session.checkedAt ?? null,
+    billing: { managed_by: "mac_owner", nomac_compute_charges: false, rental_end_confirmed: false },
+    retention: "The Mac owner controls retention. Disconnecting or detaching does not remove the workspace.",
+    access_revoked: false, machine_stopped: false,
+  };
+}
+
+function requireReady(store) {
+  const session = store.load();
+  if (!session || session.state !== "ready") throw new CliError("no active workspace", "Run nomac start first. For a new project, use nomac start --host user@mac.", undefined, "no_active_session");
+  if (session.mode !== "external_ssh") throw new CliError("unsupported session mode");
+  return session;
+}
+
+export async function sessionCommand(command, argv, { store: suppliedStore, run = runProcess, print = console.log } = {}) {
+  let parsed;
+  try { parsed = parseArgs({ args: argv, options: { ...commonOptions, ...commandOptions[command] }, allowPositionals: true }); }
+  catch (error) { throw new CliError("invalid session options", `${error.message}\nRun nomac ${command} --help.`); }
+  const { values, positionals } = parsed;
+  if (values.help) return print(SESSION_HELP);
+  const store = suppliedStore ?? sessionStore();
+  const output = (result, summary) => print(values.json ? JSON.stringify(result, null, 2) : summary);
+
+  if (command === "session") {
+    if (positionals.length !== 1 || !["status", "info"].includes(positionals[0])) throw new CliError("session usage", "Usage: nomac session status [--json]");
+    const session = store.load();
+    if (!session) throw new CliError("no workspace", "Run nomac start --host user@mac first.");
+    const result = describeSession(session);
+    return output(result, `${session.state}: ${session.target}\nWorkspace: ${session.workspace ?? "not connected"}\nLast checked: ${session.checkedAt ?? "never"}\nThis is cached status. Run nomac start to check the Mac.\nThe Mac owner controls charges and retention.`);
+  }
+
+  if (command === "ssh") {
+    if (values.json) throw new CliError("SSH is a byte stream", "Use nomac session status --json for connection metadata; SSH streams the remote command directly.");
+    const session = requireReady(store);
+    const forward = (values.forward ?? []).flatMap(value => ["-L", forwardingArg(value)]);
+    const terminal = !positionals.length && process.stdin.isTTY && process.stdout.isTTY;
+    return run("ssh", [...sshArgs(session, { batch: false }), ...(terminal ? ["-t"] : []), ...forward,
+      "-o", "ExitOnForwardFailure=yes", session.target, workspaceCommand(session, positionals)], { inherit: true });
+  }
+
+  return store.locked(async () => {
+    if (command === "start") {
+      if (positionals.length) throw new CliError("start usage", "Usage: nomac start [--host user@mac] [--identity PATH] [--port PORT]");
+      let session = store.load();
+      if (values.host && session?.state === "ready" && session.target !== values.host) throw new CliError("workspace already active", "Run nomac stop before selecting another Mac. Your existing remote files will remain on that Mac.");
+      const target = validateTarget(values.host ?? session?.target ?? "");
+      if (!session || session.target !== target) {
+        session = { id: `nms_${randomUUID().replaceAll("-", "")}`, mode: "external_ssh", state: "connecting", target, createdAt: new Date().toISOString() };
+        store.saveBaseline({});
+      }
+      if (values.port) {
+        if (!/^\d+$/.test(values.port) || Number(values.port) < 1 || Number(values.port) > 65535) throw new CliError("invalid SSH port");
+        session.port = Number(values.port);
+      }
+      if (values.identity) {
+        const identity = resolve(values.identity);
+        if (!existsSync(identity)) throw new CliError("identity missing", `SSH identity file does not exist: ${identity}`);
+        session.identity = realpathSync(identity);
+      }
+      session.state = "connecting";
+      store.save(session); // Retain the same workspace ID if the connection response is lost.
+      const prepared = await prepareWorkspace(session, { run });
+      Object.assign(session, prepared, { state: "ready", checkedAt: new Date().toISOString() });
+      store.save(session);
+      return output(describeSession(session), `Connected to macOS ${prepared.capabilities.version} on ${target}\nWorkspace: ${prepared.workspace}\nNext: nomac sync .  →  nomac ssh\nExisting-Mac preview: rental and retention remain managed by the Mac owner.`);
+    }
+    if (command === "stop") {
+      if (positionals.length) throw new CliError("stop usage", "Usage: nomac stop [--json]");
+      const session = store.load();
+      if (!session) return output({ state: "detached", machine_stopped: false, access_revoked: false }, "No workspace is attached.");
+      session.state = "detached";
+      store.save(session);
+      return output(describeSession(session), "Detached locally. Existing SSH connections, remote processes and files remain.\nThis does not shut down the Mac, revoke owner access or end a rental.\nRun nomac start to reconnect to the same workspace.");
+    }
+    const session = requireReady(store);
+    if (command === "sync") {
+      if (positionals.length > 1 || (positionals[0] && realpathSync(resolve(positionals[0])) !== store.project)) throw new CliError("sync project mismatch", "Run nomac sync . from the project used by nomac start.");
+      const result = await syncProject(session, store, { overwrite: values.overwrite, dryRun: values["dry-run"], run });
+      return output(result, `${result.dry_run ? "Would sync" : "Synced"} ${result.changed.length} changed files (${result.files} considered).${result.skipped_symlinks.length ? `\nSkipped symlinks: ${result.skipped_symlinks.join(", ")}` : ""}`);
+    }
+    if (command === "pull") {
+      if (positionals.length !== 1) throw new CliError("pull usage", "Usage: nomac pull LOCAL_DIRECTORY [--from REMOTE_DIRECTORY] [--dry-run] [--overwrite]");
+      const result = await pullProject(session, store, positionals[0], { from: values.from ?? positionals[0], overwrite: values.overwrite, dryRun: values["dry-run"], run });
+      return output(result, `${result.dry_run ? "Would retrieve" : "Retrieved"} ${result.changed.length} changed files (${result.files} considered).${result.recovery_directory ? `\nPrevious local files: ${result.recovery_directory}` : ""}`);
+    }
+    throw new CliError("unknown session command");
+  });
+}

package/src/transport-command.mjs

@@ -0,0 +1,91 @@
+import { createHash, randomBytes } from "node:crypto";
+import { readFileSync, statSync, writeFileSync, linkSync, unlinkSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { CliError } from "./api.mjs";
+import { macRequest, sessionId } from "./mac-transport.mjs";
+
+const HELP = `Nomac 2.0 transport probe (an operator-configured SSH target; no allocation or billing)
+
+Set NOMAC_GATEWAY_URL and NOMAC_SESSION_TOKEN outside the project.
+  nomac tunnel <session>                          SSH ProxyCommand byte stream
+  nomac transport status <session>                connection capabilities
+  nomac transport exec <session> --request-key KEY [--timeout SECONDS] -- command args...
+  nomac transport job <session> <job>              inspect the existing job
+  nomac transport output <session> <job> [--cursor N] [--stream stdout|stderr]
+  nomac transport put <session> <file>             upload a checksummed probe blob (up to 8 MiB)
+  nomac transport get <session> <sha256> <file>     download a probe blob without overwriting
+
+Results are JSON. Output chunks are base64 with byte cursors, so binary output is lossless.
+Reuse the same request key after a lost response. Commands are never automatically rerun.
+Probe blobs do not yet implement project sync; ordinary SSH/rsync remains available.`;
+
+function parsed(args, allowed) {
+  const values = {};
+  for (let index = 0; index < args.length; index++) {
+    const flag = args[index];
+    if (flag === "--json") continue;
+    if (!allowed.includes(flag) || index + 1 >= args.length || values[flag] !== undefined) throw new CliError(`Unexpected transport option: ${flag}`);
+    values[flag] = args[++index];
+  }
+  return values;
+}
+
+export async function transportCommand(args, { request = macRequest, print = console.log } = {}) {
+  if (!args.length || ["help", "--help"].includes(args[0])) return print(HELP);
+  const [command, value, ...rest] = args;
+  const id = sessionId(value);
+  const base = `/api/v1/mac/sessions/${id}`;
+  let result;
+  if (command === "status") {
+    parsed(rest, []); result = await request("GET", base);
+  } else if (command === "exec") {
+    const separator = rest.indexOf("--");
+    if (separator === -1 || separator === rest.length - 1) throw new CliError("Use -- before the command and its arguments.");
+    const options = parsed(rest.slice(0, separator), ["--request-key", "--timeout"]);
+    if (!/^[A-Za-z0-9_.:-]{8,128}$/.test(options["--request-key"] ?? "")) throw new CliError("Supply a stable --request-key of 8 to 128 safe characters.");
+    const timeout = Number(options["--timeout"] ?? 60);
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > 600) throw new CliError("--timeout must be 1 to 600 seconds.");
+    result = await request("POST", `${base}/jobs`, { requestKey: options["--request-key"], body: { argv: rest.slice(separator + 1), timeout_seconds: timeout } });
+  } else if (command === "job" || command === "output") {
+    const [job, ...flags] = rest;
+    if (!/^job_[a-f0-9]{40}$/.test(job ?? "")) throw new CliError("Invalid job ID.");
+    const options = parsed(flags, command === "output" ? ["--cursor", "--stream"] : []);
+    const cursor = options["--cursor"] ?? "0", stream = options["--stream"] ?? "stdout";
+    if (!/^\d{1,16}$/.test(cursor) || !Number.isSafeInteger(Number(cursor)) || !["stdout", "stderr"].includes(stream)) throw new CliError("Invalid output stream or cursor.");
+    result = await request("GET", `${base}/jobs/${job}${command === "output" ? `/output?cursor=${cursor}&stream=${stream}` : ""}`);
+  } else if (command === "put") {
+    const [file, ...flags] = rest; parsed(flags, []);
+    if (!file) throw new CliError("Supply the file to upload.");
+    const info = statSync(file);
+    if (!info.isFile() || info.size > 8 * 1024 * 1024) throw new CliError("The probe accepts regular files up to 8 MiB.");
+    const data = readFileSync(file);
+    if (data.length > 8 * 1024 * 1024) throw new CliError("The file exceeded the probe limit.");
+    const digest = createHash("sha256").update(data).digest("hex");
+    let offset = 0;
+    do {
+      result = await request("PUT", `${base}/blobs/${digest}?size=${data.length}&offset=${offset}`, { raw: data.subarray(offset, offset + 256 * 1024) });
+      offset += 256 * 1024;
+    } while (offset < data.length && !result.complete);
+    if (!result.complete || result.id !== digest) throw new CliError("The upload was not confirmed. Retry the same file to resume.", undefined, undefined, "transfer_unconfirmed");
+  } else if (command === "get") {
+    const [digest, file, ...flags] = rest; parsed(flags, []);
+    if (!/^[a-f0-9]{64}$/.test(digest ?? "") || !file) throw new CliError("Supply the blob SHA-256 and destination file.");
+    const chunks = []; let cursor = 0, size;
+    for (;;) {
+      const chunk = await request("GET", `${base}/blobs/${digest}?cursor=${cursor}`);
+      const data = Buffer.from(chunk.data_base64 ?? "", "base64");
+      size ??= chunk.size;
+      if (chunk.id !== digest || !Number.isSafeInteger(size) || size < 0 || size > 8 * 1024 * 1024 || chunk.size !== size || chunk.cursor !== cursor || chunk.next_cursor !== cursor + data.length || chunk.next_cursor > size || (!data.length && !chunk.eof)) throw new CliError("Invalid file transfer response.", undefined, undefined, "transfer_unconfirmed");
+      chunks.push(data); cursor = chunk.next_cursor;
+      if (chunk.eof) break;
+    }
+    const data = Buffer.concat(chunks);
+    if (data.length !== size || createHash("sha256").update(data).digest("hex") !== digest) throw new CliError("Download checksum mismatch. No destination file was written.", undefined, undefined, "checksum_mismatch");
+    const destination = resolve(file), temporary = join(dirname(destination), `.nomac-download-${randomBytes(12).toString("hex")}`);
+    writeFileSync(temporary, data, { flag: "wx", mode: 0o600 });
+    try { linkSync(temporary, destination); } finally { unlinkSync(temporary); }
+    result = { id: digest, size: data.length, file: destination, complete: true };
+  } else throw new CliError(`Unknown transport command: ${command}`);
+  print(JSON.stringify(result));
+  return result;
+}

package/src/upload.mjs

@@ -9,7 +9,7 @@ export async function uploadSourceSnapshot(projectId, tarball) {
   } catch (error) {
     // Older servers have no grant route. Outages and authorization failures
     // should remain actionable, not silently retry through another transport.
-    if (!(error instanceof CliError) || error.status !== 404 || error.code) throw error;
+    if (!(error instanceof CliError) || error.status !== 404 || (error.code && error.code !== "bad_response")) throw error;
     if (tarball.length > 4 * 1024 * 1024) {
       throw new CliError("direct uploads unavailable", "This server does not support direct source uploads. Update the server or reduce the compressed archive to 4 MiB.");
     }