talon-agent 5.26.1 → 5.26.2

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/update/self-update.ts

@@ -27,10 +27,19 @@
  * can never leave the deployment un-updatable, which is what the old
  * `pull --ff-only` did (it aborts on any dirty/diverged tree). `.gitignore`
  * is respected (no `-x`), so node_modules, secrets and local config survive.
+ *
+ * Before anything in the checkout moves, a pinned pre-update checkpoint is
+ * taken. If it fails, the update is refused. An update with no way back is
+ * when data goes missing, so the operator must say `force` to go on
+ * without one. Opting out in config (`backup.checkpointBeforeUpdate:
+ * false`) is the only way to skip it without being asked.
  */
 
 import { execFile } from "node:child_process";
-import { checkpointBeforeUpdate } from "../backup/index.js";
+import {
+  checkpointBeforeUpdate,
+  type UpdateCheckpoint,
+} from "../backup/index.js";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -60,6 +69,13 @@ export interface UpdateOptions {
   entry?: { cmd: string; args: readonly string[] };
   /** Injectable command runner (tests). */
   runner?: CommandRunner;
+  /**
+   * Go on even when the pre-update checkpoint fails (`/update force`).
+   * The result still says the checkpoint failed.
+   */
+  force?: boolean;
+  /** Injectable pre-update checkpoint (tests). */
+  checkpoint?: (from: string, to: string) => Promise<UpdateCheckpoint>;
 }
 
 /** One executed step in an update run. */
@@ -82,6 +98,13 @@ export interface UpdateResult {
   changed: boolean;
   /** Human-readable failure reason when `ok` is false. */
   error?: string;
+  /** The pre-update checkpoint, when the update got far enough to take one. */
+  checkpoint?: UpdateCheckpoint;
+  /**
+   * True when the update was refused because the checkpoint failed. Nothing
+   * in the checkout was touched; `force` would have gone on.
+   */
+  checkpointRefused?: boolean;
 }
 
 export type CommandRunner = (
@@ -171,12 +194,7 @@ export async function runSelfUpdate(
   const branch = opts.branch?.trim() || "main";
   const run = opts.runner ?? defaultRunner;
 
-  const record = async (
-    label: string,
-    cmd: string,
-    args: readonly string[],
-    timeoutMs: number,
-  ): Promise<UpdateStep> => {
+  const record: Recorder = async (label, cmd, args, timeoutMs) => {
     const { ok, output } = await run(cmd, args, repoRoot, timeoutMs);
     const step: UpdateStep = { label, ok, output };
     steps.push(step);
@@ -210,22 +228,58 @@ export async function runSelfUpdate(
   );
   if (!fetch.ok) return fail(`git fetch failed: ${fetch.output}`, before);
 
+  // Where the update is going, read before the tree moves: the checkpoint
+  // is labelled with it, and "already up to date" needs no checkpoint.
+  const targetRef = `${remote}/${branch}`;
+  const target = await record(
+    `rev-parse ${targetRef}`,
+    "git",
+    ["rev-parse", targetRef],
+    GIT_TIMEOUT_MS,
+  );
+  if (!target.ok) {
+    return fail(`Failed to read ${targetRef}: ${target.output}`, before);
+  }
+  const upcoming = shortSha(target.output);
+
+  // The safety net goes up before anything is destroyed: the reset and
+  // clean below discard local state, and the new code may migrate data.
+  let checkpoint: UpdateCheckpoint | undefined;
+  if (upcoming !== before) {
+    checkpoint = await (opts.checkpoint ?? checkpointBeforeUpdate)(
+      before,
+      upcoming,
+    );
+    steps.push({
+      label: "pre-update checkpoint",
+      ok: checkpoint.status !== "failed",
+      output: describeCheckpoint(checkpoint),
+    });
+    if (checkpoint.status === "failed" && !opts.force) {
+      return {
+        ...fail(refusal(checkpoint.error), before),
+        checkpoint,
+        checkpointRefused: true,
+      };
+    }
+  }
+
   // Force the checkout to exactly match the freshly-fetched remote
   // branch, discarding ANY local edits or diverged commits. The old
   // `pull --ff-only` aborted here whenever the tree was dirty, leaving the
   // deployment stuck; a bot host is meant to mirror the remote, so resetting
   // to it is both correct and reliable.
   const reset = await record(
-    `reset --hard ${remote}/${branch}`,
+    `reset --hard ${targetRef}`,
     "git",
-    ["reset", "--hard", `${remote}/${branch}`],
+    ["reset", "--hard", targetRef],
     GIT_TIMEOUT_MS,
   );
   if (!reset.ok) {
-    return fail(
-      `git reset --hard ${remote}/${branch} failed: ${reset.output}`,
-      before,
-    );
+    return {
+      ...fail(`git reset --hard ${targetRef} failed: ${reset.output}`, before),
+      checkpoint,
+    };
   }
 
   // Drop untracked files too so the tree is pristine and a future update
@@ -246,28 +300,62 @@ export async function runSelfUpdate(
   // Nothing moved — skip the expensive install/setup and tell the
   // caller no restart is needed.
   if (!changed) {
-    return { ok: true, repoRoot, steps, before, after, changed: false };
+    return {
+      ok: true,
+      repoRoot,
+      steps,
+      before,
+      after,
+      changed: false,
+      checkpoint,
+    };
   }
 
-  await checkpointBeforeUpdate(before, after);
+  const error = await installAndVerify(record, opts, before, after);
+  return {
+    ok: !error,
+    repoRoot,
+    steps,
+    before,
+    after,
+    changed: true,
+    checkpoint,
+    ...(error ? { error } : {}),
+  };
+}
+
+type Recorder = (
+  label: string,
+  cmd: string,
+  args: readonly string[],
+  timeoutMs: number,
+) => Promise<UpdateStep>;
 
+function refusal(error: string): string {
+  return (
+    `the pre-update checkpoint failed (${error}). ` +
+    `Nothing was changed. Fix the backup problem, or run the update ` +
+    `with "force" to go on without a checkpoint.`
+  );
+}
+
+/**
+ * Reinstall, run setup, and prove the new tree imports. Returns the
+ * failure reason, or null when the tree is ready to restart into.
+ */
+async function installAndVerify(
+  record: Recorder,
+  opts: UpdateOptions,
+  before: string,
+  after: string,
+): Promise<string | null> {
   const install = await record(
     "npm install",
     "npm",
     ["install"],
     INSTALL_TIMEOUT_MS,
   );
-  if (!install.ok) {
-    return {
-      ok: false,
-      repoRoot,
-      steps,
-      before,
-      after,
-      changed,
-      error: `npm install failed: ${install.output}`,
-    };
-  }
+  if (!install.ok) return `npm install failed: ${install.output}`;
 
   for (const cmd of opts.setup ?? []) {
     const trimmed = cmd.trim();
@@ -279,15 +367,7 @@ export async function runSelfUpdate(
       SETUP_TIMEOUT_MS,
     );
     if (!setup.ok) {
-      return {
-        ok: false,
-        repoRoot,
-        steps,
-        before,
-        after,
-        changed,
-        error: `setup command failed (${trimmed}): ${setup.output}`,
-      };
+      return `setup command failed (${trimmed}): ${setup.output}`;
     }
   }
 
@@ -299,18 +379,35 @@ export async function runSelfUpdate(
     VERIFY_TIMEOUT_MS,
   );
   if (!verify.ok || !verify.output.includes(BOOT_SMOKE_OK)) {
-    return {
-      ok: false,
-      repoRoot,
-      steps,
-      before,
-      after,
-      changed,
-      error:
-        `the updated tree does not import — not restarting into it. ` +
-        `Still running ${before}; the checkout is at ${after}.`,
-    };
+    return (
+      `the updated tree does not import — not restarting into it. ` +
+      `Still running ${before}; the checkout is at ${after}.`
+    );
+  }
+  return null;
+}
+
+/** One line for the step log and the chat reply. */
+export function describeCheckpoint(checkpoint: UpdateCheckpoint): string {
+  switch (checkpoint.status) {
+    case "taken":
+      return `checkpoint ${checkpoint.id} taken`;
+    case "disabled":
+      return "no checkpoint (backup.checkpointBeforeUpdate is off)";
+    case "failed":
+      return `checkpoint failed: ${checkpoint.error}`;
   }
+}
 
-  return { ok: true, repoRoot, steps, before, after, changed: true };
+/**
+ * Whether the arguments to `/update` ask to go on without a checkpoint.
+ * `force` and `--force` both work, so the chat command and a CLI habit
+ * read the same.
+ */
+export function wantsForce(args: string | undefined | null): boolean {
+  return (args ?? "")
+    .trim()
+    .toLowerCase()
+    .split(/\s+/)
+    .some((token) => token === "force" || token === "--force");
 }