@gamaze/hicortex 0.18.3 → 0.19.0

package/README.md

@@ -319,6 +319,66 @@ If no LLM is configured, the server starts in **recall-only mode**: search, less
 
 Canonical location: `~/.hicortex/hicortex.db`. The OC plugin no longer owns its own database — it is a thin client to the server. Previously, OC installations at `~/.openclaw/data/hicortex.db` were migrated automatically on upgrade; this migration path remains in the server's `resolveDbPath` for any pre-0.10.0 installations.
 
+## Backups
+
+The live DB runs with WAL on, so a plain `cp`/`tar` of `hicortex.db` is **torn** (the `-wal` file holds uncommitted pages → a copy that looks fine until you restore it). `hicortex backup` uses SQLite's online-backup API (`db.backup()`) to fold the WAL into a single consistent snapshot, then packages it with the hand-edited identity layer and capture state into one `tar.gz`.
+
+**Run a backup:**
+
+```bash
+npx @gamaze/hicortex backup
+# → writes ~/.hicortex/backups/hicortex-<ISO>.tar.gz
+```
+
+The artifact contains the irreplaceable data only: `hicortex.db`, the whole `identity/` tree (global + per-agent `agents/<id>/`), `state.json`, and `capture-cursors.json`. It deliberately **excludes** `config.json` (secrets: `authToken`/`llmApiKey`), `models/`, logs, and the `backups/` dir itself.
+
+**Offsite copy via a hook.** Set `backupCommand` in `~/.hicortex/config.json` and it runs after every backup with the artifact path appended as the last arg (cloud creds + alerting stay in your wrapper, out of the product):
+
+```jsonc
+{
+  "backupDir": "/mnt/backups/hicortex",          // optional; default <home>/backups
+  "backupCommand": "rclone copyto"               // invoked: rclone copyto <path> remote:hicortex/
+}
+```
+
+A failing, missing, or timed-out hook (5 min) reports failure and **never throws** — the artifact is already on disk; only the offsite copy didn't land. Both `hicortex backup` (non-zero exit) and the nightly stage surface the failure.
+
+**Stream to stdout** (pipe to any offsite transport, no on-disk artifact):
+
+```bash
+npx @gamaze/hicortex backup --stdout | rclone rcat remote:hicortex/$(date -I).tar.gz
+```
+
+`--stdout` is mutually exclusive with `--out`/`backupDir`.
+
+**Nightly stage.** Every full nightly run (not `--capture-only`) takes a backup automatically after consolidation and runs the hook if configured. Backup failure does NOT fail the nightly — capture + consolidation have already succeeded; the failure surfaces as `backupOk:false` in the dashboard snapshot and telemetry for alerting.
+
+**Restore (manual):**
+
+```bash
+# 0. Stop the server (so no writer is touching the DB).
+# 1. Save a current artifact (if the server is still up):
+npx @gamaze/hicortex backup --stdout > save.tar.gz
+# 2. Extract it:
+mkdir /tmp/restore && tar xzf save.tar.gz -C /tmp/restore
+# 3. Drop the snapshot into place + restore the identity/state files.
+#    IMPORTANT: restore the DB to the path the server ACTUALLY uses — check
+#    `hicortex status` for the resolved DB path. It is ~/.hicortex/hicortex.db
+#    by default, BUT if you set HICORTEX_DB_PATH or run a hosted tenant (where
+#    the DB lives at /data/hicortex.db), restore there instead:
+DB=~/.hicortex/hicortex.db          # ← verify with `hicortex status`
+cp /tmp/restore/hicortex.db "$DB"
+cp -r /tmp/restore/identity/* "$(dirname "$DB")/identity/" 2>/dev/null || \
+  cp -r /tmp/restore/identity/* ~/.hicortex/identity/
+cp /tmp/restore/state.json "$(dirname "$DB")/state.json" 2>/dev/null || \
+  cp /tmp/restore/state.json ~/.hicortex/state.json
+cp /tmp/restore/capture-cursors.json "$(dirname "$DB")/capture-cursors.json" 2>/dev/null || \
+  cp /tmp/restore/capture-cursors.json ~/.hicortex/capture-cursors.json
+# 4. Restart the server and verify (hicortex status).
+```
+
+**Restore drill — required before relying on this.** A backup you haven't restored is unverified. Before the first paying customer (and periodically after), run the full restore procedure above into a throwaway `HICORTEX_HOME` and confirm the server opens the DB, recall returns seeded memories, and the identity layer renders. A future `hicortex restore` command is planned; the manual drill is the bar for now.
+
 ## Development
 
 ```bash

package/assets/dashboard.html

@@ -105,7 +105,7 @@
     color: var(--text); font-weight: 600; text-decoration: none;
     letter-spacing: 0.02em;
   }
-  .hc-nav-links { margin-left: auto; display: flex; align-items: center; gap: 16px; }
+  .hc-nav-links { display: flex; align-items: center; gap: 16px; }
   .hc-nav-links a {
     color: var(--text-dim); text-decoration: none; transition: color 0.12s;
   }
@@ -114,6 +114,13 @@
   .hc-nav-disabled {
     color: var(--text-dim); opacity: 0.4; cursor: not-allowed; user-select: none;
   }
+  /* Account identity (hosted): "Name · Org" + a plan pill, far right (the
+     links sit LEFT next to the logo; this element owns the right side). */
+  .hc-nav-account { margin-left: auto; display: inline-flex; align-items: center; gap: 8px; color: var(--text); }
+  .hc-nav-account .plan {
+    display: inline-block; padding: 1px 8px; border-radius: 10px;
+    background: rgba(128,128,128,0.18); font-size: 11px; color: var(--text-dim);
+  }
 </style>
 </head>
 <body>
@@ -125,6 +132,7 @@
     <a href="/identity/ui">Identity</a>
     <span class="hc-nav-disabled" title="Coming soon — #250">Self-improvement</span>
   </div>
+  <span id="nav-account" class="hc-nav-account"></span>
 </nav>
 <h1>Hicortex — memory dashboard</h1>
 <div class="sub">View-only analytics. All metrics derived from the live corpus + nightly snapshots.</div>
@@ -219,6 +227,16 @@ async function fetchData(path) {
   if (token) headers["Authorization"] = "Bearer " + token;
   const resp = await fetch(path, { headers });
   if (resp.status === 401) {
+    // Offer the hosted Google login when the router has auth configured
+    // (bearer-only servers answer 503 on /auth/*); the raw token prompt
+    // stays for power users and self-hosted installs.
+    try {
+      const probe = await fetch("/auth/google/start", { redirect: "manual" });
+      if (probe.status !== 503 && confirm("Sign in with Google? (Cancel to enter a token instead)")) {
+        location.href = "/auth/google/start";
+        throw new Error("redirecting to login");
+      }
+    } catch (e) { if (String(e.message).includes("redirecting")) throw e; }
     token = prompt("Hicortex auth token:") || "";
     if (token) {
       localStorage.setItem(TOKEN_KEY, token);
@@ -230,6 +248,32 @@ async function fetchData(path) {
   return resp.json();
 }
 
+
+// Upgrade → Stripe Checkout (#298). Annual is the default plan (pricing
+// decision: annual pre-selected, "pay for 9, get 12"). Failures alert generic.
+function wireUpgrade() {
+  const btn = $("nav-upgrade");
+  if (!btn) return;
+  btn.addEventListener("click", async () => {
+    btn.disabled = true;
+    try {
+      const resp = await fetch("/stripe/checkout", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ plan: "annual" }),
+      });
+      if (resp.status === 401) { location.href = "/auth/google/start"; return; }
+      const body = await resp.json().catch(() => ({}));
+      if (resp.ok && body.url) { location.href = body.url; return; }
+      alert("Checkout unavailable (" + resp.status + ") — try again later.");
+      btn.disabled = false;
+    } catch {
+      alert("Checkout unreachable — try again later.");
+      btn.disabled = false;
+    }
+  });
+}
+
 // ---------------------------------------------------------------------------
 // State
 // ---------------------------------------------------------------------------
@@ -282,9 +326,10 @@ function renderHeadline(h) {
   }
   // LLM tokens this period (#246): hidden when `used` is 0 (no metered run yet
   // — nothing to show). When capped (cap > 0), render a usage bar with the
-  // percentage; amber at ≥85%, red at ≥100%. When uncapped (self-hosted
-  // default), show just the count. Both shapes include "this month" so the
-  // billing-period framing is uniform.
+  // percentage; amber at ≥85%, red at ≥100% — the same gauge pattern as the
+  // soft-cap capacity stat. When uncapped (self-hosted default), show just the
+  // count (no denominator → no bar, matching the digest section's convention).
+  // The total includes distill + consolidation since #287 (always-recorded).
   let tokenStat = "";
   const tok = h.tokens;
   if (tok && tok.used > 0) {
@@ -295,10 +340,10 @@ function renderHeadline(h) {
       const near = pct >= 85 && !over;
       const barColor = over ? "var(--bad, #e05555)" : near ? "var(--warn, #e0b055)" : "var(--ok, #61c98f)";
       tokenStat = `
-        <div class="stat" style="flex-basis:240px;">
+        <div class="stat">
           <div class="v" style="font-size:18px;">${escapeHtml(usedStr)} <span class="muted" style="font-size:13px;">/ ${escapeHtml(formatTokens(tok.cap))}</span></div>
           <div class="l">LLM tokens this month ${over ? "(over cap)" : ""}</div>
-          <div style="margin-top:6px;height:6px;background:rgba(128,128,128,0.2);border-radius:3px;overflow:hidden;">
+          <div style="margin-top:6px;max-width:360px;height:6px;background:rgba(128,128,128,0.2);border-radius:3px;overflow:hidden;">
             <div style="width:${pct.toFixed(1)}%;height:100%;background:${barColor};"></div>
           </div>
         </div>`;
@@ -313,7 +358,7 @@ function renderHeadline(h) {
   $("headline").innerHTML = `
     <div class="stat"><div class="v">${h.total_memories}</div><div class="l">Total memories</div></div>
     <div class="stat"><div class="v">${ups}</div><div class="l">Uses per showing (headline)</div></div>
-    <div class="stat"><div class="v warn">${h.cold_count}</div><div class="l">Cold long-tail (never shown/used)</div></div>
+    <div class="stat"><div class="v warn">${h.cold_count}</div><div class="l">Cold long-tail (never recalled)</div></div>
     ${capStat}
     ${tokenStat}
   `;
@@ -621,6 +666,54 @@ function escapeHtml(s) {
   })[c]);
 }
 
+// ---------------------------------------------------------------------------
+// Render: account identity (hosted) — "Name · Org" + plan pill in the nav.
+// Rendered ONLY when at least one field is non-null (all-null = self-hosted
+// default → no element, no empty pill). Values are operator-set config, but
+// escapeHtml anyway (same posture as every other innerHTML sink here).
+// ---------------------------------------------------------------------------
+function renderAccount(a) {
+  const host = $("nav-account");
+  // Trial users (no plan) get the Upgrade pill — the checkout entry (#298 drill,
+  // #299's first brick). Session-authenticated: the browser's hicortex-session
+  // cookie rides this same-origin fetch; the router maps it to the tenant.
+  const upgrade =
+    a && a.plan === null
+      ? ' <button id="nav-upgrade" type="button" style="background:var(--accent);color:#fff;border:none;border-radius:4px;padding:4px 12px;font:inherit;font-size:13px;cursor:pointer;">Upgrade</button>'
+      : "";
+  if (!a || (a.name === null && a.org === null && a.plan === null)) {
+    host.innerHTML = upgrade || "";
+    if (upgrade) wireUpgrade();
+    return;
+  }
+  const who = [a.name, a.org]
+    .filter((s) => typeof s === "string" && s !== "")
+    .map(escapeHtml)
+    .join(' <span class="muted">·</span> ');
+  const plan = typeof a.plan === "string" && a.plan !== ""
+    ? `<span class="plan">${escapeHtml(a.plan)}</span>`
+    : "";
+  host.innerHTML = (who ? who + " " : "") + plan + upgrade;
+  if (upgrade) wireUpgrade();
+}
+
+// Account data source: the dedicated lightweight GET /account (same shape as
+// the account block /dashboard/data still carries — kept there for the stable
+// payload contract). Fetched independently so the nav renders fail-soft and
+// the code path matches /viz + /identity/ui: 401 or fetch error leaves the
+// span empty, never blocks the page. Runs AFTER the main fetch so a 401
+// token prompt issued by fetchData() has already updated `token`.
+async function loadAccount() {
+  const headers = {};
+  if (token) headers["Authorization"] = "Bearer " + token;
+  try {
+    const resp = await fetch("/account", { headers });
+    if (!resp.ok) return; // fail-soft — the nav pill is never worth an error
+    const data = await resp.json();
+    renderAccount(data.account);
+  } catch (e) { /* network error → leave the span empty */ }
+}
+
 // ---------------------------------------------------------------------------
 // Load + wire controls
 // ---------------------------------------------------------------------------
@@ -636,6 +729,9 @@ async function load() {
     return;
   }
   renderHeadline(state.headline);
+  loadAccount();
+  // Same range-filtered series as growth/composition — the chart re-renders on
+  // every range switch because the range select triggers this full reload.
   renderGrowth(state.series, $("split").value, $("filter").value);
   renderComposition(state.composition, compKey);
   renderDigest(state.digest, state.headline.tokens);

package/assets/identity.html

@@ -179,11 +179,18 @@
     font-size: 14px;
   }
   .hc-nav-logo { color: var(--text); font-weight: 600; text-decoration: none; letter-spacing: 0.02em; }
-  .hc-nav-links { margin-left: auto; display: flex; align-items: center; gap: 16px; }
+  .hc-nav-links { display: flex; align-items: center; gap: 16px; }
   .hc-nav-links a { color: var(--text-dim); text-decoration: none; transition: color 0.12s; }
   .hc-nav-links a:hover { color: var(--accent); }
   .hc-nav-links a[data-nav-active] { color: var(--text); }
   .hc-nav-disabled { color: var(--text-dim); opacity: 0.4; cursor: not-allowed; user-select: none; }
+  /* Account identity (hosted): name + plan pill, far right of the nav (the
+     links sit LEFT next to the logo; this element owns the right side). */
+  .hc-nav-account { margin-left: auto; display: inline-flex; align-items: center; gap: 8px; color: var(--text); }
+  .hc-nav-account .plan {
+    display: inline-block; padding: 1px 8px; border-radius: 10px;
+    background: rgba(128,128,128,0.18); font-size: 11px; color: var(--text-dim);
+  }
 </style>
 </head>
 <body>
@@ -195,6 +202,7 @@
     <a href="/identity/ui" data-nav-active>Identity</a>
     <span class="hc-nav-disabled" title="Coming soon — #250">Self-improvement</span>
   </div>
+  <span id="nav-account" class="hc-nav-account"></span>
 </nav>
 <header>
   <h1>Hicortex — identity</h1>
@@ -243,6 +251,7 @@
        Run <code>hicortex status</code> on the server to get it.</p>
     <input type="password" id="token-input" placeholder="hctx-…" autocomplete="off">
     <button class="btn" id="token-submit">Connect</button>
+    <a id="google-login" href="/auth/google/start" style="display:none;margin-top:10px;">Sign in with Google</a>
     <div id="token-err">Still unauthorized — check the token.</div>
   </div>
 </div>
@@ -304,6 +313,37 @@
     return h;
   }
 
+  // =========================================================================
+  // Account identity in the nav — GET /account (the lightweight endpoint the
+  // dashboard payload also carries). Fail-soft: 401/fetch error leaves the
+  // span empty (the main load() owns the 401 token prompt); an all-null
+  // account (self-hosted default) renders nothing. Built with textContent
+  // only — this page never uses innerHTML for server-derived values.
+  // =========================================================================
+  function renderAccount(a) {
+    var host = document.getElementById("nav-account");
+    if (!host) return;
+    host.textContent = "";
+    if (!a || (a.name === null && a.org === null && a.plan === null)) return;
+    var who = [a.name, a.org].filter(function (s) { return typeof s === "string" && s !== ""; });
+    who.forEach(function (s, i) {
+      if (i > 0) host.appendChild(document.createTextNode(" · "));
+      host.appendChild(document.createTextNode(s));
+    });
+    if (typeof a.plan === "string" && a.plan !== "") {
+      var pill = document.createElement("span");
+      pill.className = "plan";
+      pill.textContent = a.plan;
+      host.appendChild(pill);
+    }
+  }
+  function loadAccount() {
+    fetch("/account", { headers: authHeaders() })
+      .then(function (resp) { return resp.ok ? resp.json() : null; })
+      .then(function (data) { if (data) renderAccount(data.account); })
+      .catch(function () { /* leave the span empty — nav is never worth an error */ });
+  }
+
   // =========================================================================
   // DOM refs
   // =========================================================================
@@ -615,6 +655,11 @@
     setMsg("", "dim");
     overlay.classList.add("open");
     tokenInput.focus();
+    // Offer the hosted Google login only when the fronting router has auth
+    // configured (bearer-only servers answer 503 on /auth/*).
+    fetch("/auth/google/start", { redirect: "manual" })
+      .then(function (r) { if (r.status !== 503) document.getElementById("google-login").style.display = "block"; })
+      .catch(function () {});
   }
   function submitToken() {
     var v = tokenInput.value.trim();
@@ -629,6 +674,7 @@
       var next = afterAuth || load;
       afterAuth = null;
       next();
+      loadAccount(); // the initial fail-soft attempt left the nav pill empty on 401
     }).catch(function () { tokenErr.style.display = "block"; });
   }
 
@@ -656,6 +702,7 @@
   tokenInput.addEventListener("keydown", function (e) { if (e.key === "Enter") submitToken(); });
 
   load();
+  loadAccount();
 })();
 </script>
 </body>

package/assets/viz.html

@@ -71,6 +71,14 @@
   .hc-nav-links a:hover { color: var(--accent); }
   .hc-nav-links a[data-nav-active] { color: var(--text); }
   .hc-nav-disabled { color: var(--text-dim); opacity: 0.4; cursor: not-allowed; user-select: none; }
+  /* Account identity (hosted): name + plan pill at the far right. Here the
+     topbar's #meta keeps margin-left:auto (it pushes the whole right group —
+     meta + account); the account span is simply the last item. */
+  .hc-nav-account { display: inline-flex; align-items: center; gap: 8px; color: var(--text); }
+  .hc-nav-account .plan {
+    display: inline-block; padding: 1px 8px; border-radius: 10px;
+    background: rgba(128,128,128,0.18); font-size: 11px; color: var(--text-dim);
+  }
 
   /* ---- left control panel ---- */
   #panel {
@@ -245,13 +253,14 @@
 
 <div id="topbar">
   <h1 class="hc-nav-logo"><a href="/dashboard" style="color:inherit;text-decoration:none">Hicortex</a></h1>
-  <span id="meta"></span>
   <nav class="hc-nav-links">
     <a href="/dashboard">Dashboard</a>
     <a href="/viz" data-nav-active>Graph</a>
     <a href="/identity/ui">Identity</a>
     <span class="hc-nav-disabled" title="Coming soon — #250">Self-improvement</span>
   </nav>
+  <span id="meta"></span>
+  <span id="nav-account" class="hc-nav-account"></span>
 </div>
 
 <div id="panel">
@@ -328,6 +337,7 @@
        Run <code>hicortex status</code> on the server to get the token.</p>
     <input type="password" id="token-input" placeholder="hctx-…" autocomplete="off">
     <button id="token-submit">Connect</button>
+    <a id="google-login" href="/auth/google/start" style="display:none;margin-top:10px;">Sign in with Google</a>
     <div class="err" id="token-err">Still unauthorized — check the token.</div>
   </div>
 </div>
@@ -374,6 +384,39 @@
     });
   });
 
+  // =========================================================================
+  // Account identity in the nav — GET /account (the lightweight endpoint, the
+  // same shape the dashboard payload carries). Fail-soft: 401/fetch error
+  // leaves the span empty (fetchGraph owns the 401 token prompt); an all-null
+  // account (self-hosted default) renders nothing. textContent only — this
+  // page uses innerHTML exclusively for the escaped 3D-force-graph tooltips.
+  // =========================================================================
+  function renderAccount(a) {
+    var host = document.getElementById("nav-account");
+    if (!host) return;
+    host.textContent = "";
+    if (!a || (a.name === null && a.org === null && a.plan === null)) return;
+    var who = [a.name, a.org].filter(function (s) { return typeof s === "string" && s !== ""; });
+    who.forEach(function (s, i) {
+      if (i > 0) host.appendChild(document.createTextNode(" · "));
+      host.appendChild(document.createTextNode(s));
+    });
+    if (typeof a.plan === "string" && a.plan !== "") {
+      var pill = document.createElement("span");
+      pill.className = "plan";
+      pill.textContent = a.plan;
+      host.appendChild(pill);
+    }
+  }
+  function loadAccount() {
+    var headers = {};
+    if (token) headers["Authorization"] = "Bearer " + token;
+    fetch("/account", { headers: headers })
+      .then(function (resp) { return resp.ok ? resp.json() : null; })
+      .then(function (data) { if (data) renderAccount(data.account); })
+      .catch(function () { /* leave the span empty — nav is never worth an error */ });
+  }
+
   // =========================================================================
   // DOM references
   // =========================================================================
@@ -590,6 +633,12 @@
     hideStatus();
     overlay.classList.add("open");
     document.getElementById("token-input").focus();
+    // Offer the hosted Google login only when the fronting router has auth
+    // configured — a bearer-only/self-hosted server answers 503 on /auth/*.
+    // (redirect:"manual" makes the 302 an opaque redirect with status 0.)
+    fetch("/auth/google/start", { redirect: "manual" })
+      .then((r) => { if (r.status !== 503) document.getElementById("google-login").style.display = "block"; })
+      .catch(() => {});
   }
   document.getElementById("token-submit").addEventListener("click", submitToken);
   document.getElementById("token-input").addEventListener("keydown", function (e) {
@@ -609,6 +658,7 @@
       }
       overlay.classList.remove("open");
       fetchGraph();
+      loadAccount(); // the initial fail-soft attempt left the nav pill empty on 401
     }).catch(function () {
       document.getElementById("token-err").style.display = "block";
     });
@@ -1162,6 +1212,7 @@
     document.body.classList.toggle("mode-2d", mode === "2d");
     syncModeControl();
     fetchGraph();
+    loadAccount();
   }
   if (document.readyState === "complete" || document.readyState === "interactive") {
     // DOM already parsed — but deferred scripts may still be pending; queue

package/dist/backup.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Backup mechanism — a transactionally-consistent snapshot of the irreplaceable
+ * data (#6, Phase 0B).
+ *
+ * For a product whose value is accumulated memory, silent backup loss is
+ * existential (spec §8). The live DB runs with WAL on, so a plain `cp`/`tar` of
+ * `hicortex.db` is torn (the `-wal` file holds uncommitted pages → a copy that
+ * looks fine until you restore it). This module uses better-sqlite3's native
+ * `db.backup(path)` — the SQLite online-backup API, already proven in `dedup.ts`
+ * — which folds the WAL into a single self-contained, consistent snapshot, then
+ * packages it with the hand-edited identity layer + capture state into one
+ * `tar.gz` artifact the operator ships offsite.
+ *
+ * Backup set (the irreplaceable data under HICORTEX_HOME):
+ *   - `hicortex.db`            — via db.backup() to a temp snapshot (WAL-safe)
+ *   - `identity/` (whole tree) — global `*.md` AND per-agent `agents/<id>/*.md`
+ *   - `context/` (legacy)      — additive fallback (identity-store.ts migrate)
+ *   - `state.json`             — cursors/tier/timestamps (state.ts)
+ *   - `capture-cursors.json`   — per-session capture positions (capture-cursors.ts)
+ *
+ * Excluded by design:
+ *   - `config.json`            — secrets (authToken/llmApiKey); re-creatable via init
+ *   - `backups/`               — output dir (never back up the backups)
+ *   - logs (`nightly.log`, `server*.log`) — re-creatable, noisy, not data
+ *   - `models/`                — embedder cache (re-downloadable)
+ *   - `capture.lock`           — a transient single-flight lock, not state
+ *   - `.allow-localhost-bypass` — a hosted fail-closed marker, not data
+ *
+ * Vectors: `db.backup()` copies the vec0 shadow tables (they're real tables).
+ * If a restore ever finds them missing, vectors regenerate from
+ * `memories.content` via the embedder — non-destructive either way.
+ */
+import type Database from "better-sqlite3";
+export interface CreateBackupOptions {
+    /** Open live DB handle (caller manages lifetime). Backed up via db.backup(). */
+    db: Database.Database;
+    /** HICORTEX_HOME — the dir whose irreplaceable files are packaged. */
+    home: string;
+    /**
+     * Explicit output file path (a tar.gz). Overrides `outDir`/default. Mutually
+     * exclusive with `stdout`.
+     */
+    outFile?: string;
+    /**
+     * Output directory. Defaults to `<home>/backups`. Ignored when `outFile` is
+     * set. Configurable via `config.backupDir`.
+     */
+    outDir?: string;
+    /**
+     * Stream the tar.gz to `process.stdout` instead of writing a file (the
+     * offsite pattern: `hicortex backup --stdout | rclone rcat ...`). Mutually
+     * exclusive with `outFile`/`outDir`.
+     */
+    stdout?: boolean;
+}
+export interface CreateBackupResult {
+    /** Absolute path of the written artifact; undefined when `stdout:true`. */
+    path?: string;
+    /** Compressed artifact size in bytes (gzip output). */
+    bytes: number;
+    /** Number of files packaged (DB snapshot + identity tree + state files). */
+    files: number;
+}
+export interface BackupHookResult {
+    ok: boolean;
+    /** Process exit code when the hook ran and exited (0 on success); undefined
+     *  when the command was missing, couldn't spawn (ENOENT), or timed out. */
+    exitCode?: number;
+}
+/**
+ * Create a backup artifact. Snapshots the live DB via the online-backup API,
+ * packages it with the identity tree + state into a single `tar.gz`, and writes
+ * it to `outFile` (default `<home>/backups/hicortex-<ISO>.tar.gz`) or streams
+ * to stdout. Returns `{ path?, bytes, files }`.
+ *
+ * Never partially writes a file artifact on failure: if the tar pipeline errors
+ * mid-stream the (likely-truncated) file is removed before the error propagates,
+ * so a stale half-backup is never left on disk to masquerade as a good one.
+ */
+export declare function createBackup(opts: CreateBackupOptions): Promise<CreateBackupResult>;
+/**
+ * Run the operator's post-backup offsite hook. The configured `command` is split
+ * on whitespace and the artifact path appended as the LAST arg (e.g.
+ * `rclone copyto <path> remote:hicortex/` → `["rclone","copyto",path,...]`).
+ * Cloud creds + active alerting stay in the operator's wrapper, out of the
+ * product. NEVER throws — a hook failure is reported as `{ ok:false }` so the
+ * nightly continues (capture/consolidation already succeeded; the backup itself
+ * is on disk). 5 min timeout so a hung upload can't hang the nightly.
+ *
+ * Whitespace-split caveat: commands with quoted args containing spaces should
+ * be a wrapper script (`/etc/hicortex/offsite.sh`), not a one-liner — the split
+ * here is deliberately dumb to avoid re-implementing a shell parser.
+ */
+export declare function runBackupHook(artifactPath: string, command: string | undefined): Promise<BackupHookResult>;
+export interface BackupCliOptions {
+    /** `--out <dir>` — output directory (the artifact is auto-named). Takes precedence over `config.backupDir`. Mutually exclusive with stdout. */
+    outDir?: string;
+    /** `--stdout` — stream the tar.gz to process.stdout (offsite pipe pattern). */
+    stdout?: boolean;
+}
+/**
+ * Run the `hicortex backup` CLI command. Loads config (for `backupDir` /
+ * `backupCommand`), opens the DB, writes (or streams) the artifact, runs the
+ * offsite hook when configured, prints the artifact path, and exits non-zero on
+ * any failure (a failed backup must be visible — `cron`/launchd surfaces it).
+ */
+export declare function runBackupCli(opts: BackupCliOptions): Promise<void>;