@nomac/cli 0.12.0 → 0.13.0

package/bin/nomac.mjs

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
 import { main } from "../src/cli.mjs";
+import { runNewerIfInstalled } from "../src/self-update.mjs";
+
+// A newer CLI this one installed in the background runs the command instead (self-update.mjs).
+const delegated = await runNewerIfInstalled(process.argv.slice(2)).catch(() => undefined);
+if (delegated !== undefined) process.exit(delegated);
 
 main(process.argv.slice(2)).catch((err) => {
   const args = process.argv.slice(2);

package/package.json

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

@@ -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
@@ -49,7 +51,17 @@ name>`, which is kept between sessions; stopping deletes everything else on
 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.
+A Mac stops at its time limit (2 hours unless `nomac start --max-duration`
+set another), its spend cap, when credit runs out, or when idle; a build left
+running in the background keeps it awake while it uses the CPU. In its last
+15 minutes answers carry `stop_notice` (when and why) and the CLI prints it:
+`nomac extend 60` (MCP `extend_mac`) adds an hour, up to 8 hours in all; for
+`reason: credit`, the human adds credit. The CLI updates itself in the
+background (`NOMAC_NO_AUTO_UPDATE=1` turns it off; `nomac update` now).
 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 +94,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 +156,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 +168,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/api.mjs

@@ -1,5 +1,25 @@
 import { loadApiKey, loadApiUrl } from "./config.mjs";
 import { clientHeaders } from "./client-info.mjs";
+import { rememberLatest, updateNotice } from "./self-update.mjs";
+
+/** Lines for the person at the terminal, on stderr (never stdout, which commands' output owns), once each. */
+const said = new Set();
+function say(key, text) {
+  if (said.has(key)) return;
+  said.add(key);
+  process.stderr.write(`${text}\n`);
+}
+/** What every answer may carry besides its own result: the latest CLI, and a Mac about to stop. */
+function noteAnswer(res, json) {
+  const latest = res.headers.get("x-nomac-cli-latest");
+  if (latest) {
+    rememberLatest(latest);
+    const notice = updateNotice();
+    if (notice) say("update", notice);
+  }
+  const stop = json && typeof json === "object" ? json.stop_notice : undefined;
+  if (stop && typeof stop.message === "string") say(`stop:${stop.stops_at}:${stop.minutes_left <= 2 ? "last" : "soon"}`, `NoMac: ${stop.message.replace(/call extend_mac \(CLI: (nomac extend)\)/, "run $1")}`);
+}
 
 export class CliError extends Error {
   constructor(message, friendly, status, code, details) {
@@ -27,6 +47,7 @@ export async function apiPublic(method, path, body) {
   } catch {
     throw new CliError(`API returned non-JSON (HTTP ${res.status}): ${text.slice(0, 200)}`, undefined, res.status);
   }
+  noteAnswer(res, json);
   return { status: res.status, ok: res.ok, json };
 }
 
@@ -64,6 +85,7 @@ export async function api(method, path, { body, raw, idempotencyKey } = {}) {
   } catch {
     throw new CliError(`API returned non-JSON (HTTP ${res.status})`, "The response could not be read. Reconcile the operation before retrying; reuse its request_key.", res.status, "bad_response", { code: "bad_response", ...(idempotencyKey ? { request_key: idempotencyKey } : {}) });
   }
+  noteAnswer(res, json);
   if (!res.ok) {
     // Some answers carry more beside the error, such as publish's blockers and findings.
     const { error, ...beside } = json && typeof json === "object" && !Array.isArray(json) ? json : {};

package/src/cli.mjs

@@ -32,6 +32,7 @@ Use it:
   nomac drive                  the account's persistent drive at ~/drive, kept between sessions
   nomac record                 record a video; nomac record stop saves it with a share link
   nomac status                 state, cost so far and when it stops
+  nomac extend 60              keep the Mac running another hour (8 hours in all)
   nomac secrets                variables and files every Mac receives (nomac secrets --help)
   nomac apple                  whether Apple is connected: team key, certificates, profiles
   nomac sign [path]            set up App Store signing for the project on the Mac
@@ -42,8 +43,8 @@ Use it:
 Agents:
   nomac mcp                    MCP server for Claude Code, Codex, Cursor and others
 
-More: nomac start --help, nomac whoami, nomac --version, nomac start --host user@mac (a Mac you own)
-Environment: NOMAC_API_KEY, NOMAC_API_URL`;
+More: nomac start --help, nomac whoami, nomac --version, nomac update, nomac start --host user@mac (a Mac you own)
+Environment: NOMAC_API_KEY, NOMAC_API_URL, NOMAC_NO_AUTO_UPDATE=1 (the CLI updates itself otherwise)`;
 
 // The Builder commands act at once (a release build uses one of the plan's builds),
 // so they take only their own flags and print usage for --help instead of running.
@@ -106,6 +107,7 @@ export async function main(argv) {
     // falls through: everyone else sees their Mac
     case "start":
     case "attach":
+    case "extend":
     case "exec":
     case "job":
     case "output":
@@ -208,6 +210,10 @@ export async function main(argv) {
       console.log(`auth:        ${me.auth?.via ?? "?"}${me.auth?.key_id ? ` (${me.auth.key_id})` : ""}`);
       return;
     }
+    case "update": {
+      const { updateCommand } = await import("./update-command.mjs");
+      return updateCommand(rest);
+    }
     case "--version":
     case "-v":
     case "version": {

package/src/hosted-sessions.mjs

@@ -12,6 +12,8 @@ import { screenshot, startRecording, stopRecording } from "./mac-screen.mjs";
 import { refreshSshConfig, sshConfigBlock, writeSshConfig } from "./ssh-config.mjs";
 
 const WORKSPACE = "/Users/agent/workspace";
+/** How long the CLI keeps trying to put a project on the drive before it gives up for now. */
+const PLACE_BUDGET_MS = 120_000;
 
 const HELP = `Nomac cloud Mac sessions
   nomac start [--wait 300] [--max-duration 7200] [--idle-timeout 600] [--max-cost 5] [--json]
@@ -74,6 +76,8 @@ const HELP = `Nomac cloud Mac sessions
                                     start a screen video; nomac record stop saves it
                                     as nomac-recording.mp4 (or -o) with a share link
   nomac status [--json]             state, cost so far and when it stops
+  nomac extend [MINUTES] [--json]   keep the Mac running longer: its time limit goes up by
+                                    MINUTES (60 by default; 8 hours in all), its spend cap with it
   nomac attach [SESSION_ID]         use the account's running Mac from this folder, when your
                                     agent started it elsewhere (MCP, the dashboard); start does it too
   nomac stop [--wait 60] [--json]   stop the Mac: deletes it and its files, not ~/drive
@@ -333,7 +337,7 @@ export function statusSummary(session, image) {
   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 (stops.length) lines.push(`Stops by itself ${stops.join(", or ")}. Longer: nomac extend 60. Stop now: nomac stop`);
   }
   const d = session.drive;
   if (d && ["mounted", "saving", "saved", "unavailable", "not_saved"].includes(d.state)) {
@@ -424,18 +428,42 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
         // A folder another local folder claimed, or one made on the Mac some other way, is left alone.
         + 'if { [ -e "$claims/$d" ] && [ "$(cat "$claims/$d")" != "$ORIGIN" ]; } || { [ ! -e "$claims/$d" ] && [ -n "$(ls -A ~/drive/src/"$d" 2>/dev/null)" ]; }; then d="$NAME-$ORIGIN"; fi; '
         + 'printf %s "$ORIGIN" > "$claims/$d"; mkdir -p ~/drive/src/"$d"; cd ~/drive/src/"$d"; pwd';
-      const job = await request("POST", `/api/v1/mac/sessions/${sessionId(local.id)}/jobs?wait=30`, { idempotencyKey: `cli-place-${local.id.slice(4, 24)}-${origin}`,
-        body: { argv: ["/bin/bash", "-c", script], env: { NAME: name, ORIGIN: origin }, timeout_seconds: 30 } }).catch(() => null);
+      const job = await placeOnDrive(local, script, { NAME: name, ORIGIN: origin }, `cli-place-${local.id.slice(4, 24)}-${origin}`);
       const path = String(job?.stdout ?? "").trim();
       if (job?.exit_code === 0 && path.startsWith("/Users/agent/drive/src/") && !path.slice(23).includes("/")) {
         // The same folder on the drive as last time: what was synced there then is still there.
         if (local.previousDriveWorkspace?.path === path) store.saveBaseline(local.previousDriveWorkspace.baseline);
         Object.assign(local, { workspace: validateWorkspace(path), workspaceOnDrive: true });
+      } else {
+        // The drive itself refused (full, or not writable): this session works in ~/workspace, and says so.
+        const why = !job ? "the Mac refused the request" : job.exit_code === 0 ? "the Mac named another folder" : `exit code ${job.exit_code}${String(job.stderr ?? "").trim() ? `: ${String(job.stderr).trim().split("\n").pop().slice(0, 120)}` : ""}`;
+        console.error(`NoMac: this project could not be put on the drive (${why}), so this session works in ${WORKSPACE}, which is deleted when the Mac stops. Copy anything to keep into ~/drive, or check the drive: nomac drive.`);
       }
     }
     delete local.previousDriveWorkspace;
     local.workspaceDecided = true; store.save(local);
   }
+  /**
+   * Runs the placement script until it answers, retrying what is passing with the same request
+   * key: a Mac is often slow in its first minutes, and a lost or busy answer put whole sessions'
+   * work in ~/workspace, deleted at stop (October 2026). An answer that never comes within the
+   * budget fails the command, with the project still unplaced, so the next command tries again.
+   */
+  async function placeOnDrive(local, script, env, key) {
+    const started = now(), base = `/api/v1/mac/sessions/${sessionId(local.id)}/jobs`;
+    const passing = error => ["guest_busy", "host_unavailable", "outcome_unknown", "operation_unconfirmed", "bad_response", "operation_pending"].includes(error?.code) || error?.status === 429 || error?.status >= 500;
+    for (;;) {
+      try {
+        let job = await request("POST", `${base}?wait=30`, { idempotencyKey: key, body: { argv: ["/bin/bash", "-c", script], env, timeout_seconds: 30 } });
+        while (job?.state !== "exited" && job?.id && now() - started < PLACE_BUDGET_MS) { await sleep(2000); job = await request("GET", `${base}/${job.id}`); }
+        if (job?.state === "exited") return job;
+      } catch (error) {
+        if (!passing(error)) return null;
+      }
+      if (now() - started + 5000 > PLACE_BUDGET_MS) throw new CliError("The Mac did not answer in time.", `The Mac did not answer while this project was being put on its drive (~/drive/src); nothing was uploaded. It is often slow in its first minutes: run the same command again.`, undefined, "drive_placement_pending");
+      await sleep(5000);
+    }
+  }
   /**
    * A Mac started elsewhere (by an agent over MCP, the dashboard or another folder) took no key
    * from this folder: add this folder's own to its authorized keys with an ordinary command, so
@@ -482,6 +510,15 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
     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 === "extend") {
+    if (positionals.length > 1) throw new CliError("Usage: nomac extend [MINUTES] [--json]");
+    const minutes = integer(positionals[0], 60, 1, 480);
+    const local = localSession();
+    const result = await request("POST", `/api/v1/mac/sessions/${sessionId(local.id)}/extend`, { body: { minutes } });
+    saveView(local, result.session);
+    print(values.json ? JSON.stringify(result, null, 2) : result.message);
+    return result;
+  }
   if (command === "status") {
     if (positionals.length) throw new CliError("Usage: nomac status [--json]");
     const loaded = store.load();
@@ -616,7 +653,7 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
   if (command === "permit") {
     if (positionals.length < 2) throw new CliError("Usage: nomac permit APP PERMISSION... (or all), for example nomac permit com.example.App camera microphone");
     const id = sessionId(localSession().id);
-    const job = await request("POST", `/api/v1/mac/sessions/${id}/jobs?wait=30`, { idempotencyKey: `cli-${randomUUID()}`, body: { argv: ["/opt/homebrew/bin/node", "/usr/local/bin/nomac-permit", ...positionals], timeout_seconds: 60 } });
+    const job = await request("POST", `/api/v1/mac/sessions/${id}/jobs?wait=30`, { idempotencyKey: `cli-${randomUUID()}`, body: { argv: ["/usr/local/bin/nomac-permit", ...positionals], timeout_seconds: 60 } });
     let answer;
     try { answer = JSON.parse(String(job.stdout ?? "").trim().split("\n").pop()); } catch { throw new CliError("The Mac gave no answer for the grant.", "Check that the Mac is ready (nomac status), then try again."); }
     if (!answer.ok) throw new CliError(answer.message, undefined, undefined, answer.error);

package/src/mac-tools.mjs

@@ -25,6 +25,7 @@ export const MAC_TOOLS = [
       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")) },
   { name: "get_mac_session", description: "Read live Mac allocation state, cost, funded time and cleanup confirmation, and once ready the credentials installed on it (secrets, signing identities and profiles, by name and path, never values) and account: the Mac's user, whether its login password is set (in $NOMAC_MAC_PASSWORD on the Mac), the access choices, and how to type and click (mac_input). queued/provisioning means wait; stopping is not yet confirmed cleanup.", inputSchema: schema({ session_id: session }, ["session_id"]), handler: async args => text(await api("GET", base(args))) },
+  { name: "extend_mac", description: "Keep a running Mac going longer: raises its time limit by minutes (default 60), up to 8 hours since it started, and its spend cap with it. Call it when an answer's stop_notice says the Mac stops soon at its time limit or spend cap, or before a build or test that would not finish in time. It adds no credit: when stop_notice's reason is credit, the human adds some (get_mac_checkout). The Mac still bills $0.80 an hour while it runs.", inputSchema: schema({ session_id: session, minutes: { type: "integer", minimum: 1, maximum: 480, default: 60, description: "Minutes to add to the time limit, 1-480. Default 60." } }, ["session_id"]), handler: async ({ session_id, minutes = 60 }) => text(await api("POST", `${base({ session_id })}/extend`, { body: { minutes } })) },
   { name: "get_mac_drive", description: "Read the account's persistent drive: a disk kept between sessions and mounted at ~/drive on every Mac (50 GB). What is there stays for the next session: keep projects in ~/drive/src for incremental builds; package and build caches (DerivedData, Swift packages, CocoaPods, npm) are kept there already. NoMac saves it when a Mac stops, with nothing to call. Shows the space used, the newest saved version, a save still in progress, recent versions, and the date it is deleted after 90 days without a Mac.", inputSchema: schema({}), handler: async () => text(await api("GET", "/api/v1/mac/drive")) },
   { name: "reset_mac_drive", description: "Empty the account's persistent drive: the next Mac starts with a new, empty ~/drive, and everything on the old drive is deleted, with no way back. Stop any running session first (stop_mac). For a single Mac without the drive, start_mac with access drive none instead.", inputSchema: schema({}), handler: async () => text(await api("DELETE", "/api/v1/mac/drive")) },
   { name: "list_secrets", description: "List the account's secrets by name: variables (set in every shell and command on the Mac) and files (with their path on the Mac), whether every Mac receives them or only when asked, sizes, and secrets an agent asked for that the person has not entered yet. Values are never returned.", inputSchema: schema({}), handler: async () => text(await api("GET", "/api/v1/secrets")) },

package/src/mcp.mjs

@@ -19,6 +19,7 @@ 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).",
+  "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%).",
@@ -28,6 +29,8 @@ const INSTRUCTIONS = [
   "Write files with write_mac_file, not heredocs in exec_mac: a command is at most 64 KiB.",
   "Shipping without the Apple key on the Mac: set_up_signing on the project returns the files and commands that sign a build with the agent's own tools; send_to_testflight sends the signed .ipa to TestFlight; publish submits it for App Review; notarize notarizes and staples a Developer ID-signed Mac app. Never ask for a secret in the chat: request_secret gives the human a link, and every Mac receives the account's secrets.",
   "The Mac is fully enabled for you: sudo needs no password, macOS asks for no administrator password, the privacy prompts and password dialogs it still shows are answered on the Mac within seconds, the screen never locks, and the Mac's login password is in $NOMAC_MAC_PASSWORD on it (for the login keychain or any prompt). nomac-permit APP camera (run with exec_mac) grants an app privacy permissions before it asks. To type or click as a person would, also on the lock screen and in password dialogs, call mac_input: its answer has a screenshot. When screenshot_mac reports screen_locked or a dialog, follow its next_step.",
+  "A Mac stops at its time limit (2 hours unless start_mac set max_duration_seconds), its spend cap, when the account's credit runs out, or after its idle timeout; everything outside ~/drive is deleted then. In its last 15 minutes every answer about it carries stop_notice, with when and why: call extend_mac to keep it running (time limit or spend cap), or ask the human to add credit (reason credit). Before a long build, check that it fits or extend first.",
+  "When an answer carries cli_update, this NoMac CLI is out of date: tell the human, who updates it with npm install -g @nomac/cli@latest (or nomac update) and restarts this MCP server.",
   "Always stop_mac when finished, after reading any output you need, so credit is not spent on an idle Mac.",
 ].join(" ");
 
@@ -370,7 +373,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: {
@@ -384,6 +387,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/self-update-worker.mjs

@@ -0,0 +1,25 @@
+// Installs one NoMac CLI version into its own folder, in the background (self-update.mjs):
+// node self-update-worker.mjs <version> <dir>. It is ready only once it answers --version
+// with that number; until then the running CLI keeps handling commands itself.
+import { spawnSync } from "node:child_process";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { installedBin, pruneInstalls } from "./self-update.mjs";
+
+const [version, dir] = process.argv.slice(2);
+if (!/^\d{1,4}\.\d{1,4}\.\d{1,4}$/.test(version ?? "") || !dir) process.exit(2);
+const windows = process.platform === "win32";
+try {
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const npm = spawnSync(windows ? "npm.cmd" : "npm", ["install", "--prefix", dir, "--no-audit", "--no-fund", "--omit=dev", "--loglevel=error", `@nomac/cli@${version}`],
+    { stdio: "ignore", timeout: 10 * 60_000, shell: windows, windowsHide: true });
+  if (npm.status !== 0) throw new Error("npm install failed");
+  const check = spawnSync(process.execPath, [installedBin(version), "--version"], { encoding: "utf8", timeout: 30_000, env: { ...process.env, NOMAC_CLI_DELEGATED: "check", NOMAC_NO_AUTO_UPDATE: "1" }, windowsHide: true });
+  if (check.status !== 0 || !check.stdout.includes(version)) throw new Error("the installed CLI did not run");
+  writeFileSync(join(dir, ".nomac-ready"), `${new Date().toISOString()}\n`);
+  pruneInstalls(version);
+} catch {
+  rmSync(dir, { recursive: true, force: true });
+  process.exit(1);
+}

package/src/self-update.mjs

@@ -0,0 +1,112 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CLI_VERSION } from "./client-info.mjs";
+
+/**
+ * Keeping the CLI current. nomac.app names the latest CLI on every answer (x-nomac-cli-latest);
+ * this CLI remembers it. When a newer one is out, it installs it in the background into
+ * ~/.nomac/cli/<version> (never over the running files) and, from the next command, hands
+ * every command to it. A global npm install or an npx cache is never touched, so it works the
+ * same for both, and a failed install leaves this version running. On October 15, 2026 most
+ * accounts using the CLI ran 0.5 to 0.11, missing months of fixes, and nothing told them.
+ * NOMAC_NO_AUTO_UPDATE=1 turns it off; then it only says an update is out.
+ */
+const DIR = () => join(homedir(), ".nomac");
+const STATE = () => join(DIR(), "cli-update.json");
+export const installDir = (version) => join(DIR(), "cli", version);
+export const installedBin = (version) => join(installDir(version), "node_modules", "@nomac", "cli", "bin", "nomac.mjs");
+/** Written once the version installed and answered --version with its own number. */
+const marker = (version) => join(installDir(version), ".nomac-ready");
+const VERSION = /^\d{1,4}\.\d{1,4}\.\d{1,4}$/;
+/** How long a failed or unfinished background install waits before it is tried again. */
+const RETRY_MS = 6 * 3600_000;
+/** How often a person is told about an update this CLI cannot install itself. */
+const NOTICE_MS = 24 * 3600_000;
+
+/** Whether version a is newer than b (x.y.z). */
+export function newer(a, b) {
+  const pa = String(a).split(".").map(Number), pb = String(b).split(".").map(Number);
+  for (let i = 0; i < 3; i++) if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0);
+  return false;
+}
+export const autoUpdateOff = () => process.env.NOMAC_NO_AUTO_UPDATE === "1";
+
+export function readState() {
+  try { return JSON.parse(readFileSync(STATE(), "utf8")); } catch { return {}; }
+}
+function writeState(state) {
+  try { mkdirSync(DIR(), { recursive: true }); writeFileSync(STATE(), JSON.stringify(state, null, 2) + "\n"); } catch { /* best effort */ }
+}
+
+/** Records the latest version nomac.app named (from a response header). Never throws. */
+export function rememberLatest(version) {
+  if (typeof version !== "string" || !VERSION.test(version)) return;
+  const state = readState();
+  if (state.latest !== version) writeState({ ...state, latest: version, seen_at: new Date().toISOString() });
+}
+
+/** The newest installed version this CLI should hand commands to, if any. */
+export function delegateTarget(state = readState(), own = CLI_VERSION) {
+  if (autoUpdateOff() || process.env.NOMAC_CLI_DELEGATED) return undefined;
+  const ready = installedVersions().filter(v => newer(v, own) && existsSync(installedBin(v)));
+  return ready.sort((a, b) => (newer(a, b) ? -1 : 1))[0];
+}
+export function installedVersions() {
+  try { return readdirSync(join(DIR(), "cli")).filter(v => VERSION.test(v) && existsSync(marker(v))); } catch { return []; }
+}
+
+/**
+ * At startup: runs the command with a newer installed CLI when there is one (and returns its
+ * exit code), else starts the background install of a newer one nomac.app named. Returns
+ * undefined when this CLI should run the command itself.
+ */
+export async function runNewerIfInstalled(argv) {
+  const state = readState(), target = delegateTarget(state);
+  if (target) {
+    // The original entry point: ssh-config's ProxyCommand and the like keep pointing at it,
+    // so they keep working after this installed version is replaced by a newer one.
+    const entry = process.env.NOMAC_CLI_ENTRY ?? process.argv[1];
+    const child = spawn(process.execPath, [installedBin(target), ...argv], { stdio: "inherit",
+      env: { ...process.env, NOMAC_CLI_DELEGATED: CLI_VERSION, ...(entry ? { NOMAC_CLI_ENTRY: entry } : {}) } });
+    for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(signal, () => child.kill(signal));
+    return new Promise(resolve => {
+      child.on("error", () => resolve(undefined));
+      child.on("exit", (code, signal) => resolve(code ?? (signal ? 128 : 1)));
+    });
+  }
+  if (!autoUpdateOff() && !process.env.NOMAC_CLI_DELEGATED && state.latest && newer(state.latest, CLI_VERSION)) startInstall(state.latest, state);
+  return undefined;
+}
+
+/** Installs version in the background, at most once per RETRY_MS. */
+export function startInstall(version, state = readState()) {
+  if (!VERSION.test(version) || existsSync(marker(version))) return false;
+  if (state.attempted === version && Date.now() - Date.parse(state.attempted_at ?? 0) < RETRY_MS) return false;
+  writeState({ ...state, attempted: version, attempted_at: new Date().toISOString() });
+  try {
+    const worker = fileURLToPath(new URL("./self-update-worker.mjs", import.meta.url));
+    spawn(process.execPath, [worker, version, installDir(version)], { detached: true, stdio: "ignore", windowsHide: true }).unref();
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * One line for a person (never on stdout, never in `nomac mcp`): a newer CLI is out. Said when
+ * this CLI will not install it itself (NOMAC_NO_AUTO_UPDATE=1), at most once a day.
+ */
+export function updateNotice(state = readState(), now = Date.now()) {
+  if (!state.latest || !newer(state.latest, CLI_VERSION)) return undefined;
+  if (!autoUpdateOff()) return undefined;
+  if (state.noticed_at && now - Date.parse(state.noticed_at) < NOTICE_MS) return undefined;
+  writeState({ ...state, noticed_at: new Date(now).toISOString() });
+  return `NoMac CLI ${state.latest} is out (this is ${CLI_VERSION}): npm install -g @nomac/cli@latest, or run nomac update.`;
+}
+
+/** Removes installed versions older than keep's predecessor (one older version stays for running commands). */
+export function pruneInstalls(keep) {
+  const versions = installedVersions().filter(v => v !== keep).sort((a, b) => (newer(a, b) ? -1 : 1));
+  for (const old of versions.slice(1)) { try { rmSync(installDir(old), { recursive: true, force: true }); } catch { /* in use: next time */ } }
+}

package/src/session-ssh.mjs

@@ -3,8 +3,8 @@ 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";
+import { cliEntry } from "./ssh-config.mjs";
 
 export const shellQuote = (value) => `'${String(value).replaceAll("'", "'\\''")}'`;
 
@@ -51,7 +51,7 @@ export function sshArgs(session, { batch = true } = {}) {
   }
   return [
     ...(session.mode === "hosted" ? ["-F", "/dev/null", "-o", `UserKnownHostsFile=${session.knownHosts}`, "-o", "GlobalKnownHostsFile=/dev/null",
-      "-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", `HostKeyAlias=nomac-${session.id}`, "-o", `ProxyCommand=${[process.execPath, cliEntry(), "tunnel", session.id].map(shellQuote).join(" ")}`] : []),
     "-o", "StrictHostKeyChecking=yes", "-o", "ForwardAgent=no",
     "-o", "ConnectTimeout=15", "-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=3",
     ...multiplexArgs(session),

package/src/ssh-config.mjs

@@ -5,6 +5,12 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CliError } from "./api.mjs";
 
+/**
+ * The nomac this person installed: a CLI that a newer installed one runs on its behalf names the
+ * original (self-update.mjs), so a ProxyCommand outlives the next update.
+ */
+export const cliEntry = () => process.env.NOMAC_CLI_ENTRY ?? fileURLToPath(new URL("../bin/nomac.mjs", import.meta.url));
+
 /**
  * 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,
@@ -28,7 +34,7 @@ export function sshConfigPaths(home = homedir()) {
 }
 
 /** 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)) } = {}) {
+export function sshConfigBlock(local, alias, project, { platform = process.platform, node = process.execPath, bin = cliEntry() } = {}) {
   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 [

package/src/update-command.mjs

@@ -0,0 +1,35 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { CliError } from "./api.mjs";
+import { CLI_VERSION } from "./client-info.mjs";
+import { installDir, installedVersions, newer, rememberLatest } from "./self-update.mjs";
+
+const HELP = `Usage: nomac update [--check]
+  Install the newest NoMac CLI now. nomac also does this by itself in the background
+  (NOMAC_NO_AUTO_UPDATE=1 turns that off) and uses it from the next command.
+  --check   only say whether a newer one is out`;
+
+/** The newest @nomac/cli on npm. */
+async function latestOnNpm() {
+  const response = await fetch("https://registry.npmjs.org/@nomac%2fcli/latest", { headers: { accept: "application/json" } }).catch(() => undefined);
+  const version = response?.ok ? (await response.json().catch(() => ({}))).version : undefined;
+  if (typeof version !== "string" || !/^\d+\.\d+\.\d+$/.test(version)) throw new CliError("npm unreachable", "Could not reach npm to look up the newest NoMac CLI. Try again, or run npm install -g @nomac/cli@latest.");
+  return version;
+}
+
+export async function updateCommand(args) {
+  if (args.some(arg => arg === "--help" || arg === "-h")) return console.log(HELP);
+  if (args.some(arg => arg !== "--check")) throw new CliError("update usage", HELP);
+  const latest = await latestOnNpm();
+  rememberLatest(latest);
+  const running = process.env.NOMAC_CLI_DELEGATED ? `${CLI_VERSION} (installed by nomac; your own install is ${process.env.NOMAC_CLI_DELEGATED})` : CLI_VERSION;
+  if (!newer(latest, CLI_VERSION)) return console.log(`NoMac CLI ${running} is the newest.`);
+  if (args.includes("--check")) return console.log(`NoMac CLI ${latest} is out (this is ${running}). Install it: nomac update`);
+  if (!installedVersions().includes(latest)) {
+    console.error(`Installing NoMac CLI ${latest}…`);
+    const worker = fileURLToPath(new URL("./self-update-worker.mjs", import.meta.url));
+    const run = spawnSync(process.execPath, [worker, latest, installDir(latest)], { stdio: "inherit" });
+    if (run.status !== 0) throw new CliError("update failed", `Could not install NoMac CLI ${latest} with npm. Run npm install -g @nomac/cli@latest instead.`);
+  }
+  console.log(`NoMac CLI ${latest} is installed; nomac uses it from your next command. To update your own install too: npm install -g @nomac/cli@latest`);
+}