Skip to content

Latest commit

 

History

History
764 lines (683 loc) · 50 KB

architecture.md

File metadata and controls

764 lines (683 loc) · 50 KB

Architecture

This is an explanation of how the Windows MSIX host is put together for contributors. It describes the boundaries that preserve a packaged, NativeAOT-hosted OpenClaw while running the application in an isolated agent session. It does not own the command catalog or the installed-data inventory: those remain in the README command model and installed-data.

The host is one binary with two entry points

The package contains one NativeAOT executable, openclaw.exe, but exposes it through two package application identities and aliases: openclaw for the OpenClaw CLI and clawctl for package lifecycle and diagnostics. The two identities are intentional, rather than two copies of a host:

  • Package.appxmanifest binds both application entries and aliases to the same executable.
  • HostEntrypoint.cs selects the control identity from the package-qualified application ID when available, or from the invoked alias otherwise.
  • HostStartup.cs supplies the production collaborators: selected entry point, diagnostic log, package base directory, process streams, and installation lifecycle.
  • Program.cs keeps the two surfaces separate after startup. The agent surface forwards OpenClaw arguments; the control surface owns the package commands.

A third package application, GatewayRecovery, is not a host entry point. It is the separate windowless sign-in helper that logon recovery starts, and it only runs the control surface's gateway-service start --recovery; see Gateway lifecycle.

This arrangement makes the user-facing distinction enforceable by package activation, while avoiding two launchers that could drift in AOT settings, diagnostics, or runtime composition. It also protects transparent forwarding: openclaw arguments are OpenClaw-owned and never become clawctl options.

Completion stays owned by the installed runtime

clawctl completion writes completion for both aliases to standard output. clawctl completion --install adds a marked loader to the invoking user's PowerShell profile. Each new shell resolves the installed clawctl application and sources its current completion output, so package updates do not require a profile rewrite. The profile update changes only the marked byte range and replaces the file atomically, so an existing profile's encoding, line endings, and unrelated content survive.

The payload build asks the pinned OpenClaw application to generate its PowerShell completion script, validates the result, and includes those immutable bytes in the application inventory and signed package. Installation copies that trusted package asset into host LocalState. Before clawctl pwsh opens an interactive shell, the launcher refreshes an installed cache from the current package, then projects it through a generation-checked SessionWorkspaceOperation, which rejects guest-controlled path redirection. The workspace copy is disposable and is removed rather than loaded when the authoritative host cache is absent. One-shot --command and --file execution does not project or load completion.

All three pwsh modes use the attached session-command path. The request keeps PowerShell's executable, argument vector, shared-workspace working directory, environment, and PATH prefix as data through the guest helper. Interactive mode supplies -NoExit plus prompt and completion preparation. Command mode supplies one explicit -Command string; it does not reconstruct that string from multiple caller arguments. File mode supplies -File, the agent-visible path, and each script argument separately. Relative paths therefore start in the shared workspace, while ~ and absolute paths belong to the agent identity. The host does not stage arbitrary script content.

flowchart LR
    openclaw["openclaw alias"] --> host["openclaw.exe NativeAOT host"]
    clawctl["clawctl alias"] --> host
    host --> dispatch{"Selected identity"}
    dispatch -->|agent| agent["Forward OpenClaw arguments"]
    dispatch -->|control| control["Run package commands"]
Loading

Setup creates an explicit, isolated execution boundary

clawctl setup creates and records the isolated session. An openclaw invocation whose setup marker is absent provisions that same boundary before forwarding its arguments, including for --help and --version. It never runs OpenClaw on the host.

Automatic setup is deliberately narrow. An unreadable, incomplete, foreign, newer-schema, preparing, or tearing-down marker, a session mismatch, and a stale agent Node.js runtime remain explicit recovery states with their existing clawctl setup or clawctl teardown guidance. Automatic setup does not repair degraded state. The lifecycle lock double-checks an absent marker so concurrent first launches provision once.

SetupStateStore persists the setup phase and its durable outcome. SessionRuntime composes the shared backend, state stores, helper, and lifecycle lock for both entry points. SessionCoordinator owns the recorded session lifecycle and protects it from concurrent lifecycle operations. SessionExecutor turns a validated request into work inside that owned session; setup calls its runtime installation path explicitly rather than leaving the first gateway or OpenClaw invocation to do it.

The separation is consequential: state says what this installation recorded, whereas inspection asks the isolated session what is actually running. A stale record is therefore not treated as proof that the session is healthy.

Setup starts a best-effort payload prewarm

The first Gateway start in a new isolated session can spend much of its time waiting for on-access antivirus scans of payload files that a later start does not repeat. MSIX runs no package code at install or update, so the earliest point this repository owns is a successful clawctl setup, explicit or automatic. After setup records its completion, PayloadPrewarm starts the package's own clawctl alias with the hidden payload-prewarm command as a detached, windowless, below-normal-priority process that does not inherit handles, then setup continues without waiting for it. Setup itself keeps its normal priority. Because a priority class alone does not lower file I/O, the worker then enters PROCESS_MODE_BACKGROUND_BEGIN, which Windows lets only the process itself set, to lower its CPU, I/O, and memory scheduling; if that fails, it records the error and reads nothing. Otherwise it reads each file named by payload\startup-files.json once.

The pass is a hint, not a dependency:

  • It never changes setup's result. Start and worker failures, a missing or invalid list, and each outcome are written only to the host diagnostic log.
  • It reads only package files, and only list entries that are plain relative paths under app\. It stops at the first exhausted budget: 8,000 files, 256 MiB, or five minutes, checked before each file and after each 64 KiB read. A blocked open or read cannot observe that deadline, so the worker also ends its own process 15 seconds after it, recording the stop in the diagnostic log when the log accepts the line within 5 seconds. Teardown signals a running worker to stop under the installation lifecycle lock. The worker validates completed setup and registers its cancellation event under that same lock before reading: teardown either sees the event or removes setup first, so a delayed worker refuses to read. A second worker for the same installation exits immediately.
  • Worker coordination uses the same cross-logon-session scope as installation lifecycle operations. Named objects include a hash of the per-user, per-package state root so a console/RDP transition can cancel the worker without colliding with another user's installation.
  • It adds no Defender exclusions and changes no Defender or system settings. CLAWCTL_PAYLOAD_PREWARM=0 skips it.

Build-MSIX.ps1 and the loose-layout owner LocalPackage.psm1 generate the list with Get-PayloadStartupFiles.ps1, which walks literal import, export ... from, import(), and require() specifiers from openclaw.mjs and from each dist\extensions\*\index entry, resolving packages through package.json exports or main. The build refuses a listed path outside the payload inventory, and Test-SigningInputs.ps1 repeats that check before signing. A static graph only approximates startup: CommonJS patterns, computed specifiers, conditional exports, and plugin discovery can be missed, and deferred imports can be included, so the list does not guarantee coverage of the files a start opens.

Benefit is unproven. The worker reads as the invoking user, whereas the Gateway reads the same package files later as the isolated agent identity; Microsoft documents Defender's scan cache but not whether a verdict produced for one process helps a later process under another identity. The Defender verdict cache is separate from the OS file cache; warming either does not imply the other, and signature updates can invalidate cached verdicts. A Gateway start that happens without setup, such as the sign-in start after a package update, is not preceded by a prewarm. A worker still running when an update arrives can hold package files until its deadline. Make no startup-time claim without a comparable packaged, isolated before-and-after measurement.

The guest helper carries data, not a user command line

MXC's current execution route accepts a command-line string and flattens it through cmd.exe. Passing the OpenClaw argument vector through that boundary would allow shell expansion and quoting changes. The OpenClaw.SessionHost helper is the guest-side adapter: it receives a request-file path, reads the actual request as JSON, and launches the requested process with the original argument vector.

OpenClaw.SessionProtocol defines the AOT-safe JSON contracts shared by host and helper. Each contract has a schema version and explicit JSON property names; the protocol validates the expected version and writes a correlated result file. When publication succeeds, helper failures are reported in that result so the host can distinguish an operation failure from a transport failure. A malformed helper invocation without a request path can only report usage on stderr and exit with the helper failure code.

The helper must be copied before it can run. SessionHelperStager stages the immutable packaged helper in the session's shared workspace because the isolated agent identity cannot execute a binary directly from another package identity's WindowsApps directory. The shared workspace is visible to both identities. This is a required execution bridge, not a caching or startup optimization; staging verifies the packaged source and reports a staging failure rather than silently substituting another executable. Gateway start (including logon recovery) refreshes this versioned helper under the installation lifecycle lock before inspecting a retained Gateway process. It reuses the configured session without rewriting setup, identity, or profile data. Status only requires an already staged helper and never stages one.

Runtime installation and log collection report a correlated failure result when the operation fails. If that failure result cannot be published, the helper reports the primary and publication errors together on stderr and retains failure exit code 64. Those messages keep file paths, are bounded in length, and have credential-shaped values redacted on a best-effort basis. This fallback requires helper entry; a successful MXC spawn alone does not prove that the staged helper loaded or ran.

When a plain helper exchange such as runtime installation, tool installation, config readiness, or collection leaves no result file, the host reports how the helper ended, followed by the guest's output. Exit code 64 means the helper failed and could not write its result, and 0 means it exited without one. Any other code means cmd.exe could not start the staged helper or the helper stopped before reporting, for example when cmd.exe prints Access is denied and exits 1.

Before starting an attached child, the helper initializes its own console's input and output to UTF-8. Host-side encoding does not set the isolated console's code page; without guest initialization, PowerShell can corrupt Unicode terminal and redirected text.

sequenceDiagram
    participant Host as Package host
    participant Shared as Shared workspace
    participant MXC as MXC adapter
    participant Helper as Session host
    participant Node as Agent Node.js

    Host->>Shared: Write versioned JSON request
    Host->>MXC: Execute helper with request path
    MXC->>Helper: Start staged session host
    Helper->>Shared: Read request
    Helper->>Node: Launch original argument vector
    Node-->>Helper: Return exit code
    Helper->>Shared: Write correlated result
    Host->>Shared: Read result
Loading

Packaging consumes the SDK API; MXC provides isolation

The boundary with MXC has two responsibilities that should not be conflated:

  • Directory.Packages.props selects the official Microsoft.Mxc.Sdk NuGet version. NuGet and the .NET build/publish pipeline acquire and copy its runtime assets; the SDK owns native library resolution. Packaging does not register a custom resolver, inspect a native file set, or maintain per-binary pins. Get-MxcSdkMetadata.ps1 copies the mandatory MIT copyright/permission notice and records descriptive package version and build architecture, not a native-binary inventory. MxcRuntimeLocator reads that optional metadata for diagnostics only. Availability is observed through SDK calls and their errors, never inferred from file presence.
  • MXC owns containment and its wire contract. MxcSdkSessionClient calls Microsoft.Mxc.Sdk.V1.MxcLifecycle in process and translates typed results/errors into the package-owned lifecycle boundary. There is no executor process or package-authored MXC JSON envelope.

Interactive foreground commands use the SDK's public PTY API, with the host bridging input/output, terminal size, and console restoration. Redirected or mixed streams use separate pipes; helper capture closes unused stdin and drains both output streams concurrently. The tagged IsolationSession SDK kill reaches only its foreground command processor, not the guest helper's tree.

This branch prototypes per-invocation cleanup with WindowsInvocationJob. The host creates a job and per-invocation lifecycle events. The helper's internal --request-in-job=<id> mode joins the job before starting any workload, then checks the event so a delayed, already-cancelled spawn cannot start late work. An outside-job helper coordinator uses its agent identity to pin member process handles. Its job access is limited to this unique invocation's query, admission-control, and termination operations. Console Ctrl+C and Ctrl+Break leave that coordinator alive to finish pinning and drain acknowledgement; its process-local handler is not inherited by the worker, which retains normal console interruption behavior. Cancellation and normal completion close process admission before that snapshot by lowering the active-process limit to one; existing members remain available to pin, but new child creation is refused. The host explicitly terminates only after pinning is acknowledged. The coordinator waits the pinned handles, including its worker helper, before acknowledging drain and exiting. Only then does the SDK adapter join output EOF and release invocation files. Detached gateway supervision is unchanged.

The earlier zero-member/completion-packet candidate failed strict process-handle exit proof. The coordinator replaces that discovery path rather than treating job accounting as completed process exit. A positive member PID from that post-admission snapshot is opened with the fixed query-limited/synchronization mask. Only ERROR_INVALID_PARAMETER (87) identifies an already-expired PID in this context, following the same .NET process-lifetime handling. Access denial, other native errors, invalid snapshot IDs, and valid handles that no longer belong to the exact job remain explicit failures. Every retained handle still requires a signaled wait; no exit-code or job-count shortcut replaces it. Failed drain closes supported SDK output readers before joining them; closing readers does not count as process exit. The agent receives no host-process access or duplication rights.

This is ordinary process-leak control, not an authorization boundary against hostile same-identity code. Explicit termination does not depend on the last job handle closing. Before publishing an invocation, the host establishes a named mutex owned by a dedicated thread for that invocation's lifetime. The coordinator watches it alongside stop, worker-exit, and termination signals. Kernel-confirmed abandonment identifies hard owner death; ordinary disposal releases it normally, after the host's drain attempt. If ownership ends before termination is confirmed, the coordinator closes admission, latches stop, pins members, and terminates and drains only that job itself. This also rejects a late worker after owner death. No timeout, process ID, or job-handle closure stands in for owner or process-exit confirmation. The coordinator reports ownership ending and confirmed orphan drain without logging command arguments. Kill-on-close remains a secondary fallback, not the owner-death mechanism. If owner-ended admission, snapshot, pinning, or drain fails, the coordinator still requests emergency termination and reports the failure. An unconfirmed drain with a native-root lease deliberately retains that waiter and lease until explicit clawctl teardown; termination success alone does not authorize native-root reclamation. Older helpers reject the new --coordinate-invocation=<id> mode without starting a workload. State-transfer workers (backup, restore, recovery) use the same lifetime through the paired --coordinate-state-transfer=<id> and --state-transfer-in-job=<id> modes, so Ctrl+C stops the exact worker tree before the exchange files are released; a cancelled restore whose prepare step already recorded its activation is rolled back automatically. The other helper modes (runtime/tool installation, inspection, collection, configuration checks) still run as plain executions. The JSON protocol version is unchanged; the branch-local modes and events require a matching host/helper. Local owner-death fixtures supplement the earlier cross-identity evidence; the current proof limits and unrun lanes are recorded in the operational evidence. Dispatched lifecycle calls are not abandoned, so a provision's identity can always be recorded.

The result is a narrow trust boundary: this repository decides exactly which runtime is packaged and verifies it, but does not reimplement MXC's process and session isolation semantics.

Node belongs to the agent account

The Node archive is package content, but SessionRuntimeInstaller runs inside the isolated agent and extracts Node into that account's profile, not the package host's LocalState. The two identities do not share readable per-account package state. Extraction by the account that will execute Node also gives that account ownership of the extracted files.

Runtime reuse checks executable PE headers before entering the Windows loader. A corrupt non-executable runtime is repaired from the selected package archive instead of reaching Process.Start, whose creation wait precedes the process exit timeout. This does not add a packaging-owned Node.js version policy.

The installer version-checks the extracted runtime and can prepend its runtime directory to the agent user's PATH. Launch requests also carry a process-specific path prefix, so Node is discoverable by the intended guest process without changing the host process's PATH or depending on an arbitrary machine-wide Node installation.

Gateway lifecycle is recorded, observed, and restarted at logon

The gateway is an optional background process inside the same recorded agent session. GatewayController coordinates its start, stop, and health inspection; it does not infer liveness from a persisted record. GatewayConfigurationStore persists launch choices because the later logon task has no interactive caller from which to recover them. SchTasksGatewayScheduler uses the inbox schtasks.exe and a task registered for the signed-in user's logon. XML readback uses the Task Scheduler API through inbox Windows PowerShell and explicit UTF-8 output, preserving Unicode profile paths that schtasks would convert lossily to the system code page. This keeps COM outside the NativeAOT launcher and avoids elevation that would make the task user-unmanageable. After registration, the persistence manager reads the task back before reporting recovery ready or removing a Startup-folder shortcut. Trigger or principal drift reports the expected and observed identities; an unreadable result remains unknown. The owning token SID and the interactive logon SID remain separate for account compatibility, rather than silently redirecting recovery to another user.

Both recovery lanes start the windowless sign-in helper, openclaw-gateway-recovery.exe, a Windows-subsystem NativeAOT executable that the package declares as its own GatewayRecovery application. It has no console, so nothing at sign-in opens a window, even when Windows Terminal is the default terminal. The logon task's only action is the helper's quoted package-qualified execution alias, %LOCALAPPDATA%\Microsoft\WindowsApps\<package family>\openclaw-gateway-recovery.exe, with no arguments. Windows recreates that alias on every package update, unlike the versioned install directory, so the registration survives updates. Setup reads the alias name from the installed manifest through PackageExecutionAlias, so a side-by-side development identity registers its own renamed alias. When Task Scheduler refuses the registration, setup instead writes a Startup-folder shortcut, OpenClaw Gateway <package family>.lnk, to the same alias through the shell's ShellLink object. Its description marks it as OpenClaw's; a same-named shortcut without that marker is reported, never replaced or removed. Setup writes only into an existing Startup folder: a folder created from inside the package would be redirected into the package's private AppData, which Explorer does not read at sign-in. Status and install report recovery as needing action when the helper alias is missing, rather than registering a lane that would fail silently.

The helper resolves this package's Control alias from the same manifest, starts clawctl gateway-service start --recovery with CreateNoWindow and the user profile as its working directory, waits, and returns that command's exit code, so the task's last-run result is the recovery result. It appends what happens before that command starts, including a missing alias, to the host diagnostic log, and it never shows UI. Interactive CLI commands keep their normal terminal output.

Earlier generations ran a generated launcher instead: a CMD file, then gateway-launcher.js through Windows Script Host, each calling a PowerShell activation script, with a Startup-folder .cmd or .wsf fallback. Those files carry a generator marker. Status reports a task that still runs them as not matching this installation, and reports a marked file that remains as needing action. An explicit clawctl setup without --fresh reuses the recorded session, keeps its data and gateway settings, replaces the logon action, and then removes only marked legacy files; teardown removes them too. If an existing task cannot be replaced, the new shortcut is written but the files that task still runs are retained, and setup reports that migration still requires action. Recovery no longer depends on Windows Script Host, so a host disabled by policy cannot block sign-in once the task has been migrated.

The real control command is gateway-service, not gateway. The configured port is distinct from the upstream default. The launcher does not force the default into the child command line, and status never uses it as a fallback address: only a configured or observed listener can be reported. This lets OpenClaw resolve its own configuration and prevents a packaging-side default from overriding upstream behavior or sending a user to a port that was never observed.

gateway-service restart performs the existing stop and start operations under one lifecycle lock. A missing or already-exited gateway makes the stop a no-op and the start continues. If the gateway cannot be confirmed stopped, the operation retains its ownership record and does not launch a replacement.

Start and restart wait up to 90 seconds for an owned listener. A verified live supervisor with no listener can then return successful acceptance with gateway.state: "starting"; this is not a running or credential-handoff claim. The record remains available for inspection and stop, and clients keep their own bounded readiness wait. Inspection failures, terminal supervisor failures, and listener conflicts remain unsuccessful starts.

Start and status share one classification of the inspected launch. Inspection failure takes precedence over supervisor exit, which takes precedence over a listener observation. A matching live process with no listener and no recorded observedPorts remains starting, without an age-based cutoff. Loss of recorded listeners and listener conflicts remain unhealthy; a missing or replaced process is stopped. Configuration eligibility is independent of these process and listener observations.

Status never writes the launch record. Consequently, readiness first observed after the start wait is not durably latched: a later observation with no listener can return to starting when the record has no observedPorts. This contract does not provide a monotonic first-readiness history. Stop/restart and session teardown remain explicit lifecycle operations.

Launch correlation is an additive v1 capability inside the existing integration envelope. The controller persists a fresh caller-selected (or generated) attempt ID in its existing launch intent before dispatch. The same ID names the supervisor exchange, and the supervisor writes its own ID, creation time, helper image, and request ID before entering application state. If the launch acknowledgement is lost, the session client resolves that receipt through the validated shared workspace and performs the usual guest identity inspection. Missing or mismatched evidence remains unknown; it never proves absence or permits replacement. No second launch registry or status-side repair is involved. The receipt's running state still means application process, not listener readiness.

For a Gateway-requested full-process restart, the same session supervisor keeps its identity, launch attempt, output log, state-access lease, and native-root lease across child generations. After the old child and its job descendants exit, it runs the bundled gateway restart-handoff consume command with --expected-pid <pid> --json under the agent identity, using the same Node.js runtime, preload, environment, and working directory. Upstream owns atomic consumption, expiry, and PID matching; packaging validates the versioned response and relaunches only an accepted external / full-process handoff. Missing or rejected handoffs, update-process handoffs, and ordinary crashes do not restart. An unavailable or unsupported consumer fails explicitly without a replacement. The named outer job remains open through handoff and successor launch, so explicit stop and teardown still terminate the whole owned tree. Each child generation has an inner job that must drain before the next begins. Only the outer job kills automatically on last-handle close: a stop retains that job before killing the supervisor, then pins and drains its members. Closing an inner handle must not kill them before that snapshot.

Start distinguishes creating an attempt from adopting an existing starting or running attempt. Adoption preserves the existing ID. Conditional stop compares the requested attempt under the same lifecycle lock used for start and restart, then verifies and stops only the recorded supervisor. A mismatch or unavailable identity refuses without clearing state or falling back to plain stop. Callers must choose a fresh ID for every new attempt and retain it across lost acknowledgements; a receipt encountered through adoption does not confer cleanup ownership. See the Companion contract for its JSON fields.

Process access denial is not evidence that a recorded PID belongs to another process. Inspection uses query rights instead of requesting a full-access handle. If Windows denies inspection or termination, the session helper reads the OS process creation-time snapshot without opening the target. Only an observed missing PID or creation-time mismatch permits stale-record recovery. A matching identity or unavailable snapshot remains unknown: its record stays intact and no replacement is launched. Stop still pins and verifies its handle before termination, and never kills a PID selected only by a snapshot.

Companion uses the package's isolated session

The Windows Companion app selects the current-user Gateway MSIX by its exact package registration and qualified clawctl.exe alias. It probes clawctl status --json for the versioned isolated-session integration contract. Operational exception responses retain this capability metadata with ok: false, the selected command, and the original error. Capability does not assert session readiness or authorize credential handoff: Companion can reach its existing explicit package setup step, whose successful ready-session response is still required. Status itself never provisions or repairs a session. After setup, clawctl companion prepare --port <port> --json instructs SessionCompanionConfig to read the agent's effective Gateway configuration through upstream-owned runtime code. The packaged plugin-sdk/health snapshot reader runs with observation and suspicious-config recovery disabled, using core-only validation to avoid plugin-state and migration reads. The public openclaw config get display command is redacted and is not a credential-delivery path. A successful existing configuration must have gateway.mode: "local" and a loopback bind when specified; otherwise Companion requires explicit recovery rather than starting a Gateway with an incompatible mode. A wholly absent or empty Gateway can be initialized; a partially configured Gateway without local mode requires explicit recovery. Implicit password authentication is incompatible even when a token is also present. When an effective local loopback token configuration already exists, prepare returns it without rewriting the configuration file. Otherwise the agent uses packaged upstream plugin-sdk/config-mutation to create missing values under the upstream mutation lock. The original config path, root hash, and effective Gateway must still match, including values read from $include files; a concurrent edit fails rather than being overwritten. Before pairing and publishing Companion's record, the package-qualified clawctl companion prepare --check --json returns the agent's effective port and token so Companion can compare them with its setup record. This check neither patches configuration, restores backups, nor records config-health observations. The response contains a credential and must be kept private. The host does not write a second profile, inherit the invoking user's profile overrides, or select device-installed Node.js. The agent rejects profile and Gateway overrides both before and after upstream environment loading, and requires the upstream-selected config path to match the agent's default profile. Incompatible configuration requires explicit recovery rather than overwriting credentials.

GatewayController starts, stops, and inspects the Gateway on Companion's behalf. When listener attribution is available, clawctl gateway-service status --json reports the recorded sandbox and agent SID alongside guest-observed listener process IDs, creation times, sequence numbers, and ports. Guest process-sequence snapshots bracket the listener and ancestry observations. Each listener and every ancestor used in attribution must have the same nonzero sequence in both snapshots; creation times come from that same tree observation. Those fields are evidence from the trusted package-qualified invocation, not a bearer credential or sufficient proof when copied out of context. Companion compares them with two fresh host-side listener and OS process-sequence snapshots before any credential handoff. The agent's process DACL denies cross-account process handles to Companion, so a host process-start-time or token-SID query cannot be the ownership check. Windows 11 builds with SystemBasicProcessInformation expose an OS-owned per-process sequence without opening that handle. Gateway health and lifecycle still use the isolated process-tree and observed listener checks when process sequences are unavailable; in that case the package omits gateway.ownership and Companion fails closed before sending credentials. Unknown, incomplete, or replaced listeners fail closed instead of accepting a reused PID.

Pairing uses package-qualified openclaw devices list --json and openclaw devices approve <request-id> --json in the isolated session. openclaw runs transparently as the agent user and reads that account's configuration; Companion does not write a host-profile config or pass a token through command-line arguments or environment overrides. Before each command, Companion verifies the live listener and checks that the agent's port and token still match its setup record. It matches the pending request to its own device ID and public key, then approves only that exact request.

State transfer preserves the current session identity

StateTransferCoordinator owns host-side backup, restore, recovery, and protected Doctor orchestration. It requires ready setup, starts only the recorded session, binds exchanges to its generation, and uses its staged helper and agent-owned Node.js runtime. The archive store publishes hash/length-checked files without overwriting an existing destination. Listing that store does not contact MXC. Archive files receive a protected DACL when their handle is created, before credential bytes are written; inherited readers of the archive folder do not gain access. The shared TrustedPath owner also creates the per-command exchange for the invoking user and recorded agent, excluding broad parent readers. Upstream scratch remains in that private exchange. Guest transaction and normalization roots are private to the agent, SYSTEM, and administrators. Exchange and scratch names retain full random identifiers but stay short so the bundled Windows SQLite helper has room for its nested snapshot paths. Generation checks remain bound to the workspace handles and request/result contract. Existing folder, profile, and archive permissions are not rewritten.

SessionStateTransfer owns guest preparation, activation, and rollback. StateArchiveApplication invokes immutable packaged OpenClaw for inventory, canonical SQLite snapshots, verification, and fresh-target extraction. It inspects configuration through the upstream SDK and relocates only declared filesystem fields and $include documents in staging, never arbitrary credential/history strings. Missing, external, relative, or environment-dependent required paths remain explicit automatic-recovery refusals. Windows/profile portability is not account or package migration.

Explicit clawctl gateway-service repair --yes uses that same lifecycle lock, backup pipeline, and recorded identity. It refuses pending activation, stops through the gateway owner, and publishes a verified archive before invoking the packaged Doctor. Doctor owns the schema/data mutations, with external service repair policy retained. It never automatically starts the gateway or runs in the update/logon path. Failure retains the archive and the stopped state; an unavailable backup prevents Doctor from running.

Restore verifies and prepares before asking the existing gateway owner to stop the managed gateway. It acquires exclusive state access, captures and retains verified current-state protection, and only then requests activation. Asset roots are collapsed to non-overlapping profile-relative mappings. A durable, source-generated journal outside .openclaw records the current profile identity, transaction, prepared-tree digest, asset identities, protection, and progress before same-volume moves. Activation rechecks the prepared contents before moving any original data. Rollback reconciles recorded identities with the moved objects, including interruption between a move and its next host response. It does not terminate an unrelated process or treat journal paths as unrestricted authority. Backend/setup identity is never replaced.

SessionStateAccess owns one required cross-process access gate. Intent blocks new attached launches, detached supervision, PowerShell, and configuration writers; existing readers must finish before maintenance can obtain exclusive access. A separate worker lease prevents rollback while an activation worker remains alive. Kernel-released leases provide liveness without trusting a reusable PID. The helpers own child process trees in kill-on-close jobs so a lease cannot end while their descendants keep writing; disposing such a job closes admission, pins every member by handle, terminates it, and waits on each pinned handle (not job accounting) before the lease is released. A member that outlives termination fails the operation; the state leases still unwind with that error, which is deliberate fail-closed behavior rather than an unkillable process blocking every later maintenance operation. The supervised gateway's job is published under a name bound to its supervisor, so a stop that kills the supervisor still waits out the whole gateway tree before it reports success. Before that kill, the --stop helper sends Ctrl+C to the gateway's own windowless console, which Node.js delivers as SIGINT and OpenClaw handles as a graceful stop that releases its agent database lease. The helper waits up to 15 seconds for the members of the tree to exit, then terminates whatever remains exactly as before. A gateway that is terminated instead leaves its lease for the next start to recover as a crash, which can keep that start starting well past the listener wait. Inspection and diagnostics remain available when activation is pending. Successful activation or explicit rollback clears intent; an unreadable journal fails closed. Finalized state remains finalized if deleting disposable transaction data or a private recovery snapshot fails: the result names the retained directory in a cleanup warning instead of falsely reporting interrupted activation. Retained archives are not part of that cleanup.

Recovery's host-side RecoverySource reads only an explicitly selected old profile. It pins source identities, refuses writable/locked files and reparse points, checks inventory stability, and carries required profile-contained dependencies into a shadow profile. The guest preserves WAL bytes in that shadow copy before invoking the upstream canonical producer. The verified recovery archive is retained first, then fed through ordinary restore. Neither recovery nor rollback recreates an old Windows account, changes ACLs, provisions a new session, or restarts the gateway.

Diagnostics and build inputs have different trust roles

HostDiagnosticLog writes host diagnostics beneath packaged LocalState when packaged, or the documented per-user fallback otherwise. A named mutex keyed by the log path keeps concurrent writers from interleaving records.

GatewayController records how long each gateway status inspection took and the state it observed. SessionExecutor records how long each non-attached session exchange, such as the Control UI handoff, took and its executor exit code. An inspection or exchange that throws instead, including on cancellation, is recorded with its duration, exception type, and any MXC error classification. Together they show where a slow command spent its time without a debugger. They never include captured output, exception messages, arguments, environment, URLs, or tokens.

Each host start records an Environment: entry from HostEnvironment: the Windows build and update revision, OS and process architecture, the package full name with the origin Windows recorded for the install (Developer Mode loose-layout registration, Store-signed, or developer-signed MSIX) and its install path, the compiled package and payload versions, the MXC SDK provenance and owned contract, the packaged Node.js version, and the .NET runtime. Reading these facts starts no process; the MXC backend probe is logged where support is checked instead. The facts are descriptive only and never authorize an operation.

Failure records are separate from those timing records. Users see an exception's message; the log records the whole failure through DiagnosticFailure: its type and message, any MXC code, backend code, and failing operation, the Windows error code behind I/O and native failures, and every inner cause. A message can repeat guest-reported detail, such as an agent-profile path, which is why each bundle warns to review it before sharing. The process's last-chance handler also records the stack trace. The one deliberate omission is a browser launch failure, whose message would repeat a Control UI URL that can carry the gateway credential.

DiagnosticsBundle collects troubleshooting material through the shared workspace while excluding credential stores, and writes the collecting host's environment into its manifest. It also reads every recent gateway launch's output log and supervisor status from that workspace. It keeps a bounded tail of each and refuses reparse points, because the guest can write there. HostPackageDiagnostics adds host/package-diagnostics.json independently of session reachability: collecting-process provenance and the manifest-qualified control alias, current-user Gateway/legacy/Companion registration metadata, and ordered clean-shell clawctl command resolution. It uses absolute inbox Windows PowerShell with no profiles, explicit inbox module imports, bounded streams, a 15-second deadline, and 32-entry inventory limits. It never invokes a discovered command or another status probe, which could start the session. Its declaration of the integration envelope shares ClawCtlJson's producer; it is not evidence that a different package returned a compatible response. Exit/parse/launch failures and unavailable sources remain explicit, with no raw subprocess output in the ZIP. Structured paths preserve drive/depth, standard directory labels, and public package/alias identities while replacing private components consistently. Companion's historical selection, response mismatch, and active distribution remain unknown to this collector.

DiagnosticsRedactor redacts credential-shaped JSON members, URL parameters, environment-style assignments, and authorization header credentials in the remaining text, the manifest, and the notes the command returns. That redaction is deliberately best-effort and does not make a bundle safe to share without review.

Diagnostics describe runtime evidence; they are not release verification. The build path independently creates an inventory of package inputs and hashes their content in Build-MSIX.ps1. That inventory, the pinned MXC archive checks, and packaging metadata form the release trust boundary: a successful process launch alone is not evidence that the intended payload was packaged.

flowchart LR
    runtime["Runtime execution"] --> diagnostics["Diagnostics and redacted bundle"]
    inputs["Pinned package inputs"] --> validation["Hash and architecture validation"]
    validation --> inventory["Package inventory and metadata"]
    diagnostics -.->|not release proof| inventory
Loading

End-to-end flow

  1. Windows activates an alias; the one NativeAOT host identifies the agent or control application identity.
  2. clawctl setup explicitly creates or repairs the isolated session, stages the helper, and installs the agent-owned Node runtime. When the setup marker is absent, openclaw performs that provisioning first.
  3. For every other marker state, openclaw preserves the explicit recovery result rather than repairing it automatically.
  4. openclaw loads the recorded session and sends a JSON launch request to the staged helper through the MXC adapter.
  5. The helper replays the argument vector inside the agent session with the agent runtime first on that child process's path. If eligible, a successful interactive launch starts the managed gateway through this same boundary.

Source map

Concept Authoritative tracked files
Package applications, aliases, and launcher dispatch Package.appxmanifest, HostEntrypoint.cs, HostStartup.cs, Program.cs
Setup state and session lifecycle SetupStateStore.cs, SessionRuntime.cs, SessionCoordinator.cs, SessionExecutor.cs
Guest protocol and helper staging OpenClaw.SessionHost/Program.cs, SessionLaunchProtocol.cs, SessionHelperStager.cs
MXC SDK API and redistribution notice Directory.Packages.props, Get-MxcSdkMetadata.ps1, MxcRuntimeLocator.cs, MxcSdkSessionClient.cs
State transfer and activation SessionStateTransferProtocol.cs, StateTransferCoordinator.cs, SessionStateTransfer.cs, SessionStateAccess.cs, StateActivationJournal.cs
Agent runtime installation SessionRuntimeInstaller.cs
Payload prewarm and startup file list PayloadPrewarm.cs, PayloadPrewarmNative.cs, Get-PayloadStartupFiles.ps1, Build-MSIX.ps1
Gateway lifecycle SchTasksGatewayScheduler.cs, GatewayController.cs, GatewayConfigurationStore.cs
Logon recovery and the sign-in helper GatewayPersistenceManager.cs, ShellStartupLinkStore.cs, PackageExecutionAlias.cs, GatewayRecoveryStart.cs
Diagnostics and payload integrity HostDiagnosticLog.cs, HostEnvironment.cs, DiagnosticFailure.cs, DiagnosticsBundle.cs, DiagnosticsRedactor.cs, Build-MSIX.ps1