@byokit/openclaw 0.16.1 → 0.16.2

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.16.2 (2026-10-18)
+
+- Dependency update: pins @byokit/accounts 0.27.1.
+- FIX: (from @byokit/accounts 0.27.1) classifyFailure returns needs_workspace for an OpenCode Go key that acts for several workspaces, so the app can ask the person to pick one instead of showing a run error.
+
+- FIX: A first start that misses its gateway handshake recovers by itself. A handshake timeout, or an engine exit before hello, now moves the state to `restarting` with `retryAt` on the same backoff as a reconnect after `ready` (1 s, 2 s, 4 s, capped at 30 s), then starts the engine again; the fifth missed attempt moves to `failed` with why `handshake`, as before. Each `start()` call has its own five attempts and resolves once the kit is ready and rejects once it has given up or is stopped, `stop()` cancels its pending retry, and the new `KitOptions.handshakeMs` (default 90 000) sets the hello deadline per attempt.
+
 ## 0.16.1 (2026-10-17)
 
 - Dependency update: pins @byokit/accounts 0.27.0.

package/README.md

@@ -387,7 +387,7 @@ streams, [`examples/openclaw-kit`](../../examples/openclaw-kit) for a whole app,
 
 Subscription sign-ins are offered by default. API-billed routes remain in `kit.routes()` with `offer: false`;
 apps can offer them when the app or person opts in, labelled API key (billed per use). Each `Route` carries `billing` (`subscription`, `api` or
-`local`) so the app can label what is billed. Proxy routes, compatibility aliases, local runtimes stay off. Native Claude Code sign-in is offered by default. A plan key (OpenCode Go: `kit.addAccount(member, { authChoice: 'opencode-go' }, on)`) asks for `Plan key`; `paste` it and the engine live-tests it before `done`. A paired device starts the same sign-in with either `via` and pastes the key over the sealed link, which keeps it on the host. A run reaches the pinned engine's static Go models (default `opencode-go/deepseek-v4-pro`); the kit keeps OpenCode Go's `x-opencode-session` header on every request, the setup probe included. A live-only Go model such as Muse needs no app config: the kit registers the plan's live catalog with each model's API, so `run({ model: 'opencode-go/muse-spark-1.3-contributor' })` runs on the account (or with `auth: 'apiKey'` on a Go key); an app that sets `config.models.providers['opencode-go'].models` keeps its own list. A choice the pinned Gateway cannot set up has readiness `no_upstream_flow` and is never offered. Pass the accounts the app offers in `KitOptions.offered` (the provider, auth choice or alias each route carries, e.g. `'openrouter'`); the kit allow-lists the plugin of every route those name, so an opted-in sign-in is not blocked. An app can still name a plugin directly in `config.plugins.allow`, and pass the route's `choice` explicitly to `kit.signIn()`.
+`local`) so the app can label what is billed. Proxy routes, compatibility aliases, local runtimes stay off. Native Claude Code sign-in is offered by default. The engine picks the installed Claude login when it starts; a person who signs in to Claude on that machine after the engine started restarts the engine to use it. A plan key (OpenCode Go: `kit.addAccount(member, { authChoice: 'opencode-go' }, on)`) asks for `Plan key`; `paste` it and the engine live-tests it before `done`. A paired device starts the same sign-in with either `via` and pastes the key over the sealed link, which keeps it on the host. A run reaches the pinned engine's static Go models (default `opencode-go/deepseek-v4-pro`); the kit keeps OpenCode Go's `x-opencode-session` header on every request, the setup probe included. A live-only Go model such as Muse needs no app config: the kit registers the plan's live catalog with each model's API, so `run({ model: 'opencode-go/muse-spark-1.3-contributor' })` runs on the account (or with `auth: 'apiKey'` on a Go key); an app that sets `config.models.providers['opencode-go'].models` keeps its own list. A choice the pinned Gateway cannot set up has readiness `no_upstream_flow` and is never offered. Pass the accounts the app offers in `KitOptions.offered` (the provider, auth choice or alias each route carries, e.g. `'openrouter'`); the kit allow-lists the plugin of every route those name, so an opted-in sign-in is not blocked. An app can still name a plugin directly in `config.plugins.allow`, and pass the route's `choice` explicitly to `kit.signIn()`.
 Offered provider plugins are allowed by default alongside the app's plugin ids. A route whose provider plugin ships outside the engine (Z.AI's GLM Coding Plan, for one) has readiness `needs_plugin` until the app calls `await kit.installPlugin(route.needs.plugin)`: it installs that plugin into the kit's own engine at exactly the engine's version and pinned npm integrity, keeps it allowed across restarts, and rejects `PluginInstallError` (`code` `version` or `integrity`) with nothing installed on a mismatch. Discovery never installs.
 
 ## API at a glance
@@ -518,7 +518,8 @@ itself — no manual file surgery:
   `cleanup`/`restoring` transitions are completed from the authenticated snapshot; empty live trees are treated as
 debris.
 - An engine exit code 78 means the engine asked for repair: the kit's own repair path runs
-  `doctor --fix --yes` with `doctorContext()`'s exact env.
+  `doctor --fix --yes` with `doctorContext()`'s exact env. Call `doctorContext()` after `prepare()` or `start()`: its
+  `CLAUDE_CONFIG_DIR` reflects the Claude login the engine chose there, and before that it reflects only the installed login.
 
 What a killed home leaves behind: live plaintext `state/` and `home/` (never resealed), `auth-store.lock/` with a
 dead owner pid, `gateway.pid` and `gateway.identity` (a still-live orphan Gateway is the dangerous case),
@@ -600,6 +601,17 @@ const oc = openclawDevice(link);
 for await (const e of oc.run('Say hello.')) console.log(e);
 ```
 
+## First start that misses its handshake
+
+`start()` waits up to `KitOptions.handshakeMs` (default 90 000) for the gateway's hello on each attempt. A timeout, or an
+engine exit before hello (except an over-cap auth-store seal refusal, which fails at once with `auth-store-seal-size`), moves the state to `restarting` with `retryAt` on the same backoff as a reconnect after
+`ready` (1 s, 2 s, 4 s, capped at 30 s), then starts the engine again. A transport that closes before hello keeps
+retrying inside the transport, so it ends as the timeout; a refused connect (a bad token) fails at once. The fifth
+missed attempt moves the state to `{ phase: 'failed', why: 'handshake' }` and `start()` rejects. Each `start()` call
+has its own five attempts, and `stop()` cancels its pending retry and makes that `start()` reject. Show `stateWords(kit.state)` while the state is
+`restarting`; the tests pass a short `handshakeMs`. A timeout that fires while the engine is repairing (exit 78) waits for the
+repair to end before the engine is stopped and retried.
+
 ## Isolation and billing
 
 The kit writes only under the `stateDir` the app passes, resolved to one absolute path through no symlink (so a
@@ -713,7 +725,8 @@ compromised engine/plugin, memory dump, or stolen host key can read credentials.
 against replacement with an older authentic snapshot. Gateway/device keys, inline config secrets, logs, engine
 install/cache files and app workspaces are outside this adapter's sealing scope; protect them separately.
 `doctorContext()` is an advanced escape hatch: launching an external doctor bypasses this lifecycle; use the
-kit's migration method for sealed stores.
+kit's migration method for sealed stores. Call it after `prepare()` or `start()`, because its Claude login folder
+is the one chosen there; before that it reflects only the installed login.
 
 See [SECURITY.md](SECURITY.md) for the credential and approval threat model, private-directory requirements,
 retained-login cleanup and sealed approval limits.
@@ -735,4 +748,4 @@ frozen (docs/runtime-kits.md §5).
 
 Apache-2.0. See [LICENSE](LICENSE); the bundled engine's MIT text is [engine/OPENCLAW-LICENSE](engine/OPENCLAW-LICENSE).
 
-Claude: `anthropic-cli` uses your own unmodified Claude Code login on this machine (provider `claude-cli`, plugin `anthropic`; subscription billing; `kit.signedIn(member, 'claude-cli')` is true once Claude Code is signed in, and `'anthropic'` stays the API-billed provider a Claude Code login never satisfies. Before 0.7.0 this route reported provider `anthropic`; that value is deprecated, kept as `deprecatedProvider` until 0.9.0), with login kept in Claude Code under the kit’s isolated `HOME=<stateDir>/openclaw/home` and `CLAUDE_CONFIG_DIR=<stateDir>/openclaw/home/.claude`; `kit.signIn(member, { authChoice: 'anthropic-cli' }, on)` starts `claude auth login --claudeai` with that `CLAUDE_CONFIG_DIR` (in its own login HOME) when it is signed out. The waiting view shows the native sign-in address and asks for the returned code; send it through the same handle's `paste`, or `openclawDevice(link).signIn.paste('claude-cli', code)` on the phone. Cancel and expiry stop only this login. The `setup.activate` call is the one commit point: a phone cancel or engine shutdown before it (even with a ready native row) declines with nothing activated; after it a cancel changes nothing, and the result is `done` once the engine restart is confirmed, or says the sign-in was saved but the engine did not restart in time. Engine shutdown also ends that restart wait. An already-ready native row can be detected and activated without a new login. If engine detection disagrees, the stale ready Claude roster row is cleared through Accounts, which deletes that folder's Claude login files (`.credentials.json`, `.claude.json`) but keeps the folder, and one fresh login is started. Pass the installed Claude binary's directory in `enginePath`. For remote ChatGPT use `openai-device-code` with `via: 'code'`; it needs no localhost callback on the phone. Native sign-out is through Claude Code. `apiKey` is explicit API billing (“API key (billed per use)”, `offer: false`): `signIn` asks for the key through `paste`, then engine activation verifies it. The `setup-token` choice is listed but never offered: the pinned Gateway has no app-guided sign-in for it. The kit never imports Claude credentials or implements direct Claude.ai OAuth; [Anthropic’s terms](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) apply.
+Claude: `anthropic-cli` uses your own unmodified Claude Code login on this machine (provider `claude-cli`, plugin `anthropic`; subscription billing; `kit.signedIn(member, 'claude-cli')` is true once Claude Code is signed in, and `'anthropic'` stays the API-billed provider a Claude Code login never satisfies. Before 0.7.0 this route reported provider `anthropic`; that value is deprecated, kept as `deprecatedProvider` until 0.9.0), and the engine uses the installed Claude Code’s own login as is: it runs with your `HOME` (and your own `CLAUDE_CONFIG_DIR` when you set one), so a signed-in Claude Code needs no sign-in step. Only when the installed `claude auth status --json` is not signed in does the engine use its own fallback folder `CLAUDE_CONFIG_DIR=<stateDir>/openclaw/home/.claude`; `kit.signIn(member, { authChoice: 'anthropic-cli' }, on)` then starts `claude auth login --claudeai` with that `CLAUDE_CONFIG_DIR` (in its own login HOME). When the status check gave no answer (a timeout, say), the engine keeps your own login location, and a sign-in it does not detect fails at once with “Claude Code is installed here, but its sign-in could not be checked. Run claude once on this machine to sign in, then try again.” Codex and the engine’s other agent CLIs likewise see your `HOME` and your own `CODEX_HOME`, never a kit-owned one. The gateway and doctor run with your `HOME` too; it is not an access boundary, since engine processes run with your account’s own rights. The waiting view shows the native sign-in address and asks for the returned code; send it through the same handle's `paste`, or `openclawDevice(link).signIn.paste('claude-cli', code)` on the phone. Cancel and expiry stop only this login. The `setup.activate` call is the one commit point: a phone cancel or engine shutdown before it (even with a ready native row) declines with nothing activated; after it a cancel changes nothing, and the result is `done` once the engine restart is confirmed, or says the sign-in was saved but the engine did not restart in time. Engine shutdown also ends that restart wait. An already-ready native row can be detected and activated without a new login. If engine detection disagrees, the stale ready Claude roster row is cleared through Accounts, which deletes that folder's Claude login files (`.credentials.json`, `.claude.json`) but keeps the folder, and one fresh login is started. Pass the installed Claude binary's directory in `enginePath`. For remote ChatGPT use `openai-device-code` with `via: 'code'`; it needs no localhost callback on the phone. Native sign-out is through Claude Code. `apiKey` is explicit API billing (“API key (billed per use)”, `offer: false`): `signIn` asks for the key through `paste`, then engine activation verifies it. The `setup-token` choice is listed but never offered: the pinned Gateway has no app-guided sign-in for it. The kit never imports Claude credentials or implements direct Claude.ai OAuth; [Anthropic’s terms](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) apply.

package/SECURITY.md

@@ -87,9 +87,16 @@ already copied credentials or erase snapshots/backups.
 
 ## Engine isolation and installation
 
-`src/engine.ts` builds the gateway/doctor environment explicitly: HOME, XDG,
-provider-tool homes, tmp, config and state paths point into the app's tree. It does
-not forward shell API keys, `NODE_OPTIONS` or shell environment snapshots. The native
+`src/engine.ts` builds the gateway/doctor environment explicitly: the engine's own
+home (`OPENCLAW_HOME`), cache, tmp, config and state paths point into the app's tree,
+while `HOME` (and the person's own `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`,
+`CLAUDE_CONFIG_DIR` and `CODEX_HOME` when set) is the person's for every engine process
+(gateway, doctor and the agent CLIs), so the installed, signed-in logins are used as is. HOME is not an
+access boundary: the engine runs with the person's own account rights and can open any path that account
+can, including other CLIs' credentials and `~/.ssh`. Engine npm runs use the engine's own npm cache and config
+(`npm_config_cache`, `npm_config_userconfig`), not the person's `~/.npm` or `~/.npmrc`. It does not forward shell API keys, `NODE_OPTIONS` or shell environment
+snapshots. Only when the installed `claude auth status --json` is not signed in does the
+gateway get `CLAUDE_CONFIG_DIR` at the engine's fallback folder. The native fallback
 Claude sign-in child (`claude auth login`, started through `@byokit/accounts/cli`) gets
 the same treatment: its env is only `PATH`, its own login HOME
 (`openclaw/login-home`), `LANG`, `TMPDIR` and the `XDG_*` variables — never the gateway

package/dist/engine.d.ts

@@ -37,6 +37,7 @@ export declare class Engine {
     private claudeAccounts?;
     private claudeReset?;
     private credentialsLocked;
+    private claudeFallback;
     private repaired;
     private prepared?;
     patchSet?: string | null;
@@ -60,13 +61,20 @@ export declare class Engine {
         code: number | null;
         output: string;
     }>;
+    private get path();
+    private get claudeFolder();
     doctorContext(): {
         entry: string;
         env: Record<string, string>;
     };
     /** The engine's own shutdown signal; aborted by stop() and replaced by the next start(). */
     get stopSignal(): AbortSignal;
+    private installedClaudeSignedOut;
+    /** The fallback Claude sign-in for a machine whose installed Claude Code is signed out: it signs into the engine's folder. */
     nativeClaudeLogin(): ReturnType<typeof remoteCliHost>;
+    /** Whether a fallback sign-in would write a folder this engine's gateway does not read: it started on the person's
+     * login location (installed sign-in, or a probe with no answer), and an in-process restart keeps that env. */
+    claudeLoginUnread(): boolean;
     resetNativeClaudeLogin(): Promise<void>;
     doctor(timeoutMs: number): {
         status: number | null;

package/dist/engine.js

@@ -1,7 +1,8 @@
-import { spawn, spawnSync } from 'node:child_process';
+import { execFile, spawn, spawnSync } from 'node:child_process';
 import { randomBytes, generateKeyPairSync, randomUUID } from 'node:crypto';
 import { accessSync, constants, closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, copyFileSync, rmSync, realpathSync, statSync } from 'node:fs';
 import { createServer } from 'node:net';
+import { homedir } from 'node:os';
 import { basename, join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
@@ -34,6 +35,23 @@ const putChanged = (path, data) => {
     if (!existsSync(path) || readFileSync(path, 'utf8') !== data)
         writeFileSync(path, data, { mode: 0o600 });
 };
+// The person's own homes for every engine process: the gateway, doctor and agent CLIs use the installed, signed-in logins as is.
+const personal = () => {
+    const env = { HOME: homedir() };
+    for (const name of ['XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_STATE_HOME', 'CLAUDE_CONFIG_DIR', 'CODEX_HOME']) {
+        const value = process.env[name];
+        if (value)
+            env[name] = value;
+    }
+    return env;
+};
+const onPath = (path, name) => path.split(':').map(dir => join(dir, name)).find(file => { try {
+    accessSync(file, constants.X_OK);
+    return true;
+}
+catch {
+    return false;
+} });
 const supports = (list, value) => !list ||
     (!list.includes(`!${value}`) && (list.includes('any') || list.every(item => item.startsWith('!')) || list.includes(value)));
 // First failed check of the most recent installMatches call; retained with the npm facts in
@@ -98,6 +116,8 @@ export class Engine {
     claudeAccounts;
     claudeReset;
     credentialsLocked = false;
+    // True when the last start found no installed Claude Code login: the engine then uses its own fallback folder.
+    claudeFallback = false;
     repaired = false;
     prepared;
     patchSet;
@@ -184,7 +204,10 @@ export class Engine {
         await this.recoverOrphan();
         for (const d of [this.root, ...(!this.o.authSeal ? [join(this.root, 'home'), join(this.root, 'state')] : []), join(this.root, 'tmp'), join(this.root, 'usage'), join(this.root, 'install-home'), join(this.root, 'npm-cache'), join(this.o.stateDir, 'logs')])
             mkdirSync(d, { recursive: true, mode: 0o700 });
+        putOnce(join(this.root, 'npmrc'), ''); // engine npm runs read this empty config, never the person's ~/.npmrc
         this.sweepAccountOrphans();
+        if (this.o.spawnEngine)
+            this.claudeFallback = await this.installedClaudeSignedOut();
         try {
             await this.authStore.prepare();
             this.credentialsLocked = false;
@@ -304,7 +327,7 @@ export class Engine {
         const npm = this.o.npmPath && this.o.npmPath.includes('/') ? [dirname(this.o.npmPath)] : (process.env.PATH ?? '').split(':');
         return new Promise((resolve, reject) => {
             const child = spawn(process.execPath, [entry, 'plugins', 'install', spec, '--force', '--accept-capabilities'], {
-                cwd: env.HOME, env: { ...env, PATH: [...npm, env.PATH].join(':'), npm_config_cache: join(this.root, 'npm-cache') },
+                cwd: env.OPENCLAW_HOME, env: { ...env, PATH: [...npm, env.PATH].join(':'), npm_config_cache: join(this.root, 'npm-cache') },
                 stdio: ['ignore', 'pipe', 'pipe'],
             });
             let output = '';
@@ -317,14 +340,17 @@ export class Engine {
             child.once('close', code => { clearTimeout(timer); this.started.forget(child); resolve({ code, output }); });
         });
     }
+    get path() { return ['/usr/bin', '/bin', ...this.o.enginePath ?? []].join(':'); }
+    // The engine's own Claude folder: the fallback login writes it and, only with claudeFallback, the gateway reads it.
+    get claudeFolder() { return join(this.root, 'home', '.claude'); }
     doctorContext() {
         const home = join(this.root, 'home');
         return { entry: this.entry, env: {
-                PATH: ['/usr/bin', '/bin', ...this.o.enginePath ?? []].join(':'), LANG: 'C.UTF-8', HOME: home, OPENCLAW_HOME: home,
+                PATH: this.path, LANG: 'C.UTF-8', ...personal(), OPENCLAW_HOME: home,
                 OPENCLAW_STATE_DIR: join(this.root, 'state'), OPENCLAW_CONFIG_PATH: join(this.root, 'openclaw.json'),
-                XDG_CONFIG_HOME: join(home, '.config'), XDG_CACHE_HOME: join(home, '.cache'), XDG_DATA_HOME: join(home, '.local/share'),
-                XDG_STATE_HOME: join(home, '.local/state'), CODEX_HOME: join(home, '.codex'), CLAUDE_CONFIG_DIR: join(home, '.claude'),
-                TMPDIR: join(this.root, 'tmp'), OPENCLAW_NO_RESPAWN: '1', OPENCLAW_SKIP_CHANNELS: '1', OPENCLAW_DISABLE_BONJOUR: '1',
+                XDG_CACHE_HOME: join(home, '.cache'), ...this.claudeFallback ? { CLAUDE_CONFIG_DIR: this.claudeFolder } : {},
+                TMPDIR: join(this.root, 'tmp'), npm_config_cache: join(this.root, 'npm-cache'), npm_config_userconfig: join(this.root, 'npmrc'),
+                OPENCLAW_NO_RESPAWN: '1', OPENCLAW_SKIP_CHANNELS: '1', OPENCLAW_DISABLE_BONJOUR: '1',
                 OPENCLAW_EXEC_SHELL_SNAPSHOT: '0', OPENCLAW_LOAD_SHELL_ENV: '0', OPENCLAW_GATEWAY_TOKEN: this.token,
                 BYOKIT_BRIDGE_SOCK: this.bridgeSock,
                 BYOKIT_APP_OWNED_SESSION_PREFIXES: JSON.stringify(this.appOwnedSessionPrefixes),
@@ -332,26 +358,45 @@ export class Engine {
     }
     /** The engine's own shutdown signal; aborted by stop() and replaced by the next start(). */
     get stopSignal() { return this.stopOwner.signal; }
+    installedClaudeSignedOut() {
+        const env = { PATH: this.path, LANG: 'C.UTF-8', TMPDIR: join(this.root, 'tmp'), ...personal() };
+        const bin = onPath(env.PATH, 'claude');
+        if (!bin)
+            return Promise.resolve(true);
+        return new Promise(resolve => execFile(bin, ['auth', 'status', '--json'], { env, timeout: 15_000, maxBuffer: 256 * 1024 }, (error, stdout) => {
+            let loggedIn;
+            try {
+                loggedIn = JSON.parse(stdout).loggedIn;
+            }
+            catch { /* no parsed answer */ }
+            if (loggedIn === true)
+                return resolve(false);
+            if (loggedIn === false) {
+                this.o.log?.('claude: no installed sign-in, the engine uses its own sign-in folder');
+                return resolve(true);
+            }
+            this.o.log?.(`claude: sign-in status unknown, using the person's own login location (${String(error?.message ?? 'unparseable output').slice(0, 200)})`);
+            resolve(false);
+        }));
+    }
+    /** The fallback Claude sign-in for a machine whose installed Claude Code is signed out: it signs into the engine's folder. */
     nativeClaudeLogin() {
         if (this.claudeLogin)
             return this.claudeLogin;
-        const { env } = this.doctorContext();
-        const bin = env.PATH.split(':').map(path => join(path, 'claude')).find(path => { try {
-            accessSync(path, constants.X_OK);
-            return true;
-        }
-        catch {
-            return false;
-        } });
+        const { env } = this.doctorContext(), home = join(this.root, 'home');
+        const bin = onPath(env.PATH, 'claude');
         const bins = bin ? { claude: bin } : {};
         // The login runs in its own HOME: CLAUDE_CONFIG_DIR points it at the engine's folder, which accounts refuses as a HOME's default login.
         for (const dir of ['home', 'login-home'])
             mkdirSync(join(this.root, dir), { recursive: true, mode: 0o700 });
-        const cli = cliAccounts({ stateDir: this.root, bins, env: { PATH: env.PATH, HOME: join(this.root, 'login-home'), LANG: env.LANG, TMPDIR: env.TMPDIR, XDG_CONFIG_HOME: env.XDG_CONFIG_HOME, XDG_CACHE_HOME: env.XDG_CACHE_HOME, XDG_DATA_HOME: env.XDG_DATA_HOME, XDG_STATE_HOME: env.XDG_STATE_HOME, }, managedFolders: { claude: env.CLAUDE_CONFIG_DIR } });
+        const cli = cliAccounts({ stateDir: this.root, bins, env: { PATH: env.PATH, HOME: join(this.root, 'login-home'), LANG: env.LANG, TMPDIR: env.TMPDIR, XDG_CONFIG_HOME: join(home, '.config'), XDG_CACHE_HOME: join(home, '.cache'), XDG_DATA_HOME: join(home, '.local/share'), XDG_STATE_HOME: join(home, '.local/state') }, managedFolders: { claude: this.claudeFolder } });
         this.claudeAccounts = cli;
         this.claudeLogin = remoteCliHost({ cli, bins });
         return this.claudeLogin;
     }
+    /** Whether a fallback sign-in would write a folder this engine's gateway does not read: it started on the person's
+     * login location (installed sign-in, or a probe with no answer), and an in-process restart keeps that env. */
+    claudeLoginUnread() { return Boolean(this.o.spawnEngine) && !this.claudeFallback; }
     resetNativeClaudeLogin() {
         if (this.claudeReset)
             return this.claudeReset;
@@ -361,7 +406,7 @@ export class Engine {
         this.claudeReset = (async () => { for (const row of await cli.list()) {
             if (host.signal.aborted)
                 return;
-            if (row.provider === 'claude' && row.state === 'ready' && cli.folderOf(row.id) === join(this.root, 'home', '.claude'))
+            if (row.provider === 'claude' && row.state === 'ready' && cli.folderOf(row.id) === this.claudeFolder)
                 await cli.remove(row.id);
         } })().finally(() => { this.claudeReset = undefined; });
         return this.claudeReset;
@@ -370,7 +415,7 @@ export class Engine {
         const { entry, env } = this.doctorContext();
         if (this.o.spawnEngine)
             verifyEngineSet(this.setDir, this.wantedSet, installMatches);
-        const result = spawnSync(process.execPath, [entry, 'doctor', '--fix', '--yes', '--non-interactive'], { cwd: env.HOME, env, timeout: timeoutMs, stdio: 'pipe' });
+        const result = spawnSync(process.execPath, [entry, 'doctor', '--fix', '--yes', '--non-interactive'], { cwd: env.OPENCLAW_HOME, env, timeout: timeoutMs, stdio: 'pipe' });
         if (this.o.spawnEngine)
             verifyEngineSet(this.setDir, this.wantedSet, installMatches);
         return { status: result.status };
@@ -389,7 +434,7 @@ export class Engine {
                 && identity.pid === pid && identity.startTime === processStartTime(pid)
                 && realpathSync(`${proc}/exe`) === realpathSync(process.execPath)
                 && realpathSync(`${proc}/cwd`) === realpathSync(home)
-                && env.includes(`HOME=${home}`)
+                && env.includes(`OPENCLAW_HOME=${home}`)
                 && env.includes(`OPENCLAW_STATE_DIR=${join(this.root, 'state')}`)
                 && env.includes(`OPENCLAW_CONFIG_PATH=${join(this.root, 'openclaw.json')}`)
                 && existsSync(owner) && !pidAlive(Number(readFileSync(owner, 'utf8')));
@@ -527,7 +572,7 @@ export class Engine {
             }
             // Detached keeps the engine out of the host's session; stop() still signals its pid alone, never its group.
             try {
-                this.child = spawn(process.execPath, [entry, 'gateway', '--port', String(this.port)], { cwd: env.HOME, env, detached: true, stdio: ['ignore', fd, fd] });
+                this.child = spawn(process.execPath, [entry, 'gateway', '--port', String(this.port)], { cwd: env.OPENCLAW_HOME, env, detached: true, stdio: ['ignore', fd, fd] });
             }
             catch (error) {
                 if (env.BYOKIT_ENGINE_BOOT)
@@ -552,7 +597,7 @@ export class Engine {
             if (this.child !== child || this.stopping)
                 return;
             this.child = undefined;
-            void this.authStore.stop().then(() => undefined, refusedOnly).then((refused) => { this.exitedState(refused); this.o.onExit(null); }, () => this.state('failed', 'exited'));
+            void this.authStore.stop().then(() => undefined, refusedOnly).then((refused) => { this.exitedState(refused); this.o.onExit(null); }, () => { this.state('failed', 'exited'); this.o.onExit(null); });
         });
         if (!child.pid) {
             this.state('failed', 'exited');
@@ -588,7 +633,7 @@ export class Engine {
                 }
                 this.exitedState(refused);
                 this.o.onExit(code);
-            })().catch(() => this.state('failed', 'exited'));
+            })().catch(() => { this.state('failed', 'exited'); this.o.onExit(code); });
         });
         return { port: this.port, token: this.token, identityPath };
     }

package/dist/kit.d.ts

@@ -35,6 +35,7 @@ export type KitOptions = {
     };
     callbackPort?: number;
     approvalTimeoutMs?: number;
+    handshakeMs?: number;
     transport?: (ctx: {
         port: number;
         token: string;
@@ -74,8 +75,13 @@ export declare class OpenClawKit {
     private signInDisconnects;
     private readonly phaseListeners;
     private starting?;
+    private stopped;
     private stopping;
     private failures;
+    private reachedReady;
+    private startRun?;
+    private retry?;
+    private engineExit?;
     private swept;
     private catalogs;
     browser?: BrowserHost;
@@ -99,13 +105,17 @@ export declare class OpenClawKit {
     get state(): KitState;
     prepare(): Promise<void>;
     start(): Promise<void>;
+    private attempts;
     private connect;
+    private repairEnded;
     private disconnect;
     private engineRestarting;
     private authSnapshot;
     private restarted;
     private closed;
+    private backoff;
     stop(): Promise<void>;
+    private teardown;
     private closeBrowsers;
     private request;
     call<M extends GatewayMethod>(method: M, params: GatewayParams<M>, o?: CallOptions): Promise<GatewayResult<M>>;
@@ -221,6 +231,7 @@ export declare class OpenClawKit {
     setLearning(mode: LearningMode | 'default'): LearningCapture;
     restoreLearning(captured: LearningCapture): LearningCapture;
     private assertLearningWritable;
+    /** The env for an external doctor. Its Claude login folder is the one chosen at `prepare()`/`start()`; before that it is the installed-login view only. */
     doctorContext(): {
         entry: string;
         env: Record<string, string>;

package/dist/kit.js

@@ -32,6 +32,8 @@ import { launchBroker } from './browser/broker.js';
 /** The engine's learning-mode config key (5.6 "Engine learning state"). */
 const LEARNING_KEY = 'skills.workshop.autonomous.mode';
 const RESTART_MS = 60_000;
+/** Consecutive failed starts before `failed/handshake` (5.4 step 2): the first start plus four retries. */
+const START_ATTEMPTS = 5;
 const operatorMethods = new Set([
     'agent',
     'agent.identity.get',
@@ -452,8 +454,13 @@ export class OpenClawKit {
     signInDisconnects = new Set();
     phaseListeners = new Set();
     starting;
+    stopped = Promise.resolve();
     stopping = false;
     failures = 0;
+    reachedReady = false;
+    startRun;
+    retry;
+    engineExit;
     swept = false;
     catalogs = Promise.resolve();
     browser;
@@ -737,20 +744,52 @@ export class OpenClawKit {
         if (this.engine.patchSet !== undefined)
             this.setState(this.current);
     }
-    start() {
+    async start() {
         if (this.current.phase === 'ready')
-            return Promise.resolve();
+            return;
+        if (this.stopping) {
+            await this.starting?.catch(() => undefined);
+            await this.stopped;
+        }
         if (this.starting)
             return this.starting;
         this.stopping = false;
-        const task = this.connect();
+        this.retry?.abort();
+        const task = this.attempts(this.reachedReady ? 1 : START_ATTEMPTS);
         this.starting = task;
         void task.finally(() => { if (this.starting === task)
             this.starting = undefined; }).catch(() => { });
         return task;
     }
+    // One start() call's attempts (5.4 step 2): a missed hello waits the reconnect backoff and starts the engine afresh
+    // until `budget` attempts have missed. The call owns its wait (stop() aborts it) and, on a first start, every close.
+    async attempts(budget) {
+        const run = this.startRun = new AbortController();
+        try {
+            for (let missed = 0;;) {
+                const miss = await this.connect();
+                if (!miss) {
+                    if (this.stopping)
+                        throw new Error('kit stopped before ready');
+                    return;
+                }
+                if (++missed === budget) {
+                    this.setState({ phase: 'failed', why: 'handshake' });
+                    throw miss;
+                }
+                await this.backoff(missed - 1, run.signal);
+            }
+        }
+        finally {
+            if (this.startRun === run)
+                this.startRun = undefined;
+        }
+    }
+    // Resolves the error of a missed hello (a deadline miss, or an engine exit before hello) for attempts() to retry.
     async connect() {
         let transport;
+        const timeout = new Error('gateway handshake timed out');
+        const exited = new Error('engine exited before the gateway handshake');
         try {
             await this.prepareBrowsers();
             const ctx = await this.engine.start();
@@ -761,7 +800,9 @@ export class OpenClawKit {
             this.transport = transport;
             this.off = [transport.onEvent((e) => { for (const fn of this.listeners)
                     fn(e); }), transport.onClose((why) => this.closed(why))];
-            const hello = await Promise.race([transport.start(), delay(90_000, undefined, { ref: false }).then(() => { throw new Error('gateway handshake timed out'); })]);
+            const deadline = delay(this.o.handshakeMs ?? 90_000, undefined, { ref: false }).then(() => { throw timeout; });
+            const exit = new Promise((_, reject) => { this.engineExit = () => reject(exited); });
+            const hello = await Promise.race([transport.start(), deadline, exit]);
             if (this.stopping || this.transport !== transport)
                 return;
             if (hello.protocol !== PROTOCOL_VERSION) {
@@ -782,9 +823,10 @@ export class OpenClawKit {
                 signIn: (agentId, o, on, fresh) => startSignIn({ ...this.signInCtx(), ensure: async () => ({ agentId }), fresh }, agentId, o, on),
                 routes: this.routeMap, log: this.o.log, reseal: () => this.engine.authStore.reseal() });
             // The fail-closed tool bridge feeds the kit's single Approval surface (5.9, O5).
-            await this.bridge.start();
+            await Promise.race([this.bridge.start(), exit]);
             this.off.push(transport.onEvent((e) => this.approvalsCtl.handleEvent(e)));
             this.failures = 0;
+            this.reachedReady = true;
             this.setState({ phase: 'ready' });
             this.syncCatalogs();
             // A failed key add whose abandon clear never reached the engine leaves an unsealed key with no ready marker;
@@ -803,6 +845,9 @@ export class OpenClawKit {
             const patchFailure = this.current.why === 'engine-patch';
             if (transport && this.transport === transport)
                 await this.disconnect();
+            if (error === timeout && this.current.phase === 'repairing')
+                await this.repairEnded();
+            const engineFailure = this.current.phase === 'failed' ? this.current : undefined;
             const refused = await this.engine.stop().then(() => undefined, refusedOnly);
             await this.closeBrowsers();
             const sealRefusal = refused ?? (error instanceof AuthStoreSealSizeError ? error : undefined);
@@ -822,12 +867,32 @@ export class OpenClawKit {
                 this.setState({ phase: 'failed', why: 'engine-patch' });
                 throw error;
             }
+            // A missed hello on a loaded host is the engine still coming up: attempts() decides whether to retry.
+            if (engineFailure?.why === 'auth-store-seal-size' && !this.stopping) {
+                this.setState(engineFailure);
+                throw error;
+            }
+            const miss = error === exited && engineFailure?.why === 'exited' ? exited : error === timeout ? timeout : undefined;
+            if (miss && !this.stopping)
+                return miss;
             if (needsUpdate)
                 this.setState({ phase: 'needs-update', why: 'version' });
             if (!needsUpdate && !this.stopping)
                 this.setState({ phase: 'failed', why: 'handshake' });
             throw error;
         }
+        finally {
+            this.engineExit = undefined;
+        }
+    }
+    repairEnded() {
+        return new Promise((resolve) => {
+            const check = () => { if (this.current.phase !== 'repairing') {
+                this.phaseListeners.delete(check);
+                resolve();
+            } };
+            this.phaseListeners.add(check);
+        });
     }
     async disconnect() {
         this.admission.invalidate();
@@ -874,8 +939,14 @@ export class OpenClawKit {
             signal?.addEventListener('abort', abort, { once: true });
         });
     }
-    closed(_why) {
-        const engineFailed = _why === 'engine exited' && this.current.phase === 'failed' && this.current.why === 'exited';
+    closed(why) {
+        // A first start's loop owns an engine exit until it reaches ready; other closes are the transport client's to retry.
+        if (this.startRun && !this.reachedReady) {
+            if (why === 'engine exited')
+                this.engineExit?.();
+            return;
+        }
+        const engineFailed = why === 'engine exited' && this.current.phase === 'failed' && this.current.why === 'exited';
         if (this.stopping || (this.current.phase !== 'ready' && !engineFailed))
             return;
         for (const fn of this.signInDisconnects)
@@ -885,13 +956,26 @@ export class OpenClawKit {
             this.setState({ phase: 'failed', why: 'handshake' });
             return;
         }
-        const retryAt = Date.now() + Math.min(30_000, 1000 * 2 ** this.failures++);
+        this.retry?.abort();
+        const retry = this.retry = new AbortController();
+        void this.backoff(this.failures++, retry.signal).then(() => { if (!this.stopping && this.current.phase === 'restarting')
+            void this.start().catch(() => { }); }, () => { });
+    }
+    // The reconnect backoff (step 3): state restarting, resolving at retryAt = now + min(30 s, 1 s × 2^failures).
+    backoff(failures, signal) {
+        const retryAt = Date.now() + Math.min(30_000, 1000 * 2 ** failures);
         this.setState({ phase: 'restarting', retryAt });
-        void delay(retryAt - Date.now()).then(() => { if (!this.stopping && this.current.phase === 'restarting')
-            void this.start().catch(() => { }); });
+        return delay(retryAt - Date.now(), undefined, { signal });
     }
     async stop() {
         this.stopping = true;
+        this.reachedReady = false;
+        this.startRun?.abort();
+        this.retry?.abort();
+        this.stopped = this.teardown();
+        await this.stopped;
+    }
+    async teardown() {
         await this.disconnect();
         await this.engine.stop();
         await this.closeBrowsers();
@@ -971,6 +1055,7 @@ export class OpenClawKit {
             ensure: (member) => this.ensureMember(member), callbackPort: this.o.callbackPort ?? 1455,
             nativeClaudeLogin: () => this.engine.nativeClaudeLogin(),
             resetNativeClaudeLogin: () => this.engine.resetNativeClaudeLogin(),
+            claudeLoginUnread: () => this.engine.claudeLoginUnread(),
             onDisconnect: (fn) => { this.signInDisconnects.add(fn); return () => { this.signInDisconnects.delete(fn); }; },
             stopSignal: this.engine.stopSignal,
             authConfig: () => this.authSnapshot(),
@@ -1382,5 +1467,6 @@ export class OpenClawKit {
         if (this.o.config?.skills !== undefined)
             throw new Error(`${op}: KitOptions.config also passes skills; that option wins at every boot (5.6)`);
     }
+    /** The env for an external doctor. Its Claude login folder is the one chosen at `prepare()`/`start()`; before that it is the installed-login view only. */
     doctorContext() { return this.engine.doctorContext(); }
 }

package/dist/signin.d.ts

@@ -10,6 +10,7 @@ export type SignInCtx = {
     callbackPort: number;
     nativeClaudeLogin?(): ReturnType<typeof remoteCliHost>;
     resetNativeClaudeLogin?(): Promise<void>;
+    claudeLoginUnread?(): boolean;
     onDisconnect?(fn: () => void): () => void;
     authConfig(): string;
     restarted(authBefore: string | undefined, signal?: AbortSignal): Promise<boolean>;

package/dist/signin.js

@@ -242,6 +242,8 @@ export function signIn(ctx, member, o, on) {
                 };
                 native = ctx.nativeClaudeLogin?.();
                 if (!await detected()) {
+                    if (ctx.claudeLoginUnread?.())
+                        return { state: 'failed', via, why: 'failed', error: 'Claude Code is installed here, but its sign-in could not be checked. Run claude once on this machine to sign in, then try again.' };
                     if (!native)
                         return { state: 'failed', via, why: 'failed', error: 'Claude Code sign-in is not available on this engine.' };
                     let started = await native.start('claude', { signal });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "The OpenClaw runtime kit: the pinned engine's full operator surface with plain-words helpers for members, sign-in, runs and approvals.",
   "license": "Apache-2.0",
   "type": "module",
@@ -60,7 +60,7 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/accounts": "0.27.0",
+    "@byokit/accounts": "0.27.1",
     "@byokit/pair": "0.10.3",
     "@byokit/relay": "0.8.1",
     "@byokit/discover": "0.8.4",