@nomac/cli 0.5.7 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomac/cli",
-  "version": "0.5.7",
+  "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

@@ -3,8 +3,7 @@ name: nomac
 description: >
   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.
+  stop.
 ---
 
 # nomac — a Mac for your agent
@@ -25,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`.
 
@@ -40,155 +45,17 @@ 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.
+when needed. Agents have no GUI control: drive the Simulator with simctl, and
+give the human `open_mac_desktop` when a screen needs a person. 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
+## Builder (existing subscribers only)
 
-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 —
-via MCP tools (preferred) or the `nomac` CLI.
-
-## Setup check
-
-1. MCP tools available (`connect_status`, `push_project`, `build`, …)? Use them.
-2. Otherwise: `npx @nomac/cli whoami`. If not logged in, run
-   `npx @nomac/cli login`; give the human the device URL and code to approve.
-   Then `claude mcp add nomac -- npx @nomac/cli mcp`.
-3. `connect_status` must show a healthy Apple connection. If not, the human
-   connects at the dashboard (60 seconds, one .p8 upload). Don't guess —
-   verify, then proceed.
-
-## Ship to TestFlight
-
-```
-push_project                    # after every code change
-build workflow=release         # ~3 min; smoke = fast compile-only check
-status                         # poll ~30s until ready | failed
-```
-
-- `ready` → tell the human: "open TestFlight on your phone." Their taps are
-  the test run; read `get_feedback` for crashes/comments afterwards.
-- `failed` → `get_failure`: kind=project means you fix source and re-push;
-  kind=account means relay the link to the human. Don't burn release builds
-  debugging compile errors — use `build workflow=smoke`.
-
-## Submit for App Store review
-
-1. `review_lint` → fix every red. Apply returned patches (e.g. generated
-   `PrivacyInfo.xcprivacy`) directly to the source. Yellow "signals"
-   (4.3 distinctiveness, thin listing) are yours to judge and improve.
-2. `set_metadata` — you write the copy; check `get_metadata_schema` for
-   limits. Age rating + data usage answers are legal attestations: ask the
-   human, relay their answers. `upload_screenshots` needs exact dimensions
-   (in the schema). It runs in the background: poll `get_screenshot_upload`
-   until complete before publishing. A rolled-back or paused replacement
-   needs the returned recovery instructions before starting another upload.
-3. `publish` without confirm stages real Apple drafts/build attachments but
-   does not submit. Fix the returned blockers; retain the exact build/submission IDs.
-4. `publish confirm=true` sends the app to Apple. Ensure the human authorized
-   this app/version; honor authorization already given. New versions use manual
-   release, while existing versions retain their Apple release policy.
-
-If metadata or publish returns pending, keep its `request_key` and repeat
-the original arguments with that key. `get_store_operation` recovers the key
-and progress after a lost response. A new key starts a separate operation;
-do not use one to bypass an unconfirmed Apple request. Staging and confirmation
-remain separate invocations. For screenshots, keep the original `request_key`
-too, and use `get_screenshot_upload` to find or poll the existing operation.
-
-## Fix review rejections and release
-
-- `get_review` lists live Apple submissions, including ones created outside
-  nomac. Pass `asc_submission_id` for all item states and exact version/build IDs.
-- Apple does not expose App Review messages through its public API. Use the
-  returned App Store Connect handoff to have the human provide the actual text.
-  Never invent a rejection reason from a status code or public customer review.
-- Fix metadata/screenshots on the exact `version_string`. A binary change needs
-  push/build, then `publish` with the exact `build_id` and `asc_submission_id`.
-  `resolve_rejection:true` explicitly asserts that this version's issue is fixed.
-- `prepare_review_reply` prepares your authored text but always returns `sent:false`.
-  The human sends it and any message attachments in App Store Connect. Changing
-  review_contact.notes is not a reply; sending a reply is not resubmission.
-- `update_review` supports `resolve_item`, `remove_item`, `cancel`, `resubmit`,
-  and `release`. Preview without confirm; confirm the exact requested action.
-  Fix issues before marking items resolved. Every rejected item must be resolved
-  or removed before resubmitting. Removed items cannot be added back to that submission.
-- Poll `get_review`; approval and release are separate. Release requires an
-  app-version item in Pending Developer Release. Edit subscription/IAP products,
-  events and custom pages through the store catalog below. Apple/account/legal
-  decisions still require the relevant Apple workflow.
-
-## External TestFlight
-
-`ready` from a nomac build means internal TestFlight readiness. External testing
-requires its own review and distribution:
-
-1. `get_testflight` lists groups, test information and recent Apple builds. Use
-   `asc_build_id` for a specific build's beta-review/external state, or `group_id`
-   to list testers. Never infer external approval from internal readiness.
-2. `manage_testflight action=metadata` sets app_info (description/feedbackEmail/URLs),
-   review_contact (Apple contact/demo fields), locale, and build whats_new.
-3. Select/create an external group. `invite_tester`/`remove_tester` use an explicit
-   email/tester ID and group_id. `update_group` can enable an optional public link.
-4. `distribute` requires asc_build_id and explicit group_ids. It submits beta
-   review if needed, then assigns those groups. auto_notify defaults false;
-   `notify` starts testing after approval. `remove_build` affects one group;
-   `expire` stops testing for the build across all groups.
-5. All actions preview without confirm and apply with confirm:true. Pending
-   requests use their original key/body; get_store_operation recovers them.
-6. Relay an accurate human-provided uses_non_exempt_encryption with action=encryption
-   when appropriate. Never guess. Encryption declarations/documents use the
-   store catalog; rejected beta messages require App Store Connect. Fix the cause
-   before resubmitting a rejected binary.
-
-## Pricing, products, customer reviews and the wider store API
-
-1. `get_store_capabilities` lists operations by category/search with next_offset.
-   Pass `operation` to get that operation's exact Apple request/query schema.
-   Categories: listing, releases, pricing, purchases, subscriptions, reviews,
-   marketing, assets, testflight, analytics, compliance, webhooks.
-2. `read_store` executes listed GET operations. Begin with an `apps_*` relationship
-   and `scope:[]` for the linked app. Every child has a reusable `scope`; copy it
-   into the next read/write. Keep the query when following `next_cursor`.
-3. `update_store` takes the operation, scope and exact JSON:API `body`. For creation,
-   scope the parent. Every existing relationship ID needs its own verified scope
-   in `references`; the target and its ancestors are already verified. Territories
-   and categories are global. Inline creates use local IDs such as `${price1}`.
-4. Preview without confirm. `confirm:true` applies real paid prices, availability,
-   products/offers, public responses, release settings or event subscriptions.
-   Honor the human's existing authorization; do not ask again for authorized work.
-   Do not invent prices, legal answers or factual claims in public replies.
-5. `customerReviewResponses_createInstance` replies to a public customer review.
-   It does not send a message to Apple reviewers. Read their actual messages in
-   App Store Connect; `prepare_review_reply` only drafts the response.
-6. Product management covers subscriptions/IAP versions, localization, prices,
-   availability, grace periods and offers. First IAP approval may require the
-   app version submission. Draft review submission items can attach products;
-   use `publish` / `update_review` to submit, resolve, resubmit and release.
-7. Events, custom pages, experiments, accessibility and phased releases use their
-   catalog operations. Apple still validates account permissions and valid states.
-   Analytics report segments supply download URLs; offer-code CSV exports return
-   bounded base64 downloads. Webhooks send app events to an owner-selected receiver;
-   that receiver is responsible for running an agent when events arrive.
-
-`upload_store_asset` handles new Apple file resources: previews, screenshot files,
-purchase images, supplemental review attachments and encryption documents. Choose
-the asset create operation, provide its parent relationship/body, and pass a local
-`file_path` (CLI, up to 500 MiB) or `data_base64` (hosted, up to 2 MiB). Apple also
-has asset-specific limits. The tool reserves, uploads each requested byte range,
-then commits its checksum. Keep the same request_key and original bytes to resume.
-`uploaded:true` is not processing success: poll `read_store` until
-`assetDeliveryState.state` is `COMPLETE`. FAILED requires addressing Apple's errors.
-This adds a new file; use `upload_screenshots` for managed screenshot replacement.
-
-Keep pending write keys and unchanged bodies. `get_store_operation` exposes captured
-targets and receipts. Unknown Apple outcomes remain pending and block other writes
-to the app until reconciled; never use a fresh key to bypass one. Corrected inputs
-or a new intentional action require a fresh key. Correspondence, appeals, App Privacy
-questionnaire answers and account-wide financial/admin APIs are not exposed.
-This catalog does not run simulators or Xcode Cloud jobs.
+The separate iOS Builder publishing product is closed to new subscriptions.
+If `get_billing_status` shows a Builder plan, its tools are listed and
+https://nomac.app/llms.txt describes them. Otherwise use the cloud Mac above.
 
 ## When stuck
 

package/src/cli.mjs

@@ -4,42 +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
 
-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
-  nomac build [--smoke]        start a release (or smoke) build
-  nomac build --testflight     release build; waits until TestFlight-ready
-  nomac status [build-id]      show latest (or given) build status
-  nomac logs <build-id>        show build logs
-  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) {
@@ -61,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":
@@ -78,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];
@@ -99,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": {
@@ -108,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/mcp.mjs

@@ -40,11 +40,6 @@ export const TOOLS = [
     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: "get_refund_status", description: "Read the progress of a refund the account owner requested at nomac.app/usage. Agents cannot request refunds; point the human to that page. Does not submit a refund or cancel anything.",
     inputSchema: { type: "object", properties: { request_id: { type: "string" } }, required: ["request_id"], additionalProperties: false },
@@ -383,6 +378,20 @@ export const TOOLS = [
   },
 ];
 
+/** Shown to everyone: the Mac tools and support. The rest serve Builder subscribers. */
+const PUBLIC_TOOLS = new Set([...MAC_TOOLS.map(t => t.name), "report_issue"]);
+let subscriber;
+
+/**
+ * The Builder (publishing) plans are closed to new subscriptions, so their tools
+ * are listed only for accounts that still have one. Hidden tools still answer
+ * when called, so existing subscribers' agents keep working.
+ */
+export async function listedTools(isSubscriber = () => (subscriber ??= api("GET", "/api/v1/billing/status").then(s => Boolean(s?.tier) && s.tier !== "none", () => false))) {
+  const legacy = await isSubscriber();
+  return TOOLS.filter(t => legacy || PUBLIC_TOOLS.has(t.name));
+}
+
 export async function runMcpServer() {
   const rl = createInterface({ input: process.stdin, terminal: false });
   const send = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
@@ -417,7 +426,7 @@ export async function runMcpServer() {
           break;
         case "tools/list":
           reply({
-            tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+            tools: (await listedTools()).map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
           });
           break;
         case "tools/call": {

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"] : []),