feat: set up on first launch and start eligible gateways

AGENTS.md

@@ -7,7 +7,7 @@ The task defines scope and authorization; its chosen workflow owns execution, re
 - **One owner per responsibility.** An owner makes a decision or changes authoritative state. Callers consume its operations and recorded facts; adapters translate contracts, and caches or projections derive from the owner with an explicit invalidation lifecycle.
 - **Thin Windows host, upstream OpenClaw.** This repository packages and launches the pinned upstream application; it does not reimplement OpenClaw commands, parse `openclaw` arguments, copy the application payload, or invent a second configuration owner.
 - **One release trust chain.** Upstream revision, Node.js version and archive, MXC runtime lock, application inventory, package identity, payload metadata, signing policy, and x64/ARM64 outputs are coordinated inputs. Change every producer, validator, consumer, test, and document together.
-- **Explicit isolation lifecycle.** `clawctl setup` provisions and records the isolated session; `openclaw` starts only that recorded session. Do not add implicit provisioning or direct execution outside the session.
+- **Explicit isolation lifecycle.** `clawctl setup` provisions and records the isolated session. `openclaw` provisions only when the setup marker is absent, then starts that recorded session; every unreadable, incomplete, foreign, newer-schema, preparing, tearing-down, or otherwise degraded state remains an explicit `clawctl setup` or `clawctl teardown` recovery path. Do not add other implicit provisioning or direct execution outside the session.
 
 ## Working agreement
 

README.md

@@ -32,10 +32,11 @@ packages.
 
 - Windows 11 on a build that supports isolated agent sessions, on x64 or ARM64.
   OpenClaw always runs inside an isolated session, so a machine that cannot host
-  one is not supported: `clawctl setup` and `openclaw` both fail with a message
-  naming this requirement and the diagnostic log path. Install the latest
-  Windows updates (Settings > Windows Update), or install a newer Windows
-  version, and run `clawctl setup` again.
+  one is not supported: both `clawctl setup` and `openclaw` fail with a message
+  naming this requirement and the diagnostic log path. `openclaw` first
+  attempts automatic setup. Install the latest Windows updates (Settings >
+  Windows Update), or install a newer Windows version, and run `clawctl setup`
+  again.
 - Developer Mode is required only for the local loose-layout development loop,
   not for the signed MSIX.
 
@@ -53,13 +54,17 @@ own package-management commands. Every argument, including an empty argument
 list, is forwarded unchanged to `node openclaw.mjs`, and the launcher returns
 the exact child exit code.
 
-`openclaw` runs only inside the isolated agent session recorded by
-`clawctl setup`. It does not run OpenClaw on the host, and it fails rather than
-falling back when the recorded session is missing, owned by another
-installation, or unavailable.
+`openclaw` runs only inside an isolated agent session. When the setup marker is
+absent, it provisions the installation before forwarding its arguments, so a
+clean machine can start with `openclaw`, including `openclaw --help` and
+`openclaw --version`. It does not run OpenClaw on the host. Unreadable,
+incomplete, foreign, newer-schema, preparing, or tearing-down setup markers,
+session mismatches, and stale agent Node.js runtimes remain explicit recovery
+states with their `clawctl setup` or `clawctl teardown` guidance; automatic
+setup never repairs them.
 
 Before launching, the host resolves the bundled Node.js executable previously
-prepared by `clawctl setup` and checks its PE product version and executable
+prepared during setup and checks its PE product version and executable
 architecture against the packaged archive without a separate Node.js process.
 The runtime directory is prepended
 to the child's `PATH` so Node.js, npm, and npx subprocesses use the bundled
@@ -88,18 +93,33 @@ the read-only application directory the workspace.
 
 After each successful interactive `openclaw` invocation, the launcher performs
 a file-only readiness check inside the isolated session. If the default
-`.openclaw\openclaw.json` has `gateway.mode` set to `local` but the managed
-gateway has never started or has stopped, it suggests
-`clawctl gateway-service start` on standard error. It does not suggest a second
-start when gateway status is starting, unhealthy, or unknown. The check stops
-for the current Windows logon after that start command is invoked or a running
-gateway is observed; a new Windows logon enables it again. On an interactive
-terminal the hint uses the crab identity and the same warning/accent palette as
-`clawctl`; redirected and explicitly color-disabled output remains plain.
+`.openclaw\openclaw.json` has `gateway.mode` set to `local` and the managed
+gateway is `NotStarted` or `Stopped`, it starts the gateway when readiness is
+`startup eligible`, narrating progress on standard error. It does nothing for
+a non-zero OpenClaw exit code, redirected output, non-eligible readiness, or a
+`Starting`, `Unhealthy`, or `Unknown` gateway. An observed `Running` gateway is
+acknowledged. A failed or unverified start writes a standard-error warning and
+a retry command, `clawctl gateway-service start`, without changing the
+OpenClaw exit code; the next eligible run retries. A successful start is
+acknowledged for the current Windows logon. See [environment
+variables](#environment-variables) to restore the prior start hint.
+
+### Environment variables
+
+These host-side variables are not passed to the OpenClaw child. Automatic
+behavior is enabled by default. Set either variable to `0`, `false`, `no`, or
+`off` (case-insensitive and with surrounding whitespace ignored) to suppress
+its automatic behavior; any other value, including an unset variable, leaves
+it enabled.
+
+| Variable | Suppressed behavior |
+| --- | --- |
+| `CLAWCTL_AUTO_SETUP` | Restores the previous clean-machine failure: `openclaw` reports that it has not been set up and directs you to `clawctl setup`; it provisions, records, and registers nothing. |
+| `CLAWCTL_AUTO_GATEWAY_START` | Restores the previous `clawctl gateway-service start` hint instead of automatically starting an eligible gateway. |
 
 ### `clawctl`
 
-`clawctl` owns setup and the isolated-session operations:
+`clawctl` owns explicit setup, recovery, and the isolated-session operations:
 
 | Command | Behavior |
 |---|---|
@@ -260,10 +280,11 @@ an upgrade once nothing is still running from it; a launch holds its root for
 its whole lifetime, and a root that is still held is left whole for a later
 setup.
 
-Run setup before using `openclaw`, `clawctl pwsh`, or gateway-service start.
-There is no session-free mode: `openclaw` runs inside the session recorded by
-setup, and both entry points fail with the same message on a machine that
-cannot host one. See
+Run `clawctl setup` before using `clawctl pwsh` or gateway-service start.
+`openclaw` provisions a clean installation automatically, but there is no
+session-free mode: it runs only inside the recorded session and leaves degraded
+setup state to explicit recovery. Both setup paths fail with the same message
+on a machine that cannot host a session. See
 [MXC compatibility evidence](docs/mxc-compatibility-evidence.md) for the
 session model, gateway health criteria, and diagnostics limits.
 
@@ -272,16 +293,19 @@ The launcher places Node.js in a Windows job configured with
 runs; if the launcher exits or is terminated, Windows terminates Node.js and
 its child processes when the job handle closes.
 
-Prepare the bundled runtime once, then use `openclaw`:
+On a clean installation, start directly with `openclaw`:
 
 ```powershell
-clawctl setup
 openclaw
 ```
 
+Run `clawctl setup` first when you want the explicit setup, recovery, or
+`--fresh` path.
+
 When an MSIX update changes the bundled Node.js version, run `clawctl setup`
-again before launching OpenClaw. Previously extracted versions are left in
-place so an update does not remove a running process's runtime.
+before launching OpenClaw. Automatic setup does not repair a stale agent Node.js
+runtime after an update. Previously extracted versions are left in place so an
+update does not remove a running process's runtime.
 
 ## Selecting the OpenClaw revision
 

docs/architecture.md

@@ -62,12 +62,17 @@ flowchart LR
 
 ## Setup creates an explicit, isolated execution boundary
 
-An ordinary `openclaw` invocation does not provision a session or install a
-runtime. It can use only the recorded, usable isolated session created by
-explicit setup. Failing instead of provisioning during an application launch
-keeps a foreground command from unexpectedly downloading, extracting, or
-creating an agent environment, and makes setup state observable and
-recoverable.
+`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`](../src/OpenClaw.Launcher/Session/SetupStateStore.cs)
 persists the setup phase and its durable outcome. [`SessionRuntime`](../src/OpenClaw.Launcher/Session/SessionRuntime.cs)
@@ -221,14 +226,16 @@ flowchart LR
 
 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.
-3. `openclaw` loads the recorded session and sends a JSON launch request to
-   the staged helper through the MXC adapter; it never provisions implicitly.
-4. The helper replays the argument vector inside the agent session with the
-   agent runtime first on that child process's path.
-5. If configured, `gateway-service` records its launch configuration and the
-   logon task restarts the gateway through the same session boundary.
+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
 

docs/clawctl-output-style.md

@@ -21,10 +21,17 @@ should describe that environment in terms an operator can act on, while
   presents onboarding as mandatory nor launches it automatically.
 - End neutral states with the command that moves the user forward, such as
   `Run: clawctl setup`.
-- When a gateway is not running, show the file-only agent config readiness
-  immediately after the gateway row. Suggest `clawctl gateway-service start`
-  only when readiness is `startup eligible`; absent, incomplete, unavailable,
-  and unknown config states need diagnosis or configuration instead.
+- When a successful interactive `openclaw` launch finds a `NotStarted` or
+  `Stopped` gateway with `startup eligible` readiness, narrate the managed
+  gateway start on standard error. Do nothing for non-zero child exits,
+  redirected output, non-eligible readiness, or `Starting`, `Unhealthy`, and
+  `Unknown` gateway states; acknowledge an observed running gateway.
+- A failed or unverified automatic gateway start must not change the OpenClaw
+  exit code. Write a warning to standard error, followed by
+  `clawctl gateway-service start` on its own line so width-constrained wrapping
+  cannot break the retry command. Leave the guidance unacknowledged so a later
+  eligible launch retries. `CLAWCTL_AUTO_GATEWAY_START=0` (or `false`, `no`,
+  or `off`) restores the start hint.
 - Keep a successful `clawctl pwsh` launch silent so the user reaches the shell
   prompt directly. Its help text explains which commands are available inside
   the session.

docs/local-development.md

@@ -49,7 +49,7 @@ Use options for a concrete reason:
 | `-PayloadRunId <id>` | You need a specific successful workflow payload instead of the latest one. Use the current branch's successful workflow run when that branch changes packaged application content. |
 | `-RefreshPayload` | A cached payload must be downloaded again; the previous payload remains available until the replacement registers successfully. |
 | `-Force` | You intentionally need to re-register although the recorded inputs have not changed. |
-| `-SkipSetup` | You only need the registration. Run `clawctl setup` before attempting to run OpenClaw, because the bundled Node.js runtime has not yet been extracted. |
+| `-SkipSetup` | You only need the registration and intentionally want to defer setup. If setup state is absent, the next `openclaw` invocation performs setup automatically unless `CLAWCTL_AUTO_SETUP` suppresses it; run `clawctl setup` when you want to provision or recover explicitly. |
 | `-ReplaceExistingInstall` | You explicitly accept removal of an installed MSIX or a registration owned by another checkout. This is destructive because app data cannot survive the loose/installed transition. |
 
 The command is idempotent, not timestamp-driven. `LocalPackage.psm1` records a

docs/mxc-compatibility-evidence.md

@@ -23,7 +23,7 @@ into that command line.
 
 ## Session ownership and routing
 
-`clawctl setup` is the required lifecycle entry point. It writes package-local
+`clawctl setup` is the explicit lifecycle entry point. It writes package-local
 setup state and records the session that this installation owns in
 `session.json`. Ownership is never inferred from a machine account or profile:
 unrelated agent accounts may exist, and teardown must remain safe and
@@ -41,10 +41,16 @@ the ordinary setup route. It refuses unpackaged execution, never follows
 reparse points, and stops without a wipe or replacement setup when teardown is
 incomplete. It does not onboard OpenClaw or start the gateway.
 
-`openclaw` always runs inside the isolated session recorded by `clawctl setup`.
-There is no environment variable, option, or automatic fallback that runs
-OpenClaw on the host. Before touching any recorded state, both `clawctl setup`
-and `openclaw` require that this machine can host a session: an MXC runtime
+`openclaw` always runs inside the isolated session recorded for this
+installation. When its setup marker is absent, it provisions that session
+before launching; the lifecycle lock double-checks the marker so concurrent
+first launches provision only once. It leaves unreadable, incomplete, foreign,
+newer-schema, preparing, and tearing-down markers, session mismatches, and
+stale agent Node.js runtimes for their explicit `clawctl setup` or
+`clawctl teardown` recovery paths. There is no environment variable, option,
+or automatic fallback that runs OpenClaw on the host. Before touching any
+recorded state, both `clawctl setup` and `openclaw` require that this machine
+can host a session: an MXC runtime
 that is unavailable, a backend that reports no isolation-session support, a
 host build measured as unsupported, or a missing package identity all fail with
 the same message, which names Windows Update or a newer Windows version as the
@@ -130,18 +136,19 @@ stable reason. A running gateway omits readiness and avoids the helper call.
 
 After an `openclaw` child exits, the launcher uses the helper's file-only
 readiness result before checking the managed gateway record and liveness. A
-successful interactive call gets a start suggestion only for `NotStarted` or
-`Stopped`; unsuccessful or redirected calls, and `Starting`, `Unhealthy`, or
-`Unknown` gateway states, remain silent. The advisory path cannot change the
-OpenClaw exit code.
-
-The suggestion remains eligible until a manual
-`clawctl gateway-service start` invocation or an observed `Running` state.
-Acknowledgement is package-local and keyed to the Windows token authentication
-ID, so it suppresses later checks only for the current Windows logon. The
-sign-in recovery command carries a hidden provenance marker and does not count
-as a manual acknowledgement; a later OpenClaw invocation that observes its
-running gateway does.
+successful interactive call starts the managed gateway only for `NotStarted` or
+`Stopped` with `startup eligible` readiness; unsuccessful or redirected calls,
+and `Starting`, `Unhealthy`, or `Unknown` gateway states, remain silent. An
+observed `Running` gateway is acknowledged. A failed or unverified start warns
+on standard error and prints `clawctl gateway-service start` on its own retry
+line; it does not change the OpenClaw exit code or acknowledge the guidance, so
+the next eligible launch retries.
+
+A successful automatic or manual start, or an observed running gateway,
+acknowledges the guidance for the current Windows logon. Acknowledgement is
+package-local and keyed to the Windows token authentication ID. Setting
+`CLAWCTL_AUTO_GATEWAY_START` to `0`, `false`, `no`, or `off` restores the
+previous start hint instead of automatically starting the gateway.
 
 Agent entrypoint startup captures and restores console state and initializes
 UTF-8 just as the control entrypoint does. Postflight rendering treats