@winmatrix/supervisor 1.0.6 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winmatrix/supervisor",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "type": "module",
   "main": "src/run-agent-engine.mjs",
   "bin": {

package/src/openclaw-device-store.mjs

@@ -0,0 +1,208 @@
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createHash, createPublicKey, generateKeyPairSync } from 'node:crypto';
+
+const REQUIRED_SCOPES = ['operator.read', 'operator.write'];
+
+function parseRecord(raw, gatewayOrigin) {
+  const value = JSON.parse(raw);
+  if (!value || value.version !== 1 || value.gatewayOrigin !== gatewayOrigin
+    || !['unpaired', 'pairing_pending', 'paired', 'token_stale'].includes(value.status)
+    || typeof value.deviceId !== 'string'
+    || typeof value.privateKeyPem !== 'string' || typeof value.publicKeyPem !== 'string'
+    || typeof value.role !== 'string' || !Array.isArray(value.scopes)) {
+    throw new Error('OpenClaw workstation device binding is invalid');
+  }
+  return value;
+}
+
+function publicKeyRaw(publicKeyPem) {
+  const der = createPublicKey(publicKeyPem).export({ type: 'spki', format: 'der' });
+  if (der.length < 32) throw new Error('OpenClaw workstation public key is invalid');
+  return der.subarray(der.length - 32);
+}
+
+export function fingerprintOpenClawPublicKey(publicKeyPem) {
+  return createHash('sha256').update(publicKeyRaw(publicKeyPem)).digest('hex');
+}
+
+export function encodeOpenClawPublicKey(publicKeyPem) {
+  return publicKeyRaw(publicKeyPem).toString('base64url');
+}
+
+function assertPrivatePermissions(path) {
+  if (process.platform === 'win32') return;
+  if ((statSync(path).mode & 0o077) !== 0) {
+    throw new Error('OpenClaw workstation device binding must have mode 0600');
+  }
+}
+
+function acquireLock(lockPath) {
+  mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+  for (let attempt = 0; attempt < 80; attempt += 1) {
+    try {
+      const fd = openSync(lockPath, 'wx', 0o600);
+      writeFileSync(fd, `${process.pid}\n`, 'utf8');
+      closeSync(fd);
+      return;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      const ageMs = Date.now() - statSync(lockPath).mtimeMs;
+      if (ageMs > 30_000) {
+        rmSync(lockPath, { force: true });
+        continue;
+      }
+      const wait = new Int32Array(new SharedArrayBuffer(4));
+      Atomics.wait(wait, 0, 0, 25);
+    }
+  }
+  throw new Error('OpenClaw workstation device binding is locked');
+}
+
+function atomicWrite(path, value, lockPath) {
+  acquireLock(lockPath);
+  const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(tempPath, JSON.stringify(value, null, 2), { mode: 0o600, flag: 'wx' });
+    chmodSync(tempPath, 0o600);
+    renameSync(tempPath, path);
+    chmodSync(path, 0o600);
+  } finally {
+    rmSync(tempPath, { force: true });
+    rmSync(lockPath, { force: true });
+  }
+}
+
+export class WorkstationOpenClawDeviceStore {
+  #filePath;
+  #lockPath;
+  #gatewayOrigin;
+
+  constructor({ stateDir, gatewayOrigin }) {
+    this.#filePath = join(stateDir, 'winmatrix-gateway-client', 'device-auth.json');
+    this.#lockPath = `${this.#filePath}.lock`;
+    this.#gatewayOrigin = gatewayOrigin;
+  }
+
+  #load() {
+    if (!existsSync(this.#filePath)) {
+      throw new Error('OpenClaw workstation DeviceToken is not paired');
+    }
+    assertPrivatePermissions(this.#filePath);
+    return parseRecord(readFileSync(this.#filePath, 'utf8'), this.#gatewayOrigin);
+  }
+
+  #loadOptional() {
+    if (!existsSync(this.#filePath)) return null;
+    assertPrivatePermissions(this.#filePath);
+    return parseRecord(readFileSync(this.#filePath, 'utf8'), this.#gatewayOrigin);
+  }
+
+  loadOrCreateIdentity() {
+    let record = this.#loadOptional();
+    if (!record) {
+      const pair = generateKeyPairSync('ed25519');
+      const privateKeyPem = pair.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+      const publicKeyPem = pair.publicKey.export({ type: 'spki', format: 'pem' }).toString();
+      record = {
+        version: 1,
+        gatewayOrigin: this.#gatewayOrigin,
+        deviceId: fingerprintOpenClawPublicKey(publicKeyPem),
+        privateKeyPem,
+        publicKeyPem,
+        role: 'operator',
+        scopes: [],
+        status: 'unpaired',
+      };
+      mkdirSync(dirname(this.#filePath), { recursive: true, mode: 0o700 });
+      chmodSync(dirname(this.#filePath), 0o700);
+      atomicWrite(this.#filePath, record, this.#lockPath);
+    }
+    return {
+      deviceId: record.deviceId,
+      privateKeyPem: record.privateKeyPem,
+      publicKeyPem: record.publicKeyPem,
+    };
+  }
+
+  loadToken({ gatewayOrigin, deviceId, role }) {
+    const record = this.#load();
+    if (gatewayOrigin !== this.#gatewayOrigin || record.deviceId !== deviceId || record.role !== role) {
+      return null;
+    }
+    if (record.status !== 'paired' || typeof record.deviceToken !== 'string') return null;
+    for (const scope of REQUIRED_SCOPES) {
+      if (!record.scopes.includes(scope)) {
+        throw new Error(`OpenClaw workstation DeviceToken is missing scope '${scope}'`);
+      }
+    }
+    return { token: record.deviceToken, scopes: [...record.scopes] };
+  }
+
+  storeToken({ gatewayOrigin, deviceId, role, token, scopes }) {
+    const record = this.#loadOptional();
+    if (!record) throw new Error('OpenClaw workstation device identity is unavailable');
+    if (gatewayOrigin !== this.#gatewayOrigin || record.deviceId !== deviceId) {
+      throw new Error('OpenClaw workstation DeviceToken rotation binding mismatch');
+    }
+    atomicWrite(this.#filePath, {
+      ...record,
+      role,
+      scopes: [...scopes],
+      status: 'paired',
+      deviceToken: token,
+    }, this.#lockPath);
+  }
+
+  clearToken({ gatewayOrigin, deviceId, role }) {
+    const record = this.#loadOptional();
+    if (!record) return;
+    if (gatewayOrigin !== this.#gatewayOrigin || record.deviceId !== deviceId || record.role !== role) return;
+    const { deviceToken: _removed, ...withoutToken } = record;
+    atomicWrite(this.#filePath, {
+      ...withoutToken,
+      scopes: [],
+      status: 'token_stale',
+    }, this.#lockPath);
+  }
+
+
+  markPairingPending(requestId) {
+    const record = this.#load();
+    atomicWrite(this.#filePath, {
+      ...record,
+      status: 'pairing_pending',
+      requestId,
+    }, this.#lockPath);
+  }
+}
+
+export function createWorkstationOpenClawAdapterConfig(env = process.env) {
+  const stateDir = env.OPENCLAW_STATE_DIR || '/home/node/.openclaw';
+  const port = Number(env.OPENCLAW_GATEWAY_PORT || 18789);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error('OPENCLAW_GATEWAY_PORT must be a valid TCP port');
+  }
+  const gatewayUrl = `ws://127.0.0.1:${port}`;
+  const gatewayOrigin = `http://127.0.0.1:${port}`;
+  const deviceAuthStore = new WorkstationOpenClawDeviceStore({ stateDir, gatewayOrigin });
+  deviceAuthStore.loadOrCreateIdentity();
+  return {
+    mode: 'gateway',
+    hostKind: 'workstation',
+    gatewayUrl,
+    gatewayOrigin,
+    deviceAuthStore,
+  };
+}

package/src/openclaw-pair-workstation.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
+import {
+  WorkstationOpenClawDeviceStore,
+  encodeOpenClawPublicKey,
+  fingerprintOpenClawPublicKey,
+} from './openclaw-device-store.mjs';
+
+const SDK_PATH = process.env.WINMATRIX_AGENT_SDK_PATH
+  || '/home/node/.local/lib/node_modules/@winmatrix/agent-sdk';
+
+function readArg(argv, name) {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1]?.trim() : undefined;
+}
+
+export function decodeSetupCode(setupCode) {
+  if (typeof setupCode !== 'string' || !setupCode) throw new Error('OpenClaw setup code is missing');
+  const payload = JSON.parse(Buffer.from(setupCode, 'base64url').toString('utf8'));
+  if (!payload || typeof payload.bootstrapToken !== 'string' || !payload.bootstrapToken.trim()) {
+    throw new Error('OpenClaw setup code does not contain a bootstrap credential');
+  }
+  return payload;
+}
+
+function resolvePairingContext(input) {
+  const expectedWorkstationId = input.workstationId?.trim();
+  const env = input.env ?? process.env;
+  const actualWorkstationId = env.WINMATRIX_WORKSTATION_ID?.trim();
+  if (!expectedWorkstationId || actualWorkstationId !== expectedWorkstationId) {
+    throw new Error('OpenClaw pairing workstation identity mismatch');
+  }
+  const port = Number(env.OPENCLAW_GATEWAY_PORT || 18789);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error('OPENCLAW_GATEWAY_PORT must be a valid TCP port');
+  }
+  return {
+    expectedWorkstationId,
+    env,
+    gatewayUrl: `ws://127.0.0.1:${port}`,
+  };
+}
+
+export async function issueOpenClawBootstrap(input, deps = {}) {
+  const context = resolvePairingContext(input);
+  const cliJson = deps.runJson ?? ((args) => runJson('openclaw', args, { env: context.env }));
+  const qr = await cliJson(['qr', '--json', '--url', context.gatewayUrl]);
+  const setup = decodeSetupCode(qr.setupCode);
+  return { bootstrapToken: setup.bootstrapToken.trim() };
+}
+
+export async function approveOpenClawPairing(input, deps = {}) {
+  const context = resolvePairingContext(input);
+  const requestId = input.requestId?.trim();
+  const deviceId = input.deviceId?.trim();
+  const publicKey = input.publicKey?.trim();
+  if (!requestId || !deviceId || !publicKey) {
+    throw new Error('OpenClaw pairing approval identity is incomplete');
+  }
+  const cliJson = deps.runJson ?? ((args) => runJson('openclaw', args, { env: context.env }));
+  const listed = await cliJson(['devices', 'list', '--json']);
+  const pending = Array.isArray(listed?.pending) ? listed.pending : [];
+  const exact = pending.find((item) => item?.requestId === requestId);
+  if (!exact || exact.deviceId !== deviceId || exact.publicKey !== publicKey) {
+    throw new Error('OpenClaw pending pairing request identity mismatch');
+  }
+  await cliJson(['devices', 'approve', requestId, '--json']);
+  return { approved: true, requestId, deviceId };
+}
+
+function runJson(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      env: options.env ?? process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on('data', (chunk) => stdout.push(chunk));
+    child.stderr.on('data', (chunk) => stderr.push(chunk));
+    child.once('error', () => reject(new Error(`OpenClaw command unavailable: ${args[0] ?? command}`)));
+    child.once('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(`OpenClaw command failed: ${args.slice(0, 2).join(' ')}`));
+        return;
+      }
+      try {
+        resolve(JSON.parse(Buffer.concat(stdout).toString('utf8')));
+      } catch {
+        reject(new Error('OpenClaw command returned invalid JSON'));
+      }
+      void stderr;
+    });
+  });
+}
+
+function createBootstrapProvider(value) {
+  let credential = value;
+  return {
+    readOnce: async () => credential,
+    clear: async () => { credential = ''; },
+  };
+}
+
+export async function pairOpenClawWorkstation(input, deps = {}) {
+  const context = resolvePairingContext(input);
+  const { expectedWorkstationId, env, gatewayUrl } = context;
+  const stateDir = env.OPENCLAW_STATE_DIR || '/home/node/.openclaw';
+  const port = Number(env.OPENCLAW_GATEWAY_PORT || 18789);
+  const gatewayOrigin = `http://127.0.0.1:${port}`;
+  const store = deps.store ?? new WorkstationOpenClawDeviceStore({ stateDir, gatewayOrigin });
+  const identity = store.loadOrCreateIdentity();
+  const expectedPublicKey = encodeOpenClawPublicKey(identity.publicKeyPem);
+  const publicKeyFingerprint = fingerprintOpenClawPublicKey(identity.publicKeyPem);
+  const cliJson = deps.runJson ?? ((args) => runJson('openclaw', args, { env }));
+  const provision = deps.provisionGatewayDevice ?? (await import(
+    pathToFileURL(join(SDK_PATH, 'dist', 'index.js')).href
+  )).provisionGatewayDevice;
+
+  let bootstrapToken = '';
+  try {
+    const qr = await cliJson(['qr', '--json', '--url', gatewayUrl]);
+    const setup = decodeSetupCode(qr.setupCode);
+    bootstrapToken = setup.bootstrapToken.trim();
+    let result = await provision({
+      gatewayUrl,
+      gatewayOrigin,
+      deviceAuthStore: store,
+      bootstrapProvider: createBootstrapProvider(bootstrapToken),
+      timeoutMs: 30_000,
+    });
+    if (result.status === 'pairing_pending') {
+      const listed = await cliJson(['devices', 'list', '--json']);
+      const pending = Array.isArray(listed?.pending) ? listed.pending : [];
+      const exact = pending.find((item) => item?.requestId === result.requestId);
+      if (!exact || exact.deviceId !== identity.deviceId || exact.publicKey !== expectedPublicKey) {
+        throw new Error('OpenClaw pending pairing request identity mismatch');
+      }
+      store.markPairingPending?.(result.requestId);
+      await cliJson(['devices', 'approve', result.requestId, '--json']);
+      result = await provision({
+        gatewayUrl,
+        gatewayOrigin,
+        deviceAuthStore: store,
+        bootstrapProvider: createBootstrapProvider(bootstrapToken),
+        timeoutMs: 30_000,
+      });
+    }
+    if (result.status !== 'paired' || result.deviceId !== identity.deviceId) {
+      throw new Error(`OpenClaw pairing did not complete: ${result.reasonCode ?? result.status}`);
+    }
+    return {
+      paired: true,
+      workstationId: expectedWorkstationId,
+      deviceId: result.deviceId,
+      role: result.role,
+      scopes: [...result.scopes],
+      publicKeyFingerprint,
+    };
+  } finally {
+    bootstrapToken = '';
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const command = argv[0]?.startsWith('--') ? 'pair' : argv[0] ?? 'pair';
+  const workstationId = readArg(argv, '--workstation-id');
+  let result;
+  if (command === 'bootstrap') {
+    result = await issueOpenClawBootstrap({ workstationId });
+  } else if (command === 'approve') {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    const approval = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    result = await approveOpenClawPairing({ workstationId, ...approval });
+  } else {
+    result = await pairOpenClawWorkstation({ workstationId });
+  }
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : 'OpenClaw pairing failed'}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/run-agent-engine.mjs

@@ -72,6 +72,7 @@ if (!SUPERVISOR_ROOT) {
 }
 const CALLBACK_TIMEOUT_MS = Number(process.env.WINMATRIX_CALLBACK_TIMEOUT_MS) || 5000;
 const MAX_ACTIVE_RUNS = Number(process.env.WINMATRIX_MAX_ACTIVE_RUNS) || 100;
+const LAUNCH_ACK_TIMEOUT_MS = Number(process.env.WINMATRIX_LAUNCH_ACK_TIMEOUT_MS) || 10_000;
 /** 单次 events 请求返回的最大事件数，避免大量事件堆积导致响应超限。 */
 const MAX_EVENTS_PAGE_SIZE = 500;
 
@@ -92,7 +93,27 @@ function saveActiveRuns() {
     runKey,
     metadata,
   }));
-  fs.writeFileSync(activeRunsFile, JSON.stringify(data, null, 2), 'utf8');
+  atomicWriteFile(activeRunsFile, JSON.stringify(data, null, 2));
+}
+
+function atomicWriteFile(filePath, content) {
+  const tempPath = `${filePath}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`;
+  fs.writeFileSync(tempPath, content, 'utf8');
+  try {
+    fs.renameSync(tempPath, filePath);
+  } finally {
+    try { fs.rmSync(tempPath, { force: true }); } catch { /* best effort */ }
+  }
+}
+
+function atomicCreateExclusive(filePath, content) {
+  const tempPath = `${filePath}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`;
+  fs.writeFileSync(tempPath, content, { encoding: 'utf8', mode: 0o600 });
+  try {
+    fs.linkSync(tempPath, filePath);
+  } finally {
+    try { fs.rmSync(tempPath, { force: true }); } catch { /* best effort */ }
+  }
 }
 
 /**
@@ -199,7 +220,7 @@ function saveRunMetadata(runKey, metadata) {
     fs.mkdirSync(runDir, { recursive: true });
   }
   const statusFile = path.join(runDir, 'status.json');
-  fs.writeFileSync(statusFile, JSON.stringify(metadata, null, 2), 'utf8');
+  atomicWriteFile(statusFile, JSON.stringify(metadata, null, 2));
 }
 
 /**
@@ -232,7 +253,7 @@ function saveResult(runKey, result) {
     fs.mkdirSync(runDir, { recursive: true });
   }
   const resultFile = path.join(runDir, 'result.json');
-  fs.writeFileSync(resultFile, JSON.stringify(result, null, 2), 'utf8');
+  atomicWriteFile(resultFile, JSON.stringify(result, null, 2));
 }
 
 /**
@@ -291,7 +312,7 @@ function hasCancelMarker(runKey) {
  * @param {RunMetadata} startMetadata - 启动元数据（startTime）
  * @returns {object} Callback payload
  */
-function buildTerminalCallbackPayload(runKey, endMetadata, result, startMetadata) {
+function buildTerminalCallbackPayload(runKey, endMetadata, result, startMetadata) {
   const sep = runKey.lastIndexOf(':');
   const recordId = sep > 0 ? runKey.slice(0, sep) : runKey;
   const parsedAttempt = sep > 0 ? Number(runKey.slice(sep + 1)) : NaN;
@@ -304,8 +325,10 @@ function buildTerminalCallbackPayload(runKey, endMetadata, result, startMetadata
     ? Math.round((endMs - startMs) / 1000)
     : undefined;
 
-  const text = typeof result?.text === 'string' ? result.text : undefined;
-  return {
+  const text = typeof result?.text === 'string' ? result.text : undefined;
+  const engineId = typeof startMetadata?.engineId === 'string' ? startMetadata.engineId : undefined;
+  const engineSessionId = typeof result?.sessionId === 'string' ? result.sessionId : undefined;
+  return {
     recordId,
     attemptNo,
     runKey,
@@ -314,7 +337,7 @@ function buildTerminalCallbackPayload(runKey, endMetadata, result, startMetadata
     result: text,
     error: typeof result?.error === 'string' ? result.error : undefined,
     durationSeconds,
-    claudeSessionId: typeof result?.sessionId === 'string' ? result.sessionId : undefined,
+    claudeSessionId: engineId === 'claude-code' ? engineSessionId : undefined,
     statusFilePath: path.join(runDir, 'status.json'),
     resultFilePath: path.join(runDir, 'result.json'),
     completedAt: endMetadata.endTime,
@@ -322,10 +345,13 @@ function buildTerminalCallbackPayload(runKey, endMetadata, result, startMetadata
       exitCode: endMetadata.exitCode,
       ...(endMetadata.signal ? { signal: endMetadata.signal } : {}),
       ...(endMetadata.resumeDegraded ? { resumeDegraded: true } : {}),
-      ...(result?.usage ? { usage: result.usage } : {}),
-    },
-  };
-}
+      ...(result?.usage ? { usage: result.usage } : {}),
+      ...(engineId && engineId !== 'claude-code' && engineSessionId
+        ? { agentEngine: { engineId, sessionId: engineSessionId } }
+        : {}),
+    },
+  };
+}
 
 /** 重定向最大跳数，防重定向环。 */
 const MAX_CALLBACK_REDIRECTS = 5;
@@ -533,6 +559,10 @@ async function runOwned(payload) {
     instanceId: payload.instanceId,
     lastSequence: 0,
   };
+  const testStartDelayMs = Number(process.env.WINMATRIX_AGENT_ENGINE_TEST_START_DELAY_MS) || 0;
+  if (testStartDelayMs > 0) {
+    await new Promise((resolve) => setTimeout(resolve, testStartDelayMs));
+  }
   saveRunMetadata(runKey, metadata);
   activeRuns.set(runKey, { child, metadata });
   saveActiveRuns();
@@ -798,7 +828,7 @@ function buildRunAck(payload, disposition) {
   };
 }
 
-async function launch(payload) {
+async function launch(payload, retryCount = 0) {
   const { runKey, invocationFingerprint, launchSpec, instanceId } = payload;
   if (!runKey || !invocationFingerprint || !launchSpec || !instanceId) {
     throw new Error('Missing required fields: runKey, invocationFingerprint, launchSpec, instanceId');
@@ -817,8 +847,32 @@ async function launch(payload) {
   }
 
   const claimFile = path.join(SUPERVISOR_ROOT, `${runKey.replace(/:/g, '_')}.launch`);
+  const readClaim = () => {
+    let raw;
+    try {
+      raw = fs.readFileSync(claimFile, 'utf8');
+    } catch (error) {
+      if (error?.code === 'ENOENT') return null;
+      throw error;
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      return { fingerprint: parsed.fingerprint, ownerPid: parsed.ownerPid };
+    } catch {
+      return { fingerprint: raw.trim(), ownerPid: undefined };
+    }
+  };
+  const isPidAlive = (pid) => {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  };
   const waitForClaimedRun = async () => {
-    const deadline = Date.now() + 2_000;
+    const deadline = Date.now() + LAUNCH_ACK_TIMEOUT_MS;
     while (Date.now() < deadline) {
       const metadata = loadRunMetadata(runKey);
       if (metadata) {
@@ -828,24 +882,44 @@ async function launch(payload) {
         return metadata;
       }
       if (!fs.existsSync(claimFile)) break;
+      const claim = readClaim();
+      if (!claim) continue;
+      const ownerPid = claim.ownerPid;
+      if (ownerPid && !isPidAlive(ownerPid)) {
+        fs.rmSync(claimFile, { force: true });
+        break;
+      }
       await new Promise((resolve) => setTimeout(resolve, 20));
     }
-    throw new Error(`Claimed run did not start: ${runKey}`);
+    throw new Error(`Launch ack timeout: runKey=${runKey} code=launch_ack_timeout`);
   };
-  let claim;
   try {
-    claim = fs.openSync(claimFile, 'wx', 0o600);
-    fs.writeFileSync(claim, invocationFingerprint, 'utf8');
+    atomicCreateExclusive(claimFile, JSON.stringify({
+      fingerprint: invocationFingerprint,
+      ownerPid: process.pid,
+      createdAt: new Date().toISOString(),
+    }));
   } catch (error) {
     if (error?.code !== 'EEXIST') throw error;
-    const claimedFingerprint = fs.readFileSync(claimFile, 'utf8');
+    const claimed = readClaim();
+    if (!claimed) {
+      if (retryCount < 1) return launch(payload, retryCount + 1);
+      throw new Error(`Launch claim disappeared: runKey=${runKey}`);
+    }
+    const claimedFingerprint = claimed.fingerprint;
     if (claimedFingerprint !== invocationFingerprint) {
       throw new Error(`Fingerprint mismatch for runKey=${runKey}`);
     }
-    await waitForClaimedRun();
-    return buildRunAck(payload, 'existing');
-  } finally {
-    if (claim !== undefined) fs.closeSync(claim);
+    try {
+      await waitForClaimedRun();
+      return buildRunAck(payload, 'existing');
+    } catch (waitError) {
+      if (String(waitError?.message ?? '').includes('launch_ack_timeout') && !fs.existsSync(claimFile)) {
+        if (retryCount < 1) return launch(payload, retryCount + 1);
+        throw waitError;
+      }
+      throw waitError;
+    }
   }
 
   if (process.env.WINMATRIX_AGENT_ENGINE_TEST_INLINE === 'true') {
@@ -860,20 +934,41 @@ async function launch(payload) {
 
   const worker = spawn(process.execPath, [SCRIPT_PATH, 'supervise-run'], {
     detached: true,
-    stdio: ['pipe', 'ignore', 'ignore'],
+    stdio: ['pipe', 'ignore', fs.openSync(path.join(SUPERVISOR_ROOT, `${runKey.replace(/:/g, '_')}.worker.log`), 'a')],
     env: process.env,
   });
+  atomicWriteFile(claimFile, JSON.stringify({
+    fingerprint: invocationFingerprint,
+    ownerPid: worker.pid,
+    createdAt: new Date().toISOString(),
+  }));
+  let workerExited = false;
+  let workerExitCode;
+  let workerSignal;
+  let workerError;
+  worker.once('error', (error) => {
+    workerError = error;
+  });
+  worker.once('exit', (code, signal) => {
+    workerExited = true;
+    workerExitCode = code;
+    workerSignal = signal;
+  });
   worker.stdin.end(JSON.stringify(payload));
   worker.unref();
-  const deadline = Date.now() + 2_000;
-  while (!loadRunMetadata(runKey) && Date.now() < deadline) {
+  const deadline = Date.now() + LAUNCH_ACK_TIMEOUT_MS;
+  while (!loadRunMetadata(runKey) && !workerExited && !workerError && Date.now() < deadline) {
     await new Promise((resolve) => setTimeout(resolve, 20));
   }
-  if (!loadRunMetadata(runKey)) {
+  if (loadRunMetadata(runKey)) {
+    return buildRunAck(payload, 'accepted');
+  }
+  if (workerError || workerExited) {
     fs.rmSync(claimFile, { force: true });
-    throw new Error(`Run worker failed to start: ${runKey}`);
+    const detail = workerError?.message ?? `exitCode=${workerExitCode ?? 'null'} signal=${workerSignal ?? 'none'}`;
+    throw new Error(`Run worker failed to start: runKey=${runKey} code=worker_start_failed ${detail}; log=${path.join(SUPERVISOR_ROOT, `${runKey.replace(/:/g, '_')}.worker.log`)}`);
   }
-  return buildRunAck(payload, 'accepted');
+  throw new Error(`Launch ack timeout: runKey=${runKey} code=launch_ack_timeout workerPid=${worker.pid ?? 'unknown'}`);
 }
 
 function listEvents(runKey, afterSequence = 0) {

package/src/run-engine.mjs

@@ -15,6 +15,7 @@
  */
 import { createRequire } from 'node:module';
 import { isSdkFailureSubtype } from './engine-run-success.mjs';
+import { createWorkstationOpenClawAdapterConfig } from './openclaw-device-store.mjs';
 
 const require = createRequire(import.meta.url);
 
@@ -201,7 +202,12 @@ async function main() {
     process.exit(1);
   }
 
-  const adapterConfig = mcpBinding.binding ? { mcpBridgeUrl: mcpBinding.binding.url } : {};
+  const adapterConfig = options.engineId === 'openclaw'
+    ? {
+        ...createWorkstationOpenClawAdapterConfig(),
+        ...(mcpBinding.binding ? { mcpBridgeUrl: mcpBinding.binding.url } : {}),
+      }
+    : (mcpBinding.binding ? { mcpBridgeUrl: mcpBinding.binding.url } : {});
   const adapter = registry.create(options.engineId, adapterConfig);
 
   /** @type {import('@winmatrix/agent-sdk').AgentTaskContext} */