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 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.appxmanifestbinds both application entries and aliases to the same executable.HostEntrypoint.csselects the control identity from the package-qualified application ID when available, or from the invoked alias otherwise.HostStartup.cssupplies the production collaborators: selected entry point, diagnostic log, package base directory, process streams, and installation lifecycle.Program.cskeeps 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.
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"]
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.
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=0skips 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.
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
The boundary with MXC has two responsibilities that should not be conflated:
Directory.Packages.propsselects the officialMicrosoft.Mxc.SdkNuGet 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.ps1copies the mandatory MIT copyright/permission notice and records descriptive package version and build architecture, not a native-binary inventory.MxcRuntimeLocatorreads 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.
MxcSdkSessionClientcallsMicrosoft.Mxc.Sdk.V1.MxcLifecyclein 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.
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.
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.
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.
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.
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
- Windows activates an alias; the one NativeAOT host identifies the agent or control application identity.
clawctl setupexplicitly creates or repairs the isolated session, stages the helper, and installs the agent-owned Node runtime. When the setup marker is absent,openclawperforms that provisioning first.- For every other marker state,
openclawpreserves the explicit recovery result rather than repairing it automatically. openclawloads the recorded session and sends a JSON launch request to the staged helper through the MXC adapter.- 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.