@abot-ai/runtime 1.3.1 → 1.5.0

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/dist/src/web-ui/system-host-upgrade-authority.d.ts

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

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

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

package/docs/architecture.md

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

@@ -56,33 +56,61 @@ npm init -y
 npm install @abot-ai/runtime
 ```
 
-Initialize a provider and concrete model id:
+Start the packaged Web UI:
 
 ```bash
-npx abot init --provider ollama --model <model-id>
+npx abot start
 ```
 
-If Ollama is outside the runtime process's network namespace, add
-`--base-url http://<ollama-host>:11434`. For OpenAI, use:
+Open [http://127.0.0.1:5177](http://127.0.0.1:5177). The command binds to
+loopback by default. On a fresh installation, the setup wizard lets you select
+OpenAI or Ollama, enter a concrete model ID, and save the connection. OpenAI
+accepts the API key directly in the form and stores it privately in the
+consumer's `.env`. The key is not returned to the browser or stored in runtime
+JSON. Existing OpenAI configurations missing a key open the same completion flow.
+
+For Ollama, the server must already be running with the selected model available.
+Its address is resolved from the ABot host, even when you use the UI from a phone.
+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.
+
+Command-line initialization remains available:
 
 ```bash
+npx abot init --provider ollama --model <model-id>
 npx abot init --provider openai --model <model-id>
 ```
 
-Then place `OPENAI_API_KEY` in the generated `.env`. The generated OpenAI model
-profile uses the recommended `execution-agent-v1` policy.
-
-Start the model gateway and packaged Web UI together:
-
-```bash
-npx abot start
-```
-
-Open [http://127.0.0.1:5177](http://127.0.0.1:5177). The command binds to
-loopback by default. If no usable model is configured, the Web UI still starts
-and presents its setup guide.
-
-Add another model without replacing existing providers or profiles:
+For a remote Ollama server, add `--base-url http://<ollama-host>:11434`.
+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 **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:
 
 ```bash
 npx abot add-model --profile <profile-id> --provider openai --model <model-id>
@@ -94,7 +122,8 @@ 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 and enable it through the Web UI Config workspace or CLI:
+an embedding model in the onboarding Embedding step, **Memory → Setup**,
+or the CLI:
 
 ```bash
 npx abot memory status
@@ -109,6 +138,90 @@ users can discover model ids installed at the configured Ollama endpoint.
 
 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.
+
+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. Importing ABot as a library never changes host
+configuration or starts background collection.
+
 ## Use As A Library
 
 After the package is published:

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
 
@@ -119,3 +133,17 @@ Generated runtime state remains local and ignored:
 
 Do not publish local runtime state, logs, memory, generated work output, or
 machine-specific config.
+
+## Conversation file viewing
+
+File previews require the local Runtime backend and a filesystem that supplies
+stable directory identity. Missing identity omits only the preview action;
+committed writes and edits retain their normal results. Windows-mounted folders
+in WSL can lack the required directory birth identity. This feature does not
+translate Windows/WSL paths or depend on an editor integration.
+
+Opening a file in its default desktop app is available only on macOS from a
+local Web UI connection, for supported non-executable documents and images.
+The server checks the recorded file authority before the handoff. The external
+app resolves the pathname asynchronously; it does not inherit the preview
+reader's pinned file descriptor. Native opening is never automatic.

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.