@nomac/cli 0.2.5 → 0.3.0

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",
+  "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/skill/SKILL.md

@@ -1,15 +1,44 @@
 ---
 name: nomac
 description: >
-  Ship iOS apps to TestFlight and the App Store without a Mac. Use when the
-  user asks to build, test on a phone, publish, or submit an iOS app for
-  review — or mentions TestFlight, App Store Connect, signing, provisioning,
-  screenshots/metadata for the App Store, or app review rejections. Works from
-  any directory containing an Xcode project (SwiftUI vibe-code exports
-  included).
+  Use a full cloud Mac over SSH, HTTPS or MCP for macOS tools, Xcode and iOS
+  development. Start sessions, sync files, run commands, retrieve work and
+  stop. Also supports the separate iOS Builder product for TestFlight and
+  App Store publishing, signing, screenshots, metadata and review replies.
 ---
 
-# nomac — ship iOS without a Mac
+# nomac — a Mac for your agent
+
+NoMac 2.0 provides a full macOS VM with administrator access. You choose the
+commands and tools. A weekly Mac subscription is separate from Builder.
+
+## Cloud Mac setup and workflow
+
+1. Sign in at https://nomac.app/mac. The human chooses $5/week for 5 hours
+   or $20/week for 25 hours. Verify with `get_mac_credits`; a checkout URL
+   is not a payment. No Apple Developer account is needed for an unsigned build.
+2. Install `npm install -g @nomac/cli`, run `nomac login`, and give the human
+   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`.
+4. Download work with `nomac pull ./build` (use `--from PATH` for another
+   remote directory), then `nomac stop --json`. Confirm `cleanup_confirmed`.
+
+Stopping deletes files and logs. Download before stopping. SSH disconnects
+do not stop the session. Ready time includes idle time; queue/setup are free.
+Unused hours expire weekly. One session at a time; no automatic overage.
+Keep the same request key and arguments after uncertain responses; inspect
+the original job before retrying. Output retrieval failure is not job failure.
+Managed jobs have a 600-second limit; SSH can run longer within session limits.
+CLI sync skips symlinks and preserves remote extra files; use native SSH/rsync
+when needed. GUI/simulator control and persistent disks are not currently offered.
+Report failures using `report_issue` with `session_id`, optional `job_id` and
+a description without secrets. Read https://nomac.app/llms.txt for full limits.
+
+## Separate Builder product
 
 nomac is the hands; you are the brain. It builds, signs, uploads, lints for
 review-readiness, writes store metadata, manages pricing/products and submits for review —

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,191 @@
+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);
+}
+const validRequestKey = value => typeof value === "string" && /^[A-Za-z0-9_.:-]{8,128}$/.test(value);
+// Only explicit pre-allocation rejections permit a fresh intent. A timeout,
+// unreadable response or idempotency conflict may still own a real session.
+const startRejections = new Set(["invalid_request", "invalid_public_key", "profile_unavailable", "session_cap_too_low",
+  "weekly_time_unavailable", "weekly_time_expired", "insufficient_compute_credit", "compute_account_blocked",
+  "session_limit_reached", "organization_not_found", "compute_unavailable", "unauthenticated", "invalid_origin"]);
+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 wait = ["start", "stop"].includes(command) ? integer(values.wait, command === "start" ? 300 : 60, 0, command === "start" ? 600 : 300) : 0;
+  if (command === "start" && values["request-key"] !== undefined && !validRequestKey(values["request-key"])) throw new CliError("Use a request key of 8–128 letters, digits, underscores, periods, colons or hyphens.");
+  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"]) };
+      // Older CLIs persisted invalid keys before contacting the API. Such a key
+      // cannot pass server validation and therefore cannot have allocated a VM.
+      if (local && !local.id && !validRequestKey(local.requestKey)) { local.state = "failed"; store.save(local); }
+      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", outcomeUnknown: false, 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 previouslyUncertain = local.outcomeUnknown !== false;
+        local.outcomeUnknown = true; store.save(local); // A crash after dispatch must reconcile this intent.
+        let result;
+        try { result = await request("POST", "/api/v1/mac/sessions", { idempotencyKey: local.requestKey, body: local.request }); }
+        catch (error) {
+          if (!previouslyUncertain && startRejections.has(error.code) && Number.isInteger(error.status) && error.status >= 400 && error.status <= 503) {
+            local.state = "failed"; local.rejection = error.code; store.save(local);
+          }
+          throw error;
+        }
+        saveView(local, result.session);
+      }
+      const deadline = now() + wait * 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() + wait * 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 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/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);
+  });
+}