@flame0510/project-aether 1.6.1 → 1.7.0

package/next.config.mjs

@@ -1,7 +1,15 @@
+// Extra hostnames or IPs allowed to reach the dev server (`next dev` only — no effect on
+// a production build), e.g. a LAN address when opening the dashboard from another device.
+// Comma-separated, without scheme or port; none by default.
+const extraDevOrigins = (process.env.REV4A_DEV_ORIGINS ?? '')
+  .split(',')
+  .map((origin) => origin.trim())
+  .filter(Boolean);
+
 const nextConfig = {
   reactStrictMode: true,
   serverExternalPackages: ['better-sqlite3'],
-  allowedDevOrigins: ['187.77.156.41', '127.0.0.1', 'localhost', 'rev4a.srv1490011.hstgr.cloud'],
+  allowedDevOrigins: ['127.0.0.1', 'localhost', ...extraDevOrigins],
 };
 
 export default nextConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flame0510/project-aether",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Rev4a — Revolution for Agents. OpenClaw agent fleet orchestrator.",
   "keywords": [
     "openclaw",
@@ -52,12 +52,14 @@
   "scripts": {
     "dev": "next dev -p 3720",
     "build": "next build",
+    "typecheck": "tsc --noEmit",
     "start": "rev4a serve",
     "start:all": "rev4a serve",
     "refresh:pricing": "node scripts/refresh-model-pricing.mjs",
-    "smoke:db-bootstrap": "node scripts/smoke-db-bootstrap.mjs",
     "postinstall": "node bin/postinstall.js",
-    "check:language": "node scripts/check-language.mjs"
+    "check:language": "node scripts/check-language.mjs",
+    "info:suggest": "node scripts/model-info-suggest.mjs",
+    "info:verify": "node scripts/model-info-verify.mjs"
   },
   "dependencies": {
     "@types/better-sqlite3": "^7.6.13",

package/scripts/backup.sh

@@ -1,66 +1,60 @@
 #!/usr/bin/env bash
-# backup.sh — Backup Rev4a data to a tar.gz archive
+# backup.sh — archive Rev4a's own data directory
 #
 # Usage:
-#   sudo bash scripts/backup.sh                     # backup to ./backups/
-#   sudo bash scripts/backup.sh /path/to/backups    # custom directory
+#   bash scripts/backup.sh                    # archive into ~/rev4a-backups/
+#   bash scripts/backup.sh /path/to/backups   # custom destination
 #
-# What it backs up:
-#   - data/*.db (events, credentials, lineage)
-#   - data/provider-keys.json
-#   - data/agents-token.json
-#   - models.config.json
-#   - .env (credentials and configuration)
+# What it archives: the whole Rev4a data directory — $REV4A_DATA_DIR when set,
+# otherwise ~/.config/rev4a (the same rule as lib/rev4a-paths.ts). That is `.env`
+# (secrets and configuration), everything under `data/` (events.db and credentials.db
+# with their -wal/-shm files, provider-keys.json, agents-token.json, model overrides,
+# the update log) and `shared/` (shared skills and rules). New files there are included
+# automatically.
 #
-# Does NOT back up:
-#   - node_modules (can be reinstalled)
-#   - .next build cache (can be rebuilt)
+# Not included: agent volumes (the cold backups in the dashboard cover those), the
+# installed package, node_modules, .next.
+#
+# The archive holds every Rev4a secret in plain text: it is created with mode 0600, and a
+# destination directory the script creates gets mode 0700 (an existing one is left as it
+# is). Keep a copy off the machine, stored securely.
+# For a fully consistent database copy, stop Rev4a first (`systemctl stop rev4a`);
+# a copy taken while it runs is normally fine, since SQLite keeps its WAL alongside.
 set -euo pipefail
 
-# Resolve script directory
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REV4A_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
-BACKUP_DIR="${1:-${REV4A_ROOT}/backups}"
-
-mkdir -p "$BACKUP_DIR"
-
-TS=$(date -u +%Y%m%d-%H%M%S)
-ARCHIVE="${BACKUP_DIR}/rev4a-backup-${TS}.tar.gz"
-
-echo "Backing up Rev4a data..."
-echo "  Source: ${REV4A_ROOT}"
-echo "  Target: ${ARCHIVE}"
+DATA_DIR="${REV4A_DATA_DIR:-${HOME}/.config/rev4a}"
+BACKUP_DIR="${1:-${HOME}/rev4a-backups}"
 
-cd "$REV4A_ROOT"
+if [[ ! -d "$DATA_DIR" ]]; then
+  echo "Error: Rev4a data directory not found: $DATA_DIR" >&2
+  echo "Set REV4A_DATA_DIR if Rev4a keeps its data elsewhere." >&2
+  exit 1
+fi
+if [[ ! -f "$DATA_DIR/.env" && ! -d "$DATA_DIR/data" ]]; then
+  echo "Error: $DATA_DIR has neither .env nor data/ — refusing to archive an unrelated directory." >&2
+  exit 1
+fi
 
-# Restrict permissions during archive creation
 umask 077
-
-# Create tar with only the files we care about
-tar -czf "$ARCHIVE" \
-  --exclude='node_modules' \
-  --exclude='.next' \
-  --exclude='.git' \
-  --exclude='backups' \
-  data/*.db \
-  data/*.db-shm \
-  data/*.db-wal \
-  data/provider-keys.json 2>/dev/null || true \
-  data/agents-token.json 2>/dev/null || true \
-  models.config.json 2>/dev/null || true \
-  .env 2>/dev/null || true
-
-echo ""
-echo "=============================================="
-echo "  Backup complete!"
-echo "=============================================="
-echo ""
-echo "  Archive: ${ARCHIVE}"
-echo "  Size:    $(du -h "$ARCHIVE" | cut -f1)"
-echo ""
+mkdir -p "$BACKUP_DIR"
+# The archive must not end up inside what it archives. Both paths are compared once they
+# exist and with symlinks resolved, so a relative or linked destination cannot slip past.
+case "$(cd "$BACKUP_DIR" && pwd -P)/" in
+  "$(cd "$DATA_DIR" && pwd -P)/"*) echo "Error: the destination is inside the data directory." >&2; exit 1 ;;
+esac
+
+ARCHIVE="${BACKUP_DIR}/rev4a-backup-$(date -u +%Y%m%d-%H%M%S).tar.gz"
+echo "Backing up Rev4a data"
+echo "  Source: $DATA_DIR"
+echo "  Target: $ARCHIVE"
+
+# noclobber: a second backup in the same second fails instead of overwriting the first.
+set -o noclobber
+tar -C "$DATA_DIR" -czf - . > "$ARCHIVE"
+set +o noclobber
 chmod 600 "$ARCHIVE"
-echo "  WARNING: This archive contains plain-text credentials (.env)."
-echo "  Store it securely (encrypted at rest recommended)."
+
 echo ""
-echo "  To restore: sudo bash scripts/restore.sh ${ARCHIVE}"
-echo "=============================================="
+echo "Backup complete: $(tar -tzf "$ARCHIVE" | grep -vc '/$') files, $(du -h "$ARCHIVE" | cut -f1)"
+echo "It contains plain-text secrets (.env, keys, credentials): keep a copy off this machine, stored securely."
+echo "To restore: bash scripts/restore.sh $ARCHIVE"

package/scripts/check-language.mjs

@@ -4,7 +4,7 @@
  * identifiers, comments, docs, UI strings (AGENTS.md §2.1).
  *
  * The word list is deliberately conservative: only words that are **not** English words.
- * `come`, `per`, `non`, `la`, `al`, `tra` are left out on purpose, they would fire on
+ * `come`, `per`, `non`, `la`, `al` are left out on purpose, they would fire on
  * English text; the list is content words plus unmistakable function words. A line
  * carrying `lang-ok` is skipped, for the legitimate case where the Italian is the point
  * (a fixture, a note about the rule):
@@ -12,8 +12,9 @@
  *   // lang-ok: the exact text a user reported
  *
  * It catches Italian *words*, not Italian thinking written in English, and it never
- * translates: the fix is manual. Wired into the release workflow (a release cannot ship
- * Italian) and available locally as `npm run check:language`.
+ * translates: the fix is manual. Run by CI on every push to main and every pull request,
+ * again by the release workflow before publishing, and available locally as
+ * `npm run check:language` (and as a pre-commit hook, `.githooks/pre-commit`).
  *
  * Usage:
  *   node scripts/check-language.mjs            # every tracked file
@@ -35,6 +36,23 @@ const WORDS = [
   'essere', 'fare', 'dove', 'nuovo', 'nuova', 'vecchio', 'vecchia', 'davvero', 'invece',
   'inoltre', 'quindi', 'della', 'delle', 'degli', 'nella', 'nelle', 'negli', 'dalla', 'dalle',
   'dallo', 'allo', 'alla', 'sul', 'sulla', 'nessuno', 'nessuna', 'adesso', 'subito', 'oggi', 'ieri',
+  // Added 2026-09-24, after three lines survived the list above — one of them a UI string
+  // ('Include OpenRouter e altri provider…' in the system-health recommendations).
+  'compila', 'compilare', 'compilato', 'pubblica', 'pubblico', 'pubblicare', 'pubblicato',
+  'altro', 'altra', 'altri', 'altre', 'giorno', 'giorni', 'mese', 'settimana', 'settimane',
+  'aggiorna', 'aggiornare', 'aggiornamento', 'aggiornato', 'controllo', 'controlla', 'controllare',
+  'verifica', 'verificare', 'esempio', 'esempi', 'funziona', 'funzione', 'funzioni',
+  'creare', 'cancella', 'cancellare', 'scarica', 'scaricare', 'usare', 'usato', 'utilizzo',
+  'riga', 'parola', 'parole', 'elenco', 'codice', 'chiave', 'chiavi', 'prova', 'risultato',
+  'risultati', 'stesso', 'stessa', 'stessi', 'stesse', 'ancora', 'sempre', 'dopo', 'forse',
+  'puoi', 'posso', 'siamo', 'abbiamo', 'erano', 'servono', 'vuole', 'vuoi', 'quale', 'quali',
+  'disponibile', 'necessario', 'corretto', 'sbagliato', 'mancante', 'vuoto', 'ultimo', 'ultima',
+  'italiano', 'italiana', 'italiane', 'inglese', 'pero', 'cosi', 'piu', 'ecco', 'grazie',
+  // Added after a later review found UI labels, alert text and a doc line the list above
+  // missed (session drawer, lineage and dashboard toolbars, system-health alerts).
+  'stato', 'tipo', 'costo', 'costi', 'durata', 'inizio', 'aggiorn', 'azioni', 'recenti',
+  'grafo', 'reimposta', 'periodo', 'agenti', 'agente', 'apri', 'soglia', 'coprire',
+  'contenuti', 'allinea', 'allineare', 'campioni', 'consecutivi',
 ];
 
 const EXTENSIONS = ['.ts', '.tsx', '.js', '.mjs', '.cjs', '.md', '.json', '.sh', '.yml', '.yaml', '.css', '.html'];

package/scripts/model-info-verify.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * Verifies proposed `info` blocks against the model cards they cite — the gate between a
+ * curator agent's proposal and `models.config.json`. Nothing is written: the script says
+ * which proposals hold and which do not.
+ *
+ * What it checks, per model:
+ *  - the id exists in the catalogue, and the model has a Hugging Face card;
+ *  - `evidence` is present (a proposal without it is not verifiable);
+ *  - every number in `params` appears in the card text;
+ *  - every benchmark value sits in a row named after the benchmark, under a column whose
+ *    header names this model (or its instruct variant) — the nearest header row that
+ *    carries the model's name, so a card with a stacked or merged header still resolves;
+ *  - `docUrl`, when asked with `--check-links`, answers 200.
+ *
+ * Usage:
+ *   node scripts/model-info-verify.mjs <file with the proposals|->   [--check-links]
+ * The file may be raw agent output: JSON objects are extracted from it.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const args = process.argv.slice(2);
+const input = args.find((a) => !a.startsWith('--')) ?? '-';
+const checkLinks = args.includes('--check-links');
+
+const catalogue = new Set(JSON.parse(fs.readFileSync(path.join(ROOT, 'models.config.json'), 'utf-8')).models.map((m) => m.id));
+const details = (() => {
+  try { return JSON.parse(fs.readFileSync(path.join(ROOT, 'model-details.json'), 'utf-8')).models ?? {}; } catch { return {}; }
+})();
+
+const decode = (s) => s.replace(/<[^>]*>/g, ' ').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/\s+/g, ' ').trim();
+const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/** Every table row of a card, markdown and HTML, as normalised `| a | b |` strings. */
+function tableRows(md) {
+  const rows = md.split('\n').filter((l) => l.trim().startsWith('|')).map(decode);
+  for (const tr of md.matchAll(/<tr[^>]*>([\s\S]*?)<\/tr>/gi)) {
+    const cells = [...tr[1].matchAll(/<t[dh][^>]*>([\s\S]*?)<\/t[dh]>/gi)].map((c) => decode(c[1]));
+    if (cells.length) rows.push(`| ${cells.join(' | ')} |`);
+  }
+  return rows;
+}
+
+const cellsOf = (row) => row.split('|').slice(1, -1).map((c) => c.replace(/\*/g, '').trim());
+
+/**
+ * A header cell names the model when it carries the same distinctive run of characters:
+ * cards label columns with a display name ("Kimi K2.5 (Thinking)", "Nemotron-3-Super")
+ * that is not the id, and an exact match would miss every one of them.
+ */
+function namesModel(cell, modelNames) {
+  const c = norm(cell);
+  if (!c) return false;
+  return modelNames.some((n) => {
+    const m = norm(n);
+    if (!m) return false;
+    for (let len = Math.min(c.length, m.length); len >= 6; len--) {
+      for (let i = 0; i + len <= c.length; i++) if (m.includes(c.slice(i, i + len))) return true;
+    }
+    return false;
+  });
+}
+
+/** The nearest row above `row` that names the model: the header this value belongs under. */
+function headerNaming(rows, rowIndex, modelNames) {
+  for (let i = rowIndex - 1; i >= 0; i--) {
+    if (!rows[i]) break;
+    const cells = cellsOf(rows[i]);
+    if (cells.some((c) => namesModel(c, modelNames))) return cells;
+  }
+  return null;
+}
+
+function proposalObjects(text) {
+  const out = [];
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] !== '{') continue;
+    let depth = 0, inString = false, escaped = false, end = -1;
+    for (let j = i; j < text.length; j++) {
+      const ch = text[j];
+      if (inString) {
+        if (escaped) escaped = false;
+        else if (ch === '\\') escaped = true;
+        else if (ch === '"') inString = false;
+        continue;
+      }
+      if (ch === '"') inString = true;
+      else if (ch === '{') depth++;
+      else if (ch === '}') { depth--; if (depth === 0) { end = j; break; } }
+    }
+    if (end < 0) continue; // an unclosed fragment (engine logs) must not stop the scan
+    try {
+      const parsed = JSON.parse(text.slice(i, end + 1));
+      if (parsed && parsed.id && (parsed.info || parsed.skipped)) out.push(parsed);
+    } catch { /* not a proposal object */ }
+    i = end;
+  }
+  return out;
+}
+
+async function cardFor(hfId) {
+  const cached = path.join('/tmp', `card-${hfId.replace('/', '_')}.md`);
+  if (fs.existsSync(cached)) return fs.readFileSync(cached, 'utf-8');
+  const res = await fetch(`https://huggingface.co/${hfId}/raw/main/README.md`, { signal: AbortSignal.timeout(30_000) });
+  if (!res.ok) throw new Error(`card HTTP ${res.status}`);
+  const md = await res.text();
+  fs.writeFileSync(cached, md);
+  return md;
+}
+
+async function verify(model, catalogueId) {
+  const problems = [];
+  const warnings = [];
+  if (!catalogue.has(catalogueId)) problems.push('id not in the catalogue');
+  if (model.skipped) return { problems, warnings: [`skipped: ${model.skipped}`] };
+  const hfId = details[catalogueId]?.hf?.id;
+  if (!hfId) return { problems, warnings: ['no Hugging Face card: not verifiable'] };
+  if (!model.evidence?.length) problems.push('evidence missing');
+  let md;
+  try {
+    md = await cardFor(hfId);
+  } catch (e) {
+    if (e instanceof Error) return { problems, warnings: [`card unavailable: ${e.message}`] };
+    return { problems, warnings: ['card unavailable'] };
+  }
+  const rows = tableRows(md);
+  const shortName = hfId.split('/').pop();
+  const modelNames = [shortName, catalogueId.split('/').pop(), shortName.replace(/-/g, '')];
+
+  const info = model.info ?? {};
+  if (info.params) {
+    const numbers = info.params.match(/\d+(?:\.\d+)?\s*[BT]/g) ?? [];
+    const missing = numbers.filter((n) => !md.replace(/\s/g, '').includes(n.replace(/\s/g, '')));
+    if (missing.length) problems.push(`params: numbers not in the card (${missing.join(', ')})`);
+  }
+  if (info.docUrl && checkLinks) {
+    try {
+      const res = await fetch(info.docUrl, { method: 'GET', signal: AbortSignal.timeout(20_000) });
+      if (!res.ok) problems.push(`docUrl: HTTP ${res.status}`);
+    } catch {
+      problems.push('docUrl: unreachable');
+    }
+  }
+  const sameNumber = (cell, value) => {
+    const parsed = Number(String(cell).replace(/[^0-9.\-]/g, ''));
+    return Number.isFinite(parsed) && Math.abs(parsed - value) < 1e-9;
+  };
+  for (const bench of info.benchmarks ?? []) {
+    // A benchmark name can appear in more than one table (or in prose rows); accept the
+    // value when any row named after it carries it, then check the column of that row.
+    const candidates = rows
+      .map((r, index) => ({ r, index }))
+      .filter(({ r }) => r.toLowerCase().includes(String(bench.name).toLowerCase()) && /\d/.test(r));
+    if (candidates.length === 0) { problems.push(`${bench.name}: no matching row`); continue; }
+    const hit = candidates.find(({ r }) => cellsOf(r).some((c) => sameNumber(c, bench.value)));
+    if (!hit) { problems.push(`${bench.name}: value ${bench.value} not in any row named after it`); continue; }
+    const cells = cellsOf(hit.r);
+    const header = headerNaming(rows, hit.index, modelNames);
+    if (!header) { warnings.push(`${bench.name}: no header naming the model above the row — check by hand`); continue; }
+    const valueAt = cells.map((c, i) => (sameNumber(c, bench.value) ? i : -1)).filter((i) => i >= 0);
+    const owns = valueAt.some((i) => header[i] && namesModel(header[i], modelNames));
+    if (!owns) problems.push(`${bench.name}: value sits under "${valueAt.map((i) => header[i] ?? '?').join(', ')}"`);
+  }
+  return { problems, warnings };
+}
+
+const raw = input === '-' ? fs.readFileSync(0, 'utf-8') : fs.readFileSync(input, 'utf-8');
+let models;
+try {
+  const parsed = JSON.parse(raw);
+  models = Array.isArray(parsed) ? parsed : Object.values(parsed);
+} catch {
+  models = proposalObjects(raw);
+}
+
+let clean = 0, flagged = 0, warned = 0;
+for (const model of models) {
+  const { problems, warnings } = await verify(model, model.id);
+  if (problems.length) {
+    flagged++;
+    console.log(`✗ ${model.id}\n   ${problems.join('\n   ')}`);
+  } else if (warnings.length) {
+    warned++;
+    console.log(`! ${model.id}\n   ${warnings.join('\n   ')}`);
+  } else {
+    clean++;
+    console.log(`✓ ${model.id}`);
+  }
+}
+console.log(`\n${models.length} proposal(s): ${clean} verified, ${warned} to check by hand, ${flagged} rejected`);
+process.exit(flagged > 0 ? 1 : 0);

package/scripts/restore.sh

@@ -1,82 +1,100 @@
 #!/usr/bin/env bash
-# restore.sh — Restore Rev4a data from a backup archive
+# restore.sh — restore Rev4a's data directory from a backup.sh archive
 #
 # Usage:
-#   sudo bash scripts/restore.sh backups/rev4a-backup-20260724-120000.tar.gz
+#   bash scripts/restore.sh ~/rev4a-backups/rev4a-backup-20260926-120000.tar.gz
 #
-# The script restores:
-#   - data/*.db
-#   - data/provider-keys.json
-#   - data/agents-token.json
-#   - models.config.json
-#   - .env
+# Restores into $REV4A_DATA_DIR when set, otherwise ~/.config/rev4a — the directory
+# backup.sh archived. Run it as the user Rev4a runs as: under `sudo` HOME becomes /root
+# and REV4A_DATA_DIR is dropped, so pass it explicitly (`sudo REV4A_DATA_DIR=… bash …`).
 #
-# Existing files are backed up to a .pre-restore directory before overwriting.
+# The data directory is replaced as a whole, not overwritten file by file: a file the
+# backup does not have (a leftover SQLite -wal, for one) would otherwise be mixed into
+# the restored state. The current contents are archived first into ~/rev4a-backups, so a
+# restore can itself be undone.
+#
+# Rev4a must not be running. When the rev4a systemd service is active it is stopped (and
+# must be started again afterwards); a `rev4a serve` started any other way makes the
+# script refuse until it is stopped.
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REV4A_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
-
+DATA_DIR="${REV4A_DATA_DIR:-${HOME}/.config/rev4a}"
+PRE_DIR="${HOME}/rev4a-backups"
 ARCHIVE="${1:-}"
 
 if [[ -z "$ARCHIVE" ]]; then
-  echo "Usage: sudo bash scripts/restore.sh <backup-archive.tar.gz>"
+  echo "Usage: bash scripts/restore.sh <rev4a-backup-….tar.gz>"
   echo ""
-  echo "Available backups:"
-  if [[ -d "${REV4A_ROOT}/backups" ]]; then
-    ls -lh "${REV4A_ROOT}/backups/"*.tar.gz 2>/dev/null || echo "  (none)"
-  else
-    echo "  (no backups directory)"
-  fi
+  echo "Backups in ~/rev4a-backups:"
+  ls -lh "${HOME}/rev4a-backups/"rev4a-backup-*.tar.gz 2>/dev/null || echo "  (none)"
   exit 1
 fi
-
 if [[ ! -f "$ARCHIVE" ]]; then
-  echo "Error: Archive not found: $ARCHIVE"
+  echo "Error: archive not found: $ARCHIVE" >&2
   exit 1
 fi
+if [[ ! -d "$DATA_DIR" ]]; then
+  # Restoring into a directory nothing reads would "succeed" and change nothing. On a new
+  # machine, create it first — the check is only there to catch a wrong path.
+  echo "Error: Rev4a data directory not found: $DATA_DIR" >&2
+  echo "Set REV4A_DATA_DIR to the directory Rev4a uses, or create it first on a new machine." >&2
+  exit 1
+fi
+# The real directory: when the path is a symlink, the swap below replaces its target.
+DATA_DIR="$(cd "$DATA_DIR" && pwd -P)"
 
-echo "Restoring Rev4a from: $ARCHIVE"
-echo ""
-
-# Create pre-restore backup of current state
-PRE_DIR="${REV4A_ROOT}/backups/.pre-restore-$(date -u +%Y%m%d-%H%M%S)"
-mkdir -p "$PRE_DIR"
-
-echo "Saving current state to: $PRE_DIR"
-cd "$REV4A_ROOT"
-for f in data/*.db data/*.db-shm data/*.db-wal data/provider-keys.json data/agents-token.json models.config.json .env; do
-  if [[ -f "$f" ]]; then
-    cp --parents "$f" "$PRE_DIR/" 2>/dev/null || true
-  fi
-done
+# Refuse an archive that is not a backup.sh archive of a Rev4a data directory. The listing
+# is read whole: `grep -q` would stop reading early and, with pipefail, turn tar's SIGPIPE
+# into a false refusal on large archives.
+LISTING="$(tar -tvzf "$ARCHIVE")"
+if ! grep -E '[[:space:]]\./(\.env|data/)' <<<"$LISTING" >/dev/null; then
+  echo "Error: $ARCHIVE does not look like a Rev4a data backup (no .env or data/ inside)." >&2
+  exit 1
+fi
+# backup.sh never stores links; a link in the archive could point outside the data directory.
+if grep -E '^[lh]' <<<"$LISTING" >/dev/null; then
+  echo "Error: $ARCHIVE contains symbolic or hard links — refusing to restore it." >&2
+  exit 1
+fi
 
-# Stop Rev4a services before restore
-if systemctl is-active --quiet rev4a.service 2>/dev/null; then
-  echo "Stopping Rev4a services..."
-  sudo systemctl stop rev4a.service
-  echo "Services stopped."
+if command -v systemctl >/dev/null 2>&1 && systemctl is-active --quiet rev4a.service 2>/dev/null; then
+  echo "Stopping rev4a.service..."
+  systemctl stop rev4a.service
+  STOPPED=1
+fi
+if pgrep -f 'rev4a(\.js)? serve' >/dev/null 2>&1; then
+  echo "Error: Rev4a is running (rev4a serve). Stop it first: it keeps the databases open." >&2
+  exit 1
 fi
 
-# Extract the archive
-echo "Extracting backup..."
-tar -xzf "$ARCHIVE" -C "$REV4A_ROOT"
+umask 077
+mkdir -p "$PRE_DIR"
+PRE="${PRE_DIR}/rev4a-pre-restore-$(date -u +%Y%m%d-%H%M%S).tar.gz"
+echo "Archiving the current state first: $PRE"
+set -o noclobber
+tar -C "$DATA_DIR" -czf - . > "$PRE"
+set +o noclobber
+chmod 600 "$PRE"
 
-# Fix permissions
-chmod 600 "${REV4A_ROOT}/.env" 2>/dev/null || true
-chmod 600 "${REV4A_ROOT}/data/provider-keys.json" 2>/dev/null || true
-chmod 600 "${REV4A_ROOT}/data/agents-token.json" 2>/dev/null || true
+# Extract next to the data directory, then swap: a failed extraction leaves the current
+# data untouched, and nothing from the current state survives into the restored one.
+PARENT="$(dirname "$DATA_DIR")"
+STAGE="$(mktemp -d "${PARENT}/.rev4a-restore.XXXXXX")"
+trap 'rm -rf "$STAGE"' EXIT
+echo "Restoring into: $DATA_DIR"
+tar -C "$STAGE" --no-same-owner -xzf "$ARCHIVE"
+find "$STAGE" -type d -exec chmod 700 {} +
+[[ -f "$STAGE/.env" ]] && chmod 600 "$STAGE/.env"
+[[ -d "$STAGE/data" ]] && find "$STAGE/data" -type f -exec chmod 600 {} +
+
+OLD="${PARENT}/.rev4a-replaced.$$"
+mv "$DATA_DIR" "$OLD"
+mv "$STAGE" "$DATA_DIR"
+trap - EXIT
+rm -rf "$OLD"
 
 echo ""
-echo "=============================================="
-echo "  Restore complete!"
-echo "=============================================="
-echo ""
-echo "  Previous state saved to: ${PRE_DIR}"
-echo ""
-echo "  To restart Rev4a:"
-echo "    sudo systemctl start rev4a.service"
-echo ""
-echo "  If something went wrong, restore previous state from:"
-echo "    ${PRE_DIR}"
-echo "=============================================="
+echo "Restore complete."
+echo "The previous state is in: $PRE"
+[[ -n "${STOPPED:-}" ]] && echo "Start Rev4a again: systemctl start rev4a.service"
+exit 0