talon-agent 5.26.0 → 5.26.2

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

package/src/core/frontend-runtime/admin-notify.ts

@@ -7,7 +7,10 @@
  * wiring, which does the same thing privately). Alerts raised before that
  * — early boot is exactly when restore reports and security alerts fire —
  * are held in a small bounded queue and flushed, oldest first, the moment
- * a notifier is wired. With nothing ever wired (tests, terminal mode with
+ * a notifier is wired. An alert carrying a key (operator alerts do) is
+ * deduplicated while it waits: a re-raise replaces the queued copy instead
+ * of queueing another, and a key that resolves before anyone could hear it
+ * is withdrawn outright. With nothing ever wired (tests, terminal mode with
  * no admin) they stay a log line; nothing throws.
  *
  * First consumer: WhatsApp pairing. When WhatsApp unlinks the device,
@@ -25,7 +28,14 @@ let deliver: Deliver | null = null;
 /** Most alerts held while no notifier is wired; the oldest are dropped past it. */
 export const ADMIN_NOTIFY_QUEUE_MAX = 20;
 
-type Pending = { text: string; at: number };
+type Pending = {
+  text: string;
+  at: number;
+  /** Dedup key (operator alert key); unkeyed alerts never coalesce. */
+  key?: string;
+  /** Re-raises folded into this entry while it waited. */
+  repeats: number;
+};
 const pending: Pending[] = [];
 let droppedWhileUnwired = 0;
 let flushing: Promise<void> | null = null;
@@ -68,6 +78,7 @@ async function flushPending(fn: Deliver): Promise<void> {
     batch.unshift({
       text: `${dropped} earlier admin alert(s) were dropped before a notifier was wired (queue holds ${ADMIN_NOTIFY_QUEUE_MAX}); see the daemon log.`,
       at: Date.now(),
+      repeats: 0,
     });
   }
   log("notify", `Flushing ${batch.length} queued admin alert(s)`);
@@ -79,7 +90,10 @@ async function flushPending(fn: Deliver): Promise<void> {
       continue;
     }
     const ageS = Math.round((Date.now() - item.at) / 1000);
-    const text = ageS >= 5 ? `(delayed ${ageS}s) ${item.text}` : item.text;
+    const repeated =
+      item.repeats > 0 ? `\n(raised ${item.repeats + 1}× while starting)` : "";
+    const text =
+      (ageS >= 5 ? `(delayed ${ageS}s) ${item.text}` : item.text) + repeated;
     try {
       await fn(text);
       log("notify", `Admin notified (queued): ${preview(item.text)}`);
@@ -95,6 +109,17 @@ async function flushPending(fn: Deliver): Promise<void> {
 }
 
 function enqueue(item: Pending): void {
+  if (item.key !== undefined) {
+    const i = pending.findIndex((p) => p.key === item.key);
+    if (i >= 0) {
+      // Same fault raised again while waiting: keep one entry, newest text,
+      // original timestamp (so the "delayed" note stays honest).
+      const prior = pending[i];
+      prior.text = item.text;
+      prior.repeats += item.repeats + 1;
+      return;
+    }
+  }
   pending.push(item);
   while (pending.length > ADMIN_NOTIFY_QUEUE_MAX) {
     const lost = pending.shift();
@@ -111,14 +136,29 @@ function preview(text: string): string {
   return text.slice(0, 80).replace(/\n/g, " ");
 }
 
+/**
+ * Withdraw a queued, not-yet-delivered alert by key (its fault cleared
+ * before a notifier was wired). Returns whether one was withdrawn.
+ */
+export function withdrawAdminNotification(key: string): boolean {
+  const i = pending.findIndex((p) => p.key === key);
+  if (i < 0) return false;
+  const [gone] = pending.splice(i, 1);
+  log("notify", `Withdrew queued admin alert ${key}: ${preview(gone.text)}`);
+  return true;
+}
+
 /**
  * Send `text` to the admin chat. Never throws; returns whether it was
  * delivered now (false = failed, or queued because no notifier is wired
- * yet — it is sent when one is).
+ * yet — it is sent when one is). `key` deduplicates while queued.
  */
-export async function notifyAdmin(text: string): Promise<boolean> {
+export async function notifyAdmin(
+  text: string,
+  key?: string,
+): Promise<boolean> {
   if (!deliver) {
-    enqueue({ text, at: Date.now() });
+    enqueue({ text, at: Date.now(), key, repeats: 0 });
     logWarn(
       "notify",
       `No admin notifier wired yet; queued (${pending.length}/${ADMIN_NOTIFY_QUEUE_MAX}): ${text.slice(0, 120)}`,

package/src/core/frontend-runtime/alerts.ts

@@ -15,7 +15,7 @@
  */
 
 import { log, logWarn } from "../../util/log.js";
-import { notifyAdmin } from "./admin-notify.js";
+import { notifyAdmin, withdrawAdminNotification } from "./admin-notify.js";
 
 export type AlertSeverity = "warn" | "error" | "critical";
 
@@ -39,7 +39,8 @@ const RANK: Record<AlertSeverity, number> = { warn: 0, error: 1, critical: 2 };
 const active = new Map<string, ActiveAlert>();
 let cooldownMs = DEFAULT_COOLDOWN_MS;
 let enabled = true;
-let send: (text: string) => Promise<unknown> = notifyAdmin;
+type Send = (text: string, key?: string) => Promise<unknown>;
+let send: Send = notifyAdmin;
 
 /** Apply operator settings (config `alerts`). */
 export function configureAlerts(opts: {
@@ -86,7 +87,9 @@ export function raiseAlert(
     // Nobody heard it: don't let the cooldown swallow the next raise.
     if (active.get(key) === entry) entry.lastSentAt = 0;
   };
-  void send(`${ICON[severity]} ${message}${repeat}`).then((ok) => {
+  // The key lets a still-queued copy (no notifier wired yet) be replaced by
+  // this raise rather than queued twice.
+  void send(`${ICON[severity]} ${message}${repeat}`, key).then((ok) => {
     if (ok === false) undelivered();
   }, undelivered);
 }
@@ -99,6 +102,9 @@ export function resolveAlert(key: string, message?: string): void {
   const mins = Math.max(1, Math.round((Date.now() - prior.firstAt) / 60_000));
   log("alert", `resolved ${key} after ${mins} min`);
   if (!enabled) return;
+  // Still queued for a notifier that never got to send it: withdraw it, and
+  // there is nothing to announce a recovery from.
+  if (withdrawAdminNotification(key)) return;
   void send(`✅ ${message ?? `Recovered: ${key}`} (after ${mins} min)`).catch(
     () => {},
   );
@@ -120,9 +126,7 @@ export function activeAlerts(): ReadonlyArray<{
 }
 
 /** Test seam: reset state and swap the delivery function. */
-export function resetAlertsForTest(
-  deliver: (text: string) => Promise<unknown> = notifyAdmin,
-): void {
+export function resetAlertsForTest(deliver: Send = notifyAdmin): void {
   active.clear();
   cooldownMs = DEFAULT_COOLDOWN_MS;
   enabled = true;