@abot-ai/runtime 1.7.0 → 1.8.0

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.

package/docs/plugins.md

@@ -237,12 +237,71 @@ options, or skill lists in `runtime.config.json`. Installing or changing a
 plugin means changing its package under `plugins/`; runtime config only decides
 whether that installed capability is available.
 
+## Runtime Platform Compatibility
+
+A plugin can declare where its code can run using a separate manifest extension:
+`extensions["ai.abot.compatibility"] = { "version": 1, "runtimePlatforms": ["linux", "darwin"] }`.
+The executable `ai.abot.runtime` extension remains at version 1.
+
+`runtimePlatforms` is a non-empty, duplicate-free list of Node platform names:
+`linux`, `darwin` (macOS), or `win32` (Windows). Unsupported versions, platform
+names and fields are rejected. Declare only platforms on which the complete
+plugin can safely load; individual operations may still require permissions,
+external programs or a connected computer.
+
+The declaration describes the **Runtime host**, not the browser or the computer
+controlled by a tool. A Linux Runtime in WSL or a Linux Docker container remains
+`linux`, including when SYSTEM controls a Windows Companion. It does not grant
+permissions or replace the tool's request-time target checks.
+
+Hosts with this compatibility support apply the following policy before resolving
+plugin settings/secrets or importing executable plugin code:
+
+- A declared matching platform can load, subject to the existing saved selection.
+- A declared non-matching platform cannot load.
+- Without a declaration, existing non-Windows behavior is preserved. Native
+  Windows reports **Compatibility not declared** and does not load the plugin.
+
+Installed, onboarding and model-selection views show compatibility separately
+from saved plugin/tool selection. Changing hosts does not rewrite saved selection
+or erase settings and keys. An incompatible package remains inspectable,
+configurable and removable. It can be installed for later use on a supported
+host; the review and installation result explain that it will not load here.
+Applying configuration cannot bypass the loader gate.
+
+**Older hosts:** ABot 1.7.0 accepts and preserves additional extension namespaces
+but does not enforce this declaration. Its existing behavior remains unchanged.
+This metadata is not an enforcement guarantee on older hosts, nor a claim that
+ABot 1.7.0 or its bundled plugins support native Windows. Existing bundled plugin
+manifests are not certified for Windows by this contract change.
+
+The required `windows-compatibility` CI job builds the Runtime, checks types and
+plugin packages, and runs the focused platform contract and loader suites on
+Windows with Node 24. It complements the Linux validation and macOS Companion
+checks; it does not certify all native Windows tool operations or Store packaging.
+
 ## Manifest Contract
 
 `@abot-ai/runtime/plugin-sdk` is the single public plugin-authoring entrypoint. It
 exports the manifest constants and types, entrypoint contract, and bounded
 authoring helpers consumed by plugin implementations.
 
+The SDK's `readBoundedRegularFile(path, { rootPath, maxBytes, signal })` reads one
+regular file within its authorized root and returns bounded bytes or a typed
+refusal. On native Windows, it uses the same C# handle primitives as `filesystem`,
+compiled by the built-in Windows PowerShell for each read. Root and file identity
+are checked before reading; traversal rejects reparse points beneath the root,
+including junctions. Binary content and documents up to 10 MiB are covered by
+native tests; each caller still sets its own size limit. Linux/macOS retain the
+existing no-follow file-descriptor path.
+
+A Windows policy or compiler restriction returns `safe_open_unsupported`. Plugins
+must report that safe reading is unavailable and avoid automatic retries or a
+less restricted fallback. Cancellation stops the helper and throws `AbortError`;
+a helper deadline (15 seconds) or ordinary I/O failure remains an explicit error.
+This SDK support does not enable Windows compatibility in a plugin manifest.
+Each plugin must still declare and validate its own Windows support.
+
 The manifest follows the Agent Plugins 1.0 package shape and keeps the local
 executable contract under `extensions.ai.abot.runtime`:
 
@@ -364,10 +423,14 @@ receive it. Planner uses this same brief instead of a separate aggregate-tag
 catalog. Its existing group-selection schema and Worker scope enforcement stay
 unchanged; descriptions do not select a group or execute an operation.
 
-Under `execution-agent-v1`, the canonical root receives group descriptions
-generated from member capability ids and summaries, and may mechanically open
-or extend its own RoleCall scope.
-It then selects a concrete capability only from that active scope. Scope
+Under `execution-agent-v1`, the canonical root receives every group and member
+in ASCII order on each decision, and may mechanically open or extend its own
+RoleCall scope. A capability's exact summary appears as `capabilityId: summary`
+at its first group membership; later memberships contain only its id, referring
+to that definition. The first group has no selection priority. Descriptions
+are neither sampled, truncated, nor synthesized. The active catalog supplies
+each capability's id and effect; its selection controls remain in the decision
+schema. It then selects a concrete capability only from that active scope. Scope
 updates, capability binding, payload authoring, adapter execution, and
 settlement use the same ledger and capability engine as delegated Worker
 execution. Unknown, empty, invalid, repeated, or no-op scopes are rejected
@@ -492,6 +555,36 @@ they must not include secrets and they never act as instructions, new user
 intent, or proof that the whole request completed. See
 [tool-execution-result-evidence-contract.md](tool-execution-result-evidence-contract.md).
 
+### Reporting a confirmed mutation
+
+Use `successResult()` for ordinary successful observations. After the owning
+plugin has confirmed a completed mutation, use `mutationSuccessResult()` to
+preserve its receipt and add the Runtime's required `data.mutationEvidence: true`:
+
+```ts
+import { mutationSuccessResult } from "@abot-ai/runtime/plugin-sdk";
+
+// apiReceipt is the result of a completed write already confirmed by this handler.
+return mutationSuccessResult({
+  output: "The article was published.",
+  data: apiReceipt,
+}, context.resultBudget);
+```
+
+The helper does not execute the operation or independently verify its effect.
+Do not use it for a failed, ambiguous, pending, or no-op operation. It retains
+the same JSON and result-size bounds as `successResult()`; a rejected receipt
+returns a failure without asserting mutation evidence. The existing generic
+helper does not infer a mutation from `ok`, `progress`, prose, or the presence of
+arbitrary data. Explicit `actions`, `progress`, and other result fields remain
+available to the owning plugin.
+
+The adapter records operation outcome separately from observed effect.
+For a `mutating` operation, `ok: true` without `mutationEvidence: true` is
+classified as `mutation_evidence_missing`. The new helper supplies that marker
+after the plugin has established the evidence; it does not change the Runtime's
+classification rules or prove completion of the user's whole request.
+
 ### EXEC output storage
 
 EXEC captures stdout and stderr in private files under its injected `stateDir`.
@@ -654,6 +747,54 @@ counts imply full-file coverage.
 
 No concrete tool or skill mapping should be added anywhere under `src/runtime`.
 
+### Native Windows plugin support
+
+The native Windows group contains `capability-brief`, `code-outline`,
+`document-reader`, `exec`, `filesystem`, `json-inspector`, `local-search`, `memory`, `web`,
+`project-orientation`, `system-probe`, and `system`.
+Each declares `win32` in its versioned
+`ai.abot.compatibility` extension, alongside its existing Linux and macOS support.
+Compatibility uses the Runtime process OS, not the browser or a paired computer.
+A Windows-only plugin should declare only `win32`; other hosts will not load it.
+
+On native Windows, SYSTEM provides `system_targets`, `system_command`,
+`system_applications`, and `system_launch`. Commands run in local PowerShell and
+retain existing approvals, cancellation, and protected output handling. Desktop
+observation and input (`computer_*`) are excluded from the request catalog in
+this phase. Linux/macOS Runtime and WSL/Docker Companion routes retain their
+existing capabilities. This phase does not add screenshot OCR.
+
+`system-probe` reports Windows load averages as unsupported instead of presenting
+the OS's placeholder zeros as measured load. Its default disk probe uses the
+Runtime installation's filesystem; an explicit path selects that path's volume.
+
+`code-outline` uses the SDK's bounded file reader on Windows, with the same
+authorized roots, parser and output limits as Linux/macOS. If safe reading is
+unavailable, it reports the restriction explicitly and tells the model not to
+retry or bypass it. See [Code Outline](../plugins/code-outline/README.md).
+
+`document-reader` uses the SDK's bounded Windows reader for configured paths
+and request attachments, with shared text, Office and PDF parsers and limits.
+A blocked reader reports an explicit no-retry restriction.
+See [Document Reader](../plugins/document-reader/README.md).
+
+`json-inspector` uses the SDK's bounded Windows reader with the existing path,
+UTF-8, size and summary limits. A blocked reader reports an explicit no-retry
+restriction. See [JSON Inspector](../plugins/json-inspector/README.md).
+
+`project-orientation` uses the SDK's bounded Windows reader for package
+metadata and retains its existing directory-tree and result limits. Blocked
+manifest reads return an explicit no-retry restriction.
+See [Project Orientation](../plugins/project-orientation/README.md).
+
+`local-search` uses native Windows ripgrep through a PowerShell/C# helper that
+pins the selected path and owns the child process through a Job Object. Existing
+query, output, timeout and cancellation limits still apply. A blocked helper
+fails explicitly without a retry or policy bypass.
+See [Local Search](../plugins/local-search/README.md).
+
+Enabling manifests alone is not a validation step.
+
 ### Shared Computer access
 
 Plugins that need host facilities can import the opt-in