@abot-ai/runtime 1.3.0 → 1.4.0

package/dist/src/web-ui/system-host-setup/installer-contract.js

@@ -0,0 +1,51 @@
+import { isNativeLoopbackAddress } from "../../../plugins/system/source/companion/native-address.js";
+export class InstallerInputError extends Error {
+}
+function hasLocalInstallerHost(hostname) {
+    if (hostname === "localhost")
+        return true;
+    if (hostname.endsWith(".localhost"))
+        return true;
+    return isNativeLoopbackAddress(hostname);
+}
+export function validateCompanionInstaller(input) {
+    if (!["windows", "macos"].includes(input.platform))
+        throw new InstallerInputError("Choose Windows or macOS.");
+    if (/[\x00-\x1f\x7f]/u.test(input.url))
+        throw new InstallerInputError("The Runtime origin must not contain control characters.");
+    let url;
+    try {
+        url = new URL(input.url);
+    }
+    catch {
+        throw new InstallerInputError("The setup address is not a valid Runtime origin.");
+    }
+    if (url.protocol !== "http:")
+        throw new InstallerInputError("Downloaded setup currently requires a local HTTP Runtime address. HTTPS setup is not supported; certificate verification is never disabled.");
+    if (url.username || url.password || url.search || url.hash || url.pathname !== "/")
+        throw new InstallerInputError("Use a Runtime origin without credentials, a path, query or fragment.");
+    if (!hasLocalInstallerHost(url.hostname))
+        throw new InstallerInputError("Setup can connect only to a Runtime on this computer's loopback interface.");
+    if (!/^[A-Za-z0-9_-]{43}$/u.test(input.code))
+        throw new InstallerInputError("The pairing code is invalid.");
+    if (!/^[a-f0-9]{64}$/iu.test(input.bundleSha256))
+        throw new InstallerInputError("The companion bundle checksum is invalid.");
+    if (!Number.isFinite(Date.parse(input.expiresAt)))
+        throw new InstallerInputError("The pairing expiration is invalid.");
+    return { ...input, url: url.origin, expiresAt: new Date(input.expiresAt).toISOString(), bundleSha256: input.bundleSha256.toLowerCase() };
+}
+export function validateWslDistribution(distribution) {
+    if (distribution === undefined)
+        return undefined;
+    if (!/^[A-Za-z0-9][A-Za-z0-9._ -]{0,127}$/u.test(distribution))
+        throw new InstallerInputError("The WSL distribution name is invalid.");
+    if (distribution.toLowerCase().startsWith("docker-desktop"))
+        throw new InstallerInputError("Docker Desktop internal distributions cannot be changed by this setup.");
+    return distribution;
+}
+export function installerMetadataBase64(value) {
+    return Buffer.from(JSON.stringify(value), "utf8").toString("base64");
+}
+export function shellString(value) {
+    return "'" + value.replaceAll("'", "'\"'\"'") + "'";
+}

package/dist/src/web-ui/system-host-setup/installers.d.ts

@@ -0,0 +1,6 @@
+import { type CompanionInstallerInput, type InstallerDownload } from "./installer-contract.js";
+export { InstallerInputError } from "./installer-contract.js";
+export declare function renderCompanionInstaller(raw: CompanionInstallerInput): Promise<InstallerDownload>;
+export declare function renderWslInteropInstaller(input: Readonly<{
+    distribution?: string;
+}>): Promise<InstallerDownload>;

package/dist/src/web-ui/system-host-setup/installers.js

@@ -0,0 +1,30 @@
+import JSZip from "jszip";
+import { validateCompanionInstaller, validateWslDistribution, } from "./installer-contract.js";
+import { renderWindowsCompanionScript } from "./companion-windows.js";
+import { renderMacCompanionScript } from "./companion-macos.js";
+import { renderWindowsWslInteropScript } from "./wsl-interop-windows.js";
+export { InstallerInputError } from "./installer-contract.js";
+export async function renderCompanionInstaller(raw) {
+    const input = validateCompanionInstaller(raw);
+    if (input.platform === "windows")
+        return {
+            filename: "ABot-Connect-Computer.cmd",
+            mimeType: "application/octet-stream",
+            contentBase64: Buffer.from(renderWindowsCompanionScript(input), "utf8").toString("base64"),
+        };
+    const zip = new JSZip();
+    zip.file("ABot-Connect-Computer.command", renderMacCompanionScript(input), { unixPermissions: 0o100755 });
+    return {
+        filename: "ABot-Connect-Computer-macOS.zip",
+        mimeType: "application/zip",
+        contentBase64: await zip.generateAsync({ type: "base64", platform: "UNIX", compression: "DEFLATE" }),
+    };
+}
+export async function renderWslInteropInstaller(input) {
+    const distribution = validateWslDistribution(input.distribution);
+    return {
+        filename: "ABot-Enable-WSL-Interop.cmd",
+        mimeType: "application/octet-stream",
+        contentBase64: Buffer.from(renderWindowsWslInteropScript(distribution), "utf8").toString("base64"),
+    };
+}

package/dist/src/web-ui/system-host-setup/native-authorization.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage } from "node:http";
+/** Native downloads and sockets do not accept browser-origin credentials. */
+export declare function hostBearerCredential(request: IncomingMessage): string | undefined;

package/dist/src/web-ui/system-host-setup/native-authorization.js

@@ -0,0 +1,11 @@
+/** Native downloads and sockets do not accept browser-origin credentials. */
+export function hostBearerCredential(request) {
+    if (request.headers.origin !== undefined)
+        return undefined;
+    if (request.headers["sec-fetch-site"] !== undefined)
+        return undefined;
+    const header = request.headers.authorization;
+    if (typeof header !== "string")
+        return undefined;
+    return /^Bearer ([A-Za-z0-9_-]{43})$/u.exec(header)?.[1];
+}

package/dist/src/web-ui/system-host-setup/node-distribution.d.ts

@@ -0,0 +1,19 @@
+export declare const COMPANION_NODE_VERSION = "v24.21.0";
+export declare const COMPANION_NODE_DISTRIBUTIONS: {
+    readonly "win-x64": {
+        readonly archive: "node-v24.21.0-win-x64.zip";
+        readonly sha256: "158f7685b44de51f6c0df1d153526cbcd3e1bc739a8dfc607721cef75de9e541";
+    };
+    readonly "win-arm64": {
+        readonly archive: "node-v24.21.0-win-arm64.zip";
+        readonly sha256: "8779b1bde1d39f8d420e3b57aa657b39891af434d3de44a919044cec06785921";
+    };
+    readonly "darwin-x64": {
+        readonly archive: "node-v24.21.0-darwin-x64.tar.gz";
+        readonly sha256: "1462cb3b3046b815cf8ea436d3da450ec1a9f11dac7e5a46b0ada5305d7e8097";
+    };
+    readonly "darwin-arm64": {
+        readonly archive: "node-v24.21.0-darwin-arm64.tar.gz";
+        readonly sha256: "bed7eea5325e1108f32ce5228ddd6a5f0f08a499ee42aa7442aea583702f6057";
+    };
+};

package/dist/src/web-ui/system-host-setup/node-distribution.js

@@ -0,0 +1,9 @@
+// Verified 2026-09-18 against https://nodejs.org/dist/index.json and
+// https://nodejs.org/dist/v24.21.0/SHASUMS256.txt. Keep updates explicit.
+export const COMPANION_NODE_VERSION = "v24.21.0";
+export const COMPANION_NODE_DISTRIBUTIONS = {
+    "win-x64": { archive: "node-v24.21.0-win-x64.zip", sha256: "158f7685b44de51f6c0df1d153526cbcd3e1bc739a8dfc607721cef75de9e541" },
+    "win-arm64": { archive: "node-v24.21.0-win-arm64.zip", sha256: "8779b1bde1d39f8d420e3b57aa657b39891af434d3de44a919044cec06785921" },
+    "darwin-x64": { archive: "node-v24.21.0-darwin-x64.tar.gz", sha256: "1462cb3b3046b815cf8ea436d3da450ec1a9f11dac7e5a46b0ada5305d7e8097" },
+    "darwin-arm64": { archive: "node-v24.21.0-darwin-arm64.tar.gz", sha256: "bed7eea5325e1108f32ce5228ddd6a5f0f08a499ee42aa7442aea583702f6057" },
+};

package/dist/src/web-ui/system-host-setup/readiness.d.ts

@@ -0,0 +1,18 @@
+import { type SystemHostFacts } from "../../../plugins/system/source/host-observation.js";
+import { resolveSystemTarget } from "../../../plugins/system/source/targets.js";
+import type { HostStatus } from "../../../plugins/system/source/companion/protocol.js";
+export type HostSetupPlatform = "windows" | "macos";
+export type HostReadiness = Readonly<{
+    ready: boolean;
+    route: "native" | "wsl_interop" | "companion" | "setup_required";
+    environment: "native" | "wsl" | "container";
+    platforms: readonly HostSetupPlatform[];
+    restartRequired: boolean;
+    distribution?: string;
+    message?: string;
+}>;
+export declare function readHostReadiness(status: HostStatus, dependencies?: {
+    facts?: SystemHostFacts;
+    distribution?: string;
+    resolveTarget?: typeof resolveSystemTarget;
+}): Promise<HostReadiness>;

package/dist/src/web-ui/system-host-setup/readiness.js

@@ -0,0 +1,70 @@
+import { observeSystemHost, readSystemHostFacts, } from "../../../plugins/system/source/host-observation.js";
+import { resolveSystemTarget } from "../../../plugins/system/source/targets.js";
+function classifyHostEnvironment(facts) {
+    const observed = observeSystemHost(facts);
+    if (observed.environment === "container")
+        return "container";
+    if (observed.environment === "wsl_guest")
+        return "wsl";
+    return "native";
+}
+export async function readHostReadiness(status, dependencies = {}) {
+    const facts = dependencies.facts ?? readSystemHostFacts();
+    const observed = observeSystemHost(facts);
+    const environment = classifyHostEnvironment(facts);
+    if (status.paired)
+        return {
+            ready: status.connected,
+            route: "companion",
+            environment,
+            platforms: [],
+            restartRequired: false,
+            message: status.connected
+                ? "Connected computer is ready."
+                : "The paired computer is offline. Sign in on that computer to reconnect.",
+        };
+    if (environment === "container")
+        return {
+            ready: false,
+            route: "setup_required",
+            environment,
+            platforms: ["windows", "macos"],
+            restartRequired: false,
+            message: "Install the connection on the Windows or Mac computer running Docker.",
+        };
+    const target = environment === "wsl" ? "windows" : observed.runtimeOs;
+    const resolveTarget = dependencies.resolveTarget ?? resolveSystemTarget;
+    try {
+        if (target === "unsupported")
+            throw new Error("unsupported_native_platform");
+        await resolveTarget(target);
+        return {
+            ready: true,
+            route: environment === "wsl" ? "wsl_interop" : "native",
+            environment,
+            platforms: [],
+            restartRequired: false,
+            message: "Direct system access is ready. No additional installation is needed.",
+        };
+    }
+    catch {
+        if (environment === "wsl")
+            return {
+                ready: false,
+                route: "setup_required",
+                environment,
+                platforms: ["windows"],
+                restartRequired: true,
+                distribution: dependencies.distribution ?? process.env.WSL_DISTRO_NAME,
+                message: "Windows interop is unavailable. Open the Windows setup script. It enables access and automatically restarts the selected WSL distribution, interrupting its running services.",
+            };
+        return {
+            ready: false,
+            route: "setup_required",
+            environment,
+            platforms: [],
+            restartRequired: false,
+            message: "The native execution target is unavailable. Restore the operating system shell, then refresh status.",
+        };
+    }
+}

package/dist/src/web-ui/system-host-setup/routes.d.ts

@@ -0,0 +1,20 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { HostPairingStore } from "../../../plugins/system/source/companion/pairing-store.js";
+import type { HostReadiness } from "./readiness.js";
+export declare function isHostSetupRoute(pathname: string): boolean;
+export declare function sendHostSetupInputError(response: ServerResponse, error: unknown): boolean;
+export type HostSetupRouteDependencies = {
+    store: HostPairingStore;
+    readiness(): Promise<HostReadiness>;
+    prepareCompanion(): Promise<void>;
+    bundleFile?: string;
+};
+/** GUI writes use same-origin JSON; native code downloads use the expiring setup grant. */
+export declare class HostSetupRoutes {
+    private readonly dependencies;
+    constructor(dependencies: HostSetupRouteDependencies);
+    private bundle;
+    handle(request: IncomingMessage, response: ServerResponse, pathname: string): Promise<void>;
+    private downloadBundle;
+    private hasCurrentSetupGrant;
+}

package/dist/src/web-ui/system-host-setup/routes.js

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { acceptConfigMutationRequest } from "../local-runtime/config-mutation-request.js";
+import { readBody, sendJson } from "../local-runtime/http.js";
+import { hostBearerCredential } from "./native-authorization.js";
+import { renderCompanionInstaller, renderWslInteropInstaller } from "./installers.js";
+import { InstallerInputError } from "./installer-contract.js";
+import { readInstallerCompanionBundle } from "./companion-bundle.js";
+const setupPath = "/web-api/runtime/system-host/setup";
+const bundlePath = "/web-api/runtime/system-host/bundle";
+export function isHostSetupRoute(pathname) {
+    return [setupPath, bundlePath].includes(pathname);
+}
+export function sendHostSetupInputError(response, error) {
+    if (!(error instanceof InstallerInputError))
+        return false;
+    sendJson(response, 400, { ok: false, error: "host_setup_input_rejected", message: error.message });
+    return true;
+}
+function isSetupPlatformRequest(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    if (Array.isArray(value))
+        return false;
+    if (Object.keys(value).length !== 1)
+        return false;
+    const platform = value.platform;
+    return platform === "windows" || platform === "macos";
+}
+function requestRuntimeOrigin(request) {
+    const encrypted = "encrypted" in request.socket && request.socket.encrypted;
+    return new URL(`${encrypted ? "https" : "http"}://${request.headers.host}`).origin;
+}
+/** GUI writes use same-origin JSON; native code downloads use the expiring setup grant. */
+export class HostSetupRoutes {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async bundle() {
+        if (this.dependencies.bundleFile)
+            return readFile(this.dependencies.bundleFile);
+        return readInstallerCompanionBundle();
+    }
+    async handle(request, response, pathname) {
+        if (pathname === bundlePath) {
+            await this.downloadBundle(request, response);
+            return;
+        }
+        if (request.method !== "POST") {
+            sendJson(response, 405, { ok: false, error: "method_not_allowed" });
+            return;
+        }
+        if (!acceptConfigMutationRequest(request, response))
+            return;
+        const raw = await readBody(request, { maxBytes: 1024 });
+        let input;
+        try {
+            input = JSON.parse(raw.toString());
+        }
+        catch { /* rejected below */ }
+        if (!isSetupPlatformRequest(input)) {
+            sendJson(response, 400, { ok: false, error: "invalid_host_setup_platform" });
+            return;
+        }
+        const readiness = await this.dependencies.readiness();
+        if (!readiness.platforms.includes(input.platform)) {
+            sendJson(response, 409, {
+                ok: false,
+                error: "host_setup_not_required",
+                message: readiness.message ?? "Refresh the computer connection status.",
+            });
+            return;
+        }
+        if (readiness.environment === "wsl") {
+            const installer = await renderWslInteropInstaller({ distribution: readiness.distribution });
+            sendJson(response, 200, { ok: true, ...installer, restartRequired: true });
+            return;
+        }
+        // Read and hash the exact running build before creating a setup grant.
+        const bundle = await this.bundle();
+        await this.dependencies.prepareCompanion();
+        const pairing = this.dependencies.store.begin(15 * 60_000);
+        const installer = await renderCompanionInstaller({
+            platform: input.platform,
+            url: requestRuntimeOrigin(request),
+            code: pairing.code,
+            expiresAt: pairing.expiresAt,
+            bundleSha256: createHash("sha256").update(bundle).digest("hex"),
+        });
+        sendJson(response, 200, {
+            ok: true,
+            ...installer,
+            expiresAt: pairing.expiresAt,
+            restartRequired: false,
+        });
+    }
+    async downloadBundle(request, response) {
+        if (request.method !== "GET") {
+            sendJson(response, 405, { ok: false, error: "method_not_allowed" });
+            return;
+        }
+        const credential = hostBearerCredential(request);
+        if (!this.hasCurrentSetupGrant(credential)) {
+            sendJson(response, 401, { ok: false, error: "host_setup_expired" });
+            return;
+        }
+        const bundle = await this.bundle();
+        response.writeHead(200, {
+            "content-type": "application/javascript; charset=utf-8",
+            "content-length": bundle.byteLength,
+            "x-content-type-options": "nosniff",
+        });
+        response.end(bundle);
+    }
+    hasCurrentSetupGrant(credential) {
+        if (!credential)
+            return false;
+        return this.dependencies.store.authenticate(credential) === "pairing";
+    }
+}

package/dist/src/web-ui/system-host-setup/windows-script-wrapper.d.ts

@@ -0,0 +1,2 @@
+/** The body is read from disk so ephemeral credentials never enter process argv. */
+export declare function wrapWindowsSetupScript(script: string): string;

package/dist/src/web-ui/system-host-setup/windows-script-wrapper.js

@@ -0,0 +1,17 @@
+/** The body is read from disk so ephemeral credentials never enter process argv. */
+export function wrapWindowsSetupScript(script) {
+    const marker = "#==ABOT-POWERSHELL==";
+    return [
+        "@echo off",
+        "setlocal DisableDelayedExpansion",
+        'set "ABOT_SETUP_FILE=%~f0"',
+        `"%SystemRoot%\\System32\\WindowsPowerShell\\v1.0\\powershell.exe" -NoLogo -NoProfile -Command "$text = [IO.File]::ReadAllText($env:ABOT_SETUP_FILE); & ([ScriptBlock]::Create($text.Substring($text.LastIndexOf('${marker}') + ${marker.length})))"`,
+        'set "ABOT_SETUP_RESULT=%ERRORLEVEL%"',
+        "echo.",
+        "pause",
+        "exit /b %ABOT_SETUP_RESULT%",
+        marker,
+        script,
+        "",
+    ].join("\r\n");
+}

package/dist/src/web-ui/system-host-setup/wsl-interop-config.d.ts

@@ -0,0 +1,3 @@
+/** Update only active enabled entries inside interop sections, preserving other lines. */
+export declare const WSL_INTEROP_AWK_PROGRAM: string;
+export declare function renderWslInteropShell(): string;

package/dist/src/web-ui/system-host-setup/wsl-interop-config.js

@@ -0,0 +1,67 @@
+/** Update only active enabled entries inside interop sections, preserving other lines. */
+export const WSL_INTEROP_AWK_PROGRAM = String.raw `
+function finishSection() {
+  if (inInterop && !hasEnabled) print "enabled=true"
+}
+{
+  normalized=$0
+  sub(/\r$/, "", normalized)
+  lowered=tolower(normalized)
+  if (lowered ~ /^[ \t]*\[/) {
+    finishSection()
+    inInterop=(lowered ~ /^[ \t]*\[interop\][ \t]*([#;].*)?$/)
+    if (inInterop) { seenInterop=1; hasEnabled=0 }
+    print $0
+    next
+  }
+  if (inInterop && lowered ~ /^[ \t]*enabled[ \t]*=/) {
+    hasEnabled=1
+    value=lowered
+    sub(/^[^=]*=[ \t]*/, "", value)
+    sub(/[ \t]*[#;].*$/, "", value)
+    sub(/[ \t]*$/, "", value)
+    if (value == "true") { print $0; next }
+    prefix=normalized
+    sub(/=.*/, "=", prefix)
+    suffix=normalized
+    if (match(suffix, /[#;]/)) suffix=" " substr(suffix, RSTART)
+    else suffix=""
+    print prefix "true" suffix
+    next
+  }
+  print $0
+}
+END {
+  finishSection()
+  if (!seenInterop) { print "[interop]"; print "enabled=true" }
+}
+`;
+export function renderWslInteropShell() {
+    return `set -eu
+config=/etc/wsl.conf
+source=/dev/null
+if [ -L "$config" ]; then echo 'Refusing to replace a linked /etc/wsl.conf.' >&2; exit 1; fi
+if [ -e "$config" ] && [ ! -f "$config" ]; then echo '/etc/wsl.conf is not a regular file.' >&2; exit 1; fi
+if [ -f "$config" ]; then
+  source="$config"
+  backup="$config.abot-before-$(date -u +%Y%m%dT%H%M%SZ)-$$"
+  cp -p "$config" "$backup"
+  printf 'Original configuration saved to %s\\n' "$backup"
+fi
+temporary=$(mktemp /etc/.abot-wsl-conf.XXXXXX)
+trap 'rm -f "$temporary"' EXIT HUP INT TERM
+awk '${WSL_INTEROP_AWK_PROGRAM}' "$source" > "$temporary"
+if [ -f "$config" ]; then
+  chmod --reference="$config" "$temporary"
+  chown --reference="$config" "$temporary"
+else
+  chmod 644 "$temporary"
+fi
+if [ -f "$config" ] && cmp -s "$config" "$temporary"; then
+  echo 'Interop configuration is already enabled.'
+else
+  mv -f "$temporary" "$config"
+  echo 'Interop configuration enabled; the selected distribution must restart.'
+fi
+`;
+}

package/dist/src/web-ui/system-host-setup/wsl-interop-windows.d.ts

@@ -0,0 +1 @@
+export declare function renderWindowsWslInteropScript(distribution?: string): string;

package/dist/src/web-ui/system-host-setup/wsl-interop-windows.js

@@ -0,0 +1,49 @@
+import { installerMetadataBase64 } from "./installer-contract.js";
+import { renderWslInteropShell } from "./wsl-interop-config.js";
+import { wrapWindowsSetupScript } from "./windows-script-wrapper.js";
+export function renderWindowsWslInteropScript(distribution) {
+    const metadata = installerMetadataBase64({ distribution });
+    const shell = Buffer.from(renderWslInteropShell(), "utf8").toString("base64");
+    return wrapWindowsSetupScript(String.raw `
+$ErrorActionPreference = 'Stop'
+$OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+$Metadata = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${metadata}')) | ConvertFrom-Json
+$Wsl = Join-Path $env:SystemRoot 'System32\wsl.exe'
+try {
+  $Installed = @(& $Wsl --list --quiet)
+  if ($LASTEXITCODE -ne 0) { throw 'Windows could not list the installed WSL distributions.' }
+  $Distributions = @($Installed | ForEach-Object { $_.Replace([string][char]0, '').Trim() } | Where-Object { $_ -and -not $_.StartsWith('docker-desktop', [StringComparison]::OrdinalIgnoreCase) })
+  $Selected = $Metadata.distribution
+  if ($Selected) {
+    if (-not ($Distributions -ccontains $Selected)) { throw 'The requested WSL distribution is not installed with that exact name.' }
+  } elseif ($Distributions.Count -eq 1) {
+    $Selected = $Distributions[0]
+  } elseif ($Distributions.Count -gt 1) {
+    Write-Host 'Choose the WSL distribution used by ABot:'
+    for ($Index = 0; $Index -lt $Distributions.Count; $Index++) { Write-Host (($Index + 1).ToString() + '. ' + $Distributions[$Index]) }
+    $Choice = Read-Host 'Distribution number (Enter cancels)'
+    if (-not $Choice) { Write-Host 'Cancelled. No settings were changed.'; exit 0 }
+    $Number = 0
+    if (-not [int]::TryParse($Choice, [ref]$Number) -or $Number -lt 1 -or $Number -gt $Distributions.Count) { throw 'The distribution selection is invalid.' }
+    $Selected = $Distributions[$Number - 1]
+  } else { throw 'No supported WSL distribution is installed.' }
+  Write-Host ('This will enable Windows executable interoperability in ' + $Selected + '.')
+  Write-Host 'It preserves other WSL settings and saves the previous configuration.'
+  Write-Host ('Restarting ' + $Selected + ' will interrupt ALL apps and services in that distribution, including ABot. Other distributions will remain running.') -ForegroundColor Yellow
+  $ShellBase64 = '${shell}'
+  $ShellBase64 | & $Wsl --distribution $Selected --user root --exec /bin/sh -c "tr -d '\r\n' | base64 -d | /bin/sh"
+  if ($LASTEXITCODE -ne 0) { throw 'WSL configuration could not be updated. The distribution was not restarted.' }
+  & $Wsl --terminate $Selected
+  if ($LASTEXITCODE -ne 0) { throw 'The selected distribution did not stop. Its configuration is saved, but restart still needs to complete.' }
+  $PowerShell = Join-Path $env:SystemRoot 'System32\WindowsPowerShell\v1.0\powershell.exe'
+  $LinuxPowerShell = @(& $Wsl --distribution $Selected --exec wslpath -u $PowerShell)
+  if ($LASTEXITCODE -ne 0 -or $LinuxPowerShell.Count -ne 1) { throw 'The distribution restarted, but its Windows executable path could not be resolved.' }
+  $Probe = @(& $Wsl --distribution $Selected --exec ($LinuxPowerShell[0].Trim()) -NoLogo -NoProfile -NonInteractive -Command '[Environment]::OSVersion.Platform.ToString()')
+  if ($LASTEXITCODE -ne 0 -or ($Probe -join '').Trim() -ne 'Win32NT') { throw 'The distribution restarted, but actual Windows PowerShell execution is still unavailable.' }
+  Write-Host ('Verified: Windows PowerShell can run through ' + $Selected + '. Return to ABot and check again.')
+} catch {
+  Write-Host ('WSL setup failed: ' + $_.Exception.Message) -ForegroundColor Red
+  exit 1
+}
+`);
+}

package/dist/src/web-ui/system-host-upgrade-authority.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+/** Native upgrades retain credential authentication and never accept browser metadata. */
+export declare function hasTrustedSystemHostUpgrade(request: IncomingMessage, listenHost: string): boolean;
+export declare function rejectSystemHostUpgrade(socket: Duplex): void;

package/dist/src/web-ui/system-host-upgrade-authority.js

@@ -0,0 +1,13 @@
+import { hasLoopbackRequestAuthority, hasTrustedWebUiAuthority, } from "./request-authority.js";
+import { hostBearerCredential } from "./system-host-setup/native-authorization.js";
+/** Native upgrades retain credential authentication and never accept browser metadata. */
+export function hasTrustedSystemHostUpgrade(request, listenHost) {
+    if (!hostBearerCredential(request))
+        return false;
+    if (hasTrustedWebUiAuthority(request, listenHost))
+        return true;
+    return hasLoopbackRequestAuthority(request);
+}
+export function rejectSystemHostUpgrade(socket) {
+    socket.end("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+}

package/docs/architecture.md

@@ -74,7 +74,12 @@ specific capability identity.
 Planner child-call commits are projected through the existing
 `planner.plan.*` event family. For client compatibility those payloads retain
 `stage=development_plan`, even though the runtime no longer has a Development
-loop. Tool execution keeps the existing `tool.*` event lifecycle.
+loop. Execution Agent may explicitly adopt a returned Planner proposal and
+report item statuses alongside an existing decision; its canonical root
+record projects through that same event family. The model chooses progress,
+and neither the advisory return nor a tool result automatically marks work
+complete. Events remain presentation rather than execution evidence or a
+second state store. Tool execution keeps the existing `tool.*` lifecycle.
 
 ## Configuration