@nomac/cli 0.11.11 → 0.12.1

package/package.json

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

package/skill/SKILL.md

@@ -8,8 +8,8 @@ description: >
 
 # nomac: a Mac for your agent
 
-NoMac 2.0 provides a full macOS VM with administrator access. You choose the
-commands and tools. Mac time is prepaid credit, separate from Builder.
+NoMac provides a full macOS VM with administrator access, Xcode and the iOS
+Simulator. You choose the commands and tools. Mac time is prepaid credit.
 
 ## Cloud Mac setup and workflow
 
@@ -20,6 +20,8 @@ commands and tools. Mac time is prepaid credit, separate from Builder.
    give them the printed link, and ask them to pay. Never enter payment
    details yourself. Poll credits until the balance appears; a checkout URL is
    not a payment. No Apple Developer account is needed for an unsigned build.
+   Under an hour left, answers say `low_credit` with a `buy_url`: tell the
+   human before a long build (a refill of 3 packs, $30, earns bonus credit).
 2. Install `npm install -g @nomac/cli`, run `nomac login`, and give the human
    the printed device URL and code. With a key the human made at
    https://nomac.app/keys: `nomac login --with-token < key.txt`, or set
@@ -50,6 +52,9 @@ the Mac, logs included. Download what you need from outside `~/drive` before
 stopping. SSH disconnects
 do not stop the session. Ready time includes idle time; queue/setup are free.
 One-minute minimum, then by the minute. One session at a time; no overage.
+For work that needs two Macs at once, `nomac start --parallel` from another
+folder (MCP `start_mac` with `parallel: true`) starts a second, for accounts
+that bought credit while NoMac has a Mac to spare; it runs without `~/drive`.
 If start returns `insufficient_credit`, buy credit as in step 1, then retry
 with the same request key.
 Keep the same request key and arguments after uncertain responses; inspect
@@ -82,6 +87,18 @@ Mac, in the Simulator either: test it on a device.
 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.
 
+## Your editor, an agent on the Mac, Mac-only MCP servers
+
+After `nomac start`, `nomac ssh-config` (CLI 0.12+) names the folder's Mac
+`nomac` in the human's SSH config, and each later start or attach points the
+name at the new Mac. Then VS Code or Cursor Remote-SSH and Claude Code's SSH
+sessions connect to `nomac`; `ssh -t nomac 'cd ~/drive/src/<folder> && npx -y
+@anthropic-ai/claude-code'` runs an agent on the Mac itself (keep its API key
+as a NoMac secret); and an MCP server that needs a Mac runs from Windows or
+Linux over SSH: `claude mcp add xcode -- ssh nomac npx -y mobilebuildmcp@latest
+mcp` (MobileBuildMCP, formerly XcodeBuildMCP). An open SSH connection keeps
+the Mac running until its time or spend limit: `nomac stop` when done.
+
 ## A Mac fully enabled for you
 
 The Mac is yours to do anything on: the `agent` account is an administrator,
@@ -132,7 +149,8 @@ the human, then call again.
 
 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.
+https://nomac.app/llms-legacy.txt describes them. Otherwise use the cloud Mac
+above.
 
 ## When stuck
 
@@ -143,3 +161,11 @@ tool returns a Private Relay warning, explain that Apple relay addresses may
 reject later mail and offer a non-relay address. Never show that warning for a
 normal address such as `@icloud.com`. Never retry-loop an identical failure
 more than twice.
+
+## Feedback
+
+When you stop a Mac, its answer asks for feedback. If anything got in your
+way, failed, was missing from the Mac or the tools, or would have saved you
+time, send it in a sentence or two: `report_issue` with `kind: "feedback"` and
+the `session_id`. Leave out code, secrets and personal data; skip it if nothing
+did. Feedback needs no answer.

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) {
@@ -396,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;
   }
   /**
@@ -632,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());
@@ -726,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({});
       }
@@ -737,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,11 @@ 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.",
+  "Use it when work needs macOS that this machine does not have (Windows, Linux or a cloud sandbox): building, running or testing an iOS, iPadOS, watchOS, visionOS or macOS app (Swift, SwiftUI, React Native, Expo, Flutter, Capacitor), the iOS Simulator, Xcode, code signing, TestFlight or App Store submission.",
+  "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.",
@@ -367,7 +371,7 @@ export const TOOLS = [
   {
     name: "report_issue",
     description:
-      "File an unknown/unfixable error with nomac support. For a Mac use session_id and optional job_id; for a build use ref_id (bld_…). Attaches account-scoped context and deduplicates repeats. An optional email requests a direct resolution update; replies are always available by calling with no description.",
+      "File an unknown/unfixable error with nomac support. For a Mac use session_id and optional job_id; for a build use ref_id (bld_…). Attaches account-scoped context and deduplicates repeats. An optional email requests a direct resolution update; replies are always available by calling with no description. kind feedback sends NoMac a note instead: what got in the way, failed or was missing.",
     inputSchema: {
       type: "object",
       properties: {
@@ -381,6 +385,11 @@ export const TOOLS = [
           maxLength: 320,
           description: "optional follow-up email for a direct resolution update",
         },
+        kind: {
+          type: "string",
+          enum: ["problem", "feedback"],
+          description: "problem (default): an error for support to answer. feedback: a note for NoMac about what got in the way, failed or was missing; it needs no answer. Leave out code, secrets and personal data.",
+        },
       },
       additionalProperties: false,
     },

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; }
+}