@yawlabs/tailscale-mcp 0.21.1 → 0.22.0

package/README.md

@@ -48,7 +48,7 @@ Fair critique from Reddit: a new repo claiming "actively maintained" with no vis
 - **1900+ tests** (`node --test`) covering every tool's input validation, API shape, and error handling. Run `npm test` to see them pass locally.
 - **Local release flow** via [`release.sh`](./release.sh): lint + test + bump + tag + push + npm publish + MCP Registry publish, all from the workstation. No CI workflow to babysit.
 - **Dependabot alerts** surface on this repo and get fixed, not ignored.
-- **Every tool verified against the live API.** If it's in the tool list, it calls a real endpoint that exists in the current v2 API. No placeholder 404 tools.
+- **Every tool names a real endpoint from the OpenAPI spec.** If it's in the tool list, it calls a path documented in the current v2 API -- no placeholder 404 tools. To be clear about the limits of that: no recorded live exchange ships with this repo (`fixtures/live/` is empty on purpose), and no claim here rests on an observation against a live tailnet.
 
 Issues and PRs are triaged. File one if something is off — [github.com/YawLabs/tailscale-mcp/issues](https://github.com/YawLabs/tailscale-mcp/issues).
 
@@ -138,6 +138,8 @@ That's it. Now ask your agent:
 - **`core`** (52 tools) — adds `acl`, `dns`, `keys`, `users`. The day-to-day admin surface.
 - **`full`** (97 tools, default) — everything. Same as omitting the env var.
 
+Profile names are case-insensitive and ignore surrounding whitespace (`Core` selects `core`). The group names in `TAILSCALE_TOOLS` and `TAILSCALE_WRITE_GROUPS` are case-sensitive.
+
 ### Option 2: `TAILSCALE_TOOLS` (explicit group list)
 
 ```json
@@ -730,26 +732,30 @@ This shows a read-only banner in the Tailscale Admin Console pointing to your re
 
 ## Running on oam.js (optional)
 
-[oam.js](https://oamjs.org) runs this server unmodified, and the `tailscale-mcp` command only ever uses the **latest oam release, currently 0.15.2**. Verified against oam 0.15.2: full MCP handshake, all 97 admin-API tools plus `tailscale_tool_groups`, all 4 resources, identical error responses, and a clean stdout protocol stream — from the shipped bundle *and* straight from the TypeScript source with no build step.
+[oam.js](https://oamjs.org) runs this server unmodified, and the `tailscale-mcp` command only ever uses the **latest oam release, currently 0.18.0**. Verified against the published oam 0.18.0: full MCP handshake, all 97 admin-API tools plus `tailscale_tool_groups`, all 4 resources, identical error responses, and a clean stdout protocol stream — from the shipped bundle *and* straight from the TypeScript source with no build step.
 
-**oam 0.15.2 is the minimum.** A floor matters here: releases before 0.9.0 ran `child_process.execFile` arguments through a shell, re-splitting them on whitespace and executing shell metacharacters inside an argument, and this server shells out to the `tailscale` binary across its local-CLI tools, so that was a reachable bug rather than a theoretical one.
+**oam 0.18.0 is the minimum.** A floor matters here: releases before 0.9.0 ran `child_process.execFile` arguments through a shell, re-splitting them on whitespace and executing shell metacharacters inside an argument, and this server shells out to the `tailscale` binary across its local-CLI tools, so that was a reachable bug rather than a theoretical one.
 
 How the `tailscale-mcp` command (`bin/tailscale-mcp.mjs`) picks a runtime:
 
-- **`TAILSCALE_MCP_RUNTIME=auto`** (the default) — if a client already launched it with `oam run` on oam 0.15.2 or newer, the server runs in that process. Otherwise it uses `OAM_BIN` when that is 0.15.2 or newer, else asks every oam binary it can find — `%LOCALAPPDATA%\oam\bin` then `~/.oam/bin` on Windows, `~/.oam/bin` elsewhere, then `PATH` — for its version and uses the newest at or above the floor (on a tie the installed copy wins). With none, it runs on Node. An oam host older than 0.15.2 never serves the server itself: it hands off to the newest usable oam, or to Node on `PATH`, or exits with an error when there is neither. Whenever it looks for an oam, stderr names an `OAM_BIN` that was passed over and why; the oam binaries it found and passed over are named, each with its reason, only when no usable oam turns up.
-- **`TAILSCALE_MCP_RUNTIME=oam`** — the same, but exit with an error instead of falling back to Node.
+- **`TAILSCALE_MCP_RUNTIME=auto`** (the default) — if a client already launched it with `oam run` on oam 0.18.0 or newer, the server runs in that process. Otherwise it uses `OAM_BIN` when that is 0.18.0 or newer, else asks every oam binary it can find — `OAM_INSTALL_DIR` when that is set, then `%LOCALAPPDATA%\oam\bin` and `~/.oam/bin` on Windows, `~/.oam/bin` elsewhere, then `PATH` — for its version and uses the newest at or above the floor (on a tie the installed copy wins). With none, it runs on Node. An oam host older than 0.18.0 never serves the server itself: it hands off to the newest usable oam, or to Node on `PATH`, or exits with an error when there is neither. Whenever it looks for an oam, stderr names an `OAM_BIN` that was passed over and why; the oam binaries it found and passed over are named, each with its reason, only when no usable oam turns up.
+- **`TAILSCALE_MCP_RUNTIME=oam`** — the same, but exit with an error instead of falling back to Node. The error names the remedy for what it actually found: `oam self-update` for an oam older than the floor, a check of the binary for one that would not run, and installing oam only when none was found (and on linux-arm64, which oam publishes no build for, not even then).
 - **`TAILSCALE_MCP_RUNTIME=node`** — always Node: in-process under `npx`, handed off to Node on `PATH` when a client launches the command with `oam run`.
 
 The value is case-insensitive; anything else is warned about on stderr and treated as `auto`. On Windows only `oam.exe` counts: an `oam.cmd` / `oam.bat` shim is never run, and it is named on stderr only when no usable oam turns up.
 
 ### Sandboxing (opt-in)
 
-Set `TAILSCALE_MCP_SANDBOX=1` to run under oam's `--permission` model: network restricted to `api.tailscale.com` -- the only host the bundle contacts, including the OAuth token exchange -- and filesystem denied. Child-process stays granted because the local-CLI tools shell out to the `tailscale` binary, which is also why `PATH` remains in the environment allow-list.
+Set `TAILSCALE_MCP_SANDBOX=1` to run under oam's `--permission` model: network restricted to `api.tailscale.com:443` -- the only host the bundle contacts, including the OAuth token exchange, and every request is HTTPS -- and filesystem denied. Child-process stays granted because the local-CLI tools shell out to the `tailscale` binary. That child inherits the server's environment, which under the sandbox holds only the granted variables, so besides the `TAILSCALE_*` settings the allow-list carries `PATH` (to find the binary) and the variables a Windows program needs to start -- `SYSTEMROOT`, `WINDIR`, `SYSTEMDRIVE`, `TEMP`/`TMP`, `USERPROFILE`, `HOMEDRIVE`/`HOMEPATH`, `APPDATA`, `LOCALAPPDATA` -- plus `HOME`. oam takes even the variables Windows adds to every child from that filtered environment, so without them the CLI started with no `SYSTEMROOT`. oam matches these names exactly, case included, so on Windows the launcher also grants each one in the spelling your environment uses (`Path`, `SystemRoot`, `SystemDrive`, `windir` when a client inherits them from Explorer).
+
+Under the sandbox, `TAILSCALE_BINARY` must point at the native `tailscale` CLI, not at a Node-based wrapper script: oam hands its permission flags to every child through `NODE_OPTIONS`, as Node does, and Node refuses `--allow-net` and `--allow-env` there and exits before running anything. The native CLI ignores the variable.
 
 It is opt-in rather than default because a wrong grant does not fail loudly. oam denies a non-granted environment variable by making it **absent** from `process.env` rather than throwing, so an under-granted `TAILSCALE_API_KEY` reads as "unauthenticated" rather than "denied". The env allow-list in the launcher is derived from what the shipped bundle actually reads -- if you add a new `process.env` lookup, extend that list with it.
 
 The sandbox is applied by the `tailscale-mcp` command, which spawns a fresh oam for it -- even when a client launched the command with `oam run` -- because `--permission` is a process-level flag. If it finds no usable oam to spawn, `TAILSCALE_MCP_RUNTIME=auto` still starts the server, without the sandbox; set `TAILSCALE_MCP_RUNTIME=oam` to make that an error. `TAILSCALE_MCP_RUNTIME=node` runs on Node, so it never applies the sandbox.
 
+The sandbox applies to the CLI subcommands too, and with the filesystem denied `tailscale-mcp validate-acl <file>` / `deploy-acl <file>` cannot read the policy file. Unset `TAILSCALE_MCP_SANDBOX` for those commands -- for example, if you export it in a shell profile for the server, run `TAILSCALE_MCP_SANDBOX= tailscale-mcp validate-acl policy.hujson`.
+
 ```jsonc
 {
   "mcpServers": {
@@ -761,14 +767,14 @@ The sandbox is applied by the `tailscale-mcp` command, which spawns a fresh oam
 }
 ```
 
-**Measure startup on your own hardware.** An MCP client cold-starts this server once per session, so startup is the cost that actually gets paid, and on the machine this was measured on node won it — 437ms vs 1554ms for `oam run` over 10 warmed runs (an earlier 5-run round showed 326ms vs 427ms; the box was busy, so treat the magnitude as noisy and the direction as the finding). Those runs used an oam that predates the 0.15.2 floor and have not been repeated since, so do not read them as a current ranking.
+**Measure startup on your own hardware.** An MCP client cold-starts this server once per session, so startup is the cost that actually gets paid, and on the machine this was measured on node won it — 437ms vs 1554ms for `oam run` over 10 warmed runs (an earlier 5-run round showed 326ms vs 427ms; the box was busy, so treat the magnitude as noisy and the direction as the finding). Those runs used an oam that predates the 0.18.0 floor and have not been repeated since, so do not read them as a current ranking.
 
 The published `tailscale-mcp` command prefers the newest usable oam it finds (see above). Without oam that costs almost nothing: discovery is file-existence checks only, never a subprocess, and the fallback runs the server inside the Node process npm already started. With oam installed, though, the command boots Node, runs `--version` on every oam binary it found to pick the newest, and only then boots oam, so it is always slower than pointing your client at a runtime directly — the config above for oam, `node /path/to/tailscale-mcp/dist/index.js` for Node. `TAILSCALE_MCP_RUNTIME=node` skips oam entirely.
 
 Two places oam *does* win for this repo, both opt-in and neither touching the npm package:
 
 - **`npm run check:oam`** — type-checks via `oam check` (tsgo, TypeScript 7 native). Measured 4015ms against 7680ms for `tsc --noEmit`, same clean result. `npx tsc --noEmit` remains the portable default.
-- **`npm run build:binary:oam`** — builds the standalone binary via `oam compile` instead of Node SEA. Measured ~57.7 MB against ~73.6 MB for the Node SEA carrier *before* its blob is injected. Writes to the same `bin/<platform>-<arch>/` path as `npm run build:binary`, so the release staging script consumes either unchanged — run one or the other. If you redistribute that binary it embeds oam's runtime, so ship oam's `LICENSE`, `NOTICE` and `THIRD_PARTY_LICENSES.md` with it.
+- **`npm run build:binary:oam`** — builds the standalone binary via `oam compile` instead of Node SEA. Measured ~57.7 MB against ~73.6 MB for the Node SEA carrier *before* its blob is injected. Writes `bin/<platform>-<arch>/` (or `bin/$TAILSCALE_MCP_BINARY_TARGET/` for a cross-build), while `npm run build:binary` adds a `-glibc` / `-musl` suffix on Linux; `scripts/stage-release-asset.mjs` looks in both and stages the newer build — run one or the other per target. If you redistribute that binary it embeds oam's runtime, so ship oam's `LICENSE`, `NOTICE` and `THIRD_PARTY_LICENSES.md` with it. A cross-build (`TAILSCALE_MCP_BINARY_TARGET=<platform>-<arch>`) downloads the target's oam release binary as its carrier and checks it against the release's signed `RELEASE-MANIFEST`, verified with `ssh-keygen -Y verify` (OpenSSH 8.1+) against oam's release keys in `scripts/oam-release-keys/`; it aborts when the signature, the manifest or the checksum does not check out. An `OAM_VERSION` older than v0.18.0, released before oam signed its releases, is checked against its `SHA256SUMS` only once that file matches the digest pinned for the tag in `scripts/oam-release-keys/presigning-sums`.
 
 The source stays runtime-agnostic on purpose: no `oam:` imports anywhere, and tests stay on `node:test`. That is what keeps the Node fallback real rather than nominal. Note that any `oam` invocation writes a bytecode cache to `oam/` in the working directory — already in `.gitignore`.
 

package/bin/tailscale-mcp.mjs

@@ -72,18 +72,32 @@
  * back. A Node host runs the server in-process, and so does an oam host at the
  * floor -- which only reaches discovery for the sandbox -- so under
  * TAILSCALE_MCP_SANDBOX=1 that fallback serves WITHOUT `--permission`, and
- * nothing on stderr mentions the sandbox. A host below the floor hands off to
- * Node instead, which has no `--permission` to apply either. Pair the sandbox
- * with TAILSCALE_MCP_RUNTIME=oam to make a sandbox that cannot be applied fatal.
+ * runInProcess() now says exactly that on stderr: the sandbox was requested but
+ * is NOT active, rather than the silence that used to hide the downgrade. A host
+ * below the floor hands off to Node instead, which has no `--permission` to
+ * apply either. Pair the sandbox with TAILSCALE_MCP_RUNTIME=oam to make a
+ * sandbox that cannot be applied fatal.
  *
  * THE `--permission` SANDBOX (opt-in)
  * `TAILSCALE_MCP_SANDBOX=1` runs the server under oam's permission model:
- * network limited to the one host the bundle actually calls
- * (api.tailscale.com), filesystem denied.
+ * network limited to the one host and port the bundle actually calls
+ * (api.tailscale.com:443), filesystem denied.
  *
  * Child-process is granted unconditionally because the local-CLI tools shell out
  * to the `tailscale` binary; that is also why PATH stays in the env grant, since
- * resolving the binary needs it.
+ * resolving the binary needs it. The CLI is spawned without an `env` option, so
+ * it inherits the server's process.env -- which under a list `--allow-env` holds
+ * ONLY the granted variables. oam also takes the variables libuv adds to a
+ * Windows child (SYSTEMROOT, TEMP, USERPROFILE, ...) from that filtered
+ * process.env rather than from the real environment, so the grant names them
+ * too: without SYSTEMROOT a Windows child cannot even start Winsock. oam
+ * matches a grant case-sensitively, so on Windows each name is granted in the
+ * environment's own spelling as well (SystemRoot, Path, windir).
+ *
+ * Under the sandbox TAILSCALE_BINARY must name the native `tailscale` CLI, not
+ * a Node-based wrapper script. oam passes its permission flags on to every
+ * child through NODE_OPTIONS, as Node does, and Node refuses `--allow-net` and
+ * `--allow-env` there (exit 9); the native CLI ignores the variable.
  *
  * Opt-in, not default, because a denied environment variable is ABSENT from
  * process.env rather than throwing -- an under-granted TAILSCALE_API_KEY reads as
@@ -91,7 +105,7 @@
  * shipped bundle; keep it in step.
  *
  * MINIMUM OAM VERSION
- * The latest oam release, 0.15.2 -- bump OAM_MIN when oam ships a newer one.
+ * The latest oam release, 0.18.0 -- bump OAM_MIN when oam ships a newer one.
  * Only the current oam is used and verified; an older one is passed over for a
  * newer oam, or for Node. The floor is not cosmetic: before 0.9.0
  * `child_process.execFile` ran its arguments through a SHELL, `exec` accepted
@@ -118,13 +132,13 @@
  */
 
 import { execFileSync, spawn } from "node:child_process";
-import { existsSync, realpathSync } from "node:fs";
+import { existsSync, realpathSync, writeSync } from "node:fs";
 import { constants, homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /** The latest oam release, and the oldest one used. See MINIMUM OAM VERSION above. */
-const OAM_MIN = [0, 15, 2];
+const OAM_MIN = [0, 18, 0];
 
 /**
  * The oldest Node this package supports, matching package.json `engines.node`.
@@ -140,8 +154,16 @@ const NODE_MIN = [20, 11, 0];
 /**
  * Bound on each `oam --version` probe. A healthy oam answers in milliseconds;
  * the bound only exists so a wedged binary on PATH cannot hang the launch.
+ *
+ * 30s, not 5s: the probe runs whatever binary is named, and on Windows that
+ * can be Node itself (the test suite passes the Node running it) -- spawning
+ * node measured 2.4-4.2s on a loaded box and blew a 5s cap often enough that
+ * the probe returned null on a perfectly healthy binary. A wrong null here is
+ * worse than a slow one: it flips chooseOam() off the override and the launcher
+ * takes a different branch entirely (discovery serves in-process instead of
+ * spawning). 30s still bounds a genuinely wedged binary.
  */
-const VERSION_PROBE_TIMEOUT_MS = 5_000;
+const VERSION_PROBE_TIMEOUT_MS = 30_000;
 
 // Two forms, deliberately. `import()` on Windows REJECTS a bare `C:\...` path
 // with ERR_UNSUPPORTED_ESM_URL_SCHEME (it reads `c:` as a protocol), so the
@@ -172,7 +194,10 @@ function pathKey(p) {
  * underneath running processes; OAM_BIN remains the way to point deliberately
  * at a dev build. Both forms are checked on Windows: the installer defaults to
  * %LOCALAPPDATA%\oam\bin there, but oam's docs name ~/.oam/bin first and
- * OAM_INSTALL_DIR can pick either.
+ * OAM_INSTALL_DIR can pick either. OAM_INSTALL_DIR itself, when set, is searched
+ * first of all: it is where oam's installer and `oam self-update` put the
+ * binary, so an oam installed to a custom directory and left off PATH is still
+ * found.
  *
  * PATH is walked manually rather than by spawning `which`/`where`, which would
  * cost a subprocess on every launch just to decide whether to spawn.
@@ -188,6 +213,7 @@ function discoverOamPaths() {
   if (isWin) {
     installed.unshift(join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "oam", "bin", exe));
   }
+  if (process.env.OAM_INSTALL_DIR) installed.unshift(join(process.env.OAM_INSTALL_DIR, exe));
   const onPath = (process.env.PATH ?? "")
     .split(delimiter)
     .filter(Boolean)
@@ -334,7 +360,11 @@ function fallbackInProcess(hostOam) {
  * not after it. `oam run --permission file.js` is rejected outright, which is a
  * good failure but only because it is loud -- ordering here is load-bearing.
  *
- * Net grants prefix-match `host` for fetch and `host:port` for sockets.
+ * Net grants, since oam 0.18.0 (the floor): an entry without a port admits that
+ * host on every port, and a `host:port` entry admits that port alone -- for
+ * fetch and https.request exactly as for sockets. Up to 0.17.1 a port-scoped
+ * entry admitted no HTTP request at all, which is why this used to be a bare
+ * host.
  * A denied environment variable is ABSENT from process.env rather than throwing,
  * so the env list below is derived from what the bundle actually reads; trimming
  * it produces silent misbehaviour, not a clear denial.
@@ -350,8 +380,10 @@ function sandboxFlags() {
   // An unused grant is the one kind of over-permission nothing ever surfaces:
   // removing it cannot break a call that was never made, and keeping it widens
   // the sandbox for no behaviour. launcher.test.ts pins this list exactly so a
-  // future host lands as a reviewed diff rather than a quiet widening.
-  const hosts = ["api.tailscale.com"];
+  // future host lands as a reviewed diff rather than a quiet widening. Scoped
+  // to :443 for the same reason: every request is https://, so no other port is
+  // ever dialled, and an http:// URL or a redirect to another port is refused.
+  const hosts = ["api.tailscale.com:443"];
 
   const netFlag = `--allow-net=${hosts.join(",")}`;
 
@@ -361,8 +393,25 @@ function sandboxFlags() {
   // meant the local-CLI tool group silently failed to register under the
   // sandbox even though --allow-child-process is granted below precisely so
   // those tools can shell out.
+  //
+  // The non-TAILSCALE_ names besides PATH are for the CLI child, not the server:
+  // see THE `--permission` SANDBOX above. HOMEDRIVE, HOMEPATH, SYSTEMDRIVE,
+  // SYSTEMROOT, TEMP, USERPROFILE and WINDIR are libuv's Windows set (measured on
+  // oam 0.18.0: a child under `--allow-env=PATH,...` got neither SYSTEMROOT nor
+  // TEMP), TMP its POSIX-style twin, APPDATA and LOCALAPPDATA where Windows
+  // programs keep per-user state, and HOME the POSIX home directory. Granting a
+  // name that is not set is harmless: it stays absent. WSL_DISTRO_NAME is the
+  // server's own: local-cli.ts reads it to recognise WSL when the CLI is
+  // missing, and its fallback, /proc/version, is a file read the sandbox denies.
   const env = [
+    "APPDATA",
+    "HOME",
+    "HOMEDRIVE",
+    "HOMEPATH",
+    "LOCALAPPDATA",
     "PATH",
+    "SYSTEMDRIVE",
+    "SYSTEMROOT",
     "TAILSCALE_API_KEY",
     "TAILSCALE_BINARY",
     "TAILSCALE_DEBUG",
@@ -381,9 +430,30 @@ function sandboxFlags() {
     "TAILSCALE_TAILNET",
     "TAILSCALE_TOOLS",
     "TAILSCALE_WRITE_GROUPS",
+    "TEMP",
+    "TMP",
+    "USERPROFILE",
+    "WINDIR",
+    "WSL_DISTRO_NAME",
   ];
 
-  const flags = ["--permission", netFlag, `--allow-env=${env.join(",")}`];
+  // On Windows each name is ALSO granted in the case this process holds it.
+  // oam compares an env grant with the variable's name exactly, case and all,
+  // but Windows keeps its own spellings -- `Path`, `SystemRoot`, `SystemDrive`,
+  // `windir` -- in the environment a client launched from Explorer passes on,
+  // and `SYSTEMROOT` does not admit `SystemRoot` (measured on oam 0.18.0: with
+  // those spellings and the upper-case grant, neither the server nor the CLI
+  // child got Path or SystemRoot). A shell that upper-cases them, as Git Bash
+  // does, hides this. Only a case variant of a name already listed is added.
+  const granted = [...env];
+  if (process.platform === "win32") {
+    for (const name of Object.keys(process.env)) {
+      const upper = name.toUpperCase();
+      if (name !== upper && env.includes(upper) && !granted.includes(name)) granted.push(name);
+    }
+  }
+
+  const flags = ["--permission", netFlag, `--allow-env=${granted.join(",")}`];
   flags.push("--allow-child-process");
   return flags;
 }
@@ -398,8 +468,7 @@ function sandboxFlags() {
  * stderr turns out to be unusable give up quietly -- failing to print a
  * diagnostic is not worth crashing a stdio server over.
  */
-async function errSync(message) {
-  const { writeSync } = await import("node:fs");
+function errSync(message) {
   const buf = Buffer.from(message);
   let off = 0;
   for (let attempts = 0; off < buf.length && attempts < 1000; attempts++) {
@@ -457,20 +526,30 @@ function unusableReason(path, version, label = path) {
 
 /**
  * Choose the oam to spawn: a usable OAM_BIN, else the newest usable discovered
- * binary. Returns the choice (or null) plus stderr notes: `overrideNote` about
- * an unusable OAM_BIN, and `skipped` describing what was found and rejected
- * when nothing was usable.
+ * binary. Returns the choice (or null) plus what stderr needs:
+ *   overrideNote     why OAM_BIN was passed over, or null
+ *   skipped          why each discovered binary was passed over, when none was
+ *                    chosen
+ *   passedOver       the `version` of every existing binary rejected (OAM_BIN
+ *                    included), so a hard failure can name the right remedy
+ *   overrideMissing  OAM_BIN was set to a path that does not exist
  */
 function chooseOam() {
   const override = process.env.OAM_BIN;
   let overrideNote = null;
+  let overrideMissing = false;
+  const passedOver = [];
   if (override) {
     if (!existsSync(override)) {
       overrideNote = `OAM_BIN=${override} does not exist`;
+      overrideMissing = true;
     } else {
       const version = oamVersion(override);
-      if (atLeast(version, OAM_MIN)) return { chosen: { path: override, version }, overrideNote, skipped: [] };
+      if (atLeast(version, OAM_MIN)) {
+        return { chosen: { path: override, version }, overrideNote, skipped: [], passedOver, overrideMissing };
+      }
       overrideNote = unusableReason(override, version, `OAM_BIN=${override}`);
+      passedOver.push(version);
     }
   }
   const overrideKey = override ? pathKey(override) : null;
@@ -479,11 +558,91 @@ function chooseOam() {
     .map((path) => ({ path, version: oamVersion(path) }));
   const chosen = pickNewest(candidates);
   const skipped = chosen ? [] : candidates.map((c) => unusableReason(c.path, c.version));
-  return { chosen, overrideNote, skipped };
+  if (!chosen) passedOver.push(...candidates.map((c) => c.version));
+  return { chosen, overrideNote, skipped, passedOver, overrideMissing };
+}
+
+/**
+ * What would fix "no usable oam", one line per cause that was actually seen.
+ *
+ * An oam that reported an old version needs `oam self-update`; one that would
+ * not run at all needs checking, and self-update will not help it; a missing
+ * OAM_BIN needs pointing somewhere real. Only when nothing at all was found is
+ * installing oam the remedy -- and not even then on a platform oam publishes no
+ * build for (there is no linux-arm64 asset), where it would send the user after
+ * a download that does not exist.
+ *
+ * Pure, with the platform passed in, so launcher.test.ts can exercise every
+ * branch on any host.
+ */
+function remedyFor({ passedOver, overrideMissing, shim, platform, arch }) {
+  const lines = [];
+  if (passedOver.some((v) => v !== null)) {
+    lines.push(`Run \`oam self-update\` to get oam ${OAM_MIN.join(".")} or newer.\n`);
+  }
+  if (passedOver.some((v) => v === null)) {
+    lines.push("Check that it is an executable oam binary for this platform.\n");
+  }
+  if (overrideMissing) lines.push("Point OAM_BIN at an existing oam binary, or unset it.\n");
+  if (lines.length === 0 && !shim) {
+    lines.push(
+      platform === "linux" && arch !== "x64"
+        ? `oam publishes no build for linux-${arch}, so there is nothing to install here; set OAM_BIN=/path/to/oam if you built one yourself.\n`
+        : "Install oam from https://oamjs.org, or set OAM_BIN=/path/to/oam.\n",
+    );
+  }
+  lines.push("Or use TAILSCALE_MCP_RUNTIME=node to run on Node.\n");
+  return lines.join("");
+}
+
+/**
+ * The environment a Node handoff gets: `env` itself, or -- when THIS process is
+ * oam and its NODE_OPTIONS carries permission-model flags -- a copy without
+ * them.
+ *
+ * oam passes `--permission` and every `--allow-*` flag on to its children
+ * through NODE_OPTIONS, as Node does, and a grandchild of a sandboxed oam
+ * inherits them in the variable itself. oam reads them back from there, but
+ * Node refuses `--allow-net` and `--allow-env` in NODE_OPTIONS and exits 9
+ * before running a line (measured on Node 22.22.2: "--allow-net= is not allowed
+ * in NODE_OPTIONS"), so a handoff to Node would die without a word from the
+ * server. Every other token is kept, in order.
+ *
+ * What this cannot reach: flags oam was given on its own command line
+ * (`oam --permission --allow-net=... run`) are appended to the child's
+ * NODE_OPTIONS by oam at the spawn, from process.execArgv, whatever `env`
+ * says. Node has no `--allow-net` to honour, so a sandboxed oam host has no way
+ * to hand the server to Node intact; it only gets there under
+ * TAILSCALE_MCP_RUNTIME=node or below the floor.
+ *
+ * Pure, taking `hostOam` rather than reading process.versions, so
+ * launcher.test.ts can exercise it like runtimePlan().
+ */
+function nodeHandoffEnv(env, hostOam) {
+  if (hostOam === undefined || !env.NODE_OPTIONS) return env;
+  const tokens = env.NODE_OPTIONS.split(/\s+/).filter(Boolean);
+  const kept = tokens.filter((token) => !/^--(?:permission|allow-[a-z-]+)(?:=|$)/.test(token));
+  if (kept.length === tokens.length) return env;
+  const copy = { ...env };
+  if (kept.length > 0) copy.NODE_OPTIONS = kept.join(" ");
+  else delete copy.NODE_OPTIONS;
+  return copy;
 }
 
 /** Run the server in THIS process. The zero-overhead fallback. */
 async function runInProcess() {
+  // Every route into this function is a path that CANNOT carry --permission:
+  // the sandbox is a process-level flag only a FRESH oam spawn applies (see
+  // THE `--permission` SANDBOX above). The note lives here rather than at each
+  // call site because in-process serve is exactly what this function is, so
+  // neither the spawn path nor a handOffToNode can print it while every silent
+  // downgrade -- fallBack's branch, plan === "in-process", the no-oam fallback
+  // at ~763 when it lands here -- is covered by one emission.
+  if (sandbox.length > 0) {
+    await errSync(
+      `tailscale-mcp: TAILSCALE_MCP_SANDBOX=1 requested, but the server is serving in-process where --permission cannot be applied -- the sandbox is NOT active. Pair it with TAILSCALE_MCP_RUNTIME=oam to make this failure fatal.\n`,
+    );
+  }
   // A server may gate its bootstrap on being the process ENTRY POINT --
   // `import.meta.url === pathToFileURL(process.argv[1]).href` -- so that its own
   // test file can import the module for unit tests without connecting a stdio
@@ -512,9 +671,10 @@ const fallbackFailed = (e) => {
  *
  * `onLaunchFailed(err)` runs when the child could not be started at all; it is
  * never called once the child is running, which would double-start the server
- * on the same stdio.
+ * on the same stdio. `env` is the child's whole environment; a Node handoff
+ * passes nodeHandoffEnv()'s.
  */
-async function launchChild(cmd, args, onLaunchFailed) {
+async function launchChild(cmd, args, onLaunchFailed, env = process.env) {
   // Every handoff from an oam host pipes; see ALREADY RUNNING ON OAM. That is a
   // host below the floor, one at the floor spawning a fresh oam for the
   // sandbox, or any oam under TAILSCALE_MCP_RUNTIME=node.
@@ -527,7 +687,7 @@ async function launchChild(cmd, args, onLaunchFailed) {
       // server's shutdown path. Piping preserves both as well: bytes are copied
       // unchanged, and stdin's end propagates to the child.
       stdio: piped ? ["pipe", "pipe", "pipe"] : "inherit",
-      env: process.env,
+      env,
       windowsHide: true,
     });
   } catch (err) {
@@ -641,24 +801,31 @@ async function launchChild(cmd, args, onLaunchFailed) {
  * one below the floor, or any oam under TAILSCALE_MCP_RUNTIME=node -- so there
  * is no in-process option left. An empty `reason` prints no note: the host is a
  * supported oam and TAILSCALE_MCP_RUNTIME=node asked for Node, which is not news.
+ * `mode` is passed in rather than read from the module scope, where it is
+ * declared after this function.
  */
-async function handOffToNode(reason) {
+async function handOffToNode(reason, mode) {
   const node = findNodeOnPath();
   if (!node) {
     const remedy =
       mode === "node"
         ? "Put Node on PATH, or launch this command with node.\n"
         : `Run \`oam self-update\` to get oam ${OAM_MIN.join(".")} or newer, or launch this command with node.\n`;
-    await errSync(
+    errSync(
       `tailscale-mcp: ${reason || `TAILSCALE_MCP_RUNTIME=node on oam ${process.versions.oam}`}, and no Node was found on PATH to run the server.\n${remedy}`,
     );
     process.exit(1);
   }
   if (reason) await errSync(`tailscale-mcp: ${reason}; running on ${node} instead.\n`);
-  await launchChild(node, [SERVER_ENTRY, ...process.argv.slice(2)], async (err) => {
-    await errSync(`tailscale-mcp: failed to launch Node at ${node} (${err?.message ?? err})\n`);
-    process.exit(1);
-  });
+  await launchChild(
+    node,
+    [SERVER_ENTRY, ...process.argv.slice(2)],
+    async (err) => {
+      await errSync(`tailscale-mcp: failed to launch Node at ${node} (${err?.message ?? err})\n`);
+      process.exit(1);
+    },
+    nodeHandoffEnv(process.env, process.versions.oam),
+  );
 }
 
 /** What a fallback serves on, for stderr. */
@@ -667,12 +834,12 @@ function fallbackTarget(hostOam) {
 }
 
 /** No usable oam, or it would not start, under a mode that allows a fallback. */
-async function fallBack(hostOam, why) {
+async function fallBack(hostOam, why, mode) {
   if (fallbackInProcess(hostOam)) {
     await runInProcess();
     return;
   }
-  await handOffToNode(`this process is oam ${hostOam}, older than ${OAM_MIN.join(".")}, and ${why}`);
+  await handOffToNode(`this process is oam ${hostOam}, older than ${OAM_MIN.join(".")}, and ${why}`, mode);
 }
 
 // Before anything else: a Node below the floor cannot be relied on to reach
@@ -681,7 +848,7 @@ async function fallBack(hostOam, why) {
 // deep, and it costs one comparison on every launch.
 const nodeFloorMessage = nodeFloorFailure(process.versions);
 if (nodeFloorMessage) {
-  await errSync(nodeFloorMessage);
+  errSync(nodeFloorMessage);
   process.exit(1);
 }
 
@@ -698,7 +865,7 @@ const mode = (requested ?? "auto").toLowerCase();
 if (requested && !RUNTIMES.includes(mode)) {
   // Echo what was SET, not the lowercased form, so the typo is recognisable in
   // the host's log next to the config line that produced it.
-  await errSync(
+  errSync(
     `tailscale-mcp: unrecognized TAILSCALE_MCP_RUNTIME "${requested}" -- known values: ${RUNTIMES.join(", ")}. Using auto.\n`,
   );
 }
@@ -712,29 +879,34 @@ const sandbox = sandboxFlags();
 const plan = runtimePlan({ mode, hostOam, sandbox: sandbox.length > 0 });
 
 if (plan === "in-process") {
-  await runInProcess();
+  // Same reason as fallbackFailed: a bare rejection here (dist/index.js missing)
+  // would surface as a raw ERR_MODULE_NOT_FOUND stack instead of one line.
+  await runInProcess().catch((e) => {
+    process.stderr.write(`tailscale-mcp: could not load the server (${e?.message ?? e})\n`);
+    process.exitCode = 1;
+  });
 } else if (plan === "handoff-node") {
   const belowFloor = !atLeast(parseVersion(hostOam), OAM_MIN);
-  await handOffToNode(belowFloor ? `this process is oam ${hostOam}, older than ${OAM_MIN.join(".")}` : "");
+  await handOffToNode(belowFloor ? `this process is oam ${hostOam}, older than ${OAM_MIN.join(".")}` : "", mode);
 } else {
-  const { chosen, overrideNote, skipped } = chooseOam();
+  const { chosen, overrideNote, skipped, passedOver, overrideMissing } = chooseOam();
 
   if (chosen) {
     if (overrideNote) {
-      await errSync(`tailscale-mcp: ${overrideNote}; using ${chosen.path} (oam ${chosen.version.join(".")}).\n`);
+      errSync(`tailscale-mcp: ${overrideNote}; using ${chosen.path} (oam ${chosen.version.join(".")}).\n`);
     }
     // The sandbox flags go BEFORE `run` (see sandboxFlags), and `--` separates
     // oam's own flags from the script's argv, so `tailscale-mcp --version` and
     // any host-supplied flags survive the hop unchanged.
     await launchChild(chosen.path, [...sandbox, "run", SERVER_ENTRY, "--", ...process.argv.slice(2)], async (err) => {
       if (mode === "oam") {
-        await errSync(`tailscale-mcp: failed to launch oam at ${chosen.path} (${err?.message ?? err})\n`);
+        errSync(`tailscale-mcp: failed to launch oam at ${chosen.path} (${err?.message ?? err})\n`);
         process.exit(1);
       }
-      await errSync(
+      errSync(
         `tailscale-mcp: failed to launch oam at ${chosen.path} (${err?.message ?? err}); using ${fallbackTarget(hostOam)} instead.\n`,
       );
-      await fallBack(hostOam, "the newer oam would not start");
+      await fallBack(hostOam, "the newer oam would not start", mode);
     });
   } else {
     const shim = findOamShim();
@@ -748,18 +920,18 @@ if (plan === "in-process") {
         : []),
     ];
     if (mode === "oam") {
-      await errSync(
+      errSync(
         `tailscale-mcp: TAILSCALE_MCP_RUNTIME=oam but no usable oam (${OAM_MIN.join(".")} or newer) was found.\n` +
           notes.map((note) => `  ${note}\n`).join("") +
-          "Install or update from https://oamjs.org, set OAM_BIN=/path/to/oam, or use TAILSCALE_MCP_RUNTIME=node.\n",
+          remedyFor({ passedOver, overrideMissing, shim, platform: process.platform, arch: process.arch }),
       );
       process.exit(1);
     }
     // auto: falling back is correct, but silence is how someone never learns
     // their OAM_BIN is wrong or their oam is too old to use.
     if (notes.length > 0) {
-      await errSync(`tailscale-mcp: ${notes.join("; ")}; using ${fallbackTarget(hostOam)} instead.\n`);
+      errSync(`tailscale-mcp: ${notes.join("; ")}; using ${fallbackTarget(hostOam)} instead.\n`);
     }
-    await fallBack(hostOam, "no newer oam was found").catch(fallbackFailed);
+    await fallBack(hostOam, "no newer oam was found", mode).catch(fallbackFailed);
   }
 }