oomi-ai 0.2.28 → 0.2.38

package/bin/oomi-ai.js

@@ -5,28 +5,59 @@ import path from 'path';
 import { spawn, spawnSync } from 'child_process';
 import { createPrivateKey, createPublicKey, randomUUID, sign as cryptoSign } from 'crypto';
 import net from 'net';
-import { lookup as dnsLookup } from 'dns/promises';
-import { fileURLToPath } from 'url';
-import WebSocket from 'ws';
-import { scaffoldPersonaApp } from '../lib/scaffold.js';
+import { lookup as dnsLookup } from 'dns/promises';
+import { fileURLToPath } from 'url';
+import WebSocket from 'ws';
+import { scaffoldPersonaApp } from '../lib/scaffold.js';
 import { createPersonaApiClient } from '../lib/personaApiClient.js';
 import { startPersonaJobPoller } from '../lib/personaJobPoller.js';
-import { executePersonaJob } from '../lib/personaJobExecutor.js';
-import { inferSpokenMetadataFromContent, normalizeSpokenMetadata } from '../lib/spokenMetadata.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 {
+  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,
-  startPersonaWorkspace,
-  waitForPersonaRuntime,
-} from '../lib/personaRuntimeProcess.js';
-import { ensureSessionBridge, flushSessionQueue, flushWaitingForConnect, forwardFrameToSession } from './sessionBridgeState.js';
+  destroyManagedPersonaRuntime,
+  getManagedPersonaRuntimeStatus,
+  launchManagedPersonaRuntime,
+  slugifyPersonaName,
+  stopManagedPersonaRuntime,
+} from '../lib/personaRuntimeManager.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 UPDATE_STATE_FILE = path.join(os.homedir(), '.openclaw', 'oomi-ai-update-check.json');
+const UPDATE_STATE_FILE = resolveOpenclawUpdateStatePath();
 const DEFAULT_UPDATE_CHECK_INTERVAL_MS = 12 * 60 * 60 * 1000;
 const DEFAULT_UPDATE_CHECK_TIMEOUT_MS = 1200;
 const BRIDGE_RECONNECT_BASE_MS = 2000;
@@ -39,21 +70,32 @@ const BRIDGE_CONNECT_CHALLENGE_TIMEOUT_MS = parsePositiveInteger(
   process.env.OOMI_BRIDGE_CONNECT_CHALLENGE_TIMEOUT_MS,
   3000
 );
-const BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS = parsePositiveInteger(
-  process.env.OOMI_BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS,
-  30000
-);
-const BRIDGE_LAUNCHD_LABEL = 'ai.oomi.bridge';
-const DEBUG_PROVIDER_ENV_KEYS = [
-  'QWEN_REALTIME_API_KEY',
-  'QWEN_REALTIME_BASE_URL',
-  'QWEN_REALTIME_ASR_MODEL',
-  'QWEN_REALTIME_TTS_MODEL',
-  'QWEN_REALTIME_TTS_VOICE',
-  'QWEN_REALTIME_LANGUAGE',
-];
-const DEVICE_IDENTITY_PATH = path.join(os.homedir(), '.openclaw', 'identity', 'device.json');
-const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS = parsePositiveInteger(
+  process.env.OOMI_BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS,
+  30000
+);
+const BRIDGE_LAUNCHD_LABEL = 'ai.oomi.bridge';
+const DEBUG_PROVIDER_ENV_KEYS = [
+  'QWEN_REALTIME_API_KEY',
+  'QWEN_REALTIME_BASE_URL',
+  'QWEN_REALTIME_ASR_MODEL',
+  'QWEN_REALTIME_TTS_MODEL',
+  'QWEN_REALTIME_TTS_VOICE',
+  'QWEN_REALTIME_LANGUAGE',
+];
+const DEVICE_IDENTITY_PATH = resolveOpenclawIdentityPath();
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const BRIDGE_DEBUG_ENABLED = process.env.OOMI_BRIDGE_DEBUG === '1';
+
+function bridgeDebugLog(...args) {
+  if (!BRIDGE_DEBUG_ENABLED) return;
+  console.log(...args);
+}
+
+function bridgeDebugWarn(...args) {
+  if (!BRIDGE_DEBUG_ENABLED) return;
+  console.warn(...args);
+}
 
 function parsePositiveInteger(value, fallback) {
   const num = Number(value);
@@ -177,14 +219,22 @@ Commands:
   openclaw install
     Install agent instructions and the Oomi skill into OpenClaw.
 
-  openclaw bridge [start|ensure|stop|restart|ps]
-    Manage local OpenClaw-to-Oomi bridge lifecycle (singleton).
-  openclaw bridge service [install|start|stop|restart|status|uninstall]
-    Manage macOS launchd bridge supervision.
-  openclaw debug assistant-final
-    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 bridge [start|ensure|stop|restart|ps]
+    Manage local OpenClaw-to-Oomi bridge lifecycle (singleton).
+  openclaw bridge service [install|start|stop|restart|status|uninstall]
+    Manage macOS launchd bridge supervision.
+  openclaw profile init
+    Write a deterministic OpenClaw profile for local/dev or hosted setup flows.
+  openclaw profile apply
+    Apply an OpenClaw profile into the current OpenClaw home/config.
+  openclaw debug assistant-final
+    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 pair
     Pair this OpenClaw host with Oomi and start bridge (single command).
@@ -201,26 +251,34 @@ Commands:
   personas sync
     Sync personas from the repo into the Oomi backend registry.
 
-  personas create <id>
-    Create a new persona manifest and optionally sync it to the backend.
-  personas create-managed [slug]
-    Create a managed persona in Oomi and enqueue its build job for the linked device.
-  personas scaffold <slug>
-    Create an Oomi-managed persona app scaffold for agent customization.
+  personas create <id>
+    Create a new persona manifest and optionally sync it to the backend.
+  personas create-managed [slug]
+    Create a managed persona in Oomi and enqueue its build job for the linked device.
+  personas launch-managed [slug]
+    Launch or reuse a managed persona runtime on this OpenClaw machine.
+  personas scaffold <slug>
+    Create an Oomi-managed persona app scaffold for agent customization.
+  personas status <slug>
+    Show local managed persona runtime state for a persona slug.
+  personas stop <slug>
+    Stop a locally running managed persona runtime.
+  personas delete <slug>
+    Stop a managed persona runtime and remove its workspace from this OpenClaw machine.
   personas runtime-register <slug>
     Register a running persona runtime with the Oomi backend.
-  personas heartbeat <slug>
-    Send a persona runtime heartbeat to the Oomi backend.
-  personas runtime-fail <slug>
-    Report persona runtime failure to the Oomi backend.
-  persona-jobs start <jobId>
-    Mark a persona job as running.
-  persona-jobs succeed <jobId>
-    Mark a persona job as succeeded.
-  persona-jobs fail <jobId>
-    Mark a persona job as failed.
-  persona-jobs execute
-    Execute a structured persona job payload end to end.
+  personas heartbeat <slug>
+    Send a persona runtime heartbeat to the Oomi backend.
+  personas runtime-fail <slug>
+    Report persona runtime failure to the Oomi backend.
+  persona-jobs start <jobId>
+    Mark a persona job as running.
+  persona-jobs succeed <jobId>
+    Mark a persona job as succeeded.
+  persona-jobs fail <jobId>
+    Mark a persona job as failed.
+  persona-jobs execute
+    Execute a structured persona job payload end to end.
 
 Common flags:
   --agents-file PATH     Override AGENTS.md path
@@ -233,94 +291,100 @@ Common flags:
   --label TEXT           Pairing label shown in broker logs
   --session-key KEY      Session key used in generated connect URL
   --detach               Start bridge in background and exit
-  --no-start             Do not start the bridge or persona runtime
+  --no-start             Do not start the bridge or persona runtime
   --device-id ID         Bridge device identifier (default: host name)
   --device-token TOKEN   Existing bridge device token
   --show-secrets         Print full token values in diagnostic output
-  --json                 Print pairing result as JSON (for automation)
-  --text TEXT            Assistant text for local debug frame replay
-  --frame-file PATH      Read a raw gateway frame from disk for local debug replay
-  --frame-json JSON      Use raw gateway frame JSON text for local debug replay
-  --session-id ID        Debug session id override (default: ms_debug_local)
-  --user-text TEXT       User utterance text used for backend voice replay
-  --live-provider        Use the real Qwen TTS provider in local debug replay
-  --env-file PATH        Load provider env vars from a specific env file (default: <repo>/.env.local)
-  --provider-timeout-ms N
-                        Timeout in ms for live provider audio during local debug replay
-  --backend-url URL      Override Oomi backend URL
-  --root PATH            Override repo root path for persona discovery
-  --role ROLE            Message role override for local debug frame replay
-  --omit-role            Omit message.role in the generated local debug frame
-  --name NAME            Persona display name (for create)
-  --description TEXT     Persona description (for scaffold)
-  --slug SLUG            Explicit slug override (for create-managed)
-  --summary TEXT         Persona summary (for create)
+  --json                 Print pairing result as JSON (for automation)
+  --text TEXT            Assistant text for local debug frame replay
+  --frame-file PATH      Read a raw gateway frame from disk for local debug replay
+  --frame-json JSON      Use raw gateway frame JSON text for local debug replay
+  --session-id ID        Debug session id override (default: ms_debug_local)
+  --user-text TEXT       User utterance text used for backend voice replay
+  --live-provider        Use the real Qwen TTS provider in local debug replay
+  --env-file PATH        Load provider env vars from a specific env file (default: <repo>/.env.local)
+  --provider-timeout-ms N
+                        Timeout in ms for live provider audio during local debug replay
+  --backend-url URL      Override Oomi backend URL
+  --root PATH            Override repo root path for persona discovery
+  --role ROLE            Message role override for local debug frame replay
+  --omit-role            Omit message.role in the generated local debug frame
+  --name NAME            Persona display name (for create)
+  --description TEXT     Persona description (for scaffold)
+  --slug SLUG            Explicit slug override (for create-managed)
+  --summary TEXT         Persona summary (for create)
   --status STATUS        Persona status (for create)
   --type TYPE            Persona type (for create)
   --tags a,b,c           Persona tags (for create)
   --chat-session KEY     Persona chat session key (for create)
-  --out PATH             Output directory for scaffolded persona app
-  --template-version V   Scaffold template version (default: v1)
-  --force                Overwrite files in an existing output directory
-  --no-sync              Skip backend sync (for create)
-  --local-port N         Local runtime port for persona runtime callbacks
-  --endpoint URL         Runtime endpoint for persona runtime callbacks
-  --health-path PATH     Runtime health path (default: /oomi.health.json)
-  --healthcheck-url URL  Runtime healthcheck URL override
-  --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
-  --message TEXT         Error message for fail callbacks
-  --message-file PATH    Structured persona job message JSON file
-  --message-json JSON    Structured persona job message JSON text
-  --log-file PATH        Runtime log file path override
-  --no-install           Skip npm install during persona job execution
-  --no-register          Skip persona runtime registration during persona job execution
-`);
-}
+  --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
+  --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)
+  --healthcheck-url URL  Runtime healthcheck URL override
+  --transport TEXT       Runtime transport label (default: local, relay when --entry-url is used)
+  --workspace-root PATH  Persona workspace root (default: ~/.openclaw/personas)
+  --restart              Restart an existing managed persona runtime before launch
+  --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
+  --message TEXT         Error message for fail callbacks
+  --message-file PATH    Structured persona job message JSON file
+  --message-json JSON    Structured persona job message JSON text
+  --log-file PATH        Runtime log file path override
+  --no-install           Skip npm install during persona job execution
+  --no-register          Skip persona runtime registration during persona job execution
+`);
+}
 
 function readFile(filePath) {
   return fs.readFileSync(filePath, 'utf-8');
 }
 
-function writeFile(filePath, content, options = undefined) {
-  fs.writeFileSync(filePath, content, options);
-}
-
-function parseDotEnvLine(line) {
-  const trimmed = String(line || '').trim();
-  if (!trimmed || trimmed.startsWith('#')) return null;
-  const separatorIndex = trimmed.indexOf('=');
-  if (separatorIndex <= 0) return null;
-  const key = trimmed.slice(0, separatorIndex).trim();
-  if (!key) return null;
-  let value = trimmed.slice(separatorIndex + 1).trim();
-  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-    value = value.slice(1, -1);
-  }
-  return { key, value };
-}
-
-function loadEnvFile(filePath, keys = []) {
-  if (!filePath || !fs.existsSync(filePath)) {
-    throw new Error(`Environment file not found: ${filePath}`);
-  }
-  const selectedKeys = Array.isArray(keys) && keys.length ? new Set(keys) : null;
-  const entries = {};
-  const lines = readFile(filePath).split(/\r?\n/);
-  for (const line of lines) {
-    const parsed = parseDotEnvLine(line);
-    if (!parsed) continue;
-    if (selectedKeys && !selectedKeys.has(parsed.key)) continue;
-    entries[parsed.key] = parsed.value;
-  }
-  return entries;
-}
-
-function xmlEscape(value) {
-  return String(value)
-    .replaceAll('&', '&amp;')
+function writeFile(filePath, content, options = undefined) {
+  fs.writeFileSync(filePath, content, options);
+}
+
+function parseDotEnvLine(line) {
+  const trimmed = String(line || '').trim();
+  if (!trimmed || trimmed.startsWith('#')) return null;
+  const separatorIndex = trimmed.indexOf('=');
+  if (separatorIndex <= 0) return null;
+  const key = trimmed.slice(0, separatorIndex).trim();
+  if (!key) return null;
+  let value = trimmed.slice(separatorIndex + 1).trim();
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    value = value.slice(1, -1);
+  }
+  return { key, value };
+}
+
+function loadEnvFile(filePath, keys = []) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    throw new Error(`Environment file not found: ${filePath}`);
+  }
+  const selectedKeys = Array.isArray(keys) && keys.length ? new Set(keys) : null;
+  const entries = {};
+  const lines = readFile(filePath).split(/\r?\n/);
+  for (const line of lines) {
+    const parsed = parseDotEnvLine(line);
+    if (!parsed) continue;
+    if (selectedKeys && !selectedKeys.has(parsed.key)) continue;
+    entries[parsed.key] = parsed.value;
+  }
+  return entries;
+}
+
+function xmlEscape(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
     .replaceAll('<', '&lt;')
     .replaceAll('>', '&gt;')
     .replaceAll('"', '&quot;')
@@ -328,11 +392,7 @@ function xmlEscape(value) {
 }
 
 function resolveWorkspace() {
-  const envWorkspace = process.env.OPENCLAW_WORKSPACE || process.env.OPENCLAW_HOME;
-  if (envWorkspace) return envWorkspace;
-  const defaultWorkspace = path.join(os.homedir(), '.openclaw', 'workspace');
-  if (fs.existsSync(defaultWorkspace)) return defaultWorkspace;
-  return path.join(os.homedir(), '.openclaw');
+  return resolveOpenclawWorkspaceRoot();
 }
 
 function resolveAgentsFile(cliAgentsFile, cliWorkspace) {
@@ -409,9 +469,9 @@ function ensureDir(dirPath) {
   }
 }
 
-function findRepoRoot(startDir) {
-  let current = startDir;
-  for (let i = 0; i < 6; i += 1) {
+function findRepoRoot(startDir) {
+  let current = startDir;
+  for (let i = 0; i < 6; i += 1) {
     const personasDir = path.join(current, 'personas');
     const skillsDir = path.join(current, 'skills', 'oomi');
     if (fs.existsSync(personasDir) || fs.existsSync(skillsDir)) {
@@ -420,23 +480,23 @@ function findRepoRoot(startDir) {
     const parent = path.dirname(current);
     if (parent === current) break;
     current = parent;
-  }
-  return null;
-}
-
-function resolveRepoRoot(rootFlag) {
-  const explicitRoot =
-    typeof rootFlag === 'string' && rootFlag.trim()
-      ? path.resolve(rootFlag.trim())
-      : '';
-  const repoRoot = explicitRoot || findRepoRoot(process.cwd()) || findRepoRoot(PACKAGE_ROOT);
-  if (!repoRoot) {
-    throw new Error('Could not locate repo root. Use --root <repo root>.');
-  }
-  return repoRoot;
-}
-
-function resolveSkillSource(cliRoot) {
+  }
+  return null;
+}
+
+function resolveRepoRoot(rootFlag) {
+  const explicitRoot =
+    typeof rootFlag === 'string' && rootFlag.trim()
+      ? path.resolve(rootFlag.trim())
+      : '';
+  const repoRoot = explicitRoot || findRepoRoot(process.cwd()) || findRepoRoot(PACKAGE_ROOT);
+  if (!repoRoot) {
+    throw new Error('Could not locate repo root. Use --root <repo root>.');
+  }
+  return repoRoot;
+}
+
+function resolveSkillSource(cliRoot) {
   const packaged = path.join(PACKAGE_ROOT, 'skills', 'oomi');
   if (fs.existsSync(packaged)) {
     return packaged;
@@ -462,7 +522,7 @@ function resolveSkillTargets(cliSkillsDir) {
   }
 
   const targets = [];
-  const openclaw = path.join(os.homedir(), '.openclaw', 'skills');
+  const openclaw = resolveOpenclawSkillsDir();
   const clawd = path.join(os.homedir(), 'clawd', 'skills');
 
   targets.push(openclaw);
@@ -648,7 +708,7 @@ async function createPersona({ id, root, flags }) {
   console.log(`Synced persona ${payload?.persona?.slug || id}`);
 }
 
-function printPersonaScaffoldResult(result, asJson = false) {
+function printPersonaScaffoldResult(result, asJson = false) {
   if (asJson) {
     console.log(JSON.stringify(result, null, 2));
     return;
@@ -661,471 +721,770 @@ function printPersonaScaffoldResult(result, asJson = false) {
   console.log(`Start: ${result.startCommand}`);
   if (Array.isArray(result.editableZones) && result.editableZones.length > 0) {
     console.log(`Editable zones: ${result.editableZones.join(', ')}`);
-  }
-}
-
-function printManagedPersonaCreateResult(result, asJson = false) {
-  if (asJson) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-
-  const persona = result?.persona && typeof result.persona === 'object' ? result.persona : {};
-  const personaJob = result?.personaJob && typeof result.personaJob === 'object' ? result.personaJob : {};
-  console.log(`Managed persona created: ${String(persona.name || persona.slug || 'unknown')}`);
-  if (persona.slug) {
-    console.log(`Slug: ${persona.slug}`);
-  }
-  if (persona.lifecycle) {
-    console.log(`Lifecycle: ${persona.lifecycle}`);
-  }
-  if (personaJob.jobId) {
-    console.log(`Persona job: ${personaJob.jobId}`);
-  }
-  if (personaJob.status) {
-    console.log(`Job status: ${personaJob.status}`);
-  }
-  if (personaJob.deviceId) {
-    console.log(`Assigned device: ${personaJob.deviceId}`);
-  }
-}
-
-function parseOptionalPositiveInteger(value) {
-  if (value === undefined || value === null || value === '') return null;
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new Error(`Expected a positive integer, received: ${value}`);
-  }
-  return Math.floor(parsed);
-}
-
+  }
+}
+
+function printManagedPersonaCreateResult(result, asJson = false) {
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  const persona = result?.persona && typeof result.persona === 'object' ? result.persona : {};
+  const personaJob = result?.personaJob && typeof result.personaJob === 'object' ? result.personaJob : {};
+  console.log(`Managed persona created: ${String(persona.name || persona.slug || 'unknown')}`);
+  if (persona.slug) {
+    console.log(`Slug: ${persona.slug}`);
+  }
+  if (persona.lifecycle) {
+    console.log(`Lifecycle: ${persona.lifecycle}`);
+  }
+  if (personaJob.jobId) {
+    console.log(`Persona job: ${personaJob.jobId}`);
+  }
+  if (personaJob.status) {
+    console.log(`Job status: ${personaJob.status}`);
+  }
+  if (personaJob.deviceId) {
+    console.log(`Assigned device: ${personaJob.deviceId}`);
+  }
+}
+
+function parseOptionalPositiveInteger(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`Expected a positive integer, received: ${value}`);
+  }
+  return Math.floor(parsed);
+}
+
 function resolvePersonaBackendUrl(flags = {}) {
   const bridgeState = readBridgeState();
   const backendUrl = String(
     flags['backend-url'] ||
-    process.env.OOMI_BACKEND_URL ||
-    process.env.NEXT_PUBLIC_BACKEND_URL ||
-    bridgeState.brokerHttp ||
-    ''
-  ).trim();
-  if (!backendUrl) {
-    throw new Error('Missing backend URL. Use --backend-url or pair the device first.');
-  }
-  return backendUrl.replace(/\/$/, '');
-}
-
-function resolvePersonaDeviceToken(flags = {}) {
-  const bridgeState = readBridgeState();
-  const deviceToken = String(
-    flags['device-token'] ||
-    bridgeState.deviceToken ||
-    ''
-  ).trim();
-  if (!deviceToken) {
-    throw new Error('Missing device token. Use --device-token or pair the device first.');
-  }
-  return deviceToken;
-}
-
-function resolvePersonaDeviceId(flags = {}) {
-  const bridgeState = readBridgeState();
-  const deviceId = String(
-    flags['device-id'] ||
-    bridgeState.deviceId ||
-    ''
+      process.env.OOMI_DEV_BACKEND_URL ||
+      process.env.OOMI_BACKEND_URL ||
+      process.env.NEXT_PUBLIC_BACKEND_URL ||
+      bridgeState.brokerHttp ||
+      ''
   ).trim();
-  if (!deviceId) {
-    throw new Error('Missing device id. Use --device-id or pair the device first.');
-  }
-  return deviceId;
-}
-
-function createCliPersonaApiClient(flags = {}) {
-  return createPersonaApiClient({
-    backendUrl: resolvePersonaBackendUrl(flags),
-    deviceToken: resolvePersonaDeviceToken(flags),
-    deviceId: resolvePersonaDeviceId(flags),
-  });
-}
-
-function ensurePersonaJobWorkspace(message, workspaceRoot = defaultPersonaWorkspaceRoot()) {
-  const metadata = message && typeof message === 'object' ? message.metadata : null;
-  const payload = metadata && typeof metadata === 'object' ? metadata.payload : null;
-  if (!payload || typeof payload !== 'object') {
-    return message;
-  }
-
-  const persona = payload.persona && typeof payload.persona === 'object' ? payload.persona : {};
-  const scaffold = payload.scaffold && typeof payload.scaffold === 'object' ? payload.scaffold : {};
-  if (!scaffold.outDir && typeof persona.slug === 'string' && persona.slug.trim()) {
-    scaffold.outDir = path.join(workspaceRoot, persona.slug.trim());
-    payload.scaffold = scaffold;
-    metadata.payload = payload;
-    message.metadata = metadata;
-  }
-
-  return message;
-}
-
-async function runManagedPersonaJobExecution({
-  message,
-  backendUrl,
-  deviceToken,
-  deviceId,
-  workspaceRoot = defaultPersonaWorkspaceRoot(),
-  shouldInstall = true,
-  shouldStart = true,
-  shouldRegister = true,
-  logFilePath = '',
-}) {
-  const normalizedMessage = ensurePersonaJobWorkspace(
-    structuredClone(message),
-    workspaceRoot,
-  );
-  const client = createPersonaApiClient({
-    backendUrl,
-    deviceToken,
-    deviceId,
-  });
-
-  return executePersonaJob({
-    message: normalizedMessage,
-    installWorkspace: shouldInstall
-      ? async ({ workspacePath }) => {
-          await installPersonaWorkspace({ workspacePath });
-        }
-      : async () => {},
-    startWorkspace: shouldStart
-      ? async ({ workspacePath }) =>
-          startPersonaWorkspace({
-            workspacePath,
-            logFilePath,
-          })
-      : async () => ({ pid: null, logFilePath }),
-    waitForRuntime: shouldStart
-      ? async ({ runtime }) => {
-          await waitForPersonaRuntime({
-            healthcheckUrl: runtime.healthcheckUrl,
-          });
-        }
-      : async () => {},
-    registerRuntime: shouldRegister
-      ? async ({ payload: jobPayload, result: runtimeResult }) => {
-          const jobPersona = jobPayload.persona && typeof jobPayload.persona === 'object' ? jobPayload.persona : {};
-          await client.registerRuntime({
-            slug: String(jobPersona.slug || '').trim(),
-            endpoint: runtimeResult.endpoint,
-            healthcheckUrl: runtimeResult.healthcheckUrl,
-            transport: runtimeResult.transport,
-            localPort: runtimeResult.localPort,
-            startedAt: new Date().toISOString(),
-          });
-        }
-      : async () => {},
-    onJobStart: async ({ jobId }) => {
-      await client.startJob({
-        jobId,
-        startedAt: new Date().toISOString(),
-      });
-    },
-    onJobSuccess: async ({ jobId, result: runtimeResult }) => {
-      await client.succeedJob({
-        jobId,
-        workspacePath: runtimeResult.workspacePath,
-        localPort: runtimeResult.localPort,
-        transport: runtimeResult.transport,
-        endpoint: runtimeResult.endpoint,
-        healthcheckUrl: runtimeResult.healthcheckUrl,
-        completedAt: new Date().toISOString(),
-      });
-    },
-    onJobFailure: async ({ jobId, error }) => {
-      await client.failJob({
-        jobId,
-        code: String(error?.code || 'PERSONA_JOB_EXECUTION_FAILED').trim(),
-        message: String(error?.message || 'Persona job execution failed.').trim(),
-        completedAt: new Date().toISOString(),
-      });
-    },
-  });
-}
-
-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}`,
-      localPort,
-      transport,
-    };
-  }
-
-  if (!localPort) {
-    throw new Error('Runtime endpoint or local port is required.');
-  }
-
-  return buildLocalPersonaRuntime({
-    localPort,
-    healthPath,
-  });
-}
-
-function parseIsoTimestamp(rawValue, label) {
-  const value = String(rawValue || '').trim();
-  if (!value) return undefined;
-  const timestamp = new Date(value);
-  if (Number.isNaN(timestamp.getTime())) {
-    throw new Error(`${label} must be a valid ISO timestamp.`);
-  }
-  return timestamp.toISOString();
-}
-
-function readStructuredPersonaJobMessage(flags = {}) {
-  const filePath = String(flags['message-file'] || '').trim();
-  const inlineJson = String(flags['message-json'] || '').trim();
-
-  if (inlineJson) {
-    return JSON.parse(inlineJson);
-  }
-  if (filePath) {
-    return JSON.parse(readFile(path.resolve(filePath)));
-  }
-
-  throw new Error('Persona job message is required. Use --message-file or --message-json.');
-}
-
-function printStructuredResult(result, asJson = false) {
-  if (asJson) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-
-  for (const [key, value] of Object.entries(result)) {
-    console.log(`${key}: ${typeof value === 'object' ? JSON.stringify(value) : value}`);
-  }
-}
-
-async function handlePersonaRuntimeRegisterCommand(slug, flags = {}) {
-  const client = createCliPersonaApiClient(flags);
-  const runtime = resolvePersonaRuntimeInput(flags);
-  const payload = await client.registerRuntime({
-    slug,
-    endpoint: runtime.endpoint,
-    healthcheckUrl: runtime.healthcheckUrl,
-    localPort: runtime.localPort,
-    transport: runtime.transport,
-    startedAt: parseIsoTimestamp(flags['started-at'], 'started-at'),
-  });
-  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,
-    healthcheckUrl: runtime.healthcheckUrl,
-    localPort: runtime.localPort,
-    transport: runtime.transport,
-    observedAt: parseIsoTimestamp(flags['observed-at'], 'observed-at'),
-  });
-  printStructuredResult(payload, isTruthyFlag(flags.json));
-}
-
-async function handlePersonaRuntimeFailCommand(slug, flags = {}) {
-  const code = String(flags.code || '').trim();
-  const message = String(flags.message || '').trim();
-  if (!code) {
-    throw new Error('Error code is required. Use --code.');
-  }
-  if (!message) {
-    throw new Error('Error message is required. Use --message.');
-  }
-
-  const client = createCliPersonaApiClient(flags);
-  const payload = await client.failRuntime({
-    slug,
-    code,
-    message,
-  });
-  printStructuredResult(payload, isTruthyFlag(flags.json));
-}
-
-async function handlePersonaJobStartCommand(jobId, flags = {}) {
-  const client = createCliPersonaApiClient(flags);
-  const payload = await client.startJob({
-    jobId,
-    startedAt: parseIsoTimestamp(flags['started-at'], 'started-at'),
-  });
-  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,
-    workspacePath,
-    localPort: runtime.localPort,
-    transport: runtime.transport,
-    endpoint: runtime.endpoint,
-    healthcheckUrl: runtime.healthcheckUrl,
-    completedAt: parseIsoTimestamp(flags['completed-at'], 'completed-at'),
-  });
-  printStructuredResult(payload, isTruthyFlag(flags.json));
-}
-
-async function handlePersonaJobFailCommand(jobId, flags = {}) {
-  const code = String(flags.code || '').trim();
-  const message = String(flags.message || '').trim();
-  if (!code) {
-    throw new Error('Error code is required. Use --code.');
-  }
-  if (!message) {
-    throw new Error('Error message is required. Use --message.');
-  }
-
-  const client = createCliPersonaApiClient(flags);
-  const payload = await client.failJob({
-    jobId,
-    code,
-    message,
-    completedAt: parseIsoTimestamp(flags['completed-at'], 'completed-at'),
-  });
-  printStructuredResult(payload, isTruthyFlag(flags.json));
-}
-
-async function handlePersonaJobExecuteCommand(flags = {}) {
-  const message = readStructuredPersonaJobMessage(flags);
-  const shouldInstall = !isTruthyFlag(flags['no-install']);
-  const shouldStart = !isTruthyFlag(flags['no-start']);
-  const shouldRegister = !isTruthyFlag(flags['no-register']) && shouldStart;
-  const logFilePath = String(flags['log-file'] || '').trim();
-  const result = await runManagedPersonaJobExecution({
-    message,
-    backendUrl: resolvePersonaBackendUrl(flags),
-    deviceToken: resolvePersonaDeviceToken(flags),
-    deviceId: resolvePersonaDeviceId(flags),
-    workspaceRoot: String(flags['workspace-root'] || defaultPersonaWorkspaceRoot()).trim(),
-    shouldInstall,
-    shouldStart,
-    shouldRegister,
-    logFilePath,
-  });
-
-  printStructuredResult(result, isTruthyFlag(flags.json));
-}
-
-async function handlePersonaCreateManagedCommand(flags = {}, positionalSlug = '') {
-  const name = String(flags.name || '').trim();
-  if (!name) {
-    throw new Error('Persona name is required. Usage: oomi personas create-managed [slug] --name "<name>" --description "<description>"');
-  }
-
-  const description = String(flags.description || '').trim() || name;
-  const explicitSlug = String(flags.slug || positionalSlug || '').trim();
-  const client = createCliPersonaApiClient(flags);
-  const result = await client.createManagedPersona({
-    slug: explicitSlug,
-    name,
-    description,
-    templateType: String(flags['template-type'] || 'persona-app').trim() || 'persona-app',
-    promptTemplateVersion: String(flags['template-version'] || 'v1').trim() || 'v1',
-  });
-
-  printManagedPersonaCreateResult(result, isTruthyFlag(flags.json));
-}
-
-function resolveOpenclawConfigPath() {
-  const candidates = [
-    path.join(os.homedir(), '.openclaw', 'clawdbot.json'),
-    path.join(os.homedir(), '.openclaw', 'openclaw.json'),
-  ];
-  for (const candidate of candidates) {
-    if (fs.existsSync(candidate)) return candidate;
+  if (!backendUrl) {
+    throw new Error('Missing backend URL. Use --backend-url or pair the device first.');
   }
-  return null;
+  return backendUrl.replace(/\/$/, '');
 }
 
-function readOpenclawGatewayConfig() {
-  const configPath = resolveOpenclawConfigPath();
-  if (!configPath) {
-    throw new Error('OpenClaw config not found (~/.openclaw/clawdbot.json or ~/.openclaw/openclaw.json).');
+function resolvePersonaDeviceToken(flags = {}) {
+  const bridgeState = readBridgeState();
+  const deviceToken = String(
+    flags['device-token'] ||
+    bridgeState.deviceToken ||
+    ''
+  ).trim();
+  if (!deviceToken) {
+    throw new Error('Missing device token. Use --device-token or pair the device first.');
   }
-
-  const parsed = JSON.parse(readFile(configPath));
-  const gateway = parsed.gateway || {};
-  const auth = gateway.auth || {};
-  const port = gateway.port || 18789;
-  const bind = gateway.bind || 'loopback';
-  const host = bind === 'all' ? '127.0.0.1' : '127.0.0.1';
-  const gatewayUrl = `ws://${host}:${port}`;
-
-  return {
-    gatewayUrl,
-    token: typeof auth.token === 'string' ? auth.token.trim() : '',
-    password: typeof auth.password === 'string' ? auth.password.trim() : '',
-    configPath,
-  };
+  return deviceToken;
 }
 
-function resolveBridgeStatePath() {
-  return path.join(os.homedir(), '.openclaw', 'oomi-bridge.json');
+function resolvePersonaDeviceId(flags = {}) {
+  const bridgeState = readBridgeState();
+  const deviceId = String(
+    flags['device-id'] ||
+    bridgeState.deviceId ||
+    ''
+  ).trim();
+  if (!deviceId) {
+    throw new Error('Missing device id. Use --device-id or pair the device first.');
+  }
+  return deviceId;
 }
 
-function resolveBridgeStatusPath() {
-  return path.join(os.homedir(), '.openclaw', 'oomi-bridge-status.json');
+function createCliPersonaApiClient(flags = {}) {
+  return createPersonaApiClient({
+    backendUrl: resolvePersonaBackendUrl(flags),
+    deviceToken: resolvePersonaDeviceToken(flags),
+    deviceId: resolvePersonaDeviceId(flags),
+  });
 }
 
-function resolveBridgeLockPath() {
-  return path.join(os.homedir(), '.openclaw', 'oomi-bridge.lock');
+function isHttpErrorStatus(error, status) {
+  return Number(error?.status) === Number(status);
 }
 
-function resolveBridgeLiveLogPath() {
-  return path.join(os.homedir(), '.openclaw', 'logs', 'oomi-bridge-live.log');
+function resolvePersonaWorkspaceRoot(flags = {}) {
+  const workspaceRoot = String(flags['workspace-root'] || defaultPersonaWorkspaceRoot()).trim();
+  if (!workspaceRoot) {
+    throw new Error('Persona workspace root is required.');
+  }
+  return workspaceRoot;
 }
 
-function resolveBridgeLaunchAgentPlistPath() {
-  return path.join(os.homedir(), 'Library', 'LaunchAgents', `${BRIDGE_LAUNCHD_LABEL}.plist`);
+function resolvePersonaTemplateVersion(flags = {}, fallback = 'v1') {
+  return String(flags['template-version'] || fallback || 'v1').trim() || 'v1';
 }
 
-function defaultDeviceId() {
-  const host = os.hostname().toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24) || 'openclaw';
-  return `oomi-${host}-${randomUUID().slice(0, 8)}`;
+function resolvePersonaEntryUrl(flags = {}) {
+  return String(flags['entry-url'] || '').trim();
 }
 
-function resolveDeviceId(flags, bridgeState) {
-  const explicit = String(flags['device-id'] || process.env.OOMI_MANAGED_DEVICE_ID || '').trim();
-  if (explicit) return explicit;
-  const existing = String(bridgeState.deviceId || '').trim();
-  if (existing) return existing;
-  return defaultDeviceId();
+function resolvePersonaLaunchTransport(flags = {}) {
+  const explicitTransport = String(flags.transport || '').trim();
+  if (explicitTransport) {
+    return explicitTransport;
+  }
+
+  return resolvePersonaEntryUrl(flags) ? 'relay' : 'local';
 }
 
-function readBridgeState() {
-  const statePath = resolveBridgeStatePath();
-  if (!fs.existsSync(statePath)) return {};
+async function findExistingManagedPersona(client, slug) {
   try {
-    return JSON.parse(readFile(statePath));
-  } catch {
-    return {};
+    return await client.getPersona({ slug });
+  } catch (error) {
+    if (isHttpErrorStatus(error, 404)) {
+      return null;
+    }
+    throw error;
   }
 }
 
-function writeBridgeState(nextState) {
-  const statePath = resolveBridgeStatePath();
+function ensurePersonaJobWorkspace(message, workspaceRoot = defaultPersonaWorkspaceRoot()) {
+  const metadata = message && typeof message === 'object' ? message.metadata : null;
+  const payload = metadata && typeof metadata === 'object' ? metadata.payload : null;
+  if (!payload || typeof payload !== 'object') {
+    return message;
+  }
+
+  const persona = payload.persona && typeof payload.persona === 'object' ? payload.persona : {};
+  const scaffold = payload.scaffold && typeof payload.scaffold === 'object' ? payload.scaffold : {};
+  if (!scaffold.outDir && typeof persona.slug === 'string' && persona.slug.trim()) {
+    scaffold.outDir = path.join(workspaceRoot, persona.slug.trim());
+    payload.scaffold = scaffold;
+    metadata.payload = payload;
+    message.metadata = metadata;
+  }
+
+  return message;
+}
+
+async function runLegacyManagedPersonaJobExecution({
+  message,
+  backendUrl,
+  deviceToken,
+  deviceId,
+  workspaceRoot = defaultPersonaWorkspaceRoot(),
+  shouldInstall = true,
+  shouldStart = true,
+  shouldRegister = true,
+  logFilePath = '',
+}) {
+  const normalizedMessage = ensurePersonaJobWorkspace(
+    structuredClone(message),
+    workspaceRoot,
+  );
+  const client = createPersonaApiClient({
+    backendUrl,
+    deviceToken,
+    deviceId,
+  });
+
+  return executePersonaJob({
+    message: normalizedMessage,
+    installWorkspace: shouldInstall
+      ? async ({ workspacePath }) => {
+          await installPersonaWorkspace({ workspacePath });
+        }
+      : async () => {},
+    startWorkspace: shouldStart
+      ? async ({ workspacePath }) =>
+          startPersonaWorkspace({
+            workspacePath,
+            logFilePath,
+          })
+      : async () => ({ pid: null, logFilePath }),
+    waitForRuntime: shouldStart
+      ? async ({ runtime }) => {
+          await waitForPersonaRuntime({
+            healthcheckUrl: runtime.healthcheckUrl,
+          });
+        }
+      : async () => {},
+    registerRuntime: shouldRegister
+      ? async ({ payload: jobPayload, result: runtimeResult }) => {
+          const jobPersona = jobPayload.persona && typeof jobPayload.persona === 'object' ? jobPayload.persona : {};
+          await client.registerRuntime({
+            slug: String(jobPersona.slug || '').trim(),
+            endpoint: runtimeResult.endpoint,
+            healthcheckUrl: runtimeResult.healthcheckUrl,
+            transport: runtimeResult.transport,
+            localPort: runtimeResult.localPort,
+            startedAt: new Date().toISOString(),
+          });
+        }
+      : async () => {},
+    destroyWorkspace: async ({ payload: jobPayload }) => {
+      const jobPersona = jobPayload.persona && typeof jobPayload.persona === 'object' ? jobPayload.persona : {};
+      const safeSlug = String(jobPersona.slug || '').trim();
+      if (!safeSlug) {
+        throw new Error('Destroy persona job payload is missing persona.slug.');
+      }
+
+      return destroyManagedPersonaRuntime({
+        slug: safeSlug,
+        workspaceRoot,
+      });
+    },
+    onJobStart: async ({ jobId }) => {
+      await client.startJob({
+        jobId,
+        startedAt: new Date().toISOString(),
+      });
+    },
+    onJobSuccess: async ({ jobId, result: runtimeResult }) => {
+      await client.succeedJob({
+        jobId,
+        workspacePath: runtimeResult.workspacePath,
+        localPort: runtimeResult.localPort,
+        transport: runtimeResult.transport,
+        endpoint: runtimeResult.endpoint,
+        healthcheckUrl: runtimeResult.healthcheckUrl,
+        completedAt: new Date().toISOString(),
+      });
+    },
+    onJobFailure: async ({ jobId, error }) => {
+      await client.failJob({
+        jobId,
+        code: String(error?.code || 'PERSONA_JOB_EXECUTION_FAILED').trim(),
+        message: String(error?.message || 'Persona job execution failed.').trim(),
+        completedAt: new Date().toISOString(),
+      });
+    },
+  });
+}
+
+async function runManagedPersonaJobExecution({
+  message,
+  backendUrl,
+  deviceToken,
+  deviceId,
+  workspaceRoot = defaultPersonaWorkspaceRoot(),
+  shouldInstall = true,
+  shouldStart = true,
+  shouldRegister = true,
+  logFilePath = '',
+}) {
+  if (!shouldStart) {
+    return runLegacyManagedPersonaJobExecution({
+      message,
+      backendUrl,
+      deviceToken,
+      deviceId,
+      workspaceRoot,
+      shouldInstall,
+      shouldStart,
+      shouldRegister,
+      logFilePath,
+    });
+  }
+
+  const normalizedMessage = ensurePersonaJobWorkspace(
+    structuredClone(message),
+    workspaceRoot,
+  );
+  const client = createPersonaApiClient({
+    backendUrl,
+    deviceToken,
+    deviceId,
+  });
+  const payload = extractPersonaJobPayload(normalizedMessage);
+  const jobId = String(payload.jobId || normalizedMessage?.metadata?.jobId || '').trim();
+  if (!jobId) {
+    throw new Error('Persona job payload is missing jobId.');
+  }
+  if (!['create_persona_runtime', 'destroy_persona_runtime'].includes(payload.jobType)) {
+    throw new Error(`Unsupported persona job type: ${payload.jobType || 'unknown'}`);
+  }
+
+  const persona = payload.persona && typeof payload.persona === 'object' ? payload.persona : {};
+  const slug = String(persona.slug || '').trim();
+  const name = String(persona.name || '').trim();
+  const description = String(persona.description || '').trim() || name;
+  if (!slug || !name) {
+    throw new Error('Persona job payload is missing persona slug or name.');
+  }
+
+  await client.startJob({
+    jobId,
+    startedAt: new Date().toISOString(),
+  });
+
+  try {
+    if (payload.jobType === 'destroy_persona_runtime') {
+      const destroyResult = await destroyManagedPersonaRuntime({
+        slug,
+        workspaceRoot,
+      });
+
+      await client.succeedJob({
+        jobId,
+        workspacePath: destroyResult.workspacePath,
+        completedAt: new Date().toISOString(),
+      });
+
+      return {
+        ok: true,
+        jobId,
+        result: destroyResult,
+      };
+    }
+
+    const launchResult = await launchManagedPersonaRuntime({
+      slug,
+      name,
+      description,
+      workspaceRoot,
+      templateVersion: String(persona.templateVersion || 'v1').trim() || 'v1',
+      forceInstall: shouldInstall,
+      restart: false,
+      logFilePath,
+      entryUrl: '',
+      transport: 'local',
+    });
+
+    let registrationPayload = null;
+    if (shouldRegister) {
+      registrationPayload = await client.registerRuntime({
+        slug,
+        endpoint: launchResult.runtime.endpoint,
+        healthcheckUrl: launchResult.runtime.healthcheckUrl,
+        transport: launchResult.runtime.transport,
+        localPort: launchResult.runtime.localPort,
+        startedAt: new Date().toISOString(),
+      });
+    }
+
+    const result = {
+      workspacePath: launchResult.workspacePath,
+      localPort: launchResult.runtime.localPort,
+      transport: launchResult.runtime.transport,
+      endpoint: launchResult.runtime.endpoint,
+      healthcheckUrl: launchResult.runtime.healthcheckUrl,
+      pid: launchResult.state?.pid || null,
+      logFilePath: launchResult.state?.logFilePath || '',
+      templateVersion: launchResult.state?.templateVersion || String(persona.templateVersion || 'v1').trim() || 'v1',
+      reusedRunningProcess: launchResult.reusedRunningProcess,
+      scaffolded: launchResult.scaffolded,
+      installed: launchResult.installed,
+      registration: registrationPayload,
+    };
+
+    await client.succeedJob({
+      jobId,
+      workspacePath: result.workspacePath,
+      localPort: result.localPort,
+      transport: result.transport,
+      endpoint: result.endpoint,
+      healthcheckUrl: result.healthcheckUrl,
+      completedAt: new Date().toISOString(),
+    });
+
+    return {
+      ok: true,
+      jobId,
+      result,
+    };
+  } catch (error) {
+    const messageText = error instanceof Error ? error.message : 'Persona job execution failed.';
+    await client.failJob({
+      jobId,
+      code: 'PERSONA_JOB_EXECUTION_FAILED',
+      message: messageText,
+      completedAt: new Date().toISOString(),
+    });
+
+    return {
+      ok: false,
+      jobId,
+      error: {
+        code: 'PERSONA_JOB_EXECUTION_FAILED',
+        message: messageText,
+      },
+    };
+  }
+}
+
+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}`,
+      localPort,
+      transport,
+    };
+  }
+
+  if (!localPort) {
+    throw new Error('Runtime endpoint or local port is required.');
+  }
+
+  return buildLocalPersonaRuntime({
+    localPort,
+    healthPath,
+  });
+}
+
+function parseIsoTimestamp(rawValue, label) {
+  const value = String(rawValue || '').trim();
+  if (!value) return undefined;
+  const timestamp = new Date(value);
+  if (Number.isNaN(timestamp.getTime())) {
+    throw new Error(`${label} must be a valid ISO timestamp.`);
+  }
+  return timestamp.toISOString();
+}
+
+function readStructuredPersonaJobMessage(flags = {}) {
+  const filePath = String(flags['message-file'] || '').trim();
+  const inlineJson = String(flags['message-json'] || '').trim();
+
+  if (inlineJson) {
+    return JSON.parse(inlineJson);
+  }
+  if (filePath) {
+    return JSON.parse(readFile(path.resolve(filePath)));
+  }
+
+  throw new Error('Persona job message is required. Use --message-file or --message-json.');
+}
+
+function printStructuredResult(result, asJson = false) {
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  for (const [key, value] of Object.entries(result)) {
+    console.log(`${key}: ${typeof value === 'object' ? JSON.stringify(value) : value}`);
+  }
+}
+
+async function handlePersonaRuntimeRegisterCommand(slug, flags = {}) {
+  const client = createCliPersonaApiClient(flags);
+  const runtime = resolvePersonaRuntimeInput(flags);
+  const payload = await client.registerRuntime({
+    slug,
+    endpoint: runtime.endpoint,
+    healthcheckUrl: runtime.healthcheckUrl,
+    localPort: runtime.localPort,
+    transport: runtime.transport,
+    startedAt: parseIsoTimestamp(flags['started-at'], 'started-at'),
+  });
+  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,
+    healthcheckUrl: runtime.healthcheckUrl,
+    localPort: runtime.localPort,
+    transport: runtime.transport,
+    observedAt: parseIsoTimestamp(flags['observed-at'], 'observed-at'),
+  });
+  printStructuredResult(payload, isTruthyFlag(flags.json));
+}
+
+async function handlePersonaRuntimeFailCommand(slug, flags = {}) {
+  const code = String(flags.code || '').trim();
+  const message = String(flags.message || '').trim();
+  if (!code) {
+    throw new Error('Error code is required. Use --code.');
+  }
+  if (!message) {
+    throw new Error('Error message is required. Use --message.');
+  }
+
+  const client = createCliPersonaApiClient(flags);
+  const payload = await client.failRuntime({
+    slug,
+    code,
+    message,
+  });
+  printStructuredResult(payload, isTruthyFlag(flags.json));
+}
+
+async function handlePersonaJobStartCommand(jobId, flags = {}) {
+  const client = createCliPersonaApiClient(flags);
+  const payload = await client.startJob({
+    jobId,
+    startedAt: parseIsoTimestamp(flags['started-at'], 'started-at'),
+  });
+  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,
+    workspacePath,
+    localPort: runtime.localPort,
+    transport: runtime.transport,
+    endpoint: runtime.endpoint,
+    healthcheckUrl: runtime.healthcheckUrl,
+    completedAt: parseIsoTimestamp(flags['completed-at'], 'completed-at'),
+  });
+  printStructuredResult(payload, isTruthyFlag(flags.json));
+}
+
+async function handlePersonaJobFailCommand(jobId, flags = {}) {
+  const code = String(flags.code || '').trim();
+  const message = String(flags.message || '').trim();
+  if (!code) {
+    throw new Error('Error code is required. Use --code.');
+  }
+  if (!message) {
+    throw new Error('Error message is required. Use --message.');
+  }
+
+  const client = createCliPersonaApiClient(flags);
+  const payload = await client.failJob({
+    jobId,
+    code,
+    message,
+    completedAt: parseIsoTimestamp(flags['completed-at'], 'completed-at'),
+  });
+  printStructuredResult(payload, isTruthyFlag(flags.json));
+}
+
+async function handlePersonaJobExecuteCommand(flags = {}) {
+  const message = readStructuredPersonaJobMessage(flags);
+  const shouldInstall = !isTruthyFlag(flags['no-install']);
+  const shouldStart = !isTruthyFlag(flags['no-start']);
+  const shouldRegister = !isTruthyFlag(flags['no-register']) && shouldStart;
+  const logFilePath = String(flags['log-file'] || '').trim();
+  const result = await runManagedPersonaJobExecution({
+    message,
+    backendUrl: resolvePersonaBackendUrl(flags),
+    deviceToken: resolvePersonaDeviceToken(flags),
+    deviceId: resolvePersonaDeviceId(flags),
+    workspaceRoot: String(flags['workspace-root'] || defaultPersonaWorkspaceRoot()).trim(),
+    shouldInstall,
+    shouldStart,
+    shouldRegister,
+    logFilePath,
+  });
+
+  printStructuredResult(result, isTruthyFlag(flags.json));
+}
+
+async function handlePersonaCreateManagedCommand(flags = {}, positionalSlug = '') {
+  const name = String(flags.name || '').trim();
+  if (!name) {
+    throw new Error('Persona name is required. Usage: oomi personas create-managed [slug] --name "<name>" --description "<description>"');
+  }
+
+  const description = String(flags.description || '').trim() || name;
+  const explicitSlug = String(flags.slug || positionalSlug || '').trim();
+  const client = createCliPersonaApiClient(flags);
+  const result = await client.createManagedPersona({
+    slug: explicitSlug,
+    name,
+    description,
+    templateType: String(flags['template-type'] || 'persona-app').trim() || 'persona-app',
+    promptTemplateVersion: String(flags['template-version'] || 'v1').trim() || 'v1',
+  });
+
+  printManagedPersonaCreateResult(result, isTruthyFlag(flags.json));
+}
+
+async function handlePersonaLaunchManagedCommand(flags = {}, positionalSlug = '') {
+  const client = createCliPersonaApiClient(flags);
+  const safeName = String(flags.name || '').trim();
+  const safeDescription = String(flags.description || '').trim() || safeName;
+  const safeSlug = String(flags.slug || positionalSlug || (safeName ? slugifyPersonaName(safeName) : '')).trim();
+  if (!safeSlug) {
+    throw new Error('Persona slug or name is required. Usage: oomi personas launch-managed [slug] --name "<name>"');
+  }
+
+  const shouldCreate = !isTruthyFlag(flags['no-create']);
+  let createdPersona = false;
+  let personaPayload = await findExistingManagedPersona(client, safeSlug);
+  if (!personaPayload) {
+    if (!shouldCreate) {
+      throw new Error(`Managed persona ${safeSlug} does not exist in Oomi. Remove --no-create or create it first.`);
+    }
+    if (!safeName) {
+      throw new Error('Persona name is required when creating a new managed persona.');
+    }
+    personaPayload = await client.createManagedPersona({
+      slug: safeSlug,
+      name: safeName,
+      description: safeDescription,
+      templateType: 'persona-app',
+      promptTemplateVersion: resolvePersonaTemplateVersion(flags),
+    });
+    createdPersona = true;
+  }
+
+  const persona = personaPayload?.persona && typeof personaPayload.persona === 'object' ? personaPayload.persona : {};
+  const launchResult = await launchManagedPersonaRuntime({
+    slug: String(persona.slug || safeSlug).trim(),
+    name: String(persona.name || safeName || safeSlug).trim(),
+    description: String(persona.description || safeDescription || safeName || safeSlug).trim(),
+    workspaceRoot: resolvePersonaWorkspaceRoot(flags),
+    templateVersion: String(persona.promptTemplateVersion || resolvePersonaTemplateVersion(flags)).trim() || 'v1',
+    forceInstall: isTruthyFlag(flags['force-install']),
+    restart: isTruthyFlag(flags.restart),
+    logFilePath: String(flags['log-file'] || '').trim(),
+    entryUrl: resolvePersonaEntryUrl(flags),
+    transport: resolvePersonaLaunchTransport(flags),
+  });
+
+  let registrationPayload = null;
+  if (!isTruthyFlag(flags['no-register'])) {
+    registrationPayload = await client.registerRuntime({
+      slug: launchResult.slug,
+      endpoint: launchResult.runtime.endpoint,
+      healthcheckUrl: launchResult.runtime.healthcheckUrl,
+      localPort: launchResult.runtime.localPort,
+      transport: launchResult.runtime.transport,
+      startedAt: parseIsoTimestamp(flags['started-at'], 'started-at') || new Date().toISOString(),
+    });
+  }
+
+  printStructuredResult({
+    ok: true,
+    persona,
+    createdPersona,
+    launch: {
+      slug: launchResult.slug,
+      workspacePath: launchResult.workspacePath,
+      scaffolded: launchResult.scaffolded,
+      installed: launchResult.installed,
+      reusedRunningProcess: launchResult.reusedRunningProcess,
+    },
+    runtime: launchResult.runtime,
+    localRuntime: launchResult.localRuntime,
+    state: launchResult.state,
+    registration: registrationPayload,
+  }, isTruthyFlag(flags.json));
+}
+
+async function handlePersonaStatusCommand(slug, flags = {}) {
+  const result = getManagedPersonaRuntimeStatus({
+    slug,
+    workspaceRoot: resolvePersonaWorkspaceRoot(flags),
+  });
+  printStructuredResult(result, isTruthyFlag(flags.json));
+}
+
+async function handlePersonaStopCommand(slug, flags = {}) {
+  const result = await stopManagedPersonaRuntime({
+    slug,
+    workspaceRoot: resolvePersonaWorkspaceRoot(flags),
+  });
+  printStructuredResult(result, isTruthyFlag(flags.json));
+}
+
+async function handlePersonaDeleteCommand(slug, flags = {}) {
+  const result = await destroyManagedPersonaRuntime({
+    slug,
+    workspaceRoot: resolvePersonaWorkspaceRoot(flags),
+  });
+  printStructuredResult(result, isTruthyFlag(flags.json));
+}
+
+function resolveOpenclawConfigPath() {
+  const candidates = resolveOpenclawConfigCandidates();
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function readOpenclawGatewayConfig() {
+  const configPath = resolveOpenclawConfigPath();
+  if (!configPath) {
+    const openclawHome = resolveOpenclawHome();
+    throw new Error(`OpenClaw config not found (${path.join(openclawHome, 'clawdbot.json')} or ${path.join(openclawHome, 'openclaw.json')}).`);
+  }
+
+  const parsed = JSON.parse(readFile(configPath));
+  const gateway = parsed.gateway || {};
+  const auth = gateway.auth || {};
+  const port = gateway.port || 18789;
+  const bind = gateway.bind || 'loopback';
+  const host = bind === 'all' ? '127.0.0.1' : '127.0.0.1';
+  const gatewayUrl = `ws://${host}:${port}`;
+
+  return {
+    gatewayUrl,
+    token: typeof auth.token === 'string' ? auth.token.trim() : '',
+    password: typeof auth.password === 'string' ? auth.password.trim() : '',
+    configPath,
+  };
+}
+
+function resolveBridgeStatePath() {
+  return resolveOpenclawBridgeStatePath();
+}
+
+function resolveBridgeStatusPath() {
+  return resolveOpenclawBridgeStatusPath();
+}
+
+function resolveBridgeLockPath() {
+  return resolveOpenclawBridgeLockPath();
+}
+
+function resolveBridgeLiveLogPath() {
+  return resolveOpenclawBridgeLiveLogPath();
+}
+
+function resolveBridgeLaunchAgentPlistPath() {
+  return path.join(os.homedir(), 'Library', 'LaunchAgents', `${BRIDGE_LAUNCHD_LABEL}.plist`);
+}
+
+function defaultDeviceId() {
+  const host = os.hostname().toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24) || 'openclaw';
+  return `oomi-${host}-${randomUUID().slice(0, 8)}`;
+}
+
+function resolveDeviceId(flags, bridgeState) {
+  const explicit = String(flags['device-id'] || process.env.OOMI_MANAGED_DEVICE_ID || '').trim();
+  if (explicit) return explicit;
+  const existing = String(bridgeState.deviceId || '').trim();
+  if (existing) return existing;
+  return defaultDeviceId();
+}
+
+function readBridgeState() {
+  const statePath = resolveBridgeStatePath();
+  if (!fs.existsSync(statePath)) return {};
+  try {
+    return JSON.parse(readFile(statePath));
+  } catch {
+    return {};
+  }
+}
+
+function writeBridgeState(nextState) {
+  const statePath = resolveBridgeStatePath();
   ensureDir(path.dirname(statePath));
   writeFile(statePath, JSON.stringify(nextState, null, 2) + '\n');
 }
@@ -1714,499 +2073,847 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
   }
 }
 
-function parseJsonPayload(raw) {
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-function extractTextFromGatewayMessage(message) {
-  if (!message || typeof message !== 'object') return '';
-
-  if (typeof message.content === 'string' && message.content.trim()) {
-    return message.content.trim();
-  }
-
-  if (!Array.isArray(message.content)) return '';
-
-  return message.content
-    .filter((block) => block && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string')
-    .map((block) => block.text.trim())
-    .filter(Boolean)
-    .join(' ');
-}
-
-function summarizeVoiceFrameContract(frameText) {
-  const frame = parseJsonPayload(frameText);
-  if (!frame || typeof frame !== 'object') {
-    return { parseable: false };
-  }
-  const payload = frame.payload && typeof frame.payload === 'object' ? frame.payload : {};
-  const message = payload.message && typeof payload.message === 'object' ? payload.message : {};
-  const metadata = message.metadata && typeof message.metadata === 'object' ? message.metadata : {};
-  const spokenRaw = Object.prototype.hasOwnProperty.call(metadata, 'spoken') ? metadata.spoken : undefined;
-  const spokenNormalized = normalizeSpokenMetadata(spokenRaw);
-  const text = extractTextFromGatewayMessage(message);
-  return {
-    parseable: true,
-    event: typeof frame.event === 'string' ? frame.event : '',
-    state: typeof payload.state === 'string' ? payload.state : '',
-    role: typeof message.role === 'string' ? message.role : '',
-    contentLength: text.length,
-    hasMetadata: Object.keys(metadata).length > 0,
-    hasSpokenKey: Object.prototype.hasOwnProperty.call(metadata, 'spoken'),
-    spokenRawType: spokenRaw === undefined ? 'missing' : Array.isArray(spokenRaw) ? 'array' : typeof spokenRaw,
-    spokenNormalized: Boolean(spokenNormalized),
-    spokenSegmentCount: Array.isArray(spokenNormalized?.segments) ? spokenNormalized.segments.length : 0,
-  };
-}
-
-function ensureAssistantSpokenMetadata(frameText) {
-  const frame = parseJsonPayload(frameText);
-  if (!frame || typeof frame !== 'object') {
-    return { frameText, changed: false, reason: '' };
-  }
-  if (frame.type !== 'event' || frame.event !== 'chat') {
-    return { frameText, changed: false, reason: '' };
-  }
-
-  const payload = frame.payload && typeof frame.payload === 'object' ? frame.payload : null;
-  if (!payload || payload.state !== 'final') {
-    return { frameText, changed: false, reason: '' };
-  }
-
-  const message = payload.message && typeof payload.message === 'object' ? payload.message : null;
-  if (!message) {
-    return { frameText, changed: false, reason: '' };
-  }
-
-  const messageRole = typeof message.role === 'string' ? message.role.trim() : '';
-  if (messageRole && messageRole !== 'assistant') {
-    return { frameText, changed: false, reason: '' };
-  }
-
-  const originalMetadata =
-    message.metadata && typeof message.metadata === 'object' && !Array.isArray(message.metadata)
-      ? message.metadata
-      : {};
-  const metadata = { ...originalMetadata };
-  const normalizedExplicitSpoken = normalizeSpokenMetadata(originalMetadata.spoken);
-  const spoken =
-    normalizedExplicitSpoken ||
-    inferSpokenMetadataFromContent(extractTextFromGatewayMessage(message));
-  if (!spoken) {
-    return { frameText, changed: false, reason: '' };
-  }
-
-  metadata.spoken = spoken;
-  const nextFrame = JSON.stringify({
-    ...frame,
-    payload: {
-      ...payload,
-      message: {
-        ...message,
-        metadata,
-      },
-    },
-  });
-
-  return {
-    frameText: nextFrame,
-    changed: nextFrame !== frameText,
-    reason: normalizedExplicitSpoken ? 'normalized' : (messageRole ? 'synthesized' : 'synthesized_missing_role'),
-  };
-}
-
-function normalizeAssistantGatewayFrame(sessionId, frameText) {
-  const scope = classifyBridgeSessionScope(sessionId);
-  const summary = summarizeVoiceFrameContract(frameText);
-  if (!summary.parseable || summary.event !== 'chat' || summary.state !== 'final') {
-    return {
-      frameText,
-      changed: false,
-      reason: '',
-      scope,
-      summary,
-    };
-  }
-
-  const normalized = ensureAssistantSpokenMetadata(frameText);
-  return {
-    ...normalized,
-    scope,
-    summary,
-  };
-}
-
-function buildAssistantFinalDebugFrame({ sessionKey, text, role }) {
-  const trimmedSessionKey =
-    typeof sessionKey === 'string' && sessionKey.trim()
-      ? sessionKey.trim()
-      : 'agent:main:webchat:channel:oomi';
-  const message = {
-    content: String(text || ''),
-  };
-  if (typeof role === 'string' && role.trim()) {
-    message.role = role.trim();
-  }
-  return JSON.stringify({
-    type: 'event',
-    event: 'chat',
-    payload: {
-      sessionKey: trimmedSessionKey,
-      state: 'final',
-      message,
-    },
-  });
-}
-
-function extractSpokenMetadata(frameText) {
-  const payload = parseJsonPayload(frameText);
-  const message =
-    payload &&
-    payload.payload &&
-    typeof payload.payload === 'object' &&
-    payload.payload.message &&
-    typeof payload.payload.message === 'object'
-      ? payload.payload.message
-      : null;
-  const metadata =
-    message &&
-    message.metadata &&
-    typeof message.metadata === 'object' &&
-    !Array.isArray(message.metadata)
-      ? message.metadata
-      : {};
-  return normalizeSpokenMetadata(metadata.spoken);
-}
-
-function runAssistantFinalDebugCheck(options = {}) {
-  const sessionId =
-    typeof options.sessionId === 'string' && options.sessionId.trim()
-      ? options.sessionId.trim()
-      : 'ms_debug_local';
-  const sessionKey =
-    typeof options.sessionKey === 'string' && options.sessionKey.trim()
-      ? options.sessionKey.trim()
-      : 'agent:main:webchat:channel:oomi';
-  const role =
-    options.omitRole
-      ? ''
-      : (typeof options.role === 'string' && options.role.trim() ? options.role.trim() : 'assistant');
-
-  const rawFrameText =
-    typeof options.frameText === 'string' && options.frameText.trim()
-      ? options.frameText
-      : buildAssistantFinalDebugFrame({
-          sessionKey,
-          text: options.text,
-          role,
-        });
-
-  const before = summarizeVoiceFrameContract(rawFrameText);
-  const normalized = normalizeAssistantGatewayFrame(sessionId, rawFrameText);
-  const after = summarizeVoiceFrameContract(normalized.frameText);
-  const spoken = extractSpokenMetadata(normalized.frameText);
-
-  return {
-    sessionId,
-    sessionKey,
-    scope: normalized.scope,
-    changed: normalized.changed,
-    reason: normalized.reason,
-    before,
-    after,
-    spoken,
-    frameText: normalized.frameText,
-  };
-}
-
-function printAssistantFinalDebugResult(result, asJson) {
-  if (asJson) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-
-  console.log(`Session id: ${result.sessionId}`);
-  console.log(`Session key: ${result.sessionKey}`);
-  console.log(`Scope: ${result.scope}`);
-  console.log(`Changed: ${result.changed ? 'yes' : 'no'}${result.reason ? ` (${result.reason})` : ''}`);
-  console.log(
-    `Before: event=${result.before.event || '<none>'} state=${result.before.state || '<none>'} role=${result.before.role || '<none>'} spoken=${result.before.spokenNormalized ? 'yes' : 'no'}`
-  );
-  console.log(
-    `After: event=${result.after.event || '<none>'} state=${result.after.state || '<none>'} role=${result.after.role || '<none>'} spoken=${result.after.spokenNormalized ? 'yes' : 'no'}`
-  );
-  if (result.spoken) {
-    console.log(`Spoken text: ${result.spoken.text}`);
-    console.log(`Segments: ${Array.isArray(result.spoken.segments) ? result.spoken.segments.length : 0}`);
-    if (typeof result.spoken.instructions === 'string' && result.spoken.instructions.trim()) {
-      console.log(`Instructions: ${result.spoken.instructions}`);
-    }
-  } else {
-    console.log('Spoken text: <missing>');
-  }
-}
-
-function resolveCommandFromPath(commandName) {
-  const normalized = String(commandName || '').trim();
-  if (!normalized) return '';
-  try {
-    const probe = spawnSync(process.platform === 'win32' ? 'where' : 'which', [normalized], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    });
-    if (probe.status !== 0) return '';
-    const firstLine = String(probe.stdout || '')
-      .split(/\r?\n/)
-      .map((line) => line.trim())
-      .find(Boolean);
-    return firstLine || '';
-  } catch {
-    return '';
-  }
-}
-
-function resolveExecutable(candidates = []) {
-  for (const candidate of candidates) {
-    if (!candidate) continue;
-    const value = String(candidate).trim();
-    if (!value) continue;
-    if (path.isAbsolute(value) && fs.existsSync(value)) {
-      return value;
-    }
-    if (value.includes(path.sep) || value.includes('/')) {
-      const resolved = path.resolve(value);
-      if (fs.existsSync(resolved)) {
-        return resolved;
-      }
-      continue;
-    }
-    const fromPath = resolveCommandFromPath(value);
-    if (fromPath) {
-      return fromPath;
-    }
-  }
-  return '';
-}
-
-function resolveBackendRoot(rootFlag) {
-  const repoRoot = resolveRepoRoot(rootFlag);
-  const backendRoot = path.join(repoRoot, 'apps', 'backend');
-  if (!fs.existsSync(backendRoot)) {
-    throw new Error(`Could not locate backend app at ${backendRoot}`);
-  }
-  return backendRoot;
-}
-
-function resolveRubyExecutable() {
-  const candidates = [
-    process.env.OOMI_RUBY_BIN,
-    process.env.RUBY,
-    process.platform === 'win32' ? 'ruby.exe' : 'ruby',
-    process.platform === 'win32' ? 'ruby' : '',
-    process.platform === 'win32' ? 'C:\\Ruby33-x64\\bin\\ruby.exe' : '',
-  ];
-  const executable = resolveExecutable(candidates);
-  if (!executable) {
-    throw new Error('Ruby executable not found. Set OOMI_RUBY_BIN or install Ruby locally.');
-  }
-  return executable;
-}
-
-function resolveBundleExecutable() {
-  const candidates = [
-    process.env.OOMI_BUNDLE_BIN,
-    process.platform === 'win32' ? 'bundle.bat' : 'bundle',
-    'bundle',
-    process.platform === 'win32' ? 'C:\\Ruby33-x64\\bin\\bundle.bat' : '',
-  ];
-  const executable = resolveExecutable(candidates);
-  if (!executable) {
-    throw new Error('Bundler executable not found. Set OOMI_BUNDLE_BIN or install Bundler locally.');
-  }
-  return executable;
-}
-
-function shellQuote(value) {
-  const text = String(value);
-  if (process.platform === 'win32') {
-    return `"${text.replace(/"/g, '""')}"`;
-  }
-  return `'${text.replace(/'/g, `'\\''`)}'`;
-}
-
-async function runBundledRubyScript({ backendRoot, scriptPath, inputFile, env = undefined }) {
-  const rubyExecutable = resolveRubyExecutable();
-  const bundleExecutable = resolveBundleExecutable();
-  const commandText = process.platform === 'win32'
-    ? [bundleExecutable, 'exec', rubyExecutable, scriptPath, '--input-file', inputFile].map(shellQuote).join(' ')
-    : '';
-  const childEnv = env ? { ...process.env, ...env } : process.env;
-
-  return await new Promise((resolve, reject) => {
-    const child = process.platform === 'win32'
-      ? spawn(commandText, [], {
-          cwd: backendRoot,
-          shell: true,
-          env: childEnv,
-          stdio: ['ignore', 'pipe', 'pipe'],
-        })
-      : spawn(bundleExecutable, ['exec', rubyExecutable, scriptPath, '--input-file', inputFile], {
-          cwd: backendRoot,
-          env: childEnv,
-          stdio: ['ignore', 'pipe', 'pipe'],
-        });
-
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => {
-      stdout += chunk.toString();
-    });
-    child.stderr.on('data', (chunk) => {
-      stderr += chunk.toString();
-    });
-    child.on('error', reject);
-    child.on('close', (code) => {
-      resolve({ code: Number(code || 0), stdout, stderr });
-    });
+function parseJsonPayload(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function extractTextFromGatewayMessage(message) {
+  if (!message || typeof message !== 'object') return '';
+
+  if (typeof message.content === 'string' && message.content.trim()) {
+    return message.content.trim();
+  }
+
+  if (!Array.isArray(message.content)) return '';
+
+  return message.content
+    .filter((block) => block && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text.trim())
+    .filter(Boolean)
+    .join(' ');
+}
+
+function summarizeVoiceFrameContract(frameText) {
+  const frame = parseJsonPayload(frameText);
+  if (!frame || typeof frame !== 'object') {
+    return { parseable: false };
+  }
+  const payload = frame.payload && typeof frame.payload === 'object' ? frame.payload : {};
+  const message = payload.message && typeof payload.message === 'object' ? payload.message : {};
+  const metadata = message.metadata && typeof message.metadata === 'object' ? message.metadata : {};
+  const spokenRaw = Object.prototype.hasOwnProperty.call(metadata, 'spoken') ? metadata.spoken : undefined;
+  const spokenNormalized = normalizeSpokenMetadata(spokenRaw);
+  const text = extractTextFromGatewayMessage(message);
+  return {
+    parseable: true,
+    event: typeof frame.event === 'string' ? frame.event : '',
+    state: typeof payload.state === 'string' ? payload.state : '',
+    role: typeof message.role === 'string' ? message.role : '',
+    contentLength: text.length,
+    hasMetadata: Object.keys(metadata).length > 0,
+    hasSpokenKey: Object.prototype.hasOwnProperty.call(metadata, 'spoken'),
+    spokenRawType: spokenRaw === undefined ? 'missing' : Array.isArray(spokenRaw) ? 'array' : typeof spokenRaw,
+    spokenNormalized: Boolean(spokenNormalized),
+    spokenSegmentCount: Array.isArray(spokenNormalized?.segments) ? spokenNormalized.segments.length : 0,
+  };
+}
+
+function ensureAssistantSpokenMetadata(frameText) {
+  const frame = parseJsonPayload(frameText);
+  if (!frame || typeof frame !== 'object') {
+    return { frameText, changed: false, reason: '' };
+  }
+  if (frame.type !== 'event' || frame.event !== 'chat') {
+    return { frameText, changed: false, reason: '' };
+  }
+
+  const payload = frame.payload && typeof frame.payload === 'object' ? frame.payload : null;
+  if (!payload || payload.state !== 'final') {
+    return { frameText, changed: false, reason: '' };
+  }
+
+  const message = payload.message && typeof payload.message === 'object' ? payload.message : null;
+  if (!message) {
+    return { frameText, changed: false, reason: '' };
+  }
+
+  const messageRole = typeof message.role === 'string' ? message.role.trim() : '';
+  if (messageRole && messageRole !== 'assistant') {
+    return { frameText, changed: false, reason: '' };
+  }
+
+  const originalMetadata =
+    message.metadata && typeof message.metadata === 'object' && !Array.isArray(message.metadata)
+      ? message.metadata
+      : {};
+  const metadata = { ...originalMetadata };
+  const normalizedExplicitSpoken = normalizeSpokenMetadata(originalMetadata.spoken);
+  const spoken =
+    normalizedExplicitSpoken ||
+    inferSpokenMetadataFromContent(extractTextFromGatewayMessage(message));
+  if (!spoken) {
+    return { frameText, changed: false, reason: '' };
+  }
+
+  metadata.spoken = spoken;
+  const nextFrame = JSON.stringify({
+    ...frame,
+    payload: {
+      ...payload,
+      message: {
+        ...message,
+        metadata,
+      },
+    },
+  });
+
+  return {
+    frameText: nextFrame,
+    changed: nextFrame !== frameText,
+    reason: normalizedExplicitSpoken ? 'normalized' : (messageRole ? 'synthesized' : 'synthesized_missing_role'),
+  };
+}
+
+function normalizeAssistantGatewayFrame(sessionId, frameText) {
+  const scope = classifyBridgeSessionScope(sessionId);
+  const summary = summarizeVoiceFrameContract(frameText);
+  if (!summary.parseable || summary.event !== 'chat' || summary.state !== 'final') {
+    return {
+      frameText,
+      changed: false,
+      reason: '',
+      scope,
+      summary,
+    };
+  }
+
+  const normalized = ensureAssistantSpokenMetadata(frameText);
+  return {
+    ...normalized,
+    scope,
+    summary,
+  };
+}
+
+function buildAssistantFinalDebugFrame({ sessionKey, text, role }) {
+  const trimmedSessionKey =
+    typeof sessionKey === 'string' && sessionKey.trim()
+      ? sessionKey.trim()
+      : 'agent:main:webchat:channel:oomi';
+  const message = {
+    content: String(text || ''),
+  };
+  if (typeof role === 'string' && role.trim()) {
+    message.role = role.trim();
+  }
+  return JSON.stringify({
+    type: 'event',
+    event: 'chat',
+    payload: {
+      sessionKey: trimmedSessionKey,
+      state: 'final',
+      message,
+    },
+  });
+}
+
+function extractSpokenMetadata(frameText) {
+  const payload = parseJsonPayload(frameText);
+  const message =
+    payload &&
+    payload.payload &&
+    typeof payload.payload === 'object' &&
+    payload.payload.message &&
+    typeof payload.payload.message === 'object'
+      ? payload.payload.message
+      : null;
+  const metadata =
+    message &&
+    message.metadata &&
+    typeof message.metadata === 'object' &&
+    !Array.isArray(message.metadata)
+      ? message.metadata
+      : {};
+  return normalizeSpokenMetadata(metadata.spoken);
+}
+
+function runAssistantFinalDebugCheck(options = {}) {
+  const sessionId =
+    typeof options.sessionId === 'string' && options.sessionId.trim()
+      ? options.sessionId.trim()
+      : 'ms_debug_local';
+  const sessionKey =
+    typeof options.sessionKey === 'string' && options.sessionKey.trim()
+      ? options.sessionKey.trim()
+      : 'agent:main:webchat:channel:oomi';
+  const role =
+    options.omitRole
+      ? ''
+      : (typeof options.role === 'string' && options.role.trim() ? options.role.trim() : 'assistant');
+
+  const rawFrameText =
+    typeof options.frameText === 'string' && options.frameText.trim()
+      ? options.frameText
+      : buildAssistantFinalDebugFrame({
+          sessionKey,
+          text: options.text,
+          role,
+        });
+
+  const before = summarizeVoiceFrameContract(rawFrameText);
+  const normalized = normalizeAssistantGatewayFrame(sessionId, rawFrameText);
+  const after = summarizeVoiceFrameContract(normalized.frameText);
+  const spoken = extractSpokenMetadata(normalized.frameText);
+
+  return {
+    sessionId,
+    sessionKey,
+    scope: normalized.scope,
+    changed: normalized.changed,
+    reason: normalized.reason,
+    before,
+    after,
+    spoken,
+    frameText: normalized.frameText,
+  };
+}
+
+function printAssistantFinalDebugResult(result, asJson) {
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`Session id: ${result.sessionId}`);
+  console.log(`Session key: ${result.sessionKey}`);
+  console.log(`Scope: ${result.scope}`);
+  console.log(`Changed: ${result.changed ? 'yes' : 'no'}${result.reason ? ` (${result.reason})` : ''}`);
+  console.log(
+    `Before: event=${result.before.event || '<none>'} state=${result.before.state || '<none>'} role=${result.before.role || '<none>'} spoken=${result.before.spokenNormalized ? 'yes' : 'no'}`
+  );
+  console.log(
+    `After: event=${result.after.event || '<none>'} state=${result.after.state || '<none>'} role=${result.after.role || '<none>'} spoken=${result.after.spokenNormalized ? 'yes' : 'no'}`
+  );
+  if (result.spoken) {
+    console.log(`Spoken text: ${result.spoken.text}`);
+    console.log(`Segments: ${Array.isArray(result.spoken.segments) ? result.spoken.segments.length : 0}`);
+    if (typeof result.spoken.instructions === 'string' && result.spoken.instructions.trim()) {
+      console.log(`Instructions: ${result.spoken.instructions}`);
+    }
+  } else {
+    console.log('Spoken text: <missing>');
+  }
+}
+
+function resolveCommandFromPath(commandName) {
+  const normalized = String(commandName || '').trim();
+  if (!normalized) return '';
+  try {
+    const probe = spawnSync(process.platform === 'win32' ? 'where' : 'which', [normalized], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (probe.status !== 0) return '';
+    const firstLine = String(probe.stdout || '')
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .find(Boolean);
+    return firstLine || '';
+  } catch {
+    return '';
+  }
+}
+
+function resolveExecutable(candidates = []) {
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    const value = String(candidate).trim();
+    if (!value) continue;
+    if (path.isAbsolute(value) && fs.existsSync(value)) {
+      return value;
+    }
+    if (value.includes(path.sep) || value.includes('/')) {
+      const resolved = path.resolve(value);
+      if (fs.existsSync(resolved)) {
+        return resolved;
+      }
+      continue;
+    }
+    const fromPath = resolveCommandFromPath(value);
+    if (fromPath) {
+      return fromPath;
+    }
+  }
+  return '';
+}
+
+function resolveBackendRoot(rootFlag) {
+  const repoRoot = resolveRepoRoot(rootFlag);
+  const backendRoot = path.join(repoRoot, 'apps', 'backend');
+  if (!fs.existsSync(backendRoot)) {
+    throw new Error(`Could not locate backend app at ${backendRoot}`);
+  }
+  return backendRoot;
+}
+
+function resolveRubyExecutable() {
+  const candidates = [
+    process.env.OOMI_RUBY_BIN,
+    process.env.RUBY,
+    process.platform === 'win32' ? 'ruby.exe' : 'ruby',
+    process.platform === 'win32' ? 'ruby' : '',
+    process.platform === 'win32' ? 'C:\\Ruby33-x64\\bin\\ruby.exe' : '',
+  ];
+  const executable = resolveExecutable(candidates);
+  if (!executable) {
+    throw new Error('Ruby executable not found. Set OOMI_RUBY_BIN or install Ruby locally.');
+  }
+  return executable;
+}
+
+function resolveBundleExecutable() {
+  const candidates = [
+    process.env.OOMI_BUNDLE_BIN,
+    process.platform === 'win32' ? 'bundle.bat' : 'bundle',
+    'bundle',
+    process.platform === 'win32' ? 'C:\\Ruby33-x64\\bin\\bundle.bat' : '',
+  ];
+  const executable = resolveExecutable(candidates);
+  if (!executable) {
+    throw new Error('Bundler executable not found. Set OOMI_BUNDLE_BIN or install Bundler locally.');
+  }
+  return executable;
+}
+
+function shellQuote(value) {
+  const text = String(value);
+  if (process.platform === 'win32') {
+    return `"${text.replace(/"/g, '""')}"`;
+  }
+  return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+
+async function runBundledRubyScript({ backendRoot, scriptPath, inputFile, env = undefined }) {
+  const rubyExecutable = resolveRubyExecutable();
+  const bundleExecutable = resolveBundleExecutable();
+  const commandText = process.platform === 'win32'
+    ? [bundleExecutable, 'exec', rubyExecutable, scriptPath, '--input-file', inputFile].map(shellQuote).join(' ')
+    : '';
+  const childEnv = env ? { ...process.env, ...env } : process.env;
+
+  return await new Promise((resolve, reject) => {
+    const child = process.platform === 'win32'
+      ? spawn(commandText, [], {
+          cwd: backendRoot,
+          shell: true,
+          env: childEnv,
+          stdio: ['ignore', 'pipe', 'pipe'],
+        })
+      : spawn(bundleExecutable, ['exec', rubyExecutable, scriptPath, '--input-file', inputFile], {
+          cwd: backendRoot,
+          env: childEnv,
+          stdio: ['ignore', 'pipe', 'pipe'],
+        });
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      resolve({ code: Number(code || 0), stdout, stderr });
+    });
+  });
+}
+
+async function runLocalTtsPipelineDebugCheck(options = {}) {
+  const assistant = runAssistantFinalDebugCheck(options);
+  const repoRoot = resolveRepoRoot(options.root);
+  const backendRoot = resolveBackendRoot(options.root);
+  const scriptPath = path.join(backendRoot, 'bin', 'voice_tts_replay.rb');
+  if (!fs.existsSync(scriptPath)) {
+    throw new Error(`Backend replay script not found: ${scriptPath}`);
+  }
+
+  const inputPayload = {
+    repoRoot,
+    sessionId: assistant.sessionId,
+    sessionKey: assistant.sessionKey,
+    frameText: assistant.frameText,
+    userText:
+      typeof options.userText === 'string' && options.userText.trim()
+        ? options.userText.trim()
+        : 'local debug utterance',
+    liveProvider: Boolean(options.liveProvider),
+    providerTimeoutMs: parsePositiveInteger(options.providerTimeoutMs, 15000),
+  };
+  let childEnv = undefined;
+  let resolvedEnvFile = '';
+  if (options.liveProvider) {
+    resolvedEnvFile =
+      typeof options.envFile === 'string' && options.envFile.trim()
+        ? path.resolve(options.envFile.trim())
+        : path.join(repoRoot, '.env.local');
+    childEnv = loadEnvFile(resolvedEnvFile, DEBUG_PROVIDER_ENV_KEYS);
+  }
+  const inputFile = path.join(os.tmpdir(), `oomi-voice-replay-${randomUUID()}.json`);
+  writeFile(inputFile, JSON.stringify(inputPayload, null, 2) + '\n');
+
+  try {
+    const backend = await runBundledRubyScript({ backendRoot, scriptPath, inputFile, env: childEnv });
+    const parsed = backend.stdout.trim() ? JSON.parse(backend.stdout) : null;
+    return {
+      assistant,
+      backend: parsed,
+      backendExitCode: backend.code,
+      backendStderr: backend.stderr.trim(),
+      liveProvider: Boolean(options.liveProvider),
+      envFile: resolvedEnvFile || null,
+    };
+  } finally {
+    try {
+      fs.unlinkSync(inputFile);
+    } catch {
+      // no-op
+    }
+  }
+}
+
+function printTtsPipelineDebugResult(result, asJson) {
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`Assistant normalization: ${result.assistant.changed ? 'changed' : 'unchanged'}${result.assistant.reason ? ` (${result.assistant.reason})` : ''}`);
+  console.log(`Assistant spoken segments: ${Array.isArray(result.assistant.spoken?.segments) ? result.assistant.spoken.segments.length : 0}`);
+  if (!result.backend) {
+    console.log('Backend replay: <no output>');
+    return;
+  }
+  console.log(`Backend replay success: ${result.backend.success ? 'yes' : 'no'}`);
+  console.log(`Managed speech sidecar: ${result.backend.managed?.assistantSpeechFinal?.present ? 'yes' : 'no'}`);
+  console.log(`Backend final text: ${result.backend.qwen?.assistantTextFinal || '<missing>'}`);
+  console.log(`Backend TTS appends: ${Array.isArray(result.backend.qwen?.ttsAppends) ? result.backend.qwen.ttsAppends.length : 0}`);
+  console.log(`Backend TTS commits: ${Number(result.backend.qwen?.commitCount || 0)}`);
+  if (result.liveProvider) {
+    console.log(`Live provider audio deltas: ${Number(result.backend.qwen?.audioDeltaCount || 0)}`);
+    console.log(`Live provider audio bytes (base64): ${Number(result.backend.qwen?.audioDeltaBytes || 0)}`);
+    console.log(`Live provider timeout: ${result.backend.qwen?.providerTimedOut ? 'yes' : 'no'}`);
+  }
+  if (result.backend.qwen?.errorCode) {
+    console.log(`Backend error: ${result.backend.qwen.errorCode}`);
+  }
+  if (result.backendStderr) {
+    console.log(`Backend stderr: ${result.backendStderr}`);
+  }
+}
+
+async function runPersonaRuntimeDebugCheck(options = {}) {
+  const generatedWorkspaceRoot = !(
+    typeof options.workspaceRoot === 'string' && options.workspaceRoot.trim()
+  );
+  const workspaceRoot = generatedWorkspaceRoot
+    ? path.join(os.tmpdir(), `oomi-openclaw-dev-${randomUUID()}`, 'personas')
+    : path.resolve(String(options.workspaceRoot).trim());
+  const safeName =
+    typeof options.name === 'string' && options.name.trim()
+      ? options.name.trim()
+      : 'Persona Dev Smoke';
+  const safeDescription =
+    typeof options.description === 'string' && options.description.trim()
+      ? options.description.trim()
+      : 'Local OpenClaw persona runtime smoke test.';
+  const safeSlug =
+    typeof options.slug === 'string' && options.slug.trim()
+      ? options.slug.trim()
+      : slugifyPersonaName(safeName);
+  const leaveRunning = Boolean(options.leaveRunning);
+  const cleanup = Boolean(options.cleanup);
+
+  const launch = await launchManagedPersonaRuntime({
+    slug: safeSlug,
+    name: safeName,
+    description: safeDescription,
+    workspaceRoot,
+    forceInstall: Boolean(options.forceInstall),
+    restart: Boolean(options.restart),
+    entryUrl: '',
+    transport: 'local',
+  });
+  const statusAfterLaunch = getManagedPersonaRuntimeStatus({
+    slug: safeSlug,
+    workspaceRoot,
+  });
+
+  let stop = null;
+  let statusAfterStop = null;
+  if (!leaveRunning) {
+    stop = await stopManagedPersonaRuntime({
+      slug: safeSlug,
+      workspaceRoot,
+    });
+    statusAfterStop = getManagedPersonaRuntimeStatus({
+      slug: safeSlug,
+      workspaceRoot,
+    });
+  }
+
+  let cleanedUp = false;
+  if (cleanup && !leaveRunning && generatedWorkspaceRoot) {
+    cleanedUp = await cleanupPersonaRuntimeDebugWorkspace(path.resolve(workspaceRoot, '..'));
+  }
+
+  return {
+    ok: true,
+    workspaceRoot,
+    generatedWorkspaceRoot,
+    cleanedUp,
+    slug: safeSlug,
+    name: safeName,
+    description: safeDescription,
+    launch: {
+      slug: launch.slug,
+      workspacePath: launch.workspacePath,
+      scaffolded: launch.scaffolded,
+      installed: launch.installed,
+      reusedRunningProcess: launch.reusedRunningProcess,
+    },
+    runtime: launch.runtime,
+    localRuntime: launch.localRuntime,
+    state: launch.state,
+    statusAfterLaunch,
+    stop,
+    statusAfterStop,
+  };
+}
+
+async function cleanupPersonaRuntimeDebugWorkspace(rootPath) {
+  const targetPath = path.resolve(rootPath);
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    try {
+      fs.rmSync(targetPath, { recursive: true, force: true });
+      return true;
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+  }
+  return false;
+}
+
+function printPersonaRuntimeDebugResult(result, asJson) {
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`Persona slug: ${result.slug}`);
+  console.log(`Workspace root: ${result.workspaceRoot}`);
+  console.log(`Workspace: ${result.launch.workspacePath}`);
+  console.log(`Scaffolded: ${result.launch.scaffolded ? 'yes' : 'no'}`);
+  console.log(`Installed dependencies: ${result.launch.installed ? 'yes' : 'no'}`);
+  console.log(`Reused running process: ${result.launch.reusedRunningProcess ? 'yes' : 'no'}`);
+  console.log(`Local endpoint: ${result.localRuntime.endpoint}`);
+  console.log(`Local port: ${result.localRuntime.localPort}`);
+  console.log(`Healthcheck: ${result.localRuntime.healthcheckUrl}`);
+  console.log(`Process running after launch: ${result.statusAfterLaunch.processRunning ? 'yes' : 'no'}`);
+  if (result.stop) {
+    console.log(`Stopped runtime: ${result.stop.stopped ? 'yes' : 'no'}`);
+    console.log(`Process running after stop: ${result.statusAfterStop?.processRunning ? 'yes' : 'no'}`);
+  } else {
+    console.log('Runtime left running for inspection.');
+  }
+  if (result.cleanedUp) {
+    console.log('Temporary workspace cleaned up.');
+  }
+}
+
+async function runLocalGatewayAgentDebug(flags) {
+  const logger = isTruthyFlag(flags.json)
+    ? () => {}
+    : (...args) => {
+        console.log(...args);
+      };
+
+  const server = await startLocalGatewayAgentServer({
+    host: flags.host,
+    port: flags.port,
+    token: flags.token,
+    password: flags.password,
+    logger,
+  });
+
+  const readyPayload = {
+    ok: true,
+    host: server.host,
+    port: server.port,
+    url: `ws://${server.host}:${server.port}`,
+    tokenConfigured: Boolean(server.token),
+    passwordConfigured: Boolean(server.password),
+  };
+
+  if (isTruthyFlag(flags.json)) {
+    console.log(JSON.stringify(readyPayload, null, 2));
+  } else {
+    console.log(`Local OpenClaw dev gateway listening on ${readyPayload.url}`);
+  }
+
+  let closing = false;
+  const shutdown = async () => {
+    if (closing) return;
+    closing = true;
+    await server.close();
+    process.exit(0);
+  };
+
+  process.once('SIGINT', () => {
+    void shutdown();
+  });
+  process.once('SIGTERM', () => {
+    void shutdown();
+  });
+
+  await new Promise(() => {});
+}
+
+async function handleOpenclawDebugCommand(action, flags) {
+  const normalizedAction = String(action || '').trim().toLowerCase();
+  if (normalizedAction === 'local-gateway-agent') {
+    await runLocalGatewayAgentDebug(flags);
+    return;
+  }
+
+  if (normalizedAction === 'persona-runtime') {
+    const result = await runPersonaRuntimeDebugCheck({
+      slug: flags.slug,
+      name: flags.name,
+      description: flags.description,
+      workspaceRoot: flags['workspace-root'] || flags['openclaw-home'],
+      forceInstall: isTruthyFlag(flags['force-install']),
+      restart: isTruthyFlag(flags.restart),
+      leaveRunning: isTruthyFlag(flags['leave-running']),
+      cleanup: !isTruthyFlag(flags['no-cleanup']),
+    });
+    printPersonaRuntimeDebugResult(result, isTruthyFlag(flags.json));
+    if (!result.statusAfterLaunch.processRunning) {
+      throw new Error('Persona runtime smoke check failed to keep the process running after launch.');
+    }
+    if (result.stop && result.statusAfterStop?.processRunning) {
+      throw new Error('Persona runtime smoke check failed to stop the process cleanly.');
+    }
+    return;
+  }
+
+  const frameFile =
+    typeof flags['frame-file'] === 'string' && flags['frame-file'].trim()
+      ? path.resolve(flags['frame-file'])
+      : '';
+  const frameText =
+    frameFile
+      ? readFile(frameFile)
+      : (typeof flags['frame-json'] === 'string' && flags['frame-json'].trim() ? flags['frame-json'] : '');
+  const text = typeof flags.text === 'string' ? flags.text : '';
+
+  if (!frameText && !text.trim()) {
+    throw new Error(
+      'Assistant text or frame input is required. Usage: oomi openclaw debug assistant-final --text "<assistant text>"'
+    );
+  }
+
+  const debugOptions = {
+    sessionId: flags['session-id'],
+    sessionKey: flags['session-key'],
+    role: flags.role,
+    omitRole: isTruthyFlag(flags['omit-role']),
+    text,
+    frameText,
+    root: flags.root,
+    userText: flags['user-text'],
+    liveProvider: isTruthyFlag(flags['live-provider']),
+    envFile: flags['env-file'],
+    providerTimeoutMs: flags['provider-timeout-ms'],
+  };
+
+  if (normalizedAction === 'assistant-final') {
+    const result = runAssistantFinalDebugCheck(debugOptions);
+    printAssistantFinalDebugResult(result, isTruthyFlag(flags.json));
+    return;
+  }
+
+  if (normalizedAction === 'tts-pipeline') {
+    const result = await runLocalTtsPipelineDebugCheck(debugOptions);
+    printTtsPipelineDebugResult(result, isTruthyFlag(flags.json));
+    if (!result.backend?.success) {
+      throw new Error(result.backend?.qwen?.errorCode || 'Local backend TTS replay failed.');
+    }
+    return;
+  }
+
+  throw new Error('Unknown debug action: ' + normalizedAction + '. Use: oomi openclaw debug assistant-final|tts-pipeline|local-gateway-agent|persona-runtime');
+}
+
+function buildOpenclawProfileFromFlags(flags) {
+  const defaultProfilePath = resolveOpenclawProfilePath();
+  const defaultOpenclawHome = path.dirname(defaultProfilePath);
+  const defaultWorkspaceRoot = String(
+    flags['workspace-root'] ||
+      flags.workspace ||
+      process.env.OPENCLAW_WORKSPACE ||
+      resolveOpenclawWorkspaceRoot()
+  ).trim();
+  const defaultGatewayPort = parsePositiveInteger(
+    flags['gateway-port'] || process.env.OPENCLAW_GATEWAY_PORT,
+    18789
+  );
+  const pluginTrustMode =
+    String(flags['plugin-trust-mode'] || '').trim() === 'plugins.allow' ||
+    isTruthyFlag(flags['strict-plugin-allow'])
+      ? 'plugins.allow'
+      : 'auto-discovery';
+
+  return buildOomiDevLocalProfile({
+    profileId: flags['profile-id'] || flags.id || 'oomi-dev-local',
+    label: flags.label || 'Oomi Local Dev',
+    workspaceRoot: defaultWorkspaceRoot,
+    deviceId: flags['device-id'] || process.env.OOMI_DEV_DEVICE_ID || '',
+    gatewayPort: defaultGatewayPort,
+    gatewayToken:
+      flags['gateway-token'] ||
+      process.env.OPENCLAW_GATEWAY_TOKEN ||
+      process.env.OOMI_DEV_GATEWAY_TOKEN ||
+      'dev-gateway-token',
+    backendUrl:
+      flags['backend-url'] ||
+      process.env.OOMI_DEV_BACKEND_URL ||
+      process.env.OOMI_BACKEND_URL ||
+      '',
+    deviceToken:
+      flags['device-token'] ||
+      process.env.OOMI_DEV_DEVICE_TOKEN ||
+      process.env.OOMI_DEVICE_TOKEN ||
+      '',
+    defaultSessionKey:
+      flags['session-key'] ||
+      flags['default-session-key'] ||
+      process.env.OOMI_DEV_DEFAULT_SESSION_KEY ||
+      process.env.OOMI_DEV_SESSION_KEY ||
+      'agent:main:webchat:channel:oomi',
+    enableOomiChannel:
+      isTruthyFlag(flags['enable-channel']) ||
+      (!isTruthyFlag(flags['disable-channel']) &&
+        Boolean(
+          String(
+            flags['device-token'] ||
+              process.env.OOMI_DEV_DEVICE_TOKEN ||
+              process.env.OOMI_DEVICE_TOKEN ||
+              ''
+          ).trim()
+        )),
+    requestTimeoutMs: parsePositiveInteger(flags['request-timeout-ms'], 15000),
+    pluginTrustMode,
+    modelPreset: flags['model-preset'] || 'openrouter-free',
+    modelAuthMode: flags['model-auth-mode'] || 'oomi-managed',
+    openclawHome: flags['openclaw-home'] || defaultOpenclawHome,
   });
 }
-
-async function runLocalTtsPipelineDebugCheck(options = {}) {
-  const assistant = runAssistantFinalDebugCheck(options);
-  const repoRoot = resolveRepoRoot(options.root);
-  const backendRoot = resolveBackendRoot(options.root);
-  const scriptPath = path.join(backendRoot, 'bin', 'voice_tts_replay.rb');
-  if (!fs.existsSync(scriptPath)) {
-    throw new Error(`Backend replay script not found: ${scriptPath}`);
-  }
-
-  const inputPayload = {
-    repoRoot,
-    sessionId: assistant.sessionId,
-    sessionKey: assistant.sessionKey,
-    frameText: assistant.frameText,
-    userText:
-      typeof options.userText === 'string' && options.userText.trim()
-        ? options.userText.trim()
-        : 'local debug utterance',
-    liveProvider: Boolean(options.liveProvider),
-    providerTimeoutMs: parsePositiveInteger(options.providerTimeoutMs, 15000),
-  };
-  let childEnv = undefined;
-  let resolvedEnvFile = '';
-  if (options.liveProvider) {
-    resolvedEnvFile =
-      typeof options.envFile === 'string' && options.envFile.trim()
-        ? path.resolve(options.envFile.trim())
-        : path.join(repoRoot, '.env.local');
-    childEnv = loadEnvFile(resolvedEnvFile, DEBUG_PROVIDER_ENV_KEYS);
-  }
-  const inputFile = path.join(os.tmpdir(), `oomi-voice-replay-${randomUUID()}.json`);
-  writeFile(inputFile, JSON.stringify(inputPayload, null, 2) + '\n');
-
-  try {
-    const backend = await runBundledRubyScript({ backendRoot, scriptPath, inputFile, env: childEnv });
-    const parsed = backend.stdout.trim() ? JSON.parse(backend.stdout) : null;
-    return {
-      assistant,
-      backend: parsed,
-      backendExitCode: backend.code,
-      backendStderr: backend.stderr.trim(),
-      liveProvider: Boolean(options.liveProvider),
-      envFile: resolvedEnvFile || null,
-    };
-  } finally {
-    try {
-      fs.unlinkSync(inputFile);
-    } catch {
-      // no-op
-    }
-  }
-}
-
-function printTtsPipelineDebugResult(result, asJson) {
-  if (asJson) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-
-  console.log(`Assistant normalization: ${result.assistant.changed ? 'changed' : 'unchanged'}${result.assistant.reason ? ` (${result.assistant.reason})` : ''}`);
-  console.log(`Assistant spoken segments: ${Array.isArray(result.assistant.spoken?.segments) ? result.assistant.spoken.segments.length : 0}`);
-  if (!result.backend) {
-    console.log('Backend replay: <no output>');
-    return;
-  }
-  console.log(`Backend replay success: ${result.backend.success ? 'yes' : 'no'}`);
-  console.log(`Managed speech sidecar: ${result.backend.managed?.assistantSpeechFinal?.present ? 'yes' : 'no'}`);
-  console.log(`Backend final text: ${result.backend.qwen?.assistantTextFinal || '<missing>'}`);
-  console.log(`Backend TTS appends: ${Array.isArray(result.backend.qwen?.ttsAppends) ? result.backend.qwen.ttsAppends.length : 0}`);
-  console.log(`Backend TTS commits: ${Number(result.backend.qwen?.commitCount || 0)}`);
-  if (result.liveProvider) {
-    console.log(`Live provider audio deltas: ${Number(result.backend.qwen?.audioDeltaCount || 0)}`);
-    console.log(`Live provider audio bytes (base64): ${Number(result.backend.qwen?.audioDeltaBytes || 0)}`);
-    console.log(`Live provider timeout: ${result.backend.qwen?.providerTimedOut ? 'yes' : 'no'}`);
-  }
-  if (result.backend.qwen?.errorCode) {
-    console.log(`Backend error: ${result.backend.qwen.errorCode}`);
-  }
-  if (result.backendStderr) {
-    console.log(`Backend stderr: ${result.backendStderr}`);
-  }
-}
-
-async function handleOpenclawDebugCommand(action, flags) {
-  const normalizedAction = String(action || '').trim().toLowerCase();
-  const frameFile =
-    typeof flags['frame-file'] === 'string' && flags['frame-file'].trim()
-      ? path.resolve(flags['frame-file'])
-      : '';
-  const frameText =
-    frameFile
-      ? readFile(frameFile)
-      : (typeof flags['frame-json'] === 'string' && flags['frame-json'].trim() ? flags['frame-json'] : '');
-  const text = typeof flags.text === 'string' ? flags.text : '';
-
-  if (!frameText && !text.trim()) {
-    throw new Error(
-      'Assistant text or frame input is required. Usage: oomi openclaw debug assistant-final --text "<assistant text>"'
-    );
-  }
-
-  const debugOptions = {
-    sessionId: flags['session-id'],
-    sessionKey: flags['session-key'],
-    role: flags.role,
-    omitRole: isTruthyFlag(flags['omit-role']),
-    text,
-    frameText,
-    root: flags.root,
-    userText: flags['user-text'],
-    liveProvider: isTruthyFlag(flags['live-provider']),
-    envFile: flags['env-file'],
-    providerTimeoutMs: flags['provider-timeout-ms'],
-  };
-
-  if (normalizedAction === 'assistant-final') {
-    const result = runAssistantFinalDebugCheck(debugOptions);
-    printAssistantFinalDebugResult(result, isTruthyFlag(flags.json));
-    return;
-  }
-
-  if (normalizedAction === 'tts-pipeline') {
-    const result = await runLocalTtsPipelineDebugCheck(debugOptions);
-    printTtsPipelineDebugResult(result, isTruthyFlag(flags.json));
-    if (!result.backend?.success) {
-      throw new Error(result.backend?.qwen?.errorCode || 'Local backend TTS replay failed.');
-    }
-    return;
-  }
-
-  throw new Error('Unknown debug action: ' + normalizedAction + '. Use: oomi openclaw debug assistant-final|tts-pipeline');
-}
+
+function printOpenclawProfileResult(payload, asJson) {
+  if (asJson) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (payload.profilePath) {
+    console.log(`Profile written: ${payload.profilePath}`);
+  }
+  if (payload.configPath) {
+    console.log(`Config updated: ${payload.configPath}`);
+  }
+  if (payload.identityPath) {
+    console.log(`Identity path: ${payload.identityPath}`);
+  }
+  if (payload.profile?.profileId) {
+    console.log(`Profile id: ${payload.profile.profileId}`);
+  }
+  if (payload.profile?.preset) {
+    console.log(`Preset: ${payload.profile.preset}`);
+  }
+  if (payload.pluginTrustMode) {
+    console.log(`Plugin trust mode: ${payload.pluginTrustMode}`);
+  }
+  if (typeof payload.oomiChannelEnabled === 'boolean') {
+    console.log(`Oomi channel enabled: ${payload.oomiChannelEnabled ? 'yes' : 'no'}`);
+  }
+  if (typeof payload.identityCreated === 'boolean') {
+    console.log(`Device identity created: ${payload.identityCreated ? 'yes' : 'no'}`);
+  }
+}
+
+async function handleOpenclawProfileCommand(action, flags) {
+  const normalizedAction = String(action || '').trim().toLowerCase();
+  if (!normalizedAction || normalizedAction === 'help') {
+    throw new Error('OpenClaw profile action is required. Use: oomi openclaw profile init|apply');
+  }
+
+  const profilePath = path.resolve(
+    String(flags.profile || flags['profile-file'] || resolveOpenclawProfilePath()).trim()
+  );
+
+  if (normalizedAction === 'init') {
+    const profile = buildOpenclawProfileFromFlags(flags);
+    writeOpenclawProfile(profilePath, profile);
+    printOpenclawProfileResult(
+      {
+        ok: true,
+        profilePath,
+        profile,
+      },
+      isTruthyFlag(flags.json)
+    );
+    return;
+  }
+
+  if (normalizedAction === 'apply') {
+    const profile = readOpenclawProfile(profilePath);
+    if (!profile) {
+      throw new Error(`OpenClaw profile not found or unreadable: ${profilePath}`);
+    }
+    const openclawHome = path.resolve(String(flags['openclaw-home'] || resolveOpenclawHome()).trim());
+    const defaultIdentityPath = path.join(openclawHome, 'identity', 'device.json');
+    const applyResult = applyOpenclawProfile({
+      profile,
+      openclawHome,
+      configPath:
+        typeof flags['config-path'] === 'string' && flags['config-path'].trim()
+          ? path.resolve(flags['config-path'])
+          : '',
+      identityPath:
+        typeof flags['identity-path'] === 'string' && flags['identity-path'].trim()
+          ? path.resolve(flags['identity-path'])
+          : defaultIdentityPath,
+      ensureIdentity: !isTruthyFlag(flags['skip-identity']),
+    });
+    printOpenclawProfileResult(
+      {
+        ...applyResult,
+        profilePath,
+        profile,
+      },
+      isTruthyFlag(flags.json)
+    );
+    return;
+  }
+
+  throw new Error(`Unknown profile action: ${normalizedAction}. Use: oomi openclaw profile init|apply`);
+}
 
 function extractCorrelationId(params) {
   if (!params || typeof params !== 'object') return '';
@@ -2385,11 +3092,11 @@ async function runBridgePreflight({ brokerWs, gatewayUrl, gatewayConfigPath }) {
   await assertTcpReachable(parsedGatewayUrl.toString());
 }
 
-function buildBridgeDetachArgs(rawFlags = {}) {
-  const orderedKeys = [
-    'broker-http',
-    'broker-ws',
-    'pair-code',
+function buildBridgeDetachArgs(rawFlags = {}) {
+  const orderedKeys = [
+    'broker-http',
+    'broker-ws',
+    'pair-code',
     'app-url',
     'device-id',
     'device-token',
@@ -2407,13 +3114,13 @@ function buildBridgeDetachArgs(rawFlags = {}) {
     if (!text) continue;
     args.push(`--${key}`, text);
   }
-
-  return args;
-}
-
-function isServiceManagedBridgeStart(flags = {}) {
-  return isTruthyFlag(flags['service-managed']);
-}
+
+  return args;
+}
+
+function isServiceManagedBridgeStart(flags = {}) {
+  return isTruthyFlag(flags['service-managed']);
+}
 
 function startBridgeDetachedProcess(rawFlags = {}) {
   const existing = findRunningBridgeProcess();
@@ -2584,17 +3291,31 @@ function runLaunchctl(args, { allowFailure = false } = {}) {
   return { status, stdout, stderr };
 }
 
-function buildBridgeLaunchAgentPlist() {
-  const scriptPath = (() => {
-    try {
-      return fs.realpathSync(process.argv[1]);
-    } catch {
-      return process.argv[1];
-    }
-  })();
-  const programArgs = [process.execPath, scriptPath, 'openclaw', 'bridge', 'start', '--service-managed'];
-  const bridgeLogPath = resolveBridgeLiveLogPath();
-  const argsXml = programArgs.map((arg) => `<string>${xmlEscape(arg)}</string>`).join('\n      ');
+function buildBridgeLaunchAgentPlist() {
+  const scriptPath = (() => {
+    try {
+      return fs.realpathSync(process.argv[1]);
+    } catch {
+      return process.argv[1];
+    }
+  })();
+  const programArgs = [process.execPath, scriptPath, 'openclaw', 'bridge', 'start', '--service-managed'];
+  const bridgeLogPath = resolveBridgeLiveLogPath();
+  const argsXml = programArgs.map((arg) => `<string>${xmlEscape(arg)}</string>`).join('\n      ');
+  const openclawHome = resolveOpenclawHome();
+  const openclawWorkspace = resolveOpenclawWorkspaceRoot();
+  const envVars = {
+    OOMI_SKIP_UPDATE_CHECK: '1',
+  };
+  if (process.env.OPENCLAW_HOME) {
+    envVars.OPENCLAW_HOME = openclawHome;
+  }
+  if (process.env.OPENCLAW_WORKSPACE) {
+    envVars.OPENCLAW_WORKSPACE = openclawWorkspace;
+  }
+  const envXml = Object.entries(envVars)
+    .map(([key, value]) => `    <key>${xmlEscape(key)}</key>\n    <string>${xmlEscape(value)}</string>`)
+    .join('\n');
 
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -2607,7 +3328,7 @@ function buildBridgeLaunchAgentPlist() {
       ${argsXml}
   </array>
   <key>WorkingDirectory</key>
-  <string>${xmlEscape(os.homedir())}</string>
+  <string>${xmlEscape(openclawHome)}</string>
   <key>RunAtLoad</key>
   <true/>
   <key>KeepAlive</key>
@@ -2616,8 +3337,7 @@ function buildBridgeLaunchAgentPlist() {
   <integer>5</integer>
   <key>EnvironmentVariables</key>
   <dict>
-    <key>OOMI_SKIP_UPDATE_CHECK</key>
-    <string>1</string>
+${envXml}
   </dict>
   <key>StandardOutPath</key>
   <string>${xmlEscape(bridgeLogPath)}</string>
@@ -2650,18 +3370,18 @@ function readBridgeLaunchdStatus() {
   };
 }
 
-function startBridgeLaunchdService() {
-  assertMacOSLaunchdAvailable();
-  const plistPath = resolveBridgeLaunchAgentPlistPath();
-  if (!fs.existsSync(plistPath)) {
-    throw new Error('Bridge service is not installed. Run: oomi openclaw bridge service install');
-  }
-  writeFile(plistPath, buildBridgeLaunchAgentPlist());
-  const domain = launchctlDomain();
-  const target = launchctlServiceTarget();
-  runLaunchctl(['bootout', domain, plistPath], { allowFailure: true });
-  runLaunchctl(['bootstrap', domain, plistPath]);
-  runLaunchctl(['enable', target], { allowFailure: true });
+function startBridgeLaunchdService() {
+  assertMacOSLaunchdAvailable();
+  const plistPath = resolveBridgeLaunchAgentPlistPath();
+  if (!fs.existsSync(plistPath)) {
+    throw new Error('Bridge service is not installed. Run: oomi openclaw bridge service install');
+  }
+  writeFile(plistPath, buildBridgeLaunchAgentPlist());
+  const domain = launchctlDomain();
+  const target = launchctlServiceTarget();
+  runLaunchctl(['bootout', domain, plistPath], { allowFailure: true });
+  runLaunchctl(['bootstrap', domain, plistPath]);
+  runLaunchctl(['enable', target], { allowFailure: true });
   runLaunchctl(['kickstart', '-k', target], { allowFailure: true });
 }
 
@@ -2820,22 +3540,22 @@ async function startOpenclawBridge(flags) {
   console.log(`Broker WS: ${brokerWs}`);
 
   const activeGatewaySockets = new Map();
-  const reconnectState = {
-    attempt: 0,
-    timer: null,
-    stopped: false,
-    lastFailure: null,
-  };
-  const personaJobPollEnabled = !isTruthyFlag(process.env.OOMI_DISABLE_PERSONA_JOB_POLL);
-  const personaJobPollIntervalMs = parsePositiveInteger(
-    process.env.OOMI_PERSONA_JOB_POLL_INTERVAL_MS,
-    3000,
-  );
-  const personaJobIdlePollIntervalMs = parsePositiveInteger(
-    process.env.OOMI_PERSONA_JOB_IDLE_POLL_INTERVAL_MS,
-    3000,
-  );
-  const personaWorkspaceRoot = defaultPersonaWorkspaceRoot();
+  const reconnectState = {
+    attempt: 0,
+    timer: null,
+    stopped: false,
+    lastFailure: null,
+  };
+  const personaJobPollEnabled = !isTruthyFlag(process.env.OOMI_DISABLE_PERSONA_JOB_POLL);
+  const personaJobPollIntervalMs = parsePositiveInteger(
+    process.env.OOMI_PERSONA_JOB_POLL_INTERVAL_MS,
+    3000,
+  );
+  const personaJobIdlePollIntervalMs = parsePositiveInteger(
+    process.env.OOMI_PERSONA_JOB_IDLE_POLL_INTERVAL_MS,
+    3000,
+  );
+  const personaWorkspaceRoot = defaultPersonaWorkspaceRoot();
   const brokerPath = (() => {
     try {
       return new URL(brokerWs).pathname || '';
@@ -2900,33 +3620,38 @@ async function startOpenclawBridge(flags) {
     onReport: ({ phase, status, error }) => {
       reportBridgeProcessFault({ phase, status, error });
     },
-    onExit: (code) => {
-      reconnectState.stopped = true;
-      if (reconnectState.timer) {
-        clearTimeout(reconnectState.timer);
-        reconnectState.timer = null;
-      }
-      personaJobPoller?.stop();
-      releaseBridgeLock();
-      process.exit(code);
-    },
-  });
+    onExit: (code) => {
+      reconnectState.stopped = true;
+      if (reconnectState.timer) {
+        clearTimeout(reconnectState.timer);
+        reconnectState.timer = null;
+      }
+      personaJobPoller?.stop();
+      releaseBridgeLock();
+      process.exit(code);
+    },
+  });
 
   const uncaughtExceptionHandler = (error) => {
     handleBridgeProcessFault({ phase: 'process.uncaughtException', error });
   };
 
-  const unhandledRejectionHandler = (reason) => {
-    handleBridgeProcessFault({ phase: 'process.unhandledRejection', error: reason });
-  };
-
-  process.on('uncaughtException', uncaughtExceptionHandler);
-  process.on('unhandledRejection', unhandledRejectionHandler);
+  const unhandledRejectionHandler = (reason) => {
+    handleBridgeProcessFault({ phase: 'process.unhandledRejection', error: reason });
+  };
+
+  process.on('uncaughtException', uncaughtExceptionHandler);
+  process.on('unhandledRejection', unhandledRejectionHandler);
+
+  const personaBackendUrl =
+    deviceToken
+      ? resolvePersonaBackendUrl({ 'backend-url': process.env.OOMI_DEV_BACKEND_URL || process.env.OOMI_BACKEND_URL || brokerHttp })
+      : '';
 
   const personaJobPoller =
-    personaJobPollEnabled && brokerHttp && deviceToken
+    personaJobPollEnabled && personaBackendUrl && deviceToken
       ? startPersonaJobPoller({
-          backendUrl: brokerHttp,
+          backendUrl: personaBackendUrl,
           deviceToken,
           pollIntervalMs: personaJobPollIntervalMs,
           idleIntervalMs: personaJobIdlePollIntervalMs,
@@ -2934,38 +3659,49 @@ async function startOpenclawBridge(flags) {
           onMessage: async (message) => {
             const result = await runManagedPersonaJobExecution({
               message,
-              backendUrl: brokerHttp,
+              backendUrl: personaBackendUrl,
               deviceToken,
               deviceId,
               workspaceRoot: personaWorkspaceRoot,
               shouldInstall: true,
               shouldStart: true,
-              shouldRegister: true,
-            });
-
-            if (result && result.ok) {
-              console.log(
-                `[persona-jobs] completed ${result.jobId} on port ${result.result?.localPort || 'unknown'}`
-              );
-              return;
-            }
-
-            if (result) {
-              console.warn(
-                `[persona-jobs] job ${result.jobId} completed with failure: ${result.error?.message || 'unknown error'}`
-              );
-            }
-          },
+              shouldRegister: true,
+            });
+
+            if (result && result.ok) {
+              console.log(
+                `[persona-jobs] completed ${result.jobId} on port ${result.result?.localPort || 'unknown'}`
+              );
+              return;
+            }
+
+            if (result) {
+              console.warn(
+                `[persona-jobs] job ${result.jobId} completed with failure: ${result.error?.message || 'unknown error'}`
+              );
+            }
+          },
+        })
+      : null;
+  const personaRuntimeSupervisor =
+    personaBackendUrl && deviceToken
+      ? startPersonaRuntimeSupervisor({
+          backendUrl: personaBackendUrl,
+          deviceToken,
+          workspaceRoot: personaWorkspaceRoot,
+          intervalMs: 30000,
+          logger: console,
+          autoRestart: true,
         })
       : null;
 
-  if (personaJobPollEnabled && brokerHttp && deviceToken) {
-    console.log('[persona-jobs] polling filtered control queue for persona_job messages.');
+  if (personaJobPollEnabled && personaBackendUrl && deviceToken) {
+    bridgeDebugLog('[persona-jobs] polling filtered control queue for persona_job messages.');
   } else if (personaJobPollEnabled) {
     console.warn('[persona-jobs] disabled because broker HTTP URL or device token is unavailable.');
   }
-
-  const sendBrokerPayload = (brokerSocket, payload) => {
+
+  const sendBrokerPayload = (brokerSocket, payload) => {
     if (brokerSocket.readyState !== WebSocket.OPEN) return;
     if (!actionCableMode) {
       brokerSocket.send(JSON.stringify(payload));
@@ -3195,7 +3931,7 @@ async function startOpenclawBridge(flags) {
       classifyBridgeFailure({ reason: 'connection closed without classified error' });
     const delayMs = computeReconnectDelayMs(reconnectState.attempt, failure.baseDelayMs);
 
-    console.warn(
+    bridgeDebugWarn(
       `[bridge] reconnect scheduled in ${delayMs}ms (attempt ${reconnectState.attempt}, class=${failure.failureClass}, code=${failure.errorCode})`
     );
 
@@ -3323,7 +4059,7 @@ async function startOpenclawBridge(flags) {
         }
         const result = forwardFrameToSession(sessionBridge, prepared.frameText);
         if (result === 'queued') {
-          console.log(`[bridge] client.frame queued after challenge ${sessionId}`);
+          bridgeDebugLog(`[bridge] client.frame queued after challenge ${sessionId}`);
           if (requestMeta) {
             startPendingRequestTimeout(brokerSocket, sessionId, sessionBridge, requestMeta);
           }
@@ -3337,7 +4073,7 @@ async function startOpenclawBridge(flags) {
             });
           }
         } else if (result === 'dropped') {
-          console.log(`[bridge] client.frame dropped after challenge ${sessionId}`);
+          bridgeDebugLog(`[bridge] client.frame dropped after challenge ${sessionId}`);
           incrementBridgeMetric('bridge_drop_count');
           if (requestMeta) {
             const pending = sessionBridge.pendingRequests instanceof Map
@@ -3369,7 +4105,7 @@ async function startOpenclawBridge(flags) {
             });
           }
         } else {
-          console.log(`[bridge] client.frame sent after challenge ${sessionId}`);
+          bridgeDebugLog(`[bridge] client.frame sent after challenge ${sessionId}`);
           if (requestMeta) {
             startPendingRequestTimeout(brokerSocket, sessionId, sessionBridge, requestMeta);
           }
@@ -3435,27 +4171,27 @@ async function startOpenclawBridge(flags) {
           clearTimeout(connectTimeout);
           connectTimeout = null;
         }
-        console.log(`[bridge] gateway.open ${sessionId}`);
+        bridgeDebugLog(`[bridge] gateway.open ${sessionId}`);
         flushSessionQueue(sessionBridge);
       });
 
-      gatewaySocket.on('message', runBridgeCallbackSafely((gatewayRaw) => {
-        let frame = typeof gatewayRaw === 'string' ? gatewayRaw : gatewayRaw.toString();
-        const spokenNormalized = normalizeAssistantGatewayFrame(sessionId, frame);
-        if (spokenNormalized.changed) {
-          frame = spokenNormalized.frameText;
-          if (spokenNormalized.scope === 'voice') {
-            console.log(`[bridge] voice.spoken_metadata.${spokenNormalized.reason} ${sessionId} ${JSON.stringify({
-              before: spokenNormalized.summary,
-              after: summarizeVoiceFrameContract(frame),
-            })}`);
-          }
-        } else if (spokenNormalized.scope === 'voice' && spokenNormalized.summary.event === 'chat' && spokenNormalized.summary.state === 'final') {
-          console.log(`[bridge] voice.chat.final ${sessionId} ${JSON.stringify(spokenNormalized.summary)}`);
-        }
-        const gatewayPayload = parseJsonPayload(frame);
-        if (gatewayPayload?.event === 'connect.challenge') {
-          console.log(`[bridge] gateway.connect.challenge ${sessionId}`);
+      gatewaySocket.on('message', runBridgeCallbackSafely((gatewayRaw) => {
+        let frame = typeof gatewayRaw === 'string' ? gatewayRaw : gatewayRaw.toString();
+        const spokenNormalized = normalizeAssistantGatewayFrame(sessionId, frame);
+        if (spokenNormalized.changed) {
+          frame = spokenNormalized.frameText;
+          if (spokenNormalized.scope === 'voice') {
+            bridgeDebugLog(`[bridge] voice.spoken_metadata.${spokenNormalized.reason} ${sessionId} ${JSON.stringify({
+              before: spokenNormalized.summary,
+              after: summarizeVoiceFrameContract(frame),
+            })}`);
+          }
+        } else if (spokenNormalized.scope === 'voice' && spokenNormalized.summary.event === 'chat' && spokenNormalized.summary.state === 'final') {
+          bridgeDebugLog(`[bridge] voice.chat.final ${sessionId} ${JSON.stringify(spokenNormalized.summary)}`);
+        }
+        const gatewayPayload = parseJsonPayload(frame);
+        if (gatewayPayload?.event === 'connect.challenge') {
+          bridgeDebugLog(`[bridge] gateway.connect.challenge ${sessionId}`);
           const nonce =
             gatewayPayload.payload && typeof gatewayPayload.payload.nonce === 'string'
               ? gatewayPayload.payload.nonce.trim()
@@ -3601,7 +4337,7 @@ async function startOpenclawBridge(flags) {
         clearChallengeTimer(sessionBridge);
         const reasonText = reason ? reason.toString() : '';
         const closeMeta = classifyGatewayClose(code, reasonText);
-        console.log(
+        bridgeDebugLog(
           `[bridge] gateway.close ${sessionId} code=${String(code)}${reasonText ? ` reason=${reasonText}` : ''}`
         );
         if (sessionBridge.pendingRequests instanceof Map) {
@@ -3678,7 +4414,7 @@ async function startOpenclawBridge(flags) {
     };
 
     brokerSocket.on('open', () => {
-      console.log('[bridge] Connected to managed broker.');
+      bridgeDebugLog('[bridge] Connected to managed broker.');
       reconnectState.attempt = 0;
       reconnectState.lastFailure = null;
       if (actionCableMode) {
@@ -3795,29 +4531,29 @@ async function startOpenclawBridge(flags) {
       }
 
       if (payload.type === 'device.ready') {
-        console.log(`[bridge] Broker ready for device ${payload.deviceId || deviceId}.`);
+        bridgeDebugLog(`[bridge] Broker ready for device ${payload.deviceId || deviceId}.`);
         return;
       }
 
       if (payload.type === 'client.open') {
         const sessionId = String(payload.sessionId || '').trim();
         if (!sessionId) return;
-        console.log(`[bridge] client.open ${sessionId}`);
+        bridgeDebugLog(`[bridge] client.open ${sessionId}`);
         getOrCreateGatewaySession(sessionId);
         return;
       }
 
-      if (payload.type === 'client.frame') {
-        const sessionId = String(payload.sessionId || '').trim();
-        const frame = typeof payload.frame === 'string' ? payload.frame : '';
-        if (!sessionId || !frame) return;
-        if (classifyBridgeSessionScope(sessionId) === 'voice') {
-          console.log(`[bridge] client.frame ${sessionId} ${JSON.stringify(summarizeVoiceFrameContract(frame))}`);
-        } else {
-          console.log(`[bridge] client.frame ${sessionId}`);
-        }
-        const sessionBridge = getOrCreateGatewaySession(sessionId);
-        if (!sessionBridge) return;
+      if (payload.type === 'client.frame') {
+        const sessionId = String(payload.sessionId || '').trim();
+        const frame = typeof payload.frame === 'string' ? payload.frame : '';
+        if (!sessionId || !frame) return;
+        if (classifyBridgeSessionScope(sessionId) === 'voice') {
+          bridgeDebugLog(`[bridge] client.frame ${sessionId} ${JSON.stringify(summarizeVoiceFrameContract(frame))}`);
+        } else {
+          bridgeDebugLog(`[bridge] client.frame ${sessionId}`);
+        }
+        const sessionBridge = getOrCreateGatewaySession(sessionId);
+        if (!sessionBridge) return;
         const requestMeta = extractGatewayRequestMeta(frame);
         if (requestMeta) {
           if (!(sessionBridge.pendingRequests instanceof Map)) {
@@ -3840,7 +4576,7 @@ async function startOpenclawBridge(flags) {
         });
         if (prepared.waitForChallenge) {
           queueConnectUntilChallenge(sessionId, sessionBridge, frame);
-          console.log(`[bridge] client.frame waiting for challenge ${sessionId}`);
+          bridgeDebugLog(`[bridge] client.frame waiting for challenge ${sessionId}`);
           if (requestMeta) {
             sendGatewayAck(brokerSocket, {
               sessionId,
@@ -3886,7 +4622,7 @@ async function startOpenclawBridge(flags) {
           requiresConnectAccepted: Boolean(requestMeta && requestMeta.method !== 'connect'),
         });
         if (result === 'waiting_for_connect') {
-          console.log(`[bridge] client.frame waiting for connect ${sessionId}`);
+          bridgeDebugLog(`[bridge] client.frame waiting for connect ${sessionId}`);
           if (requestMeta) {
             sendGatewayAck(brokerSocket, {
               sessionId,
@@ -3899,7 +4635,7 @@ async function startOpenclawBridge(flags) {
           return;
         }
         if (result === 'queued') {
-          console.log(`[bridge] client.frame queued ${sessionId}`);
+          bridgeDebugLog(`[bridge] client.frame queued ${sessionId}`);
           if (requestMeta) {
             startPendingRequestTimeout(brokerSocket, sessionId, sessionBridge, requestMeta);
           }
@@ -3913,7 +4649,7 @@ async function startOpenclawBridge(flags) {
             });
           }
         } else if (result === 'dropped') {
-          console.log(`[bridge] client.frame dropped (socket not open) ${sessionId}`);
+          bridgeDebugLog(`[bridge] client.frame dropped (socket not open) ${sessionId}`);
           incrementBridgeMetric('bridge_drop_count');
           if (requestMeta) {
             const pending = sessionBridge.pendingRequests instanceof Map
@@ -3959,7 +4695,7 @@ async function startOpenclawBridge(flags) {
 
       if (payload.type === 'client.close') {
         const sessionId = String(payload.sessionId || '').trim();
-        console.log(`[bridge] client.close ${sessionId}`);
+        bridgeDebugLog(`[bridge] client.close ${sessionId}`);
         const sessionBridge = activeGatewaySockets.get(sessionId);
         if (sessionBridge && sessionBridge.socket) {
           clearChallengeTimer(sessionBridge);
@@ -3982,7 +4718,7 @@ async function startOpenclawBridge(flags) {
         actionCableHeartbeat = null;
       }
       const reasonText = reason ? reason.toString() : '';
-      console.log(`[bridge] Broker disconnected (${code}) ${reasonText}`);
+      bridgeDebugLog(`[bridge] Broker disconnected (${code}) ${reasonText}`);
       incrementBridgeMetric('bridge_disconnect_count');
       for (const [sessionId, sessionBridge] of activeGatewaySockets.entries()) {
         clearChallengeTimer(sessionBridge);
@@ -4024,16 +4760,17 @@ async function startOpenclawBridge(flags) {
     }));
   };
 
-  const markStopped = (signal) => {
-    reconnectState.stopped = true;
+  const markStopped = (signal) => {
+    reconnectState.stopped = true;
     if (reconnectState.timer) {
       clearTimeout(reconnectState.timer);
       reconnectState.timer = null;
     }
     personaJobPoller?.stop();
+    personaRuntimeSupervisor?.stop();
     process.off('uncaughtException', uncaughtExceptionHandler);
     process.off('unhandledRejection', unhandledRejectionHandler);
-    updateBridgeStatus({
+    updateBridgeStatus({
       status: 'stopped',
       deviceId,
       brokerWs,
@@ -4434,17 +5171,17 @@ async function handleBridgeServiceCommand(actionRaw = '', flags = {}) {
   );
 }
 
-async function startBridgeLifecycle(flags = {}) {
-  const serviceManaged = isServiceManagedBridgeStart(flags);
-  if (serviceManaged && Boolean(flags.detach)) {
-    throw new Error('Detached bridge mode cannot be combined with --service-managed.');
-  }
-
-  if (Boolean(flags.detach)) {
-    const detachedFlags = { ...flags };
-    delete detachedFlags.detach;
-    const result = startBridgeDetachedProcess(detachedFlags);
-    if (result.alreadyRunning) {
+async function startBridgeLifecycle(flags = {}) {
+  const serviceManaged = isServiceManagedBridgeStart(flags);
+  if (serviceManaged && Boolean(flags.detach)) {
+    throw new Error('Detached bridge mode cannot be combined with --service-managed.');
+  }
+
+  if (Boolean(flags.detach)) {
+    const detachedFlags = { ...flags };
+    delete detachedFlags.detach;
+    const result = startBridgeDetachedProcess(detachedFlags);
+    if (result.alreadyRunning) {
       incrementBridgeMetric('duplicate_start_attempt_count');
       console.log(`Bridge already running (pid: ${result.pid}).`);
       return;
@@ -4453,30 +5190,30 @@ async function startBridgeLifecycle(flags = {}) {
     console.log(`Bridge started in background (pid: ${result.pid}).`);
     return;
   }
-
-  const running = findRunningBridgeProcess();
-  if (running) {
-    if (!serviceManaged) {
-      incrementBridgeMetric('duplicate_start_attempt_count');
-      console.log(
-        `Bridge already running (pid ${running.pid})${running.deviceId ? ` for device ${running.deviceId}` : ''}.`
-      );
-      return;
-    }
-
-    incrementBridgeMetric('bridge_restart_count');
-    console.log(
-      `Service-managed bridge start detected existing bridge (pid ${running.pid})${running.deviceId ? ` for device ${running.deviceId}` : ''}; reclaiming ownership.`
-    );
-    const result = await stopBridgeProcesses();
-    if (Array.isArray(result.stillAlive) && result.stillAlive.length > 0) {
-      throw new Error(`Failed to stop bridge processes: ${result.stillAlive.join(', ')}`);
-    }
-  }
-
-  incrementBridgeMetric('bridge_start_count');
-  await startOpenclawBridge(flags);
-}
+
+  const running = findRunningBridgeProcess();
+  if (running) {
+    if (!serviceManaged) {
+      incrementBridgeMetric('duplicate_start_attempt_count');
+      console.log(
+        `Bridge already running (pid ${running.pid})${running.deviceId ? ` for device ${running.deviceId}` : ''}.`
+      );
+      return;
+    }
+
+    incrementBridgeMetric('bridge_restart_count');
+    console.log(
+      `Service-managed bridge start detected existing bridge (pid ${running.pid})${running.deviceId ? ` for device ${running.deviceId}` : ''}; reclaiming ownership.`
+    );
+    const result = await stopBridgeProcesses();
+    if (Array.isArray(result.stillAlive) && result.stillAlive.length > 0) {
+      throw new Error(`Failed to stop bridge processes: ${result.stillAlive.join(', ')}`);
+    }
+  }
+
+  incrementBridgeMetric('bridge_start_count');
+  await startOpenclawBridge(flags);
+}
 
 async function handleBridgeLifecycleCommand(flags = {}, actionRaw = '') {
   const action = String(actionRaw || 'start').trim().toLowerCase();
@@ -4592,40 +5329,50 @@ async function main() {
     return;
   }
 
-  if (command === 'openclaw' && subcommand === 'plugin') {
-    printOpenclawPluginSetup(args.flags);
-    return;
-  }
-
-  if (command === 'openclaw' && subcommand === 'debug') {
-    await handleOpenclawDebugCommand(args.positionals[0], args.flags);
-    return;
-  }
+  if (command === 'openclaw' && subcommand === 'plugin') {
+    printOpenclawPluginSetup(args.flags);
+    return;
+  }
+
+  if (command === 'openclaw' && subcommand === 'profile') {
+    await handleOpenclawProfileCommand(args.positionals[0], args.flags);
+    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 === 'personas' && subcommand === 'create') {
+  if (command === 'personas' && subcommand === 'create') {
     const id = args.positionals[0];
     if (!id) {
       throw new Error('Persona id is required. Usage: oomi personas create <id>');
     }
     await createPersona({ id, root: args.flags.root, flags: args.flags });
     return;
-  }
-
-  if (command === 'personas' && subcommand === 'create-managed') {
-    await handlePersonaCreateManagedCommand(args.flags, args.positionals[0]);
-    return;
-  }
-
-  if (command === 'personas' && subcommand === 'scaffold') {
-    const slug = args.positionals[0];
-    if (!slug) {
-      throw new Error('Persona slug is required. Usage: oomi personas scaffold <slug> --name "<name>" --description "<description>" --out <path>');
-    }
+  }
+
+  if (command === 'personas' && subcommand === 'create-managed') {
+    await handlePersonaCreateManagedCommand(args.flags, args.positionals[0]);
+    return;
+  }
+
+  if (command === 'personas' && subcommand === 'launch-managed') {
+    await handlePersonaLaunchManagedCommand(args.flags, args.positionals[0]);
+    return;
+  }
+
+  if (command === 'personas' && subcommand === 'scaffold') {
+    const slug = args.positionals[0];
+    if (!slug) {
+      throw new Error('Persona slug is required. Usage: oomi personas scaffold <slug> --name "<name>" --description "<description>" --out <path>');
+    }
     const result = scaffoldPersonaApp({
       slug,
       name: args.flags.name,
@@ -4634,70 +5381,97 @@ async function main() {
       templateVersion: args.flags['template-version'],
       force: isTruthyFlag(args.flags.force),
     });
-    printPersonaScaffoldResult(result, isTruthyFlag(args.flags.json));
-    return;
-  }
-
-  if (command === 'personas' && subcommand === 'runtime-register') {
-    const slug = args.positionals[0];
-    if (!slug) {
-      throw new Error('Persona slug is required. Usage: oomi personas runtime-register <slug> --local-port 4789');
-    }
-    await handlePersonaRuntimeRegisterCommand(slug, args.flags);
-    return;
-  }
-
-  if (command === 'personas' && subcommand === 'heartbeat') {
+    printPersonaScaffoldResult(result, isTruthyFlag(args.flags.json));
+    return;
+  }
+
+  if (command === 'personas' && subcommand === 'runtime-register') {
+    const slug = args.positionals[0];
+    if (!slug) {
+      throw new Error('Persona slug is required. Usage: oomi personas runtime-register <slug> --local-port 4789');
+    }
+    await handlePersonaRuntimeRegisterCommand(slug, args.flags);
+    return;
+  }
+
+  if (command === 'personas' && subcommand === 'status') {
+    const slug = args.positionals[0];
+    if (!slug) {
+      throw new Error('Persona slug is required. Usage: oomi personas status <slug>');
+    }
+    await handlePersonaStatusCommand(slug, args.flags);
+    return;
+  }
+
+  if (command === 'personas' && subcommand === 'stop') {
     const slug = args.positionals[0];
     if (!slug) {
-      throw new Error('Persona slug is required. Usage: oomi personas heartbeat <slug> --local-port 4789');
+      throw new Error('Persona slug is required. Usage: oomi personas stop <slug>');
     }
-    await handlePersonaHeartbeatCommand(slug, args.flags);
+    await handlePersonaStopCommand(slug, args.flags);
     return;
   }
 
-  if (command === 'personas' && subcommand === 'runtime-fail') {
+  if (command === 'personas' && subcommand === 'delete') {
     const slug = args.positionals[0];
     if (!slug) {
-      throw new Error('Persona slug is required. Usage: oomi personas runtime-fail <slug> --code RUNTIME_FAILED --message "<text>"');
-    }
-    await handlePersonaRuntimeFailCommand(slug, args.flags);
-    return;
-  }
-
-  if (command === 'persona-jobs' && subcommand === 'start') {
-    const jobId = args.positionals[0];
-    if (!jobId) {
-      throw new Error('Persona job id is required. Usage: oomi persona-jobs start <jobId>');
-    }
-    await handlePersonaJobStartCommand(jobId, args.flags);
-    return;
-  }
-
-  if (command === 'persona-jobs' && subcommand === 'succeed') {
-    const jobId = args.positionals[0];
-    if (!jobId) {
-      throw new Error('Persona job id is required. Usage: oomi persona-jobs succeed <jobId> --workspace-path <path> --local-port 4789');
-    }
-    await handlePersonaJobSucceedCommand(jobId, args.flags);
-    return;
-  }
-
-  if (command === 'persona-jobs' && subcommand === 'fail') {
-    const jobId = args.positionals[0];
-    if (!jobId) {
-      throw new Error('Persona job id is required. Usage: oomi persona-jobs fail <jobId> --code JOB_FAILED --message "<text>"');
+      throw new Error('Persona slug is required. Usage: oomi personas delete <slug>');
     }
-    await handlePersonaJobFailCommand(jobId, args.flags);
-    return;
-  }
-
-  if (command === 'persona-jobs' && subcommand === 'execute') {
-    await handlePersonaJobExecuteCommand(args.flags);
+    await handlePersonaDeleteCommand(slug, args.flags);
     return;
   }
 
-  console.error(`Unknown command: ${command} ${subcommand || ''}`.trim());
+  if (command === 'personas' && subcommand === 'heartbeat') {
+    const slug = args.positionals[0];
+    if (!slug) {
+      throw new Error('Persona slug is required. Usage: oomi personas heartbeat <slug> --local-port 4789');
+    }
+    await handlePersonaHeartbeatCommand(slug, args.flags);
+    return;
+  }
+
+  if (command === 'personas' && subcommand === 'runtime-fail') {
+    const slug = args.positionals[0];
+    if (!slug) {
+      throw new Error('Persona slug is required. Usage: oomi personas runtime-fail <slug> --code RUNTIME_FAILED --message "<text>"');
+    }
+    await handlePersonaRuntimeFailCommand(slug, args.flags);
+    return;
+  }
+
+  if (command === 'persona-jobs' && subcommand === 'start') {
+    const jobId = args.positionals[0];
+    if (!jobId) {
+      throw new Error('Persona job id is required. Usage: oomi persona-jobs start <jobId>');
+    }
+    await handlePersonaJobStartCommand(jobId, args.flags);
+    return;
+  }
+
+  if (command === 'persona-jobs' && subcommand === 'succeed') {
+    const jobId = args.positionals[0];
+    if (!jobId) {
+      throw new Error('Persona job id is required. Usage: oomi persona-jobs succeed <jobId> --workspace-path <path> --local-port 4789');
+    }
+    await handlePersonaJobSucceedCommand(jobId, args.flags);
+    return;
+  }
+
+  if (command === 'persona-jobs' && subcommand === 'fail') {
+    const jobId = args.positionals[0];
+    if (!jobId) {
+      throw new Error('Persona job id is required. Usage: oomi persona-jobs fail <jobId> --code JOB_FAILED --message "<text>"');
+    }
+    await handlePersonaJobFailCommand(jobId, args.flags);
+    return;
+  }
+
+  if (command === 'persona-jobs' && subcommand === 'execute') {
+    await handlePersonaJobExecuteCommand(args.flags);
+    return;
+  }
+
+  console.error(`Unknown command: ${command} ${subcommand || ''}`.trim());
   usage();
   process.exit(1);
 }
@@ -4713,23 +5487,25 @@ if (__isDirectExecution) {
   });
 }
 
-export {
-  prepareGatewayFrameForLocalGateway,
-  ensureAssistantSpokenMetadata,
-  normalizeAssistantGatewayFrame,
-  runAssistantFinalDebugCheck,
-  buildBridgeLaunchAgentPlist,
-  classifyBridgeFailure,
-  classifyBridgeSessionScope,
-  createBridgeProcessFaultHandler,
-  computeReconnectDelayMs,
-  resolveBridgeStatusForBrokerOpen,
-  resolveBridgeStatusForRuntimeFault,
-  runBridgeCallbackSafely,
-  extractGatewayRequestMeta,
-  extractGatewayResponseMeta,
-  isServiceManagedBridgeStart,
-  isGatewayRunStartedFrame,
-  isBridgeWorkerCommand,
-  parsePositiveInteger,
-};
+export {
+  prepareGatewayFrameForLocalGateway,
+  ensureAssistantSpokenMetadata,
+  normalizeAssistantGatewayFrame,
+  runAssistantFinalDebugCheck,
+  buildOpenclawProfileFromFlags,
+  handleOpenclawProfileCommand,
+  buildBridgeLaunchAgentPlist,
+  classifyBridgeFailure,
+  classifyBridgeSessionScope,
+  createBridgeProcessFaultHandler,
+  computeReconnectDelayMs,
+  resolveBridgeStatusForBrokerOpen,
+  resolveBridgeStatusForRuntimeFault,
+  runBridgeCallbackSafely,
+  extractGatewayRequestMeta,
+  extractGatewayResponseMeta,
+  isServiceManagedBridgeStart,
+  isGatewayRunStartedFrame,
+  isBridgeWorkerCommand,
+  parsePositiveInteger,
+};