bridgerator 1.0.7 → 1.1.0

package/src/doctor.mjs

@@ -0,0 +1,200 @@
+// LOGIC: see critical-logic/bridge.md ("Doctor"). `bridgerator doctor` (CLI) and the bridgerator_doctor
+// tool: checks what the link to ChatGPT needs, each with a plain-words result and what to do.
+// Every check has three outcomes plus a warning: ok / warn / fail / not_checked ("could not check" is
+// never a silent ok). Windows facts come from one PowerShell run, read by registry values and enum
+// numbers (any locale). Nothing here changes the PC; the WebSocket probe sends no key (a second link
+// with this PC's key would take over the running one).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import WebSocket from 'ws';
+import { checkKey, siteOf } from './pair.mjs';
+import { psJson, json } from './tool-lib.mjs';
+
+const MB = 1024 * 1024;
+// Scheduled task state numbers (Microsoft.Management.Infrastructure CimInstance StateEnum).
+const TASK_STATE = { 0: 'unknown', 1: 'disabled', 2: 'queued', 3: 'ready', 4: 'running' };
+
+export const WIN_PS = String.raw`
+$o = [ordered]@{}
+$o.psVersion = $PSVersionTable.PSVersion.ToString()
+$o.languageMode = [string]$ExecutionContext.SessionState.LanguageMode
+$o.policies = @{}
+foreach ($p in (Get-ExecutionPolicy -List)) { $o.policies[[string]$p.Scope] = [string]$p.ExecutionPolicy }
+$o.webview2 = $null
+foreach ($k in 'HKCU:\Software\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}', 'HKLM:\SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}', 'HKLM:\SOFTWARE\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}') {
+  try { $pv = (Get-ItemProperty $k -ErrorAction Stop).pv; if ($pv -and $pv -ne '0.0.0.0') { $o.webview2 = [string]$pv; break } } catch {}
+}
+$task = $env:BRX_TASK
+if (-not $task) { $task = 'Bridgerator-' + [Security.Principal.WindowsIdentity]::GetCurrent().User.Value }
+try { $t = Get-ScheduledTask -TaskName $task -ErrorAction Stop; $o.task = @{ state = [int]$t.State } } catch {
+  # Up to 1.0.7 one task name for every user of the PC.
+  try { $t = Get-ScheduledTask -TaskName 'Bridgerator' -ErrorAction Stop; $o.task = @{ state = [int]$t.State; old = $true } } catch { $o.task = @{ missing = $true } }
+}
+$o.proxy = @{}
+try {
+  $i = Get-ItemProperty 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings' -ErrorAction Stop
+  $o.proxy = @{ enabled = ([int]$i.ProxyEnable -eq 1); server = [string]$i.ProxyServer; pac = [string]$i.AutoConfigURL }
+} catch {}
+$o | ConvertTo-Json -Compress -Depth 4
+`;
+
+const R = (id, status, title, detail = '', fix = '') => ({ id, status, title, ...(detail ? { detail } : {}), ...(fix ? { fix } : {}) });
+
+/** Network error → plain words + what to do (the cause, not the stack). */
+export function netWhy(e) {
+  const code = e?.cause?.code || e?.code || '';
+  const name = e?.name || '';
+  if (name === 'TimeoutError' || name === 'AbortError' || code === 'UND_ERR_CONNECT_TIMEOUT' || code === 'ETIMEDOUT') return ['no answer in time', 'Check the internet connection; a firewall or VPN may block the connection.'];
+  if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') return ['the server name could not be found (DNS)', 'Check the internet connection or DNS settings.'];
+  if (code === 'ECONNREFUSED' || code === 'ECONNRESET' || code === 'UND_ERR_SOCKET') return ['the connection was refused or cut', 'A firewall, antivirus or proxy may block it; try another network.'];
+  if (/CERT|SELF_SIGNED|UNABLE_TO_(GET|VERIFY)/.test(code)) return ['the secure connection was replaced by someone in between (certificate not trusted)', 'An antivirus "HTTPS scanning" or a company proxy inspects traffic: add bridgerator.recondeck.com to its exclusions.'];
+  return [String(code || e?.message || e).slice(0, 120), 'Check the internet connection and try again.'];
+}
+
+const wsProbe = (url, timeout = 10000) => new Promise((resolve) => {
+  let done = false;
+  const ws = new WebSocket(url, { handshakeTimeout: timeout });
+  const end = (r) => { if (done) return; done = true; try { ws.terminate(); } catch { /* closed */ } resolve(r); };
+  ws.on('open', () => end({ ok: true }));
+  ws.on('unexpected-response', (_q, res) => end({ ok: false, status: res.statusCode }));
+  ws.on('error', (e) => end({ ok: false, error: e }));
+  setTimeout(() => end({ ok: false, error: Object.assign(new Error('timeout'), { name: 'TimeoutError' }) }), timeout + 1000).unref?.();
+});
+
+const newer = (a, b) => { const x = String(a).split('.').map(Number), y = String(b).split('.').map(Number); for (let i = 0; i < 3; i++) if ((x[i] || 0) !== (y[i] || 0)) return (x[i] || 0) > (y[i] || 0); return false; };
+
+/**
+ * → { ok: boolean (no fail), results: [{ id, status, title, detail?, fix? }] }.
+ * deps (tests): fetch, wsOpen(url), runPs, now(), statfs(dir), platform, nodeVersion, taskName, running (CLI), linkState (inside the bridge).
+ */
+export async function runDoctor(cfg, { version, fetch: f = globalThis.fetch, wsOpen = wsProbe, runPs, now = Date.now, statfs = (d) => fs.statfsSync(d), platform = process.platform, nodeVersion = process.versions.node, taskName, running, linkState, configDir } = {}) {
+  const out = [];
+  const major = Number(String(nodeVersion).split('.')[0]);
+  out.push(major >= 22 ? R('node', 'ok', `Node.js ${nodeVersion}`) : R('node', 'fail', `Node.js ${nodeVersion} is too old`, 'Bridgerator needs Node.js 22 or newer.', 'Run the install command from https://bridgerator.recondeck.com/app again: it brings its own Node.js.'));
+
+  // Bridge version vs the newest one on npm.
+  try {
+    const r = await f('https://registry.npmjs.org/bridgerator/latest', { signal: AbortSignal.timeout(10000) });
+    const latest = String((await r.json()).version || '');
+    out.push(!latest ? R('version', 'not_checked', `Bridgerator ${version}`, 'the update server gave no version')
+      : newer(latest, version) ? R('version', 'warn', `Bridgerator ${version} — ${latest} is available`, '', 'Run the install command again to update (settings are kept).')
+        : R('version', 'ok', `Bridgerator ${version} (latest)`));
+  } catch (e) { out.push(R('version', 'not_checked', `Bridgerator ${version}`, `update check failed: ${netWhy(e)[0]}`)); }
+
+  if (!cfg) {
+    out.push(R('config', 'fail', 'Bridgerator is not set up on this PC', '', 'Run the install command from https://bridgerator.recondeck.com/app.'));
+    return finish(out);
+  }
+  if (!cfg.token) out.push(R('key', 'fail', 'This PC has no Bridgerator key', 'It was unlinked or never paired.', 'Run the install command again and confirm the PC in the browser.'));
+
+  let relay = null, site = null;
+  try { relay = new URL(cfg.relay); site = siteOf(cfg.relay); } catch { out.push(R('relay', 'fail', 'The server address in the settings is broken', String(cfg.relay).slice(0, 80), 'Run the install command again.')); }
+
+  if (relay) {
+    // Relay reachable over HTTPS + the clock (TLS and sign-in break when the clock is far off).
+    const health = `https://${relay.host}/healthz`;
+    try {
+      const t0 = now();
+      const r = await f(health, { signal: AbortSignal.timeout(10000) });
+      const ms = now() - t0;
+      out.push(r.ok ? R('relay', 'ok', `Server reachable (${ms} ms)`) : R('relay', 'fail', `Server answered HTTP ${r.status}`, '', 'Try again in a few minutes; if it stays, write to support at https://bridgerator.recondeck.com/support.'));
+      const date = Date.parse(r.headers?.get?.('date') || '');
+      if (Number.isFinite(date)) {
+        const skew = Math.round((now() - date) / 1000);
+        out.push(Math.abs(skew) > 300 ? R('clock', 'fail', `The PC clock is off by ${Math.round(Math.abs(skew) / 60)} min`, 'Secure connections and sign-in can fail.', 'Windows Settings → Time & language → Date & time → "Set time automatically" → Sync now.')
+          : R('clock', 'ok', `Clock in sync (${skew >= 0 ? '+' : ''}${skew} s)`));
+      } else out.push(R('clock', 'not_checked', 'Clock', 'the server sent no time'));
+    } catch (e) {
+      const [why, fix] = netWhy(e);
+      out.push(R('relay', 'fail', 'Server not reachable', why, fix));
+      out.push(R('clock', 'not_checked', 'Clock', 'server not reachable'));
+    }
+    // WebSocket upgrade (proxies that pass HTTPS but drop WebSockets), without the key.
+    const w = await wsOpen(cfg.relay).catch((e) => ({ ok: false, error: e }));
+    if (w.ok || [401, 403, 400].includes(w.status)) out.push(R('websocket', 'ok', 'Live connection (WebSocket) works'));
+    else if (w.status) out.push(R('websocket', 'fail', `Live connection refused (HTTP ${w.status})`, 'Something between this PC and the server blocks WebSockets.', 'A company proxy or antivirus web filter may block it: allow mcp.bridgerator.recondeck.com.'));
+    else { const [why, fix] = netWhy(w.error); out.push(R('websocket', 'fail', 'Live connection (WebSocket) failed', why, fix)); }
+    // Key still accepted?
+    if (cfg.token && site) {
+      const k = await checkKey(site, cfg.token, { fetch: f });
+      out.push(k === 'ok' ? R('key', 'ok', 'This PC\'s key is accepted')
+        : k === 'rejected' ? R('key', 'fail', 'This PC was removed from your account', 'The server no longer accepts its key.', 'Run the install command again and confirm the PC in the browser.')
+          : R('key', 'not_checked', 'This PC\'s key', 'the server could not be asked'));
+    }
+  }
+  if (linkState) out.push(linkState === 'online' ? R('link', 'ok', 'Connected to the server now') : R('link', 'warn', `Link state: ${linkState}`, '', 'It reconnects by itself; if it stays offline, see the checks above.'));
+  if (running !== undefined) out.push(running ? R('running', 'ok', 'Bridgerator is running') : R('running', 'fail', 'Bridgerator is not running', '', 'Sign out and in again, or run the install command again.'));
+
+  // Free disk space where Bridgerator keeps its files and on the system drive.
+  const rootOf = (d) => (platform === 'win32' ? path.win32.parse(path.win32.resolve(d)).root.toUpperCase() : d);
+  const dirs = [...new Map([configDir, platform === 'win32' ? `${process.env.SystemDrive || 'C:'}\\` : '/'].filter(Boolean).map((d) => [rootOf(d), d])).values()];
+  for (const d of dirs) {
+    try {
+      const s = statfs(d);
+      const free = Number(s.bavail) * Number(s.bsize);
+      const label = platform === 'win32' ? rootOf(d).replace(/\\$/, '') : d;
+      const gb = (free / 1024 / MB).toFixed(1);
+      out.push(free < 200 * MB ? R(`disk ${label}`, 'fail', `Disk ${label} only ${Math.round(free / MB)} MB free`, '', 'Free some space (Settings → System → Storage).')
+        : free < 1024 * MB ? R(`disk ${label}`, 'warn', `Disk ${label} ${gb} GB free`, 'Snapshots for Undo and updates need space.', 'Free some space soon.')
+          : R(`disk ${label}`, 'ok', `Disk ${label} ${gb} GB free`));
+    } catch (e) { out.push(R(`disk ${d}`, 'not_checked', `Disk ${d}`, String(e?.code || e?.message || e))); }
+  }
+
+  if (platform === 'win32') {
+    let w = null;
+    try { w = await psJson({ runPs }, { script: WIN_PS, env: { BRX_TASK: taskName || '' }, timeout: 30000 }); } catch (e) { out.push(R('powershell', 'fail', 'Windows PowerShell does not run', String(e?.message || e).slice(0, 160), 'Bridgerator needs Windows PowerShell 5.1 (part of Windows). Ask the PC administrator whether it is blocked.')); }
+    if (w) {
+      out.push(w.languageMode === 'FullLanguage' ? R('powershell', 'ok', `PowerShell ${w.psVersion}`)
+        : R('powershell', 'warn', `PowerShell runs in ${w.languageMode} mode`, 'A company policy (AppLocker / WDAC) limits PowerShell: notifications, the tray window and some tools may not work.', 'Ask the PC administrator to allow Bridgerator.'));
+      const gpo = ['MachinePolicy', 'UserPolicy'].map((k) => w.policies?.[k]).find((v) => v && v !== 'Undefined');
+      out.push(gpo ? R('policy', 'warn', `Script policy set by the administrator: ${gpo}`, 'Bridgerator runs its scripts in a way this policy allows in most cases.', 'If notifications or the window do not appear, ask the administrator.')
+        : R('policy', 'ok', `Script policy: ${w.policies?.CurrentUser && w.policies.CurrentUser !== 'Undefined' ? w.policies.CurrentUser : w.policies?.LocalMachine || 'default'} (fine — Bridgerator does not need it changed)`));
+      out.push(w.webview2 ? R('webview2', 'ok', `Window component (WebView2) ${w.webview2}`) : R('webview2', 'warn', 'Window component (Microsoft WebView2) not installed', 'Bridgerator works; its window opens your account page instead.', 'Install "Microsoft Edge WebView2 Runtime" from microsoft.com, or run the install command again.'));
+      {
+        const st = w.task?.missing ? 'missing' : TASK_STATE[w.task?.state] || 'unknown';
+        out.push((st === 'ready' || st === 'running') && w.task?.old ? R('autostart', 'warn', 'Starts with Windows (old-style task)', '', 'Run the install command again to update it.')
+          : st === 'ready' || st === 'running' ? R('autostart', 'ok', 'Starts with Windows')
+          : st === 'disabled' ? R('autostart', 'warn', 'Start with Windows is off', '', 'Turn it on in the Bridgerator window → Settings, or run the install command again.')
+            : st === 'missing' ? R('autostart', 'fail', 'Start with Windows is not set up', '', 'Run the install command again.')
+              : R('autostart', 'not_checked', 'Start with Windows', 'task state unknown'));
+      }
+      const p = w.proxy || {};
+      const envProxy = process.env.HTTPS_PROXY || process.env.https_proxy || process.env.HTTP_PROXY || process.env.http_proxy;
+      if (p.enabled || p.pac) {
+        const relayFail = out.some((x) => (x.id === 'relay' || x.id === 'websocket') && x.status === 'fail');
+        out.push(R('proxy', relayFail ? 'fail' : 'warn', `A proxy is set in Windows${p.server ? ` (${String(p.server).slice(0, 60)})` : p.pac ? ' (automatic script)' : ''}`, 'Bridgerator connects directly, not through the Windows proxy.', relayFail ? 'Allow direct connections to mcp.bridgerator.recondeck.com (port 443) in the firewall / proxy.' : 'Nothing to do while the connection works.'));
+      } else out.push(R('proxy', 'ok', envProxy ? 'Proxy from the environment is set (not used by Bridgerator)' : 'No proxy'));
+    }
+  }
+  return finish(out);
+}
+const finish = (results) => ({ ok: !results.some((r) => r.status === 'fail'), results });
+
+const MARK = { ok: '[ok]  ', warn: '[!]   ', fail: '[x]   ', not_checked: '[?]   ' };
+/** Report for the console. */
+export function formatDoctor({ ok, results }) {
+  const lines = ['Bridgerator doctor', ''];
+  for (const r of results) {
+    lines.push(`${MARK[r.status]}${r.title}${r.detail ? ` — ${r.detail}` : ''}`);
+    if (r.fix && r.status !== 'ok') lines.push(`      What to do: ${r.fix}`);
+  }
+  const bad = results.filter((r) => r.status === 'fail').length, warn = results.filter((r) => r.status === 'warn').length, nc = results.filter((r) => r.status === 'not_checked').length;
+  lines.push('', ok ? `All needed checks passed${warn ? ` (${warn} warning${warn > 1 ? 's' : ''})` : ''}${nc ? `, ${nc} not checked` : ''}.` : `${bad} problem${bad > 1 ? 's' : ''} found — see "What to do" above.`);
+  return lines.join(os.EOL);
+}
+
+// --- the tool --------------------------------------------------------------------------------
+export const defs = [{
+  name: 'bridgerator_doctor',
+  title: 'Check the Bridgerator connection',
+  description: 'Checks what the link between ChatGPT and this PC needs: Node.js, Bridgerator version, this PC\'s key, server and live connection, clock, proxy, PowerShell, the window component, start with Windows, free disk space. Each result has a plain explanation and what to do. Changes nothing.',
+  inputSchema: { type: 'object', additionalProperties: false, required: ['action'], properties: { action: { type: 'string', enum: ['check'], description: '"check" runs all checks' } } },
+  annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+}];
+
+export async function handle(name, args, ctx) {
+  const st = await ctx.rpc?.('getState').catch(() => null);
+  const r = await runDoctor(ctx.cfg, { version: ctx.version, runPs: ctx.runPs, linkState: st?.state, configDir: ctx.cfg?.configDir, fetch: ctx.fetch, wsOpen: ctx.wsOpen });
+  return json(r);
+}

package/src/events.mjs

@@ -0,0 +1,21 @@
+// LOGIC: see critical-logic/bridge.md ("Relay notifications"). Events the bridge tells the relay so it
+// can notify the person outside the chat (Telegram…): {type:'event', kind, …} with whole numbers only —
+// never titles, names, paths, commands or output. At most 30 a minute (the rest are dropped, logged once).
+// delegate_done {ok: 0|1}: a delegated agent run (delegate.mjs) that went on in the background has ended.
+export const EVENT_KINDS = ['queue_done', 'task_failed', 'automation_failed', 'delegate_done'];
+const FIELDS = ['n', 'code', 'failing', 'done', 'failed', 'ok'];
+export const EVENTS_PER_MIN = 30;
+
+/** → the message to send, or null (unknown kind). Non-integer fields are dropped. */
+export function eventMessage(e) {
+  if (!e || !EVENT_KINDS.includes(e.kind)) return null;
+  const m = { type: 'event', kind: e.kind };
+  for (const k of FIELDS) if (Number.isSafeInteger(e[k])) m[k] = e[k];
+  return m;
+}
+
+/** take() → true while under `max` events in the last `windowMs`. */
+export function createEventLimiter(max = EVENTS_PER_MIN, windowMs = 60000, now = Date.now) {
+  let times = [];
+  return { take() { const t = now(); times = times.filter((x) => t - x < windowMs); if (times.length >= max) return false; times.push(t); return true; } };
+}

package/src/extra-tools.mjs

@@ -0,0 +1,122 @@
+// LOGIC: see critical-logic/bridge.md ("Extra tools"). The ONE list of the bridge's own extra tools.
+// bridge.mjs only asks this registry: defs (hello), has(name), call(name, args, ctx), settings.
+//
+// A module is { defs, handle, settings? }:
+//   defs:     MCP tool definitions [{ name, title?, description, inputSchema, annotations }]
+//             (few tools with an `action` parameter; short, non-imperative descriptions; honest hints).
+//   handle:   async (name, args, ctx) → MCP result { content: [...], isError? }.
+//             Throw a ToolError (tool-lib.mjs) for a plain-words refusal; any other throw becomes a
+//             short message without a stack (registry `call`).
+//   settings: optional [{ key: 'group.name', default: boolean, widensWhen: true|false, label: { en, ru }, hint?: { en, ru }, page? }]
+//             — stored in config.json as { group: { name: value } }; shown in the window and readable /
+//             settable through bridgerator_settings (`widensWhen` = the value that lowers protection or
+//             widens access → the person's OK on the PC). Booleans by default; also
+//             { type: 'int', min, max } and { type: 'enum', values: [narrow … wide] } with
+//             widensWhen 'up' | 'down' | null (a bigger / smaller value widens; null = never asks).
+//             page: the window page that shows it (then not in Settings → Tools).
+//
+// ctx (built by bridge.mjs per call): { cfg, policy, gate, log, popup, engine(name, args), rpc(method, p), version }
+//   ctx.policy is the CURRENT policy (folders can change at runtime); path checks: tool-lib.mjs guard().
+// Format is fixed: other modules are added by appending to EXTRA_MODULES, nothing else changes.
+import { errorText } from './tool-lib.mjs';
+import * as doctor from './doctor.mjs';
+import * as docs from './docs-tool.mjs';
+import * as search from './search-tool.mjs';
+import * as photos from './photos-tool.mjs';
+import * as software from './software-tool.mjs';
+import * as pcinfo from './pc-check.mjs';
+import * as screen from './screen-tool.mjs';
+import * as automations from './automations.mjs';
+import * as plans from './batch.mjs';
+import * as delegate from './delegate.mjs';
+
+export const EXTRA_MODULES = [doctor, docs, search, photos, software, pcinfo, screen, automations, plans, delegate];
+
+/** The registry of EXTRA_MODULES (settings-tool.mjs reads the settings part of it). */
+export const extraRegistry = () => (shared ||= createExtra());
+let shared = null;
+
+// Typed settings (int / enum) next to the booleans: validation, order for the widen check, schema.
+const kind = (s) => s.type || 'boolean';
+const valid = (s, v) => (kind(s) === 'int' ? Number.isInteger(v) && v >= s.min && v <= s.max : kind(s) === 'enum' ? s.values.includes(v) : typeof v === 'boolean');
+const need = (s) => (kind(s) === 'int' ? `a whole number from ${s.min} to ${s.max}` : kind(s) === 'enum' ? `one of ${s.values.join(', ')}` : 'true or false');
+const rank = (s, v) => (kind(s) === 'enum' ? s.values.indexOf(v) : Number(v));
+
+export function createExtra(mods = EXTRA_MODULES) {
+  const owner = new Map();
+  for (const m of mods) for (const d of m.defs || []) { if (owner.has(d.name)) throw new Error(`extra tool ${d.name} registered twice`); owner.set(d.name, m); }
+  const settings = mods.flatMap((m) => m.settings || []);
+  const byKey = new Map(settings.map((s) => [s.key, s]));
+  const get = (cfg, key) => { const [g, k] = key.split('.'); const v = cfg?.[g]?.[k]; return valid(byKey.get(key), v) ? v : byKey.get(key).default; };
+  return {
+    defs: mods.flatMap((m) => m.defs || []),
+    has: (name) => owner.has(name),
+    async call(name, args, ctx) {
+      // A tool the person turned off (config disabledTools) is refused like the engine's own.
+      if (ctx?.policy && !ctx.policy.visible({ name })) return { content: [{ type: 'text', text: `Tool "${name}" is disabled on this computer.` }], isError: true, refused: true };
+      try {
+        return await owner.get(name).handle(name, args && typeof args === 'object' && !Array.isArray(args) ? args : {}, ctx);
+      } catch (e) {
+        ctx?.log?.(`[bridgerator] ${name} failed: ${e?.code || ''} ${e?.message || e}`);
+        return { content: [{ type: 'text', text: errorText(e) }], isError: true };
+      }
+    },
+    settings,
+    /** Current values: { group: { name: bool } }. */
+    values(cfg) {
+      const o = {};
+      for (const s of settings) { const [g, k] = s.key.split('.'); (o[g] ||= {})[k] = get(cfg, s.key); }
+      return o;
+    },
+    defaults() {
+      const o = {};
+      for (const s of settings) { const [g, k] = s.key.split('.'); (o[g] ||= {})[k] = s.default; }
+      return o;
+    },
+    value: (cfg, key) => get(cfg, key),
+    /** → [{key, value}] from { group: { name: bool } } input, or { error }. Unknown groups → null (not ours). */
+    parse(input) {
+      const changes = [];
+      for (const [g, obj] of Object.entries(input || {})) {
+        if (!settings.some((s) => s.key.startsWith(`${g}.`))) continue;
+        if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return { error: `${g} must be an object` };
+        for (const [k, v] of Object.entries(obj)) {
+          const s = byKey.get(`${g}.${k}`);
+          if (!s || !valid(s, v)) return { error: `${g}.${k}: unknown or not ${s ? need(s) : 'true/false'}` };
+          changes.push({ key: `${g}.${k}`, value: v });
+        }
+      }
+      return { changes };
+    },
+    groups: () => [...new Set(settings.map((s) => s.key.split('.')[0]))],
+    /** JSON schema for the bridgerator_settings `settings` properties. */
+    schema() {
+      const o = {};
+      for (const s of settings) {
+        const [g, k] = s.key.split('.');
+        const p = kind(s) === 'int' ? { type: 'integer', minimum: s.min, maximum: s.max, description: `${s.label.en} (default ${s.default})` }
+          : kind(s) === 'enum' ? { type: 'string', enum: s.values, description: `${s.label.en} (default ${s.default})` }
+          : { type: 'boolean', description: `${s.label.en} (default ${s.default ? 'on' : 'off'})` };
+        (o[g] ||= { type: 'object', additionalProperties: false, properties: {} }).properties[k] = p;
+      }
+      return o;
+    },
+    owns: (key) => byKey.has(key),
+    widens(cfg, { key, value }) {
+      const s = byKey.get(key);
+      if (!s) return false;
+      if (kind(s) === 'boolean') return value === s.widensWhen && get(cfg, key) !== value;
+      if (!valid(s, value)) return false;
+      return s.widensWhen === 'up' ? rank(s, value) > rank(s, get(cfg, key)) : s.widensWhen === 'down' ? rank(s, value) < rank(s, get(cfg, key)) : false;
+    },
+    describe: ({ key, value }) => `${byKey.get(key)?.label.en || key}: ${typeof value === 'boolean' ? (value ? 'on' : 'off') : value}`,
+    /** Window / AI change → config.json (patch = bridge's patchConfig). true when the key is ours. */
+    set(cfg, key, value, patch) {
+      if (!byKey.has(key)) return false;
+      if (!valid(byKey.get(key), value)) throw new Error(`${key} must be ${need(byKey.get(key))}`);
+      const [g, k] = key.split('.');
+      patch({ [g]: { ...(cfg[g] || {}), [k]: value } });
+      return true;
+    },
+  };
+}

package/src/guard.mjs

@@ -0,0 +1,34 @@
+// LOGIC: see critical-logic/bridge.md ("Mass-action fuse", "Keep awake").
+// Mass-action fuse (off by default): more than `limit` deletions / moves within a minute → the bridge
+// pauses itself and asks on the PC whether to continue (no answer = stays paused).
+export const FUSE_DEFAULTS = { enabled: false, limit: 20 };
+export const FUSE_WINDOW_MS = 60000;
+
+export function createFuse({ now = Date.now, windowMs = FUSE_WINDOW_MS } = {}) {
+  let hits = [];                 // [{ t, n }]
+  const count = () => { const from = now() - windowMs; hits = hits.filter((h) => h.t > from); return hits.reduce((s, h) => s + h.n, 0); };
+  return {
+    /** Would n more actions go over the limit? → the total (with them) or 0 when they fit. Counted only if they fit. */
+    take(n, limit) {
+      const total = count() + n;
+      if (total > limit) return total;
+      hits.push({ t: now(), n });
+      return 0;
+    },
+    count,
+    reset() { hits = []; },
+  };
+}
+
+// Keep the PC awake (on by default, AC power only — the tray helper checks the power line): while a
+// call runs, for 2 minutes after the last one, and for 10 minutes after it while the task queue has
+// work (ChatGPT thinks between calls). A queue nobody works on does not keep the PC up for ever.
+export const AWAKE_AFTER_MS = 2 * 60000, AWAKE_QUEUE_MS = 10 * 60000;
+export function wantAwake({ enabled = true, inFlight = 0, lastCall = 0, queue = {}, now = Date.now() } = {}) {
+  if (!enabled) return false;
+  if (inFlight > 0) return true;
+  if (!lastCall) return false;
+  const idle = now - lastCall;
+  if (idle < AWAKE_AFTER_MS) return true;
+  return ((queue.todo || 0) + (queue.doing || 0)) > 0 && idle < AWAKE_QUEUE_MS;
+}

package/src/notice.mjs

@@ -1,39 +1,102 @@
-// Plan notices from the relay (limit reached, Pro ending/ended) shown as a Windows notification with
-// an "Open account" button. They never go into the ChatGPT chat (app rules: no upgrade links there).
-// The link is fixed here — the relay only says which notice, not where to send the user.
+// Plan notices from the relay (limit reached, Pro ending/ended) and the bridge's own link notices,
+// shown as a Windows notification with an "Open account" button. They never go into the ChatGPT
+// chat (app rules: no upgrade links there). The link is fixed here — the relay only says which
+// notice, not where to send the user. Relay values are validated strictly and reach PowerShell only
+// as environment variables (escaped there), never as part of the script text.
 import { execFile } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { POWERSHELL, psArgs } from './win.mjs';
+import { LABEL } from './confirm.mjs';
+import { safeUrl, accountUrl } from './plan.mjs';
 
 export const ACCOUNT_URL = 'https://bridgerator.recondeck.com/app';
-const day = (iso) => String(iso || '').slice(0, 10);
+const int = (x) => (Number.isSafeInteger(x) && x >= 0 ? x : null);
+const ymd = (x) => (typeof x === 'string' && /^\d{4}-\d{2}-\d{2}(T|$)/.test(x) ? x.slice(0, 10) : null);
 const xml = (s) => String(s).replace(/[<>&"']/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&apos;' }[c]));
 
 // ponytail: English only for now (owner, 20.10); other languages later.
 export function noticeText(n) {
-  const t = {
-    limit: ['Bridgerator: monthly limit reached', `${n.calls} of ${n.limit} tool calls used. ChatGPT can't use this PC until the 1st. Turn on Pro in your account.`],
-    expired: ['Bridgerator Pro has ended', "You're on Free now (10,000 tool calls a month). Renew Pro in your account."],
-    expiring: [`Bridgerator Pro ends on ${day(n.until)}`, 'Pay for 30 more days in your account to keep unlimited calls.'],
-  }[n.kind];
-  return t && { title: t[0], body: t[1], button: 'Open account' };
+  const kind = n?.kind;
+  let t;
+  if (kind === 'limit') {
+    const calls = int(n.calls), limit = int(n.limit);
+    if (calls === null || limit === null) return undefined;
+    t = ['Bridgerator: monthly limit reached', `${calls} of ${limit} tool calls used. ChatGPT can't use this PC until the 1st. Turn on Pro in your account.`];
+  } else if (kind === 'expiring') {
+    const until = ymd(n.until);
+    if (!until) return undefined;
+    t = [`Bridgerator Pro ends on ${until}`, 'Pay for 30 more days in your account to keep unlimited calls.'];
+  } else if (kind === 'queue_done') {
+    const title = typeof n.title === 'string' ? n.title.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ').trim().slice(0, 120) : '';
+    if (!title) return undefined;
+    t = ['Queue task done', title];
+  } else if (kind === 'protection_off') {
+    // Internal list only (the bridge's own labels), never relay text.
+    const ok = new Set(['confirmations', 'your own patterns', ...Object.values(LABEL).map((l) => `confirmations for ${l}`)]);
+    const what = Array.isArray(n.what) ? n.what.filter((w) => ok.has(w)) : [];
+    if (!what.length) return undefined;
+    t = ['Bridgerator: protection turned off', `${what.join(', ')} — turn back on in the Bridgerator window or: bridgerator.cmd confirm on`];
+  } else if (kind === 'screenshot') {
+    // On every screenshot the AI takes (screen-tool.mjs): the person always sees that it happened.
+    const what = n.what === 'screen' ? 'Whole screen' : n.what === 'monitor' && int(n.monitor) ? `Monitor ${int(n.monitor)}`
+      : n.what === 'window' && typeof n.title === 'string' ? `Window "${n.title.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ').trim().slice(0, 80)}"` : null;
+    if (!what) return undefined;
+    t = ['Bridgerator: the AI took a screenshot', `${what}${n.ocr ? ' (text recognized)' : ''}. You can turn screenshots or this notice off in the Bridgerator window.`];
+    return { title: t[0], body: t[1], button: null, url: accountUrl() };
+  } else if (kind === 'updating' || kind === 'updated') {
+    // In-window update (owner 21.10: never a console): before the hidden installer, and from the new version.
+    const v = typeof n.version === 'string' && /^\d+\.\d+\.\d+$/.test(n.version) ? n.version : null;
+    if (!v) return undefined;
+    t = kind === 'updating' ? [`Bridgerator is updating to ${v}`, 'It restarts by itself in about a minute. ChatGPT can use this PC again right after.'] : [`Bridgerator updated to ${v}`, 'Your settings are kept.'];
+    return { title: t[0], body: t[1], button: null, url: accountUrl() };
+  } else if (kind === 'confirm_locked') {
+    // V-9: the window / tray toggle could not write confirm.ini (another program holds it): nothing changed.
+    t = ['Bridgerator: the setting was not changed', 'Another program is using confirm.ini, so the confirmation setting stays as it was. Try again in a moment.'];
+    return { title: t[0], body: t[1], button: null, url: accountUrl() };
+  } else if (kind === 'confirm_off') {
+    const label = Object.hasOwn(LABEL, n.category) ? LABEL[n.category] : null;
+    if (!label) return undefined;
+    t = [`Confirmations for ${label} are off`, `Turn back on: bridgerator.cmd confirm on ${n.category}`];
+  } else {
+    const fixed = {
+      expired: ['Bridgerator Pro has ended', "You're on Free now (10,000 tool calls a month). Renew Pro in your account."],
+      unlinked: ['Bridgerator: this computer is no longer linked', 'ChatGPT can no longer reach this PC. Run the install command from your account page again.'],
+      offline: ['Bridgerator is offline', "ChatGPT can't reach this PC right now. Bridgerator keeps trying to reconnect."],
+      replaced: ['Bridgerator: this key is used elsewhere', 'Another Bridgerator with this computer\'s key took over the link. This PC retries later; if it keeps happening, run the install command on this PC again.'],
+    };
+    t = Object.hasOwn(fixed, kind) ? fixed[kind] : undefined;
+  }
+  if (!t) return undefined;
+  // Plan notices get the pay button (allowed here on the PC, never inside ChatGPT); only our own site.
+  const pay = { limit: 'Upgrade to Pro', expiring: 'Renew Pro', expired: 'Renew Pro' }[kind];
+  return { title: t[0], body: t[1], button: pay || 'Open account', url: pay ? safeUrl(n.renewUrl) : accountUrl() };
 }
 
-export function toastXml({ title, body, button }) {
-  return `<toast activationType="protocol" launch="${ACCOUNT_URL}"><visual><binding template="ToastGeneric"><text>${xml(title)}</text><text>${xml(body)}</text></binding></visual>`
-    + `<actions><action content="${xml(button)}" activationType="protocol" arguments="${ACCOUNT_URL}"/></actions></toast>`;
+const ICON_URL = new URL('../assets/icon-64.png', import.meta.url);
+export const ICON = fileURLToPath(ICON_URL);
+export function toastXml({ title, body, button, url = accountUrl() }) {
+  const link = xml(safeUrl(url));
+  return `<toast activationType="protocol" launch="${link}"><visual><binding template="ToastGeneric"><image placement="appLogoOverride" src="${xml(ICON_URL.href)}"/><text>${xml(title)}</text><text>${xml(body)}</text></binding></visual>`
+    + (button ? `<actions><action content="${xml(button)}" activationType="protocol" arguments="${link}"/></actions>` : '') + '</toast>';
 }
 
-export function showNotice(n, log = console.log) {
-  const t = noticeText(n);
-  if (!t) return;
-  log(`[bridgerator] notice: ${t.title} — ${t.body} ${ACCOUNT_URL}`);
-  if (process.platform !== 'win32') return;
-  // Own app id under HKCU (no admin): the notification header reads "Bridgerator", not "Windows PowerShell".
-  const ps = `$k = 'HKCU:\\Software\\Classes\\AppUserModelId\\Bridgerator'
-if (-not (Test-Path $k)) { New-Item $k -Force | Out-Null; New-ItemProperty $k -Name DisplayName -Value 'Bridgerator' -Force | Out-Null }
+// Fixed script: the texts come in through BR_TOAST (the ready XML, escaped above).
+const PS = `$k = 'HKCU:\\Software\\Classes\\AppUserModelId\\Bridgerator'
+if (-not (Test-Path $k)) { New-Item $k -Force | Out-Null }
+New-ItemProperty $k -Name DisplayName -Value 'Bridgerator' -Force | Out-Null
+if ($env:BR_ICON -and (Test-Path $env:BR_ICON)) { New-ItemProperty $k -Name IconUri -Value $env:BR_ICON -Force | Out-Null }
 [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null
 [Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] > $null
 $x = New-Object Windows.Data.Xml.Dom.XmlDocument
-$x.LoadXml('${toastXml(t).replace(/'/g, "''")}')
+$x.LoadXml($env:BR_TOAST)
 [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Bridgerator').Show([Windows.UI.Notifications.ToastNotification]::new($x))`;
-  execFile('powershell', ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(ps, 'utf16le').toString('base64')], { windowsHide: true }, (e) => { if (e) log(`[bridgerator] notification failed: ${e.message}`); });
+
+// `done` runs once the notification is shown (or could not be): lets the caller exit after it.
+export function showNotice(n, log = console.log, done = () => {}) {
+  const t = noticeText(n);
+  if (!t) return done();
+  log(`[bridgerator] notice: ${t.title} — ${t.body} ${accountUrl()}`);
+  if (process.platform !== 'win32') return done();
+  // Own app id under HKCU (no admin): the notification header reads "Bridgerator", not "Windows PowerShell".
+  execFile(POWERSHELL, psArgs(PS), { windowsHide: true, timeout: 20000, env: { ...process.env, BR_TOAST: toastXml(t), BR_ICON: ICON } }, (e) => { if (e) log(`[bridgerator] notification failed: ${e.message}`); done(); });
 }

package/src/pair.mjs

@@ -1,26 +1,48 @@
 // Key-less setup: ask the relay for a pairing code, open the confirmation page in the browser, wait
 // until the signed-in owner confirms this computer there, and get this PC's device key back.
 import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import { CMD } from './win.mjs';
 
 // wss://mcp.bridgerator.recondeck.com/link → https://bridgerator.recondeck.com (the site host, where the account pages live).
 export const siteOf = (relay) => { const u = new URL(relay); return `${u.protocol === 'ws:' ? 'http' : 'https'}://${u.host.replace(/^mcp\./, '')}`; };
 
 // Opens the URL in the default browser. Only a URL we checked ourselves reaches cmd's `start`.
 export function openBrowser(url) {
-  if (!/^https?:\/\/[A-Za-z0-9.:-]+\/pair\?code=[A-Z0-9]{4}-[A-Z0-9]{4}$/.test(url)) return;
+  if (!/^https:\/\/[A-Za-z0-9.:-]+\/pair\?code=[A-Z0-9]{4}-[A-Z0-9]{4}$/.test(url)) return;
   try {
     const p = process.platform === 'win32'
-      ? spawn('cmd', ['/c', `start "" "${url}"`], { windowsHide: true, windowsVerbatimArguments: true, stdio: 'ignore', detached: true })
+      ? spawn(CMD, ['/d', '/c', `start "" "${url}"`], { windowsHide: true, windowsVerbatimArguments: true, stdio: 'ignore', detached: true })
       : spawn(process.platform === 'darwin' ? 'open' : 'xdg-open', [url], { stdio: 'ignore', detached: true });
     p.on('error', () => {});
     p.unref();
   } catch { /* no browser: the URL is printed */ }
 }
 
-/** → { token, name } once the owner confirmed; throws when the code expires. */
-export async function pair(site, name, { fetch: f = globalThis.fetch, open = openBrowser, log = console.log, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), everyMs = 3000 } = {}) {
+/** → { token, name, email? } once the owner confirmed; throws when the code expires. */
+/**
+ * This PC + this Windows user, as a one-way fingerprint: sha256 hex of MachineGuid + user SID. Lets
+ * the relay replace an offline PC of the same name only when it is really the same machine/user.
+ * The raw values never leave the PC. → '' when either is unknown.
+ */
+export function machineFp(machineGuid, sid) {
+  const g = String(machineGuid || '').trim().toLowerCase(), u = String(sid || '').trim().toUpperCase();
+  if (!/^[0-9a-f-]{32,36}$/.test(g) || !/^S-1-[\d-]+$/.test(u)) return '';
+  return crypto.createHash('sha256').update(`${g}|${u}`).digest('hex');
+}
+
+// The key travels over these requests: https only (the same "wss only" rule as the link itself);
+// plain http only to this PC itself (loopback: local tests, a relay on the same machine).
+const needHttps = (site) => {
+  const s = String(site || '');
+  if (/^https:\/\/[^\s/]+/i.test(s) || /^http:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?(\/|$)/i.test(s)) return;
+  throw new Error(`the server address must be https://, got "${site}"`);
+};
+
+export async function pair(site, name, { fp = '', fetch: f = globalThis.fetch, open = openBrowser, log = console.log, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), everyMs = 3000 } = {}) {
+  needHttps(site);
   const post = (path, body) => f(`${site}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(20000) });
-  const r = await post('/pair/start', { name });
+  const r = await post('/pair/start', { name, ...(fp ? { fp } : {}) });
   if (!r.ok) throw new Error(`could not start pairing (HTTP ${r.status}) — try again in a minute`);
   const s = await r.json();
   const url = `${site}/pair?code=${s.code}`;
@@ -36,8 +58,21 @@ export async function pair(site, name, { fetch: f = globalThis.fetch, open = ope
     await sleep(everyMs);
     let p;
     try { p = await post('/pair/poll', { poll: s.poll }); } catch { continue; } // network blip: try again
-    if (p.status === 200) { const j = await p.json(); if (j.token) return { token: j.token, name: j.name || name }; }
+    if (p.status === 200) { const j = await p.json(); if (j.token) return { token: j.token, name: j.name || name, ...(typeof j.email === 'string' ? { email: j.email } : {}) }; }
     if (p.status === 410) break;
+    if (p.status === 404) throw new Error('this pairing code is no longer valid — run the install command again');
+    if (p.status === 429) throw new Error('too many attempts — wait a few minutes, then run the install command again');
   }
   throw new Error('the code expired before it was confirmed — run the command again');
 }
+
+/** Is the stored device key still accepted? → 'ok' | 'rejected' (computer removed in the account) | 'unknown' (network). */
+export async function checkKey(site, token, { fetch: f = globalThis.fetch } = {}) {
+  try {
+    needHttps(site);
+    const r = await f(`${site}/pair/check`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ token }), signal: AbortSignal.timeout(15000) });
+    if (r.status === 401) return 'rejected';
+    if (r.status === 200 && (await r.json().catch(() => ({}))).ok === true) return 'ok';
+  } catch { /* offline: keep the key */ }
+  return 'unknown';
+}