oomi-ai 0.8.0 → 0.8.2

package/README.md

@@ -48,9 +48,22 @@ This package exposes connection, bridge, voice, and persona app state APIs. It d
 
 Connect the agent the user is speaking to. Identify your runtime and profile first. Never choose OpenClaw merely because it is installed on the same machine as Hermes.
 
+## Updating Oomi safely
+
+When the user asks you to update Oomi, read `oomi instructions` first; it supersedes copied setup/restart recipes. Keep the same connection on the same computer.
+
+1. Run `oomi update --connection NAME` (omit the selector for default OpenClaw). This only checks versions. If already current, report that and stop: do not reinstall or restart "to be sure."
+2. If an update exists, run the returned exact-version npm install command **alone**, through the runtime's normal approval flow. Do not append redirections, status checks or restarts. If installation is denied, fails, or cannot be verified, leave the bridge alone and explain the approval/error. Never disable security checks, retry through another executor, or enable blanket unattended approvals.
+3. After successful installation, check `npm list -g oomi-ai --depth=0` and `oomi update` separately. Only then run `oomi bridge repair --connection NAME`.
+4. A running 0.8.1+ supervised bridge queues its restart until active replies finish and queued phone replies are saved. If the result is `queued`, finish your reply now; do not wait for your own turn to end, poll in a loop, or claim completion. `oomi status --connection NAME --json` subsequently reports maintenance `completed`/`failed` and the running `packageVersion`. Pairing and conversations stay intact.
+
+For packages before 0.8.1 (no `oomi update` command), read the published guide, check `npm list -g oomi-ai --depth=0` and `npm view oomi-ai version` in separate commands. If equal, stop. Otherwise install the exact returned version through normal approvals. The first restart of an older or unsupervised bridge must happen from an independent host terminal/agent session, outside the Oomi conversation it would terminate. New CLI commands refuse to stop their own older host. After that bootstrap, in-chat restarts use the deferred path.
+
+Hermes single-query mode has no interactive approval surface. If its package/security check requires a human, tell the user to approve/run the exact install in an approval-capable host session, then continue there. A blocked install is not a reason to restart. Oomi does not override host permissions. `bridge repair` is also available for an actual connection fault when no package update is needed.
+
 ## Standard Connect Flow
 
-Install or update the local package:
+For a new installation (for an existing installation, use the safe update flow below):
 
 ```bash
 npm install -g oomi-ai@latest
@@ -69,7 +82,9 @@ oomi connect --runtime hermes --name hermes --app-url https://www.oomi.ai
 oomi connect --runtime command --name my-agent --command '["/absolute/path/to/adapter"]' --app-url https://www.oomi.ai
 ```
 
-Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. Hermes uses `chat --quiet --query-file -`, reads the final reply from stdout and the exact `session_id` from stderr, and resumes that ID on subsequent turns.
+Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. With oomi-ai 0.8.2+, an already-open Hermes conversation uses its existing local gateway owner and exact profile/session. Oomi attaches as another client; it never closes desktop, clears history, deletes a session lock, or substitutes a new chat. When no live owner exists, Hermes uses `chat --quiet --query-file -` and resumes the exact returned `session_id` on subsequent turns.
+
+Shared desktop conversations require Hermes's loopback WebSocket gateway, active-session discovery, and durable prompt/reply row IDs. Busy conversations ask you to retry after the current task. If a simultaneous desktop send queues your message without a reply receipt, or the connection drops after sending, check the same Hermes chat before resending. Oomi cannot safely repeat an uncertain action. Human approvals stay in the existing Hermes desktop UI. Shared photo submission is not yet supported; use Hermes desktop for that photo. Older or terminal-only owners without a shared gateway receive an actionable error, never a competing process. The shared owner keeps its existing environment, so use the explicit Oomi `--connection NAME` for account commands.
 
 The command verifies a real local reply, reuses saved credentials or pairs once, starts the bridge, waits for Oomi's subscription, then creates a single-use Auth Link. Failed verification means setup is incomplete: repair the selected runtime, never substitute a different one.
 
@@ -129,7 +144,7 @@ oomi invite --name hermes --app-url https://www.oomi.ai
 
 Do not pair again to refresh an expired Auth Link. Re-running `connect` reuses saved pairing and verification; only the first connection or an explicit `oomi verify` sends a model probe. A different command, profile, or working directory requires a new connection name, so one agent cannot silently replace another. Named connections store private state and logs under `~/.oomi/connections/<name>`; default OpenClaw keeps `~/.openclaw`. Since 0.8.0, `connect` installs a separate automatic-start service for each connection: macOS launchd or Linux systemd user. It restarts an exited worker and starts at the next login/user session. Linux servers can start at boot and remain running after logout when the host administrator enables user lingering (`loginctl enable-linger <user>`); `oomi bridge service status --name hermes` reports whether this is enabled. WSL needs systemd and a running WSL instance; native Windows does not yet have an automatic service installer. A sleeping, powered-off, or disconnected computer remains unavailable.
 
-Run `oomi bridge list` to find saved connection names and their startup protection on this computer. To upgrade an existing connection on **each computer**, install `oomi-ai@latest`, then run `oomi bridge repair --name <existing-name>` (omit the name for default OpenClaw). Repair installs/updates its supervisor, preserves pairing and conversations, and waits for the broker connection. It does not send a model probe or switch agents. Do not copy connection credentials between computers.
+Run `oomi bridge list` to find saved connection names and their startup protection on this computer. To update an existing connection on **each computer**, follow Updating Oomi safely above. Repair preserves pairing and conversations. On a running 0.8.1+ supervised bridge it queues a safe restart and reports pending work; on a stopped bridge it installs/starts supervision and waits for the broker connection. It does not send a model probe or switch agents. Do not copy connection credentials between computers.
 
 Use `oomi bridge service status --name hermes --json` to inspect startup protection. `oomi bridge stop --name hermes` disables automatic startup and stops only that connection; `oomi bridge start --name hermes` enables it again. `oomi bridge service uninstall --name hermes` removes startup management without deleting saved state. The legacy `oomi openclaw bridge service` command remains supported.
 
@@ -333,7 +348,7 @@ STT works but the assistant does not reply:
 
 Bridge keeps using an old package after update:
 
-- Action: run `oomi openclaw refresh --skip-version-check`.
+- Action: follow Updating Oomi safely above, then inspect `oomi status --json` for running version and maintenance result.
 - If still stale: run `oomi bridge repair` for default OpenClaw, or add the existing `--name` for a named connection.
 - On macOS service installs: run `oomi openclaw bridge service restart`.
 - Confirm with `oomi openclaw bridge ps`.

package/agent_instructions.md

@@ -101,9 +101,22 @@ Owner-originated identity changes are a deliberate exception: one notice per ide
 
 The legacy persona-app commands below remain compatibility tools; use Spaces for new agent-composed personal views.
 
+## Updating Oomi safely
+
+When the user asks you to update Oomi, read `oomi instructions` first; it supersedes copied setup/restart recipes. Keep the same connection on the same computer.
+
+1. Run `oomi update --connection NAME` (omit the selector for default OpenClaw). This only checks versions. If already current, report that and stop: do not reinstall or restart "to be sure."
+2. If an update exists, run the returned exact-version npm install command **alone**, through the runtime's normal approval flow. Do not append redirections, status checks or restarts. If installation is denied, fails, or cannot be verified, leave the bridge alone and explain the approval/error. Never disable security checks, retry through another executor, or enable blanket unattended approvals.
+3. After successful installation, check `npm list -g oomi-ai --depth=0` and `oomi update` separately. Only then run `oomi bridge repair --connection NAME`.
+4. A running 0.8.1+ supervised bridge queues its restart until active replies finish and queued phone replies are saved. If the result is `queued`, finish your reply now; do not wait for your own turn to end, poll in a loop, or claim completion. `oomi status --connection NAME --json` subsequently reports maintenance `completed`/`failed` and the running `packageVersion`. Pairing and conversations stay intact.
+
+For packages before 0.8.1 (no `oomi update` command), read the published guide, check `npm list -g oomi-ai --depth=0` and `npm view oomi-ai version` in separate commands. If equal, stop. Otherwise install the exact returned version through normal approvals. The first restart of an older or unsupervised bridge must happen from an independent host terminal/agent session, outside the Oomi conversation it would terminate. New CLI commands refuse to stop their own older host. After that bootstrap, in-chat restarts use the deferred path.
+
+Hermes single-query mode has no interactive approval surface. If its package/security check requires a human, tell the user to approve/run the exact install in an approval-capable host session, then continue there. A blocked install is not a reason to restart. Oomi does not override host permissions. `bridge repair` is also available for an actual connection fault when no package update is needed.
+
 ## Standard Connect Flow
 
-Install or update the local package:
+For a new installation (for an existing installation, use the safe update flow below):
 
 ```bash
 npm install -g oomi-ai@latest
@@ -122,7 +135,9 @@ oomi connect --runtime hermes --name hermes --app-url https://www.oomi.ai
 oomi connect --runtime command --name my-agent --command '["/absolute/path/to/adapter"]' --app-url https://www.oomi.ai
 ```
 
-Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. Hermes uses `chat --quiet --query-file -`, reads the final reply from stdout and the exact `session_id` from stderr, and resumes that ID on subsequent turns.
+Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. With oomi-ai 0.8.2+, an already-open Hermes conversation uses its existing local gateway owner and exact profile/session. Oomi attaches as another client; it never closes desktop, clears history, deletes a session lock, or substitutes a new chat. When no live owner exists, Hermes uses `chat --quiet --query-file -` and resumes the exact returned `session_id` on subsequent turns.
+
+Shared desktop conversations require Hermes's loopback WebSocket gateway, active-session discovery, and durable prompt/reply row IDs. Busy conversations ask you to retry after the current task. If a simultaneous desktop send queues your message without a reply receipt, or the connection drops after sending, check the same Hermes chat before resending. Oomi cannot safely repeat an uncertain action. Human approvals stay in the existing Hermes desktop UI. Shared photo submission is not yet supported; use Hermes desktop for that photo. Older or terminal-only owners without a shared gateway receive an actionable error, never a competing process. The shared owner keeps its existing environment, so use the explicit Oomi `--connection NAME` for account commands.
 
 The first connection verifies a real local reply (reconnects reuse verification), reuses saved credentials or pairs once, starts the bridge, waits for Oomi's subscription, then creates a single-use Auth Link. Failed verification means setup is incomplete: repair the selected runtime, never substitute a different one.
 
@@ -182,7 +197,7 @@ oomi invite --name hermes --app-url https://www.oomi.ai
 
 Do not pair again to refresh an expired Auth Link. Re-running `connect` reuses saved pairing and verification; only the first connection or an explicit `oomi verify` sends a model probe. A different command, profile, or working directory requires a new connection name, so one agent cannot silently replace another. Named connections store private state and logs under `~/.oomi/connections/<name>`; default OpenClaw keeps `~/.openclaw`. Since 0.8.0, `connect` installs a separate automatic-start service for each connection: macOS launchd or Linux systemd user. It restarts an exited worker and starts at the next login/user session. Linux servers can start at boot and remain running after logout when the host administrator enables user lingering (`loginctl enable-linger <user>`); `oomi bridge service status --name hermes` reports whether this is enabled. WSL needs systemd and a running WSL instance; native Windows does not yet have an automatic service installer. A sleeping, powered-off, or disconnected computer remains unavailable.
 
-Run `oomi bridge list` to find saved connection names and their startup protection on this computer. To upgrade an existing connection on **each computer**, install `oomi-ai@latest`, then run `oomi bridge repair --name <existing-name>` (omit the name for default OpenClaw). Repair installs/updates its supervisor, preserves pairing and conversations, and waits for the broker connection. It does not send a model probe or switch agents. Do not copy connection credentials between computers.
+Run `oomi bridge list` to find saved connection names and their startup protection on this computer. To update an existing connection on **each computer**, follow Updating Oomi safely above. Repair preserves pairing and conversations. On a running 0.8.1+ supervised bridge it queues a safe restart and reports pending work; on a stopped bridge it installs/starts supervision and waits for the broker connection. It does not send a model probe or switch agents. Do not copy connection credentials between computers.
 
 Use `oomi bridge service status --name hermes --json` to inspect startup protection. `oomi bridge stop --name hermes` disables automatic startup and stops only that connection; `oomi bridge start --name hermes` enables it again. `oomi bridge service uninstall --name hermes` removes startup management without deleting saved state. The legacy `oomi openclaw bridge service` command remains supported.
 

package/bin/oomi-ai.js

@@ -8,6 +8,7 @@ import net from 'net';
 import { lookup as dnsLookup } from 'dns/promises';
 import { fileURLToPath } from 'url';
 import WebSocket from 'ws';
+import { planPackageUpdate, isWorkerDescendant, queueRestart, readMaintenance, createMaintenanceController } from '../lib/bridgeMaintenance.js';
 import { bridgeServiceConfig, createBridgeService, renderLaunchAgent } from '../lib/bridgeService.js';
 import { LOCAL_PROTOCOL_MIN, LOCAL_PROTOCOL_MAX, probeGateway } from '../lib/gatewayProbe.js';
 import { LocalAgentRuntime, localAgentConfig, runLocalAgent, writePrivateJson, startChannelWorker } from '../lib/localAgent.js';
@@ -193,8 +194,7 @@ async function maybeNotifyUpdate(command) {
 
   if (compareVersions(currentVersion, latestVersion) < 0) {
     console.warn(`[oomi] Update available: oomi-ai ${currentVersion} -> ${latestVersion}`);
-    console.warn('[oomi] Update command: pnpm add -g oomi-ai@latest');
-    console.warn('[oomi] Fallback update command: npm install -g oomi-ai@latest');
+    console.warn('[oomi] Read the safe update plan: oomi update');
   }
 }
 
@@ -202,6 +202,8 @@ function usage() {
   console.log(`oomi <command>
 
 Commands:
+  update
+    Check for a newer package and return a safe, approval-preserving update plan.
   connect --runtime openclaw|hermes|command [--name CONNECTION] [--agent-name "Your name"] [--app-url URL]
     Verify the selected local agent, pair once, start its bridge, and return an Auth Link.
     Hermes: --profile PROFILE and --resume SESSION select the intended agent/session.
@@ -704,6 +706,9 @@ async function handleContextHealthSyncCommand(flags = {}) {
 async function refreshBridgeForUpdate(flags = {}, options = {}) {
   const logger = options.logger || null;
   const service = currentBridgeService();
+  const deferred = deferLiveRestart({ print: false });
+  if (deferred) return { queued: true, maintenance: deferred };
+  assertIndependentMaintenance();
   if (service.status().installed) {
     logger?.(`Restarting supervised bridge ${service.config.target}.`);
     await stopSupervisedBridge(service);
@@ -771,6 +776,7 @@ async function handleOpenclawRefreshCommand(flags = {}) {
     return;
   }
 
+  if (payload.bridge.queued) { console.log(payload.bridge.maintenance.message); return; }
   console.log(`Oomi refresh complete (${payload.currentVersion})`);
   if (payload.bridge.restarted) {
     console.log(`Bridge restarted (${payload.bridge.mode}).`);
@@ -2582,15 +2588,24 @@ async function startOpenclawBridge(flags) {
     consecutiveFailures: 0,
     pid: process.pid,
     startedAt: bridgeNowIso(),
+    packageVersion: currentPackageVersion(),
+    maintenanceProtocol: 1,
   });
 
+  try { refreshSelectedSkill(bridgeState); } catch (err) { console.warn('Oomi skill refresh failed:', err.message); }
   console.log(`Starting ${bridgeState.runtime || 'openclaw'} bridge: device=${deviceId}`);
+  let backgroundTurns = 0;
+  const deliverAgentEvent = async (turn) => {
+    backgroundTurns++;
+    try { return await (localRuntime ? localRuntime.turn(turn) : probeGateway({ gateway, deviceIdentity: gatewayDeviceIdentity, prepareFrame: prepareGatewayFrameForLocalGateway, turn, timeoutMs: 180000 })); }
+    finally { backgroundTurns--; }
+  };
   const stopChannelWorker = localRuntime ? startChannelWorker(bridgeState, localRuntime) : () => {};
   const stopIdentityWorker = startIdentityWorker({
     state: { ...bridgeState, brokerHttp, deviceToken },
     receiptPath: path.join(path.dirname(resolveBridgeStatePath()), 'oomi-identity-receipt.json'),
     // Applying a specific settings revision is idempotent, unlike a user turn.
-    deliver: (turn) => localRuntime ? localRuntime.turn({ ...turn, retryInterrupted: false }) : probeGateway({ gateway, deviceIdentity: gatewayDeviceIdentity, prepareFrame: prepareGatewayFrameForLocalGateway, turn, timeoutMs: 180000 }),
+    deliver: deliverAgentEvent,
     acknowledgeCommand: (identity) => `oomi identity acknowledge${bridgeConnectionName ? ` --connection ${bridgeConnectionName}` : ''} --identity-id ${identity.identityId} --revision ${identity.revision}`,
     onError: () => updateBridgeStatus({ identitySyncError: 'Identity notice was interrupted. Read oomi identity get in your agent to apply and acknowledge the pending revision; no model retry was sent.' }),
   });
@@ -2598,7 +2613,7 @@ async function startOpenclawBridge(flags) {
     state: { ...bridgeState, brokerHttp, deviceToken },
     connection: bridgeConnectionName,
     receiptPath: path.join(path.dirname(resolveBridgeStatePath()), 'oomi-routine-receipt.json'),
-    deliver: (turn) => localRuntime ? localRuntime.turn(turn) : probeGateway({ gateway, deviceIdentity: gatewayDeviceIdentity, prepareFrame: prepareGatewayFrameForLocalGateway, turn, timeoutMs: 180000 }),
+    deliver: deliverAgentEvent,
     onError: () => updateBridgeStatus({ routineSyncError: 'Routine updates are waiting for the runtime. They will retry.' }),
   });
   console.log(`Local gateway: ${gateway.gatewayUrl}`);
@@ -2608,6 +2623,19 @@ async function startOpenclawBridge(flags) {
   );
 
   const activeGatewaySockets = new Map();
+  const activeGatewayRuns = new Set();
+  let currentBrokerSocket;
+  const maintenanceTick = createMaintenanceController({
+    directory: path.dirname(resolveBridgeStatePath()),
+    isIdle: () => !backgroundTurns && !localRuntime?.active.size && !localRuntime?.deliveries && !activeGatewayRuns.size
+      && !currentBrokerSocket?.bufferedAmount
+      && [...activeGatewaySockets.values()].every((session) => !session.pendingRequests?.size),
+    isConnected: () => readBridgeStatus().status === 'connected',
+    restart: () => currentBridgeService().restart(),
+  });
+  const maintenanceTimer = setInterval(() => {
+    try { maintenanceTick(); } catch (err) { console.error('[bridge] maintenance:', err.message); }
+  }, 250);
   const reconnectState = {
     attempt: 0,
     timer: null,
@@ -2960,6 +2988,7 @@ async function startOpenclawBridge(flags) {
     wsUrl.searchParams.set('token', deviceToken);
 
     const brokerSocket = new WebSocket(wsUrl.toString());
+    currentBrokerSocket = brokerSocket;
     let actionCableHeartbeat = null;
 
     const clearChallengeTimer = (sessionBridge) => {
@@ -3322,10 +3351,16 @@ async function startOpenclawBridge(flags) {
           }
         }
 
+        if (gatewayPayload?.type === 'res' && gatewayPayload.ok && gatewayPayload.payload?.status === 'started' && gatewayPayload.payload?.runId) {
+          activeGatewayRuns.add(gatewayPayload.payload.runId);
+        }
+        if (gatewayPayload?.event === 'chat' && ['final', 'error', 'aborted'].includes(gatewayPayload.payload?.state)) {
+          activeGatewayRuns.delete(gatewayPayload.payload.runId);
+        }
         if (gatewayPayload?.event === 'chat' && gatewayPayload.payload?.state === 'final') {
           updateBridgeStatus({ runtimeReady: true, lastReplyAt: bridgeNowIso() });
         } else if (gatewayPayload?.event === 'chat' && gatewayPayload.payload?.state === 'error') {
-          updateBridgeStatus({ status: 'degraded', runtimeReady: false, lastErrorMessage: gatewayPayload.payload.errorMessage || 'The local agent failed to answer.' });
+          updateBridgeStatus({ ...(localRuntime && gatewayPayload.payload.runtimeReady === true ? { runtimeReady: true } : { status: 'degraded', runtimeReady: false }), lastErrorMessage: gatewayPayload.payload.errorMessage || 'The local agent failed to answer.' });
         }
 
         if (isGatewayRunStartedFrame(frame)) {
@@ -3775,6 +3810,7 @@ async function startOpenclawBridge(flags) {
 
   const markStopped = async (signal) => {
     reconnectState.stopped = true;
+    clearInterval(maintenanceTimer);
     stopChannelWorker();
     stopIdentityWorker();
     stopRoutineWorker();
@@ -3898,11 +3934,6 @@ async function pairAndStartOpenclawBridge(flags) {
     console.log('');
     console.log('Share this exact response with the user (no extra text):');
     console.log('----------------------------------------');
-    const skillSource = resolveSkillSource();
-  if (runtime === 'hermes') installSkill(skillSource, [path.join(state.localAgent.hermesHome, ...(state.localAgent.profile === 'default' ? [] : ['profiles', state.localAgent.profile]), 'skills')]);
-  else if (runtime === 'openclaw') installSkill(skillSource, [resolveOpenclawSkillsDir()]);
-  else if (flags['skills-dir']) installSkill(skillSource, [flags['skills-dir']]);
-  console.log('Oomi tools: run oomi capabilities, then oomi instructions. Add --connection ' + (bridgeConnectionName || '(omit for default)') + ' to commands. Passive updates do not invoke your model.');
   console.log('Oomi Connect Ready');
     console.log(`Auth Link: ${inviteUrl}`);
     console.log('----------------------------------------');
@@ -4019,6 +4050,7 @@ function printOpenclawBridgeStatus(flags) {
     },
     runtime: runtimeStatus,
     supervision: currentBridgeService().status(),
+    maintenance: readMaintenance(path.dirname(resolveBridgeStatePath())),
   };
 
   if (jsonOutput) {
@@ -4026,6 +4058,7 @@ function printOpenclawBridgeStatus(flags) {
     return;
   }
 
+  if (payload.maintenance) console.log(`Maintenance: ${payload.maintenance.status} — ${payload.maintenance.message || ''}`);
   console.log('Oomi Bridge Status');
   const supervision = payload.supervision;
   console.log(`Automatic startup: ${supervision.installed && supervision.enabled ? supervision.manager + ' (' + supervision.startsAt + ')' : 'off'}`);
@@ -4168,7 +4201,25 @@ function requireSavedBridge() {
   if (!readBridgeState().deviceToken) throw new Error('No saved connection. Run oomi connect with an explicit runtime first.');
 }
 
+function assertIndependentMaintenance() {
+  const running = findRunningBridgeProcess();
+  if (running && isWorkerDescendant(running.pid)) {
+    throw new Error('This command would stop the agent carrying this conversation. Use bridge repair/restart with a running 0.8.1+ bridge, or perform the first upgrade from an independent host terminal. The bridge was left unchanged.');
+  }
+}
+
+function deferLiveRestart({ print = true } = {}) {
+  const status = readBridgeStatus();
+  const service = currentBridgeService().status();
+  if (status.maintenanceProtocol !== 1 || !status.pid || !isBridgeProcess(status.pid)
+      || !service.running || service.pid !== status.pid || !service.enabled) return false;
+  const request = queueRestart(path.dirname(resolveBridgeStatePath()), status.pid);
+  if (print) console.log(JSON.stringify(request, null, 2));
+  return request;
+}
+
 async function stopSupervisedBridge(service) {
+  assertIndependentMaintenance();
   // Unload/disable before signalling the worker, otherwise KeepAlive immediately recreates it.
   service.stop();
   const stopped = await stopBridgeProcesses();
@@ -4187,6 +4238,8 @@ async function handleBridgeServiceCommand(actionRaw = '', flags = {}) {
     throw new Error('Use: oomi bridge service [install|start|stop|restart|status|uninstall] [--name NAME]');
   }
   if (['install', 'start', 'restart'].includes(action)) requireSavedBridge();
+  if (['install', 'restart'].includes(action) && !isTruthyFlag(flags['no-start']) && deferLiveRestart()) return;
+  if (action !== 'start') assertIndependentMaintenance();
   if (action === 'install') {
     service.install({ noStart: true });
     await stopSupervisedBridge(service);
@@ -4209,6 +4262,7 @@ async function handleBridgeServiceCommand(actionRaw = '', flags = {}) {
 
 async function repairBridge(flags = {}) {
   requireSavedBridge();
+  if (!isTruthyFlag(flags['no-start']) && deferLiveRestart()) return;
   await handleBridgeServiceCommand('install', flags);
   if (!isTruthyFlag(flags['no-start'])) {
     await waitForBridgeConnection({});
@@ -4291,6 +4345,8 @@ async function handleBridgeLifecycleCommand(flags = {}, actionRaw = '') {
     return handleBridgeServiceCommand(action, flags);
   }
 
+  if (['stop', 'restart'].includes(action)) assertIndependentMaintenance();
+
   if (action === 'start' || action === 'ensure') {
     await startBridgeLifecycle(flags);
     return;
@@ -4364,7 +4420,16 @@ async function verifyLocalAgent(state) {
   return { runtime: state.runtime || 'openclaw', ...result };
 }
 
+function refreshSelectedSkill(state, flags = {}) {
+  const source = resolveSkillSource();
+  if (state.runtime === 'hermes' && state.localAgent?.hermesHome) {
+    installSkill(source, [path.join(state.localAgent.hermesHome, ...(state.localAgent.profile === 'default' ? [] : ['profiles', state.localAgent.profile]), 'skills')]);
+  } else if (!state.runtime || state.runtime === 'openclaw') installSkill(source, [resolveOpenclawSkillsDir()]);
+  else if (flags['skills-dir']) installSkill(source, [flags['skills-dir']]);
+}
+
 async function connectLocalAgent(flags) {
+  assertIndependentMaintenance();
   const agentName = flags['agent-name'] === undefined ? undefined : validateAgentName(flags['agent-name']);
   const runtime = String(flags.runtime || '');
   if (!['openclaw', 'hermes', 'command'].includes(runtime)) throw new Error('Specify --runtime openclaw, hermes, or command. Never select a different agent just because it is installed.');
@@ -4436,6 +4501,7 @@ async function connectLocalAgent(flags) {
   console.log(unmanaged ? 'Automatic startup: off (--no-service); your host supervisor must manage recovery.'
     : `Automatic startup: ${service.config.platform === 'darwin' ? 'macOS login service' : 'Linux user service'}; restarts after worker exits.`);
   const invite = await requestConnectInviteLink({ backendHttp: state.brokerHttp, appUrl, sessionKey: state.sessionKey, deviceToken: state.deviceToken });
+  refreshSelectedSkill(state, flags);
   console.log(`Verified agent: ${runtime}${state.localAgent?.profile ? ` (${state.localAgent.profile})` : ''}`);
   console.log('Oomi Connect Ready');
   console.log(`Auth Link: ${invite.inviteUrl}`);
@@ -4457,9 +4523,10 @@ async function main() {
   if (connection && !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(connection)) throw new Error('Connection name must use lowercase letters, numbers, underscores, or hyphens.');
   bridgeConnectionName = connection || '';
 
+  if (command === 'update') { console.log(JSON.stringify(planPackageUpdate(currentPackageVersion(), await fetchLatestPublishedVersion('oomi-ai')), null, 2)); return; }
   if (command === 'instructions') { console.log(fs.readFileSync(resolveInstructionsFile(), 'utf8')); return; }
   if (command === 'capabilities') {
-    console.log(JSON.stringify({ instructions: 'oomi instructions', skill: path.join(PACKAGE_ROOT, 'skills/oomi/SKILL.md'), connectionSelector: '--connection NAME',
+    console.log(JSON.stringify({ instructions: 'oomi instructions', packageUpdate: 'oomi update', skill: path.join(PACKAGE_ROOT, 'skills/oomi/SKILL.md'), connectionSelector: '--connection NAME',
       spaces: { catalog: 'oomi spaces catalog', list: 'oomi spaces list', create: 'oomi spaces create --file space.json', update: 'oomi spaces update ID --file change.json', revisions: 'oomi spaces revisions ID', upgrade: 'oomi spaces upgrade ID --file upgrade.json', guide: 'oomi instructions' },
       health: { steps: 'oomi context health --window week --metric steps --json', calendarWeek: 'oomi context health --window range --from YYYY-MM-DD --to YYYY-MM-DD --metric steps --json', largeResults: '--output new-file.json', plugins: 'oomi context plugins', missing: 'unknown, never zero', week: 'rolling seven days; use explicit range for calendar week' },
       objectives: { list: 'oomi objectives list', show: 'oomi objectives show ID', history: 'oomi objectives history ID [--before YYYY-MM-DD]', create: 'oomi objectives create --file goal.json', update: 'oomi objectives update ID --file change.json', respond: 'oomi objectives respond ID --file response.json', calendar: 'daily/weekly/monthly/once; stored time zone', streaks: 'optional goal references in the Space catalog' },

package/lib/bridgeMaintenance.js

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { readJson, writePrivateJson } from './localAgent.js';
+
+export const maintenancePath = (directory) => path.join(directory, 'oomi-bridge-maintenance.json');
+export const readMaintenance = (directory) => readJson(maintenancePath(directory), null);
+const pending = (request) => ['queued', 'restarting'].includes(request?.status);
+
+// This is a plan, never an installer: the runtime keeps its normal package approval gate.
+export function planPackageUpdate(current, latest) {
+  const valid = (v) => typeof v === 'string' && /^\d+\.\d+\.\d+$/.test(v);
+  if (!valid(current) || !valid(latest)) throw new Error('Could not verify the published version. Leave the package and bridge unchanged; try again later.');
+  const a = current.split('.').map(Number), b = latest.split('.').map(Number);
+  const difference = b.map((v, i) => v - a[i]).find((v) => v !== 0) || 0;
+  return { currentVersion: current, latestVersion: latest, status: difference > 0 ? 'update_available' : 'up_to_date',
+    ...(difference > 0 ? { installCommand: `npm install -g oomi-ai@${latest}`,
+      instruction: 'Run this command alone through your normal approval flow. If blocked or unsuccessful, stop and report the approval needed; do not restart or change security settings. After success, verify the installed version, then run oomi bridge repair for this connection.' }
+      : { instruction: 'Already current. Do not reinstall or restart. Check oomi status only if the user also reports a connection problem.' }) };
+}
+
+export function isWorkerDescendant(workerPid, { pid = process.pid, run = spawnSync } = {}) {
+  if (!Number.isInteger(workerPid) || workerPid <= 0) return false;
+  const result = run('ps', ['-axo', 'pid=,ppid='], { encoding: 'utf8', timeout: 5000 });
+  if (result.status !== 0) throw new Error('Cannot establish whether this command would stop its own agent. Run maintenance from an independent host terminal.');
+  const parents = new Map(String(result.stdout).trim().split('\n').map((line) => line.trim().split(/\s+/).map(Number)));
+  const visited = new Set();
+  while (pid > 1 && !visited.has(pid)) {
+    if (pid === workerPid) return true;
+    visited.add(pid); pid = parents.get(pid);
+  }
+  return false;
+}
+
+export function queueRestart(directory, workerPid, now = Date.now()) {
+  const previous = readMaintenance(directory);
+  if (pending(previous) && previous.workerPid === workerPid && previous.expiresAt > now) return previous;
+  const request = { id: randomUUID(), status: 'queued', action: 'restart', workerPid, requestedAt: now, expiresAt: now + 300000,
+    message: 'Restart queued. Finish this reply; the bridge will restart after active replies are delivered. Check oomi status afterward; queued is not completed.' };
+  writePrivateJson(maintenancePath(directory), request);
+  return request;
+}
+
+// One host supervisor owns the replacement. Never disable/unload the service from its own job.
+export function createMaintenanceController({ directory, pid = process.pid, isIdle, isConnected, restart, now = Date.now }) {
+  let idleSince = null;
+  return () => {
+    const request = readMaintenance(directory);
+    if (!pending(request)) { idleSince = null; return; }
+    const finish = (status, message) => writePrivateJson(maintenancePath(directory), { ...request, status, message, finishedAt: now() });
+    if (request.workerPid !== pid) {
+      if (isConnected()) finish('completed', 'Bridge restarted and reconnected.');
+      else if (now() > request.expiresAt) finish('failed', 'The replacement bridge has not reconnected. Check oomi status and the host connection.');
+      return;
+    }
+    if (now() > request.expiresAt) { finish('failed', 'Restart expired while waiting for replies; no further restart will be attempted.'); return; }
+    if (request.status !== 'queued') return;
+    if (!isIdle()) { idleSince = null; return; }
+    idleSince ??= now();
+    if (now() - idleSince < 1000) return;
+    writePrivateJson(maintenancePath(directory), { ...request, status: 'restarting' });
+    try { restart(); } catch (err) { finish('failed', err.message); }
+  };
+}

package/lib/bridgeService.js

@@ -18,7 +18,7 @@ export function bridgeServiceConfig({ name = '', stateDirectory, logPath, script
   if (name && !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name)) throw new Error('Invalid connection name.');
   const label = `ai.oomi.bridge${name ? '.' + name : ''}`;
   const directory = path.resolve(stateDirectory);
-  const environment = { OOMI_SKIP_UPDATE_CHECK: '1', OOMI_CONNECTION: name, PATH: env.PATH || '/usr/local/bin:/usr/bin:/bin',
+  const environment = { HOME: home, OOMI_SKIP_UPDATE_CHECK: '1', OOMI_CONNECTION: name, PATH: env.PATH || '/usr/local/bin:/usr/bin:/bin',
     // Always pin the state root. A login service must not resolve another connection from its environment.
     OPENCLAW_HOME: path.resolve(env.OPENCLAW_HOME || path.join(home, '.openclaw')) };
   if (name) environment.OOMI_CONNECTIONS_DIR = path.dirname(directory);
@@ -158,6 +158,13 @@ export function createBridgeService(config, { run = spawnSync } = {}) {
       else if (!current.running) invoke(['kickstart', config.target]);
     } else invoke(['enable', '--now', config.target]);
   }
+  function restart() {
+    preflight();
+    const current = status();
+    if (!current.installed || !current.loaded || !current.enabled) throw new Error('Restart requires an enabled, loaded service. Repair it from an independent host terminal.');
+    // Submit one supervisor-owned replacement, so killing the caller cannot strand the service.
+    invoke(mac ? ['kickstart', '-k', config.target] : ['--no-block', 'restart', config.target]);
+  }
   function install({ noStart = false } = {}) {
     assertAvailable();
     writeDefinition();
@@ -169,5 +176,5 @@ export function createBridgeService(config, { run = spawnSync } = {}) {
     if (fs.existsSync(config.file)) fs.unlinkSync(config.file);
     if (!mac) invoke(['daemon-reload']);
   }
-  return { config, availability, preflight, status, install, start, stop, uninstall };
+  return { config, availability, preflight, status, install, start, stop, restart, uninstall };
 }

package/lib/hermesGateway.js

@@ -0,0 +1,184 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import WebSocket from 'ws';
+
+// Only fixed, sanitized messages cross the bridge. Gateway diagnostics may contain
+// credentials, private history or tool output; never interpolate them into errors.
+export class HermesTurnError extends Error {
+  constructor(code, message, { notStarted = false, runtimeReady = true } = {}) {
+    super(message); this.code = code; this.notStarted = notStarted; this.runtimeReady = runtimeReady;
+  }
+}
+const refused = (code, message) => new HermesTurnError(code, message, { notStarted: true });
+export function hermesRefusal(reason) {
+  if (reason === 'SESSION_NOT_OWNED') return refused('hermes_session_owned', 'This conversation is open in Hermes, but Oomi could not attach to it. Keep the same chat and update Hermes and Oomi on that computer, then retry.');
+  if (reason === 'MAX_CONCURRENT_SESSIONS') return refused('hermes_session_limit', 'Hermes has reached its active conversation limit. Free a conversation slot or raise the limit in Hermes, then retry.');
+  if (reason === 'SESSION_COORDINATION_UNAVAILABLE') return refused('hermes_coordination_unavailable', 'Hermes could not verify conversation ownership. Check Hermes on that computer, then retry.');
+  return null;
+}
+function readLocalJson(file, missing) {
+  try {
+    if (fs.statSync(file).size > 1024 * 1024) throw new Error();
+    return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+  } catch (err) {
+    if (err.code === 'ENOENT') return missing;
+    throw hermesRefusal('SESSION_COORDINATION_UNAVAILABLE');
+  }
+}
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (err) { return err.code !== 'ESRCH'; }
+}
+function findOwner(config, sessionId) {
+  const profile = config.profile || 'default';
+  if (!config.hermesHome || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(profile)) throw hermesRefusal('SESSION_COORDINATION_UNAVAILABLE');
+  const home = profile === 'default' ? config.hermesHome : path.join(config.hermesHome, 'profiles', profile);
+  const raw = readLocalJson(path.join(home, 'runtime', 'active_sessions.json'), []);
+  const entries = Array.isArray(raw) ? raw : raw?.entries;
+  if (!Array.isArray(entries) || entries.some(e => !e || typeof e.session_id !== 'string' || !Number.isInteger(e.pid) || e.pid <= 0)) throw hermesRefusal('SESSION_COORDINATION_UNAVAILABLE');
+  const owners = entries.filter(e => e.session_id === sessionId && alive(e.pid));
+  if (!owners.length) return null; // CLI still acquires Hermes's own exclusive lease.
+  if (owners.length !== 1) throw hermesRefusal('SESSION_COORDINATION_UNAVAILABLE');
+  const owner = owners[0];
+  const ledger = readLocalJson(path.join(config.hermesHome, 'spawn-ledger.json'), []);
+  const hosts = new Set(['', '0.0.0.0', '127.0.0.1', '::', '::1', 'localhost']);
+  const candidates = Array.isArray(ledger) ? ledger.filter(e => e?.pid === owner.pid && e.isolated !== true && ['serve', 'dashboard'].includes(e.purpose) && hosts.has(e.host || '') && Number.isInteger(e.port) && e.port > 0 && e.port <= 65535) : [];
+  if (!owner.metadata?.live_session_id || candidates.length !== 1) throw hermesRefusal('SESSION_NOT_OWNED');
+  const backend = candidates[0];
+  return { pid: owner.pid, liveId: owner.metadata.live_session_id, profile, base: `http://${backend.host === '::1' ? '[::1]' : '127.0.0.1'}:${backend.port}` };
+}
+
+async function servedToken(base, signal) {
+  // Match Hermes Desktop's supported loopback discovery. Never follow redirects,
+  // read credential stores, or bypass a gateway login when no token is served.
+  const response = await fetch(`${base}/`, { signal, redirect: 'error' });
+  if (!response.ok) throw new Error();
+  let html = '';
+  for await (const chunk of response.body) {
+    html += Buffer.from(chunk).toString('utf8');
+    if (html.length > 1024 * 1024) throw new Error();
+  }
+  const match = html.match(/window\.__HERMES_SESSION_TOKEN__\s*=\s*("(?:\\.|[^"\\])*")/);
+  const token = match && JSON.parse(match[1]);
+  if (typeof token !== 'string' || !token || token.length > 8192) throw new Error();
+  return token;
+}
+
+function connect(owner, token, signal, onEvent) {
+  const socket = new WebSocket(`${owner.base.replace(/^http/, 'ws')}/api/ws?token=${encodeURIComponent(token)}`, { handshakeTimeout: 5000, maxPayload: 4 * 1024 * 1024, followRedirects: false });
+  const pending = new Map();
+  let sequence = 0, failure;
+  let readyResolve, readyReject;
+  const ready = new Promise((resolve, reject) => { readyResolve = resolve; readyReject = reject; });
+  ready.catch(() => {});
+  const readyTimer = setTimeout(() => { fail(); socket.terminate(); }, 5000);
+  const fail = (err = new Error()) => {
+    if (failure) return;
+    failure = err; clearTimeout(readyTimer); readyReject(err);
+    for (const p of pending.values()) { clearTimeout(p.timer); p.reject(err); }
+    pending.clear(); onEvent(null, err);
+  };
+  const abort = () => { fail(); socket.terminate(); };
+  signal.addEventListener('abort', abort, { once: true });
+  socket.on('error', () => fail());
+  socket.on('close', () => fail());
+  socket.on('message', data => {
+    try {
+      for (const line of data.toString().split('\n').filter(s => s.trim())) {
+        const frame = JSON.parse(line);
+        if (frame.method === 'event') {
+          if (frame.params?.type === 'gateway.ready') { clearTimeout(readyTimer); readyResolve(); }
+          else onEvent(frame.params);
+        } else if (pending.has(frame.id)) {
+          const p = pending.get(frame.id); pending.delete(frame.id); clearTimeout(p.timer);
+          if (frame.error) p.reject(hermesRefusal(p.method === 'prompt.submit' && frame.error.code === 4090 && frame.error.data?.reason) || new Error());
+          else p.resolve(frame.result);
+        }
+      }
+    } catch { fail(); }
+  });
+  return {
+    ready,
+    rpc(method, params = {}) {
+      if (failure || signal.aborted) return Promise.reject(failure || new Error());
+      const id = ++sequence;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { pending.delete(id); reject(new Error()); }, 10000);
+        pending.set(id, { resolve, reject, timer, method });
+        socket.send(JSON.stringify({ jsonrpc: '2.0', id, method, params: { ...params, profile: owner.profile } }), err => { if (err) fail(); });
+      });
+    },
+    close() { signal.removeEventListener('abort', abort); fail(); socket.terminate(); },
+  };
+}
+
+/** Attach to the exact existing owner, or return null when CLI lease acquisition is appropriate. */
+export async function runSharedHermesTurn(config, request, { signal, timeoutMs = 180000 } = {}) {
+  if (!request.runtimeSessionId) return null;
+  const owner = findOwner(config, request.runtimeSessionId);
+  if (!owner) return null;
+  // Hermes's image.attach stages media globally for the next sender. Refuse until
+  // the gateway supports atomic message+media admission; never steal desktop photos.
+  if (request.imagePaths?.length) throw refused('hermes_shared_photo', 'Photos in an open Hermes desktop conversation are not supported yet. Send this photo from Hermes desktop in the same chat.');
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  if (signal?.aborted) abort(); else signal?.addEventListener('abort', abort, { once: true });
+  const timer = setTimeout(abort, timeoutMs);
+  let client, heartbeat, dispatched = false, userRowId;
+  const early = [];
+  let completeResolve, completeReject;
+  const completed = new Promise((resolve, reject) => { completeResolve = resolve; completeReject = reject; });
+  completed.catch(() => {});
+  const final = payload => {
+    if (payload?.persisted_turn?.user_row_id !== userRowId) return;
+    if (payload.status !== 'complete' || !Number.isSafeInteger(payload.persisted_turn.final_assistant_row_id) || typeof payload.text !== 'string' || !payload.text.trim()) {
+      completeReject(new HermesTurnError('hermes_turn_failed', 'Hermes did not finish this message. Check the same conversation in Hermes for its error or approval request before retrying.'));
+    } else completeResolve({ text: payload.text.trim(), sessionId: request.runtimeSessionId });
+  };
+  try {
+    if (controller.signal.aborted) throw new Error();
+    const authTimer = setTimeout(abort, Math.min(timeoutMs, 5000));
+    let token;
+    try { token = await servedToken(owner.base, controller.signal); } finally { clearTimeout(authTimer); }
+    client = connect(owner, token, controller.signal, (event, err) => {
+      if (err) { completeReject(err); return; }
+      if (!dispatched || event?.type !== 'message.complete' || event.session_id !== owner.liveId) return;
+      if (userRowId) final(event.payload);
+      else { if (early.length >= 32) early.shift(); early.push(event.payload); }
+    });
+    await client.ready;
+    const list = await client.rpc('session.active_list');
+    const matches = list?.sessions?.filter(s => s.id === owner.liveId && s.session_key === request.runtimeSessionId);
+    if (matches?.length !== 1) throw hermesRefusal('SESSION_NOT_OWNED');
+    if (matches[0].status !== 'idle') throw refused('hermes_session_busy', 'Hermes is busy in this conversation. Let its current task finish, then retry here. Your message has not been sent.');
+    const attached = await client.rpc('session.activate', { session_id: owner.liveId, omit_messages: true });
+    if (attached?.session_id !== owner.liveId || attached.session_key !== request.runtimeSessionId) throw hermesRefusal('SESSION_NOT_OWNED');
+    if (attached.running || attached.queued || attached.status !== 'idle') throw refused('hermes_session_busy', 'Hermes is busy in this conversation. Let its current task finish, then retry here. Your message has not been sent.');
+    // No server_requests capability: existing Hermes clients retain their normal
+    // approval UI. Oomi never answers or auto-approves another client's requests.
+    heartbeat = setInterval(() => { client.rpc('gateway.ping').catch(completeReject); }, 15000);
+    dispatched = true;
+    const accepted = await client.rpc('prompt.submit', { session_id: owner.liveId, text: request.message, queued: true });
+    // A concurrent desktop send may win after the idle check. Hermes queues ours
+    // without interruption but currently returns no durable row ID for that path.
+    // Do not misattribute the desktop reply or replay a possibly accepted action.
+    if (accepted?.status === 'queued') throw new HermesTurnError('hermes_message_queued', 'Hermes queued your message behind another task. Check the same conversation in Hermes for the reply; do not send this message again.');
+    if (accepted?.status !== 'streaming' || !Number.isSafeInteger(accepted.user_row_id) || accepted.user_row_id <= 0) throw new HermesTurnError('hermes_receipt_unavailable', 'Hermes may have accepted your message, but could not confirm its reply address. Check the same conversation in Hermes before retrying. Update Hermes on that computer for shared chat support.');
+    userRowId = accepted.user_row_id;
+    for (const payload of early) final(payload);
+    const result = await completed;
+    // Compaction can rotate Hermes's durable session key while keeping the same
+    // live owner. Follow that exact owner, never a 'latest' conversation lookup.
+    try {
+      const current = await client.rpc('session.active_list');
+      const session = current?.sessions?.find(s => s.id === owner.liveId);
+      if (typeof session?.session_key === 'string' && /^[A-Za-z0-9_-]+$/.test(session.session_key)) result.sessionId = session.session_key;
+    } catch { /* The confirmed reply remains valid when a follow-up read fails. */ }
+    return result;
+  } catch (err) {
+    if (err instanceof HermesTurnError) throw err;
+    if (dispatched) throw new HermesTurnError('hermes_reply_uncertain', 'Oomi lost track of this reply. Hermes may still be working in the same conversation. Check it there before sending this message again.');
+    throw refused('hermes_attach_failed', 'Oomi could not attach to the open Hermes conversation. Check Hermes on that computer and its local connection, then retry. Your message has not been sent.');
+  } finally {
+    clearTimeout(timer); clearInterval(heartbeat); signal?.removeEventListener('abort', abort); controller.abort(); client?.close();
+  }
+}

package/lib/localAgent.js

@@ -4,6 +4,7 @@ import os from 'node:os';
 import { spawn } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import { createHash, randomUUID } from 'node:crypto';
+import { runSharedHermesTurn, hermesRefusal } from './hermesGateway.js';
 
 const IMAGE_EXTENSIONS = { 'image/jpeg': '.jpg', 'image/png': '.png', 'image/webp': '.webp', 'image/gif': '.gif' };
 const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
@@ -98,7 +99,24 @@ export function localAgentConfig(flags) {
 }
 
 // No shell interpolation. Message bodies travel over stdin, never as executable code.
-export function runLocalAgent(config, request, { signal, timeoutMs = 180000 } = {}) {
+export async function runLocalAgent(config, request, options = {}) {
+  if (config.runtime === 'hermes') {
+    const shared = await runSharedHermesTurn(config, request, options);
+    if (shared) return shared;
+  }
+  try { return await runAgentProcess(config, request, options); }
+  catch (err) {
+    // Ownership may change between discovery and CLI lease acquisition. Only a
+    // machine-readable pre-start refusal permits trying the live owner once.
+    if (config.runtime === 'hermes' && err.code === 'hermes_session_owned') {
+      const shared = await runSharedHermesTurn(config, request, options);
+      if (shared) return shared;
+    }
+    throw err;
+  }
+}
+
+function runAgentProcess(config, request, { signal, timeoutMs = 180000 } = {}) {
   return new Promise((resolve, reject) => {
     const args = config.command.slice(1);
     if (config.runtime === 'hermes') {
@@ -112,6 +130,7 @@ export function runLocalAgent(config, request, { signal, timeoutMs = 180000 } =
     const child = spawn(config.command[0], args, { env, cwd: config.cwd, shell: false, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'] });
     let output = '';
     let diagnostics = '';
+    let diagnosticsTruncated = false;
     child.stdout.setEncoding('utf8');
     child.stderr.setEncoding('utf8');
     let bytes = 0;
@@ -139,13 +158,16 @@ export function runLocalAgent(config, request, { signal, timeoutMs = 180000 } =
       output += data.toString();
     });
     // Diagnostics may contain credentials or tool output; never forward them to Oomi.
-    child.stderr.on('data', (data) => { diagnostics = (diagnostics + data).slice(-8192); });
+    child.stderr.on('data', (data) => { diagnosticsTruncated ||= diagnostics.length + data.length > 8192; diagnostics = (diagnostics + data).slice(-8192); });
     child.stdin.on('error', () => {});
     child.on('error', (err) => { error = new Error(`Could not start ${config.runtime} agent (${err.code || 'spawn failed'}). Check the executable and working directory.`); });
     child.on('close', (code) => {
       clearTimeout(timer); clearTimeout(killer); signal?.removeEventListener('abort', abort);
       if (error) return reject(error);
-      if (code !== 0) return reject(new Error(`Agent exited with code ${code}. Check local runtime credentials and logs.`));
+      if (code !== 0) {
+        const reason = config.runtime === 'hermes' && code === 1 && !diagnosticsTruncated && !output.trim() && diagnostics.match(/^hermes-refusal-reason:\s*([A-Z_]+)(?:\r?\n|$)/)?.[1];
+        return reject(hermesRefusal(reason) || new Error(`Agent exited with code ${code}. Check local runtime credentials and logs.`));
+      }
       try {
         const result = config.runtime === 'hermes'
           ? { text: output, sessionId: diagnostics.match(/(?:^|\n)session_id:\s*([A-Za-z0-9_-]+)\s*(?:\n|$)/)?.[1] }
@@ -165,6 +187,7 @@ export class LocalAgentRuntime {
     this.onHealth = onHealth;
     this.queue = Promise.resolve();
     this.active = new Map();
+    this.deliveries = 0;
   }
   file(sessionKey) { return path.join(this.directory, 'conversations', createHash('sha256').update(sessionKey).digest('hex') + '.json'); }
   history(sessionKey) { return readJson(this.file(sessionKey), { messages: [], receipts: {} }); }
@@ -188,7 +211,7 @@ export class LocalAgentRuntime {
       if (previous?.message !== undefined && previous.message !== message) throw new Error('Idempotency key was reused for a different message.');
       if (previous?.result) return previous.result;
       // A crash after a side effect cannot safely be retried by running the agent again.
-      if (previous && !retryInterrupted) throw new Error('The previous turn was interrupted. Check the agent before sending a new message.');
+      if (previous && previous.status !== 'not_started' && !retryInterrupted) throw new Error('The previous turn was interrupted. Check the agent before sending a new message.');
       if (controller.signal.aborted) throw new Error('Agent turn cancelled.');
       state.receipts[receiptKey] = { message, status: 'running' };
       writePrivateJson(this.file(sessionKey), state);
@@ -202,7 +225,14 @@ export class LocalAgentRuntime {
         writePrivateJson(this.file(sessionKey), state);
         this.onHealth({ runtimeReady: true, lastReplyAt: new Date().toISOString(), lastErrorMessage: '' });
         return result;
-      } catch (err) { this.onHealth({ runtimeReady: false, status: 'degraded', lastErrorMessage: err.message }); throw err; }
+      } catch (err) {
+        if (err.notStarted === true) {
+          state.receipts[receiptKey] = { message, status: 'not_started' };
+          writePrivateJson(this.file(sessionKey), state);
+        }
+        this.onHealth({ runtimeReady: err.runtimeReady === true, ...(err.runtimeReady === true ? {} : { status: 'degraded' }), lastErrorMessage: err.message });
+        throw err;
+      }
       finally { if (scratch) fs.rmSync(scratch.directory, { recursive: true, force: true }); }
     });
     this.queue = promise.catch(() => {});
@@ -251,7 +281,7 @@ class LocalAgentSocket extends EventEmitter {
     this.runtime.turn({ ...params, idempotencyKey: runId }).then((result) => {
       this.frame({ type: 'event', event: 'chat', payload: { runId, sessionKey: params.sessionKey, state: 'final', message: { role: 'assistant', content: [{ type: 'text', text: result.text }], timestamp: Date.now() } } });
     }, (err) => {
-      this.frame({ type: 'event', event: 'chat', payload: { runId, sessionKey: params.sessionKey, state: 'error', errorMessage: err.message } });
+      this.frame({ type: 'event', event: 'chat', payload: { runId, sessionKey: params.sessionKey, state: 'error', errorMessage: err.message, ...(typeof err.runtimeReady === 'boolean' ? { runtimeReady: err.runtimeReady } : {}) } });
     });
   }
   close(code = 1000, reason = '') { if (this.readyState === 3) return; this.readyState = 3; this.emit('close', code, reason); }
@@ -269,6 +299,7 @@ export function startChannelWorker(state, runtime) {
     return response.json();
   };
   const poll = async () => {
+    runtime.deliveries++;
     try {
       const { messages = [] } = await post('poll', { limit: 1 });
       for (const message of messages) {
@@ -286,7 +317,7 @@ export function startChannelWorker(state, runtime) {
       }
     } catch (err) {
       runtime.onHealth({ status: 'degraded', lastErrorMessage: err.message });
-    } finally { if (!stopped) timer = setTimeout(poll, 3000); }
+    } finally { runtime.deliveries--; if (!stopped) timer = setTimeout(poll, 3000); }
   };
   timer = setTimeout(poll, 0);
   return () => { stopped = true; clearTimeout(timer); for (const entry of runtime.active.values()) entry.controller.abort(); };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Connect OpenClaw, Hermes, and other local agents to Oomi with verified runtime adapters",
   "bin": {
     "oomi": "bin/oomi-ai.js"
@@ -49,7 +49,7 @@
     "url": "https://github.com/crispcode-io/oomi/issues"
   },
   "scripts": {
-    "check": "node --check bin/oomi-ai.js && node --check lib/bridgeService.js",
+    "check": "node --check bin/oomi-ai.js && node --check lib/bridgeService.js && node --check lib/bridgeMaintenance.js && node --check lib/localAgent.js && node --check lib/hermesGateway.js",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
@@ -77,6 +77,8 @@
     "lib/routines.js",
     "lib/spaces.js",
     "lib/objectives.js",
-    "lib/bridgeService.js"
+    "lib/bridgeService.js",
+    "lib/bridgeMaintenance.js",
+    "lib/hermesGateway.js"
   ]
 }

package/skills/oomi/SKILL.md

@@ -127,9 +127,22 @@ Owner-originated identity changes are a deliberate exception: one notice per ide
 
 The legacy persona-app commands below remain compatibility tools; use Spaces for new agent-composed personal views.
 
+## Updating Oomi safely
+
+When the user asks you to update Oomi, read `oomi instructions` first; it supersedes copied setup/restart recipes. Keep the same connection on the same computer.
+
+1. Run `oomi update --connection NAME` (omit the selector for default OpenClaw). This only checks versions. If already current, report that and stop: do not reinstall or restart "to be sure."
+2. If an update exists, run the returned exact-version npm install command **alone**, through the runtime's normal approval flow. Do not append redirections, status checks or restarts. If installation is denied, fails, or cannot be verified, leave the bridge alone and explain the approval/error. Never disable security checks, retry through another executor, or enable blanket unattended approvals.
+3. After successful installation, check `npm list -g oomi-ai --depth=0` and `oomi update` separately. Only then run `oomi bridge repair --connection NAME`.
+4. A running 0.8.1+ supervised bridge queues its restart until active replies finish and queued phone replies are saved. If the result is `queued`, finish your reply now; do not wait for your own turn to end, poll in a loop, or claim completion. `oomi status --connection NAME --json` subsequently reports maintenance `completed`/`failed` and the running `packageVersion`. Pairing and conversations stay intact.
+
+For packages before 0.8.1 (no `oomi update` command), read the published guide, check `npm list -g oomi-ai --depth=0` and `npm view oomi-ai version` in separate commands. If equal, stop. Otherwise install the exact returned version through normal approvals. The first restart of an older or unsupervised bridge must happen from an independent host terminal/agent session, outside the Oomi conversation it would terminate. New CLI commands refuse to stop their own older host. After that bootstrap, in-chat restarts use the deferred path.
+
+Hermes single-query mode has no interactive approval surface. If its package/security check requires a human, tell the user to approve/run the exact install in an approval-capable host session, then continue there. A blocked install is not a reason to restart. Oomi does not override host permissions. `bridge repair` is also available for an actual connection fault when no package update is needed.
+
 ## Standard Connect Flow
 
-Install or update the local package:
+For a new installation (for an existing installation, use the safe update flow below):
 
 ```bash
 npm install -g oomi-ai@latest
@@ -148,7 +161,9 @@ oomi connect --runtime hermes --name hermes --app-url https://www.oomi.ai
 oomi connect --runtime command --name my-agent --command '["/absolute/path/to/adapter"]' --app-url https://www.oomi.ai
 ```
 
-Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. Hermes uses `chat --quiet --query-file -`, reads the final reply from stdout and the exact `session_id` from stderr, and resumes that ID on subsequent turns.
+Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. With oomi-ai 0.8.2+, an already-open Hermes conversation uses its existing local gateway owner and exact profile/session. Oomi attaches as another client; it never closes desktop, clears history, deletes a session lock, or substitutes a new chat. When no live owner exists, Hermes uses `chat --quiet --query-file -` and resumes the exact returned `session_id` on subsequent turns.
+
+Shared desktop conversations require Hermes's loopback WebSocket gateway, active-session discovery, and durable prompt/reply row IDs. Busy conversations ask you to retry after the current task. If a simultaneous desktop send queues your message without a reply receipt, or the connection drops after sending, check the same Hermes chat before resending. Oomi cannot safely repeat an uncertain action. Human approvals stay in the existing Hermes desktop UI. Shared photo submission is not yet supported; use Hermes desktop for that photo. Older or terminal-only owners without a shared gateway receive an actionable error, never a competing process. The shared owner keeps its existing environment, so use the explicit Oomi `--connection NAME` for account commands.
 
 The command verifies a real local reply, reuses saved credentials or pairs once, starts the bridge, waits for Oomi's subscription, then creates a single-use Auth Link. Failed verification means setup is incomplete: repair the selected runtime, never substitute a different one.
 
@@ -208,7 +223,7 @@ oomi invite --name hermes --app-url https://www.oomi.ai
 
 Do not pair again to refresh an expired Auth Link. Re-running `connect` reuses saved pairing and verification; only the first connection or an explicit `oomi verify` sends a model probe. A different command, profile, or working directory requires a new connection name, so one agent cannot silently replace another. Named connections store private state and logs under `~/.oomi/connections/<name>`; default OpenClaw keeps `~/.openclaw`. Since 0.8.0, `connect` installs a separate automatic-start service for each connection: macOS launchd or Linux systemd user. It restarts an exited worker and starts at the next login/user session. Linux servers can start at boot and remain running after logout when the host administrator enables user lingering (`loginctl enable-linger <user>`); `oomi bridge service status --name hermes` reports whether this is enabled. WSL needs systemd and a running WSL instance; native Windows does not yet have an automatic service installer. A sleeping, powered-off, or disconnected computer remains unavailable.
 
-Run `oomi bridge list` to find saved connection names and their startup protection on this computer. To upgrade an existing connection on **each computer**, install `oomi-ai@latest`, then run `oomi bridge repair --name <existing-name>` (omit the name for default OpenClaw). Repair installs/updates its supervisor, preserves pairing and conversations, and waits for the broker connection. It does not send a model probe or switch agents. Do not copy connection credentials between computers.
+Run `oomi bridge list` to find saved connection names and their startup protection on this computer. To update an existing connection on **each computer**, follow Updating Oomi safely above. Repair preserves pairing and conversations. On a running 0.8.1+ supervised bridge it queues a safe restart and reports pending work; on a stopped bridge it installs/starts supervision and waits for the broker connection. It does not send a model probe or switch agents. Do not copy connection credentials between computers.
 
 Use `oomi bridge service status --name hermes --json` to inspect startup protection. `oomi bridge stop --name hermes` disables automatic startup and stops only that connection; `oomi bridge start --name hermes` enables it again. `oomi bridge service uninstall --name hermes` removes startup management without deleting saved state. The legacy `oomi openclaw bridge service` command remains supported.
 

package/skills/oomi/agent_instructions.md

@@ -101,9 +101,22 @@ Owner-originated identity changes are a deliberate exception: one notice per ide
 
 The legacy persona-app commands below remain compatibility tools; use Spaces for new agent-composed personal views.
 
+## Updating Oomi safely
+
+When the user asks you to update Oomi, read `oomi instructions` first; it supersedes copied setup/restart recipes. Keep the same connection on the same computer.
+
+1. Run `oomi update --connection NAME` (omit the selector for default OpenClaw). This only checks versions. If already current, report that and stop: do not reinstall or restart "to be sure."
+2. If an update exists, run the returned exact-version npm install command **alone**, through the runtime's normal approval flow. Do not append redirections, status checks or restarts. If installation is denied, fails, or cannot be verified, leave the bridge alone and explain the approval/error. Never disable security checks, retry through another executor, or enable blanket unattended approvals.
+3. After successful installation, check `npm list -g oomi-ai --depth=0` and `oomi update` separately. Only then run `oomi bridge repair --connection NAME`.
+4. A running 0.8.1+ supervised bridge queues its restart until active replies finish and queued phone replies are saved. If the result is `queued`, finish your reply now; do not wait for your own turn to end, poll in a loop, or claim completion. `oomi status --connection NAME --json` subsequently reports maintenance `completed`/`failed` and the running `packageVersion`. Pairing and conversations stay intact.
+
+For packages before 0.8.1 (no `oomi update` command), read the published guide, check `npm list -g oomi-ai --depth=0` and `npm view oomi-ai version` in separate commands. If equal, stop. Otherwise install the exact returned version through normal approvals. The first restart of an older or unsupervised bridge must happen from an independent host terminal/agent session, outside the Oomi conversation it would terminate. New CLI commands refuse to stop their own older host. After that bootstrap, in-chat restarts use the deferred path.
+
+Hermes single-query mode has no interactive approval surface. If its package/security check requires a human, tell the user to approve/run the exact install in an approval-capable host session, then continue there. A blocked install is not a reason to restart. Oomi does not override host permissions. `bridge repair` is also available for an actual connection fault when no package update is needed.
+
 ## Standard Connect Flow
 
-Install or update the local package:
+For a new installation (for an existing installation, use the safe update flow below):
 
 ```bash
 npm install -g oomi-ai@latest
@@ -122,7 +135,9 @@ oomi connect --runtime hermes --name hermes --app-url https://www.oomi.ai
 oomi connect --runtime command --name my-agent --command '["/absolute/path/to/adapter"]' --app-url https://www.oomi.ai
 ```
 
-Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. Hermes uses `chat --quiet --query-file -`, reads the final reply from stdout and the exact `session_id` from stderr, and resumes that ID on subsequent turns.
+Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. With oomi-ai 0.8.2+, an already-open Hermes conversation uses its existing local gateway owner and exact profile/session. Oomi attaches as another client; it never closes desktop, clears history, deletes a session lock, or substitutes a new chat. When no live owner exists, Hermes uses `chat --quiet --query-file -` and resumes the exact returned `session_id` on subsequent turns.
+
+Shared desktop conversations require Hermes's loopback WebSocket gateway, active-session discovery, and durable prompt/reply row IDs. Busy conversations ask you to retry after the current task. If a simultaneous desktop send queues your message without a reply receipt, or the connection drops after sending, check the same Hermes chat before resending. Oomi cannot safely repeat an uncertain action. Human approvals stay in the existing Hermes desktop UI. Shared photo submission is not yet supported; use Hermes desktop for that photo. Older or terminal-only owners without a shared gateway receive an actionable error, never a competing process. The shared owner keeps its existing environment, so use the explicit Oomi `--connection NAME` for account commands.
 
 The first connection verifies a real local reply (reconnects reuse verification), reuses saved credentials or pairs once, starts the bridge, waits for Oomi's subscription, then creates a single-use Auth Link. Failed verification means setup is incomplete: repair the selected runtime, never substitute a different one.
 
@@ -182,7 +197,7 @@ oomi invite --name hermes --app-url https://www.oomi.ai
 
 Do not pair again to refresh an expired Auth Link. Re-running `connect` reuses saved pairing and verification; only the first connection or an explicit `oomi verify` sends a model probe. A different command, profile, or working directory requires a new connection name, so one agent cannot silently replace another. Named connections store private state and logs under `~/.oomi/connections/<name>`; default OpenClaw keeps `~/.openclaw`. Since 0.8.0, `connect` installs a separate automatic-start service for each connection: macOS launchd or Linux systemd user. It restarts an exited worker and starts at the next login/user session. Linux servers can start at boot and remain running after logout when the host administrator enables user lingering (`loginctl enable-linger <user>`); `oomi bridge service status --name hermes` reports whether this is enabled. WSL needs systemd and a running WSL instance; native Windows does not yet have an automatic service installer. A sleeping, powered-off, or disconnected computer remains unavailable.
 
-Run `oomi bridge list` to find saved connection names and their startup protection on this computer. To upgrade an existing connection on **each computer**, install `oomi-ai@latest`, then run `oomi bridge repair --name <existing-name>` (omit the name for default OpenClaw). Repair installs/updates its supervisor, preserves pairing and conversations, and waits for the broker connection. It does not send a model probe or switch agents. Do not copy connection credentials between computers.
+Run `oomi bridge list` to find saved connection names and their startup protection on this computer. To update an existing connection on **each computer**, follow Updating Oomi safely above. Repair preserves pairing and conversations. On a running 0.8.1+ supervised bridge it queues a safe restart and reports pending work; on a stopped bridge it installs/starts supervision and waits for the broker connection. It does not send a model probe or switch agents. Do not copy connection credentials between computers.
 
 Use `oomi bridge service status --name hermes --json` to inspect startup protection. `oomi bridge stop --name hermes` disables automatic startup and stops only that connection; `oomi bridge start --name hermes` enables it again. `oomi bridge service uninstall --name hermes` removes startup management without deleting saved state. The legacy `oomi openclaw bridge service` command remains supported.