oomi-ai 0.2.42 → 0.2.47

package/bin/oomi-ai.js

@@ -14,35 +14,37 @@ import { startPersonaJobPoller } from '../lib/personaJobPoller.js';
 import { startPersonaRuntimeSupervisor } from '../lib/personaRuntimeSupervisor.js';
 import { executePersonaJob, extractPersonaJobPayload } from '../lib/personaJobExecutor.js';
 import { inferSpokenMetadataFromContent, normalizeSpokenMetadata } from '../lib/spokenMetadata.js';
-import {
-  resolveOpenclawBridgeLiveLogPath,
-  resolveOpenclawBridgeLockPath,
-  resolveOpenclawBridgeStatePath,
-  resolveOpenclawBridgeStatusPath,
-  resolveOpenclawConfigCandidates,
-  resolveOpenclawHome,
-  resolveOpenclawIdentityPath,
-  resolveOpenclawProfilePath,
-  resolveOpenclawSkillsDir,
-  resolveOpenclawUpdateStatePath,
-  resolveOpenclawWorkspaceRoot,
-} from '../lib/openclawPaths.js';
+import {
+  resolveOpenclawBridgeLiveLogPath,
+  resolveOpenclawBridgeLockPath,
+  resolveOpenclawBridgeStatePath,
+  resolveOpenclawBridgeStatusPath,
+  resolveOpenclawConfigCandidates,
+  resolveOpenclawHome,
+  resolveOpenclawIdentityPath,
+  resolveOpenclawLegacyPersonasDir,
+  resolveOpenclawProfilePath,
+  resolveOpenclawSkillsDir,
+  resolveOpenclawUpdateStatePath,
+  resolveOpenclawWorkspaceRoot,
+} from '../lib/openclawPaths.js';
 import {
   applyOpenclawProfile,
   buildOomiDevLocalProfile,
   readOpenclawProfile,
   writeOpenclawProfile,
 } from '../lib/openclawProfile.js';
-import {
-  buildLocalPersonaRuntime,
-  defaultPersonaWorkspaceRoot,
-  installPersonaWorkspace,
-  isPersonaWorkspaceProcessRunning,
-  resolvePersonaDevCommand,
-  startPersonaWorkspace,
-  stopPersonaWorkspace,
-  waitForPersonaRuntime,
-} from '../lib/personaRuntimeProcess.js';
+import {
+  buildLocalPersonaRuntime,
+  defaultPersonaWorkspaceRoot,
+  installPersonaWorkspace,
+  isPersonaWorkspaceProcessRunning,
+  resolvePersonaHealthPath,
+  resolvePersonaDevCommand,
+  startPersonaWorkspace,
+  stopPersonaWorkspace,
+  waitForPersonaRuntime,
+} from '../lib/personaRuntimeProcess.js';
 import {
   destroyManagedPersonaRuntime,
   getManagedPersonaRuntimeStatus,
@@ -50,13 +52,17 @@ import {
   slugifyPersonaName,
   stopManagedPersonaRuntime,
 } from '../lib/personaRuntimeManager.js';
+import {
+  readPersonaRuntimeState,
+  resolvePersonaWorkspacePath,
+} from '../lib/personaRuntimeRegistry.js';
 import { startLocalGatewayAgentServer } from '../lib/openclawDevGateway.js';
 import { ensureSessionBridge, flushSessionQueue, flushWaitingForConnect, forwardFrameToSession } from './sessionBridgeState.js';
 
 const MARKER_START = '<oomi-agent-instructions>';
 const MARKER_END = '</oomi-agent-instructions>';
 
-const PACKAGE_ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const UPDATE_STATE_FILE = resolveOpenclawUpdateStatePath();
 const DEFAULT_UPDATE_CHECK_INTERVAL_MS = 12 * 60 * 60 * 1000;
 const DEFAULT_UPDATE_CHECK_TIMEOUT_MS = 1200;
@@ -231,10 +237,12 @@ Commands:
     Replay an assistant chat.final frame through spoken-metadata normalization.
   openclaw debug tts-pipeline
     Replay an assistant chat.final through local backend voice handling.
-  openclaw debug local-gateway-agent
-    Run a tiny local OpenClaw gateway/agent for Docker dev testing.
-  openclaw debug persona-runtime
-    Scaffold, launch, and stop a managed persona runtime locally.
+  openclaw debug local-gateway-agent
+    Run a tiny local OpenClaw gateway/agent for Docker dev testing.
+  openclaw debug persona-runtime
+    Scaffold, launch, and stop a managed persona runtime locally.
+  openclaw refresh
+    Restart the bridge and running managed persona runtimes after an oomi-ai update.
 
   openclaw pair
     Pair this OpenClaw host with Oomi and start bridge (single command).
@@ -320,18 +328,20 @@ Common flags:
   --out PATH             Output directory for scaffolded persona app
   --template-version V   Scaffold template version (default: v1)
   --force                Overwrite files in an existing output directory
-  --force-install        Reinstall persona workspace dependencies before launch
-  --no-sync              Skip backend sync (for create)
-  --no-create            Do not create a managed persona record if one does not already exist
+  --force-install        Reinstall persona workspace dependencies before launch
+  --include-stopped      Relaunch managed persona runtimes even if not currently marked running
+  --no-sync              Skip backend sync (for create)
+  --no-create            Do not create a managed persona record if one does not already exist
   --local-port N         Local runtime port for persona runtime callbacks
   --endpoint URL         Runtime endpoint for persona runtime callbacks
   --entry-url URL        Viewer URL to register for a launched persona runtime
-  --health-path PATH     Runtime health path (default: /oomi.health.json)
+  --health-path PATH     Runtime health path override (default: workspace-specific)
   --healthcheck-url URL  Runtime healthcheck URL override
-  --transport TEXT       Runtime transport label (default: local, relay when --entry-url is used)
+  --transport TEXT       Runtime transport label (default: local, relay when --entry-url is used)
   --workspace-root PATH  Persona workspace root (default: OPENCLAW_WORKSPACE/personas)
-  --restart              Restart an existing managed persona runtime before launch
-  --started-at ISO       Start timestamp override
+  --restart              Restart an existing managed persona runtime before launch
+  --skip-version-check   Skip checking npm for the latest oomi-ai version during refresh
+  --started-at ISO       Start timestamp override
   --observed-at ISO      Heartbeat timestamp override
   --completed-at ISO     Completion timestamp override
   --code TEXT            Error code for fail callbacks
@@ -829,16 +839,183 @@ function resolvePersonaEntryUrl(flags = {}) {
   return String(flags['entry-url'] || '').trim();
 }
 
-function resolvePersonaLaunchTransport(flags = {}) {
-  const explicitTransport = String(flags.transport || '').trim();
-  if (explicitTransport) {
-    return explicitTransport;
-  }
-
-  return resolvePersonaEntryUrl(flags) ? 'relay' : 'local';
-}
-
-async function findExistingManagedPersona(client, slug) {
+function resolvePersonaLaunchTransport(flags = {}) {
+  const explicitTransport = String(flags.transport || '').trim();
+  if (explicitTransport) {
+    return explicitTransport;
+  }
+
+  return resolvePersonaEntryUrl(flags) ? 'relay' : 'local';
+}
+
+function listPersonaWorkspaceRoots(workspaceRoot = defaultPersonaWorkspaceRoot()) {
+  const roots = [
+    String(workspaceRoot || '').trim(),
+    String(resolveOpenclawLegacyPersonasDir() || '').trim(),
+  ].filter(Boolean);
+
+  const deduped = [];
+  const seen = new Set();
+  for (const root of roots) {
+    const resolved = path.resolve(root);
+    if (seen.has(resolved) || !fs.existsSync(resolved)) {
+      continue;
+    }
+    seen.add(resolved);
+    deduped.push(resolved);
+  }
+
+  return deduped;
+}
+
+function collectManagedPersonaRefreshTargets({
+  workspaceRoot = defaultPersonaWorkspaceRoot(),
+  includeStopped = false,
+} = {}) {
+  const targets = [];
+  const seenWorkspacePaths = new Set();
+  const seenSlugs = new Set();
+
+  for (const root of listPersonaWorkspaceRoots(workspaceRoot)) {
+    const entries = fs.readdirSync(root, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) {
+        continue;
+      }
+
+      const workspacePath = path.join(root, entry.name);
+      let dedupeKey = workspacePath;
+      try {
+        dedupeKey = fs.realpathSync(workspacePath);
+      } catch {
+        dedupeKey = path.resolve(workspacePath);
+      }
+      if (seenWorkspacePaths.has(dedupeKey)) {
+        continue;
+      }
+      seenWorkspacePaths.add(dedupeKey);
+
+      const state = readPersonaRuntimeState(workspacePath);
+      if (!state || Object.keys(state).length === 0) {
+        continue;
+      }
+
+      const slug = String(state.slug || entry.name || '').trim();
+      if (!slug || seenSlugs.has(slug)) {
+        continue;
+      }
+
+      const pid = normalizePid(state.pid);
+      const processRunning = pid ? isPersonaWorkspaceProcessRunning(pid) : false;
+      const runtimeStatus = String(state.status || '').trim().toLowerCase();
+      if (!includeStopped && !processRunning && runtimeStatus !== 'running') {
+        continue;
+      }
+
+      seenSlugs.add(slug);
+      targets.push({
+        slug,
+        workspacePath,
+        state,
+        processRunning,
+      });
+    }
+  }
+
+  return targets.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+function normalizeBackendPersonaRefreshRecord(rawPersona) {
+  if (!rawPersona || typeof rawPersona !== 'object') {
+    return null;
+  }
+
+  const slug = String(
+    rawPersona.slug ||
+      rawPersona.id ||
+      rawPersona.personaId ||
+      ''
+  ).trim();
+  if (!slug) {
+    return null;
+  }
+
+  return {
+    slug,
+    name: String(rawPersona.name || slug).trim() || slug,
+    description: String(rawPersona.description || rawPersona.summary || rawPersona.name || slug).trim() || slug,
+    templateVersion: String(rawPersona.promptTemplateVersion || 'v1').trim() || 'v1',
+    templateType: String(rawPersona.templateType || '').trim(),
+  };
+}
+
+function resolveExistingWorkspacePathForSlug(slug, workspaceRoot = defaultPersonaWorkspaceRoot()) {
+  for (const root of listPersonaWorkspaceRoots(workspaceRoot)) {
+    const workspacePath = resolvePersonaWorkspacePath({
+      workspaceRoot: root,
+      slug,
+    });
+    if (fs.existsSync(workspacePath)) {
+      return workspacePath;
+    }
+  }
+  return '';
+}
+
+async function discoverBackendLinkedPersonaRefreshTargets({
+  client,
+  workspaceRoot = defaultPersonaWorkspaceRoot(),
+  existingTargets = [],
+  logger = null,
+} = {}) {
+  if (!client || typeof client.listPersonas !== 'function') {
+    return [];
+  }
+
+  const targetsBySlug = new Map(
+    Array.isArray(existingTargets)
+      ? existingTargets.map((target) => [String(target?.slug || '').trim(), target]).filter(([slug]) => slug)
+      : [],
+  );
+
+  const payload = await client.listPersonas();
+  const backendPersonas = Array.isArray(payload?.personas) ? payload.personas : [];
+  const discoveredTargets = [];
+
+  for (const rawPersona of backendPersonas) {
+    const backendPersona = normalizeBackendPersonaRefreshRecord(rawPersona);
+    if (!backendPersona || targetsBySlug.has(backendPersona.slug)) {
+      continue;
+    }
+    const workspacePath = resolveExistingWorkspacePathForSlug(backendPersona.slug, workspaceRoot);
+    if (!workspacePath) {
+      continue;
+    }
+    const state = readPersonaRuntimeState(workspacePath);
+    const target = {
+      slug: backendPersona.slug,
+      workspacePath,
+      state: {
+        ...state,
+        slug: backendPersona.slug,
+        name: backendPersona.name,
+        description: backendPersona.description,
+        templateVersion: backendPersona.templateVersion,
+      },
+      processRunning: false,
+    };
+    discoveredTargets.push(target);
+    targetsBySlug.set(backendPersona.slug, target);
+  }
+
+  if (discoveredTargets.length > 0) {
+    logger?.(`Added ${discoveredTargets.length} backend-linked persona runtime target${discoveredTargets.length === 1 ? '' : 's'} from workspace discovery.`);
+  }
+
+  return discoveredTargets;
+}
+
+async function findExistingManagedPersona(client, slug) {
   try {
     return await client.getPersona({ slug });
   } catch (error) {
@@ -1114,31 +1291,81 @@ async function runManagedPersonaJobExecution({
   }
 }
 
-function resolvePersonaRuntimeInput(flags = {}, defaults = {}) {
-  const localPort = parseOptionalPositiveInteger(flags['local-port'] || flags.localPort || defaults.localPort);
-  const endpoint = String(flags.endpoint || defaults.endpoint || '').trim();
-  const healthPath = String(flags['health-path'] || defaults.healthPath || '/oomi.health.json').trim() || '/oomi.health.json';
-  const healthcheckUrl = String(flags['healthcheck-url'] || defaults.healthcheckUrl || '').trim();
-  const transport = String(flags.transport || defaults.transport || 'local').trim() || 'local';
-
-  if (endpoint) {
-    return {
-      endpoint,
-      healthcheckUrl: healthcheckUrl || `${endpoint.replace(/\/$/, '')}${healthPath}`,
+function resolvePersonaRuntimeWorkspacePath({
+  slug = '',
+  workspacePath = '',
+  workspaceRoot = '',
+} = {}) {
+  const explicitWorkspacePath = String(workspacePath || '').trim();
+  if (explicitWorkspacePath) {
+    return path.resolve(explicitWorkspacePath);
+  }
+
+  const safeSlug = String(slug || '').trim();
+  if (!safeSlug) {
+    return '';
+  }
+
+  const safeWorkspaceRoot = String(workspaceRoot || defaultPersonaWorkspaceRoot()).trim();
+  if (!safeWorkspaceRoot) {
+    return '';
+  }
+
+  return resolvePersonaWorkspacePath({
+    workspaceRoot: safeWorkspaceRoot,
+    slug: safeSlug,
+  });
+}
+
+function resolvePersonaRuntimeInput(flags = {}, defaults = {}, options = {}) {
+  const localPort = parseOptionalPositiveInteger(flags['local-port'] || flags.localPort || defaults.localPort);
+  const endpoint = String(flags.endpoint || defaults.endpoint || '').trim();
+  const explicitHealthPath = String(flags['health-path'] || defaults.healthPath || '').trim();
+  const healthcheckUrl = String(flags['healthcheck-url'] || defaults.healthcheckUrl || '').trim();
+  const transport = String(flags.transport || defaults.transport || 'local').trim() || 'local';
+  const workspacePath = resolvePersonaRuntimeWorkspacePath({
+    slug: options.slug || defaults.slug || flags.slug,
+    workspacePath:
+      options.workspacePath ||
+      defaults.workspacePath ||
+      flags['workspace-path'] ||
+      flags.workspacePath,
+    workspaceRoot:
+      options.workspaceRoot ||
+      defaults.workspaceRoot ||
+      flags['workspace-root'] ||
+      flags.workspaceRoot,
+  });
+  const healthPath = explicitHealthPath ||
+    resolvePersonaHealthPath({
+      workspacePath,
+      fallback: '/oomi.health.json',
+    });
+
+  if (endpoint) {
+    return {
+      endpoint,
+      healthcheckUrl: healthcheckUrl || `${endpoint.replace(/\/$/, '')}${healthPath}`,
       localPort,
       transport,
     };
   }
 
-  if (!localPort) {
-    throw new Error('Runtime endpoint or local port is required.');
-  }
-
-  return buildLocalPersonaRuntime({
-    localPort,
-    healthPath,
-  });
-}
+  if (!localPort) {
+    throw new Error('Runtime endpoint or local port is required.');
+  }
+
+  const runtime = buildLocalPersonaRuntime({
+    localPort,
+    healthPath,
+  });
+
+  return {
+    ...runtime,
+    endpoint: runtime.reachableEndpoint || runtime.endpoint,
+    localEndpoint: runtime.endpoint,
+  };
+}
 
 function parseIsoTimestamp(rawValue, label) {
   const value = String(rawValue || '').trim();
@@ -1175,12 +1402,19 @@ function printStructuredResult(result, asJson = false) {
   }
 }
 
-async function handlePersonaRuntimeRegisterCommand(slug, flags = {}) {
-  const client = createCliPersonaApiClient(flags);
-  const runtime = resolvePersonaRuntimeInput(flags);
-  const payload = await client.registerRuntime({
-    slug,
-    endpoint: runtime.endpoint,
+async function handlePersonaRuntimeRegisterCommand(slug, flags = {}) {
+  const client = createCliPersonaApiClient(flags);
+  const runtime = resolvePersonaRuntimeInput(
+    flags,
+    {},
+    {
+      slug,
+      workspaceRoot: resolvePersonaWorkspaceRoot(flags),
+    },
+  );
+  const payload = await client.registerRuntime({
+    slug,
+    endpoint: runtime.endpoint,
     healthcheckUrl: runtime.healthcheckUrl,
     localPort: runtime.localPort,
     transport: runtime.transport,
@@ -1189,12 +1423,19 @@ async function handlePersonaRuntimeRegisterCommand(slug, flags = {}) {
   printStructuredResult(payload, isTruthyFlag(flags.json));
 }
 
-async function handlePersonaHeartbeatCommand(slug, flags = {}) {
-  const client = createCliPersonaApiClient(flags);
-  const runtime = resolvePersonaRuntimeInput(flags);
-  const payload = await client.heartbeatRuntime({
-    slug,
-    endpoint: runtime.endpoint,
+async function handlePersonaHeartbeatCommand(slug, flags = {}) {
+  const client = createCliPersonaApiClient(flags);
+  const runtime = resolvePersonaRuntimeInput(
+    flags,
+    {},
+    {
+      slug,
+      workspaceRoot: resolvePersonaWorkspaceRoot(flags),
+    },
+  );
+  const payload = await client.heartbeatRuntime({
+    slug,
+    endpoint: runtime.endpoint,
     healthcheckUrl: runtime.healthcheckUrl,
     localPort: runtime.localPort,
     transport: runtime.transport,
@@ -1231,16 +1472,22 @@ async function handlePersonaJobStartCommand(jobId, flags = {}) {
   printStructuredResult(payload, isTruthyFlag(flags.json));
 }
 
-async function handlePersonaJobSucceedCommand(jobId, flags = {}) {
-  const client = createCliPersonaApiClient(flags);
-  const runtime = resolvePersonaRuntimeInput(flags);
-  const workspacePath = String(flags['workspace-path'] || flags.workspacePath || '').trim();
-  if (!workspacePath) {
-    throw new Error('Workspace path is required. Use --workspace-path.');
-  }
-
-  const payload = await client.succeedJob({
-    jobId,
+async function handlePersonaJobSucceedCommand(jobId, flags = {}) {
+  const client = createCliPersonaApiClient(flags);
+  const workspacePath = String(flags['workspace-path'] || flags.workspacePath || '').trim();
+  if (!workspacePath) {
+    throw new Error('Workspace path is required. Use --workspace-path.');
+  }
+  const runtime = resolvePersonaRuntimeInput(
+    flags,
+    {},
+    {
+      workspacePath,
+    },
+  );
+
+  const payload = await client.succeedJob({
+    jobId,
     workspacePath,
     localPort: runtime.localPort,
     transport: runtime.transport,
@@ -1408,6 +1655,212 @@ async function handlePersonaDeleteCommand(slug, flags = {}) {
   });
   printStructuredResult(result, isTruthyFlag(flags.json));
 }
+
+async function restartManagedPersonaRefreshTargets(flags = {}, options = {}) {
+  const workspaceRoot = resolvePersonaWorkspaceRoot(flags);
+  const localTargets = collectManagedPersonaRefreshTargets({
+    workspaceRoot,
+    includeStopped: isTruthyFlag(flags['include-stopped']),
+  });
+  const targetsBySlug = new Map(localTargets.map((target) => [target.slug, target]));
+  const targets = [...localTargets];
+  const results = [];
+  const logger = options.logger || null;
+
+  let client = null;
+  let registrationError = '';
+  try {
+    client = createCliPersonaApiClient(flags);
+  } catch (error) {
+    registrationError = error instanceof Error ? error.message : String(error);
+    logger?.(`Persona backend registration unavailable: ${registrationError}`);
+  }
+
+  if (client) {
+    try {
+      const backendTargets = await discoverBackendLinkedPersonaRefreshTargets({
+        client,
+        workspaceRoot,
+        existingTargets: targets,
+        logger,
+      });
+      for (const target of backendTargets) {
+        targetsBySlug.set(target.slug, target);
+        targets.push(target);
+      }
+    } catch (error) {
+      logger?.(`Backend persona discovery failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  logger?.(
+    `Discovered ${targets.length} managed persona runtime${targets.length == 1 ? '' : 's'} to refresh.`,
+  );
+
+  for (const target of targets) {
+    const state = target.state && typeof target.state === 'object' ? target.state : {};
+    logger?.(
+      `Refreshing persona ${target.slug} (previous port: ${String(state.localPort || 'unknown')}).`,
+    );
+    const launchResult = await launchManagedPersonaRuntime({
+      slug: target.slug,
+      name: String(state.name || target.slug).trim() || target.slug,
+      description: String(state.description || state.name || target.slug).trim() || target.slug,
+      workspaceRoot,
+      templateVersion: String(state.templateVersion || 'v1').trim() || 'v1',
+      forceInstall: isTruthyFlag(flags['force-install']),
+      restart: true,
+      logFilePath: String(state.logFilePath || '').trim(),
+      entryUrl: '',
+      transport: 'local',
+    });
+
+    let registration = null;
+    if (client) {
+      try {
+        logger?.(`Re-registering runtime for ${launchResult.slug} at ${launchResult.runtime.endpoint}.`);
+        registration = await client.registerRuntime({
+          slug: launchResult.slug,
+          endpoint: launchResult.runtime.endpoint,
+          healthcheckUrl: launchResult.runtime.healthcheckUrl,
+          localPort: launchResult.runtime.localPort,
+          transport: launchResult.runtime.transport,
+          startedAt: new Date().toISOString(),
+        });
+      } catch (error) {
+        registration = {
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+        logger?.(`Runtime registration failed for ${launchResult.slug}: ${registration.error}`);
+      }
+    }
+
+    logger?.(
+      `Persona ${launchResult.slug} refreshed on port ${launchResult.runtime.localPort} (${launchResult.runtime.endpoint}).`,
+    );
+
+    results.push({
+      slug: launchResult.slug,
+      workspacePath: launchResult.workspacePath,
+      localPort: launchResult.runtime.localPort,
+      endpoint: launchResult.runtime.endpoint,
+      healthcheckUrl: launchResult.runtime.healthcheckUrl,
+      registration,
+    });
+  }
+
+  return {
+    workspaceRoot,
+    targets,
+    results,
+    registrationError,
+  };
+}
+
+async function refreshBridgeForUpdate(flags = {}, options = {}) {
+  const logger = options.logger || null;
+  if (process.platform === 'darwin') {
+    const launchdStatus = readBridgeLaunchdStatus();
+    if (launchdStatus.installed) {
+      logger?.(`Restarting launchd-managed bridge ${launchdStatus.target}.`);
+      await stopBridgeLaunchdService();
+      startBridgeLaunchdService();
+      incrementBridgeMetric('bridge_restart_count');
+      return {
+        restarted: true,
+        mode: 'service',
+        target: launchdStatus.target,
+      };
+    }
+  }
+
+  const running = findRunningBridgeProcess();
+  if (!running) {
+    logger?.('No bridge process is currently running; skipping bridge restart.');
+    return {
+      restarted: false,
+      mode: 'process',
+    };
+  }
+
+  logger?.(`Restarting bridge process ${running.pid}.`);
+  const stopResult = await stopBridgeProcesses();
+  if (Array.isArray(stopResult.stillAlive) && stopResult.stillAlive.length > 0) {
+    throw new Error(`Failed to stop bridge processes: ${stopResult.stillAlive.join(', ')}`);
+  }
+
+  const detachedResult = startBridgeDetachedProcess(flags);
+  incrementBridgeMetric('bridge_restart_count');
+  return {
+    restarted: true,
+    mode: 'process',
+    pid: detachedResult.pid,
+    alreadyRunning: Boolean(detachedResult.alreadyRunning),
+  };
+}
+
+async function handleOpenclawRefreshCommand(flags = {}) {
+  const jsonOutput = isTruthyFlag(flags.json);
+  const logProgress = jsonOutput ? null : (message) => console.log(`[refresh] ${message}`);
+  const currentVersion = currentPackageVersion();
+  let latestVersion = '';
+  if (!isTruthyFlag(flags['skip-version-check'])) {
+    logProgress?.(`Checking npm for the latest oomi-ai version (installed: ${currentVersion || 'unknown'}).`);
+    latestVersion = await fetchLatestPublishedVersion('oomi-ai');
+    if (latestVersion && compareVersions(currentVersion, latestVersion) < 0) {
+      throw new Error(
+        `Installed oomi-ai ${currentVersion} is behind npm ${latestVersion}. Update first, then rerun: oomi openclaw refresh`
+      );
+    }
+    if (latestVersion) {
+      logProgress?.(`Latest published version is ${latestVersion}.`);
+    }
+  }
+
+  logProgress?.('Refreshing managed persona runtimes.');
+  const personaRefresh = await restartManagedPersonaRefreshTargets(flags, {
+    logger: logProgress,
+  });
+  logProgress?.('Refreshing bridge process.');
+  const bridgeRefresh = await refreshBridgeForUpdate(flags, {
+    logger: logProgress,
+  });
+  const payload = {
+    ok: true,
+    currentVersion,
+    latestVersion: latestVersion || currentVersion,
+    personas: {
+      discovered: personaRefresh.targets.length,
+      restarted: personaRefresh.results.length,
+      registrationError: personaRefresh.registrationError || null,
+      results: personaRefresh.results,
+    },
+    bridge: bridgeRefresh,
+  };
+
+  if (jsonOutput) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log(`Oomi refresh complete (${payload.currentVersion})`);
+  console.log(`Personas restarted: ${payload.personas.restarted}/${payload.personas.discovered}`);
+  if (payload.personas.registrationError) {
+    console.log(`Backend registration skipped: ${payload.personas.registrationError}`);
+  }
+  payload.personas.results.forEach((result) => {
+    console.log(`- ${result.slug}: ${result.endpoint}`);
+    if (result.registration && result.registration.ok === false) {
+      console.log(`  registration: ${result.registration.error}`);
+    }
+  });
+  if (payload.bridge.restarted) {
+    console.log(`Bridge restarted (${payload.bridge.mode}).`);
+  } else {
+    console.log('Bridge not running; no restart performed.');
+  }
+}
 
 function resolveOpenclawConfigPath() {
   const candidates = resolveOpenclawConfigCandidates();
@@ -5339,15 +5792,20 @@ async function main() {
     return;
   }
 
-  if (command === 'openclaw' && subcommand === 'debug') {
-    await handleOpenclawDebugCommand(args.positionals[0], args.flags);
-    return;
-  }
-
-  if (command === 'personas' && subcommand === 'sync') {
-    await syncPersonas({ backendUrl: args.flags['backend-url'], root: args.flags.root });
-    return;
-  }
+  if (command === 'openclaw' && subcommand === 'debug') {
+    await handleOpenclawDebugCommand(args.positionals[0], args.flags);
+    return;
+  }
+
+  if (command === 'openclaw' && subcommand === 'refresh') {
+    await handleOpenclawRefreshCommand(args.flags);
+    return;
+  }
+
+  if (command === 'personas' && subcommand === 'sync') {
+    await syncPersonas({ backendUrl: args.flags['backend-url'], root: args.flags.root });
+    return;
+  }
 
   if (command === 'personas' && subcommand === 'create') {
     const id = args.positionals[0];
@@ -5504,8 +5962,13 @@ export {
   runBridgeCallbackSafely,
   extractGatewayRequestMeta,
   extractGatewayResponseMeta,
-  isServiceManagedBridgeStart,
-  isGatewayRunStartedFrame,
-  isBridgeWorkerCommand,
-  parsePositiveInteger,
-};
+  isServiceManagedBridgeStart,
+  isGatewayRunStartedFrame,
+  isBridgeWorkerCommand,
+  parsePositiveInteger,
+  collectManagedPersonaRefreshTargets,
+  discoverBackendLinkedPersonaRefreshTargets,
+  normalizeBackendPersonaRefreshRecord,
+  resolvePersonaRuntimeInput,
+  resolveExistingWorkspacePathForSlug,
+};

package/lib/personaApiClient.js

@@ -100,10 +100,19 @@ export function createPersonaApiClient({
     };
   }
 
-  return {
-    getPersona({
-      slug,
-    }) {
+  return {
+    listPersonas() {
+      return getJson({
+        fetchImpl,
+        backendUrl: resolvedBackendUrl,
+        deviceToken: resolvedDeviceToken,
+        path: '/v1/personas',
+      });
+    },
+
+    getPersona({
+      slug,
+    }) {
       const safeSlug = trimString(slug);
       if (!safeSlug) {
         throw new Error('Persona slug is required.');

package/lib/personaRuntimeManager.js

@@ -8,6 +8,7 @@ import {
   defaultPersonaWorkspaceRoot,
   installPersonaWorkspace,
   isPersonaWorkspaceProcessRunning,
+  resolvePersonaHealthPath,
   resolvePersonaDevCommand,
   syncLegacyWebSpatialScaffoldFiles,
   syncVendoredWebSpatialPackages,
@@ -143,20 +144,12 @@ export function slugifyPersonaName(name) {
   return normalized;
 }
 
-function resolveHealthPath(workspacePath) {
-  const runtimeConfigPath = path.join(workspacePath, 'oomi.runtime.json');
-  if (!fs.existsSync(runtimeConfigPath)) {
-    return '/oomi.health.json';
-  }
-
-  try {
-    const parsed = JSON.parse(fs.readFileSync(runtimeConfigPath, 'utf8'));
-    const healthPath = trimString(parsed?.healthPath);
-    return healthPath || '/oomi.health.json';
-  } catch {
-    return '/oomi.health.json';
-  }
-}
+function resolveHealthPath(workspacePath) {
+  return resolvePersonaHealthPath({
+    workspacePath,
+    fallback: '/oomi.health.json',
+  });
+}
 
 function workspaceNeedsScaffold(workspacePath) {
   return !fs.existsSync(path.join(workspacePath, 'package.json'));
@@ -270,12 +263,12 @@ export async function launchManagedPersonaRuntime({
     workspacePath,
     templateVersion,
   });
-  const installed = await ensureWorkspaceInstall({
-    workspacePath,
-    forceInstall,
-  });
-
-  const healthPath = scaffoldInfo.healthPath || resolveHealthPath(workspacePath);
+  const installed = await ensureWorkspaceInstall({
+    workspacePath,
+    forceInstall,
+  });
+
+  const healthPath = resolveHealthPath(workspacePath);
   const preferredPort = previousState.localPort || scaffoldInfo.defaultPort;
   const expectedDevCommand = resolvePersonaDevCommand({
     workspacePath,

package/lib/personaRuntimeProcess.js

@@ -30,12 +30,25 @@ const WEBSPATIAL_VENDOR_ROOT = path.join(
 );
 const VENDORED_WEBSPATIAL_CORE_SPEC = 'file:./vendor/webspatial/core-sdk';
 const VENDORED_WEBSPATIAL_REACT_SPEC = 'file:./vendor/webspatial/react-sdk';
+const WEBSPATIAL_RUNTIME_BASE_PATH = '/webspatial/avp';
 const WEBSPATIAL_TEMPLATE_DEV_DEPENDENCIES = [
   '@webspatial/builder',
   '@webspatial/platform-visionos',
   '@webspatial/vite-plugin',
 ];
 const LEGACY_WEBSPATIAL_TEMPLATE_FILE_RULES = [
+  {
+    relativePath: 'oomi.runtime.json',
+    shouldReplace: (content) =>
+      content.includes('"renderMode": "webspatial"') &&
+      content.includes('"healthPath": "/oomi.health.json"'),
+  },
+  {
+    relativePath: 'package.json',
+    shouldReplace: (content) =>
+      content.includes('vite --host 127.0.0.1 --port 4789') ||
+      content.includes('vite preview --host 127.0.0.1 --port 4789'),
+  },
   {
     relativePath: path.join('src', 'spatial.ts'),
     shouldReplace: (content) =>
@@ -295,6 +308,21 @@ function trimString(value) {
   return typeof value === 'string' ? value.trim() : '';
 }
 
+function normalizePersonaHealthPath(healthPath, runtimeConfig = {}) {
+  const safeHealthPath = trimString(healthPath) || '/oomi.health.json';
+  const renderMode = trimString(runtimeConfig?.renderMode).toLowerCase();
+  if (renderMode !== 'webspatial') {
+    return safeHealthPath;
+  }
+
+  if (safeHealthPath.startsWith(`${WEBSPATIAL_RUNTIME_BASE_PATH}/`)) {
+    return safeHealthPath;
+  }
+
+  const normalizedSuffix = safeHealthPath.startsWith('/') ? safeHealthPath : `/${safeHealthPath}`;
+  return `${WEBSPATIAL_RUNTIME_BASE_PATH}${normalizedSuffix}`;
+}
+
 function readPersonaConfigLiteral(source, key) {
   if (!source) {
     return '';
@@ -664,6 +692,17 @@ export function resolvePersonaDevEnvironment({
   return {};
 }
 
+export function resolvePersonaHealthPath({
+  workspacePath,
+  fallback = '/oomi.health.json',
+} = {}) {
+  const runtimeConfig = readPersonaRuntimeConfig(workspacePath);
+  return normalizePersonaHealthPath(
+    trimString(runtimeConfig?.healthPath) || fallback,
+    runtimeConfig,
+  );
+}
+
 export function startPersonaWorkspace({
   workspacePath,
   logFilePath,
@@ -855,6 +894,7 @@ export function buildLocalPersonaRuntime({
   const reachableHost = resolvePersonaReachableHost({ bindHost });
   const endpoint = `http://127.0.0.1:${port}`;
   const reachableEndpoint = `http://${formatPersonaRuntimeHostForUrl(reachableHost)}:${port}`;
+  const normalizedHealthPath = healthPath || '/oomi.health.json';
   return {
     transport: 'local',
     endpoint,
@@ -862,7 +902,7 @@ export function buildLocalPersonaRuntime({
     bindHost,
     reachableHost,
     localPort: port,
-    healthcheckUrl: `${endpoint}${healthPath}`,
+    healthcheckUrl: `${endpoint}${normalizedHealthPath}`,
   };
 }
 

package/lib/personaRuntimeSupervisor.js

@@ -5,7 +5,12 @@ import { resolveOpenclawLegacyPersonasDir } from './openclawPaths.js';
 import { createPersonaApiClient } from './personaApiClient.js';
 import { launchManagedPersonaRuntime } from './personaRuntimeManager.js';
 import { readPersonaRuntimeState, updatePersonaRuntimeState } from './personaRuntimeRegistry.js';
-import { buildLocalPersonaRuntime, isPersonaWorkspaceProcessRunning, resolvePersonaDevCommand } from './personaRuntimeProcess.js';
+import {
+  buildLocalPersonaRuntime,
+  isPersonaWorkspaceProcessRunning,
+  resolvePersonaDevCommand,
+  resolvePersonaHealthPath,
+} from './personaRuntimeProcess.js';
 
 function trimString(value) {
   return typeof value === 'string' ? value.trim() : '';
@@ -17,20 +22,6 @@ function wait(ms) {
   });
 }
 
-function resolveHealthPath(healthcheckUrl) {
-  const safeUrl = trimString(healthcheckUrl);
-  if (!safeUrl) {
-    return '/oomi.health.json';
-  }
-
-  try {
-    const parsed = new URL(safeUrl);
-    return `${parsed.pathname || '/oomi.health.json'}${parsed.search || ''}`;
-  } catch {
-    return '/oomi.health.json';
-  }
-}
-
 function listWorkspacePaths(workspaceRoot) {
   const roots = [trimString(workspaceRoot), trimString(resolveOpenclawLegacyPersonasDir())]
     .filter(Boolean)
@@ -100,7 +91,10 @@ async function reconcileWorkspace({
   const localRuntime = runtime.localPort
     ? buildLocalPersonaRuntime({
         localPort: runtime.localPort,
-        healthPath: resolveHealthPath(runtime.healthcheckUrl),
+        healthPath: resolvePersonaHealthPath({
+          workspacePath,
+          fallback: '/oomi.health.json',
+        }),
       })
     : null;
 
@@ -166,29 +160,86 @@ async function reconcileWorkspace({
 
   const healthy = await healthcheckOk(effectiveRuntime.healthcheckUrl);
   if (!healthy) {
-    return;
+    if (!autoRestart) {
+      return;
+    }
+
+    try {
+      const recovered = await launchManagedPersonaRuntime({
+        slug,
+        name: trimString(state.name) || slug,
+        description: trimString(state.description) || trimString(state.name) || slug,
+        workspaceRoot,
+        templateVersion: trimString(state.templateVersion) || 'v1',
+        forceInstall: false,
+        restart: true,
+        logFilePath: trimString(state.logFilePath),
+        entryUrl: '',
+        transport: 'local',
+      });
+
+      effectiveRuntime = {
+        slug,
+        endpoint: recovered.runtime.endpoint,
+        localEndpoint: recovered.runtime.localEndpoint || recovered.localRuntime.endpoint,
+        reachableEndpoint: recovered.runtime.reachableEndpoint || recovered.localRuntime.reachableEndpoint,
+        healthcheckUrl: recovered.runtime.healthcheckUrl,
+        transport: recovered.runtime.transport,
+        localPort: recovered.runtime.localPort,
+      };
+
+      await client.registerRuntime({
+        slug,
+        endpoint: effectiveRuntime.endpoint,
+        healthcheckUrl: effectiveRuntime.healthcheckUrl,
+        localPort: effectiveRuntime.localPort,
+        transport: effectiveRuntime.transport,
+        startedAt: new Date().toISOString(),
+      });
+    } catch (error) {
+      logger.warn?.(
+        `[persona-runtime] unhealthy runtime restart failed for ${slug}: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+      return;
+    }
+  }
+
+  if (!healthy) {
+    const recoveredHealthy = await healthcheckOk(effectiveRuntime.healthcheckUrl);
+    if (!recoveredHealthy) {
+      return;
+    }
   }
 
   if (localRuntime) {
-    const desiredEndpoint = localRuntime.reachableEndpoint || runtime.endpoint;
+    const refreshedLocalRuntime = buildLocalPersonaRuntime({
+      localPort: effectiveRuntime.localPort,
+      healthPath: resolvePersonaHealthPath({
+        workspacePath,
+        fallback: '/oomi.health.json',
+      }),
+    });
+    const desiredEndpoint = refreshedLocalRuntime.reachableEndpoint || runtime.endpoint;
     const endpointChanged = desiredEndpoint && desiredEndpoint !== effectiveRuntime.endpoint;
-    const localEndpointChanged = localRuntime.endpoint !== effectiveRuntime.localEndpoint;
-    const reachableEndpointChanged = localRuntime.reachableEndpoint !== effectiveRuntime.reachableEndpoint;
+    const localEndpointChanged = refreshedLocalRuntime.endpoint !== effectiveRuntime.localEndpoint;
+    const reachableEndpointChanged = refreshedLocalRuntime.reachableEndpoint !== effectiveRuntime.reachableEndpoint;
 
     if (endpointChanged || localEndpointChanged || reachableEndpointChanged) {
       effectiveRuntime = {
         ...effectiveRuntime,
         endpoint: desiredEndpoint,
-        localEndpoint: localRuntime.endpoint,
-        reachableEndpoint: localRuntime.reachableEndpoint,
+        localEndpoint: refreshedLocalRuntime.endpoint,
+        reachableEndpoint: refreshedLocalRuntime.reachableEndpoint,
       };
       updatePersonaRuntimeState(workspacePath, {
         endpoint: desiredEndpoint,
         entryUrl: desiredEndpoint,
-        localEndpoint: localRuntime.endpoint,
-        reachableEndpoint: localRuntime.reachableEndpoint,
-        bindHost: localRuntime.bindHost,
-        reachableHost: localRuntime.reachableHost,
+        localEndpoint: refreshedLocalRuntime.endpoint,
+        reachableEndpoint: refreshedLocalRuntime.reachableEndpoint,
+        bindHost: refreshedLocalRuntime.bindHost,
+        reachableHost: refreshedLocalRuntime.reachableHost,
       });
 
       try {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "oomi-ai",
   "name": "Oomi Channel Plugin",
   "description": "Managed Oomi channel integration for OpenClaw.",
-  "version": "0.2.42",
+  "version": "0.2.47",
   "author": "Oomi",
   "license": "MIT",
   "openclawVersion": ">=0.5.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.2.42",
+  "version": "0.2.47",
   "description": "Oomi OpenClaw channel plugin and bridge tooling",
   "bin": {
     "oomi": "bin/oomi-ai.js"

package/templates/persona-app/oomi.runtime.json

@@ -1,7 +1,7 @@
 {
   "templateVersion": "__OOMI_TEMPLATE_VERSION__",
   "appKind": "oomi-persona-app",
-  "healthPath": "/oomi.health.json",
+  "healthPath": "/webspatial/avp/oomi.health.json",
   "defaultPort": 4789,
   "supportsRuntimeRegistration": true,
   "renderMode": "webspatial",

package/templates/persona-app/package.json

@@ -5,10 +5,10 @@
   "type": "module",
   "scripts": {
     "install:clean": "npm install",
-    "dev": "vite --host 127.0.0.1 --port 4789",
-    "dev:avp": "cross-env XR_ENV=avp vite --host 127.0.0.1 --port 4789",
+    "dev": "vite --host 0.0.0.0 --port 4789 --strictPort",
+    "dev:avp": "cross-env XR_ENV=avp vite --host 0.0.0.0 --port 4789 --strictPort",
     "build": "vite build && cross-env XR_ENV=avp vite build",
-    "preview": "vite preview --host 127.0.0.1 --port 4789",
+    "preview": "vite preview --host 0.0.0.0 --port 4789 --strictPort",
     "lint": "eslint ."
   },
   "dependencies": {

package/templates/persona-app/template.json

@@ -4,7 +4,7 @@
   "displayName": "Oomi Persona App",
   "appKind": "oomi-persona-app",
   "defaultPort": 4789,
-  "healthPath": "/oomi.health.json",
+  "healthPath": "/webspatial/avp/oomi.health.json",
   "startCommand": "npm run dev:avp",
   "editableZones": [
     "src/persona",