@winmatrix/supervisor 1.0.5 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winmatrix/supervisor",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "type": "module",
   "main": "src/run-agent-engine.mjs",
   "bin": {
@@ -14,10 +14,6 @@
     "build": "node -e \"console.log('no build step')\"",
     "test": "node --test tests/**/*.test.mjs"
   },
-  "dependencies": {
-    "@winmatrix/agent-sdk": "^1.0.5",
-    "@winmatrix/protocol": "^1.0.5"
-  },
   "engines": {
     "node": ">=20"
   }

package/src/claude-session-lib.mjs

@@ -15,6 +15,7 @@ import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
 
 export const TRUNCATE_LEN = 4096;
+export const SESSION_DETAIL_TRANSPORT_MAX_BYTES = 48 * 1024;
 export const REDACTED = '[REDACTED]';
 export const SENSITIVE_KEY_PATTERN =
   /(authorization|password|passwd|pwd|secret|token|api[_-]?key|apikey|access[_-]?key|private[_-]?key|credential|session[_-]?key|jwt)/i;
@@ -326,6 +327,89 @@ export function previewValue(value, max = 1000) {
   return text.length > max ? text.slice(0, max) + `…[${text.length - max} chars]` : text;
 }
 
+/**
+ * 将 session-get 结果压缩到 Sandbox exec 的安全传输预算内，避免 stdout 截断后产生非法 JSON。
+ * @param {Record<string, unknown>} detail
+ * @param {number} maxBytes
+ * @returns {Record<string, unknown>}
+ */
+export function compactSessionDetailForTransport(detail, maxBytes = SESSION_DETAIL_TRANSPORT_MAX_BYTES) {
+  const serializedBytes = (value) => Buffer.byteLength(JSON.stringify(value));
+  if (serializedBytes(detail) <= maxBytes) return detail;
+
+  const compacted = {
+    ...detail,
+    messages: Array.isArray(detail.messages)
+      ? detail.messages.map((message) => ({
+        ...message,
+        content: Array.isArray(message.content)
+          ? message.content.map((block) => ({
+            ...block,
+            ...(typeof block.text === 'string' && block.text.length > 1200
+              ? { text: `${block.text.slice(0, 1200)}…[transport-truncated]` }
+              : {}),
+          }))
+          : message.content,
+      }))
+      : [],
+    metadata: detail.metadata && typeof detail.metadata === 'object'
+      ? {
+        ...detail.metadata,
+        ...(typeof detail.metadata.assistantText === 'string'
+          ? { assistantText: detail.metadata.assistantText.slice(0, 8000) }
+          : {}),
+        ...(Array.isArray(detail.metadata.userPrompts)
+          ? { userPrompts: detail.metadata.userPrompts.slice(-20).map((prompt) => (
+            typeof prompt === 'string' && prompt.length > 800
+              ? `${prompt.slice(0, 800)}…[transport-truncated]`
+              : prompt
+          )) }
+          : {}),
+        ...(detail.metadata.diagnostics && typeof detail.metadata.diagnostics === 'object'
+          ? {
+            diagnostics: {
+              ...detail.metadata.diagnostics,
+              ...(Array.isArray(detail.metadata.diagnostics.toolCalls)
+                ? { toolCalls: detail.metadata.diagnostics.toolCalls.slice(-20) }
+                : {}),
+              ...(Array.isArray(detail.metadata.diagnostics.toolResults)
+                ? { toolResults: detail.metadata.diagnostics.toolResults.slice(-20) }
+                : {}),
+              ...(Array.isArray(detail.metadata.diagnostics.timeline)
+                ? { timeline: detail.metadata.diagnostics.timeline.slice(-40) }
+                : {}),
+            },
+          }
+          : {}),
+        ...(Array.isArray(detail.metadata.rawMessages) ? { rawMessages: undefined, rawMessagesIncluded: false } : {}),
+        transportCompacted: true,
+      }
+      : detail.metadata,
+  };
+
+  if (serializedBytes(compacted) <= maxBytes) return compacted;
+
+  const minimal = {
+    ...compacted,
+    messages: [],
+    metadata: compacted.metadata && typeof compacted.metadata === 'object'
+      ? {
+        ...compacted.metadata,
+        assistantText: typeof compacted.metadata.assistantText === 'string'
+          ? compacted.metadata.assistantText.slice(0, 4000)
+          : compacted.metadata.assistantText,
+        userPrompts: Array.isArray(compacted.metadata.userPrompts)
+          ? compacted.metadata.userPrompts.map((prompt) => (
+            typeof prompt === 'string' ? prompt.slice(0, 800) : prompt
+          ))
+          : compacted.metadata.userPrompts,
+        diagnostics: undefined,
+      }
+      : compacted.metadata,
+  };
+  return minimal;
+}
+
 /** @param {string} text */
 export function redactPreviewText(text) {
   return text

package/src/engine-run-success.mjs

@@ -0,0 +1,118 @@
+/**
+ * 工作站引擎终态成败：不得只看进程 exitCode。
+ *
+ * recover-workstation-context-overflow D2：SDK result 帧 `is_error` /
+ * 失败 `subtype`（至少 error_during_execution / error_max_turns）须写成失败，
+ * 失败原因进 error，可见正文仍保留。缺字段时回退 exitCode（旧镜像靠 server P0 短语）。
+ */
+
+/** @type {ReadonlySet<string>} */
+export const SDK_FAILURE_SUBTYPES = Object.freeze(new Set([
+  'error_during_execution',
+  'error_max_turns',
+]));
+
+/**
+ * @param {unknown} subtype
+ * @returns {subtype is string}
+ */
+export function isSdkFailureSubtype(subtype) {
+  return typeof subtype === 'string' && SDK_FAILURE_SUBTYPES.has(subtype);
+}
+
+/**
+ * 从 events.jsonl 条目（envelope 或裸事件）提取最后一条 result 上的 SDK 成败信号。
+ *
+ * @param {unknown[]} events
+ * @returns {{
+ *   isError: boolean,
+ *   subtype: string | undefined,
+ *   visibleText: string | undefined,
+ *   error: string | undefined,
+ *   sessionId: string | undefined,
+ * }}
+ */
+export function extractSdkResultSignals(events) {
+  const empty = {
+    isError: false,
+    subtype: undefined,
+    visibleText: undefined,
+    error: undefined,
+    sessionId: undefined,
+  };
+  if (!Array.isArray(events)) return empty;
+
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const raw = events[i];
+    const evt = raw && typeof raw === 'object' && raw.event && typeof raw.event === 'object'
+      ? raw.event
+      : raw;
+    if (!evt || typeof evt !== 'object' || evt.type !== 'result') continue;
+
+    const payload = evt.result && typeof evt.result === 'object' && !Array.isArray(evt.result)
+      ? evt.result
+      : evt;
+
+    const isError = payload.is_error === true || payload.isError === true;
+    const subtype = typeof payload.subtype === 'string'
+      ? payload.subtype
+      : typeof payload.sdkSubtype === 'string'
+        ? payload.sdkSubtype
+        : undefined;
+    const visibleText = typeof payload.text === 'string'
+      ? payload.text
+      : typeof payload.content === 'string'
+        ? payload.content
+        : undefined;
+    const error = typeof payload.error === 'string' ? payload.error : undefined;
+    const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : undefined;
+
+    return { isError, subtype, visibleText, error, sessionId };
+  }
+
+  return empty;
+}
+
+/**
+ * @param {object} input
+ * @param {boolean} [input.cancelled]
+ * @param {number | null | undefined} [input.exitCode]
+ * @param {boolean} [input.isError]
+ * @param {string} [input.subtype]
+ * @param {string} [input.visibleText]
+ * @param {string} [input.existingError]
+ * @returns {{ success: boolean, status: 'cancelled' | 'completed' | 'failed', error?: string }}
+ */
+export function resolveEngineRunOutcome({
+  cancelled = false,
+  exitCode,
+  isError = false,
+  subtype,
+  visibleText,
+  existingError,
+} = {}) {
+  if (cancelled) {
+    return { success: false, status: 'cancelled', error: 'cancelled' };
+  }
+
+  const sdkFailed = isError === true || isSdkFailureSubtype(subtype);
+  if (sdkFailed) {
+    const trimmedVisible = typeof visibleText === 'string' ? visibleText.trim() : '';
+    const trimmedExisting = typeof existingError === 'string' ? existingError.trim() : '';
+    const error = trimmedExisting
+      || trimmedVisible
+      || (isSdkFailureSubtype(subtype) ? `SDK result subtype=${subtype}` : 'SDK result is_error=true');
+    return { success: false, status: 'failed', error };
+  }
+
+  if (exitCode !== 0) {
+    const trimmedExisting = typeof existingError === 'string' ? existingError.trim() : '';
+    return {
+      success: false,
+      status: 'failed',
+      error: trimmedExisting || `Engine exited with code ${exitCode}`,
+    };
+  }
+
+  return { success: true, status: 'completed' };
+}

package/src/env-sanitizer.mjs

@@ -69,6 +69,10 @@ export function isFilteredEnvKey(key) {
   // 精确匹配的过滤项（优先级最高）
   if (FILTERED_EXACT_KEYS.has(key)) return true;
 
+  // Pod 创建时注入的 Claude 持久根目录必须和 HOME 一起传给 Engine。
+  // 其余 CLAUDE_CODE_* 仍按下方规则过滤，避免 Supervisor 内部标记泄漏。
+  if (/^CLAUDE_CODE_HOME$/i.test(key)) return false;
+
   // 先检查是否匹配过滤模式（过滤优先于白名单）
   // 这样 CLAUDE_CODE_ENTRYPOINT 被过滤，即使 CLAUDE_ 在白名单中
   for (const pattern of FILTERED_ENV_PATTERNS) {

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;
+  });
+}