oomi-ai 0.8.0 → 0.8.1

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
@@ -129,7 +142,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 +346,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
@@ -182,7 +195,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,6 +3351,12 @@ 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') {
@@ -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/localAgent.js

@@ -165,6 +165,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: {} }); }
@@ -269,6 +270,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 +288,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.1",
   "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",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
@@ -77,6 +77,7 @@
     "lib/routines.js",
     "lib/spaces.js",
     "lib/objectives.js",
-    "lib/bridgeService.js"
+    "lib/bridgeService.js",
+    "lib/bridgeMaintenance.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
@@ -208,7 +221,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
@@ -182,7 +195,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.