@abot-ai/runtime 1.3.1 → 1.4.0

package/docs/installation.md

@@ -56,33 +56,47 @@ 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**.
+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.
+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.
 
-Start the model gateway and packaged Web UI together:
+In the Web UI, open **Config → 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.
 
-```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:
+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 +108,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, the Web UI Config workspace,
+or the CLI:
 
 ```bash
 npx abot memory status
@@ -109,6 +124,27 @@ 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 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.
+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.
+
 ## Use As A Library
 
 After the package is published:

package/docs/known-limitations.md

@@ -119,3 +119,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/plugins.md

@@ -11,6 +11,30 @@ duplicate manifest `name` across the bundled and consumer catalogs is rejected
 rather than treated as an override. In a source checkout, where both roots are
 the same physical directory, the catalog is discovered only once.
 
+## Manage Plugins In The Web UI
+
+Open **Configuration → Plugins** to see installed manifests, capability counts,
+and enabled, partially enabled or disabled selections. Switches save the selected
+plugin's configuration while preserving capability-specific allow/deny rules.
+Choose **Manage tools** on a plugin to manage its declared tools inside the same card.
+The card keeps its size; the tool list scrolls when needed. Use **Back** or Escape
+to return to the plugin overview. For example, disabling filesystem.read_file
+leaves dev_view, edit_file and write_file unchanged. Tool switches write qualified selectors and preserve
+the selections of every other tool. A plugin can remain enabled with all its
+tools switched off.
+
+Global, parent-plugin and broad tool deny rules remain explicit blockers.
+A child switch does not silently remove those rules or enable sibling tools.
+
+Choose **Apply changes** to activate saved settings. The Web process replaces
+only its own idle environments and preserves session and Job files. If any
+environment is working, or another process owns it, changes remain saved and
+the UI explains why they cannot yet be applied. Saving a switch alone does not
+change tools available to an already running agent.
+
+This screen manages packages already installed on disk; it does not install
+plugins from a marketplace.
+
 ## Package Shape
 
 ```text
@@ -119,6 +143,14 @@ input, effect, and approval. Optional capability metadata such as client event
 presentation, payload authoring, development roles, and selection grounding
 belongs here as well—not in runtime orchestration.
 
+A plugin declares sensitive operations with `approval: "always"` in its
+manifest, as the bundled EXEC and SYSTEM plugins do. Apply that policy to every
+operation when the whole plugin is sensitive. The generic approval boundary
+keeps enabled operations available in all modes: Ask and Full approve each exact
+prepared action; FULL+ skips that extra prompt. A disabled plugin stays absent.
+Sensitivity is declared by the plugin, never inferred from command text or tool
+names. Ordinary `request_policy` operations retain their existing mode behavior.
+
 `catalogGroups` classifies a capability in one or more request-catalog groups.
 A plugin-level non-empty array under `ai.abot.runtime` is inherited by every
 capability; an optional capability-level array overrides that default. Values
@@ -132,25 +164,42 @@ against a non-empty catalog. The runtime stores that scope on the Worker call
 and exposes the OR-union of matching capabilities. The Worker still selects
 the concrete capability and controls.
 
-Supervisor routing receives one optional, passive text brief from the same
-request-filtered registry used by `capability-brief`. It chooses the richest
-complete representation that fits: tool names with operation ids and groups,
-tool names by group, group counts and effects, or no brief. The brief replaces
-the previous aggregate catalog text; group ids remain in the response schema
-in every mode. It includes no tool descriptions, inputs, or operating
-instructions. Its 512-token estimate ceiling is further reduced by existing
-context headroom, including history and instruction reserves. No subset of
-tools is selected to fit, and no model call summarizes the catalog.
-This admission uses the context estimate at projection time. A later provider
-token count, steering update, or structured-output repair can still trigger
-the existing context-compaction path; the brief is not reselected there.
+Supervisor routing and delegated Planner each receive one optional, passive
+text brief through the same shared projection from the
+request-filtered registry used by `capability-brief`. It first includes every
+offered operation's tool name, operation id, summary and catalog groups when
+that complete description set fits the existing context headroom. Request-bound
+facts already present in summaries, such as available execution targets, remain
+intact. Admission reserves each consumer's existing context, configured
+instructions, calibration, output and safety headroom and stays below the
+existing compaction threshold. Root steering is reserved only for Supervisor;
+it does not enter the bounded Planner call.
+
+When complete descriptions cannot fit, the existing compact representations
+remain available under a 512-token ceiling: tool names with operation ids and
+groups, tool names by group, group counts and effects, or no brief. The declared
+level makes omitted detail explicit; it never implies that omitted detail means
+an operation is unavailable. Group ids remain in the response schema in every
+mode. No subset of tools is selected, no summary is truncated, and no model call
+summarizes the catalog. The brief carries no input schemas, execution authority
+or completion evidence. It is confined to delegation decisions; Worker selection,
+Execution Agent context, approval and terminal-response contracts are unchanged.
+Before each Supervisor routing or Planner attempt, including structured-output repairs,
+the optional brief is reselected against the actual projected messages plus
+current consumer-specific calibration and context. It retains its reference position or is
+omitted when no complete level fits; repair instructions and other context stay
+intact. Already inserted methodology is counted once. Provider token counts may
+still differ from these estimates and trigger the existing context-compaction
+path.
 
 The SDK exports `buildToolAvailabilityBrief` for the unchanged on-demand plugin
 output and `buildToolAvailabilityOverview` for informational representations.
 The runtime context helper owns token admission and the passive reference
 message; another step can explicitly attach it using the existing context
 reference API. Supervisor's working-directory and response phases do not
-receive it. Planner retains its existing group-routing projection.
+receive it. Planner uses this same brief instead of a separate aggregate-tag
+catalog. Its existing group-selection schema and Worker scope enforcement stay
+unchanged; descriptions do not select a group or execute an operation.
 
 Under `execution-agent-v1`, the canonical root receives group descriptions
 generated from member capability ids and summaries, and may mechanically open
@@ -230,6 +279,23 @@ Run `npm run typecheck:plugins` while developing. Run
 `npm run build:plugins` to regenerate every public `src/index.cjs`; CI uses
 `npm run check:plugin-build` to reject stale or hand-edited generated output.
 
+Plugins may export an asynchronous `prepareRequest(selectedModules)` hook alongside
+`handlers` and `adapters`. The host invokes it once per plugin for each request,
+after configuration selection and before projecting any model catalog. It receives
+detached frozen contracts and may remove tools or operations, narrow input enums,
+update operation summaries, and bind request-local implementations/adapters.
+Names, definitions, effects, approval policy, fixed parameters, and the remaining
+input contract cannot change. Disabled tools are never passed to the hook and
+cannot be returned. A preparation failure fails the request; it does not silently
+restore the unprepared catalog. Prepared state is not cached across requests.
+
+A call adapter may provide `executionBinding(call)` with an opaque `identity` and
+optional human-facing `metadata`. The identity participates in the normalized
+action fingerprint before approval; it is not a model input or tool result.
+Metadata is for approval and Activity disclosure only. The bound implementation
+must enforce that same captured destination at dispatch and reject stale bindings.
+Both supported execution policies consume this same prepared registry.
+
 The loader rejects missing or unexpected handlers. Plugin settings defaults
 and secret environment-variable names may be declared in `plugin.json`;
 secret values never belong in the manifest. Optional secrets do not alter the
@@ -259,7 +325,7 @@ intent, or proof that the whole request completed. See
 ## Filesystem Roots
 
 `environment.paths.agentWorkDir` is the configured primary work root. Plugins
-must resolve user-controlled filesystem targets through the injected
+with scoped filesystem operations must resolve user-controlled targets through the injected
 `runtimePathResolver`; they must not reproduce normalization, containment, or
 symlink policy. The plugin explicitly declares the configured locations that
 its operation accepts, while the Runtime proves the resulting physical path:
@@ -282,10 +348,36 @@ files. Read-only system inspection may opt into `host_system`; that location
 accepts absolute paths only and is never included implicitly. Plugins must not
 use it for mutation or as a fallback when a configured work root is missing.
 Paths outside declared roots and canonical symlink escapes fail before plugin
-I/O. Plugins must not infer or advertise a physical `sandbox/` alias.
+I/O for these scoped operations. Plugins must not infer or advertise a physical
+`sandbox/` alias. Trusted shell execution follows the explicit exception below.
 Attachment handles are a separate request-owned source and are not converted
 into ordinary filesystem targets.
 
+After a committed file mutation, the optional
+`executionContext.reportFileOutput({ target, operation, rootIdentity })` callback
+can report the exact resolved target for client presentation. `operation` is
+`created` or `updated`; no-op and failed mutations must not report an output.
+`rootIdentity` contains decimal strings for `device`, `inode` and `birthtimeNs`,
+read from the actual mutation root directory handle. Keep that handle open until
+the synchronous callback returns. The host checks this identity against the
+currently configured root before reading or creating a marker. Missing or
+mismatched identities omit the card, including a root replaced between commit
+and reporting. A receipt is published only on a successful mutating completion
+with `mutationEvidence: true`. The callback
+is best-effort: its absence or failure must not change a committed mutation's
+result. Never copy the receipt, physical path or presentation metadata into the
+canonical tool result. The bundled filesystem write/edit tools use this channel;
+it creates neither a file catalog nor a historical snapshot.
+
+The host binds that receipt to the root directory instance using its filesystem
+identity and a random token in `.abot-file-output-root`. Presentation capture
+creates this small marker once, without overwriting an existing file; preview
+only reads it. Symlink, malformed, missing or changed markers cannot authorize
+older receipts. Removing a marker revokes those receipts; a later successful
+mutation can establish a new token. Filesystems without stable directory birth
+identity omit presentation receipts while preserving the tool's mutation result.
+Legacy receipts containing only a path-derived root hash are not upgraded.
+
 Plugin state belongs to the factory instance. Mutable module globals are not
 allowed because one host process may load more than one Runtime. File-backed
 state uses a plugin-owned directory, serialized mutations, atomic replacement,
@@ -322,10 +414,23 @@ and rendered text. A truncated success reports machine-readable truncation
 metadata; an operation that cannot produce a truthful bounded result fails
 explicitly.
 
-The bundled `exec` plugin supports Linux and macOS with non-interactive
-`/bin/bash`. Commands must use utilities available on the host. Its configured working directory is constrained to
-agent-work or workspace roots, but the shell runs with the Runtime process
-permissions and is not an operating-system sandbox.
+The bundled `exec` plugin provides trusted, non-interactive `/bin/bash` execution
+on Linux and macOS. Execute, wait and cancel each declare `approval="always"`:
+Ask/Full require exact-action approval, and FULL+ skips that extra prompt.
+Commands run as the Runtime OS user without lexical path or command-name checks.
+The explicit cwd must be an accessible existing directory; relative paths and
+`workspace/...` use their configured context bases, while absolute host paths
+are allowed. Trusted shell execution is outside the scoped filesystem contract
+above; project folders do not sandbox code. Dedicated file-tool restrictions
+remain unchanged. Native shell syntax and installed utilities determine command
+behavior; process ownership, cancellation, timeout and output limits still apply.
+
+Dev View locators are literal substrings that must identify a unique occurrence
+in the bounded file scan. An ambiguous locator remains an explicit failure,
+with bounded candidate line ranges and numeric controls for inspecting observed
+locations. The caller must omit `locator` when using those numeric controls.
+Candidate and scan truncation are explicit; neither previews nor candidate
+counts imply full-file coverage.
 
 ## Adding A Plugin
 

package/docs/projects-and-full-plus.md

@@ -0,0 +1,218 @@
+# Projects and FULL+
+
+Projects organize conversations around a working folder. FULL+ authorizes
+system actions without per-action approval through the existing permission selector. These are independent choices:
+a project does not grant system access, and FULL+ does not require a project.
+
+## Projects
+
+Use the folder-plus button on the navigation rail. Choose a folder in the main
+conversation area, optionally give the project a name, and select **Create project**.
+**Browse** opens an inline folder picker. Navigate to a folder and choose
+**Use this folder** to apply it; cancelling the picker preserves the typed path.
+The folder browser shows directories on the Runtime computer, which may differ
+from the computer running the browser. Absolute folder paths can also be entered.
+On WSL, Windows folders must be accessible through the Linux filesystem, such as
+a mounted drive. On a native Mac, choose an accessible macOS directory.
+
+Project groups remain above ordinary conversations in the sidebar. Their plus
+button opens another conversation in that project. The existing plus button still
+creates an ordinary conversation using the configured default working directory.
+There is no fixed product limit on the number of projects. Opening or cancelling
+the creation form preserves the current conversation and sends no model request.
+
+The Runtime persists projects and each project's conversation binding. A
+conversation's selected directory is resolved for its own requests, including
+file output previews. Concurrent projects do not modify one another's directory
+or the global configuration. Existing conversations are not migrated automatically.
+Project deletion, renaming, and moving existing conversations are outside this
+initial feature.
+
+## Permission modes
+
+- **Ask** requests approval before each sensitive action, including EXEC and SYSTEM, using the existing tool-approval flow.
+- **Full** keeps ordinary tool behavior and also requests approval before each sensitive action. The approval card recommends FULL+ for future actions without those prompts.
+- **FULL+** authorizes task-relevant system actions without additional ABot action
+  confirmations or another enablement switch. This includes application discovery
+  and launching, general commands, service and process management, installation,
+  configuration changes, and other operations the target OS supports.
+
+The selector remembers the user's last explicit choice in this browser. New
+conversations, including project conversations, start with that saved choice.
+Existing conversations retain their own mode; opening one does not change the
+last-choice preference. Legacy conversations without a saved mode remain Full,
+and missing or unknown preferences never become FULL+. Each submitted or queued
+request captures its own mode; a later selection does not change it.
+A client connected to a server without advertised FULL+ support rejects the
+unsupported request instead of silently downgrading it.
+
+System capabilities are bundled and enabled by default, using the normal
+tool/adapter execution path and the same plugin selection rules as other tools.
+A disabled plugin or capability is absent from every request mode, including
+FULL+: permission never restores an unavailable tool. Existing explicit
+allow/deny selections are respected. Plugin changes use the existing Runtime
+restart requirement; FULL+ needs no additional enablement step under the default
+selection.
+Enabled sensitive capabilities, including every EXEC and SYSTEM operation, are available in all three modes. Their declared
+`approval="always"` policy uses the existing runtime approval boundary: Ask and
+Full wait for approval of the exact prepared action; FULL+ executes without
+that prompt. The card shows recorded target, command, working directory and
+elevation details. Approving once neither changes the selected mode nor approves
+later actions. Rejection, cancellation or an unavailable approval controller
+prevents dispatch. A model instruction, project file or tool result cannot select
+the request's mode. Direct tool implementations and low-level registry APIs are
+trusted host integration APIs; client requests use the normal invocation boundary.
+
+## Trusted shell execution
+
+The EXEC plugin declares sensitivity through the same `approval="always"`
+operation policy as SYSTEM. This covers execute, wait and cancel, without a
+tool-name branch in core orchestration. An approval applies to that exact action;
+it does not authorize later commands, polling or cancellation actions.
+
+After the required approval, EXEC passes the command to the native shell. It
+does not scan its text for paths, shell grammar, program operands or sensitive
+effects, and it does not block command names. The explicit working directory
+must exist and be accessible to the OS user; relative and workspace aliases keep
+their existing bases, and absolute host directories are accepted. Project and
+file-tool boundaries do not sandbox shell code. Existing file-tool path contracts
+remain unchanged. Execution retains non-interactive I/O, process ownership,
+cancellation, timeout, output and resource limits.
+
+## Operating-system targets
+
+Native Linux and macOS command execution, application discovery and launch use
+the target OS adapters. Windows execution from WSL requires working Windows
+interop and an actual Windows process; the Runtime reports an unavailable target
+when that transport is missing. It does not pretend that a Linux command ran on
+Windows. No product names receive special hardcoded handling.
+
+Target discovery distinguishes the Runtime OS from its host: a Linux Runtime
+inside WSL does not make a Windows desktop application a Linux application.
+Application discovery reports the sources it searched. A complete scan of those
+sources does not prove that an application is absent from the computer. When the
+catalog is insufficient, use the available target-native inspection commands to
+check installation and executable identity before choosing a launch method.
+
+FULL+ does not manufacture Administrator/root rights or bypass OS authorization.
+Required OS prompts, credentials and unavailable permissions are reported through
+the action result. A command receipt identifies its observed shell or helper;
+an application launch receipt records dispatch. Neither proves that the intended
+application started or that a visible window appeared. Verify the requested
+outcome with target-native evidence before reporting it as achieved. A matching
+filename, an exit code, or an already-running process alone does not prove a new
+launch. Command output may contain further evidence, but the adapter does not
+independently validate the effects of arbitrary commands.
+
+A project folder is the working context, not a ceiling on approved system operations.
+System commands can address resources outside it without changing `workspaceDir`
+to `/`. Existing file-tool path contracts remain in effect. This feature does not
+claim OS sandboxing, folder locking, or protection against another process running
+with the same user's OS authority. Approval controls whether a sensitive
+action may start; it does not lower that process's OS permissions.
+
+## Connecting a Docker Runtime to its computer
+
+A Docker Runtime can use applications and commands on its Windows or macOS host
+through the optional native host companion. The companion runs as the signed-in
+desktop user and connects outbound to the Runtime's published loopback Web UI
+address. It does not require a Docker socket, a privileged container, a Windows
+drive mount, or WSL interop inside the container. The container remains a separate
+Linux target; discovery identifies Docker separately from WSL.
+
+1. Publish the Docker Web UI port on `127.0.0.1` only, and keep the Runtime's data
+   directory persistent. In that deployment, set
+   `ABOT_WEB_TRUST_LOOPBACK_PUBLISH=1` in the container environment alongside the
+   loopback port mapping (for example, `-p 127.0.0.1:5184:5184
+   -e ABOT_WEB_TRUST_LOOPBACK_PUBLISH=1`). Open the Web UI using its configured
+   hostname and port.
+2. In the initial **Computer** step or **Config → Connected computer**, download
+   the setup script for the computer running Docker. Open the Windows script, or
+   extract the Mac ZIP and open its executable command file, on that computer.
+3. The script installs a private, checksum-verified Node runtime and the exact
+   companion build supplied by this ABot installation. It pairs automatically
+   using a single-use grant valid for 15 minutes, without a copied code or command.
+4. The companion saves a private credential and starts now and at future user
+   logins. The Web UI polls actual connection readiness. Downloading the script
+   alone is not a successful connection; wait for **Ready**.
+
+The publish-trust setting is off by default. Container detection cannot prove
+which host interfaces Docker publishes; a `Host: localhost` request is not proof
+of local access. Enable this setting only when every published Web UI port is
+restricted to host loopback. Do not enable it for LAN/public port mappings or an
+untrusted proxy. It permits the local browser and companion to use the published
+port when Docker changes the address/port seen inside the container; it does not
+add authentication or secure a remotely exposed Web UI. Native and WSL listeners
+retain their existing authority checks.
+
+The companion accepts only Runtime addresses resolving to this computer's
+loopback interface. Use the Web UI origin displayed in the connection panel,
+including its published port. This connection does not expose a remote command
+listener on the native host and does not support pairing to a different computer
+over the LAN or internet. Downloadable installers currently require a local HTTP
+Web UI origin. They do not disable TLS validation for unsupported HTTPS setups.
+
+One computer connection is shared by all Runtime environments belonging to the
+same ABot installation. The native user can pair with one installation at a time;
+disconnect before connecting another. Existing native macOS operation and Windows
+operation through functioning WSL interop do not require this companion. The
+setup screen checks those direct paths first. If WSL Windows execution is
+unavailable, it offers a Windows interop repair script instead. The script
+preserves unrelated `wsl.conf` settings, including `appendWindowsPath`, then
+automatically restarts only the selected distribution without a typed confirmation.
+Finish active work before opening the file: the restart interrupts all services
+in that distribution. If the configuration update fails, no restart occurs.
+The script and GUI verify actual Windows execution after the restart.
+
+Host requests use the existing system plugin and the same exact-action approval
+flow: Ask and Full request approval; FULL+ does not add a separate ABot prompt.
+Connecting a computer never enables a disabled plugin or tool. Requests identify
+available operating systems, not connection identifiers. Before each request's
+model calls, the system plugin captures native targets and the connected computer;
+existing native execution takes precedence, and the companion supplies an OS
+missing locally. Disconnected computer targets are absent from both the direct
+and delegated model catalogs. The plugin binds the destination internally before
+exact-action approval. Changing the pairing or reconnecting while approval is
+pending invalidates that action; it is never redirected or replayed on a new
+connection. Command working directories use the selected OS's path syntax.
+A container project path is not automatically translated to a Windows or Mac
+path. OS authorization still applies, and a launch receipt alone is not proof
+that a visible application window appeared.
+
+When confirmed Docker or WSL readiness requires setup, Chat shows a small,
+dismissible suggestion linking to **Config → Connected computer**. It does not
+appear for working native access, unknown status, or an already paired computer.
+It reuses the existing readiness state and refreshes on returning to Chat, without
+adding a polling loop. Dismissal lasts until the page is reloaded.
+
+Use **Disconnect computer** in the Web UI to revoke the Runtime's pairing and
+pending invitations. The connected companion removes its credential after
+revocation. Downloaded setup files contain an expiring invitation, so keep them
+private and delete them after use. Browser storage retains neither the invitation
+nor the persistent credential.
+
+Advanced installations using the ABot CLI can still use `abot host status`,
+`abot host disconnect` and `abot host uninstall`. The downloaded installer does
+not add a global `abot` command. Its private Node binary and immutable companion
+bundle live under `%LOCALAPPDATA%\ABot\HostCompanion` on Windows or
+`~/Library/Application Support/ABot/HostCompanion` on Mac; the same CLI operations
+can be invoked there as `<node> <companion-bundle> host uninstall`. This removes
+the local credential and login registration; use the Web UI to clear Runtime-side
+pairing as well. Reconnecting never silently replaces another installation's
+saved native connection.
+
+An offline computer is reported as unavailable. The companion reconnects while
+the saved pairing remains valid; it never automatically replays an interrupted
+system action. Cancellation or revocation attempts to stop an in-flight command,
+but effects already performed are not rolled back. If a connection is lost during
+execution, inspect the actual host state before trying the action again.
+
+## Validation status
+
+Implementation and validation progress are recorded in the task journal. Native
+Mac QA is performed separately with the owner; mocked platform tests are not a
+claim that an actual Mac was tested. No release or installation update is implied
+by changes in a development worktree.
+Native Windows/macOS companion installation, login startup and visible-application
+QA remain separate checks on the real desktop systems; Linux protocol and package
+tests do not establish those results.

package/docs/runtime-invariant-coverage.md

@@ -20,7 +20,7 @@ the default `supervisor-worker-v1` policy and the opt-in
 | Capability adapters report bounded operation outcomes and never decide semantic completion.                                                                                                                                                                                                                                                                                                                                                                                 | `src/runtime/adapters/registered-tool-worker-capabilities.ts`, `src/capabilities/tool-executor.ts`                                                                                                                                                     | `registered-tool-worker-capabilities.test.ts`, `tool-executor.test.ts`, `normal-invocation.test.ts`                                                                                                                                          |
 | Every capability settlement, whether produced by a delegated Worker or the direct root, atomically persists exactly one validated canonical `CapabilityAdapterResult`. Running executions cannot carry a result; invalid, non-JSON-safe, cyclic, or oversized evidence cannot settle and is never silently truncated.                                                                                                                                                       | `src/runtime/orchestration/capability-adapters/result.ts`, `src/runtime/orchestration/worker-capabilities/execution.ts`, `src/runtime/orchestration/role-calls/`                                                                                       | `registered-tool-worker-capabilities.test.ts`, `worker-capability-binding.test.ts`, `role-call-ledger.test.ts`                                                                                                                               |
 | The complete canonical result is projected only to the exact producing call and its later same-call payload author. Direct native tool linkage is not duplicated; cross-call provenance moves only through compact runtime-owned receipts and ledger-derived lineage on explicit dependency or supervision lanes. A Planner-item Worker receives no sibling execution summaries; callers, siblings and unrelated requests receive no implicit evidence.                     | `src/runtime/orchestration/worker-capabilities/settled-results.ts`, `src/runtime/context/request-tool-results.ts`, `src/runtime/orchestration/role-calls/`, `src/runtime/steps/worker-decision/`, `src/runtime/steps/execution-agent/state-context.ts` | `planner-worker-tool-result-scope.test.ts`, `role-call-dependency-work-receipt-pr1.test.ts`, `role-call-work-receipt-continuation-pr1.test.ts`, `worker-decision.test.ts`, `execution-agent-context.test.ts`                                 |
-| Delegated Planner client events project committed canonical plan state and never write progress. Planner Graph advisories do not create canonical plan items.                                                                                                                                                                                                                                                                                                               | `src/runtime/request/role-call-planner-events.ts`, `src/runtime/request/planner-plan-events.ts`, `src/runtime/steps/planner-graph/`                                                                                                                    | `role-call-planner-events.test.ts`, `execution-agent-advisory-executors.test.ts`                                                                                                                                                             |
+| Plan client events project committed state and never write progress. Planner Graph advice stays passive until the Execution Agent explicitly adopts it and reports item statuses; delegated Worker-bound plans remain unchanged.                                                                                                                                                                                                                                            | `src/runtime/request/role-call-planner-events.ts`, `src/runtime/request/planner-plan-events.ts`, `src/runtime/steps/planner-graph/`                                                                                                                    | `role-call-planner-events.test.ts`, `model-work-plan-domain.test.ts`, `model-work-plan-events.test.ts`, `model-work-plan-runner.test.ts`                                                                                                     |
 | Final response persistence and terminal request completion remain one shared request-finalizer boundary for both policies.                                                                                                                                                                                                                                                                                                                                                  | `src/runtime/lifecycle/request-finalizer.ts`                                                                                                                                                                                                           | `request-finalization.test.ts`, `execution-agent-request-runner.test.ts`                                                                                                                                                                     |
 
 ## Client Compatibility
@@ -28,8 +28,11 @@ the default `supervisor-worker-v1` policy and the opt-in
 Delegated Planner events retain the existing `planner.plan.*` names and
 `stage=development_plan` payload field. This is a client presentation contract,
 not evidence of a separate request path or semantic routing state. A
-`planner.graph` advisory is only a returned role result and does not create
-those plan events.
+`planner.graph` advisory alone is only a returned role result. An Execution
+Agent's explicit adoption and progress declarations use the same events after
+canonical ledger commit, without additional model turns or automatic item
+completion. They do not change delegated Worker-bound plan semantics or act
+as completion evidence.
 
 ## Regression Rule