mouaif 0.3.0

package/src/push.js

@@ -0,0 +1,315 @@
+'use strict';
+
+// mouaif push notification subsystem
+//
+// Three layers:
+//   1. VAPID key management (auto-generated, stored in SQLite)
+//   2. Push subscription CRUD (per-session)
+//   3. Push sending utility (tagged per-chat for updatable notifications)
+//
+// The ASCII status bar that rides every chat notification lives in
+// src/statusBar.js: it decides the bar's cell count from the receiving
+// device's screen size, notification style, and OS version. This module only
+// stores the device's self-report and resolves it per target at send time.
+
+const webpush = require('web-push');
+const crypto = require('crypto');
+const settings = require('./settings.js');
+const statusBar = require('./statusBar.js');
+
+const SUB_TABLE = 'push_subscriptions';
+const VAPID_TABLE = 'push_vapid';
+const VAPID_SUBJECT = 'mailto:push@mouaif.local';
+
+// Fields a device may report about itself for status-bar sizing. Anything
+// else in the subscribe body is ignored, so a malformed client cannot grow an
+// unbounded blob in the subscription row.
+const PROFILE_MAX_CHARS = 512;
+
+// normalizeStatusBarProfile(value) -> JSON string | null
+//
+// Keep only the known sizing fields and only when they carry a usable value,
+// so the stored profile is small and statusBarJs.statusBarPlan() can trust
+// its types. Returns null when nothing usable was reported, so a rebind can
+// preserve the previously stored profile.
+function normalizeStatusBarProfile(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const out = {};
+  const chars = Number(value.chars);
+  if (Number.isFinite(chars) && chars > 0) out.chars = Math.round(chars);
+  const viewportWidth = Number(value.viewportWidth);
+  if (Number.isFinite(viewportWidth) && viewportWidth > 0) out.viewportWidth = Math.round(viewportWidth);
+  const os = statusBar.normalizeOs(value.os);
+  if (os) out.os = os;
+  const osVersion = Number(value.osVersion);
+  if (Number.isFinite(osVersion) && osVersion > 0) out.osVersion = Math.round(osVersion);
+  const style = String(value.style || '').trim().toLowerCase();
+  if (style === 'collapsed' || style === 'expanded') out.style = style;
+  if (!Object.keys(out).length) return null;
+  const json = JSON.stringify(out);
+  return json.length <= PROFILE_MAX_CHARS ? json : null;
+}
+
+// statusBarFromLegacyChars(value) -> integer | null
+//
+// The original subscribe shape sent a bare character count. Keep honoring it
+// so a client that predates the richer profile still sizes its bar.
+function statusBarFromLegacyChars(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? Math.round(n) : null;
+}
+
+// ---- VAPID keys ---------------------------------------------------------
+
+function vapidSubjectForOrigin(origin) {
+  if (!origin) return VAPID_SUBJECT;
+  try {
+    const parsed = new URL(origin);
+    // web-push accepts mailto: or HTTPS VAPID subjects. Public iOS Web Push
+    // origins are HTTPS, so using the served origin gives Apple a stable,
+    // deployment-specific contact without requiring APNs credentials.
+    if (parsed.protocol === 'https:') return parsed.origin;
+  } catch { /* use the local fallback */ }
+  return VAPID_SUBJECT;
+}
+
+function readVapidKeys() {
+  const db = settings.getDb();
+  const publicKey = db.prepare(`SELECT value FROM ${VAPID_TABLE} WHERE key = 'publicKey'`).pluck().get() || null;
+  const privateKey = db.prepare(`SELECT value FROM ${VAPID_TABLE} WHERE key = 'privateKey'`).pluck().get() || null;
+  return { publicKey, privateKey };
+}
+
+function ensureVapidKeys(origin) {
+  const db = settings.getDb();
+  const existing = readVapidKeys();
+  const subject = vapidSubjectForOrigin(origin);
+  if (existing.publicKey && existing.privateKey) {
+    webpush.setVapidDetails(subject, existing.publicKey, existing.privateKey);
+    return existing.publicKey;
+  }
+  const keys = webpush.generateVAPIDKeys();
+  const now = new Date().toISOString();
+  const save = db.prepare(`INSERT INTO ${VAPID_TABLE} (key, value, created_at) VALUES (?, ?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value, created_at = excluded.created_at`);
+  const saveKeys = db.transaction(() => {
+    save.run('publicKey', keys.publicKey, now);
+    save.run('privateKey', keys.privateKey, now);
+  });
+  saveKeys();
+  webpush.setVapidDetails(subject, keys.publicKey, keys.privateKey);
+  return keys.publicKey;
+}
+
+function getVapidPublicKey() {
+  const db = settings.getDb();
+  return db.prepare(`SELECT value FROM ${VAPID_TABLE} WHERE key = 'publicKey'`).pluck().get() || null;
+}
+
+function getPushConfig(origin) {
+  const publicKey = ensureVapidKeys(origin);
+  const keys = readVapidKeys();
+  return {
+    origin: origin || null,
+    subject: vapidSubjectForOrigin(origin),
+    publicKey,
+    privateKeyConfigured: !!keys.privateKey
+  };
+}
+
+// ---- Subscription CRUD --------------------------------------------------
+
+function ensureTable() {
+  const db = settings.getDb();
+  db.exec(`CREATE TABLE IF NOT EXISTS ${SUB_TABLE} (
+    id         TEXT PRIMARY KEY,
+    session_id TEXT NOT NULL,
+    endpoint   TEXT NOT NULL UNIQUE,
+    p256dh     TEXT NOT NULL,
+    auth       TEXT NOT NULL,
+    origin     TEXT,
+    status_bar INTEGER,
+    status_bar_profile TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  )`);
+  db.exec(`CREATE TABLE IF NOT EXISTS ${VAPID_TABLE} (
+    key        TEXT PRIMARY KEY,
+    value      TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  )`);
+  // Devices subscribed before the status bar became device-sized have no
+  // stored report; they keep the conservative phone plan until the page
+  // rebinds its endpoint (every startup sync re-registers, so this heals).
+  // `status_bar` is the original bare character count; `status_bar_profile`
+  // is the current shape (measured chars, viewport, OS, OS version, style).
+  const cols = db.prepare(`PRAGMA table_info('${SUB_TABLE}')`).all();
+  const names = new Set(cols.map((c) => c.name));
+  if (!names.has('status_bar')) {
+    db.exec(`ALTER TABLE ${SUB_TABLE} ADD COLUMN status_bar INTEGER`);
+  }
+  if (!names.has('status_bar_profile')) {
+    db.exec(`ALTER TABLE ${SUB_TABLE} ADD COLUMN status_bar_profile TEXT`);
+  }
+}
+
+function listSubscriptions(sessionId) {
+if (!sessionId) return [];
+const db = settings.getDb();
+return db.prepare(`SELECT id, endpoint, p256dh, auth, origin, status_bar, status_bar_profile, created_at FROM ${SUB_TABLE} WHERE session_id = ? ORDER BY created_at ASC`).all(sessionId);
+}
+// Every subscription, across sessions — used by the sign-in alert, which
+// must reach the user's other already-signed-in devices. A login mints a
+// brand-new session whose own subscription list is empty until the page
+// rebinds its endpoint, so a per-session send would reach nothing.
+function listAllSubscriptions() {
+const db = settings.getDb();
+return db.prepare(`SELECT id, session_id, endpoint, p256dh, auth, origin, status_bar, status_bar_profile, created_at FROM ${SUB_TABLE} ORDER BY created_at ASC`).all();
+}
+
+
+function addSubscription({ sessionId, endpoint, p256dh, auth, origin, statusBarMaxChars, statusBarProfile }) {
+  const db = settings.getDb();
+  const now = new Date().toISOString();
+  const existing = db.prepare(`SELECT id, created_at, status_bar, status_bar_profile FROM ${SUB_TABLE} WHERE endpoint = ?`).get(endpoint);
+  const id = existing ? existing.id : crypto.randomUUID();
+  // The device reports how it presents notifications (measured body line,
+  // viewport, OS, OS version, style). An absent report (an older page, a curl
+  // client) keeps whatever this device last stored — a stale client must not
+  // reset a good profile, and a rebind is the normal path that refines it.
+  const profileJson = normalizeStatusBarProfile(statusBarProfile)
+    || (existing && existing.status_bar_profile)
+    || null;
+  const legacyChars = statusBarFromLegacyChars(statusBarMaxChars);
+  const statusBarValue = legacyChars != null
+    ? legacyChars
+    : (existing && existing.status_bar) || null;
+  db.prepare(`INSERT INTO ${SUB_TABLE} (id, session_id, endpoint, p256dh, auth, origin, status_bar, status_bar_profile, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(endpoint) DO UPDATE SET
+      session_id = excluded.session_id,
+      p256dh = excluded.p256dh,
+      auth = excluded.auth,
+      origin = excluded.origin,
+      status_bar = excluded.status_bar,
+      status_bar_profile = excluded.status_bar_profile,
+      updated_at = excluded.updated_at`)
+    .run(id, sessionId, endpoint, p256dh, auth, origin || null, statusBarValue, profileJson, existing ? existing.created_at : now, now);
+  return { id, endpoint, origin };
+}
+
+function removeSubscription(endpoint, sessionId) {
+  const db = settings.getDb();
+  const info = sessionId
+    ? db.prepare(`DELETE FROM ${SUB_TABLE} WHERE endpoint = ? AND session_id = ?`).run(endpoint, sessionId)
+    : db.prepare(`DELETE FROM ${SUB_TABLE} WHERE endpoint = ?`).run(endpoint);
+  return info.changes > 0;
+}
+
+function removeAllSubscriptions(sessionId) {
+  const db = settings.getDb();
+  db.prepare(`DELETE FROM ${SUB_TABLE} WHERE session_id = ?`).run(sessionId);
+}
+
+// ---- Push sending -------------------------------------------------------
+
+// sendPush({ ... , body, bodyFor }) — deliver one notification to every
+// target subscription.
+//
+// `body` is the device-independent text; `bodyFor(sub)` is the status-bar
+// escape hatch: a status push passes a function that builds its body from the
+// *subscription's* own device plan, so each device gets a bar sized to its
+// screen, notification style, and OS version (see src/statusBar.js). A push
+// without `bodyFor` sends the same `body` everywhere, which is what
+// authorization and sign-in alerts do.
+function sendPush({ sessionId, subs, title, body, bodyFor, tag, data, chatId, projectDir, actions, requireInteraction }) {
+const targets = Array.isArray(subs) ? subs : (sessionId ? listSubscriptions(sessionId) : []);
+if (!targets.length) return;
+
+
+  const keys = readVapidKeys();
+
+  for (const sub of targets) {
+    let targetBody = body;
+    if (typeof bodyFor === 'function') {
+      try {
+        const resolved = bodyFor(sub);
+        if (typeof resolved === 'string') targetBody = resolved;
+      } catch { /* fall back to the shared body */ }
+    }
+    const payload = JSON.stringify({
+      title: title || 'mouaif',
+      body: targetBody || '',
+      tag: tag || (chatId ? `chat-${chatId}` : undefined),
+      renotify: true,
+      icon: '/icons/icon-192.png',
+      badge: '/icons/favicon-32.png',
+      data: data || { chatId, projectDir, url: chatId && projectDir ? `/#/chat/${chatId}?projectDir=${encodeURIComponent(projectDir)}` : '/' },
+      actions: Array.isArray(actions) && actions.length
+        ? actions
+        : [{ action: 'open', title: 'Open chat' }],
+      requireInteraction: requireInteraction === true
+    });
+
+    const subscription = {
+      endpoint: sub.endpoint,
+      keys: { p256dh: sub.p256dh, auth: sub.auth }
+    };
+    const options = keys.publicKey && keys.privateKey ? {
+      vapidDetails: {
+        subject: vapidSubjectForOrigin(sub.origin),
+        publicKey: keys.publicKey,
+        privateKey: keys.privateKey
+      }
+    } : undefined;
+    webpush.sendNotification(subscription, payload, options).catch((err) => {
+      // 410 Gone / 404 Not Found means the subscription is dead
+      if (err && (err.statusCode === 410 || err.statusCode === 404)) {
+        removeSubscription(sub.endpoint);
+      }
+    });
+  }
+}
+
+// sendPushToSession — send a push notification to a specific session.
+// Called from handleChatStream for attention, completion, and error events.
+function sendPushToSession(sessionId, { title, body, bodyFor, chatId, projectDir, tag, data, actions, requireInteraction }) {
+sendPush({ sessionId, title, body, bodyFor, tag, chatId, projectDir, data, actions, requireInteraction });
+}
+// sendPushToAll — send to every subscribed endpoint regardless of session.
+// Used by the sign-in alert, which must reach the user's other devices even
+// though the login created a brand-new session.
+function sendPushToAll({ title, body, bodyFor, chatId, projectDir, tag, data, actions, requireInteraction }) {
+sendPush({ subs: listAllSubscriptions(), title, body, bodyFor, tag, chatId, projectDir, data, actions, requireInteraction });
+}
+
+
+// ---- Session ID helpers -------------------------------------------------
+
+// Derive a stable session id from the session token. One-way hash so the
+// token itself is never stored alongside subscriptions.
+function sessionIdFromToken(token) {
+  if (!token) return null;
+  return crypto.createHash('sha256').update('push:' + token).digest('hex').slice(0, 16);
+}
+
+module.exports = {
+  ensureTable,
+  ensureVapidKeys,
+  getVapidPublicKey,
+  getPushConfig,
+  vapidSubjectForOrigin,
+  normalizeStatusBarProfile,
+  // Status-bar surface re-exported so senders have one import for "build a
+  // status body": `push.statusBar` is src/statusBar.js.
+  statusBar,
+  listSubscriptions,
+listAllSubscriptions,
+addSubscription,
+removeSubscription,
+removeAllSubscriptions,
+sendPush,
+sendPushToSession,
+sendPushToAll,
+sessionIdFromToken
+};

package/src/qr.js

@@ -0,0 +1,192 @@
+'use strict';
+
+// Small dependency-free QR encoder for setup URLs. Byte mode, EC level L,
+// versions 1–10 (enough for normal mouaif origins and setup codes).
+
+const BLOCKS_L = [
+  null,
+  [[1, 26, 19]], [[1, 44, 34]], [[1, 70, 55]], [[1, 100, 80]],
+  [[1, 134, 108]], [[2, 86, 68]], [[2, 98, 78]], [[2, 121, 97]],
+  [[2, 146, 116]], [[2, 86, 68], [2, 87, 69]]
+];
+const ALIGN = [null, [], [6, 18], [6, 22], [6, 26], [6, 30], [6, 34], [6, 22, 38], [6, 24, 42], [6, 26, 46], [6, 28, 50]];
+const EXP = new Array(512);
+const LOG = new Array(256);
+let value = 1;
+for (let i = 0; i < 255; i++) { EXP[i] = value; LOG[value] = i; value <<= 1; if (value & 0x100) value ^= 0x11d; }
+for (let i = 255; i < 512; i++) EXP[i] = EXP[i - 255];
+
+function append(bits, value, length) {
+  for (let i = length - 1; i >= 0; i--) bits.push((value >>> i) & 1);
+}
+
+function multiplyPoly(a, b) {
+  const out = new Array(a.length + b.length - 1).fill(0);
+  for (let i = 0; i < a.length; i++) for (let j = 0; j < b.length; j++) {
+    if (a[i] && b[j]) out[i + j] ^= EXP[LOG[a[i]] + LOG[b[j]]];
+  }
+  return out;
+}
+
+function errorCodewords(data, count) {
+  let generator = [1];
+  for (let i = 0; i < count; i++) generator = multiplyPoly(generator, [1, EXP[i]]);
+  const work = data.concat(new Array(count).fill(0));
+  for (let i = 0; i < data.length; i++) {
+    const factor = work[i];
+    if (!factor) continue;
+    const log = LOG[factor];
+    for (let j = 0; j < generator.length; j++) if (generator[j]) work[i + j] ^= EXP[LOG[generator[j]] + log];
+  }
+  return work.slice(data.length);
+}
+
+function blocksFor(version) {
+  const out = [];
+  for (const [count, total, data] of BLOCKS_L[version]) for (let i = 0; i < count; i++) out.push({ total, data });
+  return out;
+}
+
+function codewords(text, version) {
+  const bytes = Buffer.from(String(text), 'utf8');
+  const blocks = blocksFor(version);
+  const dataCount = blocks.reduce((sum, block) => sum + block.data, 0);
+  const bits = [];
+  append(bits, 4, 4); // byte mode
+  append(bits, bytes.length, version < 10 ? 8 : 16);
+  for (const byte of bytes) append(bits, byte, 8);
+  if (bits.length + 4 <= dataCount * 8) append(bits, 0, 4);
+  while (bits.length % 8) bits.push(0);
+  const data = [];
+  for (let i = 0; i < bits.length; i += 8) {
+    let byte = 0;
+    for (let j = 0; j < 8; j++) byte = (byte << 1) | bits[i + j];
+    data.push(byte);
+  }
+  for (let pad = 0; data.length < dataCount; pad++) data.push(pad % 2 ? 0x11 : 0xec);
+  const chunks = [];
+  const errors = [];
+  let offset = 0;
+  for (const block of blocks) {
+    const chunk = data.slice(offset, offset + block.data);
+    offset += block.data;
+    chunks.push(chunk);
+    errors.push(errorCodewords(chunk, block.total - block.data));
+  }
+  const out = [];
+  const maxData = Math.max(...chunks.map((chunk) => chunk.length));
+  const maxError = Math.max(...errors.map((chunk) => chunk.length));
+  for (let i = 0; i < maxData; i++) for (const chunk of chunks) if (i < chunk.length) out.push(chunk[i]);
+  for (let i = 0; i < maxError; i++) for (const chunk of errors) if (i < chunk.length) out.push(chunk[i]);
+  return out;
+}
+
+function bch(value, polynomial) {
+  let shifted = value;
+  const degree = (number) => 31 - Math.clz32(number);
+  while (degree(shifted) >= degree(polynomial)) shifted ^= polynomial << (degree(shifted) - degree(polynomial));
+  return shifted;
+}
+
+function finder(matrix, row, col) {
+  const size = matrix.length;
+  for (let r = -1; r <= 7; r++) for (let c = -1; c <= 7; c++) {
+    if (row + r < 0 || row + r >= size || col + c < 0 || col + c >= size) continue;
+    matrix[row + r][col + c] = r >= 0 && r <= 6 && c >= 0 && c <= 6 && (r === 0 || r === 6 || c === 0 || c === 6 || (r >= 2 && r <= 4 && c >= 2 && c <= 4));
+  }
+}
+
+function makeMatrix(text) {
+  const bytes = Buffer.from(String(text), 'utf8');
+  let version = 1;
+  while (version <= 10) {
+    const dataCount = blocksFor(version).reduce((sum, block) => sum + block.data, 0);
+    const lengthBits = version < 10 ? 8 : 16;
+    if (4 + lengthBits + bytes.length * 8 <= dataCount * 8) break;
+    version++;
+  }
+  if (version > 10) throw new Error('QR content is too long');
+  const size = version * 4 + 17;
+  const matrix = Array.from({ length: size }, () => Array(size).fill(null));
+  finder(matrix, 0, 0); finder(matrix, size - 7, 0); finder(matrix, 0, size - 7);
+  for (let i = 8; i < size - 8; i++) {
+    if (matrix[i][6] === null) matrix[i][6] = i % 2 === 0;
+    if (matrix[6][i] === null) matrix[6][i] = i % 2 === 0;
+  }
+  for (const row of ALIGN[version]) for (const col of ALIGN[version]) {
+    if (matrix[row][col] !== null) continue;
+    for (let r = -2; r <= 2; r++) for (let c = -2; c <= 2; c++) matrix[row + r][col + c] = Math.max(Math.abs(r), Math.abs(c)) !== 1;
+  }
+  if (version >= 7) {
+    const bits = (version << 12) | bch(version << 12, 0x1f25);
+    for (let i = 0; i < 18; i++) {
+      const bit = ((bits >> i) & 1) === 1;
+      matrix[Math.floor(i / 3)][i % 3 + size - 11] = bit;
+      matrix[i % 3 + size - 11][Math.floor(i / 3)] = bit;
+    }
+  }
+  // Error correction L has format bits 01. Use mask pattern 0.
+  const format = ((1 << 3) | 0) << 10;
+  const formatBits = (format | bch(format, 0x537)) ^ 0x5412;
+  for (let i = 0; i < 15; i++) {
+    const bit = ((formatBits >> i) & 1) === 1;
+    if (i < 6) matrix[i][8] = bit;
+    else if (i < 8) matrix[i + 1][8] = bit;
+    else matrix[size - 15 + i][8] = bit;
+    if (i < 8) matrix[8][size - i - 1] = bit;
+    else if (i === 8) matrix[8][7] = bit;
+    else matrix[8][15 - i - 1] = bit;
+  }
+  matrix[size - 8][8] = true;
+  const data = codewords(text, version);
+  let bitIndex = 0;
+  let upward = true;
+  for (let right = size - 1; right > 0; right -= 2) {
+    if (right === 6) right--;
+    for (let step = 0; step < size; step++) {
+      const row = upward ? size - 1 - step : step;
+      for (let side = 0; side < 2; side++) {
+        const col = right - side;
+        if (matrix[row][col] !== null) continue;
+        const byte = data[Math.floor(bitIndex / 8)] || 0;
+        let bit = ((byte >>> (7 - (bitIndex % 8))) & 1) === 1;
+        if ((row + col) % 2 === 0) bit = !bit; // mask 0
+        matrix[row][col] = bit;
+        bitIndex++;
+      }
+    }
+    upward = !upward;
+  }
+  return matrix;
+}
+
+function svg(text, options = {}) {
+  const matrix = makeMatrix(text);
+  const quiet = 4;
+  const size = matrix.length + quiet * 2;
+  let path = '';
+  for (let y = 0; y < matrix.length; y++) for (let x = 0; x < matrix.length; x++) if (matrix[y][x]) path += `M${x + quiet} ${y + quiet}h1v1h-1z`;
+  const px = Number(options.size) || 256;
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${size} ${size}" width="${px}" height="${px}" role="img" aria-label="Setup QR code"><rect width="100%" height="100%" fill="#fff"/><path d="${path}" fill="#000" shape-rendering="crispEdges"/></svg>`;
+}
+
+function terminal(text) {
+  const matrix = makeMatrix(text);
+  const quiet = 2;
+  const rows = [];
+  const width = matrix.length + quiet * 2;
+  const white = new Array(width).fill(false);
+  const padded = [white, white, ...matrix.map((row) => [...new Array(quiet).fill(false), ...row, ...new Array(quiet).fill(false)]), white, white];
+  // Force a white cell background and black modules rather than relying on
+  // the terminal theme (a light foreground on a dark terminal inverts QR).
+  for (let y = 0; y < padded.length; y += 2) {
+    let line = '\x1b[30;47m';
+    const top = padded[y];
+    const bottom = padded[y + 1] || white;
+    for (let x = 0; x < width; x++) line += top[x] ? (bottom[x] ? '\x1b[40m \x1b[47m' : '▀') : (bottom[x] ? '▄' : ' ');
+    rows.push(line + '\x1b[0m');
+  }
+  return rows.join('\n');
+}
+
+module.exports = { makeMatrix, svg, terminal };

package/src/restart.js

@@ -0,0 +1,47 @@
+'use strict';
+// Shared graceful-restart scheduler used by the HTTP API and the native
+// restart_app chat tool. The caller sends its response/tool result first;
+// the delayed callback then stops MCP children and hands control back to
+// the serve supervisor through lifecycle.restart().
+const mcp = require('./mcp.js');
+
+function clampDelay(value, fallback = 150) {
+  return Number.isFinite(value) ? Math.max(0, Math.min(Math.round(value), 5000)) : fallback;
+}
+
+function requestRestart(options = {}) {
+  const lifecycle = options.lifecycle || {};
+  const reason = typeof options.reason === 'string' && options.reason.trim()
+    ? options.reason.trim().slice(0, 500)
+    : 'user-requested';
+  const delayMs = clampDelay(options.delayMs, Number.isFinite(options.defaultDelayMs) ? options.defaultDelayMs : 150);
+  if (lifecycle.restarting) {
+    return { ok: false, restarting: true, error: 'Restart already in progress' };
+  }
+  lifecycle.restarting = true;
+  const result = {
+    ok: true,
+    restarting: true,
+    reason,
+    delayMs,
+    mode: typeof lifecycle.restart === 'function' ? 'relaunch' : 'exit'
+  };
+  setTimeout(async () => {
+    try { process.stdout.write('[mouaif] restart requested: ' + reason + '\n'); } catch (_) {}
+    try { await mcp.stopAll(); } catch (_) { /* best-effort */ }
+    if (typeof lifecycle.restart === 'function') {
+      try {
+        await lifecycle.restart({ reason });
+        lifecycle.restarting = false;
+        return;
+      } catch (error) {
+        try { process.stderr.write('[mouaif] restart failed: ' + (error && error.message || error) + '\n'); } catch (_) {}
+        lifecycle.restarting = false;
+      }
+    }
+    process.exit(0);
+  }, delayMs).unref();
+  return result;
+}
+
+module.exports = { requestRestart, clampDelay };