@byokit/openclaw 0.3.4 → 0.3.5

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.3.5 (2026-10-01)
+
+
+
+- FIX: Failed engine starts no longer remove another live gateway’s guards or saved sign-in state. Verified dead-host gateways stop gracefully before restart; ambiguous ownership returns a typed engine-already-running error and preserves the store.
+
 ## 0.3.4 (2026-09-30)
 
 

package/README.md

@@ -232,7 +232,14 @@ before any restoration; a wrong key, tampering, or a missing adapter rejects. Fi
 have mode 0600 and directories 0700. File symlinks are sealed only when their fully resolved targets are
 regular files inside the isolated engine root; they restore as regular files at the link paths. Outside-root,
 dangling and directory symlinks (including loops), sockets, FIFOs and devices are skipped.
-One kit owns the store at a time; a live owner or orphan gateway blocks preparation instead of racing its writes.
+One kit owns the store at a time. After a host crash, preparation stops a verified same-user gateway
+only when its host lock owner is dead, waits up to three seconds for exit, then seals and restores the
+leftover state under the acquired lock. If process identity is ambiguous (including unavailable process
+inspection or a rewritten command line), another host is alive, or shutdown times out, `prepare()` and
+`start()` reject with exported `EngineAlreadyRunningError` (`code: 'engine-already-running'`). The kit reports
+`{ phase: 'failed', why: 'engine-already-running' }`; show `stateWords(kit.state)` and retry after the other
+session stops. Failed-start cleanup and `stop()` on an instance with no ownership preserve the other
+writer's pid, lock, sealed snapshot and live state.
 Sealing copies the whole store through memory, so startup and stop cost grows with session history.
 
 The migration doctor temporarily opens the same store and reseals it even when import fails. Once the gateway

package/dist/auth-store.js

@@ -2,20 +2,10 @@
 // Seal the complete isolated stores, including journals, only after their writer has exited.
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, closeSync, fsyncSync, openSync } from 'node:fs';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { EngineAlreadyRunningError, pidAlive as live } from "./engine-status.js";
 const encoder = new TextEncoder();
 const archive = (name) => /^(auth-profiles|auth-state|auth|oauth)\.json\.(migrated-.+|sqlite-import\..+\.bak)$/.test(name)
     || name.endsWith('.moved-to-engine');
-const live = (pid) => {
-    if (!Number.isSafeInteger(pid) || pid < 1)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return error.code !== 'ESRCH';
-    }
-};
 function regular(path) {
     if (!lstatSync(path).isFile())
         throw new Error(`credential store requires regular files: ${path}`);
@@ -108,18 +98,16 @@ export class AuthStore {
             return;
         if (existsSync(this.file) && !this.o.seal)
             throw new Error('authSeal required for sealed credential store');
-        if (!this.o.seal)
-            return;
         // Never race a live gateway or another kit, including an orphan after its host crashed.
         const gateway = join(this.o.root, 'gateway.pid');
         if (existsSync(gateway) && live(Number(readFileSync(gateway, 'utf8'))))
-            throw new Error('credential store is in use');
+            throw new EngineAlreadyRunningError();
         if (existsSync(this.lock)) {
             if (!lstatSync(this.lock).isDirectory() || lstatSync(this.lock).isSymbolicLink())
                 throw new Error('invalid credential lock');
             const owner = join(this.lock, 'pid');
             if (!existsSync(owner) || live(Number(readFileSync(owner, 'utf8'))))
-                throw new Error('credential store is in use');
+                throw new EngineAlreadyRunningError();
             // Only one stale-owner recovery can proceed. Recheck after claiming it so a stale reader
             // cannot remove the lock a newer owner has just acquired.
             const recovery = join(this.lock, 'recovery');
@@ -127,17 +115,36 @@ export class AuthStore {
                 mkdirSync(recovery, { mode: 0o700 });
             }
             catch {
-                throw new Error('credential store is in use');
+                throw new EngineAlreadyRunningError();
             }
             if (!existsSync(owner) || live(Number(readFileSync(owner, 'utf8')))) {
                 rmSync(recovery, { recursive: true });
-                throw new Error('credential store is in use');
+                throw new EngineAlreadyRunningError();
             }
             rmSync(this.lock, { recursive: true });
         }
-        mkdirSync(this.lock, { mode: 0o700 });
-        writeFileSync(join(this.lock, 'pid'), String(process.pid), { mode: 0o600, flag: 'wx' });
+        try {
+            mkdirSync(this.lock, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                throw new EngineAlreadyRunningError();
+            throw error;
+        }
         this.owned = true;
+        try {
+            writeFileSync(join(this.lock, 'pid'), String(process.pid), { mode: 0o600, flag: 'wx' });
+            // Recheck under the acquired lock before removing a dead writer's guard.
+            if (existsSync(gateway)) {
+                if (live(Number(readFileSync(gateway, 'utf8'))))
+                    throw new EngineAlreadyRunningError();
+                removeMarker(gateway);
+            }
+        }
+        catch (error) {
+            this.release();
+            throw error;
+        }
     }
     release() {
         if (!this.owned)
@@ -297,7 +304,8 @@ export class AuthStore {
     }
     stop() {
         return this.serial(async () => {
-            this.acquire();
+            if (!this.owned)
+                return;
             await this.archives();
             await this.persist();
             this.active = false;

package/dist/engine-status.d.ts

@@ -0,0 +1,6 @@
+/** A live or unverifiable writer still owns the isolated engine state. Retry after it stops. */
+export declare class EngineAlreadyRunningError extends Error {
+    readonly code = "engine-already-running";
+    constructor();
+}
+export declare function pidAlive(pid: number): boolean;

package/dist/engine-status.js

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+/** A live or unverifiable writer still owns the isolated engine state. Retry after it stops. */
+export class EngineAlreadyRunningError extends Error {
+    code = 'engine-already-running';
+    constructor() {
+        super('engine already running; credential store is in use');
+        this.name = 'EngineAlreadyRunningError';
+    }
+}
+export function pidAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return true; // An invalid guard is ambiguous, never stale.
+    try {
+        process.kill(pid, 0);
+        // An orphan can remain a zombie until its new parent reaps it; it has no writer left.
+        if (process.platform === 'linux') {
+            const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+            if (stat.slice(stat.lastIndexOf(')') + 2).startsWith('Z '))
+                return false;
+        }
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}

package/dist/engine.d.ts

@@ -36,7 +36,8 @@ export declare class Engine {
     doctor(timeoutMs: number): {
         status: number | null;
     };
-    private stalePid;
+    private verifiedOrphan;
+    private recoverOrphan;
     start(): Promise<{
         port: number;
         token: string;
@@ -45,6 +46,7 @@ export declare class Engine {
     private locked;
     private startOnce;
     private launch;
+    private removeOwnedPid;
     withAuthStore<T>(task: () => Promise<T>): Promise<T>;
     stop(): Promise<void>;
 }

package/dist/engine.js

@@ -1,11 +1,12 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes, generateKeyPairSync } from 'node:crypto';
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, copyFileSync, rmSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, copyFileSync, rmSync, realpathSync, statSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
 import { AuthStore } from "./auth-store.js";
+import { EngineAlreadyRunningError, pidAlive } from "./engine-status.js";
 import { ENGINE_VERSION } from "./constants.js";
 import { reconcileConfig } from "./config.js";
 import { writePlugin, resolveBridge } from "./bridge.js";
@@ -93,6 +94,7 @@ export class Engine {
     async prepareOnce() {
         if (!this.o.authSeal && existsSync(join(this.root, 'auth-store.sealed')))
             throw new Error('authSeal required for sealed credential store');
+        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, 'install-home'), join(this.root, 'npm-cache'), join(this.o.stateDir, 'logs'), this.dir])
             mkdirSync(d, { recursive: true, mode: 0o700 });
         try {
@@ -168,19 +170,67 @@ export class Engine {
         const result = spawnSync(process.execPath, [entry, 'doctor', '--fix', '--yes', '--non-interactive'], { cwd: env.HOME, env, timeout: timeoutMs, stdio: 'pipe' });
         return { status: result.status };
     }
-    stalePid() {
+    verifiedOrphan(pid) {
+        if (process.platform !== 'linux' || !process.getuid)
+            return false;
+        try {
+            const proc = `/proc/${pid}`;
+            const cmd = readFileSync(`${proc}/cmdline`, 'utf8').split('\0');
+            const env = readFileSync(`${proc}/environ`, 'utf8').split('\0');
+            const home = join(this.root, 'home');
+            const owner = join(this.root, 'auth-store.lock', 'pid');
+            return statSync(proc).uid === process.getuid()
+                && realpathSync(`${proc}/exe`) === realpathSync(process.execPath)
+                && cmd.indexOf(this.entry) > 0 && cmd[cmd.indexOf(this.entry) + 1] === 'gateway'
+                && realpathSync(`${proc}/cwd`) === realpathSync(home)
+                && env.includes(`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')));
+        }
+        catch {
+            return false;
+        }
+    }
+    async recoverOrphan() {
+        if (this.child && this.child.exitCode === null && this.child.signalCode === null)
+            return;
         const path = join(this.root, 'gateway.pid');
         if (!existsSync(path))
             return;
         const pid = Number(readFileSync(path, 'utf8'));
-        if (!Number.isSafeInteger(pid) || pid < 1)
-            return;
+        if (!pidAlive(pid))
+            return; // AuthStore removes stale guards only under its lock.
+        const occupied = () => { this.state('failed', 'engine-already-running'); return new EngineAlreadyRunningError(); };
+        if (!this.verifiedOrphan(pid))
+            throw occupied();
+        // Verify a stable process identity again immediately before signalling this pid, never its group.
+        const identity = () => {
+            const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+            return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19]; // starttime, not a reusable pid alone
+        };
+        try {
+            const before = identity();
+            if (!before || !this.verifiedOrphan(pid) || before !== identity())
+                throw occupied();
+        }
+        catch {
+            if (!pidAlive(pid))
+                return;
+            throw occupied();
+        }
         try {
-            const cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8');
-            if (cmd.includes(this.entry) && cmd.includes('gateway'))
-                process.kill(-pid, 'SIGTERM');
+            process.kill(pid, 'SIGTERM');
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                throw occupied();
         }
-        catch { /* pid is gone or not ours */ }
+        for (let i = 0; i < 15 && pidAlive(pid); i++)
+            await delay(200);
+        if (pidAlive(pid))
+            throw occupied();
+        // The new store owner now seals crash leftovers under its lock before restoring them.
     }
     start() {
         if (this.starting)
@@ -215,7 +265,9 @@ export class Engine {
             return this.launch();
         }
         catch (error) {
-            await this.authStore.stop();
+            // A launch failure after spawn still has a writer; the caller's stop must await its exit.
+            if (!this.child)
+                await this.authStore.stop();
             throw error;
         }
     }
@@ -229,7 +281,6 @@ export class Engine {
             return { port: this.port, token: this.token, identityPath };
         if (this.child && this.child.exitCode === null)
             return { port: this.port, token: this.token, identityPath };
-        this.stalePid();
         this.state('starting');
         const { entry, env } = this.doctorContext();
         const fd = openSync(join(this.o.stateDir, 'logs', 'openclaw.log'), 'a', 0o600);
@@ -255,7 +306,7 @@ export class Engine {
             if (this.child !== child || this.stopping)
                 return;
             this.child = undefined;
-            rmSync(join(this.root, 'gateway.pid'), { force: true });
+            this.removeOwnedPid(child.pid);
             void (async () => {
                 await this.authStore.stop();
                 if (this.stopping)
@@ -275,6 +326,11 @@ export class Engine {
         });
         return { port: this.port, token: this.token, identityPath };
     }
+    removeOwnedPid(pid) {
+        const path = join(this.root, 'gateway.pid');
+        if (pid && existsSync(path) && readFileSync(path, 'utf8') === String(pid))
+            rmSync(path, { force: true });
+    }
     withAuthStore(task) { return this.authStore.offline(task); }
     async stop() {
         this.stopping = true;
@@ -299,10 +355,9 @@ export class Engine {
         if (child && child.exitCode === null && child.signalCode === null)
             throw new Error('engine did not stop; credential store still in use');
         this.child = undefined;
-        rmSync(join(this.root, 'gateway.pid'), { force: true });
+        this.removeOwnedPid(child?.pid);
         if (!this.credentialsLocked)
             await this.authStore.stop();
-        rmSync(this.bridgeSock, { force: true });
         this.state('stopped');
     }
 }

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.t
 export type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, RunUsage, SignInOptions, SignInView, ToolHost, ToolSpec, } from './types.ts';
 export { OpenClawKit, type KitOptions, type RetainedLogin } from './kit.ts';
 export { stateWords, toAccountView, words, type AccountView, type WordKey } from './words.ts';
+export { EngineAlreadyRunningError } from './engine-status.ts';

package/dist/index.js

@@ -3,3 +3,4 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from "./constants.js";
 export { OpenClawKit } from "./kit.js";
 export { stateWords, toAccountView, words } from "./words.js";
+export { EngineAlreadyRunningError } from "./engine-status.js";

package/dist/kit.js

@@ -503,6 +503,10 @@ export class OpenClawKit {
             if (transport && this.transport === transport)
                 await this.disconnect();
             await this.engine.stop();
+            if (error instanceof Error && 'code' in error && error.code === 'engine-already-running') {
+                this.setState({ phase: 'failed', why: 'engine-already-running' });
+                throw error;
+            }
             if (needsUpdate)
                 this.setState({ phase: 'needs-update', why: 'version' });
             if (!needsUpdate && !this.stopping)

package/dist/types.d.ts

@@ -115,7 +115,7 @@ export type Decision = {
 };
 export type KitState = {
     phase: 'stopped' | 'installing' | 'starting' | 'repairing' | 'ready' | 'restarting' | 'failed' | 'needs-update' | 'locked';
-    why?: 'install' | 'handshake' | 'exited' | 'port' | 'version';
+    why?: 'install' | 'handshake' | 'exited' | 'port' | 'version' | 'engine-already-running';
     retryAt?: number;
 };
 export type Hello = {

package/dist/words.js

@@ -19,6 +19,8 @@ const PHASE_WORDS = {
 };
 export function stateWords(s) {
     // 'stopped' is never on screen (4.3 covers what a person can see), so 5.14 has no row for it.
+    if (s.phase === 'failed' && s.why === 'engine-already-running')
+        return words('engine.alreadyRunning');
     return s.phase === 'stopped' ? '' : words(PHASE_WORDS[s.phase]);
 }
 export function toAccountView(view, ready) {

package/dist/words.json

@@ -5,6 +5,7 @@
     "engine.locked": "Your saved sign-in is locked. Unlock your password storage, then try again.",
     "engine.ready": "Ready.",
     "engine.restarting": "Something stopped. Starting it again by itself.",
+    "engine.alreadyRunning": "Your saved sign-in is in use. Try again after the other session stops.",
     "engine.failed": "This computer couldn't start the helper. Restart the app to try again.",
     "engine.needsUpdate": "This app needs an update to keep working.",
     "member.signedOut": "Sign in with {name} to start.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "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",