talon-agent 5.26.2 → 5.26.4

package/README.md

@@ -468,6 +468,7 @@ talon kill      Abort a killable task by id
 talon events    Tail the event bus (-f follows, --history [N] reads the journal)
 talon plugin    Manage plugins (install / enable / disable / remove)
 talon skill     Manage skills (install / enable / disable / remove)
+talon history   Chat history kept by Talon (show / hidden / purge — docs/chat-history.md)
 talon config    View or edit configuration
 talon logs      Tail structured log file
 talon doctor    Validate environment and dependencies

package/package.json

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

package/src/backend/remote-server/sessions.ts

@@ -15,6 +15,7 @@ import {
   setSessionId,
 } from "../../storage/sessions.js";
 import { log, logWarn } from "../../util/log.js";
+import { TalonError } from "../../core/errors.js";
 import type { RemoteAgentClient, RemotePermissionRule } from "./client.js";
 import type { RemoteServerState } from "./state.js";
 import {
@@ -73,32 +74,100 @@ export function buildPermissionRuleset(chatId: string): RemotePermissionRule[] {
   ];
 }
 
+/** Pull an HTTP status out of whatever shape the SDK client threw. */
+function errorStatus(err: unknown): number | undefined {
+  if (typeof err !== "object" || err === null) return undefined;
+  const e = err as Record<string, unknown>;
+  const cause = e.cause as Record<string, unknown> | undefined;
+  const response = e.response as Record<string, unknown> | undefined;
+  for (const candidate of [
+    e.status,
+    e.statusCode,
+    response?.status,
+    cause?.status,
+  ]) {
+    if (typeof candidate === "number") return candidate;
+  }
+  return undefined;
+}
+
+/** The error's `name`, from the thrown object or the parsed body behind it. */
+function errorNames(err: unknown): string[] {
+  if (typeof err !== "object" || err === null) return [];
+  const e = err as Record<string, unknown>;
+  const cause = e.cause as Record<string, unknown> | undefined;
+  const body = (cause?.body ?? e.body) as Record<string, unknown> | undefined;
+  return [e.name, body?.name, (e.data as Record<string, unknown>)?.name].filter(
+    (name): name is string => typeof name === "string",
+  );
+}
+
+/**
+ * True only when the server definitely says the session does not exist:
+ * an HTTP 404, or the server's `NotFoundError`. Everything else — a
+ * refused connection while the server is still starting, a 5xx, a
+ * timeout, a body that would not parse — is not proof the session is
+ * gone, and must not cost the chat its session.
+ */
+export function isRemoteSessionNotFound(err: unknown): boolean {
+  if (errorStatus(err) === 404) return true;
+  return errorNames(err).includes("NotFoundError");
+}
+
+/** Waits between `session.get` attempts on a transient failure. */
+const RESUME_RETRY_DELAYS_MS: readonly number[] = [500, 1_500];
+
 /**
  * Ensure a session exists for this chat on the remote agent server.
  *
  * Resumes the stored session id if `session.get` confirms it's still
- * alive. If the stored id is stale (any failure from `session.get`),
- * resets local state and creates a fresh session, returning the new
- * id. The fresh session is created with Talon's standard permission
- * ruleset (see {@link buildPermissionRuleset}).
+ * alive. Only a definite not-found (see {@link isRemoteSessionNotFound})
+ * resets the chat — archiving the old id — and creates a fresh session
+ * with Talon's standard permission ruleset (see
+ * {@link buildPermissionRuleset}). Any other failure is retried a couple
+ * of times and then fails the turn with the session left in place: a
+ * server that is still starting after an update must not wipe every
+ * chat's session mapping.
  */
 export async function ensureRemoteSession<TClient extends RemoteAgentClient>(
   client: TClient,
   state: RemoteServerState<TClient>,
   chatId: string,
+  retryDelaysMs: readonly number[] = RESUME_RETRY_DELAYS_MS,
 ): Promise<string> {
   const session = getSession(chatId);
 
   if (session.sessionId) {
-    try {
-      await client.session.get({ sessionID: session.sessionId });
-      return session.sessionId;
-    } catch {
-      logWarn(
-        "agent",
-        `[${chatId}] Session ${session.sessionId} expired, creating new`,
-      );
-      resetSession(chatId);
+    const sessionId = session.sessionId;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        await client.session.get({ sessionID: sessionId });
+        return sessionId;
+      } catch (err) {
+        if (isRemoteSessionNotFound(err)) {
+          logWarn(
+            "agent",
+            `[${chatId}] ${state.label} session ${sessionId} not found on the server, creating new`,
+          );
+          resetSession(chatId, "remote_session_not_found");
+          break;
+        }
+        const delay = retryDelaysMs[attempt];
+        const detail = err instanceof Error ? err.message : String(err);
+        if (delay === undefined) {
+          throw new TalonError(
+            `Could not check ${state.label} session ${sessionId} (${detail}); ` +
+              `kept it — try again once the server is up`,
+            { reason: "network", retryable: true, cause: err },
+          );
+        }
+        logWarn(
+          "agent",
+          `[${chatId}] ${state.label} session check failed (${detail}); ` +
+            `retrying in ${delay}ms, session kept`,
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
     }
   }
 

package/src/backend/runtime/turn/handle-retry.ts

@@ -111,7 +111,8 @@ export interface ApplyRetryDecisionResult {
  *
  * Side effects (when a retry fires):
  *   - `incrementCounter('errors.<reason>')` exactly once per call.
- *   - `resetSession(chatId)` before recursion.
+ *   - `resetSession(chatId, reason)` before recursion (the old id is
+ *     archived under that reason).
  *   - For `fallback_model`: the fallback model id is spread into the
  *     recursion's params (`params.model` outranks chat settings).
  *
@@ -156,7 +157,7 @@ export async function applyRetryDecision(
       "agent",
       `[${chatId}] ${prefix}${decision.reason}, resetting ${resetNoun} and retrying`,
     );
-    resetSession(chatId);
+    resetSession(chatId, decision.reason);
     return { retry: await recurseWithRetried(params), classified };
   }
 
@@ -165,7 +166,7 @@ export async function applyRetryDecision(
       "agent",
       `[${chatId}] ${classified.reason}, falling back to ${decision.fallbackModelId}`,
     );
-    resetSession(chatId);
+    resetSession(chatId, `fallback_model:${decision.fallbackModelId}`);
     return {
       retry: await recurseWithRetried({
         ...params,
@@ -270,7 +271,7 @@ export async function* applyRetryDecisionStream(
       "agent",
       `[${chatId}] ${prefix}${decision.reason}, resetting ${resetNoun} and retrying`,
     );
-    resetSession(chatId);
+    resetSession(chatId, decision.reason);
     yield* buildRetryStream();
     return { retried: true, classified };
   }
@@ -280,7 +281,7 @@ export async function* applyRetryDecisionStream(
       "agent",
       `[${chatId}] ${classified.reason}, falling back to ${decision.fallbackModelId}`,
     );
-    resetSession(chatId);
+    resetSession(chatId, `fallback_model:${decision.fallbackModelId}`);
     yield* buildRetryStream(decision.fallbackModelId);
     return { retried: true, classified };
   }

package/src/cli/commands/backup.ts

@@ -46,6 +46,10 @@ import {
 import { resolveBackupSettings } from "../../core/backup/plan.js";
 import { buildSnapshot } from "../../core/backup/snapshot.js";
 import { pruneLocal, reconcileIndex } from "../../core/backup/store.js";
+import {
+  describeRetention,
+  localRetention,
+} from "../../core/backup/retention/policy.js";
 import { generatePassphraseFile } from "../../core/backup/passphrase.js";
 import { dirs } from "../../util/paths.js";
 import { fetchGateway } from "../daemon-api.js";
@@ -170,7 +174,7 @@ async function backupNow(flags: Flags): Promise<void> {
     pinned: pin,
     settings,
   });
-  await pruneLocal(settings.keepLocal);
+  await pruneLocal(localRetention(settings));
   console.log(
     `  ${pc.green("●")} ${manifest.id} — ${manifest.parts.length} part(s), ` +
       `${formatBytes(manifest.sizeBytes)}\n`,
@@ -246,10 +250,10 @@ async function backupPin(id: string, pinned: boolean): Promise<void> {
 
 async function backupPrune(): Promise<void> {
   const settings = resolveBackupSettings(loadConfig().backup);
-  const removed = await pruneLocal(settings.keepLocal);
+  const removed = await pruneLocal(localRetention(settings));
   console.log(
     removed.length === 0
-      ? `  ${pc.dim(`Nothing to prune (keepLocal=${settings.keepLocal}).`)}\n`
+      ? `  ${pc.dim(`Nothing to prune (${describeRetention(localRetention(settings))}).`)}\n`
       : `  ${pc.green("●")} Pruned ${removed.length}: ${removed.join(", ")}\n`,
   );
 }

package/src/cli/commands/history.ts

@@ -0,0 +1,152 @@
+/**
+ * `talon history` — the operator's view of chat history the daemon keeps.
+ *
+ * Talon never deletes chat history on its own: /reset is a soft reset
+ * (a context marker), backend switches leave history alone, and deleting a
+ * chat in the app only hides it. `purge` is the one way to delete rows for
+ * real — host access only (it is not reachable from any chat), and it asks
+ * for the chat id to be typed back before touching anything.
+ */
+
+import { createInterface } from "node:readline/promises";
+import pc from "picocolors";
+import {
+  getChatHistoryState,
+  getHistoryStats,
+  listHiddenChats,
+  purgeChatHistory,
+} from "../../storage/history.js";
+import { clearTurnMeta } from "../../storage/turn-meta.js";
+
+const USAGE = [
+  `  Usage: ${pc.cyan("talon history <command>")}`,
+  "",
+  "  Commands:",
+  `    ${pc.cyan("show <chatId>")}           Row count, date range, reset/hidden state`,
+  `    ${pc.cyan("hidden")}                  Chats deleted in a client (rows kept)`,
+  `    ${pc.cyan("purge <chatId> [--yes]")}  PERMANENTLY delete a chat's history`,
+  "",
+  "  Resets, backend switches and chat deletion never delete history;",
+  `  ${pc.cyan("purge")} is the only command that does. Take a checkpoint first:`,
+  `  ${pc.cyan('talon backup now --checkpoint "before purge"')}`,
+  "",
+].join("\n");
+
+/** Reads one line from stdin; injectable so tests can answer the prompt. */
+export type HistoryCliIo = {
+  ask: (question: string) => Promise<string>;
+  print: (line: string) => void;
+};
+
+const defaultIo: HistoryCliIo = {
+  ask: async (question) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    try {
+      return await rl.question(question);
+    } finally {
+      rl.close();
+    }
+  },
+  print: (line) => console.log(line),
+};
+
+function date(ms: number | undefined): string {
+  return ms ? new Date(ms).toISOString() : "—";
+}
+
+function cmdShow(chatId: string, io: HistoryCliIo): void {
+  const stats = getHistoryStats(chatId);
+  const state = getChatHistoryState(chatId);
+  io.print(`  ${pc.bold(chatId)}`);
+  io.print(
+    `    ${stats.totalMessages} message(s), ${stats.uniqueUsers} sender(s), ` +
+      `${date(stats.oldestTimestamp || undefined)} → ${date(stats.newestTimestamp || undefined)}`,
+  );
+  if (state?.clearedAt !== undefined) {
+    io.print(`    context reset at ${date(state.clearedAt)} (rows kept)`);
+  }
+  if (state?.hiddenAt !== undefined) {
+    io.print(`    deleted in a client at ${date(state.hiddenAt)} (rows kept)`);
+  }
+  io.print("");
+}
+
+function cmdHidden(io: HistoryCliIo): void {
+  const chats = listHiddenChats();
+  if (chats.length === 0) {
+    io.print(`  ${pc.dim("No hidden chats.")}\n`);
+    return;
+  }
+  for (const chat of chats) {
+    io.print(
+      `  ${pc.bold(chat.chatId)}  ${chat.total} message(s)  ${pc.dim(`hidden ${date(chat.hiddenAt)}`)}`,
+    );
+  }
+  io.print("");
+}
+
+/**
+ * Delete a chat's history for good. Without `--yes` the operator must type
+ * the chat id back; anything else aborts. Returns rows deleted (0 when
+ * aborted or empty).
+ */
+async function cmdPurge(
+  chatId: string,
+  yes: boolean,
+  io: HistoryCliIo,
+): Promise<number> {
+  const { totalMessages } = getHistoryStats(chatId);
+  if (totalMessages === 0 && getChatHistoryState(chatId) === undefined) {
+    io.print(`  ${pc.dim(`No history stored for ${chatId}.`)}\n`);
+    return 0;
+  }
+  if (!yes) {
+    io.print(
+      `\n  This PERMANENTLY deletes ${pc.bold(String(totalMessages))} message(s) of chat ${pc.bold(chatId)}.\n` +
+        `  It cannot be undone except from a backup. Take a checkpoint first:\n` +
+        `    ${pc.cyan('talon backup now --checkpoint "before purge"')}\n`,
+    );
+    const answer = (await io.ask(`  Type the chat id to confirm: `)).trim();
+    if (answer !== chatId) {
+      io.print(`  ${pc.yellow("●")} Aborted — nothing deleted.\n`);
+      return 0;
+    }
+  }
+  const deleted = purgeChatHistory(chatId);
+  clearTurnMeta(chatId);
+  io.print(`  ${pc.green("●")} Purged ${deleted} message(s) from ${chatId}.\n`);
+  return deleted;
+}
+
+/** Route a `talon history <command>` invocation. */
+export async function runHistoryCommand(
+  args: readonly string[],
+  io: HistoryCliIo = defaultIo,
+): Promise<void> {
+  const positional = args.filter((a) => !a.startsWith("--"));
+  const yes = args.includes("--yes");
+  const chatId = positional[1];
+  try {
+    switch (positional[0]) {
+      case "show":
+        if (!chatId) io.print(`  ${pc.red("✖")} show needs a chat id\n`);
+        else cmdShow(chatId, io);
+        break;
+      case "hidden":
+        cmdHidden(io);
+        break;
+      case "purge":
+        if (!chatId) io.print(`  ${pc.red("✖")} purge needs a chat id\n`);
+        else await cmdPurge(chatId, yes, io);
+        break;
+      default:
+        io.print(USAGE);
+    }
+  } catch (err) {
+    io.print(`  ${pc.red("✖")} ${err instanceof Error ? err.message : err}`);
+    process.exitCode = 1;
+  }
+}

package/src/cli/index.ts

@@ -37,6 +37,7 @@ import { showEvents } from "./events.js";
 import { runPluginCommand } from "./plugin.js";
 import { runSkillCommand } from "./skill.js";
 import { runMemoryCommand } from "./memory.js";
+import { runHistoryCommand } from "./commands/history.js";
 import { mainMenu } from "./menu.js";
 import { runBackupCommand } from "./commands/backup.js";
 import { runMeshCommand } from "./commands/mesh.js";
@@ -62,6 +63,7 @@ const CLI_COMMANDS = [
   "plugin",
   "skill",
   "memory",
+  "history",
   "backup",
   "mesh",
 ];
@@ -109,6 +111,9 @@ function printHelp(): void {
   console.log(
     `    ${pc.cyan("memory")}     Read/edit the memory store (list/search/import/render)`,
   );
+  console.log(
+    `    ${pc.cyan("history")}    Chat history kept by Talon (show/hidden/purge)`,
+  );
   console.log(
     `    ${pc.cyan("backup")}     Snapshots and checkpoints (now/list/show/pin/restore)`,
   );
@@ -180,6 +185,7 @@ const COMMANDS: Record<string, CommandHandler> = {
   plugin: (args) => runPluginCommand(args),
   skill: (args) => runSkillCommand(args),
   memory: (args) => runMemoryCommand(args),
+  history: (args) => runHistoryCommand(args),
   "--version": () => console.log(pkg.version),
   "-v": () => console.log(pkg.version),
   "--help": () => printHelp(),

package/src/core/backup/archive/verify.ts

@@ -0,0 +1,53 @@
+/**
+ * Read-back verification of a freshly written snapshot.
+ *
+ * A digest taken off the bytes on their way to disk says what was sent,
+ * not what landed. Before a snapshot is allowed to count as good, every
+ * part is read back from disk and re-hashed, and an encrypted part is
+ * decrypted end to end (and discarded) so a broken encryptor cannot
+ * produce a snapshot nobody can open. The result is `verifiedAt` in the
+ * manifest, and retention never prunes the newest snapshot that has one
+ * (see retention/policy.ts).
+ *
+ * Runs before the manifest is signed, so `verifiedAt` is covered by the
+ * MAC like every other field written at build time.
+ */
+
+import { join } from "node:path";
+import { TalonError } from "../../errors.js";
+import { isEncryptedFile, verifyDecryptable } from "./crypt.js";
+import { sha256File } from "./digest.js";
+import type { SnapshotPart } from "../types.js";
+
+/**
+ * Throws a TalonError naming the first part that does not read back.
+ * Returns the time verification finished.
+ */
+export async function verifyWrittenParts(
+  dir: string,
+  parts: readonly SnapshotPart[],
+  passphrase: string | null,
+  now: () => number = Date.now,
+): Promise<number> {
+  for (const part of parts) {
+    const path = join(dir, part.name);
+    const actual = await sha256File(path);
+    if (actual !== part.sha256) {
+      throw new TalonError(
+        `Part ${part.name} does not read back (sha256 mismatch)`,
+        { reason: "unknown" },
+      );
+    }
+    if (passphrase && (await isEncryptedFile(path))) {
+      try {
+        await verifyDecryptable(path, passphrase);
+      } catch (err) {
+        throw new TalonError(
+          `Part ${part.name} cannot be decrypted after writing: ${err instanceof Error ? err.message : String(err)}`,
+          { reason: "unknown", cause: err },
+        );
+      }
+    }
+  }
+  return now();
+}

package/src/core/backup/plan.ts

@@ -51,6 +51,9 @@ export const DEFAULT_BACKUP_SETTINGS = {
   intervalHours: 6,
   keepLocal: 12,
   keepRemote: 30,
+  keepDaily: 7,
+  keepWeekly: 4,
+  keepCheckpoints: 10,
   includePalace: true,
   loginSessions: "local",
   includeSessions: true,

package/src/core/backup/retention/policy.ts

@@ -0,0 +1,195 @@
+/**
+ * Snapshot retention — which snapshots a prune pass may delete.
+ *
+ * Keeping only the newest N is not a safety net: if something silently
+ * wipes memory, the next N scheduled snapshots faithfully back up the
+ * damage and every good copy ages out within N × intervalHours (three
+ * days at the defaults). So retention is tiered, the way restic and
+ * borg do it:
+ *
+ *   - `keepLast`    the newest N scheduled snapshots (`keepLocal` /
+ *                   `keepRemote` in config — their old meaning).
+ *   - `keepDaily`   the newest snapshot of each of the last D days that
+ *                   have one.
+ *   - `keepWeekly`  the newest snapshot of each of the last W ISO weeks
+ *                   that have one.
+ *
+ * Days and weeks are counted over snapshots that exist, not over the
+ * calendar, so a machine that was off for a month does not lose its
+ * history to the clock.
+ *
+ * Around the tiers sit three guard rails:
+ *
+ *   - Pinned snapshots are kept and count against nothing.
+ *   - Checkpoints (manual, pre-update, pre-upgrade, pre-restore) have
+ *     their own cap, `keepCheckpoints`, and never displace a scheduled
+ *     snapshot — nor are they displaced by one.
+ *   - The newest snapshot that passed verification is always kept, so a
+ *     run of corrupt snapshots can never prune the last known-good one.
+ *
+ * Entries whose `createdAt` is not a real timestamp (an unreadable or
+ * partial remote manifest) are never pruned: without an age there is no
+ * honest way to rank them, and deleting what you cannot read is how a
+ * retention pass becomes data loss. They are reported as `skipped` so
+ * the caller can warn.
+ *
+ * Pure: no clock, no filesystem.
+ */
+
+/** The tiers one prune pass applies. */
+export type RetentionPolicy = {
+  /** Newest N scheduled snapshots. */
+  keepLast: number;
+  /** Newest snapshot per day, for the last N days that have one. 0 = off. */
+  keepDaily: number;
+  /** Newest snapshot per ISO week, for the last N weeks that have one. 0 = off. */
+  keepWeekly: number;
+  /** Newest N unpinned checkpoints, counted apart from scheduled snapshots. */
+  keepCheckpoints: number;
+};
+
+/** What retention needs to know about one snapshot. */
+export type RetentionEntry = {
+  id: string;
+  createdAt: number;
+  pinned: boolean;
+  /** "backup" | "checkpoint"; anything else is treated as "backup". */
+  kind?: string;
+  /** Epoch ms of a successful post-write verification, if there was one. */
+  verifiedAt?: number;
+};
+
+/** Why a snapshot survived, for logs and tests. */
+type KeepReason =
+  "pinned" | "last" | "daily" | "weekly" | "checkpoint" | "verified";
+
+export type RetentionPlan<T> = {
+  /** Snapshots to delete, newest first. */
+  prune: T[];
+  /** id → every reason it was kept. */
+  keep: Map<string, KeepReason[]>;
+  /** Entries without a usable createdAt — kept, and worth a warning. */
+  skipped: T[];
+};
+
+/** Settings shape the policy is derived from (a subset of BackupSettings). */
+type RetentionSettings = {
+  keepLocal: number;
+  keepRemote: number;
+  keepDaily: number;
+  keepWeekly: number;
+  keepCheckpoints: number;
+};
+
+export function localRetention(settings: RetentionSettings): RetentionPolicy {
+  return {
+    keepLast: settings.keepLocal,
+    keepDaily: settings.keepDaily,
+    keepWeekly: settings.keepWeekly,
+    keepCheckpoints: settings.keepCheckpoints,
+  };
+}
+
+export function remoteRetention(settings: RetentionSettings): RetentionPolicy {
+  return { ...localRetention(settings), keepLast: settings.keepRemote };
+}
+
+/** One-line description for logs: `last=12 daily=7 weekly=8 checkpoints=10`. */
+export function describeRetention(policy: RetentionPolicy): string {
+  return (
+    `last=${policy.keepLast} daily=${policy.keepDaily} ` +
+    `weekly=${policy.keepWeekly} checkpoints=${policy.keepCheckpoints}`
+  );
+}
+
+/** A createdAt a snapshot can be ranked by. */
+function hasUsableTimestamp(entry: { createdAt: unknown }): boolean {
+  return (
+    typeof entry.createdAt === "number" &&
+    Number.isFinite(entry.createdAt) &&
+    entry.createdAt > 0
+  );
+}
+
+/** `2026-09-30` in UTC. */
+function dayKey(at: number): string {
+  return new Date(at).toISOString().slice(0, 10);
+}
+
+/** ISO-8601 week, UTC: `2026-W40`. */
+function weekKey(at: number): string {
+  const date = new Date(at);
+  const day = date.getUTCDay() || 7; // Mon=1 … Sun=7
+  // The Thursday of this week decides which year the week belongs to.
+  const thursday = Date.UTC(
+    date.getUTCFullYear(),
+    date.getUTCMonth(),
+    date.getUTCDate() + 4 - day,
+  );
+  const year = new Date(thursday).getUTCFullYear();
+  const week = Math.ceil(
+    ((thursday - Date.UTC(year, 0, 1)) / 86_400_000 + 1) / 7,
+  );
+  return `${year}-W${String(week).padStart(2, "0")}`;
+}
+
+/** Keep the newest entry of each of the first `limit` distinct buckets. */
+function keepPerBucket<T extends RetentionEntry>(
+  ordered: readonly T[],
+  limit: number,
+  bucketOf: (at: number) => string,
+  reason: KeepReason,
+  mark: (entry: T, reason: KeepReason) => void,
+): void {
+  if (limit <= 0) return;
+  const seen = new Set<string>();
+  for (const entry of ordered) {
+    const bucket = bucketOf(entry.createdAt);
+    if (seen.has(bucket)) continue;
+    seen.add(bucket);
+    mark(entry, reason);
+    if (seen.size >= limit) return;
+  }
+}
+
+/** Decide what survives. See the module comment for the rules. */
+export function planRetention<T extends RetentionEntry>(
+  snapshots: readonly T[],
+  policy: RetentionPolicy,
+): RetentionPlan<T> {
+  const keep = new Map<string, KeepReason[]>();
+  const mark = (entry: T, reason: KeepReason): void => {
+    const reasons = keep.get(entry.id);
+    if (reasons) reasons.push(reason);
+    else keep.set(entry.id, [reason]);
+  };
+
+  const skipped = snapshots.filter((entry) => !hasUsableTimestamp(entry));
+  const ranked = snapshots
+    .filter(hasUsableTimestamp)
+    .sort((a, b) => b.createdAt - a.createdAt);
+
+  for (const entry of ranked) if (entry.pinned) mark(entry, "pinned");
+
+  const unpinned = ranked.filter((entry) => !entry.pinned);
+  const checkpoints = unpinned.filter((entry) => entry.kind === "checkpoint");
+  const scheduled = unpinned.filter((entry) => entry.kind !== "checkpoint");
+
+  for (const entry of checkpoints.slice(0, Math.max(0, policy.keepCheckpoints)))
+    mark(entry, "checkpoint");
+  for (const entry of scheduled.slice(0, Math.max(0, policy.keepLast)))
+    mark(entry, "last");
+  keepPerBucket(scheduled, policy.keepDaily, dayKey, "daily", mark);
+  keepPerBucket(scheduled, policy.keepWeekly, weekKey, "weekly", mark);
+
+  const lastVerified = ranked.find(
+    (entry) => typeof entry.verifiedAt === "number" && entry.verifiedAt > 0,
+  );
+  if (lastVerified) mark(lastVerified, "verified");
+
+  return {
+    prune: ranked.filter((entry) => !keep.has(entry.id)),
+    keep,
+    skipped,
+  };
+}