@abot-ai/runtime 1.4.0 → 1.6.0

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

@@ -1,5 +1,7 @@
-import { observeSystemHost, readSystemHostFacts, } from "../../../plugins/system/source/host-observation.js";
-import { resolveSystemTarget } from "../../../plugins/system/source/targets.js";
+import { observeSystemHost, readSystemHostFacts, } from "../../computer-access/host-observation.js";
+import { resolveSystemTarget } from "../../computer-access/targets.js";
+import { OBSERVATION_CAPABILITY } from "../../computer-access/companion/observation-protocol.js";
+import { COMPUTER_CAPABILITY } from "../../computer-access/computer/native-validation.js";
 function classifyHostEnvironment(facts) {
     const observed = observeSystemHost(facts);
     if (observed.environment === "container")
@@ -8,63 +10,90 @@ function classifyHostEnvironment(facts) {
         return "wsl";
     return "native";
 }
+function isCompanionComputerControlReady(status) {
+    if (!status.connected)
+        return false;
+    if (status.companion?.updateAvailable)
+        return false;
+    if (!status.capabilities?.includes(OBSERVATION_CAPABILITY))
+        return false;
+    return status.capabilities.includes(COMPUTER_CAPABILITY);
+}
+function isCompanionNewerThanRuntime(status) {
+    const release = status.companion;
+    if (!release?.installedVersion)
+        return false;
+    return release.installedVersion > release.availableVersion;
+}
+function readPairedCompanionReadiness(status, environment) {
+    const base = {
+        route: "companion",
+        environment,
+        platforms: [],
+        restartRequired: false,
+    };
+    if (isCompanionComputerControlReady(status))
+        return { ...base, ready: true, message: "Connected computer is ready." };
+    if (isCompanionNewerThanRuntime(status))
+        return {
+            ...base,
+            ready: false,
+            message: "This companion is newer than this Runtime. Update ABot before setting up computer access again.",
+        };
+    if (!status.connected)
+        return {
+            ...base,
+            ready: false,
+            companionUpdateRequired: true,
+            platforms: status.identity ? [status.identity.os] : [],
+            message: "The paired computer is offline. Sign in to reconnect, or use Computer access setup to repair its connection. Your existing pairing is kept.",
+        };
+    return {
+        ...base,
+        ready: false,
+        companionUpdateRequired: true,
+        platforms: status.identity ? [status.identity.os] : [],
+        message: status.companion?.updateAvailable === false
+            ? "Reinstall this computer's connection for computer tools and background collection. Your existing pairing is kept."
+            : "Update this computer's connection for computer tools and background collection. Your existing pairing is kept.",
+    };
+}
 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.",
-        };
+        return readPairedCompanionReadiness(status, environment);
     if (environment === "container")
         return {
             ready: false,
             route: "setup_required",
             environment,
-            platforms: ["windows", "macos"],
+            platforms: ["windows", "macos", "linux"],
             restartRequired: false,
-            message: "Install the connection on the Windows or Mac computer running Docker.",
+            message: "Install the connection on the Windows, Mac or Linux computer running Docker.",
         };
     const target = environment === "wsl" ? "windows" : observed.runtimeOs;
     const resolveTarget = dependencies.resolveTarget ?? resolveSystemTarget;
+    let directAccessReady = false;
     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.",
-        };
+        if (target !== "unsupported") {
+            await resolveTarget(target);
+            directAccessReady = true;
+        }
     }
     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.",
-        };
+        // The shared companion also serves hosts without native shell/WSL interop.
     }
+    return {
+        ready: false,
+        route: "setup_required",
+        environment,
+        platforms: target === "unsupported" ? [] : [target],
+        restartRequired: false,
+        directAccessReady,
+        message: directAccessReady
+            ? "Direct commands are available. Set up Computer access once to also connect desktop tools and ABot Spark."
+            : "Set up Computer access once for desktop tools and ABot Spark. The connection does not require WSL interop or a WSL restart.",
+    };
 }

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

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { HostPairingStore } from "../../../plugins/system/source/companion/pairing-store.js";
+import type { HostPairingStore } from "../../computer-access/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;
@@ -12,7 +12,10 @@ export type HostSetupRouteDependencies = {
 /** GUI writes use same-origin JSON; native code downloads use the expiring setup grant. */
 export declare class HostSetupRoutes {
     private readonly dependencies;
+    private readonly local;
     constructor(dependencies: HostSetupRouteDependencies);
+    rejectConcurrentMutation(response: ServerResponse): boolean;
+    close(): Promise<void>;
     private bundle;
     handle(request: IncomingMessage, response: ServerResponse, pathname: string): Promise<void>;
     private downloadBundle;

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

@@ -3,18 +3,23 @@ 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 { renderCompanionInstaller, } from "./installers.js";
 import { InstallerInputError } from "./installer-contract.js";
 import { readInstallerCompanionBundle } from "./companion-bundle.js";
+import { LocalHostConnection, LOCAL_HOST_SETUP_PATH } from "./local-connection.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);
+    return [setupPath, bundlePath, LOCAL_HOST_SETUP_PATH].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 });
+    sendJson(response, 400, {
+        ok: false,
+        error: "host_setup_input_rejected",
+        message: error.message,
+    });
     return true;
 }
 function isSetupPlatformRequest(value) {
@@ -22,27 +27,43 @@ function isSetupPlatformRequest(value) {
         return false;
     if (Array.isArray(value))
         return false;
-    if (Object.keys(value).length !== 1)
+    if (Object.keys(value).some((key) => !["platform", "purpose"].includes(key)))
         return false;
-    const platform = value.platform;
+    const input = value;
+    if (input.purpose !== undefined && input.purpose !== "learning")
+        return false;
+    const platform = input.platform;
+    if (platform === "linux")
+        return true;
     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;
+    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;
+    local;
     constructor(dependencies) {
         this.dependencies = dependencies;
+        this.local = new LocalHostConnection({ ...dependencies, bundle: () => this.bundle() });
+    }
+    rejectConcurrentMutation(response) {
+        return this.local.rejectConcurrentMutation(response);
     }
+    async close() { await this.local.close(); }
     async bundle() {
         if (this.dependencies.bundleFile)
             return readFile(this.dependencies.bundleFile);
         return readInstallerCompanionBundle();
     }
     async handle(request, response, pathname) {
+        if (pathname === LOCAL_HOST_SETUP_PATH) {
+            await this.local.handle(request, response);
+            return;
+        }
         if (pathname === bundlePath) {
             await this.downloadBundle(request, response);
             return;
@@ -58,11 +79,18 @@ export class HostSetupRoutes {
         try {
             input = JSON.parse(raw.toString());
         }
-        catch { /* rejected below */ }
+        catch {
+            /* rejected below */
+        }
         if (!isSetupPlatformRequest(input)) {
-            sendJson(response, 400, { ok: false, error: "invalid_host_setup_platform" });
+            sendJson(response, 400, {
+                ok: false,
+                error: "invalid_host_setup_platform",
+            });
             return;
         }
+        if (this.rejectConcurrentMutation(response))
+            return;
         const readiness = await this.dependencies.readiness();
         if (!readiness.platforms.includes(input.platform)) {
             sendJson(response, 409, {
@@ -72,20 +100,23 @@ export class HostSetupRoutes {
             });
             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);
+        if (this.rejectConcurrentMutation(response))
+            return;
+        const upgrading = Boolean(this.dependencies.store.host());
+        const pairing = upgrading
+            ? this.dependencies.store.beginBundleUpgrade()
+            : this.dependencies.store.begin(15 * 60_000);
         const installer = await renderCompanionInstaller({
             platform: input.platform,
             url: requestRuntimeOrigin(request),
             code: pairing.code,
             expiresAt: pairing.expiresAt,
+            ...(upgrading
+                ? { upgradeHostId: this.dependencies.store.host().hostId }
+                : {}),
             bundleSha256: createHash("sha256").update(bundle).digest("hex"),
         });
         sendJson(response, 200, {
@@ -116,6 +147,8 @@ export class HostSetupRoutes {
     hasCurrentSetupGrant(credential) {
         if (!credential)
             return false;
-        return this.dependencies.store.authenticate(credential) === "pairing";
+        if (this.dependencies.store.authenticate(credential) === "pairing")
+            return true;
+        return this.dependencies.store.authenticateBundleUpgrade(credential);
     }
 }

package/dist/src/web-ui/system-host-startup-diagnostic.d.ts

@@ -0,0 +1,2 @@
+/** Only fixed codes leave this boundary; native errors can contain private paths. */
+export declare function reportHostStartupFailure(error: unknown): void;

package/dist/src/web-ui/system-host-startup-diagnostic.js

@@ -0,0 +1,53 @@
+const STARTUP_FAILURE_CODES = new Set([
+    "host_broker_requires_linux_runtime",
+    "local_runtime_directory_not_private",
+    "host_state_directory_invalid",
+    "host_state_owner_invalid",
+    "host_state_directory_not_private",
+    "host_broker_socket_invalid",
+    "host_broker_socket_owner_invalid",
+    "long_term_memory_store_lock_timeout",
+    "EACCES",
+    "EADDRINUSE",
+    "EADDRNOTAVAIL",
+    "EBADF",
+    "EEXIST",
+    "EINVAL",
+    "EISDIR",
+    "EMFILE",
+    "ENAMETOOLONG",
+    "ENFILE",
+    "ENOENT",
+    "ENOSPC",
+    "ENOTDIR",
+    "ENOTEMPTY",
+    "EPERM",
+    "EROFS",
+]);
+const UNKNOWN_STARTUP_FAILURE = "host_broker_startup_failed";
+function isRecognizedStartupFailureCode(value) {
+    if (typeof value !== "string")
+        return false;
+    return STARTUP_FAILURE_CODES.has(value);
+}
+function startupFailureCode(error) {
+    if (typeof error !== "object")
+        return UNKNOWN_STARTUP_FAILURE;
+    if (error === null)
+        return UNKNOWN_STARTUP_FAILURE;
+    const code = error.code;
+    if (isRecognizedStartupFailureCode(code))
+        return code;
+    if (!(error instanceof Error))
+        return UNKNOWN_STARTUP_FAILURE;
+    if (isRecognizedStartupFailureCode(error.message))
+        return error.message;
+    return UNKNOWN_STARTUP_FAILURE;
+}
+/** Only fixed codes leave this boundary; native errors can contain private paths. */
+export function reportHostStartupFailure(error) {
+    console.error({
+        event: "host_broker_startup_failed",
+        code: startupFailureCode(error),
+    });
+}

package/docs/architecture.md

@@ -137,3 +137,18 @@ Generated local state is ignored by git:
 
 Do not publish local sessions, logs, memory, artifacts, or machine-specific
 configuration.
+
+## Shared computer access
+
+`src/computer-access` owns native OS drivers, the Companion protocol, pairing,
+private state, process replacement and bounded passive observation collectors.
+The CLI and Web host compose this infrastructure independently of configured
+plugins. Runtime passive learning connects through its existing injected
+observation port; deleting or disabling SYSTEM does not remove that connection.
+
+SYSTEM owns model-facing tool declarations, request bindings, approvals and result
+projection. It consumes `src/plugin-sdk/computer-access.ts`; shared host code never
+imports optional plugin implementations. The SDK subpath is opt-in so ordinary
+plugins need not load computer drivers. A shared installation does not grant tool
+permissions or enable collection. The native collector starts only for an active
+observation lease; request computer backends remain lazy and disposable.

package/docs/installation.md

@@ -75,6 +75,8 @@ Continue through the optional **Embedding** step to configure semantic memory,
 or choose to set it up later. **Plugins** starts with all tools selected for a
 fresh installation; turn off any plugin or individual tool you do not want.
 Choose **Finish setup** to apply the selections, then **Start chatting**.
+Complete initial setup on Home before opening other workspaces. Spark appears
+when setup is ready; Computer access remains available throughout setup.
 Saving chat connection details does not make a paid model request. Explicitly
 checking an embedding model sends a small embedding probe to the chosen provider.
 
@@ -90,11 +92,23 @@ OpenAI profiles use the recommended `execution-agent-v1` policy. A gateway
 managed by a separate process remains under that process's lifecycle; the UI
 reports when saved changes require that owner to restart.
 
-In the Web UI, open **Config → Models → Add model** to add another model.
+In the Web UI, open **Models → Add model** to add another model.
 Choose a saved provider connection or create a new OpenAI/Ollama connection.
 Each provider card also has an **Add model** shortcut. Review the model, then
 choose **Save and apply**. Saved API keys are reused; existing model profiles and
 the default model are preserved. The added model is selected in the Models list.
+New profiles are stored in a separate `models/<profile-id>.config.json` beside
+the selected Runtime configuration, which keeps only its `configRef`. Existing
+inline profiles continue to work. If activation is deferred, the dialog confirms
+that the model is saved but not active yet; **Apply model** retries activation
+without adding it again, and **Close** keeps the saved declaration.
+
+Use **Remove model** to remove a profile from the Runtime declaration. Referenced
+model files, provider connections and credentials are retained. Files in the
+standard `models/` directory, and directories still referenced by another
+profile, appear as **Not registered**. Removal is refused if it would break the
+configuration, such as a default model or a request-runner mapping. Update those
+references first, then remove the profile and explicitly **Apply changes**.
 
 You can also add a model from the command line:
 
@@ -108,7 +122,7 @@ the profiles that are already configured.
 ### Optional Passive Long-Term Memory
 
 Long-term memory is disabled by default. After a provider is configured, choose
-an embedding model in the onboarding Embedding step, the Web UI Config workspace,
+an embedding model in the onboarding Embedding step, **Memory → Setup**,
 or the CLI:
 
 ```bash
@@ -126,24 +140,119 @@ See [Passive Long-Term Memory](long-term-memory.md) before enabling persistence.
 
 ### Computer Access During Setup
 
-The optional **Computer** step checks whether direct system access already works.
-Native macOS and working WSL-to-Windows access need no additional configuration.
-You can also open this step later in **Config → Connected computer**.
-
-For Docker, download and open the Windows or Mac setup script on the computer
-running Docker. It installs the matching companion and its private Node runtime,
-pairs automatically and enables user-login startup. No copied code, separate npm
-installation or terminal command is required. Wait for **Ready** in the Web UI.
-
-For WSL with unavailable Windows interop, download and open the Windows repair
-script. Opening it enables Windows interop and automatically restarts only the
-selected distribution, preserving unrelated configuration. Finish active work
-before opening the file: the restart interrupts that distribution's services.
-No typed restart confirmation is required; the script verifies Windows access
-after the restart.
+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.
+
+When ABot runs natively on your Mac, open its local Web UI and choose **Connect
+this Mac**. ABot uses its installed Node runtime and companion bundle, pairs the
+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.
+
+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.
+The code expires after five minutes. Docker must publish the Web UI port on host
+loopback; a remote Runtime needs a local port forward. Direct connections to a
+remote network address are not supported. Mac desktop tools and Spark collection
+still require local Swift tools and the relevant macOS privacy permissions.
+
+**Prepare macOS permissions before chatting:** The optional Computer setup step
+and **Home → Computer access** show separate preparation for desktop tools through
+the **Companion** and direct **SYSTEM commands through the active Runtime**.
+Connection status and operating-system permission status are separate; grants
+for one route do not establish access for the other. Check Screen Recording and
+Accessibility in each available route, then request its missing permission from
+that section and follow macOS settings. Checking does not capture a screen,
+read window content, type, or start Spark collection. Recheck after granting
+access; if macOS requires a restart, finish it before starting a conversation.
+
+Companion setup keeps a
+private copy of its Node executable at `~/.abot/host-companion/runtime/node` and
+uses that same path at sign-in, independently of NVM version paths. Authorize
+the executable identified by the permission panel in **System
+Settings → Privacy & Security → Accessibility** (called **Device Control & Data
+Access** on some macOS versions). Use **+**, **Command–Shift–G**, and the path above
+if needed. The entry may be named `node`; verify the path before approving it.
+Setup reuses identical runtime bytes; replacing the runtime can require consent
+again. Spark collection remains separately controlled and does not start when
+permissions are prepared.
+
+Native SYSTEM commands launched by ABot through Terminal or another application
+have that caller's permission identity, separate from the Companion. Their panel
+checks the process owning the selected Runtime environment, even when the Web
+server is attached to a different process. Inspect the displayed computer and
+executable, follow the macOS prompt for that route, and recheck after changing
+access. A replaced Runtime or a different environment requires a new check.
+If macOS asks to reopen Terminal or ABot, do that before starting a conversation.
+Permission preparation does not restart either process automatically.
+
+This Runtime preparation is available from a local Web connection on the Mac;
+unsupported or unavailable routes are shown explicitly. The CLI remains useful
+for setup before ABot starts or for diagnosis from the same Terminal/application:
+
+```bash
+abot host permissions
+abot host permissions --request screen-recording
+abot host permissions --request accessibility
+```
+
+The first command only checks. The request commands may show an operating-system
+prompt; approve the identity shown by macOS and check again afterward. They do
+not change Computer access pairing or send a model request. Application-specific
+Automation/Apple Events and protected-file access may still require separate
+consent for the applications or locations used by a later SYSTEM command.
+
+For Windows or Linux, download setup and run it in that computer's graphical
+login. Windows setup installs the companion and a private Node runtime; Linux
+uses an existing Node.js installation. Setup pairs automatically and enables
+startup at sign-in. Wait for **Ready** in the Web UI; downloading alone does not
+establish a connection. WSL uses the same Windows companion setup, which does
+not require changing interop settings or restarting the distribution.
+
+Installation does not enable ABot Spark collection or disabled plugin tools.
+Collection and processing controls remain in ABot Spark; tool approval modes still
+apply. Use **Unpair computer** to revoke the shared pairing and pending setup
+grants. Saved insights are retained. Reconnect through Computer access setup.
+Updates reuse the existing pairing and must replace the actual running companion.
+
+### Notifications
+
+Open **Notifications** for saved notifications, unread counts, source links and
+desktop notification settings. ABot records agent replies received while their
+conversation is not visible and focused, failed requests, approval requests and
+delivered ABot Spark suggestions. Settings control desktop delivery for each kind;
+the history stays available when desktop delivery is disabled or disconnected.
+
+Desktop notifications use the paired Computer access companion. The browser can
+be closed while ABot and the companion keep running in your graphical login.
+Install or update Computer access to register the **ABot** notification identity.
+Clicking a notification opens its source in your default browser. Docker and WSL
+use the companion on the desktop computer; links retain the address and published
+port used during pairing.
+
+- **Windows:** setup registers ABot with Windows notifications and a click handler.
+- **macOS:** setup installs a local ABot application. Allow notifications for ABot
+  in macOS settings when prompted. The helper currently uses Apple's legacy
+  `NSUserNotification` API; availability depends on the macOS release.
+- **Linux:** a graphical desktop with its notification service, `notify-send`
+  (including action support), `gdbus` and `xdg-open` is required. The desktop's
+  notification service must support actions. On Debian/Ubuntu, these commands
+  come from `libnotify-bin`, `libglib2.0-bin` and `xdg-utils`, respectively.
+  ABot keeps up to 32 active desktop alerts; when another arrives, it closes the
+  oldest alert. All saved notifications remain available in Notifications.
+
+Operating-system permissions and Do Not Disturb still control presentation.
+**Sent to computer** means the native delivery call succeeded, not that a person
+saw the notification. Unconfirmed deliveries and old records are not sent again
+after reconnect or restart. A failed notification setup leaves the other Computer
+access features available; the Notifications page reports desktop availability.
+
 See [Connecting a Docker Runtime to its computer](projects-and-full-plus.md#connecting-a-docker-runtime-to-its-computer)
-for connection limits and removal. Installing ABot as a library never changes
-host configuration or enables interop.
+for connection limits and removal. Importing ABot as a library never changes host
+configuration or starts background collection.
 
 ## Use As A Library
 

package/docs/known-limitations.md

@@ -18,6 +18,7 @@ The current public entrypoints are:
 - `@abot-ai/runtime/runtime/adapters`
 - `@abot-ai/runtime/runtime/ports`
 - `@abot-ai/runtime/plugin-sdk`
+- `@abot-ai/runtime/plugin-sdk/computer-access`
 - `@abot-ai/runtime/model-gateway`
 - `@abot-ai/runtime/runtime.config.schema.json`
 
@@ -104,9 +105,22 @@ request state.
 ## Steering And Cancellation
 
 Text steering is not a hard cancellation mechanism for active delegated work.
-Hosts that require immediate cancellation need an explicit mechanical abort
-path with defined child, capability, persistence, and terminal-state semantics.
-Cancellation must not be inferred from message wording.
+The Web UI Stop control and local Runtime cancellation API explicitly cancel an
+active request and preserve its stopped conversation context. Stopping does not
+undo completed tool effects. Cancellation must not be inferred from message wording.
+
+## Saved Tool Approvals
+
+Web UI requests save a pure approval wait with the conversation and release their
+live execution resources. Compatible waits survive Runtime restart and resume the
+prepared action only after an explicit decision. New requests and Jobs in that
+conversation are blocked while it waits; cancellation remains available.
+
+Restart interrupts work that was actually running and never replays it
+automatically. An incompatible or unreadable continuation stays pending and
+cancellable. Older approval events cannot be upgraded into executable
+continuations. Bridge and scheduler clients without durable-approval support
+retain their existing live-owner contract.
 
 ## Generated State