@abot-ai/runtime 1.7.0 → 1.8.1

package/dist/src/web-ui/local-runtime/runtime-setup-edit-recovery.js

@@ -0,0 +1,87 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { realpath, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { withFileLock } from "../../runtime/adapters/long-term-memory/file-lock.js";
+import { CONFIG_FILE_LOCK_OPTIONS } from "../../runtime/adapters/config-file-transaction.js";
+import { isMissingSetupEditFile, readSetupEditFile, requireSetupEditFileSnapshot, restoreSetupEditFile, setupEditFileMatches, setupEditRecoveryRequired, setupEditTextSnapshot, syncSetupEditDirectory, } from "./runtime-setup-edit-files.js";
+import { readSetupEditJournal, setupEditJournalPath, } from "./runtime-setup-edit-journal.js";
+/** Synchronous consumers must not observe any part of an unresolved edit. */
+export function requireRuntimeSetupEditSettled(rootDir) {
+    let path = resolve(rootDir);
+    try {
+        path = realpathSync(path);
+        lstatSync(setupEditJournalPath(path));
+    }
+    catch (error) {
+        if (isMissingSetupEditFile(error))
+            return;
+        throw setupEditRecoveryRequired();
+    }
+    throw setupEditRecoveryRequired();
+}
+async function requireRecoverableSetupEditFiles(journal) {
+    for (const file of journal.files) {
+        const current = await readSetupEditFile(file.path);
+        if (setupEditFileMatches(current, file.after))
+            continue;
+        if (journal.phase === "pending" &&
+            setupEditFileMatches(current, file.before))
+            continue;
+        throw setupEditRecoveryRequired();
+    }
+}
+/** Caller holds every participant lock; repeatable after interruption at any restore. */
+export async function reconcileSetupEditJournal(journal) {
+    await requireRecoverableSetupEditFiles(journal);
+    if (journal.phase === "pending") {
+        for (const file of [...journal.files].reverse()) {
+            const current = await readSetupEditFile(file.path);
+            if (setupEditFileMatches(current, file.before))
+                continue;
+            if (!setupEditFileMatches(current, file.after))
+                throw setupEditRecoveryRequired();
+            await restoreSetupEditFile(file.path, file.after, file.before);
+        }
+    }
+    const path = setupEditJournalPath(journal.rootDir);
+    await requireSetupEditFileSnapshot(path, setupEditTextSnapshot(JSON.stringify(journal) + "\n", 0o600));
+    await rm(path);
+    await syncSetupEditDirectory(journal.rootDir);
+}
+async function withSetupEditRecoveryLocks(journal, operation) {
+    const [model, config, receipt] = journal.files;
+    const locks = [
+        config.path + ".config.lock",
+        model.path + ".config.lock",
+        join(journal.rootDir, ".env.credentials.lock"),
+        receipt.path + ".config.lock",
+    ];
+    const acquire = (index) => {
+        if (index === locks.length)
+            return operation();
+        return withFileLock(locks[index], () => acquire(index + 1), CONFIG_FILE_LOCK_OPTIONS);
+    };
+    return acquire(0);
+}
+/** Runs before dotenv/configuration loading. No journal means no speculative repair. */
+export async function recoverRuntimeSetupEdit(rootDir) {
+    try {
+        requireRuntimeSetupEditSettled(rootDir);
+        return;
+    }
+    catch {
+        // Parsing and lock acquisition below decide whether recovery is safe.
+    }
+    const root = await realpath(rootDir);
+    await withFileLock(join(root, ".runtime-setup.lock"), async () => {
+        const journal = await readSetupEditJournal(root);
+        if (!journal)
+            return;
+        await withSetupEditRecoveryLocks(journal, async () => {
+            const current = await readSetupEditJournal(root);
+            if (!current || JSON.stringify(current) !== JSON.stringify(journal))
+                throw setupEditRecoveryRequired();
+            await reconcileSetupEditJournal(journal);
+        });
+    }, CONFIG_FILE_LOCK_OPTIONS);
+}

package/dist/src/web-ui/local-runtime/runtime-setup-edit-transaction.d.ts

@@ -0,0 +1,3 @@
+import { type SetupEditFilePlan } from "./runtime-setup-edit-journal.js";
+/** Setup, config, model and credential locks enclose this complete transaction. */
+export declare function commitRuntimeSetupEdit(rootDir: string, files: readonly SetupEditFilePlan[], commit: () => Promise<void>, publishCommittedCredentials: () => void): Promise<void>;

package/dist/src/web-ui/local-runtime/runtime-setup-edit-transaction.js

@@ -0,0 +1,37 @@
+import { realpath } from "node:fs/promises";
+import { createSetupEditJournal, readSetupEditJournal, writeSetupEditJournal, } from "./runtime-setup-edit-journal.js";
+import { requireSetupEditFileSnapshot, syncSetupEditFile, } from "./runtime-setup-edit-files.js";
+import { reconcileSetupEditJournal, requireRuntimeSetupEditSettled, } from "./runtime-setup-edit-recovery.js";
+/** Setup, config, model and credential locks enclose this complete transaction. */
+export async function commitRuntimeSetupEdit(rootDir, files, commit, publishCommittedCredentials) {
+    const root = await realpath(rootDir);
+    requireRuntimeSetupEditSettled(root);
+    const journal = await createSetupEditJournal(root, files);
+    await writeSetupEditJournal(journal);
+    try {
+        await commit();
+        for (const file of journal.files) {
+            await requireSetupEditFileSnapshot(file.path, file.after);
+            await syncSetupEditFile(file.path);
+        }
+        await writeSetupEditJournal({ ...journal, phase: "committed" }, journal);
+    }
+    catch (error) {
+        try {
+            const persisted = await readSetupEditJournal(root);
+            if (persisted?.phase === "committed")
+                publishCommittedCredentials();
+            if (persisted)
+                await reconcileSetupEditJournal(persisted);
+            if (persisted?.phase === "committed")
+                return;
+        }
+        catch (recoveryError) {
+            throw new AggregateError([error, recoveryError], "Connection edit failed and needs recovery before it can be applied.");
+        }
+        throw error;
+    }
+    publishCommittedCredentials();
+    // A cleanup failure leaves a committed marker. Never roll it back.
+    await reconcileSetupEditJournal({ ...journal, phase: "committed" });
+}

package/dist/src/web-ui/local-runtime/runtime-setup-service.js

@@ -1,3 +1,4 @@
+import { requireRuntimeSetupEditSettled } from "./runtime-setup-edit-recovery.js";
 import { readDefaultContextWindowTokens } from "../../../scripts/runtime-setup-files.js";
 import { initializeConfiguredRuntimeDirectories } from "../../../scripts/runtime-setup-directories.js";
 import { configuredSetupModel, requiresConfiguredCredential, } from "./runtime-setup-provider.js";
@@ -20,6 +21,7 @@ export class RuntimeSetupService {
         this.options = options;
     }
     source() {
+        requireRuntimeSetupEditSettled(this.options.rootDir);
         return inspectRuntimeConfigFileWithMeta(this.options.rootDir, this.savedConfigPath ?? this.options.getConfigPath());
     }
     async status() {
@@ -156,7 +158,9 @@ export class RuntimeSetupService {
                     draft,
                     input,
                     credentialChanged,
+                    credentialWrite,
                 });
+                credentialsPersisted = true;
                 draft = edited.draft;
                 embeddingInvalidated = edited.embeddingInvalidated;
             }

package/dist/src/web-ui/local-runtime-backend.js

@@ -3,6 +3,9 @@ import { LocalRuntimeApiRouter } from "./local-runtime/api-router.js";
 import { LocalRuntimeControlRoutes } from "./local-runtime/control-routes.js";
 import { RuntimeEnvironmentRegistry } from "./local-runtime/environment-registry.js";
 import { sendJson } from "./local-runtime/http.js";
+import { RequestBodyInputError } from "./local-runtime/request-body-error.js";
+import { RuntimeSetupError } from "./local-runtime/runtime-setup-input.js";
+import { requireRuntimeSetupEditSettled } from "./local-runtime/runtime-setup-edit-recovery.js";
 import { LocalRealtimeController } from "./local-runtime/realtime-controller.js";
 import { RealtimeClientHub } from "./local-runtime/realtime-hub.js";
 import { LocalRequestExecution } from "./local-runtime/request-execution.js";
@@ -21,6 +24,7 @@ export class LocalRuntimeWebBackend {
     notifications;
     notificationRoutes;
     constructor(options) {
+        requireRuntimeSetupEditSettled(options.rootDir ?? process.cwd());
         const resolvedOptions = {
             ...options,
             providerAdapters: resolveProviderAdapters({
@@ -87,6 +91,16 @@ export class LocalRuntimeWebBackend {
             return false;
         }
         catch (error) {
+            const requiresSetupRecovery = error instanceof RuntimeSetupError &&
+                error.code === "setup_edit_recovery_required";
+            if (error instanceof RequestBodyInputError || requiresSetupRecovery) {
+                sendJson(res, error.statusCode, {
+                    ok: false,
+                    error: error.code,
+                    message: error.message,
+                });
+                return true;
+            }
             sendJson(res, 500, {
                 ok: false,
                 error: "local_runtime_backend_error",

package/dist/src/web-ui/plugin-management-catalog.d.ts

@@ -1,3 +1,4 @@
+import { resolvePluginPlatformCompatibility } from "../runtime/plugins/platform-compatibility.js";
 import type { RuntimePluginConfig } from "../runtime/ports.js";
 import type { DiscoveredAgentPluginManifest } from "../runtime/plugins/discovered-manifest.js";
 import { type PluginSelection } from "../runtime/plugins/selection.js";
@@ -15,6 +16,7 @@ export type RuntimePluginSnapshot = {
         description?: string;
         version?: string;
         pluginEnabled: boolean;
+        compatibility: ReturnType<typeof resolvePluginPlatformCompatibility>;
         removable: boolean;
         configurable: boolean;
         capabilities: RuntimePluginCapabilitySnapshot[];
@@ -25,4 +27,4 @@ export type RuntimePluginSnapshot = {
     }>;
     application: "restart_required";
 };
-export declare function projectPluginSnapshot(manifests: readonly DiscoveredAgentPluginManifest[], config: RuntimePluginConfig, consumerRoot?: string): RuntimePluginSnapshot;
+export declare function projectPluginSnapshot(manifests: readonly DiscoveredAgentPluginManifest[], config: RuntimePluginConfig, consumerRoot?: string, runtimePlatform?: NodeJS.Platform): RuntimePluginSnapshot;

package/dist/src/web-ui/plugin-management-catalog.js

@@ -1,3 +1,4 @@
+import { resolvePluginPlatformCompatibility } from "../runtime/plugins/platform-compatibility.js";
 import { readPluginConfigurationStore } from "../runtime/plugins/configuration-store.js";
 import { hasConfigurablePluginValues } from "./plugin-configuration-view.js";
 import { installedPluginPackage } from "../runtime/plugins/installation/installed-package.js";
@@ -33,7 +34,7 @@ function projectPluginCapabilities(plugin, selection) {
         };
     });
 }
-export function projectPluginSnapshot(manifests, config, consumerRoot) {
+export function projectPluginSnapshot(manifests, config, consumerRoot, runtimePlatform = process.platform) {
     const selection = normalizePluginSelection(config);
     const local = consumerRoot
         ? readPluginConfigurationStore(consumerRoot).plugins
@@ -47,6 +48,7 @@ export function projectPluginSnapshot(manifests, config, consumerRoot) {
             const selectedCapabilityCount = capabilities.filter((capability) => capability.enabled).length;
             return {
                 id: manifest.name,
+                compatibility: resolvePluginPlatformCompatibility(manifest, runtimePlatform),
                 configurable: hasConfigurablePluginValues(manifest.extensions[ABOT_RUNTIME_EXTENSION], Object.hasOwn(local, manifest.name)
                     ? local[manifest.name]
                     : undefined),

package/dist/src/web-ui/plugin-management-service.d.ts

@@ -21,6 +21,7 @@ export declare function setRuntimePluginEnabled(options: PluginManagementOptions
         description?: string;
         version?: string;
         pluginEnabled: boolean;
+        compatibility: ReturnType<typeof import("../runtime/plugins/platform-compatibility.js").resolvePluginPlatformCompatibility>;
         removable: boolean;
         configurable: boolean;
         capabilities: import("./plugin-management-catalog.js").RuntimePluginCapabilitySnapshot[];

package/dist/src/web-ui/plugin-removal-service.d.ts

@@ -18,6 +18,7 @@ export declare function removeRuntimePlugin(options: PluginManagementOptions & P
         description?: string;
         version?: string;
         pluginEnabled: boolean;
+        compatibility: ReturnType<typeof import("../runtime/plugins/platform-compatibility.js").resolvePluginPlatformCompatibility>;
         removable: boolean;
         configurable: boolean;
         capabilities: import("./plugin-management-catalog.js").RuntimePluginCapabilitySnapshot[];

package/dist/src/web-ui/server-readiness.d.ts

@@ -0,0 +1,3 @@
+import type { Server } from "node:http";
+/** Resolve the actual bound address, including when the caller requested port 0. */
+export declare function waitForWebUiListening(server: Server, signal: AbortSignal): Promise<string>;

package/dist/src/web-ui/server-readiness.js

@@ -0,0 +1,36 @@
+/** Resolve the actual bound address, including when the caller requested port 0. */
+export function waitForWebUiListening(server, signal) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            server.off("listening", listening);
+            server.off("error", failed);
+            signal.removeEventListener("abort", aborted);
+        };
+        const failed = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const aborted = () => failed(new Error("web_ui_closed_before_listening"));
+        const listening = () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                failed(new Error("web_ui_tcp_address_unavailable"));
+                return;
+            }
+            cleanup();
+            const host = address.family === "IPv6" ? `[${address.address}]` : address.address;
+            resolve(`http://${host}:${address.port}/`);
+        };
+        if (signal.aborted) {
+            aborted();
+            return;
+        }
+        if (server.listening) {
+            listening();
+            return;
+        }
+        server.once("listening", listening);
+        server.once("error", failed);
+        signal.addEventListener("abort", aborted, { once: true });
+    });
+}

package/dist/src/web-ui/server.d.ts

@@ -26,6 +26,8 @@ type WebUiServerOptions = {
     checkRuntimeSetupActivation?: (configPath: string) => Promise<RuntimeSetupActivation>;
 };
 type WebUiServerHandle = {
+    ready: () => Promise<string>;
     close: () => Promise<void>;
 };
 export declare function startWebUiServer(overrides?: WebUiServerOptions): WebUiServerHandle;
+export declare function startWebUiServerWithRecovery(overrides?: WebUiServerOptions): Promise<WebUiServerHandle>;

package/dist/src/web-ui/server.js

@@ -9,8 +9,11 @@ import { resolveWebUiEnvironmentConfig, } from "./environment-config.js";
 export { resolveWebUiEnvironmentConfig, } from "./environment-config.js";
 import { closeRuntimeSetupServices } from "./runtime-setup-shutdown.js";
 import { loadDotEnvFile } from "../shared/load-dotenv.js";
+import { waitForWebUiListening } from "./server-readiness.js";
+import { recoverRuntimeSetupEdit, requireRuntimeSetupEditSettled, } from "./local-runtime/runtime-setup-edit-recovery.js";
 import { createWebUiShutdown } from "./server-shutdown.js";
 import { ExternalBridgeWebBackend } from "./external-bridge-backend.js";
+import { WebClientStateRoutes } from "./client-state/routes.js";
 import { LocalRuntimeWebBackend } from "./local-runtime-backend.js";
 import { resolveWebUiAddress } from "./web-ui-address.js";
 import { createLinkPreviewRouteHandler } from "./link-preview/routes.js";
@@ -126,6 +129,12 @@ async function serveStatic(req, res, appDir) {
     sendJson(res, 404, { ok: false, error: "not_found" });
 }
 export function startWebUiServer(overrides = {}) {
+    const startupRoots = new Set([
+        process.cwd(),
+        overrides.rootDir ?? process.cwd(),
+    ]);
+    for (const rootDir of startupRoots)
+        requireRuntimeSetupEditSettled(rootDir);
     const envOptions = getOptionsFromEnv();
     const rootDir = overrides.rootDir ?? envOptions.rootDir;
     const configPath = overrides.configPath ?? envOptions.configPath;
@@ -206,6 +215,12 @@ export function startWebUiServer(overrides = {}) {
         });
     }
     const handleLinkPreview = createLinkPreviewRouteHandler();
+    const clientState = new WebClientStateRoutes(rootDir, () => {
+        for (const client of wss.clients) {
+            if (client.readyState === 1)
+                client.send(JSON.stringify({ type: "workspace_changed", resources: ["client-state"] }));
+        }
+    });
     const systemHost = localRuntimeBackend
         ? new WebSystemHostService(rootDir, () => localRuntimeBackend.notifyHostConnectionChanged(), (environmentId) => localRuntimeBackend.nativePermissions(environmentId))
         : null;
@@ -217,6 +232,8 @@ export function startWebUiServer(overrides = {}) {
             if (await handleLinkPreview(req, res))
                 return;
             const pathname = new URL(req.url || "/", "http://localhost").pathname;
+            if (await clientState.handle(req, res, pathname))
+                return;
             if (await systemHost?.handleHttp(req, res, pathname))
                 return;
             if (pathname === "/web-config") {
@@ -317,10 +334,15 @@ export function startWebUiServer(overrides = {}) {
     });
     const schedulerStartup = localRuntimeBackend?.start(options.environments.map(({ id }) => id));
     return {
+        ready: () => waitForWebUiListening(server, listenAbort.signal),
         close: createWebUiShutdown(server, wss, schedulerStartup, () => closeRuntimeSetupServices(async () => localRuntimeBackend?.stop(), () => setupGateway.close(), async () => systemHost?.close()), listenAbort),
     };
 }
+export async function startWebUiServerWithRecovery(overrides = {}) {
+    await recoverRuntimeSetupEdit(overrides.rootDir ?? process.cwd());
+    return startWebUiServer(overrides);
+}
 const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
 if (import.meta.url === invokedPath) {
-    startWebUiServer();
+    await startWebUiServerWithRecovery();
 }

package/dist/src/web-ui/system-host-service.js

@@ -4,6 +4,9 @@ import { HostConnection } from "../computer-access/companion/connection.js";
 import { HostPairingStore } from "../computer-access/companion/pairing-store.js";
 import { startHostBroker } from "../computer-access/companion/broker-server.js";
 import { hostStateDirectory } from "../computer-access/companion/private-store.js";
+import { readCollectionConsent } from "../computer-access/collection-consent.js";
+import { readRuntimeCollectionSource } from "../computer-access/observation-source.js";
+import { COLLECTION_CONSENT_PATH, handleCollectionConsent } from "./system-host-setup/collection-consent-route.js";
 import { HOST_SOCKET_PATH, HOST_WIRE_MAX_BYTES, } from "../computer-access/companion/protocol.js";
 import { isProcessOwnerAlive, requireCurrentProcessOwnerIdentity, } from "../computer-access/companion/process-owner-identity.js";
 import { ensurePrivateRuntimeDirectory } from "../runtime/local-host/private-directory.js";
@@ -21,6 +24,8 @@ import { NativeRuntimePermissionRoute } from "./system-host-setup/native-permiss
 function isSystemHostRoute(pathname) {
     if (pathname === "/web-api/runtime/system-host")
         return true;
+    if (pathname === COLLECTION_CONSENT_PATH)
+        return true;
     return pathname === "/web-api/runtime/system-host/pairing";
 }
 export class WebSystemHostService {
@@ -102,6 +107,10 @@ export class WebSystemHostService {
             return false;
         response.setHeader("cache-control", "no-store");
         try {
+            if (pathname === COLLECTION_CONSENT_PATH) {
+                await handleCollectionConsent(request, response, this.rootDir);
+                return true;
+            }
             if (pathname === HOST_PERMISSION_PATH) {
                 await this.permissions.handle(request, response);
                 return true;
@@ -115,7 +124,8 @@ export class WebSystemHostService {
                 const status = this.connection.status();
                 const readiness = withLocalMacSetup(request, await readHostReadiness(status));
                 const nativePermissions = await this.nativePermissions.status(request);
-                sendJson(response, 200, { ok: true, ...status, readiness, nativePermissions });
+                sendJson(response, 200, { ok: true, ...status, readiness, nativePermissions,
+                    collectionSource: readRuntimeCollectionSource(), collectionConsent: readCollectionConsent(this.rootDir) });
                 return true;
             }
             if (!acceptConfigMutationRequest(request, response))
@@ -145,7 +155,8 @@ export class WebSystemHostService {
                 this.connection.disconnect();
                 const status = this.connection.status();
                 sendJson(response, 200, { ok: true, ...status,
-                    readiness: withLocalMacSetup(request, await readHostReadiness(status)) });
+                    readiness: withLocalMacSetup(request, await readHostReadiness(status)),
+                    collectionSource: readRuntimeCollectionSource(), collectionConsent: readCollectionConsent(this.rootDir) });
                 return true;
             }
             sendJson(response, 405, { ok: false, error: "method_not_allowed" });

package/dist/src/web-ui/system-host-setup/collection-consent-route.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare const COLLECTION_CONSENT_PATH = "/web-api/runtime/system-host/collection-consent";
+export declare function handleCollectionConsent(request: IncomingMessage, response: ServerResponse, rootDir: string): Promise<void>;

package/dist/src/web-ui/system-host-setup/collection-consent-route.js

@@ -0,0 +1,30 @@
+import { acceptCollectionConsent } from "../../computer-access/collection-consent.js";
+import { acceptConfigMutationRequest } from "../local-runtime/config-mutation-request.js";
+import { readBody, sendJson } from "../local-runtime/http.js";
+export const COLLECTION_CONSENT_PATH = "/web-api/runtime/system-host/collection-consent";
+function hasExplicitCollectionAcknowledgment(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    if (Object.keys(value).length !== 1)
+        return false;
+    return value.acknowledged === true;
+}
+export async function handleCollectionConsent(request, response, rootDir) {
+    if (request.method !== "POST") {
+        sendJson(response, 405, { ok: false, error: "method_not_allowed" });
+        return;
+    }
+    if (!acceptConfigMutationRequest(request, response))
+        return;
+    let body;
+    try {
+        body = JSON.parse((await readBody(request, { maxBytes: 1_024 })).toString());
+    }
+    catch { /* malformed or oversized input is rejected below */ }
+    if (!hasExplicitCollectionAcknowledgment(body)) {
+        sendJson(response, 400, { ok: false, error: "invalid_collection_acknowledgment" });
+        return;
+    }
+    const collectionConsent = await acceptCollectionConsent(rootDir);
+    sendJson(response, 200, { ok: true, collectionConsent });
+}

package/docs/installation.md

@@ -140,12 +140,35 @@ See [Passive Long-Term Memory](long-term-memory.md) before enabling persistence.
 
 ### Computer Access During Setup
 
-The optional **Computer** step and **Home → Computer access** manage one
-Computer access connection shared by SYSTEM tools, ABot Spark and compatible
-plugins. Direct native/WSL command access can already work; the shared companion
-adds desktop access and background collection without a second ABot Spark setup.
+The **Computer** step and computer card on **Home** use the platform where the
+Runtime is running. Direct native/WSL command access can already work; compatible
+plugins still require their own permissions.
 
-#### Windows: Microsoft Store connection
+#### Native Windows
+
+When the Runtime runs directly on Windows, computer setup does not require
+Companion or a pairing link. Compatible tools run locally with their existing
+approval controls. Spark uses the same Windows collection implementation locally.
+Opening a WSL or Docker Runtime in a Windows browser still uses the Companion
+connection described below.
+
+#### Spark collection acknowledgment
+
+On every platform, Spark asks for an explicit, initially unchecked acknowledgment
+before granting collection permission or starting collection. It explains the
+application content collected and how the configured learning model may receive
+it, with links to the [Software Terms](https://abot-ai.com/terms/#software) and
+[Privacy Policy](https://abot-ai.com/privacy/#software).
+
+The acknowledgment is saved once per ABot installation, shared across environments,
+and retained across updates and computer re-pairing. Existing installations also
+need to acknowledge it once. This record does not enable collection or learning:
+activity permissions and Start/Stop remain separate. Previously enabled collection
+resumes after a Runtime restart according to its saved schedule and permissions.
+Where Companion is required, connect the computer as an additional step before
+starting collection.
+
+#### Windows computer connected to WSL or Docker: Microsoft Store connection
 
 **ABot AI Companion** is available from
 [Microsoft Store](https://apps.microsoft.com/detail/9PK2FDQQLQS9).
@@ -187,6 +210,22 @@ computer and enables startup at sign-in. This path does not download a Finder
 installer or require an Apple Developer account. Use **Repair Mac connection**
 to repair or update an existing connection while retaining its pairing.
 
+After updating and restarting Runtime, an already connected Mac may still have
+an older Marketplace installation-link handler. If **Repair Mac connection** is not
+offered, use the updated CLI on that Mac to refresh the connection:
+
+```sh
+abot host status
+abot host connect --url '<url from host status>'
+```
+
+For a project-local installation, run both commands as `npx --no-install abot ...`
+from that project instead. Use the exact saved `url` reported by `host status`,
+not a new address. This reuses the existing pairing, refreshes the managed
+Companion and link handler, and briefly reconnects Computer Access. Do not run
+`disconnect` first. Then retry the Marketplace link: it opens plugin review,
+not an automatic installation.
+
 For a Mac connecting to a Docker or forwarded Runtime, choose **Connect a Mac**.
 Install the ABot CLI on that Mac, run the displayed `abot host connect --url ...`
 command in its graphical login, then paste the one-time code when Terminal asks.