talon-agent 5.26.3 → 5.26.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.26.3",
+  "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/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,
+  };
+}

package/src/core/backup/scheduler.ts

@@ -34,6 +34,11 @@ import { dirs } from "../../util/paths.js";
 import { passphraseProblem } from "./passphrase.js";
 import { buildSnapshot } from "./snapshot.js";
 import { listLocalManifests, pruneLocal, reconcileIndex } from "./store.js";
+import {
+  describeRetention,
+  localRetention,
+  remoteRetention,
+} from "./retention/policy.js";
 import { discoverTargets, selectTargets } from "./targets.js";
 import { pruneRemote, uploadSnapshot } from "./upload.js";
 import type { BackupSettings, Manifest, SnapshotKind } from "./types.js";
@@ -162,7 +167,7 @@ async function executeRun(request: RunRequest): Promise<Manifest> {
       parts: manifest.parts.length,
       durationMs: Date.now() - started,
     });
-    await _backupDeps.pruneLocal(settings.keepLocal, state.home);
+    await _backupDeps.pruneLocal(localRetention(settings), state.home);
     if (!request.localOnly) {
       const targets = selectTargets(
         await _backupDeps.discover(),
@@ -170,7 +175,7 @@ async function executeRun(request: RunRequest): Promise<Manifest> {
       );
       if (targets.length > 0) {
         await _backupDeps.upload(manifest, targets, state.home);
-        await _backupDeps.pruneRemote(targets, settings.keepRemote);
+        await _backupDeps.pruneRemote(targets, remoteRetention(settings));
       }
     }
     backoff.succeed();
@@ -379,8 +384,9 @@ export async function initBackup(options: {
   log(
     "backup",
     `Scheduled every ${options.settings.intervalHours}h; first run in ` +
-      `${Math.round(delay / 60_000)}m (keep ${options.settings.keepLocal} local, ` +
-      `${options.settings.keepRemote} remote)`,
+      `${Math.round(delay / 60_000)}m (retention ` +
+      `${describeRetention(localRetention(options.settings))}; ` +
+      `${options.settings.keepRemote} newest per remote target)`,
   );
 }
 

package/src/core/backup/snapshot.ts

@@ -54,6 +54,7 @@ import {
 import { signManifest } from "./archive/manifest-auth.js";
 import { TarWriter } from "./archive/tar.js";
 import { createCompressor } from "./archive/zstd.js";
+import { verifyWrittenParts } from "./archive/verify.js";
 import {
   collectTree,
   excludeForRoot,
@@ -755,6 +756,7 @@ export async function buildSnapshot(options: BuildOptions): Promise<Manifest> {
       }
     }
     await removeScratch(dir);
+    const verifiedAt = await verifyWrittenParts(dir, parts, passphrase);
 
     const gitHead = await readGitHead(process.cwd());
     const manifest: Manifest = {
@@ -776,6 +778,7 @@ export async function buildSnapshot(options: BuildOptions): Promise<Manifest> {
       ...(palaceHash ? { palaceHash } : {}),
       sizeBytes: parts.reduce((sum, part) => sum + part.bytes, 0),
       remote: {},
+      verifiedAt,
     };
     if (passphrase) manifest.auth = await signManifest(manifest, passphrase);
     await writeManifest(manifest, home);

package/src/core/backup/status.ts

@@ -53,6 +53,10 @@ export type BackupStatus = {
 type BackupPolicy = {
   keepLocal: number;
   keepRemote: number;
+  /** Absent on a policy built before tiered retention (older daemons). */
+  keepDaily?: number;
+  keepWeekly?: number;
+  keepCheckpoints?: number;
   /**
    * Snapshots are written encrypted: `backup.encryption` is configured or
    * the passphrase comes from the environment (see passphrase.ts). Off
@@ -69,6 +73,9 @@ function describePolicy(
   return {
     keepLocal: settings.keepLocal,
     keepRemote: settings.keepRemote,
+    keepDaily: settings.keepDaily,
+    keepWeekly: settings.keepWeekly,
+    keepCheckpoints: settings.keepCheckpoints,
     encrypted:
       settings.encryption !== undefined || Boolean(env[PASSPHRASE_ENV]?.trim()),
   };

package/src/core/backup/store.ts

@@ -33,6 +33,11 @@ import {
   updateBackupManifest,
 } from "../../storage/backup/index.js";
 import { pathExists } from "./sources/sessions.js";
+import {
+  describeRetention,
+  planRetention,
+  type RetentionPolicy,
+} from "./retention/policy.js";
 import type {
   Manifest,
   RemoteState,
@@ -236,26 +241,6 @@ export async function setSnapshotPinned(
 
 // ── Retention ───────────────────────────────────────────────────────────────
 
-/**
- * Which snapshots to drop so that at most `keep` unpinned ones remain.
- * Pure, and the order is the one the caller sees: newest first, pinned
- * snapshots kept unconditionally and not counted against the budget —
- * pinning is the user saying "this one outlives the policy".
- */
-export function selectPrunable<
-  T extends { id: string; createdAt: number; pinned: boolean },
->(snapshots: readonly T[], keep: number): T[] {
-  const ordered = [...snapshots].sort((a, b) => b.createdAt - a.createdAt);
-  const doomed: T[] = [];
-  let kept = 0;
-  for (const snapshot of ordered) {
-    if (snapshot.pinned) continue;
-    kept += 1;
-    if (kept > keep) doomed.push(snapshot);
-  }
-  return doomed;
-}
-
 /** Delete a snapshot directory and its index rows. */
 async function removeSnapshot(
   id: string,
@@ -266,14 +251,24 @@ async function removeSnapshot(
   deleteBackup(id);
 }
 
-/** Apply the local retention policy. Returns the ids removed. */
+/**
+ * Apply the local retention policy (see retention/policy.ts). Returns the ids
+ * removed. A directory whose manifest cannot be read never reaches the
+ * listing, so it is never pruned.
+ */
 export async function pruneLocal(
-  keep: number,
+  policy: RetentionPolicy,
   home: string = dirs.root,
 ): Promise<string[]> {
-  const doomed = selectPrunable(await listLocalManifests(home), keep);
+  const plan = planRetention(await listLocalManifests(home), policy);
+  for (const manifest of plan.skipped) {
+    logWarn(
+      "backup",
+      `Not pruning ${manifest.id}: its manifest has no usable createdAt`,
+    );
+  }
   const removed: string[] = [];
-  for (const manifest of doomed) {
+  for (const manifest of plan.prune) {
     try {
       await removeSnapshot(manifest.id, home);
       removed.push(manifest.id);
@@ -284,7 +279,7 @@ export async function pruneLocal(
   if (removed.length > 0) {
     log(
       "backup",
-      `Pruned ${removed.length} local snapshot(s) (keepLocal=${keep})`,
+      `Pruned ${removed.length} local snapshot(s) (${describeRetention(policy)})`,
     );
   }
   return removed;

package/src/core/backup/types.ts

@@ -123,6 +123,14 @@ export type Manifest = {
   /** Total bytes of all parts. */
   sizeBytes: number;
   remote: Record<string, RemoteState>;
+  /**
+   * Epoch ms at which every part was read back and matched its digest
+   * (and, when encrypted, decrypted end to end) — see archive/verify.ts. Set
+   * before signing, so the MAC covers it. Absent on snapshots written
+   * before verification existed. Retention never prunes the newest
+   * verified snapshot.
+   */
+  verifiedAt?: number;
   /** MAC under the backup passphrase; absent on plaintext/legacy snapshots. */
   auth?: ManifestAuth;
 };
@@ -146,6 +154,12 @@ export type BackupSettings = {
   intervalHours: number;
   keepLocal: number;
   keepRemote: number;
+  /** Newest snapshot per day, for this many days (0 = off). */
+  keepDaily: number;
+  /** Newest snapshot per ISO week, for this many weeks (0 = off). */
+  keepWeekly: number;
+  /** Unpinned checkpoints kept, apart from the scheduled snapshots. */
+  keepCheckpoints: number;
   includePalace: boolean;
   /** WhatsApp auth + userbot session: see {@link LoginSessionsPolicy}. */
   loginSessions: LoginSessionsPolicy;

package/src/core/backup/upload.ts

@@ -30,11 +30,11 @@ import {
 } from "../../storage/backup/index.js";
 import { isEncryptedFile } from "./archive/crypt.js";
 import {
-  partPath,
-  reindexSnapshot,
-  selectPrunable,
-  writeManifest,
-} from "./store.js";
+  describeRetention,
+  planRetention,
+  type RetentionPolicy,
+} from "./retention/policy.js";
+import { partPath, reindexSnapshot, writeManifest } from "./store.js";
 import type { BackupTarget } from "./targets.js";
 import type { Manifest, RemoteState, SnapshotPart } from "./types.js";
 
@@ -182,14 +182,19 @@ async function uploadToAll(
 }
 
 /**
- * Apply the remote retention policy on each target. Same rule as local:
- * the newest `keep` unpinned snapshots survive, pinned ones always do.
- * A target that cannot list is skipped — deleting on a partial listing is
- * how a retention pass turns into data loss.
+ * Apply the remote retention policy on each target — the same tiers as
+ * local (see retention/policy.ts), with `keepRemote` as the newest-N tier.
+ *
+ * Two refusals keep a retention pass from turning into data loss:
+ *   - A target that cannot list is skipped: deleting on a partial
+ *     listing is how that happens.
+ *   - An entry whose manifest is missing, unreadable, or has no
+ *     createdAt is never pruned. Without an age it cannot be ranked,
+ *     and treating it as the oldest would delete it first.
  */
 export async function pruneRemote(
   targets: readonly BackupTarget[],
-  keep: number,
+  policy: RetentionPolicy,
 ): Promise<void> {
   for (const target of targets) {
     if (!target.ready) continue;
@@ -203,15 +208,27 @@ export async function pruneRemote(
       );
       continue;
     }
-    const doomed = selectPrunable(
-      snapshots.map((entry) => ({
-        id: entry.snapshotId,
-        createdAt: entry.manifest?.createdAt ?? 0,
-        pinned: entry.manifest?.pinned === true,
-      })),
-      keep,
+    const plan = planRetention(
+      snapshots.map((entry) => {
+        const manifest = entry.manifest as Partial<Manifest> | undefined;
+        return {
+          id: entry.snapshotId,
+          createdAt: manifest?.createdAt as number,
+          pinned: manifest?.pinned === true,
+          kind: manifest?.kind,
+          verifiedAt: manifest?.verifiedAt,
+        };
+      }),
+      policy,
     );
-    for (const victim of doomed) {
+    if (plan.skipped.length > 0) {
+      logWarn(
+        "backup",
+        `Not pruning ${plan.skipped.length} snapshot(s) on ${target.id} whose manifest ` +
+          `is unreadable or has no createdAt: ${plan.skipped.map((s) => s.id).join(", ")}`,
+      );
+    }
+    for (const victim of plan.prune) {
       try {
         await target.remove(victim.id);
         deleteBackupRemote(victim.id, target.id);
@@ -222,10 +239,10 @@ export async function pruneRemote(
         );
       }
     }
-    if (doomed.length > 0) {
+    if (plan.prune.length > 0) {
       log(
         "backup",
-        `Pruned ${doomed.length} snapshot(s) from ${target.id} (keepRemote=${keep})`,
+        `Pruned ${plan.prune.length} snapshot(s) from ${target.id} (${describeRetention(policy)})`,
       );
     }
   }

package/src/core/config/index.ts

@@ -679,7 +679,8 @@ const configSchema = z.object({
    * Backups & checkpoints (docs/backups.md). Talon's only safety net, so
    * it is on by default: every `intervalHours` it writes a snapshot of
    * the identity, state, database and memory under ~/.talon/backups/,
-   * keeps `keepLocal` of them, and uploads to whatever remote targets
+   * keeps them on a tiered schedule (newest `keepLocal`, one a day for
+   * `keepDaily` days, one a week for `keepWeekly` weeks), and uploads to whatever remote targets
    * are registered (`targets: []` keeps everything local).
    *
    *   - `workspaceInclude` — the workspace is mostly bulk that can be
@@ -716,6 +717,30 @@ const configSchema = z.object({
         .min(1)
         .max(1000)
         .default(DEFAULT_BACKUP_SETTINGS.keepRemote),
+      /**
+       * Tiered retention on top of the newest `keepLocal`/`keepRemote`
+       * (docs/backups.md#retention): the newest snapshot of each of the
+       * last `keepDaily` days and `keepWeekly` weeks, plus up to
+       * `keepCheckpoints` unpinned checkpoints counted on their own.
+       */
+      keepDaily: z
+        .number()
+        .int()
+        .min(0)
+        .max(1000)
+        .default(DEFAULT_BACKUP_SETTINGS.keepDaily),
+      keepWeekly: z
+        .number()
+        .int()
+        .min(0)
+        .max(1000)
+        .default(DEFAULT_BACKUP_SETTINGS.keepWeekly),
+      keepCheckpoints: z
+        .number()
+        .int()
+        .min(1)
+        .max(1000)
+        .default(DEFAULT_BACKUP_SETTINGS.keepCheckpoints),
       includePalace: z.boolean().default(DEFAULT_BACKUP_SETTINGS.includePalace),
       /**
        * WhatsApp auth + the userbot's Telegram login. "local" (default)

package/src/core/errors.ts

@@ -139,6 +139,17 @@ function errorCodes(err: unknown, depth = 0): string[] {
 
 // ── Classify any error ──────────────────────────────────────────────────────
 
+/**
+ * A backend session that expired or no longer exists. Claude's CLI answers
+ * a resume of a session whose transcript is missing with "No conversation
+ * found with session ID: …" — a definite not-found; without the match
+ * every later turn in the chat fails the same way. The reset that follows
+ * archives the old id (resetSession), so a transcript that turns up again
+ * can be re-attached.
+ */
+const SESSION_EXPIRED_RE =
+  /session.*expired|expired.*session|invalid.*resume|no conversation found/i;
+
 /**
  * Wrap or classify any thrown value into a TalonError.
  * Call this at module boundaries (backend catch, bridge catch) to convert
@@ -259,8 +270,8 @@ export function classify(err: unknown): TalonError {
     });
   }
 
-  // Session expired
-  if (/session.*expired|expired.*session|invalid.*resume/i.test(msg)) {
+  // Session expired (or gone — see SESSION_EXPIRED_RE)
+  if (SESSION_EXPIRED_RE.test(msg)) {
     return new TalonError(msg, {
       reason: "session_expired",
       retryable: false,

package/src/frontend/presentation/backup-panel.ts

@@ -180,7 +180,13 @@ function storageLines(f: ReportFormatter, status: BackupStatus): string[] {
   if (policy) {
     lines.push(
       `${f.bold("Retention:")} newest ${policy.keepLocal} kept here, ` +
-        `${policy.keepRemote} per target · pinned ones are never pruned`,
+        `${policy.keepRemote} per target` +
+        (policy.keepDaily ? ` · 1/day for ${policy.keepDaily}d` : "") +
+        (policy.keepWeekly ? ` · 1/week for ${policy.keepWeekly}w` : "") +
+        (policy.keepCheckpoints
+          ? ` · ${policy.keepCheckpoints} checkpoints`
+          : "") +
+        ` · pinned ones and the last verified are never pruned`,
     );
     lines.push(
       policy.encrypted