@nomac/cli 0.11.10 → 0.12.0

package/package.json

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

package/src/cli.mjs

@@ -19,6 +19,7 @@ Use it:
                                wait up to 10 minutes (the default is 30 seconds)
   nomac cancel JOB_ID          stop a running command and everything it started
   nomac ssh                    open a shell (nomac ssh -- command runs one)
+  nomac ssh-config             name this Mac "nomac" in your SSH config: VS Code, Cursor, Claude Code
   nomac sync .                 upload changed project files
   nomac pull ./build           download a folder from the Mac
   nomac desktop                the Mac's desktop in your browser (--app: Apple's Screen Sharing)
@@ -111,6 +112,7 @@ export async function main(argv) {
     case "cancel":
     case "sync":
     case "ssh":
+    case "ssh-config":
     case "desktop":
     case "screenshot":
     case "record":

package/src/hosted-sessions.mjs

@@ -9,6 +9,7 @@ import { describePull, describeSync, inSkippedFolder, pullProject, syncProject }
 import { macRequest, sessionId, transportOptions } from "./mac-transport.mjs";
 import { copyToClipboard, desktop, DESKTOP_HELP, screenSharing } from "./desktop.mjs";
 import { screenshot, startRecording, stopRecording } from "./mac-screen.mjs";
+import { refreshSshConfig, sshConfigBlock, writeSshConfig } from "./ssh-config.mjs";
 
 const WORKSPACE = "/Users/agent/workspace";
 
@@ -43,6 +44,14 @@ const HELP = `Nomac cloud Mac sessions
   nomac drive [reset]               the account's persistent drive at ~/drive, kept between sessions:
                                     space used and saves; reset empties it
   nomac start --drive none          this Mac without the drive
+  nomac start --parallel            a second Mac beside the account's running one, from another
+                                    folder (accounts that bought credit, while a Mac is spare);
+                                    it runs without ~/drive. Without it, start uses the running Mac.
+  nomac ssh-config [--alias nomac] [--print]
+                                    name this folder's Mac in your SSH config (Host nomac), for
+                                    VS Code or Cursor Remote-SSH, Claude Code SSH sessions, ssh nomac,
+                                    and MCP servers on the Mac (ssh nomac COMMAND); start and attach
+                                    keep it pointing at the folder's current Mac
   nomac start --permit APP=PERMISSIONS
                                     grant permissions on this Mac at start
   nomac exec [--wait 30] -- command args
@@ -87,6 +96,7 @@ const options = {
   prompts: { type: "string" }, gatekeeper: { type: "string" }, copy: { type: "boolean" }, app: { type: "boolean" },
   right: { type: "boolean" }, double: { type: "boolean" }, "no-screenshot": { type: "boolean" },
   permit: { type: "string", multiple: true }, reset: { type: "boolean" }, drive: { type: "string" },
+  parallel: { type: "boolean" }, alias: { type: "string" }, print: { type: "boolean" },
 };
 /** --permit com.example.App=camera,microphone (or =all), as the permissions option. */
 export function permitOption(values) {
@@ -308,14 +318,17 @@ export function projectLine({ path, on_drive }) {
   return on_drive ? `Project: ${short}, on your drive: kept when the Mac stops, and the next session builds only what changed.`
     : `Project: ${short}, deleted when the Mac stops: nomac pull what you need first.`;
 }
+/** "Mac: macOS 26.6.2, Xcode 27.0 (default) and Xcode 26.6 (/Applications/Xcode-26.6.app), iOS 27.0 Simulator", or "". */
+export function macLine(image) {
+  if (!image?.macos) return "";
+  // An image with a second Xcode names it and its path, as the API's image line does.
+  const others = (image.xcodes ?? []).filter(x => !x.default);
+  const xcode = others.length ? `Xcode ${image.xcode} (default) and ${others.map(x => `Xcode ${x.version} (${x.path})`).join(" and ")}` : `Xcode ${image.xcode}`;
+  return `Mac: macOS ${image.macos.split(" ")[0]}, ${xcode}${(image.simulator_runtimes ?? []).map(r => `, ${r} Simulator`).join("")}`;
+}
 export function statusSummary(session, image) {
   const lines = [`${session.id}: ${session.state}`];
-  if (image?.macos) {
-    // An image with a second Xcode names it and its path, as the API's image line does.
-    const others = (image.xcodes ?? []).filter(x => !x.default);
-    const xcode = others.length ? `Xcode ${image.xcode} (default) and ${others.map(x => `Xcode ${x.version} (${x.path})`).join(" and ")}` : `Xcode ${image.xcode}`;
-    lines.push(`Mac: macOS ${image.macos.split(" ")[0]}, ${xcode}${(image.simulator_runtimes ?? []).map(r => `, ${r} Simulator`).join("")}`);
-  }
+  if (macLine(image)) lines.push(macLine(image));
   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") {
@@ -351,6 +364,8 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
   if (values.help) return print(command === "desktop" ? DESKTOP_HELP : HELP);
   const wait = ["start", "attach", "stop"].includes(command) ? integer(values.wait, command === "stop" ? 60 : 300, 0, command === "stop" ? 300 : 600) : 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.");
+  // The image the last read reported (macOS, Xcodes, Simulators), for start's summary.
+  let lastImage;
   const output = result => {
     // Sync, pull and the other commands answer with their own result, which has no session.
     if (values.json || !["start", "attach", "stop"].includes(command)) { print(JSON.stringify(result, null, 2)); return result; }
@@ -364,7 +379,9 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
       : ["stopped", "failed"].includes(result.session.state) ? `${result.session.drive ? "The drive saves in the background (nomac drive shows it). " : ""}Start another: nomac start`
       : result.session.state === "stopping" ? "Stopping. Check: nomac status"
       : "Check: nomac status";
-    print(`${result.attached ? `${result.attached}\n` : ""}${result.session.id}: ${result.session.state}\n${next}\n${usage}${result.warning ? `\n${result.warning}` : ""}`);
+    // A ready Mac says what is on it, as nomac status does.
+    const mac = result.session.state === "ready" && macLine(lastImage) ? `${macLine(lastImage)}\n` : "";
+    print(`${result.attached ? `${result.attached}\n` : ""}${result.session.id}: ${result.session.state}\n${mac}${next}\n${usage}${result.warning ? `\n${result.warning}` : ""}`);
     return result;
   };
   const saveView = (local, view) => {
@@ -373,7 +390,11 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
     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);
+  const refresh = async local => {
+    const answer = await request("GET", `/api/v1/mac/sessions/${sessionId(local.id)}`);
+    if (answer.image) lastImage = answer.image;
+    return saveView(local, answer.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");
@@ -385,6 +406,8 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
     if (!local.workspaceDecided) await placeWorkspace(local);
     Object.assign(local, { generation: access.generation, hostKey: access.ssh.host_key, target: `agent@nomac-${local.id}`, workspace: local.workspace ?? 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);
+    // An SSH config entry this folder made earlier (nomac ssh-config) follows it to this Mac.
+    refreshSshConfig(local, store.project);
     return local;
   }
   /**
@@ -621,6 +644,22 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
     print(values.json ? JSON.stringify(answer, null, 2) : inputSummary(answer, saved));
     return answer;
   }
+  if (command === "ssh-config") {
+    if (positionals.length || values.json) throw new CliError("Usage: nomac ssh-config [--alias NAME] [--print]");
+    const alias = values.alias ?? "nomac";
+    const local = await ready(localSession());
+    const block = sshConfigBlock(local, alias, store.project);
+    if (values.print) return print(block);
+    const written = writeSshConfig(block, alias);
+    print([`Host ${alias} is this folder's Mac (${local.id}), in ${written.file}${written.addedInclude ? `, now included from ${written.includedFrom}` : ""}.`,
+      `Project on the Mac: ${local.workspace}`,
+      `  ssh ${alias}                      a shell; VS Code and Cursor: Remote-SSH, connect to "${alias}"`,
+      `  ssh -t ${alias} 'cd ${local.workspace} && npx -y @anthropic-ai/claude-code'   an agent on the Mac itself`,
+      `  claude mcp add xcode -- ssh ${alias} npx -y mobilebuildmcp@latest mcp   a Mac-only MCP server, from here`,
+      "nomac start and nomac attach from this folder point it at the folder's next Mac.",
+      "An open SSH connection keeps the Mac running until its time or spend limit: nomac stop when done."].join("\n"));
+    return { alias, session: local.id, ...written };
+  }
   if (command === "ssh") {
     if (values.json) throw new CliError("SSH streams bytes. Use session status --json for metadata.");
     const local = await ready(localSession());
@@ -715,7 +754,7 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
         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, ...(access ? { access } : {}) },
+          request: { profile: "standard", public_key: readFileSync(`${identity}.pub`, "utf8").trim(), limits, ...(access ? { access } : {}), ...(values.parallel ? { parallel: true } : {}) },
           ...previousDrive(store.load()) };
         store.save(local); store.saveBaseline({});
       }
@@ -726,7 +765,7 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
         try { result = await request("POST", "/api/v1/mac/sessions", { idempotencyKey: local.requestKey, body: local.request }); }
         catch (error) {
           // One Mac runs per account: when it was started elsewhere (an agent over MCP, the dashboard), use it from here.
-          if (error.code === "session_limit_reached" && values["request-key"] === undefined) {
+          if (error.code === "session_limit_reached" && values["request-key"] === undefined && !values.parallel) {
             const [running] = await liveSessions();
             if (running) {
               local = await attachTo(running);

package/src/mac-tools.mjs

@@ -14,13 +14,13 @@ 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: "Get a payment link for Mac credit and open it in the human's browser on this machine. Credit is $0.80 an hour, billed by the minute, sold in $10 packs (12.5 hours each), 1 to 10 packs per purchase, and never expires. Bigger purchases earn bonus credit: +5% from 3 packs ($30), +10% from 5 ($50), +20% at 10 ($100 buys $120, 150 hours). For a first purchase (get_mac_credits shows first_purchase: true), recommend 1 pack: $10 (12.5 hours) is enough to get started. For returning buyers who expect ongoing use, offer a choice, for example $10 or $50 (+10%, about 69 hours), and let them decide. Call this when get_mac_credits shows too little credit or start_mac returns insufficient_credit. Then tell the human a payment page opened (or give them the returned url if opened_in_browser is false) and ask them to pay. Never enter payment details yourself. Poll get_mac_credits until the balance appears, then start the Mac. Reuse request_key after a lost response; a new key is a new purchase.", inputSchema: schema({ packs: { type: "integer", minimum: 1, maximum: 10, default: 1, description: "Number of $10 packs, 1-10. Pick from the human's budget or expected hours; 3+ packs earn bonus credit." }, open: { type: "boolean", default: true, description: "Open the link in this machine's browser." }, request_key: key }, ["request_key"]), handler: async ({ packs = 1, open = true, request_key }) => {
+  { name: "get_mac_checkout", description: "Get a payment link for Mac credit and open it in the human's browser on this machine. Credit is $0.80 an hour, billed by the minute, sold in $10 packs (12.5 hours each), 1 to 10 packs per purchase, and never expires. Bigger purchases earn bonus credit: +5% from 3 packs ($30), +10% from 5 ($50), +20% at 10 ($100 buys $120, 150 hours). For a first purchase (get_mac_credits shows first_purchase: true), recommend 1 pack: $10 (12.5 hours) is enough to get started. For a refill, suggest 3 packs ($30, +5%) or more, and let them decide. Call this when get_mac_credits shows too little credit or start_mac returns insufficient_credit. Then tell the human a payment page opened (or give them the returned url if opened_in_browser is false) and ask them to pay. Never enter payment details yourself. Poll get_mac_credits until the balance appears, then start the Mac. Reuse request_key after a lost response; a new key is a new purchase.", inputSchema: schema({ packs: { type: "integer", minimum: 1, maximum: 10, default: 1, description: "Number of $10 packs, 1-10. Pick from the human's budget or expected hours; 3+ packs earn bonus credit." }, open: { type: "boolean", default: true, description: "Open the link in this machine's browser." }, request_key: key }, ["request_key"]), handler: async ({ packs = 1, open = true, request_key }) => {
     const result = await api("POST", "/api/v1/mac/credits/checkout", { body: { packs }, idempotencyKey: request_key });
     const opened = open && result.action === "open_checkout_url" && result.url ? openUrl(result.url) : false;
     return text({ ...result, opened_in_browser: opened });
   } },
   { name: "get_mac_credits", description: "Read the prepaid Mac credit balance: spendable dollars, spendable_seconds (how long a Mac can run on it), amounts held by a running session, pricing (including bonus_tiers for bigger purchases), recent purchases and first_purchase (true until the first paid top-up). Credit never expires. If spendable_seconds is below what the task needs, call get_mac_checkout.", inputSchema: schema({}), handler: async () => text(await api("GET", "/api/v1/mac/credits")) },
-  { name: "start_mac", description: "Allocate a full cloud Mac VM, billed from prepaid credit at $0.80 an hour by the minute. If it returns insufficient_credit, call get_mac_checkout, have the human pay, then retry with the same request_key. 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. The Mac is fully enabled for you: macOS asks for no administrator password, and the Mac's login password is in $NOMAC_MAC_PASSWORD on it; the answer's warning says so. Every Mac has the account's persistent drive at ~/drive, kept between sessions (get_mac_drive). access opts out: prompts ask keeps macOS's usual prompts; drive none starts without the drive.", inputSchema: schema({ public_key: { type: "string" }, request_key: key, limits: { type: "object", properties: { max_duration_seconds: { type: "integer", minimum: 60, maximum: 28800 }, idle_timeout_seconds: { type: "integer", minimum: 60, maximum: 3600 }, spend_cap_microunits: { type: "string", pattern: "^[1-9][0-9]{0,17}$" } }, additionalProperties: false },
+  { name: "start_mac", description: "Allocate a full cloud Mac VM, billed from prepaid credit at $0.80 an hour by the minute. If it returns insufficient_credit, call get_mac_checkout, have the human pay, then retry with the same request_key. 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. The Mac is fully enabled for you: macOS asks for no administrator password, and the Mac's login password is in $NOMAC_MAC_PASSWORD on it; the answer's warning says so. Every Mac has the account's persistent drive at ~/drive, kept between sessions (get_mac_drive). access opts out: prompts ask keeps macOS's usual prompts; drive none starts without the drive.", inputSchema: schema({ public_key: { type: "string" }, request_key: key, limits: { type: "object", properties: { max_duration_seconds: { type: "integer", minimum: 60, maximum: 28800 }, idle_timeout_seconds: { type: "integer", minimum: 60, maximum: 3600 }, spend_cap_microunits: { type: "string", pattern: "^[1-9][0-9]{0,17}$" } }, additionalProperties: false }, parallel: { type: "boolean", description: "true starts a second Mac beside the account's running one (accounts that bought credit, while NoMac has a Mac to spare); it runs without the account's drive. Without it, a start while a Mac runs answers session_limit_reached with that Mac's id, to use." },
     access: { type: "object", properties: { prompts: { type: "string", enum: ["auto", "ask"] }, gatekeeper: { type: "string", enum: ["off", "on"] }, drive: { type: "string", enum: ["account", "none"] },
       permissions: { type: "object", description: "By bundle ID: a list of permissions (camera, microphone, contacts, calendars, reminders, photos, desktop, documents, downloads and more) or \"all\"", additionalProperties: { anyOf: [{ type: "string", enum: ["all"] }, { type: "array", items: { type: "string" }, minItems: 1 }] } } }, 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")) },

package/src/mcp.mjs

@@ -19,7 +19,10 @@ const PROTOCOL_FALLBACK = "2025-06-18";
 /** How the tools fit together, sent once at initialize (the hosted server sends the same kind of text). */
 const INSTRUCTIONS = [
   "NoMac gives you a cloud Mac with Xcode, billed from prepaid credit ($0.80 an hour, by the minute).",
-  "Typical flow: get_mac_credits, start_mac, poll get_mac_session until ready, put code there (exec_mac with git clone, write_mac_file, fetch_to_mac, create_mac_upload_link), run exec_mac, get results with read_mac_file or create_mac_download_link, then stop_mac.",
+  "Typical flow: get_mac_credits, start_mac, poll get_mac_session until ready, put code there (exec_mac with git clone into ~/drive/src, write_mac_file, fetch_to_mac, create_mac_upload_link), run exec_mac, get results with read_mac_file or create_mac_download_link, then stop_mac.",
+  "The account's drive at ~/drive (50 GB) is on every Mac and kept between sessions; everything outside it is deleted at stop. Clone and build in ~/drive/src/<repo>, so the next session rebuilds only what changed.",
+  "When an answer says low_credit (under an hour of Mac time left), tell the human before a long build and offer its buy_url: a Mac stops when the credit runs out. For a refill, suggest 3 packs ($30, +5%).",
+  "One Mac runs per account at a time: start_mac while one runs answers session_limit_reached with its id, to use. For work that needs two at once, start_mac with parallel: true starts a second (accounts that bought credit, while NoMac has a Mac to spare); it runs without the drive.",
   "exec_mac returns a quick command's output in the same call; pass wait_seconds: 50 for builds and tests. A command still running comes back as a job: poll get_mac_job with its job_id, then read_mac_output.",
   "Never rerun a command to get its output; after a lost response, repeat the call with the same request_key and arguments.",
   "Write files with write_mac_file, not heredocs in exec_mac: a command is at most 64 KiB.",
@@ -70,7 +73,7 @@ export const TOOLS = [
     handler: async args => text(await api("GET", `/api/v1/store-capabilities?${new URLSearchParams(Object.entries(args ?? {}).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]))}`)),
   },
   ...[
-    ["read_store", "read", "Read a discovered Apple GET operation. Start with an apps_* relationship and scope:[]; reuse the returned resource scopes. Paginate with next_cursor and unchanged query. Raw IDs are accepted only for global lookups. Reads live Apple state, file upload operations and analytics report URLs."],
+    ["read_store", "read", "Read a discovered Apple GET operation. Start with an apps_* relationship and scope:[]; reuse the returned resource scopes. Paginate with next_cursor and unchanged query. Raw IDs are accepted only for global lookups. Reads live Apple state and analytics report URLs; a file's upload ranges come only in the answer to its reservation, so use upload_store_asset."],
     ["set_subscription_prices", "subscription-prices", "Sets a subscription's price in every territory from one base price point, using Apple's equalized prices (what App Store Connect's all-territories pricing does): territories already at that price are skipped, the others are set one by one, about 40 per call within 35 seconds. Call again (a new request_key, or none) until remaining is 0; a repeat changes nothing. Apple's refusal for a territory is listed in failed (UNSUPPORTED_TERRITORY: set the subscription's availability there first). Without confirm it returns a preview with the counts. Prices come from the human."],
     ["update_store", "write", "Execute a discovered Apple write using its exact JSON:API body. Copy scope and relationship references from read_store. Preview by default; confirm:true changes real Apple resources. Use owner-authorized prices and attestations. On pending, retry identical arguments with request_key; get_store_operation recovers lost keys. Use publish/update_review/manage_testflight for their dedicated lifecycle actions."],
   ].map(([name, route, description]) => ({
@@ -260,7 +263,7 @@ export const TOOLS = [
   {
     name: "upload_screenshots",
     description:
-      "Start a screenshot replacement for one display type and iOS version. PNGs are validated and prior images are backed up. Reuse request_key and the original body when retrying. Poll get_screenshot_upload until complete, rolled_back or needs_attention; accepted means still in progress. images: [{filename, data: base64 PNG}].",
+      "Start a screenshot replacement for one display type and iOS version. PNGs are validated and prior images are backed up. Reuse request_key and the original body when retrying. Poll get_screenshot_upload until complete, rolled_back or needs_attention; accepted means still in progress. images: [{filename, link}] with a create_mac_download_link url for each PNG on the Mac (any size; preferred), or [{filename, data: base64 PNG}] for small images (a request is capped near 4.5 MB in all).",
     inputSchema: {
       type: "object",
       properties: {

package/src/ssh-config.mjs

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "./api.mjs";
+
+/**
+ * nomac ssh-config: a Host entry for this folder's Mac in the person's own SSH config, so any
+ * SSH client reaches it by a name: VS Code and Cursor Remote-SSH, Claude Code's SSH sessions,
+ * plain ssh, and stdio MCP servers run on the Mac (ssh nomac COMMAND). The entries live in
+ * ~/.nomac/ssh_config, which ~/.ssh/config includes; each start or attach from the folder
+ * rewrites its entry for the new Mac, so the name keeps working across sessions.
+ */
+const BEGIN = "# >>> nomac";
+const END = "# <<< nomac";
+
+export const validAlias = alias => typeof alias === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(alias);
+const projectTag = project => createHash("sha256").update(project).digest("hex").slice(0, 16);
+/** SSH config values are double-quoted; a path with a quote or a control character cannot be. */
+const quoted = value => {
+  if (/["\x00-\x1f\x7f]/.test(value)) throw new CliError("This path cannot go in an SSH config.", `Path: ${value}`);
+  return `"${value}"`;
+};
+
+export function sshConfigPaths(home = homedir()) {
+  return { managed: join(home, ".nomac", "ssh_config"), user: join(home, ".ssh", "config"), sshDir: join(home, ".ssh") };
+}
+
+/** The Host entry for a ready hosted session (target, identity and known_hosts set by nomac's ready step). */
+export function sshConfigBlock(local, alias, project, { platform = process.platform, node = process.execPath, bin = fileURLToPath(new URL("../bin/nomac.mjs", import.meta.url)) } = {}) {
+  if (!validAlias(alias)) throw new CliError("--alias takes letters, digits, dots, underscores and hyphens, starting with a letter or digit.");
+  if (!/^ses_[A-Za-z0-9_-]{1,80}$/.test(local.id ?? "") || !local.identity || !local.knownHosts) throw new CliError("This folder's Mac is not ready for SSH yet.", "Run nomac start (or nomac attach), then nomac ssh-config.");
+  return [
+    `${BEGIN} ${alias} ${projectTag(project)} ${local.id}`,
+    `# ${project}`,
+    `Host ${alias}`,
+    `  HostName nomac-${local.id}`,
+    "  User agent",
+    `  HostKeyAlias nomac-${local.id}`,
+    `  UserKnownHostsFile ${quoted(local.knownHosts)}`,
+    ...(platform === "win32" ? [] : ["  GlobalKnownHostsFile /dev/null"]),
+    "  StrictHostKeyChecking yes",
+    `  IdentityFile ${quoted(local.identity)}`,
+    "  IdentitiesOnly yes",
+    `  ProxyCommand ${quoted(node)} ${quoted(bin)} tunnel ${local.id}`,
+    "  ForwardAgent no",
+    "  ServerAliveInterval 15",
+    "  ServerAliveCountMax 3",
+    `${END} ${alias}`,
+  ].join("\n");
+}
+
+/** The managed file's entries, as [alias, text, project tag]. */
+function entries(text) {
+  const found = [];
+  const pattern = new RegExp(`^${BEGIN} (\\S+) (\\S+)[^\\n]*\\n[\\s\\S]*?^${END} \\1$`, "gm");
+  for (const match of text.matchAll(pattern)) found.push({ alias: match[1], tag: match[2], text: match[0] });
+  return found;
+}
+
+function writeAtomic(file, text) {
+  const temporary = `${file}.${process.pid}.tmp`;
+  try { writeFileSync(temporary, text, { mode: 0o600 }); renameSync(temporary, file); }
+  finally { rmSync(temporary, { force: true }); }
+  chmodSync(file, 0o600);
+}
+
+/**
+ * Puts the entry in ~/.nomac/ssh_config (replacing one of the same name) and makes sure
+ * ~/.ssh/config includes that file. Include must come before any Host line to apply to
+ * every host, so it is added as the first line. Returns what changed.
+ */
+export function writeSshConfig(block, alias, { home = homedir() } = {}) {
+  const paths = sshConfigPaths(home);
+  mkdirSync(join(home, ".nomac"), { recursive: true, mode: 0o700 });
+  const current = existsSync(paths.managed) ? readFileSync(paths.managed, "utf8") : "";
+  const kept = entries(current).filter(entry => entry.alias !== alias).map(entry => entry.text);
+  writeAtomic(paths.managed, `# Written by nomac ssh-config. Each start or attach updates its folder's entry.\n\n${[...kept, block].join("\n\n")}\n`);
+  mkdirSync(paths.sshDir, { recursive: true, mode: 0o700 });
+  const include = `Include ${paths.managed.includes(" ") ? quoted(paths.managed) : paths.managed}`;
+  const user = existsSync(paths.user) ? readFileSync(paths.user, "utf8") : "";
+  const included = user.split(/\r?\n/).some(line => line.trim() === include || line.trim() === `Include ${paths.managed}` || line.trim() === "Include ~/.nomac/ssh_config");
+  if (!included) writeAtomic(paths.user, `${include}\n${user.length && !user.startsWith("\n") ? "\n" : ""}${user}`);
+  return { file: paths.managed, includedFrom: paths.user, addedInclude: !included };
+}
+
+/**
+ * After a start or attach: if this folder has an entry, point it at the folder's new Mac.
+ * Never fails the command it follows.
+ */
+export function refreshSshConfig(local, project, { home = homedir(), ...options } = {}) {
+  try {
+    const { managed } = sshConfigPaths(home);
+    if (!existsSync(managed)) return false;
+    const tag = projectTag(project);
+    const mine = entries(readFileSync(managed, "utf8")).filter(entry => entry.tag === tag);
+    if (!mine.length || mine.every(entry => entry.text.split("\n", 1)[0].endsWith(` ${local.id}`))) return false;
+    for (const entry of mine) writeSshConfig(sshConfigBlock(local, entry.alias, project, options), entry.alias, { home });
+    return true;
+  } catch { return false; }
+}

package/src/store-upload.mjs

@@ -1,6 +1,6 @@
 // Shared by the hosted upload endpoint and the published CLI (copied by the
-// schema generator). Provider upload URLs come only from an authenticated,
-// app-scoped read_store response; Nomac credentials never go to those URLs.
+// schema generator). Provider upload URLs come only from the authenticated,
+// app-scoped answer to the reservation; Nomac credentials never go to those URLs.
 import { createHash, randomUUID } from 'node:crypto';
 import { open } from 'node:fs/promises';
 import { basename } from 'node:path';
@@ -82,8 +82,9 @@ export async function uploadStoreAsset(args, call) {
     stage = 'upload';
     const completed = ['UPLOAD_COMPLETE', 'COMPLETE', 'FAILED'].includes(attributes.assetDeliveryState?.state);
     if (!completed) {
-      const operations = attributes.uploadOperations;
-      if (!Array.isArray(operations) || !operations.length) throw new Error('Apple has not exposed upload operations yet. Retry this same upload.');
+      // Apple lists the upload ranges in its answer to the reservation only (a later read has none).
+      const operations = reservation.upload_operations?.length ? reservation.upload_operations : attributes.uploadOperations;
+      if (!Array.isArray(operations) || !operations.length) throw new Error(`Apple gives a file's upload links only in its answer to the reservation, and this request has none (that answer was lost). Delete the reservation (update_store with ${args.operation.replace(/_createInstance$/, '_deleteInstance')} and this scope), then upload again with a new request_key.`);
       let end = 0;
       for (const op of [...operations].sort((a, b) => a.offset - b.offset)) {
         if (op.method !== 'PUT' || !Number.isSafeInteger(op.offset) || !Number.isSafeInteger(op.length) || op.length < 1 || op.offset !== end || op.offset + op.length > size) throw new Error('Apple returned invalid or incomplete upload byte ranges.');
@@ -105,7 +106,7 @@ export async function uploadStoreAsset(args, call) {
         const part = await source(op.offset, op.length);
         try {
           const response = await fetch(op.url, { method: 'PUT', headers, body: part, duplex: 'half', redirect: 'error', signal: AbortSignal.timeout(120_000) });
-          if (!response.ok) throw new Error(`Apple asset upload returned HTTP ${response.status}. Retry with this same request key to refresh its upload URLs.`);
+          if (!response.ok) throw new Error(`Apple asset upload returned HTTP ${response.status}. Retry with this same request key; if it fails again, its upload links have expired: delete the reservation (update_store with ${args.operation.replace(/_createInstance$/, '_deleteInstance')} and this scope) and upload again with a new request_key.`);
           await response.body?.cancel();
         } finally { if (typeof part.destroy === 'function') part.destroy(); }
       }