oomi-ai 0.7.2 → 0.8.1

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

@@ -0,0 +1,180 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const xml = (value) => String(value).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' }[c]));
+// systemd performs specifier expansion even inside quotes; ExecStart also expands $.
+const unitString = (value, exec = false) => '"' + String(value).replace(/%/g, '%%').replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t').replace(/\$/g, exec ? '$$$$' : '$$') + '"';
+
+// These path directives consume the full value, without removing shell-style quotes.
+function unitPath(value) {
+  if (/[\\\r\n\0]/.test(value)) throw new Error('Linux service paths cannot contain backslashes or control characters.');
+  return String(value).replace(/%/g, '%%');
+}
+
+export function bridgeServiceConfig({ name = '', stateDirectory, logPath, scriptPath, nodePath = process.execPath,
+  platform = process.platform, home = os.homedir(), env = process.env, uid = process.getuid?.() } = {}) {
+  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 = { 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);
+  if (env.OPENCLAW_WORKSPACE) environment.OPENCLAW_WORKSPACE = path.resolve(env.OPENCLAW_WORKSPACE);
+  const args = [nodePath, scriptPath, ...(name ? ['bridge', 'start', '--name', name] : ['openclaw', 'bridge', 'start']), '--service-managed'];
+  return { name, label, platform, uid, directory, logPath, environment, args,
+    file: platform === 'darwin' ? path.join(home, 'Library', 'LaunchAgents', `${label}.plist`)
+      : path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'systemd', 'user', `${label}.service`),
+    target: platform === 'darwin' ? `gui/${uid}/${label}` : `${label}.service` };
+}
+
+export function renderLaunchAgent(config) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>${xml(config.label)}</string>
+<key>ProgramArguments</key><array>${config.args.map((arg) => `<string>${xml(arg)}</string>`).join('')}</array>
+<key>WorkingDirectory</key><string>${xml(config.directory)}</string>
+<key>RunAtLoad</key><true/>
+<key>KeepAlive</key><true/>
+<key>ThrottleInterval</key><integer>10</integer>
+<key>EnvironmentVariables</key><dict>${Object.entries(config.environment).map(([k, v]) => `<key>${xml(k)}</key><string>${xml(v)}</string>`).join('')}</dict>
+<key>StandardOutPath</key><string>${xml(config.logPath)}</string>
+<key>StandardErrorPath</key><string>${xml(config.logPath)}</string>
+</dict></plist>
+`;
+}
+
+export function renderSystemdUnit(config) {
+  return `[Unit]
+Description=Oomi bridge ${config.name || 'default'}
+StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+WorkingDirectory=${unitPath(config.directory)}
+ExecStart=${config.args.map((arg) => unitString(arg, true)).join(' ')}
+${Object.entries(config.environment).map(([key, value]) => `Environment=${unitString(`${key}=${value}`)}`).join('\n')}
+Restart=always
+RestartSec=10
+TimeoutStopSec=15
+UMask=0077
+StandardOutput=append:${unitPath(config.logPath)}
+StandardError=append:${unitPath(config.logPath)}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+// No credentials, runtime commands or arbitrary environment are copied into service files.
+// Use injectable process execution so lifecycle failures can be tested without real user services.
+export function createBridgeService(config, { run = spawnSync } = {}) {
+  const mac = config.platform === 'darwin';
+  const supported = mac || config.platform === 'linux';
+  const command = mac ? 'launchctl' : 'systemctl';
+  function invoke(args, allowFailure = false) {
+    const result = run(command, mac ? args : ['--user', ...args], { encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'pipe'] });
+    const code = Number.isInteger(result.status) ? result.status : 1;
+    const stdout = String(result.stdout || '').trim();
+    if (code && !allowFailure) throw new Error(`${command} ${args[0]} failed: ${String(result.stderr || result.error?.message || stdout || 'service manager unavailable').trim()}`);
+    return { code, stdout };
+  }
+  function availability() {
+    if (!supported) return { available: false, reason: 'Automatic startup supports macOS launchd and Linux systemd (including WSL with systemd). Use --no-service only with your own supervisor.' };
+    const result = invoke(mac ? ['print', `gui/${config.uid}`] : ['show-environment'], true);
+    return { available: result.code === 0, reason: result.code ? (mac ? 'A macOS login session is required for the Oomi service.' : 'The systemd user manager is unavailable. Enable systemd/user services, or use --no-service with your own supervisor.') : null };
+  }
+  function assertAvailable() { const result = availability(); if (!result.available) throw new Error(result.reason); }
+  function status() {
+    const available = availability();
+    const base = { manager: mac ? 'launchd' : config.platform === 'linux' ? 'systemd' : null,
+      connection: config.name || null, target: config.target, file: config.file, installed: supported && fs.existsSync(config.file),
+      ...available, loaded: false, running: false, enabled: false, pid: null, startsAt: mac ? 'login' : 'user-session' };
+    if (!available.available) return base;
+    if (mac) {
+      const printed = invoke(['print', config.target], true);
+      const disabled = invoke(['print-disabled', `gui/${config.uid}`], true);
+      const escapedLabel = config.label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const explicitlyDisabled = new RegExp(`"${escapedLabel}"\\s*=>\\s*(?:true|disabled)\\b`).test(disabled.stdout);
+      const pid = Number(printed.stdout.match(/\bpid\s*=\s*(\d+)/)?.[1]) || null;
+      return { ...base, loaded: printed.code === 0, running: Boolean(pid), pid,
+        enabled: base.installed && disabled.code === 0 ? !explicitlyDisabled : null };
+    }
+    const printed = invoke(['show', config.target, '--property=LoadState,ActiveState,MainPID,UnitFileState'], true);
+    const properties = Object.fromEntries(printed.stdout.split('\n').filter((line) => line.includes('=')).map((line) => { const i = line.indexOf('='); return [line.slice(0, i), line.slice(i + 1)]; }));
+    const linger = run('loginctl', ['show-user', String(config.uid), '--property=Linger', '--value'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+    const persistsWithoutLogin = linger.status === 0 && String(linger.stdout).trim() === 'yes';
+    return { ...base, loaded: properties.LoadState === 'loaded', running: properties.ActiveState === 'active',
+      pid: Number(properties.MainPID) || null, enabled: properties.UnitFileState === 'enabled',
+      startsAt: persistsWithoutLogin ? 'boot' : 'user-session', persistsWithoutLogin };
+  }
+  function assertOwnership() {
+    // Prevent a custom state root with the same name from taking over another connection's service.
+    if (fs.existsSync(config.file)) {
+      const existing = fs.readFileSync(config.file, 'utf8');
+      const matches = mac ? new RegExp(`<key>WorkingDirectory</key>\\s*<string>${xml(config.directory).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}</string>`).test(existing)
+        : existing.includes(`WorkingDirectory=${unitPath(config.directory)}\n`);
+      if (!matches) throw new Error(`Service ${config.target} belongs to a different state directory. Use a different connection name.`);
+    }
+  }
+  function preflight() {
+    assertAvailable();
+    assertOwnership();
+    if (config.args[1].split(path.sep).includes('_npx')) throw new Error('Install oomi-ai globally before installing automatic startup; an npx cache is temporary.');
+    // Validate paths before pairing or stopping an already working connection.
+    if (mac) renderLaunchAgent(config); else renderSystemdUnit(config);
+  }
+  function writeDefinition() {
+    preflight();
+    fs.mkdirSync(path.dirname(config.file), { recursive: true });
+    fs.mkdirSync(config.directory, { recursive: true });
+    fs.mkdirSync(path.dirname(config.logPath), { recursive: true });
+    const content = mac ? renderLaunchAgent(config) : renderSystemdUnit(config);
+    fs.writeFileSync(config.file, content, { mode: 0o600 });
+    fs.chmodSync(config.file, 0o600);
+    if (!mac) invoke(['daemon-reload']);
+  }
+  function stop() {
+    assertAvailable();
+    assertOwnership();
+    if (mac) {
+      invoke(['disable', config.target]);
+      const current = invoke(['print', config.target], true);
+      if (!current.code) invoke(['bootout', config.target]);
+    } else if (fs.existsSync(config.file)) invoke(['disable', '--now', config.target]);
+  }
+  function start({ rewrite = false } = {}) {
+    assertAvailable();
+    assertOwnership();
+    if (!fs.existsSync(config.file)) throw new Error('Bridge service is not installed. Run oomi bridge repair for this connection.');
+    const current = status();
+    if (rewrite) { writeDefinition(); stop(); }
+    if (mac) {
+      invoke(['enable', config.target]);
+      if (!current.loaded || rewrite) invoke(['bootstrap', `gui/${config.uid}`, config.file]);
+      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();
+    stop();
+    if (!noStart) start();
+  }
+  function uninstall() {
+    stop();
+    if (fs.existsSync(config.file)) fs.unlinkSync(config.file);
+    if (!mac) invoke(['daemon-reload']);
+  }
+  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/lib/objectives.js

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import { routineRequest } from './routines.js';
+
+export async function handleObjectivesCommand(state, action = 'list', flags = {}, positionals = [], request = routineRequest) {
+  if (!['list', 'show', 'history', 'create', 'update', 'respond'].includes(action)) throw new Error('Use objectives list, show, history, create, update, or respond.');
+  let route = 'objectives', method = 'GET', body;
+  const id = positionals[0] || flags.id;
+  if (!['list', 'create'].includes(action)) {
+    if (!/^obj_[a-f0-9]{24}$/.test(id || '')) throw new Error('Use the objective ID returned by Oomi.');
+    route += `/${id}`;
+  }
+  if (action === 'history') {
+    if (flags.before && !/^\d{4}-\d{2}-\d{2}$/.test(flags.before)) throw new Error('Use --before YYYY-MM-DD.');
+    route += `/history${flags.before ? `?before=${flags.before}` : ''}`;
+  }
+  if (['create', 'update', 'respond'].includes(action)) {
+    if (typeof flags.file !== 'string' || fs.statSync(flags.file).size > 32768) throw new Error('Use a goal JSON file under 32 KiB.');
+    body = JSON.parse(fs.readFileSync(flags.file, 'utf8'));
+    if (!body || typeof body !== 'object' || Array.isArray(body)) throw new Error('Use a JSON object.');
+    if (flags['request-id']) body.idempotencyKey = flags['request-id'];
+    if (flags.revision !== undefined) body.expectedRevision = Number(flags.revision);
+    if (flags['source-message']) body.sourceMessageId = flags['source-message'];
+    if (typeof body.idempotencyKey !== 'string' || body.idempotencyKey.length < 8) throw new Error('Include a stable idempotencyKey; retry only the identical request.');
+    if (action !== 'create' && !Number.isInteger(body.expectedRevision)) throw new Error('Read the goal and provide expectedRevision.');
+    if (action === 'respond') {
+      if (!body.periodKey || !Number.isInteger(body.expectedPeriodRevision)) throw new Error('Read the goal and include periodKey and expectedPeriodRevision.');
+      route += '/responses';
+    }
+    method = action === 'update' ? 'PATCH' : 'POST';
+  }
+  const result = await request(state, route, { method, body });
+  console.log(JSON.stringify(result, null, 2));
+  return result;
+}

package/lib/personaApiClient.js

@@ -147,7 +147,7 @@ export function createPersonaApiClient({
 
     getHealthContext(options = {}) {
       const query = new URLSearchParams();
-      for (const key of ['window', 'date', 'from', 'to', 'timezone', 'shape', 'groupBy', 'cursor']) {
+      for (const key of ['window', 'date', 'from', 'to', 'timezone', 'shape', 'groupBy', 'cursor', 'provider']) {
         if (typeof options[key] === 'string' && options[key].trim()) query.set(key, options[key].trim());
       }
       return getJson({

package/lib/routines.js

@@ -5,7 +5,7 @@ import { readJson, writePrivateJson } from './localAgent.js';
 export async function routineRequest(state, route, { method = 'GET', body, fetchImpl = fetch } = {}) {
   if (!state.deviceToken || !state.brokerHttp) throw new Error('Connect this agent to Oomi first.');
   const response = await fetchImpl(`${state.brokerHttp.replace(/\/$/, '')}/v1/${route}`, {
-    method, headers: { Authorization: `Bearer ${state.deviceToken}`, 'Content-Type': 'application/json', 'X-Oomi-Event-Delivery': 'quiet-v1' },
+    method, headers: { Authorization: `Bearer ${state.deviceToken}`, 'Content-Type': 'application/json', 'X-Oomi-Event-Delivery': 'quiet-v1', 'X-Oomi-Space-Schema': 'space.v3' },
     ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(15000),
   });
   const result = await response.json().catch(() => ({}));

package/lib/spaces.js

@@ -9,17 +9,18 @@ export async function handleSpacesCommand(state, action = 'list', flags = {}, po
     body = JSON.parse(fs.readFileSync(flags.file, 'utf8'));
     if (!body || typeof body !== 'object' || Array.isArray(body)) throw new Error('Use a JSON object.');
   }
-  if (!['list', 'catalog', 'create', 'show', 'update', 'archive', 'unarchive', 'revisions', 'restore'].includes(action)) throw new Error('Use spaces list, catalog, create, show, update, archive, unarchive, revisions, or restore.');
+  if (!['list', 'catalog', 'create', 'show', 'update', 'archive', 'unarchive', 'revisions', 'restore', 'upgrade'].includes(action)) throw new Error('Use spaces list, catalog, create, show, update, archive, unarchive, revisions, restore, or upgrade.');
   if (action === 'catalog') route += '/catalog';
   if (action === 'list' && flags.archived) route += '?archived=true';
   if (!['list', 'catalog', 'create'].includes(action)) {
     if (!/^spc_[a-f0-9]{24}$/.test(id || '')) throw new Error('Provide the Space ID returned by Oomi.');
     route += `/${id}`;
   }
-  if (['revisions', 'restore'].includes(action)) route += `/${action}`;
-  if (['create', 'update', 'archive', 'unarchive', 'restore'].includes(action)) {
-    method = ['create', 'restore'].includes(action) ? 'POST' : 'PATCH';
+  if (['revisions', 'restore', 'upgrade'].includes(action)) route += `/${action}`;
+  if (['create', 'update', 'archive', 'unarchive', 'restore', 'upgrade'].includes(action)) {
+    method = ['create', 'restore', 'upgrade'].includes(action) ? 'POST' : 'PATCH';
     body ||= {};
+    if (flags['schema-version']) body.schemaVersion = flags['schema-version'];
     if (flags.revision !== undefined) body.expectedRevision = Number(flags.revision);
     if (flags['request-id']) body.idempotencyKey = flags['request-id'];
     if (action === 'archive' || action === 'unarchive') body.archived = action === 'archive';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.7.2",
+  "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",
+    "check": "node --check bin/oomi-ai.js && node --check lib/bridgeService.js && node --check lib/bridgeMaintenance.js",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
@@ -75,6 +75,9 @@
     "lib/localAgent.js",
     "lib/agentIdentity.js",
     "lib/routines.js",
-    "lib/spaces.js"
+    "lib/spaces.js",
+    "lib/objectives.js",
+    "lib/bridgeService.js",
+    "lib/bridgeMaintenance.js"
   ]
 }

package/skills/oomi/SKILL.md

@@ -37,14 +37,82 @@ Supported types and binding fields:
 - profile: heightCm, birthDate (YYYY-MM-DD), sex, activityLevel, athleteMode. Ask incrementally only when necessary; do not invent profile facts.
 - routine/streak: routineId returned by the existing routines API. The source remains that routine's real schedule and check-ins. Rendering a component does not activate a routine.
 
-Live source example: `{"id":"steps","type":"chart","title":"Steps this week","dataKey":"steps","source":{"kind":"health","metric":"activity.steps","window":"week","unit":"count"}}`. Health sources use canonical metric names from the catalog and resolve permissioned observations when opened. Body-weight unit may be kg or lb. For the user's shared scale use `source:{kind:"scale",metric:"weight",unit:"lb"}`. The scale shows received capture values; packet stability and measurement time remain unverified. No body-composition values can be inferred from weight alone. Don't present estimates as measurements.
+For connected content, use reusable named `sources` and a component's `sourceRef`. Check the live catalog for supported versions and available providers. Send `schemaVersion:"space.v2"` on creation and every edit/restore/archive to a v2 Space; flag-only commands accept `--schema-version space.v2`. Retain existing definitions when replacing the sources object. References automatically manage subscriptions; they never grant permission.
+
+Example fragment (preserve the person's existing components and targets):
+```json
+{
+  "schemaVersion": "space.v2",
+  "sources": {
+    "weight": {"kind":"observation","metric":"body.mass_kg","providers":["smart_scale","apple_health"],"operation":"latest","window":"month","unit":"lb"},
+    "workouts": {"kind":"workouts","metric":"workout","operation":"count","window":"week","minDurationMinutes":10}
+  },
+  "components": [
+    {"id":"weight","type":"metric","title":"Latest weight","dataKey":"weight","sourceRef":"weight"},
+    {"id":"weightHistory","type":"chart","title":"Weight history","dataKey":"weightHistory","sourceRef":"weight"},
+    {"id":"workouts","type":"metric","title":"Recorded workouts","dataKey":"workouts","sourceRef":"workouts"}
+  ],
+  "bindings": {}
+}
+```
+
+Display windows are day (today), week (rolling seven days), month/year (current calendar periods), or all, with an optional IANA timezone. These are not goal recurrence. Latest weight uses a real reading even outside the chart window. Body weight accepts kg/lb. Apple Health daily averages remain in legacy history; individual readings require a sync from the updated phone, and historical averages cannot recover sample times. Scale time is phone receipt time, not a verified device timestamp. Never infer body composition from weight.
+
+Use observation operation sum for activity totals, average for averages, or count/presence for evidence. Sensor workouts (kind workouts, metric workout) and user-reported Fitness completions (kind fitness, metric completion, optionally filtered by explicit actionIds) remain separate. Never add those counts and claim duplicates were removed. Missing data is unknown, not zero. observedAt and syncedAt distinguish record time from receipt; dataRevision changes do not affect the edit revision. Quiet space.data_changed events need no model wake or acknowledgment.
+
+Legacy inline health and scale sources remain readable. Legacy scale history may contain explicitly shared diagnostic captures, separately labelled and not certified weigh-ins. Use the new observation source for automatic shared readings and selectable chart periods.
 
 Removing a component keeps its binding data and revision history. Use `oomi spaces revisions ID` and `oomi spaces restore ID --file restore.json` with `{expectedRevision,restoreRevision,idempotencyKey}` to restore layout without rolling back saved values. Archive/unarchive is reversible. Spaces never execute scripts, HTML, or agent-provided code; unsupported components require an Oomi renderer update.
 
 Creating a Space does not authorize health access, identity-file backup, push messages, or schedules. For a requested routine, use the existing routine proposal/commit commands and authenticated sourceMessageId or previously granted externalInstruction permission. When the user says to revise and set it, commit all changes together; the resolved review card disappears. Don't make them repeat the instruction in the UI. The primary agent normally coordinates; specialists keep their own assigned Spaces.
 
+### Recurring goals and optional streaks (space.v3)
+
+Use the live catalog to confirm support, then `oomi objectives list` and `oomi objectives show ID` before adding another goal. Goals belong to the account and may be reused across Spaces. Keep the existing `goal` card for numeric milestones; use an `objective` component for a recurring rule. A plain checklist does not reset or create completion history.
+
+Create with `oomi objectives create --file goal.json`. Example shape only; choose dates, calendar, target and source from the user's request rather than creating this example:
+```json
+{
+  "title": "Reading practice",
+  "idempotencyKey": "unique-goal-create-request",
+  "calendar": {"period":"daily","timezone":"America/Chicago","startsOn":"YYYY-MM-DD","weekdays":[1,2,3,4,5]},
+  "definition": {"source":{"kind":"manual","unit":"chapters"},"comparison":"gte","target":1}
+}
+```
+
+Calendars support daily (optionally selected weekdays, 1=Monday), weekly (weekStartsOn defaults to Monday), monthly, and once (endsOn required). Time zone and calendar stay fixed through travel. A different calendar requires a new goal. Targets/rules/pause changes take effect next period, leaving past and current progress intact. A future one-time goal may change before starting; once started, correct its progress or create another goal.
+
+Sources may be manual, an existing routine (`{kind:"routine",routineId:"returned ID",operation:"count"}`), or a supported observation/workouts/fitness configuration without window/timezone. The calendar supplies its evaluation window. Daily weigh-in uses observation/body.mass_kg/presence/target 1; weekly recorded workouts uses workouts/workout/count and the requested target. Fitness is user-reported and remains separate from sensor workouts. Daily activity totals imported in a different time zone are unknown for this goal, not rebinned or invented. Sources need existing permission; creating goals never grants it.
+
+For either/or completion use `{kind:"any",sources:[{kind:"workouts",metric:"workout",operation:"presence"},{kind:"fitness",metric:"completion",operation:"presence"}]}` with comparison `gte` and target `1`. Use 2–5 presence sources (observation, workouts, Fitness, or an existing routine). One period counts once even if several sources match; this does not add workout counts across providers. Nested combinations and manual sources inside this rule are unsupported.
+
+Add components using the returned goal ID, preserving all other components and bindings:
+```json
+{"schemaVersion":"space.v3","expectedRevision":1,"idempotencyKey":"unique-space-update-request","components":[{"id":"practice","type":"objective","title":"Reading practice","dataKey":"practice","objectiveId":"RETURNED_OBJECTIVE_ID"},{"id":"practiceStreak","type":"streak","title":"Practice streak","dataKey":"practiceStreak","objectiveIds":["RETURNED_OBJECTIVE_ID"],"match":"all"}]}
+```
+
+Send space.v3 on every write/restore/archive of a Space containing these references. The CLI supplies the space.v3 read header; older clients show an update message and cannot discard newer definitions. Removing a card preserves the objective and history. Never save resolvedBindings back into bindings.
+
+For requested changes use `oomi objectives update ID --file change.json` with expectedRevision, stable idempotencyKey, and only the changed title/definition/reminderRoutineId. A definition is replaced as a whole: preserve the source/comparison/target/status not being changed. Set definition.status to active/paused. An optional reminderRoutineId links an existing authorized routine, creates no schedule, and automatically suppresses its reminder once the goal is complete. One routine can follow one goal. A routine-backed goal may link that same routine as its reminder, but not a different routine. Automatic reminder completion is excluded from source evidence so it cannot complete its own goal indefinitely. Create/activate any new reminder through the established routine authority flow.
+
+For a person's progress correction use `oomi objectives respond ID --file response.json` with expectedRevision, expectedPeriodRevision, periodKey (all from the latest read), action record/incomplete/skip/reset, and a stable idempotencyKey. Record also requires numeric value; optional note is at most 500 characters. Agent-recorded progress requires sourceMessageId from the authenticated Oomi owner message. The external routine permission does not authorize generic goal responses. Existing routine and Fitness actions still use their own action APIs; goals consume that evidence. Never fabricate completed actions. Corrections persist until reset (return to source data, or clear a manual entry). On uncertain failure retry the identical key/body; after a definite revision conflict read current state and make a new request.
+
+`show` contains the last 31 periods; `oomi objectives history ID [--before YYYY-MM-DD]` pages 100 older periods using nextCursor. Full stored history drives current/best streaks, not the seven visible dots. A streak can use 1–10 goals with identical recurring calendars, matching all or any. Rest, skip and pause add no success and do not break an individual streak; an open period is not missed. Skipping one grouped goal does not hide another missed goal. Missing evidence is unknown; unavailable access hides progress. Late source changes/corrections reconcile earlier periods. Existing routine-only streak cards remain compatible and retain their older history limit; migrate explicitly when requested.
+
+### Upgrade an existing Space without losing its plan
+
+Read the Space and its existing routines first. If the catalog advertises `upgrade`, use `oomi spaces upgrade ID --file upgrade.json` to apply explicit source and goal mappings atomically. Supply `expectedRevision`, a stable `idempotencyKey`, optional named `sources`, optional `sourceBindings:{"EXISTING_COMPONENT_ID":"SOURCE_NAME"}`, and an `objectives` array. Each entry requires a distinct stable `key`, `title`, `calendar`, and `definition` in the usual goal format. Optional fields:
+- `checklistItem:{componentId,itemId}` removes exactly that legacy checklist item.
+- `componentId` chooses the new goal card ID; `replaceComponent:true` explicitly replaces an existing section.
+- `reminderRoutineId` links an existing authorized reminder.
+- `streakComponentIds:["EXISTING_STREAK_ID"]` converts selected streaks to the new goal.
+
+All mappings must succeed or nothing changes. Retry the identical body/key after an uncertain response. A conflict requires a fresh read and new request key. Preserve user targets, notes, profiles, unrelated bindings and source permissions. Existing undated checklist ticks are retained in revision history, never invented as dated completions. Use this only for a requested upgrade; do not infer recurrence or health targets from vague prose. Restore an earlier layout with the existing revision API; created account goals and their history remain available.
+
 ### Health questions without oversized output
 
+The iPhone synchronizes available Apple Health history in durable pages keyed by sample UUID, then tracks additions and explicit deletions. A cursor advances only after Oomi saves the page and its affected daily totals. Interrupted imports resume on foreground or a later health update. Apple does not reveal read denials: an empty query is unknown, not zero or proof of deletion. Provider permissions and Oomi's sharing switch still apply. Physical HealthKit/background-delivery acceptance is separate from simulator and synthetic checks.
+
 For a rolling seven days: `oomi context health --window week --metric steps --json`.
 For a previous calendar week: determine dates in the user's time zone, then `oomi context health --window range --from YYYY-MM-DD --to YYYY-MM-DD --metric steps --json`.
 Use `--metric weight`, `--metric sleep`, or a canonical metric as needed. Preserve coverage, dates, units, missing days, and today's partial count. Don't label a rolling window as a calendar week. For large/raw responses use `--output /absolute/path/new-health.json`; the CLI writes private, complete JSON to a new file and prints a small receipt. Never try to parse a terminal-truncated response as if it were the original JSON. Read existing permitted history before asking the user to sync. Request a phone sync only when current data is needed; don't repeatedly poll an offline phone.
@@ -59,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
@@ -134,11 +215,17 @@ Use the SAME connection name from setup. Omit `--name` for default OpenClaw.
 ```bash
 oomi status --name hermes --json
 oomi verify --name hermes
-oomi bridge restart --name hermes --detach
+oomi bridge repair --name hermes
 oomi invite --name hermes --app-url https://www.oomi.ai
 ```
 
-Do not pair again to refresh an expired Auth Link. Re-running `connect` reuses the saved pairing and verifies the runtime again. 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`. A detached worker requires the computer to remain awake and does not start automatically after reboot. Configure the host's process supervisor when persistence across reboot is needed.
+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 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.
+
+For containers or an existing external supervisor, use `connect --no-service` explicitly, then configure that supervisor to run `oomi bridge start --name <name> --service-managed` in the foreground. Detached mode alone does not provide crash/login recovery. Setup fails with an actionable error when the service manager is unavailable; never claim automatic startup in that case. The phone's Reconnect button reconnects the client; it cannot wake a computer or start a missing host process.
 
 `connected` describes the broker transport. Inspect `runtimeReady`, `verifiedAt`, and `lastReplyAt` separately. A process ID, Auth Link, or broker connection alone does not prove the agent is answering.