@abot-ai/runtime 1.4.0 → 1.5.0

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,87 @@ 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.
+
+**Spark permissions on macOS:** Computer access **Ready** confirms the connection;
+collection additionally needs Accessibility permission. 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. Start Spark
+collection to request consent, then authorize that executable 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.
+The collector checks approval for at most two minutes without reading content.
+After granting access, choose **Restart collection** in Home or Spark to check
+again. Setup reuses identical runtime bytes; replacing the runtime can require
+consent again. Screen recording and input permissions for other desktop tools
+are separate.
+
+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
 

package/docs/long-term-memory.md

@@ -20,7 +20,12 @@ structured candidate-only call:
   "memoryCandidates": [
     {
       "content": "A durable fact or preference established by the user.",
-      "tags": ["normalized-later-by-core"]
+      "tags": ["normalized-later-by-core"],
+      "target": null,
+      "score": 95,
+      "reason": "A lasting preference explicitly established in this request.",
+      "reinforced": true,
+      "explicitRequestQuote": null
     }
   ]
 }
@@ -40,6 +45,11 @@ unchanged.
 Candidate data remains internal and is processed after the final assistant
 response is persisted. Persistence runs through a Runtime-owned background
 queue; response completion never waits for embedding or memory-store work.
+When the current user directly asks the assistant to remember a fact, the same
+authoring result can include an exact excerpt of that request. The Runtime
+binds the excerpt to the current user message and writes the fact through the
+existing protected memory management path, without candidate maturation or a
+second model call. A queued write is not confirmation of storage.
 
 Before the next terminal response is authored, the Runtime retrieves a small
 relevant set from the cross-session pool. Retrieval uses provider embeddings
@@ -52,6 +62,62 @@ contracts differ. Automatic retrieval remains a terminal-response feature.
 Planner, Worker, Reviewer, payload, and tool contexts do not receive the memory
 projection.
 
+## Shared Automatic Admission
+
+Conversation proposals and ABot Spark observations use one core maturation owner
+and the same candidate pool, even when ABot Spark collection or processing is off.
+Candidates are excluded from recall until promoted. The default promotion
+score is 90 and can be set from 0 to 100, with at least two independent
+evidence opportunities. A first proposal always
+remains a candidate, even with a score of 100. Repeated input, replayed batches,
+unchanged screen revisits and scheduled reassessment alone cannot supply fresh evidence.
+The score expresses model judgment, not a statistical probability.
+
+The model proposes durable usefulness, semantic identity, score and a short
+reason. The core binds request/batch identity, versions and evidence timestamps;
+it controls admission, expiry, deduplication and storage. Prior knowledge is
+bounded passive reference, not fresh evidence. Task diaries, temporary activity,
+QA data and unsupported inferences about the user are excluded by the shared
+authoring policy. This adds no separate judging model call.
+
+Automatic content changes to an existing memory also pass through a replacement
+candidate and the same admission gate. A replacement is bound to the original
+record version; a manual edit or deletion wins. Manual records remain protected
+from automatic changes. Existing stored records are preserved, rather than
+retroactively deleted or demoted.
+
+The shared policy is persisted with memory state. Older Co-worker settings are
+imported once, respecting the new minimum; later stale callers cannot overwrite
+the canonical policy. Candidates are bounded by 500 entries, 2 MiB and 30 days
+without reinforcement by default. Store version 5 preserves older records and
+creates a private `.pre-v5.backup` before migration. ABot 1.4.0 cannot read the
+upgraded store; preserve that backup if a downgrade may be needed. Old candidates
+receive no invented independent evidence.
+
+Candidate and receipt expiry belongs to the core memory service, even without a
+running ABot Spark. It uses one deadline timer, no periodic polling or model calls,
+and no timer when nothing awaits expiry. Standalone service owners can stop and
+restart retention through `memory.retention`; Runtime hosts own that lifecycle.
+Conversation evidence uses the same reference clock as memory admission.
+
+## Explicit Memory Plugin
+
+The `memory_add`, `memory_get`, `memory_search` and `memory_delete` tools belong
+to the independent memory plugin. They use its own deterministic store without
+an embedding model or the core long-term memory service. Their storage format,
+legacy migration and tool-permission behavior remain unchanged.
+
+Plugin records are separate from core Stored memories and its candidate pool.
+Manual creation and editing through the existing core memory management UI
+remain immediate and protected; they atomically discard matching candidates
+and pending replacements of an edited memory. Automatic conversation proposals
+still use shared maturation. Only a direct user request bound to the current
+message may use the protected core write; the plugin remains independent.
+
+Live QA should use a separately configured environment with its own runtime
+directory. Shared admission reduces accidental automatic storage, but does not
+replace isolation for tests that deliberately exercise explicit memory writes.
+
 ## Model-Requested Recall
 
 When memory is enabled, the Supervisor and Execution Agent root decisions may
@@ -123,7 +189,7 @@ performs a real embedding probe and validates the complete candidate config
 before writing it. The previous config is backed up, and a restart is required
 after enablement or disablement.
 
-The Config workspace in the packaged Web UI uses the same onboarding service.
+**Memory → Setup** in the packaged Web UI uses the same onboarding service.
 It can list configured providers, discover models when the provider supports
 discovery, probe and enable a selected model, or disable the feature. A provider
 without discovery support accepts a model id entered by the user.
@@ -220,3 +286,145 @@ candidates.
 The bundled `memory` plugin remains a separate, explicit user-invoked
 capability. Passive long-term memory does not depend on that plugin and remains
 operational if the plugin is disabled or removed.
+
+## Learning from computer activity
+
+The **ABot Spark** screen controls optional collection, learning and proactive
+suggestions. The separate **Memory** screen manages embedding setup and saved records;
+Spark's Knowledge tab shows candidates. Collection and proactive mode are off by
+default. Collected
+text is processed by the provider of the selected model; learning also requires
+working long-term memory. Collection needs a connected Companion.
+
+In **Spark → Settings → Activity permissions**, choose which activities to
+authorize and their configured models, then **Save settings**. Saving validates
+the selected models without starting work. Use each activity's **Start/Stop**
+control to run or stop it. Stopping preserves its authorization, schedules,
+resource limits and pending work. Revoking permission stops the activity and
+prevents it from starting until authorized again. Home's Start action starts all
+authorized activities together.
+
+The controls are independent. **Stop collection** stops new observations while
+already collected activity remains eligible for processing. **Stop learning**
+interrupts learning and keeps pending activity within its retention limit; it does
+not stop collection. Proactive mode has its own control and can use existing
+knowledge without new collection. **Delete pending** is a separate confirmed action
+that removes queued activity and cancels its review. Deleting pending activity
+does not delete saved memories. Starting collection does not resume explicitly
+paused processing. Older settings that were off and have no processing
+preference load with processing paused.
+
+Choose a learning model explicitly. Proactive reviews can use that model or a
+separate profile. Configure collection, learning and proactive activity hours
+independently, with an explicit time zone. Learning can start on a time interval
+or after an eligible observation count; an admitted pass drains in bounded batches.
+Storage pressure can admit eligible work earlier, subject to the same hours,
+pause and resource limits. Pending evidence expires after 24 hours. Interactive
+requests take priority and can interrupt background work for later resumption.
+
+Learning and proactive activity share persisted daily model-call and embedding
+limits. Each actual model stage consumes a call; these limits are not monetary
+or token budgets. Local or unclassified providers run one operation at a time;
+known cloud operations can use the configured concurrency. No observation review
+runs for an empty queue, although enabled proactive checks and due knowledge
+reassessments can run independently.
+
+The Companion listens for desktop accessibility events in the signed-in graphical
+session. It collects settled visible text and editable-control changes across
+applications, including documents, editors and browsers. Repeated content is
+deduplicated; revisits retain a compact activity reference. Observations retain
+their application/window identity and declared coverage, then enter bounded batches.
+An editable control changing does not establish authorship, and a visible page
+does not prove that the user read or agreed with it.
+
+The selected profile's execution policy determines the review method. Execution
+Agent profiles use a direct review. Supervisor profiles use bounded stages for
+discovery, matching, decisions, authoring and assessment, with at most 18 stages
+per learning review and four per proactive review. Each fresh stage calls the
+model; replaying valid completed stages does not. Completed stages are saved
+before the next call and can resume after pauses, resource deferrals or
+restart while the evidence, knowledge and model bindings remain valid. Changed
+or expired inputs invalidate saved progress. Neither method can invoke tools or
+perform the suggested action.
+
+Learning proposals use the shared automatic memory-admission policy described
+above. Proactive reviews may deliver a suggestion to a conversation, decline to
+send one, or schedule reconsideration. They respect independent activity hours,
+daily message limits, current knowledge versions and duplicate-delivery controls.
+Reading a delivered suggestion clears its unread Home presentation.
+
+The Applications tab has separate collection and processing exclusions. A
+processing exclusion retains pending observations under the existing expiry
+limits; it does not retract content already sent to a provider or delete saved
+memories. Previously collected activity remains explicitly deletable.
+
+Before an observation leaves the Companion, supported credential labels and
+recognizable secret formats trigger redaction of the entire affected text field
+as `[REDACTED]`. This covers captured content, source metadata, URLs and diagnostic
+reasons across applications. Surrounding ordinary text in that field is also
+removed, which can reduce learning detail; other fields remain available.
+Recognition uses a bounded rule set: unlabelled secrets and unknown formats or
+encodings can still pass through. This protection applies to newly collected
+observations after the updated Companion is running; existing stored observations
+are unchanged.
+
+Native reads are at least five seconds apart. A sustained sequence of non-edit
+changes is muted after four reads within 30 seconds, before another accessibility
+extraction. A foreground-window switch, an editable-control change or 30 seconds
+without changes releases the mute. Quiet screens do not trigger periodic reads.
+This limits noisy movie/game interfaces without identifying specific applications.
+
+Stopping collection closes the native reader and its timers. The Companion's
+connection remains available for Computer access; it watches connection-file
+changes and checks private state every 15 seconds instead of every second.
+Status writes replace a single bounded file and retain private-file permission
+checks. This is maintenance, not screen collection or model execution.
+
+The pending queue is capped at 256 observations and 2 MiB of serialized evidence;
+the raw journal holds at most 50 batches within 4 MiB. These are data bounds,
+not total process-RAM limits. Existing memory-store retention remains unchanged.
+
+The current Companion excludes ABot's own Web UI by its canonical window title
+before transport, including tabs left open with the previous canonical title.
+This requires an updated Companion and an operating system that exposes the
+window title; a hidden or rewritten title cannot be identified by this rule.
+Previously saved memories and observation history are unchanged.
+
+Windows uses UI Automation and window events. macOS uses Accessibility and a
+Swift helper; the host needs its Swift toolchain and must grant Accessibility
+permission. Linux uses a graphical session with Python AT-SPI, D-Bus and GLib
+bindings and accessible session-lock status. Missing dependencies or permissions
+are reported without installing software or escalating privileges. Wayland and
+application accessibility coverage varies: protected controls, inaccessible
+canvas content and unexposed document text remain missing, rather than being
+presented as observed. The activity collector does not capture video, audio,
+keystrokes, clipboard history or perform OCR.
+
+For WSL, run the Companion on Windows. For Docker, run it on the native desktop
+host. The Companion connects to the Runtime endpoint published or forwarded on
+host loopback; the container or WSL process does not read the desktop itself.
+The paired device grants one learning subscription at a time, so a second
+environment cannot silently start duplicate collection. Connection leases stop
+native collection when its authorized owner disconnects.
+
+ABot Spark shows collection state, recent batches and bounded observation
+detail. Memory shows saved records and their configuration. Home shows a compact
+learning section while collection is enabled or unprocessed activity remains,
+including disconnected, failed and paused-processing states.
+These screens receive invalidation events
+and fetch canonical state; they do not poll for screen data or create collectors.
+Raw batch evidence is local, private runtime state with a bounded history and
+24-hour expiry cleanup while the service runs and at startup. A stopped process
+cannot execute cleanup until it starts again. The general model-I/O trace omits
+learning payloads and model output; diagnostics retain identifiers, counts and
+failure codes. The batch details view makes partial collection visible.
+
+Connected Companions report a release number independently of the wire protocol.
+ABot Spark offers setup again when that release is older than the Runtime's bundle
+or was not reported by an older installation. The installer still verifies the
+exact bundle and replacement process; a newer Companion is not downgraded by this
+notice. Update through Computer access to replace the installed native bundle.
+
+Native platform support must be verified on the target desktop and applications.
+Fixture tests of the transport and collector scripts alone are not proof of
+desktop coverage or the quality of learned memories.