• Release date: 2026-09-03
• Version transition: 0.3.0 → 0.3.1
• Release type: patch version jump
• Theme: reliable personal-agent bootstrap and discoverable ChatGPT onboarding

This patch completes the personal-account onboarding path introduced in v0.3.0. The first implementation correctly isolated users once provisioned, but two startup defects could prevent a new user from reaching that state: Neural Labs passed an option name that OpenClaw 2026.8.2 does not support, and the browser could connect to the Gateway before its newly created agent had been loaded. The resulting unknown agent id response also prevented Skills and Automations from reading their agent-scoped live status.

v0.3.1 makes provisioning an explicit prerequisite for the shared desktop Gateway connection, removes the last implicit main-agent fallback, and gives disconnected users a direct path to the Personalization account card.

The workspace account manager generated this OpenClaw configuration operation:

openclaw config set gateway.roles.definitions.<personal-role> <json> --json-strict

The pinned OpenClaw 2026.8.2 CLI exposes --strict-json; it does not recognize --json-strict. Agent creation could therefore succeed while matching Gateway role creation failed. Separately, successful CLI agent creation updates state before the running Gateway necessarily exposes that agent through its RPC surface. The desktop previously trusted the ID already present in /api/session and opened its WebSocket immediately, which made that reload interval visible as unknown agent id.

After authenticating the Neural Labs browser session, the desktop requests /api/account/openai. That endpoint provisions the user's agent and personal Gateway role, refreshes safe account status, and returns the same non-secret agent ID already bound to the session. The desktop verifies that both IDs match before assigning the client agent and starting the WebSocket.

The Alshival Gateway client now records an early start request without opening a socket until a valid nl-* agent ID has been supplied. Alshival and the combined Skills & Automations app can therefore mount in any saved-window order without racing onto an unknown agent. There is no default main agent. Agent-scoped methods reject calls made before bootstrap rather than silently targeting the system automation identity.

Bootstrap retries every four seconds after a transient failure and is also retried when the page returns online or becomes visible. The desktop and Terminal remain usable while this private AI connection initializes.

Provisioning uses OpenClaw's supported --strict-json parser for the exact role definition. Before the account manager marks the agent provisioned, it polls the authenticated loopback Gateway agents.list RPC until the expected agent appears. A bounded failure returns a clear personal-agent availability error instead of allowing a partially initialized browser connection.

Starting ChatGPT device-code authentication no longer requires a browser Gateway profile to pre-exist. Neural Labs first provisions and refreshes the personal agent. If an OAuth profile is already authenticated, it restores the personal role immediately. Otherwise, it starts the device-code process without premature role assignment; the existing successful-login refresh assigns the role after authentication. This removes the circular “open Alshival before you can connect Alshival” requirement.

When safe personal-account status reports that ChatGPT is disconnected or paused, the desktop shows an actionable toast: Connect your ChatGPT account to start using Alshival. The notification remains visible longer than ordinary transient status messages. Selecting it creates, restores, or focuses Settings and switches the target window to Personalization, even for an administrator whose persisted Settings section was elsewhere. Connected users do not see the prompt.

The combined reusable-workflow window now displays Skills & Automations in its title bar. The separate Skills and Automations dock shortcuts remain so each can open the appropriate section of that one live window.

• The personal agent ID is a stable, non-secret derivative already present in the authenticated session response. The desktop rejects an account response whose ID does not match it.
• OAuth credentials remain in OpenClaw's per-agent persistent state. Neither the bootstrap response nor the toast carries a token or device code.
• The Gateway readiness poll uses the existing runtime-generated password on the existing loopback-only administrative connection. It adds no route, listener, port, container capability, or host mutation.
• The default Gateway role still has no agent access. Each personal role still allows exactly one agent, limits other-session access to none, and excludes administrator scope.
• The workspace service account remains reserved for automations, heartbeats, and other background work. Interactive Alshival continues to fail closed.
• No tenant credential, provider key, certificate, SSH material, VPN state, generated tenant state, personal address, or deployment IP is included in this release.

This patch changes ordering and failure handling within the trust boundary defined by ADR 0013; it does not widen that boundary, so no new ADR is required.

1. Create and verify the normal Neural Labs backup.
2. Pull the v0.3.1 source and review deployment-local image pins in .env.
3. Rebuild and recreate the workspace service. No database migration is needed.
4. Wait for the workspace health check and run bin/neural-labs doctor.
5. Load /workspace as a disconnected user and confirm the ChatGPT toast opens Settings → Personalization.
6. Select Connect ChatGPT account, complete the OpenAI device-code flow, and confirm Alshival and Skills & Automations connect without unknown agent id.
7. Confirm the workspace-level OpenAI account still reports ready for background automations.

Workspace files, OpenClaw state, personal OAuth state, skill drafts, and code-server data stay in persistent volumes. Live terminal and agent processes end when the workspace container is recreated.

This release has no schema or destructive state migration. Roll back by using the prior reviewed source/image and recreating the workspace service. Personal agents and role definitions created by v0.3.1 are compatible with v0.3.0 and can remain in the persistent OpenClaw volume. Do not remove user agents, OAuth files, or volumes as part of an application rollback.

Rolling back also restores the old CLI option and startup race, so use rollback only as an emergency service measure and retain logs for diagnosis.

The release gate remains make validate. Focused regression coverage includes:

• the exact supported --strict-json option and absence of --json-strict;
• live Gateway acknowledgement of a provisioned personal agent;
• first-time device-code login when no Gateway browser profile exists;
• no role assignment before an unauthenticated device-code flow;
• desktop account bootstrap before Gateway start and exact agent-ID matching;
• disconnected-or-paused ChatGPT onboarding toast behavior;
• action routing into an administrator's Personalization section;
• the Skills & Automations window title; and
• all existing desktop, account, HTTP, isolation, builder, Alshival, Terminal, Files, VS Code, passkey, MCP, and control-plane regressions.

The final validation, live rebuild, health results, commit, tag, and push are recorded in Git history and the release handoff.