talon-agent 5.26.1 → 5.26.3

package/src/core/backup/boot/version-checkpoint.ts

@@ -0,0 +1,199 @@
+/**
+ * The boot-time upgrade checkpoint: a pinned snapshot taken the first time
+ * a new version boots, before anything in that version touches the data.
+ *
+ * `/update` on a git checkout takes its own pre-update checkpoint, but
+ * that is the only install shape that does. A Docker or TrueNAS update is
+ * a new image started against the old volume; npm and binary installs are
+ * the same story. The first code of the new version to run is this boot,
+ * so this boot is where the safety net has to be.
+ *
+ * The last version that booted is kept in a small marker file beside the
+ * Talon home's config (not in the database: the check runs before the
+ * database is opened, and a restore that rolls the database back should
+ * not also roll back the fact that a newer version ran). The database is
+ * captured through a read-only handle, so the checkpoint holds it exactly
+ * as the previous version left it — before this boot's schema setup.
+ *
+ * Never throws and never blocks boot: a daemon that refuses to start is
+ * worse than one that starts carefully. A failure is logged loudly,
+ * raised as a critical operator alert, and reported to the caller so the
+ * boot can skip its destructive steps. The marker is only advanced on
+ * success, so the next boot tries again.
+ */
+
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { dirs } from "../../../util/paths.js";
+import { log, logError } from "../../../util/log.js";
+import {
+  databasePath,
+  snapshotDatabase,
+  snapshotSqliteFile,
+} from "../../../storage/backup/index.js";
+import { raiseAlert } from "../../frontend-runtime/alerts.js";
+import { buildSnapshot } from "../snapshot.js";
+import type { BackupSettings } from "../types.js";
+
+/** File (under the Talon home) recording the last version that booted. */
+const BOOT_VERSION_MARKER = "last-boot-version.json";
+
+/** Alert key for a failed upgrade checkpoint. */
+export const UPGRADE_CHECKPOINT_ALERT = "backup.upgrade-checkpoint";
+
+export type VersionCheckpointResult =
+  /** Same version as last boot — nothing to do. */
+  | { status: "unchanged"; version: string }
+  /** No marker and no database: a brand-new install, nothing to protect. */
+  | { status: "fresh-install"; version: string }
+  /** Version changed but `backup.checkpointBeforeUpdate` is off. */
+  | { status: "disabled"; from: string; to: string }
+  | { status: "taken"; id: string; from: string; to: string }
+  | { status: "failed"; from: string; to: string; error: string };
+
+type MarkerFile = { version: string; bootedAt: string };
+
+export type VersionCheckpointOptions = {
+  settings: BackupSettings;
+  /** The version now booting. */
+  version: string;
+  /** Talon home; tests point this at a scratch directory. */
+  home?: string;
+  /** The database file to capture; defaults to the daemon's. */
+  databaseFile?: string;
+  /** Snapshot builder — a test seam. */
+  build?: typeof buildSnapshot;
+  /** Operator alert — a test seam. */
+  alert?: typeof raiseAlert;
+  /** Clock, for tests. */
+  now?: Date;
+};
+
+export function bootVersionMarkerPath(home: string = dirs.root): string {
+  return join(home, BOOT_VERSION_MARKER);
+}
+
+/** The last version that booted, or null when none is recorded (or readable). */
+export async function readLastBootVersion(
+  home: string = dirs.root,
+): Promise<string | null> {
+  try {
+    const raw = await readFile(bootVersionMarkerPath(home), "utf8");
+    const parsed = JSON.parse(raw) as Partial<MarkerFile>;
+    return typeof parsed.version === "string" && parsed.version
+      ? parsed.version
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeLastBootVersion(
+  home: string,
+  version: string,
+  now: Date,
+): Promise<void> {
+  const path = bootVersionMarkerPath(home);
+  const marker: MarkerFile = { version, bootedAt: now.toISOString() };
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    const temp = `${path}.tmp`;
+    await writeFile(temp, `${JSON.stringify(marker, null, 2)}\n`, {
+      mode: 0o600,
+    });
+    await rename(temp, path);
+  } catch (err) {
+    // Worst case the next boot takes one more checkpoint than needed.
+    logError("backup", `Could not record boot version ${version}`, err);
+  }
+}
+
+/**
+ * Copy the database through a read-only handle; fall back to the regular
+ * (opening) copy when SQLite refuses a read-only open, e.g. a WAL file
+ * whose shared-memory index can't be created on a read-only handle.
+ */
+function copyDatabaseReadOnly(dbFile: string): (dest: string) => void {
+  return (dest) => {
+    try {
+      snapshotSqliteFile(dbFile, dest);
+    } catch (err) {
+      logError(
+        "backup",
+        "Read-only database copy failed; copying through the daemon handle",
+        err,
+      );
+      snapshotDatabase(dest);
+    }
+  };
+}
+
+/**
+ * Take a pinned `pre-upgrade <old>→<new>` checkpoint when the version
+ * booting differs from the last one that did. See the module comment.
+ */
+export async function checkpointOnVersionChange(
+  options: VersionCheckpointOptions,
+): Promise<VersionCheckpointResult> {
+  const home = options.home ?? dirs.root;
+  const now = options.now ?? new Date();
+  const to = options.version;
+  const previous = await readLastBootVersion(home);
+  if (previous === to) return { status: "unchanged", version: to };
+
+  const dbFile = options.databaseFile ?? databasePath();
+  const hasDatabase = existsSync(dbFile);
+  if (previous === null && !hasDatabase) {
+    await writeLastBootVersion(home, to, now);
+    return { status: "fresh-install", version: to };
+  }
+
+  // No marker but a database: an install from before the marker existed.
+  const from = previous ?? "unknown";
+  if (!options.settings.checkpointBeforeUpdate) {
+    log(
+      "backup",
+      `Version changed ${from}→${to}; pre-upgrade checkpoint disabled (backup.checkpointBeforeUpdate=false)`,
+    );
+    await writeLastBootVersion(home, to, now);
+    return { status: "disabled", from, to };
+  }
+
+  const build = options.build ?? buildSnapshot;
+  try {
+    const manifest = await build({
+      kind: "checkpoint",
+      label: `pre-upgrade ${from}→${to}`,
+      pinned: true,
+      settings: options.settings,
+      ...(options.home === undefined ? {} : { home, userHome: null }),
+      // Read-only: the copy is the database exactly as the previous
+      // version left it, before this boot opens it and sets up its schema.
+      ...(hasDatabase ? { copyDatabase: copyDatabaseReadOnly(dbFile) } : {}),
+      now,
+    });
+    await writeLastBootVersion(home, to, now);
+    log(
+      "backup",
+      `Pre-upgrade checkpoint ${manifest.id} taken (${from}→${to}, pinned)`,
+    );
+    return { status: "taken", id: manifest.id, from, to };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    logError(
+      "backup",
+      `PRE-UPGRADE CHECKPOINT FAILED (${from}→${to}) — booting without a safety snapshot; destructive boot steps are skipped`,
+      err,
+    );
+    (options.alert ?? raiseAlert)(
+      UPGRADE_CHECKPOINT_ALERT,
+      `Talon upgraded ${from}→${to} but the pre-upgrade checkpoint failed: ${error}\n` +
+        "The daemon booted anyway and skipped its boot-time cleanup. " +
+        "Fix the backup setup (e.g. a missing backup key) and restart; " +
+        "the checkpoint is retried on every boot until it succeeds.",
+      { severity: "critical" },
+    );
+    return { status: "failed", from, to, error };
+  }
+}

package/src/core/backup/index.ts

@@ -25,6 +25,7 @@ export {
   runBackup,
   stopBackupScheduler,
   checkpointBeforeUpdate,
+  type UpdateCheckpoint,
 } from "./scheduler.js";
 
 export {
@@ -41,6 +42,8 @@ export {
   writeRestorePending,
 } from "./restore.js";
 
+export { checkpointOnVersionChange } from "./boot/version-checkpoint.js";
+
 export { discoverTargets, type BackupTarget } from "./targets.js";
 
 export {

package/src/core/backup/passphrase.ts

@@ -45,7 +45,10 @@ function checked(passphrase: string, source: string): string {
   return passphrase;
 }
 
-async function readPassphraseFile(raw: string): Promise<string> {
+async function readPassphraseFile(
+  raw: string,
+  warnOnMode = true,
+): Promise<string> {
   const path = expandUserPath(raw);
   let text: string;
   try {
@@ -56,7 +59,7 @@ async function readPassphraseFile(raw: string): Promise<string> {
     );
   }
   const mode = (await stat(path)).mode;
-  if (process.platform !== "win32" && (mode & 0o077) !== 0) {
+  if (warnOnMode && process.platform !== "win32" && (mode & 0o077) !== 0) {
     logWarn("backup", `${path} is readable by other users — chmod 600 it`);
   }
   return checked(text.trim(), path);
@@ -93,6 +96,56 @@ export async function resolvePassphrase(
   return null;
 }
 
+/**
+ * What is wrong with the configured key, or null when nothing is. Unlike
+ * `resolvePassphrase` this looks at every configured source: a
+ * `passphraseFile` that has gone missing is reported even while
+ * `TALON_BACKUP_PASSPHRASE` keeps snapshots running, because restoring
+ * anywhere without that variable needs the file. `blocking` says whether
+ * snapshots fail because of it. Never throws.
+ */
+export async function passphraseProblem(
+  settings: Pick<BackupSettings, "encryption">,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<{ message: string; blocking: boolean } | null> {
+  const fromEnv = env[PASSPHRASE_ENV]?.trim();
+  let envProblem: string | null = null;
+  if (fromEnv) {
+    try {
+      checked(fromEnv, PASSPHRASE_ENV);
+    } catch (err) {
+      envProblem = (err as Error).message;
+    }
+  }
+  const file = settings.encryption?.passphraseFile;
+  if (file) {
+    try {
+      await readPassphraseFile(file, false);
+    } catch (err) {
+      const message = (err as Error).message;
+      // A usable environment passphrase wins, so snapshots still run.
+      if (fromEnv && !envProblem) {
+        return {
+          message: `${message} (snapshots still run on ${PASSPHRASE_ENV}, but a restore without it needs this file)`,
+          blocking: false,
+        };
+      }
+      return {
+        message: envProblem ? `${envProblem}; ${message}` : message,
+        blocking: true,
+      };
+    }
+  }
+  if (envProblem) return { message: envProblem, blocking: true };
+  if (settings.encryption && !file && !fromEnv) {
+    return {
+      message: `backup.encryption is set but no passphrase was found: set backup.encryption.passphraseFile or ${PASSPHRASE_ENV}`,
+      blocking: true,
+    };
+  }
+  return null;
+}
+
 /** Like `resolvePassphrase`, for callers that cannot go on without one. */
 export async function requirePassphrase(
   settings: Pick<BackupSettings, "encryption">,

package/src/core/backup/restore.ts

@@ -37,7 +37,7 @@ import {
   copyFile,
 } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { dirs } from "../../util/paths.js";
 import { log, logWarn } from "../../util/log.js";
@@ -50,7 +50,7 @@ import {
 import { sha256File } from "./archive/digest.js";
 import { extractTar } from "./archive/tar.js";
 import { createDecompressor } from "./archive/zstd.js";
-import { requirePassphrase } from "./passphrase.js";
+import { passphraseFilePath, requirePassphrase } from "./passphrase.js";
 import { collectTree, excludeForRoot } from "./plan.js";
 import {
   authenticateManifest,
@@ -348,20 +348,32 @@ export function destinationFor(
   return join(home, ...segments);
 }
 
+/** True when `path` is the active backup passphrase file. */
+function isKeyFile(path: string, keyFile: string | null): boolean {
+  return keyFile !== null && resolve(path) === keyFile;
+}
+
 /**
  * Bring one include root to exactly the snapshot's state: remove what the
  * snapshot rules would have captured, keep what they deliberately skip.
  * Returns how many live files were removed.
+ *
+ * The active passphrase file is never removed. The snapshot builder leaves
+ * it out of every part (a key inside the backup it unlocks is no key), so
+ * when it sits inside an include root — `workspace/secrets/`, `keys/`, an
+ * extra path — nothing in the snapshot would ever put it back.
  */
 async function clearCovered(
   destRoot: string,
   archiveRoot: string,
+  keyFile: string | null,
 ): Promise<number> {
   const existing = await collectTree(destRoot, archiveRoot, {
     exclude: excludeForRoot(archiveRoot),
   });
   let removed = 0;
   for (const entry of [...existing].reverse()) {
+    if (isKeyFile(entry.source, keyFile)) continue;
     try {
       if (entry.type === "dir") await rmdir(entry.source).catch(() => {});
       else {
@@ -410,6 +422,7 @@ async function applyStaged(
   staging: string,
   home: string,
   external: readonly ExternalDestination[],
+  keyFile: string | null,
 ): Promise<RestoreReport> {
   const extras = manifest.extras ?? [];
   const report: RestoreReport = {
@@ -429,7 +442,7 @@ async function applyStaged(
       logWarn("backup", `No destination for ${root} on this machine — skipped`);
       continue;
     }
-    report.removed += await clearCovered(destRoot, root);
+    report.removed += await clearCovered(destRoot, root, keyFile);
     // A session database's sidecars describe the file being replaced.
     if (external.some((entry) => entry.root === root && entry.sqlite)) {
       await rm(`${destRoot}-wal`, { force: true });
@@ -439,6 +452,15 @@ async function applyStaged(
     for (const entry of staged) {
       const dest = destinationFor(entry.archivePath, home, extras, external);
       if (!dest) continue;
+      // An older snapshot (or one from another machine) may carry a file
+      // where this machine keeps its key. The key path is never written.
+      if (entry.type !== "dir" && isKeyFile(dest, keyFile)) {
+        logWarn(
+          "backup",
+          `Left the backup passphrase file ${dest} untouched — the snapshot's copy was not applied`,
+        );
+        continue;
+      }
       if (entry.type === "dir") await mkdir(dest, { recursive: true });
       else {
         await placeFile(entry.source, dest);
@@ -585,7 +607,13 @@ export async function restoreSnapshot(
   const staging = join(snapshotDir(manifest.id, home), "restore-staging");
   await extractParts(manifest, home, staging, options.settings, parts);
   await options.beforeApply?.();
-  const report = await applyStaged(manifest, staging, home, external);
+  const report = await applyStaged(
+    manifest,
+    staging,
+    home,
+    external,
+    passphraseFilePath(options.settings),
+  );
   report.checkpointId = checkpointId;
   if (options.clone && manifest.origin) {
     report.configRewritten = await rewriteConfigForClone(

package/src/core/backup/scheduler.ts

@@ -31,6 +31,7 @@ import { faultText } from "../engine/fault-text.js";
 import { bus } from "../bus/index.js";
 import { log, logError } from "../../util/log.js";
 import { dirs } from "../../util/paths.js";
+import { passphraseProblem } from "./passphrase.js";
 import { buildSnapshot } from "./snapshot.js";
 import { listLocalManifests, pruneLocal, reconcileIndex } from "./store.js";
 import { discoverTargets, selectTargets } from "./targets.js";
@@ -54,6 +55,7 @@ export type RunRequest = {
 /** Test seam: the expensive collaborators, swappable in unit tests. */
 export const _backupDeps = {
   build: buildSnapshot,
+  keyProblem: (settings: BackupSettings) => passphraseProblem(settings),
   discover: discoverTargets,
   upload: uploadSnapshot,
   pruneLocal,
@@ -85,6 +87,10 @@ type SchedulerState = {
   lastSnapshotId: string | undefined;
   lastError: string | undefined;
   nextRunAt: number | undefined;
+  /** The hourly passphrase check (see checkBackupKey). */
+  keyTimer: ReturnType<typeof setInterval> | null;
+  /** What was wrong with the key at the last check, if anything. */
+  keyProblem: string | undefined;
 };
 
 const state: SchedulerState = {
@@ -100,6 +106,8 @@ const state: SchedulerState = {
   lastSnapshotId: undefined,
   lastError: undefined,
   nextRunAt: undefined,
+  keyTimer: null,
+  keyProblem: undefined,
 };
 
 /**
@@ -242,6 +250,7 @@ async function tick(generation: number): Promise<void> {
   const intervalMs = settings.intervalHours * HOUR_MS;
   // Recomputed every tick: a suspended machine or a stepped clock lands
   // here late, and the answer is "run now", not "run N missed times".
+  await checkBackupKey();
   if (backoff.active()) {
     schedule(Math.min(intervalMs, BOOT_DELAY_MS), generation);
     return;
@@ -254,6 +263,82 @@ async function tick(generation: number): Promise<void> {
   schedule(intervalMs, generation);
 }
 
+// ── The key check ───────────────────────────────────────────────────────────
+
+const KEY_ALERT = "backup.key";
+const KEY_CHECK_MS = HOUR_MS;
+
+/**
+ * Is the configured passphrase still there? A key that disappears breaks
+ * every snapshot and the pre-update checkpoint, and a run only notices at
+ * its next window, hours later. So this runs at boot, every hour, before
+ * each scheduled run and on every status request.
+ *
+ * It tells the admin once when the key goes bad and once when it is back,
+ * never on every check. Returns the current problem, or null. Never throws.
+ */
+export async function checkBackupKey(): Promise<string | null> {
+  const settings = state.settings;
+  if (!settings) return null;
+  let problem: { message: string; blocking: boolean } | null;
+  try {
+    problem = await _backupDeps.keyProblem(settings);
+  } catch (err) {
+    problem = {
+      message: err instanceof Error ? err.message : String(err),
+      blocking: true,
+    };
+  }
+  // A check that finished after a reconfiguration describes old settings.
+  if (state.settings !== settings) return state.keyProblem ?? null;
+  const previous = state.keyProblem;
+  state.keyProblem = problem?.message;
+  if (problem && previous === undefined) {
+    await reportKeyProblem(problem);
+  } else if (!problem && previous !== undefined) {
+    await reportKeyRecovered();
+  }
+  return problem?.message ?? null;
+}
+
+async function reportKeyProblem(problem: {
+  message: string;
+  blocking: boolean;
+}): Promise<void> {
+  const consequence = problem.blocking
+    ? "Backups and the pre-update checkpoint will fail until it is fixed, and /update is refused unless forced."
+    : "Backups still run for now.";
+  const text = `Backup key problem: ${faultText(problem.message, 300)}. ${consequence}`;
+  logError("backup", text);
+  if (state.notify === notifyAdmin) {
+    raiseAlert(KEY_ALERT, text, {
+      severity: problem.blocking ? "error" : "warn",
+    });
+    return;
+  }
+  await state.notify(`⚠️ ${text}`).catch(() => {
+    /* the notifier logs its own failures */
+  });
+}
+
+async function reportKeyRecovered(): Promise<void> {
+  const text = "The backup passphrase is readable again.";
+  log("backup", text);
+  if (state.notify === notifyAdmin) {
+    resolveAlert(KEY_ALERT, text);
+    return;
+  }
+  await state.notify(`✅ ${text}`).catch(() => {
+    /* the notifier logs its own failures */
+  });
+}
+
+function armKeyCheck(): void {
+  if (state.keyTimer) clearInterval(state.keyTimer);
+  state.keyTimer = setInterval(() => void checkBackupKey(), KEY_CHECK_MS);
+  state.keyTimer.unref?.();
+}
+
 /**
  * Wire the subsystem and arm the timer. Safe to call with backups
  * disabled — it reconciles the index either way, so the listing surfaces
@@ -274,6 +359,10 @@ export async function initBackup(options: {
   const newest = (await listLocalManifests(state.home))[0];
   state.lastRunAt = newest?.createdAt ?? 0;
   state.lastSnapshotId = newest?.id;
+  // The key is checked whether or not the schedule runs: manual
+  // checkpoints and the pre-update checkpoint need it too.
+  await checkBackupKey();
+  armKeyCheck();
   if (!options.settings.enabled) {
     log(
       "backup",
@@ -301,6 +390,8 @@ export function stopBackupScheduler(): void {
   if (state.timer) clearTimeout(state.timer);
   state.timer = null;
   state.nextRunAt = undefined;
+  if (state.keyTimer) clearInterval(state.keyTimer);
+  state.keyTimer = null;
 }
 
 /** What the status surfaces report about the schedule itself. */
@@ -326,18 +417,39 @@ export function schedulerStatus(): {
   };
 }
 
+/**
+ * What the pre-update hook managed. `disabled` is the operator's explicit
+ * opt-out (`backup.checkpointBeforeUpdate: false`); `failed` covers both a
+ * run that threw and a process with no backup subsystem to ask.
+ */
+export type UpdateCheckpoint =
+  | { status: "taken"; id: string }
+  | { status: "disabled" }
+  | { status: "failed"; error: string };
+
 /**
  * The self-update hook: a pinned checkpoint before the tree moves, so a
- * bad update is one `talon backup restore` away from undone. Returns the
- * checkpoint id, or null when the feature is off or the subsystem is not
- * initialised (a CLI-driven update in a process with no daemon state).
- * Never throws: failing to take a checkpoint must not block the update.
+ * bad update is one `talon backup restore` away from undone.
+ *
+ * Never throws — it reports. The caller decides: `/update` refuses to go
+ * on after a `failed` checkpoint unless the operator forces it, because
+ * an update with no way back is exactly when data goes missing.
+ *
+ * `backup.enabled: false` only stops the schedule; manual checkpoints
+ * still work, so this one is still taken.
  */
 export async function checkpointBeforeUpdate(
   fromVersion: string,
   toVersion: string,
-): Promise<string | null> {
-  if (!state.settings?.checkpointBeforeUpdate) return null;
+): Promise<UpdateCheckpoint> {
+  const settings = state.settings;
+  if (!settings) {
+    return {
+      status: "failed",
+      error: "the backup subsystem is not running in this process",
+    };
+  }
+  if (!settings.checkpointBeforeUpdate) return { status: "disabled" };
   try {
     const manifest = await runBackup({
       kind: "checkpoint",
@@ -345,14 +457,13 @@ export async function checkpointBeforeUpdate(
       pinned: true,
       trigger: "pre-update",
     });
-    return manifest.id;
+    return { status: "taken", id: manifest.id };
   } catch (err) {
-    logError(
-      "backup",
-      "Pre-update checkpoint failed; continuing with the update",
-      err,
-    );
-    return null;
+    logError("backup", "Pre-update checkpoint failed", err);
+    return {
+      status: "failed",
+      error: err instanceof Error ? err.message : String(err),
+    };
   }
 }
 
@@ -372,5 +483,6 @@ export function _resetBackupScheduler(): void {
   state.lastRunAt = 0;
   state.lastSnapshotId = undefined;
   state.lastError = undefined;
+  state.keyProblem = undefined;
   backoff.succeed();
 }

package/src/core/backup/status.ts

@@ -15,8 +15,12 @@ import {
   selectTargets,
   type BackupTarget,
 } from "./targets.js";
-import { backupSettings, schedulerStatus } from "./scheduler.js";
-import { PASSPHRASE_ENV } from "./passphrase.js";
+import {
+  backupSettings,
+  checkBackupKey,
+  schedulerStatus,
+} from "./scheduler.js";
+import { PASSPHRASE_ENV, passphraseProblem } from "./passphrase.js";
 import type { BackupSettings, SnapshotSummary } from "./types.js";
 
 type TargetStatus = {
@@ -41,6 +45,8 @@ export type BackupStatus = {
   snapshots: SnapshotSummary[];
   /** Retention and encryption, when the subsystem is initialised. */
   policy?: BackupPolicy;
+  /** What is wrong with the configured passphrase, if anything. */
+  keyProblem?: string;
 };
 
 /** The settings a status panel renders alongside the numbers. */
@@ -125,12 +131,25 @@ export async function collectBackupStatus(
   options: {
     home?: string;
     withTargets?: boolean;
+    /**
+     * Settings to describe when this process runs no backup subsystem
+     * (the CLI with the daemon down). The daemon's own settings win.
+     */
+    settings?: BackupSettings;
   } = {},
 ): Promise<BackupStatus> {
   const home = options.home ?? dirs.root;
   const snapshots = await listSnapshots(home);
   const local = snapshots.filter((snapshot) => snapshot.local);
-  const settings = backupSettings();
+  const live = backupSettings();
+  const settings = live ?? options.settings ?? null;
+  // In the daemon the check also raises (or clears) the key alert; outside
+  // it there is nobody to alert, so it only reports.
+  const keyProblem = live
+    ? await checkBackupKey()
+    : settings
+      ? ((await passphraseProblem(settings))?.message ?? null)
+      : null;
   const targets =
     options.withTargets === false
       ? []
@@ -148,6 +167,7 @@ export async function collectBackupStatus(
     targets,
     snapshots,
     policy: describePolicy(settings),
+    ...(keyProblem ? { keyProblem } : {}),
   };
 }
 
@@ -198,6 +218,9 @@ export function formatBackupStatus(
     `Last run: ${formatRelative(schedule.lastRunAt, now)}` +
       (schedule.lastSnapshotId ? ` — ${schedule.lastSnapshotId}` : ""),
   );
+  if (status.keyProblem) {
+    lines.push(`Key: PROBLEM — ${status.keyProblem}`);
+  }
   if (schedule.consecutiveFailures > 0) {
     lines.push(
       `Failing: ${schedule.consecutiveFailures} consecutive — ${schedule.lastError ?? "unknown error"}`,