talon-agent 5.26.1 → 5.26.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.26.1",
+  "version": "5.26.2",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",

package/src/app.ts

@@ -167,8 +167,49 @@ const restoreReport = await withConfigGuard(() =>
   bootPhase("staged restore", applyStagedRestore),
 );
 
+/**
+ * The first boot of a new version (a Docker/TrueNAS image pull, an npm or
+ * binary upgrade — anything but `/update`, which checkpoints itself) takes
+ * a pinned `pre-upgrade <old>→<new>` checkpoint HERE: after a staged
+ * restore, before bootstrap opens the stores and the backend reconcile or
+ * any migration runs against them. A failed checkpoint alerts the admin
+ * and still boots, but with the destructive boot steps skipped.
+ *
+ * Never throws.
+ */
+async function checkpointIfUpgraded(): Promise<{ safe: boolean }> {
+  try {
+    const { checkpointOnVersionChange } =
+      await import("./core/backup/index.js");
+    const { loadConfig } = await import("./core/config/index.js");
+    const { resolveBackupSettings } = await import("./core/backup/plan.js");
+    const { talonVersion } = await import("./util/version.js");
+    const result = await checkpointOnVersionChange({
+      settings: resolveBackupSettings(loadConfig().backup),
+      version: talonVersion(),
+    });
+    return { safe: result.status !== "failed" };
+  } catch (err) {
+    if (err instanceof ConfigFileError) throw err;
+    logError("backup", "Pre-upgrade version check failed", err);
+    const { raiseAlert } = await import("./core/frontend-runtime/alerts.js");
+    raiseAlert(
+      "backup.upgrade-checkpoint",
+      `The boot-time version check / pre-upgrade checkpoint crashed: ${String(err)}. Booted without it; boot-time cleanup skipped.`,
+      { severity: "critical" },
+    );
+    return { safe: false };
+  }
+}
+
+const upgrade = await withConfigGuard(() =>
+  bootPhase("upgrade checkpoint", checkpointIfUpgraded),
+);
+
 const { config } = await withConfigGuard(() =>
-  bootPhase("bootstrap", () => bootstrap()),
+  bootPhase("bootstrap", () =>
+    bootstrap({ skipDestructiveSteps: !upgrade.safe }),
+  ),
 );
 
 // Record this process as the daemon. The gateway port is appended once

package/src/bootstrap.ts

@@ -15,7 +15,7 @@ import { loadSessions, resetSession } from "./storage/sessions.js";
 import { loadChatSettings } from "./storage/chat-settings.js";
 import { loadCronJobs } from "./storage/cron.js";
 import { loadTriggers } from "./storage/triggers.js";
-import { clearHistory, loadHistory } from "./storage/history.js";
+import { loadHistory } from "./storage/history.js";
 import { loadMediaIndex } from "./storage/media-index.js";
 import { cleanupOldLogs } from "./storage/daily-log.js";
 import {
@@ -90,6 +90,12 @@ function resolveFrontendByNumericId(
 export type BootstrapOptions = {
   /** Override frontend names for plugin loading (e.g. ["terminal"]). */
   frontendNames?: string[];
+  /**
+   * Skip the boot steps that delete data (expired daily logs and memory
+   * notes, expired media). Set when the pre-upgrade checkpoint failed:
+   * with no snapshot to fall back on, this boot deletes nothing.
+   */
+  skipDestructiveSteps?: boolean;
 };
 
 export type BootstrapResult = {
@@ -165,9 +171,16 @@ export async function bootstrap(
     loadCronJobs();
     loadTriggers();
     loadHistory();
-    loadMediaIndex();
+    loadMediaIndex({ purgeExpired: !options.skipDestructiveSteps });
   });
-  cleanupOldLogs();
+  if (options.skipDestructiveSteps) {
+    logWarn(
+      "bot",
+      "Skipping boot-time cleanup (old daily logs, expired media): no pre-upgrade checkpoint to fall back on",
+    );
+  } else {
+    cleanupOldLogs();
+  }
 
   return { config };
 }
@@ -195,89 +208,191 @@ type ChatBindingDeps = {
   getBackendIdForChat: (chatId: string) => string;
   getBackendForChat: (chatId: string) => Backend;
   isModelValidForBackend: (backend: Backend, model: string) => Promise<boolean>;
+  /**
+   * Tell the operator what the reconcile changed — once per boot, one
+   * message for every chat. Defaults to an operator alert.
+   */
+  notify?: (text: string) => void;
 };
 
 const CHAT_BINDING_CONCURRENCY = 8;
 const REBIND_RETRY_DELAY_MS = 1_500;
+const ONE_MILLION_SUFFIX = /\s*\[1m\]$/i;
 
 /**
  * Re-establish every chat's stored backend/model override against the
  * backends this boot actually has. Chats are independent, so they are
  * reconciled `CHAT_BINDING_CONCURRENCY` at a time; a shared backend that
  * two chats need at once is initialised exactly once by the pool.
+ *
+ * Never deletes chat history. A stale override is corrected (remapped to
+ * the closest valid id, or cleared so the backend default serves) and the
+ * operator is told once, naming every chat that changed. Only a chat whose
+ * backend is gone gets a fresh backend session — its old session id is
+ * archived by `resetSession`, and its history rows stay.
  */
 export async function reconcileChatBindings(
   config: TalonConfig,
   deps: ChatBindingDeps,
 ): Promise<void> {
   const { getAllChatSettings } = await import("./storage/chat-settings.js");
+  const changes: string[] = [];
   await mapConcurrent(
     Object.entries(getAllChatSettings()),
     CHAT_BINDING_CONCURRENCY,
-    ([cid, settings]) => reconcileChatBinding(cid, settings, config, deps),
+    async ([cid, settings]) => {
+      const change = await reconcileChatBinding(cid, settings, config, deps);
+      if (change) changes.push(`• ${cid}: ${change}`);
+    },
+  );
+  if (changes.length === 0) return;
+  const text =
+    `Boot reconcile adjusted ${changes.length} chat(s) whose pinned backend/model ` +
+    `is no longer available (chat history kept):\n${changes.sort().join("\n")}`;
+  logWarn("bot", text);
+  (deps.notify ?? defaultReconcileNotify)(text);
+}
+
+function defaultReconcileNotify(text: string): void {
+  void import("./core/frontend-runtime/alerts.js").then(({ raiseAlert }) =>
+    raiseAlert("chat-bindings.reconciled", text, { severity: "warn" }),
   );
 }
 
+/**
+ * The closest valid id for a model the catalog no longer lists, or null.
+ * Today: `<id>[1m]` → `<id>` (SDK catalogs stopped enumerating the 1M
+ * context variants), so a chat keeps its model family instead of being
+ * dropped to the backend default.
+ */
+async function remapModelAlias(
+  backend: Backend,
+  model: string,
+  deps: ChatBindingDeps,
+): Promise<string | null> {
+  if (!ONE_MILLION_SUFFIX.test(model)) return null;
+  const stem = model.replace(ONE_MILLION_SUFFIX, "").trim();
+  if (!stem) return null;
+  return (await deps.isModelValidForBackend(backend, stem)) ? stem : null;
+}
+
+/**
+ * Reconcile one chat. Returns a short description of what changed, or
+ * null when nothing did.
+ */
 async function reconcileChatBinding(
   cid: string,
   settings: { backend?: string; model?: string },
   config: TalonConfig,
   deps: ChatBindingDeps,
-): Promise<void> {
-  const { getAllChatSettings, setChatBackend, setChatModel } =
-    await import("./storage/chat-settings.js");
-  let resetVolatileState = false;
+): Promise<string | null> {
+  const changes: string[] = [];
   if (settings.backend) {
-    if (!deps.isBackendAvailable(settings.backend, config)) {
-      log(
-        "bot",
-        `Per-chat backend ${settings.backend} for ${cid} is no longer available — resetting chat to default backend`,
-      );
-      await deps.releaseChat(cid);
-      setChatBackend(cid, undefined);
-      setChatModel(cid, undefined);
-      resetVolatileState = true;
-    } else {
-      let result = await deps.rebindChat(cid, settings.backend, config);
-      if (!result.ok) {
-        await new Promise((r) => setTimeout(r, REBIND_RETRY_DELAY_MS));
-        result = await deps.rebindChat(cid, settings.backend, config);
-      }
-      if (!result.ok) {
-        log(
-          "bot",
-          `Per-chat backend rebind failed for ${cid} → ${settings.backend}: ${result.error} — keeping the setting; will serve on the default backend until re-selected`,
-        );
-      }
-    }
+    const change = await reconcileChatBackend(
+      cid,
+      settings.backend,
+      config,
+      deps,
+    );
+    if (change) changes.push(change);
   }
   const bindingMatchesSetting =
     !settings.backend || deps.getBackendIdForChat(cid) === settings.backend;
-  const currentModel = getAllChatSettings()[cid]?.model;
-  if (currentModel && bindingMatchesSetting) {
-    const be = deps.getBackendForChat(cid);
-    try {
-      const valid = await deps.isModelValidForBackend(be, currentModel);
-      if (!valid) {
-        log(
-          "bot",
-          `Per-chat model ${currentModel} for ${cid} is not valid for its backend — resetting model to default`,
-        );
-        setChatModel(cid, undefined);
-        resetVolatileState = true;
-      }
-    } catch (err) {
-      log(
+  if (bindingMatchesSetting) {
+    const change = await reconcileChatModel(cid, deps);
+    if (change) changes.push(change);
+  }
+  return changes.length > 0 ? changes.join("; ") : null;
+}
+
+async function reconcileChatBackend(
+  cid: string,
+  backendId: string,
+  config: TalonConfig,
+  deps: ChatBindingDeps,
+): Promise<string | null> {
+  const { setChatBackend, clearLegacyChatModel } =
+    await import("./storage/chat-settings.js");
+  if (!deps.isBackendAvailable(backendId, config)) {
+    logWarn(
+      "bot",
+      `Per-chat backend ${backendId} for ${cid} is no longer available — serving the chat on the default backend (history kept)`,
+    );
+    await deps.releaseChat(cid);
+    setChatBackend(cid, undefined);
+    // The per-backend model picks stay: they are keyed by backend, so the
+    // default backend's pick (if any) still applies and the vanished
+    // backend's comes back with it. Only the unkeyed legacy slot goes.
+    clearLegacyChatModel(cid);
+    // The stored session belongs to the vanished backend and cannot resume
+    // on another one. resetSession archives its id; history is untouched.
+    resetSession(cid, "backend-unavailable");
+    return `backend ${backendId} unavailable → default backend`;
+  }
+  let result = await deps.rebindChat(cid, backendId, config);
+  if (!result.ok) {
+    await new Promise((r) => setTimeout(r, REBIND_RETRY_DELAY_MS));
+    result = await deps.rebindChat(cid, backendId, config);
+  }
+  if (!result.ok) {
+    log(
+      "bot",
+      `Per-chat backend rebind failed for ${cid} → ${backendId}: ${result.error} — keeping the setting; will serve on the default backend until re-selected`,
+    );
+  }
+  return null;
+}
+
+/**
+ * Check the chat's pinned model against the backend that serves it.
+ * The unkeyed legacy slot is remapped or cleared when stale; a per-backend
+ * pick is only ever remapped (the send-time resolver already falls back
+ * past a stale one, and a catalog that failed to load must not erase it).
+ * The backend session is kept either way: a resume under a different
+ * model is fine, and the conversation is the point.
+ */
+async function reconcileChatModel(
+  cid: string,
+  deps: ChatBindingDeps,
+): Promise<string | null> {
+  const {
+    getAllChatSettings,
+    getChatModelForBackend,
+    setChatModelForBackend,
+    clearLegacyChatModel,
+  } = await import("./storage/chat-settings.js");
+  const backendId = deps.getBackendIdForChat(cid);
+  const legacy = getAllChatSettings()[cid]?.model;
+  const model = legacy ?? getChatModelForBackend(cid, backendId);
+  if (!model) return null;
+  const be = deps.getBackendForChat(cid);
+  try {
+    if (await deps.isModelValidForBackend(be, model)) return null;
+    const remapped = await remapModelAlias(be, model, deps);
+    if (remapped) {
+      setChatModelForBackend(cid, backendId, remapped);
+      if (legacy) clearLegacyChatModel(cid);
+      logWarn(
         "bot",
-        `Per-chat model validation failed for ${cid} (${currentModel}): ${
-          err instanceof Error ? err.message : String(err)
-        } — keeping stored model`,
+        `Per-chat model ${model} for ${cid} is not in the ${backendId} catalog — remapped to ${remapped} (history and session kept)`,
       );
+      return `model ${model} → ${remapped}`;
     }
-  }
-  if (resetVolatileState) {
-    resetSession(cid);
-    clearHistory(cid);
+    if (!legacy) return null;
+    clearLegacyChatModel(cid);
+    logWarn(
+      "bot",
+      `Per-chat model ${model} for ${cid} is not valid for its backend — falling back to the backend default (history and session kept)`,
+    );
+    return `model ${model} unavailable → backend default`;
+  } catch (err) {
+    log(
+      "bot",
+      `Per-chat model validation failed for ${cid} (${model}): ${
+        err instanceof Error ? err.message : String(err)
+      } — keeping stored model`,
+    );
+    return null;
   }
 }
 
@@ -370,11 +485,10 @@ export async function initBackendAndDispatcher(
   );
 
   // Re-acquire any persisted per-chat backend/model overrides so chats
-  // resume exactly where they were before restart. If a backend has
-  // since been disabled/removed, or the stored model is no longer valid
-  // for the backend that would serve it, clear the override and reset
-  // volatile chat state so the next user message starts a fresh default
-  // session instead of crashing on an orphaned model id.
+  // resume exactly where they were before restart. A backend that has
+  // since gone, or a stored model its backend no longer lists, is
+  // corrected (remapped or cleared to the default) — never by deleting
+  // the chat's history. See reconcileChatBindings.
   await bootPhase("chat bindings", () =>
     reconcileChatBindings(config, {
       isBackendAvailable,

package/src/cli/commands/backup.ts

@@ -271,7 +271,10 @@ async function backupStatus(): Promise<void> {
     renderResult(result);
     return;
   }
-  const status = await collectBackupStatus({ withTargets: false });
+  const status = await collectBackupStatus({
+    withTargets: false,
+    settings: resolveBackupSettings(loadConfig().backup),
+  });
   console.log(
     `\n${formatBackupStatus(status)
       .split("\n")

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">,