@nomac/cli 0.5.8 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomac/cli",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "description": "Cloud Mac sessions over SSH and HTTPS, plus iOS builds and publishing — built for agents.",
   "license": "UNLICENSED",
   "type": "module",

package/skill/SKILL.md

@@ -24,9 +24,15 @@ commands and tools. Mac time is prepaid credit, separate from Builder.
    the printed device URL and code. MCP: `claude mcp add nomac -- npx @nomac/cli mcp`.
    Hosted MCP: https://mcp.nomac.app/mcp with `Authorization: Bearer <nmk_key>`.
 3. `nomac start --json`, wait until ready, `nomac sync .`, then `nomac ssh`.
-   For managed commands: `nomac exec --request-key stable-key-0001 -- COMMAND`,
-   then `nomac job JOB_ID` and `nomac output JOB_ID`. MCP equivalents are
-   `start_mac`, `exec_mac`, `get_mac_job`, `read_mac_output`, `stop_mac`.
+   Run commands with `nomac exec -- COMMAND`: it prints the output and exits
+   with the command's code, waiting at most 30 s. For builds and tests use
+   `nomac exec --wait 600 -- COMMAND`. Exit code 75 means still running: wait
+   with `nomac job JOB_ID --wait 600`, never rerun. In scripts add
+   `--request-key stable-key-0001`. Over ten minutes, use `nomac ssh -- COMMAND`. MCP equivalents are `start_mac`, `exec_mac` (also waits),
+   `write_mac_file`, `read_mac_file`, `fetch_to_mac`, `stop_mac`. For a file
+   up to 2 GiB from the human, or to hand them a build, use
+   `create_mac_upload_link` and `create_mac_download_link`: each returns a url
+   they open in a browser.
 4. Download work with `nomac pull ./build` (use `--from PATH` for another
    remote directory), then `nomac stop --json`. Confirm `cleanup_confirmed`.
 

package/src/cli.mjs

@@ -4,37 +4,28 @@ import { loadProjectState, saveApiKey, saveProjectState } from "./config.mjs";
 import { packTarball } from "./pack.mjs";
 import { uploadSourceSnapshot } from "./upload.mjs";
 
-const HELP = `nomac — Mac workspaces for agents / iOS app publishing
+const HELP = `nomac: a cloud Mac for you and your agents ($0.80 an hour, by the minute)
 
-Nomac 2.0 cloud Macs:
-  nomac credits               Mac credit left ($0.80/hour, by the minute)
-  nomac credits buy --packs N  payment link for $10 packs, opened in the browser
-  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 desktop                the Mac's full desktop in your browser
-  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
+Start:
+  nomac login                  connect this device (approve in the browser)
+  nomac credits                credit left; nomac credits buy --packs N adds more
+  nomac start                  start a Mac, or reconnect to yours
+  nomac stop                   stop the Mac: deletes it and its files, billing ends
 
-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
+Use it:
+  nomac exec -- ls             run a command; prints its output, keeps its exit code
+  nomac exec --wait 600 -- xcodebuild test
+                               wait up to 10 minutes (the default is 30 seconds)
+  nomac ssh                    open a shell (nomac ssh -- command runs one)
+  nomac sync .                 upload changed project files
+  nomac pull ./build           download a folder from the Mac
+  nomac desktop                the Mac's desktop in your browser
+  nomac status                 state, cost so far and when it stops
 
-Account and agents:
-  nomac login                  connect this device (approve in the browser)
-  nomac login <api-key>        store an nmk_ key directly (CI / power users)
-  nomac mcp                    run the stdio MCP server (for agents)
-  nomac whoami                 show org + usage
+Agents:
+  nomac mcp                    MCP server for Claude Code, Codex, Cursor and others
 
+More: nomac start --help, nomac whoami, nomac start --host user@mac (a Mac you own)
 Environment: NOMAC_API_KEY, NOMAC_API_URL`;
 
 export async function main(argv) {
@@ -56,6 +47,10 @@ export async function main(argv) {
       const { transportCommand } = await import("./transport-command.mjs");
       return transportCommand(rest);
     }
+    case "status":
+      // A legacy build ID, or a folder that only ever built with the old pipeline, keeps build status.
+      if (/^bld_/.test(rest[0] ?? "") || (loadProjectState().last_build && !(await import("./session-store.mjs")).sessionStore().load())) return status(rest[0]);
+    // falls through: everyone else sees their Mac
     case "start":
     case "exec":
     case "job":
@@ -73,7 +68,8 @@ export async function main(argv) {
         return hostedSessionCommand(cmd, rest, { store });
       }
       const { sessionCommand } = await import("./sessions.mjs");
-      return sessionCommand(cmd, rest);
+      // A Mac you own reports through session status.
+      return cmd === "status" ? sessionCommand("session", ["status", ...rest]) : sessionCommand(cmd, rest);
     }
     case "login": {
       const key = rest[0];
@@ -94,8 +90,6 @@ export async function main(argv) {
       return push();
     case "build":
       return build(rest);
-    case "status":
-      return status(rest[0]);
     case "logs":
       return logs(rest[0]);
     case "mcp": {
@@ -103,12 +97,11 @@ export async function main(argv) {
       return runMcpServer();
     }
     case "whoami": {
-      const me = await api("GET", "/api/v1/me");
-      const o = me.org ?? {};
+      const [me, credit] = await Promise.all([api("GET", "/api/v1/me"), api("GET", "/api/v1/mac/credits").catch(() => null)]);
+      const o = me.org ?? {}, c = credit?.credits ?? credit ?? {};
       console.log(`org:         ${o.name ?? "?"} (${o.id ?? "?"})`);
-      console.log(`plan:        ${o.tier ?? "?"}`);
-      console.log(`projects:    ${me.projects ?? 0}`);
-      console.log(`connections: ${me.connections ?? 0}`);
+      if (c.spendable_microunits !== undefined) console.log(`Mac credit:  $${(Number(c.spendable_microunits) / 1_000_000).toFixed(2)} (${Math.floor((c.spendable_seconds ?? 0) / 3600)}h ${String(Math.floor(((c.spendable_seconds ?? 0) % 3600) / 60)).padStart(2, "0")}m of Mac time)`);
+      if (o.tier && o.tier !== "none") console.log(`Builder:     ${o.tier} (${me.projects ?? 0} projects)`);
       console.log(`auth:        ${me.auth?.via ?? "?"}${me.auth?.key_id ? ` (${me.auth.key_id})` : ""}`);
       return;
     }

package/src/hosted-sessions.mjs

@@ -15,12 +15,16 @@ const HELP = `Nomac cloud Mac sessions
   nomac ssh [--forward 8080:3000]    full Mac shell and port forwarding
   nomac ssh -- command args         run any command over SSH
   nomac desktop [--no-open] [--json] the full macOS desktop in your browser
-  nomac exec --request-key KEY -- command args
-  nomac job JOB_ID                  reconcile a submitted command
+  nomac exec [--wait 30] -- command args
+                                    runs it, prints its output, exits with its code.
+                                    Waits up to 30 s; for builds and tests use --wait 600.
+                                    Exit code 75 means still running: see nomac job.
+                                    (--request-key KEY makes a scripted retry safe)
+  nomac job JOB_ID [--wait 600]     wait for a command that outlasted --wait
   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
+  nomac status [--json]             state, cost so far and when it stops
+  nomac stop [--wait 60] [--json]   stop the Mac: deletes it and its files
 
 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.
@@ -63,11 +67,88 @@ export async function sessionAccess(id, request = api) {
   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);
+/** nomac exec's exit code for a command still running when the wait ends (EX_TEMPFAIL). */
+export const STILL_RUNNING = 75;
+/** Quick commands are checked early; after that, once a second. */
+const POLL_MS = [250, 500];
+const NOTICE_MS = 5000;
+/**
+ * nomac exec waits like a local command: up to --wait seconds (default 30), then
+ * prints stdout and stderr and exits with the command's own exit code. The wait
+ * is a ceiling: a quick command returns as soon as it finishes. A command still
+ * running keeps running on the Mac; the CLI says how to wait for it and exits
+ * 75. --wait 0 only starts it.
+ */
+async function waitForCommand(id, base, started, waitSeconds, { request, transport, cache, print, stdout, stderr, exitWith, sleep, now, json }) {
+  let job = started;
+  const deadline = now() + waitSeconds * 1000;
+  const begun = now();
+  let announced = false;
+  for (let polls = 0; waitSeconds && !["exited", "unknown"].includes(job.state) && now() < deadline; polls++) {
+    // A slow command can outlive the shell waiting for it (agent shells time out); leave a way back.
+    if (!json && !announced && now() - begun >= NOTICE_MS && deadline - now() > 1000) {
+      announced = true;
+      stderr(`nomac: ${job.id} is still running; waiting up to ${waitSeconds} s. If interrupted: nomac job ${job.id} --wait 600\n`);
+    }
+    await sleep(Math.min(POLL_MS[polls] ?? 1000, Math.max(0, deadline - now())));
+    job = await hostedRequest(id, "GET", `${base}/jobs/${job.id}`, {}, { request, transport, cache });
+  }
+  if (job.state !== "exited") {
+    if (!waitSeconds) { print(JSON.stringify(job, null, 2)); return job; }
+    const unknown = job.state === "unknown";
+    const next = unknown ? `The Mac could not confirm whether ${job.id} finished. Inspect it with nomac job ${job.id}; do not rerun it.`
+      : `Still running after ${waitSeconds} s; it keeps running on the Mac. Wait for it: nomac job ${job.id} --wait 600. Next time wait up front: nomac exec --wait 600 -- command. Over 10 minutes: nomac ssh -- command. Do not rerun it.`;
+    if (json) print(JSON.stringify({ ...job, next_step: next }, null, 2));
+    else if (unknown) stderr(`nomac: ${next}\n`);
+    else stderr(`nomac: still running after ${waitSeconds} s (${job.id}); it keeps running on the Mac.\n  wait for it:            nomac job ${job.id} --wait 600\n  next time, wait longer: nomac exec --wait 600 -- command\n  over 10 minutes:        nomac ssh -- command\n`);
+    exitWith(unknown ? 1 : STILL_RUNNING);
+    return job;
+  }
+  // Each read is a round trip to the Mac: skip empty streams and read the others together.
+  const read = async stream => {
+    if (job.output_bytes?.[stream] === 0) return Buffer.alloc(0);
+    const parts = [];
+    for (let cursor = 0; ;) {
+      const part = await hostedRequest(id, "GET", `${base}/jobs/${job.id}/output?cursor=${cursor}&stream=${stream}`, {}, { request, transport, cache });
+      parts.push(Buffer.from(part.data_base64 ?? "", "base64"));
+      if (part.eof && part.tail_base64) parts.push(Buffer.from(`\n[output over 8 MiB was not kept; its last part follows]\n`), Buffer.from(part.tail_base64, "base64"));
+      if (part.eof || part.next_cursor === cursor) break;
+      cursor = part.next_cursor;
+    }
+    return Buffer.concat(parts);
+  };
+  const [out, err] = await Promise.all([read("stdout"), read("stderr")]);
+  const streams = { stdout: out, stderr: err };
+  if (json) print(JSON.stringify({ ...job, stdout: streams.stdout.toString("utf8"), stderr: streams.stderr.toString("utf8") }, null, 2));
+  else { stdout(streams.stdout); stderr(streams.stderr); }
+  exitWith(typeof job.exit_code === "number" ? job.exit_code : 1);
+  return job;
+}
+
+const usd = microunits => `$${(Number(microunits ?? 0) / 1_000_000).toFixed(2)}`;
+const clockUtc = ms => new Date(ms).toISOString().slice(11, 16) + " UTC";
+/** One readable paragraph for nomac status. */
+export function statusSummary(session) {
+  const lines = [`${session.id}: ${session.state}`];
+  if (["ready", "provisioning", "queued"].includes(session.state)) lines.push(`Cost so far: ${usd(session.cost?.accrued_microunits)} ($0.80/hour, billed by the minute while ready). Credit left: nomac credits`);
+  const a = session.activity ?? {};
+  if (session.state === "ready") {
+    const stops = [a.idle_deadline_at ? `when idle, at ${clockUtc(a.idle_deadline_at)}` : null, a.hard_deadline_at ? `at ${clockUtc(a.hard_deadline_at)} at the latest` : null].filter(Boolean);
+    if (stops.length) lines.push(`Stops by itself ${stops.join(", or ")}. Stop now: nomac stop`);
+  }
+  if (session.failure_code) lines.push(`Ended: ${session.failure_code}`);
+  return lines.join("\n");
+}
+
+/** With a cache, one access token serves a whole command until shortly before it expires. */
+export async function hostedRequest(id, method, path, params = {}, { request = api, transport = macRequest, cache } = {}) {
+  const reusable = cache?.access && Date.parse(cache.access.expires_at) - Date.now() > 30_000;
+  const access = reusable ? cache.access : await sessionAccess(id, request);
+  if (cache) cache.access = access;
   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 } = {}) {
+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,
+  stdout = data => process.stdout.write(data), stderr = data => process.stderr.write(data), exitWith = code => { process.exitCode = code; } } = {}) {
   let parsed;
   try { parsed = parseArgs({ args: argv, options, allowPositionals: true }); }
   catch (error) { throw new CliError(error.message); }
@@ -105,15 +186,28 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
     return local;
   };
   if (command === "session") {
-    if (positionals.length !== 1 || !["status", "info"].includes(positionals[0])) throw new CliError("Usage: nomac session status --json");
+    if (positionals.length !== 1 || !["status", "info"].includes(positionals[0])) throw new CliError("Usage: nomac status [--json]");
     const local = localSession(); return output({ session: await refresh(local) });
   }
+  if (command === "status") {
+    if (positionals.length) throw new CliError("Usage: nomac status [--json]");
+    const loaded = store.load();
+    if (!loaded) { print(values.json ? JSON.stringify({ session: null }) : "No Mac in this folder. Start one: nomac start"); return null; }
+    const session = await refresh(localSession());
+    if (values.json) { print(JSON.stringify({ session }, null, 2)); return session; }
+    print(statusSummary(session));
+    return session;
+  }
   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, 300, 1, 600) } };
+      if (!positionals.length || !argv.includes("--")) throw new CliError("Use nomac exec -- command args");
+      if (values["request-key"] !== undefined && !/^[A-Za-z0-9_.:-]{8,128}$/.test(values["request-key"])) throw new CliError("A request key is 8 to 128 letters, digits, underscores, periods, colons or hyphens.");
+      // A person running a command once needs no key; scripts pass one so a lost response can be retried safely.
+      // A long wait implies a long command, so the command's own limit follows it unless set.
+      const waitFor = integer(values.wait, 30, 0, 600);
+      method = "POST"; path = `${base}/jobs`; params = { requestKey: values["request-key"] ?? `cli-${randomUUID()}`, body: { argv: positionals, timeout_seconds: integer(values.timeout, Math.max(300, waitFor), 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]}`;
@@ -123,7 +217,10 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
         path += `/output?cursor=${cursor}&stream=${stream}`;
       }
     }
-    return output(await hostedRequest(local.id, method, path, params, { request, transport }));
+    const cache = {}, result = await hostedRequest(local.id, method, path, params, { request, transport, cache });
+    const waiting = command === "exec" || (command === "job" && values.wait !== undefined);
+    if (!waiting) return output(result);
+    return waitForCommand(local.id, base, result, integer(values.wait, 30, 0, 600), { request, transport, cache, print, stdout, stderr, exitWith, sleep, now, json: Boolean(values.json) });
   }
   if (command === "desktop") {
     if (positionals.length) throw new CliError("Usage: nomac desktop [--no-open] [--json]");

package/src/mac-fetch.mjs

@@ -0,0 +1,28 @@
+/**
+ * fetch_to_mac runs this fixed script as an ordinary job. The URL and paths
+ * arrive as environment variables, so nothing a caller sends is parsed as shell.
+ * Keep identical to apps/web/lib/mac-fetch.ts (a web test compares them).
+ */
+export const FETCH_SCRIPT = [
+  "set -euo pipefail",
+  'dest="$NOMAC_PATH"',
+  'case "$dest" in "~") dest="$HOME" ;; "~/"*) dest="$HOME/${dest:2}" ;; esac',
+  'tmp="$(mktemp "${TMPDIR:-/tmp}/nomac-fetch.XXXXXX")"',
+  "trap 'rm -f \"$tmp\"' EXIT",
+  'curl -fsSL --retry 3 --retry-all-errors --max-time 590 -o "$tmp" -- "$NOMAC_URL"',
+  'case "${NOMAC_EXTRACT:-}" in',
+  '  zip) mkdir -p "$dest"; ditto -x -k "$tmp" "$dest" ;;',
+  '  tar) mkdir -p "$dest"; tar -xf "$tmp" -C "$dest" ;;',
+  '  *) mkdir -p "$(dirname "$dest")"; chmod "${NOMAC_MODE:-644}" "$tmp"; mv "$tmp" "$dest"; trap - EXIT ;;',
+  "esac",
+  'if [ -d "$dest" ]; then echo "unpacked into $dest: $(find "$dest" -type f | wc -l | tr -d " ") files"; else echo "saved $dest: $(stat -f %z "$dest") bytes"; fi',
+].join("\n");
+
+/** Image types an agent can look at, recognized by their first bytes. */
+export function imageType(bytes) {
+  if (bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return "image/png";
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+  if (bytes.subarray(0, 4).toString("latin1") === "GIF8") return "image/gif";
+  if (bytes.subarray(0, 4).toString("latin1") === "RIFF" && bytes.subarray(8, 12).toString("latin1") === "WEBP") return "image/webp";
+  return undefined;
+}

package/src/mac-links.mjs

@@ -0,0 +1,51 @@
+import { createWriteStream, mkdirSync, openAsBlob, renameSync, rmSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { api, CliError } from "./api.mjs";
+
+/**
+ * Upload and download links move files of up to 2 GiB through storage, so a
+ * file from this machine goes to the Mac (or back) without passing through the
+ * agent or the API's request size limit.
+ */
+export const MAX_LINK_BYTES = 2 * 1024 ** 3;
+/** The secret part of a link's url, or a bare token. */
+export const linkToken = link => /(?:^|\/)([A-Za-z0-9_-]{32})(?:\/file)?\/?(?:[?#].*)?$/.exec(String(link).trim())?.[1];
+const sessionBase = id => `/api/v1/mac/sessions/${encodeURIComponent(id)}`;
+
+export function createLink(sessionId, body) {
+  return api("POST", `${sessionBase(sessionId)}/links`, { body });
+}
+
+export function checkLink(link, wait = 20) {
+  const token = linkToken(link);
+  if (!token) throw new CliError("invalid link", "Pass the link's url as returned when it was made.", 400, "invalid_request", { code: "invalid_request" });
+  return api("GET", `/api/v1/mac/links/${token}?wait=${wait}`);
+}
+
+/** Sends a local file to the Mac: straight to storage, then the Mac fetches it. */
+export async function uploadThroughLink(sessionId, localPath, { path, executable = false, extract, wait = 50, fetchImpl = fetch } = {}) {
+  const file = resolve(localPath), size = statSync(file).size;
+  if (size > MAX_LINK_BYTES) throw new CliError("file too large", `${localPath} is over 2 GiB, the most a link takes. Split it, or have the Mac download it with fetch_to_mac.`, 413, "file_too_large", { code: "file_too_large" });
+  const link = await createLink(sessionId, { direction: "upload", path, executable, ...(extract ? { extract } : {}) });
+  const sent = await fetchImpl(link.upload_url, { method: "PUT", body: await openAsBlob(file) }).catch(() => null);
+  if (!sent?.ok) throw new CliError("upload failed", `The upload did not go through${sent ? ` (HTTP ${sent.status})` : ""}. Try again.`, sent?.status, "upload_failed", { code: "upload_failed", url: link.url });
+  return checkLink(link.url, wait);
+}
+
+/** Saves a ready download link's file on this machine, replacing the target only once the download is whole. */
+export async function saveFromLink(view, saveTo, { fetchImpl = fetch } = {}) {
+  const target = resolve(saveTo), partial = `${target}.nomac-part`;
+  const response = await fetchImpl(view.download_url, { redirect: "follow" }).catch(() => null);
+  if (!response?.ok || !response.body) throw new CliError("download failed", `The download did not go through${response ? ` (HTTP ${response.status})` : ""}. Try again with get_mac_file_link.`, response?.status, "download_failed", { code: "download_failed" });
+  mkdirSync(dirname(target), { recursive: true });
+  try {
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(partial));
+    renameSync(partial, target);
+  } catch (error) {
+    rmSync(partial, { force: true });
+    throw error;
+  }
+  return { saved_to: target, saved_bytes: statSync(target).size };
+}

package/src/mac-tools.mjs

@@ -1,6 +1,11 @@
 import { api } from "./api.mjs";
 import { openUrl } from "./mac-credits.mjs";
 import { desktopUrl } from "./desktop.mjs";
+import { readFileSync, statSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { FETCH_SCRIPT, imageType } from "./mac-fetch.mjs";
+import { checkLink, createLink, saveFromLink, uploadThroughLink } from "./mac-links.mjs";
+const MAX_WRITE_BYTES = 3 * 1024 * 1024;
 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}$" };
@@ -24,7 +29,46 @@ export const MAC_TOOLS = [
     return text({ session_id, url, opened_in_browser: opened, message: opened ? "The desktop opened in the human's browser; they may need to sign in to nomac.app." : "Give the human this link; it opens after they sign in to nomac.app." });
   } },
   { 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. timeout_seconds defaults to 300 and caps at 600; raise it for slow work such as a first simulator boot, which needs about 90 seconds. A command (argv plus env) can be at most 64 KiB; to put larger files on the Mac, fetch them there (git clone, curl) or write them in parts of up to about 40 KiB (e.g. base64 -d >> file).", 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: "exec_mac", description: "Run any argv command in your cloud Mac workspace. Waits up to wait_seconds (default 20, max 50): a command that finishes in time returns its exit_code, stdout and stderr (first 64 KiB each, as text) in this one call, as soon as it finishes. For builds, tests and other slow commands pass wait_seconds: 50. A longer one returns its job ID: poll get_mac_job, then read_mac_output. Reuse request_key and identical arguments after lost responses; never rerun to get output. Use bash -lc explicitly for shell syntax. timeout_seconds defaults to 300 and caps at 600; raise it for slow work such as a first simulator boot (about 90 seconds). A command (argv plus env) can be at most 64 KiB: put files on the Mac with write_mac_file (local_path, up to 2 GiB) or fetch_to_mac.", inputSchema: schema({ session_id: session, request_key: key, argv: { type: "array", items: { type: "string" }, minItems: 1 }, timeout_seconds: { type: "integer", minimum: 1, maximum: 600 }, wait_seconds: { type: "integer", minimum: 0, maximum: 50 } }, ["session_id", "request_key", "argv"]), handler: async ({ session_id, request_key, wait_seconds, ...body }) => text(await api("POST", `${base({ session_id })}/jobs?wait=${wait_seconds ?? 20}`, { body, idempotencyKey: request_key })) },
+  { name: "write_mac_file", description: "Write a file on the Mac: local_path uploads a file from this machine, up to 2 GiB, without its content passing through you; or give content as text, or content_base64 for binary, up to 3 MiB. Relative Mac paths are in the session workspace; ~ is the home folder. Creates missing folders and replaces an existing file in one step; set executable for scripts. Safe to repeat. For a whole project use nomac sync; for larger files fetch_to_mac.", inputSchema: schema({ session_id: session, path: { type: "string", minLength: 1, maxLength: 1024 }, local_path: { type: "string" }, content: { type: "string" }, content_base64: { type: "string" }, executable: { type: "boolean" } }, ["session_id", "path"]), handler: async ({ session_id, path, local_path, content, content_base64, executable }) => {
+    const given = [local_path, content, content_base64].filter(v => v !== undefined).length;
+    if (given !== 1) return text({ error: { code: "invalid_request", message: "Give exactly one of local_path, content or content_base64." } });
+    if (local_path !== undefined) {
+      const file = resolve(local_path), size = statSync(file).size;
+      // Larger files go through an upload link: straight to storage, then onto the Mac.
+      if (size > MAX_WRITE_BYTES) return text(await uploadThroughLink(session_id, file, { path, executable: Boolean(executable) }));
+      content_base64 = readFileSync(file).toString("base64");
+    }
+    return text(await api("POST", `${base({ session_id })}/files`, { body: { path, ...(content !== undefined ? { content } : { content_base64 }), executable: Boolean(executable) } }));
+  } },
+  { name: "read_mac_file", description: "Read a file on the Mac, up to max_bytes (default 1 MiB, max 4 MiB). save_to writes it to this machine instead of returning it. Otherwise text comes back as text, binary as base64, and PNG, JPEG, GIF and WebP files as an image you can see: for example a Simulator screenshot from `xcrun simctl io booted screenshot shot.png`. Relative Mac paths are in the session workspace. Read-only on the Mac.", inputSchema: schema({ session_id: session, path: { type: "string", minLength: 1, maxLength: 1024 }, max_bytes: { type: "integer", minimum: 1, maximum: 4194304 }, save_to: { type: "string" } }, ["session_id", "path"]), handler: async ({ session_id, path, max_bytes, save_to }) => {
+    const file = await api("GET", `${base({ session_id })}/files?${new URLSearchParams({ path, ...(max_bytes ? { max_bytes: String(max_bytes) } : {}) })}`);
+    const bytes = file.encoding === "utf8" ? Buffer.from(file.content ?? "", "utf8") : Buffer.from(file.content_base64 ?? "", "base64");
+    const meta = Object.fromEntries(Object.entries(file).filter(([k]) => !["content", "content_base64"].includes(k)));
+    if (save_to) {
+      const target = resolve(save_to); mkdirSync(dirname(target), { recursive: true }); writeFileSync(target, bytes);
+      return text({ ...meta, saved_to: target, saved_bytes: bytes.length });
+    }
+    const mimeType = !file.truncated && file.encoding === "base64" ? imageType(bytes) : undefined;
+    if (!mimeType) return text(file);
+    return { content: [{ type: "image", data: file.content_base64, mimeType }, { type: "text", text: JSON.stringify({ ...meta, mime_type: mimeType }, null, 2) }] };
+  } },
+  { name: "fetch_to_mac", description: "Download a URL straight onto the Mac: any size, as fast as the Mac's connection. path is the file to create, or with extract (zip or tar, including .tar.gz) the folder to unpack into. Relative paths are in the session workspace. Waits up to wait_seconds (default 30, max 50) like exec_mac; a longer download keeps running as a job. For a git repository, run git clone with exec_mac instead.", inputSchema: schema({ session_id: session, request_key: key, url: { type: "string", pattern: "^https?://", maxLength: 4096 }, path: { type: "string", minLength: 1, maxLength: 1024 }, extract: { type: "string", enum: ["zip", "tar"] }, wait_seconds: { type: "integer", minimum: 0, maximum: 50 } }, ["session_id", "request_key", "url", "path"]), handler: async ({ session_id, request_key, url, path, extract, wait_seconds }) => text(await api("POST", `${base({ session_id })}/jobs?wait=${wait_seconds ?? 30}`, { body: { argv: ["/bin/bash", "-c", FETCH_SCRIPT], env: { NOMAC_URL: url, NOMAC_PATH: path, NOMAC_EXTRACT: extract ?? "" }, timeout_seconds: 600 }, idempotencyKey: request_key })) },
+  { name: "create_mac_upload_link", description: "Get a link that puts one file of up to 2 GiB on the Mac at path. With local_path, the file is uploaded from this machine now and placed on the Mac. Otherwise give url to the human (open: true opens it in this machine's browser): they choose a file in the browser and it lands on the Mac, no account needed. Then call get_mac_file_link until state is placed. With extract (zip or tar), path is the folder to unpack into. The link takes one file and expires after expires_in_minutes (default 60, max 1440).", inputSchema: schema({ session_id: session, path: { type: "string", minLength: 1, maxLength: 1024 }, local_path: { type: "string" }, executable: { type: "boolean" }, extract: { type: "string", enum: ["zip", "tar"] }, expires_in_minutes: { type: "integer", minimum: 1, maximum: 1440 }, open: { type: "boolean", default: false, description: "Open the link in this machine's browser for the human." } }, ["session_id", "path"]), handler: async ({ session_id, path, local_path, executable, extract, expires_in_minutes, open }) => {
+    if (local_path !== undefined) return text(await uploadThroughLink(session_id, local_path, { path, executable: Boolean(executable), extract }));
+    const link = await createLink(session_id, { direction: "upload", path, executable: Boolean(executable), ...(extract ? { extract } : {}), ...(expires_in_minutes ? { expires_in_minutes } : {}) });
+    return text({ ...link, opened_in_browser: open ? openUrl(link.url) : false });
+  } },
+  { name: "create_mac_download_link", description: "Make a download link for a file or folder on the Mac, up to 2 GiB (a folder downloads as a zip). With save_to, the file is downloaded to this machine as soon as it is ready. Otherwise give url to the human. The link keeps working after the Mac stops, until it expires (expires_in_minutes, default 60, max 1440). Waits up to wait_seconds (default 30) for the copy from the Mac; if still copying, call get_mac_file_link.", inputSchema: schema({ session_id: session, path: { type: "string", minLength: 1, maxLength: 1024 }, save_to: { type: "string" }, expires_in_minutes: { type: "integer", minimum: 1, maximum: 1440 }, wait_seconds: { type: "integer", minimum: 0, maximum: 50 } }, ["session_id", "path"]), handler: async ({ session_id, path, save_to, expires_in_minutes, wait_seconds }) => {
+    let link = await createLink(session_id, { direction: "download", path, wait_seconds: wait_seconds ?? 30, ...(expires_in_minutes ? { expires_in_minutes } : {}) });
+    if (!save_to) return text(link);
+    for (let checks = 0; link.state === "copying" && checks < 12; checks++) link = await checkLink(link.url, 50);
+    return text(link.state === "ready" ? { ...link, ...await saveFromLink(link, save_to) } : link);
+  } },
+  { name: "get_mac_file_link", description: "Check an upload or download link by its url: waiting_for_upload, placing, placed, copying, ready, failed or expired. An upload that has finished is moved onto the Mac by this call, which waits up to wait_seconds (default 20, max 50) for the move. save_to downloads a ready download link's file to this machine. Safe to repeat.", inputSchema: schema({ link: { type: "string", minLength: 32, maxLength: 2048 }, wait_seconds: { type: "integer", minimum: 0, maximum: 50 }, save_to: { type: "string" } }, ["link"]), handler: async ({ link, wait_seconds, save_to }) => {
+    const view = await checkLink(link, wait_seconds ?? 20);
+    return text(save_to && view.state === "ready" ? { ...view, ...await saveFromLink(view, save_to) } : view);
+  } },
   { 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 stdout/stderr as base64 chunks; resume from next_cursor. If truncated, the final response includes tail_base64 and its absolute tail_offset. Retrieve promptly: only recent completed jobs retain output. output_expired preserves the job receipt and never means rerun. 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/session-ssh.mjs

@@ -1,5 +1,8 @@
 import { spawn } from "node:child_process";
-import { isAbsolute } from "node:path";
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CliError } from "./api.mjs";
 
@@ -20,6 +23,23 @@ export function validateWorkspace(path) {
   return path;
 }
 
+/**
+ * A hosted session reuses one SSH connection for 2 minutes on macOS and Linux,
+ * so repeated commands skip the tunnel and handshake. The socket is private to
+ * this user and named for the session and generation, never shared between
+ * Macs. Windows OpenSSH cannot multiplex; other SSH targets keep their own setup.
+ */
+export function multiplexArgs(session, { platform = process.platform, home = homedir() } = {}) {
+  const off = ["-o", "ControlMaster=no", "-o", "ControlPath=none"];
+  if (session.mode !== "hosted" || platform === "win32") return off;
+  const dir = join(home, ".nomac", "cm");
+  const name = createHash("sha256").update(`${session.id}:${session.generation ?? 0}`).digest("hex").slice(0, 20);
+  const path = join(dir, name);
+  if (path.length > 100) return off; // Unix socket paths are limited to about 104 bytes
+  try { mkdirSync(dir, { recursive: true, mode: 0o700 }); chmodSync(dir, 0o700); } catch { return off; }
+  return ["-o", "ControlMaster=auto", "-o", `ControlPath=${path}`, "-o", "ControlPersist=120"];
+}
+
 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");
@@ -32,8 +52,7 @@ export function sshArgs(session, { batch = true } = {}) {
       "-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",
+    ...multiplexArgs(session),
     ...(batch ? ["-o", "BatchMode=yes", "-o", "ClearAllForwardings=yes"] : []),
     ...(session.port ? ["-p", String(session.port)] : []),
     ...(session.identity ? ["-i", session.identity, "-o", "IdentitiesOnly=yes"] : []),