agentroam 0.2.0-preview.10 → 0.2.0-preview.12

package/README.md

@@ -20,20 +20,20 @@ npx agentroam@preview
 Or install from tarball:
 
 ```bash
-npm install ./agentroam-cloudflared-darwin-arm64-0.2.0-preview.10.tgz \
-  ./agentroam-runtime-darwin-arm64-0.2.0-preview.10.tgz \
-  ./agentroam-tui-darwin-arm64-0.2.0-preview.10.tgz \
-  ./agentroam-0.2.0-preview.10.tgz
+npm install ./agentroam-cloudflared-darwin-arm64-0.2.0-preview.12.tgz \
+  ./agentroam-runtime-darwin-arm64-0.2.0-preview.12.tgz \
+  ./agentroam-tui-darwin-arm64-0.2.0-preview.12.tgz \
+  ./agentroam-0.2.0-preview.12.tgz
 npx agentroam
 ```
 
 Windows PowerShell:
 
 ```powershell
-npm install ./agentroam-cloudflared-win32-x64-0.2.0-preview.10.tgz `
-  ./agentroam-runtime-win32-x64-0.2.0-preview.10.tgz `
-  ./caoqu-agentroam-tui-win32-x64-0.2.0-preview.10.tgz `
-  ./agentroam-0.2.0-preview.10.tgz
+npm install ./agentroam-cloudflared-win32-x64-0.2.0-preview.12.tgz `
+  ./agentroam-runtime-win32-x64-0.2.0-preview.12.tgz `
+  ./caoqu-agentroam-tui-win32-x64-0.2.0-preview.12.tgz `
+  ./agentroam-0.2.0-preview.12.tgz
 npx agentroam
 ```
 
@@ -71,6 +71,9 @@ downloaded only when no installed Node 22 is available.
 The service keeps running after the terminal closes, restarts after failure, and
 starts again when the user logs in. macOS uses a user LaunchAgent; Windows uses a
 current-user Task Scheduler task. Neither requires administrator privileges.
+Running a newer versioned installer automatically stops and replaces an existing
+AgentRoam user service before starting the new version. Session data, pairing
+state, managed runtimes, and service logs are preserved during the upgrade.
 
 ```bash
 agentroam service status

package/bin/node-preflight.mjs

@@ -7,7 +7,7 @@ import { promisify } from "node:util";
 
 const execFileAsync = promisify(execFile);
 const MANAGED_NODE_VERSION = "22.22.0";
-const RELEASE_VERSION = "0.2.0-preview.10";
+const RELEASE_VERSION = "0.2.0-preview.12";
 const RELEASE_BASE_URL = `https://gitee.com/caoqu/team-agent/releases/download/v${RELEASE_VERSION}`;
 const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
 

package/dist/cloudflared/bundled-asset.test.js

@@ -2,6 +2,7 @@ import { mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { resolve } from "node:path";
 import { describe, expect, it } from "vitest";
+import { AGENTROAM_VERSION } from "../platform-packages.js";
 import { resolveBundledCloudflared } from "./bundled-asset.js";
 describe("resolveBundledCloudflared", () => {
     it("resolves a valid platform package manifest and archive", async () => {
@@ -10,7 +11,7 @@ describe("resolveBundledCloudflared", () => {
         const archivePath = resolve(root, "cloudflared.tgz");
         await writeFile(archivePath, "archive");
         await writeFile(manifestPath, JSON.stringify({
-            packageVersion: "0.2.0-preview.10",
+            packageVersion: AGENTROAM_VERSION,
             upstreamVersion: "2026.8.2",
             target: "darwin-arm64",
             assetFormat: "tgz",
@@ -51,7 +52,7 @@ describe("resolveBundledCloudflared", () => {
         const assetPath = resolve(root, "cloudflared.exe");
         await writeFile(assetPath, "binary");
         await writeFile(manifestPath, JSON.stringify({
-            packageVersion: "0.2.0-preview.10",
+            packageVersion: AGENTROAM_VERSION,
             upstreamVersion: "2026.8.2",
             target: "windows-amd64",
             assetFormat: "executable",

package/dist/platform-packages.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname } from "node:path";
-export const AGENTROAM_VERSION = "0.2.0-preview.10";
+export const AGENTROAM_VERSION = "0.2.0-preview.12";
 export const PLATFORM_PACKAGES = {
     "darwin-arm64": {
         runtime: "agentroam-runtime-darwin-arm64",

package/dist/service/macos-launch-agent.js

@@ -26,6 +26,7 @@ export class MacLaunchAgent {
     async install(config) {
         await this.validateConfig(config);
         const paths = resolveServicePaths(this.homeDir, config.dataDir);
+        const previousState = await readServiceState(paths);
         await Promise.all([
             mkdir(paths.launchAgentsDir, { recursive: true }),
             ensurePrivateDirectory(paths.controlDir),
@@ -40,8 +41,10 @@ export class MacLaunchAgent {
             await this.runRequired("plutil", ["-convert", "xml1", "-o", plistTempPath, jsonPath]);
             await this.runRequired("plutil", ["-lint", plistTempPath]);
             await chmod(plistTempPath, 0o600);
-            if ((await this.inspectJob()).loaded)
+            if ((await this.inspectJob()).loaded) {
                 await this.runRequired("launchctl", ["bootout", this.serviceTarget]);
+                await this.waitForServiceExit(previousState?.pid);
+            }
             await rename(plistTempPath, paths.plistPath);
             await chmod(paths.plistPath, 0o600);
             await writePrivateJson(paths.configPath, config);
@@ -203,6 +206,21 @@ export class MacLaunchAgent {
             await delay(this.pollIntervalMs);
         }
     }
+    async waitForServiceExit(pid) {
+        const deadline = Date.now() + this.stopTimeoutMs;
+        do {
+            const processRunning = pid ? this.processExists(pid) : false;
+            const job = await this.inspectJob();
+            if (!processRunning && !job.loaded)
+                return;
+            if (Date.now() >= deadline) {
+                if (processRunning)
+                    throw new Error(`service process ${pid} did not stop after launchctl bootout`);
+                throw new Error(`service ${SERVICE_LABEL} did not unload after launchctl bootout`);
+            }
+            await delay(this.pollIntervalMs);
+        } while (true);
+    }
 }
 export function buildLaunchAgentPlist(config, paths) {
     const environmentVariables = {

package/dist/service/macos-launch-agent.test.js

@@ -59,6 +59,125 @@ describe("MacLaunchAgent", () => {
         expect((await stat(paths.plistPath)).mode & 0o777).toBe(0o600);
         expect(JSON.parse(await readFile(paths.configPath, "utf8"))).toMatchObject({ roots: value.roots });
     });
+    it("waits for the previous launchd job and process before bootstrapping a replacement", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-launch-agent-reinstall-"));
+        const paths = resolveServicePaths(home);
+        const value = config(home, paths.dataDir);
+        await createConfigFiles(value);
+        await mkdir(paths.launchAgentsDir, { recursive: true });
+        await writeFile(paths.plistPath, "old plist");
+        await writePrivateJson(paths.configPath, { ...value, version: "0.2.0-preview.8" });
+        await writePrivateJson(paths.statePath, {
+            status: "ready", pid: 700, version: "0.2.0-preview.8", startedAt: "x", updatedAt: "x",
+        });
+        await writePrivateText(resolve(paths.dataDir, "data/keep.txt"), "keep");
+        await writePrivateText(paths.stdoutPath, "keep logs");
+        let loaded = true;
+        let processChecks = 0;
+        const lifecycle = [];
+        const runner = async (command, args) => {
+            if (command === "plutil" && args[0] === "-convert") {
+                await writeFile(args[3], "<?xml version=\"1.0\"?><plist version=\"1.0\"><dict/></plist>");
+            }
+            if (command === "launchctl" && args[0] === "print") {
+                return { code: loaded ? 0 : 1, stdout: loaded ? "state = running" : "", stderr: "" };
+            }
+            if (command === "launchctl" && args[0] === "bootout")
+                lifecycle.push("bootout");
+            if (command === "launchctl" && args[0] === "bootstrap") {
+                lifecycle.push("bootstrap");
+                await writePrivateJson(paths.statePath, {
+                    status: "ready", pid: 701, version: value.version, startedAt: "y", updatedAt: "y",
+                    accessUrl: "https://ready.example/web",
+                });
+            }
+            return { code: 0, stdout: "", stderr: "" };
+        };
+        const processExists = vi.fn(() => {
+            processChecks++;
+            if (processChecks === 1)
+                return true;
+            loaded = false;
+            lifecycle.push("process-exit");
+            return false;
+        });
+        const result = await new MacLaunchAgent({
+            homeDir: home,
+            uid: 501,
+            runner,
+            processExists,
+            readyTimeoutMs: 20,
+            stopTimeoutMs: 50,
+            pollIntervalMs: 1,
+        }).install(value);
+        expect(result.state).toMatchObject({ status: "ready", pid: 701 });
+        expect(lifecycle).toEqual(["bootout", "process-exit", "bootstrap"]);
+        expect(processExists).toHaveBeenCalledWith(700);
+        expect(await readFile(resolve(paths.dataDir, "data/keep.txt"), "utf8")).toBe("keep");
+        expect(await readFile(paths.stdoutPath, "utf8")).toBe("keep logs");
+    });
+    it("waits for launchd to remove a previous job when no runtime pid is available", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-launch-agent-reinstall-no-pid-"));
+        const paths = resolveServicePaths(home);
+        const value = config(home, paths.dataDir);
+        await createConfigFiles(value);
+        let printCount = 0;
+        let bootedOut = false;
+        let bootstrapPrintCount = 0;
+        const runner = async (command, args) => {
+            if (command === "plutil" && args[0] === "-convert") {
+                await writeFile(args[3], "<?xml version=\"1.0\"?><plist version=\"1.0\"><dict/></plist>");
+            }
+            if (command === "launchctl" && args[0] === "print") {
+                printCount++;
+                const loaded = !bootedOut || printCount < 3;
+                return { code: loaded ? 0 : 1, stdout: loaded ? "state = exited" : "", stderr: "" };
+            }
+            if (command === "launchctl" && args[0] === "bootout")
+                bootedOut = true;
+            if (command === "launchctl" && args[0] === "bootstrap") {
+                bootstrapPrintCount = printCount;
+                await writePrivateJson(paths.statePath, {
+                    status: "ready", pid: 701, version: value.version, startedAt: "y", updatedAt: "y",
+                });
+            }
+            return { code: 0, stdout: "", stderr: "" };
+        };
+        await new MacLaunchAgent({
+            homeDir: home,
+            uid: 501,
+            runner,
+            readyTimeoutMs: 20,
+            stopTimeoutMs: 50,
+            pollIntervalMs: 1,
+        }).install(value);
+        expect(bootstrapPrintCount).toBeGreaterThanOrEqual(3);
+    });
+    it("does not bootstrap while the previous launchd job is still loaded", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-launch-agent-reinstall-timeout-"));
+        const paths = resolveServicePaths(home);
+        const value = config(home, paths.dataDir);
+        await createConfigFiles(value);
+        const calls = [];
+        const runner = async (command, args) => {
+            calls.push(`${command} ${args[0] ?? ""}`);
+            if (command === "plutil" && args[0] === "-convert") {
+                await writeFile(args[3], "<?xml version=\"1.0\"?><plist version=\"1.0\"><dict/></plist>");
+            }
+            if (command === "launchctl" && args[0] === "print") {
+                return { code: 0, stdout: "state = exited", stderr: "" };
+            }
+            return { code: 0, stdout: "", stderr: "" };
+        };
+        await expect(new MacLaunchAgent({
+            homeDir: home,
+            uid: 501,
+            runner,
+            stopTimeoutMs: 0,
+            pollIntervalMs: 1,
+        }).install(value)).rejects.toThrow("did not unload after launchctl bootout");
+        expect(calls).not.toContain("launchctl bootstrap");
+    });
     it("reports ready URLs only while the installed job is running", async () => {
         const home = await mkdtemp(resolve(tmpdir(), "agentroam-launch-agent-url-"));
         const paths = resolveServicePaths(home);

package/dist/service/service-command.js

@@ -1,11 +1,20 @@
 import { delimiter, dirname, isAbsolute, resolve, win32 } from "node:path";
 import { resolveCodexRuntime } from "../codex-runtime-manager.js";
 import { detectPlatform } from "../platform.js";
+import { renderQr } from "../qr.js";
 import { MacLaunchAgent } from "./macos-launch-agent.js";
 import { WindowsTaskService } from "./windows-task-service.js";
 export async function runServiceCommand(options, context) {
     const platform = context.platform ?? process.platform;
     const log = context.log ?? console.log;
+    const stdoutIsTTY = context.isTTY ?? process.stdout.isTTY === true;
+    const logAccessUrl = async (accessUrl) => {
+        log(`Open: ${accessUrl}`);
+        if (!options.qr || !stdoutIsTTY)
+            return;
+        log("");
+        log(await renderQr(accessUrl));
+    };
     const controller = context.controller ?? context.launchAgent ?? createController(platform, context.homeDir);
     switch (options.serviceAction) {
         case "install": {
@@ -49,7 +58,7 @@ export async function runServiceCommand(options, context) {
             const { definition, state } = await controller.install(config);
             log(`✓ AgentRoam service installed: ${definition}`);
             if (state?.status === "ready" && state.accessUrl)
-                log(`Open: ${state.accessUrl}`);
+                await logAccessUrl(state.accessUrl);
             else
                 log("Service is starting. Run `agentroam service url` shortly.");
             return;
@@ -58,7 +67,7 @@ export async function runServiceCommand(options, context) {
             const state = await controller.start();
             log("✓ AgentRoam service started");
             if (state?.status === "ready" && state.accessUrl)
-                log(`Open: ${state.accessUrl}`);
+                await logAccessUrl(state.accessUrl);
             return;
         }
         case "stop":
@@ -77,7 +86,7 @@ export async function runServiceCommand(options, context) {
                 log(`Root: ${status.config.roots.join(", ")}`);
             }
             if (status.running && status.state?.status === "ready" && status.state.accessUrl) {
-                log(`Open: ${status.state.accessUrl}`);
+                await logAccessUrl(status.state.accessUrl);
             }
             return;
         }
@@ -98,7 +107,7 @@ export async function runServiceCommand(options, context) {
             const state = await controller.restart();
             log("✓ AgentRoam service restarted");
             if (state?.status === "ready" && state.accessUrl)
-                log(`Open: ${state.accessUrl}`);
+                await logAccessUrl(state.accessUrl);
             return;
         }
         case "uninstall": {

package/dist/service/service-command.test.js

@@ -33,6 +33,48 @@ describe("runServiceCommand", () => {
         }));
         expect(log).toHaveBeenCalledWith("Open: https://ready.example/web");
     });
+    it("prints a scannable QR code after the URL on interactive terminals", async () => {
+        const log = vi.fn();
+        await runServiceCommand({ ...options("start"), qr: true }, {
+            platform: "darwin",
+            nodePath: "/node",
+            cliPath: "/agentroam.mjs",
+            version: "test",
+            isTTY: true,
+            log,
+            controller: controller({ start: vi.fn(async () => ({ status: "ready", accessUrl: "https://ready.example/web" })) }),
+        });
+        const openIndex = log.mock.calls.findIndex(([line]) => line === "Open: https://ready.example/web");
+        expect(openIndex).toBeGreaterThanOrEqual(0);
+        const qr = log.mock.calls[openIndex + 2]?.[0];
+        expect(qr).toMatch(/[▀▄█]/);
+        expect(qr).toContain("\n");
+    });
+    it("keeps service output QR-free when piped or when --no-qr is set", async () => {
+        const log = vi.fn();
+        const start = vi.fn(async () => ({ status: "ready", accessUrl: "https://ready.example/web" }));
+        await runServiceCommand({ ...options("start"), qr: true }, {
+            platform: "darwin",
+            nodePath: "/node",
+            cliPath: "/agentroam.mjs",
+            version: "test",
+            isTTY: false,
+            log,
+            controller: controller({ start }),
+        });
+        await runServiceCommand(options("start"), {
+            platform: "darwin",
+            nodePath: "/node",
+            cliPath: "/agentroam.mjs",
+            version: "test",
+            isTTY: true,
+            log,
+            controller: controller({ start }),
+        });
+        const lines = log.mock.calls.map(([line]) => line);
+        expect(lines).toContain("Open: https://ready.example/web");
+        expect(lines.some((line) => /[▀▄█]/.test(String(line)))).toBe(false);
+    });
     it("pins the selected Node directory ahead of the inherited service PATH", () => {
         expect(buildServiceEnvironmentPath("/Users/test/.nvm/versions/node/v22.22.2/bin/node", "/usr/bin:/Users/test/.nvm/versions/node/v22.22.2/bin", "darwin")).toBe("/Users/test/.nvm/versions/node/v22.22.2/bin:/usr/bin:/bin:/usr/sbin:/sbin");
     });

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

@@ -26,12 +26,21 @@ export class WindowsTaskService {
         const hostPath = resolveWindowsServiceHost(config.cliPath);
         await this.validate(config, hostPath);
         const paths = resolveServicePaths(this.homeDir, config.dataDir);
+        const previousTask = await this.inspectTask();
+        const previousState = await readServiceState(paths);
         await Promise.all([
             ensurePrivateDirectory(paths.controlDir),
             ensurePrivateDirectory(paths.logsDir),
             ensurePrivateFile(paths.stdoutPath),
             ensurePrivateFile(paths.stderrPath),
         ]);
+        if (previousTask.running) {
+            await this.runRequired(buildStopTaskScript());
+            if (previousState?.pid)
+                await this.waitForProcessExit(previousState.pid);
+        }
+        if (previousTask.installed)
+            await this.runRequired(buildUnregisterTaskScript());
         await writePrivateJson(paths.configPath, config);
         await Promise.all([removeIfExists(paths.statePath), removeIfExists(paths.urlPath)]);
         await this.runRequired(buildRegisterTaskScript(config, hostPath, paths.configPath));

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

@@ -1,7 +1,7 @@
 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 { describe, expect, it, vi } from "vitest";
 import { resolveServicePaths, writePrivateText } from "./service-files.js";
 import { WindowsTaskService, buildRegisterTaskScript, quoteWindowsCommandLineArgument, resolveWindowsServiceHost, } from "./windows-task-service.js";
 describe("WindowsTaskService", () => {
@@ -68,6 +68,141 @@ describe("WindowsTaskService", () => {
         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("stops and unregisters a running task before installing its replacement", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-windows-task-reinstall-"));
+        const paths = resolveServicePaths(home, resolve(home, "data"));
+        const value = config(home, paths.dataDir);
+        await mkdir(value.roots[0], { recursive: true });
+        await writePrivateText(paths.configPath, JSON.stringify({ ...value, version: "0.2.0-preview.8" }));
+        await writePrivateText(paths.statePath, JSON.stringify({
+            status: "ready", pid: 800, version: "0.2.0-preview.8", startedAt: "x", updatedAt: "x",
+        }));
+        await writePrivateText(resolve(paths.dataDir, "data/keep.txt"), "keep");
+        await writePrivateText(paths.stdoutPath, "keep logs");
+        let installed = true;
+        let running = true;
+        let processChecks = 0;
+        const lifecycle = [];
+        const runner = async (_command, args) => {
+            const script = Buffer.from(args.at(-1), "base64").toString("utf16le");
+            if (script.includes("Get-ScheduledTask")) {
+                return { code: 0, stdout: JSON.stringify({ installed, running }), stderr: "" };
+            }
+            if (script.includes("Stop-ScheduledTask")) {
+                lifecycle.push("stop");
+                running = false;
+            }
+            if (script.includes("Unregister-ScheduledTask")) {
+                lifecycle.push("unregister");
+                installed = false;
+            }
+            if (script.includes("Register-ScheduledTask")) {
+                lifecycle.push("register");
+                installed = true;
+            }
+            if (script.includes("Start-ScheduledTask")) {
+                lifecycle.push("start");
+                running = true;
+                await writePrivateText(paths.statePath, JSON.stringify({
+                    status: "ready", pid: 801, version: value.version, startedAt: "y", updatedAt: "y",
+                }));
+            }
+            return { code: 0, stdout: "", stderr: "" };
+        };
+        const processExists = vi.fn(() => {
+            processChecks++;
+            if (processChecks === 1)
+                return true;
+            lifecycle.push("process-exit");
+            return false;
+        });
+        const result = await new WindowsTaskService({
+            homeDir: home,
+            runner,
+            processExists,
+            validateConfig: async () => undefined,
+            readyTimeoutMs: 20,
+            stopTimeoutMs: 50,
+            pollIntervalMs: 1,
+        }).install(value);
+        expect(result.state).toMatchObject({ status: "ready", pid: 801 });
+        expect(lifecycle).toEqual(["stop", "process-exit", "unregister", "register", "start"]);
+        expect(processExists).toHaveBeenCalledWith(800);
+        expect(await readFile(resolve(paths.dataDir, "data/keep.txt"), "utf8")).toBe("keep");
+        expect(await readFile(paths.stdoutPath, "utf8")).toBe("keep logs");
+    });
+    it("replaces an installed stopped task without stopping a process", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-windows-task-reinstall-stopped-"));
+        const paths = resolveServicePaths(home, resolve(home, "data"));
+        const value = config(home, paths.dataDir);
+        await mkdir(value.roots[0], { recursive: true });
+        const lifecycle = [];
+        let installed = true;
+        const runner = async (_command, args) => {
+            const script = Buffer.from(args.at(-1), "base64").toString("utf16le");
+            if (script.includes("Get-ScheduledTask")) {
+                return { code: 0, stdout: JSON.stringify({ installed, running: false }), stderr: "" };
+            }
+            if (script.includes("Stop-ScheduledTask"))
+                lifecycle.push("stop");
+            if (script.includes("Unregister-ScheduledTask")) {
+                lifecycle.push("unregister");
+                installed = false;
+            }
+            if (script.includes("Register-ScheduledTask")) {
+                lifecycle.push("register");
+                installed = true;
+            }
+            if (script.includes("Start-ScheduledTask")) {
+                lifecycle.push("start");
+                await writePrivateText(paths.statePath, JSON.stringify({
+                    status: "ready", pid: 801, version: value.version, startedAt: "y", updatedAt: "y",
+                }));
+            }
+            return { code: 0, stdout: "", stderr: "" };
+        };
+        await new WindowsTaskService({
+            homeDir: home,
+            runner,
+            processExists: vi.fn(() => false),
+            validateConfig: async () => undefined,
+            readyTimeoutMs: 20,
+            pollIntervalMs: 1,
+        }).install(value);
+        expect(lifecycle).toEqual(["unregister", "register", "start"]);
+    });
+    it("does not replace a running task while its previous process is still alive", async () => {
+        const home = await mkdtemp(resolve(tmpdir(), "agentroam-windows-task-reinstall-timeout-"));
+        const paths = resolveServicePaths(home, resolve(home, "data"));
+        const value = config(home, paths.dataDir);
+        await mkdir(value.roots[0], { recursive: true });
+        await writePrivateText(paths.statePath, JSON.stringify({
+            status: "ready", pid: 800, version: "0.2.0-preview.8", startedAt: "x", updatedAt: "x",
+        }));
+        const lifecycle = [];
+        const runner = async (_command, args) => {
+            const script = Buffer.from(args.at(-1), "base64").toString("utf16le");
+            if (script.includes("Get-ScheduledTask")) {
+                return { code: 0, stdout: JSON.stringify({ installed: true, running: true }), stderr: "" };
+            }
+            if (script.includes("Stop-ScheduledTask"))
+                lifecycle.push("stop");
+            if (script.includes("Unregister-ScheduledTask"))
+                lifecycle.push("unregister");
+            if (script.includes("Register-ScheduledTask"))
+                lifecycle.push("register");
+            return { code: 0, stdout: "", stderr: "" };
+        };
+        await expect(new WindowsTaskService({
+            homeDir: home,
+            runner,
+            processExists: () => true,
+            validateConfig: async () => undefined,
+            stopTimeoutMs: 0,
+            pollIntervalMs: 1,
+        }).install(value)).rejects.toThrow("did not stop after task termination");
+        expect(lifecycle).toEqual(["stop"]);
+    });
     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);

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.10" },
+                    headers: { "user-agent": "agentroam-readiness/0.2.0-preview.12" },
                     signal: options.signal,
                 });
                 if (response.ok) {

package/install/README.md

@@ -5,7 +5,7 @@ These versioned installers support macOS Apple Silicon and Windows x64. They reu
 ## macOS Apple Silicon
 
 ```sh
-curl -fsSL https://gitee.com/caoqu/team-agent/releases/download/v0.2.0-preview.10/install-agentroam.sh | sh
+curl -fsSL https://gitee.com/caoqu/team-agent/releases/download/v0.2.0-preview.12/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.
@@ -13,7 +13,7 @@ The command installs the wrapper at `~/.local/bin/agentroam`. If that directory
 ## Windows x64
 
 ```powershell
-irm https://gitee.com/caoqu/team-agent/releases/download/v0.2.0-preview.10/install-agentroam.ps1 | iex
+irm https://gitee.com/caoqu/team-agent/releases/download/v0.2.0-preview.12/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`.
@@ -22,7 +22,9 @@ The command installs `%USERPROFILE%\.agentroam\bin\agentroam.cmd` and adds only
 
 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.
+The installer registers and starts the service after Node, CLI, and `doctor` validation. When a previous AgentRoam user service is installed, the new CLI stops it, waits for its process and platform registration to exit, removes only the old service registration, and then registers the replacement. Session data, pairing state, managed runtimes, and logs remain in the data directory. 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.
+
+On interactive terminals, `service install`, `start`, `status`, and `restart` print a scannable QR code beside the `Open:` URL. Piped or redirected output stays plain text, and `agentroam service install --no-qr` suppresses the code. `service url` always prints only the raw URL for scripting.
 
 Use the installer for first installation, upgrades, and repair. Use these commands for routine control:
 
@@ -38,7 +40,7 @@ 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.10`.
+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.12`.
 
 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.
 

package/install/install-agentroam.ps1

@@ -2,7 +2,7 @@ $ErrorActionPreference = "Stop"
 $ProgressPreference = "SilentlyContinue"
 
 $NodeVersion = "22.22.0"
-$AgentRoamVersion = "0.2.0-preview.10"
+$AgentRoamVersion = "0.2.0-preview.12"
 $NodeArchive = "node-v22.22.0-win-x64.zip"
 $NodeSha256 = "c97fa376d2becdc8863fcd3ca2dd9a83a9f3468ee7ccf7a6d076ec66a645c77a"
 $NodeUrl = "https://nodejs.org/dist/v22.22.0/$NodeArchive"

package/install/install-agentroam.sh

@@ -2,7 +2,7 @@
 set -eu
 
 NODE_VERSION="22.22.0"
-AGENTROAM_VERSION="0.2.0-preview.10"
+AGENTROAM_VERSION="0.2.0-preview.12"
 NODE_ARCHIVE="node-v22.22.0-darwin-arm64.tar.xz"
 NODE_SHA256="2bd596bbfc4a275ceb8721a5954ee97daea5ebe673e96a185ebd732f6fb023ac"
 NODE_URL="https://nodejs.org/dist/v22.22.0/$NODE_ARCHIVE"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentroam",
-  "version": "0.2.0-preview.10",
+  "version": "0.2.0-preview.12",
   "description": "Zero-install mobile remote terminal and file console",
   "type": "module",
   "bin": {
@@ -26,12 +26,12 @@
     "undici": "^6.25.0"
   },
   "optionalDependencies": {
-    "agentroam-runtime-darwin-arm64": "0.2.0-preview.10",
-    "agentroam-runtime-win32-x64": "0.2.0-preview.10",
-    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.10",
-    "agentroam-cloudflared-win32-x64": "0.2.0-preview.10",
-    "agentroam-tui-darwin-arm64": "0.2.0-preview.10",
-    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.10"
+    "agentroam-runtime-darwin-arm64": "0.2.0-preview.12",
+    "agentroam-runtime-win32-x64": "0.2.0-preview.12",
+    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.12",
+    "agentroam-cloudflared-win32-x64": "0.2.0-preview.12",
+    "agentroam-tui-darwin-arm64": "0.2.0-preview.12",
+    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.12"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",