agentroam 0.2.0-preview.8 → 0.2.0-preview.9

package/dist/service/windows-task-service.test.js

@@ -0,0 +1,95 @@
+import { mkdtemp, mkdir, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { resolveServicePaths, writePrivateText } from "./service-files.js";
+import { WindowsTaskService, buildRegisterTaskScript, quoteWindowsCommandLineArgument, resolveWindowsServiceHost, } from "./windows-task-service.js";
+describe("WindowsTaskService", () => {
+    it("registers, stops, starts, and uninstalls a current-user task", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-windows-task-"));
+        const paths = resolveServicePaths(home, resolve(home, "data"));
+        const value = config(home, paths.dataDir);
+        await mkdir(value.roots[0], { recursive: true });
+        let installed = false;
+        let running = false;
+        let processRunning = false;
+        let pid = 800;
+        const scripts = [];
+        const runner = async (command, args) => {
+            expect(command).toBe("powershell.exe");
+            const script = Buffer.from(args.at(-1), "base64").toString("utf16le");
+            scripts.push(script);
+            if (script.includes("Register-ScheduledTask"))
+                installed = true;
+            if (script.includes("Start-ScheduledTask")) {
+                running = true;
+                processRunning = true;
+                pid++;
+                await writePrivateText(paths.statePath, JSON.stringify({
+                    status: "ready", pid, version: value.version, startedAt: "x", updatedAt: "x",
+                    accessUrl: "https://ready.example/web",
+                }));
+                await writePrivateText(paths.urlPath, "https://ready.example/web\n");
+            }
+            if (script.includes("Stop-ScheduledTask")) {
+                running = false;
+                processRunning = false;
+            }
+            if (script.includes("Unregister-ScheduledTask"))
+                installed = false;
+            if (script.includes("Get-ScheduledTask")) {
+                return { code: 0, stdout: JSON.stringify({ installed, running }), stderr: "" };
+            }
+            return { code: 0, stdout: "", stderr: "" };
+        };
+        const service = new WindowsTaskService({
+            homeDir: home,
+            runner,
+            processExists: () => processRunning,
+            validateConfig: async () => undefined,
+            readyTimeoutMs: 50,
+            stopTimeoutMs: 50,
+            pollIntervalMs: 1,
+        });
+        const installedResult = await service.install(value);
+        expect(installedResult.state).toMatchObject({ status: "ready", pid: 801 });
+        expect(installedResult.definition).toBe("AgentRoam");
+        expect(await service.url()).toBe("https://ready.example/web");
+        await service.stop();
+        expect((await service.status()).running).toBe(false);
+        await service.start();
+        expect((await service.status()).running).toBe(true);
+        await writePrivateText(resolve(paths.dataDir, "data/keep.txt"), "keep");
+        await writePrivateText(paths.stdoutPath, "keep logs");
+        const result = await service.uninstall();
+        expect(result).toEqual({ removed: true, preservedDataDir: paths.dataDir });
+        expect(await readFile(resolve(paths.dataDir, "data/keep.txt"), "utf8")).toBe("keep");
+        expect(await readFile(paths.stdoutPath, "utf8")).toBe("keep logs");
+        expect(scripts.some((script) => script.includes("New-ScheduledTaskPrincipal") && script.includes("RunLevel Limited"))).toBe(true);
+        expect(scripts.some((script) => script.includes("cmd.exe") || script.includes("ES_DISPLAY_REQUIRED"))).toBe(false);
+    });
+    it("builds a safely quoted task action for paths with spaces and apostrophes", () => {
+        const value = config("C:\\Users\\O'Brien", "C:\\Users\\O'Brien\\.agentroam");
+        const host = resolveWindowsServiceHost(value.cliPath);
+        const script = buildRegisterTaskScript(value, host, "C:\\Users\\O'Brien\\config.json");
+        expect(host).toBe("C:\\Agent Roam\\node_modules\\agentroam\\dist\\service\\windows-service-host.js");
+        expect(script).toContain("O''Brien");
+        expect(script).toContain("New-ScheduledTaskAction");
+        expect(script).toContain("RestartCount 999");
+        expect(quoteWindowsCommandLineArgument("C:\\path with spaces\\")).toBe('"C:\\path with spaces\\\\"');
+    });
+});
+function config(home, dataDir) {
+    return {
+        version: "0.2.0-preview.9",
+        nodePath: "C:\\Node Runtime\\node.exe",
+        cliPath: "C:\\Agent Roam\\node_modules\\agentroam\\bin\\agentroam.mjs",
+        roots: [resolve(home, "workspace")],
+        port: null,
+        relay: "auto",
+        tunnelCommand: null,
+        localOnly: false,
+        dataDir,
+        installedAt: "2026-09-04T00:00:00.000Z",
+    };
+}

package/dist/tunnel/cloudflare-provider.js

@@ -6,7 +6,7 @@ export class CloudflareTunnelProvider {
         this.executable = executable;
     }
     async start({ localUrl, signal, log }) {
-        const child = spawn(this.executable, ["tunnel", "--no-autoupdate", "--url", localUrl], {
+        const child = spawn(this.executable, buildCloudflaredArguments(localUrl), {
             stdio: ["ignore", "pipe", "pipe"],
             windowsHide: true,
             detached: process.platform !== "win32",
@@ -26,6 +26,9 @@ export class CloudflareTunnelProvider {
         }
     }
 }
+export function buildCloudflaredArguments(localUrl) {
+    return ["tunnel", "--no-autoupdate", "--protocol", "http2", "--url", localUrl];
+}
 export function waitForConnectedUrl(child, log, timeoutMs) {
     return new Promise((resolvePromise, reject) => {
         const buffers = { stdout: "", stderr: "" };

package/dist/tunnel/cloudflare-provider.test.js

@@ -1,7 +1,19 @@
 import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";
 import { describe, expect, it, vi } from "vitest";
-import { waitForConnectedUrl } from "./cloudflare-provider.js";
+import { buildCloudflaredArguments, waitForConnectedUrl } from "./cloudflare-provider.js";
+describe("buildCloudflaredArguments", () => {
+    it("uses HTTP/2 so launchd tunnels do not depend on outbound UDP", () => {
+        expect(buildCloudflaredArguments("http://127.0.0.1:3000")).toEqual([
+            "tunnel",
+            "--no-autoupdate",
+            "--protocol",
+            "http2",
+            "--url",
+            "http://127.0.0.1:3000",
+        ]);
+    });
+});
 describe("waitForConnectedUrl", () => {
     it("waits for both the public URL and a registered tunnel connection", async () => {
         const { child, stderr } = fakeChild();

package/dist/tunnel/public-readiness.js

@@ -22,7 +22,7 @@ export async function waitForPublicReadiness(publicUrl, options = {}) {
             try {
                 const response = await fetchImpl(endpoint, {
                     cache: "no-store",
-                    headers: { "user-agent": "agentroam-readiness/0.2.0-preview.8" },
+                    headers: { "user-agent": "agentroam-readiness/0.2.0-preview.9" },
                     signal: options.signal,
                 });
                 if (response.ok) {

package/dist/tunnel/relay-orchestrator.js

@@ -27,6 +27,10 @@ export async function selectRelay(options) {
                 break;
         }
     }
+    if (options.allowLanFallback === false) {
+        const detail = failures.map(({ provider, message }) => `${provider}: ${message}`).join("; ");
+        throw new Error(`public relay unavailable${detail ? ` (${detail})` : ""}`);
+    }
     return { tunnel: null, publicUrl: options.lanUrl, provider: "lan", failures };
 }
 async function createProvider(name, options) {

package/dist/tunnel/relay-orchestrator.test.js

@@ -27,6 +27,16 @@ describe("selectRelay", () => {
         expect(result.publicUrl).toBe("http://10.0.0.2:43210");
         expect(result.failures).toHaveLength(2);
     });
+    it("fails instead of leaving a background service permanently on LAN", async () => {
+        const cloudflare = fakeProvider("https://bad.trycloudflare.com");
+        const pinggy = fakeProvider("https://bad.run.pinggy-free.link");
+        await expect(selectRelay({
+            ...options("auto", { cloudflare, pinggy }, async () => { throw new Error("blocked"); }),
+            allowLanFallback: false,
+        })).rejects.toThrow("public relay unavailable (cloudflare: blocked; pinggy: blocked)");
+        expect(cloudflare.handle.close).toHaveBeenCalledOnce();
+        expect(pinggy.handle.close).toHaveBeenCalledOnce();
+    });
     it("bypasses every public provider in local-only mode", async () => {
         const cloudflare = fakeProvider("https://unused.trycloudflare.com");
         const result = await selectRelay({ ...options("auto", { cloudflare }), cli: cli("auto", true) });
@@ -50,6 +60,7 @@ function options(relay, providers, readiness = async () => { }) {
 function cli(relay, localOnly = false) {
     return {
         command: "start",
+        serviceAction: null,
         roots: [process.cwd()],
         port: null,
         relay,

package/install/README.md

@@ -0,0 +1,45 @@
+# AgentRoam bootstrap installers
+
+These versioned installers support macOS Apple Silicon and Windows x64. They reuse a visible Node.js 22 installation when available. Otherwise they install the verified private Node.js `22.22.0` runtime under the AgentRoam data directory. They then register and start the current-user AgentRoam background service. They never modify, replace, or uninstall system Node.js or global power settings.
+
+## macOS Apple Silicon
+
+```sh
+curl -fsSL https://gitee.com/caoqu/team-agent/releases/download/v0.2.0-preview.9/install-agentroam.sh | sh
+```
+
+The command installs the wrapper at `~/.local/bin/agentroam`. If that directory is not already in `PATH`, the installer prints the required shell setting without editing shell profiles.
+
+## Windows x64
+
+```powershell
+irm https://gitee.com/caoqu/team-agent/releases/download/v0.2.0-preview.9/install-agentroam.ps1 | iex
+```
+
+The command installs `%USERPROFILE%\.agentroam\bin\agentroam.cmd` and adds only that user directory to the user-level `PATH`. It does not require administrator access or change the machine-level `PATH`.
+
+## Service behavior
+
+Run the installer from the project directory AgentRoam should expose, or set `AGENTROAM_ROOT` explicitly. An installer launched from the home directory without an explicit root stops before service registration so it cannot expose the entire home directory accidentally.
+
+The installer registers and starts the service after Node, CLI, and `doctor` validation. While foreground AgentRoam or the service is running, it prevents idle system sleep but still allows the display to dim and turn off. Lid close, explicit sleep, hibernation, shutdown, and low-battery forced sleep remain controlled by the operating system.
+
+Use the installer for first installation, upgrades, and repair. Use these commands for routine control:
+
+```text
+agentroam service start
+agentroam service stop
+agentroam service restart
+agentroam service status
+agentroam service url
+agentroam service logs
+agentroam service uninstall
+```
+
+## Data and updates
+
+Set `AGENTROAM_DATA_DIR` before running either installer to override the default `~/.agentroam` data directory. Node is stored at `<data-dir>/runtimes/node/22.22.0`, and the launcher is stored at `<data-dir>/launcher/0.2.0-preview.9`.
+
+Each AgentRoam release pins its own Node patch and installer assets. Updates happen only by running a newer versioned installer or installing a newer AgentRoam release; startup never follows a moving Node.js release channel.
+
+To uninstall the wrapper, remove `~/.local/bin/agentroam` on macOS or `%USERPROFILE%\.agentroam\bin\agentroam.cmd` on Windows. The private runtime, launcher, session data, and configuration under the data directory are preserved until explicitly removed by the user.

package/install/install-agentroam.ps1

@@ -0,0 +1,175 @@
+$ErrorActionPreference = "Stop"
+$ProgressPreference = "SilentlyContinue"
+
+$NodeVersion = "22.22.0"
+$AgentRoamVersion = "0.2.0-preview.9"
+$NodeArchive = "node-v22.22.0-win-x64.zip"
+$NodeSha256 = "c97fa376d2becdc8863fcd3ca2dd9a83a9f3468ee7ccf7a6d076ec66a645c77a"
+$NodeUrl = "https://nodejs.org/dist/v22.22.0/$NodeArchive"
+$NpmRegistry = "https://registry.npmjs.org"
+$DataDir = if ($env:AGENTROAM_DATA_DIR) { $env:AGENTROAM_DATA_DIR } else { Join-Path $HOME ".agentroam" }
+$NodeParent = Join-Path $DataDir "runtimes\node"
+$NodeRoot = Join-Path $NodeParent $NodeVersion
+$NodeLock = "$NodeRoot.lock"
+$LauncherParent = Join-Path $DataDir "launcher"
+$LauncherRoot = Join-Path $LauncherParent $AgentRoamVersion
+$LauncherLock = "$LauncherRoot.lock"
+$WrapperDir = Join-Path $HOME ".agentroam\bin"
+$WrapperPath = Join-Path $WrapperDir "agentroam.cmd"
+$ServiceRootExplicit = -not [string]::IsNullOrWhiteSpace($env:AGENTROAM_ROOT)
+$ServiceRoot = if ($ServiceRootExplicit) { $env:AGENTROAM_ROOT } else { (Get-Location).Path }
+if (-not (Test-Path -LiteralPath $ServiceRoot -PathType Container)) { throw "AgentRoam root is not a directory: $ServiceRoot" }
+$ServiceRoot = [System.IO.Path]::GetFullPath($ServiceRoot).TrimEnd([System.IO.Path]::DirectorySeparatorChar)
+$HomeRoot = [System.IO.Path]::GetFullPath($HOME).TrimEnd([System.IO.Path]::DirectorySeparatorChar)
+if (-not $ServiceRootExplicit -and $ServiceRoot -eq $HomeRoot) {
+  throw "Refusing to expose the entire home directory implicitly; run from a project directory or set AGENTROAM_ROOT explicitly"
+}
+
+New-Item -ItemType Directory -Force -Path $NodeParent, $LauncherParent, $WrapperDir | Out-Null
+
+function Test-Node22([string]$NodeBin) {
+  if (-not (Test-Path -LiteralPath $NodeBin -PathType Leaf)) { return $false }
+  try { return (& $NodeBin -p 'process.versions.node.split(".")[0]' 2>$null) -eq "22" } catch { return $false }
+}
+
+function Test-ManagedNode {
+  $NodeBin = Join-Path $NodeRoot "node.exe"
+  $NpmCli = Join-Path $NodeRoot "node_modules\npm\bin\npm-cli.js"
+  if (-not (Test-Path -LiteralPath $NodeBin -PathType Leaf) -or -not (Test-Path -LiteralPath $NpmCli -PathType Leaf)) { return $false }
+  try { return (& $NodeBin --version 2>$null) -eq "v$NodeVersion" } catch { return $false }
+}
+
+function Enter-InstallLock([string]$Path) {
+  $Deadline = [DateTime]::UtcNow.AddMinutes(15)
+  while ($true) {
+    try {
+      $Stream = [System.IO.File]::Open($Path, [System.IO.FileMode]::CreateNew, [System.IO.FileAccess]::Write, [System.IO.FileShare]::None)
+      $Bytes = [Text.Encoding]::UTF8.GetBytes("$PID`n$([DateTime]::UtcNow.ToString('o'))`n")
+      $Stream.Write($Bytes, 0, $Bytes.Length)
+      return $Stream
+    } catch [System.IO.IOException] {
+      if (Test-Path -LiteralPath $Path) {
+        $Age = [DateTime]::UtcNow - (Get-Item -LiteralPath $Path).LastWriteTimeUtc
+        if ($Age.TotalMinutes -gt 15) { Remove-Item -LiteralPath $Path -Force -ErrorAction SilentlyContinue; continue }
+      }
+      if ([DateTime]::UtcNow -ge $Deadline) { throw "Timed out waiting for install lock $Path" }
+      Start-Sleep -Milliseconds 500
+    }
+  }
+}
+
+$SystemNode = Get-Command node.exe -ErrorAction SilentlyContinue
+if ($env:AGENTROAM_BOOTSTRAP_TEST -eq "1" -and $env:AGENTROAM_FORCE_PRIVATE_NODE -eq "1") { $SystemNode = $null }
+if ($SystemNode -and (Test-Node22 $SystemNode.Source)) {
+  $NodeBin = $SystemNode.Source
+} else {
+  if (-not (Test-ManagedNode)) {
+    $NodeLockHandle = Enter-InstallLock $NodeLock
+    try {
+      if (-not (Test-ManagedNode)) {
+        $TempRoot = Join-Path $NodeParent ".node-$NodeVersion-$PID-$([Guid]::NewGuid().ToString('N'))"
+        $ArchivePath = Join-Path $TempRoot $NodeArchive
+        $ExtractPath = Join-Path $TempRoot "extract"
+        New-Item -ItemType Directory -Force -Path $ExtractPath | Out-Null
+        try {
+          Write-Host "Downloading Node.js $NodeVersion..."
+          if ($env:AGENTROAM_NODE_ARCHIVE_FILE) {
+            Copy-Item -LiteralPath $env:AGENTROAM_NODE_ARCHIVE_FILE -Destination $ArchivePath
+          } else {
+            Invoke-WebRequest -UseBasicParsing -TimeoutSec 600 -Uri $NodeUrl -OutFile $ArchivePath
+          }
+          $ActualHash = (Get-FileHash -Algorithm SHA256 -LiteralPath $ArchivePath).Hash.ToLowerInvariant()
+          if ($ActualHash -ne $NodeSha256) { throw "Node.js archive checksum mismatch" }
+          Expand-Archive -LiteralPath $ArchivePath -DestinationPath $ExtractPath -Force
+          $Entries = @(Get-ChildItem -LiteralPath $ExtractPath)
+          if ($Entries.Count -ne 1 -or $Entries[0].Name -ne "node-v$NodeVersion-win-x64") { throw "Unexpected Node.js archive layout" }
+          $Extracted = $Entries[0].FullName
+          $ExtractedNode = Join-Path $Extracted "node.exe"
+          $ExtractedNpm = Join-Path $Extracted "node_modules\npm\bin\npm-cli.js"
+          if (-not (Test-Path -LiteralPath $ExtractedNpm) -or (& $ExtractedNode --version) -ne "v$NodeVersion") { throw "Node.js runtime validation failed" }
+          Remove-Item -LiteralPath $NodeRoot -Recurse -Force -ErrorAction SilentlyContinue
+          Move-Item -LiteralPath $Extracted -Destination $NodeRoot
+          if (-not (Test-ManagedNode)) { throw "Node.js activation validation failed" }
+        } finally {
+          Remove-Item -LiteralPath $TempRoot -Recurse -Force -ErrorAction SilentlyContinue
+        }
+      }
+    } finally {
+      $NodeLockHandle.Dispose()
+      Remove-Item -LiteralPath $NodeLock -Force -ErrorAction SilentlyContinue
+    }
+  }
+  $NodeBin = Join-Path $NodeRoot "node.exe"
+}
+
+$NodeDirectory = Split-Path -Parent $NodeBin
+$NpmCandidates = @(
+  (Join-Path $NodeDirectory "node_modules\npm\bin\npm-cli.js"),
+  (Join-Path $NodeDirectory "..\node_modules\npm\bin\npm-cli.js")
+)
+$NpmCli = $NpmCandidates | Where-Object { Test-Path -LiteralPath $_ -PathType Leaf } | Select-Object -First 1
+if (-not $NpmCli) { throw "npm CLI was not found beside $NodeBin" }
+
+$PackageSpec = "agentroam@$AgentRoamVersion"
+$ExtraPackageSpecs = @()
+if ($env:AGENTROAM_BOOTSTRAP_TEST -eq "1" -and $env:AGENTROAM_PACKAGE_SPEC) {
+  $PackageSpec = $env:AGENTROAM_PACKAGE_SPEC
+  if ($env:AGENTROAM_BOOTSTRAP_EXTRA_SPECS) { $ExtraPackageSpecs = @($env:AGENTROAM_BOOTSTRAP_EXTRA_SPECS.Split(';') | Where-Object { $_ }) }
+}
+$Entry = Join-Path $LauncherRoot "node_modules\agentroam\bin\agentroam.mjs"
+
+function Test-Launcher {
+  if (-not (Test-Path -LiteralPath $Entry -PathType Leaf)) { return $false }
+  try {
+    $Output = & $NodeBin $Entry version 2>$null
+    return $LASTEXITCODE -eq 0 -and $Output -match [Regex]::Escape($AgentRoamVersion)
+  } catch { return $false }
+}
+
+if (-not (Test-Launcher)) {
+  $LauncherLockHandle = Enter-InstallLock $LauncherLock
+  try {
+    if (-not (Test-Launcher)) {
+      $TempLauncher = Join-Path $LauncherParent ".launcher-$AgentRoamVersion-$PID-$([Guid]::NewGuid().ToString('N'))"
+      try {
+        $NpmArgs = @("install", "--no-audit", "--no-fund", "--registry", $NpmRegistry, "--prefix", $TempLauncher) + $ExtraPackageSpecs + @($PackageSpec)
+        & $NodeBin $NpmCli @NpmArgs
+        if ($LASTEXITCODE -ne 0) { throw "npm install failed with exit code $LASTEXITCODE" }
+        $TempEntry = Join-Path $TempLauncher "node_modules\agentroam\bin\agentroam.mjs"
+        $VersionOutput = & $NodeBin $TempEntry version
+        if ($LASTEXITCODE -ne 0 -or $VersionOutput -notmatch [Regex]::Escape($AgentRoamVersion)) { throw "AgentRoam version validation failed" }
+        Remove-Item -LiteralPath $LauncherRoot -Recurse -Force -ErrorAction SilentlyContinue
+        Move-Item -LiteralPath $TempLauncher -Destination $LauncherRoot
+      } finally {
+        Remove-Item -LiteralPath $TempLauncher -Recurse -Force -ErrorAction SilentlyContinue
+      }
+    }
+  } finally {
+    $LauncherLockHandle.Dispose()
+    Remove-Item -LiteralPath $LauncherLock -Force -ErrorAction SilentlyContinue
+  }
+}
+
+$WrapperTemp = "$WrapperPath.$PID.tmp"
+$WrapperContent = "@echo off`r`n`"$NodeBin`" `"$Entry`" %*`r`n"
+[System.IO.File]::WriteAllText($WrapperTemp, $WrapperContent, [Text.Encoding]::ASCII)
+Move-Item -LiteralPath $WrapperTemp -Destination $WrapperPath -Force
+
+$UserPath = [Environment]::GetEnvironmentVariable("Path", "User")
+$PathParts = @($UserPath -split ";" | Where-Object { $_ })
+if ($PathParts -notcontains $WrapperDir) {
+  $UpdatedPath = if ($UserPath) { "$UserPath;$WrapperDir" } else { $WrapperDir }
+  [Environment]::SetEnvironmentVariable("Path", $UpdatedPath, "User")
+  $env:Path = "$env:Path;$WrapperDir"
+}
+
+& $NodeBin $Entry doctor --data-dir $DataDir
+if ($LASTEXITCODE -ne 0) { throw "AgentRoam doctor failed with exit code $LASTEXITCODE" }
+if ($env:AGENTROAM_INSTALL_SKIP_SERVICE -eq "1") {
+  Write-Host "AgentRoam service registration skipped for isolated verification."
+} else {
+  & $NodeBin $Entry service install --root $ServiceRoot --data-dir $DataDir
+  if ($LASTEXITCODE -ne 0) { throw "AgentRoam service installation failed with exit code $LASTEXITCODE" }
+}
+Write-Host "`nAgentRoam $AgentRoamVersion installed: $WrapperPath"
+Write-Host "Open a new terminal, then run: agentroam service status"

package/install/install-agentroam.sh

@@ -0,0 +1,199 @@
+#!/bin/sh
+set -eu
+
+NODE_VERSION="22.22.0"
+AGENTROAM_VERSION="0.2.0-preview.9"
+NODE_ARCHIVE="node-v22.22.0-darwin-arm64.tar.xz"
+NODE_SHA256="2bd596bbfc4a275ceb8721a5954ee97daea5ebe673e96a185ebd732f6fb023ac"
+NODE_URL="https://nodejs.org/dist/v22.22.0/$NODE_ARCHIVE"
+NPM_REGISTRY="https://registry.npmjs.org"
+DATA_DIR="${AGENTROAM_DATA_DIR:-$HOME/.agentroam}"
+NODE_PARENT="$DATA_DIR/runtimes/node"
+NODE_ROOT="$NODE_PARENT/$NODE_VERSION"
+NODE_LOCK="$NODE_ROOT.lock"
+LAUNCHER_PARENT="$DATA_DIR/launcher"
+LAUNCHER_ROOT="$LAUNCHER_PARENT/$AGENTROAM_VERSION"
+LAUNCHER_LOCK="$LAUNCHER_ROOT.lock"
+WRAPPER_DIR="$HOME/.local/bin"
+WRAPPER_PATH="$WRAPPER_DIR/agentroam"
+SERVICE_ROOT_EXPLICIT=0
+if [ "${AGENTROAM_ROOT+x}" = "x" ]; then
+  SERVICE_ROOT="$AGENTROAM_ROOT"
+  SERVICE_ROOT_EXPLICIT=1
+else
+  SERVICE_ROOT="$PWD"
+fi
+TEMP_ROOT=""
+OWN_NODE_LOCK=0
+OWN_LAUNCHER_LOCK=0
+
+fail() {
+  printf 'agentroam installer: %s\n' "$*" >&2
+  exit 1
+}
+
+cleanup() {
+  if [ -n "$TEMP_ROOT" ] && [ -d "$TEMP_ROOT" ]; then
+    rm -rf "$TEMP_ROOT"
+  fi
+  if [ "$OWN_NODE_LOCK" -eq 1 ]; then rmdir "$NODE_LOCK" 2>/dev/null || true; fi
+  if [ "$OWN_LAUNCHER_LOCK" -eq 1 ]; then rmdir "$LAUNCHER_LOCK" 2>/dev/null || true; fi
+}
+trap cleanup EXIT HUP INT TERM
+
+[ "$(uname -s)" = "Darwin" ] || fail "this installer supports macOS only"
+[ "$(uname -m)" = "arm64" ] || fail "managed Node.js supports Apple Silicon only"
+command -v curl >/dev/null 2>&1 || fail "curl is required"
+command -v shasum >/dev/null 2>&1 || fail "shasum is required"
+[ -x /usr/bin/tar ] || fail "/usr/bin/tar is required"
+[ -d "$SERVICE_ROOT" ] || fail "AgentRoam root is not a directory: $SERVICE_ROOT"
+service_root_physical=$(cd "$SERVICE_ROOT" && pwd -P)
+home_physical=$(cd "$HOME" && pwd -P)
+if [ "$SERVICE_ROOT_EXPLICIT" -eq 0 ] && [ "$service_root_physical" = "$home_physical" ]; then
+  fail "refusing to expose the entire home directory implicitly; run from a project directory or set AGENTROAM_ROOT explicitly"
+fi
+SERVICE_ROOT="$service_root_physical"
+
+mkdir -p "$NODE_PARENT" "$LAUNCHER_PARENT" "$WRAPPER_DIR"
+
+node_is_22() {
+  [ -x "$1" ] && [ "$("$1" -p 'process.versions.node.split(".")[0]' 2>/dev/null || true)" = "22" ]
+}
+
+runtime_is_valid() {
+  [ -x "$NODE_ROOT/bin/node" ] \
+    && [ -f "$NODE_ROOT/lib/node_modules/npm/bin/npm-cli.js" ] \
+    && [ "$("$NODE_ROOT/bin/node" --version 2>/dev/null || true)" = "v$NODE_VERSION" ]
+}
+
+acquire_directory_lock() {
+  lock_path=$1
+  waited=0
+  while ! mkdir "$lock_path" 2>/dev/null; do
+    if [ "$waited" -ge 900 ]; then
+      lock_mtime=$(stat -f %m "$lock_path" 2>/dev/null || printf '0')
+      now=$(date +%s)
+      if [ $((now - lock_mtime)) -gt 900 ]; then
+        rmdir "$lock_path" 2>/dev/null || true
+        waited=0
+        continue
+      fi
+      fail "timed out waiting for install lock $lock_path"
+    fi
+    sleep 1
+    waited=$((waited + 1))
+  done
+}
+
+SYSTEM_NODE=$(command -v node 2>/dev/null || true)
+if [ "${AGENTROAM_BOOTSTRAP_TEST:-}" = "1" ] && [ "${AGENTROAM_FORCE_PRIVATE_NODE:-}" = "1" ]; then
+  SYSTEM_NODE=""
+fi
+if [ -n "$SYSTEM_NODE" ] && node_is_22 "$SYSTEM_NODE"; then
+  NODE_BIN="$SYSTEM_NODE"
+else
+  if ! runtime_is_valid; then
+    acquire_directory_lock "$NODE_LOCK"
+    OWN_NODE_LOCK=1
+    if ! runtime_is_valid; then
+      TEMP_ROOT=$(mktemp -d "$NODE_PARENT/.node-$NODE_VERSION.XXXXXX")
+      archive_path="$TEMP_ROOT/$NODE_ARCHIVE"
+      extract_path="$TEMP_ROOT/extract"
+      mkdir "$extract_path"
+      printf 'Downloading Node.js %s...\n' "$NODE_VERSION"
+      if [ -n "${AGENTROAM_NODE_ARCHIVE_FILE:-}" ]; then
+        cp "$AGENTROAM_NODE_ARCHIVE_FILE" "$archive_path"
+      else
+        download_attempt=1
+        while ! curl -fL -C - --connect-timeout 15 --max-time 600 "$NODE_URL" -o "$archive_path"; do
+          [ "$download_attempt" -lt 3 ] || fail "Node.js download failed after 3 attempts"
+          download_attempt=$((download_attempt + 1))
+          sleep "$download_attempt"
+        done
+      fi
+      actual_sha=$(shasum -a 256 "$archive_path" | awk '{print $1}')
+      [ "$actual_sha" = "$NODE_SHA256" ] || fail "Node.js archive checksum mismatch"
+      /usr/bin/tar -xJf "$archive_path" -C "$extract_path"
+      entry_count=$(find "$extract_path" -mindepth 1 -maxdepth 1 | wc -l | tr -d ' ')
+      [ "$entry_count" = "1" ] || fail "unexpected Node.js archive layout"
+      extracted="$extract_path/node-v$NODE_VERSION-darwin-arm64"
+      [ -x "$extracted/bin/node" ] || fail "Node.js executable is missing"
+      [ -f "$extracted/lib/node_modules/npm/bin/npm-cli.js" ] || fail "npm CLI is missing"
+      [ "$("$extracted/bin/node" --version)" = "v$NODE_VERSION" ] || fail "Node.js version validation failed"
+      rm -rf "$NODE_ROOT"
+      mv "$extracted" "$NODE_ROOT"
+      runtime_is_valid || fail "Node.js activation validation failed"
+      rm -rf "$TEMP_ROOT"
+      TEMP_ROOT=""
+    fi
+    rmdir "$NODE_LOCK" 2>/dev/null || true
+    OWN_NODE_LOCK=0
+  fi
+  NODE_BIN="$NODE_ROOT/bin/node"
+fi
+
+find_npm_cli() {
+  node_dir=$(dirname "$NODE_BIN")
+  for candidate in \
+    "$node_dir/../lib/node_modules/npm/bin/npm-cli.js" \
+    "$node_dir/lib/node_modules/npm/bin/npm-cli.js"; do
+    if [ -f "$candidate" ]; then
+      printf '%s\n' "$candidate"
+      return
+    fi
+  done
+  fail "npm CLI was not found beside $NODE_BIN"
+}
+
+NPM_CLI=$(find_npm_cli)
+PACKAGE_SPEC="agentroam@$AGENTROAM_VERSION"
+EXTRA_PACKAGE_SPECS=""
+if [ "${AGENTROAM_BOOTSTRAP_TEST:-}" = "1" ] && [ -n "${AGENTROAM_PACKAGE_SPEC:-}" ]; then
+  PACKAGE_SPEC="$AGENTROAM_PACKAGE_SPEC"
+  EXTRA_PACKAGE_SPECS="${AGENTROAM_BOOTSTRAP_EXTRA_SPECS:-}"
+fi
+
+launcher_is_valid() {
+  [ -f "$LAUNCHER_ROOT/node_modules/agentroam/bin/agentroam.mjs" ] \
+    && [ "$("$NODE_BIN" "$LAUNCHER_ROOT/node_modules/agentroam/bin/agentroam.mjs" version 2>/dev/null | awk '{print $2}' || true)" = "$AGENTROAM_VERSION" ]
+}
+
+if ! launcher_is_valid; then
+  acquire_directory_lock "$LAUNCHER_LOCK"
+  OWN_LAUNCHER_LOCK=1
+  if ! launcher_is_valid; then
+    TEMP_ROOT=$(mktemp -d "$LAUNCHER_PARENT/.launcher-$AGENTROAM_VERSION.XXXXXX")
+    # Test-only extra specs are whitespace-delimited artifact paths in isolated CI directories.
+    # shellcheck disable=SC2086
+    "$NODE_BIN" "$NPM_CLI" install --no-audit --no-fund --registry "$NPM_REGISTRY" --prefix "$TEMP_ROOT" $EXTRA_PACKAGE_SPECS "$PACKAGE_SPEC"
+    entry="$TEMP_ROOT/node_modules/agentroam/bin/agentroam.mjs"
+    [ -f "$entry" ] || fail "AgentRoam launcher is missing after npm install"
+    [ "$("$NODE_BIN" "$entry" version | awk '{print $2}')" = "$AGENTROAM_VERSION" ] || fail "AgentRoam version validation failed"
+    rm -rf "$LAUNCHER_ROOT"
+    mv "$TEMP_ROOT" "$LAUNCHER_ROOT"
+    TEMP_ROOT=""
+  fi
+  rmdir "$LAUNCHER_LOCK" 2>/dev/null || true
+  OWN_LAUNCHER_LOCK=0
+fi
+
+entry="$LAUNCHER_ROOT/node_modules/agentroam/bin/agentroam.mjs"
+wrapper_temp=$(mktemp "$WRAPPER_DIR/.agentroam.XXXXXX")
+{
+  printf '#!/bin/sh\n'
+  printf 'exec "%s" "%s" "$@"\n' "$NODE_BIN" "$entry"
+} > "$wrapper_temp"
+chmod 755 "$wrapper_temp"
+mv "$wrapper_temp" "$WRAPPER_PATH"
+
+"$NODE_BIN" "$entry" doctor --data-dir "$DATA_DIR"
+if [ "${AGENTROAM_INSTALL_SKIP_SERVICE:-}" = "1" ]; then
+  printf 'AgentRoam service registration skipped for isolated verification.\n'
+else
+  "$NODE_BIN" "$entry" service install --root "$SERVICE_ROOT" --data-dir "$DATA_DIR"
+fi
+printf '\nAgentRoam %s installed: %s\n' "$AGENTROAM_VERSION" "$WRAPPER_PATH"
+case ":${PATH:-}:" in
+  *":$WRAPPER_DIR:"*) ;;
+  *) printf 'Add this directory to PATH: export PATH="%s:$PATH"\n' "$WRAPPER_DIR" ;;
+esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentroam",
-  "version": "0.2.0-preview.8",
+  "version": "0.2.0-preview.9",
   "description": "Zero-install mobile remote terminal and file console",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
   "files": [
     "bin",
     "dist",
+    "install",
     "README.md"
   ],
   "scripts": {
@@ -25,12 +26,12 @@
     "undici": "^6.25.0"
   },
   "optionalDependencies": {
-    "agentroam-runtime-darwin-arm64": "0.2.0-preview.8",
-    "agentroam-runtime-win32-x64": "0.2.0-preview.8",
-    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.8",
-    "agentroam-cloudflared-win32-x64": "0.2.0-preview.8",
-    "agentroam-tui-darwin-arm64": "0.2.0-preview.8",
-    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.8"
+    "agentroam-runtime-darwin-arm64": "0.2.0-preview.9",
+    "agentroam-runtime-win32-x64": "0.2.0-preview.9",
+    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.9",
+    "agentroam-cloudflared-win32-x64": "0.2.0-preview.9",
+    "agentroam-tui-darwin-arm64": "0.2.0-preview.9",
+    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.9"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",