@mono-agent/agent-app 0.11.5 → 0.12.0

package/dist/web-command.js

@@ -1,309 +1,1180 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import { networkInterfaces } from "node:os";
-import { resolve } from "node:path";
+import { readFile, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
 import { pruneTraceSources } from "@mono-agent/observability";
-import { startSessionWebServer } from "@mono-agent/session-web";
-import { generateBearerToken, hostForUrl, isLoopbackHost, isWildcardHost, normalizeHostForBind, normalizeOptionalString, } from "@mono-agent/agent-contracts";
-import { resolveAppTraceRegistryDir, resolveGlobalTraceRegistryDir } from "./app-config.js";
-export const DEFAULT_WEB_PORT = 4599;
-const WEB_AUTH_TOKEN_ENV = "MONO_AGENT_WEB_AUTH_TOKEN";
-/**
- * `mono-agent web`: discover every running agent on this machine (trace-source
- * registry, the same mechanism as `mono-agent tui`) and serve the read-only
- * Session Recorder PWA that visualises their runs live. Unlike `tui`, it shows
- * ALL instances at once and needs no TTY — it runs until interrupted.
- */
-export async function runWeb(options, deps = {}) {
+import { isLoopbackHost } from "@mono-agent/agent-contracts";
+import { accountHomeDirectory } from "./account-home.js";
+import { resolveGlobalTraceRegistryDir } from "./app-config.js";
+import { acquireFilesystemLifecycleLock, ensureOwnerPrivateLaunchdDirectory, writeOwnerPrivateLaunchdFile, } from "./background.js";
+import { selectBackgroundOperationalEnvironment } from "./background-environment.js";
+import { ensureManagedBackgroundRuntime } from "./background-runtime.js";
+import { bootout, bootstrap, buildWebPlistXml, defaultPathEnv, launchdServiceInfo, makeLaunchctlRunner, } from "./launchd.js";
+import * as ui from "./ui.js";
+export const DEFAULT_WEB_HOST = "0.0.0.0";
+export const DEFAULT_WEB_PORT = 5050;
+// Deliberately outside `com.mono-agent.*`: fleet discovery reserves that prefix
+// for configured agent instances.
+export const WEB_LAUNCHD_LABEL = "com.mono-agent-web";
+const DEFAULT_LOG_LINES = 200;
+const WEB_SERVICE_SCHEMA = "mono-agent.web-service.v1";
+const TAILSCALE_OWNERSHIP_SCHEMA = "mono-agent.web-tailscale-serve.v1";
+const READY_TIMEOUT_MS = 15_000;
+const READY_POLL_MS = 200;
+const TAILSCALE_FALLBACK_PORT_START = 8443;
+const TAILSCALE_FALLBACK_PORT_END = 8499;
+const TAILSCALE_STATUS_ATTEMPTS = 3;
+const TAILSCALE_STATUS_RETRY_MS = 200;
+const WEB_PACKAGE_NAME = "@mono-agent/web";
+export function webPaths(homeDir = accountHomeDirectory()) {
+    const stateDir = resolve(homeDir, ".mono-agent", "web");
+    const logDir = join(stateDir, "logs");
+    const launchAgentsDir = resolve(homeDir, "Library", "LaunchAgents");
+    return {
+        stateDir,
+        recordPath: join(stateDir, "service.json"),
+        tailscalePath: join(stateDir, "tailscale-serve.json"),
+        launchd: {
+            launchAgentsDir,
+            logDir,
+            plistPath: join(launchAgentsDir, `${WEB_LAUNCHD_LABEL}.plist`),
+            stdoutPath: join(logDir, "web.out.log"),
+            stderrPath: join(logDir, "web.err.log"),
+        },
+    };
+}
+export function renderWebHelp() {
+    return [
+        "mono-agent web — always-on multi-agent web console",
+        "",
+        "  mono-agent web",
+        "  mono-agent web start [--host <addr> | --loopback] [--port <n>]",
+        "  mono-agent web restart [--host <addr> | --loopback] [--port <n>]",
+        "  mono-agent web stop | status",
+        "  mono-agent web logs [--follow|-f] [--lines <n>]",
+        "  mono-agent web run [--host <addr> | --loopback] [--port <n>]",
+        "  mono-agent web reset --all --yes",
+        "",
+        `Default bind: ${DEFAULT_WEB_HOST}:${String(DEFAULT_WEB_PORT)} (LAN/Tailnet reachable; no app login).`,
+        "--loopback narrows the bind to 127.0.0.1. start/restart claim a free Tailscale Serve HTTPS port without replacing existing handlers.",
+        "",
+    ].join("\n");
+}
+/** Route the `mono-agent web` service namespace. Bare invocation is read-only. */
+export async function runWebCommand(options, deps = {}) {
     const stdout = deps.stdout ?? process.stdout;
     const stderr = deps.stderr ?? process.stderr;
-    const configuredRegistryDir = await resolveAppTraceRegistryDir({
-        env: options.env,
-        cwd: options.cwd,
-        configPath: options.configPath,
-    });
-    const globalRegistryDir = resolveGlobalTraceRegistryDir(options.env);
-    const registryDirs = dedupePaths([configuredRegistryDir, globalRegistryDir]);
-    await Promise.all(registryDirs.map((registryDir) => pruneTraceSources({ registryDir })));
-    const authRequired = requiresServerAuth(options.host);
-    const interactive = deps.interactive ?? process.stdout.isTTY === true;
-    const configuredAuthToken = normalizeOptionalString(options.env.MONO_AGENT_WEB_AUTH_TOKEN);
-    if (authRequired && configuredAuthToken === undefined && !interactive) {
-        stderr.write(`Non-interactive non-loopback web serving requires ${WEB_AUTH_TOKEN_ENV}; refusing to generate a bearer secret into logs.\n`);
-        return 1;
+    const action = options.positionals[0];
+    if (options.positionals.length > 1 || (action !== undefined && !WEB_ACTIONS.has(action))) {
+        stderr.write(ui.errorLine(`Unknown mono-agent web action \`${options.positionals.join(" ")}\`.`));
+        stdout.write(renderWebHelp());
+        return 2;
+    }
+    const validation = validateWebFlags(action, options);
+    if (validation !== undefined) {
+        stderr.write(ui.errorLine(validation));
+        stdout.write(renderWebHelp());
+        return 2;
+    }
+    if (action === undefined) {
+        stdout.write(renderWebHelp());
+        await statusWeb(options, deps, false);
+        return 0;
+    }
+    switch (action) {
+        case "run":
+            return await runWebForeground(options, deps);
+        case "start":
+            return await startWebBackground(options, deps, false);
+        case "restart":
+            return await startWebBackground(options, deps, true);
+        case "stop":
+            return await stopWebBackground(options, deps);
+        case "status":
+            return await statusWeb(options, deps, true);
+        case "logs":
+            return await tailWebLogs(options, deps);
+        case "reset":
+            return await resetWeb(options, deps);
+    }
+    return 2;
+}
+const WEB_ACTIONS = new Set(["start", "stop", "restart", "status", "logs", "run", "reset"]);
+function validateWebFlags(action, options) {
+    if (options.loopback === true && options.host !== undefined) {
+        return "Choose either --loopback or --host, not both.";
+    }
+    if (options.port !== undefined && options.port === 0) {
+        return "mono-agent web requires a stable --port between 1 and 65535.";
+    }
+    if ((options.host !== undefined || options.port !== undefined || options.loopback === true)
+        && action !== "start" && action !== "restart" && action !== "run") {
+        return "--host, --port, and --loopback are only supported for web start, restart, or run.";
+    }
+    if ((options.follow === true || options.lines !== undefined) && action !== "logs") {
+        return "--follow and --lines are only supported for mono-agent web logs.";
     }
-    const authToken = configuredAuthToken ?? (authRequired ? generateBearerToken() : undefined);
-    const generatedAuthToken = authToken !== undefined && configuredAuthToken === undefined;
+    if ((options.all === true || options.yes === true) && action !== "reset") {
+        return "--all and --yes are only supported for mono-agent web reset in this command namespace.";
+    }
+    if (action === "reset" && (options.all !== true || options.yes !== true)) {
+        return "Destructive reset requires the exact confirmation: mono-agent web reset --all --yes.";
+    }
+    return undefined;
+}
+async function runWebForeground(options, deps) {
+    const stdout = deps.stdout ?? process.stdout;
+    const stderr = deps.stderr ?? process.stderr;
+    const host = effectiveHost(options);
     const port = options.port ?? DEFAULT_WEB_PORT;
-    const startServer = deps.startServer ?? startSessionWebServer;
+    const paths = webPaths(deps.homeDir);
+    await (deps.prepareState ?? defaultPrepareWebState)({ stateDir: paths.stateDir, env: options.env });
+    const registryDir = resolveGlobalTraceRegistryDir(options.env);
+    await pruneTraceSources({ registryDir });
     let handle;
     try {
-        handle = await startServer({
-            registryDirs,
-            env: options.env,
-            ...(options.host === undefined ? {} : { host: options.host }),
-            port,
-            ...(options.allowNonLoopback === undefined ? {} : { allowNonLoopback: options.allowNonLoopback }),
-            ...(authToken === undefined ? {} : { authToken }),
-            ...(options.includeMemory === undefined ? {} : { includeMemory: options.includeMemory }),
-            ...(options.maxRunsPerInstance === undefined ? {} : { maxRunsPerInstance: options.maxRunsPerInstance }),
-        });
+        const startServer = deps.startServer ?? defaultStartWebServer;
+        handle = await startServer({ host, port, registryDirs: [registryDir], stateDir: paths.stateDir, env: options.env });
     }
     catch (error) {
-        stderr.write(`mono-agent web failed to start: ${error instanceof Error ? error.message : String(error)}\n`);
+        stderr.write(ui.errorLine(`mono-agent web failed to start: ${errorMessage(error)}`));
         return 1;
     }
-    const wildcardBind = isWildcardUrl(handle.url)
-        || (handle.boundAddress !== undefined && isWildcardHost(handle.boundAddress));
-    const networkAddresses = wildcardBind
-        ? bestEffortNetworkAddresses(deps.discoverNetworkAddresses)
-        : [];
-    const advertisedUrls = resolveAdvertisedUrls(handle.url, networkAddresses, handle.boundAddress);
-    const primaryUrl = advertisedUrls[0]?.url ?? handle.url;
-    const mayPrintConfiguredToken = configuredAuthToken !== undefined
-        && options.showAuthUrl === true
-        && interactive;
-    const printableToken = generatedAuthToken || mayPrintConfiguredToken ? authToken : undefined;
-    printAdvertisedUrls(stdout, advertisedUrls, printableToken);
-    if (configuredAuthToken !== undefined && printableToken === undefined) {
-        stdout.write(`Authentication: ${WEB_AUTH_TOKEN_ENV} is configured (token redacted).\n`);
-    }
-    if (configuredAuthToken !== undefined && options.showAuthUrl === true && !mayPrintConfiguredToken) {
-        stderr.write("--show-auth-url was ignored because stdout is not an interactive terminal.\n");
-    }
-    stdout.write(`Watching ${registryDirs.length} registr${registryDirs.length === 1 ? "y" : "ies"} for agents. Press Ctrl-C to stop.\n`);
-    stdout.write(`${reverseProxyHint(primaryUrl)}\n`);
-    stdout.write(`${reachabilityHint(handle.url, handle.boundAddress)}\n`);
-    if ((options.open ?? true) && authToken === undefined) {
-        try {
-            (deps.openUrl ?? openInBrowser)(primaryUrl);
-        }
-        catch {
-            // Best-effort: a headless host without a browser is fine — the URL is printed.
-        }
+    printWebUrls(stdout, handle.url, handle.port ?? port, host, deps.discoverNetworkAddresses);
+    stdout.write("No app authentication is enabled; network reachability is the access boundary. Press Ctrl-C to stop.\n");
+    try {
+        await (deps.waitForShutdown ?? waitForShutdownSignal)();
     }
-    else if ((options.open ?? true) && authToken !== undefined) {
-        stdout.write("Browser launch skipped in authenticated mode so the bearer token never enters process arguments.\n");
+    finally {
+        await handle.stop();
     }
-    deps.onReady?.(handle);
-    await (deps.waitForShutdown ?? waitForSignal)();
-    await handle.stop();
     stdout.write("mono-agent web stopped.\n");
     return 0;
 }
-/**
- * A one-line hint about who can reach the server. Direct HTTP never depends on
- * Tailscale Serve; Serve is only an optional HTTPS/PWA-installability layer.
- */
-function reachabilityHint(url, boundAddress) {
-    let port = "";
-    let host = "";
+async function startWebBackground(options, deps, restart) {
+    const guard = requireDarwin(deps, restart ? "restart" : "start");
+    if (guard !== undefined)
+        return guard;
+    const stdout = deps.stdout ?? process.stdout;
+    const stderr = deps.stderr ?? process.stderr;
+    const launchctl = deps.launchctl ?? makeLaunchctlRunner();
+    const getuid = deps.getuid ?? requiredUid;
+    const paths = webPaths(deps.homeDir);
     try {
-        const parsed = new URL(url);
-        port = parsed.port;
-        host = parsed.hostname;
+        await (deps.prepareState ?? defaultPrepareWebState)({ stateDir: paths.stateDir, env: options.env });
     }
-    catch {
-        /* leave blank */
+    catch (error) {
+        stderr.write(ui.errorLine(`Could not prepare the owner-private web state: ${errorMessage(error)}`));
+        return 1;
     }
-    const effectiveHost = boundAddress ?? host;
-    if (effectiveHost.length > 0 && !isLoopbackHost(effectiveHost)) {
-        return "Bound non-loopback: direct HTTP is available over your LAN/Tailnet at the URLs above. Tailscale Serve is optional and only needed for HTTPS + installable/offline PWA behavior.";
+    const release = await (deps.acquireLifecycleLock ?? acquireWebLifecycleLock)(paths);
+    if (release === undefined) {
+        stderr.write(ui.errorLine("Another mono-agent web lifecycle command is active."));
+        return 1;
     }
-    return `Loopback only. Re-run with --host 0.0.0.0 --allow-non-loopback for direct LAN/Tailnet HTTP. Tailscale Serve is optional for HTTPS + installable/offline PWA behavior (port ${port || "<port>"}).`;
-}
-function reverseProxyHint(url) {
-    let target = url;
+    let previous;
+    let previousStopped = false;
+    let replacementLaunchAttempted = false;
+    let publicationAttempted = false;
+    let publicationSnapshot;
+    const fail = async (message, error) => {
+        stderr.write(ui.errorLine(`${message}${error === undefined ? "" : `: ${errorMessage(error)}`}`));
+        if (previousStopped && previous !== undefined) {
+            const recovery = await restorePreviousWebService(previous, paths, launchctl, getuid(), deps);
+            if (recovery.ok) {
+                stderr.write(ui.style.yellow("⚠ The failed restart was rolled back and the previous web worker is running again.\n"));
+            }
+            else {
+                stderr.write(ui.style.yellow(`⚠ The failed restart could not restore the prior worker: ${recovery.detail}\n`));
+            }
+        }
+        else {
+            let safeToRestorePublication = true;
+            if (replacementLaunchAttempted) {
+                try {
+                    const replacement = await launchdServiceInfo(launchctl, WEB_LAUNCHD_LABEL, getuid());
+                    if (replacement.loaded) {
+                        const stopped = await stopLaunchdOnly(replacement, launchctl, getuid(), deps);
+                        safeToRestorePublication = stopped;
+                        stderr.write(stopped
+                            ? ui.style.yellow("⚠ The failed initial web worker was stopped.\n")
+                            : ui.style.yellow("⚠ The failed initial web worker could not be proven stopped; inspect `mono-agent web status` and logs.\n"));
+                    }
+                }
+                catch (cleanupError) {
+                    safeToRestorePublication = false;
+                    stderr.write(ui.style.yellow(`⚠ Could not clean up the failed initial web worker: ${errorMessage(cleanupError)}\n`));
+                }
+            }
+            if (publicationAttempted && publicationSnapshot !== undefined && safeToRestorePublication) {
+                try {
+                    await restoreWebPublication(paths, publicationSnapshot, deps.writePrivateFile ?? writeOwnerPrivateLaunchdFile);
+                }
+                catch (restoreError) {
+                    stderr.write(ui.style.yellow(`⚠ Could not restore the pre-start service definition: ${errorMessage(restoreError)}\n`));
+                }
+            }
+        }
+        return 1;
+    };
     try {
-        const parsed = new URL(url);
-        parsed.username = "";
-        parsed.password = "";
-        parsed.search = "";
-        parsed.hash = "";
-        target = parsed.toString();
+        const uid = getuid();
+        const existing = await launchdServiceInfo(launchctl, WEB_LAUNCHD_LABEL, uid);
+        if (existing.loaded && !restart) {
+            stdout.write(ui.style.dim("mono-agent web is already managed by launchd.\n"));
+            return await statusWeb(options, deps, true);
+        }
+        const recordRead = await readServiceRecord(paths.recordPath);
+        if (recordRead.kind === "invalid") {
+            return await fail(`Refusing to start because ${recordRead.detail}`);
+        }
+        const existingPlist = await readOptionalText(paths.launchd.plistPath);
+        publicationSnapshot = {
+            ...(existingPlist === undefined ? {} : { plist: existingPlist }),
+            ...(recordRead.kind === "valid" ? { recordText: recordRead.contents } : {}),
+        };
+        if (existing.loaded && restart) {
+            try {
+                if (existingPlist === undefined)
+                    throw new Error("the loaded LaunchAgent plist is missing");
+                if (recordRead.kind !== "valid")
+                    throw new Error("the loaded web service record is missing");
+                previous = {
+                    plist: existingPlist,
+                    recordText: recordRead.contents,
+                    record: recordRead.record,
+                };
+            }
+            catch (error) {
+                return await fail("Refusing restart because the current web service could not be snapshotted", error);
+            }
+        }
+        if (existing.loaded) {
+            const stopped = await stopLaunchdOnly(existing, launchctl, uid, deps);
+            if (!stopped) {
+                stderr.write(ui.errorLine("Could not prove the existing mono-agent web worker stopped; its definition was preserved."));
+                return 1;
+            }
+            previousStopped = restart && previous !== undefined;
+        }
+        const priorRecord = recordRead.kind === "valid" ? recordRead.record : undefined;
+        const host = effectiveHost(options, priorRecord?.host);
+        const port = options.port ?? priorRecord?.port ?? DEFAULT_WEB_PORT;
+        await ensureWebDirectories(paths);
+        const currentCliPath = fileURLToPath(new URL("./cli.js", import.meta.url));
+        let runtime;
+        try {
+            runtime = await (deps.ensureManagedRuntime ?? ((input) => ensureManagedBackgroundRuntime(input)))({
+                currentCliPath,
+                nodePath: process.execPath,
+            });
+        }
+        catch (error) {
+            return await fail("Could not install the durable web runtime", error);
+        }
+        const tailscaleRunner = deps.tailscale ?? makeTailscaleRunner(options.env);
+        const priorTailscaleOwnership = await readTailscaleOwnership(paths.tailscalePath);
+        const recordedTailscaleDnsName = priorTailscaleOwnership.kind === "valid"
+            ? tailscaleWebHostname(priorTailscaleOwnership.ownership.webKey)
+            : undefined;
+        // A healthy existing Serve route must keep working through a transient
+        // LocalAPI outage during restart. The owner-private, exact-route record is
+        // re-verified by ensureTailscaleServe after the replacement worker starts.
+        const tailscaleDnsName = await readTailscaleDnsName(tailscaleRunner, deps.sleep)
+            ?? recordedTailscaleDnsName;
+        const allowedHosts = mergeWebAllowedHosts(options.env.MONO_AGENT_WEB_ALLOWED_HOSTS, tailscaleDnsName);
+        const environment = {
+            ...selectBackgroundOperationalEnvironment(options.env),
+            PATH: defaultPathEnv(options.env),
+            ...(options.env.MONO_AGENT_GLOBAL_TRACE_REGISTRY_DIR === undefined
+                ? {}
+                : { MONO_AGENT_GLOBAL_TRACE_REGISTRY_DIR: options.env.MONO_AGENT_GLOBAL_TRACE_REGISTRY_DIR }),
+            ...(allowedHosts === undefined ? {} : { MONO_AGENT_WEB_ALLOWED_HOSTS: allowedHosts }),
+        };
+        const record = {
+            schema: WEB_SERVICE_SCHEMA,
+            host,
+            port,
+            updatedAt: new Date((deps.now ?? Date.now)()).toISOString(),
+        };
+        const plist = buildWebPlistXml({
+            label: WEB_LAUNCHD_LABEL,
+            nodePath: runtime.nodePath,
+            cliPath: runtime.cliPath,
+            cwd: paths.stateDir,
+            host,
+            port,
+            stdoutPath: paths.launchd.stdoutPath,
+            stderrPath: paths.launchd.stderrPath,
+            environment,
+        });
+        const writePrivateFile = deps.writePrivateFile ?? writeOwnerPrivateLaunchdFile;
+        publicationAttempted = true;
+        try {
+            await writePrivateFile(paths.recordPath, `${JSON.stringify(record, undefined, 2)}\n`);
+            await writePrivateFile(paths.launchd.plistPath, plist);
+        }
+        catch (error) {
+            return await fail("Could not publish the web LaunchAgent definition", error);
+        }
+        replacementLaunchAttempted = true;
+        const bootstrapped = await bootstrap(launchctl, paths.launchd.plistPath, uid);
+        if (bootstrapped.code !== 0) {
+            writeCommandDetail(stderr, bootstrapped);
+            return await fail(`launchctl could not start mono-agent web (exit ${String(bootstrapped.code)})`);
+        }
+        const ready = await waitForWebReady(host, port, launchctl, uid, deps);
+        if (!ready) {
+            stderr.write(ui.hint("Inspect `mono-agent web logs`, then retry `mono-agent web restart`."));
+            return await fail("mono-agent web did not become healthy before the startup timeout");
+        }
+        const tailscale = tailscaleDnsName === undefined
+            ? { kind: "unavailable", detail: "the node's exact Tailscale DNS name could not be resolved; no Serve handler was changed" }
+            : await ensureTailscaleServe(paths, host, port, options.env, { ...deps, tailscale: tailscaleRunner }, tailscaleDnsName);
+        if (tailscale.kind === "unavailable" && tailscale.requiresServiceRollback === true) {
+            return await fail(`Tailscale route migration failed and the replacement web worker cannot remain active: ${tailscale.detail}`);
+        }
+        stdout.write(`${ui.badge("ok")}${ui.style.bold(restart ? "Restarted mono-agent web" : "Started mono-agent web")}\n`);
+        printWebUrls(stdout, `http://${urlHost(host)}:${String(port)}/`, port, host, deps.discoverNetworkAddresses);
+        stdout.write("No app authentication is enabled; anyone who can reach this port can operate discovered agents.\n");
+        if (tailscale.kind === "active") {
+            stdout.write(`Tailscale HTTPS → ${tailscale.ownership.url}${tailscale.reused ? " (existing owned handler)" : ""}\n`);
+        }
+        else {
+            stderr.write(ui.style.yellow(`⚠ Tailscale Serve was not configured: ${tailscale.detail}\n`));
+            stderr.write(ui.hint(`LAN HTTP remains healthy on port ${String(port)}. Resolve Tailscale, then run mono-agent web restart.`));
+        }
+        return 0;
     }
-    catch {
-        /* use the original URL */
-    }
-    return `Reverse proxies should target ${target} (default port ${DEFAULT_WEB_PORT}; override with --port).`;
-}
-function requiresServerAuth(host) {
-    return host !== undefined && !isLoopbackHost(host);
-}
-function withAuthToken(url, token) {
-    const parsed = new URL(url);
-    const fragment = new URLSearchParams(parsed.hash.startsWith("#") ? parsed.hash.slice(1) : parsed.hash);
-    fragment.set("token", token);
-    parsed.hash = fragment.toString();
-    return parsed.toString();
-}
-function printAdvertisedUrls(stdout, urls, authToken) {
-    const printable = urls.map((entry) => ({
-        ...entry,
-        url: authToken === undefined ? entry.url : withAuthToken(entry.url, authToken),
-    }));
-    const primary = printable[0];
-    if (primary === undefined) {
-        return;
+    catch (error) {
+        return await fail("mono-agent web lifecycle failed", error);
     }
-    stdout.write(`mono-agent web  →  ${primary.url}\n`);
-    for (const entry of printable.slice(1)) {
-        stdout.write(`${entry.label.padEnd(9)} →  ${entry.url}\n`);
-    }
-}
-function resolveAdvertisedUrls(url, networkAddresses, boundAddress) {
-    const requestedWildcard = isWildcardUrl(url) ? new URL(url).hostname : undefined;
-    const actualWildcard = boundAddress !== undefined && isWildcardHost(boundAddress)
-        ? boundAddress
-        : undefined;
-    if (requestedWildcard === undefined && actualWildcard === undefined) {
-        return [{ label: isLoopbackUrl(url) ? "Loopback" : "Web", url }];
-    }
-    const wildcardHost = requestedWildcard ?? actualWildcard ?? new URL(url).hostname;
-    const loopbackHost = loopbackForWildcardHost(wildcardHost);
-    const urls = [{ label: "Loopback", url: replaceUrlHost(url, loopbackHost) }];
-    for (const entry of networkAddresses) {
-        urls.push({
-            label: entry.kind === "tailscale" ? "Tailscale" : "LAN",
-            url: replaceUrlHost(url, entry.address),
+    finally {
+        await release().catch((error) => {
+            stderr.write(ui.style.yellow(`⚠ Could not release the web lifecycle lock: ${errorMessage(error)}\n`));
         });
     }
-    return urls;
 }
-function loopbackForWildcardHost(host) {
-    const normalized = normalizeHostForBind(host).toLowerCase();
-    if (normalized === "0.0.0.0") {
-        return "127.0.0.1";
+async function stopWebBackground(options, deps) {
+    const guard = requireDarwin(deps, "stop");
+    if (guard !== undefined)
+        return guard;
+    const stdout = deps.stdout ?? process.stdout;
+    const stderr = deps.stderr ?? process.stderr;
+    const launchctl = deps.launchctl ?? makeLaunchctlRunner();
+    const uid = (deps.getuid ?? requiredUid)();
+    const paths = webPaths(deps.homeDir);
+    const initialService = await launchdServiceInfo(launchctl, WEB_LAUNCHD_LABEL, uid);
+    // A running worker owns the backend state lease. Stop must reach launchd
+    // bootout without opening or preparing that state first. On a pristine,
+    // already-stopped install, preparation creates a valid marked state root
+    // before the filesystem lifecycle lock needs to place its lock directory.
+    if (!initialService.loaded) {
+        try {
+            await (deps.prepareState ?? defaultPrepareWebState)({ stateDir: paths.stateDir, env: options.env });
+        }
+        catch (error) {
+            stderr.write(ui.errorLine(`Could not prepare the owner-private web state: ${errorMessage(error)}`));
+            return 1;
+        }
+    }
+    const release = await (deps.acquireLifecycleLock ?? acquireWebLifecycleLock)(paths);
+    if (release === undefined) {
+        stderr.write(ui.errorLine("Another mono-agent web lifecycle command is active."));
+        return 1;
     }
     try {
-        const canonical = new URL(`http://[${normalized}]/`).hostname.slice(1, -1);
-        if (canonical === "::ffff:0:0") {
-            return "127.0.0.1";
+        const service = await launchdServiceInfo(launchctl, WEB_LAUNCHD_LABEL, uid);
+        if (service.loaded && !await stopLaunchdOnly(service, launchctl, uid, deps)) {
+            stderr.write(ui.errorLine("Could not prove mono-agent web stopped; its LaunchAgent and Tailscale handler were preserved."));
+            return 1;
         }
+        const tailscaleResult = await removeOwnedTailscaleServe(paths, deps);
+        await rm(paths.launchd.plistPath, { force: true });
+        if (tailscaleResult.kind === "unavailable") {
+            stderr.write(ui.style.yellow(`⚠ Web stopped, but the owned Tailscale handler was preserved: ${tailscaleResult.detail}\n`));
+            return 1;
+        }
+        stdout.write(service.loaded
+            ? `${ui.badge("ok")}${ui.style.bold("Stopped mono-agent web")} and removed its LaunchAgent.\n`
+            : "mono-agent web was already stopped; removed its LaunchAgent if present.\n");
+        return 0;
     }
-    catch {
-        // isWildcardHost already validated the caller; fall through defensively.
+    finally {
+        await release().catch(() => undefined);
+    }
+}
+async function statusWeb(options, deps, strictExit) {
+    const stdout = deps.stdout ?? process.stdout;
+    const paths = webPaths(deps.homeDir);
+    const recordRead = await readServiceRecord(paths.recordPath);
+    const record = recordRead.kind === "valid" ? recordRead.record : undefined;
+    const host = record?.host ?? DEFAULT_WEB_HOST;
+    const port = record?.port ?? DEFAULT_WEB_PORT;
+    let service = { loaded: false };
+    if ((deps.platform ?? process.platform) === "darwin") {
+        service = await launchdServiceInfo(deps.launchctl ?? makeLaunchctlRunner(), WEB_LAUNCHD_LABEL, (deps.getuid ?? requiredUid)());
+    }
+    const healthy = recordRead.kind !== "invalid"
+        && service.loaded
+        && await (deps.healthcheck ?? webHealthcheck)(healthUrl(host, port));
+    stdout.write(ui.rule("Web console status"));
+    stdout.write(ui.keyValue([
+        ["service", service.loaded ? (healthy ? "running" : "loaded, not healthy") : "stopped"],
+        ["bind", recordRead.kind === "invalid" ? "invalid service record" : `${host}:${String(port)}`],
+        ["state", paths.stateDir],
+        ["pid", service.pid === undefined ? "—" : String(service.pid)],
+        ["authentication", "none (network reachability is the boundary)"],
+    ]));
+    if (recordRead.kind === "invalid")
+        stdout.write(ui.errorLine(recordRead.detail));
+    else {
+        printWebUrls(stdout, `http://${urlHost(host)}:${String(port)}/`, port, host, deps.discoverNetworkAddresses);
     }
-    return "::1";
+    const owned = await readTailscaleOwnership(paths.tailscalePath);
+    if (owned.kind === "absent") {
+        stdout.write("Tailscale HTTPS: not owned by mono-agent web.\n");
+    }
+    else if (owned.kind === "invalid") {
+        stdout.write(`Tailscale HTTPS: ${owned.detail}\n`);
+    }
+    else {
+        const inspection = await inspectOwnedTailscaleRoute(owned.ownership, deps);
+        stdout.write(inspection.kind === "exact"
+            ? `Tailscale HTTPS: ${owned.ownership.url}\n`
+            : "Tailscale HTTPS: ownership record is stale or cannot be verified; existing handlers will not be changed.\n");
+    }
+    if (!service.loaded)
+        stdout.write(ui.hint("Start it with: mono-agent web start"));
+    else if (!healthy)
+        stdout.write(ui.hint("Inspect: mono-agent web logs"));
+    return (strictExit && !healthy) || recordRead.kind === "invalid" ? 1 : 0;
 }
-function replaceUrlHost(url, host) {
-    const parsed = new URL(url);
-    parsed.hostname = hostForUrl(host);
-    return parsed.toString();
+async function tailWebLogs(options, deps) {
+    const guard = requireDarwin(deps, "logs");
+    if (guard !== undefined)
+        return guard;
+    const paths = webPaths(deps.homeDir);
+    const args = [
+        "-n",
+        String(options.lines ?? DEFAULT_LOG_LINES),
+        ...(options.follow === true ? ["-F"] : []),
+        paths.launchd.stderrPath,
+        paths.launchd.stdoutPath,
+    ];
+    return await (deps.spawnTail ?? defaultSpawnTail)(args);
 }
-function isWildcardUrl(url) {
+async function resetWeb(options, deps) {
+    const stderr = deps.stderr ?? process.stderr;
+    const stdout = deps.stdout ?? process.stdout;
+    const paths = webPaths(deps.homeDir);
+    if ((deps.platform ?? process.platform) === "darwin") {
+        const service = await launchdServiceInfo(deps.launchctl ?? makeLaunchctlRunner(), WEB_LAUNCHD_LABEL, (deps.getuid ?? requiredUid)());
+        if (service.loaded) {
+            stderr.write(ui.errorLine("Refusing to reset while mono-agent web is running."));
+            stderr.write(ui.hint("Run `mono-agent web stop`, then repeat `mono-agent web reset --all --yes`."));
+            return 1;
+        }
+    }
+    await (deps.prepareState ?? defaultPrepareWebState)({ stateDir: paths.stateDir, env: options.env });
     try {
-        const host = new URL(url).hostname;
-        return isWildcardHost(host);
+        const tailscaleOwnershipBefore = await readOptionalText(paths.tailscalePath);
+        await (deps.resetState ?? defaultResetWebState)({ stateDir: paths.stateDir, env: options.env });
+        if (tailscaleOwnershipBefore !== undefined) {
+            const after = await readOptionalText(paths.tailscalePath);
+            if (after !== tailscaleOwnershipBefore) {
+                await (deps.writePrivateFile ?? writeOwnerPrivateLaunchdFile)(paths.tailscalePath, tailscaleOwnershipBefore);
+                stderr.write(ui.errorLine("Reset changed the Tailscale ownership record; it was restored so a live route cannot become unowned."));
+                return 1;
+            }
+        }
     }
-    catch {
+    catch (error) {
+        stderr.write(ui.errorLine(`Could not reset the web console: ${errorMessage(error)}`));
+        return 1;
+    }
+    stdout.write(`${ui.badge("ok")}Reset all mono-agent web conversations, messages, attachments, and settings.\n`);
+    return 0;
+}
+async function defaultStartWebServer(options) {
+    const web = await import(WEB_PACKAGE_NAME);
+    return await web.startWebServer(options);
+}
+async function defaultResetWebState(options) {
+    const web = await import(WEB_PACKAGE_NAME);
+    await web.resetWebState(options);
+}
+async function defaultPrepareWebState(options) {
+    const web = await import(WEB_PACKAGE_NAME);
+    await web.prepareWebState(options);
+}
+function effectiveHost(options, priorHost) {
+    return options.loopback === true ? "127.0.0.1" : options.host ?? priorHost ?? DEFAULT_WEB_HOST;
+}
+async function ensureWebDirectories(paths) {
+    for (const path of [
+        dirname(paths.stateDir),
+        paths.stateDir,
+        paths.launchd.logDir,
+        paths.launchd.launchAgentsDir,
+    ]) {
+        await ensureOwnerPrivateLaunchdDirectory(path);
+    }
+}
+async function acquireWebLifecycleLock(paths) {
+    await ensureOwnerPrivateLaunchdDirectory(dirname(paths.stateDir));
+    await ensureOwnerPrivateLaunchdDirectory(paths.stateDir);
+    return await acquireFilesystemLifecycleLock({ label: WEB_LAUNCHD_LABEL, paths: paths.launchd });
+}
+async function stopLaunchdOnly(service, runner, uid, deps) {
+    const result = await bootout(runner, WEB_LAUNCHD_LABEL, uid);
+    if (result.code !== 0)
         return false;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms)));
+    const deadline = (deps.now ?? Date.now)() + READY_TIMEOUT_MS;
+    for (;;) {
+        const current = await launchdServiceInfo(runner, WEB_LAUNCHD_LABEL, uid);
+        const pidAlive = service.pid !== undefined && (deps.isAlive ?? processIsAlive)(service.pid);
+        if (!current.loaded && !pidAlive)
+            return true;
+        if ((deps.now ?? Date.now)() >= deadline)
+            return false;
+        await sleep(READY_POLL_MS);
     }
 }
-function isLoopbackUrl(url) {
+async function restorePreviousWebService(snapshot, paths, runner, uid, deps) {
     try {
-        return isLoopbackHost(new URL(url).hostname);
+        const current = await launchdServiceInfo(runner, WEB_LAUNCHD_LABEL, uid);
+        if (current.loaded && !await stopLaunchdOnly(current, runner, uid, deps)) {
+            return { ok: false, detail: "the failed replacement worker could not be stopped" };
+        }
+        const writer = deps.writePrivateFile ?? writeOwnerPrivateLaunchdFile;
+        if (snapshot.recordText === undefined)
+            await rm(paths.recordPath, { force: true });
+        else
+            await writer(paths.recordPath, snapshot.recordText);
+        await writer(paths.launchd.plistPath, snapshot.plist);
+        const booted = await bootstrap(runner, paths.launchd.plistPath, uid);
+        if (booted.code !== 0) {
+            return { ok: false, detail: commandDetail(booted) || `launchctl bootstrap exited ${String(booted.code)}` };
+        }
+        const now = deps.now ?? Date.now;
+        const sleep = deps.sleep ?? ((ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms)));
+        const deadline = now() + READY_TIMEOUT_MS;
+        for (;;) {
+            const restored = await launchdServiceInfo(runner, WEB_LAUNCHD_LABEL, uid);
+            const alive = restored.pid !== undefined && (deps.isAlive ?? processIsAlive)(restored.pid);
+            const healthy = snapshot.record === undefined
+                ? true
+                : await (deps.healthcheck ?? webHealthcheck)(healthUrl(snapshot.record.host, snapshot.record.port));
+            if (restored.loaded && alive && healthy)
+                return { ok: true };
+            if (now() >= deadline)
+                return { ok: false, detail: "the restored LaunchAgent did not become healthy" };
+            await sleep(READY_POLL_MS);
+        }
+    }
+    catch (error) {
+        return { ok: false, detail: errorMessage(error) };
+    }
+}
+async function restoreWebPublication(paths, snapshot, writer) {
+    if (snapshot.recordText === undefined)
+        await rm(paths.recordPath, { force: true });
+    else
+        await writer(paths.recordPath, snapshot.recordText);
+    if (snapshot.plist === undefined)
+        await rm(paths.launchd.plistPath, { force: true });
+    else
+        await writer(paths.launchd.plistPath, snapshot.plist);
+}
+async function waitForWebReady(host, port, launchctl, uid, deps) {
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms)));
+    const healthcheck = deps.healthcheck ?? webHealthcheck;
+    const deadline = now() + READY_TIMEOUT_MS;
+    for (;;) {
+        const service = await launchdServiceInfo(launchctl, WEB_LAUNCHD_LABEL, uid);
+        if (service.loaded && service.pid !== undefined && (deps.isAlive ?? processIsAlive)(service.pid)
+            && await healthcheck(healthUrl(host, port)))
+            return true;
+        if (now() >= deadline)
+            return false;
+        await sleep(READY_POLL_MS);
+    }
+}
+function healthUrl(host, port) {
+    const checkHost = host === "0.0.0.0" || host === "::" || host === "[::]" ? "127.0.0.1" : urlHost(host);
+    return `http://${checkHost}:${String(port)}/healthz`;
+}
+export async function webHealthcheck(url) {
+    try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(1_000) });
+        if (!response.ok || response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() !== "application/json") {
+            return false;
+        }
+        const body = await response.json();
+        return isRecord(body)
+            && hasExactKeys(body, ["status", "version"])
+            && body.status === "ok"
+            && body.version === 1;
     }
     catch {
         return false;
     }
 }
-function bestEffortNetworkAddresses(injected) {
+export async function ensureTailscaleServe(paths, bindHost, appPort, env, deps, expectedDnsName) {
+    const runner = deps.tailscale ?? makeTailscaleRunner(env);
+    const proxyTarget = tailscaleProxyTarget(bindHost, appPort);
+    const ownershipRead = await readTailscaleOwnership(paths.tailscalePath);
+    if (ownershipRead.kind === "invalid") {
+        return { kind: "unavailable", detail: ownershipRead.detail };
+    }
+    let existing = ownershipRead.kind === "valid" ? ownershipRead.ownership : undefined;
+    let priorMigration;
+    const failMigration = async (detail) => {
+        if (priorMigration === undefined)
+            return { kind: "unavailable", detail };
+        const restored = await restorePriorTailscaleRoute(paths, priorMigration.ownership, priorMigration.contents, runner, deps);
+        return { kind: "unavailable", detail: `${detail}; ${restored}`, requiresServiceRollback: true };
+    };
+    if (proxyTarget === undefined) {
+        return {
+            kind: "unavailable",
+            detail: `bind host ${bindHost} is not reachable through a loopback proxy; use --host 0.0.0.0, --host ::, or --loopback`,
+        };
+    }
+    if (existing !== undefined) {
+        const inspection = await inspectOwnedTailscaleRoute(existing, deps, runner);
+        if (inspection.kind === "absent") {
+            const cleared = await clearProvablyAbsentTailscaleOwnership(paths, existing, runner);
+            if (cleared.kind === "unavailable")
+                return { kind: "unavailable", detail: cleared.detail };
+            existing = undefined;
+        }
+        else if (inspection.kind !== "exact") {
+            return {
+                kind: "unavailable",
+                detail: inspection.kind === "unavailable"
+                    ? inspection.detail
+                    : "the prior Tailscale ownership record no longer matches its exact handler; refusing to overwrite it",
+            };
+        }
+    }
+    if (existing !== undefined) {
+        if (expectedDnsName !== undefined && tailscaleWebHostname(existing.webKey) !== expectedDnsName) {
+            return {
+                kind: "unavailable",
+                detail: "the owned Tailscale handler hostname does not match this node's exact DNS name; refusing to reuse or replace it",
+            };
+        }
+        if (proxyTarget !== undefined && existing.proxyTarget === proxyTarget) {
+            return { kind: "active", ownership: existing, reused: true };
+        }
+        if (ownershipRead.kind !== "valid") {
+            return { kind: "unavailable", detail: "the prior Tailscale ownership record changed during migration; refusing to remove its handler" };
+        }
+        priorMigration = { ownership: existing, contents: ownershipRead.contents };
+        const removed = await removeOwnedTailscaleServe(paths, { ...deps, tailscale: runner });
+        if (removed.kind === "unavailable") {
+            return await failMigration(`could not migrate the prior exact Tailscale handler: ${removed.detail}`);
+        }
+    }
+    const initial = await readTailscaleServeStatus(runner);
+    if (initial.kind === "error")
+        return await failMigration(initial.detail);
+    const httpsPort = chooseTailscaleHttpsPort(initial.status);
+    if (httpsPort === undefined) {
+        return await failMigration("ports 443 and 8443-8499 are already assigned; no handler was changed");
+    }
+    const configured = await runner(["serve", "--bg", `--https=${String(httpsPort)}`, proxyTarget]);
+    if (configured.code !== 0) {
+        return await failMigration(commandDetail(configured) || `tailscale serve exited ${String(configured.code)}`);
+    }
+    const [after, observedDnsName] = await Promise.all([
+        readTailscaleServeStatus(runner),
+        readTailscaleDnsName(runner, deps.sleep),
+    ]);
+    if (after.kind === "error") {
+        const rollback = await rollbackJustCreatedTailscaleRoute(runner, httpsPort, proxyTarget, expectedDnsName ?? observedDnsName);
+        return await failMigration(`handler command succeeded but verification failed: ${after.detail}; ${rollback}`);
+    }
+    if (expectedDnsName !== undefined && observedDnsName !== expectedDnsName) {
+        const rollback = await rollbackJustCreatedTailscaleRoute(runner, httpsPort, proxyTarget, observedDnsName);
+        return await failMigration(`handler command succeeded but the node's exact Tailscale DNS name changed or became unavailable; ${rollback}`);
+    }
+    const dnsName = expectedDnsName ?? observedDnsName;
+    const webKey = findTailscaleWebKey(after.status, httpsPort, proxyTarget, dnsName);
+    if (webKey === undefined) {
+        const rollback = await rollbackJustCreatedTailscaleRoute(runner, httpsPort, proxyTarget, dnsName);
+        return await failMigration(`handler command succeeded but the exact proxy target could not be verified; ${rollback}`);
+    }
+    if (!isExactExpectedTailscaleRoute(after.status, webKey, httpsPort, proxyTarget)) {
+        const rollback = await rollbackJustCreatedTailscaleRoute(runner, httpsPort, proxyTarget, dnsName);
+        return await failMigration(`handler command succeeded but its TCP or Web handler set was not the exact root Proxy-only shape; ${rollback}`);
+    }
+    if (expectedDnsName !== undefined && tailscaleWebHostname(webKey) !== expectedDnsName) {
+        const rollback = await rollbackJustCreatedTailscaleRoute(runner, httpsPort, proxyTarget, dnsName);
+        return await failMigration(`handler command succeeded under an unexpected Tailscale hostname; ${rollback}`);
+    }
+    const hostname = webKey.slice(0, webKey.lastIndexOf(":"));
+    const ownership = {
+        schema: TAILSCALE_OWNERSHIP_SCHEMA,
+        webKey,
+        httpsPort,
+        proxyTarget,
+        configSha256: tailscalePortConfigSha256(after.status, webKey, httpsPort),
+        url: `https://${hostname}${httpsPort === 443 ? "" : `:${String(httpsPort)}`}/`,
+        configuredAt: new Date((deps.now ?? Date.now)()).toISOString(),
+    };
     try {
-        return dedupeNetworkAddresses(injected?.() ?? discoverNetworkAddresses());
+        await (deps.writePrivateFile ?? writeOwnerPrivateLaunchdFile)(paths.tailscalePath, `${JSON.stringify(ownership, undefined, 2)}\n`);
     }
-    catch {
-        return [];
+    catch (error) {
+        const rollback = await rollbackExactTailscaleRoute(runner, after.status, ownership);
+        return await failMigration(`could not durably record Tailscale handler ownership: ${errorMessage(error)}; ${rollback}`);
     }
+    return { kind: "active", ownership, reused: false };
 }
-function discoverNetworkAddresses() {
-    const addresses = [];
-    for (const interfaces of Object.values(networkInterfaces())) {
-        for (const info of interfaces ?? []) {
-            if (info.internal || info.family !== "IPv4") {
-                continue;
-            }
-            const kind = classifyIpv4Address(info.address);
-            if (kind !== undefined) {
-                addresses.push({ address: info.address, kind });
-            }
+async function restorePriorTailscaleRoute(paths, ownership, ownershipContents, runner, deps) {
+    const before = await readTailscaleServeStatus(runner);
+    if (before.kind === "error")
+        return `the prior HTTPS route could not be restored because status failed: ${before.detail}`;
+    const tcp = isRecord(before.status.TCP) ? before.status.TCP : {};
+    if (Object.hasOwn(tcp, String(ownership.httpsPort))) {
+        return "the prior HTTPS route could not be restored because its port is no longer free; its old ownership record was not republished";
+    }
+    const configured = await runner([
+        "serve",
+        "--bg",
+        `--https=${String(ownership.httpsPort)}`,
+        ownership.proxyTarget,
+    ]);
+    if (configured.code !== 0) {
+        return `the prior HTTPS route could not be restored: ${commandDetail(configured) || `exit ${String(configured.code)}`}`;
+    }
+    const after = await readTailscaleServeStatus(runner);
+    if (after.kind === "error" || !routeMatches(after.status, ownership)) {
+        if (after.kind === "ok") {
+            await rollbackJustCreatedTailscaleRoute(runner, ownership.httpsPort, ownership.proxyTarget, undefined);
         }
+        return "the prior HTTPS route command succeeded but its exact previous handler set was not restored";
+    }
+    try {
+        await (deps.writePrivateFile ?? writeOwnerPrivateLaunchdFile)(paths.tailscalePath, ownershipContents);
+    }
+    catch (error) {
+        const rollback = await rollbackExactTailscaleRoute(runner, after.status, ownership);
+        return `the prior HTTPS route was recreated but ownership could not be republished (${errorMessage(error)}); ${rollback}`;
     }
-    return addresses;
+    return "the prior exact HTTPS route and ownership record were restored";
 }
-function classifyIpv4Address(address) {
-    const octets = address.split(".").map((part) => Number.parseInt(part, 10));
-    if (octets.length !== 4 || octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+export function tailscaleProxyTarget(bindHost, appPort) {
+    const normalized = bindHost.startsWith("[") && bindHost.endsWith("]")
+        ? bindHost.slice(1, -1).toLowerCase()
+        : bindHost.toLowerCase();
+    if (normalized === "0.0.0.0") {
+        return `http://127.0.0.1:${String(appPort)}`;
+    }
+    if (normalized === "::")
+        return `http://[::1]:${String(appPort)}`;
+    // Node may resolve localhost to either loopback family. Without the actual
+    // bound address, publishing a numeric Serve target could point at the other
+    // family. --loopback is the deterministic 127.0.0.1 spelling.
+    if (normalized === "localhost")
+        return undefined;
+    if (!isLoopbackHost(normalized))
         return undefined;
+    return `http://${urlHost(normalized)}:${String(appPort)}`;
+}
+async function rollbackJustCreatedTailscaleRoute(runner, httpsPort, proxyTarget, dnsName) {
+    const current = await readTailscaleServeStatus(runner);
+    if (current.kind === "error") {
+        return `rollback could not verify an exact handler (${current.detail}); no unrelated handler was changed`;
+    }
+    const webKey = findTailscaleWebKey(current.status, httpsPort, proxyTarget, dnsName);
+    if (webKey === undefined)
+        return "no exact newly-created handler remained to remove";
+    if (!isExactExpectedTailscaleRoute(current.status, webKey, httpsPort, proxyTarget)) {
+        return "rollback refused because the newly-created port no longer had the exact root Proxy-only shape";
+    }
+    const ownership = {
+        schema: TAILSCALE_OWNERSHIP_SCHEMA,
+        webKey,
+        httpsPort,
+        proxyTarget,
+        configSha256: tailscalePortConfigSha256(current.status, webKey, httpsPort),
+        url: "",
+        configuredAt: new Date(0).toISOString(),
+    };
+    return await rollbackExactTailscaleRoute(runner, current.status, ownership);
+}
+async function rollbackExactTailscaleRoute(runner, status, ownership) {
+    if (!routeMatches(status, ownership))
+        return "rollback refused because the handler no longer matched exactly";
+    const removed = await runner(["serve", `--https=${String(ownership.httpsPort)}`, "off"]);
+    return removed.code === 0
+        ? "the exact newly-created handler was rolled back"
+        : `rollback of the exact newly-created handler failed: ${commandDetail(removed) || `exit ${String(removed.code)}`}`;
+}
+export async function removeOwnedTailscaleServe(paths, deps) {
+    const ownershipRead = await readTailscaleOwnership(paths.tailscalePath);
+    if (ownershipRead.kind === "absent")
+        return { kind: "absent" };
+    if (ownershipRead.kind === "invalid")
+        return { kind: "unavailable", detail: ownershipRead.detail };
+    const ownership = ownershipRead.ownership;
+    const runner = deps.tailscale ?? makeTailscaleRunner(process.env);
+    const inspection = await inspectOwnedTailscaleRoute(ownership, deps, runner);
+    if (inspection.kind === "absent") {
+        return await clearProvablyAbsentTailscaleOwnership(paths, ownership, runner);
+    }
+    if (inspection.kind !== "exact") {
+        return { kind: "unavailable", detail: "the recorded handler no longer matches its exact host, port, and proxy target; refusing to remove it" };
     }
-    const [first = -1, second = -1] = octets;
-    if (first === 100 && second >= 64 && second <= 127) {
-        return "tailscale";
+    const removed = await runner(["serve", `--https=${String(ownership.httpsPort)}`, "off"]);
+    if (removed.code !== 0) {
+        return { kind: "unavailable", detail: commandDetail(removed) || `tailscale serve off exited ${String(removed.code)}` };
     }
-    if (first === 10
-        || (first === 172 && second >= 16 && second <= 31)
-        || (first === 192 && second === 168)) {
-        return "lan";
+    const after = await readTailscaleServeStatus(runner);
+    if (after.kind === "error" || routeMatches(after.status, ownership)) {
+        return { kind: "unavailable", detail: after.kind === "error" ? after.detail : "the handler is still present after tailscale serve off" };
+    }
+    await rm(paths.tailscalePath, { force: true });
+    return { kind: "removed" };
+}
+async function inspectOwnedTailscaleRoute(ownership, deps, suppliedRunner) {
+    const status = await readTailscaleServeStatus(suppliedRunner ?? deps.tailscale ?? makeTailscaleRunner(process.env));
+    if (status.kind === "error")
+        return { kind: "unavailable", detail: status.detail };
+    return classifyOwnedTailscaleRoute(status.status, ownership);
+}
+function classifyOwnedTailscaleRoute(status, ownership) {
+    if (routeMatches(status, ownership))
+        return { kind: "exact" };
+    const tcp = isRecord(status.TCP) ? status.TCP : {};
+    const web = isRecord(status.Web) ? status.Web : {};
+    if (!Object.hasOwn(tcp, String(ownership.httpsPort)) && !Object.hasOwn(web, ownership.webKey)) {
+        return { kind: "absent" };
+    }
+    return { kind: "changed" };
+}
+async function clearProvablyAbsentTailscaleOwnership(paths, ownership, runner) {
+    const confirmation = await readTailscaleServeStatus(runner);
+    if (confirmation.kind === "error")
+        return { kind: "unavailable", detail: confirmation.detail };
+    if (classifyOwnedTailscaleRoute(confirmation.status, ownership).kind !== "absent") {
+        return { kind: "unavailable", detail: "the recorded Tailscale handler changed while confirming its absence; ownership was preserved" };
+    }
+    await rm(paths.tailscalePath, { force: true });
+    return { kind: "absent" };
+}
+async function readTailscaleServeStatus(runner) {
+    const result = await runner(["serve", "status", "--json"]);
+    if (result.code !== 0) {
+        return { kind: "error", detail: commandDetail(result) || `tailscale serve status exited ${String(result.code)}` };
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        if (!isRecord(parsed))
+            throw new Error("expected an object");
+        return { kind: "ok", status: parsed };
+    }
+    catch (error) {
+        return { kind: "error", detail: `tailscale serve status returned invalid JSON: ${errorMessage(error)}` };
+    }
+}
+export function chooseTailscaleHttpsPort(status) {
+    const tcp = isRecord(status.TCP) ? status.TCP : {};
+    for (const port of [443, ...integerRange(TAILSCALE_FALLBACK_PORT_START, TAILSCALE_FALLBACK_PORT_END)]) {
+        if (!Object.hasOwn(tcp, String(port)))
+            return port;
     }
     return undefined;
 }
-function dedupeNetworkAddresses(addresses) {
-    const seen = new Set();
-    return [...addresses]
-        .filter((entry) => {
-        if (seen.has(entry.address)) {
-            return false;
-        }
-        seen.add(entry.address);
-        return true;
-    })
-        .sort((left, right) => {
-        if (left.kind !== right.kind) {
-            return left.kind === "lan" ? -1 : 1;
+function findTailscaleWebKey(status, port, proxyTarget, dnsName) {
+    const web = isRecord(status.Web) ? status.Web : {};
+    const preferred = dnsName === undefined ? undefined : `${dnsName}:${String(port)}`;
+    if (preferred !== undefined && webHandlerProxy(web[preferred]) === proxyTarget)
+        return preferred;
+    return Object.keys(web).find((key) => key.endsWith(`:${String(port)}`) && webHandlerProxy(web[key]) === proxyTarget);
+}
+function tailscaleWebHostname(webKey) {
+    return webKey.slice(0, webKey.lastIndexOf(":"));
+}
+function routeMatches(status, ownership) {
+    const tcp = isRecord(status.TCP) ? status.TCP : {};
+    const port = tcp[String(ownership.httpsPort)];
+    const web = isRecord(status.Web) ? status.Web : {};
+    return isRecord(port)
+        && port.HTTPS === true
+        && webHandlerProxy(web[ownership.webKey]) === ownership.proxyTarget
+        && tailscalePortConfigSha256(status, ownership.webKey, ownership.httpsPort) === ownership.configSha256;
+}
+function isExactExpectedTailscaleRoute(status, webKey, httpsPort, proxyTarget) {
+    const tcp = isRecord(status.TCP) ? status.TCP : {};
+    const port = tcp[String(httpsPort)];
+    const web = isRecord(status.Web) ? status.Web : {};
+    const entry = web[webKey];
+    if (!isRecord(port) || !hasExactKeys(port, ["HTTPS"]) || port.HTTPS !== true)
+        return false;
+    if (!isRecord(entry) || !hasExactKeys(entry, ["Handlers"]) || !isRecord(entry.Handlers))
+        return false;
+    if (!hasExactKeys(entry.Handlers, ["/"]) || !isRecord(entry.Handlers["/"]))
+        return false;
+    return hasExactKeys(entry.Handlers["/"], ["Proxy"])
+        && entry.Handlers["/"].Proxy === proxyTarget;
+}
+function hasExactKeys(value, expected) {
+    const actual = Object.keys(value).sort();
+    const sortedExpected = [...expected].sort();
+    return actual.length === sortedExpected.length && actual.every((key, index) => key === sortedExpected[index]);
+}
+function tailscalePortConfigSha256(status, webKey, httpsPort) {
+    const tcp = isRecord(status.TCP) ? status.TCP : {};
+    const web = isRecord(status.Web) ? status.Web : {};
+    const canonical = canonicalJson({ tcp: tcp[String(httpsPort)], web: web[webKey] });
+    return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (isRecord(value)) {
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function webHandlerProxy(value) {
+    if (!isRecord(value) || !isRecord(value.Handlers) || !isRecord(value.Handlers["/"]))
+        return undefined;
+    return typeof value.Handlers["/"].Proxy === "string" ? value.Handlers["/"].Proxy : undefined;
+}
+async function readTailscaleDnsName(runner, suppliedSleep) {
+    const sleep = suppliedSleep ?? ((ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms)));
+    for (let attempt = 0; attempt < TAILSCALE_STATUS_ATTEMPTS; attempt += 1) {
+        const result = await runner(["status", "--json"]);
+        if (result.code === 0) {
+            try {
+                const parsed = JSON.parse(result.stdout);
+                if (isRecord(parsed) && isRecord(parsed.Self) && typeof parsed.Self.DNSName === "string") {
+                    return parsed.Self.DNSName.replace(/\.$/u, "").toLowerCase();
+                }
+            }
+            catch {
+                // A transiently truncated LocalAPI response is retried below.
+            }
         }
-        return left.address.localeCompare(right.address);
+        if (attempt + 1 < TAILSCALE_STATUS_ATTEMPTS)
+            await sleep(TAILSCALE_STATUS_RETRY_MS);
+    }
+    return undefined;
+}
+function makeTailscaleRunner(env) {
+    return (args) => spawnCapture("tailscale", args, env);
+}
+function spawnCapture(command, args, env) {
+    return new Promise((resolvePromise) => {
+        const child = spawn(command, [...args], { stdio: ["ignore", "pipe", "pipe"], env: env });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => { stdout += chunk; });
+        child.stderr.on("data", (chunk) => { stderr += chunk; });
+        child.on("error", (error) => resolvePromise({ code: 127, stdout, stderr: `${stderr}${error.message}` }));
+        child.on("close", (code) => resolvePromise({ code: code ?? 1, stdout, stderr }));
     });
 }
-/** Resolve + dedupe registry dirs, preserving precedence order. */
-function dedupePaths(dirs) {
-    const seen = new Set();
-    const out = [];
-    for (const dir of dirs) {
-        const resolved = resolve(dir);
-        if (!seen.has(resolved)) {
-            seen.add(resolved);
-            out.push(resolved);
-        }
+async function readServiceRecord(path) {
+    let contents;
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT")
+            return { kind: "absent" };
+        return { kind: "invalid", detail: "the web service record is unreadable; repair or remove ~/.mono-agent/web/service.json" };
+    }
+    let value;
+    try {
+        value = JSON.parse(contents);
+    }
+    catch {
+        return { kind: "invalid", detail: "the web service record is malformed; repair or remove ~/.mono-agent/web/service.json" };
+    }
+    if (!isRecord(value) || value.schema !== WEB_SERVICE_SCHEMA || typeof value.host !== "string"
+        || !Number.isSafeInteger(value.port) || value.port < 1 || value.port > 65_535
+        || typeof value.updatedAt !== "string") {
+        return { kind: "invalid", detail: "the web service record has an invalid schema; repair or remove ~/.mono-agent/web/service.json" };
+    }
+    return { kind: "valid", record: value, contents };
+}
+async function readTailscaleOwnership(path) {
+    let contents;
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT")
+            return { kind: "absent" };
+        return { kind: "invalid", detail: "the Tailscale ownership record is unreadable; refusing to change any Serve handler" };
+    }
+    let value;
+    try {
+        value = JSON.parse(contents);
+    }
+    catch {
+        return { kind: "invalid", detail: "the Tailscale ownership record is malformed; refusing to change any Serve handler" };
+    }
+    if (!isRecord(value) || value.schema !== TAILSCALE_OWNERSHIP_SCHEMA
+        || typeof value.webKey !== "string" || typeof value.proxyTarget !== "string" || typeof value.url !== "string"
+        || typeof value.configSha256 !== "string" || !/^[0-9a-f]{64}$/u.test(value.configSha256)
+        || typeof value.configuredAt !== "string" || !Number.isSafeInteger(value.httpsPort)
+        || value.httpsPort < 1 || value.httpsPort > 65_535) {
+        return { kind: "invalid", detail: "the Tailscale ownership record has an invalid schema; refusing to change any Serve handler" };
+    }
+    return { kind: "valid", ownership: value, contents };
+}
+async function readOptionalText(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT")
+            return undefined;
+        throw error;
     }
-    return out;
 }
-/** Resolve once SIGINT/SIGTERM arrives — the foreground command's stop signal. */
-function waitForSignal() {
+function requireDarwin(deps, action) {
+    if ((deps.platform ?? process.platform) === "darwin")
+        return undefined;
+    (deps.stderr ?? process.stderr).write(ui.errorLine(`mono-agent web ${action} background management requires macOS launchd; use mono-agent web run on this platform.`));
+    return 1;
+}
+function requiredUid() {
+    if (typeof process.getuid !== "function")
+        throw new Error("launchd requires a numeric user id");
+    return process.getuid();
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return isRecord(error) && error.code === "EPERM";
+    }
+}
+function waitForShutdownSignal() {
     return new Promise((resolvePromise) => {
-        const onSignal = () => {
-            process.off("SIGINT", onSignal);
-            process.off("SIGTERM", onSignal);
+        const done = () => {
+            process.off("SIGINT", done);
+            process.off("SIGTERM", done);
             resolvePromise();
         };
-        process.once("SIGINT", onSignal);
-        process.once("SIGTERM", onSignal);
+        process.once("SIGINT", done);
+        process.once("SIGTERM", done);
     });
 }
-/** Best-effort OS browser launch. Never throws into the caller's happy path. */
-function openInBrowser(url) {
-    void (async () => {
-        try {
-            const { spawn } = await import("node:child_process");
-            const platform = process.platform;
-            const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
-            const args = platform === "win32" ? ["/c", "start", "", url] : [url];
-            const child = spawn(command, args, { stdio: "ignore", detached: true });
-            child.on("error", () => {
-                /* no browser available — the URL was printed */
-            });
-            child.unref();
+function defaultSpawnTail(args) {
+    return new Promise((resolvePromise) => {
+        const child = spawn("tail", [...args], { stdio: "inherit" });
+        child.on("error", () => resolvePromise(127));
+        child.on("close", (code) => resolvePromise(code ?? 0));
+    });
+}
+function printWebUrls(stdout, serverUrl, port, host, discover) {
+    if (host === "0.0.0.0" || host === "::" || host === "[::]") {
+        const ipv6Bind = host === "::" || host === "[::]";
+        stdout.write(`Local      → http://${ipv6Bind ? "[::1]" : "127.0.0.1"}:${String(port)}/\n`);
+        for (const address of advertisableNetworkAddresses((discover ?? discoverNetworkAddresses)())
+            .filter((candidate) => candidate.includes(":") === ipv6Bind)) {
+            const label = isTailscaleAddress(address) ? "Tailscale" : "LAN";
+            stdout.write(`${label.padEnd(10)} → http://${urlHost(address)}:${String(port)}/\n`);
         }
-        catch {
-            /* ignore */
+        return;
+    }
+    stdout.write(`Web        → ${serverUrl.endsWith("/") ? serverUrl : `${serverUrl}/`}\n`);
+}
+function isTailscaleAddress(address) {
+    const normalized = normalizeNetworkAddress(address);
+    if (normalized.split("%", 1)[0]?.startsWith("fd7a:115c:a1e0:"))
+        return true;
+    const match = /^(\d{1,3})\.(\d{1,3})\./u.exec(normalized);
+    if (match?.[1] !== "100" || match[2] === undefined)
+        return false;
+    const second = Number(match[2]);
+    return second >= 64 && second <= 127;
+}
+function discoverNetworkAddresses() {
+    const addresses = [];
+    for (const entries of Object.values(networkInterfaces())) {
+        for (const entry of entries ?? []) {
+            if (!entry.internal && (entry.family === "IPv4" || entry.family === "IPv6"))
+                addresses.push(entry.address);
         }
-    })();
+    }
+    return advertisableNetworkAddresses(addresses);
+}
+function advertisableNetworkAddresses(addresses) {
+    return [...new Set(addresses.map(normalizeNetworkAddress).filter(isAdvertisableNetworkAddress))]
+        .sort((left, right) => left.localeCompare(right, "en", { numeric: true, sensitivity: "base" }));
+}
+function normalizeNetworkAddress(address) {
+    const unbracketed = address.startsWith("[") && address.endsWith("]") ? address.slice(1, -1) : address;
+    return unbracketed.toLowerCase();
+}
+function mergeWebAllowedHosts(configured, tailscaleDnsName) {
+    const hosts = [
+        ...(configured?.split(",") ?? []),
+        ...(tailscaleDnsName === undefined ? [] : [tailscaleDnsName]),
+    ].map((host) => host.trim()).filter((host) => host.length > 0);
+    const merged = [...new Set(hosts)].join(",");
+    return merged.length === 0 ? undefined : merged;
+}
+function isAdvertisableNetworkAddress(address) {
+    const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/u.exec(address);
+    if (ipv4 !== null) {
+        const octets = ipv4.slice(1).map(Number);
+        if (octets.some((value) => value > 255))
+            return false;
+        const [first = -1, second = -1] = octets;
+        return first === 10
+            || (first === 172 && second >= 16 && second <= 31)
+            || (first === 192 && second === 168)
+            || (first === 100 && second >= 64 && second <= 127)
+            || (first === 169 && second === 254);
+    }
+    const [literal = ""] = address.split("%", 2);
+    const firstHextet = Number.parseInt(literal.split(":", 1)[0] ?? "", 16);
+    if (!Number.isFinite(firstHextet))
+        return false;
+    // Browser URL implementations do not consistently support IPv6 zone IDs,
+    // so even scoped link-local literals are not advertised as concrete links.
+    return (firstHextet & 0xfe00) === 0xfc00;
+}
+function urlHost(host) {
+    const normalized = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+    return normalized.includes(":") ? `[${normalized.replace("%", "%25")}]` : normalized;
+}
+function commandDetail(result) {
+    return (result.stderr || result.stdout).trim();
+}
+function writeCommandDetail(stream, result) {
+    const detail = commandDetail(result);
+    if (detail.length > 0)
+        stream.write(ui.style.dim(detail) + "\n");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function integerRange(start, end) {
+    return Array.from({ length: end - start + 1 }, (_, index) => start + index);
 }
 //# sourceMappingURL=web-command.js.map